@stigmer/runner 3.14.0 → 3.15.0

package/dist/shared/workspace/platform-dir.d.ts

@@ -12,7 +12,7 @@
  *   path is written into the workspace itself.
  *
  * This module replaces the duplicated `getPlatformDir` helpers in
- * execute-cursor/skill-resolver.ts and execute-cursor/attachment-resolver.ts.
+ * execute-cursor/skill-resolver.ts and shared/attachment-resolver.ts.
  */
 /**
  * Compute the WORKSPACE-scoped HITL gate directory — the home for the STABLE

package/dist/shared/workspace/platform-dir.js

@@ -12,7 +12,7 @@
  *   path is written into the workspace itself.
  *
  * This module replaces the duplicated `getPlatformDir` helpers in
- * execute-cursor/skill-resolver.ts and execute-cursor/attachment-resolver.ts.
+ * execute-cursor/skill-resolver.ts and shared/attachment-resolver.ts.
  */
 import { join } from "node:path";
 import { mkdir } from "node:fs/promises";

package/dist/shared/workspace/session-provision.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Local workspace provisioning for a harness turn.
+ *
+ * Harness-agnostic: the Cursor activity is today's only caller, the turn
+ * runtime takes it over in S2 M3, and S3 retires the native twin
+ * (execute-deep-agent/setup.ts `provisionWorkspace`). Agents run LOCAL
+ * (cloud is disabled — see execute-cursor/cursor-mode.ts), so the runner
+ * must clone git-repo workspace entries itself and mount local-path entries
+ * before the agent runs. Cloud agents previously cloned git repos
+ * server-side; that path is no longer used.
+ */
+import type { Config } from "../../config.js";
+import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import type { ProvisionResult, WorkspaceBackend } from "./types.js";
+/**
+ * The two runner settings provisioning reads. A `Pick` over `Config` rather
+ * than a fresh options type so a caller holding the whole `Config` (the turn
+ * orchestrator, and the runtime that replaces it) passes it unchanged, while
+ * the signature states exactly what is consumed: the root every workspace
+ * resolves under, and the mode that decides whether git entries are cloned
+ * or expected in place. A test constructs the two fields and nothing else.
+ */
+export type SessionProvisionConfig = Pick<Config, "workspaceRootDir" | "mode">;
+/** What {@link provisionSessionWorkspace} hands back to the harness. */
+export interface SessionWorkspaceProvision {
+    /** The directories the agent should operate in (never empty). */
+    readonly workspaceDirs: string[];
+    /**
+     * Per-entry provision outcomes — carries the git metadata (repo URL, base
+     * branch, credential state) the write-back coordinator needs. Empty for a
+     * session with no workspace entries.
+     */
+    readonly provisionResults: ProvisionResult[];
+    /**
+     * The backend the entries were provisioned through — the write-back
+     * coordinator executes its git commands through it.
+     */
+    readonly workspaceBackend: WorkspaceBackend;
+}
+/**
+ * Provision the session's workspace entries for a LOCAL agent.
+ *
+ * Clones git-repo entries (using the user's GITHUB_TOKEN from the resolved
+ * execution environment) and mounts local-path entries, then returns the
+ * directories the agent should operate in — along with the provision results
+ * and backend the git write-back coordinator needs. A session with no
+ * workspace entries gets its own empty per-session directory (see
+ * session-root.ts) — never the shared root, which would leak other sessions'
+ * files into it.
+ *
+ * provisionGit is idempotent (it reuses an existing clone), so this is safe
+ * to call on every execution, including multi-turn and HITL reinvocations.
+ */
+export declare function provisionSessionWorkspace(config: SessionProvisionConfig, session: Session, envVars: Record<string, string>, sessionId: string): Promise<SessionWorkspaceProvision>;

package/dist/{activities/execute-cursor/workspace-provision.js → shared/workspace/session-provision.js}

@@ -1,17 +1,20 @@
 /**
- * Local workspace provisioning for the Cursor harness.
+ * Local workspace provisioning for a harness turn.
  *
- * Cursor agents run LOCAL (cloud is disabled — see cursor-mode.ts), so the
- * runner must clone git-repo workspace entries itself and mount local-path
- * entries before the agent runs, mirroring the native harness. Cloud agents
- * previously cloned git repos server-side; that path is no longer used.
+ * Harness-agnostic: the Cursor activity is today's only caller, the turn
+ * runtime takes it over in S2 M3, and S3 retires the native twin
+ * (execute-deep-agent/setup.ts `provisionWorkspace`). Agents run LOCAL
+ * (cloud is disabled — see execute-cursor/cursor-mode.ts), so the runner
+ * must clone git-repo workspace entries itself and mount local-path entries
+ * before the agent runs. Cloud agents previously cloned git repos
+ * server-side; that path is no longer used.
  */
-import { WorkspaceProvisioner } from "../../shared/workspace/provisioner.js";
-import { LocalWorkspaceBackend } from "../../shared/workspace/local-backend.js";
-import { ensurePlatformDir } from "../../shared/workspace/platform-dir.js";
-import { resolveSessionWorkspaceRoot } from "../../shared/workspace/session-root.js";
+import { WorkspaceProvisioner } from "./provisioner.js";
+import { LocalWorkspaceBackend } from "./local-backend.js";
+import { ensurePlatformDir } from "./platform-dir.js";
+import { resolveSessionWorkspaceRoot } from "./session-root.js";
 /**
- * Provision the session's workspace entries for a LOCAL Cursor agent.
+ * Provision the session's workspace entries for a LOCAL agent.
  *
  * Clones git-repo entries (using the user's GITHUB_TOKEN from the resolved
  * execution environment) and mounts local-path entries, then returns the
@@ -24,7 +27,7 @@ import { resolveSessionWorkspaceRoot } from "../../shared/workspace/session-root
  * provisionGit is idempotent (it reuses an existing clone), so this is safe
  * to call on every execution, including multi-turn and HITL reinvocations.
  */
-export async function provisionCursorWorkspace(config, session, envVars, sessionId) {
+export async function provisionSessionWorkspace(config, session, envVars, sessionId) {
     const entries = session.spec?.workspaceEntries ?? [];
     const platformDir = await ensurePlatformDir(sessionId);
     if (entries.length === 0) {
@@ -47,4 +50,4 @@ export async function provisionCursorWorkspace(config, session, envVars, session
         workspaceBackend: backend,
     };
 }
-//# sourceMappingURL=workspace-provision.js.map
+//# sourceMappingURL=session-provision.js.map

package/dist/shared/workspace/session-provision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-provision.js","sourceRoot":"","sources":["../../../src/shared/workspace/session-provision.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAExD,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AA6BhE;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,MAA8B,EAC9B,OAAgB,EAChB,OAA+B,EAC/B,SAAiB;IAEjB,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,gBAAgB,IAAI,EAAE,CAAC;IACrD,MAAM,WAAW,GAAG,MAAM,iBAAiB,CAAC,SAAS,CAAC,CAAC;IAEvD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,WAAW,GAAG,MAAM,2BAA2B,CACnD,MAAM,CAAC,gBAAgB,EAAE,OAAO,EAAE,SAAS,CAC5C,CAAC;QACF,OAAO;YACL,aAAa,EAAE,CAAC,WAAW,CAAC;YAC5B,gBAAgB,EAAE,EAAE;YACpB,gBAAgB,EAAE,IAAI,qBAAqB,CAAC,WAAW,EAAE,WAAW,CAAC;SACtE,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,qBAAqB,CAAC,MAAM,CAAC,gBAAgB,EAAE,WAAW,CAAC,CAAC;IAEhF,MAAM,WAAW,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC/C,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,YAAY,CAC5C,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,EACpE,OAAO,EACP,OAAO,EACP,MAAM,CAAC,IAAI,KAAK,OAAO,EACvB,MAAM,CAAC,IAAI,KAAK,OAAO,CACxB,CAAC;IAEF,MAAM,IAAI,GAAG,OAAO;SACjB,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC;SAC/B,MAAM,CAAC,CAAC,GAAG,EAAiB,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IAEhD,OAAO;QACL,aAAa,EAAE,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,gBAAgB,CAAC;QACjE,gBAAgB,EAAE,OAAO;QACzB,gBAAgB,EAAE,OAAO;KAC1B,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/runner",
-  "version": "3.14.0",
+  "version": "3.15.0",
   "description": "Embeddable Temporal worker for the Stigmer AI agent platform — handles agent execution, workflow orchestration, and MCP server management",
   "license": "Apache-2.0",
   "type": "module",
@@ -104,9 +104,9 @@
     "@opentelemetry/sdk-metrics": "^2.0.0",
     "@opentelemetry/sdk-trace-base": "^2.0.0",
     "@opentelemetry/sdk-trace-node": "^2.0.0",
-    "@stigmer/protos": "3.14.0",
-    "@stigmer/temporal-codecs": "3.14.0",
-    "@stigmer/zip-structure": "3.14.0",
+    "@stigmer/protos": "3.15.0",
+    "@stigmer/temporal-codecs": "3.15.0",
+    "@stigmer/zip-structure": "3.15.0",
     "@temporalio/activity": "1.16.2",
     "@temporalio/common": "1.16.2",
     "@temporalio/interceptors-opentelemetry": "1.16.2",

package/src/__test-utils__/__tests__/harness-contract-self-check.test.ts

@@ -0,0 +1,325 @@
+/**
+ * The harness contract kit's self-check: proof that every invariant in
+ * `harness-contract/contract.ts` can FAIL.
+ *
+ * A contract kit that only ever passes proves nothing about the adapters it
+ * runs against — it might be asserting the wrong thing, or nothing. So each
+ * invariant is run here against an adapter deliberately broken in exactly the
+ * way that invariant exists to catch, and the kit must reject with a message
+ * that names the subject and the violation. The tester role's rule: a test
+ * that cannot fail is not a test.
+ *
+ * Every broken adapter wraps the honest scripted fake and breaks ONE thing,
+ * so a rejection here is attributable to the kit's assertion and not to some
+ * other defect of the double. Where an invariant races a hang against the
+ * interrupt bound, the bound is shortened through the assertion's parameter;
+ * the production bound stays what `contract.ts` declares. Every subject is
+ * booted first, as the kit's `describeHarnessContract` boots the adapters it
+ * runs (the assertion functions require it).
+ *
+ * The second half checks the kit's own driver — the runtime stand-in — for
+ * the facts a real adapter depends on and the fake never notices: the record
+ * carries the persisted status (an adapter may read its grants from
+ * `execution.status`, as the runtime guarantees), the engine's view carries
+ * the driver's ids and decisions, and a stop lands only once the engine
+ * reports it is parked.
+ */
+
+import { describe, it, expect } from "vitest";
+import { CancelledFailure } from "@temporalio/activity";
+import { ApprovalAction, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+import type { HarnessAdapter, TurnInput, TurnOutcome, TurnSink } from "../../harness/types.js";
+import {
+  ExecutionDriver,
+  assertConcurrentTurnsAreIndependent,
+  assertDecisionsExecuteExactlyOnce,
+  assertEveryExitIsAnOutcome,
+  assertLifetimesResolve,
+  assertProposalIsWaitingAndUnexecuted,
+  assertStateIdCapabilityAgrees,
+  assertStopSignalInterrupts,
+  assertUsageReachesSinkAsDeltas,
+} from "../harness-contract/contract.js";
+import { scriptedSubject } from "../harness-contract/scripted-adapter.js";
+import type { ScriptedSubject } from "../harness-contract/scripted-adapter.js";
+import { scenario } from "../harness-contract/types.js";
+import type { EngineView, HarnessContractSubject, TurnScenario } from "../harness-contract/types.js";
+import { findToolCallRow } from "../proto-helpers.js";
+
+/** Short enough to keep this file fast; long enough that an honest microtask settle never trips it. */
+const SHORT_BOUND_MS = 100;
+
+// ── Wrapping helpers ────────────────────────────────────────────────────────
+
+/** The kit boots before it asserts; so does every arm here. */
+async function booted<S extends HarnessContractSubject>(subject: S): Promise<S> {
+  await subject.adapter.boot(subject.config);
+  return subject;
+}
+
+/** The honest fake's adapter with the named members replaced. */
+function adapterOver(inner: HarnessAdapter, name: string, patch: Partial<HarnessAdapter>): HarnessAdapter {
+  return {
+    name,
+    capabilities: inner.capabilities,
+    boot: (config) => inner.boot(config),
+    shutdown: () => inner.shutdown(),
+    releaseSession: (sessionId) => inner.releaseSession(sessionId),
+    runTurn: (input, sink) => inner.runTurn(input, sink),
+    ...patch,
+  };
+}
+
+/** A sink that delegates to the real one except for the named members. */
+function sinkOver(inner: TurnSink, patch: Partial<TurnSink>): TurnSink {
+  return {
+    status: inner.status,
+    stopSignal: inner.stopSignal,
+    setupTiming: inner.setupTiming,
+    requestPersist: () => inner.requestPersist(),
+    recordActivity: (detail) => inner.recordActivity(detail),
+    reportUsage: (delta) => inner.reportUsage(delta),
+    reportProgress: (label) => inner.reportProgress(label),
+    bindHarnessState: (id) => inner.bindHarnessState(id),
+    ...patch,
+  };
+}
+
+/** A subject over a broken adapter that still arranges and observes through the honest fake. */
+function subjectOver(inner: ScriptedSubject, adapter: HarnessAdapter): HarnessContractSubject {
+  return {
+    name: adapter.name,
+    harness: inner.harness,
+    adapter,
+    config: inner.config,
+    arrange: (turn, view) => inner.arrange(turn, view),
+    whenHanging: () => inner.whenHanging(),
+    executionCount: (toolCallId) => inner.executionCount(toolCallId),
+  };
+}
+
+function honest(): ScriptedSubject {
+  return scriptedSubject({ pausePrimitive: "interrupt", stateIdSource: "engine-minted" });
+}
+
+// ── The broken adapters, one violation each ─────────────────────────────────
+
+/** Throws the one thing an adapter must never throw. */
+function throwsCancelledFailure(): HarnessContractSubject {
+  const inner = honest();
+  return subjectOver(inner, adapterOver(inner.adapter, "broken:throws-CancelledFailure", {
+    runTurn: async () => {
+      throw new CancelledFailure("adapter decided this was a pause");
+    },
+  }));
+}
+
+/** Treats every proposal as approved: executes what was never decided. */
+function executesUndecidedProposals(): HarnessContractSubject {
+  const inner = honest();
+  let proposedIds: string[] = [];
+  const adapter = adapterOver(inner.adapter, "broken:executes-undecided", {
+    runTurn: (input, sink) => {
+      const approvalDecisions = new Map(input.approvalDecisions);
+      for (const id of proposedIds) if (!approvalDecisions.has(id)) approvalDecisions.set(id, ApprovalAction.APPROVE);
+      return inner.adapter.runTurn({ ...input, approvalDecisions }, sink);
+    },
+  });
+  return {
+    ...subjectOver(inner, adapter),
+    arrange: (turn: TurnScenario, view: EngineView) => {
+      proposedIds = turn.flatMap((step) => (step.kind === "propose" ? [step.toolCallId] : []));
+      inner.arrange(turn, view);
+    },
+  };
+}
+
+/** Re-gates a row an earlier invocation already settled — the second-ledger drift. */
+function reGatesSettledRows(): HarnessContractSubject {
+  const inner = honest();
+  return subjectOver(inner, adapterOver(inner.adapter, "broken:re-gates-settled", {
+    runTurn: (input, sink) => {
+      for (const message of sink.status.messages) {
+        for (const row of message.toolCalls) {
+          if (row.status === ToolCallStatus.TOOL_CALL_COMPLETED) row.status = ToolCallStatus.TOOL_CALL_WAITING_APPROVAL;
+        }
+      }
+      return inner.adapter.runTurn(input, sink);
+    },
+  }));
+}
+
+/** Hands the engine a signal nobody will ever abort. */
+function ignoresStopSignal(): HarnessContractSubject {
+  const inner = honest();
+  return subjectOver(inner, adapterOver(inner.adapter, "broken:ignores-stopSignal", {
+    runTurn: (input, sink) => inner.adapter.runTurn(input, sinkOver(sink, { stopSignal: new AbortController().signal })),
+  }));
+}
+
+/** Reports running totals where the contract asks for deltas. */
+function reportsCumulativeUsage(): HarnessContractSubject {
+  const inner = honest();
+  return subjectOver(inner, adapterOver(inner.adapter, "broken:cumulative-usage", {
+    runTurn: (input, sink) => {
+      const total = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 };
+      return inner.adapter.runTurn(input, sinkOver(sink, {
+        reportUsage: (delta) => {
+          total.inputTokens += delta.inputTokens ?? 0;
+          total.outputTokens += delta.outputTokens ?? 0;
+          total.cacheReadTokens += delta.cacheReadTokens ?? 0;
+          total.cacheWriteTokens += delta.cacheWriteTokens ?? 0;
+          sink.reportUsage({ ...total });
+        },
+      }));
+    },
+  }));
+}
+
+/** Declares an engine-minted id and never binds one. */
+function claimsEngineMintedNeverBinds(): HarnessContractSubject {
+  const inner = scriptedSubject({ pausePrimitive: "interrupt", stateIdSource: "deterministic" });
+  return subjectOver(inner, adapterOver(inner.adapter, "broken:claims-engine-minted", {
+    capabilities: { ...inner.adapter.capabilities, stateIdSource: "engine-minted" },
+  }));
+}
+
+/** Refuses to release a session it does not know. */
+function refusesUnknownRelease(): HarnessContractSubject {
+  const inner = honest();
+  const served = new Set<string>();
+  return subjectOver(inner, adapterOver(inner.adapter, "broken:refuses-unknown-release", {
+    runTurn: (input, sink) => {
+      served.add(input.sessionId);
+      return inner.adapter.runTurn(input, sink);
+    },
+    releaseSession: async (sessionId) => {
+      if (!served.has(sessionId)) throw new Error(`unknown session ${sessionId}`);
+      await inner.adapter.releaseSession(sessionId);
+    },
+  }));
+}
+
+/** Runs turns one at a time through a single slot: per-turn state on the adapter object. */
+function serializesTurns(): HarnessContractSubject {
+  const inner = honest();
+  let slot: Promise<unknown> = Promise.resolve();
+  return subjectOver(inner, adapterOver(inner.adapter, "broken:serializes-turns", {
+    runTurn: (input: TurnInput, sink: TurnSink): Promise<TurnOutcome> => {
+      const next = slot.then(() => inner.adapter.runTurn(input, sink));
+      slot = next.catch(() => undefined);
+      return next;
+    },
+  }));
+}
+
+// ── The proof ───────────────────────────────────────────────────────────────
+
+describe("harness contract kit self-check — every invariant can fail", () => {
+  it("invariant 1 fires when runTurn throws a CancelledFailure", async () => {
+    await expect(assertEveryExitIsAnOutcome(await booted(throwsCancelledFailure()), SHORT_BOUND_MS)).rejects.toThrow(/broken:throws-CancelledFailure: runTurn rejected with a CancelledFailure/);
+  });
+
+  it("invariant 2 fires when an undecided proposal executes", async () => {
+    await expect(assertProposalIsWaitingAndUnexecuted(await booted(executesUndecidedProposals()))).rejects.toThrow(/broken:executes-undecided: .*awaiting_approval/);
+  });
+
+  it("invariant 3 fires when a settled row is re-gated on a later invocation", async () => {
+    await expect(assertDecisionsExecuteExactlyOnce(await booted(reGatesSettledRows()))).rejects.toThrow(/broken:re-gates-settled: .*must not re-gate/);
+  });
+
+  it("invariant 4 fires when the adapter ignores stopSignal", async () => {
+    await expect(assertStopSignalInterrupts(await booted(ignoresStopSignal()), SHORT_BOUND_MS)).rejects.toThrow(/broken:ignores-stopSignal: runTurn did not settle within 100ms/);
+  });
+
+  it("invariant 5 fires when usage is reported as running totals", async () => {
+    await expect(assertUsageReachesSinkAsDeltas(await booted(reportsCumulativeUsage()))).rejects.toThrow(/broken:cumulative-usage: .*must sum to what the engine emitted/);
+  });
+
+  it("invariant 6 fires when an adapter claims engine-minted and never binds", async () => {
+    await expect(assertStateIdCapabilityAgrees(await booted(claimsEngineMintedNeverBinds()))).rejects.toThrow(/broken:claims-engine-minted: .*must bind its state id/);
+  });
+
+  it("invariant 7 fires when releaseSession rejects an unknown session", async () => {
+    await expect(assertLifetimesResolve(await booted(refusesUnknownRelease()))).rejects.toThrow(/broken:refuses-unknown-release: releaseSession for an unknown session rejected/);
+  });
+
+  it("invariant 8 fires when the adapter serializes turns through shared state", async () => {
+    await expect(assertConcurrentTurnsAreIndependent(await booted(serializesTurns()), SHORT_BOUND_MS)).rejects.toThrow(/broken:serializes-turns: runTurn did not settle within 100ms/);
+  });
+});
+
+// ── The driver: the runtime stand-in's own guarantees ───────────────────────
+
+const WRITE_BETA = { kind: "write", resource: "/work/beta.txt" } as const;
+
+describe("harness contract kit self-check — the driver stands in for the runtime faithfully", () => {
+  it("hands the adapter the persisted status on the record AND the sink, as two clones", async () => {
+    const subject = await booted(honest());
+    const driver = new ExecutionDriver(subject, "driver-record");
+    const id = "driver-record-write";
+
+    const first = await driver.turn([scenario.propose(id, WRITE_BETA)]);
+    expect(first.outcome.kind).toBe("awaiting_approval");
+    expect(first.input.execution.status?.messages ?? [], "a first turn's record carries no persisted status").toHaveLength(0);
+    driver.decide(id, ApprovalAction.APPROVE);
+
+    const second = driver.begin([scenario.propose(id, WRITE_BETA)]);
+    const onRecord = second.input.execution.status;
+    expect(onRecord, "the reinvocation's record must carry what the previous turn persisted").toBeDefined();
+    expect(findToolCallRow(onRecord!, id)?.approvalAction, "the decision is on the record's row").toBe(ApprovalAction.APPROVE);
+    expect(findToolCallRow(second.sink.status, id)?.approvalAction, "and on the sink's row").toBe(ApprovalAction.APPROVE);
+    expect(onRecord, "the record's copy and the sink's copy are distinct objects, as after a real persist and read-back").not.toBe(second.sink.status);
+    expect(second.input.approvalDecisions.get(id), "the decisions map is the runtime's reader over the same rows").toBe(ApprovalAction.APPROVE);
+    await second.settled;
+  });
+
+  it("arranges the engine with the driver's ids and the decisions the prompt will carry", async () => {
+    const inner = await booted(honest());
+    const views: EngineView[] = [];
+    const subject: HarnessContractSubject = {
+      ...inner,
+      arrange: (turn, view) => {
+        views.push(view);
+        inner.arrange(turn, view);
+      },
+    };
+    const driver = new ExecutionDriver(subject, "driver-view");
+    const id = "driver-view-write";
+
+    await driver.turn([scenario.propose(id, WRITE_BETA)]);
+    driver.decide(id, ApprovalAction.SKIP);
+    await driver.turn([scenario.propose(id, WRITE_BETA), scenario.say("on")]);
+
+    expect(views.map((v) => v.executionId)).toEqual([driver.executionId, driver.executionId]);
+    expect(views.map((v) => v.sessionId)).toEqual([driver.sessionId, driver.sessionId]);
+    expect(views[0]!.approvalDecisions.size, "nothing decided before the first turn").toBe(0);
+    expect(views[1]!.approvalDecisions.get(id), "the reinvocation's view carries the decision").toBe(ApprovalAction.SKIP);
+  });
+
+  it("stops a turn only once the engine reports it is parked, never during setup", async () => {
+    const inner = await booted(honest());
+    let sinkInFlight: TurnSink | undefined;
+    let abortedWhenParked: boolean | undefined;
+    // Observes the signal at the instant the engine reports the hang; the
+    // driver's own abort is chained after this observer.
+    const subject: HarnessContractSubject = {
+      ...inner,
+      whenHanging: () =>
+        inner.whenHanging().then(() => {
+          abortedWhenParked = sinkInFlight?.stopSignal.aborted;
+        }),
+    };
+    const driver = new ExecutionDriver(subject, "driver-stop");
+
+    const turn = driver.begin([scenario.say("setting up"), scenario.hang(), scenario.say("never")], { stopWhenHanging: "kit: stop" });
+    sinkInFlight = turn.sink;
+    const outcome = await turn.settled;
+
+    expect(outcome.kind).toBe("interrupted");
+    expect(abortedWhenParked, "at the moment the engine reported the hang the signal was still live").toBe(false);
+    expect(turn.sink.stopSignal.aborted, "and it was aborted after").toBe(true);
+    expect(turn.sink.status.messages.map((m) => m.content), "the stop landed in the hang, after the setup step and before the step after it").toEqual(["setting up"]);
+  });
+});

package/src/__test-utils__/config-fixture.ts

@@ -0,0 +1,63 @@
+/**
+ * A complete, inert runner `Config` for tests.
+ *
+ * `Config` has twenty required fields (plus two optional token refs), so
+ * every test that needs one has had to spell all of them out; eight test
+ * files carry their own literal today. This is the one place a test-only `Config` is
+ * built from now on: {@link testConfig} returns the whole record with values
+ * that dial nothing (loopback endpoints on a port nothing listens on, no
+ * proxy, no token, the in-memory checkpointer, a temp workspace root) and
+ * takes a `Partial<Config>` for the fields a test cares about.
+ *
+ * Inert means: a component handed this config may READ every field, but a
+ * component that tries to ACT on one (connect, authenticate, spawn) fails
+ * loudly and immediately rather than reaching a real service. That is the
+ * posture the harness contract kit needs for `HarnessAdapter.boot(config)`,
+ * and the one the existing inline literals were reaching for one at a time.
+ *
+ * Not a `vi.mock`: `Config` is plain data, and a fixture that is plain data
+ * stays type-checked against the real interface, so a field added to `Config`
+ * fails here at `tsc` time instead of at the first test that needed it.
+ */
+
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { Config } from "../config.js";
+import {
+  DEFAULT_CURSOR_AGENT_RESOLVE_TIMEOUT_MS,
+  DEFAULT_CURSOR_STREAM_STALL_TIMEOUT_MS,
+  DEFAULT_WORKSPACE_LOCK_TIMEOUT_MS,
+} from "../config.js";
+
+/**
+ * Loopback on a port nothing listens on, so a component that dials it fails
+ * fast with ECONNREFUSED instead of hanging on a route to nowhere.
+ */
+const INERT_ENDPOINT = "http://127.0.0.1:1";
+
+export function testConfig(overrides: Partial<Config> = {}): Config {
+  return {
+    taskQueue: "test-task-queue",
+    temporalAddress: "127.0.0.1:1",
+    temporalNamespace: "default",
+    stigmerBackendEndpoint: INERT_ENDPOINT,
+    stigmerToken: null,
+    mcpBridgeEndpoint: null,
+    cursorApiKey: "",
+    workspaceRootDir: join(tmpdir(), "stigmer-runner-test-workspaces"),
+    mode: "local",
+    proxyEndpoint: null,
+    maxConcurrentActivities: 1,
+    idleTimeoutSeconds: null,
+    cloudModeEnabled: false,
+    checkpointerType: "memory",
+    checkpointerProxyEndpoint: null,
+    artifactProxyEndpoint: null,
+    primaryModel: "test-model",
+    cursorStreamStallTimeoutMs: DEFAULT_CURSOR_STREAM_STALL_TIMEOUT_MS,
+    agentResolveTimeoutMs: DEFAULT_CURSOR_AGENT_RESOLVE_TIMEOUT_MS,
+    workspaceLockTimeoutMs: DEFAULT_WORKSPACE_LOCK_TIMEOUT_MS,
+    ...overrides,
+  };
+}

package/src/__test-utils__/execution-record-fixture.ts

@@ -0,0 +1,104 @@
+/**
+ * The four resources of one execution, wired by id into the chain the turn
+ * runtime resolves (`execution.spec.sessionId` → `session.spec.
+ * agentInstanceId` → `agentInstance.spec.agentId` → the agent), as an
+ * `ExecutionRecord` the hermetic client answers from.
+ *
+ * Harness-agnostic: the record is the control plane's, and the runtime's
+ * phases read it the same way whatever engine runs the turn. A harness's
+ * driver supplies its own fixture ids and model (`execute-cursor/__test-
+ * utils__/hermetic-cursor.ts` `cursorExecutionRecord`); the runtime's own
+ * tests use the defaults. Ids are fixed so goldens are readable and
+ * byte-stable.
+ */
+
+import { create } from "@bufbuild/protobuf";
+import { AgentExecutionSchema, type AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { AgentExecutionSpecSchema, ExecutionConfigSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+import { SessionSchema, type Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import { SessionSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/spec_pb";
+import type { WorkspaceEntry } from "@stigmer/protos/ai/stigmer/agentic/session/v1/workspace_pb";
+import { AgentSchema, type Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import { AgentInstanceSchema, type AgentInstance } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/api_pb";
+import { AgentInstanceSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/spec_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+
+import { ExecutionRecord, type ExecutionRecordInput } from "./hermetic-activity.js";
+import { FIXTURE_MODEL } from "./model-registry-fixture.js";
+
+/** The ids a record's four resources carry. */
+export interface ExecutionRecordIds {
+  readonly org: string;
+  readonly executionId: string;
+  readonly sessionId: string;
+  readonly agentInstanceId: string;
+  readonly agentId: string;
+  readonly agentName: string;
+}
+
+export const DEFAULT_RECORD_IDS: ExecutionRecordIds = {
+  org: "hermetic-org",
+  executionId: "aex_hermetic_0001",
+  sessionId: "ses_hermetic_0001",
+  agentInstanceId: "ain_hermetic_0001",
+  agentId: "agt_hermetic_0001",
+  agentName: "hermetic-agent",
+};
+
+export interface ExecutionRecordOptions {
+  /** The user's message for this execution. */
+  readonly message: string;
+  /** The agent's instructions (system prompt body). */
+  readonly instructions?: string;
+  /** Session workspace entries (a `local_path` entry turns on capture mode). */
+  readonly workspaceEntries?: WorkspaceEntry[];
+  /** The requested model; the pinned fixture model when omitted. */
+  readonly modelName?: string;
+  readonly autoApproveAll?: boolean;
+  /**
+   * `ExecutionConfig.max_cost_usd`: the per-message cost budget the runtime
+   * enforces as a hard stop (cost-guard.ts). Omitted or 0 = no cap, the
+   * proto's default. Priced against the registry fixture's round numbers, so
+   * a scenario can state its overrun exactly (600 000 input tokens = $0.60).
+   */
+  readonly maxCostUsd?: number;
+  /** The control plane's STOP lever; see `ExecutionRecordInput.controlSignal`. */
+  readonly controlSignal?: ExecutionRecordInput["controlSignal"];
+  readonly ids?: ExecutionRecordIds;
+}
+
+export function executionRecordFixture(options: ExecutionRecordOptions): ExecutionRecord {
+  const ids = options.ids ?? DEFAULT_RECORD_IDS;
+  const execution: AgentExecution = create(AgentExecutionSchema, {
+    metadata: create(ApiResourceMetadataSchema, { id: ids.executionId, org: ids.org, name: ids.executionId }),
+    spec: create(AgentExecutionSpecSchema, {
+      sessionId: ids.sessionId,
+      message: options.message,
+      autoApproveAll: options.autoApproveAll ?? false,
+      executionConfig: create(ExecutionConfigSchema, {
+        modelName: options.modelName ?? FIXTURE_MODEL,
+        maxCostUsd: options.maxCostUsd ?? 0,
+      }),
+    }),
+  });
+  const session: Session = create(SessionSchema, {
+    metadata: create(ApiResourceMetadataSchema, { id: ids.sessionId, org: ids.org, name: ids.sessionId }),
+    spec: create(SessionSpecSchema, {
+      agentInstanceId: ids.agentInstanceId,
+      workspaceEntries: options.workspaceEntries ?? [],
+    }),
+  });
+  const agentInstance: AgentInstance = create(AgentInstanceSchema, {
+    metadata: create(ApiResourceMetadataSchema, { id: ids.agentInstanceId, org: ids.org, name: ids.agentInstanceId }),
+    spec: create(AgentInstanceSpecSchema, { agentId: ids.agentId }),
+  });
+  const agent: Agent = create(AgentSchema, {
+    metadata: create(ApiResourceMetadataSchema, { id: ids.agentId, org: ids.org, name: ids.agentName }),
+    spec: create(AgentSpecSchema, {
+      description: "Hermetic fixture agent",
+      instructions: options.instructions ?? "You are the hermetic fixture agent. Answer briefly.",
+    }),
+  });
+  return new ExecutionRecord({ execution, session, agentInstance, agent, controlSignal: options.controlSignal });
+}