@stigmer/runner 3.14.1 → 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.1",
+  "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.1",
-    "@stigmer/temporal-codecs": "3.14.1",
-    "@stigmer/zip-structure": "3.14.1",
+    "@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

@@ -13,7 +13,16 @@
  * 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.
+ * 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";
@@ -22,6 +31,7 @@ import { ApprovalAction, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agent
 
 import type { HarnessAdapter, TurnInput, TurnOutcome, TurnSink } from "../../harness/types.js";
 import {
+  ExecutionDriver,
   assertConcurrentTurnsAreIndependent,
   assertDecisionsExecuteExactlyOnce,
   assertEveryExitIsAnOutcome,
@@ -33,13 +43,21 @@ import {
 } from "../harness-contract/contract.js";
 import { scriptedSubject } from "../harness-contract/scripted-adapter.js";
 import type { ScriptedSubject } from "../harness-contract/scripted-adapter.js";
-import type { HarnessContractSubject, TurnScenario } from "../harness-contract/types.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 {
@@ -58,9 +76,11 @@ function sinkOver(inner: TurnSink, patch: Partial<TurnSink>): TurnSink {
   return {
     status: inner.status,
     stopSignal: inner.stopSignal,
+    setupTiming: inner.setupTiming,
     requestPersist: () => inner.requestPersist(),
-    recordActivity: () => inner.recordActivity(),
+    recordActivity: (detail) => inner.recordActivity(detail),
     reportUsage: (delta) => inner.reportUsage(delta),
+    reportProgress: (label) => inner.reportProgress(label),
     bindHarnessState: (id) => inner.bindHarnessState(id),
     ...patch,
   };
@@ -70,9 +90,11 @@ function sinkOver(inner: TurnSink, patch: Partial<TurnSink>): TurnSink {
 function subjectOver(inner: ScriptedSubject, adapter: HarnessAdapter): HarnessContractSubject {
   return {
     name: adapter.name,
+    harness: inner.harness,
     adapter,
     config: inner.config,
-    arrange: (turn) => inner.arrange(turn),
+    arrange: (turn, view) => inner.arrange(turn, view),
+    whenHanging: () => inner.whenHanging(),
     executionCount: (toolCallId) => inner.executionCount(toolCallId),
   };
 }
@@ -106,9 +128,9 @@ function executesUndecidedProposals(): HarnessContractSubject {
   });
   return {
     ...subjectOver(inner, adapter),
-    arrange: (turn: TurnScenario) => {
+    arrange: (turn: TurnScenario, view: EngineView) => {
       proposedIds = turn.flatMap((step) => (step.kind === "propose" ? [step.toolCallId] : []));
-      inner.arrange(turn);
+      inner.arrange(turn, view);
     },
   };
 }
@@ -196,34 +218,108 @@ function serializesTurns(): HarnessContractSubject {
 
 describe("harness contract kit self-check — every invariant can fail", () => {
   it("invariant 1 fires when runTurn throws a CancelledFailure", async () => {
-    await expect(assertEveryExitIsAnOutcome(throwsCancelledFailure(), SHORT_BOUND_MS)).rejects.toThrow(/broken:throws-CancelledFailure: runTurn rejected with a CancelledFailure/);
+    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(executesUndecidedProposals())).rejects.toThrow(/broken:executes-undecided: .*awaiting_approval/);
+    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(reGatesSettledRows())).rejects.toThrow(/broken:re-gates-settled: .*must not re-gate/);
+    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(ignoresStopSignal(), SHORT_BOUND_MS)).rejects.toThrow(/broken:ignores-stopSignal: runTurn did not settle within 100ms/);
+    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(reportsCumulativeUsage())).rejects.toThrow(/broken:cumulative-usage: .*must sum to what the engine emitted/);
+    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(claimsEngineMintedNeverBinds())).rejects.toThrow(/broken:claims-engine-minted: .*must bind its state id/);
+    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(refusesUnknownRelease())).rejects.toThrow(/broken:refuses-unknown-release: releaseSession for an unknown session rejected/);
+    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(serializesTurns(), SHORT_BOUND_MS)).rejects.toThrow(/broken:serializes-turns: runTurn did not settle within 100ms/);
+    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__/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 });
+}

package/src/__test-utils__/harness-boot-order-child.ts

@@ -0,0 +1,58 @@
+/**
+ * The child entry `__tests__/harness-boot-order.test.ts` spawns: one FRESH
+ * Node process that does exactly what the composition roots do before
+ * bootstrap — import `harness-adapters.js` and `harness/registry.js`, then
+ * `bootHarnesses` on a proxy-mode config — and reports how it went.
+ *
+ * Why a child process: the `node:http2` ESM facade is snapshotted once per
+ * process at its first import, so the positive load-order contract ("the
+ * patch reached the facade") cannot be observed inside a shared vitest
+ * worker that has already imported half the runner. A fresh process is the
+ * only honest instrument (`http2-interceptor.test.ts` says as much).
+ *
+ * Arms (argv[2]):
+ *  - `boot`: import the two pre-boot modules, boot with a proxy endpoint and
+ *    a bound token ref. Success means the pre-boot graph was connect-free,
+ *    both interceptors installed, `assertHttp2ConnectPatched` passed, and the
+ *    SDK slice loaded from inside `boot`.
+ *  - `boot-after-connect-node`: the same, after importing the Stigmer client
+ *    (connect-node) FIRST. Must fail with the facade sentence: proves the
+ *    guard is live inside `boot`, so a future regression is loud.
+ *
+ * Output: one line, `harness-boot-order: ok` or `harness-boot-order: <message>`,
+ * then exit 0 on success and 1 on a rejection. The proxy endpoint is an inert
+ * loopback nothing listens on; boot dials nothing.
+ */
+
+import { testConfig } from "./config-fixture.js";
+
+const arm = process.argv[2];
+
+async function main(): Promise<void> {
+  if (arm === "boot-after-connect-node") {
+    await import("../client/stigmer-client.js");
+  } else if (arm !== "boot") {
+    throw new Error(`harness-boot-order-child: unknown arm '${String(arm)}' (expected 'boot' or 'boot-after-connect-node')`);
+  }
+
+  const [{ HARNESS_ADAPTERS }, { adaptersOf, bootHarnesses }] = await Promise.all([
+    import("../harness-adapters.js"),
+    import("../harness/registry.js"),
+  ]);
+  const config = testConfig({
+    proxyEndpoint: "http://127.0.0.1:1",
+    proxyTokenRef: { current: "boot-order-test-token" },
+  });
+  await bootHarnesses(adaptersOf(HARNESS_ADAPTERS), config);
+}
+
+main().then(
+  () => {
+    process.stdout.write("harness-boot-order: ok\n");
+    process.exit(0);
+  },
+  (err: unknown) => {
+    process.stdout.write(`harness-boot-order: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+  },
+);