@shardflux/cli 0.15.2 → 0.17.0

package/CHANGELOG.md

@@ -1,17 +1,149 @@
 # Changelog
 
-## 0.15.2
-
-- Updates show up the moment they are published: the latest version comes from npm's `latest` tag (what
-  `npm i -g shardflux` installs), checked at most every 12 hours with its ETag. The API still says which versions it
-  supports, and can hold back a release. Offline, nothing is printed. `shard update --check` and the menu bar's update
-  check use the same versions.
-- The menu bar keeps up with npm by itself: after `npm i -g shardflux`, every `shard` command compares the installed app
-  with the one the package carries (two Info.plist reads, no network) and, when that one is newer, brings it in in the
-  background: a stopped app is replaced on disk, a running one is left to update itself (menu bar 0.3.2+) or, for
-  earlier apps, restarted on the new version when none of its windows is open. `shard update` swaps in an app the
-  package already carries without another install. App versions compare as semver (0.3.10 after 0.3.9).
-- Installs menu bar 0.3.2 (`@shardflux/menubar-darwin ^0.3.2`).
+## 0.17.0 (not yet published)
+
+- Linux (Ubuntu 24.04, x64 and arm64): bare `shard` signs in and connects Claude/Codex in the terminal. The
+  systemd user helper keeps the live twin, files and conversation mirrors running; `shard device requests`,
+  `shard device approve <id>` and `shard device deny <id>` handle local approvals. Desktop launches open a terminal;
+  macOS keeps its extra menu bar app.
+
+- A Codex project opens in T3 Code without a Claude sign-in (T3 shows Claude as signed out, and says how to sign in), and `--json` names the T3 Connect sign-in `shard` started for the phone (`t3_link.sign_in`, or `t3_link.needs_login` when this computer has no session).
+- A conversation settles when its turn ends (`done` or `unresolved` right away) and its VM takes the next message.
+  `shard agents open`, `shard ./ --resume` and ACP reattach to that VM instead of resuming the conversation into a new
+  one, `shard agents computers` and `--on` offer its computer for new threads, Try locally keeps syncing across turns,
+  and the transcript mirror reads it once per change. A conversation has ended once its VM is removed, or it is
+  archived or discarded.
+- The menu bar keeps running and updating your global install: running `shard` from a source checkout, a project's
+  `node_modules` or `npx` no longer replaces the install it records (`SHARDFLUX_RECORD_INSTALL=1` records any run).
+- `--model <model>` and `--effort <level>` on `shard ./` and `shard agents new` (also with `--on` and `--in t3`)
+  (0.17.0+): a new Claude or Codex thread starts with that model and reasoning effort, such as `--model opus --effort
+  xhigh` or `--model gpt-6-astra --effort high`. The conversation keeps them across resumes and moves. `--json` adds
+  `model_choice: {model, effort, applied}`; a computer whose platform predates the choice starts the thread with the
+  agent's defaults and says so once. Unknown values are refused before anything starts.
+- `shard agents targets --json` adds `models` (0.17.0+): for `claude` and `codex`, the `models` (`id`, `label`, `short`,
+  `description`), the `efforts` (`id`, `label`) and the agent's own `default` (`model`, `effort`; `null` where the
+  agent decides at start), so the menu bar and other apps show the same choices without hardcoding them.
+- T3 Code mode: `shard agents new --in t3 --prompt-file <file>` (or `--prompt`) starts the first message as a thread in
+  T3 Code and brings T3 to the front. With T3's Shardflux provider (T3 builds with ACP providers) the thread is launched
+  on the running T3 and gets its own cloud VM; with T3 Code 0.0.45 it starts on the T3 server in the project VM, or with
+  `--on <conversation|computer>` on that computer's. `--image` attaches images to the first message; `--model` and
+  `--effort` take the same choices as every new thread. `--json` returns `{ target: "t3", mode, project, t3_thread_id,
+  conversation_id, workspace, opened: true, focused: false, model, effort }` with the model and effort T3 got. A
+  requested effort that T3 did not get is `effort: null` with `effort_reason`: `not_offered` (the model has no such
+  level) or `models_not_known` (with the Shardflux provider, before this project's first conversation on this computer
+  has shown its levels). Refusals have their own codes: `t3_not_installed`, `t3_not_connected`, `t3_server_unreachable`,
+  `t3_version_unsupported`, `t3_on_not_supported`, `t3_model_unavailable`, `t3_thread_failed`, and `t3_open_failed` for
+  a thread that started while T3 Code did not open; once the workspace, conversation or thread exists their `details`
+  name its `workspace_key`, `conversation_id` and `t3_thread_id`, so a client opens it instead of starting it again.
+- `shard agents targets --json` reports T3 Code (`t3: { installed, mode, connected, version, last_used_at }`) and where
+  each app's new conversations open (`open_in: { claude, codex }`). `--open-in claude=t3,codex=t3` saves the choice
+  (Claude: terminal, claude-desktop, web or t3; Codex: codex-app or t3). Without one, T3 is the default when it is
+  connected (the Shardflux provider registered and this computer signed in; with T3 Code 0.0.45, this project set up
+  as a T3 environment from this computer) and the most recently used of the installed apps. `shard ./` and `--in auto`
+  open new conversations there, a conversation as itself. `--path <folder>` reports them for that project (as
+  `agents new --path` names it); an agent argument wins over it.
+- `shard agents open t3 <conversation>` brings the conversation's T3 thread back (`t3_thread_id`) and, like
+  `agents open t3 <workspace>`, opens T3 with `--json` too (`opened: true`).
+- JSON errors that come with a next step carry it as `error.fix`.
+- T3 Code on your phone: `shard agents new --in t3` and `shard agents open t3` also add the project to the T3 app as **Shardflux · <project>**. The first time, open the link it prints and confirm the code once; every later project appears by itself. A message from the app wakes the VM.
+- `shard cli-proxy import` moves CLIProxyAPI from this computer into your account: one hosted copy holds your Claude, Codex and other subscription logins, sleeps between requests and wakes on the next one. This computer and every new VM reach it at `http://127.0.0.1:8317`, so Claude Code (`ANTHROPIC_BASE_URL`), Codex (`base_url …/v1`) and T3 Code's usage view keep their settings; streaming responses and WebSockets pass through.
+  - The hosted copy is made from your own config: client API keys, routing, retries, model aliases and upstream keys carry over, and your management key keeps working.
+  - Your local CLIProxyAPI stops for good on the port its config names: a Homebrew service with `brew services stop`; after you confirm (`--yes` for scripts), a launchd agent (stopped, disabled, its plist set aside), a Docker container (`docker stop`) or a process. Only a program recognized as CLIProxyAPI is ever stopped; anything else on the port is named with the command to run.
+  - Your auth files move to the hub, and the local copies move to `<auth folder>.moved-to-shardflux` (0700), where no CLIProxyAPI reads them.
+  - Run it on a second computer to connect that one too: it adds only the accounts that are new to the hub, names them, and keeps the hub's settings. Every project of your account uses the same hosted copy. `--config <path>` names the config when it is somewhere else.
+  - VMs receive only the address of the hub's VM port, which serves the model routes (OpenAI, Claude, Gemini and Codex, WebSockets included) and nothing else; the hub's logins and settings are managed from the computers that set it up. A second computer's logins are matched to the hub's by account (provider plus every account, organization, workspace and project id and email the auth file names), whatever the file names, so two accounts of one email both move.
+- `shard cli-proxy export` brings your logins back to this computer: the hosted copy stops first, the logins it last refreshed are written to your auth folder (0600), this computer stops forwarding, and the command that starts your local CLIProxyAPI is shown. `shard cli-proxy import` moves them back.
+- `shard cli-proxy` shows the hosted copy: its accounts (provider and email), whether it is running or sleeping, and where it is reachable, in a VM too. It starts CLIProxyAPI again when the hub answers that nothing listens. `--json` for scripts.
+- Revoking an API key keeps the hub reachable: when its address was created with that key, the next request through this computer, `shard cli-proxy` or an import gives the hub a new address, uses it at once and passes it to every new VM.
+- On macOS the forwarder runs as the launchd agent `dev.shardflux.cli-proxy-forward` (at login, kept running, restarted when `shard` is updated). A request the hub did not receive (while it wakes or CLIProxyAPI starts again) is sent again, POST bodies included up to 32 MiB; a client that disconnects ends its request to the hub.
+- For onboarding: `detectLocalCliProxy()` and `importCliProxy(ctx)` are exported.
+
+- A finished conversation lands in your checkout as soon as its turn ends: the menu bar's helper keeps one wait per
+  active conversation and hears the finished turn the moment the conversation reports it (no polling every second).
+  Conversations that finish together for the same branch land in one go, in the order they finished.
+
+## 0.16.0 (not yet published)
+
+- Cloud sessions are named for the work: `shard ./` starts the agent with the repository or folder name and the first
+  line of your prompt, so claude.ai, the Claude app and its notifications show `Add CSV export · todo-app`
+  (`New conversation · todo-app` until the first prompt arrives) instead of the project slug and conversation id.
+  Claude Desktop and Codex app targets are listed as `main · acme`, without the `[SF] ` tag.
+
+- Updates show up the moment they are published (also in 0.15.2): the latest version comes from npm's `latest` tag
+  (what `npm i -g shardflux` installs), checked at most every 12 hours with its ETag. The API still says which
+  versions it supports, and can hold back a release. Offline, nothing is printed. `shard update --check` and the menu
+  bar's update check use the same versions.
+- The menu bar keeps up with npm by itself (also in 0.15.2): after `npm i -g shardflux`, every `shard` command compares
+  the installed app with the one the package carries (two Info.plist reads, no network) and, when that one is newer,
+  brings it in in the background: a stopped app is replaced on disk, a running one is left to update itself (menu bar
+  0.3.2+) or, for earlier apps, restarted on the new version when none of its windows is open. `shard update` swaps in
+  an app the package already carries without another install. App versions compare as semver (0.3.10 after 0.3.9).
+
+- A new thread on an existing computer: `shard agents new --app claude|codex --on <ref>` and `shard ./ --on <ref>`
+  start Claude or Codex on the computer (VM) of an existing conversation instead of a new one. The thread works on its
+  own branch and worktree there, starting from that conversation's committed `HEAD`, and shares the computer's
+  installed packages, caches, running services, ports and files. `<ref>` is a conversation id, key or name, or the
+  computer's workspace key or id; a parked computer wakes for it. Codex threads are genuine Codex Cloud threads.
+  `--review` starts a read-only Claude reviewer of that conversation's worktree instead. `--prompt`, `--prompt-file`
+  and `--image` work as for a new conversation.
+- `shard agents computers [--path <folder>]` lists the project's computers a thread can start on and the threads on
+  each (`--json`: `{computers: [{workspace_id, workspace_key, state, conversations: [...]}]}`).
+- `shard agents list` shows each session's CONVERSATION and COMPUTER; `--json` rows add `conversation_id` and
+  `conversation_key`. `agents open <conversation> --in auto` opens that conversation's own Claude session when its
+  computer runs several, and the `--json` of a started Claude conversation names its `conversation.id`.
+- A conversation's files folder starts from its own seed, also when several threads share one computer.
+
+- Waits show where a queued start stands: while a command waits on an operation whose start is queued for capacity,
+  one line on stderr gives its place, the host being started for it and until when it holds its place
+  (`queued for capacity (position 3): a new host is starting, ready by 21:40Z; it holds its place until 21:51Z`),
+  again whenever that changes. Dim on a terminal, plain when piped, never with `--json`. A command waiting for room on
+  the workspace's host or for a free working slot of the plan says so the same way.
+
+- **Breaking:** queued starts are seen through: without `--timeout` (or `--wake-timeout`), a wait whose start is queued for capacity
+  keeps waiting until the start's deadline instead of exiting at the default 5 minutes (or 2 minutes for a wake). An
+  explicit `--timeout`, `--wake-timeout` or `SHARDFLUX_WAKE_TIMEOUT_MS` is kept as given; its timeout error (exit 5)
+  names the queue position, and `--json` adds `last_reason`, `deadline_at` and `queue_position`.
+
+- Commands wait for room instead of failing (SDK 0.22.0): a call refused before it ran while the workspace's host makes
+  room (503 `host_capacity`) or while every workspace the plan lets work at once is busy (429 `quota_exceeded`) is sent
+  again after each `Retry-After` for up to 2 minutes, `ws exec` starts and `ws open` included.
+
+- The agent terminal (`shard ./`, `shard agents open --in terminal`) waits `Retry-After` when the workspace's host is
+  making room, says `waiting for room on the workspace's host (position N)` once, and after a drop that follows a
+  working attach reconnects from the shortest backoff again.
+
+- Every conversation's committed files on your Mac: while the menu bar app runs, its device helper keeps
+  `~/Shardflux/<repository>/<base branch>/<conversation>/` in step with what each conversation of your account
+  committed, read-only and without prompts. A folder holds the files that conversation changed or added since it
+  started (`.shardflux-manifest.json` lists them, deletions included); the base branch moving, a rebase, and the
+  uncommitted edits your worktree had when the conversation started are left out. All worktrees of one repository are
+  one `<repository>` folder. Files above 50 MB, and files past 2 GB per conversation, are listed as
+  `<file>.placeholder.txt`; set `max_file_mb` and `max_conversation_mb` in the repository's `.shardflux/files.yaml`.
+  A landed conversation's folder is marked `landed` and stops updating; a discarded one is removed. Your own
+  checkouts are never written.
+
+- `shard files pull <conversation> <path>` downloads one listed file in place of its placeholder, whatever its size.
+
+- New conversations record the working tree they start from (a seed snapshot made in the conversation's VM, never on
+  your Mac) and the base branch they start on.
+
+- Finished conversations land in your local checkout with no input: while the menu bar app runs, a conversation
+  whose turn ends with its work committed lands into the branch it started from. The branch moves to its commits
+  (fast-forward, or its commits replayed onto your newer ones) and the files it changed are written atomically in the
+  worktree where that branch is checked out, three-way merged with your uncommitted edits (your text wins where both
+  changed the same lines). The index follows, so `git status` shows only your own edits. A file is written only after
+  2 seconds without a change, never while your own merge, rebase, cherry-pick or bisect runs, and every rewritten file
+  is backed up first (`shard conversations landing backups`, `restore <backup>`; kept 14 days, up to 1 GiB). When the
+  conversation's commits conflict with your newer commits, its agent is asked in that conversation to merge your
+  branch and resolve; the result lands when it finishes. `shard conversations landing pr` opens a pull request
+  instead; `off` keeps conversations in the cloud. Conversations that finish while your computer is offline or asleep
+  land the moment it is back, one after another in the order they finished, also when their VM has been reclaimed.
+
+- A conversation started from a checkout with uncommitted edits starts from them: its base is a snapshot commit of
+  your working tree (kept as `refs/shard/twin/<id>` in your repository; your index, HEAD and branches are not
+  touched), so its own commits hold only its work and your edits stay yours.
+
+- Includes SDK 0.22.0.
 
 ## 0.15.1
 
@@ -238,7 +370,6 @@
 
 ## 0.12.0 (not yet published)
 
-
 - Add `cpu-service-fresh-inputs-v1` with `fresh_env_names`: fresh owned startup hooks/children consume allowed task values while immutable CPU initialization stays credential-free. Relevant or secret inputs retain ordinary startup.
 
 - Add explicit `pasteText` clipboard replacement with an application paste chord, LF-to-Return typing repair and unchanged screenshot settling.
@@ -246,7 +377,6 @@
 Every command and option the README shows is available from the version named here. Breaking changes ship in minor
 releases and are marked **Breaking**.
 
-
 - Accept caller-supplied exact desktop pixel predicates without an environment gate. Completion uses the same frozen full frame encoded as PNG; pre-satisfied refusal and timeout return no success image. Omitted predicates retain 250 ms settling.
 - Preserve explicit `initialized_cpu` service declarations through template YAML build/export/edit transport, matching SDK0.17.0.
 

package/README.md

@@ -26,7 +26,7 @@ See the [support guide](https://github.com/shardfluxdev/community/blob/main/SUPP
 
 ## Command center (0.15.0+)
 
-Run `shard` in a terminal to see live conversations. Press **Enter** to open the selected one, **/** to search,
+On macOS, run `shard` in a terminal to see live conversations. Press **Enter** to open the selected one, **/** to search,
 **D** to expand or collapse finished conversations, and **?** for targets, logs, fork, park and Git actions.
 Press **n** to start a conversation: describe the task, confirm a local project folder, then choose Claude or Codex.
 Both the task and project are required, and the task becomes the first user-authored message. **Esc** cancels;
@@ -50,6 +50,18 @@ Bulk transfers batch writes automatically. Active transfers retain their byte po
 
 ## Install
 
+Linux (Ubuntu 24.04, x64 and arm64) and macOS are supported. On Linux, run `shard` to sign in and
+connect Claude, Codex or both (0.17.0+), then run `shard ./` in your project to attach Claude Code or Codex in place. Sign-in opens your browser;
+on a headless terminal, follow the displayed URL and device code. `--accept-terms` accepts the terms notice.
+
+The Linux helper starts automatically after setup as `~/.config/systemd/user/shardflux-helper.service`
+and restarts after a CLI update. It keeps the live twin, `~/Shardflux` files and conversation history in sync.
+Use `shard device requests`, `shard device approve <id>` or `shard device deny <id>` for local approvals;
+desktop notifications point to pending requests. On systems without a systemd user session, the helper runs
+while your `shard` commands are open. `shard agents open` opens a terminal when launched outside one, using
+`$TERMINAL`, `x-terminal-emulator` or `gnome-terminal`, or prints the attach command. The Mac app adds a menu
+bar, launcher and Settings window.
+
 ```sh
 npm i -g shardflux
 shard --help
@@ -70,7 +82,7 @@ shard ./
 
 Choose Claude Code or Codex. Claude asks for one cloud sign-in per Shardflux account; Codex uses your copied login.
 Each `shard ./` starts its own conversation VM and opens your agent’s native terminal. Later turns stay in that
-VM; `shard ./ --resume` selects a saved project conversation. Native terminal and ACP sessions receive the conversation tools for their own conversation, so the agent can fork, ask for a review, and report to its parent (0.14.0+). You can open conversations in separate terminals at the same time; each stays in the project's local history. `shard` opens the optional command center. On macOS the menu bar starts automatically the first
+VM; `shard ./ --resume` selects a saved project conversation. Native terminal and ACP sessions receive the conversation tools for their own conversation, so the agent can fork, ask for a review, and report to its parent (0.14.0+). You can open conversations in separate terminals at the same time; each stays in the project's local history. On macOS, `shard` opens the optional command center. On macOS the menu bar starts automatically the first
 time `shard` runs, with launch at login enabled; `shard menubar stop` turns it off. See [Cloud agents](https://docs.shardflux.dev/guides/cloud-agents).
 
 T3 Code uses one **Shardflux** provider; choose a Claude Code or Codex model to start that agent in the cloud.
@@ -80,6 +92,46 @@ settings: T3 runs `shard acp --login` in its own terminal, which creates or sign
 Codex login, or your email) and connects Claude Code and Codex, skipping every step that is already done (0.15.0+).
 With T3 Code 0.0.45, `shard agents new --in t3` adds the project as an SSH environment instead.
 
+Start another thread on a computer that is already set up (0.16.0+): it shares that conversation's installed
+packages, caches, running services, ports and files, and works on its own branch and worktree.
+
+```sh
+shard agents computers                       # the project's computers and the threads on each
+shard ./ --on fix-login                      # Claude (or Codex) joins the computer of conversation fix-login
+shard agents new --app codex --on fix-login --prompt "Load-test the API it is running"
+shard ./ --on fix-login --review             # a read-only Claude reviewer of its worktree
+```
+
+`--on` takes a conversation's id, key or name, or the computer's workspace key or id. A parked computer wakes for
+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.
+
+Choose the model and reasoning effort a new thread starts with (0.17.0+):
+
+```sh
+shard ./ --model opus --effort xhigh          # Claude Opus at extra-high effort
+shard ./ codex --model gpt-6-astra --effort high
+shard agents new --app claude --path ./ --model sonnet --prompt "Tidy the README" --json
+```
+
+Claude takes `fable`, `opus`, `sonnet` or `haiku` and `low`, `medium`, `high`, `xhigh` or `max`; Codex takes
+`gpt-6.1-sol`, `gpt-6-astra` or `gpt-6-luna` and the same levels plus `ultra`. `default`, or leaving the flag out,
+keeps the agent's own choice. The conversation keeps its model and effort when it is resumed or moved, and `--json`
+adds `model_choice: {model, effort, applied}`. `shard agents targets --json` lists the choices as `models`, with menu
+and pill text and the agent's own default, so apps never hardcode them. `--in t3` passes them to T3 Code.
+
+Start a thread in T3 Code from the command line (0.17.0+):
+
+```sh
+shard agents new --path . --app claude --in t3 --prompt-file task.md
+shard agents targets --open-in claude=t3,codex=t3   # shard ./ starts new conversations in T3 Code
+```
+
+The first message becomes a T3 thread and T3 comes to the front. With the Shardflux provider the thread runs in its own
+cloud VM; with T3 Code 0.0.45 it runs on the T3 server in the project's VM, or with `--on` on that computer's.
+`--image` attaches images. `shard agents targets --json` shows T3 Code's mode and where each app's new conversations
+open; `shard agents open t3 <conversation>` brings its thread back.
+
 Git fetch and push use the coding guest’s platform transport when available, preserving Git’s binary packets (0.14.0+). Older guests retain their existing transport.
 
 To try a conversation on your Mac:
@@ -90,10 +142,30 @@ 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 Mac before preparing the conversation’s local worktree. With CLI 0.15.0 and menu bar 0.3.0, Review shows the exact command, file direction, paths or port mapping; access outside the conversation folder only offers Allow once. Live transcripts stay in
+Device tools ask for approval on your computer before preparing the conversation’s local worktree. With CLI 0.15.0 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
 `~/.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.
 
+Every conversation's committed files are on your computer too (with the helper running; macOS 0.16.0+, Linux 0.17.0+):
+`~/Shardflux/<repository>/<base branch>/<conversation>/` holds what each conversation changed or added, read-only,
+and updates when its branch moves. Large files are listed as `<file>.placeholder.txt`; download one with the menu
+bar's **Download** or:
+
+```sh
+shard files pull hype-video out/hype.mp4
+```
+
+Finished conversations land in your checkout by themselves (0.16.0+, with the menu bar app running). When a
+conversation's turn ends with its work committed, the branch it started from moves to its commits and the changed
+files are written in place, next to your own uncommitted edits, which stay as they are (where both touched the same
+lines, your text is kept). `git status` keeps showing only your edits. A conversation started from a checkout with
+uncommitted edits starts from them too. Every rewritten file is backed up first:
+
+```sh
+shard conversations landing            # auto (default), pr or off for this project
+shard conversations landing backups    # then: shard conversations landing restore <backup>
+```
+
 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.
 
@@ -692,7 +764,11 @@ without waking it (the state at suspension); `files search` then notes it on std
 - `--wake-timeout <ms>` (or `SHARDFLUX_WAKE_TIMEOUT_MS`, default `120000`) bounds the wait. Past
   it, `shard` exits 5 and names the operation and its state (for example `Operation <id> (open)
   is still queued after 120000 ms`). The operation continues server side:
-  `shard operations wait <id>` keeps waiting.
+  `shard operations wait <id>` keeps waiting. Without either (0.16.0+), a resume queued for capacity is waited for
+  until its deadline, its place shown on stderr (see [Start deadlines](#start-deadlines)).
+- A call refused while the workspace's host makes room to wake it (503 `host_capacity`) or while every workspace the
+  plan lets work at once is busy (429 `quota_exceeded`) did not run: `shard` sends it again after each `Retry-After`,
+  for up to 2 minutes (0.16.0+), and stderr says `waiting for room on the workspace's host (position 2)` once.
 - A resume or open that fails exits 6.
 - `--no-wake` (or `SHARDFLUX_NO_WAKE=1`) turns this off. A workspace that is not running is then
   refused at once (exit 1, `workspace_not_running`).
@@ -875,7 +951,16 @@ that screenshot, default 250) and `--format jpeg --quality N` for smaller images
 ## Start deadlines
 
 A queued open, resume or fork (`capacity_pending`) has a deadline 15 minutes after it was created.
-If `--timeout` ends first, the timeout error names the deadline. A start still pending at the
+While `shard` waits for it, stderr says where it stands (0.16.0+), again whenever that changes (dim on a terminal,
+never with `--json`):
+
+```text
+queued for capacity (position 3): a new host is starting, ready by 21:40Z; it holds its place until 21:51Z
+```
+
+Without `--timeout`, a queued start is waited for until its deadline (0.16.0+). An explicit `--timeout` is kept: if it
+ends first, `shard` exits 5 and the timeout error names the deadline and the queue position (`--json`:
+`deadline_at`, `queue_position`, `last_reason`). A start still pending at the
 deadline fails with `capacity_unavailable`: nothing was started, and a suspended workspace stays
 suspended. `shard` exits 6 as for any failed operation, and the error says `retryable=true` (with
 `--json`, `"retryable": true`) with a hint to retry:
@@ -1047,7 +1132,7 @@ printf %s "$NEW_KEY" | shard secrets rotate OPENAI_API_KEY
 | 2 | usage error: bad arguments, or input the API rejected as `validation_failed` |
 | 3 | not found: workspace, operation or route |
 | 4 | authentication or authorization: missing, malformed, revoked or insufficient key or session; `step_up_required` (run `shard auth step-up`), `mfa_required` (a sign-in waiting for its code), `email_unverified`, `invalid_credentials`; `access_denied` or `expired_token` from `auth login --browser` (0.15.0+) |
-| 5 | timeout: waiting gave up (`--timeout`, or `--wake-timeout` while waking a workspace); the operation continues server side (`shard operations wait <id>`), up to a queued start's 15-minute deadline. `executions get` (0.5.0+): the execution is still queued or running. `ws exec-read` (0.8.0+): the background command still runs. `billing upgrade --wait` (0.5.0+): nobody paid in time (the checkout stays open) |
+| 5 | timeout: waiting gave up (`--timeout`, or `--wake-timeout` while waking a workspace); the operation continues server side (`shard operations wait <id>`), up to a queued start's deadline (`deadline_at`). Without `--timeout`, a wait on a start queued for capacity lasts until that deadline (0.16.0+). `executions get` (0.5.0+): the execution is still queued or running. `ws exec-read` (0.8.0+): the background command still runs. `billing upgrade --wait` (0.5.0+): nobody paid in time (the checkout stays open) |
 | 6 | the awaited operation ended `failed` or `canceled` (also a resume or open that failed while waking a workspace). `retryable=true` in the error means a retry can succeed (`capacity_unavailable`). Also a file-first execution that ended `failed` or `lost` (0.5.0+): nothing was published. `exec` (0.5.1+): the command could not start (`exec_failed_to_start`). `billing upgrade --wait` (0.5.0+): the checkout expired or was canceled (`checkout_ended`) |
 | 130 | interrupted (Ctrl-C). Waits stop at once, and exec sends a cancel to the session. A file-first execution runs to completion, and the error names the `shard executions get` command for its result. |
 | exec, executions get, ws exec-read | the command's own code: 124 if it timed out, 128+N if killed by signal N. Failures before the command ran use the codes above; use `--json` to tell them apart. |
@@ -1205,7 +1290,7 @@ connection it configured and the file it is in (0.13.3+).
 
 `shard agents fork` or `f` in the command center copies the whole running state into an independent workspace and
 conversation. Open in your terminal, Claude Desktop or the Codex app, and the terminal Claude conversation in
-claude.ai or mobile. Session titles start with `[SF] `. Waiting agents stay reachable on their own connections;
+claude.ai or mobile. Sessions are titled with their task and repository, like `Add CSV export · todo-app`. Waiting agents stay reachable on their own connections;
 see the [settings and billing reference](https://docs.shardflux.dev/limits#cloud-agent-reachability).
 Claude needs one cloud sign-in per account; Codex uses your copied login.
 

package/dist/acp-models.js

@@ -7,6 +7,8 @@ import { createConversationRecord, conversationWorkspace } from "./conversations
 import { AgentStateStore } from "./agent-state.js";
 import { objectValue } from "./acp-rpc.js";
 import { nativeCurrentModel, nativeModelOptions } from "./acp-catalog.js";
+import { recordSeedSnapshot } from "./files-mirror.js";
+import { sendTwinSeed, twinCheckoutArgv } from "./worktree-twin.js";
 /** No prompts, login, logout or credential writes. Every child process group is
  * terminated, including initialization failures and interrupted clients. */
 export const ACP_MODELS_SCRIPT = String.raw `
@@ -143,9 +145,11 @@ export const ACP_LIFECYCLE = { async prepare(ctx, folder, name, callbacks) {
         const seeded = (async () => {
             await seedAgentRepository(ctx, ws, folder, { root: c.worktree_path, populate: true,
                 initialFiles: ['.claude/settings.json', '.claude/settings.local.json', '.codex/config.toml', '.mcp.json'], onInitialFiles: initialReady });
-            const result = await ws.cell().exec.run(['git', '-C', c.worktree_path, 'checkout', '-B', c.branch, c.base_commit], { timeoutMs: 30_000, signal: ctx.signal });
+            await sendTwinSeed(ctx.store.dir, ws.cell(), c, folder, ctx.signal);
+            const result = await ws.cell().exec.run(twinCheckoutArgv(ctx.store.dir, c), { timeoutMs: 30_000, signal: ctx.signal });
             if (result.exitCode !== 0)
                 throw new Error(`Conversation branch could not be prepared: ${result.stderr.trim()}`);
+            await recordSeedSnapshot(ws, c, ctx.signal);
             callbacks.prepared();
         })();
         void seeded.catch(initialFailed);

package/dist/agent-commands.d.ts

@@ -1,16 +1,30 @@
 import type { CellClient, PtySession, Workspace } from '@shardflux/sdk';
 import type { Ctx, Handler } from './commands.js';
 import type { Values } from './args.js';
+import type { T3Install, T3ThreadRequest } from './t3-mode.js';
+import type { ModelChoice } from './agent-models.js';
 /** `<slug>-<6 hex of sha256(identity)>`: the same repository gets the same key on every machine. */
 export declare function disambiguatedSlug(slug: string, identity: string): string;
 export declare function projectTemplate(ctx: Ctx, remote: string | null): Promise<string>;
-export declare function agentPty(cell: CellClient, app: 'claude' | 'codex', agent: string, approvals: boolean, term: string, signal?: AbortSignal, project?: string, setupHash?: string, cwd?: string, ptyName?: string, onLaunch?: () => void, deferSetup?: boolean, conversation?: {
+/** `place` is the repository or folder name session titles end with ("todo-app"), `task` what a new session is titled
+ * with before the guest names it from its first prompt (a first prompt line or the conversation's title). */
+export declare function agentPty(cell: CellClient, app: 'claude' | 'codex', agent: string, approvals: boolean, term: string, signal?: AbortSignal, place?: string, setupHash?: string, cwd?: string, ptyName?: string, onLaunch?: () => void, deferSetup?: boolean, conversation?: {
     id: string;
     session: string | null;
+}, task?: string, launch?: {
+    choice?: ModelChoice;
+    help?: () => Promise<string>;
 }): Promise<PtySession>;
+/** The first non-empty line of a prompt or title, bounded; the guest makes it the task part of the session title. */
+export declare function sessionTask(text: string | undefined): string | undefined;
 export declare function terminal(ctx: Ctx, ws: Workspace, app: 'claude' | 'codex', agent: string, project: string, values: Values, setupHash?: string, cwd?: string, conversation?: {
     id: string;
     session: string | null;
+    pty?: string;
+    title?: string;
+    choice?: ModelChoice;
 }): Promise<number>;
 export declare const launchProject: Handler;
+/** The project VM launch; with `--in t3` a first message becomes a thread on the T3 server in it (SSH mode, 0.17.0+). */
+export declare function launchProjectWith(ctx: Ctx, values: Values, [path, explicitApp]: string[], thread?: T3ThreadRequest, install?: T3Install): Promise<number>;
 export declare const AGENT_HANDLERS: Record<string, Handler>;