@stigmer/runner 3.14.0 → 3.15.0

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

@@ -0,0 +1,178 @@
+/**
+ * Pins the turn context's pure decisions — the three places `turn-context.ts`
+ * decides something rather than fetching it:
+ *
+ *  - `isReinvocation`: the one reading of "does the engine already hold state
+ *    for this execution", keyed on how the harness mints its state id. The
+ *    engine-minted arm is today's `!!threadId`; the deterministic arm refuses
+ *    until the native adapter lands (S3), and the refusal is pinned so a
+ *    future caller cannot get a silent `false`.
+ *  - `approvalDecisionsOf`: the runtime's reader of adjudicated approvals,
+ *    over a transcript that carries every row shape it must include or
+ *    exclude. Its agreement with the Cursor adapter's own reader
+ *    (`reconstructAdjudicatedApprovals`) is pinned from the adapter's side
+ *    (`activities/execute-cursor/__tests__/approval-state.test.ts`), because
+ *    `src/harness/` never imports `src/activities/`, tests included.
+ *  - `decideReinvocation`: the four ways a resume proceeds (reject fails,
+ *    approvals run, a clean file-review resume completes, a failed or
+ *    partially discarded one completes with its facts carried).
+ *
+ * The phases that fetch and provision are exercised end to end by the
+ * hermetic goldens (`activities/execute-cursor/__tests__/hermetic/`), which
+ * pin their observable behavior byte for byte; nothing here re-drives a
+ * client.
+ */
+
+import { describe, expect, it } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { AgentMessageSchema, ToolCallSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { SubAgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
+import { ApprovalAction, MessageType, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+import { approvalDecisionsOf, decideReinvocation, isReinvocation, type ReinvocationFacts } from "../turn-context.js";
+
+const INPUT = { executionId: "aex_1", threadId: "", turnSeq: 0 } as const;
+
+describe("isReinvocation", () => {
+  it("engine-minted: an empty state id is a first turn, any id is a resume", () => {
+    expect(isReinvocation("engine-minted", INPUT)).toBe(false);
+    expect(isReinvocation("engine-minted", { ...INPUT, threadId: "agent-42" })).toBe(true);
+  });
+
+  it("engine-minted: turnSeq is NOT the signal (a pure-reconcile turn does not advance it; the legacy wire shape yields 0)", () => {
+    expect(isReinvocation("engine-minted", { ...INPUT, turnSeq: 3 })).toBe(false);
+    expect(isReinvocation("engine-minted", { ...INPUT, threadId: "agent-42", turnSeq: 0 })).toBe(true);
+  });
+
+  it("deterministic: refuses rather than guess until the native adapter lands (S3)", () => {
+    expect(() => isReinvocation("deterministic", { ...INPUT, threadId: "thread-1" })).toThrow(
+      /deterministic arm lands with the native adapter \(S3\)/,
+    );
+  });
+});
+
+/** A transcript carrying every row shape the reader must include or exclude. */
+function transcriptWithEveryRowShape() {
+  const waitingApproved = create(ToolCallSchema, {
+    id: "tc-approved",
+    name: "Shell",
+    status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+    approvalAction: ApprovalAction.APPROVE,
+    approvalContentDigest: "sha256:approved",
+  });
+  const waitingRejected = create(ToolCallSchema, {
+    id: "tc-rejected",
+    name: "Write",
+    status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+    approvalAction: ApprovalAction.REJECT,
+  });
+  const waitingUndecided = create(ToolCallSchema, {
+    id: "tc-undecided",
+    name: "Shell",
+    status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+    approvalAction: ApprovalAction.UNSPECIFIED,
+  });
+  const completedWithStaleAction = create(ToolCallSchema, {
+    id: "tc-completed",
+    name: "Read",
+    status: ToolCallStatus.TOOL_CALL_COMPLETED,
+    approvalAction: ApprovalAction.APPROVE,
+  });
+  const subAgentWaiting = create(ToolCallSchema, {
+    id: "tc-sub",
+    name: "Shell",
+    status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+    approvalAction: ApprovalAction.APPROVE,
+  });
+  return create(AgentExecutionStatusSchema, {
+    messages: [
+      create(AgentMessageSchema, { type: MessageType.MESSAGE_AI, toolCalls: [waitingApproved, waitingUndecided] }),
+      create(AgentMessageSchema, { type: MessageType.MESSAGE_AI, toolCalls: [completedWithStaleAction, waitingRejected] }),
+    ],
+    subAgentExecutions: [
+      create(SubAgentExecutionSchema, {
+        messages: [create(AgentMessageSchema, { type: MessageType.MESSAGE_AI, toolCalls: [subAgentWaiting] })],
+      }),
+    ],
+  });
+}
+
+describe("approvalDecisionsOf", () => {
+  it("reads every WAITING row with a verdict, in transcript order, and nothing else", () => {
+    const decisions = approvalDecisionsOf(transcriptWithEveryRowShape());
+    expect([...decisions.entries()]).toEqual([
+      ["tc-approved", ApprovalAction.APPROVE],
+      ["tc-rejected", ApprovalAction.REJECT],
+    ]);
+  });
+
+  it("an undecided WAITING row, a COMPLETED row with a stale verdict, and a sub-agent row are all excluded", () => {
+    const decisions = approvalDecisionsOf(transcriptWithEveryRowShape());
+    expect(decisions.has("tc-undecided"), "no verdict yet").toBe(false);
+    expect(decisions.has("tc-completed"), "already executed; the verdict on it is history").toBe(false);
+    expect(decisions.has("tc-sub"), "sub-agent transcripts are not the top-level rows").toBe(false);
+  });
+
+  it("is empty on a fresh status", () => {
+    expect(approvalDecisionsOf(create(AgentExecutionStatusSchema, {})).size).toBe(0);
+  });
+});
+
+function facts(overrides: Partial<ReinvocationFacts> = {}): ReinvocationFacts {
+  return {
+    approvalDecisions: new Map(),
+    reconciledFileReview: false,
+    fileReviewFailed: false,
+    fileReviewFailureDetail: "",
+    discardedPaths: [],
+    ...overrides,
+  };
+}
+
+describe("decideReinvocation", () => {
+  it("a first turn, or a resume that decided nothing and reconciled nothing, runs the agent", () => {
+    expect(decideReinvocation(facts())).toBeUndefined();
+  });
+
+  it("any REJECT among the adjudicated decisions fails the turn, whatever else was decided", () => {
+    const decisions = new Map([
+      ["tc-1", ApprovalAction.APPROVE],
+      ["tc-2", ApprovalAction.REJECT],
+    ]);
+    expect(decideReinvocation(facts({ approvalDecisions: decisions }))).toEqual({ kind: "rejected-by-user" });
+  });
+
+  it("approvals without a reject run the agent, even when file review was also reconciled", () => {
+    const decisions = new Map([["tc-1", ApprovalAction.APPROVE]]);
+    expect(decideReinvocation(facts({ approvalDecisions: decisions, reconciledFileReview: true }))).toBeUndefined();
+    expect(
+      decideReinvocation(facts({ approvalDecisions: new Map([["tc-1", ApprovalAction.SKIP]]) })),
+      "a SKIP is not a reject",
+    ).toBeUndefined();
+  });
+
+  it("a pure file-review resume completes, carrying the reconcile's facts", () => {
+    expect(decideReinvocation(facts({ reconciledFileReview: true }))).toEqual({
+      kind: "file-review-resolved",
+      failed: false,
+      failureDetail: "",
+      discardedPaths: [],
+    });
+    expect(
+      decideReinvocation(
+        facts({
+          reconciledFileReview: true,
+          fileReviewFailed: true,
+          fileReviewFailureDetail: "src/a.ts changed after review",
+          discardedPaths: ["src/b.ts"],
+        }),
+      ),
+    ).toEqual({
+      kind: "file-review-resolved",
+      failed: true,
+      failureDetail: "src/a.ts changed after review",
+      discardedPaths: ["src/b.ts"],
+    });
+  });
+});

package/src/harness/__tests__/usage-accumulator.test.ts

@@ -0,0 +1,83 @@
+/**
+ * The runtime's usage accounting over priced deltas: the token-accounting
+ * convention the Usage widget and the billing parity test depend on, the
+ * audit-trail fields, and the rule that the accumulator adds and never
+ * prices. The pricing half is `execute-cursor/__tests__/usage-pricing.test.ts`.
+ */
+
+import { describe, it, expect } from "vitest";
+import { ServiceTier, ThinkingMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+import { UsageAccumulator } from "../usage-accumulator.js";
+
+describe("UsageAccumulator", () => {
+  it("reports total_tokens as input + output (cache is a subset of input, not additive)", () => {
+    const acc = new UsageAccumulator();
+
+    // Two turns. cacheRead/cacheWrite are subsets of inputTokens.
+    acc.addTurn({ inputTokens: 100, outputTokens: 50, cacheReadTokens: 30, cacheWriteTokens: 10 });
+    acc.addTurn({ inputTokens: 300, outputTokens: 20, cacheReadTokens: 200, cacheWriteTokens: 0 });
+
+    const snap = acc.snapshot();
+
+    expect(snap.inputTokens).toBe(400n);
+    expect(snap.outputTokens).toBe(70n);
+    expect(snap.cacheReadTokens).toBe(230n);
+    expect(snap.cacheWriteTokens).toBe(10n);
+    // True total = input + output = 470. NOT 470 + 230 + 10 (which would
+    // double-count the cached tokens already inside inputTokens).
+    expect(snap.totalTokens).toBe(470n);
+    expect(snap.turnCount).toBe(2);
+  });
+
+  it("returns an empty snapshot when no turns were observed", () => {
+    const acc = new UsageAccumulator();
+    const snap = acc.snapshot();
+    expect(acc.hasTurns).toBe(false);
+    expect(snap.totalTokens).toBe(0n);
+    expect(snap.turnCount).toBe(0);
+    expect(snap.estimatedCostUsd).toBe(0);
+  });
+
+  it("treats missing token fields as zero", () => {
+    const acc = new UsageAccumulator();
+    acc.addTurn({ inputTokens: 42 });
+    const snap = acc.snapshot();
+    expect(snap.inputTokens).toBe(42n);
+    expect(snap.outputTokens).toBe(0n);
+    expect(snap.totalTokens).toBe(42n);
+  });
+
+  it("sums the adapter's stated cost and never prices on its own", () => {
+    const acc = new UsageAccumulator();
+    acc.addTurn({ inputTokens: 1_000_000, estimatedCostUsd: 0.25 });
+    acc.addTurn({ inputTokens: 1_000_000, estimatedCostUsd: 0.5 });
+    acc.addTurn({ inputTokens: 1_000_000 });
+    expect(acc.snapshot().estimatedCostUsd).toBeCloseTo(0.75, 9);
+  });
+
+  it("records the latest stated price basis; a delta without one inherits it (#357 audit trail)", () => {
+    const acc = new UsageAccumulator(ServiceTier.FAST, ThinkingMode.DISABLED);
+    acc.addTurn({ inputTokens: 10, model: "composer-2.5", requestedModelParams: '[{"id":"fast","value":"true"}]' });
+    acc.addTurn({ inputTokens: 5 });
+    const snap = acc.snapshot();
+    expect(snap.model).toBe("composer-2.5");
+    expect(snap.requestedModelParams).toBe('[{"id":"fast","value":"true"}]');
+    expect(snap.requestedServiceTier).toBe(ServiceTier.FAST);
+  });
+
+  it("records an empty basis when no delta named one", () => {
+    const acc = new UsageAccumulator(ServiceTier.STANDARD, ThinkingMode.DISABLED);
+    acc.addTurn({ inputTokens: 1 });
+    const snap = acc.snapshot();
+    expect(snap.model).toBe("");
+    expect(snap.requestedModelParams).toBe("");
+    expect(snap.requestedServiceTier).toBe(ServiceTier.STANDARD);
+  });
+
+  it("records the requested thinking mode into the snapshot (#772 audit trail)", () => {
+    const acc = new UsageAccumulator(ServiceTier.STANDARD, ThinkingMode.ENABLED);
+    acc.addTurn({ inputTokens: 10, outputTokens: 5 });
+    expect(acc.snapshot().requestedThinkingMode).toBe(ThinkingMode.ENABLED);
+  });
+});

package/src/harness/capabilities.ts

@@ -0,0 +1,92 @@
+/**
+ * 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)                               |
+ * | `fileReview`      | `deep-agent`, no excludes   | `cursor`, `.cursor/hooks.json` excluded | (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";
+
+/**
+ * The two facts the runtime's file-review reconcile needs from the harness
+ * and cannot know: the id the projection reads from the BASELINE payload
+ * (`shared/filereview/capture.ts` `applyCaptureDecisions`), and the
+ * workspace-relative paths the harness writes into the repo that a turn's
+ * diff must never show (Cursor's transient `.cursor/hooks.json`). Declared
+ * once per adapter, read by `turn-context.ts` (ruled Q-M2-6 as an argument,
+ * homed here at M3).
+ */
+export interface FileReviewIdentity {
+  readonly harnessId: string;
+  readonly excludePaths: readonly string[];
+}
+
+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;
+  /** How the harness's captured file changes are identified and what its own repo writes are excluded from a diff. */
+  readonly fileReview: FileReviewIdentity;
+}

package/src/harness/persist-chokepoint.ts

@@ -0,0 +1,112 @@
+/**
+ * The turn runtime's single persist chokepoint: every write of the
+ * execution status during a turn — the adapter's streaming requests, the
+ * runtime's own terminal writes — goes through here and nowhere else, so
+ * the guards that must never be skipped cannot be skipped by a call site
+ * that forgot them.
+ *
+ * What one write does, in order:
+ *  1. The never-persist-secret backstop (DD-26 #2): content is withheld from
+ *     any built-in write row targeting a secret-like path, top-level and
+ *     sub-agent. The single airtight choke point for a deny-gate harness and
+ *     the only guarantee under `auto_approve_all`. Idempotent.
+ *  2. `streaming_usage` is refreshed from the accumulator when it has turns,
+ *     so the summary the UI shows is the one the write carries.
+ *  3. `persistStatus` (`shared/status.ts`): tool-output offload, the
+ *     aggregate size cap, transient retry, oversize recovery. Never rejects.
+ *  4. A Temporal heartbeat, so a long streaming turn's liveness is proven by
+ *     the writes it makes (Q-S2-10).
+ *  5. The control plane's answer: STOP becomes the runtime's platform-stop
+ *     cause on the stop controller, which aborts the adapter's signal.
+ *
+ * Single-flight with coalescing: an adapter's `requestPersist()` while a
+ * write is in flight does not start a second concurrent write (two writes of
+ * one status racing on the wire is the drift the chokepoint exists to
+ * prevent); it schedules ONE follow-up write after the current one lands,
+ * and resolves when that follow-up has. The promise it returns therefore
+ * always means "the state as of my request is on the control plane", which
+ * is what lets the Cursor loop await it and see a STOP before it pulls the
+ * next event, exactly as its own inline persist did (Q-M3-2).
+ *
+ * The runtime's terminal writes use the same path (`write()`), so the
+ * secret backstop and the usage summary ride the final status too, as they
+ * did when the orchestrator's `persist` closure was the one place to write.
+ */
+
+import { create } from "@bufbuild/protobuf";
+import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionControlSignal } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { StreamingUsageSummarySchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/usage_pb";
+
+import type { StigmerClient } from "../client/stigmer-client.js";
+import { persistStatus } from "../shared/status.js";
+import type { ToolOutputOffloadContext } from "../shared/status-offload.js";
+import { withholdSecretContentFromMessages } from "../shared/tool-row.js";
+import type { UsageAccumulator } from "./usage-accumulator.js";
+
+export interface PersistChokepointDeps {
+  readonly client: StigmerClient;
+  readonly executionId: string;
+  readonly status: AgentExecutionStatus;
+  /** Present when artifact storage resolved; enables tool-output offload on every write. */
+  readonly offload: ToolOutputOffloadContext | undefined;
+  /**
+   * The accumulator, read at WRITE time: it exists only once the runtime has
+   * the turn's model preferences, after resolution, so it arrives as a thunk
+   * and is `undefined` for a write made before then (no usage yet anyway).
+   */
+  readonly usage: () => UsageAccumulator | undefined;
+  /** The Temporal heartbeat, pulsed after each write. */
+  readonly heartbeat: () => void;
+  /** The control plane answered STOP to this write. */
+  readonly onPlatformStop: () => void;
+}
+
+export class PersistChokepoint {
+  private inFlight: Promise<void> | undefined;
+  private followUp: Promise<void> | undefined;
+
+  constructor(private readonly deps: PersistChokepointDeps) {}
+
+  /**
+   * The adapter's `requestPersist()`: a write now, or one follow-up write
+   * after the in-flight one. Resolves when the state as of this call has
+   * been written. Never rejects.
+   */
+  request(): Promise<void> {
+    if (this.inFlight === undefined) {
+      const write = this.write().finally(() => {
+        this.inFlight = undefined;
+      });
+      this.inFlight = write;
+      return write;
+    }
+    if (this.followUp === undefined) {
+      this.followUp = this.inFlight.then(() => {
+        this.followUp = undefined;
+        return this.request();
+      });
+    }
+    return this.followUp;
+  }
+
+  /**
+   * One write, now. The runtime's own writes (a settlement, a terminal
+   * status) call this directly: they run when no adapter write can be in
+   * flight (before `runTurn` or after it settled), so they need no
+   * coalescing, and they must not be deferred behind one.
+   */
+  async write(): Promise<void> {
+    const { client, executionId, status, offload, heartbeat } = this.deps;
+    withholdSecretContentFromMessages(status.messages, status.subAgentExecutions);
+    const usage = this.deps.usage();
+    if (usage?.hasTurns) {
+      status.streamingUsage = create(StreamingUsageSummarySchema, usage.snapshot());
+    }
+    const signal = await persistStatus(client, executionId, status, { offload });
+    heartbeat();
+    if (signal === ExecutionControlSignal.STOP) {
+      this.deps.onPlatformStop();
+    }
+  }
+}

package/src/harness/registry.ts

@@ -0,0 +1,197 @@
+/**
+ * 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.
+ *
+ * `createHarnessActivities` binds each row to its Temporal activity over the
+ * turn runtime (`run-turn.ts`). The table of real rows is NOT here: it lives
+ * at the source root (`src/harness-adapters.ts`), because a row imports its
+ * adapter from `activities/` and nothing under `src/harness/` may
+ * (`__tests__/import-direction.test.ts`; Q-M3-1). The registry knows rows,
+ * never which adapters exist.
+ *
+ * `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.
+ *
+ * THIS MODULE'S STATIC GRAPH MUST STAY CONNECT-FREE. Both composition roots
+ * import it BEFORE they boot the harnesses, and the Cursor adapter's boot
+ * patches `node:http2` (its HTTP/2 auth interceptor); a static import of
+ * anything that loads `@connectrpc/connect-node` here would snapshot the
+ * `node:http2` ESM facade to the unpatched `connect` before that boot ran,
+ * and every BiDi stream would silently 401. So `StigmerClient` is loaded
+ * with a dynamic import inside `createHarnessActivities`, the runner's
+ * dynamic-import-for-order convention (`bootstrap.ts` documents the same
+ * omission for the same reason). `__tests__/harness-boot-order.test.ts`
+ * boots a fresh process through this module and fails if the facade froze.
+ */
+
+import type { Config } from "../config.js";
+import type { StigmerClient } from "../client/stigmer-client.js";
+import { activityFinished, activityStarted } from "../idle-watchdog.js";
+import { normalizeActivityInput, type ExecuteActivityInput } from "../shared/activity-input.js";
+import { runTurnActivity } from "./run-turn.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];
+
+/** One harness the worker serves: the wire name it answers to and the adapter that runs its turns. */
+export interface HarnessRow {
+  readonly harness: HarnessName;
+  readonly adapter: HarnessAdapter;
+}
+
+/**
+ * The legacy positional activity signature, kept as the wire shape both
+ * control planes send until they both send the typed object
+ * (`shared/activity-input.ts`). Every harness's activity has it.
+ */
+export type HarnessActivity = (arg0: ExecuteActivityInput | string, arg1?: string) => Promise<unknown>;
+
+/** The adapters of a row list, for the lifecycle functions below. */
+export function adaptersOf(rows: readonly HarnessRow[]): HarnessAdapter[] {
+  return rows.map((row) => row.adapter);
+}
+
+/**
+ * One Temporal activity per row, under the row's byte-pinned name, over ONE
+ * `StigmerClient` for all of them (each harness used to build its own). The
+ * activity normalizes the wire input, brackets the turn with the idle
+ * watchdog, and hands the turn runtime the adapter. The roots spread the
+ * result into the worker's activity map beside the activities the runtime
+ * does not own.
+ *
+ * Async because the client is loaded here, not at the top of the module (see
+ * the header): the roots call this after the harnesses have booted, when
+ * connect-node may load.
+ */
+export async function createHarnessActivities(
+  rows: readonly HarnessRow[],
+  config: Config,
+): Promise<Partial<Record<HarnessActivityName, HarnessActivity>>> {
+  const { StigmerClient } = await import("../client/stigmer-client.js");
+  const client: StigmerClient = new StigmerClient({
+    endpoint: config.stigmerBackendEndpoint,
+    token: config.stigmerToken,
+    tokenRef: config.stigmerTokenRef,
+    runnerTokenRef: config.stigmerRunnerTokenRef,
+  });
+  const activities: Partial<Record<HarnessActivityName, HarnessActivity>> = {};
+  for (const row of rows) {
+    const activityName = HARNESS_ACTIVITY_NAMES[row.harness];
+    const deps = { adapter: row.adapter, activityName, client, config };
+    activities[activityName] = async (arg0, arg1) => {
+      const input = normalizeActivityInput(arg0, arg1);
+      activityStarted();
+      try {
+        return await runTurnActivity(deps, input);
+      } finally {
+        activityFinished();
+      }
+    };
+  }
+  return activities;
+}
+
+/**
+ * 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("; ")}`);
+}