@shardflux/cli 0.18.0-next.5 → 0.18.0

package/CHANGELOG.md

@@ -1,17 +1,70 @@
 # Changelog
 
-## 0.17.0 (not yet published)
+## 0.18.0 (not yet published)
+
+- A conversation that needs you says why: `shard conversations list` adds it as a fifth column, `shard conversations
+  get` prints it after the branch, and `shard agents list` shows it as the session's LAST MESSAGE (one line, cut to
+  fit). `--json` carries the API's `question`; `agents list --json` adds it to the session's row.
+
+- `shard machine save` and `shard template save` say when the save put software installed under the home into the
+  image, linked back at the same paths: `machine: version 4 saved; 1 large tool folder went into the machine image
+  (~/.dotnet); they keep working at the same paths`. `--json` carries `moved_to_image`.
+- Setting up pooled accounts creates the hosted CLIProxyAPI hub on codex-connector 5, or upgrades it in place (its
+  logins and settings stay), whose VM port runs the account pool router; it gives the hub the API URL and a hub token
+  and turns on CLIProxyAPI's rate-limit header passthrough. Hubs without pooled accounts stay as they are.
+- The Shardflux app for Ubuntu 24.04 (x64 and arm64): in a desktop session, bare `shard` opens it instead of the
+  terminal onboarding. It ships as the optional `@shardflux/desktop-linux-x64` / `-arm64` package (0.1.0), installs
+  with no npm install scripts, adds Shardflux to the app grid and starts at login. It has the Mac app's surfaces: the
+  first run, the top-bar panel (conversations, approvals, files, updates; a right click opens a small menu), the
+  launcher on Alt+Shift+Space (an X11 shortcut, or a GNOME custom shortcut it adds on Wayland), Settings, device and
+  sign-in approvals, notifications with actions, file downloads and self-update. `shard menubar start|stop|status`
+  and `--login on|off` manage it on Linux as on macOS. Without the desktop libraries, `shard` keeps the terminal
+  onboarding and says how to get the window.
+- `shard agents accounts`: your Claude and ChatGPT/Codex accounts in one list, each with its plan, status (Signed in,
+  Low, Limited, Expired), the account threads use, and its usage windows (Claude 5-hour and weekly, Codex primary and
+  secondary) with when each resets. `shard agents accounts usage` draws every window as a bar. `shard agents accounts
+  add claude|codex` signs in another account in a cloud VM (`--api-key-stdin` adds an API key instead),
+  `remove <account>` removes one and `move <account> up|down` changes its place. Accounts are named by
+  `claude:<n>`/`codex:<n>`, email, label or id; `shard accounts …` works too. `--json` everywhere (SDK 0.24.0).
+- `shard agents targets --json` carries an `accounts` block: the same list, for the menu bar.
+
+## 0.17.1 (not yet published)
 
-- Linux (Ubuntu 24.04, x64 and arm64): bare `shard` opens the Shardflux app in a graphical session. The optional CPU package installs without npm install scripts, adds Shardflux to the app grid, and starts at login. Headless sessions keep terminal onboarding. The systemd user helper keeps the live twin, files and conversation mirrors running; `shard device requests`, `shard device approve <id>` and `shard device deny <id>` handle local approvals.
-- The Ubuntu desktop app includes the custom tray panel, launcher capture and project/model menus, all Settings panes, local device and credential approval panels, notifications with actions, file downloads and packaged-app updates. `shard device approve --always` remembers matching in-project requests; outside-folder requests remain one-time approvals.
 - T3 Code on Linux: `shard` finds T3 Code installed from its .deb or AppImage (and AppImageLauncher, Gear Lever,
   flatpak and snap entries), registers the Shardflux provider in it, shows it in onboarding, and opens it from its
   desktop entry. `shard agents new --in t3`, `shard agents open t3` and `shard agents targets --open-in` work as on
   macOS: a T3 build with ACP providers starts each thread on its Shardflux provider in a cloud VM of its own, and T3
-  Code 0.0.45 opens the project VM as an SSH environment. `shard agents targets --json` reports it under `t3`
-  (`last_used_at`: when T3 last started). The Shardflux provider is also recognized in the latest T3 nightlies on
-  macOS.
-
+  Code 0.0.45 opens the project VM as an SSH environment. `shard agents targets --json` reports it under `t3`, and
+  `--open-in claude=t3,codex=t3` makes T3 Code where new conversations open. The Shardflux provider is also
+  recognized in the latest T3 nightlies on macOS.
+- Setting Shardflux up with a coding agent: `shard setup --guide` prints the one question an agent asks its user first
+  (a SaaS platform whose product runs VMs for its customers, or their personal cloud coding agents) and the ordered
+  steps of both, with every command; `--json` gives them as a list. Local only, so it never waits. Bare `shard`
+  without a terminal prints the same guide instead of the full help (macOS) or the sign-in line (Linux).
+- `shard auth login --browser --no-wait` prints the link and the code and returns; the next `shard auth login
+  --browser` waits for that same request while it is valid (`"resumed": true` on its `open` event), so an agent whose
+  command is cut off by its tool's time limit runs it again and the person approves one code. The request is kept in
+  `browser-login.json` (0600) in the config directory until it is approved, refused or expired.
+- `shard machine open` creates or resumes your machine VM without attaching to it and prints its workspace key: an
+  agent installs with `shard ws exec <key>`, writes dotfiles and secret files with `shard files write <key> <path>
+  --from -`, then `shard machine save --wait`. `--json` adds the workspace and the next commands.
+- A coding agent's shell (`CLAUDECODE`, `CODEX_SANDBOX`, `CODEX_THREAD_ID`, `CURSOR_AGENT` or `GEMINI_CLI` set) is
+  treated as no terminal, also when it is a PTY: bare `shard` prints the guide instead of the command center, `shard
+  ./` and `shard machine` do not attach, the Claude cloud sign-in says to run it in the user's own terminal, and
+  prompts take their non-terminal path (`signup` without `--accept-terms` stops with `terms_not_accepted`).
+- `shard ./` without a terminal (and without `--json`) is a usage error (exit 2) that says to run it in the user's own
+  terminal or to start the conversation detached with `--json --prompt`; before, it printed its help and exited 0.
+- `shard setup` without a session and without a terminal prints the guide and exits 4. Sign-in hints name `shard auth
+  login --browser` (and `shard signup` for a new account) instead of a password sign-in. After `shard setup` and
+  `shard auth login`, the next step names both paths; `shard setup --json` adds `next_steps: {saas, personal}` (`next`
+  is unchanged).
+
+## 0.17.0 (2026-10-10)
+
+- Linux (Ubuntu 24.04, x64 and arm64): bare `shard` signs in and connects Claude/Codex in the terminal. The
+  systemd user helper keeps the live twin, files and conversation mirrors running; `shard device requests`,
+  `shard device approve <id>` and `shard device deny <id>` handle local approvals. Desktop launches open a terminal;
+  macOS keeps its extra menu bar app.
 - A Codex project opens in T3 Code without a Claude sign-in (T3 shows Claude as signed out, and says how to sign in), and `--json` names the T3 Connect sign-in `shard` started for the phone (`t3_link.sign_in`, or `t3_link.needs_login` when this computer has no session).
 - A conversation settles when its turn ends (`done` or `unresolved` right away) and its VM takes the next message.
   `shard agents open`, `shard ./ --resume` and ACP reattach to that VM instead of resuming the conversation into a new
@@ -67,7 +120,7 @@
   active conversation and hears the finished turn the moment the conversation reports it (no polling every second).
   Conversations that finish together for the same branch land in one go, in the order they finished.
 
-## 0.16.0 (not yet published)
+## 0.16.0 (2026-10-10)
 
 - Cloud sessions are named for the work: `shard ./` starts the agent with the repository or folder name and the first
   line of your prompt, so claude.ai, the Claude app and its notifications show `Add CSV export · todo-app`

package/README.md

@@ -50,10 +50,18 @@ Bulk transfers batch writes automatically. Active transfers retain their byte po
 
 ## Install
 
+Setting Shardflux up with a coding agent (Claude Code, Codex, Cursor, ...)? See [For AI agents](#for-ai-agents): the
+agent asks one question first, then runs the steps for a SaaS platform or for your personal cloud coding agents.
+
 Linux (Ubuntu 24.04, x64 and arm64) and macOS are supported. On Linux, run `shard` to sign in and
 connect Claude, Codex or both (0.17.0+), then run `shard ./` in your project to attach Claude Code or Codex in place. Sign-in opens your browser;
 on a headless terminal, follow the displayed URL and device code. `--accept-terms` accepts the terms notice.
 
+In a desktop session, `shard` opens the Shardflux app for this (0.18.0+): guided sign-in, a top-bar panel for your
+conversations, a launcher on Alt+Shift+Space and Settings. It installs with the CLI (the optional
+`@shardflux/desktop-linux-x64` or `-arm64` package), appears in the app grid and starts at login;
+`shard menubar start|stop|status` and `--login on|off` manage it as on macOS.
+
 The Linux helper starts automatically after setup as `~/.config/systemd/user/shardflux-helper.service`
 and restarts after a CLI update. It keeps the live twin, `~/Shardflux` files and conversation history in sync.
 Use `shard device requests`, `shard device approve <id>` or `shard device deny <id>` for local approvals;
@@ -217,38 +225,62 @@ npm test 2>&1 | tail -n 60 | shard feedback --category bug --workspace acme/demo
 
 ## For AI agents
 
-`shard` is built to be driven by an agent: no browser, no prompts when standard input is not a
-terminal, `--json` on every command, secrets only on standard input, and documented exit codes.
-
-1. **Account (0.9.0+):** show your person the [Terms of Service](https://shardflux.dev/terms) and the
-   [Privacy Policy](https://shardflux.dev/privacy); once they agree, `shard signup --accept-terms --json` (0.15.0+:
-   without `--accept-terms` or a terminal to ask on, it stops before sending anything with `terms_not_accepted`, exit 2,
-   and the two links in `details`). With the Codex CLI signed in with ChatGPT on the
-   machine it signs up (or signs in) verified by that login; otherwise pass `--email <email>` and the
-   account works at once on the Free plan. It then runs `shard setup`: an organization, a project and
-   an API key with every workspace tool, saved in the credentials file. With two-factor authentication
-   it exits 4 with `mfa_required`: ask the person for the code, then `shard auth mfa --code <code>`.
-2. **Verify the email** (an `--email` signup, to start the trial): `shard verify --json` emails a
-   6-digit code; ask the person for it, then `shard verify <code>`. Nothing is signed out.
-3. **Set up again any time:** `shard setup --json` is idempotent. `shard setup --inspect --json --apps claude,codex`
-   (0.15.0+) checks every connection live (your account, Claude, Codex) and says what to do for any that is not ready;
-   `--connect` also finishes the Codex connection.
-4. **Work:** `shard exec <key> --template default -- <cmd>` creates the workspace on first use and runs the command
-   (0.10.0+); later commands reuse it. `shard ws open <key> --template <slug> --json`, `shard files ...` use the saved
-   key too.
-5. **A paid plan:** `shard billing plans`, then `shard billing upgrade <plan> --json` prints the Stripe
-   Checkout URL; give it to the person, then `shard billing upgrade <plan> --wait` (or
-   `shard billing status`) until it is active. The API activates a plan only when Stripe confirms the
-   payment.
-6. **Sensitive actions** (exports, deletions, two-factor and email changes) need a recent step-up:
-   `printf '%s\n' "$PASSWORD" | shard auth step-up` (add `--code <totp>` with two-factor
-   authentication; valid 10 minutes). Without a terminal `shard` does not ask: the command fails with
-   `step_up_required` (exit 4) and the hint names this command.
-7. **Feedback:** send `shard feedback` as you work, the moment something fails, confuses you or is
-   missing, or your user asks for an improvement (see [Feedback](#feedback-agents-use-this-while-you-work)).
-
-What a person does: entering a card in Stripe Checkout, the authenticator app's codes, and (for an
-`--email` signup) reading the 6-digit code.
+`shard` is built to be driven by an agent: no prompts and no full-screen views when standard input is not a terminal
+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):
+
+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+).
+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. 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
+fails, confuses you or is missing, or your user asks for an improvement (see
+[Feedback](#feedback-agents-use-this-while-you-work)).
+
+What a person does: agreeing to the terms, approving the browser sign-in, the Claude sign-in in their terminal,
+entering a card in Stripe Checkout and the authenticator app's codes.
 
 ## Accounts and sign-in (0.5.0+)
 
@@ -256,6 +288,7 @@ What a person does: entering a card in Stripe Checkout, the authenticator app's
 shard signup [--email you@example.com] [--name "Ada Lovelace"] [--no-codex] [--no-setup] [--accept-terms]   # 0.9.0+
 shard verify [<code>]                                  # 0.9.0+: emails a 6-digit code, then confirms it
 shard auth login --browser [--no-open]                 # 0.15.0+: approve this computer on the sign-in page
+shard auth login --browser --no-wait                   # 0.17.1+: print the link and code, return; the next --browser run waits for it
 shard auth login --codex [--accept-terms]              # 0.9.0+: sign in with the Codex login on this machine
 printf '%s\n' "$PASSWORD" | shard auth register --email you@example.com [--name "Ada Lovelace"] [--accept-terms]
 shard auth verify-email '<link from the email>'        # or just the token in it
@@ -334,6 +367,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.
+
 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
 until you revoke it. It prints what
@@ -1283,9 +1319,13 @@ New project folders are ready to use: `shard ./` and `shard agents new` initiali
 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. Every agent starts from both. Save or roll back with `shard machine save|rollback` and
+your agent uses the same save/rollback commands there. 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`. Every agent starts from both. 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 machine save --wait` and `shard template save --wait` return once the new version is ready (0.13.3+).
+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
 connection it configured and the file it is in (0.13.3+).
 
@@ -1321,6 +1361,25 @@ on it with `DISPLAY=:1`, detached so it outlives the command, for example
 
 Volume lists and details (0.14.0+) show `kind`. Project spaces show their measured storage and a platform-managed quota.
 
+### 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:
+
+```
+Claude
+  claude:1  marc@example.com (Max, in use) · Signed in
+            5-hour 43% (resets in 2h 10m) · Weekly 18% (resets in 4d 8h)
+ChatGPT / Codex
+  codex:1   marc@example.com (Pro, in use) · Signed in
+            5-hour 12% (resets in 3h 30m) · Weekly 35% (resets in 4d 23h)
+```
+
+`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.
+
 ## Conversations
 
 From 0.14.0, `shard conversations list|get|send|wait|land|move` manages project conversations. `shard c` is the short form. Conversations retain their branch and transcript as their VM binding changes.

package/dist/account-args.js

@@ -103,12 +103,13 @@ export const ACCOUNT_COMMANDS = [
             browser: { type: 'boolean', description: 'Sign in in the browser: open the sign-in page, approve this computer there (0.15.0+). An account created there agrees to the terms on the sign-up page, so --browser needs no --accept-terms.' },
             open: { type: 'boolean', description: 'With --browser: open the page in the default browser (default; --no-open only prints the link).' },
             'client-name': { type: 'string', value: '<name>', description: 'With --browser: the name the sign-in page shows for this computer (default "shard CLI on <hostname>").' },
+            wait: { type: 'boolean', description: 'With --browser: wait for the approval (default). --no-wait prints the link and the code and returns; the next "shard auth login --browser" waits for that same request while it is valid (0.17.1+).' },
             email: { type: 'string', value: '<email>', description: 'Your email address, to sign in with a password.' },
             codex: { type: 'boolean', description: 'Sign in with the Codex login on this machine instead of a password (0.9.0+; creates the account when there is none, so it needs --accept-terms like shard signup).' },
             ...ACCEPT_TERMS,
             ...SECOND_FACTOR,
         },
-        examples: ['shard auth login --browser', 'shard auth login --browser --no-open --json', `printf '%s\\n' "$PASSWORD" | shard auth login --email you@example.com`, `printf '%s\\n' "$PASSWORD" | shard auth login --email you@example.com --code 123456`, 'shard auth login --codex'],
+        examples: ['shard auth login --browser', 'shard auth login --browser --no-open --json', 'shard auth login --browser --no-wait --json   # then: shard auth login --browser --json', `printf '%s\\n' "$PASSWORD" | shard auth login --email you@example.com`, `printf '%s\\n' "$PASSWORD" | shard auth login --email you@example.com --code 123456`, 'shard auth login --codex'],
     },
     {
         path: ['auth', 'mfa'],
@@ -195,11 +196,12 @@ export const ACCOUNT_COMMANDS = [
     {
         path: ['setup'],
         summary: 'Get ready to run workspaces: use (or create) an organization and project, create an API key and save it',
-        description: 'Needs a session (shard auth login). With no organization it creates "<your name>\'s organization" and a project "Default"; the key gets every workspace tool unless --tool. The key is saved in the credentials file, checked against the API, and every workspace command uses it from then on. Idempotent: a saved key that still works is kept (unless --new-key).',
+        description: 'Needs a session (shard auth login). With no organization it creates "<your name>\'s organization" and a project "Default"; the key gets every workspace tool unless --tool. The key is saved in the credentials file, checked against the API, and every workspace command uses it from then on. Idempotent: a saved key that still works is kept (unless --new-key). --guide (0.17.1+) prints the question a coding agent asks its user first (a SaaS platform, or their personal cloud coding agents) and the ordered steps of both, without a network call.',
         positionals: [],
         options: {
             ...ORG,
             ...PROJECT,
+            guide: { type: 'boolean', description: 'Print how to set up Shardflux with a coding agent: the one question to ask your user, then the steps for a SaaS platform and for a personal setup (0.17.1+).' },
             'prepare-sample': { type: 'boolean', description: 'Copy the Daylight sample app into a new local Git project, "Daylight (sample)", for the first-run demo; prints its path.' },
             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.' },
@@ -214,7 +216,7 @@ export const ACCOUNT_COMMANDS = [
             'new-key': { type: 'boolean', description: 'Create and save a new key even when the saved one works (the old key stays valid until revoked).' },
             codex: { type: 'boolean', description: 'Set up the account Codex Cloud executor with this machine’s Codex login (default when signed in); --no-codex skips it.' },
         },
-        examples: ['shard setup', 'shard setup --json --inspect --apps claude,codex', 'shard setup --org acme --project web --tool exec --tool files'],
+        examples: ['shard setup', 'shard setup --guide', 'shard setup --json --inspect --apps claude,codex', 'shard setup --org acme --project web --tool exec --tool files'],
     },
     {
         path: ['env'],

package/dist/account-commands.d.ts

@@ -1,4 +1,5 @@
-import type { Handler } from './commands.js';
+import { setupGuide } from './agent-setup.js';
+import type { Ctx, Handler } from './commands.js';
 export declare const DEFAULT_API_URL = "https://api.shardflux.dev";
 /** What `shard setup` gave a key before 0.15.1: every tool but `computer`. Such a saved key is replaced with a full one. */
 export declare function outdatedDefaultKey(permissions: readonly string[]): boolean;
@@ -17,4 +18,6 @@ export declare function exportLine(shell: ShellKind, name: string, value: string
 export declare function parseTime(text: string, option: string, now?: number): string;
 /** A spend cap in dollars ("9", "9.5", "9.50", "$9") as minor units (cents); at most two decimals. */
 export declare function dollarsToMinor(text: string, what: string): number;
+/** The setup guide for this computer: whether a session and an API key are saved (no network call). */
+export declare function agentSetupGuide(ctx: Ctx): ReturnType<typeof setupGuide>;
 export declare const ACCOUNT_HANDLERS: Record<string, Handler>;

package/dist/account-commands.js

@@ -20,9 +20,13 @@ import { API_KEY_TOOL_PERMISSIONS, CheckoutTimeoutError, Shardflux, ShardfluxAcc
 import { CLI_VERSION, UUID, parseDuration, parsePositiveInt } from "./args.js";
 import { openUrl } from "./browser.js";
 import { defaultClientName, startDeviceAuthorization, waitForDeviceSession } from "./browser-login.js";
+import { setupGuide, setupGuideText } from "./agent-setup.js";
+import { readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
 import { legalFields, requireTermsAcceptance, showLegalNotice } from "./legal.js";
 import { fileExists, oneOf, out, parseSlugVersion, principal, readInput, resolveWorkspace, str, strs, waitTimeout } from "./commands.js";
-import { AuthConfigError, CheckoutEndedError, InterruptedError, MfaPendingError, NotFoundError, UsageError, describeError } from "./errors.js";
+import { writePrivateFile } from "./credentials.js";
+import { AuthConfigError, CheckoutEndedError, EXIT, InterruptedError, MfaPendingError, NotFoundError, UsageError, describeError } from "./errors.js";
 import { apiKeyTable, attachmentTable, auditTable, authSessionTable, billingStatusText, dataExportText, egressVersionTable, invitationTable, invoiceTable, isGrantPlan, kv, memberTable, money, orgTable, overagePolicyText, planTable, projectEgressText, projectTable, table, time, toolsText, volumeDetail, volumeTable, workspaceEgressText, WORKSPACE_HEADERS, workspaceRow, } from "./format.js";
 export const DEFAULT_API_URL = 'https://api.shardflux.dev';
 const TOTP = /^\d{6}$/;
@@ -39,6 +43,9 @@ export function outdatedDefaultKey(permissions) {
 const DEFAULT_CHECKOUT_WAIT_MS = 15 * 60_000;
 const CHECKOUT_POLL_MS = 2_000;
 const NEXT_WORKSPACE = 'shard ws open demo --template python-node-browser';
+/** After setup (0.17.1+): the next step for each answer to the setup question (shard setup --guide has them all). */
+const NEXT_STEPS = { saas: 'eval "$(shard env)", then the SDK, HTTP API or MCP server', personal: 'shard setup --inspect --connect --apps claude,codex, then shard ./' };
+const nextLines = () => `next, for your product (SDK, API, MCP): ${NEXT_STEPS.saas}\nnext, for your own cloud coding agents: ${NEXT_STEPS.personal}\n`;
 const SWITCHED_NOTE = 'note: another user was signed in here; their default organization, project and saved API key were removed from this profile (the key stays valid until revoked).\n';
 const pipe = (cmd) => `printf '%s\\n' "$PASSWORD" | ${cmd}`;
 function need(values, option, example) {
@@ -274,7 +281,7 @@ function nextAfterSignIn(ctx, user, me) {
     const hasKey = profile.api_key !== undefined || Boolean(ctx.io.env.SHARDFLUX_API_KEY?.trim());
     if (!hasKey || !me || me.memberships.length === 0)
         return 'shard setup   (an organization, a project and an API key, saved)';
-    return NEXT_WORKSPACE;
+    return 'shard setup --guide   (the steps for your product, or for your own cloud coding agents)';
 }
 async function signedInReport(ctx, account, user, session, extra = {}) {
     let me = null;
@@ -682,7 +689,7 @@ async function runSetup(ctx, values, account) {
             ]) +
             envNote +
             (codex ? 'Codex Cloud is ready. One account executor; no pairing. Its residency is billed as workspace usage.\n' : '') +
-            `next: ${NEXT_WORKSPACE}\n`,
+            nextLines(),
         data: {
             organization: org,
             project,
@@ -691,10 +698,46 @@ async function runSetup(ctx, values, account) {
             ...(codex ? { codex } : {}),
             credentials_file: ctx.store.file,
             next: NEXT_WORKSPACE,
+            next_steps: NEXT_STEPS,
         },
     };
 }
 // ---- browser sign-in (0.15.0+) -----------------------------------------------------------------------------------
+/**
+ * A browser sign-in to finish later (0.17.1+): `auth login --browser --no-wait` saves the request (0600, next to the
+ * credentials) and returns; the next `auth login --browser` for the same API waits for that request while it is valid,
+ * so an agent whose command is cut off by its tool's time limit runs it again and the person approves one code.
+ */
+const PENDING_LOGIN_FILE = 'browser-login.json';
+/** A request this close to its expiry is not resumed: a new one gives the person time to approve it. */
+const PENDING_MARGIN_MS = 15_000;
+function pendingLogin(ctx) {
+    try {
+        const saved = JSON.parse(readFileSync(join(ctx.store.dir, PENDING_LOGIN_FILE), 'utf8'));
+        const r = saved.request;
+        if (saved.api_url !== ctx.apiUrl || typeof saved.expires_at !== 'number' || !r || typeof r.device_code !== 'string' || typeof r.user_code !== 'string' || typeof r.verification_uri_complete !== 'string' || typeof r.interval !== 'number')
+            return null;
+        const left = saved.expires_at - Date.now();
+        if (left < PENDING_MARGIN_MS)
+            return null;
+        ctx.addSecret(r.device_code);
+        return { device_code: r.device_code, user_code: r.user_code, verification_uri: typeof r.verification_uri === 'string' ? r.verification_uri : r.verification_uri_complete, verification_uri_complete: r.verification_uri_complete, interval: r.interval, expires_in: Math.floor(left / 1000) };
+    }
+    catch {
+        return null;
+    }
+}
+function savePendingLogin(ctx, d) {
+    writePrivateFile(ctx.store.dir, join(ctx.store.dir, PENDING_LOGIN_FILE), `${JSON.stringify({ api_url: ctx.apiUrl, expires_at: Date.now() + d.expires_in * 1000, request: d })}\n`);
+}
+function clearPendingLogin(ctx) {
+    try {
+        rmSync(join(ctx.store.dir, PENDING_LOGIN_FILE), { force: true });
+    }
+    catch {
+        // Expires on its own.
+    }
+}
 /** One NDJSON line of `auth login --browser --json` (the Mac app reads them). */
 function event(ctx, value) {
     ctx.io.stdout.write(`${JSON.stringify(value)}\n`);
@@ -708,23 +751,49 @@ async function browserSignIn(ctx, values, noticeShown = false) {
     try {
         const opts = ctx.accountOptions();
         const clientName = str(values['client-name'])?.trim() || defaultClientName(ctx.hostname());
-        const d = await startDeviceAuthorization(opts, clientName, ctx.signal);
+        const waits = values.wait !== false;
+        // A request saved by --no-wait (0.17.1+) is the one to wait for; otherwise a new one.
+        const earlier = pendingLogin(ctx);
+        const resumed = earlier !== null;
+        const d = earlier ?? (await startDeviceAuthorization(opts, clientName, ctx.signal));
+        ctx.addSecret(d.device_code);
+        if (!waits && !resumed)
+            savePendingLogin(ctx, d);
         // The terms notice comes before the browser opens: a line here, the URLs in the event for an app to show. No
         // --accept-terms: an account created in the browser agrees to the terms on the sign-up page, which records it.
         if (ctx.json) {
-            event(ctx, { event: 'open', verification_uri_complete: d.verification_uri_complete, user_code: d.user_code, expires_in: d.expires_in, ...legalFields() });
+            event(ctx, { event: 'open', verification_uri_complete: d.verification_uri_complete, user_code: d.user_code, expires_in: d.expires_in, ...legalFields(), ...(resumed ? { resumed: true } : {}) });
         }
         else if (!noticeShown)
             showLegalNotice(ctx);
-        const opened = values.open !== false && openUrl(d.verification_uri_complete, ctx.io.env);
+        // A resumed request was opened (or printed) by the command that started it.
+        const opened = !resumed && values.open !== false && openUrl(d.verification_uri_complete, ctx.io.env);
         const minutes = Math.max(1, Math.round(d.expires_in / 60));
         if (!ctx.json) {
-            ctx.io.stderr.write(`${opened ? 'Opening your browser to sign in' : 'Open this page to sign in'}: ${d.verification_uri_complete}\n` +
+            ctx.io.stderr.write(`${resumed ? 'Continuing the sign-in started earlier' : opened ? 'Opening your browser to sign in' : 'Open this page to sign in'}: ${d.verification_uri_complete}\n` +
                 `Your code: ${d.user_code} (approve only if the page shows the same code)\n` +
-                `Waiting for the approval in the browser (the code expires in ${minutes} minutes; Ctrl-C stops)...\n`);
+                (waits
+                    ? `Waiting for the approval in the browser (the code expires in ${minutes} minutes; Ctrl-C stops)...\n`
+                    : `Approve it in the browser, then run shard auth login --browser to finish (the code is valid for ${minutes} minutes).\n`));
+        }
+        if (!waits) {
+            if (ctx.json)
+                event(ctx, { event: 'pending', expires_in: d.expires_in, next: 'shard auth login --browser --json' });
+            return null;
         }
         const sleep = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
-        const s = await waitForDeviceSession(opts, d, { signal: ctx.signal, sleep });
+        let s;
+        try {
+            s = await waitForDeviceSession(opts, d, { signal: ctx.signal, sleep });
+        }
+        catch (err) {
+            // Refused, expired or unknown: the saved request is done. Interrupted (or cut off): it stays for the next run.
+            if (resumed && !ctx.signal.aborted && err instanceof ShardfluxApiError)
+                clearPendingLogin(ctx);
+            throw err;
+        }
+        if (resumed)
+            clearPendingLogin(ctx);
         ctx.addSecret(s.session_token);
         const replaced = ctx.store.profile(ctx.apiUrl).session?.token ?? null;
         const saved = { token: s.session_token, expires_at: s.session_expires_at || null, user: { id: s.user.id, email: s.user.email }, state: 'active' };
@@ -747,8 +816,8 @@ async function browserSignIn(ctx, values, noticeShown = false) {
 }
 /** `shard signup` on a terminal without a Codex login or --email (0.15.0+): the browser sign-in, then setup like signup. */
 async function browserSignup(ctx, values) {
-    // signup has shown the notice (and asked) already.
-    const { account, user } = await browserSignIn(ctx, values, true);
+    // signup has shown the notice (and asked) already; it always waits for the approval.
+    const { account, user } = (await browserSignIn(ctx, { ...values, wait: true }, true));
     let text = `Signed in as ${userLine(user)} in the browser.\nsession: saved in ${ctx.store.file}\n`;
     const data = { status: 'authenticated', user, method: 'browser', credentials_file: ctx.store.file };
     if (values.setup !== false) {
@@ -773,8 +842,16 @@ function wantsBrowser(ctx, values) {
     }
     if (values.browser === false || email || values.codex === true)
         return false;
+    // --no-wait (0.17.1+) is a browser sign-in to finish with the next shard auth login --browser.
+    if (values.wait === false)
+        return true;
     return ctx.input.interactive && !ctx.json;
 }
+/** The setup guide for this computer: whether a session and an API key are saved (no network call). */
+export function agentSetupGuide(ctx) {
+    const profile = ctx.store.profile(ctx.apiUrl);
+    return setupGuide({ signedIn: ctx.sessionSource() !== null, email: profile.session?.user?.email ?? null, apiKey: profile.api_key !== undefined || Boolean(ctx.io.env.SHARDFLUX_API_KEY?.trim()) });
+}
 // ---- handlers --------------------------------------------------------------------------------------------------
 export const ACCOUNT_HANDLERS = {
     async 'auth register'(ctx, values) {
@@ -826,15 +903,18 @@ export const ACCOUNT_HANDLERS = {
         if (wantsBrowser(ctx, values)) {
             if (factorFlags(values) !== null)
                 throw new UsageError('--code and --recovery-code go with --email; in the browser the sign-in page asks for your second factor');
-            const { account, user, saved } = await browserSignIn(ctx, values);
+            const signedIn = await browserSignIn(ctx, values);
+            if (!signedIn)
+                return 0;
+            const { account, user, saved } = signedIn;
             if (ctx.json) {
                 event(ctx, { event: 'signed_in', email: user.email });
                 return 0;
             }
             return signedInReport(ctx, account, user, saved);
         }
-        if (values.open !== undefined || str(values['client-name']) !== undefined)
-            throw new UsageError('--no-open and --client-name go with --browser', 'shard auth login --browser --no-open');
+        if (values.open !== undefined || values.wait !== undefined || str(values['client-name']) !== undefined)
+            throw new UsageError('--no-open, --no-wait and --client-name go with --browser', 'shard auth login --browser --no-open');
         if (values.codex === true)
             return ACCOUNT_HANDLERS.signup(ctx, { ...values, setup: false, codex: true, email: undefined }, []);
         const given = str(values.email)?.trim();
@@ -1099,6 +1179,16 @@ export const ACCOUNT_HANDLERS = {
         return 0;
     },
     async setup(ctx, values) {
+        if (values.guide === true) {
+            const guide = agentSetupGuide(ctx);
+            out(ctx, setupGuideText(guide), { guide });
+            return 0;
+        }
+        // Not signed in, without a terminal (0.17.1+): the setup question and both paths' steps instead of an error line.
+        if (ctx.sessionSource() === null && !ctx.json && values.inspect !== true && values['prepare-sample'] !== true && !ctx.input.interactive) {
+            ctx.io.stdout.write(`Not signed in to ${ctx.apiUrl} yet.\n\n${setupGuideText(agentSetupGuide(ctx))}`);
+            return EXIT.auth;
+        }
         if (values['prepare-sample'] === true) {
             const path = await prepareOnboardingSample(ctx.store.dir);
             out(ctx, `Daylight is ready at ${path}\n`, { sample_path: path });

package/dist/account-pool.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `shard agents accounts` (0.18.0+); with --json every write prints the updated `{accounts, pool}` block (the menu bar
+ * redraws from it), plus the account it changed.: the organization's Claude and ChatGPT/Codex accounts, with each one's usage
+ * windows, reset times, status and threads (docs/progress/account-pool.md). Sign-ins run the provider's own login in a
+ * workspace, as `shard agents credentials login claude` does; API keys come from standard input and are write-only.
+ */
+import type { AgentAccount, AgentAccountList } from '@shardflux/sdk';
+import type { Ctx, Handler } from './commands.js';
+import { CodedError } from './errors.js';
+import type { HubCloud } from './cli-proxy-hub.js';
+/** "in 2h 10m", "in 4d 8h", "in 41m"; "now" once passed. */
+export declare function resetIn(resetsAt: string | null, now: number): string | null;
+/** Account references: the id, `<provider>:<n>` (its place in the list, from 1), the email or the label. */
+export declare function findAccount(list: AgentAccountList, ref: string): AgentAccount;
+/** The compact list: one row per account, grouped by provider. */
+export declare function formatAccounts(list: AgentAccountList, now: number): string;
+/** The usage view: every window of every account as a bar with its reset time. */
+export declare function formatUsage(list: AgentAccountList, now: number): string;
+/** Codex's device sign-in page, as Codex 0.160.0 prints it (test/fixtures/cloud-agents/codex-login-device-auth-0.160.0.json). */
+export declare function codexLoginUrls(output: string): string[];
+export declare const ACCOUNT_POOL_HANDLERS: Record<string, Handler>;
+/** The `accounts` block of `shard agents targets --json` (0.18.0+): the account list for the menu bar; null when it cannot be read. */
+export declare function targetsAccounts(ctx: Ctx): Promise<AgentAccountList | null>;
+/** The conversation's thread runs on the account pool (its `account.mode`, API with the pool). */
+export declare function conversationPooled(conversation: unknown): boolean;
+/** A pooled thread has no provider login on its session, so claude.ai, Claude Desktop and the Codex app cannot reach it. */
+export declare const pooledNeedsT3: (ref: string) => CodedError;
+/** Test seam: the hub cloud the pool toggle ensures (the SDK's by default). */
+export declare const accountPoolSeams: {
+    hubCloud?: (ctx: Ctx) => HubCloud;
+};