@iislee/opencodex 2.31.0 → 2.35.0

package/src/images/loop.ts

@@ -258,10 +258,11 @@ export interface ImageBridgeDeps {
   /** Raw adapter usage at the terminal event, pre wire-normalization (see bridgeToResponsesSSE onUsage). */
   onUsage?: (usage: OcxUsage | undefined) => void;
   /**
-   * Optional 429 key-failover for the routed (non-xAI) model. Return a rebuilt adapter for the
-   * rotated key, or null when the pool is exhausted.
+   * Optional 429 failover for the routed (non-xAI) model. Return a rebuilt adapter for the
+   * rotated credential, or null when the pool is exhausted. Async hooks support OAuth refresh;
+   * existing synchronous key-pool hooks remain valid.
    */
-  on429?: (retryAfterHeader: string | null) => ProviderAdapter | null;
+  on429?: (retryAfterHeader: string | null) => ProviderAdapter | null | Promise<ProviderAdapter | null>;
   /** Opt-in same-target 429 policy (key-auth providers). When present, 429 replays on the SAME key before on429 rotation. */
   retryOn429Policy?: Required<RateLimitRetryPolicy> | null;
   /** Called when the bridged Responses stream completes (parity with runTurn / routed paths). */
@@ -572,7 +573,7 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
       }
       // 429 key-failover parity with web-search / normal routed path.
       while (prepared.response.status === 429 && deps.on429) {
-        const rotated = deps.on429(prepared.response.headers.get("retry-after"));
+        const rotated = await deps.on429(prepared.response.headers.get("retry-after"));
         if (!rotated) break;
         try { void prepared.response.body?.cancel().catch(() => {}); } catch { /* already closed */ }
         adapter = rotated;

package/src/images/plan.ts

@@ -48,11 +48,12 @@ export async function planImageBridge(
   if (config.images?.bridgeEnabled !== true) return undefined;
   if (!parsed._imageGeneration) return undefined;
   const toolAllowed = toolChoiceToolPredicate(parsed.options.toolChoice);
-  const toolNames = new Set(
-    [...parsed._imageGeneration.toolNames, IMAGE_GEN_TOOL_NAME]
-      .filter(name => toolAllowed({ name })),
-  );
+  const toolNames = new Set([...parsed._imageGeneration.toolNames].filter(name => toolAllowed({ name })));
+  if (toolAllowed({ name: IMAGE_GEN_TOOL_NAME })) toolNames.add(IMAGE_GEN_TOOL_NAME);
   if (toolNames.size === 0) return undefined;
+  // Responses advertises and rewrites authorized aliases to this synthetic name, so the loop
+  // must always intercept it once any image-generation name has armed the bridge.
+  toolNames.add(IMAGE_GEN_TOOL_NAME);
   // Don't intercept for OpenAI native passthrough
   const host = (() => { try { return new URL(routedProvider.baseUrl).hostname; } catch { return ""; } })();
   if (host === "api.openai.com") return undefined;

package/src/integrations/ownership-policy.ts

@@ -0,0 +1,160 @@
+/**
+ * Client-scoped exceptions to strict managed-fragment ownership.
+ *
+ * Most clients must preserve every byte represented by their managed
+ * contribution. A client that persists runtime-derived fields back into an
+ * OpenCodex-owned fragment needs a narrower contract: name the exact paths it
+ * may rewrite, then fingerprint everything else. Keeping that policy here
+ * prevents a client quirk from weakening the shared classifier.
+ */
+import {
+  OPENCODE_PROVIDER_ID,
+  type ManagedContribution,
+  type ManagedFragment,
+} from "../clients/config-export";
+import { canonicalContribution, fingerprint, semanticContribution } from "./ownership";
+
+type JsonObject = Record<string, unknown>;
+
+function isObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function pathStartsWith(path: readonly string[], prefix: readonly string[]): boolean {
+  return prefix.length <= path.length && prefix.every((part, index) => path[index] === part);
+}
+
+/** Delete one nested object member and prune only the empty ancestors created by that deletion. */
+function deletePath(root: unknown, path: readonly string[]): void {
+  if (!isObject(root) || path.length === 0) return;
+  const parents: Array<{ parent: JsonObject; key: string }> = [];
+  let cursor: JsonObject = root;
+  for (let index = 0; index < path.length - 1; index += 1) {
+    const key = path[index]!;
+    const next = cursor[key];
+    if (!isObject(next)) return;
+    parents.push({ parent: cursor, key });
+    cursor = next;
+  }
+  delete cursor[path[path.length - 1]!];
+  for (let index = parents.length - 1; index >= 0; index -= 1) {
+    if (Object.keys(cursor).length > 0) break;
+    const { parent, key } = parents[index]!;
+    delete parent[key];
+    cursor = parent;
+  }
+}
+
+function cloneFragment(fragment: ManagedFragment): ManagedFragment {
+  return {
+    path: [...fragment.path],
+    value: structuredClone(fragment.value),
+  };
+}
+
+/**
+ * Paths a client is documented to derive after OpenCodex writes its block.
+ *
+ * ZCode 3.8.1 persists reasoning and output defaults for every generated
+ * model. It may also fill a context default when OpenCodex intentionally
+ * omitted one; an authoritative context emitted by OpenCodex remains
+ * protected and is never listed here.
+ */
+export function refreshablePathsOf(
+  contribution: ManagedContribution,
+): readonly (readonly string[])[] {
+  if (contribution.clientId !== "zcode") return [];
+  const fragment = contribution.fragments.find(candidate => (
+    candidate.path.length === 2
+    && candidate.path[0] === "provider"
+    && candidate.path[1] === OPENCODE_PROVIDER_ID
+  ));
+  if (!fragment || !isObject(fragment.value) || !isObject(fragment.value.models)) return [];
+
+  const paths: string[][] = [];
+  for (const modelId of Object.keys(fragment.value.models).sort()) {
+    const entry = fragment.value.models[modelId];
+    if (!isObject(entry)) continue;
+    const base = [...fragment.path, "models", modelId];
+    paths.push([...base, "reasoning"]);
+    paths.push([...base, "limit", "output"]);
+    const limit = entry.limit;
+    if (!isObject(limit) || typeof limit.context !== "number") {
+      paths.push([...base, "limit", "context"]);
+    }
+  }
+  return paths;
+}
+
+export function validRefreshablePaths(
+  contribution: ManagedContribution,
+  value: unknown,
+): value is readonly (readonly string[])[] {
+  if (contribution.clientId !== "zcode" || !Array.isArray(value) || value.length === 0) {
+    return false;
+  }
+  const fragment = contribution.fragments.find(candidate => (
+    candidate.path.length === 2
+    && candidate.path[0] === "provider"
+    && candidate.path[1] === OPENCODE_PROVIDER_ID
+  ));
+  if (!fragment || !isObject(fragment.value) || !isObject(fragment.value.models)) return false;
+
+  const modelIds = new Set(Object.keys(fragment.value.models));
+  const seen = new Set<string>();
+  return value.every(path => {
+    if (!Array.isArray(path) || !path.every(part => typeof part === "string")) return false;
+    const modelId = path[3];
+    const isReasoning = path.length === 5 && path[4] === "reasoning";
+    const isLimitDefault = path.length === 6
+      && path[4] === "limit"
+      && (path[5] === "output" || path[5] === "context");
+    const key = path.join("\u0000");
+    if (
+      path[0] !== "provider"
+      || path[1] !== OPENCODE_PROVIDER_ID
+      || path[2] !== "models"
+      || typeof modelId !== "string"
+      || !modelIds.has(modelId)
+      || (!isReasoning && !isLimitDefault)
+      || seen.has(key)
+    ) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function contributionWithoutRefreshablePaths(
+  contribution: ManagedContribution,
+  refreshablePaths: readonly (readonly string[])[],
+): ManagedContribution {
+  const fragments = contribution.fragments.map(cloneFragment);
+  for (const refreshablePath of refreshablePaths) {
+    for (const fragment of fragments) {
+      if (!pathStartsWith(refreshablePath, fragment.path)) continue;
+      deletePath(fragment.value, refreshablePath.slice(fragment.path.length));
+      break;
+    }
+  }
+  return { ...contribution, fragments };
+}
+
+/** Fingerprint a contribution after removing only its explicitly refreshable paths. */
+export function protectedContributionFingerprint(
+  contribution: ManagedContribution,
+  refreshablePaths: readonly (readonly string[])[],
+): string {
+  return fingerprint(canonicalContribution(
+    contributionWithoutRefreshablePaths(contribution, refreshablePaths),
+  ));
+}
+
+/** Semantic protected fingerprint that ignores JSON object-key order only. */
+export function semanticProtectedContributionFingerprint(
+  contribution: ManagedContribution,
+  refreshablePaths: readonly (readonly string[])[],
+): string {
+  return fingerprint(semanticContribution(
+    contributionWithoutRefreshablePaths(contribution, refreshablePaths),
+  ));
+}

package/src/integrations/ownership.ts

@@ -22,8 +22,38 @@ export function fingerprint(text: string): string {
 }
 
 /**
- * Canonical bytes of a contribution. Fragments are sorted by path so two builds
- * of the same contribution hash identically regardless of emission order.
+ * Canonicalize JSON object members recursively for semantic comparisons.
+ * Arrays stay ordered because their position can carry configuration meaning.
+ */
+function semanticJsonValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(semanticJsonValue);
+  if (value === null || typeof value !== "object") return value;
+
+  const record = value as Record<string, unknown>;
+  return Object.fromEntries(
+    Object.keys(record)
+      .sort()
+      .map(key => [key, semanticJsonValue(record[key])]),
+  );
+}
+
+/**
+ * Stable semantic bytes of a contribution. Third-party clients may
+ * re-serialize JSON object members in a different order; that formatting-only
+ * rewrite must not look like a protected-value edit.
+ */
+export function semanticContribution(contribution: ManagedContribution): string {
+  const sorted = [...contribution.fragments].sort((a, b) => {
+    const left = a.path.join("\u0000");
+    const right = b.path.join("\u0000");
+    return left < right ? -1 : left > right ? 1 : 0;
+  });
+  return JSON.stringify(sorted.map(fragment => [fragment.path, semanticJsonValue(fragment.value)]));
+}
+
+/**
+ * Legacy-compatible bytes used by existing persisted fingerprints. Fragment
+ * paths are stable, while nested object insertion order remains exact.
  */
 export function canonicalContribution(contribution: ManagedContribution): string {
   const sorted = [...contribution.fragments].sort((a, b) => {
@@ -41,6 +71,20 @@ export interface OwnershipRecord {
   fileFingerprint: string;
   /** Hash of our contribution — detects catalog/port drift. */
   blockFingerprint: string;
+  /** Key-order-independent companion for JSON clients that normalize objects. */
+  semanticBlockFingerprint?: string;
+  /**
+   * Hash of the fields the client must not rewrite. Present only when a
+   * client has explicitly declared runtime-derived paths below.
+   */
+  protectedBlockFingerprint?: string;
+  /** Key-order-independent companion to `protectedBlockFingerprint`. */
+  semanticProtectedBlockFingerprint?: string;
+  /**
+   * Exact document paths a client may derive after apply. These are recorded
+   * per operation so later catalog changes cannot widen an older grant.
+   */
+  refreshablePaths?: readonly (readonly string[])[];
   /** The exact paths we own. Removal touches these and nothing else. */
   fragmentPaths: readonly (readonly string[])[];
   /**

package/src/integrations/registry.ts

@@ -12,6 +12,8 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import {
   EXPORT_CLIENTS,
+  clineConfigPath,
+  clineHomeDir,
   dshConfigPath,
   dshHomeDir,
   gajaeConfigPath,
@@ -149,6 +151,11 @@ export const INTEGRATION_CLIENTS: Record<IntegrationClientId, IntegrationClientS
     // is set. Same choice as OMP, whose detect signal is `ompAgentDir`.
     detectDir: (env = process.env, home = homedir()) => primeAgentDir(env, home),
   },
+  cline: {
+    id: "cline",
+    configPath: (env = process.env, home = homedir()) => clineConfigPath(env, home),
+    detectDir: (env = process.env, home = homedir()) => clineHomeDir(env, home),
+  },
 };
 
 export const INTEGRATION_CLIENT_IDS: readonly IntegrationClientId[] =

package/src/integrations/state.ts

@@ -12,7 +12,13 @@ import { ClientPathError, EXPORT_CLIENTS, opencodeProxyBaseUrl, type ExportModel
 import type { OcxConfig } from "../types";
 import { PARSE_FAILED, loadTarget, parseConfig, type IntegrationIO } from "./config-io";
 import { SNAPSHOT_RETENTION } from "./journal";
-import { canonicalContribution, fingerprint, type OwnershipRecord } from "./ownership";
+import { canonicalContribution, fingerprint, semanticContribution, type OwnershipRecord } from "./ownership";
+import {
+  protectedContributionFingerprint,
+  refreshablePathsOf,
+  semanticProtectedContributionFingerprint,
+  validRefreshablePaths,
+} from "./ownership-policy";
 import { INTEGRATION_CLIENTS, type IntegrationClientId } from "./registry";
 import { createIntegrationStateStore, type IntegrationStateStore } from "./store";
 
@@ -106,10 +112,10 @@ export function blockedContainerPath(
  * values lets another integration or a user add a sibling without blocking a
  * later refresh, while a change inside our block still fails closed.
  */
-function recordedFragmentFingerprint(
+function recordedContribution(
   doc: unknown,
   record: OwnershipRecord,
-): string | null {
+): ManagedContribution | null {
   if (
     !Array.isArray(record.fragmentPaths)
     || record.fragmentPaths.length === 0
@@ -125,10 +131,72 @@ function recordedFragmentFingerprint(
     if (value === undefined) return null;
     fragments.push({ path, value });
   }
-  return fingerprint(canonicalContribution({
+  return {
     clientId: record.clientId,
     fragments,
-  }));
+  };
+}
+
+/**
+ * Prove that every protected field still matches what OpenCodex wrote.
+ *
+ * New records carry an operation-scoped protected fingerprint and the exact
+ * paths excluded from it. Legacy records can recover only when the desired
+ * contribution has not moved since apply; otherwise catalog drift and a
+ * foreign edit are indistinguishable, so the classifier keeps failing closed.
+ */
+function recordedBlockIsOwned(
+  doc: unknown,
+  record: OwnershipRecord,
+  desired: ManagedContribution,
+): boolean {
+  const observed = recordedContribution(doc, record);
+  if (!observed) return false;
+  if (fingerprint(canonicalContribution(observed)) === record.blockFingerprint) return true;
+
+  const observedSemanticFingerprint = fingerprint(semanticContribution(observed));
+  if (
+    typeof record.semanticBlockFingerprint === "string"
+    && observedSemanticFingerprint === record.semanticBlockFingerprint
+  ) return true;
+
+  const desiredFingerprint = fingerprint(canonicalContribution(desired));
+  if (
+    desiredFingerprint === record.blockFingerprint
+    && observedSemanticFingerprint === fingerprint(semanticContribution(desired))
+  ) return true;
+
+  if (
+    typeof record.protectedBlockFingerprint === "string"
+    && validRefreshablePaths(observed, record.refreshablePaths)
+    && record.refreshablePaths.length > 0
+  ) {
+    const observedProtectedFingerprint = protectedContributionFingerprint(
+      observed,
+      record.refreshablePaths,
+    );
+    if (observedProtectedFingerprint === record.protectedBlockFingerprint) return true;
+
+    const observedSemanticProtectedFingerprint = semanticProtectedContributionFingerprint(
+      observed,
+      record.refreshablePaths,
+    );
+    if (
+      typeof record.semanticProtectedBlockFingerprint === "string"
+      && observedSemanticProtectedFingerprint === record.semanticProtectedBlockFingerprint
+    ) return true;
+
+    return protectedContributionFingerprint(desired, record.refreshablePaths)
+        === record.protectedBlockFingerprint
+      && observedSemanticProtectedFingerprint
+        === semanticProtectedContributionFingerprint(desired, record.refreshablePaths);
+  }
+
+  if (desiredFingerprint !== record.blockFingerprint) return false;
+  const legacyPaths = refreshablePathsOf(desired);
+  return legacyPaths.length > 0
+    && semanticProtectedContributionFingerprint(observed, legacyPaths)
+      === semanticProtectedContributionFingerprint(desired, legacyPaths);
 }
 
 /**
@@ -191,7 +259,7 @@ export function classifyIntegration(input: {
    * conflict no matter what the rest of the file looks like, so the sibling-
    * edit exemption below can never mask it.
    */
-  if (recordedFragmentFingerprint(input.parsed, input.record) !== input.record.blockFingerprint) {
+  if (!recordedBlockIsOwned(input.parsed, input.record, input.contribution)) {
     return { state: "conflict", reason: "foreign-edit" };
   }
   if (!INTEGRATION_CLIENTS[clientId].sourcePreservingYaml
@@ -218,7 +286,11 @@ export function classifyIntegration(input: {
     }
     return { state: "stale" };
   }
-  return input.record.blockFingerprint === fingerprint(canonicalContribution(input.contribution))
+  const desiredFingerprint = typeof input.record.semanticBlockFingerprint === "string"
+    ? fingerprint(semanticContribution(input.contribution))
+    : fingerprint(canonicalContribution(input.contribution));
+  const recordedFingerprint = input.record.semanticBlockFingerprint ?? input.record.blockFingerprint;
+  return recordedFingerprint === desiredFingerprint
     ? { state: "current" }
     : { state: "stale" };
 }

package/src/integrations/writer.ts

@@ -15,7 +15,18 @@ import { EXPORT_CLIENTS, type ExportModel, type ManagedContribution } from "../c
 import { isLoopbackHostname } from "../codex/inject";
 import type { OcxConfig } from "../types";
 import { PARSE_FAILED, defaultIntegrationIO, loadTarget, parseConfig, type IntegrationIO } from "./config-io";
-import { fingerprint, canonicalContribution, fragmentPathsOf, type OwnershipRecord } from "./ownership";
+import {
+  fingerprint,
+  canonicalContribution,
+  fragmentPathsOf,
+  semanticContribution,
+  type OwnershipRecord,
+} from "./ownership";
+import {
+  protectedContributionFingerprint,
+  refreshablePathsOf,
+  semanticProtectedContributionFingerprint,
+} from "./ownership-policy";
 import { createdContainerPaths, mergeContribution, removeFragments } from "./merge";
 import { INTEGRATION_CLIENTS, isLoopbackOnly, type IntegrationClientId } from "./registry";
 import { classifyIntegration, exportContextOf } from "./state";
@@ -353,12 +364,22 @@ function applyOrRefreshIntegration(input: IntegrationWriteInput, allowAbsent: bo
     opId, clientId, kind: classified.state === "stale" ? "refresh" : "apply", at, configPath,
     snapshot, resultFingerprint: fingerprint(text), resultAbsent: false, priorRecord: record,
   };
+  const refreshablePaths = refreshablePathsOf(contribution);
   return commit({
     io, store, clientId, configPath, before, nextText: text, state: "current",
     priorRecord: record,
     record: {
       clientId, configPath, fileFingerprint: fingerprint(text),
       blockFingerprint: fingerprint(canonicalContribution(contribution)),
+      semanticBlockFingerprint: fingerprint(semanticContribution(contribution)),
+      ...(refreshablePaths.length > 0 ? {
+        protectedBlockFingerprint: protectedContributionFingerprint(contribution, refreshablePaths),
+        semanticProtectedBlockFingerprint: semanticProtectedContributionFingerprint(
+          contribution,
+          refreshablePaths,
+        ),
+        refreshablePaths,
+      } : {}),
       fragmentPaths: fragmentPathsOf(contribution), createdContainers: created,
       appliedAt: at, opId,
     },
@@ -550,7 +571,10 @@ export function restoreIntegration(input: IntegrationRestoreInput): WriteOutcome
     ? (restoredText === null ? "absent" : "conflict")
     : !recordDescribesBytes
       ? "conflict"
-      : restoredRecord.blockFingerprint === fingerprint(canonicalContribution(fresh))
+      : (
+        restoredRecord.semanticBlockFingerprint === fingerprint(semanticContribution(fresh))
+        || restoredRecord.blockFingerprint === fingerprint(canonicalContribution(fresh))
+      )
         ? "current"
         : "stale";
 

package/src/lab/conformance/fixtures/protocol-v1-cases.json

@@ -274,7 +274,7 @@
       "assertions": [
         { "id": "text", "operator": "normalized_text_equals", "selector": "/client/response/normalizedText", "expected": "OK", "required": true },
         { "id": "terminal", "operator": "terminal_signal_equals", "selector": "/client/response/terminal", "expected": "completed", "required": true },
-        { "id": "phase", "operator": "json_path_equals", "selector": "/client/response/events/6/data/item/phase", "expected": "final_answer", "required": true }
+        { "id": "phase", "operator": "json_path_equals", "selector": "/client/response/events/7/data/item/phase", "expected": "final_answer", "required": true }
       ]
     },
     {

package/src/lab/fabric/producer-child.ts

@@ -128,7 +128,7 @@ async function main(): Promise<void> {
   writeLine({ type: "result", patch });
 }
 
-main().catch((error: unknown) => {
+await main().catch((error: unknown) => {
   writeLine({
     type: "error",
     code: "harness_failure",

package/src/lib/admin-secrets.ts

@@ -1,3 +1,4 @@
+import { timingSafeEqual } from "node:crypto";
 import { lstatSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { getConfigDir } from "../config";
@@ -23,3 +24,26 @@ export function loadAdminTokenFromFile(configDir = getConfigDir()): string | nul
 export function configuredAdminToken(configDir = getConfigDir(), env: NodeJS.ProcessEnv = process.env): string | null {
   return env.OPENCODEX_ADMIN_AUTH_TOKEN?.trim() || loadAdminTokenFromFile(configDir);
 }
+
+export const ADMIN_TOKEN_PREFIX = "ocx_admin_";
+
+function secretTextEquals(left: string, right: string): boolean {
+  const a = Buffer.from(left);
+  const b = Buffer.from(right);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+/**
+ * True when `token` is a management credential: minted `ocx_admin_…` shape, or
+ * byte-equal to the configured admin token (env or admin-api-token file).
+ * Used by the service write/start chokepoint and by doctor so the two cannot drift.
+ */
+export function tokenCollidesWithAdmin(
+  token: string,
+  env: NodeJS.ProcessEnv = process.env,
+  configDir = getConfigDir(),
+): boolean {
+  if (token.startsWith(ADMIN_TOKEN_PREFIX)) return true;
+  const admin = configuredAdminToken(configDir, env);
+  return admin !== null && secretTextEquals(token, admin);
+}

package/src/lib/bounded-body.ts

@@ -103,6 +103,16 @@ function cancelWithoutWaiting(reader: ReadableStreamDefaultReader<Uint8Array>, r
 	}
 }
 
+function cancelBodyWithoutWaiting(body: ReadableStream<Uint8Array>, reason?: unknown): void {
+	// A signal can already be aborted before a reader is attached. Still settle the
+	// original body so fetch-backed streams cannot retain a rejected read in that gap.
+	try {
+		void body.cancel(reason).catch(() => undefined);
+	} catch {
+		// A locked or non-conforming stream may throw synchronously from cancel().
+	}
+}
+
 /**
  * Consume the original response body as raw bytes under a strict memory ceiling.
  *
@@ -208,9 +218,11 @@ export async function readBoundedResponseBody(
 	options: BoundedBodyOptions = {},
 ): Promise<BoundedBodyResult> {
 	const signal = options.signal;
-	if (signal?.aborted) throw signal.reason;
-
 	const body = response.body;
+	if (signal?.aborted) {
+		if (body) cancelBodyWithoutWaiting(body, signal.reason);
+		throw signal.reason;
+	}
 	if (!body) {
 		return {
 			text: "",

package/src/lib/config-ownership.ts

@@ -40,6 +40,7 @@ const INITIAL_OWNED_PATHS = [
   "artifacts",
   "auth.json",
   "auth.store.lock",
+  "admin-api-token",
   "catalog-backup.json",
   "claude-env.sh",
   "codex-accounts.json",
@@ -333,6 +334,25 @@ export function removeOwnedConfigState(configDir: string): ConfigRemovalResult {
     }
   }
 
+  // Per-catalog backups are named `catalog-backup-<16 hex>.json` (catalogBackupPathFor), one per
+  // CODEX_HOME, so they cannot be enumerated as literal manifest entries the way every other
+  // owned file can. Without this, `ocx uninstall` always reported "unowned files remain" and
+  // refused to remove a home OpenCodex created itself — the file is unambiguously ours, produced
+  // by our own writer, and the strict hex shape keeps the match from widening.
+  for (const name of readdirSync(configDir)) {
+    if (!/^catalog-backup-[0-9a-f]{16}\.json$/.test(name)) continue;
+    const path = join(configDir, name);
+    try {
+      removeOwnedEntry(rootPath, path);
+    } catch (error) {
+      return {
+        status: "partial",
+        reason: `could not remove owned path ${name}: ${error instanceof Error ? error.message : String(error)}`,
+        residualPaths: [path],
+      };
+    }
+  }
+
   try {
     unlinkSync(join(configDir, CONFIG_UNINSTALL_MANIFEST));
     unlinkSync(join(configDir, CONFIG_OWNER_FILE));

package/src/lib/errors.ts

@@ -6,11 +6,18 @@ export interface OcxErrorPayload {
 
 /** OpenAI / Codex hard block for high-risk cybersecurity activity (HTTP 400 or mid-stream). */
 export const CYBER_POLICY_ERROR_CODE = "cyber_policy";
+export const CYBER_POLICY_FALLBACK_MESSAGE = "Request blocked by the upstream cybersecurity policy.";
 
 export function isCyberPolicyCode(code: string | null | undefined): boolean {
   return code === CYBER_POLICY_ERROR_CODE;
 }
 
+/** Preserve a structured upstream error type; otherwise use the dedicated policy identity. */
+export function cyberPolicyErrorType(type: string | null | undefined): string {
+  const trimmed = typeof type === "string" ? type.trim() : "";
+  return trimmed || CYBER_POLICY_ERROR_CODE;
+}
+
 /**
  * Detect OpenAI cyber-policy refusals from message text when structured `code` was stripped.
  * Matches Codex fallback copy and Cursor/API agent wording (session evidence 2026-07-24).
@@ -139,9 +146,11 @@ export function classifyError(status: number, type: string, message: string): Oc
     return { message, type: "invalid_request_error", code: "client_closed_request" };
   }
   // Codex only shows the dedicated cyber UI when error.code === "cyber_policy".
-  // Prefer that code (and invalid_request_error) over generic remaps / 502 upstream_server_error.
+  // The public wire does not establish invalid_request_error as the canonical type, so
+  // message-only classification keeps the dedicated identity instead of inventing one.
+  // Structured callers re-apply their real upstream type with cyberPolicyErrorType().
   if (type === CYBER_POLICY_ERROR_CODE || isCyberPolicyMessage(text)) {
-    return { message, type: "invalid_request_error", code: CYBER_POLICY_ERROR_CODE };
+    return { message, type: CYBER_POLICY_ERROR_CODE, code: CYBER_POLICY_ERROR_CODE };
   }
   // A LOCAL preflight refusal keeps its own code (#1524). The message necessarily says
   // "context window" -- that is what it is refusing on -- so the generic remap below would
@@ -326,6 +335,12 @@ export function inferHttpStatusFromAdapterMessage(message: string): number {
   // subscription/permission wording.
   if (isAuthenticationMessage(lower)) return 401;
   if (isSubscriptionGateMessage(lower) || isPermissionMessage(lower)) return 403;
+  // Same precedence rule as classifyCursorError: an explicit gRPC FAILED_PRECONDITION is a
+  // structured, deterministic rejection, so it outranks the overload keywords that routinely
+  // appear beside it ("failed_precondition: model unavailable for this plan"). Without this,
+  // the message matched "unavailable" and returned a retryable 503, so clients kept retrying
+  // a rejection that can never succeed.
+  if (lower.includes("failed_precondition") || lower.includes("failed precondition")) return 400;
   if (
     lower.includes("unavailable") ||
     lower.includes("overloaded") ||
@@ -401,6 +416,24 @@ export function httpStatusFromTerminalError(error: {
   if (message && isClientClosedMessage(message)) return 499;
   if (error.type === "invalid_request_error") return 400;
   if (error.type === "proxy_error") return 500;
-  if (message) return inferHttpStatusFromAdapterMessage(message);
+  // A structured server class must not be downgraded to a CLIENT error by message wording.
+  // classifyError assigns `server_error` + `upstream_server_error` to every 5xx it sees, so
+  // the class is authoritative about blame: the upstream failed, the caller did not send a
+  // bad request. What it is NOT authoritative about is which server status fits — a stall is
+  // genuinely 504 and an overload genuinely 503, and flattening those to 502 discards
+  // information both the log surface and the retry policy read. So message inference still
+  // chooses the specific status, and only a client-error verdict is overridden.
+  //
+  // The override is deliberately narrowed to 400 alone. 429, 499, 401 and 403 are all
+  // actionable signals the caller routes on — retry-after, client cancellation, re-auth,
+  // entitlement — and overriding them would trade one kind of misreport for another. 400 is
+  // the single verdict that both blames the caller and stops the retry, which is the failure
+  // being fixed: an upstream 500 whose text happens to contain "malformed" or "invalid
+  // request" used to return 400, so Claude Code stopped retrying a retryable failure.
+  const structuredServerClass = error.type === "server_error" || error.code === "upstream_server_error";
+  if (message) {
+    const inferred = inferHttpStatusFromAdapterMessage(message);
+    return structuredServerClass && inferred === 400 ? 502 : inferred;
+  }
   return 502;
 }