@shardflux/cli 0.15.2 → 0.16.0

package/dist/handlers.js

@@ -15,5 +15,7 @@ import { MENUBAR_HANDLERS } from "./menubar.js";
 import { UPDATE_HANDLERS } from "./update.js";
 import { FILESYSTEM_HANDLERS } from "./filesystem-commands.js";
 import { CONVERSATION_HANDLERS as LOCAL_CONVERSATION_HANDLERS } from "./conversation-local.js";
+import { TWIN_HANDLERS } from "./worktree-twin-engine.js";
 import { CODEX_CLOUD_HANDLERS } from "./codex-cloud.js";
-export const HANDLERS = { ...CODEX_CLOUD_HANDLERS, ...CONVERSATION_HANDLERS, ...LOCAL_CONVERSATION_HANDLERS, ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS, ...UPDATE_HANDLERS };
+import { THREAD_HANDLERS } from "./thread-on-computer.js";
+export const HANDLERS = { ...CODEX_CLOUD_HANDLERS, ...THREAD_HANDLERS, ...CONVERSATION_HANDLERS, ...LOCAL_CONVERSATION_HANDLERS, ...TWIN_HANDLERS, ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS, ...UPDATE_HANDLERS };

package/dist/main.js

@@ -31,6 +31,7 @@ import { HANDLERS } from "./handlers.js";
 import { makeFetch } from "./http.js";
 import { Input } from "./input.js";
 import { TimingRecorder, notices, timingJson, timingText } from "./timing.js";
+import { waitStatusListener } from "./wait-status.js";
 import { CLI_DISTRIBUTION, NOTICE_WAIT_MS, UpdateCheck, noticeOf, updateCheckDisabled, updateView } from "./update-check.js";
 const KEY_SHAPE = /^sfk_[a-z2-7]{16}_[A-Za-z0-9]+$/;
 // Printable (no C0 controls or DEL), as the API's AgentLabel pattern.
@@ -126,7 +127,7 @@ function hintFor(info, cred, file, command = '') {
     if (reason === 'edit_not_text')
         return 'the file is not UTF-8 text; use files write for binary data';
     if (reason === 'host_capacity')
-        return 'the workspace cannot be woken right now and the call did not run; retry in a few seconds';
+        return "the workspace's host is making room to wake it and the call did not run (it was already retried); run the command again";
     if (reason === 'host_feature_unavailable')
         return hostFeatureHint(info.details?.feature);
     // Inbound ports (0.9.0): the next step names the command.
@@ -534,6 +535,7 @@ export async function run(argv, io, opts = {}) {
             agentLabel,
             wake,
             wakeTimeoutMs,
+            wakeTimeoutExplicit: parsed.global.wakeTimeout !== undefined || Boolean(io.env.SHARDFLUX_WAKE_TIMEOUT_MS?.trim()),
             signal,
             timing: showTiming,
             traces,
@@ -569,13 +571,18 @@ export async function run(argv, io, opts = {}) {
                 if (cloud)
                     return cloud;
                 const key = apiKey();
+                // Timings, and (0.16.0+) where a wait stands: a queued start's position, a call waiting for room (stderr).
+                const waitStatus = waitStatusListener(io.stderr, parsed.global.json);
                 cloud = new Shardflux({
                     apiKey: key.token,
                     baseUrl: apiUrl,
                     userAgent,
                     fetch: watchedFetch,
                     sleep,
-                    onProgress: traces.listener,
+                    onProgress: (e) => {
+                        traces.listener(e);
+                        waitStatus(e);
+                    },
                     versionCheck: false,
                 });
                 return cloud;

package/dist/registry.d.ts

@@ -1,48 +1,8 @@
-export declare const NPM_REGISTRY = "https://registry.npmjs.org";
-/** Each registry request's timeout (ms). */
-export declare const REGISTRY_TIMEOUT_MS = 3000;
+import type { RegistryOptions } from '@shardflux/sdk';
+export { NPM_REGISTRY, npmLatest, withRegistryLatest } from '@shardflux/sdk';
 /** The npm packages whose versions `shard update` compares. */
 export declare const NPM_CLIENTS: readonly ["shardflux", "@shardflux/cli", "@shardflux/sdk", "@shardflux/mcp", "@shardflux/menubar-darwin"];
-export interface RegistryAnswer {
-    latest: string | null;
-    /** The registry's validator for the next request (npm's dist-tags endpoint sends none today). */
-    etag: string | null;
-    /** 304: what the caller cached under `etag` is still current. */
-    notModified: boolean;
-}
-export interface RegistryOptions {
-    fetch: typeof fetch;
-    /** Default https://registry.npmjs.org (SHARDFLUX_NPM_REGISTRY overrides it for the CLI). */
-    registry?: string;
-    etag?: string | null;
-    timeoutMs?: number;
-    signal?: AbortSignal;
-    userAgent?: string;
-}
 /** The registry to ask: SHARDFLUX_NPM_REGISTRY, else npm's public registry. */
 export declare function npmRegistry(env: Record<string, string | undefined>): string;
-/** `latest` of an npm package from `<registry>/-/package/<name>/dist-tags`, or null when the registry did not answer. */
-export declare function npmLatest(pkg: string, opts: RegistryOptions): Promise<RegistryAnswer | null>;
 /** `latest` of every package in `packages`, asked in parallel; a package the registry did not answer is absent. */
 export declare function npmLatestAll(packages: readonly string[], opts: RegistryOptions): Promise<Record<string, string>>;
-export interface CatalogEntry {
-    package: string;
-    ecosystem: string;
-    latest: string | null;
-    minimum_supported: string | null;
-    upgrade_command: string | null;
-    release_notes_url: string | null;
-    hold?: string | null;
-    [key: string]: unknown;
-}
-/**
- * A GET /v1/client-versions body whose npm entries carry the registry's `latest` (`registry`: package -> version; an
- * absent package keeps the catalog's). Works with every catalog shape the API has served: no `hold` field, `latest`
- * null, a package missing from the list, or no catalog at all (`catalog` null: the API did not answer).
- *
- * `hold`: when the registry's latest is that version, it is not recommended; the catalog's own `latest` is, when it is
- * older, else `minimum_supported` (so "no longer supported" still works and nobody is told to update).
- */
-export declare function withRegistryLatest(catalog: unknown, registry: Record<string, string | null | undefined>): {
-    clients: CatalogEntry[];
-};

package/dist/registry.js

@@ -1,102 +1,18 @@
 /**
- * The latest version of each Shardflux client comes from its registry (0.15.2+), so a release is known the moment it
- * is published: npm's `latest` dist-tag, which is what `npm i -g shardflux` and `shard update` install. (`stable` is an
- * opt-in tag for installs behind a release-age gate, docs/progress/packaging.md; it never drives the update notice.)
- *
- * The API catalog (GET /v1/client-versions) still says which versions it serves (`minimum_supported`) and may name a
- * version to stop recommending (`hold`, an emergency brake). Its `latest` is only the fallback when the registry does
- * not answer. Every request here is bounded and never throws: offline means "no answer".
+ * The latest version of each Shardflux client comes from npm (0.15.2+; the SDK's registry helpers): its `latest`
+ * dist-tag is what `npm i -g shardflux` and `shard update` install. The API catalog adds `minimum_supported` and
+ * `hold` (see withRegistryLatest).
  */
-import { compareVersions } from '@shardflux/sdk';
-export const NPM_REGISTRY = 'https://registry.npmjs.org';
-/** Each registry request's timeout (ms). */
-export const REGISTRY_TIMEOUT_MS = 3_000;
+import { npmLatest, registryFromEnv } from '@shardflux/sdk';
+export { NPM_REGISTRY, npmLatest, withRegistryLatest } from '@shardflux/sdk';
 /** The npm packages whose versions `shard update` compares. */
 export const NPM_CLIENTS = ['shardflux', '@shardflux/cli', '@shardflux/sdk', '@shardflux/mcp', '@shardflux/menubar-darwin'];
-const str = (v) => (typeof v === 'string' && v.length > 0 ? v : null);
-const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
 /** The registry to ask: SHARDFLUX_NPM_REGISTRY, else npm's public registry. */
 export function npmRegistry(env) {
-    const own = env.SHARDFLUX_NPM_REGISTRY?.trim();
-    return own ? own.replace(/\/+$/, '') : NPM_REGISTRY;
-}
-/** `latest` of an npm package from `<registry>/-/package/<name>/dist-tags`, or null when the registry did not answer. */
-export async function npmLatest(pkg, opts) {
-    try {
-        const timeout = AbortSignal.timeout(opts.timeoutMs ?? REGISTRY_TIMEOUT_MS);
-        const headers = { accept: 'application/json' };
-        if (opts.userAgent)
-            headers['user-agent'] = opts.userAgent;
-        if (opts.etag)
-            headers['if-none-match'] = opts.etag;
-        const res = await opts.fetch(`${(opts.registry ?? NPM_REGISTRY).replace(/\/+$/, '')}/-/package/${encodeURIComponent(pkg)}/dist-tags`, {
-            method: 'GET',
-            headers,
-            signal: opts.signal ? AbortSignal.any([timeout, opts.signal]) : timeout,
-        });
-        const etag = res.headers.get('etag');
-        if (res.status === 304) {
-            await res.body?.cancel().catch(() => undefined);
-            return { latest: null, etag: etag ?? opts.etag ?? null, notModified: true };
-        }
-        if (!res.ok) {
-            await res.body?.cancel().catch(() => undefined);
-            return null;
-        }
-        const body = JSON.parse(await res.text());
-        const latest = isObj(body) ? str(body.latest) : null;
-        // A tag that is not a version (a broken registry mirror) is no answer.
-        if (latest === null || compareVersions(latest, latest) === null)
-            return null;
-        return { latest, etag, notModified: false };
-    }
-    catch {
-        return null;
-    }
+    return registryFromEnv(env, 'npm');
 }
 /** `latest` of every package in `packages`, asked in parallel; a package the registry did not answer is absent. */
 export async function npmLatestAll(packages, opts) {
     const answers = await Promise.all(packages.map(async (pkg) => [pkg, await npmLatest(pkg, { ...opts, etag: null })]));
     return Object.fromEntries(answers.flatMap(([pkg, a]) => (a?.latest ? [[pkg, a.latest]] : [])));
 }
-const DEFAULT_UPGRADE = {
-    shardflux: 'npm i -g shardflux',
-    '@shardflux/cli': 'npm i -g shardflux',
-    '@shardflux/menubar-darwin': 'shard update',
-};
-/**
- * A GET /v1/client-versions body whose npm entries carry the registry's `latest` (`registry`: package -> version; an
- * absent package keeps the catalog's). Works with every catalog shape the API has served: no `hold` field, `latest`
- * null, a package missing from the list, or no catalog at all (`catalog` null: the API did not answer).
- *
- * `hold`: when the registry's latest is that version, it is not recommended; the catalog's own `latest` is, when it is
- * older, else `minimum_supported` (so "no longer supported" still works and nobody is told to update).
- */
-export function withRegistryLatest(catalog, registry) {
-    const listed = isObj(catalog) && Array.isArray(catalog.clients) ? catalog.clients.filter(isObj) : [];
-    const entries = listed.map((c) => ({
-        ...c,
-        package: String(c.package),
-        ecosystem: String(c.ecosystem),
-        latest: str(c.latest),
-        minimum_supported: str(c.minimum_supported),
-        upgrade_command: str(c.upgrade_command),
-        release_notes_url: str(c.release_notes_url),
-        hold: str(c.hold),
-    }));
-    for (const pkg of Object.keys(registry)) {
-        if (!entries.some((e) => e.ecosystem === 'npm' && e.package === pkg)) {
-            entries.push({ package: pkg, ecosystem: 'npm', latest: null, minimum_supported: null, upgrade_command: DEFAULT_UPGRADE[pkg] ?? null, release_notes_url: `https://www.npmjs.com/package/${pkg}?activeTab=versions`, hold: null });
-        }
-    }
-    return {
-        clients: entries.map((e) => {
-            const fromRegistry = e.ecosystem === 'npm' ? str(registry[e.package]) : null;
-            let latest = fromRegistry ?? e.latest;
-            if (latest !== null && e.hold && compareVersions(latest, e.hold) === 0) {
-                latest = e.latest !== null && compareVersions(e.latest, e.hold) === -1 ? e.latest : e.minimum_supported;
-            }
-            return { ...e, latest };
-        }),
-    };
-}

package/dist/thread-on-computer.d.ts

@@ -0,0 +1,35 @@
+import type { Ctx, Handler } from './commands.js';
+import type { Values } from './args.js';
+import type { Conversation, Harness } from './conversations.js';
+/** A conversation still bound to its computer: not done, archived or ended. */
+export declare const activeConversation: (c: Pick<Conversation, "state" | "ended_at">) => boolean;
+export interface ComputerThread {
+    id: string;
+    key: string;
+    title: string;
+    harness: Harness;
+    state: Conversation['state'];
+    route: Conversation['route'];
+    role: string;
+    join_mode: string | null;
+    branch: string;
+}
+export interface Computer {
+    workspace_id: string;
+    workspace_key: string;
+    state: 'running' | 'suspended';
+    last_activity_at: string | null;
+    conversations: ComputerThread[];
+}
+/** The project's conversations: its repository's, or (for a folder without a remote) the ones started from it. */
+export declare function projectConversations(ctx: Pick<Ctx, 'store' | 'apiUrl'>, all: Conversation[], folder: string): Conversation[];
+/** Computers a new thread can start on: each live VM (running or parked, never deleted) of the project's active conversations. */
+export declare function listComputers(ctx: Ctx, folder: string): Promise<Computer[]>;
+/**
+ * The conversation whose computer `--on` names: a conversation id, key or name, or the VM's workspace key or id (then
+ * the VM's own conversation, else its oldest live thread).
+ */
+export declare function resolveOn(ctx: Ctx, ref: string, folder: string): Promise<Conversation>;
+/** Starts the thread on `--on`'s computer and opens it like a new conversation of that app. */
+export declare function startThreadOn(ctx: Ctx, values: Values, path: string, explicitApp?: string): Promise<number>;
+export declare const THREAD_HANDLERS: Record<string, Handler>;

package/dist/thread-on-computer.js

@@ -0,0 +1,200 @@
+// A new Claude or Codex thread on an existing conversation's computer (0.16.0+): `shard agents new --on <ref>`,
+// `shard ./ --on <ref>` and `shard agents computers`. The thread joins that VM as a worker (its own branch and
+// worktree, sharing the VM's packages, caches, services, ports and files) or, with --review, as a read-only Claude
+// reviewer. Codex threads are genuine Codex Cloud threads. docs/progress/thread-on-existing-vm.md.
+import { randomUUID } from 'node:crypto';
+import { ShardfluxApiError } from '@shardflux/sdk';
+import { out, str } from "./commands.js";
+import { UsageError } from "./errors.js";
+import { table } from "./format.js";
+import { AgentStateStore } from "./agent-state.js";
+import { normalizeRemote, projectIdentity } from "./project-identity.js";
+import { progress } from "./progress.js";
+import { conversationClient } from "./conversation-commands.js";
+import { conversationName, conversationWorkspace, getConversation, listConversations, localConversations, rememberConversation, validateConversation, waitThreadReady } from "./conversations.js";
+import { syncAgentCredentials } from "./agent-credentials.js";
+import { cloudClaudeLogin, loginClaudeInWorkspace, requireClaudeTerminal } from "./claude-cloud-login.js";
+import { promptWithImages, readInitialImages, readInitialPrompt, uploadInitialImages } from "./initial-prompt.js";
+import { recordSeedSnapshot } from "./files-mirror.js";
+import { ensureCodexCloud, printCloudThread, submitCloudInitialPrompt } from "./codex-cloud.js";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SHA = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/;
+/** A conversation still bound to its computer: not done, archived or ended. */
+export const activeConversation = (c) => c.state !== 'done' && c.state !== 'archived' && !c.ended_at;
+/** The project's conversations: its repository's, or (for a folder without a remote) the ones started from it. */
+export function projectConversations(ctx, all, folder) {
+    const project = projectIdentity(folder), remote = project.remote ?? `file://${project.folder}`, records = localConversations(ctx);
+    const same = (r) => { try {
+        return normalizeRemote(r, project.folder) === remote;
+    }
+    catch {
+        return false;
+    } };
+    return all.filter(c => c.repo_remote ? same(c.repo_remote) : records[c.id]?.folder === project.folder);
+}
+/** The VM's own conversation first (its label), then the oldest thread on it. */
+function host(bound, label) {
+    return bound.find(c => c.id === label) ?? [...bound].sort((a, b) => a.created_at.localeCompare(b.created_at))[0];
+}
+const thread = (c) => ({ id: c.id, key: c.key, title: c.title, harness: c.harness, state: c.state, route: c.route,
+    role: c.role ?? 'main', join_mode: c.join_mode ?? null, branch: c.branch });
+/** Computers a new thread can start on: each live VM (running or parked, never deleted) of the project's active conversations. */
+export async function listComputers(ctx, folder) {
+    const client = conversationClient(ctx);
+    const groups = new Map();
+    for (const c of projectConversations(ctx, await listConversations(ctx), folder).filter(activeConversation))
+        groups.set(c.workspace_id, [...groups.get(c.workspace_id) ?? [], c]);
+    const computers = await Promise.all([...groups].map(async ([id, bound]) => {
+        let ws;
+        try {
+            ws = await client.workspaces.get(id);
+        }
+        catch (error) {
+            if (error instanceof ShardfluxApiError && error.status === 404)
+                return null;
+            throw error;
+        }
+        const observed = String(ws.data.observed_state ?? '');
+        if (ws.data.deleted_at || ['failed', 'deleted', 'deleting'].includes(observed))
+            return null;
+        const own = host(bound, ws.labels.shard_conversation);
+        const ordered = [own, ...bound.filter(c => c !== own).sort((a, b) => a.created_at.localeCompare(b.created_at))];
+        const last = bound.map(c => c.last_activity_at ?? c.created_at).sort().at(-1) ?? null;
+        return { workspace_id: ws.id, workspace_key: ws.key, state: observed === 'suspended' ? 'suspended' : 'running', last_activity_at: last, conversations: ordered.map(thread) };
+    }));
+    return computers.filter((c) => c !== null).sort((a, b) => (b.last_activity_at ?? '').localeCompare(a.last_activity_at ?? ''));
+}
+/**
+ * The conversation whose computer `--on` names: a conversation id, key or name, or the VM's workspace key or id (then
+ * the VM's own conversation, else its oldest live thread).
+ */
+export async function resolveOn(ctx, ref, folder) {
+    if (!ref.trim())
+        throw new UsageError('--on needs a conversation or computer; list them with shard agents computers.');
+    let target;
+    if (/^conv_[a-z0-9]{26}$/.test(ref))
+        target = await getConversation(ctx, ref);
+    else {
+        const all = await listConversations(ctx);
+        const keyed = all.filter(c => c.key === ref);
+        if (keyed.length === 1)
+            target = keyed[0];
+        else if (UUID.test(ref) || ref.includes('/')) {
+            const client = conversationClient(ctx);
+            let ws = null;
+            try {
+                ws = UUID.test(ref) ? await client.workspaces.get(ref) : await client.workspaces.findByKey(ref, { includeDeleted: false, signal: ctx.signal });
+            }
+            catch (error) {
+                if (!(error instanceof ShardfluxApiError && error.status === 404))
+                    throw error;
+            }
+            if (ws)
+                target = host(all.filter(c => c.workspace_id === ws.id && activeConversation(c)), ws.labels.shard_conversation);
+        }
+        else {
+            const named = projectConversations(ctx, all, folder).filter(c => conversationName(c) === ref);
+            const live = named.filter(activeConversation);
+            if ((live.length || named.length) > 1)
+                throw new UsageError(`Several conversations are named ${ref}; use its key or id (shard agents computers lists them).`);
+            target = live[0] ?? named[0];
+        }
+    }
+    if (!target)
+        throw new UsageError(`No conversation or computer "${ref}" in this project. List them with shard agents computers.`);
+    if (!activeConversation(target))
+        throw new UsageError(`${target.title || target.key} has ended, so its computer is not available. Start the thread on a new computer, or continue that conversation with shard agents open ${target.id}.`);
+    return target;
+}
+/** `git rev-parse HEAD` of the target's worktree in its VM: the new thread starts from its committed work. */
+async function targetHead(ws, target, signal) {
+    const head = await ws.cell().exec.run(['git', '-C', target.worktree_path, 'rev-parse', 'HEAD'], { timeoutMs: 30_000, maxOutputBytes: 4096, signal });
+    const sha = head.stdout.trim();
+    return head.exitCode === 0 && SHA.test(sha) ? sha : target.base_commit;
+}
+/** Records a thread that could never be admitted as discarded, so it never holds the shared computer. */
+async function abandon(ctx, c) {
+    try {
+        await conversationClient(ctx).conversations.land(c.id, 'discard', { idempotencyKey: `abandon-${c.id}`, signal: ctx.signal });
+    }
+    catch { /* the API refuses it again on the next try */ }
+}
+/** Starts the thread on `--on`'s computer and opens it like a new conversation of that app. */
+export async function startThreadOn(ctx, values, path, explicitApp) {
+    const ref = str(values.on) ?? '';
+    for (const flag of ['like', 'in', 'resume', 'new'])
+        if (values[flag] !== undefined && !(flag === 'in' && ['terminal', 'codex-app'].includes(String(values.in))))
+            throw new UsageError(`--${flag} cannot be combined with --on.`);
+    if (values.computer === true)
+        throw new UsageError('--computer is a setting of a new computer; a thread with --on uses its computer as it is.');
+    const text = await readInitialPrompt(ctx, values);
+    const images = await readInitialImages(ctx, values, text);
+    const initialPrompt = text === undefined ? undefined : promptWithImages(text, images);
+    const project = projectIdentity(path), projectKey = project.remote ?? project.folder, store = new AgentStateStore(ctx.store.dir);
+    const chosen = explicitApp ?? str(values.app);
+    if (chosen !== undefined && chosen !== 'claude' && chosen !== 'codex')
+        throw new UsageError('--app must be claude or codex');
+    const app = chosen ?? store.app(projectKey);
+    const review = values.review === true;
+    if (review && app === 'codex')
+        throw new UsageError('--review starts a read-only Claude reviewer. A Codex thread on a computer works on its own branch; omit --review.');
+    const name = str(values.name);
+    if (name !== undefined && !/^[a-z0-9][a-z0-9-]{0,47}$/.test(name))
+        throw new UsageError('--name must match ^[a-z0-9][a-z0-9-]{0,47}$');
+    const target = await resolveOn(ctx, ref, path);
+    let signedIn = true;
+    if (app === 'claude') {
+        await syncAgentCredentials(ctx.cloud(), { home: ctx.io.env.HOME, redact: value => ctx.addSecret(value) });
+        signedIn = Boolean(await cloudClaudeLogin(ctx));
+        if (!signedIn)
+            requireClaudeTerminal(ctx);
+        if (!ctx.json && values.detach !== true && (!ctx.io.stdin.isTTY || !ctx.io.stdin.setRawMode))
+            throw new UsageError('agent terminal requires a TTY; add --json to start it detached');
+    }
+    else
+        await ensureCodexCloud(ctx);
+    progress(ctx, `Starting ${app === 'claude' ? 'Claude' : 'Codex'} on the computer with ${target.title || target.key}…`);
+    const ws = await conversationWorkspace(ctx, target);
+    const commit = await targetHead(ws, target, ctx.signal);
+    const baseBranch = target.base_branch ?? undefined;
+    await uploadInitialImages(ws.cell(), images, ctx.signal);
+    const response = await conversationClient(ctx).conversations.create({ projectId: target.project_id, repoRemote: target.repo_remote ?? ws.labels.repo_remote ?? '',
+        harness: app, route: app === 'codex' ? 'codex-cloud' : 'terminal', mode: 'join', parentId: target.id, ...(review ? { joinMode: 'reviewer' } : {}),
+        base: { commit, ...(baseBranch ? { branch: baseBranch } : {}) }, ...(name ? { name } : {}) }, { idempotencyKey: randomUUID(), signal: ctx.signal });
+    let c = validateConversation({ ...response.conversation, restore: response.restore });
+    rememberConversation(ctx, c, project.folder, false, baseBranch);
+    store.save(projectKey, app);
+    if (app === 'codex') {
+        try {
+            await ctx.cloud().codex.admit(c.id, { idempotencyKey: `codex-${c.id}`, signal: ctx.signal });
+        }
+        catch (error) {
+            await abandon(ctx, c);
+            throw error;
+        }
+        const task = await ctx.cloud().codex.waitTask(c.id, { timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
+        // The worktree exists once admission prepared it: record where the thread started for the files shelf.
+        await recordSeedSnapshot(ws, c, ctx.signal);
+        if (initialPrompt !== undefined)
+            await submitCloudInitialPrompt(ctx, c, initialPrompt, ws.key);
+        await printCloudThread(ctx, c, task, initialPrompt !== undefined);
+        return 0;
+    }
+    // The computer's guest prepares the worktree and starts the harness; the terminal attaches to that session.
+    c = await waitThreadReady(ctx, c);
+    if (!review)
+        await recordSeedSnapshot(ws, c, ctx.signal);
+    if (!signedIn)
+        await loginClaudeInWorkspace(ctx, ws);
+    const { conversationTerminal } = await import("./conversation-terminal.js");
+    return conversationTerminal(ctx, ws, c, projectKey, { ...values, ...(initialPrompt === undefined ? {} : { initialPrompt }) });
+}
+export const THREAD_HANDLERS = {
+    async 'agents computers'(ctx, values) {
+        const computers = await listComputers(ctx, str(values.path) ?? './');
+        const label = (t) => `${t.title || t.key} (${t.harness}, ${t.state.replace('_', ' ')})`;
+        out(ctx, computers.length ? table(['COMPUTER', 'STATE', 'THREADS'], computers.map(c => [c.workspace_key, c.state, c.conversations.map(label).join('; ')]))
+            : 'No computers to start a thread on. Start a conversation with shard ./ first.\n', { computers });
+        return 0;
+    },
+};

package/dist/wait-status.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Where a wait stands (0.16.0+): while a command waits on an operation whose start is queued for capacity, or a call
+ * waits for room (the workspace's host making room to wake it, or a free working slot of the plan), one line on stderr
+ * says so: the queue position, what the pool is doing (a new host starting, when it is expected) and until when the
+ * start holds its place. A line is printed only when it changes; dim on a terminal, plain when piped; never with
+ * --json, where stdout stays one document and stderr is left to the error.
+ */
+import type { ProgressEvent, ProgressListener, RetryRecord } from '@shardflux/sdk';
+import type { Writer } from './commands.js';
+/** `2026-10-09T21:40:12Z` as `21:40Z` (UTC); the input when it is not a timestamp. */
+export declare function clockZ(iso: string): string;
+/** A queued start in words: `queued for capacity (position 3): a new host is starting, ready by 21:40Z; it holds its place until 21:51Z`. */
+export declare function queueLine(e: Pick<Extract<ProgressEvent, {
+    type: 'phase';
+}>, 'queuePosition' | 'scaleOut' | 'expectedReadyBy' | 'deadlineAt'>): string;
+/** A call waiting to be admitted, in words. */
+export declare function admissionLine(r: Pick<RetryRecord, 'reason' | 'queuePosition'>): string;
+/**
+ * The client listener that prints where a wait stands. Silent with `json`. A phase other than capacity_pending ends
+ * the queue, so a later queue prints again.
+ */
+export declare function waitStatusListener(stderr: Writer, json: boolean): ProgressListener;

package/dist/wait-status.js

@@ -0,0 +1,59 @@
+/** `2026-10-09T21:40:12Z` as `21:40Z` (UTC); the input when it is not a timestamp. */
+export function clockZ(iso) {
+    const t = Date.parse(iso);
+    return Number.isFinite(t) ? `${new Date(t).toISOString().slice(11, 16)}Z` : iso;
+}
+/** A queued start in words: `queued for capacity (position 3): a new host is starting, ready by 21:40Z; it holds its place until 21:51Z`. */
+export function queueLine(e) {
+    const position = e.queuePosition ? ` (position ${e.queuePosition})` : '';
+    const pool = e.scaleOut === 'requested'
+        ? `: a new host is starting${e.expectedReadyBy ? `, ready by ${clockZ(e.expectedReadyBy)}` : ''}`
+        : e.scaleOut === 'clamped'
+            ? ': it starts as soon as a host has room'
+            : '';
+    const until = e.deadlineAt ? `; it holds its place until ${clockZ(e.deadlineAt)}` : '';
+    return `queued for capacity${position}${pool}${until}`;
+}
+/** A call waiting to be admitted, in words. */
+export function admissionLine(r) {
+    const position = r.queuePosition ? ` (position ${r.queuePosition})` : '';
+    if (r.reason === 'host_capacity')
+        return `waiting for room on the workspace's host${position}`;
+    if (r.reason === 'concurrent_workspaces')
+        return 'waiting for a free working slot: every workspace the plan lets work at once is busy';
+    return `waiting to be admitted${r.reason ? ` (${r.reason})` : ''}${position}`;
+}
+/**
+ * The client listener that prints where a wait stands. Silent with `json`. A phase other than capacity_pending ends
+ * the queue, so a later queue prints again.
+ */
+export function waitStatusListener(stderr, json) {
+    let last = null;
+    return (e) => {
+        if (json)
+            return;
+        let line;
+        if (e.type === 'retry') {
+            if (!e.retry.admission)
+                return;
+            line = admissionLine(e.retry);
+        }
+        else if (e.type === 'phase') {
+            if (e.phase !== 'capacity_pending') {
+                if (e.action !== 'tool')
+                    last = null;
+                return;
+            }
+            line = queueLine(e);
+        }
+        else {
+            if (e.action !== 'token' && e.action !== 'tool')
+                last = null;
+            return;
+        }
+        if (line === last)
+            return;
+        last = line;
+        stderr.write(stderr.isTTY ? `\x1b[2m· ${line}\x1b[0m\n` : `${line}\n`);
+    };
+}

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

@@ -0,0 +1,95 @@
+import type { Ctx, Handler } from './commands.js';
+import type { Conversation, LocalConversation } from './conversations.js';
+import { TwinLedger } from './worktree-twin.js';
+import type { LandingMode, TwinCell } from './worktree-twin.js';
+export interface TwinAgent {
+    id: string;
+    workspace_id: string;
+    state: 'working' | 'waiting' | 'exited';
+    since: string;
+}
+export type TwinConversation = Conversation & {
+    changes: {
+        files: number;
+        insertions: number;
+        deletions: number;
+        commits: number;
+        uncommitted: boolean;
+    };
+    landed: {
+        how: string;
+        ref: string;
+        at: string;
+    } | null;
+    summary: string;
+    name?: string;
+    join_mode?: string | null;
+    base_branch?: string | null;
+    last_activity_at?: string;
+    repo_remote?: string;
+};
+/** Its VM is gone: the conversation ended (archived after the retention window, or done). */
+export declare const ended: (c: TwinConversation) => boolean;
+export interface EngineDeps {
+    records(): LocalConversation[];
+    conversations(projectId: string): Promise<TwinConversation[]>;
+    agents(projectId: string): Promise<TwinAgent[]>;
+    /** The conversation's VM (woken when suspended), and its release; null when the VM is gone. */
+    cell(c: TwinConversation): Promise<{
+        cell: TwinCell;
+        close(): void;
+    } | null>;
+    /** A VM of the project that reads the project hub (an awake one, else the project's space reader). */
+    hubCell(projectId: string): Promise<{
+        cell: TwinCell;
+        close(): void;
+    }>;
+    /** Restores an ended conversation into a fresh VM (so its agent can resolve a conflict). */
+    resume(c: TwinConversation): Promise<void>;
+    land(c: TwinConversation, action: 'merge' | 'pr', into: string): Promise<void>;
+    message(c: TwinConversation, text: string): Promise<void>;
+    ledger: TwinLedger;
+    stateDir: string;
+    device: string;
+    log(line: string): void;
+    now(): number;
+    hub?: string;
+    vmTmp?: string;
+    quietMs?: number;
+}
+/** A turn ended with committed work only; the agent is not asking anything. */
+export declare function finished(c: TwinConversation, agents: TwinAgent[]): TwinAgent | 'state' | null;
+export declare function eligible(c: TwinConversation, ledger: TwinLedger, now: number): boolean;
+export declare function conflictMessage(into: string, files: string[]): string;
+export declare class TwinEngine {
+    #private;
+    constructor(deps: EngineDeps);
+    /** One pass over every project with a local conversation; returns the suggested wait before the next. */
+    tick(signal?: AbortSignal): Promise<number>;
+    /** Back online or awake: every conversation's retry backoff is cleared, so the next pass tries all of them. */
+    resetBackoff(): void;
+    landOne(c: TwinConversation, record: LocalConversation, mode: Exclude<LandingMode, 'off'>, agent: TwinAgent | null, signal?: AbortSignal): Promise<number | undefined>;
+}
+export interface LoopDeps {
+    tick(signal: AbortSignal): Promise<number>;
+    resetBackoff(): void;
+    sleep(ms: number, signal: AbortSignal): Promise<void>;
+    /** Wall-clock and monotonic milliseconds: the monotonic clock stands still while the computer sleeps. */
+    wall(): number;
+    mono(): number;
+    /** The computer's network addresses (any change is a network change). */
+    network(): string;
+    /** Whether the API host answers now (a TCP connect, no request). */
+    reachable(): Promise<boolean>;
+    log(line: string): void;
+}
+/**
+ * Runs the twin's passes. A failing pass (offline) backs off up to 5 minutes, but the wait ends at once when the
+ * computer wakes from sleep (the wall clock jumps past the monotonic one), when its network changes, or when the API
+ * host answers again (probed every 5 s while failing); every conversation's retry backoff is then cleared and a pass
+ * runs immediately. The first pass that succeeds after failures clears them too and runs again at once.
+ */
+export declare function runTwinLoop(deps: LoopDeps, signal: AbortSignal): Promise<void>;
+/** The device helper's twin. Nothing here asks the user anything. */
+export declare function runWorktreeTwin(ctx: Ctx, device: string, signal: AbortSignal): Promise<void>;
+export declare const TWIN_HANDLERS: Record<string, Handler>;