@stigmer/runner 3.10.0 → 3.11.1-dev.20260812192248

package/src/activities/execute-deep-agent/__tests__/hitl-resume-history.test.ts

@@ -219,6 +219,7 @@ function fakeDurableResumeSetup(): SetupResult {
     // path shared across files would serialize parallel test workers for real.
     workspaceBackend: { rootDir: "/tmp/stigmer-test-ws-hitl-history" },
     mcpConnection: null,
+    datastoreToolsMissing: [],
     mergedEnvVars: {},
     secretKeys: new Set<string>(),
     modelName: "claude-sonnet",

package/src/activities/execute-deep-agent/__tests__/plan-mode-path-normalization.test.ts

@@ -0,0 +1,174 @@
+/**
+ * End-to-end proof (real deepagents + LangGraph runtime, no LLM/network) that
+ * a plan-mode PARENT graph accepts workspace-relative paths (issue #429).
+ *
+ * Before the fix, deepagents' permission enforcement canonicalized every
+ * filesystem tool-call path BEFORE any rule ran and refused non-absolute
+ * shapes, so on a rule-bearing graph a workspace-relative call — reads
+ * included — died with `path must be absolute` instead of just working. The
+ * path-normalization middleware (middleware/path-normalization.ts) rewrites
+ * relative paths to workspace-absolute at our seam, before enforcement sees
+ * them.
+ *
+ * The graph here is composed exactly the way setup.ts composes the parent:
+ * the PRODUCTION buildMiddlewareStack (pathNormalization present, the
+ * rule-bearing shape) + the CAS capture backend + the PRODUCTION
+ * PLAN_MODE_PERMISSIONS constant. These tests are also the empirical proof
+ * that langchain's wrapToolCall seam delivers rewritten args to the tool —
+ * if it did not, the relative read below could never succeed.
+ *
+ * The sub-agent twin of this contract is pinned in
+ * subagent-plan-mode-permissions.test.ts (issue #255 wiring).
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, mkdir, rm, readFile, writeFile, access } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { HumanMessage, ToolMessage, type BaseMessage } from "@langchain/core/messages";
+import { MemorySaver } from "@langchain/langgraph";
+import { createDeepAgent } from "deepagents";
+
+import { PLAN_MODE_PERMISSIONS } from "../../../shared/plan-mode-permissions.js";
+import { buildMiddlewareStack } from "../../../middleware/index.js";
+import { createCasCaptureBackend } from "../cas-capture-backend.js";
+import { CasCaptureObserver } from "../cas-capture-observer.js";
+import { ScriptedModel, type ScriptSelector } from "../__test-utils__/scripted-model.js";
+
+const SEEDED_CONTENT = "PLAN_MODE_README_TOKEN: hello from the seeded file";
+
+describe("plan-mode parent path normalization (issue #429)", () => {
+  let root: string;
+  let observer: CasCaptureObserver;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "plan-path-"));
+    await mkdir(join(root, "src"), { recursive: true });
+    await writeFile(join(root, "src/notes.md"), SEEDED_CONTENT);
+    observer = new CasCaptureObserver({ rootDir: root, isIgnored: async () => true });
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  /**
+   * Build a parent graph the way setup.ts does in plan mode: the production
+   * middleware stack with pathNormalization set (derived, like the graph's
+   * permissions, from the plan-mode rules), a filesystem-only CAS capture
+   * backend (no shellEnv — plan mode clears it), and PLAN_MODE_PERMISSIONS
+   * on the graph.
+   */
+  async function buildPlanModeParent(script: ScriptSelector) {
+    const { middleware } = buildMiddlewareStack({
+      approvalGate: null,
+      pathNormalization: { rootDir: root },
+    });
+    const backend = await createCasCaptureBackend({ rootDir: root, observer });
+    return createDeepAgent({
+      model: new ScriptedModel(script),
+      checkpointer: new MemorySaver() as never,
+      backend,
+      middleware: middleware as never[],
+      permissions: PLAN_MODE_PERMISSIONS,
+    } as Parameters<typeof createDeepAgent>[0]);
+  }
+
+  function toolResultById(messages: BaseMessage[], toolCallId: string): string {
+    const match = messages.find(
+      (m): m is ToolMessage => m instanceof ToolMessage && m.tool_call_id === toolCallId,
+    );
+    expect(match, `expected a tool result for call '${toolCallId}'`).toBeDefined();
+    return typeof match!.content === "string" ? match!.content : JSON.stringify(match!.content);
+  }
+
+  async function invokeOnce(script: ScriptSelector, threadId: string) {
+    const agent = await buildPlanModeParent(script);
+    return (await agent.invoke(
+      { messages: [new HumanMessage({ content: "go" })] },
+      { configurable: { thread_id: threadId }, recursionLimit: 50 },
+    )) as { messages: BaseMessage[] };
+  }
+
+  it("a prompt-compliant relative read succeeds on the first tool round", async () => {
+    const result = await invokeOnce(
+      () => ({
+        toolCalls: [
+          { name: "read_file", args: { file_path: "src/notes.md" }, id: "c_read_rel" },
+        ],
+        done: "done",
+      }),
+      "t_read_rel",
+    );
+
+    const readResult = toolResultById(result.messages, "c_read_rel");
+    expect(readResult).toContain("PLAN_MODE_README_TOKEN");
+    expect(readResult).not.toMatch(/path must be absolute/i);
+    expect(readResult).not.toMatch(/permission denied/i);
+  });
+
+  it("a relative write is refused by the RULES — permission denied, not a path-shape error", async () => {
+    const result = await invokeOnce(
+      () => ({
+        toolCalls: [
+          { name: "write_file", args: { file_path: "src/out.txt", content: "x" }, id: "c_write_rel" },
+        ],
+        done: "done",
+      }),
+      "t_write_rel",
+    );
+
+    // The deny-all-writes rule fires on the normalized path — the honest
+    // plan-mode refusal the model can reason about, instead of the
+    // pre-fix validation error that taught it to abandon relative paths.
+    expect(toolResultById(result.messages, "c_write_rel")).toMatch(/permission denied for write/i);
+    expect(toolResultById(result.messages, "c_write_rel")).not.toMatch(/path must be absolute/i);
+    await expect(access(join(root, "src/out.txt"))).rejects.toThrow();
+    expect(observer.before.size).toBe(0);
+  });
+
+  it("an escaping relative read is still refused — normalization grants no new reachability", async () => {
+    // Outside the root, reachable only if `..` were naively joined away.
+    const result = await invokeOnce(
+      () => ({
+        toolCalls: [
+          { name: "read_file", args: { file_path: "../escape.txt" }, id: "c_read_escape" },
+        ],
+        done: "done",
+      }),
+      "t_read_escape",
+    );
+
+    // Left raw by the middleware, refused by upstream validation exactly as
+    // before the fix.
+    expect(toolResultById(result.messages, "c_read_escape")).toMatch(/must not contain|path must be absolute/i);
+  });
+
+  it("absolute in-workspace paths keep working unchanged", async () => {
+    const result = await invokeOnce(
+      () => ({
+        toolCalls: [
+          { name: "read_file", args: { file_path: join(root, "src/notes.md") }, id: "c_read_abs" },
+        ],
+        done: "done",
+      }),
+      "t_read_abs",
+    );
+
+    expect(toolResultById(result.messages, "c_read_abs")).toContain("PLAN_MODE_README_TOKEN");
+  });
+
+  it("relative ls flows through normalization to list the workspace directory", async () => {
+    const result = await invokeOnce(
+      () => ({
+        toolCalls: [{ name: "ls", args: { path: "src" }, id: "c_ls_rel" }],
+        done: "done",
+      }),
+      "t_ls_rel",
+    );
+
+    const lsResult = toolResultById(result.messages, "c_ls_rel");
+    expect(lsResult).toContain("notes.md");
+    expect(lsResult).not.toMatch(/path must be absolute/i);
+  });
+});

package/src/activities/execute-deep-agent/__tests__/prompt-builder.test.ts

@@ -142,6 +142,10 @@ describe("buildEnhancedSystemPrompt", () => {
   });
 
   it("includes injected files section with size info", () => {
+    // The section renders the injector's own result type (sizeBytes). A local
+    // structural twin with a `size` field used to live in the prompt builder,
+    // and production wiring silently dropped the size — this pin holds the
+    // real field name so that drift class cannot return.
     const prompt = buildEnhancedSystemPrompt({
       instructions: "Test",
       provisionResults: [],
@@ -150,15 +154,40 @@ describe("buildEnhancedSystemPrompt", () => {
       workspaceFileRefs: [],
       workspaceRoot: "/workspace",
       injectedFiles: [
-        { filename: "data.csv", path: ".stigmer/inputs/data.csv", size: 1024 },
-        { filename: "notes.md", path: ".stigmer/inputs/notes.md", size: null },
+        { filename: "data.csv", path: ".stigmer/inputs/data.csv", sizeBytes: 1024 },
+        { filename: "notes.md", path: ".stigmer/inputs/notes.md", sizeBytes: 12 },
       ],
     });
 
     expect(prompt).toContain("## Input Files");
     expect(prompt).toContain("`.stigmer/inputs/data.csv` (1024 bytes)");
-    expect(prompt).toContain("`.stigmer/inputs/notes.md`");
-    expect(prompt).not.toContain("null");
+    expect(prompt).toContain("`.stigmer/inputs/notes.md` (12 bytes)");
+  });
+
+  it("discloses a duplicate-renamed injected file's original name", () => {
+    const prompt = buildEnhancedSystemPrompt({
+      instructions: "Test",
+      provisionResults: [],
+      containerRoot: "",
+      skillsPromptSection: "",
+      workspaceFileRefs: [],
+      workspaceRoot: "/workspace",
+      injectedFiles: [
+        { filename: "report.pdf", path: ".stigmer/inputs/report.pdf", sizeBytes: 10 },
+        {
+          filename: "report-2.pdf",
+          path: ".stigmer/inputs/report-2.pdf",
+          sizeBytes: 20,
+          renamedFrom: "report.pdf",
+        },
+      ],
+    });
+
+    expect(prompt).toContain(
+      "`.stigmer/inputs/report-2.pdf` (20 bytes) (renamed from duplicate 'report.pdf')",
+    );
+    // The first file keeps a clean entry — no disclosure noise.
+    expect(prompt).toContain("`.stigmer/inputs/report.pdf` (10 bytes)\n");
   });
 
   it("produces a git repo description for git workspace entries", () => {
@@ -361,7 +390,7 @@ describe("buildEnhancedSystemPrompt", () => {
     const planFile = {
       filename: "plan.md",
       path: ".stigmer/inputs/plan.md",
-      size: 1024,
+      sizeBytes: 1024,
     };
 
     it("appends the implement-plan directive pointing at the injected plan", () => {

package/src/activities/execute-deep-agent/__tests__/sequential-gate-resume.test.ts

@@ -196,6 +196,7 @@ function fakeMemoryGateSetup(opts: {
       readFile: vi.fn(async () => ""),
     },
     mcpConnection: null,
+    datastoreToolsMissing: [],
     mergedEnvVars: {},
     secretKeys: new Set<string>(),
     modelName: "claude-sonnet",

package/src/activities/execute-deep-agent/__tests__/shell-env.test.ts

@@ -1,22 +1,36 @@
 import { describe, it, expect } from "vitest";
 import { buildShellEnv, SHELL_ENV_DENYLIST } from "../shell-env.js";
+import { RUNNER_CREDENTIAL_ENV_KEYS } from "../../../shared/runner-credential-keys.js";
 
 describe("buildShellEnv", () => {
-  it("strips runner-internal credentials from the base env", () => {
-    const base = {
-      PATH: "/usr/bin",
-      HOME: "/home/runner",
-      STIGMER_RUNNER_HITL_SECRET: "secret",
-      CURSOR_API_KEY: "cursor-key",
-      STIGMER_TOKEN: "stigmer-token",
-    };
+  it("strips every runner credential from the base env", () => {
+    // Plant a value for every name in the source-of-truth list, so a key
+    // added to runner-credential-keys.ts is covered here automatically.
+    const base: NodeJS.ProcessEnv = { PATH: "/usr/bin", HOME: "/home/runner" };
+    for (const key of RUNNER_CREDENTIAL_ENV_KEYS) {
+      base[key] = `leaked-${key}`;
+    }
 
     const env = buildShellEnv({}, base);
 
     expect(env.PATH).toBe("/usr/bin");
     expect(env.HOME).toBe("/home/runner");
-    for (const key of SHELL_ENV_DENYLIST) {
-      expect(env[key]).toBeUndefined();
+    for (const key of RUNNER_CREDENTIAL_ENV_KEYS) {
+      expect(env[key], `runner credential '${key}' must not reach the shell env`).toBeUndefined();
+    }
+  });
+
+  it("denies the full credential list, not just the original three (issue #385)", () => {
+    // Pins the five names #385 added. The parameterized test above would
+    // pass even if the list regressed to three; this one cannot.
+    for (const key of [
+      "ANTHROPIC_API_KEY",
+      "OPENAI_API_KEY",
+      "STIGMER_AUTH_TOKEN",
+      "ANTHROPIC_FOUNDRY_API_KEY",
+      "AWS_BEARER_TOKEN_BEDROCK",
+    ]) {
+      expect(SHELL_ENV_DENYLIST, `'${key}' must be in the shell denylist`).toContain(key);
     }
   });
 

package/src/activities/execute-deep-agent/__tests__/subagent-plan-mode-permissions.test.ts

@@ -0,0 +1,178 @@
+/**
+ * End-to-end proof (real deepagents + LangGraph runtime, no LLM/network) that a
+ * plan-mode SUB-AGENT is read-only BY CONSTRUCTION (issue #255).
+ *
+ * The parent graph receives PLAN_MODE_PERMISSIONS in setup.ts, but deepagents'
+ * parent-permission inheritance covers only spec-style sub-agents — our
+ * pre-built CompiledSubAgents bypass `normalizeSubagentSpec` entirely, so
+ * `compileSubagents` must bake the rules into each sub-agent graph itself.
+ * These tests exercise that exact wiring with NO approval gate installed (the
+ * auto-approve-all shape): any denial must come from the permission rules
+ * alone, proving plan mode's "read-only by construction, not by gate"
+ * contract at the sub-agent level. A contrast case pins that without the
+ * rules (act mode) the same write flows — this change is a plan-mode-only
+ * delta.
+ *
+ * The rule under test is the PRODUCTION constant from
+ * shared/plan-mode-permissions.ts (the same one setup.ts applies to both
+ * graph sites), not a test copy, so a change to the plan-mode permission set
+ * re-proves sub-agent coverage automatically.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, mkdir, rm, readFile, writeFile, access } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { HumanMessage, ToolMessage, type BaseMessage } from "@langchain/core/messages";
+
+import { PLAN_MODE_PERMISSIONS } from "../../../shared/plan-mode-permissions.js";
+import { CasCaptureObserver } from "../cas-capture-observer.js";
+import { compileSubagents } from "../subagent-transformer.js";
+import { ScriptedModel, type ScriptSelector } from "../__test-utils__/scripted-model.js";
+
+const SEEDED_CONTENT = "PLAN_MODE_README_TOKEN: hello from the seeded file";
+
+describe("plan-mode sub-agent filesystem permissions (issue #255)", () => {
+  let root: string;
+  let observer: CasCaptureObserver;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "sa-plan-"));
+    await mkdir(join(root, "dist"), { recursive: true });
+    await writeFile(join(root, "notes.md"), SEEDED_CONTENT);
+    // Everything is gitignored from the observer's view — the strictest case:
+    // every write would be CAS-observed if it ever reached the backend.
+    observer = new CasCaptureObserver({ rootDir: root, isIgnored: async () => true });
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  /**
+   * Compile a worker through the production path with NO approval gate, so the
+   * permission rules are the only thing standing between the model and the
+   * filesystem. `permissions` present = the plan-mode wiring under test;
+   * absent = the act-mode contrast.
+   */
+  async function compileWorker(script: ScriptSelector, planMode: boolean) {
+    const compiled = await compileSubagents(
+      [{ name: "worker", description: "test worker", systemPrompt: "do the work", tools: [] }],
+      {
+        approvalGate: null,
+        parentModelName: "test-model",
+        workspaceRootDir: root,
+        casObserver: observer,
+        modelFactory: async () => new ScriptedModel(script),
+        ...(planMode ? { permissions: PLAN_MODE_PERMISSIONS } : {}),
+      },
+    );
+    expect(compiled).toHaveLength(1);
+    return compiled[0];
+  }
+
+  function toolResultById(messages: BaseMessage[], toolCallId: string): string {
+    const match = messages.find(
+      (m): m is ToolMessage => m instanceof ToolMessage && m.tool_call_id === toolCallId,
+    );
+    expect(match, `expected a tool result for call '${toolCallId}'`).toBeDefined();
+    return typeof match!.content === "string" ? match!.content : JSON.stringify(match!.content);
+  }
+
+  it("denies write_file and edit_file at the tool level, while read_file still works", async () => {
+    // One turn, three tool calls: both mutation tools must be denied by the
+    // permission rules; the read must pass through untouched (the deny rule
+    // covers the `write` operation class only).
+    // Absolute workspace paths — the canonical shape after enforcement
+    // canonicalization, and what the single-workspace prompt's prose (the
+    // absolute rootDir) steers models toward. The workspace-relative shape
+    // is pinned separately below (issue #429).
+    const script: ScriptSelector = () => ({
+      toolCalls: [
+        { name: "write_file", args: { file_path: join(root, "dist/out.txt"), content: "new file" }, id: "c_write" },
+        { name: "edit_file", args: { file_path: join(root, "notes.md"), old_string: "hello", new_string: "HACKED" }, id: "c_edit" },
+        { name: "read_file", args: { file_path: join(root, "notes.md") }, id: "c_read" },
+      ],
+      done: "worker done",
+    });
+
+    const worker = await compileWorker(script, true);
+    const result = (await worker.runnable.invoke(
+      { messages: [new HumanMessage({ content: "go" })] },
+      { configurable: { thread_id: "t1" }, recursionLimit: 50 },
+    )) as { messages: BaseMessage[] };
+
+    // Both mutations denied with deepagents' permission error, and nothing on disk:
+    // the new file was never created and the seeded file is byte-identical.
+    expect(toolResultById(result.messages, "c_write")).toMatch(/permission denied for write/i);
+    expect(toolResultById(result.messages, "c_edit")).toMatch(/permission denied for write/i);
+    await expect(access(join(root, "dist/out.txt"))).rejects.toThrow();
+    expect(await readFile(join(root, "notes.md"), "utf8")).toBe(SEEDED_CONTENT);
+
+    // The read flowed: its result carries the seeded content, not a denial.
+    const readResult = toolResultById(result.messages, "c_read");
+    expect(readResult).toContain("PLAN_MODE_README_TOKEN");
+    expect(readResult).not.toMatch(/permission denied/i);
+
+    // The denial fired INSIDE the tool handler, before any backend was reached:
+    // the CAS observer (which records pre-write bytes on the backend's write/edit
+    // seams) saw neither mutation.
+    expect(observer.before.size).toBe(0);
+  });
+
+  it("act-mode contrast: without the permissions option the same write lands (zero-delta outside plan mode)", async () => {
+    const script: ScriptSelector = () => ({
+      toolCalls: [
+        { name: "write_file", args: { file_path: join(root, "dist/out.txt"), content: "new file" }, id: "c_write" },
+      ],
+      done: "worker done",
+    });
+
+    const worker = await compileWorker(script, false);
+    const result = (await worker.runnable.invoke(
+      { messages: [new HumanMessage({ content: "go" })] },
+      { configurable: { thread_id: "t2" }, recursionLimit: 50 },
+    )) as { messages: BaseMessage[] };
+
+    expect(toolResultById(result.messages, "c_write")).not.toMatch(/permission denied/i);
+    expect(await readFile(join(root, "dist/out.txt"), "utf8")).toBe("new file");
+    // And the backend WAS reached this time — the observer recorded a write.
+    // (Key shape is DD-19 territory, deliberately not pinned here.)
+    expect(observer.before.size).toBe(1);
+  });
+
+  it("relative-path writes are refused by the RULES, and relative reads flow (issue #429)", async () => {
+    // The multi-workspace prompt mandates workspace-relative paths, and
+    // models routinely choose them in single-workspace sessions too. Before
+    // the #429 fix, deepagents' permission canonicalization refused the
+    // shape outright — every relative call, reads included, died with
+    // "path must be absolute" before any rule ran. compileSubagents now
+    // derives a path-normalization shim from the same `permissions` it
+    // bakes into the graph, so the relative shape reaches the rules in
+    // canonical form: writes get the honest plan-mode denial, reads just
+    // work. Read-only-by-construction (issue #255) holds throughout.
+    const script: ScriptSelector = () => ({
+      toolCalls: [
+        { name: "write_file", args: { file_path: "dist/out.txt", content: "new file" }, id: "c_write_rel" },
+        { name: "read_file", args: { file_path: "notes.md" }, id: "c_read_rel" },
+      ],
+      done: "worker done",
+    });
+
+    const worker = await compileWorker(script, true);
+    const result = (await worker.runnable.invoke(
+      { messages: [new HumanMessage({ content: "go" })] },
+      { configurable: { thread_id: "t3" }, recursionLimit: 50 },
+    )) as { messages: BaseMessage[] };
+
+    const writeResult = toolResultById(result.messages, "c_write_rel");
+    expect(writeResult).toMatch(/permission denied for write/i);
+    expect(writeResult).not.toMatch(/path must be absolute/i);
+    await expect(access(join(root, "dist/out.txt"))).rejects.toThrow();
+    expect(observer.before.size).toBe(0);
+
+    const readResult = toolResultById(result.messages, "c_read_rel");
+    expect(readResult).toContain("PLAN_MODE_README_TOKEN");
+    expect(readResult).not.toMatch(/path must be absolute/i);
+  });
+});

package/src/activities/execute-deep-agent/__tests__/subagent-wiring.test.ts

@@ -7,10 +7,11 @@ describe("buildSubAgentMiddleware", () => {
   it("returns the correct middleware order without cost cap", () => {
     const stack = buildSubAgentMiddleware();
 
-    expect(stack).toHaveLength(3);
+    expect(stack).toHaveLength(4);
     expect(stack[0].name).toBe("LoopDetectionMiddleware");
     expect(stack[1].name).toBe("ExecutionBudgetMiddleware");
     expect(stack[2].name).toBe("ToolTruncationMiddleware");
+    expect(stack[3].name).toBe("ErrorHintsMiddleware");
   });
 
   it("includes cost cap view when parent cost cap is provided", () => {
@@ -24,8 +25,9 @@ describe("buildSubAgentMiddleware", () => {
 
     const stack = buildSubAgentMiddleware({ costCap: parentCostCap });
 
-    expect(stack).toHaveLength(4);
+    expect(stack).toHaveLength(5);
     expect(stack[3].name).toBe("CostCapSubAgentView");
+    expect(stack[4].name).toBe("ErrorHintsMiddleware");
   });
 
   it("sub-agent cost cap view shares parent state", () => {
@@ -75,8 +77,8 @@ describe("buildSubAgentMiddleware", () => {
       approvalGate: { policies: new Map(), toolServerMap: new Map() },
     });
 
-    // loop, budget, truncation, approval gate
-    expect(stack).toHaveLength(4);
+    // loop, budget, truncation, approval gate, error hints
+    expect(stack).toHaveLength(5);
     expect(stack[3].name).toBe("ApprovalGateMiddleware");
     expect(stack[3].wrapToolCall).toBeDefined();
   });
@@ -84,7 +86,7 @@ describe("buildSubAgentMiddleware", () => {
   it("omits the approval gate when approvalGate is null (auto-approve-all parity)", () => {
     const stack = buildSubAgentMiddleware({ approvalGate: null });
 
-    expect(stack).toHaveLength(3);
+    expect(stack).toHaveLength(4);
     expect(stack.some((m) => m.name === "ApprovalGateMiddleware")).toBe(false);
   });
 
@@ -102,10 +104,13 @@ describe("buildSubAgentMiddleware", () => {
       approvalGate: { policies: new Map(), toolServerMap: new Map() },
     });
 
-    // loop, budget, truncation, approval gate, cost cap view
-    expect(stack).toHaveLength(5);
+    // loop, budget, truncation, approval gate, cost cap view, error hints.
+    // Hints AFTER the gate matches the parent nesting: the gate's HITL
+    // interrupt stays outside the hints' try/catch (issue #255).
+    expect(stack).toHaveLength(6);
     expect(stack[3].name).toBe("ApprovalGateMiddleware");
     expect(stack[4].name).toBe("CostCapSubAgentView");
+    expect(stack[5].name).toBe("ErrorHintsMiddleware");
   });
 
   // captureIgnored is the structural coupling that makes sub-agent gitignored