@bitkyc08/opencodex 2.37.0 → 2.39.0-preview.20260901

package/src/sidecar/candidates.ts

@@ -37,7 +37,7 @@ export async function pickerVisibleSidecarCandidates(
   auth: SidecarAuthState,
 ): Promise<SidecarCandidate[]> {
   let rows: Awaited<ReturnType<typeof listManagementModelRows>> = [];
-  try { rows = await listManagementModelRows(config); } catch { rows = []; }
+  try { rows = await listManagementModelRows(config, { entitlementWaitMs: 0 }); } catch { rows = []; }
   const byKey = new Map<string, SidecarCandidate>();
   for (const row of rows) {
     if (row.disabled === true) continue;

package/src/update/codex-cli-update-launch-policy.d.mts

@@ -0,0 +1,18 @@
+export const CODEX_CLI_VERSION_MANAGER_ROOT_ENV_SLOTS: readonly [
+  "ASDF_DATA_DIR",
+  "FNM_DIR",
+  "FNM_MULTISHELL_PATH",
+  "MISE_DATA_DIR",
+  "NODENV_ROOT",
+  "NVS_HOME",
+  "NVS_NODE_PATH",
+  "N_PREFIX",
+  "NVM_DIR",
+  "NVM_HOME",
+  "NVM_SYMLINK",
+  "PROTO_HOME",
+  "SCOOP",
+  "SCOOP_GLOBAL",
+  "VOLTA_HOME",
+];
+export function isCodexCliUpdateInspectionArgv(argv: readonly string[]): boolean;

package/src/update/codex-cli-update-launch-policy.mjs

@@ -0,0 +1,30 @@
+export const CODEX_CLI_VERSION_MANAGER_ROOT_ENV_SLOTS = Object.freeze([
+  "ASDF_DATA_DIR",
+  "FNM_DIR",
+  "FNM_MULTISHELL_PATH",
+  "MISE_DATA_DIR",
+  "NODENV_ROOT",
+  "NVS_HOME",
+  "NVS_NODE_PATH",
+  "N_PREFIX",
+  "NVM_DIR",
+  "NVM_HOME",
+  "NVM_SYMLINK",
+  "PROTO_HOME",
+  "SCOOP",
+  "SCOOP_GLOBAL",
+  "VOLTA_HOME",
+]);
+
+/**
+ * Detect the read-only Codex CLI updater inspection namespace before Bun loads.
+ * Keep this exact and argument-position based: malformed actions still inherit
+ * the zero-effect launcher contract and are rejected by the Bun-side parser.
+ */
+export function isCodexCliUpdateInspectionArgv(argv) {
+  // Bun consumes every internal launch-proof argument before ordinary command
+  // parsing. Classify the same effective argv here so a user-supplied invalid
+  // proof cannot hide this namespace from the pre-Bun zero-effect policy.
+  const args = argv.slice(2).filter(value => !value.startsWith("--ocx-internal-launch-proof="));
+  return args[0] === "system" && args[1] === "codex-cli-update";
+}

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" +
@@ -347,8 +379,9 @@ export async function runUpdate(): Promise<void> {
           }
         }
         if (!serviceRefreshed || !serviceViable) {
-          // A repair needs no elevation (it never calls `schtasks /create`), but it can
-          // still fail — or exit 0 while leaving stale/missing assets that never start
+          // Repair normally avoids elevation for a healthy scheduler task, but a stale
+          // definition may require guarded create/elevation. It can also fail — or exit 0
+          // while leaving stale/missing assets that never start
           // the proxy. Fall back to a direct detached proxy start so the update
           // never leaves the user without a running proxy — but only when the port is free.
           if (!freed) {

package/src/update/job.ts

@@ -459,8 +459,8 @@ export function restartCommand(
   const startArgs = pinPort
     ? [launcher, "start", "--port", String(Math.trunc(port))]
     : [launcher, "start"];
-  // Default to the non-registering refresh: an update path reaching here has an already
-  // installed service, and `install` would demand elevation on Windows scheduler backends.
+  // Default to the in-place refresh: `install` always registers, while repair reuses a healthy
+  // Windows scheduler definition and re-registers only when the live definition is stale.
   const svcArgs = serviceInstalled ? [launcher, ...(serviceArgs ?? ["service", "repair"])] : startArgs;
   if (installer === "npm") {
     const bin = nodeBin();
@@ -1116,12 +1116,10 @@ async function restartAfterUpdate(
     const preServiceAllow = reclaimKillAllowlist();
     const freed = await waitFn(port, hostname, reclaimOptsFor(preServiceAllow));
     let skipServiceInstall = false;
-    // This skip existed because the refresh ran `ocx service install`, whose Windows
-    // scheduler path always reaches `schtasks /create` — elevation the GUI update worker
-    // (OCX_SERVICE=1) never has. `service repair` rewrites the wrapper assets and
-    // restarts the EXISTING task with no `/create`, so the reason no longer applies and
-    // skipping would leave the dashboard-triggered update — the most common Windows
-    // path — with a stale service it could have refreshed.
+    // This skip existed because refresh ran `ocx service install`, whose Windows path always
+    // registers. `service repair` normally reuses the live task and can refresh a stale
+    // definition through its guarded create/elevation path, so the install-only skip no longer
+    // applies and would leave the common dashboard update with stale service assets.
     //
     // Only a caller that still passes install argv keeps the old behavior.
     const refreshRegisters = (svcArgs ?? []).includes("install");
@@ -1161,9 +1159,10 @@ async function restartAfterUpdate(
         const result = run(job, cmd.bin, cmd.args);
         serviceOk = result.status === 0;
         if (!serviceOk) {
-          // The refresh that just failed was `ocx service repair` (serviceReinstallArgs),
-          // which needs no elevation because it never calls `schtasks /create`. Advising
-          // `install` here would send the user to re-registration — a UAC prompt on
+          // The refresh that just failed was `ocx service repair` (serviceReinstallArgs).
+          // It normally reuses a healthy registration, but a stale definition may have tried
+          // guarded re-registration/elevation. Advising `install` here would unconditionally
+          // send the user to re-registration — a UAC prompt on
           // Windows and a possible WinSW-to-scheduler backend switch — to fix a service
           // that is already registered. Point at the same command that failed so its
           // output explains why, on every platform.

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,