@shardflux/cli 0.15.0 → 0.15.2

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # 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`.
+
+- `shard agents open --in auto` opens a Claude conversation where you work: in Claude Desktop when it is installed (its own session, `claude://code/<session>`), else Claude Code in this terminal. With `--json` it prints `{target: "claude-desktop", url, app_bundle_id}` or `{target: "terminal", command}`. claude.ai opens with `--in web` (or a saved web target). Codex conversations open in the Codex app as before.
+
+- `shard setup` and `shard signup` print "Starting your Codex remote device…" while they wait for it.
+
 ## 0.15.0
 
 - The onboarding activity report includes the conversation's turn state for Claude and Codex, including while its VM is suspended.

package/README.md

@@ -258,10 +258,12 @@ shard auth totp recovery-codes
    "<your name>'s organization" (`--org-name` to choose); with several it lists them;
 2. the project: `--project`, the saved default, or the organization's only one; with none it creates
    "Default" (`--project-name`);
-3. an API key with every workspace tool (`--tool` repeatable to narrow it), named
+3. an API key with every workspace tool, `computer` included (0.15.1+; `--tool` repeatable to narrow it), named
    `shard-cli <hostname>` (`--key-name`), saved in the credentials file and checked against the API.
 
-It is idempotent: a saved key that still works is kept (`--new-key` makes a new one). It prints what
+It is idempotent: a saved key that still works is kept (`--new-key` makes a new one). A saved key from an earlier
+`shard setup` (every tool but `computer`) is replaced with one that has every tool (0.15.1+); the old key keeps working
+until you revoke it. It prints what
 it found or created and the next command. The key is never printed; `shard env` prints it for tools
 that read `SHARDFLUX_API_KEY`:
 
@@ -1261,7 +1263,7 @@ shard agents new --app claude --path ./ --prompt "What is wrong on this page?" -
 
 `--image <file|->` (0.15.0+, repeatable) attaches up to five PNG, JPEG, GIF or WebP images of up to 10 MiB each to that first message. They are written into the conversation VM under `/home/user/.shardflux/attachments/` and named in the message: Claude Code attaches them as images and Codex opens them with its image viewer. `--image -` reads one image, or PNG images back to back, from standard input; use a file for `--prompt-file` when images come from standard input.
 
-Use `shard agents open <workspace> --in auto --json` to resolve the remembered app destination. The result includes a `url` or `app_bundle_id` when that app route is available; the caller opens it. Explicit `--in terminal` retains terminal attachment. The menu uses this resolver for new and existing conversations, without provider URLs in Swift.
+Use `shard agents open <workspace> --in auto --json` to resolve where a conversation opens: a saved target first; then, for Claude (0.15.1+), the conversation itself in Claude Desktop when it is installed (`{"target":"claude-desktop","url":"claude://code/session_…","app_bundle_id":…}`), else Claude Code in the terminal (`{"target":"terminal","command":["shard","agents","open","<workspace>"]}`; without `--json` it attaches in this terminal). Codex opens its Cloud thread in the Codex app. claude.ai opens with `--in web`. The caller opens the `url` or app, or runs the command in a terminal. Explicit `--in terminal` retains terminal attachment. The menu uses this resolver for new and existing conversations, without provider URLs in Swift.
 
 ## Codex Cloud (0.15.0+, unreleased)
 

package/dist/account-args.js

@@ -58,7 +58,7 @@ export const ACCOUNT_COMMANDS = [
             name: { type: 'string', value: '<display name>', description: 'Your name as others see it (setup names the organization after it).' },
             codex: { type: 'boolean', description: 'Use the Codex login on this machine (default; --no-codex signs up with --email).' },
             setup: { type: 'boolean', description: 'Run shard setup afterwards (default; --no-setup skips it).' },
-            tool: { type: 'string', multiple: true, value: '<tool>', description: 'Workspace tool the saved API key may use (repeatable; exec, files, pty, process, git, browser). Default: all.' },
+            tool: { type: 'string', multiple: true, value: '<tool>', description: 'Workspace tool the saved API key may use (repeatable; exec, files, pty, process, git, browser, computer). Default: all.' },
             ...ACCEPT_TERMS,
             ...SECOND_FACTOR,
         },
@@ -210,7 +210,7 @@ export const ACCOUNT_COMMANDS = [
             'org-name': { type: 'string', value: '<name>', description: 'Name of the organization to create when you have none.' },
             'project-name': { type: 'string', value: '<name>', description: 'Name of the project to create when the organization has none (default Default).' },
             'key-name': { type: 'string', value: '<name>', description: 'Name of the API key (default "shard-cli <hostname>").' },
-            tool: { type: 'string', multiple: true, value: '<tool>', description: 'Workspace tool the key may use (repeatable; exec, files, pty, process, git, browser). Default: all.' },
+            tool: { type: 'string', multiple: true, value: '<tool>', description: 'Workspace tool the key may use (repeatable; exec, files, pty, process, git, browser, computer). Default: all.' },
             'new-key': { type: 'boolean', description: 'Create and save a new key even when the saved one works (the old key stays valid until revoked).' },
             codex: { type: 'boolean', description: 'Set up the account Codex Cloud executor with this machine’s Codex login (default when signed in); --no-codex skips it.' },
         },
@@ -281,7 +281,7 @@ export const ACCOUNT_COMMANDS = [
         description: 'Owners and admins grant workspace tools; billing members create keys without tools. The secret cannot be shown again.',
         positionals: [{ name: 'name', required: true }],
         options: {
-            tool: { type: 'string', multiple: true, value: '<tool>', description: 'Workspace tool the key may use (repeatable). Default: all six.' },
+            tool: { type: 'string', multiple: true, value: '<tool>', description: 'Workspace tool the key may use (repeatable; exec, files, pty, process, git, browser, computer). Default: all.' },
             'read-only': { type: 'boolean', description: 'No workspace tools (read-only API use).' },
             expires: { type: 'string', value: '<30d|90d|365d|never>', description: 'Expiry (default never).' },
             save: { type: 'boolean', description: 'Save it in the credentials file for the workspace commands instead of printing it.' },

package/dist/account-commands.d.ts

@@ -1,5 +1,7 @@
 import type { Handler } from './commands.js';
 export declare const DEFAULT_API_URL = "https://api.shardflux.dev";
+/** What `shard setup` gave a key before 0.15.1: every tool but `computer`. Such a saved key is replaced with a full one. */
+export declare function outdatedDefaultKey(permissions: readonly string[]): boolean;
 /**
  * The organization name setup creates: "<display name or email local part>'s organization", within the API's rules
  * for names (1-200 characters, no control characters or line breaks).

package/dist/account-commands.js

@@ -27,7 +27,15 @@ import { apiKeyTable, attachmentTable, auditTable, authSessionTable, billingStat
 export const DEFAULT_API_URL = 'https://api.shardflux.dev';
 const TOTP = /^\d{6}$/;
 const ROLES = ['owner', 'admin', 'member', 'billing'];
-const TOOL_NAMES = API_KEY_TOOL_PERMISSIONS;
+/**
+ * Every tool permission a key can carry, `computer` included (0.15.1+): the SDK's list before 0.21.1 left it out, so a
+ * key made by `shard setup` could not watch or use its workspace's desktop (computer stream 403).
+ */
+const TOOL_NAMES = [...new Set([...API_KEY_TOOL_PERMISSIONS, 'computer'])];
+/** What `shard setup` gave a key before 0.15.1: every tool but `computer`. Such a saved key is replaced with a full one. */
+export function outdatedDefaultKey(permissions) {
+    return !permissions.includes('computer') && TOOL_NAMES.every((t) => t === 'computer' || permissions.includes(t));
+}
 const DEFAULT_CHECKOUT_WAIT_MS = 15 * 60_000;
 const CHECKOUT_POLL_MS = 2_000;
 const NEXT_WORKSPACE = 'shard ws open demo --template python-node-browser';
@@ -307,7 +315,7 @@ async function checkKey(ctx, token) {
         const cloud = new Shardflux({ ...ctx.accountOptions(), apiKey: token });
         const me = await cloud.me();
         if (me.type === 'api_key' && me.api_key)
-            return { ok: true, organizationId: me.api_key.organization_id, projectId: me.api_key.project_id };
+            return { ok: true, organizationId: me.api_key.organization_id, projectId: me.api_key.project_id, toolPermissions: me.api_key.tool_permissions ?? [] };
         return { ok: false, reason: 'not a project API key' };
     }
     catch (err) {
@@ -622,7 +630,12 @@ async function runSetup(ctx, values, account) {
         else
             throw new UsageError(`${org.name} has ${projects.length} projects; pick one with --project <id|slug>:\n${choices(projects)}\n`, 'or save a default first: shard projects use <id|slug>');
     }
-    const keep = keyCheck?.ok === true && profile.api_key?.project_id === project.id;
+    // A key from an earlier `shard setup` (every tool but computer) is replaced unless --tool asks for a set: the desktop
+    // stream and screenshots need `computer`. The old key stays valid until revoked.
+    const outdated = keyCheck?.ok === true && strs(values.tool).length === 0 && values['read-only'] !== true && outdatedDefaultKey(keyCheck.toolPermissions);
+    if (outdated && !ctx.json)
+        ctx.io.stderr.write(`note: the saved API key ${profile.api_key.key_id} cannot use computer use; creating one with every tool.\n`);
+    const keep = keyCheck?.ok === true && profile.api_key?.project_id === project.id && !outdated;
     let key;
     let permissions = tools;
     if (keep)
@@ -655,6 +668,8 @@ async function runSetup(ctx, values, account) {
         const cloud = new Shardflux({ apiKey: key.token, baseUrl: ctx.apiUrl });
         await syncAgentCredentials(cloud, { home: credentialHome, redact: value => ctx.addSecret(value) });
         await cloud.codex.enable({ signal: ctx.signal });
+        if (!ctx.json)
+            ctx.io.stderr.write('Starting your Codex remote device…\n');
         codex = { ...await cloud.codex.waitConnector({ timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal }) };
     }
     const envNote = ctx.io.env.SHARDFLUX_API_KEY?.trim() ? 'note: SHARDFLUX_API_KEY is set in this environment and wins over the saved key; unset it to use the saved key.\n' : '';

package/dist/agent-commands.js

@@ -11,7 +11,7 @@ import { prepareProjectTemplate } from "./project-template-setup.js";
 import { projectIdentity, projectLabels } from "./project-identity.js";
 import { ensureProjectGit } from "./project-git.js";
 import { json } from "./format.js";
-import { resolveWorkspace } from "./commands.js";
+import { out, resolveWorkspace } from "./commands.js";
 import { savedMachine } from "./filesystem-state.js";
 import { startAgentConfigTunnels, syncAgentConfig } from "./agent-config-sync.js";
 import { rememberGitAgent } from "./agent-git-commands.js";
@@ -22,7 +22,7 @@ import { progress } from "./progress.js";
 import { rememberLaunch } from "./agent-live.js";
 import { prepareAgentMachine } from "./agent-machine.js";
 import { installedTargets } from "./agent-targets.js";
-import { openDesktopWorkspace, queueT3Prewarm } from "./agent-target-commands.js";
+import { openClaudeDesktopSession, openDesktopWorkspace, queueT3Prewarm } from "./agent-target-commands.js";
 import { submitInitialPrompt, prepareInitialCodexProject } from "./initial-prompt.js";
 import { conversationWorkspace, conversationsUnavailable, getConversation, listConversations, resumeConversation } from "./conversations.js";
 import { conversationTerminal } from "./conversation-terminal.js";
@@ -272,12 +272,26 @@ export const AGENT_HANDLERS = {
                 delete next.in;
                 return AGENT_HANDLERS['agents open'](ctx, next, [ws.key]);
             }
-            const target = saved && detected.targets.includes(saved) ? saved : 'web';
-            const { HANDLERS } = await import("./handlers.js");
-            const handler = HANDLERS[`agents open ${target}`];
-            if (!handler)
-                throw new UsageError('Choose an installed open target with shard agents targets.');
-            return handler(ctx, { ...values, in: target }, [ws.key]);
+            if (saved && detected.targets.includes(saved)) {
+                const { HANDLERS } = await import("./handlers.js");
+                const handler = HANDLERS[`agents open ${saved}`];
+                if (!handler)
+                    throw new UsageError('Choose an installed open target with shard agents targets.');
+                return handler(ctx, { ...values, in: saved }, [ws.key]);
+            }
+            // Claude opens where people work (0.15.1+): the conversation in Claude Desktop when it is installed, else Claude
+            // Code in a terminal. The browser (claude.ai) only when it is the chosen target (--in web).
+            if (detected.clients.includes('claude-desktop')) {
+                return openClaudeDesktopSession(ctx, ws);
+            }
+            if (ctx.json) {
+                // An app runs this in the person's terminal (the menu bar opens Terminal with it).
+                out(ctx, `shard agents open ${ws.key}\n`, { target: 'terminal', workspace: ws.data, command: ['shard', 'agents', 'open', ws.key] });
+                return 0;
+            }
+            const next = { ...values };
+            delete next.in;
+            return AGENT_HANDLERS['agents open'](ctx, next, [ws.key]);
         }
         if (values.in !== undefined && values.in !== 'terminal') {
             const { HANDLERS } = await import("./handlers.js");

package/dist/agent-target-commands.d.ts

@@ -8,6 +8,20 @@ export declare function installDeviceKey(cell: CellClient, key: string, signal?:
 /** Host trust is established over the authenticated files API, before sending any SSH protocol bytes. */
 export declare function prepareSsh(ws: Workspace, ctx: Ctx, targets: AgentTargets, host: string): Promise<CellClient>;
 export declare function proxyStream(io: Io, ended?: () => void, outputGate?: Promise<unknown>): Duplex;
+/**
+ * The Remote Control URL (https://claude.ai/code/session_…) of the workspace's live Claude session. A Claude process
+ * this computer just started can accept its first prompt before Remote Control registers, so an open of our recent
+ * launch probes the guest for up to 30 s; history browsing stays passive.
+ */
+export declare function remoteControlUrl(ctx: Ctx, ws: Workspace): Promise<string>;
+/** Claude Desktop's own link to a Remote Control session: claude://code/<session id> opens it in its Code tab. */
+export declare function claudeDesktopLink(remoteControl: string): string;
+export declare const CLAUDE_DESKTOP_BUNDLE = "com.anthropic.claudefordesktop";
+/**
+ * Opens the conversation itself (its live Remote Control session) in Claude Desktop (0.15.1+), the way `--in auto`
+ * opens a Claude conversation when Claude Desktop is installed. --json prints {target, url, app_bundle_id} for apps.
+ */
+export declare function openClaudeDesktopSession(ctx: Ctx, ws: Workspace): Promise<number>;
 export declare function openDesktopWorkspace(ctx: Ctx, ws: Workspace, target: DesktopTarget, t3Version?: string, prewarmed?: boolean): Promise<number>;
 export declare function queueT3Prewarm(ctx: Ctx, ws: Workspace, version: string): Promise<void>;
 export declare const TARGET_HANDLERS: Record<string, Handler>;

package/dist/agent-target-commands.js

@@ -132,6 +132,78 @@ export function proxyStream(io, ended, outputGate) {
     source.once('error', (error) => stream.destroy(error));
     return stream;
 }
+/**
+ * The Remote Control URL (https://claude.ai/code/session_…) of the workspace's live Claude session. A Claude process
+ * this computer just started can accept its first prompt before Remote Control registers, so an open of our recent
+ * launch probes the guest for up to 30 s; history browsing stays passive.
+ */
+export async function remoteControlUrl(ctx, ws) {
+    let cursor;
+    let url;
+    do {
+        const page = await ctx.cloud().agents.list({ limit: 200, ...(cursor ? { cursor } : {}) });
+        url = page.data.find(a => a.workspace_id === ws.id && a.app === 'claude' && a.state !== 'exited' && a.remote_control_url)?.remote_control_url;
+        cursor = page.nextCursor ?? undefined;
+    } while (!url && cursor && !ctx.signal.aborted);
+    // A new Claude process can accept its first prompt before Remote Control registers.
+    // Only an explicit open of our recent launch probes the guest; history browsing stays passive.
+    const launchedAt = new AgentStateStore(ctx.store.dir).read().agent_launches?.[ws.id];
+    if (!url && typeof launchedAt === 'number' && Date.now() - launchedAt < LAUNCH_WINDOW_MS && ws.ready) {
+        const waitMs = Math.min(ctx.wakeTimeoutMs, RECENT_LAUNCH_URL_WAIT_MS);
+        const deadline = Date.now() + waitMs;
+        const cell = ws.cell({ agentLabel: ctx.agentLabel });
+        while (!url && Date.now() < deadline) {
+            const result = await cell.exec.run(['sf-agent', 'list'], {
+                timeoutMs: Math.min(10_000, Math.max(1, deadline - Date.now())), signal: ctx.signal, maxOutputBytes: 1 << 20,
+            });
+            if (result.exitCode !== 0)
+                break;
+            url = guestSessions(result.stdout).find(a => a.app === 'claude' && a.state !== 'exited' && a.remote_control_url)?.remote_control_url;
+            if (!url && Date.now() < deadline)
+                await delay(Math.min(250, Math.max(1, deadline - Date.now())), undefined, { signal: ctx.signal });
+        }
+        if (!url)
+            throw new Error(`Claude in ${ws.key} did not publish a Remote Control URL within ${Math.ceil(waitMs / 1000)} s; run shard agents open ${ws.key} again`);
+    }
+    if (!url)
+        throw new UsageError(`${ws.key} has no active Remote Control URL; start Claude with Remote Control first`);
+    const parsed = new URL(url);
+    if (parsed.protocol !== 'https:' || parsed.hostname !== 'claude.ai' || !parsed.pathname.startsWith('/code/') || parsed.username || parsed.password)
+        throw new Error('agent returned an invalid Claude Remote Control URL');
+    return url;
+}
+/** Claude Desktop's own link to a Remote Control session: claude://code/<session id> opens it in its Code tab. */
+export function claudeDesktopLink(remoteControl) {
+    const id = new URL(remoteControl).pathname.split('/')[2] ?? '';
+    if (!/^(cse|session)_[A-Za-z0-9_-]+$/.test(id))
+        throw new Error('agent returned an invalid Claude Remote Control URL');
+    return `claude://code/${id}`;
+}
+export const CLAUDE_DESKTOP_BUNDLE = 'com.anthropic.claudefordesktop';
+/**
+ * Opens the conversation itself (its live Remote Control session) in Claude Desktop (0.15.1+), the way `--in auto`
+ * opens a Claude conversation when Claude Desktop is installed. --json prints {target, url, app_bundle_id} for apps.
+ */
+export async function openClaudeDesktopSession(ctx, ws) {
+    await ensureCloudClaude(ctx, ws);
+    const session = await remoteControlUrl(ctx, ws);
+    const url = claudeDesktopLink(session);
+    if (!ctx.json)
+        await openLink(url, ctx.io.env);
+    out(ctx, `${url}\n`, { target: 'claude-desktop', workspace: ws.data, url, remote_control_url: session, app_bundle_id: CLAUDE_DESKTOP_BUNDLE });
+    return 0;
+}
+async function openLink(url, env) {
+    const child = spawn('open', [url], { env, stdio: 'ignore' });
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { child.kill('SIGKILL'); reject(new Error('Claude Desktop did not open in time')); }, 10_000);
+        child.once('error', e => { clearTimeout(timer); reject(e); });
+        child.once('exit', code => { clearTimeout(timer); if (code === 0)
+            resolve();
+        else
+            reject(new Error(`could not open ${url}`)); });
+    });
+}
 const openTarget = (target) => async (ctx, values, [ref = 'main']) => {
     const detected = installedTargets(ctx.io.env);
     if (target !== 'web' && !detected.targets.includes(target))
@@ -142,38 +214,7 @@ const openTarget = (target) => async (ctx, values, [ref = 'main']) => {
     if (target !== 'codex-app')
         await ensureCloudClaude(ctx, ws);
     if (target === 'web') {
-        let cursor;
-        let url;
-        do {
-            const page = await ctx.cloud().agents.list({ limit: 200, ...(cursor ? { cursor } : {}) });
-            url = page.data.find(a => a.workspace_id === ws.id && a.app === 'claude' && a.state !== 'exited' && a.remote_control_url)?.remote_control_url;
-            cursor = page.nextCursor ?? undefined;
-        } while (!url && cursor && !ctx.signal.aborted);
-        // A new Claude process can accept its first prompt before Remote Control registers.
-        // Only an explicit open of our recent launch probes the guest; history browsing stays passive.
-        const launchedAt = new AgentStateStore(ctx.store.dir).read().agent_launches?.[ws.id];
-        if (!url && typeof launchedAt === 'number' && Date.now() - launchedAt < LAUNCH_WINDOW_MS && ws.ready) {
-            const waitMs = Math.min(ctx.wakeTimeoutMs, RECENT_LAUNCH_URL_WAIT_MS);
-            const deadline = Date.now() + waitMs;
-            const cell = ws.cell({ agentLabel: ctx.agentLabel });
-            while (!url && Date.now() < deadline) {
-                const result = await cell.exec.run(['sf-agent', 'list'], {
-                    timeoutMs: Math.min(10_000, Math.max(1, deadline - Date.now())), signal: ctx.signal, maxOutputBytes: 1 << 20,
-                });
-                if (result.exitCode !== 0)
-                    break;
-                url = guestSessions(result.stdout).find(a => a.app === 'claude' && a.state !== 'exited' && a.remote_control_url)?.remote_control_url;
-                if (!url && Date.now() < deadline)
-                    await delay(Math.min(250, Math.max(1, deadline - Date.now())), undefined, { signal: ctx.signal });
-            }
-            if (!url)
-                throw new Error(`Claude in ${ws.key} did not publish a Remote Control URL within ${Math.ceil(waitMs / 1000)} s; run shard agents open ${ws.key} again`);
-        }
-        if (!url)
-            throw new UsageError(`${ws.key} has no active Remote Control URL; start Claude with Remote Control first`);
-        const parsed = new URL(url);
-        if (parsed.protocol !== 'https:' || parsed.hostname !== 'claude.ai' || !parsed.pathname.startsWith('/code/') || parsed.username || parsed.password)
-            throw new Error('agent returned an invalid Claude Remote Control URL');
+        const url = await remoteControlUrl(ctx, ws);
         if (!ctx.json && !openUrl(url, ctx.io.env))
             throw new Error(`could not open ${url}`);
         out(ctx, `${url}\n`, { target, workspace: ws.data, url });

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.15.0";
+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.0';
+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).' },
@@ -1207,7 +1207,7 @@ const AGENT_COMMANDS = [
         },
     })),
     ...['status', 'enable', 'disable'].map(action => ({ path: ['agents', 'codex', action], summary: `${action} the account's billed Codex Cloud connector`, positionals: [], options: {} })),
-    { path: ['agents', 'open'], summary: 'Open a conversation (Codex Cloud or the native Claude session)', description: 'Codex opens its existing Cloud thread without waking its VM. Claude attaches its native session.', positionals: [{ name: 'agent', required: true }], options: { ...AGENT_OPTIONS, app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default remembered choice).' }, in: { type: 'string', value: '<terminal|auto|claude-desktop|codex-app|web|t3>', description: 'Where to open a legacy session.' } } },
+    { path: ['agents', 'open'], summary: 'Open a conversation (Codex Cloud or the native Claude session)', description: 'Codex opens its existing Cloud thread without waking its VM. Claude attaches its native session.', positionals: [{ name: 'agent', required: true }], options: { ...AGENT_OPTIONS, app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default remembered choice).' }, in: { type: 'string', value: '<terminal|auto|claude-desktop|codex-app|web|t3>', description: 'Where to open it. auto (0.15.1+): the saved target, else a Claude conversation in Claude Desktop when it is installed, else in this terminal; web opens claude.ai.' } } },
     { path: ['agents', 'new'], summary: 'Start a conversation in a fresh VM; Codex opens a genuine Cloud thread', positionals: [{ name: 'agent' }], options: {
             ...AGENT_OPTIONS,
             computer: COMPUTER_OPTION,
@@ -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/format.js

@@ -813,10 +813,12 @@ export function keyStatus(k, now = Date.now()) {
         return 'expired';
     return 'active';
 }
+/** Every workspace tool a key can carry (`computer` since the API's computer use). */
+const ALL_TOOLS = ['exec', 'files', 'pty', 'process', 'git', 'browser', 'computer'];
 export function toolsText(tools) {
     if (tools.length === 0)
         return '(none: read-only)';
-    return tools.length === 6 ? 'all' : tools.join(',');
+    return ALL_TOOLS.every((t) => tools.includes(t)) ? 'all' : tools.join(',');
 }
 export function apiKeyTable(rows, savedId) {
     return table(['', 'ID', 'KEY ID', 'NAME', 'TOOLS', 'STATUS', 'CREATED', 'EXPIRES', 'LAST USED'], rows.map((k) => [mark(k.id === savedId), k.id, k.key_id, k.name, toolsText(k.tool_permissions), keyStatus(k), time(k.created_at), time(k.expires_at), time(k.last_used_at)]));

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 {};