@stigmer/runner 3.32.0 → 3.33.0

package/src/activities/execute-deep-agent/__tests__/hermetic/goldens/sub-agent-delegation.status.json

@@ -12,7 +12,7 @@
             "description": "Look up the fixture value.",
             "subagent_type": "helper"
           },
-          "result": "[{\"type\":\"text\",\"text\":\"The fixture value is forty-two.\"}]",
+          "result": "The fixture value is forty-two.",
           "status": "TOOL_CALL_COMPLETED",
           "startedAt": "2026-01-01T00:00:01.000Z",
           "completedAt": "2026-01-01T00:00:02.000Z",
@@ -33,7 +33,7 @@
       "id": "call-hermetic-task-0001",
       "name": "helper",
       "input": "Look up the fixture value.",
-      "output": "[{\"type\":\"text\",\"text\":\"The fixture value is forty-two.\"}]",
+      "output": "The fixture value is forty-two.",
       "status": "SUB_AGENT_COMPLETED",
       "startedAt": "2026-01-01T00:00:01.000Z",
       "completedAt": "2026-01-01T00:00:02.000Z",

package/src/activities/execute-deep-agent/__tests__/hermetic/goldens/tool-call.status.json

@@ -11,7 +11,7 @@
           "args": {
             "file_path": "/README.md"
           },
-          "result": "[{\"type\":\"text\",\"text\":\"     1\\t# Hermetic\\n     2\\t\\n     3\\tA fixture readme.\"}]",
+          "result": "[{\"type\":\"text\",\"text\":\"@@ lines 1-3 of 3 @@\\n# Hermetic\\n\\nA fixture readme.\"}]",
           "status": "TOOL_CALL_COMPLETED",
           "startedAt": "2026-01-01T00:00:01.000Z",
           "completedAt": "2026-01-01T00:00:01.000Z",

package/src/activities/execute-deep-agent/__tests__/hermetic/plain-turn.test.ts

@@ -15,12 +15,16 @@
  * model streams, so the events under this golden are the ones a provider
  * produces (`scripted-model.ts` header).
  *
- * Two shapes of the activity's wire contract ride on the same golden, and
- * matching the SAME file is the assertion that they are invisible to the
- * status: the legacy positional `(executionId, threadId)` form the control
- * planes still may send (`shared/activity-input.ts`), and an empty
- * `thread_id` (carried from `index.test.ts`: "handles empty threadId
- * gracefully").
+ * The legacy positional `(executionId, threadId)` form the control planes
+ * still may send (`shared/activity-input.ts`) rides on the same golden, and
+ * matching the SAME file is the assertion that it is invisible to the status.
+ * An empty `thread_id` rode here too (carried from `index.test.ts`: "handles
+ * empty threadId gracefully") until @langchain/langgraph-checkpoint 1.1's
+ * memory saver started refusing an empty key. That arm was only ever true of
+ * the test-only memory saver: the native thread id is runtime-minted
+ * (`EnsureThread` sends `thread-{sessionId}` on every invocation), and the
+ * sqlite saver the runner ships has always refused an empty one
+ * (`shared/checkpointer/sqlite-saver.ts`), so no saver left to prove it on.
  *
  * Since #1096 the activity is the turn runtime over the native adapter, and
  * `streamingUsage` carries the runtime accountant's fields — `model`,
@@ -132,11 +136,4 @@ describe("ExecuteDeepAgent hermetic — plain turn", () => {
     const json = JSON.stringify(toJson(AgentExecutionStatusSchema, record.lastFullStatus!), null, 2) + "\n";
     await expect(json).toMatchFileSnapshot(GOLDEN);
   });
-
-  it("produces the same status with an empty thread_id", async () => {
-    const { record, invocation } = await runPlainTurn({ threadId: "" });
-    expect(invocation.outcome.kind).toBe("returned");
-    const json = JSON.stringify(toJson(AgentExecutionStatusSchema, record.lastFullStatus!), null, 2) + "\n";
-    await expect(json).toMatchFileSnapshot(GOLDEN);
-  });
 });

package/src/activities/execute-deep-agent/__tests__/hermetic/resume-across-engine-upgrade.test.ts

@@ -0,0 +1,374 @@
+/**
+ * Hermetic net: a session paused for approval on an OLDER engine resumes on
+ * this one. Every stored checkpoint crosses an engine upgrade (deepagents,
+ * langchain, `@langchain/langgraph` and its checkpoint library move
+ * together), and cloud sessions live in the server's database, so "a session
+ * paused before the upgrade resumes after it" is a property the runner owes on
+ * both savers, not an accident of the serializer.
+ *
+ * The fixtures in `./fixtures/paused-session.deepagents-<version>.json` are
+ * the checkpoint rows an OLDER engine wrote, never regenerated after the fact:
+ * each is recorded on the engine it names, before the upgrade that leaves it
+ * behind, and committed with that upgrade. The scenario it froze:
+ *
+ *  - round 0: the model writes its to-do list (`write_todos`, ungated);
+ *  - round 1: the model proposes a gated `execute`; the gate's `interrupt()`
+ *    pauses the graph and the activity persists WAITING_FOR_APPROVAL.
+ *
+ * A fixture carries the sqlite rows (`checkpoints`, `writes`) with each blob
+ * as UTF-8 text when it is JSON (the serializer's `json` tag) and base64
+ * otherwise, and the status the server held when the turn returned.
+ *
+ * What each fixture proves on the CURRENT engine:
+ *  - sqlite, end to end: the rows are loaded into the session's checkpoint
+ *    file, the server-held status is seeded, APPROVE is decided as
+ *    `SubmitApproval` would, and the reinvocation resumes INSIDE the gate — the
+ *    command runs exactly once, the run closes COMPLETED, and the to-do list
+ *    the old engine wrote survives.
+ *  - http: the same stored bytes served through the proxy wire
+ *    (`HttpCheckpointSaver`) load into the same checkpoint tuple the sqlite
+ *    saver loads — the graph resumes from the tuple, so the sqlite resume above
+ *    carries over to cloud sessions.
+ *
+ * Recording a fixture (only on the engine that is about to be left behind,
+ * before its upgrade lands):
+ *   RECORD_ENGINE_UPGRADE_FIXTURE=1 npx vitest run src/activities/execute-deep-agent/__tests__/hermetic/resume-across-engine-upgrade.test.ts
+ * The recording arm names the file after the installed deepagents version and
+ * refuses to overwrite one that exists.
+ *
+ * Resume is one-way: `@langchain/langgraph` 1.4.9 and later write Topic
+ * channels (`__pregel_tasks` among them) as a flat list that 1.3.x reads as
+ * `[seen, values]`, so a checkpoint written by this engine does not resume on
+ * the 1.3 line. Nothing here pretends otherwise.
+ */
+
+import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { DatabaseSync } from "node:sqlite";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { fromJson, toJson, type JsonValue } from "@bufbuild/protobuf";
+import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import {
+  ApprovalAction,
+  ExecutionPhase,
+  TodoStatus,
+  ToolCallStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+vi.mock("../../../../shared/model-client.js", async () =>
+  (await import("../../__test-utils__/scripted-model-module.js")).scriptedModelClientModule(),
+);
+vi.mock("../../../../client/stigmer-client.js", async () =>
+  (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
+);
+
+import {
+  ScriptedClock,
+  createHermeticEnvironment,
+  type HermeticEnvironment,
+} from "../../../../__test-utils__/hermetic-activity.js";
+import { stubRegistryFetch } from "../../../../__test-utils__/model-registry-fixture.js";
+import { getCheckpointDbPath } from "../../../../shared/workspace/platform-dir.js";
+import { SqliteCheckpointSaver } from "../../../../shared/checkpointer/sqlite-saver.js";
+import { HttpCheckpointSaver } from "../../../../shared/checkpointer/http-saver.js";
+import {
+  FIXTURE,
+  beginDeepAgentScenario,
+  deepAgentExecutionRecord,
+  runDeepAgentTurn,
+} from "../../__test-utils__/hermetic-deep-agent.js";
+import type { ScriptedTurn } from "../../__test-utils__/scripted-model.js";
+import { CLOSING_TURN, EXECUTE_CALL_A, GATED_OPENING_TURN } from "../../__test-utils__/hitl-script.js";
+
+const USER_MESSAGE = "Plan it, then run the command for me.";
+const DECIDED_AT = "2026-01-01T00:00:30.000Z";
+const RESUME_AFTER_MS = 60_000;
+const FIXTURE_DIR = join(dirname(fileURLToPath(import.meta.url)), "fixtures");
+const FIXTURE_PREFIX = "paused-session.deepagents-";
+const RECORDING = process.env.RECORD_ENGINE_UPGRADE_FIXTURE === "1";
+
+const TODOS = [
+  { content: "Run the command", status: "in_progress" },
+  { content: "Report the result", status: "pending" },
+];
+
+/** Round 0: the to-do list, so the fixture carries the `todos` channel an engine writes. */
+const TODO_TURN: ScriptedTurn = {
+  text: "Planning the two steps.",
+  toolCalls: [{ id: "call-hermetic-todo-0001", name: "write_todos", args: { todos: TODOS } }],
+  usage: { inputTokens: 1_200, outputTokens: 40 },
+};
+
+const SCRIPT = () => ({ turns: [TODO_TURN, GATED_OPENING_TURN, CLOSING_TURN] });
+
+/** A blob as the fixture stores it: readable when the serializer wrote JSON. */
+interface StoredBlob {
+  readonly encoding: "utf8" | "base64";
+  readonly data: string;
+}
+
+interface CheckpointRow {
+  readonly thread_id: string;
+  readonly checkpoint_ns: string;
+  readonly checkpoint_id: string;
+  readonly parent_checkpoint_id: string | null;
+  readonly type: string | null;
+  readonly checkpoint: StoredBlob;
+  readonly metadata: StoredBlob;
+}
+
+interface WriteRow {
+  readonly thread_id: string;
+  readonly checkpoint_ns: string;
+  readonly checkpoint_id: string;
+  readonly task_id: string;
+  readonly idx: number;
+  readonly channel: string;
+  readonly type: string | null;
+  readonly value: StoredBlob;
+}
+
+interface PausedSessionFixture {
+  /** The engine that wrote the rows. */
+  readonly recordedWith: Readonly<Record<string, string>>;
+  readonly threadId: string;
+  readonly checkpoints: readonly CheckpointRow[];
+  readonly writes: readonly WriteRow[];
+  /** The status the server held when the paused turn returned (`toJson` form). */
+  readonly status: JsonValue;
+}
+
+function installedVersion(pkg: string): string {
+  const require = createRequire(import.meta.url);
+  let dir = dirname(require.resolve(pkg));
+  while (!existsSync(join(dir, "package.json")) || readPackageName(dir) !== pkg) {
+    const parent = dirname(dir);
+    if (parent === dir) throw new Error(`no package.json found for ${pkg}`);
+    dir = parent;
+  }
+  return (JSON.parse(readFileSync(join(dir, "package.json"), "utf8")) as { version: string }).version;
+}
+
+function readPackageName(dir: string): string | undefined {
+  return (JSON.parse(readFileSync(join(dir, "package.json"), "utf8")) as { name?: string }).name;
+}
+
+function storeBlob(type: string | null, bytes: Uint8Array): StoredBlob {
+  return type === "json"
+    ? { encoding: "utf8", data: Buffer.from(bytes).toString("utf8") }
+    : { encoding: "base64", data: Buffer.from(bytes).toString("base64") };
+}
+
+function loadBlob(blob: StoredBlob): Uint8Array {
+  return new Uint8Array(Buffer.from(blob.data, blob.encoding));
+}
+
+function readRows(dbPath: string): Pick<PausedSessionFixture, "checkpoints" | "writes"> {
+  const db = new DatabaseSync(dbPath, { readOnly: true });
+  try {
+    const checkpoints = (
+      db
+        .prepare(
+          `SELECT thread_id, checkpoint_ns, checkpoint_id, parent_checkpoint_id, type, checkpoint, metadata
+           FROM checkpoints ORDER BY checkpoint_ns, checkpoint_id`,
+        )
+        .all() as unknown as Array<Omit<CheckpointRow, "checkpoint" | "metadata"> & { checkpoint: Uint8Array; metadata: Uint8Array }>
+    ).map((r) => ({ ...r, checkpoint: storeBlob(r.type, r.checkpoint), metadata: storeBlob(r.type, r.metadata) }));
+    const writes = (
+      db
+        .prepare(
+          `SELECT thread_id, checkpoint_ns, checkpoint_id, task_id, idx, channel, type, value
+           FROM writes ORDER BY checkpoint_ns, checkpoint_id, task_id, idx`,
+        )
+        .all() as unknown as Array<Omit<WriteRow, "value"> & { value: Uint8Array }>
+    ).map((r) => ({ ...r, value: storeBlob(r.type, r.value) }));
+    return { checkpoints, writes };
+  } finally {
+    db.close();
+  }
+}
+
+/** Write a fixture's rows into a checkpoint file whose schema the saver itself created. */
+async function loadRows(dbPath: string, fixture: PausedSessionFixture): Promise<void> {
+  mkdirSync(dirname(dbPath), { recursive: true });
+  const saver = new SqliteCheckpointSaver(dbPath);
+  expect(await saver.getTuple({ configurable: { thread_id: fixture.threadId } }), "a fresh file").toBeUndefined();
+  const db = new DatabaseSync(dbPath);
+  try {
+    const cp = db.prepare(
+      `INSERT INTO checkpoints (thread_id, checkpoint_ns, checkpoint_id, parent_checkpoint_id, type, checkpoint, metadata)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+    );
+    for (const r of fixture.checkpoints) {
+      cp.run(r.thread_id, r.checkpoint_ns, r.checkpoint_id, r.parent_checkpoint_id, r.type, loadBlob(r.checkpoint), loadBlob(r.metadata));
+    }
+    const w = db.prepare(
+      `INSERT INTO writes (thread_id, checkpoint_ns, checkpoint_id, task_id, idx, channel, type, value)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+    );
+    for (const r of fixture.writes) {
+      w.run(r.thread_id, r.checkpoint_ns, r.checkpoint_id, r.task_id, r.idx, r.channel, r.type, loadBlob(r.value));
+    }
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * The proxy's checkpoint API over a fixture's rows, as `fetch` sees it: the
+ * documents the server stores and returns (`$binary` Extended JSON), keyed as
+ * the saver queries them.
+ */
+function proxyFetch(fixture: PausedSessionFixture): typeof fetch {
+  const binary = (blob: StoredBlob) => ({
+    $binary: { base64: Buffer.from(loadBlob(blob)).toString("base64"), subType: "00" },
+  });
+  const checkpointDoc = (r: CheckpointRow) => ({
+    thread_id: r.thread_id,
+    checkpoint_ns: r.checkpoint_ns,
+    checkpoint_id: r.checkpoint_id,
+    parent_checkpoint_id: r.parent_checkpoint_id,
+    type: r.type,
+    checkpoint: binary(r.checkpoint),
+    metadata_type: r.type,
+    metadata: binary(r.metadata),
+  });
+  const json = (body: unknown) => new Response(JSON.stringify(body), { status: 200 });
+  return (async (input: string | URL | Request) => {
+    const url = new URL(typeof input === "string" ? input : input instanceof URL ? input.href : input.url);
+    const ns = url.searchParams.get("checkpoint_ns") ?? "";
+    const rows = fixture.checkpoints.filter((r) => r.thread_id === url.searchParams.get("thread_id") && r.checkpoint_ns === ns);
+    if (url.pathname.endsWith("/checkpoint")) {
+      const id = url.searchParams.get("checkpoint_id");
+      const row = id ? rows.find((r) => r.checkpoint_id === id) : [...rows].sort((a, b) => b.checkpoint_id.localeCompare(a.checkpoint_id))[0];
+      return row ? json(checkpointDoc(row)) : new Response("", { status: 404 });
+    }
+    if (url.pathname.endsWith("/writes")) {
+      const id = url.searchParams.get("checkpoint_id");
+      const writes = fixture.writes
+        .filter((w) => w.thread_id === url.searchParams.get("thread_id") && w.checkpoint_ns === ns && w.checkpoint_id === id)
+        .map((w) => ({ ...w, value: binary(w.value) }));
+      return json({ writes });
+    }
+    throw new Error(`the fixture proxy serves no ${url.pathname}`);
+  }) as typeof fetch;
+}
+
+function committedFixtures(): string[] {
+  if (!existsSync(FIXTURE_DIR)) return [];
+  return readdirSync(FIXTURE_DIR)
+    .filter((f) => f.startsWith(FIXTURE_PREFIX) && f.endsWith(".json"))
+    .sort();
+}
+
+describe("ExecuteDeepAgent hermetic — a paused session resumes across an engine upgrade", () => {
+  let env: HermeticEnvironment;
+  let registry: ReturnType<typeof stubRegistryFetch>;
+  const clock = new ScriptedClock();
+
+  beforeAll(() => {
+    env = createHermeticEnvironment();
+    registry = stubRegistryFetch();
+    clock.install();
+  });
+
+  afterAll(() => {
+    clock.uninstall();
+    registry.restore();
+    env.dispose();
+  });
+
+  it.runIf(RECORDING)("records the paused session on the installed engine", async () => {
+    const version = installedVersion("deepagents");
+    const target = join(FIXTURE_DIR, `${FIXTURE_PREFIX}${version}.json`);
+    expect(existsSync(target), `${target} is frozen; a fixture is recorded once, on the engine it names`).toBe(false);
+
+    clock.reset();
+    const record = deepAgentExecutionRecord({ message: USER_MESSAGE });
+    const scenario = beginDeepAgentScenario({ env, clock, record, checkpointer: "sqlite", script: SCRIPT });
+    const turn = await runDeepAgentTurn(scenario, { turnSeq: 0 });
+    expect(turn.outcome.kind).toBe("returned");
+    expect(record.lastFullStatus?.phase).toBe(ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL);
+    expect(record.lastFullStatus?.todos).not.toEqual({});
+
+    const fixture: PausedSessionFixture = {
+      recordedWith: {
+        deepagents: version,
+        "@langchain/langgraph": installedVersion("@langchain/langgraph"),
+        "@langchain/langgraph-checkpoint": installedVersion("@langchain/langgraph-checkpoint"),
+        "@langchain/core": installedVersion("@langchain/core"),
+      },
+      threadId: FIXTURE.threadId,
+      ...readRows(getCheckpointDbPath(FIXTURE.sessionId)),
+      status: toJson(AgentExecutionStatusSchema, record.lastFullStatus!),
+    };
+    mkdirSync(FIXTURE_DIR, { recursive: true });
+    writeFileSync(target, JSON.stringify(fixture, null, 2) + "\n");
+  });
+
+  describe.skipIf(RECORDING).each(committedFixtures())("%s", (file) => {
+    const fixture = JSON.parse(readFileSync(join(FIXTURE_DIR, file), "utf8")) as PausedSessionFixture;
+
+    it("resumes inside the gate on sqlite: the command runs once, the old to-do list survives", async () => {
+      // ── Arrange: the old engine's rows and the status the server held ─────
+      clock.reset();
+      const record = deepAgentExecutionRecord({ message: USER_MESSAGE });
+      const scenario = beginDeepAgentScenario({ env, clock, record, checkpointer: "sqlite", script: SCRIPT });
+      await loadRows(getCheckpointDbPath(FIXTURE.sessionId), fixture);
+      record.applyStatusUpdate(fromJson(AgentExecutionStatusSchema, fixture.status));
+      // The approval arrives after the pause, as it does live. Checkpoint ids
+      // are time-ordered, and the recorded turn ran on this same scripted
+      // clock from its epoch, so the resumed turn starts a minute on: its new
+      // checkpoints must sort after the paused one they continue.
+      clock.tick(RESUME_AFTER_MS);
+      expect(record.waitingToolCalls().map((tc) => tc.id)).toEqual([EXECUTE_CALL_A.id]);
+
+      // ── Between turns: what SubmitApproval does to the row ─────────────────
+      expect(record.decideWaitingToolCalls(ApprovalAction.APPROVE, DECIDED_AT)).toBe(1);
+
+      // ── Act: the reinvocation on THIS engine ───────────────────────────────
+      const turn = await runDeepAgentTurn(scenario, { turnSeq: 1 });
+
+      // ── Assert ─────────────────────────────────────────────────────────────
+      expect(turn.outcome.kind).toBe("returned");
+      expect((turn.outcome as { value: Record<string, unknown> }).value.phase).toBe("EXECUTION_COMPLETED");
+      const final = record.lastFullStatus!;
+      const rows = final.messages.flatMap((m) => m.toolCalls).filter((tc) => tc.id === EXECUTE_CALL_A.id);
+      expect(rows, "exactly one copy of the gated call — a resume, not a replay").toHaveLength(1);
+      expect(rows[0].status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+      expect(rows[0].result, "the command ran on this engine").toContain("hermetic-a");
+      expect(
+        Object.values(final.todos).map((t) => [t.content, t.status]),
+        "the to-do list the old engine wrote",
+      ).toEqual([
+        ["Run the command", TodoStatus.TODO_IN_PROGRESS],
+        ["Report the result", TodoStatus.TODO_PENDING],
+      ]);
+      expect(final.messages.at(-1)?.content).toBe(CLOSING_TURN.text);
+      expect(registry.urls.every((u) => u.includes("/model-registry"))).toBe(true);
+    });
+
+    it("loads the same stored bytes into the same tuple through the proxy wire", async () => {
+      const dbPath = join(env.home, "resume-across-engine-upgrade", file.replace(/\.json$/, ".db"));
+      await loadRows(dbPath, fixture);
+      const config = { configurable: { thread_id: fixture.threadId, checkpoint_ns: "" } };
+      const fromSqlite = await new SqliteCheckpointSaver(dbPath).getTuple(config);
+
+      const realFetch = globalThis.fetch;
+      globalThis.fetch = proxyFetch(fixture);
+      try {
+        const fromProxy = await new HttpCheckpointSaver("http://proxy.invalid", { current: "t" }, { maxRetries: 0 }).getTuple(config);
+        expect(fromSqlite, "the sqlite saver loads the old rows").toBeDefined();
+        expect(fromProxy?.checkpoint).toEqual(fromSqlite?.checkpoint);
+        expect(fromProxy?.metadata).toEqual(fromSqlite?.metadata);
+        expect(fromProxy?.parentConfig).toEqual(fromSqlite?.parentConfig);
+        expect(fromProxy?.pendingWrites).toEqual(fromSqlite?.pendingWrites);
+        expect(fromSqlite?.pendingWrites?.length, "the paused turn left its interrupt as a pending write").toBeGreaterThan(0);
+      } finally {
+        globalThis.fetch = realFetch;
+      }
+    });
+  });
+});

package/src/activities/execute-deep-agent/__tests__/hermetic/sub-agent-delegation.test.ts

@@ -47,6 +47,13 @@
  * the blocks array the image offload reads — where they were the whole
  * serialized Command. Those two lines are the whole of that hunk.
  *
+ * Since deepagents 1.14 (2026-09-28): the `task` tool returns the
+ * sub-agent's last non-empty text as a plain string, so the same two lines
+ * read `"The fixture value is forty-two."` instead of the blocks array. The
+ * status offload is size-driven and treats either form the same; an image
+ * could only ever have ridden a `task` result inside the sub-agent's final
+ * AI message. Those two lines are the whole of that hunk.
+ *
  * Also since #1097: the `task` row sits on the AI message whose text
  * delegated ("Delegating to the helper."), not on an empty AI message of its
  * own after it — two root AI messages (the delegating text with the row, the

package/src/activities/execute-deep-agent/__tests__/hermetic/tool-call.test.ts

@@ -33,6 +33,12 @@
  * thinking mode (one writer of the summary, the runtime). Nothing
  * else in this golden moved with the flip.
  *
+ * Since deepagents 1.12 (landed with 1.14, 2026-09-28): `read_file`
+ * returns the file's lines unnumbered under a status header,
+ * `@@ lines 1-3 of 3 @@`, where it returned `cat -n` numbered lines. The
+ * row's `result` is that one line of the golden; the clients' read view
+ * drops the header (`sdk/typescript/src/execution/tool-view.ts`).
+ *
  * Regenerate ONLY after a deliberate behavior change:
  *   npx vitest run src/activities/execute-deep-agent/__tests__/hermetic -u
  */

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

@@ -11,8 +11,10 @@
  * relative paths to VIRTUAL-absolute at our seam, before enforcement sees
  * them. The read boundary #528 built out of rules is structural since #754:
  * the backend is virtual-rooted, so every expressible path resolves inside
- * the workspace — an out-of-root name is simply nonexistent, and the
- * `.stigmer` symlink keeps platform-dir reads addressable in-root.
+ * the workspace — an out-of-root name is simply nonexistent. Platform-dir
+ * reads stay addressable in-root at `.stigmer/…`: the virtual-rooted backend
+ * refuses to follow the workspace link out of the root, so the platform dir is
+ * mounted read-only at that prefix (`platform-route.ts`).
  *
  * The graph here is composed exactly the way turn-setup.ts composes the parent:
  * the PRODUCTION buildMiddlewareStack (pathNormalization present on every
@@ -36,30 +38,36 @@ import { createDeepAgent } from "deepagents";
 import { buildPlanModePermissions } from "../../../shared/plan-mode-permissions.js";
 import { buildMiddlewareStack } from "../../../middleware/index.js";
 import { createCasCaptureBackend } from "../cas-capture-backend.js";
+import { mountPlatformRoute } from "../platform-route.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";
 const OUTSIDE_CONTENT = "OUT_OF_ROOT_SECRET_TOKEN: must never cross the boundary";
-const PLATFORM_CONTENT = "PLATFORM_SKILL_TOKEN: reached through the .stigmer symlink";
+const PLATFORM_CONTENT = "PLATFORM_SKILL_TOKEN: reached through the .stigmer route";
 
 /**
  * Build a plan-mode parent graph the way turn-setup.ts does: 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 the production
- * buildPlanModePermissions rules on the graph.
+ * backend (no shellEnv — plan mode clears it) with the read-only platform
+ * route mounted when the workspace link points at `platformDir`, and the
+ * production buildPlanModePermissions rules on the graph.
  */
 async function buildPlanModeParent(
   root: string,
   observer: CasCaptureObserver,
   script: ScriptSelector,
+  platformDir?: string,
 ) {
   const { middleware } = buildMiddlewareStack({
     approvalGate: null,
     pathNormalization: { rootDir: root },
   });
-  const backend = await createCasCaptureBackend({ rootDir: root, observer });
+  const backend = await mountPlatformRoute(await createCasCaptureBackend({ rootDir: root, observer }), {
+    workspaceDir: root,
+    platformDir,
+  });
   return createDeepAgent({
     model: new ScriptedModel(script),
     checkpointer: new MemorySaver() as never,
@@ -215,7 +223,7 @@ describe("plan-mode workspace read boundary (issue #528)", () => {
   });
 
   async function invokeOnce(script: ScriptSelector, threadId: string) {
-    const agent = await buildPlanModeParent(root, observer, script);
+    const agent = await buildPlanModeParent(root, observer, script, platform);
     return (await agent.invoke(
       { messages: [new HumanMessage({ content: "go" })] },
       { configurable: { thread_id: threadId }, recursionLimit: 50 },
@@ -256,7 +264,7 @@ describe("plan-mode workspace read boundary (issue #528)", () => {
     expect(lsResult).not.toMatch(/permission denied/i);
   });
 
-  it("reads platform-dir material through the .stigmer symlink — in-root strings, out-of-root bytes", async () => {
+  it("reads platform-dir material at .stigmer — in-root strings, out-of-root bytes", async () => {
     const result = await invokeOnce(
       () => ({
         toolCalls: [