@shardflux/cli 0.19.0 → 0.20.0

package/dist/agent-config-sync.js

@@ -7,7 +7,8 @@ import { parse, stringify } from 'smol-toml';
 import { ShardfluxApiError, tarEnd, tarHeader, tarPadding } from '@shardflux/sdk';
 import { AgentStateStore } from "./agent-state.js";
 import { UsageError } from "./errors.js";
-import { collectPlugins, collectUserFiles, object, readObject, readOptional, rewritePaths } from "./agent-config-files.js";
+import { collectMemory, collectPlugins, collectUserFiles, object, readObject, readOptional, rewritePaths, vmMemoryPath } from "./agent-config-files.js";
+import { localConversations } from "./conversations.js";
 import { digest, prepareMcp } from "./agent-config-mcp.js";
 import { configIssueLines } from "./agent-config-report.js";
 const missing = (e) => e instanceof ShardfluxApiError && e.status === 404;
@@ -15,7 +16,8 @@ const parseFailure = (e) => e instanceof SyntaxError || (e instanceof Error && /
 const markerPath = '.config/shardflux/agent-config.json';
 const safePath = (path) => !path.split('/').some(p => !p || p === '.' || p === '..') &&
     (/^(?:\.claude\/(?:settings\.json|CLAUDE\.md)|\.codex\/(?:config\.toml|AGENTS\.md))$/.test(path) ||
-        /^\.claude\/(?:skills|commands|agents|output-styles|plugins)\/.+/.test(path) || /^\.codex\/(?:prompts|skills)\/.+/.test(path));
+        /^\.claude\/(?:skills|commands|agents|output-styles|plugins)\/.+/.test(path) || /^\.codex\/(?:prompts|skills)\/.+/.test(path) ||
+        /^\.claude\/projects\/[^/]+\/memory\/.+/.test(path));
 const key = (ctx, id) => `${ctx.apiUrl}:${id}`;
 export function configManifests(ctx) {
     const value = object(new AgentStateStore(ctx.store.dir).read().agent_config);
@@ -285,33 +287,51 @@ async function installPlugins(cell, plan, issues, signal) {
         if (line.startsWith('failed '))
             issues.push({ item: `plugin:${line.slice(7)}`, reason: 'could not be installed in the VM' });
 }
-export async function syncAgentConfig(ctx, ws) {
+/**
+ * `memoryOnly` (0.20.0+): just the project memory, for an account whose saved machine carries the rest. A conversation
+ * VM gets this computer's memory for its project, under the VM project folder's name (Claude keys memory by path).
+ */
+export async function syncAgentConfig(ctx, ws, opts = {}) {
     const home = ctx.io.env.HOME || homedir();
     const store = new AgentStateStore(ctx.store.dir);
     const previous = configManifests(ctx)[key(ctx, ws.id)];
     const issues = [];
-    const files = await collectUserFiles(home, issues);
-    const codexBytes = await readOptional(join(home, '.codex/config.toml'));
+    const files = opts.memoryOnly ? new Map() : await collectUserFiles(home, issues);
+    const codexBytes = opts.memoryOnly ? undefined : await readOptional(join(home, '.codex/config.toml'));
     // One file that does not parse is skipped with a reason; it never stops the rest of the sync.
     let claude;
-    try {
-        claude = await readObject(join(home, '.claude.json'));
-    }
-    catch (error) {
-        if (!parseFailure(error))
-            throw error;
-        issues.push({ item: '.claude.json', reason: 'not valid JSON; its MCP servers were not copied' });
+    if (!opts.memoryOnly) {
+        try {
+            claude = await readObject(join(home, '.claude.json'));
+        }
+        catch (error) {
+            if (!parseFailure(error))
+                throw error;
+            issues.push({ item: '.claude.json', reason: 'not valid JSON; its MCP servers were not copied' });
+        }
     }
-    const plugins = await collectPlugins(home, issues);
+    const plugins = opts.memoryOnly ? { marketplaces: [], plugins: [] } : await collectPlugins(home, issues);
     const hasPlugins = plugins.marketplaces.length > 0 || plugins.plugins.length > 0;
+    const records = Object.values(localConversations(ctx));
+    const conversation = records.find(r => r.conversation.id === ws.labels.shard_conversation) ?? records.find(r => r.conversation.workspace_id === ws.id);
+    const memory = conversation ? await collectMemory(home, conversation.folder, issues) : undefined;
     const empty = { workspace_id: ws.id, workspace_key: ws.key, copied: [], removed: [], skipped: issues, mcp: [], synced_at: null };
-    if (!files.size && !codexBytes && !hasPlugins && !Object.keys(object(claude?.mcpServers)).length && !previous)
+    if (!files.size && !memory?.files.size && !codexBytes && !hasPlugins && !Object.keys(object(claude?.mcpServers)).length && !previous)
         return empty;
     const cell = ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs });
-    const run = await cell.exec.run(['sh', '-c', 'printf "%s\\n" "$HOME"'], { signal: ctx.signal, timeoutMs: 5000, maxOutputBytes: 4096 });
-    const remoteHome = run.stdout.trim();
+    // The VM home, and the project folder its Claude keys memory by (the main checkout of the conversation's worktree).
+    const run = await cell.exec.run(['sh', '-c', 'printf "%s\\n" "$HOME"; [ -n "$1" ] && git -C "$1" rev-parse --path-format=absolute --git-common-dir 2>/dev/null || true', 'shard-config', conversation?.conversation.worktree_path ?? ''], { signal: ctx.signal, timeoutMs: 5000, maxOutputBytes: 4096 });
+    const [remoteHome = '', common = ''] = run.stdout.trim().split('\n').map(line => line.trim());
     if (run.exitCode !== 0 || !/^\/(?:[a-zA-Z0-9._-]+\/)*[a-zA-Z0-9._-]+$/.test(remoteHome) || remoteHome.split('/').some(p => p === '..' || p === '.'))
         throw new Error('agent config could not resolve the VM user home');
+    if (memory && conversation) {
+        const vmRoot = common.endsWith('/.git') ? common.slice(0, -5) : conversation.conversation.worktree_path;
+        for (const [path, file] of memory.files) {
+            const dest = vmMemoryPath(path, memory.root, vmRoot);
+            if (dest)
+                files.set(dest, file);
+        }
+    }
     // Claude settings stay the user's. sf-agent hooks are in /etc/claude-code/managed-settings.json.
     const secrets = { ...previous?.secrets, ...object(object(store.read().agent_config_secrets)[key(ctx, ws.id)]) };
     const commandCache = new Map();
@@ -432,8 +452,10 @@ export async function syncAgentConfig(ctx, ws) {
         sync_state: 'synced', synced_at, files: applied.files, claude_mcp: Object.keys(claudeMcp), claude_mcp_owned: partial.claude_mcp_owned, secrets, skipped: issues, mcp, tunnels,
         ...(pluginsHash ? { plugins_hash: pluginsHash } : {}) };
     manifest.remote_hash = digest(JSON.stringify({ files: applied.files, claude_mcp: claudeMcp, mcp, tunnels }));
-    if (marker?.workspace_id !== ws.id || marker.manifest_hash !== manifest.remote_hash)
-        await cell.files.write(`${remoteHome}/${markerPath}`, JSON.stringify({ workspace_id: ws.id, manifest_hash: manifest.remote_hash }) + '\n', { createParents: true, mode: '0600' });
+    // The marker names each file's hash (0.20.0+): the guest tells this copy's writes from the agent's own changes.
+    if (marker?.workspace_id !== ws.id || marker.manifest_hash !== manifest.remote_hash || !marker.files)
+        await cell.files.write(`${remoteHome}/${markerPath}`, JSON.stringify({ workspace_id: ws.id, manifest_hash: manifest.remote_hash,
+            files: Object.fromEntries(Object.entries(applied.files).map(([path, file]) => [path, file.hash])) }) + '\n', { createParents: true, mode: '0600' });
     store.update(doc => { const all = object(doc.agent_config); all[key(ctx, ws.id)] = manifest; doc.agent_config = all; });
     const result = { ...empty, copied: applied.copied, removed: applied.removed, skipped: issues, mcp, synced_at };
     if (!ctx.json) {
@@ -451,13 +473,13 @@ export async function syncAgentConfig(ctx, ws) {
  * output in agent-config-sync.log of the config directory), so the command that started the conversation reports the
  * start at once; without a runtime (tests, an embedding) it runs here and the returned promise settles when it ends.
  */
-export function syncAgentConfigAfterStart(ctx, ws) {
+export function syncAgentConfigAfterStart(ctx, ws, opts = {}) {
     if (ctx.runtime?.script) {
         try {
             mkdirSync(ctx.store.dir, { recursive: true, mode: 0o700 });
             const log = openSync(join(ctx.store.dir, 'agent-config-sync.log'), 'a', 0o600);
             try {
-                const child = spawn(ctx.runtime.node, [ctx.runtime.script, 'agents', 'config-sync', ws.id], {
+                const child = spawn(ctx.runtime.node, [ctx.runtime.script, 'agents', 'config-sync', ws.id, ...(opts.memoryOnly ? ['--memory-only'] : [])], {
                     detached: true, stdio: ['ignore', log, log],
                     env: { ...process.env, ...ctx.io.env, SHARDFLUX_CONFIG_DIR: ctx.store.dir, SHARDFLUX_API_URL: ctx.apiUrl, SHARDFLUX_NO_UPDATE_CHECK: '1' }
                 });
@@ -471,7 +493,7 @@ export function syncAgentConfigAfterStart(ctx, ws) {
         }
         catch { /* runs in this process below */ }
     }
-    return syncAgentConfig(ctx, ws).then(() => undefined, (error) => {
+    return syncAgentConfig(ctx, ws, opts).then(() => undefined, (error) => {
         ctx.io.stderr.write(`Agent config not copied to ${ws.key}: ${error instanceof Error ? error.message : String(error)}\n`);
     });
 }
@@ -501,41 +523,13 @@ export async function startAgentConfigTunnels(ctx, ws) {
 }
 export const AGENT_CONFIG_HANDLERS = {
     /** The detached copy syncAgentConfigAfterStart starts; one line per run in agent-config-sync.log. */
-    async 'agents config-sync'(ctx, _values, [id]) {
+    async 'agents config-sync'(ctx, values, [id]) {
         const ws = await ctx.cloud().workspaces.get(id);
         const started = Date.now();
-        const result = await syncAgentConfig({ ...ctx, json: true }, ws);
+        const result = await syncAgentConfig({ ...ctx, json: true }, ws, { memoryOnly: values['memory-only'] === true });
         ctx.io.stderr.write(`${new Date().toISOString()} ${ws.key}: ${result.copied.length} copied, ${result.removed.length} removed, ${result.skipped.length} skipped in ${Date.now() - started} ms\n`);
         for (const line of configIssueLines(result.skipped))
             ctx.io.stderr.write(`  ${line}\n`);
         return 0;
     },
-    'agents config status'(ctx, values) {
-        const workspace = typeof values.workspace === 'string' ? values.workspace : undefined;
-        const manifests = Object.values(configManifests(ctx)).filter(m => m.api_url === ctx.apiUrl && (!workspace || m.workspace_id === workspace || m.workspace_key === workspace));
-        const report = { observation: 'last sync on this machine', workspaces: manifests };
-        ctx.io.stdout.write(ctx.json ? JSON.stringify(report, null, 2) + '\n' : manifests.length ? manifests.map(m => `${m.workspace_key}: ${Object.keys(m.files).length} files; ${m.sync_state === 'synced' ? `last sync ${m.synced_at}` : 'sync interrupted; run config sync again'}\n` +
-            m.skipped.map(s => `  skipped ${s.item}: ${s.reason}\n`).join('') +
-            m.mcp.map(s => `  MCP ${s.app}/${s.name}: ${s.status}${s.reason ? ` (${s.reason})` : ''}\n`).join('')).join('') : 'No agent config has been synced on this machine.\n');
-        return Promise.resolve(0);
-    },
-    async 'agents config sync'(ctx, values) {
-        const workspace = typeof values.workspace === 'string' ? values.workspace : undefined;
-        const cloud = ctx.cloud();
-        const targets = [];
-        if (workspace) {
-            const ws = await cloud.workspaces.findByKey(workspace, { includeDeleted: false, signal: ctx.signal });
-            targets.push(ws ?? await cloud.workspaces.get(workspace));
-        }
-        else
-            for await (const ws of cloud.workspaces.listAll()) {
-                if (ws.labels.shard_project && ws.mode === 'processful')
-                    targets.push(ws);
-            }
-        const results = [];
-        for (const ws of targets)
-            results.push(await syncAgentConfig(ctx, ws));
-        ctx.io.stdout.write(ctx.json ? JSON.stringify({ workspaces: results }, null, 2) + '\n' : results.length ? results.map(r => r.synced_at === null ? `${r.workspace_key}: no local agent config found\n` : `${r.workspace_key}: ${r.copied.length} files copied, ${r.removed.length} removed\n`).join('') : 'No agent workspaces found.\n');
-        return 0;
-    },
 };

package/dist/agent-setup.js

@@ -54,8 +54,8 @@ export function setupGuide(state) {
             {
                 step: 'Build the machine',
                 ask: 'What should every cloud agent start with? Languages and runtimes, CLIs and tools, dotfiles and shell, secrets and credentials, editor and agent config.',
-                commands: ['shard machine open --json', "shard ws exec <key> -- bash -lc '<install commands>'", 'shard files write <key> <path> --from -', 'shard machine save --wait --json'],
-                note: 'machine open prints the machine VM’s workspace key. Install with ws exec, write dotfiles and secret files with files write (contents on standard input, never in arguments), then save: every new conversation starts from it.',
+                commands: ['shard machine setup --from-this-computer --json', 'shard machine open --json', "shard ws exec <key> -- bash -lc '<install commands>'", 'shard files write <key> <path> --from -', 'shard machine save --wait --json'],
+                note: 'machine setup recreates this computer’s tools, runtimes, shell, git identity and dotfiles on the machine with this computer’s Claude Code or Codex, and saves it (0.20.0+). For the rest: machine open prints the machine VM’s workspace key. Install with ws exec, write dotfiles and secret files with files write (contents on standard input, never in arguments), then save: every new conversation starts from it.',
             },
             {
                 step: 'Set up the project',

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.19.0";
+export declare const CLI_VERSION = "0.20.0";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;

package/dist/args.js

@@ -13,7 +13,7 @@ import { parseArgs } from 'node:util';
 import { ACCOUNT_COMMANDS } from "./account-args.js";
 import { UsageError } from "./errors.js";
 import { DEFAULT_CHOICE, MODEL_CHOICES } from "./agent-models.js";
-export const CLI_VERSION = '0.19.0';
+export const CLI_VERSION = '0.20.0';
 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).' },
@@ -176,6 +176,15 @@ const KEY_COMMANDS = [
     { path: ['machine', 'open'], summary: 'Create or resume your machine VM without attaching to it, and print its workspace key (0.17.1+)', positionals: [], options: {},
         description: 'For an agent building your machine from a terminal it does not attach to: install with "shard ws exec <key> -- bash -lc ...", write dotfiles and secret files with "shard files write <key> <path> --from -" (contents on standard input), then "shard machine save --wait". The first open copies your Claude and Codex settings into it, as "shard machine" does.',
         examples: ['shard machine open --json', "shard ws exec \"$(shard machine open)\" -- bash -lc 'sudo apt-get install -y ripgrep'", 'shard machine save --wait --json'] },
+    { path: ['machine', 'setup'], summary: 'Let your own Claude Code or Codex set up your machine from this computer (0.20.0+)', positionals: [], options: {
+            'from-this-computer': { type: 'boolean', description: 'Recreate this computer’s development setup on your machine: its CLIs and tools, language runtimes, shell config and aliases, git identity and dotfiles. Required.' },
+            'if-needed': { type: 'boolean', description: 'Only when your machine was never set up from this computer (what the apps run after onboarding).' },
+            status: { type: 'boolean', description: 'Show the last setup from this computer instead of running one.' },
+            agent: { type: 'string', value: '<claude|codex|cloud>', description: 'Which agent sets it up (default: this computer’s Claude Code, else its Codex, else your cloud Claude in the machine VM).' },
+            timeout: { type: 'string', value: '<duration>', description: 'Time box for the agent (default 10m).' },
+        },
+        description: 'Your own coding agent does it, on your subscription, with no question asked: shard starts this computer’s Claude Code (claude -p) or Codex (codex exec) with a fixed task. On this computer it may only read (no edits, no ~/.ssh, keychain, token or credential files) and run shard on your machine VM; files go over standard input. Without Claude Code or Codex here, your cloud Claude does it inside the machine VM from a list of this computer’s tools and versions. Then shard copies your Claude and Codex config and saves the machine (shard machine save --wait). Progress goes to stderr, one line per step.',
+        examples: ['shard machine setup --from-this-computer', 'shard machine setup --from-this-computer --if-needed --json', 'shard machine setup --status --json'] },
     { path: ['agents', 'list'], summary: 'List coding agent sessions.', positionals: [], options: {
             ...PAGE,
             state: { type: 'string', value: '<working|waiting|exited>', description: 'Agent state filter.' },
@@ -1299,7 +1308,7 @@ const AGENT_COMMANDS = [
         } },
     { path: ['agents', 'fork'], summary: 'Fork an agent’s memory and disk', positionals: [{ name: 'agent', required: true }, { name: 'name', required: true }], options: WAIT },
     { path: ['agents', 'park'], summary: 'Suspend an agent when idle', positionals: [{ name: 'agent', required: true }], options: { 'when-idle': { type: 'string', value: '<duration>', description: 'Idle grace before suspend (default 1s).' } } },
-    { path: ['agents', 'config-sync'], hidden: true, summary: 'Copy this computer’s Claude and Codex config into a conversation VM (started in the background after a start, 0.19.0+)', positionals: [{ name: 'workspace', required: true }], options: {} },
+    { path: ['agents', 'config-sync'], hidden: true, summary: 'Copy this computer’s Claude and Codex config into a conversation VM (started in the background after a start, 0.19.0+)', positionals: [{ name: 'workspace', required: true }], options: { 'memory-only': { type: 'boolean', description: 'Only the project memory (an account with a saved machine, 0.20.0+).' } } },
     { path: ['agents', 'logs'], summary: 'Tail an agent’s terminal from its output offset: a conversation id (0.18.1+) or an agent workspace key', positionals: [{ name: 'agent', required: true }], options: {
             app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default remembered choice; a conversation uses its own).' },
             offset: { type: 'string', value: '<bytes>', description: 'Read from this output byte offset (default last 64 KiB).' },

package/dist/conversation-terminal.js

@@ -24,6 +24,8 @@ import { openClaudeDesktopSession, remoteControlUrl } from "./agent-target-comma
 import { openUrl } from "./browser.js";
 import { out } from "./commands.js";
 import { progress } from "./progress.js";
+/** This computer's agent config, copied after the start; with a saved machine (which carries it) just the project memory. */
+const afterStartConfig = (ctx, ws, machine) => () => syncAgentConfigAfterStart(ctx, ws, machine ? { memoryOnly: true } : {});
 /** Every terminal entry point uses the durable conversation's native harness, worktree and session. */
 export async function conversationTerminal(ctx, ws, c, project, values, afterStart) {
     if (c.route === 'codex-cloud')
@@ -48,7 +50,7 @@ export async function reopenConversation(ctx, c, values) {
         progress(ctx, 'Restored');
         return { conversation: restored, ws };
     }
-    const afterStart = (await savedMachine(ctx))?.template ? undefined : () => syncAgentConfigAfterStart(ctx, ws);
+    const afterStart = afterStartConfig(ctx, ws, !!(await savedMachine(ctx))?.template);
     const quiet = { ...ctx, io: { ...ctx.io, stdout: { write: () => true } } };
     await conversationTerminal(quiet, ws, restored, ws.labels.repo_remote || ws.labels.shard_project || ws.key, { ...values, detach: true }, afterStart);
     return { conversation: restored, ws };
@@ -148,7 +150,7 @@ async function startConversation(ctx, values, [path = './', explicit], openIn) {
     if (!signedIn)
         await loginClaudeInWorkspace(ctx, ws);
     // Without a saved machine the laptop's Claude and Codex config is copied in, after the agent has its first prompt.
-    const afterStart = (await savedMachine(ctx))?.template ? undefined : () => syncAgentConfigAfterStart(ctx, ws);
+    const afterStart = afterStartConfig(ctx, ws, !!(await savedMachine(ctx))?.template);
     await ensureMenubar(ctx.store.dir, ctx.apiUrl, new MenubarManager({ home: ctx.io.env.HOME, signal: ctx.signal }));
     if (openIn) {
         // The agent starts detached in its VM; the conversation then opens in Claude Desktop or claude.ai (Remote Control).

package/dist/conversations.d.ts

@@ -49,6 +49,10 @@ export interface Conversation {
     } | null;
     /** Why it needs you, while `state` is needs_you; null otherwise (0.18.0+, APIs that return it). */
     question?: string | null;
+    /** The user who started it (0.20.0+, APIs that record it); null when unknown. */
+    started_by?: {
+        user_id: string;
+    } | null;
 }
 export interface LocalConversation {
     api_url: string;

package/dist/device-helper.js

@@ -12,6 +12,7 @@ import { writePrivateFile } from "./credentials.js";
 import { conversationClient } from "./conversation-commands.js";
 import { Readable } from 'node:stream';
 import { runWorktreeTwin } from "./worktree-twin-engine.js";
+import { AGENT_CONFIG_POLL_MS, AgentConfigReturnState, returnAgentConfigsOnce } from "./agent-config-return.js";
 import { askLocalDeviceApproval } from "./device-approvals.js";
 /** The menu bar owns this helper and its stdin; VM data can request actions but cannot answer approvals. */
 export async function runDeviceHelper(ctx, options = {}) {
@@ -55,7 +56,7 @@ export async function runDeviceHelper(ctx, options = {}) {
             ctx.io.stdout.write(JSON.stringify({ type: 'approval_resolved', request_id: approval.request_id }) + '\n'); });
     };
     const working = new Map();
-    const mirrored = new ConversationMirrorState(), files = new FilesMirrorState();
+    const mirrored = new ConversationMirrorState(), files = new FilesMirrorState(), config = new AgentConfigReturnState();
     const deviceFile = join(ctx.store.dir, 'device-id');
     let deviceId;
     try {
@@ -67,11 +68,35 @@ export async function runDeviceHelper(ctx, options = {}) {
     }
     const executor = new DeviceExecutor(ctx, ask, deviceId);
     const report = (e) => { ctx.io.stderr.write(`Device bridge: ${e instanceof Error ? e.message : String(e)}\n`); };
-    let mirroring, twin;
+    let mirroring, twin, returning;
     try {
         return await withTargetLock(join(ctx.store.dir, 'device-helper-lock'), async () => {
             // Finished conversations land in their local branches (worktree-twin-engine.ts); its own loop and backoff.
             twin = runWorktreeTwin(ctx, deviceId, signal).catch(report);
+            // Skills, memories and CLAUDE.md lines saved in the cloud come back on their own cadence (agent-config-return.ts):
+            // never behind a files-mirror pass, which takes minutes for an account with hundreds of conversations.
+            returning = (async () => {
+                let failures = 0;
+                const reported = new Set();
+                while (!signal.aborted) {
+                    let wait = AGENT_CONFIG_POLL_MS;
+                    try {
+                        await returnAgentConfigsOnce(ctx, config);
+                        failures = 0;
+                    }
+                    catch (e) {
+                        if (signal.aborted)
+                            break;
+                        wait = Math.min(300_000, 5000 * 2 ** Math.min(failures++, 6));
+                        const message = e instanceof Error ? e.message : String(e);
+                        if (!conversationsUnavailable(e) && !reported.has(message)) {
+                            reported.add(message);
+                            ctx.io.stderr.write(`Agent config: ${message} (retrying in ${wait / 1000}s).\n`);
+                        }
+                    }
+                    await delay(wait, undefined, { signal }).catch(() => undefined);
+                }
+            })();
             // A slow or failed transcript copy must not delay heartbeats, request polling or approvals.
             mirroring = (async () => {
                 let failures = 0;
@@ -133,6 +158,8 @@ export async function runDeviceHelper(ctx, options = {}) {
         await executor.close();
         await Promise.all([...working.values()]);
         await mirroring;
+        await returning;
+        await config.folding;
         await twin;
         await input.catch(() => undefined);
     }

package/dist/errors.d.ts

@@ -62,6 +62,13 @@ export declare class AuthConfigError extends HintedError {
 export declare class NotFoundError extends HintedError {
     name: string;
 }
+/**
+ * `shard machine setup --from-this-computer` (0.20.0+) ran but did not save a machine: the agent failed, ran past its
+ * time box, or the save failed. Retryable: the same command runs it again (exit 6).
+ */
+export declare class MachineSetupError extends HintedError {
+    name: string;
+}
 /** `auth login` of a two-factor account without a code: the pending sign-in is saved; `shard auth mfa` completes it (exit 4). */
 export declare class MfaPendingError extends HintedError {
     name: string;

package/dist/errors.js

@@ -87,6 +87,13 @@ export class AuthConfigError extends HintedError {
 export class NotFoundError extends HintedError {
     name = 'NotFoundError';
 }
+/**
+ * `shard machine setup --from-this-computer` (0.20.0+) ran but did not save a machine: the agent failed, ran past its
+ * time box, or the save failed. Retryable: the same command runs it again (exit 6).
+ */
+export class MachineSetupError extends HintedError {
+    name = 'MachineSetupError';
+}
 /** `auth login` of a two-factor account without a code: the pending sign-in is saved; `shard auth mfa` completes it (exit 4). */
 export class MfaPendingError extends HintedError {
     name = 'MfaPendingError';
@@ -265,6 +272,8 @@ export function describeError(err) {
         return { code: 'mfa_required', message: err.message };
     if (err instanceof NotFoundError)
         return { code: 'not_found', message: err.message };
+    if (err instanceof MachineSetupError)
+        return { code: 'machine_setup_failed', message: err.message, retryable: true };
     if (err instanceof InterruptedError) {
         return { code: 'interrupted', message: err.message, ...(err.operationId ? { operation_id: err.operationId } : {}), ...(err.executionId ? { execution_id: err.executionId } : {}) };
     }
@@ -294,6 +303,8 @@ export function exitCodeFor(err, interrupted = false) {
         return EXIT.operationFailed;
     if (err instanceof NotFoundError)
         return EXIT.notFound;
+    if (err instanceof MachineSetupError)
+        return EXIT.operationFailed;
     if (err instanceof OperationTimeoutError || err instanceof CheckoutTimeoutError || isNamed(err, 'TimeoutError'))
         return EXIT.timeout;
     if (err instanceof OperationFailedError || err instanceof DurabilityLostError || err instanceof ExecutionFailedError || err instanceof CheckoutEndedError)

package/dist/filesystem-commands.d.ts

@@ -4,6 +4,18 @@ import type { Ctx, Handler } from './commands.js';
 export declare function filesystemLine(state: AgentFilesystem & {
     cache_scope?: string;
 }): string;
+/** A build's place while it waits for one of the plan's build slots (API: TemplateBuild.queue). */
+export interface BuildQueue {
+    position: number;
+    slots: number;
+    expected_wait_seconds: number;
+}
+/** "about 40 s" / "about 3 min": the queue's estimate, rounded the way people say it. */
+export declare function aboutWait(seconds: number): string;
+/** One line for a build that waits for a slot (0.20.0+): "Queued behind 3 builds · about 40 s" (running ones + those ahead). */
+export declare function queueLine(q: BuildQueue): string;
+/** How often a waited save reads its build's place in the queue. */
+export declare const QUEUE_POLL_MS = 2500;
 /** The save's one line about software under the home that went into the image (0.18.0+), as the in-VM shard says it. */
 export declare function movedLine(state: AgentFilesystem, level: 'machine' | 'template'): string;
 /** Creates or resumes the machine VM of the saved machine version; the first one gets this computer's agent config. */

package/dist/filesystem-commands.js

@@ -29,17 +29,79 @@ function output(ctx, state) {
     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). */
+/** "about 40 s" / "about 3 min": the queue's estimate, rounded the way people say it. */
+export function aboutWait(seconds) {
+    if (seconds < 90)
+        return `about ${Math.max(10, Math.round(seconds / 10) * 10)} s`;
+    return `about ${Math.round(seconds / 60)} min`;
+}
+/** One line for a build that waits for a slot (0.20.0+): "Queued behind 3 builds · about 40 s" (running ones + those ahead). */
+export function queueLine(q) {
+    const behind = q.slots + q.position - 1;
+    return `Queued behind ${behind} build${behind === 1 ? '' : 's'} · ${aboutWait(q.expected_wait_seconds)}`;
+}
+/** How often a waited save reads its build's place in the queue. */
+export const QUEUE_POLL_MS = 2_500;
+/** The pending build's queue, if it waits for a slot; nothing when the API predates it or the build cannot be read. */
+async function pendingQueue(ctx, state) {
+    if (!state.pending)
+        return undefined;
+    try {
+        const build = await ctx.cloud().templates.builds.get(state.organization_id, state.pending.build_id);
+        return build.queue ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Save output: one line naming the version being saved (and its place in the queue when the plan's build slots are in
+ * use, 0.20.0+), or with --wait the saved version (progress on stderr, the queue line updating while it waits).
+ */
 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 } : {}) });
+    const stop = new AbortController();
+    let watcher;
+    // While the save waits, its build's place in the queue: one line each time it changes.
+    const watchQueue = (state) => {
+        if (watcher || !state.pending)
+            return;
+        watcher = (async () => {
+            let last = '';
+            while (!stop.signal.aborted) {
+                const q = await pendingQueue(ctx, state);
+                const line = q ? queueLine(q) : '';
+                if (line && line !== last && !stop.signal.aborted)
+                    progress(ctx, line);
+                last = line;
+                await new Promise(resolve => {
+                    const timer = setTimeout(resolve, QUEUE_POLL_MS);
+                    stop.signal.addEventListener('abort', () => { clearTimeout(timer); resolve(); }, { once: true });
+                });
+            }
+        })();
+    };
+    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}…`);
+                watchQueue(state);
+            }
+        } } : undefined;
+    let state;
+    try {
+        state = await save({ signal: ctx.signal, ...(wait ? { wait } : {}) });
+    }
+    finally {
+        stop.abort();
+        await watcher;
+    }
+    const queue = wait ? undefined : await pendingQueue(ctx, state);
     if (ctx.json)
-        return output(ctx, state);
+        return output(ctx, queue ? { ...state, queue } : state);
     const moved = movedLine(state, level);
-    ctx.io.stdout.write(wait ? `${level}: version ${state.version} saved${moved}\n` : state.pending ? `${filesystemLine(state)}; shard ${level} shows when it is ready${moved}\n` : `${filesystemLine(state)}${moved}\n`);
+    const queued = queue ? `; ${queueLine(queue).replace(/^Q/, 'q')}` : '';
+    ctx.io.stdout.write(wait ? `${level}: version ${state.version} saved${moved}\n` : state.pending ? `${filesystemLine(state)}${queued}; shard ${level} shows when it is ready${moved}\n` : `${filesystemLine(state)}${moved}\n`);
     return 0;
 }
 /** The save's one line about software under the home that went into the image (0.18.0+), as the in-VM shard says it. */

package/dist/handlers.js

@@ -23,4 +23,5 @@ import { CLI_PROXY_HANDLERS } from "./cli-proxy.js";
 import { ACCOUNT_POOL_HANDLERS } from "./account-pool.js";
 import { MOVE_HANDLERS } from "./move.js";
 import { AGENT_CONFIG_HANDLERS } from "./agent-config-sync.js";
-export const HANDLERS = { ...MOVE_HANDLERS, ...DEVICE_HANDLERS, ...CODEX_CLOUD_HANDLERS, ...CLI_PROXY_HANDLERS, ...THREAD_HANDLERS, ...CONVERSATION_HANDLERS, ...LOCAL_CONVERSATION_HANDLERS, ...TWIN_HANDLERS, ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...ACCOUNT_POOL_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS, ...UPDATE_HANDLERS, 'agents config-sync': AGENT_CONFIG_HANDLERS['agents config-sync'] };
+import { MACHINE_SETUP_HANDLERS } from "./machine-setup.js";
+export const HANDLERS = { ...MOVE_HANDLERS, ...DEVICE_HANDLERS, ...CODEX_CLOUD_HANDLERS, ...CLI_PROXY_HANDLERS, ...THREAD_HANDLERS, ...CONVERSATION_HANDLERS, ...LOCAL_CONVERSATION_HANDLERS, ...TWIN_HANDLERS, ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...ACCOUNT_POOL_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS, ...MACHINE_SETUP_HANDLERS, ...UPDATE_HANDLERS, ...AGENT_CONFIG_HANDLERS };

package/dist/initial-prompt.d.ts

@@ -22,5 +22,18 @@ export declare function readInitialImages(ctx: Ctx, values: Values, prompt: stri
 export declare function promptWithImages(prompt: string, images: readonly InitialImage[]): string;
 /** Writes the images into the conversation VM before the first message refers to them. */
 export declare function uploadInitialImages(cell: Pick<CellClient, 'files'>, images: readonly InitialImage[], signal?: AbortSignal): Promise<void>;
-/** Wait for the native terminal to enable paste before submitting one first turn. No blind timing or input replay. */
-export declare function submitInitialPrompt(connect: (signal: AbortSignal) => Promise<TerminalConnection>, prompt: string, workspaceKey: string, signal: AbortSignal, app?: 'claude' | 'codex', write?: (bytes: Uint8Array) => Promise<unknown>): Promise<void>;
+/** The conversation inbox takes a message of at most this many characters (the API's text limit). */
+export declare const INBOX_MAX_CHARS = 65536;
+/**
+ * The harness's input box is the last thing that drew its prompt glyph (0.19.1+). Claude Code and Codex draw the same
+ * glyph as the selection cursor of their dialogs ("❯ 1. Yes, I trust this folder"); a prompt pasted there would pick
+ * options. The guest's own first-message delivery reads the screen the same way (coding 39+).
+ */
+export declare function inputBoxReady(tail: string, glyph: string): boolean;
+/**
+ * Wait for the native terminal to enable paste before submitting one first turn. No blind timing or input replay.
+ * When nothing was typed yet and the terminal never became ready, `queue` hands the prompt to the conversation's guest
+ * (its inbox, which waits for the harness and retries Enter) and the result is `queued` (0.19.1+): a first prompt is
+ * never lost to a slow start.
+ */
+export declare function submitInitialPrompt(connect: (signal: AbortSignal) => Promise<TerminalConnection>, prompt: string, workspaceKey: string, signal: AbortSignal, app?: 'claude' | 'codex', write?: (bytes: Uint8Array) => Promise<unknown>, queue?: () => Promise<unknown>): Promise<'submitted' | 'queued'>;

package/dist/initial-prompt.js

@@ -137,8 +137,26 @@ export async function uploadInitialImages(cell, images, signal) {
         await cell.files.write(image.path, image.data, { mode: '0600', createParents: true });
     }
 }
-/** Wait for the native terminal to enable paste before submitting one first turn. No blind timing or input replay. */
-export async function submitInitialPrompt(connect, prompt, workspaceKey, signal, app = 'claude', write) {
+/** The conversation inbox takes a message of at most this many characters (the API's text limit). */
+export const INBOX_MAX_CHARS = 65536;
+/**
+ * The harness's input box is the last thing that drew its prompt glyph (0.19.1+). Claude Code and Codex draw the same
+ * glyph as the selection cursor of their dialogs ("❯ 1. Yes, I trust this folder"); a prompt pasted there would pick
+ * options. The guest's own first-message delivery reads the screen the same way (coding 39+).
+ */
+export function inputBoxReady(tail, glyph) {
+    // eslint-disable-next-line no-control-regex -- Native terminal escapes are removed before reading the screen text.
+    const plain = tail.replace(/\x1b\[[0-?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, ' ');
+    const at = plain.lastIndexOf(glyph);
+    return at >= 0 && !/^[\s\u00a0]*\d+\./.test(plain.slice(at + glyph.length));
+}
+/**
+ * Wait for the native terminal to enable paste before submitting one first turn. No blind timing or input replay.
+ * When nothing was typed yet and the terminal never became ready, `queue` hands the prompt to the conversation's guest
+ * (its inbox, which waits for the harness and retries Enter) and the result is `queued` (0.19.1+): a first prompt is
+ * never lost to a slow start.
+ */
+export async function submitInitialPrompt(connect, prompt, workspaceKey, signal, app = 'claude', write, queue) {
     const bounded = AbortSignal.any([signal, AbortSignal.timeout(20000)]);
     let connection;
     let sent = false, pasted = false;
@@ -159,7 +177,7 @@ export async function submitInitialPrompt(connect, prompt, workspaceKey, signal,
             // eslint-disable-next-line no-control-regex -- Strip native terminal ANSI before matching prompt echo.
             const plain = tail.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '').replace(/\s/g, '');
             if (sent && bytes.length)
-                return;
+                return 'submitted';
             if (pasted) {
                 // A long prompt overflows the input box: a 24-row terminal shows only its end, so either end confirms the paste.
                 const compact = prompt.replace(/\s/g, '');
@@ -174,7 +192,7 @@ export async function submitInitialPrompt(connect, prompt, workspaceKey, signal,
                 tail = '';
                 continue;
             }
-            const ready = app === 'claude' ? tail.includes('❯') : tail.includes('›');
+            const ready = inputBoxReady(tail, app === 'claude' ? '❯' : '›');
             if (!ready || !pasteEnabled)
                 continue;
             const paste = Buffer.from(`\x1b[200~${prompt}\x1b[201~`);
@@ -188,6 +206,13 @@ export async function submitInitialPrompt(connect, prompt, workspaceKey, signal,
         throw new Error('The agent terminal closed before accepting a prompt.');
     }
     catch {
+        if (!pasted && queue && !signal.aborted && prompt.length <= INBOX_MAX_CHARS) {
+            try {
+                await queue();
+                return 'queued';
+            }
+            catch { /* reported as not submitted below */ }
+        }
         throw new CodedError('initial_prompt_failed', `Created ${workspaceKey}, but the initial prompt ${sent ? 'could not be confirmed' : 'was not submitted'}. Open that conversation before starting another.`, undefined, { workspace_key: workspaceKey, submitted: sent });
     }
     finally {