# Argos

Argos is built into Acahti: registered case sources, shared plans, execution
history, case outcomes, artifacts and reports. Every signed-in member reads it.
**Argos** appears in the header after Knowledge; its sidebar groups
**Results** (**Overview**, **Cases**, **Runs**), **Library** (**Sources**,
**Plans**) and **Runner** (**Run command**, **Connect a runner**).

## Find what needs attention

The **Overview** opens on one **Needs attention** list: failing cases grouped
by pack and group, each row opening the filtered cases page or the case itself,
with the latest failing run and its ticket. A case opens beside the list with
its results and its [Track](track.md) flow (`/argos/cases?case=<id>`). It also flags failures in a run
that is still in progress and tickets that can be closed because their case
passes again. When nothing fails, the list says so. The tiles above it (cases,
failing cases, pass rate and running) open the matching filtered list. The
cases page keeps its case, pack, group, failing and environment filters in the
URL, and the runs page keeps environment and status, so a filtered view can be
shared as a link.

## Register source-visible cases

Open **Argos → Sources → Register source**. Supply the case ID,
title, pack, owner, repository, source revision, file path and complete code.
The case can be registered before its first execution. A SHA-256 checksum
identifies its exact source content; earlier source snapshots remain readable.

Agents can synchronize cases with `argos_test_save`. To update an existing case,
read it first and supply its `expected_sha256`. Updates require the current
owner, original creator or an org admin. Source is displayed as code and
is never executed by registration.

A historical execution without registered source is not sufficient to identify
its exact implementation. Register its source at the matching repository
revision before treating it as reproducible evidence.

## Share a plan

Open **Argos → Plans** and set a plan ID, title, owner, environment, optional
product iteration ID and the case IDs. Cases must be registered first. Plans
are stored on the server and visible to every member. After creation only the
owner, creator or an org admin changes a plan, passing its current revision so
concurrent edits never overwrite each other silently.

## Run cases

The Argos CLI streams a run to Acahti as the person or agent running it. Set
`ACAHTI_ROOT_URL` to the instance and `ACAHTI_TOKEN` to a personal Access Token
from **Access tokens**, then run:

```bash
argos run <case-id> --env <environment> --dash
```

`--dash ./acahti.env` reads the same two keys from a file instead. The run
shows its runner as that login, and only the runner or an org admin writes to
it. Acahti pipelines inject both variables for the head commit author's account
(falling back to the account that started the run),
so a pipeline needs no Argos secret. The CLI prints `argos <sid>`; a pipeline job
named like `e2e` or `argos` links that line to the run as **Argos**. A run with
no events for 24 hours, or 6 hours past a soak's planned duration, is
interrupted.

Follow the run at `/argos/runs/<sid>` and inspect steps, errors and run
files, which are shown as plain text. A run page starts with its track: the cases it ran, the run and its status, the
tickets opened from its failures, and **Re-run**, which loads the failed cases
(or every case) into **Run command**. Link the run to its product
iteration, or to a todo so it appears in that item's [Track](track.md) flow. A
saved plan does not launch a runner by itself; execution must produce real
Argos evidence.

## Agent operations

| Goal | MCP tools |
|---|---|
| Discover and inspect cases | `argos_test_list`, `argos_test_get`, `argos_test_source` |
| Register exact source | `argos_test_save` |
| Manage shared plans | `argos_plan_list`, `argos_plan_save` |
| Inspect results | `argos_run_list`, `argos_run_get`, `argos_case_history`, `argos_catalog`, `argos_overview` |
| Collaborate on a run | `argos_run_comment`, `argos_run_interrupt` |
| Search source | `argos_search` |

Tools are exposed through Acahti's `/mcp` using the caller's identity, and
each has the same REST operation under `/acahti/v1/argos`. `argos_run_list`
returns a brief summary and case results without steps; `argos_run_get` reads
one run in full; `argos_case_history` pages one case's results across runs.