@shardflux/cli 0.15.1 → 0.16.0

package/dist/args.js

@@ -12,7 +12,7 @@
 import { parseArgs } from 'node:util';
 import { ACCOUNT_COMMANDS } from "./account-args.js";
 import { UsageError } from "./errors.js";
-export const CLI_VERSION = '0.15.1';
+export const CLI_VERSION = '0.16.0';
 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).' },
@@ -57,7 +57,7 @@ const IF_REVISION = {
 };
 const WAIT = {
     wait: { type: 'boolean', description: 'Wait until the operation finishes.' },
-    timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (e.g. 90s, 5m; default 5m). The operation continues server side (a start waiting for capacity until its deadline, 15 minutes after it began; then it fails with capacity_unavailable).' },
+    timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (e.g. 90s, 5m; default 5m, and a start queued for capacity is waited for until its deadline, its place in the queue shown on stderr). The operation continues server side (a start waiting for capacity until its deadline, 15 minutes after it began; then it fails with capacity_unavailable).' },
     ...TIMING,
 };
 const REF = { name: 'id|key', required: true };
@@ -158,6 +158,11 @@ const KEY_COMMANDS = [
         } },
     { path: ['conversations', 'land'], summary: 'Record the landing action performed by the agent', positionals: [{ name: 'id', required: true }, { name: 'action', required: true }], options: { into: { type: 'string', value: '<ref>', description: 'Destination branch or PR URL.' } } },
     { path: ['conversations', 'move'], summary: 'Move at the end of the turn', positionals: [{ name: 'id', required: true }, { name: 'to', required: true }], options: {} },
+    { path: ['conversations', 'landing'], summary: 'Show or set how finished conversations reach this checkout', positionals: [{ name: 'mode' }, { name: 'backup' }], options: {
+            path: { type: 'string', value: '<path>', description: 'Local project checkout (default the current directory).' }
+        },
+        description: 'While the macOS app runs, a conversation whose turn ends with committed work lands in the local branch it started from: the branch moves to its commits and the changed files are written, keeping your uncommitted edits (auto, the default). pr opens a pull request instead; off leaves conversations in the cloud. Every file a landing rewrites is backed up first: backups lists them, restore <backup> puts the files back.',
+        examples: ['shard conversations landing', 'shard conversations landing pr', 'shard conversations landing backups', 'shard conversations landing restore 2026-10-09T12-00-00-000Z-fix-login-3fa2c1'] },
     ...['machine', 'template'].flatMap((level) => [
         { path: [level], summary: level === 'machine' ? 'Open your machine agent, or show its saved filesystem with --json' : 'Show this project’s template filesystem', positionals: [], options: {},
             description: LAYER_HELP[level] },
@@ -851,6 +856,14 @@ const KEY_COMMANDS = [
             'shard files patch acme/agent-7 /home/user/app.py --old "DEBUG = True" --new "DEBUG = False" --if-revision "$(shard ws get acme/agent-7 --json | jq .tree_revision)"',
         ],
     },
+    {
+        path: ['files', 'pull'],
+        summary: 'Download a large file a conversation committed into ~/Shardflux',
+        description: 'Each conversation’s committed changes appear in ~/Shardflux/<repository>/<base branch>/<conversation>/ while the macOS app runs. Files above the size limit are listed there as <file>.placeholder.txt; this downloads one in its place. <conversation> is its name, id or folder name.',
+        positionals: [{ name: 'conversation', required: true }, { name: 'path', required: true }],
+        options: {},
+        examples: ['shard files pull hype-video out/hype.mp4'],
+    },
     {
         path: ['operations', 'list'],
         summary: 'List a workspace’s operations, newest first',
@@ -1175,11 +1188,17 @@ const AGENT_OPTIONS = {
     reachable: { type: 'string', value: '<duration>', hidden: true, description: 'Deprecated; ignored. Claude conversations stay reachable without a time limit.' },
     approvals: { type: 'boolean', description: 'Keep the agent’s permission prompts.' },
 };
+/** A new thread on an existing conversation's computer (0.16.0+). */
+const ON_OPTIONS = {
+    on: { type: 'string', value: '<conversation|computer>', description: 'Start the thread on the computer of an existing conversation, sharing its packages, caches, services, ports and files, on its own branch: a conversation id, key or name, or its workspace key or id (shard agents computers lists them) (0.16.0+).' },
+    review: { type: 'boolean', description: 'With --on: a read-only Claude reviewer of that conversation’s worktree instead of a thread with its own branch (0.16.0+).' },
+};
 export const PROJECT_COMMAND = {
     path: ['<path>'], summary: 'Start a conversation in its own cloud VM',
     description: 'Opens Claude Code or Codex directly. --resume continues a project conversation. With --json it starts detached and prints the session. Detach with Ctrl-] then d.',
     positionals: [{ name: 'path', required: true }, { name: 'claude|codex' }], options: {
         ...AGENT_OPTIONS,
+        ...ON_OPTIONS,
         computer: COMPUTER_OPTION,
         new: { type: 'boolean', description: 'Start a new conversation.' },
         resume: { type: 'boolean', description: 'Continue a conversation from this project.' },
@@ -1208,8 +1227,12 @@ const AGENT_COMMANDS = [
     })),
     ...['status', 'enable', 'disable'].map(action => ({ path: ['agents', 'codex', action], summary: `${action} the account's billed Codex Cloud connector`, positionals: [], options: {} })),
     { path: ['agents', 'open'], summary: 'Open a conversation (Codex Cloud or the native Claude session)', description: 'Codex opens its existing Cloud thread without waking its VM. Claude attaches its native session.', positionals: [{ name: 'agent', required: true }], options: { ...AGENT_OPTIONS, app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default remembered choice).' }, in: { type: 'string', value: '<terminal|auto|claude-desktop|codex-app|web|t3>', description: 'Where to open it. auto (0.15.1+): the saved target, else a Claude conversation in Claude Desktop when it is installed, else in this terminal; web opens claude.ai.' } } },
-    { path: ['agents', 'new'], summary: 'Start a conversation in a fresh VM; Codex opens a genuine Cloud thread', positionals: [{ name: 'agent' }], options: {
+    { path: ['agents', 'computers'], summary: 'List the project’s computers a new thread can start on with --on, and the threads on each (0.16.0+)', positionals: [], options: {
+            path: { type: 'string', value: '<path>', description: 'Local project path (default the current directory).' },
+        } },
+    { path: ['agents', 'new'], summary: 'Start a conversation in a fresh VM, or with --on on an existing conversation’s computer; Codex opens a genuine Cloud thread', positionals: [{ name: 'agent' }], options: {
             ...AGENT_OPTIONS,
+            ...ON_OPTIONS,
             computer: COMPUTER_OPTION,
             app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default remembered choice).' },
             path: { type: 'string', value: '<path>', description: 'Local project path for first launch.' },
@@ -1407,6 +1430,9 @@ export function parseCommandLine(argv, options = {}) {
     // `acp --login` is the ACP terminal sign-in an editor runs (ACP appends the method's args to `shard acp`).
     if (argv.length === 2 && argv[0] === 'acp' && argv[1] === '--login')
         return { kind: 'run', command: { path: ['acp'], summary: '', positionals: [], options: {} }, values: { login: true }, positionals: [], global: { apiUrl: undefined, json: false, agentLabel: undefined, wake: undefined, wakeTimeout: undefined } };
+    // `menubar refresh` (0.15.2+, not in help): the background step each command may start (menubar.ts).
+    if (argv.length === 2 && argv[0] === 'menubar' && argv[1] === 'refresh')
+        return { kind: 'run', command: { path: ['menubar', 'refresh'], summary: '', positionals: [], options: {} }, values: {}, positionals: [], global: { apiUrl: undefined, json: false, agentLabel: undefined, wake: undefined, wakeTimeout: undefined } };
     if (argv.length === 1 && (argv[0] === 'acp' || argv[0] === 'device-helper'))
         return { kind: 'run', command: { path: [argv[0]], summary: '', positionals: [], options: {} }, values: {}, positionals: [], global: { apiUrl: undefined, json: false, agentLabel: undefined, wake: undefined, wakeTimeout: undefined } };
     const terminator = argv.indexOf('--');

package/dist/codex-cloud.d.ts

@@ -6,6 +6,8 @@ import type { InitialImage } from './initial-prompt.js';
 /** Only provider-returned task ids enter the registered Codex deep-link route. */
 export declare function openCodexThread(task: CodexCloudTask, env: Ctx['io']['env']): Promise<void>;
 export declare function submitCloudInitialPrompt(ctx: Ctx, c: Conversation, prompt: string, workspaceKey: string): Promise<void>;
+/** Prints the Cloud thread (and its link) and opens it in the Codex app; --json prints it instead. */
+export declare function printCloudThread(ctx: Ctx, c: Conversation, task: CodexCloudTask, submitted?: boolean): Promise<void>;
 /** How long the account's Codex remote device may take to come up before it counts as stuck. */
 export declare const CODEX_STARTING_LIMIT_MS: number;
 export type CodexConnectorView = {

package/dist/codex-cloud.js

@@ -32,6 +32,8 @@ export async function submitCloudInitialPrompt(ctx, c, prompt, workspaceKey) {
         throw new CodedError('initial_prompt_failed', `Created ${workspaceKey}, but the initial prompt could not be confirmed. Open that conversation before starting another.`, undefined, { workspace_key: workspaceKey, conversation_id: c.id, submitted: null });
     }
 }
+/** Prints the Cloud thread (and its link) and opens it in the Codex app; --json prints it instead. */
+export async function printCloudThread(ctx, c, task, submitted = false) { return output(ctx, c, task, submitted); }
 async function output(ctx, c, task, submitted = false) {
     const url = threadLink(task);
     if (ctx.json) {

package/dist/command-center-actions.js

@@ -12,6 +12,7 @@ import { randomUUID } from 'node:crypto';
 import { prepareAgentMachine } from "./agent-machine.js";
 import { OperationFailedError } from '@shardflux/sdk';
 import { launchConversationProject } from "./conversation-terminal.js";
+import { startThreadOn } from "./thread-on-computer.js";
 /** L9 can register target-specific handlers after detecting the installed applications. */
 export async function availableTargets(ctx) {
     const { HANDLERS } = await import("./handlers.js");
@@ -34,6 +35,14 @@ export async function agentAction(ctx, action, values, args) {
 }
 export const CENTER_HANDLERS = {
     async 'agents new'(ctx, values, [ref]) {
+        // A thread on an existing conversation's computer (0.16.0+).
+        if (values.on !== undefined) {
+            if (ref || values.like !== undefined)
+                throw new UsageError('--on starts a thread on that conversation’s computer; omit the agent argument and --like.');
+            return startThreadOn(ctx, values, str(values.path) ?? './');
+        }
+        if (values.review === true)
+            throw new UsageError('--review needs --on <conversation>.');
         if ((values.prompt !== undefined || values['prompt-file'] !== undefined || values.image !== undefined) && (ref || values.name !== undefined || values.like !== undefined || values.in !== undefined)) {
             throw new UsageError('An initial prompt needs a new conversation: use agents new --path <folder> --app claude|codex.');
         }

package/dist/commands.d.ts

@@ -31,6 +31,11 @@ export interface Ctx {
     wake: boolean;
     /** Bound on lifecycle waits per cell call, wakes included (--wake-timeout / SHARDFLUX_WAKE_TIMEOUT_MS). */
     wakeTimeoutMs: number;
+    /**
+     * The wake bound was given (--wake-timeout or SHARDFLUX_WAKE_TIMEOUT_MS; 0.16.0+): it is kept as given. Otherwise a
+     * resume queued for capacity is waited for until its deadline, its place shown on stderr.
+     */
+    wakeTimeoutExplicit?: boolean;
     signal: AbortSignal;
     /** --timing: print the SDK's timing of the command's open, wait or wake (stderr; a `timing` field with --json). */
     timing: boolean;
@@ -66,7 +71,7 @@ export interface Ctx {
     distribution: Distribution;
     /** The Node.js binary and script of this process; null when run in-process (tests, embedders). */
     runtime: import('./update.js').Runtime | null;
-    /** GET /v1/client-versions (unauthenticated): the latest version of every client. */
+    /** Every client's versions: GET /v1/client-versions (minimum_supported, hold) with `latest` from npm (0.15.2+). */
     clientVersions(): Promise<unknown>;
     /** This machine's name (default API key name of `shard setup`). */
     hostname(): string;
@@ -127,4 +132,21 @@ export declare function ttlSeconds(values: Values, b: {
     max: number;
     range: string;
 }): number | undefined;
+type ThreadRow = import('@shardflux/sdk').Agent & {
+    conversation_id?: string | null;
+    conversation_key?: string;
+};
+/**
+ * Each session's own conversation: the one whose harness session it is, else the computer's only live conversation.
+ * Rows that cannot be told apart keep no conversation rather than another thread's.
+ */
+export declare function withConversations(rows: import('@shardflux/sdk').Agent[], conversations: {
+    id: string;
+    key: string;
+    workspace_id: string;
+    harness_session_id: string | null;
+    state: string;
+    ended_at?: string | null;
+}[] | null): ThreadRow[];
 export declare const KEY_HANDLERS: Record<string, Handler>;
+export {};

package/dist/commands.js

@@ -12,7 +12,7 @@ import { agentConfigLikeSecrets, syncAgentConfig } from "./agent-config-sync.js"
 import { randomUUID } from 'node:crypto';
 import { access, readFile, writeFile } from 'node:fs/promises';
 import { basename, dirname, resolve as resolvePath } from 'node:path';
-import { EXECUTION_ID, ExecStartError, FEEDBACK_CATEGORIES, FEEDBACK_MESSAGE_MAX_LENGTH, NotSupportedForModeError, SDK_VERSION, ShardfluxApiError, ShardfluxProtocolError, newExecutionId, exitCodePosix } from '@shardflux/sdk';
+import { EXECUTION_ID, ExecStartError, capacityOf, FEEDBACK_CATEGORIES, FEEDBACK_MESSAGE_MAX_LENGTH, NotSupportedForModeError, SDK_VERSION, ShardfluxApiError, ShardfluxProtocolError, newExecutionId, exitCodePosix } from '@shardflux/sdk';
 import { parse as parseYaml } from 'yaml';
 import { CLI_VERSION, SECRET_NAME, UUID, parseDuration, parseEnvPairs, parsePositiveInt } from "./args.js";
 import { ExecSessionRunningError, ExecutionFailedError, ExecutionPendingError, InterruptedError, NotFoundError, UsageError } from "./errors.js";
@@ -32,7 +32,15 @@ export const str = (v) => (typeof v === 'string' ? v : undefined);
  * The workspace's cell client as this invocation configures it: the CLI's agent label, wake on use unless turned off,
  * and the wake timeout (an OperationTimeoutError past it exits 5).
  */
-const cellOf = (ctx, ws) => ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs, ...(ctx.wake ? {} : { wake: null }) });
+const cellOf = (ctx, ws) => ws.cell({
+    agentLabel: ctx.agentLabel,
+    transitionTimeoutMs: ctx.wakeTimeoutMs,
+    ...(!ctx.wake
+        ? { wake: null }
+        : ctx.wakeTimeoutExplicit
+            ? { wake: (timeoutMs, signal) => ws.wake({ timeoutMs, ...(signal ? { signal } : {}), agentLabel: ctx.agentLabel, untilCapacityDeadline: false }) }
+            : {}),
+});
 export const strs = (v) => (Array.isArray(v) ? v : typeof v === 'string' ? [v] : []);
 const MAX_SECRET_VALUE_BYTES = 65_536;
 /** `files patch --content-file`: a patch request is at most 7 MiB; larger files go through `files write`. */
@@ -357,10 +365,17 @@ async function writeNew(path, text, force) {
         throw new UsageError(`${path} exists; pass --force to overwrite it`);
     await writeFile(path, text);
 }
+/**
+ * An explicit `--timeout` is kept as given (0.16.0+): without one, a wait whose start is queued for capacity keeps waiting
+ * until the start's deadline (the SDK's `untilCapacityDeadline`), printing where it stands on stderr.
+ */
+function capacityWait(values) {
+    return values !== undefined && str(values.timeout) !== undefined ? { untilCapacityDeadline: false } : {};
+}
 /** Waits with the SDK's backoff; Ctrl-C reports the operation that keeps running. */
-async function waitOperation(ctx, operationId, timeoutMs) {
+async function waitOperation(ctx, operationId, timeoutMs, values) {
     try {
-        return await ctx.cloud().workspaces.waitForOperation(operationId, { timeoutMs, signal: ctx.signal });
+        return await ctx.cloud().workspaces.waitForOperation(operationId, { timeoutMs, signal: ctx.signal, ...capacityWait(values) });
     }
     catch (err) {
         if (ctx.signal.aborted)
@@ -782,7 +797,28 @@ function reportExecution(ctx, ref, r, opts) {
 }
 function lifecycleText(verb, w, op) {
     const finished = op.state === 'succeeded' || op.state === 'failed' || op.state === 'canceled';
-    return `${verb} ${w.key !== undefined ? `${w.key} (${w.id})` : w.id}: operation ${op.id} ${op.kind} ${op.state}${op.state_reason ? ` (${op.state_reason})` : ''}\n${finished ? durableText(op) : `wait with: shard operations wait ${op.id}\n`}`;
+    // A start queued for capacity (0.16.0+): its place in the queue.
+    const position = capacityOf(op)?.queuePosition;
+    const why = [op.state_reason, position ? `position ${position} in the queue` : null].filter(Boolean).join('; ');
+    return `${verb} ${w.key !== undefined ? `${w.key} (${w.id})` : w.id}: operation ${op.id} ${op.kind} ${op.state}${why ? ` (${why})` : ''}\n${finished ? durableText(op) : `wait with: shard operations wait ${op.id}\n`}`;
+}
+/**
+ * Each session's own conversation: the one whose harness session it is, else the computer's only live conversation.
+ * Rows that cannot be told apart keep no conversation rather than another thread's.
+ */
+export function withConversations(rows, conversations) {
+    if (!conversations)
+        return rows;
+    const live = conversations.filter(c => c.state !== 'done' && c.state !== 'archived' && !c.ended_at);
+    return rows.map(a => {
+        const session = a.id.slice(a.workspace_id.length + 1);
+        const bound = live.filter(c => c.workspace_id === a.workspace_id);
+        // An API that names the session's conversation (0.16.0+) decides; older ones are matched here by the same rule.
+        const named = a.conversation_id;
+        const c = (named ? conversations.find(c => c.id === named) : undefined)
+            ?? conversations.find(c => c.workspace_id === a.workspace_id && c.harness_session_id === session) ?? (bound.length === 1 ? bound[0] : undefined);
+        return c ? { ...a, conversation_id: c.id, conversation_key: c.key } : a;
+    });
 }
 /** The project-key commands; handlers.ts adds the account plane's. */
 function agentGrace(text) {
@@ -807,6 +843,9 @@ export const KEY_HANDLERS = {
             ...(str(values.limit) ? { limit: parsePositiveInt(str(values.limit), 'limit', 200) } : {}),
         };
         const rows = [];
+        // Which conversation each session belongs to (0.16.0+): several threads can share one computer. Read alongside
+        // the sessions; an API without conversations leaves the rows as they are.
+        const threads = import("./conversations.js").then(m => m.listConversations(ctx)).catch(() => null);
         let cursor = str(values.cursor);
         let next;
         do {
@@ -820,7 +859,8 @@ export const KEY_HANDLERS = {
             rows.splice(0, rows.length, ...await withLiveAgents(ctx, rows, { ...(state ? { state } : {}), labels }));
         // LAST MESSAGE (0.13.4+): the session's latest message, from an API that reports it.
         const message = (a) => !a.last_message ? '-' : a.last_message.length > 60 ? `${a.last_message.slice(0, 59)}…` : a.last_message;
-        out(ctx, rows.length ? table(['WORKSPACE', 'APP', 'STATE', 'TITLE', 'LAST MESSAGE'], rows.map(a => [a.workspace_key, a.app, a.state, a.title, message(a)])) : 'No agent sessions.\n', { data: rows, next_cursor: next });
+        const enriched = withConversations(rows, await threads);
+        out(ctx, rows.length ? table(['CONVERSATION', 'COMPUTER', 'APP', 'STATE', 'TITLE', 'LAST MESSAGE'], enriched.map(a => [a.conversation_key?.split('/').at(-1) ?? '-', a.workspace_key, a.app, a.state, a.title, message(a)])) : 'No agent sessions.\n', { data: enriched, next_cursor: next });
         if (!ctx.json && next)
             ctx.io.stderr.write(`more: shard agents list --cursor ${next}\n`);
         return 0;
@@ -1090,7 +1130,7 @@ export const KEY_HANDLERS = {
             ...(mode ? { mode } : {}),
             ...(computerUse !== undefined ? { computerUse } : {}),
             agentLabel: ctx.agentLabel,
-            wait: values.wait === false ? false : { timeoutMs, signal: ctx.signal },
+            wait: values.wait === false ? false : { timeoutMs, signal: ctx.signal, ...capacityWait(values) },
         }));
         const op = ws.activeOperation;
         if (ws.ready && ws.mode === 'processful' && ws.labels.shard_project)
@@ -1653,7 +1693,7 @@ export const KEY_HANDLERS = {
         });
         const op = ws.activeOperation;
         if (values.wait !== false && !ws.ready && op) {
-            await waitOperation(ctx, op.id, timeoutMs);
+            await waitOperation(ctx, op.id, timeoutMs, values);
             ws = await ctx.cloud().workspaces.get(ws.id);
         }
         const human = ws.ready
@@ -1849,7 +1889,7 @@ export const KEY_HANDLERS = {
         let ws = opened.workspace;
         const op = opened.operation;
         if (values.wait !== false && !ws.ready && op) {
-            await waitOperation(ctx, op.id, timeoutMs);
+            await waitOperation(ctx, op.id, timeoutMs, values);
             ws = await cloud.workspaces.get(ws.id);
         }
         const human = ws.ready
@@ -1875,7 +1915,7 @@ export const KEY_HANDLERS = {
         const label = str(values.label);
         let op = await draft.captureState(label === undefined ? {} : { label });
         if (values.wait === true)
-            op = await waitOperation(ctx, op.id, waitTimeout(values));
+            op = await waitOperation(ctx, op.id, waitTimeout(values), values);
         const checkpoint = typeof op.result?.checkpoint_id === 'string' ? `state ${op.result.checkpoint_id}\n` : '';
         out(ctx, `Capturing a state of the ${slug} draft: operation ${op.id} ${op.kind} ${op.state}\n${checkpoint}${op.state === 'succeeded' ? '' : `wait with: shard operations wait ${op.id}\n`}`, op);
         return 0;
@@ -1902,7 +1942,7 @@ export const KEY_HANDLERS = {
         let ws = await draft.openTestInstance({ ...(state ? { stateId: state } : {}), ...(instanceKey ? { key: instanceKey } : {}), ...(c ? { caps: c } : {}), agentLabel: ctx.agentLabel, wait: false });
         const op = ws.activeOperation;
         if (values.wait !== false && !ws.ready && op) {
-            await waitOperation(ctx, op.id, timeoutMs);
+            await waitOperation(ctx, op.id, timeoutMs, values);
             ws = await ctx.cloud().workspaces.get(ws.id);
         }
         const human = ws.ready
@@ -1931,7 +1971,7 @@ export const KEY_HANDLERS = {
             throw new UsageError('refusing to discard without --yes (the draft is deleted and its live test instances end)');
         let op = await ctx.cloud().templates.draft(slug).discard();
         if (values.wait === true)
-            op = await waitOperation(ctx, op.id, waitTimeout(values));
+            op = await waitOperation(ctx, op.id, waitTimeout(values), values);
         out(ctx, `Discarding the ${slug} draft: operation ${op.id} ${op.kind} ${op.state}\n`, op);
         return 0;
     },
@@ -2344,7 +2384,7 @@ export const KEY_HANDLERS = {
         const timeoutMs = waitTimeout(values);
         const op = values.durable === true
             ? await waited(ctx, `operation ${id} continues server side.`, () => ctx.cloud().workspaces.waitForDurable(id, { timeoutMs, signal: ctx.signal }))
-            : await waitOperation(ctx, id, timeoutMs);
+            : await waitOperation(ctx, id, timeoutMs, values);
         out(ctx, operationDetail(op), op);
         return 0;
     },
@@ -2488,7 +2528,7 @@ async function resolveSecret(ctx, values, ref) {
 }
 /** `--wait`: the SDK's own wait (the call resolves once the operation finished; one trace covers request and wait). */
 function lifecycleOptions(ctx, values, timeoutMs) {
-    return values.wait === true ? { wait: { timeoutMs, signal: ctx.signal } } : {};
+    return values.wait === true ? { wait: { timeoutMs, signal: ctx.signal, ...capacityWait(values) } } : {};
 }
 async function lifecycle(ctx, values, ref, verb, start, processfulOnly) {
     const timeoutMs = waitTimeout(values);

package/dist/conversation-commands.js

@@ -1,5 +1,6 @@
 import { out, str } from "./commands.js";
 import { UsageError } from "./errors.js";
+import { FilesMirror, humanBytes, listMirrorConversations, workspaceHub } from "./files-mirror.js";
 export function conversationClient(ctx) {
     const key = Boolean(ctx.io.env.SHARDFLUX_API_KEY?.trim()) || ctx.store.profile(ctx.apiUrl).api_key !== undefined;
     const session = Boolean(ctx.io.env.SHARDFLUX_SESSION_TOKEN?.trim()) || ctx.store.profile(ctx.apiUrl).session !== undefined;
@@ -32,5 +33,10 @@ export const CONVERSATION_HANDLERS = {
         out(ctx, `${r.title}: ${r.landed.how}\n`, r);
         return 0;
     },
+    async 'files pull'(ctx, _values, [conversation, path]) {
+        const r = await new FilesMirror(ctx, workspaceHub(ctx)).pull(conversation, path, () => listMirrorConversations(ctx));
+        out(ctx, r.already ? `${r.local_path} is already downloaded.\n` : `Downloaded ${r.path} (${humanBytes(r.bytes)}) to ${r.local_path}\n`, r);
+        return 0;
+    },
     async 'conversations move'(ctx, _values, [id, to]) { const r = await conversationClient(ctx).conversations.move(id, to, { signal: ctx.signal }); out(ctx, `Move scheduled for the end of the turn.\n`, r); return 0; },
 };

package/dist/conversation-terminal.js

@@ -15,15 +15,24 @@ import { localResumeTerminal } from "./conversation-local-resume.js";
 import { agentReachability } from "./agent-reachability.js";
 import { promptWithImages, readInitialImages, readInitialPrompt, uploadInitialImages } from "./initial-prompt.js";
 import { launchCodexCloud, openCodexConversation } from "./codex-cloud.js";
+import { startThreadOn } from "./thread-on-computer.js";
 /** Every terminal entry point uses the durable conversation's native harness, worktree and session. */
 export async function conversationTerminal(ctx, ws, c, project, values) {
     if (c.route === 'codex-cloud')
         return openCodexConversation(ctx, c);
     await restoreConversationBinding(ctx, c, ws);
-    return terminal(ctx, ws, c.harness, conversationName(c), project, values, undefined, c.worktree_path, { id: c.id, session: c.harness_session_id });
+    // A thread on another conversation's computer has its own PTY there, never the VM's own (0.16.0+).
+    const pty = ws.labels.shard_conversation && ws.labels.shard_conversation !== c.id ? conversationName(c) : undefined;
+    return terminal(ctx, ws, c.harness, conversationName(c), project, values, undefined, c.worktree_path, { id: c.id, session: c.harness_session_id, title: c.title, ...(pty ? { pty } : {}) });
 }
 /** Select a durable conversation, then use the harness's native terminal for all interaction. */
 export const launchConversationProject = async (ctx, values, [path = './', explicit]) => {
+    if (values.on !== undefined) {
+        const app = explicit ?? (values.claude === true ? 'claude' : values.codex === true ? 'codex' : undefined);
+        return startThreadOn(ctx, values, path, app);
+    }
+    if (values.review === true)
+        throw new UsageError('--review needs --on <conversation>.');
     const text = await readInitialPrompt(ctx, values);
     // Images are read and validated before allocation, held in memory, and written only into the new VM.
     const images = await readInitialImages(ctx, values, text);

package/dist/conversations.d.ts

@@ -26,6 +26,11 @@ export interface Conversation {
     } | null;
     ports?: number[];
     restore?: Record<string, unknown> | null;
+    /** The repository and the branch it started from, from APIs that return them. */
+    repo_remote?: string;
+    base_branch?: string | null;
+    role?: string;
+    join_mode?: string | null;
 }
 export interface LocalConversation {
     api_url: string;
@@ -33,17 +38,24 @@ export interface LocalConversation {
     project_id: string;
     conversation: Conversation;
     handed_off?: boolean;
+    /** The branch the conversation started from (0.16.0+), for APIs that do not return base_branch yet. */
+    base_branch?: string;
 }
 export declare const conversationName: (c: Conversation) => string;
 export declare function validateConversation(c: Conversation): Conversation;
 export declare function localConversations(ctx: Pick<Ctx, 'store' | 'apiUrl'>): Record<string, LocalConversation>;
-export declare function rememberConversation(ctx: Pick<Ctx, 'store' | 'apiUrl'>, c: Conversation, folder: string, handedOff?: boolean): void;
+export declare function rememberConversation(ctx: Pick<Ctx, 'store' | 'apiUrl'>, c: Conversation, folder: string, handedOff?: boolean, baseBranch?: string): void;
 export declare function conversationsUnavailable(e: unknown): boolean;
 export declare function getConversation(ctx: Ctx, id: string): Promise<Conversation>;
 export declare function listConversations(ctx: Ctx, projectId?: string): Promise<Conversation[]>;
 export declare function resolveConversation(ctx: Ctx, ref: string, folder?: string): Promise<Conversation>;
 /** Re-resolve the binding on every attach: a move changes the VM, never the conversation identity. */
 export declare function conversationWorkspace(ctx: Ctx, c: Conversation): Promise<Workspace>;
+/**
+ * A thread on an existing computer (a join) is prepared by that computer's guest: its worktree, then its harness. Waits
+ * until the guest confirms it (the conversation no longer carries restore instructions), within the wake timeout.
+ */
+export declare function waitThreadReady(ctx: Ctx, c: Conversation, pollMs?: number): Promise<Conversation>;
 export declare function restoreConversationBinding(ctx: Ctx, c: Conversation, ws: Workspace): Promise<void>;
 export declare function createConversationRecord(ctx: Ctx, folder: string, harness: Harness, route: Conversation['route'], name?: string, allocated?: (workspace: WorkspaceView) => void, idempotencyKey?: string): Promise<Conversation>;
 export declare function createConversation(ctx: Ctx, folder: string, harness: Harness, route: Conversation['route'], name?: string): Promise<{

package/dist/conversations.js

@@ -7,6 +7,8 @@ import { ensureProjectGit } from "./project-git.js";
 import { seedAgentRepository } from "./agent-repository.js";
 import { UsageError } from "./errors.js";
 import { conversationClient } from "./conversation-commands.js";
+import { recordSeedSnapshot } from "./files-mirror.js";
+import { rememberTwinSeed, sendTwinSeed, twinCheckoutArgv, twinSeed } from "./worktree-twin.js";
 export const conversationName = (c) => {
     const name = c.key.split('/').at(-1);
     if (!/^[a-z0-9][a-z0-9-]{0,47}$/.test(name) || c.branch !== `shard/${name}`)
@@ -23,11 +25,12 @@ export function localConversations(ctx) {
     const records = new AgentStateStore(ctx.store.dir).read().conversations ?? {};
     return Object.fromEntries(Object.entries(records).filter(([, r]) => r.api_url === ctx.apiUrl));
 }
-export function rememberConversation(ctx, c, folder, handedOff = false) {
+export function rememberConversation(ctx, c, folder, handedOff = false, baseBranch) {
     validateConversation(c);
     new AgentStateStore(ctx.store.dir).update(doc => {
         const records = doc.conversations ?? {};
-        records[c.id] = { api_url: ctx.apiUrl, folder, project_id: c.project_id, conversation: c, ...(handedOff ? { handed_off: true } : {}) };
+        const base = baseBranch ?? records[c.id]?.base_branch;
+        records[c.id] = { api_url: ctx.apiUrl, folder, project_id: c.project_id, conversation: c, ...(handedOff ? { handed_off: true } : {}), ...(base ? { base_branch: base } : {}) };
         doc.conversations = records;
     });
 }
@@ -68,9 +71,36 @@ export async function conversationWorkspace(ctx, c) {
         await ws.wake({ timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
     return ws;
 }
+/**
+ * A thread on an existing computer (a join) is prepared by that computer's guest: its worktree, then its harness. Waits
+ * until the guest confirms it (the conversation no longer carries restore instructions), within the wake timeout.
+ */
+export async function waitThreadReady(ctx, c, pollMs = 1000) {
+    const deadline = Date.now() + ctx.wakeTimeoutMs;
+    for (;;) {
+        const current = await getConversation(ctx, c.id);
+        if (!current.restore || current.restore.kind !== 'join')
+            return current;
+        if (current.state === 'done' || current.state === 'archived' || current.ended_at)
+            throw new UsageError('This thread ended before it started.');
+        if (Date.now() >= deadline)
+            throw new UsageError(`The computer is still preparing this thread; open it with shard agents open ${c.id} in a moment.`);
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(done, Math.min(pollMs, Math.max(1, deadline - Date.now())));
+            function done() { ctx.signal.removeEventListener('abort', abort); resolve(); }
+            function abort() { clearTimeout(timer); reject(ctx.signal.reason ?? new Error('interrupted')); }
+            ctx.signal.addEventListener('abort', abort, { once: true });
+        });
+    }
+}
 export async function restoreConversationBinding(ctx, c, ws) {
     if (!c.restore || c.restore.kind === 'new')
         return;
+    // Threads on an existing computer (0.16.0+): its guest prepares them, never this command.
+    if (c.restore.kind === 'join') {
+        await waitThreadReady(ctx, c);
+        return;
+    }
     const cell = ws.cell();
     if (c.restore.kind === 'join' && c.restore.read_only === true) {
         const review = await cell.exec.run(['sf-agent', 'conversation', 'restore', '--args', '{"start":false}'], { cwd: c.worktree_path, env: { SF_CONVERSATION_ID: c.id }, timeoutMs: 120_000, signal: ctx.signal });
@@ -92,13 +122,17 @@ export async function createConversationRecord(ctx, folder, harness, route, name
     // Both the conversation API and its legacy workspace fallback need a usable local HEAD.
     await conversationClient(ctx).conversations.list({ limit: 1 });
     const git = gitRunner(project.folder, { ...process.env, ...ctx.io.env }, ctx.signal);
-    const commit = await git(['rev-parse', 'HEAD']);
+    const head = await git(['rev-parse', 'HEAD']);
     const branch = await git(['symbolic-ref', '--quiet', '--short', 'HEAD']).catch(() => undefined);
+    // Uncommitted edits ride along as the twin snapshot the conversation starts from (worktree-twin.ts).
+    const seed = await twinSeed(ctx.store.dir, project.folder, head, ctx.store.profile(ctx.apiUrl).project_id).catch(() => ({ commit: head, snapshot: false }));
+    const commit = seed.commit;
     const response = await conversationClient(ctx).conversations.create({ repoRemote: project.remote ?? `file://${project.folder}`, harness, route, mode: 'new',
         base: { commit, ...(branch ? { branch } : {}) }, ...(name ? { name } : {}), projectId: ctx.store.profile(ctx.apiUrl).project_id }, { idempotencyKey, signal: ctx.signal });
     const c = validateConversation({ ...response.conversation, restore: response.restore });
     allocated?.(response.workspace);
-    rememberConversation(ctx, c, project.folder);
+    rememberTwinSeed(ctx.store.dir, c.id, project.folder, seed, branch);
+    rememberConversation(ctx, c, project.folder, false, branch);
     return c;
 }
 export async function createConversation(ctx, folder, harness, route, name) {
@@ -109,9 +143,11 @@ export async function createConversation(ctx, folder, harness, route, name) {
         // This is a one-time seed. A conversation never watches or writes the owner's checkout.
         await seedAgentRepository(ctx, ws, project.folder, { root: c.worktree_path, populate: true });
         const cell = ws.cell();
-        const result = await 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, cell, c, project.folder, ctx.signal);
+        const result = await 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);
         return { conversation: c, workspace: ws };
     }
     catch (error) {

package/dist/device-helper.js

@@ -1,6 +1,7 @@
 import { setTimeout as delay } from 'node:timers/promises';
 import { DeviceExecutor, askConnectedAcp } from "./device-bridge.js";
 import { ConversationMirrorState, mirrorProjectConversations } from "./conversation-stash.js";
+import { FilesMirrorState, mirrorFilesOnce } from "./files-mirror.js";
 import { withTargetLock } from "./target-lock.js";
 import { join } from 'node:path';
 import { conversationsUnavailable } from "./conversations.js";
@@ -10,6 +11,7 @@ import { readFileSync } from 'node:fs';
 import { writePrivateFile } from "./credentials.js";
 import { conversationClient } from "./conversation-commands.js";
 import { Readable } from 'node:stream';
+import { runWorktreeTwin } from "./worktree-twin-engine.js";
 /** The menu bar owns this helper and its stdin; VM data can request actions but cannot answer approvals. */
 export async function runDeviceHelper(ctx) {
     const abort = new AbortController(), signal = AbortSignal.any([ctx.signal, abort.signal]);
@@ -50,7 +52,7 @@ export async function runDeviceHelper(ctx) {
             ctx.io.stdout.write(JSON.stringify({ type: 'approval_resolved', request_id: approval.request_id }) + '\n'); });
     };
     const working = new Map();
-    const mirrored = new ConversationMirrorState();
+    const mirrored = new ConversationMirrorState(), files = new FilesMirrorState();
     const deviceFile = join(ctx.store.dir, 'device-id');
     let deviceId;
     try {
@@ -62,15 +64,19 @@ export async function runDeviceHelper(ctx) {
     }
     const executor = new DeviceExecutor(ctx, ask, deviceId);
     const report = (e) => { ctx.io.stderr.write(`Device bridge: ${e instanceof Error ? e.message : String(e)}\n`); };
-    let mirroring;
+    let mirroring, twin;
     try {
         return await withTargetLock(join(ctx.store.dir, 'device-helper-lock'), async () => {
+            // Finished conversations land in their local branches (worktree-twin-engine.ts); its own loop and backoff.
+            twin = runWorktreeTwin(ctx, deviceId, signal).catch(report);
             // A slow or failed transcript copy must not delay heartbeats, request polling or approvals.
             mirroring = (async () => {
                 let failures = 0;
                 const reported = new Set();
                 while (!signal.aborted) {
                     let wait = 1000;
+                    // Committed files of every conversation, under ~/Shardflux; its own interval and backoff.
+                    await mirrorFilesOnce(ctx, files);
                     try {
                         await mirrorProjectConversations(ctx, mirrored);
                         failures = 0;
@@ -124,6 +130,7 @@ export async function runDeviceHelper(ctx) {
         await executor.close();
         await Promise.all([...working.values()]);
         await mirroring;
+        await twin;
         await input.catch(() => undefined);
     }
 }

package/dist/errors.d.ts

@@ -121,6 +121,11 @@ export interface ErrorInfo {
     details?: Record<string, unknown>;
     source?: 'api' | 'cell' | 'unknown';
     last_state?: string;
+    /** A wait that timed out (0.16.0+): the operation's last state_reason. */
+    last_reason?: string;
+    /** A wait that timed out on a queued start (0.16.0+): its deadline (RFC 3339) and place in the queue. */
+    deadline_at?: string;
+    queue_position?: number;
     operation?: unknown;
     /** A file-first execution the error is about (failed, lost, still running, or left running by Ctrl-C). */
     execution_id?: string;

package/dist/errors.js

@@ -199,7 +199,17 @@ export function describeError(err) {
         };
     }
     if (err instanceof OperationTimeoutError) {
-        return { code: 'timeout', message: err.message, operation_id: err.operationId, last_state: err.lastState, ...(err.durable ? { details: { durable: false, state: 'pending' } } : {}) };
+        // A queued start (0.16.0+): its last reason, deadline and place in the queue.
+        return {
+            code: 'timeout',
+            message: err.message,
+            operation_id: err.operationId,
+            last_state: err.lastState,
+            ...(err.lastReason ? { last_reason: err.lastReason } : {}),
+            ...(err.deadlineAt ? { deadline_at: err.deadlineAt } : {}),
+            ...(err.queuePosition !== null ? { queue_position: err.queuePosition } : {}),
+            ...(err.durable ? { details: { durable: false, state: 'pending' } } : {}),
+        };
     }
     // --durable (0.7.0+): the suspend succeeded; its durable copy could not be made (see the lifecycle reference).
     if (err instanceof DurabilityLostError) {