@opengeni/runtime 0.6.0 → 0.7.0

package/src/index.ts

@@ -1,6 +1,30 @@
-import type { ConfiguredModel, ContextCompactionMode, ModelProviderApi, ResolvedModelProvider, Settings } from "@opengeni/config";
-import { AGENT_INSTRUCTIONS_CORE_PLACEHOLDER, collectSandboxEnvironment, contextInputBudgetTokens, contextServerCompactThreshold, firstPartyMcpBaseUrl, parseExposedPorts, resolveContextCompactionMode, resolveModelProvider, sandboxLifecycleHookIds } from "@opengeni/config";
-import { CAPABILITY_DESCRIPTORS, isClearedRunStateBlob, prefixedMcpToolName as sharedPrefixedMcpToolName, signDelegatedAccessToken, type McpServerConnectionRef, type Permission, type ReasoningEffort, type ResourceRef, type SessionEventType, type ToolAuthNeededPayload, type ToolRef } from "@opengeni/contracts";
+import type {
+  ConfiguredModel,
+  ModelProviderApi,
+  ResolvedModelProvider,
+  Settings,
+} from "@opengeni/config";
+import {
+  AGENT_INSTRUCTIONS_CORE_PLACEHOLDER,
+  collectSandboxEnvironment,
+  firstPartyMcpBaseUrl,
+  resolveModelProvider,
+  sandboxLifecycleHookIds,
+} from "@opengeni/config";
+import {
+  CAPABILITY_DESCRIPTORS,
+  isClearedRunStateBlob,
+  prefixedMcpToolName as sharedPrefixedMcpToolName,
+  signDelegatedAccessToken,
+  type GitCredentialProvider,
+  type McpServerConnectionRef,
+  type Permission,
+  type ReasoningEffort,
+  type ResourceRef,
+  type SessionEventType,
+  type ToolAuthNeededPayload,
+  type ToolRef,
+} from "@opengeni/contracts";
 import {
   Agent,
   AgentsError,
@@ -45,20 +69,17 @@ import {
   type MCPServer,
   type MCPToolErrorFunction,
   type Model,
+  type ModelRequest,
   type ModelProvider,
   type RunStreamEvent,
   type Tool,
 } from "@openai/agents";
-import {
-  localDirLazySkillSource,
-} from "@openai/agents/sandbox/local";
+import { localDirLazySkillSource } from "@openai/agents/sandbox/local";
 import {
   Capabilities,
   Manifest,
   SandboxAgent,
-  StaticCompactionPolicy,
   azureBlobMount,
-  compaction,
   dir,
   file,
   filesystem,
@@ -79,30 +100,39 @@ import {
 } from "@openai/agents/sandbox";
 import { ModalCloudBucketMountStrategy } from "@openai/agents-extensions/sandbox/modal";
 import OpenAI from "openai";
-import { CODEX_APPS_MCP_SERVER_ID, CODEX_MODEL_ID_PREFIX, CODEX_ORIGINATOR, codexAppsSanitizingFetch, codexRequestStorage, codexSubscriptionFetch } from "@opengeni/codex";
+import {
+  CODEX_APPS_MCP_SERVER_ID,
+  CODEX_MODEL_ID_PREFIX,
+  CODEX_ORIGINATOR,
+  codexAppsSanitizingFetch,
+  codexRequestStorage,
+  codexSubscriptionFetch,
+} from "@opengeni/codex";
 import { cpSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync } from "node:fs";
 import { dirname, isAbsolute, join, posix as posixPath, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { computerCallNormalizingFetch, normalizeComputerCallActions, sanitizeHistoryItemsForModel } from "./history-sanitizer";
-import { elideStaleScreenshotImages } from "./image-history";
+import {
+  computerCallNormalizingFetch,
+  elideSupersededViewImagePairs,
+  normalizeComputerCallActions,
+  sanitizeHistoryItemsForModel,
+} from "./history-sanitizer";
 import { installCodexToolSearch } from "./codex-tool-search";
 import {
   CompactionNeededError,
   SUMMARY_BUFFER_TOKENS,
-  clientCompactionThresholdTokens,
-  enforceInputBudget,
-  estimateItemTokens,
+  compactionThresholdTokens,
   estimateTokens,
   renderCompactionPromptInputForChat,
 } from "./context-compaction";
 import {
   createSandboxClient,
-  deserializeSandboxSessionStateEnvelope,
   desktopCapableBackend,
   restoredSandboxSessionStateFromEntry,
   setSelfhostedApplyDiff,
 } from "./sandbox";
+import { runWithToolCallCorrelation } from "./sandbox/op-correlation";
 import { computerUse, type ComputerToolMode } from "./sandbox-computer";
 import type { RuntimeMetricsHooks } from "./metrics";
 
@@ -136,9 +166,17 @@ export * from "./sandbox";
 // active backend can now apply file edits over its NATS fs ops with the SDK's exact
 // diff semantics; without this, `createEditor()` throws a clear "not injected" error
 // rather than mis-editing. Runs at import time, before any turn binds a capability.
-setSelfhostedApplyDiff(applyDiff as unknown as (input: string, diff: string, mode?: "default" | "create") => string);
+setSelfhostedApplyDiff(
+  applyDiff as unknown as (input: string, diff: string, mode?: "default" | "create") => string,
+);
 
-export { sanitizeHistoryItemsForModel, stripReasoningEncryptedContent, stripReasoningIdentityFromSerializedRunState, neutralizeToolSearchItemsInSerializedRunState } from "./history-sanitizer";
+export {
+  elideSupersededViewImagePairs,
+  sanitizeHistoryItemsForModel,
+  stripReasoningEncryptedContent,
+  stripReasoningIdentityFromSerializedRunState,
+  neutralizeToolSearchItemsInSerializedRunState,
+} from "./history-sanitizer";
 export type { HistoryItem } from "./history-sanitizer";
 
 // The provider-bound Model classes used by buildModelInstance/resolveTurnModel.
@@ -151,17 +189,14 @@ export { OpenAIChatCompletionsModel, OpenAIResponsesModel } from "@openai/agents
 export {
   CompactionNeededError,
   buildCompactionPromptInput,
-  buildDeterministicFallbackCompactionHistory,
   buildCompactionReplacementHistory,
-  clientCompactionThresholdTokens,
+  compactionThresholdTokens,
   clampCompactionThresholdRatio,
-  decideClientCompaction,
-  enforceInputBudget,
+  decideCompaction,
   buildSummaryItem,
   findCompactionNeededError,
   isCompactionSummary,
   isUserMessage,
-  findKeepBoundary,
   estimateTokens,
   estimateItemTokens,
   renderCompactionPromptInputForChat,
@@ -173,14 +208,12 @@ export {
   MAX_COMPACTION_THRESHOLD_RATIO,
   SUMMARY_BUFFER_TOKENS,
   SUMMARY_PREFIX,
+  isEphemeralInternalContext,
   USER_MESSAGE_TRUNCATION_MARKER,
 } from "./context-compaction";
-export type { ClientCompactionDecision, CompactionItem } from "./context-compaction";
-export {
-  elideStaleScreenshotImages,
-  SCREENSHOT_OMITTED_PLACEHOLDER,
-} from "./image-history";
-export type { ElideStaleScreenshotsOptions, ElideStaleScreenshotsResult } from "./image-history";
+export type { CompactionDecision, CompactionItem } from "./context-compaction";
+export { modelCallUsageTelemetry } from "./usage-telemetry";
+export type { ModelCallUsageTelemetry } from "./usage-telemetry";
 
 ensureReadableStreamFrom();
 
@@ -198,6 +231,7 @@ export type ModelResponseUsage = {
     outputTokens?: number;
     totalTokens?: number;
     inputTokensDetails?: Record<string, number> | Array<Record<string, number>>;
+    outputTokensDetails?: Record<string, number> | Array<Record<string, number>>;
   };
 };
 
@@ -217,19 +251,21 @@ export type ResolveConnectionCredentialInput = {
 export type ResolveConnectionCredentialResult =
   | { status: "ok"; headers: Record<string, string>; connectionId: string; expiresAt?: Date | null }
   | {
-    status: "auth_needed";
-    reason: ToolAuthNeededPayload["reason"];
-    providerDomain: string;
-    connectionId?: string;
-    scopes?: string[];
-    resource?: string;
-    authorizationUrl?: string;
-  };
+      status: "auth_needed";
+      reason: ToolAuthNeededPayload["reason"];
+      providerDomain: string;
+      connectionId?: string;
+      scopes?: string[];
+      resource?: string;
+      authorizationUrl?: string;
+    };
 
 export function ensureReadableStreamFrom(): void {
-  const ctor = globalThis.ReadableStream as (typeof ReadableStream & {
-    from?: <T>(source: Iterable<T> | AsyncIterable<T>) => ReadableStream<T>;
-  }) | undefined;
+  const ctor = globalThis.ReadableStream as
+    | (typeof ReadableStream & {
+        from?: <T>(source: Iterable<T> | AsyncIterable<T>) => ReadableStream<T>;
+      })
+    | undefined;
   if (!ctor || typeof ctor.from === "function") {
     return;
   }
@@ -259,21 +295,27 @@ export function ensureReadableStreamFrom(): void {
 
 export type AgentSegmentInput =
   | {
-    kind: "message";
-    text: string;
-    serializedRunState?: string | null;
-    // Items-mode conversation truth (issue #35): when provided, turn input is
-    // built from these verbatim AgentInputItems and the stored sandbox
-    // envelope — no RunState deserialization, no SDK-version coupling.
-    historyItems?: AgentInputItem[] | null;
-    sandboxEnvelope?: Record<string, unknown> | null;
-  }
-  | { kind: "approval"; serializedRunState: string; approvalId: string; decision: "approve" | "reject"; message?: string };
+      kind: "message";
+      /** A real human/API prompt. Omitted when resuming the same inference. */
+      text?: string;
+      /** Ephemeral platform context: system role, never conversation history. */
+      internalContext?: string;
+      // Canonical conversation truth. When omitted, this is a fresh first
+      // message; ordinary messages never deserialize an SDK RunState.
+      historyItems?: AgentInputItem[] | null;
+      sandboxEnvelope?: Record<string, unknown> | null;
+    }
+  | {
+      kind: "approval";
+      serializedRunState: string;
+      approvalId: string;
+      decision: "approve" | "reject";
+      message?: string;
+    };
 
 export type PreparedAgentInput = {
   input: string | AgentInputItem[] | RunState<any, any>;
   sandboxSessionState?: SandboxSessionState;
-  serializedRunStateForSandbox?: string;
 };
 
 export type SandboxFileDownload = {
@@ -286,6 +328,19 @@ export type SandboxFileDownload = {
   sizeBytes?: number;
 };
 
+export type SandboxFileDownloadFailure = {
+  fileId: string;
+  filename: string;
+  path: string;
+  reason: string;
+  exitCode?: number;
+  output?: string;
+};
+
+export type SandboxFileDownloadMaterializationResult = {
+  failures: SandboxFileDownloadFailure[];
+};
+
 let runtimeMetricsHooks: RuntimeMetricsHooks | null = null;
 
 export function configureRuntimeMetricsHooks(hooks: RuntimeMetricsHooks | null | undefined): void {
@@ -299,10 +354,27 @@ export type OpenGeniRuntime = {
   // shape; null when the turn's model is not in the registry, so the caller
   // falls back to the legacy global-client path (settings.openaiModel).
   resolveTurnModel: (settings: Settings, modelId: string) => ReturnType<typeof resolveTurnModel>;
-  buildAgent: (settings: Settings, resources: ResourceRef[], options?: BuildAgentOptions) => Agent<any, any>;
-  prepareTools: (settings: Settings, tools: ToolRef[], options?: PrepareToolsOptions) => Promise<PreparedAgentTools>;
-  prepareInput: (agent: Agent<any, any>, input: AgentSegmentInput, options?: PrepareInputOptions) => Promise<PreparedAgentInput>;
-  runStream: (agent: Agent<any, any>, input: PreparedAgentInput, settings: Settings, options?: RunAgentStreamOptions) => Promise<Awaited<ReturnType<typeof runAgentStream>>>;
+  buildAgent: (
+    settings: Settings,
+    resources: ResourceRef[],
+    options?: BuildAgentOptions,
+  ) => Agent<any, any>;
+  prepareTools: (
+    settings: Settings,
+    tools: ToolRef[],
+    options?: PrepareToolsOptions,
+  ) => Promise<PreparedAgentTools>;
+  prepareInput: (
+    agent: Agent<any, any>,
+    input: AgentSegmentInput,
+    options?: PrepareInputOptions,
+  ) => Promise<PreparedAgentInput>;
+  runStream: (
+    agent: Agent<any, any>,
+    input: PreparedAgentInput,
+    settings: Settings,
+    options?: RunAgentStreamOptions,
+  ) => Promise<Awaited<ReturnType<typeof runAgentStream>>>;
   serializeApprovals: (interruptions: unknown[]) => unknown[];
 };
 
@@ -312,7 +384,9 @@ export type ProductionRuntimeOverrides = {
   metrics?: RuntimeMetricsHooks;
 };
 
-export function createProductionAgentRuntime(overrides: ProductionRuntimeOverrides = {}): OpenGeniRuntime {
+export function createProductionAgentRuntime(
+  overrides: ProductionRuntimeOverrides = {},
+): OpenGeniRuntime {
   return {
     configure: (settings) => {
       configureRuntimeMetricsHooks(overrides.metrics);
@@ -322,17 +396,20 @@ export function createProductionAgentRuntime(overrides: ProductionRuntimeOverrid
     // model used in worker tests is not in any provider's allow-list), so when
     // one is supplied resolveTurnModel reports "no resolution" and the caller
     // keeps the legacy global-client path with the override model.
-    resolveTurnModel: (settings, modelId) => (overrides.model ? null : resolveTurnModel(settings, modelId)),
-    buildAgent: (settings, resources, options) => buildOpenGeniAgent(settings, resources, {
-      ...options,
-      ...(overrides.model ? { model: overrides.model } : {}),
-    }),
+    resolveTurnModel: (settings, modelId) =>
+      overrides.model ? null : resolveTurnModel(settings, modelId),
+    buildAgent: (settings, resources, options) =>
+      buildOpenGeniAgent(settings, resources, {
+        ...options,
+        ...(overrides.model ? { model: overrides.model } : {}),
+      }),
     prepareTools: prepareAgentTools,
     prepareInput: prepareRunInput,
-    runStream: async (agent, input, settings, options) => await runAgentStream(agent, input, settings, {
-      ...options,
-      sandboxClient: overrides.sandboxClient,
-    }),
+    runStream: async (agent, input, settings, options) =>
+      await runAgentStream(agent, input, settings, {
+        ...options,
+        sandboxClient: overrides.sandboxClient,
+      }),
     serializeApprovals,
   };
 }
@@ -344,7 +421,10 @@ export function createProductionAgentRuntime(overrides: ProductionRuntimeOverrid
  * the OpenAI-platform path has only a key (the SDK default client is used via
  * setDefaultOpenAIKey there); the caller then constructs a key-only client.
  */
-export function buildOpenAIClientFromSettings(settings: Settings, providerId: string = settings.openaiProvider): OpenAI {
+export function buildOpenAIClientFromSettings(
+  settings: Settings,
+  providerId: string = settings.openaiProvider,
+): OpenAI {
   if (settings.openaiProvider === "azure") {
     const baseURL = settings.azureOpenaiBaseUrl ?? azureDeploymentBaseUrl(settings);
     const apiKey = settings.azureOpenaiApiKey ?? settings.azureOpenaiAdToken ?? "azure-ad-token";
@@ -353,11 +433,12 @@ export function buildOpenAIClientFromSettings(settings: Settings, providerId: st
       baseURL,
       maxRetries: settings.openaiMaxRetries,
       defaultQuery: azureOpenAIDefaultQuery(settings, baseURL),
-      defaultHeaders: settings.azureOpenaiAdToken && !settings.azureOpenaiApiKey
-        ? { Authorization: `Bearer ${settings.azureOpenaiAdToken}` }
-        : undefined,
+      defaultHeaders:
+        settings.azureOpenaiAdToken && !settings.azureOpenaiApiKey
+          ? { Authorization: `Bearer ${settings.azureOpenaiAdToken}` }
+          : undefined,
       // Rewrite every outbound /responses computer_call to the ACTIONS-ONLY shape
-      // the GA Azure computer tool (gpt-5.5) accepts. This is the lowest reachable
+      // the GA Azure computer tool accepts. This is the lowest reachable
       // seam — below the SDK responses converter, which always re-synthesizes BOTH
       // `action` and `actions` (rejected 400 "exactly one of action or actions").
       // See computerCallNormalizingFetch / rewriteComputerCallsToActionsOnly.
@@ -392,29 +473,32 @@ export function buildProviderClient(provider: ResolvedModelProvider, settings: S
   const client = provider.builtin
     ? buildOpenAIClientFromSettings(settings, provider.id)
     : provider.kind === "codex-subscription"
-      // Codex subscription: the static apiKey is a placeholder — the real per-request
-      // bearer + ChatGPT-Account-ID, the /responses->/codex/responses rewrite, and the
-      // body normalization are all injected by codexSubscriptionFetch, which reads the
-      // per-workspace token from codexRequestStorage (AsyncLocalStorage) at call time.
-      // The provider id is constant ("codex-subscription"), so one cached client serves
-      // every workspace without baking a token into it.
-      ? new OpenAI({
-        apiKey: provider.apiKey ?? "codex-subscription",
-        ...(provider.baseUrl ? { baseURL: provider.baseUrl } : {}),
-        maxRetries: settings.openaiMaxRetries,
-        fetch: codexSubscriptionFetch(instrumentedModelFetch(provider.id, globalThis.fetch)),
-      })
-    // ResolvedModelProvider.apiKey is already the resolved key (configuredProviders
-    // ran resolveProviderApiKey at config time, collapsing apiKey/apiKeyEnv), so it
-    // is passed straight through here rather than re-resolved.
-    : new OpenAI({
-      ...(provider.apiKey ? { apiKey: provider.apiKey } : {}),
-      ...(provider.baseUrl ? { baseURL: provider.baseUrl } : {}),
-      maxRetries: settings.openaiMaxRetries,
-      ...(provider.defaultQuery ? { defaultQuery: provider.defaultQuery } : {}),
-      ...(provider.defaultHeaders ? { defaultHeaders: provider.defaultHeaders } : {}),
-      fetch: instrumentedModelFetch(provider.id, globalThis.fetch),
-    });
+      ? // Codex subscription: the static apiKey is a placeholder — the real per-request
+        // bearer + ChatGPT-Account-ID, the /responses->/codex/responses rewrite, and the
+        // body normalization are all injected by codexSubscriptionFetch, which reads the
+        // per-workspace token from codexRequestStorage (AsyncLocalStorage) at call time.
+        // The provider id is constant ("codex-subscription"), so one cached client serves
+        // every workspace without baking a token into it.
+        new OpenAI({
+          apiKey: provider.apiKey ?? "codex-subscription",
+          ...(provider.baseUrl ? { baseURL: provider.baseUrl } : {}),
+          // Codex transport owns exactly one explicit 401 refresh/retry. Blind
+          // SDK retries on network/5xx/partial streams can replay provider work
+          // or external tool side effects without a durable checkpoint.
+          maxRetries: 0,
+          fetch: codexSubscriptionFetch(instrumentedModelFetch(provider.id, globalThis.fetch)),
+        })
+      : // ResolvedModelProvider.apiKey is already the resolved key (configuredProviders
+        // ran resolveProviderApiKey at config time, collapsing apiKey/apiKeyEnv), so it
+        // is passed straight through here rather than re-resolved.
+        new OpenAI({
+          ...(provider.apiKey ? { apiKey: provider.apiKey } : {}),
+          ...(provider.baseUrl ? { baseURL: provider.baseUrl } : {}),
+          maxRetries: settings.openaiMaxRetries,
+          ...(provider.defaultQuery ? { defaultQuery: provider.defaultQuery } : {}),
+          ...(provider.defaultHeaders ? { defaultHeaders: provider.defaultHeaders } : {}),
+          fetch: instrumentedModelFetch(provider.id, globalThis.fetch),
+        });
   providerClientCache.set(provider.id, client);
   return client;
 }
@@ -428,7 +512,11 @@ export function buildProviderClient(provider: ResolvedModelProvider, settings: S
  * the agent is what routes a turn to its provider without mutating the global
  * default client.
  */
-export function buildModelInstance(provider: ResolvedModelProvider, client: OpenAI, modelId: string): Model {
+export function buildModelInstance(
+  provider: ResolvedModelProvider,
+  client: OpenAI,
+  modelId: string,
+): Model {
   return provider.api === "chat"
     ? new OpenAIChatCompletionsModel(client, modelId)
     : new OpenAIResponsesModel(client, modelId);
@@ -445,7 +533,12 @@ export function buildModelInstance(provider: ResolvedModelProvider, client: Open
 export function resolveTurnModel(
   settings: Settings,
   modelId: string,
-): { provider: ResolvedModelProvider; client: OpenAI; model: Model; configured: ConfiguredModel } | null {
+): {
+  provider: ResolvedModelProvider;
+  client: OpenAI;
+  model: Model;
+  configured: ConfiguredModel;
+} | null {
   const resolved = resolveModelProvider(settings, modelId);
   if (!resolved) {
     return null;
@@ -486,7 +579,10 @@ export class MultiProviderModelProvider implements ModelProvider {
 
   async getModel(modelName?: string): Promise<Model> {
     if (modelName) {
-      const resolved = resolveTurnModel(settingsForRunScopedModelResolution(this.settings, modelName), modelName);
+      const resolved = resolveTurnModel(
+        settingsForRunScopedModelResolution(this.settings, modelName),
+        modelName,
+      );
       if (resolved) {
         // Fail-loud floor (defense in depth): a `codex/<slug>` id must only ever
         // resolve through the synthetic codex-subscription provider (which installs
@@ -496,7 +592,10 @@ export class MultiProviderModelProvider implements ModelProvider {
         // to Azure/OpenAI as a deployment name (DeploymentNotFound 404). Refuse it
         // here so codex can never reach a non-codex client on ANY backend; the
         // primary fix (config configuredModels) keeps this a no-op in practice.
-        if (modelName.startsWith(CODEX_MODEL_ID_PREFIX) && resolved.provider.kind !== "codex-subscription") {
+        if (
+          modelName.startsWith(CODEX_MODEL_ID_PREFIX) &&
+          resolved.provider.kind !== "codex-subscription"
+        ) {
           throw new CodexSubscriptionUnavailableError(modelName);
         }
         return resolved.model;
@@ -538,11 +637,16 @@ function settingsForRunScopedModelResolution(settings: Settings, modelName: stri
   // bare registry id would otherwise be claimed by the built-in only because of
   // that per-turn override. Resolve the run-scoped router against the deployment
   // allow-list head instead; real built-in models stay in the allow-list.
-  return builtinAllowed.includes(modelName) ? settings : { ...settings, openaiModel: fallbackBuiltin };
+  return builtinAllowed.includes(modelName)
+    ? settings
+    : { ...settings, openaiModel: fallbackBuiltin };
 }
 
 function splitOpenaiAllowedModels(value: string): string[] {
-  return value.split(",").map((item) => item.trim()).filter(Boolean);
+  return value
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
 }
 
 /**
@@ -557,13 +661,34 @@ function splitOpenaiAllowedModels(value: string): string[] {
 export class CodexSubscriptionUnavailableError extends Error {
   constructor(modelName: string) {
     super(
-      `Codex subscription model "${modelName}" is unavailable: no active Codex subscription is connected for this workspace. `
-      + `Connect (or reconnect) your ChatGPT/Codex subscription in Settings, then retry.`,
+      `Codex subscription model "${modelName}" is unavailable: no active Codex subscription is connected for this workspace. ` +
+        `Connect (or reconnect) your ChatGPT/Codex subscription in Settings, then retry.`,
     );
     this.name = "CodexSubscriptionUnavailableError";
   }
 }
 
+/**
+ * The workspace's model policy blocks the provider/model this turn resolved
+ * to. Thrown at the worker's post-resolution gate INSTEAD of running the turn
+ * on the blocked provider — a policy-restricted workspace (e.g. fail-closed to
+ * the Codex subscription) must never silently remap to, or fall through to,
+ * the paid built-in client. Like CodexSubscriptionUnavailableError the message
+ * is user-actionable and surfaces verbatim as a non-retryable turn.failed.
+ */
+export class WorkspaceModelPolicyBlockedError extends Error {
+  constructor(modelName: string, providerId: string, reason: "provider" | "model") {
+    super(
+      reason === "provider"
+        ? `Model "${modelName}" is not available in this workspace: its provider ("${providerId}") is not in the workspace's allowed providers. ` +
+            `Pick an allowed model, or ask a workspace admin to change the workspace model policy.`
+        : `Model "${modelName}" is not in this workspace's allowed models. ` +
+            `Pick an allowed model, or ask a workspace admin to change the workspace model policy.`,
+    );
+    this.name = "WorkspaceModelPolicyBlockedError";
+  }
+}
+
 export function configureOpenAI(settings: Settings): void {
   setOpenAIResponsesTransport(settings.openaiResponsesTransport);
   setTracingDisabled(settings.disableOpenaiTracing || !settings.observabilityOtlpEndpoint);
@@ -604,25 +729,32 @@ function instrumentedModelFetch(provider: string, inner: typeof fetch): typeof f
 }
 
 function isModelCallFetch(input: Parameters<typeof fetch>[0]): boolean {
-  const rawUrl = typeof input === "string"
-    ? input
-    : input instanceof URL
-      ? input.toString()
-      : (input as { url?: unknown }).url;
+  const rawUrl =
+    typeof input === "string"
+      ? input
+      : input instanceof URL
+        ? input.toString()
+        : (input as { url?: unknown }).url;
   if (typeof rawUrl !== "string" || rawUrl.length === 0) {
     return false;
   }
   try {
     const pathname = new URL(rawUrl, "http://opengeni.local").pathname;
-    return pathname.endsWith("/responses")
-      || pathname.endsWith("/chat/completions")
-      || pathname.endsWith("/codex/responses");
+    return (
+      pathname.endsWith("/responses") ||
+      pathname.endsWith("/chat/completions") ||
+      pathname.endsWith("/codex/responses")
+    );
   } catch {
     return /\/(?:codex\/)?responses(?:\?|$)|\/chat\/completions(?:\?|$)/.test(rawUrl);
   }
 }
 
-function recordModelCallMetric(provider: string, outcome: "completed" | "failed", started: number): void {
+function recordModelCallMetric(
+  provider: string,
+  outcome: "completed" | "failed",
+  started: number,
+): void {
   const durationSeconds = Math.max(0, (performance.now() - started) / 1000);
   try {
     runtimeMetricsHooks?.onModelCall?.({ provider, outcome, durationSeconds });
@@ -634,10 +766,10 @@ function recordModelCallMetric(provider: string, outcome: "completed" | "failed"
 /**
  * Run the compaction summarizer as one plain, tool-less, non-streaming model
  * call against the resolved provider. `input` is the active history plus
- * Codex's checkpoint prompt. Returns the trimmed summary text, or null on any
- * failure (the caller can retry with a harder-trimmed transcript, then fall
- * back to deterministic non-LLM compaction). The call deliberately does NOT
- * request reasoning encryption, tools, or server-side compaction; it is a
+ * Codex's checkpoint prompt. Provider failures propagate to the compaction
+ * lifecycle; there is no non-model fallback that silently discards history.
+ * The call deliberately does NOT
+ * request reasoning encryption, tools, or inline provider compaction; it is a
  * self-contained summarize.
  *
  * Provider-aware: the summary always runs on the SAME provider that serves the
@@ -645,52 +777,69 @@ function recordModelCallMetric(provider: string, outcome: "completed" | "failed"
  * versa). `api: "chat"` providers (Fireworks) speak /v1/chat/completions, where
  * the summary is choices[0].message.content; `api: "responses"` (the default,
  * built-in OpenAI/Azure) speaks /v1/responses as before. When no client/api is
- * supplied it falls back to the built-in OpenAI/Azure Responses path so the
- * legacy global-client callers are byte-for-byte unchanged. store:false is set
+ * supplied it uses the built-in OpenAI/Azure Responses path. store:false is set
  * only on the OpenAI-platform Responses path (Azure rejects it; chat ignores it).
  */
 export async function summarizeForCompaction(
   settings: Settings,
   input: Array<Record<string, unknown>>,
-  options: { client?: OpenAI; api?: ModelProviderApi; maxOutputTokens?: number; model?: string; maxTranscriptTokens?: number } = {},
-): Promise<string | null> {
+  options: {
+    client?: OpenAI;
+    api?: ModelProviderApi;
+    maxOutputTokens?: number;
+    model?: string;
+    promptCacheKey?: string;
+    systemInstructions?: string;
+    onUsage?: (usage: ModelResponseUsage) => void | Promise<void>;
+  } = {},
+): Promise<string> {
   const client = options.client ?? buildOpenAIClientFromSettings(settings);
   const api = options.api ?? "responses";
   const model = options.model ?? settings.openaiModel;
   const maxTokens = options.maxOutputTokens ?? SUMMARY_BUFFER_TOKENS;
-  const transcript = renderCompactionPromptInputForChat(
-    input,
-    typeof options.maxTranscriptTokens === "number" && options.maxTranscriptTokens > 0
-      ? { maxEstimatedTokens: options.maxTranscriptTokens }
-      : {},
-  );
-  try {
-    if (api === "chat") {
-      const completion = await client.chat.completions.create({
-        model,
-        max_tokens: maxTokens,
-        messages: [{ role: "user", content: transcript }],
-      } as any);
-      const text = (completion as { choices?: Array<{ message?: { content?: unknown } }> }).choices?.[0]?.message?.content;
-      const trimmed = typeof text === "string" ? text.trim() : "";
-      return trimmed.length > 0 ? trimmed : null;
-    }
-    const response = await client.responses.create({
+  if (api === "chat") {
+    const transcript = renderCompactionPromptInputForChat(input);
+    const completion = await client.chat.completions.create({
       model,
-      // store:false is the OpenAI-platform-only storeless precondition; Azure
-      // rejects it. The summarizer's resolved client is OpenAI/Azure on the
-      // built-in path (api "responses"), so gate it on the built-in provider.
-      ...(settings.openaiProvider === "azure" ? {} : { store: false }),
-      max_output_tokens: maxTokens,
-      input: transcript,
+      max_tokens: maxTokens,
+      messages: [{ role: "user", content: transcript }],
+      ...(options.promptCacheKey ? { prompt_cache_key: options.promptCacheKey } : {}),
     } as any);
-    const text = extractResponseOutputText(response);
-    const trimmed = text.trim();
-    return trimmed.length > 0 ? trimmed : null;
-  } catch (error) {
-    console.error("context compaction summarize failed", error);
-    return null;
+    const usage = modelResponseUsageFromResponse(completion);
+    if (usage) {
+      await options.onUsage?.(usage);
+    }
+    const text = (completion as { choices?: Array<{ message?: { content?: unknown } }> })
+      .choices?.[0]?.message?.content;
+    return typeof text === "string" ? text.trim() : "";
+  }
+  // Use the same SDK Responses adapter as the real agent call. It converts the
+  // structured AgentInputItems (callId/providerData/etc.) to provider wire
+  // items without flattening tool history into a fake user transcript.
+  const request: ModelRequest = {
+    systemInstructions: options.systemInstructions ?? "",
+    input: input as AgentInputItem[],
+    modelSettings: {
+      maxTokens,
+      // Azure rejects store:false; the Codex subscription transport enforces
+      // it independently. The OpenAI platform path remains explicitly storeless.
+      ...(settings.openaiProvider === "azure" ? {} : { store: false }),
+      ...(options.promptCacheKey
+        ? { providerData: { prompt_cache_key: options.promptCacheKey } }
+        : {}),
+    },
+    tools: [],
+    toolsExplicitlyProvided: true,
+    outputType: "text",
+    handoffs: [],
+    tracing: false,
+  };
+  const response = await new CompactionResponsesModel(client, model).fetchResponse(request);
+  const usage = modelResponseUsageFromResponse(response);
+  if (usage) {
+    await options.onUsage?.(usage);
   }
+  return extractResponseOutputText(response).trim();
 }
 
 /**
@@ -730,7 +879,11 @@ export function extractResponseOutputText(response: unknown): string {
       continue;
     }
     for (const part of content) {
-      if (part && typeof part === "object" && typeof (part as { text?: unknown }).text === "string") {
+      if (
+        part &&
+        typeof part === "object" &&
+        typeof (part as { text?: unknown }).text === "string"
+      ) {
         parts.push((part as { text: string }).text);
       }
     }
@@ -738,6 +891,21 @@ export function extractResponseOutputText(response: unknown): string {
   return parts.join("");
 }
 
+/**
+ * The public SDK getResponse() method is runner-facing and always opens a
+ * tracing span. Compaction is a standalone model call, so use the same SDK
+ * request conversion and Responses transport without manufacturing a runner
+ * trace solely to satisfy that wrapper.
+ */
+class CompactionResponsesModel extends OpenAIResponsesModel {
+  fetchResponse(request: ModelRequest) {
+    return this._fetchResponse(request, false);
+  }
+}
+
+export type GitTokenSeeds = Partial<Record<GitCredentialProvider, string>>;
+export type GitCredentialTokenWriterSession = SandboxSessionLike;
+
 export type BuildAgentOptions = {
   model?: Model;
   reasoningEffort?: ReasoningEffort;
@@ -745,11 +913,6 @@ export type BuildAgentOptions = {
   // today's settings-derived behaviour when omitted, so the legacy
   // global-client callers (no model resolution) are byte-for-byte unchanged.
   //
-  // - compactionMode: the resolved context-compaction path. Drives whether the
-  //   sandbox `compaction()` capability is attached AND whether `store: false`
-  //   is set (the OpenAI-platform-only storeless precondition). Registry
-  //   providers resolve to "client", so neither is applied to them.
-  //   Default: resolveContextCompactionMode(settings).
   // - hostedWebSearch: attach the hosted web_search tool. Only the providers
   //   that actually execute it (built-in OpenAI/Azure; a registry model that
   //   opts in) should get it — Fireworks accepts the param but no-ops it, which
@@ -758,9 +921,6 @@ export type BuildAgentOptions = {
   //   providerData.include. Only the Responses API carries it; the chat wire
   //   API has no such field, so registry "chat" providers turn it off.
   //   Default: settings.openaiReasoningEncryptedContent.
-  // - contextWindowTokens: the model's effective window, used to derive the
-  //   server-path compaction threshold. A registry model can declare its own
-  //   (e.g. GLM 5.2's 1,048,576). Default: settings.contextWindowTokens.
   // - structuredToolTransport: whether the backend supports the Responses
   //   STRUCTURED/HOSTED sandbox-tool transport — the hosted `apply_patch` tool
   //   type and structured `view_image` output. The SDK's sandbox capabilities
@@ -773,10 +933,8 @@ export type BuildAgentOptions = {
   //   function `apply_patch` + text `view_image` variants it accepts. Default
   //   true (let the SDK decide from the model instance) — non-codex paths are
   //   byte-for-byte unchanged.
-  compactionMode?: ContextCompactionMode;
   hostedWebSearch?: boolean;
   encryptedReasoning?: boolean;
-  contextWindowTokens?: number;
   structuredToolTransport?: boolean;
   // EXPLICIT computer-use tool transport, decided where provider identity is
   // authoritative (the worker's model resolution — agent-turn.ts). Threaded into
@@ -784,12 +942,24 @@ export type BuildAgentOptions = {
   // on the SDK's constructor-name sniff. When omitted, the legacy sniff +
   // `structuredToolTransport` neutralize path is preserved byte-for-byte.
   computerToolMode?: ComputerToolMode;
+  /**
+   * Invoked once, immediately before the first real computer action and after
+   * the display is ready. Merely advertising computer-use does not call it.
+   * The worker uses this seam for computer-use-only recording; ordinary
+   * shell/filesystem turns never pay that cost.
+   */
+  onComputerUseReady?: (session: SandboxSessionLike) => Promise<void>;
   // The LIVE, by-reference connector-namespace Set from prepareAgentTools
   // (codexConnectorNamespaces): fills during each turn's codex_apps tools/list,
   // read per model call by the codex tool_search description so the model sees
   // the account's ACTUALLY-connected sources (codex-rs parity). Only meaningful
   // on the codex tool-search path.
   codexConnectorNamespaces?: ReadonlySet<string>;
+  // Stable per-session routing key for provider-side prompt prefix caches. The
+  // worker passes this only for transports whose docs/API surface accept
+  // prompt_cache_key; registry providers that use a different affinity field stay
+  // unset to avoid unknown-parameter 400s.
+  promptCacheKey?: string;
   sandboxEnvironment?: Record<string, string>;
   // The EFFECTIVE/active compute backend for this turn. `settings.sandboxBackend`
   // is the session's HOME backend (the default cloud group box it was created
@@ -806,27 +976,49 @@ export type BuildAgentOptions = {
   activeSandboxBackend?: Settings["sandboxBackend"];
   fileResourceDownloads?: SandboxFileDownload[];
   mcpServers?: MCPServer[];
+  // Workspace Memory V1 working-set block, resolved by the worker per turn.
+  // Composed after the workspace persona/CORE/toolspace substrate and before
+  // per-session instructions. Omitted/blank ⇒ byte-identical instructions.
+  workspaceMemory?: string;
   workspaceEnvironment?: WorkspaceEnvironmentContext;
-  // TOKEN-BROKER (B1): the run-scoped GitHub App installation token, minted ONCE
-  // per turn by the worker (sandboxEnvironmentForRun's `gitToken`). Threaded here
-  // OFF-MANIFEST — it is NOT part of sandboxEnvironment (the manifest env), so the
-  // token VALUE never triggers the SDK's provided-session env-delta guard even
-  // though it rotates every turn. buildAgent stashes it alongside the agent's
-  // repository-clone hooks; runStream forwards it into the clone hook context, which
-  // seeds it to the box's token FILE before the clone runs. Omitted on the
-  // selfhosted path (the machine uses its own git creds) — a NO-OP there.
+  // M3 rig runtime binding (all absent ⇒ a rig-less turn, byte-for-byte today).
+  //  - `rig`: renders the non-bypassable rig doctrine block in the CORE.
+  //  - `rigSetup`: the rig version's setup script, run ONCE per box (marker-
+  //    guarded) as the FIRST beforeAgentStart hook so later hooks see its tooling.
+  //  - `rigCredentialHookIds`: the rig version's credential_hooks, unioned with
+  //    the deployment preparation-profile hooks. Resolved (and VALIDATED — an
+  //    unknown name throws here, at build = per-turn resolution time) so a typo'd
+  //    hook fails the turn instead of being silently ignored.
+  rig?: RigInstructionsContext;
+  rigSetup?: RigSetupDescriptor;
+  rigCredentialHookIds?: string[];
+  // TOKEN-BROKER (B1): the run-scoped GitHub App installation token alias,
+  // minted ONCE per turn by the worker (sandboxEnvironmentForRun's `gitToken`).
+  // Kept for back-compat; internally it maps to gitTokenSeeds.github.
   gitTokenSeed?: string;
+  // Provider-token map for GitHub/GitLab/Azure DevOps. Threaded here OFF-
+  // MANIFEST — it is NOT part of sandboxEnvironment (the manifest env), so token
+  // VALUES never trigger the SDK's provided-session env-delta guard even though
+  // they rotate every turn. buildAgent stashes them alongside the agent's
+  // repository-clone hooks; runStream forwards them into the hook context, which
+  // seeds provider token FILES before the clone/setup runs.
+  gitTokenSeeds?: GitTokenSeeds;
   // TOOLSPACE: the run-scoped delegated token to seed into
   // $OPENGENI_TOOLSPACE_TOKEN_FILE. Like gitTokenSeed, this stays off the
   // manifest/env delta and is written into the sandbox filesystem by a lifecycle
   // hook before the agent starts.
   toolspaceTokenSeed?: string;
-  // Genesis turn only: append a one-shot instruction to the agent's system
-  // prompt telling it to title the session via opengeni__set_session_title
-  // before responding. Delivered through the instructions channel (where the
-  // model actually obeys), appended AFTER the non-bypassable core so a
-  // white-label persona template can't drop it.
+  // Genesis turn only: inject a one-shot instruction into the FIRST model
+  // call telling it to title the session via opengeni__set_session_title.
+  // Keeping this out of the persistent Agent.instructions prevents every
+  // tool-follow-up model call in a long first turn from re-running setup.
   genesisTitleHint?: boolean;
+  // Persistent session settings, resolved by the worker from the durable
+  // session row at turn start. Tool schemas are rebuilt on every turn, so
+  // without this factual state the model can mistake persistent metadata tools
+  // for per-turn initialization and re-apply the same title/notification mode.
+  // Values only — never the user-controlled title text — enter instructions.
+  persistentSessionSettings?: PersistentSessionSettings;
   // Per-call agent persona override (the white-label surface). Resolved by the
   // caller as session > workspace > deployment default; when omitted the
   // runtime falls back to settings.agentInstructionsTemplate. The runtime
@@ -876,7 +1068,35 @@ export type WorkspaceEnvironmentContext = {
   variableNames?: string[];
 };
 
-export function workspaceEnvironmentInstructions(environment: WorkspaceEnvironmentContext): string[] {
+export type PersistentSessionSettings = {
+  titleIsSet: boolean;
+  childNotificationsMode?: "digest" | "passive";
+};
+
+/**
+ * The rig a session rides (M3): its name + the active version pinned onto the
+ * session. Surfaced verbatim in the non-bypassable CORE instructions so the
+ * agent understands its sandbox is a disposable fork of a shared, versioned
+ * machine definition and how to promote a durable change. Absent for rig-less
+ * sessions (the block never renders).
+ */
+export type RigInstructionsContext = {
+  name: string;
+  version: number;
+};
+
+export function rigInstructions(rig: RigInstructionsContext): string[] {
+  return [
+    `This session runs on rig "${rig.name}" (active version v${rig.version}) — a shared, versioned sandbox machine definition for your workspace.`,
+    "Your sandbox is an EPHEMERAL FORK of that rig: you have root and may install anything freely, but everything you change here is junk that dies with the box and never reaches the rig or other sessions.",
+    "For a DURABLE, team-wide change (tooling every future session on this rig should have), propose it with rig_propose_change, passing the EXACT command that already worked in this box — never assume an unverified change propagates.",
+    "If tooling you expect is missing, consult rig_get to see the rig's current setup and checks before reinstalling.",
+  ];
+}
+
+export function workspaceEnvironmentInstructions(
+  environment: WorkspaceEnvironmentContext,
+): string[] {
   const lines = [
     `A workspace environment named "${environment.name}" is attached to this session; its variables are exported in the sandbox shell environment.`,
   ];
@@ -902,10 +1122,16 @@ export function workspaceEnvironmentInstructions(environment: WorkspaceEnvironme
  * drop: composeAgentInstructions() substitutes it at the persona template's
  * {{core}} marker, and appends it when the marker is absent.
  */
-export function coreInstructions(workspaceEnvironment?: WorkspaceEnvironmentContext): string[] {
+export function coreInstructions(
+  workspaceEnvironment?: WorkspaceEnvironmentContext,
+  rig?: RigInstructionsContext,
+): string[] {
   return [
     "If the session has a goal, you own it: keep working until you call opengeni__goal_complete with concrete evidence or opengeni__goal_pause with a rationale; revise it with opengeni__goal_update; create one with opengeni__goal_set when given a long-running objective.",
     ...(workspaceEnvironment ? workspaceEnvironmentInstructions(workspaceEnvironment) : []),
+    // Rig doctrine (M3): data-conditional, inside the non-bypassable CORE so a
+    // white-label persona template can never drop it. Absent for rig-less sessions.
+    ...(rig ? rigInstructions(rig) : []),
   ];
 }
 
@@ -917,8 +1143,12 @@ export function coreInstructions(workspaceEnvironment?: WorkspaceEnvironmentCont
  * and the append both join by " ", so the DEFAULT_AGENT_INSTRUCTIONS template
  * with an empty environment reproduces the historical preamble byte-for-byte.
  */
-export function composeAgentInstructions(template: string, workspaceEnvironment?: WorkspaceEnvironmentContext): string {
-  const core = coreInstructions(workspaceEnvironment).join(" ");
+export function composeAgentInstructions(
+  template: string,
+  workspaceEnvironment?: WorkspaceEnvironmentContext,
+  rig?: RigInstructionsContext,
+): string {
+  const core = coreInstructions(workspaceEnvironment, rig).join(" ");
   if (template.includes(AGENT_INSTRUCTIONS_CORE_PLACEHOLDER)) {
     return template.split(AGENT_INSTRUCTIONS_CORE_PLACEHOLDER).join(core);
   }
@@ -937,6 +1167,41 @@ export function appendSessionInstructions(composed: string, sessionInstructions?
   return trimmed ? `${composed} ${trimmed}` : composed;
 }
 
+/**
+ * Append the durable session metadata the model otherwise cannot observe.
+ * This is deliberately declarative and excludes the title text: the title is
+ * user-controlled display metadata, while the agent only needs to know whether
+ * initialization has already happened. The block is present on every turn when
+ * supplied so compaction cannot erase knowledge that these settings persist.
+ */
+export function appendPersistentSessionSettings(
+  composed: string,
+  settings?: PersistentSessionSettings,
+): string {
+  if (!settings) {
+    return composed;
+  }
+  const childState = settings.childNotificationsMode
+    ? `; spawned-worker completion notifications are ${settings.childNotificationsMode}`
+    : "";
+  const persistentTools = settings.childNotificationsMode
+    ? "opengeni__set_session_title or opengeni__set_child_notifications_mode"
+    : "opengeni__set_session_title";
+  return `${composed} Persistent session settings already in effect: the display title is ${settings.titleIsSet ? "set" : "not set"}${childState}. These settings persist across turns, continuations, and interruptions. Do not call ${persistentTools} merely to reassert an unchanged value; call them only when the current value actually needs to change.`;
+}
+
+/**
+ * Appends the workspace memory working-set block to the already-composed
+ * (workspace + CORE + generic substrate) instructions, joined by " ". The
+ * memory slice is workspace-ground and intentionally lands before
+ * per-session instructions. An absent/blank value is a no-op that returns the
+ * composed string byte-for-byte.
+ */
+export function appendWorkspaceMemory(composed: string, workspaceMemory?: string): string {
+  const trimmed = workspaceMemory?.trim();
+  return trimmed ? `${composed} ${trimmed}` : composed;
+}
+
 /**
  * Appends the generic programmatic-tool-calling (toolspace) directive to the
  * composed workspace + CORE instructions, joined by " ". This is GENERIC
@@ -961,23 +1226,36 @@ export function appendToolspaceInstructions(composed: string, toolspaceAvailable
  * " " and always LAST so a white-label persona template or a per-session
  * instruction can't drop it. A no-op when the hint is absent.
  */
-export function appendGenesisTitleDirective(instructions: string, genesisTitleHint?: boolean): string {
+export function appendGenesisTitleDirective(
+  instructions: string,
+  genesisTitleHint?: boolean,
+): string {
   return genesisTitleHint ? `${instructions} ${GENESIS_TITLE_DIRECTIVE}` : instructions;
 }
 
 const agentFileDownloads = new WeakMap<object, SandboxFileDownload[]>();
 const agentRepositoryCloneHooks = new WeakMap<object, SandboxLifecycleHook[]>();
-// TOKEN-BROKER (B1): the per-turn git token seed, stashed alongside the agent's
-// repository-clone hooks (a parallel map keyed by the agent). Kept OFF the
-// manifest/defaultManifest so the rotating value never rides the SDK's provided-
-// session env; runStream reads it to build the clone hook context. Absent when
-// no repo is attached / on the selfhosted path.
-const agentGitTokenSeed = new WeakMap<object, string>();
+// TOKEN-BROKER (B1): the per-turn provider git token seeds, stashed alongside
+// the agent's repository-clone hooks (a parallel map keyed by the agent). Kept
+// OFF the manifest/defaultManifest so rotating values never ride the SDK's
+// provided-session env; runStream reads them to build the clone hook context.
+// Absent when no brokered repo is attached / on the selfhosted path.
+const agentGitTokenSeeds = new WeakMap<object, GitTokenSeeds>();
 const agentToolspaceTokenSeed = new WeakMap<object, string>();
+// A genesis directive is consumed by runAgentStream exactly once for the
+// freshly-built agent. It must not remain in Agent.instructions: those
+// instructions are presented again on every internal model/tool loop.
+const agentsNeedingGenesisTitleDirective = new WeakSet<object>();
 // The EFFECTIVE backend the turn resolved for this agent (undefined -> the home
 // backend). Read by runStream's owned branch to keep platform box-setup hooks off
 // connected machines (a user's real computer).
 const agentActiveSandboxBackend = new WeakMap<object, Settings["sandboxBackend"]>();
+// M3: the rig-setup descriptor + resolved rig credential hooks for this agent's
+// turn (kept off the manifest like the clone hooks). Read by runStream to build
+// the rig-setup hook and to union the rig credential hooks with the deployment
+// preparation-profile hooks. Absent for a rig-less turn.
+const agentRigSetup = new WeakMap<object, RigSetupDescriptor>();
+const agentRigCredentialHooks = new WeakMap<object, SandboxLifecycleHook[]>();
 
 /**
  * The tool output emitted for an MCP tool call that FAILED with a THROWN error
@@ -1003,9 +1281,20 @@ const agentActiveSandboxBackend = new WeakMap<object, Settings["sandboxBackend"]
  * requires an SDK-level change (preserve `isError`) or reading the raw
  * CallToolResult — tracked separately.
  */
-export function mcpToolErrorOutput(error: unknown): { isError: true; content: [{ type: "text"; text: string }] } {
+export function mcpToolErrorOutput(error: unknown): {
+  isError: true;
+  content: [{ type: "text"; text: string }];
+} {
   const details = error instanceof Error ? error.message : String(error);
-  return { isError: true, content: [{ type: "text", text: `An error occurred while running the tool. Please try again. Error: ${details}` }] };
+  return {
+    isError: true,
+    content: [
+      {
+        type: "text",
+        text: `An error occurred while running the tool. Please try again. Error: ${details}`,
+      },
+    ],
+  };
 }
 
 // Applied to EVERY MCP server via the agent's `mcpConfig.errorFunction`
@@ -1013,17 +1302,24 @@ export function mcpToolErrorOutput(error: unknown): { isError: true; content: [{
 // SDK types the return as `string`; the runtime actually stores the raw return
 // as the tool output, so we return the MCP-shaped error object and cast — this
 // is the only way to attach an `isError` flag to a failed MCP tool call's output.
-const mcpToolErrorFunction: MCPToolErrorFunction = ({ error }) => mcpToolErrorOutput(error) as unknown as string;
+const mcpToolErrorFunction: MCPToolErrorFunction = ({ error }) =>
+  mcpToolErrorOutput(error) as unknown as string;
 
-export function buildOpenGeniAgent(settings: Settings, resources: ResourceRef[], options: BuildAgentOptions = {}): Agent<any, any> {
+export function buildOpenGeniAgent(
+  settings: Settings,
+  resources: ResourceRef[],
+  options: BuildAgentOptions = {},
+): Agent<any, any> {
   // Resolved per-turn gating. Each override defaults to today's settings-derived
   // behaviour, so the legacy global-client callers (no resolved model) build the
   // exact same agent as before; the multi-provider worker path passes the
-  // resolved provider's mode/api/window/web-search instead.
-  const compactionMode = options.compactionMode ?? resolveContextCompactionMode(settings);
+  // resolved provider's api/window/web-search instead.
   const hostedWebSearch = options.hostedWebSearch ?? settings.webSearchEnabled;
   const encryptedReasoning = options.encryptedReasoning ?? settings.openaiReasoningEncryptedContent;
-  const contextWindowTokens = options.contextWindowTokens ?? settings.contextWindowTokens;
+  const providerData = {
+    ...(encryptedReasoning ? { include: ["reasoning.encrypted_content"] } : {}),
+    ...(options.promptCacheKey ? { prompt_cache_key: options.promptCacheKey } : {}),
+  };
   // Native hosted tools attached to every constructed agent. webSearchEnabled
   // is ON by default and provider-unconditional on the built-in path (the live
   // Azure Responses path executes the hosted web_search tool); a registry model
@@ -1053,32 +1349,36 @@ export function buildOpenGeniAgent(settings: Settings, resources: ResourceRef[],
     //      when a toolspace token was minted for this turn (feature enabled + a
     //      per-turn seed — the mint gate, which includes selfhosted turns since
     //      they now receive the token too) — appendToolspaceInstructions,
-    //   3. + the per-session persona instructions (session-specific, so it
+    //   3. + workspace memory working set, ONLY when the workspace setting is on
+    //      and the worker resolved a nonblank block — appendWorkspaceMemory,
+    //   4. + the per-session persona instructions (session-specific, so it
     //      refines both the workspace persona and the substrate note),
-    //   4. + the one-shot genesis title directive (genesis turn only).
-    // With no toolspace token, no session instructions, and no genesis hint this
-    // is byte-identical to the historical composed instructions.
-    instructions: appendGenesisTitleDirective(
+    //   5. + durable session-setting state (title present + child notification
+    //      mode), when supplied by the worker,
+    // The genesis title directive is deliberately NOT part of this persistent
+    // string. runAgentStream injects it into the first model call only.
+    instructions: appendPersistentSessionSettings(
       appendSessionInstructions(
-        appendToolspaceInstructions(
-          composeAgentInstructions(options.instructionsTemplate ?? settings.agentInstructionsTemplate, options.workspaceEnvironment),
-          settings.toolspaceEnabled && Boolean(options.toolspaceTokenSeed),
+        appendWorkspaceMemory(
+          appendToolspaceInstructions(
+            composeAgentInstructions(
+              options.instructionsTemplate ?? settings.agentInstructionsTemplate,
+              options.workspaceEnvironment,
+              options.rig,
+            ),
+            settings.toolspaceEnabled && Boolean(options.toolspaceTokenSeed),
+          ),
+          options.workspaceMemory,
         ),
         options.sessionInstructions,
       ),
-      options.genesisTitleHint,
+      options.persistentSessionSettings,
     ),
     modelSettings: {
-      reasoning: { effort: options.reasoningEffort ?? settings.openaiReasoningEffort, summary: "detailed" },
-      // Server-side compaction (OpenAI platform) requires store=false: the
-      // server emits an opaque ENCRYPTED 'compaction' item that round-trips in
-      // the request rather than being anchored to a stored response. OpenGeni
-      // already runs storeless (provider item ids stripped, encrypted reasoning
-      // round-tripped), so this is consistent with the existing design and
-      // only set where the server compaction capability is attached. Gated on
-      // the RESOLVED compaction mode (registry providers resolve to "client",
-      // so they never carry store:false).
-      ...(compactionMode === "server" ? { store: false } : {}),
+      reasoning: {
+        effort: options.reasoningEffort ?? settings.openaiReasoningEffort,
+        summary: "detailed",
+      },
       // Round-trip the encrypted reasoning payload with every call so chains
       // of thought survive without provider-side response storage (which is
       // what stripped provider item ids opt us out of — see
@@ -1087,9 +1387,7 @@ export function buildOpenGeniAgent(settings: Settings, resources: ResourceRef[],
       // function tools, which contribute none. Gated on the resolved
       // encryptedReasoning flag: the chat wire API has no encrypted_content
       // field, so registry "chat" providers turn it off.
-      ...(encryptedReasoning
-        ? { providerData: { include: ["reasoning.encrypted_content"] } }
-        : {}),
+      ...(Object.keys(providerData).length > 0 ? { providerData } : {}),
     },
     // Explicit hosted tools (web_search when enabled). Threaded into BOTH the
     // `new Agent(baseConfig)` path (sandboxBackend === "none") and the
@@ -1108,6 +1406,9 @@ export function buildOpenGeniAgent(settings: Settings, resources: ResourceRef[],
 
   if (settings.sandboxBackend === "none") {
     const agent = new Agent(baseConfig);
+    if (options.genesisTitleHint) {
+      agentsNeedingGenesisTitleDirective.add(agent);
+    }
     maybeInstallCodexToolSearch(agent, settings, options);
     applyMcpApprovalPolicy(agent, settings);
     return agent;
@@ -1116,17 +1417,36 @@ export function buildOpenGeniAgent(settings: Settings, resources: ResourceRef[],
   const runAs = sandboxRunAs(settings);
   const agent = new SandboxAgent({
     ...baseConfig,
-    defaultManifest: buildManifest(settings, resources, options.sandboxEnvironment, options.fileResourceDownloads),
+    defaultManifest: buildManifest(
+      settings,
+      resources,
+      options.sandboxEnvironment,
+      options.fileResourceDownloads,
+    ),
     ...(runAs ? { runAs } : {}),
     capabilities: buildAgentCapabilities(settings, options.packSkills ?? [], {
-      compactionMode,
-      contextWindowTokens,
-      ...(options.structuredToolTransport !== undefined ? { structuredToolTransport: options.structuredToolTransport } : {}),
-      ...(options.computerToolMode !== undefined ? { computerToolMode: options.computerToolMode } : {}),
+      ...(options.structuredToolTransport !== undefined
+        ? { structuredToolTransport: options.structuredToolTransport }
+        : {}),
+      ...(options.computerToolMode !== undefined
+        ? { computerToolMode: options.computerToolMode }
+        : {}),
+      ...(options.onComputerUseReady ? { onComputerUseReady: options.onComputerUseReady } : {}),
     }),
   });
-  agentFileDownloads.set(agent, normalizeSandboxFileDownloads(options.fileResourceDownloads ?? []).filter((download) => !download.content));
-  agentRepositoryCloneHooks.set(agent, sandboxRepositoryCloneHooks(settings, resources, options.activeSandboxBackend));
+  if (options.genesisTitleHint) {
+    agentsNeedingGenesisTitleDirective.add(agent);
+  }
+  agentFileDownloads.set(
+    agent,
+    normalizeSandboxFileDownloads(options.fileResourceDownloads ?? []).filter(
+      (download) => !download.content,
+    ),
+  );
+  agentRepositoryCloneHooks.set(
+    agent,
+    sandboxRepositoryCloneHooks(settings, resources, options.activeSandboxBackend),
+  );
   // Stash the EFFECTIVE backend so runStream's owned branch can skip the direct
   // beforeAgentStart hook run on a connected machine: the box there is the user's
   // REAL computer — the platform must not run setup (az login) against it. The
@@ -1135,14 +1455,29 @@ export function buildOpenGeniAgent(settings: Settings, resources: ResourceRef[],
   if (options.activeSandboxBackend) {
     agentActiveSandboxBackend.set(agent, options.activeSandboxBackend);
   }
-  // TOKEN-BROKER (B1): stash the per-turn seed off-manifest so runStream can seed the
-  // clone hook without the token ever touching defaultManifest / sandboxEnvironment.
-  if (options.gitTokenSeed) {
-    agentGitTokenSeed.set(agent, options.gitTokenSeed);
+  // TOKEN-BROKER (B1): stash per-turn provider seeds off-manifest so runStream
+  // can seed the setup hook without tokens ever touching defaultManifest /
+  // sandboxEnvironment. `gitTokenSeed` remains the GitHub alias.
+  const gitTokenSeeds = {
+    ...(options.gitTokenSeeds ?? {}),
+    ...(options.gitTokenSeed ? { github: options.gitTokenSeed } : {}),
+  } satisfies GitTokenSeeds;
+  if (Object.keys(gitTokenSeeds).length > 0) {
+    agentGitTokenSeeds.set(agent, gitTokenSeeds);
   }
   if (options.toolspaceTokenSeed) {
     agentToolspaceTokenSeed.set(agent, options.toolspaceTokenSeed);
   }
+  // M3: stash the rig setup descriptor + RESOLVE the rig credential hooks now.
+  // sandboxLifecycleHooksForIds throws on an unknown hook name, so a typo'd rig
+  // credential_hook fails the turn HERE (per-turn resolution) rather than being
+  // silently dropped — the fail-visible contract the brief requires.
+  if (options.rigSetup) {
+    agentRigSetup.set(agent, options.rigSetup);
+  }
+  if (options.rigCredentialHookIds && options.rigCredentialHookIds.length > 0) {
+    agentRigCredentialHooks.set(agent, sandboxLifecycleHooksForIds(options.rigCredentialHookIds));
+  }
   maybeInstallCodexToolSearch(agent, settings, options);
   applyMcpApprovalPolicy(agent, settings);
   return agent;
@@ -1157,7 +1492,11 @@ export function buildOpenGeniAgent(settings: Settings, resources: ResourceRef[],
  * codex_apps schemas + add the client tool_search tool, whose description renders
  * the live connector namespaces threaded from prepareAgentTools.
  */
-function maybeInstallCodexToolSearch(agent: Agent<any, any>, settings: Settings, options: BuildAgentOptions): void {
+function maybeInstallCodexToolSearch(
+  agent: Agent<any, any>,
+  settings: Settings,
+  options: BuildAgentOptions,
+): void {
   if (settings.codexToolSearchEnabled && options.structuredToolTransport === false) {
     installCodexToolSearch(
       agent as unknown as Parameters<typeof installCodexToolSearch>[0],
@@ -1197,7 +1536,10 @@ type ApprovalCapableAgent = {
  * paths. The base (non-sandbox) `Agent.clone` spreads `...this` and would carry
  * the override, but re-installing is idempotent there and keeps one code path.
  */
-function installMcpApprovalPolicy(agent: ApprovalCapableAgent, policies: McpApprovalPolicy[]): void {
+function installMcpApprovalPolicy(
+  agent: ApprovalCapableAgent,
+  policies: McpApprovalPolicy[],
+): void {
   const listMcpTools = agent.getMcpTools.bind(agent);
   agent.getMcpTools = async (runContext: unknown) => {
     const tools = await listMcpTools(runContext);
@@ -1252,8 +1594,15 @@ function installMcpApprovalPolicy(agent: ApprovalCapableAgent, policies: McpAppr
  */
 function applyMcpApprovalPolicy(agent: Agent<any, any>, settings: Settings): void {
   const policies: McpApprovalPolicy[] = settings.mcpServers
-    .filter((server) => server.requireApproval === true || (Array.isArray(server.requireApproval) && server.requireApproval.length > 0))
-    .map((server) => ({ prefix: prefixedMcpToolName(server.id, ""), requireApproval: server.requireApproval as boolean | string[] }))
+    .filter(
+      (server) =>
+        server.requireApproval === true ||
+        (Array.isArray(server.requireApproval) && server.requireApproval.length > 0),
+    )
+    .map((server) => ({
+      prefix: prefixedMcpToolName(server.id, ""),
+      requireApproval: server.requireApproval as boolean | string[],
+    }))
     .sort((a, b) => b.prefix.length - a.prefix.length);
   if (policies.length === 0) {
     return;
@@ -1275,7 +1624,9 @@ function applyMcpApprovalPolicy(agent: Agent<any, any>, settings: Settings): voi
  * `computer_screenshot` for computer-use. `bindModel` still returns the capability
  * so the SDK's bind chain (`.bind().bindRunAs().bindModel()`) is preserved.
  */
-function neutralizeStructuredToolTransport(capability: ReturnType<typeof filesystem> | ReturnType<typeof computerUse>): void {
+function neutralizeStructuredToolTransport(
+  capability: ReturnType<typeof filesystem> | ReturnType<typeof computerUse>,
+): void {
   // Use `this` (NOT a captured reference to `capability`): the SandboxAgent binds
   // via `cap.clone().bind(session).bindRunAs(runAs).bindModel(model, instance)` and
   // runs tools() on the object the CHAIN returns. Capability.clone() copies this
@@ -1289,49 +1640,95 @@ function neutralizeStructuredToolTransport(capability: ReturnType<typeof filesys
     this._modelInstance = undefined;
     return this;
   };
-  (capability as unknown as { bindModel: typeof forceFunctionTransport }).bindModel = forceFunctionTransport;
+  (capability as unknown as { bindModel: typeof forceFunctionTransport }).bindModel =
+    forceFunctionTransport;
 }
 
 /**
- * Build the SandboxAgent capability set provider-aware.
- *
- * The SDK's `Capabilities.default()` force-includes `compaction()`, whose
- * sampling params emit `context_management:[{type:'compaction', …}]` to the
- * Responses transport. The OpenAI platform honors that (server-side compaction);
- * AZURE rejects it with `400 unsupported_parameter` — which is exactly the live
- * production failure on Azure today. So we MUST NOT attach the compaction
- * capability on the Azure / client / off paths.
- *
- * We rebuild the base set explicitly (`filesystem()`, `shell()`, the same
- * factories the SDK default uses) and add `compaction()` ONLY on the server
- * path, with an explicit `StaticCompactionPolicy(threshold)` so gpt-5.5 — which
- * is absent from the SDK's hardcoded context-window map and would otherwise hit
- * the wrong 240k fallback — gets the correct threshold. The SDK has no
- * window-registration API, so an explicit threshold is the only way to fix it.
- *
- * The resolved compaction mode and the effective context window are now passed
- * IN (the multi-provider caller resolves them per provider/model) rather than
- * re-derived from settings here. Both default to the settings-derived value so
- * callers that don't route per-model (and the existing tests) keep today's exact
- * behaviour; the effective window only changes the server-path threshold when a
- * resolved model declares its own contextWindowTokens.
+ * Build the SandboxAgent capability set explicitly. The SDK default includes
+ * its inline provider compaction capability; OpenGeni deliberately omits it
+ * because durable portable compaction owns the full history transition.
+ */
+/**
+ * Wrap the shell capability's `exec_command` so its execution runs inside a
+ * tool-call correlation context (op-correlation.ts): the SDK's tool machinery
+ * passes `details.toolCall` (the model's function_call, with its durable
+ * `callId`) into every function-tool `invoke`, and binding an
+ * AsyncLocalStorage around the invocation makes that id visible to the sandbox
+ * transport underneath — which mints the DURABLE op id `{callId}:{ordinal}`
+ * (op-stream ruling B1). A re-dispatched turn re-executes the same
+ * function_call with the same callId, so the transport's idempotent OpStart
+ * ATTACHES to the already-running/completed op instead of re-running it.
+ * Without a callId (no details on the invocation) the tool runs unwrapped and
+ * the transport falls back to a random unique id — today's semantics.
+ */
+function withExecOpCorrelation(tools: Tool<unknown>[]): Tool<unknown>[] {
+  return tools.map((capabilityTool) => {
+    if (capabilityTool.type !== "function" || capabilityTool.name !== "exec_command") {
+      return capabilityTool;
+    }
+    const invoke = capabilityTool.invoke;
+    return {
+      ...capabilityTool,
+      invoke: (runContext, input, details) => {
+        const callId = details?.toolCall?.callId;
+        if (!callId) {
+          return invoke(runContext, input, details);
+        }
+        return runWithToolCallCorrelation(callId, () => invoke(runContext, input, details));
+      },
+    };
+  });
+}
+
+/**
+ * Codex accepts ordinary FUNCTION tools but also accepts `input_image` content
+ * inside a function_call_output (the same transport used by codex-rs
+ * view_image). The SDK filesystem capability unnecessarily couples this choice
+ * to hosted apply_patch support; when hosted tools are disabled it degrades
+ * view_image to a giant text data URL, charging roughly one token per four
+ * base64 characters. Re-wrap only successful data-URL results as a structured
+ * image. Text errors remain text, and the tool itself remains a normal function.
  */
+export function withStructuredViewImageFunctionResults(tools: Tool<unknown>[]): Tool<unknown>[] {
+  return tools.map((capabilityTool) => {
+    if (capabilityTool.type !== "function" || capabilityTool.name !== "view_image") {
+      return capabilityTool;
+    }
+    const invoke = capabilityTool.invoke;
+    return {
+      ...capabilityTool,
+      invoke: async (runContext, input, details) => {
+        const output = await invoke(runContext, input, details);
+        const dataUrl =
+          typeof output === "string"
+            ? output
+            : output &&
+                typeof output === "object" &&
+                typeof (output as { text?: unknown }).text === "string"
+              ? (output as { text: string }).text
+              : null;
+        return dataUrl?.startsWith("data:image/")
+          ? { type: "image" as const, image: { url: dataUrl } }
+          : output;
+      },
+    };
+  });
+}
+
 export function buildAgentCapabilities(
   settings: Settings,
   packSkills: PackSkill[],
   options: {
-    compactionMode?: ContextCompactionMode;
-    contextWindowTokens?: number;
     structuredToolTransport?: boolean;
     // EXPLICIT computer-use transport (see BuildAgentOptions.computerToolMode). When
     // present, computerUse() is handed the mode directly and its tools() obeys it
     // without the constructor-name sniff. When absent, the legacy neutralize +
     // imageFunctionResults path (driven by structuredToolTransport) is unchanged.
     computerToolMode?: ComputerToolMode;
+    onComputerUseReady?: (session: SandboxSessionLike) => Promise<void>;
   } = {},
 ): ReturnType<typeof Capabilities.default> {
-  const mode = options.compactionMode ?? resolveContextCompactionMode(settings);
-  const contextWindowTokens = options.contextWindowTokens ?? settings.contextWindowTokens;
   // The `filesystem()` capability picks hosted-vs-function tool variants from the
   // bound model instance (supportsApplyPatchTransport / structured tool output).
   // When the caller declares the backend does NOT support that structured/hosted
@@ -1339,16 +1736,19 @@ export function buildAgentCapabilities(
   // neutralize this capability's model binding so tools() falls to the function
   // `apply_patch` + text `view_image` variants the backend accepts — the SDK
   // handles their function_call round-trip natively, so no reimplementation.
-  // Scoped to filesystem: shell() (always function tools) and compaction() (a
-  // sampling param, dropped by the codex normalizer) are untouched.
-  const filesystemCapability = filesystem();
+  // Scoped to filesystem: shell() is always a function-tool transport.
+  const filesystemCapability = filesystem({
+    ...(options.structuredToolTransport === false
+      ? { configureTools: withStructuredViewImageFunctionResults }
+      : {}),
+  });
   if (options.structuredToolTransport === false) {
     neutralizeStructuredToolTransport(filesystemCapability);
   }
-  const caps: ReturnType<typeof Capabilities.default> = [filesystemCapability, shell()];
-  if (mode === "server") {
-    caps.push(compaction({ policy: new StaticCompactionPolicy(contextServerCompactThreshold({ ...settings, contextWindowTokens })) }));
-  }
+  const caps: ReturnType<typeof Capabilities.default> = [
+    filesystemCapability,
+    shell({ configureTools: withExecOpCorrelation }),
+  ];
   caps.push(skills({ lazyFrom: lazySkillSourceWithPackSkills(packSkills) }));
   // P4.3 computer-use: the agent drives the SAME :0 humans watch (xdotool/XTEST +
   // scrot), but only when the desktop tier is ON, computer-use is enabled, and the
@@ -1359,9 +1759,9 @@ export function buildAgentCapabilities(
   // run time (the SandboxAgent merge); xdotool drives :0 regardless of whether any
   // viewer is attached, so no pixel-tunnel dependency.
   if (
-    settings.computerUseEnabled
-    && settings.sandboxDesktopEnabled
-    && desktopCapableBackend(settings.sandboxBackend)
+    settings.computerUseEnabled &&
+    settings.sandboxDesktopEnabled &&
+    desktopCapableBackend(settings.sandboxBackend)
   ) {
     // computer-use is transport-aware, exactly like filesystem: `tools()` emits the
     // HOSTED `computer_use_preview` tool on the structured transport and a set of
@@ -1381,15 +1781,18 @@ export function buildAgentCapabilities(
     const computerCapability = computerUse({
       dimensions: [settings.streamResolutionWidth, settings.streamResolutionHeight],
       readOnly: settings.computerUseReadOnly,
+      ...(options.onComputerUseReady ? { onReady: options.onComputerUseReady } : {}),
       ...(explicitMode
         ? { toolMode: explicitMode }
-        // Legacy (no explicit mode): on the codex path the function tools deliver
-        // screenshots as a real image the model can see. The ChatGPT/Codex backend
-        // rejects HOSTED tool types but DOES accept `input_image` content items inside a
-        // `function_call_output` (proven by openai/codex codex-rs, whose view_image tool
-        // ships exactly that shape) — so a structured image tool result is seen, where a
-        // text data-URL would be unreadable.
-        : options.structuredToolTransport === false ? { imageFunctionResults: true } : {}),
+        : // Legacy (no explicit mode): on the codex path the function tools deliver
+          // screenshots as a real image the model can see. The ChatGPT/Codex backend
+          // rejects HOSTED tool types but DOES accept `input_image` content items inside a
+          // `function_call_output` (proven by openai/codex codex-rs, whose view_image tool
+          // ships exactly that shape) — so a structured image tool result is seen, where a
+          // text data-URL would be unreadable.
+          options.structuredToolTransport === false
+          ? { imageFunctionResults: true }
+          : {}),
     });
     // Neutralize ONLY on the legacy sniff path. With an explicit toolMode the mode
     // already forces the function tools, so the constructor-name override is moot.
@@ -1423,17 +1826,26 @@ export type PrepareToolsOptions = {
   // Worker-asserted session scope for first-party MCP calls; enables
   // session-scoped tools such as goal management on the API side.
   sessionId?: string;
+  // The calling turn's id, signed into the token so tools can classify the
+  // caller from its own identity instead of the session's live active pointer.
+  turnId?: string;
   subjectId?: string;
   subjectLabel?: string;
   // Overrides the fixed first-party MCP permission set for this session's
   // delegated token (manager-style sessions). The caller is responsible for
   // having validated the set against the session creator's grant.
   firstPartyPermissions?: Permission[];
-  resolveCredential?: (input: ResolveConnectionCredentialInput) => Promise<ResolveConnectionCredentialResult>;
+  resolveCredential?: (
+    input: ResolveConnectionCredentialInput,
+  ) => Promise<ResolveConnectionCredentialResult>;
   onAuthNeeded?: (payload: ToolAuthNeededPayload) => Promise<void> | void;
 };
 
-export async function prepareAgentTools(settings: Settings, tools: ToolRef[], options: PrepareToolsOptions = {}): Promise<PreparedAgentTools> {
+export async function prepareAgentTools(
+  settings: Settings,
+  tools: ToolRef[],
+  options: PrepareToolsOptions = {},
+): Promise<PreparedAgentTools> {
   // P4 (Part B.1): one Set per prepareTools call, shared by reference into the
   // codex_apps sanitizing fetch so every tools/list this turn accumulates the
   // account's connector namespaces. Surfaced on PreparedAgentTools for the worker.
@@ -1442,49 +1854,76 @@ export async function prepareAgentTools(settings: Settings, tools: ToolRef[], op
     return { mcpServers: [], close: async () => {}, codexConnectorNamespaces };
   }
   const registry = new Map(settings.mcpServers.map((server) => [server.id, server]));
-  const servers = await Promise.all(tools.map(async (tool) => {
-    const config = registry.get(tool.id);
-    if (!config) {
-      throw new Error(`Unknown MCP server id: ${tool.id}`);
-    }
-    const url = firstPartyMcpServerUrlForRun(settings, config, options.workspaceId) ?? config.url;
-    const baseFetch = isCodexAppsMcpServer(config)
-      ? codexAppsSanitizingFetch(globalThis.fetch, codexConnectorNamespaces)
-      : globalThis.fetch;
-    const fetchImpl = config.connectionRef
-      ? connectionBrokerFetch(baseFetch, config, options)
-      : baseFetch;
-    const server = new PrefixedMcpServer(new MCPServerStreamableHttp({
-      url,
-      name: config.name ?? config.id,
-      cacheToolsList: config.cacheToolsList,
-      // codex_apps returns connector tools with empty `outputSchema: {}` that the
-      // MCP SDK's strict Tool schema rejects (fails the turn during tools/list);
-      // sanitize the response on the wire before validation. The namespace Set
-      // also captures each tool's original connector namespace (P4 Part B.1).
-      ...(fetchImpl !== globalThis.fetch ? { fetch: fetchImpl } : {}),
-      ...await mcpServerRequestInit(settings, config, options),
-      ...(config.timeoutMs ? {
-        timeout: config.timeoutMs,
-        clientSessionTimeoutSeconds: Math.ceil(config.timeoutMs / 1000),
-      } : {}),
-    }), config.id, config.allowedTools);
-    // A server is connected BEST-EFFORT (a connect / tools-list failure drops
-    // it instead of failing the turn) in two cases:
-    //  - codex_apps: connector availability is RUNTIME-DISCOVERED — the
-    //    device-code login may lack the connector scopes, and the backend can
-    //    reject the bearer at the initialize/tools-list handshake, so a 401/403
-    //    (or a missing/failed token) drops the server.
-    //  - an optional ToolRef: either an auto-attached workspace-default
-    //    capability MCP or a client/pack-selected portable ref. A
-    //    broken/expired credential or unavailable endpoint skips the server
-    //    with a warning, never killing the turn before the model runs. Bare
-    //    refs stay strict (below), preserving the fail-loud default.
-    const optional = tool.optional === true;
-    return { server, bestEffort: isCodexAppsMcpServer(config) || optional || !!config.connectionRef, optional };
-  }));
+  const servers = await Promise.all(
+    tools.map(async (tool) => {
+      const config = registry.get(tool.id);
+      if (!config) {
+        throw new Error(`Unknown MCP server id: ${tool.id}`);
+      }
+      const url = firstPartyMcpServerUrlForRun(settings, config, options.workspaceId) ?? config.url;
+      const baseFetch = isCodexAppsMcpServer(config)
+        ? codexAppsSanitizingFetch(globalThis.fetch, codexConnectorNamespaces)
+        : globalThis.fetch;
+      const fetchImpl = config.connectionRef
+        ? connectionBrokerFetch(baseFetch, config, options)
+        : isFirstPartyMcpServer(settings, config)
+          ? firstPartyAuthFetch(baseFetch, settings, options)
+          : baseFetch;
+      // A server is connected BEST-EFFORT (a connect OR tools-list failure drops
+      // it — its tools go unavailable for the turn — instead of failing the turn)
+      // in two cases:
+      //  - codex_apps: connector availability is RUNTIME-DISCOVERED — the
+      //    device-code login may lack the connector scopes, and the backend can
+      //    reject the bearer at the initialize/tools-list handshake, so a 401/403
+      //    (or a missing/failed token) drops the server.
+      //  - an optional ToolRef: either an auto-attached workspace-default
+      //    capability MCP or a client/pack-selected portable ref. A
+      //    broken/expired credential or unavailable endpoint skips the server
+      //    with a warning, never killing the turn before the model runs. Bare
+      //    refs stay strict (below), preserving the fail-loud default.
+      // The connect-time drop is handled by connectMcpServers({ strict: false });
+      // the tools-list-time drop is enforced inside PrefixedMcpServer.listTools —
+      // a best-effort server whose tools/list throws (e.g. an expired connection
+      // credential surfacing as a StreamableHTTP "authentication required" 401)
+      // degrades to zero tools rather than throwing out of the SDK's run-time
+      // getAllMcpTools and failing an unrelated turn. The actionable
+      // tool.auth_needed signal is preserved: the connection-broker fetch
+      // publishes it before returning the 401 that provokes the throw.
+      const optional = tool.optional === true;
+      const bestEffort = isCodexAppsMcpServer(config) || optional || !!config.connectionRef;
+      const server = new PrefixedMcpServer(
+        new MCPServerStreamableHttp({
+          url,
+          name: config.name ?? config.id,
+          cacheToolsList: config.cacheToolsList,
+          // codex_apps returns connector tools with empty `outputSchema: {}` that the
+          // MCP SDK's strict Tool schema rejects (fails the turn during tools/list);
+          // sanitize the response on the wire before validation. The namespace Set
+          // also captures each tool's original connector namespace (P4 Part B.1).
+          ...(fetchImpl !== globalThis.fetch ? { fetch: fetchImpl } : {}),
+          ...(await mcpServerRequestInit(settings, config)),
+          ...(config.timeoutMs
+            ? {
+                timeout: config.timeoutMs,
+                clientSessionTimeoutSeconds: Math.ceil(config.timeoutMs / 1000),
+              }
+            : {}),
+        }),
+        config.id,
+        config.allowedTools,
+        bestEffort,
+      );
+      return {
+        server,
+        bestEffort,
+        optional,
+      };
+    }),
+  );
   const requiredServers = servers.filter((entry) => !entry.bestEffort).map((entry) => entry.server);
-  const bestEffortServers = servers.filter((entry) => entry.bestEffort).map((entry) => entry.server);
+  const bestEffortServers = servers
+    .filter((entry) => entry.bestEffort)
+    .map((entry) => entry.server);
   // Names of the OPTIONAL servers (not codex_apps) so a drop is surfaced as a
   // warning; codex_apps keeps its historically-quiet drop (a not-logged-in
   // ChatGPT plan is a normal, non-noteworthy state).
@@ -1536,36 +1975,64 @@ function connectionBrokerFetch(
   }
   return async (input, init) => {
     const request = await mcpRequestInfo(input, init);
-    const first = await resolveConnectionForRequest(options, config.id, connectionRef, request.toolName, false);
+    const first = await resolveConnectionForRequest(
+      options,
+      config.id,
+      connectionRef,
+      request.toolName,
+      false,
+    );
     if (first.status === "auth_needed") {
       return await authNeededFetchResponse(options, config.id, request, first, connectionRef);
     }
-    const response = await baseFetch(fetchInputForAttempt(input), withConnectionHeaders(input, init, first.headers));
+    const response = await baseFetch(
+      fetchInputForAttempt(input),
+      withConnectionHeaders(input, init, first.headers),
+    );
     if (response.status === 401) {
-      const refreshed = await resolveConnectionForRequest(options, config.id, connectionRef, request.toolName, true);
+      const refreshed = await resolveConnectionForRequest(
+        options,
+        config.id,
+        connectionRef,
+        request.toolName,
+        true,
+      );
       if (refreshed.status === "auth_needed") {
         return await authNeededFetchResponse(options, config.id, request, refreshed, connectionRef);
       }
-      const retry = await baseFetch(fetchInputForAttempt(input), withConnectionHeaders(input, init, refreshed.headers));
+      const retry = await baseFetch(
+        fetchInputForAttempt(input),
+        withConnectionHeaders(input, init, refreshed.headers),
+      );
       if (retry.status === 403) {
         const auth = insufficientScopeAuth(retry.headers, connectionRef, refreshed.connectionId);
-        return auth ? await authNeededFetchResponse(options, config.id, request, auth, connectionRef) : retry;
+        return auth
+          ? await authNeededFetchResponse(options, config.id, request, auth, connectionRef)
+          : retry;
       }
       if (retry.status === 401) {
-        return await authNeededFetchResponse(options, config.id, request, {
-          status: "auth_needed",
-          reason: "expired",
-          providerDomain: connectionRef.providerDomain,
-          connectionId: refreshed.connectionId,
-          ...(connectionRef.scopes ? { scopes: connectionRef.scopes } : {}),
-          ...(connectionRef.resource ? { resource: connectionRef.resource } : {}),
-        }, connectionRef);
+        return await authNeededFetchResponse(
+          options,
+          config.id,
+          request,
+          {
+            status: "auth_needed",
+            reason: "expired",
+            providerDomain: connectionRef.providerDomain,
+            connectionId: refreshed.connectionId,
+            ...(connectionRef.scopes ? { scopes: connectionRef.scopes } : {}),
+            ...(connectionRef.resource ? { resource: connectionRef.resource } : {}),
+          },
+          connectionRef,
+        );
       }
       return retry;
     }
     if (response.status === 403) {
       const auth = insufficientScopeAuth(response.headers, connectionRef, first.connectionId);
-      return auth ? await authNeededFetchResponse(options, config.id, request, auth, connectionRef) : response;
+      return auth
+        ? await authNeededFetchResponse(options, config.id, request, auth, connectionRef)
+        : response;
     }
     return response;
   };
@@ -1624,8 +2091,16 @@ function insufficientScopeAuth(
     reason: "insufficient_scope",
     providerDomain: connectionRef.providerDomain,
     connectionId,
-    ...(challenge.scope?.length ? { scopes: challenge.scope } : connectionRef.scopes ? { scopes: connectionRef.scopes } : {}),
-    ...(challenge.resource ? { resource: challenge.resource } : connectionRef.resource ? { resource: connectionRef.resource } : {}),
+    ...(challenge.scope?.length
+      ? { scopes: challenge.scope }
+      : connectionRef.scopes
+        ? { scopes: connectionRef.scopes }
+        : {}),
+    ...(challenge.resource
+      ? { resource: challenge.resource }
+      : connectionRef.resource
+        ? { resource: connectionRef.resource }
+        : {}),
   };
 }
 
@@ -1643,8 +2118,16 @@ async function authNeededFetchResponse(
     providerDomain: auth.providerDomain,
     reason: auth.reason,
     ...(connectionId ? { connectionId } : {}),
-    ...(auth.scopes ? { scopes: auth.scopes } : connectionRef.scopes ? { scopes: connectionRef.scopes } : {}),
-    ...(auth.resource ? { resource: auth.resource } : connectionRef.resource ? { resource: connectionRef.resource } : {}),
+    ...(auth.scopes
+      ? { scopes: auth.scopes }
+      : connectionRef.scopes
+        ? { scopes: connectionRef.scopes }
+        : {}),
+    ...(auth.resource
+      ? { resource: auth.resource }
+      : connectionRef.resource
+        ? { resource: connectionRef.resource }
+        : {}),
     ...(auth.authorizationUrl ? { authorizationUrl: auth.authorizationUrl } : {}),
     ...(options.subjectId ? { subjectId: options.subjectId } : {}),
   });
@@ -1654,7 +2137,10 @@ async function authNeededFetchResponse(
   return new Response("Authentication required for MCP server connection", { status: 401 });
 }
 
-async function publishAuthNeeded(options: PrepareToolsOptions, payload: ToolAuthNeededPayload): Promise<void> {
+async function publishAuthNeeded(
+  options: PrepareToolsOptions,
+  payload: ToolAuthNeededPayload,
+): Promise<void> {
   try {
     await options.onAuthNeeded?.(payload);
   } catch {
@@ -1669,20 +2155,37 @@ type McpRequestInfo = {
   toolName?: string;
 };
 
-async function mcpRequestInfo(input: string | URL | Request, init?: RequestInit): Promise<McpRequestInfo> {
-  const body = typeof init?.body === "string"
-    ? init.body
-    : input instanceof Request && (init?.method ?? input.method).toUpperCase() === "POST"
-      ? await input.clone().text().catch(() => "")
-      : "";
+async function mcpRequestInfo(
+  input: string | URL | Request,
+  init?: RequestInit,
+): Promise<McpRequestInfo> {
+  const body =
+    typeof init?.body === "string"
+      ? init.body
+      : input instanceof Request && (init?.method ?? input.method).toUpperCase() === "POST"
+        ? await input
+            .clone()
+            .text()
+            .catch(() => "")
+        : "";
   if (!body) {
     return {};
   }
   try {
-    const parsed = JSON.parse(body) as { id?: unknown; method?: unknown; params?: { name?: unknown } };
+    const parsed = JSON.parse(body) as {
+      id?: unknown;
+      method?: unknown;
+      params?: { name?: unknown };
+    };
     const method = typeof parsed.method === "string" ? parsed.method : undefined;
-    const id = typeof parsed.id === "string" || typeof parsed.id === "number" || parsed.id === null ? parsed.id : undefined;
-    const toolName = method === "tools/call" && typeof parsed.params?.name === "string" ? parsed.params.name : undefined;
+    const id =
+      typeof parsed.id === "string" || typeof parsed.id === "number" || parsed.id === null
+        ? parsed.id
+        : undefined;
+    const toolName =
+      method === "tools/call" && typeof parsed.params?.name === "string"
+        ? parsed.params.name
+        : undefined;
     return {
       ...(method ? { method } : {}),
       ...(id !== undefined ? { id } : {}),
@@ -1693,8 +2196,14 @@ async function mcpRequestInfo(input: string | URL | Request, init?: RequestInit)
   }
 }
 
-function withConnectionHeaders(input: string | URL | Request, init: RequestInit | undefined, authHeaders: Record<string, string>): RequestInit {
-  const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+function withConnectionHeaders(
+  input: string | URL | Request,
+  init: RequestInit | undefined,
+  authHeaders: Record<string, string>,
+): RequestInit {
+  const headers = new Headers(
+    init?.headers ?? (input instanceof Request ? input.headers : undefined),
+  );
   for (const [name, value] of Object.entries(authHeaders)) {
     headers.set(name, value);
   }
@@ -1705,7 +2214,11 @@ function fetchInputForAttempt(input: string | URL | Request): string | URL | Req
   return input instanceof Request ? input.clone() : input;
 }
 
-function parseWwwAuthenticate(header: string | null): { error?: string; scope?: string[]; resource?: string } {
+function parseWwwAuthenticate(header: string | null): {
+  error?: string;
+  scope?: string[];
+  resource?: string;
+} {
   if (!header) {
     return {};
   }
@@ -1719,7 +2232,9 @@ function parseWwwAuthenticate(header: string | null): { error?: string; scope?:
   let match: RegExpExecArray | null;
   while ((match = re.exec(paramsText)) !== null) {
     const raw = match[2]!;
-    params[match[1]!.toLowerCase()] = raw.startsWith("\"") ? raw.slice(1, -1).replace(/\\"/g, "\"") : raw;
+    params[match[1]!.toLowerCase()] = raw.startsWith('"')
+      ? raw.slice(1, -1).replace(/\\"/g, '"')
+      : raw;
   }
   return {
     ...(params.error ? { error: params.error } : {}),
@@ -1735,20 +2250,24 @@ function parseWwwAuthenticate(header: string | null): { error?: string; scope?:
 // McpError, which PrefixedMcpServer.callTool converts back into an MCP-shaped
 // `{ isError: true }` output for the model.
 const MCP_AUTH_NEEDED_ERROR_CODE = -32001;
-const MCP_AUTH_NEEDED_MESSAGE = "Authentication required - a connection link was posted to the session.";
+const MCP_AUTH_NEEDED_MESSAGE =
+  "Authentication required - a connection link was posted to the session.";
 
 function mcpToolAuthNeededResponse(id: string | number | null | undefined): Response {
-  return new Response(JSON.stringify({
-    jsonrpc: "2.0",
-    id: id ?? null,
-    error: {
-      code: MCP_AUTH_NEEDED_ERROR_CODE,
-      message: MCP_AUTH_NEEDED_MESSAGE,
+  return new Response(
+    JSON.stringify({
+      jsonrpc: "2.0",
+      id: id ?? null,
+      error: {
+        code: MCP_AUTH_NEEDED_ERROR_CODE,
+        message: MCP_AUTH_NEEDED_MESSAGE,
+      },
+    }),
+    {
+      status: 200,
+      headers: { "content-type": "application/json" },
     },
-  }), {
-    status: 200,
-    headers: { "content-type": "application/json" },
-  });
+  );
 }
 
 function isAuthNeededMcpError(error: unknown): boolean {
@@ -1759,7 +2278,44 @@ function isAuthNeededMcpError(error: unknown): boolean {
   return code === MCP_AUTH_NEEDED_ERROR_CODE || error.message.includes(MCP_AUTH_NEEDED_MESSAGE);
 }
 
-async function mcpServerRequestInit(settings: Settings, config: Settings["mcpServers"][number], options: PrepareToolsOptions): Promise<{ requestInit: { headers: Record<string, string> } } | {}> {
+// Model-facing text for a best-effort server whose tool call failed for a
+// non-auth reason (transport 401/403 that never became the broker's JSON-RPC
+// short-circuit, a provider 5xx, a network blip). The copy is LOOP-SAFE: it
+// tells the model the tool is dead for the REST OF THIS TURN and to NOT retry
+// it, so a model that would otherwise burn the turn re-calling the same broken
+// optional tool moves on instead. Only the safe error surface (JS error class +
+// numeric HTTP status) is interpolated — NEVER the raw error message/response
+// body, which for a broker 401/403 can echo request URLs/headers/credentials.
+function mcpToolUnavailableMessage(reason: string): string {
+  return `This tool is unavailable for the rest of this turn (${reason}). Do not retry it — continue without it or use another approach.`;
+}
+
+// The only error detail safe to surface to the model or the logs: the JS error
+// constructor name and, when present, a numeric HTTP status. A StreamableHTTP
+// transport error carries the raw response BODY in its `.message` (a broker
+// 401/403 body can echo request detail), so `.message` is never included; the
+// numeric `.code`/`.status` (e.g. 401) is safe and useful.
+function safeMcpErrorFields(error: unknown): { errorClass: string; status?: number } {
+  const errorClass = error instanceof Error ? error.constructor.name : typeof error;
+  const raw = (error as { code?: unknown; status?: unknown } | null)?.code;
+  const status = typeof raw === "number" ? raw : undefined;
+  if (status === undefined) {
+    const altRaw = (error as { status?: unknown } | null)?.status;
+    return typeof altRaw === "number" ? { errorClass, status: altRaw } : { errorClass };
+  }
+  return { errorClass, status };
+}
+
+// Compose the safe model/log reason string ("StreamableHTTPError 401", or just
+// the class when no numeric status is available). Never carries the raw body.
+function mcpErrorReason(fields: { errorClass: string; status?: number }): string {
+  return fields.status === undefined ? fields.errorClass : `${fields.errorClass} ${fields.status}`;
+}
+
+async function mcpServerRequestInit(
+  settings: Settings,
+  config: Settings["mcpServers"][number],
+): Promise<{ requestInit: { headers: Record<string, string> } } | {}> {
   // codex_apps is checked FIRST so the static-headers path can never apply to
   // it: its refreshing ChatGPT/Codex bearer is resolved per-connect from the
   // codex ALS, never from a baked `config.headers` value.
@@ -1767,7 +2323,7 @@ async function mcpServerRequestInit(settings: Settings, config: Settings["mcpSer
     return await codexAppsMcpRequestInit(settings);
   }
   if (isFirstPartyMcpServer(settings, config)) {
-    return await firstPartyMcpRequestInit(settings, config, options);
+    return await firstPartyMcpRequestInit(settings, config);
   }
   // Third-party MCP servers get their configured credential headers (for
   // example workspace-enabled capability MCP credentials) and nothing else —
@@ -1778,7 +2334,10 @@ async function mcpServerRequestInit(settings: Settings, config: Settings["mcpSer
   return {};
 }
 
-async function firstPartyMcpRequestInit(settings: Settings, config: Settings["mcpServers"][number], options: PrepareToolsOptions): Promise<{ requestInit: { headers: Record<string, string> } } | {}> {
+async function firstPartyMcpRequestInit(
+  settings: Settings,
+  config: Settings["mcpServers"][number],
+): Promise<{ requestInit: { headers: Record<string, string> } } | {}> {
   if (!isFirstPartyMcpServer(settings, config)) {
     return {};
   }
@@ -1786,17 +2345,14 @@ async function firstPartyMcpRequestInit(settings: Settings, config: Settings["mc
   if (settings.authRequired && settings.accessKey) {
     headers["x-opengeni-access-key"] = settings.accessKey;
   }
-  if (settings.delegationSecret && options.accountId && options.workspaceId) {
-    headers.authorization = `Bearer ${await signDelegatedAccessToken(settings.delegationSecret, {
-      accountId: options.accountId,
-      workspaceId: options.workspaceId,
-      subjectId: options.subjectId ?? "worker:first-party-mcp",
-      ...(options.subjectLabel ? { subjectLabel: options.subjectLabel } : {}),
-      permissions: options.firstPartyPermissions ?? firstPartyMcpPermissions,
-      ...(options.sessionId ? { sessionId: options.sessionId } : {}),
-      exp: Math.floor(Date.now() / 1000) + 60 * 60,
-    })}`;
-  }
+  // The delegated bearer is deliberately NOT baked here. It is re-signed PER
+  // REQUEST by firstPartyAuthFetch (wired in prepareAgentTools) so a turn or
+  // persistent MCP connection that outlives the token's 1h TTL never sends a
+  // stale bearer — an expired first-party bearer 401s ("authentication
+  // required"), and because the first-party server is REQUIRED that killed the
+  // turn on any run past ~1h. This function keeps only NON-expiring static
+  // headers (the access key); the per-request fetch wrapper is the single source
+  // of truth for the ever-refreshed Authorization header.
   if (Object.keys(headers).length === 0) {
     return {};
   }
@@ -1807,6 +2363,55 @@ async function firstPartyMcpRequestInit(settings: Settings, config: Settings["mc
   };
 }
 
+// Sign a FRESH first-party delegated bearer for a single request. Returns null
+// when the run lacks the inputs to mint one (no delegation secret / account /
+// workspace), in which case the request proceeds with whatever static headers
+// requestInit already set. The 1h TTL is safe precisely because this runs per
+// request: the token on the wire is always seconds old, never near expiry.
+async function signFirstPartyDelegatedBearer(
+  settings: Settings,
+  options: PrepareToolsOptions,
+): Promise<string | null> {
+  if (!settings.delegationSecret || !options.accountId || !options.workspaceId) {
+    return null;
+  }
+  return await signDelegatedAccessToken(settings.delegationSecret, {
+    accountId: options.accountId,
+    workspaceId: options.workspaceId,
+    subjectId: options.subjectId ?? "worker:first-party-mcp",
+    ...(options.subjectLabel ? { subjectLabel: options.subjectLabel } : {}),
+    permissions: options.firstPartyPermissions ?? firstPartyMcpPermissions,
+    ...(options.sessionId ? { sessionId: options.sessionId } : {}),
+    ...(options.turnId ? { turnId: options.turnId } : {}),
+    exp: Math.floor(Date.now() / 1000) + 60 * 60,
+  });
+}
+
+// Per-request auth for the FIRST-PARTY MCP server: re-sign the delegated bearer
+// on EVERY request (connect/initialize, every tools/list re-list, every
+// tools/call) and set it as the Authorization header, so a turn or connection
+// outliving the 1h token TTL never sends an expired bearer. This is the fix for
+// the prod grind where a >1h turn's next re-list/tool-call 401'd on the stale
+// first-party bearer and — the first-party server being required — failed the
+// whole turn. Scoped STRICTLY to the token WE mint; external OAuth (connectionRef
+// servers) go through connectionBrokerFetch and are untouched.
+function firstPartyAuthFetch(
+  baseFetch: FetchLike,
+  settings: Settings,
+  options: PrepareToolsOptions,
+): FetchLike {
+  return async (input, init) => {
+    const bearer = await signFirstPartyDelegatedBearer(settings, options);
+    if (!bearer) {
+      return await baseFetch(input, init);
+    }
+    return await baseFetch(
+      fetchInputForAttempt(input),
+      withConnectionHeaders(input, init, { authorization: `Bearer ${bearer}` }),
+    );
+  };
+}
+
 /**
  * Builds the connect-time auth headers for the codex_apps connectors MCP. The
  * bearer is resolved from codexRequestStorage — the SAME refreshing token source
@@ -1815,7 +2420,9 @@ async function firstPartyMcpRequestInit(settings: Settings, config: Settings["mc
  * ran outside the ALS) or a token failure (needs_relogin) returns {} so the
  * best-effort connect drops the server rather than crashing the turn.
  */
-async function codexAppsMcpRequestInit(settings: Settings): Promise<{ requestInit: { headers: Record<string, string> } } | {}> {
+async function codexAppsMcpRequestInit(
+  settings: Settings,
+): Promise<{ requestInit: { headers: Record<string, string> } } | {}> {
   const ctx = codexRequestStorage.getStore();
   if (!ctx) {
     return {};
@@ -1848,8 +2455,8 @@ async function codexAppsMcpRequestInit(settings: Settings): Promise<{ requestIni
 // The first-party MCP permission set signed into a worker's delegated token
 // when the session does not specify its own. POWERFUL BY DEFAULT: it carries
 // every permission that unlocks a first-party tool — session orchestration
-// (sessions:*), workspace environments (environments:*), and GitHub
-// (github:use) — so agents are fully capable out of the box. A user DEMOTES a
+// (sessions:*), workspace variable sets (variable-sets:*), rigs:use
+// (list/get/propose/verify only), and GitHub (github:use) — so agents are fully capable out of the box. A user DEMOTES a
 // specific session by setting a narrower session.firstPartyMcpPermissions (the
 // create-session permission picker), which the worker uses instead. Account-
 // level scopes (billing/account/members/api_keys/workspace:admin) are
@@ -1865,8 +2472,9 @@ const firstPartyMcpPermissions: Permission[] = [
   "sessions:read",
   "sessions:create",
   "sessions:control",
-  "environments:use",
-  "environments:manage",
+  "variable-sets:use",
+  "variable-sets:manage",
+  "rigs:use",
   "github:use",
 ];
 
@@ -1878,7 +2486,10 @@ function isCodexAppsMcpServer(config: Settings["mcpServers"][number]): boolean {
   return config.id === CODEX_APPS_MCP_SERVER_ID;
 }
 
-function isFirstPartyMcpServer(settings: Settings, config: Settings["mcpServers"][number]): boolean {
+function isFirstPartyMcpServer(
+  settings: Settings,
+  config: Settings["mcpServers"][number],
+): boolean {
   if (!["opengeni", "files", "docs"].includes(config.id)) {
     return false;
   }
@@ -1892,7 +2503,11 @@ function isFirstPartyMcpServer(settings: Settings, config: Settings["mcpServers"
   return firstPartyMcpUrls(settings).some((candidate) => candidate === url);
 }
 
-function firstPartyMcpServerUrlForRun(settings: Settings, config: Settings["mcpServers"][number], workspaceId: string | undefined): string | null {
+function firstPartyMcpServerUrlForRun(
+  settings: Settings,
+  config: Settings["mcpServers"][number],
+  workspaceId: string | undefined,
+): string | null {
   if (!workspaceId || !["opengeni", "files", "docs"].includes(config.id)) {
     return null;
   }
@@ -1906,9 +2521,9 @@ function firstPartyMcpServerUrlForRun(settings: Settings, config: Settings["mcpS
     ? settings.opengeniMcpUrl.replaceAll("{workspaceId}", workspaceId)
     : settings.opengeniMcpUrl
       ? scopedMcpUrlFromConfiguredBase(settings.opengeniMcpUrl, workspaceId)
-      // unset → the shared loopback default (a `{workspaceId}` template owned by
-      // @opengeni/config's firstPartyMcpBaseUrl), scoped to this run's workspace.
-      : firstPartyMcpBaseUrl(settings).replaceAll("{workspaceId}", workspaceId);
+      : // unset → the shared loopback default (a `{workspaceId}` template owned by
+        // @opengeni/config's firstPartyMcpBaseUrl), scoped to this run's workspace.
+        firstPartyMcpBaseUrl(settings).replaceAll("{workspaceId}", workspaceId);
   const url = new URL(rawBase);
   if (config.id === "docs") {
     url.pathname = `${url.pathname.replace(/\/+$/, "")}/docs`;
@@ -1956,12 +2571,24 @@ class PrefixedMcpServer implements MCPServer {
   readonly name: string;
   readonly prefix: string;
   private readonly allowedTools: Set<string> | undefined;
-
-  constructor(private readonly inner: MCPServer, registryId: string, allowedTools?: string[]) {
+  // Best-effort servers (optional refs, connectionRef-backed capability MCPs,
+  // codex_apps) must never fail a turn: a tools/list throw degrades to zero
+  // tools instead of propagating. Deduplicate the warn so one degraded server
+  // doesn't spam the log when the SDK re-lists across model turns.
+  private readonly bestEffort: boolean;
+  private loggedListToolsFailure = false;
+
+  constructor(
+    private readonly inner: MCPServer,
+    registryId: string,
+    allowedTools?: string[],
+    bestEffort = false,
+  ) {
     this.name = registryId;
     this.prefix = prefixedMcpToolName(registryId, "");
     this.cacheToolsList = inner.cacheToolsList;
     this.allowedTools = allowedTools ? new Set(allowedTools) : undefined;
+    this.bestEffort = bestEffort;
   }
 
   connect(): Promise<void> {
@@ -1973,13 +2600,49 @@ class PrefixedMcpServer implements MCPServer {
   }
 
   async listTools(): Promise<RuntimeMcpTool[]> {
-    const tools = await this.inner.listTools();
+    let tools: RuntimeMcpTool[];
+    try {
+      tools = await this.inner.listTools();
+    } catch (error) {
+      // A REQUIRED server's tools/list failure is fatal (fail-loud default): the
+      // caller explicitly requested it, so its absence must fail the turn.
+      if (!this.bestEffort) {
+        throw error;
+      }
+      // Best-effort isolation. The SDK's run-time getAllMcpTools calls listTools
+      // OUTSIDE the connect-time connectMcpServers({ strict: false }) guard, so a
+      // best-effort server whose tools/list throws here — for ANY reason (an
+      // expired/failed connection credential surfacing as a StreamableHTTP
+      // "authentication required" 401, a provider 5xx, a network blip) — would
+      // otherwise take down an unrelated turn. Drop this server's tools for the
+      // turn instead. An auth failure additionally published tool.auth_needed via
+      // the connection-broker fetch before the throw (so that actionable signal
+      // is preserved), but a non-auth failure has NO such signal — the structured
+      // warn below is its only visibility, so a chronically-dead optional
+      // integration surfaces in logs/metrics rather than being silently swallowed.
+      // Warn once per degraded server per turn (instances are per-turn), so a
+      // re-list across model turns does not spam the log.
+      if (!this.loggedListToolsFailure) {
+        this.loggedListToolsFailure = true;
+        console.warn(
+          "[mcp] best-effort server tools/list failed; its tools are unavailable this turn",
+          // Safe surface only (class + numeric status), never the raw error
+          // message/response body — a broker 401/403 body can echo request detail.
+          { serverId: this.name, ...safeMcpErrorFields(error) },
+        );
+      }
+      return [];
+    }
     return tools
       .filter((tool) => this.isAllowed(tool.name))
       .map((tool) => ({ ...tool, name: prefixedMcpToolName(this.name, tool.name) }));
   }
 
-  async callTool(toolName: string, args: Record<string, unknown> | null, meta?: Record<string, unknown> | null): Promise<any> {
+  async callTool(
+    toolName: string,
+    args: Record<string, unknown> | null,
+    meta?: Record<string, unknown> | null,
+  ): Promise<any> {
     const unprefixed = this.unprefixToolName(toolName);
     if (!this.isAllowed(unprefixed)) {
       throw new Error(`MCP tool ${unprefixed} is not allowed for server ${this.name}`);
@@ -1991,9 +2654,34 @@ class PrefixedMcpServer implements MCPServer {
       // JSON-RPC error (an inline isError result would be stripped by the SDK
       // shim). Surface it to the model as a failed-but-recoverable tool result
       // instead of failing the turn; the timeline chip was already published.
+      // This applies to ANY server — an auth-needed is recoverable once the user
+      // re-links, so even a required tool degrades gracefully here.
       if (isAuthNeededMcpError(error)) {
         return { isError: true, content: [{ type: "text", text: MCP_AUTH_NEEDED_MESSAGE }] };
       }
+      // Best-effort INVOCATION isolation (sibling to the listTools guard). When
+      // the model calls a best-effort server's tool and the call throws for ANY
+      // other reason — a raw transport 401/403 that never became the broker's
+      // JSON-RPC short-circuit (e.g. a codex_apps bearer that expired mid-turn,
+      // or a 403 with no insufficient_scope challenge), a provider 5xx, or a
+      // network blip — the whole turn would otherwise die. Return a tool-error
+      // RESULT the model sees instead, so it adapts (tries another approach,
+      // tells the user) and the turn survives. Required servers keep the
+      // fail-loud default: the caller depends on them, so their tool failure
+      // still fails the turn. For auth cases the actionable tool.auth_needed was
+      // already published upstream by the connection-broker fetch before the
+      // throw, so degrading here never silences it.
+      if (this.bestEffort) {
+        const fields = safeMcpErrorFields(error);
+        console.warn(
+          "[mcp] best-effort server tool call failed; returning an unavailable result for this turn",
+          { serverId: this.name, toolName: unprefixed, ...fields },
+        );
+        return {
+          isError: true,
+          content: [{ type: "text", text: mcpToolUnavailableMessage(mcpErrorReason(fields)) }],
+        };
+      }
       throw error;
     }
   }
@@ -2003,7 +2691,9 @@ class PrefixedMcpServer implements MCPServer {
   }
 
   async listResources(params?: Record<string, unknown>): Promise<any> {
-    const resourcesServer = this.inner as MCPServer & { listResources?: (params?: Record<string, unknown>) => Promise<any> };
+    const resourcesServer = this.inner as MCPServer & {
+      listResources?: (params?: Record<string, unknown>) => Promise<any>;
+    };
     if (!resourcesServer.listResources) {
       throw new Error(`MCP server ${this.name} does not support resources`);
     }
@@ -2011,7 +2701,9 @@ class PrefixedMcpServer implements MCPServer {
   }
 
   async listResourceTemplates(params?: Record<string, unknown>): Promise<any> {
-    const resourcesServer = this.inner as MCPServer & { listResourceTemplates?: (params?: Record<string, unknown>) => Promise<any> };
+    const resourcesServer = this.inner as MCPServer & {
+      listResourceTemplates?: (params?: Record<string, unknown>) => Promise<any>;
+    };
     if (!resourcesServer.listResourceTemplates) {
       throw new Error(`MCP server ${this.name} does not support resource templates`);
     }
@@ -2019,7 +2711,9 @@ class PrefixedMcpServer implements MCPServer {
   }
 
   async readResource(uri: string): Promise<any> {
-    const resourcesServer = this.inner as MCPServer & { readResource?: (uri: string) => Promise<any> };
+    const resourcesServer = this.inner as MCPServer & {
+      readResource?: (uri: string) => Promise<any>;
+    };
     if (!resourcesServer.readResource) {
       throw new Error(`MCP server ${this.name} does not support resource reads`);
     }
@@ -2043,112 +2737,58 @@ class PrefixedMcpServer implements MCPServer {
 
 export type PrepareInputOptions = {
   sandboxClient?: unknown;
-  /**
-   * Usable input-token budget B (window - reserved output). When set, the
-   * assembled history is passed through `enforceInputBudget` so a single
-   * over-budget input can never be sent — the last-resort backstop behind the
-   * best-effort pre-turn compaction. Omitted (undefined) disables the guard
-   * (no behaviour change for callers that don't opt in).
-   */
-  inputBudgetTokens?: number;
 };
 
-/**
- * Apply the read-path budget guard to an assembled model input: drop the oldest
- * history at a clean turn boundary until the request fits B. Orphan-safe (only
- * cuts at user-message boundaries) and only active when a budget is supplied.
- * The trailing user message is counted against the budget but never dropped.
- */
-function guardAssembledInput(
-  history: AgentInputItem[],
-  trailing: AgentInputItem,
-  inputBudgetTokens: number | undefined,
-): AgentInputItem[] {
-  if (typeof inputBudgetTokens !== "number" || inputBudgetTokens <= 0) {
-    return [...history, trailing];
-  }
-  const trailingTokens = estimateItemTokens(trailing as unknown as Record<string, unknown>);
-  const guarded = enforceInputBudget(
-    history as unknown as Array<Record<string, unknown>>,
-    inputBudgetTokens,
-    trailingTokens,
-  );
-  if (guarded.trimmed) {
-    console.warn(
-      `read-path budget guard trimmed ${guarded.droppedCount} oldest history item(s) to fit input budget (${inputBudgetTokens} tokens); the over-budget input was NOT sent`,
-    );
-  }
-  return [...(guarded.items as unknown as AgentInputItem[]), trailing];
-}
-
-export async function prepareRunInput(agent: Agent<any, any>, input: AgentSegmentInput, options: PrepareInputOptions = {}): Promise<PreparedAgentInput> {
+export async function prepareRunInput(
+  agent: Agent<any, any>,
+  input: AgentSegmentInput,
+  options: PrepareInputOptions = {},
+): Promise<PreparedAgentInput> {
   if (input.kind === "message") {
-    if (input.historyItems && input.historyItems.length > 0) {
-      // Items mode: conversation truth comes from the database, the sandbox
-      // recovery descriptor from its own store. The RunState blob is not
-      // touched at all on this path.
-      const sandboxSessionState = input.sandboxEnvelope
-        ? await restoredSandboxSessionStateFromEntry(input.sandboxEnvelope, options.sandboxClient)
-        : undefined;
-      // Replayed conversation truth is reloaded verbatim from the database, so
-      // it can contain a tool-call pairing the Responses API rejects (most
-      // destructively an orphaned function_call_result with no matching
-      // function_call — which 400s every turn and bricks the session until the
-      // row is hand-deleted). Sanitize the in-memory copy before it reaches the
-      // model so existing corruption self-heals and a future write-path race is
-      // non-fatal; the stored rows are never touched.
-      const sanitizedHistory = sanitizeHistoryItemsForModel(
-        input.historyItems as unknown as Array<Record<string, unknown>>,
-      ) as unknown as AgentInputItem[];
-      return {
-        // Read-path budget guard: even after the orphan sanitizer, an assembled
-        // input can exceed the model window (pre-turn compaction is best-effort
-        // and can no-op). Trim the oldest history at a clean turn boundary so an
-        // over-budget request is never sent. No-op when no budget is supplied.
-        input: guardAssembledInput(
-          sanitizedHistory,
-          {
-            type: "message",
-            role: "user",
-            content: input.text,
-          } as AgentInputItem,
-          options.inputBudgetTokens,
-        ),
-        ...(sandboxSessionState ? { sandboxSessionState } : {}),
-      };
+    const trailingMessages: AgentInputItem[] = [];
+    if (input.internalContext?.trim()) {
+      trailingMessages.push({
+        type: "message",
+        role: "system",
+        content: input.internalContext,
+      } as AgentInputItem);
+    }
+    if (input.text?.trim()) {
+      trailingMessages.push({
+        type: "message",
+        role: "user",
+        content: input.text,
+      } as AgentInputItem);
     }
-    // No prior state, or a cleared sentinel: start fresh. The clear sentinel
-    // ({@link CLEARED_RUN_STATE_BLOB}) is not a real serialized run state — it
-    // carries no $schemaVersion, so RunState.fromString would throw on it. In
-    // run_state history mode this message path is the one that reads the blob
-    // after a /clear, so recognizing the sentinel here is what keeps the next
-    // turn working (a fresh, empty context) instead of bricking on deserialize.
-    if (!input.serializedRunState || isClearedRunStateBlob(input.serializedRunState)) {
-      return { input: input.text };
+    if (
+      trailingMessages.length === 0 &&
+      (input.historyItems === undefined ||
+        input.historyItems === null ||
+        input.historyItems.length === 0)
+    ) {
+      throw new Error("Message input requires a user prompt or internal context");
     }
-    const state = await RunState.fromString(agent, input.serializedRunState);
-    const sandboxSessionState = await restoredSandboxSessionState(state, options.sandboxClient);
-    // state.history already runs the SDK's own orphan-tool-call pruning, but
-    // applying the same sanitizer keeps the legacy run-state resume path under
-    // one invariant with the items path and is defensive against a corrupt blob.
+    // Conversation truth comes only from durable history items. Sanitize the
+    // in-memory copy before it reaches the model so a corrupt tool-call pair is
+    // non-fatal; stored audit rows remain untouched.
     const sanitizedHistory = sanitizeHistoryItemsForModel(
-      state.history as unknown as Array<Record<string, unknown>>,
+      (input.historyItems ?? []) as unknown as Array<Record<string, unknown>>,
     ) as unknown as AgentInputItem[];
+    const sandboxSessionState = input.sandboxEnvelope
+      ? await restoredSandboxSessionStateFromEntry(input.sandboxEnvelope, options.sandboxClient)
+      : undefined;
+    const assembled = [...sanitizedHistory, ...trailingMessages];
+    if (assembled.length === 0) {
+      throw new Error("Message input requires durable history or internal context");
+    }
     return {
-      // Read-path budget guard (see the items path above): keep an over-budget
-      // resumed history off the wire by trimming the oldest turns when a budget
-      // is supplied.
-      input: guardAssembledInput(
-        sanitizedHistory,
-        {
-          type: "message",
-          role: "user",
-          content: input.text,
-        } as AgentInputItem,
-        options.inputBudgetTokens,
-      ),
+      // Preserve the SDK's simple first-message form without creating a second
+      // history path: this is merely the zero-history representation.
+      input:
+        sanitizedHistory.length === 0 && !input.internalContext?.trim() && input.text?.trim()
+          ? input.text
+          : assembled,
       ...(sandboxSessionState ? { sandboxSessionState } : {}),
-      serializedRunStateForSandbox: input.serializedRunState,
     };
   }
   // An approval can only be resumed against a real saved run state. If the
@@ -2156,7 +2796,9 @@ export async function prepareRunInput(agent: Agent<any, any>, input: AgentSegmen
   // refuses clear in requires_action, so this is a defensive guard) — fail with
   // an honest message instead of the cryptic SDK "missing schema version".
   if (isClearedRunStateBlob(input.serializedRunState)) {
-    throw new Error("Cannot resume an approval: the session context was cleared, so the awaiting run state no longer exists.");
+    throw new Error(
+      "Cannot resume an approval: the session context was cleared, so the awaiting run state no longer exists.",
+    );
   }
   const state = await RunState.fromString(agent, input.serializedRunState);
   const interruptions = state.getInterruptions();
@@ -2177,6 +2819,12 @@ export type RunAgentStreamOptions = {
   sandboxEnvironment?: Record<string, string>;
   onRuntimeEvent?: (event: NormalizedRuntimeEvent) => Promise<void> | void;
   contextCompactionSignalTokens?: () => number | null | undefined;
+  contextCompactionRequested?: () => boolean | Promise<boolean>;
+  // Host-managed git credential renewal registration. Called only after the
+  // initial token-file seed completed on a real provisioned box. The worker
+  // owns the multi-day timer and uses this pinned, un-proxied session to
+  // atomically replace token files; runtime never mints credentials itself.
+  onGitCredentialSessionReady?: (session: GitCredentialTokenWriterSession) => Promise<void> | void;
   // OWNERSHIP INVERSION (P1.2): an externally-owned, already-live sandbox
   // session resolved by the per-turn resume-by-id path. When present,
   // runAgentStream does NOT build (or resume, or discard) a client — it threads
@@ -2189,15 +2837,23 @@ export type RunAgentStreamOptions = {
   // re-applied around the resumed client here; the live `session`/`sessionState`
   // carry the box, so no create()/resume() is re-invoked inside run().
   ownedSandbox?: {
-    client: unknown;          // built by the per-turn resume path (the raw provider client)
-    session: unknown;         // SandboxSessionLike — the live, NON-OWNED handle (never reaped)
-    sessionState?: unknown;   // SandboxSessionState the box was resumed from
+    client: unknown; // built by the per-turn resume path (the raw provider client)
+    session: unknown; // SandboxSessionLike — the live, NON-OWNED handle (never reaped)
+    sessionState?: unknown; // SandboxSessionState the box was resumed from
     // The UN-PROXIED established box for platform setup (lifecycle hooks + file
     // resource materialization). `session` may be the mid-turn routing proxy whose
     // every exec re-reads the active pointer — platform-initiated setup must NOT
     // follow a swap onto a connected machine (the user's real computer), so it
     // runs against this pinned handle instead. Absent -> falls back to `session`.
     setupSession?: unknown;
+    // True when the caller already ran file-resource materialization for this
+    // provided session and threaded any failures into the model input.
+    fileDownloadsMaterialized?: boolean;
+    // Lazy sandbox provisioning injects a synthetic provided session at run start;
+    // the real box does not exist until the first sandbox op. In that path the
+    // worker provisioner runs runOwnedSandboxSetup against the un-proxied real box
+    // after establish, so runAgentStream must not run it eagerly here.
+    deferredSetup?: boolean;
   };
   // A per-turn model-input filter chained AFTER the provider-item-id strip.
   // Used by the genesis-title injection to prepend a hidden, NON-PERSISTED
@@ -2209,17 +2865,48 @@ export type RunAgentStreamOptions = {
 
 export type ContextRobustnessFilterOptions = {
   contextCompactionSignalTokens?: () => number | null | undefined;
+  contextCompactionRequested?: () => boolean | Promise<boolean>;
   throwOnCompactionNeeded?: boolean;
 };
 
-// One-shot directive appended to the agent's system prompt on the genesis turn
+// One-shot directive injected into the FIRST model call on the genesis turn
 // (see buildOpenGeniAgent's genesisTitleHint). Delivered through the
 // authoritative instructions channel so the model reliably obeys; references
 // the prefixed tool name the agent actually sees (opengeni__set_session_title).
-// Appended after the non-bypassable core so a white-label persona can't drop it.
 export const GENESIS_TITLE_DIRECTIVE =
   "This is the first turn of a new session. Before responding to the user, call the opengeni__set_session_title tool with a concise 3-7 word title that summarizes what this session is about, then address the user's request normally.";
 
+/**
+ * Inject the genesis-title directive into exactly one model request. Agent
+ * instructions are reused for every model call in a tool loop, so placing this
+ * directive there turned a nominally one-shot setup action into repeated title
+ * calls. The closure is intentionally consumed even when the first request
+ * fails: a retry/recovery must continue the task, not restart setup.
+ */
+export function oneShotGenesisTitleInputFilter(): CallModelInputFilter {
+  let pending = true;
+  return ({ modelData }) => {
+    if (!pending) {
+      return modelData;
+    }
+    pending = false;
+    return {
+      ...modelData,
+      instructions: modelData.instructions
+        ? `${modelData.instructions} ${GENESIS_TITLE_DIRECTIVE}`
+        : GENESIS_TITLE_DIRECTIVE,
+    };
+  };
+}
+
+function takeGenesisTitleInputFilter(agent: Agent<any, any>): CallModelInputFilter | undefined {
+  if (!agentsNeedingGenesisTitleDirective.has(agent)) {
+    return undefined;
+  }
+  agentsNeedingGenesisTitleDirective.delete(agent);
+  return oneShotGenesisTitleInputFilter();
+}
+
 // Generic substrate prompting for programmatic tool calling (toolspace). Same
 // text for every host; gated per-turn by appendToolspaceInstructions on the
 // presence of a minted toolspace token, so it only appears when the sandbox
@@ -2256,7 +2943,7 @@ export const stripProviderItemIdsFilter: CallModelInputFilter = ({ modelData })
  * `action` and `actions` down to EXACTLY ONE (keeps `actions`, drops `action`).
  * The Azure computer-use endpoint rejects a request whose computer_call has
  * both with `400 Computer call input must include exactly one of `action` or
- * `actions``; and (live-proven against gpt-5.5's GA computer tool) it also
+ * `actions``; and (live-proven against gpt-5.6-sol's GA computer tool) it also
  * rejects the `action`-only form, accepting ONLY the batched plural `actions`.
  * The SDK 0.11.6 schema allows both, so a freshly-emitted
  * screenshot call carries the redundant pair. This filter runs before EVERY
@@ -2272,43 +2959,43 @@ export const normalizeComputerCallsFilter: CallModelInputFilter = ({ modelData }
   ) as unknown as AgentInputItem[],
 });
 
+/**
+ * Per-call state compaction for local image inspection. Re-opening the same
+ * path supersedes its prior base64 result; carrying both provides no newer
+ * information and can otherwise balloon every following model request.
+ */
+export const elideSupersededViewImagesFilter: CallModelInputFilter = ({ modelData }) => ({
+  ...modelData,
+  input: elideSupersededViewImagePairs(
+    modelData.input as unknown as Array<Record<string, unknown>>,
+  ) as unknown as AgentInputItem[],
+});
+
 export function contextRobustnessFilterForSettings(
   settings: Settings,
   options: ContextRobustnessFilterOptions = {},
 ): CallModelInputFilter {
-  const inputBudgetTokens = modelCallBudgetTokens(settings);
-  const clientCompactionMode = resolveContextCompactionMode(settings) === "client";
-  const compactionThresholdTokens = clientCompactionThresholdTokens(settings);
-  return ({ modelData }) => {
-    const images = elideStaleScreenshotImages(modelData.input);
-    if (images.elidedCount > 0) {
-      console.warn(
-        `per-call image history policy elided ${images.elidedCount} older screenshot image(s), keeping the last ${Math.min(3, images.imageCount)} full image(s)`,
-      );
-    }
-    let input = images.items;
-    if (inputBudgetTokens !== undefined) {
-      const guarded = enforceInputBudget(
-        input as unknown as Array<Record<string, unknown>>,
-        inputBudgetTokens,
-      );
-      if (guarded.trimmed) {
-        console.warn(
-          `per-call budget guard trimmed ${guarded.droppedCount} oldest history item(s) to fit input budget (${inputBudgetTokens} tokens); the over-budget model call was NOT sent`,
-        );
-        input = guarded.items as unknown as AgentInputItem[];
-      }
-    }
-    if (clientCompactionMode && options.throwOnCompactionNeeded) {
+  const thresholdTokens = compactionThresholdTokens(settings);
+  return async ({ modelData }) => {
+    const input = modelData.input;
+    if (options.throwOnCompactionNeeded) {
       const reported = options.contextCompactionSignalTokens?.();
       const hasReported = typeof reported === "number" && reported > 0;
       const signalTokens = hasReported
         ? reported
         : estimateTokens(input as unknown as Array<Record<string, unknown>>);
-      if (signalTokens > compactionThresholdTokens) {
+      if (await options.contextCompactionRequested?.()) {
+        throw new CompactionNeededError({
+          signalTokens,
+          thresholdTokens,
+          signalSource: hasReported ? "provider" : "estimate",
+          trigger: "operator",
+        });
+      }
+      if (signalTokens >= thresholdTokens) {
         throw new CompactionNeededError({
           signalTokens,
-          thresholdTokens: compactionThresholdTokens,
+          thresholdTokens,
           signalSource: hasReported ? "provider" : "estimate",
         });
       }
@@ -2317,14 +3004,6 @@ export function contextRobustnessFilterForSettings(
   };
 }
 
-function modelCallBudgetTokens(settings: Settings): number | undefined {
-  if (resolveContextCompactionMode(settings) !== "client") {
-    return undefined;
-  }
-  const budget = contextInputBudgetTokens(settings);
-  return budget > 0 ? budget : undefined;
-}
-
 /**
  * Compose a list of callModelInputFilters into one, applied left-to-right so
  * each sees the prior filter's output.
@@ -2343,14 +3022,18 @@ function composeCallModelInputFilters(filters: CallModelInputFilter[]): CallMode
  * The model-input filter applied before every model call. The computer_call
  * action/actions normalizer is ALWAYS on (the Azure endpoint 400s without it);
  * the provider-item-id strip is layered on top when the configured policy
- * selects it; the context-robustness guard then elides stale screenshots on
- * every mode and applies hard budget trimming only on the client-compaction path.
+ * selects it; the context-robustness guard then raises the proactive durable
+ * compaction signal on the client-compaction path. It never trims history from
+ * an individual request.
  */
 export function callModelInputFilterForSettings(
   settings: Settings,
   options: ContextRobustnessFilterOptions = {},
 ): CallModelInputFilter | undefined {
-  const filters: CallModelInputFilter[] = [normalizeComputerCallsFilter];
+  const filters: CallModelInputFilter[] = [
+    normalizeComputerCallsFilter,
+    elideSupersededViewImagesFilter,
+  ];
   if (settings.openaiProviderItemIds === "strip") {
     filters.push(stripProviderItemIdsFilter);
   }
@@ -2358,9 +3041,16 @@ export function callModelInputFilterForSettings(
   return composeCallModelInputFilters(filters);
 }
 
-export async function runAgentStream(agent: Agent<any, any>, input: PreparedAgentInput | string | RunState<any, any>, settings: Settings, overrides: RunAgentStreamOptions = {}) {
-  const prepared: PreparedAgentInput = typeof input === "string" || input instanceof RunState ? { input } : input;
+export async function runAgentStream(
+  agent: Agent<any, any>,
+  input: PreparedAgentInput | string | RunState<any, any>,
+  settings: Settings,
+  overrides: RunAgentStreamOptions = {},
+) {
+  const prepared: PreparedAgentInput =
+    typeof input === "string" || input instanceof RunState ? { input } : input;
   const environment = overrides.sandboxEnvironment ?? collectSandboxEnvironment(settings);
+  const genesisTitleInputFilter = takeGenesisTitleInputFilter(agent);
 
   // OWNED PATH (P1.2 ownership inversion): the per-turn resume path injected a
   // live, externally-owned box. We thread the live `session` straight into
@@ -2379,90 +3069,75 @@ export async function runAgentStream(agent: Agent<any, any>, input: PreparedAgen
     // whose per-op pointer re-read could land these execs on a machine swapped in
     // mid-turn.
     const setupSession = (overrides.ownedSandbox.setupSession ?? session) as SandboxSessionLike;
+    // Platform setup (manifest-env pin + beforeAgentStart hooks + file downloads)
+    // against the UN-proxied established box — the ONE-TRUTH helper shared with the
+    // lazy provisioner. Eager path: runs here, before the run starts (unchanged).
+    if (!overrides.ownedSandbox.deferredSetup) {
+      await runOwnedSandboxSetup(agent, session as SandboxSessionLike, setupSession, {
+        settings,
+        environment,
+        preparedInput: prepared,
+        ...(overrides.ownedSandbox.fileDownloadsMaterialized
+          ? { fileDownloadsMaterialized: true }
+          : {}),
+        ...(overrides.onRuntimeEvent ? { onRuntimeEvent: overrides.onRuntimeEvent } : {}),
+      });
+      await overrides.onGitCredentialSessionReady?.(setupSession);
+    }
     const runAs = sandboxRunAs(settings);
     const fileDownloads = sandboxFileDownloadsForAgent(agent);
-    const resourceClient = fileDownloads.length > 0
-      ? withSandboxFileDownloads(ownedClient as SandboxClient, fileDownloads, {
-        ...(overrides.onRuntimeEvent ? { onRuntimeEvent: overrides.onRuntimeEvent } : {}),
-        ...(runAs ? { runAs } : {}),
-      })
-      : (ownedClient as SandboxClient);
+    const resourceClient =
+      fileDownloads.length > 0
+        ? withSandboxFileDownloads(ownedClient as SandboxClient, fileDownloads, {
+            ...(overrides.onRuntimeEvent ? { onRuntimeEvent: overrides.onRuntimeEvent } : {}),
+            ...(runAs ? { runAs } : {}),
+          })
+        : (ownedClient as SandboxClient);
     // TOKEN-BROKER (B1): the per-turn git token seed, forwarded OFF-MANIFEST so the
     // repository-clone hook seeds it to the box's token file before the clone.
-    const ownedGitTokenSeed = gitTokenSeedForAgent(agent);
+    const ownedGitTokenSeeds = gitTokenSeedsForAgent(agent);
     const ownedToolspaceTokenSeed = toolspaceTokenSeedForAgent(agent);
+    const ownedRigSetup = rigSetupDescriptorForAgent(agent);
     const ownedHooks = [
-      ...sandboxLifecycleHooksForIds(sandboxLifecycleHookIds(settings)),
+      // M3: rig setup runs FIRST so any tooling it installs is present for the
+      // credential / repository-clone hooks below. The rig's credential hooks are
+      // unioned into the deployment preparation-profile hooks (deduped by id).
+      ...sandboxRigSetupHooksForAgent(agent),
+      ...unionCredentialHooks(
+        sandboxLifecycleHooksForIds(sandboxLifecycleHookIds(settings)),
+        rigCredentialHooksForAgent(agent),
+      ),
       ...sandboxToolspaceTokenHooksForAgent(agent),
       ...sandboxRepositoryCloneHooksForAgent(agent),
+      ...gitCredentialSessionRegistrationHooks(overrides.onGitCredentialSessionReady),
     ];
     const ownedHookContext: SandboxLifecycleHookContext = {
       environment,
       ...(overrides.onRuntimeEvent ? { onRuntimeEvent: overrides.onRuntimeEvent } : {}),
       ...(runAs ? { runAs } : {}),
-      ...(ownedGitTokenSeed ? { gitTokenSeed: ownedGitTokenSeed } : {}),
+      ...(ownedGitTokenSeeds ? { gitTokenSeeds: ownedGitTokenSeeds } : {}),
       ...(ownedToolspaceTokenSeed ? { toolspaceTokenSeed: ownedToolspaceTokenSeed } : {}),
+      ...(ownedRigSetup ? { rigSetup: ownedRigSetup } : {}),
     };
-    // OWNED-PATH HOOKS: the SDK NEVER calls client.create/resume when handed a live
-    // provided session (SandboxRuntimeManager uses `sandboxConfig.session` directly),
-    // so the withSandboxLifecycleHooks decoration below can never fire on this branch —
-    // it only wraps create/resume. Run the beforeAgentStart hooks directly against the
-    // provided box, once per turn, BEFORE the run starts: this is what executes the
-    // repository-clone hook (which also seeds the B1 askpass + token file) and the
-    // azure-cli-login hook on lease-owned boxes. Re-running on a warm box is safe by
-    // construction: clone skips when the target is already materialized, the token
-    // seed OVERWRITES the file (the desired per-turn refresh), and az login is
-    // idempotent. A turn resumed after preemption re-enters here and re-seeds the
-    // freshly minted token — which is exactly what a >1h-old warm box needs.
-    // EXCEPT on a connected machine (effective backend "selfhosted"): the box is the
-    // user's REAL computer — the platform must not run setup against it (the clone
-    // hooks are already empty there; this keeps az login off it too).
-    if (agentActiveSandboxBackend.get(agent) !== "selfhosted") {
-      await runBeforeAgentStartHooks(setupSession, ownedHooks, ownedHookContext);
-      // FILE RESOURCES: withSandboxFileDownloads below has the IDENTICAL provided-
-      // session blind spot (it too wraps only create/resume), so signed-URL file
-      // materialization must also run directly against the pinned box. The download
-      // command is idempotent (skips an existing file) and atomic (tmp + rename),
-      // so the per-turn re-run is safe; the turn re-signs URLs each run, so a
-      // re-warmed box always gets fresh links.
-      if (fileDownloads.length > 0) {
-        await materializeSandboxFileDownloads(setupSession, fileDownloads, {
-          ...(overrides.onRuntimeEvent ? { onRuntimeEvent: overrides.onRuntimeEvent } : {}),
-          ...(runAs ? { runAs } : {}),
-        });
-      }
-    } else {
-      // SELFHOSTED TOOLSPACE (parity): the platform setup hooks (repository clone,
-      // az login) and file materialization stay OFF the user's real machine — but
-      // the toolspace token seed is the ONE piece of per-turn material that must
-      // reach it. It writes a scoped, own-session-bound token to
-      // $OPENGENI_TOOLSPACE_TOKEN_FILE over the SAME exec channel the clone-seed
-      // uses (off-manifest, value never on the manifest), and it grants no more
-      // than the machine owner's own authority (toolspace:call, this session, turn
-      // TTL, budgeted, approval-tools excluded) — the invariant that makes it safe
-      // to cross to a user machine when the git token is not. It is also the
-      // machine's only path to programmatic tool calling. Seed it (only) here; the
-      // hook list is empty when no toolspace token was minted for this turn.
-      const toolspaceHooks = sandboxToolspaceTokenHooksForAgent(agent);
-      if (toolspaceHooks.length > 0) {
-        await runBeforeAgentStartHooks(setupSession, toolspaceHooks, ownedHookContext);
-      }
-    }
     // Keep the decoration as a safety net for any session the SDK does create/resume
     // through the client during this run (it is inert for the provided session).
     const decoratedClient = withSandboxLifecycleHooks(resourceClient, ownedHooks, ownedHookContext);
     const ownedFilter = composeCallModelInputFilters(
       [
         callModelInputFilterForSettings(settings, {
-          throwOnCompactionNeeded: Boolean(overrides.contextCompactionSignalTokens),
+          throwOnCompactionNeeded: Boolean(
+            overrides.contextCompactionSignalTokens || overrides.contextCompactionRequested,
+          ),
           ...(overrides.contextCompactionSignalTokens
             ? { contextCompactionSignalTokens: overrides.contextCompactionSignalTokens }
             : {}),
+          ...(overrides.contextCompactionRequested
+            ? { contextCompactionRequested: overrides.contextCompactionRequested }
+            : {}),
         }),
+        genesisTitleInputFilter,
         overrides.callModelInputFilter,
-      ].filter(
-        (f): f is CallModelInputFilter => Boolean(f),
-      ),
+      ].filter((f): f is CallModelInputFilter => Boolean(f)),
     );
     const ownedRunOptions: Parameters<typeof run>[2] = {
       stream: true,
@@ -2479,37 +3154,55 @@ export async function runAgentStream(agent: Agent<any, any>, input: PreparedAgen
 
   const rawClient = overrides.sandboxClient ?? createSandboxClient(settings, environment);
   const refreshedClient = rawClient
-    ? withManifestRefreshOnResume(rawClient as SandboxClient, (agent as { defaultManifest?: Manifest }).defaultManifest)
+    ? withManifestRefreshOnResume(
+        rawClient as SandboxClient,
+        (agent as { defaultManifest?: Manifest }).defaultManifest,
+        {
+          ...(overrides.onRuntimeEvent ? { onRuntimeEvent: overrides.onRuntimeEvent } : {}),
+        },
+      )
     : undefined;
   const runAs = sandboxRunAs(settings);
   const fileDownloads = sandboxFileDownloadsForAgent(agent);
-  const resourceClient = refreshedClient && fileDownloads.length > 0
-    ? withSandboxFileDownloads(refreshedClient, fileDownloads, {
-      ...(overrides.onRuntimeEvent ? { onRuntimeEvent: overrides.onRuntimeEvent } : {}),
-      ...(runAs ? { runAs } : {}),
-    })
-    : refreshedClient;
+  const resourceClient =
+    refreshedClient && fileDownloads.length > 0
+      ? withSandboxFileDownloads(refreshedClient, fileDownloads, {
+          ...(overrides.onRuntimeEvent ? { onRuntimeEvent: overrides.onRuntimeEvent } : {}),
+          ...(runAs ? { runAs } : {}),
+        })
+      : refreshedClient;
   // TOKEN-BROKER (B1): the per-turn git token seed, forwarded OFF-MANIFEST so the
   // repository-clone hook seeds it to the box's token file before the clone.
-  const gitTokenSeed = gitTokenSeedForAgent(agent);
+  const gitTokenSeeds = gitTokenSeedsForAgent(agent);
   const toolspaceTokenSeed = toolspaceTokenSeedForAgent(agent);
+  const legacyRigSetup = rigSetupDescriptorForAgent(agent);
   const client = resourceClient
-    ? withSandboxLifecycleHooks(resourceClient, [
-      ...sandboxLifecycleHooksForIds(sandboxLifecycleHookIds(settings)),
-      ...sandboxToolspaceTokenHooksForAgent(agent),
-      ...sandboxRepositoryCloneHooksForAgent(agent),
-    ], {
-      environment,
-      ...(overrides.onRuntimeEvent ? { onRuntimeEvent: overrides.onRuntimeEvent } : {}),
-      ...(runAs ? { runAs } : {}),
-      ...(gitTokenSeed ? { gitTokenSeed } : {}),
-      ...(toolspaceTokenSeed ? { toolspaceTokenSeed } : {}),
-    })
+    ? withSandboxLifecycleHooks(
+        resourceClient,
+        [
+          // M3: same rig-setup-first ordering + credential-hook union as the owned
+          // path (this legacy create/resume decoration path is byte-for-byte today
+          // for a rig-less turn — the rig hooks are empty then).
+          ...sandboxRigSetupHooksForAgent(agent),
+          ...unionCredentialHooks(
+            sandboxLifecycleHooksForIds(sandboxLifecycleHookIds(settings)),
+            rigCredentialHooksForAgent(agent),
+          ),
+          ...sandboxToolspaceTokenHooksForAgent(agent),
+          ...sandboxRepositoryCloneHooksForAgent(agent),
+          ...gitCredentialSessionRegistrationHooks(overrides.onGitCredentialSessionReady),
+        ],
+        {
+          environment,
+          ...(overrides.onRuntimeEvent ? { onRuntimeEvent: overrides.onRuntimeEvent } : {}),
+          ...(runAs ? { runAs } : {}),
+          ...(gitTokenSeeds ? { gitTokenSeeds } : {}),
+          ...(toolspaceTokenSeed ? { toolspaceTokenSeed } : {}),
+          ...(legacyRigSetup ? { rigSetup: legacyRigSetup } : {}),
+        },
+      )
     : undefined;
-  const sandboxSessionState = prepared.sandboxSessionState
-    ?? (prepared.serializedRunStateForSandbox && client
-      ? await restoredSandboxSessionState(await RunState.fromString(agent, prepared.serializedRunStateForSandbox), client)
-      : undefined);
+  const sandboxSessionState = prepared.sandboxSessionState;
   // Apply the built-in per-call filters (computer-call normalization, optional
   // provider-id stripping, image/budget guard), then any per-turn filter
   // (genesis title directive). A callModelInputFilter only shapes the per-call
@@ -2518,22 +3211,26 @@ export async function runAgentStream(agent: Agent<any, any>, input: PreparedAgen
   const callModelInputFilter = composeCallModelInputFilters(
     [
       callModelInputFilterForSettings(settings, {
-        throwOnCompactionNeeded: Boolean(overrides.contextCompactionSignalTokens),
+        throwOnCompactionNeeded: Boolean(
+          overrides.contextCompactionSignalTokens || overrides.contextCompactionRequested,
+        ),
         ...(overrides.contextCompactionSignalTokens
           ? { contextCompactionSignalTokens: overrides.contextCompactionSignalTokens }
           : {}),
+        ...(overrides.contextCompactionRequested
+          ? { contextCompactionRequested: overrides.contextCompactionRequested }
+          : {}),
       }),
+      genesisTitleInputFilter,
       overrides.callModelInputFilter,
-    ].filter(
-      (f): f is CallModelInputFilter => Boolean(f),
-    ),
+    ].filter((f): f is CallModelInputFilter => Boolean(f)),
   );
   const runOptions: Parameters<typeof run>[2] = {
     stream: true,
     maxTurns: settings.agentMaxModelCallsPerTurn,
     // Built-in per-call guard chain: normalize computer calls, optionally strip
-    // provider ids, elide stale screenshots in every mode, and trim to the input
-    // budget on the client-compaction path. This runs for turn-start replay AND
+    // provider ids, trim to the input budget on the client-compaction path, and
+    // raise the proactive compaction signal. This runs for turn-start replay AND
     // every mid-turn follow-up.
     callModelInputFilter,
   };
@@ -2546,6 +3243,26 @@ export async function runAgentStream(agent: Agent<any, any>, input: PreparedAgen
   return await runScopedRunner(settings).run(agent, prepared.input, runOptions);
 }
 
+function appendSandboxFileDownloadFailureNote(
+  input: PreparedAgentInput,
+  failures: SandboxFileDownloadFailure[],
+): void {
+  const note = sandboxFileDownloadFailureNote(failures);
+  if (!note) {
+    return;
+  }
+  if (typeof input.input === "string") {
+    input.input = [input.input, "", note].join("\n");
+    return;
+  }
+  if (Array.isArray(input.input)) {
+    input.input = [
+      ...input.input,
+      { type: "message", role: "user", content: note } as AgentInputItem,
+    ];
+  }
+}
+
 /**
  * A per-run `Runner` whose `modelProvider` is built from THIS turn's settings.
  *
@@ -2577,7 +3294,9 @@ export { MaxTurnsExceededError } from "@openai/agents";
  * the work. When the SDK attached the run state at the moment the cap hit,
  * the serialized form is returned so the resumed turn keeps full context.
  */
-export function maxTurnsExceededRunState(error: unknown): { serializedRunState: string | null } | null {
+export function maxTurnsExceededRunState(
+  error: unknown,
+): { serializedRunState: string | null } | null {
   if (!(error instanceof MaxTurnsExceededError)) {
     return null;
   }
@@ -2605,42 +3324,102 @@ export function agentsErrorRunState(error: unknown): string | null {
   }
 }
 
-export function withManifestRefreshOnResume(client: SandboxClient, targetManifest: Manifest | undefined): SandboxClient {
+export function withManifestRefreshOnResume(
+  client: SandboxClient,
+  targetManifest: Manifest | undefined,
+  context: Pick<SandboxLifecycleHookContext, "onRuntimeEvent"> = {},
+): SandboxClient {
   if (!targetManifest || !client.resume) {
     return client;
   }
   return {
     backendId: client.backendId,
-    ...(client.supportsDefaultOptions !== undefined ? { supportsDefaultOptions: client.supportsDefaultOptions } : {}),
-    ...(client.create ? { create: async (...args: any[]) => await (client.create as any)(...args) } : {}),
+    ...(client.supportsDefaultOptions !== undefined
+      ? { supportsDefaultOptions: client.supportsDefaultOptions }
+      : {}),
+    ...(client.create
+      ? { create: async (...args: any[]) => await (client.create as any)(...args) }
+      : {}),
     resume: async (state: SandboxSessionState) => {
       const session = await client.resume!(state);
-      await applyMissingManifestEntries(session, targetManifest);
+      await applyMissingManifestEntries(session, targetManifest, context);
       return session;
     },
-    ...(client.delete ? { delete: async (state: SandboxSessionState) => await client.delete!(state) } : {}),
-    ...(client.serializeSessionState ? { serializeSessionState: async (state: SandboxSessionState, options) => await client.serializeSessionState!(state, options) } : {}),
-    ...(client.canPersistOwnedSessionState ? { canPersistOwnedSessionState: async (state: SandboxSessionState) => await client.canPersistOwnedSessionState!(state) } : {}),
-    ...(client.canReusePreservedOwnedSession ? { canReusePreservedOwnedSession: async (state: SandboxSessionState) => await client.canReusePreservedOwnedSession!(state) } : {}),
-    ...(client.deserializeSessionState ? { deserializeSessionState: async (state: Record<string, unknown>) => await client.deserializeSessionState!(state) } : {}),
+    ...(client.delete
+      ? { delete: async (state: SandboxSessionState) => await client.delete!(state) }
+      : {}),
+    ...(client.serializeSessionState
+      ? {
+          serializeSessionState: async (state: SandboxSessionState, options) =>
+            await client.serializeSessionState!(state, options),
+        }
+      : {}),
+    ...(client.canPersistOwnedSessionState
+      ? {
+          canPersistOwnedSessionState: async (state: SandboxSessionState) =>
+            await client.canPersistOwnedSessionState!(state),
+        }
+      : {}),
+    ...(client.canReusePreservedOwnedSession
+      ? {
+          canReusePreservedOwnedSession: async (state: SandboxSessionState) =>
+            await client.canReusePreservedOwnedSession!(state),
+        }
+      : {}),
+    ...(client.deserializeSessionState
+      ? {
+          deserializeSessionState: async (state: Record<string, unknown>) =>
+            await client.deserializeSessionState!(state),
+        }
+      : {}),
   };
 }
 
-export async function applyMissingManifestEntries(session: SandboxSessionLike, targetManifest: Manifest): Promise<void> {
-  const currentManifestValue = (session as { state?: { manifest?: Manifest | { root?: string; entries?: Record<string, any>; environment?: Record<string, any> } } }).state?.manifest;
+// OWNED-RESUME manifest refresh. This path runs ONLY for SDK-owned sessions
+// (withManifestRefreshOnResume wraps client.resume, which the SDK never calls
+// when handed a live provided session — the ownedSandbox branch bypasses this
+// entirely). Owned applyManifest MERGES env safely with no guard, and this
+// refresh is a FEATURE: it is how a workspace-env edit reaches a long-lived
+// owned local/docker box that rarely recycles. The provided-session env pin
+// (pinProvidedSessionManifestEnvironment below) — NOT this function — is the
+// fix for the SDK's validateNoEnvironmentDelta session-fatal guard. Drift is
+// additionally REPORTED here (key names only, never values) so any env
+// recompute change stays attributable from the DB alone.
+export async function applyMissingManifestEntries(
+  session: SandboxSessionLike,
+  targetManifest: Manifest,
+  context: Pick<SandboxLifecycleHookContext, "onRuntimeEvent"> = {},
+): Promise<void> {
+  const currentManifestValue = (
+    session as {
+      state?: {
+        manifest?:
+          | Manifest
+          | { root?: string; entries?: Record<string, any>; environment?: Record<string, any> };
+      };
+    }
+  ).state?.manifest;
   const currentManifest = currentManifestValue ? ensureManifest(currentManifestValue) : undefined;
   const target = ensureManifest(targetManifest);
   if (!currentManifest) {
     if (Object.keys(target.entries).length === 0) {
       return;
     }
-    throw new Error("Resumed sandbox session cannot apply new manifest entries because current manifest state is unavailable");
+    throw new Error(
+      "Resumed sandbox session cannot apply new manifest entries because current manifest state is unavailable",
+    );
   }
+  // Drift detection runs on EVERY resume (even no-op ones): the durable trace
+  // that makes an env-recompute regression attributable from the DB instead of
+  // from rotated worker logs.
+  await reportManifestEnvironmentDrift(currentManifest, target, context);
   if (!session.applyManifest && !session.materializeEntry) {
     if (Object.keys(target.entries).length === 0) {
       return;
     }
-    throw new Error("Resumed sandbox session cannot apply new manifest entries because it does not support applyManifest() or materializeEntry()");
+    throw new Error(
+      "Resumed sandbox session cannot apply new manifest entries because it does not support applyManifest() or materializeEntry()",
+    );
   }
   if (Object.keys(target.entries).length === 0) {
     return;
@@ -2659,9 +3438,12 @@ export async function applyMissingManifestEntries(session: SandboxSessionLike, t
       throw new Error(`Cannot replace existing sandbox manifest entry: ${path}`);
     }
   }
-  const environmentChanged = stableJson(currentManifest.environment) !== stableJson(target.environment);
+  const environmentChanged =
+    stableJson(currentManifest.environment) !== stableJson(target.environment);
   if (environmentChanged && !session.applyManifest) {
-    throw new Error("Resumed sandbox session cannot refresh manifest environment because it does not support applyManifest()");
+    throw new Error(
+      "Resumed sandbox session cannot refresh manifest environment because it does not support applyManifest()",
+    );
   }
   if (Object.keys(entries).length === 0 && !environmentChanged) {
     return;
@@ -2694,6 +3476,216 @@ export async function applyMissingManifestEntries(session: SandboxSessionLike, t
   });
 }
 
+/**
+ * Key-level diff of the live box's baked manifest env vs the freshly recomputed
+ * target env. Returns null when identical. Key NAMES only — values are secrets
+ * and must never leave this function's comparison.
+ */
+export function manifestEnvironmentDrift(
+  current: Manifest,
+  target: Manifest,
+): { added: string[]; removed: string[]; changed: string[] } | null {
+  const currentEnv = (current.environment ?? {}) as Record<string, unknown>;
+  const targetEnv = (target.environment ?? {}) as Record<string, unknown>;
+  const added: string[] = [];
+  const removed: string[] = [];
+  const changed: string[] = [];
+  for (const key of Object.keys(targetEnv)) {
+    if (!(key in currentEnv)) {
+      added.push(key);
+    } else if (stableJson(currentEnv[key]) !== stableJson(targetEnv[key])) {
+      changed.push(key);
+    }
+  }
+  for (const key of Object.keys(currentEnv)) {
+    if (!(key in targetEnv)) {
+      removed.push(key);
+    }
+  }
+  if (added.length === 0 && removed.length === 0 && changed.length === 0) {
+    return null;
+  }
+  return { added: added.sort(), removed: removed.sort(), changed: changed.sort() };
+}
+
+async function reportManifestEnvironmentDrift(
+  current: Manifest,
+  target: Manifest,
+  context: Pick<SandboxLifecycleHookContext, "onRuntimeEvent">,
+): Promise<ReturnType<typeof manifestEnvironmentDrift>> {
+  const drift = manifestEnvironmentDrift(current, target);
+  if (!drift) {
+    return null;
+  }
+  // Reporting must never break a resume: the drift itself is benign under the
+  // env pin (the box keeps running on its baked env); only the SIGNAL matters.
+  try {
+    await context.onRuntimeEvent?.({ type: "sandbox.env.drift", payload: drift });
+  } catch {
+    // Swallow: a failed emit must not fail the turn.
+  }
+  return drift;
+}
+
+/**
+ * ENV PIN for provided sessions (the ownership-inversion turn path). The SDK
+ * validates the FULL target manifest environment against a live provided
+ * session's baked env BEFORE reducing to its entry-only delta
+ * (validateNoEnvironmentDelta -> session-fatal UserError on ANY difference).
+ * So a turn resuming an existing box must declare the box's OWN env,
+ * byte-identical — never the fresh recompute. This replaces the agent's
+ * defaultManifest environment with the baked one and reports the drift (key
+ * names only) instead of letting it kill the session. Fresh env lands at the
+ * next cold-create; rotating values ride OFF-manifest (TOKEN-BROKER B1/B2).
+ */
+export async function pinProvidedSessionManifestEnvironment(
+  agent: Agent<any, any>,
+  session: SandboxSessionLike,
+  context: Pick<SandboxLifecycleHookContext, "onRuntimeEvent"> = {},
+): Promise<void> {
+  const holder = agent as { defaultManifest?: Manifest };
+  const currentManifestValue = (
+    session as {
+      state?: {
+        manifest?:
+          | Manifest
+          | { root?: string; entries?: Record<string, any>; environment?: Record<string, any> };
+      };
+    }
+  ).state?.manifest;
+  if (!holder.defaultManifest || !currentManifestValue) {
+    return;
+  }
+  const current = ensureManifest(currentManifestValue);
+  const target = ensureManifest(holder.defaultManifest);
+  const drift = await reportManifestEnvironmentDrift(current, target, context);
+  if (!drift) {
+    return;
+  }
+  holder.defaultManifest = new Manifest({
+    ...(target.root ? { root: target.root } : {}),
+    entries: target.entries,
+    environment: current.environment,
+    ...(target.extraPathGrants?.length ? { extraPathGrants: target.extraPathGrants } : {}),
+  });
+}
+
+/**
+ * The one-truth owned-path platform setup: the manifest-env pin (align the turn's
+ * manifest to the live box's baked env + report drift, NEVER die on it) plus the
+ * beforeAgentStart hooks (repository clone with B1 token/askpass seed, toolspace
+ * token seed, azure-cli-login) and signed-URL file materialization — all executed
+ * DIRECTLY against the pinned, UN-proxied established box (the SDK never calls
+ * client.create/resume for a provided session, so these decorations would never
+ * fire on their own).
+ *
+ * Extracted verbatim from `runStream`'s owned branch so both the EAGER path
+ * (runStream, before the run starts) and the LAZY path (the worker's first-op
+ * provisioner, after the box is established) run the IDENTICAL setup. A pure
+ * refactor for the eager path: same order, same gates, same idempotency
+ * (clone skips a materialized tree, token seed overwrites — the desired per-turn
+ * refresh, az login is idempotent). The connected-machine (selfhosted) branch
+ * keeps platform setup OFF the user's real box and seeds ONLY the toolspace token.
+ *
+ * `gitTokenSeedsOverride` lets the lazy provisioner pass its own freshly-minted
+ * run-scoped provider tokens (minted at establish time, not turn start);
+ * unset ⇒ read the seeds off the agent exactly as the eager path does.
+ */
+export async function runOwnedSandboxSetup(
+  agent: Agent<any, any>,
+  session: SandboxSessionLike,
+  setupSession: SandboxSessionLike,
+  opts: {
+    settings: Settings;
+    environment: Record<string, string>;
+    preparedInput?: PreparedAgentInput;
+    fileDownloadsMaterialized?: boolean;
+    onRuntimeEvent?: SandboxLifecycleHookContext["onRuntimeEvent"];
+    gitTokenSeedsOverride?: GitTokenSeeds;
+    gitTokenSeedOverride?: string;
+  },
+): Promise<void> {
+  const { settings, environment } = opts;
+  // ENV PIN (provided sessions): the SDK validates the FULL recomputed manifest
+  // env against the live box's baked env before applying its entry-only delta
+  // (validateNoEnvironmentDelta — session-fatal on ANY drift; killed a 4-day
+  // prod manager session 2026-07-06). Align the turn's manifest to the box's
+  // own env and REPORT the drift instead of dying on it.
+  await pinProvidedSessionManifestEnvironment(agent, session, {
+    ...(opts.onRuntimeEvent ? { onRuntimeEvent: opts.onRuntimeEvent } : {}),
+  });
+  const runAs = sandboxRunAs(settings);
+  const fileDownloads = sandboxFileDownloadsForAgent(agent);
+  // TOKEN-BROKER (B1): per-turn provider token seeds, forwarded OFF-MANIFEST so
+  // the repository-clone hook writes provider token files before the clone. The
+  // lazy provisioner overrides them with its own establish-time mint.
+  const ownedGitTokenSeeds = {
+    ...(gitTokenSeedsForAgent(agent) ?? {}),
+    ...(opts.gitTokenSeedOverride ? { github: opts.gitTokenSeedOverride } : {}),
+    ...(opts.gitTokenSeedsOverride ?? {}),
+  } satisfies GitTokenSeeds;
+  const ownedToolspaceTokenSeed = toolspaceTokenSeedForAgent(agent);
+  const ownedRigSetup = rigSetupDescriptorForAgent(agent);
+  const ownedHooks = [
+    // M3: rig setup runs FIRST so any tooling it installs is present for the
+    // credential / repository-clone hooks below; the rig's credential hooks are
+    // unioned into the deployment preparation-profile hooks (deduped by id).
+    // This is the LIVE owned-path execution (the provided session skips the
+    // client create/resume decoration), so the rig hooks MUST be here or a
+    // rig-bound turn would start without ever running the frozen setup script.
+    ...sandboxRigSetupHooksForAgent(agent),
+    ...unionCredentialHooks(
+      sandboxLifecycleHooksForIds(sandboxLifecycleHookIds(settings)),
+      rigCredentialHooksForAgent(agent),
+    ),
+    ...sandboxToolspaceTokenHooksForAgent(agent),
+    ...sandboxRepositoryCloneHooksForAgent(agent),
+  ];
+  const ownedHookContext: SandboxLifecycleHookContext = {
+    environment,
+    ...(opts.onRuntimeEvent ? { onRuntimeEvent: opts.onRuntimeEvent } : {}),
+    ...(runAs ? { runAs } : {}),
+    ...(Object.keys(ownedGitTokenSeeds).length > 0 ? { gitTokenSeeds: ownedGitTokenSeeds } : {}),
+    ...(ownedToolspaceTokenSeed ? { toolspaceTokenSeed: ownedToolspaceTokenSeed } : {}),
+    ...(ownedRigSetup ? { rigSetup: ownedRigSetup } : {}),
+  };
+  // OWNED-PATH HOOKS: run the beforeAgentStart hooks directly against the provided
+  // box, once per turn, BEFORE the run starts (repository-clone hook seeds the B1
+  // askpass + token file; azure-cli-login on lease-owned boxes). Re-running on a
+  // warm box is safe by construction (clone skips a materialized tree, token seed
+  // overwrites the file, az login is idempotent). EXCEPT on a connected machine
+  // (effective backend "selfhosted"): the box is the user's REAL computer — the
+  // platform must not run setup against it (clone hooks are already empty there;
+  // this keeps az login off it too).
+  if (agentActiveSandboxBackend.get(agent) !== "selfhosted") {
+    await runBeforeAgentStartHooks(setupSession, ownedHooks, ownedHookContext);
+    // FILE RESOURCES: withSandboxFileDownloads has the IDENTICAL provided-session
+    // blind spot (it too wraps only create/resume), so signed-URL file
+    // materialization must also run directly against the pinned box. The download
+    // command is idempotent (skips an existing file) and atomic (tmp + rename).
+    if (fileDownloads.length > 0 && !opts.fileDownloadsMaterialized) {
+      const materialized = await materializeSandboxFileDownloads(setupSession, fileDownloads, {
+        ...(opts.onRuntimeEvent ? { onRuntimeEvent: opts.onRuntimeEvent } : {}),
+        ...(runAs ? { runAs } : {}),
+      });
+      if (opts.preparedInput) {
+        appendSandboxFileDownloadFailureNote(opts.preparedInput, materialized.failures);
+      }
+    }
+  } else {
+    // SELFHOSTED TOOLSPACE (parity): the platform setup hooks and file
+    // materialization stay OFF the user's real machine — but the toolspace token
+    // seed is the ONE piece of per-turn material that must reach it (a scoped,
+    // own-session-bound token written to $OPENGENI_TOOLSPACE_TOKEN_FILE over the
+    // same off-manifest exec channel the clone-seed uses; the machine's only path
+    // to programmatic tool calling). Seed it (only) here.
+    const toolspaceHooks = sandboxToolspaceTokenHooksForAgent(agent);
+    if (toolspaceHooks.length > 0) {
+      await runBeforeAgentStartHooks(setupSession, toolspaceHooks, ownedHookContext);
+    }
+  }
+}
+
 function mergePathGrants(
   current: Manifest["extraPathGrants"] | undefined,
   target: Manifest["extraPathGrants"] | undefined,
@@ -2724,14 +3716,48 @@ export function withSandboxFileDownloads(
   };
   return {
     backendId: client.backendId,
-    ...(client.supportsDefaultOptions !== undefined ? { supportsDefaultOptions: client.supportsDefaultOptions } : {}),
-    ...(client.create ? { create: async (...args: any[]) => await wrapSession(await (client.create as any)(...args)) } : {}),
-    ...(client.resume ? { resume: async (state: SandboxSessionState) => await wrapSession(await client.resume!(state)) } : {}),
-    ...(client.delete ? { delete: async (state: SandboxSessionState) => await client.delete!(state) } : {}),
-    ...(client.serializeSessionState ? { serializeSessionState: async (state: SandboxSessionState, options) => await client.serializeSessionState!(state, options) } : {}),
-    ...(client.canPersistOwnedSessionState ? { canPersistOwnedSessionState: async (state: SandboxSessionState) => await client.canPersistOwnedSessionState!(state) } : {}),
-    ...(client.canReusePreservedOwnedSession ? { canReusePreservedOwnedSession: async (state: SandboxSessionState) => await client.canReusePreservedOwnedSession!(state) } : {}),
-    ...(client.deserializeSessionState ? { deserializeSessionState: async (state: Record<string, unknown>) => await client.deserializeSessionState!(state) } : {}),
+    ...(client.supportsDefaultOptions !== undefined
+      ? { supportsDefaultOptions: client.supportsDefaultOptions }
+      : {}),
+    ...(client.create
+      ? {
+          create: async (...args: any[]) =>
+            await wrapSession(await (client.create as any)(...args)),
+        }
+      : {}),
+    ...(client.resume
+      ? {
+          resume: async (state: SandboxSessionState) =>
+            await wrapSession(await client.resume!(state)),
+        }
+      : {}),
+    ...(client.delete
+      ? { delete: async (state: SandboxSessionState) => await client.delete!(state) }
+      : {}),
+    ...(client.serializeSessionState
+      ? {
+          serializeSessionState: async (state: SandboxSessionState, options) =>
+            await client.serializeSessionState!(state, options),
+        }
+      : {}),
+    ...(client.canPersistOwnedSessionState
+      ? {
+          canPersistOwnedSessionState: async (state: SandboxSessionState) =>
+            await client.canPersistOwnedSessionState!(state),
+        }
+      : {}),
+    ...(client.canReusePreservedOwnedSession
+      ? {
+          canReusePreservedOwnedSession: async (state: SandboxSessionState) =>
+            await client.canReusePreservedOwnedSession!(state),
+        }
+      : {}),
+    ...(client.deserializeSessionState
+      ? {
+          deserializeSessionState: async (state: Record<string, unknown>) =>
+            await client.deserializeSessionState!(state),
+        }
+      : {}),
   };
 }
 
@@ -2739,14 +3765,12 @@ export async function materializeSandboxFileDownloads(
   session: SandboxSessionLike,
   downloads: SandboxFileDownload[],
   context: Pick<SandboxLifecycleHookContext, "onRuntimeEvent" | "runAs"> = {},
-): Promise<void> {
+): Promise<SandboxFileDownloadMaterializationResult> {
   const normalizedDownloads = normalizeSandboxFileDownloads(downloads);
   if (normalizedDownloads.length === 0) {
-    return;
-  }
-  if (!session.exec && !session.execCommand) {
-    throw new Error("Sandbox file download materialization requires command execution support");
+    return { failures: [] };
   }
+  const failures: SandboxFileDownloadFailure[] = [];
   for (const download of normalizedDownloads) {
     const targetPath = sandboxDownloadTargetPath(download);
     const payload = {
@@ -2755,37 +3779,94 @@ export async function materializeSandboxFileDownloads(
       sizeBytes: download.sizeBytes ?? null,
       expiresAt: download.expiresAt ? new Date(download.expiresAt).toISOString() : null,
     };
-    await context.onRuntimeEvent?.({ type: "sandbox.operation.started", payload: { name: "file-resource-download", ...payload } });
+    await context.onRuntimeEvent?.({
+      type: "sandbox.operation.started",
+      payload: { name: "file-resource-download", ...payload },
+    });
+    if (!session.exec && !session.execCommand) {
+      const failure = sandboxFileDownloadFailure(
+        download,
+        targetPath,
+        "Sandbox file download materialization requires command execution support",
+      );
+      failures.push(failure);
+      await context.onRuntimeEvent?.({
+        type: "sandbox.operation.failed",
+        payload: {
+          name: "file-resource-download",
+          ...payload,
+          error: failure.reason,
+        },
+      });
+      continue;
+    }
+    let result: unknown;
     try {
-      const result = session.exec
+      result = session.exec
         ? await session.exec({
-          cmd: sandboxFileDownloadCommand(download, targetPath),
-          workdir: "/workspace",
-          ...(context.runAs ? { runAs: context.runAs } : {}),
-          yieldTimeMs: SANDBOX_LIFECYCLE_COMMAND_TIMEOUT_MS,
-          maxOutputTokens: 20_000,
-        })
+            cmd: sandboxFileDownloadCommand(download, targetPath),
+            workdir: "/workspace",
+            ...(context.runAs ? { runAs: context.runAs } : {}),
+            yieldTimeMs: SANDBOX_LIFECYCLE_COMMAND_TIMEOUT_MS,
+            maxOutputTokens: 20_000,
+          })
         : await session.execCommand!({
-          cmd: sandboxFileDownloadCommand(download, targetPath),
-          workdir: "/workspace",
-          ...(context.runAs ? { runAs: context.runAs } : {}),
-          yieldTimeMs: SANDBOX_LIFECYCLE_COMMAND_TIMEOUT_MS,
-          maxOutputTokens: 20_000,
-        });
+            cmd: sandboxFileDownloadCommand(download, targetPath),
+            workdir: "/workspace",
+            ...(context.runAs ? { runAs: context.runAs } : {}),
+            yieldTimeMs: SANDBOX_LIFECYCLE_COMMAND_TIMEOUT_MS,
+            maxOutputTokens: 20_000,
+          });
       assertSandboxCommandSucceeded(result, `Sandbox file resource download ${download.fileId}`);
-      await context.onRuntimeEvent?.({ type: "sandbox.operation.completed", payload: { name: "file-resource-download", ...payload } });
+      await context.onRuntimeEvent?.({
+        type: "sandbox.operation.completed",
+        payload: { name: "file-resource-download", ...payload },
+      });
     } catch (error) {
+      const failure = sandboxFileDownloadFailure(download, targetPath, error, result);
+      failures.push(failure);
       await context.onRuntimeEvent?.({
         type: "sandbox.operation.failed",
         payload: {
           name: "file-resource-download",
           ...payload,
-          error: error instanceof Error ? error.message : String(error),
+          error: failure.reason,
+          ...(failure.exitCode !== undefined ? { exitCode: failure.exitCode } : {}),
+          ...(failure.output ? { output: failure.output } : {}),
         },
       });
-      throw error;
     }
   }
+  return { failures };
+}
+
+function sandboxFileDownloadFailure(
+  download: SandboxFileDownload,
+  targetPath: string,
+  error: unknown,
+  result?: unknown,
+): SandboxFileDownloadFailure {
+  const exitCode = sandboxCommandExitCode(result);
+  const output = sandboxCommandOutput(result);
+  return {
+    fileId: download.fileId,
+    filename: download.filename,
+    path: targetPath,
+    reason: error instanceof Error ? error.message : String(error),
+    ...(exitCode !== null ? { exitCode } : {}),
+    ...(output ? { output } : {}),
+  };
+}
+
+export function sandboxFileDownloadFailureNote(failures: SandboxFileDownloadFailure[]): string {
+  if (failures.length === 0) {
+    return "";
+  }
+  return [
+    "The following attached files could not be loaded into the sandbox and are unavailable this turn:",
+    ...failures.map((failure) => `- ${failure.filename} (${failure.reason})`),
+    "Continue without them or tell the user.",
+  ].join("\n");
 }
 
 export function sandboxFileDownloadsForAgent(agent: unknown): SandboxFileDownload[] {
@@ -2794,8 +3875,20 @@ export function sandboxFileDownloadsForAgent(agent: unknown): SandboxFileDownloa
     : [];
 }
 
-function ensureManifest(manifest: Manifest | { root?: string; entries?: Record<string, any>; environment?: Record<string, any>; extraPathGrants?: any[] }): Manifest {
-  if (manifest instanceof Manifest && typeof manifest.mountTargetsForMaterialization === "function") {
+function ensureManifest(
+  manifest:
+    | Manifest
+    | {
+        root?: string;
+        entries?: Record<string, any>;
+        environment?: Record<string, any>;
+        extraPathGrants?: any[];
+      },
+): Manifest {
+  if (
+    manifest instanceof Manifest &&
+    typeof manifest.mountTargetsForMaterialization === "function"
+  ) {
     return manifest;
   }
   return new Manifest({
@@ -2846,7 +3939,10 @@ function structuredImageToDataUrl(value: unknown): string | null {
   if (typeof image.url === "string" && image.url.length > 0) {
     return image.url;
   }
-  const mediaType = typeof image.mediaType === "string" && image.mediaType.length > 0 ? image.mediaType : "image/png";
+  const mediaType =
+    typeof image.mediaType === "string" && image.mediaType.length > 0
+      ? image.mediaType
+      : "image/png";
   if (typeof image.data === "string") {
     return image.data.startsWith("data:") ? image.data : `data:${mediaType};base64,${image.data}`;
   }
@@ -2894,6 +3990,9 @@ export function normalizeSdkEvent(event: RunStreamEvent): NormalizedRuntimeEvent
       out.push({ type: "agent.message.delta", payload: { text: data.delta } });
       return out;
     }
+    if (data?.type === "response_done") {
+      return out;
+    }
   }
   if (isOpenAIResponsesRawModelStreamEvent(event)) {
     const raw = (event as any).data?.event;
@@ -2952,13 +4051,21 @@ export function normalizeSdkEvent(event: RunStreamEvent): NormalizedRuntimeEvent
   } else if (item.type === "tool_search_output_item") {
     const raw = item.rawItem ?? {};
     const disclosed = Array.isArray(raw.tools)
-      ? raw.tools.map((tool: { name?: unknown }) => (typeof tool?.name === "string" ? tool.name : "")).filter(Boolean)
+      ? raw.tools
+          .map((tool: { name?: unknown }) => (typeof tool?.name === "string" ? tool.name : ""))
+          .filter(Boolean)
       : [];
     out.push({
       type: "agent.toolCall.output",
       payload: {
         id: raw.call_id ?? raw.callId ?? item.id ?? null,
-        output: { type: "text", text: disclosed.length > 0 ? `Disclosed tools: ${disclosed.join(", ")}` : "No matching tools found." },
+        output: {
+          type: "text",
+          text:
+            disclosed.length > 0
+              ? `Disclosed tools: ${disclosed.join(", ")}`
+              : "No matching tools found.",
+        },
       },
     });
   } else if (item.type === "message_output_item") {
@@ -2972,15 +4079,21 @@ export function normalizeSdkEvent(event: RunStreamEvent): NormalizedRuntimeEvent
 
 export function modelResponseUsageFromSdkEvent(event: RunStreamEvent): ModelResponseUsage | null {
   const response = modelResponseFromSdkEvent(event);
+  return modelResponseUsageFromResponse(response);
+}
+
+/** Normalize usage from either a Responses or Chat Completions result. */
+export function modelResponseUsageFromResponse(response: unknown): ModelResponseUsage | null {
   const usage = usageFromResponse(response);
   if (!usage) {
     return null;
   }
-  const responseId = typeof response?.id === "string"
-    ? response.id
-    : typeof response?.responseId === "string"
-      ? response.responseId
-      : undefined;
+  const responseId =
+    typeof (response as { id?: unknown } | null)?.id === "string"
+      ? (response as { id: string }).id
+      : typeof (response as { responseId?: unknown } | null)?.responseId === "string"
+        ? (response as { responseId: string }).responseId
+        : undefined;
   return {
     ...(responseId ? { responseId } : {}),
     usage,
@@ -3003,33 +4116,70 @@ function modelResponseFromSdkEvent(event: RunStreamEvent): any {
   return null;
 }
 
-function usageFromResponse(response: any): ModelResponseUsage["usage"] | null {
-  const raw = response?.usage;
+function usageFromResponse(response: unknown): ModelResponseUsage["usage"] | null {
+  const raw = (response as { usage?: unknown } | null)?.usage;
   if (!raw || typeof raw !== "object") {
     return null;
   }
+  const record = raw as Record<string, unknown>;
   const usage = {
-    ...numberProp(raw, "inputTokens", "inputTokens", "input_tokens"),
-    ...numberProp(raw, "outputTokens", "outputTokens", "output_tokens"),
-    ...numberProp(raw, "totalTokens", "totalTokens", "total_tokens"),
-    ...inputTokenDetailsProp(raw),
+    ...numberProp(
+      record,
+      "inputTokens",
+      "inputTokens",
+      "input_tokens",
+      "promptTokens",
+      "prompt_tokens",
+    ),
+    ...numberProp(
+      record,
+      "outputTokens",
+      "outputTokens",
+      "output_tokens",
+      "completionTokens",
+      "completion_tokens",
+    ),
+    ...numberProp(record, "totalTokens", "totalTokens", "total_tokens"),
+    ...inputTokenDetailsProp(record),
+    ...outputTokenDetailsProp(record),
   };
   return Object.keys(usage).length > 0 ? usage : null;
 }
 
-function numberProp(raw: Record<string, unknown>, outputKey: "inputTokens" | "outputTokens" | "totalTokens", camel: string, snake: string): Partial<ModelResponseUsage["usage"]> {
-  const value = raw[camel] ?? raw[snake];
+function numberProp(
+  raw: Record<string, unknown>,
+  outputKey: "inputTokens" | "outputTokens" | "totalTokens",
+  ...keys: string[]
+): Partial<ModelResponseUsage["usage"]> {
+  const value = keys.map((key) => raw[key]).find((candidate) => candidate !== undefined);
   return typeof value === "number" && Number.isFinite(value) ? { [outputKey]: value } : {};
 }
 
 function inputTokenDetailsProp(raw: Record<string, unknown>): Partial<ModelResponseUsage["usage"]> {
-  const details = raw.inputTokensDetails ?? raw.input_tokens_details;
+  const details =
+    raw.inputTokensDetails ??
+    raw.input_tokens_details ??
+    raw.promptTokensDetails ??
+    raw.prompt_tokens_details;
   if (!details || typeof details !== "object") {
     return {};
   }
   return { inputTokensDetails: details as Record<string, number> | Array<Record<string, number>> };
 }
 
+function outputTokenDetailsProp(
+  raw: Record<string, unknown>,
+): Partial<ModelResponseUsage["usage"]> {
+  const details = raw.outputTokensDetails ?? raw.output_tokens_details;
+  const normalized = details ?? raw.completionTokensDetails ?? raw.completion_tokens_details;
+  if (!normalized || typeof normalized !== "object") {
+    return {};
+  }
+  return {
+    outputTokensDetails: normalized as Record<string, number> | Array<Record<string, number>>,
+  };
+}
+
 export function serializeApprovals(interruptions: unknown[]): unknown[] {
   return interruptions.map((item: any) => {
     if (typeof item?.toJSON === "function") {
@@ -3051,7 +4201,12 @@ export function buildManifest(
   fileResourceDownloads: SandboxFileDownload[] = [],
 ): Manifest {
   const entries: Record<string, any> = {};
-  const downloadsByFileId = new Map(normalizeSandboxFileDownloads(fileResourceDownloads).map((download) => [download.fileId, download]));
+  const downloadsByFileId = new Map(
+    normalizeSandboxFileDownloads(fileResourceDownloads).map((download) => [
+      download.fileId,
+      download,
+    ]),
+  );
   for (const resource of resources) {
     if (resource.kind === "repository") {
       const url = new URL(resource.uri);
@@ -3092,7 +4247,9 @@ export function buildManifest(
 
 function sandboxDownloadDirectory(download: SandboxFileDownload, mountPath: string): any {
   if (download.mountPath !== mountPath) {
-    throw new Error(`File download materialization path mismatch for ${download.fileId}: expected ${mountPath}, got ${download.mountPath}`);
+    throw new Error(
+      `File download materialization path mismatch for ${download.fileId}: expected ${mountPath}, got ${download.mountPath}`,
+    );
   }
   assertSafeSandboxFilename(download.filename, download.fileId);
   if (download.content) {
@@ -3113,7 +4270,9 @@ function objectStorageFileMount(settings: Settings, prefix: string): any {
   const nativeBucketMount = CAPABILITY_DESCRIPTORS[settings.sandboxBackend].nativeBucketMount;
   if (settings.objectStorageBackend === "azure-blob") {
     if (nativeBucketMount) {
-      throw new Error("Modal sandbox Azure Blob file resources require pre-signed download materialization because the current OpenAI Agents SDK Modal client does not support Azure Blob mount entries.");
+      throw new Error(
+        "Modal sandbox Azure Blob file resources require pre-signed download materialization because the current OpenAI Agents SDK Modal client does not support Azure Blob mount entries.",
+      );
     }
     const config = azureBlobMountConfig(settings);
     return azureBlobMount({
@@ -3127,7 +4286,9 @@ function objectStorageFileMount(settings: Settings, prefix: string): any {
     });
   }
   if (settings.objectStorageBackend === "aws-s3" || settings.objectStorageBackend === "gcs") {
-    throw new Error(`${settings.objectStorageBackend} file resources require pre-signed download materialization`);
+    throw new Error(
+      `${settings.objectStorageBackend} file resources require pre-signed download materialization`,
+    );
   }
   const config = s3CompatibleMountConfig(settings);
   return s3Mount({
@@ -3154,7 +4315,11 @@ function s3CompatibleMountConfig(settings: Settings): {
   secretAccessKey: string;
 } {
   const endpointUrl = settings.objectStorageSandboxEndpoint ?? settings.objectStorageEndpoint;
-  if (!endpointUrl || !settings.objectStorageAccessKeyId || !settings.objectStorageSecretAccessKey) {
+  if (
+    !endpointUrl ||
+    !settings.objectStorageAccessKeyId ||
+    !settings.objectStorageSecretAccessKey
+  ) {
     throw new Error("File resources require configured S3-compatible object storage");
   }
   return {
@@ -3181,7 +4346,10 @@ function azureBlobMountConfig(settings: Settings): {
   if (!accountName || !accountKey) {
     throw new Error("File resources require Azure Blob account name and account key");
   }
-  const endpointUrl = azureBlobManifestEndpoint(settings.objectStorageAzureEndpoint ?? parsed.BlobEndpoint, accountName);
+  const endpointUrl = azureBlobManifestEndpoint(
+    settings.objectStorageAzureEndpoint ?? parsed.BlobEndpoint,
+    accountName,
+  );
   return {
     container: settings.objectStorageBucket,
     accountName,
@@ -3190,7 +4358,10 @@ function azureBlobMountConfig(settings: Settings): {
   };
 }
 
-function azureBlobManifestEndpoint(endpoint: string | undefined, accountName: string): string | undefined {
+function azureBlobManifestEndpoint(
+  endpoint: string | undefined,
+  accountName: string,
+): string | undefined {
   if (!endpoint) {
     return undefined;
   }
@@ -3200,13 +4371,16 @@ function azureBlobManifestEndpoint(endpoint: string | undefined, accountName: st
 }
 
 function parseAzureConnectionString(value: string): Record<string, string> {
-  return Object.fromEntries(value.split(";")
-    .map((part) => part.trim())
-    .filter(Boolean)
-    .map((part) => {
-      const index = part.indexOf("=");
-      return index === -1 ? [part, ""] : [part.slice(0, index), part.slice(index + 1)];
-    }));
+  return Object.fromEntries(
+    value
+      .split(";")
+      .map((part) => part.trim())
+      .filter(Boolean)
+      .map((part) => {
+        const index = part.indexOf("=");
+        return index === -1 ? [part, ""] : [part.slice(0, index), part.slice(index + 1)];
+      }),
+  );
 }
 
 function normalizeManifestPath(path: string): string {
@@ -3222,7 +4396,9 @@ function normalizeSandboxFileDownloads(downloads: SandboxFileDownload[]): Sandbo
     const mountPath = normalizeManifestPath(download.mountPath);
     assertSafeSandboxFilename(download.filename, download.fileId);
     if (!download.content && !download.url?.trim()) {
-      throw new Error(`File download materialization requires content or a URL for ${download.fileId}`);
+      throw new Error(
+        `File download materialization requires content or a URL for ${download.fileId}`,
+      );
     }
     return {
       ...download,
@@ -3232,7 +4408,14 @@ function normalizeSandboxFileDownloads(downloads: SandboxFileDownload[]): Sandbo
 }
 
 function assertSafeSandboxFilename(filename: string, fileId: string): void {
-  if (!filename || filename.includes("/") || filename.includes("\\") || filename === "." || filename === ".." || filename.includes("..")) {
+  if (
+    !filename ||
+    filename.includes("/") ||
+    filename.includes("\\") ||
+    filename === "." ||
+    filename === ".." ||
+    filename.includes("..")
+  ) {
     throw new Error(`Invalid sandbox file name for ${fileId}: ${filename}`);
   }
 }
@@ -3248,11 +4431,11 @@ function sandboxFileDownloadCommand(download: SandboxFileDownload, targetPath: s
   const targetDir = posixPath.dirname(targetPath);
   const tmpPath = `${targetPath}.opengeni-download-$$`;
   return [
-    "set -euo pipefail",
+    "set -eu",
     `mkdir -p -- ${shellQuote(targetDir)}`,
     `if [ ! -f ${shellQuote(targetPath)} ]; then`,
     `  tmp=${shellQuote(tmpPath)}`,
-    "  cleanup() { rm -f -- \"$tmp\"; }",
+    '  cleanup() { rm -f -- "$tmp"; }',
     "  trap cleanup EXIT",
     `  curl --fail --location --silent --show-error --retry 3 --retry-delay 1 --output "$tmp" ${shellQuote(download.url)}`,
     `  mv -- "$tmp" ${shellQuote(targetPath)}`,
@@ -3266,47 +4449,36 @@ function shellQuote(value: string): string {
   return `'${value.replace(/'/g, "'\\''")}'`;
 }
 
-async function restoredSandboxSessionState(state: RunState<any, any>, client: unknown): Promise<SandboxSessionState | undefined> {
-  if (!client) {
-    return undefined;
-  }
-  const sandboxState = (state as any)._sandbox;
-  const entry = sandboxState?.sessionsByAgent?.[sandboxState.currentAgentKey]
-    ?? (sandboxState?.currentAgentKey && sandboxState?.sessionState
-      ? {
-        backendId: sandboxState.backendId,
-        currentAgentKey: sandboxState.currentAgentKey,
-        currentAgentName: sandboxState.currentAgentName,
-        sessionState: sandboxState.sessionState,
-      }
-      : undefined);
-  if (!entry) {
-    return undefined;
-  }
-  if ((client as SandboxClient).backendId !== entry.backendId) {
-    throw new Error("RunState sandbox backend does not match the configured sandbox client");
-  }
-  return await deserializeSandboxSessionStateEnvelope(client as SandboxClient, entry.sessionState);
-}
-
-// sandboxStateEntryFromRunState + restoredSandboxSessionStateFromEntry +
-// deserializeSandboxSessionStateEnvelope moved to the agent-loop-free leaf
-// ./sandbox; re-exported via `export * from "./sandbox"`. The private
-// restoredSandboxSessionState above (which takes an agent-loop RunState) calls
-// the moved deserializeSandboxSessionStateEnvelope, imported from ./sandbox.
-
 export type SandboxLifecycleHookPhase = "beforeAgentStart";
 
 export type SandboxLifecycleHookContext = {
   environment: Record<string, string>;
   onRuntimeEvent?: (event: NormalizedRuntimeEvent) => Promise<void> | void;
   runAs?: string;
-  // TOKEN-BROKER (B1): the run-scoped GitHub token to seed into the box's token
-  // FILE before the repository clone runs. Threaded OFF-MANIFEST — it rides ONLY
-  // the clone exec's per-call env (OPENGENI_GIT_TOKEN_SEED), NEVER the box/agent
-  // manifest env (validateNoEnvironmentDelta must never see a rotating value).
+  // TOKEN-BROKER (B1): back-compat GitHub alias for gitTokenSeeds.github.
   gitTokenSeed?: string;
+  // Provider tokens to seed into box token FILES before repository clone/setup
+  // runs. Threaded OFF-MANIFEST — they ride ONLY the setup exec command prefix,
+  // NEVER the box/agent manifest env (validateNoEnvironmentDelta must never see
+  // rotating values).
+  gitTokenSeeds?: GitTokenSeeds;
   toolspaceTokenSeed?: string;
+  // M3: the rig setup descriptor for the rig-setup hook (the script + marker
+  // version id + the rig's own timeout). Present only on a rig-bound turn.
+  rigSetup?: RigSetupDescriptor;
+};
+
+// M3: everything the rig-setup hook needs to run the frozen rig version's setup
+// script exactly once per box. `versionId` keys the idempotence marker
+// (/var/opengeni/rig-setup-<versionId>.done); `timeoutMs` is the rig-specific
+// budget (settings.rigSetupTimeoutMs), NOT the 120s lifecycle default; `rigName`
+// is for human-readable events/errors only.
+export type RigSetupDescriptor = {
+  rigId: string;
+  versionId: string;
+  rigName: string;
+  script: string;
+  timeoutMs: number;
 };
 
 export type SandboxLifecycleHook = {
@@ -3339,7 +4511,9 @@ function applicableBeforeAgentStartHooks(
   hooks: SandboxLifecycleHook[],
   context: SandboxLifecycleHookContext,
 ): SandboxLifecycleHook[] {
-  return hooks.filter((hook) => hook.phase === "beforeAgentStart" && (hook.shouldRun?.(context) ?? true));
+  return hooks.filter(
+    (hook) => hook.phase === "beforeAgentStart" && (hook.shouldRun?.(context) ?? true),
+  );
 }
 
 /**
@@ -3384,14 +4558,48 @@ export function withSandboxLifecycleHooks(
   };
   const wrapped: SandboxClient = {
     backendId: client.backendId,
-    ...(client.supportsDefaultOptions !== undefined ? { supportsDefaultOptions: client.supportsDefaultOptions } : {}),
-    ...(client.create ? { create: async (...args: any[]) => await wrapSession(await (client.create as any)(...args)) } : {}),
-    ...(client.resume ? { resume: async (state: SandboxSessionState) => await wrapSession(await client.resume!(state)) } : {}),
-    ...(client.delete ? { delete: async (state: SandboxSessionState) => await client.delete!(state) } : {}),
-    ...(client.serializeSessionState ? { serializeSessionState: async (state: SandboxSessionState, options) => await client.serializeSessionState!(state, options) } : {}),
-    ...(client.canPersistOwnedSessionState ? { canPersistOwnedSessionState: async (state: SandboxSessionState) => await client.canPersistOwnedSessionState!(state) } : {}),
-    ...(client.canReusePreservedOwnedSession ? { canReusePreservedOwnedSession: async (state: SandboxSessionState) => await client.canReusePreservedOwnedSession!(state) } : {}),
-    ...(client.deserializeSessionState ? { deserializeSessionState: async (state: Record<string, unknown>) => await client.deserializeSessionState!(state) } : {}),
+    ...(client.supportsDefaultOptions !== undefined
+      ? { supportsDefaultOptions: client.supportsDefaultOptions }
+      : {}),
+    ...(client.create
+      ? {
+          create: async (...args: any[]) =>
+            await wrapSession(await (client.create as any)(...args)),
+        }
+      : {}),
+    ...(client.resume
+      ? {
+          resume: async (state: SandboxSessionState) =>
+            await wrapSession(await client.resume!(state)),
+        }
+      : {}),
+    ...(client.delete
+      ? { delete: async (state: SandboxSessionState) => await client.delete!(state) }
+      : {}),
+    ...(client.serializeSessionState
+      ? {
+          serializeSessionState: async (state: SandboxSessionState, options) =>
+            await client.serializeSessionState!(state, options),
+        }
+      : {}),
+    ...(client.canPersistOwnedSessionState
+      ? {
+          canPersistOwnedSessionState: async (state: SandboxSessionState) =>
+            await client.canPersistOwnedSessionState!(state),
+        }
+      : {}),
+    ...(client.canReusePreservedOwnedSession
+      ? {
+          canReusePreservedOwnedSession: async (state: SandboxSessionState) =>
+            await client.canReusePreservedOwnedSession!(state),
+        }
+      : {}),
+    ...(client.deserializeSessionState
+      ? {
+          deserializeSessionState: async (state: Record<string, unknown>) =>
+            await client.deserializeSessionState!(state),
+        }
+      : {}),
   };
   return wrapped;
 }
@@ -3403,8 +4611,8 @@ function sandboxRepositoryCloneHooksForAgent(agent: Agent<any, any>): SandboxLif
 // TOKEN-BROKER (B1): the per-turn git token seed stashed for this agent (undefined
 // when no repo is attached / on the selfhosted path). Read into the clone hook
 // context at runStream so the token is seeded off-manifest.
-function gitTokenSeedForAgent(agent: Agent<any, any>): string | undefined {
-  return agentGitTokenSeed.get(agent);
+function gitTokenSeedsForAgent(agent: Agent<any, any>): GitTokenSeeds | undefined {
+  return agentGitTokenSeeds.get(agent);
 }
 
 function toolspaceTokenSeedForAgent(agent: Agent<any, any>): string | undefined {
@@ -3413,11 +4621,70 @@ function toolspaceTokenSeedForAgent(agent: Agent<any, any>): string | undefined
 
 function sandboxToolspaceTokenHooksForAgent(agent: Agent<any, any>): SandboxLifecycleHook[] {
   return toolspaceTokenSeedForAgent(agent)
-    ? [{
-        id: "toolspace-token",
-        phase: "beforeAgentStart",
-        run: runToolspaceTokenSeedHook,
-      }]
+    ? [
+        {
+          id: "toolspace-token",
+          phase: "beforeAgentStart",
+          run: runToolspaceTokenSeedHook,
+        },
+      ]
+    : [];
+}
+
+// M3: the rig-setup hook for this agent (present only on a rig-bound turn whose
+// frozen version carries a non-empty setup script). It runs FIRST among the
+// owned beforeAgentStart hooks so any tooling it installs is available to the
+// repository-clone / credential hooks that follow. The descriptor is threaded
+// through the hook context (rigSetupHookContext) so runRigSetupHook reads it.
+function sandboxRigSetupHooksForAgent(agent: Agent<any, any>): SandboxLifecycleHook[] {
+  return agentRigSetup.get(agent)
+    ? [
+        {
+          id: "rig-setup",
+          phase: "beforeAgentStart",
+          run: runRigSetupHook,
+        },
+      ]
+    : [];
+}
+
+function rigSetupDescriptorForAgent(agent: Agent<any, any>): RigSetupDescriptor | undefined {
+  return agentRigSetup.get(agent);
+}
+
+// M3: the rig version's credential hooks (already resolved + validated at build
+// time). Unioned with the deployment preparation-profile hooks by the caller.
+function rigCredentialHooksForAgent(agent: Agent<any, any>): SandboxLifecycleHook[] {
+  return agentRigCredentialHooks.get(agent) ?? [];
+}
+
+// M3: union the deployment preparation-profile hooks with the rig version's
+// credential hooks, deduped by id (a hook named by BOTH the deployment profile
+// and the rig runs once). Deployment hooks keep their leading position.
+function unionCredentialHooks(
+  deploymentHooks: SandboxLifecycleHook[],
+  rigHooks: SandboxLifecycleHook[],
+): SandboxLifecycleHook[] {
+  if (rigHooks.length === 0) {
+    return deploymentHooks;
+  }
+  const seen = new Set(deploymentHooks.map((hook) => hook.id));
+  return [...deploymentHooks, ...rigHooks.filter((hook) => !seen.has(hook.id))];
+}
+
+function gitCredentialSessionRegistrationHooks(
+  callback: RunAgentStreamOptions["onGitCredentialSessionReady"],
+): SandboxLifecycleHook[] {
+  return callback
+    ? [
+        {
+          id: "git-credential-renewal-registration",
+          phase: "beforeAgentStart",
+          run: async (session) => {
+            await callback(session);
+          },
+        },
+      ]
     : [];
 }
 
@@ -3426,19 +4693,23 @@ function sandboxRepositoryCloneHooks(
   resources: ResourceRef[],
   activeSandboxBackend: Settings["sandboxBackend"] = settings.sandboxBackend,
 ): SandboxLifecycleHook[] {
-  const repositories = resources.filter((resource): resource is Extract<ResourceRef, { kind: "repository" }> => (
-    resource.kind === "repository" && repositoryUsesSandboxClone(settings, resource, activeSandboxBackend)
-  ));
+  const repositories = resources.filter(
+    (resource): resource is Extract<ResourceRef, { kind: "repository" }> =>
+      resource.kind === "repository" &&
+      repositoryUsesSandboxClone(settings, resource, activeSandboxBackend),
+  );
   if (repositories.length === 0) {
     return [];
   }
-  return [{
-    id: "repository-clone",
-    phase: "beforeAgentStart",
-    run: async (session, context) => {
-      await runRepositoryCloneHook(session, repositories, context);
+  return [
+    {
+      id: "repository-clone",
+      phase: "beforeAgentStart",
+      run: async (session, context) => {
+        await runRepositoryCloneHook(session, repositories, context);
+      },
     },
-  }];
+  ];
 }
 
 /**
@@ -3467,60 +4738,273 @@ export function repositoryUsesSandboxClone(
   if (activeSandboxBackend === "selfhosted") {
     return false;
   }
-  return settings.sandboxBackend === "modal" || Boolean(resource.githubInstallationId && resource.githubRepositoryId);
+  return (
+    settings.sandboxBackend === "modal" ||
+    Boolean(resource.githubInstallationId && resource.githubRepositoryId) ||
+    Boolean(resource.provider)
+  );
 }
 
-export function repositoryCloneCommand(resources: Extract<ResourceRef, { kind: "repository" }>[]): string {
-  const commands = [
-    "set -eu",
-    "export HOME=\"${HOME:-/workspace}\"",
-    "export GIT_TERMINAL_PROMPT=\"${GIT_TERMINAL_PROMPT:-0}\"",
-    // TOKEN-BROKER (B1/B2): seed the run-scoped GitHub token into the STABLE token FILE
-    // AND provision the git-askpass helper into the box AT SETUP (runtime) BEFORE any
-    // clone runs, so GIT_ASKPASS points at a per-box, user-writable script that reads
-    // that file for the fetch below. Provisioning the askpass here (rather than relying
-    // on a baked image script at /usr/local/bin/opengeni-git-askpass) removes the
-    // image-rebuild rollout gate: the askpass is correct on ANY box image, including
-    // pre-existing warm boxes on their next turn's clone hook, and no product image has
-    // to carry it. The seed rides the per-exec env (OPENGENI_GIT_TOKEN_SEED) — NEVER the
-    // box/agent manifest (validateNoEnvironmentDelta must not see a rotating value), so
-    // this whole block is a no-op when the seed is absent (e.g. the selfhosted path,
-    // which uses its own git creds). The token file lives at $OPENGENI_GIT_TOKEN_FILE
-    // (stable, from the shared base) with a $HOME/.opengeni/git-token fallback.
-    // $GIT_ASKPASS is on the box manifest env (set by
-    // sandboxEnvironmentForRun to $HOME/.opengeni/askpass), so it is available to this
-    // exec; the askpass script we write is byte-identical to docker/opengeni-git-askpass
-    // and is written via a QUOTED heredoc (<<'ASKPASS_EOF') so NOTHING inside it expands
-    // ($1, $HOME, ${OPENGENI_GIT_TOKEN_FILE:-...}, and the literal \n in printf all land
-    // verbatim), then chmod 0755 so git can exec it.
-    //
-    // ATOMIC REWRITE: this block now re-runs at the start of EVERY turn on a warm box
-    // that other turn holders may be actively using — an in-flight `git fetch` from a
-    // concurrent turn can invoke the askpass (which cats the token file) at any moment.
-    // Both files are therefore written to a pid-suffixed temp under umask 077 and
-    // renamed into place: rename is atomic, concurrent readers keep the old inode, and
-    // the token is never observable world-readable (no post-hoc chmod window).
-    "if [ -n \"${OPENGENI_GIT_TOKEN_SEED:-}\" ]; then",
-    "  seed_umask=\"$(umask)\"",
-    "  umask 077",
-    "  git_token_file=\"${OPENGENI_GIT_TOKEN_FILE:-$HOME/.opengeni/git-token}\"",
-    "  mkdir -p \"$(dirname \"$git_token_file\")\"",
-    "  printf '%s' \"$OPENGENI_GIT_TOKEN_SEED\" > \"$git_token_file.tmp.$$\"",
-    "  mv -f \"$git_token_file.tmp.$$\" \"$git_token_file\"",
-    "  git_askpass=\"${GIT_ASKPASS:-$HOME/.opengeni/askpass}\"",
-    "  mkdir -p \"$(dirname \"$git_askpass\")\"",
-    "  cat > \"$git_askpass.tmp.$$\" <<'ASKPASS_EOF'",
+const GIT_CREDENTIAL_PROVIDERS = [
+  "github",
+  "gitlab",
+  "azure_devops",
+] as const satisfies readonly GitCredentialProvider[];
+
+function gitProviderSeedEnv(provider: GitCredentialProvider): string {
+  return `OPENGENI_GIT_${provider.toUpperCase()}_TOKEN_SEED`;
+}
+
+function gitTokenSeedExportPrefix(seeds: GitTokenSeeds): string {
+  const lines: string[] = [];
+  for (const provider of GIT_CREDENTIAL_PROVIDERS) {
+    const token = seeds[provider];
+    if (!token) {
+      continue;
+    }
+    lines.push(`export ${gitProviderSeedEnv(provider)}=${shellQuote(token)}`);
+    if (provider === "github") {
+      lines.push(`export OPENGENI_GIT_TOKEN_SEED=${shellQuote(token)}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+function repositoryCredentialProvider(
+  resource: Extract<ResourceRef, { kind: "repository" }>,
+): GitCredentialProvider {
+  return resource.provider ?? "github";
+}
+
+function gitAskpassHostProviderCaseLines(
+  resources: Extract<ResourceRef, { kind: "repository" }>[],
+): string[] {
+  const hosts = new Map<string, GitCredentialProvider>();
+  for (const resource of resources) {
+    try {
+      const hostname = new URL(resource.uri).hostname.toLowerCase();
+      if (!hostname) {
+        continue;
+      }
+      hosts.set(hostname, repositoryCredentialProvider(resource));
+    } catch {
+      // Resource validation catches invalid URIs before normal runtime use. Keep
+      // helper generation tolerant so tests for clone failure can still build.
+    }
+  }
+  return [...hosts.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(
+      ([hostname, provider]) =>
+        `    ${shellQuote(hostname)}) printf '%s\\n' ${provider}; return 0 ;;`,
+    );
+}
+
+function gitCredentialTokenWriterCommandLines(): string[] {
+  return [
+    // TOKEN-BROKER (B1/B2): seed run-scoped provider tokens into stable files and
+    // atomically replace each provider file. Token VALUES are supplied only by
+    // the per-exec command prefix
+    // (OPENGENI_GIT_*_TOKEN_SEED), never by the box/agent manifest. Helper paths
+    // are stable manifest values from @opengeni/config.
+    "git_provider_token_file() {",
+    '  provider="$1"',
+    '  case "$provider" in',
+    "    github) printf '%s\\n' \"${OPENGENI_GIT_TOKEN_FILE:-$HOME/.opengeni/git-token}\" ;;",
+    "    *) printf '%s\\n' \"${OPENGENI_GIT_CREDENTIALS_DIR:-$HOME/.opengeni/git-credentials}/$provider-token\" ;;",
+    "  esac",
+    "}",
+    "write_git_provider_token() {",
+    '  provider="$1"',
+    '  token="$2"',
+    '  [ -n "$token" ] || return 0',
+    '  token_file="$(git_provider_token_file "$provider")"',
+    '  mkdir -p "$(dirname "$token_file")"',
+    '  printf \'%s\' "$token" > "$token_file.tmp.$$"',
+    '  mv -f "$token_file.tmp.$$" "$token_file"',
+    '  if [ "$provider" = github ]; then',
+    '    credential_dir="${OPENGENI_GIT_CREDENTIALS_DIR:-$HOME/.opengeni/git-credentials}"',
+    '    mkdir -p "$credential_dir"',
+    '    printf \'%s\' "$token" > "$credential_dir/github-token.tmp.$$"',
+    '    mv -f "$credential_dir/github-token.tmp.$$" "$credential_dir/github-token"',
+    "  fi",
+    "}",
+    'seed_umask="$(umask)"',
+    "umask 077",
+    'write_git_provider_token github "${OPENGENI_GIT_GITHUB_TOKEN_SEED:-${OPENGENI_GIT_TOKEN_SEED:-}}"',
+    'write_git_provider_token gitlab "${OPENGENI_GIT_GITLAB_TOKEN_SEED:-}"',
+    'write_git_provider_token azure_devops "${OPENGENI_GIT_AZURE_DEVOPS_TOKEN_SEED:-}"',
+    'umask "$seed_umask"',
+  ];
+}
+
+function gitCredentialHelperCommandLines(
+  resources: Extract<ResourceRef, { kind: "repository" }>[] = [],
+): string[] {
+  const hostProviderCases = gitAskpassHostProviderCaseLines(resources);
+  return [
+    ...gitCredentialTokenWriterCommandLines(),
+    // Provision git/provider-CLI helpers at SETUP (runtime) before any clone
+    // runs. Renewal updates only token files and deliberately leaves these
+    // repository-specific host mappings intact.
+    'git_askpass="${GIT_ASKPASS:-$HOME/.opengeni/askpass}"',
+    'mkdir -p "$(dirname "$git_askpass")"',
+    "cat > \"$git_askpass.tmp.$$\" <<'ASKPASS_EOF'",
     "#!/usr/bin/env sh",
-    "case \"$1\" in",
-    "  *Username*) printf '%s\\n' \"x-access-token\" ;;",
-    "  *Password*) cat \"${OPENGENI_GIT_TOKEN_FILE:-$HOME/.opengeni/git-token}\" 2>/dev/null || printf '\\n' ;;",
+    "prompt_host() {",
+    "  prompt_lower=\"$(printf '%s\\n' \"$1\" | tr '[:upper:]' '[:lower:]')\"",
+    '  case "$prompt_lower" in',
+    "    *://*) ;;",
+    "    *) printf '\\n'; return 0 ;;",
+    "  esac",
+    '  rest="${prompt_lower#*://}"',
+    '  rest="${rest#*@}"',
+    '  host="${rest%%/*}"',
+    '  host="${host%%:*}"',
+    '  host="$(printf \'%s\\n\' "$host" | tr -d "\'")"',
+    "  printf '%s\\n' \"$host\"",
+    "}",
+    "provider_for_prompt() {",
+    '  host="$(prompt_host "$1")"',
+    '  case "$host" in',
+    ...(hostProviderCases.length > 0 ? hostProviderCases : ['    "") : ;;']),
+    "  esac",
+    "  case \"$(printf '%s\\n' \"$1\" | tr '[:upper:]' '[:lower:]')\" in",
+    "    *github.com*|*githubusercontent.com*) printf '%s\\n' github ;;",
+    "    *gitlab*) printf '%s\\n' gitlab ;;",
+    "    *dev.azure.com*|*.visualstudio.com*) printf '%s\\n' azure_devops ;;",
+    "    *) printf '%s\\n' github ;;",
+    "  esac",
+    "}",
+    "token_file_for_provider() {",
+    '  case "$1" in',
+    "    github) printf '%s\\n' \"${OPENGENI_GIT_TOKEN_FILE:-$HOME/.opengeni/git-token}\" ;;",
+    "    *) printf '%s\\n' \"${OPENGENI_GIT_CREDENTIALS_DIR:-$HOME/.opengeni/git-credentials}/$1-token\" ;;",
+    "  esac",
+    "}",
+    "username_for_provider() {",
+    '  case "$1" in',
+    "    github) printf '%s\\n' \"x-access-token\" ;;",
+    "    gitlab) printf '%s\\n' \"oauth2\" ;;",
+    "    azure_devops) printf '%s\\n' \"opengeni\" ;;",
+    "    *) printf '\\n' ;;",
+    "  esac",
+    "}",
+    'provider="$(provider_for_prompt "$1")"',
+    'case "$1" in',
+    '  *Username*) username_for_provider "$provider" ;;',
+    '  *Password*) cat "$(token_file_for_provider "$provider")" 2>/dev/null || printf \'\\n\' ;;',
     "  *) printf '\\n' ;;",
     "esac",
     "ASKPASS_EOF",
-    "  chmod 0755 \"$git_askpass.tmp.$$\"",
-    "  mv -f \"$git_askpass.tmp.$$\" \"$git_askpass\"",
-    "  umask \"$seed_umask\"",
+    'chmod 0755 "$git_askpass.tmp.$$"',
+    'mv -f "$git_askpass.tmp.$$" "$git_askpass"',
+    'wrapper_dir="${OPENGENI_GIT_CLI_WRAPPER_DIR:-$HOME/.opengeni/bin}"',
+    'mkdir -p "$wrapper_dir"',
+    "for opengeni_git_cli_tool in gh glab az; do",
+    '  wrapper="$wrapper_dir/$opengeni_git_cli_tool"',
+    "  cat > \"$wrapper.tmp.$$\" <<'CLI_WRAPPER_EOF'",
+    "#!/usr/bin/env sh",
+    "set -eu",
+    'tool="${0##*/}"',
+    'case "$tool" in',
+    "  gh) provider=github; token_env=GH_TOKEN ;;",
+    "  glab) provider=gitlab; token_env=GITLAB_TOKEN ;;",
+    "  az) provider=azure_devops; token_env=AZURE_DEVOPS_EXT_PAT ;;",
+    "  *) provider=; token_env= ;;",
+    "esac",
+    'if [ -n "$provider" ]; then',
+    '  case "$provider" in',
+    '    github) token_file="${OPENGENI_GIT_TOKEN_FILE:-$HOME/.opengeni/git-token}" ;;',
+    '    *) token_file="${OPENGENI_GIT_CREDENTIALS_DIR:-$HOME/.opengeni/git-credentials}/$provider-token" ;;',
+    "  esac",
+    '  if [ -f "$token_file" ]; then',
+    '    token="$(cat "$token_file" 2>/dev/null || true)"',
+    '    if [ -n "$token" ]; then',
+    '      case "$token_env" in',
+    '        GH_TOKEN) export GH_TOKEN="$token" ;;',
+    '        GITLAB_TOKEN) export GITLAB_TOKEN="$token" ;;',
+    '        AZURE_DEVOPS_EXT_PAT) export AZURE_DEVOPS_EXT_PAT="$token" ;;',
+    "      esac",
+    "    fi",
+    "  fi",
     "fi",
+    'self_real="$(readlink -f "$0" 2>/dev/null || printf \'%s\\n\' "$0")"',
+    'old_ifs="$IFS"',
+    "IFS=:",
+    "for dir in $PATH; do",
+    '  [ -n "$dir" ] || dir=.',
+    '  candidate="$dir/$tool"',
+    '  [ -x "$candidate" ] || continue',
+    '  candidate_real="$(readlink -f "$candidate" 2>/dev/null || printf \'%s\\n\' "$candidate")"',
+    '  [ "$candidate_real" = "$self_real" ] && continue',
+    '  IFS="$old_ifs"',
+    '  exec "$candidate" "$@"',
+    "done",
+    'IFS="$old_ifs"',
+    "printf '%s\\n' \"$tool: real command not found on PATH\" >&2",
+    "exit 127",
+    "CLI_WRAPPER_EOF",
+    '  chmod 0755 "$wrapper.tmp.$$"',
+    '  mv -f "$wrapper.tmp.$$" "$wrapper"',
+    "done",
+  ];
+}
+
+/**
+ * Build the off-manifest command used to atomically replace provider token files.
+ *
+ * Token values exist only in this one sandbox exec command. The stable askpass
+ * and provider-CLI wrappers always read the files at invocation time, so an
+ * in-flight multi-day turn observes the replacement without changing its
+ * manifest environment or rebuilding the sandbox.
+ */
+export function gitProviderTokenRefreshCommand(seeds: GitTokenSeeds): string {
+  const seedPrefix = gitTokenSeedExportPrefix(seeds);
+  if (!seedPrefix) {
+    return "";
+  }
+  return [
+    seedPrefix,
+    "set -eu",
+    'export HOME="${HOME:-/workspace}"',
+    ...gitCredentialTokenWriterCommandLines(),
+  ].join("\n");
+}
+
+export async function refreshGitProviderTokenFiles(
+  session: GitCredentialTokenWriterSession,
+  seeds: GitTokenSeeds,
+  options: { runAs?: string } = {},
+): Promise<void> {
+  const command = gitProviderTokenRefreshCommand(seeds);
+  if (!command) {
+    return;
+  }
+  const args = {
+    cmd: command,
+    workdir: "/workspace",
+    ...(options.runAs ? { runAs: options.runAs } : {}),
+    yieldTimeMs: SANDBOX_LIFECYCLE_COMMAND_TIMEOUT_MS,
+    maxOutputTokens: 4_000,
+  };
+  if (session.exec) {
+    assertSandboxCommandSucceeded(await session.exec(args), "Git credential refresh");
+  } else if (session.execCommand) {
+    assertSandboxCommandSucceeded(await session.execCommand(args), "Git credential refresh");
+  } else {
+    throw new Error("Sandbox session does not support command execution");
+  }
+}
+
+export function repositoryCloneCommand(
+  resources: Extract<ResourceRef, { kind: "repository" }>[],
+): string {
+  const commands = [
+    "set -eu",
+    'export HOME="${HOME:-/workspace}"',
+    'export GIT_TERMINAL_PROMPT="${GIT_TERMINAL_PROMPT:-0}"',
+    ...gitCredentialHelperCommandLines(resources),
     "ensure_git() {",
     "  if command -v git >/dev/null 2>&1; then",
     "    return 0",
@@ -3532,16 +5016,16 @@ export function repositoryCloneCommand(resources: Extract<ResourceRef, { kind: "
     "    rm -rf /var/lib/apt/lists/*",
     "    command -v git >/dev/null 2>&1 && return 0",
     "  fi",
-    "  echo \"git is not installed in the sandbox and could not be bootstrapped\" >&2",
+    '  echo "git is not installed in the sandbox and could not be bootstrapped" >&2',
     "  exit 127",
     "}",
     "ensure_git",
     "clone_repository() {",
-    "  target=\"$1\"",
-    "  uri=\"$2\"",
-    "  ref=\"$3\"",
-    "  subpath=\"$4\"",
-    "  if [ -e \"$target\" ] && { [ -f \"$target\" ] || [ -n \"$(find \"$target\" -mindepth 1 -maxdepth 1 -print -quit 2>/dev/null)\" ]; }; then",
+    '  target="$1"',
+    '  uri="$2"',
+    '  ref="$3"',
+    '  subpath="$4"',
+    '  if [ -e "$target" ] && { [ -f "$target" ] || [ -n "$(find "$target" -mindepth 1 -maxdepth 1 -print -quit 2>/dev/null)" ]; }; then',
     // This hook re-runs every turn on a long-lived box, so \"non-empty\" alone is not
     // proof of a completed materialization: an interrupted clone (worker crash /
     // lifecycle timeout mid-mv/cp) leaves a partial tree that would otherwise pass
@@ -3549,75 +5033,77 @@ export function repositoryCloneCommand(resources: Extract<ResourceRef, { kind: "
     // skipped; a partial one is wiped and rebuilt (nothing legitimate writes under
     // the mount path before the repo exists). Subpath extracts are not git repos —
     // for those the plain non-empty check stands (no stronger signal available).
-    "    if [ -n \"$subpath\" ] || git -C \"$target\" rev-parse --is-inside-work-tree >/dev/null 2>&1; then",
-    "      echo \"Repository resource already present at $target\"",
+    '    if [ -n "$subpath" ] || git -C "$target" rev-parse --is-inside-work-tree >/dev/null 2>&1; then',
+    '      echo "Repository resource already present at $target"',
     "      return 0",
     "    fi",
-    "    echo \"Re-materializing partial repository resource at $target\" >&2",
-    "    find \"$target\" -mindepth 1 -maxdepth 1 -exec rm -rf {} +",
+    '    echo "Re-materializing partial repository resource at $target" >&2',
+    '    find "$target" -mindepth 1 -maxdepth 1 -exec rm -rf {} +',
     "  fi",
-    "  mkdir -p \"$(dirname \"$target\")\"",
-    "  tmp=\"${target}.tmp.$$\"",
-    "  rm -rf \"$tmp\"",
+    '  mkdir -p "$(dirname "$target")"',
+    '  tmp="${target}.tmp.$$"',
+    '  rm -rf "$tmp"',
     // Fetch failures must not leak the pid-suffixed tmp clone beside the mount
     // (set -eu would exit before any cleanup).
-    "  if ! { git init \"$tmp\" >/dev/null && git -C \"$tmp\" remote add origin \"$uri\" && git -C \"$tmp\" fetch --depth 1 --no-tags --filter=blob:none origin \"$ref\" && git -C \"$tmp\" checkout --detach FETCH_HEAD >/dev/null; }; then",
-    "    rm -rf \"$tmp\"",
-    "    echo \"Repository resource fetch failed for $target\" >&2",
+    '  if ! { git init "$tmp" >/dev/null && git -C "$tmp" remote add origin "$uri" && git -C "$tmp" fetch --depth 1 --no-tags --filter=blob:none origin "$ref" && git -C "$tmp" checkout --detach FETCH_HEAD >/dev/null; }; then',
+    '    rm -rf "$tmp"',
+    '    echo "Repository resource fetch failed for $target" >&2',
     "    exit 1",
     "  fi",
-    "  if [ -n \"$subpath\" ]; then",
-    "    if [ ! -e \"$tmp/$subpath\" ]; then",
-    "      echo \"Repository subpath not found: $subpath\" >&2",
-    "      rm -rf \"$tmp\"",
+    '  if [ -n "$subpath" ]; then',
+    '    if [ ! -e "$tmp/$subpath" ]; then',
+    '      echo "Repository subpath not found: $subpath" >&2',
+    '      rm -rf "$tmp"',
     "      exit 1",
     "    fi",
-    "    if [ -d \"$tmp/$subpath\" ]; then",
-    "      mkdir -p \"$target\"",
-    "      cp -a \"$tmp/$subpath/.\" \"$target/\"",
+    '    if [ -d "$tmp/$subpath" ]; then',
+    '      mkdir -p "$target"',
+    '      cp -a "$tmp/$subpath/." "$target/"',
     "    else",
-    "      rmdir \"$target\" 2>/dev/null || true",
-    "      cp -a \"$tmp/$subpath\" \"$target\"",
+    '      rmdir "$target" 2>/dev/null || true',
+    '      cp -a "$tmp/$subpath" "$target"',
     "    fi",
-    "    rm -rf \"$tmp\"",
+    '    rm -rf "$tmp"',
     "  else",
-    "    rmdir \"$target\" 2>/dev/null || true",
+    '    rmdir "$target" 2>/dev/null || true',
     // Two concurrent turn holders can race this install: without the existence
     // re-check the loser's un-flagged `mv` would nest its tmp clone INSIDE the
     // winner's tree as <name>.tmp.<pid>. If the winner produced a valid work tree,
     // accept it; a non-empty non-repo survivor here is a mount point the manifest
     // re-filled — install into it by content copy instead of rename.
-    "    if [ -e \"$target\" ]; then",
-    "      if git -C \"$target\" rev-parse --is-inside-work-tree >/dev/null 2>&1; then",
-    "        rm -rf \"$tmp\"",
-    "        echo \"Repository resource already present at $target\"",
+    '    if [ -e "$target" ]; then',
+    '      if git -C "$target" rev-parse --is-inside-work-tree >/dev/null 2>&1; then',
+    '        rm -rf "$tmp"',
+    '        echo "Repository resource already present at $target"',
     "        return 0",
     "      fi",
-    "      cp -a \"$tmp/.\" \"$target/\"",
-    "      rm -rf \"$tmp\"",
+    '      cp -a "$tmp/." "$target/"',
+    '      rm -rf "$tmp"',
     "    else",
-    "      mv \"$tmp\" \"$target\"",
+    '      mv "$tmp" "$target"',
     "    fi",
-    "    git -C \"$target\" rev-parse --is-inside-work-tree >/dev/null",
+    '    git -C "$target" rev-parse --is-inside-work-tree >/dev/null',
     "  fi",
-    "  if [ ! -e \"$target\" ]; then",
-    "    echo \"Repository resource was not materialized at $target\" >&2",
+    '  if [ ! -e "$target" ]; then',
+    '    echo "Repository resource was not materialized at $target" >&2',
     "    exit 1",
     "  fi",
-    "  echo \"Repository resource ready at $target\"",
+    '  echo "Repository resource ready at $target"',
     "}",
   ];
   for (const resource of resources) {
     const url = new URL(resource.uri);
     const repo = url.pathname.replace(/^\/+|\/+$/g, "").replace(/\.git$/, "");
     const mountPath = normalizeManifestPath(resource.mountPath ?? `repos/${repo}`);
-    commands.push([
-      "clone_repository",
-      shellQuote(posixPath.join("/workspace", mountPath)),
-      shellQuote(resource.uri),
-      shellQuote(resource.ref),
-      shellQuote(resource.subpath ? normalizeManifestPath(resource.subpath) : ""),
-    ].join(" "));
+    commands.push(
+      [
+        "clone_repository",
+        shellQuote(posixPath.join("/workspace", mountPath)),
+        shellQuote(resource.uri),
+        shellQuote(resource.ref),
+        shellQuote(resource.subpath ? normalizeManifestPath(resource.subpath) : ""),
+      ].join(" "),
+    );
   }
   return commands.join("\n");
 }
@@ -3625,15 +5111,15 @@ export function repositoryCloneCommand(resources: Extract<ResourceRef, { kind: "
 export function toolspaceTokenSeedCommand(): string {
   return [
     "set -eu",
-    "export HOME=\"${HOME:-/workspace}\"",
-    "if [ -n \"${OPENGENI_TOOLSPACE_TOKEN_SEED:-}\" ]; then",
-    "  seed_umask=\"$(umask)\"",
+    'export HOME="${HOME:-/workspace}"',
+    'if [ -n "${OPENGENI_TOOLSPACE_TOKEN_SEED:-}" ]; then',
+    '  seed_umask="$(umask)"',
     "  umask 077",
-    "  token_file=\"${OPENGENI_TOOLSPACE_TOKEN_FILE:-$HOME/.opengeni/toolspace-token}\"",
-    "  mkdir -p \"$(dirname \"$token_file\")\"",
-    "  printf '%s' \"$OPENGENI_TOOLSPACE_TOKEN_SEED\" > \"$token_file.tmp.$$\"",
-    "  mv -f \"$token_file.tmp.$$\" \"$token_file\"",
-    "  umask \"$seed_umask\"",
+    '  token_file="${OPENGENI_TOOLSPACE_TOKEN_FILE:-$HOME/.opengeni/toolspace-token}"',
+    '  mkdir -p "$(dirname "$token_file")"',
+    '  printf \'%s\' "$OPENGENI_TOOLSPACE_TOKEN_SEED" > "$token_file.tmp.$$"',
+    '  mv -f "$token_file.tmp.$$" "$token_file"',
+    '  umask "$seed_umask"',
     "fi",
   ].join("\n");
 }
@@ -3669,6 +5155,165 @@ export async function runToolspaceTokenSeedHook(
   }
 }
 
+// Bounds the setup output tail carried on a rig.setup failure event/error so a
+// runaway script can't bloat the session's event stream or the turn error.
+const RIG_SETUP_OUTPUT_TAIL_LIMIT = 4_000;
+
+// A distinctive sentinel the guard prints when the idempotence marker already
+// exists, so the runtime can tell a SKIP from an actual run without a second
+// exec round-trip.
+const RIG_SETUP_SKIPPED_SENTINEL = "__OPENGENI_RIG_SETUP_SKIPPED__";
+
+/**
+ * The rig-setup command (M3). One idempotent bash program:
+ *   1. `mkdir -p /var/opengeni` and, if the per-version marker already exists,
+ *      print the SKIP sentinel and exit 0 (a warm box re-running the hook).
+ *   2. otherwise atomically claim a per-version lock directory. A loser waits
+ *      for the winner's marker, then skips; if the winner fails and releases the
+ *      lock, the loser retries the claim.
+ *   3. the winner writes the rig's setup script to a temp file and runs it under
+ *      coreutils `timeout` (NOT `bash -e` — the script opts into `set -e`
+ *      itself if it wants), then captures the exit code and `touch`es the marker
+ *      ONLY on success (exit 0) so a failed/timed-out setup re-runs next turn.
+ * The heredoc delimiter is quoted, so the script content is executed verbatim
+ * with no host-side expansion.
+ */
+export function rigSetupScriptCommand(
+  script: string,
+  versionId: string,
+  timeoutMs = 600_000,
+  markerRoot = "/var/opengeni",
+): string {
+  const timeoutSecs = Math.max(1, Math.ceil(timeoutMs / 1000));
+  const lockWaitSecs = timeoutSecs + 6;
+  const marker = `${markerRoot.replace(/\/+$/, "")}/rig-setup-${versionId}.done`;
+  return [
+    "set -u",
+    `mkdir -p ${shellQuote(markerRoot)}`,
+    `__OG_RIG_MARKER=${shellQuote(marker)}`,
+    '__OG_RIG_LOCK="$__OG_RIG_MARKER.lock"',
+    `__OG_RIG_TIMEOUT_SECS=${timeoutSecs}`,
+    `__OG_RIG_LOCK_WAIT_SECS=${lockWaitSecs}`,
+    `if [ -f "$__OG_RIG_MARKER" ]; then printf '%s\\n' ${shellQuote(RIG_SETUP_SKIPPED_SENTINEL)}; exit 0; fi`,
+    "while :; do",
+    '  if mkdir "$__OG_RIG_LOCK" 2>/dev/null; then',
+    "    trap 'rm -rf \"$__OG_RIG_LOCK\"' EXIT",
+    `    if [ -f "$__OG_RIG_MARKER" ]; then printf '%s\\n' ${shellQuote(RIG_SETUP_SKIPPED_SENTINEL)}; exit 0; fi`,
+    '__OG_RIG_SCRIPT="$(mktemp)"',
+    "cat > \"$__OG_RIG_SCRIPT\" <<'__OPENGENI_RIG_SETUP_SCRIPT_EOF__'",
+    script,
+    "__OPENGENI_RIG_SETUP_SCRIPT_EOF__",
+    '    timeout -k 5s "${__OG_RIG_TIMEOUT_SECS}s" bash "$__OG_RIG_SCRIPT"',
+    "__OG_RIG_RC=$?",
+    '    rm -f "$__OG_RIG_SCRIPT"',
+    '    if [ "$__OG_RIG_RC" -eq 0 ]; then touch "$__OG_RIG_MARKER"; fi',
+    '    exit "$__OG_RIG_RC"',
+    "  fi",
+    "  __OG_RIG_WAITED=0",
+    '  while [ "$__OG_RIG_WAITED" -lt "$__OG_RIG_LOCK_WAIT_SECS" ]; do',
+    `    if [ -f "$__OG_RIG_MARKER" ]; then printf '%s\\n' ${shellQuote(RIG_SETUP_SKIPPED_SENTINEL)}; exit 0; fi`,
+    '    if [ ! -d "$__OG_RIG_LOCK" ]; then break; fi',
+    "    sleep 1",
+    "    __OG_RIG_WAITED=$((__OG_RIG_WAITED + 1))",
+    "  done",
+    `  if [ -f "$__OG_RIG_MARKER" ]; then printf '%s\\n' ${shellQuote(RIG_SETUP_SKIPPED_SENTINEL)}; exit 0; fi`,
+    '  if [ ! -d "$__OG_RIG_LOCK" ]; then continue; fi',
+    '  rmdir "$__OG_RIG_LOCK" 2>/dev/null || true',
+    "done",
+  ].join("\n");
+}
+
+/**
+ * The rig-setup beforeAgentStart hook (M3). Runs the frozen rig version's setup
+ * script exactly once per box (marker-guarded), under the RIG's own timeout
+ * (context.rigSetup.timeoutMs, NOT the 120s lifecycle default). Emits
+ * rig.setup.started, then one terminal event:
+ *   - rig.setup.skipped   — marker already present,
+ *   - rig.setup.completed — script ran and exited 0,
+ *   - rig.setup.failed    — nonzero exit / timeout,
+ * and on failure THROWS (fail the turn closed) with a message naming the
+ * rig/version and a bounded tail of the setup output.
+ */
+export async function runRigSetupHook(
+  session: SandboxSessionLike,
+  context: SandboxLifecycleHookContext = { environment: {} },
+): Promise<void> {
+  const rigSetup = context.rigSetup;
+  if (!rigSetup) {
+    return;
+  }
+  const payload = {
+    rigId: rigSetup.rigId,
+    versionId: rigSetup.versionId,
+    rigName: rigSetup.rigName,
+  };
+  await context.onRuntimeEvent?.({ type: "rig.setup.started", payload });
+  const command = rigSetupScriptCommand(rigSetup.script, rigSetup.versionId, rigSetup.timeoutMs);
+  const execArgs = {
+    cmd: command,
+    workdir: "/workspace",
+    ...(context.runAs ? { runAs: context.runAs } : {}),
+    // The in-box coreutils timeout is the hard deadline; the SDK yield waits a
+    // little longer so it observes timeout's non-zero exit instead of a live
+    // still-running process.
+    yieldTimeMs: rigSetup.timeoutMs + 7_000,
+    maxOutputTokens: 20_000,
+  };
+  let result: unknown;
+  try {
+    if (session.exec) {
+      result = await session.exec(execArgs);
+    } else if (session.execCommand) {
+      result = await session.execCommand(execArgs);
+    } else {
+      throw new Error("Sandbox session does not support command execution");
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    await context.onRuntimeEvent?.({
+      type: "rig.setup.failed",
+      payload: { ...payload, error: message.slice(-RIG_SETUP_OUTPUT_TAIL_LIMIT) },
+    });
+    throw new Error(
+      `Rig setup failed for rig "${rigSetup.rigName}" (version ${rigSetup.versionId}): ${message}`,
+      { cause: error },
+    );
+  }
+  const output = sandboxCommandOutput(result);
+  // Marker present → the guard skipped the script. Distinct terminal signal.
+  if (output.includes(RIG_SETUP_SKIPPED_SENTINEL)) {
+    await context.onRuntimeEvent?.({ type: "rig.setup.skipped", payload });
+    return;
+  }
+  // Ran → classify. A "still running" result means the script outlived the rig
+  // timeout; any nonzero/absent exit code is a setup failure. Both fail closed.
+  const stillRunning = sandboxCommandStillRunning(result);
+  const exitCode = sandboxCommandExitCode(result);
+  if (stillRunning || exitCode === null || exitCode !== 0) {
+    const tail =
+      output.length > RIG_SETUP_OUTPUT_TAIL_LIMIT
+        ? output.slice(-RIG_SETUP_OUTPUT_TAIL_LIMIT)
+        : output;
+    const reason = stillRunning
+      ? `did not finish within the rig setup timeout (${rigSetup.timeoutMs}ms)`
+      : exitCode === null
+        ? "did not report an exit code"
+        : `exited with code ${exitCode}`;
+    const failure = new Error(
+      `Rig setup failed for rig "${rigSetup.rigName}" (version ${rigSetup.versionId}): the setup script ${reason}${tail ? `:\n${tail}` : ""}`,
+    );
+    await context.onRuntimeEvent?.({
+      type: "rig.setup.failed",
+      payload: { ...payload, error: failure.message.slice(-RIG_SETUP_OUTPUT_TAIL_LIMIT) },
+    });
+    throw failure;
+  }
+  await context.onRuntimeEvent?.({
+    type: "rig.setup.completed",
+    payload: { ...payload, skipped: false },
+  });
+}
+
 export async function runRepositoryCloneHook(
   session: SandboxSessionLike,
   resources: Extract<ResourceRef, { kind: "repository" }>[],
@@ -3677,17 +5322,21 @@ export async function runRepositoryCloneHook(
   const payload = { name: "repository-clone", repositoryCount: resources.length };
   await context.onRuntimeEvent?.({ type: "sandbox.operation.started", payload });
   try {
-    // TOKEN-BROKER (B1): thread the run-scoped GitHub token PER-EXEC, never on the
-    // manifest. The SDK's ExecCommandArgs has no `environment` field (exec inherits
-    // the box's manifest env), so we can't hand the seed through an exec option — and
-    // we MUST NOT put it on the manifest (validateNoEnvironmentDelta would see a
-    // rotating value). We therefore inline it as an ephemeral `export` prefix on THIS
-    // exec's command text only: it lives in the command, not the box/agent manifest,
-    // and never persists. The clone command's gated seed block then writes it to the
-    // token FILE before the fetch, so GIT_ASKPASS reads it. Absent seed (e.g. the
-    // selfhosted path) -> no prefix, the clone runs byte-for-byte as before.
-    const command = context.gitTokenSeed
-      ? `export OPENGENI_GIT_TOKEN_SEED=${shellQuote(context.gitTokenSeed)}\n${repositoryCloneCommand(resources)}`
+    // TOKEN-BROKER (B1): thread run-scoped provider tokens PER-EXEC, never on
+    // the manifest. The SDK's ExecCommandArgs has no `environment` field (exec
+    // inherits the box's manifest env), so we can't hand seeds through an exec
+    // option — and we MUST NOT put them on the manifest (validateNoEnvironmentDelta
+    // would see rotating values). We inline ephemeral `export` prefixes on THIS
+    // exec's command text only. The clone command writes them to provider token
+    // FILES before fetch/CLI use. Absent seeds -> no prefix; helper wrappers still
+    // install and passthrough cleanly.
+    const gitTokenSeeds = {
+      ...(context.gitTokenSeeds ?? {}),
+      ...(context.gitTokenSeed ? { github: context.gitTokenSeed } : {}),
+    } satisfies GitTokenSeeds;
+    const seedPrefix = gitTokenSeedExportPrefix(gitTokenSeeds);
+    const command = seedPrefix
+      ? `${seedPrefix}\n${repositoryCloneCommand(resources)}`
       : repositoryCloneCommand(resources);
     if (session.exec) {
       const result = await session.exec({
@@ -3725,20 +5374,20 @@ export async function runRepositoryCloneHook(
 
 export function azureCliLoginCommand(): string {
   return [
-    "export HOME=\"${HOME:-/workspace}\"",
-    "mkdir -p \"$HOME/.azure\"",
-    "CLIENT_ID=\"${AZURE_CLIENT_ID:-${ARM_CLIENT_ID:-}}\"",
-    "CLIENT_SECRET=\"${AZURE_CLIENT_SECRET:-${ARM_CLIENT_SECRET:-}}\"",
-    "TENANT_ID=\"${AZURE_TENANT_ID:-${ARM_TENANT_ID:-}}\"",
-    "SUBSCRIPTION_ID=\"${AZURE_SUBSCRIPTION_ID:-${ARM_SUBSCRIPTION_ID:-}}\"",
-    "if [ -n \"$CLIENT_ID\" ] && [ -n \"$CLIENT_SECRET\" ] && [ -n \"$TENANT_ID\" ]; then",
-    "  command -v az >/dev/null 2>&1 || { echo \"Azure CLI is not installed in the sandbox\" >&2; exit 127; }",
-    "  az account show --only-show-errors >/dev/null 2>&1 || az login --service-principal --username \"$CLIENT_ID\" --password \"$CLIENT_SECRET\" --tenant \"$TENANT_ID\" --allow-no-subscriptions --only-show-errors --output none",
+    'export HOME="${HOME:-/workspace}"',
+    'mkdir -p "$HOME/.azure"',
+    'CLIENT_ID="${AZURE_CLIENT_ID:-${ARM_CLIENT_ID:-}}"',
+    'CLIENT_SECRET="${AZURE_CLIENT_SECRET:-${ARM_CLIENT_SECRET:-}}"',
+    'TENANT_ID="${AZURE_TENANT_ID:-${ARM_TENANT_ID:-}}"',
+    'SUBSCRIPTION_ID="${AZURE_SUBSCRIPTION_ID:-${ARM_SUBSCRIPTION_ID:-}}"',
+    'if [ -n "$CLIENT_ID" ] && [ -n "$CLIENT_SECRET" ] && [ -n "$TENANT_ID" ]; then',
+    '  command -v az >/dev/null 2>&1 || { echo "Azure CLI is not installed in the sandbox" >&2; exit 127; }',
+    '  az account show --only-show-errors >/dev/null 2>&1 || az login --service-principal --username "$CLIENT_ID" --password "$CLIENT_SECRET" --tenant "$TENANT_ID" --allow-no-subscriptions --only-show-errors --output none',
     // if/fi, NOT `[ -n ] && az`: this line ends the credentialed if-body, so with a
     // no-subscription SP (an explicitly supported config — the login above passes
     // --allow-no-subscriptions) the bare `[ -n ]` would exit the whole script 1 and
     // fail the turn.
-    "  if [ -n \"$SUBSCRIPTION_ID\" ]; then az account set --subscription \"$SUBSCRIPTION_ID\" --only-show-errors; fi",
+    '  if [ -n "$SUBSCRIPTION_ID" ]; then az account set --subscription "$SUBSCRIPTION_ID" --only-show-errors; fi',
     "fi",
   ].join("\n");
 }
@@ -3766,6 +5415,10 @@ export function sandboxCommandExitCode(result: unknown): number | null {
 }
 
 export function sandboxCommandOutput(result: unknown): string {
+  if (typeof result === "string") {
+    const outputIndex = result.indexOf("Output:");
+    return outputIndex >= 0 ? result.slice(outputIndex + "Output:".length).trim() : result.trim();
+  }
   if (!result || typeof result !== "object") {
     return "";
   }
@@ -3782,11 +5435,15 @@ export function sandboxCommandOutput(result: unknown): string {
 function assertSandboxCommandSucceeded(result: unknown, operation: string): void {
   const output = sandboxCommandOutput(result);
   if (sandboxCommandStillRunning(result)) {
-    throw new Error(`${operation} did not finish before the lifecycle command timeout${output ? `:\n${output}` : ""}`);
+    throw new Error(
+      `${operation} did not finish before the lifecycle command timeout${output ? `:\n${output}` : ""}`,
+    );
   }
   const exitCode = sandboxCommandExitCode(result);
   if (exitCode !== null && exitCode !== 0) {
-    throw new Error(output || `${operation} failed with exit code ${exitCode}`);
+    throw new Error(
+      `${operation} failed with exit code ${exitCode}${output ? `:\n${output}` : ""}`,
+    );
   }
   if (exitCode === null) {
     throw new Error(output || `${operation} did not return a command exit code`);
@@ -3883,15 +5540,20 @@ let stagedBundledSkillsDir: string | null = null;
 
 function bundledSkillsDir(): string {
   const moduleDir = dirname(fileURLToPath(import.meta.url));
-  const packaged = [
-    join(moduleDir, "bundled_hashicorp_terraform_skills"),
-    join(moduleDir, "..", "src", "bundled_hashicorp_terraform_skills"),
-  ].find((candidate) => existsSync(candidate)) ?? join(moduleDir, "bundled_hashicorp_terraform_skills");
+  const packaged =
+    [
+      join(moduleDir, "bundled_hashicorp_terraform_skills"),
+      join(moduleDir, "..", "src", "bundled_hashicorp_terraform_skills"),
+    ].find((candidate) => existsSync(candidate)) ??
+    join(moduleDir, "bundled_hashicorp_terraform_skills");
   if (isPathWithin(process.cwd(), packaged)) {
     return packaged;
   }
   if (!stagedBundledSkillsDir) {
-    stagedBundledSkillsDir = stageBundledSkills(packaged, join(process.cwd(), ".opengeni", "bundled_hashicorp_terraform_skills"));
+    stagedBundledSkillsDir = stageBundledSkills(
+      packaged,
+      join(process.cwd(), ".opengeni", "bundled_hashicorp_terraform_skills"),
+    );
   }
   return stagedBundledSkillsDir;
 }
@@ -3949,12 +5611,18 @@ export function lazySkillSourceWithPackSkills(packSkills: PackSkill[]): LocalDir
     packNameKeys.add(skill.name.toLowerCase());
     packNames.add(skill.name);
     children[skill.name] = packSkillDirEntry(skill);
-    packIndex.push({ name: skill.name, description: packSkillDescription(skill), path: skill.name });
+    packIndex.push({
+      name: skill.name,
+      description: packSkillDescription(skill),
+      path: skill.name,
+    });
   }
   return {
     source: dir({ children }),
     getIndex: (manifest, skillsPath) => [
-      ...(bundled.getIndex?.(manifest, skillsPath) ?? []).filter((entry) => !packNames.has(entry.path ?? entry.name)),
+      ...(bundled.getIndex?.(manifest, skillsPath) ?? []).filter(
+        (entry) => !packNames.has(entry.path ?? entry.name),
+      ),
       ...packIndex,
     ],
   };
@@ -4019,7 +5687,11 @@ function assertSafePackSkillName(name: string): void {
 
 function packSkillPathSegments(skillName: string, path: string): string[] {
   const segments = path.split("/");
-  if (path.startsWith("/") || path.includes("\\") || segments.some((segment) => segment.length === 0 || segment === "." || segment === "..")) {
+  if (
+    path.startsWith("/") ||
+    path.includes("\\") ||
+    segments.some((segment) => segment.length === 0 || segment === "." || segment === "..")
+  ) {
     throw new Error(`Invalid pack skill file path for ${skillName}: ${path}`);
   }
   return segments;
@@ -4068,16 +5740,16 @@ function skillFrontmatterDescription(markdown: string): string | null {
 }
 
 function unquoteFrontmatterValue(value: string): string {
-  if (value.length >= 2 && value[0] === value[value.length - 1] && (value[0] === '"' || value[0] === "'")) {
+  if (
+    value.length >= 2 &&
+    value[0] === value[value.length - 1] &&
+    (value[0] === '"' || value[0] === "'")
+  ) {
     return value.slice(1, -1);
   }
   return value;
 }
 
-function stringValue(value: unknown): string | undefined {
-  return typeof value === "string" && value.trim() ? value.trim() : undefined;
-}
-
 function isAsyncIterable<T>(source: Iterable<T> | AsyncIterable<T>): source is AsyncIterable<T> {
   return typeof (source as AsyncIterable<T>)[Symbol.asyncIterator] === "function";
 }
@@ -4091,7 +5763,11 @@ function sortJson(value: unknown): unknown {
     return value.map(sortJson);
   }
   if (value && typeof value === "object") {
-    return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, nested]) => [key, sortJson(nested)]));
+    return Object.fromEntries(
+      Object.entries(value)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, nested]) => [key, sortJson(nested)]),
+    );
   }
   return value;
 }