@stigmer/runner 3.14.1 → 3.15.0

package/src/__test-utils__/harness-contract/scripted-adapter.ts

@@ -29,9 +29,20 @@
  * approval exactly once, refusing to resume a state it never minted — because
  * those are what the kit measures.
  *
- * A `runTurn` with no scenario arranged is a test bug and throws (the same
- * rule as the scripted `@cursor/sdk` agent's `send()` with no script left);
- * every other exit is a `TurnOutcome`.
+ * What this fake deliberately does NOT do, because it is not an adapter's
+ * job: carry a REJECTed or SKIPped row to its terminal status. The decision
+ * is on the row (the server's field) and the transition follows from it with
+ * no engine knowledge, so it belongs to the runtime — one writer per field,
+ * as `approvalDecisionsOf` is the runtime's one reader (S2 M4, Q-M4-1; the
+ * runtime's arm lands in S3). An adapter's whole duty for a non-executing
+ * decision is to not execute.
+ *
+ * Scenarios are arranged PER SESSION (the engine is per session in every real
+ * harness; a subject arranges that session's engine), and arranging replaces
+ * what that session had not yet played. A `runTurn` with no scenario arranged
+ * for its session is a test bug and throws (the same rule as the scripted
+ * `@cursor/sdk` agent's `send()` with no script left); every other exit is a
+ * `TurnOutcome`.
  */
 
 import { ApprovalAction, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
@@ -43,14 +54,21 @@ import type { HarnessAdapter, TurnInput, TurnOutcome, TurnSink } from "../../har
 import { DEEP_AGENT_VISION_PROFILE } from "../../shared/attachment-vision.js";
 import type { ProposedAction } from "../approval-contract/types.js";
 import { testConfig } from "../config-fixture.js";
-import { aiMessage, findToolCallRow, waitingToolCall } from "../proto-helpers.js";
-import type { HarnessContractSubject, ScenarioStep, TurnScenario } from "./types.js";
+import { aiMessage, findToolCallRow, toolCall, waitingToolCall } from "../proto-helpers.js";
+import type { EngineView, HarnessContractSubject, ScenarioStep, TurnScenario } from "./types.js";
 
 export interface ScriptedHarnessOptions {
   /** Diagnostic name; defaults to a name that says which primitives this instance runs under. */
   readonly name?: string;
   readonly pausePrimitive: PausePrimitive;
   readonly stateIdSource: StateIdSource;
+  /**
+   * The subject's `Config` over `testConfig()`'s inert defaults. The fake reads
+   * none of it; the RUNTIME does when the subject runs through the real
+   * activity (the workspace root it provisions under, the task queue the
+   * drain signal is keyed by).
+   */
+  readonly config?: Partial<Config>;
 }
 
 /**
@@ -74,9 +92,11 @@ export class ScriptedHarnessAdapter implements HarnessAdapter {
   readonly name: string;
   readonly capabilities: HarnessCapabilities;
 
-  private readonly queue: TurnScenario[] = [];
+  /** The next turn each session plays; arranging a session replaces its entry. */
+  private readonly arranged = new Map<string, TurnScenario>();
   private readonly mintedStateIds = new Set<string>();
   private readonly executions = new Map<string, number>();
+  private readonly hangWaiters: Array<() => void> = [];
   private mintCounter = 0;
 
   constructor(options: ScriptedHarnessOptions) {
@@ -88,14 +108,29 @@ export class ScriptedHarnessAdapter implements HarnessAdapter {
       subAgents: false,
       toolRestriction: true,
       visionProfile: DEEP_AGENT_VISION_PROFILE,
+      fileReview: { harnessId: "scripted", excludePaths: [] },
     };
   }
 
+  /**
+   * Resolves the next time a turn parks on a `hang` step — for a test that
+   * stands where the runtime's watchdog stands and needs to know the engine
+   * is silent before it advances the clock. Never on a timer.
+   */
+  whenHanging(): Promise<void> {
+    return new Promise((resolve) => this.hangWaiters.push(resolve));
+  }
+
   // ── Engine controls (the subject's side of the kit seam) ──────────────────
 
-  /** Queue what the next `runTurn` plays. */
-  arrange(turn: TurnScenario): void {
-    this.queue.push(turn);
+  /**
+   * What the session's next `runTurn` plays. The rest of the view is not
+   * needed here: this fake reads its decisions from `input.approvalDecisions`
+   * and settles a repeated proposal from the row itself, so it has nothing to
+   * decide before the turn.
+   */
+  arrange(turn: TurnScenario, view: Pick<EngineView, "sessionId">): void {
+    this.arranged.set(view.sessionId, turn);
   }
 
   executionCount(toolCallId: string): number {
@@ -114,8 +149,9 @@ export class ScriptedHarnessAdapter implements HarnessAdapter {
   async releaseSession(_sessionId: string): Promise<void> {}
 
   async runTurn(input: TurnInput, sink: TurnSink): Promise<TurnOutcome> {
-    const turn = this.queue.shift();
-    if (!turn) throw new Error(`${this.name}: runTurn called with no scenario arranged (test bug)`);
+    const turn = this.arranged.get(input.sessionId);
+    if (!turn) throw new Error(`${this.name}: runTurn called with no scenario arranged for session '${input.sessionId}' (test bug)`);
+    this.arranged.delete(input.sessionId);
 
     // The signal may be aborted before the turn is entered; do no work then.
     if (sink.stopSignal.aborted) return { kind: "interrupted" };
@@ -153,7 +189,7 @@ export class ScriptedHarnessAdapter implements HarnessAdapter {
       } catch (err) {
         return {
           kind: "ended",
-          outcome: { kind: "failed", message: `${this.name}: could not bind engine state`, cause: err },
+          outcome: { kind: "failed", surface: "internal", message: `${this.name}: could not bind engine state`, cause: err },
         };
       }
       return { kind: "ok" };
@@ -162,7 +198,7 @@ export class ScriptedHarnessAdapter implements HarnessAdapter {
     if (!this.mintedStateIds.has(input.threadId)) {
       return {
         kind: "ended",
-        outcome: { kind: "failed", message: `${this.name}: no engine state '${input.threadId}' to resume` },
+        outcome: { kind: "failed", surface: "internal", message: `${this.name}: no engine state '${input.threadId}' to resume` },
       };
     }
     return { kind: "ok" };
@@ -174,22 +210,42 @@ export class ScriptedHarnessAdapter implements HarnessAdapter {
       case "say": {
         sink.status.messages.push(aiMessage(step.text));
         sink.recordActivity();
-        sink.requestPersist();
+        // Awaited, as the Cursor loop awaits its own: a platform STOP the
+        // runtime reads from this write aborts the signal before the next
+        // step boundary sees it (the contract's "MAY await for ordering").
+        await sink.requestPersist();
         return undefined;
       }
       case "propose":
         return this.propose(step.toolCallId, step.action, input, sink);
+      case "read": {
+        // Ungated: the row lands COMPLETED at once, the effect counts as run,
+        // and the persist is awaited like `say`'s — a real engine's tool call
+        // is the discrete event its loop flushes on.
+        const message = aiMessage("");
+        const row = toolCall(step.toolCallId, "read", ToolCallStatus.TOOL_CALL_COMPLETED);
+        row.result = `contents of ${step.path}`;
+        message.toolCalls.push(row);
+        sink.status.messages.push(message);
+        this.executions.set(step.toolCallId, this.executionCount(step.toolCallId) + 1);
+        sink.recordActivity("read");
+        await sink.requestPersist();
+        return undefined;
+      }
       case "usage": {
         sink.reportUsage(step.delta);
         sink.recordActivity();
         return undefined;
       }
       case "hang": {
+        for (const waiter of this.hangWaiters.splice(0)) waiter();
         await whenAborted(sink.stopSignal);
         return { kind: "interrupted" };
       }
       case "fail":
-        return { kind: "failed", message: step.message };
+        return { kind: "failed", surface: step.surface, message: step.message };
+      case "cancelled":
+        return { kind: "cancelled" };
       default: {
         const exhaustive: never = step;
         throw new Error(`${this.name}: unknown scenario step ${JSON.stringify(exhaustive)}`);
@@ -230,12 +286,14 @@ export class ScriptedHarnessAdapter implements HarnessAdapter {
       case ApprovalAction.APPROVE:
       case ApprovalAction.APPROVE_ALL: {
         this.executions.set(toolCallId, this.executionCount(toolCallId) + 1);
-        this.settleRow(existing, toolCallId, action, ToolCallStatus.TOOL_CALL_COMPLETED, sink);
+        this.completeRow(existing, toolCallId, action, sink);
         return undefined;
       }
       case ApprovalAction.SKIP:
       case ApprovalAction.REJECT: {
-        this.settleRow(existing, toolCallId, action, ToolCallStatus.TOOL_CALL_SKIPPED, sink);
+        // Not executed, and the row is left as the runtime handed it (see
+        // the header): the engine simply moves on.
+        sink.recordActivity();
         return undefined;
       }
       default: {
@@ -246,24 +304,19 @@ export class ScriptedHarnessAdapter implements HarnessAdapter {
   }
 
   /**
-   * Carry the proposal's row to its terminal status. The row normally exists
-   * (the runtime seeded the status with last turn's WAITING row); a decision
-   * with no row is a runtime that decided out of band, and the adapter still
-   * records what happened rather than losing the fact.
+   * Report the executed action on its row, as a real engine's completion
+   * event does. The row normally exists (the runtime seeded the status with
+   * last turn's WAITING row); a decision with no row is a runtime that decided
+   * out of band, and the adapter still records what happened rather than
+   * losing the fact.
    */
-  private settleRow(
-    existing: ToolCall | undefined,
-    toolCallId: string,
-    action: ProposedAction,
-    status: ToolCallStatus,
-    sink: TurnSink,
-  ): void {
+  private completeRow(existing: ToolCall | undefined, toolCallId: string, action: ProposedAction, sink: TurnSink): void {
     if (existing) {
-      existing.status = status;
+      existing.status = ToolCallStatus.TOOL_CALL_COMPLETED;
     } else {
       const message = aiMessage("");
       const row = waitingToolCall(toolCallId, action.kind, "");
-      row.status = status;
+      row.status = ToolCallStatus.TOOL_CALL_COMPLETED;
       message.toolCalls.push(row);
       sink.status.messages.push(message);
     }
@@ -277,13 +330,20 @@ export interface ScriptedSubject extends HarnessContractSubject {
   readonly adapter: ScriptedHarnessAdapter;
 }
 
+/**
+ * The fake fills the `deep-agent` row in S2 — the one row the runtime does
+ * not yet serve for real (the native adapter lands in S3, and takes the row
+ * over from the fake in the runtime half then).
+ */
 export function scriptedSubject(options: ScriptedHarnessOptions): ScriptedSubject {
   const adapter = new ScriptedHarnessAdapter(options);
   return {
     name: adapter.name,
+    harness: "deep-agent",
     adapter,
-    config: testConfig(),
-    arrange: (turn) => adapter.arrange(turn),
+    config: testConfig(options.config),
+    arrange: (turn, view) => adapter.arrange(turn, view),
+    whenHanging: () => adapter.whenHanging(),
     executionCount: (toolCallId) => adapter.executionCount(toolCallId),
   };
 }

package/src/__test-utils__/harness-contract/types.ts

@@ -23,9 +23,13 @@
  * HITL taxonomy.
  */
 
+import type { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
 import type { Config } from "../../config.js";
-import type { HarnessAdapter, UsageDelta } from "../../harness/types.js";
+import type { HarnessName } from "../../harness/registry.js";
+import type { FailureSurface, HarnessAdapter, UsageDelta } from "../../harness/types.js";
 import type { ProposedAction } from "../approval-contract/types.js";
+import type { TurnInputFixtureOverrides } from "../turn-input-fixture.js";
 
 /**
  * One thing the engine does during a turn. A turn plays its steps in order
@@ -35,20 +39,33 @@ import type { ProposedAction } from "../approval-contract/types.js";
  *  - `propose`: the engine reaches a gated side effect identified by
  *    `toolCallId`. Undecided → the turn ends `awaiting_approval` and later
  *    steps do not run; APPROVE → the effect runs once and the turn continues;
- *    REJECT / SKIP → the effect never runs and the turn continues.
+ *    REJECT / SKIP → the effect never runs and the turn continues. WHICH
+ *    kinds a harness gates is the harness's policy and the workspace's
+ *    posture: a `shell` is gated by every harness in every posture; a `write`
+ *    is gated only outside apply-then-review capture (a git tree, or artifact
+ *    storage), so an arm that must gate on every subject proposes a `shell`.
+ *  - `read`: the engine performs an UNGATED read of `path` — a tool-call row
+ *    that runs at once, never pauses, and is the discrete event every harness
+ *    flushes a persist on (the lever an arm pulls when it needs the control
+ *    plane to answer a mid-turn persist).
  *  - `usage`: the engine reports one turn's token counts.
  *  - `hang`: the engine makes no further progress until told to stop. The
  *    step that the stop-signal invariants and the runtime's stall watchdog
  *    are built around; it must be parked on the signal, never on a timer.
  *  - `fail`: the engine fails with a message the adapter can name; the turn
- *    ends `failed`.
+ *    ends `failed` on the given surface (`engine` unless the scenario says
+ *    otherwise — the runtime's three failure copies are its own invariant).
+ *  - `cancelled`: the engine ends its own run cancelled with nothing to
+ *    wait for (an SDK-side cancel); the turn ends `cancelled`.
  */
 export type ScenarioStep =
   | { readonly kind: "say"; readonly text: string }
   | { readonly kind: "propose"; readonly toolCallId: string; readonly action: ProposedAction }
+  | { readonly kind: "read"; readonly toolCallId: string; readonly path: string }
   | { readonly kind: "usage"; readonly delta: UsageDelta }
   | { readonly kind: "hang" }
-  | { readonly kind: "fail"; readonly message: string };
+  | { readonly kind: "fail"; readonly message: string; readonly surface: FailureSurface }
+  | { readonly kind: "cancelled" };
 
 /** One turn's worth of engine behaviour. */
 export type TurnScenario = readonly ScenarioStep[];
@@ -61,36 +78,95 @@ export const scenario = {
   propose(toolCallId: string, action: ProposedAction): ScenarioStep {
     return { kind: "propose", toolCallId, action };
   },
+  read(toolCallId: string, path: string): ScenarioStep {
+    return { kind: "read", toolCallId, path };
+  },
   usage(delta: UsageDelta): ScenarioStep {
     return { kind: "usage", delta };
   },
   hang(): ScenarioStep {
     return { kind: "hang" };
   },
-  fail(message: string): ScenarioStep {
-    return { kind: "fail", message };
+  fail(message: string, surface: FailureSurface = "engine"): ScenarioStep {
+    return { kind: "fail", message, surface };
+  },
+  cancelled(): ScenarioStep {
+    return { kind: "cancelled" };
   },
 } as const;
 
+/**
+ * What the engine can know about the turn it is about to play, handed to the
+ * subject with every {@link HarnessContractSubject.arrange}: which execution
+ * and session it serves (a real engine is per session — its handle is parked
+ * under the session, its workspace and hook state live under the session —
+ * so a subject arranges THAT session's engine, never "the next turn"), and
+ * the approval decisions the prompt will carry (the runtime's
+ * `approvalDecisionsOf` over the persisted status — the one reader both
+ * drivers call). A subject whose engine cannot re-run a settled action, or
+ * whose model is told not to perform a skipped one, reads its decision here
+ * instead of parsing the prompt for it.
+ */
+export interface EngineView {
+  readonly executionId: string;
+  readonly sessionId: string;
+  readonly approvalDecisions: ReadonlyMap<string, ApprovalAction>;
+}
+
+/**
+ * What a subject may say about the record its engine is handed, laid UNDER
+ * the driver's own facts: the five it threads (`executionId`, `threadId`,
+ * `turnSeq`, `sessionId`, `approvalDecisions`) and the persisted status it
+ * seeds are the kit's bookkeeping and never a subject's to state.
+ */
+export type SubjectInputOverrides = Omit<
+  TurnInputFixtureOverrides,
+  "executionId" | "threadId" | "turnSeq" | "sessionId" | "approvalDecisions" | "persistedStatus"
+>;
+
 /**
  * One adapter under test, with the engine controls the kit needs. Adapters
  * translate scenarios into their own double's drives and report what the
  * double observed; they never reimplement contract behaviour.
+ *
+ * The kit owns the adapter's lifetime: it boots the adapter before the first
+ * turn and shuts it down after the last (the registry boots every adapter
+ * before the worker polls, and a real adapter refuses a turn before boot).
+ * The exported assertion functions therefore REQUIRE a booted adapter.
  */
 export interface HarnessContractSubject {
   /** Stable name, used in suite titles and every assertion message. */
   readonly name: string;
+  /** The registry row this adapter fills; the runtime half selects the activity by it. */
+  readonly harness: HarnessName;
   /** The adapter under test — the real implementation of the contract. */
   readonly adapter: HarnessAdapter;
   /** What `adapter.boot` needs. The subject knows its adapter's fields; the kit does not. */
   readonly config: Config;
   /**
-   * Arrange the engine so that the NEXT `runTurn` on this adapter plays
-   * `turn`. Called by the kit before every `runTurn`, including a
+   * Arrange the engine so that the NEXT `runTurn` for `view.sessionId` plays
+   * `turn` — REPLACING whatever was arranged for that session and not yet
+   * played (a turn interrupted before its engine ran leaves no stale script
+   * behind). Called by the kit before every `runTurn`, including a
    * reinvocation (the engine re-reaches the same gated call on resume, so the
    * same proposal is arranged again).
    */
-  arrange(turn: TurnScenario): void;
+  arrange(turn: TurnScenario, view: EngineView): void;
+  /**
+   * What this engine needs the record to say beyond the driver's facts (the
+   * model the adapter validates, the workspace its gate installs into). A
+   * subject whose engine reads nothing of the record omits it.
+   */
+  inputOverrides?(view: EngineView): SubjectInputOverrides;
+  /**
+   * Resolves the next time a turn parks on a `hang` step — the moment the
+   * kit stops a turn from the outside, and the moment the runtime half
+   * delivers a cancellation, a drain or the clock tick that trips the stall
+   * watchdog. A real engine reaches its hang only after real setup (file
+   * writes, catalog fetches); a stop delivered any earlier would land in that
+   * setup and prove nothing about the hang. Never a timer.
+   */
+  whenHanging(): Promise<void>;
   /**
    * How many times the side effect behind `toolCallId` actually ran, as the
    * subject's double observed it. The safety-critical observable; zero for an

package/src/__test-utils__/hermetic-activity.ts

@@ -77,12 +77,13 @@ import {
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import {
   ApprovalAction,
+  ExecutionControlSignal,
   ExecutionPhase,
   ToolCallStatus,
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { UpdateStatusResponseSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
 import type { ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
-import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import { SessionSchema, type Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
 import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
 import type { AgentInstance } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/api_pb";
 import type { StigmerClient } from "../client/stigmer-client.js";
@@ -107,11 +108,20 @@ export interface ExecutionRecordInput {
   readonly session: Session;
   readonly agentInstance: AgentInstance;
   readonly agent: Agent;
+  /**
+   * What `UpdateStatus` answers for each FULL status write — the platform's
+   * STOP lever (`ExecutionControlSignal`), decided by the control plane per
+   * write and read by the harness stream loop on its mid-stream persist.
+   * Evaluated AFTER the write lands, on the snapshot just persisted, so a
+   * policy can key on the transcript ("stop once the first assistant message
+   * is in"). Defaults to UNSPECIFIED: keep going.
+   */
+  readonly controlSignal?: (status: AgentExecutionStatus) => ExecutionControlSignal;
 }
 
 /**
  * An in-memory stand-in for the server's execution row, with the TWO merge
- * rules the activity depends on and no others:
+ * rules and the ONE control lever the activity depends on, and no others:
  *
  *  - A status whose phase is UNSPECIFIED is a setup-progress report
  *    (`reportSetupProgress`): the server keeps `setup_progress` and leaves the
@@ -120,6 +130,10 @@ export interface ExecutionRecordInput {
  *    writer of the transcript; the server's own field-ownership merge — approval
  *    fields it owns — is exercised by the test SETTING `approvalAction` on the
  *    record between invocations, exactly as `SubmitApproval` would).
+ *  - Every `UpdateStatus` answers a control signal ({@link ExecutionRecordInput.controlSignal});
+ *    the server's STOP is the one instruction that travels back to the runner
+ *    on this channel, and it is a server decision, so it is modelled here and
+ *    not by the test hand-writing the client.
  *
  * Every persisted status is also kept in order (`persisted`) so a test can
  * assert the phase sequence the activity wrote, independent of the final state.
@@ -129,11 +143,16 @@ export class ExecutionRecord {
   readonly session: Session;
   readonly agentInstance: AgentInstance;
   readonly agent: Agent;
+  private readonly controlSignal: (status: AgentExecutionStatus) => ExecutionControlSignal;
   /** Every `updateStatus` payload, in order, snapshotted at write time. */
   readonly persisted: AgentExecutionStatus[] = [];
   /** Setup-progress labels reported before the stream started, in order. */
   readonly setupProgress: string[] = [];
-  /** Every `updateSession` payload, in order (the `harness_state_id` write-back). */
+  /**
+   * Every `updateSession` payload, in order (the `harness_state_id` write-back),
+   * snapshotted at write time: the activity re-binds the SAME session object on
+   * a fresh-agent recovery, so a live reference would show the second id twice.
+   */
   readonly sessionUpdates: Session[] = [];
 
   constructor(input: ExecutionRecordInput) {
@@ -141,6 +160,7 @@ export class ExecutionRecord {
     this.session = input.session;
     this.agentInstance = input.agentInstance;
     this.agent = input.agent;
+    this.controlSignal = input.controlSignal ?? (() => ExecutionControlSignal.UNSPECIFIED);
   }
 
   get executionId(): string {
@@ -201,16 +221,22 @@ export class ExecutionRecord {
     return waiting.length;
   }
 
-  applyStatusUpdate(status: AgentExecutionStatus): void {
+  /**
+   * Apply one `UpdateStatus` write and answer the control signal the server
+   * would. A setup-progress report never carries a signal (the runner ignores
+   * the response there; the server has nothing to say about a label).
+   */
+  applyStatusUpdate(status: AgentExecutionStatus): ExecutionControlSignal {
     const snapshot = clone(AgentExecutionStatusSchema, status);
     this.persisted.push(snapshot);
     if (snapshot.phase === ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED) {
       if (snapshot.setupProgress?.currentPhase) {
         this.setupProgress.push(snapshot.setupProgress.currentPhase);
       }
-      return;
+      return ExecutionControlSignal.UNSPECIFIED;
     }
     this.execution.status = clone(AgentExecutionStatusSchema, snapshot);
+    return this.controlSignal(snapshot);
   }
 
   /**
@@ -228,12 +254,11 @@ export class ExecutionRecord {
       getAgentInstance: vi.fn(async () => this.agentInstance),
       getAgent: vi.fn(async () => this.agent),
       updateStatus: vi.fn(async (_id: string, status: AgentExecutionStatus) => {
-        this.applyStatusUpdate(status);
         // The activity reads only `.signal`; UNSPECIFIED means "keep going".
-        return create(UpdateStatusResponseSchema, {});
+        return create(UpdateStatusResponseSchema, { signal: this.applyStatusUpdate(status) });
       }),
       updateSession: vi.fn(async (session: Session) => {
-        this.sessionUpdates.push(session);
+        this.sessionUpdates.push(clone(SessionSchema, session));
         return session;
       }),
       getExecutionContextByExecutionId: vi.fn(async () => {

package/src/__test-utils__/model-registry-fixture.ts

@@ -0,0 +1,72 @@
+/**
+ * The model registry document a hermetic activity run reads, and the `fetch`
+ * stub that serves it and refuses everything else.
+ *
+ * The activity's only HTTP fetch is the model registry (`shared/model-
+ * registry.ts` for vision capability; the Cursor harness's `model-pricing-
+ * data.ts` for pricing). Both fail SOFT to defaults with a 60 s failure
+ * cache, which would make a golden depend on DEFAULT_PRICING and log a
+ * warning on every run, so a hermetic run stubs `fetch` to answer one
+ * registry document — and to THROW for any other URL, so a new network
+ * dependency on the activity path fails the run instead of leaking.
+ *
+ * One entry, `composer-2.5`, priced at round numbers so a golden's
+ * `estimatedCostUsd` is legible (600 000 input tokens = $0.60). The entry is
+ * a Cursor-harness model because that is what the registry lists; the
+ * document itself is the control plane's, read by every harness's runtime.
+ * `parsePricingTable` wants `harness: "cursor"` + `pricing`; `parseRegistry`
+ * wants `id` + `provider` and reads `capabilities.vision`.
+ */
+
+import { vi } from "vitest";
+
+/** The pinned model of every hermetic run; in the registry document AND in the Cursor double's catalog. */
+export const FIXTURE_MODEL = "composer-2.5";
+
+export const REGISTRY_DOCUMENT = {
+  models: [
+    {
+      id: FIXTURE_MODEL,
+      displayName: "Composer 2.5 (hermetic fixture)",
+      provider: "cursor",
+      harness: "cursor",
+      costTier: "standard",
+      featured: true,
+      capabilities: { vision: true },
+      pricing: {
+        inputPricePerMillion: 1.0,
+        outputPricePerMillion: 4.0,
+        cacheWritePricePerMillion: 1.0,
+        cacheReadPricePerMillion: 0.1,
+      },
+      pricingVariants: {
+        fast: {
+          inputPricePerMillion: 3.0,
+          outputPricePerMillion: 12.0,
+          cacheWritePricePerMillion: 3.0,
+          cacheReadPricePerMillion: 0.3,
+        },
+      },
+    },
+  ],
+} as const;
+
+/**
+ * Stub `fetch` to answer the registry document and refuse everything else.
+ * Returns the URLs fetched, for the "no other network" assertion.
+ */
+export function stubRegistryFetch(): { readonly urls: string[]; restore(): void } {
+  const urls: string[] = [];
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (input: string | URL | Request) => {
+      const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+      urls.push(url);
+      if (!url.includes("/model-registry")) {
+        throw new Error(`hermetic run attempted a non-registry network call: ${url}`);
+      }
+      return { ok: true, status: 200, json: async () => REGISTRY_DOCUMENT } as unknown as Response;
+    }),
+  );
+  return { urls, restore: () => vi.unstubAllGlobals() };
+}

package/src/__test-utils__/module-specifiers.ts

@@ -0,0 +1,82 @@
+/**
+ * The module specifiers a TypeScript file names, read off its syntax tree —
+ * the primitive behind the runner's import fences.
+ *
+ * Two fences stand on it: `src/harness/` and production `src/shared/` never
+ * import `src/activities/` (`harness/__tests__/import-direction.test.ts`,
+ * the rule the turn runtime is written under), and the Cursor adapter never
+ * imports `@temporalio/*` (`execute-cursor/__tests__/adapter-is-temporal-
+ * free.test.ts`, what lets the contract kit run it outside an activity).
+ *
+ * A syntax tree, not a regex, so a path quoted in a header comment cannot
+ * trip a fence, and no import form can slip past one: static, type-only,
+ * side-effect, re-export and dynamic `import()` are all module specifiers to
+ * the parser. A dynamic import whose argument is not a string literal names
+ * nothing and is ignored (no fence has a literal to match).
+ */
+
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import ts from "typescript";
+
+/** Every module specifier a file names, in source order, whatever the form. */
+export function moduleSpecifiers(fileName: string, source: string): string[] {
+  const sourceFile = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, /* setParentNodes */ false);
+  const specifiers: string[] = [];
+  const visit = (node: ts.Node): void => {
+    if (
+      (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) &&
+      node.moduleSpecifier !== undefined &&
+      ts.isStringLiteral(node.moduleSpecifier)
+    ) {
+      specifiers.push(node.moduleSpecifier.text);
+    } else if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+      const [argument] = node.arguments;
+      if (argument !== undefined && ts.isStringLiteralLike(argument)) {
+        specifiers.push(argument.text);
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return specifiers;
+}
+
+/**
+ * The relative specifiers in `source` that resolve to a path inside
+ * `forbiddenRoot`. Package specifiers are ignored: no alias maps a package
+ * name onto a source directory.
+ */
+export function forbiddenImports(filePath: string, source: string, forbiddenRoot: string): string[] {
+  return moduleSpecifiers(filePath, source).filter((specifier) => {
+    if (!specifier.startsWith(".")) return false;
+    const target = resolve(dirname(filePath), specifier);
+    return target === forbiddenRoot || target.startsWith(forbiddenRoot + sep);
+  });
+}
+
+/** The package specifiers in `source` whose name is `pkg` or starts with `${pkg}/`. */
+export function packageImports(filePath: string, source: string, pkg: string): string[] {
+  return moduleSpecifiers(filePath, source).filter((specifier) => specifier === pkg || specifier.startsWith(`${pkg}/`));
+}
+
+/** Every `.ts` file under `dir`, sorted, skipping the named directories at any depth. */
+export function typeScriptFilesUnder(dir: string, skipDirectories: ReadonlySet<string>): string[] {
+  const files: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (!skipDirectories.has(entry.name)) {
+        files.push(...typeScriptFilesUnder(path, skipDirectories));
+      }
+    } else if (entry.name.endsWith(".ts")) {
+      files.push(path);
+    }
+  }
+  return files.sort();
+}
+
+/** Read a file for a sweep; one place so every fence reads the same bytes the compiler does. */
+export function readSource(filePath: string): string {
+  return readFileSync(filePath, "utf-8");
+}