@iislee/opencodex 2.11.0 → 2.35.0

package/src/lib/bounded-body.ts

@@ -7,10 +7,24 @@ export const BOUNDED_BODY_TIMEOUT_MS = 5_000;
 export interface BoundedBodyOptions {
 	/** Abort the read with this signal. Its reason is rethrown by identity. */
 	signal?: AbortSignal;
+	/**
+	 * Reject the returned promise with TypeError on malformed or truncated UTF-8
+	 * instead of replacing invalid bytes, including during timeout-path flushes.
+	 * Reader cancellation and lock release still run. Defaults to false.
+	 */
+	fatalUtf8?: boolean;
+	/**
+	 * Byte ceiling for retained body data. Defaults to BOUNDED_BODY_MAX_BYTES (64 KiB),
+	 * which suits error bodies; callers materializing whole success payloads (e.g. a
+	 * non-streaming upstream JSON completion) pass a larger explicit budget.
+	 */
+	maxBytes?: number;
 	/** Total wall-clock deadline. Exposed for focused tests. */
 	totalTimeoutMs?: number;
 	/** Deadline between non-empty raw chunks. Exposed for focused tests. */
 	inactivityTimeoutMs?: number;
+	/** Deadline for the first non-empty raw chunk. Defaults to inactivityTimeoutMs. */
+	firstByteTimeoutMs?: number;
 }
 
 export interface BoundedBodyResult {
@@ -30,9 +44,42 @@ export interface BoundedBodyResult {
 	displaySafe: boolean;
 }
 
+export interface BoundedBytesOptions {
+	/** Abort the read with this signal. Its reason is rethrown by identity. */
+	signal?: AbortSignal;
+	/** Maximum number of raw bytes retained from the response body. */
+	maxBytes: number;
+}
+
+export interface BoundedBytesResult {
+	/**
+	 * Exact raw bytes retained from the response. Empty when the cap was exceeded.
+	 *
+	 * This is a view over internal storage, so `bytes.buffer.byteLength` can exceed
+	 * `bytes.byteLength`. Consumers must honor the view's byteOffset and byteLength
+	 * instead of reading or transferring the backing buffer directly.
+	 */
+	bytes: Uint8Array<ArrayBuffer>;
+	/** True when the body was observed to exceed the byte cap. */
+	oversized: boolean;
+}
+
 const TOTAL_TIMEOUT = Symbol("bounded body total timeout");
 const INACTIVITY_TIMEOUT = Symbol("bounded body inactivity timeout");
 
+/**
+ * Test-only instrumentation: how many times the retained buffer was reallocated
+ * during the most recent read. The accumulator grows geometrically, so this is
+ * logarithmic in the body size and independent of how many chunks the peer sends.
+ * The per-chunk array it replaced retained one object per chunk instead, which a
+ * fragmenting peer can inflate far past the payload ceiling — a property no
+ * correctness assertion can see, which is why it is observable here.
+ */
+let bufferGrowthsForTests = 0;
+export function boundedBodyBufferGrowthsForTests(): number {
+	return bufferGrowthsForTests;
+}
+
 function timeoutPromise(ms: number, value: symbol): { promise: Promise<symbol>; clear: () => void } {
 	let timer: ReturnType<typeof setTimeout> | undefined;
 	const promise = new Promise<symbol>((resolve) => {
@@ -56,8 +103,102 @@ function cancelWithoutWaiting(reader: ReadableStreamDefaultReader<Uint8Array>, r
 	}
 }
 
-function decodeUtf8(chunks: readonly Uint8Array[]): string {
-	const decoder = new TextDecoder();
+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.
+ *
+ * The caller owns any wall-clock deadline through `signal`, which lets one budget
+ * cover both response headers and body consumption. No decoding, cloning, or teeing
+ * occurs, so arbitrary upstream bytes remain unchanged.
+ */
+export async function readBoundedResponseBytes(
+	response: Response,
+	options: BoundedBytesOptions,
+): Promise<BoundedBytesResult> {
+	const signal = options.signal;
+	if (signal?.aborted) throw signal.reason;
+
+	const body = response.body;
+	if (!body) return { bytes: new Uint8Array(0), oversized: false };
+
+	const reader = body.getReader();
+	const maxBytes = options.maxBytes;
+	let retained = new Uint8Array(Math.min(maxBytes, 64 * 1024));
+	let retainedBytes = 0;
+	let mustCancel = false;
+	let cancelReason: unknown;
+
+	let rejectForAbort: ((reason: unknown) => void) | undefined;
+	const aborted = new Promise<never>((_resolve, reject) => {
+		rejectForAbort = reject;
+	});
+	const onAbort = () => rejectForAbort?.(signal?.reason);
+	signal?.addEventListener("abort", onAbort, { once: true });
+	// Close the narrow race between the preflight check and listener install.
+	if (signal?.aborted) onAbort();
+
+	try {
+		while (true) {
+			const read = reader.read();
+			// Observe a late read rejection when abort/cancellation wins the race.
+			void read.catch(() => undefined);
+			const outcome = await Promise.race([read, aborted]);
+			if (signal?.aborted) {
+				mustCancel = true;
+				cancelReason = signal.reason;
+				throw signal.reason;
+			}
+
+			const { value, done } = outcome;
+			if (done) {
+				return { bytes: retained.subarray(0, retainedBytes), oversized: false };
+			}
+			if (!value || value.byteLength === 0) continue;
+
+			if (value.byteLength > maxBytes - retainedBytes) {
+				mustCancel = true;
+				cancelReason = new DOMException("Response body size limit reached", "QuotaExceededError");
+				retained = new Uint8Array(0);
+				retainedBytes = 0;
+				return { bytes: retained, oversized: true };
+			}
+
+			if (retainedBytes + value.byteLength > retained.length) {
+				const grown = new Uint8Array(
+					Math.min(maxBytes, Math.max(retained.length * 2, retainedBytes + value.byteLength)),
+				);
+				grown.set(retained.subarray(0, retainedBytes));
+				retained = grown;
+			}
+			retained.set(value, retainedBytes);
+			retainedBytes += value.byteLength;
+		}
+	} catch (error) {
+		mustCancel = true;
+		cancelReason = error;
+		throw error;
+	} finally {
+		signal?.removeEventListener("abort", onAbort);
+		if (mustCancel) cancelWithoutWaiting(reader, cancelReason);
+		try {
+			reader.releaseLock();
+		} catch {
+			// A pending read can keep the lock briefly while cancel settles.
+		}
+	}
+}
+
+function decodeUtf8(chunks: readonly Uint8Array[], fatal: boolean): string {
+	const decoder = new TextDecoder("utf-8", { fatal });
 	let text = "";
 	for (const chunk of chunks) text += decoder.decode(chunk, { stream: true });
 	// Flush an incomplete trailing UTF-8 sequence deterministically.
@@ -77,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: "",
@@ -93,13 +236,18 @@ export async function readBoundedResponseBody(
 	}
 
 	const reader = body.getReader();
-	const chunks: Uint8Array[] = [];
+	const maxBytes = options.maxBytes ?? BOUNDED_BODY_MAX_BYTES;
+	// Geometrically growing single buffer: per-chunk arrays would retain one object per
+	// transport chunk, which a hostile peer could inflate into metadata amplification far
+	// beyond the payload ceiling on large budgets.
+	let retained = new Uint8Array(Math.min(maxBytes, 64 * 1024));
 	let retainedBytes = 0;
+	bufferGrowthsForTests = 0;
 	let mustCancel = false;
 	let cancelReason: unknown;
 	const total = timeoutPromise(options.totalTimeoutMs ?? BOUNDED_BODY_TIMEOUT_MS, TOTAL_TIMEOUT);
 	let inactivity = timeoutPromise(
-		options.inactivityTimeoutMs ?? BOUNDED_BODY_TIMEOUT_MS,
+		options.firstByteTimeoutMs ?? options.inactivityTimeoutMs ?? BOUNDED_BODY_TIMEOUT_MS,
 		INACTIVITY_TIMEOUT,
 	);
 
@@ -134,7 +282,7 @@ export async function readBoundedResponseBody(
 					"TimeoutError",
 				);
 				return {
-					text: decodeUtf8(chunks),
+					text: decodeUtf8([retained.subarray(0, retainedBytes)], options.fatalUtf8 === true),
 					truncated: true,
 					timedOut: true,
 					totalTimedOut: outcome === TOTAL_TIMEOUT,
@@ -147,7 +295,7 @@ export async function readBoundedResponseBody(
 			const { value, done } = outcome as ReadableStreamReadResult<Uint8Array>;
 			if (done) {
 				return {
-					text: decodeUtf8(chunks),
+					text: decodeUtf8([retained.subarray(0, retainedBytes)], options.fatalUtf8 === true),
 					truncated: false,
 					timedOut: false,
 					totalTimedOut: false,
@@ -165,10 +313,10 @@ export async function readBoundedResponseBody(
 				INACTIVITY_TIMEOUT,
 			);
 
-			if (value.byteLength > BOUNDED_BODY_MAX_BYTES - retainedBytes) {
+			if (value.byteLength > maxBytes - retainedBytes) {
 				mustCancel = true;
 				cancelReason = new DOMException("Error body size limit reached", "QuotaExceededError");
-				chunks.length = 0;
+				retained = new Uint8Array(0);
 				retainedBytes = 0;
 				return {
 					text: "",
@@ -181,7 +329,15 @@ export async function readBoundedResponseBody(
 				};
 			}
 
-			chunks.push(value);
+			if (retainedBytes + value.byteLength > retained.length) {
+				const grown = new Uint8Array(
+					Math.min(maxBytes, Math.max(retained.length * 2, retainedBytes + value.byteLength)),
+				);
+				grown.set(retained.subarray(0, retainedBytes));
+				retained = grown;
+				bufferGrowthsForTests += 1;
+			}
+			retained.set(value, retainedBytes);
 			retainedBytes += value.byteLength;
 		}
 	} catch (error) {

package/src/lib/bun-runtime.ts

@@ -11,7 +11,8 @@
  * back to `process.execPath` (which is itself Bun when run via `bun src/cli/index.ts`).
  */
 import { createRequire } from "node:module";
-import { dirname, join, resolve } from "node:path";
+import { realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { isRealBunBinary } from "./bun-binary-validator.mjs";
 
 export { isRealBunBinary };
@@ -20,12 +21,124 @@ const require = createRequire(import.meta.url);
 
 const BUN_OVERRIDE_ENV = "OPENCODEX_BUN_PATH";
 
+/**
+ * Env marker stamped by whichever launcher selected the Bun binary, then read back
+ * inside the launched process.
+ *
+ * Provenance has to travel with the launch because it cannot be recovered afterwards:
+ * resolving it at report time answers "what would this shell pick now", not "what was
+ * this service started with", and those differ exactly when the answer matters.
+ */
+export const BUN_RUNTIME_SOURCE_ENV = "OCX_BUN_RUNTIME_SOURCE";
+
+/**
+ * The binary the marker was minted for. Stamped beside the source so a reader can tell
+ * whether a marker still describes the process holding it, without re-deriving the
+ * selection from an environment that may no longer contain it.
+ */
+export const BUN_RUNTIME_PATH_ENV = "OCX_BUN_RUNTIME_PATH";
+
+export type BunRuntimeSource = "override" | "bundled" | "process";
+
+/** The only provenance values any surface may accept off the wire or out of the env. */
+export const BUN_RUNTIME_SOURCES: readonly BunRuntimeSource[] = ["override", "bundled", "process"];
+
 export type DurableBunRuntime = {
   path: string;
-  source: "override" | "bundled" | "process";
+  source: BunRuntimeSource;
   overrideEnv: typeof BUN_OVERRIDE_ENV;
 };
 
+/**
+ * The provenance this process was launched with, or `undefined` when nothing
+ * trustworthy is recorded.
+ *
+ * Deliberately never falls back to `durableBunRuntime()`. A service installed before
+ * the marker existed has no provenance, and guessing one from the current environment
+ * would report a confident wrong answer — "unknown" is the honest result and callers
+ * are expected to say so. Values outside the allowlist are treated as absent rather
+ * than passed through.
+ */
+export function reportedBunRuntimeSource(
+  env: NodeJS.ProcessEnv = process.env,
+): BunRuntimeSource | undefined {
+  const raw = env[BUN_RUNTIME_SOURCE_ENV]?.trim();
+  const source = BUN_RUNTIME_SOURCES.find(candidate => candidate === raw);
+  if (!source) return undefined;
+  // Source and binary are a PAIR: without a recorded path that names THIS
+  // executable, the marker describes some other launch and must not be
+  // reported (a bare OCX_BUN_RUNTIME_SOURCE inherited from an unrelated
+  // parent would otherwise claim a confident wrong origin).
+  const recordedPath = env[BUN_RUNTIME_PATH_ENV]?.trim();
+  if (!recordedPath || !samePath(recordedPath, process.execPath)) return undefined;
+  return source;
+}
+
+/** Env pair a launcher stamps for the binary it just selected. */
+export function bunRuntimeProvenanceEnv(runtime: DurableBunRuntime): Record<string, string> {
+  return { [BUN_RUNTIME_SOURCE_ENV]: runtime.source, [BUN_RUNTIME_PATH_ENV]: runtime.path };
+}
+
+/**
+ * Child environment for a proxy started with `process.execPath` — the runtime this
+ * process is already using.
+ *
+ * These launchers re-exec the current runtime rather than resolving a binary, so the
+ * provenance to report is whatever launched THIS process. Without this the marker would
+ * be silently dropped on `ocx ensure`, GUI start, restart, and update-relaunch, and the
+ * service would report an unknown origin it actually knows.
+ *
+ * An inherited marker is carried forward only when the binary it was minted for is the
+ * one about to be re-executed. Inheritance travels down a process tree, so a marker can
+ * outlive its binary — something started under a marked process but running a different
+ * Bun would otherwise relaunch the daemon with a provenance contradicting the binary
+ * actually serving it. The check compares the recorded path rather than re-deriving the
+ * selection, because a service installed with a shell-local override keeps neither that
+ * shell nor its `OPENCODEX_BUN_PATH`, and re-deriving would demote a correct `override`
+ * to `process` on its first relaunch.
+ */
+export function withProcessRuntimeProvenance(
+  env: NodeJS.ProcessEnv,
+): NodeJS.ProcessEnv {
+  return { ...env, ...bunRuntimeProvenanceEnv(currentRuntimeProvenance(env)) };
+}
+
+/**
+ * Provenance for `process.execPath`: the inherited claim when it was minted for this
+ * exact executable, otherwise what this executable actually is.
+ */
+function currentRuntimeProvenance(env: NodeJS.ProcessEnv): DurableBunRuntime {
+  const recorded = recordedCurrentRuntime(env);
+  if (recorded) return recorded;
+  // No marker that describes this binary: report what is running. One resolution
+  // supplies both halves so the pair can never disagree.
+  const runtime = unmarkedDurableBunRuntime();
+  return samePath(runtime.path, process.execPath)
+    ? runtime
+    : { path: process.execPath, source: "process", overrideEnv: BUN_OVERRIDE_ENV };
+}
+
+function recordedCurrentRuntime(env: NodeJS.ProcessEnv): DurableBunRuntime | null {
+  const source = reportedBunRuntimeSource(env);
+  const path = env[BUN_RUNTIME_PATH_ENV]?.trim();
+  if (!source || !path || !samePath(path, process.execPath)) return null;
+  return { path, source, overrideEnv: BUN_OVERRIDE_ENV };
+}
+
+/**
+ * Same file, allowing for the aliases a path can pick up between launch and relaunch:
+ * symlinks/junctions, mapped drives, and Windows case differences. Falls back to a
+ * lexical comparison when a path cannot be resolved (it may be gone).
+ */
+function samePath(left: string, right: string): boolean {
+  const canonical = (value: string): string => {
+    let resolved = value;
+    try { resolved = realpathSync(value); } catch { /* keep the literal path */ }
+    return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+  };
+  return canonical(left) === canonical(right);
+}
+
 /**
  * Absolute path to the bundled Bun binary, or null if the `bun` dependency is
  * not installed/resolvable (or only the un-downloaded placeholder is present).
@@ -45,21 +158,21 @@ export function bundledBunPath(): string | null {
   }
 }
 
-export function overrideBunPath(): string | null {
-  const value = process.env[BUN_OVERRIDE_ENV]?.trim();
-  if (!value) return null;
-  const resolved = resolve(value);
-  return isRealBunBinary(resolved) ? resolved : null;
-}
-
-export function durableBunRuntime(): DurableBunRuntime {
-  const override = overrideBunPath();
-  if (override) return { path: override, source: "override", overrideEnv: BUN_OVERRIDE_ENV };
+function unmarkedDurableBunRuntime(): DurableBunRuntime {
   const bundled = bundledBunPath();
   if (bundled) return { path: bundled, source: "bundled", overrideEnv: BUN_OVERRIDE_ENV };
   return { path: process.execPath, source: "process", overrideEnv: BUN_OVERRIDE_ENV };
 }
 
+export function durableBunRuntime(): DurableBunRuntime {
+  // A durable artifact must use the runtime selected BEFORE Bun auto-loaded a
+  // project dotenv. The Node launcher and owned service/shim launchers stamp the
+  // selected source/path pair; it is accepted only when it names this exact
+  // running executable. Re-reading OPENCODEX_BUN_PATH here would let a project
+  // `.env` persist an arbitrary executable into a shim or service.
+  return recordedCurrentRuntime(process.env) ?? unmarkedDurableBunRuntime();
+}
+
 /**
  * Bun path to bake into durable artifacts (launchd/systemd/Task Scheduler and
  * the Codex auto-start shim). Prefer the bundled binary — it lives under the

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

@@ -3,13 +3,14 @@
  *
  * The eager bounded relay (src/server/relay-eager.ts) uses a JS async producer
  * loop — the exact shape of the Bun#32111 use-after-free (fixed upstream by Bun
- * PR #32120, merged 2026-06-21). No RELEASED Bun version is proven to carry
- * that fix yet, so `MIN_FIXED_BUN_VERSION` is null: every runtime is
- * "known-bad" until a bundle-bump commit sets it. Windows no-rewrite traffic
- * follows this runtime/config decision. Darwin no-rewrite traffic stays on tee
+ * PR #32120, merged 2026-06-21). Bun 1.4.0 is the first RELEASED version proven
+ * to carry that fix, so `MIN_FIXED_BUN_VERSION` is "1.4.0": older runtimes stay
+ * "known-bad". Windows no-rewrite traffic
+ * follows this runtime/config decision, preserving the explicit legacy-tee
+ * safety pin. Darwin no-rewrite traffic stays on tee
  * for `auto` regardless of runtime capability and reaches eager relay only via
  * explicit `streamMode: "eager-relay"` opt-in (see
- * devlog/_plan/260731_macos_rss_retention/100_darwin_eager_optin.md).
+ * devlog/_fin/260731_macos_rss_retention/100_darwin_eager_optin.md).
  *
  * Prerelease conservatism: a version carrying a prerelease suffix (e.g.
  * `1.4.0-canary.3`) is NEVER treated as fixed even when its numeric triple
@@ -20,8 +21,11 @@
 /**
  * Bump in the SAME commit that bumps package.json's bundled Bun to a version
  * verified to include Bun PR #32120. null = no released version is known-fixed.
+ * Bun 1.4.0 (npm stable, bundled by this package.json) carries the fix: PR
+ * #32120 merged 2026-06-21, well before the 1.4.0 cut, and the full suite ran
+ * green under the 1.4 line on every supported OS (devlog/260814_bun14-preview-dev).
  */
-export const MIN_FIXED_BUN_VERSION: string | null = null;
+export const MIN_FIXED_BUN_VERSION: string | null = "1.4.0";
 
 export type StreamMode = "auto" | "legacy-tee" | "eager-relay";
 
@@ -93,7 +97,7 @@ export function decideEagerRelay(
  * Windows preserves the decision for no-rewrite traffic. Darwin permits only
  * explicit config opt-in; `auto` remains tee even on a future fixed runtime.
  * Returns the normalized effective decision, or null when platform policy,
- * rewrite needs, or a Darwin non-config-eager mode selects tee.
+ * Windows rewrite needs, or a Darwin non-config-eager mode selects tee.
  */
 export function selectEagerPath(
   platform: NodeJS.Platform,
@@ -102,12 +106,12 @@ export function selectEagerPath(
   version: string = Bun.version,
   minFixed: string | null = MIN_FIXED_BUN_VERSION,
 ): EagerRelayDecision | null {
-  if (needsClientRewrite || (platform !== "win32" && platform !== "darwin")) {
+  if (platform !== "win32" && platform !== "darwin") {
     return null;
   }
 
   const decision = decideEagerRelay(mode, version, minFixed);
-  if (platform === "win32") return decision;
+  if (platform === "win32") return needsClientRewrite ? null : decision;
   return decision.reason === "config-eager" ? decision : null;
 }
 

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

@@ -0,0 +1,120 @@
+/**
+ * Contract for the dashboard-driven Codex app-server restart (#1046 follow-up).
+ *
+ * Distinct from `system-restart-contract.ts`: that one restarts THIS proxy process
+ * and needs a pid-bound capability because it kills its own listener. This one asks
+ * matching Codex app-server children to exit so Codex rereads the catalog on next
+ * launch. It never touches the proxy and never spawns a replacement — whoever owns
+ * the app-server (the Codex app, an SSH bootstrap) relaunches it on next use.
+ *
+ * Scalar-only payload. A command line can contain a home directory and a username,
+ * and an OS error message often embeds a path, so neither crosses this boundary.
+ *
+ * Design and audit history: `devlog/_fin/260815_gui_codex_restart/`.
+ */
+
+export const CODEX_RESTART_METHOD = "POST";
+export const CODEX_RESTART_PATH = "/api/system/codex-restart";
+export const CODEX_APP_SERVER_STATE_PATH = "/api/system/codex-app-server";
+
+/** Mirrors CodexAppServerCatalogState so the GUI never imports runtime code. */
+export type CodexAppServerState = "fresh" | "stale" | "not_running" | "unknown";
+
+export type CodexRestartCode =
+  | "stopped"
+  | "nothing_running"
+  | "enumeration_unavailable"
+  | "partially_stopped";
+
+/** GET response: a cheap reading with no side effects. It never signals. */
+export interface CodexAppServerStateResponse {
+  state: CodexAppServerState;
+  runningCount: number;
+}
+
+/** POST response. All four arrays are pid lists — never command lines. */
+export interface CodexRestartResponse {
+  success: boolean;
+  /** Classifier reading taken BEFORE any signal, so the UI can explain why it acted. */
+  stateBefore: CodexAppServerState;
+  /** Whether a catalog or cache write happened during this request. */
+  synced: boolean;
+  requested: number[];
+  stopped: number[];
+  surviving: number[];
+  failed: number[];
+  code: CodexRestartCode;
+}
+
+const APP_SERVER_STATES: readonly string[] = ["fresh", "stale", "not_running", "unknown"];
+const RESTART_CODES: readonly string[] = [
+  "stopped",
+  "nothing_running",
+  "enumeration_unavailable",
+  "partially_stopped",
+];
+
+/**
+ * A pid is a positive safe integer. Accepting a float or a negative number would
+ * let a malformed body reach UI code that renders counts and indexes lengths.
+ */
+function isPidList(value: unknown): value is number[] {
+  return Array.isArray(value)
+    && value.every(entry => typeof entry === "number" && Number.isSafeInteger(entry) && entry > 0);
+}
+
+/**
+ * Runtime guard for GUI consumers: a 2xx body is not automatically this shape.
+ *
+ * Structure is not enough. A body can be structurally valid and still contradict
+ * itself — `code: "stopped"` alongside surviving pids, or `success: true` with a
+ * failure code — and a caller that trusts it reports a success that did not happen.
+ * A version-skewed or regressed proxy is exactly how that arrives, so the
+ * cross-field invariants are checked here rather than assumed.
+ */
+export function isCodexRestartResponse(value: unknown): value is CodexRestartResponse {
+  if (typeof value !== "object" || value === null) return false;
+  const view = value as Record<string, unknown>;
+  const structural = typeof view.success === "boolean"
+    && typeof view.synced === "boolean"
+    && typeof view.stateBefore === "string"
+    && APP_SERVER_STATES.includes(view.stateBefore)
+    && typeof view.code === "string"
+    && RESTART_CODES.includes(view.code)
+    && isPidList(view.requested)
+    && isPidList(view.stopped)
+    && isPidList(view.surviving)
+    && isPidList(view.failed);
+  if (!structural) return false;
+
+  const success = view.success as boolean;
+  const code = view.code as CodexRestartCode;
+  const surviving = view.surviving as number[];
+  const failed = view.failed as number[];
+  const stopped = view.stopped as number[];
+
+  // `success` and `code` must agree: only partially_stopped is an unsuccessful code.
+  if (success !== (code !== "partially_stopped")) return false;
+  // A clean outcome cannot leave anything behind.
+  if (success && (surviving.length > 0 || failed.length > 0)) return false;
+  // An unsuccessful outcome must name what survived.
+  if (!success && surviving.length === 0 && failed.length === 0) return false;
+  // Nothing can be reported stopped when the service says nothing was running.
+  if ((code === "nothing_running" || code === "enumeration_unavailable") && stopped.length > 0) {
+    return false;
+  }
+  return true;
+}
+
+export function isCodexAppServerStateResponse(
+  value: unknown,
+): value is CodexAppServerStateResponse {
+  if (typeof value !== "object" || value === null) return false;
+  const view = value as Record<string, unknown>;
+  return typeof view.state === "string"
+    && APP_SERVER_STATES.includes(view.state)
+    && typeof view.runningCount === "number"
+    && Number.isSafeInteger(view.runningCount)
+    && view.runningCount >= 0;
+}
+

package/src/lib/config-ownership.ts

@@ -5,7 +5,6 @@ import {
   readFileSync,
   readdirSync,
   realpathSync,
-  renameSync,
   rmdirSync,
   unlinkSync,
   writeFileSync,
@@ -13,6 +12,7 @@ import {
 import { randomUUID } from "node:crypto";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import type { GenerationContext } from "./state-store-sweeper";
+import { renameAtomicFile } from "./windows-atomic-replace";
 
 export const CONFIG_OWNER_FILE = ".opencodex-owner.json";
 export const CONFIG_UNINSTALL_MANIFEST = ".opencodex-uninstall.json";
@@ -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",
@@ -69,6 +70,7 @@ const INITIAL_OWNED_PATHS = [
   "service-state.json",
   "service.log",
   "system-env-port",
+  "thought-signature-replay.json",
   "tray-heartbeat.json",
   "tray-state.json",
   "update-job.json",
@@ -231,7 +233,10 @@ function writeManifest(configDir: string, manifest: ConfigUninstallManifest): vo
   const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
   writeFileSync(temp, `${JSON.stringify(manifest, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
   try {
-    renameSync(temp, path);
+    // Same Windows sharing-violation tolerance the config writer has: a
+    // scanner holding the manifest must not turn uninstall bookkeeping into a
+    // hard failure.
+    renameAtomicFile(temp, path, undefined, "config-ownership");
   } catch (error) {
     try { unlinkSync(temp); } catch { /* best effort */ }
     throw error;
@@ -329,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));