@shardflux/cli 0.15.2 → 0.16.0

package/CHANGELOG.md

@@ -1,17 +1,87 @@
 # 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.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
 

package/README.md

@@ -80,6 +80,20 @@ 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.
+
 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:
@@ -94,6 +108,26 @@ Device tools ask for approval on your Mac before preparing the conversation’s
 `~/.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 Mac too (0.16.0+, with the menu bar app running):
+`~/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 +726,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 +913,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 +1094,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. |

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

@@ -4,13 +4,19 @@ import type { Values } from './args.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;
-}): Promise<PtySession>;
+}, task?: 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;
 }): Promise<number>;
 export declare const launchProject: Handler;
 export declare const AGENT_HANDLERS: Record<string, Handler>;

package/dist/agent-commands.js

@@ -1,3 +1,4 @@
+import { repositoryName } from "./files-mirror.js";
 import { prepareSetupCache } from "./setup-cache.js";
 import { launchCodexCloud, openCodexConversation } from "./codex-cloud.js";
 import { agentReachability } from "./agent-reachability.js";
@@ -47,7 +48,9 @@ export async function projectTemplate(ctx, remote) {
         throw error;
     }
 }
-export async function agentPty(cell, app, agent, approvals, term, signal, project, setupHash, cwd, ptyName, onLaunch, deferSetup = false, 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 async function agentPty(cell, app, agent, approvals, term, signal, place, setupHash, cwd, ptyName, onLaunch, deferSetup = false, conversation, task) {
     const id = `shard-${ptyName || agent}-${app}`;
     // Arrival and changed locks queue the same durable guest job even when the
     // native agent is already alive. Setup never becomes its first user turn.
@@ -73,7 +76,7 @@ export async function agentPty(cell, app, agent, approvals, term, signal, projec
             conversationArgs = ['--conversation', conversation.id, ...(conversation.session ? ['--resume-session', conversation.session] : [])];
     }
     const launch = await cell.exec.run(['sf-agent', 'run', app, '--name', agent, '--detach', ...conversationArgs, ...(ptyName ? ['--pty-name', ptyName] : []), ...(approvals ? ['--approvals'] : []), ...(setupHash ? ['--setup', '--setup-deps-hash', setupHash] : [])], {
-        env: { TERM: term, ...(project ? { SF_PROJECT_NAME: project } : {}), ...(setupHash && deferSetup ? { SF_SETUP_DEFERRED: '1' } : {}) }, timeoutMs: 30_000, maxOutputBytes: 4096, signal, ...(cwd ? { cwd } : {}),
+        env: { TERM: term, ...(place ? { SF_PROJECT_NAME: place, SF_REPO_NAME: place } : {}), ...(task ? { SF_TASK_TITLE: task } : {}), ...(setupHash && deferSetup ? { SF_SETUP_DEFERRED: '1' } : {}) }, timeoutMs: 30_000, maxOutputBytes: 4096, signal, ...(cwd ? { cwd } : {}),
     });
     if (launch.exitCode !== 0)
         throw new Error(`agent launch failed: ${launch.stderr.trim() || `exit ${launch.exitCode}`}`);
@@ -91,7 +94,13 @@ export async function agentPty(cell, app, agent, approvals, term, signal, projec
         throw new Error(`agent exited before attach: ${session.state}`);
     return session;
 }
+/** The first non-empty line of a prompt or title, bounded; the guest makes it the task part of the session title. */
+export function sessionTask(text) {
+    const line = text?.split(/\r?\n/).map(l => l.replace(/[\s\p{Cc}]+/gu, ' ').trim()).find(Boolean);
+    return line ? [...line].slice(0, 200).join('') : undefined;
+}
 export async function terminal(ctx, ws, app, agent, project, values, setupHash, cwd = workspaceRepositoryPath(ws), conversation) {
+    const ptyName = conversation?.pty ?? ws.labels.agent_pty_name;
     const store = new AgentStateStore(ctx.store.dir);
     if (!ws.ready)
         await ws.wake({ timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
@@ -101,12 +110,12 @@ export async function terminal(ctx, ws, app, agent, project, values, setupHash,
     const tunnels = attach ? await startAgentConfigTunnels(ctx, ws) : null;
     try {
         if (app === 'codex' && typeof values.initialPrompt === 'string') {
-            await prepareInitialCodexProject(cell, cwd, `shard-${ws.labels.agent_pty_name || agent}-${app}`);
+            await prepareInitialCodexProject(cell, cwd, `shard-${ptyName || agent}-${app}`);
         }
         const credentialFill = await configureCredentialFill(ctx, ws);
         // A cold launch is remembered before it starts, so the listing can show it before the projection does (agent-live.ts).
         const term = ctx.io.env.TERM && ctx.io.env.TERM !== 'dumb' ? ctx.io.env.TERM : 'xterm-256color';
-        const session = await agentPty(cell, app, agent, values.approvals === true, term, ctx.signal, ws.labels.shard_project || ws.key.split('/')[0], setupHash, cwd, ws.labels.agent_pty_name, () => { rememberLaunch(ctx, ws.id); progress(ctx, `Starting ${app === 'claude' ? 'Claude' : 'Codex'} in ${ws.key}…`); }, true, conversation);
+        const session = await agentPty(cell, app, agent, values.approvals === true, term, ctx.signal, repositoryName(ws.labels.repo_remote || project), setupHash, cwd, ptyName, () => { rememberLaunch(ctx, ws.id); progress(ctx, `Starting ${app === 'claude' ? 'Claude' : 'Codex'} in ${ws.key}…`); }, true, conversation && { id: conversation.id, session: conversation.session }, sessionTask(typeof values.initialPrompt === 'string' ? values.initialPrompt : conversation?.title));
         // A new conversation's guest can start the agent before this command reaches it, so the launch above never ran.
         // Remember it either way: listing and `agents open` then read the guest until the projection lists the session.
         rememberLaunch(ctx, ws.id);
@@ -126,7 +135,8 @@ export async function terminal(ctx, ws, app, agent, project, values, setupHash,
         }
         if (!attach) {
             await preparation;
-            ctx.io.stdout.write(json({ workspace: ws.data, session, ...(typeof values.initialPrompt === 'string' ? { initial_prompt: { submitted: true } } : {}) }));
+            // conversation (0.16.0+): which conversation this session is, also when its computer hosts several threads.
+            ctx.io.stdout.write(json({ workspace: ws.data, session, ...(conversation ? { conversation: { id: conversation.id } } : {}), ...(typeof values.initialPrompt === 'string' ? { initial_prompt: { submitted: true } } : {}) }));
             return 0;
         }
         ctx.io.stderr.write(`Shardflux · ${ws.key}\nDetach: Ctrl-] then d\n`);
@@ -258,10 +268,11 @@ export const AGENT_HANDLERS = {
         }
         if (values.in === 'auto') {
             // The menu and other launchers use the same CLI-owned target selection. Never put provider URLs in a client.
-            const ws = await resolveWorkspace(ctx, agent);
+            // A conversation id opens that conversation's own session, also when its computer hosts other threads.
+            const ws = resolvedConversation ? await conversationWorkspace(ctx, resolvedConversation) : await resolveWorkspace(ctx, agent);
             const project = ws.labels.repo_remote || ws.labels.shard_project || ws.key;
             const store = new AgentStateStore(ctx.store.dir);
-            const app = values.app ?? ws.labels.shard_app ?? ws.labels.app ?? store.app(project);
+            const app = values.app ?? resolvedConversation?.harness ?? ws.labels.shard_app ?? ws.labels.app ?? store.app(project);
             const detected = installedTargets(ctx.io.env);
             const saved = store.read().projects?.[project]?.target ??
                 (project.startsWith('file://') ? store.read().projects?.[new URL(project).pathname]?.target : undefined);
@@ -270,7 +281,7 @@ export const AGENT_HANDLERS = {
             if ((!saved || !detected.targets.includes(saved)) && app === 'codex') {
                 const next = { ...values };
                 delete next.in;
-                return AGENT_HANDLERS['agents open'](ctx, next, [ws.key]);
+                return AGENT_HANDLERS['agents open'](ctx, next, [resolvedConversation?.id ?? ws.key]);
             }
             if (saved && detected.targets.includes(saved)) {
                 const { HANDLERS } = await import("./handlers.js");
@@ -282,16 +293,17 @@ export const AGENT_HANDLERS = {
             // Claude opens where people work (0.15.1+): the conversation in Claude Desktop when it is installed, else Claude
             // Code in a terminal. The browser (claude.ai) only when it is the chosen target (--in web).
             if (detected.clients.includes('claude-desktop')) {
-                return openClaudeDesktopSession(ctx, ws);
+                return openClaudeDesktopSession(ctx, ws, resolvedConversation);
             }
+            const opened = resolvedConversation?.id ?? ws.key;
             if (ctx.json) {
                 // An app runs this in the person's terminal (the menu bar opens Terminal with it).
-                out(ctx, `shard agents open ${ws.key}\n`, { target: 'terminal', workspace: ws.data, command: ['shard', 'agents', 'open', ws.key] });
+                out(ctx, `shard agents open ${opened}\n`, { target: 'terminal', workspace: ws.data, command: ['shard', 'agents', 'open', opened] });
                 return 0;
             }
             const next = { ...values };
             delete next.in;
-            return AGENT_HANDLERS['agents open'](ctx, next, [ws.key]);
+            return AGENT_HANDLERS['agents open'](ctx, next, [opened]);
         }
         if (values.in !== undefined && values.in !== 'terminal') {
             const { HANDLERS } = await import("./handlers.js");

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

@@ -1,5 +1,6 @@
 import { Duplex } from 'node:stream';
 import type { CellClient, Workspace } from '@shardflux/sdk';
+import type { Conversation } from './conversations.js';
 import type { Ctx, Handler, Io } from './commands.js';
 import { AgentTargets } from './agent-targets.js';
 import type { DesktopTarget } from './agent-targets.js';
@@ -13,7 +14,11 @@ export declare function proxyStream(io: Io, ended?: () => void, outputGate?: Pro
  * this computer just started can accept its first prompt before Remote Control registers, so an open of our recent
  * launch probes the guest for up to 30 s; history browsing stays passive.
  */
-export declare function remoteControlUrl(ctx: Ctx, ws: Workspace): Promise<string>;
+/**
+ * The Claude Remote Control URL of a session in `ws`. With several threads on one computer (0.16.0+) a conversation's
+ * own session is chosen by its harness session id; a thread that has not reported one yet is unambiguous only alone.
+ */
+export declare function remoteControlUrl(ctx: Ctx, ws: Workspace, conversation?: Pick<Conversation, 'harness_session_id'>): Promise<string>;
 /** Claude Desktop's own link to a Remote Control session: claude://code/<session id> opens it in its Code tab. */
 export declare function claudeDesktopLink(remoteControl: string): string;
 export declare const CLAUDE_DESKTOP_BUNDLE = "com.anthropic.claudefordesktop";
@@ -21,7 +26,7 @@ export declare const CLAUDE_DESKTOP_BUNDLE = "com.anthropic.claudefordesktop";
  * Opens the conversation itself (its live Remote Control session) in Claude Desktop (0.15.1+), the way `--in auto`
  * opens a Claude conversation when Claude Desktop is installed. --json prints {target, url, app_bundle_id} for apps.
  */
-export declare function openClaudeDesktopSession(ctx: Ctx, ws: Workspace): Promise<number>;
+export declare function openClaudeDesktopSession(ctx: Ctx, ws: Workspace, conversation?: Pick<Conversation, 'harness_session_id'>): Promise<number>;
 export declare function openDesktopWorkspace(ctx: Ctx, ws: Workspace, target: DesktopTarget, t3Version?: string, prewarmed?: boolean): Promise<number>;
 export declare function queueT3Prewarm(ctx: Ctx, ws: Workspace, version: string): Promise<void>;
 export declare const TARGET_HANDLERS: Record<string, Handler>;

package/dist/agent-target-commands.js

@@ -6,7 +6,7 @@ import { spawn } from 'node:child_process';
 import { Readable, Duplex } from 'node:stream';
 import { ShardfluxApiError, WorkspaceTunnels } from '@shardflux/sdk';
 import { out, resolveWorkspace } from "./commands.js";
-import { AgentTargets, installedTargets } from "./agent-targets.js";
+import { AgentTargets, installedTargets, targetLabel } from "./agent-targets.js";
 import { join, relative } from 'node:path';
 import { projectIdentity } from "./project-identity.js";
 import { projectWorkspacePath } from "./agent-repository.js";
@@ -137,12 +137,18 @@ export function proxyStream(io, ended, outputGate) {
  * this computer just started can accept its first prompt before Remote Control registers, so an open of our recent
  * launch probes the guest for up to 30 s; history browsing stays passive.
  */
-export async function remoteControlUrl(ctx, ws) {
+/**
+ * The Claude Remote Control URL of a session in `ws`. With several threads on one computer (0.16.0+) a conversation's
+ * own session is chosen by its harness session id; a thread that has not reported one yet is unambiguous only alone.
+ */
+export async function remoteControlUrl(ctx, ws, conversation) {
     let cursor;
     let url;
+    const session = conversation?.harness_session_id ?? undefined;
+    const mine = (id) => session === undefined || id === session;
     do {
         const page = await ctx.cloud().agents.list({ limit: 200, ...(cursor ? { cursor } : {}) });
-        url = page.data.find(a => a.workspace_id === ws.id && a.app === 'claude' && a.state !== 'exited' && a.remote_control_url)?.remote_control_url;
+        url = page.data.find(a => a.workspace_id === ws.id && a.app === 'claude' && a.state !== 'exited' && a.remote_control_url && mine(a.id.slice(a.workspace_id.length + 1)))?.remote_control_url;
         cursor = page.nextCursor ?? undefined;
     } while (!url && cursor && !ctx.signal.aborted);
     // A new Claude process can accept its first prompt before Remote Control registers.
@@ -158,7 +164,7 @@ export async function remoteControlUrl(ctx, ws) {
             });
             if (result.exitCode !== 0)
                 break;
-            url = guestSessions(result.stdout).find(a => a.app === 'claude' && a.state !== 'exited' && a.remote_control_url)?.remote_control_url;
+            url = guestSessions(result.stdout).find(a => a.app === 'claude' && a.state !== 'exited' && a.remote_control_url && mine(a.session_id))?.remote_control_url;
             if (!url && Date.now() < deadline)
                 await delay(Math.min(250, Math.max(1, deadline - Date.now())), undefined, { signal: ctx.signal });
         }
@@ -184,9 +190,9 @@ export const CLAUDE_DESKTOP_BUNDLE = 'com.anthropic.claudefordesktop';
  * Opens the conversation itself (its live Remote Control session) in Claude Desktop (0.15.1+), the way `--in auto`
  * opens a Claude conversation when Claude Desktop is installed. --json prints {target, url, app_bundle_id} for apps.
  */
-export async function openClaudeDesktopSession(ctx, ws) {
+export async function openClaudeDesktopSession(ctx, ws, conversation) {
     await ensureCloudClaude(ctx, ws);
-    const session = await remoteControlUrl(ctx, ws);
+    const session = await remoteControlUrl(ctx, ws, conversation);
     const url = claudeDesktopLink(session);
     if (!ctx.json)
         await openLink(url, ctx.io.env);
@@ -251,7 +257,6 @@ export async function queueT3Prewarm(ctx, ws, version) {
     }
 }
 const tilde = (targets, file) => file.startsWith(`${targets.home}/`) ? `~/${relative(targets.home, file)}` : file;
-const targetLabel = (e) => e.agent === 'router' ? `Shardflux · ${e.project}` : `[SF] ${e.project} · ${e.agent}`;
 /** Where each managed connection of an entry lives: the SSH host block (and its Include), then each desktop app's file. */
 function configuredTargets(targets, e, t3 = false) {
     return [

package/dist/agent-targets.d.ts

@@ -7,6 +7,9 @@ export interface TargetEntry {
     agent: string;
     targets: DesktopTarget[];
 }
+/** What Claude Desktop and the Codex app list a target as: the project's router "Shardflux · <project>", an agent
+ * "<agent> · <project>" (the thing, then the place, as session titles are; no tag). */
+export declare const targetLabel: (e: Pick<TargetEntry, "agent" | "project">) => string;
 export declare function targetIdentity(key: string): Pick<TargetEntry, 'host' | 'workspace' | 'project' | 'agent'>;
 /** Replace only a marked block, retaining every byte outside it. Put Includes before user Host blocks. */
 export declare function managedBlock(text: string, body: string): string;

package/dist/agent-targets.js

@@ -15,6 +15,9 @@ const shellQuote = (s) => "'" + s.replaceAll("'", "'\\''").replaceAll('%', '%%')
 const quote = (s) => '"' + s.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('%', '%%') + '"';
 // Some SSH config readers (T3 Code's host discovery) split Include on whitespace and keep quotes; quote only when needed.
 const includePath = (s) => /^[^\s"'\\#%]+$/.test(s) ? s : quote(s);
+/** What Claude Desktop and the Codex app list a target as: the project's router "Shardflux · <project>", an agent
+ * "<agent> · <project>" (the thing, then the place, as session titles are; no tag). */
+export const targetLabel = (e) => e.agent === 'router' ? `Shardflux · ${e.project}` : `${e.agent} · ${e.project}`;
 export function targetIdentity(key) {
     const parts = key.split('/');
     if (parts.length !== 2 || parts.some(p => !/^[a-z0-9][a-z0-9._-]{0,95}$/.test(p)))
@@ -280,7 +283,7 @@ export class AgentTargets {
             if (!(prop in doc) && !manifest.created[file].includes(prop))
                 manifest.created[file].push(prop);
             doc[prop] = [...kept, ...entries.filter(e => e.targets.includes(target)).map(e => {
-                    const label = e.agent === 'router' ? `Shardflux · ${e.project}` : `[SF] ${e.project} · ${e.agent}`;
+                    const label = targetLabel(e);
                     return target === 'claude-desktop' ? { id: e.host, name: label, sshHost: e.host, startDirectory: projectWorkspacePath({ slug: e.project }) } : { sshAlias: e.host, projects: [{ remotePath: projectWorkspacePath({ slug: e.project }), label }] };
                 })];
             if (!doc[prop].length && manifest.created[file].includes(prop))

package/dist/agent-terminal.d.ts

@@ -8,6 +8,14 @@ export interface TerminalConnection {
 }
 /** The workspace (or the VM under this terminal) is asleep: the user's next keystroke wakes it. */
 export declare function sleepingAttach(error: unknown): boolean;
+/**
+ * The wait before the next attach (0.16.0+): an attach refused with a Retry-After (503 `host_capacity` while the
+ * workspace's host makes room, 429 `quota_exceeded`) waits it with up to 20 % jitter; others back off from 100 ms to
+ * 2 s by consecutive failures, which reset once an attach delivers.
+ */
+export declare function reattachDelayMs(error: unknown, failures: number, random?: () => number): number;
+/** The line an attach that waits for room prints (0.16.0+), or null for any other refusal. */
+export declare function admissionNotice(error: unknown): string | null;
 export declare function retryableAttach(error: unknown): boolean;
 /** Offsets address bytes, including escape sequences and UTF-8 split across frames. */
 export declare class PtyOutputCursor {

package/dist/agent-terminal.js

@@ -1,11 +1,29 @@
 import { StringDecoder } from 'node:string_decoder';
-import { PtyConnection, ShardfluxApiError, ShardfluxProtocolError, exitCodePosix } from '@shardflux/sdk';
+import { PtyConnection, ShardfluxApiError, ShardfluxProtocolError, exitCodePosix, isAdmissionRefusal } from '@shardflux/sdk';
 import { UsageError } from "./errors.js";
 /** The workspace (or the VM under this terminal) is asleep: the user's next keystroke wakes it. */
 export function sleepingAttach(error) {
     return error instanceof ShardfluxApiError && error.code === 'workspace_not_running';
 }
 const ASLEEP_NOTICE = '\r\n\x1b[2m· asleep. Type to wake it.\x1b[0m\r\n';
+/**
+ * The wait before the next attach (0.16.0+): an attach refused with a Retry-After (503 `host_capacity` while the
+ * workspace's host makes room, 429 `quota_exceeded`) waits it with up to 20 % jitter; others back off from 100 ms to
+ * 2 s by consecutive failures, which reset once an attach delivers.
+ */
+export function reattachDelayMs(error, failures, random = Math.random) {
+    const hinted = error instanceof ShardfluxApiError ? error.retryAfterSeconds : undefined;
+    if (hinted !== undefined && hinted > 0)
+        return Math.floor(hinted * 1000 * (1 + 0.2 * random()));
+    return Math.min(2_000, 100 * 2 ** Math.min(failures, 5));
+}
+/** The line an attach that waits for room prints (0.16.0+), or null for any other refusal. */
+export function admissionNotice(error) {
+    if (!isAdmissionRefusal(error))
+        return null;
+    const position = typeof error.details?.queue_position === 'number' ? ` (position ${error.details.queue_position})` : '';
+    return error.reason === 'host_capacity' ? `waiting for room on the workspace's host${position}` : 'waiting for a free working slot: every workspace the plan lets work at once is busy';
+}
 export function retryableAttach(error) {
     if (error instanceof ShardfluxProtocolError && /invalid|byte gap|omitted/.test(error.message))
         return false;
@@ -164,6 +182,10 @@ export async function attachTerminal(options) {
         controller.abort();
     } });
     let reconnects = 0;
+    // Consecutive failed attaches: the backoff's exponent, back to 0 once an attach delivers a message.
+    let failures = 0;
+    let lastError;
+    let notice = null;
     let asleep = false;
     try {
         while (!signal.aborted) {
@@ -193,6 +215,9 @@ export async function attachTerminal(options) {
                 for await (const message of connection.messages()) {
                     if (signal.aborted)
                         break;
+                    // The attach delivers: a later drop starts the backoff over, and the next wait for room is said again.
+                    failures = 0;
+                    notice = null;
                     const bytes = cursor.consume(message);
                     if (bytes?.length)
                         io.stdout.write(bytes);
@@ -212,6 +237,7 @@ export async function attachTerminal(options) {
                     asleep = true;
                     continue;
                 }
+                lastError = error;
             }
             finally {
                 const previous = connection;
@@ -220,7 +246,14 @@ export async function attachTerminal(options) {
                 await previous?.close();
             }
             reconnects += 1;
-            await options.sleep(Math.min(2_000, 100 * 2 ** Math.min(reconnects, 5)), signal);
+            failures += 1;
+            // Waiting for room on the workspace's host (or a working slot): said once, and again when the position changes.
+            const waiting = admissionNotice(lastError);
+            if (waiting && waiting !== notice)
+                io.stderr.write(`\r\n\x1b[2m· ${waiting}\x1b[0m\r\n`);
+            notice = waiting;
+            await options.sleep(reattachDelayMs(lastError, failures), signal);
+            lastError = undefined;
         }
         if (inputFailure)
             throw inputFailure;

package/dist/args.d.ts

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