@shardflux/cli 0.20.0 → 0.23.0

package/README.md

@@ -1,5 +1,13 @@
 # @shardflux/cli: `shard`
 
+Historical template file lists: reads queue checksum-verified reconstruction when a cold list is absent from the SQL cache. TypeScript SDK 0.27.0+ / Python 0.23.0+ wait full Retry-After for retryable API 409 file_list_indexing on GET/HEAD within the admission timeout. Template objects and version history stay available.
+
+Plan-derived API budgets (0.23.0+, SDK 0.27.0): `--json` error output includes `rate_limit` and `retry_after_seconds`; the text hint names the shared scope and delay. API request pacing follows the SDK admission timeout and preserves the request body. Reuse workspace credentials and reduce status polling when the returned budget asks for a delay.
+
+Exec survives a dropped connection (0.23.0+): a lost start response is retried with the same session ID and reattaches to the command that already started, and a cut-off JSON answer is retried within the same safe retry boundary.
+
+Suspension controls arrive in 0.22.0 (next coordinated release). `shard operations progress <operation-id>` reads the actual phase, host deadline, cancellation window and safe next action. `shard operations cancel <operation-id>` requests cancellation; `--wait --timeout 5m` waits for confirmed `suspend_canceled` recovery of the original workspace. Asynchronous acceptance is labeled separately. The owning host refuses cancellation outside validated preparation; after capture, wait for the outcome and resume if it succeeded. These commands never reset, replace or launch a provider turn. `--json` preserves the reported values; unavailable progress is explicit.
+
 The command line for [Shardflux](https://shardflux.dev): serverless VMs for AI agents. Open a
 persistent workspace by key, run commands in it, move files in and out, and suspend, resume, fork
 or delete it. From 0.5.0 it also does everything the web app does: create an account, sign in
@@ -13,6 +21,11 @@ idempotency keys, operation polling and tool-token handling.
 
 Requires Node.js 24 or later.
 
+T3 Connect (0.22.0+): `shard setup --inspect --t3-connect --org <id|slug>` signs in for that organization;
+`--project <id|slug>` selects its project. Without flags it uses the API key's project, then the saved default
+project. Status and Connect use the same person and organization, including a saved session without an API key;
+an explicit selection keeps the default credentials and target status. An approved T3 sign-in is reused.
+
 ## Support and bug reports
 
 [Report a bug](https://github.com/shardfluxdev/community/issues/new?template=bug_report.yml) or
@@ -41,8 +54,8 @@ shard ws tunnel customer-42/main --remote 8081 --to localhost:8081
 ```
 
 Commands in the workspace can then call `http://127.0.0.1:8081`. The target is dialed on the machine running
-`shard`. Half-close and resets pass through: a reset on either side reaches the other as `ECONNRESET` (0.14.5+). Ctrl-C closes the sockets and guest process. `--bind 0.0.0.0` selects all guest interfaces; loopback is the
-default. An open tunnel keeps the workspace awake, and persistent workspaces preserve it across explicit suspend/resume.
+`shard`. Half-close and resets pass through: a reset on either side reaches the other as `ECONNRESET` (0.14.5+). Ctrl-C closes the sockets and guest process. `--bind 0.0.0.0` selects all guest interfaces; loopback (`127.0.0.1`
+and `::1`, 0.22.0+) is the default. An open tunnel keeps the workspace awake, and persistent workspaces preserve it across explicit suspend/resume.
 
 The tunnel selects a streaming transport automatically when `pty` permission is granted. Choose `transport: 'pty'` or `transport: 'exec'` in the SDK, or `--transport pty|exec` in the CLI, to select it explicitly. The handle reports `transport`.
 
@@ -78,6 +91,8 @@ shard --help
 The [`shardflux`](https://www.npmjs.com/package/shardflux) package installs the `shard` command.
 Use `shard` for your projects, machine, templates and account.
 
+If npm reports `EACCES` or `EPERM`, install only Shardflux in your user directory: `npm install --global --prefix "$HOME/.local" shardflux@latest`. Run `"$HOME/.local/bin/shard"` (including `"$HOME/.local/bin/shard" update` for updates), or use `shard` if `command -v shard` points there. Keep npm config, PATH and other global packages unchanged; do not use sudo or chmod. [Installation help](https://docs.shardflux.dev/reference/cli#npm-permission-errors).
+
 ## Quick start
 
 Start a conversation on a local project (0.14.0+):
@@ -95,12 +110,24 @@ time `shard` runs, with launch at login enabled; `shard menubar stop` turns it o
 
 T3 Code uses one **Shardflux** provider; choose a Claude Code or Codex model to start that agent in the cloud.
 Model choices come from your cloud agent's session and use the same coding tools and settings as its terminal.
+Project files synchronize before each message and before its completion (0.22.0+): review remote edits in T3’s
+Changes panel and checkpoints, and send local edits to the next turn. Conflicting versions are retained with
+a `.shard-conflict-<agent>` suffix. Sync runs between turns; an idle T3 thread needs no file watcher.
 The provider is registered automatically when T3 Code is installed, on macOS and on Linux from its .deb or AppImage
 (0.17.0+). Choose **Sign in** on its card in T3's provider settings: T3 runs `shard acp --login` in its own terminal,
 which creates or signs in to your account (with this computer's Codex login, or your email) and connects Claude Code
-and Codex, skipping every step that is already done (0.15.0+).
+and Codex, skipping every step that is already done (0.15.0+). Editors that launch agents from the ACP registry
+run the same sign-in as `shard --login` (0.22.0+).
 With T3 Code 0.0.45, `shard agents new --in t3` adds the project as an SSH environment instead.
 
+ACP journal read reattachment uses bounded backoff through temporary lifecycle interruptions (0.23.0+). It keeps the saved sequence and never resubmits an uncertain turn.
+
+In CLI 0.22.0+, `shard setup --inspect` shows a stopped T3 Connect workspace link and its remedy without restarting
+the link or replacing your approved sign-in. `shard agents open t3` brings T3 Code up once the workspace is linked
+(0.23.0+): a refused link answers `t3_link_failed` with what to do (for T3 Connect's environment limit, remove an
+environment in T3 Code → Settings → Connections, `details.recovery`), and a link still in progress after 30 seconds
+answers `t3_link_pending`. Both name the workspace and conversation: open it again with `shard agents open t3`.
+
 Start another thread on a computer that is already set up (0.16.0+): it shares that conversation's installed
 packages, caches, running services, ports and files, and works on its own branch and worktree.
 
@@ -138,11 +165,28 @@ shard move --list                  # the project's sessions, and where moved one
 shard move --session 3d085e35-aa66-4866-9a53-f09719d6767c --detach --json
 ```
 
+The session's checkout moves, uncommitted edits included; the repository's other worktrees and local branches stay
+on this computer (0.23.0+; `--this-worktree-only` says so explicitly). When the session also worked in another
+worktree, the move names it in one line (`other_worktrees` in `--json`). To bring every registered worktree, all
+local refs, indices and ignored files too, inspect the exact paths and file bytes with
+`shard move --last --plan --json`, then move with `--preserve-all-worktrees` (0.22.0+). Preserve-all includes ignored dependency/build caches; tar headers add to the displayed file bytes and the VM
+and project space need free disk for the copies. It never follows symlinks into unrelated sibling folders.
+The source checkout stays untouched. Cloud worktrees keep their staged/unstaged state; the selected tree runs on
+the conversation's branch while its original branch and HEAD remain in the recovery archive. Git location
+pointers are repaired for the VM. The result's `preserved.snapshot` names an immutable migration-time snapshot
+in the project space. Its `restore.py manifest.json <empty-folder>` command restores the original repository
+state into a new folder and refuses to overwrite continued work. It is a recovery snapshot, not an ongoing
+backup of later edits in other worktrees. External object alternates, nested repositories and special files need
+resolution before preserve-all can upload; a registration whose folder is gone has nothing to copy and is listed as
+`stale_registrations`.
+
 A running turn finishes here first. Uncommitted edits come along, and your working tree, index and branch stay as
 they are. The cloud work comes back to your checkout by itself, and typing in the local Claude Code copy shows one line
 that it continues in the cloud. Sessions from Claude Desktop's Code tab and the Codex app move the same way; in the
 macOS menu bar, a project's recent sessions have **Move to cloud** in their ⋯ menu, and with the Shardflux MCP server
-you can ask the agent itself to continue in the cloud.
+you can ask the agent itself to continue in the cloud. A session is listed under every repository it worked in, also
+one that began in another folder such as Claude Desktop's scratch folder, and `--path <repository>` moves it from
+anywhere (0.22.0+).
 
 Start a thread in T3 Code from the command line (0.17.0+):
 
@@ -153,8 +197,26 @@ shard agents targets --open-in claude=t3,codex=t3   # shard ./ starts new conver
 
 The first message becomes a T3 thread and T3 comes to the front. With the Shardflux provider the thread runs in its own
 cloud VM; with T3 Code 0.0.45 it runs on the T3 server in the project's VM, or with `--on` on that computer's.
-`--image` attaches images. `shard agents targets --json` shows T3 Code's mode and where each app's new conversations
-open; `shard agents open t3 <conversation>` brings its thread back.
+`--image` attaches images. `shard agents targets --json` shows T3 Code's mode, where each app's new conversations
+open, and every place each app can open (`open_in_targets`, 0.22.0+); `shard agents open t3 <conversation>` brings its
+thread back, and a Codex Cloud conversation's chat opens in your browser (0.23.0+). Answer a Codex Cloud
+conversation with `shard conversations send <id> "<answer>"` (0.23.0+ names it when you open one). Codex opens in a terminal app on macOS too (0.22.0+): `shard agents targets --open-in codex=terminal`.
+
+`shard settings --title-prefix <text|none|default>` (0.22.0+) sets the marker your Claude conversations' titles start
+with in claude.ai and the Claude app (default `☁`: "☁ Fix login bug · todo-app"); `shard settings` shows it with where
+conversations open.
+
+Terminal conversations open in the terminal you choose (0.22.0+):
+
+```sh
+shard agents targets --terminal ghostty        # a new tab in Ghostty's front window (Ghostty 1.3+); :window for a window
+shard agents targets --json                    # terminals on this computer, the one shard runs in, the saved choice
+shard agents open acme/main --in terminal      # opens it there, in the project folder
+```
+
+iTerm2, WezTerm, kitty and Warp open a tab too; Terminal and Alacritty a window. When the chosen app can't be driven
+(for example Automation not allowed) the next one opens and the line says what to allow. `shard ./` run by a coding
+agent opens the new conversation there.
 
 Git fetch and push use the coding guest’s platform transport when available, preserving Git’s binary packets (0.14.0+). Older guests retain their existing transport.
 
@@ -193,27 +255,17 @@ shard conversations landing backups    # then: shard conversations landing resto
 For application workspace commands, `shard signup` creates an account and saves a project key, or set
 `SHARDFLUX_API_KEY` to a key from the console and run `shard login`. `shard --help` lists every command.
 
-## Feedback: agents, use this while you work
+## Feedback: preview and user approval
 
-**(0.5.0+)** `shard feedback` sends a message straight to the Shardflux team, who read every one. If you are a
-coding agent (Claude Code, Codex, Cursor, ...) driving `shard`, use it actively while you work, not once at the end.
-Send a short message the moment:
+**(0.22.0+)** `shard feedback` previews the exact message, category and context without sending. Add `--yes` only after reviewing that preview and obtaining explicit user authorization. Earlier CLI versions send immediately.
 
-- something fails unexpectedly (`--category bug`),
-- an error, doc, name or output is confusing (`--category confusing`),
-- a capability, option or template you need is missing (`--category missing`),
-- 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.
+Coding agents: report only when your user asks to send feedback. Show the exact message and context first, then obtain explicit authorization. A failure or request for a feature is not consent. Leave out private data, secrets and code the user did not mean to share; paraphrase, never paste transcripts. Tell the user what was sent.
 
-Short and frequent beats polished: what you ran, what happened, what you expected. 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. Pass the request id and error code from the error so the team can find the logs. A failed
-`shard` command ends with a ready-made line to fill in:
+Keep the request id and error code from the failure. The suggested command previews a report; it never includes `--yes`:
 
 ```text
 error: Operation not found. [code=not_found status=404 request_id=req-2b9d4f6a8c0e4a1b3d5f7e90]
-feedback: shard feedback --category bug --request-id req-2b9d4f6a8c0e4a1b3d5f7e90 --error-code not_found "<what you expected>"
+feedback: shard feedback --category bug --request-id req-2b9d4f6a8c0e4a1b3d5f7e90 --error-code not_found "<what you expected>" # preview only; show the message and context, then use --yes only after explicit user authorization
 ```
 
 ```sh
@@ -225,13 +277,17 @@ shard feedback --category praise forking a workspace with its dev server still r
 npm test 2>&1 | tail -n 60 | shard feedback --category bug --workspace acme/demo --from-file -
 ```
 
+The commands above only preview. After the user approves the exact message and context, repeat the chosen command with `--yes` to submit. Re-preview file or piped input if its contents changed.
+
+
 - The message is the remaining arguments joined with spaces. Quote it, or put it after `--`, when it contains shell
   characters or words starting with `-`. `--from-file <file|->` reads it from a file or standard input instead. 1-8000
   characters.
 - Options: `--category bug|confusing|missing|idea|praise|other` (default `other`), `--workspace <id|key>`,
   `--request-id <id>`, `--error-code <code>`, `--command <text>` (what you ran). Name the reporting agent with
   `--agent-label` or `SHARDFLUX_AGENT_LABEL` (e.g. `claude-code`); `shard` adds its own version as the client.
-- Output: one line with the feedback id. `Already received` means the same message was sent from this key in the last
+- Preview output includes `sent: false`, `authorization_required: true`, `preview` and `note` with `--json`.
+- Approved submission output: one line with the feedback id. `Already received` means the same message was sent from this key in the last
   24 hours; it is not emailed again. With `--json`: `{"id", "received_at", "duplicate"}`.
 - It sends with the project API key (any key; no tool permission), or, when no key is configured yet, with your
   signed-in session (`shard auth login`), so it works while you are still setting up. It is rate limited per key or
@@ -244,52 +300,70 @@ npm test 2>&1 | tail -n 60 | shard feedback --category bug --workspace acme/demo
 or the shell is a coding agent's (Claude Code, Codex, Cursor, Gemini CLI; 0.17.1+), `--json` on every command, secrets
 only on standard input, and documented exit codes.
 
-**Ask your user one question first:** is Shardflux 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 both paths with every command, `--json` as a list
-(0.17.1+); so does `shard` in a shell without a terminal. The full walk-through:
-[Set up Shardflux with your coding agent](https://docs.shardflux.dev/guides/agent-setup).
-
-1. **Account, for both.** Show your user the [Terms of Service](https://shardflux.dev/terms) and the
-   [Privacy Policy](https://shardflux.dev/privacy); once they agree, `shard signup --accept-terms --json`. With the
-   Codex CLI signed in with ChatGPT on the machine it signs up (or signs in) with that login and runs `shard setup`:
-   an organization, a project and an API key, saved. Without a Codex login, or for an account they already have:
-   `shard auth login --browser --no-wait --json` prints the link and the code for your user and returns (0.17.1+);
-   `shard auth login --browser --json` then waits for that same request (run it again if your tool's time limit cuts
-   it off), and `shard setup --json` saves the key. With two-factor authentication a password sign-in exits 4 with
-   `mfa_required`: ask for the code, then `shard auth mfa --code <code>`.
-
-**SaaS platform** (no agent sign-ins, menu bar or machine):
+**You run permitted steps; your user decides** (0.22.0+): ask one multiple-choice question at a time with the
+recommended answer first, keep each message to a sentence or two, and never ask for a secret or sign-in code in
+the chat. They answer your questions, agree to the Terms, approve sign-ins in the browser tabs
+shard opens and type secrets into the page shard opens. `shard setup --guide` prints the whole order with every
+command, `--json` as a list with each step's `choices` (0.17.1+); so does `shard` in a shell without a terminal. The
+full walk-through: [Set up Shardflux with your coding agent](https://docs.shardflux.dev/guides/agent-setup).
+
+If a permission system or auto-mode classifier refuses an action, stop that action. Explain the reason and hand
+your user the exact refused command to run in their own terminal; ask only for its non-secret result, then resume
+permitted steps. Do not change permission settings, wrap the action in a script or use another tool to bypass the
+refusal. A plugin install needs confirmation that the plugin is installed; machine opening needs the workspace
+key. If setup output or a status check is refused, have your user run `shard setup --guide --json` and confirm
+`guide.signed_in.email` and `guide.api_key_saved`. This local check never prints the credentials and does not prove
+that the key works. Never read redirected logs or credential files instead. An exit code alone does not prove
+onboarding; keep blocked or unobserved behavior unverified.
+
+First ask what it is for: their own cloud coding agents (each Claude or Codex conversation gets its own VM; the usual
+answer) or their product (it runs VMs for its customers through the API, SDK or MCP).
+
+1. **Account, for both.** Ask whether they agree to the [Terms of Service](https://shardflux.dev/terms) and the
+   [Privacy Policy](https://shardflux.dev/privacy) (Yes / No); then `shard signup --accept-terms --json`. With the
+   Codex CLI signed in with ChatGPT on the machine it signs up (or signs in) with that login and runs `shard setup`: an
+   organization, a project and an API key, saved. Without a Codex login, or for an existing account, `shard auth login
+   --browser --json` opens the sign-in page and waits until they approve it (run it again if your tool's time limit cuts
+   it off: it waits for the same request), then `shard setup --json`.
+
+**Their own cloud coding agents:**
+
+2. **Connect Claude and Codex.** Ask which they use (Claude Code and Codex / Claude Code / Codex). `shard agents
+   credentials login claude --json` opens the claude.ai sign-in and a page for its code in their browser (0.22.0+);
+   Codex Cloud uses this computer's ChatGPT sign-in (`codex login`); copy it with `shard setup`.
+   `shard setup --inspect --connect --json --apps claude,codex`
+   (0.15.0+) checks both live, copies the Codex login and starts the account's Codex remote device.
+3. **Set up the machine** every conversation starts from: ask "Set up your cloud machine from this computer?" (Yes /
+   Not now), then `shard machine setup --from-this-computer --json` (0.20.0+): this computer's Claude Code or Codex
+   recreates its tools, runtimes, shell, git identity and dotfiles there and saves it. Anything more they want: `shard
+   machine open --json`, `shard ws exec <key> -- bash -lc '...'`, `shard files write <key> <path> --ask` for a secret
+   file they type in the page (0.22.0+), and `shard machine save --wait --json`.
+4. **Choose where conversations open** (0.22.0+): `shard agents targets --json` lists the apps on this computer;
+   offer them (the terminal shard runs in first: Ghostty, iTerm2, WezTerm, kitty, Warp, Terminal; or the Claude app,
+   the Codex app, T3 Code) and save the answer with `shard agents targets --open-in <target> --terminal <app>`.
+5. **Set up the project.** Ask whether it needs secrets (No / type them in a secure page / from their vault): `shard
+   secrets create NAME --ask --json` opens a page where they type the value, `shard secrets import --from
+   <hsec|1password|bitwarden|keychain> NAME` reads a vault item. Then, in its folder, `shard ./ --json --prompt "Set up
+   this project and run its tests"` starts a conversation in its own VM (`shard ./ codex --json ...` for Codex); setup
+   installs the dependencies and saves the project template. `shard conversations wait <conversation-id> --timeout 90`
+   follows it (run it again while it says Still working).
+6. **Open the first conversation:** `shard ./` opens it in the app they chose. Claude conversations continue on
+   claude.ai and in the Claude app; Codex threads in the Codex app, on the web and on the phone.
+
+Commands that wait for your user in the browser (sign-ins, `--ask`) take up to 10 minutes: run them with a long timeout
+or in the background.
+
+**Their product** (no agent sign-ins, menu bar or machine):
 
 2. `eval "$(shard env)"` exports `SHARDFLUX_API_KEY` for the SDKs, the MCP server and your product's server. Keep it in
    server-side secrets.
-3. Integrate with `@shardflux/sdk`, the Python SDK `shardflux`, the HTTP API or the MCP server. Your customers'
-   workspaces start from a template: `shard templates build template.yaml`. `shard exec <key> --template default --
-   <cmd>` tries a workspace from here (0.10.0+).
+3. Ask how the product calls Shardflux (TypeScript SDK / Python SDK / HTTP API / MCP server) and integrate with
+   `@shardflux/sdk`, the Python SDK `shardflux`, the HTTP API or the MCP server. Your customers' workspaces start from
+   a template: `shard templates build template.yaml`. `shard exec <key> --template default -- <cmd>` tries a workspace
+   from here (0.10.0+).
 4. A paid plan: `shard billing upgrade <plan> --json` prints the Stripe Checkout URL; give it to your user, then
    `shard billing upgrade <plan> --wait` (or `shard billing status`) until it is active.
 
-**Personal setup** (their own cloud coding agents):
-
-2. **Connect Claude and Codex.** Claude: your user runs `shard agents credentials login claude` in their own terminal,
-   once (a claude.ai link and a code). Codex: `codex login` on this computer. Then
-   `shard setup --inspect --connect --json --apps claude,codex` (0.15.0+) checks both live, copies the Codex login and
-   starts the account's Codex remote device.
-3. **Build the machine** every conversation starts from. `shard machine setup --from-this-computer --json` (0.20.0+)
-   has this computer's Claude Code or Codex recreate its tools, runtimes, shell, git identity and dotfiles there and
-   saves it. For the rest, ask your user what it should carry: languages and runtimes,
-   CLIs and tools, dotfiles and shell, secrets and credentials, editor and agent config. Then
-   `shard machine open --json` (0.17.1+) prints the machine VM's key; install with
-   `shard ws exec <key> -- bash -lc '...'`, write dotfiles and secret files with
-   `shard files write <key> <path> --from -` (contents on standard input), and `shard machine save --wait --json`.
-4. **Set up the project.** In its folder, `shard ./ --json --prompt "Set up this project and run its tests"` starts a
-   conversation in its own VM (`shard ./ codex --json ...` for Codex); setup installs the dependencies and saves the
-   project template. `shard conversations wait <conversation-id> --timeout 90` follows it (run it again while it says
-   Still working), and `shard template --json` shows the saved version. Project secrets:
-   `shard secrets import --from <hsec|1password|bitwarden|keychain> NAME`.
-5. **Hand over.** Your user runs `shard ./` in their own terminal. Claude conversations continue on claude.ai and in the
-   Claude app; Codex threads in the Codex app, on the web and on the phone.
-
 Any time: `shard setup --json` is idempotent, and sensitive actions (exports, deletions, two-factor and email changes)
 need a recent step-up: `printf '%s\n' "$PASSWORD" | shard auth step-up` (without a terminal the command fails with
 `step_up_required`, exit 4, and the hint names this command). Send `shard feedback` as you work, the moment something
@@ -384,8 +458,9 @@ shard auth totp recovery-codes
 3. an API key with every workspace tool, `computer` included (0.15.1+; `--tool` repeatable to narrow it), named
    `shard-cli <hostname>` (`--key-name`), saved in the credentials file and checked against the API.
 
-`shard setup --guide` (0.17.1+) prints how to set Shardflux up with a coding agent: the question to ask first (a SaaS
-platform, or the user's own cloud coding agents) and the ordered steps of both; `--json` gives them as a list.
+`shard setup --guide` (0.17.1+) prints how to set Shardflux up with a coding agent: how to run it (the agent does
+permitted steps and hands off actual policy refusals, the user answers multiple-choice questions; 0.22.0+), the
+question to ask first and the ordered steps of both answers; `--json` gives them as a list with each step's `choices`.
 
 It is idempotent: a saved key that still works is kept (`--new-key` makes a new one). A saved key from an earlier
 `shard setup` (every tool but `computer`) is replaced with one that has every tool (0.15.1+); the old key keeps working
@@ -412,6 +487,7 @@ shard orgs workspaces [org] [--project P] [--state S] [--all]   # every project'
 shard orgs deletion [org]                         # what deleting would do, and what blocks it
 shard orgs delete <org> --confirm <slug> --yes    # irreversible (step-up)
 shard projects list | create <name> [--slug] [--use] | get <project> | use <project>
+shard projects sync add | pause | remove <path> | list   # projects kept ready for new conversations (0.22.0+)
 shard api-keys list | create <name> [--tool T]... [--read-only] [--expires 30d|90d|365d|never] [--save] | revoke <id|key_id> --yes
 shard members list | set-role <user|email> <owner|admin|member|billing> | remove <user|email> --yes
 shard invitations list | create <email> --role <role> | revoke <id|email> | accept '<link>' [--use]
@@ -422,6 +498,23 @@ shard templates publish <slug>@<version> | archive <slug>@<version>
 what it is on stderr; `--json` includes it as `secret`; `--save` stores it in the credentials file for
 the workspace commands instead of printing it. Revoking the saved key also removes it from the file.
 
+In more than one organization (0.22.0+): workspace, agent and usage commands act where the API key belongs, account
+commands where the default is. `orgs use` and `projects use` say when the key belongs to another organization and
+name the command that makes one for the new default (`shard setup --org <org> --new-key`; in a terminal they offer to
+run it). With a signed-in session, `whoami` distinguishes a saved default or key from an organization you left from
+a key in another organization you still belong to. Warnings name `shard orgs use <org>` for a stale default and
+`shard setup --org <org> --new-key` for the key. The switches preserve the key unless you accept the replacement
+prompt. `SHARDFLUX_API_KEY` wins over the saved key: recovery saves the replacement, then you must unset the
+environment variable to use it. `--json` carries the same `warnings` (`code`, `message`, `fix`); `setup --json`
+also warns when the environment key still overrides its saved key. `shard usage --org <org>` reads any of your
+organizations with your signed-in session.
+
+For organization usage (0.22.0+), the summary, estimate and series keep using your project key in its own
+organization. An explicit `--org <id|slug>` for another organization uses your session only when you are a member.
+Without a session, sign in with `shard auth login`; to save a project key for that organization, then run
+`shard setup --org <org> --new-key`. If `SHARDFLUX_API_KEY` is set, unset it after saving the new key so the saved
+key takes effect. Workspace usage keeps the project key's authorization, and API errors stay errors.
+
 ## Billing (0.5.0+)
 
 ```sh
@@ -586,7 +679,7 @@ shows the status; `shard version --check` asks now (`--json`: `{"cli", "sdk", "u
 | `login`, `whoami` | Show the principal behind the project key (`SHARDFLUX_API_KEY`, else the saved one). |
 | `version [--check]` | Print the CLI and SDK versions and the update status (`--check` asks the API now). |
 | `usage [--org <id>] [--estimate \| --series \| --workspace <id\|key>] [--from T] [--to T] [--granularity hour\|day] [--meter M]` | Usage summary for the current period: plan, meters and allowances. `--estimate`: the bill so far and projected allowance use; `--series`: usage over time; `--workspace`: one workspace's usage over time (0.5.0+). The summary includes the [overage](#usage-and-overage) block (0.5.1+). |
-| `feedback [--category C] [--workspace W] [--request-id ID] [--error-code CODE] [--command TEXT] [--from-file F\|-] <message...>` | Send feedback straight to the Shardflux team (0.5.0+). See [Feedback](#feedback-agents-use-this-while-you-work). |
+| `feedback [--yes] [--category C] [--workspace W] [--request-id ID] [--error-code CODE] [--command TEXT] [--from-file F\|-] <message...>` | Preview feedback; `--yes` sends after explicit user authorization (0.22.0+). See [Feedback](#feedback-preview-and-user-approval). |
 | `workspaces open <key> --template <slug> [--secret NAME]... [--input NAME=value]... [--input-file F] [--lifetime persistent\|session] [--mode processful\|file-first] [--cpu-millis N --memory-mib N --disk-gib N] [--allocation-mode fixed\|elastic] [--memory-held N] [--no-wait] [--timeout 5m] [--timing]` | Open by key. Creates the workspace on first use and reconnects or resumes it afterwards, never resetting it. Waits until it is ready (the template's start commands and services included) unless you pass `--no-wait`. `--secret` binds secret names (replacing the binding of an existing workspace). `--input` (0.4.0+) passes the template's text inputs (replacing those of an existing workspace); `--input-file` reads `NAME=value` lines or a JSON object. `--lifetime session`: the workspace is discarded when the session ends (`workspaces close` or the idle timeout), and the key then opens a new workspace. `--mode file-first` (0.5.0+) opens a [file-first workspace](#file-first-workspaces); the default is processful for a new key and the stored mode for an existing one. `--allocation-mode elastic` (0.8.0+): [elastic memory](#elastic-memory-080). |
 | `workspaces list [--state S] [--prefix P] [--lifetime persistent\|session\|any] [--purpose standard\|template_draft\|template_test\|any] [--include-deleted] [--all] [--limit N] [--cursor C]` | One page, or every page with `--all`. The next cursor is printed on stderr. By default only persistent standard workspaces are listed. A file-first workspace's state reads `running (file-first)` (0.5.0+). |
 | `workspaces get <id\|key>` | One workspace (deleted ones included), with the startup of its template's start commands and services (0.4.0+): a failed step shows its exit code, reason and output tail. Its mode, and a file-first workspace's tree revision (0.5.0+). Its memory (0.8.0+): `fixed 4096 MiB`, or `elastic: promised …, held …, plugged +… MiB`. The template version whose [immutable paths](#immutable-paths-080) it has mounted (0.8.0+): `immutable paths  v3 (mounted read-only)`. |
@@ -1122,6 +1215,7 @@ For live progress events, use the SDK's `onProgress`.
 ```sh
 printf %s "$OPENAI_API_KEY" | shard secrets create OPENAI_API_KEY     # value from standard input
 shard secrets create DATABASE_URL --from-file ./database-url.txt      # or from a file
+shard secrets create GITHUB_TOKEN --ask                                # or typed in a page shard opens (0.22.0+)
 shard ws open acme/demo --template python-node-browser --secret OPENAI_API_KEY --secret DATABASE_URL
 shard ws exec acme/demo -- python3 agent.py                           # sees both as environment variables
 shard ws secrets acme/demo                                            # names and status, never values
@@ -1149,7 +1243,9 @@ printf %s "$NEW_KEY" | shard secrets rotate OPENAI_API_KEY
 - **`--json`:** stdout carries the API's own objects:
   - `workspaces open`/`get` print the workspace view; `list` prints `{data, next_cursor}`.
   - Lifecycle commands print the operation; `fork` prints `{operation, workspace}`.
-  - `login`/`whoami` print `{api_url, organization_id, project_id, api_key:{id,key_id}, tool_permissions}`.
+  - `login`/`whoami` print `{api_url, organization_id, project_id, api_key:{id,key_id}, tool_permissions}`; `whoami`
+    adds `warnings` (`code`, `message`, `fix`) for a departed organization or a key in another accessible default
+    organization (0.22.0+). Without a signed-in session, membership and default warnings are unavailable.
   - `exec` prints `{session_id, exit_code, term_signal, timed_out, canceled, stdout, stderr, truncated, reconnects}`.
     On a file-first workspace (0.5.0+), `exec` and `executions get` print the execution (see
     [File-first workspaces](#file-first-workspaces)).
@@ -1345,17 +1441,39 @@ Run `shard ./` in your project to start Claude Code or Codex, usable immediately
 
 New project folders are ready to use: `shard ./` and `shard agents new` initialize Git on `main` when needed and create an empty initial commit (CLI 0.14.2+). Existing files and staged work stay yours; the initial commit contains no files. Repositories without commits keep their current branch. If Git identity is missing, that one commit uses `Shardflux <noreply@shardflux.dev>` without changing your Git configuration.
 
+Machine saves require a machine source VM (`labels.shard_layer = "machine"`). On your computer, run
+`shard machine open --json`, make changes in that VM, then `shard machine save --wait`. The computer's CLI
+selects the machine VM; inside a VM, save uses that VM. A conversation or unmarked fork returns
+`filesystem_source_mismatch`: copy the intended files or repeat the install in the machine VM and save there.
+Project keys stay in their own project; a VM's native token cannot select another workspace.
+
 Your **machine** carries credentials, tools, dotfiles, logins and agent config; the project's **template** carries
 toolchains, dependencies, services and project secrets. Both are private filesystem templates and include secrets
 as ordinary files. Browser logins and Claude/Codex config belong to the machine. Set up tools and secrets normally inside the VM;
-your agent uses the same save/rollback commands there. An agent working from your computer builds the machine with
+your agent uses the matching machine or project save/rollback commands in its source VM. An agent working from your computer builds the machine with
 `shard machine open` (0.17.1+): it creates or resumes the machine VM without attaching and prints its key for
 `shard ws exec` and `shard files write`. `shard machine setup --from-this-computer` (0.20.0+) does it for you: your own
 Claude Code (`claude -p`, else Codex) recreates this computer's CLIs and tools, language runtimes, shell config and
 aliases, git identity and dotfiles on the machine, on your subscription, then saves it. On this computer it only reads;
 `~/.ssh`, keychains, `.env`, token and credential files are never read. The apps and the first run start it once,
-right after you connect your agents. Every agent starts from both. Save or roll back with `shard machine save|rollback` and
+right after you connect your agents. `shard machine setup --status` shows the machine as your account has it, in the
+same line the apps show: ready, saving (with its place in the queue), or the one command to run next (0.22.0+); `shard
+setup --inspect --json` carries it as `onboarding.machine`. `connections_ready` (and the legacy `ready` field) means
+your account and an agent are connected; it does not mean tools from this computer carry over. `machine_ready`
+requires a ready saved version. The row names the version in use, a failed build's full error and recovery, or no
+saved version. An older API reports `unavailable`; a failed check reports `unknown`, with `version: null` when it
+could not be read. Conversations can start while the machine is not ready (0.22.0+).
+Setup checks the granted disk limit and available space before installing;
+tools that do not fit are reported as skipped. A failed agent-config copy, an explicit Claude tool permission refusal, an agent that
+never reaches the VM, or an absent setup report stops before saving (0.22.0+). A permission refusal is not retried
+through another agent. Setup never changes your plan or disk caps. Run the command
+again after resolving the reported refusal or limit.
+Every agent starts from the saved machine and project template when available. Save or roll back with `shard machine save|rollback` and
 `shard template save|rollback`; changed files reach running agents live, software at the next start.
+`shard template delete` (0.22.0+) starts a project over from your machine: its saved versions go, new conversations
+start from your machine until setup saves a new one, and VMs running on it keep their files. In a terminal it asks
+first; scripts and agents pass `--yes`. `shard template` says when a template nobody used for 30 days follows your
+machine on its next use (0.20.0+).
 
 Skills, commands, agents, output styles, memories and `CLAUDE.md` / `AGENTS.md` lines that Claude or Codex saves in a
 cloud conversation come back to this computer by themselves, seconds after the turn ends, and into your saved
@@ -1363,6 +1481,9 @@ machine too (0.20.0+). A file you changed here at the same time keeps your versi
 (`CLAUDE.cloud.md`); a deleted one goes to the Trash. Project memory follows the project both ways. The menu bar says
 what arrived in one line, and `agent-config-return.jsonl` in the config directory lists every change.
 `shard machine save --wait` and `shard template save --wait` return once the new version is ready (0.13.3+).
+A version larger than the plan's workspace disk names its size and the disk, with `retryable: false` and a hint: delete
+what the VM does not need, then save again, or move to a plan with a larger disk (`shard billing plans`); `--json`
+`details` carry `error_code`, `limit`, `value` and `actual` (0.22.0+).
 Software installed under the home goes into the saved image, linked back at the same path; the save line names those
 folders, and `--json` carries `moved_to_image` (0.18.0+).
 `shard ./ codex` (or `claude`; `--codex` and `--claude` also work, 0.14.4+) starts that agent directly; `shard agents targets <project>/<agent>` lists each
@@ -1402,22 +1523,30 @@ Volume lists and details (0.14.0+) show `kind`. Project spaces show their measur
 
 ### Claude and ChatGPT/Codex accounts (0.18.0+)
 
-`shard agents accounts` lists your Claude and ChatGPT/Codex accounts with their plan, status, the account threads use
-and how much of each usage window is left:
+`shard agents accounts` lists your Claude and ChatGPT/Codex accounts with their plan, status, which one is active
+(0.22.0+) and how much of each usage window is left:
 
 ```
 Claude
-  claude:1  marc@example.com (Max, in use) · Signed in
+  claude:1  marc@example.com (Max, active) · Signed in
             5-hour 43% (resets in 2h 10m) · Weekly 18% (resets in 4d 8h)
+  claude:2  ops@example.com (Team) · Signed in
+            5-hour 12% (resets in 4h 5m) · Weekly 9% (resets in 6d 2h)
 ChatGPT / Codex
-  codex:1   marc@example.com (Pro, in use) · Signed in
+  codex:1   marc@example.com (Pro, active) · Signed in
             5-hour 12% (resets in 3h 30m) · Weekly 35% (resets in 4d 23h)
+Switch Claude: shard agents accounts use claude:<n>
 ```
 
+Each provider has one active account (0.22.0+). Its login is the one your conversations use: new conversations start
+with it and running ones switch to it. `shard agents accounts use claude:2` makes another account active; running
+Claude conversations continue on it and Remote Control turns back on by itself, and Codex Cloud moves to the active
+ChatGPT account. Organization owners and admins choose the active account: a team account, or their own personal one.
+Another member's personal account can be made active only by that member.
+
 `shard agents accounts usage` shows every window as a bar. `shard agents accounts add claude` (or `codex`) signs in
-another account in a cloud VM; `pbpaste | shard agents accounts add claude --api-key-stdin` adds an API key.
-`shard agents accounts move claude:2 up` changes an account's place and `shard agents accounts remove claude:2`
-removes it. `--json` prints the API's account list.
+another account in a cloud VM and `shard agents accounts remove claude:2` removes one. To remove someone else's active
+account, make another one active first; your own you can always remove. `--json` prints the API's account list.
 
 ## Conversations
 
@@ -1432,6 +1561,27 @@ Conversation JSON includes `join_mode` and the worktree used by reviewers and wo
 
 `shard conversations resume <id>` continues a saved conversation in a fresh VM under the same identity (0.14.0+). `shard ./ --resume` uses this same path. `shard conversations reader <project-id>` opens a small read-only workspace for saved branches and transcripts; the Mac transcript mirror opens it automatically when no project VM is live. Adaptive idle reclaims the reader.
 
+### Starting from your working state (0.22.0+)
+
+A new conversation starts from your worktree as it is: committed history, uncommitted edits, untracked files and your
+`.env` files. Its VM gets them from a project cache that every VM of the project shares, so a start sends only what the
+cache lacks: a second conversation on the same state sends nothing, and a one-file edit sends its delta. Parts travel
+in parallel and resume where they stopped. Large untracked images, audio and video land as files the conversation's
+Git ignores, as yours does, and large ones keep arriving after the agent has your prompt.
+
+### Prepared projects (0.22.0+)
+
+```sh
+shard projects sync add ~/code/web      # keep this project ready for new conversations
+shard projects sync list                # selected projects and their state
+shard projects sync pause ~/code/web    # stop preparing it (remove: forget it)
+```
+
+The device helper (started by the menu bar or the Linux app) prepares each selected project in a short-lived VM: it
+puts the project's current state in the project cache, and when its dependency files change, installs them and saves
+the project template. Conversations then start without sending the project, with dependencies installed. Only the
+projects you add are prepared; onboarding and Settings → Projects in both desktop apps choose them too.
+
 ### Menu bar conversation shortcut (0.15.0+)
 
 The macOS menu bar's **New conversation** action (menu bar 0.3.0+) opens the same launcher as **Option-Shift-Space**. It requires a task and project, remembers Claude/Codex, and invokes the commands below. Configure the hotkey in the macOS Settings window (⌘,), with conflict detection and a fallback.
@@ -1456,3 +1606,20 @@ New Codex conversations use `shard agents new --app codex --path <directory>` or
 `shard setup` uses your existing Codex ChatGPT login to register one executor for the account. Its small connector workspace stays resident and is billed as ordinary workspace memory/CPU usage, including while conversations wait. Use `--no-codex` to skip setup, `shard agents codex status` to inspect it, or `shard agents codex disable` to remove the executor and release its residency. Conversation VMs wake for tools and follow the normal adaptive idle policy afterwards.
 
 Explicit `agents new --in terminal`, `--in t3`, and `--like` launches keep their existing VM routes. Local Git is prepared and validated before Cloud enrollment. This branch's Cloud feature is awaiting release. Existing local-mode conversations keep their original route. Cloud uses OpenAI's model/configuration capabilities; local app-server plugins and settings are not automatically transferred.
+
+Save progress (0.22.0+): Machine and template saves show source size and an estimated duration, then queued/build state and phase updates immediately. With `--json`, progress events go to stderr and the final stdout document includes `preflight` and `phases`. Failure and timeout output retain the latest counters and `details.last_progress`, with the build id and recovery action. If an older API cannot expose the build, JSON stderr emits `save_started` with the version/build id and leaves the phase unknown. Missing final host reports preserve the last observed progress.
+
+Desktop launch cards (0.22.0+): the bundled desktop apps clear and close the launcher on submission, then show each pending start in a layered card stack near the top of the display. **Show all launches** expands individual statuses and recovery.
+
+
+### Pending execution cancellation (0.23.0+)
+
+On guests advertising `exec_cancel_pending.v1`, successful cancellation can return the actual `running` state
+with `canceled: true` while the kernel holds a killed process. The execution's `error` explains pending drain,
+and becomes unverified after 30 seconds without claiming an exit or freeing ownership. Read/follow that
+session until its real final status; repeat cancellation is idempotent. An already exited foreground keeps
+its result while descendant drain can remain pending. TS/Python agent tools and MCP expose the reason as
+`status_reason` and keep the exit code null while active. CLI prints the reason and follow command.
+Older clients read the same session response fields.
+
+Cloud history (0.23.0+): `shard agents open <conversation-id> --original` opens the original chat; `--history <thread-id>` opens an earlier linked chat. `--json` includes `previous_threads` with each history URL. Sign in with the Codex account that owns the selected chat.

package/dist/account-args.js

@@ -206,8 +206,8 @@ export const ACCOUNT_COMMANDS = [
             activity: { type: 'boolean', description: 'With --inspect: the current commands, listening ports, sudo installs and browser window of --workspace, without waking it.' },
             workspace: { type: 'string', value: '<key|conv_id>', description: 'The workspace or conversation to inspect for live onboarding activity.' },
             inspect: { type: 'boolean', description: 'Report the onboarding steps and verify every connection live (account, Claude, Codex) without changing anything.' },
-            apps: { type: 'string', multiple: true, value: '<claude,codex>', description: 'The apps to verify (default: the ones found on this Mac). Repeatable or comma separated.' },
-            connect: { type: 'boolean', description: 'With --inspect: also copy this Mac’s Codex login and enable the account’s Codex remote device when Codex is picked.' },
+            apps: { type: 'string', multiple: true, value: '<claude,codex>', description: 'The apps to verify (default: the ones found on this computer). Repeatable or comma separated.' },
+            connect: { type: 'boolean', description: 'With --inspect: also copy this computer’s Codex login and enable the account’s Codex remote device when Codex is picked.' },
             'retry-codex': { type: 'boolean', description: 'With --inspect --connect: start a Codex remote device that failed or is stuck starting again, once.' },
             't3-connect': { type: 'boolean', description: 'With --inspect: start your T3 Connect sign-in for T3 Code (0.0.45, over SSH); the t3 row carries its page and code (t3_link). After it, your projects appear in T3 Code and the T3 app (0.19.0+).' },
             'org-name': { type: 'string', value: '<name>', description: 'Name of the organization to create when you have none.' },
@@ -269,6 +269,11 @@ export const ACCOUNT_COMMANDS = [
         options: { confirm: { type: 'string', value: '<slug>', description: 'The organization’s slug, typed out (required).' }, ...YES('the deletion') },
     },
     { path: ['projects', 'list'], summary: 'List the organization’s projects (* marks the default)', positionals: [], options: { ...ORG } },
+    { path: ['projects', 'sync', 'list'], summary: 'Show selected local projects and their preparation state', positionals: [], options: {} },
+    { path: ['projects', 'sync', 'add'], summary: 'Prepare and keep this selected local project synced', positionals: [{ name: 'path', required: true }], options: { wait: { type: 'boolean', description: 'Prepare now and wait for its published environment; otherwise the device helper prepares it in the background.' } } },
+    { path: ['projects', 'sync', 'pause'], summary: 'Pause background preparation of this local project', positionals: [{ name: 'path', required: true }], options: {} },
+    { path: ['projects', 'sync', 'remove'], summary: 'Remove this local project from background preparation', positionals: [{ name: 'path', required: true }], options: {} },
+    { path: ['projects', 'sync', 'run'], summary: 'Run selected-project preparation in the background', positionals: [], options: {}, hidden: true },
     {
         path: ['projects', 'create'],
         summary: 'Create a project (owners and admins)',