pi-gauntlet 7.26.0 → 7.27.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 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/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);
+    });
+  }
+}

package/extensions/phase-tracker.ts

@@ -31,6 +31,7 @@ import { checkoutOf, gitSync } from "./lib/checkout.ts";
 import { checkPlan, sha256, type FsPort, type PlanCheckFinding } from "./lib/plan-check.ts";
 import {
   checkSubstep,
+  dispatchLabel,
   findMarkerFile,
   flowGuardApplies,
   implementExemptDirs,
@@ -354,10 +355,11 @@ function hasActivity(phases: PhaseMap): boolean {
   return PHASES.some((p) => phases[p].status !== "pending");
 }
 
-function formatWidget(phases: PhaseMap, theme: Theme): string {
+function formatWidget(phases: PhaseMap, dispatchCounts: Record<Phase, Record<string, number>>, theme: Theme): string {
   const parts = PHASES.map((p) => {
     const icon = phaseIcon(phases[p].status, theme);
-    const labeled = phaseLabel(p, phases[p].status === "in_progress" ? phases[p].substep : undefined);
+    const substep = phases[p].status === "in_progress" ? phases[p].substep : undefined;
+    const labeled = phaseLabel(p, substep, dispatchCounts[p][substep ?? ""] ?? 0);
     const name = phases[p].status === "skipped" ? theme.fg("dim", labeled) : labeled;
     return `${icon} ${name}`;
   });
@@ -422,6 +424,31 @@ async function applyPhaseModel(
 export default function (pi: ExtensionAPI) {
   let phases: PhaseMap = emptyPhases();
   let conformanceDispatched = false;
+  let dispatchCounts = Object.fromEntries(PHASES.map((p) => [p, {}])) as Record<Phase, Record<string, number>>;
+  let liveDispatch: { toolCallId: string; phase: Phase; label: string } | undefined;
+  const observeDispatch = (toolName: string, input: unknown, toolCallId: string): boolean => {
+    if (isSubagentChild) return false;
+    const label = dispatchLabel(toolName, input);
+    const phase = PHASES.find((p) => phases[p].status === "in_progress");
+    if (label === undefined || phase === undefined) return false;
+    dispatchCounts[phase][label] = (dispatchCounts[phase][label] ?? 0) + 1;
+    phases = { ...phases, [phase]: { ...phases[phase], substep: label } };
+    liveDispatch = { toolCallId, phase, label };
+    return true;
+  };
+  const isNonDispatchResult = (isError: boolean | undefined, details: unknown): boolean =>
+    isError === true && details !== null && typeof details === "object" && Object.keys(details).length === 0;
+  const finishDispatch = (toolName: string, toolCallId: string, isError: boolean | undefined, details: unknown): boolean => {
+    if ((toolName !== "subagent" && toolName !== "plan_check") || liveDispatch?.toolCallId !== toolCallId) return false;
+    const { phase, label } = liveDispatch;
+    if (isNonDispatchResult(isError, details)) dispatchCounts[phase][label] -= 1;
+    if (phases[phase].substep === label) {
+      const { substep: _substep, ...entry } = phases[phase];
+      phases = { ...phases, [phase]: entry };
+    }
+    liveDispatch = undefined;
+    return true;
+  };
   let fixRounds = 0;
   let fixRoundCredits = 0;
   let gauntletEntered = false;
@@ -493,6 +520,7 @@ export default function (pi: ExtensionAPI) {
       tasks.every((t) => t.status === "complete" || t.status === "skipped")
     ) {
       phases = { ...phases, implement: { status: "complete" } };
+      liveDispatch = undefined;
       firedGuards.clear();
     }
   };
@@ -507,6 +535,9 @@ export default function (pi: ExtensionAPI) {
 
   const reconstructState = (ctx: ExtensionContext) => {
     phases = emptyPhases();
+    dispatchCounts = Object.fromEntries(PHASES.map((p) => [p, {}])) as Record<Phase, Record<string, number>>;
+    liveDispatch = undefined;
+    let explicitSubstep: Partial<Record<Phase, string>> = {};
     conformanceDispatched = false;
     fixRounds = 0;
     fixRoundCredits = 0;
@@ -533,6 +564,23 @@ export default function (pi: ExtensionAPI) {
       if (msg.toolName === "phase_tracker") {
         const details = msg.details as PhaseTrackerDetails | undefined;
         if (details && !details.error) {
+          if (details.action === "substep") {
+            const phase = PHASES.find((p) => details.phases[p].status === "in_progress");
+            if (phase !== undefined) {
+              const label = details.phases[phase].substep;
+              if (label !== undefined) explicitSubstep[phase] = label;
+              else delete explicitSubstep[phase];
+            }
+          } else if (details.action === "start" || details.action === "complete" || details.action === "skip") {
+            const changed = PHASES.filter((p) => phases[p].status !== details.phases[p].status);
+            if (changed.length === 0 && details.action === "start") {
+              const phase = PHASES.find((p) => details.phases[p].status === "in_progress");
+              if (phase !== undefined) delete explicitSubstep[phase];
+            }
+            for (const phase of changed) delete explicitSubstep[phase];
+          } else if (details.action === "reset") {
+            explicitSubstep = {};
+          }
           phases = details.phases;
           if (details.action === "grant_fix_rounds" && typeof details.rounds === "number") fixRoundCredits = details.rounds;
           gauntletEntered = nextGauntletEntered(gauntletEntered, details.action, details.phases.brainstorm.status);
@@ -561,9 +609,18 @@ export default function (pi: ExtensionAPI) {
         observeCadence(msg.details);
       } else if (msg.toolName === "plan_tracker") {
         const details = msg.details as { tasks?: { status: string }[]; error?: string } | undefined;
-        if (details && !details.error) applyPlanActivity(details.tasks);
+        if (details && !details.error) {
+          const wasImplementing = phases.implement.status === "in_progress";
+          applyPlanActivity(details.tasks);
+          if (wasImplementing && phases.implement.status === "complete") delete explicitSubstep.implement;
+        }
       }
     }
+    phases = Object.fromEntries(PHASES.map((phase) => {
+      const { substep: _substep, ...entry } = phases[phase];
+      const label = explicitSubstep[phase];
+      return [phase, label === undefined ? entry : { ...entry, substep: label }];
+    })) as PhaseMap;
   };
 
   const updateWidget = (ctx: ExtensionContext) => {
@@ -572,7 +629,7 @@ export default function (pi: ExtensionAPI) {
       ctx.ui.setWidget("phase_tracker", undefined);
     } else {
       ctx.ui.setWidget("phase_tracker", (_tui, theme) => {
-        return new Text(formatWidget(phases, theme), 0, 0);
+        return new Text(formatWidget(phases, dispatchCounts, theme), 0, 0);
       });
     }
   };
@@ -657,6 +714,8 @@ export default function (pi: ExtensionAPI) {
       }
     }
 
+    if (observeDispatch(event.toolName, event.input, event.toolCallId)) updateWidget(ctx);
+
     // Flow guards apply only to write/edit/bash while a guard phase is active.
     // Cheap in-memory gate BEFORE any settings load: phase state is in-memory, so an
     // event no guard inspects (any read-only tool, or any tool in a dormant session)
@@ -782,6 +841,7 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.on("tool_result", async (event, ctx) => {
+    if (finishDispatch(event.toolName, event.toolCallId, event.isError, event.details)) updateWidget(ctx);
     if (event.toolName === "subagent") {
       observeFixWave(event.details, event.isError, ctx);
       if (qualifiesAsClosureDispatch(event.details)) conformanceDispatched = true;
@@ -818,6 +878,8 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.on("tool_execution_end", async (event, ctx) => {
+    const resultDetails = (event.result as { details?: unknown } | undefined)?.details;
+    if (finishDispatch(event.toolName, event.toolCallId, event.isError, resultDetails)) updateWidget(ctx);
     if (event.toolName !== "plan_tracker" || event.isError) return;
     const details = (event.result as { details?: { tasks?: { status: string }[]; error?: string } } | undefined)
       ?.details;
@@ -1032,6 +1094,8 @@ export default function (pi: ExtensionAPI) {
             const target = resolved.phaseModels[phase];
             if (target) startLines.push(...(await applyPhaseModel(pi, ctx, phase, target)));
           }
+          if (liveDispatch?.phase === params.phase) liveDispatch = undefined;
+          dispatchCounts[params.phase] = {};
           phases = { ...phases, [params.phase]: transitionPhaseState("in_progress") as PhaseState };
           // A rewind must not inherit the prior verify's conformance latch.
           if (params.phase === "implement") {
@@ -1102,6 +1166,7 @@ export default function (pi: ExtensionAPI) {
               };
             }
           }
+          if (liveDispatch?.phase === params.phase) liveDispatch = undefined;
           phases = { ...phases, [params.phase]: transitionPhaseState("complete") as PhaseState };
           firedGuards.clear();
           updateWidget(ctx);
@@ -1134,6 +1199,7 @@ export default function (pi: ExtensionAPI) {
             };
           }
           const reason = params.reason;
+          if (liveDispatch?.phase === params.phase) liveDispatch = undefined;
           phases = { ...phases, [params.phase]: transitionPhaseState("skipped", reason) as PhaseState };
           firedGuards.clear();
           updateWidget(ctx);
@@ -1180,6 +1246,8 @@ export default function (pi: ExtensionAPI) {
         }
 
         case "reset": {
+          liveDispatch = undefined;
+          dispatchCounts = Object.fromEntries(PHASES.map((p) => [p, {}])) as Record<Phase, Record<string, number>>;
           phases = Object.fromEntries(
             PHASES.map((p) => [p, transitionPhaseState("pending")]),
           ) as PhaseMap;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "7.26.0",
+  "version": "7.27.0",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",