feat(webui): split the task run page into a master-detail pane

The five tabs gave the stage rail less than a third of the screen and
disconnected the log stream from the stage that produced it. The stage
rail is now the page's master pane, always visible; the four context
panels are the inspector and own the tab bar. Selecting a stage commands
the inspector to the log tab with that stage's filter set; clicking the
selected stage clears it. Selection is a command, not a binding -- the
operator can change the filter afterwards.

No endpoint, RPC or contract changed. tab=stages still resolves, to the
log tab; every inspector tab and attempt deep-link survives a reload.
Below the shell's 900px frame breakpoint the rail stacks above the
inspector. Design of record: docs/prds/task-run-master-detail.md (Draft,
per-run panel contracts unchanged from task-run-detail.md).
This commit is contained in:
sam committed 2026-09-23 11:20:45 +10:00
1 parent 5aeffa3028
commit 39ad75ac22
7 files changed
+178 -56

No files matched your search

+10
View File
@@ -414,6 +414,12 @@
"section": "PRDs",
"body": "# Per-run task detail: attempts, stages, changes, config, debug\n\n**Status:** Approved\n**Authority:** the surface contract itself is\n`docs/architecture/observability.md`.\n**Date:** 2026-09-18\n**Compounds with:** `docs/prds/task-logs-pagination.md` (a bounded read says\nwhat it does not show), `docs/prds/status-health-surface.md` (no surface that\nanswers something already answered elsewhere).\n\n## Decision\n\nA task gets one detail page that answers \"what did this run actually do?\" per\n**attempt**: an ordered stage rail, the change each commit/push produced, the\neffective configuration the attempt ran under, the attempt's log, and the raw\nrecord behind all of it.\n\nThe single organising idea is **attempt attribution**. The dashboard\nrenders a task's whole event stream as one flat timeline, so a retried task\nreads as one long run with two of everything. Every new panel is scoped to one\nattempt and says which one.\n\nThe second organising idea is **provenance, not re-derivation**. What a run\nproduced is captured at the producer, while the evidence exists, and persisted\ndurably. Nothing in this surface tries to reconstruct a past run from state\nthat has since moved on.\n\n## The requirement set\n\n| # | Requirement | Mechanism |\n| --- | --- | --- |\n| 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` |\n| R2 | Events carry an attempt, migrated safely and carried on the wire | `events.attempt` column + presence-gated migrator arm; `Event.attempt = 11` |\n| 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` |\n| 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 |\n| 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 |\n| 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 |\n| R7 | Raw JSON of the task record and its events for the selected attempt | `GET /api/tasks/{id}/debug` |\n| 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=...` |\n| R9 | Design polish: hierarchy, tokens, both themes, responsive rail, a11y, loading/empty/error states | UI lane; measured at 480px and 700px in both themes |\n| R10 | Documentation of record | This document plus `docs/architecture/observability.md` |\n| 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 |\n\n## Attempt attribution: a column, not a guess\n\n`events.Event.Attempt`, persisted by `internal/store` as the `events.attempt`\ncolumn (`internal/store/events.go`, `eventsSchema`), is a real column,\n`NOT NULL DEFAULT 0`. It was chosen over segmenting the stream on `task_queued` /\n`task_retried` because a fold would have to guess which side of a boundary an\nevent belongs to when the daemon restarts mid-attempt, when `RecoverStale`\nrequeues, or when two attempts interleave across a crash. A guess rendered as\nstructure is exactly the false fidelity this surface exists to avoid; a column\nis durable, queryable and ordered by construction.\n\n**`0` means \"not attributable\".** It is every row written before this change\nplus the deliberately task-agnostic producers. It is not an attempt number and\nis never rendered as one. The attempts endpoint reports the count of\nunattributed events so the page can say so instead of presenting old history as\nattempt 1.\n\n## Migration against an existing `archie.db`\n\nThe store's migrator (`migrateTasks` in `internal/store/store.go`) already reads\n`PRAGMA table_info` through `tableColumns` and applies a presence-gated\n`ALTER TABLE ... ADD COLUMN` list. This change adds an `events` arm: a\n`tableColumns(ctx, tx, \"events\")` read beside the other two, and the entry\n`ALTER TABLE events ADD COLUMN attempt INTEGER NOT NULL DEFAULT 0`.\n\nThree consequences a future maintainer must not get wrong:\n\n- `eventsSchema` is `CREATE TABLE IF NOT EXISTS` (`internal/store/events.go`),\n so on an existing database it is a **no-op**. The migrator arm is the only\n thing that adds the column there. This is why the red test builds a raw\n SQLite file with the pre-change `events` DDL and must fail before the arm\n exists: eveLine truncated
},
{
"url": "/dev/prds/task-run-master-detail/",
"title": "Task run detail as a master-detail split pane",
"section": "PRDs",
"body": "# Task run detail as a master-detail split pane\n\n**Status:** Draft\n**Authority:** the panel contracts stay as ratified in\n`docs/prds/task-run-detail.md`; this document changes only the run page's\narrangement of them.\n**Compounds with:** `docs/prds/task-run-detail.md` (attempt attribution, the\nlog stage filter, the per-panel honesty rules).\n\n## Decision\n\nThe run page's five tabs become two panes. The stage rail is the **master**,\nalways visible on the left. The four context panels — log, changed files,\nconfiguration, debug — are the **inspector** on the right, and their tab bar\nmoves into the inspector. The \"Stages\" tab stops existing: the rail is not a\nview of the page, it is the page's spine.\n\nSelecting a stage in the rail is a command, not a binding: it switches the\ninspector to the log tab and sets the log pane's stage filter to that stage.\nChanging the filter afterwards is the operator's choice and is not overridden.\nClearing the selection returns the filter to \"all stages\". Changed files,\nconfiguration and debug stay attempt-scoped; a stage selection never pretends\nto scope them.\n\n## What does not change\n\n- No new endpoint, RPC, table or configuration field. Every read is one the\n page already makes.\n- The URL contract: `tab` and `attempt` ride in the query string and every\n view survives a reload. `tab=stages` stays a valid URL and renders the\n inspector with the log tab; the page never generates it again.\n- Attempt attribution, the log stage filter's coverage limit, and every\n honesty rule in `task-run-detail.md`. Each pane states what it cannot show\n under the same rendering rules that document defines.\n- The attempt selector and the task header stay pinned above both panes.\n\n## Arrangement\n\n- Left pane: fixed-width rail (~320px) with the attempt's stage rows. Status,\n duration, error and per-stage events render in the rail; the rail scrolls\n independently.\n- Right pane: the inspector's tab bar plus the selected panel, filling the\n remaining width.\n- Below 900px (the shell's existing frame breakpoint) the rail stacks above\n the inspector; neither pane is hidden.\n- Keyboard: the rail keeps its list semantics; the inspector keeps the\n WAI-ARIA tabs pattern the tab bar already provides.\n\n## Acceptance\n\n1. The rail is visible without opening any tab, and no \"Stages\" trigger exists.\n2. Clicking a stage opens the log filtered to that stage; clearing the\n selection shows all stages.\n3. `tab=stages` loads and renders the log tab.\n4. Every inspector tab and attempt deep-link survives a reload.\n5. Below 900px the rail stacks above the inspector.\n6. `task check` passes clean and `ui/dist` matches the sources."
},
{
"url": "/dev/prds/ui-service-boundary/",
"title": "UI Service boundary and configuration ownership",
@@ -715,6 +721,10 @@
"title": "Per-run task detail: attempts, stages, changes, config, debug",
"url": "/dev/prds/task-run-detail/"
},
{
"title": "Task run detail as a master-detail split pane",
"url": "/dev/prds/task-run-master-detail/"
},
{
"title": "UI Service boundary and configuration ownership",
"url": "/dev/prds/ui-service-boundary/"
+57
View File
@@ -0,0 +1,57 @@
# Task run detail as a master-detail split pane
**Status:** Draft
**Authority:** the panel contracts stay as ratified in
`docs/prds/task-run-detail.md`; this document changes only the run page's
arrangement of them.
**Compounds with:** `docs/prds/task-run-detail.md` (attempt attribution, the
log stage filter, the per-panel honesty rules).
## Decision
The run page's five tabs become two panes. The stage rail is the **master**,
always visible on the left. The four context panels — log, changed files,
configuration, debug — are the **inspector** on the right, and their tab bar
moves into the inspector. The "Stages" tab stops existing: the rail is not a
view of the page, it is the page's spine.
Selecting a stage in the rail is a command, not a binding: it switches the
inspector to the log tab and sets the log pane's stage filter to that stage.
Changing the filter afterwards is the operator's choice and is not overridden.
Clearing the selection returns the filter to "all stages". Changed files,
configuration and debug stay attempt-scoped; a stage selection never pretends
to scope them.
## What does not change
- No new endpoint, RPC, table or configuration field. Every read is one the
page already makes.
- The URL contract: `tab` and `attempt` ride in the query string and every
view survives a reload. `tab=stages` stays a valid URL and renders the
inspector with the log tab; the page never generates it again.
- Attempt attribution, the log stage filter's coverage limit, and every
honesty rule in `task-run-detail.md`. Each pane states what it cannot show
under the same rendering rules that document defines.
- The attempt selector and the task header stay pinned above both panes.
## Arrangement
- Left pane: fixed-width rail (~320px) with the attempt's stage rows. Status,
duration, error and per-stage events render in the rail; the rail scrolls
independently.
- Right pane: the inspector's tab bar plus the selected panel, filling the
remaining width.
- Below 900px (the shell's existing frame breakpoint) the rail stacks above
the inspector; neither pane is hidden.
- Keyboard: the rail keeps its list semantics; the inspector keeps the
WAI-ARIA tabs pattern the tab bar already provides.
## Acceptance
1. The rail is visible without opening any tab, and no "Stages" trigger exists.
2. Clicking a stage opens the log filtered to that stage; clearing the
selection shows all stages.
3. `tab=stages` loads and renders the log tab.
4. Every inspector tab and attempt deep-link survives a reload.
5. Below 900px the rail stacks above the inspector.
6. `task check` passes clean and `ui/dist` matches the sources.
+21 -1
View File
@@ -9,7 +9,7 @@ import PanelLoading from "./PanelLoading.vue";
import StageRow from "./StageRow.vue";
import { stageStatusMeta } from "./stage-rail";
import { useTaskRun } from "./use-task-run";
import type { AttemptsState } from "./task-run";
import type { AttemptsState, Stage } from "./task-run";
/**
* The per-attempt stage rail.
@@ -35,6 +35,24 @@ const attempt = computed(() => attempts.value.find((a) => Number(a.attempt) ===
const meta = computed(() => stageStatusMeta(attempt.value?.status));
const stages = computed(() => attempt.value?.stages || []);
/**
* Master-detail selection (docs/prds/task-run-master-detail.md): clicking a
* stage commands the inspector to the log tab with this stage's filter set.
* Clicking the selected stage clears the filter back to all stages. The
* selection is a command, not a binding: the operator can change the filter
* afterwards and the rail does not fight them. A stage with no name has
* nothing to filter on and is not selectable.
*/
function selectedStage(stage: Stage): boolean {
return run.tab === "log" && Boolean(stage.name) && run.filters.stage === stage.name;
}
function selectStage(stage: Stage): void {
if (!stage.name) return;
run.setFilters({ stage: selectedStage(stage) ? "" : stage.name, level: run.filters.level });
run.setTab("log");
}
/** An attempt's start is rendered as an absolute instant, never as "started 2
* days ago": on a still-running attempt a relative stamp reads as two days of
* work, which is exactly the elapsed-time claim the design forbids. */
@@ -81,6 +99,8 @@ const startedAt = computed(() => {
:stage="stage"
:attempt-number="attempt.attempt"
:events="run.events"
:selected="selectedStage(stage)"
@select="selectStage(stage)"
/>
</ol>
<Empty v-else>
+18 -4
View File
@@ -19,8 +19,11 @@ const props = defineProps<{
stage: Stage;
attemptNumber: number;
events: TaskEvent[] | null | undefined;
selected?: boolean;
}>();
const emit = defineEmits<{ select: [] }>();
const meta = computed(() => stageStatusMeta(props.stage.status));
const ran = computed(() => duration(props.stage.duration_ms));
const reports = computed(() => agentReports(props.events, props.attemptNumber, props.stage.name));
@@ -47,17 +50,28 @@ const nodeClass = computed(() =>
<template>
<li
class="relative grid grid-cols-[1.75rem_1fr] gap-2 pb-4 before:absolute before:top-4 before:bottom-0 before:left-[0.6875rem] before:w-px before:bg-border-strong last:before:hidden max-[700px]:grid-cols-1 max-[700px]:border-b max-[700px]:border-border max-[700px]:pb-3 max-[700px]:before:hidden"
:class="props.selected ? 'rounded-md bg-primary-soft' : ''"
>
<span :class="nodeClass" aria-hidden="true" class="max-[700px]:hidden" />
<div class="min-w-0">
<div class="flex flex-wrap items-center gap-2">
<div class="min-w-0" :class="props.selected ? '-my-2 rounded-md py-2' : ''">
<!--
Selecting a stage commands the inspector to this stage's log (the
master-detail contract). The control is a real button so keyboard
activation works without the row carrying a second role.
-->
<button
type="button"
class="flex w-full flex-wrap items-center gap-2 rounded text-left"
:aria-pressed="props.selected ?? false"
@click="emit('select')"
>
<!-- A stage name is one unbroken token often enough that it has to be
allowed to break, or a long one pushes the status and duration off
the row. -->
<span class="min-w-0 font-mono font-medium break-words">{{ stage.name || "(unnamed stage)" }}</span>
<span class="min-w-0 font-mono font-medium break-words hover:underline" :class="props.selected ? 'text-primary' : ''">{{ stage.name || "(unnamed stage)" }}</span>
<Badge :variant="meta.kind">{{ meta.label }}</Badge>
<span class="text-xs text-fg-muted">{{ ran ? `ran for ${ran}` : "duration not recorded" }}</span>
</div>
</button>
<div
v-if="stage.error"
class="mt-2 rounded-sm border-l-[3px] border-danger bg-danger-soft px-3 py-2 text-sm break-words whitespace-pre-wrap text-fg-muted"
+28 -11
View File
@@ -12,6 +12,7 @@ import TaskHeader from "./TaskHeader.vue";
import TaskMetaBar from "./TaskMetaBar.vue";
import TaskNotes from "./TaskNotes.vue";
import TaskRunPanels from "./TaskRunPanels.vue";
import StageRail from "./StageRail.vue";
import { parseTaskId } from "./task-run";
import { provideTaskRun } from "./use-task-run";
@@ -24,11 +25,16 @@ import { provideTaskRun } from "./use-task-run";
* the query string, so every view of this page is a deep link that survives a
* reload -- /tasks/42?tab=changes&attempt=2.
*
* The page is a master-detail split pane (docs/prds/task-run-master-detail.md):
* the stage rail is the master and is always visible, the four context panels
* are the inspector and own the tab bar. Below the shell's 900px frame
* breakpoint the rail stacks above the inspector.
*
* This file composes the page and nothing else: the reads and the caches are
* use-task-run, the head, meta bar, notes, restart control, attempt selector,
* tab bar and panel area are each their own component. The router keys this
* component on the path (App.vue), so a different :id gets a fresh instance
* rather than diffing the last task's state in place.
* rail, tab bar and panel area are each their own component. The router keys
* this component on the path (App.vue), so a different :id gets a fresh
* instance rather than diffing the last task's state in place.
*/
const route = useRoute();
@@ -48,13 +54,24 @@ const run = provideTaskRun(taskId);
</TaskMetaBar>
<TaskNotes :id="rawId" />
<Card>
<CardContent>
<Tabs class="gap-4" :model-value="run.tab" @update:model-value="run.setTab">
<TabBar />
<TaskRunPanels :id="rawId" />
</Tabs>
</CardContent>
</Card>
<div class="grid items-start gap-4 min-[900px]:grid-cols-[20rem_minmax(0,1fr)]">
<!--
The master pane: the attempt's stage rail, always on screen. It owns
its own loading, failure and empty states, so the inspector never has
to speak for it.
-->
<aside aria-label="Run stages">
<StageRail :state="run.attempts" />
</aside>
<Card>
<CardContent>
<Tabs class="gap-4" :model-value="run.tab" @update:model-value="run.setTab">
<TabBar />
<TaskRunPanels :id="rawId" />
</Tabs>
</CardContent>
</Card>
</div>
</div>
</template>
+33 -39
View File
@@ -7,19 +7,18 @@ import ChangedFiles from "./ChangedFiles.vue";
import DebugView from "./DebugView.vue";
import PanelError from "./PanelError.vue";
import PanelLoading from "./PanelLoading.vue";
import StageRail from "./StageRail.vue";
import TaskLogs from "./TaskLogs.vue";
import { RUN_TABS } from "./task-run";
import { useTaskRun } from "./use-task-run";
/**
* The run page's panel area: one panel per tab, each reading the attempt the
* page has selected.
* The run page's inspector panels: one panel per tab, each reading the attempt
* the page has selected. The stage rail lives in the page's master pane and is
* not one of these tabs.
*
* The rail owns its own loading, failure and empty states. Every other panel is
* scoped to one attempt, and "no attempt" is a claim only a successful read of
* the run history can make -- a read still in flight is not a verdict either,
* and a failed read is reported as a failed read.
* Every panel is scoped to one attempt, and "no attempt" is a claim only a
* successful read of the run history can make -- a read still in flight is not
* a verdict either, and a failed read is reported as a failed read.
*/
const props = defineProps<{ id: string }>();
@@ -28,42 +27,37 @@ const run = useTaskRun();
<template>
<TabsContent v-for="tab in RUN_TABS" :key="tab.id" :value="tab.id">
<StageRail v-if="tab.id === 'stages'" :state="run.attempts" />
<PanelLoading v-if="run.attempts === undefined" label="Loading this task's attempts…" />
<template v-else>
<PanelLoading v-if="run.attempts === undefined" label="Loading this task's attempts…" />
<PanelError
v-else-if="run.attempts === null"
title="Could not load this task's attempts"
detail="The task's run history could not be read."
/>
<PanelError
v-else-if="run.attempts === null"
title="Could not load this task's attempts"
detail="The task's run history could not be read."
/>
<Empty v-else-if="run.attemptNumber == null">
<EmptyHeader>
<EmptyTitle>No attempt recorded</EmptyTitle>
</EmptyHeader>
</Empty>
<TaskLogs
v-else-if="tab.id === 'log'"
:state="run.logState"
:attempt="run.attemptNumber"
:stages="run.stageNames"
:filters="run.filters"
:task-id="props.id"
@filter="run.setFilters"
/>
<Empty v-else-if="run.attemptNumber == null">
<EmptyHeader>
<EmptyTitle>No attempt recorded</EmptyTitle>
</EmptyHeader>
</Empty>
<ChangedFiles v-else-if="tab.id === 'changes'" :state="run.changesState" :task="run.task" />
<TaskLogs
v-else-if="tab.id === 'log'"
:state="run.logState"
:attempt="run.attemptNumber"
:stages="run.stageNames"
:filters="run.filters"
:task-id="props.id"
@filter="run.setFilters"
/>
<AttemptConfig
v-else-if="tab.id === 'config'"
:events="run.events"
:attempt="run.attemptNumber"
/>
<ChangedFiles v-else-if="tab.id === 'changes'" :state="run.changesState" :task="run.task" />
<AttemptConfig
v-else-if="tab.id === 'config'"
:events="run.events"
:attempt="run.attemptNumber"
/>
<DebugView v-else-if="tab.id === 'debug'" :state="run.debugState" :attempt="run.attemptNumber" />
</template>
<DebugView v-else-if="tab.id === 'debug'" :state="run.debugState" :attempt="run.attemptNumber" />
</TabsContent>
</template>
+11 -1
View File
@@ -21,8 +21,12 @@ export interface TaskRunTab {
label: string;
}
/**
* The inspector's tabs. The stage rail is not one of them: it is the page's
* master pane, always visible, and selecting a stage commands the inspector
* to the log tab with that stage's filter set (docs/prds/task-run-master-detail.md).
*/
export const RUN_TABS: TaskRunTab[] = [
{ id: "stages", label: "Stages" },
{ id: "log", label: "Log" },
{ id: "changes", label: "Changed files" },
{ id: "config", label: "Configuration" },
@@ -31,6 +35,9 @@ export const RUN_TABS: TaskRunTab[] = [
const TAB_IDS = new Set(RUN_TABS.map((tab) => tab.id));
/** URL ids from before the split-pane layout that must keep resolving. */
const LEGACY_TAB_IDS = new Set(["stages"]);
/** The task record as the task list serves it. */
export interface TaskRecord {
id: number | string;
@@ -149,6 +156,9 @@ export function parseTaskId(raw: unknown): number | null {
export function initialTab(query: LocationQuery | undefined): string {
const requested = String(query?.tab ?? "");
// tab=stages named the rail before the split pane; the rail is now always
// visible, so the URL resolves to the inspector's first tab.
if (LEGACY_TAB_IDS.has(requested)) return "log";
return TAB_IDS.has(requested) ? requested : RUN_TABS[0].id;
}