@stigmer/runner 3.15.3-dev.20260914121148 → 3.16.0

package/src/harness/__tests__/readme-index.test.ts

@@ -0,0 +1,339 @@
+/**
+ * Pins that `src/harness/README.md` resolves: every path it names exists and
+ * every symbol it names occurs in a file the same passage cites.
+ *
+ * Why it matters: the README is an index for someone adding a harness, not a
+ * restatement of the headers. An index earns its keep only while its entries
+ * point somewhere. A module renamed, a test moved, an export renamed — each
+ * turns a line of the guide into a false trail, and nothing in CI reads a
+ * `src/**` README (the docs link checker walks `docs/` only). This fence is
+ * the guide's one mechanical check; it is what lets the README carry file
+ * paths and export names at all.
+ *
+ * Two rules, both about resolution, neither about prose:
+ *
+ *  1. A backticked token that reads as a path (ends in a `/`, or is a file
+ *     name with an extension, with or without a directory part) exists,
+ *     resolved against `src/` (the base the runner's own headers cite each
+ *     other from) or against the repository root (the base for everything
+ *     outside the runner).
+ *  2. A backticked identifier occurs in the text of at least one FILE the
+ *     same passage resolved under rule 1. A passage that names a symbol and
+ *     cites no file is an offence: the index rule ("say where it lives") made
+ *     mechanical. Hyphenated literals (`deep-agent`, `deny-and-retry`) count
+ *     as identifiers so the wire words are checked too.
+ *
+ * A "passage" is a markdown block — one paragraph, one list item with its
+ * wrapped continuation lines, or one table row — because the repository's
+ * prettier wraps prose at 80 columns, so a line is not a unit of meaning.
+ * Fenced code blocks are blanked before the scan (they hold shell commands
+ * and search patterns, not references). Two token classes are exempt with
+ * a reason: a template (`activities/<harness>/adapter.ts`, contains `<`)
+ * names a shape, not a file; a package specifier (`@cursor/sdk`, starts
+ * with `@`) is resolved by npm, not by this tree.
+ *
+ * Hand-rolled over three regular expressions rather than a markdown parser:
+ * the README has three shapes and the runner has no markdown dependency.
+ * The fence shape is `import-direction.test.ts`'s: a sweep that reports what
+ * it visited beside what it found, a liveness guard that fails when the
+ * sweep saw nothing, and every offence named with its block's first line.
+ * What it never asserts: wording, section order, or that a header agrees
+ * with the README — the header wins that by rule, not by test.
+ */
+
+import { describe, it, expect } from "vitest";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const README_PATH = join(HERE, "..", "README.md");
+/** `src/`: the base the runner's headers cite each other from. */
+const SRC_ROOT = resolve(HERE, "../..");
+/** The repository root: `src/` → `runner/` → `services/` → `backend/` → root. */
+const REPO_ROOT = resolve(SRC_ROOT, "../../../..");
+
+// ── The scanner ──────────────────────────────────────────────────────────────
+
+/** One passage of the README: a paragraph, a list item with its continuation, or a table row. */
+interface Block {
+  /** 1-based line of the block's first line in the README, for the offence message. */
+  readonly line: number;
+  readonly text: string;
+}
+
+/**
+ * Blank every fenced code block, keeping the line count so block line
+ * numbers still point into the real file.
+ */
+function stripFencedCode(markdown: string): string {
+  let inFence = false;
+  return markdown
+    .split("\n")
+    .map((line) => {
+      if (line.trimStart().startsWith("```")) {
+        inFence = !inFence;
+        return "";
+      }
+      return inFence ? "" : line;
+    })
+    .join("\n");
+}
+
+const BLOCK_START = /^(#{1,6}\s|[-*]\s|\d+\.\s|\|)/;
+
+/**
+ * Split markdown into blocks. A blank line ends a block; a heading, a list
+ * marker or a table row starts one; any other non-blank line continues the
+ * current block (prettier indents a list item's wrapped lines, and a
+ * paragraph's lines are simply consecutive).
+ */
+function splitBlocks(markdown: string): Block[] {
+  const blocks: Block[] = [];
+  let current: { line: number; parts: string[] } | undefined;
+  const flush = (): void => {
+    if (current !== undefined) {
+      blocks.push({ line: current.line, text: current.parts.join(" ") });
+      current = undefined;
+    }
+  };
+  markdown.split("\n").forEach((raw, index) => {
+    const line = raw.trim();
+    if (line === "") {
+      flush();
+      return;
+    }
+    if (BLOCK_START.test(line) || current === undefined) {
+      flush();
+      current = { line: index + 1, parts: [line] };
+      return;
+    }
+    current.parts.push(line);
+  });
+  flush();
+  return blocks;
+}
+
+/** Every backticked token in a block, in order, backticks removed. */
+function backtickedTokens(text: string): string[] {
+  return [...text.matchAll(/`([^`\n]+)`/g)].map((m) => m[1] ?? "");
+}
+
+type TokenClass = "template" | "package" | "path" | "identifier" | "other";
+
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$-]{3,}$/;
+/** A directory (`activities/execute-cursor/`) or a file with an extension, with or without a directory part (`harness-adapters.ts` sits at the `src/` root). */
+const DIRECTORY = /\/$/;
+const FILE_WITH_EXTENSION = /^[^.\s][^\s]*\.[A-Za-z0-9]{1,5}$/;
+
+/** Which rule a token falls under; `other` is prose in backticks and is ignored. */
+function classify(token: string): TokenClass {
+  if (token.includes("<")) return "template";
+  if (token.startsWith("@")) return "package";
+  if (DIRECTORY.test(token) || FILE_WITH_EXTENSION.test(token)) return "path";
+  if (IDENTIFIER.test(token)) return "identifier";
+  return "other";
+}
+
+/** The first base under which `token` exists, or `undefined`. */
+function resolvePath(token: string, bases: readonly string[]): string | undefined {
+  for (const base of bases) {
+    const candidate = join(base, token);
+    if (existsSync(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+interface Offence {
+  readonly line: number;
+  readonly token: string;
+  readonly rule: "path" | "symbol" | "no-file-cited";
+}
+
+interface Sweep {
+  /** What the sweep saw; the liveness guards read these. */
+  readonly blocks: number;
+  readonly paths: number;
+  readonly identifiers: number;
+  readonly offences: Offence[];
+}
+
+/** Run both rules over `markdown`, resolving paths against `bases` in order. */
+function sweep(markdown: string, bases: readonly string[]): Sweep {
+  const offences: Offence[] = [];
+  let paths = 0;
+  let identifiers = 0;
+  const blocks = splitBlocks(stripFencedCode(markdown));
+  for (const block of blocks) {
+    const files: string[] = [];
+    const symbols: string[] = [];
+    for (const token of backtickedTokens(block.text)) {
+      const kind = classify(token);
+      switch (kind) {
+        case "path": {
+          paths += 1;
+          const resolved = resolvePath(token, bases);
+          if (resolved === undefined) {
+            offences.push({ line: block.line, token, rule: "path" });
+          } else if (statSync(resolved).isFile()) {
+            files.push(resolved);
+          }
+          break;
+        }
+        case "identifier":
+          identifiers += 1;
+          symbols.push(token);
+          break;
+        case "template":
+        case "package":
+        case "other":
+          break;
+        default: {
+          const exhaustive: never = kind;
+          throw new Error(`unhandled token class ${String(exhaustive)}`);
+        }
+      }
+    }
+    if (symbols.length === 0) continue;
+    if (files.length === 0) {
+      for (const token of symbols) offences.push({ line: block.line, token, rule: "no-file-cited" });
+      continue;
+    }
+    const corpus = files.map((f) => readFileSync(f, "utf-8"));
+    for (const token of symbols) {
+      if (!corpus.some((text) => text.includes(token))) {
+        offences.push({ line: block.line, token, rule: "symbol" });
+      }
+    }
+  }
+  return { blocks: blocks.length, paths, identifiers, offences };
+}
+
+function describeOffences(offences: readonly Offence[]): string {
+  const words: Record<Offence["rule"], string> = {
+    path: "does not exist under src/ or the repository root",
+    symbol: "does not occur in any file this passage cites",
+    "no-file-cited": "is named in a passage that cites no file",
+  };
+  return offences.map((o) => `  README.md:${o.line}  \`${o.token}\` ${words[o.rule]}`).join("\n");
+}
+
+// ── The checker itself ───────────────────────────────────────────────────────
+
+describe("the scanner (the checker itself)", () => {
+  it("blanks fenced code and keeps the line count", () => {
+    const text = ["before", "```bash", "rg -l 'x/y.ts'", "```", "after"].join("\n");
+    const stripped = stripFencedCode(text);
+    expect(stripped.split("\n")).toHaveLength(5);
+    expect(stripped).not.toContain("x/y.ts");
+    expect(stripped).toContain("after");
+  });
+
+  it("splits paragraphs, wrapped list items, table rows and headings into blocks with their first line", () => {
+    const text = [
+      "# Title",
+      "",
+      "A paragraph that",
+      "wraps onto two lines.",
+      "",
+      "- `a/b.ts` — a bullet whose",
+      "  continuation is indented.",
+      "- a second bullet",
+      "",
+      "| `c/d.ts` | row one |",
+      "| `e/f.ts` | row two |",
+    ].join("\n");
+    expect(splitBlocks(text)).toEqual([
+      { line: 1, text: "# Title" },
+      { line: 3, text: "A paragraph that wraps onto two lines." },
+      { line: 6, text: "- `a/b.ts` — a bullet whose continuation is indented." },
+      { line: 8, text: "- a second bullet" },
+      { line: 10, text: "| `c/d.ts` | row one |" },
+      { line: 11, text: "| `e/f.ts` | row two |" },
+    ]);
+  });
+
+  it.each<[string, TokenClass]>([
+    ["harness/types.ts", "path"],
+    ["harness-adapters.ts", "path"],
+    ["activities/execute-cursor/", "path"],
+    ["apis/", "path"],
+    ["apis/ai/stigmer/agentic/session/v1/enum.proto", "path"],
+    ["activities/<harness>/adapter.ts", "template"],
+    ["@cursor/sdk", "package"],
+    ["@temporalio/*", "package"],
+    ["HarnessAdapter", "identifier"],
+    ["deep-agent", "identifier"],
+    ["deny-and-retry", "identifier"],
+    ["boot", "identifier"],
+    ["src", "other"],
+    ["make codegen", "other"],
+    ["--harness", "other"],
+    [".ts", "other"],
+    ["f25d15131", "identifier"],
+  ])("classifies %s as %s", (token, expected) => {
+    expect(classify(token)).toBe(expected);
+  });
+
+  it("resolves a path against the bases in order and reports a miss", () => {
+    expect(resolvePath("harness/types.ts", [SRC_ROOT, REPO_ROOT])).toBe(join(SRC_ROOT, "harness/types.ts"));
+    expect(resolvePath("apis/", [SRC_ROOT, REPO_ROOT])).toBe(join(REPO_ROOT, "apis/"));
+    expect(resolvePath("harness/no-such-module.ts", [SRC_ROOT, REPO_ROOT])).toBeUndefined();
+  });
+
+  it("flags a missing path, a symbol absent from the cited file, and a symbol with no file cited", () => {
+    const text = [
+      "- `harness/no-such-module.ts` — a moved module.",
+      "- `harness/registry.ts` — `NoSuchExport` was renamed.",
+      "- `HarnessName` is named here with no file beside it.",
+      "- `harness/registry.ts` — `HarnessName` is fine.",
+    ].join("\n");
+    expect(sweep(text, [SRC_ROOT, REPO_ROOT]).offences).toEqual([
+      { line: 1, token: "harness/no-such-module.ts", rule: "path" },
+      { line: 2, token: "NoSuchExport", rule: "symbol" },
+      { line: 3, token: "HarnessName", rule: "no-file-cited" },
+    ]);
+  });
+
+  it("ignores templates, package specifiers, prose in backticks and anything inside a code fence", () => {
+    const text = [
+      "- `activities/<harness>/adapter.ts` loads `@cursor/sdk` inside `boot`; see `harness/types.ts`.",
+      "",
+      "```bash",
+      "rg -l 'x/y.ts' `NoSuchExport`",
+      "```",
+    ].join("\n");
+    const result = sweep(text, [SRC_ROOT, REPO_ROOT]);
+    expect(result.offences).toEqual([]);
+    expect(result.paths).toBe(1);
+    expect(result.identifiers).toBe(1);
+  });
+});
+
+// ── The README ───────────────────────────────────────────────────────────────
+
+describe("src/harness/README.md resolves", () => {
+  const readme = readFileSync(README_PATH, "utf-8");
+  const result = sweep(readme, [SRC_ROOT, REPO_ROOT]);
+
+  it("is rooted where it claims (the repository root holds apis/ and backend/)", () => {
+    expect(existsSync(join(REPO_ROOT, "apis")), `expected ${REPO_ROOT} to contain apis/`).toBe(true);
+    expect(existsSync(join(REPO_ROOT, "backend")), `expected ${REPO_ROOT} to contain backend/`).toBe(true);
+  });
+
+  it("saw the guide (the sweep visited blocks, paths and identifiers)", () => {
+    expect(result.blocks).toBeGreaterThan(20);
+    expect(result.paths).toBeGreaterThan(40);
+    expect(result.identifiers).toBeGreaterThan(20);
+  });
+
+  it("names no path that does not exist", () => {
+    const misses = result.offences.filter((o) => o.rule === "path");
+    expect(misses, `paths in the README that resolve nowhere:\n${describeOffences(misses)}`).toEqual([]);
+  });
+
+  it("names no symbol outside a file the same passage cites", () => {
+    const misses = result.offences.filter((o) => o.rule !== "path");
+    expect(misses, `symbols in the README without a home:\n${describeOffences(misses)}`).toEqual([]);
+  });
+});

package/src/harness/__tests__/run-turn.test.ts

@@ -28,6 +28,7 @@
  * this file.
  */
 
+import { join } from "node:path";
 import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
 import { ApprovalAction, ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 
@@ -38,8 +39,9 @@ vi.mock("../../client/stigmer-client.js", async () =>
 import { ScriptedClock, createHermeticEnvironment } from "../../__test-utils__/hermetic-activity.js";
 import { stubRegistryFetch } from "../../__test-utils__/model-registry-fixture.js";
 import { scriptedSubject } from "../../__test-utils__/harness-contract/scripted-adapter.js";
-import { initGitWorkspace } from "../../__test-utils__/git-workspace-fixture.js";
+import { initGitWorkspace, localPathEntry } from "../../__test-utils__/git-workspace-fixture.js";
 import { scenario } from "../../__test-utils__/harness-contract/types.js";
+import { WriteBackCoordinator } from "../../shared/workspace/writeback-coordinator.js";
 import {
   COST_CAP_FAKE_PRICE_USD,
   FAILURE_MESSAGES,
@@ -58,6 +60,7 @@ import {
   type RuntimeContractHarness,
 } from "../../__test-utils__/harness-contract/runtime-contract.js";
 import { TERMINAL_COPY } from "../terminal-table.js";
+import type { HarnessAdapter } from "../types.js";
 
 const TASK_QUEUE = "runtime-test-queue";
 
@@ -101,7 +104,7 @@ describe("run-turn: the fake adapter through the real runtime", () => {
       expect(registry.urls.every((u) => u.includes("/model-registry"))).toBe(true);
     });
 
-    it("the approval round trip: the WAITING write is the fake's first full persist (M3a finding 3)", async () => {
+    it("the approval round trip: the WAITING write is the fake's first full persist", async () => {
       clock.reset();
       const { driver } = await assertApprovalRoundTrip(harness, "fake-approval");
       expect(driver.record.persistedPhases).toEqual([
@@ -138,11 +141,11 @@ describe("run-turn: the fake adapter through the real runtime", () => {
       expect(aiMessages(final)).toEqual([]);
     });
 
-    it("REJECT continues the run without the tool and the row settles SKIPPED with its reason (stigmer#197; S3 M1, Q-S3-2)", async () => {
-      // Until S3 M1 this arm pinned the opposite: the runtime FAILED a
+    it("REJECT continues the run without the tool and the row settles SKIPPED with its reason (stigmer#197)", async () => {
+      // Until #1096 this arm pinned the opposite: the runtime FAILED a
       // reinvocation carrying any REJECT (`rejectedByUserArm`, Cursor's
       // legacy), against the proto's `APPROVAL_ACTION_REJECT` doc, the
-      // conformance suite and the native harness (S2 M4 finding F1, Q-M4-1).
+      // conformance suite and the native harness.
       // The kit's runtime half now carries the contract for every subject;
       // what is the fake's own here is the persist cadence around it.
       clock.reset();
@@ -156,7 +159,7 @@ describe("run-turn: the fake adapter through the real runtime", () => {
       expect(systemMessages(final), "no terminal copy: the run ended normally").toEqual([]);
     });
 
-    it("structured output on a file-review-pending turn is resolved before the pause and rides the reconcile's completion (Q-M4-8)", async () => {
+    it("structured output on a file-review-pending turn is resolved before the pause and rides the reconcile's completion", async () => {
       clock.reset();
       const driver = new RuntimeExecutionDriver(harness, "fake-review-structured", {
         structuredOutputSchema: { type: "object", properties: { answer: { type: "number" } }, required: ["answer"] },
@@ -178,4 +181,126 @@ describe("run-turn: the fake adapter through the real runtime", () => {
       expect(slim.final_text).toBe('{"answer": 42}');
     });
   });
+
+  describe("the runtime's own transcript rules", () => {
+    it("finalizes the transcript once runTurn returns: an adapter that leaves its last message streaming still persists a settled one", async () => {
+      // A harness that streams text and returns without closing the run —
+      // the shape of a turn that fails or is cut off before its own settle
+      // (native's thrown recursion limit; either harness's internal failure
+      // before its settle ran). Before the runtime owned the close, that
+      // message persisted `isStreaming: true` in a terminal execution: a
+      // spinner the console never stopped, seen by the kit on both real
+      // adapters. The rule lives in `run-turn.ts`, so its proof lives here.
+      const streamsAndLeaves: HarnessAdapter = {
+        ...subject.adapter,
+        name: "streams-and-leaves",
+        boot: (config) => subject.adapter.boot(config),
+        shutdown: () => subject.adapter.shutdown(),
+        releaseSession: (sessionId) => subject.adapter.releaseSession(sessionId),
+        async runTurn(_input, sink) {
+          sink.transcript.apply({ kind: "message_start", runId: "r1" });
+          sink.transcript.apply({ kind: "text_delta", runId: "r1", text: "half a thou" });
+          sink.transcript.apply({ kind: "tool_started", callId: "t1", name: "shell", input: { command: "make" }, mcpServerSlug: "" });
+          sink.transcript.apply({ kind: "tool_output_delta", callId: "t1", delta: "building" });
+          return { kind: "completed" };
+        },
+      };
+      const leaving: RuntimeContractHarness = { ...harness, subject: { ...subject, name: streamsAndLeaves.name, adapter: streamsAndLeaves } };
+      await streamsAndLeaves.boot(subject.config);
+      clock.reset();
+      const driver = new RuntimeExecutionDriver(leaving, "fake-streams-and-leaves");
+      const invocation = await driver.turn([]);
+
+      expect(slimOf(leaving.subject, invocation).phase).toBe("EXECUTION_COMPLETED");
+      const final = driver.record.lastFullStatus!;
+      expect(final.messages.map((m) => [m.content, m.isStreaming]), "the message the adapter left open is closed").toEqual([["half a thou", false]]);
+      const row = final.messages[0]!.toolCalls[0]!;
+      expect([row.id, row.isStreaming, row.result], "the row the adapter left streaming output is closed, its output kept").toEqual(["t1", false, "building"]);
+    });
+  });
+
+  describe("the runtime's write-back rule", () => {
+    // `run-turn.ts` calls `frame.writeback.finalize()` in exactly two places:
+    // once when a completed turn reaches its epilogue, and once when a resumed
+    // file review reconciles cleanly — never when the reconcile failed, since
+    // diverged bytes must not reach a remote. These arms pin the CALL and its
+    // guards, not the coordinator's own behaviour (`writeback-coordinator.test.ts`
+    // does that): the session mounts a local path so a coordinator exists
+    // (`provisionWorkspace` builds one whenever the session has an entry; with
+    // no git remote it has nothing eligible and `finalize` is a no-op loop), and
+    // the spy sits on the prototype because the coordinator is constructed
+    // inside `provisionWorkspace` with no injection seam — adding one for a
+    // test would be a production change the arm does not need.
+    const finalize = vi.spyOn(WriteBackCoordinator.prototype, "finalize");
+
+    afterAll(() => {
+      finalize.mockRestore();
+    });
+
+    function driverWithLocalWorkspace(label: string): { driver: RuntimeExecutionDriver; repo: string } {
+      const repo = join(env.workspaceRootDir, "repos", label);
+      initGitWorkspace(repo, { "README.md": "# write-back\n" });
+      const driver = new RuntimeExecutionDriver(harness, label, { workspaceEntries: [localPathEntry("notes", repo)] });
+      return { driver, repo };
+    }
+
+    it("a completed turn finalizes the write-back exactly once", async () => {
+      clock.reset();
+      finalize.mockClear();
+      const { driver } = driverWithLocalWorkspace("fake-writeback-completed");
+
+      const invocation = await driver.turn([scenario.say("Nothing to change.")]);
+
+      expect(slimOf(subject, invocation).phase).toBe("EXECUTION_COMPLETED");
+      expect(finalize, "the completion epilogue's one call").toHaveBeenCalledTimes(1);
+    });
+
+    it("a resumed file review that reconciles cleanly finalizes exactly once, on the resume", async () => {
+      clock.reset();
+      finalize.mockClear();
+      const { driver } = driverWithLocalWorkspace("fake-writeback-review");
+
+      const first = await driver.turn([scenario.flowingWrite("fake-writeback-review-w", "answer.md"), scenario.say("Written.")]);
+      expect(slimOf(subject, first).phase).toBe("EXECUTION_WAITING_FOR_APPROVAL");
+      expect(finalize, "a turn paused for review has pushed nothing").toHaveBeenCalledTimes(0);
+
+      clock.tick();
+      driver.record.decideCapturedFileChanges({ approve: ["answer.md"] }, new Date().toISOString());
+      const second = await driver.turn([]);
+
+      expect(slimOf(subject, second).phase).toBe("EXECUTION_COMPLETED");
+      expect(finalize, "the resolved review's one call; the completion path does not run again").toHaveBeenCalledTimes(1);
+    });
+
+    it("a resumed file review whose reconcile fails never finalizes", async () => {
+      clock.reset();
+      finalize.mockClear();
+      const { driver } = driverWithLocalWorkspace("fake-writeback-diverged");
+
+      const first = await driver.turn([scenario.flowingWrite("fake-writeback-diverged-w", "answer.md"), scenario.say("Written.")]);
+      expect(slimOf(subject, first).phase).toBe("EXECUTION_WAITING_FOR_APPROVAL");
+
+      // What the reviewer approved must be what applies. On the git substrate
+      // the reconcile re-asserts the approved bytes from the pinned capture
+      // ref (a working-tree edit after the pause is simply overwritten), so
+      // the failure path is the ledger's digest disagreeing with the captured
+      // bytes — the same divergence `capture.test.ts` drives at unit level.
+      // The reconcile then refuses to apply anything, the review completes
+      // with the refusal on the transcript, the tree is left for diagnosis —
+      // and nothing may be pushed from it.
+      clock.tick();
+      driver.record.decideCapturedFileChanges({ approve: ["answer.md"] }, new Date().toISOString());
+      const decided = driver.record.status!.fileChangeSets.at(-1)!.changes.find((c) => c.pathAfter === "answer.md")!;
+      decided.afterSha256 = "deadbeef".repeat(8);
+      const second = await driver.turn([]);
+
+      expect(slimOf(subject, second).phase).toBe("EXECUTION_COMPLETED");
+      const final = driver.record.lastFullStatus!;
+      expect(
+        final.messages.some((m) => m.content.startsWith(TERMINAL_COPY.fileReview.applyFailedPrefix)),
+        "the reconcile reported its refusal",
+      ).toBe(true);
+      expect(finalize, "diverged bytes never reach a remote").toHaveBeenCalledTimes(0);
+    });
+  });
 });

package/src/harness/__tests__/transcript-is-engine-free.test.ts

@@ -0,0 +1,83 @@
+/**
+ * Pins that the transcript builder knows no engine: every file under
+ * `src/harness/transcript/`, tests included, names only the packages on a
+ * short allow-list — the proto runtime and the generated protos, Node's
+ * builtins, and `vitest` inside `__tests__/`.
+ *
+ * Why it matters (the canonical transcript's one disposition rule): the builder folds
+ * facts into the status proto; every fact about an engine — a LangGraph
+ * namespace, a Cursor `SDKMessage`, a LangChain `ToolMessage` envelope —
+ * reaches it as a translator's output, never as an import. A Claude or Codex
+ * adapter is then a translator and nothing else. `@temporalio/*` is refused
+ * for the same reason the adapters refuse it: the builder runs under the
+ * contract kit outside any activity, and it moved out from under the native
+ * adapter's Temporal-free fence when it moved into `harness/` (the runtime
+ * itself is not Temporal-free — `run-turn.ts` heartbeats).
+ *
+ * An ALLOW-list, not a deny-list: an SDK that does not exist yet is refused
+ * on the day this file was written, and admitting a new package is a visible
+ * edit here with a reason, not an absence someone forgot to extend. Tests are
+ * swept too, on the direction fence's precedent (`import-direction.test.ts`):
+ * a test that imported `@langchain/core` to build a fixture would be exactly
+ * the coupling that keeps the builder's own tests in the native adapter's
+ * folder until #1097 re-keyed them to the canonical union.
+ *
+ * Landed in #1097, the day the folder was created.
+ */
+
+import { describe, it, expect } from "vitest";
+import { join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { packageNames, readSource, typeScriptFilesUnder } from "../../__test-utils__/module-specifiers.js";
+
+const SRC_ROOT = fileURLToPath(new URL("../../", import.meta.url));
+const TRANSCRIPT_ROOT = join(SRC_ROOT, "harness", "transcript");
+
+/** What a production module under `harness/transcript/` may name. */
+const ALLOWED = new Set(["@bufbuild/protobuf", "@stigmer/protos"]);
+/** What a test under `harness/transcript/__tests__/` may name in addition. */
+const ALLOWED_IN_TESTS = new Set([...ALLOWED, "vitest"]);
+
+function isTestFile(file: string): boolean {
+  return file.includes(`${sep}__tests__${sep}`);
+}
+
+describe("packageNames (the checker itself)", () => {
+  const file = join(TRANSCRIPT_ROOT, "builder.ts");
+
+  it("reduces a specifier to its package and drops relatives and builtins", () => {
+    const source = [
+      'import { create } from "@bufbuild/protobuf";',
+      'import type { AgentMessage } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";',
+      'import { join } from "node:path";',
+      'import { a } from "./events.js";',
+      'import { b } from "../../shared/status.js";',
+      'import ts from "typescript";',
+      'const m = await import("@langchain/core/messages");',
+    ].join("\n");
+    expect(packageNames(file, source)).toEqual(["@bufbuild/protobuf", "@stigmer/protos", "typescript", "@langchain/core"]);
+  });
+});
+
+describe("src/harness/transcript names no engine, no SDK, no Temporal", () => {
+  const files = typeScriptFilesUnder(TRANSCRIPT_ROOT, new Set());
+  const offences = files.flatMap((file) => {
+    const allowed = isTestFile(file) ? ALLOWED_IN_TESTS : ALLOWED;
+    return packageNames(file, readSource(file))
+      .filter((pkg) => !allowed.has(pkg))
+      .map((pkg) => `  ${relative(SRC_ROOT, file)} names "${pkg}"`);
+  });
+
+  it("inspected the builder's own files, tests included (the walk is rooted where it claims)", () => {
+    const walked = files.map((f) => relative(TRANSCRIPT_ROOT, f));
+    expect(walked).toEqual(expect.arrayContaining(["builder.ts", "events.ts", "state.ts", join("__tests__", "state.test.ts")]));
+  });
+
+  it("finds no package outside the allow-list", () => {
+    expect(
+      offences,
+      `src/harness/transcript/ may name only ${[...ALLOWED_IN_TESTS].join(", ")} (vitest in tests only):\n${offences.join("\n")}`,
+    ).toEqual([]);
+  });
+});