@bitkyc08/opencodex 2.60.0 → 2.61.0-preview.20260922

package/src/cli/resolve.ts

@@ -0,0 +1,230 @@
+/**
+ * `ocx resolve` — the machine-readable runtime resolution surface for an embedding shell.
+ *
+ * D5 of devlog/_plan/260921_app_runtime_ownership/: the desktop shell must stop resolving
+ * the config home, the port and liveness itself. The tuned probe budgets in
+ * src/server/proxy-liveness.ts exist because a shell-side reimplementation answered
+ * "nobody listening" twice and started duplicate proxies; this verb exposes that module's
+ * verdict instead of copying it, alongside src/config/paths.ts (the home) and the CLI's
+ * own preferred-port selection (`config.port ?? 10100` — resolve takes no --port).
+ *
+ * Contract:
+ *  - `--json` puts exactly ONE JSON document on stdout, versioned by `schema`; the
+ *    default prints two human lines, the same opt-in split as `ocx ready --json`.
+ *  - liveness has three answers, not two: "live", "absent-proven" (every recorded and
+ *    configured endpoint definitively refused or answered non-opencodex), and unknown.
+ *    Unknown NEVER reaches the wire as absent — a probe that timed out, a listener that
+ *    withheld /healthz, or an identity mismatch exits 1 instead. Only "absent-proven"
+ *    may authorise starting a new runtime.
+ *  - exit 0 whenever a trustworthy verdict exists — live, or proven absent. A MISSING
+ *    config.json is defaults, not an error.
+ *  - exit 1 when the CLI cannot resolve: an invalid config.json must NOT be answered
+ *    with `loadConfig`'s repair-to-defaults behaviour, because that hands the caller
+ *    a guessed port; and unknown liveness must not be answered as absence.
+ *  - exit 64 for any argument, pre-parsed in src/cli/root.ts before preflight side
+ *    effects, mirroring `ocx ready`. The verb is read-only and listed in
+ *    skipsCodexShimAutoRestore, so a lookup made to populate a consent surface never
+ *    triggers a shim repair side effect.
+ *
+ * Discovery uses the START_OWNERSHIP_LIVENESS budget, not the 750ms single-shot default:
+ * the shell's launch decision keys on this verdict, and answering "nobody" for a slow
+ * live proxy is the duplicate-proxy decision the start path tunes against (#5004).
+ *
+ * Lives outside cli/index.ts (which dispatches argv at module top level) so tests can
+ * import it, the same split as ready.ts.
+ */
+import { readConfigDiagnostics, type ConfigDiagnostics } from "../config";
+import { getConfigDir } from "../config/paths";
+import { readRuntimePort } from "../config/process-state";
+import { packageVersion } from "../lib/package-version";
+import {
+  findLiveProxy,
+  probeEndpointLiveness,
+  START_OWNERSHIP_LIVENESS,
+  type EndpointLiveness,
+  type LiveProxy,
+} from "../server/proxy-liveness";
+import { endpointsToProve, everyEndpointProvenDownAsync, type ProbeEndpoint } from "./uninstall-plan";
+
+/** Wire version of the resolve document. Bump only on an incompatible shape change. */
+export const RESOLVE_SCHEMA = "ocx-resolve/1";
+
+/** The port every preferred-port selection in the CLI falls back to. */
+export const RESOLVE_DEFAULT_PORT = 10100;
+
+export interface ResolveLivenessJson {
+  /**
+   * "live" when the identity-checked probe found our proxy; "absent-proven" when every
+   * recorded and configured endpoint is definitively dead. The third state — unknown —
+   * exits 1 before this document is printed, so it never appears on the wire as absence.
+   */
+  status: "live" | "absent-proven";
+  pid: number | null;
+  port: number | null;
+  /** Raw bind hostname that answered; compose probe URLs via probeHostname semantics. */
+  hostname?: string;
+  /** Where the verdict came from: the runtime record, or the configured listen port. */
+  source: LiveProxy["source"] | null;
+  /** Version the live proxy reported on /healthz, when it reported one. */
+  version?: string;
+  /** Listener role the live proxy reported, when it reported one ("client" = connected client). */
+  role?: string;
+}
+
+export interface ResolveJson {
+  schema: typeof RESOLVE_SCHEMA;
+  /** Version of this CLI binary, so a shell can compare its engine against the live proxy. */
+  cliVersion: string;
+  /** Resolved opencodex home (OPENCODEX_HOME or ~/.opencodex), from src/config/paths.ts. */
+  configHome: string;
+  port: {
+    /** The port a client should use: the live listener's port when one answers, else the configured one. */
+    effective: number;
+    /** The configured listen port (config.port ?? 10100); what a start would prefer. */
+    configured: number;
+    /** Whether `effective` came from a live proxy or from configuration. */
+    source: LiveProxy["source"];
+  };
+  liveness: ResolveLivenessJson;
+}
+
+export interface ResolveArgs {
+  json: boolean;
+}
+
+export type ResolveParseResult = { ok: true; args: ResolveArgs } | { ok: false; code: 64 };
+
+/** Pure argument parser: the only flag is `--json`. */
+export function parseResolveArgs(argv: string[]): ResolveParseResult {
+  for (const flag of argv) {
+    if (flag !== "--json") return { ok: false, code: 64 };
+  }
+  return { ok: true, args: { json: argv.includes("--json") } };
+}
+
+export interface ResolveIo {
+  configDir?: () => string;
+  readDiagnostics?: () => ConfigDiagnostics;
+  findLive?: () => Promise<LiveProxy | null>;
+  /** Runtime-port record reader; production default is readRuntimePort. */
+  readRuntime?: () => { port?: number; hostname?: string } | null;
+  /** Tri-state endpoint probe; production default runs in-process for compiled standalone binaries. */
+  probeEndpoint?: (endpoint: ProbeEndpoint) => EndpointLiveness | Promise<EndpointLiveness>;
+  cliVersion?: () => string;
+  stdout?: { log: (s: string) => void };
+  stderr?: { error: (s: string) => void };
+}
+
+function livenessJson(live: LiveProxy | null): ResolveLivenessJson {
+  // Reaching here with null means absence was PROVEN by the caller (unknown exits 1
+  // before this document is built).
+  if (!live) return { status: "absent-proven", pid: null, port: null, source: null };
+  return {
+    status: "live",
+    pid: live.pid,
+    port: live.port,
+    source: live.source,
+    ...(live.hostname === undefined ? {} : { hostname: live.hostname }),
+    ...(live.version === undefined ? {} : { version: live.version }),
+    ...(live.role === undefined ? {} : { role: live.role }),
+  };
+}
+
+/** Pure shaper: one live verdict plus configuration becomes the wire document. */
+export function buildResolveJson(
+  config: { port?: number },
+  live: LiveProxy | null,
+  configHome: string,
+  cliVersion: string,
+): ResolveJson {
+  const configured = config.port ?? RESOLVE_DEFAULT_PORT;
+  return {
+    schema: RESOLVE_SCHEMA,
+    cliVersion,
+    configHome,
+    port: {
+      effective: live ? live.port : configured,
+      configured,
+      source: live ? live.source : "config",
+    },
+    liveness: livenessJson(live),
+  };
+}
+
+/**
+ * Human form: two lines, no prose flourish — an operator skims it, a shell uses --json.
+ */
+function reportHuman(json: ResolveJson, stdout: { log: (s: string) => void }): void {
+  stdout.log(`Config home: ${json.configHome}`);
+  const live = json.liveness;
+  if (live.status === "live") {
+    const pidText = live.pid === null ? "unknown" : String(live.pid);
+    const versionText = live.version ?? "unknown version";
+    stdout.log(`Proxy live on port ${json.port.effective} (PID ${pidText}, ${versionText}); effective port ${json.port.effective}.`);
+  } else {
+    stdout.log(`No live proxy (absence proven); effective port ${json.port.effective} (configured).`);
+  }
+}
+
+/**
+ * Run `ocx resolve` over injected I/O. Returns the exit code. The production defaults
+ * read config through the diagnostics surface (which distinguishes missing, valid and
+ * invalid instead of repairing to defaults) and perform one identity-checked discovery
+ * at the ownership-safe budget — resolve adds no probing policy of its own.
+ */
+export async function runResolve(args: ResolveArgs, io: ResolveIo = {}): Promise<number> {
+  const stdout = io.stdout ?? console;
+  const stderr = io.stderr ?? console;
+  const configDir = io.configDir ?? getConfigDir;
+  const readDiagnostics = io.readDiagnostics ?? readConfigDiagnostics;
+  const findLive = io.findLive ?? (() => findLiveProxy(START_OWNERSHIP_LIVENESS));
+  const readRuntime = io.readRuntime ?? readRuntimePort;
+  const probeEndpoint = io.probeEndpoint ?? probeEndpointLiveness;
+  const cliVersion = io.cliVersion ?? packageVersion;
+  const configHome = configDir();
+  let diagnostics: ConfigDiagnostics;
+  try {
+    diagnostics = readDiagnostics();
+  } catch (error) {
+    // A resolution that could not run must not read as "no proxy": the caller has to
+    // refuse to guess (D5) rather than treat this as a proven-absent verdict.
+    stderr.error(`resolve failed: ${error instanceof Error ? error.message : String(error)}`);
+    return 1;
+  }
+  if (diagnostics.source === "fallback") {
+    // An invalid config must not resolve to defaults: the effective port would be a
+    // guess at 10100 while the operator's config.port is unread. The repair-to-defaults
+    // policy in loadConfig is for interactive recovery, not for a shell contract.
+    stderr.error(`resolve failed: the config in ${configHome} is invalid (${diagnostics.error ?? "unknown error"}); refusing to guess.`);
+    return 1;
+  }
+  let live: LiveProxy | null;
+  try {
+    live = await findLive();
+  } catch (error) {
+    stderr.error(`resolve failed: ${error instanceof Error ? error.message : String(error)}`);
+    return 1;
+  }
+  if (!live) {
+    // findLiveProxy collapses "definitely nothing" and "could not tell" into the same
+    // null. The launch decision keys on this verdict, so resolve owes the caller the
+    // tri-state answer the updater already enforces: only EVERY candidate definitively
+    // dead is absence. Anything else is unknown, and unknown exits 1 — it must never
+    // authorise starting a second runtime.
+    let provenDown = false;
+    try {
+      provenDown = await everyEndpointProvenDownAsync(endpointsToProve(readRuntime(), diagnostics.config), probeEndpoint);
+    } catch {
+      // A probe that cannot run is not evidence of absence.
+      provenDown = false;
+    }
+    if (!provenDown) {
+      stderr.error("resolve: liveness is unknown (a probe timed out or a listener withheld /healthz); refusing to treat unknown as absent.");
+      return 1;
+    }
+  }
+  const json = buildResolveJson(diagnostics.config, live, configHome, cliVersion());
+  if (args.json) stdout.log(JSON.stringify(json));
+  else reportHuman(json, stdout);
+  return 0;
+}

package/src/cli/root.ts

@@ -10,16 +10,19 @@
  */
 import { hasHelpFlag, printSubcommandUsage, printUsage, printVersion } from "./help";
 import { parseReadyArgs, type ReadyArgs } from "./ready";
+import { parseResolveArgs, type ResolveArgs } from "./resolve";
 import { maybeAutoRestoreCodexShim } from "./codex-shim-autorestore";
 
 export interface CliHead {
-  kind: "version" | "help" | "ready" | "command";
+  kind: "version" | "help" | "ready" | "resolve" | "command";
   command: string | undefined;
   args: string[];
   /** For kind "help": the subcommand whose usage should print, if any. */
   helpTarget?: string;
   /** Present only for `ready`; undefined when the ready args failed to parse. */
   readyArgs?: ReadyArgs;
+  /** Present only for `resolve`; undefined when the resolve args failed to parse. */
+  resolveArgs?: ResolveArgs;
 }
 
 export function parseCliHead(argv: string[]): CliHead {
@@ -51,6 +54,13 @@ export function parseCliHead(argv: string[]): CliHead {
     if (!parsed.ok) return { kind: "ready", command, args, readyArgs: undefined };
     return { kind: "ready", command, args, readyArgs: parsed.args };
   }
+  // Same ordering contract as `ready`: `ocx resolve` rejects any argument with exit
+  // 64 BEFORE maybeAutoRestoreCodexShim (or any other preflight with side effects) runs.
+  if (command === "resolve") {
+    const parsed = parseResolveArgs(args.slice(1));
+    if (!parsed.ok) return { kind: "resolve", command, args, resolveArgs: undefined };
+    return { kind: "resolve", command, args, resolveArgs: parsed.args };
+  }
   return { kind: "command", command, args };
 }
 
@@ -79,6 +89,19 @@ export async function runCli(argv: string[]): Promise<CliHead> {
       maybeAutoRestoreCodexShim(head.command, head.args);
       return head;
     }
+    case "resolve": {
+      // Fail-closed impossible-state guard, mirroring ready: the pre-parse above already
+      // rejected invalid arguments before any preflight, so a missing resolveArgs means
+      // dispatch diverged. Refuse with code 64 and perform NO I/O.
+      if (!head.resolveArgs) {
+        console.error("Usage: ocx resolve [--json]");
+        console.error("  --json prints one JSON document: the config home, the effective port,");
+        console.error("  and the identity-checked liveness verdict.");
+        process.exit(64);
+      }
+      maybeAutoRestoreCodexShim(head.command, head.args);
+      return head;
+    }
     case "command":
       maybeAutoRestoreCodexShim(head.command, head.args);
       return head;

package/src/cli/start-ownership-publication.ts

@@ -0,0 +1,56 @@
+export interface StartOwnershipLease {
+  release(): void;
+}
+
+export class StartOwnershipRollbackUncertainError extends AggregateError {
+  constructor(errors: Iterable<unknown>) {
+    super(errors, "start listener rollback could not be proven complete");
+    this.name = "StartOwnershipRollbackUncertainError";
+  }
+}
+
+export interface StartOwnershipPublicationDeps<TBound> {
+  acquireLease(): StartOwnershipLease;
+  bind(): Promise<TBound>;
+  writePid(bound: TBound): void;
+  writeRuntime(bound: TBound): void;
+  stopBound(bound: TBound): void | Promise<void>;
+  removeRuntime(): void;
+  removePid(): void;
+}
+
+/** Bind and publish PID/runtime ownership as one lease-protected transaction. */
+export async function bindAndPublishStartOwnership<TBound>(
+  deps: StartOwnershipPublicationDeps<TBound>,
+): Promise<TBound> {
+  const lease = deps.acquireLease();
+  let bound: TBound;
+  let releaseLease = true;
+  try {
+    try { bound = await deps.bind(); }
+    catch (error) {
+      if (error instanceof StartOwnershipRollbackUncertainError) releaseLease = false;
+      throw error;
+    }
+    try {
+      deps.writePid(bound);
+      deps.writeRuntime(bound);
+    } catch (error) {
+      const failures: unknown[] = [error];
+      let stopFailed = false;
+      try { await deps.stopBound(bound); }
+      catch (failure) { stopFailed = true; failures.push(failure); }
+      try { deps.removeRuntime(); } catch (failure) { failures.push(failure); }
+      try { deps.removePid(); } catch (failure) { failures.push(failure); }
+      if (stopFailed) {
+        releaseLease = false;
+        throw new StartOwnershipRollbackUncertainError(failures);
+      }
+      if (failures.length > 1) throw new AggregateError(failures, "start ownership publication rollback failed");
+      throw error;
+    }
+    return bound;
+  } finally {
+    if (releaseLease) lease.release();
+  }
+}

package/src/cli/status-probes.ts

@@ -1,5 +1,5 @@
 import { readPidFileValue, readRuntimePort } from "../config/process-state";
-import { isOpencodexHealthz, probeHostname } from "../server/proxy-liveness";
+import { isConnectionRefused, isOpencodexHealthz, probeHostname } from "../server/proxy-liveness";
 import { directLocalHttpFetch } from "../server/direct-local-http";
 import { isProcessAlive } from "../lib/process-control";
 
@@ -26,23 +26,7 @@ export function proxyHealthFailureReason(error: unknown, signal: AbortSignal): "
     : "unreachable";
 }
 
-/**
- * "Nothing is listening" is narrower than "the probe failed". `unreachable` covers every
- * non-abort failure, including a socket that was ACCEPTED and then reset — which is what
- * an in-flight start looks like mid-bind. Only a connect-phase refusal proves the port is
- * free, so this reads the underlying errno instead of the display string.
- */
-export function isConnectionRefused(error: unknown): boolean {
-  for (let current: unknown = error, depth = 0; current instanceof Error && depth < 4; depth++) {
-    const code = (current as { code?: unknown }).code;
-    if (code === "ECONNREFUSED" || code === "ConnectionRefused") return true;
-    // Bun surfaces the refusal as a plain message on some platforms; the errno name is
-    // still the discriminator, not a substring of arbitrary prose.
-    if (typeof code === "string" && code.endsWith("ECONNREFUSED")) return true;
-    current = (current as { cause?: unknown }).cause;
-  }
-  return false;
-}
+export { isConnectionRefused } from "../server/proxy-liveness";
 
 /**
  * A proxy killed by a native trap or SIGKILL never runs the exit cleanup that removes

package/src/cli/status.ts

@@ -1,4 +1,5 @@
 import { durableBunRuntime } from "../lib/bun-runtime";
+import { existsSync, readFileSync } from "node:fs";
 import { codexAutoStartEnabled, getConfigPath, readConfigDiagnostics } from "../config";
 import { getPidPath, readPid, readRuntimePort, type RuntimePortState } from "../config/process-state";
 import { diagnoseCodexBundledPlugins, type CodexPluginsDiagnostic } from "../codex/plugins-doctor";
@@ -7,6 +8,8 @@ import type { OcxConfig } from "../types";
 import { diagnoseService, serviceLogPath } from "../service";
 import { collectStartupHealth, type StartupHealth } from "../codex/autostart-health";
 import { getCodexRoutingKind } from "../codex/inject";
+import { missingOwnedCatalogPath } from "../codex/inject/config-toml";
+import { CODEX_CONFIG_PATH } from "../codex/paths";
 import { diagnoseCodexShim } from "../codex/shim";
 import { displayCodexRuntimePath, effortClampAppliesToRuntime, liveRemovedEfforts, loadLastEffortClamp, resolveCodexRuntime } from "../codex/runtime";
 import { packageVersion } from "./help";
@@ -502,6 +505,65 @@ export function unusedProxyWarningLines(input: {
   ];
 }
 
+/**
+ * The mirror case: routing is ours and nothing is answering it.
+ *
+ * #5261: this state does not merely fail model calls. The root `openai_base_url` we inject
+ * is the base URL of Codex's own built-in openai provider, so with the proxy down a user can
+ * be stopped at Codex sign-in with no mention of opencodex anywhere on the screen. The
+ * injection is on disk and survives reboot, so it does not clear itself.
+ *
+ * The rest of the not-running report offers only ways to bring the proxy BACK, which is the
+ * wrong half of the choice for someone who wants their editor working again now. `ocx restore`
+ * needs no proxy, no management API and no network, so name it here — this report is the
+ * surface such a user is most likely to reach before the config file itself.
+ *
+ * Restricted to routing opencodex owns. `custom-local` is somebody else's gateway, and
+ * `ocx restore` would not remove it.
+ */
+export function deadProxyRoutingAdviceLines(input: {
+  proxyUp: boolean;
+  routingKind: StartupHealth["routingKind"];
+}): string[] {
+  if (input.proxyUp || input.routingKind !== "opencodex-local") return [];
+  return [
+    "Codex is still pointed at this proxy, so sign-in and model requests both fail while it is down.",
+    "To hand Codex back to its own account and endpoints without starting anything: ocx restore",
+  ];
+}
+
+/**
+ * Read the live Codex config and report an opencodex catalog pointer whose file is gone.
+ *
+ * Unreadable or absent config is reported as no finding rather than as a problem: this is a
+ * diagnostic line, and inventing one from missing evidence is worse than staying quiet.
+ */
+export function detectMissingCodexCatalogPath(): string | null {
+  try {
+    if (!existsSync(CODEX_CONFIG_PATH)) return null;
+    return missingOwnedCatalogPath(readFileSync(CODEX_CONFIG_PATH, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The one state in this report where Codex is broken independently of the proxy (#5261).
+ *
+ * A `model_catalog_json` naming a file that is gone stops Codex loading its configuration at
+ * all, so it presents as the same blank wall as dead routing while having a different cause and
+ * a different fix. Both are named, because restarting the proxy rewrites the catalog and
+ * restoring removes the pointer, and which one the user wants is their choice, not ours.
+ */
+export function missingCodexCatalogLines(missingCatalogPath: string | null): string[] {
+  if (!missingCatalogPath) return [];
+  return [
+    "⚠️  Codex is pointed at a model catalog that is no longer on disk, so Codex cannot load its config:",
+    `   ${missingCatalogPath}`,
+    "   Regenerate it with 'ocx start', or remove opencodex from Codex with 'ocx restore'.",
+  ];
+}
+
 export async function collectStatus(): Promise<CliStatusView> {
   const configDiagnostics = readConfigDiagnostics();
   const config = configDiagnostics.config;

package/src/cli/stop-report.ts

@@ -0,0 +1,143 @@
+/**
+ * Structured summary for `ocx stop --json` (D4 of the app runtime ownership unit).
+ *
+ * The desktop shell drives the real `ocx stop` as a child process so the receipt-backed
+ * teardown, the drain, the Windows respawn verification and the client-config restore run
+ * exactly as they do from a terminal. This module makes that run's RESULT readable from
+ * outside: a StopRunRecord is threaded through the existing stop path in
+ * src/cli/index.ts (the same booleans that already decide the exit code), and
+ * summarizeStopRun turns it into one versioned JSON document.
+ *
+ * Nothing here re-decides anything. If a field of the record is wrong, the fix belongs
+ * in the stop path, not in the summarizer.
+ */
+import { STOP_HISTORY_DEFERRED_EXIT_CODE } from "../update/stop-contract.mjs";
+
+/** Wire version of the stop summary document. */
+export const STOP_SUMMARY_SCHEMA = "ocx-stop/1";
+
+export type StopServiceOutcome =
+  | "absent"
+  | "stopped"
+  | "stopped-respawnable"
+  | "failed"
+  | "state-unknown"
+  | "error";
+
+export type StopProxyOutcome =
+  | "stopped"
+  | "stopped-orphan"
+  | "not-running"
+  | "stop-failed"
+  | "ownership-refused"
+  | "unresolvable-pid"
+  | "respawned"
+  | "unknown";
+
+export type StopSharedTeardownOutcome =
+  | "restored"
+  | "performed-by-proxy"
+  | "refused"
+  | "failed"
+  | "skipped";
+
+/** Facts recorded where the stop path already decides them. */
+export interface StopRunRecord {
+  /** What stopServiceIfInstalledDetailed returned, or "error" when it threw. */
+  service: StopServiceOutcome;
+  /** Which proxy path ran and how it ended. */
+  proxy: StopProxyOutcome;
+  /** Who ended up restoring shared client config (native Codex + Grok). */
+  sharedTeardown: StopSharedTeardownOutcome;
+  /** An inherited pending-teardown receipt blocked the restore. */
+  inheritedTeardownBlocks: boolean;
+  /** A discharged receipt could not be removed from disk. */
+  receiptClearFailed: boolean;
+}
+
+/** The internal booleans that already pick the process exit code. */
+export interface StopRunSignals {
+  failed: boolean;
+  historyOnly: boolean;
+  historyDeferred: boolean;
+  exitCode: number;
+}
+
+export interface StopSummaryJson {
+  schema: typeof STOP_SUMMARY_SCHEMA;
+  /** Strict exit-code view: true only for exit 0. */
+  ok: boolean;
+  outcome: "stopped" | "not-running" | "history-incomplete" | "history-deferred" | "failed";
+  exitCode: number;
+  /** True when this stop left no proxy of this home running by its own paths. */
+  runtimeDown: boolean;
+  service: StopServiceOutcome;
+  proxy: StopProxyOutcome;
+  sharedTeardown: StopSharedTeardownOutcome;
+  /** One stable human-readable line for a caller's UI. */
+  message: string;
+}
+
+/** What handleStop returns: the pre-existing boolean plus the structured twin. */
+export interface StopOutcome {
+  /**
+   * The exact boolean the stop path returned before summaries existed (!stopFailed).
+   * It is NOT the same as summary.ok: 79/80 stops return true here, because the
+   * downtime warning that keys on it applies whenever the runtime went down.
+   */
+  ok: boolean;
+  summary: StopSummaryJson;
+}
+
+function stopOutcome(record: StopRunRecord, signals: StopRunSignals): StopSummaryJson["outcome"] {
+  if (signals.failed) return "failed";
+  if (signals.historyOnly) return "history-incomplete";
+  if (signals.historyDeferred) {
+    // The deferred exit code is a proven claim; anything else means another obligation
+    // was sitting in the home, which the exit-code logic already reports as failure.
+    return signals.exitCode === STOP_HISTORY_DEFERRED_EXIT_CODE ? "history-deferred" : "failed";
+  }
+  if (record.proxy === "not-running") return "not-running";
+  if (record.proxy === "stopped" || record.proxy === "stopped-orphan") return "stopped";
+  return "failed";
+}
+
+function stopMessage(record: StopRunRecord, signals: StopRunSignals, outcome: StopSummaryJson["outcome"]): string {
+  if (record.proxy === "respawned") return "The proxy was respawned after the stop; it is still running.";
+  if (record.proxy === "ownership-refused") return "The proxy refused the stop; it belongs to a different opencodex home.";
+  if (record.proxy === "unresolvable-pid") return "A proxy is answering, but its process id could not be resolved, so it was not stopped.";
+  if (record.proxy === "stop-failed") return "The proxy process could not be stopped.";
+  if (record.service === "failed") return "The installed service manager did not stop and may respawn the proxy.";
+  if (record.service === "state-unknown") return "The service manager state could not be read.";
+  if (record.service === "error") return "Stopping the installed service failed.";
+  if (record.inheritedTeardownBlocks) return "An earlier stop left an outstanding shared teardown that could not be confirmed.";
+  if (record.sharedTeardown === "failed") return "The shared teardown failed; client configuration may still point at the stopped proxy.";
+  if (record.receiptClearFailed) return "The shared teardown finished, but its receipt could not be removed.";
+  if (record.sharedTeardown === "refused") return "The shared teardown was refused before it changed anything; it is still owed.";
+  if (signals.historyOnly) return "The proxy stopped; Codex history cleanup did not complete.";
+  if (outcome === "history-deferred") return "The proxy stopped; the shared teardown was deferred and is still owed.";
+  if (outcome === "not-running") return "No proxy was running.";
+  if (outcome === "stopped") return "The proxy stopped.";
+  return "The stop failed.";
+}
+
+/** Pure mapper from the recorded run to the wire document. */
+export function summarizeStopRun(record: StopRunRecord, signals: StopRunSignals): StopSummaryJson {
+  const outcome = stopOutcome(record, signals);
+  return {
+    schema: STOP_SUMMARY_SCHEMA,
+    ok: signals.exitCode === 0,
+    outcome,
+    exitCode: signals.exitCode,
+    runtimeDown: record.proxy === "stopped" || record.proxy === "stopped-orphan" || record.proxy === "not-running",
+    service: record.service,
+    proxy: record.proxy,
+    sharedTeardown: record.sharedTeardown,
+    message: stopMessage(record, signals, outcome),
+  };
+}
+
+/** Emit the summary as exactly one JSON document on stdout. */
+export function printStopSummary(summary: StopSummaryJson, stdout: { log: (s: string) => void } = console): void {
+  stdout.log(JSON.stringify(summary));
+}

package/src/cli/uninstall-plan.ts

@@ -84,3 +84,12 @@ export function everyEndpointProvenDown(
   if (endpoints.length === 0) return false;
   return endpoints.every(e => probe(e) === "dead");
 }
+
+export async function everyEndpointProvenDownAsync(
+  endpoints: readonly ProbeEndpoint[],
+  probe: (e: ProbeEndpoint) => Promise<"live" | "dead" | "unknown"> | "live" | "dead" | "unknown",
+): Promise<boolean> {
+  if (endpoints.length === 0) return false;
+  const results = await Promise.all(endpoints.map(e => probe(e)));
+  return results.every(result => result === "dead");
+}

package/src/client/machine-listener.ts

@@ -1,4 +1,3 @@
-import { readFileSync } from "node:fs";
 import type { Server } from "bun";
 import { loadConfig } from "../config";
 import { browserSecurityHeaders } from "../server/auth-cors";
@@ -16,11 +15,9 @@ import { readClientConnectionState } from "./state";
 import { handleMachineApi, type HubReachability, type MachineApiDeps } from "./machine-api";
 import { MACHINE_GUI_ORIGIN_HEADER, requireMachineAuth } from "./machine-auth";
 import { relayHubManagementRequest } from "./hub-relay";
+import { packageVersion } from "../lib/package-version";
 
-const VERSION = (() => {
-  try { return JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version as string; }
-  catch { return "0.0.0"; }
-})();
+const VERSION = packageVersion("0.0.0");
 const GUI_SPA_PATHS = new Set([
   "/dashboard", "/startup", "/providers", "/models", "/subagents",
   "/logs", "/usage", "/storage", "/codex-set", "/integrations",

package/src/clients/aside-profiles.ts

@@ -201,6 +201,7 @@ export function guardAsideProfileIO(profile: AsideProfile, io: IntegrationIO, pr
   const selected = { ...profile };
   const registered = registeredProfiles(selected, profiles).map(peer => ({ ...peer }));
   const captured = boundary(selected, registered, false);
+  const lstatProbe = io.lstatKind;
   function check(path: string, directory: boolean, mutation: boolean): void {
     if (path !== (directory ? selected.detectDir : selected.configPath)) {
       refuse("IO attempted to access a different account path.");
@@ -214,6 +215,9 @@ export function guardAsideProfileIO(profile: AsideProfile, io: IntegrationIO, pr
   return {
     readText: path => { check(path, false, false); return io.readText(path); },
     statKind: path => { check(path, path === selected.detectDir, false); return io.statKind(path); },
+    ...(lstatProbe
+      ? { lstatKind: (path: string) => { check(path, path === selected.detectDir, false); return lstatProbe(path); } }
+      : {}),
     writeText: (path, text) => { check(path, false, true); io.writeText(path, text); },
     removeFile: path => { check(path, false, true); io.removeFile(path); },
     mkdirp: path => { check(path, true, true); io.mkdirp(path); },