import assert from "node:assert/strict"; import { after, mock, test } from "node:test"; import childProcess, { execFileSync } from "node:child_process"; import fs from "node:fs"; import { syncBuiltinESMExports } from "node:module"; import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, realpathSync } from "node:fs"; import { createHash } from "node:crypto"; import { tmpdir } from "node:os"; import { isAbsolute, join } from "node:path"; import registerPhaseTracker from "./phase-tracker.ts"; import registerPlanTracker from "./plan-tracker.ts"; import { mergeToolResult } from "./test-support/merge-tool-result.mjs"; const originalSubagentDepth = process.env.PI_SUBAGENT_DEPTH; process.env.PI_SUBAGENT_DEPTH = "0"; const tempDirs: string[] = []; after(() => { for (const dir of tempDirs) rmSync(dir, { recursive: true, force: true }); if (originalSubagentDepth === undefined) delete process.env.PI_SUBAGENT_DEPTH; else process.env.PI_SUBAGENT_DEPTH = originalSubagentDepth; }); const tempCwd = (settings?: unknown) => { const dir = mkdtempSync(join(tmpdir(), "phase-tracker-test-")); tempDirs.push(dir); if (settings !== undefined) { mkdirSync(join(dir, ".pi"), { recursive: true }); writeFileSync(join(dir, ".pi", "settings.json"), JSON.stringify(settings)); } return dir; }; // Primary checkout with one linked worktree at .worktrees/x. Real git: plan_check and Guard 2 // resolve checkouts with gitSync, and macOS temp paths need realpath to compare toplevels. const gitPrimary = () => { const primary = realpathSync(tempCwd()); const git = (...args: string[]) => execFileSync("git", ["-C", primary, ...args], { stdio: "pipe" }); git("init", "-q"); git("-c", "user.email=t@example.com", "-c", "user.name=t", "commit", "-q", "--allow-empty", "-m", "init"); mkdirSync(join(primary, "doc")); git("worktree", "add", "-q", join(primary, ".worktrees", "x"), "-b", "x"); return { primary, worktree: join(primary, ".worktrees", "x") }; }; const PHASES = ["brainstorm", "plan", "implement", "verify", "ship"] as const; type Phase = (typeof PHASES)[number]; type Status = "pending" | "in_progress" | "complete" | "skipped"; const phases = (overrides: Partial> = {}) => Object.fromEntries(PHASES.map((phase) => [phase, { status: overrides[phase] ?? "pending" }])) as Record< Phase, { status: Status; substep?: string } >; const phaseResult = (action: string, state: Record) => ({ 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, extra: unknown[] = []) => [ phaseResult("start", phases({ brainstorm: "in_progress" })), phaseResult("complete", state), ...extra, ]; const resumedBranch = (rest: Partial>) => [ phaseResult("start", phases({ brainstorm: "in_progress" })), phaseResult("skip", phases({ brainstorm: "skipped" })), phaseResult("start", phases({ brainstorm: "skipped", plan: "in_progress" })), phaseResult("complete", phases({ brainstorm: "skipped", ...rest })), ]; type TestModel = { provider: string; id: string }; 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; setModelResult?: boolean | Error } = {}) { const handlers = new Map unknown)[]>(); const tools: { name: string; exposure?: 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: 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, thinkingLevel: options.thinkingLevel, modelRegistry: { find: (provider: string, id: string) => options.registry?.[`${provider}/${id}`] }, }; const pi = { calls: [] as string[], setModelCalls: [] as unknown[], thinkingCalls: [] as string[], async setModel(model: TestModel) { pi.calls.push("setModel"); pi.setModelCalls.push(model); if (options.setModelResult instanceof Error) throw options.setModelResult; const ok = options.setModelResult ?? true; if (ok) ctx.model = model; return ok; }, setThinkingLevel(level: string) { pi.calls.push("setThinkingLevel"); pi.thinkingCalls.push(level); }, on(event: string, handler: (event: unknown, context: unknown) => unknown) { const registered = handlers.get(event) ?? []; registered.push(handler); handlers.set(event, registered); }, registerTool(tool: { name: string; exposure?: string; executionMode?: string; parameters?: any; execute: (...args: any[]) => unknown }) { tools.push(tool); }, sendMessage(message: unknown, sendOptions: unknown) { sent.push({ message, options: sendOptions }); if (options.sendThrows) throw new Error("send failed"); }, }; if (options.beforeSettled) pi.on("agent_settled", () => options.beforeSettled!(next => (idle = next))); registerPhaseTracker(pi as any); const emit = async (event: string) => { for (const handler of handlers.get(event) ?? []) await handler({ type: event }, ctx); }; const emitEvent = async (name: string, event: unknown) => { const results: unknown[] = []; for (const handler of handlers.get(name) ?? []) results.push(await handler(event, ctx)); return results; }; return { pi, emit, emitEvent, sent, tools, ctx, widgets, setIdle: (next: boolean) => (idle = next), setBranch: (next: unknown[]) => (branch = next) }; } const settle = async (h: ReturnType) => { await h.emit("session_start"); await h.emit("agent_settled"); }; const startPhase = async (h: ReturnType, phase: string) => { const tool = h.tools.find((t) => t.name === "phase_tracker")!; const r = (await tool.execute("id", { action: "start", phase }, undefined, undefined, h.ctx)) as { content: { text: string }[]; details: { phases: Record } }; return { text: r.content.map((c) => c.text).join("\n"), status: r.details.phases[phase].status }; }; const M = (id: string) => ({ provider: "p", id }); const preparePhase = async (h: ReturnType, phase = "plan") => { await settle(h); const tool = h.tools.find((t) => t.name === "phase_tracker")!; for (const prior of phase === "implement" ? ["brainstorm", "plan"] : ["brainstorm"]) { await startPhase(h, prior); await tool.execute("id", { action: "complete", phase: prior }, undefined, undefined, h.ctx); } }; test("phaseModels: switch applies thinking and reports the old and new model", async () => { const h = harness({ cwd: tempCwd({ piGauntlet: { phaseModels: { plan: "p/m:medium" } } }), model: M("old"), thinkingLevel: "high", registry: { "p/m": M("m") } }); await preparePhase(h); const r = await startPhase(h, "plan"); assert.deepEqual(h.pi.setModelCalls, [M("m")]); assert.deepEqual(h.pi.thinkingCalls, ["medium"]); assert.deepEqual(h.pi.calls, ["setModel", "setThinkingLevel"]); assert.match(r.text, /model: p\/old:high -> p\/m:medium/); assert.equal(r.status, "in_progress"); }); for (const row of [ { name: "unknown model", target: "p/nope", warning: /phaseModels\.plan: model p\/nope not found in the registry/, calls: 0 }, { name: "unknown thinking suffix", target: "p/m:turbo", warning: /":turbo" is not a pi thinking level \(off\|minimal\|low\|medium\|high\|xhigh\|max\)/, calls: 0 }, { name: "colon model id", target: "p/a:b", warning: undefined, calls: 1 }, { name: "missing auth", target: "p/m", result: false, warning: /cannot switch to p\/m - no auth configured for p/, calls: 1 }, { name: "auth exception", target: "p/m", result: new Error("No API key for p"), warning: /cannot switch to p\/m - No API key for p/, calls: 1 }, ]) { test(`phaseModels: ${row.name} still starts the phase`, async () => { const h = harness({ cwd: tempCwd({ piGauntlet: { phaseModels: { plan: row.target } } }), model: M("old"), registry: { "p/m": M("m"), "p/a:b": M("a:b") }, setModelResult: row.result }); await preparePhase(h); const r = await startPhase(h, "plan"); assert.equal(h.pi.setModelCalls.length, row.calls); assert.deepEqual(h.pi.thinkingCalls, []); if (row.warning) assert.match(r.text, row.warning); else assert.doesNotMatch(r.text, /phaseModels\.plan:/); assert.equal(r.status, "in_progress"); }); } for (const row of [ { target: "p/m:high", levels: ["high"], line: /thinking: medium -> high/ }, { target: "p/m:medium", levels: [], line: undefined }, { target: "p/m", levels: [], line: undefined }, ]) { test(`phaseModels: active target ${row.target} never reselects the model`, async () => { const h = harness({ cwd: tempCwd({ piGauntlet: { phaseModels: { plan: row.target } } }), model: M("m"), thinkingLevel: "medium", registry: { "p/m": M("m") } }); await preparePhase(h); const r = await startPhase(h, "plan"); assert.deepEqual(h.pi.setModelCalls, []); assert.deepEqual(h.pi.thinkingCalls, row.levels); if (row.line) assert.match(r.text, row.line); else assert.doesNotMatch(r.text, /model:|thinking:/); assert.equal(r.status, "in_progress"); }); } test("phaseModels: child sessions neither switch nor warn", async () => { const depth = process.env.PI_SUBAGENT_DEPTH; process.env.PI_SUBAGENT_DEPTH = "1"; try { const h = harness({ cwd: tempCwd({ piGauntlet: { phaseModels: { plan: "p/nope" } } }) }); await preparePhase(h); const r = await startPhase(h, "plan"); assert.deepEqual(h.pi.setModelCalls, []); assert.deepEqual(h.pi.thinkingCalls, []); assert.doesNotMatch(r.text, /phaseModels/); assert.equal(r.status, "in_progress"); } finally { if (depth === undefined) delete process.env.PI_SUBAGENT_DEPTH; else process.env.PI_SUBAGENT_DEPTH = depth; } }); test("phaseModels: resolver warnings appear only for their phase", async () => { const h = harness({ cwd: tempCwd({ piGauntlet: { phaseModels: { plan: 5 } } }) }); await settle(h); assert.doesNotMatch((await startPhase(h, "brainstorm")).text, /phaseModels/); await h.tools.find(t => t.name === "phase_tracker")!.execute("id", { action: "complete", phase: "brainstorm" }, undefined, undefined, h.ctx); const r = await startPhase(h, "plan"); assert.match(r.text, /piGauntlet\.phaseModels\.plan must be a "provider\/id" or "provider\/id:level" string/); assert.equal(r.status, "in_progress"); assert.deepEqual(h.pi.setModelCalls, []); assert.deepEqual(h.pi.thinkingCalls, []); }); test("agent_settled nudges each exact edge with persisted details", async () => { for (const [state, edge, skill] of [ [phases({ brainstorm: "complete", plan: "complete" }), "plan-implement", "/skill:subagent-driven-development"], [ phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "complete" }), "verify-ship", "/skill:finishing-a-development-branch", ], ] as const) { const h = harness({ branch: enteredBranch(state, [assistant()]) }); await settle(h); assert.equal(h.sent.length, 1); assert.deepEqual(h.sent[0].options, { triggerTurn: true }); assert.equal(h.sent[0].message.customType, "pi-gauntlet-transition-recovery"); assert.equal(h.sent[0].message.display, true); assert.deepEqual(h.sent[0].message.details, { piGauntletRecoveryEdge: edge }); assert.match(h.sent[0].message.content, new RegExp(skill.replace(/[/-]/g, "\\$&"))); } }); test("repeated settlement and persisted matching recovery details suppress a second nudge", async () => { const state = phases({ brainstorm: "complete", plan: "complete" }); const h = harness({ branch: enteredBranch(state, [assistant()]) }); await settle(h); await h.emit("agent_settled"); assert.equal(h.sent.length, 1); const restored = harness({ branch: enteredBranch(state, [ { type: "custom_message", customType: "pi-gauntlet-transition-recovery", details: { piGauntletRecoveryEdge: "plan-implement" } }, assistant(), ]), }); await settle(restored); assert.equal(restored.sent.length, 0); }); test("foreign or malformed custom-message details do not suppress recovery", async () => { const state = phases({ brainstorm: "complete", plan: "complete" }); for (const entry of [ { type: "custom_message", customType: "other", details: { piGauntletRecoveryEdge: "plan-implement" } }, { type: "custom_message", customType: "pi-gauntlet-transition-recovery", details: null }, { type: "custom_message", customType: "pi-gauntlet-transition-recovery", details: { piGauntletRecoveryEdge: "nope" } }, ]) { const h = harness({ branch: enteredBranch(state, [entry, assistant()]) }); await settle(h); assert.equal(h.sent.length, 1); } }); test("only brainstorming-entered, non-aborted settled flows recover", async () => { const state = phases({ brainstorm: "complete", plan: "complete" }); const cold = harness({ branch: [phaseResult("complete", state), assistant()] }); await settle(cold); assert.equal(cold.sent.length, 0); const branch = enteredBranch(state, [assistant("aborted")]); const aborted = harness({ branch }); await settle(aborted); assert.equal(aborted.sent.length, 0); branch.push(assistant()); await aborted.emit("agent_settled"); assert.equal(aborted.sent.length, 1); }); test("active phases, non-idleness, and earlier competing handlers do not spend recovery", async () => { for (const phase of PHASES) { const h = harness({ branch: enteredBranch(phases({ brainstorm: phase === "brainstorm" ? "in_progress" : "complete", plan: phase === "plan" ? "in_progress" : "complete", implement: phase === "implement" ? "in_progress" : "pending", verify: phase === "verify" ? "in_progress" : "pending", ship: phase === "ship" ? "in_progress" : "pending" }), [assistant()]) }); await settle(h); assert.equal(h.sent.length, 0, phase); } const state = phases({ brainstorm: "complete", plan: "complete" }); const notIdle = harness({ branch: enteredBranch(state, [assistant()]), idle: false }); await settle(notIdle); notIdle.setIdle(true); await notIdle.emit("agent_settled"); assert.equal(notIdle.sent.length, 1); const ordered = harness({ branch: enteredBranch(state, [assistant()]), beforeSettled: setIdle => setIdle(false), }); await settle(ordered); assert.equal(ordered.sent.length, 0); }); const assistantText = (text: string, stopReason = "stop") => ({ type: "message", message: { role: "assistant", stopReason, content: [{ type: "text", text }] }, }); const beforeSettle = async (h: ReturnType, overrides = {}) => (await h.emitEvent("agent_before_settle", { type: "agent_before_settle", outcome: "completed", entries: [], continue: false, context: { pendingMessages: [] }, ...overrides, })).filter(Boolean) as { entries: any[]; continue: boolean }[]; test("agent_before_settle requests one implement restart without running past a later marked stop", async () => { const branch = enteredBranch(phases({ brainstorm: "complete", plan: "complete", implement: "in_progress" }), [ taskSnapshot([{ name: "next task", status: "in_progress" }]), assistantText("The first wave is complete."), ]); let firstSettle = true; const h = harness({ branch, beforeSettled: () => { if (!firstSettle) return; firstSettle = false; h.pi.sendMessage({ customType: "other-extension", content: "Check the decision.", display: true }, { triggerTurn: true }); } }); const prior = { type: "custom", customType: "other-extension", data: "keep" }; await h.emit("session_start"); const proposals = await beforeSettle(h, { entries: [prior] }); assert.equal(proposals.length, 1, "the eligible stop must request a boundary continuation"); const [{ entries, continue: shouldContinue }] = proposals; assert.equal(shouldContinue, true); assert.deepEqual(entries, [prior, { type: "custom_message", customType: "pi-gauntlet-transition-recovery", display: true, details: { piGauntletRecoveryEdge: "implement-continue" }, content: "Your last message ended the turn during the implementation phase without a `gauntlet:` marker line. If the user asked you to stop, or a decision is still unresolved, restate it and end the turn; start with a `gauntlet:` line only where a skill already prescribes one for that stop, and do not invent a gate, `done` or `stuck` line. Otherwise continue only work that is already authorized; do not reopen a task the user settled as a terminal failure.", }]); branch.push(...entries, assistantText("The wave resumed.")); await h.emit("agent_settled"); assert.deepEqual(h.sent.map(s => s.message.customType), ["other-extension"]); branch.push({ type: "custom_message", ...h.sent[0].message }, assistantText("gauntlet: question")); assert.deepEqual(await beforeSettle(h), []); await h.emit("agent_settled"); assert.equal(h.sent.length, 1, "no recovery run may start after the marked stop"); }); const movedTask = () => taskSnapshot([{ name: "next task", status: "in_progress" }]); const decisionOn = async (branch: unknown[], event = {}) => { const h = harness({ branch }); await h.emit("session_start"); return beforeSettle(h, event); }; test("standalone implementation does not request a restart after task movement", async () => { const start = phaseResult("start", phases({ brainstorm: "skipped", plan: "skipped", implement: "in_progress" })); assert.deepEqual(await decisionOn([start, movedTask(), assistantText("Status.")]), []); }); test("only visible marker lines veto implement recovery", async () => { const marker = "gauntlet: question"; const visible = { type: "text", text: marker }; const status = { type: "text", text: "Status:" }; for (const [name, content, expected] of [ ["visible marker alone", [visible], 0], ["visible marker after status", [status, visible], 0], ["thinking marker first", [{ type: "thinking", thinking: marker }, status], 1], ["tool call marker after status", [status, { type: "toolCall", name: "tool", arguments: { note: marker } }], 1], ] as const) { const last = assistant(); const message = { ...last.message, content }; assert.equal((await decisionOn(implementBranch([movedTask(), { ...last, message }]))).length, expected, name); } }); const human = { type: "message", message: { role: "user", content: "Stop after this wave." } }; const foreignTrigger = { type: "custom_message", customType: "other-extension", content: "Continue." }; test("replies with no successful task movement since the boundary stay stopped", async () => { const failedResult = taskSnapshot([{ name: "other", status: "failed" }], true); for (const [history, expected] of [ [[], 0], [[movedTask(), human], 0], [[movedTask(), human, movedTask()], 0], [[movedTask(), human, failedResult], 0], [[movedTask(), taskSnapshot([])], 0], [[movedTask(), assistantText("gauntlet: question"), foreignTrigger], 0], [[movedTask(), foreignTrigger], 1], ] as const) { assert.equal((await decisionOn(implementBranch([...history, assistantText("Status.")]))).length, expected); } }); test("a recovery entry requires fresh movement for the next implementation restart", async () => { const branch = implementBranch([movedTask(), assistantText("Status.")]); const h = harness({ branch }); await h.emit("session_start"); const [first] = await beforeSettle(h); branch.push(...first.entries, assistantText("Still waiting.")); assert.deepEqual(await beforeSettle(h), []); branch.push(taskSnapshot([{ name: "next task", status: "failed" }]), assistantText("Another attempt finished.")); assert.equal((await beforeSettle(h)).length, 1); }); test("only a normal assistant stop qualifies for implement recovery", async () => { for (const reason of ["pending", "length", "toolUse", "error", "aborted", "deferred"]) { assert.deepEqual(await decisionOn(implementBranch([movedTask(), assistantText("Status.", reason)])), [], reason); } assert.deepEqual(await decisionOn(implementBranch([movedTask(), assistantText("Status.")]), { outcome: "aborted" }), []); }); test("a subagent replaying its parent's implement history never requests a restart", async () => { const branch = implementBranch([movedTask(), assistantText("Status.")]); assert.equal((await decisionOn(branch)).length, 1); const depth = process.env.PI_SUBAGENT_DEPTH!; try { process.env.PI_SUBAGENT_DEPTH = "1"; assert.deepEqual(await decisionOn(branch), []); } finally { process.env.PI_SUBAGENT_DEPTH = depth; } }); test("implement recovery yields to pending messages and to a prior boundary continuation", async () => { const branch = implementBranch([movedTask(), assistantText("Status.")]); for (const event of [ { context: { pendingMessages: [human.message] } }, { continue: true, entries: [foreignTrigger] }, ]) assert.deepEqual(await decisionOn(branch, event), []); }); test("reload and fork reproduce live decisions from branch history", async () => { const branch = implementBranch(); const live = harness({ branch }); await live.emit("session_start"); for (const entry of [movedTask(), taskSnapshot([{ name: "next task", status: "complete" }], true)]) { const { toolName, isError, details } = entry.message; await live.emitEvent("tool_execution_end", { toolName, isError, result: { details } }); branch.push(entry); } const assertDecision = async (count: number) => { const expected = await beforeSettle(live); assert.equal(expected.length, count); for (const event of ["session_start", "session_fork"]) { const rebuilt = harness({ branch: structuredClone(branch) }); await rebuilt.emit(event); assert.deepEqual(await beforeSettle(rebuilt), expected, event); } return expected; }; branch.push(assistantText("Status.")); const [restart] = await assertDecision(1); for (const [entries, count] of [ [[...restart.entries, assistantText("Waiting.")], 0], [[taskSnapshot([{ name: "next task", status: "failed" }]), assistantText("Attempt finished.")], 1], [[assistantText("gauntlet: question"), foreignTrigger, assistantText("Waiting.")], 0], ] as const) { branch.push(...entries); await assertDecision(count); } }); test("retrying a failed loop row counts movement without assuming more work is authorized", async () => { const row = (status: string, attempts: number) => taskSnapshot([ { name: "row 1", status, label: `${attempts}/3: Check the result` }, ]); for (const [updates, text, count] of [ [[row("failed", 2)], "Attempt finished.", 1], [[row("in_progress", 1), row("failed", 1)], "Attempt finished.", 1], [[row("failed", 1)], "Refreshed.", 0], [[row("failed", 3)], "gauntlet: stuck", 0], ] as const) { const result = await decisionOn(implementBranch([row("failed", 1), human, ...updates, assistantText(text)])); assert.equal(result.length, count); if (count) { assert.equal(result[0].entries[0].details.piGauntletRecoveryEdge, "implement-continue"); assert.doesNotMatch(result[0].entries[0].content, /tasks remain/i); assert.match(result[0].entries[0].content, /do not reopen a task the user settled as a terminal failure/); } } }); test("task movement outside implement never requests a restart", async () => { for (const phase of ["brainstorm", "plan", "verify", "ship"] as const) { const state = phases(); for (const earlier of PHASES.slice(0, PHASES.indexOf(phase))) state[earlier].status = "complete"; state[phase].status = "in_progress"; const h = harness({ branch: enteredBranch(state, [movedTask(), assistantText("Status.")]) }); await h.emit("session_start"); assert.deepEqual(await beforeSettle(h), [], phase); await h.emit("agent_settled"); assert.deepEqual(h.sent, [], phase); } }); test("a throwing send spends the in-memory edge", async () => { const h = harness({ branch: enteredBranch(phases({ brainstorm: "complete", plan: "complete" }), [assistant()]), sendThrows: true }); await h.emit("session_start"); await assert.rejects(h.emit("agent_settled"), /send failed/); await h.emit("agent_settled"); assert.equal(h.sent.length, 1); }); const writeCall = (id: string, path: string) => ({ toolName: "write", toolCallId: id, input: { path } }); const writeResult = (id: string) => ({ toolName: "write", toolCallId: id, content: [{ type: "text", text: "ok" }] }); test("implement-write guard: warns once on parent write outside exempt dirs, exempt paths silent", async () => { const priorDepth = process.env.PI_SUBAGENT_DEPTH; delete process.env.PI_SUBAGENT_DEPTH; // isolate from an ambient subagent depth in the test-runner's own process try { const h = harness({ cwd: tempCwd(), branch: resumedBranch({ plan: "complete", implement: "in_progress" }) }); await h.emit("session_start"); await h.emitEvent("tool_call", writeCall("t1", "doc/specs/x.md")); assert.equal((await h.emitEvent("tool_result", writeResult("t1")))[0], undefined); // spec dir exempt await h.emitEvent("tool_call", writeCall("t2", "doc/plans/x.md")); assert.equal((await h.emitEvent("tool_result", writeResult("t2")))[0], undefined); // plans dir exempt await h.emitEvent("tool_call", writeCall("t3", "src/x.ts")); const warned = (await h.emitEvent("tool_result", writeResult("t3")))[0] as { content: { text: string }[] }; assert.match(warned.content[0].text, /implement/); assert.match(warned.content[0].text, /subagent-driven-development/); assert.match(warned.content[0].text, /merge-conflict/); await h.emitEvent("tool_call", writeCall("t4", "src/y.ts")); assert.equal((await h.emitEvent("tool_result", writeResult("t4")))[0], undefined); // warn-once } finally { if (priorDepth !== undefined) process.env.PI_SUBAGENT_DEPTH = priorDepth; } }); test("implement-write guard: fires in the armed post-plan gap (plan complete, implement pending)", async () => { const priorDepth = process.env.PI_SUBAGENT_DEPTH; delete process.env.PI_SUBAGENT_DEPTH; try { const h = harness({ cwd: tempCwd(), branch: resumedBranch({ plan: "complete" }) }); await h.emit("session_start"); await h.emitEvent("tool_call", writeCall("t1", "src/x.ts")); const warned = (await h.emitEvent("tool_result", writeResult("t1")))[0] as { content: { text: string }[] }; assert.match(warned.content[0].text, /implement/); } finally { if (priorDepth !== undefined) process.env.PI_SUBAGENT_DEPTH = priorDepth; } }); test("implement-write guard: silent when unarmed, when enforce is false, and in subagent children", async () => { const cold = harness({ cwd: tempCwd(), branch: [phaseResult("complete", phases({ plan: "complete", implement: "in_progress" }))] }); await cold.emit("session_start"); await cold.emitEvent("tool_call", writeCall("t1", "src/x.ts")); assert.equal((await cold.emitEvent("tool_result", writeResult("t1")))[0], undefined); const off = harness({ cwd: tempCwd({ piGauntlet: { flowGuards: { enforce: false } } }), branch: resumedBranch({ plan: "complete", implement: "in_progress" }), }); await off.emit("session_start"); await off.emitEvent("tool_call", writeCall("t1", "src/x.ts")); assert.equal((await off.emitEvent("tool_result", writeResult("t1")))[0], undefined); const priorDepth = process.env.PI_SUBAGENT_DEPTH; process.env.PI_SUBAGENT_DEPTH = "1"; try { const child = harness({ cwd: tempCwd(), branch: resumedBranch({ plan: "complete", implement: "in_progress" }) }); await child.emit("session_start"); await child.emitEvent("tool_call", writeCall("t1", "src/x.ts")); assert.equal((await child.emitEvent("tool_result", writeResult("t1")))[0], undefined); } finally { if (priorDepth === undefined) delete process.env.PI_SUBAGENT_DEPTH; else process.env.PI_SUBAGENT_DEPTH = priorDepth; } }); for (const toolName of ["bash", "write", "edit"]) { for (const nested of [false, true]) { test(`brainstorm ${toolName} warning preserves results (${nested ? "nested" : "direct"}) and stays fired`, async () => { const h = harness({ branch: [phaseResult("start", phases({ brainstorm: "in_progress" }))] }); await h.emit("session_start"); const toolCallId = nested ? "parent/0" : "direct"; const nesting = nested ? { parentToolCallId: "parent" } : {}; const call = { toolName, toolCallId, ...nesting, input: toolName === "bash" ? { command: "echo x > src/a.ts" } : { path: "src/a.ts" }, }; await h.emitEvent("tool_call", call); const event = { ...writeResult(toolCallId), toolName, ...nesting, isError: true, details: { sentinel: "guard details" }, usage: { sentinel: "guard usage" }, structuredContent: toolName === "bash" ? { output: "ok", exit_code: 0 } : toolName === "write" ? null : { edited: true }, }; const original = structuredClone(event); const [ret] = await h.emitEvent("tool_result", event); let delivered = event; let merged = mergeToolResult(event, ret); if (nested) { assert.equal(ret, undefined); assert.deepEqual(merged, original); const parent = { ...event, toolName: "codemode", toolCallId: "parent", parentToolCallId: undefined, content: [{ type: "text", text: "script value: 0" }], structuredContent: { value: 0 }, }; delivered = parent; const [parentRet] = await h.emitEvent("tool_result", parent); merged = mergeToolResult(parent, parentRet); } assert.deepEqual(event, original); assert.match(merged.content[0].text, /Writing outside the spec directory/); assert.equal(merged.content[0].text.split("Writing outside the spec directory").length - 1, 1); assert.deepEqual(merged, { ...delivered, content: [merged.content[0], ...delivered.content] }); assert.equal((await h.emitEvent("tool_result", delivered))[0], undefined); await h.emitEvent("tool_call", writeCall("later", "src/b.ts")); assert.equal((await h.emitEvent("tool_result", writeResult("later")))[0], undefined); }); } } for (const toolName of ["bash", "write", "edit"]) { for (const nested of [false, true]) { test(`implement-write and cadence warnings preserve ${toolName} results (${nested ? "nested" : "direct"})`, async () => { const h = harness({ branch: implementBranch([subagentResult(["implementer"])]) }); await h.emit("session_start"); const nesting = nested ? { parentToolCallId: "parent" } : {}; const write = { ...writeCall("write", "src/a.ts"), toolName: toolName === "edit" ? "edit" : "write" }; for (const [index, call] of [write, commitCall("commit")].entries()) { const toolCallId = nested ? `parent/${index}` : call.toolCallId; await h.emitEvent("tool_call", { ...call, toolCallId, ...nesting }); // Deferred cadence delivery is keyed by call ID, not the result's tool name. const event = { ...writeResult(toolCallId), toolName: index === 0 ? write.toolName : toolName, ...nesting, structuredContent: { exit_code: 0 } }; const [ret] = await h.emitEvent("tool_result", event); if (nested) { assert.equal(ret, undefined); assert.deepEqual(mergeToolResult(event, ret), event); } else { const merged = mergeToolResult(event, ret); assert.match(merged.content[0].text, index === 0 ? /Parent write/ : /no wave-reviewer observed/); assert.deepEqual(merged, { ...event, content: [merged.content[0], ...event.content] }); } } if (nested) { const parent = { ...commitResult("parent"), toolName: "codemode", structuredContent: { value: "done" } }; const [ret] = await h.emitEvent("tool_result", parent); const merged = mergeToolResult(parent, ret); assert.match(merged.content[0].text, /Parent write[\s\S]*no wave-reviewer observed/); assert.equal(merged.content[0].text.split("Parent write").length - 1, 1); assert.equal(merged.content[0].text.split("no wave-reviewer observed").length - 1, 1); assert.deepEqual(merged, { ...parent, content: [merged.content[0], ...parent.content] }); assert.equal((await h.emitEvent("tool_result", parent))[0], undefined); } await h.emitEvent("tool_call", writeCall("later", "src/b.ts")); assert.equal((await h.emitEvent("tool_result", writeResult("later")))[0], undefined); }); } } for (const transition of ["reset", "session_start"]) { test(`${transition} clears a deferred nested guard warning before the parent result`, async () => { const h = harness({ branch: [phaseResult("start", phases({ brainstorm: "in_progress" }))] }); await h.emit("session_start"); await h.emitEvent("tool_call", { ...writeCall("parent/0", "src/a.ts"), parentToolCallId: "parent" }); assert.equal((await h.emitEvent("tool_result", { ...writeResult("parent/0"), parentToolCallId: "parent" }))[0], undefined); if (transition === "reset") { const tool = h.tools.find((t) => t.name === "phase_tracker")!; await tool.execute("reset", { action: "reset" }, undefined, undefined, h.ctx); } else { await h.emit("session_start"); } const parent = { ...writeResult("parent"), toolName: "codemode", structuredContent: { value: 0 } }; const [ret] = await h.emitEvent("tool_result", parent); assert.equal(ret, undefined); assert.deepEqual(mergeToolResult(parent, ret), parent); }); } test("brainstorm write confinement: a docs/specs write under the default dirs does not warn", async () => { const priorDepth = process.env.PI_SUBAGENT_DEPTH; delete process.env.PI_SUBAGENT_DEPTH; try { const h = harness({ cwd: tempCwd(), branch: [phaseResult("start", phases({ brainstorm: "in_progress" }))] }); await h.emit("session_start"); await h.emitEvent("tool_call", writeCall("t1", "docs/specs/x.md")); assert.equal((await h.emitEvent("tool_result", writeResult("t1")))[0], undefined); } finally { if (priorDepth !== undefined) process.env.PI_SUBAGENT_DEPTH = priorDepth; } }); test("resumed session: plan-implement recovery edge fires (AC 3)", async () => { const h = harness({ cwd: tempCwd(), branch: [...resumedBranch({ plan: "complete" }), assistant()] }); await settle(h); assert.equal(h.sent.length, 1); assert.deepEqual(h.sent[0].message.details, { piGauntletRecoveryEdge: "plan-implement" }); }); test("resumed session: closure gate blocks complete verify without a conformance dispatch (AC 3)", async () => { const h = harness({ cwd: tempCwd(), branch: resumedBranch({ plan: "complete", implement: "complete", verify: "in_progress" }), }); await h.emit("session_start"); const tool = h.tools.find((t) => t.name === "phase_tracker")!; const res = (await tool.execute("t1", { action: "complete", phase: "verify" }, undefined, undefined, h.ctx)) as { details: { error?: string }; }; assert.equal(res.details.error, "no conformance-reviewer dispatch observed"); }); test("restarting implement clears a resumed conformance dispatch latch", async () => { const h = harness({ cwd: tempCwd({ piGauntlet: { flowGuards: { enforce: false }, closureReview: { enforce: true } } }), branch: [ ...resumedBranch({ plan: "complete", implement: "complete", verify: "complete", ship: "in_progress" }), subagentResult(["conformance-reviewer"]), ], }); await h.emit("session_start"); const tool = h.tools.find((t) => t.name === "phase_tracker")!; await tool.execute("t1", { action: "skip", phase: "ship", reason: "amendment reopened Task 1" }, undefined, undefined, h.ctx); await tool.execute("t2", { action: "start", phase: "implement", force: true }, undefined, undefined, h.ctx); await tool.execute("t3", { action: "skip", phase: "implement", reason: "amendment implementation tested separately" }, undefined, undefined, h.ctx); await tool.execute("t4", { action: "start", phase: "verify", force: true }, undefined, undefined, h.ctx); const res = (await tool.execute("t5", { action: "complete", phase: "verify" }, undefined, undefined, h.ctx)) as { details: { error?: string }; }; assert.equal(res.details.error, "no conformance-reviewer dispatch observed"); }); test("replayed implement restart clears a persisted conformance dispatch latch", async () => { const h = harness({ cwd: tempCwd({ piGauntlet: { flowGuards: { enforce: false }, closureReview: { enforce: true } } }), branch: [ ...resumedBranch({ plan: "complete", implement: "complete", verify: "complete", ship: "in_progress" }), subagentResult(["conformance-reviewer"]), phaseResult("skip", phases({ brainstorm: "skipped", plan: "complete", implement: "complete", verify: "complete", ship: "skipped" })), phaseResult("start", phases({ brainstorm: "skipped", plan: "complete", implement: "in_progress", verify: "complete", ship: "skipped" })), phaseResult("skip", phases({ brainstorm: "skipped", plan: "complete", implement: "skipped", verify: "complete", ship: "skipped" })), phaseResult("start", phases({ brainstorm: "skipped", plan: "complete", implement: "skipped", verify: "in_progress", ship: "skipped" })), ], }); await h.emit("session_start"); const tool = h.tools.find((t) => t.name === "phase_tracker")!; const res = (await tool.execute("t1", { action: "complete", phase: "verify" }, undefined, undefined, h.ctx)) as { details: { error?: string }; }; assert.equal(res.details.error, "no conformance-reviewer dispatch observed"); }); const taskSnapshot = (tasks: { name: string; status: string; label?: string }[], isError = false) => ({ type: "message", message: { role: "toolResult", toolName: "plan_tracker", isError, details: { tasks } }, }); const completePhase = async (h: ReturnType, phase: "implement" | "verify") => { const tool = h.tools.find((t) => t.name === "phase_tracker")!; return (await tool.execute("complete", { action: "complete", phase }, undefined, undefined, h.ctx)) as { content: { text: string }[]; details: { error?: string; phases: Record }; }; }; test("tracker registration is model-only and phase_tracker requests sequential execution", () => { const h = harness(); assert.equal(h.tools.find((t) => t.name === "phase_tracker")!.executionMode, "sequential"); for (const name of ["phase_tracker", "plan_check"]) { assert.equal(h.tools.find((t) => t.name === name)!.exposure, "model-only", name); } }); for (const row of [ { name: "exactly 25 percent", read: () => ({ tokens: 250000, contextWindow: 1000000, percent: 0 }), expected: "25.0% of window" }, { name: "just above 25 percent", read: () => ({ tokens: 250001, contextWindow: 1000000, percent: 25 }), expected: "25.1% of window" }, { name: "exactly 26 percent", read: () => ({ tokens: 260000, contextWindow: 1000000, percent: null }), expected: "26.0% of window" }, { name: "zero tokens", read: () => ({ tokens: 0, contextWindow: 1000000, percent: 99 }), expected: "0.0% of window" }, { name: "fractional percentage", read: () => ({ tokens: 1, contextWindow: 3, percent: 33 }), expected: "33.4% of window" }, { name: "missing reader", read: undefined, expected: "unknown" }, { name: "no usage", read: () => undefined, expected: "unknown" }, { name: "null tokens", read: () => ({ tokens: null, contextWindow: 1000000, percent: null }), expected: "unknown" }, { name: "zero window", read: () => ({ tokens: 250000, contextWindow: 0, percent: 25 }), expected: "unknown" }, { name: "negative window", read: () => ({ tokens: 250000, contextWindow: -1, percent: 25 }), expected: "unknown" }, ]) { test(`status context: ${row.name}`, async () => { const h = harness(); const tool = h.tools.find(t => t.name === "phase_tracker")!; const ctx = { ...h.ctx, getContextUsage: row.read }; const result = await tool.execute("status", { action: "status" }, undefined, undefined, ctx) as { content: { text: string }[]; }; assert.equal(result.content.map(c => c.text).join("\n").split("\n").at(-1), `Context: ${row.expected}`); }); } for (const row of [ { name: "known", usage: { tokens: 1, contextWindow: 3, percent: 33 }, expected: "33.4% of window" }, { name: "unknown", usage: undefined, expected: "unknown" }, ]) { test(`status context stays out of details, TUI and widget: ${row.name}`, async () => { const state = phases({ brainstorm: "in_progress" }); const h = harness({ hasUI: true, branch: enteredBranch(state) }); Object.assign(h.ctx, { getContextUsage: () => row.usage }); await h.emit("session_start"); const widgetBefore = h.widgets.at(-1); assert.match(widgetBefore!, /brainstorm/); const tool = h.tools.find(t => t.name === "phase_tracker")! as any; const result = await tool.execute("status", { action: "status" }, undefined, undefined, h.ctx); assert.equal(result.content[0].text.split("\n").at(-1), `Context: ${row.expected}`); assert.deepEqual(result.details, { action: "status", phases: state }); const rendered = tool.renderResult(result, {}, { fg: (_color: string, text: string) => text }); assert.match(rendered.text, /Phases:[\s\S]*brainstorm/); assert.doesNotMatch(rendered.text, /Context:|of window/); await h.emit("session_switch"); assert.equal(h.widgets.at(-1), widgetBefore); for (const widget of h.widgets) assert.doesNotMatch(widget!, /Context:|of window/); }); } test("all-complete plan activity auto-completes an active implement phase", async () => { const h = harness({ branch: implementBranch() }); await h.emit("session_start"); await h.emitEvent("tool_execution_end", { toolName: "plan_tracker", isError: false, result: { details: { tasks: [{ status: "complete" }, { status: "complete" }] } }, }); const tool = h.tools.find((t) => t.name === "phase_tracker")!; const status = (await tool.execute("t1", { action: "status" }, undefined, undefined, h.ctx)) as { details: { phases: { implement: { status: string } } }; }; assert.equal(status.details.phases.implement.status, "complete"); }); test("plan activity auto-completes implement with complete+skipped, not with failed, not from an errored result", async () => { const implementStatus = async (tasks: { status: string }[], isError = false) => { const h = harness({ branch: implementBranch() }); await h.emit("session_start"); await h.emitEvent("tool_execution_end", { toolName: "plan_tracker", isError, result: { details: { tasks } }, }); const tool = h.tools.find((t) => t.name === "phase_tracker")!; const status = (await tool.execute("t1", { action: "status" }, undefined, undefined, h.ctx)) as { details: { phases: { implement: { status: string } } }; }; return status.details.phases.implement.status; }; assert.equal(await implementStatus([{ status: "complete" }, { status: "skipped" }]), "complete"); assert.equal(await implementStatus([{ status: "skipped" }, { status: "skipped" }]), "complete"); assert.equal(await implementStatus([{ status: "complete" }, { status: "failed" }]), "in_progress"); assert.equal(await implementStatus([{ status: "complete" }, { status: "skipped" }], true), "in_progress"); }); test("ledger refresh completes only started implement and keeps failed, in-flight and Gn work open", async () => { for (const allCut of [true, false]) { const dir = tempCwd({ piGauntlet: { flowGuards: { enforce: false } } }); const path = join(dir, "ledger.md"); execFileSync("git", ["init", "-q", dir]); writeFileSync(join(dir, "spec.md"), "# Spec\n\n## Acceptance criteria\n- [ ] The tracker shows a readable step\n in-scope\n"); const save = (status: string, pending = "") => writeFileSync(path, `# Ledger - loop engine\n**Spec:** \`spec.md\`\n${pending}\n| row | status | attempts | evidence |\n|---|---|---|---|\n| 1 | ${status} | 0 | check |\n\n## Decisions\n`); save(allCut ? "cut" : "failed"); const branch = implementBranch().slice(0, -1); const h = harness({ cwd: dir, branch }); registerPlanTracker(h.pi as any); await h.emit("session_start"); const tracker = h.tools.find(t => t.name === "plan_tracker")!; const phase = h.tools.find(t => t.name === "phase_tracker")!; const status = async () => (await phase.execute("status", { action: "status" }, undefined, undefined, h.ctx) as any).details.phases.implement.status; const refresh = async (target = path) => { const result = await tracker.execute("refresh", { action: "refresh", path: target }, undefined, undefined, h.ctx) as any; branch.push({ type: "message", message: { role: "toolResult", toolName: "plan_tracker", details: result.details } } as any); await h.emitEvent("tool_execution_end", { toolName: "plan_tracker", result }); return result; }; assert.equal((await refresh()).details.error, undefined); assert.equal(await status(), "pending", "refresh before start cannot complete implement"); assert.equal((await startPhase(h, "implement")).status, "in_progress"); await refresh(); if (!allCut) { assert.equal(await status(), "in_progress", "failed row keeps implement active"); save("failed", "pending: 1 | home | abc1234"); const inFlight = await refresh(); assert.equal(inFlight.details.tasks[0].status, "in_progress"); assert.equal(await status(), "in_progress"); assert.ok((await refresh(join(dir, "missing.md"))).details.error); assert.equal(await status(), "in_progress", "invalid refresh cannot complete implement"); await tracker.execute("add", { action: "add", tasks: ["G1: conformance"] }, undefined, undefined, h.ctx); save("done"); const withGap = await refresh(); assert.equal(withGap.details.tasks[1].status, "pending"); assert.equal(await status(), "in_progress", "kept Gn task blocks completion"); await tracker.execute("update", { action: "update", index: 1, status: "complete" }, undefined, undefined, h.ctx); await refresh(); } assert.equal(await status(), "complete"); assert.equal((await startPhase(h, "verify")).status, "in_progress"); } }); test("cold implement and verify completions ignore unfinished snapshots", async () => { for (const phase of ["implement", "verify"] as const) { const h = harness({ branch: [ phaseResult("start", phases({ [phase]: "in_progress" })), taskSnapshot([{ name: "standalone task", status: "pending" }]), ], }); await h.emit("session_start"); const completed = await completePhase(h, phase); assert.equal(completed.details.error, undefined, phase); assert.equal(completed.details.phases[phase].status, "complete", phase); } }); test("completion backstop rejects unfinished snapshot indices, preserves state, and permits same-index retry", async () => { const branch: unknown[] = [ ...resumedBranch({ plan: "complete", implement: "complete", verify: "in_progress" }), subagentResult(["conformance-reviewer"]), taskSnapshot([ { name: "T1 implementation", status: "complete" }, { name: "G1 conformance", status: "pending" }, { name: "G2 conformance", status: "in_progress" }, ]), ]; const h = harness({ branch }); await h.emit("session_start"); const rejected = await completePhase(h, "verify"); assert.equal(rejected.details.error, "unfinished tasks"); assert.equal(rejected.details.phases.verify.status, "in_progress"); assert.match(rejected.content[0].text, /1: G1 conformance \(pending\)/); assert.match(rejected.content[0].text, /2: G2 conformance \(in_progress\)/); branch.push(taskSnapshot([ { name: "T1 implementation", status: "complete" }, { name: "G1 conformance", status: "complete" }, { name: "G2 conformance", status: "complete" }, ])); const completed = await completePhase(h, "verify"); assert.equal(completed.details.error, undefined); assert.equal(completed.details.phases.verify.status, "complete"); }); test("completion backstop uses the latest successful current-branch snapshot", async () => { const branch: unknown[] = [ ...resumedBranch({ plan: "complete", implement: "in_progress" }), taskSnapshot([{ name: "old", status: "pending" }]), taskSnapshot([{ name: "errored", status: "pending" }], true), ]; const h = harness({ branch }); await h.emit("session_start"); const rejected = await completePhase(h, "implement"); assert.equal(rejected.details.error, "unfinished tasks"); assert.match(rejected.content[0].text, /0: old \(pending\)/); branch.push(taskSnapshot([])); // clear/init supersedes the old snapshot assert.equal((await completePhase(h, "implement")).details.phases.implement.status, "complete"); const resetOnlyBranch: unknown[] = [ ...resumedBranch({ plan: "complete", implement: "in_progress" }), taskSnapshot([{ name: "retained through reset", status: "in_progress" }]), phaseResult("reset", phases()), ...resumedBranch({ plan: "complete", implement: "in_progress" }), ]; const resetOnly = harness({ branch: resetOnlyBranch }); await resetOnly.emit("session_start"); assert.equal((await completePhase(resetOnly, "implement")).details.error, "unfinished tasks"); resetOnlyBranch.push(taskSnapshot([{ name: "retained through reset", status: "complete" }])); assert.equal((await completePhase(resetOnly, "implement")).details.phases.implement.status, "complete"); }); test("completion backstop preserves exclusions and closure-error precedence", async () => { const unfinished = taskSnapshot([{ name: "failed", status: "failed" }]); const explicitImplement = harness({ branch: [...resumedBranch({ plan: "complete", implement: "in_progress" }), unfinished] }); await explicitImplement.emit("session_start"); assert.equal((await completePhase(explicitImplement, "implement")).details.phases.implement.status, "complete"); const closureFirst = harness({ branch: [...resumedBranch({ plan: "complete", implement: "complete", verify: "in_progress" }), taskSnapshot([{ name: "T1", status: "pending" }])], }); await closureFirst.emit("session_start"); assert.equal((await completePhase(closureFirst, "verify")).details.error, "no conformance-reviewer dispatch observed"); const disabled = harness({ cwd: tempCwd({ piGauntlet: { flowGuards: { enforce: false } } }), branch: [...resumedBranch({ plan: "complete", implement: "in_progress" }), taskSnapshot([{ name: "T1", status: "pending" }])], }); await disabled.emit("session_start"); assert.equal((await completePhase(disabled, "implement")).details.phases.implement.status, "complete"); const adHoc = harness({ branch: [taskSnapshot([{ name: "T1", status: "pending" }])] }); await adHoc.emit("session_start"); const tool = adHoc.tools.find((t) => t.name === "phase_tracker")!; assert.equal((await tool.execute("x", { action: "complete", phase: "plan" }, undefined, undefined, adHoc.ctx)).details.error, undefined); }); test("completion backstop leaves no/empty snapshots and skip alone, and uses the switched branch", async () => { const noSnapshot = harness({ branch: resumedBranch({ plan: "complete", implement: "in_progress" }) }); await noSnapshot.emit("session_start"); assert.equal((await completePhase(noSnapshot, "implement")).details.phases.implement.status, "complete"); const skipped = harness({ branch: [...resumedBranch({ plan: "complete", implement: "in_progress" }), taskSnapshot([{ name: "T1", status: "pending" }])], }); await skipped.emit("session_start"); const skipTool = skipped.tools.find((t) => t.name === "phase_tracker")!; assert.equal((await skipTool.execute("skip", { action: "skip", phase: "implement", reason: "waived" }, undefined, undefined, skipped.ctx)).details.error, undefined); const switched = harness({ branch: [...resumedBranch({ plan: "complete", implement: "in_progress" }), taskSnapshot([{ name: "off branch", status: "pending" }])], }); await switched.emit("session_start"); switched.setBranch([...resumedBranch({ plan: "complete", implement: "in_progress" }), taskSnapshot([{ name: "active", status: "complete" }])]); await switched.emit("session_switch"); assert.equal((await completePhase(switched, "implement")).details.phases.implement.status, "complete"); const closureOff = harness({ cwd: tempCwd({ piGauntlet: { closureReview: { enforce: false } } }), branch: [...resumedBranch({ plan: "complete", implement: "complete", verify: "in_progress" }), taskSnapshot([{ name: "T1", status: "pending" }])], }); await closureOff.emit("session_start"); assert.equal((await completePhase(closureOff, "verify")).details.error, "unfinished tasks"); }); const subagentResult = (agents: string[]) => ({ type: "message", message: { role: "toolResult", toolName: "subagent", details: { results: agents.map((agent) => ({ agent, exitCode: 0 })) }, }, }); const implementBranch = (extra: unknown[] = []) => [ phaseResult("start", phases({ brainstorm: "in_progress" })), phaseResult("complete", phases({ brainstorm: "complete" })), phaseResult("start", phases({ brainstorm: "complete", plan: "in_progress" })), phaseResult("complete", phases({ brainstorm: "complete", plan: "complete" })), phaseResult("start", phases({ brainstorm: "complete", plan: "complete", implement: "in_progress" })), ...extra, ]; const commitCall = (id: string) => ({ toolName: "bash", toolCallId: id, input: { command: "git commit -m 'integrate wave'" }, }); const commitResult = (id: string) => ({ toolName: "bash", toolCallId: id, isError: false, content: [{ type: "text", text: "ok" }], }); for (const path of ["README.md", "extensions/example.ts"]) { for (const [name, agents, warns] of [ ["missing review", ["implementer"], true], ["stale review", ["wave-reviewer", "implementer"], true], ["newer review", ["implementer", "wave-reviewer"], false], ] as const) { test(`cadence for ${path}: ${name}`, async () => { const priorDepth = process.env.PI_SUBAGENT_DEPTH; delete process.env.PI_SUBAGENT_DEPTH; // isolate from an ambient subagent depth in the test-runner's own process try { const h = harness({ branch: implementBranch(agents.map((agent) => subagentResult([agent]))) }); await h.emit("session_start"); const call = commitCall("c1"); call.input.command = `git commit -m 'integrate wave' -- ${path}`; await h.emitEvent("tool_call", call); const warned = (await h.emitEvent("tool_result", commitResult("c1")))[0] as { content: { text: string }[] } | undefined; assert.equal(warned !== undefined, warns); if (warned) assert.match(warned.content[0].text, /no wave-reviewer observed/); } finally { if (priorDepth === undefined) delete process.env.PI_SUBAGENT_DEPTH; else process.env.PI_SUBAGENT_DEPTH = priorDepth; } }); } } test("cadence guard silent in subagent children", async () => { const priorDepth = process.env.PI_SUBAGENT_DEPTH; process.env.PI_SUBAGENT_DEPTH = "1"; try { const branch = implementBranch([subagentResult(["implementer"])]); const h = harness({ branch }); await h.emit("session_start"); await h.emitEvent("tool_call", commitCall("c1")); assert.equal((await h.emitEvent("tool_result", commitResult("c1")))[0], undefined); } finally { if (priorDepth === undefined) delete process.env.PI_SUBAGENT_DEPTH; else process.env.PI_SUBAGENT_DEPTH = priorDepth; } }); test("fresh wave review after the implementer keeps the commit silent", async () => { const priorDepth = process.env.PI_SUBAGENT_DEPTH; delete process.env.PI_SUBAGENT_DEPTH; try { const h = harness({ branch: implementBranch([ subagentResult(["implementer"]), subagentResult(["wave-reviewer"]), ]), }); await h.emit("session_start"); await h.emitEvent("tool_call", commitCall("c1")); assert.equal((await h.emitEvent("tool_result", commitResult("c1")))[0], undefined); } finally { if (priorDepth !== undefined) process.env.PI_SUBAGENT_DEPTH = priorDepth; } }); test("fresh wave review stays silent for a doc-only wave", async () => { const priorDepth = process.env.PI_SUBAGENT_DEPTH; delete process.env.PI_SUBAGENT_DEPTH; try { const h = harness({ branch: implementBranch([subagentResult(["implementer"]), subagentResult(["wave-reviewer"])]), }); await h.emit("session_start"); await h.emitEvent("tool_call", commitCall("c1")); assert.equal((await h.emitEvent("tool_result", commitResult("c1")))[0], undefined); } finally { if (priorDepth !== undefined) process.env.PI_SUBAGENT_DEPTH = priorDepth; } }); test("fused implementer+reviewer results in one dispatch stay silent", async () => { const priorDepth = process.env.PI_SUBAGENT_DEPTH; delete process.env.PI_SUBAGENT_DEPTH; try { const h = harness({ branch: implementBranch([subagentResult(["implementer", "wave-reviewer"])]), }); await h.emit("session_start"); await h.emitEvent("tool_call", commitCall("c1")); assert.equal((await h.emitEvent("tool_result", commitResult("c1")))[0], undefined); } finally { if (priorDepth !== undefined) process.env.PI_SUBAGENT_DEPTH = priorDepth; } }); test("no implementer observed: commit stays silent", async () => { const priorDepth = process.env.PI_SUBAGENT_DEPTH; delete process.env.PI_SUBAGENT_DEPTH; try { const h = harness({ branch: implementBranch() }); await h.emit("session_start"); await h.emitEvent("tool_call", commitCall("c1")); assert.equal((await h.emitEvent("tool_result", commitResult("c1")))[0], undefined); } finally { if (priorDepth !== undefined) process.env.PI_SUBAGENT_DEPTH = priorDepth; } }); test("guard silent outside implement and when flowGuards.enforce is false", async () => { const priorDepth = process.env.PI_SUBAGENT_DEPTH; delete process.env.PI_SUBAGENT_DEPTH; try { const planOnly = harness({ branch: [ phaseResult("start", phases({ brainstorm: "in_progress" })), phaseResult("complete", phases({ brainstorm: "complete" })), phaseResult("start", phases({ brainstorm: "complete", plan: "in_progress" })), subagentResult(["implementer"]), ], }); await planOnly.emit("session_start"); await planOnly.emitEvent("tool_call", commitCall("c1")); assert.equal((await planOnly.emitEvent("tool_result", commitResult("c1")))[0], undefined); const off = harness({ cwd: tempCwd({ piGauntlet: { flowGuards: { enforce: false } } }), branch: implementBranch([subagentResult(["implementer"])]), }); await off.emit("session_start"); await off.emitEvent("tool_call", commitCall("c1")); assert.equal((await off.emitEvent("tool_result", commitResult("c1")))[0], undefined); } finally { if (priorDepth !== undefined) process.env.PI_SUBAGENT_DEPTH = priorDepth; } }); test("live tool_result observation updates the ledger", async () => { const priorDepth = process.env.PI_SUBAGENT_DEPTH; delete process.env.PI_SUBAGENT_DEPTH; try { const h = harness({ branch: implementBranch([subagentResult(["implementer"])]) }); await h.emit("session_start"); await h.emitEvent("tool_result", { toolName: "subagent", toolCallId: "s1", content: [], details: { results: [{ agent: "wave-reviewer", exitCode: 0 }, { agent: "wave-reviewer", exitCode: 0 }] }, }); await h.emitEvent("tool_call", commitCall("c1")); assert.equal((await h.emitEvent("tool_result", commitResult("c1")))[0], undefined); } finally { if (priorDepth !== undefined) process.env.PI_SUBAGENT_DEPTH = priorDepth; } }); test("second implementer after reviews re-arms the warning", async () => { const priorDepth = process.env.PI_SUBAGENT_DEPTH; delete process.env.PI_SUBAGENT_DEPTH; try { const h = harness({ branch: implementBranch([ subagentResult(["implementer"]), subagentResult(["wave-reviewer"]), subagentResult(["implementer"]), ]), }); await h.emit("session_start"); await h.emitEvent("tool_call", commitCall("c1")); const warned = (await h.emitEvent("tool_result", commitResult("c1")))[0] as { content: { text: string }[] }; assert.match(warned.content[0].text, /no wave-reviewer observed/); } finally { if (priorDepth !== undefined) process.env.PI_SUBAGENT_DEPTH = priorDepth; } }); // --- plan_check tool + hash stamp + replay + implement-start gate (gh-19) --- const sha256Hex = (bytes: Buffer) => createHash("sha256").update(bytes).digest("hex"); const FIXTURE_SPEC = [ "# Fixture Spec", "", "## Design", "Line A.", "This part defines `helperFn()` config.", "Another line here.", ].join("\n"); const FIXTURE_PLAN = `# Fixture Plan **Spec:** \`doc/specs/spec.md\` **Verification:** npm test --- ## Wave 1 - Two parallel tasks ### Task 1: Implement helper **Spec:** spec.md § "Design" L4-L6 **Files:** - Create: lib/task1.ts - Create: lib/task1.test.ts - Modify: file-a.ts - Test: lib/task1.test.ts **Tests:** - \`node --test lib/task1.test.ts\` - baseline: abc1234 skipped - lib/task1.test.ts created by this task This task implements helperFn() for parsing. ### Task 2: Implement naming **Spec:** spec.md § "Design" L4-L4 **Files:** - Create: lib/task2.ts - Create: lib/task2.test.ts - Modify: file-b.ts - Test: lib/task2.test.ts **Tests:** - \`node --test lib/task2.test.ts\` - baseline: abc1234 skipped - lib/task2.test.ts created by this task This task handles naming details. ## Spec coverage | anchor | requirement | owner | |---|---|---| | § "Design" L4-L6 | parser grammar basics | Task 1 | | § "Design" L4-L4 | helper naming | Task 2 | `; function writePlanFixture( dir: string, opts: { mutatePlan?: (t: string) => string; mutateSpec?: (t: string) => string } = {}, ) { const planText = opts.mutatePlan ? opts.mutatePlan(FIXTURE_PLAN) : FIXTURE_PLAN; const specText = opts.mutateSpec ? opts.mutateSpec(FIXTURE_SPEC) : FIXTURE_SPEC; const planPath = join(dir, "doc/plans/plan.md"); const specPath = join(dir, "doc/specs/spec.md"); mkdirSync(join(dir, "doc/plans"), { recursive: true }); mkdirSync(join(dir, "doc/specs"), { recursive: true }); writeFileSync(planPath, planText); writeFileSync(specPath, specText); writeFileSync(join(dir, "file-a.ts"), "// a\n"); writeFileSync(join(dir, "file-b.ts"), "// b\n"); return { planPath, specPath, planText, specText }; } const readyForImplementBranch = implementBranch().slice(0, 4); const planCheckResult = (details: unknown) => ({ type: "message", message: { role: "toolResult", toolName: "plan_check", details }, }); test("plan_check is registered", () => { const h = harness(); assert.ok(h.tools.some((t) => t.name === "plan_check")); }); test("plan_check roots at the plan's checkout: worktree plan passes from /doc (AC 1)", async () => { const { primary, worktree } = gitPrimary(); const { planPath } = writePlanFixture(worktree); const h = harness({ cwd: join(primary, "doc") }); await h.emit("session_start"); const tool = h.tools.find((t) => t.name === "plan_check")!; const res = (await tool.execute("t1", { planPath }, undefined, undefined, h.ctx)) as { content: { text: string }[]; details: { status: string; specPath: string } }; assert.match(res.content[0].text, /^PASS/); assert.equal(res.details.specPath, join(worktree, "doc/specs/spec.md")); }); test("plan_check outside any checkout: input finding", async () => { const dir = tempCwd(); const { planPath } = writePlanFixture(dir); const h = harness({ cwd: dir }); await h.emit("session_start"); const tool = h.tools.find((t) => t.name === "plan_check")!; const res = (await tool.execute("t1", { planPath }, undefined, undefined, h.ctx)) as { content: { text: string }[]; details: { status: string } }; assert.equal(res.details.status, "fail"); assert.match(res.content[0].text, /input @ line 0: plan is not inside a git checkout/); }); const bashCall = (id: string, command: string) => ({ toolName: "bash", toolCallId: id, input: { command } }); const blocked = (results: unknown[]) => (results[0] as { block?: boolean } | undefined)?.block === true; test("Guard 2 evaluates the command's target checkout (AC 3)", async () => { const { primary, worktree } = gitPrimary(); const h = harness({ cwd: join(primary, "doc"), branch: [phaseResult("start", phases({ brainstorm: "in_progress" }))] }); await h.emit("session_start"); assert.ok(blocked(await h.emitEvent("tool_call", bashCall("b1", "git switch -c y"))), "bare switch from /doc blocks"); assert.ok(blocked(await h.emitEvent("tool_call", bashCall("b2", `git -C ${primary} switch -c y`))), "-C blocks"); assert.ok(!blocked(await h.emitEvent("tool_call", bashCall("b3", `git -C ${worktree} switch -c y`))), "-C passes"); assert.ok(!blocked(await h.emitEvent("tool_call", bashCall("b4", `cd ${worktree} && git checkout -b y`))), "cd passes"); assert.ok(!blocked(await h.emitEvent("tool_call", bashCall("b5", "git -C /nonexistent/dir switch -c y"))), "unresolvable target passes"); assert.ok(!blocked(await h.emitEvent("tool_call", bashCall("b6", "git worktree add .worktrees/y -b y"))), "git worktree is exempt"); }); test("plan_check pass: text, details, and stamp arming when a flow is entered", async () => { const dir = gitPrimary().primary; const { planPath, specPath, planText, specText } = writePlanFixture(dir, { mutatePlan: t => t.replace(/- Create: lib\/task[12]\.test\.ts\n/g, "") .replace(/skipped - lib\/task[12]\.test\.ts created by this task/g, "pass"), }); mkdirSync(join(dir, "lib"), { recursive: true }); writeFileSync(join(dir, "lib/task1.test.ts"), ""); writeFileSync(join(dir, "lib/task2.test.ts"), ""); const h = harness({ cwd: dir, branch: readyForImplementBranch }); await h.emit("session_start"); const tool = h.tools.find((t) => t.name === "plan_check")!; const res = (await tool.execute("t1", { planPath }, undefined, undefined, h.ctx)) as { content: { text: string }[]; details: { status: string; planPath: string; planSha256: string; specPath: string; specSha256: string }; }; assert.match(res.content[0].text, /^PASS[^\n]*\n\nmanifest: /); const manifestLines = res.content[0].text.split("\n").slice(2); assert.equal(manifestLines[0], `manifest: ${planPath} | spec: ${specPath} | tasks: 2 | waves: 1`); assert.deepEqual(manifestLines.slice(1).map(line => JSON.parse(line).task), [1, 2]); const repeated = await tool.execute("repeat", { planPath }, undefined, undefined, h.ctx); assert.deepEqual(repeated, res); assert.equal(res.details.status, "pass"); assert.equal(res.details.planPath, planPath); assert.equal(res.details.specPath, specPath); assert.equal(res.details.planSha256, sha256Hex(readFileSync(planPath))); assert.equal(res.details.specSha256, sha256Hex(readFileSync(specPath))); assert.ok(isAbsolute(res.details.planPath)); assert.ok(isAbsolute(res.details.specPath)); // stamp armed: implement-start now succeeds. const phaseTool = h.tools.find((t) => t.name === "phase_tracker")!; const start = (await phaseTool.execute("t2", { action: "start", phase: "implement" }, undefined, undefined, h.ctx)) as { details: { error?: string; phases: { implement: { status: string } } }; }; assert.equal(start.details.error, undefined); assert.equal(start.details.phases.implement.status, "in_progress"); void planText; void specText; }); for (const failure of [false, true]) { test(`plan_check missing baseline${failure ? " with base failure" : ""} prevents implement stamp`, async () => { const dir = gitPrimary().primary; const command = "node --test lib/task1.test.ts"; const row = `- Task 1: \`${command}\` fails on abc1234 (exit 2): assertion failed`; const { planPath } = writePlanFixture(dir, { mutatePlan: t => t.replace("- baseline: abc1234 skipped - lib/task1.test.ts created by this task\n", "") + (failure ? "\n## Open Questions\n" + row + "\n" : ""), }); const h = harness({ cwd: dir, branch: readyForImplementBranch }); await h.emit("session_start"); const tool = h.tools.find(t => t.name === "plan_check")!; const result = await tool.execute("baseline", { planPath }, undefined, undefined, h.ctx) as { details: { status: string; findings: { check: string; reason: string }[] }; }; assert.equal(result.details.status, "fail"); assert.ok(result.details.findings.some(f => f.check === "baseline-line" && f.reason.includes("Task 1"))); if (failure) assert.ok(result.details.findings.some(f => f.reason === "plan has open questions: " + row)); const phase = h.tools.find(t => t.name === "phase_tracker")!; const start = await phase.execute("start", { action: "start", phase: "implement" }, undefined, undefined, h.ctx) as { details: { error?: string; phases: { implement: { status: string } } }; }; assert.match(start.details.error ?? "", /plan_check/); assert.notEqual(start.details.phases.implement.status, "in_progress"); }); } test("plan_check pass outside a flow: no stamp, plain-linter text", async () => { const dir = gitPrimary().primary; const { planPath } = writePlanFixture(dir); const h = harness({ cwd: dir }); await h.emit("session_start"); const tool = h.tools.find((t) => t.name === "plan_check")!; const res = (await tool.execute("t1", { planPath }, undefined, undefined, h.ctx)) as { content: { text: string }[] }; assert.match(res.content[0].text, /^PASS \(no flow to stamp\)\n\nmanifest: /); }); test("plan_check fail: mutated plan body, no error key, clears stamp", async () => { const dir = gitPrimary().primary; const { planPath } = writePlanFixture(dir, { mutatePlan: (t) => t.replace("implements helperFn() for parsing.", "implements the helper for parsing."), }); const h = harness({ cwd: dir, branch: readyForImplementBranch }); await h.emit("session_start"); const tool = h.tools.find((t) => t.name === "plan_check")!; const res = (await tool.execute("t1", { planPath }, undefined, undefined, h.ctx)) as { content: { text: string }[]; details: { status: string; error?: string }; }; assert.match(res.content[0].text, /^FAIL/); assert.ok(!res.content[0].text.includes("\nmanifest:")); assert.equal(res.details.status, "fail"); assert.equal("error" in res.details, false); const phaseTool = h.tools.find((t) => t.name === "phase_tracker")!; const start = (await phaseTool.execute("t2", { action: "start", phase: "implement" }, undefined, undefined, h.ctx)) as { details: { error?: string }; }; assert.match(start.details.error ?? "", /plan_check/); }); test("plan_check fail: unresolvable spec path", async () => { const dir = gitPrimary().primary; const { planPath } = writePlanFixture(dir, { mutatePlan: (t) => t.replace("**Spec:** `doc/specs/spec.md`", "**Spec:** `missing-spec.md`"), }); const h = harness({ cwd: dir, branch: readyForImplementBranch }); await h.emit("session_start"); const tool = h.tools.find((t) => t.name === "plan_check")!; const res = (await tool.execute("t1", { planPath }, undefined, undefined, h.ctx)) as { content: { text: string }[]; details: { status: string; findings?: { check: string }[]; error?: string }; }; assert.match(res.content[0].text, /^FAIL/); assert.equal(res.details.status, "fail"); assert.equal("error" in res.details, false); assert.ok(res.details.findings?.some((f) => f.check === "input")); const phaseTool = h.tools.find((t) => t.name === "phase_tracker")!; const start = (await phaseTool.execute("t2", { action: "start", phase: "implement" }, undefined, undefined, h.ctx)) as { details: { error?: string }; }; assert.match(start.details.error ?? "", /plan_check/); }); test("plan_check fail: header **Spec:** extraction is confined to the header (a path-only-looking line below the separator does not count)", async () => { const dir = gitPrimary().primary; const { planPath } = writePlanFixture(dir, { mutatePlan: (t) => t .replace("**Spec:** `doc/specs/spec.md`\n\n", "") .replace( "## Wave 1 - Two parallel tasks", "## Wave 1 - Two parallel tasks\n\n**Spec:** `not-the-header-spec.md`\n", ), }); const h = harness({ cwd: dir, branch: readyForImplementBranch }); await h.emit("session_start"); const tool = h.tools.find((t) => t.name === "plan_check")!; const res = (await tool.execute("t1", { planPath }, undefined, undefined, h.ctx)) as { content: { text: string }[]; details: { status: string; findings?: { check: string; reason: string }[] }; }; assert.match(res.content[0].text, /^FAIL/); assert.equal(res.details.status, "fail"); assert.ok( res.details.findings?.some((f) => f.reason.includes("no path-only **Spec:** header line found in plan")), `expected the missing-header-spec finding, got: ${JSON.stringify(res.details.findings)}`, ); }); test("plan_check fail: plan header has no path-only **Spec:** line at all", async () => { const dir = gitPrimary().primary; const { planPath } = writePlanFixture(dir, { mutatePlan: (t) => t.replace("**Spec:** `doc/specs/spec.md`\n\n", ""), }); const h = harness({ cwd: dir, branch: readyForImplementBranch }); await h.emit("session_start"); const tool = h.tools.find((t) => t.name === "plan_check")!; const res = (await tool.execute("t1", { planPath }, undefined, undefined, h.ctx)) as { content: { text: string }[]; details: { status: string; findings?: { check: string }[] }; }; assert.match(res.content[0].text, /^FAIL/); assert.equal(res.details.status, "fail"); assert.ok(res.details.findings?.some((f) => f.check === "input")); const phaseTool = h.tools.find((t) => t.name === "phase_tracker")!; const start = (await phaseTool.execute("t2", { action: "start", phase: "implement" }, undefined, undefined, h.ctx)) as { details: { error?: string }; }; assert.match(start.details.error ?? "", /plan_check/); }); test("implement-start gate: rejects with no stamp, names plan_check remedy", async () => { const h = harness({ branch: readyForImplementBranch }); await h.emit("session_start"); const tool = h.tools.find((t) => t.name === "phase_tracker")!; const res = (await tool.execute("t1", { action: "start", phase: "implement" }, undefined, undefined, h.ctx)) as { content: { text: string }[]; details: { error?: string }; }; assert.match(res.content[0].text, /plan_check/); assert.ok(res.details.error); }); test("implement-start gate: stale plan bytes rejected, names the stale file", async () => { const dir = gitPrimary().primary; const { planPath } = writePlanFixture(dir); const h = harness({ cwd: dir, branch: readyForImplementBranch }); await h.emit("session_start"); const planCheck = h.tools.find((t) => t.name === "plan_check")!; await planCheck.execute("t1", { planPath }, undefined, undefined, h.ctx); writeFileSync(planPath, readFileSync(planPath, "utf8") + "\nx"); const phaseTool = h.tools.find((t) => t.name === "phase_tracker")!; const res = (await phaseTool.execute("t2", { action: "start", phase: "implement" }, undefined, undefined, h.ctx)) as { details: { error?: string }; }; assert.match(res.details.error ?? "", /stale/); assert.match(res.details.error ?? "", new RegExp(planPath.replace(/[/.]/g, "\\$&"))); }); test("implement-start gate: stale spec bytes rejected, names the stale file", async () => { const dir = gitPrimary().primary; const { planPath, specPath } = writePlanFixture(dir); const h = harness({ cwd: dir, branch: readyForImplementBranch }); await h.emit("session_start"); const planCheck = h.tools.find((t) => t.name === "plan_check")!; await planCheck.execute("t1", { planPath }, undefined, undefined, h.ctx); writeFileSync(specPath, readFileSync(specPath, "utf8") + "\nx"); const phaseTool = h.tools.find((t) => t.name === "phase_tracker")!; const res = (await phaseTool.execute("t2", { action: "start", phase: "implement" }, undefined, undefined, h.ctx)) as { details: { error?: string }; }; assert.match(res.details.error ?? "", /stale/); assert.match(res.details.error ?? "", new RegExp(specPath.replace(/[/.]/g, "\\$&"))); }); test("implement-start gate: missing stamped file rejected, names the missing path", async () => { const dir = gitPrimary().primary; const { planPath } = writePlanFixture(dir); const h = harness({ cwd: dir, branch: readyForImplementBranch }); await h.emit("session_start"); const planCheck = h.tools.find((t) => t.name === "plan_check")!; await planCheck.execute("t1", { planPath }, undefined, undefined, h.ctx); rmSync(planPath); const phaseTool = h.tools.find((t) => t.name === "phase_tracker")!; const res = (await phaseTool.execute("t2", { action: "start", phase: "implement" }, undefined, undefined, h.ctx)) as { details: { error?: string }; }; assert.match(res.details.error ?? "", /missing/); assert.match(res.details.error ?? "", new RegExp(planPath.replace(/[/.]/g, "\\$&"))); }); test("implement-start gate: enforce false skips the gate entirely", async () => { const dir = tempCwd({ piGauntlet: { flowGuards: { enforce: false } } }); const h = harness({ cwd: dir, branch: readyForImplementBranch }); await h.emit("session_start"); const phaseTool = h.tools.find((t) => t.name === "phase_tracker")!; const res = (await phaseTool.execute("t1", { action: "start", phase: "implement" }, undefined, undefined, h.ctx)) as { details: { error?: string; phases: { implement: { status: string } } }; }; assert.equal(res.details.error, undefined); assert.equal(res.details.phases.implement.status, "in_progress"); }); test("replay: a passing plan_check result restores the stamp without re-running the tool", async () => { const dir = gitPrimary().primary; const { planPath, specPath } = writePlanFixture(dir); const passDetails = { status: "pass", planPath, planSha256: sha256Hex(readFileSync(planPath)), specPath, specSha256: sha256Hex(readFileSync(specPath)), }; const h = harness({ cwd: dir, branch: [...readyForImplementBranch, planCheckResult(passDetails)] }); await h.emit("session_start"); const phaseTool = h.tools.find((t) => t.name === "phase_tracker")!; const res = (await phaseTool.execute("t1", { action: "start", phase: "implement" }, undefined, undefined, h.ctx)) as { details: { error?: string; phases: { implement: { status: string } } }; }; assert.equal(res.details.error, undefined); assert.equal(res.details.phases.implement.status, "in_progress"); }); test("replay: pass then fail clears the stamp", async () => { const dir = gitPrimary().primary; const { planPath, specPath } = writePlanFixture(dir); const passDetails = { status: "pass", planPath, planSha256: sha256Hex(readFileSync(planPath)), specPath, specSha256: sha256Hex(readFileSync(specPath)), }; const failDetails = { status: "fail", planPath }; const h = harness({ cwd: dir, branch: [...readyForImplementBranch, planCheckResult(passDetails), planCheckResult(failDetails)], }); await h.emit("session_start"); const phaseTool = h.tools.find((t) => t.name === "phase_tracker")!; const res = (await phaseTool.execute("t1", { action: "start", phase: "implement" }, undefined, undefined, h.ctx)) as { details: { error?: string }; }; assert.match(res.details.error ?? "", /plan_check/); }); test("replay: a plan_check pass observed before any flow entry does not arm the stamp, and a live walk with no live plan_check is rejected", async () => { const dir = gitPrimary().primary; const { planPath, specPath } = writePlanFixture(dir); const passDetails = { status: "pass", planPath, planSha256: sha256Hex(readFileSync(planPath)), specPath, specSha256: sha256Hex(readFileSync(specPath)), }; // plan_check pass happens with gauntletEntered still false: no phase_tracker // history precedes it in the branch. const h = harness({ cwd: dir, branch: [planCheckResult(passDetails)] }); await h.emit("session_start"); const phaseTool = h.tools.find((t) => t.name === "phase_tracker")!; await phaseTool.execute("t1", { action: "start", phase: "brainstorm" }, undefined, undefined, h.ctx); await phaseTool.execute("t2", { action: "complete", phase: "brainstorm" }, undefined, undefined, h.ctx); await phaseTool.execute("t3", { action: "start", phase: "plan" }, undefined, undefined, h.ctx); await phaseTool.execute("t4", { action: "complete", phase: "plan" }, undefined, undefined, h.ctx); const res = (await phaseTool.execute("t5", { action: "start", phase: "implement" }, undefined, undefined, h.ctx)) as { details: { error?: string }; }; assert.match(res.details.error ?? "", /plan_check/); }); test("replay: a phase_tracker reset clears the stamp", async () => { const dir = gitPrimary().primary; const { planPath, specPath } = writePlanFixture(dir); const passDetails = { status: "pass", planPath, planSha256: sha256Hex(readFileSync(planPath)), specPath, specSha256: sha256Hex(readFileSync(specPath)), }; const h = harness({ cwd: dir, branch: [ ...readyForImplementBranch, planCheckResult(passDetails), phaseResult("reset", phases()), ...readyForImplementBranch, ], }); await h.emit("session_start"); const phaseTool = h.tools.find((t) => t.name === "phase_tracker")!; const res = (await phaseTool.execute("t1", { action: "start", phase: "implement" }, undefined, undefined, h.ctx)) as { details: { error?: string }; }; assert.match(res.details.error ?? "", /plan_check/); }); test("replay via session_fork: a passing plan_check result restores the stamp without re-running the tool", async () => { const dir = gitPrimary().primary; const { planPath, specPath } = writePlanFixture(dir); const passDetails = { status: "pass", planPath, planSha256: sha256Hex(readFileSync(planPath)), specPath, specSha256: sha256Hex(readFileSync(specPath)), }; const h = harness({ cwd: dir, branch: [...readyForImplementBranch, planCheckResult(passDetails)] }); // The child fork inherits the parent's branch; phase-tracker must rebuild // phases/gauntletEntered/the stamp from replay on session_fork exactly as it // does on session_start. Without that rebuild, gauntletEntered would stay // false (its un-replayed default) and the implement-start gate below would // be skipped entirely rather than genuinely satisfied - the plan.status // assertion is what tells the two apart (a skipped gate leaves plan pending). await h.emit("session_fork"); const phaseTool = h.tools.find((t) => t.name === "phase_tracker")!; const res = (await phaseTool.execute("t1", { action: "start", phase: "implement" }, undefined, undefined, h.ctx)) as { details: { error?: string; phases: { plan: { status: string }; implement: { status: string } } }; }; assert.equal(res.details.error, undefined); assert.equal(res.details.phases.plan.status, "complete"); assert.equal(res.details.phases.implement.status, "in_progress"); }); test("replay via session_tree: a passing plan_check result restores the stamp without re-running the tool", async () => { const dir = gitPrimary().primary; const { planPath, specPath } = writePlanFixture(dir); const passDetails = { status: "pass", planPath, planSha256: sha256Hex(readFileSync(planPath)), specPath, specSha256: sha256Hex(readFileSync(specPath)), }; const h = harness({ cwd: dir, branch: [...readyForImplementBranch, planCheckResult(passDetails)] }); // Fork/tree sessions follow the same branch-replay semantics as fork/switch: // phase-tracker must rebuild phases/gauntletEntered/the stamp from replay on // session_tree exactly as it does on the other three events. Without that // rebuild, gauntletEntered would stay false (its un-replayed default) and // the implement-start gate below would be skipped entirely rather than // genuinely satisfied - the plan.status assertion is what tells the two // apart (a skipped gate leaves plan pending). await h.emit("session_tree"); const phaseTool = h.tools.find((t) => t.name === "phase_tracker")!; const res = (await phaseTool.execute("t1", { action: "start", phase: "implement" }, undefined, undefined, h.ctx)) as { details: { error?: string; phases: { plan: { status: string }; implement: { status: string } } }; }; assert.equal(res.details.error, undefined); assert.equal(res.details.phases.plan.status, "complete"); assert.equal(res.details.phases.implement.status, "in_progress"); }); test("replay via session_switch: pass then fail clears the stamp, rebuilt from replay rather than a live run", async () => { const dir = gitPrimary().primary; const { planPath, specPath } = writePlanFixture(dir); const passDetails = { status: "pass", planPath, planSha256: sha256Hex(readFileSync(planPath)), specPath, specSha256: sha256Hex(readFileSync(specPath)), }; const failDetails = { status: "fail", planPath }; const h = harness({ cwd: dir, branch: [...readyForImplementBranch, planCheckResult(passDetails), planCheckResult(failDetails)], }); // session_switch must rebuild gauntletEntered (true, from the replayed // readyForImplementBranch entries) and the stamp (armed by the pass, then // cleared by the fail) purely from replay - no plan_check tool call happens // in this test. If the rebuild didn't run, gauntletEntered would stay false // and the implement-start gate would be skipped (no error) instead of // rejecting for a stale/missing stamp, so this assertion distinguishes the // two. await h.emit("session_switch"); const phaseTool = h.tools.find((t) => t.name === "phase_tracker")!; const res = (await phaseTool.execute("t1", { action: "start", phase: "implement" }, undefined, undefined, h.ctx)) as { details: { error?: string }; }; assert.match(res.details.error ?? "", /plan_check/); }); test("gauntlet_setting escalationLoop: setting absent -> ctx-derived main-loop model; setting wins when set", async () => { const h = harness({ cwd: tempCwd({ piGauntlet: {} }), model: { provider: "p", id: "main" }, thinkingLevel: "medium" }); const tool = h.tools.find((t) => t.name === "gauntlet_setting")!; const absent = (await tool.execute("g1", { key: "escalationLoop" }, undefined, undefined, h.ctx)) as { details: { key: string; implModel?: string; errors: string[] } }; assert.deepEqual(absent.details, { key: "escalationLoop", implModel: "p/main:medium", errors: [] }); const set = harness({ cwd: tempCwd({ piGauntlet: { escalationLoop: { implModel: "p/strong:high" } } }), model: { provider: "p", id: "main" }, thinkingLevel: "medium" }); const res = (await set.tools.find((t) => t.name === "gauntlet_setting")!.execute("g2", { key: "escalationLoop" }, undefined, undefined, set.ctx)) as { details: { implModel?: string } }; assert.equal(res.details.implModel, "p/strong:high"); }); test("gauntlet_setting loopEngine resolves the key", async () => { for (const [loopEngine, expected, escalateAfter, warning] of [ [undefined, 4, 3, undefined], [{ maxIterationsPerRow: 8, escalateAfter: 2 }, 8, 2, undefined], [{ escalateAfter: 0 }, 4, 1, undefined], [{ maxIterations: 99, maxIterationsPerRow: "4", escalateAfter: "3" }, 4, 3, "loopEngine.maxIterations is removed; set loopEngine.maxIterationsPerRow; loopEngine.maxIterationsPerRow must be an integer; using default 4; loopEngine.escalateAfter must be an integer; using default 3"], ] as const) { const h = harness({ cwd: tempCwd({ piGauntlet: { loopEngine } }) }); const tool = h.tools.find(t => t.name === "gauntlet_setting")!; const result = await tool.execute("loop", { key: "loopEngine" }, undefined, undefined, h.ctx) as any; assert.deepEqual(result.details, { key: "loopEngine", maxIterationsPerRow: expected, escalateAfter, warning, errors: [] }); assert.equal(Object.hasOwn(result.details, "maxIterations"), false); } }); test("gauntlet_setting loopEngine composes settings load warnings", async () => { const dir = tempCwd({}); writeFileSync(join(dir, ".pi/settings.json"), "{"); const h = harness({ cwd: dir }); const result = await h.tools.find(t => t.name === "gauntlet_setting")!.execute("loop", { key: "loopEngine" }, undefined, undefined, h.ctx) as any; assert.equal(result.details.key, "loopEngine"); assert.equal(result.details.maxIterationsPerRow, 4); assert.equal(result.details.escalateAfter, 3); assert.equal(Object.hasOwn(result.details, "maxIterations"), false); assert.ok(result.details.errors.length); assert.equal(result.details.warning, `⚠️ gauntlet settings load error (using defaults): ${result.details.errors.join("; ")}`); }); test("ledger handler stamps after brainstorm and skipped plan, then admits implement", async () => { const dir = gitPrimary().primary; mkdirSync(join(dir, "doc/specs"), { recursive: true }); mkdirSync(join(dir, "doc/plans"), { recursive: true }); writeFileSync(join(dir, "doc/specs/loop.md"), "# Spec\n## Acceptance criteria\n- [ ] Works\n"); const planPath = join(dir, "doc/plans/loop-ledger.md"); writeFileSync(planPath, "# Ledger - loop engine\n**Spec:** `doc/specs/loop.md`\nbase: abc\nverification: check\niterations: 0\n\n| row | status | attempts | evidence |\n|---|---|---|---|\n| 1 | open | 0 | |\n\n## Decisions\n"); const h = harness({ cwd: dir }); await h.emit("session_start"); const phase = h.tools.find(t => t.name === "phase_tracker")!; const call = (action: string, p: string, reason?: string) => phase.execute("phase", { action, phase: p, reason }, undefined, undefined, h.ctx) as Promise; await call("start", "brainstorm"); await call("complete", "brainstorm"); await call("skip", "plan", "loop engine"); const checked = await h.tools.find(t => t.name === "plan_check")!.execute("check", { planPath }, undefined, undefined, h.ctx) as any; assert.equal(checked.details.status, "pass"); assert.equal(checked.content[0].text, "PASS \u2014 plan verified and stamped for implement-start"); assert.equal(checked.details.planSha256, sha256Hex(readFileSync(planPath))); const started = await call("start", "implement"); assert.equal(started.details.error, undefined); assert.equal(started.details.phases.implement.status, "in_progress"); }); test("gauntlet_setting flowGuards: default dirs + derived plan dirs; repo override replaces them", async () => { const h = harness({ cwd: tempCwd({ piGauntlet: {} }) }); const tool = h.tools.find((t) => t.name === "gauntlet_setting")!; const def = (await tool.execute("f1", { key: "flowGuards" }, undefined, undefined, h.ctx)) as { details: unknown }; assert.deepEqual(def.details, { key: "flowGuards", enforce: true, specDirs: ["doc/specs", "docs/specs"], planDirs: ["doc/plans", "docs/plans"], errors: [] }); const set = harness({ cwd: tempCwd({ piGauntlet: { flowGuards: { specDirs: ["design/specs"] } } }) }); const res = (await set.tools.find((t) => t.name === "gauntlet_setting")!.execute("f2", { key: "flowGuards" }, undefined, undefined, set.ctx)) as { details: { specDirs: string[]; planDirs: string[] } }; assert.deepEqual(res.details.specDirs, ["design/specs"]); assert.deepEqual(res.details.planDirs, ["design/plans"]); }); // --- Conformance fix-loop dispatch guard (spec 2026-09-13-conformance-dispatch-guard) --- const verifyBranch = (extra: unknown[] = []) => [ ...implementBranch(), phaseResult("complete", phases({ brainstorm: "complete", plan: "complete", implement: "complete" })), phaseResult("start", phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "in_progress" })), ...extra, ]; const subagentCall = (id: string, input: unknown) => ({ toolName: "subagent", toolCallId: id, input }); const loneImplementer = (extra: Record = {}) => ({ agent: "implementer", task: "fix G1", ...extra }); const implementerWave = (n = 1, agent = "implementer") => ({ tasks: Array.from({ length: n }, (_, i) => ({ agent, task: `fix G${i + 1}`, worktree: true })), }); const firstCallResult = async (h: ReturnType, id: string, input: unknown) => (await h.emitEvent("tool_call", subagentCall(id, input)))[0] as { block?: boolean; reason?: string } | undefined; for (const agent of ["implementer", "loop-implementer"]) { test(`shape guard: lone ${agent} blocked in verify after the audit, with and without closureReview.model, async or not`, async () => { for (const settings of [ { piGauntlet: { closureReview: { enforce: true } } }, { piGauntlet: { closureReview: { enforce: true, model: "x/y" } } }, ]) { const h = harness({ cwd: tempCwd(settings), branch: verifyBranch([subagentResult(["conformance-reviewer"])]) }); await h.emit("session_start"); const sync = await firstCallResult(h, "s1", loneImplementer({ agent })); assert.equal(sync?.block, true); assert.match(sync?.reason ?? "", /dispatch implementers as a one-task tasks wave/); assert.match(sync?.reason ?? "", /piGauntlet\.closureReview\.enforce: false/); const async = await firstCallResult(h, "s2", loneImplementer({ agent, async: true })); assert.equal(async?.block, true); } }); test(`shape guard: lone ${agent} passes before the audit, in implement, in ship, and on management calls`, async () => { const preLatch = harness({ branch: verifyBranch() }); await preLatch.emit("session_start"); assert.equal(await firstCallResult(preLatch, "s1", loneImplementer({ agent })), undefined); const implement = harness({ branch: implementBranch([subagentResult(["conformance-reviewer"])]) }); await implement.emit("session_start"); assert.equal(await firstCallResult(implement, "s1", loneImplementer({ agent })), undefined); const ship = harness({ branch: verifyBranch([ subagentResult(["conformance-reviewer"]), phaseResult("complete", phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "complete" })), phaseResult("start", phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "complete", ship: "in_progress" })), ]), }); await ship.emit("session_start"); assert.equal(await firstCallResult(ship, "s1", loneImplementer({ agent })), undefined); const mgmt = harness({ branch: verifyBranch([subagentResult(["conformance-reviewer"])]) }); await mgmt.emit("session_start"); assert.equal(await firstCallResult(mgmt, "s1", { action: "status", agent }), undefined); }); } test("shape guard: dormant when the flow was never entered (cold start verify) and when closureReview.enforce is false", async () => { const cold = harness({ cwd: tempCwd({ piGauntlet: { closureReview: { maxFixRounds: 0 } } }), branch: [phaseResult("start", phases({ verify: "in_progress" })), subagentResult(["conformance-reviewer"])], }); await cold.emit("session_start"); assert.equal(await firstCallResult(cold, "s1", loneImplementer()), undefined); assert.equal(await firstCallResult(cold, "s2", implementerWave(1)), undefined); assert.equal(await firstCallResult(cold, "s3", { chain: [{ agent: "implementer", task: "fix" }] }), undefined); const off = harness({ cwd: tempCwd({ piGauntlet: { closureReview: { enforce: false } } }), branch: verifyBranch([subagentResult(["conformance-reviewer"])]), }); await off.emit("session_start"); assert.equal(await firstCallResult(off, "s1", loneImplementer()), undefined); }); test("shape guard: a one-task tasks wave and a chain step are not the lone shape", async () => { const h = harness({ branch: verifyBranch([subagentResult(["conformance-reviewer"])]) }); await h.emit("session_start"); assert.equal(await firstCallResult(h, "s1", implementerWave(1)), undefined); assert.equal(await firstCallResult(h, "s2", { chain: [{ agent: "implementer", task: "fix" }] }), undefined); }); const waveResult = (id: string, results: { agent: string; exitCode: number; interrupted?: boolean }[], isError = false) => ({ toolName: "subagent", toolCallId: id, isError, content: [], details: { results }, }); const okWave = (id: string) => waveResult(id, [{ agent: "implementer", exitCode: 0 }]); for (const delivery of ["live", "session_start", "session_switch", "session_fork", "session_tree"]) { test(`closure completion excludes interrupted children per result: ${delivery}`, async () => { const cwd = tempCwd(); const reviewer = { agent: "conformance-reviewer", exitCode: 0 }; for (const row of [ { name: "interrupted single/resumed child", results: [{ ...reviewer, interrupted: true }], qualifies: false }, { name: "legacy success", results: [reviewer], qualifies: true }, { name: "explicit uninterrupted", results: [{ ...reviewer, interrupted: false }], qualifies: true }, { name: "nonzero exit", results: [{ ...reviewer, exitCode: 1 }], qualifies: false }, { name: "exact agent match", results: [{ agent: "conformance-reviewer-extra", exitCode: 0 }], qualifies: false }, { name: "empty async/management", results: [], qualifies: false }, { name: "mixed parallel", results: [{ ...reviewer, interrupted: true }, reviewer], qualifies: true }, { name: "earlier success in errored chain", results: [reviewer, { agent: "implementer", exitCode: 1 }], isError: true, qualifies: true }, ]) { const result = waveResult("review", row.results, row.isError); const h = harness({ cwd, branch: verifyBranch() }); await h.emit("session_start"); if (delivery === "live") await h.emitEvent("tool_result", result); else { h.setBranch(verifyBranch([{ type: "message", message: { role: "toolResult", ...result } }])); await h.emit(delivery); } assert.equal((await completePhase(h, "verify")).details.error, row.qualifies ? undefined : "no conformance-reviewer dispatch observed", row.name); } }); test(`cadence completion excludes interrupted children and preserves ties: ${delivery}`, async () => { const cwd = tempCwd(); const implementer = { agent: "implementer", exitCode: 0 }; for (const row of [ { name: "interrupted implementer", results: [{ ...implementer, interrupted: true }], prior: false, warns: false }, { name: "interrupted wave reviewer", results: [{ agent: "wave-reviewer", exitCode: 0, interrupted: true }], prior: true, warns: true }, { name: "legacy implementer", results: [implementer], prior: false, warns: true }, { name: "explicit uninterrupted wave reviewer", results: [{ agent: "wave-reviewer", exitCode: 0, interrupted: false }], prior: true, warns: false }, { name: "failed reviewer", results: [{ agent: "wave-reviewer", exitCode: 1 }], prior: true, warns: true }, { name: "wrong agent", results: [{ agent: "spec-reviewer-extra", exitCode: 0 }], prior: true, warns: true }, { name: "empty async/management", results: [], prior: true, warns: true }, { name: "mixed parallel tie", results: [implementer, { agent: "wave-reviewer", exitCode: 0 }, { agent: "wave-reviewer", exitCode: 0, interrupted: true }], prior: false, warns: false }, { name: "earlier review in errored chain", results: [{ agent: "wave-reviewer", exitCode: 0 }, { ...implementer, interrupted: true }], prior: true, isError: true, warns: false }, ]) { const prior = row.prior ? [subagentResult(["implementer"])] : []; const result = waveResult("work", row.results, row.isError); const h = harness({ cwd, branch: implementBranch(prior) }); await h.emit("session_start"); if (delivery === "live") await h.emitEvent("tool_result", result); else { h.setBranch(implementBranch([...prior, { type: "message", message: { role: "toolResult", ...result } }])); await h.emit(delivery); } await h.emitEvent("tool_call", commitCall("commit")); const [warning] = await h.emitEvent("tool_result", commitResult("commit")) as ({ content: { text: string }[] } | undefined)[]; assert.equal(warning !== undefined, row.warns, row.name); if (warning) assert.match(warning.content[0].text, /no wave-reviewer observed/, row.name); } }); } test("interrupted implementer waves still spend rounds and granted credits and nudge open tasks live and on replay", async () => { const cwd = tempCwd({ piGauntlet: { closureReview: { maxFixRounds: 1 } } }); const interrupted = waveResult("paused", [{ agent: "implementer", exitCode: 0, interrupted: true }]); for (const delivery of ["live", "session_start"]) { const trail = [subagentResult(["conformance-reviewer"]), taskSnapshot([{ name: "repair", status: "in_progress" }])]; const h = harness({ cwd, branch: verifyBranch(trail) }); await h.emit("session_start"); if (delivery === "live") { const [nudge] = await h.emitEvent("tool_result", interrupted) as { content: { text: string }[] }[]; assert.match(nudge.content[0].text, /0: repair \(in_progress\)/); } else { h.setBranch(verifyBranch([...trail, { type: "message", message: { role: "toolResult", ...interrupted } }])); await h.emit(delivery); } assert.equal((await firstCallResult(h, "blocked", implementerWave()))?.block, true); assert.equal((await grant(h, "grant", { rounds: 1, reason: "one more repair" })).details.error, undefined); assert.equal(await firstCallResult(h, "funded", implementerWave()), undefined); if (delivery === "live") await h.emitEvent("tool_result", interrupted); else { h.setBranch(verifyBranch([...trail, { type: "message", message: { role: "toolResult", ...interrupted } }, grantResult(1), { type: "message", message: { role: "toolResult", ...interrupted } }, ])); await h.emit(delivery); } assert.equal((await firstCallResult(h, "spent", implementerWave()))?.block, true); assert.equal((await grant(h, "again", { rounds: 1, reason: "another repair" })).details.error, undefined); } }); const guardedHarness = (settings: unknown, extra: unknown[] = []) => harness({ cwd: tempCwd(settings), branch: verifyBranch([subagentResult(["conformance-reviewer"]), ...extra]) }); for (const agent of ["implementer", "loop-implementer"]) { test(`cap guard: default 5 ${agent} waves pass, the sixth is blocked with the escalation text`, async () => { const h = guardedHarness({ piGauntlet: { closureReview: { enforce: true } } }); await h.emit("session_start"); for (let i = 1; i <= 5; i++) { assert.equal(await firstCallResult(h, `c${i}`, implementerWave(2, agent)), undefined, `round ${i} passes`); await h.emitEvent("tool_result", waveResult(`c${i}`, [{ agent, exitCode: 0 }, { agent, exitCode: 1 }])); } const blocked = await firstCallResult(h, "c6", implementerWave(1, agent)); assert.equal(blocked?.block, true); assert.match(blocked?.reason ?? "", /^Conformance fix loop: 5 fix round\(s\) used against a cap of 5 \(granted rounds included\); escalate to the human/); assert.ok((blocked?.reason ?? "").includes("Start the escalation message with the line: gauntlet: gate=verification-before-completion/step-6")); assert.doesNotMatch(blocked?.reason ?? "", /^gauntlet:/); }); } test("cap guard: maxFixRounds 0 blocks the first wave; 1 blocks the second; a chain implementer is cap-checked and counted", async () => { const zero = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 0 } } }); await zero.emit("session_start"); assert.equal((await firstCallResult(zero, "c1", implementerWave(1)))?.block, true); const one = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 1 } } }); await one.emit("session_start"); assert.equal(await firstCallResult(one, "c1", { chain: [{ agent: "implementer", task: "fix" }] }), undefined); await one.emitEvent("tool_result", okWave("c1")); assert.equal((await firstCallResult(one, "c2", implementerWave(1)))?.block, true); }); test("counter: results while closure review enforcement is off do not consume budget", async () => { const h = guardedHarness({ piGauntlet: { closureReview: { enforce: false, maxFixRounds: 1 } } }); await h.emit("session_start"); await h.emitEvent("tool_result", okWave("c1")); await h.emitEvent("tool_result", okWave("c2")); writeFileSync( join(h.ctx.cwd, ".pi", "settings.json"), JSON.stringify({ piGauntlet: { closureReview: { enforce: true, maxFixRounds: 1 } } }), ); assert.equal(await firstCallResult(h, "c3", implementerWave(1)), undefined); }); test("fix-loop guard and counter are dormant in subagent children", async () => { const priorDepth = process.env.PI_SUBAGENT_DEPTH; process.env.PI_SUBAGENT_DEPTH = "1"; let live: ReturnType; let replay: ReturnType; try { live = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 0 } } }); replay = guardedHarness( { piGauntlet: { closureReview: { maxFixRounds: 2 } } }, [subagentResult(["implementer"]), subagentResult(["implementer"])], ); } finally { if (priorDepth === undefined) delete process.env.PI_SUBAGENT_DEPTH; else process.env.PI_SUBAGENT_DEPTH = priorDepth; } await live.emit("session_start"); assert.equal(await firstCallResult(live, "c1", loneImplementer()), undefined); assert.equal(await firstCallResult(live, "c2", implementerWave(1)), undefined); await live.emitEvent("tool_result", okWave("c2")); await replay.emit("session_start"); assert.equal(await firstCallResult(replay, "c3", implementerWave(1)), undefined); }); test("cap guard: non-implementer dispatches never blocked; enforce false passes everything", async () => { const h = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 0 } } }); await h.emit("session_start"); assert.equal(await firstCallResult(h, "r1", { agent: "conformance-reviewer", task: "re-audit" }), undefined); assert.equal(await firstCallResult(h, "r2", { agent: "wave-reviewer", task: "review" }), undefined); const off = guardedHarness({ piGauntlet: { closureReview: { enforce: false, maxFixRounds: 0 } } }); await off.emit("session_start"); assert.equal(await firstCallResult(off, "c1", implementerWave(1)), undefined); assert.equal(await firstCallResult(off, "c2", loneImplementer()), undefined); }); test("counter: blocked, errored, empty, non-implementer, and out-of-window results do not count; non-zero exit does", async () => { const h = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 1 } } }); await h.emit("session_start"); await h.emitEvent("tool_result", waveResult("e1", [{ agent: "implementer", exitCode: 0 }], true)); await h.emitEvent("tool_result", waveResult("e2", [])); await h.emitEvent("tool_result", waveResult("e3", [{ agent: "wave-reviewer", exitCode: 0 }])); const blockedLone = await firstCallResult(h, "b1", loneImplementer()); assert.equal(blockedLone?.block, true); assert.equal(await firstCallResult(h, "c1", implementerWave(1)), undefined, "budget untouched"); await h.emitEvent("tool_result", waveResult("c1", [{ agent: "implementer", exitCode: 1 }])); assert.equal((await firstCallResult(h, "c2", implementerWave(1)))?.block, true); }); test("counter: a ship-phase implementer wave with the latch set does not count", async () => { const h = harness({ cwd: tempCwd({ piGauntlet: { closureReview: { maxFixRounds: 1 } } }), branch: verifyBranch([ subagentResult(["conformance-reviewer"]), phaseResult("complete", phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "complete" })), phaseResult("start", phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "complete", ship: "in_progress" })), subagentResult(["implementer"]), phaseResult("start", phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "in_progress", ship: "in_progress" })), ]), }); await h.emit("session_start"); assert.equal(await firstCallResult(h, "c1", implementerWave(1)), undefined); }); test("counter reset: start implement and reset zero it; start verify --force keeps it", async () => { const mk = () => guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 1 }, flowGuards: { enforce: false } } }, [subagentResult(["implementer"])]); const force = mk(); await force.emit("session_start"); const forceTool = force.tools.find((t) => t.name === "phase_tracker")!; const forced = (await forceTool.execute("p1", { action: "start", phase: "verify", force: true }, undefined, undefined, force.ctx)) as { details: { error?: string } }; assert.equal(forced.details.error, undefined); assert.equal((await firstCallResult(force, "c1", implementerWave(1)))?.block, true, "budget survives verify --force"); const impl = mk(); await impl.emit("session_start"); const implTool = impl.tools.find((t) => t.name === "phase_tracker")!; for (const [id, input] of [ ["p1", { action: "skip", phase: "verify", reason: "amendment" }], ["p2", { action: "start", phase: "implement", force: true }], ["p3", { action: "complete", phase: "implement" }], ["p4", { action: "start", phase: "verify", force: true }], ] as const) { const result = (await implTool.execute(id, input, undefined, undefined, impl.ctx)) as { details: { error?: string } }; assert.equal(result.details.error, undefined); } assert.equal(await firstCallResult(impl, "c1", loneImplementer()), undefined, "latch cleared by start implement"); await impl.emitEvent("tool_result", waveResult("audit", [{ agent: "conformance-reviewer", exitCode: 0 }])); assert.equal(await firstCallResult(impl, "c2", implementerWave(1)), undefined, "counter cleared by start implement"); const reset = mk(); await reset.emit("session_start"); const resetTool = reset.tools.find((t) => t.name === "phase_tracker")!; const resetResult = (await resetTool.execute("p1", { action: "reset" }, undefined, undefined, reset.ctx)) as { details: { error?: string } }; assert.equal(resetResult.details.error, undefined); assert.equal(await firstCallResult(reset, "c1", loneImplementer()), undefined, "dormant after reset"); }); for (const agent of ["implementer", "loop-implementer"]) { test(`replay: two ${agent} waves after the audit in verify restore fixRounds 2; the same waves in ship restore 0`, async () => { const inVerify = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 2 } } }, [ subagentResult([agent]), subagentResult([agent, "wave-reviewer"]), ]); await inVerify.emit("session_start"); assert.equal((await firstCallResult(inVerify, "c1", implementerWave(1, agent)))?.block, true); const inShip = harness({ cwd: tempCwd({ piGauntlet: { closureReview: { maxFixRounds: 2 } } }), branch: verifyBranch([ subagentResult(["conformance-reviewer"]), phaseResult("complete", phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "complete" })), phaseResult("start", phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "complete", ship: "in_progress" })), subagentResult([agent]), subagentResult([agent]), phaseResult("start", phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "in_progress", ship: "in_progress" })), ]), }); await inShip.emit("session_start"); assert.equal(await firstCallResult(inShip, "c1", implementerWave(1, agent)), undefined); }); } // --- Human overrule of the fix-round cap (spec 2026-09-14-fix-round-human-overrule) --- const grantResult = (rounds: number, reason = "human approved") => ({ type: "message", message: { role: "toolResult", toolName: "phase_tracker", details: { action: "grant_fix_rounds", rounds, reason, phases: phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "in_progress" }), } }, }); const grant = async (h: ReturnType, id: string, input: Record) => (await h.tools.find((t) => t.name === "phase_tracker")!.execute(id, { action: "grant_fix_rounds", ...input }, undefined, undefined, h.ctx)) as { content: { type: string; text: string }[]; details: { action: string; rounds?: number; reason?: string; error?: string }; }; const exhaust = async (h: ReturnType, rounds: number, prefix = "x") => { for (let i = 1; i <= rounds; i++) { assert.equal(await firstCallResult(h, `${prefix}${i}`, implementerWave(1)), undefined); await h.emitEvent("tool_result", okWave(`${prefix}${i}`)); } }; test("grant: funds extra waves and rejects another grant while credits remain", async () => { const h = guardedHarness({ piGauntlet: { closureReview: { enforce: true, maxFixRounds: 3 } } }); await h.emit("session_start"); await exhaust(h, 3); const res = await grant(h, "g1", { rounds: 2, reason: "I'm approving 2 more rounds" }); assert.equal(res.details.error, undefined); assert.deepEqual([res.details.rounds, res.details.reason], [2, "I'm approving 2 more rounds"]); assert.equal((await grant(h, "g2", { rounds: 1, reason: "more" })).details.error, "grant_fix_rounds: 2 granted round(s) still unused; spend them before granting more"); await exhaust(h, 2, "c"); const blocked = await firstCallResult(h, "c3", implementerWave(1)); assert.equal(blocked?.block, true); assert.match(blocked?.reason ?? "", /5 fix round\(s\) used against a cap of 3 \(granted rounds included\)/); }); test("grant: schema declares rounds as integer 1..MAX_SAFE_INTEGER; missing rounds or empty reason error without state change", async () => { const h = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 0 } } }); await h.emit("session_start"); const params = h.tools.find((t) => t.name === "phase_tracker")!.parameters; const roundOptions = params.args[0].rounds.args[0].args[0]; assert.equal(params.args[0].rounds.args[0].kind, "Integer"); assert.deepEqual([roundOptions.minimum, roundOptions.maximum], [1, Number.MAX_SAFE_INTEGER]); assert.ok(params.args[0].action.values.includes("grant_fix_rounds")); const noRounds = await grant(h, "g1", { reason: "ok" }); assert.equal(noRounds.details.error, "grant_fix_rounds requires rounds: a positive integer"); assert.equal(noRounds.details.rounds, undefined); const noReason = await grant(h, "g2", { rounds: 1, reason: " " }); assert.equal(noReason.details.error, "grant_fix_rounds requires reason: the human's approval, quoted"); assert.equal(noReason.details.rounds, undefined); assert.equal((await firstCallResult(h, "c1", implementerWave(1)))?.block, true, "no credit was granted"); }); test("grant: rejected when no cap block is live - before the audit, in implement, below the cap, enforce off, and in a child", async () => { const expectNotLive = async (h: ReturnType, used: number, cap: number) => { const res = await grant(h, "g", { rounds: 1, reason: "ok" }); assert.equal(res.details.error, `grant_fix_rounds: no fix-round cap block is active (${used} used, cap ${cap}); nothing to overrule`); }; const preAudit = harness({ cwd: tempCwd({ piGauntlet: { closureReview: { maxFixRounds: 0 } } }), branch: verifyBranch() }); await preAudit.emit("session_start"); await expectNotLive(preAudit, 0, 0); const implement = harness({ cwd: tempCwd({ piGauntlet: { closureReview: { maxFixRounds: 0 } } }), branch: implementBranch([subagentResult(["conformance-reviewer"])]) }); await implement.emit("session_start"); await expectNotLive(implement, 0, 0); const below = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 3 } } }); await below.emit("session_start"); await exhaust(below, 2); await expectNotLive(below, 2, 3); const off = guardedHarness({ piGauntlet: { closureReview: { enforce: false, maxFixRounds: 0 } } }); await off.emit("session_start"); await expectNotLive(off, 0, 0); const priorDepth = process.env.PI_SUBAGENT_DEPTH; process.env.PI_SUBAGENT_DEPTH = "1"; let child: ReturnType; try { child = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 0 } } }); } finally { if (priorDepth === undefined) delete process.env.PI_SUBAGENT_DEPTH; else process.env.PI_SUBAGENT_DEPTH = priorDepth; } await child.emit("session_start"); await expectNotLive(child, 0, 0); }); test("grant: only qualifying synchronous parent task waves spend credits", async () => { const h = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 0 } } }); await h.emit("session_start"); await grant(h, "g", { rounds: 1, reason: "ok" }); await h.emitEvent("tool_result", waveResult("e1", [{ agent: "wave-reviewer", exitCode: 0 }])); await h.emitEvent("tool_result", waveResult("e2", [{ agent: "implementer", exitCode: 0 }], true)); await h.emitEvent("tool_result", waveResult("e3", [])); assert.equal((await firstCallResult(h, "a", { ...implementerWave(1), async: true }))?.block, true); assert.equal((await firstCallResult(h, "l", loneImplementer()))?.block, true); assert.equal(await firstCallResult(h, "c", implementerWave(1)), undefined); await h.emitEvent("tool_result", okWave("c")); assert.equal((await firstCallResult(h, "d", implementerWave(1)))?.block, true); // In a child (PI_SUBAGENT_DEPTH >= 1, fixed at registration) both the cap gate and observeFixWave // are dormant, so credit consumption has no public effect; the observable contract is dormancy. const priorDepth = process.env.PI_SUBAGENT_DEPTH; process.env.PI_SUBAGENT_DEPTH = "1"; let child: ReturnType; try { child = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 0 } } }, [grantResult(1), subagentResult(["implementer"])]); } finally { if (priorDepth === undefined) delete process.env.PI_SUBAGENT_DEPTH; else process.env.PI_SUBAGENT_DEPTH = priorDepth; } await child.emit("session_start"); assert.equal(await firstCallResult(child, "child-wave", implementerWave(1)), undefined, "child session: cap gate and observer are dormant, so the replayed grant and implementer result have no observable effect"); }); test("grant replay restores and spends the recorded pool independent of current cap; rejected grants restore no credit", async () => { const trail = [subagentResult(["implementer"]), subagentResult(["implementer"]), subagentResult(["implementer"]), grantResult(2), subagentResult(["implementer"])]; const h = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 3 } } }, trail); await h.emit("session_start"); assert.equal( (await grant(h, "g", { rounds: 1, reason: "more" })).details.error, "grant_fix_rounds: 1 granted round(s) still unused; spend them before granting more", ); assert.equal(await firstCallResult(h, "c", implementerWave(1)), undefined); await h.emitEvent("tool_result", okWave("c")); const blocked = await firstCallResult(h, "d", implementerWave(1)); assert.equal(blocked?.block, true); assert.match(blocked?.reason ?? "", /5 fix round\(s\) used against a cap of 3 \(granted rounds included\)/); // Same trail at cap 5: replay yields fixRounds = 4 (cap not live yet); lowering the live cap // exposes the one replayed credit, then wave 5 passes on the counter and wave 6 blocks. const capChanged = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 5 } } }, trail); await capChanged.emit("session_start"); assert.equal( (await grant(capChanged, "g", { rounds: 1, reason: "more" })).details.error, "grant_fix_rounds: no fix-round cap block is active (4 used, cap 5); nothing to overrule", "replayed fixRounds = 4 regardless of cap on disk", ); // Lower the cap on disk without spending a wave: the block goes live at 4 >= 3 and the grant // probe now reads the replayed pool - exactly one credit, independent of the cap at replay time. writeFileSync(join(capChanged.ctx.cwd, ".pi", "settings.json"), JSON.stringify({ piGauntlet: { closureReview: { maxFixRounds: 3 } } })); assert.equal( (await grant(capChanged, "g2", { rounds: 1, reason: "more" })).details.error, "grant_fix_rounds: 1 granted round(s) still unused; spend them before granting more", "same credits regardless of cap on disk", ); writeFileSync(join(capChanged.ctx.cwd, ".pi", "settings.json"), JSON.stringify({ piGauntlet: { closureReview: { maxFixRounds: 5 } } })); assert.equal(await firstCallResult(capChanged, "c", implementerWave(1)), undefined); await capChanged.emitEvent("tool_result", okWave("c")); const blockedAt5 = await firstCallResult(capChanged, "d", implementerWave(1)); assert.equal(blockedAt5?.block, true); assert.match(blockedAt5?.reason ?? "", /5 fix round\(s\) used against a cap of 5 \(granted rounds included\)/); const rejected = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 0 } } }, [{ type: "message", message: { role: "toolResult", toolName: "phase_tracker", details: { action: "grant_fix_rounds", error: "grant_fix_rounds requires rounds: a positive integer", phases: phases({ verify: "in_progress" }) }, }, }]); await rejected.emit("session_start"); assert.equal((await firstCallResult(rejected, "c1", implementerWave(1)))?.block, true, "no credits from a rejected grant"); }); test("grant reset: start implement and reset zero credits (live and replay); start verify --force keeps them", async () => { const settings = { piGauntlet: { closureReview: { maxFixRounds: 0 }, flowGuards: { enforce: false } } }; const force = guardedHarness(settings, [grantResult(1)]); await force.emit("session_start"); await force.tools.find((t) => t.name === "phase_tracker")!.execute("p", { action: "start", phase: "verify", force: true }, undefined, undefined, force.ctx); assert.equal(await firstCallResult(force, "c", implementerWave(1)), undefined); const liveImpl = guardedHarness(settings); await liveImpl.emit("session_start"); await grant(liveImpl, "g", { rounds: 1, reason: "ok" }); const tool = liveImpl.tools.find((t) => t.name === "phase_tracker")!; for (const [id, input] of [ ["p1", { action: "skip", phase: "verify", reason: "amendment" }], ["p2", { action: "start", phase: "implement", force: true }], ["p3", { action: "complete", phase: "implement" }], ["p4", { action: "start", phase: "verify", force: true }], ] as const) { assert.equal(((await tool.execute(id, input, undefined, undefined, liveImpl.ctx)) as { details: { error?: string } }).details.error, undefined); } await liveImpl.emitEvent("tool_result", waveResult("audit", [{ agent: "conformance-reviewer", exitCode: 0 }])); assert.equal((await firstCallResult(liveImpl, "c1", implementerWave(1)))?.block, true, "credits zeroed by start implement (cap 0 blocks)"); const reset = guardedHarness(settings); await reset.emit("session_start"); await grant(reset, "g", { rounds: 1, reason: "ok" }); const resetTool = reset.tools.find((t) => t.name === "phase_tracker")!; await resetTool.execute("p", { action: "reset" }, undefined, undefined, reset.ctx); assert.match((await grant(reset, "g2", { rounds: 1, reason: "ok" })).details.error ?? "", /no fix-round cap block is active/); for (const [id, input] of [ ["p1", { action: "start", phase: "brainstorm" }], ["p2", { action: "complete", phase: "brainstorm" }], ["p3", { action: "start", phase: "plan" }], ["p4", { action: "complete", phase: "plan" }], ["p5", { action: "start", phase: "implement" }], ["p6", { action: "complete", phase: "implement" }], ["p7", { action: "start", phase: "verify" }], ] as const) { assert.equal(((await resetTool.execute(id, input, undefined, undefined, reset.ctx)) as { details: { error?: string } }).details.error, undefined); } await reset.emitEvent("tool_result", waveResult("audit", [{ agent: "conformance-reviewer", exitCode: 0 }])); assert.equal((await firstCallResult(reset, "c1", implementerWave(1)))?.block, true, "credits zeroed by reset (cap 0 blocks)"); const replayImpl = harness({ cwd: tempCwd(settings), branch: verifyBranch([ subagentResult(["conformance-reviewer"]), grantResult(1), phaseResult("skip", phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "skipped" })), phaseResult("start", phases({ brainstorm: "complete", plan: "complete", implement: "in_progress", verify: "skipped" })), phaseResult("complete", phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "skipped" })), phaseResult("start", phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "in_progress" })), subagentResult(["conformance-reviewer"]), ]), }); await replayImpl.emit("session_start"); assert.equal((await firstCallResult(replayImpl, "c1", implementerWave(1)))?.block, true, "replayed start implement zeroed credits"); const replayReset = harness({ cwd: tempCwd(settings), branch: verifyBranch([ subagentResult(["conformance-reviewer"]), grantResult(1), phaseResult("reset", phases({})), phaseResult("start", phases({ brainstorm: "in_progress" })), phaseResult("complete", phases({ brainstorm: "complete" })), phaseResult("start", phases({ brainstorm: "complete", plan: "in_progress" })), phaseResult("complete", phases({ brainstorm: "complete", plan: "complete" })), phaseResult("start", phases({ brainstorm: "complete", plan: "complete", implement: "in_progress" })), phaseResult("complete", phases({ brainstorm: "complete", plan: "complete", implement: "complete" })), phaseResult("start", phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "in_progress" })), subagentResult(["conformance-reviewer"]), ]), }); await replayReset.emit("session_start"); assert.equal((await firstCallResult(replayReset, "c1", implementerWave(1)))?.block, true, "replayed reset zeroed credits"); }); test("grant: block reason gives action, settings path, and live-read guidance", async () => { const h = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 0 } } }); await h.emit("session_start"); const reason = (await firstCallResult(h, "c", implementerWave(1)))?.reason ?? ""; assert.match(reason, /phase_tracker\(\{ action: "grant_fix_rounds"/); assert.ok(reason.includes(join(h.ctx.cwd, ".pi", "settings.json"))); assert.match(reason, /no restart.*restate model and maxFixRounds/s); }); test("gauntlet_setting registration requests sequential execution", () => { assert.equal(harness().tools.find((t) => t.name === "gauntlet_setting")!.executionMode, "sequential"); }); test("grant renderResult shows count and reason", async () => { const h = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 0 } } }); await h.emit("session_start"); const res = await grant(h, "g", { rounds: 2, reason: "go on" }); const tool = h.tools.find((t) => t.name === "phase_tracker")! as any; const rendered = tool.renderResult(res, {}, { fg: (_c: string, s: string) => s, bold: (s: string) => s }); assert.match(JSON.stringify(rendered), /2.*go on/); }); test("grant: child sessions cannot overrule even a zero cap", async () => { const priorDepth = process.env.PI_SUBAGENT_DEPTH; process.env.PI_SUBAGENT_DEPTH = "1"; let child: ReturnType; try { child = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 0 } } }); } finally { if (priorDepth === undefined) delete process.env.PI_SUBAGENT_DEPTH; else process.env.PI_SUBAGENT_DEPTH = priorDepth; } await child.emit("session_start"); assert.match((await grant(child, "g", { rounds: 1, reason: "ok" })).details.error ?? "", /no fix-round cap block is active/); }); test("grant: accepts MAX_SAFE_INTEGER and current on-disk cap controls whether the block is live", async () => { const h = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 0 } } }); await h.emit("session_start"); const result = await grant(h, "g", { rounds: Number.MAX_SAFE_INTEGER, reason: "approved" }); assert.equal(result.details.rounds, Number.MAX_SAFE_INTEGER); const changed = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 0 } } }); await changed.emit("session_start"); writeFileSync(join(changed.ctx.cwd, ".pi", "settings.json"), JSON.stringify({ piGauntlet: { closureReview: { maxFixRounds: 1 } } })); assert.match((await grant(changed, "g", { rounds: 1, reason: "ok" })).details.error ?? "", /0 used, cap 1/); }); const eightTasks = (open: number[]) => Array.from({ length: 8 }, (_, i) => ({ name: `T${i + 1} task`, status: open.includes(i) ? "in_progress" : "complete" })); const resultText = async (h: ReturnType, id: string, isError = false) => { const [res] = (await h.emitEvent("tool_result", waveResult(id, [{ agent: "implementer", exitCode: 0 }], isError))) as ( | { content: { text: string }[] } | undefined )[]; return res?.content[0]?.text; }; test("open-task nudge: verify-phase implementer wave lists mid-list open rows with the closure instruction, before any audit", async () => { const h = harness({ branch: verifyBranch([taskSnapshot(eightTasks([3]))]) }); await h.emit("session_start"); const text = await resultText(h, "w1"); assert.ok(text, "nudge present"); assert.match(text, /^Plan tasks still open after this repair wave:\n3: T4 task \(in_progress\)\nOnce this wave's repair is integrated and its re-review or re-audit accepts it, close that task: plan_tracker\(\{ action: "update", index: N, status: "complete" \}\)\. Leave unaccepted repairs in_progress\. A pending row is a task still to run, not to close\. Open tasks block complete verify\.$/); assert.doesNotMatch(text, /0: T1 task/); }); // fixRounds is observed through the cap guard: one nudged wave against maxFixRounds 1 // blocks the next dispatch exactly as an un-nudged wave would. test("open-task nudge: fires on every qualifying wave and leaves fix-round counting unchanged", async () => { const h = guardedHarness({ piGauntlet: { closureReview: { enforce: true, maxFixRounds: 1 } } }, [taskSnapshot(eightTasks([0, 3]))]); await h.emit("session_start"); assert.equal(await firstCallResult(h, "c1", implementerWave(1)), undefined); assert.match((await resultText(h, "c1")) ?? "", /0: T1 task \(in_progress\)\n3: T4 task \(in_progress\)/); const blocked = await firstCallResult(h, "c2", implementerWave(1)); assert.equal(blocked?.block, true, "one wave counted, cap 1 reached"); const h2 = guardedHarness({ piGauntlet: { closureReview: { enforce: true } } }, [taskSnapshot(eightTasks([3]))]); await h2.emit("session_start"); assert.match((await resultText(h2, "a")) ?? "", /^Plan tasks still open/); assert.match((await resultText(h2, "b")) ?? "", /^Plan tasks still open/); }); // The closure-model mismatch warning is stashed at tool_call; it must render first. test("open-task nudge and mismatch preserve results and warning order (direct)", async () => { const h = harness({ cwd: tempCwd({ piGauntlet: { closureReview: { enforce: true, model: "p/configured", maxFixRounds: 1 } } }), branch: verifyBranch([taskSnapshot(eightTasks([3])), subagentResult(["conformance-reviewer"])]), }); await h.emit("session_start"); const call = { tasks: [{ agent: "conformance-reviewer", model: "p/other", task: "audit" }, { agent: "implementer", task: "fix", worktree: true }] }; const toolCallId = "m1"; assert.equal((await h.emitEvent("tool_call", { toolName: "subagent", toolCallId, input: call }))[0], undefined); const event = { ...waveResult(toolCallId, [{ agent: "implementer", exitCode: 0 }]), structuredContent: { results: [{ value: "repair" }] }, usage: { sentinel: "subagent usage" }, }; const original = structuredClone(event); const [ret] = await h.emitEvent("tool_result", event); const merged = mergeToolResult(event, ret); assert.deepEqual(event, original); assert.match(merged.content[0].text, /p\/other[\s\S]*Plan tasks still open after this repair wave:/); assert.deepEqual(merged, { ...event, content: [merged.content[0], ...event.content] }); assert.equal((await firstCallResult(h, "next", implementerWave(1)))?.block, true, "repair still spends one fix round"); }); test("open-task nudge: silent outside the verify window and without open rows", async () => { const cases: [string, ReturnType][] = [ ["implement in progress", harness({ branch: implementBranch([taskSnapshot(eightTasks([3]))]) })], [ "ship in progress", harness({ branch: verifyBranch([ phaseResult("complete", phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "complete" })), phaseResult("start", phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "complete", ship: "in_progress" })), taskSnapshot(eightTasks([3])), ]), }), ], ["all tasks complete or skipped", harness({ branch: verifyBranch([taskSnapshot([...eightTasks([]).slice(0, 7), { name: "T8 task", status: "skipped" }])]) })], ["no snapshot on the branch", harness({ branch: verifyBranch() })], ["latest snapshot is a clear", harness({ branch: verifyBranch([taskSnapshot(eightTasks([3])), taskSnapshot([])]) })], ["rejected update is skipped, prior all-complete snapshot used", harness({ branch: verifyBranch([taskSnapshot(eightTasks([])), { type: "message", message: { role: "toolResult", toolName: "plan_tracker", details: { tasks: eightTasks([3]), error: "rejected" } } }]) })], ["flowGuards.enforce: false", harness({ cwd: tempCwd({ piGauntlet: { flowGuards: { enforce: false } } }), branch: verifyBranch([taskSnapshot(eightTasks([3]))]) })], ["async handle results: []", harness({ branch: verifyBranch([taskSnapshot(eightTasks([3]))]) })], ]; for (const [label, h] of cases) { await h.emit("session_start"); if (label === "async handle results: []") { assert.deepEqual(await h.emitEvent("tool_result", waveResult("x", [])), [undefined], label); continue; } assert.equal(await resultText(h, "x"), undefined, label); } }); test("open-task nudge: closureReview.enforce: false does not silence it", async () => { const h = harness({ cwd: tempCwd({ piGauntlet: { closureReview: { enforce: false } } }), branch: verifyBranch([taskSnapshot(eightTasks([3]))]) }); await h.emit("session_start"); assert.match((await resultText(h, "k")) ?? "", /^Plan tasks still open/); }); test("open-task nudge: silent on an isError result, a degraded settings read, and in a subagent child", async () => { const errored = harness({ branch: verifyBranch([taskSnapshot(eightTasks([3]))]) }); await errored.emit("session_start"); assert.equal(await resultText(errored, "e", true), undefined, "isError result"); const malformed = tempCwd(); mkdirSync(join(malformed, ".pi"), { recursive: true }); writeFileSync(join(malformed, ".pi", "settings.json"), "{ not json"); const degraded = harness({ cwd: malformed, branch: verifyBranch([taskSnapshot(eightTasks([3]))]) }); await degraded.emit("session_start"); assert.equal(await resultText(degraded, "d"), undefined, "settings errors"); process.env.PI_SUBAGENT_DEPTH = "1"; try { const child = harness({ branch: verifyBranch([taskSnapshot(eightTasks([3]))]) }); await child.emit("session_start"); assert.equal(await resultText(child, "c"), undefined, "subagent child"); } finally { 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: "wave-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\(wave-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: "wave-reviewer" })); assert.ok(h.widgets.at(-1)!.includes(`verify(wave-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(resolve => { entered = resolve; }); const modelReleased = new Promise(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: "wave-reviewer" })); release(); assert.equal((await shipStart).status, "in_progress"); assert.match(h.widgets.at(-1)!, /verify\(wave-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: "wave-reviewer" })); assert.ok(h.widgets.at(-1)!.includes(`verify(wave-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: "wave-reviewer" }] }] }, label: "implement" }, { phase: "implement", input: { agent: "implementer" }, label: "implement" }, { phase: "implement", input: { agent: "wave-reviewer" }, label: "wave-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 [ ["wave-reviewer", "implementer", "wave-reviewer", "conformance-reviewer"], ["conformance-reviewer", "implementer", "conformance-reviewer", "wave-reviewer", "wave-reviewer", "wave-reviewer"], ]) { test(`live repair sequence: ${agents.join(" -> ")}`, async () => { const h = harness({ hasUI: true }); await startPhase(h, "verify"); const counts: Record = {}; for (const [i, agent] of agents.entries()) { const label = ({ "wave-reviewer": "wave-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: "wave-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: "wave-reviewer" })); assert.ok(h.widgets.at(-1)!.includes(`verify(wave-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: "wave-reviewer", async: true })); assert.match(h.widgets.at(-1)!, /verify\(wave-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: "wave-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: "wave-reviewer" })); assert.match(h.widgets.at(-1)!, /verify\(wave-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: "wave-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\(wave-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: "wave-reviewer" })); assert.match(h.widgets.at(-1)!, /verify\(wave-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: "wave-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\(wave-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: "wave-reviewer" })); assert.match(h.widgets.at(-1)!, /verify\(wave-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; 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: "wave-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: "wave-reviewer" })); await h.emitEvent("tool_result", { toolName: "subagent", toolCallId: "first", details: {}, content: [] }); await h.emitEvent("tool_call", subagentCall("old", { agent: "wave-reviewer" })); assert.match(h.widgets.at(-1)!, /verify\(wave-review #2\)/); const branch = kind === "empty" ? [assistant()] : kind === "explicit" ? explicitReplay("verify", "custom") : [phaseResult("start", replaySnapshot("verify")), phaseResult("status", replaySnapshot("verify", "wave-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: "wave-reviewer" })); assert.match(h.widgets.at(-1)!, /verify\(wave-review\)/); await h.emitEvent("tool_result", { toolName: "subagent", toolCallId: "next", details: {}, content: [] }); await h.emitEvent("tool_call", subagentCall("again", { agent: "wave-reviewer" })); assert.match(h.widgets.at(-1)!, /verify\(wave-review #2\)/); assert.deepEqual(branch, original); }); } } for (const pattern of [".worktrees/", "../companion-"]) test(`plan_check resolves clone URL companions with ${pattern}`, async (t) => { const primary = gitPrimary().primary; const companion = gitPrimary().primary; const unselected = gitPrimary().primary; const name = companion.split("/").at(-1)!; const repo = `team/${name}`; const cloneUrl = `git@example.test:${repo}.git`; execFileSync("git", ["config", "remote.origin.url", `https://example.test/${repo}.git`], { cwd: companion }); const branch = "user/slug"; let companionRoot = join(companion, pattern.replace("", "user-slug")); execFileSync("git", ["worktree", "add", "-b", branch, companionRoot], { cwd: companion, stdio: "pipe" }); if (pattern.startsWith("..")) tempDirs.push(companionRoot); mkdirSync(join(primary, ".pi"), { recursive: true }); writeFileSync(join(primary, ".pi/gauntlet-overrides.md"), `## shape-ticket\n- sibling: ${cloneUrl}\n- sibling: git@example.test:other/${unselected.split("/").at(-1)!}.git\n`); const { planPath } = writePlanFixture(primary, { mutateSpec: s => s + `\n## Legs\n### Leg: team/repo-a\nscope: none\nbranch: ${branch}\n### Leg: ${repo}\nscope: none\nbranch: ${branch}\ncontract: home: ${pattern}\n`, mutatePlan: s => s.replace("---", `Baseline team/repo-a: abc1234\nBaseline ${repo}: def5678\n---`).replace("### Task 2: Implement naming", `## Wave 2 - Companion\n\n### Task 2: Implement naming\nLeg: ${repo.toUpperCase()}`).replace("abc1234 skipped - lib/task2", "def5678 skipped - lib/task2"), }); rmSync(join(primary, "file-b.ts")); writeFileSync(join(companionRoot, "file-b.ts"), "companion only\n"); const h = harness({ cwd: primary }); await h.emit("session_start"); const tool = h.tools.find(t => t.name === "plan_check")!; const probes: string[] = []; const spies: { mock: { restore(): void } }[] = []; if (unselected) { for (const method of ["existsSync", "realpathSync", "statSync", "readFileSync", "readdirSync"] as const) { const original = fs[method]; spies.push(mock.method(fs, method, (...args: any[]) => { if (String(args[0]).startsWith(unselected)) probes.push(`${method}: ${args[0]}`); return (original as Function)(...args); })); } const original = childProcess.execFileSync; spies.push(mock.method(childProcess, "execFileSync", (...args: any[]) => { if (String(args[2]?.cwd).startsWith(unselected)) probes.push(`git: ${args[2].cwd}`); return (original as Function)(...args); })); syncBuiltinESMExports(); } try { const result = await tool.execute("legs", { planPath }, undefined, undefined, h.ctx) as { details: { status: string; findings?: unknown } }; assert.equal(result.details.status, "pass", JSON.stringify(result.details.findings)); assert.deepEqual(probes, [], "unselected sibling must receive no filesystem or Git probes"); writeFileSync(join(primary, ".pi/gauntlet-overrides.md"), `## shape-ticket\n- sibling: https://user@example.test:7999/${repo}.git/\n`); const https = await tool.execute("https", { planPath }, undefined, undefined, h.ctx) as { details: { status: string } }; assert.equal(https.details.status, "pass"); writeFileSync(join(primary, ".pi/gauntlet-overrides.md"), "## shape-ticket\n- sibling: ../viewer\n"); const invalid = await tool.execute("invalid", { planPath }, undefined, undefined, h.ctx) as { details: { status: string; findings: { check: string; reason: string }[] } }; assert.equal(invalid.details.status, "fail"); assert.ok(invalid.details.findings.some(f => f.check === "input" && f.reason.includes("- sibling: ../viewer") && f.reason.includes("invalid configuration"))); const plain = realpathSync(tempCwd()); const missingName = `${name}-missing`; const cases = [ { name: "PATH not found", value: `https://example.test/team/${missingName}.git`, reason: "PATH not found" }, { name: "not a checkout", value: `https://example.test/team/${plain.split("/").at(-1)}.git`, reason: "not a checkout" }, { name: "no origin", value: cloneUrl, origin: null, reason: "no origin" }, { name: "unparseable stored origin", value: cloneUrl, origin: "local-origin", reason: "unparseable origin" }, { name: "wrong repo", value: cloneUrl, origin: `https://example.test/other/${name}.git`, reason: "wrong repo" }, { name: "home primary", value: `https://example.test/team/${primary.split("/").at(-1)}.git`, reason: "PATH equals home primary" }, ...["viewer", "/srv/git/viewer.git", "file:///srv/git/viewer.git"].map(value => ({ name: `invalid ${value}`, value, reason: "invalid configuration" })), { name: "stored trailing slash", value: cloneUrl, origin: `https://example.test/${repo}.git/` }, { name: "stored origin with insteadOf", value: cloneUrl, origin: `https://example.test/${repo}.git`, rewrite: true }, ]; for (const row of cases) await t.test(row.name, async () => { const stored = "origin" in row ? row.origin : `https://example.test/${repo}.git`; if (stored === null) execFileSync("git", ["config", "--unset", "remote.origin.url"], { cwd: companion }); else execFileSync("git", ["config", "remote.origin.url", stored!], { cwd: companion }); const rewriteKey = "url.https://rewritten.test/other/.insteadOf"; if ("rewrite" in row) execFileSync("git", ["config", rewriteKey, "https://example.test/team/"], { cwd: companion }); const line = `- sibling: ${row.value}`; writeFileSync(join(primary, ".pi/gauntlet-overrides.md"), `## shape-ticket\n${line}\n`); try { const result = await tool.execute(row.name, { planPath }, undefined, undefined, h.ctx) as { details: { status: string; findings?: { check: string; reason: string }[] } }; assert.equal(result.details.status, row.reason ? "fail" : "pass", JSON.stringify(result.details.findings)); if (row.reason) assert.ok(result.details.findings?.some(f => f.check === "input" && f.reason.includes(line) && f.reason.includes(row.reason!)), JSON.stringify(result.details.findings)); } finally { if ("rewrite" in row) execFileSync("git", ["config", "--unset", rewriteKey], { cwd: companion }); } }); execFileSync("git", ["config", "remote.origin.url", `https://example.test/${repo}.git`], { cwd: companion }); await t.test("identity precedes shared NAME without probing the other declaration", async () => { writeFileSync(join(primary, ".pi/gauntlet-overrides.md"), `## shape-ticket\n- sibling: git@example.test:other/${name}.git\n- sibling: ${cloneUrl}\n`); const result = await tool.execute("identity", { planPath }, undefined, undefined, h.ctx) as { details: { status: string; findings?: unknown } }; assert.equal(result.details.status, "pass", JSON.stringify(result.details.findings)); }); writeFileSync(join(primary, ".pi/gauntlet-overrides.md"), `## shape-ticket\n- sibling: ${cloneUrl}\n`); } finally { for (const spy of spies) spy.mock.restore(); syncBuiltinESMExports(); } const specPath = join(primary, "doc/specs/spec.md"); const originalSpec = readFileSync(specPath, "utf8"); const scriptHome = join(companion, "..", `${name}-worktrees`); tempDirs.push(scriptHome); mkdirSync(scriptHome); const scriptRoot = join(scriptHome, "slug"); execFileSync("git", ["worktree", "move", companionRoot, scriptRoot], { cwd: companion, stdio: "pipe" }); companionRoot = scriptRoot; for (const home of [undefined, `../${name}-worktrees/slug`, ".worktrees/"]) { await t.test(`script-placed companion with home ${home ?? "absent"}`, async () => { writeFileSync(specPath, originalSpec.replace(`contract: home: ${pattern}`, home ? `contract:\n- home: ${home}` : "contract:")); const result = await tool.execute("script-placed", { planPath }, undefined, undefined, h.ctx) as { details: { status: string; findings?: unknown } }; assert.equal(result.details.status, "pass", JSON.stringify(result.details.findings)); }); } writeFileSync(specPath, originalSpec); const originalPlan = readFileSync(planPath, "utf8"); const foreignSpec = join(companionRoot, "foreign-spec.md"); writeFileSync(foreignSpec, readFileSync(join(primary, "doc/specs/spec.md"))); writeFileSync(planPath, originalPlan.replace("doc/specs/spec.md", foreignSpec)); const foreign = await tool.execute("foreign-spec", { planPath }, undefined, undefined, h.ctx) as { details: { status: string; findings: { check: string }[] } }; assert.equal(foreign.details.status, "fail"); assert.ok(foreign.details.findings.some(f => f.check === "input")); writeFileSync(planPath, originalPlan); rmSync(join(companionRoot, "file-b.ts")); const failure = await tool.execute("legs-missing", { planPath }, undefined, undefined, h.ctx) as { details: { status: string; findings: { check: string }[] } }; assert.equal(failure.details.status, "fail"); execFileSync("git", ["worktree", "remove", "--force", companionRoot], { cwd: companion, stdio: "pipe" }); const missing = await tool.execute("legs-missing-root", { planPath }, undefined, undefined, h.ctx) as { details: { findings: { check: string }[] } }; assert.ok(missing.details.findings.some(f => f.check === "input")); }); for (const state of ["unlinked", "primary", "detached", "not a checkout", "foreign linked checkout", "duplicate", "missing branch", "lookup failed"] as const) { test(`plan_check rejects companion branch lookup: ${state}`, async () => { const primary = gitPrimary().primary; const companion = gitPrimary().primary; const name = companion.split("/").at(-1)!; const repo = `team/${name}`; const branch = "user/slug"; const companionRoot = join(companion, ".worktrees", "slug"); const git = (...args: string[]) => execFileSync("git", ["-C", companion, ...args], { stdio: "pipe" }); git("config", "remote.origin.url", `https://example.test/${repo}.git`); git("branch", branch); if (state === "primary") git("checkout", branch); if (state === "detached") git("worktree", "add", "--detach", companionRoot, branch); if (state === "not a checkout" || state === "foreign linked checkout" || state === "duplicate") { git("worktree", "add", companionRoot, branch); if (state === "duplicate") git("worktree", "add", "--force", `${companionRoot}-other`, branch); else { rmSync(companionRoot, { recursive: true }); if (state === "foreign linked checkout") { execFileSync("git", ["-C", primary, "worktree", "add", "--detach", companionRoot], { stdio: "pipe" }); } else mkdirSync(companionRoot); } } mkdirSync(join(primary, ".pi"), { recursive: true }); writeFileSync(join(primary, ".pi/gauntlet-overrides.md"), `## shape-ticket\n- sibling: git@example.test:${repo}.git\n`); const { planPath } = writePlanFixture(primary, { mutateSpec: s => s + `\n## Legs\n### Leg: team/repo-a\nscope: none\nbranch: ${branch}\n### Leg: ${repo}\nscope: none\n${state === "missing branch" ? "" : `branch: ${branch}\n`}contract:\n`, mutatePlan: s => s.replace("---", `Baseline team/repo-a: abc1234\nBaseline ${repo}: def5678\n---`).replace("### Task 2: Implement naming", `## Wave 2 - Companion\n\n### Task 2: Implement naming\nLeg: ${repo}`).replace("abc1234 skipped - lib/task2", "def5678 skipped - lib/task2"), }); const h = harness({ cwd: primary }); await h.emit("session_start"); const tool = h.tools.find(t => t.name === "plan_check")!; const original = childProcess.execFileSync; const spy = state === "lookup failed" ? mock.method(childProcess, "execFileSync", (...args: any[]) => { if (args[0] === "git" && args[2]?.cwd === companion && JSON.stringify(args[1]) === JSON.stringify(["worktree", "list", "--porcelain", "-z"])) { throw Object.assign(new Error("worktree listing failed"), { status: 128 }); } return (original as Function)(...args); }) : undefined; if (spy) syncBuiltinESMExports(); let result: { details: { status: string; findings: { check: string; reason: string }[] } }; try { result = await tool.execute(state, { planPath }, undefined, undefined, h.ctx) as typeof result; } finally { if (spy) { spy.mock.restore(); syncBuiltinESMExports(); } } const reason = state === "duplicate" ? `2 worktrees hold ${branch}` : state === "not a checkout" || state === "foreign linked checkout" ? `${companionRoot} is not a checkout` : state === "lookup failed" ? `worktree lookup failed for ${branch}` : `no worktree holds ${branch}`; assert.equal(result.details.status, "fail"); assert.deepEqual(result.details.findings.map(({ check, reason }) => ({ check, reason })), [ { check: "input", reason: state === "missing branch" ? `invalid recorded branch for ${repo.toLowerCase()}` : `cannot resolve worktree for ${repo.toLowerCase()}: ${reason}` }, ]); }); } for (const length of [32767, 32768, 32769]) { test(`plan_check complete manifest JS length ${length} bounds stamping`, async () => { const dir = gitPrimary().primary; const { planPath, specPath } = writePlanFixture(dir); const passLine = "PASS \u2014 plan verified and stamped for implement-start"; const prefix = `${passLine}\n\nmanifest: ${planPath} | spec: ${specPath} | tasks: 1 | waves: 1\n`; const task = { task: 1, wave: 1, heading: "Docs", files: [{ kind: "Modify", path: "file-a.ts" }], tests: [], orchestrator: "é" }; task.orchestrator += "a".repeat(length - prefix.length - JSON.stringify(task).length); const expected = prefix + JSON.stringify(task); assert.equal(expected.length, length); assert.ok(Buffer.byteLength(expected, "utf8") > length); writeFileSync(planPath, `# Plan **Spec:** \`doc/specs/spec.md\` **Verification:** all-checks --- ## Wave 1 - Docs ### Task 1: Docs Orchestrator: ${task.orchestrator} **Files:** - Modify: file-a.ts **Tests:** - none: docs ## Spec coverage | anchor | requirement | owner | |---|---|---| | - | mechanical: docs | Task 1 | `); const h = harness({ cwd: dir, branch: readyForImplementBranch }); await h.emit("session_start"); const tool = h.tools.find(t => t.name === "plan_check")!; const result = await tool.execute("size", { planPath }, undefined, undefined, h.ctx) as { content: { text: string }[]; details: { status: string; findings?: { check: string; line: number; reason: string }[] }; }; if (length < 32768) { assert.equal(result.details.status, "pass"); assert.equal(result.content[0].text, expected); } else { assert.equal(result.details.status, "fail"); assert.equal(result.details.findings?.length, 1); assert.equal(result.details.findings?.[0].check, "manifest-size"); assert.equal(result.details.findings?.[0].line, 0); assert.equal(result.details.findings?.[0].reason, `manifest content is ${length} characters (limit 32,768); the plan is too large for the orchestrator's manifest - stop and ask the user to reduce it`); assert.ok(!result.content[0].text.includes("\nmanifest:")); } const phase = h.tools.find(t => t.name === "phase_tracker")!; const start = await phase.execute("start", { action: "start", phase: "implement" }, undefined, undefined, h.ctx) as { details: { error?: string; phases: { implement: { status: string } } } }; if (length < 32768) assert.equal(start.details.phases.implement.status, "in_progress"); else assert.match(start.details.error ?? "", /plan_check/); }); }