@bitkyc08/opencodex 2.48.0 → 2.50.0

package/src/server/responses/fetch-helpers.ts

@@ -74,13 +74,20 @@ export function providerFetch(
   const preconnect = (...args: Parameters<typeof globalThis.fetch.preconnect>): void => {
     base.preconnect?.(...args);
   };
+  // Rebuilt dispatches must use the same physical-send boundary as ordinary HTTP sends.
+  // Return the original 3xx so the response owner retains its retry/health/relay contract.
+  const dispatch = Object.assign(
+    (input: Parameters<typeof globalThis.fetch>[0], init?: RequestInit) =>
+      base(input, { ...init, redirect: "manual" }),
+    { preconnect },
+  ) as typeof globalThis.fetch;
   const httpFetch = Object.assign(
     async (input: Parameters<typeof globalThis.fetch>[0], init?: RequestInit) => {
       options.beforeDispatch?.(new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined)));
       const dispatchInit = { ...withUpstreamHttpVersion(input, init, provider), timeout: 0 };
       return options.dispatchOverride
-        ? options.dispatchOverride(input, dispatchInit, base)
-        : base(input, dispatchInit);
+        ? options.dispatchOverride(input, dispatchInit, dispatch)
+        : dispatch(input, dispatchInit);
     },
     { preconnect },
   ) as typeof globalThis.fetch;
@@ -163,6 +170,10 @@ export function storedPoolReplayDispatchNotifier(
   }) as ProviderFetch;
 }
 
+/**
+ * Fetch through the header deadline with redirects always manual.
+ * @param _manualRedirect Ignored; retained for call compatibility. Even false uses manual.
+ */
 export async function fetchWithHeaderTimeout(
   url: string,
   init: Omit<RequestInit, "signal">,
@@ -170,7 +181,8 @@ export async function fetchWithHeaderTimeout(
   timeoutMs: number,
   preferIdentityEncoding = false,
   executor: typeof globalThis.fetch = globalThis.fetch,
-  manualRedirect = false,
+  // Retained for existing callers; credential-bearing transport no longer opts out.
+  _manualRedirect = false,
 ): Promise<Response> {
   const pacing = executor as ProviderFetch;
   await pacing.waitForPacing?.(abortSignal);
@@ -189,10 +201,9 @@ export async function fetchWithHeaderTimeout(
     return await fetchExecutor(url, {
       ...init,
       headers,
-      // Credential-bearing sends opt into manual redirects so a 3xx is relayed
-      // as a Response instead of being followed into a rejection that is
-      // indistinguishable from a pre-connection failure (#914).
-      ...(manualRedirect ? { redirect: "manual" as const } : {}),
+      // Never replay provider credentials or request bodies to a redirect destination.
+      // Preserve the 3xx for the owner's existing response/health policy (#914, #1471).
+      redirect: "manual",
       signal: AbortSignal.any([abortSignal, timeout.signal]),
       timeout: 0,
     });

package/src/server/responses/policy-fallback.ts

@@ -1,11 +1,13 @@
 import { comboFailureDecision } from "../../combos/failover";
 import { readBoundedResponseBody } from "../../lib/bounded-body";
-import { readJsonRequestBody } from "../request-decompress";
+import { readJsonRequestBody, resolveInboundBodyLimitBytes } from "../request-decompress";
 import { finishRequestAttempt, type RequestLogContext } from "../request-log";
 import type { OcxConfig } from "../../types";
 import type { RouteCandidateTrace, RouteDecisionTraceV1 } from "../../routing/trace";
 import { handleResponses as handleResponsesCore } from "./core";
 import { requestPacingOverloadResponse } from "./pacing-overload";
+import { captureExplicitOpenAiCallerAuth } from "../../providers/openai-sidecar";
+import { captureCallerDirectAuth } from "../../providers/caller-authorization";
 
 type CoreHandler = typeof handleResponsesCore;
 type CoreOptions = Parameters<CoreHandler>[3];
@@ -47,6 +49,10 @@ function requestWithCandidate(
   candidate: Pick<RouteCandidateTrace, "provider" | "model">,
 ): Request {
   const headers = new Headers(req.headers);
+  // The next candidate owns a different physical credential domain. Typed
+  // admission and any claimed Claude snapshot stay in caller-owned CoreOptions.
+  headers.delete("authorization");
+  headers.delete("chatgpt-account-id");
   headers.delete("content-encoding");
   headers.delete("content-length");
   headers.set("content-type", "application/json");
@@ -119,6 +125,12 @@ export async function handleResponsesWithPolicyFallback(
   let storedPool401ReplayDispatched = false;
   const coreOptions: CoreOptions = {
     ...options,
+    openAiSidecarAuth: options.openAiSidecarAuth === undefined
+      ? captureExplicitOpenAiCallerAuth(req.headers, config) : options.openAiSidecarAuth,
+    nativeCallerAuth: options.nativeCallerAuth === undefined
+      ? captureExplicitOpenAiCallerAuth(req.headers, config) : options.nativeCallerAuth,
+    callerDirectAuth: options.callerDirectAuth === undefined
+      ? captureCallerDirectAuth(req.headers, config) : options.callerDirectAuth,
     ...(options.onRequestBodyRead ? {
       onRequestBodyRead: () => {
         if (requestBodyReadNotified) return;
@@ -133,7 +145,11 @@ export async function handleResponsesWithPolicyFallback(
   };
   let rawBody: Record<string, unknown> | null = null;
   try {
-    const parsed = await readJsonRequestBody(req.clone());
+    const parsed = await readJsonRequestBody(
+      req.clone(),
+      undefined,
+      resolveInboundBodyLimitBytes(config.maxInboundBodyBytes),
+    );
     if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) rawBody = parsed as Record<string, unknown>;
   } catch {
     // Core owns the client-facing parse/decompression error.

package/src/server/search.ts

@@ -33,7 +33,7 @@ import {
   type ExactOpenAiSidecarAccount,
 } from "../providers/openai-sidecar";
 import { routeModel } from "../router";
-import { readJsonRequestBody } from "./request-decompress";
+import { readJsonRequestBody, resolveInboundBodyLimitBytes } from "./request-decompress";
 import { ForwardAdmissionCredentialError, validateForwardAdmissionCredential } from "./auth-cors";
 import type { RequestLogContext } from "./request-log";
 import { codexLogAccountId, decodeRequestErrorResponse } from "./responses";
@@ -64,7 +64,7 @@ export async function handleSearch(
   }
   let body: unknown;
   try {
-    body = await readJsonRequestBody(req);
+    body = await readJsonRequestBody(req, undefined, resolveInboundBodyLimitBytes(config.maxInboundBodyBytes));
   } catch (err) {
     return decodeRequestErrorResponse(err, "search");
   }

package/src/service.ts

@@ -16,6 +16,13 @@ import { restoreNativeCodex, restoreNativeCodexAsync } from "./codex/inject";
 import { stripGrokConfig } from "./grok/inject";
 import { isWslRuntime, resolveCodexHomeDir, type CodexHomeDeps } from "./codex/home";
 import { BUN_RUNTIME_PATH_ENV, BUN_RUNTIME_SOURCE_ENV, durableBunRuntime } from "./lib/bun-runtime";
+
+/**
+ * Written only by the launchd plist and the systemd unit. `OCX_SERVICE=1` cannot stand in
+ * for it: `ocx claude` and `ocx opencode` set that on the proxies they spawn to borrow its
+ * routing-preservation meaning, so a proxy carrying it is not necessarily the managed job.
+ */
+export const SERVICE_MANAGED_ENV = "OCX_SERVICE_MANAGED";
 import type { BunRuntimeSource, DurableBunRuntime } from "./lib/bun-runtime";
 import { isProcessAlive, stopProxy } from "./lib/process-control";
 import { serviceApiTokenFilePath } from "./lib/service-secrets";
@@ -508,6 +515,11 @@ export function buildPlist(
   const opencodexHome = process.env.OPENCODEX_HOME?.trim();
   const envLines = [
     `    <key>OCX_SERVICE</key><string>1</string>`,
+    // OCX_SERVICE alone cannot identify the managed job: `ocx claude` and `ocx opencode`
+    // also set it on the proxies they spawn, to borrow its routing-preservation meaning
+    // (src/cli/index.ts preserveRouting). Only the wrapper writes this second marker, so
+    // the dashboard-stop refusal below can tell a real launchd job from an ordinary child.
+    `    <key>${SERVICE_MANAGED_ENV}</key><string>1</string>`,
     ...(launcher ? [] : [
       `    <key>${BUN_RUNTIME_SOURCE_ENV}</key><string>${bunRuntimeSource}</string>`,
       `    <key>${BUN_RUNTIME_PATH_ENV}</key><string>${plistString(bun)}</string>`,
@@ -853,9 +865,51 @@ export function resolvedProxyEnv(env: NodeJS.ProcessEnv = process.env): { name:
 }
 
 function sh(cmd: string): string {
+  assertLiveServiceManagerAllowed(cmd);
   return execSync(cmd, { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
 }
 
+/**
+ * Service-manager invocations that only observe. Everything else changes a job that
+ * launchd or the systemd user manager is running right now.
+ */
+const READ_ONLY_SERVICE_MANAGER = new RegExp(
+  "^(?:launchctl\\s+(?:list|print|print-disabled|blame|managerpid|manageruid)\\b"
+  + "|systemctl\\s+(?:--user\\s+)?(?:show|show-environment|status|is-active|is-enabled|is-failed|cat|list-units|list-unit-files|--version)\\b)",
+);
+
+const SERVICE_MANAGER_COMMAND = /^(?:launchctl|systemctl)\b/;
+
+/**
+ * Refuse to mutate a live service manager from an armed test process.
+ *
+ * The test preload isolates HOME, OPENCODEX_HOME and CODEX_HOME, and that is enough for
+ * anything addressed by path. It is not enough here. `systemctl --user stop
+ * opencodex-proxy.service` is addressed by job NAME and talks to the user manager that is
+ * already running, so it stops the proxy the developer is actually using no matter what
+ * HOME says. `launchctl bootout gui/<uid>/com.opencodex.proxy` has the same shape.
+ *
+ * Windows already had this guard: `querySchtasks` refuses every non-query call while the
+ * test-home guard is armed, after a partially-faked test replaced a real scheduled task
+ * with a launcher inside a temporary test home. macOS and Linux were left without the
+ * equivalent, which means the person most likely to run this suite - someone running
+ * opencodex on the machine they are developing it on - is the person it can disrupt.
+ *
+ * Read-only verbs stay allowed: probing what the manager reports is the whole point of
+ * the diagnostics, and observation cannot take a service down.
+ */
+export function assertLiveServiceManagerAllowed(command: string): void {
+  if (!isTestHomeGuardArmed()) return;
+  const trimmed = command.trim();
+  if (!SERVICE_MANAGER_COMMAND.test(trimmed)) return;
+  if (READ_ONLY_SERVICE_MANAGER.test(trimmed)) return;
+  throw new Error(
+    `refusing to run \`${trimmed}\` from an armed test process: launchd and the systemd user `
+    + "manager address a job by name, not by HOME, so this reaches the service the developer is "
+    + "actually running. Inject the service operation instead of calling the live manager.",
+  );
+}
+
 /**
  * Run `launchctl` and report BOTH streams regardless of exit status.
  *
@@ -875,6 +929,9 @@ export function runLaunchctl(
   deps: { run?: typeof spawnSync } = {},
 ): { ok: boolean; stdout: string; stderr: string; status: number | null } {
   const run = deps.run ?? spawnSync;
+  // Only the real runner is guarded. Tests that inject a spawnSync stand-in are
+  // exercising the parsing, not reaching launchd, and must keep working.
+  if (run === spawnSync) assertLiveServiceManagerAllowed(`launchctl ${args.join(" ")}`);
   const result = run("/bin/launchctl", args, { encoding: "utf8", windowsHide: true });
   // `error` is set when the spawn itself failed (ENOENT off macOS) and `status` is
   // null for a signalled child; neither may be reported as success.
@@ -2281,7 +2338,23 @@ export function readWindowsSchedulerXmlState(
 }
 
 // ── macOS (launchd) ──
-function installLaunchd(): void {
+/**
+ * Deps follow {@link startLaunchd}: `launchctl` replaces the LAYER, returning a
+ * {@link runLaunchctl} result, not a spawnSync result. It is optional so this stays
+ * assignable to `ServiceOps.install` and `RepairServiceDeps.repairLaunchd`
+ * (`() => void`), and so `platformOps` wires the same function the tests exercise.
+ *
+ * The seam is what makes the eviction below testable at all. The live-service-manager
+ * guard refuses every mutating verb from an armed test process and `bootout` is not on
+ * its read-only list, so a test reaching the real runner would fail closed on the guard
+ * instead of exercising the sequence.
+ *
+ * No `matches` dep: unlike `startLaunchd`, this function never consults
+ * {@link launchdJobMatchesPlist}. It has just rewritten the plist, so a live job is stale
+ * by construction and there is nothing to compare against.
+ */
+export function installLaunchd(deps: { launchctl?: typeof runLaunchctl } = {}): void {
+  const run = deps.launchctl ?? runLaunchctl;
   const dir = join(homedir(), "Library", "LaunchAgents");
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
   recordOwnedConfigPath(getConfigDir(), serviceStatePath());
@@ -2295,17 +2368,41 @@ function installLaunchd(): void {
   // so the staleness diagnostic judges exactly what launchd runs.
   const launcher = stableLauncherEntry();
   writeServiceDefinitionFile(p, buildPlist(resolvedProxyEnv(), { launcher }), "utf8");
-  // Best-effort: an absent job is fine here, and a failed unload is caught by the
-  // load verification below with a better message than a raw unload error.
-  runLaunchctl(["unload", p]);
-  const loaded = runLaunchctl(["load", "-w", p]);
+  // `unload` is the legacy verb and it does not evict a job bootstrapped into the GUI
+  // domain — which is precisely the state that could not repair itself. Modern launchd
+  // answers `load -w` for an already-bootstrapped job with "Load failed: 5:
+  // Input/output error" AND exits 0, so `ocx update` replaced the binary, ran repair,
+  // and left launchd running the PREVIOUS job while the fresh plist sat unused (#4141).
+  //
+  // This EVICTS the running job. That is the repair being asked for, and it is why it
+  // lives here and nowhere else: `installLaunchd` has already rewritten the plist, so
+  // whatever is loaded is stale by construction. `ocx service start` must never do
+  // this, and `startLaunchd` accordingly still refuses to.
+  //
+  // Absence is fine: booting out a job that is not there is a no-op, and a real failure
+  // is reported by the load verification below with a better message than a raw
+  // eviction error would carry.
+  const bootoutTarget = `${launchdGuiDomain()}/${LABEL}`;
+  run(["bootout", bootoutTarget]);
+  let loaded = run(["load", "-w", p]);
+  if (launchctlLoadFailed(loaded.stderr)) {
+    // Still bootstrapped after an eviction: the job re-registered between the two calls,
+    // or the first `bootout` raced a job that had not finished exiting. Evict and load
+    // once more — ONCE. A bounded retry recovers the race; a loop would turn a genuinely
+    // wedged domain into a hang instead of the diagnosable throw below.
+    run(["bootout", bootoutTarget]);
+    loaded = run(["load", "-w", p]);
+  }
   if (!loaded.ok || launchctlLoadFailed(loaded.stderr)) {
     // Do NOT write install state for a load that did not take: state describing an
     // unused plist is what made this failure invisible.
     throw new Error(
       `launchctl could not load ${p}: ${loaded.stderr || "load reported failure"}\n`
-      + "A previous job may still be bootstrapped. Try:\n"
-      + `  launchctl bootout ${launchdGuiDomain()}/${LABEL}\n`
+      // The hint used to tell the operator to run `bootout` by hand. It now runs twice
+      // above, so naming it as an untried remedy would send someone to repeat what just
+      // failed. Report what was attempted instead.
+      + `A previous job is still bootstrapped after two attempts to boot it out of ${launchdGuiDomain()}.\n`
+      + `Inspect it with:\n  launchctl print ${bootoutTarget}\n`
       // macOS `service repair` delegates straight to installLaunchd, so this fires for
       // an already-installed service too; repair reloads it without re-registering.
       + `then re-run '${wasInstalled ? "ocx service repair" : "ocx service install"}'.`,
@@ -3328,6 +3425,7 @@ export function buildUnit(
   const opencodexHome = systemdEnvironmentAssignment("OPENCODEX_HOME", process.env.OPENCODEX_HOME?.trim());
   const envLines = [
     systemdEnvironmentAssignment("OCX_SERVICE", "1"),
+    systemdEnvironmentAssignment(SERVICE_MANAGED_ENV, "1"),
     ...(launcher ? [] : [
       systemdEnvironmentAssignment(BUN_RUNTIME_SOURCE_ENV, bunRuntimeSource),
       systemdEnvironmentAssignment(BUN_RUNTIME_PATH_ENV, bun),
@@ -3860,10 +3958,31 @@ export async function installFreshWindowsSchedulerSafely(
 export function installedServiceRespawnRisk(
   probe: () => WindowsSchedulerTaskProbe = probeWindowsSchedulerTask,
   platform: NodeJS.Platform = process.platform,
-): "none" | "respawnable" | "unknown" {
+  io: { env?: NodeJS.ProcessEnv; exists?: (path: string) => boolean } = {},
+): "none" | "respawnable" | "unknown" | "self-unload" {
   // launchd, systemd and WinSW are down when they report stopped; only the Task Scheduler
   // wrapper survives its task ending (#764).
-  if (platform !== "win32") return "none";
+  //
+  // "Down when they report stopped" answers the RESPAWN question but not the SELF-UNLOAD
+  // one (#4023). When the proxy is itself the managed job, `launchctl unload` /
+  // `systemctl stop` terminate this very process, so the manager stop can kill the request
+  // handler before the shared teardown restores the native Codex config keys — leaving
+  // `openai_base_url`, `experimental_realtime_ws_base_url` and `model_catalog_json`
+  // pointed at a proxy that is gone. Reordering teardown ahead of the manager stop is not
+  // available here: the #3008 contract requires the manager to be proven stopped first.
+  // So refuse, exactly as Windows does, and send the operator to `ocx stop`, which stops
+  // the proxy from the outside and owns the teardown through its receipt.
+  if (platform !== "win32") {
+    const env = io.env ?? process.env;
+    // Discriminate on the wrapper-only marker, not on OCX_SERVICE: `ocx claude` and
+    // `ocx opencode` set OCX_SERVICE=1 on the proxies they spawn (for preserveRouting),
+    // and refusing their dashboard stop would break a proxy that no manager supervises.
+    if (env[SERVICE_MANAGED_ENV] !== "1") return "none";
+    const exists = io.exists ?? existsSync;
+    if (platform === "darwin") return exists(plistPath()) ? "self-unload" : "none";
+    if (platform === "linux") return exists(unitPath()) ? "self-unload" : "none";
+    return "none";
+  }
   try {
     // `probeWindowsSchedulerTask` returns "unknown" as an ordinary value when its queries
     // fail — it does not throw — so testing for "present" let an unanswerable probe

package/src/storage/cleanup.ts

@@ -96,6 +96,7 @@ export interface CleanupResult {
   trashDir?: string;
   error?: CleanupErrorCode;
   removedPaths: string[];
+  skippedReferencedPaths?: string[];
 }
 
 const STATE_DB_FILE = /^state_(\d+)\.sqlite$/;
@@ -684,52 +685,59 @@ function loadMatchingThreads(db: Database, candidates: ArchivedCandidate[], code
 }
 
 /**
- * True when any matched thread is still linked to a thread outside the delete set
- * (spawn edges) or uses paginated history that other live threads may depend on via fork.
- * Throws real DB errors (busy/corruption) so callers can refuse cleanup.
+ * Partition matched threads into deletable and referenced snapshots. Linked spawn/fork
+ * history and paginated histories stay in the skipped set. Throws real DB errors.
  */
-function findReferencedHistory(
+function filterReferencedHistory(
   db: Database,
   threads: ThreadSnapshot[],
-): boolean {
-  if (threads.length === 0) return false;
-  const ids = threads.map(t => t.id);
-  const idSet = new Set(ids);
-
-  // Paginated history keeps durable projections tied to the rollout — refuse cleanup.
-  if (threads.some(t => (t.history_mode ?? "").toLowerCase() === "paginated")) {
-    return true;
-  }
-
-  // Spawn edges that cross the delete boundary keep history reachable.
-  if (tableExists(db, "thread_spawn_edges")) {
-    for (const chunk of chunkIds(ids, SQLITE_ID_CHUNK)) {
+): { safe: ThreadSnapshot[]; skipped: ThreadSnapshot[] } {
+  let safe = threads.filter(t => (t.history_mode ?? "").toLowerCase() !== "paginated");
+  const skipped = new Map(threads
+    .filter(t => (t.history_mode ?? "").toLowerCase() === "paginated")
+    .map(t => [t.id, t]));
+
+  while (safe.length > 0) {
+    const idSet = new Set(safe.map(t => t.id));
+    const unsafeIds = new Set<string>();
+
+    // Spawn edges that cross the delete boundary keep history reachable.
+    if (tableExists(db, "thread_spawn_edges")) {
+      for (const chunk of chunkIds([...idSet], SQLITE_ID_CHUNK)) {
       const placeholders = chunk.map(() => "?").join(",");
       const edges = db.query<{ parent_thread_id: string; child_thread_id: string }, string[]>(
         `SELECT parent_thread_id, child_thread_id FROM thread_spawn_edges
          WHERE parent_thread_id IN (${placeholders}) OR child_thread_id IN (${placeholders})`,
       ).all(...chunk, ...chunk);
       for (const edge of edges) {
-        if (!idSet.has(edge.parent_thread_id) || !idSet.has(edge.child_thread_id)) {
-          return true;
+        if (!idSet.has(edge.parent_thread_id)) unsafeIds.add(edge.child_thread_id);
+        if (!idSet.has(edge.child_thread_id)) unsafeIds.add(edge.parent_thread_id);
+      }
+    }
+    }
+
+    // Other threads that list one of ours as forked_from / parent (when columns exist).
+    for (const column of ["forked_from_id", "parent_thread_id", "source_thread_id"] as const) {
+      if (!columnExists(db, "threads", column)) continue;
+      for (const chunk of chunkIds([...idSet], SQLITE_ID_CHUNK * 2)) {
+        const placeholders = chunk.map(() => "?").join(",");
+        const rows = db.query<{ id: string; ref: string }, string[]>(
+          `SELECT id, ${column} AS ref FROM threads WHERE ${column} IN (${placeholders})`,
+        ).all(...chunk);
+        for (const row of rows) {
+          if (!idSet.has(row.id)) unsafeIds.add(row.ref);
         }
       }
     }
-  }
 
-  // Other threads that list one of ours as forked_from / parent (when columns exist).
-  for (const column of ["forked_from_id", "parent_thread_id", "source_thread_id"] as const) {
-    if (!columnExists(db, "threads", column)) continue;
-    for (const chunk of chunkIds(ids, SQLITE_ID_CHUNK * 2)) {
-      const placeholders = chunk.map(() => "?").join(",");
-      const rows = db.query<{ id: string }, string[]>(
-        `SELECT id FROM threads WHERE ${column} IN (${placeholders})`,
-      ).all(...chunk);
-      if (rows.some(r => !idSet.has(r.id))) return true;
+    if (unsafeIds.size === 0) break;
+    for (const thread of safe) {
+      if (unsafeIds.has(thread.id)) skipped.set(thread.id, thread);
     }
+    safe = safe.filter(thread => !unsafeIds.has(thread.id));
   }
 
-  return false;
+  return { safe, skipped: [...skipped.values()] };
 }
 
 function tableExists(db: Database, name: string): boolean {
@@ -778,6 +786,7 @@ function deleteThreadsAndDependents(db: Database, threadIds: string[]): void {
 interface ReconcileOk {
   ok: true;
   threads: ThreadSnapshot[];
+  skipped: ThreadSnapshot[];
 }
 interface ReconcileErr {
   ok: false;
@@ -1463,14 +1472,14 @@ function withWritableDb(
   }
 }
 
-/** Load matching archived threads and refuse referenced history — no deletes yet. */
+/** Load matching archived threads and retain referenced history — no deletes yet. */
 function loadThreadsForCleanup(
   stateDbPath: string,
   candidates: ArchivedCandidate[],
   codexHome: string,
   busyTimeoutMs: number,
 ): ReconcileOk | ReconcileErr {
-  if (!stateDbPath || !existsSync(stateDbPath)) return { ok: true, threads: [] };
+  if (!stateDbPath || !existsSync(stateDbPath)) return { ok: true, threads: [], skipped: [] };
   let db: Database | undefined;
   try {
     db = openDbWritable(stateDbPath, busyTimeoutMs);
@@ -1478,10 +1487,8 @@ function loadThreadsForCleanup(
     if (threads.some(t => Number(t.is_pinned ?? 0) === 1)) {
       return { ok: false, error: "pinned_thread" };
     }
-    if (findReferencedHistory(db, threads)) {
-      return { ok: false, error: "referenced_history" };
-    }
-    return { ok: true, threads };
+    const filtered = filterReferencedHistory(db, threads);
+    return { ok: true, threads: filtered.safe, skipped: filtered.skipped };
   } catch (error) {
     return { ok: false, error: mapDbError(error) };
   } finally {
@@ -1504,7 +1511,7 @@ function reconcileDeletedThreads(
   stageDir: string,
   hooks?: ReconcileTestHooks,
 ): ReconcileOk | ReconcileErr {
-  if (!paths.state || !existsSync(paths.state)) return { ok: true, threads: [] };
+  if (!paths.state || !existsSync(paths.state)) return { ok: true, threads: [], skipped: [] };
 
   if (hooks?.beforeReconcileLock) hooks.beforeReconcileLock();
 
@@ -1546,7 +1553,7 @@ function reconcileDeletedThreads(
       stateDb.exec("ROLLBACK");
       return { ok: false, error: "pinned_thread" };
     }
-    if (findReferencedHistory(stateDb, threads)) {
+    if (filterReferencedHistory(stateDb, threads).safe.length !== threads.length) {
       stateDb.exec("ROLLBACK");
       return { ok: false, error: "referenced_history" };
     }
@@ -1582,7 +1589,7 @@ function reconcileDeletedThreads(
       if (hooks?.afterSatelliteMutations) hooks.afterSatelliteMutations();
 
       // Re-check under the same lock before committing state deletes.
-      if (findReferencedHistory(stateDb, threads)) {
+      if (filterReferencedHistory(stateDb, threads).safe.length !== threads.length) {
         stateDb.exec("ROLLBACK");
         return failWithRestore("referenced_history");
       }
@@ -1590,7 +1597,7 @@ function reconcileDeletedThreads(
       if (hooks?.failBeforeStateCommit) throw new Error("test_fail_before_state_commit");
       stateDb.exec("COMMIT");
       // Keep satellite-backup.json for quarantine restore; permanent purge removes the stage.
-      return { ok: true, threads };
+      return { ok: true, threads, skipped: [] };
     } catch (error) {
       if (satelliteLocks) rollbackAllSatelliteLocks(satelliteLocks);
       throw error;
@@ -1895,7 +1902,30 @@ export function executeArchivedCleanup(options: ExecuteCleanupOptions): CleanupR
     const normalized = normalizeArchivedRolloutPath(thread.rollout_path, codexHome);
     if (normalized) threadByRelPath.set(normalized, thread);
   }
-  const manifestEntries: CleanupManifestEntry[] = preview.candidates.map(candidate => {
+  const skippedReferencedPaths = loaded.skipped
+    .map(thread => normalizeArchivedRolloutPath(thread.rollout_path, codexHome))
+    .filter((path): path is string => path !== null);
+  const matchedPaths = new Set([
+    ...threadByRelPath.keys(),
+    ...skippedReferencedPaths,
+  ]);
+  const candidates = preview.candidates.filter(candidate => {
+    return !matchedPaths.has(candidate.relPath) || threadByRelPath.has(candidate.relPath);
+  });
+  if (candidates.length === 0) {
+    removeStageIfEmpty(stageDir, []);
+    removeEmptyTrashRoot(codexHome);
+    return {
+      ok: true,
+      mode,
+      percent,
+      count: 0,
+      bytes: 0,
+      removedPaths: [],
+      ...(skippedReferencedPaths.length ? { skippedReferencedPaths } : {}),
+    };
+  }
+  const manifestEntries: CleanupManifestEntry[] = candidates.map(candidate => {
     const thread = threadByRelPath.get(candidate.relPath);
     return {
       relPath: candidate.relPath,
@@ -1936,7 +1966,7 @@ export function executeArchivedCleanup(options: ExecuteCleanupOptions): CleanupR
     return fail(mode, percent, "fs_failed");
   }
 
-  const stageResult = stageCandidates(codexHome, preview.candidates, stageDir, {
+  const stageResult = stageCandidates(codexHome, candidates, stageDir, {
     blockDestBasenames: blockStageDest.size > 0 ? blockStageDest : undefined,
   });
   if (!stageResult.ok) {
@@ -1956,7 +1986,7 @@ export function executeArchivedCleanup(options: ExecuteCleanupOptions): CleanupR
 
   const deleted = reconcileDeletedThreads(
     paths,
-    preview.candidates,
+    candidates,
     codexHome,
     busyTimeoutMs,
     stageDir,
@@ -1973,8 +2003,8 @@ export function executeArchivedCleanup(options: ExecuteCleanupOptions): CleanupR
     return fail(mode, percent, deleted.error, keepTrash ? { trashDir } : undefined);
   }
 
-  const removedPaths = preview.candidates.map(c => c.relPath);
-  const bytes = preview.candidates.reduce((sum, c) => sum + c.bytes, 0);
+  const removedPaths = candidates.map(c => c.relPath);
+  const bytes = candidates.reduce((sum, c) => sum + c.bytes, 0);
 
   if (mode === "quarantine") {
     return {
@@ -1985,6 +2015,7 @@ export function executeArchivedCleanup(options: ExecuteCleanupOptions): CleanupR
       bytes,
       trashDir,
       removedPaths,
+      ...(skippedReferencedPaths.length ? { skippedReferencedPaths } : {}),
     };
   }
 
@@ -2038,6 +2069,7 @@ export function executeArchivedCleanup(options: ExecuteCleanupOptions): CleanupR
     count: removedPaths.length,
     bytes,
     removedPaths,
+    ...(skippedReferencedPaths.length ? { skippedReferencedPaths } : {}),
   };
 }
 

package/src/types/accounts.ts

@@ -34,4 +34,22 @@ export interface CodexAccountCredentialRecord {
   lastCodexValidatedAt?: number;
   lastCodexValidationStatus?: "ok" | "failed";
   lastCodexValidationError?: string;
+  /** OAuth succeeded while quota was exhausted; never route until deferred validation succeeds. */
+  codexValidationPending?: boolean;
+  /**
+   * Set when the recorded failure is TERMINAL: the OAuth grant itself was revoked or has
+   * expired, so no retry can recover it and only a re-login will. It distinguishes a dead
+   * credential from a transient warmup or probe failure that may clear on its own.
+   *
+   * Deliberately a separate optional key rather than a third value in
+   * `lastCodexValidationStatus`: `isCredentialRecord` admits only `"ok" | "failed"`, so a
+   * record carrying an unrecognized status fails validation and is DROPPED from the store
+   * on load. An unknown extra key is carried through untouched instead, which keeps a
+   * downgrade from deleting the account entry and its credential.
+   *
+   * Cleared by `markCodexAccountValidated` and — because it is absent from
+   * `preservedValidationMetadata` — by every credential write. A refresh that succeeds
+   * disproves "the grant was revoked", so the verdict must not outlive it.
+   */
+  lastCodexValidationTerminal?: boolean;
 }