@stigmer/runner 3.4.0 → 3.5.0

package/src/client/__tests__/stigmer-client.test.ts

@@ -51,10 +51,19 @@ function fakeTokenOfType(tokenType: string): string {
   return `${b64({ alg: "RS256" })}.${b64({ token_type: tokenType })}.sig`;
 }
 
+/**
+ * Run the request through the full interceptor chain, composed the same way
+ * the transport composes it (first interceptor outermost). The client
+ * registers more than just the auth interceptor (e.g. OTel trace
+ * propagation), so invoking a single one by index would silently test the
+ * wrong thing.
+ */
 async function runInterceptor(req: ReturnType<typeof makeRequest>) {
-  const interceptor = capturedInterceptors[0]!;
   const next = vi.fn().mockResolvedValue({ ok: true });
-  const handler = interceptor(next);
+  const handler = capturedInterceptors.reduceRight(
+    (inner, interceptor) => interceptor(inner),
+    next as (req: any) => Promise<any>,
+  );
   await handler(req as any);
   return { next, req };
 }
@@ -330,6 +339,72 @@ describe("StigmerClient", () => {
     });
   });
 
+  describe("getRunnerScopedToken scope mapping", () => {
+    function clientWithPlatformQuery(response: Record<string, unknown>) {
+      const client = new StigmerClient({ endpoint: "http://localhost", token: null });
+      const getRunnerScopedToken = vi.fn().mockResolvedValue(response);
+      // Reach into the private generated client: the mocked createClient()
+      // returned {}, so install the method it would have provided.
+      (client as any).platformQuery = { getRunnerScopedToken };
+      return { client, rpc: getRunnerScopedToken };
+    }
+
+    it("maps agentExecutionId onto its oneof arm", async () => {
+      const { client, rpc } = clientWithPlatformQuery({ runnerScopedToken: "tok" });
+
+      await client.getRunnerScopedToken({ agentExecutionId: "aex_1" });
+
+      const input = rpc.mock.calls[0]![0];
+      expect(input.scope).toEqual({ case: "agentExecutionId", value: "aex_1" });
+    });
+
+    it("maps workflowExecutionId onto its oneof arm", async () => {
+      const { client, rpc } = clientWithPlatformQuery({ runnerScopedToken: "tok" });
+
+      await client.getRunnerScopedToken({ workflowExecutionId: "wfx_1" });
+
+      const input = rpc.mock.calls[0]![0];
+      expect(input.scope).toEqual({ case: "workflowExecutionId", value: "wfx_1" });
+    });
+
+    it("maps poolClaimSessionId onto the pool_claim message arm", async () => {
+      const { client, rpc } = clientWithPlatformQuery({ runnerScopedToken: "tok" });
+
+      await client.getRunnerScopedToken({ poolClaimSessionId: "ses_1" });
+
+      const input = rpc.mock.calls[0]![0];
+      expect(input.scope.case).toBe("poolClaim");
+      expect(input.scope.value.sessionId).toBe("ses_1");
+    });
+
+    it("authenticates with the caller token per-call when one is supplied (pool attach)", async () => {
+      const { client, rpc } = clientWithPlatformQuery({ runnerScopedToken: "tok" });
+
+      await client.getRunnerScopedToken({ poolClaimSessionId: "ses_1" }, "pool-tok");
+
+      expect(rpc).toHaveBeenCalledWith(
+        expect.anything(),
+        { headers: { authorization: "Bearer pool-tok" } },
+      );
+    });
+
+    it("passes no call options without a caller token", async () => {
+      const { client, rpc } = clientWithPlatformQuery({ runnerScopedToken: "tok" });
+
+      await client.getRunnerScopedToken({ agentExecutionId: "aex_1" });
+
+      expect(rpc).toHaveBeenCalledWith(expect.anything(), undefined);
+    });
+
+    it("returns undefined when the server mints nothing (presence-based contract)", async () => {
+      const { client } = clientWithPlatformQuery({ runnerScopedToken: "" });
+
+      const scoped = await client.getRunnerScopedToken({ poolClaimSessionId: "ses_1" });
+
+      expect(scoped).toBeUndefined();
+    });
+  });
+
   describe("getExecutionContextByExecutionId per-call credential", () => {
     it("passes the scoped token as a per-call authorization header", async () => {
       const client = new StigmerClient({ endpoint: "http://localhost", token: null });

package/src/client/__tests__/token-claims.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { tokenTypeOf, isEmbeddedRunnerToken } from "../token-claims.js";
+import { tokenTypeOf, isEmbeddedRunnerToken, sessionIdClaimOf } from "../token-claims.js";
 
 /** Build an unsigned JWT-shaped token with the given payload. */
 function fakeJwt(payload: Record<string, unknown>): string {
@@ -32,6 +32,20 @@ describe("tokenTypeOf", () => {
   });
 });
 
+describe("sessionIdClaimOf", () => {
+  it("extracts the session_id claim of a session sandbox token", () => {
+    expect(sessionIdClaimOf(fakeJwt({ token_type: "sandbox", session_id: "ses_1" })))
+      .toBe("ses_1");
+  });
+
+  it("returns undefined when the claim is absent or non-string", () => {
+    expect(sessionIdClaimOf(fakeJwt({ token_type: "pool_sandbox" }))).toBeUndefined();
+    expect(sessionIdClaimOf(fakeJwt({ session_id: 7 }))).toBeUndefined();
+    expect(sessionIdClaimOf(null)).toBeUndefined();
+    expect(sessionIdClaimOf("garbage")).toBeUndefined();
+  });
+});
+
 describe("isEmbeddedRunnerToken", () => {
   it("is true only for token_type=embedded_runner", () => {
     expect(isEmbeddedRunnerToken(fakeJwt({ token_type: "embedded_runner" }))).toBe(true);

package/src/client/stigmer-client.ts

@@ -10,6 +10,7 @@
 
 import { createClient, type Client, type Transport } from "@connectrpc/connect";
 import { createGrpcTransport } from "@connectrpc/connect-node";
+import { context as otelContext, propagation } from "@opentelemetry/api";
 import { AgentExecutionCommandController } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/command_pb";
 import { AgentExecutionQueryController } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/query_pb";
 import { ExecutionContextQueryController } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/query_pb";
@@ -87,10 +88,31 @@ export interface RunnerScopedToken {
 /**
  * Names the unit of dispatched work a scoped runner token should serve.
  * Exactly one id must be set — mirrors the proto oneof.
+ *
+ * `poolClaimSessionId` is the warm-pool attach exchange: a pool sandbox
+ * presenting its pool_sandbox credential for the session it was claimed for
+ * (the server authorizes against the claim record, not the caller's FGA
+ * relations). The execution arms remain embedded_runner-only.
  */
 export type RunnerScopedTokenScope =
   | { agentExecutionId: string }
-  | { workflowExecutionId: string };
+  | { workflowExecutionId: string }
+  | { poolClaimSessionId: string };
+
+/**
+ * Map the scope union onto the proto oneof init shape. The narrowing chain is
+ * exhaustive: adding a variant to {@link RunnerScopedTokenScope} breaks the
+ * final branch's type until it is mapped here.
+ */
+function toRunnerScopedTokenOneof(scope: RunnerScopedTokenScope) {
+  if ("agentExecutionId" in scope) {
+    return { case: "agentExecutionId", value: scope.agentExecutionId } as const;
+  }
+  if ("workflowExecutionId" in scope) {
+    return { case: "workflowExecutionId", value: scope.workflowExecutionId } as const;
+  }
+  return { case: "poolClaim", value: { sessionId: scope.poolClaimSessionId } } as const;
+}
 
 /**
  * A shared mutable token reference. When provided, the interceptor
@@ -145,6 +167,19 @@ export class StigmerClient {
     this.transport = createGrpcTransport({
       baseUrl: options.endpoint,
       interceptors: [
+        // W3C trace-context propagation: stamps `traceparent` (and baggage)
+        // from the active OTel context onto every outgoing RPC, so a runner
+        // span and the server-side request span join into one distributed
+        // trace (the server's GrpcRequestTraceIdInterceptor already parses
+        // traceparent). When OTel is not initialized — the OSS default, no
+        // OTEL_EXPORTER_OTLP_ENDPOINT — the global propagator is a no-op and
+        // this adds nothing to the request.
+        (next) => async (req) => {
+          propagation.inject(otelContext.active(), req.header, {
+            set: (carrier, key, value) => carrier.set(key, value),
+          });
+          return next(req);
+        },
         // Credential selection lives here — one tested decision point — rather
         // than at call sites. Precedence:
         //
@@ -276,15 +311,25 @@ export class StigmerClient {
    * sandbox token a cloud sandbox runner receives at provisioning. Returns
    * undefined when the server does not mint (OSS, or no signing key) —
    * presence-based, like the bootstrap token fields.
+   *
+   * `callerToken` authenticates the exchange per-call instead of the
+   * process-wide runner credential. The warm-pool attach uses it: a pool
+   * member exchanges with its pool_sandbox token, which is not the runner
+   * credential the interceptor would pick for this method.
    */
   async getRunnerScopedToken(
     scope: RunnerScopedTokenScope,
+    callerToken?: string,
   ): Promise<RunnerScopedToken | undefined> {
-    const input = create(GetRunnerScopedTokenInputSchema,
-      "agentExecutionId" in scope
-        ? { scope: { case: "agentExecutionId", value: scope.agentExecutionId } }
-        : { scope: { case: "workflowExecutionId", value: scope.workflowExecutionId } });
-    const res = await this.platformQuery.getRunnerScopedToken(input);
+    const input = create(GetRunnerScopedTokenInputSchema, {
+      scope: toRunnerScopedTokenOneof(scope),
+    });
+    const res = await this.platformQuery.getRunnerScopedToken(
+      input,
+      callerToken
+        ? { headers: { authorization: `Bearer ${callerToken}` } }
+        : undefined,
+    );
     if (!res.runnerScopedToken) {
       return undefined;
     }

package/src/client/token-claims.ts

@@ -12,16 +12,26 @@
 /** The `token_type` claim value of a bootstrap-minted embedded runner token. */
 export const TOKEN_TYPE_EMBEDDED_RUNNER = "embedded_runner";
 
+/** The `token_type` claim value of a session sandbox token. */
+export const TOKEN_TYPE_SANDBOX = "sandbox";
+
+/** The `token_type` claim value of a warm-pool member's pre-claim credential. */
+export const TOKEN_TYPE_POOL_SANDBOX = "pool_sandbox";
+
 const CLAIM_TOKEN_TYPE = "token_type";
+const CLAIM_SESSION_ID = "session_id";
 
 /**
- * Extract the `token_type` claim from a JWT without verifying it.
+ * Extract one string claim from a JWT without verifying it.
  *
  * Returns undefined for null/malformed tokens and for tokens without the
- * claim (e.g. a user's Auth0 token) — callers branch on the specific value,
- * so "unknown" and "absent" collapse to the same answer.
+ * claim — callers branch on the specific value, so "unknown" and "absent"
+ * collapse to the same answer.
  */
-export function tokenTypeOf(token: string | null | undefined): string | undefined {
+function claimOf(
+  token: string | null | undefined,
+  claim: string,
+): string | undefined {
   if (!token) return undefined;
   const parts = token.split(".");
   if (parts.length !== 3) return undefined;
@@ -29,13 +39,26 @@ export function tokenTypeOf(token: string | null | undefined): string | undefine
     const payload = JSON.parse(
       Buffer.from(parts[1]!, "base64url").toString("utf8"),
     ) as Record<string, unknown>;
-    const tokenType = payload[CLAIM_TOKEN_TYPE];
-    return typeof tokenType === "string" ? tokenType : undefined;
+    const value = payload[claim];
+    return typeof value === "string" ? value : undefined;
   } catch {
     return undefined;
   }
 }
 
+/** Extract the `token_type` claim (e.g. a user's Auth0 token has none). */
+export function tokenTypeOf(token: string | null | undefined): string | undefined {
+  return claimOf(token, CLAIM_TOKEN_TYPE);
+}
+
+/**
+ * Extract the `session_id` claim of a session-scoped token. A claimed pool
+ * member reads its post-claim identity from this on restart.
+ */
+export function sessionIdClaimOf(token: string | null | undefined): string | undefined {
+  return claimOf(token, CLAIM_SESSION_ID);
+}
+
 /** Whether the token is a bootstrap-minted `embedded_runner` credential. */
 export function isEmbeddedRunnerToken(token: string | null | undefined): boolean {
   return tokenTypeOf(token) === TOKEN_TYPE_EMBEDDED_RUNNER;

package/src/main.ts

@@ -3,7 +3,7 @@
 /**
  * CLI entry point for the unified runner service.
  *
- * Two modes of operation:
+ * Three modes of operation:
  *
  * 1. Static mode (default): Reads configuration from environment variables,
  *    initializes OTel, creates a single-queue runner. Used by CLI daemon and
@@ -13,6 +13,13 @@
  *    stdin, manages per-session Workers dynamically. Used by the desktop app
  *    via the IPC protocol. Responses go to stdout; logs go to stderr.
  *
+ * 3. Pool mode (STIGMER_POOL_MEMBER_ID set): A warm-pool cloud sandbox. Boots
+ *    the runner manager, then serves whatever its Secret-injected credential
+ *    says it is: a pool_sandbox token means "blank member" (poll the
+ *    sandbox:{memberId} control queue for a claim), a session token means
+ *    "claimed member that restarted" (go straight to that session's queue).
+ *    See pool-member.ts for the identity model.
+ *
  * OTel is initialized here (not in the factory) because it mutates
  * global state that the consumer should control when embedding the
  * runner as a library.
@@ -23,11 +30,13 @@ import { readFileSync, readdirSync } from "node:fs";
 import { join, relative } from "node:path";
 import { createInterface } from "node:readline";
 import { preflightNodeRuntime } from "./preflight.js";
+import { markBoot, emitRunnerBootTiming } from "./shared/cold-start-timing.js";
 import { loadConfig } from "./config.js";
 import { initTracing, initMetrics } from "./otel.js";
 import { createStigmerRunner } from "./runner.js";
 import { createStigmerRunnerManager } from "./runner-manager.js";
 import type { StigmerRunnerManager } from "./runner-manager.js";
+import { decidePoolBoot, registerPoolMemberContext } from "./pool-member.js";
 import { buildReadyMessage } from "./ipc-protocol.js";
 import type { IpcCommand, IpcResponse } from "./ipc-protocol.js";
 
@@ -170,6 +179,121 @@ async function runManagerMode(config: import("./config.js").Config): Promise<voi
   await manager.shutdown();
 }
 
+// ─── Pool Mode ───────────────────────────────────────────────────────────────
+
+async function runPoolMode(
+  config: import("./config.js").Config,
+  memberId: string,
+): Promise<void> {
+  const otelShutdown = await initTracing("stigmer-runner");
+  const metricsShutdown = await initMetrics("stigmer-runner");
+
+  // The Secret-injected credential is the single source of truth for what this
+  // process serves (the control plane rewrites the Secret at claim time, and
+  // secretKeyRef env is read only at pod start — so a restart lands here with
+  // the post-claim identity). Decide before any expensive boot work.
+  const intent = decidePoolBoot(config.stigmerToken);
+  if (intent.kind === "invalid") {
+    throw new Error(`Pool member ${memberId} cannot boot: ${intent.reason}`);
+  }
+
+  const manager = await createStigmerRunnerManager({
+    temporalAddress: config.temporalAddress,
+    temporalNamespace: config.temporalNamespace,
+    stigmerEndpoint: config.stigmerBackendEndpoint,
+    stigmerToken: config.stigmerToken ?? undefined,
+    cursorApiKey: config.cursorApiKey || undefined,
+    workspaceRootDir: config.workspaceRootDir,
+    maxConcurrentActivitiesPerSession: config.maxConcurrentActivities,
+    proxyEndpoint: config.proxyEndpoint ?? undefined,
+    primaryModel: config.primaryModel,
+    checkpointerType: config.checkpointerType,
+    checkpointerProxyEndpoint: config.checkpointerProxyEndpoint ?? undefined,
+    cloudModeEnabled: config.cloudModeEnabled,
+    executionMode: config.mode,
+  });
+
+  let taskQueue: string;
+  if (intent.kind === "pool-control") {
+    registerPoolMemberContext({
+      memberId,
+      poolToken: config.stigmerToken!,
+      manager,
+    });
+    await manager.addPoolControl(memberId);
+    taskQueue = `sandbox:${memberId}`;
+  } else {
+    // Claimed member after a restart: the pool row is gone and nothing will
+    // dispatch on the control queue again, so no pool context, no control
+    // worker — just serve the session this pod already belongs to.
+    console.warn(
+      `[pool-member] ${memberId} restarted post-claim; ` +
+      `resuming session ${intent.sessionId}`,
+    );
+    await manager.addSession(intent.sessionId);
+    taskQueue = `session:${intent.sessionId}`;
+  }
+
+  // The boot window the pool exists to hide from users: emitted with pool
+  // context so the baseline harness can separate member pre-boots (background,
+  // free) from user-facing boots.
+  markBoot("worker_polling");
+  emitRunnerBootTiming({
+    task_queue: taskQueue,
+    mode: config.mode,
+    pool_member_id: memberId,
+    pool_rehydrated: intent.kind === "claimed-session",
+  });
+
+  console.warn(`[pool-member] ${memberId} ready (queue=${taskQueue})`);
+
+  // Idle-time warm-up (issue #209): pay the Cursor SDK's per-process SQLite
+  // cost now, while the member waits for a claim, instead of inside the
+  // claimed session's first resolve_agent. Fire-and-forget by design —
+  // pool-control members only (a claimed-session restart serves immediately
+  // and must not compete with its own executions).
+  if (intent.kind === "pool-control") {
+    const { warmCursorSdkStateStores } = await import("./activities/execute-cursor/sdk-warmup.js");
+    void warmCursorSdkStateStores().then((result) => {
+      if (result.warmed) {
+        console.log(`[pool-member] Cursor SDK state stores warmed in ${result.durationMs}ms`);
+      } else {
+        console.warn(
+          `[pool-member] Cursor SDK warm-up skipped (non-fatal): ${result.error} ` +
+          `(${result.durationMs}ms)`,
+        );
+      }
+    });
+  }
+
+  // Park until terminated; the workers poll in the background. Unlike manager
+  // mode there is no stdin driver — Kubernetes signals are the only exit.
+  await new Promise<void>((resolve) => {
+    let shutdownRequested = false;
+    const shutdown = (signal: string) => {
+      if (shutdownRequested) {
+        console.warn("Shutdown already in progress, ignoring duplicate signal");
+        return;
+      }
+      shutdownRequested = true;
+      console.warn(`[pool-member] Received ${signal}, shutting down gracefully...`);
+      void manager.shutdown().then(resolve, (err) => {
+        console.error("[pool-member] Shutdown failed:", err);
+        resolve();
+      });
+    };
+    process.on("SIGTERM", () => shutdown("SIGTERM"));
+    process.on("SIGINT", () => shutdown("SIGINT"));
+  });
+
+  if (metricsShutdown) {
+    await metricsShutdown();
+  }
+  if (otelShutdown) {
+    await otelShutdown();
+  }
+}
+
 // ─── Static Mode ─────────────────────────────────────────────────────────────
 
 async function runStaticMode(config: import("./config.js").Config): Promise<void> {
@@ -299,10 +423,14 @@ async function main(): Promise<void> {
     }
     process.exit(1);
   }
+  // Cold-start timeline: this first mark's span covers Node startup +
+  // entrypoint module loading + preflight (origin = process start).
+  markBoot("node_start_and_preflight");
 
   checkBuildFreshness();
 
   const config = loadConfig();
+  markBoot("config_loaded");
 
   // Route ALL Cursor SDK traffic through the Stigmer proxy in proxy mode.
   //
@@ -327,7 +455,11 @@ async function main(): Promise<void> {
     process.env.CURSOR_API_BASE_URL = proxyBase;
   }
 
-  const runnerMode = process.env.STIGMER_RUNNER_MODE === "manager" ? "manager" : "static";
+  const poolMemberId = process.env.STIGMER_POOL_MEMBER_ID?.trim() || undefined;
+  const runnerMode =
+    process.env.STIGMER_RUNNER_MODE === "manager" ? "manager"
+    : poolMemberId ? "pool"
+    : "static";
   console.warn(
     `[runner] mode=${runnerMode}, proxy=${config.proxyEndpoint ?? "none"}, ` +
     `hasToken=${!!config.stigmerToken}, workspace=${config.workspaceRootDir}, ` +
@@ -343,6 +475,11 @@ async function main(): Promise<void> {
     process.exit(0);
   }
 
+  if (runnerMode === "pool") {
+    await runPoolMode(config, poolMemberId!);
+    return;
+  }
+
   await runStaticMode(config);
 }
 

package/src/middleware/index.ts

@@ -24,7 +24,6 @@ import { createCostCapMiddleware, type CostCapMiddleware } from "./cost-cap.js";
 import { createErrorHintsMiddleware } from "./error-hints.js";
 import { createOtelSpansMiddleware } from "./otel-spans.js";
 
-export { createThinkTool } from "./think-tool.js";
 export type { GracefulStopMiddleware } from "./graceful-stop.js";
 export type { CostCapMiddleware } from "./cost-cap.js";
 export type { StigmerMiddleware, MiddlewareStackConfig } from "./types.js";

package/src/otel-metrics.ts

@@ -1,7 +1,13 @@
 /**
  * OTel metric instrument registry for the unified runner.
  *
- * Matches Go workflow-runner's `pkg/otel/metrics.go` instrument names.
+ * Instrument names follow the platform-wide `stigmer.*` convention shared
+ * with stigmer-service (SigNoz renders the dots as underscores). The
+ * cold-start instruments (runner boot / execution setup / pool attach) are
+ * sandbox-runner-specific — they mirror the `stigmer_timing` stdout
+ * timelines (see `shared/cold-start-timing.ts`) as dashboard aggregates and
+ * have no counterpart in other runners.
+ *
  * All instruments are created lazily on first access. When no
  * MeterProvider is configured, they are no-ops (OTel global fallback).
  */
@@ -20,6 +26,9 @@ export interface RunnerInstruments {
   readonly llmCallCount: Counter;
   readonly llmTokensInput: Counter;
   readonly llmTokensOutput: Counter;
+  readonly runnerBootDuration: Histogram;
+  readonly executionSetupDuration: Histogram;
+  readonly poolAttachDuration: Histogram;
 }
 
 let instruments: RunnerInstruments | null = null;
@@ -63,6 +72,21 @@ export async function getInstruments(): Promise<RunnerInstruments> {
       unit: "{token}",
       description: "Total output tokens produced across LLM calls",
     }),
+    // Cold-start timelines as dashboard aggregates (warm-agent-surfaces).
+    // Attribute cardinality is bounded by the emitter's whitelist in
+    // cold-start-timing.ts: `mode` / `harness` only, never per-pod values.
+    runnerBootDuration: meter.createHistogram("stigmer.runner.boot.duration", {
+      unit: "ms",
+      description: "Runner process boot: Node start to Temporal worker polling",
+    }),
+    executionSetupDuration: meter.createHistogram("stigmer.execution.setup.duration", {
+      unit: "ms",
+      description: "Per-execution setup: activity start to agent ready to stream",
+    }),
+    poolAttachDuration: meter.createHistogram("stigmer.sandbox.pool.attach.duration", {
+      unit: "ms",
+      description: "Warm-pool attach hand-off on the member: token exchange to session worker polling",
+    }),
   };
 
   return instruments;

package/src/pool-member.ts

@@ -0,0 +1,99 @@
+/**
+ * Warm-pool member context.
+ *
+ * A pool member is a blank, pre-booted cloud sandbox (selected by the
+ * STIGMER_POOL_MEMBER_ID env) that polls a control queue
+ * `sandbox:{memberId}` until the control plane claims it for a session.
+ * The claim arrives as the AttachSession activity, which needs two things
+ * only the pool boot path knows: the member's identity/credential and a
+ * handle to the runner manager (to attach the session worker).
+ *
+ * This module is that hand-off point — a module-level registry mirroring
+ * `in-flight.ts` and the shutdown-signal registry: the boot path writes,
+ * the activity reads via the exported getter with zero handle to the boot
+ * closure, and every non-pool process (static, desktop manager, tests)
+ * simply reads undefined, which is the activity's inert state.
+ */
+
+import {
+  TOKEN_TYPE_POOL_SANDBOX,
+  TOKEN_TYPE_SANDBOX,
+  tokenTypeOf,
+  sessionIdClaimOf,
+} from "./client/token-claims.js";
+
+/** The manager surface the attach path needs — kept minimal for testability. */
+export interface PoolAttachTarget {
+  addSession(sessionId: string): Promise<void>;
+  updateToken(token: string | null): void;
+}
+
+export interface PoolMemberContext {
+  /** The pool member id this process was provisioned as. */
+  readonly memberId: string;
+  /**
+   * The pool_sandbox credential the member booted with. Captured at
+   * registration because the manager's tokenRef is overwritten with the
+   * session token during attach — the exchange itself must authenticate
+   * with the pool credential.
+   */
+  readonly poolToken: string;
+  /** The live runner manager hosting this member's workers. */
+  readonly manager: PoolAttachTarget;
+}
+
+let _context: PoolMemberContext | undefined;
+
+/** Called once by the pool boot path after the manager is up. */
+export function registerPoolMemberContext(context: PoolMemberContext): void {
+  _context = context;
+}
+
+/** Undefined everywhere except a booted pool member — the inert switch. */
+export function getPoolMemberContext(): PoolMemberContext | undefined {
+  return _context;
+}
+
+/** Test hook: pool membership is process-lifetime state in production. */
+export function clearPoolMemberContext(): void {
+  _context = undefined;
+}
+
+// ─── Boot decision ───────────────────────────────────────────────────────────
+
+/**
+ * What a pool-configured process should do, decided from its credential.
+ *
+ * The Secret-injected STIGMER_TOKEN is the single source of truth for a pool
+ * member's identity across restarts: the token is read into the pod's env only
+ * at container start, and the control plane rewrites the Secret to the session
+ * token when the member is claimed. So a fresh member sees pool_sandbox and
+ * polls its control queue, while a claimed member that restarted sees the
+ * session token and must go straight to serving that session — its pool row
+ * is gone and nothing will ever dispatch on the control queue again.
+ */
+export type PoolBootIntent =
+  | { kind: "pool-control" }
+  | { kind: "claimed-session"; sessionId: string }
+  | { kind: "invalid"; reason: string };
+
+export function decidePoolBoot(token: string | null | undefined): PoolBootIntent {
+  const tokenType = tokenTypeOf(token);
+  if (tokenType === TOKEN_TYPE_POOL_SANDBOX) {
+    return { kind: "pool-control" };
+  }
+  if (tokenType === TOKEN_TYPE_SANDBOX) {
+    const sessionId = sessionIdClaimOf(token);
+    if (!sessionId) {
+      return {
+        kind: "invalid",
+        reason: "session sandbox token carries no session_id claim",
+      };
+    }
+    return { kind: "claimed-session", sessionId };
+  }
+  return {
+    kind: "invalid",
+    reason: `expected a pool_sandbox or sandbox token, got token_type=${tokenType ?? "none"}`,
+  };
+}