@stigmer/runner 3.1.1 → 3.1.3

package/src/activities/execute-cursor/__tests__/build-prompt.test.ts

@@ -9,12 +9,13 @@
 
 import { describe, it, expect } from "vitest";
 import { create } from "@bufbuild/protobuf";
-import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { ApprovalAction, InteractionMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { PendingApprovalSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
 
 import { buildPrompt } from "../index.js";
 import type { BuildPromptInput } from "../index.js";
-import { buildReinvocationPrompt, formatToolApprovalProtocol, buildToolApprovalRuleFile } from "../prompt-builder.js";
+import { buildReinvocationPrompt, formatInteractionModePrefix, formatImplementPlanSection, formatToolApprovalProtocol, buildToolApprovalRuleFile } from "../prompt-builder.js";
+import { PLAN_MODE_DIRECTIVE } from "../../../shared/plan-mode-prompt.js";
 import type { AgentResolution, AgentResolutionReason } from "../session-lifecycle.js";
 
 const USER_MESSAGE = "What was the secret token I told you?";
@@ -250,3 +251,132 @@ describe("buildReinvocationPrompt", () => {
     expect(prompt).not.toContain("Carry them out now");
   });
 });
+
+describe("formatInteractionModePrefix", () => {
+  it("wraps the shared plan-mode directive in the interaction_mode section", () => {
+    const prefix = formatInteractionModePrefix(InteractionMode.PLAN);
+
+    expect(prefix).toBeDefined();
+    expect(prefix!.startsWith("<interaction_mode>")).toBe(true);
+    expect(prefix!.endsWith("</interaction_mode>")).toBe(true);
+    expect(prefix).toContain(PLAN_MODE_DIRECTIVE);
+  });
+
+  it.each([
+    ["AGENT", InteractionMode.AGENT],
+    ["UNSPECIFIED", InteractionMode.UNSPECIFIED],
+    ["undefined", undefined],
+  ])("returns undefined for %s", (_label, mode) => {
+    expect(formatInteractionModePrefix(mode)).toBeUndefined();
+  });
+
+  it("injects the directive into a Plan-mode first prompt", () => {
+    const prompt = buildPrompt(
+      input({
+        resolution: resolution("local", "created_first_execution"),
+        interactionMode: InteractionMode.PLAN,
+      }),
+    );
+
+    expect(prompt).toContain("<interaction_mode>");
+    expect(prompt).toContain("your FINAL message IS the plan");
+  });
+
+  it("prefixes the directive on a resumed Plan-mode follow-up (mode is per-execution)", () => {
+    const prompt = buildPrompt(
+      input({
+        resolution: resolution("local", "resumed_successfully"),
+        interactionMode: InteractionMode.PLAN,
+      }),
+    );
+
+    expect(prompt.startsWith("<interaction_mode>")).toBe(true);
+    expect(prompt.endsWith(USER_MESSAGE)).toBe(true);
+  });
+
+  it("keeps a resumed Agent-mode follow-up as the raw user message", () => {
+    const prompt = buildPrompt(
+      input({
+        resolution: resolution("local", "resumed_successfully"),
+        interactionMode: InteractionMode.AGENT,
+      }),
+    );
+
+    expect(prompt).toBe(USER_MESSAGE);
+  });
+});
+
+describe("formatImplementPlanSection", () => {
+  const PLAN_PATH = ".stigmer/inputs/plan.md";
+
+  it("wraps the attached-plan directive when the plan is among the attachments", () => {
+    const section = formatImplementPlanSection(true, [PLAN_PATH, ".stigmer/inputs/data.csv"]);
+
+    expect(section).toBeDefined();
+    expect(section!.startsWith("<implement_plan>")).toBe(true);
+    expect(section!.endsWith("</implement_plan>")).toBe(true);
+    expect(section).toContain(`\`${PLAN_PATH}\``);
+    expect(section).toContain("APPROVED");
+  });
+
+  it("falls back to the conversation-plan directive when no plan attachment resolved", () => {
+    const section = formatImplementPlanSection(true, [".stigmer/inputs/data.csv"]);
+
+    expect(section).toBeDefined();
+    expect(section).not.toContain("plan.md");
+    expect(section).toContain("conversation above");
+  });
+
+  it("returns undefined for an ordinary (non-build) execution", () => {
+    expect(formatImplementPlanSection(false, [PLAN_PATH])).toBeUndefined();
+    expect(formatImplementPlanSection(undefined, [PLAN_PATH])).toBeUndefined();
+  });
+
+  it("carries the plan-derived progress-tracking instruction (Tier 3)", () => {
+    const section = formatImplementPlanSection(true, [PLAN_PATH]);
+
+    expect(section).toContain("to-do list");
+    expect(section).toContain("break the plan into");
+  });
+
+  it("injects the directive into a build-from-plan first prompt", () => {
+    const prompt = buildPrompt(
+      input({
+        resolution: resolution("local", "created_first_execution"),
+        buildFromPlan: true,
+        attachmentPaths: [PLAN_PATH],
+      }),
+    );
+
+    expect(prompt).toContain("<implement_plan>");
+    expect(prompt).toContain(`\`${PLAN_PATH}\``);
+    expect(prompt).toContain(USER_MESSAGE);
+  });
+
+  it("prefixes the directive on a resumed build turn (build_from_plan is per-execution)", () => {
+    // The common shape: the plan turn ran earlier in the session, so the
+    // build turn resumes the agent — the directive must still arrive.
+    const prompt = buildPrompt(
+      input({
+        resolution: resolution("local", "resumed_successfully"),
+        buildFromPlan: true,
+        attachmentPaths: [PLAN_PATH],
+      }),
+    );
+
+    expect(prompt.startsWith("<implement_plan>")).toBe(true);
+    expect(prompt.endsWith(USER_MESSAGE)).toBe(true);
+  });
+
+  it("keeps a resumed non-build follow-up as the raw user message", () => {
+    const prompt = buildPrompt(
+      input({
+        resolution: resolution("local", "resumed_successfully"),
+        buildFromPlan: false,
+        attachmentPaths: [PLAN_PATH],
+      }),
+    );
+
+    expect(prompt).toBe(USER_MESSAGE);
+  });
+});

package/src/activities/execute-cursor/__tests__/cas-observations.test.ts

@@ -26,6 +26,7 @@ import {
   resetCasObservations,
   casObservationsDir,
   buildObservationStagingScript,
+  buildSecretClassifyScript,
 } from "../cas-observations.js";
 import { isSecretLikePath } from "../../../shared/filereview/secret-paths.js";
 
@@ -184,4 +185,58 @@ describe("cas-observations sidecar", () => {
       }
     });
   });
+
+  // The deny-gate (no-capture-substrate) classify-only script. It shares the
+  // classifier fragment with the staging script, so its verdict must equal
+  // isSecretLikePath byte-for-byte — a secret must never fall through the hook's
+  // deny-gate secret hard-block (DD-26 #2).
+  describe("buildSecretClassifyScript (deny-gate classify-only)", () => {
+    function runClassify(salient: string): string {
+      return execFileSync(process.execPath, ["-e", buildSecretClassifyScript()], {
+        input: salient,
+      })
+        .toString()
+        .trim();
+    }
+
+    it("classifies secrets byte-for-byte identically to isSecretLikePath (no staging)", () => {
+      const paths = [
+        ".env",
+        ".env.local",
+        "config/.env.production",
+        "id_rsa",
+        "server.pem",
+        "certs/key.pfx",
+        "terraform.tfstate",
+        ".aws/credentials",
+        "home/.ssh/known_hosts",
+        ".npmrc",
+        "secrets.yaml",
+        "/abs/path/.env",
+        "id_rsa.pub",
+        "app.log",
+        "src/index.ts",
+        "docs/notes.md",
+        "build/out.js",
+        "environment.ts",
+      ];
+      for (const p of paths) {
+        const expected = isSecretLikePath(p) ? "secret" : "ok";
+        expect(runClassify(p), `classification for ${p}`).toBe(expected);
+      }
+    });
+
+    it("fail-closes on empty input (classifies as secret), matching isSecretLikePath('')", () => {
+      expect(runClassify("")).toBe("secret");
+      expect(isSecretLikePath("")).toBe(true);
+    });
+
+    it("does not stage anything (pure classifier)", async () => {
+      const ws = tmp("obs-classify-nostage-");
+      writeFileSync(join(ws, ".env"), "API_KEY=xyz", "utf-8");
+      expect(runClassify(".env")).toBe("secret");
+      // No sidecar dir is created or written by the classify-only script.
+      expect(await readCasObservations(ws)).toEqual({ captured: [], secretPaths: [] });
+    });
+  });
 });

package/src/activities/execute-cursor/__tests__/delta-enricher.test.ts

@@ -240,3 +240,71 @@ describe("DeltaEnricher finalize reconciliation", () => {
     expect(messages[1].toolCalls[0].status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
   });
 });
+
+describe("DeltaEnricher recovery-retry stream epilogue", () => {
+  // Regression for the zombie RUNNING row of aex_01kws27q1e2esvkqjpvectttxf:
+  // the recovery retry's bare stream loop buffered the tool-call-completed
+  // delta but never flushed it, so the row lacked the completedAt evidence
+  // finalize's sweep requires and persisted as RUNNING forever. The epilogue
+  // must applyEnrichments (flush the buffered evidence) BEFORE finalize.
+  it("applyEnrichments + finalize promotes a retry's buffered-completion RUNNING row", () => {
+    vi.spyOn(console, "log").mockImplementation(() => {});
+
+    const enricher = new DeltaEnricher();
+    const messages: AgentMessage[] = [
+      makeMessage([{ id: "tc-retry", name: "Shell", status: ToolCallStatus.TOOL_CALL_RUNNING }]),
+    ];
+
+    // The retry's onDelta buffered the completion, but the bare retry loop
+    // never applied it to the transcript.
+    enricher.processDelta({
+      type: "tool-call-completed",
+      callId: "tc-retry",
+      toolCall: { type: "shell" },
+    } as unknown as InteractionUpdate);
+
+    // Without the flush, finalize alone cannot promote (no evidence on the row).
+    const unflushed = makeMessage([
+      { id: "tc-retry", name: "Shell", status: ToolCallStatus.TOOL_CALL_RUNNING },
+    ]);
+    new DeltaEnricher().finalize([unflushed]);
+    expect(unflushed.toolCalls[0].status).toBe(ToolCallStatus.TOOL_CALL_RUNNING);
+
+    // The epilogue sequence: flush the buffered evidence, then finalize.
+    enricher.applyEnrichments(messages);
+    enricher.finalize(messages);
+
+    const tc = messages[0].toolCalls[0];
+    expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+    expect(tc.completedAt).toBeTruthy();
+  });
+
+  it("re-running applyEnrichments and finalize is idempotent", () => {
+    vi.spyOn(console, "log").mockImplementation(() => {});
+
+    const enricher = new DeltaEnricher();
+    const messages: AgentMessage[] = [
+      makeMessage([{ id: "tc-1", name: "Shell", status: ToolCallStatus.TOOL_CALL_RUNNING }]),
+    ];
+
+    enricher.processDelta({
+      type: "tool-call-completed",
+      callId: "tc-1",
+      toolCall: { type: "shell" },
+    } as unknown as InteractionUpdate);
+
+    // Primary epilogue ...
+    enricher.applyEnrichments(messages);
+    enricher.finalize(messages);
+    const stamped = messages[0].toolCalls[0].completedAt;
+
+    // ... and the retry epilogue re-runs both. The row must keep its original
+    // completion evidence and terminal status.
+    enricher.applyEnrichments(messages);
+    enricher.finalize(messages);
+
+    const tc = messages[0].toolCalls[0];
+    expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+    expect(tc.completedAt).toBe(stamped);
+  });
+});

package/src/activities/execute-cursor/__tests__/hitl-ledger.test.ts

@@ -1025,6 +1025,34 @@ describe("reconcileDeniedToolCalls — authoritative hook input overlay", () =>
     expect(tc.approvalContentDigest).not.toBe("");
   });
 
+  it("does NOT overlay a secret-like write's content (DD-26 #2 defensive guard)", async () => {
+    // Normally unreachable — the hook hard-blocks a secret write and records no
+    // ledger entry — but if a hook classify failure fell one through with content,
+    // that content must still never reach args / args_preview / the digest.
+    const tc = toolCall({
+      id: "c1",
+      name: "write",
+      status: ToolCallStatus.TOOL_CALL_COMPLETED,
+      argsPreview: JSON.stringify({ path: ".env" }),
+    });
+    const messages = [aiMessageWith([tc])];
+
+    await reconcileDeniedToolCalls(
+      messages,
+      [{
+        toolName: "Write",
+        token: grantToken("write", ".env"),
+        input: { file_path: ".env", content: "API_KEY=super-secret" },
+      }],
+      undefined,
+      rootBackend(),
+    );
+
+    expect(args(tc).content).toBeUndefined(); // content never overlaid
+    expect(tc.argsPreview).not.toContain("super-secret");
+    expect(tc.approvalContentDigest).toBe(""); // digest not stamped from secret content
+  });
+
   it("stamps the captured edit old/new strings and a digest", async () => {
     const tc = toolCall({
       id: "c1",

package/src/activities/execute-cursor/__tests__/hook-script.test.ts

@@ -403,10 +403,11 @@ d("generated approval hook (preToolUse + beforeMCPExecution)", () => {
     });
 
     it("keeps gating a write to a GITIGNORED path (the snapshot cannot revert it)", () => {
-      // .env-style ignored paths are invisible to the git snapshot, so capture
-      // mode must still gate them for explicit approval.
-      const h = setup({ captureMode: true, gitignored: ["secret.txt"] });
-      expect(h.decide(hookWrite("secret.txt")).permission).toBe("deny");
+      // A NON-secret gitignored path is invisible to the git snapshot, so capture
+      // mode must still gate it for explicit approval. (A secret-like gitignored
+      // write is hard-blocked instead — see the deny-gate secret cases below.)
+      const h = setup({ captureMode: true, gitignored: ["ignored.txt"] });
+      expect(h.decide(hookWrite("ignored.txt")).permission).toBe("deny");
       expect(h.ledger().map((e) => e.toolName)).toContain("Write");
       // A non-ignored sibling still flows.
       expect(h.decide(hookWrite("normal.txt")).permission).toBe("allow");
@@ -418,6 +419,64 @@ d("generated approval hook (preToolUse + beforeMCPExecution)", () => {
     });
   });
 
+  // Deny-gate secret hard-block (DD-26 #2): with no capture substrate for a write
+  // (capture off — the classic deny-gate — or captureIgnored off in a git-no-
+  // storage workspace) a secret-like WRITE must NOT surface its content for
+  // approval. The hook hard-blocks it with the security message and records NO
+  // ledger entry, so it never becomes an approvable WAITING row; a non-secret
+  // write still deny-gates, and a delete (content-less) stays gated.
+  describe("deny-gate secret hard-block (DD-26 #2)", () => {
+    it("hard-blocks a secret-like write and records NO ledger entry", () => {
+      const h = setup({}); // captureMode off — the classic deny-gate
+      const dec = h.decide(hookWrite(".env", "API_KEY=abc"));
+      expect(dec.permission).toBe("deny");
+      expect(dec.raw).toContain("blocked for security");
+      // SECRET_BLOCKED, not APPROVAL_REQUIRED: the model is told to move on.
+      expect(dec.raw.toLowerCase()).toContain("nothing was written");
+      expect(dec.raw).not.toContain("submitted to the user for approval");
+      expect(h.ledger()).toEqual([]); // never recorded → never approvable
+    });
+
+    it("hard-blocks a secret-like edit (path-fragment match)", () => {
+      const h = setup({});
+      const dec = h.decide(hookEdit(".ssh/id_rsa"));
+      expect(dec.permission).toBe("deny");
+      expect(dec.raw).toContain("blocked for security");
+      expect(h.ledger()).toEqual([]);
+    });
+
+    it("still deny-gates a NON-secret write and records its content for approval", () => {
+      const h = setup({});
+      const dec = h.decide(hookWrite("notes.md", "hello"));
+      expect(dec.permission).toBe("deny");
+      expect(dec.raw).toContain("submitted to the user for approval"); // APPROVAL_REQUIRED
+      expect(h.ledger().map((e) => e.toolName)).toContain("Write");
+    });
+
+    it("a write-category lease does NOT bypass the secret block", () => {
+      const h = setup({ leasedCategories: ["write"] });
+      expect(h.decide(hookWrite("notes.md", "x")).permission).toBe("allow"); // non-secret rides the lease
+      const dec = h.decide(hookWrite(".env", "SECRET")); // secret is still hard-blocked
+      expect(dec.permission).toBe("deny");
+      expect(dec.raw).toContain("blocked for security");
+      expect(h.ledger()).toEqual([]);
+    });
+
+    it("hard-blocks a secret write in a git workspace with captureIgnored off (no storage)", () => {
+      const h = setup({ captureMode: true, captureIgnored: false, gitignored: [".env"] });
+      const dec = h.decide(hookWrite(".env", "API_KEY=abc"));
+      expect(dec.permission).toBe("deny");
+      expect(dec.raw).toContain("blocked for security");
+      expect(h.ledger()).toEqual([]);
+    });
+
+    it("does NOT hard-block a secret DELETE (no content; stays deny-gated)", () => {
+      const h = setup({});
+      expect(h.decide(hookDelete(".env")).permission).toBe("deny");
+      expect(h.ledger().map((e) => e.toolName)).toContain("Delete");
+    });
+  });
+
   // CAS parity (DD-18): with captureIgnored on, a non-secret gitignored write no
   // longer stays on the deny-gate — the hook stages its pre-turn bytes into the
   // cas-observations sidecar and ALLOWS it (apply-then-review), while a secret-

package/src/activities/execute-cursor/__tests__/turn-boundary.test.ts

@@ -0,0 +1,280 @@
+/**
+ * Tests for the extracted turn boundary (turn-boundary.ts) — the post-run
+ * pipeline shared by the primary path and the recovery retries.
+ *
+ * The load-bearing scenario is the recovery-retry sequence that motivated the
+ * extraction (production case aex_01kws27q1e2esvkqjpvectttxf): the primary
+ * boundary runs against an untouched tree (the resumed agent errored before
+ * doing anything), the retry agent then edits files, and the boundary is
+ * re-entered — the candidate must be authored exactly once and the turn must
+ * pause for review. Runs against a REAL temp git repo with in-memory
+ * transcript + status protos, mirroring capture-flow.test.ts.
+ */
+
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import {
+  AgentMessageSchema,
+  ToolCallSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import type { AgentMessage } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import {
+  FileReviewEventType,
+  MessageType,
+  ToolCallStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { captureBaselineToLedger } from "../capture-flow.js";
+import { denialLedgerPath } from "../approval-state.js";
+import { toolCallIdentityToken } from "../message-translator.js";
+import { runTurnBoundary, type TurnBoundaryOptions } from "../turn-boundary.js";
+
+const execFileAsync = promisify(execFile);
+const EXEC_ID = "exec-boundary-1";
+const CHANGE_SET_ID = `${EXEC_ID}:0`;
+
+let repo: string;
+let hitlDir: string;
+
+async function git(args: string[]): Promise<void> {
+  await execFileAsync("git", args, { cwd: repo });
+}
+async function write(rel: string, content: string): Promise<void> {
+  await writeFile(join(repo, rel), content, "utf-8");
+}
+
+function newStatus(): AgentExecutionStatus {
+  return create(AgentExecutionStatusSchema, {});
+}
+
+/** A streamed (COMPLETED) file-edit tool call, as the SDK would have recorded. */
+function streamedEdit(id: string, path: string, content: string): AgentMessage {
+  return create(AgentMessageSchema, {
+    type: MessageType.MESSAGE_AI,
+    toolCalls: [
+      create(ToolCallSchema, {
+        id,
+        name: "edit",
+        status: ToolCallStatus.TOOL_CALL_COMPLETED,
+        args: { path, content },
+      }),
+    ],
+  });
+}
+
+/** Boundary options for this repo's turn; overrides layer the per-test shape. */
+function boundaryOpts(
+  status: AgentExecutionStatus,
+  baselineTree: string,
+  overrides?: Partial<TurnBoundaryOptions>,
+): TurnBoundaryOptions {
+  return {
+    status,
+    executionId: EXEC_ID,
+    changeSetId: CHANGE_SET_ID,
+    hitlDir,
+    captureMode: true,
+    baselineTree,
+    primaryWorkspaceDir: repo,
+    gitWorkspace: true,
+    turnStartMessageIndex: 0,
+    approvalGrants: undefined,
+    globalBypass: false,
+    seededSubAgents: [],
+    artifactStorage: undefined,
+    mergedPolicies: new Map(),
+    ...overrides,
+  };
+}
+
+function candidateEvents(status: AgentExecutionStatus) {
+  return (status.fileReviewEventStream?.events ?? []).filter(
+    (e) => e.eventType === FileReviewEventType.CANDIDATE_CAPTURED,
+  );
+}
+
+beforeEach(async () => {
+  repo = await mkdtemp(join(tmpdir(), "stigmer-boundary-repo-"));
+  hitlDir = await mkdtemp(join(tmpdir(), "stigmer-boundary-hitl-"));
+  await git(["init", "-q"]);
+  await git(["config", "user.email", "t@t.local"]);
+  await git(["config", "user.name", "t"]);
+  await write("notes.md", "original notes\n");
+  await git(["add", "-A"]);
+  await git(["commit", "-q", "-m", "initial"]);
+});
+
+afterEach(async () => {
+  await rm(repo, { recursive: true, force: true });
+  await rm(hitlDir, { recursive: true, force: true });
+});
+
+describe("runTurnBoundary", () => {
+  it("authors a candidate, stamps the row, and pauses when the turn edited files", async () => {
+    const status = newStatus();
+    const baseline = await captureBaselineToLedger({
+      status,
+      gitRoot: repo,
+      executionId: EXEC_ID,
+      changeSetId: CHANGE_SET_ID,
+    });
+
+    await write("notes.md", "original notes\n\n## TODO\n- ship\n");
+    status.messages.push(
+      streamedEdit("tc-1", "notes.md", "original notes\n\n## TODO\n- ship\n"),
+    );
+
+    const result = await runTurnBoundary(boundaryOpts(status, baseline));
+
+    expect(result.waiting).toBe(true);
+    expect(result.capturedChangeCount).toBe(1);
+    expect(result.deniedToolCallCount).toBe(0);
+    expect(candidateEvents(status)).toHaveLength(1);
+    // The streamed row is stamped with the change set id (observational record
+    // anchoring the decision surface).
+    expect(status.messages[0].toolCalls[0].fileChangeSetId).toBe(CHANGE_SET_ID);
+  });
+
+  it("reports a clean turn when nothing changed (no candidate, no pause)", async () => {
+    const status = newStatus();
+    const baseline = await captureBaselineToLedger({
+      status,
+      gitRoot: repo,
+      executionId: EXEC_ID,
+      changeSetId: CHANGE_SET_ID,
+    });
+
+    const result = await runTurnBoundary(boundaryOpts(status, baseline));
+
+    expect(result.waiting).toBe(false);
+    expect(result.capturedChangeCount).toBe(0);
+    expect(result.deniedToolCallCount).toBe(0);
+    expect(candidateEvents(status)).toHaveLength(0);
+  });
+
+  it("skips capture when no baseline was authored this turn", async () => {
+    const status = newStatus();
+    await write("notes.md", "edited without a baseline\n");
+
+    const result = await runTurnBoundary(
+      boundaryOpts(status, "", { baselineTree: undefined }),
+    );
+
+    expect(result.waiting).toBe(false);
+    expect(result.capturedChangeCount).toBe(0);
+    expect(candidateEvents(status)).toHaveLength(0);
+  });
+
+  it("re-entered after a no-op primary call, authors the candidate exactly once (recovery-retry sequence)", async () => {
+    const status = newStatus();
+    const baseline = await captureBaselineToLedger({
+      status,
+      gitRoot: repo,
+      executionId: EXEC_ID,
+      changeSetId: CHANGE_SET_ID,
+    });
+
+    // Primary boundary: the resumed agent errored before touching anything —
+    // the tree is at baseline, no candidate is authored, the turn looks clean.
+    const primary = await runTurnBoundary(boundaryOpts(status, baseline));
+    expect(primary.waiting).toBe(false);
+    expect(candidateEvents(status)).toHaveLength(0);
+
+    // Recovery retry: a fresh agent re-ran the prompt and created the file.
+    await write("notes.md", "original notes\n\nretry made this edit\n");
+    status.messages.push(
+      streamedEdit("tc-retry", "notes.md", "original notes\n\nretry made this edit\n"),
+    );
+
+    // Boundary re-entry: the retry's edit reaches the ledger and arms the gate.
+    const retry = await runTurnBoundary(boundaryOpts(status, baseline));
+    expect(retry.waiting).toBe(true);
+    expect(retry.capturedChangeCount).toBe(1);
+    expect(candidateEvents(status)).toHaveLength(1);
+    expect(status.messages[0].toolCalls[0].fileChangeSetId).toBe(CHANGE_SET_ID);
+  });
+
+  it("surfaces a hook denial as a WAITING_APPROVAL gate and pauses", async () => {
+    const status = newStatus();
+    const baseline = await captureBaselineToLedger({
+      status,
+      gitRoot: repo,
+      executionId: EXEC_ID,
+      changeSetId: CHANGE_SET_ID,
+    });
+
+    // The hook gated a shell command mid-turn; the streamed call is still
+    // RUNNING (Cursor reported the deny to the model, not a completion).
+    const shellCall = create(ToolCallSchema, {
+      id: "tc-shell",
+      name: "shell",
+      status: ToolCallStatus.TOOL_CALL_RUNNING,
+      args: { command: "rm -rf build" },
+    });
+    status.messages.push(
+      create(AgentMessageSchema, {
+        type: MessageType.MESSAGE_AI,
+        content: "cleaning the build dir",
+        toolCalls: [shellCall],
+      }),
+    );
+    await writeFile(
+      denialLedgerPath(hitlDir),
+      JSON.stringify({ toolName: "shell", token: toolCallIdentityToken(shellCall) }) + "\n",
+      "utf-8",
+    );
+
+    const result = await runTurnBoundary(boundaryOpts(status, baseline));
+
+    expect(result.waiting).toBe(true);
+    expect(result.deniedToolCallCount).toBe(1);
+    expect(result.capturedChangeCount).toBe(0);
+    expect(shellCall.status).toBe(ToolCallStatus.TOOL_CALL_WAITING_APPROVAL);
+  });
+
+  it("waits for the denial-stop cancel to settle before reading the ledger", async () => {
+    const status = newStatus();
+    const baseline = await captureBaselineToLedger({
+      status,
+      gitRoot: repo,
+      executionId: EXEC_ID,
+      changeSetId: CHANGE_SET_ID,
+    });
+
+    const shellCall = create(ToolCallSchema, {
+      id: "tc-late",
+      name: "shell",
+      status: ToolCallStatus.TOOL_CALL_RUNNING,
+      args: { command: "curl example.com" },
+    });
+    status.messages.push(
+      create(AgentMessageSchema, {
+        type: MessageType.MESSAGE_AI,
+        toolCalls: [shellCall],
+      }),
+    );
+
+    // The denial lands only while the cancel is settling — a premature ledger
+    // read would miss it and leave the row RUNNING forever.
+    const denialCancelSettled = (async () => {
+      await writeFile(
+        denialLedgerPath(hitlDir),
+        JSON.stringify({ toolName: "shell", token: toolCallIdentityToken(shellCall) }) + "\n",
+        "utf-8",
+      );
+    })();
+
+    const result = await runTurnBoundary(
+      boundaryOpts(status, baseline, { denialCancelSettled }),
+    );
+
+    expect(result.deniedToolCallCount).toBe(1);
+    expect(shellCall.status).toBe(ToolCallStatus.TOOL_CALL_WAITING_APPROVAL);
+  });
+});