@shardflux/cli 0.28.0 → 0.28.1

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## Unreleased
 
+- The Shardflux app 0.9.2 (0.28.1+): `shard` installs and updates `@shardflux/desktop-darwin-arm64` / `-x64` and
+  `@shardflux/desktop-linux-x64` / `-arm64` 0.9.2 (Stop in ⌘1, organization choice at the first sign-in, Sign in after
+  signing out).
+
+- Return the coding-agent setup guide without loading the account command handlers.
+
+- Manual landing uses the result’s own ready computer or the persistent project reader, so deleting an unrelated thread does not interrupt it.
+
+- Check T3 presence directly during startup, avoiding unrelated desktop-app probes before every command.
+
+- Orchestrator inputs preserve long pastes, including their final instruction, without an application character cap. `shard orchestrator say` sends the full text to the API.
+
+- Land a finished conversation in its own repository's linked folder when a project holds several repositories.
+  Preserve the hub's default branch when it belongs to another repository.
+
+- Load only the selected command and skip optional setup modules when their local state is absent.
+
+
+- Load interactive command surfaces on demand, keeping help/version and simple commands fast while preserving command parsing, saved-work housekeeping, setup guards and install registration.
+
+- Codex Cloud admission (0.28.1+, SDK 0.30.1): a stopped startup/open reports its stored reason and recovery instruction immediately (`codex_admission_stopped`), instead of calling it pending or pointing only at connector status.
+
+- Stored-file recovery (0.28.1+): workspace views show when files are saved for recovery; resume restarts the workspace from those files.
+
 - `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
@@ -17,22 +41,22 @@
 - 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,
+- Orchestrator answer media (0.28.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
+- Orchestrator report cards (0.28.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
+- Board content at any length (0.28.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
+- Your brain (0.28.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
@@ -58,18 +82,18 @@
   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
+- Auto land switch (0.28.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
+- Message delivery (0.28.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,
+- One Shardflux app (0.28.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
@@ -84,31 +108,31 @@
   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
+- Device registration (0.28.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 agents on this computer (0.28.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.
+- First prompts (0.28.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
+- Device helper (0.28.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.
+- Filesystem recovery (0.28.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.
+- Admission queue waits (0.28.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>`
+- `shard orchestrator` (0.28.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
@@ -118,13 +142,13 @@
   <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
+- `shard needs-you` (0.28.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
+- `shard agents models` (0.28.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 ./`)
@@ -140,7 +164,7 @@
 - `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. 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).
+  (`cloud_transcription_off`) and exits 1 (0.28.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

@@ -1,5 +1,7 @@
 # @shardflux/cli: `shard`
 
+Use `shard --help` or `shard <command> --help` to explore commands before signing in.
+
 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.
@@ -127,8 +129,8 @@ Model choices come from your cloud agent's session and use the same coding tools
 Project files synchronize before each message and before its completion (0.22.0+): review remote edits in T3’s
 Changes panel and checkpoints, and send local edits to the next turn. Conflicting versions are retained with
 a `.shard-conflict-<agent>` suffix. Sync runs between turns; an idle T3 thread needs no file watcher.
-The provider is registered automatically when T3 Code is installed, on macOS and on Linux from its .deb or AppImage
-(0.17.0+). Choose **Sign in** on its card in T3's provider settings: T3 runs `shard acp --login` in its own terminal,
+At command startup, Shardflux checks for T3 Code and registers the provider automatically on macOS and on Linux
+from its .deb or AppImage (0.17.0+). Choose **Sign in** on its card in T3's provider settings: T3 runs `shard acp --login` in its own terminal,
 which creates or signs in to your account (with this computer's Codex login, or your email) and connects Claude Code
 and Codex, skipping every step that is already done (0.15.0+). Editors that launch agents from the ACP registry
 run the same sign-in as `shard --login` (0.22.0+).
@@ -305,6 +307,11 @@ shard conversations landing            # auto (default), pr or off for this proj
 shard conversations landing backups    # then: shard conversations landing restore <backup>
 ```
 
+To land a finished conversation manually, run `shard conversations land <id> merge`. In a project with several
+repositories it chooses a linked folder of that conversation's repository; the hub's default branch for another
+repository stays where it is. `--path <folder>` chooses the destination explicitly. From 0.28.1, manual landing
+uses the result’s own ready computer or the project reader, so deleting an unrelated thread does not interrupt it.
+
 For application workspace commands, `shard signup` creates an account and saves a project key, or set
 `SHARDFLUX_API_KEY` to a key from the console and run `shard login`. `shard --help` lists every command.
 
@@ -735,8 +742,10 @@ 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). |
-| `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). |
+| `orchestrator say [--wait [--timeout D]] [--task ID\|--report ID\|--needs-you ID\|--input ID\|--conversation ID] <words...>`, `orchestrator list [--all]`, `orchestrator retry\|dismiss\|restore <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-0280). |
+| `brain ls [prefix] [--org O] [--all] [--limit N] [--cursor C]`, `brain get <path> [--org O] [--sha256 HEX] [-o FILE]` | Your brain (0.28.0+): your orchestrator's answers, reports and notes, read from any device. See [Your brain](#your-brain-0280). |
 | `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 archive\|unarchive\|seen <id...>` (`c archive`) | Your inbox, the same on every device (0.28.0+): archive conversations, bring them back, or mark them seen. `--json` prints `{data, skipped}`. See [Conversations](#conversations). |
 | `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+). |
@@ -1671,6 +1680,24 @@ 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.
 
+Your inbox is the same on every device (0.28.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, so a result that finished before then is no longer new to you in the Shardflux app or any
+other client. Name one conversation or many in one command. Only your view changes: the conversations, their agents
+and computers carry on, and everyone else keeps their own inbox. `--json` prints the API's answer, `{data, skipped}`:
+the conversations with your `seen_at` and `dismissed_at`, and the ids not found. `shard c get --json` and
+`shard c list --json` carry the same two fields.
+
+```sh
+shard c archive conv_k3m5q7s2u4w6y3b5d7f2h4j6ln conv_a7k2m4q6s3t5v7x2z4b6d3f5h7
+# Archived conv_k3m5q7s2u4w6y3b5d7f2h4j6ln  Fix login
+# Archived conv_a7k2m4q6s3t5v7x2z4b6d3f5h7  Upgrade the test runner
+shard c unarchive conv_a7k2m4q6s3t5v7x2z4b6d3f5h7
+# Unarchived conv_a7k2m4q6s3t5v7x2z4b6d3f5h7  Upgrade the test runner
+shard c seen conv_k3m5q7s2u4w6y3b5d7f2h4j6ln
+# Marked seen conv_k3m5q7s2u4w6y3b5d7f2h4j6ln  Fix login
+```
+
 `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
@@ -1684,6 +1711,8 @@ shard c delete conv_k3m5q7s2u4w6y3b5d7f2h4j6ln --yes
 
 ### Your orchestrator (0.28.0+)
 
+`shard orchestrator say` passes your words to the API as one input, without cutting the final instruction.
+
 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
@@ -1691,25 +1720,33 @@ 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
+# Training is 73% done, on pace to finish at 16:40
+#   Moved
+#   - Loss is down to 1.84: from 2.31 at step 5,000 (14:02)
+#   - Checkpoint saved: at step 7,000
+#   Still open
+#   - Eval has not run: it starts after the last checkpoint
+#   media: loss-curve.png (image, 1200×800, 84.0 KB)
 #   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
+# in_7wcx227ovjpei4u6i47llu7w4i	done	Lets check on our language model training progress	Training is 73% done, on pace to finish at 16:40
 ```
 
-`--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 answer card is the verdict, then its points under the headings the orchestrator chose (a point's time in your
+local time; an answer written as plain facts prints its facts), then a media line for each picture, video or file it
+shows (an image with its width×height once measured). Each is a file on the project drive: `--json` has its
+`file.path` and `file.sha256`, and `shard drive get <path> --sha256 <sha256> -o <file>` saves it. `--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
+dismissed with `shard orchestrator dismiss`); `shard orchestrator restore <input-id>` (0.28.0+) brings one back on every
+device. 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}`).
 
@@ -1977,6 +2014,32 @@ shard drive rm tasks/t_ab12/notes.md
 - 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.
 
+## Your brain (0.28.0+)
+
+`shard brain` reads your brain: your archive in an organization, kept by your orchestrator. Every answer it publishes is
+filed as `reports/<YYYY-MM-DD>/<folder>/report.md` with the answer's media next to it (image thumbnails under
+`.thumbs/`), with its own notes and files and an `index.md` of everything, newest first. Your orchestrator writes it;
+you read it from any device, with every computer asleep. Paths are relative to the brain's root, the names `~/brain`
+shows on your orchestrator's computer.
+
+```sh
+shard brain get index.md
+shard brain ls reports/2026-10-17/
+# SIZE      SAVED                 TYPE           PATH
+# 195.3 KB  2026-10-17 09:12:40Z  image/png      reports/2026-10-17/training-progress-ab12cd34/loss.png
+# 1.2 KB    2026-10-17 09:12:41Z  text/markdown  reports/2026-10-17/training-progress-ab12cd34/report.md
+shard brain get reports/2026-10-17/training-progress-ab12cd34/report.md
+shard brain get reports/2026-10-17/training-progress-ab12cd34/loss.png -o loss.png
+```
+
+- `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`), `next_cursor` and the brain's `version`, which moves whenever anything
+  in it changes.
+- `get` writes the bytes to standard output, or to a file with `-o`, once they match their SHA-256; `--sha256` reads
+  exactly that version, and `--json` returns `content_base64` with `sha256`, `size` and `content_type`.
+- Signed in, it is your brain in your saved organization (`shard orgs use`), else your only one, or `--org <id|slug>`;
+  with `SHARDFLUX_API_KEY` set, the brain of the person who created that key.
+
 ## 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
@@ -2021,3 +2084,5 @@ shard volumes detach --machine datasets
 ```
 
 Defaults mount in new and running conversations. Removal waits for current work to finish and preserves manual attachments. Add `--json` to read propagation results.
+
+Bare `shard` in a coding-agent shell or without a TTY returns its setup guide using locally saved sign-in and API-key state.

package/dist/account-commands.d.ts

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

package/dist/account-commands.js

@@ -21,7 +21,8 @@ import { API_KEY_TOOL_PERMISSIONS, CheckoutTimeoutError, Shardflux, ShardfluxAcc
 import { CLI_VERSION, UUID, parseDuration, parsePositiveInt } from "./args.js";
 import { openUrl } from "./browser.js";
 import { defaultClientName, startDeviceAuthorization, waitForDeviceSession } from "./browser-login.js";
-import { setupGuide, setupGuideText } from "./agent-setup.js";
+import { agentSetupGuide, setupGuideText } from "./agent-setup.js";
+export { agentSetupGuide } from "./agent-setup.js";
 import { allOrgs, allProjects, byRef, choices, findOrg, gone, keyOrganizationWarning, keyScope, resolveOrg, resolveProject, staleDefaultOrg } from "./account-scope.js";
 import { readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
@@ -768,11 +769,6 @@ function wantsBrowser(ctx, values) {
         return true;
     return ctx.input.interactive && !ctx.json;
 }
-/** The setup guide for this computer: whether a session and an API key are saved (no network call). */
-export function agentSetupGuide(ctx) {
-    const profile = ctx.store.profile(ctx.apiUrl);
-    return setupGuide({ signedIn: ctx.sessionSource() !== null, email: profile.session?.user?.email ?? null, apiKey: profile.api_key !== undefined || Boolean(ctx.io.env.SHARDFLUX_API_KEY?.trim()) });
-}
 /**
  * After `orgs use` / `projects use` (0.20.2+): the defaults moved, but workspace, agent and usage commands use the API
  * key, which may act in another organization. Says so; on a terminal offers to make a key for the new default (a

package/dist/agent-git-commands.d.ts

@@ -6,5 +6,4 @@ export declare function rememberGitAgent(ctx: Ctx, ws: Workspace, folder: string
 export declare const AGENT_GIT_HANDLERS: Record<string, Handler>;
 /** No Git or network work when no records are due. Active passes are bounded and never infer deletion from an error. */
 export declare function housekeeping(ctx: HousekeepingCtx, now?: () => number, budgetMs?: number): Promise<void>;
-/** Help/version starts also clean saved work, without requiring credentials when nothing is due. */
-export declare function startupHousekeeping(ctx: Pick<Ctx, 'io' | 'store' | 'signal'>): Promise<void>;
+export { startupHousekeeping } from './startup-housekeeping.js';

package/dist/agent-git-commands.js

@@ -1,9 +1,8 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { Shardflux, ShardfluxApiError } from '@shardflux/sdk';
+import { ShardfluxApiError } from '@shardflux/sdk';
 import { out, resolveWorkspace, str } from "./commands.js";
 import { AgentStateStore } from "./agent-state.js";
-import { resolveApiUrl } from "./args.js";
 import { AgentGit, agentName } from "./agent-git.js";
 import { shardRemote } from "./git-remote.js";
 import { projectIdentity } from "./project-identity.js";
@@ -274,22 +273,4 @@ export async function housekeeping(ctx, now = Date.now, budgetMs = 1500) {
         clearTimeout(timer);
     }
 }
-/** Help/version starts also clean saved work, without requiring credentials when nothing is due. */
-export async function startupHousekeeping(ctx) {
-    try {
-        const state = new AgentStateStore(ctx.store.dir).read();
-        if (!state.git_repositories || !Object.keys(state.git_repositories).length)
-            return;
-        const apiUrl = resolveApiUrl(undefined, ctx.io.env.SHARDFLUX_API_URL ?? ctx.io.env.SHARDFLUX_BASE_URL);
-        let cloud;
-        await housekeeping({ ...ctx, apiUrl, cloud: () => {
-                const key = ctx.io.env.SHARDFLUX_API_KEY?.trim() || ctx.store.profile(apiUrl).api_key?.token;
-                if (!key)
-                    throw new UsageError('saved agents need a project key for housekeeping; run shard setup');
-                return cloud ??= new Shardflux({ apiKey: key, baseUrl: apiUrl, versionCheck: false });
-            } });
-    }
-    catch (error) {
-        ctx.io.stderr.write(`shard housekeeping: ${error instanceof Error ? error.message : String(error)}\n`);
-    }
-}
+export { startupHousekeeping } from "./startup-housekeeping.js";

package/dist/agent-setup.d.ts

@@ -1,10 +1,10 @@
+import type { Ctx } from './commands.js';
 /**
  * Set in a coding agent's shell: Claude Code (CLAUDECODE), Codex (CODEX_SANDBOX, CODEX_THREAD_ID), Cursor's agent
  * (CURSOR_AGENT) and Gemini CLI (GEMINI_CLI). Such a shell may have a terminal (Cursor and Codex can run commands in a
  * PTY), but nobody types into it: a full-screen view or a prompt there waits forever.
  */
-export declare const AGENT_SHELL_VARIABLES: readonly ["CLAUDECODE", "CODEX_SANDBOX", "CODEX_THREAD_ID", "CURSOR_AGENT", "GEMINI_CLI"];
-export declare function codingAgentShell(env: Record<string, string | undefined>): boolean;
+export { AGENT_SHELL_VARIABLES, codingAgentShell } from './agent-shell.js';
 /**
  * How the agent runs the setup (0.20.1+): it does the work, the person only decides. Onboarding testers (2026-10-12)
  * found agents handing them commands, links and codes, writing paragraphs and asking open questions.
@@ -46,4 +46,6 @@ export interface GuideState {
     apiKey: boolean;
 }
 export declare function setupGuide(state: GuideState): SetupGuide;
+/** The setup guide for this computer: whether a session and an API key are saved (no network call). */
+export declare function agentSetupGuide(ctx: Ctx): ReturnType<typeof setupGuide>;
 export declare function setupGuideText(g: SetupGuide): string;

package/dist/agent-setup.js

@@ -18,10 +18,7 @@ import { legalFields } from "./legal.js";
  * (CURSOR_AGENT) and Gemini CLI (GEMINI_CLI). Such a shell may have a terminal (Cursor and Codex can run commands in a
  * PTY), but nobody types into it: a full-screen view or a prompt there waits forever.
  */
-export const AGENT_SHELL_VARIABLES = ['CLAUDECODE', 'CODEX_SANDBOX', 'CODEX_THREAD_ID', 'CURSOR_AGENT', 'GEMINI_CLI'];
-export function codingAgentShell(env) {
-    return AGENT_SHELL_VARIABLES.some((name) => (env[name]?.trim() ?? '') !== '');
-}
+export { AGENT_SHELL_VARIABLES, codingAgentShell } from "./agent-shell.js";
 /**
  * How the agent runs the setup (0.20.1+): it does the work, the person only decides. Onboarding testers (2026-10-12)
  * found agents handing them commands, links and codes, writing paragraphs and asking open questions.
@@ -137,6 +134,11 @@ function stepText(n, s) {
         ...(s.note ? [`     ${wrap(s.note, '     ', 96)}`] : []),
     ].join('\n');
 }
+/** The setup guide for this computer: whether a session and an API key are saved (no network call). */
+export function agentSetupGuide(ctx) {
+    const profile = ctx.store.profile(ctx.apiUrl);
+    return setupGuide({ signedIn: ctx.sessionSource() !== null, email: profile.session?.user?.email ?? null, apiKey: profile.api_key !== undefined || Boolean(ctx.io.env.SHARDFLUX_API_KEY?.trim()) });
+}
 export function setupGuideText(g) {
     return [
         'Set up Shardflux for your user. How:',

package/dist/agent-shell.d.ts

@@ -0,0 +1,2 @@
+export declare const AGENT_SHELL_VARIABLES: readonly ["CLAUDECODE", "CODEX_SANDBOX", "CODEX_THREAD_ID", "CURSOR_AGENT", "GEMINI_CLI"];
+export declare function codingAgentShell(env: Record<string, string | undefined>): boolean;

package/dist/agent-shell.js

@@ -0,0 +1,5 @@
+// Identify an agent shell before loading onboarding or command handlers.
+export const AGENT_SHELL_VARIABLES = ['CLAUDECODE', 'CODEX_SANDBOX', 'CODEX_THREAD_ID', 'CURSOR_AGENT', 'GEMINI_CLI'];
+export function codingAgentShell(env) {
+    return AGENT_SHELL_VARIABLES.some((name) => (env[name]?.trim() ?? '') !== '');
+}

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.28.0";
+export declare const CLI_VERSION = "0.28.1";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;

package/dist/args.js

@@ -15,7 +15,7 @@ import { BOARD_COMMANDS } from "./board-args.js";
 import { ORCHESTRATOR_COMMANDS } from "./orchestrator-args.js";
 import { UsageError } from "./errors.js";
 import { DEFAULT_CHOICE, MODEL_CHOICES } from "./agent-models.js";
-export const CLI_VERSION = '0.28.0';
+export const CLI_VERSION = '0.28.1';
 export const GLOBAL_OPTIONS = {
     'api-url': { type: 'string', value: '<url>', description: 'API base URL (default $SHARDFLUX_API_URL, else https://api.shardflux.dev).' },
     json: { type: 'boolean', description: 'Print machine-readable JSON on stdout (errors as JSON on stderr).' },

package/dist/cli-proxy.d.ts

@@ -16,8 +16,7 @@ export declare const cliProxyTools: {
     inVm: () => boolean;
     kill: (pid: number) => void;
 };
-/** The launchd agent that keeps the forwarder on 127.0.0.1:8317 on a Mac. */
-export declare const FORWARD_LABEL = "dev.shardflux.cli-proxy-forward";
+export { FORWARD_LABEL, forwarderPlistPath, refreshForwarderAgent } from './forwarder-refresh.js';
 /** Where every VM finds the hub info (the machine template carries it). */
 export declare const VM_HUB_INFO_PATH = "/home/user/.config/shardflux-cli-proxy.json";
 export interface LocalLogin {
@@ -151,7 +150,6 @@ export interface PlistOptions {
 }
 /** The launchd agent: `shard cli-proxy forward` at login, started again whenever it exits. */
 export declare function forwarderPlist(o: PlistOptions): string;
-export declare function forwarderPlistPath(home: string): string;
 /** Whether Shardflux's forwarder answers on 127.0.0.1:port, and for which hub. */
 export interface ForwarderIdentity {
     hub: string | null; /** `mac`: shard cli-proxy forward; `vm`: sf-agent cli-proxy-forward. */
@@ -168,16 +166,6 @@ export interface LaunchdDeps {
     identity?: () => Promise<ForwarderIdentity | null>;
     sleep?: (ms: number) => Promise<void>;
 }
-/**
- * After `shard` is updated, the launchd forwarder still runs the program it started with. Called on every shard run
- * (one file read on macOS): an installed forwarder agent recorded for another shard version is started again, on this
- * one. Returns whether it was.
- */
-export declare function refreshForwarderAgent(env: Record<string, string | undefined>, dir: string, deps?: {
-    run?: ProgramRunner;
-    uid?: number;
-    platform?: NodeJS.Platform;
-}): Promise<boolean>;
 /** Installs (or refreshes) the launchd agent and waits until the forwarder answers. macOS only. */
 export declare function installForwarderAgent(ctx: Ctx, apiUrl: string, deps?: LaunchdDeps): Promise<string>;
 /**

package/dist/cli-proxy.js

@@ -47,7 +47,8 @@ export const cliProxyTools = {
     kill: (pid) => { process.kill(pid, 'SIGTERM'); },
 };
 /** The launchd agent that keeps the forwarder on 127.0.0.1:8317 on a Mac. */
-export const FORWARD_LABEL = 'dev.shardflux.cli-proxy-forward';
+import { FORWARD_LABEL, forwarderPlistPath, recordForwarder } from "./forwarder-refresh.js";
+export { FORWARD_LABEL, forwarderPlistPath, refreshForwarderAgent } from "./forwarder-refresh.js";
 /** Where every VM finds the hub info (the machine template carries it). */
 // Outside ~/.config/shardflux, which machines and templates never capture (the platform's per-VM state).
 export const VM_HUB_INFO_PATH = '/home/user/.config/shardflux-cli-proxy.json';
@@ -470,9 +471,6 @@ ${Object.entries(env).map(([k, v]) => `    <key>${k}</key>\n    <string>${xml(v)
 </plist>
 `;
 }
-export function forwarderPlistPath(home) {
-    return join(home, 'Library', 'LaunchAgents', `${FORWARD_LABEL}.plist`);
-}
 /** Whether Shardflux's forwarder (this computer's, or a VM's sf-agent) answers on 127.0.0.1:port, and for which hub. */
 export async function forwarderIdentity(port = CLI_PROXY_PORT) {
     try {
@@ -492,29 +490,6 @@ export function inShardfluxVm() {
 }
 /** The forwarder that answers is this shard's (an update replaces the program, not the running process). */
 const current = (id) => id !== null && id.kind === 'mac' && id.version === CLI_VERSION;
-/** The shard version the launchd forwarder runs (refreshForwarderAgent compares it with this one). */
-function recordForwarder(dir) {
-    new AgentStateStore(dir).update((doc) => { doc.cli_proxy_forwarder = { version: CLI_VERSION }; });
-}
-/**
- * After `shard` is updated, the launchd forwarder still runs the program it started with. Called on every shard run
- * (one file read on macOS): an installed forwarder agent recorded for another shard version is started again, on this
- * one. Returns whether it was.
- */
-export async function refreshForwarderAgent(env, dir, deps = {}) {
-    if ((deps.platform ?? process.platform) !== 'darwin')
-        return false;
-    if (!existsSync(forwarderPlistPath(env.HOME || homedir())))
-        return false;
-    const store = new AgentStateStore(dir);
-    const record = store.read().cli_proxy_forwarder;
-    if (record?.version === CLI_VERSION)
-        return false;
-    // Recorded first: a failed restart is not retried on every command (the next import installs the agent again).
-    recordForwarder(dir);
-    await (deps.run ?? cliProxyTools.run)('launchctl', ['kickstart', '-k', `gui/${deps.uid ?? userInfo().uid}/${FORWARD_LABEL}`]);
-    return true;
-}
 /** Installs (or refreshes) the launchd agent and waits until the forwarder answers. macOS only. */
 export async function installForwarderAgent(ctx, apiUrl, deps = {}) {
     const runtime = ctx.runtime;

package/dist/codex-cloud.js

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { spawn } from 'node:child_process';
-import { ShardfluxApiError, codexAccountMatches, localCodexLogin } from '@shardflux/sdk';
+import { CodexAdmissionStoppedError, ShardfluxApiError, codexAccountMatches, localCodexLogin } from '@shardflux/sdk';
 import { CodedError, UsageError } from "./errors.js";
 import { json } from "./format.js";
 import { syncAgentCredentials } from "./agent-credentials.js";
@@ -311,6 +311,8 @@ export async function openCodexConversation(ctx, c, history) {
         if (task.state !== 'canceled')
             task = await ctx.cloud().codex.waitTask(c.id, { timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
     }
+    if (task.state === 'attention' && task.next_attempt_at === null)
+        throw new CodexAdmissionStoppedError(task);
     if (task.state === 'canceled')
         throw new UsageError('This conversation’s Codex executor was removed. Start a new Cloud conversation; its saved branch and history remain available.');
     if (task.state !== 'active' || !task.thread_id)

package/dist/device-bridge.d.ts

@@ -2,6 +2,7 @@ import type { CellClient, Workspace } from '@shardflux/sdk';
 import type { Ctx } from './commands.js';
 import type { Conversation } from './conversations.js';
 import type { DirListing, LinkedProject } from './device-folders.js';
+import type { HubSeed } from './project-hub-seed.js';
 export type DeviceChoice = 'once' | 'always' | 'deny';
 export interface DeviceRequest {
     id: string;
@@ -121,7 +122,9 @@ export declare function deviceExec(argv: string[], cwd: string, timeoutSeconds?:
 export type DeviceAsk = (approval: DeviceApproval, signal?: AbortSignal) => Promise<DeviceChoice>;
 export declare class DeviceExecutor {
     #private;
-    constructor(ctx: Ctx, ask: DeviceAsk, deviceId: string);
+    constructor(ctx: Ctx, ask: DeviceAsk, deviceId: string, options?: {
+        seedHub?: (ctx: Ctx, folder: string, projectId: string) => Promise<HubSeed>;
+    });
     /** A new device id for a new sign-in (device-helper.ts): requests for the old one are no longer this device's. */
     set deviceId(id: string);
     get deviceId(): string;

package/dist/device-bridge.js

@@ -229,7 +229,14 @@ export class DeviceExecutor {
     /** Requests that run without asking (device-mode.ts), until their outcome is recorded. */
     #auto = new Map();
     #identity = { at: 0 };
-    constructor(ctx, ask, deviceId) { this.#ctx = ctx; this.#ask = ask; this.#deviceId = deviceId; }
+    /** How an agent's folder link reaches the project hub (project-hub-seed.ts unless a test gives its own hub). */
+    #seedHub;
+    constructor(ctx, ask, deviceId, options = {}) {
+        this.#ctx = ctx;
+        this.#ask = ask;
+        this.#deviceId = deviceId;
+        this.#seedHub = options.seedHub;
+    }
     /** A new device id for a new sign-in (device-helper.ts): requests for the old one are no longer this device's. */
     set deviceId(id) { this.#deviceId = id; this.#identity = { at: 0 }; }
     get deviceId() { return this.#deviceId; }
@@ -578,7 +585,7 @@ export class DeviceExecutor {
             if (r.kind === 'dir_list')
                 result = { state: 'done', dir: await listDeviceDir(target, r.dir ?? {}, ctx.signal) };
             else if (r.kind === 'project_link')
-                result = { state: 'done', project: await linkLocalProject(ctx, target, { ...(r.link?.brief ? { brief: r.link.brief } : {}), harness: r.link?.harness ?? current.harness, projectId: current.project_id, seed: true }) };
+                result = { state: 'done', project: await linkLocalProject(ctx, target, { ...(r.link?.brief ? { brief: r.link.brief } : {}), harness: r.link?.harness ?? current.harness, projectId: current.project_id, seed: true }, undefined, this.#seedHub) };
             else {
                 const f = r.files;
                 if (!f.remote_path.startsWith('/') || /[\0\r\n]/.test(f.remote_path))

package/dist/format.js

@@ -83,6 +83,8 @@ export function workspaceState(w) {
         tags.push('session');
     if (w.deleted_at)
         tags.push(w.ended_reason ? `ended: ${w.ended_reason}` : 'deleted');
+    if (w.storage_recovery)
+        tags.push('files stored');
     return tags.length ? `${w.observed_state} (${tags.join(', ')})` : w.observed_state;
 }
 export function workspaceRow(w) {
@@ -230,6 +232,7 @@ export function workspaceDetail(w) {
         ['id', w.id],
         ['key', w.workspace_key],
         ['state', `${w.observed_state} (desired ${w.desired_state})`],
+        ...(w.storage_recovery ? [['storage', w.storage_recovery.message]] : []),
         ['ready', isReady(w) ? 'yes' : 'no'],
         ['template', `${w.template.slug} v${w.template.version} (${w.template.version_id})`],
         // Immutable paths (0.8.0): the template version whose immutable paths the workspace has mounted, when it has one.

package/dist/forwarder-refresh.d.ts

@@ -0,0 +1,15 @@
+import type { ProgramRunner } from './cli-proxy.js';
+export declare const FORWARD_LABEL = "dev.shardflux.cli-proxy-forward";
+export declare function forwarderPlistPath(home: string): string;
+/** The shard version the launchd forwarder runs (refreshForwarderAgent compares it with this one). */
+export declare function recordForwarder(dir: string): void;
+/**
+ * After `shard` is updated, the launchd forwarder still runs the program it started with. Called on every shard run
+ * (one file read on macOS): an installed forwarder agent recorded for another shard version is started again, on this
+ * one. Returns whether it was.
+ */
+export declare function refreshForwarderAgent(env: Record<string, string | undefined>, dir: string, deps?: {
+    run?: ProgramRunner;
+    uid?: number;
+    platform?: NodeJS.Platform;
+}): Promise<boolean>;

package/dist/forwarder-refresh.js

@@ -0,0 +1,32 @@
+import { existsSync } from 'node:fs';
+import { homedir, userInfo } from 'node:os';
+import { join } from 'node:path';
+import { AgentStateStore } from "./agent-state.js";
+import { CLI_VERSION } from "./args.js";
+export const FORWARD_LABEL = 'dev.shardflux.cli-proxy-forward';
+export function forwarderPlistPath(home) {
+    return join(home, 'Library', 'LaunchAgents', `${FORWARD_LABEL}.plist`);
+}
+/** The shard version the launchd forwarder runs (refreshForwarderAgent compares it with this one). */
+export function recordForwarder(dir) {
+    new AgentStateStore(dir).update((doc) => { doc.cli_proxy_forwarder = { version: CLI_VERSION }; });
+}
+/**
+ * After `shard` is updated, the launchd forwarder still runs the program it started with. Called on every shard run
+ * (one file read on macOS): an installed forwarder agent recorded for another shard version is started again, on this
+ * one. Returns whether it was.
+ */
+export async function refreshForwarderAgent(env, dir, deps = {}) {
+    if ((deps.platform ?? process.platform) !== 'darwin')
+        return false;
+    if (!existsSync(forwarderPlistPath(env.HOME || homedir())))
+        return false;
+    const store = new AgentStateStore(dir);
+    const record = store.read().cli_proxy_forwarder;
+    if (record?.version === CLI_VERSION)
+        return false;
+    // Recorded first: a failed restart is not retried on every command (the next import installs the agent again).
+    recordForwarder(dir);
+    await (deps.run ?? (await import("./cli-proxy.js")).cliProxyTools.run)('launchctl', ['kickstart', '-k', `gui/${deps.uid ?? userInfo().uid}/${FORWARD_LABEL}`]);
+    return true;
+}

package/dist/handler-loader.d.ts

@@ -0,0 +1,3 @@
+import type { Handler } from './commands.js';
+export declare const HANDLER_PATHS: string[];
+export declare function handlerFor(path: string): Promise<Handler | undefined>;

package/dist/handler-loader.js

@@ -0,0 +1,43 @@
+// Exact command ownership, in the same override order as HANDLERS. The parity test catches additions
+// or moves without loading every command module during an ordinary command.
+const groups = [
+    [["projects sync list", "projects sync add", "projects sync pause", "projects sync remove", "projects sync run"], async () => (await import("./project-preparation.js")).PROJECT_PREPARATION_HANDLERS],
+    [["projects link"], async () => (await import("./device-folders.js")).PROJECT_LINK_HANDLERS],
+    [["move"], async () => (await import("./move.js")).MOVE_HANDLERS],
+    [["device approvals", "device requests", "device approve", "device deny"], async () => (await import("./device-approvals.js")).DEVICE_HANDLERS],
+    [["agents codex status", "agents codex enable", "agents codex disable"], async () => (await import("./codex-cloud.js")).CODEX_CLOUD_HANDLERS],
+    [["cli-proxy", "cli-proxy import", "cli-proxy export", "cli-proxy use", "cli-proxy forward"], async () => (await import("./cli-proxy.js")).CLI_PROXY_HANDLERS],
+    [["agents computers"], async () => (await import("./thread-on-computer.js")).THREAD_HANDLERS],
+    [["conversations resume", "conversations reader", "conversations list", "conversations feed", "conversations get", "conversations permissions", "conversations answer", "conversations watch", "conversations send", "conversations start", "conversations wait", "conversations land", "files pull", "conversations move", "conversations archive", "conversations unarchive", "conversations seen", "conversations delete"], async () => (await import("./conversation-commands.js")).CONVERSATION_HANDLERS],
+    [["orchestrator say", "orchestrator list", "orchestrator retry", "orchestrator dismiss", "orchestrator restore"], async () => (await import("./orchestrator-commands.js")).ORCHESTRATOR_HANDLERS],
+    [["board", "task add", "task show", "task edit", "task rm", "task steer", "task land", "task clear-done", "needs-you", "needs-you answer", "approvals", "approvals set", "approvals allow", "approvals remove"], async () => (await import("./board-commands.js")).BOARD_HANDLERS],
+    [["conversations transcript", "conversations events"], async () => (await import("./conversation-transcript.js")).TRANSCRIPT_HANDLERS],
+    [["conversations try"], async () => (await import("./conversation-local.js")).CONVERSATION_HANDLERS],
+    [["conversations landing"], async () => (await import("./worktree-twin-engine.js")).TWIN_HANDLERS],
+    [["secrets log", "credentials list", "credentials enable", "credentials approve", "credentials deny", "credentials forget"], async () => (await import("./credential-prompts.js")).CREDENTIAL_HANDLERS],
+    [["agents credentials login", "agents credentials sync", "agents credentials status", "agents credentials forget"], async () => (await import("./agent-credentials.js")).AGENT_CREDENTIAL_HANDLERS],
+    [["agents accounts", "agents accounts list", "agents accounts usage", "agents accounts add", "agents accounts remove", "agents accounts use", "accounts", "accounts list", "accounts usage", "accounts add", "accounts remove", "accounts use"], async () => (await import("./account-pool.js")).ACCOUNT_POOL_HANDLERS],
+    [["agents models"], async () => (await import("./account-pool.js")).AGENT_MODELS_HANDLERS],
+    [["agents list", "login", "whoami", "version", "feedback", "usage", "workspaces labels", "workspaces hint", "workspaces idle", "workspaces exec-start", "workspaces tunnel", "workspaces exec-read", "workspaces exec-cancel", "workspaces exec-input", "workspaces retention", "projects retention", "workspaces open", "workspaces list", "workspaces get", "workspaces inputs", "workspaces exec", "files read-many", "files read", "files write", "files delete", "files ls", "files stat", "files search", "files patch", "workspaces suspend", "workspaces resume", "workspaces delete", "workspaces close", "workspaces upgrade", "workspaces reset", "workspaces save-as-template", "workspaces changes", "templates list", "templates get", "templates init", "templates build", "templates export", "templates test", "templates builds list", "templates builds get", "templates builds log", "templates builds cancel", "templates languages", "templates packages search", "templates files", "templates diff", "templates draft open", "templates draft status", "templates draft state", "templates draft test", "templates draft publish", "templates draft discard", "workspaces fork", "workspaces resize", "workspaces sessions", "workspaces port expose", "workspaces port ls", "workspaces port close", "workspaces port token", "workspaces port link", "workspaces port callback", "workspaces computer status", "workspaces computer screenshot", "workspaces computer act", "workspaces computer click", "workspaces computer type", "workspaces computer paste-text", "workspaces computer key", "workspaces computer scroll", "workspaces computer move", "workspaces computer drag", "workspaces computer mouse-down", "workspaces computer mouse-up", "workspaces computer hold-key", "workspaces computer wait", "workspaces computer zoom", "workspaces computer cursor", "workspaces computer start", "workspaces computer stop", "workspaces computer stream", "workspaces computer enable", "workspaces computer disable", "workspaces computer inherit", "templates computer-use", "workspaces secrets", "secrets import", "secrets create", "secrets list", "secrets get", "secrets update", "secrets rotate", "secrets versions", "secrets delete", "secrets access-log", "operations list", "operations get", "operations progress", "operations cancel", "operations wait", "executions get"], async () => (await import("./commands.js")).KEY_HANDLERS],
+    [["auth register", "auth verify-email", "auth resend-verification", "auth login", "auth mfa", "auth status", "auth logout", "auth sessions", "auth step-up", "auth password change", "auth password reset", "auth password reset-confirm", "auth email change", "auth email confirm", "auth totp enroll", "auth totp confirm", "auth totp disable", "auth totp recovery-codes", "setup", "signup", "verify", "env", "orgs list", "orgs create", "orgs get", "orgs use", "orgs export", "orgs workspaces", "orgs deletion", "orgs delete", "projects list", "projects create", "projects get", "projects use", "api-keys list", "api-keys create", "api-keys revoke", "members list", "members set-role", "members remove", "invitations list", "invitations create", "invitations revoke", "invitations accept", "billing plans", "billing status", "billing upgrade", "billing portal", "billing invoices", "billing alerts", "billing overage", "audit list", "audit export", "account status", "account export", "account delete", "account cancel-deletion", "egress get", "egress set", "egress history", "egress clear", "volumes list", "status", "volumes open", "volumes create", "volumes get", "volumes delete", "volumes attachments", "volumes attach", "volumes detach", "templates publish", "templates archive"], async () => (await import("./account-commands.js")).ACCOUNT_HANDLERS],
+    [["agents open"], async () => (await import("./agent-commands.js")).AGENT_HANDLERS],
+    [["agents new", "agents fork", "agents park", "agents logs"], async () => (await import("./command-center-actions.js")).CENTER_HANDLERS],
+    [["agents targets", "agents terminal-run", "agents open claude-desktop", "agents open codex-app", "agents open t3", "agents open web", "ssh-proxy"], async () => (await import("./agent-target-commands.js")).TARGET_HANDLERS],
+    [["agents merge", "agents keep", "agents discard", "agents worktree", "agents restore"], async () => (await import("./agent-git-commands.js")).AGENT_GIT_HANDLERS],
+    [["menubar start", "menubar stop", "menubar status", "menubar account"], async () => (await import("./menubar.js")).MENUBAR_HANDLERS],
+    [["machine", "machine open", "machine save", "machine rollback", "template", "template save", "template rollback", "template delete"], async () => (await import("./filesystem-commands.js")).FILESYSTEM_HANDLERS],
+    [["machine setup"], async () => (await import("./machine-setup.js")).MACHINE_SETUP_HANDLERS],
+    [["settings"], async () => (await import("./client-settings.js")).SETTINGS_HANDLERS],
+    [["update"], async () => (await import("./update.js")).UPDATE_HANDLERS],
+    [["agents config-sync"], async () => (await import("./agent-config-sync.js")).AGENT_CONFIG_HANDLERS],
+    [["route", "ask"], async () => (await import("./router-commands.js")).ROUTER_HANDLERS],
+    [["transcribe"], async () => (await import("./transcribe-commands.js")).TRANSCRIBE_HANDLERS],
+    [["drive ls", "drive get", "drive put", "drive rm", "models", "models primary"], async () => (await import("./drive-commands.js")).DRIVE_HANDLERS],
+    [["brain ls", "brain get"], async () => (await import("./brain-commands.js")).BRAIN_HANDLERS],
+];
+const owners = new Map(groups.flatMap(([paths, load]) => paths.map(path => [path, load])));
+export const HANDLER_PATHS = [...owners.keys()];
+export async function handlerFor(path) {
+    const load = owners.get(path);
+    return load ? (await load())[path] : undefined;
+}

package/dist/land.d.ts

@@ -97,7 +97,7 @@ export interface LandDeps {
         tasks: Pick<ReturnType<typeof conversationClient>['tasks'], 'get' | 'recordLanding' | 'steer'>;
         conversations: Pick<ReturnType<typeof conversationClient>['conversations'], 'get' | 'land'>;
     };
-    hubCell(projectId: string): Promise<{
+    hubCell(projectId: string, workspaceIds?: readonly string[]): Promise<{
         cell: TwinCell;
         close(): void;
     }>;

package/dist/land.js

@@ -127,11 +127,11 @@ function message(o) {
     return hub;
 }
 export function landDeps(ctx) {
-    return { client: conversationClient(ctx), hubCell: p => projectHubCell(ctx, p, ctx.signal, 'shard-land'), folder: (p, c, r) => linkedFolder(ctx, p, c, r),
+    return { client: conversationClient(ctx), hubCell: (p, ids) => projectHubCell(ctx, p, ctx.signal, 'shard-land', ids), folder: (p, c, r) => linkedFolder(ctx, p, c, r),
         device: deviceId(ctx.store.dir), stateDir: ctx.store.dir, signal: ctx.signal };
 }
 async function land(d, l, onConflict) {
-    const vm = await d.hubCell(l.projectId);
+    const vm = await d.hubCell(l.projectId, l.workspaceIds);
     try {
         const input = { result: l.result, sources: l.sources.map(s => s.branch), title: l.title, ...(d.hub ? { hub: d.hub } : {}) };
         let hub = await landOnHub(vm.cell, input, d.signal);
@@ -228,7 +228,7 @@ export async function landTask(d, taskId, opts = {}) {
     const repository = workers.find(w => w.repo_remote)?.repo_remote ?? (task.master_id ? (await client.conversations.get(task.master_id).catch(() => null))?.repo_remote : undefined) ?? null;
     const folder = opts.path ?? d.folder(task.project_id, undefined, repository ?? undefined);
     const done = await land(d, { projectId: task.project_id, title, name: taskId, result: resultBranch(taskId), sources: workers.map(w => ({ branch: w.branch, conversation_id: w.id })),
-        base: workers.find(w => w.base_commit)?.base_commit ?? null, folder, repository }, async (hub) => {
+        base: workers.find(w => w.base_commit)?.base_commit ?? null, folder, repository, workspaceIds: workers.map(w => w.workspace_id).filter(Boolean) }, async (hub) => {
         const what = hub.stage === 'integrate' ? `${hub.source} into ${resultBranch(taskId)}` : `${resultBranch(taskId)} into ${hub.into}`;
         await client.tasks.steer(taskId, `Land could not merge ${what}: ${list(hub.conflicts ?? [])} changed on both sides. Merge ${hub.into} from the project hub and every worker branch into ${resultBranch(taskId)}, resolve the conflicts so both changes work (ask the person only if the choice is theirs), run the tests, push ${resultBranch(taskId)} to the hub and seal done again.`, signal);
     });
@@ -267,9 +267,10 @@ export async function landConversation(d, id, opts = {}) {
     const c = await client.conversations.get(id);
     if (c.changes?.uncommitted)
         throw new CodedError('uncommitted_changes', 'The conversation has uncommitted changes.', 'ask its agent to commit them, then land');
-    const folder = opts.path ?? d.folder(c.project_id, c.id);
+    const repository = c.repo_remote ?? null;
+    const folder = opts.path ?? d.folder(c.project_id, c.id, repository ?? undefined);
     const done = await land(d, { projectId: c.project_id, title: c.title || c.branch, name: c.name ?? c.branch.replace(/^shard\//, ''), result: c.branch, sources: [],
-        base: c.base_commit ?? null, folder }, () => Promise.resolve());
+        base: c.base_commit ?? null, folder, repository, workspaceIds: [c.workspace_id] }, () => Promise.resolve());
     let recorded = false, record_error;
     try {
         await client.conversations.land(id, 'merge', { into: done.hub.into, ...(d.signal ? { signal: d.signal } : {}) });

package/dist/linux-helper.js

@@ -4,7 +4,6 @@ import { readFileSync, realpathSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { CLI_VERSION } from "./args.js";
 import { writePrivateFile } from "./credentials.js";
-import { runDeviceHelper } from "./device-helper.js";
 export const HELPER_UNIT = 'shardflux-helper.service';
 export const helperUnitPath = (home) => join(home, '.config/systemd/user', HELPER_UNIT);
 const quote = (s) => '"' + s.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('%', '%%').replaceAll('\n', '\\n').replaceAll('\r', '\\r') + '"';
@@ -83,6 +82,6 @@ export function startLinuxHelper(ctx) {
         writePrivateFile(ctx.store.dir, notice, '1\n');
     }
     const abort = new AbortController();
-    const work = runDeviceHelper({ ...ctx, signal: AbortSignal.any([ctx.signal, abort.signal]) }, { service: true }).catch(() => undefined);
+    const work = import("./device-helper.js").then(({ runDeviceHelper }) => runDeviceHelper({ ...ctx, signal: AbortSignal.any([ctx.signal, abort.signal]) }, { service: true })).catch(() => undefined);
     return async () => { abort.abort(); await work; };
 }

package/dist/machine-setup-guard.d.ts

@@ -0,0 +1,9 @@
+import type { Values } from './args.js';
+type Env = Record<string, string | undefined>;
+export declare const SETUP_VM_ENV = "SHARDFLUX_MACHINE_SETUP_VM";
+/**
+ * While `SHARDFLUX_MACHINE_SETUP_VM` is set (the setup agent's own commands), shard only runs commands on that VM: exec,
+ * file writes from standard input, reads and listings. Returns the refusal, or undefined when the command may run.
+ */
+export declare function setupGuard(env: Env, command: string, values: Values, positionals: string[]): string | undefined;
+export {};

package/dist/machine-setup-guard.js

@@ -0,0 +1,22 @@
+export const SETUP_VM_ENV = 'SHARDFLUX_MACHINE_SETUP_VM';
+/**
+ * While `SHARDFLUX_MACHINE_SETUP_VM` is set (the setup agent's own commands), shard only runs commands on that VM: exec,
+ * file writes from standard input, reads and listings. Returns the refusal, or undefined when the command may run.
+ */
+export function setupGuard(env, command, values, positionals) {
+    const vm = env[SETUP_VM_ENV]?.trim();
+    if (!vm)
+        return undefined;
+    const allowed = ['workspaces exec', 'files write', 'files read', 'files ls', 'files stat', 'version'];
+    if (!allowed.includes(command))
+        return `machine setup runs only shard ws exec, files write and files read on ${vm}`;
+    if (command === 'version')
+        return undefined;
+    if (positionals[0] !== vm)
+        return `machine setup runs commands only on ${vm}`;
+    if (command === 'files write' && values.from !== undefined && values.from !== '-')
+        return 'machine setup writes files only from standard input (--from -)';
+    if (command === 'files read' && values.out !== undefined)
+        return 'machine setup reads files only to standard output';
+    return undefined;
+}

package/dist/machine-setup.d.ts

@@ -4,8 +4,7 @@ import { AgentStateStore } from './agent-state.js';
 import { type Values } from './args.js';
 export type Runner = 'claude' | 'codex' | 'cloud';
 type Env = Record<string, string | undefined>;
-/** Set for the local agent's processes: the `shard` it runs only reaches this machine VM (see `setupGuard`). */
-export declare const SETUP_VM_ENV = "SHARDFLUX_MACHINE_SETUP_VM";
+export { SETUP_VM_ENV, setupGuard } from './machine-setup-guard.js';
 export declare const DEFAULT_AGENT_TIMEOUT_MS: number;
 export interface ChildResult {
     code: number | null;
@@ -71,11 +70,6 @@ export declare const SECRET_PATHS: readonly ["~/.ssh/**", "~/.aws/**", "~/.azure
 export declare function claudeArgs(key: string, help: string): string[];
 /** `codex exec` argv: writes only in `workDir` (and temp folders), network on for `shard`, the task on standard input. */
 export declare function codexArgs(workDir: string, help: string): string[];
-/**
- * While `SHARDFLUX_MACHINE_SETUP_VM` is set (the setup agent's own commands), shard only runs commands on that VM: exec,
- * file writes from standard input, reads and listings. Returns the refusal, or undefined when the command may run.
- */
-export declare function setupGuard(env: Env, command: string, values: Values, positionals: string[]): string | undefined;
 export interface Inventory {
     /** The home whose files were inventoried; a local agent's login shell can use a different home. */
     source_home?: string;
@@ -187,4 +181,3 @@ export declare function machineSetup(ctx: Ctx, values: Values, deps?: SetupDeps)
  */
 export declare function startMachineSetupInBackground(ctx: Ctx): boolean;
 export declare const MACHINE_SETUP_HANDLERS: Record<string, Handler>;
-export {};

package/dist/machine-setup.js

@@ -31,7 +31,8 @@ import { progress as stderrProgress } from "./progress.js";
 import { writeProgress } from "./seed-phases.js";
 import { parseDuration } from "./args.js";
 /** Set for the local agent's processes: the `shard` it runs only reaches this machine VM (see `setupGuard`). */
-export const SETUP_VM_ENV = 'SHARDFLUX_MACHINE_SETUP_VM';
+import { SETUP_VM_ENV } from "./machine-setup-guard.js";
+export { SETUP_VM_ENV, setupGuard } from "./machine-setup-guard.js";
 export const DEFAULT_AGENT_TIMEOUT_MS = 10 * 60_000;
 const SAVE_TIMEOUT_MS = 10 * 60_000;
 /**
@@ -228,27 +229,6 @@ export function codexArgs(workDir, help) {
         '-',
     ];
 }
-/**
- * While `SHARDFLUX_MACHINE_SETUP_VM` is set (the setup agent's own commands), shard only runs commands on that VM: exec,
- * file writes from standard input, reads and listings. Returns the refusal, or undefined when the command may run.
- */
-export function setupGuard(env, command, values, positionals) {
-    const vm = env[SETUP_VM_ENV]?.trim();
-    if (!vm)
-        return undefined;
-    const allowed = ['workspaces exec', 'files write', 'files read', 'files ls', 'files stat', 'version'];
-    if (!allowed.includes(command))
-        return `machine setup runs only shard ws exec, files write and files read on ${vm}`;
-    if (command === 'version')
-        return undefined;
-    if (positionals[0] !== vm)
-        return `machine setup runs commands only on ${vm}`;
-    if (command === 'files write' && values.from !== undefined && values.from !== '-')
-        return 'machine setup writes files only from standard input (--from -)';
-    if (command === 'files read' && values.out !== undefined)
-        return 'machine setup reads files only to standard output';
-    return undefined;
-}
 function setupCapacity(ws) {
     const disk = ws.grants?.disk_gib;
     if (typeof disk !== 'number' || !Number.isFinite(disk) || disk <= 0)

package/dist/main.js

@@ -14,27 +14,17 @@ import { homedir, hostname } from 'node:os';
 import { statSync } from 'node:fs';
 import { SDK_VERSION, Shardflux, ShardfluxAccount, aboutSeconds, isSessionToken } from '@shardflux/sdk';
 import { CLI_VERSION, CENTER_COMMAND, GUIDE_COMMAND, ONBOARDING_COMMAND, PROJECT_COMMAND, parseCommandLine, resolveApiUrl, resolveWake, resolveWakeTimeout } from "./args.js";
-import { commandCenter } from "./command-center.js";
-import { launchProjectCommand } from "./conversation-terminal.js";
-import { runAcp } from "./acp.js";
 import { registerInstalledT3 } from "./t3-provider.js";
-import { refreshForwarderAgent } from "./cli-proxy.js";
-import { runAcpLogin } from "./acp-login.js";
-import { terminalOnboarding } from "./terminal-onboarding.js";
-import { codingAgentShell, setupGuideText } from "./agent-setup.js";
-import { agentSetupGuide } from "./account-commands.js";
-import { tryLinuxDesktop } from "./desktop-linux.js";
+import { codingAgentShell } from "./agent-shell.js";
 import { startLinuxHelper } from "./linux-helper.js";
-import { runDeviceHelper } from "./device-helper.js";
-import { housekeeping, startupHousekeeping } from "./agent-git-commands.js";
+import { housekeepingIfTracked, startupHousekeeping } from "./startup-housekeeping.js";
 import { CredentialStore, configDir } from "./credentials.js";
 import { recordInstall } from "./update.js";
 import { refreshMenubarInBackground, runMenubarRefresh } from "./menubar.js";
 import { NPM_CLIENTS, npmLatestAll, npmRegistry, withRegistryLatest } from "./registry.js";
 import { AuthConfigError, EXIT, ExecutionPendingError, InterruptedError, UsageError, describeError, exitCodeFor, ownHint, redact } from "./errors.js";
 import { errorText, feedbackCommand, json, time } from "./format.js";
-import { HANDLERS } from "./handlers.js";
-import { SETUP_VM_ENV, setupGuard } from "./machine-setup.js";
+import { SETUP_VM_ENV, setupGuard } from "./machine-setup-guard.js";
 import { makeFetch } from "./http.js";
 import { Input } from "./input.js";
 import { TimingRecorder, notices, timingJson, timingText } from "./timing.js";
@@ -726,6 +716,7 @@ export async function run(argv, io, opts = {}) {
     };
     // Bare shard without a terminal (0.17.1+): the setup guide, read from local state only (never waits).
     if (parsed.command === GUIDE_COMMAND) {
+        const { setupGuideText, agentSetupGuide } = await import("./agent-setup.js");
         io.stdout.write(setupGuideText(agentSetupGuide(ctx)));
         return EXIT.ok;
     }
@@ -733,14 +724,24 @@ export async function run(argv, io, opts = {}) {
     const refused = setupGuard(io.env, command, parsed.values, parsed.positionals);
     if (refused)
         return report(new UsageError(refused));
-    const handler = parsed.command.path[0] === 'acp' ? (ctx) => parsed.values.login === true ? runAcpLogin(ctx) : runAcp(ctx) : parsed.command.path[0] === 'device-helper' ? (ctx) => runDeviceHelper(ctx, { service: parsed.values.service === true }) : command === 'menubar refresh' ? runMenubarRefresh : parsed.command === PROJECT_COMMAND ? launchProjectCommand : parsed.command === ONBOARDING_COMMAND ? async (ctx, values) => await tryLinuxDesktop(ctx) ? 0 : terminalOnboarding(ctx, values, { startHelper }) : parsed.command === CENTER_COMMAND ? commandCenter : HANDLERS[parsed.command.path.join(' ')];
+    // Load the selected interactive surface only after help/version and credential parsing. Plain commands do
+    // not need the terminal UI, ACP session machinery, device bridge or onboarding just to start.
+    const handler = parsed.command.path[0] === 'acp'
+        ? async (ctx) => parsed.values.login === true ? (await import("./acp-login.js")).runAcpLogin(ctx) : (await import("./acp.js")).runAcp(ctx)
+        : parsed.command.path[0] === 'device-helper'
+            ? async (ctx) => (await import("./device-helper.js")).runDeviceHelper(ctx, { service: parsed.values.service === true })
+            : command === 'menubar refresh' ? runMenubarRefresh
+                : parsed.command === PROJECT_COMMAND ? (await import("./conversation-terminal.js")).launchProjectCommand
+                    : parsed.command === ONBOARDING_COMMAND ? async (ctx, values) => await (await import("./desktop-linux.js")).tryLinuxDesktop(ctx) ? 0 : (await import("./terminal-onboarding.js")).terminalOnboarding(ctx, values, { startHelper })
+                        : parsed.command === CENTER_COMMAND ? (await import("./command-center.js")).commandCenter
+                            : await (await import("./handler-loader.js")).handlerFor(parsed.command.path.join(' '));
     if (!handler)
         return report(new UsageError(`unknown command "${parsed.command.path.join(' ')}"`));
     // Long-running helpers other programs start (an editor, launchd, the menu bar) skip the per-command housekeeping.
     if (!['acp', 'device-helper'].includes(parsed.command.path[0]) && command !== 'menubar refresh' && command !== 'cli-proxy forward' && !io.env[SETUP_VM_ENV]) {
         // An updated shard restarts this computer's CLIProxyAPI forwarder on itself (a no-op unless the version changed).
-        await refreshForwarderAgent(io.env, ctx.store.dir).catch(() => false);
-        await housekeeping(ctx);
+        await import("./forwarder-refresh.js").then(({ refreshForwarderAgent }) => refreshForwarderAgent(io.env, ctx.store.dir)).catch(() => false);
+        await housekeepingIfTracked(ctx);
         startHelper();
     }
     const running = handler(ctx, parsed.values, parsed.positionals).then((code) => ({ code }), (err) => ({ err }));

package/dist/orchestrator-commands.js

@@ -6,7 +6,7 @@
  * a session) reaches the orchestrator of the member who created that key (person-scope.ts). Text output is one line
  * per input, tab-separated, id first; --json prints the API's objects.
  */
-import { inputSettled, ORCHESTRATOR_TEXT_MAX } from '@shardflux/sdk';
+import { inputSettled } from '@shardflux/sdk';
 import { parseDuration } from "./args.js";
 import { out, str } from "./commands.js";
 import { EXIT, UsageError } from "./errors.js";
@@ -202,8 +202,6 @@ export const ORCHESTRATOR_HANDLERS = {
         const text = words.join(' ');
         if (!text.trim())
             throw new UsageError('missing <words...> for "shard orchestrator say"');
-        if (text.length > ORCHESTRATOR_TEXT_MAX)
-            throw new UsageError(`your words are ${text.length} characters; one input takes up to ${ORCHESTRATOR_TEXT_MAX}`);
         const selection = selectionOf(values);
         const wait = values.wait === true;
         const timeoutMs = str(values.timeout) === undefined ? SAY_WAIT_MS : parseDuration(str(values.timeout), 'timeout');

package/dist/startup-housekeeping.d.ts

@@ -0,0 +1,5 @@
+import type { Ctx } from './commands.js';
+/** Help/version starts also clean saved work, without requiring credentials when nothing is due. */
+export declare function startupHousekeeping(ctx: Pick<Ctx, 'io' | 'store' | 'signal'>): Promise<void>;
+/** Keep the command's already selected auth behavior, loading Git machinery only for tracked repositories. */
+export declare function housekeepingIfTracked(ctx: Pick<Ctx, 'io' | 'apiUrl' | 'signal' | 'store' | 'cloud'>): Promise<void>;

package/dist/startup-housekeeping.js

@@ -0,0 +1,30 @@
+import { Shardflux } from '@shardflux/sdk';
+import { AgentStateStore } from "./agent-state.js";
+import { resolveApiUrl } from "./args.js";
+import { UsageError } from "./errors.js";
+/** Help/version starts also clean saved work, without requiring credentials when nothing is due. */
+export async function startupHousekeeping(ctx) {
+    try {
+        const state = new AgentStateStore(ctx.store.dir).read();
+        if (!state.git_repositories || !Object.keys(state.git_repositories).length)
+            return;
+        const apiUrl = resolveApiUrl(undefined, ctx.io.env.SHARDFLUX_API_URL ?? ctx.io.env.SHARDFLUX_BASE_URL);
+        let cloud;
+        await (await import("./agent-git-commands.js")).housekeeping({ ...ctx, apiUrl, cloud: () => {
+                const key = ctx.io.env.SHARDFLUX_API_KEY?.trim() || ctx.store.profile(apiUrl).api_key?.token;
+                if (!key)
+                    throw new UsageError('saved agents need a project key for housekeeping; run shard setup');
+                return cloud ??= new Shardflux({ apiKey: key, baseUrl: apiUrl, versionCheck: false });
+            } });
+    }
+    catch (error) {
+        ctx.io.stderr.write(`shard housekeeping: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+}
+/** Keep the command's already selected auth behavior, loading Git machinery only for tracked repositories. */
+export async function housekeepingIfTracked(ctx) {
+    const repos = new AgentStateStore(ctx.store.dir).read().git_repositories;
+    if (!repos || !Object.keys(repos).length)
+        return;
+    await (await import("./agent-git-commands.js")).housekeeping(ctx);
+}

package/dist/t3-provider.js

@@ -3,13 +3,15 @@ import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { writePrivateFile } from "./credentials.js";
 import { withTargetLock } from "./target-lock.js";
-import { installedTargets } from "./agent-targets.js";
+import { applicationDirs, t3Apps } from "./agent-targets.js";
 import { t3ArchiveSupportsAcp } from "./t3-asar.js";
 const ID = 'shardflux';
 const provider = { driver: 'acpRegistry', displayName: 'Shardflux', enabled: true, config: { source: 'local', commandPath: 'shard', commandArgs: ['acp'] } };
 /** Every shard invocation registers the one installed T3 provider without adding terminal noise (macOS and Linux). */
 export async function registerInstalledT3(env, dir, signal, platform = process.platform) {
-    if (!installedTargets(env, platform).targets.includes('t3'))
+    // Registration only needs T3 presence; probing other apps or choosing a
+    // preferred T3 version would inspect unrelated bundles on every command.
+    if (!t3Apps(applicationDirs(env, platform), platform, env).length)
         return;
     try {
         await configureT3Provider(env, dir, false, signal);

package/dist/worktree-twin-engine.d.ts

@@ -123,7 +123,7 @@ export declare function runTwinLoop(deps: LoopDeps, signal: AbortSignal): Promis
  * A VM of the project that reads the project hub: an awake one reads it without waking anything; else the project's
  * small space reader (woken). The twin lands from it when a conversation's VM is gone; `shard task land` merges there.
  */
-export declare function projectHubCell(ctx: Ctx, projectId: string, signal?: AbortSignal, agentLabel?: string): Promise<{
+export declare function projectHubCell(ctx: Ctx, projectId: string, signal?: AbortSignal, agentLabel?: string, workspaceIds?: readonly string[]): Promise<{
     cell: TwinCell;
     close(): void;
 }>;

package/dist/worktree-twin-engine.js

@@ -508,14 +508,17 @@ const openCell = (ws, agentLabel) => {
  * A VM of the project that reads the project hub: an awake one reads it without waking anything; else the project's
  * small space reader (woken). The twin lands from it when a conversation's VM is gone; `shard task land` merges there.
  */
-export async function projectHubCell(ctx, projectId, signal, agentLabel = 'shard-twin') {
+export async function projectHubCell(ctx, projectId, signal, agentLabel = 'shard-twin', workspaceIds) {
     const client = conversationClient(ctx);
-    const all = (await listConversations(ctx, projectId)).filter(c => !ended(c))
-        .sort((a, b) => (b.last_activity_at ?? '').localeCompare(a.last_activity_at ?? ''));
-    for (const c of all) {
+    // A manual landing uses its own result's computer. Borrowing an unrelated thread races that person's deletion:
+    // staging 2026-10-17 cut off a real landing when a newer home thread's VM was deleted. If the result's computers
+    // are gone or asleep, the persistent space reader owns the operation instead; do not wake a finished agent.
+    const ids = workspaceIds ?? (await listConversations(ctx, projectId)).filter(c => !ended(c))
+        .sort((a, b) => (b.last_activity_at ?? '').localeCompare(a.last_activity_at ?? '')).map(c => c.workspace_id);
+    for (const id of new Set(ids)) {
         try {
-            const ws = await client.workspaces.get(c.workspace_id);
-            if (!ws.data.deleted_at && ws.ready)
+            const ws = await client.workspaces.get(id);
+            if (ws.data.project_id === projectId && !ws.data.deleted_at && ws.ready)
                 return openCell(ws, agentLabel);
         }
         catch { /* another may be awake */ }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.28.0",
+  "version": "0.28.1",
   "type": "module",
   "description": "shard: the Shardflux command line. Create an account, sign in, set up keys and billing, then open, run commands in, move files to, suspend, resume and fork serverless agent workspaces.",
   "license": "Apache-2.0",
@@ -31,7 +31,12 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
-    "./bin": "./dist/bin.js"
+    "./bin": "./dist/bin.js",
+    "./main": {
+      "types": "./dist/main.d.ts",
+      "import": "./dist/main.js",
+      "default": "./dist/main.js"
+    }
   },
   "files": [
     "dist",
@@ -48,7 +53,7 @@
     "snappyjs": "0.7.0",
     "ws": "8.22.0",
     "yaml": "2.9.1",
-    "@shardflux/sdk": "^0.30.0"
+    "@shardflux/sdk": "^0.30.1"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
@@ -60,10 +65,10 @@
     "typescript-eslint": "8.70.1"
   },
   "optionalDependencies": {
-    "@shardflux/desktop-darwin-arm64": "0.9.1",
-    "@shardflux/desktop-darwin-x64": "0.9.1",
-    "@shardflux/desktop-linux-arm64": "0.9.1",
-    "@shardflux/desktop-linux-x64": "0.9.1"
+    "@shardflux/desktop-darwin-arm64": "0.9.2",
+    "@shardflux/desktop-darwin-x64": "0.9.2",
+    "@shardflux/desktop-linux-arm64": "0.9.2",
+    "@shardflux/desktop-linux-x64": "0.9.2"
   },
   "scripts": {
     "build": "node scripts/build.mjs",