@shardflux/cli 0.18.0 → 0.19.0

package/dist/agent-target-commands.js

@@ -5,7 +5,7 @@ import { ensureCloudClaude } from "./claude-cloud-login.js";
 import { spawn } from 'node:child_process';
 import { Readable, Duplex } from 'node:stream';
 import { ShardfluxApiError, WorkspaceTunnels } from '@shardflux/sdk';
-import { conversationWorkspace, getConversation } from "./conversations.js";
+import { getConversation } from "./conversations.js";
 import { out, resolveWorkspace } from "./commands.js";
 import { MODEL_CHOICES } from "./agent-models.js";
 import { AgentTargets, installedTargets, targetLabel } from "./agent-targets.js";
@@ -229,14 +229,21 @@ const openTarget = (target) => async (ctx, values, [ref = 'main']) => {
     if (target === 't3' && /^conv_[a-z0-9]{26}$/.test(ref))
         return openT3Conversation(ctx, ref, values);
     // A conversation id opens that conversation's own session on its computer (claude.ai, the desktop apps).
-    const conversation = /^conv_[a-z0-9]{26}$/.test(ref) ? await getConversation(ctx, ref) : undefined;
+    let conversation = /^conv_[a-z0-9]{26}$/.test(ref) ? await getConversation(ctx, ref) : undefined;
     // A pooled thread (0.18.0+) has no provider login on its session: it opens remotely in T3 Code.
     if (conversation && conversationPooled(conversation)) {
         if (!detected.targets.includes('t3'))
             throw pooledNeedsT3(ref);
         return openT3Conversation(ctx, ref, values);
     }
-    let ws = conversation ? await conversationWorkspace(ctx, conversation) : await resolveWorkspace(ctx, keyOf(ref));
+    // A conversation whose VM was removed restores into a fresh one first (0.18.1+).
+    let ws;
+    if (conversation) {
+        const { reopenConversation } = await import("./conversation-terminal.js");
+        ({ conversation, ws } = await reopenConversation(ctx, conversation, values));
+    }
+    else
+        ws = await resolveWorkspace(ctx, keyOf(ref));
     if (values.reachable !== undefined)
         ws = await ctx.cloud().workspaces.open({ key: ws.key, ...agentReachability(values), wait: false });
     // T3 lists both agents and opens without Claude (it shows Claude as signed out); the Claude apps need it.
@@ -270,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 {
@@ -283,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;
@@ -297,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);
@@ -341,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.0";
+export declare const CLI_VERSION = "0.19.0";
 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.0';
+export const CLI_VERSION = '0.19.0';
 export const GLOBAL_OPTIONS = {
     'api-url': { type: 'string', value: '<url>', description: 'API base URL (default $SHARDFLUX_API_URL, else https://api.shardflux.dev).' },
     json: { type: 'boolean', description: 'Print machine-readable JSON on stdout (errors as JSON on stderr).' },
@@ -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,8 +1299,9 @@ 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', 'logs'], summary: 'Tail an agent PTY from its output offset', positionals: [{ name: 'agent', required: true }], options: {
-            app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default remembered choice).' },
+    { 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).' },
             follow: { type: 'boolean', description: 'Follow output until interrupted.' },
         } },
@@ -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/command-center-actions.js

@@ -11,9 +11,11 @@ import { agentName as gitAgentName } from "./agent-git.js";
 import { randomUUID } from 'node:crypto';
 import { prepareAgentMachine } from "./agent-machine.js";
 import { OperationFailedError } from '@shardflux/sdk';
+import { conversationPtyId, getConversation } from "./conversations.js";
 import { launchConversationProject, launchProjectCommand } from "./conversation-terminal.js";
 import { startThreadOn } from "./thread-on-computer.js";
 import { launchT3 } from "./t3-launch.js";
+const CONVERSATION_ID = /^conv_[a-z0-9]{26}$/;
 /** L9 can register target-specific handlers after detecting the installed applications. */
 export async function availableTargets(ctx) {
     const { HANDLERS } = await import("./handlers.js");
@@ -124,14 +126,38 @@ export const CENTER_HANDLERS = {
     },
     async 'agents logs'(ctx, values, [ref]) {
         if (!ref)
-            throw new UsageError('agents logs requires an agent workspace key');
+            throw new UsageError('agents logs requires a conversation id or an agent workspace key');
         if (values.app !== undefined && values.app !== 'claude' && values.app !== 'codex')
             throw new UsageError('--app must be claude or codex');
-        const ws = await resolveWorkspace(ctx, ref);
+        // A conversation (0.18.1+): its id, or its VM's key. Its PTY is the guest's record, never derived from the VM key.
+        let conversation;
+        let ws;
+        if (CONVERSATION_ID.test(ref)) {
+            conversation = await getConversation(ctx, ref);
+            ws = await ctx.cloud().workspaces.get(conversation.workspace_id);
+        }
+        else {
+            ws = await resolveWorkspace(ctx, ref);
+            if (ws.labels.shard_conversation && CONVERSATION_ID.test(ws.labels.shard_conversation))
+                conversation = await getConversation(ctx, ws.labels.shard_conversation);
+        }
+        if (conversation?.route === 'codex-cloud')
+            throw new UsageError(`Codex Cloud runs this conversation; follow it with shard agents open ${conversation.id}.`);
+        if (conversation?.route === 'acp')
+            throw new UsageError('This conversation runs through its ACP client, which shows its output; it has no terminal to follow.');
+        if (conversation && values.app !== undefined && values.app !== conversation.harness)
+            throw new UsageError(`This conversation runs ${conversation.harness}; omit --app.`);
         const project = ws.labels.repo_remote || ws.labels.shard_project || ws.key;
-        const app = str(values.app) ?? new AgentStateStore(ctx.store.dir).app(project, ws.labels.app === 'codex' ? 'codex' : 'claude');
-        const id = `shard-${ws.labels.agent_pty_name || agentName(ws.key, ws.labels)}-${app}`;
+        const app = conversation?.harness ?? str(values.app) ?? new AgentStateStore(ctx.store.dir).app(project, ws.labels.app === 'codex' ? 'codex' : 'claude');
         const cell = ws.cell({ agentLabel: ctx.agentLabel, ...(ctx.wake ? {} : { wake: null }), transitionTimeoutMs: ctx.wakeTimeoutMs });
+        let id;
+        try {
+            id = conversation ? await conversationPtyId(cell, conversation, ctx.signal) : `shard-${ws.labels.agent_pty_name || agentName(ws.key, ws.labels)}-${app}`;
+        }
+        catch (error) {
+            cell.close();
+            throw error;
+        }
         const offsetText = str(values.offset);
         if (offsetText !== undefined && (!/^\d+$/.test(offsetText) || !Number.isSafeInteger(Number(offsetText))))
             throw new UsageError('--offset must be a nonnegative safe integer');
@@ -175,7 +201,7 @@ export const CENTER_HANDLERS = {
             }
             const remainder = decoder.decode();
             if (ctx.json)
-                ctx.io.stdout.write(json({ pty_id: id, output: output + remainder, nextOffset: cursor.offset, session, exited }));
+                ctx.io.stdout.write(json({ pty_id: id, ...(conversation ? { conversation: { id: conversation.id } } : {}), output: output + remainder, nextOffset: cursor.offset, session, exited }));
             else
                 ctx.io.stdout.write(remainder);
             return 0;

package/dist/conversation-commands.js

@@ -22,7 +22,12 @@ export const CONVERSATION_HANDLERS = {
         return 0;
     },
     async 'conversations get'(ctx, _values, [id]) { const c = await conversationClient(ctx).conversations.get(id); const q = questionLine(c, 200); out(ctx, `${c.title}\n${c.state}\n${c.branch}\n${q ? `${q}\n` : ''}`, c); return 0; },
-    async 'conversations send'(ctx, _values, [id, text]) { const r = await conversationClient(ctx).conversations.send(id, text, { signal: ctx.signal }); out(ctx, `Message sent (${r.seq}).\n`, r); return 0; },
+    // A finished conversation whose VM was removed restores into a fresh one, then takes the message (APIs that do; 0.18.1+).
+    async 'conversations send'(ctx, _values, [id, text]) {
+        const r = await conversationClient(ctx).conversations.send(id, text, { signal: ctx.signal });
+        out(ctx, `${r.restored ? 'Restored\n' : ''}Message sent (${r.seq}).\n`, r);
+        return 0;
+    },
     async 'conversations wait'(ctx, values, [id]) {
         const seconds = values.timeout === undefined ? 900 : Number(values.timeout);
         if (!Number.isInteger(seconds) || seconds < 0 || seconds > 900)

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,17 @@ 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
+ * same conversation and its session resumed. A terminal conversation's session starts detached, as a new one does, so
+ * the app reaches it at once; the guest starts the others.
+ */
+export declare function reopenConversation(ctx: Ctx, c: Conversation, values: Values): Promise<{
+    conversation: Conversation;
+    ws: Workspace;
+}>;
 /**
  * `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.

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";
@@ -23,14 +23,35 @@ import { launchT3 } from "./t3-launch.js";
 import { openClaudeDesktopSession, remoteControlUrl } from "./agent-target-commands.js";
 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
+ * whose VM was removed after it finished restores first (0.18.1+): a fresh VM from its saved branch and transcript, the
+ * same conversation and its session resumed. A terminal conversation's session starts detached, as a new one does, so
+ * the app reaches it at once; the guest starts the others.
+ */
+export async function reopenConversation(ctx, c, values) {
+    if (!c.ended_at || c.route === 'codex-cloud')
+        return { conversation: c, ws: await conversationWorkspace(ctx, c) };
+    const restored = await resumeConversation(ctx, c);
+    const ws = await conversationWorkspace(ctx, restored);
+    if (restored.route !== 'terminal') {
+        progress(ctx, 'Restored');
+        return { conversation: restored, 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 }, afterStart);
+    return { conversation: restored, ws };
 }
 /**
  * `shard ./` (and `agents new --in auto`): new conversations open where `agents targets` says (open_in, 0.17.0+): T3
@@ -126,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);
@@ -141,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

@@ -1,4 +1,4 @@
-import type { Workspace, WorkspaceView } from '@shardflux/sdk';
+import type { CellClient, Workspace, WorkspaceView } from '@shardflux/sdk';
 import type { Ctx } from './commands.js';
 import type { ModelChoice } from './agent-models.js';
 export type Harness = 'claude' | 'codex';
@@ -65,6 +65,13 @@ export interface LocalConversation {
  */
 export declare const conversationEnded: (c: Pick<Conversation, "state" | "ended_at" | "route" | "landed">) => boolean;
 export declare const conversationName: (c: Conversation) => string;
+/**
+ * The managed PTY a conversation's harness runs in (0.18.1+). The guest records it per conversation
+ * (sf-agent's conversation runtime record), which also keeps the PTY a fork inherited from its parent; without a
+ * record it is the one the guest names after the conversation, `shard-<name>-<harness>`. Never the VM key's name: a
+ * conversation's VM is `<project>/conv-<name>`.
+ */
+export declare function conversationPtyId(cell: Pick<CellClient, 'exec'>, c: Conversation, signal?: AbortSignal): Promise<string>;
 export declare function validateConversation(c: Conversation): Conversation;
 export declare function localConversations(ctx: Pick<Ctx, 'store' | 'apiUrl'>): Record<string, LocalConversation>;
 export declare function rememberConversation(ctx: Pick<Ctx, 'store' | 'apiUrl'>, c: Conversation, folder: string, handedOff?: boolean, baseBranch?: string): void;
@@ -80,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;
 }>;