@shardflux/cli 0.20.0 → 0.23.0

package/dist/machine-setup.js

@@ -25,6 +25,7 @@ import { syncAgentConfig } from "./agent-config-sync.js";
 import { cloudClaudeLogin } from "./claude-cloud-login.js";
 import { MachineSetupError, UsageError } from "./errors.js";
 import { openMachine } from "./filesystem-commands.js";
+import { machineRow, readMachineRow, rowText, statusDoc } from "./machine-status.js";
 import { installDirs } from "./onboarding.js";
 import { progress as stderrProgress } from "./progress.js";
 import { writeProgress } from "./seed-phases.js";
@@ -248,6 +249,14 @@ export function setupGuard(env, command, values, positionals) {
         return 'machine setup reads files only to standard output';
     return undefined;
 }
+function setupCapacity(ws) {
+    const disk = ws.grants?.disk_gib;
+    if (typeof disk !== 'number' || !Number.isFinite(disk) || disk <= 0)
+        return undefined;
+    const requested = ws.caps?.disk_gib ?? null;
+    const source = ws.ceilings?.disk_gib === disk ? ws.ceilings.sources.disk_gib : requested === disk ? 'cap' : null;
+    return { disk_gib: disk, requested_disk_gib: requested, source };
+}
 const CLIS = ['gh', 'git-lfs', 'docker', 'kubectl', 'helm', 'k9s', 'kind', 'terraform', 'tofu', 'pulumi', 'aws', 'gcloud', 'az', 'doctl', 'flyctl', 'vercel',
     'netlify', 'heroku', 'supabase', 'wrangler', 'stripe', 'jq', 'yq', 'rg', 'fd', 'fzf', 'bat', 'eza', 'tree', 'htop', 'btop', 'tmux', 'nvim', 'vim', 'emacs',
     'http', 'wget', 'make', 'cmake', 'just', 'direnv', 'starship', 'zoxide', 'atuin', 'lazygit', 'delta', 'tig', 'uv', 'pipx', 'poetry', 'pnpm', 'yarn', 'bun',
@@ -309,7 +318,10 @@ export async function collectInventory(env) {
         catch { /* absent */ }
     }
     const os = osPlatform() === 'darwin' ? `macOS ${release()} (${arch()})` : `${osPlatform()} ${release()} (${arch()})`;
+    const dotfiles = DOTFILES.filter(f => exists(join(home, f)));
     return {
+        source_home: home,
+        config_paths: dotfiles.map(f => join(home, f)),
         os,
         shell: env.SHELL ? env.SHELL.split('/').pop() : null,
         homebrew: brew ? brew.split('\n').map(s => s.trim()).filter(Boolean).slice(0, 400) : null,
@@ -319,7 +331,7 @@ export async function collectInventory(env) {
         clis: CLIS.filter(c => has(c)),
         npm_globals: npmGlobals.slice(0, 200),
         git: { ...(name ? { name } : {}), ...(email ? { email } : {}) },
-        dotfiles: DOTFILES.filter(f => exists(join(home, f))),
+        dotfiles,
     };
 }
 /** Skills this computer's config copy brings to the machine: ~/.claude/skills and ~/.codex/skills (not Codex's bundled .system). */
@@ -340,7 +352,7 @@ const SUMMARY_SHAPE = '{"tools":["gh","ripgrep"],"runtimes":["Node 24","Python 3
  * The fixed task: agent-setup.ts's "Build the machine" step, extended to recreate this computer. `where` is 'local' for
  * an agent on this computer (it reaches the VM through shard) or 'vm' for the cloud Claude inside the machine VM.
  */
-export function setupTask(where, key, inventory) {
+export function setupTask(where, key, inventory, capacity) {
     const reach = where === 'local'
         ? [
             `The machine VM's workspace key is ${key}. Run commands on it with:`,
@@ -349,6 +361,8 @@ export function setupTask(where, key, inventory) {
             `  shard files write ${key} /home/user/<path> --from - <<'EOF'`,
             '  <contents>',
             '  EOF',
+            ...(inventory.source_home ? [`Read local configuration only under ${JSON.stringify(inventory.source_home)}. The inventory and those files are the source of truth. Do not infer the source home or git identity from your login shell, inspect another home, or read dotfiles there.`] : []),
+            ...(inventory.config_paths ? [`The allowed local configuration paths are ${JSON.stringify(inventory.config_paths)}. Read only these paths (or their children for a listed directory); an empty list means there are no portable dotfiles to read. Claude/Codex configuration is copied separately by shard, not by you.`] : []),
             'On this computer you may only read: the Read and Glob tools, and read-only commands (brew list, brew leaves, ls, which, git config --global --list, <tool> --version). Nothing on this computer may change. Run every shard command on its own, not in a pipeline.',
         ]
         : [
@@ -362,8 +376,11 @@ export function setupTask(where, key, inventory) {
         'Their computer (collected by shard; names and versions only):',
         JSON.stringify(inventory, null, 1),
         '',
+        ...(capacity ? ['Machine disk granted by Shardflux (a requested cap is not additional space):', JSON.stringify(capacity), ''] : []),
+        'Before installing, run df -h / /home/user on the VM. Check package download/installed sizes before each small batch; use --no-install-recommends with apt-get. Leave room for package configuration and the saved machine. If a tool or matching runtime will not fit, skip it with the concrete disk-space reason in your JSON, and keep the package manager healthy. Never grow the disk, change caps or upgrade the plan. Do not describe skipped tools as installed.',
+        '',
         'Do:',
-        '1. Dev tools and CLIs it uses (Homebrew formulae, the CLIs present, global npm packages): install the Linux equivalents with sudo apt-get install -y, the tool\'s official Linux install script or binary release, npm -g, pipx or uv tool. Check with command -v first and skip what the VM already has. Skip GUI apps, macOS-only tools and libraries that are only dependencies.',
+        '1. Dev tools and CLIs it uses (Homebrew formulae, the CLIs present, global npm packages): install the Linux equivalents with sudo apt-get install -y --no-install-recommends, the tool\'s official Linux install script or binary release, npm -g, pipx or uv tool. Check with command -v first and skip what the VM already has. Skip GUI apps, macOS-only tools and libraries that are only dependencies.',
         '2. Language runtimes at the same major versions (Node, Python, Go, Rust, Ruby, Java…), with the version manager the computer uses when there is one (nvm, mise, asdf, pyenv, uv…).',
         '3. Shell: the same login shell if it is zsh or fish (install it and chsh -s for user), with the framework and prompt it uses (oh-my-zsh, starship…). Bring the aliases, functions, environment variables and PATH entries from its rc files that make sense on Linux into the VM\'s rc files, in a block marked "# from your computer (shard machine setup)", keeping what is there. Leave out macOS-only lines (brew shellenv, /opt/homebrew, /Applications, pbcopy, open, osascript), paths that only exist on that computer, and every line that sets a token, key, password or other secret.',
         '4. Git: the global identity (user.name, user.email) and global settings that are not machine specific (aliases, init.defaultBranch, pull.rebase, the global gitignore). No credential helper, no signing key.',
@@ -470,6 +487,21 @@ export function claimRun(store, apiUrl, org, ifNeeded, start) {
     });
     return result;
 }
+/** An explicit tool permission refusal must not be retried through a different agent. */
+class SetupPermissionRefusal extends MachineSetupError {
+}
+function checkClaudePermissions(result, app) {
+    if (!Array.isArray(result?.permission_denials) || !result.permission_denials.length)
+        return;
+    const tools = [...new Set(result.permission_denials.flatMap(d => typeof d?.tool_name === 'string' ? [d.tool_name.slice(0, 40)] : []))].slice(0, 5);
+    throw new SetupPermissionRefusal(`${app} stopped: permission refused${tools.length ? ` for ${tools.join(', ')}` : '; the provider omitted the tool names'}`, 'Resolve the reported permission refusal, then run shard machine setup --from-this-computer again');
+}
+function setupOutcome(text, app) {
+    const summary = parseSummary(text);
+    if (!summary)
+        throw new MachineSetupError(`${app} did not return a setup report`, 'shard machine setup --from-this-computer runs it again');
+    return { summary, text };
+}
 /**
  * Whether the agent reached the machine VM at all: every shard command it ran failed (a sandbox without network, a
  * permission it was never given) means nothing was set up, whatever its reply says, and the next agent should try.
@@ -486,11 +518,13 @@ export class ShardReach {
             this.firstError = firstLine(output).slice(0, 160);
     }
     check(app) {
+        if (this.ok === 0 && this.calls === 0)
+            throw new MachineSetupError(`${app} did not confirm access to your machine with shard`, 'shard machine setup --from-this-computer runs it again');
         if (this.calls > 0 && this.ok === 0)
             throw new MachineSetupError(`${app} could not reach your machine with shard${this.firstError ? `: ${this.firstError}` : ''}`, 'shard machine setup --from-this-computer runs it again');
     }
 }
-const isShardCommand = (command) => /(^|[\s;&|('"])shard\s+(ws|workspaces|files)\s/.test(command);
+const isShardCommand = (command) => /(^|[\s;&|('"])shard\s+(?:(?:--json|--wake|--no-wake)\s+|(?:--api-url|--agent-label|--wake-timeout)\s+(?:"[^"]*"|'[^']*'|[^\s]+)\s+)*(ws|workspaces|files)\s/.test(command);
 const toolText = (content) => typeof content === 'string' ? content
     : Array.isArray(content) ? content.map(c => (c && typeof c === 'object' && typeof c.text === 'string' ? c.text : '')).join(' ') : '';
 /** A private folder for the run: the agent's working directory, and a `shard` on PATH that is this very CLI. */
@@ -539,6 +573,7 @@ async function runClaudeLocal(ctx, agent, key, task, timeoutMs, log) {
                 catch { /* not an event */ }
             },
         });
+        checkClaudePermissions(result, 'Claude');
         if (run.timedOut)
             throw new MachineSetupError(`Claude ran past the ${timeoutText(timeoutMs)} time box`, 'shard machine setup --from-this-computer runs it again');
         if (!result)
@@ -546,7 +581,7 @@ async function runClaudeLocal(ctx, agent, key, task, timeoutMs, log) {
         if (result.is_error || result.subtype !== 'success')
             throw new MachineSetupError(`Claude stopped: ${(result.result ?? result.subtype ?? 'error').slice(0, 200)}`, 'shard machine setup --from-this-computer runs it again');
         reach.check('Claude');
-        return { summary: parseSummary(result.result ?? ''), text: result.result ?? '' };
+        return setupOutcome(result.result ?? '', 'Claude');
     }
     finally {
         rmSync(dir, { recursive: true, force: true });
@@ -587,7 +622,7 @@ async function runCodexLocal(ctx, agent, key, task, timeoutMs, log) {
         if (run.code !== 0)
             throw new MachineSetupError(`Codex stopped: ${failure || firstLine(run.stderr) || `exit ${run.code ?? run.signal}`}`.slice(0, 300), 'shard machine setup --from-this-computer runs it again');
         reach.check('Codex');
-        return { summary: parseSummary(last), text: last };
+        return setupOutcome(last, 'Codex');
     }
     finally {
         rmSync(dir, { recursive: true, force: true });
@@ -615,9 +650,10 @@ async function runCloud(ctx, ws, task, timeoutMs) {
             doc = JSON.parse(run.stdout.trim().split('\n').pop() ?? '{}');
         }
         catch { /* below */ }
-        if (run.exitCode !== 0 || doc.is_error || !doc.result)
+        checkClaudePermissions(doc, 'Cloud Claude');
+        if (run.exitCode !== 0 || doc.is_error || (doc.subtype !== undefined && doc.subtype !== 'success') || !doc.result)
             throw new MachineSetupError(`Claude in the machine VM stopped: ${(doc.result ?? firstLine(run.stderr) ?? `exit ${run.exitCode}`).slice(0, 200) || `exit ${run.exitCode}`}`, 'shard machine setup --from-this-computer runs it again');
-        return { summary: parseSummary(doc.result), text: doc.result };
+        return setupOutcome(doc.result, 'Cloud Claude');
     }
     finally {
         await cell.files.remove('/tmp/shard-machine-setup', { recursive: true }).catch(() => undefined);
@@ -665,17 +701,19 @@ function output(ctx, doc, human) {
     ctx.io.stdout.write(ctx.json ? `${JSON.stringify(doc)}\n` : `${human}\n`);
     return 0;
 }
-function statusDoc(rec, machine) {
-    return { state: rec?.state ?? 'none', machine_version: machine.version, ...(rec ?? {}), ...(rec ? {} : { line: null }) };
-}
 export async function machineSetup(ctx, values, deps = {}) {
     const cloud = ctx.cloud();
     const store = new AgentStateStore(ctx.store.dir);
     const machine = await cloud.machine.get({ signal: ctx.signal });
     const org = machine.organization_id;
+    // One source of truth (0.20.2+): the API's machine decides, this computer's record adds a run under way or stopped.
+    const status = async () => {
+        const rec = readRecord(store, ctx.apiUrl, org), row = await readMachineRow(ctx, machine);
+        return { doc: statusDoc(row, rec), text: rowText(row) };
+    };
     if (values.status === true) {
-        const rec = readRecord(store, ctx.apiUrl, org);
-        return output(ctx, statusDoc(rec, machine), rec?.line ?? (machine.version > 0 ? `machine: version ${machine.version}; not set up from this computer` : 'machine: not set up yet'));
+        const { doc, text } = await status();
+        return output(ctx, doc, text);
     }
     if (values['from-this-computer'] !== true)
         throw new UsageError('shard machine setup needs --from-this-computer', 'shard machine setup --from-this-computer');
@@ -687,8 +725,10 @@ export async function machineSetup(ctx, values, deps = {}) {
     const startRec = { state: 'running', runner: null, pid: process.pid, started_at: new Date(started).toISOString(), finished_at: null, machine_version: null,
         line: workingLine('claude'), summary: null, error: null, duration_ms: null };
     const claim = claimRun(store, ctx.apiUrl, org, values['if-needed'] === true, startRec);
-    if (!claim.claimed)
-        return output(ctx, { ...statusDoc(claim.record, machine), skipped: true }, claim.record.state === 'running' ? `${claim.record.line} (already running)` : claim.record.line);
+    if (!claim.claimed) {
+        const { doc, text } = await status();
+        return output(ctx, { ...doc, skipped: true }, claim.record.state === 'running' ? `${text} (already running)` : text);
+    }
     const phase = phaseWriter(ctx);
     const steps = stepLog(ctx);
     let runner = null;
@@ -705,10 +745,16 @@ export async function machineSetup(ctx, values, deps = {}) {
         phase('machine', workingLine(runner));
         const inventory = await (deps.inventory ?? collectInventory)(env);
         const { state, ws } = await (deps.open ?? ((c, s) => openMachine(c, s)))(ctx, machine);
+        const capacity = setupCapacity(ws);
+        if (capacity) {
+            const line = `Cloud machine disk: ${capacity.disk_gib} GiB${capacity.source === 'plan' ? ' (plan limit)' : ''}; checking which tools fit…`;
+            phase('capacity', line);
+            steps.log(line);
+        }
         // A machine saved before (from another computer, or by hand) gets this computer's Claude and Codex config too;
         // openMachine copies it into a first machine itself.
         if (state.version > 0)
-            await syncAgentConfig(ctx, ws).catch((error) => steps.log(`config copy: ${error instanceof Error ? error.message : String(error)}`));
+            await syncAgentConfig(ctx, ws);
         let outcome;
         let spent = 0;
         for (const candidate of chain) {
@@ -725,16 +771,16 @@ export async function machineSetup(ctx, values, deps = {}) {
             const began = Date.now();
             try {
                 outcome = runner === 'cloud'
-                    ? await runCloud(ctx, ws, setupTask('vm', ws.key, inventory), box)
+                    ? await runCloud(ctx, ws, setupTask('vm', ws.key, inventory, capacity), box)
                     : runner === 'claude'
-                        ? await runClaudeLocal(ctx, candidate.agent, ws.key, setupTask('local', ws.key, inventory), box, steps.log)
-                        : await runCodexLocal(ctx, candidate.agent, ws.key, setupTask('local', ws.key, inventory), box, steps.log);
+                        ? await runClaudeLocal(ctx, candidate.agent, ws.key, setupTask('local', ws.key, inventory, capacity), box, steps.log)
+                        : await runCodexLocal(ctx, candidate.agent, ws.key, setupTask('local', ws.key, inventory, capacity), box, steps.log);
                 attempts.push({ runner, ok: true, error: null, duration_ms: Date.now() - began });
                 break;
             }
             catch (error) {
                 // Only the agent's own failures move on to the next agent; the API, the network or an interrupt stop here.
-                if (!(error instanceof MachineSetupError) || ctx.signal.aborted)
+                if (error instanceof SetupPermissionRefusal || !(error instanceof MachineSetupError) || ctx.signal.aborted)
                     throw error;
                 attempts.push({ runner, ok: false, error: error.message, duration_ms: Date.now() - began });
                 steps.log(`agent ${runner} stopped: ${error.message}`);
@@ -751,10 +797,11 @@ export async function machineSetup(ctx, values, deps = {}) {
         const skills = countSkills(env.HOME || homedir());
         const line = readyLine(outcome.summary, skills);
         const rec = { state: 'ready', runner, pid: null, started_at: startRec.started_at, finished_at: new Date().toISOString(), machine_version: saved.version,
-            line, summary: { ...(outcome.summary ?? { tools: [], runtimes: [], shell: null, dotfiles: [], skipped: [] }), skills, runner }, attempts, error: null, duration_ms: Date.now() - started };
+            line, summary: { ...outcome.summary, skills, runner }, attempts, error: null, duration_ms: Date.now() - started };
         writeRecord(store, ctx.apiUrl, org, rec);
         phase('ready', line);
-        return output(ctx, { ...rec, workspace_key: ws.key }, line);
+        const row = machineRow(saved, rec);
+        return output(ctx, { ...statusDoc(row, rec), workspace_key: ws.key }, rowText(row));
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);

package/dist/machine-status.d.ts

@@ -0,0 +1,67 @@
+import type { AgentFilesystem } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+import { type BuildQueue } from './filesystem-commands.js';
+import { type SaveFailure } from './errors.js';
+import { type SetupRecord } from './machine-setup.js';
+export type MachineRowState = 'ready' | 'saving' | 'failed' | 'none';
+/** too_large and timeout: the save's build; save_failed: any other build failure; setup_stopped: this computer's agent. */
+export type MachineFailure = 'too_large' | 'timeout' | 'save_failed' | 'setup_stopped';
+export interface MachineAction {
+    id: 'save' | 'retry' | 'setup';
+    title: 'Save again' | 'Retry' | 'Set up';
+    command: string[];
+}
+export interface MachineRow {
+    /** unknown: the check or response could not establish readiness; unavailable: the API has no machine route. */
+    state: MachineRowState | 'unknown' | 'unavailable';
+    /** The saved version in use; 0 when none is, null when the version could not be read. */
+    version: number | null;
+    /** One plain line of at most 80 characters. */
+    line: string;
+    reason?: MachineFailure;
+    /** The failure's full message. */
+    error?: string;
+    /** saving: the setup's agent (setup) or the save's build (save), with its version and place in the queue. */
+    progress?: {
+        phase: 'setup' | 'save';
+        version?: number;
+        queue?: BuildQueue;
+    };
+    action?: MachineAction;
+}
+/** `text` cut so that it and `suffix` fit one 80-character line. */
+export declare function fitLine(text: string, suffix?: string): string;
+/**
+ * A build failure as people say it: too large, out of time, or the build's own first sentence. The failure's code
+ * (0.21.1+, from an API that reports it) decides first: resource_limit is too large, named with the plan's disk when it
+ * is that limit.
+ */
+export declare function saveFailure(message: string, failure?: SaveFailure): {
+    reason: MachineFailure;
+    why: string;
+};
+/** What `machineRow` reads besides the machine: whether the failed save's VM is still there, and a build's queue. */
+export interface MachineRowFacts {
+    saveSourceExists?: boolean;
+    queue?: BuildQueue;
+}
+/** The row, from the API's machine and this computer's setup record (pure: the facts are read by `readMachineRow`). */
+export declare function machineRow(machine: AgentFilesystem, rec: SetupRecord | undefined, facts?: MachineRowFacts): MachineRow;
+/**
+ * The row for this account and computer: the machine (one API call), the setup record, and, only when they matter,
+ * whether a failed save's VM is still there and a saving build's queue. `machine` skips the first call when the caller
+ * has it.
+ */
+export declare function readMachineRow(ctx: Ctx, machine?: AgentFilesystem): Promise<MachineRow>;
+/**
+ * `setup --inspect`'s row: an API without machines reports unavailable; a check that fails says so on the row
+ * (state unknown) and never fails the report.
+ */
+export declare function inspectMachineRow(ctx: Ctx): Promise<MachineRow | null>;
+/**
+ * `machine setup --status` and a setup's result: this computer's record (runner, summary, attempts…) with the row's
+ * state and line. Saving reads as running for older apps; unknown and unavailable remain explicit.
+ */
+export declare function statusDoc(row: MachineRow, rec: SetupRecord | undefined): Record<string, unknown>;
+/** The row as the terminal shows it: its line, and for a failure or none the command that recovers it. */
+export declare function rowText(row: MachineRow): string;

package/dist/machine-status.js

@@ -0,0 +1,140 @@
+/**
+ * The account's cloud machine as one row (0.20.2+), the one source of truth that `shard machine setup --status`, `shard
+ * setup --inspect` (onboarding.machine) and a setup run's result report, and that the menu bar, the Linux app and the
+ * terminal onboarding show. The API's machine (GET /v1/machine: what is saved, saving or failed) decides; this
+ * computer's setup record (agents.json) adds only what the API cannot know: its agent is setting the machine up right
+ * now, or its last setup stopped before anything was saved.
+ *
+ * - ready: a version is saved and in use. saving: the setup's agent works, or a save builds (with its place in the
+ *   queue). failed: the newest save failed (its reason: too large, out of time, or the build's own message), or this
+ *   computer's setup stopped and no version was saved since it started. none: nothing saved and nothing under way.
+ * - A failed row has one plain line and one recovery: Save again (`shard machine save --wait`) when the save failed and
+ *   its machine VM is still there, else Retry (`shard machine setup --from-this-computer`).
+ */
+import { ShardfluxApiError, saveProgressText } from '@shardflux/sdk';
+import { AgentStateStore } from "./agent-state.js";
+import { machineSaveSource, pendingQueue } from "./filesystem-commands.js";
+import { gib, planDiskLimit } from "./errors.js";
+import { readRecord, readyLine, workingLine } from "./machine-setup.js";
+const LIMIT = 80;
+/** `text` cut so that it and `suffix` fit one 80-character line. */
+export function fitLine(text, suffix = '') {
+    const flat = text.replace(/\s+/g, ' ').trim(), room = LIMIT - suffix.length;
+    return (flat.length <= room ? flat : `${flat.slice(0, room - 1).trimEnd()}…`) + suffix;
+}
+/**
+ * A build failure as people say it: too large, out of time, or the build's own first sentence. The failure's code
+ * (0.21.1+, from an API that reports it) decides first: resource_limit is too large, named with the plan's disk when it
+ * is that limit.
+ */
+export function saveFailure(message, failure) {
+    const disk = planDiskLimit(failure);
+    if (disk)
+        return { reason: 'too_large', why: `over the plan’s ${gib(disk.limit)} disk` };
+    if (failure?.code === 'resource_limit')
+        return { reason: 'too_large', why: 'it’s too large' };
+    if (failure?.code === 'timeout')
+        return { reason: 'timeout', why: 'it ran out of time' };
+    if (/too[ _]large|exceed\w* (the |its )?(\w+ )?(max|size|limit|quota)|max_\w*bytes|disk (is )?full|no space|insufficient_disk|quota_exceeded|above the .*(GiB|MiB)/i.test(message))
+        return { reason: 'too_large', why: 'it’s too large' };
+    if (/exceeded its \d+ ?(second|s)\b|time ?out|timed out|ran past|took too long|deadline/i.test(message))
+        return { reason: 'timeout', why: 'it ran out of time' };
+    const first = message.replace(/\s+/g, ' ').trim().split(/(?<=[.!?])\s/)[0]?.replace(/[.!?]$/, '') ?? '';
+    // The API's own fallback ("Filesystem save failed. Open its build status…") adds nothing to "not saved".
+    return { reason: 'save_failed', why: /^(filesystem )?save failed$/i.test(first) ? '' : first };
+}
+const SAVE_AGAIN = { id: 'save', title: 'Save again', command: ['shard', 'machine', 'save', '--wait'] };
+const RETRY = { id: 'retry', title: 'Retry', command: ['shard', 'machine', 'setup', '--from-this-computer'] };
+const SET_UP = { id: 'setup', title: 'Set up', command: ['shard', 'machine', 'setup', '--from-this-computer'] };
+/** When the newest saved version was made (0 when none is). */
+const savedAt = (m) => Math.max(0, ...m.history.map(h => Date.parse(h.created_at)).filter(Number.isFinite));
+const inUse = (version) => (version > 0 ? ` · version ${version} stays in use` : ' · no saved version');
+/** The row, from the API's machine and this computer's setup record (pure: the facts are read by `readMachineRow`). */
+export function machineRow(machine, rec, facts = {}) {
+    const version = machine.version;
+    if (!Number.isSafeInteger(version) || version < 0)
+        return { state: 'unknown', version: null, line: 'Cloud machine readiness could not be confirmed: saved version unavailable' };
+    if (machine.state === 'building' && machine.pending) {
+        const q = facts.queue;
+        return { state: 'saving', version, line: fitLine(q ? `Saving machine v${machine.pending.version} · ${saveProgressText({ version: machine.pending.version, build_id: machine.pending.build_id, state: 'queued', queue: q })}` : `Saving machine v${machine.pending.version}…`, inUse(version)),
+            progress: { phase: 'save', version: machine.pending.version, ...(q ? { queue: q } : {}) } };
+    }
+    if (machine.state === 'building')
+        return { state: 'unknown', version, line: 'Cloud machine is saving; build progress is unavailable' };
+    if (rec?.state === 'running') {
+        return { state: 'saving', version, line: fitLine(rec.line || workingLine(rec.runner ?? 'claude')), progress: { phase: 'setup' } };
+    }
+    if (machine.state === 'failed') {
+        const message = machine.failure?.message || 'The API reported a failed save without build details.';
+        const { reason, why } = saveFailure(message, machine.failure);
+        return { state: 'failed', version, line: fitLine(`Cloud machine not saved${why ? `: ${why}` : ''}`, inUse(version)), reason, error: message,
+            action: facts.saveSourceExists === false ? RETRY : SAVE_AGAIN };
+    }
+    // A setup that stopped counts until a version is saved after it started (by its own save that outlived its wait, by
+    // Save again, or by hand).
+    const started = Date.parse(rec?.started_at ?? '');
+    if (rec?.state === 'failed' && (version === 0 || (Number.isFinite(started) && started > savedAt(machine)))) {
+        const error = rec.error ?? 'it didn’t finish';
+        return { state: 'failed', version, line: fitLine(`Cloud machine setup stopped: ${error}`, inUse(version)), reason: 'setup_stopped', error, action: RETRY };
+    }
+    if (machine.state === 'ready' && version > 0) {
+        const mine = rec?.state === 'ready' && rec.machine_version === version;
+        const line = mine ? (rec.line || (rec.summary ? readyLine(rec.summary, rec.summary.skills) : '')) : '';
+        return { state: 'ready', version, line: line ? fitLine(line, ` · version ${version}`) : `Cloud machine ready (version ${version})` };
+    }
+    if (machine.state !== 'empty' || version !== 0)
+        return { state: 'unknown', version, line: 'Cloud machine readiness could not be confirmed from this API response' };
+    return { state: 'none', version: 0, line: 'Cloud machine not set up yet', action: SET_UP };
+}
+/**
+ * The row for this account and computer: the machine (one API call), the setup record, and, only when they matter,
+ * whether a failed save's VM is still there and a saving build's queue. `machine` skips the first call when the caller
+ * has it.
+ */
+export async function readMachineRow(ctx, machine) {
+    const cloud = ctx.cloud();
+    machine ??= await cloud.machine.get({ signal: ctx.signal });
+    const rec = readRecord(new AgentStateStore(ctx.store.dir), ctx.apiUrl, machine.organization_id);
+    const facts = {};
+    if (machine.state === 'building' && machine.pending)
+        facts.queue = await pendingQueue(ctx, machine);
+    if (machine.state === 'failed' && machine.failure)
+        facts.saveSourceExists = await saveSourceExists(ctx, machine);
+    return machineRow(machine, rec, facts);
+}
+/** The VM `shard machine save` saves (machineSaveSource): Save again needs it; without it the setup runs again. */
+async function saveSourceExists(ctx, machine) {
+    try {
+        return !!(await machineSaveSource(ctx, machine));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * `setup --inspect`'s row: an API without machines reports unavailable; a check that fails says so on the row
+ * (state unknown) and never fails the report.
+ */
+export async function inspectMachineRow(ctx) {
+    try {
+        return await readMachineRow(ctx);
+    }
+    catch (error) {
+        if (error instanceof ShardfluxApiError && (error.status === 404 || error.details?.reason === 'filesystem_unavailable'))
+            return { state: 'unavailable', version: null, line: 'This API does not report cloud machine readiness; update the server' };
+        return { state: 'unknown', version: null, line: fitLine(`Couldn’t check your cloud machine: ${error instanceof Error ? error.message : String(error)}`) };
+    }
+}
+/**
+ * `machine setup --status` and a setup's result: this computer's record (runner, summary, attempts…) with the row's
+ * state and line. Saving reads as running for older apps; unknown and unavailable remain explicit.
+ */
+export function statusDoc(row, rec) {
+    const state = row.state === 'saving' ? 'running' : row.state;
+    return { ...(rec ?? {}), state, line: state === 'none' ? null : row.line, error: row.state === 'failed' ? row.error ?? null : null,
+        machine_version: row.version, machine: row };
+}
+/** The row as the terminal shows it: its line, and for a failure or none the command that recovers it. */
+export function rowText(row) {
+    return row.action ? `${row.line}. ${row.action.title}: ${row.action.command.join(' ')}` : row.line;
+}

package/dist/main.js

@@ -10,10 +10,9 @@
  *   (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 { aboutWait } from "./filesystem-commands.js";
 import { homedir, hostname } from 'node:os';
 import { statSync } from 'node:fs';
-import { SDK_VERSION, Shardflux, ShardfluxAccount, isSessionToken } from '@shardflux/sdk';
+import { SDK_VERSION, Shardflux, ShardfluxAccount, aboutSeconds, isSessionToken } from '@shardflux/sdk';
 import { CLI_VERSION, CENTER_COMMAND, GUIDE_COMMAND, ONBOARDING_COMMAND, PROJECT_COMMAND, parseCommandLine, resolveApiUrl, resolveWake, resolveWakeTimeout } from "./args.js";
 import { commandCenter } from "./command-center.js";
 import { launchProjectCommand } from "./conversation-terminal.js";
@@ -73,10 +72,8 @@ function hintFor(info, cred, file, command = '') {
         return `keep waiting with: shard operations wait ${info.operation_id}`;
     if (info.code === 'usage')
         return 'run "shard --help" or "shard <command> --help"';
-    if (info.code === 'filesystem_save_failed') {
-        const level = info.details?.level === 'template' ? 'template' : 'machine';
-        return `the version in use is unchanged; fix what the message names in ${level === 'machine' ? 'shard machine' : 'the project agent'}, then run shard ${level} save --wait again`;
-    }
+    if (info.code === 'filesystem_save_failed')
+        return info.fix;
     if (info.source === 'cell' && info.code === 'workspace_not_running')
         return 'open or resume the workspace first: shard workspaces open <key> --template <slug>';
     if (info.status === 401 && info.code === 'unauthenticated') {
@@ -118,7 +115,7 @@ function hintFor(info, cred, file, command = '') {
     if (info.code === 'rate_limited' && reasonOf(info) === 'template_build_queue_full') {
         const queued = typeof info.details?.queued === 'number' ? info.details.queued : undefined;
         const retry = info.retry_after_seconds ?? (typeof info.details?.retry_after_seconds === 'number' ? info.details.retry_after_seconds : undefined);
-        return `${queued ?? 'Several'} build${queued === 1 ? '' : 's'} already wait for your plan's build slots; nothing was started. Run the same command again${retry ? ` in ${aboutWait(retry)}` : ' when one finishes'}`;
+        return `${queued ?? 'Several'} build${queued === 1 ? '' : 's'} already wait for your plan's build slots; nothing was started. Run the same command again${retry ? ` in ${aboutSeconds(retry)}` : ' when one finishes'}`;
     }
     const policyHint = spendPolicyHint(info);
     if (policyHint)
@@ -351,6 +348,8 @@ const FEEDBACK_EMAIL = 'shardflux@heliosone.fi';
 // names the next step (upgrade, overage, the cap, the payment method), not a problem to report.
 const NO_NUDGE_CODES = new Set(['usage', 'terms_not_accepted', 'interrupted', 'unauthenticated', 'validation_failed', 'mfa_required', 'step_up_required', 'email_unverified', 'timeout', 'checkout_ended', 'allowance_exhausted']);
 const NO_NUDGE_REASONS = new Set([
+    // shard template delete with nothing saved (0.20.1+): the hint names the next step.
+    'filesystem_not_found',
     'revision_mismatch',
     'tree_revision_mismatch',
     'edit_not_found',
@@ -383,6 +382,9 @@ function nudges(info, command) {
     // A plan limit whose hint names the next step (0.9.0): busy working slots, or Retained state used up.
     if (info.code === 'quota_exceeded' && quotaHint(info) !== undefined)
         return false;
+    // A save the same VM cannot pass (0.21.1+), such as one larger than the plan's workspace disk: the hint names the fix.
+    if (info.code === 'filesystem_save_failed' && info.retryable === false)
+        return false;
     const reason = reasonOf(info);
     return !NO_NUDGE_CODES.has(info.code) && !(reason !== undefined && NO_NUDGE_REASONS.has(reason));
 }
@@ -474,12 +476,8 @@ export async function run(argv, io, opts = {}) {
         io.stdout.write(wantsJson ? json({ cli: CLI_VERSION, sdk: SDK_VERSION }) : `shard ${CLI_VERSION} (@shardflux/sdk ${SDK_VERSION})\n`);
         return EXIT.ok;
     }
-    // shard ./ attaches Claude Code or Codex to this terminal: without one (or in a coding agent's shell) it says how to
-    // start the conversation instead of starting one nobody can see (0.17.1+: a usage error, before 0.17.1 its help).
-    if (parsed.command === PROJECT_COMMAND && !tty && !parsed.global.json) {
-        await startupHousekeeping({ io, store, signal });
-        return report(new UsageError('shard ./ opens Claude Code or Codex in a terminal, and this shell has none.', 'ask your user to run shard ./ in their own terminal, or start the conversation detached: shard ./ --json --prompt "<task>" (shard ./ codex --json ... for Codex)'));
-    }
+    // shard ./ attaches Claude Code or Codex to this terminal. Without one (or in a coding agent's shell) it opens in the
+    // person's chosen app (0.20.1+: a new tab of their terminal app, see launchProjectCommand), never one nobody can see.
     command = parsed.command.path.join(' ');
     let ctx;
     let updates = null;

package/dist/menubar.d.ts

@@ -1,12 +1,13 @@
 import type { Handler } from './commands.js';
-export type NativeRunner = (tool: string, args: string[]) => Promise<string>;
+/** `env` adds variables to this process's environment for the tool (the app's --control reads its config directory). */
+export type NativeRunner = (tool: string, args: string[], env?: Record<string, string>) => Promise<string>;
 /**
  * Every native tool a default MenubarManager runs (plutil, codesign, xattr, open, the app's --control) goes through
  * `nativeTools.run`. The CLI test support replaces it, so a test run never starts, stops or inspects a real app,
  * whether or not a built Shardflux.app is in the package.
  */
 export declare const nativeTools: {
-    run: (tool: string, args: string[], signal?: AbortSignal) => Promise<string>;
+    run: (tool: string, args: string[], signal?: AbortSignal, env?: Record<string, string>) => Promise<string>;
 };
 export interface MenubarStatus {
     installed: boolean;
@@ -57,9 +58,9 @@ export declare class MenubarManager {
     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>;
+    status(configDir?: string): Promise<MenubarStatus>;
+    stop(configDir?: string): Promise<MenubarStatus>;
+    login(value: 'on' | 'off', configDir?: string): 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