@shardflux/cli 0.20.0 → 0.22.0

package/dist/move-worktrees-restore.py

@@ -0,0 +1,144 @@
+"""Restore an owned migration into an EMPTY folder; never overwrite continued work.
+
+The immutable archives retain original Git metadata. Only location pointers in the
+restored copy change. Can be run again with a new empty root for recovery.
+"""
+import hashlib
+import json
+import os
+from pathlib import Path, PurePosixPath
+import shutil
+import subprocess
+import sys
+import tarfile
+
+manifest = Path(sys.argv[1]).resolve()
+plan = json.loads(manifest.read_text())
+root = Path(sys.argv[2]).absolute()
+if root.is_symlink() or (root.exists() and any(root.iterdir())):
+    raise ValueError("Restore requires a new empty folder; existing work was not replaced")
+root.mkdir(parents=True, exist_ok=True)
+
+def destination(target):
+    parts = PurePosixPath(target).parts
+    if target != "." and (target.startswith("/") or any(p in ("", "..") for p in parts)):
+        raise ValueError("Unsafe worktree destination")
+    return root if target == "." else root.joinpath(*parts)
+
+targets = {t["source"]: destination(t["target"]) for t in plan["trees"]}
+expected = plan["bytes"] + plan["files"] * 1024
+if shutil.disk_usage(root).free < expected:
+    raise ValueError(f"Restore requires at least {expected} free bytes on the target filesystem")
+
+def parents_safe(path, base):
+    parent = path.parent
+    while parent != base:
+        if parent.is_symlink():
+            raise ValueError("Archive parent is a symlink")
+        if parent == parent.parent:
+            raise ValueError("Archive escaped its root")
+        parent = parent.parent
+    if base.is_symlink():
+        raise ValueError("Archive root is a symlink")
+
+for i, tree in enumerate(plan["trees"]):
+    base = targets[tree["source"]]
+    base.mkdir(parents=True, exist_ok=True)
+    directories = []
+    with tarfile.open(manifest.parent / f"{i}.tar", "r:") as archive:
+        for member in archive:
+            parts = PurePosixPath(member.name).parts
+            if member.name in (".", "./"):
+                continue
+            if member.name.startswith("/") or any(p in ("", "..") for p in parts):
+                raise ValueError("Unsafe archive member")
+            path = base.joinpath(*parts)
+            parents_safe(path, base)
+            if member.isdir():
+                if path.is_symlink():
+                    raise ValueError("Archive directory is a symlink")
+                path.mkdir(parents=True, exist_ok=True)
+                directories.append((path, member.mode & 0o777, member.mtime))
+            elif member.issym():
+                path.parent.mkdir(parents=True, exist_ok=True)
+                path.symlink_to(member.linkname)
+            elif member.isreg() or member.islnk():
+                # Expand hard links: Git index/content is preserved, no link may escape.
+                path.parent.mkdir(parents=True, exist_ok=True)
+                with archive.extractfile(member) as src, path.open("xb") as out:
+                    shutil.copyfileobj(src, out, 1024 * 1024)
+                path.chmod(member.mode & 0o777)
+                os.utime(path, (member.mtime, member.mtime))
+            else:
+                raise ValueError("Special archive member is not supported")
+    # Read-only directory modes must be applied after writing their contents.
+    for path, mode, mtime in reversed(directories):
+        path.chmod(mode)
+        os.utime(path, (mtime, mtime))
+    for entry in tree["files"]:
+        path = base / entry["path"]
+        if "link" in entry:
+            if not path.is_symlink() or os.readlink(path) != entry["link"]:
+                raise ValueError(f"Symlink verification failed: {path}")
+            digest = hashlib.sha256(("symlink\0" + entry["link"]).encode()).hexdigest()
+        else:
+            if path.is_symlink() or not path.is_file() or path.stat().st_size != entry["size"]:
+                raise ValueError(f"File size/type verification failed: {path}")
+            sha = hashlib.sha256()
+            with path.open("rb") as src:
+                for chunk in iter(lambda: src.read(1024 * 1024), b""):
+                    sha.update(chunk)
+            digest = sha.hexdigest()
+            if path.stat().st_mode & 0o777 != entry["mode"]:
+                raise ValueError(f"File mode verification failed: {path}")
+        if digest != entry["sha256"]:
+            raise ValueError(f"File hash verification failed: {path}")
+
+common = targets[plan["main"]] / ".git"
+env = {**os.environ, "GIT_OPTIONAL_LOCKS": "0", "GIT_TERMINAL_PROMPT": "0"}
+def git(tree, *args):
+    return subprocess.run(["git", "-C", str(tree), "-c", "core.hooksPath=/dev/null", *args],
+                          env=env, check=True, stdout=subprocess.PIPE).stdout
+
+# Repair forward/back pointers without running checkout/reset or refreshing an index.
+for tree in plan["trees"]:
+    dest = targets[tree["source"]]
+    if tree["gitDir"] != plan["commonDir"]:
+        gitdir = common / Path(tree["gitDir"]).relative_to(plan["commonDir"])
+        (dest / ".git").write_text(f"gitdir: {gitdir}\n")
+        (gitdir / "gitdir").write_text(f"{dest / '.git'}\n")
+        (gitdir / "commondir").write_text(os.path.relpath(common, gitdir) + "\n")
+        worktree_config = gitdir / "config.worktree"
+        if worktree_config.exists():
+            subprocess.run(["git", "config", "--file", str(worktree_config), "core.worktree", str(dest)], check=True)
+git(targets[plan["main"]], "config", "core.worktree", str(targets[plan["main"]]))
+# External registered worktrees live in this private recovery area, outside the
+# selected checkout's tracked content. Hide only that explicit location.
+exclude = common / "info/exclude"
+exclude.parent.mkdir(parents=True, exist_ok=True)
+with exclude.open("a") as out:
+    out.write("\n/.shard/preserved-worktrees/\n")
+
+selected = targets[plan["selected"]]
+refs = git(selected, "for-each-ref", "--format=%(objectname) %(refname)").decode()
+if refs != plan["refs"]:
+    raise ValueError("Local refs did not survive migration")
+for tree in plan["trees"]:
+    dest = targets[tree["source"]]
+    if git(dest, "rev-parse", "HEAD").decode().strip() != tree["head"]:
+        raise ValueError(f"HEAD did not survive migration: {dest}")
+    status = git(dest, "status", "--porcelain=v1", "-z", "--untracked-files=all").decode()
+    if status != tree["status"]:
+        raise ValueError(f"Git status changed during migration: {dest}")
+
+# The platform tracks this conversation by its own branch; the original branch
+# and raw HEAD remain in refs/archives. Index and working bytes stay untouched.
+branch = plan["branch"]
+git(selected, "check-ref-format", branch)
+if any(line.endswith(" " + branch) for line in refs.splitlines()):
+    raise ValueError("Conversation branch collides with a preserved local ref")
+if "--defer-conversation-branch" not in sys.argv[3:]:
+    git(selected, "update-ref", branch, git(selected, "rev-parse", "HEAD").decode().strip())
+    git(selected, "symbolic-ref", "HEAD", branch)
+print(json.dumps({"worktrees": len(plan["trees"]), "files": plan["files"], "bytes": plan["bytes"],
+                  "root": str(root), "refs": len(refs.splitlines()), "status": "matched"}))

package/dist/move-worktrees.d.ts

@@ -0,0 +1,63 @@
+import type { SyncCell } from './project-sync-transfer.js';
+export interface MigrationFile {
+    path: string;
+    size: number;
+    mode: number;
+    sha256: string;
+    link?: string;
+}
+export interface MigrationTree {
+    source: string;
+    spellings: string[];
+    target: string;
+    head: string;
+    branch: string;
+    gitDir: string;
+    status: string;
+    files: MigrationFile[];
+    exclude: string[];
+}
+export interface WorktreeMigration {
+    version: 1;
+    selected: string;
+    commonDir: string;
+    main: string;
+    refs: string;
+    trees: MigrationTree[];
+    bytes: number;
+    files: number;
+    referenced: string[];
+}
+/** Git is the source of membership; sibling folders and symlink targets never expand the upload scope. */
+export declare function inspectWorktreeMigration(folder: string, transcript: Buffer, signal?: AbortSignal): Promise<WorktreeMigration | null>;
+/** Size/hash pass only after preserve-all is selected (ignored caches may be large). */
+export declare function captureWorktreeMigration(plan: WorktreeMigration, signal?: AbortSignal): Promise<void>;
+export declare function migrationScope(plan: WorktreeMigration): {
+    worktrees: {
+        path: string;
+        branch: string;
+        target: string;
+    }[];
+    referenced: string[];
+    local_refs: string[];
+    bytes: number;
+    files: number;
+    scope: string;
+    size_basis: string;
+};
+/** User refs a normal move leaves behind. Shardflux's own refs/shard/* (twin snapshots, land and agent refs) are rebuilt, never user work. */
+export declare function omittedLocalRefs(plan: WorktreeMigration): string[];
+/** Longest paths first, before replacing a parent. Message text and signed thinking keep the existing rewrite contract. */
+export declare function rewriteWorktreeTranscript(bytes: Buffer, plan: WorktreeMigration, root: string): Buffer;
+export interface MigrationResult {
+    snapshot: string;
+    bytes: number;
+    worktrees: number;
+    files: number;
+}
+/** Called instead of regular seeding: the guest starts only after its refs, index, bytes and statuses are checked. */
+export declare function preserveWorktreeMigration(cell: SyncCell, plan: WorktreeMigration, c: {
+    id: string;
+    branch: string;
+    worktree_path: string;
+}, signal?: AbortSignal): Promise<MigrationResult>;

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 };
     });