@shardflux/cli 0.15.1 → 0.16.0

package/dist/worktree-twin.js

@@ -0,0 +1,718 @@
+/**
+ * The live twin (0.16.0+): finished cloud conversations land in the user's local worktree with no input.
+ * Design: docs/progress/cross-conversation-files.md, "Design note: building the live twin".
+ *
+ * - A twin is one snapshot commit per local worktree (its working state as `git add -A` sees it, first parent the
+ *   checked-out branch tip), written with a private index; the user's index, HEAD and branches are not touched.
+ * - The twin is snapshotted when the cloud needs it and carried inside an operation that already has a VM awake
+ *   (a landing in the finished conversation's VM, a seed in a new conversation's VM): no timer keeps a VM awake.
+ * - worktree-twin-land.py runs in the conversation's VM and returns the new branch tip and the result tree; the
+ *   device helper applies them here (quiet period, compare-and-swap, backups, atomic writes, index refresh).
+ */
+import { spawn } from 'node:child_process';
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, symlinkSync, utimesSync, writeFileSync } from 'node:fs';
+import { open, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { AgentStateStore } from "./agent-state.js";
+import { MAX_SYNC_FILE_BYTES } from "./project-sync-manifest.js";
+import { SYNC_CHUNK_BYTES } from "./project-sync-transfer.js";
+/** Files above this stay at HEAD's version in a twin (the bound the seed copy already uses). */
+export const TWIN_MAX_FILE_BYTES = MAX_SYNC_FILE_BYTES;
+/** A file the landing rewrites must be untouched this long first. */
+export const QUIET_MS = 2000;
+export const HUB_PATH = '/shardflux/project/git/hub.git';
+const TRANSFER_LIMIT = 256 << 20;
+const INLINE_BYTES = 512 << 10;
+const BACKUP_DAYS = 14;
+const BACKUP_BYTES = 1 << 30;
+const SNAPSHOT_TRAILER = 'Shardflux-Snapshot';
+const ZERO = /^0+$/;
+export class TwinGitError extends Error {
+    code;
+    stderr;
+    constructor(args, result) {
+        super(`git ${args.find(a => !a.startsWith('-') && !a.includes('=')) ?? ''} failed (${result.code}): ${result.stderr.trim().slice(-400)}`);
+        this.code = result.code;
+        this.stderr = result.stderr;
+    }
+}
+/** Git with no hooks, no fsmonitor and no optional locks; binary-safe output. */
+export function git(cwd, args, options = {}) {
+    const full = ['-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false', ...args];
+    return new Promise((resolveResult, reject) => {
+        const child = spawn('git', full, { cwd, stdio: ['pipe', 'pipe', 'pipe'], signal: options.signal,
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_OPTIONAL_LOCKS: '0', LC_ALL: 'C', ...options.env } });
+        const out = [], err = [];
+        child.stdout.on('data', (b) => out.push(b));
+        child.stderr.on('data', (b) => err.push(b));
+        child.stdin.on('error', () => undefined);
+        child.once('error', reject);
+        child.once('close', code => {
+            const result = { code: code ?? 1, stdout: Buffer.concat(out), stderr: Buffer.concat(err).toString('utf8') };
+            if ((options.ok ?? [0]).includes(result.code))
+                resolveResult(result);
+            else
+                reject(new TwinGitError(args, result));
+        });
+        child.stdin.end(options.input ?? '');
+    });
+}
+export async function gitText(cwd, args, options = {}) {
+    return (await git(cwd, args, options)).stdout.toString('utf8').trim();
+}
+async function verifyCommit(cwd, rev) {
+    const r = await git(cwd, ['rev-parse', '-q', '--verify', `${rev}^{commit}`], { ok: [0, 1, 128] });
+    return r.code === 0 ? r.stdout.toString().trim() : '';
+}
+export async function inspectWorktree(root) {
+    const [gitDir, commonDir, top] = (await gitText(root, ['rev-parse', '--path-format=absolute', '--git-dir', '--git-common-dir', '--show-toplevel'])).split('\n');
+    const head = await verifyCommit(root, 'HEAD');
+    const branch = (await git(root, ['symbolic-ref', '-q', 'HEAD'], { ok: [0, 1] })).stdout.toString().trim();
+    return { root: realpathSync(top), gitDir: gitDir, commonDir: commonDir, head: head || null, branch: branch || null };
+}
+/** The user's own Git operation in progress: the twin waits for it. */
+export function pauseReason(info) {
+    for (const name of ['index.lock', 'MERGE_HEAD', 'CHERRY_PICK_HEAD', 'REVERT_HEAD', 'BISECT_LOG', 'rebase-merge', 'rebase-apply', 'sequencer', 'HEAD.lock']) {
+        if (existsSync(join(info.gitDir, name)))
+            return name;
+    }
+    return existsSync(join(info.commonDir, 'sequencer')) ? 'sequencer' : null;
+}
+export async function listWorktrees(anyRoot) {
+    const raw = (await git(anyRoot, ['worktree', 'list', '--porcelain', '-z'])).stdout.toString('utf8');
+    const out = [];
+    let cur = null, bare = false;
+    for (const line of raw.split('\0')) {
+        if (line.startsWith('worktree ')) {
+            cur = { root: line.slice(9), head: null, branch: null };
+            bare = false;
+        }
+        else if (line.startsWith('HEAD ') && cur)
+            cur.head = line.slice(5);
+        else if (line.startsWith('branch ') && cur)
+            cur.branch = line.slice(7);
+        else if (line === 'bare')
+            bare = true;
+        else if (line === '' && cur) {
+            if (!bare && existsSync(cur.root))
+                out.push(cur);
+            cur = null;
+        }
+    }
+    if (cur && !bare && existsSync(cur.root))
+        out.push(cur);
+    return out;
+}
+export const worktreeId = (root) => createHash('sha256').update(realpathSync(root)).digest('hex').slice(0, 16);
+export const twinRef = (id) => `refs/shard/twin/${id}`;
+export const hubTwinRef = (device, id) => `refs/shard/twin/${device}/${id}`;
+const identity = (now) => ({ GIT_AUTHOR_NAME: 'Shardflux', GIT_AUTHOR_EMAIL: 'twin@shardflux.dev', GIT_COMMITTER_NAME: 'Shardflux', GIT_COMMITTER_EMAIL: 'twin@shardflux.dev',
+    GIT_AUTHOR_DATE: `@${Math.floor(now.getTime() / 1000)} +0000`, GIT_COMMITTER_DATE: `@${Math.floor(now.getTime() / 1000)} +0000` });
+const excludedPath = (path) => path.split('/').some(part => part === '.git' || part === '.shard' || part.includes('.shard-tmp-'));
+/**
+ * One snapshot commit of the worktree's working state (what `git add -A` sees; `.shard/` and files above the size gate
+ * left at HEAD's version), first parent HEAD. Kept as refs/shard/twin/<worktree id>; an unchanged state reuses it.
+ */
+export async function snapshotWorktree(info, options) {
+    if (!info.head)
+        throw new Error('the worktree has no commit yet');
+    const id = worktreeId(info.root), max = options.maxFileBytes ?? TWIN_MAX_FILE_BYTES, signal = options.signal;
+    const dir = join(options.stateDir, 'twin');
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const index = join(dir, `${id}.${process.pid}.${randomBytes(4).toString('hex')}.index`);
+    const env = { GIT_INDEX_FILE: index };
+    try {
+        // A copy of the user's index carries its stat cache, so only changed files are hashed. The original is never written.
+        if (existsSync(join(info.gitDir, 'index'))) {
+            // The copy keeps the index's own mtime: Git re-reads a file whose stat equals its entry but which changed in the
+            // same second as the index was written ("racily clean"); a newer copy would make such an edit invisible.
+            const original = statSync(join(info.gitDir, 'index'));
+            copyFileSync(join(info.gitDir, 'index'), index);
+            utimesSync(index, original.atime, original.mtime);
+        }
+        else
+            await git(info.root, ['read-tree', info.head], { env, signal });
+        const candidates = (await git(info.root, ['ls-files', '-z', '-m', '-o', '--exclude-standard'], { signal })).stdout.toString('utf8').split('\0').filter(Boolean);
+        const held = [];
+        for (const path of candidates) {
+            if (excludedPath(path))
+                continue;
+            const st = lstatSync(join(info.root, path), { throwIfNoEntry: false });
+            if (st?.isFile() && st.size > max)
+                held.push(path);
+        }
+        const specs = ['.', ':(exclude).shard', ':(exclude,glob)**/.shard/**', ':(exclude,glob)**/*.shard-tmp-*', ...held.map(p => `:(exclude,literal)${p}`)];
+        await git(info.root, ['add', '-A', '--ignore-errors', '--pathspec-from-file=-', '--pathspec-file-nul'], { env, input: specs.join('\0') + '\0', signal });
+        if (held.length) {
+            const atHead = (await git(info.root, ['ls-tree', '-z', '--full-tree', info.head, '--', ...held], { signal })).stdout.toString('utf8').split('\0').filter(Boolean);
+            const known = new Set(atHead.map(line => line.slice(line.indexOf('\t') + 1)));
+            const lines = [...atHead, ...held.filter(p => !known.has(p)).map(p => `0 ${'0'.repeat(40)}\t${p}`)];
+            await git(info.root, ['update-index', '-z', '--index-info'], { env, input: lines.join('\0') + '\0', signal });
+        }
+        const tree = await gitText(info.root, ['write-tree'], { env, signal });
+        const headTree = await gitText(info.root, ['rev-parse', `${info.head}^{tree}`], { signal });
+        const previous = await verifyCommit(info.root, twinRef(id));
+        let commit = '';
+        if (previous) {
+            const [prevTree, prevParent] = (await gitText(info.root, ['show', '-s', '--format=%T %P', previous], { signal })).split(' ');
+            if (prevTree === tree && prevParent === info.head)
+                commit = previous;
+        }
+        if (!commit) {
+            const message = `Shardflux twin of ${basename(info.root)}${info.branch ? ` (${info.branch.replace(/^refs\/heads\//, '')})` : ''}\n\n${SNAPSHOT_TRAILER}: ${options.device}/${id}\nShardflux-Branch: ${info.branch ?? 'HEAD'}\n`;
+            commit = await gitText(info.root, ['commit-tree', tree, '-p', info.head, '-F', '-'], { env: identity(options.now ?? new Date()), input: message, signal });
+            await git(info.root, ['update-ref', twinRef(id), commit], { signal });
+        }
+        return { commit, tree, base: info.head, branch: info.branch, root: info.root, id, held, headTree };
+    }
+    finally {
+        rmSync(index, { force: true });
+    }
+}
+/** A twin for a branch checked out nowhere: its own tree, first parent its tip. */
+export async function refTwin(repo, branch, device, now = new Date()) {
+    const base = await verifyCommit(repo, branch);
+    if (!base)
+        throw new Error(`${branch} does not exist`);
+    const tree = await gitText(repo, ['rev-parse', `${base}^{tree}`]);
+    const id = createHash('sha256').update(`${realpathSync(repo)}\0${branch}`).digest('hex').slice(0, 16);
+    const commit = await gitText(repo, ['commit-tree', tree, '-p', base, '-F', '-'], { env: identity(now), input: `Shardflux twin of ${branch}\n\n${SNAPSHOT_TRAILER}: ${device}/${id}\nShardflux-Branch: ${branch}\n` });
+    await git(repo, ['update-ref', twinRef(id), commit]);
+    return { commit, tree, base, branch, root: realpathSync(repo), id, held: [], headTree: tree };
+}
+async function rawDiff(cwd, a, b) {
+    const parts = (await git(cwd, ['diff-tree', '-r', '-z', '--raw', '--no-renames', '--no-abbrev', a, b])).stdout.toString('utf8').split('\0');
+    const out = [];
+    for (let i = 0; i + 1 < parts.length; i += 2) {
+        const meta = parts[i];
+        if (!meta.startsWith(':')) {
+            i--;
+            continue;
+        }
+        const [oldMode, newMode, oldSha, newSha] = meta.slice(1).split(' ');
+        out.push({ oldMode: oldMode, newMode: newMode, oldSha: oldSha, newSha: newSha, path: parts[i + 1] });
+    }
+    return out;
+}
+const absent = (mode) => ZERO.test(mode);
+const gitlink = (mode) => mode === '160000';
+function inside(root, path) {
+    const target = resolve(root, path);
+    if (target !== root && !target.startsWith(root + sep))
+        throw new Error(`path escapes the worktree: ${path}`);
+    // No symlinked parent: the landing writes only inside the worktree it inspected.
+    let at = dirname(target);
+    while (at !== root && at.startsWith(root + sep)) {
+        const st = lstatSync(at, { throwIfNoEntry: false });
+        if (st?.isSymbolicLink())
+            throw new Error(`path traverses a symbolic link: ${path}`);
+        at = dirname(at);
+    }
+    return target;
+}
+/** The blob id Git would store for this path now (filters applied), or null when it is absent; 'other' for a directory. */
+async function diskBlob(root, path) {
+    const file = inside(root, path), st = lstatSync(file, { throwIfNoEntry: false });
+    if (!st)
+        return { sha: null, mtime: 0 };
+    const mtime = Math.max(st.mtimeMs, st.ctimeMs);
+    if (st.isSymbolicLink())
+        return { sha: await gitText(root, ['hash-object', '--stdin'], { input: readlinkSync(file) }), mtime };
+    if (!st.isFile())
+        return 'other';
+    return { sha: await gitText(root, ['hash-object', '--path', path, '--', file]), mtime };
+}
+async function blob(cwd, sha, path) {
+    return (await git(cwd, path ? ['cat-file', '--filters', `--path=${path}`, sha] : ['cat-file', 'blob', sha])).stdout;
+}
+/** Temp file next to the target, then rename: readers see the old or the new file, never a partial one. */
+async function writeAtomic(root, path, mode, content) {
+    const file = inside(root, path);
+    mkdirSync(dirname(file), { recursive: true });
+    const tmp = join(dirname(file), `.${basename(file)}.shard-tmp-${randomBytes(4).toString('hex')}`);
+    try {
+        if (mode === '120000')
+            symlinkSync(content.toString('utf8'), tmp);
+        else {
+            // Keep the file's own permissions; Git's mode only decides the execute bits.
+            const umask = process.umask(), current = lstatSync(file, { throwIfNoEntry: false });
+            const bits = current?.isFile() ? current.mode & 0o777 : 0o666 & ~umask;
+            const perms = mode === '100755' ? bits | ((bits & 0o444) >> 2) : bits & ~0o111;
+            const handle = await open(tmp, 'wx', perms);
+            try {
+                await handle.writeFile(content);
+                await handle.chmod(perms);
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        renameSync(tmp, file);
+    }
+    finally {
+        rmSync(tmp, { force: true });
+    }
+}
+function removeEmptyParents(root, file) {
+    for (let dir = dirname(file); dir !== root && dir.startsWith(root + sep); dir = dirname(dir)) {
+        try {
+            rmdirSync(dir);
+        }
+        catch {
+            return;
+        }
+    }
+}
+async function mergeFile(cwd, base, ours, theirs) {
+    const dir = join(tmpdir(), `shard-merge-${randomUUID()}`);
+    mkdirSync(dir, { mode: 0o700 });
+    try {
+        for (const [name, data] of [['ours', ours], ['base', base], ['theirs', theirs]])
+            writeFileSync(join(dir, name), data);
+        const r = await git(cwd, ['merge-file', '-p', join(dir, 'ours'), join(dir, 'base'), join(dir, 'theirs')], { ok: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10] });
+        return r.code === 0 ? r.stdout : null;
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+/** Prune twin backups older than 14 days, then the oldest while the total exceeds 1 GiB. */
+export function pruneBackups(root, now = Date.now(), maxDays = BACKUP_DAYS, maxBytes = BACKUP_BYTES) {
+    if (!existsSync(root))
+        return [];
+    const size = (p) => { const st = lstatSync(p); return st.isDirectory() ? readdirSync(p).reduce((n, e) => n + size(join(p, e)), 0) : st.size; };
+    const entries = readdirSync(root).map(name => ({ name, path: join(root, name), at: statSync(join(root, name)).mtimeMs })).sort((a, b) => a.at - b.at);
+    const removed = [];
+    let total = entries.reduce((n, e) => n + size(e.path), 0);
+    for (const e of entries) {
+        if (now - e.at > maxDays * 86_400_000 || total > maxBytes) {
+            total -= size(e.path);
+            rmSync(e.path, { recursive: true, force: true });
+            removed.push(e.name);
+        }
+    }
+    return removed;
+}
+/** Writes each backed-up file back (the current content is backed up first); files the landing created are removed. */
+export async function restoreBackup(backup, options) {
+    const manifest = JSON.parse(readFileSync(join(backup, 'manifest.json'), 'utf8'));
+    const root = realpathSync(manifest.worktree), stamp = new Date((options.now ?? Date.now)()).toISOString().replace(/[:.]/g, '-');
+    const safety = join(options.backupRoot, `${stamp}-restore-${manifest.name}-${randomBytes(3).toString('hex')}`);
+    mkdirSync(safety, { recursive: true, mode: 0o700 });
+    const restored = [];
+    for (const f of manifest.files) {
+        const target = inside(root, f.path), current = lstatSync(target, { throwIfNoEntry: false });
+        if (current?.isFile() || current?.isSymbolicLink()) {
+            mkdirSync(dirname(join(safety, 'files', f.path)), { recursive: true });
+            copyFileSync(target, join(safety, 'files', f.path));
+        }
+        if (f.saved) {
+            const source = join(backup, 'files', f.path), st = lstatSync(source);
+            await writeAtomic(root, f.path, st.isSymbolicLink() ? '120000' : (st.mode & 0o111 ? '100755' : '100644'), st.isSymbolicLink() ? Buffer.from(readlinkSync(source)) : await readFile(source));
+            restored.push(f.path);
+        }
+        else if (f.action === 'create' && current) {
+            rmSync(target, { force: true });
+            removeEmptyParents(root, target);
+            restored.push(f.path);
+        }
+    }
+    writeFileSync(join(safety, 'manifest.json'), JSON.stringify({ ...manifest, restored_from: basename(backup) }, null, 1) + '\n', { mode: 0o600 });
+    return { restored, backup: safety };
+}
+/**
+ * Moves the branch from plan.base to plan.tip and the worktree from plan.twin's tree to plan.result's tree, only where
+ * the disk still holds what the twin captured and has been quiet. Never drops a user's edit: a changed file means
+ * 'moved' (redo the round), a running Git operation 'paused', a recent write 'busy'.
+ */
+export async function applyLanding(plan, options) {
+    const now = options.now ?? Date.now, quiet = options.quietMs ?? QUIET_MS, wt = plan.worktree;
+    if (wt) {
+        const reason = pauseReason(wt);
+        if (reason)
+            return { state: 'paused', reason };
+        const head = (await git(wt.root, ['symbolic-ref', '-q', 'HEAD'], { ok: [0, 1] })).stdout.toString().trim();
+        if (head !== plan.branch)
+            return { state: 'moved', reason: 'branch_switched' };
+    }
+    if (await verifyCommit(plan.repo, plan.branch) !== plan.base)
+        return { state: 'moved', reason: 'branch_moved' };
+    if (!wt) {
+        const r = await git(plan.repo, ['update-ref', '-m', `shardflux: landed ${options.label.name}`, plan.branch, plan.tip, plan.base], { ok: [0, 1, 128] });
+        return r.code === 0 ? { state: 'applied', files: [], raced: [], backup: null, at: now() } : { state: 'moved', reason: 'branch_moved' };
+    }
+    const root = wt.root, changes = await rawDiff(root, plan.twin, plan.result);
+    const edited = [];
+    let wait = 0;
+    for (const c of changes) {
+        if (gitlink(c.oldMode) || gitlink(c.newMode))
+            continue;
+        const disk = await diskBlob(root, c.path);
+        if (disk === 'other') {
+            edited.push(c.path);
+            continue;
+        }
+        const expected = absent(c.oldMode) ? null : c.oldSha;
+        if (disk.sha !== expected) {
+            edited.push(c.path);
+            continue;
+        }
+        if (disk.sha !== null)
+            wait = Math.max(wait, quiet - (now() - disk.mtime));
+    }
+    if (edited.length)
+        return { state: 'moved', reason: 'edited', paths: edited };
+    if (wait > 0)
+        return { state: 'busy', waitMs: Math.ceil(wait) };
+    if (pauseReason(wt))
+        return { state: 'paused', reason: pauseReason(wt) };
+    // Backups first: every file this landing rewrites or removes.
+    const stamp = new Date(now()).toISOString().replace(/[:.]/g, '-');
+    const backup = join(options.backupRoot, `${stamp}-${options.label.name}-${randomBytes(3).toString('hex')}`);
+    const manifest = { version: 1, created_at: new Date(now()).toISOString(), worktree: root, branch: plan.branch, conversation_id: options.label.conversation_id,
+        name: options.label.name, title: options.label.title, from: plan.base, to: plan.tip, twin: plan.twin, result: plan.result, files: [] };
+    const writes = changes.filter(c => !gitlink(c.oldMode) && !gitlink(c.newMode));
+    if (writes.length) {
+        mkdirSync(join(backup, 'files'), { recursive: true, mode: 0o700 });
+        for (const c of writes) {
+            const action = absent(c.oldMode) ? 'create' : absent(c.newMode) ? 'delete' : 'modify';
+            let saved = false;
+            if (action !== 'create') {
+                const target = join(backup, 'files', c.path);
+                mkdirSync(dirname(target), { recursive: true });
+                if (c.oldMode === '120000')
+                    symlinkSync(readlinkSync(inside(root, c.path)), target);
+                else
+                    copyFileSync(inside(root, c.path), target);
+                saved = true;
+            }
+            manifest.files.push({ path: c.path, action, before: action === 'create' ? null : c.oldSha, after: action === 'delete' ? null : c.newSha, saved });
+        }
+        writeFileSync(join(backup, 'manifest.json'), JSON.stringify(manifest, null, 1) + '\n', { mode: 0o600 });
+        pruneBackups(options.backupRoot, now());
+    }
+    // Deletions before writes (a file can become a directory). Each file is re-checked just before it is replaced.
+    const written = [], raced = [];
+    for (const c of [...writes.filter(w => absent(w.newMode)), ...writes.filter(w => !absent(w.newMode))]) {
+        options.beforeWrite?.(c.path);
+        const disk = await diskBlob(root, c.path), expected = absent(c.oldMode) ? null : c.oldSha;
+        const current = disk === 'other' ? 'other' : disk.sha;
+        if (current !== expected) {
+            // The user saved this file between the check and now: merge three ways; a conflict keeps the user's file.
+            if (current === 'other' || current === null || absent(c.newMode) || absent(c.oldMode) || c.newMode === '120000') {
+                raced.push(c.path);
+                continue;
+            }
+            const merged = await mergeFile(root, await blob(root, c.oldSha, c.path), await readFile(inside(root, c.path)), await blob(root, c.newSha, c.path));
+            if (!merged) {
+                raced.push(c.path);
+                continue;
+            }
+            await writeAtomic(root, c.path, c.newMode, merged);
+            written.push(c.path);
+            raced.push(c.path);
+            continue;
+        }
+        if (absent(c.newMode)) {
+            const file = inside(root, c.path);
+            rmSync(file, { force: true });
+            removeEmptyParents(root, file);
+            written.push(c.path);
+            continue;
+        }
+        const content = c.newMode === '120000' ? await blob(root, c.newSha) : await blob(root, c.newSha, c.path);
+        await writeAtomic(root, c.path, c.newMode, content);
+        written.push(c.path);
+    }
+    const moved = await git(plan.repo, ['update-ref', '-m', `shardflux: landed ${options.label.name}`, plan.branch, plan.tip, plan.base], { ok: [0, 1, 128] });
+    // Lost the branch to a commit made in this instant: the files are the user's now, and the next round folds them in.
+    if (moved.code !== 0)
+        return { state: 'moved', reason: 'branch_moved' };
+    await refreshIndex(root, plan.base, plan.tip);
+    return { state: 'applied', files: written, raced, backup: writes.length ? backup : null, at: now() };
+}
+/** Index entries that equal the old tip move to the new tip; entries the user staged differently are merged three ways. */
+export async function refreshIndex(root, base, tip, attempts = 50) {
+    const changes = (await rawDiff(root, base, tip)).filter(c => !gitlink(c.oldMode) && !gitlink(c.newMode));
+    for (let attempt = 0;; attempt++) {
+        try {
+            if (changes.length) {
+                const staged = new Map();
+                for (let at = 0; at < changes.length; at += 500) {
+                    const listing = (await git(root, ['ls-files', '-s', '-z', '--', ...changes.slice(at, at + 500).map(c => `:(literal)${c.path}`)])).stdout.toString('utf8');
+                    for (const line of listing.split('\0').filter(Boolean)) {
+                        const [meta, path] = [line.slice(0, line.indexOf('\t')), line.slice(line.indexOf('\t') + 1)];
+                        const [mode, sha, stage] = meta.split(' ');
+                        if (stage !== '0' || !staged.has(path))
+                            staged.set(path, { mode: mode, sha: sha, stage: stage });
+                    }
+                }
+                const lines = [];
+                for (const c of changes) {
+                    const entry = staged.get(c.path);
+                    if (entry && entry.stage !== '0')
+                        continue; // the user's own unresolved merge state
+                    const matchesBase = entry ? !absent(c.oldMode) && entry.sha === c.oldSha && entry.mode === c.oldMode : absent(c.oldMode);
+                    if (matchesBase) {
+                        lines.push(absent(c.newMode) ? `0 ${'0'.repeat(c.newSha.length)}\t${c.path}` : `${c.newMode} ${c.newSha}\t${c.path}`);
+                        continue;
+                    }
+                    if (!entry || absent(c.oldMode) || absent(c.newMode))
+                        continue;
+                    const merged = await mergeFile(root, await blob(root, c.oldSha), await blob(root, entry.sha), await blob(root, c.newSha));
+                    if (merged)
+                        lines.push(`${entry.mode} ${await gitText(root, ['hash-object', '-w', '--stdin'], { input: merged })}\t${c.path}`);
+                }
+                if (lines.length)
+                    await git(root, ['update-index', '-z', '--index-info'], { input: lines.join('\0') + '\0' });
+            }
+            await git(root, ['update-index', '-q', '--refresh'], { ok: [0, 1] });
+            return;
+        }
+        catch (error) {
+            if (!(error instanceof TwinGitError) || !/index\.lock/.test(error.stderr) || attempt >= attempts)
+                throw error;
+            await delay(100);
+        }
+    }
+}
+let script;
+/** The landing script, shipped next to this module (src in the monorepo, dist when published). */
+export function landingScript() { return script ??= readFileSync(new URL('./worktree-twin-land.py', import.meta.url), 'utf8'); }
+export async function runLandingScript(cell, input, signal) {
+    const r = await cell.exec.run(['python3', '-c', landingScript()], { stdin: JSON.stringify(input), timeoutMs: 300_000, maxOutputBytes: 4 << 20, ...(signal ? { signal } : {}) });
+    const line = r.stdout.trim().split('\n').at(-1) ?? '';
+    if (r.exitCode !== 0 || !line.startsWith('{'))
+        return { state: 'error', reason: 'script', message: `landing script exited ${r.exitCode}: ${r.stderr.trim().slice(-400)}` };
+    return JSON.parse(line);
+}
+/** A temporary repository in the cell with the conversation's branch (and its earlier landing refs) from the hub. */
+export const HUB_CHECKOUT = `set -eu
+d=$(mktemp -d "\${TMPDIR:-/tmp}/shard-land-XXXXXX")
+git init -q "$d"
+cd "$d"
+git fetch -q --no-tags "$1" "+refs/heads/$2:refs/heads/$2"
+git fetch -q --no-tags "$1" "+refs/shard/land/$3/upto:refs/shard/land/upto" 2>/dev/null || true
+git symbolic-ref HEAD "refs/heads/$2"
+if [ -n "$4" ]; then git remote add origin "$4"; fi
+printf '%s\\n' "$d"
+`;
+export async function landingRound(cell, input) {
+    if (!input.fromHub)
+        return landingRoundIn(cell, input);
+    const hub = input.hub ?? HUB_PATH, c = input.conversation;
+    const made = await cell.exec.run(['sh', '-c', HUB_CHECKOUT, 'shard-land', hub, c.branch, c.name, input.fromHub.repoRemote ?? ''], { timeoutMs: 300_000, maxOutputBytes: 4096, ...(input.signal ? { signal: input.signal } : {}) });
+    const dir = made.stdout.trim().split('\n').at(-1) ?? '';
+    if (made.exitCode !== 0 || !dir.startsWith('/'))
+        return { state: 'error', land: { state: 'error', reason: 'hub', message: `the conversation's branch could not be read from the project hub: ${made.stderr.trim().slice(-400)}` }, timings: {} };
+    try {
+        return await landingRoundIn(cell, { ...input, conversation: { ...c, worktree_path: dir }, hub: '' });
+    }
+    finally {
+        await cell.exec.run(['rm', '-rf', '--', dir], { timeoutMs: 60_000 }).catch(() => undefined);
+    }
+}
+async function landingRoundIn(cell, input) {
+    const now = input.now ?? Date.now, t0 = now(), timings = {};
+    const mark = (name) => { timings[name] = now() - t0; };
+    const c = input.conversation, branch = `refs/heads/${input.into}`, hub = input.hub ?? HUB_PATH, vmTmp = input.vmTmp ?? '/tmp';
+    if (input.worktree) {
+        const reason = pauseReason(input.worktree);
+        if (reason)
+            return { state: 'paused', reason, timings };
+    }
+    const snap = input.worktree ? await snapshotWorktree(input.worktree, { device: input.device, stateDir: input.stateDir, signal: input.signal }) : await refTwin(input.repo, branch, input.device);
+    if (input.worktree && snap.base !== await verifyCommit(input.repo, branch))
+        return { state: 'moved', reason: 'branch_switched', timings };
+    mark('snapshot');
+    const out = `${vmTmp}/shard-land-${randomUUID()}.bundle`;
+    const send = async (known) => {
+        // The VM has the conversation's base and what earlier landings made there; the bundle carries the rest.
+        const exclude = [];
+        for (const rev of [c.base_commit, ...known])
+            if (rev && await verifyCommit(input.repo, rev))
+                exclude.push(rev);
+        const local = join(tmpdir(), `shard-twin-${randomUUID()}.bundle`), remote = `${vmTmp}/shard-twin-${randomUUID()}.bundle`, ref = twinRef(snap.id);
+        try {
+            const bundled = await git(input.repo, ['bundle', 'create', '-q', local, ref, ...(exclude.length ? ['--not', ...exclude] : [])], { ok: [0, 128] });
+            // "Refusing to create empty bundle": the VM already has every commit the twin needs.
+            if (bundled.code !== 0 && !/empty bundle/.test(bundled.stderr))
+                throw new TwinGitError(['bundle'], bundled);
+            const hasBundle = bundled.code === 0;
+            let inline, uploaded = false;
+            if (hasBundle) {
+                const bytes = await readFile(local);
+                if (bytes.length > TRANSFER_LIMIT)
+                    throw new Error('the twin exceeds the 256 MiB transfer bound');
+                // A small bundle rides in the script's input: no file round trips.
+                if (bytes.length <= INLINE_BYTES)
+                    inline = bytes.toString('base64');
+                else {
+                    for (let at = 0; at < bytes.length; at += SYNC_CHUNK_BYTES)
+                        await cell.files.write(remote, bytes.subarray(at, at + SYNC_CHUNK_BYTES), { mode: '0600', append: at > 0 });
+                    uploaded = true;
+                }
+            }
+            mark('upload');
+            try {
+                return await runLandingScript(cell, { op: 'land', repo: c.worktree_path, hub, bundle: uploaded ? remote : null, bundle_b64: inline ?? null, twin_ref: ref, twin: snap.commit,
+                    hub_twin_ref: hubTwinRef(input.device, snap.id), name: c.name, branch: c.branch, base: c.base_commit, upto: input.upto ?? '', into: input.into,
+                    mode: input.mode === 'pr' ? 'pr' : 'land', title: c.title, summary: c.summary, conversation_id: c.id, out }, input.signal);
+            }
+            finally {
+                if (uploaded)
+                    await cell.files.remove(remote).catch(() => undefined);
+            }
+        }
+        finally {
+            await rm(local, { force: true });
+        }
+    };
+    let land = await send(input.known ?? []);
+    // A VM that lacks an earlier landing (the conversation moved) gets everything since the conversation's base.
+    if (land.state === 'error' && (land.reason === 'prerequisites' || land.reason === 'twin_missing'))
+        land = await send([]);
+    mark('merge');
+    if (land.state === 'noop' && land.upto) {
+        // Nothing to write here, but the conversation's work is in the branch: record it as landed in its VM too.
+        await runLandingScript(cell, { op: 'confirm', repo: c.worktree_path, hub, name: c.name, upto: land.upto, into: input.into }, input.signal).catch(() => undefined);
+    }
+    if (land.state !== 'ready')
+        return { state: land.state === 'error' ? 'error' : land.state, land, timings };
+    const fetched = join(tmpdir(), `shard-land-${randomUUID()}.bundle`);
+    const tipRef = `refs/shard/land/${c.name}/tip`, resultRef = `refs/shard/land/${c.name}/result`;
+    try {
+        let bytes;
+        if (land.bundle_b64)
+            bytes = Buffer.from(land.bundle_b64, 'base64');
+        else {
+            const info = await cell.files.stat(out);
+            if (info.size > TRANSFER_LIMIT)
+                throw new Error('the landing exceeds the 256 MiB transfer bound');
+            bytes = await cell.files.read(out, { length: info.size + 1 });
+            if (bytes.length !== info.size)
+                throw new Error('the landing bundle changed while it was read');
+        }
+        await writeFile(fetched, bytes, { mode: 0o600 });
+        await git(input.repo, ['fetch', '-q', '--no-tags', fetched, `+refs/shard/land/tip:${tipRef}`, `+refs/shard/land/result:${resultRef}`]);
+        if (await verifyCommit(input.repo, tipRef) !== land.tip || await verifyCommit(input.repo, resultRef) !== land.result)
+            throw new Error('the landing bundle does not match the landing');
+    }
+    finally {
+        await rm(fetched, { force: true });
+        if (!land.bundle_b64)
+            await cell.files.remove(out).catch(() => undefined);
+    }
+    mark('download');
+    const outcome = await applyLanding({ worktree: input.worktree, repo: input.repo, branch, base: land.base, twin: land.twin, tip: land.tip, result: land.result }, { backupRoot: input.backupRoot, quietMs: input.quietMs, now, label: { conversation_id: c.id, name: c.name, title: c.title } });
+    mark('apply');
+    await git(input.repo, ['update-ref', '-d', resultRef], { ok: [0, 1] });
+    await git(input.repo, ['update-ref', '-d', tipRef], { ok: [0, 1] });
+    if (outcome.state !== 'applied')
+        return { ...outcome, reason: 'reason' in outcome ? outcome.reason : 'busy', land, timings };
+    // The files are on disk. Recording the landing in the VM and copying it to the project hub (shared storage, seconds)
+    // runs after, without holding up the next landing.
+    const confirmed = runLandingScript(cell, { op: 'confirm', repo: c.worktree_path, hub, name: c.name, upto: land.upto, into: input.into,
+        twin: land.twin, hub_twin_ref: hubTwinRef(input.device, snap.id), tip: land.tip, result: land.result }, input.signal).then(r => {
+        if (r.state === 'error')
+            throw new Error(`landing confirmation failed: ${r.message ?? r.reason}`);
+        timings.confirm = now() - t0;
+    });
+    confirmed.catch(() => undefined);
+    return { state: 'landed', land, applied: outcome, timings, confirmed };
+}
+export class TwinLedger {
+    store;
+    constructor(dir) { this.store = new AgentStateStore(dir); }
+    read() { return this.store.read().worktree_twin ?? {}; }
+    mode(project) { return this.read().landing?.[project] ?? 'auto'; }
+    setMode(project, mode) { this.update(doc => { doc.landing = { ...doc.landing, [project]: mode }; }); }
+    conversation(id) { return this.read().conversations?.[id] ?? {}; }
+    patch(id, change) {
+        this.update(doc => { doc.conversations = { ...doc.conversations, [id]: { ...doc.conversations?.[id], ...change } }; });
+    }
+    forget(id) { this.update(doc => { if (doc.conversations)
+        delete doc.conversations[id]; }); }
+    update(change) {
+        this.store.update(state => { const doc = state.worktree_twin ?? {}; change(doc); state.worktree_twin = doc; });
+    }
+}
+export const backupRoot = (stateDir) => join(stateDir, 'twin-backups');
+export function relativeTo(root, path) { return relative(root, path) || '.'; }
+// ---------------------------------------------------------------------------------------------------------------
+// Seeding a new conversation from the twin
+/** This computer's device id (the device helper's), created on first use. */
+export function deviceId(stateDir) {
+    const file = join(stateDir, 'device-id');
+    try {
+        const id = readFileSync(file, 'utf8').trim();
+        if (/^[a-zA-Z0-9-]{8,64}$/.test(id))
+            return id;
+    }
+    catch { /* first use */ }
+    const id = randomUUID();
+    mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+    try {
+        writeFileSync(file, id + '\n', { mode: 0o600, flag: 'wx' });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    return readFileSync(file, 'utf8').trim();
+}
+/**
+ * The commit a new conversation starts from: HEAD when the worktree is clean (or landing is off, or the user's Git
+ * operation is running), else the twin snapshot S (first parent HEAD). The conversation's own work is then S..T, and
+ * the user's edits stay theirs.
+ */
+export async function twinSeed(stateDir, folder, head, project) {
+    if (project && new TwinLedger(stateDir).mode(project) === 'off')
+        return { commit: head, snapshot: false };
+    const info = await inspectWorktree(folder);
+    if (info.head !== head || pauseReason(info))
+        return { commit: head, snapshot: false };
+    const snap = await snapshotWorktree(info, { device: deviceId(stateDir), stateDir });
+    return snap.tree === snap.headTree ? { commit: head, snapshot: false } : { commit: snap.commit, snapshot: true };
+}
+export function rememberTwinSeed(stateDir, conversation, folder, seed, branch) {
+    new TwinLedger(stateDir).patch(conversation, { seed: seed.commit, seed_snapshot: seed.snapshot, folder, ...(branch ? { base_branch: branch } : {}) });
+}
+/** Carries a snapshot seed into the conversation's VM repository (one small bundle: the snapshot over HEAD). */
+export async function sendTwinSeed(stateDir, cell, conversation, folder, signal) {
+    const state = new TwinLedger(stateDir).conversation(conversation.id);
+    if (!state.seed_snapshot || state.seed !== conversation.base_commit)
+        return;
+    const ref = `refs/shard/seed-tmp/${randomUUID()}`, local = join(tmpdir(), `shard-seed-${randomUUID()}.bundle`), remote = `/tmp/shard-seed-${randomUUID()}.bundle`;
+    await git(folder, ['update-ref', ref, conversation.base_commit]);
+    try {
+        await git(folder, ['bundle', 'create', '-q', local, ref, '--not', `${conversation.base_commit}^1`]);
+        const bytes = await readFile(local);
+        if (bytes.length > TRANSFER_LIMIT)
+            throw new Error('the uncommitted changes exceed the 256 MiB transfer bound');
+        for (let at = 0; at < bytes.length; at += SYNC_CHUNK_BYTES)
+            await cell.files.write(remote, bytes.subarray(at, at + SYNC_CHUNK_BYTES), { mode: '0600', append: at > 0 });
+        const r = await cell.exec.run(['git', '-C', conversation.worktree_path, '-c', 'core.hooksPath=/dev/null', 'fetch', '-q', '--no-tags', remote, `+${ref}:refs/shard/twin-seed`], { timeoutMs: 120_000, ...(signal ? { signal } : {}) });
+        if (r.exitCode !== 0)
+            throw new Error(`the conversation could not receive its starting snapshot: ${r.stderr.trim()}`);
+    }
+    finally {
+        await git(folder, ['update-ref', '-d', ref], { ok: [0, 1] });
+        await rm(local, { force: true });
+        await cell.files.remove(remote).catch(() => undefined);
+    }
+}
+/**
+ * The conversation branch at its base. A snapshot base already matches the copied files: the branch starts at HEAD
+ * and moves to the snapshot without touching them (`checkout` would refuse the "local changes").
+ */
+export function twinCheckoutArgv(stateDir, conversation) {
+    const state = new TwinLedger(stateDir).conversation(conversation.id);
+    if (!state.seed_snapshot || state.seed !== conversation.base_commit)
+        return ['git', '-C', conversation.worktree_path, 'checkout', '-B', conversation.branch, conversation.base_commit];
+    return ['sh', '-c', 'set -e; git -C "$1" checkout -q -B "$2" HEAD; git -C "$1" reset -q --mixed "$3"', 'shard-seed', conversation.worktree_path, conversation.branch, conversation.base_commit];
+}