@shardflux/cli 0.24.0 → 0.25.0

package/CHANGELOG.md

@@ -1,5 +1,153 @@
 # Changelog
 
+## Unreleased
+
+- 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
+  start's whole JSON output; before, it failed with "Unexpected token '}'" although the conversation started.
+
+- `shard board` and `shard task show` show what a working task does now ("working (Fixing the login cookie)") and
+  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.
+- 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
+  same commit as the folder and its work comes back by fast-forward, as in any repository. Before, an empty first
+  commit left every file to the starting snapshot and the landing asked the agent to merge. A repository of your own
+  keeps its staged and untracked files as they are.
+- Device requests (0.25.0+) are answered between turns and as a turn ends; only an archived conversation refuses them.
+- Background preparation of a project with no build or test command ends ready (0.25.0+): there is nothing to check,
+  so `shard projects sync list` and the folders `shard projects link` adds no longer show an error.
+- `shard move` (0.25.0+) brings the files the session used outside the project: files you @-mentioned or named in a
+  prompt, files it read or edited, and the files a handed file names (a `~/Downloads` handoff and what it points to).
+  Each goes to the same place under the VM's home, and this computer's home path leads there, so the history's paths
+  open in the cloud. Before, only the checkout and the transcript moved, and a moved session stopped at a handoff it
+  could no longer open. Key and sign-in stores (`~/.ssh`, `~/.aws`, `.env` files, private keys) stay here. Up to 64
+  files, 64 MiB in all, 16 MiB each; the command names what it brings and what stays, and `--json` adds `files` and
+  `files_left`.
+- 0.25.0 (pending): Allowance hints respect unavailable overage; operation errors retain the service’s recovery message and retry delay.
+
+- Landing that lands (0.25.0+): `shard task land <task>` merges a finished task's result (`shard/<task id>`, where its
+  master merged its workers' branches; when a master did not, their branches are merged into it here when they merge
+  cleanly) into the project's default branch on the project hub, a fast-forward or a clean merge commit, never by
+  force; brings it into your folder on this computer the way finished conversations land (your branch moves, your
+  uncommitted edits stay, rewritten files are backed up first); checks the commit is in the branch; and only then
+  records it on the board (`Landed in ~/code/best-todo · 3f2a1c9`). A conflict changes nothing and asks the task's
+  master to merge (`land_conflict`). `shard needs-you answer land_… land` does the same, and
+  `shard conversations land <id> merge` now lands the conversation's branch the same way before it records it (before,
+  both only recorded a landing). `--path <folder>` picks the folder; `--json` returns `{landed, result, hub, folder,
+  recorded, message}`.
+
+- `shard conversations delete <id> --yes` (`shard c delete`, 0.25.0+, SDK 0.28.0) deletes a conversation everywhere at
+  once: its agent stops, its computer is deleted (a computer other conversations share stays for them), and its
+  messages, transcript and branch go with it, on every device. Without `--yes` it is refused before any request, as
+  every deletion is. `--json` prints the API's answer, `{id, deleted, deleted_at, operation}`; deleting it again answers
+  the same. The person who started it (or created the API key that did) and organization owners and admins delete
+  conversations. `shard conversations feed` shows a deleted conversation once as `<id>  Deleted conversation  deleted`.
+- ACP input recovery (0.25.0): temporary guest-agent interruptions use bounded backoff with the same native input identity. The editor retains its running turn; permanent errors and unverified receipts still require loading the session.
+
+- Tunnel recovery (0.24.1, SDK 0.27.3): a foreground reverse tunnel replaces its guest helper automatically when replay is lost. Existing TCP peers reset; fresh connections reach the new listener. SSH and device port-forward connections close cleanly for a new connection instead of looping on an unrecoverable cursor.
+- Folders on this computer (0.25.0+): an agent can list a folder here (`dir_list`: names, kinds, sizes and Git
+  remotes, never file contents), make one of your projects from it (`project_link`, with an optional first task), and
+  move a file to or from anywhere here with an absolute or `~/` path. Nothing runs before you approve it: **Allow once**,
+  or **Always for this folder**, which covers that kind of request for that folder and what is inside it, from any of
+  your conversations. A path outside every such folder asks again, and commands never run under a folder grant. The
+  background helper now answers for your signed-in project (and, signed in without a key, every project you can reach),
+  so a home conversation or an Orchestrator task can ask too, and reads every project's requests in one poll.
+- `shard projects link <path> [--prompt <text>] [--app claude|codex]` (0.25.0+) makes a local folder one of your
+  projects: prepared in the background and kept as this computer's live copy; `--prompt` also starts a conversation
+  there. `--json`: `{project: {project_id, repo_remote, folder, name, conversation_id?}}`.
+- `shard device-helper` (0.25.0+) asks the desktop app first when it serves `device-approver.sock` in the config folder,
+  so approvals show there as Needs-you items; otherwise the menu bar, an editor (ACP) or `shard device approve` as before.
+
+- `shard route <text...>` and `shard ask <question...>` (0.25.0+, SDK 0.28.0): the board's input bar in a terminal.
+  `shard route` prints where the input goes (its project or your home) and whether it is a task, a question or a steer
+  for an open task, with each task in your words and its title when the input asks for several; `shard ask` streams
+  the answer to a quick question about your work as it is written. `--task <task-id>` names the selected task, `--org`
+  and `--project` the scope (signed in: your organization's projects; with `SHARDFLUX_API_KEY` set: that key's
+  project), and `--json` prints the API's `RouterResult` or the whole answer.
+- The board (0.25.0+, SDK 0.28.0): `shard board` shows what waits on you first, then every task in Now, Next and
+  Later with its state, title or words and project; `--follow` prints each change as it happens, until Ctrl-C
+  (`--json`: the board, then one feed answer per line). `shard task add <words...>` (`--next`, `--later`, `--first`,
+  `--after <task-id>`, `--home`, `--project`), `show`, `edit` (`--text`, `--title`, `--now|--next|--later`,
+  `--first|--after`, `--keep`, `--clear`), `rm`, `steer` and `clear-done` manage tasks in your own words, and `shard
+  task show` lists each report with its evidence. `shard needs-you` lists everything your agents wait on, and `shard
+  needs-you answer <id>` answers any of it (`allow|always|deny`, `--everywhere`, `--pick`, `--text`,
+  `land|keep|discard`, `--keep <task-id>`). `shard approvals` shows the approval mode and always-allow rules; `set
+  <ask|routine|trusted|default> [--project <id>|--default]`, `allow <tool> <pattern...> [--project <id>|--everywhere]`
+  and `remove <rule-id>` change them.
+
+- Project drive (0.25.0+, SDK 0.28.0): `shard drive put <local-file> [<drive-path>]` saves a file to the project's
+  drive as a new version and prints its path and sha256 (the drive path defaults to the file's name; `-` reads standard
+  input; `--content-type`); `shard drive get <path>` writes its bytes to standard output or with `-o` to a file, checked
+  against their SHA-256, and `--sha256` reads exactly that version, also after the path was overwritten or removed;
+  `shard drive ls [prefix]` lists the current files (size, saved time, type, path; `--limit`, `--cursor`, `--all`);
+  `shard drive rm <path>`. The API key's project or `--project`; signed in, any of your projects by id or slug.
+  `--json` everywhere.
+- Model template (0.25.0+, SDK 0.28.0): `shard models` prints which harness, model and effort each role of a task
+  (master, builder, hard, light, reviewer) runs with, until when a role waits for its account's next usage window and
+  what the other provider would run now; `--harness` and `--attempt` show a running task's and a retry's. `shard models
+  primary claude|codex|clear` sets the project's primary provider, `--org <id|slug>` the organization's default.
+- `shard conversations list` and `shard conversations feed` (0.25.0+, SDK 0.28.0): signed in without an API key, every
+  project you work in, across your organizations, on one cursor; `--org <id|slug>` narrows them to one organization
+  (and uses your sign-in when you have one). With an API key they cover its project, as before.
+
+- `shard conversations answer <id> <permission-id> --pick <option>` (0.25.0+) answers the agent's question (Claude Code's
+  AskUserQuestion) with exactly the picked option; repeat `--pick` for a multi-select question, `--pick
+  "<question>=<option>"` when it asks several; `deny` declines it.
+
+- `shard acp`: a conversation computer on a newer template keeps the models the session offered until its live list
+  arrives, so the editor's first model choice is taken; before, the list went empty for a few seconds after
+  `session/new` and `session/set_model` answered "This model is no longer available".
+
+- Codex accounts (0.25.0+, SDK 0.28.0): `shard agents open` of a Codex Cloud conversation checks the Codex app on this
+  computer first. When the app is signed out or signed in to another ChatGPT account than the thread's, it says so in
+  one line with the account to sign in as and the thread's web link, instead of opening a link the app cannot show.
+  Earlier threads are listed with their accounts (`Earlier history: <url> (account)`). `--json` adds `account`,
+  `codex_app_login`, `account_mismatch` (`line`, `sign_in_as`, `web_url`) and each earlier thread's `account`.
+  `shard agents accounts use` of a Codex account says when the Codex app here is signed in to another account
+  (`--json`: `codex_app`).
+- Codex sign-in (0.25.0+, SDK 0.28.0): when Codex Cloud refuses the copied ChatGPT login, `shard setup --inspect`
+  says so in one line with the next step: `codex login` (Sign in to Codex again), then, once this computer has the new
+  sign-in, Copy sign-in (`shard agents credentials sync`); `--connect` copies it. `shard ./ codex` and
+  `shard agents codex enable` copy this computer's login and continue when it is new, or stop at once with
+  `codex_sign_in_required` and that line. The Codex remote device is never restarted for a sign-in (its Cloud threads
+  keep running), and one starting again with the new login reads as connecting.
+
+- `shard conversations start` starts a conversation without a folder: from the project hub (`--repo`, `--branch`), or with `--home` a coordinator on your machine that spawns threads in the project's repositories. `--app`, `--model`, `--effort`, `--title`, `--project`; `--prompt` sends the first message, with `--file` attachments. Prints the conversation's id, key and state (`--json`: the conversation, its workspace and the message).
+
+- `shard conversations send <id> <text> --file <path>` (repeatable, up to 20 files of 64 MiB each) puts each file in the conversation's computer before the message, which lists their paths, and prints `Attached <path>` for each. The text may be left out when files are attached, and unquoted words are sent as one message.
+
+- Home conversations list as `home` in `shard conversations list` and `get`, and open without a repository in `/home/user`.
+
+- `shard acp`: a permission prompt answered through the API (the Shard client, `shard conversations answer`, MCP)
+  while the editor shows it is withdrawn from the editor (`$/cancel_request`) and the turn goes on in the editor; before,
+  the editor saw nothing more of the turn until it answered its own prompt.
+
+- Permission requests (0.25.0+, SDK 0.28.0): `shard conversations permissions <id>` lists what a conversation's agent
+  asked permission for before running a tool (Claude Code, Codex and ACP agents), oldest first, with `--state`,
+  `--all` and `--json`; `shard conversations answer <id> <permission-id> allow|always|deny` answers one.
+  `shard conversations get` names the requests a `needs_you` conversation waits on (`Waiting on: Run npm test`).
+
+- `shard conversations watch <id>` shows a conversation's terminal live and read-only: its last 256 KiB, then the agent's
+  output as it works, until its session exits or Ctrl-C. It never types into the terminal and never keeps the computer
+  awake while the agent is idle.
+- `shard conversations get <id>` prints one line per port a process listens on in the conversation's computer: the
+  port, the program, and its URL once exposed (or `127.0.0.1 only`). `--json` includes `pty_id`, `listening_ports` and
+  `listening_ports_at`.
+
+- `shard conversations feed` (0.25.0+): each conversation of the project as it changes, until interrupted; `--json`
+  prints one `{conversation, cursor}` object per line, `--cursor` continues after one. `shard conversations list
+  --updated-after <time>` filters by `updated_at`.
+- Conversation titles in human output are the agent's own short title (`title_short`) once it has one.
+
+- `shard acp` opens a conversation by its id: `session/load` with a `conv_…` session id attaches an ACP client to that conversation's live session in its computer, with its history replayed by the agent and no local folder synced.
+
+- `shard conversations transcript <id>` prints a conversation’s transcript, the agent’s own Claude Code or Codex JSONL byte for byte, for working, parked and finished conversations alike (`--offset`, `--session`; `--follow` keeps printing new lines). `shard conversations events <id>` follows it live: state changes, new transcript lines, tool calls and the reply as it streams; `--json` prints one event per line.
+
 ## 0.24.0
 
 - Finish all active device port-forward cleanup and close the local listener and cell before returning the original tunnel-close error. Repeated stop and abort keep the same error and promise.

package/README.md

@@ -1,5 +1,7 @@
 # @shardflux/cli: `shard`
 
+For error codes, retry timing, and plan recovery, see the [error reference](https://docs.shardflux.dev/reference/errors).
+
 Historical template file lists: reads queue checksum-verified reconstruction when a cold list is absent from the SQL cache. TypeScript SDK 0.27.0+ / Python 0.23.0+ wait full Retry-After for retryable API 409 file_list_indexing on GET/HEAD within the admission timeout. Template objects and version history stay available.
 
 Plan-derived API budgets (0.23.0+, SDK 0.27.0): `--json` error output includes `rate_limit` and `retry_after_seconds`; the text hint names the shared scope and delay. API request pacing follows the SDK admission timeout and preserves the request body. Reuse workspace credentials and reduce status polling when the returned budget asks for a delay.
@@ -144,6 +146,21 @@ shard ./ --on fix-login --review             # a read-only Claude reviewer of it
 the new thread. Codex threads are Codex Cloud threads, on the web and your phone too. `shard agents list` shows each
 thread's conversation and computer.
 
+Start a conversation without a folder (0.25.0+): its repository is checked out from the project's saved branches, or
+with `--home` a coordinator starts on your machine and spawns threads in the project's repositories.
+
+```sh
+shard conversations start --prompt "Add CSV export to the invoices page" --file mockup.png
+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
+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.
+
 Choose the model and reasoning effort a new thread starts with (0.17.0+):
 
 ```sh
@@ -235,6 +252,8 @@ 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
+
+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+).
 From 0.14.3, transcript copying runs independently of device approvals. Unknown entries are skipped, and failed copies retry with backoff; diagnostics name the conversation and affected entry.
 
@@ -687,6 +706,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. |
+| `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+). |
 | `workspaces get <id\|key>` | One workspace (deleted ones included), with the startup of its template's start commands and services (0.4.0+): a failed step shows its exit code, reason and output tail. Its mode, and a file-first workspace's tree revision (0.5.0+). Its memory (0.8.0+): `fixed 4096 MiB`, or `elastic: promised …, held …, plugged +… MiB`. The template version whose [immutable paths](#immutable-paths-080) it has mounted (0.8.0+): `immutable paths  v3 (mounted read-only)`. |
@@ -1446,7 +1467,7 @@ A message from claude.ai or the Claude app wakes a waiting Claude conversation a
 
 Run `shard ./` in your project to start Claude Code or Codex, usable immediately while setup runs in the background.
 
-New project folders are ready to use: `shard ./` and `shard agents new` initialize Git on `main` when needed and create an empty initial commit (CLI 0.14.2+). Existing files and staged work stay yours; the initial commit contains no files. Repositories without commits keep their current branch. If Git identity is missing, that one commit uses `Shardflux <noreply@shardflux.dev>` without changing your Git configuration.
+New project folders are ready to use: `shard ./` and `shard agents new` initialize Git on `main` when needed (CLI 0.14.2+). From 0.25.0 a folder `shard` makes a repository of gets its files as the first commit (`.gitignore` respected; large media stay untracked), so a conversation's work comes back by fast-forward; a repository of your own without commits keeps its staged and untracked files behind an empty initial commit. Repositories without commits keep their current branch. If Git identity is missing, that one commit uses `Shardflux <noreply@shardflux.dev>` without changing your Git configuration.
 
 Machine saves require a machine source VM (`labels.shard_layer = "machine"`). On your computer, run
 `shard machine open --json`, make changes in that VM, then `shard machine save --wait`. The computer's CLI
@@ -1559,6 +1580,40 @@ account, make another one active first; your own you can always remove. `--json`
 
 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.
 
+Watch an agent work: `shard conversations watch <id>` shows the conversation's terminal live, read-only. It starts
+with the last 256 KiB the agent printed, then streams everything it prints, until its session exits or you press
+Ctrl-C. Nothing you type reaches the agent, and watching never keeps its computer awake while the agent is idle.
+`shard conversations get <id>` lists the servers running in the conversation's computer, one line per port, with
+each port's URL once exposed (`shard ws port expose`); `--json` returns them as `listening_ports`, and the terminal as
+`pty_id`.
+
+```sh
+shard conversations watch conv_a7k2m4q6s3t5v7x2z4b6d3f5h7
+shard conversations get conv_a7k2m4q6s3t5v7x2z4b6d3f5h7
+# Fix login
+# working
+# shard/fix-login
+# 5173  node  https://5173-<handle>.shardflux.app (exposed)
+# 5432  postgres  127.0.0.1 only
+```
+
+`shard conversations transcript <id>` (0.25.0+) prints the conversation's transcript: the agent's own Claude Code or
+Codex JSONL, byte for byte, for a working, parked or finished conversation alike, without waking its VM. `--follow`
+keeps printing lines as the agent writes them; `--offset` starts at a byte offset and `--session` reads an earlier
+session. `shard conversations events <id>` (0.25.0+) follows the conversation live: its state, new transcript lines,
+tool calls and the reply as it streams; `--json` prints one event per line.
+
+```sh
+shard c transcript conv_k3m5q7s2u4w6y3b5d7f2h4j6ln > session.jsonl
+shard c transcript conv_k3m5q7s2u4w6y3b5d7f2h4j6ln --follow | jq -c 'select(.type=="assistant")'
+shard c events conv_k3m5q7s2u4w6y3b5d7f2h4j6ln
+# state: working
+# Looking at the login test.
+# tool: Read login.test.ts (pending)
+# tool: Read login.test.ts (completed)
+# state: done
+```
+
 
 Desktop project connections (0.14.0+): `shard agents open codex-app <project>/<workspace>` and
 `shard agents open claude-desktop <project>/<workspace>` register **Shardflux · <project>** in the app.
@@ -1568,6 +1623,78 @@ Conversation JSON includes `join_mode` and the worktree used by reviewers and wo
 
 `shard conversations resume <id>` continues a saved conversation in a fresh VM under the same identity (0.14.0+). `shard ./ --resume` uses this same path. `shard conversations reader <project-id>` opens a small read-only workspace for saved branches and transcripts; the Mac transcript mirror opens it automatically when no project VM is live. Adaptive idle reclaims the reader.
 
+`shard conversations delete <id> --yes` (0.25.0+) deletes a conversation everywhere at once: its agent stops, its
+computer is deleted (a computer other conversations share stays for them), and its messages, transcript and branch go
+with it, on every device. From then on it leaves every list and reads not found; `shard c feed` shows it once as
+`deleted`. The person who started it and organization owners and admins delete conversations. `--json` prints the
+API's answer: `{id, deleted, deleted_at, operation}`, where `operation` is the deletion of its computer.
+
+```sh
+shard c delete conv_k3m5q7s2u4w6y3b5d7f2h4j6ln --yes
+# Deleted: conv_k3m5q7s2u4w6y3b5d7f2h4j6ln
+```
+
+### Route input and ask about your work (0.25.0+)
+
+`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.
+
+```sh
+shard route fix the hero image on the landing page and add a GPU row to the pricing table
+# 2 tasks in site
+#   1. Fix the landing page hero image
+#      fix the hero image on the landing page
+#   2. Add a GPU pricing row
+#      add a GPU row to the pricing table
+shard route --task task_healthzhealthzhealthzhealt return 503 instead of 500 when the database is down
+# steer task_healthzhealthzhealthzhealt in status-board
+#   return 503 instead of 500 when the database is down
+shard ask what is the healthz work doing right now
+# Your “Add /healthz endpoint” agent is working on shard/healthz with 2 commits and was last active 4 minutes ago. …
+```
+
+Signed in, both read every project of your organization (`--org <id|slug>` when you belong to several, `--project` to
+lean to one); with `SHARDFLUX_API_KEY` set they read that key's project. `--task` names the selected task. `--json`
+prints the API's object: the route (`kind`, `parts`, `task_ref`, `uncertain`, …) or the whole answer (`text`,
+`needs_work`, `sources`, …). An answer that needs work ends with "Make it a task?". Neither starts work or wakes a
+computer.
+
+### Transcribe a recording (0.25.0+)
+
+`shard transcribe <file>` prints what a recording says. `--words` adds each word with its start and end; `--json`
+prints the transcript (`text`, `words` with `w`, `start` and `end` in seconds, `language`, `duration`).
+
+```sh
+shard transcribe note.webm
+# Take this sidebar, and move it over here, then make the header a bit taller, and change that color to blue.
+shard transcribe hello.wav --words
+# Move this button over here, then make that panel a little wider.
+# 0:00.00  0:00.18  Move
+# 0:00.18  0:00.44  this
+# …
+```
+
+WebM/Opus and PCM WAV are read from the file; raw 16-bit mono PCM takes `--format pcm16 --sample-rate 16000`.
+`--language en` names the language when you know it. Up to 120 s of audio. Signed in, or with `SHARDFLUX_API_KEY`.
+
+### Permission requests (0.25.0+)
+
+When a conversation's agent asks before it runs a tool (Claude Code, Codex or an ACP agent), the conversation is
+`needs_you` and `shard conversations get` names what it waits on. Answer it from any terminal:
+
+```sh
+shard c permissions <conversation-id> --state pending
+# 01a1300c-…  pending  Run npm test  npm test
+shard c answer <conversation-id> <permission-id> allow      # or always, deny
+# Allowed once: Run npm test
+```
+
+Each line is the request id, its state, what the agent wants to do, the command, path or URL, and the decision once
+answered. Without `--state` every request is listed, oldest first; `--all` reads every page and `--json` prints `data`
+and `nextCursor`. `always` lets the agent's harness stop asking for this kind of call. The agent goes on with its turn
+as soon as you answer, and a parked computer wakes to take the answer.
+
 ### Starting from your working state (0.22.0+)
 
 A new conversation starts from your worktree as it is: committed history, uncommitted edits, untracked files and your
@@ -1608,6 +1735,56 @@ With CLI 0.23.0+, a full conversation key or id opens that same Claude or Codex
 
 Use `shard agents open <workspace> --in auto --json` to resolve where a conversation opens: a saved target first; then, for Claude (0.15.1+), the conversation itself in Claude Desktop when it is installed (`{"target":"claude-desktop","url":"claude://code/session_…","app_bundle_id":…}`), else Claude Code in the terminal (`{"target":"terminal","command":["shard","agents","open","<workspace>"]}`; without `--json` it attaches in this terminal). Codex Cloud opens its current thread in your browser (CLI 0.23.0+). claude.ai opens with `--in web`. The caller opens the `url` or app, or runs the command in a terminal. Explicit `--in terminal` retains terminal attachment. The menu uses this resolver for new and existing conversations, without provider URLs in Swift.
 
+## The board (0.25.0+)
+
+The board is one list of what you asked your agents for, the same on every device: what waits on you first, then every
+task in Now, Next and Later, each in your own words. The agent that does the work seals a report with its evidence, and
+reading the board never wakes a computer. The board commands use your project API key: the board is its project's.
+
+```sh
+shard task add Fix the wake race in resume         # your words, kept exactly; the project's master starts the work
+# task_h7g4d7tqyv2pz3a2npyo4rpgzq  now  queued
+shard board
+# Needs you
+# perm_01a1300c-…  Run npm test?  npm test
+#
+# Now
+# task_h7g4d7tqyv2pz3a2npyo4rpgzq  working  Fix the wake race in resume  01a1415f-…
+shard needs-you answer perm_01a1300c-… always      # allow, always or deny
+# Always allowed: Run npm test (rule rule_ym4xywjgj7vvvrhkqlduotkvb4)
+shard task show task_h7g4d7tqyv2pz3a2npyo4rpgzq    # the plan, then each report with its evidence
+shard board --follow                               # each change as it happens, until Ctrl-C
+```
+
+**Tasks.** `shard task add <words...>` adds a task to Now (`--next`, `--later`), last in its bucket unless `--first` or
+`--after <task-id>` places it; `--home` runs a personal task on the project's machine home. `shard task edit <id>`
+changes the words (`--text`, and the task's master hears it), the title (`--title`), the bucket (`--now`, `--next`,
+`--later`) and the order (`--first`, `--after`), keeps an agent's suggestion as your own (`--keep`) or clears the task
+(`--clear`; `--no-clear` brings it back). `shard task steer <id> <words...>` sends steering words to the task's master,
+`shard task rm <id>` deletes the task, and `shard task clear-done` clears every finished one. `shard task show <id>`
+prints the task, its plan and each report: milestone, outcome and evidence (`tests 12/12 (pnpm test)`).
+`shard task land <id>` lands a finished task: its result (the branch `shard/<task id>`, where its master merged its
+workers' branches) goes into the project's default branch and into your folder on this computer the way finished
+conversations land there (your uncommitted edits stay), and the board shows it shipped once the commit is in the
+branch: `Landed in ~/code/best-todo · 3f2a1c9`.
+
+**Needs you.** `shard needs-you` lists permission requests, questions, credential requests, finished work to land and
+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.
+
+**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
+deploys, pushes to main and spending. `shard approvals` shows the modes and rules. `shard approvals set <mode>` sets the
+project's mode (`--project <id>`; `default` puts it back on the default mode), `shard approvals allow <tool>
+<pattern...>` always allows a tool for commands that start with the pattern (`shard approvals allow Bash pnpm test`),
+and `shard approvals remove <rule-id>` removes a rule. Requests already waiting that a new mode or rule covers are
+answered at once.
+
+Each line is one item, tab-separated, id first. `--json` prints the API's objects; `shard board --follow --json` prints
+the board on its first line, then one feed answer per line.
+
 ## Codex Cloud (0.15.0+)
 
 New Codex conversations use `shard agents new --app codex --path <directory>` or `shard ./ codex`. Each gets a fresh conversation VM and a genuine Codex Cloud thread. `shard agents open <conversation-id>` opens the existing thread without waking its VM. These paths create no SSH device entries and need no pairing.
@@ -1633,10 +1810,95 @@ Older clients read the same session response fields.
 
 Cloud history (0.23.0+): `shard agents open <conversation-id> --original` opens the original chat; `--history <thread-id>` opens an earlier linked chat. `--json` includes `previous_threads` with each history URL. Sign in with the Codex account that owns the selected chat.
 
+Codex accounts (0.25.0+): before opening a Cloud thread, `shard agents open` checks which ChatGPT account the Codex app on this computer is signed in to. When it is not the thread's account, it names the account to sign in as and prints the thread's web link. Earlier threads are listed with their accounts.
+
 ## Complete conversation lists (0.23.1+)
 
+`shard conversations feed` (0.25.0+) prints each conversation of the project the moment it changes, until you stop it:
+`<id>  <title>  <state>`, or with `--json` one `{conversation, cursor}` object per line (`--cursor` continues after
+it). `shard conversations list --updated-after <time>` lists only conversations changed since then. Titles show the
+agent's own short name for a conversation once it has one (`title_short`).
+
+Signed in (`shard auth login`) without an API key, `shard conversations list` and `shard conversations feed` (0.25.0+)
+cover every project you work in, across your organizations, with one cursor; `--org <id|slug>` narrows them to one
+organization and `--project` to one project. With an API key they cover the key's project, and `--org` uses your
+sign-in when you have one:
+
+```sh
+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.
 
+## Project drive (0.25.0+)
+
+`shard drive` keeps a project's files: the screenshots, logs, reports and notes your agents and people save and read by
+path, the same from a phone, a script or another agent whether the project's computers are working, asleep or gone.
+Paths are relative to the project space root, the names agents see under `/shardflux/project`
+(`tasks/t_ab12/evidence/healthz.png`, `BOARD.md`).
+
+```sh
+shard drive put ./out/healthz.png tasks/t_ab12/evidence/healthz.png
+# Saved tasks/t_ab12/evidence/healthz.png (48.2 KB, image/png)
+# sha256 <sha256>
+shard drive put BOARD.md                          # saved as BOARD.md
+git diff | shard drive put - tasks/t_ab12/review.diff
+shard drive ls tasks/t_ab12/
+# SIZE      SAVED                 TYPE                          PATH
+# 48.2 KB   2026-10-15 23:13:47Z  image/png                     tasks/t_ab12/evidence/healthz.png
+# 24 bytes  2026-10-15 23:13:48Z  text/markdown; charset=utf-8  tasks/t_ab12/notes.md
+shard drive get tasks/t_ab12/evidence/healthz.png -o healthz.png
+shard drive get tasks/t_ab12/notes.md --sha256 <sha256>   # exactly that version
+shard drive rm tasks/t_ab12/notes.md
+```
+
+- Every `put` is a new version named by the SHA-256 of its bytes, printed after the path; saving the bytes that are
+  already current keeps that version. `get --sha256` reads any version, also after its path was overwritten or
+  removed, so a report that names a file's sha256 always opens the bytes it was written with.
+- `get` writes the bytes to standard output, or to a file with `-o`, once they match their SHA-256; with `--json` it
+  returns `content_base64` with `sha256`, `size` and `content_type`.
+- `put <local-file> [<drive-path>]`: the drive path defaults to the file's name, and `-` reads standard input. The
+  type comes from the extension (`.png` image/png, `.md` text/markdown) unless `--content-type` names one. `--json`
+  returns the saved `file`.
+- `ls [prefix]` lists the current files by path, 200 to a page (`--limit` up to 1000, `--cursor`, `--all`); `--json`
+  returns `data` (each file with its `sha256`) and `next_cursor`.
+- The drive is the API key's project, or `--project <id>`. Signed in (`shard auth login`), `--project` takes any of
+  your projects by id or slug, and without an API key the drive is your default project's.
+
+## Model template (0.25.0+)
+
+`shard models` shows which harness, model and effort each role of a task runs with, from the Claude and Codex accounts
+your organization connected: master plans and coordinates, builder does the work, hard takes the hardest parts, light
+the small ones and reviewer reviews with a fresh context.
+
+```sh
+shard models
+# Primary: claude (connected first), secondary: codex
+# Connected: claude (max), codex (pro)
+#
+# ROLE      HARNESS  MODEL        EFFORT               WAITS UNTIL
+# master    claude   opus         medium (plans high)  -
+# builder   claude   opus         high                 -
+# hard      claude   fable        high                 -
+# light     codex    gpt-6.1-sol  low                  -
+# reviewer  codex    gpt-6.1-sol  medium               -
+shard models primary codex                  # this project's primary
+shard models primary claude --org acme      # the organization's default
+shard models primary clear
+```
+
+- A role's harness, model and effort go straight to `shard conversations start --app <harness> --model <model>
+  --effort <effort>` (`default`: leave out `--effort`).
+- `--harness claude|codex` keeps a running task's master, builder and hard work on its provider; `--attempt <n>` (1 to
+  10) shows the template for a retry, on the other provider or one tier up.
+- A role whose account waits for its next usage window shows until when, and what the other provider would run now,
+  to offer the person; nothing switches on its own.
+- The primary provider is the project's choice when it has one, else the organization's, else the provider connected
+  first. `shard models primary` sets the project's (owners and admins, or the project's API key), and with `--org` the
+  organization's default (owners and admins, signed in); `clear` removes the choice. `--json` returns the template:
+  `primary`, `primary_source`, `secondary`, `connected` and `roles`.
+
 ## Default shared volumes (0.24.0+)
 
 ```sh

package/dist/account-args.js

@@ -269,6 +269,11 @@ export const ACCOUNT_COMMANDS = [
         options: { confirm: { type: 'string', value: '<slug>', description: 'The organization’s slug, typed out (required).' }, ...YES('the deletion') },
     },
     { path: ['projects', 'list'], summary: 'List the organization’s projects (* marks the default)', positionals: [], options: { ...ORG } },
+    { path: ['projects', 'link'], summary: 'Make a local folder one of your projects, prepared in the background and kept as this computer’s live copy (0.25.0+)', positionals: [{ name: 'path', required: true }], options: {
+            prompt: { type: 'string', value: '<text>', description: 'Also start a conversation in that folder with this first message.' },
+            'prompt-file': { type: 'string', value: '<file|->', description: 'Read that first message from a UTF-8 file or stdin (-), up to 256 KiB.' },
+            app: { type: 'string', value: '<claude|codex>', description: 'Agent app of that conversation (default claude).' },
+        } },
     { path: ['projects', 'sync', 'list'], summary: 'Show selected local projects and their preparation state', positionals: [], options: {} },
     { path: ['projects', 'sync', 'add'], summary: 'Prepare and keep this selected local project synced', positionals: [{ name: 'path', required: true }], options: { wait: { type: 'boolean', description: 'Prepare now and wait for its published environment; otherwise the device helper prepares it in the background.' } } },
     { path: ['projects', 'sync', 'pause'], summary: 'Pause background preparation of this local project', positionals: [{ name: 'path', required: true }], options: {} },

package/dist/account-pool.js

@@ -2,6 +2,7 @@ import { out, resolveWorkspace } from "./commands.js";
 import { UsageError } from "./errors.js";
 import { claudeLoginUrls, requireClaudeTerminal, runWorkspaceLogin } from "./claude-cloud-login.js";
 import { openMachine } from "./filesystem-commands.js";
+import { codexAppAccountNotice } from "./codex-cloud.js";
 const PROVIDERS = { claude: 'Claude', codex: 'ChatGPT / Codex' };
 const WINDOW_LABELS = { five_hour: '5-hour', seven_day: 'Weekly', seven_day_opus: 'Weekly Opus', seven_day_sonnet: 'Weekly Sonnet', primary: 'Primary', secondary: 'Secondary' };
 /** A window's length as a title, as Claude's windows read: "Weekly", "5-hour", "2-day", "90-minute". */
@@ -245,7 +246,10 @@ export const ACCOUNT_POOL_HANDLERS = {
         const follows = account.provider === 'claude'
             ? 'New conversations start with it; running ones continue on it, and Remote Control turns back on by itself.'
             : `New conversations and every running conversation VM use it; Codex Cloud moves to it${previous ? ` (Cloud threads started on ${name(previous)} stay in that ChatGPT account)` : ''}.`;
-        out(ctx, previous || !isActive(account) ? `${name(active)} is the active ${PROVIDERS[account.provider]} account. ${follows}\n` : `${name(active)} is already the active ${PROVIDERS[account.provider]} account.\n`, { ...list, account: active });
+        // codex_app (0.25.0+): the Codex app here opens the account's Cloud threads only once it is signed in to it.
+        const app = account.provider === 'codex' ? await codexAppAccountNotice(ctx, active) : null;
+        out(ctx, (previous || !isActive(account) ? `${name(active)} is the active ${PROVIDERS[account.provider]} account. ${follows}\n` : `${name(active)} is already the active ${PROVIDERS[account.provider]} account.\n`)
+            + (app?.line ? `${app.line}\n` : ''), { ...list, account: active, ...(account.provider === 'codex' ? { codex_app: app ? { login: app.login, notice: app.line } : null } : {}) });
         return 0;
     },
 };

package/dist/acp-journal.js

@@ -90,6 +90,28 @@ export class AcpJournal {
     }
     #wanted() { return !this.#signal.aborted && !this.rpc.closed && this.#paused === 0 && (this.rpc.busy || this.#cursor.prompt_id !== undefined); }
     async #deliver(inputId, message) {
+        let failures = 0;
+        const started = performance.now();
+        while (true) {
+            this.#signal.throwIfAborted();
+            try {
+                return await this.#deliverOnce(inputId, message);
+            }
+            catch (error) {
+                // Guest restarts can refuse a new input command while its native
+                // supervisor keeps running. Its persisted receipt deduplicates this
+                // exact input id, including a command accepted before the refusal.
+                // An unverified receipt or a permanent error still stops delivery.
+                if (!(error instanceof ShardfluxApiError) || !error.retryable)
+                    throw error;
+                const remaining = RECONNECT_BUDGET_MS - (performance.now() - started);
+                if (remaining <= 0)
+                    throw new Error('ACP input reconnect timed out; load this session to continue.', { cause: error });
+                await delay(Math.min(reattachDelayMs(error, ++failures), remaining), undefined, { signal: this.#signal });
+            }
+        }
+    }
+    async #deliverOnce(inputId, message) {
         const dir = `/home/user/.local/share/shardflux/acp/${this.#conversation}`;
         const payload = Buffer.from(`{"mode":"input","input_id":${JSON.stringify(inputId)},"message":${message}}\n`);
         if (payload.length <= ONE_SHOT_INPUT) {
@@ -133,7 +155,7 @@ export class AcpJournal {
         finally {
             await this.#cell.exec.cancel(session.session_id, 0).catch(() => undefined);
         }
-        // Never resend an uncertain mutation. Its stable input identity is fenced by CVB before provider stdin.
+        // Retries retain inputId: CVB persists its receipt before provider stdin.
     }
     start() {
         this.#initial ??= this.#replay().then(() => { this.#ready = true; this.#follow(); }).catch(error => { this.rpc.close(error instanceof Error ? error : new Error(String(error))); throw error; });

package/dist/acp-permission-elsewhere.d.ts

@@ -0,0 +1,38 @@
+import type { ConversationPermission } from '@shardflux/sdk';
+import type { ObjectValue } from './acp-rpc.js';
+/** The part of the SDK client the watch reads: GET /v1/conversations/{id}/permissions (0.28.0+). */
+export interface PermissionsReader {
+    conversations: {
+        permissions(id: string, p: {
+            state?: ConversationPermission['state'];
+            limit?: number;
+            cursor?: string;
+        }): Promise<{
+            data: ConversationPermission[];
+            nextCursor: string | null;
+        }>;
+        permission(id: string, permissionId: string): Promise<ConversationPermission>;
+    };
+}
+/** How often the watch reads the API while the editor's permission prompt is open (it never touches the VM). */
+export declare const ELSEWHERE_POLL_MS = 1500;
+/** The tool and command, path or URL the guest records for an ACP permission request (services/guest-agent ACPPermissionAsk). */
+export declare function requestIdentity(params: ObjectValue): {
+    tool: string | null;
+    detail: string;
+};
+/**
+ * While the editor shows the agent's permission prompt, the journal relay is paused, so nothing else of the turn reaches
+ * the editor. The same request is listed through the API, where a person can answer it too (the Shard client, the CLI,
+ * MCP). This resolves with the request once it leaves `pending` that way (answered through the API, or closed because
+ * the agent no longer waits), so the relay can withdraw the editor's prompt and go on with the turn. The request is the
+ * newest one of the conversation with the prompt's tool and command, path or URL that was reported as the prompt opened
+ * or still waits. It resolves null on an API without permission requests (404, 503) or when `signal` ends the prompt;
+ * other errors are retried.
+ */
+export declare function answeredElsewhere(client: PermissionsReader, conversationId: string, params: ObjectValue, openedAt: number, signal: AbortSignal, pollMs?: number): Promise<ConversationPermission | null>;
+/**
+ * The editor-side answer matching a request answered elsewhere: the option of its decision's kind (as the guest picks
+ * it), or a cancelled outcome. The agent already has the first answer; this one only completes the relayed request.
+ */
+export declare function outcomeFor(p: ConversationPermission, params: ObjectValue): ObjectValue;