@shardflux/cli 0.13.3 → 0.13.5

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.13.5
+
+- `shard update` brings this computer's Shardflux install up to date in one step: it checks shard (the `shardflux`
+  package or `@shardflux/cli`), its SDK, the macOS menu bar app and a globally installed `@shardflux/mcp` against the
+  latest versions, runs one install with the package manager that installed shard (npm in its own prefix, pnpm, bun
+  or Volta), checks the result with the new shard and restarts the menu bar on its new app. `--check` only reports;
+  `--json` for both. A prefix npm cannot write to fails with `update_permission_denied` and the exact command to run.
+- The menu bar's Update button runs `shard update`: each `shard` run on macOS records where it runs
+  (`install.json` in the config directory), and `shard update` records its outcome (`last-update.json`).
+- `shard` replaces a running menu bar app that is older than the one its npm package carries (after
+  `npm i -g shardflux`, the old app used to keep running).
+- The daily update notice and `shard version` say `Update: shard update`.
+- `shard agents list` shows each session's latest message (LAST MESSAGE); `--json` returns it as `last_message`.
+
+## 0.13.4
+
+- Cloud Claude sign-in and reopening the machine editor preserve existing workspace labels while updating their own labels.
+- `shard billing status` on the signup trial suggests `shard billing upgrade pro` when the live catalog offers Pro (the trial is 60 days of Pro from catalog live-v10); otherwise it points to `shard billing plans`.
+- Reuse an account-private setup cache across projects after the agent starts; report cache scope with `shard template --json`.
+- Machine and project filesystem status shows the current platform base and whether a rebase is pending.
+
 ## 0.13.3
 
 - `shard ./` seeds the workspace repository with the checked-out branch and its upstream only, not every local branch, tag and stash. When that history is still above 256 MiB, the workspace fetches the branch from origin with its own Git credentials and receives only the commits origin does not have yet. The workspace branch tracks its origin branch.
@@ -13,7 +34,7 @@
 - Git history above the first copy's 256 MiB limit fails with `repository_too_large` and its next step in the hint, not `internal_error`.
 - A `revision_mismatch` suggests `--expected-revision` only for the file commands that take it; elsewhere it says to run the same command again.
 - Config sync reports project entries keyed by paths on this computer (Codex `config.projects.*`) as one summary line.
-- The command center does not show a setup step that `.shardflux/setup.yaml` marks `required: false` as the setup failure while the template saves, and reads skipped steps (coding template 8+).
+- The command center does not show a setup step that `.shardflux/setup.yaml` marks `required: false` as the setup failure while the template saves, and reads skipped steps (coding template 10+).
 
 ## 0.13.2
 

package/README.md

@@ -264,9 +264,9 @@ plan only when Stripe confirms the payment, so `--wait` polls until the subscrip
 open). An organization that already has a subscription changes plans in the billing portal: the
 command prints the portal URL instead (exit 0).
 
-On the signup trial (60 days at Developer limits, no card), `billing status` shows when it ends and
+On the signup trial (60 days of Pro, no card), `billing status` shows when it ends and
 what follows (0.6.2+): `plan  trial, ends 2026-11-29 14:03:00Z, then free (trial, catalog ...)`, then
-`keep these limits after the trial: shard billing upgrade developer`. A subscription outranks the
+`keep these limits after the trial: shard billing upgrade pro` (0.13.4+). A subscription outranks the
 trial and ends it. The trial is granted, never bought, so `billing plans` leaves it out.
 
 `billing overage` shows and changes opt-in overage (owners and billing members). With it on,
@@ -283,7 +283,7 @@ already charged this period (`spend_cap_below_charges`); a plan without overage
 ```text
 $ shard billing overage on --cap 9
 Acme: overage is on, spend cap $9.00 per billing period ($1.00 to $9.00, the plan price).
-Rates past the allowances: $0.03 per RAM GiB-hour, $0.12 per CPU-hour, charged on the next invoice (this period: shard usage).
+Rates past the allowances: $0.015 per RAM GiB-hour, $0.04 per CPU-hour, charged on the next invoice (this period: shard usage).
 Saved (policy version 1).
 ```
 
@@ -346,12 +346,26 @@ and the session renewals of step-up and password changes).
 - **Never printed:** the session and the saved key appear only in the file. Output shows key ids; error
   output redacts anything shaped like a key or session token. `shard env` prints the key on purpose.
 
+## Update
+
+`shard update` **(0.13.5+)** brings everything Shardflux installed on this computer up to date: shard itself
+(the `shardflux` package or `@shardflux/cli`), its SDK, the macOS menu bar app and a globally installed
+`@shardflux/mcp`. It runs one install of the latest versions with the package manager that installed shard (npm,
+pnpm, bun or Volta) and restarts the menu bar on its new app. The menu bar's **Update** button runs the same command.
+
+```sh
+shard update --check   # what is behind, without installing
+shard update
+```
+
+Projects that depend on `@shardflux/sdk` or the Python `shardflux` package keep the versions their lockfiles pin.
+
 ## Version check
 
 `shard` tells you when a newer version exists, on stderr after the command's output:
 
 ```text
-@shardflux/cli 0.5.0 is outdated: 0.6.0 is available. Update: npm i -g shardflux
+@shardflux/cli 0.13.5 is outdated: 0.14.0 is available. Update: shard update
 ```
 
 or that the API no longer supports it (`... is no longer supported by the Shardflux API (minimum
@@ -828,12 +842,12 @@ amount:
 ```text
 overage          accruing (usage past the allowances is charged on the next invoice)
 spend cap        $9.00 (at most $9.00, the plan price)
-overage charges  $2.40 of $9.00 (26.67%), $6.60 left; billed on the next invoice
+overage charges  $1.10 of $9.00 (12.22%), $7.90 left; billed on the next invoice
 cap reached      2026-09-29 15:02:46Z (projected at this period's average use)
 
-OVERAGE        UNIT       PAST ALLOWANCE  BILLED  RATE   AMOUNT
-ram_gib_hours  gib_hours  70              60      $0.03  $1.80
-cpu_hours      hours      5               5       $0.12  $0.60
+OVERAGE        UNIT       PAST ALLOWANCE  BILLED  RATE    AMOUNT
+ram_gib_hours  gib_hours  70              60      $0.015  $0.90
+cpu_hours      hours      5               5       $0.04   $0.20
 ```
 
 `--json` prints the API's summary, with `spend_cap` and `exhausted_reason`. Owners and billing members turn overage on

package/dist/account-commands.js

@@ -1403,12 +1403,15 @@ export const ACCOUNT_HANDLERS = {
         const account = ctx.account();
         const org = await resolveOrg(ctx, account, values);
         const s = await account.billing.subscription(org.id);
-        // The trial has Developer limits: Developer keeps them (a subscription outranks the trial and ends it).
+        // The trial has Pro's limits and allowances (catalog live-v10): Pro keeps them (a subscription outranks the trial and ends it).
+        // Name Pro only while the live catalog sells it; a catalog without Pro gets the general hint.
+        const trialToPro = !s.subscription && s.purchase_available && s.plan?.plan_key === 'trial'
+            && (await fetchBillingCatalog({ baseUrl: ctx.apiUrl, fetch: ctx.accountOptions().fetch ?? fetch }).catch(() => null))?.plans?.some((p) => p.plan_key === 'pro') === true;
         const next = s.subscription
             ? 'manage it: shard billing portal'
             : s.purchase_available
-                ? s.plan?.plan_key === 'trial'
-                    ? 'keep these limits after the trial: shard billing upgrade developer'
+                ? trialToPro
+                    ? 'keep these limits after the trial: shard billing upgrade pro'
                     : 'buy a plan: shard billing plans, then shard billing upgrade <plan>'
                 : '';
         out(ctx, `${billingStatusText(s, org)}${next ? `${next}\n` : ''}`, s);

package/dist/agent-commands.d.ts

@@ -3,6 +3,6 @@ import type { Ctx, Handler } from './commands.js';
 /** `<slug>-<6 hex of sha256(identity)>`: the same repository gets the same key on every machine. */
 export declare function disambiguatedSlug(slug: string, identity: string): string;
 export declare function projectTemplate(ctx: Ctx, remote: string | null): Promise<string>;
-export declare function agentPty(cell: CellClient, app: 'claude' | 'codex', agent: string, approvals: boolean, term: string, signal?: AbortSignal, project?: string, setupHash?: string, cwd?: string, ptyName?: string, onLaunch?: () => void): Promise<PtySession>;
+export declare function agentPty(cell: CellClient, app: 'claude' | 'codex', agent: string, approvals: boolean, term: string, signal?: AbortSignal, project?: string, setupHash?: string, cwd?: string, ptyName?: string, onLaunch?: () => void, deferSetup?: boolean): Promise<PtySession>;
 export declare const launchProject: Handler;
 export declare const AGENT_HANDLERS: Record<string, Handler>;

package/dist/agent-commands.js

@@ -1,3 +1,4 @@
+import { prepareSetupCache } from "./setup-cache.js";
 import { agentReachability } from "./agent-reachability.js";
 import { configureCredentialFill, watchCredentialPrompts } from "./credential-prompts.js";
 import { createHash } from 'node:crypto';
@@ -39,11 +40,11 @@ export async function projectTemplate(ctx, remote) {
         throw error;
     }
 }
-export async function agentPty(cell, app, agent, approvals, term, signal, project, setupHash, cwd, ptyName, onLaunch) {
+export async function agentPty(cell, app, agent, approvals, term, signal, project, setupHash, cwd, ptyName, onLaunch, deferSetup = false) {
     const id = `shard-${ptyName || agent}-${app}`;
     // Arrival and changed locks queue the same durable guest job even when the
     // native agent is already alive. Setup never becomes its first user turn.
-    if (setupHash) {
+    if (setupHash && !deferSetup) {
         const queued = await cell.exec.run(['sf-agent', 'setup-start', '--deps-hash', setupHash], { timeoutMs: 30_000, maxOutputBytes: 4096, signal, ...(cwd ? { cwd } : {}) });
         if (queued.exitCode !== 0)
             throw new Error(`project setup could not be queued: ${queued.stderr.trim() || `exit ${queued.exitCode}`}`);
@@ -59,7 +60,7 @@ export async function agentPty(cell, app, agent, approvals, term, signal, projec
     }
     onLaunch?.();
     const launch = await cell.exec.run(['sf-agent', 'run', app, '--name', agent, '--detach', ...(ptyName ? ['--pty-name', ptyName] : []), ...(approvals ? ['--approvals'] : []), ...(setupHash ? ['--setup', '--setup-deps-hash', setupHash] : [])], {
-        env: { TERM: term, ...(project ? { SF_PROJECT_NAME: project } : {}) }, timeoutMs: 30_000, maxOutputBytes: 4096, signal, ...(cwd ? { cwd } : {}),
+        env: { TERM: term, ...(project ? { SF_PROJECT_NAME: project } : {}), ...(setupHash && deferSetup ? { SF_SETUP_DEFERRED: '1' } : {}) }, timeoutMs: 30_000, maxOutputBytes: 4096, signal, ...(cwd ? { cwd } : {}),
     });
     if (launch.exitCode !== 0)
         throw new Error(`agent launch failed: ${launch.stderr.trim() || `exit ${launch.exitCode}`}`);
@@ -88,14 +89,25 @@ async function terminal(ctx, ws, app, agent, project, values, setupHash, cwd = w
     try {
         const credentialFill = await configureCredentialFill(ctx, ws);
         // A cold launch is remembered before it starts, so the listing can show it before the projection does (agent-live.ts).
-        const session = await agentPty(cell, app, agent, values.approvals === true, ctx.io.env.TERM || 'xterm-256color', ctx.signal, ws.labels.shard_project || ws.key.split('/')[0], setupHash, cwd, ws.labels.agent_pty_name, () => { rememberLaunch(ctx, ws.id); progress(ctx, `Starting ${app === 'claude' ? 'Claude' : 'Codex'} in ${ws.key}…`); });
+        const session = await agentPty(cell, app, agent, values.approvals === true, ctx.io.env.TERM || 'xterm-256color', ctx.signal, ws.labels.shard_project || ws.key.split('/')[0], setupHash, cwd, ws.labels.agent_pty_name, () => { rememberLaunch(ctx, ws.id); progress(ctx, `Starting ${app === 'claude' ? 'Claude' : 'Codex'} in ${ws.key}…`); }, true);
+        // The real agent is running before any cache provisioning or mount wait.
+        const preparation = prepareSetupCache(ctx, ws).catch((error) => {
+            ctx.io.stderr.write(`Account setup cache unavailable: ${error instanceof Error ? error.message : String(error)}\n`);
+        }).then(async () => {
+            if (!setupHash)
+                return;
+            const queued = await cell.exec.run(['sf-agent', 'setup-start', '--deps-hash', setupHash], { cwd, timeoutMs: 30_000, maxOutputBytes: 4096, signal: ctx.signal });
+            if (queued.exitCode !== 0)
+                throw new Error(`project setup could not be queued: ${queued.stderr.trim() || `exit ${queued.exitCode}`}`);
+        });
         store.save(project, app);
         if (!attach) {
+            await preparation;
             ctx.io.stdout.write(json({ workspace: ws.data, session }));
             return 0;
         }
         ctx.io.stderr.write(`Shardflux · ${ws.key}\nDetach: Ctrl-] then d\n`);
-        return await attachTerminal({
+        const attached = attachTerminal({
             ...(credentialFill ? { credentialPrompts: (ask, signal) => watchCredentialPrompts(ctx, ws, ask, signal) } : {}),
             io: ctx.io, signal: ctx.signal, connect: cellConnector(cell, session.session_id),
             wake: (signal) => ws.wake({ timeoutMs: ctx.wakeTimeoutMs, signal }),
@@ -108,8 +120,11 @@ async function terminal(ctx, ws, app, agent, project, values, setupHash, cwd = w
                     done();
             }),
         });
+        const [code] = await Promise.all([attached, preparation]);
+        return code;
     }
     finally {
+        cell.close();
         await tunnels?.stop();
     }
 }

package/dist/agent-credentials.js

@@ -76,8 +76,15 @@ export const AGENT_CREDENTIAL_HANDLERS = {
         }
         requireClaudeTerminal(ctx);
         const project = projectIdentity('./');
-        const ws = typeof values.workspace === 'string' ? await resolveWorkspace(ctx, values.workspace)
-            : await ctx.cloud().workspaces.open({ key: `${project.slug}/main`, template: 'coding', labels: projectLabels(project, 'main', 'claude'), wait: { signal: ctx.signal, timeoutMs: ctx.wakeTimeoutMs } });
+        let ws;
+        if (typeof values.workspace === 'string')
+            ws = await resolveWorkspace(ctx, values.workspace);
+        else {
+            const cloud = ctx.cloud();
+            const key = `${project.slug}/main`;
+            const current = await cloud.workspaces.findByKey(key, { includeDeleted: false, signal: ctx.signal });
+            ws = await cloud.workspaces.open({ key, template: 'coding', labels: { ...current?.labels, ...projectLabels(project, 'main', 'claude') }, wait: { signal: ctx.signal, timeoutMs: ctx.wakeTimeoutMs } });
+        }
         output(ctx, await loginClaudeInWorkspace(ctx, ws));
         return 0;
     },

package/dist/agent-live.d.ts

@@ -8,6 +8,7 @@ interface GuestSession {
     since_unix_ms: number;
     title: string;
     remote_control_url: string;
+    last_message?: string;
 }
 /** Parses `sf-agent list` stdout; anything malformed yields no sessions rather than a wrong row. */
 export declare function guestSessions(stdout: string): GuestSession[];

package/dist/agent-live.js

@@ -61,7 +61,9 @@ export async function withLiveAgents(ctx, agents, filter, now = Date.now()) {
                 return [];
             return guestSessions(result.stdout).map(s => ({
                 id: `${w.id}:${s.session_id}`, workspace_id: w.id, workspace_key: w.workspace_key, app: s.app, state: s.state,
-                since: new Date(s.since_unix_ms).toISOString(), title: s.title, remote_control_url: s.remote_control_url, labels: w.labels,
+                since: new Date(s.since_unix_ms).toISOString(), title: s.title, remote_control_url: s.remote_control_url,
+                // A guest from before the latest message (coding templates before it) lists none.
+                last_message: typeof s.last_message === 'string' ? s.last_message : '', labels: w.labels,
             }));
         }
         catch (error) {

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.13.3";
+export declare const CLI_VERSION = "0.13.5";
 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.13.3';
+export const CLI_VERSION = '0.13.5';
 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).' },
@@ -161,6 +161,19 @@ const KEY_COMMANDS = [
         options: {},
     },
     { path: ['whoami'], summary: 'Show the principal behind the project API key (SHARDFLUX_API_KEY, else the saved one)', positionals: [], options: {} },
+    {
+        path: ['update'],
+        summary: 'Update shard, the menu bar app and a global MCP server to their latest versions',
+        description: [
+            'Checks every local Shardflux piece against GET /v1/client-versions: shard (the shardflux package or @shardflux/cli),',
+            'its SDK, the macOS menu bar app and a globally installed @shardflux/mcp. When one is behind, runs one install of',
+            'the latest versions with the package manager that installed shard (npm, pnpm, bun or Volta), then restarts the',
+            'menu bar on its new app. --check only reports. Projects that depend on @shardflux/sdk or shardflux (Python) keep',
+            'their own versions.',
+        ].join('\n'),
+        positionals: [],
+        options: { check: { type: 'boolean', description: 'Report what is behind without installing anything.' } },
+    },
     {
         path: ['version'],
         summary: 'Print the CLI and SDK versions and whether a newer shard is available',
@@ -1540,7 +1553,7 @@ export const HELP_SECTIONS = [
     { title: 'Account (a user session: shard signup or shard auth login)', groups: ['signup', 'verify', 'auth', 'setup', 'env', 'orgs', 'projects', 'api-keys', 'members', 'invitations', 'billing', 'audit', 'account'] },
     { title: 'Workspaces (a project API key: SHARDFLUX_API_KEY, else the one shard setup saved)', groups: ['login', 'whoami', 'status', 'usage', 'machine', 'template', 'agents', 'ssh-proxy', 'workspaces', 'files', 'operations', 'executions', 'secrets', 'credentials', 'volumes', 'egress'] },
     { title: 'Templates (publish and archive use the session; the rest the API key)', groups: ['templates'] },
-    { title: 'Other', groups: ['menubar', 'feedback', 'version'] },
+    { title: 'Other', groups: ['menubar', 'update', 'feedback', 'version'] },
 ];
 export function topHelp() {
     const w = Math.max(...COMMANDS.map((c) => usageLine(c).length));

package/dist/commands.d.ts

@@ -64,6 +64,10 @@ export interface Ctx {
     input: Input;
     /** The package that runs the CLI (the version check's identity). */
     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. */
+    clientVersions(): Promise<unknown>;
     /** This machine's name (default API key name of `shard setup`). */
     hostname(): string;
 }

package/dist/commands.js

@@ -818,7 +818,9 @@ export const KEY_HANDLERS = {
         // A complete listing also shows sessions the projection has not picked up yet (agent-live.ts).
         if (!next && !str(values.cursor))
             rows.splice(0, rows.length, ...await withLiveAgents(ctx, rows, { ...(state ? { state } : {}), labels }));
-        out(ctx, rows.length ? table(['WORKSPACE', 'APP', 'STATE', 'TITLE'], rows.map(a => [a.workspace_key, a.app, a.state, a.title])) : 'No agent sessions.\n', { data: rows, next_cursor: next });
+        // LAST MESSAGE (0.13.4+): the session's latest message, from an API that reports it.
+        const message = (a) => !a.last_message ? '-' : a.last_message.length > 60 ? `${a.last_message.slice(0, 59)}…` : a.last_message;
+        out(ctx, rows.length ? table(['WORKSPACE', 'APP', 'STATE', 'TITLE', 'LAST MESSAGE'], rows.map(a => [a.workspace_key, a.app, a.state, a.title, message(a)])) : 'No agent sessions.\n', { data: rows, next_cursor: next });
         if (!ctx.json && next)
             ctx.io.stderr.write(`more: shard agents list --cursor ${next}\n`);
         return 0;
@@ -2374,9 +2376,9 @@ function updateLine(u, d) {
         case 'current':
             return `up to date${pkg}: latest ${u.latest ?? '-'}${when}\n`;
         case 'outdated':
-            return `update available${pkg}: ${u.latest} (you have ${u.current}). Update: ${u.upgrade_command ?? '-'}\n`;
+            return `update available${pkg}: ${u.latest} (you have ${u.current}). Update: shard update\n`;
         case 'unsupported':
-            return `no longer supported${pkg}: the API needs ${u.minimum_supported} or later (latest ${u.latest ?? '-'}). Update: ${u.upgrade_command ?? '-'}\n`;
+            return `no longer supported${pkg}: the API needs ${u.minimum_supported} or later (latest ${u.latest ?? '-'}). Update: shard update\n`;
         default:
             return `update status unknown${pkg}${when} (the API could not be asked, or has no release of ${u.package} yet)\n`;
     }

package/dist/filesystem-commands.d.ts

@@ -1,5 +1,7 @@
 import type { AgentFilesystem } from '@shardflux/sdk';
 import type { Handler } from './commands.js';
-/** One line per status: what is in use and what is saving or failed. */
-export declare function filesystemLine(state: AgentFilesystem): string;
+/** One line per status: what is in use and what is saving or failed, its platform base and setup cache. */
+export declare function filesystemLine(state: AgentFilesystem & {
+    cache_scope?: string;
+}): string;
 export declare const FILESYSTEM_HANDLERS: Record<string, Handler>;

package/dist/filesystem-commands.js

@@ -2,14 +2,19 @@ import { waitTimeout } from "./commands.js";
 import { UsageError } from "./errors.js";
 import { projectIdentity, normalizeRemote } from "./project-identity.js";
 import { AGENT_HANDLERS } from "./agent-commands.js";
+import { readSetupProgress } from "./assisted-setup.js";
 import { syncAgentConfig } from "./agent-config-sync.js";
 import { progress } from "./progress.js";
 function remote() {
     const project = projectIdentity('./');
     return { project, repoRemote: project.remote ?? normalizeRemote(`file://${project.folder}`) };
 }
-/** One line per status: what is in use and what is saving or failed. */
+/** One line per status: what is in use and what is saving or failed, its platform base and setup cache. */
 export function filesystemLine(state) {
+    const base = state.platform_base ? `; platform ${state.platform_base.slug}@${state.platform_base.version}${state.rebase_pending ? ', rebase pending' : ''}` : '';
+    return usageLine(state) + base + (state.cache_scope ? `; cache: ${state.cache_scope}` : '');
+}
+function usageLine(state) {
     const current = state.version > 0 ? `version ${state.version}` : '';
     if (state.state === 'building' && state.pending)
         return `${state.level}: saving version ${state.pending.version}${current ? ` (${current} stays in use until it is ready)` : ''}`;
@@ -56,7 +61,7 @@ export const FILESYSTEM_HANDLERS = {
         else if (existing.data.observed_state !== 'running')
             progress(ctx, `Resuming your machine VM (${key})…`);
         const ws = await cloud.workspaces.open({ key, template: state.template ? `${state.template.slug}@${state.template.version}` : 'coding',
-            labels: { shard_layer: 'machine', shard_machine: state.organization_id, repo_path: '/home/user', app: 'claude', agent: 'machine' },
+            labels: { ...existing?.labels, shard_layer: 'machine', shard_machine: state.organization_id, repo_path: '/home/user', app: 'claude', agent: 'machine' },
             wait: { timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal } });
         if (state.version === 0) {
             progress(ctx, 'Syncing your Claude and Codex config into the machine…');
@@ -77,7 +82,13 @@ export const FILESYSTEM_HANDLERS = {
         return output(ctx, await ctx.cloud().machine.rollback({ to: rollbackTo(values.to) }, { signal: ctx.signal }));
     },
     async template(ctx) {
-        return output(ctx, await ctx.cloud().templates.getProject(remote().repoRemote, { signal: ctx.signal }));
+        const { project, repoRemote } = remote();
+        const state = await ctx.cloud().templates.getProject(repoRemote, { signal: ctx.signal });
+        const ws = await ctx.cloud().workspaces.findByKey(`${project.slug}/main`, { signal: ctx.signal });
+        const progress = ws ? await readSetupProgress(ctx, ws.data) : undefined;
+        const attachments = ws ? await ctx.cloud().volumes.listAttached(ws.id) : undefined;
+        const mounted = attachments?.data.some((a) => a.mount_path === '/mnt/shardflux-cache' && a.mounted && a.volume.name === 'shardflux-setup-cache' && a.volume.org_shared);
+        return output(ctx, { ...state, cache_scope: progress?.cache_scope ?? (mounted ? 'account' : 'workspace') });
     },
     async 'template save'(ctx, values) {
         const { project, repoRemote } = remote();

package/dist/handlers.js

@@ -11,5 +11,6 @@ import { TARGET_HANDLERS } from "./agent-target-commands.js";
 import { CENTER_HANDLERS } from "./command-center-actions.js";
 import { AGENT_GIT_HANDLERS } from "./agent-git-commands.js";
 import { MENUBAR_HANDLERS } from "./menubar.js";
+import { UPDATE_HANDLERS } from "./update.js";
 import { FILESYSTEM_HANDLERS } from "./filesystem-commands.js";
-export const HANDLERS = { ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS };
+export const 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.d.ts

@@ -1,4 +1,5 @@
 import type { Io } from './commands.js';
+import type { Runtime } from './update.js';
 import type { Distribution } from './update-check.js';
 /** A sleep that ends early when the signal aborts (so Ctrl-C never waits out a poll interval). */
 export declare function abortableSleep(signal: AbortSignal): (ms: number) => Promise<void>;
@@ -6,6 +7,8 @@ export interface RunOptions {
     signal?: AbortSignal;
     /** The package that runs the CLI, for the version check (default @shardflux/cli at CLI_VERSION). */
     distribution?: Distribution;
+    /** The Node.js binary and script of this `shard` process (main() sets them; `shard update` needs them). */
+    runtime?: Runtime;
 }
 export declare function run(argv: readonly string[], io: Io, opts?: RunOptions): Promise<number>;
 export interface MainOptions {

package/dist/main.js

@@ -17,6 +17,7 @@ import { CLI_VERSION, CENTER_COMMAND, PROJECT_COMMAND, commandHelp, parseCommand
 import { commandCenter } from "./command-center.js";
 import { housekeeping, startupHousekeeping } from "./agent-git-commands.js";
 import { CredentialStore, configDir } from "./credentials.js";
+import { recordInstall } from "./update.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";
@@ -528,6 +529,15 @@ export async function run(argv, io, opts = {}) {
             store,
             input: new Input(io.stdin, io.stderr),
             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();
+            },
             hostname: () => {
                 try {
                     return hostname();
@@ -616,7 +626,7 @@ export async function run(argv, io, opts = {}) {
             },
         };
         // The update check runs next to the command (not for `version`, which reports it itself).
-        if (!updateCheckDisabled(io.env) && !['version', 'ssh-proxy'].includes(parsed.command.path[0])) {
+        if (!updateCheckDisabled(io.env) && !['version', 'update', 'ssh-proxy'].includes(parsed.command.path[0])) {
             try {
                 updates = new UpdateCheck({ dir: store.dir, apiUrl, distribution, fetch: base, userAgent });
                 updates.start();
@@ -684,7 +694,11 @@ export async function main(opts = {}) {
         controller.abort(new Error('interrupted'));
     });
     const flush = (stream) => new Promise((resolve) => stream.write('', () => resolve()));
-    const code = await run(process.argv.slice(2), { stdout: process.stdout, stderr: process.stderr, stdin: process.stdin, env: process.env }, { signal: controller.signal, ...(opts.distribution ? { distribution: opts.distribution } : {}) });
+    const runtime = { node: process.execPath, script: process.argv[1] ?? '' };
+    // The menu bar's update button runs this shard; it finds it here (macOS only, written when it changes).
+    if (process.platform === 'darwin' && runtime.script)
+        recordInstall(configDir(process.env), runtime, opts.distribution ?? CLI_DISTRIBUTION);
+    const code = await run(process.argv.slice(2), { stdout: process.stdout, stderr: process.stderr, stdin: process.stdin, env: process.env }, { signal: controller.signal, runtime, ...(opts.distribution ? { distribution: opts.distribution } : {}) });
     await Promise.all([flush(process.stdout), flush(process.stderr)]);
     process.exit(code);
 }

package/dist/menubar.d.ts

@@ -21,6 +21,9 @@ export declare class MenubarManager {
         packageApp?: () => string;
         signal?: AbortSignal;
     });
+    get platform(): NodeJS.Platform;
+    /** The version of the app this CLI's npm package carries (what `start` installs). */
+    packagedVersion(): Promise<string>;
     status(): Promise<MenubarStatus>;
     stop(): Promise<MenubarStatus>;
     login(value: 'on' | 'off'): Promise<MenubarStatus>;

package/dist/menubar.js

@@ -49,8 +49,11 @@ export class MenubarManager {
             }
         });
     }
+    get platform() { return this.#platform; }
     #requireMac() { if (this.#platform !== 'darwin')
         throw new UsageError('shard menubar requires macOS 14 or later.'); }
+    /** The version of the app this CLI's npm package carries (what `start` installs). */
+    async packagedVersion() { this.#requireMac(); return this.#version(this.#packageApp()); }
     async #version(app) {
         const file = join(app, 'Contents', 'Info.plist');
         const id = (await this.#run('/usr/bin/plutil', ['-extract', 'CFBundleIdentifier', 'raw', '-o', '-', file])).trim();
@@ -158,7 +161,8 @@ export async function ensureMenubar(dir, apiUrl, manager = new MenubarManager(),
         return undefined;
     try {
         const status = await manager.status();
-        if (status.running)
+        // 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))
             return undefined;
         const started = await manager.start(dir, apiUrl);
         if (!started.running)

package/dist/setup-cache.d.ts

@@ -0,0 +1,5 @@
+import type { Workspace } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+export declare const SETUP_CACHE_PATH = "/mnt/shardflux-cache";
+/** Uses ordinary fenced shared-volume operations, after the managed PTY starts. */
+export declare function prepareSetupCache(ctx: Ctx, workspace: Workspace): Promise<void>;

package/dist/setup-cache.js

@@ -0,0 +1,11 @@
+const name = 'shardflux-setup-cache';
+export const SETUP_CACHE_PATH = '/mnt/shardflux-cache';
+/** Uses ordinary fenced shared-volume operations, after the managed PTY starts. */
+export async function prepareSetupCache(ctx, workspace) {
+    const cloud = ctx.cloud();
+    const wait = { timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal };
+    const { volume } = await cloud.volumes.open({ name, projectId: workspace.data.project_id, wait });
+    if (volume.state !== 'available' || !volume.org_shared || volume.quota_gib !== 1)
+        throw new Error('account setup cache is not available');
+    await cloud.volumes.attach(workspace.id, { volumeId: volume.id, mountPath: SETUP_CACHE_PATH, wait });
+}

package/dist/update-check.d.ts

@@ -59,6 +59,7 @@ export declare class UpdateCheck {
         checkedAt: string | null;
     } | null>;
 }
-/** The one-line notice for stderr, or null when there is nothing to say. */
+/** The one-line notice for stderr, or null when there is nothing to say. It names `shard update` (0.13.5+), which
+ *  updates with the package manager that installed shard, rather than the catalog's npm command. */
 export declare function noticeOf(s: ClientVersionStatus | undefined | null): string | null;
 export {};

package/dist/update-check.js

@@ -120,9 +120,10 @@ export class UpdateCheck {
         }
     }
 }
-/** The one-line notice for stderr, or null when there is nothing to say. */
+/** The one-line notice for stderr, or null when there is nothing to say. It names `shard update` (0.13.5+), which
+ *  updates with the package manager that installed shard, rather than the catalog's npm command. */
 export function noticeOf(s) {
     if (!s || (s.status !== 'outdated' && s.status !== 'unsupported') || !s.message)
         return null;
-    return `${s.message}\n`;
+    return `${s.message.replace(/ Update: .*$/, ' Update: shard update')}\n`;
 }

package/dist/update.d.ts

@@ -0,0 +1,61 @@
+import type { ClientVersionStatusKind } from '@shardflux/sdk';
+import type { Ctx, Handler } from './commands.js';
+import { MenubarManager } from './menubar.js';
+export declare const INSTALL_FILE = "install.json";
+export declare const LAST_UPDATE_FILE = "last-update.json";
+/** How this `shard` process runs: the Node.js binary and the script it was started with. */
+export interface Runtime {
+    node: string;
+    script: string;
+}
+export type Manager = 'npm' | 'pnpm' | 'bun' | 'volta' | 'npx' | 'unmanaged';
+export interface Install {
+    manager: Manager;
+    /** The installed package directory of the distribution, when found. */
+    packageDir: string | null;
+    /** The node_modules directory that holds it (the global root for a global install). */
+    root: string | null;
+    /** npm's global prefix (`<prefix>/lib/node_modules` is the root). */
+    prefix: string | null;
+}
+export interface Component {
+    package: string;
+    label: string;
+    current: string;
+    latest: string | null;
+    status: ClientVersionStatusKind;
+}
+/** Finds the package directory of `pkg` above `script` and how it was installed. */
+export declare function detectInstall(script: string, pkg: string, platform?: NodeJS.Platform): Install;
+/** The packages one install updates: the distribution, plus `@shardflux/mcp` when it is installed next to it. */
+export declare function installSpecs(install: Install, pkg: string): string[];
+/** The install command as argv (npm keeps the prefix it was installed in), or null when shard cannot run it. */
+export declare function installArgv(install: Install, specs: string[], npm?: string): string[] | null;
+/** The command a person types for the same update. */
+export declare function displayCommand(install: Install, specs: string[]): string;
+/** Every local piece and its status against the catalog. */
+export declare function components(ctx: Ctx, install: Install, catalog: unknown, menubar?: MenubarManager): Promise<Component[]>;
+/** One line per change: `shard 0.13.4 → 0.13.5 · menu bar 0.1.1 → 0.1.2`. */
+export declare function changesText(list: {
+    label: string;
+    from: string;
+    to: string | null;
+}[]): string;
+export interface Exec {
+    code: number;
+    output: string;
+}
+export type Runner = (argv: string[], env: Record<string, string | undefined>, signal: AbortSignal) => Promise<Exec>;
+/** Runs argv without a shell, keeping the last 64 KiB of output; never throws for a non-zero exit. */
+export declare const runProcess: Runner;
+export interface UpdateDeps {
+    run?: Runner;
+    menubar?: MenubarManager;
+}
+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: string;
+    version: string;
+}): void;
+export declare const UPDATE_HANDLERS: Record<string, Handler>;

package/dist/update.js

@@ -0,0 +1,298 @@
+/**
+ * `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
+ * 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.
+ *
+ * The menu bar app runs the same command: it finds `shard` through install.json (written by each `shard` run on
+ * macOS) and shows the outcome from last-update.json, also when the update replaced the app that started it.
+ */
+import { spawn } from 'node:child_process';
+import { closeSync, existsSync, openSync, readFileSync, realpathSync, rmSync, writeSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, sep } from 'node:path';
+import { clientVersionStatus, SDK_VERSION } from '@shardflux/sdk';
+import { CLI_VERSION } from "./args.js";
+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";
+export const INSTALL_FILE = 'install.json';
+export const LAST_UPDATE_FILE = 'last-update.json';
+const LOCK_FILE = 'update.lock';
+const MCP = '@shardflux/mcp';
+const MENUBAR = '@shardflux/menubar-darwin';
+/** Finds the package directory of `pkg` above `script` and how it was installed. */
+export function detectInstall(script, pkg, platform = process.platform) {
+    let real = script;
+    try {
+        real = realpathSync(script);
+    }
+    catch { /* a missing script keeps its path */ }
+    let packageDir = null;
+    for (let dir = dirname(real); dir !== dirname(dir); dir = dirname(dir)) {
+        try {
+            if (JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).name === pkg) {
+                packageDir = dir;
+                break;
+            }
+        }
+        catch { /* no package.json here */ }
+    }
+    const none = { manager: 'unmanaged', packageDir, root: null, prefix: null };
+    if (!packageDir)
+        return none;
+    const root = pkg.startsWith('@') ? dirname(dirname(packageDir)) : dirname(packageDir);
+    if (basename(root) !== 'node_modules')
+        return none;
+    const has = (part) => root.split(sep).join('/').includes(part);
+    if (has('/_npx/'))
+        return { manager: 'npx', packageDir, root, prefix: null };
+    if (has('/.volta/'))
+        return { manager: 'volta', packageDir, root, prefix: null };
+    if (has('/.bun/install/global/'))
+        return { manager: 'bun', packageDir, root, prefix: null };
+    if (has('/pnpm/global/') || has('/.pnpm/'))
+        return { manager: 'pnpm', packageDir, root, prefix: null };
+    if (basename(dirname(root)) === 'lib')
+        return { manager: 'npm', packageDir, root, prefix: dirname(dirname(root)) };
+    if (platform === 'win32' && basename(dirname(root)) === 'npm')
+        return { manager: 'npm', packageDir, root, prefix: dirname(root) };
+    return none;
+}
+function versionAt(dir) {
+    try {
+        const v = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).version;
+        return typeof v === 'string' ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The packages one install updates: the distribution, plus `@shardflux/mcp` when it is installed next to it. */
+export function installSpecs(install, pkg) {
+    const specs = [`${pkg}@latest`];
+    if (install.root && versionAt(join(install.root, MCP)))
+        specs.push(`${MCP}@latest`);
+    return specs;
+}
+/** The install command as argv (npm keeps the prefix it was installed in), or null when shard cannot run it. */
+export function installArgv(install, specs, npm = 'npm') {
+    switch (install.manager) {
+        case 'npm': return [npm, 'install', '--global', ...(install.prefix ? ['--prefix', install.prefix] : []), ...specs, '--no-fund', '--no-audit'];
+        case 'pnpm': return ['pnpm', 'add', '--global', ...specs];
+        case 'bun': return ['bun', 'add', '--global', ...specs];
+        case 'volta': return ['volta', 'install', ...specs];
+        default: return null;
+    }
+}
+/** The command a person types for the same update. */
+export function displayCommand(install, specs) {
+    switch (install.manager) {
+        case 'pnpm': return `pnpm add -g ${specs.join(' ')}`;
+        case 'bun': return `bun add -g ${specs.join(' ')}`;
+        case 'volta': return `volta install ${specs.join(' ')}`;
+        case 'npx': return `npx ${specs[0]}`;
+        default: return `npm install -g ${specs.join(' ')}`;
+    }
+}
+const LABELS = { shardflux: 'shardflux', '@shardflux/cli': 'shard', '@shardflux/sdk': 'SDK', [MENUBAR]: 'menu bar', [MCP]: 'MCP server' };
+/** Every local piece and its status against the catalog. */
+export async function components(ctx, install, catalog, menubar = menubarManager(ctx)) {
+    const local = [[ctx.distribution.package, ctx.distribution.version]];
+    if (ctx.distribution.package !== '@shardflux/cli')
+        local.push(['@shardflux/cli', CLI_VERSION]);
+    local.push(['@shardflux/sdk', SDK_VERSION]);
+    if (menubar.platform === 'darwin') {
+        const status = await menubar.status().catch(() => null);
+        if (status?.installed && status.version)
+            local.push([MENUBAR, status.version]);
+    }
+    if (install.root)
+        local.push([MCP, versionAt(join(install.root, MCP))]);
+    return local.filter((entry) => entry[1] !== null).map(([pkg, version]) => {
+        const s = clientVersionStatus(catalog, { package: pkg, version });
+        return { package: pkg, label: LABELS[pkg] ?? pkg, current: version, latest: s.latest, status: s.status };
+    });
+}
+const outdated = (c) => c.status === 'outdated' || c.status === 'unsupported';
+function menubarManager(ctx) {
+    return new MenubarManager({ home: ctx.io.env.HOME || homedir(), signal: ctx.signal });
+}
+/** One line per change: `shard 0.13.4 → 0.13.5 · menu bar 0.1.1 → 0.1.2`. */
+export function changesText(list) {
+    return list.map(c => `${c.label} ${c.from} → ${c.to ?? '?'}`).join(' · ');
+}
+/** Runs argv without a shell, keeping the last 64 KiB of output; never throws for a non-zero exit. */
+export const runProcess = (argv, env, signal) => new Promise((resolve, reject) => {
+    const child = spawn(argv[0], argv.slice(1), { env: env, stdio: ['ignore', 'pipe', 'pipe'], signal });
+    let output = '';
+    const keep = (chunk) => { output = (output + chunk.toString('utf8')).slice(-65536); };
+    child.stdout.on('data', keep);
+    child.stderr.on('data', keep);
+    child.on('error', reject);
+    child.on('close', code => resolve({ code: code ?? 1, output }));
+});
+function writeLastUpdate(dir, doc) {
+    try {
+        writePrivateFile(dir, join(dir, LAST_UPDATE_FILE), `${JSON.stringify({ version: 1, finished_at: new Date().toISOString(), ...doc }, null, 2)}\n`);
+    }
+    catch { /* the outcome is also printed; the menu bar then shows no result */ }
+}
+/** One update at a time per config directory; a lock left by a process that is gone is taken over. */
+function lock(dir) {
+    const file = join(dir, LOCK_FILE);
+    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')
+                throw error;
+            const pid = Number(readFileSync(file, 'utf8'));
+            let alive = false;
+            try {
+                if (Number.isInteger(pid) && pid > 0) {
+                    process.kill(pid, 0);
+                    alive = true;
+                }
+            }
+            catch { /* gone */ }
+            if (alive)
+                throw new CodedError('update_in_progress', 'A Shardflux update is already running.', 'wait for it to finish, then run shard update --check');
+            rmSync(file, { force: true });
+        }
+    }
+    throw new CodedError('update_in_progress', 'A Shardflux update is already running.', 'wait for it to finish, then run shard update --check');
+}
+/** npm next to the running Node.js (the same installation), else npm on PATH. */
+function npmFor(node) {
+    const sibling = join(dirname(node), process.platform === 'win32' ? 'npm.cmd' : 'npm');
+    return existsSync(sibling) ? sibling : 'npm';
+}
+export async function update(ctx, values, deps = {}) {
+    const run = deps.run ?? runProcess;
+    const menubar = deps.menubar ?? menubarManager(ctx);
+    const runtime = ctx.runtime;
+    const install = runtime ? detectInstall(runtime.script, ctx.distribution.package) : { manager: 'unmanaged', packageDir: null, root: null, prefix: null };
+    const catalog = await ctx.clientVersions();
+    const list = await components(ctx, install, catalog, menubar);
+    const specs = installSpecs(install, ctx.distribution.package);
+    const command = displayCommand(install, specs);
+    const pending = list.filter(outdated);
+    const view = { update_available: pending.length > 0, components: list, install: { manager: install.manager, command } };
+    const versions = list.map(c => `${c.label} ${c.current}`).join(' · ');
+    if (values.check === true) {
+        ctx.io.stdout.write(ctx.json ? json(view) : pending.length
+            ? `Update available: ${changesText(pending.map(c => ({ label: c.label, from: c.current, to: c.latest })))}\nRun: shard update\n`
+            : `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.
+        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`);
+        return 0;
+    }
+    const argv = installArgv(install, specs, runtime ? npmFor(runtime.node) : 'npm');
+    if (!argv || !runtime) {
+        const where = install.packageDir ?? runtime?.script ?? 'this process';
+        const message = install.manager === 'npx'
+            ? 'npx runs the latest version the next time you start it.'
+            : `shard update does not manage the install at ${where}.`;
+        writeLastUpdate(ctx.store.dir, { status: 'failed', changes: [], message, command });
+        throw new CodedError('update_unmanaged', message, `run: ${command}`);
+    }
+    const unlock = lock(ctx.store.dir);
+    try {
+        if (!ctx.json)
+            ctx.io.stderr.write(`Updating ${changesText(pending.map(c => ({ label: c.label, from: c.current, to: c.latest })))} with ${install.manager}…\n`);
+        const env = { ...process.env, ...ctx.io.env, PATH: [dirname(runtime.node), ctx.io.env.PATH ?? process.env.PATH ?? ''].join(process.platform === 'win32' ? ';' : ':') };
+        const result = await run(argv, env, ctx.signal);
+        if (result.code !== 0) {
+            const denied = /\bEACCES\b|\bEPERM\b/.test(result.output);
+            const fix = denied ? `sudo ${command}` : command;
+            const message = denied
+                ? `${install.manager} cannot write to ${install.prefix ?? install.root}.`
+                : `${install.manager} failed: ${result.output.trim().split('\n').slice(-3).join(' ').slice(0, 400)}`;
+            writeLastUpdate(ctx.store.dir, { status: 'failed', changes: [], message, command: fix });
+            throw new CodedError(denied ? 'update_permission_denied' : 'update_failed', message, `run: ${fix}`);
+        }
+        // The new shard reports what is installed now.
+        const after = await run([runtime.node, runtime.script, 'version', '--json'], { ...env, SHARDFLUX_NO_UPDATE_CHECK: '1' }, ctx.signal);
+        let now = {};
+        try {
+            now = JSON.parse(after.output.slice(after.output.indexOf('{')));
+        }
+        catch { /* reported as unknown below */ }
+        const installed = {
+            [ctx.distribution.package]: install.packageDir ? versionAt(install.packageDir) : null,
+            '@shardflux/cli': now.cli ?? null, '@shardflux/sdk': now.sdk ?? null,
+            [MCP]: install.root ? versionAt(join(install.root, MCP)) : null,
+        };
+        const restart = await refreshMenubar(ctx, menubar, runtime, run, env);
+        if (restart.version)
+            installed[MENUBAR] = restart.version;
+        const changes = list.filter(c => (installed[c.package] ?? c.current) !== c.current)
+            .map(c => ({ package: c.package, label: c.label, from: c.current, to: installed[c.package] ?? null }));
+        const message = changes.length ? `Updated ${changesText(changes)}` : 'Shardflux is up to date';
+        writeLastUpdate(ctx.store.dir, { status: 'ok', changes, message, command });
+        ctx.io.stdout.write(ctx.json ? json({ ...view, updated: true, changes, menubar: restart.status }) : `${message}.\n`);
+        return 0;
+    }
+    finally {
+        unlock();
+    }
+}
+/**
+ * Restarts the menu bar on the app its npm package carries now, when that is newer than the installed one and the
+ * person has not turned the menu bar off. With `runtime`, the freshly installed shard does it (this process still
+ * runs the code from before the update).
+ */
+async function refreshMenubar(ctx, menubar, runtime, run, env) {
+    if (menubar.platform !== 'darwin')
+        return { status: 'off' };
+    if (new AgentStateStore(ctx.store.dir).read().menubar_stopped === true)
+        return { status: 'off' };
+    const before = await menubar.status().catch(() => null);
+    if (!before?.installed)
+        return { status: 'off' };
+    if (runtime && run && env) {
+        const r = await run([runtime.node, runtime.script, '--api-url', ctx.apiUrl, 'menubar', 'start', '--json'], { ...env, SHARDFLUX_NO_UPDATE_CHECK: '1', SHARDFLUX_CONFIG_DIR: ctx.store.dir }, ctx.signal);
+        if (r.code !== 0)
+            return { status: 'failed' };
+    }
+    else {
+        const packaged = await menubar.packagedVersion().catch(() => null);
+        if (!packaged || !before.version || compareBundleVersions(before.version, packaged) >= 0)
+            return { status: 'current' };
+        await menubar.start(ctx.store.dir, ctx.apiUrl);
+    }
+    const after = await menubar.status().catch(() => null);
+    return after?.version && after.version !== before.version ? { status: 'restarted', version: after.version } : { status: 'current' };
+}
+/** Records where `shard` runs, for the menu bar's update button. Written on macOS, only when it changed. */
+export function recordInstall(dir, runtime, distribution) {
+    let script = runtime.script;
+    try {
+        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 };
+    const text = `${JSON.stringify(doc, null, 2)}\n`;
+    try {
+        if (readFileSync(join(dir, INSTALL_FILE), 'utf8') === text)
+            return;
+    }
+    catch { /* first run */ }
+    try {
+        writePrivateFile(dir, join(dir, INSTALL_FILE), text);
+    }
+    catch { /* the menu bar then offers the terminal instead */ }
+}
+export const UPDATE_HANDLERS = { update: (ctx, values) => update(ctx, values) };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.13.3",
+  "version": "0.13.5",
   "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",
@@ -47,7 +47,7 @@
     "smol-toml": "1.9.0",
     "snappyjs": "0.7.0",
     "yaml": "2.9.1",
-    "@shardflux/sdk": "^0.18.1"
+    "@shardflux/sdk": "^0.18.3"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
@@ -58,7 +58,7 @@
     "typescript-eslint": "8.70.1"
   },
   "optionalDependencies": {
-    "@shardflux/menubar-darwin": "^0.1.1"
+    "@shardflux/menubar-darwin": "^0.1.2"
   },
   "scripts": {
     "build": "node scripts/build.mjs",