@opengeni/config 0.5.1 → 0.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/config",
-  "version": "0.5.1",
+  "version": "0.6.2",
   "description": "OpenGeni runtime configuration: settings resolution, deployment knobs, and config validation shared across the server packages.",
   "license": "Apache-2.0",
   "repository": {
@@ -33,8 +33,8 @@
     "prepublishOnly": "bash ../../scripts/prepublish-guard"
   },
   "dependencies": {
-    "@opengeni/codex": "^0.2.3",
-    "@opengeni/contracts": "^0.10.0",
+    "@opengeni/codex": "^0.2.5",
+    "@opengeni/contracts": "^0.15.0",
     "zod": "^4.2.1"
   },
   "engines": {

package/src/index.ts

@@ -90,7 +90,7 @@ export const DEFAULT_AGENT_INSTRUCTIONS = [
   "You are an OpenGeni workspace agent.",
   "Follow the user's task and any enabled pack or skill instructions for the current role.",
   "Work inside the sandbox workspace and use filesystem and shell tools when useful.",
-  "Repository resources are mounted under repos/<owner>/<repo>.",
+  "Repository resources are mounted under repos/<host>/<owner>/<repo> unless the session specifies another collision-free mount path.",
   "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.",
@@ -103,14 +103,59 @@ export const DEFAULT_AGENT_INSTRUCTIONS = [
 
 export const McpServerConnectionRefSchema = z
   .object({
-    connectionId: z.string().uuid().optional(),
+    // Standalone ids are UUIDs; embedded hosts may use any stable opaque id.
+    connectionId: z.string().min(1).optional(),
+    provider: z.string().min(1).max(128).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(),
+    selectedResources: z
+      .array(
+        z
+          .object({
+            id: z.string().min(1).max(512),
+            kind: z.literal("repository"),
+          })
+          .strict(),
+      )
+      .min(1)
+      .max(256)
+      .superRefine((resources, context) => {
+        const seen = new Set<string>();
+        for (const [index, resource] of resources.entries()) {
+          const key = `${resource.kind}\0${resource.id}`;
+          if (seen.has(key)) {
+            context.addIssue({
+              code: "custom",
+              message: "selectedResources must not contain duplicates",
+              path: [index],
+            });
+          }
+          seen.add(key);
+        }
+      })
+      .optional(),
     subjectScope: z.enum(["workspace", "subject"]).optional(),
   })
-  .strict();
+  .strict()
+  .superRefine((reference, context) => {
+    if (!reference.selectedResources) return;
+    if (!reference.connectionId) {
+      context.addIssue({
+        code: "custom",
+        message: "selectedResources requires connectionId",
+        path: ["connectionId"],
+      });
+    }
+    if (!reference.provider) {
+      context.addIssue({
+        code: "custom",
+        message: "selectedResources requires provider",
+        path: ["provider"],
+      });
+    }
+  });
 export type McpServerConnectionRef = z.infer<typeof McpServerConnectionRefSchema>;
 
 const SettingsSchema = z.object({
@@ -125,7 +170,7 @@ const SettingsSchema = z.object({
   // topology. Default "" → standalone: no search_path scoping, server default
   // (`public`). When set (e.g. "opengeni"), the db handle + the managed-auth
   // pool send `search_path = "<dbSchema>","opengeni_private","public"` so every
-  // query resolves into the dedicated schema with NO query rewrite (SPIKE-1 F1).
+  // query resolves into the dedicated schema with NO query rewrite (schema-isolation contract F1).
   dbSchema: z.string().default(""),
   // Step I (§7.7). RLS posture. "force" (default) = today's FORCE-RLS via the
   // non-owner `opengeni_app` role. "scoped" = the embedded owner-role path (the
@@ -135,6 +180,12 @@ const SettingsSchema = z.object({
   temporalHost: z.string().default("127.0.0.1:7233"),
   temporalNamespace: z.string().default("default"),
   temporalTaskQueue: z.string().default("opengeni-runs-ts"),
+  temporalTlsEnabled: EnvBoolean.default(false),
+  temporalApiKey: z.string().optional(),
+  temporalTlsServerName: z.string().optional(),
+  temporalTlsRootCaCertificateBase64: z.string().optional(),
+  temporalTlsClientCertificateBase64: z.string().optional(),
+  temporalTlsClientPrivateKeyBase64: z.string().optional(),
   startupDependencyRetryAttempts: z.coerce.number().int().positive().default(30),
   startupDependencyRetryInitialDelayMs: z.coerce.number().int().positive().default(1000),
   startupDependencyRetryMaxDelayMs: z.coerce.number().int().positive().default(5000),
@@ -157,11 +208,11 @@ const SettingsSchema = z.object({
   staticEntitlementsJson: z.string().default("{}"),
   staticUsageLimitsJson: z.string().default("{}"),
   delegationSecret: z.string().optional(),
-  // Sandbox-surfacing scoped stream-token HMAC secret (master-spine §C.3 / I8).
+  // sandbox workspace scoped stream-token HMAC secret (sandbox contract §C.3 / stream-token availability contract).
   // When unset, the API falls back to `delegationSecret` (the same HMAC envelope
   // family, `ogs_` vs `ogd_` prefix). REQUIRED-WHEN-DESKTOP, but the absence of
   // BOTH while sandboxDesktopEnabled=true is a GRACEFUL DEGRADE (DesktopStream
-  // transport:null + a loud boot warning), NOT a hard boot-fail (I8/OD-8).
+  // transport:null + a loud boot warning), NOT a hard boot-fail (stream-token availability contract).
   streamTokenSecret: z.string().optional(),
   // The desktop input plane (raw stream:control writes) is OFF in v1: even a
   // holder of stream:control gets 403 until this flips. Keeps stream:control a
@@ -169,6 +220,13 @@ const SettingsSchema = z.object({
   streamControlEnabled: EnvBoolean.default(false),
   toolspaceEnabled: EnvBoolean.default(false),
   toolspaceMaxCallsPerTurn: z.coerce.number().int().positive().default(200),
+  // Optional release-coherent bootstrap hint for custom rigs/connected machines
+  // that do not carry the stock-image ogtool binary. Exact stable versions only:
+  // the agent must never guess a tag or silently install `latest`.
+  ogtoolPackageSpec: z
+    .string()
+    .regex(/^@opengeni\/ogtool@(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/u)
+    .optional(),
   environmentsEncryptionKey: z.string().optional(),
   integrationsEnabled: EnvBoolean.default(false),
   integrationsStateSecret: z.string().optional(),
@@ -216,6 +274,10 @@ const SettingsSchema = z.object({
   // 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(),
+  // Provider-neutral fallback for canonical model-facing tool-result text.
+  // The current stable Codex catalog policy is 10k tokens; the truncator adds
+  // Codex's 1.2x JSON serialization allowance when applying it.
+  modelToolOutputTruncationTokens: z.coerce.number().int().positive().default(10_000),
   authRequired: EnvBoolean.default(false),
   accessKey: z.string().optional(),
   authAllowHealth: EnvBoolean.default(true),
@@ -249,15 +311,11 @@ const SettingsSchema = z.object({
   // 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
+  // credential allocator 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.
-  codexRotationNearExhaustionPct: z.coerce.number().int().min(1).max(100).default(90),
   openaiReasoningEffort: ReasoningEffort.default("low"),
   openaiAllowedReasoningEfforts: z.string().default("low,medium,high,xhigh"),
   openaiResponsesTransport: z.enum(["http", "websocket"]).default("http"),
@@ -398,7 +456,7 @@ 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
+  // Workbench v2 turn-end workspace capture. 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
@@ -477,7 +535,7 @@ const SettingsSchema = z.object({
   // 404 (invisible — the surface does not exist for this deployment) and the
   // selfhosted backend is inert; boot is unaffected. EnvBoolean (NOT
   // z.coerce.boolean(), which coerces "false" -> true). Flipped per-environment via
-  // the deploy-staging IaC secret/configmap pattern (dossier §17/§25.1).
+  // the deploy-staging IaC secret/configmap pattern.
   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
@@ -497,7 +555,7 @@ const SettingsSchema = z.object({
   selfhostedNatsUrl: z.string().optional(),
   selfhostedRelayUrl: z.string().optional(),
   // The HMAC secret the control plane signs the agent's relay PRODUCER token with
-  // (the `ogr_` envelope threaded into EnrollmentCredentials.relayToken; M8b/dossier
+  // (the `ogr_` envelope threaded into EnrollmentCredentials.relayToken; M8b/design
   // §10.5). The relay verifies the producer token with the SAME secret. Optional:
   // when ABSENT the poll returns an empty relayToken (graceful degrade — the stream
   // plane is simply unavailable until configured). Falls back to streamTokenSecret /
@@ -507,7 +565,7 @@ const SettingsSchema = z.object({
   // The minisign PUBLIC key the agent pins for self-update verification (handed to
   // the agent in EnrollmentCredentials; the SECRET key lives only in CI).
   agentUpdatePublicKey: z.string().optional(),
-  // --- NATS auth-callout tenancy boundary (bring-your-own-compute M-AUTH; dossier
+  // --- NATS auth-callout tenancy boundary (bring-your-own-compute M-AUTH; design
   //     §10.1 NATS Accounts per workspace + §17 the isolation smoke) -------------
   // nats-server is configured with AUTH CALLOUT: an external agent connects
   // presenting its `oge_` enrollment bearer as the connect auth-token; the server
@@ -701,6 +759,19 @@ const SettingsSchema = z.object({
 
 export type Settings = z.infer<typeof SettingsSchema>;
 export type McpServerConfig = Settings["mcpServers"][number];
+export type TemporalTlsConnectionConfig = {
+  serverNameOverride?: string;
+  serverRootCACertificate?: Uint8Array;
+  clientCertPair?: {
+    crt: Uint8Array;
+    key: Uint8Array;
+  };
+};
+export type TemporalConnectionOptions = {
+  address: string;
+  tls?: true | TemporalTlsConnectionConfig;
+  apiKey?: string;
+};
 export type ModelPricing = {
   inputMicrosPerMillionTokens: number;
   cachedInputMicrosPerMillionTokens?: number | undefined;
@@ -750,6 +821,9 @@ const RegistryModelSchema = z.object({
   contextWindowTokens: z.number().int().positive().optional(),
   effectiveContextWindowTokens: z.number().int().positive().optional(),
   autoCompactTokenLimit: z.number().int().positive().optional(),
+  // Canonical model-facing function/tool-result policy. The runtime applies
+  // the same 1.2x serialization allowance as Codex when materializing output.
+  toolOutputTruncationTokens: 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(),
@@ -808,6 +882,7 @@ export interface ConfiguredModel {
   contextWindowTokens?: number | undefined;
   effectiveContextWindowTokens?: number | undefined;
   autoCompactTokenLimit?: number | undefined;
+  toolOutputTruncationTokens?: number | undefined;
   reasoningEffort: boolean;
   hostedWebSearch: boolean;
 }
@@ -971,6 +1046,14 @@ export function getSettings(): Settings {
     temporalHost: optional("OPENGENI_TEMPORAL_HOST"),
     temporalNamespace: optional("OPENGENI_TEMPORAL_NAMESPACE"),
     temporalTaskQueue: optional("OPENGENI_TEMPORAL_TASK_QUEUE"),
+    temporalTlsEnabled: optional("OPENGENI_TEMPORAL_TLS_ENABLED"),
+    temporalApiKey: optional("OPENGENI_TEMPORAL_API_KEY"),
+    temporalTlsServerName: optional("OPENGENI_TEMPORAL_TLS_SERVER_NAME"),
+    temporalTlsRootCaCertificateBase64: optional(
+      "OPENGENI_TEMPORAL_TLS_ROOT_CA_CERTIFICATE_BASE64",
+    ),
+    temporalTlsClientCertificateBase64: optional("OPENGENI_TEMPORAL_TLS_CLIENT_CERTIFICATE_BASE64"),
+    temporalTlsClientPrivateKeyBase64: optional("OPENGENI_TEMPORAL_TLS_CLIENT_PRIVATE_KEY_BASE64"),
     startupDependencyRetryAttempts: optional("OPENGENI_STARTUP_DEPENDENCY_RETRY_ATTEMPTS"),
     startupDependencyRetryInitialDelayMs: optional(
       "OPENGENI_STARTUP_DEPENDENCY_RETRY_INITIAL_DELAY_MS",
@@ -995,6 +1078,7 @@ export function getSettings(): Settings {
     streamControlEnabled: optional("OPENGENI_STREAM_CONTROL_ENABLED"),
     toolspaceEnabled: optional("OPENGENI_TOOLSPACE_ENABLED"),
     toolspaceMaxCallsPerTurn: optional("OPENGENI_TOOLSPACE_MAX_CALLS_PER_TURN"),
+    ogtoolPackageSpec: optional("OPENGENI_OGTOOL_PACKAGE_SPEC"),
     environmentsEncryptionKey: optional("OPENGENI_ENVIRONMENTS_ENCRYPTION_KEY"),
     integrationsEnabled: optional("OPENGENI_INTEGRATIONS_ENABLED"),
     integrationsStateSecret: optional("OPENGENI_INTEGRATIONS_STATE_SECRET"),
@@ -1010,6 +1094,7 @@ export function getSettings(): Settings {
     contextCompactionThresholdRatio: optional("OPENGENI_COMPACTION_THRESHOLD_RATIO"),
     contextReservedOutputTokens: optional("OPENGENI_CONTEXT_RESERVED_OUTPUT_TOKENS"),
     contextAutoCompactThresholdTokens: optional("OPENGENI_CONTEXT_AUTO_COMPACT_THRESHOLD_TOKENS"),
+    modelToolOutputTruncationTokens: optional("OPENGENI_MODEL_TOOL_OUTPUT_TRUNCATION_TOKENS"),
     authRequired: optional("OPENGENI_AUTH_REQUIRED"),
     accessKey: optional("OPENGENI_ACCESS_KEY"),
     authAllowHealth: optional("OPENGENI_AUTH_ALLOW_HEALTH"),
@@ -1030,7 +1115,6 @@ export function getSettings(): Settings {
     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"),
     openaiAllowedReasoningEfforts: optional("OPENGENI_OPENAI_ALLOWED_REASONING_EFFORTS"),
     openaiResponsesTransport: optional("OPENGENI_OPENAI_RESPONSES_TRANSPORT"),
@@ -1368,6 +1452,7 @@ export function configuredModels(settings: Settings): ConfiguredModel[] {
       providerLabel: builtinLabel,
       api: "responses" as const,
       contextWindowTokens: settings.contextWindowTokens,
+      toolOutputTruncationTokens: settings.modelToolOutputTruncationTokens,
       reasoningEffort: true,
       hostedWebSearch: settings.webSearchEnabled,
     }));
@@ -1389,6 +1474,9 @@ export function configuredModels(settings: Settings): ConfiguredModel[] {
         ...(model.autoCompactTokenLimit === undefined
           ? {}
           : { autoCompactTokenLimit: model.autoCompactTokenLimit }),
+        ...(model.toolOutputTruncationTokens === undefined
+          ? {}
+          : { toolOutputTruncationTokens: model.toolOutputTruncationTokens }),
         reasoningEffort: model.reasoningEffort ?? false,
         hostedWebSearch: model.hostedWebSearch ?? false,
       });
@@ -1485,7 +1573,10 @@ export function settingsWithResolvedModelContext(
   settings: Settings,
   model: Pick<
     ConfiguredModel,
-    "contextWindowTokens" | "effectiveContextWindowTokens" | "autoCompactTokenLimit"
+    | "contextWindowTokens"
+    | "effectiveContextWindowTokens"
+    | "autoCompactTokenLimit"
+    | "toolOutputTruncationTokens"
   >,
 ): Settings {
   const contextWindowTokens = model.contextWindowTokens ?? settings.contextWindowTokens;
@@ -1503,6 +1594,9 @@ export function settingsWithResolvedModelContext(
     ...(model.autoCompactTokenLimit === undefined
       ? {}
       : { contextAutoCompactThresholdTokens: model.autoCompactTokenLimit }),
+    ...(model.toolOutputTruncationTokens === undefined
+      ? {}
+      : { modelToolOutputTruncationTokens: model.toolOutputTruncationTokens }),
   };
 }
 
@@ -1573,6 +1667,77 @@ export function environmentsEncryptionKeyBytes(settings: Settings): Uint8Array |
   return new Uint8Array(decoded);
 }
 
+/**
+ * Build one structurally compatible connection policy for both
+ * `@temporalio/client` and `@temporalio/worker`. An API key or any custom TLS
+ * material enables TLS automatically; the explicit flag covers server-auth TLS
+ * without credentials. Secret values are never included in validation errors.
+ */
+export function temporalConnectionOptions(settings: Settings): TemporalConnectionOptions {
+  const apiKey = settings.temporalApiKey?.trim() || undefined;
+  const serverNameOverride = settings.temporalTlsServerName?.trim() || undefined;
+  const rootCa = decodeTemporalTlsMaterial(
+    settings.temporalTlsRootCaCertificateBase64,
+    "OPENGENI_TEMPORAL_TLS_ROOT_CA_CERTIFICATE_BASE64",
+  );
+  const clientCertificate = decodeTemporalTlsMaterial(
+    settings.temporalTlsClientCertificateBase64,
+    "OPENGENI_TEMPORAL_TLS_CLIENT_CERTIFICATE_BASE64",
+  );
+  const clientPrivateKey = decodeTemporalTlsMaterial(
+    settings.temporalTlsClientPrivateKeyBase64,
+    "OPENGENI_TEMPORAL_TLS_CLIENT_PRIVATE_KEY_BASE64",
+  );
+
+  if (Boolean(clientCertificate) !== Boolean(clientPrivateKey)) {
+    throw new Error(
+      "OPENGENI_TEMPORAL_TLS_CLIENT_CERTIFICATE_BASE64 and " +
+        "OPENGENI_TEMPORAL_TLS_CLIENT_PRIVATE_KEY_BASE64 must both be set or both omitted",
+    );
+  }
+
+  const tls: TemporalTlsConnectionConfig = {};
+  if (serverNameOverride) {
+    tls.serverNameOverride = serverNameOverride;
+  }
+  if (rootCa) {
+    tls.serverRootCACertificate = rootCa;
+  }
+  if (clientCertificate && clientPrivateKey) {
+    tls.clientCertPair = { crt: clientCertificate, key: clientPrivateKey };
+  }
+  const hasCustomTls = Object.keys(tls).length > 0;
+  const tlsEnabled = settings.temporalTlsEnabled || Boolean(apiKey) || hasCustomTls;
+
+  return {
+    address: settings.temporalHost,
+    ...(tlsEnabled ? { tls: hasCustomTls ? tls : true } : {}),
+    ...(apiKey ? { apiKey } : {}),
+  };
+}
+
+function decodeTemporalTlsMaterial(
+  value: string | undefined,
+  settingName: string,
+): Uint8Array | undefined {
+  // RFC 2045 base64 commonly arrives wrapped at 76 columns. Kubernetes
+  // stringData and external secret stores preserve those line breaks, so
+  // normalize whitespace before applying the strict alphabet/canonical check.
+  const encoded = value?.replace(/\s/g, "");
+  if (!encoded) {
+    return undefined;
+  }
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(encoded) || encoded.length % 4 === 1) {
+    throw new Error(`${settingName} must contain valid base64`);
+  }
+  const decoded = Buffer.from(encoded, "base64");
+  const canonical = decoded.toString("base64").replace(/=+$/, "");
+  if (decoded.length === 0 || canonical !== encoded.replace(/=+$/, "")) {
+    throw new Error(`${settingName} must contain valid base64`);
+  }
+  return new Uint8Array(decoded);
+}
+
 /**
  * The connection `search_path` for OpenGeni's db handles + the managed-auth pool
  * (Step I, §7.8 runtime half). Returns `undefined` when `dbSchema` is unset
@@ -1580,7 +1745,7 @@ export function environmentsEncryptionKeyBytes(settings: Settings): Uint8Array |
  * default (`public`) applies — byte-for-byte today's behavior. When `dbSchema`
  * is set (embedded), returns `"<schema>,opengeni_private,public"` — `public`
  * stays LAST so `gen_random_uuid()` (pgcrypto) and the `vector` type still
- * resolve (the SPIKE-1 live footgun). `opengeni_private` is on the path so the
+ * resolve (the schema-isolation contract live footgun). `opengeni_private` is on the path so the
  * RLS GUC-reader helpers resolve when referenced unqualified.
  */
 export function dbSearchPath(settings: Pick<Settings, "dbSchema">): string | undefined {
@@ -1683,6 +1848,9 @@ export function stableSandboxEnvironmentForRun(
   }
   if (settings.toolspaceEnabled) {
     environment.OPENGENI_TOOLSPACE_TOKEN_FILE ??= `${environment.HOME ?? descriptor.workspaceRoot}/.opengeni/toolspace-token`;
+    if (settings.ogtoolPackageSpec) {
+      environment.OPENGENI_OGTOOL_PACKAGE_SPEC ??= settings.ogtoolPackageSpec;
+    }
     if (options.workspaceId) {
       environment.OPENGENI_TOOLSPACE_URL ??= firstPartyMcpWorkspaceUrl(
         settings,
@@ -2196,6 +2364,7 @@ function firstPartyDocumentsMcpServerUrl(mcpUrl: string): string {
 }
 
 function validateSettings(settings: Settings): void {
+  temporalConnectionOptions(settings);
   if (settings.toolspaceEnabled && !settings.delegationSecret) {
     throw new Error("OPENGENI_DELEGATION_SECRET is required when OPENGENI_TOOLSPACE_ENABLED=true");
   }
@@ -2507,7 +2676,7 @@ function validateSettings(settings: Settings): void {
       );
     }
   }
-  // --- stream-token secret: required-when-desktop, but GRACEFULLY DEGRADE (I8) ---
+  // --- stream-token secret: required-when-desktop, but GRACEFULLY DEGRADE (stream-token availability contract) ---
   // The desktop pixel plane needs an HMAC secret to mint scoped stream tokens.
   // It is REQUIRED when desktop is enabled — but per OD-8 a missing secret is NOT
   // a hard boot-fail: we emit a LOUD warning and the deployment ships with
@@ -2554,7 +2723,7 @@ function validateSettings(settings: Settings): void {
 }
 
 /**
- * Resolve the secret used to sign/verify scoped stream tokens (master-spine
+ * Resolve the secret used to sign/verify scoped stream tokens (sandbox contract
  * §C.3). Falls back to `delegationSecret` (the same HMAC envelope family —
  * `ogs_` vs `ogd_` prefix) so a deployment that already carries a delegation
  * secret does not need a second one. Returns undefined when neither is set,
@@ -2571,7 +2740,7 @@ export function resolveStreamTokenSecret(settings: Settings): string | undefined
 
 /**
  * True iff the desktop pixel plane must GRACEFULLY DEGRADE because desktop is
- * enabled but no stream-token secret is resolvable (I8/OD-8). When true,
+ * enabled but no stream-token secret is resolvable (stream-token availability contract). When true,
  * negotiateCapabilities forces DesktopStream.transport:null.
  */
 export function streamTokenDegraded(settings: Settings): boolean {
@@ -2580,7 +2749,7 @@ export function streamTokenDegraded(settings: Settings): boolean {
 
 /**
  * Resolve the secret the control plane signs the enrollment bearer credential
- * with (the `oge_` envelope the agent presents back — M5/dossier §10.2). Falls
+ * with (the `oge_` envelope the agent presents back — M5). Falls
  * back to `delegationSecret` (the same HMAC envelope family) so a deployment that
  * already carries a delegation secret needs no second one. Returns undefined when
  * neither is set; when selfhosted is enabled but this is undefined, the poll route
@@ -2598,7 +2767,7 @@ export function resolveEnrollmentSigningSecret(settings: Settings): string | und
 
 /**
  * Resolve the HMAC secret the control plane signs the agent's relay PRODUCER token
- * with (the `ogr_` envelope; M8b/dossier §10.5). The RELAY verifies the producer
+ * with (the `ogr_` envelope; M8b). The RELAY verifies the producer
  * token with the SAME secret (injected into the relay via env). Prefers an explicit
  * `selfhostedRelayTokenSecret`, then the `streamTokenSecret` (the relay already
  * needs that one to verify the viewer's `ogs_` token, so a single secret can back