@shardflux/cli 0.20.0 → 0.22.0

package/dist/conversation-terminal.js

@@ -1,4 +1,6 @@
 import { linuxTerminalSession } from "./linux-terminal.js";
+import { resolve } from 'node:path';
+import { attachable, openShardInTerminal, reportTerminalOpen } from "./terminal-apps.js";
 import { randomUUID } from 'node:crypto';
 import { AgentStateStore } from "./agent-state.js";
 import { projectIdentity, projectLabels } from "./project-identity.js";
@@ -7,11 +9,12 @@ import { modelChoice } from "./agent-models.js";
 import { terminal } from "./agent-commands.js";
 import { cloudClaudeLogin, loginClaudeInWorkspace, requireClaudeTerminal } from "./claude-cloud-login.js";
 import { syncAgentCredentials } from "./agent-credentials.js";
-import { prepareProjectTemplate } from "./project-template-setup.js";
+import { labelConversationSetup, prepareProjectTemplate, readConversationSetup } from "./project-template-setup.js";
 import { projectWorkspacePath, seedAgentRepository } from "./agent-repository.js";
 import { syncAgentConfig, syncAgentConfigAfterStart } from "./agent-config-sync.js";
 import { savedMachine } from "./filesystem-state.js";
 import { ensureMenubar, MenubarManager } from "./menubar.js";
+import { ensureProjectGit } from "./project-git.js";
 import { UsageError } from "./errors.js";
 import { localResumeTerminal } from "./conversation-local-resume.js";
 import { agentReachability } from "./agent-reachability.js";
@@ -24,16 +27,21 @@ import { openClaudeDesktopSession, remoteControlUrl } from "./agent-target-comma
 import { openUrl } from "./browser.js";
 import { out } from "./commands.js";
 import { progress } from "./progress.js";
+import { seedPhase } from "./seed-phases.js";
 /** This computer's agent config, copied after the start; with a saved machine (which carries it) just the project memory. */
 const afterStartConfig = (ctx, ws, machine) => () => syncAgentConfigAfterStart(ctx, ws, machine ? { memoryOnly: true } : {});
-/** Every terminal entry point uses the durable conversation's native harness, worktree and session. */
-export async function conversationTerminal(ctx, ws, c, project, values, afterStart) {
+/**
+ * Every terminal entry point uses the durable conversation's native harness, worktree and session. A new conversation
+ * in a repository without a project template for its dependencies sets its worktree up once its agent has started
+ * (`setup`, 0.21.1+).
+ */
+export async function conversationTerminal(ctx, ws, c, project, values, afterStart, setup) {
     if (c.route === 'codex-cloud')
         return openCodexConversation(ctx, c);
     await restoreConversationBinding(ctx, c, ws);
     // 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 } : {}), choice: recordedChoice(c), ...(afterStart ? { afterStart } : {}) });
+    return terminal(ctx, ws, c.harness, conversationName(c), project, values, setup?.hash, c.worktree_path, { id: c.id, session: c.harness_session_id, title: c.title, ...(pty ? { pty } : {}), choice: recordedChoice(c), ...(afterStart ? { afterStart } : {}), ...(setup ? { setupLabelled: setup.labelled } : {}) });
 }
 /**
  * A conversation and its VM, for an app to open (Claude Desktop, claude.ai, T3 Code, the menu bar). A conversation
@@ -58,20 +66,58 @@ export async function reopenConversation(ctx, c, values) {
 /**
  * `shard ./` (and `agents new --in auto`): new conversations open where `agents targets` says (open_in, 0.17.0+): T3
  * Code mode, Claude Desktop or claude.ai for Claude (the conversation's Remote Control session), else this terminal.
+ * From a shell nobody types into (a coding agent's, or none) a terminal conversation opens in a new tab of the
+ * person's terminal app (0.20.1+, agents targets --terminal).
  */
 export const launchProjectCommand = async (ctx, values, [path = './', explicit]) => {
     const named = explicit ?? (values.claude === true ? 'claude' : values.codex === true ? 'codex' : undefined);
+    const typing = attachable(ctx.io), here = typing || ctx.json;
     if (values.resume !== true && values.review !== true) {
         const project = projectIdentity(path);
         const app = named === 'claude' || named === 'codex' ? named : new AgentStateStore(ctx.store.dir).app(project.remote ?? project.folder);
-        const where = process.platform === 'linux' && ctx.io.stdin.isTTY ? 'terminal' : openInChoices(ctx, project.slug)[app];
+        const where = process.platform === 'linux' && typing ? 'terminal' : openInChoices(ctx, project.slug)[app];
         if (where === 't3')
             return launchT3(ctx, values, path, app);
         if (values.on === undefined && app === 'claude' && (where === 'claude-desktop' || where === 'web'))
             return startConversation(ctx, values, [path, ...(explicit ? [explicit] : [])], where);
+        if (!here && where === 'terminal')
+            return projectInTerminalApp(ctx, values, path, named);
     }
+    else if (!here)
+        return projectInTerminalApp(ctx, values, path, named);
     return launchConversationProject(ctx, values, [path, ...(explicit ? [explicit] : [])]);
 };
+/** Flags `shard ./` hands to the terminal tab that runs it; files become absolute paths (the tab starts in the project). */
+const NOT_FORWARDED = new Set(['json', 'api-url', 'agent-label', 'wake', 'wake-timeout', 'help', 'version', 'timing', 'reachable', 'claude', 'codex']);
+export function forwardedFlags(values) {
+    const flags = [];
+    for (const [key, value] of Object.entries(values)) {
+        if (NOT_FORWARDED.has(key) || value === undefined)
+            continue;
+        for (const v of Array.isArray(value) ? value : [value]) {
+            if (v === true)
+                flags.push(`--${key}`);
+            else if (v === false)
+                flags.push(`--no-${key}`);
+            else if (typeof v === 'string') {
+                if ((key === 'prompt-file' || key === 'image') && v === '-')
+                    throw new UsageError(`--${key} - reads standard input, which a new terminal tab cannot: pass a file, or start it detached with --json.`);
+                flags.push(`--${key}`, key === 'prompt-file' || key === 'image' ? resolve(v) : v);
+            }
+        }
+    }
+    return flags;
+}
+/** `shard ./` with its flags in a new tab of the person's terminal app, in the project folder: the tab owns the start,
+ * any sign-in and the attach, as if the person typed it there. */
+async function projectInTerminalApp(ctx, values, path, app) {
+    const result = await openShardInTerminal(ctx, ['./', ...(app ? [app] : []), ...forwardedFlags(values)], { cwd: resolve(path) });
+    if (!result.opened) {
+        throw new UsageError(`shard ./ opens Claude Code or Codex in a terminal, and none opened here${result.reason ? `: ${result.reason.replace(/\.$/, '')}` : ''}.`, 'ask your user to run shard ./ in their own terminal, or start the conversation detached: shard ./ --json --prompt "<task>" (shard ./ codex --json ... for Codex)');
+    }
+    reportTerminalOpen(ctx, result);
+    return 0;
+}
 /** Select a durable conversation, then use the harness's native terminal for all interaction. */
 export const launchConversationProject = (ctx, values, args) => startConversation(ctx, values, args);
 async function startConversation(ctx, values, [path = './', explicit], openIn) {
@@ -114,17 +160,31 @@ async function startConversation(ctx, values, [path = './', explicit], openIn) {
     }
     if (app === 'codex' && !linuxTerminalSession(ctx, values))
         return launchCodexCloud(ctx, values, path, images);
-    await syncAgentCredentials(ctx.cloud(), { home: ctx.io.env.HOME, redact: value => ctx.addSecret(value) });
-    const signedIn = app === 'claude' ? await cloudClaudeLogin(ctx) : true;
-    if (!signedIn)
-        requireClaudeTerminal(ctx);
+    seedPhase('cli_start');
+    // Agent credentials and the Claude sign-in are checked beside the project's local work (its Git state and snapshot),
+    // and both pass before a VM is requested (0.21.1+).
+    const signIn = (async () => {
+        await syncAgentCredentials(ctx.cloud(), { home: ctx.io.env.HOME, redact: value => ctx.addSecret(value) });
+        const signed = app === 'claude' ? await cloudClaudeLogin(ctx) : true;
+        if (!signed)
+            requireClaudeTerminal(ctx);
+        seedPhase('claude_login');
+        return signed;
+    })();
+    signIn.catch(() => undefined);
+    // Whether this conversation sets the project up: hashed from the files it starts from (in a Git repository, as its VM
+    // reads them), and asked while its VM starts.
+    await ensureProjectGit(ctx, project.folder);
+    const setup = readConversationSetup(ctx, project);
+    seedPhase('project_git');
     let created;
     try {
-        created = await createConversation(ctx, project.folder, app, 'terminal', undefined, choice);
+        created = await createConversation(ctx, project.folder, app, 'terminal', undefined, choice, undefined, setup, signIn);
     }
     catch (e) {
         if (!conversationsUnavailable(e))
             throw e;
+        const signedIn = await signIn;
         // Optional migration: preserve the native terminal on the old control plane, without reviving main sync.
         const name = `c-${randomUUID().slice(0, 12)}`;
         const prepared = await prepareProjectTemplate(ctx, project, undefined);
@@ -142,6 +202,9 @@ async function startConversation(ctx, values, [path = './', explicit], openIn) {
         return terminal(ctx, ws, app, name, project.remote ?? project.folder, values, prepared.setupHash);
     }
     const { conversation: c, workspace: ws } = created;
+    const signedIn = await signIn;
+    const setupStart = labelConversationSetup(ctx, ws, c.worktree_path, await setup);
+    seedPhase('setup_label');
     if (values.computer === true)
         await ws.setComputerUse(true);
     await uploadInitialImages(ws.cell(), images, ctx.signal);
@@ -152,17 +215,18 @@ async function startConversation(ctx, values, [path = './', explicit], openIn) {
     // Without a saved machine the laptop's Claude and Codex config is copied in, after the agent has its first prompt.
     const afterStart = afterStartConfig(ctx, ws, !!(await savedMachine(ctx))?.template);
     await ensureMenubar(ctx.store.dir, ctx.apiUrl, new MenubarManager({ home: ctx.io.env.HOME, signal: ctx.signal }));
+    seedPhase('menubar');
     if (openIn) {
         // The agent starts detached in its VM; the conversation then opens in Claude Desktop or claude.ai (Remote Control).
         const quiet = { ...ctx, io: { ...ctx.io, stdout: { write: () => true } } };
-        await conversationTerminal(quiet, ws, c, project.remote ?? project.folder, { ...values, detach: true }, afterStart);
+        await conversationTerminal(quiet, ws, c, project.remote ?? project.folder, { ...values, detach: true }, afterStart, setupStart);
         if (openIn === 'claude-desktop')
             return openClaudeDesktopSession(ctx, ws, c);
         const url = await remoteControlUrl(ctx, ws, c);
-        if (!ctx.json && !openUrl(url, ctx.io.env))
+        if (!ctx.json && !(await openUrl(url, ctx.io.env)))
             throw new Error(`could not open ${url}`);
         out(ctx, `${url}\n`, { target: 'web', workspace: ws.data, conversation_id: c.id, url });
         return 0;
     }
-    return conversationTerminal(ctx, ws, c, project.remote ?? project.folder, values, afterStart);
+    return conversationTerminal(ctx, ws, c, project.remote ?? project.folder, values, afterStart, setupStart);
 }

package/dist/conversations.d.ts

@@ -1,6 +1,8 @@
 import type { CellClient, Workspace, WorkspaceView } from '@shardflux/sdk';
 import type { Ctx } from './commands.js';
+import type { LocalChanges } from './agent-repository.js';
 import type { ModelChoice } from './agent-models.js';
+import type { PreparedApply, PreparedTransfer } from './prepared-repository.js';
 export type Harness = 'claude' | 'codex';
 export interface Conversation {
     id: string;
@@ -62,6 +64,33 @@ export interface LocalConversation {
     handed_off?: boolean;
     /** The branch the conversation started from (0.16.0+), for APIs that do not return base_branch yet. */
     base_branch?: string;
+    /**
+     * The prepared revision this conversation starts from (0.22.0+): captured while its VM was allocated and kept until
+     * the start is done, so a start resumed after a deadline uses exactly that state. `deferred`: large files still
+     * following the first prompt.
+     */
+    preparation?: {
+        revision: string;
+        cache: string;
+        state: 'accepted' | 'syncing' | 'deferred' | 'ready' | 'error';
+        error?: string;
+        workspace?: string;
+        transfer?: PreparedTransfer;
+        apply?: PreparedApply;
+        pending?: string[];
+    };
+    cloud_start?: {
+        prompt?: string;
+        computer: boolean;
+        attachments_pending: boolean;
+        submitted?: boolean;
+        state: 'accepted' | 'active' | 'error';
+        error?: string;
+        /** When the process carrying this start last said so (carryStart): the device helper resumes only one nobody carries. */
+        heartbeat_at?: number;
+    };
+    /** Why this start left its prepared revision for the copy seed. */
+    preparation_fallback?: string;
 }
 /**
  * Whether the conversation has ended: its VM was reclaimed, or it was archived or discarded. A finished turn is `done`
@@ -95,14 +124,57 @@ export declare function restoreConversationBinding(ctx: Ctx, c: Conversation, ws
 export interface MovedInSession {
     session_id: string;
     title?: string;
+    preserveWorktrees?: boolean;
 }
-export declare function createConversationRecord(ctx: Ctx, folder: string, harness: Harness, route: Conversation['route'], name?: string, allocated?: (workspace: WorkspaceView) => void, idempotencyKey?: string, choice?: ModelChoice, movedIn?: MovedInSession): Promise<Conversation>;
+/**
+ * `ready`: checks the caller runs beside this local work (a sign-in check, 0.21.1+); the VM is requested only after
+ * they pass. The conversation API's availability is read meanwhile too.
+ */
+export declare function createConversationRecord(ctx: Ctx, folder: string, harness: Harness, route: Conversation['route'], name?: string, allocated?: (workspace: WorkspaceView) => void, idempotencyKey?: string, choice?: ModelChoice, movedIn?: MovedInSession, ready?: Promise<unknown>): Promise<Conversation>;
+/**
+ * Brings the conversation's accepted revision into its VM (0.22.0+): only what the project cache lacks is sent, and
+ * with `defer` large incompressible files follow the first prompt. Resumable: a later call (the device helper, or
+ * `shard agents open`) continues the same revision, never a newer checkout. False when the start has no revision.
+ */
+export declare function prepareAcceptedConversation(ctx: Ctx, c: Conversation, ws: Workspace, options?: {
+    defer?: boolean;
+    fallback?: boolean;
+    setup?: Promise<{
+        depsHash: string;
+    } | undefined>;
+}): Promise<boolean>;
+/**
+ * Sends a conversation's deferred large files and lands them in its worktree. Runs while its VM is awake (it never
+ * wakes one); the device helper retries until the start is whole.
+ */
+export declare function completeDeferredPreparation(ctx: Ctx, c: Conversation): Promise<boolean>;
+/**
+ * The one-time seed of a new conversation's worktree (a conversation never watches or writes the owner's checkout):
+ * its prepared revision (0.22.0+), or the copy seed when the start has none or the VM cannot take one. Repeatable: a
+ * start resumed after a deadline continues here.
+ */
+export declare function seedConversation(ctx: Ctx, c: Conversation, ws: Workspace, folder: string, movedIn?: MovedInSession & {
+    seedRepository?(ws: Workspace, c: Conversation): Promise<void>;
+}, changes?: Promise<LocalChanges>, setup?: Promise<{
+    depsHash: string;
+} | undefined>): Promise<void>;
 export declare function createConversation(ctx: Ctx, folder: string, harness: Harness, route: Conversation['route'], name?: string, choice?: ModelChoice, movedIn?: MovedInSession & {
     beforeSeed(ws: Workspace, c: Conversation): Promise<void>;
+    seedRepository?(ws: Workspace, c: Conversation): Promise<void>;
+}, setup?: Promise<{
+    depsHash: string;
+} | undefined>, ready?: Promise<unknown>, startup?: {
+    accepted(c: Conversation): void;
+    beforeSeed(ws: Workspace, c: Conversation): Promise<void>;
 }): Promise<{
     conversation: Conversation;
     workspace: Workspace;
 }>;
+/**
+ * The conversation branch, then the start state's snapshot, in one request (0.21.1+): a failed checkout fails the
+ * start, a failed snapshot only leaves it without one (recordSeedSnapshot). Its hub push stays detached in the VM.
+ */
+export declare function checkoutConversationBranch(ctx: Pick<Ctx, 'store' | 'signal'>, cell: Pick<CellClient, 'exec'>, c: Conversation): Promise<void>;
 export declare function resumeConversation(ctx: Ctx, c: Conversation): Promise<Conversation>;
 /** The model and effort a conversation's harness starts with, as its record keeps them. */
 export declare const recordedChoice: (c: Pick<Conversation, "model" | "effort">) => ModelChoice;

package/dist/conversations.js

@@ -4,13 +4,19 @@ import { AgentStateStore } from "./agent-state.js";
 import { gitRunner } from "./agent-git.js";
 import { projectIdentity } from "./project-identity.js";
 import { ensureProjectGit } from "./project-git.js";
-import { preflightProjectSeed, seedAgentRepository } from "./agent-repository.js";
-import { UsageError } from "./errors.js";
+import { localChanges, preflightProjectSeed, runGitStep, seedAgentRepository } from "./agent-repository.js";
+import { CodedError, UsageError } from "./errors.js";
 import { conversationClient } from "./conversation-commands.js";
-import { recordSeedSnapshot } from "./files-mirror.js";
+import { HUB_PATH, recordSeedSnapshot, SEED_SNAPSHOT } from "./files-mirror.js";
 import { rememberTwinSeed, sendTwinSeed, twinCheckoutArgv, twinSeed } from "./worktree-twin.js";
 import { progress } from "./progress.js";
 import { seedPhase, startProgress } from "./seed-phases.js";
+import { storedTitlePrefix } from "./client-settings.js";
+import { applyPreparedSnapshot, capturePreparedSnapshot, landDeferredFiles, preparedCachePath, preparedGitConfig, PreparedRefusal, pruneLocalPrepared, readPreparedSnapshot, releaseLocalSnapshot, transferPreparedSnapshot } from "./prepared-repository.js";
+import { withTargetLock } from "./target-lock.js";
+import { join } from 'node:path';
+import { acceptedProgress } from "./seed-phases.js";
+import { recordSetupIntent } from "./project-template-setup.js";
 /**
  * Whether the conversation has ended: its VM was reclaimed, or it was archived or discarded. A finished turn is `done`
  * while its VM still takes the next turn; on Codex Cloud, `done` ends the conversation.
@@ -68,7 +74,7 @@ export function rememberConversation(ctx, c, folder, handedOff = false, baseBran
     new AgentStateStore(ctx.store.dir).update(doc => {
         const records = doc.conversations ?? {};
         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 } : {}) };
+        records[c.id] = { ...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;
     });
 }
@@ -157,58 +163,273 @@ export async function restoreConversationBinding(ctx, c, ws) {
     if (c.restore.kind === 'resume')
         progress(ctx, 'Restored');
 }
-export async function createConversationRecord(ctx, folder, harness, route, name, allocated, idempotencyKey = randomUUID(), choice = {}, movedIn) {
+/**
+ * `ready`: checks the caller runs beside this local work (a sign-in check, 0.21.1+); the VM is requested only after
+ * they pass. The conversation API's availability is read meanwhile too.
+ */
+export async function createConversationRecord(ctx, folder, harness, route, name, allocated, idempotencyKey = randomUUID(), choice = {}, movedIn, ready) {
     const project = projectIdentity(folder);
     await ensureProjectGit(ctx, project.folder);
     // A start refuses before a VM is allocated, never after (0.19.0+).
     await preflightProjectSeed(project.folder, ctx.signal);
-    // Both the conversation API and its legacy workspace fallback need a usable local HEAD.
-    await conversationClient(ctx).conversations.list({ limit: 1 });
+    // Both the conversation API and its legacy workspace fallback need a usable local HEAD. The API's answer (a legacy
+    // control plane refuses) is awaited before the create, after the local snapshot it runs beside.
+    const probe = conversationClient(ctx).conversations.list({ limit: 1 }).then(() => undefined, (error) => ({ error }));
     const git = gitRunner(project.folder, { ...process.env, ...ctx.io.env }, ctx.signal);
     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 seed = movedIn?.preserveWorktrees ? { commit: head, snapshot: false }
+        : await twinSeed(ctx.store.dir, project.folder, head, ctx.store.profile(ctx.apiUrl).project_id).catch(() => ({ commit: head, snapshot: false }));
     seedPhase('local_snapshot');
+    const refused = await probe;
+    if (refused)
+        throw refused.error;
+    await ready;
+    seedPhase('api_probe');
     const commit = seed.commit;
+    // The prepared revision of that state (0.22.0+): its media and what Git does not hold (.env files, filter output),
+    // captured while the VM is requested and boots. A capture that cannot complete falls back to the copy seed, never fails
+    // the start. ACP sessions seed their own way (acp-models.ts).
+    const capture = movedIn || route === 'acp' ? Promise.resolve(undefined) : capturePreparedSnapshot(ctx.store.dir, project.folder, seed, project.remote, ctx.signal).catch((error) => {
+        if (ctx.signal.aborted)
+            throw error;
+        ctx.io.stderr.write(`Project snapshot: ${error instanceof Error ? error.message : String(error)}; copying the project instead.\n`);
+        return undefined;
+    });
+    capture.catch(() => undefined);
+    // The title marker this computer chose (`shard settings --title-prefix`, 0.20.1+); none sent means the platform's.
+    const titlePrefix = storedTitlePrefix(ctx.store.dir);
     const response = await conversationClient(ctx).conversations.create({ repoRemote: project.remote ?? `file://${project.folder}`, harness, route, mode: 'new',
         base: { commit, ...(branch ? { branch } : {}) }, ...(name ? { name } : {}), ...choice, projectId: ctx.store.profile(ctx.apiUrl).project_id,
+        ...(titlePrefix !== undefined ? { titlePrefix } : {}),
         ...(movedIn ? { harnessSessionId: movedIn.session_id, ...(movedIn.title ? { title: movedIn.title.slice(0, 200) } : {}) } : {}) }, { idempotencyKey, signal: ctx.signal });
     const c = validateConversation({ ...response.conversation, restore: response.restore });
     allocated?.(response.workspace);
     rememberTwinSeed(ctx.store.dir, c.id, project.folder, seed, branch);
     rememberConversation(ctx, c, project.folder, false, branch);
+    // The seed awaits the capture (prepareAcceptedConversation), so it runs on while the VM boots, with the Git settings
+    // the VM repository copies from this one.
+    pendingCaptures.set(c.id, capture.then(async (prepared) => {
+        if (!prepared)
+            return undefined;
+        new AgentStateStore(ctx.store.dir).update(doc => {
+            const record = doc.conversations[c.id];
+            if (record)
+                record.preparation = { revision: prepared.revision, cache: preparedCachePath(project.remote ?? `file://${project.folder}`), state: 'accepted' };
+        });
+        return { snapshot: prepared, git: await preparedGitConfig(project.folder, prepared.manifest, ctx.signal) };
+    }));
+    acceptedProgress(c.id, c.key);
     return c;
 }
-export async function createConversation(ctx, folder, harness, route, name, choice = {}, movedIn) {
+/** Captures still running for conversations this process created (createConversationRecord). */
+const pendingCaptures = new Map();
+/** A start the copy seed took over: its prepared revision is no longer this conversation's (recorded as the reason). */
+function dropPreparation(ctx, id, reason) {
+    new AgentStateStore(ctx.store.dir).update(doc => {
+        const record = doc.conversations[id];
+        if (record?.preparation) {
+            delete record.preparation;
+            record.preparation_fallback = reason;
+        }
+    });
+}
+function updatePreparation(ctx, id, patch) {
+    new AgentStateStore(ctx.store.dir).update(doc => {
+        const record = doc.conversations[id];
+        if (record?.preparation)
+            record.preparation = { ...record.preparation, ...patch };
+    });
+}
+const errorText = (error) => (error instanceof Error ? error.message : String(error)).slice(0, 2000);
+/** The template checkout a conversation outside it copies dependency folders from (a Codex Cloud worktree). */
+const templateCheckout = (c) => `/home/user/${c.key.split('/')[0]}`;
+/**
+ * Brings the conversation's accepted revision into its VM (0.22.0+): only what the project cache lacks is sent, and
+ * with `defer` large incompressible files follow the first prompt. Resumable: a later call (the device helper, or
+ * `shard agents open`) continues the same revision, never a newer checkout. False when the start has no revision.
+ */
+export async function prepareAcceptedConversation(ctx, c, ws, options = {}) {
+    const capturing = pendingCaptures.get(c.id);
+    let captured;
+    if (capturing) {
+        captured = await capturing.catch(() => undefined);
+        pendingCaptures.delete(c.id);
+        seedPhase('prepared_snapshot');
+    }
+    // The setup intent goes in the exec that checks the repository out, before the repository appears (0.22.0+).
+    const intent = await options.setup;
+    const local = localConversations(ctx)[c.id];
+    if (!local?.preparation)
+        return false;
+    if (local.preparation.state === 'ready' || local.preparation.state === 'deferred')
+        return true;
+    return withTargetLock(join(ctx.store.dir, 'prepared-starts', c.id), async () => {
+        const current = localConversations(ctx)[c.id]?.preparation;
+        if (!current)
+            return false;
+        if (current.state === 'ready' || current.state === 'deferred')
+            return true;
+        try {
+            updatePreparation(ctx, c.id, { state: 'syncing', error: undefined });
+            const fresh = captured?.snapshot.revision === current.revision ? captured : undefined;
+            const snapshot = fresh?.snapshot ?? await readPreparedSnapshot(ctx.store.dir, local.folder, current.revision);
+            const cell = ws.cell(), outside = c.worktree_path !== templateCheckout(c);
+            // The seed's copy to the project hub starts in the same exec as the checkout, detached (no extra round trip).
+            const target = { root: c.worktree_path, branch: c.branch, options: { signal: ctx.signal, adopt: true,
+                    git: fresh?.git ?? await preparedGitConfig(local.folder, snapshot.manifest, ctx.signal), ...(outside ? { dependencySource: templateCheckout(c) } : {}),
+                    after: { script: SEED_SNAPSHOT, args: [c.worktree_path, c.branch.replace(/^shard\//, ''), HUB_PATH, 'background'] },
+                    ...(intent ? { setupIntent: { conversation: c.id, depsHash: intent.depsHash } } : {}), workspace: ws.id } };
+            let transfer, apply;
+            try {
+                // A warm start: the probe checks the revision out in its own exec.
+                transfer = await transferPreparedSnapshot(cell, local.folder, current.cache, snapshot, { signal: ctx.signal, defer: options.defer ?? true, pin: c.id, apply: target });
+                seedPhase('prepared_transfer');
+                apply = transfer.applied ?? await applyPreparedSnapshot(cell, current.cache, current.revision, c.worktree_path, c.branch, { ...target.options, ...(transfer.complete ? { releasePin: c.id } : {}) });
+            }
+            catch (error) {
+                // No agent has this worktree yet: a VM that cannot take a prepared revision (a custom template without Python
+                // 3.11, say) still starts, through the copy seed, into a clean directory.
+                if (ctx.signal.aborted || !options.fallback || (error instanceof PreparedRefusal && error.reason === 'owned'))
+                    throw error;
+                ctx.io.stderr.write(`Project transfer: ${errorText(error)}; copying the project instead.\n`);
+                // The copy seed owns this start from here: nothing resumes the prepared one onto its worktree.
+                dropPreparation(ctx, c.id, errorText(error));
+                await releaseLocalSnapshot(local.folder, current.revision).catch(() => undefined);
+                // A fresh start leaves nothing at the path; a checkout taken over in place (a template's) is set aside.
+                await cell.exec.run(['sh', '-c', 'if [ -e "$1" ]; then mv "$1" "$1.unfinished-$(date +%s)"; fi', 'shard-seed', c.worktree_path], { timeoutMs: 30_000, signal: ctx.signal });
+                return false;
+            }
+            seedPhase('prepared_apply');
+            updatePreparation(ctx, c.id, { state: transfer.complete ? 'ready' : 'deferred', transfer, apply, pending: transfer.pending, error: undefined, workspace: ws.id });
+            if (transfer.complete)
+                await releaseLocalSnapshot(local.folder, current.revision);
+            return true;
+        }
+        catch (error) {
+            updatePreparation(ctx, c.id, { state: 'error', error: errorText(error) });
+            throw error;
+        }
+    }, ctx.signal);
+}
+/**
+ * Sends a conversation's deferred large files and lands them in its worktree. Runs while its VM is awake (it never
+ * wakes one); the device helper retries until the start is whole.
+ */
+export async function completeDeferredPreparation(ctx, c) {
+    const local = localConversations(ctx)[c.id];
+    if (local?.preparation?.state !== 'deferred' || conversationEnded(c))
+        return false;
+    return withTargetLock(join(ctx.store.dir, 'prepared-starts', c.id), async () => {
+        const current = localConversations(ctx)[c.id]?.preparation;
+        if (current?.state !== 'deferred')
+            return false;
+        let ws;
+        try {
+            ws = await conversationClient(ctx).workspaces.get(c.workspace_id);
+        }
+        catch (error) {
+            if (!(error instanceof ShardfluxApiError && error.status === 404))
+                throw error;
+        }
+        if (!ws || ws.data.deleted_at || (current.workspace && current.workspace !== c.workspace_id)) {
+            // The VM is gone (reclaimed, moved, deleted) or the conversation continues in another one (a resume restores its
+            // worktree there): there is no worktree left to complete.
+            updatePreparation(ctx, c.id, { state: 'error', error: 'The conversation\'s VM was removed before its media arrived.', pending: undefined });
+            await releaseLocalSnapshot(local.folder, current.revision);
+            return false;
+        }
+        if (!ws.ready)
+            return false;
+        const snapshot = await readPreparedSnapshot(ctx.store.dir, local.folder, current.revision);
+        const cell = ws.cell();
+        // Staged into the conversation's own repository and landed before this returns; the cache gets them after.
+        const transfer = await transferPreparedSnapshot(cell, local.folder, current.cache, snapshot, { signal: ctx.signal, pin: c.id,
+            apply: { root: c.worktree_path, branch: c.branch, options: { adopt: true } } });
+        // Media edited on this computer after the start never arrive as captured: the worktree goes on without them.
+        const drop = snapshot.manifest.files.filter(f => transfer.changed.includes(f.path)).map(f => f.oid);
+        const landed = await landDeferredFiles(cell, current.cache, current.revision, c.worktree_path, { signal: ctx.signal, drop });
+        if (landed.pending)
+            return false;
+        updatePreparation(ctx, c.id, { state: 'ready', transfer: { ...transfer, pending: current.pending ?? [] }, pending: undefined });
+        await releaseLocalSnapshot(local.folder, current.revision);
+        await pruneLocalPrepared(ctx.store.dir).catch(() => undefined);
+        return true;
+    }, ctx.signal);
+}
+/**
+ * The one-time seed of a new conversation's worktree (a conversation never watches or writes the owner's checkout):
+ * its prepared revision (0.22.0+), or the copy seed when the start has none or the VM cannot take one. Repeatable: a
+ * start resumed after a deadline continues here.
+ */
+export async function seedConversation(ctx, c, ws, folder, movedIn, changes, setup) {
+    // Requests the copy seed starts and nothing waits for (the history backfill's start), settled before this returns.
+    const background = [];
+    const cell = ws.cell();
+    // A conversation that sets its project up records it before its repository appears: its guest starts the agent as
+    // soon as the repository appears, then with the setup's context and toolchains (0.21.1+). A prepared start writes it
+    // in its checkout's exec; the copy seed beside its first request.
+    let recorded;
+    const recordIntent = () => recorded ??= (async () => {
+        const intent = await setup;
+        if (intent)
+            await recordSetupIntent(cell, c, intent.depsHash, ctx.signal).catch((error) => {
+                if (!ctx.signal.aborted)
+                    ctx.io.stderr.write(`The agent starts without the project setup context: ${error instanceof Error ? error.message : String(error)}\n`);
+            });
+    })();
+    if (movedIn?.seedRepository) {
+        void recordIntent();
+        await movedIn.seedRepository(ws, c);
+    }
+    else if (!await prepareAcceptedConversation(ctx, c, ws, { fallback: true, ...(setup ? { setup } : {}) })) {
+        await seedAgentRepository(ctx, ws, folder, { root: c.worktree_path, populate: true, changes: changes ?? localChanges(folder, ctx.signal),
+            background: started => background.push(started), beforeHistory: recordIntent() });
+    }
+    await recorded;
+    seedPhase('seed_done');
+    const preparation = localConversations(ctx)[c.id]?.preparation?.state, prepared = preparation === 'ready' || preparation === 'deferred';
+    if (!prepared && !movedIn?.preserveWorktrees) {
+        await sendTwinSeed(ctx.store.dir, cell, c, folder, ctx.signal);
+        seedPhase('twin_seed');
+        await checkoutConversationBranch(ctx, cell, c);
+        seedPhase('branch_checkout');
+    }
+    else if (!prepared) {
+        await recordSeedSnapshot(ws, c, ctx.signal);
+        seedPhase('seed_snapshot');
+    }
+    await Promise.all(background);
+    // Large media that follow the first prompt keep coming while this process runs; the device helper finishes them.
+    if (preparation === 'deferred')
+        void completeDeferredPreparation(ctx, c).catch(() => undefined);
+    // This computer's spool and snapshots stay bounded with no selected project to prune them (hourly at most).
+    void pruneLocalPrepared(ctx.store.dir, undefined, 3_600_000).catch(() => undefined);
+}
+export async function createConversation(ctx, folder, harness, route, name, choice = {}, movedIn, setup, ready, startup) {
     const project = projectIdentity(folder);
     seedPhase('start');
     // The launcher's phase line (SHARDFLUX_PROGRESS_FILE, 0.19.0+): a computer starts, then the seed's own marks move it on.
     startProgress(harness, ctx.io.env);
-    const c = await createConversationRecord(ctx, project.folder, harness, route, name, undefined, undefined, choice, movedIn);
+    const c = await createConversationRecord(ctx, project.folder, harness, route, name, undefined, undefined, choice, movedIn, ready);
+    startup?.accepted(c);
     seedPhase('conversation_create');
+    // A start without a prepared revision (a moved-in session) reads this computer's changes while its VM starts.
+    const changes = movedIn && !movedIn.seedRepository ? localChanges(project.folder, ctx.signal) : undefined;
+    changes?.catch(() => undefined);
     try {
         const ws = await conversationWorkspace(ctx, c);
         seedPhase('vm_running');
         // A moved-in session's transcript is in place before the repository: its guest resumes it once the seed is done.
         await movedIn?.beforeSeed(ws, c);
-        // 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();
-        seedPhase('seed_done');
-        await sendTwinSeed(ctx.store.dir, cell, c, project.folder, ctx.signal);
-        seedPhase('twin_seed');
-        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()}`);
-        seedPhase('branch_checkout');
-        await recordSeedSnapshot(ws, c, ctx.signal);
-        seedPhase('seed_snapshot');
+        await startup?.beforeSeed(ws, c);
+        await seedConversation(ctx, c, ws, project.folder, movedIn, changes, setup);
         return { conversation: c, workspace: ws };
     }
     catch (error) {
         // A failed move leaves nothing behind: its session can move again (the API counts only a live VM's move).
-        if (route === 'codex-cloud' || movedIn) {
+        if (movedIn) {
             try {
                 await ctx.cloud().workspaces.delete(c.workspace_id);
             }
@@ -216,9 +437,22 @@ export async function createConversation(ctx, folder, harness, route, name, choi
                 throw new AggregateError([error, cleanup], `Cloud setup failed; remove owned workspace ${c.workspace_id} before retrying.`, { cause: cleanup });
             }
         }
+        if (route === 'codex-cloud')
+            throw new CodedError('project_preparation_pending', `Accepted ${c.key}; project preparation can resume. Open this conversation to continue.`, `shard agents open ${c.id}`, { conversation_id: c.id, workspace_key: c.key, workspace_id: c.workspace_id, setup_state: localConversations(ctx)[c.id]?.preparation?.state ?? 'error' });
         throw error;
     }
 }
+const shellQuote = (s) => `'${s.replaceAll("'", "'\\''")}'`;
+/**
+ * The conversation branch, then the start state's snapshot, in one request (0.21.1+): a failed checkout fails the
+ * start, a failed snapshot only leaves it without one (recordSeedSnapshot). Its hub push stays detached in the VM.
+ */
+export async function checkoutConversationBranch(ctx, cell, c) {
+    const checkout = `${twinCheckoutArgv(ctx.store.dir, c).map(shellQuote).join(' ')} || exit 3\nsh -c "$1" shard-seed "$2" "$3" "$4" background >/dev/null || true`;
+    const result = await runGitStep(cell, ['sh', '-c', checkout, 'shard-seed', SEED_SNAPSHOT, c.worktree_path, c.branch.replace(/^shard\//, ''), HUB_PATH], { timeoutMs: 120_000, maxOutputBytes: 4096, signal: ctx.signal });
+    if (result.exitCode !== 0)
+        throw new Error(`Conversation branch could not be prepared: ${result.stderr.trim()}`);
+}
 export async function resumeConversation(ctx, c) {
     if (!conversationEnded(c))
         return getConversation(ctx, c.id);

package/dist/device-bridge.d.ts

@@ -63,7 +63,7 @@ export declare class DeviceGrants {
     allows(api: string, project: string, root: string, kind: string, outside: boolean): boolean;
     save(api: string, project: string, root: string, kind: string): Promise<void>;
 }
-export declare function deviceSummary(r: DeviceRequest): string;
+export declare function deviceSummary(r: DeviceRequest, platform?: NodeJS.Platform): string;
 /** Structured local approval details; the summary remains for older menu bar and ACP clients. */
 export declare function deviceApproval(r: DeviceRequest, c: Conversation, target: {
     path: string;