@shardflux/cli 0.25.0 → 0.28.0

package/CHANGELOG.md

@@ -2,6 +2,134 @@
 
 ## Unreleased
 
+- `shard orchestrator say` (0.28.0+, SDK 0.30.0): every input waits its turn in order,
+  however many wait (no more 429), and one of your orchestrator's threads hears each input at once, all in parallel: a
+  follow-up reaches the thread of the request it is about (the input reads merged), the row you point at reaches the
+  thread of that row's input, and anything new gets a thread of its own. The help text says so.
+- Your inbox on every device (0.28.0+, SDK 0.30.0): `shard conversations archive <id...>` archives conversations from
+  your own inbox, `shard conversations unarchive <id...>` brings them back and `shard conversations seen <id...>` records
+  that you opened them now, the same in the Shardflux app and every client you use (`shard c archive|unarchive|seen`).
+  Each takes up to 200 ids in one request and prints `Archived <id>  <title>`, `Unarchived <id>  <title>` or
+  `Marked seen <id>  <title>` per conversation, and `Not found: <id>` on stderr for an id you cannot read; it exits 3
+  when none was found. `--json` prints the API's answer, `{data, skipped}`, the conversations with your `seen_at` and
+  `dismissed_at`. Only your view changes: the conversations, their agents and computers carry on. `shard conversations
+  get --json` and `list --json` carry the same `seen_at`, `dismissed_at` and `needs_you_reason`.
+- Restore an orchestrator input (0.28.0+, SDK 0.30.0): `shard orchestrator restore <input-id>` brings an input you
+  dismissed back into `shard orchestrator list` on every device and prints `Restored: <your words>` (`--json`:
+  `{input}`). Restoring an input that is not dismissed changes nothing.
+- Orchestrator answer media (0.27.0+, SDK 0.29.0): `shard orchestrator say --wait` prints a line for each picture,
+  video or file the answer shows, after its points: `  media: loss-curve.png (image, 1200×800, 84.0 KB)` (the size in
+  pixels once measured). `--json` adds the answer's `media`; `shard drive get <file.path> --sha256 <file.sha256>` reads
+  one.
+
+- Orchestrator report cards (0.27.0+, SDK 0.29.0): `shard orchestrator say --wait` prints an answer the orchestrator
+  wrote as a report as its verdict, then its points under their group headings, one line each:
+  `- Loss is down to 1.84: from 2.31 at step 5,000 (14:02)`, the time short and in this computer's local time; a point
+  written without a lead prints its words. Every point, source and follow-up prints whole, however long. An answer
+  written as facts prints its facts as before. `--json` adds the answer's `points`.
+
+- Board content at any length (0.27.0+, SDK 0.29.0): `shard task show` prints a task's title, its plan steps and each
+  report's title and outcome whole, however long the agent wrote them (the terminal wraps them); `shard task edit
+  --title` takes a title of any length.
+
+- Your brain (0.27.0+, SDK 0.29.0): `shard brain ls [prefix]` lists your brain's files (size, saved time, type and
+  path; `--all`, `--limit`, `--cursor`; `--json` adds `next_cursor` and the brain's `version`) and `shard brain get
+  <path>` writes a file's bytes to standard output, to a file with `-o`, or as `--json` (`--sha256` reads exactly that
+  version). Your brain is your archive in an organization, kept by your orchestrator: its published answers as
+  `reports/<YYYY-MM-DD>/<folder>/report.md` with their media, its own notes and files, and `index.md`. Signed in it is
+  your brain in the saved organization, your only one, or `--org <id|slug>`; with `SHARDFLUX_API_KEY`, the brain of the
+  person who created the key.
+- 0.28.0: shard files delete removes a file or, with --recursive, a directory through the files API; disk-full errors give cleanup guidance without a retry loop.
+- Hung checkpoint recovery: `guest_unresponsive` identifies a cold boot after bounded restore readiness failures. Retained files are kept; memory is not restored and processes restart. Conversation moves can use their last durable copy after a bounded source restore failure; the newer source disk stays kept under its retention policy.
+
+- A linked folder's start point (0.28.0+): when an agent links a folder of yours (a device's
+  `project_link`), the folder as it is now (its commit, uncommitted files as a snapshot on top) goes to the project hub
+  under `refs/shard/seed/link-<folder>`, and the link's result names that `commit` and the folder's `branch`. A task can
+  then name exactly where its work starts, and its agent starts there with no conversation of that folder yet. Linking
+  from the app or `shard projects link` copies nothing to the hub. An API without the fields takes the link without them.
+
+- Landing per repository (0.28.0+): a project holds every folder its people linked, so a task's result lands only in a
+  folder of the repository it was started from (its workers' `repo_remote`). When the project hub's default branch is
+  another repository's, the result lands in its own folder and the hub's default branch stays as it is; with no folder
+  of that repository on this computer it answers `land_unrelated`.
+
+- A result from another repository (0.28.0+): `shard task land` and `shard conversations land` answer `land_unrelated`
+  when the result has no history in common with the branch it lands in (it was started from another repository than
+  the one that branch holds, or two of its workers were), with what to do instead; nothing moves on the project hub or
+  in your folder. It was a Git error ("refusing to merge unrelated histories") that read as if trying again could help.
+
+- Auto land switch (0.27.0+): `shard settings --auto-land on|off` turns automatic landing on or off for every project
+  on this computer (on by default). Off, the live twin lands no conversation and new conversations start from your
+  HEAD; `shard task land` and `shard conversations land` still land on request. `shard settings` shows it and `--json`
+  adds `auto_land`. The Shardflux app reads the same switch to land finished board tasks with no click.
+
+- Message delivery (0.27.0+, SDK 0.29.0): `shard conversations send` reaches a working agent in its running turn
+  (Claude Code, Codex and Codex Cloud) and starts an idle one's next turn; its help says so instead of "next turn".
+  `--wait` waits up to 60 s and prints what happened: `Steered into the running turn.`, `Started the next turn.` or
+  `Not delivered yet.` (`Delivery not confirmed yet: …` when Codex Cloud has not confirmed it); `--json` adds
+  `delivery`. Without `--wait` the output stays `Message sent (<seq>).`
+
+- One Shardflux app (0.27.0+): `shard` installs and updates the one desktop app (menu bar or tray, onboarding,
+  launcher, conversations with their computers, device approvals, one Settings window) from
+  `@shardflux/desktop-darwin-arm64` / `-x64` 0.9.0 on macOS (replacing `@shardflux/menubar-darwin`) and from
+  `@shardflux/desktop-linux-x64` / `-arm64` 0.9.0 on Linux (replacing the GTK tray app), at the same places as before
+  (`~/Applications/Shardflux.app`, `~/.local/share/shardflux/desktop`). It keeps the menu bar app's bundle id,
+  executable and signature, so `shard menubar start|stop|status|--login` and the running app's own update work
+  unchanged, and its first start retires the apps it replaces, keeping where each agent's conversations open (the
+  places `agents targets --open-in` saved) and, on Linux, the tray app's settings. The Linux autostart entry starts it with `--background`
+  (tray icon only). The launcher shortcut lines read the app's own choice (`desktop-app.json`). `shard update` lists it
+  as "Shardflux app". Retired: the CGWindowList window probe used for menu bar apps before 0.3.2.
+  On Linux the running app is found by its executable (`/proc/<pid>/exe`): Electron rewrites its command line, so
+  `shard menubar start|stop|status` and the refresh no longer miss it; the library check probes the Electron
+  executable behind the app's launcher and names each library the computer is missing.
+- 0.27.0 includes the changes prepared as 0.26.0 (not released on its own): the entries marked 0.27.0 below.
+
+- Device registration (0.27.0+): isolate each project, back off transient failures and stop after eight attempts with
+  an actionable needs-attention message. A device id another sign-in registered (the API key `shard setup` replaced,
+  or another account) is replaced by a new one (at most once every 10 minutes), with one line in the helper's log, and every project
+  registers again at once, so your agents reach this computer without a restart. The old id is kept in
+  `device-id-history.json`.
+- Your agents on this computer (0.27.0+): `shard device approvals auto|read|ask` chooses how this computer answers
+  your own agents: `auto` runs everything they ask without asking, `read` runs folder listings and files copied to a
+  conversation and asks before anything else (commands, files saved here, ports, linking a folder), `ask` asks every
+  time. The first request asks for the choice (the Shardflux app's prompt; without the app, `shard` prints the two
+  commands once) and runs under the mode chosen. A teammate's request always asks. What ran without asking is listed
+  by `shard device approvals` (`--json`: `recent`) and the app's Settings. Approvals carry `choose_mode: true` while
+  nothing is chosen.
+- First prompts (0.27.0+): a Codex Cloud start queues its initial prompt while the executor prepares. Resuming an accepted start uses the same prompt key; an unconfirmed send keeps its created conversation.
+
+- Device helper (0.27.0+): a command your orchestrator asks your computer to run (a home conversation, so no folder of
+  it on this computer) asks you once with the exact command and folder ("Run on your Mac: sh -c tail -n 5 train.log ·
+  in ~/code/lm-train"), Allow once or Deny, and runs in your home folder or the ~/ folder it names. A request whose
+  conversation has no folder on this computer is refused with the reason instead of staying pending.
+- Filesystem recovery (0.27.0+): resume JSON/timing keeps `cold_boot_reason: guest_filesystem`; the existing note reports restarted processes. Ships with SDK 0.29.0.
+
+- Admission queue waits (0.27.0+, SDK 0.29.0): workspace opens retry `429 admission_queued` within the admission timeout with the same body/key, honor full `Retry-After`, and display `queued for admission; retrying in 2 s` while waiting.
+- 0.27.0: workspace disk caps report the admitted and acknowledged size. Completed disk grows refresh the disk grant; resize results retain the original request.
+
+
+- `shard orchestrator` (0.27.0+, SDK 0.29.0): your orchestrator agent from a terminal. `shard orchestrator say <words>`
+  sends your exact words (`--task`, `--report`, `--needs-you`, `--input`, `--conversation` point at a row) and prints
+  the input id and its place in line; every input is handled in parallel by its own thread. `--wait` follows it until
+  it is done, merged, failed or waiting and prints its curated result: the answer's headline and facts with their
+  sources and follow-ups, the tasks it created, the line it waits on (a question names its `shard needs-you answer
+  oq_…` command), or the input it was added to; exit 6 when it failed, 5 when `--timeout` (default 10m) passed first.
+  `shard orchestrator list [--all]` shows your inputs newest first, one line each; `shard orchestrator retry
+  <input-id>` sends a failed one again and `shard orchestrator dismiss <input-id>` takes one out of the list. Signed in
+  they reach your orchestrator; with `SHARDFLUX_API_KEY`, the orchestrator of the person who created the key. `--json`
+  prints `{input}` / `{inputs, cursor}`.
+- `shard needs-you` (0.27.0+, SDK 0.29.0) lists your orchestrator's questions (`oq_…`, answered with `--text`) and what
+  it asked your computer while it was offline (`dev_…`, "Waiting for your computer: list ~/code"; `shard needs-you
+  answer dev_… cancel` drops it).
+- Deprecated (0.27.0): `shard route` (POST /v1/router) and `shard ask` (POST /v1/questions); use the orchestrator
+  instead (`shard orchestrator say`). Each prints a one-line notice on stderr.
+
+- `shard agents models` (0.27.0+): the models each active account can use, as Claude and ChatGPT list them for that
+  account (asked server side the way Claude Code and Codex fill their pickers; never starts a computer): effort levels
+  with the default starred, the default model, and unavailable models with the provider's reason. `--account <ref>`,
+  `--provider`, `--all`, `--refresh`; `--json` prints the API answer. `--model` on `shard agents new` (and `shard ./`)
+  also takes a model id from that list (`claude-fable-5-1`, `gpt-5.6-terra`) next to the aliases.
+
 - Device requests reach the right computer (0.25.0+): the background helper tells the API which conversations are
   local to this computer (started or opened here), so their requests come here first, then to the computer you used
   last, never to whichever was seen last. A project link with a first task (`project_link` with `brief`) reads the
@@ -11,7 +139,8 @@
   what each working step does, next to the plain waiting line of a task that waits to start.
 - `shard transcribe <file>` (0.25.0+, SDK 0.28.0) prints what a recording says (WebM/Opus or PCM WAV from the file;
   raw PCM with `--format pcm16 --sample-rate`); `--words` adds each word's start and end, `--json` prints the
-  transcript.
+  transcript. Where cloud transcription is not on for the organization it says so in one line
+  (`cloud_transcription_off`) and exits 1 (0.27.0+, SDK 0.29.0).
 - Faster conversation starts (0.24.1): the project's dependency fingerprint is read from Git's own file list instead of walking the whole folder, so ignored and untracked trees beside the project (agent worktrees, build output) no longer hold a start on **Getting your project…**. A folder with 1.2 million such files took 32 s per start; it now takes 0.3 s, with the same fingerprint.
 - A folder without Git that `shard` makes a repository of (a first chat, `shard projects link`) starts with its files as
   the first commit (0.25.0+; `.gitignore` respected, large media stay untracked), so a conversation starts from the

package/README.md

@@ -30,6 +30,8 @@ T3 Connect (0.22.0+): `shard setup --inspect --t3-connect --org <id|slug>` signs
 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.
 
+Filesystem recovery timing (0.28.0+): cold resume output identifies `guest_filesystem` in JSON and the restart notice. See the [workspace lifecycle](https://docs.shardflux.dev/concepts/lifecycle) for retained files and process restart semantics.
+
 ## Support and bug reports
 
 [Report a bug](https://github.com/shardfluxdev/community/issues/new?template=bug_report.yml) or
@@ -51,6 +53,8 @@ Both the task and project are required, and the task becomes the first user-auth
 
 ## Reverse tunnels (0.11.0+)
 
+Reverse listener recovery (0.24.1+): the foreground tunnel replaces its helper automatically after replay is lost and accepts fresh connections. Keep the command running for callbacks; Ctrl-C closes it.
+
 Run a foreground TCP tunnel from a workspace to a service on this machine:
 
 ```sh
@@ -74,18 +78,24 @@ Linux (Ubuntu 24.04, x64 and arm64) and macOS are supported. On Linux, run `shar
 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.
+In a desktop session, `shard` opens the Shardflux app (0.18.0+): guided sign-in, your conversations with their
+computers, approvals for this computer, a launcher on Alt+Shift+Space and one Settings window. It lives in the tray
+and the app grid and starts at login; `shard menubar start|stop|status` and `--login on|off` manage it as on macOS.
+
+The Shardflux app (0.28.0+) is one desktop app on macOS and Linux: the menu bar or tray, onboarding, the launcher,
+conversations with their computers, device approvals and one Settings window. `shard` installs it from the optional
+`@shardflux/desktop-darwin-arm64` / `-x64` package on macOS (at `~/Applications/Shardflux.app`, in place of the menu
+bar app, keeping its login item and privacy grants) and from `@shardflux/desktop-linux-x64` / `-arm64` on Linux (at
+`~/.local/share/shardflux/desktop`), and `shard update` keeps it current.
 
 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;
+Use `shard device requests`, `shard device approve <id>` or `shard device deny <id>` for local approvals, and
+`shard device approvals auto|read|ask` to choose whether your agents ask first (0.28.0+);
 desktop notifications point to pending requests. On systems without a systemd user session, the helper runs
 while your `shard` commands are open. `shard agents open` opens a terminal when launched outside one, using
-`$TERMINAL`, `x-terminal-emulator` or `gnome-terminal`, or prints the attach command. The Mac app adds a menu
-bar, launcher and Settings window.
+`$TERMINAL`, `x-terminal-emulator` or `gnome-terminal`, or prints the attach command. On macOS the same app lives in
+the menu bar.
 
 ```sh
 npm i -g shardflux
@@ -109,7 +119,7 @@ shard ./
 
 Choose Claude Code or Codex. Claude asks for one cloud sign-in per Shardflux account; Codex uses your copied login.
 Each `shard ./` starts its own conversation VM and opens your agent’s native terminal. Later turns stay in that
-VM; `shard ./ --resume` selects a saved project conversation. Native terminal and ACP sessions receive the conversation tools for their own conversation, so the agent can fork, ask for a review, and report to its parent (0.14.0+). You can open conversations in separate terminals at the same time; each stays in the project's local history. On macOS, `shard` opens the optional command center. On macOS the menu bar starts automatically the first
+VM; `shard ./ --resume` selects a saved project conversation. Native terminal and ACP sessions receive the conversation tools for their own conversation, so the agent can fork, ask for a review, and report to its parent (0.14.0+). You can open conversations in separate terminals at the same time; each stays in the project's local history. On macOS, `shard` opens the optional command center. The Shardflux app starts automatically the first
 time `shard` runs, with launch at login enabled; `shard menubar stop` turns it off. See [Cloud agents](https://docs.shardflux.dev/guides/cloud-agents).
 
 T3 Code uses one **Shardflux** provider; choose a Claude Code or Codex model to start that agent in the cloud.
@@ -124,7 +134,7 @@ and Codex, skipping every step that is already done (0.15.0+). Editors that laun
 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.
+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. ACP input reattachment (0.25.0+) retains the native request identity and running turn while reconnecting.
 
 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
@@ -155,12 +165,24 @@ shard conversations start --home --title "Plan the billing work"
 shard conversations send conv_6qz2dmu4kd3xa7v5l2hgmfnpjy "Here is the failing run" --file ci.log
 ```
 
-`--repo` and `--branch` choose the repository and the branch it starts from (default: the project's most recently
-active repository, from `main`, then `master`); `--app`, `--model` and `--effort` work as for `shard ./`. It prints the
+`--repo` and `--branch` choose the repository and the branch it starts from (default: the project's only
+repository, from `main`, then `master`; a project with several asks you to name one with `--repo`); `--app`, `--model` and `--effort` work as for `shard ./`. It prints the
 conversation's id, key and state; `shard agents open <id>` opens it. `--file` (repeatable, up to 20 files of 64 MiB
 each) puts each file in the conversation's computer before the message and prints where it landed; `--json` returns
 the stored paths.
 
+A message reaches the agent at once: a working agent takes it into its running turn (Claude Code, Codex and Codex
+Cloud), and an idle one starts its next turn with it. `--wait` (0.28.0+) says which:
+
+```sh
+$ shard conversations send conv_6qz2dmu4kd3xa7v5l2hgmfnpjy "Use the staging database instead" --wait
+Message sent (12).
+Steered into the running turn.
+```
+
+It prints `Started the next turn.` when the agent was idle; `--json` adds `delivery` (`state`, `delivered_at`,
+`steered`).
+
 Choose the model and reasoning effort a new thread starts with (0.17.0+):
 
 ```sh
@@ -202,14 +224,14 @@ resolution before preserve-all can upload; a registration whose folder is gone h
 With CLI 0.24.0+, a move during a reply stops the local turn and continues the same reply in the cloud automatically, redoing the interrupted step. An agent calling `move_to_cloud` inside its own turn waits for that turn to finish. 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
+Shardflux app's menu, a project's recent sessions under **On this Mac** (**On this computer** on Ubuntu) have
+**Move to cloud**, and with the Shardflux MCP server
 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+).
 
-With menu bar 0.8.5+, a failed move stays at its session’s row with its reason on hover and **Retry move to cloud**
-in **⋯**. Retry or Refresh clears the previous failure. CLI 0.23.0+ records a matching stable Node.js path on macOS,
-and menu bar 0.8.5+ recovers Node.js after an upgrade removes the recorded binary.
+In the Shardflux app, a failed move stays at its session’s row as **Couldn’t move**, with its reason on hover:
+choose it to try again (**Retry move to cloud** in the row's menu). CLI 0.23.0+ records a matching stable Node.js path on macOS.
 
 Start a thread in T3 Code from the command line (0.17.0+):
 
@@ -229,6 +251,11 @@ conversation with `shard conversations send <id> "<answer>"` (0.23.0+ names it w
 with in claude.ai and the Claude app (default `☁`: "☁ Fix login bug · todo-app"); `shard settings` shows it with where
 conversations open.
 
+Finished cloud work lands in your folder by itself: a conversation's commits come into the branch it started from, a
+board task's result into your linked folder and the project's default branch. `shard settings --auto-land off`
+(0.28.0+) keeps it in the cloud on this computer (`shard task land` and `shard conversations land` still land on
+request); `--auto-land on` turns it back on. The Shardflux app's Settings → Projects changes the same switch.
+
 Terminal conversations open in the terminal you choose (0.22.0+):
 
 ```sh
@@ -251,7 +278,7 @@ shard conversations try <conversation>
 
 Your branch opens in `.shard/worktrees/<name>`, syncs both ways, and its dev servers appear at localhost.
 Ctrl-C stops local sync. Your main checkout stays available for your own work.
-Device tools ask for approval on your computer before preparing the conversation’s local worktree. With CLI 0.15.0 and menu bar 0.3.0, Review shows the exact command, file direction, paths or port mapping; access outside the conversation folder only offers Allow once. Live transcripts stay in
+Device tools ask for approval on your computer before preparing the conversation’s local worktree. With CLI 0.15.0+, Review shows the exact command, file direction, paths or port mapping; access outside the conversation folder only offers Allow once. Live transcripts stay in
 
 From 0.25.0, an agent can also list a folder on your computer, make one of your projects from it, and move a file to or from anywhere on it by an absolute or `~/` path. Each asks first: **Allow once**, or **Always for this folder**, which covers that kind of request for that folder and everything inside it. `shard projects link <path> [--prompt <text>]` does the same from a terminal: the folder is prepared in the background, kept as this computer’s live copy, and `--prompt` starts a conversation there.
 `~/.config/shardflux/conversations/`; ended sessions enter Claude Code’s or Codex’s native history. Transcript files up to 64 MiB are supported (0.14.0+).
@@ -259,14 +286,14 @@ From 0.14.3, transcript copying runs independently of device approvals. Unknown
 
 Every conversation's committed files are on your computer too (with the helper running; macOS 0.16.0+, Linux 0.17.0+):
 `~/Shardflux/<repository>/<base branch>/<conversation>/` holds what each conversation changed or added, read-only,
-and updates when its branch moves. Large files are listed as `<file>.placeholder.txt`; download one with the menu
-bar's **Download** or:
+and updates when its branch moves. Large files are listed as `<file>.placeholder.txt`; open one from the
+conversation's computer in the Shardflux app and choose **Save to Downloads**, or:
 
 ```sh
 shard files pull hype-video out/hype.mp4
 ```
 
-Finished conversations land in your checkout by themselves (0.16.0+, with the menu bar app running). When a
+Finished conversations land in your checkout by themselves (0.16.0+, with the Shardflux app running). When a
 conversation's turn ends with its work committed, the branch it started from moves to its commits and the changed
 files are written in place, next to your own uncommitted edits, which stay as they are (where both touched the same
 lines, your text is kept). `git status` keeps showing only your edits. A conversation started from a checkout with
@@ -379,7 +406,7 @@ answer) or their product (it runs VMs for its customers through the API, SDK or
 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):
+**Their product** (no agent sign-ins, Shardflux app 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.
@@ -649,9 +676,11 @@ and the session renewals of step-up and password changes).
 ## Update
 
 `shard update` **(0.13.5+)** brings everything Shardflux installed on this computer up to date: shard itself
-(the `shardflux` package or `@shardflux/cli`), its SDK, the macOS menu bar app and a globally installed
+(the `shardflux` package or `@shardflux/cli`), its SDK, the Shardflux app and a globally installed
 `@shardflux/mcp`. It runs one install of the latest versions with the package manager that installed shard (npm,
-pnpm, bun or Volta) and restarts the menu bar on its new app. The menu bar's **Update** button runs the same command.
+pnpm, bun or Volta) and restarts the app on its new version; **Update now** in the app's Settings → Updates runs the
+same command. After `npm i -g shardflux` the app moves to the new version by itself once no window is open and no
+approval or move is in progress.
 
 ```sh
 shard update --check   # what is behind, without installing
@@ -706,7 +735,8 @@ shows the status; `shard version --check` asks now (`--json`: `{"cli", "sdk", "u
 | `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 [--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). |
-| `route [--task ID] [--org O] [--project P] <text...>`, `ask [--task ID] [--org O] [--project P] <question...>` | The board's input bar (0.25.0+): where a line of input goes (its project or your home; a task, a question or a steer, split per task), and a quick question about your work, answered as it is written. |
+| `orchestrator say [--wait [--timeout D]] [--task ID\|--report ID\|--needs-you ID\|--input ID\|--conversation ID] <words...>`, `orchestrator list [--all]`, `orchestrator retry\|dismiss <input-id>` | Your orchestrator (0.28.0+): say something and every input is handled at once by its own thread; `--wait` prints its curated result. See [Your orchestrator](#your-orchestrator-0270). |
+| `route [--task ID] [--org O] [--project P] <text...>`, `ask [--task ID] [--org O] [--project P] <question...>` | Deprecated; use `shard orchestrator say`. The board's input bar (0.25.0+): where a line of input goes, and a quick question about your work. |
 | `conversations delete <id> --yes` (`c delete`) | Delete a conversation everywhere at once (0.25.0+): its agent stops, its computer is deleted, and its messages, transcript and branch go with it. `--json` prints `{id, deleted, deleted_at, operation}`. See [Conversations](#conversations). |
 | `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+). |
@@ -941,6 +971,7 @@ without waking it (the state at suspension); `files search` then notes it on std
   is still queued after 120000 ms`). The operation continues server side:
   `shard operations wait <id>` keeps waiting. Without either (0.16.0+), a resume queued for capacity is waited for
   until its deadline, its place shown on stderr (see [Start deadlines](#start-deadlines)).
+- Admission queues (0.28.0+, SDK 0.29.0): an open keeps its body and Idempotency-Key while waiting, and stderr says `queued for admission; retrying in 2 s`. Each wait honors `Retry-After` within the SDK admission timeout (default 2 minutes).
 - A call refused while the workspace's host makes room to wake it (503 `host_capacity`) or while every workspace the
   plan lets work at once is busy (429 `quota_exceeded`) did not run: `shard` sends it again after each `Retry-After`,
   for up to 2 minutes (0.16.0+), and stderr says `waiting for room on the workspace's host (position 2)` once.
@@ -1024,7 +1055,8 @@ $ shard ws resize acme/demo --elastic --held 1024    # switch modes live
 Memory changes live, and disks grow online. A suspended workspace gets its new size when it resumes, before its first
 call. CPU changes live within the vCPUs the workspace booted with; a larger CPU size applies at the next start. Each
 resource says when it applies (`now`, `on resume` or `next start`), and the new caps are stored, so every later start
-uses them. `--json` prints the result with `applies_at` per resource and the stored `caps`.
+uses them. `--json` prints the result with `applies_at` per resource and `caps`. A non-null `caps.disk_gib` is bounded
+by the admitted plan and template ceiling and the acknowledged disk size. `disk.requested_gib` retains the resize request.
 
 ## Burst execution (0.8.0+)
 
@@ -1506,8 +1538,8 @@ 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
 machine too (0.20.0+). A file you changed here at the same time keeps your version, with the cloud's next to it
-(`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.
+(`CLAUDE.cloud.md`); a deleted one goes to the Trash. Project memory follows the project both ways. The Shardflux app
+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`
@@ -1524,7 +1556,7 @@ see the [settings and billing reference](https://docs.shardflux.dev/limits#cloud
 Claude needs one cloud sign-in per account; Codex uses your copied login.
 
 Import project secrets from hsec, 1Password, Bitwarden or Keychain. Approve browser fills from the attached CLI or
-menu bar; remember a selected login for unattended work with automatic relay renewal. Bound secret values are
+the Shardflux app; remember a selected login for unattended work with automatic relay renewal. Bound secret values are
 redacted from command output and saved logs.
 
 Imported secrets: stored encrypted with AWS KMS; only this project's workspaces can load it, and every load is logged.
@@ -1576,6 +1608,22 @@ Another member's personal account can be made active only by that member.
 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.
 
+From 0.28.0, `shard agents models` shows the models each active account can use, as Claude and ChatGPT list them
+for that account (the same lists Claude Code and Codex fill their pickers with): effort levels with the default
+starred, the default model, and what the plan does not include.
+
+```text
+Claude · marc@example.com (active)
+  claude-opus-5-5            Opus 5.5    low medium* high xhigh max  (default)
+  claude-fable-5-1           Fable 5.1   low medium high* xhigh max
+  claude-sonnet-5-5          Sonnet 5.5  low medium* high xhigh max
+  More models
+  claude-haiku-4-5-20251001  Haiku 4.5   no effort levels
+```
+
+`--account claude:2` shows another account, `--all` every account, `--refresh` asks again (lists are kept for an
+hour), and `--json` prints the API's answer. Pass an id to `shard agents new --model` (with `--effort`).
+
 ## 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.
@@ -1634,8 +1682,63 @@ shard c delete conv_k3m5q7s2u4w6y3b5d7f2h4j6ln --yes
 # Deleted: conv_k3m5q7s2u4w6y3b5d7f2h4j6ln
 ```
 
+### Your orchestrator (0.28.0+)
+
+Your orchestrator is your own agent on top of every project, on its own Shardflux computer and the same on every
+device. `shard orchestrator say` sends it your exact words and answers at once with the input and its place in line;
+every input is handled in parallel by its own thread, which answers it, puts tasks on the board, asks you something or
+adds it to an input in flight. `--wait` follows it and prints what it became:
+
+```sh
+shard orchestrator say --wait Lets check on our language model training progress
+# Training is 73% done, step 7,300 of 10,000
+#   - Loss 1.84, down from 2.31 at step 5,000
+#   - About 2 h 10 min left at this pace
+#   - Last checkpoint at step 7,000
+#   Sources: train.log (~/code/lm-train/train.log), wandb.ai (https://wandb.ai/acme/lm)
+#   Follow-ups: Check again in an hour
+shard orchestrator say --task task_h7g4d7tqyv2pz3a2npyo4rpgzq use postgres instead
+# in_q3vd5k2xbnwjm7e4rtyhcu6aio	queued (1 in line)
+shard orchestrator list
+# in_q3vd5k2xbnwjm7e4rtyhcu6aio	working	use postgres instead
+# in_7wcx227ovjpei4u6i47llu7w4i	done	Lets check on our language model training progress	Training is 73% done, step 7,300 of 10,000
+```
+
+`--task`, `--report`, `--needs-you`, `--input` and `--conversation` point at the row your words are about. `--wait`
+stops when the input is done (its answer card and the tasks it created), merged (the input it was added to), waiting
+(the line it waits on; a question names the `shard needs-you answer oq_… --text <answer>` that answers it) or failed
+(exit 6; `shard orchestrator retry <input-id>` sends it again); `--timeout` (default 10m) stops following with exit 5
+while the input goes on. `shard orchestrator list` shows your recent inputs newest first (`--all` adds the ones you
+dismissed with `shard orchestrator dismiss`). Signed in, they reach your orchestrator (`--org <id|slug>` when you belong
+to several); with `SHARDFLUX_API_KEY` set, the orchestrator of the person who created that key. `--json` prints the
+API's objects (`{input}`, `{inputs, cursor}`).
+
+Device helper recovery (0.28.0+): projects register independently and report when a sign-in needs attention. A new
+sign-in on this computer (a new API key from `shard setup`, another account) gets this computer a new device id by
+itself and registers again at once. See the [error reference](https://docs.shardflux.dev/reference/errors) for recovery.
+
+When your orchestrator needs your computer (the tail of `~/code/lm-train/train.log`, say), the device helper asks you
+first with the exact command and folder, **Allow once** or **Deny**, and runs it in your home folder or the `~/`
+folder it names (0.28.0+). Each of these commands asks; none runs under an Always grant, unless you let your agents
+run things without asking.
+
+**Your agents on this computer (0.28.0+).** Choose once how this computer answers your own agents:
+
+| `shard device approvals` | Your agents |
+|---|---|
+| `auto` | Allow everything: commands, files, ports and folders run without asking |
+| `read` | Allow reading: folder listings and files copied to a conversation run; anything that changes this computer asks |
+| `ask` | Ask every time |
+
+The first request asks which you want (the Shardflux app's prompt, or one line from `shard` with both commands) and
+runs under your choice; the app's Settings and `shard device approvals` change it any time. A teammate's request
+always asks. `shard device approvals` lists what ran without asking (`--json` for `recent`).
+
 ### Route input and ask about your work (0.25.0+)
 
+`shard route` and `shard ask` are deprecated (0.28.0); use `shard orchestrator say` (each prints a one-line notice on
+stderr).
+
 `shard route` reads a line of input the way the board's input bar does: which project it belongs to (or your home),
 whether it is a new task, a question or a steer for an open task, and each task in your own words when it asks for
 several. `shard ask` answers a quick question about your work from the board, printing the answer as it is written.
@@ -1711,14 +1814,20 @@ 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
+The device helper (started by the Shardflux app, and on Linux by its systemd service) 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.
+projects you add are prepared; onboarding (**Sync projects**) and Settings → Projects in the Shardflux app choose them
+too.
 
-### Menu bar conversation shortcut (0.15.0+)
+### Launcher (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.
+**New conversation** in the Shardflux app's menu opens the same launcher as **⌥⇧Space** (**Alt+Shift+Space** on
+Ubuntu; a GNOME keybinding on Wayland), in the project open in the app in front (app 0.9.0+). It starts the
+conversation where your conversations open (Settings → Agents → **Open conversations in**), with a card near the top
+of the screen that follows each start (**Show all N launches**); change the shortcut, **Detect my project** and the
+panel's position in Settings → Launcher. From a terminal:
 
 ```sh
 shard agents new --app claude --path ./ --prompt "Review the billing changes" --json
@@ -1772,7 +1881,9 @@ branch: `Landed in ~/code/best-todo · 3f2a1c9`.
 Later tasks to keep, oldest first. `shard needs-you answer <id>` answers any of them: `allow`, `always` (also adds the
 always-allow rule for the project; `--everywhere` for every project) or `deny` for a permission request, `--pick` for an
 agent's question in one, `--text` for a question, `land` (as `shard task land`), `keep` or `discard` for finished work, and `--keep <task-id>`
-(or `keep`, `discard`) for Later tasks. The agent goes on as soon as you answer.
+(or `keep`, `discard`) for Later tasks. The agent goes on as soon as you answer. Your orchestrator's questions are
+`oq_…` items (`--text`), and what it asked your computer while it was offline waits as a `dev_…` item ("Waiting for
+your computer: list ~/code"): it runs when your computer is back, and `cancel` drops it (0.28.0+).
 
 **Approvals.** The approval mode answers your agents' permission requests before they reach you: `ask` sends every one
 to you, `routine` (the default) approves tests, builds, reads and installs, `trusted` approves everything except
@@ -1795,7 +1906,7 @@ Explicit `agents new --in terminal`, `--in t3`, and `--like` launches keep their
 
 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.
+Desktop launch cards (0.22.0+): the Shardflux app clears and closes the launcher on submission, then shows each pending start as a card near the top of the display. **Show all N launches** expands their statuses and recovery.
 
 
 ### Pending execution cancellation (0.23.0+)
@@ -1829,7 +1940,7 @@ shard c list --org acme --state needs_you
 shard c feed --org acme --json
 ```
 
-`shard conversations list --all` reads every page, keeping the selected project, state and parent filters. `--json` returns `data` and `nextCursor`. Linux desktop 0.1.11+ reads all conversation and computer pages and shows the selected project key’s organization, usage, spend and connector status in Settings.
+`shard conversations list --all` reads every page, keeping the selected project, state and parent filters. `--json` returns `data` and `nextCursor`.
 
 ## Project drive (0.25.0+)
 

package/dist/account-pool.d.ts

@@ -6,7 +6,7 @@
  * With --json every write prints the updated `{accounts, pool}` block (the menu bar redraws from it), plus the account
  * it changed. Sign-ins run the provider's own login in a workspace, as `shard agents credentials login claude` does.
  */
-import type { AgentAccount, AgentAccountList, AgentAccountWindow } from '@shardflux/sdk';
+import type { AgentAccount, AgentAccountList, AgentAccountModels, AgentAccountWindow } from '@shardflux/sdk';
 import type { Ctx, Handler } from './commands.js';
 /**
  * Codex names its windows primary and secondary; their length says which is the 5-hour and which the weekly one (a
@@ -31,6 +31,16 @@ export declare function formatAccounts(list: AgentAccountList, now: number): str
 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[];
+/**
+ * `shard agents models` (0.27.0+): each account's models as its provider lists them for that account, the way Claude
+ * Code and Codex ask for their pickers. The default effort is starred; the harness's default model is marked.
+ */
+export declare function formatModels(entries: Array<AgentAccountModels & {
+    label?: string;
+    active?: boolean;
+}>, now: number): string;
+/** `shard agents models` (no `shard models` alias: that one is the model template). */
+export declare const AGENT_MODELS_HANDLERS: Record<string, Handler>;
 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>;

package/dist/account-pool.js

@@ -207,6 +207,54 @@ async function signIn(ctx, values, app) {
             await api.cancelSignIn(claim.sign_in_id).catch(() => undefined);
     }
 }
+const REASONS = { disabled: 'turned off for this account', not_entitled: 'not included for this account', not_in_plan: 'not in this plan' };
+/** "3m ago", "2h ago". */
+const ago = (at, now) => { const m = Math.max(0, Math.round((now - Date.parse(at)) / 60_000)); return m < 60 ? `${m}m ago` : `${Math.round(m / 60)}h ago`; };
+/**
+ * `shard agents models` (0.27.0+): each account's models as its provider lists them for that account, the way Claude
+ * Code and Codex ask for their pickers. The default effort is starred; the harness's default model is marked.
+ */
+export function formatModels(entries, now) {
+    if (!entries.length)
+        return 'No Claude or ChatGPT/Codex account is signed in. Add one with shard agents accounts add claude|codex.\n';
+    const lines = [];
+    for (const e of entries) {
+        const freshness = e.source === 'builtin' ? 'the harness’s own list until the provider answers' : e.stale && e.fetched_at ? `as of ${ago(e.fetched_at, now)}` : '';
+        lines.push(`${PROVIDERS[e.provider]}${e.label ? ` · ${e.label}` : ''}${e.active ? ' (active)' : ''}${freshness ? ` · ${freshness}` : ''}`);
+        const width = Math.max(...e.models.map(m => m.id.length), 8) + 2, nameWidth = Math.max(...e.models.map(m => m.name.length), 4) + 2;
+        const row = (m) => `  ${m.id.padEnd(width)}${m.name.padEnd(nameWidth)}${m.available
+            ? `${m.efforts.map(x => x === m.default_effort ? `${x}*` : x).join(' ') || 'no effort levels'}${m.id === e.default_model ? '  (default)' : ''}`
+            : `unavailable: ${m.reason_text ?? (m.reason ? REASONS[m.reason] : 'not offered')}`}`;
+        const main = e.models.filter(m => m.section === 'main'), more = e.models.filter(m => m.section === 'more');
+        lines.push(...main.map(row));
+        if (more.length)
+            lines.push('  More models', ...more.map(row));
+        lines.push('');
+    }
+    lines.push('Start with one: shard agents new <claude|codex> --model <id> --effort <level> (* the model’s default effort).');
+    return `${lines.join('\n')}\n`;
+}
+/** `shard agents models` (no `shard models` alias: that one is the model template). */
+export const AGENT_MODELS_HANDLERS = {
+    async 'agents models'(ctx, values) {
+        const api = ctx.cloud().agentAccounts;
+        const refresh = values.refresh === true;
+        if (values.account !== undefined) {
+            if (typeof values.account !== 'string' || !values.account.trim())
+                throw new UsageError('--account needs an account: its id, claude:<n>, codex:<n>, email or label.');
+            const account = findAccount(await api.list(), values.account.trim());
+            if (account.kind !== 'oauth')
+                throw new UsageError(`${name(account)} is an API key: it has no model list. Sign in with shard agents accounts add ${account.provider}.`);
+            const models = await api.models(account.id, { refresh });
+            out(ctx, formatModels([{ ...models, label: name(account), active: isActive(account) }], Date.now()), models);
+            return 0;
+        }
+        const all = await api.allModels({ provider: optionalProvider(values.provider), refresh });
+        const shown = values.all === true ? all.accounts : all.accounts.filter(a => a.active);
+        out(ctx, formatModels(shown, Date.now()), { accounts: shown });
+        return 0;
+    },
+};
 export const ACCOUNT_POOL_HANDLERS = {
     async 'agents accounts'(ctx, values) {
         const list = await ctx.cloud().agentAccounts.list({ provider: optionalProvider(values.provider) });