@shardflux/cli 0.15.1 → 0.15.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.15.2
+
+- Updates show up the moment they are published: the latest version comes from npm's `latest` tag (what
+  `npm i -g shardflux` installs), checked at most every 12 hours with its ETag. The API still says which versions it
+  supports, and can hold back a release. Offline, nothing is printed. `shard update --check` and the menu bar's update
+  check use the same versions.
+- The menu bar keeps up with npm by itself: after `npm i -g shardflux`, every `shard` command compares the installed app
+  with the one the package carries (two Info.plist reads, no network) and, when that one is newer, brings it in in the
+  background: a stopped app is replaced on disk, a running one is left to update itself (menu bar 0.3.2+) or, for
+  earlier apps, restarted on the new version when none of its windows is open. `shard update` swaps in an app the
+  package already carries without another install. App versions compare as semver (0.3.10 after 0.3.9).
+- Installs menu bar 0.3.2 (`@shardflux/menubar-darwin ^0.3.2`).
+
 ## 0.15.1
 
 - `shard setup`, `shard signup` and `shard api-keys create` make keys with every workspace tool, `computer` included, so the saved key can watch and screenshot a workspace's desktop (`shard ws computer stream`, `screenshot`), as the first-run demo does. `shard setup` replaces a saved key from an earlier setup (every tool but `computer`) with one that has every tool; the old key keeps working until revoked. `--tool` lists `computer`.

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.15.1";
+export declare const CLI_VERSION = "0.15.2";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;

package/dist/args.js

@@ -12,7 +12,7 @@
 import { parseArgs } from 'node:util';
 import { ACCOUNT_COMMANDS } from "./account-args.js";
 import { UsageError } from "./errors.js";
-export const CLI_VERSION = '0.15.1';
+export const CLI_VERSION = '0.15.2';
 export const GLOBAL_OPTIONS = {
     'api-url': { type: 'string', value: '<url>', description: 'API base URL (default $SHARDFLUX_API_URL, else https://api.shardflux.dev).' },
     json: { type: 'boolean', description: 'Print machine-readable JSON on stdout (errors as JSON on stderr).' },
@@ -1407,6 +1407,9 @@ export function parseCommandLine(argv, options = {}) {
     // `acp --login` is the ACP terminal sign-in an editor runs (ACP appends the method's args to `shard acp`).
     if (argv.length === 2 && argv[0] === 'acp' && argv[1] === '--login')
         return { kind: 'run', command: { path: ['acp'], summary: '', positionals: [], options: {} }, values: { login: true }, positionals: [], global: { apiUrl: undefined, json: false, agentLabel: undefined, wake: undefined, wakeTimeout: undefined } };
+    // `menubar refresh` (0.15.2+, not in help): the background step each command may start (menubar.ts).
+    if (argv.length === 2 && argv[0] === 'menubar' && argv[1] === 'refresh')
+        return { kind: 'run', command: { path: ['menubar', 'refresh'], summary: '', positionals: [], options: {} }, values: {}, positionals: [], global: { apiUrl: undefined, json: false, agentLabel: undefined, wake: undefined, wakeTimeout: undefined } };
     if (argv.length === 1 && (argv[0] === 'acp' || argv[0] === 'device-helper'))
         return { kind: 'run', command: { path: [argv[0]], summary: '', positionals: [], options: {} }, values: {}, positionals: [], global: { apiUrl: undefined, json: false, agentLabel: undefined, wake: undefined, wakeTimeout: undefined } };
     const terminator = argv.indexOf('--');

package/dist/commands.d.ts

@@ -66,7 +66,7 @@ export interface Ctx {
     distribution: Distribution;
     /** The Node.js binary and script of this process; null when run in-process (tests, embedders). */
     runtime: import('./update.js').Runtime | null;
-    /** GET /v1/client-versions (unauthenticated): the latest version of every client. */
+    /** Every client's versions: GET /v1/client-versions (minimum_supported, hold) with `latest` from npm (0.15.2+). */
     clientVersions(): Promise<unknown>;
     /** This machine's name (default API key name of `shard setup`). */
     hostname(): string;

package/dist/main.js

@@ -10,7 +10,7 @@
  *   (step-up, password change, TOTP change) is saved at once; a saved session the API rejects (401) is removed.
  * Every credential the command loaded is redacted from what it prints on failure.
  */
-import { hostname } from 'node:os';
+import { homedir, hostname } from 'node:os';
 import { statSync } from 'node:fs';
 import { SDK_VERSION, Shardflux, ShardfluxAccount, isSessionToken } from '@shardflux/sdk';
 import { CLI_VERSION, CENTER_COMMAND, PROJECT_COMMAND, commandHelp, parseCommandLine, resolveApiUrl, resolveWake, resolveWakeTimeout } from "./args.js";
@@ -23,6 +23,8 @@ import { runDeviceHelper } from "./device-helper.js";
 import { housekeeping, startupHousekeeping } from "./agent-git-commands.js";
 import { CredentialStore, configDir } from "./credentials.js";
 import { recordInstall } from "./update.js";
+import { refreshMenubarInBackground, runMenubarRefresh } from "./menubar.js";
+import { NPM_CLIENTS, npmLatestAll, npmRegistry, withRegistryLatest } from "./registry.js";
 import { AuthConfigError, EXIT, ExecutionPendingError, InterruptedError, UsageError, describeError, exitCodeFor, ownHint, redact } from "./errors.js";
 import { errorText, feedbackCommand, json, time } from "./format.js";
 import { HANDLERS } from "./handlers.js";
@@ -540,12 +542,20 @@ export async function run(argv, io, opts = {}) {
             distribution,
             runtime: opts.runtime ?? null,
             async clientVersions() {
-                const res = await base(new URL('/v1/client-versions', `${apiUrl.replace(/\/+$/, '')}/`), {
-                    headers: { accept: 'application/json', 'user-agent': userAgent }, signal: AbortSignal.any([signal, AbortSignal.timeout(10_000)]),
-                });
-                if (!res.ok)
-                    throw new UsageError(`Could not read the latest versions from ${apiUrl} (HTTP ${res.status}).`);
-                return res.json();
+                // The latest versions come from npm (0.15.2+); the API adds minimum_supported and hold. Either one is enough.
+                const catalog = (async () => {
+                    const res = await base(new URL('/v1/client-versions', `${apiUrl.replace(/\/+$/, '')}/`), {
+                        headers: { accept: 'application/json', 'user-agent': userAgent }, signal: AbortSignal.any([signal, AbortSignal.timeout(10_000)]),
+                    });
+                    if (!res.ok)
+                        throw new UsageError(`Could not read the latest versions from ${apiUrl} (HTTP ${res.status}).`);
+                    const body = await res.json();
+                    return body;
+                })();
+                const [api, latest] = await Promise.all([catalog.then((body) => ({ body }), (error) => ({ error })), npmLatestAll(NPM_CLIENTS, { fetch: base, registry: npmRegistry(io.env), userAgent, signal })]);
+                if ('error' in api && Object.keys(latest).length === 0)
+                    throw api.error;
+                return withRegistryLatest('body' in api ? api.body : null, latest);
             },
             hostname: () => {
                 try {
@@ -624,7 +634,7 @@ export async function run(argv, io, opts = {}) {
                     secrets.push(value);
             },
             async versionStatus(force) {
-                const check = new UpdateCheck({ dir: store.dir, apiUrl, distribution, fetch: base, userAgent });
+                const check = new UpdateCheck({ dir: store.dir, apiUrl, distribution, fetch: base, userAgent, registry: npmRegistry(io.env) });
                 if (!force && updateCheckDisabled(io.env)) {
                     const cached = check.peek();
                     return cached ? updateView(cached.status, cached.checkedAt) : null;
@@ -634,10 +644,18 @@ export async function run(argv, io, opts = {}) {
                 return r ? updateView(r.status, r.checkedAt) : null;
             },
         };
+        // After `npm i -g shardflux` the package may carry a newer menu bar app: brought in by a detached process (no
+        // network; an Info.plist compare decides whether to start it).
+        // `shard update` brings the app in itself; `shard update --check` (the menu bar of an app before 0.3.2 runs it every
+        // 6 hours) is how such an app learns of a newer one with no action from the person.
+        const updating = command === 'update' && parsed.values.check !== true;
+        if (opts.runtime && !updating && !['menubar', 'device-helper'].includes(parsed.command.path[0])) {
+            refreshMenubarInBackground({ dir: store.dir, home: io.env.HOME || homedir(), runtime: opts.runtime, env: { ...process.env, ...io.env } });
+        }
         // The update check runs next to the command (not for `version`, which reports it itself).
-        if (!updateCheckDisabled(io.env) && !['version', 'update', 'ssh-proxy', 'acp', 'device-helper'].includes(parsed.command.path[0])) {
+        if (!updateCheckDisabled(io.env) && !['version', 'update', 'ssh-proxy', 'acp', 'device-helper'].includes(parsed.command.path[0]) && command !== 'menubar refresh') {
             try {
-                updates = new UpdateCheck({ dir: store.dir, apiUrl, distribution, fetch: base, userAgent });
+                updates = new UpdateCheck({ dir: store.dir, apiUrl, distribution, fetch: base, userAgent, registry: npmRegistry(io.env) });
                 updates.start();
             }
             catch {
@@ -648,10 +666,10 @@ export async function run(argv, io, opts = {}) {
     catch (err) {
         return report(err);
     }
-    const handler = parsed.command.path[0] === 'acp' ? (ctx) => parsed.values.login === true ? runAcpLogin(ctx) : runAcp(ctx) : parsed.command.path[0] === 'device-helper' ? runDeviceHelper : parsed.command === PROJECT_COMMAND ? launchConversationProject : parsed.command === CENTER_COMMAND ? commandCenter : HANDLERS[parsed.command.path.join(' ')];
+    const handler = parsed.command.path[0] === 'acp' ? (ctx) => parsed.values.login === true ? runAcpLogin(ctx) : runAcp(ctx) : parsed.command.path[0] === 'device-helper' ? runDeviceHelper : command === 'menubar refresh' ? runMenubarRefresh : parsed.command === PROJECT_COMMAND ? launchConversationProject : parsed.command === CENTER_COMMAND ? commandCenter : HANDLERS[parsed.command.path.join(' ')];
     if (!handler)
         return report(new UsageError(`unknown command "${parsed.command.path.join(' ')}"`));
-    if (!['acp', 'device-helper'].includes(parsed.command.path[0]))
+    if (!['acp', 'device-helper'].includes(parsed.command.path[0]) && command !== 'menubar refresh')
         await housekeeping(ctx);
     const running = handler(ctx, parsed.values, parsed.positionals).then((code) => ({ code }), (err) => ({ err }));
     // On Ctrl-C give the command a moment to clean up (exec sends a cancel), then stop regardless.

package/dist/menubar.d.ts

@@ -17,6 +17,24 @@ export interface MenubarStatus {
 }
 type NativeStatus = Omit<MenubarStatus, 'installed' | 'version'>;
 export declare function compareBundleVersions(left: string, right: string): number;
+/**
+ * Marketing versions (CFBundleShortVersionString) compare as semver: 0.3.10 > 0.3.9, 0.4.0-rc.1 < 0.4.0. A version that
+ * is not semver compares as a numeric bundle version.
+ */
+export declare function compareAppVersions(left: string, right: string): number;
+/**
+ * The first app that swaps itself in when the npm package next to the CLI carries a newer one (it knows when no window
+ * is open and nothing is in progress). The CLI leaves a running app of this version or later to do that itself.
+ */
+export declare const SELF_UPDATING_APP = "0.3.2";
+/** CFBundleShortVersionString of a Shardflux app from its XML Info.plist, read without any tool (null: not readable). */
+export declare function plistVersion(app: string): string | null;
+/**
+ * Whether any of these processes shows a window: the menu, the launcher, Settings, onboarding, an approval. The status
+ * item itself (a strip at the top of the screen on the status layer, owned by the app before macOS 26) does not count.
+ * Null when the probe could not answer: then nothing may be replaced.
+ */
+export declare function windowsOpen(text: string): boolean | null;
 export declare function parseNativeStatus(text: string): NativeStatus;
 /**
  * The app's executables keep their execute permission (0.13.6+). @shardflux/menubar-darwin 0.1.1 and 0.1.2 reached npm
@@ -37,13 +55,52 @@ export declare class MenubarManager {
     get platform(): NodeJS.Platform;
     /** The version of the app this CLI's npm package carries (what `start` installs). */
     packagedVersion(): Promise<string>;
+    /** Whether the app shows any window (see windowsOpen); null when that could not be read. */
+    windowsOpen(pids: number[]): Promise<boolean | null>;
     status(): Promise<MenubarStatus>;
     stop(): Promise<MenubarStatus>;
     login(value: 'on' | 'off'): Promise<MenubarStatus>;
     start(configDir: string, apiUrl: string): Promise<MenubarStatus>;
+    /**
+     * Brings an installed app up to the one this CLI's npm package carries, without disturbing the person: nothing when
+     * the versions are equal (each swap of an ad-hoc signed app costs its privacy grants), the copy on disk alone when it
+     * is not running, and a running app only when it shows no window and no `shard update` runs. A running app that
+     * swaps itself in (SELF_UPDATING_APP or later) is left to do so: it also knows when it is in the middle of something.
+     */
+    refresh(configDir: string, apiUrl: string): Promise<{
+        result: 'current' | 'not_installed' | 'installed' | 'restarted' | 'deferred' | 'busy';
+        from: string | null;
+        to: string | null;
+    }>;
 }
 /** On macOS, `shard` brings the menu bar up by itself (with launch at login) unless the user ran `shard menubar stop`.
  *  It never fails the command center: a missing optional package or a refused start just leaves it off. */
 export declare function ensureMenubar(dir: string, apiUrl: string, manager?: MenubarManager, platform?: NodeJS.Platform): Promise<string | undefined>;
+/** How often a command may start a background refresh while the app is busy (a window open). */
+export declare const REFRESH_RETRY_MS: number;
+/** Where this CLI's npm package keeps the app it carries, or null when the optional package is missing. */
+export declare function packagedAppPath(): string | null;
+export interface BackgroundRefreshOptions {
+    dir: string;
+    home: string;
+    /** This `shard` process: the refresh runs the same Node.js and script. */
+    runtime: {
+        node: string;
+        script: string;
+    };
+    env: Record<string, string | undefined>;
+    platform?: NodeJS.Platform;
+    packageApp?: () => string | null;
+    now?: () => number;
+    spawn?: (node: string, args: string[], env: Record<string, string | undefined>) => void;
+}
+/**
+ * Every `shard` command (0.15.2+): when the npm package carries a newer app than the installed one (two Info.plist
+ * reads, no network, no tool), `shard menubar refresh` runs detached, so the command never waits for it. It is started
+ * at most every 5 minutes while the app is busy, and not at all after `shard menubar stop`. Returns whether it started.
+ */
+export declare function refreshMenubarInBackground(o: BackgroundRefreshOptions): boolean;
+/** `shard menubar refresh` (not listed in help, so not in HANDLERS): what refreshMenubarInBackground starts. */
+export declare const runMenubarRefresh: Handler;
 export declare const MENUBAR_HANDLERS: Record<string, Handler>;
 export {};

package/dist/menubar.js

@@ -1,9 +1,10 @@
-import { execFile } from 'node:child_process';
-import { chmodSync, cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, renameSync, rmSync } from 'node:fs';
+import { execFile, spawn } from 'node:child_process';
+import { chmodSync, closeSync, cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readdirSync, readFileSync, renameSync, rmSync, writeSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { promisify } from 'node:util';
+import { compareVersions } from '@shardflux/sdk';
 import { AgentStateStore } from "./agent-state.js";
 import { UsageError } from "./errors.js";
 import { json } from "./format.js";
@@ -27,6 +28,61 @@ export function compareBundleVersions(left, right) {
     }
     return 0;
 }
+/**
+ * Marketing versions (CFBundleShortVersionString) compare as semver: 0.3.10 > 0.3.9, 0.4.0-rc.1 < 0.4.0. A version that
+ * is not semver compares as a numeric bundle version.
+ */
+export function compareAppVersions(left, right) {
+    return compareVersions(left, right) ?? compareBundleVersions(left, right);
+}
+/**
+ * The first app that swaps itself in when the npm package next to the CLI carries a newer one (it knows when no window
+ * is open and nothing is in progress). The CLI leaves a running app of this version or later to do that itself.
+ */
+export const SELF_UPDATING_APP = '0.3.2';
+/** CFBundleShortVersionString of a Shardflux app from its XML Info.plist, read without any tool (null: not readable). */
+export function plistVersion(app) {
+    try {
+        const text = readFileSync(join(app, 'Contents', 'Info.plist'), 'utf8');
+        const value = (key) => new RegExp(`<key>${key}</key>\\s*<string>([^<]+)</string>`).exec(text)?.[1]?.trim() ?? null;
+        if (value('CFBundleIdentifier') !== BUNDLE_ID)
+            return null;
+        const version = value('CFBundleShortVersionString') ?? value('CFBundleVersion');
+        return version && compareVersions(version, version) !== null ? version : null;
+    }
+    catch {
+        return null;
+    }
+}
+const WINDOW_PROBE = `ObjC.import('CoreGraphics');
+function run(argv) {
+  const pids = argv.map(Number);
+  const list = ObjC.deepUnwrap(ObjC.castRefToObject($.CGWindowListCopyWindowInfo($.kCGWindowListOptionOnScreenOnly, $.kCGNullWindowID))) || [];
+  return JSON.stringify(list.filter(w => pids.includes(w.kCGWindowOwnerPID)).map(w => ({ pid: w.kCGWindowOwnerPID, layer: w.kCGWindowLayer,
+    x: w.kCGWindowBounds.X, y: w.kCGWindowBounds.Y, width: w.kCGWindowBounds.Width, height: w.kCGWindowBounds.Height, alpha: w.kCGWindowAlpha })));
+}`;
+/**
+ * Whether any of these processes shows a window: the menu, the launcher, Settings, onboarding, an approval. The status
+ * item itself (a strip at the top of the screen on the status layer, owned by the app before macOS 26) does not count.
+ * Null when the probe could not answer: then nothing may be replaced.
+ */
+export function windowsOpen(text) {
+    let rows;
+    try {
+        rows = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(rows))
+        return null;
+    const windows = rows;
+    if (!windows.every(w => w && typeof w === 'object' && ['layer', 'y', 'width', 'height'].every(k => typeof w[k] === 'number')))
+        return null;
+    // A status item is a strip on the status layer at the top of the screen (39 pt high on a notched display).
+    const statusItem = (w) => w.layer === 25 && w.y <= 0 && w.height <= 50;
+    return windows.some(w => w.layer >= 0 && !statusItem(w) && (w.alpha ?? 1) > 0 && w.width > 1 && w.height > 1);
+}
 export function parseNativeStatus(text) {
     const value = JSON.parse(text);
     if (!value || typeof value !== 'object')
@@ -68,12 +124,10 @@ export class MenubarManager {
         this.#platform = options.platform ?? process.platform;
         this.#run = options.run ?? ((tool, args) => nativeTools.run(tool, args, options.signal));
         this.#packageApp = options.packageApp ?? (() => {
-            try {
-                return join(dirname(createRequire(import.meta.url).resolve('@shardflux/menubar-darwin/package.json')), 'Shardflux.app');
-            }
-            catch {
+            const app = packagedAppPath();
+            if (!app)
                 throw new UsageError('The macOS app package is missing. Reinstall shard with optional dependencies enabled, then run shard menubar start.');
-            }
+            return app;
         });
     }
     get platform() { return this.#platform; }
@@ -86,10 +140,25 @@ export class MenubarManager {
         const id = (await this.#run('/usr/bin/plutil', ['-extract', 'CFBundleIdentifier', 'raw', '-o', '-', file])).trim();
         if (id !== BUNDLE_ID || lstatSync(app).isSymbolicLink())
             throw new UsageError(`Refusing to replace an unrelated app at ${app}.`);
+        // The marketing version (0.15.2+), compared as semver; an app without one has its numeric bundle version.
+        const marketing = await this.#run('/usr/bin/plutil', ['-extract', 'CFBundleShortVersionString', 'raw', '-o', '-', file]).then(v => v.trim(), () => '');
+        if (marketing && compareVersions(marketing, marketing) !== null)
+            return marketing;
         const version = (await this.#run('/usr/bin/plutil', ['-extract', 'CFBundleVersion', 'raw', '-o', '-', file])).trim();
         compareBundleVersions(version, version);
         return version;
     }
+    /** Whether the app shows any window (see windowsOpen); null when that could not be read. */
+    async windowsOpen(pids) {
+        if (!pids.length)
+            return false;
+        try {
+            return windowsOpen(await this.#run('/usr/bin/osascript', ['-l', 'JavaScript', '-e', WINDOW_PROBE, ...pids.map(String)]));
+        }
+        catch {
+            return null;
+        }
+    }
     async #control(action, ...args) {
         makeExecutable(this.app);
         return parseNativeStatus(await this.#run(join(this.app, 'Contents', 'MacOS', 'ShardfluxMenuBar'), ['--control', action, ...args]));
@@ -125,46 +194,49 @@ export class MenubarManager {
         await this.#control('login', value);
         return this.status();
     }
-    async start(configDir, apiUrl) {
-        this.#requireMac();
-        const source = this.#packageApp(), sourceVersion = await this.#version(source);
-        const current = await this.status();
-        if (!current.installed || compareBundleVersions(current.version, sourceVersion) < 0) {
-            // Verify the source before stopping or replacing any existing app.
-            await this.#run('/usr/bin/codesign', ['--verify', '--deep', '--strict', source]);
-            mkdirSync(dirname(this.app), { recursive: true });
-            const stage = mkdtempSync(join(dirname(this.app), '.Shardflux-install-'));
-            const staged = join(stage, 'Shardflux.app'), backup = join(stage, 'previous.app');
-            let committed = false, restored = false;
+    /** Replaces the installed app with `source` (verified first), stopping it while it is swapped. */
+    async #install(source, current) {
+        // Verify the source before stopping or replacing any existing app.
+        await this.#run('/usr/bin/codesign', ['--verify', '--deep', '--strict', source]);
+        mkdirSync(dirname(this.app), { recursive: true });
+        const stage = mkdtempSync(join(dirname(this.app), '.Shardflux-install-'));
+        const staged = join(stage, 'Shardflux.app'), backup = join(stage, 'previous.app');
+        let committed = false, restored = false;
+        try {
+            cpSync(source, staged, { recursive: true, dereference: false });
+            if (current.running)
+                await this.stop();
+            if (current.installed)
+                renameSync(this.app, backup);
+            makeExecutable(staged);
             try {
-                cpSync(source, staged, { recursive: true, dereference: false });
-                if (current.running)
-                    await this.stop();
-                if (current.installed)
-                    renameSync(this.app, backup);
-                makeExecutable(staged);
-                try {
-                    renameSync(staged, this.app);
-                    committed = true;
-                }
-                catch (error) {
-                    if (existsSync(backup)) {
-                        try {
-                            renameSync(backup, this.app);
-                            restored = true;
-                        }
-                        catch {
-                            throw new UsageError(`Could not restore the previous app. It is preserved at ${backup}.`);
-                        }
+                renameSync(staged, this.app);
+                committed = true;
+            }
+            catch (error) {
+                if (existsSync(backup)) {
+                    try {
+                        renameSync(backup, this.app);
+                        restored = true;
+                    }
+                    catch {
+                        throw new UsageError(`Could not restore the previous app. It is preserved at ${backup}.`);
                     }
-                    throw error;
                 }
+                throw error;
             }
-            finally {
-                if (committed || restored || !existsSync(backup))
-                    rmSync(stage, { recursive: true, force: true });
-            }
         }
+        finally {
+            if (committed || restored || !existsSync(backup))
+                rmSync(stage, { recursive: true, force: true });
+        }
+    }
+    async start(configDir, apiUrl) {
+        this.#requireMac();
+        const source = this.#packageApp(), sourceVersion = await this.#version(source);
+        const current = await this.status();
+        if (!current.installed || compareAppVersions(current.version, sourceVersion) < 0)
+            await this.#install(source, current);
         await this.#stripQuarantine();
         if (!(await this.status()).running) {
             mkdirSync(configDir, { recursive: true, mode: 0o700 });
@@ -179,6 +251,45 @@ export class MenubarManager {
         }
         throw new UsageError(`Shardflux did not start. Check ${join(configDir, 'menubar.log')}.`);
     }
+    /**
+     * Brings an installed app up to the one this CLI's npm package carries, without disturbing the person: nothing when
+     * the versions are equal (each swap of an ad-hoc signed app costs its privacy grants), the copy on disk alone when it
+     * is not running, and a running app only when it shows no window and no `shard update` runs. A running app that
+     * swaps itself in (SELF_UPDATING_APP or later) is left to do so: it also knows when it is in the middle of something.
+     */
+    async refresh(configDir, apiUrl) {
+        this.#requireMac();
+        const current = await this.status();
+        if (!current.installed || !current.version)
+            return { result: 'not_installed', from: null, to: null };
+        const to = await this.packagedVersion(), from = current.version;
+        if (compareAppVersions(from, to) >= 0)
+            return { result: 'current', from, to };
+        if (current.running) {
+            if (compareAppVersions(from, SELF_UPDATING_APP) >= 0)
+                return { result: 'deferred', from, to };
+            if (updateRunning(configDir) || (await this.windowsOpen(current.pids)) !== false)
+                return { result: 'busy', from, to };
+            await this.start(configDir, apiUrl);
+            return { result: 'restarted', from, to };
+        }
+        await this.#install(this.#packageApp(), current);
+        await this.#stripQuarantine();
+        return { result: 'installed', from, to };
+    }
+}
+/** A `shard update` holds update.lock while it runs (update.ts); a lock of a process that is gone does not count. */
+function updateRunning(dir) {
+    try {
+        const pid = Number(readFileSync(join(dir, 'update.lock'), 'utf8'));
+        if (!Number.isInteger(pid) || pid <= 0)
+            return false;
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
 }
 /** On macOS, `shard` brings the menu bar up by itself (with launch at login) unless the user ran `shard menubar stop`.
  *  It never fails the command center: a missing optional package or a refused start just leaves it off. */
@@ -190,8 +301,9 @@ export async function ensureMenubar(dir, apiUrl, manager = new MenubarManager(),
         return undefined;
     try {
         const status = await manager.status();
-        // A running app stays unless this CLI carries a newer one (after `npm i -g shardflux`): then it is replaced.
-        if (status.running && !(status.version && compareBundleVersions(status.version, await manager.packagedVersion()) < 0))
+        // A running app is brought up to the one this CLI carries (after `npm i -g shardflux`) by the background refresh
+        // every command starts (refreshMenubarInBackground), at a moment when it shows no window.
+        if (status.running)
             return undefined;
         const started = await manager.start(dir, apiUrl);
         if (!started.running)
@@ -204,7 +316,114 @@ export async function ensureMenubar(dir, apiUrl, manager = new MenubarManager(),
         return undefined;
     }
 }
-export const MENUBAR_HANDLERS = Object.fromEntries(['start', 'stop', 'status'].map(action => {
+const REFRESH_MARK = 'menubar-refresh.json';
+const REFRESH_LOCK = 'menubar-refresh.lock';
+/** How often a command may start a background refresh while the app is busy (a window open). */
+export const REFRESH_RETRY_MS = 5 * 60_000;
+/** Where this CLI's npm package keeps the app it carries, or null when the optional package is missing. */
+export function packagedAppPath() {
+    try {
+        return join(dirname(createRequire(import.meta.url).resolve('@shardflux/menubar-darwin/package.json')), 'Shardflux.app');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Every `shard` command (0.15.2+): when the npm package carries a newer app than the installed one (two Info.plist
+ * reads, no network, no tool), `shard menubar refresh` runs detached, so the command never waits for it. It is started
+ * at most every 5 minutes while the app is busy, and not at all after `shard menubar stop`. Returns whether it started.
+ */
+export function refreshMenubarInBackground(o) {
+    try {
+        if ((o.platform ?? process.platform) !== 'darwin')
+            return false;
+        const installed = plistVersion(join(o.home, 'Applications', 'Shardflux.app'));
+        const source = (o.packageApp ?? packagedAppPath)();
+        const packaged = source ? plistVersion(source) : null;
+        if (!installed || !packaged || compareAppVersions(installed, packaged) >= 0)
+            return false;
+        if (new AgentStateStore(o.dir).read().menubar_stopped === true)
+            return false;
+        const now = (o.now ?? Date.now)(), mark = join(o.dir, REFRESH_MARK);
+        try {
+            const last = JSON.parse(readFileSync(mark, 'utf8'));
+            if (last.to === packaged && typeof last.at === 'number' && now - last.at < REFRESH_RETRY_MS && last.at <= now)
+                return false;
+        }
+        catch { /* never started */ }
+        mkdirSync(o.dir, { recursive: true, mode: 0o700 });
+        const fd = openSync(mark, 'w', 0o600);
+        try {
+            writeSync(fd, `${JSON.stringify({ at: now, from: installed, to: packaged })}\n`);
+        }
+        finally {
+            closeSync(fd);
+        }
+        const env = { ...o.env, SHARDFLUX_CONFIG_DIR: o.dir, SHARDFLUX_NO_UPDATE_CHECK: '1' };
+        (o.spawn ?? spawnDetached)(o.runtime.node, [o.runtime.script, 'menubar', 'refresh'], env);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function spawnDetached(node, args, env) {
+    const child = spawn(node, args, { detached: true, stdio: 'ignore', env });
+    child.on('error', () => undefined);
+    child.unref();
+}
+/** One refresh at a time per config directory; the lock of a process that is gone is taken over. */
+function refreshLock(dir) {
+    const file = join(dir, REFRESH_LOCK);
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const fd = openSync(file, 'wx', 0o600);
+            writeSync(fd, String(process.pid));
+            closeSync(fd);
+            return () => rmSync(file, { force: true });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                return null;
+            let alive = false;
+            try {
+                const pid = Number(readFileSync(file, 'utf8'));
+                if (Number.isInteger(pid) && pid > 0) {
+                    process.kill(pid, 0);
+                    alive = true;
+                }
+            }
+            catch { /* gone */ }
+            if (alive)
+                return null;
+            rmSync(file, { force: true });
+        }
+    }
+    return null;
+}
+/** `shard menubar refresh` (not listed in help, so not in HANDLERS): what refreshMenubarInBackground starts. */
+export const runMenubarRefresh = async (ctx) => {
+    const manager = new MenubarManager({ home: ctx.io.env.HOME || homedir(), signal: ctx.signal });
+    let outcome;
+    if (new AgentStateStore(ctx.store.dir).read().menubar_stopped === true)
+        outcome = { result: 'off', from: null, to: null };
+    else {
+        const unlock = refreshLock(ctx.store.dir);
+        if (!unlock)
+            outcome = { result: 'locked', from: null, to: null };
+        else
+            try {
+                outcome = await manager.refresh(ctx.store.dir, ctx.apiUrl);
+            }
+            finally {
+                unlock();
+            }
+    }
+    ctx.io.stdout.write(ctx.json ? json(outcome) : `Menu bar: ${outcome.result}${outcome.from ? ` · app ${outcome.from}${outcome.to && outcome.to !== outcome.from ? ` → ${outcome.to}` : ''}` : ''}\n`);
+    return 0;
+};
+export const MENUBAR_HANDLERS = Object.fromEntries(['start', 'stop', 'status'].map((action) => {
     const handler = async (ctx, values) => {
         if (values.login !== undefined && !['on', 'off'].includes(String(values.login)))
             throw new UsageError('--login must be on or off.');

package/dist/registry.d.ts

@@ -0,0 +1,48 @@
+export declare const NPM_REGISTRY = "https://registry.npmjs.org";
+/** Each registry request's timeout (ms). */
+export declare const REGISTRY_TIMEOUT_MS = 3000;
+/** The npm packages whose versions `shard update` compares. */
+export declare const NPM_CLIENTS: readonly ["shardflux", "@shardflux/cli", "@shardflux/sdk", "@shardflux/mcp", "@shardflux/menubar-darwin"];
+export interface RegistryAnswer {
+    latest: string | null;
+    /** The registry's validator for the next request (npm's dist-tags endpoint sends none today). */
+    etag: string | null;
+    /** 304: what the caller cached under `etag` is still current. */
+    notModified: boolean;
+}
+export interface RegistryOptions {
+    fetch: typeof fetch;
+    /** Default https://registry.npmjs.org (SHARDFLUX_NPM_REGISTRY overrides it for the CLI). */
+    registry?: string;
+    etag?: string | null;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    userAgent?: string;
+}
+/** The registry to ask: SHARDFLUX_NPM_REGISTRY, else npm's public registry. */
+export declare function npmRegistry(env: Record<string, string | undefined>): string;
+/** `latest` of an npm package from `<registry>/-/package/<name>/dist-tags`, or null when the registry did not answer. */
+export declare function npmLatest(pkg: string, opts: RegistryOptions): Promise<RegistryAnswer | null>;
+/** `latest` of every package in `packages`, asked in parallel; a package the registry did not answer is absent. */
+export declare function npmLatestAll(packages: readonly string[], opts: RegistryOptions): Promise<Record<string, string>>;
+export interface CatalogEntry {
+    package: string;
+    ecosystem: string;
+    latest: string | null;
+    minimum_supported: string | null;
+    upgrade_command: string | null;
+    release_notes_url: string | null;
+    hold?: string | null;
+    [key: string]: unknown;
+}
+/**
+ * A GET /v1/client-versions body whose npm entries carry the registry's `latest` (`registry`: package -> version; an
+ * absent package keeps the catalog's). Works with every catalog shape the API has served: no `hold` field, `latest`
+ * null, a package missing from the list, or no catalog at all (`catalog` null: the API did not answer).
+ *
+ * `hold`: when the registry's latest is that version, it is not recommended; the catalog's own `latest` is, when it is
+ * older, else `minimum_supported` (so "no longer supported" still works and nobody is told to update).
+ */
+export declare function withRegistryLatest(catalog: unknown, registry: Record<string, string | null | undefined>): {
+    clients: CatalogEntry[];
+};

package/dist/registry.js

@@ -0,0 +1,102 @@
+/**
+ * The latest version of each Shardflux client comes from its registry (0.15.2+), so a release is known the moment it
+ * is published: npm's `latest` dist-tag, which is what `npm i -g shardflux` and `shard update` install. (`stable` is an
+ * opt-in tag for installs behind a release-age gate, docs/progress/packaging.md; it never drives the update notice.)
+ *
+ * The API catalog (GET /v1/client-versions) still says which versions it serves (`minimum_supported`) and may name a
+ * version to stop recommending (`hold`, an emergency brake). Its `latest` is only the fallback when the registry does
+ * not answer. Every request here is bounded and never throws: offline means "no answer".
+ */
+import { compareVersions } from '@shardflux/sdk';
+export const NPM_REGISTRY = 'https://registry.npmjs.org';
+/** Each registry request's timeout (ms). */
+export const REGISTRY_TIMEOUT_MS = 3_000;
+/** The npm packages whose versions `shard update` compares. */
+export const NPM_CLIENTS = ['shardflux', '@shardflux/cli', '@shardflux/sdk', '@shardflux/mcp', '@shardflux/menubar-darwin'];
+const str = (v) => (typeof v === 'string' && v.length > 0 ? v : null);
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** The registry to ask: SHARDFLUX_NPM_REGISTRY, else npm's public registry. */
+export function npmRegistry(env) {
+    const own = env.SHARDFLUX_NPM_REGISTRY?.trim();
+    return own ? own.replace(/\/+$/, '') : NPM_REGISTRY;
+}
+/** `latest` of an npm package from `<registry>/-/package/<name>/dist-tags`, or null when the registry did not answer. */
+export async function npmLatest(pkg, opts) {
+    try {
+        const timeout = AbortSignal.timeout(opts.timeoutMs ?? REGISTRY_TIMEOUT_MS);
+        const headers = { accept: 'application/json' };
+        if (opts.userAgent)
+            headers['user-agent'] = opts.userAgent;
+        if (opts.etag)
+            headers['if-none-match'] = opts.etag;
+        const res = await opts.fetch(`${(opts.registry ?? NPM_REGISTRY).replace(/\/+$/, '')}/-/package/${encodeURIComponent(pkg)}/dist-tags`, {
+            method: 'GET',
+            headers,
+            signal: opts.signal ? AbortSignal.any([timeout, opts.signal]) : timeout,
+        });
+        const etag = res.headers.get('etag');
+        if (res.status === 304) {
+            await res.body?.cancel().catch(() => undefined);
+            return { latest: null, etag: etag ?? opts.etag ?? null, notModified: true };
+        }
+        if (!res.ok) {
+            await res.body?.cancel().catch(() => undefined);
+            return null;
+        }
+        const body = JSON.parse(await res.text());
+        const latest = isObj(body) ? str(body.latest) : null;
+        // A tag that is not a version (a broken registry mirror) is no answer.
+        if (latest === null || compareVersions(latest, latest) === null)
+            return null;
+        return { latest, etag, notModified: false };
+    }
+    catch {
+        return null;
+    }
+}
+/** `latest` of every package in `packages`, asked in parallel; a package the registry did not answer is absent. */
+export async function npmLatestAll(packages, opts) {
+    const answers = await Promise.all(packages.map(async (pkg) => [pkg, await npmLatest(pkg, { ...opts, etag: null })]));
+    return Object.fromEntries(answers.flatMap(([pkg, a]) => (a?.latest ? [[pkg, a.latest]] : [])));
+}
+const DEFAULT_UPGRADE = {
+    shardflux: 'npm i -g shardflux',
+    '@shardflux/cli': 'npm i -g shardflux',
+    '@shardflux/menubar-darwin': 'shard update',
+};
+/**
+ * A GET /v1/client-versions body whose npm entries carry the registry's `latest` (`registry`: package -> version; an
+ * absent package keeps the catalog's). Works with every catalog shape the API has served: no `hold` field, `latest`
+ * null, a package missing from the list, or no catalog at all (`catalog` null: the API did not answer).
+ *
+ * `hold`: when the registry's latest is that version, it is not recommended; the catalog's own `latest` is, when it is
+ * older, else `minimum_supported` (so "no longer supported" still works and nobody is told to update).
+ */
+export function withRegistryLatest(catalog, registry) {
+    const listed = isObj(catalog) && Array.isArray(catalog.clients) ? catalog.clients.filter(isObj) : [];
+    const entries = listed.map((c) => ({
+        ...c,
+        package: String(c.package),
+        ecosystem: String(c.ecosystem),
+        latest: str(c.latest),
+        minimum_supported: str(c.minimum_supported),
+        upgrade_command: str(c.upgrade_command),
+        release_notes_url: str(c.release_notes_url),
+        hold: str(c.hold),
+    }));
+    for (const pkg of Object.keys(registry)) {
+        if (!entries.some((e) => e.ecosystem === 'npm' && e.package === pkg)) {
+            entries.push({ package: pkg, ecosystem: 'npm', latest: null, minimum_supported: null, upgrade_command: DEFAULT_UPGRADE[pkg] ?? null, release_notes_url: `https://www.npmjs.com/package/${pkg}?activeTab=versions`, hold: null });
+        }
+    }
+    return {
+        clients: entries.map((e) => {
+            const fromRegistry = e.ecosystem === 'npm' ? str(registry[e.package]) : null;
+            let latest = fromRegistry ?? e.latest;
+            if (latest !== null && e.hold && compareVersions(latest, e.hold) === 0) {
+                latest = e.latest !== null && compareVersions(e.latest, e.hold) === -1 ? e.latest : e.minimum_supported;
+            }
+            return { ...e, latest };
+        }),
+    };
+}

package/dist/update-check.d.ts

@@ -11,10 +11,16 @@ export interface Distribution {
 export declare const CLI_DISTRIBUTION: Distribution;
 interface CacheEntry {
     checked_at: string;
+    /** What the notice compares with: the registry's latest, unless the catalog holds it (registry.ts). */
     latest: string | null;
     minimum_supported: string | null;
     upgrade_command: string | null;
     release_notes_url: string | null;
+    /** The catalog's own `latest` and `hold`, and the registry's answer with its ETag (0.15.2+). */
+    catalog_latest?: string | null;
+    hold?: string | null;
+    registry_latest?: string | null;
+    registry_etag?: string | null;
 }
 /** The `update` object of `shard version --json`. */
 export interface UpdateView {
@@ -37,6 +43,8 @@ export interface UpdateCheckOptions {
     distribution: Distribution;
     fetch: typeof fetch;
     userAgent: string;
+    /** The npm registry (default https://registry.npmjs.org). */
+    registry?: string;
     now?: () => number;
 }
 /**
@@ -51,7 +59,7 @@ export declare class UpdateCheck {
         status: ClientVersionStatus;
         checkedAt: string | null;
     } | null;
-    /** Starts the check: from the cache when it is younger than 24 h (unless `force`), else one request. */
+    /** Starts the check: from the cache when it is younger than 12 h (unless `force`), else the registry and the API. */
     start(force?: boolean): void;
     /** The status (with when it was fetched), or null when not started or still running after `waitMs`. */
     result(waitMs: number): Promise<{

package/dist/update-check.js

@@ -1,11 +1,12 @@
 /**
- * `shard` tells its user when it is outdated or no longer supported (0.5.0+). The API's
- * GET /v1/client-versions names the latest published version of every client and the oldest one it still serves.
+ * `shard` tells its user when it is outdated or no longer supported (0.5.0+). The latest version comes from the
+ * registry (0.15.2+: npm's `latest` dist-tag, see registry.ts); the API's GET /v1/client-versions names the oldest
+ * version it still serves and, optionally, a version to stop recommending (`hold`).
  *
- * - At most one request per 24 hours per API URL and package: the answer is cached in
- *   <config dir>/update-check.json (`checked_at`, `latest`, `minimum_supported`, `upgrade_command`). The attempt is
- *   recorded before the request, so an unreachable API is not asked again for a day either.
- * - Started in parallel with the command (the SDK's checkClientVersion: one request, 3 s timeout, never throws) and
+ * - At most one check per 12 hours per API URL and package: the answer is cached in <config dir>/update-check.json
+ *   (`checked_at`, `latest`, `minimum_supported`, `upgrade_command`, and what each source said, with the registry's
+ *   ETag). The attempt is recorded before the requests, so an unreachable network is not asked again for 12 hours.
+ * - Started in parallel with the command (two requests in parallel, 3 s timeout each, never throws) and
  *   printed on stderr after it. When the command ends first, `shard` waits at most ~300 ms and otherwise skips the
  *   notice (the next run uses what this one cached). Never changes the exit code; never printed after a command that
  *   failed with --json (the error document stays the only stderr content).
@@ -14,13 +15,16 @@
  * - Off with SHARDFLUX_NO_UPDATE_CHECK=1 (also true/yes/on) or NO_UPDATE_NOTIFIER (the SDK's rules);
  *   `shard version --check` still asks.
  */
-import { checkClientVersion, clientVersionStatus, versionCheckDisabledByEnv } from '@shardflux/sdk';
+import { clientVersionStatus, versionCheckDisabledByEnv } from '@shardflux/sdk';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { CLI_VERSION } from "./args.js";
 import { writePrivateFile } from "./credentials.js";
+import { NPM_REGISTRY, npmLatest, withRegistryLatest } from "./registry.js";
 export const UPDATE_CHECK_FILE = 'update-check.json';
-export const CHECK_INTERVAL_MS = 24 * 3600 * 1000;
+export const CHECK_INTERVAL_MS = 12 * 3600 * 1000;
+/** The catalog request's timeout (ms). */
+const CATALOG_TIMEOUT_MS = 3_000;
 /** How long the end of a command waits for a check that is still running. */
 export const NOTICE_WAIT_MS = 300;
 export const CLI_DISTRIBUTION = { package: '@shardflux/cli', version: CLI_VERSION };
@@ -44,7 +48,26 @@ function entryOf(doc, apiUrl, pkg) {
     const e = doc.checks[apiUrl]?.[pkg];
     if (!isObj(e) || typeof e.checked_at !== 'string' || Number.isNaN(Date.parse(e.checked_at)))
         return null;
-    return { checked_at: e.checked_at, latest: strOrNull(e.latest), minimum_supported: strOrNull(e.minimum_supported), upgrade_command: strOrNull(e.upgrade_command), release_notes_url: strOrNull(e.release_notes_url) };
+    return {
+        checked_at: e.checked_at, latest: strOrNull(e.latest), minimum_supported: strOrNull(e.minimum_supported), upgrade_command: strOrNull(e.upgrade_command), release_notes_url: strOrNull(e.release_notes_url),
+        // An entry written before 0.15.2 has no sources: its `latest` came from the catalog.
+        catalog_latest: 'catalog_latest' in e ? strOrNull(e.catalog_latest) : strOrNull(e.latest), hold: strOrNull(e.hold), registry_latest: strOrNull(e.registry_latest), registry_etag: strOrNull(e.registry_etag),
+    };
+}
+/** GET /v1/client-versions, or null when the API did not answer with JSON (never throws). */
+async function fetchCatalog(apiUrl, f, userAgent) {
+    try {
+        const res = await f(new URL('/v1/client-versions', `${apiUrl.replace(/\/+$/, '')}/`), { method: 'GET', headers: { accept: 'application/json', 'user-agent': userAgent }, signal: AbortSignal.timeout(CATALOG_TIMEOUT_MS) });
+        if (!res.ok) {
+            await res.body?.cancel().catch(() => undefined);
+            return null;
+        }
+        const body = JSON.parse(await res.text());
+        return isObj(body) && Array.isArray(body.clients) ? body : null;
+    }
+    catch {
+        return null;
+    }
 }
 /** The status the cached answer gives this distribution (the same rules as the SDK; no request). */
 export function statusFromEntry(entry, d) {
@@ -71,7 +94,7 @@ export class UpdateCheck {
         const cached = entryOf(readCache(this.#file), this.#o.apiUrl, this.#o.distribution.package);
         return cached ? { status: statusFromEntry(cached, this.#o.distribution), checkedAt: cached.checked_at } : null;
     }
-    /** Starts the check: from the cache when it is younger than 24 h (unless `force`), else one request. */
+    /** Starts the check: from the cache when it is younger than 12 h (unless `force`), else the registry and the API. */
     start(force = false) {
         const { apiUrl, distribution: d } = this.#o;
         const now = (this.#o.now ?? Date.now)();
@@ -82,14 +105,29 @@ export class UpdateCheck {
             return;
         }
         const checkedAt = new Date(now).toISOString();
-        // Record the attempt first: a request that never finishes (the command ended, the API is unreachable) still
-        // counts, and the previous answer stays until a new one arrives.
+        // Record the attempt first: requests that never finish (the command ended, the network is down) still count,
+        // and the previous answer stays until a new one arrives.
         this.#write(doc, { ...(cached ?? { latest: null, minimum_supported: null, upgrade_command: null, release_notes_url: null }), checked_at: checkedAt });
-        this.#pending = checkClientVersion({ baseUrl: apiUrl, fetch: this.#o.fetch, package: d.package, version: d.version, ecosystem: 'npm', userAgent: this.#o.userAgent }).then((status) => {
-            const answered = status.latest !== null || status.minimumSupported !== null;
-            if (!answered)
-                return { status: cached ? statusFromEntry(cached, d) : status, checkedAt: cached ? cached.checked_at : null };
-            this.#write(readCache(this.#file), { checked_at: checkedAt, latest: status.latest, minimum_supported: status.minimumSupported, upgrade_command: status.upgradeCommand, release_notes_url: status.releaseNotesUrl });
+        const f = this.#o.fetch;
+        this.#pending = Promise.all([
+            fetchCatalog(apiUrl, f, this.#o.userAgent),
+            npmLatest(d.package, { fetch: f, registry: this.#o.registry ?? NPM_REGISTRY, etag: cached?.registry_latest ? cached.registry_etag : null, userAgent: this.#o.userAgent }),
+        ]).then(([catalog, registry]) => {
+            const registryLatest = registry?.notModified ? (cached?.registry_latest ?? null) : (registry?.latest ?? null);
+            if (catalog === null && registryLatest === null) {
+                // Nobody answered: the last answer stands.
+                return { status: cached ? statusFromEntry(cached, d) : statusFromEntry(null, d), checkedAt: cached ? cached.checked_at : null };
+            }
+            // A catalog that did not answer this time: what it said last time (minimum_supported, hold) still applies.
+            const base = catalog ?? (cached ? { clients: [{ package: d.package, ecosystem: 'npm', latest: cached.catalog_latest ?? null, minimum_supported: cached.minimum_supported, upgrade_command: cached.upgrade_command, release_notes_url: cached.release_notes_url, hold: cached.hold ?? null }] } : null);
+            const merged = withRegistryLatest(base, registryLatest ? { [d.package]: registryLatest } : {});
+            const own = merged.clients.find((c) => c.ecosystem === 'npm' && c.package === d.package);
+            const status = clientVersionStatus(merged, { package: d.package, version: d.version, ecosystem: 'npm' });
+            const raw = base?.clients.find((c) => c.ecosystem === 'npm' && c.package === d.package);
+            this.#write(readCache(this.#file), {
+                checked_at: checkedAt, latest: own?.latest ?? null, minimum_supported: own?.minimum_supported ?? null, upgrade_command: own?.upgrade_command ?? null, release_notes_url: own?.release_notes_url ?? null,
+                catalog_latest: strOrNull(raw?.latest), hold: own?.hold ?? null, registry_latest: registryLatest, registry_etag: registry?.etag ?? cached?.registry_etag ?? null,
+            });
             return { status, checkedAt };
         });
     }

package/dist/update.d.ts

@@ -52,6 +52,8 @@ export interface UpdateDeps {
     run?: Runner;
     menubar?: MenubarManager;
 }
+/** True when nothing is behind but the menu bar app, and the app the npm package carries is already that version. */
+export declare function onlyAppToSwap(pending: Component[], packagedApp: string | null): boolean;
 export declare function update(ctx: Ctx, values: Record<string, unknown>, deps?: UpdateDeps): Promise<number>;
 /** Records where `shard` runs, for the menu bar's update button. Written on macOS, only when it changed. */
 export declare function recordInstall(dir: string, runtime: Runtime, distribution: {

package/dist/update.js

@@ -1,7 +1,7 @@
 /**
  * `shard update` (0.13.5+): brings this computer's Shardflux install up to date in one step. It checks every local
- * piece against GET /v1/client-versions — the package that runs `shard` (the `shardflux` bundle or `@shardflux/cli`),
- * the CLI and SDK inside it, the macOS menu bar app and a globally installed `@shardflux/mcp` — then runs one install
+ * piece against the latest versions on npm (0.15.2+; GET /v1/client-versions adds minimum_supported and hold) — the
+ * package that runs `shard` (the `shardflux` bundle or `@shardflux/cli`), the CLI and SDK inside it, the macOS menu bar app and a globally installed `@shardflux/mcp` — then runs one install
  * of the latest versions with the package manager that installed `shard`, checks the result with the new `shard`,
  * and restarts the menu bar on its new app. `--check` only reports.
  *
@@ -18,7 +18,7 @@ import { AgentStateStore } from "./agent-state.js";
 import { writePrivateFile } from "./credentials.js";
 import { CodedError } from "./errors.js";
 import { json } from "./format.js";
-import { compareBundleVersions, MenubarManager } from "./menubar.js";
+import { compareAppVersions, MenubarManager, packagedAppPath } from "./menubar.js";
 export const INSTALL_FILE = 'install.json';
 export const LAST_UPDATE_FILE = 'last-update.json';
 const LOCK_FILE = 'update.lock';
@@ -175,6 +175,10 @@ function npmFor(node) {
     const sibling = join(dirname(node), process.platform === 'win32' ? 'npm.cmd' : 'npm');
     return existsSync(sibling) ? sibling : 'npm';
 }
+/** True when nothing is behind but the menu bar app, and the app the npm package carries is already that version. */
+export function onlyAppToSwap(pending, packagedApp) {
+    return pending.every(c => c.package === MENUBAR && packagedApp !== null && c.latest !== null && compareAppVersions(packagedApp, c.latest) >= 0);
+}
 export async function update(ctx, values, deps = {}) {
     const run = deps.run ?? runProcess;
     const menubar = deps.menubar ?? menubarManager(ctx);
@@ -193,10 +197,15 @@ export async function update(ctx, values, deps = {}) {
             : `Shardflux is up to date (${versions}).\n`);
         return 0;
     }
-    if (!pending.length) {
-        // The npm package may already carry a newer menu bar app than the one running.
+    // The npm package may already carry the latest menu bar app (installed with npm, not yet swapped in): no install.
+    const packagedApp = pending.some(c => c.package === MENUBAR) ? await menubar.packagedVersion().catch(() => null) : null;
+    if (onlyAppToSwap(pending, packagedApp)) {
         const refreshed = await refreshMenubar(ctx, menubar);
-        ctx.io.stdout.write(ctx.json ? json({ ...view, updated: false, menubar: refreshed }) : `Shardflux is up to date (${versions}).\n`);
+        const changes = refreshed.status === 'restarted' ? pending.map(c => ({ package: c.package, label: c.label, from: c.current, to: refreshed.version ?? null })) : [];
+        if (changes.length)
+            writeLastUpdate(ctx.store.dir, { status: 'ok', changes, message: `Updated ${changesText(changes)}`, command });
+        ctx.io.stdout.write(ctx.json ? json({ ...view, updated: changes.length > 0, ...(changes.length ? { changes } : {}), menubar: refreshed.status })
+            : changes.length ? `Updated ${changesText(changes)}.\n` : `Shardflux is up to date (${versions}).\n`);
         return 0;
     }
     const argv = installArgv(install, specs, runtime ? npmFor(runtime.node) : 'npm');
@@ -269,7 +278,7 @@ async function refreshMenubar(ctx, menubar, runtime, run, env) {
     }
     else {
         const packaged = await menubar.packagedVersion().catch(() => null);
-        if (!packaged || !before.version || compareBundleVersions(before.version, packaged) >= 0)
+        if (!packaged || !before.version || compareAppVersions(before.version, packaged) >= 0)
             return { status: 'current' };
         await menubar.start(ctx.store.dir, ctx.apiUrl);
     }
@@ -283,7 +292,16 @@ export function recordInstall(dir, runtime, distribution) {
         script = realpathSync(script);
     }
     catch { /* keep the path */ }
-    const doc = { version: 1, node: runtime.node, script, package: distribution.package, package_version: distribution.version, cli_version: CLI_VERSION };
+    // The app this CLI's npm package carries (0.15.2+): the menu bar compares itself with it and swaps itself in.
+    let menubarApp = packagedAppPath();
+    try {
+        if (menubarApp)
+            menubarApp = realpathSync(menubarApp);
+    }
+    catch {
+        menubarApp = null;
+    }
+    const doc = { version: 1, node: runtime.node, script, package: distribution.package, package_version: distribution.version, cli_version: CLI_VERSION, ...(menubarApp ? { menubar_app: menubarApp } : {}) };
     const text = `${JSON.stringify(doc, null, 2)}\n`;
     try {
         if (readFileSync(join(dir, INSTALL_FILE), 'utf8') === text)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "type": "module",
   "description": "shard: the Shardflux command line. Create an account, sign in, set up keys and billing, then open, run commands in, move files to, suspend, resume and fork serverless agent workspaces.",
   "license": "Apache-2.0",
@@ -58,7 +58,7 @@
     "typescript-eslint": "8.70.1"
   },
   "optionalDependencies": {
-    "@shardflux/menubar-darwin": "^0.3.1"
+    "@shardflux/menubar-darwin": "^0.3.2"
   },
   "scripts": {
     "build": "node scripts/build.mjs",