@opengeni/config 0.4.0 → 0.5.0

package/src/index.ts

@@ -9,7 +9,7 @@ import {
   StaticUsageLimits,
   UsageLimitsMode,
 } from "@opengeni/contracts";
-import { CODEX_MODEL_ID_PREFIX } from "@opengeni/codex/constants";
+import { CODEX_MODEL_ID_PREFIX, CODEX_PROVIDER_ID } from "@opengeni/codex/constants";
 import { z } from "zod";
 
 const envName = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -81,10 +81,10 @@ export const AGENT_INSTRUCTIONS_CORE_PLACEHOLDER = "{{core}}";
  * baked into this overridable string.
  *
  * INVARIANT: with no per-workspace override and an empty environment, the
- * runtime's composed instructions are BYTE-IDENTICAL to the historical
- * hardcoded preamble. The template below is exactly the historical lines 1–11
- * joined by " ", followed by " " + the placeholder. Changing a single
- * character here changes that default; a runtime test pins it.
+ * runtime's composed instructions are byte-for-byte pinned by a runtime test.
+ * The template below is joined by " ", followed by " " + the placeholder.
+ * Changing a single character here changes that default; update the pin
+ * intentionally.
  */
 export const DEFAULT_AGENT_INSTRUCTIONS = [
   "You are an OpenGeni workspace agent.",
@@ -94,21 +94,23 @@ export const DEFAULT_AGENT_INSTRUCTIONS = [
   "File resources are mounted under files/<file-id>/ unless the session specifies another mount path.",
   "Attached files are mounted read-only; copy them before modifying.",
   "Bundled skills are under .agents/ and can include infrastructure, marketing, or other role-specific guidance.",
-  "Use Checkov, Terraform, Azure CLI, GitHub CLI, and repository tools when relevant.",
+  "Use Checkov, Terraform, Azure CLI, git provider CLIs, and repository tools when relevant; gh, glab, and az repos are pre-authenticated when the host brokers matching git credentials.",
   "When the Azure sandbox preparation profile is enabled and service-principal variables are present, the sandbox is pre-authenticated with normal Azure CLI before work starts.",
-  "Treat code-changing work as GitOps work: create a focused branch/commit/PR when GitHub credentials are available; otherwise report exact commands and blockers.",
+  "Treat code-changing work as GitOps work: create a focused branch/commit/PR when git provider credentials are available; otherwise report exact commands and blockers.",
   "Return concise, factual summaries with files changed, commands run, and remaining blockers.",
   AGENT_INSTRUCTIONS_CORE_PLACEHOLDER,
 ].join(" ");
 
-export const McpServerConnectionRefSchema = z.object({
-  connectionId: z.string().uuid().optional(),
-  providerDomain: z.string().min(1),
-  kind: z.enum(["oauth2", "api_key", "app_install", "delegated"]).optional(),
-  scopes: z.array(z.string().min(1)).optional(),
-  resource: z.string().min(1).optional(),
-  subjectScope: z.enum(["workspace", "subject"]).optional(),
-}).strict();
+export const McpServerConnectionRefSchema = z
+  .object({
+    connectionId: z.string().uuid().optional(),
+    providerDomain: z.string().min(1),
+    kind: z.enum(["oauth2", "api_key", "app_install", "delegated"]).optional(),
+    scopes: z.array(z.string().min(1)).optional(),
+    resource: z.string().min(1).optional(),
+    subjectScope: z.enum(["workspace", "subject"]).optional(),
+  })
+  .strict();
 export type McpServerConnectionRef = z.infer<typeof McpServerConnectionRefSchema>;
 
 const SettingsSchema = z.object({
@@ -144,7 +146,10 @@ const SettingsSchema = z.object({
   // 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>` (or `/latest/download/<asset>`).
-  agentReleasesBaseUrl: z.string().url().default("https://github.com/Cloudgeni-ai/opengeni/releases"),
+  agentReleasesBaseUrl: z
+    .string()
+    .url()
+    .default("https://github.com/Cloudgeni-ai/opengeni/releases"),
   productAccessMode: ProductAccessMode.default("local"),
   billingMode: BillingMode.default("disabled"),
   entitlementsMode: EntitlementsMode.default("none"),
@@ -176,62 +181,45 @@ const SettingsSchema = z.object({
   // it then acts as a hard ceiling that per-goal overrides can only lower.
   goalMaxAutoContinuations: z.coerce.number().int().positive().optional(),
   goalNoProgressLimit: z.coerce.number().int().positive().default(3),
+  // Temporary safety valve: spawned child sessions still run and retain their
+  // own durable events/goals, but terminal child episodes do not create parent
+  // system updates or inference work unless explicitly enabled.
+  childCompletionParentWakeEnabled: EnvBoolean.default(false),
   // Per-segment ceiling on agent loop turns (model calls) within a single
   // session turn. Effectively unbounded by default for the same reason as
   // above; the graceful max-turns valve (idle + goal continuation, never a
   // session failure) remains as inert safety should a deployment set a cap.
   agentMaxModelCallsPerTurn: z.coerce.number().int().positive().default(1_000_000),
-  // Where turn-input conversation history comes from (issue #35):
-  // "items" (default) = the session_history_items table (SDK-native,
-  // version-stable conversation truth); "run_state" = the legacy serialized
-  // RunState blob. Items and the sandbox envelope are dual-written
-  // unconditionally; this flag governs the read path only, so flipping back to
-  // "run_state" remains a safe rollback at any time.
-  sessionHistorySource: z.enum(["run_state", "items"]).default("items"),
-  // Provider-aware conversation context management (long-lived sessions
-  // otherwise grow unbounded until they overflow the model context window and
-  // hard-fail every turn). Resolution (see resolveContextCompactionMode):
-  //   "auto" (default) -> "server" when openaiProvider === "openai" (the
-  //     OpenAI platform Responses API honors server-side context_management),
-  //     else "client" (Azure rejects context_management with a 400, so we run
-  //     our own client-side compaction).
-  //   "server" / "client" -> force that path regardless of provider.
-  //   "off" -> neither path (legacy unbounded growth; escape hatch only).
-  contextCompactionMode: z.enum(["auto", "server", "client", "off"]).default("auto"),
-  // The model's real context window in tokens. gpt-5.5's true window is
-  // 1,050,000; it is absent from the SDK's hardcoded compaction window map (it
-  // knows only up to gpt-5.4), so the SDK's DynamicCompactionPolicy would fall
-  // back to a wrong 240k. We pass an explicit StaticCompactionPolicy threshold
-  // derived from these settings on the server path, and use the same numbers to
-  // budget the client path.
+  // The model family's real context window in tokens. OpenGeni always performs
+  // one durable, portable plaintext compaction transition; there is no
+  // provider/server/off mode ladder.
   contextWindowTokens: z.coerce.number().int().positive().default(1_050_000),
+  // Optional model-catalog effective input ceiling. Codex models expose this as
+  // raw context_window * effective_context_window_percent; when absent, retain
+  // the deployment-level window-minus-reserved-output behavior.
+  contextEffectiveWindowTokens: z.coerce.number().int().positive().optional(),
   // Proactive compaction threshold as a ratio of the model context window.
-  // Defaults to 60% and is clamped to [0.3, 0.9] so deployments can tune the
-  // trigger without accidentally disabling compaction or waiting until the
-  // provider is already at the cliff.
-  contextCompactionThresholdRatio: z.coerce.number().default(0.6).transform((value) => {
-    if (!Number.isFinite(value)) {
-      return 0.6;
-    }
-    return Math.min(0.9, Math.max(0.3, value));
-  }),
+  // Defaults to 90%: compact as late as possible — retained context beats early
+  // headroom now that per-model windows are declared honestly (input-effective,
+  // empirically measured), and the fail-closed reactive compact-on-reject path
+  // absorbs any overshoot as one retried call rather than a dead session.
+  // Clamped to [0.3, 0.9] so deployments can tune the trigger without
+  // accidentally disabling compaction.
+  contextCompactionThresholdRatio: z.coerce
+    .number()
+    .default(0.9)
+    .transform((value) => {
+      if (!Number.isFinite(value)) {
+        return 0.9;
+      }
+      return Math.min(0.9, Math.max(0.3, value));
+    }),
   // Tokens reserved for model output; subtracted from the window to get the
   // usable input budget B = contextWindowTokens - contextReservedOutputTokens.
   contextReservedOutputTokens: z.coerce.number().int().nonnegative().default(128_000),
-  // Server path only: explicit compact_threshold (tokens) handed to the SDK's
-  // StaticCompactionPolicy. Defaults to floor(contextWindowTokens *
-  // contextCompactionThresholdRatio) when unset.
-  contextServerCompactThresholdTokens: z.coerce.number().int().positive().optional(),
-  // Deprecated back-compat knobs. The threshold is now controlled by
-  // contextCompactionThresholdRatio; these remain parsed so older deployments do
-  // not fail boot when their env still contains them.
-  contextCompactSoftFraction: z.coerce.number().positive().max(1).default(0.70),
-  contextCompactHardFraction: z.coerce.number().positive().max(1).default(0.85),
-  // Deprecated for the client path; parsed for env/back-compat only.
-  contextKeepRecentTokens: z.coerce.number().int().positive().default(32_000),
-  // Parsed for back-compat. Client compaction uses the fixed 20k Codex summary
-  // buffer as its generated-summary output ceiling.
-  contextSummaryMaxTokens: z.coerce.number().int().positive().default(20_000),
+  // Model-catalog auto-compact limit. When present it is clamped to
+  // 90% of the raw window, matching Codex core's auto_compact_token_limit().
+  contextAutoCompactThresholdTokens: z.coerce.number().int().positive().optional(),
   authRequired: EnvBoolean.default(false),
   accessKey: z.string().optional(),
   authAllowHealth: EnvBoolean.default(true),
@@ -244,8 +232,8 @@ const SettingsSchema = z.object({
   openaiProvider: z.enum(["openai", "azure"]).default("openai"),
   openaiApiKey: z.string().optional(),
   openaiBaseUrl: z.string().optional(),
-  openaiModel: z.string().default("gpt-5.5"),
-  openaiAllowedModels: z.string().default("gpt-5.5,gpt-5.4,gpt-5.4-mini"),
+  openaiModel: z.string().default("gpt-5.6-sol"),
+  openaiAllowedModels: z.string().default("gpt-5.6-sol,gpt-5.6-terra,gpt-5.6-luna"),
   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
@@ -257,14 +245,19 @@ const SettingsSchema = z.object({
   // Codex (ChatGPT) subscription: when enabled, a per-workspace connected
   // subscription is injected as a synthetic "codex-subscription" registry
   // provider whose models route through the ChatGPT backend (@opengeni/codex).
-  codexSubscriptionEnabled: EnvBoolean.default(false),  // OPENGENI_CODEX_SUBSCRIPTION_ENABLED
-  codexProductSku: z.string().optional(),               // OPENGENI_CODEX_PRODUCT_SKU (X-OpenAI-Product-Sku, apps only)
+  codexSubscriptionEnabled: EnvBoolean.default(false), // OPENGENI_CODEX_SUBSCRIPTION_ENABLED
+  codexProductSku: z.string().optional(), // OPENGENI_CODEX_PRODUCT_SKU (X-OpenAI-Product-Sku, apps only)
   // Progressive connector disclosure (Codex-CLI-style tool_search): on a codex
   // turn, flag the ~217 codex_apps connector tools `defer_loading:true` (dropping
   // their schemas from model context) and add one client-executed tool_search
   // tool that BM25-discloses only the matching connectors. Default OFF — a codex
   // turn is byte-for-byte unchanged until enabled. OPENGENI_CODEX_TOOL_SEARCH_ENABLED
   codexToolSearchEnabled: EnvBoolean.default(false),
+  // OPE-21 atomic, workspace-local credential allocation. Default OFF is a
+  // deliberate rolling-deploy fence: migrate + roll every worker first, then
+  // enable. Turning it off restores the legacy sticky selector without a schema
+  // rollback; the additive lease table/cursor columns become inert.
+  codexCredentialLeasingEnabled: EnvBoolean.default(false),
   // Multi-account P3 (auto-rotation): an account is "near exhaustion" — ineligible to be
   // rotated TO — when EITHER usage window (5h/weekly) is at/over this percent. Default 90 to
   // match the UI danger flip (UsageBar danger at pct >= 90). OPENGENI_CODEX_ROTATION_NEAR_EXHAUSTION_PCT.
@@ -302,7 +295,7 @@ const SettingsSchema = z.object({
   // the non-bypassable CORE at AGENT_INSTRUCTIONS_CORE_PLACEHOLDER (or appends
   // it when the template omits the marker), and uses the result as the agent's
   // instructions. Defaulting to DEFAULT_AGENT_INSTRUCTIONS keeps the composed
-  // default byte-identical to the historical hardcoded preamble.
+  // default pinned by runtime tests.
   agentInstructionsTemplate: z.string().default(DEFAULT_AGENT_INSTRUCTIONS),
   azureOpenaiBaseUrl: z.string().optional(),
   azureOpenaiEndpoint: z.string().optional(),
@@ -409,6 +402,13 @@ const SettingsSchema = z.object({
   // recordingMaxSeconds is the ffmpeg -t hard ceiling (bounds a multi-day turn).
   recordingEnabled: EnvBoolean.default(true),
   recordingDefaultCodec: z.enum(["h264-mp4", "vp9-webm"]).default("h264-mp4"),
+  // Workbench v2 turn-end workspace capture (dossier §10.1). When on, the turn
+  // activity probes the box's changed files off the live box at turn end and
+  // persists a capture revision (blobs in @opengeni/storage) so the workbench
+  // paints cold/offline sessions with zero machine round-trips. Best-effort and
+  // fully behind this flag: off ⇒ capture is skipped and reads fall back to the
+  // live/wake path (status-quo behavior). Default on; explicit per environment.
+  workspaceCaptureEnabled: EnvBoolean.default(true),
   recordingFramerate: z.coerce.number().int().positive().default(15),
   recordingMaxSeconds: z.coerce.number().int().positive().default(600),
   recordingMaxBytes: z.coerce.number().int().positive().default(268_435_456), // 256 MB
@@ -462,6 +462,19 @@ const SettingsSchema = z.object({
   // EnvBoolean (NOT z.coerce.boolean(), which would coerce "false" -> true and
   // turn the flag ON the moment anyone set the env var to disable it).
   sandboxOwnershipEnabled: EnvBoolean.default(false),
+  // --- lazy sandbox provisioning rollout flag, default OFF ---
+  // Only effective when sandboxOwnershipEnabled is ALSO on (lazy provisioning is a
+  // property of the owned path — the SDK never creates/resumes an injected session,
+  // so we control when the box is established). When TRUE, a turn does NOT provision
+  // its box at turn start: the lease acquire + resume-by-id + hooks + downloads +
+  // heartbeat + recording are deferred to an in-process single-flight provisioner
+  // that runs the FIRST time a sandbox op is dispatched (via the routing proxy's
+  // resolveActiveBackend). A turn whose model never calls a sandbox-backed tool ends
+  // with NO lease row and ZERO warm-seconds. When FALSE (or ownership off) the turn
+  // provisions eagerly exactly as today — byte-for-byte. EnvBoolean (NOT
+  // z.coerce.boolean(), which coerces "false" -> true and would turn the flag ON the
+  // moment anyone set the env var to disable it).
+  sandboxLazyProvisionEnabled: EnvBoolean.default(false),
   // --- bring-your-own-compute (selfhosted 11th backend) rollout flag, default OFF ---
   // The keystone flag for the whole selfhosted feature (the enrollment device-flow,
   // the NATS control plane, the relay stream tier). When FALSE the enrollment routes
@@ -470,6 +483,11 @@ const SettingsSchema = z.object({
   // z.coerce.boolean(), which coerces "false" -> true). Flipped per-environment via
   // the deploy-staging IaC secret/configmap pattern (dossier §17/§25.1).
   sandboxSelfhostedEnabled: EnvBoolean.default(false),
+  // Gates the op-stream (streaming exec) transport to Connected Machines. The
+  // runner must ALSO advertise Capabilities.op_stream; default off, and legacy
+  // request/reply exec is the permanent fallback. EnvBoolean (NOT
+  // z.coerce.boolean(), which coerces "false" -> true).
+  agentOpStreamEnabled: EnvBoolean.default(false),
   // The HMAC secret the control plane signs the enrollment bearer credential with
   // (the `oge_` envelope the agent presents back to the control plane). Optional:
   // when ABSENT and sandboxSelfhostedEnabled is on, the poll route reports the
@@ -526,6 +544,25 @@ const SettingsSchema = z.object({
   // bus connects anonymously (local dev / a NATS with no auth_callout).
   selfhostedNatsControlUser: z.string().optional(),
   selfhostedNatsControlPassword: z.string().optional(),
+  // --- selfhosted (Connected Machine) control/exec op deadlines ---------------
+  // The control plane splits its op deadline in two. CONTROL ops (ping / fs / git /
+  // desktop / pty) must stay responsive so a machine's liveness is never masked by a
+  // slow op, so they use the short control timeout. EXEC gets its OWN, larger budget:
+  // a real command (compile, test run, dependency install) routinely outlives the
+  // control timeout, and before the split a long command was killed at the ~30s
+  // control wall. The agent kills the exec child at this deadline; the wire waits
+  // slightly longer (SELFHOSTED_EXEC_REPLY_GRACE_MS) for the typed timed-out reply.
+  //
+  // The exec default is a DELIBERATELY MODEST 2min (not 5): the agent-side admission
+  // pool is (until a later agent release) a FLAT 8 permits with no per-class split,
+  // so 8 slow execs holding a permit for 5 minutes would blanket-DRAIN every fs/git
+  // op — shipping the amplifier before the class-aware-admission fix. 2min still
+  // clears the large majority of the observed >30s exec tail; genuinely long jobs run
+  // in the background (see the exec-deadline hint) or raise the knob per deployment.
+  // Knobs: OPENGENI_SANDBOX_SELFHOSTED_EXEC_TIMEOUT_MS (default 2min) and
+  // OPENGENI_SANDBOX_SELFHOSTED_CONTROL_TIMEOUT_MS (default 30s).
+  sandboxSelfhostedExecTimeoutMs: z.coerce.number().int().positive().default(120_000),
+  sandboxSelfhostedControlTimeoutMs: z.coerce.number().int().positive().default(30_000),
   // --- sandbox lease cadences (cadence invariant validated at boot below) ---
   // reaperPeriod < viewerHolderTTL, and reaperPeriod + idleGrace < the EFFECTIVE
   // box idle timeout (effectiveModalIdleTimeoutSeconds, which defaults to the hard
@@ -544,6 +581,22 @@ const SettingsSchema = z.object({
   // fresh EMPTY box; lower it to trade warm cost for a snappier reclaim. 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
+  // that dies any other way (Modal's hard creation-time timeout on a session
+  // busy past it, provider OOM/infra death) loses everything since the last
+  // clean drain. While a turn holds the box, the turn heartbeat and turn-end
+  // both take a snapshot when at least this interval has passed since the last
+  // one (same epoch-fenced fold-onto-lease seam as the drain), bounding the
+  // worst-case loss of ANY unclean box death to this window. 0 disables.
+  // Knob: OPENGENI_SANDBOX_SNAPSHOT_INTERVAL_MS. Default 15min.
+  sandboxSnapshotIntervalMs: z.coerce.number().int().min(0).default(900_000),
+  // Maximum time a best-effort /workspace snapshot capture may hold turn/reaper
+  // cleanup. A hung provider snapshot must never pin a lease holder, block
+  // graceful shutdown, or become permission to GC an older archive. Timeout is
+  // 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),
   // 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.
@@ -553,6 +606,11 @@ const SettingsSchema = z.object({
   // (a liveness/reaper cadence), this bounds how long one turn waits for capacity
   // or provider creation before surfacing a clear turn.failed error.
   sandboxWarmingTimeoutMs: z.coerce.number().int().positive().default(600_000),
+  // Rig setup-script budget (M3): the wall-clock timeout the rig-setup lifecycle
+  // hook runs its script under, distinct from the 120s per-command lifecycle
+  // default (a rig may compile/install heavy tooling on first cold create).
+  // Env: OPENGENI_RIG_SETUP_TIMEOUT_MS. Default 10min.
+  rigSetupTimeoutMs: z.coerce.number().int().positive().default(600_000),
   // --- sandbox warm-time billing (P2.1) ---
   // Per-backend warm rate (usd_micros/sec), like modelPricingJson: an empty {}
   // means warm-cost is not debited (warm-seconds are still metered for audit).
@@ -568,7 +626,9 @@ const SettingsSchema = z.object({
   sandboxEnvAllowlist: z.string().default(""),
   objectStorageEndpoint: z.string().url().optional(),
   objectStorageSandboxEndpoint: z.string().url().optional(),
-  objectStorageBackend: z.enum(["s3-compatible", "aws-s3", "azure-blob", "gcs"]).default("s3-compatible"),
+  objectStorageBackend: z
+    .enum(["s3-compatible", "aws-s3", "azure-blob", "gcs"])
+    .default("s3-compatible"),
   objectStorageBucket: z.string().min(1).default("opengeni-files"),
   objectStorageRegion: z.string().min(1).default("us-east-1"),
   objectStorageS3Provider: z.string().min(1).default("Minio"),
@@ -613,30 +673,34 @@ const SettingsSchema = z.object({
   stripePublishableKey: z.string().optional(),
   stripeWebhookSecret: z.string().optional(),
   stripeCreditsProductId: z.string().optional(),
-  mcpServers: z.array(z.object({
-    id: z.string().min(1).regex(registryId),
-    name: z.string().min(1).optional(),
-    url: z.string().url(),
-    allowedTools: z.array(z.string().min(1)).optional(),
-    timeoutMs: z.number().int().positive().optional(),
-    cacheToolsList: z.boolean().default(false),
-    /**
-     * Human-approval policy for this server's tools, overlaid per-run from a
-     * session MCP server row (never from OPENGENI_MCP_SERVERS). `true` = all
-     * tools require approval; a string[] = only the listed UNPREFIXED tool
-     * names do; absent = auto-run (the historical default). Enforced in the
-     * runtime by attaching `needsApproval` to the matching MCP tools.
-     */
-    requireApproval: z.union([z.boolean(), z.array(z.string().min(1))]).optional(),
-    /**
-     * Extra request headers sent to this MCP server (credential injection
-     * for workspace-enabled capability MCPs). Populated at runtime from
-     * encrypted capability-installation credentials; do not put secrets in
-     * OPENGENI_MCP_SERVERS.
-     */
-    headers: z.record(z.string(), z.string()).optional(),
-    connectionRef: McpServerConnectionRefSchema.optional(),
-  })).default([]),
+  mcpServers: z
+    .array(
+      z.object({
+        id: z.string().min(1).regex(registryId),
+        name: z.string().min(1).optional(),
+        url: z.string().url(),
+        allowedTools: z.array(z.string().min(1)).optional(),
+        timeoutMs: z.number().int().positive().optional(),
+        cacheToolsList: z.boolean().default(false),
+        /**
+         * Human-approval policy for this server's tools, overlaid per-run from a
+         * session MCP server row (never from OPENGENI_MCP_SERVERS). `true` = all
+         * tools require approval; a string[] = only the listed UNPREFIXED tool
+         * names do; absent = auto-run (the historical default). Enforced in the
+         * runtime by attaching `needsApproval` to the matching MCP tools.
+         */
+        requireApproval: z.union([z.boolean(), z.array(z.string().min(1))]).optional(),
+        /**
+         * Extra request headers sent to this MCP server (credential injection
+         * for workspace-enabled capability MCPs). Populated at runtime from
+         * encrypted capability-installation credentials; do not put secrets in
+         * OPENGENI_MCP_SERVERS.
+         */
+        headers: z.record(z.string(), z.string()).optional(),
+        connectionRef: McpServerConnectionRefSchema.optional(),
+      }),
+    )
+    .default([]),
 });
 
 export type Settings = z.infer<typeof SettingsSchema>;
@@ -685,23 +749,25 @@ export type RegistryProviderKind = z.infer<typeof RegistryProviderKind>;
 
 /** A single model exposed by a registry provider. */
 const RegistryModelSchema = z.object({
-  id: z.string().min(1),                 // model id sent to the provider, e.g. "accounts/fireworks/models/glm-5p2"
-  label: z.string().min(1).optional(),   // display name; defaults to id
+  id: z.string().min(1), // model id sent to the provider, e.g. "accounts/fireworks/models/glm-5p2"
+  label: z.string().min(1).optional(), // display name; defaults to id
   contextWindowTokens: z.number().int().positive().optional(),
-  reasoningEffort: z.boolean().optional(),  // model accepts a reasoning-effort control
-  hostedWebSearch: z.boolean().optional(),  // provider executes the hosted web_search tool for this model
+  effectiveContextWindowTokens: z.number().int().positive().optional(),
+  autoCompactTokenLimit: z.number().int().positive().optional(),
+  reasoningEffort: z.boolean().optional(), // model accepts a reasoning-effort control
+  hostedWebSearch: z.boolean().optional(), // provider executes the hosted web_search tool for this model
   pricing: ModelPricingSchema.optional(),
 });
 
 /** A non-built-in provider declared by the host via OPENGENI_MODEL_PROVIDERS_JSON. */
 const RegistryProviderSchema = z.object({
-  kind: RegistryProviderKind.default("api-key"),  // "codex-subscription" => per-request token, no static key
-  id: z.string().min(1).regex(registryId),  // stable provider id, e.g. "fireworks"
+  kind: RegistryProviderKind.default("api-key"), // "codex-subscription" => per-request token, no static key
+  id: z.string().min(1).regex(registryId), // stable provider id, e.g. "fireworks"
   label: z.string().min(1).optional(),
   api: ModelProviderApi.default("chat"),
   baseUrl: z.string().url(),
-  apiKey: z.string().optional(),         // inline key (pragmatic) ...
-  apiKeyEnv: z.string().optional(),      // ... OR name of the env var holding the key (preferred)
+  apiKey: z.string().optional(), // inline key (pragmatic) ...
+  apiKeyEnv: z.string().optional(), // ... OR name of the env var holding the key (preferred)
   defaultQuery: z.record(z.string(), z.string()).optional(),
   defaultHeaders: z.record(z.string(), z.string()).optional(),
   models: z.array(RegistryModelSchema).min(1),
@@ -711,28 +777,29 @@ export type RegistryProvider = z.infer<typeof RegistryProviderSchema>;
 export const IntegrationOAuthClientConfigSchema = z.object({
   clientId: z.string().min(1),
   clientSecret: z.string().min(1).optional(),
-  tokenEndpointAuthMethod: z.enum(["none", "client_secret_post", "client_secret_basic"]).default("none"),
+  tokenEndpointAuthMethod: z
+    .enum(["none", "client_secret_post", "client_secret_basic"])
+    .default("none"),
 });
 export type IntegrationOAuthClientConfig = z.infer<typeof IntegrationOAuthClientConfigSchema>;
 
 /**
  * Runtime-resolved provider (built-in or registry), client-construction-ready.
  * The built-in OpenAI/Azure provider is always present and always "responses";
- * registry providers carry their own base URL / key / wire API. compactionMode
- * is "server" only for the built-in OpenAI platform provider (its Responses API
- * honors server-side context_management) and "client" for everything else.
+ * registry providers carry their own base URL / key / wire API. Compaction is
+ * not a provider capability: all providers use the same durable plaintext
+ * replacement.
  */
 export interface ResolvedModelProvider {
-  id: string;                  // "openai" | "azure" | registry id
+  id: string; // "openai" | "azure" | registry id
   label: string;
-  kind: RegistryProviderKind;  // "api-key" (built-ins + most registry) | "codex-subscription"
+  kind: RegistryProviderKind; // "api-key" (built-ins + most registry) | "codex-subscription"
   api: ModelProviderApi;
   builtin: boolean;
   baseUrl?: string | undefined;
   apiKey?: string | undefined;
   defaultQuery?: Record<string, string> | undefined;
   defaultHeaders?: Record<string, string> | undefined;
-  compactionMode: ContextCompactionMode;   // "server" only for built-in OpenAI; "client" otherwise
 }
 
 /** A single exposed model + the provider that serves it. */
@@ -743,17 +810,31 @@ export interface ConfiguredModel {
   providerLabel: string;
   api: ModelProviderApi;
   contextWindowTokens?: number | undefined;
+  effectiveContextWindowTokens?: number | undefined;
+  autoCompactTokenLimit?: number | undefined;
   reasoningEffort: boolean;
   hostedWebSearch: boolean;
 }
 
 export const defaultModelPricing: Record<string, ModelPricing> = {
-  "gpt-5.5": {
+  "gpt-5.6-sol": {
     inputMicrosPerMillionTokens: 5_000_000,
     cachedInputMicrosPerMillionTokens: 500_000,
     outputMicrosPerMillionTokens: 30_000_000,
     marginBps: 2_500,
   },
+  "gpt-5.6-terra": {
+    inputMicrosPerMillionTokens: 2_500_000,
+    cachedInputMicrosPerMillionTokens: 250_000,
+    outputMicrosPerMillionTokens: 15_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,
@@ -839,7 +920,10 @@ export type SandboxRequiredEnv = {
   env: string;
 };
 
-export const SANDBOX_REQUIRED_ENV: Record<z.infer<typeof SandboxBackend>, readonly SandboxRequiredEnv[]> = {
+export const SANDBOX_REQUIRED_ENV: Record<
+  z.infer<typeof SandboxBackend>,
+  readonly SandboxRequiredEnv[]
+> = {
   // docker/local/none need no credentials (local dev container / in-process / off).
   docker: [],
   local: [],
@@ -849,21 +933,11 @@ export const SANDBOX_REQUIRED_ENV: Record<z.infer<typeof SandboxBackend>, readon
     { field: "modalTokenId", env: "OPENGENI_MODAL_TOKEN_ID" },
     { field: "modalTokenSecret", env: "OPENGENI_MODAL_TOKEN_SECRET" },
   ],
-  daytona: [
-    { field: "daytonaApiKey", env: "OPENGENI_DAYTONA_API_KEY" },
-  ],
-  runloop: [
-    { field: "runloopApiKey", env: "OPENGENI_RUNLOOP_API_KEY" },
-  ],
-  e2b: [
-    { field: "e2bApiKey", env: "OPENGENI_E2B_API_KEY" },
-  ],
-  blaxel: [
-    { field: "blaxelApiKey", env: "OPENGENI_BLAXEL_API_KEY" },
-  ],
-  cloudflare: [
-    { field: "cloudflareWorkerUrl", env: "OPENGENI_CLOUDFLARE_WORKER_URL" },
-  ],
+  daytona: [{ field: "daytonaApiKey", env: "OPENGENI_DAYTONA_API_KEY" }],
+  runloop: [{ field: "runloopApiKey", env: "OPENGENI_RUNLOOP_API_KEY" }],
+  e2b: [{ field: "e2bApiKey", env: "OPENGENI_E2B_API_KEY" }],
+  blaxel: [{ field: "blaxelApiKey", env: "OPENGENI_BLAXEL_API_KEY" }],
+  cloudflare: [{ field: "cloudflareWorkerUrl", env: "OPENGENI_CLOUDFLARE_WORKER_URL" }],
   vercel: [
     { field: "vercelToken", env: "OPENGENI_VERCEL_TOKEN" },
     { field: "vercelProjectId", env: "OPENGENI_VERCEL_PROJECT_ID" },
@@ -889,7 +963,10 @@ export function getSettings(): Settings {
   const raw = {
     serviceName: optional("OPENGENI_SERVICE_NAME"),
     environment: optional("OPENGENI_ENVIRONMENT"),
-    deploymentRevision: optional("OPENGENI_DEPLOYMENT_REVISION") ?? optional("SOURCE_VERSION") ?? optional("GITHUB_SHA"),
+    deploymentRevision:
+      optional("OPENGENI_DEPLOYMENT_REVISION") ??
+      optional("SOURCE_VERSION") ??
+      optional("GITHUB_SHA"),
     serverVersion: optional("OPENGENI_SERVER_VERSION"),
     databaseUrl: optional("OPENGENI_DATABASE_URL"),
     dbSchema: optional("OPENGENI_DB_SCHEMA"),
@@ -899,12 +976,16 @@ export function getSettings(): Settings {
     temporalNamespace: optional("OPENGENI_TEMPORAL_NAMESPACE"),
     temporalTaskQueue: optional("OPENGENI_TEMPORAL_TASK_QUEUE"),
     startupDependencyRetryAttempts: optional("OPENGENI_STARTUP_DEPENDENCY_RETRY_ATTEMPTS"),
-    startupDependencyRetryInitialDelayMs: optional("OPENGENI_STARTUP_DEPENDENCY_RETRY_INITIAL_DELAY_MS"),
+    startupDependencyRetryInitialDelayMs: optional(
+      "OPENGENI_STARTUP_DEPENDENCY_RETRY_INITIAL_DELAY_MS",
+    ),
     startupDependencyRetryMaxDelayMs: optional("OPENGENI_STARTUP_DEPENDENCY_RETRY_MAX_DELAY_MS"),
     observabilityStructuredLogs: optional("OPENGENI_OBSERVABILITY_STRUCTURED_LOGS"),
     observabilityMetricsEnabled: optional("OPENGENI_OBSERVABILITY_METRICS_ENABLED"),
-    observabilityOtlpEndpoint: optional("OPENGENI_OTEL_EXPORTER_OTLP_ENDPOINT") ?? optional("OTEL_EXPORTER_OTLP_ENDPOINT"),
-    observabilityOtlpHeaders: optional("OPENGENI_OTEL_EXPORTER_OTLP_HEADERS") ?? optional("OTEL_EXPORTER_OTLP_HEADERS"),
+    observabilityOtlpEndpoint:
+      optional("OPENGENI_OTEL_EXPORTER_OTLP_ENDPOINT") ?? optional("OTEL_EXPORTER_OTLP_ENDPOINT"),
+    observabilityOtlpHeaders:
+      optional("OPENGENI_OTEL_EXPORTER_OTLP_HEADERS") ?? optional("OTEL_EXPORTER_OTLP_HEADERS"),
     publicBaseUrl: optional("OPENGENI_PUBLIC_BASE_URL"),
     agentReleasesBaseUrl: optional("OPENGENI_AGENT_RELEASES_BASE_URL"),
     productAccessMode: optional("OPENGENI_PRODUCT_ACCESS_MODE"),
@@ -921,21 +1002,19 @@ export function getSettings(): Settings {
     environmentsEncryptionKey: optional("OPENGENI_ENVIRONMENTS_ENCRYPTION_KEY"),
     integrationsEnabled: optional("OPENGENI_INTEGRATIONS_ENABLED"),
     integrationsStateSecret: optional("OPENGENI_INTEGRATIONS_STATE_SECRET"),
-    integrationsAllowPrivateNetworkTargets: optional("OPENGENI_INTEGRATIONS_ALLOW_PRIVATE_NETWORK_TARGETS"),
+    integrationsAllowPrivateNetworkTargets: optional(
+      "OPENGENI_INTEGRATIONS_ALLOW_PRIVATE_NETWORK_TARGETS",
+    ),
     integrationsOauthClientsJson: optional("OPENGENI_INTEGRATIONS_OAUTH_CLIENTS_JSON"),
     goalMaxAutoContinuations: optional("OPENGENI_GOAL_MAX_AUTO_CONTINUATIONS"),
     goalNoProgressLimit: optional("OPENGENI_GOAL_NO_PROGRESS_LIMIT"),
+    childCompletionParentWakeEnabled: optional("OPENGENI_CHILD_COMPLETION_PARENT_WAKE_ENABLED"),
     agentMaxModelCallsPerTurn: optional("OPENGENI_AGENT_MAX_MODEL_CALLS_PER_TURN"),
-    sessionHistorySource: optional("OPENGENI_SESSION_HISTORY_SOURCE"),
-    contextCompactionMode: optional("OPENGENI_CONTEXT_COMPACTION_MODE"),
     contextWindowTokens: optional("OPENGENI_CONTEXT_WINDOW_TOKENS"),
+    contextEffectiveWindowTokens: optional("OPENGENI_CONTEXT_EFFECTIVE_WINDOW_TOKENS"),
     contextCompactionThresholdRatio: optional("OPENGENI_COMPACTION_THRESHOLD_RATIO"),
     contextReservedOutputTokens: optional("OPENGENI_CONTEXT_RESERVED_OUTPUT_TOKENS"),
-    contextServerCompactThresholdTokens: optional("OPENGENI_CONTEXT_SERVER_COMPACT_THRESHOLD_TOKENS"),
-    contextCompactSoftFraction: optional("OPENGENI_CONTEXT_COMPACT_SOFT_FRACTION"),
-    contextCompactHardFraction: optional("OPENGENI_CONTEXT_COMPACT_HARD_FRACTION"),
-    contextKeepRecentTokens: optional("OPENGENI_CONTEXT_KEEP_RECENT_TOKENS"),
-    contextSummaryMaxTokens: optional("OPENGENI_CONTEXT_SUMMARY_MAX_TOKENS"),
+    contextAutoCompactThresholdTokens: optional("OPENGENI_CONTEXT_AUTO_COMPACT_THRESHOLD_TOKENS"),
     authRequired: optional("OPENGENI_AUTH_REQUIRED"),
     accessKey: optional("OPENGENI_ACCESS_KEY"),
     authAllowHealth: optional("OPENGENI_AUTH_ALLOW_HEALTH"),
@@ -954,6 +1033,7 @@ export function getSettings(): Settings {
     modelProvidersJson: optional("OPENGENI_MODEL_PROVIDERS_JSON"),
     codexSubscriptionEnabled: optional("OPENGENI_CODEX_SUBSCRIPTION_ENABLED"),
     codexToolSearchEnabled: optional("OPENGENI_CODEX_TOOL_SEARCH_ENABLED"),
+    codexCredentialLeasingEnabled: optional("OPENGENI_CODEX_CREDENTIAL_LEASING_ENABLED"),
     codexProductSku: optional("OPENGENI_CODEX_PRODUCT_SKU"),
     codexRotationNearExhaustionPct: optional("OPENGENI_CODEX_ROTATION_NEAR_EXHAUSTION_PCT"),
     openaiReasoningEffort: optional("OPENGENI_OPENAI_REASONING_EFFORT"),
@@ -993,6 +1073,7 @@ export function getSettings(): Settings {
     computerUseEnabled: optional("OPENGENI_COMPUTER_USE_ENABLED"),
     computerUseReadOnly: optional("OPENGENI_COMPUTER_USE_READONLY"),
     recordingEnabled: optional("OPENGENI_RECORDING_ENABLED"),
+    workspaceCaptureEnabled: optional("OPENGENI_WORKSPACE_CAPTURE"),
     recordingDefaultCodec: optional("OPENGENI_RECORDING_DEFAULT_CODEC"),
     recordingFramerate: optional("OPENGENI_RECORDING_FRAMERATE"),
     recordingMaxSeconds: optional("OPENGENI_RECORDING_MAX_SECONDS"),
@@ -1032,7 +1113,9 @@ export function getSettings(): Settings {
     vercelTeamId: optional("OPENGENI_VERCEL_TEAM_ID"),
     vercelRuntime: optional("OPENGENI_VERCEL_RUNTIME"),
     sandboxOwnershipEnabled: optional("OPENGENI_SANDBOX_OWNERSHIP_ENABLED"),
+    sandboxLazyProvisionEnabled: optional("OPENGENI_SANDBOX_LAZY_PROVISION"),
     sandboxSelfhostedEnabled: optional("OPENGENI_SANDBOX_SELFHOSTED_ENABLED"),
+    agentOpStreamEnabled: optional("OPENGENI_AGENT_OP_STREAM_ENABLED"),
     enrollmentSigningSecret: optional("OPENGENI_ENROLLMENT_SIGNING_SECRET"),
     selfhostedNatsUrl: optional("OPENGENI_SELFHOSTED_NATS_URL"),
     selfhostedRelayUrl: optional("OPENGENI_SELFHOSTED_RELAY_URL"),
@@ -1044,13 +1127,20 @@ export function getSettings(): Settings {
     selfhostedNatsCalloutPassword: optional("OPENGENI_SELFHOSTED_NATS_CALLOUT_PASSWORD"),
     selfhostedNatsControlUser: optional("OPENGENI_SELFHOSTED_NATS_CONTROL_USER"),
     selfhostedNatsControlPassword: optional("OPENGENI_SELFHOSTED_NATS_CONTROL_PASSWORD"),
+    sandboxSelfhostedExecTimeoutMs: optional("OPENGENI_SANDBOX_SELFHOSTED_EXEC_TIMEOUT_MS"),
+    sandboxSelfhostedControlTimeoutMs: optional("OPENGENI_SANDBOX_SELFHOSTED_CONTROL_TIMEOUT_MS"),
     sandboxLeaseReaperPeriodMs: optional("OPENGENI_SANDBOX_LEASE_REAPER_PERIOD_MS"),
     sandboxViewerHolderTtlMs: optional("OPENGENI_SANDBOX_VIEWER_HOLDER_TTL_MS"),
     sandboxIdleGraceMs: optional("OPENGENI_SANDBOX_IDLE_GRACE_MS"),
+    sandboxSnapshotIntervalMs: optional("OPENGENI_SANDBOX_SNAPSHOT_INTERVAL_MS"),
+    sandboxSnapshotTimeoutMs: optional("OPENGENI_SANDBOX_SNAPSHOT_TIMEOUT_MS"),
     sandboxLeaseTtlMs: optional("OPENGENI_SANDBOX_LEASE_TTL_MS"),
     sandboxLeaseWarmingTtlMs: optional("OPENGENI_SANDBOX_LEASE_WARMING_TTL_MS"),
     sandboxWarmingTimeoutMs: optional("OPENGENI_SANDBOX_WARMING_TIMEOUT_MS"),
-    sandboxWarmRateMicrosPerSecondJson: optional("OPENGENI_SANDBOX_WARM_RATE_MICROS_PER_SECOND_JSON"),
+    rigSetupTimeoutMs: optional("OPENGENI_RIG_SETUP_TIMEOUT_MS"),
+    sandboxWarmRateMicrosPerSecondJson: optional(
+      "OPENGENI_SANDBOX_WARM_RATE_MICROS_PER_SECOND_JSON",
+    ),
     sandboxMaxWarmSecondsPerWorkspace: optional("OPENGENI_SANDBOX_MAX_WARM_SECONDS_PER_WORKSPACE"),
     sandboxPreparationProfiles: optional("OPENGENI_SANDBOX_PREPARATION_PROFILES"),
     sandboxEnvAllowlist: optional("OPENGENI_SANDBOX_ENV_ALLOWLIST"),
@@ -1127,7 +1217,10 @@ export function effectiveModalIdleTimeoutSeconds(settings: Settings): number {
   return settings.modalIdleTimeoutSeconds ?? settings.modalTimeoutSeconds;
 }
 
-export function collectSandboxEnvironment(settings: Settings, source: NodeJS.ProcessEnv = process.env): Record<string, string> {
+export function collectSandboxEnvironment(
+  settings: Settings,
+  source: NodeJS.ProcessEnv = process.env,
+): Record<string, string> {
   const out: Record<string, string> = {};
   for (const name of sandboxEnvironmentVariableNames(settings)) {
     const value = source[name];
@@ -1159,8 +1252,14 @@ export function resolveProviderApiKey(
   return undefined;
 }
 
-/** The built-in provider's stable id: "openai" on the OpenAI platform, "azure" on Azure. */
-function builtinProviderId(settings: Pick<Settings, "openaiProvider">): string {
+/**
+ * The built-in provider's stable id: "openai" on the OpenAI platform, "azure"
+ * on Azure. Exported because the workspace model-policy gate must attribute
+ * the legacy resolveTurnModel-null fallback (which routes to this built-in
+ * client) to the SAME identity the router uses — otherwise a policy blocking
+ * the built-in could be bypassed through the null-resolution path.
+ */
+export function builtinProviderId(settings: Pick<Settings, "openaiProvider">): string {
   return settings.openaiProvider === "azure" ? "azure" : "openai";
 }
 
@@ -1170,9 +1269,8 @@ function builtinProviderLabel(settings: Pick<Settings, "openaiProvider">): strin
 
 /**
  * Every provider a client may route to: the built-in OpenAI/Azure provider
- * first (id "openai"/"azure", always "responses", compactionMode from
- * resolveContextCompactionMode), then each registry provider in declaration
- * order (compactionMode "client"). Client-construction inputs are filled from
+ * first (id "openai"/"azure", always "responses"), then each registry provider
+ * in declaration order. Client-construction inputs are filled from
  * the existing flat openai/azure settings for the built-in, and from the
  * registry entry for the rest. Registry ids may not collide with the built-in
  * id — validateSettings rejects that at boot.
@@ -1184,7 +1282,6 @@ export function configuredProviders(settings: Settings): ResolvedModelProvider[]
     kind: "api-key",
     api: "responses",
     builtin: true,
-    compactionMode: resolveContextCompactionMode(settings),
   };
   if (settings.openaiProvider === "azure") {
     builtin.baseUrl = settings.azureOpenaiBaseUrl ?? settings.azureOpenaiEndpoint;
@@ -1193,21 +1290,43 @@ export function configuredProviders(settings: Settings): ResolvedModelProvider[]
     builtin.baseUrl = settings.openaiBaseUrl;
     builtin.apiKey = settings.openaiApiKey;
   }
-  const registry = parseModelProvidersJson(settings.modelProvidersJson).map((provider): ResolvedModelProvider => ({
-    id: provider.id,
-    label: provider.label ?? provider.id,
-    kind: provider.kind,
-    api: provider.api,
-    builtin: false,
-    baseUrl: provider.baseUrl,
-    apiKey: resolveProviderApiKey(provider),
-    defaultQuery: provider.defaultQuery,
-    defaultHeaders: provider.defaultHeaders,
-    compactionMode: "client",
-  }));
+  const registry = parseModelProvidersJson(settings.modelProvidersJson).map(
+    (provider): ResolvedModelProvider => ({
+      id: provider.id,
+      label: provider.label ?? provider.id,
+      kind: provider.kind,
+      api: provider.api,
+      builtin: false,
+      baseUrl: provider.baseUrl,
+      apiKey: resolveProviderApiKey(provider),
+      defaultQuery: provider.defaultQuery,
+      defaultHeaders: provider.defaultHeaders,
+    }),
+  );
   return [builtin, ...registry];
 }
 
+/**
+ * The provider identity a model id resolves to, for workspace model-policy
+ * evaluation — MUST agree with the real router (resolveTurnModel /
+ * MultiProviderModelProvider) on every case:
+ *   - `codex/<slug>` → the codex-subscription provider id, ALWAYS. With no
+ *     active subscription the router fails loud (CodexSubscriptionUnavailableError),
+ *     never the built-in — so attributing by prefix is exact even against BASE
+ *     settings where the overlay provider is not injected.
+ *   - a configured model id → its configuredModels providerId (registry or built-in).
+ *   - anything else → the built-in id: an unknown id is the legacy
+ *     resolveTurnModel-null fallback, which the built-in OpenAI/Azure client
+ *     serves. A policy blocking the built-in must block this path too.
+ */
+export function policyProviderIdForModel(settings: Settings, modelId: string): string {
+  if (modelId.startsWith(CODEX_MODEL_ID_PREFIX)) {
+    return CODEX_PROVIDER_ID;
+  }
+  const configured = configuredModels(settings).find((model) => model.id === modelId);
+  return configured?.providerId ?? builtinProviderId(settings);
+}
+
 /**
  * Every model a client may use, the built-in provider's models first
  * (configuredAllowedModels-from-openai, mapped to "responses" with
@@ -1230,17 +1349,22 @@ export function configuredModels(settings: Settings): ConfiguredModel[] {
   // contains "/") that a registry actually owns is never a valid Azure/OpenAI
   // deployment name, and a `codex/`-prefixed id never is either — exclude both
   // from the built-in list. A BARE id a registry merely redeclares (e.g.
-  // "gpt-5.5") is left in place so the built-in still wins it via the first-wins
+  // "gpt-5.6-sol") is left in place so the built-in still wins it via the first-wins
   // de-dup below (preserving the documented built-in-precedence contract). When
   // a codex/ id has NO codex provider injected (no active subscription) it then
   // resolves to nothing and getModel fails loud with
   // CodexSubscriptionUnavailableError instead of mis-routing to Azure.
   const registryOwnedIds = new Set(
-    parseModelProvidersJson(settings.modelProvidersJson).flatMap((provider) => provider.models.map((model) => model.id)),
+    parseModelProvidersJson(settings.modelProvidersJson).flatMap((provider) =>
+      provider.models.map((model) => model.id),
+    ),
   );
   const isRegistryNamespaced = (id: string): boolean =>
     id.startsWith(CODEX_MODEL_ID_PREFIX) || (id.includes("/") && registryOwnedIds.has(id));
-  const out: ConfiguredModel[] = uniqueValues([settings.openaiModel, ...splitCsv(settings.openaiAllowedModels)])
+  const out: ConfiguredModel[] = uniqueValues([
+    settings.openaiModel,
+    ...splitCsv(settings.openaiAllowedModels),
+  ])
     .filter((id) => !isRegistryNamespaced(id))
     .map((id) => ({
       id,
@@ -1261,7 +1385,15 @@ export function configuredModels(settings: Settings): ConfiguredModel[] {
         providerId: provider.id,
         providerLabel,
         api: provider.api,
-        ...(model.contextWindowTokens === undefined ? {} : { contextWindowTokens: model.contextWindowTokens }),
+        ...(model.contextWindowTokens === undefined
+          ? {}
+          : { contextWindowTokens: model.contextWindowTokens }),
+        ...(model.effectiveContextWindowTokens === undefined
+          ? {}
+          : { effectiveContextWindowTokens: model.effectiveContextWindowTokens }),
+        ...(model.autoCompactTokenLimit === undefined
+          ? {}
+          : { autoCompactTokenLimit: model.autoCompactTokenLimit }),
         reasoningEffort: model.reasoningEffort ?? false,
         hostedWebSearch: model.hostedWebSearch ?? false,
       });
@@ -1302,7 +1434,9 @@ export function resolveModelProvider(
   if (!model) {
     return undefined;
   }
-  const provider = configuredProviders(settings).find((candidate) => candidate.id === model.providerId);
+  const provider = configuredProviders(settings).find(
+    (candidate) => candidate.id === model.providerId,
+  );
   if (!provider) {
     return undefined;
   }
@@ -1332,49 +1466,49 @@ export function configuredModelPricing(settings: Settings): Record<string, Model
 }
 
 /**
- * Resolved conversation-context compaction path for a run.
- *  - "server": let the OpenAI platform Responses API compact server-side (the
- *    SDK emits context_management; we pass the correct gpt-5.5 threshold).
- *  - "client": run OpenGeni's own client-side compaction (Azure and any other
- *    backend that rejects/ignores context_management).
- *  - "off": neither (legacy unbounded growth; escape hatch).
- *
- * "auto" maps to "server" on the OpenAI platform provider and "client"
- * otherwise — Azure's Responses API returns 400 unsupported_parameter for
- * context_management, so it must never take the server path.
+ * Usable input-token budget: an explicit model-catalog effective window when
+ * available, otherwise the deployment window minus its output reserve.
  */
-export type ContextCompactionMode = "server" | "client" | "off";
-
-export function resolveContextCompactionMode(settings: Pick<Settings, "contextCompactionMode" | "openaiProvider">): ContextCompactionMode {
-  switch (settings.contextCompactionMode) {
-    case "server":
-      return "server";
-    case "client":
-      return "client";
-    case "off":
-      return "off";
-    case "auto":
-    default:
-      return settings.openaiProvider === "openai" ? "server" : "client";
+export function contextInputBudgetTokens(
+  settings: Pick<
+    Settings,
+    "contextWindowTokens" | "contextEffectiveWindowTokens" | "contextReservedOutputTokens"
+  >,
+): number {
+  if (settings.contextEffectiveWindowTokens !== undefined) {
+    return Math.min(settings.contextWindowTokens, settings.contextEffectiveWindowTokens);
   }
-}
-
-/** Usable input-token budget B = window - reserved output. */
-export function contextInputBudgetTokens(settings: Pick<Settings, "contextWindowTokens" | "contextReservedOutputTokens">): number {
   return Math.max(0, settings.contextWindowTokens - settings.contextReservedOutputTokens);
 }
 
 /**
- * Server-path compact_threshold (tokens) handed to the SDK's
- * StaticCompactionPolicy: the explicit override when set, else
- * floor(B * softFraction). This is what sidesteps the SDK's wrong 240k
- * fallback for gpt-5.5 (which is absent from its hardcoded window map).
+ * Apply the resolved provider/model's context policy to one turn. Registry
+ * metadata is authoritative when present; deployment defaults remain the
+ * fallback for models that do not declare their own limits.
  */
-export function contextServerCompactThreshold(settings: Pick<Settings, "contextWindowTokens" | "contextReservedOutputTokens" | "contextServerCompactThresholdTokens" | "contextCompactSoftFraction" | "contextCompactionThresholdRatio">): number {
-  if (settings.contextServerCompactThresholdTokens) {
-    return settings.contextServerCompactThresholdTokens;
-  }
-  return Math.floor(settings.contextWindowTokens * settings.contextCompactionThresholdRatio);
+export function settingsWithResolvedModelContext(
+  settings: Settings,
+  model: Pick<
+    ConfiguredModel,
+    "contextWindowTokens" | "effectiveContextWindowTokens" | "autoCompactTokenLimit"
+  >,
+): Settings {
+  const contextWindowTokens = model.contextWindowTokens ?? settings.contextWindowTokens;
+  return {
+    ...settings,
+    contextWindowTokens,
+    ...(model.effectiveContextWindowTokens === undefined
+      ? {}
+      : {
+          contextEffectiveWindowTokens: Math.min(
+            contextWindowTokens,
+            model.effectiveContextWindowTokens,
+          ),
+        }),
+    ...(model.autoCompactTokenLimit === undefined
+      ? {}
+      : { contextAutoCompactThresholdTokens: model.autoCompactTokenLimit }),
+  };
 }
 
 export function configuredStaticUsageLimits(settings: Settings): StaticUsageLimitsConfig {
@@ -1399,20 +1533,31 @@ export function configuredEntitlements(settings: Settings): EntitlementsConfig {
   };
 }
 
-export function calculateModelUsageCostMicros(settings: Settings, model: string, usage: ModelUsageInput): number {
+export function calculateModelUsageCostMicros(
+  settings: Settings,
+  model: string,
+  usage: ModelUsageInput,
+): number {
   const pricing = configuredModelPricing(settings)[model];
   if (!pricing) {
     throw new Error(`Missing model pricing for ${model}`);
   }
-  const entries = usage.requestUsageEntries && usage.requestUsageEntries.length > 0 ? usage.requestUsageEntries : [usage];
+  const entries =
+    usage.requestUsageEntries && usage.requestUsageEntries.length > 0
+      ? usage.requestUsageEntries
+      : [usage];
   const rawCost = entries.reduce((sum, entry) => sum + calculateEntryCostMicros(pricing, entry), 0);
   const marginBps = pricing.marginBps ?? 0;
-  return Math.ceil(rawCost * (10_000 + marginBps) / 10_000);
+  return Math.ceil((rawCost * (10_000 + marginBps)) / 10_000);
 }
 
-export function configuredAllowedReasoningEfforts(settings: Settings): Array<z.infer<typeof ReasoningEffort>> {
-  return uniqueValues([settings.openaiReasoningEffort, ...splitCsv(settings.openaiAllowedReasoningEfforts)])
-    .map((value) => ReasoningEffort.parse(value));
+export function configuredAllowedReasoningEfforts(
+  settings: Settings,
+): Array<z.infer<typeof ReasoningEffort>> {
+  return uniqueValues([
+    settings.openaiReasoningEffort,
+    ...splitCsv(settings.openaiAllowedReasoningEfforts),
+  ]).map((value) => ReasoningEffort.parse(value));
 }
 
 /**
@@ -1426,7 +1571,9 @@ export function environmentsEncryptionKeyBytes(settings: Settings): Uint8Array |
   }
   const decoded = Buffer.from(settings.environmentsEncryptionKey, "base64");
   if (decoded.length !== 32) {
-    throw new Error("OPENGENI_ENVIRONMENTS_ENCRYPTION_KEY must be base64 for exactly 32 bytes (generate with: openssl rand -base64 32)");
+    throw new Error(
+      "OPENGENI_ENVIRONMENTS_ENCRYPTION_KEY must be base64 for exactly 32 bytes (generate with: openssl rand -base64 32)",
+    );
   }
   return new Uint8Array(decoded);
 }
@@ -1453,12 +1600,24 @@ export function dbSearchPath(settings: Pick<Settings, "dbSchema">): string | und
 }
 
 export function collectGitIdentityEnvironment(settings: Settings): Record<string, string> {
-  return Object.fromEntries(Object.entries({
-    GIT_AUTHOR_NAME: settings.gitAuthorName,
-    GIT_AUTHOR_EMAIL: settings.gitAuthorEmail,
-    GIT_COMMITTER_NAME: settings.gitCommitterName ?? settings.gitAuthorName,
-    GIT_COMMITTER_EMAIL: settings.gitCommitterEmail ?? settings.gitAuthorEmail,
-  }).filter((entry): entry is [string, string] => typeof entry[1] === "string" && entry[1].trim().length > 0));
+  return Object.fromEntries(
+    Object.entries({
+      GIT_AUTHOR_NAME: settings.gitAuthorName,
+      GIT_AUTHOR_EMAIL: settings.gitAuthorEmail,
+      GIT_COMMITTER_NAME: settings.gitCommitterName ?? settings.gitAuthorName,
+      GIT_COMMITTER_EMAIL: settings.gitCommitterEmail ?? settings.gitAuthorEmail,
+    }).filter(
+      (entry): entry is [string, string] =>
+        typeof entry[1] === "string" && entry[1].trim().length > 0,
+    ),
+  );
+}
+
+const DEFAULT_SANDBOX_PATH = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+
+function prependPathEntry(pathValue: string | undefined, entry: string): string {
+  const parts = (pathValue ?? DEFAULT_SANDBOX_PATH).split(":").filter(Boolean);
+  return [entry, ...parts.filter((part) => part !== entry)].join(":");
 }
 
 /**
@@ -1476,20 +1635,22 @@ export function collectGitIdentityEnvironment(settings: Settings): Record<string
  * workspace environment < the backend-aware HOME default. Reserved-name validation
  * at write time keeps workspace values from colliding with platform entries.
  *
- * DELIBERATELY EXCLUDES the per-run, ROTATING GitHub App installation token
- * VALUE that `sandboxEnvironmentForRun` mints when a repository resource is
+ * DELIBERATELY EXCLUDES the per-run, ROTATING git provider token VALUES that
+ * `sandboxEnvironmentForRun` mints when a repository resource is
  * attached: that token is minted FRESH per call, so it is not a stable, attach-
  * reproducible value and must not be part of the shared base. Under the token-
- * broker (B1) the token VALUE never rides the manifest at all — it is seeded to a
- * FILE inside the box (agent-managed, refreshable mid-turn via the `github_token`
- * MCP tool) and git auth flows through GIT_ASKPASS -> that file. What IS stable and
- * lives here is the token FILE PATH (`OPENGENI_GIT_TOKEN_FILE`): a constant derived
- * from HOME, so it appears IDENTICALLY on BOTH the turn AND every attach manifest
- * (the SDK's per-turn provided-session env delta stays empty even as the token
- * rotates). The attach surfaces have only the `Session` (no repo resources) and so
- * never seed a token, but the file-path pointer is harmless (an unwritten file
- * simply yields no auth); the BLOCKING attach-vs-turn error this helper fixes is
- * for the common (no-repo) and workspace-environment-attached cases.
+ * broker (B1) token VALUES never ride the manifest at all — they are seeded to
+ * FILES inside the box and git/provider CLI auth reads those files. What IS stable
+ * and lives here for provisioned boxes are the token directory / GitHub alias
+ * FILE PATH and wrapper PATH entries: constants derived from HOME, so they
+ * appear IDENTICALLY on BOTH the turn AND every attach manifest (the SDK's
+ * per-turn provided-session env delta stays empty even as tokens rotate). These
+ * helper pointers are deliberately not added for selfhosted/local/none because
+ * the platform never mints or seeds git provider tokens there. The attach
+ * surfaces have only the `Session` (no repo resources) and so never seed a token,
+ * but unwritten files simply yield no auth; the BLOCKING attach-vs-turn error
+ * this helper fixes is for the common (no-repo) and workspace-environment-attached
+ * provisioned-box cases.
  */
 export function stableSandboxEnvironmentForRun(
   settings: Settings,
@@ -1508,18 +1669,30 @@ export function stableSandboxEnvironmentForRun(
   if (settings.sandboxBackend !== "none" && settings.sandboxBackend !== "local") {
     environment.HOME ??= descriptor.workspaceRoot;
   }
-  // TOKEN-BROKER (B1): the STABLE token FILE PATH. A constant derived from the
-  // resolved HOME (falling back to the descriptor workspaceRoot), so it is
-  // parity-safe — it joins the shared base and therefore appears IDENTICALLY on
-  // BOTH the worker-turn manifest AND every API-direct attach manifest, keeping
-  // the SDK's provided-session env delta empty. Only the PATH is stable; the token
-  // VALUE lives exclusively in the file (agent-managed, refreshable mid-turn), never
-  // the manifest env.
-  environment.OPENGENI_GIT_TOKEN_FILE ??= `${environment.HOME ?? descriptor.workspaceRoot}/.opengeni/git-token`;
+  // TOKEN-BROKER (B1): the STABLE credential FILE PATHS and CLI wrapper PATH for
+  // provisioned boxes only. Constants derived from the resolved HOME (falling
+  // back to the descriptor workspaceRoot), so they are parity-safe — they join
+  // the shared base and therefore appear IDENTICALLY on BOTH the worker-turn
+  // manifest AND every API-direct attach manifest. Only PATHS are stable; token
+  // VALUES live exclusively in files that runtime seeds off-manifest.
+  const provisionedGitHelperBackend =
+    settings.sandboxBackend !== "none" &&
+    settings.sandboxBackend !== "local" &&
+    settings.sandboxBackend !== "selfhosted";
+  if (provisionedGitHelperBackend) {
+    const home = environment.HOME ?? descriptor.workspaceRoot;
+    environment.OPENGENI_GIT_CREDENTIALS_DIR ??= `${home}/.opengeni/git-credentials`;
+    environment.OPENGENI_GIT_TOKEN_FILE ??= `${home}/.opengeni/git-token`;
+    environment.OPENGENI_GIT_CLI_WRAPPER_DIR ??= `${home}/.opengeni/bin`;
+    environment.PATH = prependPathEntry(environment.PATH, environment.OPENGENI_GIT_CLI_WRAPPER_DIR);
+  }
   if (settings.toolspaceEnabled) {
     environment.OPENGENI_TOOLSPACE_TOKEN_FILE ??= `${environment.HOME ?? descriptor.workspaceRoot}/.opengeni/toolspace-token`;
     if (options.workspaceId) {
-      environment.OPENGENI_TOOLSPACE_URL ??= firstPartyMcpWorkspaceUrl(settings, options.workspaceId);
+      environment.OPENGENI_TOOLSPACE_URL ??= firstPartyMcpWorkspaceUrl(
+        settings,
+        options.workspaceId,
+      );
     }
   }
   return environment;
@@ -1532,11 +1705,45 @@ export function stableSandboxEnvironmentForRun(
  * an attach-warmed cold box carries the IDENTICAL manifest env a later repo turn
  * declares (env parity — see applyGitAuthPointerEnvironment).
  */
-export function hasGitHubRepositorySelection(resources: ReadonlyArray<{ kind: string; githubInstallationId?: unknown; githubRepositoryId?: unknown }>): boolean {
+export function hasGitHubRepositorySelection(
+  resources: ReadonlyArray<{
+    kind: string;
+    provider?: unknown;
+    installationId?: unknown;
+    repositoryId?: unknown;
+    githubInstallationId?: unknown;
+    githubRepositoryId?: unknown;
+  }>,
+): boolean {
   const positive = (value: unknown): boolean =>
-    (typeof value === "number" && Number.isInteger(value) && value > 0)
-    || (typeof value === "string" && /^\d+$/.test(value) && Number(value) > 0);
-  return resources.some((resource) => resource.kind === "repository" && positive(resource.githubInstallationId) && positive(resource.githubRepositoryId));
+    (typeof value === "number" && Number.isInteger(value) && value > 0) ||
+    (typeof value === "string" && /^\d+$/.test(value) && Number(value) > 0);
+  return resources.some(
+    (resource) =>
+      resource.kind === "repository" &&
+      ((positive(resource.githubInstallationId) && positive(resource.githubRepositoryId)) ||
+        (resource.provider === "github" &&
+          positive(resource.installationId) &&
+          positive(resource.repositoryId))),
+  );
+}
+
+export function hasGitCredentialRepositorySelection(
+  resources: ReadonlyArray<{
+    kind: string;
+    provider?: unknown;
+    githubInstallationId?: unknown;
+    githubRepositoryId?: unknown;
+  }>,
+): boolean {
+  return resources.some(
+    (resource) =>
+      resource.kind === "repository" &&
+      (resource.provider === "github" ||
+        resource.provider === "gitlab" ||
+        resource.provider === "azure_devops" ||
+        hasGitHubRepositorySelection([resource])),
+  );
 }
 
 /**
@@ -1584,7 +1791,9 @@ export type StartupRetryOptions = {
   }) => void;
 };
 
-export function startupRetryOptions(settings: Settings): Required<Omit<StartupRetryOptions, "onRetry">> {
+export function startupRetryOptions(
+  settings: Settings,
+): Required<Omit<StartupRetryOptions, "onRetry">> {
   return {
     attempts: settings.startupDependencyRetryAttempts,
     initialDelayMs: settings.startupDependencyRetryInitialDelayMs,
@@ -1634,10 +1843,14 @@ export function sandboxLifecycleHookIds(settings: Settings): string[] {
 }
 
 function sandboxPreparationProfileNames(settings: Settings): string[] {
-  const profiles = splitCsv(settings.sandboxPreparationProfiles).map((value) => value.toLowerCase());
+  const profiles = splitCsv(settings.sandboxPreparationProfiles).map((value) =>
+    value.toLowerCase(),
+  );
   if (profiles.includes("none")) {
     if (profiles.length > 1) {
-      throw new Error("OPENGENI_SANDBOX_PREPARATION_PROFILES cannot combine none with other profiles");
+      throw new Error(
+        "OPENGENI_SANDBOX_PREPARATION_PROFILES cannot combine none with other profiles",
+      );
     }
     return ["none"];
   }
@@ -1671,7 +1884,7 @@ export function parseMcpServers(raw: string | undefined): unknown[] | undefined
     return parsed;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`OPENGENI_MCP_SERVERS must be a JSON array: ${message}`);
+    throw new Error(`OPENGENI_MCP_SERVERS must be a JSON array: ${message}`, { cause: error });
   }
 }
 
@@ -1684,7 +1897,7 @@ export function parseModelPricingJson(raw: string): Record<string, ModelPricing>
     parsed = JSON.parse(raw);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`OPENGENI_MODEL_PRICING_JSON must be valid JSON: ${message}`);
+    throw new Error(`OPENGENI_MODEL_PRICING_JSON must be valid JSON: ${message}`, { cause: error });
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
     throw new Error("OPENGENI_MODEL_PRICING_JSON must be a JSON object keyed by model name");
@@ -1712,19 +1925,28 @@ export function parseSandboxWarmRateJson(raw: string): Record<string, number> {
     parsed = JSON.parse(raw);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`OPENGENI_SANDBOX_WARM_RATE_MICROS_PER_SECOND_JSON must be valid JSON: ${message}`);
+    throw new Error(
+      `OPENGENI_SANDBOX_WARM_RATE_MICROS_PER_SECOND_JSON must be valid JSON: ${message}`,
+      { cause: error },
+    );
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error("OPENGENI_SANDBOX_WARM_RATE_MICROS_PER_SECOND_JSON must be a JSON object keyed by backend name");
+    throw new Error(
+      "OPENGENI_SANDBOX_WARM_RATE_MICROS_PER_SECOND_JSON must be a JSON object keyed by backend name",
+    );
   }
   const out: Record<string, number> = {};
   for (const [backend, value] of Object.entries(parsed)) {
     if (!backend.trim()) {
-      throw new Error("OPENGENI_SANDBOX_WARM_RATE_MICROS_PER_SECOND_JSON contains an empty backend name");
+      throw new Error(
+        "OPENGENI_SANDBOX_WARM_RATE_MICROS_PER_SECOND_JSON contains an empty backend name",
+      );
     }
     const rate = typeof value === "number" ? value : Number(value);
     if (!Number.isFinite(rate) || rate < 0) {
-      throw new Error(`OPENGENI_SANDBOX_WARM_RATE_MICROS_PER_SECOND_JSON rate for ${backend} must be a non-negative number`);
+      throw new Error(
+        `OPENGENI_SANDBOX_WARM_RATE_MICROS_PER_SECOND_JSON rate for ${backend} must be a non-negative number`,
+      );
     }
     out[backend] = rate;
   }
@@ -1752,7 +1974,9 @@ export function parseModelProvidersJson(raw: string): RegistryProvider[] {
     parsed = JSON.parse(raw);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`OPENGENI_MODEL_PROVIDERS_JSON must be valid JSON: ${message}`);
+    throw new Error(`OPENGENI_MODEL_PROVIDERS_JSON must be valid JSON: ${message}`, {
+      cause: error,
+    });
   }
   if (!Array.isArray(parsed)) {
     throw new Error("OPENGENI_MODEL_PROVIDERS_JSON must be a JSON array of providers");
@@ -1760,13 +1984,17 @@ export function parseModelProvidersJson(raw: string): RegistryProvider[] {
   return parsed.map((entry, index) => {
     const result = RegistryProviderSchema.safeParse(entry);
     if (!result.success) {
-      throw new Error(`OPENGENI_MODEL_PROVIDERS_JSON provider[${index}] is invalid: ${result.error.message}`);
+      throw new Error(
+        `OPENGENI_MODEL_PROVIDERS_JSON provider[${index}] is invalid: ${result.error.message}`,
+      );
     }
     return result.data;
   });
 }
 
-export function parseIntegrationsOauthClientsJson(raw: string | undefined): Record<string, IntegrationOAuthClientConfig> {
+export function parseIntegrationsOauthClientsJson(
+  raw: string | undefined,
+): Record<string, IntegrationOAuthClientConfig> {
   if (!raw?.trim() || raw.trim() === "{}") {
     return {};
   }
@@ -1775,10 +2003,14 @@ export function parseIntegrationsOauthClientsJson(raw: string | undefined): Reco
     parsed = JSON.parse(raw);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`OPENGENI_INTEGRATIONS_OAUTH_CLIENTS_JSON must be valid JSON: ${message}`);
+    throw new Error(`OPENGENI_INTEGRATIONS_OAUTH_CLIENTS_JSON must be valid JSON: ${message}`, {
+      cause: error,
+    });
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error("OPENGENI_INTEGRATIONS_OAUTH_CLIENTS_JSON must be a JSON object keyed by authorization-server issuer or URL");
+    throw new Error(
+      "OPENGENI_INTEGRATIONS_OAUTH_CLIENTS_JSON must be a JSON object keyed by authorization-server issuer or URL",
+    );
   }
   const out: Record<string, IntegrationOAuthClientConfig> = {};
   for (const [key, value] of Object.entries(parsed)) {
@@ -1787,7 +2019,9 @@ export function parseIntegrationsOauthClientsJson(raw: string | undefined): Reco
     }
     const result = IntegrationOAuthClientConfigSchema.safeParse(value);
     if (!result.success) {
-      throw new Error(`OPENGENI_INTEGRATIONS_OAUTH_CLIENTS_JSON client for ${key} is invalid: ${result.error.message}`);
+      throw new Error(
+        `OPENGENI_INTEGRATIONS_OAUTH_CLIENTS_JSON client for ${key} is invalid: ${result.error.message}`,
+      );
     }
     out[key] = result.data;
   }
@@ -1803,7 +2037,9 @@ export function parseStaticUsageLimitsJson(raw: string): StaticUsageLimitsConfig
     parsed = JSON.parse(raw);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`OPENGENI_STATIC_USAGE_LIMITS_JSON must be valid JSON: ${message}`);
+    throw new Error(`OPENGENI_STATIC_USAGE_LIMITS_JSON must be valid JSON: ${message}`, {
+      cause: error,
+    });
   }
   return StaticUsageLimits.parse(parsed);
 }
@@ -1817,7 +2053,9 @@ export function parseStaticEntitlementsJson(raw: string): EntitlementsConfig {
     parsed = JSON.parse(raw);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`OPENGENI_STATIC_ENTITLEMENTS_JSON must be valid JSON: ${message}`);
+    throw new Error(`OPENGENI_STATIC_ENTITLEMENTS_JSON must be valid JSON: ${message}`, {
+      cause: error,
+    });
   }
   return Entitlements.parse(parsed);
 }
@@ -1827,10 +2065,13 @@ function calculateEntryCostMicros(pricing: ModelPricing, entry: ModelUsageInput)
   const outputTokens = positiveInt(entry.outputTokens);
   const cachedTokens = Math.min(inputTokens, cachedInputTokens(entry));
   const uncachedInputTokens = Math.max(0, inputTokens - cachedTokens);
-  const cachedInputRate = pricing.cachedInputMicrosPerMillionTokens ?? pricing.inputMicrosPerMillionTokens;
-  return Math.ceil((uncachedInputTokens * pricing.inputMicrosPerMillionTokens) / 1_000_000)
-    + Math.ceil((cachedTokens * cachedInputRate) / 1_000_000)
-    + Math.ceil((outputTokens * pricing.outputMicrosPerMillionTokens) / 1_000_000);
+  const cachedInputRate =
+    pricing.cachedInputMicrosPerMillionTokens ?? pricing.inputMicrosPerMillionTokens;
+  return (
+    Math.ceil((uncachedInputTokens * pricing.inputMicrosPerMillionTokens) / 1_000_000) +
+    Math.ceil((cachedTokens * cachedInputRate) / 1_000_000) +
+    Math.ceil((outputTokens * pricing.outputMicrosPerMillionTokens) / 1_000_000)
+  );
 }
 
 function cachedInputTokens(entry: ModelUsageInput): number {
@@ -1841,9 +2082,10 @@ function cachedInputTokens(entry: ModelUsageInput): number {
       : [];
   let total = 0;
   for (const detail of details) {
-    total += positiveInt(detail.cached_tokens)
-      + positiveInt(detail.cachedInputTokens)
-      + positiveInt(detail.cached_input_tokens);
+    total +=
+      positiveInt(detail.cached_tokens) +
+      positiveInt(detail.cachedInputTokens) +
+      positiveInt(detail.cached_input_tokens);
   }
   return total;
 }
@@ -1876,20 +2118,36 @@ function ensureBuiltInMcpServers(settings: Settings): Settings["mcpServers"] {
       // safe to cache / leave as-is.)
       cacheToolsList: false,
     },
-    ...(hasFiles ? [] : [{
-      id: "files",
-      name: "Files",
-      url: firstPartyMcpUrl,
-      allowedTools: ["files_get_download_url"],
-      cacheToolsList: true,
-    }]),
-    ...(hasDocs ? [] : [{
-      id: "docs",
-      name: "Document Search",
-      url: firstPartyDocsMcpUrl,
-      allowedTools: ["search_documents", "fetch_document_chunk", "list_document_bases", "knowledge_search", "knowledge_fetch", "memory_search", "memory_propose"],
-      cacheToolsList: false,
-    }]),
+    ...(hasFiles
+      ? []
+      : [
+          {
+            id: "files",
+            name: "Files",
+            url: firstPartyMcpUrl,
+            allowedTools: ["files_get_download_url"],
+            cacheToolsList: true,
+          },
+        ]),
+    ...(hasDocs
+      ? []
+      : [
+          {
+            id: "docs",
+            name: "Document Search",
+            url: firstPartyDocsMcpUrl,
+            allowedTools: [
+              "search_documents",
+              "fetch_document_chunk",
+              "list_document_bases",
+              "knowledge_search",
+              "knowledge_fetch",
+              "memory_search",
+              "memory_propose",
+            ],
+            cacheToolsList: false,
+          },
+        ]),
     ...existing,
   ];
 }
@@ -1916,7 +2174,10 @@ function ensureBuiltInMcpServers(settings: Settings): Settings["mcpServers"] {
  *     the one binding a mounted embed cannot leave unset.
  */
 export function firstPartyMcpBaseUrl(settings: Settings): string {
-  return settings.opengeniMcpUrl ?? `http://127.0.0.1:${settings.apiPort}/v1/workspaces/{workspaceId}/mcp`;
+  return (
+    settings.opengeniMcpUrl ??
+    `http://127.0.0.1:${settings.apiPort}/v1/workspaces/{workspaceId}/mcp`
+  );
 }
 
 export function firstPartyMcpWorkspaceUrl(settings: Settings, workspaceId: string): string {
@@ -1945,45 +2206,67 @@ function validateSettings(settings: Settings): void {
   }
   if (settings.productAccessMode === "managed") {
     if (!settings.publicBaseUrl) {
-      throw new Error("OPENGENI_PUBLIC_BASE_URL is required when OPENGENI_PRODUCT_ACCESS_MODE=managed");
+      throw new Error(
+        "OPENGENI_PUBLIC_BASE_URL is required when OPENGENI_PRODUCT_ACCESS_MODE=managed",
+      );
     }
     if (!settings.betterAuthSecret) {
-      throw new Error("OPENGENI_BETTER_AUTH_SECRET is required when OPENGENI_PRODUCT_ACCESS_MODE=managed");
+      throw new Error(
+        "OPENGENI_BETTER_AUTH_SECRET is required when OPENGENI_PRODUCT_ACCESS_MODE=managed",
+      );
     }
     if (!settings.delegationSecret) {
-      throw new Error("OPENGENI_DELEGATION_SECRET is required when OPENGENI_PRODUCT_ACCESS_MODE=managed");
+      throw new Error(
+        "OPENGENI_DELEGATION_SECRET is required when OPENGENI_PRODUCT_ACCESS_MODE=managed",
+      );
     }
     if (!["local", "test"].includes(settings.environment) && !settings.resendApiKey) {
       throw new Error("OPENGENI_RESEND_API_KEY is required for managed mode outside local/test");
     }
     if (!["local", "test"].includes(settings.environment) && !settings.environmentsEncryptionKey) {
-      throw new Error("OPENGENI_ENVIRONMENTS_ENCRYPTION_KEY is required for managed mode outside local/test");
+      throw new Error(
+        "OPENGENI_ENVIRONMENTS_ENCRYPTION_KEY is required for managed mode outside local/test",
+      );
     }
   }
   environmentsEncryptionKeyBytes(settings);
   if (settings.integrationsEnabled) {
     if (settings.productAccessMode === "managed" && !settings.publicBaseUrl) {
-      throw new Error("OPENGENI_PUBLIC_BASE_URL is required when OPENGENI_INTEGRATIONS_ENABLED=true and OPENGENI_PRODUCT_ACCESS_MODE=managed");
+      throw new Error(
+        "OPENGENI_PUBLIC_BASE_URL is required when OPENGENI_INTEGRATIONS_ENABLED=true and OPENGENI_PRODUCT_ACCESS_MODE=managed",
+      );
     }
-    if (settings.publicBaseUrl && !settings.publicBaseUrl.startsWith("https://") && !["local", "test"].includes(settings.environment)) {
-      throw new Error("OPENGENI_PUBLIC_BASE_URL must use https when OPENGENI_INTEGRATIONS_ENABLED=true outside local/test");
+    if (
+      settings.publicBaseUrl &&
+      !settings.publicBaseUrl.startsWith("https://") &&
+      !["local", "test"].includes(settings.environment)
+    ) {
+      throw new Error(
+        "OPENGENI_PUBLIC_BASE_URL must use https when OPENGENI_INTEGRATIONS_ENABLED=true outside local/test",
+      );
     }
     if (!settings.integrationsStateSecret && !["local", "test"].includes(settings.environment)) {
-      throw new Error("OPENGENI_INTEGRATIONS_STATE_SECRET is required when OPENGENI_INTEGRATIONS_ENABLED=true outside local/test");
+      throw new Error(
+        "OPENGENI_INTEGRATIONS_STATE_SECRET is required when OPENGENI_INTEGRATIONS_ENABLED=true outside local/test",
+      );
     }
   }
   parseIntegrationsOauthClientsJson(settings.integrationsOauthClientsJson);
   if (
-    settings.productAccessMode === "configured"
-    && !["local", "test"].includes(settings.environment)
-    && !settings.delegationSecret
-    && !settings.authRequired
+    settings.productAccessMode === "configured" &&
+    !["local", "test"].includes(settings.environment) &&
+    !settings.delegationSecret &&
+    !settings.authRequired
   ) {
-    throw new Error("OPENGENI_PRODUCT_ACCESS_MODE=configured requires OPENGENI_DELEGATION_SECRET or OPENGENI_AUTH_REQUIRED=true outside local/test");
+    throw new Error(
+      "OPENGENI_PRODUCT_ACCESS_MODE=configured requires OPENGENI_DELEGATION_SECRET or OPENGENI_AUTH_REQUIRED=true outside local/test",
+    );
   }
   if (settings.billingMode === "stripe") {
     if (!settings.stripeSecretKey || !settings.stripeWebhookSecret) {
-      throw new Error("OPENGENI_STRIPE_SECRET_KEY and OPENGENI_STRIPE_WEBHOOK_SECRET are required when OPENGENI_BILLING_MODE=stripe");
+      throw new Error(
+        "OPENGENI_STRIPE_SECRET_KEY and OPENGENI_STRIPE_WEBHOOK_SECRET are required when OPENGENI_BILLING_MODE=stripe",
+      );
     }
   }
   if (settings.productAccessMode !== "managed" && settings.billingMode === "stripe") {
@@ -1993,13 +2276,17 @@ function validateSettings(settings: Settings): void {
     const pricing = configuredModelPricing(settings);
     const missing = configuredAllowedModels(settings).filter((model) => !pricing[model]);
     if (missing.length > 0) {
-      throw new Error(`Missing model pricing for managed billing model(s): ${missing.join(", ")}. Set OPENGENI_MODEL_PRICING_JSON.`);
+      throw new Error(
+        `Missing model pricing for managed billing model(s): ${missing.join(", ")}. Set OPENGENI_MODEL_PRICING_JSON.`,
+      );
     }
   }
   if (settings.usageLimitsMode === "static") {
     const limits = configuredStaticUsageLimits(settings);
     if (Object.keys(limits).length === 0) {
-      throw new Error("OPENGENI_STATIC_USAGE_LIMITS_JSON must define at least one cap when OPENGENI_USAGE_LIMITS_MODE=static");
+      throw new Error(
+        "OPENGENI_STATIC_USAGE_LIMITS_JSON must define at least one cap when OPENGENI_USAGE_LIMITS_MODE=static",
+      );
     }
   } else {
     parseStaticUsageLimitsJson(settings.staticUsageLimitsJson);
@@ -2007,7 +2294,9 @@ function validateSettings(settings: Settings): void {
   if (settings.entitlementsMode === "static") {
     const entitlements = parseStaticEntitlementsJson(settings.staticEntitlementsJson);
     if (Object.keys(entitlements).length === 0) {
-      throw new Error("OPENGENI_STATIC_ENTITLEMENTS_JSON must define at least one feature when OPENGENI_ENTITLEMENTS_MODE=static");
+      throw new Error(
+        "OPENGENI_STATIC_ENTITLEMENTS_JSON must define at least one feature when OPENGENI_ENTITLEMENTS_MODE=static",
+      );
     }
   } else {
     parseStaticEntitlementsJson(settings.staticEntitlementsJson);
@@ -2017,7 +2306,9 @@ function validateSettings(settings: Settings): void {
   }
   if (settings.openaiProvider === "azure") {
     if (!settings.azureOpenaiBaseUrl && !settings.azureOpenaiEndpoint) {
-      throw new Error("Azure OpenAI requires OPENGENI_AZURE_OPENAI_BASE_URL or OPENGENI_AZURE_OPENAI_ENDPOINT");
+      throw new Error(
+        "Azure OpenAI requires OPENGENI_AZURE_OPENAI_BASE_URL or OPENGENI_AZURE_OPENAI_ENDPOINT",
+      );
     }
     if (!settings.azureOpenaiBaseUrl && !settings.azureOpenaiDeployment) {
       throw new Error("Azure OpenAI endpoint mode requires OPENGENI_AZURE_OPENAI_DEPLOYMENT");
@@ -2033,7 +2324,9 @@ function validateSettings(settings: Settings): void {
   // (a half-configured token is always a misconfiguration). This is orthogonal
   // to the backend-gated required-cred sweep below.
   if (Boolean(settings.modalTokenId) !== Boolean(settings.modalTokenSecret)) {
-    throw new Error("OPENGENI_MODAL_TOKEN_ID and OPENGENI_MODAL_TOKEN_SECRET must both be set or both omitted");
+    throw new Error(
+      "OPENGENI_MODAL_TOKEN_ID and OPENGENI_MODAL_TOKEN_SECRET must both be set or both omitted",
+    );
   }
   // Backend-gated required credentials: only the *active* backend's creds are
   // required. A modal deployment must carry the Modal token; a daytona/e2b/none
@@ -2041,48 +2334,115 @@ function validateSettings(settings: Settings): void {
   // SANDBOX_REQUIRED_ENV table that the deployment package also mirrors.
   for (const required of SANDBOX_REQUIRED_ENV[settings.sandboxBackend] ?? []) {
     const value = settings[required.field];
-    if (value === undefined || value === null || (typeof value === "string" && value.trim().length === 0)) {
-      throw new Error(`${required.env} is required when OPENGENI_SANDBOX_BACKEND=${settings.sandboxBackend}`);
+    if (
+      value === undefined ||
+      value === null ||
+      (typeof value === "string" && value.trim().length === 0)
+    ) {
+      throw new Error(
+        `${required.env} is required when OPENGENI_SANDBOX_BACKEND=${settings.sandboxBackend}`,
+      );
     }
   }
-  if (settings.objectStorageBackend === "s3-compatible" || settings.objectStorageBackend === "aws-s3") {
-    if (Boolean(settings.objectStorageAccessKeyId) !== Boolean(settings.objectStorageSecretAccessKey)) {
-      throw new Error("OPENGENI_OBJECT_STORAGE_ACCESS_KEY_ID and OPENGENI_OBJECT_STORAGE_SECRET_ACCESS_KEY must both be set or both omitted");
+  if (
+    settings.objectStorageBackend === "s3-compatible" ||
+    settings.objectStorageBackend === "aws-s3"
+  ) {
+    if (
+      Boolean(settings.objectStorageAccessKeyId) !== Boolean(settings.objectStorageSecretAccessKey)
+    ) {
+      throw new Error(
+        "OPENGENI_OBJECT_STORAGE_ACCESS_KEY_ID and OPENGENI_OBJECT_STORAGE_SECRET_ACCESS_KEY must both be set or both omitted",
+      );
     }
-    if (settings.objectStorageBackend === "s3-compatible" && (settings.objectStorageEndpoint || settings.objectStorageSandboxEndpoint) && (!settings.objectStorageAccessKeyId || !settings.objectStorageSecretAccessKey)) {
-      throw new Error("S3-compatible object storage endpoints require OPENGENI_OBJECT_STORAGE_ACCESS_KEY_ID and OPENGENI_OBJECT_STORAGE_SECRET_ACCESS_KEY");
+    if (
+      settings.objectStorageBackend === "s3-compatible" &&
+      (settings.objectStorageEndpoint || settings.objectStorageSandboxEndpoint) &&
+      (!settings.objectStorageAccessKeyId || !settings.objectStorageSecretAccessKey)
+    ) {
+      throw new Error(
+        "S3-compatible object storage endpoints require OPENGENI_OBJECT_STORAGE_ACCESS_KEY_ID and OPENGENI_OBJECT_STORAGE_SECRET_ACCESS_KEY",
+      );
     }
-    if (settings.objectStorageAzureConnectionString || settings.objectStorageAzureAccountName || settings.objectStorageAzureAccountKey || settings.objectStorageAzureEndpoint) {
-      throw new Error("S3 object storage uses OPENGENI_OBJECT_STORAGE_* S3 settings, not OPENGENI_OBJECT_STORAGE_AZURE_* settings");
+    if (
+      settings.objectStorageAzureConnectionString ||
+      settings.objectStorageAzureAccountName ||
+      settings.objectStorageAzureAccountKey ||
+      settings.objectStorageAzureEndpoint
+    ) {
+      throw new Error(
+        "S3 object storage uses OPENGENI_OBJECT_STORAGE_* S3 settings, not OPENGENI_OBJECT_STORAGE_AZURE_* settings",
+      );
     }
-    if (settings.objectStorageGcsProjectId || settings.objectStorageGcsCredentialsJson || settings.objectStorageGcsKeyFilename || settings.objectStorageGcsApiEndpoint) {
-      throw new Error("S3 object storage uses OPENGENI_OBJECT_STORAGE_* S3 settings, not OPENGENI_OBJECT_STORAGE_GCS_* settings");
+    if (
+      settings.objectStorageGcsProjectId ||
+      settings.objectStorageGcsCredentialsJson ||
+      settings.objectStorageGcsKeyFilename ||
+      settings.objectStorageGcsApiEndpoint
+    ) {
+      throw new Error(
+        "S3 object storage uses OPENGENI_OBJECT_STORAGE_* S3 settings, not OPENGENI_OBJECT_STORAGE_GCS_* settings",
+      );
     }
   } else if (settings.objectStorageBackend === "azure-blob") {
-    if (settings.objectStorageEndpoint || settings.objectStorageSandboxEndpoint || settings.objectStorageAccessKeyId || settings.objectStorageSecretAccessKey) {
-      throw new Error("Azure Blob storage uses OPENGENI_OBJECT_STORAGE_AZURE_* settings, not S3-compatible object storage settings");
+    if (
+      settings.objectStorageEndpoint ||
+      settings.objectStorageSandboxEndpoint ||
+      settings.objectStorageAccessKeyId ||
+      settings.objectStorageSecretAccessKey
+    ) {
+      throw new Error(
+        "Azure Blob storage uses OPENGENI_OBJECT_STORAGE_AZURE_* settings, not S3-compatible object storage settings",
+      );
     }
-    if (settings.objectStorageGcsProjectId || settings.objectStorageGcsCredentialsJson || settings.objectStorageGcsKeyFilename || settings.objectStorageGcsApiEndpoint) {
-      throw new Error("Azure Blob storage uses OPENGENI_OBJECT_STORAGE_AZURE_* settings, not OPENGENI_OBJECT_STORAGE_GCS_* settings");
+    if (
+      settings.objectStorageGcsProjectId ||
+      settings.objectStorageGcsCredentialsJson ||
+      settings.objectStorageGcsKeyFilename ||
+      settings.objectStorageGcsApiEndpoint
+    ) {
+      throw new Error(
+        "Azure Blob storage uses OPENGENI_OBJECT_STORAGE_AZURE_* settings, not OPENGENI_OBJECT_STORAGE_GCS_* settings",
+      );
     }
     const hasConnectionString = Boolean(settings.objectStorageAzureConnectionString);
-    const hasSharedKey = Boolean(settings.objectStorageAzureAccountName) && Boolean(settings.objectStorageAzureAccountKey);
+    const hasSharedKey =
+      Boolean(settings.objectStorageAzureAccountName) &&
+      Boolean(settings.objectStorageAzureAccountKey);
     if (!hasConnectionString && !hasSharedKey) {
-      throw new Error("Azure Blob storage requires OPENGENI_OBJECT_STORAGE_AZURE_CONNECTION_STRING or OPENGENI_OBJECT_STORAGE_AZURE_ACCOUNT_NAME plus OPENGENI_OBJECT_STORAGE_AZURE_ACCOUNT_KEY");
+      throw new Error(
+        "Azure Blob storage requires OPENGENI_OBJECT_STORAGE_AZURE_CONNECTION_STRING or OPENGENI_OBJECT_STORAGE_AZURE_ACCOUNT_NAME plus OPENGENI_OBJECT_STORAGE_AZURE_ACCOUNT_KEY",
+      );
     }
   } else {
-    if (settings.objectStorageEndpoint || settings.objectStorageSandboxEndpoint || settings.objectStorageAccessKeyId || settings.objectStorageSecretAccessKey) {
-      throw new Error("GCS object storage uses OPENGENI_OBJECT_STORAGE_GCS_* settings, not S3-compatible object storage settings");
+    if (
+      settings.objectStorageEndpoint ||
+      settings.objectStorageSandboxEndpoint ||
+      settings.objectStorageAccessKeyId ||
+      settings.objectStorageSecretAccessKey
+    ) {
+      throw new Error(
+        "GCS object storage uses OPENGENI_OBJECT_STORAGE_GCS_* settings, not S3-compatible object storage settings",
+      );
     }
-    if (settings.objectStorageAzureConnectionString || settings.objectStorageAzureAccountName || settings.objectStorageAzureAccountKey || settings.objectStorageAzureEndpoint) {
-      throw new Error("GCS object storage uses OPENGENI_OBJECT_STORAGE_GCS_* settings, not OPENGENI_OBJECT_STORAGE_AZURE_* settings");
+    if (
+      settings.objectStorageAzureConnectionString ||
+      settings.objectStorageAzureAccountName ||
+      settings.objectStorageAzureAccountKey ||
+      settings.objectStorageAzureEndpoint
+    ) {
+      throw new Error(
+        "GCS object storage uses OPENGENI_OBJECT_STORAGE_GCS_* settings, not OPENGENI_OBJECT_STORAGE_AZURE_* settings",
+      );
     }
     if (settings.objectStorageGcsCredentialsJson) {
       parseGcsCredentialsJson(settings.objectStorageGcsCredentialsJson);
     }
   }
   if (settings.documentChunkOverlap >= settings.documentChunkSize) {
-    throw new Error("OPENGENI_DOCUMENT_CHUNK_OVERLAP must be smaller than OPENGENI_DOCUMENT_CHUNK_SIZE");
+    throw new Error(
+      "OPENGENI_DOCUMENT_CHUNK_OVERLAP must be smaller than OPENGENI_DOCUMENT_CHUNK_SIZE",
+    );
   }
   parseExposedPorts(settings.dockerExposedPorts);
   sandboxEnvironmentVariableNames(settings);
@@ -2121,31 +2481,35 @@ function validateSettings(settings: Settings): void {
     const idleTimeoutMs = effectiveModalIdleTimeoutSeconds(settings) * 1000;
     if (!(reaperPeriod < viewerTtl)) {
       throw new Error(
-        `OPENGENI_SANDBOX_LEASE_REAPER_PERIOD_MS (${reaperPeriod}) must be strictly less than `
-        + `OPENGENI_SANDBOX_VIEWER_HOLDER_TTL_MS (${viewerTtl}): the reaper must run more often `
-        + `than the TTL it polices, or stale viewer holders outlive a full reaper period.`);
+        `OPENGENI_SANDBOX_LEASE_REAPER_PERIOD_MS (${reaperPeriod}) must be strictly less than ` +
+          `OPENGENI_SANDBOX_VIEWER_HOLDER_TTL_MS (${viewerTtl}): the reaper must run more often ` +
+          `than the TTL it polices, or stale viewer holders outlive a full reaper period.`,
+      );
     }
     if (!(idleTimeoutMs <= providerLifetimeMs)) {
       throw new Error(
-        `OPENGENI_MODAL_IDLE_TIMEOUT_SECONDS*1000 (${idleTimeoutMs}) must not exceed the hard provider `
-        + `lifetime (OPENGENI_MODAL_TIMEOUT_SECONDS*1000 = ${providerLifetimeMs}): the idle timeout is a `
-        + `floor under the hard lifetime, not above it.`);
+        `OPENGENI_MODAL_IDLE_TIMEOUT_SECONDS*1000 (${idleTimeoutMs}) must not exceed the hard provider ` +
+          `lifetime (OPENGENI_MODAL_TIMEOUT_SECONDS*1000 = ${providerLifetimeMs}): the idle timeout is a ` +
+          `floor under the hard lifetime, not above it.`,
+      );
     }
     if (!(viewerTtl < idleTimeoutMs)) {
       throw new Error(
-        `OPENGENI_SANDBOX_VIEWER_HOLDER_TTL_MS (${viewerTtl}) must be strictly less than the effective box `
-        + `idle timeout (${idleTimeoutMs}): a viewer holder must be reapable before the box idles out from `
-        + `under it (the provider idle-timeout is the backstop).`);
+        `OPENGENI_SANDBOX_VIEWER_HOLDER_TTL_MS (${viewerTtl}) must be strictly less than the effective box ` +
+          `idle timeout (${idleTimeoutMs}): a viewer holder must be reapable before the box idles out from ` +
+          `under it (the provider idle-timeout is the backstop).`,
+      );
     }
     if (!(reaperPeriod + idleGraceMs < idleTimeoutMs)) {
       throw new Error(
-        `OPENGENI_SANDBOX_LEASE_REAPER_PERIOD_MS + OPENGENI_SANDBOX_IDLE_GRACE_MS `
-        + `(${reaperPeriod} + ${idleGraceMs} = ${reaperPeriod + idleGraceMs}) must be strictly less than the `
-        + `effective box idle timeout (${idleTimeoutMs}): a drained box must SURVIVE its full warm window so `
-        + `the reaper can resume + snapshot /workspace + terminate it on the sweep AFTER the drain grace `
-        + `elapses — Modal's idle-reap must NOT fire first (or /workspace is lost). Raise `
-        + `OPENGENI_MODAL_IDLE_TIMEOUT_SECONDS (defaults to OPENGENI_MODAL_TIMEOUT_SECONDS) or lower `
-        + `OPENGENI_SANDBOX_IDLE_GRACE_MS.`);
+        `OPENGENI_SANDBOX_LEASE_REAPER_PERIOD_MS + OPENGENI_SANDBOX_IDLE_GRACE_MS ` +
+          `(${reaperPeriod} + ${idleGraceMs} = ${reaperPeriod + idleGraceMs}) must be strictly less than the ` +
+          `effective box idle timeout (${idleTimeoutMs}): a drained box must SURVIVE its full warm window so ` +
+          `the reaper can resume + snapshot /workspace + terminate it on the sweep AFTER the drain grace ` +
+          `elapses — Modal's idle-reap must NOT fire first (or /workspace is lost). Raise ` +
+          `OPENGENI_MODAL_IDLE_TIMEOUT_SECONDS (defaults to OPENGENI_MODAL_TIMEOUT_SECONDS) or lower ` +
+          `OPENGENI_SANDBOX_IDLE_GRACE_MS.`,
+      );
     }
   }
   // --- stream-token secret: required-when-desktop, but GRACEFULLY DEGRADE (I8) ---
@@ -2158,10 +2522,10 @@ function validateSettings(settings: Settings): void {
   // crashing the whole API on a missing secret.
   if (settings.sandboxDesktopEnabled && resolveStreamTokenSecret(settings) === undefined) {
     console.warn(
-      "[opengeni] OPENGENI_SANDBOX_DESKTOP_ENABLED=true but neither OPENGENI_STREAM_TOKEN_SECRET nor "
-      + "OPENGENI_DELEGATION_SECRET is set: the desktop pixel plane will GRACEFULLY DEGRADE "
-      + "(DesktopStream.transport=null — no scoped stream tokens can be minted). Set "
-      + "OPENGENI_STREAM_TOKEN_SECRET to enable the live desktop stream.",
+      "[opengeni] OPENGENI_SANDBOX_DESKTOP_ENABLED=true but neither OPENGENI_STREAM_TOKEN_SECRET nor " +
+        "OPENGENI_DELEGATION_SECRET is set: the desktop pixel plane will GRACEFULLY DEGRADE " +
+        "(DesktopStream.transport=null — no scoped stream tokens can be minted). Set " +
+        "OPENGENI_STREAM_TOKEN_SECRET to enable the live desktop stream.",
     );
   }
   // Model provider registry: parse it here so JSON/zod errors surface at boot,
@@ -2176,14 +2540,20 @@ function validateSettings(settings: Settings): void {
   const providerIds = new Set<string>();
   for (const provider of registryProviders) {
     if (provider.id === builtinId) {
-      throw new Error(`OPENGENI_MODEL_PROVIDERS_JSON provider id ${provider.id} collides with the built-in provider id`);
+      throw new Error(
+        `OPENGENI_MODEL_PROVIDERS_JSON provider id ${provider.id} collides with the built-in provider id`,
+      );
     }
     if (providerIds.has(provider.id)) {
-      throw new Error(`OPENGENI_MODEL_PROVIDERS_JSON contains duplicate provider id ${provider.id}`);
+      throw new Error(
+        `OPENGENI_MODEL_PROVIDERS_JSON contains duplicate provider id ${provider.id}`,
+      );
     }
     providerIds.add(provider.id);
     if (!resolveProviderApiKey(provider)) {
-      throw new Error(`OPENGENI_MODEL_PROVIDERS_JSON provider ${provider.id} requires a resolvable API key (set apiKey or apiKeyEnv)`);
+      throw new Error(
+        `OPENGENI_MODEL_PROVIDERS_JSON provider ${provider.id} requires a resolvable API key (set apiKey or apiKeyEnv)`,
+      );
     }
   }
 }
@@ -2303,7 +2673,10 @@ export function resolveNatsControlPlaneAuth(settings: Settings): NatsControlPlan
 }
 
 function splitCsv(raw: string): string[] {
-  return raw.split(",").map((value) => value.trim()).filter(Boolean);
+  return raw
+    .split(",")
+    .map((value) => value.trim())
+    .filter(Boolean);
 }
 
 function uniqueEnvNames(raw: string[], fieldName: string): string[] {
@@ -2330,7 +2703,9 @@ function parseGcsCredentialsJson(raw: string): unknown {
     return JSON.parse(raw);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`OPENGENI_OBJECT_STORAGE_GCS_CREDENTIALS_JSON must be valid JSON: ${message}`);
+    throw new Error(`OPENGENI_OBJECT_STORAGE_GCS_CREDENTIALS_JSON must be valid JSON: ${message}`, {
+      cause: error,
+    });
   }
 }