@shardflux/cli 0.20.0 → 0.23.0

package/dist/menubar.js

@@ -16,7 +16,7 @@ const execute = promisify(execFile);
  * whether or not a built Shardflux.app is in the package.
  */
 export const nativeTools = {
-    run: async (tool, args, signal) => (await execute(tool, args, { timeout: 15000, maxBuffer: 1024 * 1024, signal })).stdout,
+    run: async (tool, args, signal, env) => (await execute(tool, args, { timeout: 15000, maxBuffer: 1024 * 1024, signal, ...(env ? { env: { ...process.env, ...env } } : {}) })).stdout,
 };
 const BUNDLE_ID = 'dev.shardflux.menubar';
 export function compareBundleVersions(left, right) {
@@ -123,7 +123,7 @@ export class MenubarManager {
     constructor(options = {}) {
         this.app = join(options.home ?? homedir(), 'Applications', 'Shardflux.app');
         this.#platform = options.platform ?? process.platform;
-        this.#run = options.run ?? ((tool, args) => nativeTools.run(tool, args, options.signal));
+        this.#run = options.run ?? ((tool, args, env) => nativeTools.run(tool, args, options.signal, env));
         this.#packageApp = options.packageApp ?? (() => {
             const app = packagedAppPath();
             if (!app)
@@ -160,43 +160,51 @@ export class MenubarManager {
             return null;
         }
     }
-    async #control(action, ...args) {
+    /**
+     * The app's --control for `configDir`: its pids are the app running for that config directory, wherever it runs from
+     * (menu bar 0.8.4+, one app per config directory), and any app running from the installed bundle.
+     */
+    async #control(configDir, action, ...args) {
         makeExecutable(this.app);
-        return parseNativeStatus(await this.#run(join(this.app, 'Contents', 'MacOS', 'ShardfluxMenuBar'), ['--control', action, ...args]));
+        const env = configDir ? { SHARDFLUX_CONFIG_DIR: configDir } : undefined;
+        return parseNativeStatus(await this.#run(join(this.app, 'Contents', 'MacOS', 'ShardfluxMenuBar'), ['--control', action, ...args], env));
     }
-    async status() {
+    async status(configDir) {
         this.#requireMac();
         if (!existsSync(this.app))
             return { installed: false, version: null, running: false, pids: [], login: 'off' };
         const version = await this.#version(this.app);
-        return { installed: true, version, ...await this.#control('status') };
+        return { installed: true, version, ...await this.#control(configDir, 'status') };
     }
     async #stripQuarantine() {
         const attributes = await this.#run('/usr/bin/xattr', ['-lr', this.app]);
         if (attributes.includes('com.apple.quarantine'))
             await this.#run('/usr/bin/xattr', ['-dr', 'com.apple.quarantine', this.app]);
     }
-    async stop() {
-        const current = await this.status();
+    async stop(configDir) {
+        const current = await this.status(configDir);
         if (!current.installed || !current.running)
             return current;
-        await this.#control('stop');
+        await this.#control(configDir, 'stop');
         for (let i = 0; i < 20; i++) {
-            const status = await this.status();
+            const status = await this.status(configDir);
             if (!status.running)
                 return status;
             await new Promise(resolve => setTimeout(resolve, 100));
         }
         throw new UsageError('Shardflux is still stopping. Run shard menubar status before retrying.');
     }
-    async login(value) {
-        if (!(await this.status()).installed)
+    async login(value, configDir) {
+        if (!(await this.status(configDir)).installed)
             throw new UsageError('Run shard menubar start before changing launch at login.');
-        await this.#control('login', value);
-        return this.status();
+        await this.#control(configDir, 'login', value);
+        return this.status(configDir);
     }
-    /** Replaces the installed app with `source` (verified first), stopping it while it is swapped. */
-    async #install(source, current) {
+    /**
+     * Replaces the installed app with `source` (verified first), stopping it while it is swapped: the app running from
+     * the bundle and the one running for `configDir` from elsewhere, so no older app stays behind.
+     */
+    async #install(source, current, configDir) {
         // Verify the source before stopping or replacing any existing app.
         await this.#run('/usr/bin/codesign', ['--verify', '--deep', '--strict', source]);
         mkdirSync(dirname(this.app), { recursive: true });
@@ -206,7 +214,7 @@ export class MenubarManager {
         try {
             cpSync(source, staged, { recursive: true, dereference: false });
             if (current.running)
-                await this.stop();
+                await this.stop(configDir);
             if (current.installed)
                 renameSync(this.app, backup);
             makeExecutable(staged);
@@ -235,17 +243,19 @@ export class MenubarManager {
     async start(configDir, apiUrl) {
         this.#requireMac();
         const source = this.#packageApp(), sourceVersion = await this.#version(source);
-        const current = await this.status();
+        const current = await this.status(configDir);
         if (!current.installed || compareAppVersions(current.version, sourceVersion) < 0)
-            await this.#install(source, current);
+            await this.#install(source, current, configDir);
         await this.#stripQuarantine();
-        if (!(await this.status()).running) {
+        if (!(await this.status(configDir)).running) {
             mkdirSync(configDir, { recursive: true, mode: 0o700 });
             const log = join(configDir, 'menubar.log');
-            await this.#run('/usr/bin/open', ['-g', this.app, '--env', `SHARDFLUX_CONFIG_DIR=${configDir}`, '--env', `SHARDFLUX_API_URL=${apiUrl}`, '--stdout', log, '--stderr', log]);
+            // A start that races another one for this config directory hands over to it without opening the launcher.
+            await this.#run('/usr/bin/open', ['-g', this.app, '--env', `SHARDFLUX_CONFIG_DIR=${configDir}`, '--env', `SHARDFLUX_API_URL=${apiUrl}`,
+                '--env', 'SHARDFLUX_MENUBAR_LAUNCH=background', '--stdout', log, '--stderr', log]);
         }
         for (let i = 0; i < 20; i++) {
-            const status = await this.status();
+            const status = await this.status(configDir);
             if (status.running)
                 return status;
             await new Promise(resolve => setTimeout(resolve, 100));
@@ -260,7 +270,7 @@ export class MenubarManager {
      */
     async refresh(configDir, apiUrl) {
         this.#requireMac();
-        const current = await this.status();
+        const current = await this.status(configDir);
         if (!current.installed || !current.version)
             return { result: 'not_installed', from: null, to: null };
         const to = await this.packagedVersion(), from = current.version;
@@ -274,7 +284,7 @@ export class MenubarManager {
             await this.start(configDir, apiUrl);
             return { result: 'restarted', from, to };
         }
-        await this.#install(this.#packageApp(), current);
+        await this.#install(this.#packageApp(), current, configDir);
         await this.#stripQuarantine();
         return { result: 'installed', from, to };
     }
@@ -301,7 +311,7 @@ export async function ensureMenubar(dir, apiUrl, manager = new MenubarManager(),
     if (store.read().menubar_stopped === true)
         return undefined;
     try {
-        const status = await manager.status();
+        const status = await manager.status(dir);
         // A running app is brought up to the one this CLI carries (after `npm i -g shardflux`) by the background refresh
         // every command starts (refreshMenubarInBackground), at a moment when it shows no window.
         if (status.running)
@@ -310,7 +320,7 @@ export async function ensureMenubar(dir, apiUrl, manager = new MenubarManager(),
         if (!started.running)
             return undefined;
         if (started.login !== 'on')
-            await manager.login('on').catch(() => undefined);
+            await manager.login('on', dir).catch(() => undefined);
         return 'Menu bar started · shard menubar stop to turn it off';
     }
     catch {
@@ -468,7 +478,7 @@ export const MENUBAR_HANDLERS = Object.fromEntries(['start', 'stop', 'status'].m
         if (values.login !== undefined && !['on', 'off'].includes(String(values.login)))
             throw new UsageError('--login must be on or off.');
         const manager = new MenubarManager({ home: ctx.io.env.HOME || homedir(), signal: ctx.signal });
-        let status = action === 'start' ? await manager.start(ctx.store.dir, ctx.apiUrl) : action === 'stop' ? await manager.stop() : await manager.status();
+        let status = action === 'start' ? await manager.start(ctx.store.dir, ctx.apiUrl) : action === 'stop' ? await manager.stop(ctx.store.dir) : await manager.status(ctx.store.dir);
         // An explicit stop keeps `shard` from starting the menu bar again; an explicit start re-enables it.
         if (action !== 'status')
             new AgentStateStore(ctx.store.dir).update(doc => { if (action === 'stop')
@@ -476,7 +486,7 @@ export const MENUBAR_HANDLERS = Object.fromEntries(['start', 'stop', 'status'].m
             else
                 delete doc.menubar_stopped; });
         if (values.login === 'on' || values.login === 'off')
-            status = await manager.login(values.login);
+            status = await manager.login(values.login, ctx.store.dir);
         ctx.io.stdout.write(ctx.json ? json(status) : `Menu bar: ${status.running ? 'running' : 'stopped'}${status.installed ? ` · app ${status.version}` : ' · not installed'} · login ${status.login}\n`);
         return 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,69 @@
+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[];
+    /** Registrations Git reports as prunable (their folder or its .git is gone): nothing to copy, never a refusal. */
+    stale: string[];
+}
+/**
+ * Other registered worktrees of this repository that the session's transcript works in. A normal move leaves them on
+ * this computer; the CLI says so. Best effort: an empty list when Git cannot answer.
+ */
+export declare function referencedWorktrees(folder: string, transcript: Buffer, signal?: AbortSignal): Promise<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): {
+    local_refs: string[];
+    bytes: number;
+    files: number;
+    scope: string;
+    size_basis: string;
+    stale_registrations?: string[] | undefined;
+    worktrees: {
+        path: string;
+        branch: string;
+        target: string;
+    }[];
+    referenced: 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,252 @@
+/** 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}/`);
+/** `git worktree list --porcelain -z`: each registration's path and whether Git calls it prunable. */
+async function registeredWorktrees(folder, signal) {
+    const out = [];
+    for (const field of (await git(folder, ['worktree', 'list', '--porcelain', '-z'], signal)).split('\0')) {
+        if (field.startsWith('worktree '))
+            out.push({ path: field.slice(9), prunable: false });
+        else if ((field === 'prunable' || field.startsWith('prunable ')) && out.length)
+            out.at(-1).prunable = true;
+    }
+    return out;
+}
+/**
+ * Whether the transcript names `path` itself (or a file below it), not just a longer registered worktree path that
+ * starts with it (the main checkout is a prefix of every worktree nested inside it). JSON-escaped spellings count.
+ */
+function names(text, path, registered) {
+    const longer = registered.filter(p => p.length > path.length && p.startsWith(path));
+    for (const spelled of new Set([path, JSON.stringify(path).slice(1, -1)])) {
+        for (let at = text.indexOf(spelled); at >= 0; at = text.indexOf(spelled, at + 1)) {
+            const next = text[at + spelled.length];
+            if (next !== undefined && /[\w.-]/.test(next))
+                continue; // a sibling folder: /repo-old for /repo
+            if (longer.some(p => text.startsWith(p, at) || text.startsWith(JSON.stringify(p).slice(1, -1), at)))
+                continue;
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Other registered worktrees of this repository that the session's transcript works in. A normal move leaves them on
+ * this computer; the CLI says so. Best effort: an empty list when Git cannot answer.
+ */
+export async function referencedWorktrees(folder, transcript, signal) {
+    try {
+        const selected = await realpath(folder), text = transcript.toString('utf8');
+        const live = (await registeredWorktrees(folder, signal)).filter(w => !w.prunable).map(w => w.path);
+        const all = [...new Set([...live, selected])];
+        const others = [];
+        for (const path of live) {
+            const real = await realpath(path).catch(() => '');
+            if (!real || real === selected)
+                continue;
+            if (names(text, path, all) || (real !== path && names(text, real, all)))
+                others.push(real);
+        }
+        return others;
+    }
+    catch (e) {
+        if (signal?.aborted)
+            throw e;
+        return [];
+    }
+}
+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.');
+    // A registration whose folder (or its .git) is gone has nothing to copy: Git itself calls it prunable. It is
+    // reported, never a reason to refuse; its branch is a local ref and moves with the others.
+    const registered = [], sources = [], stale = [];
+    for (const w of await registeredWorktrees(folder, signal)) {
+        const real = w.prunable ? '' : await realpath(w.path).catch(() => '');
+        if (!real) {
+            stale.push(w.path);
+            continue;
+        }
+        registered.push(w.path);
+        sources.push(real);
+    }
+    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'), all = trees.flatMap(t => t.spellings);
+    const referenced = trees.filter(t => t.source !== folder && t.spellings.some(p => names(text, p, all))).map(t => t.source);
+    return { version: 1, selected: folder, commonDir, main, trees, referenced, stale,
+        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,
+        ...(plan.stale.length ? { stale_registrations: plan.stale } : {}),
+        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.' };
+}
+/** 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 };
+}