@shardflux/cli 0.19.0 → 0.20.0

package/dist/machine-setup.js

@@ -0,0 +1,802 @@
+/**
+ * `shard machine setup --from-this-computer` (0.20.0+): the person's own coding agent sets up their cloud machine from
+ * what is on this computer, with no question asked. The menu bar and the Linux app run it right after onboarding's
+ * Agents step (and from Settings); the terminal onboarding starts it in the background.
+ *
+ * - Runner: this computer's Claude Code when it is installed, signed in and new enough for a restricted run (`claude
+ *   -p`), else its Codex (`codex exec` in a workspace-write sandbox confined to a private temporary folder), else the
+ *   account's cloud Claude login inside the machine VM, given a non-secret inventory of this computer.
+ * - On this computer a local agent may only read (Read and Glob with the secret folders denied, and a fixed list of
+ *   read-only commands) and run `shard` against the machine VM. `SHARDFLUX_MACHINE_SETUP_VM` makes every `shard` it
+ *   runs refuse anything but exec, file writes from standard input and reads on that one VM.
+ * - When an agent stops for a reason the next would not hit, the next one runs (0.20.0: local Claude Code → local
+ *   Codex → cloud Claude); Retry is offered only when every one stopped. `attempts` records each.
+ * - Each agent is time boxed (10 minutes by default, all together twice that); shard then copies the Claude and Codex config as every machine
+ *   gets it, saves the machine and records the result per API and organization in agents.json, so it never runs twice
+ *   by accident (`--if-needed`).
+ * - Progress goes to the launchers' SHARDFLUX_PROGRESS_FILE as one-line `{phase, line}` documents.
+ */
+import { spawn } from 'node:child_process';
+import { accessSync, constants, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, chmodSync, mkdirSync, openSync, closeSync } from 'node:fs';
+import { homedir, platform as osPlatform, release, tmpdir, arch } from 'node:os';
+import { delimiter, join } from 'node:path';
+import { AgentStateStore } from "./agent-state.js";
+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 { installDirs } from "./onboarding.js";
+import { progress as stderrProgress } from "./progress.js";
+import { writeProgress } from "./seed-phases.js";
+import { parseDuration } from "./args.js";
+/** Set for the local agent's processes: the `shard` it runs only reaches this machine VM (see `setupGuard`). */
+export const SETUP_VM_ENV = 'SHARDFLUX_MACHINE_SETUP_VM';
+export const DEFAULT_AGENT_TIMEOUT_MS = 10 * 60_000;
+const SAVE_TIMEOUT_MS = 10 * 60_000;
+/**
+ * Runs argv without a shell in its own process group; past the time box (or on abort) the whole group gets SIGTERM, then
+ * SIGKILL 5 s later. Keeps the last `maxBytes` of each stream. Never throws for a non-zero exit or a missing program.
+ */
+export function runChild(argv, o) {
+    return new Promise(resolve => {
+        const max = o.maxBytes ?? 1024 * 1024;
+        let stdout = '', stderr = '', timedOut = false, partial = '', settled = false;
+        let child;
+        try {
+            child = spawn(argv[0], argv.slice(1), { cwd: o.cwd, env: o.env, stdio: ['pipe', 'pipe', 'pipe'], detached: process.platform !== 'win32' });
+        }
+        catch (error) {
+            resolve({ code: null, signal: null, stdout: '', stderr: error instanceof Error ? error.message : String(error), timedOut: false });
+            return;
+        }
+        const kill = (sig) => { try {
+            if (child.pid)
+                process.kill(process.platform === 'win32' ? child.pid : -child.pid, sig);
+        }
+        catch { /* already gone */ } };
+        let hard;
+        const stop = () => { kill('SIGTERM'); hard = setTimeout(() => kill('SIGKILL'), 5000); hard.unref?.(); };
+        const timer = setTimeout(() => { timedOut = true; stop(); }, o.timeoutMs);
+        const abort = () => stop();
+        o.signal?.addEventListener('abort', abort, { once: true });
+        child.stdout.on('data', (chunk) => {
+            const text = chunk.toString('utf8');
+            stdout = (stdout + text).slice(-max);
+            if (!o.onLine)
+                return;
+            partial += text;
+            const lines = partial.split('\n');
+            partial = lines.pop() ?? '';
+            for (const line of lines)
+                if (line.trim())
+                    o.onLine(line);
+        });
+        child.stderr.on('data', (chunk) => { stderr = (stderr + chunk.toString('utf8')).slice(-65536); });
+        child.stdin.on('error', () => undefined);
+        child.stdin.end(o.input ?? '');
+        const done = (code, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (hard && !timedOut)
+                clearTimeout(hard);
+            o.signal?.removeEventListener('abort', abort);
+            if (partial.trim() && o.onLine)
+                o.onLine(partial);
+            resolve({ code, signal, stdout, stderr, timedOut });
+        };
+        child.on('error', error => { stderr += error.message; done(null, null); });
+        child.on('close', done);
+    });
+}
+/** The first executable `name` on PATH or in the usual install folders (a menu bar app's PATH is short). */
+export function findExecutable(name, env) {
+    const home = env.HOME || homedir();
+    const dirs = [...(env.PATH ?? '').split(delimiter).filter(Boolean), ...installDirs(home), '/opt/homebrew/bin', '/usr/local/bin', '/usr/bin'];
+    for (const dir of dirs) {
+        const file = join(dir, name);
+        try {
+            accessSync(file, constants.X_OK);
+            if (statSync(file).isFile())
+                return file;
+        }
+        catch { /* next */ }
+    }
+    return undefined;
+}
+/** Flags a restricted `claude -p` run needs (checked against `claude --help` of the installed version). */
+export const CLAUDE_REQUIRED_FLAGS = ['--print', '--tools', '--allowedTools', '--disallowedTools', '--permission-mode', 'dontAsk', '--strict-mcp-config', '--setting-sources', '--output-format', 'stream-json'];
+/** Flags `codex exec` needs for a sandboxed run (checked against `codex exec --help`). */
+export const CODEX_REQUIRED_FLAGS = ['--sandbox', 'workspace-write', '--skip-git-repo-check', '--json', '--cd'];
+function firstLine(text) { return text.trim().split('\n')[0]?.trim() ?? ''; }
+export async function inspectClaude(env) {
+    const bin = findExecutable('claude', env);
+    if (!bin)
+        return undefined;
+    const opts = { env, timeoutMs: 15_000, maxBytes: 256 * 1024 };
+    const [version, help] = await Promise.all([runChild([bin, '--version'], opts), runChild([bin, '--help'], opts)]);
+    const missing = CLAUDE_REQUIRED_FLAGS.filter(flag => !help.stdout.includes(flag));
+    const agent = { app: 'claude', bin, version: firstLine(version.stdout), help: help.stdout, signedIn: false, usable: false };
+    if (version.code !== 0)
+        return { ...agent, reason: 'claude --version failed' };
+    if (missing.length)
+        return { ...agent, reason: `Claude Code ${agent.version} has no ${missing.join(', ')}; update it for a restricted run` };
+    const status = await runChild([bin, 'auth', 'status'], opts);
+    try {
+        agent.signedIn = JSON.parse(status.stdout).loggedIn === true;
+    }
+    catch {
+        agent.signedIn = false;
+    }
+    return agent.signedIn ? { ...agent, usable: true } : { ...agent, reason: 'Claude Code is not signed in on this computer' };
+}
+export async function inspectCodex(env) {
+    const bin = findExecutable('codex', env);
+    if (!bin)
+        return undefined;
+    const opts = { env, timeoutMs: 15_000, maxBytes: 256 * 1024 };
+    const [version, help] = await Promise.all([runChild([bin, '--version'], opts), runChild([bin, 'exec', '--help'], opts)]);
+    const missing = CODEX_REQUIRED_FLAGS.filter(flag => !help.stdout.includes(flag));
+    const agent = { app: 'codex', bin, version: firstLine(version.stdout), help: help.stdout, signedIn: false, usable: false };
+    if (version.code !== 0)
+        return { ...agent, reason: 'codex --version failed' };
+    if (missing.length)
+        return { ...agent, reason: `${agent.version} has no ${missing.join(', ')}; update Codex for a sandboxed run` };
+    agent.signedIn = (await runChild([bin, 'login', 'status'], opts)).code === 0;
+    return agent.signedIn ? { ...agent, usable: true } : { ...agent, reason: 'Codex is not signed in on this computer' };
+}
+/**
+ * The agents to try, in order: this computer's Claude Code, then its Codex, then the account's cloud Claude in the
+ * machine VM. When one stops for a reason the next would not hit (a usage limit, a sign-in that expired, a sandbox that
+ * keeps shard from the VM, a crash, its time box), the next one runs. `--agent` names exactly one.
+ */
+export function runnerChain(claude, codex, forced) {
+    const skipped = [claude, codex].filter((a) => !!a && !a.usable).map(a => a.reason ?? `${a.app} is not usable`);
+    if (forced === 'claude' || forced === 'codex') {
+        const agent = forced === 'claude' ? claude : codex;
+        if (!agent)
+            throw new UsageError(`${forced === 'claude' ? 'Claude Code' : 'Codex'} is not installed on this computer`);
+        if (!agent.usable)
+            throw new UsageError(agent.reason ?? `${forced} cannot run here`);
+        return { chain: [{ runner: forced, agent }], skipped: [] };
+    }
+    if (forced === 'cloud')
+        return { chain: [{ runner: 'cloud' }], skipped };
+    const local = [claude, codex].filter((a) => !!a?.usable).map(agent => ({ runner: agent.app, agent }));
+    return { chain: [...local, { runner: 'cloud' }], skipped };
+}
+/** Every agent gets its own time box, and all of them together at most twice it: the apps wait 30 minutes. */
+export const AGENT_BUDGET_FACTOR = 2;
+const MIN_ATTEMPT_MS = 60_000;
+export function attemptTimeout(perAgentMs, spentMs) {
+    const left = perAgentMs * AGENT_BUDGET_FACTOR - spentMs;
+    const box = Math.min(perAgentMs, left);
+    return box >= Math.min(MIN_ATTEMPT_MS, perAgentMs) ? box : undefined;
+}
+// ---------------------------------------------------------------------------------------------------------------------
+// Tool restrictions
+/** Read-only commands a local Claude may run on this computer (each a prefix rule). No cat: file reads go through Read, where the secret paths are denied. */
+export const READ_ONLY_COMMANDS = [
+    'brew list', 'brew leaves', 'brew info', 'brew --prefix', 'brew --version', 'ls', 'which', 'command -v', 'uname', 'sw_vers',
+    'git config --global --get', 'git config --global --list', 'git config --get', 'git config --list', 'npm ls -g', 'npm list -g', 'pnpm ls -g',
+    'pipx list', 'uv tool list', 'gem list', 'cargo install --list', 'gh extension list', 'asdf current', 'asdf list', 'mise ls', 'mise current',
+    'pyenv versions', 'rbenv versions', 'fnm list', 'volta list',
+];
+/** Tools whose `--version` (or `version`) a local Claude may print. */
+export const VERSION_TOOLS = ['node', 'npm', 'pnpm', 'yarn', 'bun', 'deno', 'python3', 'python', 'pip3', 'uv', 'go', 'rustc', 'cargo', 'ruby', 'java',
+    'php', 'dotnet', 'git', 'gh', 'docker', 'kubectl', 'terraform', 'aws', 'gcloud', 'zsh', 'bash', 'fish', 'tmux', 'nvim', 'vim', 'starship', 'mise', 'asdf'];
+/** Never read on this computer, whatever the agent decides: keys, tokens, cloud and package-registry credentials, keychains, browser and app data. */
+export const SECRET_PATHS = [
+    '~/.ssh/**', '~/.aws/**', '~/.azure/**', '~/.config/gcloud/**', '~/.kube/**', '~/.docker/**', '~/.gnupg/**', '~/.password-store/**',
+    '~/Library/**', '~/.local/share/keyrings/**', '~/.config/op/**', '~/.config/gh/**', '~/.config/hub', '~/.config/shardflux/**', '~/.netrc',
+    '~/.git-credentials', '~/.npmrc', '~/.yarnrc.yml', '~/.pypirc', '~/.gem/credentials', '~/.cargo/credentials', '~/.cargo/credentials.toml',
+    '~/.vault-token', '~/.terraform.d/**', '~/.claude.json', '~/.claude/.credentials.json', '~/.codex/auth.json', '~/.mozilla/**', '~/.config/google-chrome/**',
+    '//**/.env', '//**/.env.*', '//**/*.pem', '//**/*.key', '//**/*.p12', '//**/*.pfx', '//**/id_rsa*', '//**/id_ed25519*', '//**/id_ecdsa*', '//**/*credentials*', '//**/*secret*', '//**/*token*',
+];
+/** `claude` argv for the restricted run (the task goes on standard input). `help` is the installed version's `--help`. */
+export function claudeArgs(key, help) {
+    const allow = [
+        'Read', 'Glob',
+        ...READ_ONLY_COMMANDS.map(c => `Bash(${c}:*)`),
+        ...VERSION_TOOLS.flatMap(t => [`Bash(${t} --version)`, `Bash(${t} -V)`, `Bash(${t} version)`]),
+        `Bash(shard ws exec ${key}:*)`, `Bash(shard files write ${key}:*)`, `Bash(shard files read ${key}:*)`, `Bash(shard files ls ${key}:*)`,
+    ];
+    const deny = [...SECRET_PATHS.map(p => `Read(${p})`), 'Edit', 'Write', 'NotebookEdit', 'WebFetch', 'WebSearch'];
+    return [
+        '-p', '--output-format', 'stream-json', '--verbose',
+        // Only these built-in tools exist in the session: no Edit, Write, web or subagents; no MCP server, hook or plugin of the user's.
+        '--tools', 'Read,Glob,Bash',
+        '--permission-mode', 'dontAsk',
+        ...(help.includes('--permission-prompts') ? ['--permission-prompts', 'none'] : []),
+        '--strict-mcp-config', '--setting-sources', 'project',
+        ...(help.includes('--no-session-persistence') ? ['--no-session-persistence'] : []),
+        '--allowedTools', ...allow,
+        '--disallowedTools', ...deny,
+    ];
+}
+/** `codex exec` argv: writes only in `workDir` (and temp folders), network on for `shard`, the task on standard input. */
+export function codexArgs(workDir, help) {
+    return [
+        'exec', '--sandbox', 'workspace-write', '-c', 'sandbox_workspace_write.network_access=true',
+        '--skip-git-repo-check', '--cd', workDir, '--json',
+        ...(help.includes('--ephemeral') ? ['--ephemeral'] : []),
+        ...(help.includes('--ignore-user-config') ? ['--ignore-user-config'] : []),
+        ...(help.includes('--ignore-rules') ? ['--ignore-rules'] : []),
+        ...(help.includes('--output-last-message') ? ['--output-last-message', join(workDir, 'last-message.txt')] : []),
+        '-',
+    ];
+}
+/**
+ * While `SHARDFLUX_MACHINE_SETUP_VM` is set (the setup agent's own commands), shard only runs commands on that VM: exec,
+ * file writes from standard input, reads and listings. Returns the refusal, or undefined when the command may run.
+ */
+export function setupGuard(env, command, values, positionals) {
+    const vm = env[SETUP_VM_ENV]?.trim();
+    if (!vm)
+        return undefined;
+    const allowed = ['workspaces exec', 'files write', 'files read', 'files ls', 'files stat', 'version'];
+    if (!allowed.includes(command))
+        return `machine setup runs only shard ws exec, files write and files read on ${vm}`;
+    if (command === 'version')
+        return undefined;
+    if (positionals[0] !== vm)
+        return `machine setup runs commands only on ${vm}`;
+    if (command === 'files write' && values.from !== undefined && values.from !== '-')
+        return 'machine setup writes files only from standard input (--from -)';
+    if (command === 'files read' && values.out !== undefined)
+        return 'machine setup reads files only to standard output';
+    return undefined;
+}
+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',
+    'deno', 'go', 'cargo', 'ruby', 'java', 'mvn', 'gradle', 'dotnet', 'php', 'composer', 'elixir', 'psql', 'mysql', 'redis-cli', 'sqlite3', 'mongosh', 'ffmpeg',
+    'magick', 'protoc', 'buf', 'grpcurl', 'act', 'pre-commit', 'shellcheck', 'hadolint', 'ngrok', 'cloudflared', 'ansible', 'packer', 'vault', 'sops', 'age',
+    'watchman', 'zsh', 'fish'];
+const RUNTIMES = [['node', ['node', '--version']], ['python', ['python3', '--version']], ['go', ['go', 'version']],
+    ['rust', ['rustc', '--version']], ['ruby', ['ruby', '--version']], ['java', ['java', '-version']], ['bun', ['bun', '--version']],
+    ['deno', ['deno', '--version']], ['php', ['php', '--version']], ['dotnet', ['dotnet', '--version']]];
+const VERSION_FILES = ['.nvmrc', '.node-version', '.python-version', '.ruby-version', '.tool-versions', '.config/mise/config.toml'];
+const MANAGERS = [['nvm', '.nvm'], ['pyenv', '.pyenv'], ['rbenv', '.rbenv'], ['asdf', '.asdf'], ['volta', '.volta'], ['rustup', '.rustup'],
+    ['sdkman', '.sdkman'], ['mise', '.local/share/mise'], ['fnm', '.local/share/fnm'], ['oh-my-zsh', '.oh-my-zsh']];
+const DOTFILES = ['.zshrc', '.zprofile', '.zshenv', '.bashrc', '.bash_profile', '.profile', '.bash_aliases', '.aliases', '.functions', '.exports', '.p10k.zsh',
+    '.gitconfig', '.gitignore_global', '.gitignore', '.config/git/config', '.config/git/ignore', '.tmux.conf', '.config/tmux/tmux.conf', '.vimrc', '.config/nvim',
+    '.config/starship.toml', '.inputrc', '.editorconfig', '.config/fish/config.fish', '.curlrc', '.psqlrc', '.irbrc', '.config/direnv/direnvrc'];
+/** Agent CLIs and Shardflux itself are already in every VM. */
+const SKIP_NPM = /^(npm|corepack|shardflux|@shardflux\/.*|@anthropic-ai\/claude-code|@openai\/codex|@agentclientprotocol\/.*|@zed-industries\/.*)$/;
+function exists(path) { try {
+    statSync(path);
+    return true;
+}
+catch {
+    return false;
+} }
+/** What is on this computer, without contents that could hold a secret: names, versions, the git identity. */
+export async function collectInventory(env) {
+    const home = env.HOME || homedir();
+    const opts = { env, timeoutMs: 5000, maxBytes: 512 * 1024 };
+    const has = (name) => findExecutable(name, env);
+    const out = async (argv) => {
+        const bin = has(argv[0]);
+        if (!bin)
+            return undefined;
+        const r = await runChild([bin, ...argv.slice(1)], opts);
+        return r.code === 0 ? (r.stdout.trim() || r.stderr.trim()) : undefined;
+    };
+    const [brew, npm, name, email, ...versions] = await Promise.all([
+        out(['brew', 'leaves', '--installed-on-request']).then(v => v ?? out(['brew', 'leaves'])),
+        out(['npm', 'ls', '-g', '--depth=0', '--json']),
+        out(['git', 'config', '--global', '--get', 'user.name']),
+        out(['git', 'config', '--global', '--get', 'user.email']),
+        ...RUNTIMES.map(([, argv]) => out(argv)),
+    ]);
+    const runtimes = {};
+    RUNTIMES.forEach(([label], i) => { const v = versions[i]; if (v)
+        runtimes[label] = firstLine(v).slice(0, 80); });
+    let npmGlobals = [];
+    try {
+        npmGlobals = Object.keys(JSON.parse(npm ?? '{}').dependencies ?? {}).filter(n => !SKIP_NPM.test(n));
+    }
+    catch { /* none */ }
+    const versionFiles = {};
+    for (const file of VERSION_FILES) {
+        try {
+            const text = readFileSync(join(home, file), 'utf8');
+            if (text.length <= 2048 && !/(token|secret|password|key)\s*=/i.test(text))
+                versionFiles[file] = text.trim();
+        }
+        catch { /* absent */ }
+    }
+    const os = osPlatform() === 'darwin' ? `macOS ${release()} (${arch()})` : `${osPlatform()} ${release()} (${arch()})`;
+    return {
+        os,
+        shell: env.SHELL ? env.SHELL.split('/').pop() : null,
+        homebrew: brew ? brew.split('\n').map(s => s.trim()).filter(Boolean).slice(0, 400) : null,
+        runtimes,
+        version_files: versionFiles,
+        version_managers: MANAGERS.filter(([, dir]) => exists(join(home, dir))).map(([m]) => m),
+        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))),
+    };
+}
+/** Skills this computer's config copy brings to the machine: ~/.claude/skills and ~/.codex/skills (not Codex's bundled .system). */
+export function countSkills(home) {
+    let n = 0;
+    for (const dir of [join(home, '.claude', 'skills'), join(home, '.codex', 'skills')]) {
+        try {
+            n += readdirSync(dir, { withFileTypes: true }).filter(e => (e.isDirectory() || e.isSymbolicLink()) && !e.name.startsWith('.')).length;
+        }
+        catch { /* none */ }
+    }
+    return n;
+}
+// ---------------------------------------------------------------------------------------------------------------------
+// The task
+const SUMMARY_SHAPE = '{"tools":["gh","ripgrep"],"runtimes":["Node 24","Python 3.13"],"shell":"zsh","dotfiles":[".zshrc",".gitconfig"],"skipped":[{"item":"Docker Desktop","reason":"GUI app"}]}';
+/**
+ * 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) {
+    const reach = where === 'local'
+        ? [
+            `The machine VM's workspace key is ${key}. Run commands on it with:`,
+            `  shard ws exec ${key} -- bash -lc '<commands>'`,
+            'Write a file on it with its contents on standard input, never in arguments:',
+            `  shard files write ${key} /home/user/<path> --from - <<'EOF'`,
+            '  <contents>',
+            '  EOF',
+            '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.',
+        ]
+        : [
+            'You are running inside that VM, as `user` (passwordless sudo): install and write files directly. The user\'s computer is not reachable; the inventory below is all you know about it.',
+        ];
+    return [
+        'Set up this person\'s Shardflux cloud machine: the Ubuntu Linux VM (user `user`, home /home/user, passwordless sudo) that every new cloud coding agent of theirs starts from. Recreate their computer\'s development setup on it, so their agents find the same tools. Do it now without asking questions.',
+        '',
+        ...reach,
+        '',
+        'Their computer (collected by shard; names and versions only):',
+        JSON.stringify(inventory, null, 1),
+        '',
+        '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.',
+        '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.',
+        '5. Editor-agnostic dotfiles: .editorconfig, .inputrc, .tmux.conf, .vimrc or the nvim config, starship.toml, .psqlrc.',
+        'Do not touch Claude Code or Codex settings, skills, plugins or MCP config: shard copies them. Never read or copy secrets: ~/.ssh, ~/.aws, ~/.config/gh, ~/.netrc, ~/.npmrc, .env files, keychains, credential or token files. Do not run shard machine save: shard saves the machine when you are done. Keep to what the computer actually uses and finish within 8 minutes.',
+        '',
+        `When done, reply with only this JSON and nothing else. List only what you added or changed in the VM, by short name ("gh", "Node 24", ".tmux.conf"), never what it already had (empty lists when nothing was needed); the values here are examples: ${SUMMARY_SHAPE}`,
+    ].join('\n');
+}
+/** Short names only: "Node 24 (v24.21.0, already present)" is not something that was added, and parentheses are notes. */
+const strings = (v) => Array.isArray(v)
+    ? v.filter((x) => typeof x === 'string' && !/already (present|installed|there|on)/i.test(x)).map(s => s.replace(/\s*\([^)]*\)?\s*$/, '').trim().slice(0, 60)).filter(Boolean).slice(0, 100)
+    : [];
+/** The last JSON object in the agent's final message (a fenced block or bare), normalised. */
+export function parseSummary(text) {
+    const candidates = [];
+    for (const m of text.matchAll(/```(?:json)?\s*([\s\S]*?)```/g))
+        candidates.push(m[1]);
+    const end = text.lastIndexOf('}');
+    // Every '{' before the last '}', nearest first (lastIndexOf with a negative start would find index 0 forever).
+    for (let start = text.lastIndexOf('{', end); start >= 0 && end > start && candidates.length < 500; start = start > 0 ? text.lastIndexOf('{', start - 1) : -1)
+        candidates.push(text.slice(start, end + 1));
+    for (const candidate of candidates.reverse()) {
+        try {
+            const doc = JSON.parse(candidate.trim());
+            if (!doc || typeof doc !== 'object' || !('tools' in doc || 'runtimes' in doc))
+                continue;
+            const skipped = Array.isArray(doc.skipped) ? doc.skipped.flatMap(s => s && typeof s === 'object' && typeof s.item === 'string'
+                ? [{ item: String(s.item).slice(0, 80), reason: (typeof s.reason === 'string' ? s.reason : '').slice(0, 120) }] : []).slice(0, 50) : [];
+            return { tools: strings(doc.tools), runtimes: strings(doc.runtimes), shell: typeof doc.shell === 'string' ? doc.shell.slice(0, 20) : null, dotfiles: strings(doc.dotfiles), skipped };
+        }
+        catch { /* next candidate */ }
+    }
+    return undefined;
+}
+/** "Cloud machine ready: gh, Node 24, Python 3.13, 12 skills": what a person recognises, at most 80 characters. */
+export function readyLine(summary, skills) {
+    const items = [...(summary?.tools ?? []).slice(0, 3), ...(summary?.runtimes ?? []).slice(0, 3)];
+    const more = (summary?.tools.length ?? 0) + (summary?.runtimes.length ?? 0) - items.length;
+    const tail = [...(more > 0 ? [`${more} more`] : []), ...(skills > 0 ? [`${skills} skill${skills === 1 ? '' : 's'}`] : [])];
+    let line = `Cloud machine ready: ${[...items, ...tail].join(', ')}`;
+    while (line.length > 80 && items.length > 1) {
+        items.pop();
+        line = `Cloud machine ready: ${[...items, ...tail].join(', ')}`;
+    }
+    return items.length || tail.length ? line.slice(0, 80) : 'Cloud machine ready';
+}
+export function workingLine(runner) {
+    return runner === 'codex' ? 'Your Codex is setting up your cloud machine…' : 'Your Claude is setting up your cloud machine…';
+}
+export function failedLine(message) {
+    const short = message.replace(/\s+/g, ' ').trim();
+    const line = `Cloud machine setup stopped: ${short}`;
+    return line.length <= 80 ? line : `${line.slice(0, 79)}…`;
+}
+const recordKey = (apiUrl, org) => `${apiUrl} ${org}`;
+function alive(pid) {
+    if (!pid)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+export function readRecord(store, apiUrl, org) {
+    const all = store.read().machine_setup;
+    const rec = all && typeof all === 'object' ? all[recordKey(apiUrl, org)] : undefined;
+    if (!rec || typeof rec !== 'object')
+        return undefined;
+    // A run whose process is gone (a restart, a kill) did not finish: it reads as failed, so Retry is offered.
+    if (rec.state === 'running' && !alive(rec.pid))
+        return { ...rec, state: 'failed', error: rec.error ?? 'The setup was interrupted', line: failedLine('it was interrupted') };
+    return rec;
+}
+function writeRecord(store, apiUrl, org, rec) {
+    store.update(doc => {
+        const all = (doc.machine_setup && typeof doc.machine_setup === 'object' ? doc.machine_setup : {});
+        all[recordKey(apiUrl, org)] = rec;
+        doc.machine_setup = all;
+    });
+}
+/**
+ * Claims the run under agents.json's lock: a live run is never doubled; with `ifNeeded` a machine already set up from
+ * this computer is left alone.
+ */
+export function claimRun(store, apiUrl, org, ifNeeded, start) {
+    let result = { claimed: true };
+    store.update(doc => {
+        const all = (doc.machine_setup && typeof doc.machine_setup === 'object' ? doc.machine_setup : {});
+        const current = all[recordKey(apiUrl, org)];
+        if (current?.state === 'running' && alive(current.pid) && current.pid !== process.pid) {
+            result = { claimed: false, record: current };
+            return;
+        }
+        if (ifNeeded && current?.state === 'ready') {
+            result = { claimed: false, record: current };
+            return;
+        }
+        all[recordKey(apiUrl, org)] = start;
+        doc.machine_setup = all;
+    });
+    return result;
+}
+/**
+ * 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.
+ */
+export class ShardReach {
+    calls = 0;
+    ok = 0;
+    firstError = '';
+    record(succeeded, output = '') {
+        this.calls++;
+        if (succeeded)
+            this.ok++;
+        else if (!this.firstError)
+            this.firstError = firstLine(output).slice(0, 160);
+    }
+    check(app) {
+        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 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. */
+function workFolder(ctx) {
+    const dir = mkdtempSync(join(tmpdir(), 'shard-machine-setup-'));
+    chmodSync(dir, 0o700);
+    const bin = join(dir, 'bin');
+    mkdirSync(bin, { mode: 0o700 });
+    if (ctx.runtime?.script) {
+        writeFileSync(join(bin, 'shard'), `#!/bin/sh\nexec ${JSON.stringify(ctx.runtime.node)} ${JSON.stringify(ctx.runtime.script)} "$@"\n`, { mode: 0o700 });
+    }
+    return { dir, bin };
+}
+function agentEnv(ctx, key, bin) {
+    const env = { ...process.env, ...ctx.io.env };
+    for (const name of ['SHARDFLUX_PROGRESS_FILE', 'CLAUDECODE', 'CLAUDE_CODE_ENTRYPOINT', 'CODEX_SANDBOX', 'CODEX_THREAD_ID'])
+        delete env[name];
+    return { ...env, PATH: `${bin}${delimiter}${env.PATH ?? ''}`, SHARDFLUX_CONFIG_DIR: ctx.store.dir, SHARDFLUX_API_URL: ctx.apiUrl, SHARDFLUX_NO_UPDATE_CHECK: '1', [SETUP_VM_ENV]: key };
+}
+function timeoutText(ms) { return ms % 60_000 === 0 ? `${ms / 60_000} min` : `${Math.round(ms / 1000)} s`; }
+async function runClaudeLocal(ctx, agent, key, task, timeoutMs, log) {
+    const { dir, bin } = workFolder(ctx);
+    try {
+        let result;
+        const reach = new ShardReach(), shardCalls = new Set();
+        const run = await runChild([agent.bin, ...claudeArgs(key, agent.help)], {
+            cwd: dir, env: agentEnv(ctx, key, bin), input: task, timeoutMs, signal: ctx.signal,
+            onLine: line => {
+                try {
+                    const event = JSON.parse(line);
+                    if (event.type === 'result')
+                        result = event;
+                    for (const part of event.message?.content ?? []) {
+                        if (part.type === 'tool_use') {
+                            log(`${part.name}: ${(part.input?.command ?? part.input?.file_path ?? '').slice(0, 200)}`);
+                            if (part.name === 'Bash' && part.id && isShardCommand(part.input?.command ?? ''))
+                                shardCalls.add(part.id);
+                        }
+                        if (part.type === 'tool_result' && part.tool_use_id && shardCalls.has(part.tool_use_id)) {
+                            reach.record(part.is_error !== true, toolText(part.content));
+                            if (part.is_error === true)
+                                log(`shard failed: ${toolText(part.content).slice(0, 200)}`);
+                        }
+                    }
+                }
+                catch { /* not an event */ }
+            },
+        });
+        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)
+            throw new MachineSetupError(`Claude Code exited ${run.code ?? run.signal} without a result: ${firstLine(run.stderr) || 'no output'}`.slice(0, 300), 'shard machine setup --from-this-computer runs it again');
+        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 ?? '' };
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+async function runCodexLocal(ctx, agent, key, task, timeoutMs, log) {
+    const { dir, bin } = workFolder(ctx);
+    try {
+        let last = '', failure = '';
+        const reach = new ShardReach();
+        const run = await runChild([agent.bin, ...codexArgs(dir, agent.help)], {
+            cwd: dir, env: agentEnv(ctx, key, bin), input: task, timeoutMs, signal: ctx.signal,
+            onLine: line => {
+                try {
+                    const event = JSON.parse(line);
+                    // turn.failed carries why (a usage limit, a sign-in): the one line the person sees.
+                    if (event.type === 'turn.failed' || event.type === 'error')
+                        failure = event.error?.message ?? event.message ?? failure;
+                    if (event.item?.type === 'agent_message' && event.item.text)
+                        last = event.item.text;
+                    if (event.item?.type === 'command_execution' && event.item.command && event.type === 'item.started')
+                        log(`exec: ${event.item.command.slice(0, 200)}`);
+                    if (event.item?.type === 'command_execution' && event.type === 'item.completed' && isShardCommand(event.item.command ?? '')) {
+                        reach.record(event.item.exit_code === 0, event.item.aggregated_output ?? '');
+                        if (event.item.exit_code !== 0)
+                            log(`shard failed: ${firstLine(event.item.aggregated_output ?? '').slice(0, 200)}`);
+                    }
+                }
+                catch { /* not an event */ }
+            },
+        });
+        if (run.timedOut)
+            throw new MachineSetupError(`Codex ran past the ${timeoutText(timeoutMs)} time box`, 'shard machine setup --from-this-computer runs it again');
+        try {
+            last = readFileSync(join(dir, 'last-message.txt'), 'utf8') || last;
+        }
+        catch { /* the events had it */ }
+        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 };
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+/** The account's cloud Claude login, inside the machine VM: the same task with the inventory, full rights in the VM. */
+async function runCloud(ctx, ws, task, timeoutMs) {
+    if (!await cloudClaudeLogin(ctx))
+        throw new MachineSetupError('Your cloud Claude is not signed in', 'shard agents credentials login claude, then shard machine setup --from-this-computer');
+    const cell = ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs });
+    const file = '/tmp/shard-machine-setup/task.md';
+    try {
+        await cell.files.write(file, task, { createParents: true, mode: '0600' });
+        let run;
+        try {
+            run = await cell.exec.run(['bash', '-lc', `cd /home/user && claude -p --dangerously-skip-permissions --output-format json < ${file}`], { cwd: '/home/user', timeoutMs, maxOutputBytes: 4 * 1024 * 1024, signal: ctx.signal });
+        }
+        catch (error) {
+            if (error instanceof Error && /time(d)? ?out/i.test(error.message))
+                throw new MachineSetupError(`Claude ran past the ${timeoutText(timeoutMs)} time box`, 'shard machine setup --from-this-computer runs it again');
+            throw error;
+        }
+        let doc = {};
+        try {
+            doc = JSON.parse(run.stdout.trim().split('\n').pop() ?? '{}');
+        }
+        catch { /* below */ }
+        if (run.exitCode !== 0 || doc.is_error || !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 };
+    }
+    finally {
+        await cell.files.remove('/tmp/shard-machine-setup', { recursive: true }).catch(() => undefined);
+        cell.close();
+    }
+}
+// ---------------------------------------------------------------------------------------------------------------------
+// The command
+/** One line for the launcher (SHARDFLUX_PROGRESS_FILE) and stderr. */
+function phaseWriter(ctx) {
+    const file = ctx.io.env.SHARDFLUX_PROGRESS_FILE;
+    let last = '';
+    return (phase, line) => {
+        if (line === last)
+            return;
+        last = line;
+        if (file)
+            writeProgress(file, { phase, line });
+        stderrProgress(ctx, line);
+    };
+}
+/** A log of the agent's steps next to agents.json (machine-setup.log), for support; one line per tool call. */
+function stepLog(ctx) {
+    let fd;
+    try {
+        fd = openSync(join(ctx.store.dir, 'machine-setup.log'), 'w', 0o600);
+    }
+    catch {
+        fd = undefined;
+    }
+    return {
+        log: line => { if (fd !== undefined)
+            try {
+                writeFileSync(fd, `${new Date().toISOString()} ${line.replace(/\n/g, ' ')}\n`);
+            }
+            catch { /* best effort */ } },
+        close: () => { if (fd !== undefined)
+            try {
+                closeSync(fd);
+            }
+            catch { /* closed */ } },
+    };
+}
+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;
+    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'));
+    }
+    if (values['from-this-computer'] !== true)
+        throw new UsageError('shard machine setup needs --from-this-computer', 'shard machine setup --from-this-computer');
+    const forced = typeof values.agent === 'string' ? values.agent : undefined;
+    if (forced !== undefined && !['claude', 'codex', 'cloud'].includes(forced))
+        throw new UsageError('--agent must be claude, codex or cloud');
+    const timeoutMs = typeof values.timeout === 'string' ? parseDuration(values.timeout, 'timeout') : DEFAULT_AGENT_TIMEOUT_MS;
+    const started = Date.now();
+    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);
+    const phase = phaseWriter(ctx);
+    const steps = stepLog(ctx);
+    let runner = null;
+    const attempts = [];
+    try {
+        const env = { ...process.env, ...ctx.io.env };
+        const [claude, codex] = forced === 'cloud' ? [undefined, undefined] : await Promise.all([(deps.inspectClaude ?? inspectClaude)(env), (deps.inspectCodex ?? inspectCodex)(env)]);
+        const { chain, skipped } = runnerChain(claude, codex, forced);
+        runner = chain[0].runner;
+        for (const reason of skipped)
+            steps.log(`skipped: ${reason}`);
+        steps.log(`agents: ${chain.map(c => `${c.runner}${c.agent ? ` (${c.agent.bin}, ${c.agent.version})` : ''}`).join(' → ')}`);
+        writeRecord(store, ctx.apiUrl, org, { ...startRec, runner, line: workingLine(runner) });
+        phase('machine', workingLine(runner));
+        const inventory = await (deps.inventory ?? collectInventory)(env);
+        const { state, ws } = await (deps.open ?? ((c, s) => openMachine(c, s)))(ctx, machine);
+        // 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)}`));
+        let outcome;
+        let spent = 0;
+        for (const candidate of chain) {
+            const box = attemptTimeout(timeoutMs, spent);
+            if (box === undefined) {
+                steps.log(`agent ${candidate.runner} not tried: the setup's time is used up`);
+                break;
+            }
+            runner = candidate.runner;
+            if (attempts.length)
+                writeRecord(store, ctx.apiUrl, org, { ...startRec, runner, line: workingLine(runner), attempts });
+            phase('agent', workingLine(runner));
+            steps.log(`agent: ${runner} (time box ${timeoutText(box)})`);
+            const began = Date.now();
+            try {
+                outcome = runner === 'cloud'
+                    ? await runCloud(ctx, ws, setupTask('vm', ws.key, inventory), 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);
+                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)
+                    throw error;
+                attempts.push({ runner, ok: false, error: error.message, duration_ms: Date.now() - began });
+                steps.log(`agent ${runner} stopped: ${error.message}`);
+            }
+            finally {
+                spent += Date.now() - began;
+            }
+        }
+        if (!outcome)
+            throw new MachineSetupError(attempts.map(a => a.error).filter(Boolean).join('; ') || 'no agent could set up the machine', 'shard machine setup --from-this-computer runs it again');
+        steps.log(`result: ${outcome.text.slice(0, 2000)}`);
+        phase('save', 'Saving your cloud machine…');
+        const saved = await cloud.machine.save({ workspaceId: ws.id }, { signal: ctx.signal, wait: { timeoutMs: SAVE_TIMEOUT_MS } });
+        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 };
+        writeRecord(store, ctx.apiUrl, org, rec);
+        phase('ready', line);
+        return output(ctx, { ...rec, workspace_key: ws.key }, line);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const rec = { ...startRec, state: 'failed', runner, pid: null, finished_at: new Date().toISOString(), line: failedLine(message), attempts, error: message.slice(0, 500), duration_ms: Date.now() - started };
+        try {
+            writeRecord(store, ctx.apiUrl, org, rec);
+        }
+        catch { /* the error below still reports it */ }
+        phase('failed', rec.line);
+        throw error;
+    }
+    finally {
+        steps.close();
+    }
+}
+/**
+ * Starts `shard machine setup --from-this-computer --if-needed --json` detached (the terminal onboarding, right after
+ * its Agents step): its output goes to machine-setup.out in the config directory. Returns false without a runtime.
+ */
+export function startMachineSetupInBackground(ctx) {
+    if (!ctx.runtime?.script)
+        return false;
+    try {
+        mkdirSync(ctx.store.dir, { recursive: true, mode: 0o700 });
+        const out = openSync(join(ctx.store.dir, 'machine-setup.out'), 'w', 0o600);
+        try {
+            const child = spawn(ctx.runtime.node, [ctx.runtime.script, 'machine', 'setup', '--from-this-computer', '--if-needed', '--json'], {
+                detached: true, stdio: ['ignore', out, out],
+                env: { ...process.env, ...ctx.io.env, SHARDFLUX_CONFIG_DIR: ctx.store.dir, SHARDFLUX_API_URL: ctx.apiUrl, SHARDFLUX_NO_UPDATE_CHECK: '1' }
+            });
+            child.on('error', () => undefined);
+            child.unref();
+        }
+        finally {
+            closeSync(out);
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export const MACHINE_SETUP_HANDLERS = {
+    'machine setup': (ctx, values) => machineSetup(ctx, values),
+};