pi-gauntlet 7.25.1 → 7.27.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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
+
+- **The implement orchestrator honors standing amend grants and per-task fix-round funding.** With amend permission on the spec's `**Amend-grant:**` line, it applies each amend-class item's recommended edit in the same turn instead of presenting an option menu; a redraw still stops. A granting sentence may include `fund N fix rounds` or `N more fix rounds`, giving each task N funded fix rounds past the escalated round. Each funded dispatch prints `funded round <k> of <N> for task <n>`, and every stop note while funding exists carries `budget: <spent> of <N> spent`. A funded `STAGNANT`, error, or non-`DONE` status still stops; unrecoverable spend on resume counts as exhausted. (#74)
+
 ## v7.25.1 - 2026-10-22
 
 ### Changed

package/README.md

@@ -122,7 +122,7 @@ Run by a human against pi-cohort >= 7.1.0, before a pi-gauntlet release claims t
 ## Requirements
 
 - [pi-coding-agent](https://github.com/earendil-works/pi) ≥ 0.85.1 - tested minimum for sequential `phase_tracker` tool execution, which persists a tracker update before a later tool call in the same model message.
-- [pi-cohort](https://github.com/jjuraszek/pi-cohort) >= 7.4.3 - required peer package, including binary-safe worktree patches. Skills that dispatch agents (`requesting-code-review`, `subagent-driven-development`, `dispatching-parallel-agents`, `writing-plans`, `forge-skill`, `shape-ticket`, `roasting-the-spec`) call `subagent({})`, which pi-cohort provides. pi-gauntlet does not vendor the dispatch tool; without pi-cohort those skills have nothing to call. Gauntlet execution dispatches explicitly use `async: false`; do not enable pi-cohort's incompatible `forceTopLevelAsync` setting. See pi-cohort's [dispatch configuration](https://github.com/jjuraszek/pi-cohort/blob/main/doc/configuration.md) for that setting's owner and semantics. A wave of N >= 1 tasks dispatches its implementers and first spec reviews as one chain call. `subagent-driven-development` stops before dispatch on unsupported installs; there is no older-runtime fallback.
+- [pi-cohort](https://github.com/jjuraszek/pi-cohort) >= 7.4.4 - required peer package, including binary-safe worktree patches. Skills that dispatch agents (`requesting-code-review`, `subagent-driven-development`, `dispatching-parallel-agents`, `writing-plans`, `forge-skill`, `shape-ticket`, `roasting-the-spec`) call `subagent({})`, which pi-cohort provides. pi-gauntlet does not vendor the dispatch tool; without pi-cohort those skills have nothing to call. Gauntlet execution dispatches explicitly use `async: false`; do not enable pi-cohort's incompatible `forceTopLevelAsync` setting. See pi-cohort's [dispatch configuration](https://github.com/jjuraszek/pi-cohort/blob/main/doc/configuration.md) for that setting's owner and semantics. A wave of N >= 1 tasks dispatches its implementers and first spec reviews as one chain call. `subagent-driven-development` stops before dispatch on unsupported installs; there is no older-runtime fallback.
 
 Both packages must be listed in your `.pi/settings.json#packages` array (pi adds them automatically when you `pi install`). pi-gauntlet and pi-cohort are versioned independently but release together whenever dispatch semantics change - pin compatible versions of both. At each pi-gauntlet release, set the pi-cohort peer minimum and README floor together to the newest released pi-cohort version; `/skill:release` checks the registry before proceeding.
 

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.25.1",
+  "version": "7.27.0",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",
@@ -62,7 +62,7 @@
     "test": "node scripts/ci.mjs"
   },
   "peerDependencies": {
-    "pi-cohort": ">=7.4.3"
+    "pi-cohort": ">=7.4.4"
   },
   "dependencies": {
     "yaml": "^2.9.0"

package/skills/brainstorming/reference/amendment-surface.md

@@ -19,6 +19,8 @@ A grant is the spec's `**Amend-grant:**` line read through the shared predicate;
 | exactly one line whose trimmed value is any other non-empty single-line text | grant active; the sentence is that value |
 | two or more lines, one line with an empty value, or a value continued onto the next physical line (any non-blank line directly below the field that is neither a `**Key:**` header line nor a `> **Superseded by:**` banner line) | malformed -> stop, print the offending line(s) |
 
+**Value decoding**. Run the structural predicate first; missing or `none` gives neither capability, and malformed lines stop with the offending lines quoted. Decode every active value: section 1 at each batch boundary, SDD Fix-Loop Rounds at each funded dispatch, and `spec-finalization.md` before writing the value. Match exactly one `fund N fix rounds` or `N more fix rounds` anywhere on the line, with N matching `[1-9][0-9]*`; no match funds nothing. Stop and quote the line before any item applies or any round is funded on two or more matches or a token-shaped invalid phrase (`fund 0 fix rounds`, `fund three fix rounds`, `-2 more fix rounds`). Remove the matched token and its `; ` / `, ` separators for amend decoding: a non-empty remainder keeps wording-agnostic amend permission (`auto-apply amends`, `apply spec fixes without asking`, or equivalent); an empty remainder is budget-only, with no amend permission. Keep grants without a budget unchanged. Decode `auto-apply amends; fund 3 fix rounds` as both capabilities and `2 more fix rounds` as budget-only. The budget is non-retroactive: rounds spent before the line was written do not count against or toward it. Write `none` on revocation such as `revoke auto-apply amends`, clearing both capabilities; retain funding alone by writing the token alone.
+
 **Writers.** Spec-writing and the spec gate are owned by `spec-finalization.md`; this file owns the mid-flow changes:
 
 | Event | Edit |
@@ -54,7 +56,7 @@ Collect every amendment pending at this decision point (same spec-review round,
 
 The working tree stays at pre-batch HEAD until apply (section 5) - nothing is edited before the reviewer and, where needed, the human have answered. A redraw item stops alone first (`../SKILL.md` redraw path); amend items are held and re-batched after it resolves.
 
-**Standing grant active** ([boundaries](#standing-grants)): at every batch boundary re-read the spec's `**Amend-grant:**` line through the predicate; malformed stops the batch with the offending line(s). Active -> skip steps 2-4, apply every item, print one line each `amended the spec: <title> - <what>`, record `granted`, and quote the line's value in the commit body - the record kind `finishing-a-development-branch` Step 4's digest reads is unchanged.
+**Standing grant active** ([boundaries](#standing-grants)): at every batch boundary re-read the spec's `**Amend-grant:**` line through the predicate and Value decoding; malformed stops the batch with the offending line(s). Active with amend permission -> skip steps 2-4, apply every item's `recommended` choice (`accept` or its named `alt-n`, never `accept` by default) through section 5, print one line each `amended the spec: <title> - <what>`, record `granted`, and quote the line's value in the commit body - the record kind `finishing-a-development-branch` Step 4's digest reads is unchanged. Budget-only takes ordinary steps 2-4; absent or `none` follows the ordinary path.
 
 ## 2. Prefilter - no model call
 

package/skills/brainstorming/reference/spec-finalization.md

@@ -126,6 +126,7 @@ New predecessor candidates at spec-writing: <path> (<title>), ... - index rows a
 1 - approve: proceed to planning under the existing amendment review; a fresh reviewer applies evidence-backed factual corrections on its own, and every other spec amendment (scope, acceptance-criteria, or contract edits, and redraws) stops for your review.
 2 - approve, auto-apply amends: every later spec amendment in this flow (corrected facts, paths, verification lines, and scope, acceptance-criteria, or public-contract edits alike) applies without asking; only a redraw (changed problem statement, component added, removed, or re-bounded) still stops for you, and the grant never stands in for a spec approval.
 3 - show council dispositions: prints the council audit verbatim, then re-presents this gate. Not an approval.
+Add "; fund N fix rounds" (or "N more fix rounds") to 1 or 2 to fund N implement fix rounds past the escalated round.
 
 Or tell me what to change in the spec, or say "revert applied council edit <X>" to undo a specific applied edit.
 ```
@@ -134,7 +135,20 @@ If you believe the summary needs correcting, do **not** silently rewrite it - re
 
 **Revert valve.** "Revert applied council edit X" is a normal change request: revise the spec to undo edit X, re-dispatch the summarizer with a **fresh** temp path (per the re-dispatch rule below), and re-present the gate. This is cheap here - the spec is not yet plan- or code-bearing.
 
-Wait for the user. On a change request (including a revert), revise the spec and re-present - mint a **fresh** temp path for the re-dispatched summarizer (never reuse a prior round's path, so stale content can never be mistaken for the new summary). On `3` or its label alone: print the audit verbatim from `git -C <abs worktree path> show -s --format=%b HEAD` (never from a held tool result; the body survives the grant's `--amend --no-edit`), then re-present the same gate - the briefing text of the gate message just rendered, reused verbatim (no summarizer re-dispatch, no read of the removed `$SUMMARY_PATH`; if that text is no longer in context, the one-line degrade note takes its place), the `Council:` line, the adjacent lines, the three rows; nothing in the spec or the commit changes. `3` plus a change request is a change request. `3` plus `1`/`2` prints and re-presents, and the approval is read only from a clean `1`/`2` on the re-presented gate - a reply carrying `3` never grants. A gate-round recommit (change request or revert) re-runs the same heredoc commit with the audit as its body, so HEAD always carries it; on a revert of edit X, move X's `Applied:` line to `Rejected:` with `-> reverted at gate` and recompute the `Council:` counts from the revised audit. On approval - `1`, `approve`, or equivalent prose approves without a grant; `2`, `approve, auto-apply amends`, or equivalent prose approves and grants - proceed immediately to `/skill:writing-plans` with no further prompt; first read [Standing grants](amendment-surface.md#standing-grants) (stop if unreadable). On a grant (`2`, `approve, auto-apply amends`, or equivalent prose), `edit` the spec's `**Amend-grant:**` value to the granting sentence (the digit `2` becomes the grant description after `2 - approve, auto-apply amends:` above), then `git -C <abs worktree path> add -- <spec path>` and `git -C <abs worktree path> commit --amend --no-edit -q`, so the spec commit carries the line and keeps its council-audit body; then confirm `git -C <abs worktree path> show HEAD:<spec path>` reads "grant active" through the predicate. On a plain approval (`1`, `approve`) the value stays `none` and the commit is untouched. A reply that mixes approval with a change request ("2 but rename the section") is a change request: revise, re-present, and read the grant only from the reply to the re-presented gate. If the amend or the HEAD check fails, stop and report; never proceed as granted. The plan and execution mode are mechanical derivatives, so the only human gate here is spec approval itself. Don't land the spec on `main`; it stays in the worktree and ships in the same squash commit as the implementation.
+Wait for the user. Interpret funded replies with this table before routing change requests:
+
+| Reply | Action / written value |
+|---|---|
+| bare `2` | approve; persist the option-2 description above |
+| `2; fund 3 fix rounds` or `2, fund 3 fix rounds` | approve; persist that description plus `; fund 3 fix rounds`, not a change request |
+| `1` with a budget token | approve; persist `fund 3 fix rounds` alone for that token (budget-only) |
+| approval prose with a token | approve; preserve the prose collapsed to one physical line |
+| budget token alone (`fund 3 fix rounds`) | re-present the gate asking for `1` or `2`; write nothing |
+| token with malformed N | re-present the gate quoting the token; write nothing, never imply a change request |
+
+For every value to persist, read [Standing grants](amendment-surface.md#standing-grants) and run Value decoding. Decode before `edit` or `--amend`; never persist a malformed token. Use the decoded table value in the approval persistence below, including budget-only approvals.
+
+On a change request (including a revert), revise the spec and re-present - mint a **fresh** temp path for the re-dispatched summarizer (never reuse a prior round's path, so stale content can never be mistaken for the new summary). On `3` or its label alone: print the audit verbatim from `git -C <abs worktree path> show -s --format=%b HEAD` (never from a held tool result; the body survives the grant's `--amend --no-edit`), then re-present the same gate - the briefing text of the gate message just rendered, reused verbatim (no summarizer re-dispatch, no read of the removed `$SUMMARY_PATH`; if that text is no longer in context, the one-line degrade note takes its place), the `Council:` line, the adjacent lines, the three rows; nothing in the spec or the commit changes. `3` plus a change request is a change request. `3` plus `1`/`2` prints and re-presents, and the approval is read only from a clean `1`/`2` on the re-presented gate - a reply carrying `3` never grants. A gate-round recommit (change request or revert) re-runs the same heredoc commit with the audit as its body, so HEAD always carries it; on a revert of edit X, move X's `Applied:` line to `Rejected:` with `-> reverted at gate` and recompute the `Council:` counts from the revised audit. On approval - `1`, `approve`, or equivalent prose approves without a grant; `2`, `approve, auto-apply amends`, or equivalent prose approves and grants - proceed immediately to `/skill:writing-plans` with no further prompt; first read [Standing grants](amendment-surface.md#standing-grants) (stop if unreadable). On a grant or funded approval, `edit` the spec's `**Amend-grant:**` value to the table value for funded replies, otherwise the granting sentence (the digit `2` becomes the grant description after `2 - approve, auto-apply amends:` above), then `git -C <abs worktree path> add -- <spec path>` and `git -C <abs worktree path> commit --amend --no-edit -q`, so the spec commit carries the line and keeps its council-audit body; then confirm `git -C <abs worktree path> show HEAD:<spec path>` reads "grant active" through the predicate. On a plain approval (`1`, `approve`) the value stays `none` and the commit is untouched. A reply that mixes approval with a change request ("2 but rename the section") is a change request: revise, re-present, and read the grant only from the reply to the re-presented gate. If the amend or the HEAD check fails, stop and report; never proceed as granted. The plan and execution mode are mechanical derivatives, so the only human gate here is spec approval itself. Don't land the spec on `main`; it stays in the worktree and ships in the same squash commit as the implementation.
 
 Post-approval changes follow [Amending an approved spec](../SKILL.md#amending-an-approved-spec).
 

package/skills/subagent-driven-development/SKILL.md

@@ -30,7 +30,7 @@ You are the **orchestrator**. You read the plan, dispatch, review the review, de
 **Do not pause to check in with the user between tasks.** The plan is already approved. Pause only when:
 
 - A subagent returns `NEEDS_CONTEXT` or `BLOCKED` (see [Implementer Status](#implementer-status))
-- An escalated round fails (stop note per [Fix-Loop Rounds](#fix-loop-rounds))
+- An escalated round fails with no funded round left (stop note per [Fix-Loop Rounds](#fix-loop-rounds))
 - A ⚠️ workflow warning fires
 
 Reaching the end of the plan is not a pause: continue through verification and invoke `/skill:finishing-a-development-branch <abs worktree path>` as defined in [After All Tasks](#after-all-tasks-complete).
@@ -45,7 +45,7 @@ Periodic "should I continue?" prompts add latency without adding safety. The pla
 
 Extract **`SCOPED_TEST_COMMANDS`** from the task's `**Tests:**` command bullets, backticks stripped, one per line; `- none:` -> `none`; a wave = the union of its tasks' commands. Treat `via:` and `baseline:` bullets and `- Test:` paths as contract, not commands: carry them with the task text, never in `SCOPED_TEST_COMMANDS`.
 
-Keep the orchestrator as the spec's only writer during execution. On implementer `BLOCKED` citing a spec defect, or a review finding showing the spec (not the code) is wrong, pause the fix loop, read and execute brainstorming's [amendment path](../brainstorming/SKILL.md#amending-an-approved-spec) in place (it reviews first, stops only on escalation or redraw), then resume. Keep code-vs-spec mismatch in the SR loop. Require an SR unable to read the spec at a cited anchor (missing file, unresolvable heading/range) to return a blocking finding - the contract is spec+task or stop, never a silent fallback to task-only review.
+Keep the orchestrator as the spec's only writer during execution. On implementer `BLOCKED` citing a spec defect, or a review finding showing the spec (not the code) is wrong, pause the fix loop, read and execute brainstorming's [amendment path](../brainstorming/SKILL.md#amending-an-approved-spec) in place (it reviews first; with amend permission on the `**Amend-grant:**` line it applies amends without a stop and still stops on a redraw; without permission it stops on escalation or redraw), then resume. Keep code-vs-spec mismatch in the SR loop. Require an SR unable to read the spec at a cited anchor (missing file, unresolvable heading/range) to return a blocking finding - the contract is spec+task or stop, never a silent fallback to task-only review.
 
 ## Fix-Loop Rounds
 
@@ -68,7 +68,7 @@ Every fix re-dispatch (implementer) and code-review re-review carries the consum
 
 Every dispatched fix is verified by a re-review before escalation or task progression - the loop only ever exits on a clean review or an escalation.
 
-**Escalate** = one escalated round; stop only on failure. Call `gauntlet_setting({ key: "escalationLoop" })` (unavailable -> stop and report). `implModel` undefined -> stop note. Otherwise re-dispatch that fix - same payload and isolation knobs (`cwd`, `worktree`, `SCOPED_TEST_COMMANDS`, status protocol, prior patch, spec anchors) plus the prior report verbatim - overriding only `model: <implModel>`, `context: "fresh"`, `async: false`; one implementer, no fan-out. Run the normal fix-round review gate (SR then CR on `Behaviour-change: yes`, else the triggering reviewer with the re-review marker). All clean -> proceed; the escalated patch supersedes the prior one at integrate. Any review with issues, a non-`DONE` status, or a dispatch error -> stop note per `stop-note.md`; no second dispatch. Once per loop; independent of the convergence exception. No `plan_tracker` write during escalation - the task stays `in_progress` until the human decides.
+Read [reference/fix-loop.md](./reference/fix-loop.md) now for escalation and funded-round dispatch rules.
 
 **Worked examples:**
 
@@ -103,10 +103,10 @@ Every implementer dispatch returns one of:
 |---|---|---|
 | `DONE` | Implemented + tests pass + self-reviewed; work present in the worker's tree; the wave commit is step 7 | Proceed to spec review |
 | `DONE_WITH_CONCERNS` | Implemented + tests pass, but flagged a deviation or risk | Read concerns. If acceptable, proceed. If not, dispatch fix subagent. |
-| `NEEDS_CONTEXT` | Implementer needs information you have | Resolve fact asks per [lookup handling](./stop-note.md). For decisions, answer and re-dispatch with answers in the task text, or escalate to the user. |
-| `BLOCKED` | Cannot proceed (missing dependency, spec contradicts code, environment broken) | Resolve fact asks per [lookup handling](./stop-note.md). For decisions, stop and diagnose: fix the orchestration-level issue and re-dispatch, or escalate to the user. |
+| `NEEDS_CONTEXT` | Implementer needs information you have | For a spec-defect citation, take the amendment route below first. Resolve fact asks per [lookup handling](./stop-note.md). For decisions, answer and re-dispatch with answers in the task text, or escalate to the user. |
+| `BLOCKED` | Cannot proceed (missing dependency, spec contradicts code, environment broken) | For a spec-defect citation, take the amendment route below first. Resolve fact asks per [lookup handling](./stop-note.md). For decisions, stop and diagnose: fix the orchestration-level issue and re-dispatch, or escalate to the user. |
 
-Classify each question: artifact location, value, or existence is a fact ask; scope choices, option choices, and another-round approval are decisions.
+Classify each question: treat a question whose candidate answers are each edits to the spec, plan, or an approved rule as an amendment batch per [amendment-surface.md](../brainstorming/reference/amendment-surface.md), never a decision. Stop for a redraw: changed problem statement; component added, removed, or re-bounded. Decode the `**Amend-grant:**` value through that surface's Standing grants. With amend permission, apply each item's `recommended` (`accept` or named `alt-n`), print `amended the spec: <title> - <what>`, and complete section 5's plan-writer amend dispatch, `plan_check`, tracker update, and one `amend:` commit in the same turn; skip reviewer, menu, and confirmation turns. Without permission (including absent or `none`), retain the surface's menu and escalation/redraw routing. For remaining questions, classify artifact location, value, or existence as a fact ask; scope and option choices as decisions; another-round approval as a decision only with no funded round left.
 
 Implementer prompt templates must instruct subagents to return one of these statuses explicitly.
 
@@ -305,7 +305,7 @@ git -C "$SR_TREE" apply --index "$SR_PATCH" || exit 1
 printf 'snapshot: %s\n' "$SR_TREE"
 ```
 
-Record its review tree per [Fix delta](#fix-delta) before every parent-dispatched SR, keyed by task. Use the printed snapshot path as that spec-review task's `cwd` and whole-file read root. Keep the authoritative spec's absolute path in the implementation worktree. Pass the patch diff as before; the snapshot contains this task's changed and added files, with deleted files absent. Read deleted files from `WAVE_BASE_SHA` when the review needs their prior contents. Dispatch read-only, with no `worktree` flag. On snapshot setup or tree-capture failure, or a missing snapshot path, stop dispatch and retain the failed snapshot directory and shell output for diagnosis; dispatch no review and perform no snapshot cleanup. Save each snapshot-backed review's terminal report to its `output:` path, read it, then remove that review's snapshot with `git -C <implementation-worktree> worktree remove --force <snapshot-path>`. Keep every snapshot used as a reviewer `cwd` until that terminal report is saved; recording its tree never authorizes early cleanup. Remove a reconstruction used only to record tree-before after capturing its tree, since no reviewer runs there. Recreate from the replacement patch for each pre-integration re-review. Post-integration SR reviews the implementation worktree directly.
+Record its review tree per [Fix delta](#fix-delta) before every parent-dispatched SR, keyed by task. Use the printed snapshot path as that spec-review task's `cwd` and whole-file read root. Keep the authoritative spec's absolute path in the implementation worktree. Pass the patch diff as before; the snapshot contains this task's changed and added files, with deleted files absent. Read deleted files from `WAVE_BASE_SHA` when the review needs their prior contents. Dispatch read-only, with no `worktree` flag. On snapshot setup or tree-capture failure, or a missing snapshot path, stop dispatch and retain the failed snapshot directory and shell output for diagnosis; dispatch no review and perform no snapshot cleanup. Save each snapshot-backed review's terminal report to its `output:` path, read it, then remove that review's snapshot with `git -C <implementation-worktree> worktree remove --force <snapshot-path>`. Keep every snapshot used as a reviewer `cwd` until that terminal report is saved; recording its tree never authorizes early cleanup. Remove a reconstruction used only to record tree-before after capturing its tree, since no reviewer runs there. Recreate from the replacement patch for each pre-integration re-review; on a failed recreate, stop dispatch and retain that snapshot directory and shell output, like any setup failure. Post-integration SR reviews the implementation worktree directly.
 
 ## When a Subagent Fails
 
@@ -338,13 +338,13 @@ Record its review tree per [Fix delta](#fix-delta) before every parent-dispatche
 ## Red Flags — STOP
 
 - Writing code yourself instead of dispatching.
-- Pausing between tasks for anything other than `NEEDS_CONTEXT`, `BLOCKED`, a fix-loop escalation, a workflow warning, or a spec amendment.
+- Pausing between tasks for anything other than `NEEDS_CONTEXT`, `BLOCKED`, a fix-loop escalation, a workflow warning, a redraw, or an amend with no standing grant.
 - Dispatching parallel implementers on overlapping files, on a shared mutable runtime resource, or without `worktree: true`.
 - Making a subagent read the plan, inlining spec excerpts to the spec reviewer, or dispatching with a `SCOPED_TEST_COMMANDS` value missing or not copied from the plan's `Tests:` bullets.
 - Dispatching `code-reviewer` before every in-scope spec-review verdict is ✅, or per task inside a wave.
 - Moving to the next task with either review still showing issues, or skipping the `Implementer Status` parse.
 - Second chain call in the same wave after a stop or a chain error - the retained results are the fan-out result; continue on the snapshot path.
-- Dispatching fix 3 without a reviewer-emitted `CONVERGING` verdict, or continuing past `STAGNANT` instead of escalating.
+- Dispatching fix 3 without a reviewer-emitted `CONVERGING` verdict, or continuing past `STAGNANT` instead of escalating (or, on a funded re-review, stopping).
 - Running the full verification entrypoint, or any test command outside `SCOPED_TEST_COMMANDS`, during the implement phase.
 - Dispatching a repair before reopening the plan-task indices that own its files, whole-diff CR before parent verification passes, or conformance before the CR result is accepted.
 - Polling, joining, or relaunching an unexpectedly asynchronous dispatch, or starting on main without explicit user consent.

package/skills/subagent-driven-development/reference/fix-loop.md

@@ -0,0 +1,23 @@
+# Escalated fix rounds
+
+**Escalate** = one escalated round; stop only on failure. Call `gauntlet_setting({ key: "escalationLoop" })` (unavailable -> stop and report). `implModel` undefined -> stop note. Otherwise re-dispatch that fix - same payload and isolation knobs (`cwd`, `worktree`, `SCOPED_TEST_COMMANDS`, status protocol, prior patch, spec anchors) plus the prior report verbatim - overriding only `model: <implModel>`, `context: "fresh"`, `async: false`; one implementer, no fan-out. Run the normal fix-round review gate (SR then CR on `Behaviour-change: yes`, else the triggering reviewer with the re-review marker). All clean -> proceed; the escalated patch supersedes the prior one at integrate. A non-`DONE` status or a dispatch error -> stop note per `stop-note.md`. A review with issues -> a funded round while one remains for the task (below), otherwise stop note; no other second dispatch. Once per loop; independent of the convergence exception. No `plan_tracker` write during escalation - keep the task `in_progress` until the wave commit or, on a stop, the human decides.
+
+## Funded rounds
+
+Decode the current `**Amend-grant:**` line using **Value decoding** in [Standing grants](../../brainstorming/reference/amendment-surface.md#standing-grants) before each funded dispatch. Funding is independent of ordinary fixes and the escalated round; it never supplies a missing `implModel`, another escalation grant, verify credits, or `grant_fix_rounds`. Keep the review-3 convergence exception once per loop; never re-arm it through funding.
+
+Start one per-task ledger at zero when each task first enters Fix-Loop Rounds. Carry it across SR, behavior-change reroutes, the SR-to-CR transition, and wave repairs re-entering SR; use no wave-level allowance. Determine touched owners using the SR targeting rule (tasks whose files the fix touches). For a multi-task CR repair, spend once from every touched task; a touched exhausted owner stops the wave with that task's stop note before dispatch.
+
+Before every funded dispatch, print `funded round <k> of <N> for task <n>` for each touched task. Apply mid-loop grants prospectively, with spent starting at zero: rounds before the token was written neither count against nor toward it. Repeat the escalated payload and isolation exactly: configured `model: <implModel>` from `escalationLoop`, `context: "fresh"`, `async: false`, one implementer, no fan-out, same `cwd`/`worktree`, task text, prior patch, spec anchors, status protocol, `SCOPED_TEST_COMMANDS`, and complete prior report verbatim. Run the same tests and same review gate: SR then CR on `Behaviour-change: yes`, otherwise the triggering reviewer with the re-review marker, trajectory block and Fix delta. Every dispatched round spends one, including failures.
+
+| Funded outcome | Action |
+|---|---|
+| Errors and non-`DONE` | Count as spent and stop with the task's stop note. |
+| Any funded re-review reports `STAGNANT` | Stop immediately regardless of funding remaining. |
+| Issue-bearing re-review with rounds left | Dispatch the next funded round. |
+| Issue-bearing re-review after N rounds | Stop with the exhausted task's stop note. |
+| All reviews clean | Continue through the wave gate and commit before task completion. |
+
+Emit the task's stop note for the funded-stop outcomes above (including `STAGNANT`) and an escalated-round failure with no funded round left. While a budget token exists, include `budget: <spent> of <N> spent` in every stop note after `Problem:` and any `Searched:` lines and before the file finding, including pre-escalation stops, missing `implModel`, and exhausted fact lookups at spent zero; use the `(not recovered on resume)` suffix below when recovery fails, and omit the line without a token. Treat this line as the only round-history exception to `stop-note.md`'s no-round-history rule.
+
+On resume, keep header restoration unchanged; recover each task's spent count only from its `funded round <k> of <N>` transcript lines. Without recoverable lines, treat funding as exhausted; stop the next issue-bearing re-review with `budget: <N> of <N> spent (not recovered on resume)`. Treat a newly written budget token as the human refund, never a resume reset. Use no new spent carrier or handoff/resume grammar.