@bitkyc08/opencodex 2.38.0 → 2.39.0

package/src/server/stop-teardown.ts

@@ -0,0 +1,84 @@
+import type { CodexNativeRestoreResult } from "../codex/inject";
+import { deferralMatchesReceipt } from "../config/pending-teardown";
+
+/**
+ * Shared-teardown decision and execution for `POST /api/stop` (#3008).
+ *
+ * Lives outside the route handler because the handler schedules `process.exit` 200ms
+ * after it answers, which makes it uncallable from a test. The part worth testing is
+ * exactly this: whether the deferral is honoured, whether the restores actually run, and
+ * whether the response says what happened.
+ */
+
+export type GrokStripResult = { ok: boolean; changed: boolean; message: string };
+
+export type StopTeardownIo = {
+  /** Does the nonce this request carries name a readable obligation on disk? */
+  ownsReceipt?: (nonce: string | null) => boolean;
+  restoreNativeCodex?: () => Promise<CodexNativeRestoreResult>;
+  stripGrok?: () => GrokStripResult;
+};
+
+export type StopTeardownBody = {
+  success: boolean;
+  message: string;
+  sharedTeardown: "deferred" | "performed";
+};
+
+/**
+ * A deferral is honoured only when the caller proves it owns the obligation.
+ *
+ * The query flag names an intention; the receipt is the obligation. Without the second
+ * half any authenticated caller could ask the proxy to skip teardown and then exit,
+ * leaving native Codex and the Grok fence pointed at a proxy that no longer exists.
+ *
+ * "A receipt exists" is not that proof either: it would let any caller ride on another
+ * stop's outstanding obligation and get a deferral it never owns. The request has to name
+ * the receipt's nonce, which only the process that wrote it (and anything that can read
+ * the 0700 config directory, which is already the trust boundary for the admin token)
+ * can know.
+ */
+export function deferralHonored(url: URL, ownsReceipt: (nonce: string | null) => boolean): boolean {
+  if (url.searchParams.get("deferSharedTeardown") !== "1") return false;
+  return ownsReceipt(url.searchParams.get("teardownNonce"));
+}
+
+/** Run (or skip) the shared teardown and describe the outcome truthfully. */
+export async function performStopTeardown(url: URL, io: StopTeardownIo = {}): Promise<StopTeardownBody> {
+  const ownsReceipt = io.ownsReceipt ?? deferralMatchesReceipt;
+  if (deferralHonored(url, ownsReceipt)) {
+    // Not "native Codex restored": nothing was restored here, and claiming otherwise
+    // would be a success message the operator cannot verify.
+    return {
+      success: true,
+      message: "Proxy stopping; shared teardown deferred to the stopping client.",
+      sharedTeardown: "deferred",
+    };
+  }
+  const restore = io.restoreNativeCodex
+    ? await io.restoreNativeCodex()
+    : await (await import("../codex/inject")).restoreNativeCodexAsync();
+  const grok = io.stripGrok
+    ? io.stripGrok()
+    : (await import("../grok/inject")).stripGrokConfig();
+  // Success means BOTH halves came down. Deciding it from the native restore alone and
+  // appending the Grok text let a caller read `success: true` while the fence still
+  // pointed at a proxy that was exiting — the teardown reported done with half of it
+  // undone (#3008).
+  const grokNote = grok.ok ? "" : ` Grok config cleanup failed: ${grok.message}`;
+  if (restore.success && grok.ok) {
+    return { success: true, message: "Proxy stopping, native Codex restored.", sharedTeardown: "performed" };
+  }
+  if (restore.success) {
+    return {
+      success: false,
+      message: `Proxy stopping, native Codex restored, but the Grok fence was not removed:${grokNote} Run \`ocx restore\`.`,
+      sharedTeardown: "performed",
+    };
+  }
+  return {
+    success: false,
+    message: `Proxy stopping, but native Codex restore failed: ${restore.message}. Run \`ocx restore\`.${grokNote}`,
+    sharedTeardown: "performed",
+  };
+}

package/src/service.ts

@@ -2998,6 +2998,22 @@ export function stopWindows(): void {
     if (isWindowsSchedulerEndBenign(error)) return;
   }
 }
+
+/**
+ * `stopWindows` for callers that need to know whether it worked.
+ *
+ * The void form swallows a non-benign `/end` failure, which is right for best-effort
+ * teardown and wrong for deciding whether an update may replace files: a scheduler that
+ * refused to stop can respawn the proxy on top of a half-written install (#3008).
+ */
+export function stopWindowsChecked(): boolean {
+  try {
+    schtasks(["/end", "/tn", TASK]);
+    return true;
+  } catch (error) {
+    return isWindowsSchedulerEndBenign(error);
+  }
+}
 function statusWindows(): string { try { return schtasks(["/query", "/tn", TASK]); } catch { return ""; } }
 function statusWindowsXml(): string { try { return schtasks(["/query", "/tn", TASK, "/xml"]); } catch { return ""; } }
 
@@ -3604,36 +3620,129 @@ export async function installFreshWindowsSchedulerSafely(
   }
 }
 
+// `stopServiceIfInstalled` (boolean) is deliberately gone. It collapsed "not installed",
+// "refused to stop" and "state could not be read" into the same `false`, and every caller
+// that trusted it eventually read a live manager as absence — the route, then uninstall
+// (#3008). Callers take `stopServiceIfInstalledDetailed` and handle the outcomes.
 /**
- * If a service is installed, stop it so the process manager doesn't respawn after `ocx stop`.
- * Returns true if a service was found and stopped.
+ * Would stopping the installed manager leave something that can respawn the proxy?
+ *
+ * Answered WITHOUT stopping anything, because a caller that must refuse the stop has to
+ * refuse before it acts: `POST /api/stop` briefly ended the Task Scheduler task and then
+ * returned 409, which left the proxy running with its manager stopped — worse than either
+ * outcome it was choosing between.
+ *
+ * Task Scheduler only. `schtasks /end` ends the task instance while the `cmd :loop`
+ * wrapper survives and respawns its child (#764); launchd, systemd and WinSW are down when
+ * they report stopped.
  */
-export function stopServiceIfInstalled(): boolean {
+export function installedServiceRespawnRisk(
+  probe: () => WindowsSchedulerTaskProbe = probeWindowsSchedulerTask,
+  platform: NodeJS.Platform = process.platform,
+): "none" | "respawnable" | "unknown" {
+  // launchd, systemd and WinSW are down when they report stopped; only the Task Scheduler
+  // wrapper survives its task ending (#764).
+  if (platform !== "win32") return "none";
+  try {
+    // `probeWindowsSchedulerTask` returns "unknown" as an ordinary value when its queries
+    // fail — it does not throw — so testing for "present" let an unanswerable probe
+    // through, and the route then killed scheduler wrappers before refusing.
+    //
+    // "unknown" is kept SEPARATE from "respawnable" because the remedies differ. Telling
+    // an operator whose schtasks query is broken to run `ocx stop` is circular: that
+    // command maps the same unknown to a stop failure, so it cannot finish either.
+    const status = probe().status;
+    if (status === "absent") return "none";
+    return status === "present" ? "respawnable" : "unknown";
+  } catch {
+    // A probe that cannot answer is not evidence of absence either.
+    return "unknown";
+  }
+}
+
+/**
+ * Outcome of stopping an installed process manager.
+ *
+ * `stopServiceIfInstalled` collapses "no service was installed" and "a service was
+ * installed and would not stop" into the same `false`, which is fine for a caller that
+ * only wants to log. It is not fine for one deciding whether an update may replace package
+ * files: a manager that refused to stop can respawn the proxy on top of a half-written
+ * install (#3008).
+ */
+/**
+ * `stopped-respawnable` is Task Scheduler specifically: `schtasks /end` ends the task
+ * instance while the `cmd :loop` wrapper survives and respawns its child seconds later
+ * (#764). Only that backend needs the restart-window wait — launchd, systemd and WinSW
+ * are down when they report stopped, and making them pay a seven-second poll would be a
+ * regression in every ordinary `ocx stop`.
+ */
+/**
+ * `state-unknown` is kept apart from `failed` because the remedies differ. A manager that
+ * refused to stop is a stop failure the operator can retry; a scheduler whose state cannot
+ * be READ is a broken query, and telling that operator "the manager did not stop" sends
+ * them looking for the wrong thing (#3008).
+ */
+export type ServiceStopOutcome = "absent" | "stopped" | "stopped-respawnable" | "failed" | "state-unknown";
+
+/**
+ * Collapse the Windows backend observations into one outcome.
+ *
+ * Extracted so the precedence is testable by calling it. The rule that matters: a readable
+ * failure outranks an unreadable state, and an unreadable state outranks success — a
+ * scheduler we cannot see may still respawn the proxy.
+ */
+export function classifyWindowsServiceStop(o: {
+  stopped: boolean;
+  failed: boolean;
+  schedulerStopped: boolean;
+  stateUnknown: boolean;
+}): ServiceStopOutcome {
+  if (o.failed) return "failed";
+  if (o.stateUnknown) return "state-unknown";
+  if (o.stopped) return o.schedulerStopped ? "stopped-respawnable" : "stopped";
+  return "absent";
+}
+
+export function stopServiceIfInstalledDetailed(): ServiceStopOutcome {
   assertServiceEnvironmentMatchesInstall();
   if (process.platform === "darwin") {
     if (existsSync(plistPath())) {
-      try { stopLaunchd(); return true; } catch { return false; }
+      try { stopLaunchd(); return "stopped"; } catch { return "failed"; }
     }
   } else if (process.platform === "win32") {
     // Query BOTH backends regardless of state: a failed switch or stale state can leave
     // two managers installed, and either one would respawn the proxy after `ocx stop`.
     let stopped = false;
-    try {
-      const q = schtasks(["/query", "/tn", TASK]);
-      if (q.includes(TASK)) { stopWindows(); stopped = true; }
-    } catch { /* task not found */ }
+    let failed = false;
+    let schedulerStopped = false;
+    let stateUnknown = false;
+    // `probeWindowsSchedulerTask` is tri-state on purpose: a query that THROWS is not the
+    // same as a task that is absent, and treating it as absent lets a live scheduler
+    // survive a "successful" stop.
+    const probe = probeWindowsSchedulerTask();
+    if (probe.status === "present") {
+      if (stopWindowsChecked()) { stopped = true; schedulerStopped = true; }
+      else failed = true;
+    } else if (probe.status === "unknown") {
+      // Not "failed": nothing refused to stop. The query itself could not answer, which is
+      // a different problem with a different fix.
+      stateUnknown = true;
+    }
     if (statusWinswRaw() !== "nonexistent") {
-      try { stopWinswService(); stopped = true; } catch { /* best-effort */ }
+      try { stopWinswService(); stopped = true; } catch { failed = true; }
     }
     // `schtasks /end` ends the task instance but the cmd `:loop` wrapper survives and
     // respawns its child seconds later (issue #764), resurrecting the proxy during a
     // stop or a tray restart. Kill the launcher/wrapper processes outright.
     killWindowsServiceWrapperProcesses();
-    if (stopped) return true;
+    // A failure on either backend wins: the other one stopping does not make the live one
+    // safe to update over.
+    const outcome = classifyWindowsServiceStop({ stopped, failed, schedulerStopped, stateUnknown });
+    if (outcome !== "absent") return outcome;
   } else if (process.platform === "linux" && isSystemd() && existsSync(unitPath())) {
-    try { stopSystemd(); return true; } catch { return false; }
+    try { stopSystemd(); return "stopped"; } catch { return "failed"; }
   }
-  return false;
+  return "absent";
 }
 
 /** Delete install-state files; stale state would make `ocx update` "reinstall" a service that no longer exists. */
@@ -3666,13 +3775,22 @@ export function setUninstallServiceHooksForTests(hooks: UninstallServiceHooksFor
  * service or scheduler task that cannot be removed throws so the caller cannot erase state and
  * report success.
  */
-export function uninstallServiceIfInstalled(): boolean {
+/**
+ * Outcome of removing an installed manager.
+ *
+ * `false` used to mean both "nothing was installed" and "removal failed" on darwin and
+ * linux, so a failed removal was reported as absence and authorized the shared teardown
+ * while the service assets were still there (#3008).
+ */
+export type ServiceUninstallOutcome = "absent" | "removed" | "failed";
+
+export function uninstallServiceDetailed(): ServiceUninstallOutcome {
   const hooks = uninstallServiceHooksForTests;
   (hooks?.assertEnvironment ?? assertServiceEnvironmentMatchesInstall)();
   const platform = hooks?.platform ?? process.platform;
   if (platform === "darwin") {
     if (existsSync(plistPath())) {
-      try { uninstallLaunchd(); removeServiceInstallState(); return true; } catch { return false; }
+      try { uninstallLaunchd(); removeServiceInstallState(); return "removed"; } catch { return "failed"; }
     }
   } else if (platform === "win32") {
     let removed = false;
@@ -3688,13 +3806,20 @@ export function uninstallServiceIfInstalled(): boolean {
       (hooks?.uninstallNative ?? uninstallWinswService)();
       removed = true;
     }
-    if (removed) { (hooks?.removeInstallState ?? removeServiceInstallState)(); return true; }
+    if (removed) { (hooks?.removeInstallState ?? removeServiceInstallState)(); return "removed"; }
   } else if (platform === "linux" && existsSync(unitPath())) {
-    try { uninstallSystemd(); removeServiceInstallState(); return true; } catch {
-      try { unlinkSync(unitPath()); removeServiceInstallState(); return true; } catch { return false; }
+    try { uninstallSystemd(); removeServiceInstallState(); return "removed"; } catch {
+      try { unlinkSync(unitPath()); removeServiceInstallState(); return "removed"; } catch { return "failed"; }
     }
   }
-  return false;
+  return "absent";
+}
+
+/** Boolean form for callers that only distinguish "something was removed". */
+export function uninstallServiceIfInstalled(): boolean {
+  const outcome = uninstallServiceDetailed();
+  if (outcome === "failed") throw new Error("the installed service could not be removed");
+  return outcome === "removed";
 }
 
 /** True if a background service (launchd/systemd/Task Scheduler) is installed. */
@@ -4204,11 +4329,17 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
         const restore = await restoreNativeCodexAsync();
         if (restore.success) console.log("✅ service stopped + native Codex restored.");
         else console.error(`⚠️ service stopped, but native Codex restore FAILED: ${restore.message}\nRun \`ocx restore\` (or check $CODEX_HOME/config.toml) before using native Codex.`);
+        if (!restore.success) process.exitCode = 1;
         // The Grok fence is the other managed config this command owns. Leaving it behind
         // pointed grok at a dead endpoint while native Codex was already restored.
         const grok = stripGrokConfig();
         if (grok.changed) console.log(`↩️  ${grok.message}`);
-        else if (!grok.ok) console.error(`⚠️  ${grok.message}`);
+        else if (!grok.ok) {
+          // A failed strip leaves Grok aimed at a proxy this command just stopped. Exiting
+          // 0 tells a script the teardown finished when half of it did not.
+          console.error(`⚠️  ${grok.message}`);
+          process.exitCode = 1;
+        }
       }
       break;
     }
@@ -4242,10 +4373,14 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
         const restore = await restoreNativeCodexAsync();
         if (!restore.success) {
           console.error(`⚠️ native Codex restore FAILED: ${restore.message}\nRun \`ocx restore\` before using native Codex.`);
+          process.exitCode = 1;
         }
         const grok = stripGrokConfig();
         if (grok.changed) console.log(`↩️  ${grok.message}`);
-        else if (!grok.ok) console.error(`⚠️  ${grok.message}`);
+        else if (!grok.ok) {
+          console.error(`⚠️  ${grok.message}`);
+          process.exitCode = 1;
+        }
       }
       removeServiceInstallState();
       try { if (existsSync(serviceApiTokenFilePath())) unlinkSync(serviceApiTokenFilePath()); } catch { /* best-effort */ }

package/src/update/index.ts

@@ -1,9 +1,14 @@
 import { spawn, spawnSync } from "node:child_process";
+import { STOP_HISTORY_INCOMPLETE_EXIT_CODE } from "./stop-contract.mjs";
+import { proxyIdentityAt } from "../server/proxy-liveness";
+import { probeProxyLiveness } from "./proxy-liveness-probe.mjs";
+import { decidePostStopUpdate } from "./stop-decision.mjs";
 import { readFileSync, readdirSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { getConfigDir, loadConfig } from "../config";
 import { readPid, readRuntimePort } from "../config/process-state";
+import { pendingTeardownOutstanding } from "../config/pending-teardown";
 import { npmInvocation } from "./npm-invocation.mjs";
 import {
   npmCachePreflightFailureMessage,
@@ -246,8 +251,13 @@ export async function runUpdate(): Promise<void> {
   // modules after startup, so an in-place update leaves it executing mixed old/new code.
   // Gate on the service and the runtime-port record too, not just the pid file — a
   // service-managed or orphaned proxy can be live while ocx.pid is stale/missing.
+  //
+  // An outstanding pending-teardown receipt is a fourth reason to run the stop. After a
+  // parent crashed mid-deferral all three of the other signals can be absent while the
+  // shared client config still points at a proxy that is gone; installing over that
+  // silently skips the recovery the receipt was written to trigger (#3008).
   // Full `ocx stop` semantics (drain, service stop, restore).
-  if (serviceWasInstalled || readPid() || readRuntimePort()) {
+  if (serviceWasInstalled || readPid() || readRuntimePort() || pendingTeardownOutstanding()) {
     console.log("⏹  Stopping the running proxy before updating...");
     const stopStdio = updateChildStdio();
     const stop = spawnSync(process.execPath, selfLaunchArgv(["stop"]), {
@@ -256,17 +266,39 @@ export async function runUpdate(): Promise<void> {
       windowsHide: true,
     });
     if (stopStdio === "pipe") logSpawnOutput("", stop);
-    if (stop.status !== 0 || readPid() || readRuntimePort()) {
+    // One decision, shared with the npm launcher (#3008). The two lanes disagreeing about
+    // the same situation is how this shipped fixed on one side only. Absent PID and runtime
+    // files are weak evidence - a crashed-but-listening proxy leaves none - so the captured
+    // endpoint is asked, and `null` from proxyIdentityAt covers refusal AND timeout alike.
+    const identity = await proxyIdentityAt(capturedListen.port, { hostname: capturedListen.hostname });
+    const decision = decidePostStopUpdate({
+      status: stop.status,
+      hasRuntimeState: !!(readPid() || readRuntimePort()),
+      // Re-checked AFTER the stop: a quarantined receipt lets the stop itself succeed
+      // (there is nothing left to stop), so a pre-stop check alone let the retry install
+      // over a teardown that never ran.
+      teardownOutstanding: pendingTeardownOutstanding(),
+      liveness: identity ? "live" : probeProxyLiveness(capturedListen.port, capturedListen.hostname),
+    });
+    const historyOnlyStop = decision.reason === "history-only";
+    if (!decision.proceed) {
       if (trayWasRunning) {
         try {
           const { startWindowsTray } = await import("../tray/windows");
           startWindowsTray();
         } catch { /* preserve the proxy stop failure */ }
       }
-      console.error("⚠️  Could not stop the running proxy; aborting the update. Run 'ocx stop' and retry.");
+      if (decision.reason === "teardown-outstanding") {
+        console.error("⚠️  A shared teardown from an earlier stop is still outstanding and needs manual review; aborting the update.");
+        console.error("    Confirm no proxy is running, run 'ocx restore', then remove the pending-teardown file in your opencodex home.");
+      } else {
+        console.error(decision.reason === "proxy-unknown"
+          ? `⚠️  Could not confirm the proxy on ${capturedListen.hostname}:${capturedListen.port} is stopped; aborting the update. Run 'ocx stop' and retry.`
+          : "⚠️  Could not stop the running proxy; aborting the update. Run 'ocx stop' and retry.");
+      }
       process.exit(1);
     }
-    if (historyRestoreIncomplete()) {
+    if (historyOnlyStop || historyRestoreIncomplete()) {
       console.warn(
         "⚠️  Codex resume-history metadata restore is incomplete (a backup manifest remains).\n" +
         "    The DB may be busy or the manifest/target may need review; untracked routed history is intentionally unchanged.\n" +

package/src/update/proxy-liveness-probe.d.mts

@@ -0,0 +1,6 @@
+/** Declaration for the plain-ESM liveness probe shared with `bin/ocx.mjs`. */
+export declare function probeProxyLiveness(
+  port: number,
+  hostname?: string,
+  timeoutMs?: number,
+): "live" | "dead" | "unknown";

package/src/update/proxy-liveness-probe.mjs

@@ -0,0 +1,84 @@
+import { spawnSync } from "node:child_process";
+
+/**
+ * Is something still answering `/healthz` as an opencodex proxy on this endpoint?
+ *
+ * Absent PID and runtime-port files are weak evidence that the proxy is gone: a crashed
+ * but still-listening process, or one supervised outside our records, leaves no files and
+ * keeps the port. Replacing package files under it leaves a server running a mix of old
+ * and new modules, which is the hazard `ocx update` stops the proxy to avoid (#3008).
+ *
+ * Synchronous and dependency-free because it runs inside the plain-Node launcher's
+ * `runNpmSelfUpdate`, which is not async and cannot import the TypeScript liveness module.
+ * A separate Node child does the fetch so the caller keeps its straight-line control flow.
+ *
+ * Returns `"live" | "dead" | "unknown"`, and the caller treats `unknown` as a reason to
+ * stop. Fail-open was wrong here: a listener that accepts connections but withholds
+ * `/healthz`, or a probe that times out, is exactly the state where replacing package
+ * files is most dangerous, and "we could not tell" is not evidence the proxy is gone.
+ * Only a refused connection or a definitive non-OpenCodex answer earns `"dead"`.
+ */
+export function probeProxyLiveness(port, hostname = "127.0.0.1", timeoutMs = 1500) {
+  // An unusable port is not an ambiguous probe: there is nothing to ask.
+  if (!Number.isFinite(port) || port <= 0 || port > 65535) return "dead";
+  // Normalize HERE rather than at each call site. Leaving it to the callers put the fix in
+  // one lane and not the other, and a bracketed IPv6 literal handed to node:http answers
+  // nothing - which the tri-state correctly reports as "unknown" and the updater correctly
+  // treats as a reason to abort, turning a healthy stop into a refused update.
+  let host = typeof hostname === "string" && hostname.trim() !== "" ? hostname.trim() : "127.0.0.1";
+  // A wildcard bind answers on loopback; `node:http` cannot dial the wildcard itself.
+  if (host === "0.0.0.0" || host === "*") host = "127.0.0.1";
+  if (host === "::" ) host = "::1";
+  // `[::1]` is a URL spelling; the socket layer wants the bare address.
+  if (host.startsWith("[") && host.endsWith("]")) host = host.slice(1, -1);
+  // `node:http` rather than `fetch`: the child inherits a parent whose event loop is
+  // blocked on `spawnSync`, and an aborted-before-dispatch fetch reports the same "not
+  // live" as a genuinely dead port. A request emitted on the socket cannot be confused
+  // with one that never left.
+  const script = [
+    "const http = require('node:http');",
+    "const [host, port, timeout] = process.argv.slice(1);",
+    "const req = http.get({ host, port: Number(port), path: '/healthz', timeout: Number(timeout) }, res => {",
+    "  let body = '';",
+    "  res.setEncoding('utf8');",
+    "  res.on('data', chunk => { body += chunk; });",
+    "  res.on('end', () => {",
+    "    try {",
+    "      const parsed = JSON.parse(body);",
+    "      // Mirrors isOpencodexHealthz in src/server/proxy-liveness.ts. A foreign server",
+    "      // that happens to expose /healthz must not be read as our proxy, and a",
+    "      // pre-identity build of ours must not be read as foreign.",
+    "      const isOpencodex = parsed && typeof parsed === 'object'",
+    "        && (parsed.service === 'opencodex'",
+    "          || (parsed.service === undefined",
+    "            && parsed.status === 'ok'",
+    "            && typeof parsed.version === 'string'",
+    "            && typeof parsed.uptime === 'number'));",
+    "      // Only a clean 200 decides anything. Any other status means the endpoint is",
+    "      // answering but not telling us what it is, which is not evidence of absence.",
+    "      if (res.statusCode !== 200) process.stdout.write('UNKNOWN');",
+    "      else process.stdout.write(isOpencodex ? 'LIVE' : 'DEAD');",
+    "    } catch { process.stdout.write('UNKNOWN'); }",
+    "  });",
+    "});",
+    "req.on('timeout', () => { process.stdout.write('UNKNOWN'); req.destroy(); });",
+    "// ECONNREFUSED is the one error that proves nothing is listening. Everything else -",
+    "// reset, unreachable host, TLS confusion - leaves the question open.",
+    "req.on('error', err => process.stdout.write(err && err.code === 'ECONNREFUSED' ? 'DEAD' : 'UNKNOWN'));",
+  ].join("\n");
+  try {
+    const probe = spawnSync(
+      process.execPath,
+      ["-e", script, host, String(port), String(timeoutMs)],
+      { encoding: "utf8", timeout: timeoutMs + 1500, windowsHide: true },
+    );
+    const out = probe.stdout ?? "";
+    if (out.includes("LIVE")) return "live";
+    if (out.includes("DEAD")) return "dead";
+    // A child that produced nothing, was killed by its own timeout, or failed to spawn
+    // leaves the question open rather than answering it.
+    return "unknown";
+  } catch {
+    return "unknown";
+  }
+}

package/src/update/stop-contract.d.mts

@@ -0,0 +1,2 @@
+/** Declaration for the plain-ESM stop contract shared with `bin/ocx.mjs`. */
+export declare const STOP_HISTORY_INCOMPLETE_EXIT_CODE: 79;

package/src/update/stop-contract.mjs

@@ -0,0 +1,15 @@
+/**
+ * The exit code `ocx stop` uses to say "teardown succeeded, history cleanup did not".
+ *
+ * This is plain ESM rather than TypeScript because it has two consumers on opposite sides
+ * of a process boundary: `src/update/index.ts` and the Node launcher `bin/ocx.mjs`, which
+ * cannot import a `.ts` module. A TypeScript union would not survive `spawnSync` anyway —
+ * the value has to be on the wire, and an exit code is the wire.
+ *
+ * 79 is deliberate. It sits above the `sysexits.h` block (64-78), below `128 + signal`,
+ * and outside every code this CLI already uses: `src/cli/index.ts` emits 0, 1 and 130,
+ * and `src/cli/dispatch.ts` adds 2, 4 and 64. Picking one of those would have made a
+ * history-only stop indistinguishable from a config conflict, and `bin/ocx.mjs` mirrors
+ * the child's code faithfully enough to propagate the confusion.
+ */
+export const STOP_HISTORY_INCOMPLETE_EXIT_CODE = 79;

package/src/update/stop-decision.d.mts

@@ -0,0 +1,10 @@
+/** Declaration for the plain-ESM post-stop decision shared with `bin/ocx.mjs`. */
+export declare function decidePostStopUpdate(input: {
+  status: number | null;
+  hasRuntimeState: boolean;
+  liveness: "live" | "dead" | "unknown";
+  teardownOutstanding?: boolean;
+}): {
+  proceed: boolean;
+  reason: "stop-failed" | "runtime-state" | "teardown-outstanding" | "proxy-live" | "proxy-unknown" | "history-only" | "ok";
+};

package/src/update/stop-decision.mjs

@@ -0,0 +1,34 @@
+import { STOP_HISTORY_INCOMPLETE_EXIT_CODE } from "./stop-contract.mjs";
+
+/**
+ * May an update replace package files after `ocx stop` returned?
+ *
+ * Both updaters ask this: `src/update/index.ts` on the Bun path and `bin/ocx.mjs` on the
+ * npm path the dashboard uses. It lives here as plain ESM so the Node launcher can import
+ * it, and so the two lanes cannot drift into disagreeing about the same situation — which
+ * is how #3008 shipped in the first place, with the fix on one side only.
+ *
+ * Returns `{ proceed, reason }`. The reasons are:
+ *
+ * - `stop-failed` — a nonzero status other than the history-only code, or a signal kill.
+ *   A signal kill carries no evidence the teardown finished, so it is not a maybe.
+ * - `runtime-state` — a PID or runtime-port record survived the stop.
+ * - `teardown-outstanding` — a shared-teardown obligation survived the stop. That is a
+ *   quarantined receipt awaiting a human: the stop itself can succeed (there was nothing
+ *   left to stop), so checking only BEFORE the stop let the retry sail straight through
+ *   and install over a teardown that never ran.
+ * - `proxy-live` — something is still answering as our proxy on the captured endpoint.
+ * - `proxy-unknown` — the probe could not answer. Absence of proof is not proof of
+ *   absence, and replacing files under a live server leaves it running a mix of old and
+ *   new modules.
+ * - `ok` / `history-only` — proceed; the second also prints the manifest warning.
+ */
+export function decidePostStopUpdate({ status, hasRuntimeState, liveness, teardownOutstanding = false }) {
+  const historyOnly = status === STOP_HISTORY_INCOMPLETE_EXIT_CODE;
+  if (status !== 0 && !historyOnly) return { proceed: false, reason: "stop-failed" };
+  if (hasRuntimeState) return { proceed: false, reason: "runtime-state" };
+  if (teardownOutstanding) return { proceed: false, reason: "teardown-outstanding" };
+  if (liveness === "live") return { proceed: false, reason: "proxy-live" };
+  if (liveness !== "dead") return { proceed: false, reason: "proxy-unknown" };
+  return { proceed: true, reason: historyOnly ? "history-only" : "ok" };
+}

package/src/vision/eligibility.ts

@@ -21,6 +21,7 @@
  *    explicit modalities.
  */
 import { modelInList, type OcxConfig, type OcxProviderConfig } from "../types";
+import { modelRecordValue } from "../reasoning-effort";
 import { getModelMetadataCaseInsensitive, resolveMetadataProvider } from "../generated/model-metadata";
 import { nativeInputModalities } from "../codex/catalog/metadata";
 import { SUPPORTED_NATIVE_OPENAI_SLUGS } from "../codex/catalog/native-models";
@@ -68,6 +69,22 @@ export interface VisionModelOption {
 
 type EnrichedProviderCache = Map<string, OcxProviderConfig>;
 
+/**
+ * Whether the proxy must describe images for this model before dispatching its main request.
+ *
+ * `noVisionModels` is an explicit override. A modality declaration is only evidence for this
+ * path when it describes a text model that excludes image input: an audio-only declaration is
+ * not a text-only model and must not be widened to image through the vision sidecar.
+ */
+export function isModelVisionSidecarConsumer(
+  provider: Pick<OcxProviderConfig, "noVisionModels" | "modelInputModalities">,
+  modelId: string,
+): boolean {
+  if (modelInList(provider.noVisionModels, modelId)) return true;
+  const modalities = modelRecordValue(provider.modelInputModalities, modelId);
+  return Array.isArray(modalities) && modalities.includes("text") && !modalities.includes("image");
+}
+
 function advertisesImageInput(modalities: readonly string[] | undefined): boolean | undefined {
   if (!modalities || modalities.length === 0) return undefined;
   return modalities.includes("image");
@@ -105,7 +122,8 @@ function isVisionSidecarConsumerWithCache(
   modelId: string,
   cache: EnrichedProviderCache,
 ): boolean {
-  return modelInList(enrichedProviderForVision(config, providerName, cache)?.noVisionModels, modelId);
+  const provider = enrichedProviderForVision(config, providerName, cache);
+  return provider !== undefined && isModelVisionSidecarConsumer(provider, modelId);
 }
 
 /**

package/src/vision/index.ts

@@ -1,12 +1,10 @@
 import { createHash } from "node:crypto";
 import type { OcxConfig, OcxContentPart, OcxMessage, OcxParsedRequest, OcxProviderConfig, OcxTextContent } from "../types";
-import { modelInList } from "../types";
-import { modelRecordValue } from "../reasoning-effort";
 import type { VisionReasoningEffort } from "../reasoning-effort";
 import { describeImage, type DescribeOutcome, type VisionSettings } from "./describe";
 import { describeImageAnthropic } from "./anthropic-describe";
 import { describeImageRouted } from "./routed-describe";
-import { modelAcceptsImageInput } from "./eligibility";
+import { isModelVisionSidecarConsumer as isModelTextOnly, modelAcceptsImageInput } from "./eligibility";
 import { normalizeVisionReasoningForModel } from "./reasoning";
 import type { CodexAuthContext } from "../codex/auth-context";
 import { resolveSidecarAuth } from "../sidecar/auth";
@@ -22,24 +20,12 @@ import {
 
 export { describeImage } from "./describe";
 
-/**
- * True when the model is explicitly known to be text-only — either listed in
- * `noVisionModels` or declared with `modelInputModalities` that exclude "image".
- * Returns false for unknown models (no evidence either way) so they fall through
- * to native image passthrough, which is the safe default for an unclassified model.
- */
-export function isModelTextOnly(
-  provider: OcxProviderConfig,
-  modelId: string,
-): boolean {
-  if (modelInList(provider.noVisionModels, modelId)) return true;
-  const modalities = modelRecordValue(provider.modelInputModalities, modelId);
-  if (Array.isArray(modalities) && modalities.length > 0 && !modalities.includes("image")) return true;
-  return false;
-}
+/** Backward-compatible request-time name for the shared vision-sidecar consumer predicate. */
+export { isModelVisionSidecarConsumer as isModelTextOnly } from "./eligibility";
 export { describeImageAnthropic, parseAnthropicVisionSSE } from "./anthropic-describe";
 export {
   BASELINE_VISION_MODELS,
+  isModelVisionSidecarConsumer,
   isVisionEligibleModel,
   isVisionSidecarConsumer,
   modelAcceptsImageInput,