@opengeni/config 0.7.11 → 0.7.22

package/src/index.ts

@@ -3,6 +3,7 @@ import {
   CAPABILITY_DESCRIPTORS,
   Entitlements,
   EntitlementsMode,
+  LatencyMode,
   MAX_NESTED_AGENT_DEPTH,
   ProductAccessMode,
   ReasoningEffort,
@@ -11,6 +12,7 @@ import {
   StaticUsageLimits,
   TurnExecutionPolicyV1,
   UsageLimitsMode,
+  type TurnExecutionLatencyModeSourceV1,
   type TurnExecutionModelSourceV1,
   type TurnExecutionReasoningSourceV1,
 } from "@opengeni/contracts";
@@ -217,6 +219,9 @@ const SettingsSchema = z.object({
   observabilityOtlpEndpoint: z.string().url().optional(),
   observabilityOtlpHeaders: z.string().default(""),
   publicBaseUrl: z.string().url().optional(),
+  // Browser origin when the web app and API use separate origins in local
+  // development. Production normally leaves this unset and uses publicBaseUrl.
+  webBaseUrl: z.string().url().optional(),
   // Base URL for the bring-your-own-compute agent release assets the get.<domain>
   // install routes redirect to. Defaults to this repo's GitHub Releases. The route
   // appends `/download/agent-v<ver>/<asset>`.
@@ -248,9 +253,6 @@ const SettingsSchema = z.object({
   // holder of stream:control gets 403 until this flips. Keeps stream:control a
   // declared-but-inert permission so later hardening is a flag flip.
   streamControlEnabled: EnvBoolean.default(false),
-  // Existing-session explicit tool replacement is gated until every API and
-  // worker instance understands durable tools_provided provenance.
-  sessionTurnToolReplacementEnabled: EnvBoolean.default(false),
   toolspaceEnabled: EnvBoolean.default(false),
   toolspaceMaxCallsPerTurn: z.coerce.number().int().positive().default(200),
   // Optional release-coherent bootstrap hint for custom rigs/connected machines
@@ -267,6 +269,8 @@ const SettingsSchema = z.object({
   integrationsOauthClientsJson: z.string().default("{}"),
   slackClientId: z.string().optional(),
   slackClientSecret: z.string().optional(),
+  googleDriveClientId: z.string().optional(),
+  googleDriveClientSecret: z.string().optional(),
   // Undefined is meaningful: the migration boundary persists the product
   // default of 3 when no deployment override is supplied.
   maxNestedAgentDepth: z.coerce.number().int().nonnegative().max(MAX_NESTED_AGENT_DEPTH).optional(),
@@ -330,6 +334,41 @@ const SettingsSchema = z.object({
   openaiBaseUrl: z.string().optional(),
   openaiModel: z.string().default("gpt-5.6-sol"),
   openaiAllowedModels: z.string().default("gpt-5.6-sol,gpt-5.6-terra,gpt-5.6-luna"),
+  // Native composer voice input (browser MediaRecorder → API transcription).
+  // Provider credentials stay server-side; ClientConfig only projects availability
+  // and hard ceilings. Selection happens once before audio is sent — never retry
+  // the same clip across vendors after an upstream request may have started.
+  voiceInputMaxDurationSeconds: z.coerce.number().int().positive().max(600).default(60),
+  voiceInputMaxSizeBytes: z.coerce
+    .number()
+    .int()
+    .positive()
+    .max(100 * 1024 * 1024)
+    .default(25 * 1024 * 1024),
+  // Preferred provider order (comma-separated ids). First configured+ready wins.
+  // Codex subscription STT is preferred by default when subscription routing is
+  // enabled; operators can put openai/azure-openai first explicitly.
+  // Supported: openai, azure-openai, codex-subscription.
+  voiceInputProviderOrder: z.string().default("codex-subscription,openai,azure-openai"),
+  // OpenAI public /v1/audio/transcriptions path. Reuses OPENGENI_OPENAI_API_KEY
+  // when voiceInputOpenaiApiKey is unset. Default model is gpt-transcribe.
+  voiceInputOpenaiEnabled: EnvBoolean.default(true),
+  voiceInputOpenaiApiKey: z.string().optional(),
+  voiceInputOpenaiBaseUrl: z.string().optional(),
+  voiceInputOpenaiModel: z.string().default("gpt-transcribe"),
+  // Azure OpenAI deployment-scoped audio transcriptions. Reuses the turn-model
+  // Azure endpoint/key/AD token when voice-specific overrides are unset.
+  voiceInputAzureEnabled: EnvBoolean.default(true),
+  voiceInputAzureEndpoint: z.string().optional(),
+  voiceInputAzureDeployment: z.string().optional(),
+  voiceInputAzureApiVersion: z.string().optional(),
+  voiceInputAzureApiKey: z.string().optional(),
+  voiceInputAzureAdToken: z.string().optional(),
+  // Legacy opt-in for undocumented ChatGPT /backend-api/transcribe. When
+  // OPENGENI_CODEX_SUBSCRIPTION_ENABLED is true, Codex STT is included without
+  // this flag. Set false and omit codex-subscription from PROVIDER_ORDER to
+  // keep subscription model routing while disabling Codex voice input.
+  voiceInputCodexExperimentalEnabled: EnvBoolean.default(false),
   modelPricingJson: z.string().default("{}"),
   // Extra (non-built-in) model providers, declared by the host as a JSON
   // provider registry. Each entry carries its own base URL, API key, wire API
@@ -413,6 +452,11 @@ const SettingsSchema = z.object({
   dockerImage: z.string().default("opengeni-sandbox:local"),
   dockerExposedPorts: z.string().default(""),
   dockerNetwork: z.string().optional(),
+  // When the worker itself runs in a container and talks to a host Docker daemon,
+  // this directory must be bind-mounted at the exact same absolute path on both
+  // sides. The Agents SDK materializes the workspace here before bind-mounting it
+  // into the sandbox container.
+  dockerWorkspaceBaseDir: z.string().min(1).optional(),
   modalAppName: z.string().default("opengeni-sandbox"),
   modalImageRef: z.string().optional(),
   // Name of a Modal Secret (containing REGISTRY_USERNAME + REGISTRY_PASSWORD) used
@@ -424,17 +468,17 @@ const SettingsSchema = z.object({
   // the named Secret and builds the image via `fromRegistry(tag, secret)` before the
   // first sandbox is created. Knob: OPENGENI_MODAL_IMAGE_REGISTRY_SECRET.
   modalImageRegistrySecret: z.string().optional(),
-  // Modal's hard sandbox lifetime (timeoutMs = this * 1000), counted from each
-  // create/resume — it is the BACKSTOP that reclaims a box if the reaper/worker is
-  // down, NOT the warm-window controller (that's sandboxIdleGraceMs). It must
-  // comfortably exceed reaperPeriod + idleGrace so the reaper terminates a
-  // genuinely-idle box FIRST; the boot invariant below enforces that. Default 1h
-  // (was 900s/15min): the 15-min drain grace counts from the user's LAST release,
-  // but Modal's clock starts at the preceding turn's resume — so a 15-min grace on
-  // top of a 900s lifetime would let Modal kill the box mid-warm-window. 3600s
-  // leaves ~45min of headroom for the active turn before the warm window opens.
+  // Modal's hard sandbox lifetime (timeoutMs = this * 1000), counted from box
+  // creation. A resume-by-id does NOT reset that provider clock. It is the
+  // BACKSTOP that reclaims a box if the reaper/worker is down, NOT the warm-window
+  // controller (that's sandboxIdleGraceMs). It must comfortably exceed
+  // reaperPeriod + idleGrace so the reaper terminates a genuinely-idle box FIRST;
+  // the boot invariant below enforces that. Default 24h, Modal's documented
+  // maximum, to reduce premature active-box loss and leave headroom for the
+  // deadline-aware snapshot/rematerialization transition. The transition—not a
+  // larger timeout—is what lets a session outlive one finite provider box.
   // Knob: OPENGENI_MODAL_TIMEOUT_SECONDS.
-  modalTimeoutSeconds: z.coerce.number().int().positive().default(3600),
+  modalTimeoutSeconds: z.coerce.number().int().positive().max(86_400).default(86_400),
   modalTokenId: z.string().optional(),
   modalTokenSecret: z.string().optional(),
   modalEnvironment: z.string().optional(),
@@ -467,13 +511,6 @@ const SettingsSchema = z.object({
   modalWorkspacePersistence: z
     .enum(["tar", "snapshot_filesystem", "snapshot_directory"])
     .default("snapshot_filesystem"),
-  // Snapshot GC backstop (sandbox-file-persistence): the reaper keeps ONE latest
-  // filesystem snapshot per lease (delete-prior-on-supersede + delete-on-teardown).
-  // This is the TTL retention floor for the periodic orphan sweep — a snapshot
-  // whose lease is cold and older than this is best-effort deleted so a crashed
-  // persist-then-no-restore never leaks a Modal image. 0 disables the TTL sweep
-  // (delete-on-supersede/teardown still run). Default 7 days.
-  modalSnapshotRetentionSeconds: z.coerce.number().int().nonnegative().default(604_800),
   // Shared desktop toggle: this module reads it for the 6080 port-merge; the
   // owner module (P4.x) acts on it to launch the display stack.
   sandboxDesktopEnabled: EnvBoolean.default(false),
@@ -692,8 +729,9 @@ const SettingsSchema = z.object({
   // this whole window so a "glanced away then came back" re-arms the SAME warm box
   // (acquireLease re-arms draining->warm; the reaper's BEFORE-terminate re-read
   // skips a re-armed box). Default 15min so a brief detour never cold-creates a
-  // fresh EMPTY box; lower it to trade warm cost for a snappier reclaim. Knob:
-  // OPENGENI_SANDBOX_IDLE_GRACE_MS.
+  // fresh EMPTY box; lower it to trade warm cost for a snappier reclaim.
+  // getSettings caps the default at half a shorter configured Modal lifetime so
+  // the entire reaper window always fits. Knob: OPENGENI_SANDBOX_IDLE_GRACE_MS.
   sandboxIdleGraceMs: z.coerce.number().int().positive().default(900_000),
   // MID-SESSION /workspace snapshot cadence (sandbox-file-persistence). The
   // reaper's drain-persist only protects boxes the reaper itself kills; a box
@@ -711,6 +749,22 @@ const SettingsSchema = z.object({
   // treated exactly like a failed best-effort snapshot. Knob:
   // OPENGENI_SANDBOX_SNAPSHOT_TIMEOUT_MS. Default 60s.
   sandboxSnapshotTimeoutMs: z.coerce.number().int().positive().default(60_000),
+  // Begin a controlled snapshot/quiesce/drain/rematerialize transition this far
+  // ahead of a finite provider deadline. Modal's 24h creation clock cannot be
+  // extended; the logical sandbox outlives it by moving to one successor box.
+  // getSettings derives the actual default as min(1h, half the configured
+  // provider lifetime) so short-lived test/canary boxes remain bootable without
+  // an extra coupled environment override. An explicit value may be larger when
+  // an operator deliberately wants more rotation headroom; the boot invariant
+  // still requires it to remain below the provider lifetime.
+  sandboxRotationLeadMs: z.coerce.number().int().positive().default(3_600_000),
+  // Bound each global reaper pass so a rollout that discovers many legacy boxes
+  // with unknown creation clocks cannot create a provider/API thundering herd.
+  // One is the safe admission default: the reaper services provider transitions
+  // sequentially, so claiming a wider batch would fence boxes before the same
+  // sweep can service them. Larger fleets may raise this only as an explicit,
+  // observed deployment choice.
+  sandboxRotationBatchSize: z.coerce.number().int().positive().max(500).default(1),
   // expires_at refresh window for a held lease (>> the turn 10s heartbeat so a
   // single missed heartbeat never TTL-reaps a live turn). The warming TTL is the
   // window a cold->warming spawner has to commit warm before a reaper resets it.
@@ -739,6 +793,7 @@ const SettingsSchema = z.object({
   sandboxPreparationProfiles: z.string().default("none"),
   sandboxEnvAllowlist: z.string().default(""),
   objectStorageEndpoint: z.string().url().optional(),
+  objectStorageInternalEndpoint: z.string().url().optional(),
   objectStorageSandboxEndpoint: z.string().url().optional(),
   objectStorageBackend: z
     .enum(["s3-compatible", "aws-s3", "azure-blob", "gcs"])
@@ -817,6 +872,163 @@ const SettingsSchema = z.object({
 
 export type Settings = z.infer<typeof SettingsSchema>;
 export type McpServerConfig = Settings["mcpServers"][number];
+
+/** Declarative voice-input transcription provider ids. */
+export type VoiceInputProviderId = "openai" | "azure-openai" | "codex-subscription";
+
+export type VoiceInputProviderConfig =
+  | {
+      id: "openai";
+      kind: "openai";
+      apiKey: string;
+      baseUrl: string;
+      model: string;
+    }
+  | {
+      id: "azure-openai";
+      kind: "azure-openai";
+      endpoint: string;
+      deployment: string;
+      apiVersion: string;
+      apiKey: string | null;
+      adToken: string | null;
+    }
+  | {
+      id: "codex-subscription";
+      kind: "codex-subscription";
+      experimental: true;
+    };
+
+/**
+ * Reject empty / template secrets so `.env.example` placeholders like
+ * `your-key` cannot advertise voice input as available and then 401 upstream.
+ */
+export function isUsableVoiceInputSecret(value: string | null | undefined): value is string {
+  if (value == null) return false;
+  const trimmed = value.trim();
+  if (!trimmed) return false;
+  const normalized = trimmed.toLowerCase();
+  if (
+    normalized === "your-key" ||
+    normalized === "your_key" ||
+    normalized === "changeme" ||
+    normalized === "replace-me" ||
+    normalized === "xxx" ||
+    normalized.startsWith("your-") ||
+    normalized.startsWith("your_")
+  ) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Resolve the configured voice-input provider registry in selection order.
+ * Credentials stay in this server-side structure; ClientConfig only projects
+ * whether at least one non-experimental (or probed experimental) provider exists.
+ */
+export function resolveVoiceInputProviderRegistry(settings: Settings): VoiceInputProviderConfig[] {
+  const order = settings.voiceInputProviderOrder
+    .split(",")
+    .map((part) => part.trim())
+    .filter(
+      (part): part is VoiceInputProviderId =>
+        part === "openai" || part === "azure-openai" || part === "codex-subscription",
+    );
+  const seen = new Set<VoiceInputProviderId>();
+  const providers: VoiceInputProviderConfig[] = [];
+  for (const id of order) {
+    if (seen.has(id)) continue;
+    seen.add(id);
+    if (id === "openai") {
+      if (!settings.voiceInputOpenaiEnabled) continue;
+      const apiKey = settings.voiceInputOpenaiApiKey ?? settings.openaiApiKey;
+      if (!isUsableVoiceInputSecret(apiKey)) continue;
+      // When the turn provider is Azure-only and no voice-specific OpenAI key/URL
+      // was set, do not silently reuse a leftover OPENAI_API_KEY for voice.
+      if (
+        settings.openaiProvider === "azure" &&
+        !settings.voiceInputOpenaiApiKey &&
+        !settings.voiceInputOpenaiBaseUrl
+      ) {
+        continue;
+      }
+      providers.push({
+        id: "openai",
+        kind: "openai",
+        apiKey,
+        baseUrl: (
+          settings.voiceInputOpenaiBaseUrl ??
+          settings.openaiBaseUrl ??
+          "https://api.openai.com/v1"
+        ).replace(/\/+$/, ""),
+        model: settings.voiceInputOpenaiModel,
+      });
+      continue;
+    }
+    if (id === "azure-openai") {
+      if (!settings.voiceInputAzureEnabled) continue;
+      const endpoint = (
+        settings.voiceInputAzureEndpoint ??
+        settings.azureOpenaiEndpoint ??
+        ""
+      ).replace(/\/+$/, "");
+      const deployment = settings.voiceInputAzureDeployment ?? settings.azureOpenaiDeployment ?? "";
+      const apiVersion =
+        settings.voiceInputAzureApiVersion ??
+        settings.azureOpenaiApiVersion ??
+        "2025-04-01-preview";
+      const apiKey = settings.voiceInputAzureApiKey ?? settings.azureOpenaiApiKey ?? null;
+      const adToken = settings.voiceInputAzureAdToken ?? settings.azureOpenaiAdToken ?? null;
+      if (
+        !endpoint ||
+        !deployment ||
+        (!isUsableVoiceInputSecret(apiKey) && !isUsableVoiceInputSecret(adToken))
+      ) {
+        continue;
+      }
+      // When turn provider is OpenAI-only and no voice-specific Azure settings
+      // were provided, skip ambient Azure leftovers.
+      if (
+        settings.openaiProvider !== "azure" &&
+        !settings.voiceInputAzureEndpoint &&
+        !settings.voiceInputAzureDeployment &&
+        !settings.voiceInputAzureApiKey &&
+        !settings.voiceInputAzureAdToken
+      ) {
+        continue;
+      }
+      providers.push({
+        id: "azure-openai",
+        kind: "azure-openai",
+        endpoint,
+        deployment,
+        apiVersion,
+        apiKey: isUsableVoiceInputSecret(apiKey) ? apiKey : null,
+        adToken: isUsableVoiceInputSecret(adToken) ? adToken : null,
+      });
+      continue;
+    }
+    if (id === "codex-subscription") {
+      // Prefer Codex STT whenever subscription model routing is enabled.
+      // Operators who want OpenAI/Azure first should set PROVIDER_ORDER; omit
+      // `codex-subscription` from the order to disable Codex voice while keeping
+      // subscription turns. VOICE_INPUT_CODEX_EXPERIMENTAL is retained for
+      // back-compat docs/env but no longer gates inclusion.
+      if (!settings.codexSubscriptionEnabled) continue;
+      providers.push({ id: "codex-subscription", kind: "codex-subscription", experimental: true });
+    }
+  }
+  return providers;
+}
+
+/** True when the deployment has at least one supported (non-experimental) provider. */
+export function voiceInputDeploymentConfigured(settings: Settings): boolean {
+  return resolveVoiceInputProviderRegistry(settings).some(
+    (provider) => provider.kind !== "codex-subscription",
+  );
+}
+
 export type TemporalTlsConnectionConfig = {
   serverNameOverride?: string;
   serverRootCACertificate?: Uint8Array;
@@ -1165,88 +1377,91 @@ export interface ConfiguredModel {
   hostedWebSearch: boolean;
 }
 
-export const defaultModelPricing: Record<string, ModelPricing> = {
+/**
+ * Built-in OpenGeni credit pricing schedules.
+ *
+ * Rates are provider list prices in USD micros per 1M tokens. Debit applies
+ * `marginBps` (2_500 = +25%) on top. Long-context tiers follow OpenAI's
+ * ">272K input tokens" rule (threshold exclusive of 272_000).
+ *
+ * GPT-5.4 and older families are intentionally omitted — they are no longer
+ * offered. Codex / connected-subscription turns use `metering: external` and
+ * never consult this map.
+ *
+ * When adding or changing a billed model, run `bun run check:model-pricing`
+ * (see docs/model-providers.md § Price audit). That compares this map to
+ * llm-prices.com as a ground-truth canary; it does not generate this table.
+ */
+export const defaultModelPricing: Record<string, ModelPricingScheduleV1> = {
   "gpt-5.6-sol": {
-    inputMicrosPerMillionTokens: 5_000_000,
-    cachedInputMicrosPerMillionTokens: 500_000,
-    outputMicrosPerMillionTokens: 30_000_000,
-    marginBps: 2_500,
+    default: {
+      inputMicrosPerMillionTokens: 5_000_000,
+      cachedInputMicrosPerMillionTokens: 500_000,
+      outputMicrosPerMillionTokens: 30_000_000,
+      marginBps: 2_500,
+    },
+    inputTokenTiers: [
+      {
+        // OpenAI: prompts with >272K input tokens use the long-context rate.
+        minimumInputTokens: 272_001,
+        pricing: {
+          inputMicrosPerMillionTokens: 10_000_000,
+          cachedInputMicrosPerMillionTokens: 1_000_000,
+          outputMicrosPerMillionTokens: 45_000_000,
+          marginBps: 2_500,
+        },
+      },
+    ],
   },
   "gpt-5.6-terra": {
-    inputMicrosPerMillionTokens: 2_500_000,
-    cachedInputMicrosPerMillionTokens: 250_000,
-    outputMicrosPerMillionTokens: 15_000_000,
-    marginBps: 2_500,
+    default: {
+      inputMicrosPerMillionTokens: 2_000_000,
+      cachedInputMicrosPerMillionTokens: 200_000,
+      outputMicrosPerMillionTokens: 12_000_000,
+      marginBps: 2_500,
+    },
+    inputTokenTiers: [
+      {
+        minimumInputTokens: 272_001,
+        pricing: {
+          inputMicrosPerMillionTokens: 4_000_000,
+          cachedInputMicrosPerMillionTokens: 400_000,
+          outputMicrosPerMillionTokens: 18_000_000,
+          marginBps: 2_500,
+        },
+      },
+    ],
   },
   "gpt-5.6-luna": {
-    inputMicrosPerMillionTokens: 1_000_000,
-    cachedInputMicrosPerMillionTokens: 100_000,
-    outputMicrosPerMillionTokens: 6_000_000,
-    marginBps: 2_500,
-  },
-  "gpt-5.4": {
-    inputMicrosPerMillionTokens: 2_500_000,
-    cachedInputMicrosPerMillionTokens: 250_000,
-    outputMicrosPerMillionTokens: 15_000_000,
-    marginBps: 2_500,
-  },
-  "gpt-5.4-mini": {
-    inputMicrosPerMillionTokens: 750_000,
-    cachedInputMicrosPerMillionTokens: 75_000,
-    outputMicrosPerMillionTokens: 4_500_000,
-    marginBps: 2_500,
-  },
-  "gpt-5.2": {
-    inputMicrosPerMillionTokens: 1_750_000,
-    cachedInputMicrosPerMillionTokens: 175_000,
-    outputMicrosPerMillionTokens: 14_000_000,
-    marginBps: 2_500,
-  },
-  "gpt-5.2-chat-latest": {
-    inputMicrosPerMillionTokens: 1_750_000,
-    cachedInputMicrosPerMillionTokens: 175_000,
-    outputMicrosPerMillionTokens: 14_000_000,
-    marginBps: 2_500,
-  },
-  "gpt-5.2-codex": {
-    inputMicrosPerMillionTokens: 1_750_000,
-    cachedInputMicrosPerMillionTokens: 175_000,
-    outputMicrosPerMillionTokens: 14_000_000,
-    marginBps: 2_500,
-  },
-  "gpt-5.1": {
-    inputMicrosPerMillionTokens: 1_250_000,
-    cachedInputMicrosPerMillionTokens: 125_000,
-    outputMicrosPerMillionTokens: 10_000_000,
-    marginBps: 2_500,
-  },
-  "gpt-5": {
-    inputMicrosPerMillionTokens: 1_250_000,
-    cachedInputMicrosPerMillionTokens: 125_000,
-    outputMicrosPerMillionTokens: 10_000_000,
-    marginBps: 2_500,
-  },
-  "gpt-5-mini": {
-    inputMicrosPerMillionTokens: 250_000,
-    cachedInputMicrosPerMillionTokens: 25_000,
-    outputMicrosPerMillionTokens: 2_000_000,
-    marginBps: 2_500,
-  },
-  "gpt-5-nano": {
-    inputMicrosPerMillionTokens: 50_000,
-    cachedInputMicrosPerMillionTokens: 5_000,
-    outputMicrosPerMillionTokens: 400_000,
-    marginBps: 2_500,
+    default: {
+      inputMicrosPerMillionTokens: 200_000,
+      cachedInputMicrosPerMillionTokens: 20_000,
+      outputMicrosPerMillionTokens: 1_200_000,
+      marginBps: 2_500,
+    },
+    inputTokenTiers: [
+      {
+        minimumInputTokens: 272_001,
+        pricing: {
+          inputMicrosPerMillionTokens: 400_000,
+          cachedInputMicrosPerMillionTokens: 40_000,
+          outputMicrosPerMillionTokens: 1_800_000,
+          marginBps: 2_500,
+        },
+      },
+    ],
   },
   // Fireworks AI / GLM 5.2 — the first shipped non-OpenAI registry model. A
   // built-in default pricing entry makes managed billing work out of the box
   // for hosts that expose this model via OPENGENI_MODEL_PROVIDERS_JSON without
   // also setting OPENGENI_MODEL_PRICING_JSON.
   "accounts/fireworks/models/glm-5p2": {
-    inputMicrosPerMillionTokens: 1_400_000,
-    cachedInputMicrosPerMillionTokens: 260_000,
-    outputMicrosPerMillionTokens: 4_400_000,
-    marginBps: 2_500,
+    default: {
+      inputMicrosPerMillionTokens: 1_400_000,
+      cachedInputMicrosPerMillionTokens: 140_000,
+      outputMicrosPerMillionTokens: 4_400_000,
+      marginBps: 2_500,
+    },
   },
 };
 
@@ -1349,6 +1564,7 @@ export function getSettings(): Settings {
     observabilityOtlpHeaders:
       optional("OPENGENI_OTEL_EXPORTER_OTLP_HEADERS") ?? optional("OTEL_EXPORTER_OTLP_HEADERS"),
     publicBaseUrl: optional("OPENGENI_PUBLIC_BASE_URL"),
+    webBaseUrl: optional("OPENGENI_WEB_BASE_URL"),
     agentReleasesBaseUrl: optional("OPENGENI_AGENT_RELEASES_BASE_URL"),
     agentStableVersion: optional("OPENGENI_AGENT_STABLE_VERSION"),
     productAccessMode: optional("OPENGENI_PRODUCT_ACCESS_MODE"),
@@ -1360,7 +1576,6 @@ export function getSettings(): Settings {
     delegationSecret: optional("OPENGENI_DELEGATION_SECRET"),
     streamTokenSecret: optional("OPENGENI_STREAM_TOKEN_SECRET"),
     streamControlEnabled: optional("OPENGENI_STREAM_CONTROL_ENABLED"),
-    sessionTurnToolReplacementEnabled: optional("OPENGENI_SESSION_TURN_TOOL_REPLACEMENT_ENABLED"),
     toolspaceEnabled: optional("OPENGENI_TOOLSPACE_ENABLED"),
     toolspaceMaxCallsPerTurn: optional("OPENGENI_TOOLSPACE_MAX_CALLS_PER_TURN"),
     ogtoolPackageSpec: optional("OPENGENI_OGTOOL_PACKAGE_SPEC"),
@@ -1373,6 +1588,8 @@ export function getSettings(): Settings {
     integrationsOauthClientsJson: optional("OPENGENI_INTEGRATIONS_OAUTH_CLIENTS_JSON"),
     slackClientId: optional("OPENGENI_SLACK_CLIENT_ID"),
     slackClientSecret: optional("OPENGENI_SLACK_CLIENT_SECRET"),
+    googleDriveClientId: optional("OPENGENI_GOOGLE_DRIVE_CLIENT_ID"),
+    googleDriveClientSecret: optional("OPENGENI_GOOGLE_DRIVE_CLIENT_SECRET"),
     maxNestedAgentDepth: optional("OPENGENI_MAX_NESTED_AGENT_DEPTH"),
     goalMaxAutoContinuations: optional("OPENGENI_GOAL_MAX_AUTO_CONTINUATIONS"),
     goalNoProgressLimit: optional("OPENGENI_GOAL_NO_PROGRESS_LIMIT"),
@@ -1397,6 +1614,20 @@ export function getSettings(): Settings {
     openaiBaseUrl: optional("OPENGENI_OPENAI_BASE_URL") ?? optional("OPENAI_BASE_URL"),
     openaiModel: optional("OPENGENI_OPENAI_MODEL"),
     openaiAllowedModels: optional("OPENGENI_OPENAI_ALLOWED_MODELS"),
+    voiceInputMaxDurationSeconds: optional("OPENGENI_VOICE_INPUT_MAX_DURATION_SECONDS"),
+    voiceInputMaxSizeBytes: optional("OPENGENI_VOICE_INPUT_MAX_SIZE_BYTES"),
+    voiceInputProviderOrder: optional("OPENGENI_VOICE_INPUT_PROVIDER_ORDER"),
+    voiceInputOpenaiEnabled: optional("OPENGENI_VOICE_INPUT_OPENAI_ENABLED"),
+    voiceInputOpenaiApiKey: optional("OPENGENI_VOICE_INPUT_OPENAI_API_KEY"),
+    voiceInputOpenaiBaseUrl: optional("OPENGENI_VOICE_INPUT_OPENAI_BASE_URL"),
+    voiceInputOpenaiModel: optional("OPENGENI_VOICE_INPUT_OPENAI_MODEL"),
+    voiceInputAzureEnabled: optional("OPENGENI_VOICE_INPUT_AZURE_ENABLED"),
+    voiceInputAzureEndpoint: optional("OPENGENI_VOICE_INPUT_AZURE_ENDPOINT"),
+    voiceInputAzureDeployment: optional("OPENGENI_VOICE_INPUT_AZURE_DEPLOYMENT"),
+    voiceInputAzureApiVersion: optional("OPENGENI_VOICE_INPUT_AZURE_API_VERSION"),
+    voiceInputAzureApiKey: optional("OPENGENI_VOICE_INPUT_AZURE_API_KEY"),
+    voiceInputAzureAdToken: optional("OPENGENI_VOICE_INPUT_AZURE_AD_TOKEN"),
+    voiceInputCodexExperimentalEnabled: optional("OPENGENI_VOICE_INPUT_CODEX_EXPERIMENTAL"),
     modelPricingJson: optional("OPENGENI_MODEL_PRICING_JSON"),
     modelProvidersJson: optional("OPENGENI_MODEL_PROVIDERS_JSON"),
     codexSubscriptionEnabled: optional("OPENGENI_CODEX_SUBSCRIPTION_ENABLED"),
@@ -1424,6 +1655,7 @@ export function getSettings(): Settings {
     dockerImage: optional("OPENGENI_DOCKER_IMAGE"),
     dockerExposedPorts: optional("OPENGENI_DOCKER_EXPOSED_PORTS"),
     dockerNetwork: optional("OPENGENI_DOCKER_NETWORK"),
+    dockerWorkspaceBaseDir: optional("OPENGENI_DOCKER_WORKSPACE_BASE_DIR"),
     modalAppName: optional("OPENGENI_MODAL_APP_NAME"),
     modalImageRef: optional("OPENGENI_MODAL_IMAGE_REF"),
     modalImageRegistrySecret: optional("OPENGENI_MODAL_IMAGE_REGISTRY_SECRET"),
@@ -1433,7 +1665,6 @@ export function getSettings(): Settings {
     modalEnvironment: optional("OPENGENI_MODAL_ENVIRONMENT"),
     modalIdleTimeoutSeconds: optional("OPENGENI_MODAL_IDLE_TIMEOUT_SECONDS"),
     modalWorkspacePersistence: optional("OPENGENI_MODAL_WORKSPACE_PERSISTENCE"),
-    modalSnapshotRetentionSeconds: optional("OPENGENI_MODAL_SNAPSHOT_RETENTION_SECONDS"),
     sandboxDesktopEnabled: optional("OPENGENI_SANDBOX_DESKTOP_ENABLED"),
     sandboxDesktopInteractive: optional("OPENGENI_SANDBOX_DESKTOP_INTERACTIVE"),
     sandboxTerminalEnabled: optional("OPENGENI_SANDBOX_TERMINAL_ENABLED"),
@@ -1506,6 +1737,8 @@ export function getSettings(): Settings {
     sandboxIdleGraceMs: optional("OPENGENI_SANDBOX_IDLE_GRACE_MS"),
     sandboxSnapshotIntervalMs: optional("OPENGENI_SANDBOX_SNAPSHOT_INTERVAL_MS"),
     sandboxSnapshotTimeoutMs: optional("OPENGENI_SANDBOX_SNAPSHOT_TIMEOUT_MS"),
+    sandboxRotationLeadMs: optional("OPENGENI_SANDBOX_ROTATION_LEAD_MS"),
+    sandboxRotationBatchSize: optional("OPENGENI_SANDBOX_ROTATION_BATCH_SIZE"),
     sandboxLeaseTtlMs: optional("OPENGENI_SANDBOX_LEASE_TTL_MS"),
     sandboxLeaseWarmingTtlMs: optional("OPENGENI_SANDBOX_LEASE_WARMING_TTL_MS"),
     sandboxWarmingTimeoutMs: optional("OPENGENI_SANDBOX_WARMING_TIMEOUT_MS"),
@@ -1517,6 +1750,7 @@ export function getSettings(): Settings {
     sandboxPreparationProfiles: optional("OPENGENI_SANDBOX_PREPARATION_PROFILES"),
     sandboxEnvAllowlist: optional("OPENGENI_SANDBOX_ENV_ALLOWLIST"),
     objectStorageEndpoint: optional("OPENGENI_OBJECT_STORAGE_ENDPOINT"),
+    objectStorageInternalEndpoint: optional("OPENGENI_OBJECT_STORAGE_INTERNAL_ENDPOINT"),
     objectStorageSandboxEndpoint: optional("OPENGENI_OBJECT_STORAGE_SANDBOX_ENDPOINT"),
     objectStorageBackend: optional("OPENGENI_OBJECT_STORAGE_BACKEND"),
     objectStorageBucket: optional("OPENGENI_OBJECT_STORAGE_BUCKET"),
@@ -1572,6 +1806,14 @@ export function getSettings(): Settings {
   const parsed = SettingsSchema.parse(raw);
   const settings = {
     ...parsed,
+    sandboxIdleGraceMs:
+      raw.sandboxIdleGraceMs === undefined
+        ? Math.min(900_000, Math.floor((parsed.modalTimeoutSeconds * 1000) / 2))
+        : parsed.sandboxIdleGraceMs,
+    sandboxRotationLeadMs:
+      raw.sandboxRotationLeadMs === undefined
+        ? Math.min(3_600_000, Math.floor((parsed.modalTimeoutSeconds * 1000) / 2))
+        : parsed.sandboxRotationLeadMs,
     mcpServers: ensureBuiltInMcpServers(parsed),
   };
   validateSettings(settings);
@@ -1593,6 +1835,23 @@ export function effectiveModalIdleTimeoutSeconds(settings: Settings): number {
   return settings.modalIdleTimeoutSeconds ?? settings.modalTimeoutSeconds;
 }
 
+/**
+ * One shared upper bound for the durable provider-capture claim and for command
+ * admission waiting behind it. The SDK request itself is bounded by
+ * sandboxSnapshotTimeoutMs; the extra window lets a non-cancellable provider
+ * response settle and release its exact claim without turning a normal
+ * checkpoint into a visible command failure. Database validation caps both
+ * consumers at one hour.
+ */
+export function sandboxArchiveCaptureTimeoutMs(
+  settings: Pick<Settings, "sandboxSnapshotTimeoutMs">,
+): number {
+  return Math.min(
+    60 * 60_000,
+    Math.max(settings.sandboxSnapshotTimeoutMs + 30_000, settings.sandboxSnapshotTimeoutMs * 2),
+  );
+}
+
 export function collectSandboxEnvironment(
   settings: Settings,
   source: NodeJS.ProcessEnv = process.env,
@@ -1883,6 +2142,115 @@ function legacyModelCapabilities(
   });
 }
 
+/** OpenAI GPT-5.6 Fast mode is 2× Standard list rates (service_tier fast/priority). */
+const GPT56_FAST_BILLING_MULTIPLIER_BPS = 20_000;
+
+/**
+ * Product display label for catalog/picker UI.
+ * Same string for OpenAI and Codex copies of a slug (`gpt-5.6-luna` and
+ * `codex/gpt-5.6-luna` → `GPT-5.6 Luna`). Non-gpt ids pass through unchanged.
+ */
+export function productLabelForModelId(modelId: string): string {
+  const slug = modelId.startsWith(CODEX_MODEL_ID_PREFIX)
+    ? modelId.slice(CODEX_MODEL_ID_PREFIX.length)
+    : modelId;
+  const match = /^(gpt-\d+(?:\.\d+)?)(?:-(.+))?$/i.exec(slug);
+  if (!match) {
+    return slug;
+  }
+  const family = match[1]!.replace(/^gpt/i, "GPT");
+  const rest = match[2];
+  if (!rest) {
+    return family;
+  }
+  const suffix = rest
+    .split("-")
+    .filter((part) => part.length > 0)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
+    .join(" ");
+  return suffix.length > 0 ? `${family} ${suffix}` : family;
+}
+
+function builtinLatencyModesForModel(modelId: string): Array<{
+  id: z.infer<typeof ModelLatencyModeV1>;
+  upstream: "supported" | "unsupported" | "unknown";
+  runnable: boolean;
+  billingMultiplierBps?: number;
+}> {
+  if (
+    modelId === "gpt-5.6-sol" ||
+    modelId === "gpt-5.6-terra" ||
+    modelId === "gpt-5.6-luna" ||
+    modelId.startsWith("codex/gpt-5.6-")
+  ) {
+    return [
+      { id: "standard", upstream: "supported", runnable: true },
+      {
+        id: "fast",
+        upstream: "supported",
+        runnable: true,
+        billingMultiplierBps: GPT56_FAST_BILLING_MULTIPLIER_BPS,
+      },
+    ];
+  }
+  return [{ id: "standard", upstream: "unknown", runnable: true }];
+}
+
+/**
+ * Map OpenGeni latency mode to the provider `service_tier` wire value.
+ * Azure and Codex ChatGPT accept `priority`; OpenAI API accepts `fast` (alias of priority).
+ * Standard omits the field.
+ */
+export function serviceTierForLatencyMode(
+  providerId: string,
+  latencyMode: LatencyMode,
+): "fast" | "priority" | undefined {
+  if (latencyMode === "standard") {
+    return undefined;
+  }
+  if (providerId === "azure" || providerId === CODEX_PROVIDER_ID) {
+    return "priority";
+  }
+  return "fast";
+}
+
+/** True when the response tier fulfills a non-standard Fast/priority request. */
+export function responseSatisfiesLatencyMode(
+  requested: LatencyMode,
+  responseServiceTier: string | null | undefined,
+): boolean {
+  if (requested === "standard") {
+    return true;
+  }
+  return responseServiceTier === "priority" || responseServiceTier === "fast";
+}
+
+export function runnableLatencyModesForModel(settings: Settings, modelId: string): LatencyMode[] {
+  const resolved = resolveModelProvider(
+    settingsForTurnExecutionPolicy(settings, modelId),
+    canonicalizeConfiguredModelId(settings, modelId),
+  );
+  if (!resolved) {
+    return ["standard"];
+  }
+  return resolved.model.capabilities.latencyModes
+    .filter((mode) => mode.runnable)
+    .map((mode) => LatencyMode.parse(mode.id));
+}
+
+function assertLatencyModeRunnable(
+  settings: Settings,
+  modelId: string,
+  latencyMode: LatencyMode,
+): void {
+  const runnable = runnableLatencyModesForModel(settings, modelId);
+  if (!runnable.includes(latencyMode)) {
+    throw new Error(
+      `latency mode ${latencyMode} is not runnable for model ${modelId} (allowed: ${runnable.join(", ")})`,
+    );
+  }
+}
+
 function registryCredentialSource(provider: RegistryProvider): CredentialSourceV1 {
   return provider.kind === "codex-subscription"
     ? { kind: "connected_subscription", provider: "codex" }
@@ -2056,21 +2424,31 @@ export function withCodexCatalogProvider(settings: Settings): Settings {
     label: "Codex (ChatGPT subscription)",
     api: "responses",
     baseUrl: CODEX_PROVIDER_BASE_URL,
-    models: CODEX_FALLBACK_MODEL_SLUGS.map((slug) => ({
-      id: `${CODEX_MODEL_ID_PREFIX}${slug}`,
-      upstreamModelId: slug,
-      label: slug,
-      reasoningEffort: true,
-      // The ChatGPT/Codex Responses backend accepts the native web_search
-      // hosted tool (unlike hosted apply_patch/computer transports). Declaring
-      // this here makes provider resolution truthful; the worker still applies
-      // the durable session/turn policy gate before attaching it.
-      hostedWebSearch: true,
-      contextWindowTokens: CODEX_MODEL_CONTEXT_WINDOW_TOKENS,
-      effectiveContextWindowTokens: CODEX_MODEL_EFFECTIVE_CONTEXT_WINDOW_TOKENS,
-      autoCompactTokenLimit: CODEX_MODEL_AUTO_COMPACT_TOKEN_LIMIT,
-      toolOutputTruncationTokens: CODEX_MODEL_TOOL_OUTPUT_TRUNCATION_TOKENS,
-    })),
+    models: CODEX_FALLBACK_MODEL_SLUGS.map((slug) => {
+      const capabilities = {
+        ...legacyModelCapabilities(settings, {
+          reasoningEffort: true,
+          hostedWebSearch: true,
+        }),
+        latencyModes: builtinLatencyModesForModel(`${CODEX_MODEL_ID_PREFIX}${slug}`),
+      };
+      return {
+        id: `${CODEX_MODEL_ID_PREFIX}${slug}`,
+        upstreamModelId: slug,
+        label: productLabelForModelId(slug),
+        reasoningEffort: true,
+        // The ChatGPT/Codex Responses backend accepts the native web_search
+        // hosted tool (unlike hosted apply_patch/computer transports). Declaring
+        // this here makes provider resolution truthful; the worker still applies
+        // the durable session/turn policy gate before attaching it.
+        hostedWebSearch: true,
+        capabilities,
+        contextWindowTokens: CODEX_MODEL_CONTEXT_WINDOW_TOKENS,
+        effectiveContextWindowTokens: CODEX_MODEL_EFFECTIVE_CONTEXT_WINDOW_TOKENS,
+        autoCompactTokenLimit: CODEX_MODEL_AUTO_COMPACT_TOKEN_LIMIT,
+        toolOutputTruncationTokens: CODEX_MODEL_TOOL_OUTPUT_TRUNCATION_TOKENS,
+      };
+    }),
   };
   return { ...settings, modelProvidersJson: JSON.stringify([...providers, provider]) };
 }
@@ -2217,14 +2595,17 @@ export function configuredModels(settings: Settings): ConfiguredModel[] {
   ])
     .filter((id) => !isRegistryNamespaced(id))
     .map((id) => {
-      const capabilities = legacyModelCapabilities(settings, {
-        reasoningEffort: true,
-        hostedWebSearch: settings.webSearchEnabled,
-      });
+      const capabilities = {
+        ...legacyModelCapabilities(settings, {
+          reasoningEffort: true,
+          hostedWebSearch: settings.webSearchEnabled,
+        }),
+        latencyModes: builtinLatencyModesForModel(id),
+      };
       return finalizeConfiguredModel(settings, builtinProvider, {
         id,
         aliases: [],
-        label: id,
+        label: productLabelForModelId(id),
         providerId: builtinId,
         providerLabel: builtinLabel,
         api: "responses" as const,
@@ -2258,7 +2639,7 @@ export function configuredModels(settings: Settings): ConfiguredModel[] {
         finalizeConfiguredModel(settings, resolvedProvider, {
           id: model.id,
           aliases: [...(model.aliases ?? [])],
-          label: model.label ?? model.id,
+          label: model.label ?? productLabelForModelId(model.id),
           providerId: provider.id,
           providerLabel,
           api: provider.api,
@@ -2345,6 +2726,8 @@ export type ResolveTurnExecutionPolicyV1Input = {
   modelSource: TurnExecutionModelSourceV1;
   reasoningEffort: Settings["openaiReasoningEffort"];
   reasoningSource: TurnExecutionReasoningSourceV1;
+  latencyMode?: LatencyMode;
+  latencyModeSource?: TurnExecutionLatencyModeSourceV1;
 };
 
 function settingsForTurnExecutionPolicy(settings: Settings, modelId: string): Settings {
@@ -2374,6 +2757,9 @@ export function resolveTurnExecutionPolicyV1(
   ) {
     throw new Error("Turn execution policy requested model does not canonicalize to its product");
   }
+  const latencyMode = LatencyMode.parse(input.latencyMode ?? "standard");
+  const latencyModeSource = input.latencyModeSource ?? "deployment";
+  assertLatencyModeRunnable(catalogSettings, productModelId, latencyMode);
   return TurnExecutionPolicyV1.parse({
     schemaVersion: 1,
     productModelId,
@@ -2381,6 +2767,8 @@ export function resolveTurnExecutionPolicyV1(
     modelSource: input.modelSource,
     reasoningEffort: input.reasoningEffort,
     reasoningSource: input.reasoningSource,
+    latencyMode,
+    latencyModeSource,
     providerId: resolved.provider.id,
     upstreamModelId: resolved.model.upstreamModelId,
     wireApi: resolved.model.api,
@@ -2401,6 +2789,7 @@ export function assertTurnExecutionPolicyMatchesConfigV1(
   expected: {
     modelId: string;
     reasoningEffort: Settings["openaiReasoningEffort"];
+    latencyMode?: LatencyMode;
   },
 ): {
   policy: TurnExecutionPolicyV1;
@@ -2410,12 +2799,17 @@ export function assertTurnExecutionPolicyMatchesConfigV1(
   const parsed = TurnExecutionPolicyV1.parse(policy);
   const catalogSettings = settingsForTurnExecutionPolicy(settings, parsed.productModelId);
   const canonicalExpectedModel = canonicalizeConfiguredModelId(catalogSettings, expected.modelId);
+  const expectedLatencyMode = expected.latencyMode ?? parsed.latencyMode;
   if (
     parsed.productModelId !== canonicalExpectedModel ||
-    parsed.reasoningEffort !== expected.reasoningEffort
+    parsed.reasoningEffort !== expected.reasoningEffort ||
+    parsed.latencyMode !== expectedLatencyMode
   ) {
-    throw new Error("Turn execution policy does not match the accepted turn model/reasoning");
+    throw new Error(
+      "Turn execution policy does not match the accepted turn model/reasoning/latency",
+    );
   }
+  assertLatencyModeRunnable(catalogSettings, parsed.productModelId, parsed.latencyMode);
   if (
     parsed.requestedModelId !== null &&
     canonicalizeConfiguredModelId(catalogSettings, parsed.requestedModelId) !==
@@ -2451,7 +2845,10 @@ export function configuredModelPricingSchedules(
   settings: Settings,
 ): Record<string, ModelPricingScheduleV1> {
   const defaults = Object.fromEntries(
-    Object.entries(defaultModelPricing).map(([model, pricing]) => [model, { default: pricing }]),
+    Object.entries(defaultModelPricing).map(([model, pricing]) => [
+      model,
+      normalizeModelPricingSchedule(pricing),
+    ]),
   );
   const registry: Record<string, ModelPricingScheduleV1> = {};
   for (const provider of parseModelProvidersJson(settings.modelProvidersJson)) {
@@ -2578,6 +2975,7 @@ export function calculateModelUsageCostMicros(
   settings: Settings,
   model: string,
   usage: ModelUsageInput,
+  options?: { latencyMode?: LatencyMode },
 ): number {
   const schedule = configuredModelPricingSchedules(settings)[model];
   if (!schedule) {
@@ -2600,6 +2998,20 @@ export function calculateModelUsageCostMicros(
     const marginBps = pricing.marginBps ?? 0;
     total += Math.ceil((rawCost * (10_000 + marginBps)) / 10_000);
   }
+  const latencyMode = options?.latencyMode ?? "standard";
+  if (latencyMode !== "standard") {
+    const catalogSettings = settingsForTurnExecutionPolicy(settings, model);
+    const resolved = resolveModelProvider(
+      catalogSettings,
+      canonicalizeConfiguredModelId(catalogSettings, model),
+    );
+    const multiplierBps = resolved?.model.capabilities.latencyModes.find(
+      (mode) => mode.id === latencyMode && mode.runnable,
+    )?.billingMultiplierBps;
+    if (multiplierBps && multiplierBps > 0) {
+      total = Math.ceil((total * multiplierBps) / 10_000);
+    }
+  }
   return total;
 }
 
@@ -3428,6 +3840,31 @@ function validateSettings(settings: Settings): void {
       );
     }
   }
+  if (Boolean(settings.googleDriveClientId) !== Boolean(settings.googleDriveClientSecret)) {
+    throw new Error(
+      "OPENGENI_GOOGLE_DRIVE_CLIENT_ID and OPENGENI_GOOGLE_DRIVE_CLIENT_SECRET must be configured together",
+    );
+  }
+  if (settings.googleDriveClientId) {
+    if (!settings.publicBaseUrl) {
+      throw new Error(
+        "OPENGENI_PUBLIC_BASE_URL is required when the Google Drive integration is configured",
+      );
+    }
+    if (
+      !settings.publicBaseUrl.startsWith("https://") &&
+      !["local", "test"].includes(settings.environment)
+    ) {
+      throw new Error(
+        "OPENGENI_PUBLIC_BASE_URL must use https when the Google Drive integration is configured outside local/test",
+      );
+    }
+    if (!settings.integrationsStateSecret) {
+      throw new Error(
+        "OPENGENI_INTEGRATIONS_STATE_SECRET is required when the Google Drive integration is configured",
+      );
+    }
+  }
   parseIntegrationsOauthClientsJson(settings.integrationsOauthClientsJson);
   if (
     settings.productAccessMode === "configured" &&
@@ -3534,7 +3971,9 @@ function validateSettings(settings: Settings): void {
     }
     if (
       settings.objectStorageBackend === "s3-compatible" &&
-      (settings.objectStorageEndpoint || settings.objectStorageSandboxEndpoint) &&
+      (settings.objectStorageEndpoint ||
+        settings.objectStorageInternalEndpoint ||
+        settings.objectStorageSandboxEndpoint) &&
       (!settings.objectStorageAccessKeyId || !settings.objectStorageSecretAccessKey)
     ) {
       throw new Error(
@@ -3564,6 +4003,7 @@ function validateSettings(settings: Settings): void {
   } else if (settings.objectStorageBackend === "azure-blob") {
     if (
       settings.objectStorageEndpoint ||
+      settings.objectStorageInternalEndpoint ||
       settings.objectStorageSandboxEndpoint ||
       settings.objectStorageAccessKeyId ||
       settings.objectStorageSecretAccessKey
@@ -3594,6 +4034,7 @@ function validateSettings(settings: Settings): void {
   } else {
     if (
       settings.objectStorageEndpoint ||
+      settings.objectStorageInternalEndpoint ||
       settings.objectStorageSandboxEndpoint ||
       settings.objectStorageAccessKeyId ||
       settings.objectStorageSecretAccessKey
@@ -3642,12 +4083,13 @@ function validateSettings(settings: Settings): void {
   //     out from under us — the provider lifetime is the backstop, not the
   //     warm-window controller. idleGrace counts from the user's last release;
   //     the provider clock counts from the preceding resume, so we leave the
-  //     active-turn headroom in modalTimeoutSeconds (default 3600s).
+  //     active-turn headroom in modalTimeoutSeconds (default 86400s).
   {
     const reaperPeriod = settings.sandboxLeaseReaperPeriodMs;
     const viewerTtl = settings.sandboxViewerHolderTtlMs;
     const idleGraceMs = settings.sandboxIdleGraceMs;
     const providerLifetimeMs = settings.modalTimeoutSeconds * 1000;
+    const rotationLeadMs = settings.sandboxRotationLeadMs;
     // The EFFECTIVE box lifetime when it sits idle between turns is the Modal IDLE
     // timeout, NOT the hard lifetime (sandbox-file-persistence): a box with no
     // active connection is idle-reaped at idleTimeout. effectiveModalIdleTimeout
@@ -3670,6 +4112,18 @@ function validateSettings(settings: Settings): void {
           `floor under the hard lifetime, not above it.`,
       );
     }
+    if (!(rotationLeadMs < providerLifetimeMs)) {
+      throw new Error(
+        `OPENGENI_SANDBOX_ROTATION_LEAD_MS (${rotationLeadMs}) must be strictly less than ` +
+          `OPENGENI_MODAL_TIMEOUT_SECONDS*1000 (${providerLifetimeMs}).`,
+      );
+    }
+    if (!(rotationLeadMs > settings.sandboxSnapshotTimeoutMs + 2 * reaperPeriod)) {
+      throw new Error(
+        `OPENGENI_SANDBOX_ROTATION_LEAD_MS (${rotationLeadMs}) must exceed the snapshot timeout ` +
+          `plus two reaper periods (${settings.sandboxSnapshotTimeoutMs + 2 * reaperPeriod}).`,
+      );
+    }
     if (!(viewerTtl < idleTimeoutMs)) {
       throw new Error(
         `OPENGENI_SANDBOX_VIEWER_HOLDER_TTL_MS (${viewerTtl}) must be strictly less than the effective box ` +