@bitkyc08/opencodex 2.64.0 → 2.65.0

package/src/types/config.ts

@@ -81,10 +81,11 @@ export interface OcxClaudeCodeConfig {
    */
   authModeMigratedAt?: string;
   /**
-   * Context-window override for Claude Code/Desktop clients (devlog 136 B6):
-   * injected as CLAUDE_CODE_MAX_CONTEXT_TOKENS + DISABLE_COMPACT=1 (the official
-   * env pair — recognized claude-shaped ids need both). WARNING: DISABLE_COMPACT
-   * turns off auto-compaction. Unset = client defaults.
+   * Context-window override for Claude Code/Desktop clients (devlog 136 B6).
+   * Injected as CLAUDE_CODE_MAX_CONTEXT_TOKENS only. Current ocx-claude aliases do
+   * not start with claude-, so Claude Code 2.1.278 honors the window without
+   * DISABLE_COMPACT. A persisted claude-ocx id is still claude-shaped and keeps
+   * the 200k accounting until the picker selects the new id. Unset = client defaults.
    */
   maxContextTokens?: number;
   /**
@@ -131,8 +132,7 @@ export interface OcxClaudeCodeConfig {
    * (Claude Code then accounts 1M) and CLAUDE_CODE_AUTO_COMPACT_WINDOW is injected
    * so compaction fires at the real budget. 2.1.207 semantics (binary-verified):
    * effective compact window = min(believed window, env) — one global env behaves
-   * like a per-model floor. Default: enabled. Inert while maxContextTokens is set
-   * (the legacy DISABLE_COMPACT pair takes rule-1 precedence in the CLI).
+   * like a per-model floor. Default: enabled. Inert while maxContextTokens is set.
    */
   autoContext?: boolean;
   /** Compact-window tokens for auto-context. Default 829_800 (AUTO_COMPACT_WINDOW_DEFAULT). */
@@ -142,8 +142,19 @@ export interface OcxClaudeCodeConfig {
    * traffic without any `ANTHROPIC_BASE_URL` rewrite (src/claude/intercept). Claude Code reaches
    * it via `HTTPS_PROXY`/`NODE_EXTRA_CA_CERTS` in its settings env. Default: enabled on a
    * hub; the proxy port defaults to the public port + 100.
+   *
+   * `modelMap` holds first-party model bindings (src/claude/intercept/model-bindings.ts): a
+   * Claude Desktop Code tab picker id such as `claude-sonnet-4-6` mapped to an opencodex route in
+   * the Desktop route vocabulary (`provider/model`, or `native/<slug>`). Bindings apply only to
+   * requests that arrive through the intercept pair, overlaid on the global `modelMap`.
    */
-  intercept?: { enabled?: boolean; port?: number };
+  intercept?: {
+    enabled?: boolean;
+    port?: number;
+    /** First-party Desktop Code-tab picker injection; unset enables it when eligible. */
+    picker?: boolean;
+    modelMap?: Record<string, string>;
+  };
   /**
    * Bundled-skill content elision for ROUTED (non-Anthropic) models (devlog 260712
    * 060): Skill-tool results whose skill name matches an entry here are replaced
@@ -175,10 +186,12 @@ export interface OcxClaudeCodeConfig {
   desktopProfile?: OcxClaudeDesktopProfile;
   /**
    * How Claude Desktop reaches opencodex (src/claude/desktop-first-party.ts).
-   * `first-party` (default) leaves the app on its normal claude.ai login and redirects only the
-   * Code tab's Claude Code process through the intercept pair via settings.json env.
-   * `gateway` installs the third-party deployment profile (desktop-3p) for the whole app.
-   * Unset on an install that already applied a gateway profile resolves to `gateway`.
+   * `gateway` (default) installs the third-party deployment profile (desktop-3p) for the whole app.
+   * `first-party` leaves the app on its normal claude.ai login and redirects only the Code tab's
+   * Claude Code process through the intercept pair via settings.json env; it sends Claude
+   * subscription traffic through a local interception proxy and carries an account-risk warning
+   * (src/claude/desktop-risk.ts). Unset: a gateway row or apply marker resolves to `gateway`, and
+   * first-party env that opencodex wrote resolves to `first-party` (observeClaudeDesktopMode).
    */
   desktopMode?: "first-party" | "gateway";
   /** Auto-reconcile Desktop 3P config when provider catalog changes. Default: enabled. */
@@ -498,7 +511,13 @@ export interface OcxConfig {
    * "no fast tier was requested".
    */
   ultraFastTier?: boolean;
-  /** Stop new identity-matched main-account requests at observed 99% usage. Default off. */
+  /**
+   * Stop new identity-matched main-account requests at observed 98% usage (#5694).
+   *
+   * On by default: an absent key and `true` both enable it, and only an explicit `false`
+   * opts out. While it blocks, the main account's Luna Reserve cannot activate, so an operator
+   * who wants Reserve has to turn the setting off rather than delete the key.
+   */
   codexMainAccountHardLock?: boolean;
   /** Explicit top-level deletion intent used by stale whole-config rebases. */
   configRebaseProvenance?: OcxConfigRebaseProvenance | Record<string, unknown>;
@@ -1134,11 +1153,20 @@ export type OcxComboDefaultEffortMode = "fallback" | "force";
  */
 export type OcxComboReasoningEffortMode = "strict" | "adaptive";
 
+/** Policy for how target cooldowns interact with `lastResort` targets (#5691). */
+export type OcxComboCooldownWaitPolicy = "before-last-resort";
+
 export interface OcxComboTarget {
   provider: string;
   model: string;
   /** Relative target weight for round-robin batches and random selection. Default 1; valid range 1..10000. */
   weight?: number;
+  /**
+   * Marks an emergency-only target. Inert unless the combo sets
+   * `cooldownWaitPolicy`, and never makes a target permanently ineligible —
+   * see `OcxComboConfig.cooldownWaitPolicy` (#5691).
+   */
+  lastResort?: boolean;
 }
 
 export interface OcxComboConfig {
@@ -1155,6 +1183,18 @@ export interface OcxComboConfig {
   cooldownMs?: number;
   /** Maximum wait for an eligible target cooldown to expire before failing closed. Default 0; range 0..600000, per selection attempt. */
   waitForCooldownMs?: number;
+  /**
+   * `before-last-resort` defers targets marked `lastResort` while a normal
+   * target is merely cooling and that cooldown can be waited out inside
+   * `waitForCooldownMs`. Omitted keeps today's behavior, where a brief cooldown
+   * on a preferred target routes straight to the emergency target (#5691).
+   *
+   * It only ever defers. When no normal target can be reached — all cooling
+   * past the budget, excluded, or ruled out by the caller — the last-resort
+   * target is dispatched, because a policy that could withhold it would turn a
+   * fallback into an outage.
+   */
+  cooldownWaitPolicy?: OcxComboCooldownWaitPolicy;
   /** Used as a fallback when the client omits reasoning.effort, or as an override in `force` mode. null/omitted leaves the target default unchanged. */
   defaultEffort?: OcxComboDefaultEffort | null;
   /** `force` makes the combo default override a valid client effort. Omitted / `fallback` preserves client precedence. */

package/src/types/provider.ts

@@ -377,6 +377,13 @@ export interface OcxProviderConfig {
    * An explicit config value always wins over the registry default.
    */
   supportsServiceTier?: boolean;
+  /**
+   * Operator switch for the provider's Fast lane. `false` turns Fast off (no Fast toggle, no
+   * `--fast` row, no fast wire field) and overrides `supportsServiceTier`; `true` enables a lane the
+   * registry marks opt-in (Anthropic fast mode, which draws usage credits at 2x price). Absent keeps
+   * the registry default: off for opt-in entries, unchanged elsewhere.
+   */
+  fastEnabled?: boolean;
   /** Exact upstream model ids that override the provider-level service-tier capability. */
   modelSupportsServiceTier?: Record<string, boolean>;
   /**
@@ -461,11 +468,14 @@ export interface OcxProviderConfig {
    * streaming POST turns use the configured Responses path (default `/v1/responses`): forward
    * providers use `{baseUrl}/responses`, while key-auth providers use `responsesPath` or the
    * legacy `/v1/responses` fallback. HTTPS providers use wss and are re-encoded to SSE; HTTP
-   * providers continue using SSE, and `openai-chat` requests stay on HTTP. This mirrors the
-   * canonical ChatGPT backend optimization for any OpenAI-compatible gateway that speaks the
-   * Responses WebSocket protocol (for example an aggregator like sub2api whose WS ingress is
-   * measurably faster than its SSE queue). Default false. Canonical ChatGPT backend WS selection
-   * is independent of this flag.
+   * providers continue using SSE, and `openai-chat` requests stay on HTTP. On a custom provider this
+   * opt-in is honored only for the first-party `https://api.openai.com/v1` upstream; every other
+   * endpoint stays on bounded HTTP/SSE. On the canonical ChatGPT `openai` provider the field
+   * selects the transport instead of opting in: omitted keeps the upstream WebSocket for eligible
+   * turns, an explicit `false` sends streaming turns over HTTP/SSE, and provider management rejects `true`. Either
+   * way it is independent of the client-facing `websockets` setting and changes neither the
+   * endpoint nor the credential; with `false`, native mid-turn steering and injection are
+   * unavailable.
    */
   upstreamWebsocket?: boolean;
   /**
@@ -810,6 +820,13 @@ export interface OcxProviderConfig {
   noTemperatureModels?: string[];
   /** Model ids that reject caller-specified top_p. */
   noTopPModels?: string[];
+  /**
+   * Model ids that reject caller-specified stop sequences. The openai-chat adapter
+   * drops `stop` for these (xAI grok-4.6 answers 400 invalid-argument
+   * "Model grok-4.6 does not support parameter stop.", which makes Claude Code's
+   * auto-mode safety classifier report the model as temporarily unavailable).
+   */
+  noStopModels?: string[];
   /** Model ids that reject caller-specified presence/frequency penalty values. */
   noPenaltyModels?: string[];
   /**

package/src/types/tools.ts

@@ -67,9 +67,11 @@ export function dottedToolName(namespace: string | undefined, name: string): str
  * Codex's code-mode shell tool is declared as `exec` (a freeform custom tool whose own
  * description mentions the nested `await tools.exec_command(...)` helper). Some routed providers
  * echo that helper name as the tool-call name, emitting `exec_command`, `write_stdin`,
- * `apply_patch`, or `view_image` instead of the declared `exec`. Accept these nested helper names
- * only when the request catalog actually declares `exec` and does not itself declare the emitted
- * name (an MCP server may legitimately advertise one under its own namespace).
+ * `apply_patch`, `view_image`, or one of the goal helpers (`create_goal`, `get_goal`,
+ * `update_goal`, #5495) instead of the declared `exec`. Accept these nested helper names only
+ * when the request catalog actually declares `exec` and does not itself declare the emitted name
+ * (an MCP server may legitimately advertise one under its own namespace). The list is closed: an
+ * unlisted name is never admitted through `exec`.
  */
 const LEGACY_SHELL_BRIDGE_TOOL_NAMES = ["exec_command", "shell_command"] as const;
 const CODE_MODE_HELPER_TOOL_NAMES = [
@@ -77,6 +79,9 @@ const CODE_MODE_HELPER_TOOL_NAMES = [
   "write_stdin",
   "apply_patch",
   "view_image",
+  "create_goal",
+  "get_goal",
+  "update_goal",
 ] as const;
 
 /**
@@ -105,7 +110,7 @@ export const CODE_MODE_HELPER_WIRE_NAMES: ReadonlySet<string> = new Set<string>(
  *
  * A bare alias is an ordinary compatibility affordance -- providers echo a namespaced tool
  * without its prefix, and restoring the identity needs the bare spelling registered. For these
- * six it is also an authorization decision, because a declared-name set is what
+ * names it is also an authorization decision, because a declared-name set is what
  * `normalizeDeclaredToolName` and `declaresCodeModeExec` read: bare `exec` turns nested-helper
  * normalization on for a catalog that never declared the shell, bare `exec_command` or
  * `shell_command` turns it off for one that did, and the rest are accepted as declared calls the
@@ -131,7 +136,8 @@ export const NAMESPACED_BARE_ALIAS_EXCLUDED_NAMES: ReadonlySet<string> = new Set
  * is declared and neither `default.<name>` nor `default__<name>` was explicitly declared (#4176).
  * The same wrapper may surround an already-flattened namespace identity; accept that exact
  * declared suffix without treating its child name as a bare declaration.
- * Also normalizes legacy helper names (`exec_command`, `shell_command`, `apply_patch`, `view_image`) to
+ * Also normalizes nested helper names (`exec_command`, `shell_command`, `write_stdin`,
+ * `apply_patch`, `view_image`, `create_goal`, `get_goal`, `update_goal`) to
  * `exec` when code-mode `exec` is declared in the request catalog.
  *
  * @param name - The tool name emitted on the wire by the provider.

package/src/types.ts

@@ -77,6 +77,7 @@ export type {
   OcxConfig,
   OcxAccountPoolRotationStrategy,
   OcxAccountPoolQuotaWindow,
+  OcxComboCooldownWaitPolicy,
   OcxComboStrategy,
   OcxComboDefaultEffort,
   OcxComboDefaultEffortMode,

package/src/update/async-check.ts

@@ -0,0 +1,109 @@
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { unprivilegedOwnershipMutationEnvironment } from "../service/ownership-mutation-lease.mjs";
+import { PKG, registrySpawnTarget, type Channel, type Installer } from "./index";
+import type { PnpmGlobalOwner } from "./pnpm-global-install.mjs";
+
+export const REGISTRY_DEADLINE_MS = 12_000;
+export const REGISTRY_OUTPUT_LIMIT = 4_096;
+
+export interface PnpmOwnerDeps {
+  workerUrl?: URL;
+  deadlineMs?: number;
+  invoked?: string;
+}
+
+export async function pnpmOwner(deps: PnpmOwnerDeps = {}): Promise<PnpmGlobalOwner | null> {
+  return new Promise(resolve => {
+    let worker: Worker;
+    try {
+      worker = new Worker((deps.workerUrl ?? new URL("./pnpm-owner-worker.ts", import.meta.url)).href);
+    } catch {
+      resolve(null);
+      return;
+    }
+    let done = false;
+    const finish = (owner: PnpmGlobalOwner | null) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      void worker.terminate();
+      resolve(owner);
+    };
+    const timer = setTimeout(() => finish(null), deps.deadlineMs ?? REGISTRY_DEADLINE_MS);
+    worker.onmessage = event => finish(event.data as PnpmGlobalOwner | null);
+    worker.onerror = () => finish(null);
+    try { worker.postMessage(deps.invoked ?? process.argv[1] ?? ""); }
+    catch { finish(null); }
+  });
+}
+
+export interface AsyncLookupDeps {
+  ownerFn: () => Promise<PnpmGlobalOwner | null>;
+  spawnFn: typeof spawn;
+  deadlineMs?: number;
+}
+
+const defaultDeps: AsyncLookupDeps = { ownerFn: pnpmOwner, spawnFn: spawn };
+
+export async function latestVersionAsync(
+  channel: Channel,
+  installer: Installer,
+  deps: AsyncLookupDeps = defaultDeps,
+): Promise<string | null> {
+  if (installer === "source" || installer === "mise") return null;
+  let owner: PnpmGlobalOwner | null | undefined;
+  try { owner = installer === "pnpm" ? await deps.ownerFn() : undefined; }
+  catch { return null; }
+  if (installer === "pnpm" && !owner) return null;
+  const target = registrySpawnTarget(installer, ["view", `${PKG}@${channel}`, "version"], owner ?? undefined);
+  if (!target) return null;
+
+  return new Promise(resolve => {
+    let child: ChildProcessWithoutNullStreams;
+    try {
+      child = deps.spawnFn(target.bin, target.args, {
+        stdio: ["pipe", "pipe", "pipe"],
+        windowsHide: true,
+        env: unprivilegedOwnershipMutationEnvironment(target.env ?? process.env),
+        ...target.options,
+      }) as ChildProcessWithoutNullStreams;
+    } catch {
+      resolve(null);
+      return;
+    }
+    child.stdin.end();
+    let done = false;
+    let bytes = 0;
+    let stdout = "";
+    let failed = false;
+    const finish = (version: string | null) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      resolve(version);
+    };
+    const accept = (chunk: Buffer, capture: boolean) => {
+      bytes += chunk.length;
+      if (bytes > REGISTRY_OUTPUT_LIMIT) {
+        failed = true;
+        child.kill();
+      } else if (capture) {
+        stdout += chunk.toString("utf8");
+      }
+    };
+    child.stdout.on("data", (chunk: Buffer) => accept(chunk, true));
+    child.stderr.on("data", (chunk: Buffer) => accept(chunk, false));
+    child.once("error", () => finish(null));
+    child.once("close", code => {
+      const value = stdout.trim();
+      finish(!failed && code === 0 && (channel === "latest"
+        ? /^\d+\.\d+\.\d+$/.test(value)
+        : /^\d+\.\d+\.\d+(?:-preview\.\d+)?$/.test(value))
+        ? value : null);
+    });
+    const timer = setTimeout(() => {
+      child.kill();
+      finish(null);
+    }, deps.deadlineMs ?? REGISTRY_DEADLINE_MS);
+  });
+}

package/src/update/badge.ts

@@ -1,20 +1,7 @@
-/**
- * Cached "is an update available?" answer for the GUI sidebar badge.
- *
- * `/api/update/check` spawns the installing manager's `view` command on every call
- * (~1s, network-bound), so a
- * sidebar that polls it would spawn a process per tick on every page of the GUI.
- * The badge instead READS the 20h version cache the CLI update prompt already
- * maintains (`~/.opencodex/version.json`).
- *
- * This is deliberately read-only: it must never trigger a registry refresh. The GUI
- * polls it, so a refresh-on-read would let repeated polls launch repeated manager `view`
- * helpers with no coalescing. Cache warming stays with `ocx start`
- * (`triggerBackgroundRefreshIfStale` in `src/update/notify.ts`) and with the explicit
- * `/api/update/check` the user reaches by clicking the sidebar update button.
- */
+/** The badge only reads package cache. Server and explicit checks produce it;
+ * missing, wrong-channel, and 40-hour-old cache answers are unknown. */
 import { currentVersion, defaultUpdateTag, detectInstall, type Channel } from "./index";
-import { isNewer, isSourceBuildVersion, readVersionCache } from "./notify";
+import { CACHE_MAX_AGE_MS, isNewer, isSourceBuildVersion, readVersionCache } from "./notify";
 
 export interface UpdateBadge {
   /** True only when a newer version exists on the current channel. */
@@ -22,6 +9,7 @@ export interface UpdateBadge {
   currentVersion: string;
   latestVersion: string | null;
   channel: Channel;
+  installer: ReturnType<typeof detectInstall> | "desktop";
   /** False for source checkouts, where the GUI cannot offer a one-click update. */
   canUpdate: boolean;
   /** True when no cached registry answer exists yet, so "no update" is unproven. */
@@ -32,12 +20,14 @@ export interface UpdateBadgeDeps {
   currentVersion: () => string;
   detectInstall: () => ReturnType<typeof detectInstall>;
   readCache: (channel: Channel) => ReturnType<typeof readVersionCache>;
+  now?: () => number;
 }
 
 const defaultDeps: UpdateBadgeDeps = {
   currentVersion,
   detectInstall,
   readCache: readVersionCache,
+  now: Date.now,
 };
 
 /**
@@ -53,7 +43,8 @@ export function readUpdateBadge(deps: UpdateBadgeDeps = defaultDeps): UpdateBadg
     currentVersion: current,
     latestVersion: null,
     channel,
-    canUpdate: installer !== "source",
+    installer,
+    canUpdate: installer !== "source" && installer !== "mise",
     unknown: true,
   };
   // A source checkout has nothing to compare against, so "unknown" is not useful there.
@@ -63,6 +54,9 @@ export function readUpdateBadge(deps: UpdateBadgeDeps = defaultDeps): UpdateBadg
 
   const cache = deps.readCache(channel);
   if (!cache) return base;
+  const checked = Date.parse(cache.last_checked_at);
+  const now = deps.now?.() ?? Date.now();
+  if (!Number.isFinite(checked) || checked > now || now - checked >= CACHE_MAX_AGE_MS) return base;
 
   return {
     ...base,

package/src/update/check-types.ts

@@ -0,0 +1,9 @@
+import type { Channel, Installer, InstallOwnership } from "./index";
+
+export interface UpdateCheckDeps {
+  currentVersion: () => string;
+  detectInstall: () => Installer;
+  detectInstallOwnership?: () => InstallOwnership;
+  latestVersion: (tag: Channel) => string | null;
+  miseUpdateCommand?: (ownership: InstallOwnership) => string | null;
+}

package/src/update/desktop-badge.ts

@@ -0,0 +1,102 @@
+import type { UpdateBadge } from "./badge";
+import { defaultUpdateTag } from "./index";
+
+export type DesktopPhase =
+  | "idle" | "checking" | "available" | "current"
+  | "error" | "installing" | "install-failed";
+
+export interface DesktopSnapshot {
+  sessionId: string;
+  currentVersion: string;
+  latestVersion: string | null;
+  available: boolean;
+  checkedAtMs: number | null;
+  phase: DesktopPhase;
+}
+
+const SESSION = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const VERSION = /^[0-9A-Za-z][0-9A-Za-z.+_-]{0,63}$/;
+const PHASES = new Set<DesktopPhase>([
+  "idle", "checking", "available", "current", "error", "installing", "install-failed",
+]);
+export const DESKTOP_SNAPSHOT_TTL_MS = 180_000;
+export const DESKTOP_SNAPSHOT_MAX_SESSIONS = 32;
+const MIN_DESKTOP_CHECKED_AT_MS = 946_684_800_000; // 2000-01-01 UTC
+const MAX_DESKTOP_CLOCK_SKEW_MS = 60_000;
+
+export function validDesktopSession(value: unknown): value is string {
+  return typeof value === "string" && SESSION.test(value);
+}
+
+export function parseDesktopSnapshot(value: unknown, nowMs: number): DesktopSnapshot | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const body = value as Record<string, unknown>;
+  const keys = Object.keys(body).sort();
+  if (keys.join(",") !== "available,checkedAtMs,currentVersion,latestVersion,phase,sessionId") return null;
+  if (!validDesktopSession(body.sessionId)
+    || typeof body.currentVersion !== "string" || !VERSION.test(body.currentVersion)
+    || (body.latestVersion !== null && (typeof body.latestVersion !== "string" || !VERSION.test(body.latestVersion)))
+    || typeof body.available !== "boolean"
+    || typeof body.phase !== "string" || !PHASES.has(body.phase as DesktopPhase)) return null;
+  const checked = body.checkedAtMs;
+  if (checked !== null && (typeof checked !== "number" || !Number.isSafeInteger(checked) || checked < 0
+    || checked < MIN_DESKTOP_CHECKED_AT_MS
+    || checked > nowMs + MAX_DESKTOP_CLOCK_SKEW_MS)) return null;
+  if (body.available !== (body.latestVersion !== null)) return null;
+  if (body.available && checked === null) return null;
+  if (body.phase === "available" && !body.available) return null;
+  if (body.phase === "current" && (body.available || checked === null)) return null;
+  if (body.phase === "idle" && (body.available || checked !== null)) return null;
+  if ((body.phase === "installing" || body.phase === "install-failed") && !body.available) return null;
+  return body as unknown as DesktopSnapshot;
+}
+
+export class DesktopBadgeStore {
+  private readonly entries = new Map<string, { snapshot: DesktopSnapshot; receivedAtMs: number }>();
+  constructor(
+    private readonly wallNowMs: () => number = Date.now,
+    private readonly elapsedNowMs: () => number = () => performance.now(),
+  ) {}
+
+  put(value: unknown): boolean {
+    const snapshot = parseDesktopSnapshot(value, this.wallNowMs());
+    if (!snapshot) return false;
+    const now = this.elapsedNowMs();
+    this.prune(now);
+    this.entries.delete(snapshot.sessionId);
+    while (this.entries.size >= DESKTOP_SNAPSHOT_MAX_SESSIONS) {
+      this.entries.delete(this.entries.keys().next().value!);
+    }
+    this.entries.set(snapshot.sessionId, { snapshot, receivedAtMs: now });
+    return true;
+  }
+
+  read(sessionId: string | null): UpdateBadge {
+    const now = this.elapsedNowMs();
+    this.prune(now);
+    const snapshot = sessionId && validDesktopSession(sessionId)
+      ? this.entries.get(sessionId)?.snapshot : undefined;
+    if (!snapshot) return {
+      updateAvailable: false, currentVersion: "?", latestVersion: null,
+      channel: "latest", installer: "desktop", canUpdate: true, unknown: true,
+    };
+    return {
+      updateAvailable: snapshot.available,
+      currentVersion: snapshot.currentVersion,
+      latestVersion: snapshot.latestVersion,
+      channel: defaultUpdateTag(snapshot.currentVersion),
+      installer: "desktop",
+      canUpdate: true,
+      unknown: snapshot.phase === "idle"
+        || ((snapshot.phase === "checking" || snapshot.phase === "error") && !snapshot.available),
+    };
+  }
+
+  private prune(now: number): void {
+    for (const [key, entry] of this.entries) {
+      if (now - entry.receivedAtMs >= DESKTOP_SNAPSHOT_TTL_MS) this.entries.delete(key);
+    }
+  }
+}
+
+export const desktopBadgeStore = new DesktopBadgeStore();

package/src/update/index.ts

@@ -15,7 +15,15 @@ import { unprivilegedOwnershipMutationEnvironment } from "../service/ownership-m
 import { withUpdateOwnershipLease, readUpdateRuntimeTarget } from "./ownership-transaction";
 import { npmInvocation } from "./npm-invocation.mjs";
 import { pnpmInvocation, pnpmInvocationForPath, resolvePnpmCommands } from "./pnpm-invocation.mjs";
-import { detectInstallFromPath } from "./install-detection.mjs";
+import {
+  detectInstallFromPath,
+  detectInstallOwnershipFromPath,
+} from "./install-detection.mjs";
+import type {
+  DetectedInstall,
+  InstallOwnership,
+  MiseInstallOwner,
+} from "./install-detection.d.mts";
 import {
   pnpmOwnerInvocation,
   readPnpmGlobalPackage,
@@ -50,20 +58,33 @@ export function historyRestoreIncomplete(configDir = getConfigDir()): boolean {
 export const PKG = "@bitkyc08/opencodex";
 const HERE = dirname(fileURLToPath(import.meta.url)); // .../opencodex/src/update
 
-export type Installer = "bun" | "npm" | "pnpm" | "source";
+export type Installer = DetectedInstall;
 export type Channel = "latest" | "preview";
+export type { InstallOwnership, MiseInstallOwner };
 
 /** Infer how opencodex is installed from the running module's path. */
 export function detectInstall(): Installer {
   return detectInstallFromPath(HERE, { exists: existsSync });
 }
 
+/** Resolve installer ownership and verified mise update guidance for this package. */
+export function detectInstallOwnership(): InstallOwnership {
+  return detectInstallOwnershipFromPath(HERE, { exists: existsSync });
+}
+
+export function miseUpdateCommand(
+  ownership: InstallOwnership = detectInstallOwnership(),
+): string | null {
+  return ownership.installer === "mise" && ownership.owner
+    ? `mise upgrade ${ownership.owner.tool}`
+    : null;
+}
+
 function packageRoot(): string {
   return resolve(HERE, "..", "..");
 }
 
-function runningPnpmShimPath(): string | undefined {
-  const invoked = process.argv[1];
+function runningPnpmShimPath(invoked = process.argv[1]): string | undefined {
   if (!invoked) return undefined;
   const name = invoked.replaceAll("\\", "/").split("/").at(-1)?.toLowerCase();
   if (!new Set(["ocx", "opencodex", "ocx.cmd", "opencodex.cmd", "ocx.ps1", "opencodex.ps1"]).has(name ?? "")) {
@@ -90,12 +111,12 @@ function runPnpmCandidate(
 }
 
 /** Resolve the exact pnpm executable/group/bin that own this package. */
-export function resolveCurrentPnpmGlobalOwner(): PnpmGlobalOwnerResult {
+export function resolveCurrentPnpmGlobalOwner(invoked = process.argv[1]): PnpmGlobalOwnerResult {
   return resolvePnpmGlobalOwner({
     packageName: PKG,
     packagePath: packageRoot(),
     commandPaths: resolvePnpmCommands(),
-    runningShimPath: runningPnpmShimPath(),
+    runningShimPath: runningPnpmShimPath(invoked),
     runPnpm: runPnpmCandidate,
   });
 }
@@ -170,6 +191,8 @@ type SpawnTarget = {
   env?: Record<string, string | undefined>;
 };
 
+export type RegistrySpawnTarget = SpawnTarget;
+
 function npmSpawnTarget(args: readonly string[]): SpawnTarget | null {
   const invocation = npmInvocation(args);
   if (!invocation) return null;
@@ -192,7 +215,7 @@ function pnpmSpawnTarget(args: readonly string[], owner?: PnpmGlobalOwner): Spaw
   return { bin: invocation.file, args: invocation.args, options: invocation.options };
 }
 
-function registrySpawnTarget(
+export function registrySpawnTarget(
   installer: Installer,
   args: readonly string[],
   owner?: PnpmGlobalOwner,
@@ -269,6 +292,9 @@ export function latestVersion(
 
 /** The global-install command opencodex would run to update on this channel. */
 export function updateCommand(installer: Installer, tag: Channel, resolvedVersion?: string | null): { bin: string; args: string[] } {
+  if (installer === "mise") {
+    throw new Error("mise-owned installations must be upgraded through mise");
+  }
   // Immutable target: when the registry resolved a concrete version, install exactly
   // that version — the dist-tag can move between resolution and install (TOCTOU).
   const target = resolvedVersion || tag;
@@ -361,11 +387,25 @@ async function resolvedRuntimeOwnership(): Promise<RuntimeOwnershipObservation>
  * Bun binary.
  */
 export async function runUpdate(): Promise<void> {
-  const installer = detectInstall();
+  const ownership = detectInstallOwnership();
+  const installer = ownership.installer;
   const current = currentVersion();
   const tag = updateTag(current);
   console.log(`opencodex v${current} (installed via ${installer}, tag ${tag})`);
 
+  if (installer === "mise") {
+    const command = miseUpdateCommand(ownership);
+    if (command) {
+      console.error(`OpenCodex is externally managed by mise. Update it with: ${command}`);
+    } else {
+      console.error(
+        "OpenCodex appears to be managed by mise, but its ownership metadata is unreadable or inconsistent. Repair the mise installation metadata before updating.",
+      );
+    }
+    process.exitCode = 1;
+    return;
+  }
+
   if (installer === "source") {
     console.log("Running from a source checkout — update with:  git pull && bun install");
     return;