@golba98/codexa 1.0.5 → 1.0.6

package/README.md

@@ -577,7 +577,7 @@ npm install -g @golba98/codexa@latest
 
 ### Update notice does not appear
 
-Codexa checks for updates on startup and caches the result for 6 hours (stored in `~/.codexa-update-check.json`). The update notice only appears when the npm registry `latest` version is newer than the running version.
+Codexa checks npm for updates on every interactive startup. The local cache at `~/.codexa-update-check.json` is only used as a best-effort fallback if npm is temporarily unavailable. The update notice appears when the npm registry `latest` version is newer than the running version.
 
 Published npm versions are immutable. Versions before the fixed update checker may not show update notices even when a newer package exists. If in doubt, update directly:
 
@@ -588,9 +588,8 @@ npm install -g @golba98/codexa@latest
 If you expect a notice but don't see one:
 
 1. Check the current registry state: `npm view @golba98/codexa dist-tags --json`
-2. Clear the cache to force a fresh check: delete `~/.codexa-update-check.json`, then restart Codexa
-3. Force an explicit check in-app: `/update check`
-4. Update checks are disabled for local dev builds (`codexa-dev` / `cxd`)
+2. Force an explicit check in-app: `/update check`
+3. Update checks are disabled for local dev builds (`codexa-dev` / `cxd`)
 
 | Symptom | Fix |
 |---------|-----|
@@ -606,11 +605,8 @@ If you expect a notice but don't see one:
 
 See [CHANGELOG.md](CHANGELOG.md) for the full release history.
 
-**Current release: v1.0.4**
+**Current release: v1.0.6**
 
-v1.0.4 is an update-notice reliability fix:
-- Older installed versions can detect when npm `latest` is newer
-- `/update check` bypasses stale cache and reports a useful status
-- Failed registry lookups do not get cached as “up to date”
+v1.0.6 checks npm on every interactive startup and shows an update prompt as soon as Codexa is idle. The prompt offers the correct update command for the package manager that installed Codexa.
 
-> Versions before the fixed update checker may not show update notices. Update directly with `npm install -g @golba98/codexa@latest`.
+> Versions before v1.0.6 can wait for a cached result before discovering a new npm release. Update directly with `npm install -g @golba98/codexa@latest` if needed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@golba98/codexa",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "Terminal UI for Codexa — TypeScript + Bun + Ink",
   "type": "module",
   "bin": {

package/src/app.tsx

@@ -270,9 +270,10 @@ import { AppShell } from "./ui/chrome/AppShell.js";
 import { TranscriptShell } from "./ui/timeline/TranscriptShell.js";
 import type { RuntimeAvailability } from "./ui/chrome/RuntimeStatusBar.js";
 import { checkForUpdates, formatLocalDevUpdateStatus, formatUpdateInstructions, shouldRunStartupUpdateCheck, type UpdateCheckResult } from "./core/version/updateCheck.js";
+import { detectGlobalPackageManager, getUpdateCommand } from "./core/version/packageManager.js";
 import { isLocalDevChannel } from "./core/version/channel.js";
 import {
-  isCacheValid,
+  isCacheForRunningVersion,
   loadUpdateCheckCache,
   saveUpdateCheckCache,
 } from "./config/updateCheckCache.js";
@@ -394,9 +395,6 @@ export function App({ launchArgs }: AppProps) {
     ? projectInstructionsLoad.instructions
     : null;
   const initialSettings = useRef(loadSettings());
-  const skippedUpdateVersionRef = useRef<string | null>(
-    initialSettings.current.updateCheck.skippedUpdateVersion ?? null,
-  );
   const initialProviderWorkspaceConfig = useRef<ProviderWorkspaceConfig>(loadProviderWorkspaceConfig(workspaceRoot));
   const initialLayeredConfig = useRef<LayeredConfigResult | null>(null);
   if (initialLayeredConfig.current === null) {
@@ -550,6 +548,9 @@ export function App({ launchArgs }: AppProps) {
   const [planFlow, setPlanFlow] = useState<PlanFlowState>(createInitialPlanFlowState);
   const [initialRevisionText, setInitialRevisionText] = useState("");
   const [updateCheckResult, setUpdateCheckResult] = useState<UpdateCheckResult | null>(null);
+  const [startupUpdateDismissed, setStartupUpdateDismissed] = useState(false);
+  // Launcher path is fixed for the process lifetime, so detect once.
+  const globalPackageManager = useMemo(() => detectGlobalPackageManager(), []);
   // Transcript mode leaves mouse reporting off so wheel/trackpad input scrolls
   // the terminal emulator's native scrollback instead of an in-app viewport.
   const mouseCapture = (mouseOverride ?? (terminalMouseMode === "wheel")) && !isMouseIdle;
@@ -1625,54 +1626,53 @@ export function App({ launchArgs }: AppProps) {
   // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [workspaceRoot]);
 
-  // Non-blocking background update check — runs once at startup.
+  // Non-blocking background update check — fetches npm on every interactive startup.
   useEffect(() => {
     const ucSettings = initialSettings.current.updateCheck ?? DEFAULT_UPDATE_CHECK_SETTINGS;
     if (!shouldRunStartupUpdateCheck(process.env, ucSettings.enabled)) return;
 
-    const timer = setTimeout(() => {
-      void (async () => {
-        try {
-          const cache = loadUpdateCheckCache();
-          if (cache && isCacheValid(cache, ucSettings.intervalHours, APP_VERSION)) {
-            if (cache.updateAvailable && cache.latestVersion) {
-              setUpdateCheckResult({
-                status: "update-available",
-                currentVersion: cache.currentVersion,
-                latestVersion: cache.latestVersion,
-                checkedAt: cache.lastChecked,
-              });
-              if (cache.latestVersion !== skippedUpdateVersionRef.current) {
-                setScreen("update-prompt");
-              }
-            }
-            return;
-          }
-          const result = await checkForUpdates({ enabled: true });
-          if (result.status !== "error") {
-            setUpdateCheckResult(result);
-            saveUpdateCheckCache({
-              lastChecked: result.checkedAt,
-              currentVersion: result.currentVersion,
-              latestVersion: result.latestVersion,
-              updateAvailable: result.status === "update-available",
-            });
-            if (result.status === "update-available" && result.latestVersion) {
-              if (result.latestVersion !== skippedUpdateVersionRef.current) {
-                setScreen("update-prompt");
-              }
-            }
-          }
-        } catch {
-          // Never crash the TUI on a failed update check.
-        }
-      })();
-    }, 2000);
-
-    return () => clearTimeout(timer);
+    void (async () => {
+      const cache = loadUpdateCheckCache();
+      try {
+        const result = await checkForUpdates({ enabled: true });
+        if (result.status === "error") {
+          // A previously confirmed update is still useful when npm is briefly
+          // unreachable, but it must never suppress the next fresh startup check.
+          if (cache?.updateAvailable && cache.latestVersion && isCacheForRunningVersion(cache, APP_VERSION)) {
+            setUpdateCheckResult({
+              status: "update-available",
+              currentVersion: cache.currentVersion,
+              latestVersion: cache.latestVersion,
+              checkedAt: cache.lastChecked,
+              source: "cache",
+            });
+          }
+          return;
+        }
+
+        setUpdateCheckResult(result);
+        saveUpdateCheckCache({
+          lastChecked: result.checkedAt,
+          currentVersion: result.currentVersion,
+          latestVersion: result.latestVersion,
+          updateAvailable: result.status === "update-available",
+        });
+      } catch {
+        // Never crash the TUI on a failed update check.
+      }
+    })();
   // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
+  // A startup update prompt must not interrupt an active run or another panel.
+  // Keep the result until the user returns to the idle main screen instead.
+  useEffect(() => {
+    if (startupUpdateDismissed || busy || screen !== "main") return;
+    if (updateCheckResult?.status === "update-available" && updateCheckResult.latestVersion) {
+      setScreen("update-prompt");
+    }
+  }, [busy, screen, startupUpdateDismissed, updateCheckResult]);
+
   // Track clear epoch to suppress stale command result events
   useEffect(() => {
     clearEpochRef.current = sessionState.clearEpoch;
@@ -2160,32 +2160,10 @@ export function App({ launchArgs }: AppProps) {
   }, [applyWorkspaceDisplayMode, showBusyLoader, terminalMouseMode, terminalTitleMode, workspaceDisplayMode]);
 
   const handleSkipUpdateForSession = useCallback(() => {
+    setStartupUpdateDismissed(true);
     setScreen("main");
   }, []);
 
-  const handleSkipUpdateVersion = useCallback((version: string) => {
-    initialSettings.current.updateCheck = {
-      ...initialSettings.current.updateCheck,
-      skippedUpdateVersion: version,
-    };
-    saveSettings({
-      ui: {
-        layoutStyle: initialSettings.current.ui.layoutStyle,
-        theme: themeSelection.committedTheme,
-        workspaceDisplayMode,
-        terminalTitleMode,
-        showBusyLoader,
-        terminalMouseMode,
-        customTheme,
-      },
-      auth: { preference: authPreference },
-      header: headerConfig,
-      updateCheck: initialSettings.current.updateCheck,
-    });
-    skippedUpdateVersionRef.current = version;
-    setScreen("main");
-  }, [authPreference, customTheme, headerConfig, showBusyLoader, terminalMouseMode, terminalTitleMode, themeSelection.committedTheme, workspaceDisplayMode]);
-
   const setApprovalPolicyWithNotice = useCallback((nextValue: RuntimeApprovalPolicy) => {
     const gate = guardConfigMutation("mode", busy);
     if (!gate.allowed) {
@@ -4435,7 +4413,10 @@ export function App({ launchArgs }: AppProps) {
             if (freshResult?.status === "update-available" && freshResult.latestVersion) {
               setScreen("update-prompt");
             } else {
-              appendSystemEvent("Update", formatUpdateInstructions(freshResult));
+              appendSystemEvent(
+                "Update",
+                formatUpdateInstructions(freshResult, getUpdateCommand(globalPackageManager).displayCommand),
+              );
             }
           })();
           return;
@@ -4527,6 +4508,7 @@ export function App({ launchArgs }: AppProps) {
     dispatchSession,
     findUserPromptForTurn,
     focusManager,
+    globalPackageManager,
     handleCopy,
     handleClear,
     handleQuit,
@@ -4751,8 +4733,12 @@ export function App({ launchArgs }: AppProps) {
           clearCount={sessionState.clearCount}
           headerConfig={effectiveHeaderConfig}
           updateAvailable={
-            updateCheckResult?.status === "update-available" && updateCheckResult.latestVersion
-              ? { latestVersion: updateCheckResult.latestVersion, currentVersion: updateCheckResult.currentVersion }
+            screen !== "update-prompt" && updateCheckResult?.status === "update-available" && updateCheckResult.latestVersion
+              ? {
+                latestVersion: updateCheckResult.latestVersion,
+                currentVersion: updateCheckResult.currentVersion,
+                updateCommand: getUpdateCommand(globalPackageManager).displayCommand,
+              }
               : null
           }
           panel={
@@ -5010,9 +4996,9 @@ export function App({ launchArgs }: AppProps) {
                 focusId={FOCUS_IDS.updatePrompt}
                 currentVersion={updateCheckResult.currentVersion}
                 latestVersion={updateCheckResult.latestVersion}
-                onSkip={handleSkipUpdateForSession}
-                onSkipUntilNextVersion={handleSkipUpdateVersion}
-              />
+                packageManager={globalPackageManager}
+                onSkip={handleSkipUpdateForSession}
+              />
             )}
             </>
           }

package/src/commands/handler.ts

@@ -391,12 +391,12 @@ function buildHelpMessage(context: CommandContext): string {
     `  Current reasoning: ${formatReasoningLabel(context.runtime.reasoningLevel)}`,
     `  Current plan mode: ${context.runtime.planMode ? "Enabled" : "Disabled"}`,
     "  /copy              Copy last response to clipboard",
-    "  /update [check]    Show update status and instructions for updating Codexa",
+    "  /update [status]   Check for updates and install the latest Codexa (status: cached result only)",
     "  /help              Show this help",
-    "",
-    "Local development:",
-    "  npm run install:dev-bin  Install the codexa-dev command",
-    "  codexa-dev               Run this repo without replacing codexa",
+    "",
+    "Local development:",
+    "  npm run install:dev-bin  Install the codexa-dev command",
+    "  codexa-dev               Run this repo without replacing codexa",
     "",
     "Shortcuts:",
     "  Ctrl+B    Open backend picker",
@@ -515,11 +515,11 @@ export function handleCommand(text: string, context: CommandContext): CommandRes
             message: `Unknown reasoning level for ${context.runtime.model}: ${arg}. Valid: ${valid}`,
           };
         }
-        return {
-          action: "reasoning",
-          value: normalized,
-          message: `Reasoning level switched to ${formatReasoningLabel(normalized)} (runtime metadata unavailable; unverified until runtime)`,
-        };
+        return {
+          action: "reasoning",
+          value: normalized,
+          message: `Reasoning level switched to ${formatReasoningLabel(normalized)} (runtime metadata unavailable; unverified until runtime)`,
+        };
       }
 
       case "plan": {
@@ -846,7 +846,9 @@ export function handleCommand(text: string, context: CommandContext): CommandRes
         return { action: "help", message: buildHelpMessage(context) };
 
       case "update":
-        return { action: "update", value: normalizedArg || "status" };
+        // Bare /update forces a fresh registry check; /update status is the
+        // explicit no-network path that reuses the cached/in-memory result.
+        return { action: "update", value: normalizedArg || "check" };
 
       default:
         return {

package/src/config/appVersion.ts

@@ -0,0 +1,65 @@
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { APP_VERSION as BUILD_INFO_VERSION } from "./buildInfo.js";
+
+// Leaf module: must not import settings.ts or anything under src/core/version
+// (settings.ts re-exports APP_VERSION from here, so that would be a cycle).
+
+const CODEXA_PACKAGE_NAME = "@golba98/codexa";
+const SEMVER_RE = /^\d+\.\d+\.\d+(-[\w.]+)?$/;
+
+function readPackageVersion(packageJsonPath: string, requireName?: string): string | null {
+  try {
+    const parsed = JSON.parse(readFileSync(packageJsonPath, "utf8")) as {
+      name?: unknown;
+      version?: unknown;
+    };
+    if (requireName !== undefined && parsed.name !== requireName) return null;
+    if (typeof parsed.version !== "string") return null;
+    const version = parsed.version.trim();
+    return SEMVER_RE.test(version) ? version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolves the version of the running Codexa install:
+ * 1. `CODEXA_PACKAGE_ROOT` (set by bin/codexa.js) → that package.json's version
+ * 2. Walk up from this module for a package.json named "@golba98/codexa" (local dev)
+ * 3. The committed buildInfo.ts APP_VERSION as the last resort
+ *
+ * `startDir` overrides the walk-up starting directory (test seam).
+ */
+export function resolveAppVersion(
+  env: NodeJS.ProcessEnv = process.env,
+  startDir?: string,
+): string {
+  const packageRoot = env.CODEXA_PACKAGE_ROOT?.trim();
+  if (packageRoot) {
+    const version = readPackageVersion(join(packageRoot, "package.json"));
+    if (version) return version;
+  }
+
+  let dir = startDir ?? dirname(fileURLToPath(import.meta.url));
+  for (;;) {
+    const version = readPackageVersion(join(dir, "package.json"), CODEXA_PACKAGE_NAME);
+    if (version) return version;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return BUILD_INFO_VERSION;
+}
+
+let cachedVersion: string | null = null;
+
+/** Cached form of resolveAppVersion() — the installed version cannot change mid-process. */
+export function getAppVersion(): string {
+  if (cachedVersion === null) {
+    cachedVersion = resolveAppVersion();
+  }
+  return cachedVersion;
+}

package/src/config/buildInfo.ts

@@ -1,3 +1,3 @@
 // Generated by scripts/gen-build-info.mjs — do not edit manually.
-export const BUILD_COMMIT = "aaffb655176a0acb1bc7800ddbb3e6402e5933f4" as const;
-export const APP_VERSION = "1.0.5" as const;
+export const BUILD_COMMIT = "8a275f0a19434d0cf59ff59cebe1aae734559bde" as const;
+export const APP_VERSION = "1.0.6" as const;

package/src/config/settings.ts

@@ -9,7 +9,11 @@ function smartJoin(base: string, ...parts: string[]): string {
   return isWindowsStylePath(base) ? win32.join(base, ...parts) : join(base, ...parts);
 }
 
-export { APP_VERSION } from "./buildInfo.js";
+import { getAppVersion } from "./appVersion.js";
+
+// Authoritative runtime version: resolved from the installed package.json at
+// startup (buildInfo.ts is only the committed fallback and can drift).
+export const APP_VERSION: string = getAppVersion();
 export const APP_NAME = "Codexa";
 export const DEFAULT_BACKEND = "codex-subprocess";
 export const DEFAULT_MODEL = "gpt-5.4";

package/src/config/updateCheckCache.ts

@@ -9,11 +9,16 @@ export interface UpdateCheckCache {
   updateAvailable: boolean;
 }
 
-const CACHE_FILE = join(homedir(), ".codexa-update-check.json");
+// Resolved per call (not at module load) so HOME changes — e.g. test isolation —
+// are honored. See the same pattern in src/core/models/providerModelCache.ts.
+export function getUpdateCheckCacheFilePath(): string {
+  const home = process.env.USERPROFILE ?? process.env.HOME ?? homedir();
+  return join(home, ".codexa-update-check.json");
+}
 
-export function loadUpdateCheckCache(): UpdateCheckCache | null {
+export function loadUpdateCheckCache(filePath = getUpdateCheckCacheFilePath()): UpdateCheckCache | null {
   try {
-    const text = readFileSync(CACHE_FILE, "utf-8");
+    const text = readFileSync(filePath, "utf-8");
     const data = JSON.parse(text) as Record<string, unknown>;
     if (typeof data.lastChecked !== "number") return null;
     if (typeof data.currentVersion !== "string") return null;
@@ -28,12 +33,12 @@ export function loadUpdateCheckCache(): UpdateCheckCache | null {
   }
 }
 
-export function saveUpdateCheckCache(cache: UpdateCheckCache): void {
+export function saveUpdateCheckCache(cache: UpdateCheckCache, filePath = getUpdateCheckCacheFilePath()): void {
   try {
-    mkdirSync(dirname(CACHE_FILE), { recursive: true });
-    const tmp = `${CACHE_FILE}.tmp`;
+    mkdirSync(dirname(filePath), { recursive: true });
+    const tmp = `${filePath}.tmp`;
     writeFileSync(tmp, JSON.stringify(cache, null, 2), "utf-8");
-    renameSync(tmp, CACHE_FILE);
+    renameSync(tmp, filePath);
   } catch {
     // Best-effort — never crash on cache write failure.
   }
@@ -43,6 +48,11 @@ function stripV(v: string): string {
   return v.startsWith("v") ? v.slice(1) : v;
 }
 
+/** Returns true when a cache entry was created by the running Codexa version. */
+export function isCacheForRunningVersion(cache: UpdateCheckCache, runningVersion: string): boolean {
+  return stripV(cache.currentVersion) === stripV(runningVersion);
+}
+
 /**
  * Returns true only when the cache is still usable:
  * - `runningVersion` matches the version the cache was written for (version-mismatch = stale)
@@ -54,7 +64,7 @@ export function isCacheValid(
   runningVersion?: string,
 ): boolean {
   if (runningVersion !== undefined) {
-    if (stripV(cache.currentVersion) !== stripV(runningVersion)) {
+    if (!isCacheForRunningVersion(cache, runningVersion)) {
       return false;
     }
   }

package/src/core/models/providerModelCache.ts

@@ -46,30 +46,18 @@ function readCacheFile(cacheFile: string): ProviderModelCacheFile | null {
   }
 }
 
-// A model id is passed straight to a provider CLI, so it must be a bare token.
-// Discovery scrapes CLI output, and a buggy build can bake an ANSI escape into
-// an id (e.g. "claude-fable-5\x1b[1m"). Reject rather than repair: a cached id
-// we cannot vouch for is dropped so discovery re-probes for a clean one.
-const VALID_MODEL_ID = /^[A-Za-z0-9._:\/-]+$/;
-
-function isUsableModel(model: unknown): model is ProviderModel {
-  if (typeof model !== "object" || model === null) {
-    return false;
-  }
-  const candidate = model as ProviderModel;
-  return typeof candidate.id === "string"
-    && typeof candidate.modelId === "string"
-    && typeof candidate.label === "string"
-    && VALID_MODEL_ID.test(candidate.id)
-    && VALID_MODEL_ID.test(candidate.modelId);
-}
-
 function isValidEntry(entry: unknown): entry is CachedProviderModels {
   if (typeof entry !== "object" || entry === null) {
     return false;
   }
   const candidate = entry as CachedProviderModels;
-  return typeof candidate.discoveredAt === "number" && Array.isArray(candidate.models);
+  return typeof candidate.discoveredAt === "number"
+    && Array.isArray(candidate.models)
+    && candidate.models.every((model) =>
+      typeof model === "object" && model !== null
+      && typeof model.id === "string"
+      && typeof model.modelId === "string"
+      && typeof model.label === "string");
 }
 
 export function loadCachedProviderModels(
@@ -78,14 +66,10 @@ export function loadCachedProviderModels(
 ): CachedProviderModels | null {
   const cache = readCacheFile(cacheFile);
   const entry = cache?.providers?.[providerId];
-  if (!entry || !isValidEntry(entry)) {
-    return null;
-  }
-  const models = entry.models.filter(isUsableModel);
-  if (models.length === 0) {
+  if (!entry || !isValidEntry(entry) || entry.models.length === 0) {
     return null;
   }
-  return { discoveredAt: entry.discoveredAt, models };
+  return entry;
 }
 
 export function saveCachedProviderModels(

package/src/core/providerRuntime/antigravity.ts

@@ -165,7 +165,18 @@ export function getAgyModelSelector(
 }
 
 export function getAntigravityModelLabel(modelId: string): string {
-  return getActiveAgyModels().find((m) => m.id === modelId)?.label ?? modelId;
+  const discovered = getActiveAgyModels().find((m) => m.id === modelId || m.modelId === modelId);
+  if (discovered) return discovered.label;
+
+  const normalizedId = migrateAntigravityLegacyModelId(modelId).modelId;
+  const knownLabels: Record<string, string> = {
+    "gemini-3.5-flash": "Gemini 3.5 Flash",
+    "gemini-3.1-pro": "Gemini 3.1 Pro",
+    "claude-sonnet-4.6-thinking": "Claude Sonnet 4.6 (Thinking)",
+    "claude-opus-4.6-thinking": "Claude Opus 4.6 (Thinking)",
+    "gpt-oss-120b-medium": "GPT-OSS 120B",
+  };
+  return knownLabels[normalizedId] ?? modelId;
 }
 
 // ---------------------------------------------------------------------------

package/src/core/providerRuntime/registry.ts

@@ -199,17 +199,21 @@ export function resolveActiveProviderRoute(options: {
       route.modelId = resolveGeminiModelId(route.modelSelection);
     } else if (route.providerId === "google") {
       route.modelId = normalizeGeminiModelId(route.modelId);
-    } else if (route.providerId === "anthropic") {
-      const discovery = discoverProviderModels("anthropic");
+    } else if (route.providerId === "anthropic") {
+      const discovery = discoverProviderModels("anthropic");
       const stillAvailable = discovery.models.some((model) =>
         model.modelId === route.modelId ||
         model.id === route.modelId ||
         model.canonicalId === route.modelId
       );
-      const hasNonFallbackModels = discovery.models.some((model) => model.source !== "fallback");
-      if (discovery.status === "ready" && hasNonFallbackModels && discovery.models.length > 0 && !stillAvailable) {
-        route.modelId = discovery.models[0]!.modelId;
-      }
+      const hasNonFallbackModels = discovery.models.some((model) => model.source !== "fallback");
+      // Preserve explicit versioned Claude IDs even when the current discovery
+      // output does not advertise that historical model. Short aliases are the
+      // values that need migration to the first currently discovered model.
+      const isKnownShortAlias = ANTHROPIC_FALLBACK_MODELS.some((model) => model.modelId === route.modelId);
+      if (discovery.status === "ready" && hasNonFallbackModels && discovery.models.length > 0 && !stillAvailable && isKnownShortAlias) {
+        route.modelId = discovery.models[0]!.modelId;
+      }
     } else if (route.providerId === "local") {
       const discovery = discoverProviderModels("local");
       const selectedModel = typeof discovery.diagnostics?.selectedModel === "string"

package/src/core/version/packageManager.ts

@@ -0,0 +1,119 @@
+import type { ChildProcess } from "child_process";
+import {
+  runCommand,
+  runShellCommand,
+  type CommandResult,
+  type CommandSpec,
+  type CommandStreamHandlers,
+} from "../process/CommandRunner.js";
+import { CODEXA_NPM_PACKAGE } from "./updateCheck.js";
+
+export type GlobalPackageManager = "npm" | "pnpm" | "yarn" | "bun";
+
+const UPDATE_TIMEOUT_MS = 300_000;
+
+const PACKAGE_SPEC = `${CODEXA_NPM_PACKAGE}@latest`;
+
+// Yarn Classic only — Yarn Berry (v2+) removed `yarn global`, but Berry installs
+// don't produce the global launcher paths we detect, so Classic is the only case.
+const UPDATE_ARGV: Record<GlobalPackageManager, readonly string[]> = {
+  npm: ["npm", "install", "-g", PACKAGE_SPEC],
+  pnpm: ["pnpm", "add", "-g", PACKAGE_SPEC],
+  yarn: ["yarn", "global", "add", PACKAGE_SPEC],
+  bun: ["bun", "add", "-g", PACKAGE_SPEC],
+};
+
+/**
+ * Infers which package manager owns the global Codexa install from the
+ * launcher script location (CODEXA_LAUNCHER_SCRIPT, set by bin/codexa.js).
+ */
+export function detectGlobalPackageManager(
+  env: NodeJS.ProcessEnv = process.env,
+  launcherPathOverride?: string,
+): GlobalPackageManager {
+  const launcherPath = launcherPathOverride ?? env.CODEXA_LAUNCHER_SCRIPT ?? process.argv[1] ?? "";
+  const normalized = launcherPath.toLowerCase().replace(/\\/g, "/");
+  if (!normalized) return "npm";
+
+  if (normalized.includes("pnpm")) return "pnpm";
+  if (normalized.includes("/.bun/") || normalized.includes("/bun/install/global/")) return "bun";
+  if (normalized.includes("/.yarn/") || normalized.includes("/yarn/") || normalized.includes(".config/yarn")) {
+    return "yarn";
+  }
+  return "npm";
+}
+
+export function getUpdateCommand(pm: GlobalPackageManager): {
+  displayCommand: string;
+  argv: readonly string[];
+} {
+  const argv = UPDATE_ARGV[pm];
+  return { displayCommand: argv.join(" "), argv };
+}
+
+export interface RunUpdateCommandDeps {
+  platform?: NodeJS.Platform;
+  cwd?: string;
+  runCommandFn?: (
+    spec: CommandSpec,
+    handlers?: CommandStreamHandlers,
+  ) => { child: ChildProcess; result: Promise<CommandResult>; cancel: () => void };
+  runShellCommandFn?: (
+    command: string,
+    options: Pick<CommandSpec, "cwd" | "env" | "timeoutMs">,
+    handlers?: CommandStreamHandlers,
+  ) => { child: ChildProcess; result: Promise<CommandResult>; cancel: () => void };
+}
+
+/**
+ * Runs the global update command for the detected package manager.
+ * POSIX spawns the argv directly; Windows routes the constant, whitelisted
+ * command string through cmd.exe so .cmd shims (npm.cmd, pnpm.cmd) resolve —
+ * spawning them without a shell throws EINVAL on Node >= 18.20.
+ */
+export function runUpdateCommand(
+  pm: GlobalPackageManager,
+  handlers: CommandStreamHandlers = {},
+  deps: RunUpdateCommandDeps = {},
+): { result: Promise<CommandResult>; cancel: () => void } {
+  const platform = deps.platform ?? process.platform;
+  const cwd = deps.cwd ?? process.cwd();
+  const { displayCommand, argv } = getUpdateCommand(pm);
+
+  if (platform === "win32") {
+    const runShell = deps.runShellCommandFn ?? runShellCommand;
+    const { result, cancel } = runShell(displayCommand, { cwd, timeoutMs: UPDATE_TIMEOUT_MS }, handlers);
+    return { result, cancel };
+  }
+
+  const run = deps.runCommandFn ?? runCommand;
+  const { result, cancel } = run(
+    { executable: argv[0]!, args: [...argv.slice(1)], cwd, timeoutMs: UPDATE_TIMEOUT_MS },
+    handlers,
+  );
+  return { result, cancel };
+}
+
+const PERMISSION_STDERR_RE = /EACCES|EPERM|permission denied/i;
+
+/** npm reports EACCES via stderr with a nonzero exit, not as a spawn error. */
+export function isPermissionError(result: CommandResult): boolean {
+  if (result.errorCode === "EACCES" || result.errorCode === "EPERM") return true;
+  return result.exitCode !== 0 && PERMISSION_STDERR_RE.test(result.stderr);
+}
+
+export function formatPermissionGuidance(pm: GlobalPackageManager): string {
+  const { displayCommand } = getUpdateCommand(pm);
+  const lines = [
+    `${pm} could not write to its global package directory, so the update was not installed.`,
+  ];
+  if (pm === "npm") {
+    lines.push(
+      "Check where global packages are installed with `npm config get prefix` and make sure that directory is writable by your user, or switch to a user-writable prefix (for example `npm config set prefix ~/.npm-global`, then add its bin directory to PATH).",
+    );
+  } else {
+    lines.push(`Make sure the ${pm} global package directory is writable by your user.`);
+  }
+  lines.push(`You can also run the command manually in a terminal with the right permissions: ${displayCommand}`);
+  return lines.join("\n");
+}

package/src/core/version/updateCheck.ts

@@ -154,7 +154,10 @@ export async function checkForUpdates(
   }
 }
 
-export function formatUpdateInstructions(result: UpdateCheckResult | null): string {
+export function formatUpdateInstructions(
+  result: UpdateCheckResult | null,
+  updateCommand: string = CODEXA_UPDATE_COMMAND,
+): string {
   const current = result?.currentVersion ?? APP_VERSION;
   const latest = result?.latestVersion ?? "unknown";
 
@@ -166,21 +169,24 @@ export function formatUpdateInstructions(result: UpdateCheckResult | null): stri
     ].join("\n");
   }
 
-  let statusLine: string;
-  if (result?.status === "update-available" && result.latestVersion) {
-    statusLine = `Update available: Codexa ${formatVersionLabel(result.latestVersion)}`;
-  } else if (result?.status === "up-to-date") {
-    statusLine = "Already up to date.";
-  } else {
-    statusLine = "Status unknown — could not reach npm registry.";
+  if (result?.status === "up-to-date") {
+    return [
+      "Codexa is up to date.",
+      `Current installed version: ${current}`,
+      `npm latest version:        ${latest}`,
+    ].join("\n");
   }
 
+  const statusLine = result?.status === "update-available" && result.latestVersion
+    ? `Update available: Codexa ${formatVersionLabel(result.latestVersion)}`
+    : "Status unknown — could not reach npm registry.";
+
   return [
     `Current installed version: ${current}`,
     `npm latest version:        ${latest}`,
     `Status:          ${statusLine}`,
     "",
-    `Run: ${CODEXA_UPDATE_COMMAND}`,
+    `Run: ${updateCommand}`,
   ].join("\n");
 }
 

package/src/test/runtimeTestUtils.ts

@@ -1,11 +1,4 @@
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
 import { resolveRuntimeConfig, type RuntimeConfig, DEFAULT_RUNTIME_CONFIG, type ResolvedRuntimeConfig } from "../config/runtimeConfig.js";
-import type { ProviderId } from "../core/providerLauncher/types.js";
-import { resetAnthropicRouteValidationCacheForTests } from "../core/providerRuntime/anthropic.js";
-import { resetAntigravityRouteValidationCacheForTests } from "../core/providerRuntime/antigravity.js";
-import type { ProviderModel } from "../core/providerRuntime/types.js";
 
 export function makeResolvedRuntime(overrides: Partial<RuntimeConfig> = {}): ResolvedRuntimeConfig {
   return resolveRuntimeConfig({
@@ -19,86 +12,3 @@ export function makeResolvedRuntime(overrides: Partial<RuntimeConfig> = {}): Res
 }
 
 export const TEST_RUNTIME = makeResolvedRuntime();
-
-function agyModel(id: string, label: string): ProviderModel {
-  return {
-    id,
-    modelId: id,
-    label,
-    description: null,
-    defaultReasoningLevel: null,
-    supportedReasoningLevels: null,
-    source: "discovered",
-  };
-}
-
-/**
- * The catalog `agy models` reports on a configured machine. Antigravity resolves
- * its status, backend kind, and model labels from whatever discovery last found,
- * so tests that assert on any of those need a catalog seeded rather than
- * whatever happens to be installed.
- */
-export const ANTIGRAVITY_FIXTURE_MODELS: readonly ProviderModel[] = [
-  agyModel("gemini-3.5-flash", "Gemini 3.5 Flash"),
-  agyModel("gemini-3.1-pro", "Gemini 3.1 Pro"),
-  agyModel("claude-sonnet-4-6", "Claude Sonnet 4.6"),
-  agyModel("claude-sonnet-4-6-think", "Claude Sonnet 4.6 (Thinking)"),
-  agyModel("gpt-oss-120b", "GPT-OSS 120B"),
-];
-
-/**
- * Drops every provider's in-memory discovery result.
- *
- * Bun shares the module registry across test files, so a catalog discovered by
- * one test (some probe the real `claude` / `agy` CLIs) otherwise survives into
- * the next and takes precedence over both the cache and the fallback list —
- * making assertions depend on file order and on what is installed locally.
- */
-export function resetProviderDiscoveryState(): void {
-  resetAntigravityRouteValidationCacheForTests();
-  resetAnthropicRouteValidationCacheForTests();
-}
-
-/**
- * Runs `fn` with HOME pointed at a throwaway directory holding only the provider
- * model cache built from `seed`.
- *
- * Provider discovery reads `~/.codexa-model-cache.json`, so a test that calls it
- * without this is asserting against the developer's own machine — it passes with
- * a warm cache and fails on a cold one (or in CI). HOME is read per call (see
- * `getProviderModelCacheFile`), so redirecting the env var here is enough.
- *
- * Antigravity's in-memory discovery is reset around the body as well: Bun shares
- * the module registry across test files, so a catalog discovered by one file
- * otherwise leaks into the next and takes precedence over the seeded cache,
- * making results depend on file order. Seed exactly what the assertions need.
- */
-export function withSeededModelCache<T>(
-  seed: Partial<Record<ProviderId, readonly ProviderModel[]>>,
-  fn: () => T,
-): T {
-  const tempHome = mkdtempSync(join(tmpdir(), "codexa-test-home-"));
-  const previousHome = process.env.HOME;
-  const previousUserProfile = process.env.USERPROFILE;
-  try {
-    process.env.HOME = tempHome;
-    delete process.env.USERPROFILE;
-    const providers = Object.fromEntries(
-      Object.entries(seed).map(([providerId, models]) => [providerId, { discoveredAt: 1, models }]),
-    );
-    writeFileSync(
-      join(tempHome, ".codexa-model-cache.json"),
-      `${JSON.stringify({ version: 1, providers }, null, 2)}\n`,
-      "utf8",
-    );
-    resetProviderDiscoveryState();
-    return fn();
-  } finally {
-    if (previousHome === undefined) delete process.env.HOME;
-    else process.env.HOME = previousHome;
-    if (previousUserProfile === undefined) delete process.env.USERPROFILE;
-    else process.env.USERPROFILE = previousUserProfile;
-    rmSync(tempHome, { recursive: true, force: true });
-    resetProviderDiscoveryState();
-  }
-}

package/src/ui/chrome/TopHeader.tsx

@@ -2,7 +2,7 @@ import React, { memo } from "react";
 import { Box, Text } from "ink";
 import { HEADER_CONFIG_DEFAULTS, type HeaderConfig } from "../../config/settings.js";
 import { formatCodexaBrandLabel } from "../../core/version/channel.js";
-import { formatVersionLabel } from "../../core/version/updateCheck.js";
+import { CODEXA_UPDATE_COMMAND, formatVersionLabel } from "../../core/version/updateCheck.js";
 import type { RuntimeSummary } from "../../config/runtimeConfig.js";
 import type { CodexAuthState } from "../../core/auth/codexAuth.js";
 import { getAuthStateLabel } from "../../core/auth/codexAuth.js";
@@ -58,6 +58,7 @@ type HeaderMetadataLine = { key: string; text: string; color: string; bold: bool
 export interface UpdateAvailableInfo {
   latestVersion: string;
   currentVersion: string;
+  updateCommand?: string;
 }
 
 interface TopHeaderProps {
@@ -343,6 +344,7 @@ export function TopHeader({
                   <UpdateAvailableCard
                     latestVersion={updateAvailable.latestVersion}
                     currentVersion={updateAvailable.currentVersion}
+                    updateCommand={updateAvailable.updateCommand}
                     width={metadataWidth}
                   />
                   <Box height={UPDATE_CARD_GAP_ROWS} />
@@ -359,7 +361,7 @@ export function TopHeader({
             )}
             {metadataColumn}
             {updateAvailable && (
-              <Text color={theme.warning} wrap="truncate">{`Update available: Codexa ${formatVersionLabel(updateAvailable.latestVersion)} — Run: npm install -g @golba98/codexa@latest`}</Text>
+              <Text color={theme.warning} wrap="truncate">{`Update available: Codexa ${formatVersionLabel(updateAvailable.latestVersion)} — Run: ${updateAvailable.updateCommand ?? CODEXA_UPDATE_COMMAND}`}</Text>
             )}
           </Box>
         )}

package/src/ui/chrome/UpdateAvailableCard.tsx

@@ -10,13 +10,14 @@ export const UPDATE_CARD_ROWS = UPDATE_CARD_CONTENT_ROWS + 2; // +2 for top/bott
 export interface UpdateAvailableCardProps {
   latestVersion: string;
   currentVersion: string;
+  updateCommand?: string;
   /** Total box width including borders. Long lines are truncated to fit. */
   width?: number;
 }
 
-export function UpdateAvailableCard({ latestVersion, currentVersion, width }: UpdateAvailableCardProps) {
+export function UpdateAvailableCard({ latestVersion, currentVersion, updateCommand = CODEXA_UPDATE_COMMAND, width }: UpdateAvailableCardProps) {
   const theme = useTheme();
-  const command = `Run: ${CODEXA_UPDATE_COMMAND}`;
+  const command = `Run: ${updateCommand}`;
   // Inner content width = boxWidth - 2 (left/right border cols)
   const innerWidth = width !== undefined ? Math.max(8, width - 2) : undefined;
 

package/src/ui/input/slashCommands.ts

@@ -24,6 +24,7 @@ export const SLASH_COMMANDS = [
   { cmd: "/auth", desc: "Manage authentication" },
   { cmd: "/workspace", desc: "Show the locked workspace" },
   { cmd: "/copy", desc: "Copy the full conversation transcript to clipboard" },
+  { cmd: "/update", desc: "Check for updates and install the latest Codexa" },
   { cmd: "/mouse", desc: "Toggle mouse capture for wheel scrolling (off by default)" },
   { cmd: "/exit", desc: "Quit the application" },
 ] as const satisfies readonly SlashCommandSuggestion[];

package/src/ui/panels/UpdatePromptPanel.tsx

@@ -1,31 +1,45 @@
 import React, { useEffect, useRef, useState } from "react";
 import { Box, Text, useFocus, useInput } from "ink";
-import { spawn } from "child_process";
 import { useTheme } from "../theme.js";
-import { CODEXA_NPM_PACKAGE, CODEXA_UPDATE_COMMAND, formatVersionLabel } from "../../core/version/updateCheck.js";
+import { CODEXA_NPM_PACKAGE, formatVersionLabel } from "../../core/version/updateCheck.js";
+import {
+  formatPermissionGuidance,
+  getUpdateCommand,
+  isPermissionError,
+  runUpdateCommand,
+  type GlobalPackageManager,
+} from "../../core/version/packageManager.js";
+import type { CommandResult, CommandStreamHandlers } from "../../core/process/CommandRunner.js";
 
 type Phase = "menu" | "running" | "done" | "error";
 
+export type RunUpdateFn = (
+  pm: GlobalPackageManager,
+  handlers?: CommandStreamHandlers,
+) => { result: Promise<CommandResult>; cancel: () => void };
+
 const MENU_ITEMS = [
   { label: "Update now" },
-  { label: "Skip" },
-  { label: "Skip until next version" },
+  { label: "Later" },
 ] as const;
 
 interface UpdatePromptPanelProps {
   focusId: string;
   currentVersion: string;
   latestVersion: string;
+  packageManager: GlobalPackageManager;
+  /** Test seam — defaults to the real cross-platform runner. */
+  runUpdate?: RunUpdateFn;
   onSkip: () => void;
-  onSkipUntilNextVersion: (version: string) => void;
 }
 
 export function UpdatePromptPanel({
   focusId,
   currentVersion,
   latestVersion,
+  packageManager,
+  runUpdate,
   onSkip,
-  onSkipUntilNextVersion,
 }: UpdatePromptPanelProps) {
   const theme = useTheme();
   const { isFocused } = useFocus({ id: focusId, autoFocus: true });
@@ -35,7 +49,7 @@ export function UpdatePromptPanel({
   const [outputLines, setOutputLines] = useState<string[]>([]);
   const [errorMessage, setErrorMessage] = useState<string | null>(null);
 
-  const spawnStartedRef = useRef(false);
+  const runStartedRef = useRef(false);
 
   useInput((input, key) => {
     if (key.escape) {
@@ -54,10 +68,8 @@ export function UpdatePromptPanel({
       if (key.return) {
         if (selectedIndex === 0) {
           setPhase("running");
-        } else if (selectedIndex === 1) {
-          onSkip();
         } else {
-          onSkipUntilNextVersion(latestVersion);
+          onSkip();
         }
         return;
       }
@@ -70,42 +82,42 @@ export function UpdatePromptPanel({
 
   useEffect(() => {
     if (phase !== "running") return;
-    if (spawnStartedRef.current) return;
-    spawnStartedRef.current = true;
+    if (runStartedRef.current) return;
+    runStartedRef.current = true;
 
-    const child = spawn("npm", ["install", "-g", `${CODEXA_NPM_PACKAGE}@latest`], {
-      shell: false,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-
-    const appendLines = (buf: Buffer) => {
-      const lines = buf.toString("utf8").split(/\r?\n/).filter(Boolean);
+    const appendLines = (text: string) => {
+      const lines = text.split(/\r?\n/).filter(Boolean);
       if (lines.length > 0) {
         setOutputLines((prev) => [...prev, ...lines]);
       }
     };
 
-    child.stdout?.on("data", appendLines);
-    child.stderr?.on("data", appendLines);
-
-    child.once("error", (err: Error) => {
-      setErrorMessage(err.message);
-      setPhase("error");
+    const runner = runUpdate ?? runUpdateCommand;
+    const { result, cancel } = runner(packageManager, {
+      onStdout: appendLines,
+      onStderr: appendLines,
     });
 
-    child.once("close", (code: number | null) => {
-      if (code === 0) {
+    let disposed = false;
+    void result.then((res) => {
+      if (disposed) return;
+      if (res.status === "completed" && res.exitCode === 0) {
         setPhase("done");
+        return;
+      }
+      if (isPermissionError(res)) {
+        setErrorMessage(formatPermissionGuidance(packageManager));
       } else {
-        setErrorMessage(`npm exited with code ${code ?? "unknown"}.`);
-        setPhase("error");
+        setErrorMessage(res.userMessage);
       }
+      setPhase("error");
     });
 
     return () => {
-      try { child.kill(); } catch { /* ignore */ }
+      disposed = true;
+      cancel();
     };
-  }, [phase]);
+  }, [phase, packageManager, runUpdate]);
 
   const footerText = phase === "menu"
     ? "Esc to close · Enter to confirm"
@@ -122,16 +134,16 @@ export function UpdatePromptPanel({
         flexDirection="column"
       >
         <Box>
-          <Text color={theme.accent} bold>{`Update available: Codexa ${formatVersionLabel(latestVersion)}`}</Text>
+          <Text color={theme.accent} bold>{`Update available: Codexa ${latestVersion}`}</Text>
         </Box>
         <Box marginTop={1}>
-          <Text color={theme.text}>{`${formatVersionLabel(currentVersion)} -> ${formatVersionLabel(latestVersion)}`}</Text>
+          <Text color={theme.text}>{`Current version: ${currentVersion}`}</Text>
         </Box>
         <Box>
           <Text color={theme.textMuted}>{`Package: ${CODEXA_NPM_PACKAGE}`}</Text>
         </Box>
         <Box>
-          <Text color={theme.textMuted}>{`Run: ${CODEXA_UPDATE_COMMAND}`}</Text>
+          <Text color={theme.textMuted}>{`Run: ${getUpdateCommand(packageManager).displayCommand}`}</Text>
         </Box>
       </Box>
 
@@ -146,19 +158,17 @@ export function UpdatePromptPanel({
       >
         {phase === "menu" && (
           <>
-            {MENU_ITEMS.map((item, index) => (
-              <Box key={item.label}>
-                <Text color={index === selectedIndex ? theme.accent : theme.textMuted}>
-                  {index === selectedIndex ? "› " : "  "}
-                </Text>
+            <Box>
+              {MENU_ITEMS.map((item, index) => (
                 <Text
+                  key={item.label}
                   color={index === selectedIndex ? theme.text : theme.textMuted}
                   bold={index === selectedIndex}
                 >
-                  {`${index + 1}. ${item.label}`}
+                  {`[ ${item.label} ]${index === 0 ? "  " : ""}`}
                 </Text>
-              </Box>
-            ))}
+              ))}
+            </Box>
           </>
         )}
 
@@ -173,7 +183,7 @@ export function UpdatePromptPanel({
 
         {phase === "done" && (
           <>
-            <Text color={theme.success}>{"Codexa was updated successfully."}</Text>
+            <Text color={theme.success}>{`Codexa ${formatVersionLabel(latestVersion)} installed successfully.`}</Text>
             <Text color={theme.textMuted}>{"Restart Codexa to use the new version."}</Text>
           </>
         )}