@bitkyc08/opencodex 2.76.0 → 2.78.0-preview.20261005

package/src/cli/update-restart-child.ts

@@ -0,0 +1,81 @@
+import { existsSync } from "node:fs";
+import { getRuntimePortPath, readRuntimePort } from "../config/process-state";
+import { packageVersion } from "../lib/package-version";
+import { parseStrictSemver } from "../lib/strict-semver";
+import { acquireOwnershipMutationLease, OWNERSHIP_MUTATION_LEASE_TOKEN_ENV } from "../service/ownership-mutation-lease.mjs";
+import { serviceStatePaths } from "../service/state";
+import { assertUpdateRestartConfiguration, assertUpdateRestartHome, type UpdateRestartHome } from "./update-restart-home";
+
+export const UPDATE_RESTART_CHILD_ENV = "OCX_UPDATE_RESTART_CHILD";
+export interface UpdateRestartChildMarker { home: UpdateRestartHome; version: string; port: number; hostname: string; deadlineAt: number }
+export interface UpdateRestartChildGuard { check(port?: number, hostname?: string): void; complete(): void }
+
+function parseMarker(raw: string): UpdateRestartChildMarker {
+  if (raw.length > 8192) throw new Error("update_restart_child_marker_invalid");
+  const value = JSON.parse(raw) as UpdateRestartChildMarker;
+  if (!value || !Number.isSafeInteger(value.deadlineAt) || !Number.isInteger(value.port)
+    || typeof value.hostname !== "string" || value.port < 1 || value.port > 65535 || typeof value.version !== "string"
+    || value.version === "0.0.0" || !parseStrictSemver(value.version) || !value.home
+    || !Number.isSafeInteger(value.home.revision)) throw new Error("update_restart_child_marker_invalid");
+  for (const directory of [value.home.config, value.home.codex]) {
+    if (!directory || typeof directory.path !== "string" || !directory.path
+      || !Number.isSafeInteger(directory.dev) || !Number.isSafeInteger(directory.ino)) {
+      throw new Error("update_restart_child_marker_invalid");
+    }
+  }
+  return value;
+}
+
+export interface UpdateRestartChildIo {
+  env?: NodeJS.ProcessEnv;
+  now?: () => number;
+  version?: () => string;
+  checkHome?: (home: UpdateRestartHome) => void;
+  acquire?: (waitMs: number) => { release(): void };
+  onExit?: (release: () => void) => void;
+  checkState?: (marker: UpdateRestartChildMarker) => void;
+  armDeadline?: (remainingMs: number) => () => void;
+}
+
+/** Admit the replacement before CLI preflight; custody belongs to this child PID. */
+export function admitUpdateRestartChild(argv: string[], io: UpdateRestartChildIo = {}): UpdateRestartChildGuard | undefined {
+  const env = io.env ?? process.env;
+  const raw = env[UPDATE_RESTART_CHILD_ENV];
+  if (raw === undefined) return undefined;
+  delete env[UPDATE_RESTART_CHILD_ENV];
+  delete env[OWNERSHIP_MUTATION_LEASE_TOKEN_ENV];
+  const marker = parseMarker(raw);
+  if (argv.length !== 3 || argv[0] !== "start" || argv[1] !== "--port" || argv[2] !== String(marker.port)) {
+    throw new Error("update_restart_child_command_changed");
+  }
+  const now = io.now ?? Date.now;
+  const check = (port = marker.port, hostname = marker.hostname) => {
+    if (now() >= marker.deadlineAt) throw new Error("update_restart_deadline_expired");
+    const bindHost = (host: string) => !host.trim() || /^localhost\.?$/i.test(host.trim()) ? "127.0.0.1" : host.trim();
+    if (port !== marker.port || bindHost(hostname) !== bindHost(marker.hostname) || (io.version ?? packageVersion)() !== marker.version) throw new Error("update_restart_child_identity_changed");
+    (io.checkHome ?? assertUpdateRestartHome)(marker.home);
+    (io.checkState ?? (expected => {
+      assertUpdateRestartConfiguration(expected.hostname);
+      const current = readRuntimePort();
+      if (existsSync(getRuntimePortPath()) && (!current || current.pid !== process.pid
+        || current.port !== expected.port || current.siblingOfPort !== undefined)) {
+        throw new Error("update_restart_competing_runtime");
+      }
+    }))(marker);
+  };
+  check();
+  const lease = (io.acquire ?? (waitMs => acquireOwnershipMutationLease(serviceStatePaths(), { waitMs })))(Math.min(2000, marker.deadlineAt - now()));
+  let released = false;
+  let cancelDeadline: (() => void) | undefined;
+  const release = () => { if (!released) { released = true; cancelDeadline?.(); lease.release(); } };
+  try {
+    check();
+    cancelDeadline = (io.armDeadline ?? (remainingMs => {
+      const timer = setTimeout(() => process.exit(1), remainingMs);
+      timer.unref();
+      return () => clearTimeout(timer);
+    }))(marker.deadlineAt - now());
+    (io.onExit ?? (callback => { process.once("exit", callback); }))(release);
+    return { check, complete: () => { check(); release(); } };
+  } catch (error) { release(); throw error; }
+}

package/src/cli/update-restart-home.ts

@@ -0,0 +1,38 @@
+import { realpathSync, statSync } from "node:fs";
+import { readClientConnectionState } from "../client/state";
+import { readConfigDiagnostics } from "../config/diagnostics";
+import { getConfigDir } from "../config/paths";
+import { currentCodexHome, resolveServiceOwnership, resolveServiceState } from "../service/state";
+
+export interface UpdateRestartHome {
+  config: { path: string; dev: number; ino: number };
+  codex: { path: string; dev: number; ino: number };
+  revision: number;
+}
+
+function physicalDirectory(path: string): UpdateRestartHome["config"] {
+  const canonical = realpathSync.native(path);
+  const stat = statSync(canonical);
+  if (!stat.isDirectory()) throw new Error("update_restart_home_unverified");
+  return { path: canonical, dev: stat.dev, ino: stat.ino };
+}
+
+/** Only an unclaimed standalone home is eligible for this narrow update path. */
+export function readUpdateRestartHome(): UpdateRestartHome {
+  const state = resolveServiceState();
+  const owner = resolveServiceOwnership();
+  if (state.kind !== "none" || owner.kind !== "none") throw new Error("update_restart_owner_unverified");
+  return { config: physicalDirectory(getConfigDir()), codex: physicalDirectory(currentCodexHome()), revision: owner.revision };
+}
+
+export function assertUpdateRestartHome(expected: UpdateRestartHome): void {
+  const current = readUpdateRestartHome();
+  if (JSON.stringify(current) !== JSON.stringify(expected)) throw new Error("update_restart_home_changed");
+}
+
+/** Read-only eligibility shared by parent pre-stop and child admission. */
+export function assertUpdateRestartConfiguration(hostname: string): void {
+  const diagnostics = readConfigDiagnostics();
+  if (readClientConnectionState().kind !== "disconnected" || diagnostics.error
+    || (diagnostics.config.hostname ?? "") !== hostname) throw new Error("update_restart_configuration_changed");
+}

package/src/cli/update-restart-transport.ts

@@ -0,0 +1,193 @@
+import { Agent, request, type ClientRequest, type IncomingMessage } from "node:http";
+import { connect, type Socket } from "node:net";
+import type { Duplex } from "node:stream";
+import {
+  LOCAL_ATTESTATION_CHALLENGE_HEADER,
+  LOCAL_ATTESTATION_PROOF_HEADER,
+  createLocalAttestationChallenge,
+  isLocalAttestationSecret,
+  verifyLocalAttestationProof,
+} from "../lib/local-management-attestation";
+import { SYSTEM_RESTART_CAPABILITY_VERSION } from "../lib/system-restart-contract";
+import { isOpencodexHealthz, probeHostname, type LiveProxy } from "../server/proxy-liveness";
+import { computeVersionSkew } from "./version-skew";
+
+const FAILURE = "update_restart_stop_failed";
+const MAX_RESPONSE_BYTES = 64 * 1024;
+
+/** This agent owns exactly one direct TCP connection, including on Bun's HTTP layer. */
+class AttestedAgent extends Agent {
+  socket?: Socket;
+  private connected = false;
+
+  constructor(private readonly hostname: string, private readonly port: number) {
+    super({ keepAlive: true, maxSockets: 1, maxTotalSockets: 1, maxFreeSockets: 1 });
+  }
+
+  override createConnection(
+    _options: unknown,
+    callback?: (error: Error | null, stream: Duplex) => void,
+  ): Socket | undefined {
+    if (this.connected) {
+      // Returning no socket with an error also refuses queued reconnect attempts.
+      callback?.(new Error(FAILURE), this.socket!);
+      return undefined;
+    }
+    this.connected = true;
+    this.socket = connect({ host: this.hostname, port: this.port, autoSelectFamily: false });
+    return this.socket;
+  }
+}
+
+function checkDeadline(deadlineAt: number): void {
+  if (!Number.isFinite(deadlineAt) || Date.now() >= deadlineAt) throw new Error(FAILURE);
+}
+
+function readJson(response: IncomingMessage): Promise<Record<string, unknown>> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let size = 0;
+    const fail = () => { reject(new Error(FAILURE)); response.destroy(); };
+    response.on("error", fail);
+    response.on("aborted", fail);
+    response.on("data", (chunk: Buffer) => {
+      size += chunk.length;
+      if (size > MAX_RESPONSE_BYTES) { fail(); return; }
+      chunks.push(chunk);
+    });
+    response.on("end", () => {
+      try {
+        const value: unknown = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        if (!response.complete || value === null || typeof value !== "object" || Array.isArray(value)) {
+          throw new Error(FAILURE);
+        }
+        resolve(value as Record<string, unknown>);
+      } catch { reject(new Error(FAILURE)); }
+    });
+  });
+}
+
+type AttestedTarget = { target: LiveProxy & { pid: number }; secret: string; deadlineAt: number };
+type JsonReply = { response: IncomingMessage; body: Record<string, unknown> };
+
+class AttestedSession {
+  readonly agent: AttestedAgent;
+  readonly challenge = createLocalAttestationChallenge();
+  private readonly hostname: string;
+  private readonly timer: ReturnType<typeof setTimeout>;
+  private current?: ClientRequest;
+
+  constructor(private readonly options: AttestedTarget) {
+    const { target, secret, deadlineAt } = options;
+    checkDeadline(deadlineAt);
+    if (target.source !== "runtime" || target.role !== undefined || target.packageTreeFenced
+      || !Number.isSafeInteger(target.pid) || target.pid <= 0
+      || !Number.isInteger(target.port) || target.port < 1 || target.port > 65535
+      || !isLocalAttestationSecret(secret)) throw new Error(FAILURE);
+    const host = probeHostname(target.hostname);
+    this.hostname = host.startsWith("[") ? host.slice(1, -1) : host;
+    this.agent = new AttestedAgent(this.hostname, target.port);
+    this.timer = setTimeout(() => {
+      this.current?.destroy(new Error(FAILURE));
+      this.agent.socket?.destroy(new Error(FAILURE));
+    }, Math.min(deadlineAt - Date.now(), 2_147_483_647));
+  }
+
+  exchange(adminToken?: string): Promise<JsonReply> {
+    const stop = adminToken !== undefined;
+    return new Promise((resolve, reject) => {
+      const req = request({
+        hostname: this.hostname, port: this.options.target.port, agent: this.agent,
+        method: stop ? "POST" : "GET", path: stop ? "/api/stop" : "/healthz",
+        maxHeaderSize: MAX_RESPONSE_BYTES,
+        headers: stop ? { "content-length": "0" } : { [LOCAL_ATTESTATION_CHALLENGE_HEADER]: this.challenge },
+      });
+      this.current = req;
+      req.on("error", reject);
+      req.on("response", response => {
+        readJson(response).then(body => resolve({ response, body }), reject);
+      });
+      req.once("socket", (socket: Socket) => {
+        try {
+          checkDeadline(this.options.deadlineAt);
+          if (socket !== this.agent.socket || socket.destroyed || !socket.writable
+            || (stop && (socket.connecting || socket.readableEnded || socket.writableEnded))) {
+            throw new Error(FAILURE);
+          }
+          // No end/flushHeaders/write, or credential header, before this socket check.
+          if (adminToken !== undefined) req.setHeader("X-OpenCodex-API-Key", adminToken);
+          req.end();
+        } catch { req.destroy(new Error(FAILURE)); }
+      });
+    });
+  }
+
+  validateHealth(health: JsonReply): void {
+    const { target, secret, deadlineAt } = this.options;
+    const proof = health.response.headers[LOCAL_ATTESTATION_PROOF_HEADER];
+    checkDeadline(deadlineAt);
+    if (health.response.statusCode !== 200 || !isOpencodexHealthz(health.body)
+      || health.body.status !== "ok" || health.body.role !== undefined
+      || health.body.pid !== target.pid || health.body.port !== target.port
+      || !verifyLocalAttestationProof(secret, this.challenge, target.pid, target.port, typeof proof === "string" ? proof : null)) {
+      throw new Error(FAILURE);
+    }
+  }
+
+  close(): void {
+    clearTimeout(this.timer);
+    this.current?.destroy();
+    this.agent.destroy();
+    this.agent.socket?.destroy();
+  }
+}
+
+/** Proof and credential delivery must remain on one established channel; never retry. */
+export async function stopAttestedUpdateTarget(options: AttestedTarget & {
+  cliVersion: string;
+  beforeStop: () => void;
+  adminToken: string;
+}): Promise<void> {
+  let session: AttestedSession | undefined;
+  try {
+    const { cliVersion, deadlineAt, beforeStop, adminToken } = options;
+    if (!adminToken) throw new Error(FAILURE);
+    session = new AttestedSession(options);
+    const health = await session.exchange();
+    session.validateHealth(health);
+    if (health.body.restartCapability !== SYSTEM_RESTART_CAPABILITY_VERSION
+      || computeVersionSkew(cliVersion, typeof health.body.version === "string" ? health.body.version : undefined).relation !== "cli-newer"
+      || /\bclose\b/i.test(health.response.headers.connection ?? "")) throw new Error(FAILURE);
+    checkDeadline(deadlineAt);
+    beforeStop();
+    // Synchronous candidate revalidation and POST enqueue: no intervening await.
+    const stopped = await session.exchange(adminToken);
+    checkDeadline(deadlineAt);
+    if (stopped.response.statusCode !== 200 || stopped.body.success !== true
+      || stopped.body.sharedTeardown !== "performed") throw new Error(FAILURE);
+  } catch {
+    // Never expose parser/network/callback errors (which may contain credentials).
+    throw new Error(FAILURE);
+  } finally {
+    session?.close();
+  }
+}
+
+/** Observe only the caller's exact newly started runtime; ordinary liveness is not proof. */
+export async function observeAttestedUpdateReplacement(options: AttestedTarget & {
+  version: string;
+}): Promise<LiveProxy> {
+  let session: AttestedSession | undefined;
+  try {
+    session = new AttestedSession(options);
+    const health = await session.exchange();
+    session.validateHealth(health);
+    if (health.body.version !== options.version) throw new Error(FAILURE);
+    return { pid: options.target.pid, port: options.target.port, hostname: options.target.hostname,
+      source: "runtime", version: options.version };
+  } catch {
+    throw new Error("update_restart_replacement_observation_failed");
+  } finally {
+    session?.close();
+  }
+}

package/src/cli/update-restart.ts

@@ -0,0 +1,260 @@
+import { execFileSync, spawn } from "node:child_process";
+import { isIP } from "node:net";
+import { existsSync } from "node:fs";
+import { getRuntimePortPath, readRuntimePort, readProcessCommandLine, isOcxStartCommandLine, type RuntimePortState } from "../config/process-state";
+import { configuredAdminToken } from "../lib/admin-secrets";
+import { isRealBunBinary } from "../lib/bun-binary-validator.mjs";
+import { isProcessAlive } from "../lib/process-control";
+import { parseStrictSemver } from "../lib/strict-semver";
+import { startArgv } from "../lib/self-launch-argv";
+import { diagnoseService } from "../service/diagnostics";
+import { inspectGuardedManagerTarget } from "../service/guarded-manager-target";
+import { acquireOwnershipMutationLease, unprivilegedOwnershipMutationEnvironment } from "../service/ownership-mutation-lease.mjs";
+import { serviceStatePaths } from "../service/state";
+import { findLiveProxy, probeEndpointLiveness, probeHostname, type LiveProxy } from "../server/proxy-liveness";
+import { waitForPortAvailable } from "../server/ports";
+import { UPDATE_RESTART_CHILD_ENV, type UpdateRestartChildMarker } from "./update-restart-child";
+import { assertUpdateRestartConfiguration, assertUpdateRestartHome, readUpdateRestartHome, type UpdateRestartHome } from "./update-restart-home";
+import { observeAttestedUpdateReplacement, stopAttestedUpdateTarget } from "./update-restart-transport";
+import type { UpdateRestartCandidate } from "./update-restart-candidate";
+import { INCOMPLETE_INSTALL_RECOVERY } from "./restart-failure";
+import { computeVersionSkew } from "./version-skew";
+
+export interface UpdateRestartChild { pid?: number; exitCode: number | null; signalCode: string | null }
+export interface UpdateRestartIo {
+  now(): number;
+  acquire(): { release(): void };
+  home(): UpdateRestartHome;
+  checkHome(home: UpdateRestartHome): void;
+  runtime(): RuntimePortState | null;
+  standalone(target: UpdateRestartCandidate["target"]): boolean;
+  /** Whether the executable the replacement will run is complete (not the npm `bun` placeholder). */
+  runtimeReady(): boolean;
+  stop(candidate: UpdateRestartCandidate, deadlineAt: number, beforeStop: () => void): Promise<void>;
+  stopped(candidate: UpdateRestartCandidate, deadlineAt: number): Promise<boolean>;
+  start(marker: UpdateRestartChildMarker): UpdateRestartChild;
+  observe(deadlineAt: number, childPid: number): Promise<LiveProxy | null>;
+  wait(ms: number): Promise<void>;
+}
+const ELIGIBILITY_REASONS = ["windows", "unsupported_platform", "foreground", "service", "shared_or_client",
+  "package_tree_fenced", "unverifiable_ancestry", "target_changed", "configuration_changed"] as const;
+export type UpdateRestartEligibilityReason = (typeof ELIGIBILITY_REASONS)[number];
+
+/** Carries only a closed reason code across the eligibility/transport boundary. */
+export class UpdateRestartEligibilityError extends Error {
+  constructor(readonly reason: UpdateRestartEligibilityReason) { super("Update restart eligibility refused"); }
+}
+export type UpdateRestartResult = { ok: true; live: LiveProxy }
+  | { ok: false; code: string; reason?: UpdateRestartEligibilityReason };
+
+function sameRuntime(candidate: UpdateRestartCandidate, current: RuntimePortState | null): boolean {
+  const expected = candidate.runtime;
+  return !!current && current.pid === expected.pid && current.port === expected.port
+    && current.hostname === expected.hostname && current.attestationSecret === expected.attestationSecret
+    && current.siblingOfPort === undefined;
+}
+
+/** A terminal update transaction: it never enters generic restart recovery. */
+export async function runUpdateRestart(candidate: UpdateRestartCandidate, deadlineAt: number, io: UpdateRestartIo): Promise<UpdateRestartResult> {
+  let phase = "eligibility";
+  let lease: { release(): void } | undefined;
+  // Recorded here because the stop transport sanitizes anything thrown by beforeStop.
+  let runtimeRefused = false;
+  let eligibilityReason: UpdateRestartEligibilityReason | undefined;
+  try {
+    if (!parseStrictSemver(candidate.cliVersion) || candidate.cliVersion === "0.0.0"
+      || computeVersionSkew(candidate.cliVersion, candidate.target.version).relation !== "cli-newer") {
+      throw new Error("version");
+    }
+    const withinDeadline = () => { if (io.now() >= deadlineAt) throw new Error("deadline"); };
+    withinDeadline();
+    lease = io.acquire();
+    const home = candidate.home;
+    if (JSON.stringify(io.home()) !== JSON.stringify(home)) throw new Error("home_changed");
+    const revalidate = () => {
+      withinDeadline();
+      io.checkHome(home);
+      const currentRuntime = io.runtime();
+      if (!sameRuntime(candidate, currentRuntime)) {
+        eligibilityReason = currentRuntime?.siblingOfPort !== undefined ? "shared_or_client" : "target_changed";
+        throw new Error("target");
+      }
+      try {
+        if (!io.standalone(candidate.target)) throw new Error("target");
+      } catch (error) {
+        if (error instanceof UpdateRestartEligibilityError && ELIGIBILITY_REASONS.includes(error.reason)) eligibilityReason = error.reason;
+        throw error;
+      }
+      if (!io.runtimeReady()) {
+        runtimeRefused = true;
+        throw new Error("runtime");
+      }
+      withinDeadline();
+    };
+    revalidate();
+    phase = "stop";
+    await io.stop(candidate, deadlineAt, revalidate);
+    withinDeadline();
+    phase = "settle";
+    if (!await io.stopped(candidate, deadlineAt)) throw new Error("stop_unconfirmed");
+    // Shutdown is confirmed from here on and nothing has launched yet.
+    phase = "prelaunch";
+    withinDeadline();
+    io.checkHome(home);
+    // An in-place npm install can still be swapping its Bun in; wait for it inside the deadline,
+    // then repeat the launch preconditions synchronously so the wait opens no gap before spawn.
+    phase = "runtime";
+    while (!io.runtimeReady()) {
+      withinDeadline();
+      await io.wait(Math.min(100, deadlineAt - io.now()));
+    }
+    phase = "prelaunch";
+    withinDeadline();
+    io.checkHome(home);
+    phase = "start";
+    const child = io.start({ home, version: candidate.cliVersion, port: candidate.target.port, hostname: candidate.runtime.hostname ?? "", deadlineAt });
+    // The child must acquire its own lease and validate this frozen handoff before preflight.
+    lease.release();
+    lease = undefined;
+    if (!Number.isSafeInteger(child.pid) || !child.pid || child.pid === candidate.target.pid) throw new Error("launch_unknown");
+    phase = "replacement";
+    while (io.now() < deadlineAt) {
+      if (child.exitCode !== null || child.signalCode !== null) throw new Error("child_exited");
+      io.checkHome(home);
+      const live = await io.observe(deadlineAt, child.pid);
+      withinDeadline();
+      if (live) {
+        io.checkHome(home);
+        if (live.source !== "runtime" || live.pid !== child.pid || live.port !== candidate.target.port
+          || (live.hostname ?? "") !== (candidate.target.hostname ?? "") || live.role === "client"
+          || live.packageTreeFenced || live.version !== candidate.cliVersion) throw new Error("replacement_mismatch");
+        return { ok: true, live };
+      }
+      await io.wait(Math.min(100, deadlineAt - io.now()));
+    }
+    throw new Error("deadline");
+  } catch {
+    return { ok: false, code: runtimeRefused ? "update_restart_runtime_incomplete" : `update_restart_${phase}_failed`,
+      ...(eligibilityReason ? { reason: eligibilityReason } : {}) };
+  }
+  finally { lease?.release(); }
+}
+
+/** Sanitized, actionable text for each terminal update-restart code; it claims only what that phase proved. */
+export function describeUpdateRestartFailure(code: string, reason?: UpdateRestartEligibilityReason): string {
+  if (reason && (code === "update_restart_eligibility_failed" || code === "update_restart_stop_failed")) {
+    const action = (() => {
+      switch (reason) {
+        case "windows": return "Restart from a newer CLI is unavailable on Windows. Run `ocx status`, then restart through the owning service or desktop app.";
+        case "unsupported_platform": return "Restart from a newer CLI requires macOS or Linux. Run `ocx status`, then use the owning lifecycle manager.";
+        case "service": return "An installed or active service owns lifecycle control. Run `ocx status`, then use the owning installation's `ocx service restart`.";
+        case "foreground": return "The proxy is attached to a parent process. Run `ocx status`; if it runs in a terminal, restart it in that terminal, otherwise use its owning app or supervisor.";
+        case "shared_or_client": return "This is a shared or connected-client runtime. Run `ocx status` and restart through its owning Hub, service or desktop app.";
+        case "package_tree_fenced": return `The proxy's package files are unsettled. Wait for the install to finish. ${INCOMPLETE_INSTALL_RECOVERY}`;
+        case "unverifiable_ancestry": return "The proxy's process ancestry or manager could not be verified. Run `ocx status` to identify its owner before restarting.";
+        case "configuration_changed": return "The selected configuration or connection changed. Run `ocx status` to inspect the intended proxy before restarting.";
+        case "target_changed": return "The captured proxy identity changed. Run `ocx status` to inspect the intended proxy before restarting.";
+      }
+    })();
+    return `${action} Nothing was stopped by this restart attempt.`;
+  }
+  switch (code) {
+    case "update_restart_runtime_incomplete":
+      return `This installation's Bun runtime is incomplete; nothing was stopped. Wait for the install to finish, then run \`ocx restart\` again. ${INCOMPLETE_INSTALL_RECOVERY}`;
+    case "update_restart_eligibility_failed":
+      return "The running proxy is not eligible for an update restart from this CLI (it is supervised, shared, or changed); nothing was stopped. Run `ocx status` to inspect the intended proxy.";
+    case "update_restart_stop_failed":
+      return "The guarded stop of the old proxy could not be confirmed; inspect `ocx status` before retrying.";
+    case "update_restart_settle_failed":
+      return "The old proxy was not confirmed stopped, so no second proxy was started; inspect `ocx status` before retrying.";
+    case "update_restart_prelaunch_failed":
+      return "The old proxy stopped, but its home, ownership or deadline changed before launch, so nothing was launched. Check `ocx status`; if no proxy is running, run `ocx start`.";
+    case "update_restart_runtime_failed":
+      return `The old proxy stopped, but this installation's Bun runtime did not finish installing in time, so nothing was launched. ${INCOMPLETE_INSTALL_RECOVERY} Run \`ocx status\`; if no proxy is running, run \`ocx start\` once the install completes.`;
+    case "update_restart_start_failed":
+      return "The old proxy stopped, but the new proxy's launch could not be confirmed. Check `ocx status`; if no proxy is running, run `ocx start`.";
+    case "update_restart_replacement_failed":
+      return "The new proxy did not verify as the expected replacement in time; inspect `ocx status` before retrying.";
+    default:
+      return "Update restart could not be confirmed; inspect `ocx status` before retrying.";
+  }
+}
+
+function standalone(target: UpdateRestartCandidate["target"]): boolean {
+  try { assertUpdateRestartConfiguration(target.hostname ?? ""); }
+  catch { throw new UpdateRestartEligibilityError("configuration_changed"); }
+  if (process.platform !== "darwin" && process.platform !== "linux") {
+    throw new UpdateRestartEligibilityError(process.platform === "win32" ? "windows" : "unsupported_platform");
+  }
+  const host = probeHostname(target.hostname).replace(/^\[|\]$/g, "");
+  if (target.role === "client") throw new UpdateRestartEligibilityError("shared_or_client");
+  if (target.packageTreeFenced) throw new UpdateRestartEligibilityError("package_tree_fenced");
+  if (!isIP(host) || target.source !== "runtime") throw new UpdateRestartEligibilityError("unverifiable_ancestry");
+  const command = readProcessCommandLine(target.pid);
+  if (!command || !isOcxStartCommandLine(command)) throw new UpdateRestartEligibilityError("unverifiable_ancestry");
+  if (diagnoseService().installed) throw new UpdateRestartEligibilityError("service");
+  const manager = inspectGuardedManagerTarget(target.pid, target.port);
+  if (manager.kind !== "absent") throw new UpdateRestartEligibilityError(manager.kind === "bound" ? "service" : "unverifiable_ancestry");
+  let parent: string;
+  try {
+    parent = execFileSync("ps", ["-o", "ppid=", "-p", String(target.pid)], {
+      encoding: "utf8", timeout: 1000, stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch { throw new UpdateRestartEligibilityError("unverifiable_ancestry"); }
+  if (!/^[1-9]\d*$/.test(parent)) throw new UpdateRestartEligibilityError("unverifiable_ancestry");
+  if (parent !== "1") throw new UpdateRestartEligibilityError("foreground");
+  return true;
+}
+
+/** Production composition keeps stop/start side effects out of cli/index.ts. */
+export function restartFromCurrentInstallation(candidate: UpdateRestartCandidate, deadlineAt: number, environment: NodeJS.ProcessEnv): Promise<UpdateRestartResult> {
+  const argv = startArgv(candidate.target.port);
+  const executable = process.execPath;
+  return runUpdateRestart(candidate, deadlineAt, {
+    now: Date.now,
+    acquire: () => acquireOwnershipMutationLease(serviceStatePaths(), { waitMs: Math.max(0, Math.min(2000, deadlineAt - Date.now())) }),
+    home: readUpdateRestartHome, checkHome: assertUpdateRestartHome, runtime: readRuntimePort, standalone,
+    runtimeReady: () => isRealBunBinary(executable),
+    stop: async (target, deadline, beforeStop) => {
+      const token = configuredAdminToken();
+      if (!token) throw new Error("update_restart_credential_unavailable");
+      await stopAttestedUpdateTarget({ target: target.target, secret: target.runtime.attestationSecret,
+        cliVersion: target.cliVersion, deadlineAt: deadline, beforeStop, adminToken: token });
+    },
+    stopped: async (target, deadline) => {
+      while (Date.now() < deadline && isProcessAlive(target.target.pid)) await Bun.sleep(Math.min(100, deadline - Date.now()));
+      if (Date.now() >= deadline || existsSync(getRuntimePortPath())) return false;
+      const endpoint = { port: target.target.port, hostname: target.target.hostname };
+      if (!await waitForPortAvailable(endpoint.port, probeHostname(endpoint.hostname),
+        { timeoutMs: Math.max(0, Math.min(1000, deadline - Date.now())), intervalMs: 50 })) return false;
+      if (Date.now() >= deadline) return false;
+      return await probeEndpointLiveness(endpoint, { timeoutMs: Math.min(250, deadline - Date.now()) }) === "dead";
+    },
+    start: marker => {
+      const env = unprivilegedOwnershipMutationEnvironment(environment);
+      env.OPENCODEX_HOME = marker.home.config.path;
+      env.CODEX_HOME = marker.home.codex.path;
+      env[UPDATE_RESTART_CHILD_ENV] = JSON.stringify(marker);
+      const child = spawn(executable, argv, { detached: true, stdio: "ignore", windowsHide: true, env });
+      child.on("error", () => {}); // exit/health evidence reports failure; never retry a possibly launched child.
+      child.unref();
+      return child;
+    },
+    observe: async (deadline, childPid) => {
+      const live = await findLiveProxy({ deadlineAt: deadline, attempts: 1 });
+      if (!live) return null;
+      if (live.pid !== childPid) throw new Error("update_restart_replacement_changed");
+      const runtime = readRuntimePort(childPid);
+      if (!runtime?.attestationSecret || runtime.port !== candidate.target.port
+        || runtime.hostname !== candidate.runtime.hostname || runtime.siblingOfPort !== undefined) {
+        throw new Error("update_restart_replacement_unattested");
+      }
+      const attested = await observeAttestedUpdateReplacement({ target: { ...live, pid: childPid },
+        secret: runtime.attestationSecret, version: candidate.cliVersion, deadlineAt: deadline });
+      const current = readRuntimePort(childPid);
+      if (JSON.stringify(current) !== JSON.stringify(runtime)) throw new Error("update_restart_replacement_changed");
+      return attested;
+    },
+    wait: ms => Bun.sleep(ms),
+  });
+}

package/src/cli/usage-model-search.ts

@@ -0,0 +1,58 @@
+/** Model-row display search; server attribution and report totals stay unchanged. */
+import { CliUsageError } from "./runtime-api";
+
+export interface UsageModelView {
+  query: string;
+  matchedModelCount: number;
+  returnedModelCount: number;
+  limit: 100;
+  truncated: boolean;
+}
+
+interface SearchableModel {
+  model: string;
+  provider: string;
+  resolvedModel?: string;
+  requests: number;
+  totalTokens: number;
+  estimatedCostUsd?: number;
+  [key: string]: unknown;
+}
+
+/** Unlike exact attribution flags, an explicit empty search is a valid view. */
+export function takeUsageSearchOption(args: string[]): string | undefined {
+  const indices = args.flatMap((arg, index) => arg === "--search" || arg.startsWith("--search=") ? [index] : []);
+  if (indices.length > 1) throw new CliUsageError("--search was given more than once");
+  const index = indices[0];
+  if (index === undefined) return undefined;
+  const arg = args[index]!;
+  if (arg.startsWith("--search=")) {
+    args.splice(index, 1);
+    return arg.slice("--search=".length);
+  }
+  const value = args[index + 1];
+  if (value === undefined || value.startsWith("--")) throw new CliUsageError("--search requires a value; use --search= for an empty search");
+  args.splice(index, 2);
+  return value;
+}
+
+export function selectUsageModelView<T extends { models?: unknown }>(report: T, rawQuery: string): Omit<T, "models"> & { models: SearchableModel[]; modelView: UsageModelView } {
+  if (!report || !Array.isArray(report.models)) throw new Error("Invalid usage model rows; retry after checking the runtime.");
+  const models = report.models.map((raw: unknown): SearchableModel => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("Invalid usage model row.");
+    const row = raw as Record<string, unknown>;
+    if (typeof row.model !== "string" || typeof row.provider !== "string"
+      || (row.resolvedModel !== undefined && typeof row.resolvedModel !== "string")
+      || ![row.requests, row.totalTokens].every(value => typeof value === "number" && Number.isFinite(value) && value >= 0)
+      || (row.estimatedCostUsd !== undefined && (typeof row.estimatedCostUsd !== "number" || !Number.isFinite(row.estimatedCostUsd)))) {
+      throw new Error("Invalid usage model row.");
+    }
+    return row as SearchableModel;
+  });
+  const query = rawQuery.trim().toLowerCase();
+  const matching = models.toSorted((a, b) => b.totalTokens - a.totalTokens).filter(row => !query
+    || row.model.toLowerCase().includes(query) || row.provider.toLowerCase().includes(query)
+    || (row.resolvedModel ?? "").toLowerCase().includes(query));
+  const selected = matching.slice(0, 100);
+  return { ...report, models: selected, modelView: { query, matchedModelCount: matching.length, returnedModelCount: selected.length, limit: 100, truncated: matching.length > selected.length } };
+}