@stigmer/server 3.14.0-dev.20260910084630

package/src/runnerauth/runner-credential-provider.ts

@@ -0,0 +1,328 @@
+/**
+ * The runner-credential provider seam — convergence program 20260826.02,
+ * blueprint/03 §6c, extracted with O5 (20260827.02). Lives in
+ * src/runnerauth beside the OSS implementation it fronts.
+ *
+ * Mint and verify PER CREDENTIAL LANE, where a lane is an implementation's
+ * own token_type vocabulary: OSS defines exactly one
+ * (TOKEN_TYPE_EXECUTION_SCOPED, runnerauth.ts); the cloud edition's
+ * session/workflow/connect/pool lanes stay entirely on its side of the
+ * seam (C4). The lane parameter is an open string DELIBERATELY — this
+ * contract must neither import cloud vocabulary into OSS nor pretend OSS
+ * has lanes it does not (the Q4 gate ruling).
+ *
+ * Per-arm fail posture, pinned precisely because the approved docs
+ * abbreviate it two different ways ("fail-closed" / "fail-soft") and the
+ * real contract is BOTH, per arm:
+ *
+ *   - verify fails CLOSED: any failure — forged, expired, wrong lane, a
+ *     lane the implementation does not provide — throws InvalidTokenError,
+ *     and the caller's only correct reaction is to fall back to redaction
+ *     (the executioncontext decrypt lane's posture, oss#535).
+ *   - mint on a PROVIDED lane without a signing key throws
+ *     MintingDisabledError, which the platform exchange RPC maps to the
+ *     presence-based "not minted" response the runner handles — degraded,
+ *     not fatal. Minting on a lane the implementation does NOT provide is
+ *     a composition bug, not a runtime condition: it throws a plain Error
+ *     naming the lane (the loud-fail doctrine).
+ *
+ * The OSS default (newExecutionScopedRunnerCredentialProvider) adapts
+ * RunnerAuthService unchanged — same key ladder, same HS256 tokens, same
+ * boot-fatal key posture owned by the composition root. Extensions
+ * substitute an implementation through the drivers registry point
+ * (extensions/drivers.ts); with none composed, behavior is byte-identical
+ * to the direct-service wiring this seam replaced.
+ *
+ * # The optional capability methods (C4, 20260827.09 — gate ruling Q1)
+ *
+ * Beyond the mint/verify primitives, an edition's runner credentials
+ * surface at four OSS-owned touchpoints whose POLICY is edition-specific:
+ * the platform scoped-token exchange, the bootstrap credential response,
+ * the token baked into a provisioned sandbox, and the ExecutionContext
+ * decrypt trust decision. Each is an OPTIONAL method here; each OSS call
+ * site falls back to today's exact behavior when the method is absent,
+ * and the OSS default provider defines none — empty-composition behavior
+ * is byte-identical by construction (the local conformance rosters pin
+ * it). One provider object carries the edition's whole credential story;
+ * the rejected alternative (a second single-instance driver for the
+ * exchange) split that story across two objects whose only consumer is
+ * the same composition.
+ *
+ * Capability implementations REFUSE by throwing (a ConnectError with the
+ * implementation's own byte-pinned copy — the gate-step refusal shape)
+ * and DEGRADE by returning their not-minted/empty results. The
+ * distinction is contract: a refusal fails the RPC, a degrade rides the
+ * presence-based response the runner already handles.
+ */
+import type { CallerIdentity } from "../extensions/identity.js";
+import type { MintedToken } from "./runnerauth.js";
+import {
+  InvalidTokenError,
+  RunnerAuthService,
+  TOKEN_TYPE_EXECUTION_SCOPED,
+} from "./runnerauth.js";
+
+/**
+ * The domain shape of a getRunnerScopedToken request — one arm per proto
+ * scope (server_info.proto), transcribed so implementations never import
+ * wire types. The renewal arm is deliberately empty: every renewal
+ * parameter comes from the CALLER's verified credential, never the
+ * request (the Java exchange's ruled posture).
+ */
+export type RunnerScopedTokenRequest =
+  | { readonly arm: "agent-execution"; readonly executionId: string }
+  | { readonly arm: "workflow-execution"; readonly executionId: string }
+  | { readonly arm: "pool-claim"; readonly sessionId: string }
+  | { readonly arm: "renewal" }
+  // The proto oneof left unset — carried so implementations own the
+  // refusal (the Java exchange answers INVALID_ARGUMENT; OSS's
+  // capability-less fallback answers not-minted). Erasing this arm into
+  // any other would let a malformed request impersonate that arm's
+  // semantics.
+  | { readonly arm: "unset" };
+
+/**
+ * An exchange outcome: minted, or the presence-based "not minted" shape
+ * (empty output on the wire — the runner's degrade contract). Refusals
+ * are NOT an arm of this type: implementations throw them.
+ */
+export type RunnerScopedTokenExchange =
+  | { readonly minted: false }
+  | {
+      readonly minted: true;
+      readonly token: string;
+      readonly expiresInSeconds: number;
+    };
+
+/**
+ * The credential portion of a getRunnerBootstrapConfig response. Both
+ * arms are independently optional — the Java contract's presence-based
+ * coupling (token fields all-or-nothing, key fields all-or-nothing) is
+ * expressed structurally.
+ */
+export interface RunnerBootstrapCredentials {
+  readonly accessToken?: {
+    readonly token: string;
+    readonly expiresInSeconds: number;
+  };
+  readonly payloadKeys?: {
+    readonly keyId: string;
+    readonly keyBase64: string;
+    readonly secondaryKeyId?: string;
+    readonly secondaryKeyBase64?: string;
+  };
+}
+
+/**
+ * What the sandbox ensure steps know when they mint the credential baked
+ * into a provisioned sandbox (steps.ts). `sessionId` is empty on the
+ * workflow scope; `callerIdentityId` is empty when the invocation site
+ * has no caller (the Java ensure step's null-identity arm, which mints
+ * nothing rather than minting unattributed).
+ */
+export interface SandboxCredentialRequest {
+  readonly scope: "session" | "workflow";
+  readonly sessionId: string;
+  readonly executionId: string;
+  readonly org: string;
+  readonly callerIdentityId: string;
+}
+
+/**
+ * The memory-capture eligibility answer for one caller (the sixth
+ * capability, parity entry 20260830.05 — the Java
+ * MemoryCreateHandler.ResolveMemoryDefaults runner arm):
+ *
+ *   - `no-opinion`: the caller's credential is not one this
+ *     implementation classifies — the gate's own eligibility logic
+ *     applies unchanged.
+ *   - `refuse`: a runner-class credential outside the capture lane —
+ *     the gate answers its byte-pinned PERMISSION_DENIED copy.
+ *   - `admit`: the session-scoped capture lane. The implementation
+ *     hands over the token's own proved claims: the subject the record
+ *     belongs to (Java: "the sub IS the human subject the session
+ *     belongs to") and the session id provenance is overridden with
+ *     (server-proved beats runner-reported). Both are the
+ *     implementation's claim vocabulary — OSS never decodes them.
+ */
+export type MemoryCaptureDecision =
+  | { readonly verdict: "no-opinion" }
+  | { readonly verdict: "refuse" }
+  | {
+      readonly verdict: "admit";
+      readonly subjectIdentityAccountId: string;
+      readonly provedSessionId: string;
+    };
+
+/**
+ * Mints and verifies runner credentials per lane. Implementations must be
+ * stateless-safe for concurrent use (they gate every ExecutionContext
+ * decrypt and every execution dispatch).
+ */
+export interface RunnerCredentialProvider {
+  /**
+   * Whether the implementation can currently mint for the lane — false
+   * for lanes it does not provide AND for provided lanes with no signing
+   * key. Callers that degrade on "cannot mint" (mcpserver connect) probe
+   * this instead of catching MintingDisabledError.
+   */
+  isEnabled(lane: string): boolean;
+  /**
+   * A credential on the given lane bound to `binding` (what the binding
+   * identifies is lane vocabulary — OSS's execution_scoped lane binds an
+   * execution id). ttlSeconds <= 0 selects the implementation default.
+   */
+  mint(lane: string, binding: string, ttlSeconds: number): MintedToken;
+  /**
+   * Verifies a credential against the ONE lane the caller accepts — the
+   * caller states its trust decision, the provider enforces it — and
+   * returns the binding. ANY failure throws InvalidTokenError.
+   */
+  verify(lane: string, token: string): string;
+
+  /**
+   * The whole getRunnerScopedToken policy: per-arm caller-class gating,
+   * authorization, and mint (the cloud edition's four-arm exchange).
+   * When present, the platform controller delegates EVERY arm here;
+   * absent, the controller keeps the OSS behavior (execution arms mint
+   * on the execution_scoped lane; pool-claim/renewal answer not-minted).
+   * Refusals throw; keyless degrade returns `{ minted: false }`.
+   */
+  exchangeScopedToken?(
+    request: RunnerScopedTokenRequest,
+    caller: CallerIdentity,
+  ): Promise<RunnerScopedTokenExchange>;
+
+  /**
+   * The credential portion of getRunnerBootstrapConfig (the runner access
+   * token and per-identity payload-encryption keys). When present, the
+   * platform controller merges the result into the response; absent, the
+   * fields stay empty (the OSS posture — minting a proxy credential is a
+   * cloud capability). Both arms are best-effort by contract: a failure
+   * inside an arm degrades that arm to absent, never fails the bootstrap
+   * the Temporal coordinates ride on.
+   */
+  bootstrapCredentials?(
+    caller: CallerIdentity,
+  ): Promise<RunnerBootstrapCredentials>;
+
+  /**
+   * The credential baked into a provisioned sandbox (SandboxEnvironment.
+   * stigmerToken). When present, the ensure steps delegate here with the
+   * full provisioning context; absent, they mint on the execution_scoped
+   * lane exactly as before. Returns "" to launch tokenless (the
+   * redaction-fallback contract lane.ts documents); a thrown error
+   * propagates to the invoking step's own failure posture.
+   */
+  mintSandboxCredential?(request: SandboxCredentialRequest): string;
+
+  /**
+   * The ExecutionContext decrypt trust decision for getByExecutionId
+   * (`executionId` is the EC's spec.execution_id). When present, it IS
+   * the entire decision — the implementation owns its lane set and scope
+   * bindings (the cloud's session/workflow/connect scope rules, including
+   * any resource loads through its own clients); absent, the decrypt gate
+   * keeps the OSS decision (execution_scoped verify + binding equality).
+   * True decrypts; false redacts; never throws for an unrecognized or
+   * invalid token — redaction-as-success is the pinned contract.
+   */
+  authorizeExecutionContextRead?(
+    rawToken: string,
+    executionId: string,
+  ): Promise<boolean>;
+
+  /**
+   * Decrypt-key material for a Temporal payload-encryption key id the
+   * server's env-configured codec does not hold (C4 Stage 2: the
+   * server-managed per-identity `rpk_` keys bootstrapCredentials hands
+   * out — resolution belongs on the same object that distributes them).
+   * Threaded into the server's decode-only payload codec at compose;
+   * consulted only when that codec is installed at all (env-keyed — the
+   * cloud composition always configures the platform key). Undefined
+   * means unknown: the codec keeps its pinned fail-closed throw. Absent
+   * method → today's exact behavior (static env keys only).
+   */
+  resolvePayloadKey?(keyId: string): Promise<Buffer | undefined>;
+
+  /**
+   * The workflow-lineage vouching decision for an agent-execution create
+   * that carries the runner-stamped lineage labels (parity entry
+   * 20260830.05; the Java RecordRunnerLineageLabelsStep, cloud#386,
+   * consumed by the agentexecution chain's RecordRunnerLineageLabels
+   * step). The implementation owns
+   * BOTH halves of the decision: whether the caller's credential is a
+   * runner credential at all (its own token-type vocabulary — no caller
+   * class expresses this, and OSS must not learn another edition's
+   * lane names), and whether a workflow-bound credential may stamp the
+   * given workflow execution id ("a workflow sandbox cannot stamp
+   * another workflow's lineage" — Java verifies the label against the
+   * token's own binding).
+   *
+   * Returns true to vouch the lineage keys (the guard then exempts
+   * exactly them), false for a non-runner credential (nothing vouched —
+   * the caller stays fully subject to the guard). REFUSES by throwing a
+   * ConnectError with the implementation's byte-pinned copy when the
+   * binding check fails. `stampedWorkflowExecutionId` is empty when the
+   * request stamped only the task label — no binding to check.
+   *
+   * Absent method → nothing is vouched (today's exact OSS behavior: the
+   * permissive default Authorizer is what admits the local runner's
+   * lineage write, and a strict composition without the capability keeps
+   * refusing).
+   */
+  vouchRunnerLineageLabels?(
+    caller: CallerIdentity,
+    stampedWorkflowExecutionId: string,
+  ): boolean;
+
+  /**
+   * The memory capture-eligibility decision for one caller (parity entry
+   * 20260830.05, stigmer-cloud#564; the Java MemoryCreateHandler runner
+   * arm: admit `isSessionSandbox()`, refuse every other runner
+   * credential). Consulted by GuardMemoryCapture
+   * BEFORE its own eligibility logic; `no-opinion` falls through to
+   * that logic unchanged. REFUSES the org-mismatch arm by throwing a
+   * ConnectError with the implementation's byte-pinned copy (Java:
+   * "a mismatch is a forged address, not a routing choice" —
+   * `captureOrg` is the request's metadata.org, checked against the
+   * token's own org claim).
+   *
+   * Absent method → the gate's existing logic exactly (today's OSS
+   * behavior: the trusted-local single-user posture admits, honestly).
+   */
+  authorizeMemoryCapture?(
+    caller: CallerIdentity,
+    captureOrg: string,
+  ): MemoryCaptureDecision;
+}
+
+/**
+ * The OSS default: RunnerAuthService behind the provider contract,
+ * providing only the execution_scoped lane. A separate adapter rather
+ * than the service implementing the interface: the service's concrete
+ * lane-free signatures are a stable test surface (and the O2 sub-project
+ * edits runnerauth.ts in parallel — this file keeps O5 out of it).
+ */
+export function newExecutionScopedRunnerCredentialProvider(
+  service: RunnerAuthService,
+): RunnerCredentialProvider {
+  return {
+    isEnabled(lane: string): boolean {
+      return lane === TOKEN_TYPE_EXECUTION_SCOPED && service.isEnabled();
+    },
+    mint(lane: string, binding: string, ttlSeconds: number): MintedToken {
+      if (lane !== TOKEN_TYPE_EXECUTION_SCOPED) {
+        throw new Error(
+          `runner credential lane '${lane}' is not provided by this implementation (provides '${TOKEN_TYPE_EXECUTION_SCOPED}')`,
+        );
+      }
+      return service.mint(binding, ttlSeconds);
+    },
+    verify(lane: string, token: string): string {
+      if (lane !== TOKEN_TYPE_EXECUTION_SCOPED) {
+        throw new InvalidTokenError();
+      }
+      return service.verify(token);
+    },
+  };
+}

package/src/runnerauth/runnerauth.ts

@@ -0,0 +1,251 @@
+/**
+ * Execution-scoped runner tokens — ports pkg/runnerauth/runnerauth.go
+ * (oss#535), the lane that gates the ExecutionContext decrypt path.
+ *
+ * WHY: since oss#535 the EC read RPCs redact is_secret values for every
+ * caller — the same contract the cloud edition enforces — but the runner
+ * still needs the real values to serve executions. Cloud distinguishes the
+ * runner by the token_type claim of its platform-minted credential; OSS
+ * ships no token VERIFIERS on its identity chassis (O2, 20260827.01 — the
+ * verifier chain exists but resolves every request to the trusted-local
+ * identity until O3 lands the first verifiers), so this module supplies
+ * the minimal equivalent: the platform exchange mints a short-lived token
+ * bound to ONE execution, and the EC handler decrypts only for a token
+ * whose binding matches the requested ExecutionContext.
+ *
+ * A LANE DISCRIMINATOR, NOT A TRUST BOUNDARY (DD-004): in the trusted-local
+ * posture anyone who can reach the server can mint. What the token buys is
+ * the redaction-by-default read contract converging with cloud, on top of
+ * oss#405's encryption at rest. It is deliberately NOT an IdentityVerifier
+ * on the chassis: presenting it must never change the caller's identity
+ * (the Q6 fall-through keeps the runner's Bearer-on-every-RPC behavior
+ * byte-identical), only unlock this one decrypt lane.
+ *
+ * Token shape (field names are wire contract — the runner's
+ * token-claims.ts reads token_type by name):
+ *   {"token_type":"execution_scoped","execution_id":"<id>","iat":…,"exp":…}
+ *
+ * Consumers arrive with their own domains: the platform exchange RPC
+ * (mint) and the executioncontext resolve step (verify). This module lands
+ * with the encryption sub-project because its signing key rides the shared
+ * key ladder and its boot posture is a ratified cross-domain invariant
+ * (fatal — see compose.ts).
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+import { getOrCreateNamedKey } from "../encryption/key-manager.js";
+import type { KeyLoaderOptions } from "../encryption/key-manager.js";
+
+/**
+ * The token_type claim of every OSS-minted runner token — Go
+ * TokenTypeExecutionScoped. Deliberately distinct from the cloud sandbox
+ * vocabulary (sandbox / workflow_sandbox / connect_sandbox): borrowing
+ * "sandbox" while carrying different claims would mislead anyone debugging
+ * across editions. One honest type with a direct execution_id binding.
+ */
+export const TOKEN_TYPE_EXECUTION_SCOPED = "execution_scoped";
+
+/** Env var for the signing key (Base64 32B) — Go EnvKeyName. */
+export const RUNNER_TOKEN_KEY_ENV_VAR = "STIGMER_RUNNER_TOKEN_KEY";
+
+/** Auto-generated key file under ~/.stigmer — Go KeyFileName. */
+export const RUNNER_TOKEN_KEY_FILE_NAME = "runner-token.key";
+
+/**
+ * Default token lifetime — Go DefaultTTL (1 hour). Tokens are minted
+ * immediately before each ExecutionContext read (or carried in a connect
+ * workflow's dispatch payload), so the TTL only needs to cover one unit of
+ * dispatched work including its Temporal retries: generous without being
+ * an effectively-permanent credential in Temporal history.
+ */
+export const DEFAULT_TTL_SECONDS = 3600;
+
+/**
+ * Go ErrInvalidToken: ANY verification failure — forged signature, wrong
+ * algorithm, expired, wrong type, empty binding — collapses to this one
+ * error. Callers fail closed to redaction on it; a finer-grained reason
+ * would just invite branching on it.
+ */
+export class InvalidTokenError extends Error {
+  constructor() {
+    super("invalid runner token");
+    this.name = "InvalidTokenError";
+  }
+}
+
+/**
+ * Go ErrMintingDisabled: minting with no signing key (keyless deployments,
+ * effectively test-only — fromEnv auto-generates). The exchange RPC maps
+ * it to the presence-based "not minted" response the runner handles.
+ */
+export class MintingDisabledError extends Error {
+  constructor() {
+    super("runner token minting is disabled - no signing key configured");
+    this.name = "MintingDisabledError";
+  }
+}
+
+/**
+ * The constant JWT header: HS256 is the only algorithm this module ever
+ * produces or accepts — Verify refuses alg-confusion inputs by comparing
+ * the ENCODED header, without parsing attacker-controlled JSON.
+ */
+const JWT_HEADER = Buffer.from('{"alg":"HS256","typ":"JWT"}').toString(
+  "base64url",
+);
+
+/** JWT payload shape — field names are wire contract. */
+interface TokenClaims {
+  readonly token_type: string;
+  readonly execution_id: string;
+  readonly iat: number;
+  readonly exp: number;
+}
+
+/** A minted token with its lifetime in whole seconds (the RPC's shape). */
+export interface MintedToken {
+  readonly token: string;
+  readonly ttlSeconds: number;
+}
+
+/**
+ * Mints and verifies execution-scoped runner tokens with a single
+ * HMAC-SHA256 key. Stateless and safe for concurrent use.
+ */
+export class RunnerAuthService {
+  private readonly key: Buffer | undefined;
+
+  private constructor(key: Buffer | undefined) {
+    this.key = key;
+  }
+
+  /**
+   * Go NewService: nil/empty key → disabled service (Mint fails with
+   * MintingDisabledError, Verify rejects everything — fail closed: without
+   * a key no token can be genuine).
+   */
+  static create(key: Buffer | undefined): RunnerAuthService {
+    if (key === undefined || key.length === 0) {
+      return new RunnerAuthService(undefined);
+    }
+    return new RunnerAuthService(key);
+  }
+
+  /**
+   * Go NewServiceFromEnv: key via the shared ladder (env var → key file →
+   * auto-generate). Errors only on unusable explicit configuration; the
+   * composition root maps that to the BOOT-FATAL posture (the ratified D2
+   * asymmetry: a server that cannot mint runner tokens would hand every
+   * execution redaction markers instead of its secrets — the silent-junk
+   * failure the oss#405 fail-loud doctrine forbids).
+   */
+  static fromEnv(options: KeyLoaderOptions = {}): RunnerAuthService {
+    const key = getOrCreateNamedKey(
+      RUNNER_TOKEN_KEY_ENV_VAR,
+      RUNNER_TOKEN_KEY_FILE_NAME,
+      options,
+    );
+    return RunnerAuthService.create(key);
+  }
+
+  /** Go IsEnabled: whether the service holds a signing key. */
+  isEnabled(): boolean {
+    return this.key !== undefined;
+  }
+
+  /**
+   * Go Mint: a token bound to executionId, valid for ttlSeconds
+   * (DEFAULT_TTL_SECONDS when <= 0).
+   */
+  mint(executionId: string, ttlSeconds: number = 0): MintedToken {
+    if (this.key === undefined) {
+      throw new MintingDisabledError();
+    }
+    if (executionId === "") {
+      throw new Error("execution id is required to mint a runner token");
+    }
+    const ttl = ttlSeconds > 0 ? ttlSeconds : DEFAULT_TTL_SECONDS;
+
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    const claims: TokenClaims = {
+      token_type: TOKEN_TYPE_EXECUTION_SCOPED,
+      execution_id: executionId,
+      iat: nowSeconds,
+      exp: nowSeconds + ttl,
+    };
+    const signingInput =
+      JWT_HEADER + "." + Buffer.from(JSON.stringify(claims)).toString("base64url");
+    return {
+      token: signingInput + "." + this.sign(signingInput),
+      ttlSeconds: ttl,
+    };
+  }
+
+  /**
+   * Go Verify: checks signature, algorithm, expiry, and token type, and
+   * returns the execution id the token is bound to. Any failure throws the
+   * one InvalidTokenError — the caller's only correct reaction is to fall
+   * closed to redaction.
+   *
+   * Check order mirrors Go: enabled → three parts → exact encoded-header
+   * compare → constant-time HMAC → payload decode → claims. The expiry
+   * boundary is `now >= exp` (a token in its expiring second is invalid).
+   */
+  verify(token: string): string {
+    if (this.key === undefined) {
+      throw new InvalidTokenError();
+    }
+
+    const parts = token.split(".");
+    if (parts.length !== 3) {
+      throw new InvalidTokenError();
+    }
+    if (parts[0] !== JWT_HEADER) {
+      throw new InvalidTokenError();
+    }
+
+    const signingInput = parts[0] + "." + parts[1];
+    const expected = Buffer.from(this.sign(signingInput));
+    const provided = Buffer.from(parts[2] as string);
+    // Go's hmac.Equal returns false on length mismatch; Node's
+    // timingSafeEqual THROWS on it, so the length guard comes first (the
+    // signature length is not secret — no timing channel is opened).
+    if (
+      expected.length !== provided.length ||
+      !timingSafeEqual(expected, provided)
+    ) {
+      throw new InvalidTokenError();
+    }
+
+    let claims: TokenClaims;
+    try {
+      claims = JSON.parse(
+        Buffer.from(parts[1] as string, "base64url").toString("utf8"),
+      ) as TokenClaims;
+    } catch {
+      throw new InvalidTokenError();
+    }
+
+    if (
+      claims.token_type !== TOKEN_TYPE_EXECUTION_SCOPED ||
+      typeof claims.execution_id !== "string" ||
+      claims.execution_id === "" ||
+      typeof claims.exp !== "number" ||
+      Math.floor(Date.now() / 1000) >= claims.exp
+    ) {
+      throw new InvalidTokenError();
+    }
+
+    return claims.execution_id;
+  }
+
+  /** base64url HMAC-SHA256 of the signing input — Go sign(). */
+  private sign(signingInput: string): string {
+    if (this.key === undefined) {
+      throw new InvalidTokenError();
+    }
+    return createHmac("sha256", this.key)
+      .update(signingInput)
+      .digest("base64url");
+  }
+}

package/src/sandbox/__tests__/docker.integration.test.ts

@@ -0,0 +1,103 @@
+/**
+ * Integration smoke for the Docker driver (§6d, O6): the real docker
+ * CLI, the full provision → probe → stop/start → deprovision cycle, and
+ * the label/env contract on the live container.
+ *
+ * Gated HONESTLY, never silently: it runs only when Docker answers AND
+ * the operator opts in with STIGMER_SANDBOX_DOCKER_SMOKE=1 — the smoke
+ * pulls the published runner image (the breakdown's acceptance names
+ * it), which is far too heavy for every `npm test`. CI's opt-in lane and
+ * the PR's recorded run are the proof points. Override the image with
+ * STIGMER_SANDBOX_RUNNER_IMAGE to smoke against a local build.
+ */
+import { execFileSync } from "node:child_process";
+
+import { afterAll, describe, expect, it } from "vitest";
+
+import { createLogger } from "../../boot/logger.js";
+import { newDockerSandboxProvisioner } from "../docker.js";
+import { sandboxBaseName } from "../naming.js";
+import type { SandboxDriverConfig } from "../provisioner.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+function dockerAnswers(): boolean {
+  try {
+    execFileSync("docker", ["version", "--format", "{{.Server.Version}}"], {
+      stdio: "pipe",
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const optedIn = process.env["STIGMER_SANDBOX_DOCKER_SMOKE"] === "1";
+
+describe.skipIf(!optedIn || !dockerAnswers())(
+  "docker driver (integration smoke — opt-in)",
+  () => {
+    const config: SandboxDriverConfig = {
+      // host.docker.internal: reachable-from-container on Docker Desktop;
+      // the smoke only needs the vars INJECTED, not a live server behind
+      // them (the runner tolerates an unreachable backend at boot).
+      backendEndpoint: "http://host.docker.internal:7234",
+      temporalAddress: "host.docker.internal:7233",
+      runnerImage:
+        process.env["STIGMER_SANDBOX_RUNNER_IMAGE"] ??
+        "ghcr.io/stigmer/runner:latest",
+      runnerCommand: "unused-by-this-driver",
+      kubernetesNamespace: "unused-by-this-driver",
+    };
+    const driver = newDockerSandboxProvisioner({
+      config,
+      logger: silentLogger,
+    });
+    const sessionId = `ses_docker_smoke_${Date.now()}`;
+    const containerName = sandboxBaseName("session", sessionId);
+
+    afterAll(async () => {
+      await driver.deprovisionSessionSandbox(sessionId);
+    });
+
+    it("provisions a labeled container with the env contract, probes, and tears down", async () => {
+      await driver.ensureSessionSandbox(sessionId, {
+        taskQueue: `session:${sessionId}`,
+        stigmerToken: "tok-docker-smoke",
+      });
+      expect(await driver.probe("session", sessionId)).toBe("running");
+
+      const inspect = JSON.parse(
+        execFileSync("docker", ["inspect", containerName], {
+          stdio: "pipe",
+        }).toString(),
+      ) as Array<{
+        Config: { Env: string[]; Labels: Record<string, string> };
+      }>;
+      const container = inspect[0];
+      expect(container?.Config.Labels["stigmer.ai/sandbox-id"]).toBe(sessionId);
+      expect(container?.Config.Labels["stigmer.ai/scope"]).toBe("session");
+      expect(container?.Config.Env).toContain(
+        `STIGMER_TASK_QUEUE=session:${sessionId}`,
+      );
+      expect(container?.Config.Env).toContain("STIGMER_TOKEN=tok-docker-smoke");
+      expect(container?.Config.Env).toContain("MODE=local");
+
+      // Idempotent fast path.
+      await driver.ensureSessionSandbox(sessionId, {
+        taskQueue: `session:${sessionId}`,
+        stigmerToken: "tok-docker-smoke",
+      });
+      expect(await driver.probe("session", sessionId)).toBe("running");
+
+      await driver.deprovisionSessionSandbox(sessionId);
+      expect(await driver.probe("session", sessionId)).toBe("absent");
+      // Idempotent teardown.
+      await driver.deprovisionSessionSandbox(sessionId);
+    });
+  },
+);