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<Record<Phase, Status>> = {}) =>
  Object.fromEntries(PHASES.map((phase) => [phase, { status: overrides[phase] ?? "pending" }])) as Record<
    Phase,
    { status: Status; substep?: string }
  >;

const phaseResult = (action: string, state: Record<Phase, { status: Status; substep?: string }>) => ({
  type: "message",
  message: { role: "toolResult", toolName: "phase_tracker", details: { action, phases: state } },
});

const assistant = (stopReason = "stop") => ({ type: "message", message: { role: "assistant", stopReason } });

const enteredBranch = (state: Record<Phase, { status: Status; substep?: string }>, extra: unknown[] = []) => [
  phaseResult("start", phases({ brainstorm: "in_progress" })),
  phaseResult("complete", state),
  ...extra,
];

const resumedBranch = (rest: Partial<Record<Phase, Status>>) => [
  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<string, TestModel>; setModelResult?: boolean | Error } = {}) {
  const handlers = new Map<string, ((event: unknown, ctx: unknown) => 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<typeof harness>) => {
  await h.emit("session_start");
  await h.emit("agent_settled");
};

const startPhase = async (h: ReturnType<typeof harness>, 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<string, { status: string }> } };
  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<typeof harness>, 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);
});

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 }[], isError = false) => ({
  type: "message",
  message: { role: "toolResult", toolName: "plan_tracker", isError, details: { tasks } },
});

const completePhase = async (h: ReturnType<typeof harness>, 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<Phase, { status: string }> };
  };
};

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);
  }
});

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 <primary>/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 <primary>/doc blocks");
  assert.ok(blocked(await h.emitEvent("tool_call", bashCall("b2", `git -C ${primary} switch -c y`))), "-C <primary> blocks");
  assert.ok(!blocked(await h.emitEvent("tool_call", bashCall("b3", `git -C ${worktree} switch -c y`))), "-C <worktree> passes");
  assert.ok(!blocked(await h.emitEvent("tool_call", bashCall("b4", `cd ${worktree} && git checkout -b y`))), "cd <worktree> 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<any>;
  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<string, unknown> = {}) => ({ 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<typeof harness>, 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<typeof harness>;
  let replay: ReturnType<typeof harness>;
  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<typeof harness>, id: string, input: Record<string, unknown>) =>
  (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<typeof harness>, 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<typeof harness>, 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<typeof harness>;
  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<typeof harness>;
  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<typeof harness>;
  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<typeof harness>, 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<typeof harness>][] = [
    ["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<void>(resolve => { entered = resolve; });
    const modelReleased = new Promise<void>(resolve => { release = resolve; });
    h.pi.setModel = async () => {
      entered();
      await modelReleased;
      return true;
    };
    const shipStart = startPhase(h, "ship");
    await modelEntered;
    await startPhase(h, "verify");
    await h.emitEvent("tool_call", subagentCall("review", { agent: "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<string, number> = {};
    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<typeof harness>;
  try {
    process.env.PI_SUBAGENT_DEPTH = "1";
    child = harness({ hasUI: true });
  } finally {
    if (prior === undefined) delete process.env.PI_SUBAGENT_DEPTH;
    else process.env.PI_SUBAGENT_DEPTH = prior;
  }
  await startPhase(child, "verify");
  const paints = child.widgets.length;
  await child.emitEvent("tool_call", subagentCall("a", { agent: "conformance-reviewer" }));
  await child.emitEvent("tool_call", { toolName: "plan_check", toolCallId: "b", input: {} });
  assert.equal(child.widgets.length, paints);
});

for (const cap of [false, true]) {
  test(`live blocked ${cap ? "cap" : "lone"} call creates no label or ordinal`, async () => {
    const cwd = tempCwd({ piGauntlet: { closureReview: { enforce: true, maxFixRounds: cap ? 0 : 3 } } });
    const h = harness({ hasUI: true, cwd, branch: verifyBranch([subagentResult(["conformance-reviewer"])]) });
    await h.emit("session_start");
    const paints = h.widgets.length;
    assert.equal((await firstCallResult(h, "blocked", cap ? implementerWave() : loneImplementer()))?.block, true);
    await h.emitEvent("tool_execution_end", { toolName: "subagent", toolCallId: "blocked", isError: true, result: { details: {} } });
    assert.equal(h.widgets.length, paints);
    writeFileSync(join(cwd, ".pi", "settings.json"), JSON.stringify({ piGauntlet: { closureReview: { enforce: false } } }));
    await firstCallResult(h, "allowed", implementerWave());
    assert.match(h.widgets.at(-1)!, /verify\(implement\)/);
  });
}

const replaySnapshot = (phase: Phase, substep?: string, status: Status = "in_progress") => {
  const state = phases({ [phase]: status });
  if (substep !== undefined) state[phase].substep = substep;
  return state;
};

const explicitReplay = (phase: Phase, label: string) => [
  phaseResult("start", replaySnapshot(phase)),
  phaseResult("substep", replaySnapshot(phase, label)),
];

for (const row of [
  { name: "derived status only", branch: [phaseResult("start", replaySnapshot("verify")), phaseResult("status", replaySnapshot("verify", "conformance"))], phase: "verify", expected: undefined },
  { name: "explicit before derived status", branch: [...explicitReplay("verify", "gather"), phaseResult("status", replaySnapshot("verify", "council"))], phase: "verify", expected: "gather" },
  ...([{ phase: "brainstorm", label: "gather", agent: "scout" }, { phase: "plan", label: "plan-write", agent: "plan-writer" }] as const).map(r => ({
    name: `unfinished ${r.agent}`, phase: r.phase, expected: r.label,
    branch: [...explicitReplay(r.phase, r.label), assistant(), { type: "message", message: { role: "assistant", content: [{ type: "toolCall", id: "unfinished", name: "subagent", arguments: { agent: r.agent } }] } }],
  })),
  { name: "null or omitted clear", phase: "verify", expected: undefined, branch: [...explicitReplay("verify", "gather"), phaseResult("substep", replaySnapshot("verify")), phaseResult("status", replaySnapshot("verify", "council"))] },
  ...["start", "complete", "skip"].map(action => ({ name: `same phase ${action}`, phase: "verify", expected: undefined, branch: [...explicitReplay("verify", "gather"), phaseResult(action, replaySnapshot("verify", undefined, action === "complete" ? "complete" : action === "skip" ? "skipped" : "in_progress"))] })),
  ...["complete", "skip"].map(action => {
    const state = replaySnapshot("verify", "gather");
    state.ship.status = action === "complete" ? "complete" : "skipped";
    return { name: `other phase ${action}`, phase: "verify", expected: "gather", branch: [...explicitReplay("verify", "gather"), phaseResult(action, state)] };
  }),
  { name: "reset then start", phase: "verify", expected: undefined, branch: [...explicitReplay("verify", "gather"), phaseResult("reset", phases()), phaseResult("start", replaySnapshot("verify"))] },
  ...["substep", "start", "complete", "skip", "reset"].map(action => {
    const rejected = phaseResult(action, phases());
    Object.assign(rejected.message.details, { error: "rejected" });
    return { name: `rejected ${action}`, phase: "verify", expected: "gather", branch: [...explicitReplay("verify", "gather"), rejected] };
  }),
  { name: "task-driven completion", phase: "implement", expected: undefined, expectedStatus: "complete", branch: [...explicitReplay("implement", "custom"), taskSnapshot([{ name: "task", status: "complete" }])] },
  { name: "custom after clear", phase: "verify", expected: "custom", branch: [...explicitReplay("verify", "gather"), phaseResult("substep", replaySnapshot("verify")), phaseResult("substep", replaySnapshot("verify", "custom"))] },
]) {
  test(`replay explicit labels: ${row.name}`, async () => {
    const original = structuredClone(row.branch);
    const h = harness({ hasUI: true, branch: row.branch });
    const tool = h.tools.find(t => t.name === "phase_tracker")!;
    await h.emit("session_start");
    const status = await tool.execute("status", { action: "status" }, undefined, undefined, h.ctx) as any;
    assert.equal(status.details.phases[row.phase].substep, row.expected);
    if ("expectedStatus" in row) assert.equal(status.details.phases[row.phase].status, row.expectedStatus);
    if (row.expected) {
      assert.ok(h.widgets.at(-1)!.includes(`${row.phase}(${row.expected})`));
      assert.ok(status.content[0].text.includes(`${row.phase}(${row.expected})`));
    } else {
      assert.ok(!h.widgets.at(-1)!.includes(`${row.phase}(`));
    }
    assert.deepEqual(row.branch, original);
    if (status.details.phases[row.phase].status !== "in_progress") await startPhase(h, row.phase);
    const restarted = await tool.execute("status", { action: "status" }, undefined, undefined, h.ctx) as any;
    assert.equal(restarted.details.phases[row.phase].substep, row.expected);
    await h.emitEvent("tool_call", subagentCall("new", { agent: "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/<name>", "../companion-<name>"]) 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("<name>", "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/<name>"]) {
    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/);
  });
}
