@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/src/__test-utils__/approval-contract/hook-commands.ts

@@ -0,0 +1,100 @@
+/**
+ * The contract's hooks as real commands, shared by every substrate so both
+ * engines run the very same hooks: each logs what it reads on stdin, then
+ * answers as its behaviour says, in its format (Claude Code's JSON, or
+ * Cursor's `permission`), grouped into the turn's sources one per plugin
+ * and format.
+ */
+
+import { create } from "@bufbuild/protobuf";
+import { HookGroupSchema, HookHandlerSchema, type HookGroup } from "@stigmer/apis/ai/stigmer/agentic/plugin/v1/hooks_pb";
+import type { HookSourceGroups } from "../../shared/hooks/hook-set.js";
+import type { ContractHook, ContractHookBehaviour, ProposedAction } from "./types.js";
+
+/** One word of a bash command, quoted. */
+export function shellWord(value: string): string {
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+
+/**
+ * The bash command a contract hook runs: log its stdin, then answer as `does`
+ * says, in the hook's format (Claude Code's JSON, or Cursor's `permission`).
+ * Shared with the Cursor substrate, so both engines run the very same hooks.
+ */
+export function contractHookCommand(
+  does: ContractHookBehaviour,
+  files: { runs: string; state: string },
+  format: "claude-code" | "cursor",
+  rewriteInput: (action: ProposedAction) => Record<string, unknown>,
+): string {
+  const log = `cat >> ${shellWord(files.runs)}; echo >> ${shellWord(files.runs)}; `;
+  const print = (json: unknown) => `printf '%s' ${shellWord(JSON.stringify(json))}`;
+  const decide = (permissionDecision: string, extra: { reason?: string; updatedInput?: unknown; additionalContext?: string } = {}) =>
+    format === "cursor"
+      ? print({
+          permission: permissionDecision,
+          ...(extra.reason ? { agent_message: extra.reason } : {}),
+          ...(extra.updatedInput ? { updated_input: extra.updatedInput } : {}),
+          ...(extra.additionalContext ? { additional_context: extra.additionalContext } : {}),
+        })
+      : print({
+          hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision,
+            ...(extra.reason ? { permissionDecisionReason: extra.reason } : {}),
+            ...(extra.updatedInput ? { updatedInput: extra.updatedInput } : {}),
+            ...(extra.additionalContext ? { additionalContext: extra.additionalContext } : {}),
+          },
+        });
+  if ("hang" in does) return `${log}sleep 30`;
+  if ("exit" in does) return `${log}printf '%s' ${shellWord(does.stderr ?? "")} >&2; exit ${does.exit}`;
+  if ("invalidJson" in does) return `${log}printf '%s' 'this is not json'`;
+  if ("postBlock" in does) {
+    return log + print({
+      decision: "block",
+      reason: does.postBlock,
+      ...(does.context ? { hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: does.context } } : {}),
+    });
+  }
+  if (does.answer === "ask-then-deny") {
+    return `${log}if [ -e ${shellWord(files.state)} ]; then ${decide("deny", { reason: "asked once already" })}; ` +
+      `else : > ${shellWord(files.state)}; ${decide("ask")}; fi`;
+  }
+  return log + decide(does.answer, {
+    ...(does.reason ? { reason: does.reason } : {}),
+    ...(does.rewrite ? { updatedInput: rewriteInput(does.rewrite) } : {}),
+    ...(does.context ? { additionalContext: does.context } : {}),
+  });
+}
+
+/** The contract's hooks as the turn's sources: one per plugin and format, in first-seen order. */
+export function contractHookSources(
+  hooks: readonly ContractHook[],
+  files: { runs: string; state: string },
+  pluginRoot: string,
+  rewriteInput: (action: ProposedAction) => Record<string, unknown>,
+): HookSourceGroups[] {
+  const bySource = new Map<string, { plugin: string; format: "claude-code" | "cursor"; groups: HookGroup[] }>();
+  for (const hook of hooks) {
+    const plugin = hook.plugin ?? "safety";
+    const format = hook.format ?? "claude-code";
+    const key = `${plugin}\n${format}`;
+    const source = bySource.get(key) ?? { plugin, format, groups: [] };
+    source.groups.push(create(HookGroupSchema, {
+      event: hook.event,
+      matcher: hook.matcher,
+      handlers: [create(HookHandlerSchema, {
+        command: contractHookCommand(hook.does, files, format, rewriteInput),
+        timeoutSeconds: "hang" in hook.does ? 1 : 0,
+        condition: hook.condition ?? "",
+        failClosed: hook.failClosed ?? false,
+      })],
+    }));
+    bySource.set(key, source);
+  }
+  return [...bySource.values()].map(({ plugin, format, groups }) => ({
+    source: { plugin, root: pluginRoot, data: pluginRoot, options: new Map() },
+    format,
+    groups,
+  }));
+}

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

@@ -0,0 +1,323 @@
+/**
+ * The substrate-agnostic seam for the HITL gateway Contract Test Kit.
+ *
+ * Stigmer enforces tool approval through two real substrates with very different
+ * mechanics:
+ * - the in-process deep-agent gate (a LangGraph middleware that IS the side
+ *   effect), and
+ * - the out-of-process Cursor deny-oracle (a bash preToolUse hook that allows or
+ *   denies a tool the agent runs inside cursor-agent).
+ *
+ * The safety invariants they must uphold are identical, so the contract describes
+ * them once and runs them against anything that implements {@link GatewaySubstrate}.
+ * A future substrate (another runner, say) joins the safety net by
+ * implementing this one interface — it does not get to redefine the invariants.
+ *
+ * This seam intentionally does NOT carry raw, harness-specific tool names. The
+ * two substrates name the same operation differently (the Cursor hook says
+ * `Write`/`Shell`/`Delete`; the deep-agent stream says `edit`/`shell`/`delete`),
+ * so the contract speaks in the abstract {@link ProposedAction} and each adapter
+ * translates it into its own taxonomy. Keeping the contract taxonomy-free is what
+ * makes "both substrates agree on the same logical action" a meaningful assertion.
+ */
+
+/**
+ * A logical action a model proposes, expressed independently of any harness
+ * taxonomy. Each adapter maps it to its substrate's concrete tool name and args.
+ */
+export interface ProposedAction {
+  /**
+   * The action's approval-relevant kind. `write`/`shell`/`delete` are the gated
+   * mutating categories; `read` is any non-mutating built-in; `mcp` is an
+   * MCP-server tool.
+   */
+  readonly kind: "write" | "shell" | "delete" | "read" | "mcp";
+  /**
+   * The resource the action acts on — the absolute file path for file actions,
+   * the command string for shell. Empty for `mcp` (MCP identity is name-scoped).
+   * This is the "salient" value the exact-resource lease binds to.
+   */
+  readonly resource: string;
+  /**
+   * The edit content for a `write` action — the body whose digest the
+   * content-exact grant binds to. Two `write`s to the same `resource` with
+   * DIFFERENT `content` are distinct identities (the sibling-isolation probe);
+   * omitted, a substrate uses a fixed placeholder. Ignored for non-write kinds.
+   */
+  readonly content?: string;
+  /** MCP server slug — required for `kind: "mcp"`, ignored otherwise. */
+  readonly mcpServerSlug?: string;
+  /** MCP tool name — required for `kind: "mcp"`, ignored otherwise. */
+  readonly mcpToolName?: string;
+  /**
+   * For `kind: "mcp"`: the tool's server marks it destructive (its MCP
+   * annotation `destructiveHint: true`, read live each turn), so the
+   * approval default asks.
+   */
+  readonly mcpDestructive?: boolean;
+  /**
+   * For `kind: "read"`: `resource` is a path under the platform's own content
+   * (the `.stigmer/` route that carries the agent's skills, inputs and plan),
+   * which each adapter places where its engine mounts it.
+   */
+  readonly platformContent?: boolean;
+}
+
+/** An agent's (or sub-agent's) two tool lists, in Claude Code's names. */
+export interface ContractToolLists {
+  readonly tools: readonly string[];
+  readonly disallowedTools: readonly string[];
+}
+
+/** How a lists drive runs the action. */
+export interface ListsDriveOptions {
+  /** The pre-armed "trust this whole run": the approval gate is absent. */
+  readonly autoApproveAll?: boolean;
+  /**
+   * Run the action inside a sub-agent carrying these lists, narrowed from the
+   * agent's. Driven only where {@link SubstrateCapabilities.enforcesSubAgentLists}.
+   */
+  readonly subAgent?: ContractToolLists;
+}
+
+/** The outcome of a lists drive: a {@link GatewayOutcome} plus whether the lists refused the call. */
+export interface ListsOutcome extends GatewayOutcome {
+  /**
+   * The agent's lists refused the call: it did not run, the model read the
+   * out-of-scope message, and no approval was asked.
+   */
+  readonly refused: boolean;
+}
+
+/**
+ * The decision applied to a proposed action.
+ * - `none`   — no decision yet: run the action up to the gate and stop (the
+ *              "what happens with no backing authorization" probe).
+ * - `approve`— authorize THIS action.
+ * - `skip` / `reject` / `unknown` — every non-approving outcome; none may execute.
+ */
+export type GatewayDecision = "none" | "approve" | "skip" | "reject" | "unknown";
+
+/**
+ * The observable result of putting one proposed action through a substrate.
+ */
+export interface GatewayOutcome {
+  /**
+   * Whether the side effect ran (or, for an out-of-process substrate, whether
+   * the substrate ALLOWED it to run). This is the safety-critical observable and
+   * is comparable across substrates.
+   */
+  readonly executed: boolean;
+  /**
+   * Whether the substrate withheld the action pending approval. Note the precise
+   * meaning is substrate-specific (the in-process gate "paused at an interrupt";
+   * the deny-oracle "denied this call"), so it is only compared across substrates
+   * for `none`-decision probes, where both mean "withheld".
+   */
+  readonly gated: boolean;
+  /**
+   * Exact number of times the side effect ran. Populated only when
+   * {@link SubstrateCapabilities.observesExecution} is true (an in-process
+   * substrate can count; an out-of-process one cannot observe execution at all).
+   */
+  readonly executionCount?: number;
+  /**
+   * The authorization provenance the gate attached when it withheld the action —
+   * the PolicySource union string (e.g. "builtin_category", "agent_override").
+   * Populated only when {@link SubstrateCapabilities.surfacesGatePolicySource} is
+   * true; empty/undefined otherwise. Lets the contract assert every gated side
+   * effect is provenance-tagged.
+   */
+  readonly policySource?: string;
+}
+
+/**
+ * Capability flags for invariants that legitimately differ by substrate, gated
+ * rather than forked — mirroring the conformance suite's `CapabilityFlags`.
+ */
+export interface SubstrateCapabilities {
+  /**
+   * True when the runner executes the tool in-process and can therefore observe
+   * (and count) the side effect directly. The deep-agent gate is in-process
+   * (`true`); the Cursor hook authorizes a tool that runs in another process
+   * (`false`, receipts are best-effort).
+   */
+  readonly observesExecution: boolean;
+  /**
+   * True when an approval is bound to the exact resource it was granted for, so
+   * approving one resource never authorizes another. The Cursor grant token binds
+   * the resource (`true`); the deep-agent gate re-checks every distinct call and
+   * relies on checkpoint replay for sameness, so per-resource lease isolation is
+   * not a property of that gate (`false`).
+   */
+  readonly enforcesExactResource: boolean;
+  /**
+   * True when an approval is bound to the exact CONTENT of the action, not just
+   * its resource — so approving one edit to a file never authorizes a DIFFERENT
+   * edit to the SAME file. The Cursor grant binds (category, path, contentDigest)
+   * (`true`); the deep-agent gate relies on checkpoint replay for sameness, so
+   * content isolation is not a property of that gate (`false`).
+   */
+  readonly enforcesExactContent: boolean;
+  /**
+   * True when the substrate honors a run-lifetime CLASS lease: an APPROVE_ALL on
+   * one action auto-approves later actions of the SAME class (built-in category)
+   * for the rest of the run, while a DIFFERENT class stays gated. Both production
+   * substrates enforce this (the deep-agent gate clears leased categories; the
+   * Cursor hook reads `leasedCategories` from its state file), so both set `true`
+   * and implement {@link GatewaySubstrate.authorizeUnderClassLease}.
+   */
+  readonly appliesRunLifetimeLease: boolean;
+  /**
+   * True when the substrate attaches authorization provenance
+   * (approval_policy_source) at the gate, so a withheld action's
+   * {@link GatewayOutcome.policySource} is populated. The deep-agent gate decides
+   * and stamps the source at interrupt time (`true`); the Cursor substrate's
+   * provenance is a reconstruction-time projection over the persisted tool call,
+   * not a property of the hook's deny decision, so it is `false` here and is
+   * covered instead by the translator, boundary-rows and corpus suites.
+   */
+  readonly surfacesGatePolicySource: boolean;
+  /**
+   * True when the substrate runs an agent's hooks, in either format, at its
+   * gate; the contract's hooks section runs only there. Both engines do: the
+   * native gate in process, the Cursor gate through the runner's hook server.
+   */
+  readonly runsHooks: boolean;
+  /**
+   * True when a hook can tell a sub-agent's call from the main agent's (its
+   * stdin carries `agent_id` and `agent_type`). The native gate knows which
+   * sub-agent graph made a call (`true`); Cursor's hook payload carries no
+   * sub-agent identity (live probe, 2026-10-05), so the Cursor engine's
+   * hooks run on a sub-agent's calls without it (`false`).
+   */
+  readonly hookSeesSubAgent: boolean;
+  /**
+   * True when a sub-agent's own tool lists are enforced inside the sub-agent.
+   * The native engine narrows each sub-agent graph (`true`); the Cursor hook
+   * cannot tell which sub-agent is calling, so the Cursor engine refuses a
+   * turn whose sub-agent carries lists at setup instead (`false`, pinned by
+   * that harness's own tests).
+   */
+  readonly enforcesSubAgentLists: boolean;
+}
+
+/**
+ * A real enforcement substrate, wired to its production code. Adapters translate
+ * abstract actions/decisions into substrate-specific drives and report a uniform
+ * {@link GatewayOutcome}; they never reimplement enforcement logic.
+ */
+export interface GatewaySubstrate {
+  /** Stable substrate name, used in suite titles and diagnostics. */
+  readonly name: string;
+  /** Honest per-substrate capability flags. */
+  readonly capabilities: SubstrateCapabilities;
+  /**
+   * Whether this substrate can run in the current environment (e.g. the Cursor
+   * deny-oracle needs `bash`). The contract skips its suite when `false`.
+   */
+  readonly available: boolean;
+  /**
+   * Put a single proposed action through the substrate under a decision and
+   * report what happened.
+   */
+  authorize(action: ProposedAction, decision: GatewayDecision): Promise<GatewayOutcome>;
+  /**
+   * Approve `granted`, then probe `probe` against that standing authorization —
+   * the lease-isolation drive. Implemented only when
+   * {@link SubstrateCapabilities.enforcesExactResource} is true.
+   */
+  authorizeAfterGrant?(granted: ProposedAction, probe: ProposedAction): Promise<GatewayOutcome>;
+  /**
+   * Grant a run-lifetime CLASS lease by choosing APPROVE_ALL on `leased`, then
+   * probe `probe` against that standing lease — the scoped-lease drive that
+   * proves "approving all of class A never auto-approves class B." `leased` must
+   * be a gated built-in (write/shell/delete). Implemented only when
+   * {@link SubstrateCapabilities.appliesRunLifetimeLease} is true.
+   */
+  authorizeUnderClassLease?(leased: ProposedAction, probe: ProposedAction): Promise<GatewayOutcome>;
+  /**
+   * Put one action through an agent carrying `lists`, with no approval
+   * decision (`none`), and report whether the lists refused it, the default
+   * gated it, or it ran.
+   */
+  authorizeUnderLists(lists: ContractToolLists, action: ProposedAction, options?: ListsDriveOptions): Promise<ListsOutcome>;
+  /**
+   * Put one action through an agent carrying `hooks` and report what the
+   * hooks and the gate made of it. Implemented only when
+   * {@link SubstrateCapabilities.runsHooks} is true.
+   */
+  authorizeUnderHooks?(hooks: readonly ContractHook[], action: ProposedAction, options?: HooksDriveOptions): Promise<HooksOutcome>;
+}
+
+/** What a contract hook's command does when it runs. */
+export type ContractHookBehaviour =
+  /** Answer with Claude Code's JSON: a decision, its reason, a rewritten action, and context for the model. */
+  | {
+      readonly answer: "allow" | "deny" | "ask";
+      readonly reason?: string;
+      /** Rewrite the call into this action (`updatedInput`). */
+      readonly rewrite?: ProposedAction;
+      readonly context?: string;
+    }
+  /** Ask on its first run and deny on every later one: the resume probe. */
+  | { readonly answer: "ask-then-deny" }
+  /** Exit with this code, writing `stderr`. */
+  | { readonly exit: number; readonly stderr?: string }
+  /** Never answer: outlive the hook's timeout. */
+  | { readonly hang: true }
+  /** A PostToolUse hook that blocks on the result with this reason, beside optional context. */
+  | { readonly postBlock: string; readonly context?: string }
+  /** Print something that is not JSON and exit 0. */
+  | { readonly invalidJson: true };
+
+/** One command hook, in Claude Code's format or Cursor's. */
+export interface ContractHook {
+  /** Claude Code's `PreToolUse`/`PostToolUse`, or one of Cursor's tool events. */
+  readonly event: "PreToolUse" | "PostToolUse" | "preToolUse" | "beforeShellExecution" | "beforeMCPExecution" | "postToolUse";
+  /** The matcher: Claude Code's (`Bash`, `mcp__srv__search_issues`) or Cursor's (`Shell`, `MCP:search_issues`, a command pattern). */
+  readonly matcher: string;
+  /** The handler's `if` (Claude Code's format only). */
+  readonly condition?: string;
+  readonly does: ContractHookBehaviour;
+  /** The plugin the hook comes from; `""` is the agent's own hooks block. Default `safety`. */
+  readonly plugin?: string;
+  /** The format the hook is written in; Claude Code's when absent. */
+  readonly format?: "claude-code" | "cursor";
+  /** Cursor's `failClosed`: a run that fails refuses the call. */
+  readonly failClosed?: boolean;
+}
+
+/** How a hooks drive runs the action. */
+export interface HooksDriveOptions {
+  /** The decision a card gets, if one shows; default `none`. */
+  readonly decision?: GatewayDecision;
+  /** The pre-armed "trust this whole run". */
+  readonly autoApproveAll?: boolean;
+  /** The unattended approval mode: an ask resolves as a skip. */
+  readonly unattended?: boolean;
+  /** A held hook lease: `plugin`'s asks on `action`'s tool count as its allow. */
+  readonly hookLease?: { readonly plugin: string; readonly action: ProposedAction };
+  /** A held category lease. */
+  readonly categoryLease?: "write" | "shell";
+  /** Make the call inside a sub-agent of this type. */
+  readonly subAgent?: string;
+  /** The agent's tool lists, ahead of the hooks. */
+  readonly lists?: ContractToolLists;
+  /** The tool itself fails when it runs. */
+  readonly failTool?: boolean;
+}
+
+/** The outcome of a hooks drive. */
+export interface HooksOutcome extends GatewayOutcome {
+  /** Who refused the call, if anyone: a hook's deny, or the agent's tool lists. */
+  readonly refusedBy: "hook" | "lists" | undefined;
+  /** The plugin a withheld call's card names; undefined when no hook asked. */
+  readonly policyHook?: string;
+  /** What the model read back for the call. */
+  readonly modelRead: string;
+  /** What each hook run read on stdin, in run order. */
+  readonly hookRuns: readonly Record<string, unknown>[];
+  /** The files a write created, by the action's resource. */
+  readonly writtenPaths: readonly string[];
+}

package/src/__test-utils__/approval-log.ts

@@ -0,0 +1,142 @@
+/**
+ * What the server writes when a person answers a call that asked, as both
+ * test kits model it (the harness-contract `ExecutionDriver.decide` and the
+ * hermetic `ExecutionRecord.decideWaitingToolCalls`): the answer's session
+ * events, as the server's answer core commits them.
+ *
+ *  - a `user.tool_confirmation` naming the call's tool use id
+ *    (`harness/events/ids.ts` `toolUseEventId`): `allow` for APPROVE and
+ *    APPROVE_ALL, `deny` for REJECT and SKIP (a person's skip and reject
+ *    are one deny; a reason, when given, is its `deny_message`);
+ *  - for APPROVE_ALL, a `stigmer.permission.grant` on that call after it,
+ *    naming the lease the server derives from the call.
+ *
+ * The kits write nothing on the row: the runtime reads the answers from the
+ * log and its seed copies each onto its row's `approval_action` (APPROVE_ALL,
+ * APPROVE, or REJECT for any deny, a SKIP included).
+ *
+ * The ids follow the server's rule for an answer (`sevt_` and a hash of the
+ * tool use id), so a resent answer names the same event.
+ *
+ * The runtime reads the answers back through its one door
+ * (`harness/approval-answers.ts`), so a kit's answer reaches a turn only
+ * through the log, as a person's does. Beside them, the ask the runner's
+ * emitter writes for a row ({@link askedEventFor}), and the unit tests'
+ * shorthand for a transcript a person answered ({@link loggedApprovalsFor}).
+ */
+import { createHash } from "node:crypto";
+
+import { create } from "@bufbuild/protobuf";
+import { SessionEventSchema, type SessionEvent } from "@stigmer/apis/ai/stigmer/agentic/session/v1/event_pb";
+
+import { approvalAnswersOf, type ApprovalAsk } from "../harness/approval-answers.js";
+import { POLICY_SOURCE_WORDS } from "../harness/events/emitter.js";
+import { permissionAskedEventId, toolUseEventId } from "../harness/events/ids.js";
+import { deriveLeaseScope } from "../shared/approval-policy.js";
+import type { AgentMessage, ToolCall } from "../gen/turn/ai/stigmer/runner/turn/v1/rows_pb.js";
+import { ApprovalAction, ToolCallStatus } from "../gen/turn/ai/stigmer/runner/turn/v1/enum_pb.js";
+
+function hashed(prefix: string, toolUseId: string): string {
+  return `${prefix}${createHash("sha256").update(toolUseId).digest("hex").slice(0, 40)}`;
+}
+
+/**
+ * The events the server appends when a person answers `row` of run `runId`
+ * with `action` (and, for a deny, `denyMessage`), in order.
+ */
+export function answerEventsFor(
+  args: { readonly sessionId: string; readonly runId: string },
+  row: ToolCall,
+  action: ApprovalAction,
+  denyMessage = "",
+): SessionEvent[] {
+  const toolUseId = toolUseEventId(args.runId, row.id);
+  const allow = action === ApprovalAction.APPROVE || action === ApprovalAction.APPROVE_ALL;
+  const events: SessionEvent[] = [
+    create(SessionEventSchema, {
+      sessionId: args.sessionId,
+      runId: args.runId,
+      event: {
+        case: "userToolConfirmation",
+        value: {
+          id: hashed("sevt_tc_", toolUseId),
+          result: allow ? "allow" : "deny",
+          toolUseId,
+          denyMessage: allow ? "" : denyMessage,
+        },
+      },
+    }),
+  ];
+  const lease = action === ApprovalAction.APPROVE_ALL ? deriveLeaseScope(row) : undefined;
+  if (lease !== undefined) {
+    events.push(
+      create(SessionEventSchema, {
+        sessionId: args.sessionId,
+        runId: args.runId,
+        event: {
+          case: "stigmerPermissionGrant",
+          value: {
+            id: hashed("sevt_pg_", toolUseId),
+            toolUseId,
+            scope: "turn",
+            lease:
+              lease.kind === "hook"
+                ? { category: "", server: lease.server, hook: lease.hook, tool: lease.tool }
+                : lease.kind === "server"
+                  ? { category: "", server: lease.server, tool: "" }
+                  : { category: lease.category, server: "", tool: "" },
+          },
+        },
+      }),
+    );
+  }
+  return events;
+}
+
+/**
+ * The `stigmer.permission.asked` the runner's emitter writes for a row that
+ * asks (`harness/events/emitter.ts` `writeToolUse`): its policy source word,
+ * its hook and its content digest, as the row carried them at the ask.
+ */
+export function askedEventFor(args: { readonly sessionId: string; readonly runId: string }, row: ToolCall): SessionEvent {
+  const toolUseId = toolUseEventId(args.runId, row.id);
+  return create(SessionEventSchema, {
+    sessionId: args.sessionId,
+    runId: args.runId,
+    event: {
+      case: "stigmerPermissionAsked",
+      value: {
+        id: permissionAskedEventId(toolUseId),
+        toolUseId,
+        message: row.approvalMessage,
+        argsPreview: row.argsPreview,
+        policySource: POLICY_SOURCE_WORDS[row.approvalPolicySource],
+        policyHook: row.approvalPolicyHook,
+        contentDigest: row.approvalContentDigest,
+      },
+    },
+  });
+}
+
+/**
+ * What the runtime's door reads for `messages` when every root WAITING row
+ * whose `approvalAction` is set was asked as the emitter writes it and
+ * answered with that action: the unit tests' shorthand for "a person
+ * answered these rows", stated once. The rows' `approvalAction` stands for
+ * the answer here only; the reader under test never sees it.
+ */
+export function loggedApprovalsFor(
+  runId: string,
+  messages: readonly AgentMessage[],
+): { readonly runId: string; readonly decisions: ReadonlyMap<string, ApprovalAction>; readonly asks: ReadonlyMap<string, ApprovalAsk>; readonly denyMessages: ReadonlyMap<string, string> } {
+  const ids = { sessionId: "ses_logged", runId };
+  const log: SessionEvent[] = [];
+  for (const message of messages) {
+    for (const row of message.toolCalls) {
+      if (row.status !== ToolCallStatus.TOOL_CALL_WAITING_APPROVAL || row.approvalAction === ApprovalAction.UNSPECIFIED) continue;
+      log.push(askedEventFor(ids, row), ...answerEventsFor(ids, row, row.approvalAction));
+    }
+  }
+  const answers = approvalAnswersOf(runId, { messages }, log);
+  return { runId, decisions: answers.decisions, asks: answers.asks, denyMessages: answers.denyMessages };
+}

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

@@ -0,0 +1,65 @@
+/**
+ * A complete, inert runner `Config` for tests.
+ *
+ * `Config` has twenty required fields (the credential ref among them, plus two optional 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",
+    temporalConnection: {},
+    stigmerBackendEndpoint: INERT_ENDPOINT,
+    stigmerTokenRef: { current: null },
+    mcpBridgeEndpoint: null,
+    mcpPublicEndpoint: 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__/cursor-sdk-wire-child.ts

@@ -0,0 +1,47 @@
+/**
+ * The agent host's side of the Cursor wire, as its own process: the real
+ * `@cursor/sdk`, the runner's Cursor interceptors bound to the local
+ * proxy's Cursor lane with the host's token, trusting the lane only through
+ * the `NODE_EXTRA_CA_CERTS` it was started with
+ * (`agent-proxy/__tests__/cursor-sdk-wire.test.ts` and
+ * `cursor-sdk-key-required.test.ts` start it).
+ *
+ * argv: the lane's endpoint, the host token, the execution id, the turn's key. It creates
+ * one local agent, sends one prompt, and prints one JSON line: the run's
+ * result (or the error, with a thrown `CursorSdkError`'s code and status,
+ * the fields the runner classifies it by), and what
+ * `NODE_TLS_REJECT_UNAUTHORIZED` reads afterwards.
+ */
+
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { installFetchInterceptor } from "../activities/execute-cursor/fetch-interceptor.js";
+import { assertHttp2ConnectPatched, installHttp2Interceptor } from "../activities/execute-cursor/http2-interceptor.js";
+import { runWithExecutionContext } from "../shared/execution-context.js";
+
+const [lane = "", token = "", executionId = "", turnKey = ""] = process.argv.slice(2);
+const proxyTokenRef = { current: token };
+installFetchInterceptor({ proxyEndpoint: lane, proxyTokenRef });
+installHttp2Interceptor({ proxyEndpoint: lane, proxyTokenRef });
+await assertHttp2ConnectPatched();
+const { Agent, CursorSdkError } = await import("@cursor/sdk");
+
+const outcome = await runWithExecutionContext(executionId, async () => {
+  try {
+    const agent = await Agent.create({
+      apiKey: token,
+      model: { id: "composer-2.5", params: [] },
+      local: { cwd: mkdtempSync(join(tmpdir(), "cursor-sdk-wire-")), enableAgentRetries: false },
+    });
+    const run = await agent.send("hello");
+    const result = await run.wait();
+    return { status: result.status, error: result.error?.message ?? null };
+  } catch (err) {
+    const sdkError = err instanceof CursorSdkError ? { sdkError: { code: err.code ?? null, status: err.status ?? null } } : {};
+    return { status: "thrown", error: err instanceof Error ? err.message : String(err), ...sdkError };
+  }
+}, turnKey);
+console.log(`WIRE ${JSON.stringify({ ...outcome, tlsRejectUnauthorized: process.env.NODE_TLS_REJECT_UNAUTHORIZED ?? null })}`);
+process.exit(0);