@shardflux/cli 0.18.1 → 0.19.1

package/dist/agent-target-commands.js

@@ -277,10 +277,13 @@ export async function openDesktopWorkspace(ctx, ws, target, t3Version, prewarmed
     const targets = new AgentTargets(ctx.io.env, ctx.store.dir);
     const entry = (await (ws.labels.shard_router === 'project' ? targets.configureProject(ws.key, ctx.apiUrl, [target], ctx.signal) : targets.configure(ws.key, ctx.apiUrl, [target], false, ctx.signal))).find(e => e.workspace === ws.key);
     const instructions = target === 't3'
-        ? `Add environment → SSH → ${entry.host} (${agentMachineName(ws.key)}), then open ${projectWorkspacePath({ slug: entry.project })}.`
+        ? '' // T3 Code: where the project is comes from its T3 Connect link (t3Line), set below.
         : target === 'claude-desktop'
             ? `Restart Claude Desktop to load the connection, then choose ${targetLabel(entry)} in Code's environment dropdown and open ${projectWorkspacePath({ slug: entry.project })}.`
             : `Restart Codex to import ${entry.host} and its remote project. If it has already been imported, enable ${entry.host} in Settings → Connections → SSH.`;
+    // T3 Code: the project is linked with the person's T3 Connect sign-in first, then the thread starts in it.
+    const fresh = target === 't3' && !new AgentStateStore(ctx.store.dir).t3Environments(ctx.apiUrl).some(e => e.workspace === ws.key);
+    let phone = target === 't3' ? await linkT3Phone(ctx, ws) : undefined;
     let started;
     if (target === 't3' && thread) {
         try {
@@ -290,10 +293,15 @@ export async function openDesktopWorkspace(ctx, ws, target, t3Version, prewarmed
             throw withT3Context(error, { workspace_key: ws.key, conversation_id: conversation ?? (ws.labels.shard_conversation || null) });
         }
     }
+    // The first time a project is set up for T3 Code, T3 opens on its Connections page once the project is linked: the
+    // project is listed there (or T3's own Sign in to T3 Connect, when T3 Code is signed out).
     if (target === 't3') {
+        if (fresh && phone?.link.status === 'linking')
+            phone = await waitT3Linked(ctx, ws, phone);
+        const page = fresh && phone?.link.status === 'linked' ? T3_CONNECTIONS_PAGE : undefined;
         // The thread exists once startSshThread returns: a failure to show T3 names it rather than inviting a retry.
         try {
-            await openT3(ctx.io.env, install ?? t3Install(ctx.io.env));
+            await openT3(ctx.io.env, install ?? t3Install(ctx.io.env), page);
         }
         catch (error) {
             throw started ? t3OpenFailed(error, { t3_thread_id: started.t3_thread_id, conversation_id: conversation ?? (ws.labels.shard_conversation || null), workspace_key: ws.key }) : error;
@@ -304,35 +312,57 @@ export async function openDesktopWorkspace(ctx, ws, target, t3Version, prewarmed
     new AgentStateStore(ctx.store.dir).saveTarget(ws.labels.repo_remote || ws.labels.shard_project || entry.project, target);
     if (target === 't3')
         new AgentStateStore(ctx.store.dir).saveT3Environment({ workspace: ws.key, host: entry.host, api_url: ctx.apiUrl });
-    const phone = target === 't3' ? await linkT3Phone(ctx, ws) : undefined;
+    const where = target === 't3' ? phone?.line ?? `${targetLabel(entry)} is set up for T3 Code.\n` : '';
     const threadLine = started ? `Started a thread in T3 Code on ${agentMachineName(ws.key)}${started.model ? ` (${started.model}${started.effort ? `, ${started.effort}` : ''})` : ''}.\n` : '';
-    out(ctx, `${threadLine}${instructions}\n${phone?.line ?? ''}`, { target, workspace: ws.data, host: entry.host, instructions, ...(phone ? { t3_link: phone.link } : {}),
+    out(ctx, target === 't3' ? `${threadLine}${where}` : `${threadLine}${instructions}\n`, { target, workspace: ws.data, host: entry.host, instructions: target === 't3' ? where.trim() : instructions, ...(phone ? { t3_link: phone.link } : {}),
         ...(target === 't3' ? t3Fields(ws, entry.project, install ?? t3Install(ctx.io.env), started, conversation) : {}),
         app_bundle_id: { 'claude-desktop': 'com.anthropic.claudefordesktop', 'codex-app': 'com.openai.codex', t3: 'com.t3tools.t3code' }[target] });
     return 0;
 }
+/** T3 Code's Connections page (its t3code:// link), where a project linked with T3 Connect is listed. */
+export const T3_CONNECTIONS_PAGE = 't3code://app/settings/connections';
 /**
- * The T3 app on the phone reaches this workspace through the account's T3 Connect sign-in (0.17.0+). The sign-in is
- * asked for once per person; linking continues by itself once it is approved.
+ * T3 Code and the T3 app reach this workspace through the account's T3 Connect sign-in (0.17.0+; on the desktop
+ * 0.19.0+). The sign-in is asked for once per person; linking continues by itself once it is approved.
  */
 async function linkT3Phone(ctx, ws) {
     try {
         const { link, signIn, needsLogin } = await t3PhoneLink(ctx, ws.id);
-        const line = signIn
-            ? `Phone: to use ${link.label} from the T3 app, open ${signIn.verification_uri} and confirm ${signIn.user_code} (once).\n`
-            : needsLogin ? `Phone: to use ${link.label} from the T3 app, sign in with shard auth login, then run this again.\n`
-                : `Phone: ${link.label} appears in the T3 app's environments.\n`;
-        // --json carries the sign-in shard started with its session too, so the menu bar can show it.
-        return { line, link: signIn ? { ...link, sign_in: { ...link.sign_in, ...signIn } } : needsLogin ? { ...link, needs_login: true } : link };
+        return { line: t3LinkLine(link, signIn, needsLogin), link: signIn ? { ...link, sign_in: { ...link.sign_in, ...signIn } } : needsLogin ? { ...link, needs_login: true } : link };
     }
     catch (error) {
-        // An API without T3 Connect leaves the desktop route as it is.
+        // An API without T3 Connect leaves the project set up for T3 Code over SSH.
         if (describeError(error).code === 'not_found')
             return undefined;
-        ctx.io.stderr.write(`Phone link: ${describeError(error).message}\n`);
+        ctx.io.stderr.write(`T3 Connect: ${describeError(error).message}\n`);
         return undefined;
     }
 }
+const t3LinkLine = (link, signIn, needsLogin) => signIn
+    ? `To have ${link.label} appear in T3 Code and the T3 app, open ${signIn.verification_uri} and confirm ${signIn.user_code} (once).\n`
+    : needsLogin ? `To have ${link.label} appear in T3 Code and the T3 app, sign in with shard auth login, then run this again.\n`
+        : link.status === 'linked' ? `${link.label} is linked to your T3 account.\n`
+            : `Linking ${link.label} to your T3 account…\n`;
+/** A project linking for the first time: T3 lists it once linked, so its Connections page waits for that (at most 20 s). */
+async function waitT3Linked(ctx, ws, phone) {
+    const until = Date.now() + 20_000;
+    while (Date.now() < until && !ctx.signal?.aborted) {
+        await delay(2000);
+        try {
+            const known = (await ctx.cloud().t3.status()).links.find(l => l.workspace_id === ws.id);
+            if (known?.status === 'linked') {
+                const link = { ...phone.link, status: 'linked' };
+                return { line: t3LinkLine(link), link };
+            }
+            if (known && known.status !== 'linking')
+                return phone;
+        }
+        catch {
+            return phone;
+        }
+    }
+    return phone;
+}
 export async function queueT3Prewarm(ctx, ws, version) {
     try {
         await prewarmT3(ctx, ws, version);
@@ -348,7 +378,7 @@ function configuredTargets(targets, e, t3 = false) {
         { target: 'ssh', label: 'SSH', file: targets.sshFile, name: e.host, detail: `(included from ${tilde(targets, join(targets.home, '.ssh', 'config'))}): ssh ${e.host}` },
         ...(e.targets.includes('claude-desktop') ? [{ target: 'claude-desktop', label: 'Claude Desktop', file: targets.claudeFile, name: targetLabel(e), detail: `(sshConfigs: ${targetLabel(e)}); restart Claude Desktop, then pick it in Code's environment list` }] : []),
         ...(e.targets.includes('codex-app') ? [{ target: 'codex-app', label: 'Codex app', file: targets.codexFile, name: targetLabel(e), detail: `(remoteConnections: ${targetLabel(e)}); restart Codex to import it` }] : []),
-        ...(t3 ? [{ target: 't3', label: 'T3 Code', file: targets.sshFile, name: agentMachineName(e.workspace), detail: `Add environment → SSH → ${e.host}; project ${projectWorkspacePath({ slug: e.project })}` }] : []),
+        ...(t3 ? [{ target: 't3', label: 'T3 Code', file: targets.sshFile, name: agentMachineName(e.workspace), detail: `SSH host ${e.host}; project ${projectWorkspacePath({ slug: e.project })}; in T3 Code and the T3 app through T3 Connect` }] : []),
     ];
 }
 function targetFiles(targets, entries) {

package/dist/args.d.ts

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

package/dist/args.js

@@ -13,7 +13,7 @@ import { parseArgs } from 'node:util';
 import { ACCOUNT_COMMANDS } from "./account-args.js";
 import { UsageError } from "./errors.js";
 import { DEFAULT_CHOICE, MODEL_CHOICES } from "./agent-models.js";
-export const CLI_VERSION = '0.18.1';
+export const CLI_VERSION = '0.19.1';
 export const GLOBAL_OPTIONS = {
     'api-url': { type: 'string', value: '<url>', description: 'API base URL (default $SHARDFLUX_API_URL, else https://api.shardflux.dev).' },
     json: { type: 'boolean', description: 'Print machine-readable JSON on stdout (errors as JSON on stderr).' },
@@ -1252,6 +1252,17 @@ export const CENTER_COMMAND = { path: ['<center>'], summary: 'Open the cloud age
 /** Bare `shard` without a terminal, or in a coding agent's shell (0.17.1+): the setup question and both paths' steps. */
 export const GUIDE_COMMAND = { path: ['<guide>'], summary: 'Show how to set up Shardflux with a coding agent', positionals: [], options: {} };
 const AGENT_COMMANDS = [
+    { path: ['move'], summary: 'Move a Claude Code or Codex session from this computer to the cloud: the same session, with its history',
+        description: 'Run it in the project folder. The session continues in its own cloud VM as the same session (claude --resume, codex resume), from your project exactly as it is, uncommitted edits included; your working tree, index and branch stay as they are. A running turn finishes here first. The cloud work comes back to this folder by itself, and typing in the local copy says it now continues in the cloud. Sessions from Claude Desktop and the Codex app move the same way.',
+        positionals: [], options: {
+            last: { type: 'boolean', description: 'This project’s most recent session.' },
+            session: { type: 'string', value: '<id>', description: 'The session to move: a Claude Code session id or Codex thread id.' },
+            path: { type: 'string', value: '<path>', description: 'The project folder (default: the current folder).' },
+            claude: { type: 'boolean', description: 'With --last or --list: Claude Code sessions only.' },
+            codex: { type: 'boolean', description: 'With --last or --list: Codex sessions only.' },
+            list: { type: 'boolean', description: 'List this project’s sessions on this computer, and where the moved ones continue.' },
+            detach: { type: 'boolean', description: 'Start it in the cloud without opening it here.' },
+        }, examples: ['shard move --last', 'shard move --list', 'shard move --session 3d085e35-aa66-4866-9a53-f09719d6767c --detach --json'] },
     { path: ['device', 'requests'], summary: 'Review local device requests waiting for approval', positionals: [], options: {} },
     ...['approve', 'deny'].map((action) => ({ path: ['device', action], summary: `${action} a local device request`, positionals: [{ name: 'id', required: true }], options: action === 'approve' ? { always: { type: 'boolean', description: 'Allow matching requests for this project; never for outside-folder access.' } } : {} })),
     { path: ['conversations', 'try'], summary: 'Try a conversation in a synced local worktree', positionals: [{ name: 'conversation', required: true }], options: { path: { type: 'string', value: '<path>', description: 'Local project checkout.' }, stop: { type: 'boolean', description: 'Stop the device helper’s local sync and ports.' } } },
@@ -1288,6 +1299,7 @@ const AGENT_COMMANDS = [
         } },
     { path: ['agents', 'fork'], summary: 'Fork an agent’s memory and disk', positionals: [{ name: 'agent', required: true }, { name: 'name', required: true }], options: WAIT },
     { path: ['agents', 'park'], summary: 'Suspend an agent when idle', positionals: [{ name: 'agent', required: true }], options: { 'when-idle': { type: 'string', value: '<duration>', description: 'Idle grace before suspend (default 1s).' } } },
+    { path: ['agents', 'config-sync'], hidden: true, summary: 'Copy this computer’s Claude and Codex config into a conversation VM (started in the background after a start, 0.19.0+)', positionals: [{ name: 'workspace', required: true }], options: {} },
     { path: ['agents', 'logs'], summary: 'Tail an agent’s terminal from its output offset: a conversation id (0.18.1+) or an agent workspace key', positionals: [{ name: 'agent', required: true }], options: {
             app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default remembered choice; a conversation uses its own).' },
             offset: { type: 'string', value: '<bytes>', description: 'Read from this output byte offset (default last 64 KiB).' },
@@ -1719,7 +1731,7 @@ export const EXIT_CODE_HELP = [
 /** The top help's sections: every command's group (first word) is in exactly one (args.test.ts checks). */
 export const HELP_SECTIONS = [
     { title: 'Account (a user session: shard signup or shard auth login)', groups: ['signup', 'verify', 'auth', 'setup', 'env', 'orgs', 'projects', 'api-keys', 'members', 'invitations', 'billing', 'audit', 'account'] },
-    { title: 'Cloud agents (shard ./ starts one; a project API key)', groups: ['conversations', 'machine', 'template', 'agents', 'accounts', 'device', 'cli-proxy', 'ssh-proxy'] },
+    { title: 'Cloud agents (shard ./ starts one; a project API key)', groups: ['conversations', 'move', 'machine', 'template', 'agents', 'accounts', 'device', 'cli-proxy', 'ssh-proxy'] },
     { title: 'Workspaces for your app (a project API key: SHARDFLUX_API_KEY, else the one shard setup saved)', groups: ['login', 'whoami', 'status', 'usage', 'workspaces', 'files', 'operations', 'executions', 'secrets', 'credentials', 'volumes', 'egress'] },
     { title: 'Templates for your app’s workspaces (not for cloud agents; publish and archive use the session, the rest the API key)', groups: ['templates'] },
     { title: 'Other', groups: ['menubar', 'update', 'feedback', 'version'] },

package/dist/conversation-router.js

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { ShardfluxApiError } from '@shardflux/sdk';
-import { workspaceRepositoryPath, projectWorkspacePath, HISTORY_BUNDLE_LIMIT } from "./agent-repository.js";
-import { writeSyncBlob } from "./project-sync-transfer.js";
+import { workspaceRepositoryPath, projectWorkspacePath } from "./agent-repository.js";
+import { copySyncBlob } from "./project-sync-transfer.js";
 import { UsageError } from "./errors.js";
 import { conversationClient } from "./conversation-commands.js";
 export const ROUTER_CONFIG = '/home/user/.config/shardflux/conversation-router.json';
@@ -58,18 +58,14 @@ export async function prepareDesktopRouter(ctx, source) {
     const archive = `/tmp/shard-router-${randomUUID()}.bundle`;
     try {
         if (created) {
-            const packed = await cell.exec.run(['git', '-C', workspaceRepositoryPath(source), '-c', 'core.hooksPath=/dev/null', 'bundle', 'create', archive, 'HEAD'], { timeoutMs: 120_000, signal: ctx.signal });
+            const packed = await cell.exec.run(['git', '-C', workspaceRepositoryPath(source), '-c', 'core.hooksPath=/dev/null', 'bundle', 'create', archive, 'HEAD'], { timeoutMs: 600_000, signal: ctx.signal });
             if (packed.exitCode !== 0)
                 throw new Error(`Project router seed failed: ${packed.stderr.trim()}`);
-            const info = await cell.files.stat(archive);
-            if (info.size > HISTORY_BUNDLE_LIMIT)
-                throw new UsageError('Project router history exceeds the 256 MiB transfer bound.');
-            const bytes = await cell.files.read(archive, { length: info.size + 1 });
-            if (bytes.length !== info.size)
-                throw new Error('Project router history changed during copying.');
-            await writeSyncBlob(destination, archive, bytes);
+            // Any history size: the bundle goes VM to VM one chunk at a time, and the import may take a second per 8 MiB.
+            const { size } = await cell.files.stat(archive);
+            await copySyncBlob(cell, archive, size, destination, archive, ctx.signal);
             await destination.files.mkdir(root, { parents: true });
-            const imported = await destination.exec.run(['sh', '-c', 'set -eu; git -C "$1" init -q; git -C "$1" -c core.hooksPath=/dev/null fetch -q "$2" HEAD:refs/heads/shardflux-router; git -C "$1" -c core.hooksPath=/dev/null checkout -q shardflux-router', 'sh', root, archive], { timeoutMs: 120_000, signal: ctx.signal });
+            const imported = await destination.exec.run(['sh', '-c', 'set -eu; git -C "$1" init -q; git -C "$1" -c core.hooksPath=/dev/null fetch -q "$2" HEAD:refs/heads/shardflux-router; git -C "$1" -c core.hooksPath=/dev/null checkout -q shardflux-router', 'sh', root, archive], { timeoutMs: 120_000 + Math.ceil(size / (8 << 20)) * 1000, signal: ctx.signal });
             if (imported.exitCode !== 0)
                 throw new Error(`Project router repository could not be prepared: ${imported.stderr.trim()}`);
         }

package/dist/conversation-stash.js

@@ -1,13 +1,16 @@
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { closeSync, constants, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { open, rename, rm } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { conversationName, listConversations, localConversations, rememberConversation } from "./conversations.js";
 import { gitRunner } from "./agent-git.js";
 import { shardRemote } from "./git-remote.js";
 import { writePrivateFile } from "./credentials.js";
 import { conversationClient } from "./conversation-commands.js";
-const MAX = 64 << 20; // Guest FileManifest uses the project-sync 64 MiB per-file bound.
+import { movedSession, movedUnchanged } from "./moved-sessions.js";
+import { claudeProjectName } from "./local-sessions.js";
+import { remoteManifest, SYNC_CHUNK_BYTES } from "./project-sync-transfer.js";
 export function rewriteTranscript(bytes, remoteCwd, localCwd) {
     const text = new TextDecoder('utf8', { fatal: true }).decode(bytes);
     const rewrite = (value) => {
@@ -30,7 +33,7 @@ export function transcriptDestination(c, folder, filename, env) {
         throw new Error('Transcript filename is not a native JSONL file.');
     const home = env.HOME || homedir();
     if (c.harness === 'claude')
-        return join(env.CLAUDE_CONFIG_DIR || join(home, '.claude'), 'projects', resolve(folder).replace(/[^a-zA-Z0-9]/g, '-'), filename);
+        return join(env.CLAUDE_CONFIG_DIR || join(home, '.claude'), 'projects', claudeProjectName(resolve(folder)), filename);
     const match = /^rollout-(\d{4})-(\d{2})-(\d{2})T/.exec(filename);
     if (!match)
         throw new Error('Codex transcript has no native rollout date.');
@@ -61,6 +64,43 @@ function readStashFile(file) {
         closeSync(fd);
     }
 }
+/**
+ * Copies one transcript into the stash in SYNC_CHUNK_BYTES reads (any size, never whole in memory): checked as UTF-8
+ * and against the manifest hash on the way, written private (0600) next to its destination and renamed into place.
+ */
+async function copyTranscript(cell, path, entry, dir, file, signal) {
+    const tmp = join(dir, `.${entry.path}.${randomUUID()}.tmp`);
+    try {
+        const fd = await open(tmp, 'wx', 0o600);
+        try {
+            const hash = createHash('sha256'), utf8 = new TextDecoder('utf8', { fatal: true });
+            for (let offset = 0; offset < entry.size;) {
+                signal.throwIfAborted();
+                const want = Math.min(SYNC_CHUNK_BYTES, entry.size - offset);
+                // A read below the gateway's per-read cap returns what was asked unless the file shrank.
+                const chunk = await cell.files.read(path, { offset, length: want });
+                if (chunk.length !== want)
+                    throw new Error('Transcript changed during copying; retaining the previous stash.');
+                hash.update(chunk);
+                utf8.decode(chunk, { stream: true });
+                for (let at = 0; at < chunk.length;)
+                    at += (await fd.write(chunk, at, chunk.length - at, offset + at)).bytesWritten;
+                offset += chunk.length;
+            }
+            utf8.decode();
+            if (hash.digest('hex') !== entry.sha256)
+                throw new Error('Transcript changed during copying; retaining the previous stash.');
+            await fd.sync();
+        }
+        finally {
+            await fd.close();
+        }
+        await rename(tmp, file);
+    }
+    finally {
+        await rm(tmp, { force: true });
+    }
+}
 /** Keep growing copies away from native session discovery until the control plane ends the conversation. */
 export async function mirrorConversation(ctx, record, source, skipped = new Set()) {
     const c = record.conversation;
@@ -85,7 +125,8 @@ export async function mirrorConversation(ctx, record, source, skipped = new Set(
     ctx.signal.addEventListener('abort', close, { once: true });
     try {
         ctx.signal.throwIfAborted();
-        const manifest = await cell.files.manifest(root, { maxFileBytes: MAX, signal: ctx.signal });
+        // Transcripts of any size: no per-file bound (an older guest's size skips are hashed in the VM).
+        const manifest = await remoteManifest(cell, root, undefined, ctx.signal);
         for (const entry of manifest.skipped)
             skip(entry.path, entry.reason);
         let count = 0;
@@ -98,8 +139,8 @@ export async function mirrorConversation(ctx, record, source, skipped = new Set(
                 skip(entry.path, 'not a safe top-level JSONL or JSON file');
                 continue;
             }
-            if (!Number.isSafeInteger(entry.size) || entry.size < 0 || entry.size > MAX) {
-                skip(entry.path, 'outside the 64 MiB mirror bound');
+            if (!Number.isSafeInteger(entry.size) || entry.size < 0) {
+                skip(entry.path, 'invalid size');
                 continue;
             }
             try {
@@ -109,12 +150,8 @@ export async function mirrorConversation(ctx, record, source, skipped = new Set(
                     continue;
                 }
                 const expected = existing ? createHash('sha256').update(readStashFile(file)).digest('hex') : '';
-                if (expected !== entry.sha256) {
-                    const bytes = await cell.files.read(`${root}/${entry.path}`, { length: entry.size + 1 });
-                    if (bytes.length !== entry.size || createHash('sha256').update(bytes).digest('hex') !== entry.sha256)
-                        throw new Error('Transcript changed during copying; retaining the previous stash.');
-                    writePrivateFile(dir, file, new TextDecoder('utf8', { fatal: true }).decode(bytes));
-                }
+                if (expected !== entry.sha256)
+                    await copyTranscript(cell, `${root}/${entry.path}`, entry, dir, file, ctx.signal);
             }
             catch (e) {
                 throw new Error(`Entry ${JSON.stringify(entry.path)}: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
@@ -148,10 +185,16 @@ export async function handoffConversation(ctx, c, folder, dir, source) {
     const files = readdirSync(dir).filter(f => !f.includes('..') && /^[a-zA-Z0-9_.-]+\.jsonl$/.test(f) && lstatSync(join(dir, f)).isFile());
     if (!files.length)
         throw new Error('Conversation has no transcript to hand off.');
-    const writes = files.map(name => ({ dest: transcriptDestination(c, folder, name, ctx.io.env), bytes: rewriteTranscript(readStashFile(join(dir, name)), c.worktree_path, folder) }));
+    // A session moved in from this computer (`shard move`) comes back to the file it left; it replaces that local copy only
+    // while the copy holds exactly what moved (nobody continued it here meanwhile).
+    const moved = c.harness_session_id ? movedSession(ctx.store.dir, ctx.apiUrl, c.harness, c.harness_session_id) : undefined;
+    const writes = files.map(name => {
+        const dest = moved && name === basename(moved.file) ? moved.file : transcriptDestination(c, folder, name, ctx.io.env);
+        return { dest, bytes: rewriteTranscript(readStashFile(join(dir, name)), c.worktree_path, folder), replace: !!moved && dest === moved.file && movedUnchanged(moved) };
+    });
     // Check every destination before the first write. Preserve local native history on any collision.
-    for (const { dest, bytes } of writes) {
-        if (existsSync(dest) && (lstatSync(dest).isSymbolicLink() || !readFileSync(dest).equals(Buffer.from(bytes))))
+    for (const { dest, bytes, replace } of writes) {
+        if (existsSync(dest) && (lstatSync(dest).isSymbolicLink() || (!replace && !readFileSync(dest).equals(Buffer.from(bytes)))))
             throw new Error(`Native transcript already exists with different bytes: ${dest}`);
     }
     if (!source)
@@ -160,9 +203,12 @@ export async function handoffConversation(ctx, c, folder, dir, source) {
     const run = gitRunner(folder, { ...process.env, ...ctx.io.env, SHARDFLUX_CONFIG_DIR: ctx.store.dir, SHARDFLUX_API_URL: ctx.apiUrl }, ctx.signal);
     const hub = 'hub' in source ? source.hub : shardRemote(source.key, '/shardflux/project/git/hub.git');
     await run(['-c', 'core.hooksPath=/dev/null', 'fetch', '--no-tags', hub, `+${c.state === 'archived' ? `refs/shard/archive/${name}` : `refs/heads/${c.branch}`}:refs/remotes/shardflux/${name}`]);
-    for (const { dest, bytes } of writes) {
+    for (const { dest, bytes, replace } of writes) {
         privateDirectory(dirname(dest));
-        if (!existsSync(dest))
+        // The local copy it replaces stays in the stash.
+        if (replace && existsSync(dest) && !readFileSync(dest).equals(Buffer.from(bytes)))
+            writePrivateFile(dir, join(dir, `local-${basename(dest)}`), readStashFile(dest).toString('utf8'));
+        if (!existsSync(dest) || replace)
             writePrivateFile(dirname(dest), dest, new TextDecoder('utf8', { fatal: true }).decode(bytes));
     }
     rememberConversation(ctx, c, folder, true);

package/dist/conversation-terminal.d.ts

@@ -3,7 +3,7 @@ import type { Ctx, Handler } from './commands.js';
 import type { Values } from './args.js';
 import type { Conversation } from './conversations.js';
 /** Every terminal entry point uses the durable conversation's native harness, worktree and session. */
-export declare function conversationTerminal(ctx: Ctx, ws: Workspace, c: Conversation, project: string, values: Values): Promise<number>;
+export declare function conversationTerminal(ctx: Ctx, ws: Workspace, c: Conversation, project: string, values: Values, afterStart?: () => Promise<void> | undefined): Promise<number>;
 /**
  * A conversation and its VM, for an app to open (Claude Desktop, claude.ai, T3 Code, the menu bar). A conversation
  * whose VM was removed after it finished restores first (0.18.1+): a fresh VM from its saved branch and transcript, the

package/dist/conversation-terminal.js

@@ -9,7 +9,7 @@ import { cloudClaudeLogin, loginClaudeInWorkspace, requireClaudeTerminal } from
 import { syncAgentCredentials } from "./agent-credentials.js";
 import { prepareProjectTemplate } from "./project-template-setup.js";
 import { projectWorkspacePath, seedAgentRepository } from "./agent-repository.js";
-import { syncAgentConfig } from "./agent-config-sync.js";
+import { syncAgentConfig, syncAgentConfigAfterStart } from "./agent-config-sync.js";
 import { savedMachine } from "./filesystem-state.js";
 import { ensureMenubar, MenubarManager } from "./menubar.js";
 import { UsageError } from "./errors.js";
@@ -25,13 +25,13 @@ import { openUrl } from "./browser.js";
 import { out } from "./commands.js";
 import { progress } from "./progress.js";
 /** Every terminal entry point uses the durable conversation's native harness, worktree and session. */
-export async function conversationTerminal(ctx, ws, c, project, values) {
+export async function conversationTerminal(ctx, ws, c, project, values, afterStart) {
     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) });
+    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 } : {}) });
 }
 /**
  * A conversation and its VM, for an app to open (Claude Desktop, claude.ai, T3 Code, the menu bar). A conversation
@@ -48,10 +48,9 @@ export async function reopenConversation(ctx, c, values) {
         progress(ctx, 'Restored');
         return { conversation: restored, ws };
     }
-    if (!(await savedMachine(ctx))?.template)
-        await syncAgentConfig(ctx, ws);
+    const afterStart = (await savedMachine(ctx))?.template ? undefined : () => syncAgentConfigAfterStart(ctx, ws);
     const quiet = { ...ctx, io: { ...ctx.io, stdout: { write: () => true } } };
-    await conversationTerminal(quiet, ws, restored, ws.labels.repo_remote || ws.labels.shard_project || ws.key, { ...values, detach: true });
+    await conversationTerminal(quiet, ws, restored, ws.labels.repo_remote || ws.labels.shard_project || ws.key, { ...values, detach: true }, afterStart);
     return { conversation: restored, ws };
 }
 /**
@@ -148,13 +147,13 @@ async function startConversation(ctx, values, [path = './', explicit], openIn) {
         await ctx.cloud().workspaces.open({ key: ws.key, ...agentReachability(values), wait: false });
     if (!signedIn)
         await loginClaudeInWorkspace(ctx, ws);
-    if (!(await savedMachine(ctx))?.template)
-        await syncAgentConfig(ctx, ws);
+    // Without a saved machine the laptop's Claude and Codex config is copied in, after the agent has its first prompt.
+    const afterStart = (await savedMachine(ctx))?.template ? undefined : () => syncAgentConfigAfterStart(ctx, ws);
     await ensureMenubar(ctx.store.dir, ctx.apiUrl, new MenubarManager({ home: ctx.io.env.HOME, signal: ctx.signal }));
     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 });
+        await conversationTerminal(quiet, ws, c, project.remote ?? project.folder, { ...values, detach: true }, afterStart);
         if (openIn === 'claude-desktop')
             return openClaudeDesktopSession(ctx, ws, c);
         const url = await remoteControlUrl(ctx, ws, c);
@@ -163,5 +162,5 @@ async function startConversation(ctx, values, [path = './', explicit], openIn) {
         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);
+    return conversationTerminal(ctx, ws, c, project.remote ?? project.folder, values, afterStart);
 }

package/dist/conversations.d.ts

@@ -87,8 +87,15 @@ export declare function conversationWorkspace(ctx: Ctx, c: Conversation): Promis
  */
 export declare function waitThreadReady(ctx: Ctx, c: Conversation, pollMs?: number): Promise<Conversation>;
 export declare function restoreConversationBinding(ctx: Ctx, c: Conversation, ws: Workspace): Promise<void>;
-export declare function createConversationRecord(ctx: Ctx, folder: string, harness: Harness, route: Conversation['route'], name?: string, allocated?: (workspace: WorkspaceView) => void, idempotencyKey?: string, choice?: ModelChoice): Promise<Conversation>;
-export declare function createConversation(ctx: Ctx, folder: string, harness: Harness, route: Conversation['route'], name?: string, choice?: ModelChoice): Promise<{
+/** A native session moved in from this computer (`shard move`, 0.19.0+): the conversation starts by resuming it. */
+export interface MovedInSession {
+    session_id: string;
+    title?: string;
+}
+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>;
+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>;
+}): Promise<{
     conversation: Conversation;
     workspace: Workspace;
 }>;

package/dist/conversations.js

@@ -4,12 +4,13 @@ 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 { seedAgentRepository } from "./agent-repository.js";
+import { preflightProjectSeed, seedAgentRepository } from "./agent-repository.js";
 import { UsageError } from "./errors.js";
 import { conversationClient } from "./conversation-commands.js";
 import { recordSeedSnapshot } from "./files-mirror.js";
 import { rememberTwinSeed, sendTwinSeed, twinCheckoutArgv, twinSeed } from "./worktree-twin.js";
 import { progress } from "./progress.js";
+import { seedPhase, startProgress } from "./seed-phases.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.
@@ -156,9 +157,11 @@ 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 = {}) {
+export async function createConversationRecord(ctx, folder, harness, route, name, allocated, idempotencyKey = randomUUID(), choice = {}, movedIn) {
     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 });
     const git = gitRunner(project.folder, { ...process.env, ...ctx.io.env }, ctx.signal);
@@ -166,32 +169,46 @@ export async function createConversationRecord(ctx, folder, harness, route, name
     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 }));
+    seedPhase('local_snapshot');
     const commit = seed.commit;
     const response = await conversationClient(ctx).conversations.create({ repoRemote: project.remote ?? `file://${project.folder}`, harness, route, mode: 'new',
-        base: { commit, ...(branch ? { branch } : {}) }, ...(name ? { name } : {}), ...choice, projectId: ctx.store.profile(ctx.apiUrl).project_id }, { idempotencyKey, signal: ctx.signal });
+        base: { commit, ...(branch ? { branch } : {}) }, ...(name ? { name } : {}), ...choice, projectId: ctx.store.profile(ctx.apiUrl).project_id,
+        ...(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);
     return c;
 }
-export async function createConversation(ctx, folder, harness, route, name, choice = {}) {
+export async function createConversation(ctx, folder, harness, route, name, choice = {}, movedIn) {
     const project = projectIdentity(folder);
-    const c = await createConversationRecord(ctx, project.folder, harness, route, name, undefined, undefined, choice);
+    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);
+    seedPhase('conversation_create');
     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');
         return { conversation: c, workspace: ws };
     }
     catch (error) {
-        if (route === 'codex-cloud') {
+        // 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) {
             try {
                 await ctx.cloud().workspaces.delete(c.workspace_id);
             }

package/dist/errors.d.ts

@@ -37,7 +37,7 @@ export declare class GitError extends HintedError {
 }
 /**
  * A refusal `shard` detects itself, with a stable code, its facts in `details` and the next step as `hint` (exit 1),
- * e.g. `repository_too_large` (0.13.3+) for Git history over the initial sync limit.
+ * e.g. `t3_not_installed` (0.17.0+) when T3 Code is missing.
  */
 export declare class CodedError extends HintedError {
     name: string;

package/dist/errors.js

@@ -54,7 +54,7 @@ export class GitError extends HintedError {
 }
 /**
  * A refusal `shard` detects itself, with a stable code, its facts in `details` and the next step as `hint` (exit 1),
- * e.g. `repository_too_large` (0.13.3+) for Git history over the initial sync limit.
+ * e.g. `t3_not_installed` (0.17.0+) when T3 Code is missing.
  */
 export class CodedError extends HintedError {
     name = 'CodedError';

package/dist/files-mirror.d.ts

@@ -146,15 +146,7 @@ export declare class FilesMirror {
         already: boolean;
     }>;
 }
-/**
- * The seed snapshot (sh; $1 repository, $2 conversation name, $3 hub): HEAD plus the working tree the conversation was
- * seeded with, committed in the conversation's VM with a temporary index (never on this computer), kept per worktree
- * as refs/worktree/shard/seed and in the hub as refs/shard/seed/<name>. Mirrors leave out what it already contains,
- * so the user's own uncommitted edits never show as the conversation's change. Threads on one computer are worktrees
- * of one repository (0.16.0+), so the seed is per worktree; the shared refs/shard/seed of earlier seeds is read, and
- * still written, only in the repository's main worktree.
- */
-export declare const SEED_SNAPSHOT = "set -eu\ncd \"$1\"\nmain=0; [ \"$(git rev-parse --absolute-git-dir)\" = \"$(git rev-parse --path-format=absolute --git-common-dir)\" ] && main=1\nif git rev-parse -q --verify refs/worktree/shard/seed >/dev/null; then seed=$(git rev-parse refs/worktree/shard/seed)\nelif [ \"$main\" = 1 ] && git rev-parse -q --verify refs/shard/seed >/dev/null; then seed=$(git rev-parse refs/shard/seed); else\nidx=$(mktemp); trap 'rm -f \"$idx\"' EXIT\ncp \"$(git rev-parse --path-format=absolute --git-path index)\" \"$idx\" 2>/dev/null || { rm -f \"$idx\"; GIT_INDEX_FILE=\"$idx\" git read-tree HEAD; }\nGIT_INDEX_FILE=\"$idx\" git add -A\ntree=$(GIT_INDEX_FILE=\"$idx\" git write-tree)\nif [ \"$tree\" = \"$(git rev-parse 'HEAD^{tree}')\" ]; then seed=$(git rev-parse HEAD); else\nseed=$(GIT_AUTHOR_NAME=Shardflux GIT_AUTHOR_EMAIL=seed@shardflux.dev GIT_COMMITTER_NAME=Shardflux GIT_COMMITTER_EMAIL=seed@shardflux.dev git commit-tree \"$tree\" -p HEAD -m \"Shardflux: the working tree this conversation started from\"); fi\ngit update-ref refs/worktree/shard/seed \"$seed\"\nif [ \"$main\" = 1 ]; then git update-ref refs/shard/seed \"$seed\"; fi\nfi\nif [ -d \"$3\" ]; then git -c core.hooksPath=/dev/null push -q \"$3\" \"+$seed:refs/shard/seed/$2\" >/dev/null 2>&1 || true; fi\nprintf '%s\n' \"$seed\"\n";
+export declare const SEED_SNAPSHOT = "set -eu\ncd \"$1\"\nmain=0; [ \"$(git rev-parse --absolute-git-dir)\" = \"$(git rev-parse --path-format=absolute --git-common-dir)\" ] && main=1\nif git rev-parse -q --verify refs/worktree/shard/seed >/dev/null; then seed=$(git rev-parse refs/worktree/shard/seed)\nelif [ \"$main\" = 1 ] && git rev-parse -q --verify refs/shard/seed >/dev/null; then seed=$(git rev-parse refs/shard/seed); else\nidx=$(mktemp); trap 'rm -f \"$idx\"' EXIT\ncp \"$(git rev-parse --path-format=absolute --git-path index)\" \"$idx\" 2>/dev/null || { rm -f \"$idx\"; GIT_INDEX_FILE=\"$idx\" git read-tree HEAD; }\nGIT_INDEX_FILE=\"$idx\" git add -A\ntree=$(GIT_INDEX_FILE=\"$idx\" git write-tree)\nif [ \"$tree\" = \"$(git rev-parse 'HEAD^{tree}')\" ]; then seed=$(git rev-parse HEAD); else\nseed=$(GIT_AUTHOR_NAME=Shardflux GIT_AUTHOR_EMAIL=seed@shardflux.dev GIT_COMMITTER_NAME=Shardflux GIT_COMMITTER_EMAIL=seed@shardflux.dev git commit-tree \"$tree\" -p HEAD -m \"Shardflux: the working tree this conversation started from\"); fi\ngit update-ref refs/worktree/shard/seed \"$seed\"\nif [ \"$main\" = 1 ]; then git update-ref refs/shard/seed \"$seed\"; fi\nfi\npush='set -u\nseed=$1; name=$2; hub=$3; cd \"$4\"\npush=1; if [ \"$(git config --bool remote.origin.promisor 2>/dev/null || true)\" = true ]; then push=0\nfor c in \"$seed\" \"$seed^1\"; do o=$(git rev-parse -q --verify \"$c^{commit}\" 2>/dev/null) && git --git-dir=\"$hub\" cat-file -e \"$o^{commit}\" 2>/dev/null && push=1 && break; done; fi\nif [ -d \"$hub\" ] && [ \"$push\" = 1 ]; then git -c core.hooksPath=/dev/null push -q \"$hub\" \"+$seed:refs/shard/seed/$name\" >/dev/null 2>&1 || true; fi\n'\nif [ \"${4:-}\" = background ]; then\n  if command -v setsid >/dev/null 2>&1; then (setsid sh -c \"$push\" shard-seed-push \"$seed\" \"$2\" \"$3\" \"$PWD\" >/dev/null 2>&1 </dev/null &)\n  else (sh -c \"$push\" shard-seed-push \"$seed\" \"$2\" \"$3\" \"$PWD\" >/dev/null 2>&1 </dev/null &); fi\nelse sh -c \"$push\" shard-seed-push \"$seed\" \"$2\" \"$3\" \"$PWD\"; fi\nprintf '%s\n' \"$seed\"\n";
 /** Best effort: without a snapshot the folder also lists the start state's own edits. */
 export declare function recordSeedSnapshot(ws: Pick<Workspace, 'cell'>, c: Pick<Conversation, 'worktree_path' | 'branch'>, signal?: AbortSignal): Promise<string | null>;
 /** A ready VM of the project (never woken), else the project's space reader, woken when needed. */