@shardflux/cli 0.20.0 → 0.23.0

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.20.0';
+export const CLI_VERSION = '0.23.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).' },
@@ -110,18 +110,14 @@ const FEEDBACK_HELP = [
 ];
 /**
  * Why `shard feedback` exists, for the coding agents that drive shard: the same words as the top-level help and the
- * MCP server's send_feedback tool. It has to make an agent actually send feedback while it works.
+ * MCP server's send_feedback tool. Reporting is user-directed and requires approval of the message.
  */
 const FEEDBACK_WHY = [
-    'Sends your message straight to the Shardflux team, who read every one. Agents: use it actively while you work,',
-    'not once at the end. Send a short note the moment:',
-    '- something fails unexpectedly, an error or doc is unclear, an option is missing, or you needed a workaround;',
-    '- your user asks for a capability, an option or a smoother workflow: paraphrase it, with what they were trying',
-    '  to do;',
-    '- your user has an idea for how Shardflux could fit their work better.',
-    'Short and frequent beats polished; include the request id and error code (a failed shard command prints a',
-    'ready-made "feedback:" line to fill in). No need to ask first, but tell your user you sent it. Leave out private',
-    'data about the user and secrets or code they did not mean to share; paraphrase, never paste transcripts.',
+    'Previews a message for the Shardflux team without sending it. Use --yes to send only after approval.',
+    'Agents: report only when your user asks you to send feedback. Show the exact message and context first,',
+    'then obtain explicit authorization before using --yes. A failure or request for a feature is not consent.',
+    'Include the request id and error code. Leave out private data, secrets and code the user did not mean to',
+    'share; paraphrase, never paste transcripts. Tell your user what was sent.',
 ];
 const LIFETIME_FILTER = {
     lifetime: { type: 'string', value: '<persistent|session|any>', description: 'Lifetime filter (default persistent: sessions are hidden).' },
@@ -132,8 +128,12 @@ const SECRET_SCOPE = {
     org: { type: 'string', value: '<organization-id>', description: 'Organization-wide secrets of this organization (owners/admins; project API keys get 403). Default: the API key’s project.' },
 };
 const SECRET_VALUE = {
-    'from-file': { type: 'string', value: '<file>', description: 'Read the value from this file. Default: standard input (pipe it in). One trailing newline is removed. Values are never accepted as arguments.' },
+    'from-file': { type: 'string', value: '<file>', description: 'Read the value from this file. Default: standard input (pipe it in), a hidden prompt on a terminal, or the --ask page in a coding agent’s shell. One trailing newline is removed. Values are never accepted as arguments.' },
+    ask: { type: 'boolean', description: 'Your user types the value in a page shard opens in the browser; it goes straight to the API, never through the coding agent (0.20.1+). The default in a coding agent’s shell when nothing is piped.' },
+    timeout: { type: 'string', value: '<duration>', description: 'How long the --ask page waits (default 10m).' },
 };
+/** What --ask prints (0.20.1+), for the help of each command that asks. */
+const ASK_EVENTS = 'The page’s link is printed too ("Opened a page in your browser to type …"); with --json the first line is {"event":"open","url":…,"opened":true|false,"expires_in":600}, then the result once the page was submitted.';
 const SECRET_PERMISSIONS = {
     tool: { type: 'string', multiple: true, value: '<tool>', description: 'Tool that receives the value at session start (repeatable; exec, pty, files, process, git, browser). Default exec and pty.' },
     'allow-workspace': { type: 'string', multiple: true, value: '<workspace-id>', description: 'Only these workspaces may use it (repeatable). Default: any workspace of the allowed projects.' },
@@ -142,8 +142,8 @@ const SECRET_PERMISSIONS = {
 };
 // Cloud agents: a VM is the coding template, then the machine, then the project template.
 const LAYER_HELP = {
-    machine: 'Your machine is what every cloud agent starts with: tools, credentials, dotfiles, browser logins, git identity, Claude/Codex settings and skills. "shard machine" opens its VM; change it there (or in any agent’s VM), then run "shard machine save". It is saved from an agent’s VM, so it always keeps Claude Code, Codex and the agent runtime.',
-    template: 'The project template is this repository’s layer: toolchains, dependencies, services and project secrets. Setup after "shard ./" saves it; "shard template save" saves the current agent VM’s project changes. It is saved from an agent’s VM; "shard templates" builds templates for your own app’s workspaces instead.',
+    machine: 'Your machine is what every cloud agent starts with: tools, credentials, dotfiles, browser logins, git identity, Claude/Codex settings and skills. On your computer, "shard machine open --json" opens its source VM; change that VM, then run "shard machine save --wait". The computer’s CLI selects the machine VM, regardless of your current folder or conversation. Inside a VM, save uses that VM and requires a machine source; a conversation or unmarked fork returns filesystem_source_mismatch. To keep changes from another VM, copy the intended files or repeat the install in the machine VM, then save it. A machine source keeps Claude Code, Codex and the agent runtime.',
+    template: 'The project template is this repository’s layer: toolchains, dependencies, services and project secrets. Setup after "shard ./" saves it; "shard template save" saves the current agent VM’s project changes, and "shard template delete" starts the project over from your machine. It is saved from an agent’s VM; "shard templates" builds templates for your own app’s workspaces instead.',
 };
 const KEY_COMMANDS = [
     { path: ['conversations', 'list'], summary: 'List project conversations', positionals: [], options: {
@@ -162,19 +162,23 @@ const KEY_COMMANDS = [
     { path: ['conversations', 'landing'], summary: 'Show or set how finished conversations reach this checkout', positionals: [{ name: 'mode' }, { name: 'backup' }], options: {
             path: { type: 'string', value: '<path>', description: 'Local project checkout (default the current directory).' }
         },
-        description: 'While the macOS app runs, a conversation whose turn ends with committed work lands in the local branch it started from: the branch moves to its commits and the changed files are written, keeping your uncommitted edits (auto, the default). pr opens a pull request instead; off leaves conversations in the cloud. Every file a landing rewrites is backed up first: backups lists them, restore <backup> puts the files back.',
+        description: 'While the Shardflux app runs (the menu bar on macOS, the background helper on Linux), a conversation whose turn ends with committed work lands in the local branch it started from: the branch moves to its commits and the changed files are written, keeping your uncommitted edits (auto, the default). pr opens a pull request instead; off leaves conversations in the cloud. Every file a landing rewrites is backed up first: backups lists them, restore <backup> puts the files back.',
         examples: ['shard conversations landing', 'shard conversations landing pr', 'shard conversations landing backups', 'shard conversations landing restore 2026-10-09T12-00-00-000Z-fix-login-3fa2c1'] },
     ...['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: {},
             description: LAYER_HELP[level] },
         { path: [level, 'save'], summary: `Save the ${level} filesystem as a new private version`, description: LAYER_HELP[level], positionals: [], options: {
-                wait: { type: 'boolean', description: 'Return when the new version is ready (or failed), printing progress on stderr.' },
+                wait: { type: 'boolean', description: 'Return when the new version is ready (or failed), printing each phase and its progress on stderr (0.20.2+; with --json as {"event":"save_progress"} lines, and `phases` in the result).' },
                 timeout: { type: 'string', value: '<duration>', description: 'With --wait: give up waiting after this long (default 10m). The save continues server side.' },
             } },
         { path: [level, 'rollback'], summary: `Restore a saved ${level} version`, positionals: [], options: { to: { type: 'string', value: '<version>', description: 'Version to restore (default previous saved version).' } } },
+        ...(level === 'template' ? [{ path: [level, 'delete'], summary: 'Delete this project’s template and its saved versions (0.20.1+)', positionals: [], options: {
+                    yes: { type: 'boolean', description: 'Skip the confirmation.' },
+                }, description: 'Deletes the project template of this folder’s repository: its saved versions, binding and setup state. It is no longer rebuilt when your machine or the platform changes; new conversations start from your machine until setup after "shard ./" (or "shard template save") saves a new one. VMs running on it keep their files, and builds still running for it are stopped. In a terminal it asks first; elsewhere it needs --yes.',
+                examples: ['shard template delete', 'shard template delete --yes --json'] }] : []),
     ]),
     { 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.',
+        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 with "shard files write <key> <path> --from -" (contents on standard input) and secret files with --ask (your user types them in a page shard opens; 0.20.1+), 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.' },
@@ -200,13 +204,13 @@ const KEY_COMMANDS = [
     { path: ['whoami'], summary: 'Show the principal behind the project API key (SHARDFLUX_API_KEY, else the saved one)', positionals: [], options: {} },
     {
         path: ['update'],
-        summary: 'Update shard, the menu bar app and a global MCP server to their latest versions',
+        summary: 'Update shard, the desktop app and a global MCP server to their latest versions',
         description: [
             'Checks every local Shardflux piece against GET /v1/client-versions: shard (the shardflux package or @shardflux/cli),',
-            'its SDK, the macOS menu bar app and a globally installed @shardflux/mcp. When one is behind, runs one install of',
-            'the latest versions with the package manager that installed shard (npm, pnpm, bun or Volta), then restarts the',
-            'menu bar on its new app. --check only reports. Projects that depend on @shardflux/sdk or shardflux (Python) keep',
-            'their own versions.',
+            'its SDK, the desktop app (the macOS menu bar, or the Linux app that installs with shard) and a globally installed',
+            '@shardflux/mcp. When one is behind, runs one install of the latest versions with the package manager that installed',
+            'shard (npm, pnpm, bun or Volta), then restarts the macOS menu bar on its new app. --check only reports. Projects',
+            'that depend on @shardflux/sdk or shardflux (Python) keep their own versions.',
         ].join('\n'),
         positionals: [],
         options: { check: { type: 'boolean', description: 'Report what is behind without installing anything.' } },
@@ -220,7 +224,7 @@ const KEY_COMMANDS = [
     },
     {
         path: ['feedback'],
-        summary: 'Tell the Shardflux team what failed, confused you or is missing (agents: as you work)',
+        summary: 'Preview feedback; send to the Shardflux team only with explicit approval',
         description: [
             ...FEEDBACK_WHY,
             '',
@@ -234,6 +238,7 @@ const KEY_COMMANDS = [
         ].join('\n'),
         positionals: [{ name: 'message', variadic: true, words: true }],
         options: {
+            yes: { type: 'boolean', description: 'Send this message and context after reviewing the preview and obtaining explicit user authorization (0.21.0+).' },
             category: { type: 'string', value: '<bug|confusing|missing|idea|praise|other>', description: 'Kind of feedback (default other; see Categories).' },
             workspace: { type: 'string', value: '<id|key>', description: 'The workspace it is about.' },
             'request-id': { type: 'string', value: '<id>', description: 'request_id from the error, so the team can find the logs.' },
@@ -253,7 +258,7 @@ const KEY_COMMANDS = [
         description: 'Default: the summary (meters, allowances, caps). --estimate: the subscription fee, usage charges and projected allowance use at period end. --series: usage over time from the ledger (hour: at most 31 days, day: at most 400 days per request). --workspace: the same series for one workspace (the dashboard’s per-workspace usage).',
         positionals: [],
         options: {
-            org: { type: 'string', value: '<organization-id>', description: 'Organization (default: the API key’s organization).' },
+            org: { type: 'string', value: '<id|slug>', description: 'Organization (default: the API key’s organization). Another of your organizations uses your signed-in session; slugs require sign-in (0.20.2+).' },
             estimate: { type: 'boolean', description: 'Show the period estimate instead of the summary.' },
             series: { type: 'boolean', description: 'Show usage over time instead of the summary.' },
             workspace: { type: 'string', value: '<id|key>', description: 'Show usage over time of this workspace.' },
@@ -815,12 +820,15 @@ const KEY_COMMANDS = [
         positionals: [REF, { name: 'path', required: true }],
         options: {
             from: { type: 'string', value: '<file|->', description: 'Local file to upload, or - for standard input (default -).' },
+            ask: { type: 'boolean', description: 'Your user types or pastes the contents in a page shard opens in the browser, for secret files such as ~/.npmrc; the coding agent never sees them, and a new file gets mode 0600 (0.20.1+).' },
+            timeout: { type: 'string', value: '<duration>', description: 'How long the --ask page waits (default 10m).' },
             append: { type: 'boolean', description: 'Append instead of replacing.' },
             parents: { type: 'boolean', description: 'Create missing parent directories (default; --no-parents to refuse).' },
             ...IF_REVISION,
             ...WAKE_TIMING,
         },
-        examples: ['shard files write acme/demo /home/user/notes.txt --from notes.txt', 'printf "x = 1\\n" | shard files write acme/agent-7 /home/user/app/config.py --if-revision 4'],
+        description: `--ask (0.20.1+) asks your user for a secret file’s contents on a page on this computer; the page says Saved once the file is written. ${ASK_EVENTS}`,
+        examples: ['shard files write acme/demo /home/user/notes.txt --from notes.txt', 'printf "x = 1\\n" | shard files write acme/agent-7 /home/user/app/config.py --if-revision 4', 'shard files write "$(shard machine open)" /home/user/.npmrc --ask --json'],
     },
     {
         path: ['files', 'ls'],
@@ -872,7 +880,7 @@ const KEY_COMMANDS = [
     {
         path: ['files', 'pull'],
         summary: 'Download a large file a conversation committed into ~/Shardflux',
-        description: 'Each conversation’s committed changes appear in ~/Shardflux/<repository>/<base branch>/<conversation>/ while the macOS app runs. Files above the size limit are listed there as <file>.placeholder.txt; this downloads one in its place. <conversation> is its name, id or folder name.',
+        description: 'Each conversation’s committed changes appear in ~/Shardflux/<repository>/<base branch>/<conversation>/ while the Shardflux app runs (the menu bar on macOS, the background helper on Linux). Files above the size limit are listed there as <file>.placeholder.txt; this downloads one in its place. <conversation> is its name, id or folder name.',
         positionals: [{ name: 'conversation', required: true }, { name: 'path', required: true }],
         options: {},
         examples: ['shard files pull hype-video out/hype.mp4'],
@@ -888,6 +896,14 @@ const KEY_COMMANDS = [
         },
     },
     { path: ['operations', 'get'], summary: 'Show one operation', positionals: [{ name: 'operation-id', required: true }], options: {} },
+    { path: ['operations', 'progress'], summary: 'Read suspension preparation and capture progress without waking the workspace',
+        positionals: [{ name: 'operation-id', required: true }], options: {} },
+    { path: ['operations', 'cancel'], summary: 'Cancel suspension preparation before capture and retain the original workspace',
+        description: 'Only host-acknowledged pre-capture cancellation is accepted. Without --wait this is a request; poll the same operation for recovery. After capture starts, wait for the suspension outcome and resume. No reset or replacement.',
+        positionals: [{ name: 'operation-id', required: true }], options: {
+            wait: { type: 'boolean', description: 'Wait for confirmed original-workspace recovery (suspend_canceled).' },
+            timeout: { type: 'string', value: '<duration>', description: 'With --wait, give up after this long (default 5m); recovery continues server side.' },
+        } },
     {
         path: ['executions', 'get'],
         summary: 'Fetch the result of a file-first workspace’s execution (exit: its command’s code; 6 failed/lost; 5 still running)',
@@ -920,11 +936,11 @@ const KEY_COMMANDS = [
     },
     {
         path: ['secrets', 'create'],
-        summary: 'Create a secret; the value is read from standard input or --from-file, never from arguments',
-        description: 'Project secret of the API key’s project by default, or an organization-wide secret with --org. The value (UTF-8 text, up to 64 KiB) is encrypted and never shown again. Bind it to workspaces with "shard ws open --secret NAME" or "shard ws secrets <ws> --set NAME".',
+        summary: 'Create a secret (the value from the --ask page, standard input or --from-file; never from arguments)',
+        description: `Project secret of the API key’s project by default, or an organization-wide secret with --org. The value (UTF-8 text, up to 64 KiB) is encrypted and never shown again. Bind it to workspaces with "shard ws open --secret NAME" or "shard ws secrets <ws> --set NAME". With --ask (0.20.1+; the default in a coding agent’s shell when nothing is piped) your user types the value in a page on this computer and the coding agent never sees it; the page says Saved once the API stored it. ${ASK_EVENTS}`,
         positionals: [{ name: 'name', required: true }],
         options: { ...SECRET_SCOPE, ...SECRET_VALUE, description: { type: 'string', value: '<text>', description: 'Description (up to 500 characters).' }, ...SECRET_PERMISSIONS },
-        examples: ['printf %s "$OPENAI_API_KEY" | shard secrets create OPENAI_API_KEY', 'shard secrets create DATABASE_URL --from-file ./database-url.txt --description "Staging database"'],
+        examples: ['shard secrets create GITHUB_TOKEN --ask --json', 'printf %s "$OPENAI_API_KEY" | shard secrets create OPENAI_API_KEY', 'shard secrets create DATABASE_URL --from-file ./database-url.txt --description "Staging database"'],
     },
     {
         path: ['secrets', 'list'],
@@ -953,10 +969,11 @@ const KEY_COMMANDS = [
     },
     {
         path: ['secrets', 'rotate'],
-        summary: 'Store a new value as the next version (standard input or --from-file); older values are erased',
+        summary: 'Store a new value as the next version (the --ask page, standard input or --from-file); older values are erased',
+        description: `With --ask (0.20.1+; the default in a coding agent’s shell when nothing is piped) your user types the new value in a page on this computer and the coding agent never sees it. ${ASK_EVENTS}`,
         positionals: [SECRET_REF],
         options: { ...SECRET_SCOPE, ...SECRET_VALUE },
-        examples: ['printf %s "$NEW_TOKEN" | shard secrets rotate API_TOKEN'],
+        examples: ['shard secrets rotate GITHUB_TOKEN --ask --json', 'printf %s "$NEW_TOKEN" | shard secrets rotate API_TOKEN'],
     },
     {
         path: ['secrets', 'versions'],
@@ -1191,24 +1208,28 @@ 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.' } } },
+    { 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.' },
+            ask: { type: 'boolean', description: 'Use the browser pages even on a terminal (0.20.1+).' },
+            timeout: { type: 'string', value: '<duration>', description: 'How long the sign-in waits for the code (default 10m).' },
+        },
+        description: 'On a terminal the Claude sign-in runs attached to it: open the claude.ai link, then paste its code. In a coding agent’s shell, with --json or without a terminal (0.20.1+) shard opens the claude.ai sign-in and a page on this computer where your user pastes the code, so the coding agent runs it itself and never sees the code. The links are printed too; with --json the first lines are {"event":"open","url":…} (claude.ai) and {"event":"ask","url":…} (the page), then the login.',
+        examples: ['shard agents credentials login claude --json'] },
 ];
 const ACCOUNT_PROVIDER = { type: 'string', value: '<claude|codex>', description: 'Only this provider’s accounts.' };
-/** Claude and ChatGPT/Codex accounts with their usage windows, resets and threads (0.18.0+). */
+/** Claude and ChatGPT/Codex accounts with their usage windows and resets, and the active one of each provider (0.18.0+). */
 const AGENT_ACCOUNT_COMMANDS = [
-    { path: ['agents', 'accounts'], summary: 'Claude and ChatGPT/Codex accounts with usage, resets and status (0.18.0+)', positionals: [], options: { provider: ACCOUNT_PROVIDER },
-        examples: ['shard agents accounts', 'shard agents accounts usage', 'shard agents accounts add claude', 'pbpaste | shard agents accounts add codex --api-key-stdin'] },
-    { path: ['agents', 'accounts', 'list'], summary: 'List the accounts: status, usage windows and when they reset (0.18.0+)', positionals: [], options: { provider: ACCOUNT_PROVIDER } },
+    { path: ['agents', 'accounts'], summary: 'Claude and ChatGPT/Codex accounts: which one is active, usage, resets and status (0.18.0+)', positionals: [], options: { provider: ACCOUNT_PROVIDER },
+        examples: ['shard agents accounts', 'shard agents accounts usage', 'shard agents accounts add claude', 'shard agents accounts use claude:2'] },
+    { path: ['agents', 'accounts', 'list'], summary: 'List the accounts: which one is active, status, usage windows and when they reset (0.18.0+)', positionals: [], options: { provider: ACCOUNT_PROVIDER } },
     { path: ['agents', 'accounts', 'usage'], summary: 'Every usage window of every account, with its reset time (0.18.0+)', positionals: [], options: { provider: ACCOUNT_PROVIDER } },
-    { path: ['agents', 'accounts', 'add'], summary: 'Sign in a Claude or ChatGPT account, or add an API key (0.18.0+)', positionals: [{ name: 'provider', required: true }], options: {
-            'api-key-stdin': { type: 'boolean', description: 'Add an API key read from standard input instead of signing in.' },
+    { path: ['agents', 'accounts', 'add'], summary: 'Sign in a Claude or ChatGPT account (0.18.0+)', positionals: [{ name: 'provider', required: true }], options: {
             label: { type: 'string', value: '<name>', description: 'The account’s name in lists (default its email).' },
-            scope: { type: 'string', value: '<personal|team>', description: 'personal: only your threads use it; team: any member’s (default: team for team plans and API keys, else personal).' },
             workspace: { type: 'string', value: '<id|key>', description: 'Run the sign-in in this workspace (default your machine VM, from any folder).' },
         } },
+    { path: ['agents', 'accounts', 'use'], summary: 'Make an account the active one of its provider: new conversations start with it and running ones switch to it', positionals: [{ name: 'account', required: true }], options: {},
+        examples: ['shard agents accounts use claude:2', 'shard agents accounts use marc@example.com --json'] },
     { path: ['agents', 'accounts', 'remove'], summary: 'Remove an account and its login (0.18.0+)', positionals: [{ name: 'account', required: true }], options: {} },
-    { path: ['agents', 'accounts', 'move'], summary: 'Move an account up or down in its provider’s order (0.18.0+)', positionals: [{ name: 'account', required: true }, { name: 'direction', required: true }], options: {} },
-    { path: ['agents', 'accounts', 'pool'], hidden: true, summary: 'Pool accounts: each new thread on the account with the most room', positionals: [{ name: 'state', required: true }], options: {} },
 ];
 /** `shard accounts …`: the same commands, as the menu bar and the design name them. */
 const ACCOUNT_ALIASES = AGENT_ACCOUNT_COMMANDS.map(c => ({ ...c, path: c.path.slice(1), hidden: true }));
@@ -1239,7 +1260,7 @@ const ON_OPTIONS = {
 };
 export const PROJECT_COMMAND = {
     path: ['<path>'], summary: 'Start a conversation in its own cloud VM',
-    description: 'Opens Claude Code or Codex directly. --resume continues a project conversation. With --json it starts detached and prints the session. Detach with Ctrl-] then d.',
+    description: 'Opens Claude Code or Codex directly. --resume continues a project conversation. With --json it starts detached and prints the session. Detach with Ctrl-] then d. From a shell with no terminal of its own (a coding agent\'s) it opens in a new tab of your terminal app, the one agents targets --terminal chose (0.20.1+).',
     positionals: [{ name: 'path', required: true }, { name: 'claude|codex' }], options: {
         ...AGENT_OPTIONS,
         ...MODEL_OPTIONS,
@@ -1267,6 +1288,9 @@ const AGENT_COMMANDS = [
             last: { type: 'boolean', description: 'This project’s most recent session.' },
             session: { type: 'string', value: '<id>', description: 'The session to move: a Claude Code session id or Codex thread id.' },
             path: { type: 'string', value: '<path>', description: 'The project folder (default: the current folder).' },
+            plan: { type: 'boolean', description: 'Inspect all registered worktree paths, reference hits and file bytes before any upload.' },
+            'preserve-all-worktrees': { type: 'boolean', description: 'Also bring every registered worktree, all local refs, indices and ignored files. Reports paths and bytes; keeps a durable recovery archive.' },
+            'this-worktree-only': { type: 'boolean', description: 'Move the session’s checkout only (the default): other worktrees and local refs stay on this computer.' },
             claude: { type: 'boolean', description: 'With --last or --list: Claude Code sessions only.' },
             codex: { type: 'boolean', description: 'With --last or --list: Codex sessions only.' },
             list: { type: 'boolean', description: 'List this project’s sessions on this computer, and where the moved ones continue.' },
@@ -1277,7 +1301,8 @@ const AGENT_COMMANDS = [
     { path: ['conversations', 'try'], summary: 'Try a conversation in a synced local worktree', positionals: [{ name: 'conversation', required: true }], options: { path: { type: 'string', value: '<path>', description: 'Local project checkout.' }, stop: { type: 'boolean', description: 'Stop the device helper’s local sync and ports.' } } },
     { 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.' },
-            'open-in': { type: 'string', value: '<app=target,…>', description: 'Where new conversations open (0.17.0+): claude=terminal|claude-desktop|web|t3, codex=codex-app|t3, e.g. claude=t3,codex=t3.' },
+            'open-in': { type: 'string', value: '<target|app=target,…>', description: 'Where new conversations open (0.17.0+): claude=terminal|claude-desktop|web|t3, codex=codex-app|t3, e.g. claude=t3,codex=t3; a bare target sets every app that opens there, e.g. terminal or t3 (0.20.1+).' },
+            terminal: { type: 'string', value: '<app>[:tab|:window]', description: 'The terminal app terminal conversations open in (0.20.1+): ghostty, iterm, terminal, wezterm, kitty, alacritty or warp, a new tab in its front window (:window for a window); auto clears the choice.' },
             path: { type: 'string', value: '<path>', description: 'Local project folder whose T3 Code state and open_in to report, as agents new --path names it (default the current folder; the agent argument wins) (0.17.0+).' },
         } },
     ...['claude-desktop', 'codex-app', 'web', 't3'].map(target => ({ path: ['agents', 'open', target], summary: `Open the agent in ${target}`, positionals: [{ name: 'agent' }], options: { reachable: AGENT_OPTIONS.reachable } })),
@@ -1291,7 +1316,12 @@ const AGENT_COMMANDS = [
         },
     })),
     ...['status', 'enable', 'disable'].map(action => ({ path: ['agents', 'codex', action], summary: `${action} the account's billed Codex Cloud connector`, positionals: [], options: {} })),
-    { path: ['agents', 'open'], summary: 'Open a conversation (Codex Cloud or the native Claude session)', description: 'Codex opens its existing Cloud thread without waking its VM. Claude attaches its native 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|auto|claude-desktop|codex-app|web|t3>', description: 'Where to open it. auto (0.15.1+): the saved target, else a Claude conversation in Claude Desktop when it is installed, else in this terminal; web opens claude.ai.' } } },
+    { path: ['agents', 'open'], summary: 'Open a conversation (Codex Cloud or the native Claude session)', description: 'Codex opens its existing Cloud thread without waking its VM. Claude attaches its native session.', positionals: [{ name: 'agent', required: true }], options: { ...AGENT_OPTIONS, original: { type: 'boolean', description: 'Open the original Codex Cloud history after a connector change.' }, history: { type: 'string', value: '<thread-id>', description: 'Open an earlier thread listed in the Cloud conversation history.' }, app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default remembered choice).' }, in: { type: 'string', value: '<terminal|auto|claude-desktop|codex-app|web|t3>', description: 'Where to open it. auto (0.15.1+): the saved target, else a Claude conversation in Claude Desktop when it is installed, else in this terminal; web opens claude.ai. terminal (0.20.1+): a new tab of the terminal app agents targets --terminal chose, or this terminal when it is that one.' },
+            window: { type: 'boolean', description: 'With --in terminal: a new window of the terminal app instead of a tab (0.20.1+).' } } },
+    { path: ['agents', 'terminal-run'], hidden: true, summary: 'Run a command in the terminal app agents targets --terminal chose (0.20.1+)', positionals: [{ name: 'command', required: true, variadic: true }], options: {
+            cwd: { type: 'string', value: '<path>', description: 'The folder the new tab starts in (default the current folder).' },
+            window: { type: 'boolean', description: 'A new window instead of a tab.' },
+        } },
     { path: ['agents', 'computers'], summary: 'List the project’s computers a new thread can start on with --on, and the threads on each (0.16.0+)', positionals: [], options: {
             path: { type: 'string', value: '<path>', description: 'Local project path (default the current directory).' },
         } },
@@ -1323,7 +1353,11 @@ const CLI_PROXY_COMMANDS = [
     { path: ['cli-proxy', 'import'], summary: 'Move CLIProxyAPI from this computer into your account, reachable at 127.0.0.1:8317 everywhere', description: `${CLI_PROXY_HELP} Import brings your config and logins over, stops the local copy (one copy refreshes each login), and connects this computer and your machine template. On a second computer it connects that computer.`, positionals: [], options: {
             config: { type: 'string', value: '<path>', description: 'Your CLIProxyAPI config file (default: the one the running CLIProxyAPI uses, else the usual locations).' },
             yes: { type: 'boolean', description: 'Stop the local CLIProxyAPI without asking.' },
+            use: { type: 'string', multiple: true, value: '<email|file>', description: 'Serve its provider with only this login; the provider’s others are kept, disabled (repeatable, one per provider). Default: every login as it is on this computer.' },
         }, examples: ['shard cli-proxy import', 'shard cli-proxy'] },
+    { path: ['cli-proxy', 'use'], summary: 'Choose which logins your hosted CLIProxyAPI uses: one for its provider, or all', description: 'Your hosted CLIProxyAPI routes requests across its enabled logins as its config says. `use <login>` keeps only that login enabled for its provider (the others stay in the hub, disabled); `use --all` enables every login again.', positionals: [{ name: 'login' }], options: {
+            all: { type: 'boolean', description: 'Enable every login; the hub routes across them as its config says.' },
+        }, examples: ['shard cli-proxy use ana@example.com', 'shard cli-proxy use --all'] },
     { path: ['cli-proxy', 'export'], summary: 'Bring your logins back to this computer and stop the hosted CLIProxyAPI', description: 'The hosted copy stops first, so only this computer refreshes your logins from then on. Its logins, as last refreshed, go to the auth folder the import took them from (0600), this computer stops forwarding 127.0.0.1:8317, and the command that starts your local CLIProxyAPI is shown. shard cli-proxy import moves them back.', positionals: [], options: {
             yes: { type: 'boolean', description: 'Do it without asking.' },
         } },
@@ -1334,7 +1368,14 @@ 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, ...AGENT_ACCOUNT_COMMANDS, ...ACCOUNT_ALIASES, ...CLI_PROXY_COMMANDS, ...MENUBAR_COMMANDS, ...KEY_COMMANDS, ...ACCOUNT_COMMANDS.filter((c) => c.path[0] === 'templates')];
+const SETTINGS_COMMANDS = [{
+        path: ['settings'], summary: 'Show or change this computer’s settings for cloud conversations (0.20.1+)', positionals: [], options: {
+            'title-prefix': { type: 'string', value: '<text|none|default>', description: 'The marker your cloud conversations’ Claude session titles start with in claude.ai and the Claude app ("☁ Fix login bug · todo-app"): up to 16 characters on one line; none for no marker, default for ☁. New conversations use it.' },
+        },
+        description: 'Shows the title marker, where new conversations open and the terminal app (change those two with "shard agents targets --open-in" and "--terminal"). The menu bar and desktop apps change the same settings.',
+        examples: ['shard settings', 'shard settings --title-prefix SF', 'shard settings --title-prefix none', 'shard settings --title-prefix default --json'],
+    }];
+export const COMMANDS = [...ACCOUNT_COMMANDS.filter((c) => c.path[0] !== 'templates'), ...AGENT_COMMANDS, ...AGENT_CREDENTIAL_COMMANDS, ...AGENT_ACCOUNT_COMMANDS, ...ACCOUNT_ALIASES, ...CLI_PROXY_COMMANDS, ...MENUBAR_COMMANDS, ...SETTINGS_COMMANDS, ...KEY_COMMANDS, ...ACCOUNT_COMMANDS.filter((c) => c.path[0] === 'templates')];
 const GROUPS = {
     device: 'Local device approvals',
     'cli-proxy': 'Your hosted CLIProxyAPI, reachable at http://127.0.0.1:8317 on this computer and in every VM',
@@ -1358,7 +1399,7 @@ const GROUPS = {
     workspaces: 'Open, inspect and manage workspaces',
     'workspaces port': 'Serve ports of a workspace at private HTTPS URLs: expose, list, close, tokens, browser links and callback URLs (0.9.0+)',
     files: 'Read, write, list, search and patch files in a workspace',
-    operations: 'Inspect and wait for lifecycle operations',
+    operations: 'Inspect lifecycle operations, wait for outcomes and cancel suspension preparation',
     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',
@@ -1510,8 +1551,9 @@ function toParseArgsOptions(opts) {
  * returns help text for --help, bare groups and non-TTY bare `shard`.
  */
 export function parseCommandLine(argv, options = {}) {
-    // `acp --login` is the ACP terminal sign-in an editor runs (ACP appends the method's args to `shard acp`).
-    if (argv.length === 2 && argv[0] === 'acp' && argv[1] === '--login')
+    // The ACP terminal sign-in an editor runs: T3 Code appends the method's args to `shard acp` (`acp --login`); clients
+    // following the ACP registry replace the agent's args with them (`--login`, 0.21.1+).
+    if ((argv.length === 2 && argv[0] === 'acp' && argv[1] === '--login') || (argv.length === 1 && argv[0] === '--login'))
         return { kind: 'run', command: { path: ['acp'], summary: '', positionals: [], options: {} }, values: { login: true }, positionals: [], global: { apiUrl: undefined, json: false, agentLabel: undefined, wake: undefined, wakeTimeout: undefined } };
     // `menubar refresh` (0.15.2+, not in help): the background step each command may start (menubar.ts).
     if (argv.length === 2 && argv[0] === 'menubar' && argv[1] === 'refresh')
@@ -1724,7 +1766,7 @@ export function groupHelp(prefix) {
     const group = words.join(' ');
     const cmds = COMMANDS.filter((c) => !c.hidden && words.every((w, i) => c.path[i] === w));
     const w = Math.max(...cmds.map((c) => usageLine(c).length));
-    return [`Usage: shard ${group} <command> [options]`, '', `${GROUPS[group] ?? GROUPS[words[0]] ?? ''}.`, '', 'Commands:', ...cmds.map((c) => `  ${usageLine(c).padEnd(w)}  ${c.summary}`), ...(group === 'workspaces' ? ['', 'Also: shard workspaces files <read|write|ls|stat|search|patch> ..., shard workspaces operations <list|get|wait> ... and shard workspaces executions get ...'] : []), '', `Run "shard ${group} <command> --help" for details.`].join('\n') + '\n';
+    return [`Usage: shard ${group} <command> [options]`, '', `${GROUPS[group] ?? GROUPS[words[0]] ?? ''}.`, '', 'Commands:', ...cmds.map((c) => `  ${usageLine(c).padEnd(w)}  ${c.summary}`), ...(group === 'workspaces' ? ['', 'Also: shard workspaces files <read|write|ls|stat|search|patch> ..., shard workspaces operations <list|get|wait|progress|cancel> ... and shard workspaces executions get ...'] : []), '', `Run "shard ${group} <command> --help" for details.`].join('\n') + '\n';
 }
 export const EXIT_CODE_HELP = [
     '  0    success',
@@ -1740,7 +1782,7 @@ 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: 'Cloud agents (shard ./ starts one; a project API key)', groups: ['conversations', 'move', 'machine', 'template', 'agents', 'accounts', 'device', 'cli-proxy', 'ssh-proxy'] },
+    { title: 'Cloud agents (shard ./ starts one; a project API key)', groups: ['conversations', 'move', 'machine', 'template', 'agents', 'settings', 'accounts', 'device', 'cli-proxy', 'ssh-proxy'] },
     { title: 'Workspaces for your app (a project API key: SHARDFLUX_API_KEY, else the one shard setup saved)', groups: ['login', 'whoami', 'status', 'usage', 'workspaces', 'files', 'operations', 'executions', 'secrets', 'credentials', 'volumes', 'egress'] },
     { title: 'Templates for your app’s workspaces (not for cloud agents; publish and archive use the session, the rest the API key)', groups: ['templates'] },
     { title: 'Other', groups: ['menubar', 'update', 'feedback', 'version'] },
@@ -1755,10 +1797,8 @@ export function topHelp() {
         '       shard <path> [claude|codex] [--approvals]',
         'Terminal: detach with Ctrl-] then d; /exit ends the agent session.',
         '',
-        'Setting Shardflux up with a coding agent? Ask your user one question first: is it for a SaaS platform (their',
-        'product runs VMs for its own customers through the API, SDK or MCP) or for their personal setup (their own cloud',
-        'coding agents: each Claude or Codex conversation gets its own VM)? "shard setup --guide" prints the steps of both',
-        '(0.17.1+; --json for a list); so does "shard" in a shell without a terminal.',
+        'Setting Shardflux up for someone as their coding agent? "shard setup --guide" prints how (0.17.1+; --json for a',
+        'list; so does "shard" in a shell without a terminal): you run every step, they answer multiple-choice questions.',
         '',
         'Feedback: shard feedback [options] <message...>',
         ...FEEDBACK_WHY.map((l) => `  ${l}`),
@@ -1779,6 +1819,7 @@ export function topHelp() {
         '  shard ./                                      # a conversation on this folder’s repository: Claude Code in its own VM (shard ./ codex: Codex; --resume: a saved one)',
         '  shard machine save                            # what every agent starts with: tools, logins, dotfiles, Claude/Codex config',
         '  shard template save                           # this project: toolchains, dependencies, services, project secrets',
+        '  shard template delete                         # start this project over from your machine; setup saves a new one',
         '  A VM is the coding template, then your machine, then the project template. Setup after shard ./ saves the',
         '  project template; machine and project templates are always saved from an agent’s VM, so they keep Claude Code,',
         '  Codex and the agent runtime. "shard templates" is for your own app’s workspaces, not for agents: a repository',

package/dist/bin.js

@@ -4,5 +4,9 @@
  * waits/streams cleanly (exit 130); a second Ctrl-C exits at once. Output is flushed before exiting (stdout/stderr
  * pipes are asynchronous on macOS). The `shardflux` npm bundle calls main() with its own identity instead.
  */
-import { main } from "./main.js";
+import { enableCompileCache } from 'node:module';
+// V8's compiled code for the CLI's modules is kept on disk (the OS temp directory) and reused: ~0.1 s off each
+// command's start (0.21.1+). Best effort: without a writable cache the CLI compiles as before.
+enableCompileCache?.();
+const { main } = await import("./main.js");
 await main();

package/dist/browser.d.ts

@@ -3,5 +3,16 @@ export declare function openerFor(url: string, env: Record<string, string | unde
     command: string;
     args: string[];
 };
-/** Starts the browser detached and returns whether it could be started; only http(s) URLs are opened. */
-export declare function openUrl(url: string, env: Record<string, string | undefined>): boolean;
+/** How long an opener that has not exited counts as a browser that started in the foreground ($BROWSER=firefox, or
+ * xdg-open running one): opened. xdg-open hands a link to the desktop and exits well within it. */
+export declare const OPENER_SETTLE_MS = 3000;
+/**
+ * Starts the browser detached and resolves whether it took the URL: false when the opener cannot start (no xdg-open:
+ * ENOENT) or exits with a failure (xdg-open exits 3 or 4 when nothing on the desktop opens the link, `open` 1), so the
+ * caller says to open the printed link; true when it exits 0 or is still running after `settleMs`. Only http(s) URLs
+ * are opened.
+ */
+export declare function openUrl(url: string, env: Record<string, string | undefined>, options?: {
+    platform?: NodeJS.Platform;
+    settleMs?: number;
+}): Promise<boolean>;

package/dist/browser.js

@@ -15,25 +15,41 @@ export function openerFor(url, env, platform = process.platform) {
         return { command: 'rundll32', args: ['url.dll,FileProtocolHandler', url] };
     return { command: 'xdg-open', args: [url] };
 }
-/** Starts the browser detached and returns whether it could be started; only http(s) URLs are opened. */
-export function openUrl(url, env) {
+/** How long an opener that has not exited counts as a browser that started in the foreground ($BROWSER=firefox, or
+ * xdg-open running one): opened. xdg-open hands a link to the desktop and exits well within it. */
+export const OPENER_SETTLE_MS = 3000;
+/**
+ * Starts the browser detached and resolves whether it took the URL: false when the opener cannot start (no xdg-open:
+ * ENOENT) or exits with a failure (xdg-open exits 3 or 4 when nothing on the desktop opens the link, `open` 1), so the
+ * caller says to open the printed link; true when it exits 0 or is still running after `settleMs`. Only http(s) URLs
+ * are opened.
+ */
+export function openUrl(url, env, options = {}) {
     let u;
     try {
         u = new URL(url);
     }
     catch {
-        return false;
+        return Promise.resolve(false);
     }
     if (u.protocol !== 'https:' && u.protocol !== 'http:')
-        return false;
-    const { command, args } = openerFor(u.toString(), env);
-    try {
-        const child = spawn(command, args, { stdio: 'ignore', detached: true, env });
-        child.on('error', () => undefined);
-        child.unref();
-        return true;
-    }
-    catch {
-        return false;
-    }
+        return Promise.resolve(false);
+    const { command, args } = openerFor(u.toString(), env, options.platform);
+    return new Promise((resolve) => {
+        let timer;
+        const done = (opened) => {
+            clearTimeout(timer);
+            resolve(opened);
+        };
+        try {
+            const child = spawn(command, args, { stdio: 'ignore', detached: true, env });
+            child.once('error', () => done(false));
+            child.once('exit', (code) => done(code === 0));
+            child.unref();
+            timer = setTimeout(() => done(true), options.settleMs ?? OPENER_SETTLE_MS);
+        }
+        catch {
+            done(false);
+        }
+    });
 }

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

@@ -1,5 +1,7 @@
 import type { AgentCredentialMetadata, CellClient, Workspace } from '@shardflux/sdk';
 import type { Ctx } from './commands.js';
+/** Someone types into this terminal: not --json, a TTY with raw mode, and not a coding agent's shell. */
+export declare function claudeTerminal(ctx: Ctx): boolean;
 export declare function requireClaudeTerminal(ctx: Ctx): void;
 export declare function cloudClaudeLogin(ctx: Ctx): Promise<AgentCredentialMetadata | undefined>;
 /** Parse only complete provider authorize links, including the native OSC-8 link. */
@@ -21,6 +23,26 @@ export declare function runWorkspaceLogin(ctx: Ctx, ws: Workspace, cell: CellCli
     cwd: string;
     urls: (output: string) => string[];
 }): Promise<boolean>;
-/** A transient Linux profile holds the initial pair; it is removed before an agent starts. */
-export declare function loginClaudeInWorkspace(ctx: Ctx, ws: Workspace): Promise<AgentCredentialMetadata>;
+/**
+ * The same sign-in without an attached terminal (0.20.1+: a coding agent's shell, --json, no TTY). The workspace PTY
+ * runs the login exactly as runWorkspaceLogin does; shard reads its output, opens the claude.ai link it prints, and
+ * opens a page on this computer where the person pastes the code claude.ai shows (the agent never sees it). The code
+ * and Enter go into the PTY; the page says "Signed in" once the login exited 0. True when it did.
+ */
+export declare function runWorkspaceLoginHeadless(ctx: Ctx, cell: CellClient, login: {
+    session: string;
+    argv: string[];
+    env: Record<string, string>;
+    cwd: string;
+    urls: (output: string) => string[];
+}, timeoutMs: number): Promise<boolean>;
+/**
+ * A transient Linux profile holds the initial pair; it is removed before an agent starts. `headless` (0.20.1+): the
+ * sign-in runs through the pages shard opens (runWorkspaceLoginHeadless) instead of an attached terminal.
+ */
+export declare function loginClaudeInWorkspace(ctx: Ctx, ws: Workspace, opts?: {
+    headless?: {
+        timeoutMs: number;
+    };
+}): Promise<AgentCredentialMetadata>;
 export declare function ensureCloudClaude(ctx: Ctx, ws: Workspace): Promise<void>;