@stigmer/runner 3.14.1 → 3.15.1

package/src/activities/execute-cursor/adapter.ts

@@ -0,0 +1,138 @@
+/**
+ * The Cursor harness as a `HarnessAdapter` — the worker- and session-lifetime
+ * half of its SDK slice, behind the turn runtime's contract
+ * (`harness/types.ts`). One engine turn is `turn.ts`'s `runCursorTurn`; this
+ * module boots, releases, and delegates.
+ *
+ * What this adapter owns: the proxy interceptors and the parked-agent cache
+ * (worker lifetime), the parked agent per session (session lifetime), and one
+ * engine turn (`runTurn`, through `turn.ts`). Everything else about a turn is
+ * the runtime's (`harness/run-turn.ts`).
+ *
+ * THIS MODULE'S STATIC GRAPH IS SDK-FREE, ON PURPOSE. The composition roots
+ * import it (through `src/harness-adapters.ts`) BEFORE they boot it, and
+ * `boot` is where the fetch and HTTP/2 interceptors are installed. The HTTP/2
+ * one patches `node:http2`, whose ESM facade is snapshotted the first time
+ * `@connectrpc/connect-node` is imported — and `@cursor/sdk` imports
+ * connect-node. So the SDK-touching half of this harness (`turn.ts` and,
+ * through it, `turn-setup.ts` and its siblings) is loaded with a dynamic
+ * import INSIDE `boot`, after the installs and after
+ * `assertHttp2ConnectPatched` has proven the facade sees the patch. This is
+ * the contract's own rule ("vendor SDKs are imported lazily inside" boot,
+ * `types.ts`), and the runner's dynamic-import-for-order convention
+ * (`bootstrap.ts`). `src/__tests__/harness-boot-order.test.ts` boots a fresh
+ * process through this path and fails if the graph regresses; the modules
+ * this file imports statically must each stay connect-free.
+ *
+ * The interceptors read the proxy credential from `Config.proxyTokenRef` per
+ * request; which credential that is (the static root's control-plane token,
+ * the manager's minted runner token) is the root's decision, not this
+ * module's (Q-S2-7).
+ *
+ * What this adapter never does: throw out of `runTurn` (an SDK failure is
+ * `failed` with the classifier's sentence; an unexpected exception is
+ * `failed` on the `internal` surface; a `CancelledFailure` never exists
+ * here), branch on why `stopSignal` aborted, write a phase or a terminal
+ * copy, or import `@temporalio/*` (`__tests__/adapter-is-temporal-free.test.ts`
+ * pins it, which is what lets the contract kit run this adapter outside any
+ * activity context).
+ *
+ * The file-review boundary (`turn-boundary.ts`) runs whole inside `turn.ts`
+ * for S2 (Q-S2-1): five of its six steps read the denial ledger, this
+ * harness's deny-and-retry primitive. S3 lifts the capture into the runtime
+ * with both harnesses' captures in view; `types.ts`'s "the file-review
+ * boundary is the runtime's" becomes true then.
+ *
+ * Extracted from `index.ts` `createCursorActivities` at S2 M3b; split from
+ * the turn body at S2 M5. The seventeen hermetic goldens under
+ * `__tests__/hermetic/` pin the result byte for byte.
+ */
+
+import type { Config } from "../../config.js";
+import type { HarnessAdapter, TurnInput, TurnOutcome, TurnSink } from "../../harness/types.js";
+import { markBoot } from "../../shared/cold-start-timing.js";
+import { closeAllCachedAgents, evictSessionAgent } from "./agent-session-cache.js";
+import { CURSOR_CAPABILITIES } from "./cursor-capabilities.js";
+import { installFetchInterceptor } from "./fetch-interceptor.js";
+import { assertHttp2ConnectPatched, installHttp2Interceptor } from "./http2-interceptor.js";
+import type { CursorAdapterConfig } from "./turn-setup.js";
+
+/** The config slice this adapter reads per turn, taken at `boot`; a whole `Config` satisfies it. */
+export function resolveCursorConfig(config: Config): CursorAdapterConfig {
+  return {
+    proxyEndpoint: config.proxyEndpoint,
+    cursorApiKey: config.cursorApiKey,
+    stigmerToken: config.stigmerToken,
+    stigmerTokenRef: config.stigmerTokenRef,
+    workspaceRootDir: config.workspaceRootDir,
+    cloudModeEnabled: config.cloudModeEnabled,
+    agentResolveTimeoutMs: config.agentResolveTimeoutMs,
+  };
+}
+
+/** What `boot` leaves behind for the turns: the config slice and the engine turn, loaded after the interceptors. */
+interface BootedCursorHarness {
+  readonly config: CursorAdapterConfig;
+  readonly runCursorTurn: typeof import("./turn.js").runCursorTurn;
+}
+
+export function createCursorAdapter(): HarnessAdapter {
+  let booted: BootedCursorHarness | undefined;
+
+  return {
+    name: "cursor",
+    capabilities: CURSOR_CAPABILITIES,
+
+    /**
+     * Install the proxy transport, prove the HTTP/2 patch reached the facade,
+     * then load the SDK slice — in that order, for the reason in the header.
+     * Runs before bootstrap resolution, so `bootConfig` carries no Temporal
+     * coordinates yet; every field the slice reads is known at that point.
+     * Idempotent: a re-boot rebinds the interceptors and re-reads the slice.
+     */
+    async boot(bootConfig: Config): Promise<void> {
+      if (bootConfig.proxyEndpoint && !bootConfig.proxyTokenRef) {
+        throw new Error(
+          "cursor adapter: a proxy endpoint needs Config.proxyTokenRef (the composition root binds its proxy credential there; see config.ts)",
+        );
+      }
+      // The Cursor SDK's REST client resolves `fetch` at call time and its
+      // Connect transport opens native HTTP/2 sessions; the two interceptors
+      // route the first through the proxy and stamp the second with the proxy
+      // credential and the execution id. Both are no-ops without a proxy.
+      installFetchInterceptor({
+        proxyEndpoint: bootConfig.proxyEndpoint ?? undefined,
+        proxyTokenRef: bootConfig.proxyTokenRef,
+      });
+      installHttp2Interceptor({
+        proxyEndpoint: bootConfig.proxyEndpoint ?? undefined,
+        proxyTokenRef: bootConfig.proxyTokenRef,
+      });
+      markBoot("interceptors_installed");
+      // Fail loudly at boot if a load-order regression left the node:http2 ESM
+      // facade unpatched (otherwise BiDi streams would silently 401). No-op
+      // when the interceptor is unconfigured (no proxy).
+      await assertHttp2ConnectPatched();
+
+      const { runCursorTurn } = await import("./turn.js");
+      booted = { config: resolveCursorConfig(bootConfig), runCursorTurn };
+    },
+
+    /** Close every parked agent (their executor leases and MCP subprocesses). */
+    async shutdown(): Promise<void> {
+      closeAllCachedAgents();
+    },
+
+    /** The session is done on this host: close the agent parked for it, if any (#215). */
+    async releaseSession(sessionId: string): Promise<void> {
+      evictSessionAgent(sessionId);
+    },
+
+    async runTurn(input: TurnInput, sink: TurnSink): Promise<TurnOutcome> {
+      if (booted === undefined) {
+        throw new Error("cursor adapter: runTurn before boot (the registry boots every adapter before the worker polls)");
+      }
+      return booted.runCursorTurn(input, sink, booted.config);
+    },
+  };
+}

package/src/activities/execute-cursor/approval-state.ts

@@ -346,7 +346,7 @@ export function emitCursorGrantReceipts(
  */
 export function buildApprovalGrants(
   pendingApprovals: PendingApproval[],
-  decisions: Map<string, ApprovalAction>,
+  decisions: ReadonlyMap<string, ApprovalAction>,
   contentDigests?: Map<string, string>,
 ): ApprovalGrant[] {
   const grants: ApprovalGrant[] = [];
@@ -406,7 +406,7 @@ function parseArgs(argsPreview: string): Record<string, unknown> | undefined {
  * generated hook script (from approval-policy.ts), not carried here.
  */
 export function buildApprovalState(
-  mergedPolicies: Map<string, MergedToolPolicy>,
+  mergedPolicies: ReadonlyMap<string, MergedToolPolicy>,
   globalBypass: boolean,
   leasedCategories: ReadonlySet<ApprovalCategory>,
   grants?: ApprovalGrant[],

package/src/activities/execute-cursor/capture-flow.ts

@@ -14,8 +14,12 @@
  *    observational/audit records at their transcript positions, while
  *    `file_change_sets` remains the single DECISION surface.
  *
- * The three turn-boundary functions keep their original signatures so the
- * activity wiring (index.ts) and the cutover tests are unchanged.
+ * The resume-time reconcile is NOT here since S2 M2: the turn runtime's
+ * `reconcileReinvocation` (`harness/turn-context.ts`) calls the shared
+ * reconcile directly under {@link CURSOR_FILE_REVIEW_IDENTITY}, the one
+ * export that carries the two Cursor facts it needs. The two capture
+ * functions keep their original signatures so the activity wiring (index.ts)
+ * and the cutover tests are unchanged.
  */
 
 import { readFile } from "node:fs/promises";
@@ -30,10 +34,8 @@ import { readCasObservations } from "./cas-observations.js";
 import { contentDigest } from "../../shared/file-tools.js";
 import { isToolCallRowHidden, stampFileEditRow } from "../../shared/tool-row.js";
 import {
-  applyCaptureDecisions as sharedApplyCaptureDecisions,
   captureBaselineToLedger as sharedCaptureBaselineToLedger,
   captureCandidateToLedger as sharedCaptureCandidateToLedger,
-  type CaptureResumeResult,
 } from "../../shared/filereview/capture.js";
 import {
   createGitProgressSubstrate,
@@ -50,8 +52,7 @@ import { partitionIgnoredPathsBySecret } from "../../shared/filereview/secret-pa
 import { casBlobReader, type CasPathCapture } from "../../shared/filereview/cas-substrate.js";
 import type { GitSubstrateChange as GitCapturedChange } from "../../shared/filereview/git-substrate.js";
 import type { ArtifactStorage } from "../../shared/artifact-storage.js";
-
-export type { CaptureResumeResult };
+import type { FileReviewIdentity } from "../../harness/capabilities.js";
 
 /** The harness id the projection reads from the BASELINE payload (load-bearing). */
 const HARNESS_ID = "cursor";
@@ -67,6 +68,17 @@ const CURSOR_RUNNER_OWNED_PATHS: readonly string[] = [
   ".cursor/rules/stigmer-tool-approval.mdc",
 ];
 
+/**
+ * The two facts the runtime's resume-time reconcile needs from this harness
+ * (`harness/turn-context.ts` `reconcileReinvocation`): the same id and
+ * exclude list the capture functions below stamp and apply, so the baseline a
+ * turn authors and the reconcile a resume runs agree by construction.
+ */
+export const CURSOR_FILE_REVIEW_IDENTITY: FileReviewIdentity = {
+  harnessId: HARNESS_ID,
+  excludePaths: CURSOR_RUNNER_OWNED_PATHS,
+};
+
 // `deriveCaptureMode` is the single capture-vs-deny-gate decision, now shared by
 // BOTH harnesses from `shared/filereview/capture.ts`. Re-exported here so existing
 // Cursor imports (index.ts, the deny-gate-exact-apply seam test) keep resolving
@@ -326,41 +338,6 @@ async function readFileOrNull(absolutePath: string): Promise<Uint8Array | null>
   }
 }
 
-/**
- * Resume: reconcile the working tree to the change set's DECIDED decisions
- * (keep approved "after" bytes, snap rejected/undecided back to baseline,
- * hash-verified), author RECONCILED / FAILED, and release the refs. Delegates to
- * the shared orchestration with the Cursor harness id + exclude paths.
- *
- * `storage` threads the CAS blob store + reader so gitignored (CAS) files in the
- * change set reconcile from the durable manifest — approved after-blobs written
- * (hash-verified), rejected files snapped back to their before-blobs. Omit for a
- * git-only harness/turn; the shared CAS branch is then skipped. The read path is
- * the same one `exact-apply` already uses (`ArtifactStorage.download`).
- */
-export function applyCaptureDecisions(opts: {
-  readonly status: AgentExecutionStatus;
-  readonly gitRoot: string;
-  readonly executionId: string;
-  readonly changeSet: FileChangeSet;
-  readonly storage?: ArtifactStorage;
-  /**
-   * True (default) for a git work tree; false for a CAS-only non-git workspace
-   * (Slice 2c). When false the reconcile never consults git refs — it is driven
-   * entirely by the durable CAS manifest.
-   */
-  readonly gitWorkspace?: boolean;
-}): Promise<CaptureResumeResult> {
-  const { storage, ...rest } = opts;
-  return sharedApplyCaptureDecisions({
-    ...rest,
-    harnessId: HARNESS_ID,
-    excludePaths: CURSOR_RUNNER_OWNED_PATHS,
-    storage,
-    readBlob: storage ? casBlobReader(storage) : undefined,
-  });
-}
-
 // ---------------------------------------------------------------------------
 // Cursor-specific presentation
 // ---------------------------------------------------------------------------

package/src/activities/execute-cursor/cursor-capabilities.ts

@@ -0,0 +1,35 @@
+/**
+ * The Cursor harness's capability flags — the facts about `@cursor/sdk` the
+ * turn runtime branches on, declared once (`harness/capabilities.ts` has the
+ * matrix and the meaning of each flag).
+ *
+ *  - `deny-and-retry`: an out-of-process hook denies a gated tool, the
+ *    denial lands in the session ledger, the run is cancelled, and the next
+ *    invocation re-runs with grants (`hook-script.ts`, `approval-state.ts`).
+ *  - `engine-minted`: the agent id exists only once `Agent.create` returns;
+ *    the adapter binds it through `TurnSink.bindHarnessState` before its
+ *    first persist.
+ *  - No system prompt: instructions ride the first user message
+ *    (`prompt-builder.ts`).
+ *  - Sub-agents through the SDK's `agents` option (`subagent-config.ts`).
+ *  - No tool restriction in the SDK config: the hook's "disabled" arm
+ *    enforces `enabledTools` at call time (issue #350).
+ *  - PNG and JPEG inline; the transport re-sniffs (`shared/attachment-vision.ts`).
+ *  - File review under the `cursor` harness id, with the transient
+ *    `.cursor/hooks.json` the gate writes excluded from every diff
+ *    (`capture-flow.ts`).
+ */
+
+import type { HarnessCapabilities } from "../../harness/capabilities.js";
+import { CURSOR_VISION_PROFILE } from "../../shared/attachment-vision.js";
+import { CURSOR_FILE_REVIEW_IDENTITY } from "./capture-flow.js";
+
+export const CURSOR_CAPABILITIES: HarnessCapabilities = {
+  pausePrimitive: "deny-and-retry",
+  stateIdSource: "engine-minted",
+  systemPrompt: false,
+  subAgents: true,
+  toolRestriction: false,
+  visionProfile: CURSOR_VISION_PROFILE,
+  fileReview: CURSOR_FILE_REVIEW_IDENTITY,
+};

package/src/activities/execute-cursor/cursor-mcp-config.ts

@@ -42,7 +42,7 @@ export type CursorMcpServerConfig =
  * expressed here — the HITL hook enforces it (see ResolvedMcpServer.enabledTools).
  */
 export function toCursorMcpConfig(
-  servers: ResolvedMcpServer[],
+  servers: readonly ResolvedMcpServer[],
 ): Record<string, CursorMcpServerConfig> {
   const result: Record<string, CursorMcpServerConfig> = {};
 
@@ -75,7 +75,7 @@ export function toCursorMcpConfig(
  * Used as a pre-flight check before agent.send() to surface config issues early.
  */
 export function validateMcpServerEnv(
-  servers: ResolvedMcpServer[],
+  servers: readonly ResolvedMcpServer[],
   usages: McpServerUsage[],
 ): string[] {
   const warnings: string[] = [];

package/src/activities/execute-cursor/fetch-interceptor.ts

@@ -9,15 +9,17 @@
  * This is the JavaScript-level equivalent of LangChain's base_url parameter
  * that the Python agent-runner uses for the LLM proxy pattern.
  *
- * IMPORTANT: This module must be imported BEFORE @cursor/sdk to ensure the
- * interceptor is in place when the SDK initializes its HTTP client.
+ * Installed by the Cursor adapter's `boot` (adapter.ts), which the registry
+ * runs in both composition roots before Temporal coordinates are resolved and
+ * before the adapter loads `@cursor/sdk`, so the interceptor is in place
+ * before the SDK issues its first request. The proxy credential is read per
+ * request from the ref the root bound as `Config.proxyTokenRef`.
  *
  * When STIGMER_PROXY_ENDPOINT is not set, this module is a no-op.
  */
 
-import { AsyncLocalStorage } from "node:async_hooks";
-
 import { TimingRecorder, emitTimingLog } from "../../shared/cold-start-timing.js";
+import { getExecutionContext } from "../../shared/execution-context.js";
 
 /** One REST path's timing identity: the emitted timeline event and its
  * single segment name. */
@@ -56,22 +58,37 @@ const CURSOR_DOMAINS = [
 
 interface ProxyConfig {
   proxyEndpoint: string;
-  stigmerToken: string;
+  /**
+   * The proxy credential, read on EVERY request (never copied): the
+   * composition root that installed this interceptor owns the ref and
+   * rotates it in place (the static root's sandbox-token renewal, the
+   * manager's token coordinator), so a rotation reaches the next request
+   * without a call into this module. Which credential it is differs per
+   * root — the static root's control-plane token, the manager's minted
+   * runner token (Q-S2-7) — and this module never knows which.
+   */
+  proxyTokenRef: { readonly current: string | null };
   executionId?: string;
 }
 
-let interceptorConfig: ProxyConfig | null = null;
-const originalFetch = globalThis.fetch;
-
-interface ExecutionContextStore {
-  executionId: string;
+/**
+ * The `Authorization`-style header value for the current proxy credential,
+ * or undefined when the ref is empty. Empty is unreachable by construction
+ * today (neither root ever writes null into the ref it bound), so the request
+ * goes out without the header and the proxy's 401 is the diagnostic; a
+ * runner-side throw here would surface inside the SDK's transport, a path
+ * nothing exercises.
+ */
+function bearer(config: ProxyConfig): string | undefined {
+  const token = config.proxyTokenRef.current;
+  return token === null ? undefined : `Bearer ${token}`;
 }
 
-const executionContext = new AsyncLocalStorage<ExecutionContextStore>();
+let interceptorConfig: ProxyConfig | null = null;
+const originalFetch = globalThis.fetch;
 
-export function getExecutionContext(): AsyncLocalStorage<ExecutionContextStore> {
-  return executionContext;
-}
+/** The execution-scoped store the headers below are stamped from (`shared/execution-context.ts`). */
+const executionContext = getExecutionContext();
 
 /**
  * Connect RPC path prefixes used by the Cursor SDK. Most requests with
@@ -193,7 +210,11 @@ function rewriteUrl(originalUrl: string, proxyEndpoint: string): string {
  */
 function replaceAuth(init: RequestInit | undefined, config: ProxyConfig): RequestInit {
   const headers = new Headers(init?.headers);
-  headers.set("authorization", `Bearer ${config.stigmerToken}`);
+  const auth = bearer(config);
+  // Replace, never leak: with no proxy credential the SDK's own authorization
+  // (a Cursor credential) must still not reach the proxy.
+  if (auth !== undefined) headers.set("authorization", auth);
+  else headers.delete("authorization");
   const ctx = executionContext.getStore();
   const effectiveExecutionId = ctx?.executionId ?? config.executionId;
   if (effectiveExecutionId) {
@@ -210,7 +231,8 @@ function replaceAuth(init: RequestInit | undefined, config: ProxyConfig): Reques
  */
 function injectProxyAuth(init: RequestInit | undefined, config: ProxyConfig): RequestInit {
   const headers = new Headers(init?.headers);
-  headers.set("x-stigmer-auth", `Bearer ${config.stigmerToken}`);
+  const auth = bearer(config);
+  if (auth !== undefined) headers.set("x-stigmer-auth", auth);
   const ctx = executionContext.getStore();
   const effectiveExecutionId = ctx?.executionId ?? config.executionId;
   if (effectiveExecutionId) {
@@ -362,21 +384,26 @@ async function fetchWithProxyAuth(
 }
 
 /**
- * Install the global fetch interceptor. Call once at startup, BEFORE
- * importing @cursor/sdk.
+ * Install the global fetch interceptor, at boot, BEFORE `@cursor/sdk` is
+ * imported. Idempotent: a second install rebinds the config (a worker may
+ * re-boot its harnesses) and never captures the interceptor itself as the
+ * original fetch.
  *
  * When proxyEndpoint is empty or not provided, the interceptor is not
  * installed and all fetch calls pass through to the original implementation.
+ * A proxy endpoint with no credential bound at install is a configuration
+ * defect and fails the boot here, the same failure as before the ref (the
+ * ref is read per request afterwards; only its presence is judged now).
  */
 export function installFetchInterceptor(config: {
   proxyEndpoint: string | undefined;
-  stigmerToken: string | undefined;
+  proxyTokenRef: { readonly current: string | null } | undefined;
 }): void {
   if (!config.proxyEndpoint) {
     return;
   }
 
-  if (!config.stigmerToken) {
+  if (!config.proxyTokenRef || config.proxyTokenRef.current === null) {
     throw new Error(
       "STIGMER_TOKEN is required when STIGMER_PROXY_ENDPOINT is set. " +
       "In proxy mode, the runner authenticates with Stigmer's proxy using STIGMER_TOKEN.",
@@ -385,7 +412,7 @@ export function installFetchInterceptor(config: {
 
   interceptorConfig = {
     proxyEndpoint: config.proxyEndpoint,
-    stigmerToken: config.stigmerToken,
+    proxyTokenRef: config.proxyTokenRef,
   };
 
   globalThis.fetch = interceptedFetch;
@@ -395,18 +422,6 @@ export function installFetchInterceptor(config: {
   );
 }
 
-/**
- * Update the auth token on the live interceptor config. Must be called
- * whenever the Stigmer JWT is refreshed (e.g. via IPC updateToken) so
- * that fetch-intercepted REST calls (token exchange, /v1/models) use the
- * current token instead of the one frozen at install time.
- */
-export function updateInterceptorToken(token: string): void {
-  if (interceptorConfig) {
-    interceptorConfig = { ...interceptorConfig, stigmerToken: token };
-  }
-}
-
 /**
  * Update the execution ID on the active interceptor (legacy global path).
  * Prefer {@link runWithExecutionContext} for concurrent-safe isolation.
@@ -419,18 +434,6 @@ export function setInterceptorExecutionId(executionId: string | undefined): void
   }
 }
 
-/**
- * Run an async function with execution-scoped context. The executionId is
- * propagated through the async call chain via AsyncLocalStorage, ensuring
- * concurrent activities on the same runner process don't overwrite each
- * other's proxy headers.
- */
-export function runWithExecutionContext<T>(
-  executionId: string,
-  fn: () => Promise<T>,
-): Promise<T> {
-  return executionContext.run({ executionId }, fn);
-}
 
 /**
  * Remove the interceptor and restore the original fetch. Primarily for

package/src/activities/execute-cursor/http2-interceptor.ts

@@ -16,11 +16,14 @@
  *
  * LOAD ORDER IS THEREFORE LOAD-BEARING: this interceptor MUST be installed
  * before the first connect-node import in the process. The runner enforces this
- * by (a) keeping connect-node out of the pre-install static module graph
- * (bootstrap.ts loads StigmerClient via dynamic import) and (b) installing this
- * interceptor before resolving Temporal coordinates / importing the SDK in the
- * runner factories. assertHttp2ConnectPatched() verifies the ESM-facade view at
- * boot so any future regression fails loudly instead of silently 401-ing.
+ * by (a) keeping connect-node out of the pre-boot static module graph
+ * (bootstrap.ts and harness/registry.ts load StigmerClient via dynamic import;
+ * adapter.ts loads the SDK inside boot) and (b) installing this interceptor in
+ * the Cursor adapter's `boot`, which the registry runs in both composition
+ * roots before Temporal coordinates are resolved. assertHttp2ConnectPatched()
+ * verifies the ESM-facade view right after the install so any future
+ * regression fails loudly instead of silently 401-ing;
+ * src/__tests__/harness-boot-order.test.ts runs that boot in a fresh process.
  *
  * This module patches `http2.connect()` to wrap returned sessions. The
  * wrapped session's `request()` method reads the execution ID from the
@@ -42,7 +45,7 @@
 
 import { createRequire } from "node:module";
 import type http2Type from "node:http2";
-import { getExecutionContext } from "./fetch-interceptor.js";
+import { getExecutionContext } from "../../shared/execution-context.js";
 
 // Use require() to get the ACTUAL CJS module singleton. Mutations here
 // are visible to all importers including ESM namespace imports, because
@@ -56,7 +59,14 @@ const STIGMER_AUTH_HEADER = "x-stigmer-auth";
 interface Http2InterceptorConfig {
   proxyHostname: string;
   proxyPort: string;
-  stigmerToken: string;
+  /**
+   * The proxy credential, read on EVERY stream (never copied): the root that
+   * installed this interceptor owns the ref and rotates it in place, so a
+   * rotation reaches the next `request()` on an already-open session without
+   * a call into this module (see fetch-interceptor.ts for the two roots'
+   * bindings, Q-S2-7).
+   */
+  proxyTokenRef: { readonly current: string | null };
 }
 
 let config: Http2InterceptorConfig | null = null;
@@ -110,10 +120,15 @@ function wrapSession(session: http2Type.ClientHttp2Session): http2Type.ClientHtt
     }
 
     const ctx = getExecutionContext().getStore();
-    const augmented: http2Type.OutgoingHttpHeaders = {
-      ...headers,
-      [STIGMER_AUTH_HEADER]: `Bearer ${config.stigmerToken}`,
-    };
+    const augmented: http2Type.OutgoingHttpHeaders = { ...headers };
+    // An empty ref is unreachable by construction today (no root writes null
+    // into the ref it bound); the stream then goes out without the header and
+    // the proxy's 401 is the diagnostic, rather than a throw inside the SDK's
+    // transport, a path nothing exercises.
+    const token = config.proxyTokenRef.current;
+    if (token !== null) {
+      augmented[STIGMER_AUTH_HEADER] = `Bearer ${token}`;
+    }
     if (ctx?.executionId) {
       augmented[EXECUTION_ID_HEADER] = ctx.executionId;
     }
@@ -124,21 +139,27 @@ function wrapSession(session: http2Type.ClientHttp2Session): http2Type.ClientHtt
 }
 
 /**
- * Install the HTTP/2 interceptor. Call once at startup, BEFORE importing
- * @cursor/sdk.
+ * Install the HTTP/2 interceptor, at boot, BEFORE `@cursor/sdk` (and so
+ * connect-node) is imported. Idempotent: a second install rebinds the config
+ * (a worker may re-boot its harnesses) and leaves the one patch in place —
+ * re-capturing `http2.connect` here would take the patched function as the
+ * original and wrap every proxy session twice.
  *
- * When proxyEndpoint is not provided, the interceptor is not installed
- * and all http2.connect() calls pass through to the original.
+ * When proxyEndpoint is not provided, or no credential ref is bound, the
+ * interceptor is not installed and all http2.connect() calls pass through to
+ * the original. (The fetch interceptor, installed first, throws on a proxy
+ * without a credential; this one stays a silent no-op as it always has, so a
+ * caller that installs only this half keeps its historical posture.)
  */
 export function installHttp2Interceptor(opts: {
   proxyEndpoint: string | undefined;
-  stigmerToken: string | undefined;
+  proxyTokenRef: { readonly current: string | null } | undefined;
 }): void {
   if (!opts.proxyEndpoint) {
     return;
   }
 
-  if (!opts.stigmerToken) {
+  if (!opts.proxyTokenRef || opts.proxyTokenRef.current === null) {
     return;
   }
 
@@ -150,7 +171,11 @@ export function installHttp2Interceptor(opts: {
     return;
   }
 
-  config = { proxyHostname: parsed.hostname, proxyPort: parsed.port, stigmerToken: opts.stigmerToken };
+  const alreadyPatched = config !== null;
+  config = { proxyHostname: parsed.hostname, proxyPort: parsed.port, proxyTokenRef: opts.proxyTokenRef };
+  if (alreadyPatched) {
+    return;
+  }
   originalConnect = http2.connect;
 
   http2.connect = function patchedConnect(
@@ -205,26 +230,14 @@ export async function assertHttp2ConnectPatched(): Promise<void> {
       "[http2-interceptor] node:http2 ESM facade is unpatched: connect-node imported " +
         "node:http2 before installHttp2Interceptor() ran, so its frozen namespace still " +
         "holds the original http2.connect. BiDi streams would omit x-stigmer-auth and 401. " +
-        "Fix the load order: keep @connectrpc/connect-node out of the pre-install static " +
-        "module graph (load StigmerClient via dynamic import) and install this interceptor " +
-        "before resolving Temporal coordinates / importing @cursor/sdk. See bootstrap.ts " +
-        "and the runner factories.",
+        "Fix the load order: keep @connectrpc/connect-node out of the pre-boot static module " +
+        "graph (load StigmerClient via dynamic import, as bootstrap.ts and harness/registry.ts " +
+        "do) and keep @cursor/sdk behind the Cursor adapter's boot (adapter.ts loads turn.ts " +
+        "after this install). See src/__tests__/harness-boot-order.test.ts.",
     );
   }
 }
 
-/**
- * Update the auth token on the live interceptor config. Must be called
- * whenever the Stigmer JWT is refreshed (e.g. via IPC updateToken) so
- * that HTTP/2-intercepted streams use the current token instead of the
- * one frozen at install time.
- */
-export function updateHttp2InterceptorToken(token: string): void {
-  if (config) {
-    config = { ...config, stigmerToken: token };
-  }
-}
-
 /**
  * Remove the interceptor and restore the original http2.connect.
  * Primarily for testing.