@shardflux/cli 0.19.1 → 0.22.0

package/dist/move-worktrees.js

@@ -0,0 +1,201 @@
+/** An explicit, recoverable cold copy of a repository and its registered worktrees. Never writes to local Git. */
+import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { createReadStream } from 'node:fs';
+import { lstat, readFile, readdir, readlink, realpath } from 'node:fs/promises';
+import { basename, dirname, join, relative } from 'node:path';
+import { SYNC_CHUNK_BYTES } from "./project-sync-transfer.js";
+import { projectGit } from "./project-sync-manifest.js";
+import { UsageError } from "./errors.js";
+import { rewriteSessionPaths } from "./local-sessions.js";
+const inside = (root, path) => path === root || path.startsWith(`${root}/`);
+const git = (folder, args, signal) => projectGit(folder, args, signal);
+const hash = async (file, signal) => {
+    const sha = createHash('sha256');
+    for await (const chunk of createReadStream(file, { signal }))
+        sha.update(chunk);
+    return sha.digest('hex');
+};
+/** Git is the source of membership; sibling folders and symlink targets never expand the upload scope. */
+export async function inspectWorktreeMigration(folder, transcript, signal) {
+    let commonDir;
+    try {
+        commonDir = (await git(folder, ['rev-parse', '--path-format=absolute', '--git-common-dir'], signal)).trim();
+    }
+    catch (e) {
+        if (signal?.aborted || e.code !== 128)
+            throw e;
+        return null;
+    }
+    folder = await realpath(folder);
+    commonDir = await realpath(commonDir);
+    try {
+        await git(folder, ['rev-parse', '--verify', 'HEAD'], signal);
+    }
+    catch (e) {
+        if (signal?.aborted || e.code !== 128)
+            throw e;
+        return null;
+    }
+    const main = dirname(commonDir);
+    if (basename(commonDir) !== '.git' || !(await lstat(commonDir)).isDirectory())
+        throw new UsageError('Preserve-all needs a repository with its own .git directory; separate Git directories are not supported.');
+    if ((await git(main, ['rev-parse', '--show-toplevel'], signal)).trim() !== main)
+        throw new UsageError('The main checkout is unavailable; restore it before moving all worktrees.');
+    // External alternate stores cannot be represented by this bounded copy.
+    const alternates = join(commonDir, 'objects/info/alternates');
+    if (await readFile(alternates, 'utf8').then(s => !!s.trim(), (e) => { if (e.code !== 'ENOENT')
+        throw e; return false; }))
+        throw new UsageError('This repository borrows an external Git object store. Make it self-contained before preserving all worktrees.');
+    const registered = (await git(folder, ['worktree', 'list', '--porcelain', '-z'], signal)).split('\0').filter(v => v.startsWith('worktree ')).map(v => v.slice(9));
+    const sources = [];
+    for (const path of registered) {
+        try {
+            sources.push(await realpath(path));
+        }
+        catch {
+            throw new UsageError(`Registered worktree is missing: ${path}. Recover it or explicitly remove its stale Git registration before moving all worktrees.`);
+        }
+    }
+    if (!sources.includes(folder) || !sources.includes(main))
+        throw new UsageError('Git did not list the selected and main worktrees.');
+    const trees = [];
+    for (const [i, source] of sources.entries()) {
+        // Worktrees inside the selected folder keep their relative paths, including ignored .worktrees.
+        const target = source === folder ? '.' : inside(folder, source) ? relative(folder, source) : `.shard/preserved-worktrees/${i}-${basename(source)}`;
+        const gitDir = (await git(source, ['rev-parse', '--absolute-git-dir'], signal)).trim();
+        if (!inside(commonDir, gitDir))
+            throw new UsageError(`Worktree ${source} uses an unrelated Git store.`);
+        const branch = await git(source, ['symbolic-ref', '-q', 'HEAD'], signal).then(s => s.trim(), (e) => { if (e.code !== 1)
+            throw e; return ''; });
+        const spellings = [...new Set([source, registered[i]])];
+        trees.push({ source, spellings, target, gitDir, branch, head: (await git(source, ['rev-parse', 'HEAD'], signal)).trim(),
+            status: await git(source, ['status', '--porcelain=v1', '-z', '--untracked-files=all'], signal), files: [],
+            exclude: sources.filter(p => p !== source && inside(source, p)).map(p => relative(source, p)) });
+    }
+    const text = transcript.toString('utf8');
+    const referenced = trees.filter(t => t.source !== folder && t.spellings.some(p => text.includes(p) || text.includes(JSON.stringify(p).slice(1, -1)))).map(t => t.source);
+    return { version: 1, selected: folder, commonDir, main, trees, referenced,
+        refs: await git(folder, ['for-each-ref', '--format=%(objectname) %(refname)'], signal), bytes: 0, files: 0 };
+}
+/** Size/hash pass only after preserve-all is selected (ignored caches may be large). */
+export async function captureWorktreeMigration(plan, signal) {
+    plan.bytes = 0;
+    plan.files = 0;
+    for (const tree of plan.trees) {
+        tree.files = [];
+        const walk = async (path) => {
+            signal?.throwIfAborted();
+            if (tree.exclude.some(p => inside(p, path)))
+                return;
+            if (path.endsWith('/.git'))
+                throw new UsageError(`Nested repository ${join(tree.source, path)} is not a registered worktree. Migrate it separately before preserving all worktrees.`);
+            const file = join(tree.source, path), st = await lstat(file);
+            if (st.isDirectory()) {
+                for (const name of (await readdir(file)).sort())
+                    await walk(path ? `${path}/${name}` : name);
+                return;
+            }
+            if (!st.isFile() && !st.isSymbolicLink())
+                throw new UsageError(`Cannot preserve special file ${file}. Remove it from this migration scope before retrying.`);
+            if (path.endsWith('.lock') && inside('.git', path))
+                throw new UsageError(`Git is writing ${file}; finish the Git operation before migrating.`);
+            const link = st.isSymbolicLink() ? await readlink(file) : undefined;
+            const sha256 = link === undefined ? await hash(file, signal) : createHash('sha256').update(`symlink\0${link}`).digest('hex');
+            tree.files.push({ path, size: st.size, mode: st.mode & 0o777, sha256, ...(link !== undefined ? { link } : {}) });
+            plan.bytes += st.size;
+            plan.files++;
+        };
+        await walk('');
+    }
+}
+export function migrationScope(plan) {
+    return { worktrees: plan.trees.map(t => ({ path: t.source, branch: t.branch || '(detached)', target: t.target })), referenced: plan.referenced,
+        local_refs: plan.refs.trim().split('\n').filter(Boolean).map(line => line.slice(line.indexOf(' ') + 1)),
+        bytes: plan.bytes, files: plan.files, scope: 'All files, including ignored files and Git metadata, inside these registered worktrees. Symlink targets and unrelated sibling folders are not uploaded.',
+        size_basis: 'File bytes before tar headers; archive bytes and free-space requirement are larger. Ignored dependency/build caches are included.' };
+}
+/** User refs a normal move leaves behind. Shardflux's own refs/shard/* (twin snapshots, land and agent refs) are rebuilt, never user work. */
+export function omittedLocalRefs(plan) {
+    const selected = plan.trees.find(t => t.source === plan.selected);
+    return plan.refs.trim().split('\n').filter(Boolean).map(line => line.slice(line.indexOf(' ') + 1))
+        .filter(ref => ref !== selected.branch && !ref.startsWith('refs/remotes/') && !ref.startsWith('refs/shard/'));
+}
+/** Longest paths first, before replacing a parent. Message text and signed thinking keep the existing rewrite contract. */
+export function rewriteWorktreeTranscript(bytes, plan, root) {
+    const mappings = plan.trees.flatMap(tree => tree.spellings.map(from => ({ from, to: tree.target === '.' ? root : `${root}/${tree.target}` })));
+    for (const { from, to } of mappings.sort((a, b) => b.from.length - a.from.length))
+        bytes = rewriteSessionPaths(bytes, from, to);
+    return bytes;
+}
+async function uploadTree(cell, tree, dest, signal) {
+    const child = spawn('tar', ['-cf', '-', ...tree.exclude.map(p => `--exclude=./${p}`), '-C', tree.source, '.'], { stdio: ['ignore', 'pipe', 'pipe'], signal, env: { ...process.env, COPYFILE_DISABLE: '1' } });
+    let stderr = '';
+    child.stderr.on('data', (b) => { stderr = (stderr + b.toString()).slice(-2000); });
+    const exited = new Promise((resolve, reject) => { child.on('error', reject); child.on('close', code => resolve(code ?? 1)); });
+    // Attach a rejection handler while reading the stream.
+    void exited.catch(() => undefined);
+    let total = 0, size = 0, pending = [];
+    const flush = async () => { if (!size)
+        return; const bytes = Buffer.concat(pending, size); await cell.files.write(dest, bytes, { mode: '0600', append: total > 0 }); total += size; size = 0; pending = []; };
+    try {
+        for await (const chunk of child.stdout) {
+            let b = chunk;
+            while (b.length) {
+                const n = Math.min(b.length, SYNC_CHUNK_BYTES - size);
+                pending.push(b.subarray(0, n));
+                size += n;
+                b = b.subarray(n);
+                if (size === SYNC_CHUNK_BYTES)
+                    await flush();
+            }
+        }
+        await flush();
+        if (await exited !== 0)
+            throw new Error(`Worktree archive failed: ${stderr}`);
+        return total;
+    }
+    catch (e) {
+        child.kill();
+        await exited.catch(() => undefined);
+        throw e;
+    }
+}
+/** Called instead of regular seeding: the guest starts only after its refs, index, bytes and statuses are checked. */
+export async function preserveWorktreeMigration(cell, plan, c, signal) {
+    if (!/^conv_[a-z0-9]{26}$/.test(c.id))
+        throw new Error('Invalid migration identity');
+    const snapshot = `/shardflux/project/migrations/${c.id}`;
+    const mounted = await cell.exec.run(['test', '-d', '/shardflux/project/git/hub.git'], { timeoutMs: 10_000, signal });
+    if (mounted.exitCode !== 0)
+        throw new Error('The durable project space is unavailable; preserve-all did not upload or resume the session.');
+    await cell.files.mkdir(snapshot, { parents: true });
+    const space = await cell.exec.run(['python3', '-c', 'import os,shutil,sys; a,b,n=sys.argv[1:]; os.makedirs(b,exist_ok=True); need=int(n); assert shutil.disk_usage(a).free>=need and shutil.disk_usage(b).free>=need, "Migration needs more free disk space for archives and restored files"', snapshot, c.worktree_path,
+        String(2 * (plan.bytes + plan.files * 1024))], { timeoutMs: 10_000, signal });
+    if (space.exitCode !== 0)
+        throw new UsageError(space.stderr.trim());
+    let bytes = 0;
+    for (const [i, tree] of plan.trees.entries())
+        bytes += await uploadTree(cell, tree, `${snapshot}/${i}.tar`, signal);
+    const script = await readFile(new URL('./move-worktrees-restore.py', import.meta.url), 'utf8');
+    await cell.files.write(`${snapshot}/restore.py`, script, { mode: '0600' });
+    const branch = c.branch.startsWith('refs/heads/') ? c.branch : `refs/heads/${c.branch}`;
+    await cell.files.write(`${snapshot}/manifest.json`, JSON.stringify({ ...plan, branch, root: c.worktree_path }), { mode: '0600' });
+    const applied = await cell.exec.run(['python3', `${snapshot}/restore.py`, `${snapshot}/manifest.json`, c.worktree_path, '--defer-conversation-branch'], { timeoutMs: 600_000, maxOutputBytes: 8192, signal });
+    if (applied.exitCode !== 0)
+        throw new Error(`Preserve-all verification failed; the local source is unchanged: ${applied.stderr.trim()}`);
+    // No move is recorded or resumed if another local process changed a tree during upload.
+    const source = (await inspectWorktreeMigration(plan.selected, Buffer.alloc(0), signal));
+    await captureWorktreeMigration(source, signal);
+    if (source.refs !== plan.refs || JSON.stringify(source.trees.map(t => [t.source, t.head, t.branch, t.status, t.files])) !== JSON.stringify(plan.trees.map(t => [t.source, t.head, t.branch, t.status, t.files]))) {
+        throw new UsageError('A local worktree changed during migration; no session was resumed. Finish its work and retry. The captured recovery archive is retained.');
+    }
+    await cell.files.write(`${snapshot}/ready.json`, JSON.stringify({ bytes, worktrees: plan.trees.length, files: plan.files }), { mode: '0600' });
+    // MovedInReady in the guest observes this symbolic branch. It is the last
+    // readiness transition, after all copies and both local/remote verification.
+    const ready = await cell.exec.run(['sh', '-c', 'set -e; git -C "$1" -c core.hooksPath=/dev/null update-ref "$2" HEAD; git -C "$1" symbolic-ref HEAD "$2"',
+        'shard-migration-ready', c.worktree_path, branch], { timeoutMs: 10_000, signal });
+    if (ready.exitCode !== 0)
+        throw new Error(`Migration branch could not be activated: ${ready.stderr.trim()}`);
+    return { snapshot, bytes, worktrees: plan.trees.length, files: plan.files };
+}

package/dist/move.d.ts

@@ -3,6 +3,7 @@ import type { Ctx, Handler } from './commands.js';
 import type { Values } from './args.js';
 import type { Conversation } from './conversations.js';
 import type { LocalSession, SessionHarness, SessionState } from './local-sessions.js';
+import type { WorktreeMigration } from './move-worktrees.js';
 type Env = Record<string, string | undefined>;
 /** The project a folder belongs to: its Git repository's top, or the folder itself. */
 export declare function projectRoot(folder: string): string;
@@ -15,10 +16,17 @@ type MoveCell = Pick<ReturnType<Workspace['cell']>, 'exec' | 'files'>;
  * project space is mounted, as the conversation's durable copy with the same checkpoint metadata the guest writes
  * (transcripts/<id>/meta.json), so the session survives the VM from its first minute.
  */
-export declare function placeTranscript(cell: MoveCell, c: Pick<Conversation, 'id' | 'harness' | 'worktree_path'>, s: LocalSession, bytes: Buffer, folder: string, signal?: AbortSignal): Promise<{
+export declare function placeTranscript(cell: MoveCell, c: Pick<Conversation, 'id' | 'harness' | 'worktree_path'>, s: LocalSession, bytes: Buffer, folder: string, signal?: AbortSignal, worktrees?: WorktreeMigration): Promise<{
     native: string;
     durable: boolean;
 }>;
+/** Every working directory the whole transcript names in its record metadata, never in message or tool content. */
+export declare function transcriptCwds(bytes: Buffer): string[];
+/**
+ * The project a move goes to: --path when the session's records confirm it worked there (placeTranscript checks), the
+ * current folder's project when it worked there, else the project of where it works now.
+ */
+export declare function moveFolder(s: Pick<LocalSession, 'cwd' | 'cwds'>, here: string, explicit: boolean): string;
 export declare function moveSession(ctx: Ctx, values: Values): Promise<number>;
 /** `shard move --list`: this project's sessions on this computer, and where each moved one continues. */
 export declare function listMovable(ctx: Pick<Ctx, 'store' | 'apiUrl'>, values: Values, env: Env, now?: number): {
@@ -30,6 +38,7 @@ export declare function listMovable(ctx: Pick<Ctx, 'store' | 'apiUrl'>, values:
         updated_at: string;
         source: string;
         cwd: string;
+        cwds: string[];
         running: boolean;
         turn: "working" | "idle";
         moved: {

package/dist/move.js

@@ -31,8 +31,9 @@ import { openInChoices } from "./t3-mode.js";
 import { openClaudeDesktopSession, remoteControlUrl } from "./agent-target-commands.js";
 import { openUrl } from "./browser.js";
 import { SYNC_CHUNK_BYTES } from "./project-sync-transfer.js";
-import { completeRecords, continuedAfter, findLocalSession, homeRelativeTranscript, listLocalSessions, readTranscript, rewriteSessionPaths, sessionState } from "./local-sessions.js";
+import { completeRecords, continuedAfter, findLocalSession, homeRelativeTranscript, listLocalSessions, readTranscript, recordCwd, rewriteSessionPaths, sessionState } from "./local-sessions.js";
 import { installDivergenceNotice, movedKey, movedSession, movedSessions, rememberMoved } from "./moved-sessions.js";
+import { captureWorktreeMigration, inspectWorktreeMigration, migrationScope, omittedLocalRefs, preserveWorktreeMigration, rewriteWorktreeTranscript } from "./move-worktrees.js";
 const VM_HOME = '/home/user';
 const SPACE = '/shardflux/project';
 /** A transcript above this moves with the repository's history bound. */
@@ -95,14 +96,27 @@ async function writeChunks(cell, path, bytes) {
  * project space is mounted, as the conversation's durable copy with the same checkpoint metadata the guest writes
  * (transcripts/<id>/meta.json), so the session survives the VM from its first minute.
  */
-export async function placeTranscript(cell, c, s, bytes, folder, signal) {
-    const sessionCwd = realOr(s.cwd), inside = relative(folder, sessionCwd);
-    if (inside.startsWith('..'))
-        throw new UsageError('The session ran outside this project folder; run shard move in its project.');
-    let moved = rewriteSessionPaths(bytes, folder, c.worktree_path);
-    if (s.cwd !== sessionCwd && !s.cwd.startsWith(`${folder}/`) && s.cwd !== folder) {
-        // The transcript recorded a path through a link (/tmp for /private/tmp): move that spelling too.
-        moved = rewriteSessionPaths(moved, s.cwd.slice(0, s.cwd.length - inside.length).replace(/\/$/, ''), c.worktree_path);
+export async function placeTranscript(cell, c, s, bytes, folder, signal, worktrees) {
+    // The project is confirmed by the session's own records (0.20.2+): any of them working in the folder, not only the
+    // first (a session started in a scratch folder that went on in this repository). Paths are moved for this folder;
+    // records of a folder outside it keep their bytes.
+    const here = confirmedCwds(s, bytes, folder, worktrees);
+    let moved = bytes;
+    if (worktrees) {
+        // Normalize linked spellings confirmed by record metadata before mapping
+        // longest registered prefixes. Scratch records outside the family stay intact.
+        for (const tree of [...worktrees.trees].sort((a, b) => b.source.length - a.source.length)) {
+            const spellings = here.filter(cwd => isInside(tree.source, realOr(cwd))).map(cwd => linkedSpelling(cwd, tree.source));
+            for (const spelled of new Set(spellings.filter((p) => !!p)))
+                moved = rewriteSessionPaths(moved, spelled, tree.source);
+        }
+        moved = rewriteWorktreeTranscript(moved, worktrees, c.worktree_path);
+    }
+    else {
+        moved = rewriteSessionPaths(moved, folder, c.worktree_path);
+        // A path recorded through a link (/tmp for /private/tmp): move that spelling too.
+        for (const spelled of new Set(here.map(cwd => linkedSpelling(cwd, folder)).filter((p) => !!p)))
+            moved = rewriteSessionPaths(moved, spelled, c.worktree_path);
     }
     const homeRelative = homeRelativeTranscript(s, c.worktree_path);
     const native = `${VM_HOME}/${homeRelative}`;
@@ -125,6 +139,52 @@ const realOr = (path) => { try {
 catch {
     return resolve(path);
 } };
+const isInside = (folder, path) => path === folder || path.startsWith(folder.endsWith('/') ? folder : `${folder}/`);
+/** The folder as `cwd` spells it through a link (/tmp/x for /private/tmp/x), or undefined when it spells it plainly. */
+function linkedSpelling(cwd, folder) {
+    if (isInside(folder, cwd))
+        return undefined;
+    const inside = relative(folder, realOr(cwd));
+    if (inside && !cwd.endsWith(`/${inside}`))
+        return undefined;
+    return inside ? cwd.slice(0, cwd.length - inside.length - 1) : cwd;
+}
+/** Every working directory the whole transcript names in its record metadata, never in message or tool content. */
+export function transcriptCwds(bytes) {
+    const out = new Set();
+    for (const line of bytes.toString('utf8').split('\n')) {
+        try {
+            const r = JSON.parse(line);
+            if (!r || typeof r !== 'object' || Array.isArray(r))
+                continue;
+            const cwd = recordCwd(r);
+            if (cwd)
+                out.add(cwd);
+        }
+        catch { /* a partial record */ }
+    }
+    return [...out];
+}
+function confirmedCwds(s, bytes, folder, worktrees) {
+    const roots = [folder, ...(worktrees?.trees.map(t => t.source) ?? [])];
+    const here = [...new Set([s.cwd, ...s.cwds, ...transcriptCwds(bytes)])].filter(cwd => roots.some(root => isInside(root, realOr(cwd))));
+    if (!here.length)
+        throw new UsageError('The session ran outside this project folder; run shard move in its project, or pass --path with the repository it worked in.');
+    return here;
+}
+/**
+ * The project a move goes to: --path when the session's records confirm it worked there (placeTranscript checks), the
+ * current folder's project when it worked there, else the project of where it works now.
+ */
+export function moveFolder(s, here, explicit) {
+    if (explicit)
+        return here;
+    const root = (cwd) => (existsSync(cwd) ? projectRoot(cwd) : here);
+    if (isInside(here, realOr(s.cwd)))
+        return root(s.cwd);
+    const inHere = [...s.cwds].reverse().find(cwd => isInside(here, realOr(cwd)));
+    return inHere ? root(inHere) : root(s.cwd);
+}
 async function alreadyMoved(ctx, m) {
     try {
         const c = await getConversation(ctx, m.conversation_id);
@@ -136,23 +196,58 @@ async function alreadyMoved(ctx, m) {
         throw e;
     }
 }
+function requireExplicitWorktreeScope(plan, values, sessionId) {
+    if (!plan || values['preserve-all-worktrees'] === true || values['this-worktree-only'] === true)
+        return;
+    const omitted = omittedLocalRefs(plan);
+    if (plan.trees.length > 1 || omitted.length)
+        throw new UsageError(`This repository has ${plan.trees.length} registered worktrees and ${omitted.length} other local refs${plan.referenced.length ? `; the session references ${plan.referenced.length} other worktrees` : ''}. Normal migration omits those refs and other worktree files. Inspect paths and bytes with shard move --session ${sessionId} --plan, then choose --preserve-all-worktrees or explicitly --this-worktree-only.`);
+}
 export async function moveSession(ctx, values) {
     const env = { ...process.env, ...ctx.io.env };
     const here = projectRoot(typeof values.path === 'string' ? values.path : process.cwd());
     const s = chooseSession(values, env, here);
-    const folder = typeof values.path === 'string' ? here : projectRoot(existsSync(s.cwd) ? s.cwd : here);
+    const folder = moveFolder(s, here, typeof values.path === 'string');
     const prior = movedSession(ctx.store.dir, ctx.apiUrl, s.harness, s.session_id);
-    if (prior) {
+    if (prior && values.plan !== true) {
         const live = await alreadyMoved(ctx, prior);
         if (live) {
             out(ctx, `This session already continues in the cloud as ${prior.key}. Open it: shard agents open ${prior.key}\n`, { already: true, moved: prior, conversation: live });
             return 0;
         }
     }
-    await waitForTurnEnd(ctx, s, env);
+    if (values.plan !== true) {
+        // A local MCP caller is still in its turn. Report the required scope choice
+        // before waiting, so it can answer while it still runs on this computer.
+        if (values['preserve-all-worktrees'] !== true && values['this-worktree-only'] !== true) {
+            const current = completeRecords(readTranscript(s.file));
+            confirmedCwds(s, current, folder);
+            requireExplicitWorktreeScope(await inspectWorktreeMigration(folder, current, ctx.signal), values, s.session_id);
+        }
+        await waitForTurnEnd(ctx, s, env);
+    }
     const bytes = completeRecords(readTranscript(s.file));
     if (bytes.length > TRANSCRIPT_LIMIT)
         throw new UsageError('This session’s transcript is above the 256 MiB move bound.');
+    if (values['preserve-all-worktrees'] && values['this-worktree-only'])
+        throw new UsageError('Choose --preserve-all-worktrees or --this-worktree-only.');
+    const plan = values['this-worktree-only'] === true && values.plan !== true ? null : await inspectWorktreeMigration(folder, bytes, ctx.signal);
+    // Refuse before syncing credentials, creating a VM or snapshotting an unrelated
+    // folder. An explicit all-worktree scope also accepts record-confirmed linked owners.
+    confirmedCwds(s, bytes, folder, values['preserve-all-worktrees'] === true || values.plan === true ? plan ?? undefined : undefined);
+    if (values.plan === true || values['preserve-all-worktrees'] === true) {
+        if (!plan)
+            throw new UsageError('Preserve-all-worktrees requires a Git repository.');
+        await captureWorktreeMigration(plan, ctx.signal);
+        const scope = migrationScope(plan);
+        if (values.plan === true) {
+            out(ctx, `${JSON.stringify(scope, null, 2)}\n`, scope);
+            return 0;
+        }
+        ctx.io.stderr.write(`Preserving ${plan.trees.length} registered worktrees, ${plan.files} files, ${plan.bytes} file bytes (archives add headers). Includes ignored files and Git metadata:\n${plan.trees.map(t => `  ${t.source}`).join('\n')}\nSymlink targets and unrelated sibling folders are not uploaded.\n`);
+    }
+    else
+        requireExplicitWorktreeScope(plan, values, s.session_id);
     const sha256 = createHash('sha256').update(bytes).digest('hex');
     if (!ctx.json)
         ctx.io.stderr.write(`Moving ${s.harness === 'claude' ? 'Claude Code' : 'Codex'} session “${s.title}” to the cloud…\n`);
@@ -162,11 +257,16 @@ export async function moveSession(ctx, values) {
         requireClaudeTerminal(ctx);
     let created;
     let placed;
+    let preserved;
     try {
         created = await createConversation(ctx, folder, s.harness, 'terminal', undefined, {}, {
             session_id: s.session_id, title: s.title,
+            ...(values['preserve-all-worktrees'] === true && plan ? { preserveWorktrees: true,
+                seedRepository: async (ws, c) => { preserved = await preserveWorktreeMigration(ws.cell(), plan, c, ctx.signal); } } : {}),
             // The workspace's cell handle is shared with the seed that follows: it stays open.
-            beforeSeed: async (ws, c) => { placed = await placeTranscript(ws.cell(), c, s, bytes, folder, ctx.signal); },
+            beforeSeed: async (ws, c) => {
+                placed = await placeTranscript(ws.cell(), c, s, bytes, folder, ctx.signal, values['preserve-all-worktrees'] === true && plan ? plan : undefined);
+            },
         });
     }
     catch (e) {
@@ -198,7 +298,7 @@ export async function moveSession(ctx, values) {
     if (!attach) {
         const quiet = { ...ctx, io: { ...ctx.io, stdout: { write: () => true } } };
         await conversationTerminal(quiet, ws, c, place, { ...values, detach: true });
-        out(ctx, `Moved to the cloud as ${c.key}: the same session, with its history. Open it: shard agents open ${c.key}\n`, { moved, conversation: c, workspace: ws.data, ...(placed ? { transcript: placed } : {}) });
+        out(ctx, `Moved to the cloud as ${c.key}: the same session, with its history. Open it: shard agents open ${c.key}\n`, { moved, conversation: c, workspace: ws.data, ...(placed ? { transcript: placed } : {}), ...(preserved ? { preserved } : {}) });
         return 0;
     }
     const where = openInChoices(ctx, project.slug)[s.harness];
@@ -208,7 +308,7 @@ export async function moveSession(ctx, values) {
         if (where === 'claude-desktop')
             return openClaudeDesktopSession(ctx, ws, c);
         const url = await remoteControlUrl(ctx, ws, c);
-        if (!openUrl(url, ctx.io.env))
+        if (!(await openUrl(url, ctx.io.env)))
             throw new Error(`could not open ${url}`);
         out(ctx, `${url}\n`, { moved, conversation: c, url });
         return 0;
@@ -223,7 +323,7 @@ export function listMovable(ctx, values, env, now = Date.now()) {
     const sessions = listLocalSessions(folder, env, { harness: harnessOf(values), limit: 10 }).map(s => {
         const m = moved[movedKey(s.harness, s.session_id)];
         const state = sessionState(s, env, now);
-        return { harness: s.harness, session_id: s.session_id, title: s.title, updated_at: s.updated_at, source: s.source, cwd: s.cwd,
+        return { harness: s.harness, session_id: s.session_id, title: s.title, updated_at: s.updated_at, source: s.source, cwd: s.cwd, cwds: s.cwds,
             running: state.running, turn: state.turn,
             moved: m ? { conversation_id: m.conversation_id, key: m.key, moved_at: m.moved_at, diverged: continuedAfter(s, m.bytes) } : null };
     });

package/dist/onboarding.d.ts

@@ -1,6 +1,7 @@
 import type { Ctx } from './commands.js';
 import type { Values } from './args.js';
 import type { CodexConnectorView, CodexHealth } from './codex-cloud.js';
+import type { MachineRow } from './machine-status.js';
 /**
  * The first-run demo's task: it shows the agent's own computer at work. The user copies it and pastes it into the
  * launcher themselves; Daylight's own CLAUDE.md and AGENTS.md say how to run it and test it in the desktop browser.
@@ -13,7 +14,7 @@ export type AgentApp = 'claude' | 'codex';
  * rest (Claude Code's installer uses ~/.local/bin).
  */
 export declare function installDirs(home: string): string[];
-/** Claude Code or Codex is on this Mac: its home folder (~/.claude, ~/.codex) or its command on PATH or in an install folder. */
+/** Claude Code or Codex is on this computer: its home folder (~/.claude, ~/.codex) or its command on PATH or in an install folder. */
 export declare function foundApps(env: NodeJS.ProcessEnv): Promise<AgentApp[]>;
 /** --apps claude,codex (repeatable or comma separated); unknown names are refused. */
 export declare function parseApps(value: unknown): AgentApp[] | undefined;
@@ -71,32 +72,35 @@ export interface T3SignInRow {
  * appears in T3 Code and the T3 app by itself. `startSignIn` (`--t3-connect`) starts that sign-in. Null when T3 Code
  * is not installed.
  */
-export declare function t3Connection(ctx: Ctx, signedIn: boolean, appDirs?: string[], platform?: NodeJS.Platform, startSignIn?: boolean): Promise<Connection | null>;
+export declare function t3Connection(ctx: Ctx, signedIn: boolean, appDirs?: string[], platform?: NodeJS.Platform, startSignIn?: boolean, scope?: Values): Promise<Connection | null>;
 /** Claude: the account login is ready and Claude itself accepts it right now. */
 export declare function claudeConnection(row: CredentialRow | undefined): Omit<Connection, 'id' | 'picked' | 'found'>;
-/** Codex: this Mac's Codex login is copied and the account's Codex remote device (one executor) is connected. */
+/** Codex: this computer's Codex login is copied and the account's Codex remote device (one executor) is connected. */
 export declare function codexConnection(local: boolean, synced: boolean, connector: CodexConnectorView | null, health: CodexHealth): Omit<Connection, 'id' | 'picked' | 'found'>;
 /**
  * The onboarding report, for an agent setting itself up from chat and for the menu bar app. It verifies every
  * connection live: the Shardflux account, Claude (Claude itself accepts the login) and Codex (the login is copied and
- * the account's Codex remote device is connected), for the apps picked (--apps, else saved, else found on this Mac).
+ * the account's Codex remote device is connected), for the apps picked (--apps, else saved, else found on this computer).
  * With --connect it also does what needs no sign-in: copies the Codex login and enables the Codex remote device.
  */
-export declare function onboardingReport(ctx: Ctx, values: Values): Promise<{
+export declare function onboardingReport(ctx: Ctx, values: Values, platform?: NodeJS.Platform): Promise<{
     version: number;
     api_url: string;
     apps: AgentApp[];
     found_apps: AgentApp[];
     connections: Connection[];
     ready: boolean;
+    connections_ready: boolean;
+    machine_ready: boolean | null;
     account_error: string | null;
+    machine: MachineRow | null;
     demo: {
         prompt: string;
         project: string;
         prepare: string[];
     };
     activity: {
-        state: "running" | "failed" | "suspended" | "deleted" | "creating" | "starting" | "suspending" | "resuming" | "forking" | "stopping" | "deleting";
+        state: "running" | "failed" | "creating" | "starting" | "suspending" | "suspended" | "resuming" | "forking" | "stopping" | "deleting" | "deleted";
         workspace: {
             id: string;
             key: string;
@@ -180,7 +184,7 @@ interface ProcessRow {
 export declare function activeCommands(processes: ProcessRow[]): string[];
 /** Commands and listening ports of a running VM. Never wakes a parked computer. */
 export declare function liveActivity(ctx: Ctx, ref: string): Promise<{
-    state: "running" | "failed" | "suspended" | "deleted" | "creating" | "starting" | "suspending" | "resuming" | "forking" | "stopping" | "deleting";
+    state: "running" | "failed" | "creating" | "starting" | "suspending" | "suspended" | "resuming" | "forking" | "stopping" | "deleting" | "deleted";
     workspace: {
         id: string;
         key: string;