@bitkyc08/opencodex 2.58.0 → 2.59.0

package/src/codex/windows-installation-files.ts

@@ -0,0 +1,224 @@
+import { createHash } from "node:crypto";
+import type { Library, Symbols } from "bun:ffi";
+
+const KERNEL_SYMBOLS = {
+  GetDriveTypeW: { args: ["ptr"], returns: "u32" },
+  GetVolumeNameForVolumeMountPointW: { args: ["ptr", "ptr", "u32"], returns: "i32" },
+  CreateFileW: { args: ["ptr", "u32", "u32", "ptr", "u32", "u32", "u64"], returns: "u64" },
+  GetFileInformationByHandleEx: { args: ["u64", "i32", "ptr", "u32"], returns: "i32" },
+  GetFileType: { args: ["u64"], returns: "u32" },
+  ReadFile: { args: ["u64", "ptr", "u32", "ptr", "ptr"], returns: "i32" },
+  CloseHandle: { args: ["u64"], returns: "i32" },
+} as const satisfies Symbols;
+const NT_SYMBOLS = {
+  NtCreateFile: { args: ["ptr", "u32", "ptr", "ptr", "ptr", "u32", "u32", "u32", "u32", "ptr", "u32"], returns: "i32" },
+} as const satisfies Symbols;
+
+export interface WindowsInstallationFileRequest {
+  readonly path: string;
+  readonly maxBytes: number;
+  readonly hashOnly?: boolean;
+}
+export interface WindowsInstallationFileIdentity {
+  readonly volumeSerial: string;
+  readonly fileId: string;
+  readonly size: number;
+  readonly lastWriteTime: string;
+  readonly changeTime: string;
+}
+export type WindowsInstallationFilesResult =
+  | { kind: "observed"; files: {
+    path: string; identity: WindowsInstallationFileIdentity; bytes: Uint8Array; digest: string;
+  }[] }
+  | { kind: "refused"; reason: "unsupported-platform" | "invalid-request" | "native-api-unavailable"
+    | "volume-unavailable" | "open-refused" | "reparse-point" | "not-regular-file"
+    | "size-limit" | "read-failed" | "identity-changed" | "inspection-failed" };
+
+type Refusal = Extract<WindowsInstallationFilesResult, { kind: "refused" }>["reason"];
+class InspectionRefusal extends Error {
+  constructor(readonly reason: Refusal) { super(reason); }
+}
+const MIB = 1024 * 1024;
+const REPARSE = 0x400;
+const DIRECTORY = 0x10;
+const INVALID_HANDLE = 0xffffffffffffffffn;
+let openedForTests: (() => void) | undefined;
+/** Runs after handles are held, for real Windows sharing/rename regression fixtures. */
+export function setWindowsInstallationFilesOpenedForTests(callback?: () => void): void {
+  openedForTests = callback;
+}
+
+function components(path: string): { drive: string; names: string[] } | null {
+  if (typeof path !== "string" || path.length > 8192 || !/^[A-Za-z]:[\\/]/.test(path)) return null;
+  const names = path.slice(3).split(/[\\/]/);
+  if (!names.length || names.length > 64 || names.some(name => !name || name === "." || name === ".."
+    || /[\x00-\x1f<>:"|?*]/.test(name) || /[. ]$/.test(name)
+    || /^(?:con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³])(?:\.|$)/i.test(name))) return null;
+  return { drive: `${path[0]!.toUpperCase()}:\\`, names };
+}
+
+/**
+ * An explicit, read-only snapshot; never installation authority or a runtime-selection proof.
+ * All component opens are relative to held directory handles, not checked-then-reopened paths.
+ * Windows x64 only: the UNICODE_STRING/OBJECT_ATTRIBUTES layouts below are the x64 ABI.
+ * No candidate runs and no shell/compiler is started. Disk/driver latency is not a hard deadline.
+ * API contracts: learn.microsoft.com/windows/win32/api/winternl/nf-winternl-ntcreatefile
+ * and /windows/win32/api/fileapi/nf-fileapi-getvolumenameforvolumemountpointw.
+ */
+export async function inspectWindowsInstallationFiles(
+  requests: readonly WindowsInstallationFileRequest[],
+): Promise<WindowsInstallationFilesResult> {
+  if (!Array.isArray(requests) || requests.length === 0 || requests.length > 12) {
+    return { kind: "refused", reason: "invalid-request" };
+  }
+  let ceiling = 0;
+  const parsed = requests.map(request => {
+    const parsedPath = request && components(request.path);
+    if (!parsedPath || !Number.isSafeInteger(request.maxBytes) || request.maxBytes < 0
+      || (request.hashOnly !== undefined && typeof request.hashOnly !== "boolean")
+      || request.maxBytes > (request.hashOnly ? 256 * MIB : MIB)) return null;
+    ceiling += request.maxBytes;
+    return parsedPath;
+  });
+  if (parsed.some(path => path === null) || ceiling > 300 * MIB) {
+    return { kind: "refused", reason: "invalid-request" };
+  }
+  if (process.platform !== "win32" || process.arch !== "x64") {
+    return { kind: "refused", reason: "unsupported-platform" };
+  }
+  // Loading FFI is itself opt-in; importing this module performs no Windows inspection.
+  let ffi: typeof import("bun:ffi");
+  try { ffi = await import("bun:ffi"); } catch { return { kind: "refused", reason: "native-api-unavailable" }; }
+  let kernel: Library<typeof KERNEL_SYMBOLS> | undefined;
+  let nt: Library<typeof NT_SYMBOLS> | undefined;
+  const handles: bigint[] = [];
+  try {
+    try {
+      kernel = ffi.dlopen("kernel32.dll", KERNEL_SYMBOLS);
+      nt = ffi.dlopen("ntdll.dll", NT_SYMBOLS);
+    } catch { throw new InspectionRefusal("native-api-unavailable"); }
+    const k = kernel.symbols;
+    const wide = (text: string): Buffer => Buffer.from(`${text}\0`, "utf16le");
+    const keep = (handle: bigint): bigint => {
+      if (handle === 0n || handle === INVALID_HANDLE) throw new InspectionRefusal("open-refused");
+      handles.push(handle);
+      return handle;
+    };
+    const info = (handle: bigint, infoClass: number, length: number): Buffer => {
+      const buffer = Buffer.alloc(length);
+      if (!k.GetFileInformationByHandleEx!(handle, infoClass, ffi.ptr(buffer), length)) {
+        throw new InspectionRefusal("inspection-failed");
+      }
+      return buffer;
+    };
+    const inspect = (handle: bigint, directory: boolean): WindowsInstallationFileIdentity => {
+      if (k.GetFileType!(handle) !== 1) throw new InspectionRefusal("not-regular-file"); // FILE_TYPE_DISK
+      const basic = info(handle, 0, 40); // FILE_BASIC_INFO: 4 LARGE_INTEGERs, attributes.
+      const attributes = basic.readUInt32LE(32);
+      if (attributes & REPARSE) throw new InspectionRefusal("reparse-point");
+      if (Boolean(attributes & DIRECTORY) !== directory) throw new InspectionRefusal("not-regular-file");
+      const id = info(handle, 18, 24); // FILE_ID_INFO: volume serial and 128-bit file ID.
+      const standard = info(handle, 1, 24); // FILE_STANDARD_INFO.EndOfFile
+      const size = standard.readBigInt64LE(8);
+      if (size < 0n || size > BigInt(Number.MAX_SAFE_INTEGER)) throw new InspectionRefusal("size-limit");
+      return { volumeSerial: id.readBigUInt64LE(0).toString(16), fileId: id.subarray(8, 24).toString("hex"),
+        size: Number(size), lastWriteTime: basic.readBigInt64LE(16).toString(), changeTime: basic.readBigInt64LE(24).toString() };
+    };
+    const roots = new Map<string, bigint>();
+    const root = (drive: string): bigint => {
+      const held = roots.get(drive);
+      if (held !== undefined) return held;
+      const mount = wide(drive);
+      const name = Buffer.alloc(100 * 2);
+      if (![2, 3, 5, 6].includes(Number(k.GetDriveTypeW!(ffi.ptr(mount))))) {
+        throw new InspectionRefusal("volume-unavailable");
+      }
+      // Root-only volume management query, never a candidate-controlled ancestor traversal.
+      // This API does not support SMB; only a strict local volume GUID reaches CreateFileW.
+      if (!k.GetVolumeNameForVolumeMountPointW!(ffi.ptr(mount), ffi.ptr(name), 100)) {
+        throw new InspectionRefusal("volume-unavailable");
+      }
+      const guid = name.toString("utf16le").split("\0", 1)[0]!;
+      if (!/^\\\\\?\\Volume\{[0-9a-f-]{36}\}\\$/i.test(guid)) throw new InspectionRefusal("volume-unavailable");
+      const path = wide(guid);
+      const handle = keep(BigInt(k.CreateFileW!(ffi.ptr(path), 0x100081, 1, null, 3, 0x02200000, 0n)));
+      inspect(handle, true);
+      roots.set(drive, handle);
+      return handle;
+    };
+    const relativeOpen = (parent: bigint, component: string, directory: boolean): bigint => {
+      const name = wide(component);
+      const unicode = Buffer.alloc(16);
+      unicode.writeUInt16LE(name.length - 2, 0);
+      unicode.writeUInt16LE(name.length, 2);
+      unicode.writeBigUInt64LE(BigInt(ffi.ptr(name)), 8);
+      const attributes = Buffer.alloc(48);
+      attributes.writeUInt32LE(48, 0);
+      attributes.writeBigUInt64LE(parent, 8);
+      attributes.writeBigUInt64LE(BigInt(ffi.ptr(unicode)), 16);
+      attributes.writeUInt32LE(0x40, 24); // OBJ_CASE_INSENSITIVE; one component only.
+      const output = Buffer.alloc(8);
+      const status = Buffer.alloc(16);
+      // FILE_OPEN; FILE_SYNCHRONOUS_IO_NONALERT; FILE_OPEN_REPARSE_POINT.
+      // Share READ only: while held, writes/reparse edits and delete/rename opens are refused.
+      const result = nt!.symbols.NtCreateFile!(ffi.ptr(output), 0x100081, ffi.ptr(attributes),
+        ffi.ptr(status), null, 0, 1, 1, 0x200020 | (directory ? 1 : 0), null, 0);
+      if (result < 0) throw new InspectionRefusal("open-refused");
+      const handle = keep(output.readBigUInt64LE(0));
+      inspect(handle, directory);
+      return handle;
+    };
+    const directories = new Map<string, bigint>();
+    const files = requests.map((request, index) => {
+      const { drive, names } = parsed[index]!;
+      let parent = root(drive);
+      let key = drive;
+      for (const component of names.slice(0, -1)) {
+        key += `${component}\\`;
+        let handle = directories.get(key);
+        if (handle === undefined) {
+          handle = relativeOpen(parent, component, true);
+          directories.set(key, handle);
+        }
+        parent = handle;
+      }
+      const handle = relativeOpen(parent, names[names.length - 1]!, false);
+      const identity = inspect(handle, false);
+      if (identity.size > request.maxBytes) throw new InspectionRefusal("size-limit");
+      return { request, handle, identity };
+    });
+    openedForTests?.();
+    const observed = files.map(({ request, handle, identity }) => {
+      const hash = createHash("sha256");
+      const bytes = request.hashOnly ? new Uint8Array() : new Uint8Array(identity.size);
+      const chunk = Buffer.alloc(Math.min(MIB, Math.max(1, identity.size)));
+      const read = Buffer.alloc(4);
+      let offset = 0;
+      while (offset < identity.size) {
+        const length = Math.min(chunk.length, identity.size - offset);
+        if (!k.ReadFile!(handle, ffi.ptr(chunk), length, ffi.ptr(read), null)) throw new InspectionRefusal("read-failed");
+        const count = read.readUInt32LE(0);
+        if (!count || count > length) throw new InspectionRefusal("read-failed");
+        hash.update(chunk.subarray(0, count));
+        if (!request.hashOnly) bytes.set(chunk.subarray(0, count), offset);
+        offset += count;
+      }
+      if (!k.ReadFile!(handle, ffi.ptr(chunk), 1, ffi.ptr(read), null) || read.readUInt32LE(0) !== 0) {
+        throw new InspectionRefusal("identity-changed");
+      }
+      return { path: request.path, identity, bytes, digest: hash.digest("hex") };
+    });
+    for (const file of files) {
+      if (JSON.stringify(inspect(file.handle, false)) !== JSON.stringify(file.identity)) {
+        throw new InspectionRefusal("identity-changed");
+      }
+    }
+    return { kind: "observed", files: observed };
+  } catch (error) {
+    return { kind: "refused", reason: error instanceof InspectionRefusal ? error.reason : "inspection-failed" };
+  } finally {
+    for (const handle of handles.reverse()) kernel?.symbols.CloseHandle?.(handle);
+    nt?.close();
+    kernel?.close();
+  }
+}

package/src/combos/failover.ts

@@ -118,23 +118,29 @@ function parseHttpDate(value: string, now: number): number | undefined {
 export function parseRetryAfterMs(
   value: string | null | undefined,
   now = Date.now(),
-  options?: { preserveImmediate?: boolean },
+  options?: { preserveImmediate?: boolean; preserveServerDelay?: boolean },
 ): number | undefined {
   const text = value?.trim();
   if (!text) return undefined;
+  // A local wait ceiling must not make an explicit upstream reset expire early.
+  // Keep legacy bounded parsing for other callers. The opt-in stores a timestamp;
+  // the combo picker still independently limits how long a live request waits.
+  const maximum = options?.preserveServerDelay === true
+    ? Number.MAX_SAFE_INTEGER - Math.max(0, now)
+    : MAX_COOLDOWN_MS;
   if (/^\d+(?:\.\d+)?$/.test(text)) {
     const seconds = Number(text);
     if (
       Number.isFinite(seconds)
       && (seconds > 0 || (options?.preserveImmediate && seconds === 0))
     ) {
-      return Math.min(Math.max(Math.ceil(seconds * 1000), 1), MAX_COOLDOWN_MS);
+      return Math.min(Math.max(Math.ceil(seconds * 1000), 1), maximum);
     }
   }
   const timestamp = parseHttpDate(text, now);
   if (timestamp === undefined) return undefined;
   const delay = timestamp - now;
-  if (delay > 0) return Math.min(delay, MAX_COOLDOWN_MS);
+  if (delay > 0) return Math.min(delay, maximum);
   return options?.preserveImmediate ? 1 : undefined;
 }
 
@@ -215,7 +221,11 @@ export function coolComboTarget(
   // A server-provided Retry-After is authoritative, including an immediate `0` directive.
   // A quota reset is the next-most-specific signal (#3256); configured and default cooldowns
   // are only fallbacks when upstream supplied neither usable value.
-  const cooldownMs = parseRetryAfterMs(options?.retryAfter, now, { preserveImmediate: true })
+  const serverDelayMs = parseRetryAfterMs(options?.retryAfter, now, {
+    preserveImmediate: true,
+    preserveServerDelay: true,
+  });
+  const cooldownMs = serverDelayMs
     ?? parseResetCooldownMs(options?.resetAt, now)
     ?? options?.cooldownMs
     ?? (isTransientRequestRateLimit({
@@ -224,7 +234,9 @@ export function coolComboTarget(
       message: options?.message,
     }) ? COMBO_REQUEST_RATE_COOLDOWN_MS : DEFAULT_COOLDOWN_MS);
   targetCooldowns.set(cooldownMapKey(comboId, target), {
-    cooldownUntil: now + Math.min(Math.max(cooldownMs, 1), MAX_COOLDOWN_MS),
+    // Only the locally chosen fallback is capped at ten minutes. An explicit
+    // server lower bound (including one hour) remains authoritative.
+    cooldownUntil: now + (serverDelayMs ?? Math.min(Math.max(cooldownMs, 1), MAX_COOLDOWN_MS)),
   });
   sweepExpiredOnWrite(now);
 }
@@ -394,6 +406,103 @@ function isRequestLocalTargetIncompatibility(status: number, message: string, co
   return false;
 }
 
+/**
+ * Codes a gateway uses when it declines a request field it cannot serve.
+ *
+ * Wider than the set {@link isRequestLocalTargetIncompatibility} accepts, by exactly one member:
+ * Alibaba's gateway reports `invalid_parameter_error`. It is kept in its own set rather than
+ * added to the shared one, because that set also governs the `user` parameter and image-input
+ * branches and widening it there would admit shapes those branches were reasoned about without.
+ */
+const RESPONSE_FORMAT_REFUSAL_CODES = new Set([
+  "",
+  "invalid_request_error",
+  "invalid_parameter_error",
+  "unsupported_parameter",
+  "unsupported_value",
+]);
+
+/**
+ * Does this message say the target cannot PROVIDE `response_format`, rather than that the
+ * request's `response_format` was malformed?
+ *
+ * That distinction is the whole point of #4903 and it is why neither obvious option was taken.
+ * Hopping on every 400 would replay a genuinely malformed request against every remaining
+ * target. Dropping `response_format` would silently change the output contract the caller
+ * asked for, on a path whose entire purpose is a structured result.
+ *
+ * So both halves are required: the message must name the field, AND it must say the field is
+ * unavailable or unsupported. "Invalid schema for response_format" names the field and claims
+ * nothing about capability, so it stays terminal.
+ *
+ * `param` may be absent or explicitly null -- the reported gateway sends `param: null` -- but a
+ * param naming a DIFFERENT field contradicts the message and fails closed.
+ */
+function namesResponseFormatIncapability(message: string, param: unknown): boolean {
+  if (param !== undefined && param !== null && param !== "response_format") return false;
+  const text = message.toLowerCase();
+  if (!text.includes("response_format")) return false;
+  return /(unavailable|not available|unsupported|not supported|does not support|doesn't support|cannot be used|is not enabled)/u
+    .test(text);
+}
+
+/**
+ * A `response_format` capability gap is target-local: this model cannot produce the requested
+ * output shape, which says nothing about the next target in the combo.
+ *
+ * Reported against a shadow title-generation call, where a combo's first target rejects
+ * `response_format` and the chain stops instead of trying the target behind it (#4903).
+ *
+ * The next target receives the SAME request, `response_format` included, so a target that can
+ * honour the contract honours it and one that cannot is skipped in turn. Traversal stays finite
+ * because combo excludes each attempted target and policy tries each candidate once.
+ *
+ * The envelope is bounded exactly like {@link isRequestLocalTargetIncompatibility}: an intact
+ * provider JSON object, a depth budget, `type: "invalid_request_error"`, and a code from a
+ * closed set. Nothing is inferred from echoed prompt text and no field is removed.
+ */
+function isResponseFormatCapabilityRefusal(
+  status: number,
+  message: string,
+  code?: string | null,
+): boolean {
+  if (status !== 400 || message.length > 16_384) return false;
+  if (!RESPONSE_FORMAT_REFUSAL_CODES.has(normalizedFailureCode(code))) return false;
+  let text = message.trim();
+  for (let depth = 0; depth < 3; depth += 1) {
+    if (text.startsWith("Provider error 400: ")) {
+      text = text.slice("Provider error 400: ".length).trim();
+    }
+    // A chat gateway can report the refusal inside a single SSE frame, and the combo consumer
+    // keeps the raw text when that frame stops the error object from being extracted -- which is
+    // why the reported classification text reads `data: {"error":...}` and why the structured
+    // code arrives undefined. Exactly one `data:` prefix is removed, and only when the body is
+    // one line: this unwraps a single frame rather than parsing a stream, so a multi-event body
+    // is left alone and still fails closed.
+    if (text.startsWith("data:") && !text.includes("\n")) {
+      text = text.slice("data:".length).trim();
+    }
+    let payload: unknown;
+    try { payload = JSON.parse(text); } catch { return false; }
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) return false;
+    const error = (payload as Record<string, unknown>).error;
+    if (!error || typeof error !== "object" || Array.isArray(error)) return false;
+    const e = error as Record<string, unknown>;
+    if (e.code !== undefined && e.code !== null && typeof e.code !== "string") return false;
+    if (typeof e.message !== "string") return false;
+    // Our own wrapper, re-wrapped by a downstream hop. Peel it and look again, within budget.
+    if (e.message.startsWith("Provider error 400: ") && e.param === undefined) {
+      text = e.message;
+      continue;
+    }
+    if (e.type !== "invalid_request_error") return false;
+    const errorCode = normalizedFailureCode(typeof e.code === "string" ? e.code : undefined);
+    if (!RESPONSE_FORMAT_REFUSAL_CODES.has(errorCode)) return false;
+    return namesResponseFormatIncapability(e.message, e.param);
+  }
+  return false;
+}
+
 export function comboFailureCooldownScope(
   status: number,
   message: string,
@@ -411,6 +520,9 @@ export function comboFailureCooldownScope(
     || isProviderTargetContextOverflow(status, message, options?.code)
     || isDefiniteContextOverflow(status, message)
     || isRequestLocalTargetIncompatibility(status, message, options?.code)
+    // A capability gap says the target is healthy and the request did not fit it, which is the
+    // same reason every other entry here refuses to cool a target.
+    || isResponseFormatCapabilityRefusal(status, message, options?.code)
   ) return "none";
   if (isProviderScopedQuotaCap(status, message, options?.code)) return "provider";
   // A rejected or unpaid credential is provider-wide evidence: every target that routes
@@ -595,6 +707,11 @@ export function comboFailureDecision(
   // per-request cap, not provider-wide evidence), so keep its hop verdict explicit here.
   if (failureCode === "free_rate_limited") return "hop";
   if (isRequestLocalTargetIncompatibility(status, message, options?.code)) return "hop";
+  // Must precede the generic `invalid_request_error` stop below, which is where this refusal
+  // ended the chain: the gateway reports `type: "invalid_request_error"`, so the classifier
+  // reaches that list and returns terminal before anything can ask whether the next target
+  // could have served the request (#4903).
+  if (isResponseFormatCapabilityRefusal(status, message, options?.code)) return "hop";
   if (["origin_rejected", "context_length_exceeded", "invalid_request_error"].includes(error.code ?? "")) {
     return "stop";
   }

package/src/config/diagnostics.ts

@@ -34,6 +34,7 @@ import {
   malformedQuotaResetNotifyWarning,
   malformedCatalogAutoRefreshWarning,
   malformedCodexPoolWarning,
+  malformedSpendWarning,
   rawConfigRecord,
   malformedNativeSubagentFields,
   malformedNativeSubagentFieldWarning,
@@ -58,6 +59,7 @@ import {
   quotaResetNotifySchema,
   remoteGuiConfigSchema,
   runtimeRoleSchema,
+  spendSchema,
 } from "./schema/leaf-validators";
 
 export type ConfigDiagnostics = {
@@ -122,6 +124,8 @@ function validFileConfigDiagnostics(config: OcxConfig, rawParsed: unknown): Conf
   if (catalogRefreshWarning) warnings.push(catalogRefreshWarning);
   const codexPoolWarning = malformedCodexPoolWarning(rawParsed);
   if (codexPoolWarning) warnings.push(codexPoolWarning);
+  const spendWarning = malformedSpendWarning(rawParsed);
+  if (spendWarning) warnings.push(spendWarning);
   const plaintextWarning = malformedPlaintextV2AgentMessagesWarning(rawParsed);
   if (plaintextWarning) warnings.push(plaintextWarning);
   if (syncDisabledReason) {
@@ -295,6 +299,22 @@ function catalogAutoRefreshError(value: unknown): string | null {
   return `schema_invalid: catalogAutoRefresh${field ? `.${field}` : ""}: ${issue?.message ?? "invalid configuration"}`;
 }
 
+/**
+ * The read path degrades a malformed spend section to undefined, which means no ceiling is
+ * enforced. Reject it on write so `ocx config set` cannot store a budget that reads back as
+ * configured and refuses nothing -- a ceiling that is not enforced looks identical to one
+ * nothing has reached.
+ */
+function spendError(value: unknown): string | null {
+  const raw = rawConfigRecord(value);
+  if (!raw || !Object.hasOwn(raw, "spend") || raw.spend === undefined) return null;
+  const result = spendSchema.safeParse(raw.spend);
+  if (result.success) return null;
+  const issue = result.error.issues[0];
+  const field = issue?.path.join(".");
+  return `schema_invalid: spend${field ? `.${field}` : ""}: ${issue?.message ?? "invalid configuration"}`;
+}
+
 /**
  * The read path degrades a malformed pool policy to undefined, which for an exclusion policy means
  * the excluded accounts quietly keep serving traffic. Reject it on write so `ocx config set` cannot
@@ -551,6 +571,7 @@ export function validateConfigCandidate(value: unknown): { ok: true; config: Ocx
     ?? agentTaskRecoveryError(value)
     ?? quotaResetNotifyError(value)
     ?? catalogAutoRefreshError(value)
+    ?? spendError(value)
     ?? codexPoolError(value)
     ?? googleAntigravityStaticCatalogVersionError(value)
     ?? codexAccountPrioritiesError(value)

package/src/config/load-degrade.ts

@@ -33,6 +33,7 @@ import {
   remoteGuiConfigSchema,
   retryOn429PolicySchema,
   runtimeRoleSchema,
+  spendSchema,
 } from "./schema/leaf-validators";
 import { hasWarnedInheritedFastWireConflict, markWarnedInheritedFastWireConflict } from "./warn-memo";
 
@@ -636,6 +637,20 @@ export function malformedCatalogAutoRefreshWarning(rawParsed: unknown): string |
   return `catalogAutoRefresh${field ? `.${field}` : ""} ignored: invalid catalog auto-refresh configuration`;
 }
 
+/**
+ * The same silent-in-the-wrong-direction failure, and the most expensive instance of it here:
+ * a dropped spend section means the ceilings are not enforced, and an unenforced ceiling is
+ * indistinguishable from one nothing has reached. The operator finds out from the bill.
+ */
+export function malformedSpendWarning(rawParsed: unknown): string | null {
+  const raw = rawConfigRecord(rawParsed);
+  if (!raw || !Object.hasOwn(raw, "spend")) return null;
+  const result = spendSchema.safeParse(raw.spend);
+  if (result.success) return null;
+  const field = result.error.issues[0]?.path.join(".");
+  return `spend${field ? `.${field}` : ""} ignored: invalid spend ceiling configuration, so no token ceiling is enforced`;
+}
+
 /**
  * Same silent-in-the-wrong-direction failure as the notification block: a dropped pool policy means
  * the accounts the operator meant to exclude keep taking traffic, and the only visible symptom is

package/src/config/pending-teardown.ts

@@ -295,6 +295,14 @@ export function quarantinePendingTeardown(nonce: string): string | null {
  * alone. Only an abandoned obligation is a candidate, and a VALID one still has to prove
  * its endpoint is down before anything is restored — an invalid one never can, which is
  * what {@link quarantinePendingTeardown} exists for.
+ *
+ * `isAlive` must answer "is the OWNER still running", which is not "is this PID alive".
+ * PIDs are reused: after the owner exits its number can be handed to an unrelated process,
+ * and a bare liveness probe then reports the owner as running for as long as that process
+ * lives. The receipt is neither recovered nor quarantined nor reported while both updater
+ * gates keep refusing on it, which is a permanent fail-closed with no way forward (#4897).
+ * `handleStop` therefore passes an identity-aware predicate; do not substitute a bare
+ * `process.kill(pid, 0)` here for cheapness.
  */
 export function isPendingTeardownAbandoned(
   read: PendingTeardownRead | TeardownScanFailure,

package/src/config/process-state.ts

@@ -110,16 +110,29 @@ export function removeRuntimePortIfPidIs(snapshotPid: number | null): void {
   try { unlinkSync(getRuntimePortPath()); } catch { /* ignore */ }
 }
 
-export function isOcxStartCommandLine(commandLine: string): boolean {
+/**
+ * Does this command line belong to an opencodex process at all, whatever it is doing?
+ *
+ * {@link isOcxStartCommandLine} answers the narrower question the pidfile needs — "is this
+ * the proxy?" — by additionally requiring the `start` verb. Ownership of a pending-teardown
+ * receipt is the broader question: the owner is whichever invocation claimed it, which is an
+ * `ocx stop` or the `ocx update` worker that drove it, never an `ocx start`. Asking the
+ * start-shaped question there would call every real owner foreign.
+ */
+export function isOcxCommandLine(commandLine: string): boolean {
   const normalized = commandLine.toLowerCase().replace(/\\/g, "/");
   // Keep legacy source launches and npm's in-place Windows rename recognizable:
   // a service wrapper may respawn from `.opencodex-*` during a global update.
-  const hasOcxEntrypoint = normalized.includes("src/cli.ts")
+  return normalized.includes("src/cli.ts")
     || normalized.includes("src/cli/index.ts")
     || normalized.includes("@bitkyc08/opencodex")
     || /@bitkyc08\/\.opencodex-/.test(normalized)
     || /(?:^|[\s/"'])(?:ocx|opencodex)(?:\.cmd)?(?:$|[\s"'])/.test(normalized);
-  return hasOcxEntrypoint && /(?:^|[\s"'])start(?:$|[\s"'])/.test(normalized);
+}
+
+export function isOcxStartCommandLine(commandLine: string): boolean {
+  const normalized = commandLine.toLowerCase().replace(/\\/g, "/");
+  return isOcxCommandLine(commandLine) && /(?:^|[\s"'])start(?:$|[\s"'])/.test(normalized);
 }
 
 /** Avoid spawning WMIC/PowerShell on every short liveness poll. */
@@ -227,6 +240,26 @@ export function verifyPidIdentity(candidatePid: number): number | null {
   return isLikelyOcxStartProcess(candidatePid) ? candidatePid : null;
 }
 
+/**
+ * Is this PID an opencodex process, rather than merely a live one?
+ *
+ * `process.kill(pid, 0)` answers "does this number name a process", which is not the same
+ * question. PIDs are reused, so a recorded owner that exited can have its number handed to
+ * an unrelated process, and bare liveness then reports the owner as still running forever.
+ *
+ * Deliberately uncached, unlike {@link isLikelyOcxStartProcess}. That cache exists because
+ * liveness polling asks about the same PID many times a second; this is asked once per
+ * outstanding teardown receipt in a short-lived `ocx stop`, so the cache would only add an
+ * unswept map. The Windows WMIC/PowerShell probe cost is the point rather than a regression:
+ * the runtime contract requires the identity check, not the cheap one, before acting on
+ * stale state.
+ */
+export function isLikelyOcxProcess(pid: number): boolean {
+  const commandLine = readProcessCommandLine(pid);
+  if (commandLine === undefined) return false;
+  return isOcxCommandLine(commandLine);
+}
+
 type ProcessCommandLineExec = (
   executable: string,
   args: string[],

package/src/config/provider-relative-send-path.ts

@@ -0,0 +1,16 @@
+/** Shared, initialization-independent shape check for provider send-path overrides. */
+export function providerRelativeSendPathConfigError(
+  field: "responsesPath" | "chatCompletionsPath",
+  value: unknown,
+): string | null {
+  if (value === undefined) return null;
+  if (typeof value !== "string") return `${field} must be a string`;
+  if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(value) || value.includes("://")) {
+    return `${field} must be a relative path without a URL scheme`;
+  }
+  if (!value.startsWith("/")) return `${field} must start with /`;
+  if (value.includes("?") || value.includes("#")) {
+    return `${field} must not include query strings or fragments`;
+  }
+  return null;
+}

package/src/config/proxy-env.ts

@@ -1,3 +1,5 @@
+import { configureSocks5Fetch } from "../lib/proxy-env";
+import { redactUrlForLog } from "../lib/redact";
 import { join } from "node:path";
 import { DEFAULT_SUBAGENT_MODELS, SUBAGENT_MODELS_VERSION } from "./subagent-models";
 import { MULTI_AGENT_SURFACE_ADVISORY_VERSION } from "./multi-agent-surface";
@@ -102,10 +104,15 @@ function warnProxyConfigDiscardOnce(kind: "proxy" | "noProxy" | "noProxyElements
  * variables win; config fills missing scheme proxies, which take precedence over ALL_PROXY for WS.
  * localhost/127.0.0.1 are appended to NO_PROXY so the CLI's own health checks and
  * running-proxy API calls stay direct. Call once per process entry that makes outbound provider
- * requests (server start, catalog sync).
+ * requests (server start, catalog sync). `announce` prints the one-line startup banner naming
+ * the outbound proxy actually in effect; only server start passes it, because on catalog sync
+ * that line is noise. The URL is redacted because a proxy URL can carry credentials.
  */
-export function applyProxyEnv(config: OcxConfig): void {
+export function applyProxyEnv(config: OcxConfig, announce = false): void {
   applyProxyEnvWith(config);
+  if (!announce) return;
+  const outbound = process.env.ALL_PROXY?.trim() || process.env.HTTPS_PROXY?.trim() || process.env.HTTP_PROXY?.trim();
+  if (outbound) console.log(`   outbound proxy: ${redactUrlForLog(outbound)}`);
 }
 
 /** Test seam for `proxy: "auto"`: the registry reader and platform are injectable. */
@@ -123,6 +130,7 @@ export function applyProxyEnvWith(
   let proxy = typeof rawProxy === "string" ? resolveEnvValue(rawProxy) : undefined;
   if (!proxy) {
     if (rawProxy !== undefined) warnProxyConfigDiscardOnce("proxy");
+    configureSocks5Fetch();
     return;
   }
   if (proxy.trim().toLowerCase() === "auto") {
@@ -151,8 +159,18 @@ export function applyProxyEnvWith(
     }
   }
   if (proxy) {
-  if (!process.env.HTTP_PROXY?.trim() && !process.env.http_proxy?.trim()) process.env.HTTP_PROXY = proxy;
-  if (!process.env.HTTPS_PROXY?.trim() && !process.env.https_proxy?.trim()) process.env.HTTPS_PROXY = proxy;
+    if (/^socks/i.test(proxy.trim()) && !/^socks5h?:\/\//i.test(proxy.trim())) {
+      throw new Error("Only SOCKS5 proxy URLs are supported; use socks5://host:port");
+    }
+    if (/^socks5h?:\/\//i.test(proxy.trim())) {
+      for (const key of ["HTTP_PROXY", "HTTPS_PROXY", "http_proxy", "https_proxy", "ALL_PROXY", "all_proxy"] as const) {
+        delete process.env[key];
+      }
+      process.env.ALL_PROXY = proxy;
+    } else {
+      if (!process.env.HTTP_PROXY?.trim() && !process.env.http_proxy?.trim()) process.env.HTTP_PROXY = proxy;
+      if (!process.env.HTTPS_PROXY?.trim() && !process.env.https_proxy?.trim()) process.env.HTTPS_PROXY = proxy;
+    }
   }
   const existing = process.env.NO_PROXY ?? process.env.no_proxy ?? "";
   const entries = existing.split(",").map(s => s.trim()).filter(Boolean);
@@ -184,5 +202,5 @@ export function applyProxyEnvWith(
     }
   }
   process.env.NO_PROXY = entries.join(",");
+  configureSocks5Fetch();
 }
-