@shardflux/cli 0.20.0 → 0.23.0

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`
@@ -82,6 +111,9 @@ export declare function rememberConversation(ctx: Pick<Ctx, 'store' | 'apiUrl'>,
 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[]>;
+/** Resolve an open reference without using the local cwd or waking a VM. A conversation key survives a VM move;
+ * a computer key names its bound conversation. Legacy computers without that binding keep the workspace path. */
+export declare function conversationForOpen(ctx: Ctx, ref: string): Promise<Conversation | undefined>;
 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>;
@@ -95,14 +127,67 @@ 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>;
+/**
+ * Files of a conversation's prepared start still on their way (large media that follow the first prompt): an editor's
+ * file sync leaves them alone until they land, instead of sending them a second time.
+ */
+export declare function preparedInFlight(ctx: Pick<Ctx, 'store' | 'apiUrl'>, id: string): string[];
+/**
+ * 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>;
+    landNow?: boolean;
+}): 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>, editor?: {
+    initialFiles?: readonly string[];
+    onInitialFiles?: () => void;
+    landNow?: boolean;
+}): 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;
     });
 }
@@ -90,6 +96,41 @@ export async function listConversations(ctx, projectId) {
     } while (cursor);
     return all;
 }
+/** Resolve an open reference without using the local cwd or waking a VM. A conversation key survives a VM move;
+ * a computer key names its bound conversation. Legacy computers without that binding keep the workspace path. */
+export async function conversationForOpen(ctx, ref) {
+    if (/^conv_[a-z0-9]{26}$/.test(ref))
+        return getConversation(ctx, ref);
+    if (!ref.includes('/'))
+        return undefined;
+    const ws = await ctx.cloud().workspaces.findByKey(ref, { signal: ctx.signal });
+    if (ws) {
+        const id = ws.labels.shard_conversation;
+        if (!id)
+            return undefined;
+        try {
+            const c = await getConversation(ctx, id);
+            return c.workspace_id === ws.data.id ? c : undefined;
+        }
+        catch (error) {
+            if (conversationsUnavailable(error))
+                return undefined;
+            throw error;
+        }
+    }
+    let matches;
+    try {
+        matches = (await listConversations(ctx)).filter(c => c.key === ref);
+    }
+    catch (error) {
+        if (conversationsUnavailable(error))
+            return undefined;
+        throw error;
+    }
+    if (matches.length > 1)
+        throw new UsageError('Use the conversation id.');
+    return matches[0] ? getConversation(ctx, matches[0].id) : undefined;
+}
 export async function resolveConversation(ctx, ref, folder) {
     if (ref.startsWith('conv_'))
         return getConversation(ctx, ref);
@@ -157,58 +198,287 @@ 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. Every route but a moved-in session (its own worktrees) starts this way, editors' (ACP) too (0.22.0+).
+    const capture = movedIn ? 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) => {
+        seedPhase('capture_done');
+        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) {
+/**
+ * Files of a conversation's prepared start still on their way (large media that follow the first prompt): an editor's
+ * file sync leaves them alone until they land, instead of sending them a second time.
+ */
+export function preparedInFlight(ctx, id) {
+    const preparation = localConversations(ctx)[id]?.preparation;
+    return preparation?.state === 'deferred' ? preparation.pending ?? [] : [];
+}
+/** 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, ...(options.landNow ? { landNow: true } : {}) } };
+            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, editor = {}) {
+    // 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 } : {}), ...(editor.landNow ? { landNow: true } : {}) })) {
+        // A prepared worktree appears whole: an editor's agent settings are there with everything else.
+        editor.onInitialFiles?.();
+    }
+    else {
+        await seedAgentRepository(ctx, ws, folder, { root: c.worktree_path, populate: true, changes: changes ?? localChanges(folder, ctx.signal),
+            background: started => background.push(started), beforeHistory: recordIntent(),
+            ...(editor.initialFiles ? { initialFiles: editor.initialFiles } : {}), ...(editor.onInitialFiles ? { onInitialFiles: editor.onInitialFiles } : {}) });
+    }
+    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 +486,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/desktop-linux.js

@@ -1,6 +1,6 @@
 import { spawn, execFile } from 'node:child_process';
 import { createRequire } from 'node:module';
-import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, chmodSync, mkdtempSync } from 'node:fs';
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, chmodSync, mkdtempSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 import { promisify } from 'node:util';
@@ -19,6 +19,15 @@ export function linuxDesktopPackage(arch = process.arch) {
 }
 export function graphicalSession(env) { return !!(env.DISPLAY || env.WAYLAND_DISPLAY); }
 const desktopString = (text) => `"${text.replace(/(["`$\\])/g, '\\$1')}"`;
+// fnm's multishell aliases belong to the launching shell; the desktop and its autostart entry outlive it.
+function stableDesktopRuntime(runtime) {
+    try {
+        return { node: realpathSync(runtime.node), script: realpathSync(runtime.script) };
+    }
+    catch {
+        throw new UsageError('Open shard from its installed CLI to start the Shardflux window.');
+    }
+}
 export class LinuxDesktopManager {
     home;
     app;
@@ -117,6 +126,7 @@ export class LinuxDesktopManager {
             throw new UsageError('Install the window with npm i -g shardflux --include=optional, then run shard.');
         if (!graphicalSession(this.#env))
             throw new UsageError('Open shard from your desktop session to show the window.');
+        const stable = stableDesktopRuntime(runtime);
         const current = await this.status(dir);
         if (!current.version || (compareVersions(current.version, version) ?? -1) < 0) {
             if (existsSync(this.app) && (lstatSync(this.app).isSymbolicLink() || !current.version))
@@ -148,11 +158,14 @@ export class LinuxDesktopManager {
             }
         }
         mkdirSync(dir, { recursive: true, mode: 0o700 });
-        const env = { ...this.#env, SHARDFLUX_CONFIG_DIR: dir, SHARDFLUX_API_URL: api, SHARDFLUX_NODE: runtime.node, SHARDFLUX_CLI: runtime.script };
+        const env = { ...this.#env, SHARDFLUX_CONFIG_DIR: dir, SHARDFLUX_API_URL: api, SHARDFLUX_NODE: stable.node, SHARDFLUX_CLI: stable.script };
         const desktop = join(this.home, '.local/share/applications/dev.shardflux.Desktop.desktop');
         mkdirSync(dirname(desktop), { recursive: true });
-        const args = ['/usr/bin/env', `SHARDFLUX_CONFIG_DIR=${dir}`, `SHARDFLUX_API_URL=${api}`, `SHARDFLUX_NODE=${runtime.node}`, `SHARDFLUX_CLI=${runtime.script}`, join(this.app, 'shardflux-desktop')];
+        const args = ['/usr/bin/env', `SHARDFLUX_CONFIG_DIR=${dir}`, `SHARDFLUX_API_URL=${api}`, `SHARDFLUX_NODE=${stable.node}`, `SHARDFLUX_CLI=${stable.script}`, join(this.app, 'shardflux-desktop')];
         writeFileSync(desktop, `[Desktop Entry]\nType=Application\nName=Shardflux\nComment=Your agents, a shortcut away\nExec=${args.map(desktopString).join(' ')}\nIcon=${join(this.app, 'ui/assets/shardflux-icon.png')}\nTerminal=false\nCategories=Development;\nStartupWMClass=dev.shardflux.Desktop\n`, { mode: 0o644 });
+        const autostart = join(this.home, '.config/autostart/shardflux.desktop');
+        if (existsSync(autostart))
+            cpSync(desktop, autostart);
         if ((await this.status(dir)).running)
             await this.#exec(join(this.app, 'shardflux-desktop'), ['--control', view], { env, timeout: 5_000 });
         else {

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;

package/dist/device-bridge.js

@@ -14,6 +14,7 @@ import { UsageError } from "./errors.js";
 import { conversationClient } from "./conversation-commands.js";
 import { withTargetLock } from "./target-lock.js";
 import { checkConversationWorktree, rememberConversationWorktree } from "./conversation-worktree.js";
+import { yourComputer } from "./this-computer.js";
 const LIMIT = 256 << 20, OUTPUT = (192 << 10) - 128;
 const inside = (root, target) => target === root || target.startsWith(root + sep);
 const safeId = (value) => { if (!/^[a-zA-Z0-9_-]{1,96}$/.test(value))
@@ -67,14 +68,15 @@ export class DeviceGrants {
         });
     }
 }
-export function deviceSummary(r) {
+export function deviceSummary(r, platform = process.platform) {
+    const yours = yourComputer(platform);
     if (tryLocallyAction(r))
         return tryLocallyAction(r) === 'stop' ? 'Stop this conversation’s local sync and ports.' : 'Try this conversation in an isolated local worktree with two-way sync and localhost ports.';
     if (r.kind === 'exec')
-        return `Run on your Mac: ${JSON.stringify(r.exec?.argv)} · directory ${r.exec?.cwd_relative ?? '.'}`;
+        return `Run on ${yours}: ${JSON.stringify(r.exec?.argv)} · directory ${r.exec?.cwd_relative ?? '.'}`;
     if (r.files)
-        return `${r.kind === 'files_pull' ? 'Share with conversation' : 'Save on your Mac'}: ${r.files.local_path_relative} ↔ ${r.files.remote_path}`;
-    return `${r.kind === 'port_forward' ? 'Open conversation preview on your Mac' : 'Connect conversation to your Mac'}: ${r.port?.remote_port} ↔ localhost:${r.port?.local_port}`;
+        return `${r.kind === 'files_pull' ? 'Share with conversation' : `Save on ${yours}`}: ${r.files.local_path_relative} ↔ ${r.files.remote_path}`;
+    return `${r.kind === 'port_forward' ? `Open conversation preview on ${yours}` : `Connect conversation to ${yours}`}: ${r.port?.remote_port} ↔ localhost:${r.port?.local_port}`;
 }
 /** Structured local approval details; the summary remains for older menu bar and ACP clients. */
 export function deviceApproval(r, c, target, folder) {