@shardflux/cli 0.15.1 → 0.16.0

package/dist/handlers.js

@@ -15,5 +15,7 @@ import { MENUBAR_HANDLERS } from "./menubar.js";
 import { UPDATE_HANDLERS } from "./update.js";
 import { FILESYSTEM_HANDLERS } from "./filesystem-commands.js";
 import { CONVERSATION_HANDLERS as LOCAL_CONVERSATION_HANDLERS } from "./conversation-local.js";
+import { TWIN_HANDLERS } from "./worktree-twin-engine.js";
 import { CODEX_CLOUD_HANDLERS } from "./codex-cloud.js";
-export const HANDLERS = { ...CODEX_CLOUD_HANDLERS, ...CONVERSATION_HANDLERS, ...LOCAL_CONVERSATION_HANDLERS, ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS, ...UPDATE_HANDLERS };
+import { THREAD_HANDLERS } from "./thread-on-computer.js";
+export const HANDLERS = { ...CODEX_CLOUD_HANDLERS, ...THREAD_HANDLERS, ...CONVERSATION_HANDLERS, ...LOCAL_CONVERSATION_HANDLERS, ...TWIN_HANDLERS, ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS, ...UPDATE_HANDLERS };

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,12 +23,15 @@ 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";
 import { makeFetch } from "./http.js";
 import { Input } from "./input.js";
 import { TimingRecorder, notices, timingJson, timingText } from "./timing.js";
+import { waitStatusListener } from "./wait-status.js";
 import { CLI_DISTRIBUTION, NOTICE_WAIT_MS, UpdateCheck, noticeOf, updateCheckDisabled, updateView } from "./update-check.js";
 const KEY_SHAPE = /^sfk_[a-z2-7]{16}_[A-Za-z0-9]+$/;
 // Printable (no C0 controls or DEL), as the API's AgentLabel pattern.
@@ -124,7 +127,7 @@ function hintFor(info, cred, file, command = '') {
     if (reason === 'edit_not_text')
         return 'the file is not UTF-8 text; use files write for binary data';
     if (reason === 'host_capacity')
-        return 'the workspace cannot be woken right now and the call did not run; retry in a few seconds';
+        return "the workspace's host is making room to wake it and the call did not run (it was already retried); run the command again";
     if (reason === 'host_feature_unavailable')
         return hostFeatureHint(info.details?.feature);
     // Inbound ports (0.9.0): the next step names the command.
@@ -532,6 +535,7 @@ export async function run(argv, io, opts = {}) {
             agentLabel,
             wake,
             wakeTimeoutMs,
+            wakeTimeoutExplicit: parsed.global.wakeTimeout !== undefined || Boolean(io.env.SHARDFLUX_WAKE_TIMEOUT_MS?.trim()),
             signal,
             timing: showTiming,
             traces,
@@ -540,12 +544,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 {
@@ -559,13 +571,18 @@ export async function run(argv, io, opts = {}) {
                 if (cloud)
                     return cloud;
                 const key = apiKey();
+                // Timings, and (0.16.0+) where a wait stands: a queued start's position, a call waiting for room (stderr).
+                const waitStatus = waitStatusListener(io.stderr, parsed.global.json);
                 cloud = new Shardflux({
                     apiKey: key.token,
                     baseUrl: apiUrl,
                     userAgent,
                     fetch: watchedFetch,
                     sleep,
-                    onProgress: traces.listener,
+                    onProgress: (e) => {
+                        traces.listener(e);
+                        waitStatus(e);
+                    },
                     versionCheck: false,
                 });
                 return cloud;
@@ -624,7 +641,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 +651,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 +673,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,8 @@
+import type { RegistryOptions } from '@shardflux/sdk';
+export { NPM_REGISTRY, npmLatest, withRegistryLatest } from '@shardflux/sdk';
+/** The npm packages whose versions `shard update` compares. */
+export declare const NPM_CLIENTS: readonly ["shardflux", "@shardflux/cli", "@shardflux/sdk", "@shardflux/mcp", "@shardflux/menubar-darwin"];
+/** The registry to ask: SHARDFLUX_NPM_REGISTRY, else npm's public registry. */
+export declare function npmRegistry(env: Record<string, string | undefined>): string;
+/** `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>>;

package/dist/registry.js

@@ -0,0 +1,18 @@
+/**
+ * The latest version of each Shardflux client comes from npm (0.15.2+; the SDK's registry helpers): its `latest`
+ * dist-tag is what `npm i -g shardflux` and `shard update` install. The API catalog adds `minimum_supported` and
+ * `hold` (see withRegistryLatest).
+ */
+import { npmLatest, registryFromEnv } from '@shardflux/sdk';
+export { NPM_REGISTRY, npmLatest, withRegistryLatest } from '@shardflux/sdk';
+/** The npm packages whose versions `shard update` compares. */
+export const NPM_CLIENTS = ['shardflux', '@shardflux/cli', '@shardflux/sdk', '@shardflux/mcp', '@shardflux/menubar-darwin'];
+/** The registry to ask: SHARDFLUX_NPM_REGISTRY, else npm's public registry. */
+export function npmRegistry(env) {
+    return registryFromEnv(env, 'npm');
+}
+/** `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]] : [])));
+}