@shardflux/cli 0.15.1 → 0.16.0

package/dist/thread-on-computer.d.ts

@@ -0,0 +1,35 @@
+import type { Ctx, Handler } from './commands.js';
+import type { Values } from './args.js';
+import type { Conversation, Harness } from './conversations.js';
+/** A conversation still bound to its computer: not done, archived or ended. */
+export declare const activeConversation: (c: Pick<Conversation, "state" | "ended_at">) => boolean;
+export interface ComputerThread {
+    id: string;
+    key: string;
+    title: string;
+    harness: Harness;
+    state: Conversation['state'];
+    route: Conversation['route'];
+    role: string;
+    join_mode: string | null;
+    branch: string;
+}
+export interface Computer {
+    workspace_id: string;
+    workspace_key: string;
+    state: 'running' | 'suspended';
+    last_activity_at: string | null;
+    conversations: ComputerThread[];
+}
+/** The project's conversations: its repository's, or (for a folder without a remote) the ones started from it. */
+export declare function projectConversations(ctx: Pick<Ctx, 'store' | 'apiUrl'>, all: Conversation[], folder: string): Conversation[];
+/** Computers a new thread can start on: each live VM (running or parked, never deleted) of the project's active conversations. */
+export declare function listComputers(ctx: Ctx, folder: string): Promise<Computer[]>;
+/**
+ * The conversation whose computer `--on` names: a conversation id, key or name, or the VM's workspace key or id (then
+ * the VM's own conversation, else its oldest live thread).
+ */
+export declare function resolveOn(ctx: Ctx, ref: string, folder: string): Promise<Conversation>;
+/** Starts the thread on `--on`'s computer and opens it like a new conversation of that app. */
+export declare function startThreadOn(ctx: Ctx, values: Values, path: string, explicitApp?: string): Promise<number>;
+export declare const THREAD_HANDLERS: Record<string, Handler>;

package/dist/thread-on-computer.js

@@ -0,0 +1,200 @@
+// A new Claude or Codex thread on an existing conversation's computer (0.16.0+): `shard agents new --on <ref>`,
+// `shard ./ --on <ref>` and `shard agents computers`. The thread joins that VM as a worker (its own branch and
+// worktree, sharing the VM's packages, caches, services, ports and files) or, with --review, as a read-only Claude
+// reviewer. Codex threads are genuine Codex Cloud threads. docs/progress/thread-on-existing-vm.md.
+import { randomUUID } from 'node:crypto';
+import { ShardfluxApiError } from '@shardflux/sdk';
+import { out, str } from "./commands.js";
+import { UsageError } from "./errors.js";
+import { table } from "./format.js";
+import { AgentStateStore } from "./agent-state.js";
+import { normalizeRemote, projectIdentity } from "./project-identity.js";
+import { progress } from "./progress.js";
+import { conversationClient } from "./conversation-commands.js";
+import { conversationName, conversationWorkspace, getConversation, listConversations, localConversations, rememberConversation, validateConversation, waitThreadReady } from "./conversations.js";
+import { syncAgentCredentials } from "./agent-credentials.js";
+import { cloudClaudeLogin, loginClaudeInWorkspace, requireClaudeTerminal } from "./claude-cloud-login.js";
+import { promptWithImages, readInitialImages, readInitialPrompt, uploadInitialImages } from "./initial-prompt.js";
+import { recordSeedSnapshot } from "./files-mirror.js";
+import { ensureCodexCloud, printCloudThread, submitCloudInitialPrompt } from "./codex-cloud.js";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SHA = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/;
+/** A conversation still bound to its computer: not done, archived or ended. */
+export const activeConversation = (c) => c.state !== 'done' && c.state !== 'archived' && !c.ended_at;
+/** The project's conversations: its repository's, or (for a folder without a remote) the ones started from it. */
+export function projectConversations(ctx, all, folder) {
+    const project = projectIdentity(folder), remote = project.remote ?? `file://${project.folder}`, records = localConversations(ctx);
+    const same = (r) => { try {
+        return normalizeRemote(r, project.folder) === remote;
+    }
+    catch {
+        return false;
+    } };
+    return all.filter(c => c.repo_remote ? same(c.repo_remote) : records[c.id]?.folder === project.folder);
+}
+/** The VM's own conversation first (its label), then the oldest thread on it. */
+function host(bound, label) {
+    return bound.find(c => c.id === label) ?? [...bound].sort((a, b) => a.created_at.localeCompare(b.created_at))[0];
+}
+const thread = (c) => ({ id: c.id, key: c.key, title: c.title, harness: c.harness, state: c.state, route: c.route,
+    role: c.role ?? 'main', join_mode: c.join_mode ?? null, branch: c.branch });
+/** Computers a new thread can start on: each live VM (running or parked, never deleted) of the project's active conversations. */
+export async function listComputers(ctx, folder) {
+    const client = conversationClient(ctx);
+    const groups = new Map();
+    for (const c of projectConversations(ctx, await listConversations(ctx), folder).filter(activeConversation))
+        groups.set(c.workspace_id, [...groups.get(c.workspace_id) ?? [], c]);
+    const computers = await Promise.all([...groups].map(async ([id, bound]) => {
+        let ws;
+        try {
+            ws = await client.workspaces.get(id);
+        }
+        catch (error) {
+            if (error instanceof ShardfluxApiError && error.status === 404)
+                return null;
+            throw error;
+        }
+        const observed = String(ws.data.observed_state ?? '');
+        if (ws.data.deleted_at || ['failed', 'deleted', 'deleting'].includes(observed))
+            return null;
+        const own = host(bound, ws.labels.shard_conversation);
+        const ordered = [own, ...bound.filter(c => c !== own).sort((a, b) => a.created_at.localeCompare(b.created_at))];
+        const last = bound.map(c => c.last_activity_at ?? c.created_at).sort().at(-1) ?? null;
+        return { workspace_id: ws.id, workspace_key: ws.key, state: observed === 'suspended' ? 'suspended' : 'running', last_activity_at: last, conversations: ordered.map(thread) };
+    }));
+    return computers.filter((c) => c !== null).sort((a, b) => (b.last_activity_at ?? '').localeCompare(a.last_activity_at ?? ''));
+}
+/**
+ * The conversation whose computer `--on` names: a conversation id, key or name, or the VM's workspace key or id (then
+ * the VM's own conversation, else its oldest live thread).
+ */
+export async function resolveOn(ctx, ref, folder) {
+    if (!ref.trim())
+        throw new UsageError('--on needs a conversation or computer; list them with shard agents computers.');
+    let target;
+    if (/^conv_[a-z0-9]{26}$/.test(ref))
+        target = await getConversation(ctx, ref);
+    else {
+        const all = await listConversations(ctx);
+        const keyed = all.filter(c => c.key === ref);
+        if (keyed.length === 1)
+            target = keyed[0];
+        else if (UUID.test(ref) || ref.includes('/')) {
+            const client = conversationClient(ctx);
+            let ws = null;
+            try {
+                ws = UUID.test(ref) ? await client.workspaces.get(ref) : await client.workspaces.findByKey(ref, { includeDeleted: false, signal: ctx.signal });
+            }
+            catch (error) {
+                if (!(error instanceof ShardfluxApiError && error.status === 404))
+                    throw error;
+            }
+            if (ws)
+                target = host(all.filter(c => c.workspace_id === ws.id && activeConversation(c)), ws.labels.shard_conversation);
+        }
+        else {
+            const named = projectConversations(ctx, all, folder).filter(c => conversationName(c) === ref);
+            const live = named.filter(activeConversation);
+            if ((live.length || named.length) > 1)
+                throw new UsageError(`Several conversations are named ${ref}; use its key or id (shard agents computers lists them).`);
+            target = live[0] ?? named[0];
+        }
+    }
+    if (!target)
+        throw new UsageError(`No conversation or computer "${ref}" in this project. List them with shard agents computers.`);
+    if (!activeConversation(target))
+        throw new UsageError(`${target.title || target.key} has ended, so its computer is not available. Start the thread on a new computer, or continue that conversation with shard agents open ${target.id}.`);
+    return target;
+}
+/** `git rev-parse HEAD` of the target's worktree in its VM: the new thread starts from its committed work. */
+async function targetHead(ws, target, signal) {
+    const head = await ws.cell().exec.run(['git', '-C', target.worktree_path, 'rev-parse', 'HEAD'], { timeoutMs: 30_000, maxOutputBytes: 4096, signal });
+    const sha = head.stdout.trim();
+    return head.exitCode === 0 && SHA.test(sha) ? sha : target.base_commit;
+}
+/** Records a thread that could never be admitted as discarded, so it never holds the shared computer. */
+async function abandon(ctx, c) {
+    try {
+        await conversationClient(ctx).conversations.land(c.id, 'discard', { idempotencyKey: `abandon-${c.id}`, signal: ctx.signal });
+    }
+    catch { /* the API refuses it again on the next try */ }
+}
+/** Starts the thread on `--on`'s computer and opens it like a new conversation of that app. */
+export async function startThreadOn(ctx, values, path, explicitApp) {
+    const ref = str(values.on) ?? '';
+    for (const flag of ['like', 'in', 'resume', 'new'])
+        if (values[flag] !== undefined && !(flag === 'in' && ['terminal', 'codex-app'].includes(String(values.in))))
+            throw new UsageError(`--${flag} cannot be combined with --on.`);
+    if (values.computer === true)
+        throw new UsageError('--computer is a setting of a new computer; a thread with --on uses its computer as it is.');
+    const text = await readInitialPrompt(ctx, values);
+    const images = await readInitialImages(ctx, values, text);
+    const initialPrompt = text === undefined ? undefined : promptWithImages(text, images);
+    const project = projectIdentity(path), projectKey = project.remote ?? project.folder, store = new AgentStateStore(ctx.store.dir);
+    const chosen = explicitApp ?? str(values.app);
+    if (chosen !== undefined && chosen !== 'claude' && chosen !== 'codex')
+        throw new UsageError('--app must be claude or codex');
+    const app = chosen ?? store.app(projectKey);
+    const review = values.review === true;
+    if (review && app === 'codex')
+        throw new UsageError('--review starts a read-only Claude reviewer. A Codex thread on a computer works on its own branch; omit --review.');
+    const name = str(values.name);
+    if (name !== undefined && !/^[a-z0-9][a-z0-9-]{0,47}$/.test(name))
+        throw new UsageError('--name must match ^[a-z0-9][a-z0-9-]{0,47}$');
+    const target = await resolveOn(ctx, ref, path);
+    let signedIn = true;
+    if (app === 'claude') {
+        await syncAgentCredentials(ctx.cloud(), { home: ctx.io.env.HOME, redact: value => ctx.addSecret(value) });
+        signedIn = Boolean(await cloudClaudeLogin(ctx));
+        if (!signedIn)
+            requireClaudeTerminal(ctx);
+        if (!ctx.json && values.detach !== true && (!ctx.io.stdin.isTTY || !ctx.io.stdin.setRawMode))
+            throw new UsageError('agent terminal requires a TTY; add --json to start it detached');
+    }
+    else
+        await ensureCodexCloud(ctx);
+    progress(ctx, `Starting ${app === 'claude' ? 'Claude' : 'Codex'} on the computer with ${target.title || target.key}…`);
+    const ws = await conversationWorkspace(ctx, target);
+    const commit = await targetHead(ws, target, ctx.signal);
+    const baseBranch = target.base_branch ?? undefined;
+    await uploadInitialImages(ws.cell(), images, ctx.signal);
+    const response = await conversationClient(ctx).conversations.create({ projectId: target.project_id, repoRemote: target.repo_remote ?? ws.labels.repo_remote ?? '',
+        harness: app, route: app === 'codex' ? 'codex-cloud' : 'terminal', mode: 'join', parentId: target.id, ...(review ? { joinMode: 'reviewer' } : {}),
+        base: { commit, ...(baseBranch ? { branch: baseBranch } : {}) }, ...(name ? { name } : {}) }, { idempotencyKey: randomUUID(), signal: ctx.signal });
+    let c = validateConversation({ ...response.conversation, restore: response.restore });
+    rememberConversation(ctx, c, project.folder, false, baseBranch);
+    store.save(projectKey, app);
+    if (app === 'codex') {
+        try {
+            await ctx.cloud().codex.admit(c.id, { idempotencyKey: `codex-${c.id}`, signal: ctx.signal });
+        }
+        catch (error) {
+            await abandon(ctx, c);
+            throw error;
+        }
+        const task = await ctx.cloud().codex.waitTask(c.id, { timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
+        // The worktree exists once admission prepared it: record where the thread started for the files shelf.
+        await recordSeedSnapshot(ws, c, ctx.signal);
+        if (initialPrompt !== undefined)
+            await submitCloudInitialPrompt(ctx, c, initialPrompt, ws.key);
+        await printCloudThread(ctx, c, task, initialPrompt !== undefined);
+        return 0;
+    }
+    // The computer's guest prepares the worktree and starts the harness; the terminal attaches to that session.
+    c = await waitThreadReady(ctx, c);
+    if (!review)
+        await recordSeedSnapshot(ws, c, ctx.signal);
+    if (!signedIn)
+        await loginClaudeInWorkspace(ctx, ws);
+    const { conversationTerminal } = await import("./conversation-terminal.js");
+    return conversationTerminal(ctx, ws, c, projectKey, { ...values, ...(initialPrompt === undefined ? {} : { initialPrompt }) });
+}
+export const THREAD_HANDLERS = {
+    async 'agents computers'(ctx, values) {
+        const computers = await listComputers(ctx, str(values.path) ?? './');
+        const label = (t) => `${t.title || t.key} (${t.harness}, ${t.state.replace('_', ' ')})`;
+        out(ctx, computers.length ? table(['COMPUTER', 'STATE', 'THREADS'], computers.map(c => [c.workspace_key, c.state, c.conversations.map(label).join('; ')]))
+            : 'No computers to start a thread on. Start a conversation with shard ./ first.\n', { computers });
+        return 0;
+    },
+};

package/dist/update-check.d.ts

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

package/dist/update-check.js

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

package/dist/update.d.ts

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

package/dist/update.js

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

package/dist/wait-status.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Where a wait stands (0.16.0+): while a command waits on an operation whose start is queued for capacity, or a call
+ * waits for room (the workspace's host making room to wake it, or a free working slot of the plan), one line on stderr
+ * says so: the queue position, what the pool is doing (a new host starting, when it is expected) and until when the
+ * start holds its place. A line is printed only when it changes; dim on a terminal, plain when piped; never with
+ * --json, where stdout stays one document and stderr is left to the error.
+ */
+import type { ProgressEvent, ProgressListener, RetryRecord } from '@shardflux/sdk';
+import type { Writer } from './commands.js';
+/** `2026-10-09T21:40:12Z` as `21:40Z` (UTC); the input when it is not a timestamp. */
+export declare function clockZ(iso: string): string;
+/** A queued start in words: `queued for capacity (position 3): a new host is starting, ready by 21:40Z; it holds its place until 21:51Z`. */
+export declare function queueLine(e: Pick<Extract<ProgressEvent, {
+    type: 'phase';
+}>, 'queuePosition' | 'scaleOut' | 'expectedReadyBy' | 'deadlineAt'>): string;
+/** A call waiting to be admitted, in words. */
+export declare function admissionLine(r: Pick<RetryRecord, 'reason' | 'queuePosition'>): string;
+/**
+ * The client listener that prints where a wait stands. Silent with `json`. A phase other than capacity_pending ends
+ * the queue, so a later queue prints again.
+ */
+export declare function waitStatusListener(stderr: Writer, json: boolean): ProgressListener;

package/dist/wait-status.js

@@ -0,0 +1,59 @@
+/** `2026-10-09T21:40:12Z` as `21:40Z` (UTC); the input when it is not a timestamp. */
+export function clockZ(iso) {
+    const t = Date.parse(iso);
+    return Number.isFinite(t) ? `${new Date(t).toISOString().slice(11, 16)}Z` : iso;
+}
+/** A queued start in words: `queued for capacity (position 3): a new host is starting, ready by 21:40Z; it holds its place until 21:51Z`. */
+export function queueLine(e) {
+    const position = e.queuePosition ? ` (position ${e.queuePosition})` : '';
+    const pool = e.scaleOut === 'requested'
+        ? `: a new host is starting${e.expectedReadyBy ? `, ready by ${clockZ(e.expectedReadyBy)}` : ''}`
+        : e.scaleOut === 'clamped'
+            ? ': it starts as soon as a host has room'
+            : '';
+    const until = e.deadlineAt ? `; it holds its place until ${clockZ(e.deadlineAt)}` : '';
+    return `queued for capacity${position}${pool}${until}`;
+}
+/** A call waiting to be admitted, in words. */
+export function admissionLine(r) {
+    const position = r.queuePosition ? ` (position ${r.queuePosition})` : '';
+    if (r.reason === 'host_capacity')
+        return `waiting for room on the workspace's host${position}`;
+    if (r.reason === 'concurrent_workspaces')
+        return 'waiting for a free working slot: every workspace the plan lets work at once is busy';
+    return `waiting to be admitted${r.reason ? ` (${r.reason})` : ''}${position}`;
+}
+/**
+ * The client listener that prints where a wait stands. Silent with `json`. A phase other than capacity_pending ends
+ * the queue, so a later queue prints again.
+ */
+export function waitStatusListener(stderr, json) {
+    let last = null;
+    return (e) => {
+        if (json)
+            return;
+        let line;
+        if (e.type === 'retry') {
+            if (!e.retry.admission)
+                return;
+            line = admissionLine(e.retry);
+        }
+        else if (e.type === 'phase') {
+            if (e.phase !== 'capacity_pending') {
+                if (e.action !== 'tool')
+                    last = null;
+                return;
+            }
+            line = queueLine(e);
+        }
+        else {
+            if (e.action !== 'token' && e.action !== 'tool')
+                last = null;
+            return;
+        }
+        if (line === last)
+            return;
+        last = line;
+        stderr.write(stderr.isTTY ? `\x1b[2m· ${line}\x1b[0m\n` : `${line}\n`);
+    };
+}