pi-gauntlet 7.26.0 → 7.28.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## v7.28.0 - 2026-10-23
+
+### Added
+
+- **shape-ticket repairs a list of tickets as one batch and grounds every ticket in a repo audit.** A comma or whitespace list of refs runs as one batch repair: duplicates collapse, unfetched refs are reported and skipped, a wishful or tautological AC stops only its own ticket, and each ticket gets the single-ticket confirmation gate in ref order, written on approval before the next gate prints; splits keep their all-or-nothing gate, and batches above eight tickets dispatch in successive calls. A read-only `scout` audit runs per ticket in create and repair mode (`skills/shape-ticket/reference/repo-audit.md`): claims checked against code, repo-fit of the Idea against AGENTS.md/CLAUDE.md/REVIEW.md with a cited simpler or existing path, a sibling-repo leg from the `## shape-ticket` `- sibling:` overrides lines, in-motion work, and a best-effort replication scenario recorded as a note, never a block. Findings rewrite the Problem/Idea with citations or render as an `Audit:` block inside the existing gate; the roast stays content-only and receives the audit as untrusted data; the drafter keeps `audit.md` beside the draft only when gather produced it. The AC integrity gate gains a uniqueness rule (an implied child row folds into its parent, a bundled row splits). `## Examples and rationalizations` and the tracker ladder move to `reference/examples.md` and `reference/tracker-ladder.md`. (#80)
+- Eval samples `batch-repair`, `audit-repo-fit`, `scenario-best-effort`, `audit-quiet-noop`, `audit-byte-lock`, `audit-dispatch`, and `audit-grounding` under `eval/shape-ticket/`. (#80)
+
+### Changed
+
+- The bundle-reference lint in `scripts/ci.mjs` exempts `audit.md` and `snapshot.md` only as `<tmp>/...` path segments or bare names, so a broken `reference/audit.md` link is flagged again. (#80)
+
+## v7.27.0 - 2026-10-22
+
+### Added
+
+- **The phase widget labels the in-progress phase from the dispatches it observes.** A `subagent` call of a known persona (`scout`, `context-builder`, `spec-council-*`, `spec-reviewer`, `plan-writer`, `implementer`, `code-reviewer`, `conformance-reviewer`) or a `plan_check` call sets the phase's substep while the dispatch runs - `verify(conformance)`, `implement(implement+sr)` - and the result clears it; a repeated label in the same phase renders a widget-only ordinal, `verify(conformance #2)`. Skills are unchanged, `status` and the resume brief show the bare label, and session replay restores only labels set by an explicit `substep` call. Vocabulary in `doc/configuration.md`.
+
 ## v7.26.0 - 2026-10-22
 
 ### Changed

package/README.md

@@ -35,7 +35,7 @@ pi-gauntlet's only hard dependency is pi-cohort - every gate that dispatches a r
 
 Concretely, one change through the gauntlet:
 
-0. *(Optional)* Before there's even a spec, `/skill:shape-ticket` can create or repair a single tracker issue - shaping a raw ask into a Context/Problem/Idea/Acceptance Criteria ticket, gated by an AC integrity check, a cheap council roast, and one human-confirmed write that may include one optional gated comment for a Reporter note or overlap evidence. Implementer detail moves into the gated Reporter note; brainstorming reads that note with the ticket so the spec retains the detail. A failed roast is retried once, then surfaced inline at the gate if it fails again. It's a tool, not a phase: no worktree, no plan/phase tracker, runs from any repo state. The agent may start it on its own when the ask is "file a ticket" or another skill routes there; the write still waits for your yes on the presented diff. Similarly, `/skill:chase-bug` triages a raw bug report into an evidenced verdict - and can hand off to shape-ticket, brainstorming, or a bounded hotfix - before any spec exists.
+0. *(Optional)* Before there's even a spec, `/skill:shape-ticket` can create one tracker issue or repair a comma/whitespace list of issue refs - shaping each into a Context/Problem/Idea/Acceptance Criteria ticket, grounded by a repository audit, an AC integrity check, and a cheap council roast. Repair finishes preparation for all tickets before presenting exact-diff confirmations sequentially in ref order; each approval writes that ticket before the next gate, and may include one optional gated comment for a Reporter note or overlap evidence. The audit checks factual claims, Idea fit, AC mechanisms against cited repo guidance, and already-stated observable legs in configured sibling checkouts. It reports in-motion work and attempts a best-effort scenario through authorized current-system reads, without promising reproduction or a fix; missing access or nothing to observe is reported, not a new approval gate. Implementer detail moves into the gated Reporter note; brainstorming reads that note with the ticket so the spec retains the detail. A failed roast is retried once, then surfaced inline at the gate if it fails again. It's a tool, not a phase: no worktree, no plan/phase tracker, runs from any repo state. The agent may start it on its own when the ask is "file a ticket" or another skill routes there; the write still waits for your yes on the presented diff. Similarly, `/skill:chase-bug` triages a raw bug report into an evidenced verdict - and can hand off to shape-ticket, brainstorming, or a bounded hotfix - before any spec exists.
 1. Opt in with `/skill:brainstorming` and describe the change. The command is the reliable discovery-and-entry path; explicit prose requesting brainstorming/the gauntlet also supplies consent when the skill is already loaded or an available instruction or route identifies it. An ordinary implementation request or an agent recommendation is not consent. **`brainstorming`** sets up an isolated worktree, explores the codebase, and turns your description into a written spec - when its recon finds a cited case that the ask is the wrong change (misdiagnosed, wrong-sized, already solved, a band-aid, or cutting across a sound pattern - including a repo convention that is itself debt) and can name the alternative, question one is a framing question (`as framed`, `pivot: <alternative>`, or `smaller or none`); otherwise it opens with one sentence naming what it checked, and every approach it proposes ends with a `Pattern:` line naming what it follows or cuts across; when the run starts from a ticket, the spec carries the ticket's acceptance criteria verbatim, each with a disposition (`in-scope`, `deviates:`, `deferred:`, `venue:`, `elsewhere:` for a row another repo's part delivers), scope cuts come only from your answer to a cut question and are listed at the gate, the conformance gate checks the in-scope ones, and `/skill:check-delivery` verifies `venue:` rows before the prod deploy. A multi-model critique runs on it automatically. If the spec replaces a known prior spec, brainstorming marks the predecessor with a `> **Superseded by:**` banner under its title (default format, syntax overridable via `.pi/gauntlet-overrides.md`; candidates come from brainstorming's scout recon, never a mechanical sweep). **You read and approve the spec - human gate 1.** No implementation code exists yet.
 2. **`writing-plans`** decomposes the approved spec into atomic, independently-verifiable tasks, grouped into parallel waves where they don't touch the same files.
 3. **`subagent-driven-development`** executes the plan one task at a time, each in a fresh subagent, behind spec-compliance review then code-quality review. TDD-locked: red, green, refactor. Independent implementation, review, and council batches remain parallel, but their dispatches are foreground: the orchestrator waits for terminal results before accepting work or advancing a phase.
@@ -77,7 +77,7 @@ The run's grants, target/scope baseline, repair usage, and poll deadline live in
 
 pi-gauntlet ships three kinds of pieces, layered on top of pi-cohort's dispatch:
 
-- **20 skills** - the workflow logic. Fifteen activate automatically when pi sees the matching kind of task, and the workflow skills chain through their gates: `shape-ticket` (creates or repairs one tracker issue per run against a Context/Problem/Idea/Acceptance-Criteria template, gated by an AC integrity check, a cheap council roast, and a single human-confirmed write; model-invocable so other skills and commands can route "file a ticket" to it, the gate still needs your yes), `gatekeep-pr` (model-invocable on an explicit ask that names the PR and the verb; the gates still need your selection - is consent-gated pre-merge verification of a PR against the scope contract at its head - the approved spec's acceptance-criteria dispositions and Design when the PR carries one, else the PR's stated intent; the ticket is cross-checked, never judged here (`check-delivery` owns it) - read-only gathering, verification evidence resolved CI-first (green checks on the exact assessed head count as evidence; a pending commit status that GitHub does not report as blocking the gating actor (`mergeStateStatus` not `BLOCKED`) is not waited for - external-CI commit statuses included - while a running Actions check, an unknown merge state, and every other merge precondition still withhold; the project's verification command runs only as fallback), a rubric-based review, a compact bottom-up report (what the PR delivers, including rows deferred or deviating per spec, PR comments, nits, blockers, then a `mergeable` / `fixable` verdict) and a verb menu whose rows derive from the actor's permissions on the PR; nothing mutates (fixes, pushes, reviews, merges, tracker comments) until you pick a row, except the opt-in `--rebase [base]` sync that rebases, reviews, and lease-pushes the head before verification, or holds the rebased head locally when a conflict stop's scoped tests fail, so the normal `fix` row resolves it before the lease push; after your own merge two opt-in rows post the `AC coverage` block to the ticket or the PR; every terminal menu offers a recommended `cleanup` row that tears down the gate's worktree and branch and runs the overrides file's `## cleanup` steps - run it with `/skill:gatekeep-pr <pr> [--rebase [base]]`), `check-delivery` (model-invocable on an explicit ask that names the ticket and the verb; the gates still need your selection - is a post-merge detective control: proves an issue actually shipped (default-branch landing, delivery target, per-AC evidence) before its tracker status advances; it never writes a terminal status - run it with `/skill:check-delivery <ref>`), `writing-plans`, `roasting-the-spec`, `test-driven-development`, `subagent-driven-development`, `dispatching-parallel-agents`, `verification-before-completion`, `requesting-code-review`, `receiving-code-review`, `using-git-worktrees`, `finishing-a-development-branch`, `forge-skill`, `linear` (reads/searches/comments on/manages Linear tickets via the `linearis` CLI; owns all linearis mechanics and the `## Issue tracker` overrides schema; tracker-facing skills route to it). Five more require explicit entry (`disable-model-invocation: true`): `brainstorming` starts the gated workflow on explicit consent - use `/skill:brainstorming` for reliable discovery, or opt in through reachable explicit prose or a human-selected handoff; after spec approval, downstream planning and implementation still chain automatically. `chase-bug` is human-only bug triage: read-only root-cause discovery to an evidenced verdict menu (real bug -> ticket/brainstorm/hotfix/respond; five negative verdicts), then a gated response to the reporter for addressable origins (GitHub issue / tracker ticket) and a rendered verdict summary otherwise - it never fixes during triage; the hotfix row hands off to `skills/chase-bug/hotfix.md` after the menu - run it with `/skill:chase-bug`. `gauntlet-performance` reads the committed run telemetry (current repo by default, `--dir <path>` adds others) through the parse-only `gauntlet-performance` CLI and answers with one example-led recommendation, 3-5 cornerstone numbers, a council assessment when available, and a menu of at most three actions (render a report file, open the recommendation as a ticket via `shape-ticket`, drill into one run); it writes nothing unless you pick render - run it with `/skill:gauntlet-performance [--dir <path>]... [--since <version>]`. `gauntlet-handoff` ends a session whose flow a fresh session will continue: it invokes pi-cohort's `handoff` skill (`--out <path>` or `--key <name>`, default key = the run worktree's branch with `/` flattened to `-`, default file `<tmpdir>/pi-handoff/<key>.md`), then appends the gauntlet process-state section (phase/plan tracker status) per the shared contract `skills/gauntlet-resume/reference/brief-contract.md` - run it with `/skill:gauntlet-handoff [--out <path> | --key <name>]`. `gauntlet-resume` is the only way back into an interrupted flow from a fresh session: it takes a `gauntlet-handoff` brief (a file path, pasted text, or - with no arguments - a pick from the briefs under `<tmpdir>/pi-handoff/`), a bare worktree that already holds a spec, or a spec tracked on main under a configured spec dir (a spec seed: it creates or reuses the worktree through `using-git-worktrees` and pins the spec), restores phase/plan tracker state through the legal arming sequence (`start brainstorm`, `skip` with `resume:` reasons, `plan_check` before implement-or-later), and never infers approval from artifacts - run it with `/skill:gauntlet-resume [<brief-file> | <spec>.md | <worktree-name-or-path>]`.
+- **20 skills** - the workflow logic. Fifteen activate automatically when pi sees the matching kind of task, and the workflow skills chain through their gates: `shape-ticket` (creates one tracker issue or repairs a comma/whitespace list of refs against a Context/Problem/Idea/Acceptance-Criteria template, with a grounded repo audit, an AC integrity check, a cheap council roast, and sequential per-ticket exact-diff write confirmations; model-invocable so other skills and commands can route "file a ticket" to it, the gate still needs your yes), `gatekeep-pr` (model-invocable on an explicit ask that names the PR and the verb; the gates still need your selection - is consent-gated pre-merge verification of a PR against the scope contract at its head - the approved spec's acceptance-criteria dispositions and Design when the PR carries one, else the PR's stated intent; the ticket is cross-checked, never judged here (`check-delivery` owns it) - read-only gathering, verification evidence resolved CI-first (green checks on the exact assessed head count as evidence; a pending commit status that GitHub does not report as blocking the gating actor (`mergeStateStatus` not `BLOCKED`) is not waited for - external-CI commit statuses included - while a running Actions check, an unknown merge state, and every other merge precondition still withhold; the project's verification command runs only as fallback), a rubric-based review, a compact bottom-up report (what the PR delivers, including rows deferred or deviating per spec, PR comments, nits, blockers, then a `mergeable` / `fixable` verdict) and a verb menu whose rows derive from the actor's permissions on the PR; nothing mutates (fixes, pushes, reviews, merges, tracker comments) until you pick a row, except the opt-in `--rebase [base]` sync that rebases, reviews, and lease-pushes the head before verification, or holds the rebased head locally when a conflict stop's scoped tests fail, so the normal `fix` row resolves it before the lease push; after your own merge two opt-in rows post the `AC coverage` block to the ticket or the PR; every terminal menu offers a recommended `cleanup` row that tears down the gate's worktree and branch and runs the overrides file's `## cleanup` steps - run it with `/skill:gatekeep-pr <pr> [--rebase [base]]`), `check-delivery` (model-invocable on an explicit ask that names the ticket and the verb; the gates still need your selection - is a post-merge detective control: proves an issue actually shipped (default-branch landing, delivery target, per-AC evidence) before its tracker status advances; it never writes a terminal status - run it with `/skill:check-delivery <ref>`), `writing-plans`, `roasting-the-spec`, `test-driven-development`, `subagent-driven-development`, `dispatching-parallel-agents`, `verification-before-completion`, `requesting-code-review`, `receiving-code-review`, `using-git-worktrees`, `finishing-a-development-branch`, `forge-skill`, `linear` (reads/searches/comments on/manages Linear tickets via the `linearis` CLI; owns all linearis mechanics and the `## Issue tracker` overrides schema; tracker-facing skills route to it). Five more require explicit entry (`disable-model-invocation: true`): `brainstorming` starts the gated workflow on explicit consent - use `/skill:brainstorming` for reliable discovery, or opt in through reachable explicit prose or a human-selected handoff; after spec approval, downstream planning and implementation still chain automatically. `chase-bug` is human-only bug triage: read-only root-cause discovery to an evidenced verdict menu (real bug -> ticket/brainstorm/hotfix/respond; five negative verdicts), then a gated response to the reporter for addressable origins (GitHub issue / tracker ticket) and a rendered verdict summary otherwise - it never fixes during triage; the hotfix row hands off to `skills/chase-bug/hotfix.md` after the menu - run it with `/skill:chase-bug`. `gauntlet-performance` reads the committed run telemetry (current repo by default, `--dir <path>` adds others) through the parse-only `gauntlet-performance` CLI and answers with one example-led recommendation, 3-5 cornerstone numbers, a council assessment when available, and a menu of at most three actions (render a report file, open the recommendation as a ticket via `shape-ticket`, drill into one run); it writes nothing unless you pick render - run it with `/skill:gauntlet-performance [--dir <path>]... [--since <version>]`. `gauntlet-handoff` ends a session whose flow a fresh session will continue: it invokes pi-cohort's `handoff` skill (`--out <path>` or `--key <name>`, default key = the run worktree's branch with `/` flattened to `-`, default file `<tmpdir>/pi-handoff/<key>.md`), then appends the gauntlet process-state section (phase/plan tracker status) per the shared contract `skills/gauntlet-resume/reference/brief-contract.md` - run it with `/skill:gauntlet-handoff [--out <path> | --key <name>]`. `gauntlet-resume` is the only way back into an interrupted flow from a fresh session: it takes a `gauntlet-handoff` brief (a file path, pasted text, or - with no arguments - a pick from the briefs under `<tmpdir>/pi-handoff/`), a bare worktree that already holds a spec, or a spec tracked on main under a configured spec dir (a spec seed: it creates or reuses the worktree through `using-git-worktrees` and pins the spec), restores phase/plan tracker state through the legal arming sequence (`start brainstorm`, `skip` with `resume:` reasons, `plan_check` before implement-or-later), and never infers approval from artifacts - run it with `/skill:gauntlet-resume [<brief-file> | <spec>.md | <worktree-name-or-path>]`.
 - **9 subagent personas** - the specialized child agents the skills dispatch via pi-cohort: `implementer`, `code-reviewer`, `spec-reviewer`, `conformance-reviewer`, `spec-summarizer`, `plan-writer`, `spec-council-member`, `spec-council-synthesizer`, `spec-council-applier`. See [doc/personas.md](./doc/personas.md) for what each one does and why its permissions are scoped the way they are.
 - **4 runtime extensions** - the enforcement layer. `plan-tracker` and `phase-tracker` are tools skills call to track progress (with a TUI widget); `verify-before-ship` is a hook that warns if you push or open a PR without a passing test run since your last edit; a phase-tracker flow guard reminds on implement-phase commits missing spec/code review. In a brainstorming-entered flow, phase-tracker rejects `implement` or `verify` completion while tracker tasks remain pending or in progress; see [its configuration reference](./doc/configuration.md#phase-tracker). phase-tracker also registers `plan_check`, which verifies a plan against its spec and against the grammar in [skills/writing-plans/reference/plan-contract.md](./skills/writing-plans/reference/plan-contract.md), including that each task's `Tests:` commands are selective and never the full suite, and that every test command carries a passing base-commit result; a pass stamps the plan for implementation. `telemetry` records one YAML record per gauntlet run (phase timing, models, personas, gate/fix rounds, diff at ship) that ships in the squash beside the spec - it is written only inside a brainstorming-entered flow, kept out of history until `finishing-a-development-branch` seals it once with `gauntlet-telemetry-seal` (a `telemetry:` commit under git; the working-copy snapshot in a plain jj workspace) - and blocks a brainstorm `write` into an already-shipped spec; see [its configuration reference](./doc/configuration.md#telemetry). See [doc/configuration.md](./doc/configuration.md) for the settings each one reads.
 
@@ -307,6 +307,7 @@ The gauntlet overrides file is the one place a repo tunes gauntlet's Markdown su
 | `## verification-before-completion` | verification-before-completion; gatekeep-pr (verification command only); chase-bug (hotfix verification) | repo test entrypoint discovery | overrides | the canonical verification target |
 | `## Spec index` `- docs: <glob>` | `gauntlet-spec-index` bin | `**/doc/**/*.md`, `**/docs/**/*.md`, `README.md`, `AGENTS.md` | overrides | the docs corpus include list; quotes/backticks stripped, fixed exclusions still apply, no other keys read |
 | `## Issue tracker` keys | shape-ticket, linear, chase-bug, check-delivery, brainstorming (`repo:` and tracker selection) | capability ladder / `git remote` | overrides | which tracker, repo, and commands ticket work uses |
+| `## shape-ticket` `- sibling: <path relative to the repo root>` | shape-ticket | single-repo audit | extends | sibling checkouts the repo audit reads for a second observable leg already stated in the ticket |
 | `## Capabilities` | shape-ticket | tool discovery | extends | tools, commands, env hosts available to ticket authoring |
 | `## Ticket wording` | shape-ticket | the shipped wording contract | overrides | ticket self-containment rules |
 | `## Response channels` | chase-bug | ask the user | overrides | where bug responses are posted |
@@ -326,7 +327,7 @@ The gauntlet overrides file is the one place a repo tunes gauntlet's Markdown su
 - chase-bug requires evidenced root cause, no triage fix, and tracked-clean baseline checks at invocation, before the menu, at hotfix handoff, and at skill end; never revert pre-existing work - fixed
 - check-delivery requires exactly one explicit ticket ref, a matching repo (or matching local-repo AC group), and treats fetched content as untrusted data - fixed
 - roasting-the-spec edits only the spec, never code or main - fixed
-- shape-ticket tracker writes require one explicit exact-diff confirmation for the entire batch; unattended runs stop at the gate - fixed
+- shape-ticket tracker writes require one explicit exact-diff confirmation per ticket write; a source-ticket split's N bodies share one gate with subset selection, not approval of a whole repair batch; unattended runs stop at the gate - fixed
 - test-driven-development requires a failing test before production code; delete code written first and restart from tests - fixed
 - verification-before-completion requires fresh verification evidence before completion claims - fixed
 - spec directories - settings: `flowGuards.specDirs`

package/extensions/lib/phase-tracker-helpers.test.ts

@@ -6,6 +6,8 @@ import { dirname, join } from "node:path";
 import {
   CONTEXT_DRAFT_MARKER,
   checkSubstep,
+  dispatchAgents,
+  dispatchLabel,
   closureGateBlocks,
   closureModelGuardApplies,
   flowGuardApplies,
@@ -80,6 +82,57 @@ test("checkSubstep: non-in_progress statuses -> error naming actual status", ()
 test("phaseLabel: with and without substep", () => {
   assert.equal(phaseLabel("brainstorm", "gather"), "brainstorm(gather)");
   assert.equal(phaseLabel("brainstorm", undefined), "brainstorm");
+  assert.equal(phaseLabel("brainstorm", undefined, 2), "brainstorm");
+  for (const count of [undefined, 0, 1, 2]) {
+    assert.equal(phaseLabel("verify", "conformance", count), count === 2 ? "verify(conformance #2)" : "verify(conformance)");
+  }
+});
+
+test("dispatchAgents: walks dispatch shapes in order and ignores non-string agents", () => {
+  const cases: [string, unknown, string[]][] = [
+    ["single", { agent: "scout" }, ["scout"]],
+    ["tasks", { tasks: [{ agent: "scout" }, { agent: "context-builder" }] }, ["scout", "context-builder"]],
+    ["recursive chain", { chain: [{ chain: [{ agent: "plan-writer" }] }] }, ["plan-writer"]],
+    ["root and nested", { agent: "root", tasks: [{ agent: "task" }], chain: [{ agent: "step", parallel: [{ agent: "implementer" }, { agent: "spec-reviewer" }] }] }, ["root", "task", "step", "implementer", "spec-reviewer"]],
+    ["bare top-level array", [{ agent: "scout" }], []],
+    ["nested array ignored", { tasks: [[{ agent: "scout" }]] }, []],
+    ["object nodes", { tasks: { agent: "context-builder" } }, ["context-builder"]],
+    ["malformed", { agent: 42, tasks: [null, "scout", { agent: false }, { agent: "unknown" }] }, ["unknown"]],
+    ["null", null, []],
+  ];
+  for (const [name, input, expected] of cases) assert.deepEqual(dispatchAgents(input), expected, name);
+});
+
+test("dispatchLabel: maps the vocabulary and combined implementation dispatch", () => {
+  const cases: [string, unknown, string][] = [
+    ["subagent", { agent: "scout" }, "gather"],
+    ["subagent", { agent: "context-builder" }, "gather"],
+    ["subagent", { agent: "spec-council-design" }, "council"],
+    ["subagent", { agent: "spec-council-security" }, "council"],
+    ["subagent", { agent: "spec-reviewer" }, "spec-review"],
+    ["subagent", { agent: "plan-writer" }, "plan-write"],
+    ["plan_check", {}, "plan-check"],
+    ["subagent", { agent: "implementer" }, "implement"],
+    ["subagent", { agent: "code-reviewer" }, "code-review"],
+    ["subagent", { agent: "conformance-reviewer" }, "conformance"],
+    ["subagent", { chain: [{ parallel: [{ agent: "implementer" }] }, { parallel: [{ agent: "spec-reviewer" }] }] }, "implement+sr"],
+    ["subagent", { tasks: [{ agent: "worker" }, { agent: "scout" }] }, "gather"],
+    ["subagent", { tasks: [{ agent: "scout" }, { agent: "code-reviewer" }] }, "gather"],
+    ["subagent", { tasks: [{ agent: "code-reviewer" }, { agent: "scout" }] }, "code-review"],
+    ["subagent", { tasks: [{ agent: "scout" }, { agent: "spec-reviewer" }, { agent: "implementer" }] }, "implement+sr"],
+  ];
+  for (const [tool, input, expected] of cases) assert.equal(dispatchLabel(tool, input), expected);
+});
+
+test("dispatchLabel: ignores management, unmapped agents, other tools and malformed input", () => {
+  const inputs: unknown[] = [
+    { agent: "worker" }, { agent: "spec-summarizer" }, { agent: "ad-hoc" },
+    { agent: "spec-council" }, { agent: "implementer-extra" },
+    { action: "list", agent: "scout" }, { action: undefined, agent: "scout" },
+    undefined, null, 1, "scout", {}, { agent: 1 }, { tasks: [null, false] },
+  ];
+  for (const input of inputs) assert.equal(dispatchLabel("subagent", input), undefined);
+  assert.equal(dispatchLabel("tool_result", { agent: "scout" }), undefined);
 });
 
 test("parseGitCommand: branch subcommands with and without global flags", () => {

package/extensions/lib/phase-tracker-helpers.ts

@@ -31,8 +31,54 @@ export function checkSubstep(phaseStatus: string): SubstepCheck {
   return { ok: false, error: `substep requires an in_progress phase (status is ${phaseStatus})` };
 }
 
-export function phaseLabel(name: string, substep?: string): string {
-  return substep ? `${name}(${substep})` : name;
+export const DISPATCH_LABELS = {
+  scout: "gather",
+  "context-builder": "gather",
+  "spec-council-": "council",
+  "spec-reviewer": "spec-review",
+  "plan-writer": "plan-write",
+  plan_check: "plan-check",
+  implementer: "implement",
+  "code-reviewer": "code-review",
+  "conformance-reviewer": "conformance",
+  "implement+sr": "implement+sr",
+} as const;
+
+export function dispatchAgents(input: unknown): string[] {
+  const agents: string[] = [];
+  const collect = (node: unknown): void => {
+    if (!node || typeof node !== "object") return;
+    const object = node as Record<string, unknown>;
+    if (typeof object.agent === "string") agents.push(object.agent);
+    for (const key of ["tasks", "chain", "parallel"] as const) {
+      const value = object[key];
+      if (Array.isArray(value)) for (const item of value) collect(item);
+      else if (value && typeof value === "object") collect(value);
+    }
+  };
+  collect(input);
+  return agents;
+}
+
+export function dispatchLabel(toolName: string, input: unknown): string | undefined {
+  if (toolName === "plan_check") return DISPATCH_LABELS.plan_check;
+  if (toolName !== "subagent") return undefined;
+  if (input && typeof input === "object" && "action" in input) return undefined;
+  const agents = dispatchAgents(input);
+  if (agents.includes("implementer") && agents.includes("spec-reviewer")) return DISPATCH_LABELS["implement+sr"];
+  for (const agent of agents) {
+    for (const name of ["scout", "context-builder", "spec-reviewer", "plan-writer", "implementer", "code-reviewer", "conformance-reviewer"] as const) {
+      if (agent === name) return DISPATCH_LABELS[name];
+    }
+    if (agent.startsWith("spec-council-")) return DISPATCH_LABELS["spec-council-"];
+  }
+  return undefined;
+}
+
+export function phaseLabel(name: string, substep?: string, count?: number): string {
+  if (!substep) return name;
+  const ordinal = count !== undefined && count >= 2 ? ` #${count}` : "";
+  return `${name}(${substep}${ordinal})`;
 }
 
 // Same statement-start anchor as the branch guards in phase-tracker.ts. Exported

package/extensions/phase-tracker.test.ts

@@ -46,17 +46,17 @@ type Status = "pending" | "in_progress" | "complete" | "skipped";
 const phases = (overrides: Partial<Record<Phase, Status>> = {}) =>
   Object.fromEntries(PHASES.map((phase) => [phase, { status: overrides[phase] ?? "pending" }])) as Record<
     Phase,
-    { status: Status }
+    { status: Status; substep?: string }
   >;
 
-const phaseResult = (action: string, state: Record<Phase, { status: Status }>) => ({
+const phaseResult = (action: string, state: Record<Phase, { status: Status; substep?: string }>) => ({
   type: "message",
   message: { role: "toolResult", toolName: "phase_tracker", details: { action, phases: state } },
 });
 
 const assistant = (stopReason = "stop") => ({ type: "message", message: { role: "assistant", stopReason } });
 
-const enteredBranch = (state: Record<Phase, { status: Status }>, extra: unknown[] = []) => [
+const enteredBranch = (state: Record<Phase, { status: Status; substep?: string }>, extra: unknown[] = []) => [
   phaseResult("start", phases({ brainstorm: "in_progress" })),
   phaseResult("complete", state),
   ...extra,
@@ -71,15 +71,19 @@ const resumedBranch = (rest: Partial<Record<Phase, Status>>) => [
 
 type TestModel = { provider: string; id: string };
 
-function harness(options: { cwd?: string; branch?: unknown[]; idle?: boolean; beforeSettled?: (setIdle: (idle: boolean) => void) => void; sendThrows?: boolean; model?: TestModel; thinkingLevel?: string; registry?: Record<string, TestModel>; setModelResult?: boolean | Error } = {}) {
+function harness(options: { hasUI?: boolean; cwd?: string; branch?: unknown[]; idle?: boolean; beforeSettled?: (setIdle: (idle: boolean) => void) => void; sendThrows?: boolean; model?: TestModel; thinkingLevel?: string; registry?: Record<string, TestModel>; setModelResult?: boolean | Error } = {}) {
   const handlers = new Map<string, ((event: unknown, ctx: unknown) => unknown)[]>();
   const tools: { name: string; executionMode?: string; parameters?: any; execute: (...args: any[]) => unknown }[] = [];
   const sent: { message: any; options: any }[] = [];
+  const widgets: (string | undefined)[] = [];
   let idle = options.idle ?? true;
   let branch = options.branch ?? [];
   const ctx = {
     cwd: options.cwd ?? tempCwd(),
-    hasUI: false,
+    hasUI: options.hasUI ?? false,
+    ui: { setWidget: (name: string, factory: any) => {
+      if (name === "phase_tracker") widgets.push(factory?.({}, { fg: (_color: string, text: string) => text }).text);
+    } },
     isIdle: () => idle,
     sessionManager: { getBranch: () => branch },
     model: options.model,
@@ -122,7 +126,7 @@ function harness(options: { cwd?: string; branch?: unknown[]; idle?: boolean; be
     for (const handler of handlers.get(name) ?? []) results.push(await handler(event, ctx));
     return results;
   };
-  return { pi, emit, emitEvent, sent, tools, ctx, setIdle: (next: boolean) => (idle = next), setBranch: (next: unknown[]) => (branch = next) };
+  return { pi, emit, emitEvent, sent, tools, ctx, widgets, setIdle: (next: boolean) => (idle = next), setBranch: (next: unknown[]) => (branch = next) };
 }
 
 const settle = async (h: ReturnType<typeof harness>) => {
@@ -2064,3 +2068,335 @@ test("open-task nudge: silent on an isError result, a degraded settings read, an
     process.env.PI_SUBAGENT_DEPTH = "0";
   }
 });
+
+for (const action of ["complete", "skip"] as const) {
+  for (const isError of [false, true]) {
+    test(`live dispatch clears after ${action} of a different phase, error=${isError}`, async () => {
+      const h = harness({ hasUI: true });
+      const tool = h.tools.find(t => t.name === "phase_tracker")!;
+      await startPhase(h, "verify");
+      await h.emitEvent("tool_call", subagentCall("review", { agent: "code-reviewer" }));
+      const result = await tool.execute("transition", { action, phase: "ship", reason: "not needed" }, undefined, undefined, h.ctx) as any;
+      assert.equal(result.details.error, undefined);
+      assert.match(h.widgets.at(-1)!, /verify\(code-review\)/);
+      await h.emitEvent("tool_result", { toolName: "subagent", toolCallId: "review", isError, details: {}, content: [] });
+      assert.doesNotMatch(h.widgets.at(-1)!, /verify\(/);
+      await h.emitEvent("tool_call", subagentCall("next", { agent: "code-reviewer" }));
+      assert.ok(h.widgets.at(-1)!.includes(`verify(code-review${isError ? "" : " #2"})`));
+    });
+  }
+}
+
+for (const isError of [false, true]) {
+  test(`live dispatch survives a deferred start of a different phase, error=${isError}`, async () => {
+    const h = harness({
+      hasUI: true,
+      cwd: tempCwd({ piGauntlet: { phaseModels: { ship: "p/m" } } }),
+      model: M("old"),
+      registry: { "p/m": M("m") },
+    });
+    let entered!: () => void;
+    let release!: () => void;
+    const modelEntered = new Promise<void>(resolve => { entered = resolve; });
+    const modelReleased = new Promise<void>(resolve => { release = resolve; });
+    h.pi.setModel = async () => {
+      entered();
+      await modelReleased;
+      return true;
+    };
+    const shipStart = startPhase(h, "ship");
+    await modelEntered;
+    await startPhase(h, "verify");
+    await h.emitEvent("tool_call", subagentCall("review", { agent: "code-reviewer" }));
+    release();
+    assert.equal((await shipStart).status, "in_progress");
+    assert.match(h.widgets.at(-1)!, /verify\(code-review\)/);
+    await h.emitEvent("tool_result", { toolName: "subagent", toolCallId: "review", isError, details: {}, content: [] });
+    assert.doesNotMatch(h.widgets.at(-1)!, /verify\(/);
+    const tool = h.tools.find(t => t.name === "phase_tracker")!;
+    const status = await tool.execute("status", { action: "status" }, undefined, undefined, h.ctx) as any;
+    assert.equal(status.details.phases.ship.status, "in_progress");
+    await h.emitEvent("tool_call", subagentCall("next", { agent: "code-reviewer" }));
+    assert.ok(h.widgets.at(-1)!.includes(`verify(code-review${isError ? "" : " #2"})`));
+  });
+}
+
+test("live dispatch labels repaint and keep ordinals out of status snapshots", async () => {
+  const h = harness({ hasUI: true });
+  const tool = h.tools.find(t => t.name === "phase_tracker")!;
+  const start = await tool.execute("start", { action: "start", phase: "verify" }, undefined, undefined, h.ctx) as any;
+  await h.emitEvent("tool_call", subagentCall("a", { agent: "conformance-reviewer" }));
+  assert.match(h.widgets.at(-1)!, /verify\(conformance\)/);
+  assert.equal(start.details.phases.verify.substep, undefined);
+  await h.emitEvent("tool_result", { toolName: "subagent", toolCallId: "a", details: {}, content: [] });
+  assert.doesNotMatch(h.widgets.at(-1)!, /verify\(/);
+  await h.emitEvent("tool_call", subagentCall("b", { agent: "conformance-reviewer" }));
+  assert.match(h.widgets.at(-1)!, /verify\(conformance #2\)/);
+  const status = await tool.execute("status", { action: "status" }, undefined, undefined, h.ctx) as any;
+  assert.match(status.content[0].text, /verify\(conformance\)/);
+  assert.doesNotMatch(status.content[0].text, /#2/);
+  const theme = { fg: (_color: string, text: string) => text };
+  const renderer = (tool as any).renderResult;
+  assert.doesNotMatch(renderer(status, {}, theme).text, /#2/);
+  const explicit = await tool.execute("explicit", { action: "substep", phase: "verify", substep: "conformance" }, undefined, undefined, h.ctx) as any;
+  assert.equal(renderer(explicit, {}, theme).text, "→ verify(conformance)");
+});
+
+for (const row of [
+  { phase: "implement", input: { chain: [{ parallel: [{ agent: "implementer" }] }, { parallel: [{ agent: "spec-reviewer" }] }] }, label: "implement+sr" },
+  { phase: "implement", input: { agent: "code-reviewer" }, label: "code-review" },
+  { phase: "implement", input: { agent: "implementer" }, label: "implement" },
+  { phase: "implement", input: { agent: "spec-reviewer" }, label: "spec-review" },
+  { phase: "plan", toolName: "plan_check", input: {}, label: "plan-check" },
+  { phase: "verify", toolName: "plan_check", input: {}, label: "plan-check" },
+]) {
+  test(`live vocabulary: ${row.phase}(${row.label})`, async () => {
+    const h = harness({ hasUI: true });
+    await startPhase(h, row.phase);
+    await h.emitEvent("tool_call", { toolName: row.toolName ?? "subagent", toolCallId: "a", input: row.input });
+    assert.ok(h.widgets.at(-1)!.includes(`${row.phase}(${row.label})`));
+    const paints = h.widgets.length;
+    for (const input of [{ agent: "worker" }, { action: "status", agent: "implementer" }]) {
+      await h.emitEvent("tool_call", subagentCall("ignored", input));
+    }
+    await h.emitEvent("tool_execution_end", { toolName: "plan_tracker", toolCallId: "reopen", result: { details: { tasks: [{ status: "in_progress" }] } } });
+    assert.ok(h.widgets.at(-1)!.includes(`${row.phase}(${row.label})`));
+    assert.equal(h.widgets.length, paints + 1);
+    await h.emitEvent("tool_execution_end", { toolName: row.toolName ?? "subagent", toolCallId: "a", result: { details: {} } });
+    assert.ok(!h.widgets.at(-1)!.includes(`${row.phase}(`));
+  });
+}
+
+for (const agents of [
+  ["code-reviewer", "implementer", "code-reviewer", "conformance-reviewer"],
+  ["conformance-reviewer", "implementer", "conformance-reviewer", "code-reviewer", "code-reviewer", "code-reviewer"],
+]) {
+  test(`live repair sequence: ${agents.join(" -> ")}`, async () => {
+    const h = harness({ hasUI: true });
+    await startPhase(h, "verify");
+    const counts: Record<string, number> = {};
+    for (const [i, agent] of agents.entries()) {
+      const label = ({ "code-reviewer": "code-review", implementer: "implement", "conformance-reviewer": "conformance" })[agent]!;
+      const n = counts[label] = (counts[label] ?? 0) + 1;
+      await h.emitEvent("tool_call", subagentCall(String(i), { tasks: [{ agent }] }));
+      assert.ok(h.widgets.at(-1)!.includes(`verify(${label}${n > 1 ? ` #${n}` : ""})`));
+      await h.emitEvent("tool_result", { toolName: "subagent", toolCallId: String(i), details: {}, content: [] });
+    }
+  });
+}
+
+for (const row of [
+  { name: "normal", isError: false, details: {}, refund: false },
+  { name: "executed error", isError: true, details: { results: [] }, refund: false },
+  { name: "empty error", isError: true, details: {}, refund: true },
+]) {
+  for (const endOnly of [false, true]) {
+    test(`live terminal: ${row.name}, execution-end-only=${endOnly}`, async () => {
+      const h = harness({ hasUI: true });
+      await startPhase(h, "verify");
+      await h.emitEvent("tool_call", subagentCall("a", { agent: "code-reviewer" }));
+      const paints = h.widgets.length;
+      await h.emitEvent("tool_result", { toolName: "subagent", toolCallId: "other", details: {}, content: [] });
+      assert.equal(h.widgets.length, paints);
+      const terminal = { toolName: "subagent", toolCallId: "a", isError: row.isError, details: row.details, content: [] };
+      if (!endOnly) await h.emitEvent("tool_result", terminal);
+      await h.emitEvent("tool_execution_end", { ...terminal, result: { details: row.details } });
+      assert.equal(h.widgets.length, paints + 1);
+      assert.doesNotMatch(h.widgets.at(-1)!, /verify\(/);
+      await h.emitEvent("tool_execution_end", { ...terminal, result: { details: row.details } });
+      assert.equal(h.widgets.length, paints + 1);
+      await h.emitEvent("tool_call", subagentCall("b", { agent: "code-reviewer" }));
+      assert.ok(h.widgets.at(-1)!.includes(`verify(code-review${row.refund ? "" : " #2"})`));
+    });
+  }
+}
+
+test("live overlap forgets older calls and explicit overwrite survives cleanup", async () => {
+  const h = harness({ hasUI: true });
+  await startPhase(h, "verify");
+  const tool = h.tools.find(t => t.name === "phase_tracker")!;
+  const explicit = (substep: string) => tool.execute("explicit", { action: "substep", phase: "verify", substep }, undefined, undefined, h.ctx);
+  await explicit("before");
+  for (const id of ["a", "b"]) await h.emitEvent("tool_call", subagentCall(id, { agent: "code-reviewer", async: true }));
+  assert.match(h.widgets.at(-1)!, /verify\(code-review #2\)/);
+  const paints = h.widgets.length;
+  await h.emitEvent("tool_result", { toolName: "subagent", toolCallId: "a", details: {}, content: [] });
+  assert.equal(h.widgets.length, paints);
+  await h.emitEvent("tool_result", { toolName: "subagent", toolCallId: "b", details: {}, content: [] });
+  assert.doesNotMatch(h.widgets.at(-1)!, /verify\(/);
+  await h.emitEvent("tool_call", subagentCall("c", { agent: "code-reviewer" }));
+  const snapshot = await explicit("custom") as any;
+  await h.emitEvent("tool_result", { toolName: "subagent", toolCallId: "c", isError: true, details: {}, content: [] });
+  assert.match(h.widgets.at(-1)!, /verify\(custom\)/);
+  assert.equal(snapshot.details.phases.verify.substep, "custom");
+  await h.emitEvent("tool_call", subagentCall("d", { agent: "code-reviewer" }));
+  assert.match(h.widgets.at(-1)!, /verify\(code-review #3\)/);
+});
+
+for (const action of ["start", "complete", "skip", "reset"]) {
+  test(`live transition ${action} drops terminal ownership and restart resets counts`, async () => {
+    const h = harness({ hasUI: true });
+    const tool = h.tools.find(t => t.name === "phase_tracker")!;
+    await startPhase(h, "verify");
+    await h.emitEvent("tool_call", subagentCall("old", { agent: "code-reviewer" }));
+    const rejected = await tool.execute("bad", { action: "start", phase: "plan" }, undefined, undefined, h.ctx) as any;
+    assert.ok(rejected.details.error);
+    assert.match(h.widgets.at(-1)!, /verify\(code-review\)/);
+    await tool.execute("transition", { action, phase: "verify", reason: "test" }, undefined, undefined, h.ctx);
+    if (action === "reset") assert.equal(h.widgets.at(-1), undefined);
+    if (action !== "start") await tool.execute("restart", { action: "start", phase: "verify", force: true }, undefined, undefined, h.ctx);
+    await tool.execute("label", { action: "substep", phase: "verify", substep: "custom" }, undefined, undefined, h.ctx);
+    const paints = h.widgets.length;
+    await h.emitEvent("tool_execution_end", { toolName: "subagent", toolCallId: "old", result: { details: {} } });
+    assert.equal(h.widgets.length, paints);
+    assert.match(h.widgets.at(-1)!, /verify\(custom\)/);
+    await h.emitEvent("tool_call", subagentCall("new", { agent: "code-reviewer" }));
+    assert.match(h.widgets.at(-1)!, /verify\(code-review\)/);
+  });
+}
+
+test("live plan backstop clears ownership only on actual implement completion", async () => {
+  const h = harness({ hasUI: true });
+  await startPhase(h, "implement");
+  await h.emitEvent("tool_call", subagentCall("old", { agent: "code-reviewer" }));
+  for (const tasks of [undefined, [{ status: "in_progress" }]]) {
+    await h.emitEvent("tool_execution_end", { toolName: "plan_tracker", result: { details: { tasks } } });
+    assert.match(h.widgets.at(-1)!, /implement\(code-review\)/);
+  }
+  await h.emitEvent("tool_execution_end", { toolName: "plan_tracker", result: { details: { tasks: [{ status: "complete" }] } } });
+  await startPhase(h, "verify");
+  const tool = h.tools.find(t => t.name === "phase_tracker")!;
+  await tool.execute("label", { action: "substep", phase: "verify", substep: "custom" }, undefined, undefined, h.ctx);
+  await h.emitEvent("tool_result", { toolName: "subagent", toolCallId: "old", details: {}, content: [] });
+  assert.match(h.widgets.at(-1)!, /verify\(custom\)/);
+  await h.emitEvent("tool_call", subagentCall("new", { agent: "code-reviewer" }));
+  assert.match(h.widgets.at(-1)!, /verify\(code-review\)/);
+});
+
+test("live observation is dormant without a phase and in a subagent child", async () => {
+  const dormant = harness({ hasUI: true });
+  await dormant.emitEvent("tool_call", { toolName: "plan_check", toolCallId: "a", input: {} });
+  assert.equal(dormant.widgets.length, 0);
+  const prior = process.env.PI_SUBAGENT_DEPTH;
+  let child: ReturnType<typeof harness>;
+  try {
+    process.env.PI_SUBAGENT_DEPTH = "1";
+    child = harness({ hasUI: true });
+  } finally {
+    if (prior === undefined) delete process.env.PI_SUBAGENT_DEPTH;
+    else process.env.PI_SUBAGENT_DEPTH = prior;
+  }
+  await startPhase(child, "verify");
+  const paints = child.widgets.length;
+  await child.emitEvent("tool_call", subagentCall("a", { agent: "conformance-reviewer" }));
+  await child.emitEvent("tool_call", { toolName: "plan_check", toolCallId: "b", input: {} });
+  assert.equal(child.widgets.length, paints);
+});
+
+for (const cap of [false, true]) {
+  test(`live blocked ${cap ? "cap" : "lone"} call creates no label or ordinal`, async () => {
+    const cwd = tempCwd({ piGauntlet: { closureReview: { enforce: true, maxFixRounds: cap ? 0 : 3 } } });
+    const h = harness({ hasUI: true, cwd, branch: verifyBranch([subagentResult(["conformance-reviewer"])]) });
+    await h.emit("session_start");
+    const paints = h.widgets.length;
+    assert.equal((await firstCallResult(h, "blocked", cap ? implementerWave() : loneImplementer()))?.block, true);
+    await h.emitEvent("tool_execution_end", { toolName: "subagent", toolCallId: "blocked", isError: true, result: { details: {} } });
+    assert.equal(h.widgets.length, paints);
+    writeFileSync(join(cwd, ".pi", "settings.json"), JSON.stringify({ piGauntlet: { closureReview: { enforce: false } } }));
+    await firstCallResult(h, "allowed", implementerWave());
+    assert.match(h.widgets.at(-1)!, /verify\(implement\)/);
+  });
+}
+
+const replaySnapshot = (phase: Phase, substep?: string, status: Status = "in_progress") => {
+  const state = phases({ [phase]: status });
+  if (substep !== undefined) state[phase].substep = substep;
+  return state;
+};
+
+const explicitReplay = (phase: Phase, label: string) => [
+  phaseResult("start", replaySnapshot(phase)),
+  phaseResult("substep", replaySnapshot(phase, label)),
+];
+
+for (const row of [
+  { name: "derived status only", branch: [phaseResult("start", replaySnapshot("verify")), phaseResult("status", replaySnapshot("verify", "conformance"))], phase: "verify", expected: undefined },
+  { name: "explicit before derived status", branch: [...explicitReplay("verify", "gather"), phaseResult("status", replaySnapshot("verify", "council"))], phase: "verify", expected: "gather" },
+  ...([{ phase: "brainstorm", label: "gather", agent: "scout" }, { phase: "plan", label: "plan-write", agent: "plan-writer" }] as const).map(r => ({
+    name: `unfinished ${r.agent}`, phase: r.phase, expected: r.label,
+    branch: [...explicitReplay(r.phase, r.label), assistant(), { type: "message", message: { role: "assistant", content: [{ type: "toolCall", id: "unfinished", name: "subagent", arguments: { agent: r.agent } }] } }],
+  })),
+  { name: "null or omitted clear", phase: "verify", expected: undefined, branch: [...explicitReplay("verify", "gather"), phaseResult("substep", replaySnapshot("verify")), phaseResult("status", replaySnapshot("verify", "council"))] },
+  ...["start", "complete", "skip"].map(action => ({ name: `same phase ${action}`, phase: "verify", expected: undefined, branch: [...explicitReplay("verify", "gather"), phaseResult(action, replaySnapshot("verify", undefined, action === "complete" ? "complete" : action === "skip" ? "skipped" : "in_progress"))] })),
+  ...["complete", "skip"].map(action => {
+    const state = replaySnapshot("verify", "gather");
+    state.ship.status = action === "complete" ? "complete" : "skipped";
+    return { name: `other phase ${action}`, phase: "verify", expected: "gather", branch: [...explicitReplay("verify", "gather"), phaseResult(action, state)] };
+  }),
+  { name: "reset then start", phase: "verify", expected: undefined, branch: [...explicitReplay("verify", "gather"), phaseResult("reset", phases()), phaseResult("start", replaySnapshot("verify"))] },
+  ...["substep", "start", "complete", "skip", "reset"].map(action => {
+    const rejected = phaseResult(action, phases());
+    Object.assign(rejected.message.details, { error: "rejected" });
+    return { name: `rejected ${action}`, phase: "verify", expected: "gather", branch: [...explicitReplay("verify", "gather"), rejected] };
+  }),
+  { name: "task-driven completion", phase: "implement", expected: undefined, expectedStatus: "complete", branch: [...explicitReplay("implement", "custom"), taskSnapshot([{ name: "task", status: "complete" }])] },
+  { name: "custom after clear", phase: "verify", expected: "custom", branch: [...explicitReplay("verify", "gather"), phaseResult("substep", replaySnapshot("verify")), phaseResult("substep", replaySnapshot("verify", "custom"))] },
+]) {
+  test(`replay explicit labels: ${row.name}`, async () => {
+    const original = structuredClone(row.branch);
+    const h = harness({ hasUI: true, branch: row.branch });
+    const tool = h.tools.find(t => t.name === "phase_tracker")!;
+    await h.emit("session_start");
+    const status = await tool.execute("status", { action: "status" }, undefined, undefined, h.ctx) as any;
+    assert.equal(status.details.phases[row.phase].substep, row.expected);
+    if ("expectedStatus" in row) assert.equal(status.details.phases[row.phase].status, row.expectedStatus);
+    if (row.expected) {
+      assert.ok(h.widgets.at(-1)!.includes(`${row.phase}(${row.expected})`));
+      assert.ok(status.content[0].text.includes(`${row.phase}(${row.expected})`));
+    } else {
+      assert.ok(!h.widgets.at(-1)!.includes(`${row.phase}(`));
+    }
+    assert.deepEqual(row.branch, original);
+    if (status.details.phases[row.phase].status !== "in_progress") await startPhase(h, row.phase);
+    const restarted = await tool.execute("status", { action: "status" }, undefined, undefined, h.ctx) as any;
+    assert.equal(restarted.details.phases[row.phase].substep, row.expected);
+    await h.emitEvent("tool_call", subagentCall("new", { agent: "code-reviewer" }));
+    await h.emitEvent("tool_result", { toolName: "subagent", toolCallId: "new", details: {}, content: [] });
+    assert.deepEqual(row.branch, original);
+  });
+}
+
+for (const event of ["session_start", "session_switch", "session_fork", "session_tree"]) {
+  for (const kind of ["explicit", "derived", "empty"]) {
+    test(`replay ${event} resets live ownership and ordinals: ${kind}`, async () => {
+      const h = harness({ hasUI: true });
+      const tool = h.tools.find(t => t.name === "phase_tracker")!;
+      await startPhase(h, "verify");
+      await h.emitEvent("tool_call", subagentCall("first", { agent: "code-reviewer" }));
+      await h.emitEvent("tool_result", { toolName: "subagent", toolCallId: "first", details: {}, content: [] });
+      await h.emitEvent("tool_call", subagentCall("old", { agent: "code-reviewer" }));
+      assert.match(h.widgets.at(-1)!, /verify\(code-review #2\)/);
+      const branch = kind === "empty" ? [assistant()] : kind === "explicit" ? explicitReplay("verify", "custom") : [phaseResult("start", replaySnapshot("verify")), phaseResult("status", replaySnapshot("verify", "code-review"))];
+      const original = structuredClone(branch);
+      h.setBranch(branch);
+      await h.emit(event);
+      if (kind === "empty") assert.equal(h.widgets.at(-1), undefined);
+      else if (kind === "explicit") assert.match(h.widgets.at(-1)!, /verify\(custom\)/);
+      else assert.doesNotMatch(h.widgets.at(-1)!, /verify\(/);
+      const status = await tool.execute("status", { action: "status" }, undefined, undefined, h.ctx) as any;
+      assert.equal(status.details.phases.verify.substep, kind === "explicit" ? "custom" : undefined);
+      assert.deepEqual(branch, original);
+      const paints = h.widgets.length;
+      await h.emitEvent("tool_result", { toolName: "subagent", toolCallId: "old", details: {}, content: [] });
+      await h.emitEvent("tool_execution_end", { toolName: "subagent", toolCallId: "old", result: { details: {} } });
+      assert.equal(h.widgets.length, paints);
+      if (kind === "empty") await startPhase(h, "verify");
+      await h.emitEvent("tool_call", subagentCall("next", { agent: "code-reviewer" }));
+      assert.match(h.widgets.at(-1)!, /verify\(code-review\)/);
+      await h.emitEvent("tool_result", { toolName: "subagent", toolCallId: "next", details: {}, content: [] });
+      await h.emitEvent("tool_call", subagentCall("again", { agent: "code-reviewer" }));
+      assert.match(h.widgets.at(-1)!, /verify\(code-review #2\)/);
+      assert.deepEqual(branch, original);
+    });
+  }
+}