@shardflux/cli 0.13.2 → 0.13.4

package/dist/agent-target-commands.js

@@ -5,6 +5,7 @@ import { Readable, Duplex } from 'node:stream';
 import { ShardfluxApiError, WorkspaceTunnels } from '@shardflux/sdk';
 import { out, resolveWorkspace } from "./commands.js";
 import { AgentTargets, installedTargets } from "./agent-targets.js";
+import { join, relative } from 'node:path';
 import { projectIdentity } from "./project-identity.js";
 import { projectWorkspacePath } from "./agent-repository.js";
 import { UsageError } from "./errors.js";
@@ -134,14 +135,42 @@ const openTarget = (target) => async (ctx, values, [ref = 'main']) => {
     out(ctx, `${instructions}\n`, { target, workspace: ws.data, host: entry.host, instructions });
     return 0;
 };
+const tilde = (targets, file) => file.startsWith(`${targets.home}/`) ? `~/${relative(targets.home, file)}` : file;
+const targetLabel = (e) => `[SF] ${e.project} · ${e.agent}`;
+/** Where each managed connection of an entry lives: the SSH host block (and its Include), then each desktop app's file. */
+function configuredTargets(targets, e) {
+    return [
+        { target: 'ssh', label: 'SSH', file: targets.sshFile, name: e.host, detail: `(included from ${tilde(targets, join(targets.home, '.ssh', 'config'))}): ssh ${e.host}` },
+        ...(e.targets.includes('claude-desktop') ? [{ target: 'claude-desktop', label: 'Claude Desktop', file: targets.claudeFile, name: targetLabel(e), detail: `(sshConfigs: ${targetLabel(e)}); restart Claude Desktop, then pick it in Code's environment list` }] : []),
+        ...(e.targets.includes('codex-app') ? [{ target: 'codex-app', label: 'Codex app', file: targets.codexFile, name: targetLabel(e), detail: `(remoteConnections: ${targetLabel(e)}); restart Codex to import it` }] : []),
+    ];
+}
+function targetFiles(targets, entries) {
+    return [...new Set(entries.flatMap(e => configuredTargets(targets, e).map(c => c.file)))];
+}
 export const TARGET_HANDLERS = {
     'agents targets'(ctx, values, [ref]) {
         const detected = installedTargets(ctx.io.env);
         const targets = new AgentTargets(ctx.io.env, ctx.store.dir);
+        const key = ref ? keyOf(ref) : undefined;
+        const before = values.remove === true ? targets.configure(undefined, ctx.apiUrl, []) : [];
         const entries = ref || values.remove === true
-            ? targets.configure(ref ? keyOf(ref) : undefined, ctx.apiUrl, detected.targets.filter((t) => t === 'claude-desktop' || t === 'codex-app'), values.remove === true)
+            ? targets.configure(key, ctx.apiUrl, detected.targets.filter((t) => t === 'claude-desktop' || t === 'codex-app'), values.remove === true)
             : [];
-        out(ctx, `${detected.clients.join(', ') || 'No installed agent clients'}\nOpen targets: ${detected.targets.join(', ')}\n${entries.map(e => e.host).join('\n')}${entries.length ? '\n' : ''}`, { ...detected, entries });
+        const detection = `${detected.clients.join(', ') || 'No installed agent clients'}\nOpen targets: ${detected.targets.join(', ')}\n`;
+        if (values.remove === true) {
+            const removed = before.filter(e => !entries.some(n => n.host === e.host));
+            out(ctx, removed.length ? `Removed ${removed.map(e => `${e.workspace} (${e.host})`).join(', ')} from ${targetFiles(targets, removed).map(f => tilde(targets, f)).join(', ')}\n` : 'No managed targets to remove.\n', { ...detected, entries, removed });
+            return Promise.resolve(0);
+        }
+        const entry = key ? entries.find(e => e.workspace === key) : undefined;
+        if (!entry) {
+            out(ctx, detection, { ...detected, entries });
+            return Promise.resolve(0);
+        }
+        const configured = configuredTargets(targets, entry);
+        out(ctx, `Configured ${entry.workspace} as SSH host ${entry.host}:\n${configured.map(c => `  ${c.label.padEnd(15)} ${tilde(targets, c.file)}${c.detail ? ` ${c.detail}` : ''}`).join('\n')}\n` +
+            ['claude-desktop', 'codex-app'].filter(t => !entry.targets.includes(t)).map(t => `  ${(t === 'claude-desktop' ? 'Claude Desktop' : 'Codex app').padEnd(15)} not installed on this computer\n`).join(''), { ...detected, entries, configured: configured.map(({ target, file, name }) => ({ target, file, name })) });
         return Promise.resolve(0);
     },
     'agents open claude-desktop': openTarget('claude-desktop'),

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.13.2";
+export declare const CLI_VERSION = "0.13.4";
 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.2';
+export const CLI_VERSION = '0.13.4';
 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).' },
@@ -142,7 +142,10 @@ const SECRET_PERMISSIONS = {
 const KEY_COMMANDS = [
     ...['machine', 'template'].flatMap((level) => [
         { path: [level], summary: level === 'machine' ? 'Open your machine agent, or show its saved filesystem with --json' : 'Show this project’s template filesystem', positionals: [], options: {} },
-        { path: [level, 'save'], summary: `Save the ${level} filesystem as a new private version`, positionals: [], options: {} },
+        { path: [level, 'save'], summary: `Save the ${level} filesystem as a new private version`, positionals: [], options: {
+                wait: { type: 'boolean', description: 'Return when the new version is ready (or failed), printing progress on stderr.' },
+                timeout: { type: 'string', value: '<duration>', description: 'With --wait: give up waiting after this long (default 10m). The save continues server side.' },
+            } },
         { path: [level, 'rollback'], summary: `Restore a saved ${level} version`, positionals: [], options: { to: { type: 'string', value: '<version>', description: 'Version to restore (default previous saved version).' } } },
     ]),
     { path: ['agents', 'list'], summary: 'List coding agent sessions.', positionals: [], options: {
@@ -1136,8 +1139,8 @@ const AGENT_OPTIONS = {
     approvals: { type: 'boolean', description: 'Keep the agent’s permission prompts.' },
 };
 export const PROJECT_COMMAND = {
-    path: ['<path>'], summary: 'Open the project’s cloud agent command center',
-    description: 'Claude is the default; add codex to use Codex. Detach with Ctrl-] then d; /exit ends the agent session.',
+    path: ['<path>'], summary: 'Open the project’s cloud agent command center, or start its agent directly with claude|codex',
+    description: 'Naming the app starts (or reattaches) that agent at once; with --json it starts detached and prints the session. Detach with Ctrl-] then d; /exit ends the agent session.',
     positionals: [{ name: 'path', required: true }, { name: 'claude|codex' }], options: AGENT_OPTIONS,
 };
 export const CENTER_COMMAND = { path: ['<center>'], summary: 'Open the cloud agent command center', positionals: [], options: {} };

package/dist/assisted-setup.d.ts

@@ -4,10 +4,12 @@ export interface SetupProgress {
     id: string;
     deps_hash: string;
     state: 'queued' | 'running' | 'checking' | 'saving' | 'ready' | 'failed';
+    /** required is false for a step the repository marked `required: false` in .shardflux/setup.yaml. */
     tasks: {
         name: string;
-        state: 'queued' | 'running' | 'ready' | 'failed';
+        state: 'queued' | 'running' | 'ready' | 'failed' | 'skipped';
         attempts: number;
+        required?: boolean;
         error?: {
             code: string;
             message: string;

package/dist/assisted-setup.js

@@ -67,7 +67,10 @@ export async function retrySetupStep(ctx, workspace, step) {
 export function setupLine(project, setup) {
     if (setup.state === 'ready')
         return undefined;
-    const failed = setup.tasks.find(task => task.state === 'failed' && task.error?.code !== 'setup_dependency_failed');
+    const failures = setup.tasks.filter(task => task.state === 'failed' && task.error?.code !== 'setup_dependency_failed');
+    // A step marked required: false does not hold back the save; it is the
+    // failure shown only when the job failed and no required step did.
+    const failed = failures.find(task => task.required !== false) ?? (setup.state === 'failed' ? failures[0] : undefined);
     if (failed)
         return `Setting up ${project}: ${failed.name} failed: ${failed.error?.message ?? 'No error receipt'}${failed.error?.retryable ? ' · r retries once' : ''}`;
     if (setup.state === 'saving')

package/dist/claude-cloud-login.d.ts

@@ -1,9 +1,15 @@
-import type { AgentCredentialMetadata, Workspace } from '@shardflux/sdk';
+import type { AgentCredentialMetadata, CellClient, Workspace } from '@shardflux/sdk';
 import type { Ctx } from './commands.js';
 export declare function requireClaudeTerminal(ctx: Ctx): void;
 export declare function cloudClaudeLogin(ctx: Ctx): Promise<AgentCredentialMetadata | undefined>;
 /** Parse only complete provider authorize links, including the native OSC-8 link. */
 export declare function claudeLoginUrls(output: string): string[];
+/**
+ * Put the signed-in account into the workspace's ~/.claude.json, keeping every other key. The platform's credential
+ * delivery writes the same file right after the upload, so a revision conflict re-reads and merges again; a file that
+ * already holds this account is left as it is.
+ */
+export declare function mergeClaudeAccount(cell: Pick<CellClient, 'files'>, oauthAccount: unknown, signal?: AbortSignal): Promise<void>;
 /** A transient Linux profile holds the initial pair; it is removed before an agent starts. */
 export declare function loginClaudeInWorkspace(ctx: Ctx, ws: Workspace): Promise<AgentCredentialMetadata>;
 export declare function ensureCloudClaude(ctx: Ctx, ws: Workspace): Promise<void>;

package/dist/claude-cloud-login.js

@@ -1,3 +1,4 @@
+import { isDeepStrictEqual } from 'node:util';
 import { ShardfluxApiError } from '@shardflux/sdk';
 import { UsageError } from "./errors.js";
 import { openUrl } from "./browser.js";
@@ -42,6 +43,39 @@ function credentialFile(path, value, ctx) {
     ctx.addSecret(content_b64);
     return { path, mode: '0600', content_b64 };
 }
+/**
+ * Put the signed-in account into the workspace's ~/.claude.json, keeping every other key. The platform's credential
+ * delivery writes the same file right after the upload, so a revision conflict re-reads and merges again; a file that
+ * already holds this account is left as it is.
+ */
+export async function mergeClaudeAccount(cell, oauthAccount, signal) {
+    const path = '/home/user/.claude.json';
+    for (let attempt = 0; attempt < 5; attempt++) {
+        let document = {}, revision = 'absent';
+        try {
+            const current = await cell.files.readWithInfo(path);
+            document = JSON.parse(Buffer.from(current.data).toString());
+            if (!current.revision)
+                throw new UsageError('Claude account configuration has no safe content revision.');
+            revision = current.revision;
+        }
+        catch (error) {
+            if (!(error instanceof Error && 'status' in error && error.status === 404))
+                throw error;
+        }
+        if (isDeepStrictEqual(document.oauthAccount, oauthAccount))
+            return;
+        try {
+            await cell.files.patch({ path, content: JSON.stringify({ ...document, oauthAccount }), expectedRevision: revision, mode: '0600', createParents: true }, { signal });
+            return;
+        }
+        catch (error) {
+            if (!(error instanceof ShardfluxApiError && error.status === 409 && error.details?.reason === 'revision_mismatch'))
+                throw error;
+        }
+    }
+    throw new UsageError('Claude account configuration kept changing in the workspace. Run shard agents credentials login claude again.');
+}
 /** A transient Linux profile holds the initial pair; it is removed before an agent starts. */
 export async function loginClaudeInWorkspace(ctx, ws) {
     requireClaudeTerminal(ctx);
@@ -112,22 +146,10 @@ export async function loginClaudeInWorkspace(ctx, ws) {
         // persistence. An upload error requires a new cloud login, never guest refresh.
         await cell.files.remove(root, { recursive: true });
         const metadata = await api.put('claude', files, { loginId: claim.login_id });
+        complete = true; // stored: the login must not be canceled by a later local write failure
         const access = Object.fromEntries(['accessToken', 'expiresAt', 'scopes', 'subscriptionType', 'rateLimitTier'].filter(key => key in credential.claudeAiOauth).map(key => [key, credential.claudeAiOauth[key]]));
         await cell.files.write('/home/user/.claude/.credentials.json', JSON.stringify({ claudeAiOauth: access }), { mode: '0600', createParents: true });
-        let document = {}, revision = 'absent';
-        try {
-            const current = await cell.files.readWithInfo('/home/user/.claude.json');
-            document = JSON.parse(Buffer.from(current.data).toString());
-            if (!current.revision)
-                throw new UsageError('Claude account configuration has no safe content revision.');
-            revision = current.revision;
-        }
-        catch (error) {
-            if (!(error instanceof Error && 'status' in error && error.status === 404))
-                throw error;
-        }
-        await cell.files.patch({ path: '/home/user/.claude.json', content: JSON.stringify({ ...document, oauthAccount: config.oauthAccount }), expectedRevision: revision, mode: '0600', createParents: true }, { signal: ctx.signal });
-        complete = true;
+        await mergeClaudeAccount(cell, config.oauthAccount, ctx.signal);
         return metadata;
     }
     finally {

package/dist/command-center-actions.js

@@ -6,6 +6,7 @@ import { json } from "./format.js";
 import { UsageError } from "./errors.js";
 import { cellConnector, PtyOutputCursor } from "./agent-terminal.js";
 import { rememberGitAgent } from "./agent-git-commands.js";
+import { rememberLaunch } from "./agent-live.js";
 import { agentName as gitAgentName } from "./agent-git.js";
 /** L9 can register target-specific handlers after detecting the installed applications. */
 export async function availableTargets(ctx) {
@@ -43,6 +44,7 @@ export const CENTER_HANDLERS = {
         const labels = { ...source.labels, shard_project: source.labels.shard_project || source.key.split('/')[0], agent: name,
             agent_pty_name: source.labels.agent_pty_name || agentName(source.key, source.labels) };
         const caps = workspaceCaps(values);
+        const started = Date.now();
         const result = await ctx.cloud().workspaces.fork(source.id, { key, labels, ...(caps ? { caps } : {}) }, {
             agentLabel: ctx.agentLabel, wait: values.wait === false ? false : { timeoutMs: waitTimeout(values), signal: ctx.signal },
         });
@@ -54,6 +56,8 @@ export const CENTER_HANDLERS = {
             throw new Error(`Fork ${key} has no independent agent session receipt`);
         }
         await ctx.cloud().workspaces.setRetention(result.workspace.id, { delete_after_idle_days: 7 });
+        if (agent)
+            rememberLaunch(ctx, result.workspace.id, started);
         await rememberGitAgent(ctx, result.workspace, './');
         out(ctx, `Forked ${key}: operation ${result.operation.id} ${result.operation.state}\n`, { workspace: result.workspace.data, operation: result.operation, ...(agent ? { agent } : {}) });
         return 0;

package/dist/command-center.js

@@ -308,6 +308,9 @@ export async function showCenter(ctx, scope, options = {}) {
     }
 }
 export const commandCenter = async (ctx, values, [path, app]) => {
+    // `shard <path> claude|codex` names the agent: start (or reattach) it without the picker; --json starts it detached.
+    if (path && (app === 'claude' || app === 'codex'))
+        return agentAction(ctx, 'new', { ...values, path, app }, []);
     const scope = path ? projectIdentity(path) : undefined;
     if (ctx.json) {
         const data = await loadCenter(ctx);

package/dist/commands.d.ts

@@ -79,7 +79,7 @@ export declare function openVolumes(values: readonly string[]): import('@shardfl
 export declare function workspaceCaps(values: Values): Caps | undefined;
 /** `--when-idle <duration>`: whole seconds from 0 (as soon as it is idle; 0.6.1) to 3600 (the API's after_seconds bounds). */
 export declare function whenIdleSeconds(text: string): number;
-export declare function waitTimeout(values: Values): number;
+export declare function waitTimeout(values: Values, fallbackMs?: number): number;
 /**
  * `<id|key>`: a UUID is tried as an id first; anything else (or an unknown UUID) as an exact workspace key, across every
  * lifetime and purpose (sessions, drafts and test instances are hidden from the default list), preferring the live

package/dist/commands.js

@@ -17,6 +17,7 @@ import { parse as parseYaml } from 'yaml';
 import { CLI_VERSION, SECRET_NAME, UUID, parseDuration, parseEnvPairs, parsePositiveInt } from "./args.js";
 import { ExecSessionRunningError, ExecutionFailedError, ExecutionPendingError, InterruptedError, NotFoundError, UsageError } from "./errors.js";
 import { updateCheckDisabled } from "./update-check.js";
+import { withLiveAgents } from "./agent-live.js";
 import { initTemplateYaml, recipeYaml } from "./template-yaml.js";
 import { BuildTimer, buildTimingJson, buildTimingText, progressLine } from "./timing.js";
 import { timingJson } from "./timing.js";
@@ -174,9 +175,9 @@ export function whenIdleSeconds(text) {
         throw new UsageError(`--when-idle must be between 0s and 1h (got "${text}")`);
     return s;
 }
-export function waitTimeout(values) {
+export function waitTimeout(values, fallbackMs = DEFAULT_WAIT_MS) {
     const t = str(values.timeout);
-    return t === undefined ? DEFAULT_WAIT_MS : parseDuration(t, 'timeout');
+    return t === undefined ? fallbackMs : parseDuration(t, 'timeout');
 }
 /**
  * `<id|key>`: a UUID is tried as an id first; anything else (or an unknown UUID) as an exact workspace key, across every
@@ -814,6 +815,9 @@ export const KEY_HANDLERS = {
             next = page.nextCursor;
             cursor = next ?? undefined;
         } while (values.all === true && cursor);
+        // 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 });
         if (!ctx.json && next)
             ctx.io.stderr.write(`more: shard agents list --cursor ${next}\n`);

package/dist/errors.d.ts

@@ -28,6 +28,16 @@ declare class HintedError extends Error {
 export declare class UsageError extends HintedError {
     name: string;
 }
+/**
+ * A refusal `shard` detects itself, with a stable code, its facts in `details` and the next step as `hint` (exit 1),
+ * e.g. `repository_too_large` (0.13.3+) for Git history over the initial sync limit.
+ */
+export declare class CodedError extends HintedError {
+    name: string;
+    readonly code: string;
+    readonly details: Record<string, unknown> | undefined;
+    constructor(code: string, message: string, hint?: string, details?: Record<string, unknown>);
+}
 /** No usable credential: SHARDFLUX_API_KEY / the saved key, or the session, missing or malformed (never carries it). */
 export declare class AuthConfigError extends HintedError {
     name: string;

package/dist/errors.js

@@ -3,7 +3,7 @@
  * stderr with the API's error code, message and request id; the process exit
  * code tells scripts what kind of failure it was (README "Exit codes").
  */
-import { CheckoutTimeoutError, DurabilityLostError, ExecStartError, OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TemplateBuildTimeoutError, TemplateFileError, TemplateUploadError } from '@shardflux/sdk';
+import { CheckoutTimeoutError, DurabilityLostError, ExecStartError, FilesystemSaveFailedError, FilesystemSaveTimeoutError, OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TemplateBuildTimeoutError, TemplateFileError, TemplateUploadError } from '@shardflux/sdk';
 export const EXIT = {
     ok: 0,
     /** Any other failure: API refusal (conflict, quota, ...), network, protocol. */
@@ -36,6 +36,20 @@ class HintedError extends Error {
 export class UsageError extends HintedError {
     name = 'UsageError';
 }
+/**
+ * A refusal `shard` detects itself, with a stable code, its facts in `details` and the next step as `hint` (exit 1),
+ * e.g. `repository_too_large` (0.13.3+) for Git history over the initial sync limit.
+ */
+export class CodedError extends HintedError {
+    name = 'CodedError';
+    code;
+    details;
+    constructor(code, message, hint, details) {
+        super(message, hint);
+        this.code = code;
+        this.details = details;
+    }
+}
 /** No usable credential: SHARDFLUX_API_KEY / the saved key, or the session, missing or malformed (never carries it). */
 export class AuthConfigError extends HintedError {
     name = 'AuthConfigError';
@@ -180,6 +194,8 @@ export function describeError(err) {
         return { code: 'timeout', message: err.message, last_state: err.session.state, details: { session_id: err.session.session_id } };
     if (err instanceof UsageError)
         return { code: 'usage', message: err.message };
+    if (err instanceof CodedError)
+        return { code: err.code, message: err.message, retryable: false, ...(err.details ? { details: err.details } : {}) };
     if (err instanceof CheckoutTimeoutError) {
         return { code: 'timeout', message: `${err.message}; the checkout stays open (pay at its URL, then check with: shard billing status)`, last_state: err.checkout.status, details: { checkout_id: err.checkout.id, status: err.checkout.status, url: err.checkout.url } };
     }
@@ -190,6 +206,11 @@ export function describeError(err) {
         return { code: 'usage', message: err.message };
     if (err instanceof TemplateBuildTimeoutError)
         return { code: 'timeout', message: `${err.message}; follow it with: shard templates builds get ${err.build.id}`, last_state: err.build.state };
+    // machine/template save --wait (0.13.3+): the save ended without its version, or is still building at the deadline.
+    if (err instanceof FilesystemSaveFailedError)
+        return { code: 'filesystem_save_failed', message: err.message, retryable: true, details: { level: err.state.level, version: err.version } };
+    if (err instanceof FilesystemSaveTimeoutError)
+        return { code: 'timeout', message: `${err.message}; check with shard ${err.state.level}`, last_state: err.state.state, details: { level: err.state.level, version: err.version } };
     if (err instanceof TemplateUploadError)
         return { code: 'upload_failed', message: err.message, ...(err.status ? { status: err.status } : {}), details: { sha256: err.sha256, ...(err.code ? { storage_code: err.code } : {}) } };
     if (err instanceof AuthConfigError)
@@ -221,8 +242,10 @@ export function exitCodeFor(err, interrupted = false) {
         return EXIT.usage;
     if (err instanceof AuthConfigError || err instanceof MfaPendingError)
         return EXIT.auth;
-    if (err instanceof TemplateBuildTimeoutError)
+    if (err instanceof TemplateBuildTimeoutError || err instanceof FilesystemSaveTimeoutError)
         return EXIT.timeout;
+    if (err instanceof FilesystemSaveFailedError)
+        return EXIT.operationFailed;
     if (err instanceof NotFoundError)
         return EXIT.notFound;
     if (err instanceof OperationTimeoutError || err instanceof CheckoutTimeoutError || isNamed(err, 'TimeoutError'))

package/dist/filesystem-commands.d.ts

@@ -1,2 +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, 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

@@ -1,16 +1,43 @@
+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, 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)` : ''}`;
+    if (state.state === 'failed' && state.failure)
+        return `${state.level}: version ${state.failure.version} was not saved: ${state.failure.message}${current ? ` (${current} stays in use)` : ''}`;
+    if (current)
+        return `${state.level}: ${current} is ready`;
+    return state.level === 'machine' ? 'machine: nothing saved yet; change it in shard machine, then run shard machine save' : 'template: nothing saved yet; setup saves it after shard ./, or run shard template save';
+}
 function output(ctx, state) {
-    ctx.io.stdout.write(ctx.json ? JSON.stringify(state) + '\n' : `${state.level}: ${state.state}; version ${state.version}\n` +
-        (state.pending ? `Saving version ${state.pending.version}. Run shard ${state.level} --json for progress.\n` : '') +
-        (state.failure ? `${state.failure.message}\n` : '') +
-        (state.template ? `${state.template.slug}@${state.template.version}\n` : 'No saved version yet.\n'));
+    ctx.io.stdout.write(ctx.json ? JSON.stringify(state) + '\n' : `${filesystemLine(state)}\n`);
+    return 0;
+}
+/** Save output: one line naming the version being saved, or with --wait the saved version (progress on stderr). */
+async function saved(ctx, values, save, level) {
+    if (values.wait !== true && values.timeout !== undefined)
+        throw new UsageError('--timeout needs --wait');
+    const wait = values.wait === true ? { timeoutMs: waitTimeout(values, 600_000), onChange: (state) => { if (state.state === 'building' && state.pending)
+            progress(ctx, `Saving ${level} version ${state.pending.version}…`); } } : undefined;
+    const state = await save({ signal: ctx.signal, ...(wait ? { wait } : {}) });
+    if (ctx.json)
+        return output(ctx, state);
+    ctx.io.stdout.write(wait ? `${level}: version ${state.version} saved\n` : state.pending ? `${filesystemLine(state)}; shard ${level} shows when it is ready\n` : `${filesystemLine(state)}\n`);
     return 0;
 }
 const rollbackTo = (value) => {
@@ -28,34 +55,47 @@ export const FILESYSTEM_HANDLERS = {
         if (ctx.json || !ctx.io.stdin.isTTY)
             return output(ctx, state);
         const key = `machine/${state.organization_id}/v${state.version}`;
+        const existing = await cloud.workspaces.findByKey(key, { includeDeleted: false, signal: ctx.signal });
+        if (!existing)
+            progress(ctx, `Creating your machine VM (${key}); the first open takes about a minute…`);
+        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)
+        if (state.version === 0) {
+            progress(ctx, 'Syncing your Claude and Codex config into the machine…');
             await syncAgentConfig(ctx, ws);
+        }
         return AGENT_HANDLERS['agents open'](ctx, {}, [ws.key]);
     },
-    async 'machine save'(ctx) {
+    async 'machine save'(ctx, values) {
         const cloud = ctx.cloud();
         const state = await cloud.machine.get({ signal: ctx.signal });
         const ws = await cloud.workspaces.findByKey(`machine/${state.organization_id}/v${state.version}`, { signal: ctx.signal }) ??
             (state.workspace_id ? await cloud.workspaces.get(state.workspace_id) : null);
         if (!ws)
             throw new UsageError('Open shard machine, change it, then run shard machine save');
-        return output(ctx, await cloud.machine.save({ workspaceId: ws.id }, { signal: ctx.signal }));
+        return saved(ctx, values, options => cloud.machine.save({ workspaceId: ws.id }, options), 'machine');
     },
     async 'machine rollback'(ctx, values) {
         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) {
+    async 'template save'(ctx, values) {
         const { project, repoRemote } = remote();
         const ws = await ctx.cloud().workspaces.findByKey(`${project.slug}/main`, { signal: ctx.signal });
         if (!ws)
             throw new UsageError('Run shard ./ for this project before saving its template');
-        return output(ctx, await ctx.cloud().templates.saveProject({ repoRemote, workspaceId: ws.id }, { signal: ctx.signal }));
+        return saved(ctx, values, options => ctx.cloud().templates.saveProject({ repoRemote, workspaceId: ws.id }, options), 'template');
     },
     async 'template rollback'(ctx, values) {
         return output(ctx, await ctx.cloud().templates.rollbackProject({ repoRemote: remote().repoRemote, to: rollbackTo(values.to) }, { signal: ctx.signal }));

package/dist/main.js

@@ -46,7 +46,7 @@ export function abortableSleep(signal) {
 function reasonOf(info) {
     return typeof info.details?.reason === 'string' ? info.details.reason : undefined;
 }
-function hintFor(info, cred, file) {
+function hintFor(info, cred, file, command = '') {
     if (info.code === 'timeout' && info.operation_id)
         return `the operation continues server side; keep waiting with: shard operations wait ${info.operation_id}`;
     if (info.code === 'operation_failed' && info.retryable) {
@@ -56,6 +56,10 @@ function hintFor(info, cred, file) {
         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.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') {
@@ -67,6 +71,10 @@ function hintFor(info, cred, file) {
             return `the API key saved in ${file} was revoked or expired; save a new one: shard setup --new-key`;
         return undefined;
     }
+    // The edge firewall answers before the API: the contract body (edge_refused), or a bare 403 from an edge without it.
+    if (reasonOf(info) === 'edge_refused' || (info.code === 'protocol_error' && info.status === 403)) {
+        return `the edge firewall refused the request before it reached Shardflux; send the data through a command's stdin instead, for example: shard ws exec <workspace> --stdin <local-file> -- sh -c 'cat > "$1"' sh <path>`;
+    }
     if (info.code === 'step_up_required')
         return STEP_UP_HINT;
     if (info.code === 'mfa_required')
@@ -94,6 +102,9 @@ function hintFor(info, cred, file) {
     const reason = info.details?.reason;
     const index = typeof info.details?.index === 'number' ? ` #${info.details.index + 1}` : '';
     if (reason === 'revision_mismatch') {
+        // Only file commands take --expected-revision; elsewhere (a sign-in, config sync) shard chose the revision itself.
+        if (!command.startsWith('files '))
+            return 'the file changed while shard was updating it; run the same command again';
         const current = typeof info.details?.current_revision === 'string' ? info.details.current_revision : 'unknown';
         return `the file changed since that revision (current revision: ${current}); read it again, then retry with --expected-revision ${current}`;
     }
@@ -387,7 +398,7 @@ export async function run(argv, io, opts = {}) {
         }
         // An error that knows the command to continue with (an interrupted or still running execution) brings its own hint.
         const own = ownHint(err) ?? ((err instanceof InterruptedError || err instanceof ExecutionPendingError) && err.hint ? err.hint : undefined);
-        const hint = command === 'feedback' ? feedbackHint(info, own ?? hintFor(info, cred, store.file)) : (own ?? hintFor(info, cred, store.file));
+        const hint = command === 'feedback' ? feedbackHint(info, own ?? hintFor(info, cred, store.file, command)) : (own ?? hintFor(info, cred, store.file, command));
         // --timing on a failure: the failed call's timing (err.timing, else the last recorded), before the error; with
         // --json a `timing` field next to `error`.
         const timing = showTiming ? traces.forError(err) : null;

package/dist/progress.d.ts

@@ -0,0 +1,6 @@
+import type { Ctx } from './commands.js';
+/**
+ * One progress line on stderr before a step that can take a while (creating a VM, syncing config, signing in,
+ * starting an agent), so a long first run never looks hung. Silent with --json: stdout stays one document.
+ */
+export declare function progress(ctx: Pick<Ctx, 'json' | 'io'>, line: string): void;

package/dist/progress.js

@@ -0,0 +1,8 @@
+/**
+ * One progress line on stderr before a step that can take a while (creating a VM, syncing config, signing in,
+ * starting an agent), so a long first run never looks hung. Silent with --json: stdout stays one document.
+ */
+export function progress(ctx, line) {
+    if (!ctx.json)
+        ctx.io.stderr.write(`${line}\n`);
+}

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.13.2",
+  "version": "0.13.4",
   "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.0"
+    "@shardflux/sdk": "^0.18.2"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
@@ -58,7 +58,7 @@
     "typescript-eslint": "8.70.1"
   },
   "optionalDependencies": {
-    "@shardflux/menubar-darwin": "^0.1.0"
+    "@shardflux/menubar-darwin": "^0.1.1"
   },
   "scripts": {
     "build": "node scripts/build.mjs",