ima2-gen 3.25.0 → 3.26.0

package/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.26.0] - 2026-09-30
+
+### Added
+
+- **Update notices and `ima2 update`** — an npm install checks the registry for a newer ima2 at most once every 20 hours while the server runs (preview installs follow the `preview` tag) and caches the answer in `~/.ima2/version.json`. Interactive commands such as `ima2 serve`, `ima2 start` and `ima2 status` print one line when an update is waiting, and the web UI shows an update button in the top strip (a floating pill on phones) with the command to run, release notes and Dismiss. `ima2 update` installs the new version globally, restarts the login service or background server it owns and waits until the new version answers; `--check`, `--tag latest|preview`, `--yes` and `--json` are supported. After an update the CLI or the web UI says "ima2 updated to vX" once. `IMA2_DISABLE_UPDATE_CHECK=1` turns the automatic check off.
+- **Desktop update states in the menu bar** — the macOS menu bar icon gains a dot while an update is available, downloading or ready (Windows and Linux switch to the update tray icon). The tray menu, app menu, tray popup and the app window show the same state: *Download Update vX*, *Downloading Update vX… n%*, *Restart to Update (vX)*, *Up to date (vX)*. With Auto-update on, the app checks every six hours. After an update relaunch it shows "ima2 updated to vX" once, with a *What's New* link. Installs started from the app window still ask for confirmation.
+
 ## [3.25.0] - 2026-09-30
 
 ### Added

package/README.md

@@ -165,12 +165,19 @@ See [docs/DOCKER.md](docs/DOCKER.md) for compose usage, required environment, an
 
 Video generation needs Grok OAuth (option 2 or 3). If you already use GPT OAuth, run `ima2 grok login` to add video; it defaults to the manual-paste flow.
 
-To update, stop the server with Ctrl+C (or `ima2 stop` from another terminal), then run:
+To update, run:
 
 ```bash
-npm install -g ima2-gen@latest
+ima2 update            # or: ima2 update --check
 ```
 
+It installs the latest release globally, restarts the login service or background server
+it owns, and waits until the new version answers. A server running in a terminal
+(`ima2 serve`) only needs a restart afterwards. ima2 tells you when an update is waiting:
+interactive commands print one line and the web UI shows an update button in the top
+strip. Set `IMA2_DISABLE_UPDATE_CHECK=1` to turn the background check off. Without the
+command, stop the server with Ctrl+C (or `ima2 stop`) and run `npm install -g ima2-gen@latest`.
+
 Ctrl+C shuts down cleanly: it closes the database, stops child processes and releases file locks. If an install fails, check the reported npm permissions or stop the specific `ima2` process yourself; the installer does not perform broad process cleanup.
 
 Using npx instead? See [docs/NPX_QUICKSTART.md](docs/NPX_QUICKSTART.md) for the `npx ima2-gen serve` workflow.
@@ -269,6 +276,7 @@ Grok video generation defaults to canonical `grok-imagine-video-1.5`; `grok-imag
 | `ima2 logs [-n N] [-f]` | Show or follow the background server log |
 | `ima2 service <sub>` | Background service: `install`/`uninstall`/`start`/`stop`/`restart`/`status`/`logs`/`repair` — launchd on macOS, systemd user unit on Linux, auto-start on login with crash restart |
 | `ima2 setup` | Reconfigure saved auth |
+| `ima2 update [--check] [--tag latest\|preview] [--yes] [--json]` | Update a global npm install and restart the service or background server it owns; `--check` only reports |
 | `ima2 status` | Show config and OAuth status |
 | `ima2 doctor` | Diagnose Node, package, config, and auth |
 | `ima2 doctor image-probe [--json]` | Run sanitized image probes for no-image diagnostics |

package/bin/commands/update.js

@@ -0,0 +1,161 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { config } from "../../config.js";
+import { errInfo } from "../../lib/errInfo.js";
+import { markSeen } from "../../lib/updateCache.js";
+import { checkForUpdate } from "../../lib/updateCheck.js";
+import { defaultTag, isNewer, isUpdateTag, parseVersion } from "../../lib/updateVersion.js";
+import { confirmDestructiveAction } from "../lib/destructive-confirm.js";
+import { classifyInstall, defaultExec, defaultFs, installGlobal, planRestart, readInstalledVersion, runNewCli, runtimeSnapshot, serviceOwned } from "../lib/npmUpdate.js";
+const USAGE = "Usage: ima2 update [--check] [--tag latest|preview] [--yes] [--json]\nCheck or install the latest global npm release. --check never installs or restarts.";
+const RESTART_POLL_MS = 500;
+const RESTART_TIMEOUT_MS = 20_000;
+class UsageError extends Error {
+}
+function parseOptions(args, current) {
+    const opts = { check: false, yes: false, json: args.includes("--json"), tag: defaultTag(current) };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--check")
+            opts.check = true;
+        else if (arg === "--yes" || arg === "-y")
+            opts.yes = true;
+        else if (arg === "--json")
+            opts.json = true;
+        else if (arg === "--tag") {
+            const tag = args[++i];
+            if (!isUpdateTag(tag))
+                throw new UsageError("--tag must be latest or preview");
+            opts.tag = tag;
+        }
+        else
+            throw new UsageError(`Unknown option: ${arg}`);
+    }
+    return opts;
+}
+function refuseUnsupported(ctx) {
+    const install = classifyInstall(ctx.deps.pkgDir, ctx.deps.exec, ctx.deps.fs);
+    if (install.kind === "source")
+        throw new UsageError("This is a source checkout. Update it with: git pull && npm install && npm run build");
+    if (install.kind === "other")
+        throw new UsageError(`ima2 is not a global npm install (${install.reason}). Install globally with: npm i -g ima2-gen@${ctx.opts.tag}`);
+}
+async function confirmUpdate(ctx) {
+    ctx.say(`v${ctx.result.current} -> v${ctx.result.latest}`);
+    if (ctx.opts.yes)
+        return true;
+    if (ctx.opts.json || !ctx.deps.isTTY)
+        throw new UsageError("Updating requires --yes in non-interactive or --json mode.");
+    return ctx.deps.confirm("Install this update?");
+}
+function restartHint(kind) {
+    return kind === "service" ? "ima2 service restart" : "ima2 restart";
+}
+async function proveRestart(ctx) {
+    const now = ctx.deps.now ?? (() => performance.now());
+    const deadline = now() + RESTART_TIMEOUT_MS;
+    let runtime = await ctx.deps.runtime();
+    while (now() < deadline && !(runtime.live && runtime.version === ctx.result.latest)) {
+        await (ctx.deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))))(Math.min(RESTART_POLL_MS, deadline - now()));
+        runtime = await ctx.deps.runtime();
+    }
+    return runtime;
+}
+async function restartUpdated(ctx, plan, exec) {
+    if (plan.kind === "none")
+        return;
+    ctx.result.restart = { kind: plan.kind, ok: false, version: null };
+    if (plan.kind === "desktop") {
+        ctx.say("The running server belongs to the ima2 desktop app, which updates itself; it was left running.");
+        return;
+    }
+    if (plan.kind === "foreground") {
+        ctx.say(`Restart your running 'ima2 serve' (${plan.url}) to use v${ctx.result.latest}.`);
+        return;
+    }
+    try {
+        const args = plan.kind === "service" ? ["service", "restart"] : ["restart"];
+        if (runNewCli(ctx.deps.pkgDir, args, exec) === 0) {
+            const runtime = await proveRestart(ctx);
+            ctx.result.restart.version = runtime.version;
+            ctx.result.restart.ok = runtime.live && runtime.version === ctx.result.latest;
+        }
+    }
+    catch { /* Subprocess/probe errors are surfaced with the actionable restart hint below. */ }
+    if (!ctx.result.restart.ok)
+        throw new Error(`Updated to v${ctx.result.latest}, but the restart failed. Run: ${restartHint(plan.kind)}`);
+}
+async function installUpdate(ctx) {
+    const { deps, opts, result } = ctx;
+    const exec = (cmd, args, options) => deps.exec(cmd, args, { ...options, inherit: !opts.json && Boolean(options?.inherit) });
+    const owned = deps.serviceOwned(deps.pkgDir);
+    const plan = planRestart({ ...await deps.runtime(), serviceOwned: owned });
+    installGlobal(result.latest, exec, process.platform, deps.fs);
+    const installed = readInstalledVersion(deps.pkgDir, deps.fs);
+    if (installed === null || installed !== result.latest)
+        throw new Error(`npm finished but ima2 is still v${installed ?? "unknown"}`);
+    result.updated = true;
+    deps.markSeen(installed);
+    ctx.say(`Updated to v${installed}`);
+    await restartUpdated(ctx, plan, exec);
+}
+async function executeUpdate(ctx) {
+    if (!ctx.opts.check)
+        refuseUnsupported(ctx);
+    const cache = await ctx.deps.check(ctx.opts.tag);
+    if (!cache.latest_version || !parseVersion(cache.latest_version))
+        throw new Error("Update check returned an invalid version");
+    ctx.result.latest = cache.latest_version;
+    ctx.result.available = isNewer(cache.latest_version, ctx.deps.current);
+    if (!ctx.result.available) {
+        ctx.say(`Up to date (v${ctx.deps.current})`);
+        return 0;
+    }
+    if (ctx.opts.check) {
+        const command = ctx.opts.tag === "preview" ? "ima2 update --tag preview" : "ima2 update";
+        ctx.say(`Update available: v${cache.latest_version} (current v${ctx.deps.current}). Run: ${command}`);
+        return 0;
+    }
+    if (!await confirmUpdate(ctx)) {
+        ctx.say("Aborted.");
+        return 0;
+    }
+    await installUpdate(ctx);
+    return 0;
+}
+export async function runUpdate(args, deps) {
+    if (args.includes("--help") || args.includes("-h")) {
+        deps.log(USAGE);
+        return 0;
+    }
+    const json = args.includes("--json");
+    const result = { current: deps.current, latest: null, tag: defaultTag(deps.current), available: false, updated: false, restart: null };
+    let code;
+    try {
+        const opts = parseOptions(args, deps.current);
+        result.tag = opts.tag;
+        code = await executeUpdate({ deps, opts, result, say: (line) => { if (!json)
+                deps.log(line); } });
+    }
+    catch (error) {
+        result.error = errInfo(error).message;
+        code = error instanceof UsageError ? 2 : 1;
+        if (!json)
+            deps.error(`${result.error}${error instanceof UsageError ? `\n${USAGE}` : ""}`);
+    }
+    if (json)
+        deps.log(JSON.stringify(result));
+    return code;
+}
+export default async function update(args = []) {
+    const pkgDir = join(dirname(fileURLToPath(import.meta.url)), "../..");
+    const json = args.includes("--json");
+    process.exitCode = await runUpdate(args, {
+        current: readInstalledVersion(pkgDir) ?? "?", pkgDir, exec: defaultExec, fs: defaultFs,
+        check: (tag) => checkForUpdate(tag), isTTY: Boolean(process.stdin.isTTY),
+        confirm: (question) => confirmDestructiveAction(question, false),
+        serviceOwned: (dir) => serviceOwned(dir, config.storage.configDir, { log: (line) => { if (!json)
+                console.error(line); } }),
+        runtime: runtimeSnapshot, markSeen, log: console.log, error: console.error,
+    });
+}

package/bin/ima2.js

@@ -43,9 +43,7 @@ if (process.argv[2] === "doctor" && process.argv.slice(3).includes("--installati
 const { config: runtimeConfig } = await import("../config.js");
 const { doctor } = await import("./commands/doctor.js");
 const { maybePromptGithubStar } = await import("./lib/star-prompt.js");
-// Config lives under runtimeConfig.storage.configDir (honors IMA2_CONFIG_DIR).
-// Legacy installs that stored config at <packageRoot>/.ima2/config.json will be
-// migrated on first write.
+// Config honors IMA2_CONFIG_DIR; legacy package-local config migrates on first write.
 const CONFIG_DIR = runtimeConfig.storage.configDir;
 const CONFIG_FILE = runtimeConfig.storage.configFile;
 const LEGACY_CONFIG_FILE = join(ROOT, ".ima2", "config.json");
@@ -297,10 +295,7 @@ async function showStatus() {
     }
     console.log("");
 }
-/**
- * Auth verdicts for `ima2 status`. When a server is advertised, its live proxy verdict is
- * folded in: a session file can look fine while ChatGPT has already revoked it.
- */
+/** Fold an advertised server's live proxy verdict into the stored auth status. */
 async function buildAuthReport() {
     const { gptAuthStatus, grokAuthStatus } = await import("../lib/authStatus.js");
     const { resolveChatgptSession } = await import("../lib/chatgptAuth.js");
@@ -344,7 +339,7 @@ if (args.includes("-v") || args.includes("--version")) {
     console.log(pkg.version);
     exitFlushed(0);
 }
-const helpOwningCommands = ["doctor", "gen", "video", "edit", "vectorize", "ls", "show", "ps", "cancel", "session", "history", "prompt", "multimode", "node", "annotate", "canvas-versions", "metadata", "comfy", "cardnews", "inflight", "storage", "billing", "providers", "oauth", "grok", "gpt", "login", "config", "defaults", "models", "capabilities", "tools", "skill", "ping", "backfill-thumbs", "service", "start", "restart", "stop", "logs"];
+const helpOwningCommands = ["update", "doctor", "gen", "video", "edit", "vectorize", "ls", "show", "ps", "cancel", "session", "history", "prompt", "multimode", "node", "annotate", "canvas-versions", "metadata", "comfy", "cardnews", "inflight", "storage", "billing", "providers", "oauth", "grok", "gpt", "login", "config", "defaults", "models", "capabilities", "tools", "skill", "ping", "backfill-thumbs", "service", "start", "restart", "stop", "logs"];
 if (!command) {
     showHelp();
     exitFlushed(1);
@@ -353,7 +348,15 @@ if ((args.includes("-h") || args.includes("--help")) && !helpOwningCommands.incl
     showHelp();
     exitFlushed(0);
 }
+const { printUpdateNotice } = await import("./lib/updateNotice.js");
+printUpdateNotice(command, args, pkg.version);
 switch (command) {
+    case "update": {
+        const { default: updateCmd } = await import("./commands/update.js");
+        await updateCmd(args.slice(1));
+        exitFlushed(Number(process.exitCode ?? 0));
+        break;
+    }
     case "serve":
         if (args.includes("--background")) {
             const { runRuntimeCommand } = await import("./commands/runtimeCommands.js");

package/bin/lib/helpText.js

@@ -19,6 +19,7 @@ export function renderHelp(pkg) {
     doctor         Diagnose environment and setup
     open           Open web UI in browser
     reset          Reset configuration
+    update         Update ima2 to the latest npm release (--check, --tag preview)
 
   Client commands (require a running 'ima2 serve'):
     gen <prompt>   Generate image(s) from prompt  (ima2 gen --help)

package/bin/lib/npmUpdate.js

@@ -0,0 +1,149 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, win32 } from "node:path";
+import { parseVersion, PACKAGE_NAME } from "../../lib/updateVersion.js";
+import { launchdPlistPath, parseServiceConfigDir, systemdUnitPath } from "./serviceManager.js";
+export const defaultExec = (cmd, args, opts = {}) => {
+    const result = spawnSync(cmd, args, {
+        encoding: "utf8", windowsHide: true, shell: opts.shell ?? false,
+        stdio: opts.inherit ? ["inherit", "inherit", "pipe"] : ["ignore", "pipe", "pipe"],
+    });
+    const stderr = result.stderr ?? result.error?.message ?? "";
+    if (opts.inherit && stderr)
+        process.stderr.write(stderr);
+    return { status: result.status, stdout: result.stdout ?? "", stderr };
+};
+export const defaultFs = {
+    exists: existsSync, realpath: realpathSync, readFile: (p) => readFileSync(p, "utf8"),
+};
+export function npmCommand(platform = process.platform) {
+    return platform === "win32" ? "npm.cmd" : "npm";
+}
+export function npmInvocation(platform = process.platform, execPath = process.execPath, fs = defaultFs) {
+    if (platform !== "win32")
+        return { command: "npm", args: [], shell: false };
+    const paths = execPath.includes("\\") ? win32 : { dirname, join };
+    const cli = paths.join(paths.dirname(execPath), "node_modules", "npm", "bin", "npm-cli.js");
+    return fs.exists(cli) ? { command: execPath, args: [cli], shell: false }
+        : { command: npmCommand(platform), args: [], shell: true };
+}
+export function globalRoot(exec, platform = process.platform, fs = defaultFs) {
+    const npm = npmInvocation(platform, process.execPath, fs);
+    const result = exec(npm.command, [...npm.args, "root", "-g"], { inherit: false, shell: npm.shell });
+    return result.status === 0 && result.stdout.trim() ? result.stdout.trim() : null;
+}
+export function classifyInstall(pkgDir, exec, fs = defaultFs, platform = process.platform) {
+    if (fs.exists(join(pkgDir, "server.ts")) || fs.exists(join(pkgDir, ".git")))
+        return { kind: "source", pkgDir };
+    const root = globalRoot(exec, platform, fs);
+    const paths = platform === "win32" ? win32 : { join };
+    try {
+        if (root && fs.realpath(pkgDir) === fs.realpath(paths.join(root, PACKAGE_NAME)))
+            return { kind: "global", pkgDir, root };
+    }
+    catch { /* Missing paths cannot establish global-install ownership. */ }
+    const normalized = pkgDir.replaceAll("\\", "/");
+    const reason = /\/_npx\//.test(normalized) ? "npx" : /\/node_modules\//.test(normalized) ? "local" : "unknown";
+    return { kind: "other", pkgDir, reason };
+}
+export function installGlobal(version, exec, platform = process.platform, fs = defaultFs) {
+    if (!parseVersion(version))
+        throw new Error("Invalid update version");
+    const npm = npmInvocation(platform, process.execPath, fs);
+    const result = exec(npm.command, [...npm.args, "install", "--global", `${PACKAGE_NAME}@${version}`, "--no-fund", "--no-audit"], { inherit: true, shell: npm.shell });
+    if (result.status === 0)
+        return;
+    const hint = /EACCES|EPERM/.test(result.stderr) ? ` Fix the npm prefix permissions or run: sudo npm i -g ${PACKAGE_NAME}@${version}` : "";
+    throw new Error(`npm install failed (exit ${result.status ?? "unknown"}).${hint}`);
+}
+export function readInstalledVersion(pkgDir, fs = defaultFs) {
+    try {
+        const pkg = JSON.parse(fs.readFile(join(pkgDir, "package.json")));
+        return pkg !== null && typeof pkg === "object" && "version" in pkg && typeof pkg.version === "string"
+            && parseVersion(pkg.version) ? pkg.version : null;
+    }
+    catch {
+        return null; /* A missing/corrupt manifest cannot prove installation success. */
+    }
+}
+export async function runtimeSnapshot() {
+    const { collectRuntimeStatus } = await import("../commands/runtimeStatus.js");
+    const report = await collectRuntimeStatus();
+    return { live: report.liveness === "live", launcher: report.runtime?.launcher ?? null,
+        url: report.runtime?.url ?? null, version: report.runtime?.version ?? null, managed: report.serviceOwnership === "managed" };
+}
+/**
+ * A service restart stops whatever server answers first, so it is chosen only when no live
+ * server exists or the live one is that service. A live desktop, terminal or background
+ * server keeps running and gets its own plan.
+ */
+export function planRestart(input) {
+    if (input.live && input.launcher === "desktop")
+        return { kind: "desktop" };
+    if (input.serviceOwned && (!input.live || input.managed || input.launcher === "service"))
+        return { kind: "service" };
+    if (!input.live || input.managed)
+        return { kind: "none" };
+    if (input.launcher === "background")
+        return { kind: "background" };
+    if (input.launcher === "foreground" && input.url)
+        return { kind: "foreground", url: input.url };
+    return { kind: "none" };
+}
+export function runNewCli(pkgDir, args, exec) {
+    return exec(process.execPath, [join(pkgDir, "bin", "ima2.js"), ...args], { inherit: true, shell: false }).status ?? 1;
+}
+export function serviceArtifactPath(platform = process.platform) {
+    return platform === "darwin" ? launchdPlistPath() : platform === "linux" ? systemdUnitPath() : null;
+}
+function serviceServerPath(text, platform) {
+    if (platform === "darwin") {
+        const array = /<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(text)?.[1];
+        const server = array ? Array.from(array.matchAll(/<string>([^<]*)<\/string>/g))[1]?.[1] : null;
+        return server?.replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&quot;", '"').replaceAll("&apos;", "'").replaceAll("&amp;", "&") ?? null;
+    }
+    const command = /^ExecStart=(.+)$/m.exec(text)?.[1];
+    const args = command?.match(/"[^"]*"|'[^']*'|\S+/g);
+    return args?.length === 2 ? args[1].replace(/^(["'])(.*)\1$/, "$2") : null;
+}
+/**
+ * The config dir the artifact declares, or null when a declaration exists that the simple
+ * parser cannot read (quoted systemd assignments, escapes): ownership must then fail closed
+ * instead of falling back to the default ~/.ima2.
+ */
+function declaredConfigDir(text) {
+    const mentions = text.split("\n").filter((line) => line.includes("IMA2_CONFIG_DIR")).length;
+    const plain = /<key>IMA2_CONFIG_DIR<\/key>/.test(text) || /^Environment=IMA2_CONFIG_DIR=[^"'\\\s]*$/m.test(text);
+    if (mentions > 0 && (!plain || mentions > 1))
+        return null;
+    return parseServiceConfigDir(text);
+}
+function canonicalConfig(path, fs) {
+    try {
+        return fs.realpath(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
+export function serviceOwned(pkgDir, configDir, opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    const fs = opts.fs ?? defaultFs;
+    const artifact = serviceArtifactPath(platform);
+    if (!artifact || !fs.exists(artifact))
+        return false;
+    try {
+        const text = fs.readFile(artifact);
+        const server = serviceServerPath(text, platform);
+        if (server && isAbsolute(server) && basename(server) === "server.js") {
+            const inside = relative(fs.realpath(pkgDir), fs.realpath(server));
+            const declared = declaredConfigDir(text);
+            if (inside && inside !== ".." && !inside.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) && !isAbsolute(inside)
+                && declared !== null && canonicalConfig(declared, fs) === canonicalConfig(configDir, fs))
+                return true;
+        }
+    }
+    catch { /* An unreadable/unparseable artifact cannot prove ownership. */ }
+    (opts.log ?? console.error)("A login service exists but belongs to another install; not restarting it.");
+    return false;
+}

package/bin/lib/updateNotice.js

@@ -0,0 +1,30 @@
+import { claimUpdatedNotice, readVersionCache } from "../../lib/updateCache.js";
+import { defaultTag, isNewer, releaseUrl } from "../../lib/updateVersion.js";
+const NOTICE_COMMANDS = new Set(["serve", "start", "status", "open", "doctor", "ls", "ps"]);
+const SILENT_FLAGS = new Set(["--json", "--quiet", "-q", "-h", "--help", "-v", "--version"]);
+function eligible(input) {
+    return input.isTTY && input.env.IMA2_DISABLE_UPDATE_CHECK !== "1" && input.env.IMA2_DESKTOP !== "1"
+        && NOTICE_COMMANDS.has(input.command ?? "") && !input.args.some((arg) => SILENT_FLAGS.has(arg));
+}
+export function updateNoticeLine(input) {
+    const { cache, current } = input;
+    if (!eligible(input) || cache.tag !== defaultTag(current) || !isNewer(cache.latest_version, current)
+        || cache.dismissed_version === cache.latest_version)
+        return null;
+    const command = cache.tag === "preview" ? "ima2 update --tag preview" : "ima2 update";
+    return `Update available: v${cache.latest_version} (current v${current}). Run: ${command}`;
+}
+export function printUpdateNotice(command, args, current, deps = { isTTY: Boolean(process.stdout.isTTY), env: process.env,
+    readCache: readVersionCache, claim: claimUpdatedNotice, write: (line) => process.stderr.write(`${line}\n`) }) {
+    if (!eligible({ command, args, isTTY: deps.isTTY, env: deps.env }))
+        return;
+    try {
+        const line = updateNoticeLine({ command, args, current, cache: deps.readCache(), isTTY: deps.isTTY, env: deps.env });
+        if (line)
+            deps.write(line);
+        const updated = deps.claim(current);
+        if (updated)
+            deps.write(`ima2 updated to v${updated} — what's new: ${releaseUrl(updated)}`);
+    }
+    catch { /* Notices are best-effort and must not interrupt the requested command. */ }
+}

package/config.js

@@ -112,6 +112,16 @@ export function defaultLogLevelForEnv(runtimeEnv = env) {
 }
 export const config = {
     security: LAN_SECURITY_POLICY,
+    update: {
+        registry: (env.IMA2_NPM_REGISTRY || "https://registry.npmjs.org").replace(/\/+$/, ""),
+        freshMs: 20 * 60 * 60_000,
+        staleMs: 40 * 60 * 60_000,
+        tickMs: 60 * 60_000,
+        backoffMinMs: 60_000,
+        backoffMaxMs: 60 * 60_000,
+        timeoutMs: 8_000,
+        disabled: env.IMA2_DISABLE_UPDATE_CHECK === "1",
+    },
     diagnostics: {
         keyTimeoutMs: Math.min(30000, pickPositiveInt(env.IMA2_DIAGNOSTIC_KEY_TIMEOUT_MS, fileCfg.diagnostics?.keyTimeoutMs, 5000)),
         runtimeTimeoutMs: Math.min(30000, pickPositiveInt(env.IMA2_DIAGNOSTIC_RUNTIME_TIMEOUT_MS, fileCfg.diagnostics?.runtimeTimeoutMs, 1500)),

package/docs/API.md

@@ -912,6 +912,17 @@ The studio's one-time star prompt stars the repository with the user's own `gh`
 | `POST` | `/api/github/star` | Stars via `gh api -X PUT /user/starred/lidge-ai/ima2-gen` and marks prompted; `409 GH_UNAUTHENTICATED`, `502 GH_FAILED` |
 | `POST` | `/api/github/star/dismiss` | Marks prompted without starring |
 
+## Updates
+
+npm installs check the registry for a newer ima2 while the server runs (at most once every 20 hours, hourly retries with backoff; preview installs follow the `preview` tag). State lives under the config dir: `version.json` (check results), `update-dismissed.json` and `update-seen/<version>` markers. Servers launched by the desktop app report `surface: "desktop"`, never check npm and never claim notices; the app updates itself. `IMA2_DISABLE_UPDATE_CHECK=1` stops the automatic check only.
+
+| Method | Path | Result |
+|---|---|---|
+| `GET` | `/api/update/badge` | `{ surface, enabled, currentVersion, latestVersion, available, dismissed, stale, checkedAt, tag, command, releaseUrl, noticePending }` from the cache, no network. The web UI receives the same badge as an `update` frame when it opens `GET /api/events` (npm servers only, no `id`), then re-reads this route every 10 minutes and claims the notice only when `noticePending` |
+| `POST` | `/api/update/check` | Forced registry check, then the badge; `503 UPDATE_CHECK_FAILED` with `{ message, badge }` on failure |
+| `POST` | `/api/update/dismiss` | Body `{ version }`; hides that version's badge; `400 INVALID_VERSION` |
+| `POST` | `/api/update/notice` | `{ updatedTo: string \| null }` — the one-time "updated to vX" claim (null on first run, downgrade or repeat) |
+
 
 ## Common Error Codes
 
@@ -1069,6 +1080,8 @@ Most server routes under `/api/*` have a CLI wrapper. The exception is **Agent M
 | `POST /api/auth/switch` / `GET /api/auth/switch/:sessionId` | Web UI (Settings > QuotaCard > Switch Account) and `ima2 grok login` |
 | `POST /api/oauth/restart` | `ima2 login`, `ima2 gpt login`, `ima2 gpt logout` |
 | `GET /api/health` | `ima2 ping` |
+| `GET /api/update/badge` / `POST /api/update/check` | `ima2 update --check` (the CLI checks the registry itself and shares the cache) |
+| `POST /api/update/dismiss` / `POST /api/update/notice` | Web UI only (update popover and the one-time toast) |
 | `GET /api/capabilities` | `ima2 capabilities` |
 | `GET /api/config/grok-planner` | — (Grok planner model query) |
 | `PATCH /api/config/grok-planner` | — (Grok planner model update) |

package/docs/migration/runtime-test-inventory.md

@@ -4,7 +4,7 @@ Generated by `npm run test:inventory` (script: `scripts/classify-tests.mjs`).
 
 _Tests considered "runtime-importing" if they import from `../lib/`, `../routes/`, `../bin/`, `../server`, or `../config`._
 
-Total: 536 (runtime: 243, contract: 293)
+Total: 541 (runtime: 246, contract: 295)
 
 ## Runtime-importing tests
 - `tests/advertise-payload-contract.test.ts`
@@ -230,6 +230,9 @@ Total: 536 (runtime: 243, contract: 293)
 - `tests/transparent-alpha-verification.test.ts`
 - `tests/transparent-background-contract.test.ts`
 - `tests/transparent-background-route.test.ts`
+- `tests/update-cli.test.ts`
+- `tests/update-core.test.ts`
+- `tests/update-routes.test.ts`
 - `tests/vectorize-image-contract.test.ts`
 - `tests/video-chroma-key.test.ts`
 - `tests/video-concat.test.ts`
@@ -366,6 +369,7 @@ Total: 536 (runtime: 243, contract: 293)
 - `tests/desktop-takeover.test.ts`
 - `tests/desktop-titlebar-contract.test.ts`
 - `tests/desktop-tray.test.ts`
+- `tests/desktop-update-state.test.ts`
 - `tests/desktop-updater.test.ts`
 - `tests/desktop-window-open.test.ts`
 - `tests/direct-mode-visual-contract.test.ts`
@@ -532,6 +536,7 @@ Total: 536 (runtime: 243, contract: 293)
 - `tests/ui-radius-scale-contract.test.ts`
 - `tests/ui-touch-target-contract.test.ts`
 - `tests/ui-typography-rules-contract.test.ts`
+- `tests/update-ui-contract.test.ts`
 - `tests/vectorize-cli-contract.test.ts`
 - `tests/vectorize-panel-contract.test.ts`
 - `tests/video-continuity-ui-contract.test.ts`

package/lib/updateCache.js

@@ -0,0 +1,128 @@
+import { randomBytes } from "node:crypto";
+import { closeSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { config } from "../config.js";
+import { errInfo } from "./errInfo.js";
+import { compareVersions, isNewer, isUpdateTag, parseVersion, releaseUrl } from "./updateVersion.js";
+export function versionCachePath(configDir = config.storage.configDir) {
+    return join(configDir, "version.json");
+}
+function readObject(path) {
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+    }
+    catch {
+        return {}; // Missing or corrupt update state has the same empty read view.
+    }
+}
+function highestSeen(path) {
+    try {
+        return readdirSync(join(dirname(path), "update-seen"), { withFileTypes: true })
+            .filter((entry) => entry.isFile() && parseVersion(entry.name) !== null)
+            .reduce((highest, entry) => highest === null || compareVersions(entry.name, highest) > 0 ? entry.name : highest, null);
+    }
+    catch {
+        return null; // The marker directory does not exist on the first run.
+    }
+}
+export function readVersionCache(path = versionCachePath()) {
+    const version = readObject(path);
+    const dismissed = readObject(join(dirname(path), "update-dismissed.json"));
+    return {
+        latest_version: typeof version.latest_version === "string" ? version.latest_version : null,
+        last_checked_at: typeof version.last_checked_at === "number" && Number.isFinite(version.last_checked_at) ? version.last_checked_at : null,
+        tag: isUpdateTag(version.tag) ? version.tag : null,
+        dismissed_version: typeof dismissed.dismissed_version === "string" ? dismissed.dismissed_version : null,
+        last_seen_version: highestSeen(path),
+    };
+}
+// Windows refuses to replace a file another process has open (EPERM/EBUSY/EACCES) for a moment;
+// concurrent writers and readers of version.json hit that window, so the rename retries briefly.
+const RENAME_RETRY_CODES = new Set(["EPERM", "EBUSY", "EACCES"]);
+const RENAME_ATTEMPTS = 20;
+const RENAME_RETRY_MS = 25;
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function renameWithRetry(from, to) {
+    for (let attempt = 1;; attempt++) {
+        try {
+            renameSync(from, to);
+            return;
+        }
+        catch (error) {
+            if (attempt >= RENAME_ATTEMPTS || !RENAME_RETRY_CODES.has(errInfo(error).code ?? ""))
+                throw error;
+            sleepSync(RENAME_RETRY_MS);
+        }
+    }
+}
+function writeOwner(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
+    try {
+        writeFileSync(tmp, JSON.stringify(value, null, 2) + "\n", { mode: 0o600 });
+        renameWithRetry(tmp, path);
+    }
+    catch (error) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch { /* best-effort removal after a failed atomic write */ }
+        throw error;
+    }
+}
+function createSeen(version, path) {
+    if (!parseVersion(version))
+        throw new Error("Invalid update version");
+    const dir = join(dirname(path), "update-seen");
+    mkdirSync(dir, { recursive: true });
+    try {
+        closeSync(openSync(join(dir, version), "wx", 0o600));
+        return true;
+    }
+    catch (error) {
+        if (errInfo(error).code === "EEXIST")
+            return false;
+        throw error;
+    }
+}
+/** Record the version installed by the CLI without claiming a UI notice. */
+export function markSeen(version, path = versionCachePath()) {
+    createSeen(version, path);
+}
+export function updateVersionCache(patch, path = versionCachePath()) {
+    const fresh = readVersionCache(path);
+    const next = { ...fresh, ...patch };
+    if (["latest_version", "last_checked_at", "tag"].some((key) => Object.hasOwn(patch, key))) {
+        writeOwner(path, { latest_version: next.latest_version, last_checked_at: next.last_checked_at, tag: next.tag });
+    }
+    if (Object.hasOwn(patch, "dismissed_version")) {
+        writeOwner(join(dirname(path), "update-dismissed.json"), { dismissed_version: next.dismissed_version });
+    }
+    if (patch.last_seen_version !== undefined && patch.last_seen_version !== null)
+        markSeen(patch.last_seen_version, path);
+    return readVersionCache(path);
+}
+export function claimUpdatedNotice(current, path = versionCachePath()) {
+    const previous = highestSeen(path);
+    if (!createSeen(current, path))
+        return null;
+    return previous !== null && compareVersions(current, previous) > 0 ? current : null;
+}
+export function buildBadge(input) {
+    const { cache, current, tag, enabled, surface, now } = input;
+    const latest = cache.latest_version;
+    const dismissed = latest !== null && cache.dismissed_version === latest;
+    return {
+        surface, enabled: enabled && surface === "npm", currentVersion: current, latestVersion: latest,
+        available: surface === "npm" && cache.tag === tag && isNewer(latest, current) && !dismissed,
+        dismissed,
+        stale: cache.last_checked_at === null || cache.tag !== tag || now - cache.last_checked_at >= (input.staleMs ?? config.update.staleMs),
+        checkedAt: cache.last_checked_at, tag,
+        command: tag === "preview" ? "ima2 update --tag preview" : "ima2 update",
+        releaseUrl: latest !== null ? releaseUrl(latest) : null,
+        noticePending: surface === "npm" && cache.last_seen_version !== null && compareVersions(current, cache.last_seen_version) > 0,
+    };
+}