@bitkyc08/opencodex 2.83.0 → 2.84.0

package/src/service/health-sentinel-policy.ts

@@ -0,0 +1,241 @@
+/**
+ * Health-unresponsiveness recovery policy for the opt-in service health sentinel (#6671).
+ *
+ * Every supervisor this repository installs restarts the proxy only when it exits: the Windows
+ * Task Scheduler batch loop, launchd `KeepAlive`/`SuccessfulExit=false`, systemd
+ * `Restart=on-failure` and the desktop app's `on_exit`. A proxy that stays alive with its port
+ * listening while its event loop answers nothing is invisible to all of them. The sentinel turns
+ * that state into an exit, and this module is the whole of its judgement: pure, clock-injected,
+ * and free of I/O so every false-positive guard is testable on any platform.
+ *
+ * The guards, in the order they apply:
+ * - nothing counts until the target has answered once as itself and the startup grace is over;
+ *   the grace is elapsed time, so setting the clock back neither restarts nor extends it;
+ * - only a probe that got no complete answer by its deadline counts. Any answer proves the event
+ *   loop ran, and a refused or failed connection means the listener is closing, not hung;
+ * - an answer from another pid means the port is no longer the target's: stand down for good;
+ * - a probe that started far later than the cadence allows, that outlived its own deadline by
+ *   far more than jitter, or during which the sentinel's own event loop ran late (sleep, or the
+ *   sentinel itself paused or starved), discards the streak, because the timeout may belong to
+ *   that pause rather than to the target;
+ * - once a probe times out the next ones follow back to back, so a run of timeouts is one
+ *   continuous unresponsive stretch rather than separate stalls that line up with the cadence;
+ * - recovery needs both a run of consecutive timeouts and a minimum unhealthy span, which doubles
+ *   for each recovery in the last hour, and a cap on recoveries per hour stands the sentinel down:
+ *   a proxy that hangs again right after every restart is not fixed by killing it, and each kill
+ *   loses the work it held. Nothing is ever replayed.
+ */
+
+export type HealthProbeOutcome =
+  /** A complete status line and headers arrived before the deadline. */
+  | { kind: "answered"; pid: number | null; startedAt: number; endedAt: number }
+  /**
+   * No complete answer by the deadline, whether or not the connection was accepted.
+   * `sentinelLagMs` is how late the sentinel's own event loop ran during the probe: a sentinel
+   * that was itself paused or starved cannot tell a silent target from its own silence.
+   */
+  | { kind: "timeout"; startedAt: number; endedAt: number; sentinelLagMs?: number }
+  /** The connection was refused: nothing is listening. */
+  | { kind: "refused"; startedAt: number; endedAt: number }
+  /** Any other failure. */
+  | { kind: "error"; startedAt: number; endedAt: number };
+
+export type HealthSentinelTiming = {
+  /** Time between the end of one answered probe and the start of the next. */
+  intervalMs: number;
+  /**
+   * Time between a timed-out probe and the next. Short on purpose: back-to-back probes make a run
+   * of timeouts mean one continuous unresponsive stretch, so recurring shorter stalls that happen
+   * to line up with the cadence cannot add up to a recovery.
+   */
+  failureIntervalMs: number;
+  /** A probe without a complete answer by this deadline is a timeout. */
+  probeTimeoutMs: number;
+  /** Counted from the sentinel's start; nothing counts before it ends. */
+  startupGraceMs: number;
+  /** Consecutive timeouts needed before a recovery. */
+  failureThreshold: number;
+  /** Minimum span from the first failing probe's start to the last one's end, before backoff. */
+  minUnhealthyMs: number;
+  /** Slack over the cadence (and over a probe's deadline) before a pause voids the streak. */
+  suspendSlackMs: number;
+  /** A timeout during which the sentinel's own loop ran later than this is not evidence. */
+  lagToleranceMs: number;
+  /** Window over which earlier recoveries raise the backoff and count toward the cap. */
+  recoveryWindowMs: number;
+  /** Recoveries within the window after which the sentinel stands down. */
+  maxRecoveriesPerWindow: number;
+  /** Ceiling on the backoff multiplier. */
+  maxBackoffMultiplier: number;
+  /**
+   * Oldest the final failing observation may be when the kill is issued. Lease, history and log
+   * work runs between the decision and the kill; evidence older than this is discarded.
+   */
+  maxEvidenceAgeMs: number;
+};
+
+export const DEFAULT_HEALTH_SENTINEL_TIMING: Readonly<HealthSentinelTiming> = Object.freeze({
+  intervalMs: 30_000,
+  failureIntervalMs: 1_000,
+  probeTimeoutMs: 20_000,
+  startupGraceMs: 120_000,
+  failureThreshold: 3,
+  minUnhealthyMs: 60_000,
+  suspendSlackMs: 5_000,
+  lagToleranceMs: 2_000,
+  recoveryWindowMs: 60 * 60_000,
+  maxRecoveriesPerWindow: 3,
+  maxBackoffMultiplier: 8,
+  maxEvidenceAgeMs: 5_000,
+});
+
+export type HealthSentinelDecision =
+  | { action: "continue"; note?: string }
+  | { action: "recover"; reason: string; consecutiveTimeouts: number; unhealthyMs: number }
+  /** Stop acting for this target; the reason is logged once. */
+  | { action: "stand_down"; reason: string };
+
+export type HealthSentinelPolicyState = {
+  readonly armed: boolean;
+  readonly consecutiveTimeouts: number;
+  readonly firstFailureStartedAt: number | null;
+  readonly lastObservedAt: number | null;
+  readonly stoodDown: string | null;
+};
+
+export type HealthSentinelPolicy = {
+  observe(outcome: HealthProbeOutcome): HealthSentinelDecision;
+  state(): HealthSentinelPolicyState;
+  /** Minimum unhealthy span currently required, after backoff. */
+  requiredUnhealthyMs(): number;
+  /** How long to wait before the next probe: short while a failure streak is open. */
+  nextDelayMs(): number;
+};
+
+/**
+ * Recoveries recorded inside the window ending at `now`. An entry dated after `now` counts as
+ * recent: it means the wall clock was set back after it was written, and dropping it would let a
+ * clock rollback (or a restart after one) lift the hourly cap. It keeps counting until the clock
+ * passes it by a full window, which errs toward not killing.
+ */
+export function recentRecoveryCount(history: readonly number[], now: number, windowMs: number): number {
+  return history.filter(at => Number.isFinite(at) && now - at < windowMs).length;
+}
+
+/** The unhealthy span required after `recent` recoveries: doubled per recovery, capped. */
+export function requiredUnhealthySpan(timing: HealthSentinelTiming, recent: number): number {
+  const multiplier = Math.min(timing.maxBackoffMultiplier, 2 ** Math.max(0, recent));
+  return timing.minUnhealthyMs * multiplier;
+}
+
+export function createHealthSentinelPolicy(input: {
+  targetPid: number;
+  startedAt: number;
+  /** Epoch-ms of earlier recoveries for this installation, newest last. */
+  recoveryHistory: readonly number[];
+  timing?: Partial<HealthSentinelTiming>;
+}): HealthSentinelPolicy {
+  const timing: HealthSentinelTiming = { ...DEFAULT_HEALTH_SENTINEL_TIMING, ...input.timing };
+  let armed = false;
+  let streak = 0;
+  let firstFailureStartedAt: number | null = null;
+  let lastObservedAt: number | null = null;
+  let stoodDown: string | null = null;
+  let required = timing.minUnhealthyMs;
+  // Startup grace is measured as elapsed time, accumulated from forward clock movement only, so a
+  // wall clock set back after (or during) the grace cannot reopen it and hold off recovery for as
+  // long as the clock was moved.
+  let graceElapsedMs = 0;
+  let graceClock = input.startedAt;
+  const noteGraceProgress = (at: number) => {
+    if (at > graceClock) graceElapsedMs += at - graceClock;
+    graceClock = at;
+  };
+
+  const resetStreak = () => {
+    streak = 0;
+    firstFailureStartedAt = null;
+  };
+
+  const standDown = (reason: string): HealthSentinelDecision => {
+    stoodDown = reason;
+    resetStreak();
+    return { action: "stand_down", reason };
+  };
+
+  const observe = (outcome: HealthProbeOutcome): HealthSentinelDecision => {
+    if (stoodDown !== null) return { action: "stand_down", reason: stoodDown };
+    noteGraceProgress(outcome.startedAt);
+    const previous = lastObservedAt;
+    lastObservedAt = outcome.endedAt;
+    let note: string | undefined;
+    if (previous !== null && streak > 0 && outcome.startedAt - previous > timing.failureIntervalMs + timing.suspendSlackMs) {
+      // The sentinel overslept its cadence (a suspended machine, or the sentinel itself starved),
+      // so the timeouts counted so far may belong to that pause rather than to the target.
+      resetStreak();
+      note = "observation gap; failure streak discarded";
+    }
+    switch (outcome.kind) {
+      case "answered": {
+        if (outcome.pid !== null && outcome.pid !== input.targetPid) {
+          return standDown("another process answers the health endpoint");
+        }
+        if (outcome.pid === input.targetPid) armed = true;
+        resetStreak();
+        return { action: "continue", note };
+      }
+      case "refused":
+      case "error":
+        resetStreak();
+        return { action: "continue", note };
+      case "timeout": {
+        if (!armed) return { action: "continue", note: note ?? "not armed: the target has not answered yet" };
+        if (graceElapsedMs < timing.startupGraceMs) {
+          return { action: "continue", note: note ?? "startup grace" };
+        }
+        if (
+          outcome.endedAt - outcome.startedAt > timing.probeTimeoutMs + timing.suspendSlackMs
+          || outcome.endedAt < outcome.startedAt
+          || (previous !== null && outcome.startedAt < previous)
+        ) {
+          // The probe outlived its own deadline by far more than scheduling jitter, or the wall
+          // clock ran backwards: its timing spanned a pause or a clock step, so this timeout says
+          // nothing about the target.
+          resetStreak();
+          return { action: "continue", note: "probe spanned a pause; failure streak discarded" };
+        }
+        if ((outcome.sentinelLagMs ?? 0) > timing.lagToleranceMs) {
+          // The sentinel itself stalled during the probe (paused, starved, or the machine slept),
+          // so the deadline may have expired while nobody was listening for the answer.
+          resetStreak();
+          return { action: "continue", note: "probe spanned a pause; failure streak discarded" };
+        }
+        streak += 1;
+        if (firstFailureStartedAt === null) firstFailureStartedAt = outcome.startedAt;
+        const unhealthyMs = outcome.endedAt - firstFailureStartedAt;
+        const recent = recentRecoveryCount(input.recoveryHistory, outcome.endedAt, timing.recoveryWindowMs);
+        required = requiredUnhealthySpan(timing, recent);
+        if (streak < timing.failureThreshold || unhealthyMs < required) return { action: "continue", note };
+        if (recent >= timing.maxRecoveriesPerWindow) {
+          return standDown(`${recent} recoveries in the last ${Math.round(timing.recoveryWindowMs / 60_000)} minutes; not recovering again`);
+        }
+        const decision: HealthSentinelDecision = {
+          action: "recover",
+          reason: `no health answer for ${streak} consecutive probes over ${Math.round(unhealthyMs / 1000)}s`,
+          consecutiveTimeouts: streak,
+          unhealthyMs,
+        };
+        resetStreak();
+        return decision;
+      }
+    }
+  };
+
+  return {
+    observe,
+    state: () => ({ armed, consecutiveTimeouts: streak, firstFailureStartedAt, lastObservedAt, stoodDown }),
+    requiredUnhealthyMs: () => required,
+    nextDelayMs: () => (streak > 0 ? timing.failureIntervalMs : timing.intervalMs),
+  };
+}
+

package/src/service/health-sentinel-probe.ts

@@ -0,0 +1,54 @@
+/**
+ * The service health sentinel's one question to the proxy it watches: does `GET /healthz`
+ * produce a complete answer before the deadline (#6671)?
+ *
+ * The request goes through {@link directLocalHttpFetch}: raw `node:net`, so neither proxy
+ * environment variables nor the bundled runtime's fetch stack (#6684) are involved, with capped
+ * response framing and an absolute deadline. Only the timing decides liveness; the body's `pid`
+ * lets the policy tell the target from another process that took the port.
+ */
+import { directLocalHttpFetch } from "../server/direct-local-http";
+import type { HealthProbeOutcome } from "./health-sentinel-policy";
+
+export type HealthProbeTarget = { hostname: string; port: number };
+
+export type HealthProbeIo = {
+  now?: () => number;
+  fetch?: (url: string, timeoutMs: number) => Promise<Response>;
+};
+
+/** The URL host to dial for a recorded listen hostname: wildcard binds answer on loopback. */
+export function probeUrlHost(hostname: string | undefined): string {
+  const value = (hostname ?? "").trim().replace(/^\[|\]$/g, "");
+  if (!value || value === "0.0.0.0" || value === "localhost") return "127.0.0.1";
+  if (value === "::") return "[::1]";
+  return value.includes(":") ? `[${value}]` : value;
+}
+
+/** `pid` from a `/healthz` JSON body, or null when the body does not carry one. */
+export function healthzPid(body: string): number | null {
+  try {
+    const parsed = JSON.parse(body) as { pid?: unknown };
+    return typeof parsed.pid === "number" && Number.isSafeInteger(parsed.pid) && parsed.pid > 0 ? parsed.pid : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function probeHealth(target: HealthProbeTarget, timeoutMs: number, io: HealthProbeIo = {}): Promise<HealthProbeOutcome> {
+  const now = io.now ?? Date.now;
+  const fetchFn = io.fetch ?? ((url: string, deadlineMs: number) => directLocalHttpFetch(url, { headers: { accept: "application/json" } }, { timeoutMs: deadlineMs }));
+  const startedAt = now();
+  try {
+    const response = await fetchFn(`http://${probeUrlHost(target.hostname)}:${target.port}/healthz`, timeoutMs);
+    // The framed body is already in memory; reading it cannot wait on the target.
+    const body = await response.text().catch(() => "");
+    return { kind: "answered", pid: healthzPid(body), startedAt, endedAt: now() };
+  } catch (error) {
+    const endedAt = now();
+    const failure = error as { name?: unknown; code?: unknown };
+    if (failure?.name === "TimeoutError") return { kind: "timeout", startedAt, endedAt };
+    if (failure?.code === "ECONNREFUSED") return { kind: "refused", startedAt, endedAt };
+    return { kind: "error", startedAt, endedAt };
+  }
+}

package/src/service/health-sentinel-windows.ts

@@ -0,0 +1,87 @@
+/**
+ * A Windows process handle on the health sentinel's parent, held for the sentinel's lifetime
+ * (#6671).
+ *
+ * Windows reuses process ids quickly, so "is pid N still my parent" checked just before a kill
+ * cannot bind the kill to the proxy: the proxy may exit and its id be handed to another process in
+ * between. An open handle can: while any handle to a process object is open, its id is not
+ * reused, and `TerminateProcess` acts on exactly that object. The handle is opened once at
+ * startup and accepted only if the process it names was created before this sentinel, which a
+ * replacement holding a recycled id cannot satisfy. libuv's kill-on-close Job would otherwise be
+ * the only tie between the two processes, and libuv ignores a failed Job assignment.
+ *
+ * Bun exposes no API for a handle on a process it did not spawn, so this calls kernel32 through
+ * `bun:ffi`. Nothing here runs on other platforms.
+ */
+import { dlopen, FFIType } from "bun:ffi";
+
+const PROCESS_TERMINATE = 0x0001;
+const PROCESS_QUERY_LIMITED_INFORMATION = 0x1000;
+const SYNCHRONIZE = 0x0010_0000;
+const WAIT_OBJECT_0 = 0;
+const WAIT_TIMEOUT = 0x102;
+
+export type ParentProcessHandle = {
+  /** TerminateProcess on the held handle; true when Windows accepted the request. */
+  terminate(exitCode: number): boolean;
+  /** True once the process has exited (non-blocking). */
+  exited(): boolean;
+  close(): void;
+};
+
+export type ParentHandleResult =
+  | { ok: true; handle: ParentProcessHandle }
+  | { ok: false; reason: string };
+
+// HANDLEs travel as u64 (bigint), never as `ptr`: a JS number cannot carry every pointer-width
+// value, and a truncated handle would name a different object.
+function kernel32() {
+  return dlopen("kernel32.dll", {
+    OpenProcess: { args: [FFIType.u32, FFIType.i32, FFIType.u32], returns: FFIType.u64 },
+    GetProcessTimes: { args: [FFIType.u64, FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr], returns: FFIType.i32 },
+    TerminateProcess: { args: [FFIType.u64, FFIType.u32], returns: FFIType.i32 },
+    WaitForSingleObject: { args: [FFIType.u64, FFIType.u32], returns: FFIType.u32 },
+    CloseHandle: { args: [FFIType.u64], returns: FFIType.i32 },
+  }).symbols;
+}
+
+/** Open the parent and prove it is the process that created this one. */
+export function openParentProcessHandle(parentPid: number): ParentHandleResult {
+  if (process.platform !== "win32") return { ok: false, reason: "not Windows" };
+  let k32: ReturnType<typeof kernel32>;
+  try {
+    k32 = kernel32();
+  } catch {
+    return { ok: false, reason: "kernel32 is unavailable" };
+  }
+  const handle = BigInt(k32.OpenProcess(PROCESS_TERMINATE | PROCESS_QUERY_LIMITED_INFORMATION | SYNCHRONIZE, 0, parentPid));
+  if (handle === 0n) return { ok: false, reason: "the parent process cannot be opened" };
+  const close = () => { try { k32.CloseHandle(handle); } catch { /* already closed */ } };
+  const created = (target: bigint): bigint | null => {
+    const times = new BigUint64Array(4);
+    const ok = k32.GetProcessTimes(target, times.subarray(0, 1), times.subarray(1, 2), times.subarray(2, 3), times.subarray(3, 4));
+    return ok ? times[0]! : null;
+  };
+  // This process cannot be reused while it runs, so opening it by id is exact; the pseudo-handle
+  // from GetCurrentProcess is avoided because it is -1.
+  const self = BigInt(k32.OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, 0, process.pid));
+  const parentCreated = created(handle);
+  const selfCreated = self === 0n ? null : created(self);
+  if (self !== 0n) { try { k32.CloseHandle(self); } catch { /* already closed */ } }
+  if (parentCreated === null || selfCreated === null || parentCreated === 0n || parentCreated >= selfCreated) {
+    close();
+    return { ok: false, reason: "the process holding the parent id was not created before this sentinel" };
+  }
+  if (k32.WaitForSingleObject(handle, 0) !== WAIT_TIMEOUT) {
+    close();
+    return { ok: false, reason: "the parent process has already exited" };
+  }
+  return {
+    ok: true,
+    handle: {
+      terminate: exitCode => k32.TerminateProcess(handle, exitCode) !== 0,
+      exited: () => k32.WaitForSingleObject(handle, 0) === WAIT_OBJECT_0,
+      close,
+    },
+  };
+}

package/src/service/linux-linger.ts

@@ -0,0 +1,20 @@
+import { execFileSync } from "node:child_process";
+import { userInfo } from "node:os";
+
+interface LinuxLingerDeps {
+  user?: () => string;
+  run?: typeof execFileSync;
+}
+
+/** Advisory only: never enables linger or changes the user's login settings. */
+export function linuxServiceBootHint(deps: LinuxLingerDeps = {}): string {
+  try {
+    const user = (deps.user ?? (() => userInfo().username))();
+    const output = (deps.run ?? execFileSync)("loginctl", ["show-user", user, "-p", "Linger"], {
+      encoding: "utf8", timeout: 750, maxBuffer: 16 * 1024, stdio: ["ignore", "pipe", "pipe"],
+    }).trim();
+    if (output === "Linger=yes") return "   Auto-start on boot: user lingering is already enabled.";
+    if (output === "Linger=no") return "   For auto-start on boot: loginctl enable-linger $USER";
+  } catch { /* Missing loginctl or failed diagnosis is advisory, not an install failure. */ }
+  return "   User lingering could not be verified. For auto-start on boot, check it and, if disabled, run: loginctl enable-linger $USER";
+}

package/src/types/config.ts

@@ -519,6 +519,11 @@ export interface OcxConfig {
   skills?: OcxSkillsConfig;
   /** Opt-in process-local aggregate request metrics on the authenticated management plane. */
   metricsExport?: { enabled?: boolean };
+  /**
+   * Opt-in recovery of a managed service proxy that stays alive but stops answering /healthz:
+   * a separate sentinel process terminates it so its supervisor restarts it (#6671).
+   */
+  serviceHealthRecovery?: { enabled?: boolean };
   /** Opt in to one identical-turn retry when a Responses completion has no text or tool call. */
   emptyCompletionRetry?: boolean;
   /** Suppress allowlisted client-facing Codex transport hints; provider enforcement is unchanged. */

package/src/usage/expected-prices.ts

@@ -211,6 +211,8 @@ const META_MODEL_PRICING = "https://dev.meta.ai/docs/pricing-rate-limits";
  */
 const META_MUSE_SPARK_13: Cost4 = { input: 1.25, output: 4.25, cacheRead: 0.15, cacheWrite: 0 };
 const META_MUSE_SPARK_13_CONTRIBUTOR: Cost4 = { input: 0.1, output: 0.2, cacheRead: 0.002, cacheWrite: 0 };
+// Muse Wonder (muse-wonder-1.0): Standard mode only, no long-context premium (verified 2026-10-13).
+const META_MUSE_WONDER_10: Cost4 = { input: 4, output: 20, cacheRead: 0.2, cacheWrite: 0 };
 const META_SPARK_SOURCE = `Meta Model API published price ${META_MODEL_PRICING}`;
 const META_SPARK_CONTRIBUTOR_SOURCE = `Meta Model API published Contributor-tier price ${META_MODEL_PRICING}; data-sharing discount tier`;
 const DEEPSEEK_PRICING = "https://api-docs.deepseek.com/quick_start/pricing-details-usd; V4 Flash alias transition scheduled 2026-07-24 — re-verify after";
@@ -369,11 +371,13 @@ export const EXPECTED_PRICE_OVERLAYS: readonly ExpectedPriceOverlay[] = [
   // cacheWrite=0: Meta publishes a cached-input price but no cache-write charge.
   { provider: "meta-model", modelId: "muse-spark-1.3", cost4: META_MUSE_SPARK_13, source: META_SPARK_SOURCE, verifiedAt: "2026-09-03", status: "verified" },
   { provider: "meta-model", modelId: "muse-spark-1.3-contributor", cost4: META_MUSE_SPARK_13_CONTRIBUTOR, source: META_SPARK_CONTRIBUTOR_SOURCE, verifiedAt: "2026-09-03", status: "verified" },
+  { provider: "meta-model", modelId: "muse-wonder-1.0", cost4: META_MUSE_WONDER_10, source: META_SPARK_SOURCE, verifiedAt: "2026-10-13", status: "verified" },
   // Same endpoint, same list price, different credential. Meta does not authorize this
   // reuse and settlement is not observable, so these are the public Model API rates as a
   // conservative estimate — not evidence of how the call is actually billed.
   { provider: "meta-muse", modelId: "muse-spark-1.3", cost4: META_MUSE_SPARK_13, source: META_SPARK_SOURCE, verifiedAt: "2026-09-03", status: "verified-derived" },
   { provider: "meta-muse", modelId: "muse-spark-1.3-contributor", cost4: META_MUSE_SPARK_13_CONTRIBUTOR, source: META_SPARK_CONTRIBUTOR_SOURCE, verifiedAt: "2026-09-03", status: "verified-derived" },
+  { provider: "meta-muse", modelId: "muse-wonder-1.0", cost4: META_MUSE_WONDER_10, source: META_SPARK_SOURCE, verifiedAt: "2026-10-13", status: "verified-derived" },
   // Daybreak aliases: priced as their current snapshots (red -> gpt-5.6-cyber,
   // blue -> gpt-5.6-sol). The alias ids carry no rows of their own upstream, hence
   // verified-derived. Blue deliberately reuses GPT56_SOL rather than duplicating the tuple.

package/src/usage/log.ts

@@ -23,7 +23,7 @@ import { normalizeRouteDecisionTrace, type RouteDecisionTraceV1 } from "../routi
 import { parseProtocolTraceV1, type ProtocolTraceV1 } from "../protocols/dto";
 import { ACCOUNT_LOG_LABEL_RE, CODEX_ACCOUNT_LOG_LABEL_RE } from "../codex/account-label";
 import { claudeCompatibilityReason, normalizeClaudeFeatureCodes, type ClaudeFeatureCode } from "../claude/compatibility";
-import type { CodexWsStageRecord } from "../server/responses/codex-ws-wire";
+import type { CodexWsStageRecord, CodexWsTerminalEvent } from "../server/responses/codex-ws-wire";
 import {
   ATTEMPT_RECOVERY_KIND_ROSTER,
   ATTEMPT_RECOVERY_WITHHELD_ROSTER,
@@ -805,6 +805,15 @@ function normalizeUsageAttempt(raw: unknown): PersistedUsageAttempt | null {
  * injected free-form field — drops the whole record rather than passing
  * attacker text into the DTO.
  */
+// Total over the terminal union by `satisfies`; a type-only import keeps the WS transport out of
+// this module's runtime graph.
+const CODEX_WS_TERMINAL_EVENT_NAMES = {
+  "response.completed": true,
+  "response.failed": true,
+  "response.incomplete": true,
+  error: true,
+} as const satisfies Record<CodexWsTerminalEvent, true>;
+
 function normalizeCodexWsStageRecord(value: unknown): CodexWsStageRecord | undefined {
   if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
   const stage = value as Record<string, unknown>;
@@ -839,6 +848,15 @@ function normalizeCodexWsStageRecord(value: unknown): CodexWsStageRecord | undef
     reused: stage.reused,
     ocxVersion: stage.ocxVersion,
     bunVersion: stage.bunVersion,
+    // #6740 fields are newer than the record: absent or malformed values read as unobserved
+    // rather than costing the row the rest of its stage evidence.
+    terminalEvent: typeof stage.terminalEvent === "string" && Object.hasOwn(CODEX_WS_TERMINAL_EVENT_NAMES, stage.terminalEvent)
+      ? stage.terminalEvent as CodexWsTerminalEvent
+      : null,
+    terminalErrorStatus: typeof stage.terminalErrorStatus === "number" && Number.isInteger(stage.terminalErrorStatus)
+      && stage.terminalErrorStatus >= 100 && stage.terminalErrorStatus <= 599
+      ? stage.terminalErrorStatus
+      : null,
   };
 }