@bitkyc08/opencodex 2.10.2 → 2.11.0

package/src/config.ts

@@ -27,8 +27,12 @@ import {
   isValidCodexAccountNamespaceTarget,
   MAIN_CODEX_ACCOUNT_NAMESPACE_TARGET,
 } from "./codex/account-namespace-match";
+import { isCodexAccountPriorityKey } from "./codex/account-priority";
+import { UPSTREAM_HOST_CIRCUIT_MAX_THRESHOLD } from "./codex/upstream-host-health";
+import { parseAccountPriority } from "./codex/pool-rotation";
 import { COMBO_NAMESPACE, comboConfigIssues } from "./combos/types";
 import { routingProfileIssues } from "./routing/profile";
+import { POLICY_NAMESPACE } from "./routing/profile-namespace";
 import {
   forgetEphemeralSecretPath,
   hardenSecretDir,
@@ -945,6 +949,33 @@ const codexAccountNamespacesSchema = z.custom<Record<string, unknown>>(
   }
 }).pipe(z.record(z.string(), z.string()));
 
+const CODEX_ACCOUNT_PRIORITIES_RECORD_ERROR =
+  "codexAccountPriorities must be a plain object mapping Codex account ids to selection-order integers";
+const CODEX_ACCOUNT_PRIORITY_KEY_ERROR =
+  "selection-order keys must be a Codex pool-account id or the main Codex account and cannot be reserved JavaScript object keys";
+const CODEX_ACCOUNT_PRIORITY_VALUE_ERROR =
+  "selection order must be an integer between -100 and 100";
+
+const CODEX_ACCOUNT_PIN_PATTERN = /^[a-zA-Z0-9._-]{1,64}$/;
+
+const codexAccountPrioritiesSchema = z.custom<Record<string, unknown>>(
+  (value): value is Record<string, unknown> => !!value
+    && typeof value === "object"
+    && !Array.isArray(value)
+    && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null),
+  { error: CODEX_ACCOUNT_PRIORITIES_RECORD_ERROR },
+).superRefine((priorities, ctx) => {
+  // Inspect raw own entries before z.record parses them; Zod omits __proto__ record keys.
+  for (const [accountId, priority] of Object.entries(priorities)) {
+    if (!isCodexAccountPriorityKey(accountId)) {
+      ctx.addIssue({ code: "custom", path: [accountId], message: CODEX_ACCOUNT_PRIORITY_KEY_ERROR });
+    }
+    if (parseAccountPriority(priority) === null) {
+      ctx.addIssue({ code: "custom", path: [accountId], message: CODEX_ACCOUNT_PRIORITY_VALUE_ERROR });
+    }
+  }
+}).pipe(z.record(z.string(), z.number().int()));
+
 /**
  * Deliberately permissive. A user's config is not ours to invalidate: a strict
  * entry fails the whole parse, and loadConfig's fallback then backs the file up
@@ -987,11 +1018,18 @@ const apiKeyEntrySchema = z.object({
 const clientIntegrationsSchema = z.object({
   codex: z.boolean().optional().catch(undefined),
   grok: z.boolean().optional().catch(undefined),
+  "claude-desktop": z.boolean().optional().catch(undefined),
 }).passthrough();
 
 const configSchema = z.object({
   port: z.number().int().min(0).max(65535).default(10100),
   managementUsageMaxReadBytes: z.number().int().positive().default(64 * 1024 * 1024),
+  // Invalid hand edits disable only this opt-in circuit. Live writes remain strict.
+  upstreamHostCircuitThreshold: z.number().int()
+    .min(0)
+    .max(UPSTREAM_HOST_CIRCUIT_MAX_THRESHOLD)
+    .optional()
+    .catch(undefined),
   appOwnedMemoryBudgetMb: z.number().int()
     .min(MIN_APP_OWNED_MEMORY_BUDGET_MB)
     .max(MAX_APP_OWNED_MEMORY_BUDGET_MB)
@@ -1004,6 +1042,14 @@ const configSchema = z.object({
   // is safe: startServer() already falls back to 127.0.0.1 for a missing hostname. Write-time
   // rejection lives in validateConfigCandidate() so bad values still surface to the caller.
   hostname: z.string().trim().min(1).optional().catch(undefined),
+  // Discriminated on `enabled` so a disabled entry cannot be forced to carry a port, and an
+  // enabled one cannot omit it (#1102). A malformed value degrades to undefined rather than
+  // failing the whole parse: this is an opt-in convenience surface, and a hand-edit typo here
+  // must never reset providers/apiKeys through the backup-and-defaults repair path.
+  unauthenticatedLoopbackListener: z.union([
+    z.object({ enabled: z.literal(false) }),
+    z.object({ enabled: z.literal(true), port: z.number().int().min(1).max(65535) }),
+  ]).optional().catch(undefined),
   providers: z.record(z.string(), providerConfigSchema),
   defaultProvider: z.string().min(1).default("openai"),
   openaiProviderTierVersion: z.union([z.literal(1), z.literal(2)]).optional(),
@@ -1024,6 +1070,15 @@ const configSchema = z.object({
   codexShimAutoRestore: z.boolean().optional(),
   pausedCodexAccountIds: z.array(z.string().regex(/^[a-zA-Z0-9._-]{1,64}$/)).optional(),
   codexAccountNamespaces: codexAccountNamespacesSchema.optional(),
+  // Selection order is a preference, not a safety control like pause: a malformed
+  // map degrades to "no ordering" rather than failing the parse, so a hand-edited
+  // typo cannot trip the backup-and-defaults repair path and wipe providers or
+  // pool accounts. Warning emitted in loadConfig.
+  codexAccountPriorities: codexAccountPrioritiesSchema.optional().catch(undefined),
+  activeCodexAccountPinned: z.string().regex(CODEX_ACCOUNT_PIN_PATTERN).optional().catch(undefined),
+  // A malformed hand edit must degrade to false without discarding providers, accounts,
+  // or the exact selector map. Live writes remain strict.
+  codexAccountPickerEnabled: z.boolean().optional().catch(false),
   // Model ids excluded from the Grok Build managed block (dashboard switches).
   grokExcludedModels: z.array(z.string()).optional(),
   // Invalid values degrade to undefined ("auto") instead of failing the whole
@@ -1076,6 +1131,7 @@ const configSchema = z.object({
     const configuredProviderNamespaces = new Set([
       COMBO_NAMESPACE,
       OPENAI_CODEX_PROVIDER_ID,
+      POLICY_NAMESPACE,
       ...Object.keys(config.providers),
     ].map(codexProviderNamespaceKey));
     const namespaceTargets = new Set(
@@ -1087,7 +1143,7 @@ const configSchema = z.object({
         ctx.addIssue({
           code: "custom",
           path: ["codexAccountNamespaces", namespace],
-          message: "account selectors must not collide with configured provider or combo namespaces",
+          message: "account selectors must not collide with configured provider, combo, or routing policy namespaces",
         });
       }
       if (configuredAccountIds.has(namespace) || namespaceTargets.has(namespace)) {
@@ -1493,6 +1549,32 @@ function warnDegradedHostname(rawParsed: unknown, validated: OcxConfig): void {
   }
 }
 
+/**
+ * Companion to {@link warnDegradedStreamMode} for a malformed selection-order map.
+ * Priority is a preference, so the schema drops the whole map rather than failing
+ * the parse — say so once, otherwise the pool silently reverts to flat ordering.
+ */
+function degradedCodexAccountPriorityWarnings(rawParsed: unknown, validated: OcxConfig): string[] {
+  const record = rawConfigRecord(rawParsed);
+  const warnings: string[] = [];
+  // The pin degrades silently otherwise, which reads as the manual selection simply
+  // not having survived the restart.
+  if (record?.activeCodexAccountPinned !== undefined && validated.activeCodexAccountPinned === undefined) {
+    warnings.push("activeCodexAccountPinned is not a valid account id — the manually selected account is no longer pinned");
+  }
+  const raw = record?.codexAccountPriorities;
+  if (raw !== undefined && validated.codexAccountPriorities === undefined) {
+    warnings.push("codexAccountPriorities is invalid (expected account ids mapped to integers between -100 and 100) — account selection order is disabled");
+  }
+  return warnings;
+}
+
+function warnDegradedCodexAccountPriorities(rawParsed: unknown, validated: OcxConfig): void {
+  for (const warning of degradedCodexAccountPriorityWarnings(rawParsed, validated)) {
+    console.warn(`⚠️  config.json ${warning}`);
+  }
+}
+
 /**
  * The apiKeys schema salvages entry by entry rather than failing the parse, so a
  * dropped key is otherwise invisible — and it will not be re-saved by the next
@@ -1621,6 +1703,23 @@ function warnDegradedClaudeSubagentEffort(rawParsed: unknown): void {
   }
 }
 
+function malformedUpstreamHostCircuitThresholdWarning(rawParsed: unknown): string | null {
+  const raw = rawConfigRecord(rawParsed);
+  if (!raw || !Object.hasOwn(raw, "upstreamHostCircuitThreshold")) return null;
+  const threshold = raw.upstreamHostCircuitThreshold;
+  if (threshold === undefined) return null;
+  if (typeof threshold === "number"
+    && Number.isInteger(threshold)
+    && threshold >= 0
+    && threshold <= UPSTREAM_HOST_CIRCUIT_MAX_THRESHOLD) return null;
+  return `upstreamHostCircuitThreshold ignored: expected an integer from 0 to ${UPSTREAM_HOST_CIRCUIT_MAX_THRESHOLD}`;
+}
+
+function warnDegradedUpstreamHostCircuitThreshold(rawParsed: unknown): void {
+  const warning = malformedUpstreamHostCircuitThresholdWarning(rawParsed);
+  if (warning) console.warn(`⚠️  config.json ${warning}. Other settings were preserved.`);
+}
+
 type NativeSubagentPersistedField = "injectionModel" | "injectionEffort" | "syncCodexSubagentDefaults";
 
 function rawConfigRecord(rawParsed: unknown): Record<string, unknown> | null {
@@ -1650,6 +1749,18 @@ function malformedNativeSubagentFieldWarning(field: NativeSubagentPersistedField
   return `${field} ignored: expected ${expected}`;
 }
 
+function malformedCodexAccountPickerWarning(rawParsed: unknown): string | null {
+  const raw = rawConfigRecord(rawParsed);
+  if (!raw || !Object.hasOwn(raw, "codexAccountPickerEnabled")) return null;
+  if (typeof raw.codexAccountPickerEnabled === "boolean") return null;
+  return "codexAccountPickerEnabled ignored: expected a boolean";
+}
+
+function warnDegradedCodexAccountPicker(rawParsed: unknown): void {
+  const warning = malformedCodexAccountPickerWarning(rawParsed);
+  if (warning) console.warn(`⚠️  config.json ${warning}. Other settings were preserved.`);
+}
+
 function nativeSubagentSyncDisabledReason(config: OcxConfig, rawParsed?: unknown): string | null {
   if (config.syncCodexSubagentDefaults !== true) return null;
   const malformed = malformedNativeSubagentFields(rawParsed);
@@ -1698,8 +1809,11 @@ export function loadConfig(): OcxConfig {
       warnDegradedStreamMode(parsed, config);
       warnDegradedHostname(parsed, config);
       warnDegradedApiKeys(parsed, config);
+      warnDegradedCodexAccountPriorities(parsed, config);
       warnDegradedClaudeSubagentEffort(parsed);
       warnDegradedNativeSubagentConfig(parsed, config);
+      warnDegradedCodexAccountPicker(parsed);
+      warnDegradedUpstreamHostCircuitThreshold(parsed);
       return normalizeClaudeSubagentEffort(normalizeNativeSubagentSync(config, parsed), parsed);
     }
     // Schema validation failed — merge defaults into the raw object instead of
@@ -1717,8 +1831,11 @@ export function loadConfig(): OcxConfig {
       const config = normalizeApiKeyIds(retryResult.data as OcxConfig);
       warnDegradedHostname(parsed, config);
       warnDegradedApiKeys(parsed, config);
+      warnDegradedCodexAccountPriorities(parsed, config);
       warnDegradedClaudeSubagentEffort(parsed);
       warnDegradedNativeSubagentConfig(parsed, config);
+      warnDegradedCodexAccountPicker(parsed);
+      warnDegradedUpstreamHostCircuitThreshold(parsed);
       return normalizeClaudeSubagentEffort(normalizeNativeSubagentSync(config, parsed), parsed);
     }
     // Merge couldn't fix it — truly broken config
@@ -1763,10 +1880,15 @@ function validFileConfigDiagnostics(config: OcxConfig, rawParsed: unknown): Conf
   const rawEffort = rawClaudeSubagentEffort(rawParsed);
   const normalized = normalizeClaudeSubagentEffort(normalizeNativeSubagentSync(config, rawParsed), rawParsed);
   const warnings = configPlaceholderWarnings(normalized);
+  warnings.push(...degradedCodexAccountPriorityWarnings(rawParsed, normalized));
   if (rawEffort !== undefined && !isClaudeSubagentEffort(rawEffort)) {
     warnings.push(`claudeCode.subagentEffort ignored: expected one of ${CLAUDE_SUBAGENT_EFFORTS.join(", ")}`);
   }
   warnings.push(...malformedNativeSubagentFields(rawParsed).map(malformedNativeSubagentFieldWarning));
+  const pickerWarning = malformedCodexAccountPickerWarning(rawParsed);
+  if (pickerWarning) warnings.push(pickerWarning);
+  const hostCircuitWarning = malformedUpstreamHostCircuitThresholdWarning(rawParsed);
+  if (hostCircuitWarning) warnings.push(hostCircuitWarning);
   if (syncDisabledReason) {
     warnings.push(`syncCodexSubagentDefaults ignored: ${syncDisabledReason}`);
   }
@@ -1836,6 +1958,44 @@ function appOwnedMemoryBudgetError(value: unknown): string | null {
   return null;
 }
 
+function upstreamHostCircuitThresholdError(value: unknown): string | null {
+  const raw = rawConfigRecord(value);
+  if (!raw || !Object.hasOwn(raw, "upstreamHostCircuitThreshold")) return null;
+  const threshold = raw.upstreamHostCircuitThreshold;
+  if (threshold === undefined) return null;
+  if (typeof threshold === "number"
+    && Number.isInteger(threshold)
+    && threshold >= 0
+    && threshold <= UPSTREAM_HOST_CIRCUIT_MAX_THRESHOLD) return null;
+  return `schema_invalid: upstreamHostCircuitThreshold: must be an integer from 0 to ${UPSTREAM_HOST_CIRCUIT_MAX_THRESHOLD}`;
+}
+
+/**
+ * Same reasoning as {@link blankHostnameError}, and more urgent: the read path degrades a
+ * malformed selection-order map to undefined, which on a write would drop every entry the
+ * user had accumulated and still report success. A load-time degrade leaves the raw map in
+ * the file to be repaired by hand; a degraded write erases it. One bad `ocx config set`
+ * must not cost the whole map, so a live caller is told instead.
+ */
+function codexAccountPrioritiesError(value: unknown): string | null {
+  const raw = rawConfigRecord(value);
+  if (!raw) return null;
+  if (raw.codexAccountPriorities !== undefined) {
+    const parsed = codexAccountPrioritiesSchema.safeParse(raw.codexAccountPriorities);
+    if (!parsed.success) {
+      return schemaDiagnosticsError(parsed.error).replace("schema_invalid: ", "schema_invalid: codexAccountPriorities.");
+    }
+  }
+  // Tested as a string rather than coerced: `String(123)` matches the id pattern, so a
+  // coercing guard waves a non-string pin through to the schema, where `.catch(undefined)`
+  // drops it and reports the write as a success — the exact silent-degrade this guards.
+  const pin = raw.activeCodexAccountPinned;
+  if (pin !== undefined && (typeof pin !== "string" || !CODEX_ACCOUNT_PIN_PATTERN.test(pin))) {
+    return "schema_invalid: activeCodexAccountPinned: must be an account id";
+  }
+  return null;
+}
+
 function googleAntigravityStaticCatalogVersionError(value: unknown): string | null {
   const raw = rawConfigRecord(value);
   if (!raw || !Object.hasOwn(raw, "googleAntigravityStaticCatalogVersion")) return null;
@@ -1844,12 +2004,71 @@ function googleAntigravityStaticCatalogVersionError(value: unknown): string | nu
   return "schema_invalid: googleAntigravityStaticCatalogVersion: must be 1 or omitted";
 }
 
+function codexAccountPickerEnabledError(value: unknown): string | null {
+  const raw = rawConfigRecord(value);
+  if (!raw) return null;
+  const descriptor = Object.getOwnPropertyDescriptor(raw, "codexAccountPickerEnabled");
+  if (!descriptor) {
+    return "codexAccountPickerEnabled" in raw
+      ? "schema_invalid: codexAccountPickerEnabled: must be an own boolean data property or omitted"
+      : null;
+  }
+  if (!("value" in descriptor)) {
+    return "schema_invalid: codexAccountPickerEnabled: must be an own boolean data property or omitted";
+  }
+  const enabled = descriptor.value;
+  if (enabled === undefined || typeof enabled === "boolean") return null;
+  return "schema_invalid: codexAccountPickerEnabled: must be a boolean or omitted";
+}
+
 /** Validate an in-memory config candidate without touching disk. Used by headless CLI import/set. */
+/**
+ * Reject a loopback-listener port that collides with the proxy port (#1102).
+ *
+ * The schema can only check the shape of each field on its own; the two ports being distinct
+ * is a relationship between them. Letting the pair through would surface as a startup failure
+ * after the public listener already bound, which reads like an unrelated port conflict.
+ *
+ * This is write-time only, matching `blankHostnameError`: a live caller can be told the value
+ * is wrong, whereas a hand-edited config on the read path degrades to undefined rather than
+ * resetting the whole file.
+ */
+function loopbackListenerPortError(value: unknown): string | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const listener = (value as Record<string, unknown>).unauthenticatedLoopbackListener;
+  if (listener === undefined) return null;
+  if (!listener || typeof listener !== "object" || Array.isArray(listener)) {
+    return "schema_invalid: unauthenticatedLoopbackListener: must be an object or omitted";
+  }
+  const entry = listener as Record<string, unknown>;
+  // `enabled` must be a real boolean. The schema's `.catch(undefined)` would otherwise DELETE
+  // a `"true"` string entry and report success, leaving an operator convinced they enabled an
+  // unauthenticated listener that is in fact off. Load-time still degrades quietly — a hand
+  // edit must not reset the file — but a live caller gets told.
+  if (typeof entry.enabled !== "boolean") {
+    return "schema_invalid: unauthenticatedLoopbackListener.enabled: must be a boolean";
+  }
+  if (entry.enabled !== true) return null;
+  const listenerPort = entry.port;
+  if (typeof listenerPort !== "number" || !Number.isInteger(listenerPort) || listenerPort < 1 || listenerPort > 65535) {
+    return "schema_invalid: unauthenticatedLoopbackListener.port: must be an integer port when enabled";
+  }
+  const proxyPort = (value as Record<string, unknown>).port;
+  if (typeof proxyPort === "number" && proxyPort === listenerPort) {
+    return "schema_invalid: unauthenticatedLoopbackListener.port: must differ from the proxy port";
+  }
+  return null;
+}
+
 export function validateConfigCandidate(value: unknown): { ok: true; config: OcxConfig } | { ok: false; error: string } {
   const boundaryError = blankHostnameError(value)
     ?? claudeSubagentEffortError(value)
     ?? appOwnedMemoryBudgetError(value)
-    ?? googleAntigravityStaticCatalogVersionError(value);
+    ?? upstreamHostCircuitThresholdError(value)
+    ?? googleAntigravityStaticCatalogVersionError(value)
+    ?? codexAccountPrioritiesError(value)
+    ?? codexAccountPickerEnabledError(value)
+    ?? loopbackListenerPortError(value);
   if (boundaryError) return { ok: false, error: boundaryError };
   const result = configSchema.safeParse(value);
   if (result.success) return { ok: true, config: normalizeApiKeyIds(result.data as OcxConfig) };

package/src/images/loop.ts

@@ -900,7 +900,7 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
   }
 
   const sse = bridgeToResponsesSSE(
-    produce(), parsed.modelId, toolNsMap, freeform, toolSearch, () => {
+    produce(), parsed._responseModelId ?? parsed.modelId, toolNsMap, freeform, toolSearch, () => {
       internalAbort.abort("client closed responses stream");
     }, 2_000,
     {

package/src/integrations/native/ownership-preflight.ts

@@ -78,6 +78,25 @@ function claimNamesDifferentHome(
   return false;
 }
 
+/**
+ * Map a service-manager claim backend to the `ServiceInstallState.backend`
+ * value it corresponds to. `scheduler` (Task Scheduler) and `winsw` (native)
+ * are the two Windows manager backends; launchd/systemd claims have no Windows
+ * backend and can never mismatch a v2 state file.
+ */
+function claimBackendToStateBackend(backend: ServiceManagerClaim["backend"]): "scheduler" | "native" | null {
+  if (backend === "scheduler") return "scheduler";
+  if (backend === "winsw") return "native";
+  return null;
+}
+
+/** True when the recorded state backend disagrees with the manager claim. Legacy v1 means scheduler. */
+function claimBackendMismatchesState(claim: ServiceManagerClaim, state: { backend?: "scheduler" | "native" }): boolean {
+  const expected = claimBackendToStateBackend(claim.backend);
+  if (expected === null) return false;
+  return (state.backend ?? "scheduler") !== expected;
+}
+
 export interface OwnershipDeps extends ProbeDeps {
   /**
    * Which state paths to consult. Injectable because the default set includes
@@ -125,7 +144,14 @@ export function inspectNativeCodexOwnership(deps: OwnershipDeps = {}): Ownership
     };
   }
 
-  const manager = inspectServiceManagerInstallation(deps);
+  // The manager assets live under the effective OPENCODEX_HOME. Production
+  // callers do not inject ProbeDeps.configDir, so derive it from the same
+  // current-home snapshot used for ownership comparison rather than silently
+  // falling back to <homedir>/.opencodex.
+  const manager = inspectServiceManagerInstallation({
+    ...deps,
+    configDir: deps.configDir ?? current.opencodexHome,
+  });
   if (manager.kind === "unknown") {
     return { ownership: "unknown", reason: manager.reason };
   }
@@ -146,6 +172,17 @@ export function inspectNativeCodexOwnership(deps: OwnershipDeps = {}): Ownership
         reason: `${disagreeing.backend} is installed from ${disagreeing.definitionPath}, which names different homes than the recorded service state`,
       };
     }
+    // A manager backend that disagrees with the recorded state (e.g. state says
+    // native/WinSW but a scheduler task is found) is an interrupted backend
+    // switch: it does not prove which manager owns the installation. v1 state
+    // predates the field and is scheduler by contract.
+    const stateBackendMismatch = valid.find(state => manager.claims.some(claim => claimBackendMismatchesState(claim, state.state)));
+    if (stateBackendMismatch) {
+      return {
+        ownership: "unknown",
+        reason: `the service state records backend ${stateBackendMismatch.state.backend ?? "scheduler"} but ${manager.claims[0]?.backend ?? "a service manager"} is installed`,
+      };
+    }
     // Definition agrees. Valid state agreeing with it is ownership; no state at
     // all beside an installed definition is not, because the definition is the
     // claim and nothing here recorded making it.
@@ -162,4 +199,4 @@ export function inspectNativeCodexOwnership(deps: OwnershipDeps = {}): Ownership
   return valid.length === 0
     ? { ownership: "owned", reason: "no service state and no service manager claim" }
     : { ownership: "owned", reason: "the recorded service state names these homes" };
-}
+}

package/src/lib/bun-stream-caps.ts

@@ -94,7 +94,7 @@ export function decideEagerRelay(
  * Windows preserves the decision for no-rewrite traffic. Darwin permits only
  * explicit config opt-in; `auto` remains tee even on a future fixed runtime.
  * Returns the normalized effective decision, or null when platform policy,
- * rewrite needs, or a Darwin non-config-eager mode selects tee.
+ * Windows rewrite needs, or a Darwin non-config-eager mode selects tee.
  */
 export function selectEagerPath(
   platform: NodeJS.Platform,
@@ -103,12 +103,12 @@ export function selectEagerPath(
   version: string = Bun.version,
   minFixed: string | null = MIN_FIXED_BUN_VERSION,
 ): EagerRelayDecision | null {
-  if (needsClientRewrite || (platform !== "win32" && platform !== "darwin")) {
+  if (platform !== "win32" && platform !== "darwin") {
     return null;
   }
 
   const decision = decideEagerRelay(mode, version, minFixed);
-  if (platform === "win32") return decision;
+  if (platform === "win32") return needsClientRewrite ? null : decision;
   return decision.reason === "config-eager" ? decision : null;
 }
 

package/src/lib/sse-decoder.ts

@@ -13,6 +13,47 @@ export type SseRecord =
   | { kind: "event"; event?: string; data: string }
   | { kind: "comment"; comment: string };
 
+/**
+ * Extract one SSE field value from a single line, or null when the line is a different field.
+ *
+ * The space after the colon is OPTIONAL in text/event-stream: `data:{"a":1}` is as valid as
+ * `data: {"a":1}`. Parsers that hardcoded `startsWith("data: ")` silently dropped every frame
+ * from a producer that omits it, which surfaced as a completed turn with no content (#1170).
+ *
+ * Strips at most ONE leading space — the same rule `decodeServerSentEvents` applies below — so a
+ * payload that legitimately begins with whitespace keeps the rest of it. Does not trim the value:
+ * callers own that choice, and some of them intentionally keep trailing bytes.
+ */
+export function sseFieldValue(line: string, field: string): string | null {
+  if (!line.startsWith(field)) return null;
+  const rest = line.slice(field.length);
+  // A colonless field line is the field with an empty value per the SSE rules, and
+  // `decodeServerSentEvents` below treats it that way (`colon < 0` -> valueStart = line.length).
+  // These helpers must not disagree with the decoder they mirror.
+  if (rest.length === 0) return "";
+  if (!rest.startsWith(":")) return null;
+  return rest.startsWith(": ") ? rest.slice(2) : rest.slice(1);
+}
+
+/**
+ * Offset-only variant of {@link sseFieldValue} for parsers that index into a larger buffer.
+ *
+ * Returns the index where the field's value begins within `text`, or -1 when the line at
+ * `[lineStart, lineEnd)` is a different field. Slicing nothing matters for the live Claude relay,
+ * whose translator-budget accounting reserves bytes by offset — materializing the line first would
+ * allocate the very string the budget exists to bound.
+ */
+export function sseFieldOffset(text: string, lineStart: number, lineEnd: number, field: string): number {
+  if (!text.startsWith(field, lineStart)) return -1;
+  let valueStart = lineStart + field.length;
+  // Colonless field line: empty value, positioned at end-of-line (matches the decoder).
+  if (valueStart >= lineEnd) return lineEnd;
+  if (text[valueStart] !== ":") return -1;
+  valueStart += 1;
+  if (valueStart < lineEnd && text[valueStart] === " ") valueStart += 1;
+  return valueStart;
+}
+
 /**
  * Decode text/event-stream records across arbitrary fetch chunk boundaries.
  *

package/src/lib/system-restart-contract.ts

@@ -0,0 +1,73 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { isLocalAttestationSecret } from "./local-management-attestation";
+
+export const SYSTEM_RESTART_METHOD = "POST";
+export const SYSTEM_RESTART_PATH = "/api/system/restart";
+export const SYSTEM_RESTART_CAPABILITY_VERSION = "v1";
+export const SYSTEM_RESTART_EXPECTED_PID_HEADER = "x-opencodex-restart-expected-pid";
+export const SYSTEM_RESTART_NONCE_HEADER = "x-opencodex-restart-nonce";
+export const SYSTEM_RESTART_CAPABILITY_HEADER = "x-opencodex-restart-capability";
+
+/** Fixed drain and replacement budgets shared by the server, CLI, and tray. */
+export const MEMORY_DRAIN_RESTART_MS = 60_000;
+export const REPLACEMENT_READY_TIMEOUT_MS = 70_000;
+
+const BASE64URL_256 = /^[A-Za-z0-9_-]{43}$/;
+
+export type ExpectedSystemRestartPid =
+  | { kind: "absent" }
+  | { kind: "invalid" }
+  | { kind: "present"; pid: number };
+
+export function parseExpectedSystemRestartPid(value: string | null): ExpectedSystemRestartPid {
+  if (value === null) return { kind: "absent" };
+  if (!/^[1-9]\d*$/.test(value)) return { kind: "invalid" };
+  const pid = Number(value);
+  return Number.isSafeInteger(pid) ? { kind: "present", pid } : { kind: "invalid" };
+}
+
+function restartCapabilityPayload(
+  nonce: string,
+  method: string,
+  path: string,
+  pid: number,
+  port: number,
+): string | null {
+  if (!BASE64URL_256.test(nonce)) return null;
+  if (method !== SYSTEM_RESTART_METHOD || path !== SYSTEM_RESTART_PATH) return null;
+  if (!Number.isSafeInteger(pid) || pid <= 0) return null;
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) return null;
+  return `opencodex-system-restart-v1\n${nonce}\n${method}\n${path}\n${pid}\n${port}`;
+}
+
+/** Process-scoped, operation-only authorization. It is not a reusable management credential. */
+export function createSystemRestartCapability(
+  secret: string,
+  nonce: string,
+  method: string,
+  path: string,
+  pid: number,
+  port: number,
+): string | null {
+  if (!isLocalAttestationSecret(secret)) return null;
+  const payload = restartCapabilityPayload(nonce, method, path, pid, port);
+  if (!payload) return null;
+  return createHmac("sha256", secret).update(payload).digest("base64url");
+}
+
+export function verifySystemRestartCapability(
+  secret: string,
+  nonce: string | null,
+  method: string,
+  path: string,
+  pid: number,
+  port: number,
+  capability: string | null,
+): boolean {
+  if (!nonce || !capability || !BASE64URL_256.test(capability)) return false;
+  const expected = createSystemRestartCapability(secret, nonce, method, path, pid, port);
+  if (!expected) return false;
+  const expectedBytes = Buffer.from(expected);
+  const actualBytes = Buffer.from(capability);
+  return expectedBytes.length === actualBytes.length && timingSafeEqual(expectedBytes, actualBytes);
+}