feat(webui): add the per-run task detail page
A per-task page at #/tasks/{id} with tabs for the attempt's stages and log, changed
files, configuration and a raw debug view. Reachable from the task list, deep
linkable via ?tab= and ?attempt=, and reload safe. Existing URLs (#/tasks?task=N
and #/tasks?status=...) are unchanged.
- A stage rail per attempt: name, duration, terminal status and error text, with
unattributed events surfaced and the agent's own verdict shown separately.
- No pass/fail badge and no exit code anywhere: the backend has neither, and a stage
that returned nil after producing a poor diff is a success. Status word, duration
and error text are shown instead.
- The log pane filters by attempt, stage and level, states the coverage caveat for
stage filters (agent and tool output records no stage), and keeps the three read
outcomes distinct: no log reader in this deployment, no file for this attempt, and
no entries matching the filter.
- Retry is labelled as a new run and its confirm says the previous attempt's commits
are discarded, because it hard-resets the branch onto the base.
- An absent capture reads "not captured for this run" rather than implying nothing
changed, and no elapsed-run figure is shown since only per-stage durations exist.
- The events cache is invalidated on retry (it previously kept the ended attempt's
events) and the log cache is keyed by attempt, so two attempts cannot be conflated.
- ui/dist is rebuilt and committed: the gate runs the node tests but never rebuilds
the bundle, so a stale one would otherwise ship behind a green gate.
- docs/prds/task-run-detail.md records the surface and its limits, and
docs/architecture/observability.md describes it alongside the read endpoints.
Both new vocabularies are pinned by tests on each side (config schema, change
statuses) so a one-sided rename fails a test instead of silently degrading the page.
This commit is contained in:
1 parent
862ac46e8b
commit
7414713d61
33 files changed
+4195
-91
No files matched your search
@@ -0,0 +1,291 @@
|
||||
# Per-run task detail: attempts, stages, changes, config, debug
|
||||
|
||||
**Status:** Settled design, landing with this change set (workflow run
|
||||
`76f8e877`). The persistence foundation is already in the tree
|
||||
(`events.attempt`, the two new event kinds, the two proto fields); the read
|
||||
endpoints and the page land with it. The surface contract itself is
|
||||
`docs/architecture/observability.md`.
|
||||
**Date:** 2026-09-18
|
||||
**Compounds with:** `docs/prds/task-logs-pagination.md` (a bounded read says
|
||||
what it does not show), `docs/prds/status-health-surface.md` (no surface that
|
||||
answers something already answered elsewhere).
|
||||
|
||||
## Decision
|
||||
|
||||
A task gets one detail page that answers "what did this run actually do?" per
|
||||
**attempt**: an ordered stage rail, the change each commit/push produced, the
|
||||
effective configuration the attempt ran under, the attempt's log, and the raw
|
||||
record behind all of it.
|
||||
|
||||
The single organising idea is **attempt attribution**. Today the dashboard
|
||||
renders a task's whole event stream as one flat timeline, so a retried task
|
||||
reads as one long run with two of everything. Every new panel is scoped to one
|
||||
attempt and says which one.
|
||||
|
||||
The second organising idea is **provenance, not re-derivation**. What a run
|
||||
produced is captured at the producer, while the evidence exists, and persisted
|
||||
durably. Nothing in this surface tries to reconstruct a past run from state
|
||||
that has since moved on.
|
||||
|
||||
## The requirement set
|
||||
|
||||
| # | Requirement | Mechanism |
|
||||
| --- | --- | --- |
|
||||
| R1 | Per-attempt stage rail: stages with name, start, duration, terminal status and error, ordered within one attempt | `GET /api/tasks/{id}/attempts` reads the task's events and groups them by `attempt` |
|
||||
| R2 | Events carry an attempt, migrated safely and carried on the wire | `events.attempt` column + presence-gated migrator arm; `Event.attempt = 11` |
|
||||
| R3 | Changed files captured at commit/push, persisted per task, exposed, shown with repo/PR links | `changes_captured` durable event written by the commit/push steps; `GET /api/tasks/{id}/changes` |
|
||||
| R4 | The effective configuration an attempt ran under, secrets redacted, shown | `config_captured` durable event written once per attempt; read from the events response the page already holds |
|
||||
| R5 | Log pane filters by attempt, stage and level; absence stays distinct from an unreadable deployment | `logging.Query.Stage` + `ReadTaskLogRequest.stage = 9`; the pane keeps `disabled` and `found=false` apart |
|
||||
| R6 | Retry is reachable from the run view and produces a new attempt shown as a new run | Existing retry action, labelled as a NEW run whose confirm states the previous attempt's commits are discarded |
|
||||
| R7 | Raw JSON of the task record and its events for the selected attempt | `GET /api/tasks/{id}/debug` |
|
||||
| R8 | Deep-linkable, reload-safe per-task detail page that keeps existing URLs working | `#/tasks/{id}` route beside the existing `#/tasks?task=N` and `#/tasks?status=...` |
|
||||
| R9 | Design polish: hierarchy, tokens, both themes, responsive rail, a11y, loading/empty/error states | UI lane; measured at 480px and 700px in both themes |
|
||||
| R10 | Documentation of record | This document plus `docs/architecture/observability.md` |
|
||||
| R11 | Red-first tests for every new behaviour, full gate, `task ui`, forced `go build ./...`, `go test -race` on touched packages | Per lane; the anti-cost-cutting requirement lives here |
|
||||
|
||||
## Attempt attribution: a column, not a guess
|
||||
|
||||
`events.Event.Attempt`, persisted by `internal/store` as the `events.attempt`
|
||||
column (`internal/store/events.go`, `eventsSchema`), is a real column,
|
||||
`NOT NULL DEFAULT 0`. It was chosen over segmenting the stream on `task_queued` /
|
||||
`task_retried` because a fold would have to guess which side of a boundary an
|
||||
event belongs to when the daemon restarts mid-attempt, when `RecoverStale`
|
||||
requeues, or when two attempts interleave across a crash. A guess rendered as
|
||||
structure is exactly the false fidelity this surface exists to avoid; a column
|
||||
is durable, queryable and ordered by construction.
|
||||
|
||||
**`0` means "not attributable".** It is every row written before this change
|
||||
plus the deliberately task-agnostic producers. It is not an attempt number and
|
||||
is never rendered as one. The attempts endpoint reports the count of
|
||||
unattributed events so the page can say so instead of presenting old history as
|
||||
attempt 1.
|
||||
|
||||
## Migration against an existing `archie.db`
|
||||
|
||||
The store's migrator (`migrateTasks` in `internal/store/store.go`) already reads
|
||||
`PRAGMA table_info` through `tableColumns` and applies a presence-gated
|
||||
`ALTER TABLE ... ADD COLUMN` list. This change adds an `events` arm: a
|
||||
`tableColumns(ctx, tx, "events")` read beside the other two, and the entry
|
||||
`ALTER TABLE events ADD COLUMN attempt INTEGER NOT NULL DEFAULT 0`.
|
||||
|
||||
Three consequences a future maintainer must not get wrong:
|
||||
|
||||
- `eventsSchema` is `CREATE TABLE IF NOT EXISTS` (`internal/store/events.go`),
|
||||
so on an existing database it is a **no-op**. The migrator arm is the only
|
||||
thing that adds the column there. This is why the red test builds a raw
|
||||
SQLite file with the pre-change `events` DDL and must fail before the arm
|
||||
exists: every temp-database test passes either way.
|
||||
- **`user_version` stays 3.** The loop is presence-gated, not version-gated;
|
||||
bumping it would force an edit to the test that exists to prove a newer
|
||||
schema is refused.
|
||||
- **No backfill, ever.** Existing rows keep `attempt = 0`. Inferring an attempt
|
||||
number for them would be fabrication.
|
||||
|
||||
## Changed files: captured at the producer
|
||||
|
||||
The measurement is taken inside the shared step library immediately after a
|
||||
successful commit and after a successful push (`StageCommit` and
|
||||
`StageCommitPush` in `internal/domain/workflow/steps.go`) — the one place
|
||||
where the worktree, the branch, the base, the task and the store are all in
|
||||
scope, and the only place that knows a push actually happened.
|
||||
|
||||
Both alternatives were rejected on evidence, not taste:
|
||||
|
||||
- **Reading the diff on demand** is impossible. The worktree is deleted on
|
||||
merge, close and no-PR terminal states (`internal/worktree.(*Manager).Cleanup`,
|
||||
called from the daemon's terminal paths) and a retry resets the branch onto
|
||||
its base (`internal/worktree.(*Manager).refresh` → `resetOnto`). There is
|
||||
nothing left to read.
|
||||
- **Reading it from the forge** is impossible today. The forge contract exposes
|
||||
no changed-file capability, and adding one would cost three implementations
|
||||
plus an RPC and would still fail for chat-sourced tasks with no PR.
|
||||
|
||||
Binding consequences:
|
||||
|
||||
- Capture **degrades, never parks**. A `Trees` implementation without the
|
||||
capture seam captures nothing, logs, and lets the run continue. A reporting
|
||||
failure must never fail a task.
|
||||
- The value types live in `internal/domain/workflow/task` (`changes.go`), not in
|
||||
package `workflow` and not in `internal/worktree`. Package `workflow` has no
|
||||
import of `internal/worktree`, and this subpackage is not projected into the
|
||||
interpreted-stage symbol table, so declaring the types here widens nothing and
|
||||
needs no symbol-table regeneration. The capture method stays off that surface
|
||||
entirely.
|
||||
- `files` is capped at 200 entries because an event's `data` is not
|
||||
length-limited by the store. `totals` always covers the **full** set and
|
||||
`truncated: true` says when entries were dropped.
|
||||
- `binary` means "no textual hunks", not "a binary file". Rename pairing is
|
||||
go-git behaviour the lane pins with a test; where the repository records a
|
||||
rename as add + delete, the surface reports what was recorded.
|
||||
|
||||
## Per-run configuration: a durable event, not a table
|
||||
|
||||
**Decision.** The effective configuration an attempt ran under is persisted as a
|
||||
`config_captured` durable event (`internal/events.KindConfigCaptured`), on the
|
||||
same attempt key R2 adds — not in a table, and not behind new RPCs.
|
||||
|
||||
**Why.** Three reasons, in order of weight:
|
||||
|
||||
1. Events are already this system's durable per-attempt provenance stream, and
|
||||
they demonstrably carry aggregation (`StageStats`, `TokensByDay` both
|
||||
aggregate over persisted events). R3 puts its diffstat there in this same
|
||||
change. A table plus two RPCs would have given one feature **two provenance
|
||||
mechanisms for one purpose**.
|
||||
2. It adds no RPC, so the ratified state-store surface is untouched and nothing
|
||||
in `docs/prds/state-store-contract.md` (rev 2c) changes.
|
||||
3. The page already fetches the task's events to build the rail (R1) and to read
|
||||
the diffstat (R3), so the document arrives in a fetch it already makes. There
|
||||
is nothing to join.
|
||||
|
||||
The single-row `config_snapshot` table is deliberately **left alone**. It
|
||||
answers "what is the running configuration now", is replaced on every publish,
|
||||
and is pinned to one row by a test. It could not answer "what did attempt 2 run
|
||||
under" in any case.
|
||||
|
||||
**Payload.** The result of `config.Config.ForTask()` — the non-secret
|
||||
task-runtime subset — plus the schema constant `archie/task-config@1`. Not the
|
||||
dashboard's configuration view: that is a larger projection carrying the full
|
||||
schema catalog, and it is the wrong object for this. Stored shape and the tab's
|
||||
read rule are in `docs/architecture/observability.md`.
|
||||
|
||||
**Binding conditions.** It is emitted through the durable path, never the
|
||||
lossy bus; it is written once per attempt, not once per stage; redaction is
|
||||
proven **positively** by a canary-secrets test rather than assumed from the
|
||||
producer's contract; the timeline gains one human line for it rather than
|
||||
dumping a JSON blob; and an attempt with no such event renders "not captured for
|
||||
this run", never an empty table implying defaults applied.
|
||||
|
||||
**Documented residual — the honest trust claim.** A task-scoped grant may insert
|
||||
events on its own task ID; that is how `tool_call` and `agent_finish` already
|
||||
work, so a task can in principle write its own `config_captured` event. This
|
||||
**widens no capability** — the grant could already insert arbitrary events on
|
||||
itself — but it does mean this provenance is exactly as trustworthy as the rest
|
||||
of that task's event stream, and no more. It is not tamper-proofing and must
|
||||
never be described as such.
|
||||
|
||||
## No new RPC and no new table
|
||||
|
||||
The entire wire change is two fields on existing messages:
|
||||
|
||||
```proto
|
||||
// proto/state/v1/state.proto
|
||||
message Event { int64 attempt = 11; }
|
||||
message ReadTaskLogRequest { string stage = 9; }
|
||||
```
|
||||
|
||||
No RPC was added, no store table was added, and no new configuration field was
|
||||
introduced. `docs/prds/state-store-contract.md` is unchanged because no ratified
|
||||
contract changed; the JSON document rides an existing `data` column over an
|
||||
existing RPC.
|
||||
|
||||
Both fields are tolerant in both directions, and the degrade is stated rather
|
||||
than hidden: an old server makes `attempt` read as `0` and `stage` match
|
||||
nothing, so the page must say the deployment cannot attribute events to attempts
|
||||
rather than show one run labelled "attempt 1". An old client shows
|
||||
`config_captured` as an unknown kind, and the Config tab must then say "this
|
||||
deployment cannot read per-run configuration" — a different claim from "not
|
||||
captured for this attempt".
|
||||
|
||||
## Retry is a new run
|
||||
|
||||
The retry action is reachable from the run view and produces a new attempt that
|
||||
appears as a new run. It is a **fresh** run: it resets the branch onto
|
||||
`origin/<base>` (`internal/worktree.(*Manager).refresh` → `resetOnto`) and
|
||||
**discards the previous attempt's commits**. Labelling it "restart" would imply
|
||||
resumption that does not happen, so the control and its confirm copy say so.
|
||||
|
||||
## Honest limits the surface carries
|
||||
|
||||
These are the claims that would otherwise be overstated. Each is a copy or
|
||||
rendering rule, not a caveat in a comment:
|
||||
|
||||
- **There is no exit code, so no stage shows pass/fail.** `stage_finish` carries
|
||||
a duration and an optional error string and nothing else. A stage `ok` means
|
||||
"returned without error", not "the work was correct". The agent's own verdict
|
||||
is shown separately from the rail. A stage that parks after finishing cleanly
|
||||
leaves that stage `ok` on a failed task, so attempt status is read together
|
||||
with task status.
|
||||
- **The log stage filter only matches lines the workflow bound a stage to.**
|
||||
Agent and tool output carries no stage and never matches. The pane states that
|
||||
coverage limit next to the control rather than presenting a filtered view as
|
||||
the whole story.
|
||||
- **Absence and unreadability are different answers.** A deployment that cannot
|
||||
read task logs says so; an attempt whose log does not exist says that. They
|
||||
are never collapsed, in either direction, for logs or for configuration.
|
||||
- **An empty changed-files view never means "nothing changed".** No capture
|
||||
exists for runs predating this change and the forge cannot supply one, so the
|
||||
empty state reads "not captured for this run".
|
||||
- **No run-duration figure is shown.** Per-stage durations only: a run can spend
|
||||
days in `waiting_human`, and one number would understate wall time.
|
||||
- **No duration is invented** for a stage with no `stage_start`; it reads "not
|
||||
recorded".
|
||||
- **Unattributed history is never presented as an attempt.** Events with
|
||||
`attempt = 0` are reported as a count, not guessed into a run.
|
||||
- **The configuration shown is the attempt's non-secret task-runtime subset** —
|
||||
bot identity, models, limits, budgets, dispatch, diff cap, notifications,
|
||||
forge host, tool policy. It is not the full dashboard configuration and must
|
||||
never imply it contains providers, repositories, identities or credentials.
|
||||
|
||||
## Route and compatibility
|
||||
|
||||
`#/tasks/{id}` is the detail route; it is deep-linkable and reload-safe.
|
||||
`#/tasks?task=N` and `#/tasks?status=...` keep working and keep their existing
|
||||
behaviour, including the nav highlight. The debug view is why the raw view
|
||||
exists at all: the task list response is capped, so a client-side join has no
|
||||
row for an older task, and a debug view that silently hid events would be worse
|
||||
than useless.
|
||||
|
||||
## What this deliberately does not do
|
||||
|
||||
- **No new RPC, table, store interface or configuration field.** Nothing here
|
||||
needed one, and each would have widened a ratified surface.
|
||||
- **No exit status, no pass/fail gate badge, no "steps" in the CI sense.** The
|
||||
reference layout is a CI pipeline; archie's stages are agent runs and the page
|
||||
must not borrow CI's claims.
|
||||
- **No backfill** of attempts, change captures or configurations onto runs that
|
||||
predate the change.
|
||||
- **No client-side join for configuration.** It arrives in the events response
|
||||
the page already fetches; there is nothing to join.
|
||||
- **No change to `docs/prds/state-store-contract.md`.** No ratified contract
|
||||
moved.
|
||||
|
||||
## Files this change touches
|
||||
|
||||
- `internal/store/`: the `events.attempt` column, its migrator arm, and the
|
||||
schema-presence test.
|
||||
- `internal/events/`: `Event.Attempt`, `KindChangesCaptured`,
|
||||
`KindConfigCaptured`, `ConfigCapturedSchema`.
|
||||
- `internal/domain/workflow/task/changes.go`: the change value types.
|
||||
- `internal/worktree/` + `internal/app/agentworker/`: the capture primitive and
|
||||
its production forwarding.
|
||||
- `internal/domain/workflow/steps.go`: the capture at commit and push.
|
||||
- `internal/daemon/`: the per-attempt configuration emit at dispatch.
|
||||
- `internal/logging/`: `Query.Stage`.
|
||||
- `internal/webui/`: the three read endpoints and the `stage` log parameter.
|
||||
- `proto/state/v1/state.proto` + generated stubs: the two field additions.
|
||||
- `ui/src/`: the detail page, the tab primitive, the rail, and the panel copy.
|
||||
- `docs/`: this document and `docs/architecture/observability.md`.
|
||||
|
||||
## Acceptance
|
||||
|
||||
1. Two attempts of one task render as two runs, and attempt 1's rail excludes
|
||||
attempt 2's stages.
|
||||
2. A task with no stages renders "no stages recorded", never an unexplained
|
||||
empty rail.
|
||||
3. A pre-change `archie.db` gains the `attempt` column with `user_version`
|
||||
still 3, and its old events are reported as unattributed.
|
||||
4. An attempt with a capture shows per-file added/deleted counts, status, repo
|
||||
and PR links; an attempt without one says so and never says "no changes".
|
||||
5. The Config tab shows the attempt's document for the selected attempt only,
|
||||
with no secret value present in the serialized document.
|
||||
6. Retry from the run view produces a new attempt shown as a new run, with copy
|
||||
stating the previous attempt's commits are discarded.
|
||||
7. The log stage filter narrows to stage-bound lines and the pane states the
|
||||
coverage limit; `disabled` and `found=false` remain distinguishable.
|
||||
8. `#/tasks/{id}` survives reload, and `#/tasks?task=N` / `#/tasks?status=...`
|
||||
are unchanged.
|
||||
9. The debug view returns the task record and its unfiltered events, each
|
||||
carrying `attempt`.
|
||||
10. Run the gate and the dashboard build: `task check` passes clean, `task ui`
|
||||
has been run so `ui/dist` matches the sources, and every touched package
|
||||
builds and passes under `-race`.
|
||||
Reference in new issue
Block a user