@stigmer/runner 3.14.0 → 3.14.1

package/src/activities/execute-cursor/__tests__/hermetic/recovery-fresh-agent.test.ts

@@ -0,0 +1,156 @@
+/**
+ * Hermetic golden: POISONED-HANDLE RECOVERY — a resumed agent whose run fails
+ * with a transport error is replaced by a fresh agent, once, and the turn
+ * completes on the replacement.
+ *
+ * Invariant pinned: when `run.wait()` reports `error` on an agent that was
+ * RESUMED (`resolution.reason === "resumed_successfully"`) and the classifier
+ * files the error as `network` or `agent-stale`, the activity closes the stale
+ * handle, calls `Agent.create` for a fresh one, writes the fresh id to the
+ * session's `harness_state_id`, re-runs the turn on the fresh agent through the
+ * IDENTICAL stream loop and boundary, and ends COMPLETED. The retry happens at
+ * most once (`alreadyRetriedWithFreshAgent`). The golden
+ * (`goldens/recovery-fresh-agent.status.json`) pins what the user sees after a
+ * recovered turn.
+ *
+ * Parent phase rows exercised beyond the earlier scenarios: `Agent.resume`
+ * through `resolveAgentWithTransportRecovery` (a second execution in a session:
+ * `thread_id` set, no parked agent); the `status: ERROR` stream event feeding
+ * `streamErrorMessage`; `run.wait()` error mapping; the error classifier
+ * (`error-classifier.ts` NETWORK_PATTERNS, the same shapes its own tests pin);
+ * the fresh-agent recovery spine (`runRecoveryStream`); the second
+ * `harness_state_id` write-back.
+ *
+ * Regenerate ONLY after a deliberate behavior change:
+ *   npx vitest run src/activities/execute-cursor/__tests__/hermetic -u
+ */
+
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { toJson } from "@bufbuild/protobuf";
+import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+vi.mock("@cursor/sdk", async () =>
+  (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSdkModule(),
+);
+vi.mock("../../../../client/stigmer-client.js", async () =>
+  (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
+);
+
+import {
+  ScriptedClock,
+  createHermeticEnvironment,
+  type HermeticEnvironment,
+} from "../../../../__test-utils__/hermetic-activity.js";
+import { ScriptedCursorAgent, sdkEvents, step } from "../../__test-utils__/scripted-agent.js";
+import {
+  FIXTURE,
+  SDK_CATALOG,
+  beginCursorScenario,
+  cursorExecutionRecord,
+  runCursorTurn,
+  stubRegistryFetch,
+} from "../../__test-utils__/hermetic-cursor.js";
+
+const STALE_AGENT_ID = "agent-hermetic-stale-0001";
+const FRESH_AGENT_ID = "agent-hermetic-fresh-0002";
+const RUN_STALE = "run-hermetic-stale-0001";
+const RUN_FRESH = "run-hermetic-fresh-0001";
+const USER_MESSAGE = "Summarize what changed since yesterday.";
+// A real network-class failure shape (error-classifier NETWORK_PATTERNS:
+// "unavailable", "econnreset", "fetch failed").
+const TRANSPORT_ERROR = "UNAVAILABLE: fetch failed (ECONNRESET) while streaming the run";
+const FINAL_TEXT = "Two files changed since yesterday: notes.md and README.md.";
+
+describe("ExecuteCursor hermetic — poisoned-handle recovery on a fresh agent", () => {
+  let env: HermeticEnvironment;
+  let registry: ReturnType<typeof stubRegistryFetch>;
+  const clock = new ScriptedClock();
+
+  beforeAll(() => {
+    env = createHermeticEnvironment();
+    registry = stubRegistryFetch();
+    clock.install();
+  });
+
+  afterAll(() => {
+    clock.uninstall();
+    registry.restore();
+    env.dispose();
+  });
+
+  it("replaces the stale resumed agent once and completes on the fresh one", async () => {
+    // ── Arrange ──────────────────────────────────────────────────────────────
+    const evStale = sdkEvents(STALE_AGENT_ID, RUN_STALE);
+    const evFresh = sdkEvents(FRESH_AGENT_ID, RUN_FRESH);
+    const stale = new ScriptedCursorAgent({
+      agentId: STALE_AGENT_ID,
+      runIds: [RUN_STALE],
+      observeStep: () => clock.tick(),
+      turns: [
+        [
+          step.event(evStale.init()),
+          step.event(evStale.assistant("Let me look at the recent changes.")),
+          step.event(evStale.status("ERROR", TRANSPORT_ERROR)),
+          step.errored({ result: TRANSPORT_ERROR }),
+        ],
+      ],
+    });
+    const fresh = new ScriptedCursorAgent({
+      agentId: FRESH_AGENT_ID,
+      runIds: [RUN_FRESH],
+      observeStep: () => clock.tick(),
+      turns: [
+        [
+          step.event(evFresh.init()),
+          step.event(evFresh.assistant(FINAL_TEXT)),
+          step.turnEnded({ inputTokens: 2_800, outputTokens: 55 }),
+          step.finished({ result: FINAL_TEXT, model: { id: FIXTURE.model, params: [] } }),
+        ],
+      ],
+    });
+    const record = cursorExecutionRecord({ message: USER_MESSAGE });
+    const scenario = beginCursorScenario({
+      env,
+      clock,
+      record,
+      // `Agent.create` hands out `fresh`; `Agent.resume(STALE)` finds `stale`,
+      // the previous turn's agent the session knows only by harness_state_id.
+      sdk: { agents: [fresh], resumableAgents: [stale], catalog: SDK_CATALOG },
+    });
+
+    // ── Act: the second execution in the session resumes the stale handle ────
+    const invocation = await runCursorTurn(scenario, { threadId: STALE_AGENT_ID, turnSeq: 0 });
+
+    // ── Assert: outcome ──────────────────────────────────────────────────────
+    expect(invocation.outcome.kind, "a recovered turn RETURNS like any completion").toBe("returned");
+    const slim = (invocation.outcome as { value: Record<string, unknown> }).value;
+    expect(slim.phase).toBe("EXECUTION_COMPLETED");
+    expect(slim.final_text).toBe(FINAL_TEXT);
+    expect(record.persistedPhases).toEqual([
+      ExecutionPhase.EXECUTION_IN_PROGRESS,
+      ExecutionPhase.EXECUTION_COMPLETED,
+    ]);
+
+    // ── Assert: the recovery spine ───────────────────────────────────────────
+    expect(scenario.sdk.resolutions.map((r) => [r.kind, r.agentId])).toEqual([
+      ["resume", STALE_AGENT_ID],
+      ["create", FRESH_AGENT_ID],
+    ]);
+    expect(stale.sends, "the stale handle ran exactly once").toHaveLength(1);
+    expect(stale.closeCalls, "the poisoned handle is disposed").toBe(1);
+    expect(fresh.sends, "the fresh agent ran the turn exactly once — no second retry").toHaveLength(1);
+    expect(String(fresh.sends[0].message), "the rebuilt prompt carries the user's message").toContain(USER_MESSAGE);
+
+    // The session now points at the fresh agent (the stale id is superseded).
+    const lastSessionWrite = record.sessionUpdates.at(-1);
+    expect(lastSessionWrite?.spec?.harnessStateId).toBe(FRESH_AGENT_ID);
+
+    // ── Assert: hermeticity ──────────────────────────────────────────────────
+    expect(registry.urls.every((u) => u.includes("/model-registry"))).toBe(true);
+
+    // ── Assert: the golden ───────────────────────────────────────────────────
+    const json = JSON.stringify(toJson(AgentExecutionStatusSchema, record.lastFullStatus!), null, 2) + "\n";
+    await expect(json).toMatchFileSnapshot("./goldens/recovery-fresh-agent.status.json");
+  });
+});

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

@@ -0,0 +1,137 @@
+/**
+ * Hermetic golden: a turn with an UNGATED TOOL CALL through the whole
+ * `ExecuteCursor` activity.
+ *
+ * Invariant pinned: a `tool_call` the SDK streams as `running` and then
+ * `completed` folds into exactly one `ToolCall` row on the AI message — id from
+ * `call_id`, name from the stream taxonomy, `args` + `argsPreview` from the
+ * event's args, `result` from the completed event, `startedAt`/`completedAt`
+ * from the two events' instants, `toolKind` classified, no approval fields set
+ * (a read-only built-in is not gated) — and the turn ends COMPLETED. The golden
+ * (`goldens/tool-call.status.json`) is the row shape S4's canonical transcript
+ * builder must reproduce byte for byte.
+ *
+ * Parent phase rows exercised beyond `plain-turn`: run the turn and consume
+ * the engine stream (tool-call folding in `message-translator.ts`); the turn
+ * boundary with nothing to gate or capture (a read tool writes no file; the
+ * per-session workspace is unchanged, so the capture finds no candidate).
+ *
+ * Regenerate ONLY after a deliberate behavior change:
+ *   npx vitest run src/activities/execute-cursor/__tests__/hermetic -u
+ */
+
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { toJson } from "@bufbuild/protobuf";
+import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionPhase, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+vi.mock("@cursor/sdk", async () =>
+  (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSdkModule(),
+);
+vi.mock("../../../../client/stigmer-client.js", async () =>
+  (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
+);
+
+import {
+  ScriptedClock,
+  createHermeticEnvironment,
+  type HermeticEnvironment,
+} from "../../../../__test-utils__/hermetic-activity.js";
+import { ScriptedCursorAgent, sdkEvents, step } from "../../__test-utils__/scripted-agent.js";
+import {
+  FIXTURE,
+  SDK_CATALOG,
+  beginCursorScenario,
+  cursorExecutionRecord,
+  runCursorTurn,
+  stubRegistryFetch,
+} from "../../__test-utils__/hermetic-cursor.js";
+
+const AGENT_ID = "agent-hermetic-tool-0001";
+const RUN_ID = "run-hermetic-tool-0001";
+const CALL_ID = "call-hermetic-read-0001";
+const USER_MESSAGE = "What is in README.md?";
+const READ_ARGS = { path: "README.md" };
+const READ_RESULT = "# Hermetic\n\nA fixture readme.\n";
+const ASSISTANT_TEXT = "README.md holds a one-line fixture description.";
+
+describe("ExecuteCursor hermetic — ungated tool call", () => {
+  let env: HermeticEnvironment;
+  let registry: ReturnType<typeof stubRegistryFetch>;
+  const clock = new ScriptedClock();
+
+  beforeAll(() => {
+    env = createHermeticEnvironment();
+    registry = stubRegistryFetch();
+    clock.install();
+  });
+
+  afterAll(() => {
+    clock.uninstall();
+    registry.restore();
+    env.dispose();
+  });
+
+  it("folds running -> completed into one COMPLETED tool-call row and completes", async () => {
+    // ── Arrange ──────────────────────────────────────────────────────────────
+    const ev = sdkEvents(AGENT_ID, RUN_ID);
+    const agent = new ScriptedCursorAgent({
+      agentId: AGENT_ID,
+      runIds: [RUN_ID],
+      observeStep: () => clock.tick(),
+      turns: [
+        [
+          step.event(ev.init()),
+          step.event(ev.assistant("Let me read it.")),
+          step.event(ev.toolCall(CALL_ID, "read", "running", READ_ARGS)),
+          step.event(ev.toolCall(CALL_ID, "read", "completed", READ_ARGS, READ_RESULT)),
+          step.event(ev.assistant(ASSISTANT_TEXT)),
+          step.turnEnded({ inputTokens: 2_000, outputTokens: 90 }),
+          step.finished({ result: ASSISTANT_TEXT, model: { id: FIXTURE.model, params: [] } }),
+        ],
+      ],
+    });
+    const record = cursorExecutionRecord({ message: USER_MESSAGE });
+    const scenario = beginCursorScenario({
+      env,
+      clock,
+      record,
+      sdk: { agents: [agent], catalog: SDK_CATALOG },
+    });
+
+    // ── Act ──────────────────────────────────────────────────────────────────
+    const invocation = await runCursorTurn(scenario);
+
+    // ── Assert: outcome and phases ───────────────────────────────────────────
+    expect(invocation.outcome.kind).toBe("returned");
+    const slim = (invocation.outcome as { value: Record<string, unknown> }).value;
+    expect(slim.phase).toBe("EXECUTION_COMPLETED");
+    expect(slim.final_text).toBe(ASSISTANT_TEXT);
+    expect(record.persistedPhases).toEqual([
+      ExecutionPhase.EXECUTION_IN_PROGRESS,
+      ExecutionPhase.EXECUTION_COMPLETED,
+    ]);
+
+    // ── Assert: the one tool-call row ────────────────────────────────────────
+    const rows = record.toolCalls();
+    expect(rows, "running + completed fold into ONE row, never two").toHaveLength(1);
+    const row = rows[0];
+    expect(row.id).toBe(CALL_ID);
+    expect(row.name).toBe("read");
+    expect(row.status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+    expect(row.args).toEqual(READ_ARGS);
+    expect(row.result).toBe(READ_RESULT);
+    expect(row.requiresApproval, "a read-only built-in is not gated").toBe(false);
+    expect(row.startedAt < row.completedAt, "started before completed on the scripted clock").toBe(true);
+
+    // ── Assert: hermeticity ──────────────────────────────────────────────────
+    expect(registry.urls.every((u) => u.includes("/model-registry"))).toBe(true);
+    expect(agent.runs[0].cancelCalls, "an ungated turn is never cancelled").toHaveLength(0);
+
+    // ── Assert: the golden ───────────────────────────────────────────────────
+    const finalStatus = record.lastFullStatus;
+    expect(finalStatus).toBeDefined();
+    const json = JSON.stringify(toJson(AgentExecutionStatusSchema, finalStatus!), null, 2) + "\n";
+    await expect(json).toMatchFileSnapshot("./goldens/tool-call.status.json");
+  });
+});

package/src/harness/__tests__/registry.test.ts

@@ -0,0 +1,167 @@
+/**
+ * Pins the harness registry's two load-bearing properties — ORDER and ERROR
+ * POSTURE — and the byte-pinned activity names.
+ *
+ * Order: boot in declaration order, one at a time (the Cursor interceptors
+ * must precede anything that dials the control plane); shutdown in reverse.
+ * Posture: boot validates the table before touching any adapter and fails
+ * fast at the first rejection; shutdown and release continue past a failing
+ * adapter and surface every failure in one AggregateError. Names: the map
+ * must equal the server's constants byte for byte; the runner cannot import
+ * the server, so the literals are asserted here and the server's file is
+ * cited beside them.
+ */
+
+import { describe, it, expect } from "vitest";
+
+import { testConfig } from "../../__test-utils__/config-fixture.js";
+import { DEEP_AGENT_VISION_PROFILE } from "../../shared/attachment-vision.js";
+import { HARNESS_ACTIVITY_NAMES, bootHarnesses, releaseHarnessSession, shutdownHarnesses } from "../registry.js";
+import type { HarnessAdapter } from "../types.js";
+
+interface StubBehaviour {
+  readonly bootRejects?: Error;
+  readonly shutdownRejects?: Error;
+  readonly releaseRejects?: Error;
+}
+
+/** An adapter that only records lifecycle calls into a shared, ordered log. */
+function stubAdapter(name: string, log: string[], behaviour: StubBehaviour = {}): HarnessAdapter {
+  return {
+    name,
+    capabilities: {
+      pausePrimitive: "interrupt",
+      stateIdSource: "deterministic",
+      systemPrompt: true,
+      subAgents: false,
+      toolRestriction: true,
+      visionProfile: DEEP_AGENT_VISION_PROFILE,
+    },
+    async boot() {
+      log.push(`boot:${name}`);
+      if (behaviour.bootRejects) throw behaviour.bootRejects;
+    },
+    async shutdown() {
+      log.push(`shutdown:${name}`);
+      if (behaviour.shutdownRejects) throw behaviour.shutdownRejects;
+    },
+    async releaseSession(sessionId) {
+      log.push(`release:${name}:${sessionId}`);
+      if (behaviour.releaseRejects) throw behaviour.releaseRejects;
+    },
+    async runTurn() {
+      throw new Error(`${name}: runTurn is not under test here`);
+    },
+  };
+}
+
+describe("HARNESS_ACTIVITY_NAMES", () => {
+  it("equals the server's byte-pinned activity names (stigmer-server temporal/agentexecution/names.ts)", () => {
+    expect(HARNESS_ACTIVITY_NAMES.cursor).toBe("ExecuteCursor");
+    expect(HARNESS_ACTIVITY_NAMES["deep-agent"]).toBe("ExecuteDeepAgent");
+    expect(Object.keys(HARNESS_ACTIVITY_NAMES).sort()).toEqual(["cursor", "deep-agent"]);
+  });
+});
+
+describe("bootHarnesses", () => {
+  it("boots adapters in declaration order, one at a time", async () => {
+    const log: string[] = [];
+    await bootHarnesses([stubAdapter("first", log), stubAdapter("second", log), stubAdapter("third", log)], testConfig());
+    expect(log).toEqual(["boot:first", "boot:second", "boot:third"]);
+  });
+
+  it("hands every adapter the same config", async () => {
+    const seen: unknown[] = [];
+    const config = testConfig({ taskQueue: "registry-test-queue" });
+    const adapters = ["a", "b"].map((name) => ({
+      ...stubAdapter(name, []),
+      async boot(c: unknown) {
+        seen.push(c);
+      },
+    }));
+    await bootHarnesses(adapters, config);
+    expect(seen, "each adapter must receive the one worker config").toEqual([config, config]);
+  });
+
+  it("refuses duplicate adapter names before booting anything", async () => {
+    const log: string[] = [];
+    const adapters = [stubAdapter("cursor", log), stubAdapter("other", log), stubAdapter("cursor", log)];
+    await expect(bootHarnesses(adapters, testConfig())).rejects.toThrow(/duplicate adapter name 'cursor'/);
+    expect(log, "a table with a duplicate must not boot even its first adapter").toEqual([]);
+  });
+
+  it("fails fast: the first rejection propagates and later adapters never boot", async () => {
+    const log: string[] = [];
+    const adapters = [
+      stubAdapter("first", log),
+      stubAdapter("broken", log, { bootRejects: new Error("interceptor install failed") }),
+      stubAdapter("third", log),
+    ];
+    await expect(bootHarnesses(adapters, testConfig())).rejects.toThrow("interceptor install failed");
+    expect(log).toEqual(["boot:first", "boot:broken"]);
+  });
+
+  it("boots an empty table as a no-op", async () => {
+    await expect(bootHarnesses([], testConfig())).resolves.toBeUndefined();
+  });
+});
+
+describe("shutdownHarnesses", () => {
+  it("shuts adapters down in reverse declaration order", async () => {
+    const log: string[] = [];
+    await shutdownHarnesses([stubAdapter("first", log), stubAdapter("second", log), stubAdapter("third", log)]);
+    expect(log).toEqual(["shutdown:third", "shutdown:second", "shutdown:first"]);
+  });
+
+  it("continues past a failing adapter and reports every failure in one AggregateError", async () => {
+    const log: string[] = [];
+    const adapters = [
+      stubAdapter("first", log, { shutdownRejects: new Error("first leaked") }),
+      stubAdapter("second", log),
+      stubAdapter("third", log, { shutdownRejects: new Error("third leaked") }),
+    ];
+    const failure = await shutdownHarnesses(adapters).catch((e: unknown) => e);
+    expect(failure).toBeInstanceOf(AggregateError);
+    const aggregate = failure as AggregateError;
+    expect(aggregate.message).toContain("third: shutdown rejected: third leaked");
+    expect(aggregate.message).toContain("first: shutdown rejected: first leaked");
+    expect(aggregate.errors.map((e: Error) => e.message)).toEqual([
+      "third: shutdown rejected: third leaked",
+      "first: shutdown rejected: first leaked",
+    ]);
+    expect(log, "every adapter must be shut down even when an earlier one failed").toEqual([
+      "shutdown:third",
+      "shutdown:second",
+      "shutdown:first",
+    ]);
+  });
+
+  it("preserves the original error as the cause of each reported failure", async () => {
+    const original = new Error("socket already closed");
+    const failure = await shutdownHarnesses([stubAdapter("only", [], { shutdownRejects: original })]).catch((e: unknown) => e);
+    expect((failure as AggregateError).errors[0]?.cause).toBe(original);
+  });
+});
+
+describe("releaseHarnessSession", () => {
+  it("tells every adapter, in declaration order, with the session id", async () => {
+    const log: string[] = [];
+    await releaseHarnessSession([stubAdapter("first", log), stubAdapter("second", log)], "ses-42");
+    expect(log).toEqual(["release:first:ses-42", "release:second:ses-42"]);
+  });
+
+  it("continues past a failing adapter and reports the failure with the session id", async () => {
+    const log: string[] = [];
+    const adapters = [
+      stubAdapter("first", log, { releaseRejects: new Error("executor busy") }),
+      stubAdapter("second", log),
+    ];
+    const failure = await releaseHarnessSession(adapters, "ses-7").catch((e: unknown) => e);
+    expect(failure).toBeInstanceOf(AggregateError);
+    expect((failure as AggregateError).message).toContain("releaseSession('ses-7') failed");
+    expect((failure as AggregateError).errors.map((e: Error) => e.message)).toEqual([
+      "first: releaseSession('ses-7') rejected: executor busy",
+    ]);
+    expect(log).toEqual(["release:first:ses-7", "release:second:ses-7"]);
+  });
+});

package/src/harness/capabilities.ts

@@ -0,0 +1,75 @@
+/**
+ * Harness capability flags — the facts about an engine the runtime branches
+ * on, declared once per adapter and read nowhere else.
+ *
+ * The runtime is written against the flags, not against harness names: a
+ * phase that must differ per engine asks "does this harness accept a system
+ * prompt?" rather than "is this Cursor?". That is what keeps a new harness a
+ * registry row and an SDK slice instead of a new branch in every phase.
+ * Every row of the matrix below is either a flag here or internal to one
+ * adapter; nothing in it needed a third kind of thing.
+ *
+ * The matrix the contract was designed against (2026-09; Claude and Codex are
+ * the surveyed SDKs, not built harnesses):
+ *
+ * | Capability        | Native (LangGraph)          | Cursor (`@cursor/sdk`)                  | Claude (`@anthropic-ai/claude-agent-sdk`)     | Codex (`@openai/codex-sdk`)                    |
+ * |-------------------|-----------------------------|-----------------------------------------|-----------------------------------------------|------------------------------------------------|
+ * | `pausePrimitive`  | `interrupt` (checkpoint)    | `deny-and-retry` (hook, ledger, cancel) | `callback` (`canUseTool`, in-process)         | `none` (approvalPolicy only) → capture-only    |
+ * | `stateIdSource`   | `deterministic` (thread id) | `engine-minted` (agent id)              | either (caller-supplied or minted)            | `engine-minted` (thread id)                    |
+ * | `systemPrompt`    | yes                         | no (rides the first message)            | yes                                           | no (`AGENTS.md` or first message)              |
+ * | `subAgents`       | yes (compiled sub-graphs)   | yes (`agents` option)                   | yes (`AgentDefinition`)                       | no                                             |
+ * | `toolRestriction` | yes (tool list)             | no (the hook enforces)                  | yes (`disallowedTools`, `tools`)              | per-server config                              |
+ * | `visionProfile`   | PNG, JPEG, WebP, GIF        | PNG, JPEG (transport re-sniffs)         | (surveyed later)                              | (surveyed later)                               |
+ *
+ * Adapter-internal, deliberately NOT flags: how MCP servers are bound, how
+ * metering is routed, how the cost cap is applied inside the engine, how a
+ * run is cancelled. Those differ per engine but the runtime never needs to
+ * know.
+ *
+ * Two flags matter to the contract kit directly: `pausePrimitive` (the kit
+ * proves the two real primitives are indistinguishable above the contract
+ * line — both end a turn `awaiting_approval` and both take the decisions on
+ * reinvocation) and `stateIdSource` (an `engine-minted` adapter must bind its
+ * id before its first persist; a `deterministic` one must never bind).
+ */
+
+import type { VisionProfile } from "../shared/attachment-vision.js";
+
+/**
+ * How the engine can be made to stop before a gated side effect.
+ *
+ *  - `interrupt`: the engine checkpoints and stops at the gate (LangGraph
+ *    `interrupt`); the adapter resumes it with the decisions.
+ *  - `deny-and-retry`: an out-of-process hook denies the tool, the adapter
+ *    records the denial, cancels the run, and re-runs with grants on the next
+ *    invocation.
+ *  - `callback`: an in-process callback decides per tool; the runtime still
+ *    returns `awaiting_approval` and reinvokes, so the adapter answers the
+ *    callback with "deny, stop" and resumes with the decisions.
+ *  - `none`: the engine offers no gate; the runtime confines it to
+ *    capture-only work (a read-only sandbox) and gated actions never reach
+ *    the engine.
+ */
+export type PausePrimitive = "interrupt" | "deny-and-retry" | "callback" | "none";
+
+/**
+ * Who mints the engine's state id. `deterministic`: the runtime derives it
+ * from the session before the first turn (`EnsureThread`), so it is known
+ * before any engine exists. `engine-minted`: the engine issues it on first
+ * use and the adapter must hand it to the runtime at once
+ * (`TurnSink.bindHarnessState`) so a crash mid-turn still resumes.
+ */
+export type StateIdSource = "deterministic" | "engine-minted";
+
+export interface HarnessCapabilities {
+  readonly pausePrimitive: PausePrimitive;
+  readonly stateIdSource: StateIdSource;
+  /** The engine accepts a system prompt; otherwise instructions ride the first user message. */
+  readonly systemPrompt: boolean;
+  /** The engine runs delegated sub-agents from a definition map. */
+  readonly subAgents: boolean;
+  /** The engine can hide or deny tools by name; otherwise the gate enforces `enabledTools`. */
+  readonly toolRestriction: boolean;
+  /** Which image types the engine can display inline; the runtime degrades the rest before the turn. */
+  readonly visionProfile: VisionProfile;
+}

package/src/harness/registry.ts

@@ -0,0 +1,123 @@
+/**
+ * The harness registry — the lifecycle fan-out over the adapters a worker
+ * runs, and the byte-pinned binding from harness to Temporal activity name.
+ *
+ * Plain functions over an `adapters` argument, no module state and no DI
+ * (the composition roots are staged plain functions; a missing adapter is a
+ * compile error or a loud boot throw, never a silent no-op). ORDER IS
+ * LOAD-BEARING: `bootHarnesses` runs adapters in declaration order because
+ * the Cursor harness's interceptors must patch `node:http2` before anything
+ * dials the control plane, and `shutdownHarnesses` runs them in reverse so
+ * what was set up last is torn down first.
+ *
+ * Error posture, ruled at the entry's gate (Q-S1-10):
+ *  - Boot validates the whole table BEFORE booting anything (a duplicate name
+ *    is a configuration defect, and a half-booted worker is the worst state to
+ *    discover it in), then fails fast at the first adapter that rejects. A
+ *    worker that cannot boot a harness must not start.
+ *  - Shutdown and session release CONTINUE past a failing adapter and throw
+ *    one `AggregateError` at the end naming each failure, so one bad teardown
+ *    never leaks the others' resources.
+ *
+ * What is NOT here yet: `createHarnessActivities` (its body is the turn
+ * runtime, which does not exist until the extraction entry) and the table of
+ * real adapters (they exist once the Cursor and native harnesses implement
+ * the contract). Both land with the runtime; no empty table sits on `main`
+ * between the two.
+ *
+ * `HarnessName` lives here and not in `types.ts` on purpose: the wire
+ * vocabulary is the registry's concern. An adapter never declares the
+ * activity it is bound to (its `name` is a diagnostic identity); the registry
+ * row does.
+ */
+
+import type { Config } from "../config.js";
+import type { HarnessAdapter } from "./types.js";
+
+/** The harnesses the control plane can dispatch to, as the registry knows them. */
+export type HarnessName = "cursor" | "deep-agent";
+
+/**
+ * Byte-pinned Temporal activity names, one per harness. The server side of
+ * the pin is `stigmer-server/src/temporal/agentexecution/names.ts`
+ * (`EXECUTE_CURSOR_ACTIVITY_NAME`, `EXECUTE_DEEP_AGENT_ACTIVITY_NAME`); the
+ * two must stay byte-identical or the workflow schedules an activity no
+ * worker registers. Never "cleaned up".
+ */
+export const HARNESS_ACTIVITY_NAMES = {
+  cursor: "ExecuteCursor",
+  "deep-agent": "ExecuteDeepAgent",
+} as const satisfies Record<HarnessName, string>;
+
+export type HarnessActivityName = (typeof HARNESS_ACTIVITY_NAMES)[HarnessName];
+
+/**
+ * Refuse a table two of whose adapters share a name. Names are the registry's
+ * identity for diagnostics and for this check; a duplicate means two adapters
+ * would be indistinguishable in every log line and kit message.
+ */
+function assertUniqueNames(adapters: readonly HarnessAdapter[]): void {
+  const seen = new Set<string>();
+  for (const adapter of adapters) {
+    if (seen.has(adapter.name)) {
+      throw new Error(`harness registry: duplicate adapter name '${adapter.name}'; every adapter must have a unique name`);
+    }
+    seen.add(adapter.name);
+  }
+}
+
+/**
+ * Boot every adapter in declaration order, one at a time, awaiting each. The
+ * table is validated first; the first rejection stops the boot and propagates
+ * (adapters after it are never booted; adapters before it stay booted for the
+ * caller's shutdown path to release).
+ */
+export async function bootHarnesses(adapters: readonly HarnessAdapter[], config: Config): Promise<void> {
+  assertUniqueNames(adapters);
+  for (const adapter of adapters) {
+    await adapter.boot(config);
+  }
+}
+
+/**
+ * Shut every adapter down in reverse declaration order, continuing past
+ * failures. Rejects with one `AggregateError` carrying every failure once all
+ * adapters have been given their chance.
+ */
+export async function shutdownHarnesses(adapters: readonly HarnessAdapter[]): Promise<void> {
+  const failures: Error[] = [];
+  for (const adapter of [...adapters].reverse()) {
+    try {
+      await adapter.shutdown();
+    } catch (err) {
+      failures.push(describeFailure(adapter, "shutdown", err));
+    }
+  }
+  throwIfAny(failures, "harness registry: shutdown failed for one or more adapters");
+}
+
+/**
+ * Tell every adapter the session is done on this host, in declaration order,
+ * continuing past failures. An adapter that parks nothing per session
+ * resolves as a no-op; the registry does not know which do.
+ */
+export async function releaseHarnessSession(adapters: readonly HarnessAdapter[], sessionId: string): Promise<void> {
+  const failures: Error[] = [];
+  for (const adapter of adapters) {
+    try {
+      await adapter.releaseSession(sessionId);
+    } catch (err) {
+      failures.push(describeFailure(adapter, `releaseSession('${sessionId}')`, err));
+    }
+  }
+  throwIfAny(failures, `harness registry: releaseSession('${sessionId}') failed for one or more adapters`);
+}
+
+function describeFailure(adapter: HarnessAdapter, call: string, err: unknown): Error {
+  const cause = err instanceof Error ? err : new Error(String(err));
+  return new Error(`${adapter.name}: ${call} rejected: ${cause.message}`, { cause });
+}
+
+function throwIfAny(failures: readonly Error[], message: string): void {
+  if (failures.length > 0) throw new AggregateError(failures, `${message}: ${failures.map((f) => f.message).join("; ")}`);
+}