@bitkyc08/opencodex 2.10.0 → 2.10.1

package/src/types.ts

@@ -2,6 +2,8 @@ import type { KiroOAuthMetadata } from "./oauth/types";
 
 export interface OcxParsedRequest {
   modelId: string;
+  /** Selected OpenAI API virtual-model id retained after it rewrites the upstream wire model. */
+  _openAiVirtualSelectedModelId?: string;
   previousResponseId?: string;
   context: OcxContext;
   stream: boolean;
@@ -83,6 +85,12 @@ export interface OcxAssistantMessage {
   phase?: OcxMessagePhase;
   model?: string;
   timestamp: number;
+  /**
+   * Kiro `reasoningContent.redactedContent` for THIS assistant turn — an opaque encrypted blob
+   * Kiro replays to preserve model reasoning across turns. Provider-specific and unrenderable, so
+   * it rides the message rather than a content part: any other adapter simply ignores it.
+   */
+  kiroRedactedReasoning?: string;
 }
 
 export interface OcxDeveloperMessage {
@@ -252,6 +260,9 @@ export type AdapterEvent =
   // opaque redacted_thinking blocks. Both must be replayed verbatim or tool-use turns 400.
   | { type: "thinking_signature"; signature: string }
   | { type: "redacted_thinking"; data: string }
+  // Kiro reasoning round-trip: the encrypted `redactedContent` blob for the CURRENT assistant turn.
+  // Never rendered — it only rides the reasoning item's envelope so the next request can replay it.
+  | { type: "kiro_redacted_reasoning"; data: string }
   | { type: "reasoning_raw_delta"; text: string }
   | { type: "tool_call_start"; id: string; name: string }
   | { type: "tool_call_delta"; arguments: string }
@@ -528,6 +539,22 @@ export interface OcxApiKeyEntry {
   createdAt: string;
 }
 
+/**
+ * Durable per-client intent. One key today, deliberately.
+ *
+ * A top-level `codexEnabled` would force every later client to invent an
+ * unrelated name and its own helpers; a ten-key union recreated the coupling
+ * that failed two audits, because every phase then had to touch every client's
+ * write path. A one-key object keeps the extension point without letting this
+ * phase claim ownership over a client it does not implement.
+ */
+export interface OcxClientIntegrationsConfig {
+  /** Durable desired state for native Codex. MISSING MEANS ON. */
+  codex?: boolean;
+  /** Durable desired state for Grok Build. MISSING MEANS ON. */
+  grok?: boolean;
+}
+
 export interface OcxConfig {
   port: number;
   /** Maximum usage-log bytes read for one management snapshot. */
@@ -541,8 +568,15 @@ export interface OcxConfig {
   /** Claude Code inbound + launcher settings. */
   claudeCode?: OcxClaudeCodeConfig;
   /**
-   * Up to 5 routed model ids ("<provider>/<model>") to feature FIRST in the injected Codex catalog.
-   * Codex's spawn_agent only advertises the first 5 routed models, so this picks which 5 appear.
+   * Per-client durable intent. This phase owns only `codex`; later phases extend
+   * one key at a time rather than widening a shared union.
+   */
+  clientIntegrations?: OcxClientIntegrationsConfig;
+  /**
+   * Up to 5 Codex-facing catalog ids to feature first. Values may be bare catalog ids,
+   * exact account-qualified "<selector>/<native-openai-model>" ids, or routed
+   * "<provider>/<model>" ids. With account selectors, one bare native choice can expand
+   * into a selector-qualified group; Codex still advertises only the first 5 visible rows.
    */
   subagentModels?: string[];
   /**
@@ -605,12 +639,17 @@ export interface OcxConfig {
    */
   streamMode?: "auto" | "legacy-tee" | "eager-relay";
   /**
-   * Custom override for the injected multi-agent guidance body (the text inside the
-   * <multi_agent_mode> tags). When set, it replaces the built-in prompt on whichever
-   * collab surface would have fired; firing gates are unchanged. Placeholders:
-   * `{{model}}` -> injectionModel, `{{effort}}` -> injectionEffort, `{{roster}}` ->
-   * the resolved sub-agent roster block ("" when nothing resolves), `{{fallback}}` ->
-   * the configured subagent model fallback guidance block ("" when unset).
+   * Custom override for the injected v2 multi-agent guidance body (the text inside
+   * the <multi_agent_mode> tags). After guidance is enabled and the v2 surface and
+   * catalog-state gates pass, a configured injectionModel is sufficient to render it;
+   * otherwise an eligible roster or fallback is required. Placeholders: `{{model}}` -> the
+   * effective preferred model for the request (a bare native model is account-qualified
+   * only when the request targets an explicit account selector; unresolved or ambiguous
+   * bare values become "", while unresolved explicit routed or account-qualified values
+   * remain unchanged),
+   * `{{effort}}` -> injectionEffort, `{{roster}}` -> the resolved sub-agent roster
+   * block ("" when nothing resolves), `{{fallback}}` -> the configured subagent
+   * model fallback guidance block ("" when unset).
    */
   injectionPrompt?: string;
   /**
@@ -633,10 +672,10 @@ export interface OcxConfig {
    */
   subagentEffortCap?: string;
   /**
-   * Models hidden from Codex. Routed ids are namespaced ("<provider>/<model>") and are excluded
-   * from the catalog + /v1/models entirely. BARE ids (no "/") are native GPT passthrough slugs:
-   * their catalog entries flip to visibility "hide" (entry preserved, picker-hidden) and they
-   * are omitted from the bare /v1/models list.
+   * Models hidden from Codex discovery without blocking direct proxy calls. Routed provider ids
+   * are excluded from the catalog + /v1/models entirely. Account-qualified native ids hide only
+   * their generated selector row and are omitted from raw /v1/models. BARE native GPT ids hide
+   * the bare row plus every generated selector row and omit that model family from raw discovery.
    */
   disabledModels?: string[];
   /** 사용자가 대시보드에서 직접 추가한 커스텀 모델 목록. */
@@ -645,7 +684,8 @@ export interface OcxConfig {
    * Shadow call intercept: redirect Codex's hard-coded helper calls (title generation,
    * commit messages, skill orchestration) to a user-chosen model. Default intercepted
    * source models: gpt-5.4-mini (older clients) and gpt-5.6-luna (Codex 0.145.0+).
-   * Opt-in; disabled by default. When enabled, effort is forced to low.
+   * Opt-in; disabled by default. Matching maintenance/helper requests are forced to low.
+   * Normal Codex turns identified by request_kind=turn are never rewritten.
    */
   shadowCallIntercept?: {
     /** When true, requests for known shadow/helper source models are rewritten to the configured model. */
@@ -754,9 +794,16 @@ export interface OcxConfig {
   };
   /** Virtual `combo/<id>` models spanning concrete provider/model targets (issue #133). */
   combos?: Record<string, OcxComboConfig>;
+  /**
+   * Routing policy profiles (Router Intelligence, RI-04+): explicitly requested
+   * `policy/<id>` (or configured alias) models select among an explicit
+   * candidate allowlist using hard capability requirements and deterministic
+   * scoring. Existing model ids are never routed through profiles implicitly.
+   */
+  routingProfiles?: Record<string, OcxRoutingProfileConfig>;
   /** Background proactive token refresh ("Token Guardian"). Off by default; see OcxTokenGuardianConfig. */
   tokenGuardian?: OcxTokenGuardianConfig;
-  /** Additional origins allowed for CORS (e.g. ["https://clisu-oracle.tail19a2d7.ts.net"]). Loopback origins are always allowed. */
+  /** Additional exact origins allowed for CORS (e.g. HTTPS or chrome-extension://<id>). Loopback origins are always allowed. */
   corsAllowOrigins?: string[];
 }
 
@@ -788,6 +835,65 @@ export interface OcxComboConfig {
   alias?: string;
 }
 
+export type OcxRoutingUnknownEvidenceMode = "allow" | "penalize" | "exclude";
+
+export interface OcxRoutingProfileCandidate {
+  provider: string;
+  model: string;
+}
+
+export interface OcxRoutingProfileRequirements {
+  /** Minimum model context window in tokens. */
+  minContextWindow?: number;
+  /** Minimum remaining quota headroom fraction (0..1). */
+  minQuotaHeadroom?: number;
+  tools?: boolean;
+  imageInput?: boolean;
+  structuredOutput?: boolean;
+  reasoningEffort?: string;
+  serviceTier?: string;
+  localOnly?: boolean;
+  remoteAllowed?: boolean;
+  /** Special encrypted Codex task readability (ChatGPT forward pool). */
+  encryptedCodexTasks?: boolean;
+}
+
+export interface OcxRoutingProfileOptimize {
+  latency?: number;
+  health?: number;
+  cost?: number;
+  quota?: number;
+}
+
+export interface OcxRoutingProfileLimits {
+  /** Hard per-request estimated-cost ceiling in USD. */
+  maxEstimatedCostUsd?: number;
+}
+
+export interface OcxRoutingProfileUnknownEvidence {
+  capability?: OcxRoutingUnknownEvidenceMode;
+  health?: OcxRoutingUnknownEvidenceMode;
+  quota?: OcxRoutingUnknownEvidenceMode;
+  cost?: OcxRoutingUnknownEvidenceMode;
+}
+
+export interface OcxRoutingProfileConfig {
+  /**
+   * Explicit candidate allowlist (`provider/model` refs). No implicit
+   * expansion in v1.
+   */
+  candidates: OcxRoutingProfileCandidate[];
+  /** Optional public model name replacing the default `policy/<id>` slug. */
+  alias?: string;
+  /** Hard requirements evaluated before scoring. */
+  require?: OcxRoutingProfileRequirements;
+  /** Optimization weights; normalized deterministically. */
+  optimize?: OcxRoutingProfileOptimize;
+  limits?: OcxRoutingProfileLimits;
+  /** How unknown evidence is handled per dimension. */
+  unknownEvidence?: OcxRoutingProfileUnknownEvidence;
+}
+
 /**
  * Per-provider proactive-refresh policy. The guardian only ever touches a provider whose EFFECTIVE
  * policy is "proactive"; "lazy-only" keeps today's on-demand refresh, "disabled" forbids the
@@ -905,8 +1011,37 @@ export interface ResponsesItemIdRepairConfig {
   reasoning?: string[];
   /** Backfill missing `output_item.done` / terminal snapshot ids from the matching output_index. */
   repairMissingTerminalIds?: boolean;
+  /**
+   * Treat existing message/reasoning ids without the canonical `msg_`/`rs_` prefix (e.g. bare
+   * UUIDs from DeepSeek's Responses route) as invalid and mint canonical replacements (#938).
+   * function_call ids and call_id pairing are never rewritten.
+   */
+  repairInvalidIds?: boolean;
 }
 
+/**
+ * Same-target 429 wait-and-retry policy (`providers.<name>.retryOn429`). When present and not
+ * explicitly disabled, the proxy waits and replays the identical request on the same key before
+ * any key failover. All fields optional; the runtime applies defaults (attempts=3,
+ * intervalMs=5000, maxIntervalMs=60000, respectRetryAfter=true, enabled=true).
+ */
+export interface RateLimitRetryPolicy {
+  /** Master switch. The presence of the object also enables the policy (default true). */
+  enabled?: boolean;
+  /** Extra replay attempts after the first 429 (1..20, default 3). */
+  attempts?: number;
+  /** Fixed wait between attempts when the upstream sends no usable Retry-After (default 5000). */
+  intervalMs?: number;
+  /** Cap for any single wait, including an upstream Retry-After (default 60000). */
+  maxIntervalMs?: number;
+  /** Prefer the upstream Retry-After header when present and parseable (default true). */
+  respectRetryAfter?: boolean;
+}
+
+/**
+ * One configured provider entry. `authMode` (default `"key"`) decides whether same-target 429
+ * retries are allowed; OAuth/forward credentials and local runtimes are never replayed.
+ */
 export interface OcxProviderConfig {
   adapter: string;
   /** Cursor MCP compatibility bounds; positive integers when configured. */
@@ -938,6 +1073,24 @@ export interface OcxProviderConfig {
    * forwarded to an upstream that cannot resolve their pair.
    */
   statelessResponses?: boolean;
+  /**
+   * Whether this provider's Responses route honours the OpenAI `service_tier`
+   * parameter. Tri-state: `true` lets fast mode inject/remove the field (an unset
+   * fast mode preserves a caller-supplied value); `false` strips the field and
+   * never injects, because an upstream documented as not supporting the parameter
+   * must not receive it; absent (`undefined`) leaves the provider unclassified —
+   * caller-supplied values are preserved untouched, and fast mode never injects.
+   * An explicit config value always wins over the registry default.
+   */
+  supportsServiceTier?: boolean;
+  /**
+   * Responses upstream whose native contract accepts plaintext reasoning replay
+   * (DeepSeek documents reasoning items with plaintext content). When set, the
+   * passthrough serializer keeps `reasoning_text` content on replayed reasoning
+   * items instead of blanking it the way the ChatGPT backend requires; proxy-minted
+   * `ocxr1` envelopes are still stripped because no upstream can decrypt them.
+   */
+  preserveResponsesReasoningContent?: boolean;
   /**
    * Explicit opt-in for non-registry private-network destinations such as localhost, RFC1918,
    * link-local, or unique-local upstreams. Metadata endpoints remain blocked.
@@ -1046,10 +1199,23 @@ export interface OcxProviderConfig {
    * Presence also advertises reasoning-summary support for that routed model.
    */
   modelReasoningSummaryDelivery?: Record<string, ReasoningSummaryDelivery>;
+  /**
+   * Exact-model hosted tools that win collisions with Codex client tool declarations.
+   * Use for non-forward Responses gateways that reserve a hosted tool namespace server-side.
+   */
+  modelPreferHostedTools?: Record<string, string[]>;
+  /**
+   * Provider-local repair for Responses gateways whose lifecycle snapshots omit canonical
+   * fields or closing events (#893). Disabled by default and applied only to client-facing
+   * SSE/JSON; raw inspection state remains authoritative.
+   */
+  responsesSnapshotRepair?: boolean;
   /** Provider-wide mapping from Codex effort labels to upstream `reasoning_effort` values. */
   reasoningEffortMap?: Record<string, string>;
   /** Model-specific mapping from Codex effort labels to upstream `reasoning_effort` values. */
   modelReasoningEffortMap?: Record<string, Record<string, string>>;
+  /** OpenAI-compatible gateway reasoning wire shape. Default sends `reasoning_effort`. */
+  reasoningWireFormat?: "gateway-object";
   /**
    * Model ids that do NOT support a reasoning/thinking parameter. The openai-chat adapter drops
    * reasoning_effort for these even when Codex selects a reasoning level (e.g. xAI grok-build-0.1).
@@ -1085,6 +1251,13 @@ export interface OcxProviderConfig {
   autoToolChoiceOnlyModels?: string[];
   /** Model ids that expect prior assistant `reasoning_content` to be preserved in chat history. */
   preserveReasoningContentModels?: string[];
+  /**
+   * Opt-in same-target 429 retry policy. Codex itself never retries 429 (it retries 5xx only,
+   * openai/codex#30471), and single-key pools have no failover, so the proxy waits and replays
+   * the identical request on the same key before any failover. Pre-stream only: a 429 arrives
+   * before any response bytes are relayed, so the replay is lossless.
+   */
+  retryOn429?: RateLimitRetryPolicy;
   /**
    * Model ids whose OpenAI-compatible chat endpoint accepts `reasoning_split: true` and returns
    * thinking separately in `reasoning_content` / `reasoning_details` instead of visible content.
@@ -1104,6 +1277,13 @@ export interface OcxProviderConfig {
   thinkingBudgetModels?: string[];
   /** Anthropic-compatible gateways that need custom tool names escaped on the wire. */
   escapeBuiltinToolNames?: boolean;
+  /**
+   * Anthropic-compatible gateways (e.g. AgentRouter) that may close the stream before
+   * `message_stop`. With this enabled the adapter completes an otherwise-clean EOF only when
+   * visible text was received or an open tool call has complete JSON-object arguments; all
+   * other EOFs remain truncation errors. Absent = strict default behavior.
+   */
+  anthropicEofTolerance?: boolean;
   /**
    * Model ids that do NOT accept image inputs. The proxy gives them "eyes" via the vision sidecar:
    * attached images are described by a gpt vision model and replaced with text before the call.

package/src/update/index.ts

@@ -5,6 +5,7 @@ import { dirname, join } from "node:path";
 import { getConfigDir, loadConfig, readPid, readRuntimePort } from "../config";
 import { npmInvocation } from "./npm-invocation.mjs";
 import { handoffWindowsTrayForUpdate, planWindowsTrayUpdate } from "./tray-update-plan.mjs";
+import { withProcessRuntimeProvenance } from "../lib/bun-runtime";
 
 /**
  * A `codex-history-backup-*.json` surviving a stop means the native-history restore was
@@ -185,7 +186,7 @@ export async function runUpdate(): Promise<void> {
   }
 
   // Remember whether a background service manages the proxy BEFORE stopping — `ocx stop`
-  // unloads it permanently, so a successful update must reinstall/restart it afterwards.
+  // unloads it, so a successful update must repair/restart it afterwards.
   let serviceWasInstalled = false;
   try {
     const { isServiceInstalled } = await import("../service");
@@ -294,11 +295,11 @@ export async function runUpdate(): Promise<void> {
         if (trayWasRunning) spawnSync(process.execPath, [process.argv[1], "tray", "start"], { stdio: "ignore", windowsHide: true });
       }
     }
-    // The stop above unloaded any managed service; reinstall it with the NEW files
+    // The stop above unloaded any managed service; repair it with the NEW files
     // (spawn the fresh cli.ts so updated code writes the baked paths) so a
     // launchd/schtasks/systemd user isn't left with the background proxy down.
     if (serviceWasInstalled) {
-      console.log("🔁 Reinstalling the background service with the updated files...");
+      console.log("🔁 Refreshing the background service with the updated files...");
       const { serviceReinstallArgs } = await import("../service");
       const { reclaimListenPort } = await import("../server/port-reclaim");
       const freed = await reclaimListenPort(capturedListen.port, capturedListen.hostname, {
@@ -309,7 +310,7 @@ export async function runUpdate(): Promise<void> {
         onlyKillPids: capturedListen.oldPid != null ? [capturedListen.oldPid] : [],
       });
       if (!freed) {
-        console.warn(`⚠️  Port ${capturedListen.port} still busy after 30s; reinstalling service with pinned --port ${capturedListen.port} anyway (refusing to hop).`);
+        console.warn(`⚠️  Port ${capturedListen.port} still busy after 30s; repairing service with pinned --port ${capturedListen.port} anyway (refusing to hop).`);
       }
       const prevBake = process.env.OCX_BAKE_PORT;
       process.env.OCX_BAKE_PORT = String(capturedListen.port);
@@ -332,9 +333,8 @@ export async function runUpdate(): Promise<void> {
           }
         }
         if (!serviceRefreshed || !serviceViable) {
-          // On Windows, schtasks /create requires elevation. The CLI inherits the
-          // user's (non-admin) token, so the service reinstall can fail with access
-          // denied — or exit 0 while leaving stale/missing assets that never start
+          // 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
           // 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) {
@@ -344,8 +344,8 @@ export async function runUpdate(): Promise<void> {
                 : "⚠️  Service refresh failed and the captured port is still busy; not starting on another port.",
             );
             console.warn(process.platform === "win32"
-              ? `   Run 'ocx service install' as administrator, then 'ocx start --port ${capturedListen.port}'.`
-              : `   Run 'ocx service install' to see the reason, then 'ocx start --port ${capturedListen.port}'.`);
+              ? `   Run 'ocx service repair', then 'ocx start --port ${capturedListen.port}'.`
+              : `   Run 'ocx service repair' to see the reason, then 'ocx start --port ${capturedListen.port}'.`);
           } else {
             console.warn(
               serviceRefreshed
@@ -353,18 +353,18 @@ export async function runUpdate(): Promise<void> {
                 : "⚠️  Service refresh failed — starting the proxy directly instead.",
             );
             // Elevation is a Windows-only remedy; elsewhere the refresh fails for
-            // reasons `ocx service install` reports directly (since it now verifies
+            // reasons `ocx service repair` reports directly (since it now verifies
             // the service actually serves).
             console.warn(process.platform === "win32"
-              ? "   Run 'ocx service install' as administrator to refresh the background service."
-              : "   Run 'ocx service install' to refresh the background service and see why it failed.");
+              ? "   Run 'ocx service repair' to refresh the background service."
+              : "   Run 'ocx service repair' to refresh the background service and see why it failed.");
             const env = { ...process.env };
             delete env.OCX_SERVICE;
             const child = spawn(process.execPath, [process.argv[1], "start", "--port", String(capturedListen.port)], {
               detached: true,
               stdio: "ignore",
               windowsHide: true,
-              env,
+              env: withProcessRuntimeProvenance(env),
             });
             child.unref();
             console.log(`✅ Proxy starting on port ${capturedListen.port}.`);

package/src/update/job.ts

@@ -300,7 +300,9 @@ export function restartCommand(
   const startArgs = pinPort
     ? [launcher, "start", "--port", String(Math.trunc(port))]
     : [launcher, "start"];
-  const svcArgs = serviceInstalled ? [launcher, ...(serviceArgs ?? ["service", "install"])] : startArgs;
+  // 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.
+  const svcArgs = serviceInstalled ? [launcher, ...(serviceArgs ?? ["service", "repair"])] : startArgs;
   if (installer === "npm") {
     const bin = nodeBin();
     const args = svcArgs;
@@ -648,6 +650,8 @@ export interface RestartIo {
   serviceHealthTimeoutMs?: number;
   sleepMs?: (ms: number) => Promise<void>;
   now?: () => number;
+  /** Test seam — defaults to process.platform so the Windows-only branch is reachable off Windows. */
+  platform?: NodeJS.Platform;
   /** Service-mode install/reinstall command (defaults to spawnSync via runLoggedCommand). */
   runService?: (
     job: UpdateJobState,
@@ -782,11 +786,17 @@ async function restartAfterUpdate(
     const preServiceAllow = reclaimKillAllowlist();
     const freed = await waitFn(port, hostname, reclaimOptsFor(preServiceAllow));
     let skipServiceInstall = false;
-    // Windows GUI update worker sets OCX_SERVICE=1 and is never elevated.
-    // `schtasks /create` will UAC-fail and can race the subsequent direct start.
-    // Keep systemd/launchd reinstall on non-Windows supervisors.
-    if (process.platform === "win32" && process.env.OCX_SERVICE === "1") {
-      updateJob(job, {}, "Skipping service reinstall from the non-elevated update worker; falling back to a direct proxy start.");
+    // 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.
+    //
+    // Only a caller that still passes install argv keeps the old behavior.
+    const refreshRegisters = (svcArgs ?? []).includes("install");
+    if ((io.platform ?? process.platform) === "win32" && process.env.OCX_SERVICE === "1" && refreshRegisters) {
+      updateJob(job, {}, "Skipping service re-registration from the non-elevated update worker; falling back to a direct proxy start.");
       skipServiceInstall = true;
     }
     if (!freed && !skipServiceInstall) {
@@ -813,24 +823,17 @@ async function restartAfterUpdate(
         const result = run(job, cmd.bin, cmd.args);
         serviceOk = result.status === 0;
         if (!serviceOk) {
-          // On Windows, `schtasks /create` requires an elevated token. The update worker
-          // inherits the (non-admin) proxy's privileges, so a service-managed install
-          // updated from the GUI or a normal terminal fails here with access denied.
-          // Falling back to a direct proxy start keeps the update from leaving the proxy
-          // stopped; the stale service manager can be refreshed later with an admin
-          // `ocx service install`.
-          //
-          // That advice is Windows-only, and on macOS/Linux it now actively misleads:
-          // `ocx service install` gained a non-zero exit for a service that registers
-          // but does not serve, so this branch fires there for a reason elevation
-          // cannot fix. Point at the command that prints the real reason instead.
+          // 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
+          // 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.
           updateJob(
             job,
             {},
-            `Service reinstall failed (exit ${result.status ?? "?"}); falling back to a direct proxy start.`
-            + (process.platform === "win32"
-              ? " Run 'ocx service install' as administrator to refresh the background service manager."
-              : " Run 'ocx service install' by hand to see the reason, then 'ocx service status'."),
+            `Service refresh failed (exit ${result.status ?? "?"}); falling back to a direct proxy start.`
+            + " Run 'ocx service repair' by hand to see the reason, then 'ocx service status'.",
           );
         }
       } finally {

package/src/update/notify.ts

@@ -83,8 +83,12 @@ function gt(a: number[], b: number[]): boolean {
 
 /**
  * Channel-aware "is latest newer than current?".
- * - latest channel: compare maj.min.pat only; prereleases are never "newer"
- *   (parity with codex-rs), so stable users are not pushed onto previews.
+ * - latest channel: compare maj.min.pat only; prerelease TARGETS are never
+ *   "newer" (parity with codex-rs), so stable users are not pushed onto
+ *   previews. An installed preview CURRENT compares by its maj.min.pat core,
+ *   so a stable release with a strictly higher base is offered (same base is
+ *   content-lateral promotion and stays not-newer, mirroring the preview
+ *   channel's O3 rule).
  * - preview channel: preview-vs-preview compares the trailing -preview.N; a
  *   stable release with a strictly higher base counts as newer (O3), while a
  *   stable release with the same base as the current preview does not.
@@ -92,7 +96,7 @@ function gt(a: number[], b: number[]): boolean {
 export function isNewer(latest: string, current: string, channel: Channel): boolean {
   if (channel === "latest") {
     const l = parseStable(latest);
-    const c = parseStable(current);
+    const c = parseStable(current) ?? parsePreview(current)?.slice(0, 3);
     if (!l || !c) return false;
     return gt(l, c);
   }