@shardflux/cli 0.11.1 → 0.13.1

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.11.1';
+export const CLI_VERSION = '0.13.1';
 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).' },
@@ -67,6 +67,7 @@ const SLUG = { name: 'slug', required: true };
 /** The screenshot after a computer action or batch (0.10.0+). */
 const COMPUTER_LOOK = {
     screenshot: { type: 'string', value: '<file>', description: 'Take a screenshot after it and write it here.' },
+    'pixel-predicate': { type: 'string', value: '<json>', description: 'Exact caller-supplied RGBA region hashes on the full PNG; requires --screenshot and no --settle.' },
     settle: { type: 'string', value: '<ms>', description: 'Wait this long before that screenshot when the screen may change (0-10000, default 250).' },
     format: { type: 'string', value: '<png|jpeg>', description: 'Screenshot format (default png).' },
     quality: { type: 'string', value: '<1-100>', description: 'JPEG quality (default 80).' },
@@ -139,6 +140,16 @@ const SECRET_PERMISSIONS = {
     'all-projects': { type: 'boolean', description: 'Organization secrets: every project of the organization may use it.' },
 };
 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, '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: {
+            ...PAGE,
+            state: { type: 'string', value: '<working|waiting|exited>', description: 'Agent state filter.' },
+            label: { type: 'string', multiple: true, value: '<key=value>', description: 'Exact workspace label match.' },
+        } },
     {
         path: ['login'],
         summary: 'Verify the project API key (SHARDFLUX_API_KEY, else the saved one) and show its organization, project and tools',
@@ -220,6 +231,10 @@ const KEY_COMMANDS = [
             template: { type: 'string', value: '<slug>', description: 'Template slug (required), e.g. python-node-browser.' },
             labels: { type: 'string', value: '<json>', description: 'Replace workspace labels with a JSON object of strings.' },
             'delete-after-idle': { type: 'string', value: '<days>d', description: 'Delete this persistent workspace after 1..3650 idle days (e.g. 14d).' },
+            like: { type: 'string', value: '<id|key>', description: 'Open a fresh workspace with the source’s template and configuration.' },
+            volume: { type: 'string', multiple: true, value: '<name:/path[:ro]>', description: 'Replace the named volume mounts; repeat for each mount.' },
+            reachable: { type: 'string', value: '<duration>', description: 'Keep waiting agents reachable (default 30m; 0 off; maximum 24h).' },
+            'agent-idle-grace-seconds': { type: 'string', value: '<0-3600>', description: 'Grace after a coding agent waits or exits (default 300 seconds).' },
             'idle-policy': { type: 'string', value: '<policy>', description: 'adaptive, never or fixed:<seconds>.' },
             secret: {
                 type: 'string',
@@ -589,6 +604,14 @@ const KEY_COMMANDS = [
         options: { ...COMPUTER_LOOK },
         examples: ['shard ws computer type acme/demo "hello world"', 'cat notes.txt | shard ws computer type acme/demo -'],
     },
+    {
+        path: ['workspaces', 'computer', 'paste-text'],
+        summary: 'Intentionally replace the clipboard and paste text (0.12.0+)',
+        description: 'Replaces CLIPBOARD with <text> and presses the paste chord (default ctrl+v). The former clipboard is never restored, including cancellation after acquisition. Requires released keys. Up to 20,000 characters; - reads standard input.',
+        positionals: [REF, { name: 'text|-', required: true }],
+        options: { 'paste-chord': { type: 'string', value: '<keys>', description: 'One paste chord, e.g. shift+Insert or ctrl+shift+v.' }, ...COMPUTER_LOOK },
+        examples: ['cat notes.txt | shard ws computer paste-text acme/demo - --paste-chord shift+Insert --screenshot after.png'],
+    },
     {
         path: ['workspaces', 'computer', 'key'],
         summary: 'Press keys on the workspace desktop (0.10.0+)',
@@ -721,6 +744,12 @@ const KEY_COMMANDS = [
         options: {},
         examples: ['shard templates computer-use my-desktop-agent on'],
     },
+    {
+        path: ['files', 'read-many'],
+        summary: 'Read complete files from one sealed suspended generation without waking',
+        positionals: [REF],
+        options: { path: { type: 'string', multiple: true, value: '<path>', description: 'Absolute file path (repeat for 1–8 ordered files).' }, generation: { type: 'string', value: '<id>', description: 'Require this exact sealed generation.' } },
+    },
     {
         path: ['files', 'read'],
         summary: 'Print (or save) a file from a workspace',
@@ -808,6 +837,25 @@ const KEY_COMMANDS = [
         },
         examples: ['shard executions get acme/agent-7 build-42', 'shard ws executions get acme/agent-7 ex-6f1c2a9e-0d7b-4c1e-9a53-2b8e1f0c4d7a --wait 10m --json'],
     },
+    { path: ['secrets', 'log'], summary: 'Show credential request and fill audit events', positionals: [], options: {} },
+    { path: ['credentials', 'list'], summary: 'Show pending login requests', positionals: [], options: {} },
+    { path: ['credentials', 'enable'], summary: 'Enable credential fill in a workspace', positionals: [REF], options: {} },
+    { path: ['credentials', 'deny'], summary: 'Deny a login request', positionals: [{ name: 'request-id', required: true }], options: {} },
+    { path: ['credentials', 'forget'], summary: 'Remove a remembered site credential', positionals: [REF, { name: 'site', required: true }], options: {} },
+    { path: ['credentials', 'approve'], summary: 'Approve a login directly from your vault', positionals: [{ name: 'request-id', required: true }], options: {
+            from: { type: 'string', description: 'hsec, 1password, bitwarden or keychain.' }, item: { type: 'string', description: 'Vault login item name.' },
+            always: { type: 'boolean', description: 'Always allow these fields for this project on this laptop.' }, remember: { type: 'boolean', description: 'Remember for unattended use, encrypted with AWS KMS.' },
+        } },
+    {
+        path: ['secrets', 'import'],
+        summary: 'Import named items from your vault as encrypted project secrets',
+        positionals: [{ name: 'name', required: true, variadic: true }],
+        options: {
+            from: { type: 'string', value: '<hsec|1password|bitwarden|keychain>', description: 'Vault to read; values go straight into the encrypted secrets request.' },
+            as: { type: 'string', value: '<secret-name>', description: 'Secret name for a single imported item.' },
+            keychain: { type: 'string', value: '<path>', description: 'Read from this Keychain (keychain source only).' },
+        },
+    },
     {
         path: ['secrets', 'create'],
         summary: 'Create a secret; the value is read from standard input or --from-file, never from arguments',
@@ -1078,9 +1126,58 @@ const KEY_COMMANDS = [
         },
     },
 ];
+/** Copied sessions are project-key commands; --json is the normal global output option. */
+const AGENT_CREDENTIAL_COMMANDS = [
+    ...['sync', 'status', 'forget'].map((action) => ({ path: ['agents', 'credentials', action], summary: `${action} Codex copies and the account's cloud Claude login (contents never printed)`, positionals: [], options: {} })),
+    { path: ['agents', 'credentials', 'login'], summary: 'Sign in once to cloud Claude for this account', positionals: [{ name: 'app', required: true }], options: { workspace: { type: 'string', value: '<id|key>', description: 'Use this workspace for the cloud sign-in.' } } },
+];
+const AGENT_OPTIONS = {
+    reachable: { type: 'string', value: '<duration>', description: 'Keep waiting agents reachable (default 30m; 0 off; maximum 24h).' },
+    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.',
+    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: {} };
+const AGENT_COMMANDS = [
+    { path: ['agents', 'targets'], summary: 'Detect apps or configure managed desktop connections', positionals: [{ name: 'agent' }], options: { remove: { type: 'boolean', description: 'Remove this agent’s managed entries, or all entries for this API URL.' } } },
+    ...['claude-desktop', 'codex-app', 'web'].map(target => ({ path: ['agents', 'open', target], summary: `Open the agent in ${target}`, positionals: [{ name: 'agent' }], options: { reachable: AGENT_OPTIONS.reachable } })),
+    { path: ['ssh-proxy'], summary: 'Forward SSH standard IO to a managed workspace', positionals: [{ name: 'host', required: true }], options: {} },
+    ...['worktree', 'merge', 'keep', 'discard', 'restore'].map((action) => ({
+        path: ['agents', action], summary: { worktree: 'Open agent work in a local worktree', merge: 'Merge agent work into the current branch and clean up', keep: 'Keep agent work as a branch and clean up', discard: 'Delete an agent and its local work', restore: 'Restore archived work as a local branch within 30 days' }[action],
+        positionals: [{ name: 'agent', required: true }], options: {
+            path: { type: 'string', value: '<path>', description: 'Local repository path (default current repository).' },
+            ...(['worktree', 'merge', 'keep'].includes(action) ? { 'remote-path': { type: 'string', value: '<path>', description: 'Absolute repository path in the workspace (default /home/user/<project-slug>).' } } : {}),
+            ...(action === 'keep' ? { push: { type: 'boolean', description: 'Push the kept branch to origin and open a PR when gh is installed.' } } : {}),
+        },
+    })),
+    { path: ['agents', 'open'], summary: 'Attach an agent in the terminal', description: 'Detach with Ctrl-] then d; /exit ends the agent session.', positionals: [{ name: 'agent', required: true }], options: { ...AGENT_OPTIONS, app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default remembered choice).' }, in: { type: 'string', value: '<terminal>', description: 'Where to open the session (default terminal).' } } },
+    { path: ['agents', 'new'], summary: 'Start a session or a named agent', positionals: [{ name: 'agent' }], options: {
+            ...AGENT_OPTIONS,
+            app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default remembered choice).' },
+            path: { type: 'string', value: '<path>', description: 'Local project path for first launch.' },
+            name: { type: 'string', value: '<name>', description: 'New agent name; copies the project main workspace with --like.' },
+            like: { type: 'string', value: '<id|key>', description: 'Copy the workspace configuration onto a fresh disk.' },
+        } },
+    { 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', 'logs'], summary: 'Tail an agent PTY from its output offset', positionals: [{ name: 'agent', required: true }], options: {
+            app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default remembered choice).' },
+            offset: { type: 'string', value: '<bytes>', description: 'Read from this output byte offset (default last 64 KiB).' },
+            follow: { type: 'boolean', description: 'Follow output until interrupted.' },
+        } },
+];
 /** Every command: the account plane first (sign in, set up), then the project-key commands. */
-export const COMMANDS = [...ACCOUNT_COMMANDS.filter((c) => c.path[0] !== 'templates'), ...KEY_COMMANDS, ...ACCOUNT_COMMANDS.filter((c) => c.path[0] === 'templates')];
+const MENUBAR_COMMANDS = ['start', 'stop', 'status'].map(action => ({
+    path: ['menubar', action], summary: `${action === 'start' ? 'Install and start' : action === 'stop' ? 'Stop' : 'Show'} the macOS menu bar app`,
+    positionals: [], options: { login: { type: 'string', value: '<on|off>', description: 'Enable or disable launch at login.' } },
+}));
+export const COMMANDS = [...ACCOUNT_COMMANDS.filter((c) => c.path[0] !== 'templates'), ...AGENT_COMMANDS, ...AGENT_CREDENTIAL_COMMANDS, ...MENUBAR_COMMANDS, ...KEY_COMMANDS, ...ACCOUNT_COMMANDS.filter((c) => c.path[0] === 'templates')];
 const GROUPS = {
+    menubar: 'macOS menu bar app',
+    agents: 'Cloud agent sessions and copied credentials',
     auth: 'Create an account and sign in (the session is saved in the credentials file); passwords, email, two-factor authentication and sessions',
     'auth password': 'Change or reset your password',
     'auth email': 'Change your sign-in email',
@@ -1100,6 +1197,7 @@ const GROUPS = {
     files: 'Read, write, list, search and patch files in a workspace',
     operations: 'Inspect and wait for lifecycle operations',
     executions: 'Fetch the results of file-first executions (the commands "shard ws exec" runs in file-first workspaces)',
+    credentials: 'Approve browser login requests from your vault',
     secrets: 'Manage secrets (values are write-only) and bind them to workspaces',
     templates: 'Build templates from template.yaml, test and export versions, browse templates (file tree, diff), develop them in a draft, and publish or archive versions',
 };
@@ -1111,7 +1209,6 @@ const ALIASES = {
     execution: 'executions',
     file: 'files',
     secret: 'secrets',
-    template: 'templates',
     org: 'orgs',
     organization: 'orgs',
     organizations: 'orgs',
@@ -1131,7 +1228,7 @@ const FOLDED = new Set(['files', 'operations', 'executions']);
 /** Top-level shortcuts for a whole command path (0.10.0+): `shard exec` is `shard workspaces exec`. */
 const SHORTCUTS = { exec: ['workspaces', 'exec'] };
 export function normalizeWords(words) {
-    const w = words.flatMap((x, i) => (i === 0 ? SHORTCUTS[x] : undefined) ?? [ALIASES[x] ?? x]);
+    const w = words.flatMap((x, i) => (i === 0 ? SHORTCUTS[x] : undefined) ?? [i === 1 && ['projects', 'project'].includes(words[0]) && x === 'template' ? x : ALIASES[x] ?? x]);
     if (w[0] === 'workspaces' && w[1] !== undefined && FOLDED.has(w[1]))
         return w.slice(1);
     return w;
@@ -1245,9 +1342,9 @@ function toParseArgsOptions(opts) {
 }
 /**
  * Parses argv (without node/script). Throws UsageError for anything invalid;
- * returns help text for --help, bare groups and a bare `shard`.
+ * returns help text for --help, bare groups and non-TTY bare `shard`.
  */
-export function parseCommandLine(argv) {
+export function parseCommandLine(argv, options = {}) {
     const terminator = argv.indexOf('--');
     const head = terminator < 0 ? argv : argv.slice(0, terminator);
     const leading = [];
@@ -1294,7 +1391,7 @@ export function parseCommandLine(argv) {
                 rest.push(argv[(i += 1)]);
             continue;
         }
-        if (!sawPositional && !findCommand(words) && isPrefix([...words, a])) {
+        if (!sawPositional && isPrefix([...words, a])) {
             words.push(a);
             continue;
         }
@@ -1302,7 +1399,14 @@ export function parseCommandLine(argv) {
         rest.push(a);
     }
     const wantsHelp = head.includes('--help') || head.includes('-h');
-    const command = findCommand(words);
+    let command = findCommand(words);
+    if (!command && words.length === 0) {
+        const path = rest.find((r, i) => !r.startsWith('-') && !GLOBAL_VALUE_FLAGS.has(rest[i - 1] ?? ''));
+        if (path !== undefined && (/^(?:\.|\/|~\/)/.test(path) || options.isProjectPath?.(path)))
+            command = PROJECT_COMMAND;
+        else if (path === undefined && !wantsHelp && !head.includes('--version') && !head.includes('-V') && (options.tty || head.includes('--json')))
+            command = CENTER_COMMAND;
+    }
     if (!command) {
         if (words.length === 0) {
             if (head.includes('--version') || head.includes('-V'))
@@ -1341,6 +1445,8 @@ export function parseCommandLine(argv) {
     if (values.version === true)
         return { kind: 'version' };
     const positionals = parsed.positionals;
+    if (command === PROJECT_COMMAND && positionals[1] !== undefined && !['claude', 'codex'].includes(positionals[1]))
+        throw new UsageError('agent app must be claude or codex');
     const specs = command.positionals;
     const variadic = specs.at(-1)?.variadic === true;
     const required = specs.filter((s) => s.required && !s.variadic).length;
@@ -1390,6 +1496,8 @@ function optionLines(opts) {
     return rows.map(([l, d]) => `  ${l.padEnd(w)}  ${d}`);
 }
 export function usageLine(c) {
+    if (c === PROJECT_COMMAND)
+        return 'shard [options] <path> [claude|codex]';
     const pos = c.positionals.map((p) => (p.variadic ? (p.words ? `<${p.name}...>` : `-- <${p.name}> [args...]`) : p.required ? `<${p.name}>` : `[${p.name}]`));
     const opts = Object.keys(c.options).length > 0 ? ' [options]' : '';
     return `shard ${c.path.join(' ')}${opts}${pos.length ? ` ${pos.join(' ')}` : ''}`;
@@ -1427,9 +1535,9 @@ export const EXIT_CODE_HELP = [
 /** The top help's sections: every command's group (first word) is in exactly one (args.test.ts checks). */
 export const HELP_SECTIONS = [
     { title: 'Account (a user session: shard signup or shard auth login)', groups: ['signup', 'verify', 'auth', 'setup', 'env', 'orgs', 'projects', 'api-keys', 'members', 'invitations', 'billing', 'audit', 'account'] },
-    { title: 'Workspaces (a project API key: SHARDFLUX_API_KEY, else the one shard setup saved)', groups: ['login', 'whoami', 'usage', 'workspaces', 'files', 'operations', 'executions', 'secrets', 'volumes', 'egress'] },
+    { title: 'Workspaces (a project API key: SHARDFLUX_API_KEY, else the one shard setup saved)', groups: ['login', 'whoami', 'status', 'usage', 'machine', 'template', 'agents', 'ssh-proxy', 'workspaces', 'files', 'operations', 'executions', 'secrets', 'credentials', 'volumes', 'egress'] },
     { title: 'Templates (publish and archive use the session; the rest the API key)', groups: ['templates'] },
-    { title: 'Other', groups: ['feedback', 'version'] },
+    { title: 'Other', groups: ['menubar', 'feedback', 'version'] },
 ];
 export function topHelp() {
     const w = Math.max(...COMMANDS.map((c) => usageLine(c).length));
@@ -1438,6 +1546,8 @@ export function topHelp() {
         `shard ${CLI_VERSION} — the Shardflux command line (built on @shardflux/sdk)`,
         '',
         'Usage: shard [global options] <command> [options] [arguments]',
+        '       shard <path> [claude|codex] [--approvals]',
+        'Terminal: detach with Ctrl-] then d; /exit ends the agent session.',
         '',
         'Feedback: shard feedback [options] <message...>',
         ...FEEDBACK_WHY.map((l) => `  ${l}`),

package/dist/assisted-setup.d.ts

@@ -0,0 +1,24 @@
+import type { WorkspaceView } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+export interface SetupProgress {
+    id: string;
+    deps_hash: string;
+    state: 'queued' | 'running' | 'checking' | 'saving' | 'ready' | 'failed';
+    tasks: {
+        name: string;
+        state: 'queued' | 'running' | 'ready' | 'failed';
+        attempts: number;
+        error?: {
+            code: string;
+            message: string;
+            retryable: boolean;
+        };
+    }[];
+    cache_scope: 'workspace' | 'account';
+}
+/** Read only while the command center is visible, from opted-in running VMs.
+ * A parked workspace is never woken just to display setup progress.
+ */
+export declare function readSetupProgress(ctx: Ctx, workspace: WorkspaceView, agentWorking?: boolean): Promise<SetupProgress | undefined>;
+export declare function retrySetupStep(ctx: Ctx, workspace: WorkspaceView, step: string): Promise<void>;
+export declare function setupLine(project: string, setup: SetupProgress): string | undefined;

package/dist/assisted-setup.js

@@ -0,0 +1,77 @@
+import { workspaceRepositoryPath } from "./agent-repository.js";
+const settled = new WeakMap();
+async function registered(ctx, workspace, progress) {
+    if (progress.state !== 'saving')
+        return progress;
+    try {
+        const binding = await ctx.cloud().projectTemplates.get(workspace.labels.shard_repo_remote, { signal: ctx.signal });
+        if (binding.deps_hash === progress.deps_hash && binding.version > 0)
+            progress.state = 'ready';
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'status' in error && error.status === 404))
+            throw error;
+    }
+    return progress;
+}
+/** Read only while the command center is visible, from opted-in running VMs.
+ * A parked workspace is never woken just to display setup progress.
+ */
+export async function readSetupProgress(ctx, workspace, agentWorking = false) {
+    if (workspace.labels.shard_setup !== 'true')
+        return undefined;
+    const cloud = ctx.cloud();
+    let cache = settled.get(cloud);
+    if (!cache) {
+        cache = new Map();
+        settled.set(cloud, cache);
+    }
+    const previous = cache.get(workspace.id);
+    // A status exec counts as activity. Stop spawning them after setup settles
+    // so the command center cannot keep a waiting agent awake indefinitely.
+    if (previous && previous.deps_hash === workspace.labels.shard_deps_hash && (previous.state !== 'failed' || !agentWorking))
+        return registered(ctx, workspace, previous);
+    if (workspace.observed_state !== 'running')
+        return previous?.deps_hash === workspace.labels.shard_deps_hash ? previous : undefined;
+    const ws = await ctx.cloud().workspaces.get(workspace.id);
+    const cell = ws.cell({ wake: null, agentLabel: ctx.agentLabel, transitionTimeoutMs: 0 });
+    try {
+        const response = await cell.exec.run(['sf-agent', 'template', '--json'], { cwd: workspaceRepositoryPath(ws), timeoutMs: 3000, maxOutputBytes: 1024 * 1024, signal: ctx.signal });
+        if (response.exitCode !== 0)
+            return undefined; // Older guests have no setup status.
+        const progress = JSON.parse(response.stdout);
+        if (!progress || !/^[a-f0-9]{64}$/.test(progress.id) || !Array.isArray(progress.tasks))
+            throw new Error('guest omitted structured setup progress');
+        if (['saving', 'ready', 'failed'].includes(progress.state))
+            cache.set(workspace.id, progress);
+        await registered(ctx, workspace, progress);
+        return progress;
+    }
+    finally {
+        cell.close();
+    }
+}
+export async function retrySetupStep(ctx, workspace, step) {
+    settled.get(ctx.cloud())?.delete(workspace.id);
+    const ws = await ctx.cloud().workspaces.get(workspace.id);
+    const cell = ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs });
+    try {
+        const result = await cell.exec.run(['sf-agent', 'template', 'retry', '--step', step, '--json'], { cwd: workspaceRepositoryPath(ws), timeoutMs: 3000, maxOutputBytes: 64 * 1024, signal: ctx.signal });
+        if (result.exitCode !== 0)
+            throw new Error(result.stderr.trim() || `setup retry exited ${result.exitCode}`);
+    }
+    finally {
+        cell.close();
+    }
+}
+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');
+    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')
+        return `Setting up ${project}: saving template`;
+    const running = setup.tasks.filter(task => task.state === 'running').map(task => task.name);
+    return `Setting up ${project}: ${running.join(', ') || 'detecting pinned tools and dependencies'}`;
+}

package/dist/browser-commands.d.ts

@@ -0,0 +1,3 @@
+import type { Handler } from './commands.js';
+export declare const browserProfileName: (site: string, scope: string) => string;
+export declare const BROWSER_HANDLERS: Record<string, Handler>;

package/dist/browser-commands.js

@@ -0,0 +1,83 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { resolveWorkspace } from "./commands.js";
+import { UsageError } from "./errors.js";
+import { browserSessionNote, workspaceBrowserSessionNote } from "./browser-profile-copy.js";
+import { normalizeBrowserSite } from "./browser-sites.js";
+const browsers = ['chrome', 'arc', 'brave', 'edge', 'safari', 'firefox'];
+const text = (v) => typeof v === 'string' ? v : undefined;
+export const browserProfileName = (site, scope) => `site-${createHash('sha256').update(`${site}\0${scope}`).digest('hex').slice(0, 24)}`;
+const note = (workspace) => workspace ? workspaceBrowserSessionNote : browserSessionNote;
+function summary(rows) {
+    return rows.length ? rows.flatMap(p => p.sites.map(s => `${s.site} · ${s.cookie_count} cookies · ${s.origins.length} storage origins · ${typeof p.scope === 'string' ? 'project' : p.scope.workspace_id}`)).join('\n') + '\n' : 'No browser sessions.\n';
+}
+export const BROWSER_HANDLERS = {
+    async 'browser import'(ctx, values, sites) {
+        if (values.project && values.workspace)
+            throw new UsageError('Choose --project or --workspace.');
+        const from = text(values.from) ?? 'chrome';
+        if (!browsers.includes(from))
+            throw new UsageError('--from must be chrome, arc, brave, edge, safari or firefox');
+        const browser = from;
+        const ws = text(values.workspace) ? await resolveWorkspace(ctx, text(values.workspace)) : undefined;
+        const { browserDirectory, readBrowserState } = await import("./browser-readers.js");
+        const directory = text(values['profile-dir']) ?? await browserDirectory(browser);
+        const states = await readBrowserState(browser, directory, sites);
+        const profiles = [];
+        for (const s of states) {
+            if (!s.storage_state.cookies.length && !s.storage_state.origins.some(o => o.localStorage.length))
+                throw new UsageError(`No browser session was found for ${s.site}. Sign in to that site in the selected browser, then retry.`);
+            profiles.push(await ctx.cloud().browserProfiles.put(browserProfileName(s.site, ws?.id ?? 'project'), { scope: ws ? { workspace_id: ws.id } : 'project', sites: [s] }, { signal: ctx.signal }));
+        }
+        if (ctx.json)
+            ctx.io.stdout.write(`${JSON.stringify({ profiles, security_note: note(!!ws) })}\n`);
+        else
+            ctx.io.stdout.write(`${summary(profiles)}${note(!!ws)}\n`);
+        return 0;
+    },
+    async 'browser list'(ctx) {
+        const profiles = await ctx.cloud().browserProfiles.list({ signal: ctx.signal });
+        ctx.io.stdout.write(ctx.json ? `${JSON.stringify(profiles)}\n` : summary(profiles));
+        return 0;
+    },
+    async 'browser remove'(ctx, values, [raw]) {
+        if (values.project && values.workspace)
+            throw new UsageError('Choose --project or --workspace.');
+        const site = normalizeBrowserSite(raw);
+        const ws = text(values.workspace) ? await resolveWorkspace(ctx, text(values.workspace)) : undefined;
+        const profiles = (await ctx.cloud().browserProfiles.list({ signal: ctx.signal })).filter(p => p.sites.some(s => s.site === site) && (ws ? typeof p.scope !== 'string' && p.scope.workspace_id === ws.id : p.scope === 'project'));
+        if (!profiles.length)
+            throw new UsageError(`No stored browser session was found for ${site} in this scope.`);
+        for (const p of profiles)
+            await ctx.cloud().browserProfiles.remove(p.name, { site, signal: ctx.signal });
+        ctx.io.stdout.write(ctx.json ? `${JSON.stringify({ removed: site })}\n` : `Removed ${site}.\n`);
+        return 0;
+    },
+    async 'browser save'(ctx, values, [raw]) {
+        const key = text(values.workspace);
+        if (!key)
+            throw new UsageError('browser save requires --workspace <key>');
+        const site = normalizeBrowserSite(raw), ws = await resolveWorkspace(ctx, key);
+        const cell = ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs });
+        const filename = `/home/user/.local/share/shardflux/browser/export-${randomUUID()}.json`;
+        try {
+            const run = await cell.exec.run(['sf-guest-agent', 'browser-profile', 'export', site, filename], { env: { HOME: '/home/user' }, signal: ctx.signal, timeoutMs: 60_000, maxOutputBytes: 4096 });
+            if (run.exitCode !== 0 || run.truncated)
+                throw new UsageError('The workspace browser session could not be saved.');
+            let storage;
+            try {
+                storage = JSON.parse(await cell.files.readText(filename, { length: 4 * 1024 * 1024 + 1 }));
+            }
+            catch {
+                throw new UsageError('The workspace browser session could not be read.');
+            }
+            if (!storage.cookies?.length && !storage.origins?.some(o => o.localStorage.length))
+                throw new UsageError(`Sign in to ${site} through the workspace desktop, then retry save.`);
+            const profile = await ctx.cloud().browserProfiles.put(browserProfileName(site, ws.id), { scope: { workspace_id: ws.id }, sites: [{ site, storage_state: storage }] }, { signal: ctx.signal });
+            ctx.io.stdout.write(ctx.json ? `${JSON.stringify({ profile, security_note: note(true) })}\n` : `${summary([profile])}${note(true)}\n`);
+            return 0;
+        }
+        finally {
+            await cell.files.remove(filename).catch(() => { });
+        }
+    },
+};

package/dist/browser-profile-copy.d.ts

@@ -0,0 +1,2 @@
+export declare const browserSessionNote = "Stored encrypted with AWS KMS; only this project's workspaces can load it, and every load is logged.";
+export declare const workspaceBrowserSessionNote = "Stored encrypted with AWS KMS; only this workspace can load it, and every load is logged.";

package/dist/browser-profile-copy.js

@@ -0,0 +1,2 @@
+export const browserSessionNote = "Stored encrypted with AWS KMS; only this project's workspaces can load it, and every load is logged.";
+export const workspaceBrowserSessionNote = 'Stored encrypted with AWS KMS; only this workspace can load it, and every load is logged.';

package/dist/browser-readers.d.ts

@@ -0,0 +1,13 @@
+import type { BrowserStorageState } from '@shardflux/sdk';
+export type BrowserName = 'chrome' | 'arc' | 'brave' | 'edge' | 'safari' | 'firefox';
+export { browserSessionNote } from './browser-profile-copy.js';
+export { normalizeBrowserSite } from './browser-sites.js';
+/** Called only by an explicit import. Tests pass a throwaway directory and synthetic key provider. */
+export declare function browserDirectory(browser: BrowserName): Promise<string>;
+export declare function safeStorageKey(browser: Exclude<BrowserName, 'safari' | 'firefox'>): Promise<Buffer>;
+export declare function decryptChromiumCookie(encrypted: Uint8Array, password: Buffer, host: string, version: number): string;
+export declare function readBrowserState(browser: BrowserName, directory: string, rawSites: string[], keyProvider?: typeof safeStorageKey): Promise<{
+    site: string;
+    storage_state: BrowserStorageState;
+}[]>;
+export declare function readSafariCookies(b: Buffer): BrowserStorageState['cookies'];