@shardflux/cli 0.15.1 → 0.16.0

package/dist/files-mirror.js

@@ -0,0 +1,761 @@
+import { spawn } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
+import { closeSync, existsSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, writeSync, chmodSync, unlinkSync, rmdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, posix } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { conversationsUnavailable, localConversations } from "./conversations.js";
+import { conversationClient } from "./conversation-commands.js";
+import { projectIdentity } from "./project-identity.js";
+import { withTargetLock } from "./target-lock.js";
+import { UsageError } from "./errors.js";
+/**
+ * Files across conversations on the Mac (docs/progress/cross-conversation-files.md): a read-only folder per
+ * conversation, `~/Shardflux/<repository>/<base branch>/<conversation>/`, holding what that conversation committed
+ * relative to its fork point. Git (the project hub) is the only channel; the user's own checkouts are never written.
+ * Files above the per-file limit, or past the conversation's total, are placeholders until `shard files pull`.
+ */
+export const HUB_PATH = '/shardflux/project/git/hub.git';
+export const MANIFEST = '.shardflux-manifest.json';
+export const PLACEHOLDER = '.placeholder.txt';
+export const FILES_CONFIG = '.shardflux/files.yaml';
+export const DEFAULT_MAX_FILE = 50 * 2 ** 20;
+export const DEFAULT_MAX_CONVERSATION = 2 * 2 ** 30;
+export function filesRoot(env) {
+    return env.SHARDFLUX_FILES_DIR || join(env.HOME || homedir(), 'Shardflux');
+}
+// ---- pure rules, shared with the guest's sibling view (services/guest-agent/internal/conversations/siblings.go) ----
+/** A base branch as one path component: slashes and other separators become "-". */
+export function branchFolder(branch) {
+    if (!branch)
+        return 'detached';
+    const name = branch.replaceAll('/', '-').replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^[.-]+|[.-]+$/g, '').slice(0, 100);
+    return name || 'branch';
+}
+/** A human name as one Finder path component. */
+export function humanFolder(text, fallback) {
+    const printable = [...text.normalize('NFC')].map(ch => (ch.charCodeAt(0) < 32 || ch.charCodeAt(0) === 127 ? ' ' : ch)).join('');
+    const name = printable.replace(/[/:\\]+/g, ' ').replace(/\s+/g, ' ').trim().replace(/^\.+/, '');
+    if (!name)
+        return fallback;
+    if (name.length <= 60)
+        return name;
+    const cut = name.slice(0, 60), space = cut.lastIndexOf(' ');
+    return (space > 30 ? cut.slice(0, space) : cut).trim();
+}
+export function repositoryName(identity) {
+    const tail = identity.replace(/\/+$/, '').split(/[/:]/).at(-1)?.replace(/\.git$/, '') ?? '';
+    return humanFolder(tail, 'project');
+}
+export function parseFilesConfig(text) {
+    const limits = { maxFile: DEFAULT_MAX_FILE, maxConversation: DEFAULT_MAX_CONVERSATION };
+    if (!text)
+        return limits;
+    let doc;
+    try {
+        doc = parseYaml(text);
+    }
+    catch {
+        return limits;
+    }
+    if (!doc || typeof doc !== 'object')
+        return limits;
+    const { max_file_mb: file, max_conversation_mb: total } = doc;
+    if (Number.isInteger(file) && file >= 1 && file <= 10240)
+        limits.maxFile = file * 2 ** 20;
+    if (Number.isInteger(total) && total >= 1 && total <= 2 ** 20)
+        limits.maxConversation = total * 2 ** 20;
+    return limits;
+}
+export function parseDiffTree(bytes) {
+    const fields = bytes.toString('utf8').split('\0'), out = [];
+    for (let i = 0; i + 1 < fields.length; i += 2) {
+        const head = fields[i];
+        if (!head)
+            break;
+        const parts = head.replace(/^:/, '').split(' ');
+        if (parts.length !== 5)
+            throw new Error(`unexpected diff-tree record ${JSON.stringify(head)}`);
+        out.push({ status: parts[4].slice(0, 1), mode: parts[1], oid: parts[3], path: fields[i + 1] });
+    }
+    return out;
+}
+export function safeRelative(path) {
+    if (!path || path.startsWith('/') || /[\0\\]/.test(path) || posix.normalize(path) !== path || path === MANIFEST)
+        return false;
+    return path.split('/').every(part => part !== '..' && part !== '.' && part.toLowerCase() !== '.git');
+}
+/** Smallest first while the conversation's total stays within its limit; fetched files stay while unchanged. */
+export function planFiles(files, limits, prev) {
+    files.sort((a, b) => a.size - b.size || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    let total = 0;
+    for (const f of files) {
+        const before = prev.get(f.path);
+        delete f.reason;
+        delete f.fetched;
+        if (f.mode === '160000')
+            f.state = 'submodule';
+        else if (f.mode === '120000')
+            f.state = 'symlink';
+        else if (before?.fetched && before.oid === f.oid) {
+            f.state = 'present';
+            f.fetched = true;
+        }
+        else if (f.size > limits.maxFile) {
+            f.state = 'placeholder';
+            f.reason = 'file_limit';
+        }
+        else if (total + f.size > limits.maxConversation) {
+            f.state = 'placeholder';
+            f.reason = 'conversation_limit';
+        }
+        else {
+            f.state = 'present';
+            total += f.size;
+        }
+    }
+    return files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+export function humanBytes(n) {
+    if (n >= 2 ** 30)
+        return `${(n / 2 ** 30).toFixed(1)} GB`;
+    if (n >= 2 ** 20)
+        return `${(n / 2 ** 20).toFixed(1)} MB`;
+    if (n >= 2 ** 10)
+        return `${(n / 2 ** 10).toFixed(1)} KB`;
+    return `${n} bytes`;
+}
+const shellWord = (s) => /^[A-Za-z0-9._/@%+=:,-]+$/.test(s) ? s : `'${s.replaceAll("'", `'\\''`)}'`;
+export function placeholderText(m, f) {
+    const why = f.reason === 'conversation_limit' ? `this conversation's changed files are above the ${humanBytes(m.max_conversation_bytes)} total limit` : `it is above the ${humanBytes(m.max_file_bytes)} per-file limit`;
+    return `${f.path} (${humanBytes(f.size)}) is listed here but not downloaded, because ${why}.\nConversation ${m.name}, commit ${m.commit.slice(0, 12)}.\n` +
+        `Download it from the Shardflux menu bar (Download), or run: shard files pull ${m.name} ${shellWord(f.path)}\n`;
+}
+function runGit(args, options = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('git', args, { env: { ...(options.env ?? process.env), GIT_TERMINAL_PROMPT: '0' }, stdio: ['pipe', 'pipe', 'pipe'], ...(options.signal ? { signal: options.signal } : {}) });
+        const out = [], err = [];
+        child.stdout.on('data', (b) => out.push(b));
+        child.stderr.on('data', (b) => err.push(b));
+        child.on('error', reject);
+        child.on('close', code => resolve({ code: code ?? 1, stdout: Buffer.concat(out), stderr: Buffer.concat(err).toString('utf8').trim() }));
+        child.stdin.on('error', () => undefined);
+        child.stdin.end(options.stdin ?? '');
+    });
+}
+/** A hub on this machine (tests). */
+export function localHub(path) {
+    return {
+        git: (args, stdin) => runGit([`--git-dir=${path}`, ...args], { ...(stdin !== undefined ? { stdin } : {}) }),
+        blobs: (oids, onData) => new Promise((resolve, reject) => {
+            const child = spawn('git', [`--git-dir=${path}`, 'cat-file', '--batch'], { stdio: ['pipe', 'pipe', 'pipe'] });
+            const err = [];
+            child.stdout.on('data', (b) => onData(b));
+            child.stderr.on('data', (b) => err.push(b));
+            child.on('error', reject);
+            child.on('close', code => code === 0 ? resolve() : reject(new Error(`git cat-file failed: ${Buffer.concat(err).toString('utf8').trim()}`)));
+            child.stdin.end(oids.join('\n') + '\n');
+        }),
+        close() { },
+    };
+}
+/** The project hub through a ready VM of the project: git runs there, file contents stream back over the same exec API. */
+export function cellHub(ws, signal) {
+    const cell = ws.cell({ wake: null, agentLabel: 'shard-files' });
+    return {
+        async git(args, stdin) {
+            const chunks = [];
+            const r = await cell.exec.run(['git', `--git-dir=${HUB_PATH}`, ...args], { ...(stdin !== undefined ? { stdin } : {}), timeoutMs: 120_000, maxOutputBytes: 1 << 20, signal, onOutput: (stream, chunk) => { if (stream === 'stdout')
+                    chunks.push(chunk); } });
+            return { code: r.exitCode ?? 1, stdout: Buffer.concat(chunks), stderr: r.stderr.trim() };
+        },
+        async blobs(oids, onData) {
+            // The batch goes to a file on the VM's disk and comes back through the files API, which carries any bytes and
+            // reads a VM's disk even if it suspends meanwhile.
+            const made = await cell.exec.run(['sh', '-c', 'set -e; d="$HOME/.cache/shard-files"; mkdir -p "$d"; f=$(mktemp "$d/batch-XXXXXX"); git --git-dir="$1" cat-file --batch > "$f"; wc -c < "$f"; printf "%s\\n" "$f"', 'shard-files', HUB_PATH], { stdin: oids.join('\n') + '\n', timeoutMs: 1_800_000, maxOutputBytes: 4096, signal });
+            const [size, path] = made.stdout.trim().split('\n').map(s => s.trim());
+            if (made.exitCode !== 0 || !path?.startsWith('/') || !/^\d+$/.test(size ?? ''))
+                throw new Error(`git cat-file failed in the project's VM: ${made.stderr.trim() || `exit ${made.exitCode}`}`);
+            try {
+                for (let at = 0, total = Number(size); at < total;) {
+                    signal.throwIfAborted();
+                    const chunk = await cell.files.read(path, { offset: at, length: Math.min(8 << 20, total - at) });
+                    if (!chunk.length)
+                        throw new Error('the project hub stream ended early');
+                    onData(chunk);
+                    at += chunk.length;
+                }
+            }
+            finally {
+                await cell.files.remove(path).catch(() => undefined);
+            }
+        },
+        close() { cell.close(); },
+    };
+}
+/** Writes `git cat-file --batch` output into place as it arrives: read-only files, verified sizes, atomic renames. */
+class BatchWriter {
+    #queue;
+    #root;
+    #header = Buffer.alloc(0);
+    #current;
+    #newline = false;
+    error;
+    constructor(root, files) { this.#root = root; this.#queue = [...files]; }
+    feed(chunk) {
+        if (this.error)
+            return;
+        try {
+            this.#feed(Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength));
+        }
+        catch (e) {
+            this.error = e instanceof Error ? e : new Error(String(e));
+            this.#abort();
+        }
+    }
+    #feed(chunk) {
+        let at = 0;
+        while (at < chunk.length) {
+            if (this.#current) {
+                const n = Math.min(this.#current.left, chunk.length - at);
+                writeSync(this.#current.fd, chunk, at, n);
+                this.#current.left -= n;
+                at += n;
+                if (this.#current.left === 0)
+                    this.#finish();
+            }
+            else if (this.#newline) {
+                if (chunk[at] !== 0x0a)
+                    throw new Error('git cat-file output is out of step');
+                this.#newline = false;
+                at++;
+            }
+            else {
+                const end = chunk.indexOf(0x0a, at);
+                if (end < 0) {
+                    this.#header = Buffer.concat([this.#header, chunk.subarray(at)]);
+                    at = chunk.length;
+                    continue;
+                }
+                const header = Buffer.concat([this.#header, chunk.subarray(at, end)]).toString('utf8');
+                this.#header = Buffer.alloc(0);
+                at = end + 1;
+                this.#start(header);
+            }
+        }
+    }
+    #start(header) {
+        const file = this.#queue.shift(), [oid, type, size] = header.split(' ');
+        if (!file || oid !== file.oid || type !== 'blob' || Number(size) !== file.size)
+            throw new Error(`the project hub does not have ${file?.path ?? 'the file'} (${header})`);
+        ensureDirs(this.#root, posix.dirname(file.path));
+        const target = join(this.#root, file.path), tmp = join(dirname(target), `.sf-copy-${process.pid}-${Math.random().toString(36).slice(2)}`);
+        this.#current = { file, fd: openSync(tmp, 'wx', 0o600), tmp, left: file.size };
+        if (file.size === 0)
+            this.#finish();
+    }
+    #finish() {
+        const { file, fd, tmp } = this.#current;
+        this.#current = undefined;
+        this.#newline = true;
+        closeSync(fd);
+        chmodSync(tmp, file.mode === '100755' ? 0o555 : 0o444);
+        const target = join(this.#root, file.path), st = lstatSync(target, { throwIfNoEntry: false });
+        if (st?.isDirectory())
+            rmSync(target, { recursive: true, force: true });
+        renameSync(tmp, target);
+    }
+    #abort() { if (this.#current) {
+        try {
+            closeSync(this.#current.fd);
+        }
+        catch { /* closed */ }
+        rmSync(this.#current.tmp, { force: true });
+        this.#current = undefined;
+    } }
+    end() {
+        if (this.error)
+            throw this.error;
+        if (this.#current || this.#queue.length || this.#header.length) {
+            this.#abort();
+            throw new Error('the project hub stopped before every file arrived');
+        }
+    }
+}
+/** Copy files' contents from the hub into root, in one stream. */
+export async function copyFromHub(hub, root, files) {
+    if (!files.length)
+        return;
+    const writer = new BatchWriter(root, files);
+    await hub.blobs(files.map(f => f.oid), chunk => writer.feed(chunk));
+    writer.end();
+}
+async function must(hub, args, stdin) {
+    const r = await hub.git(args, stdin);
+    if (r.code !== 0)
+        throw new Error(`git ${args[0]} failed: ${r.stderr}`);
+    return r.stdout;
+}
+async function hubRefs(hub) {
+    const refs = new Map();
+    for (const line of (await must(hub, ['for-each-ref', '--format=%(objectname) %(refname)', 'refs/heads/', 'refs/shard/base/', 'refs/shard/seed/'])).toString('utf8').split('\n')) {
+        const [sha, ref] = line.split(' ');
+        if (sha && ref)
+            refs.set(ref, sha);
+    }
+    return refs;
+}
+async function forkPoint(hub, tip, candidates) {
+    for (const set of [candidates, candidates.slice(0, -1)]) {
+        if (!set.length)
+            continue;
+        const r = await hub.git(['merge-base', tip, ...set]);
+        if (r.code === 0)
+            return r.stdout.toString('utf8').trim().split('\n')[0];
+    }
+    return '';
+}
+/** Create rel under base one component at a time, replacing (never following) a file or symlink in the way. */
+function ensureDirs(base, rel) {
+    let at = base;
+    for (const part of rel.split('/').filter(p => p && p !== '.')) {
+        at = join(at, part);
+        const st = lstatSync(at, { throwIfNoEntry: false });
+        if (st?.isDirectory())
+            continue;
+        if (st)
+            unlinkSync(at);
+        mkdirSync(at, { mode: 0o755 });
+    }
+}
+function removeLeaf(root, rel) {
+    const target = join(root, rel);
+    const st = lstatSync(target, { throwIfNoEntry: false });
+    if (st && !st.isDirectory()) {
+        try {
+            unlinkSync(target);
+        }
+        catch { /* already gone */ }
+    }
+    for (let dir = dirname(target); dir !== root && dir.startsWith(root + '/'); dir = dirname(dir)) {
+        try {
+            rmdirSync(dir);
+        }
+        catch {
+            break;
+        }
+    }
+}
+function writeAtomic(target, bytes, mode) {
+    const tmp = join(dirname(target), `.sf-write-${process.pid}-${Math.random().toString(36).slice(2)}`);
+    writeFileSync(tmp, bytes, { mode });
+    chmodSync(tmp, mode);
+    const st = lstatSync(target, { throwIfNoEntry: false });
+    if (st?.isDirectory())
+        rmSync(target, { recursive: true, force: true });
+    renameSync(tmp, target);
+}
+export class FilesMirrorState {
+    revisions = new Map();
+    retryAt = 0;
+    failures = 0;
+    listedAt = 0;
+    reported = new Set();
+}
+function readJson(file, fallback) { try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+}
+catch {
+    return fallback;
+} }
+function manifests(root) {
+    const found = new Map();
+    const dirs = (p) => { try {
+        return readdirSync(p, { withFileTypes: true }).filter(d => d.isDirectory() && !d.name.startsWith('.')).map(d => d.name);
+    }
+    catch {
+        return [];
+    } };
+    for (const project of dirs(root))
+        for (const group of dirs(join(root, project)))
+            for (const conv of dirs(join(root, project, group))) {
+                const rel = join(project, group, conv), manifest = readJson(join(root, rel, MANIFEST), null);
+                if (manifest && /^conv_[a-z0-9]{26}$/.test(manifest.conversation_id ?? ''))
+                    found.set(manifest.conversation_id, { rel, manifest });
+            }
+    return found;
+}
+const nameOf = (c) => c.branch.replace(/^shard\//, '');
+/** The repository a conversation belongs to: its normalized remote; worktrees of an origin-less repository share its Git common directory. */
+export function repositoryIdentity(c, local) {
+    let remote = c.repo_remote || undefined;
+    if (!remote && local) {
+        try {
+            const p = projectIdentity(local.folder);
+            remote = p.remote ?? `file://${p.folder}`;
+        }
+        catch { /* the folder moved */ }
+    }
+    if (remote?.startsWith('file://')) {
+        const path = remote.slice('file://'.length);
+        try {
+            const common = execFileSync('git', ['-C', path, 'rev-parse', '--path-format=absolute', '--git-common-dir'], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+            remote = `file://${basename(common) === '.git' ? dirname(common) : common.replace(/\.git$/, '')}`;
+        }
+        catch { /* not on this Mac */ }
+    }
+    if (remote)
+        return { id: remote, name: repositoryName(remote) };
+    return { id: `project:${c.project_id}`, name: humanFolder(c.key.split('/')[0] ?? '', 'project') };
+}
+function assign(taken, candidates) {
+    for (const c of candidates)
+        if (!taken.has(c.toLowerCase()))
+            return c;
+    for (let n = 2;; n++) {
+        const c = `${candidates[0]}-${n}`;
+        if (!taken.has(c.toLowerCase()))
+            return c;
+    }
+}
+export class FilesMirror {
+    root;
+    ctx;
+    connect;
+    constructor(ctx, connect, root = filesRoot(ctx.io.env)) {
+        this.ctx = ctx;
+        this.connect = connect;
+        this.root = root;
+    }
+    get stateFile() { return join(this.root, '.shardflux', 'state.json'); }
+    get indexFile() { return join(this.ctx.store.dir, 'files.json'); }
+    /** One pass: only conversations whose API record moved touch the hub. */
+    async sync(all, state = new FilesMirrorState()) {
+        const locals = localConversations({ store: this.ctx.store, apiUrl: this.ctx.apiUrl });
+        const revision = (c) => JSON.stringify([c.state, c.last_activity_at, c.title, c.base_branch ?? null, c.landed ?? null, c.repo_remote ?? null, c.workspace_id]);
+        const listed = new Set(all.map(c => c.id));
+        const existing = manifests(this.root);
+        const changed = all.filter(c => state.revisions.get(c.id) !== revision(c));
+        const gone = [...existing.keys()].filter(id => !listed.has(id) || all.find(c => c.id === id)?.landed?.how === 'discarded');
+        if (!changed.length && !gone.length)
+            return;
+        await withTargetLock(join(this.ctx.store.dir, 'files-lock'), async () => {
+            mkdirSync(join(this.root, '.shardflux'), { recursive: true, mode: 0o755 });
+            const a = readJson(this.stateFile, { projects: {}, groups: {}, conversations: {} });
+            const current = manifests(this.root);
+            for (const id of gone) {
+                const d = current.get(id);
+                if (d)
+                    this.#remove(d.rel);
+                delete a.conversations[id];
+                current.delete(id);
+            }
+            const errors = [];
+            const byProject = new Map();
+            for (const c of changed) {
+                if (c.landed?.how === 'discarded' || c.join_mode === 'reviewer') {
+                    state.revisions.set(c.id, revision(c));
+                    continue;
+                }
+                byProject.set(c.project_id, [...(byProject.get(c.project_id) ?? []), c]);
+            }
+            for (const [projectId, list] of byProject) {
+                let hub;
+                try {
+                    hub = await this.connect(projectId, all);
+                    const refs = await hubRefs(hub);
+                    for (const c of list) {
+                        try {
+                            if (refs.has(`refs/heads/${c.branch}`))
+                                await this.#refresh(hub, refs, c, locals[c.id], a, current);
+                            state.revisions.set(c.id, revision(c));
+                        }
+                        catch (e) {
+                            errors.push(`${c.branch}: ${e instanceof Error ? e.message : String(e)}`);
+                        }
+                    }
+                }
+                catch (e) {
+                    errors.push(e instanceof Error ? e.message : String(e));
+                }
+                finally {
+                    hub?.close();
+                }
+            }
+            writeFileSync(this.stateFile, JSON.stringify(a, null, 2) + '\n');
+            this.#index();
+            if (errors.length)
+                throw new Error(`Files mirror: ${errors.join('; ')}`);
+        }, this.ctx.signal);
+    }
+    #remove(rel) {
+        rmSync(join(this.root, rel), { recursive: true, force: true });
+        for (let dir = dirname(join(this.root, rel)); dir !== this.root && dir.startsWith(this.root + '/'); dir = dirname(dir)) {
+            try {
+                rmdirSync(dir);
+            }
+            catch {
+                break;
+            }
+        }
+    }
+    /** Where a conversation's folder lives; assignments persist so a new repository never renames an existing one. */
+    #placeOf(c, local, a) {
+        const repo = repositoryIdentity(c, local);
+        const usedProjects = new Set(Object.entries(a.projects).filter(([id]) => id !== repo.id).map(([, n]) => n.toLowerCase()));
+        a.projects[repo.id] ??= assign(usedProjects, [repo.name]);
+        const project = a.projects[repo.id];
+        const base = c.base_branch ?? local?.base_branch ?? null, groupKey = `${repo.id}\n${base ?? ''}`;
+        const usedGroups = new Set(Object.entries(a.groups).filter(([k]) => k !== groupKey && k.startsWith(`${repo.id}\n`)).map(([, n]) => n.toLowerCase()));
+        a.groups[groupKey] ??= assign(usedGroups, [branchFolder(base)]);
+        const group = a.groups[groupKey];
+        // Titles start as the first prompt; attachment markers are not a name.
+        const name = nameOf(c), title = humanFolder((c.title && c.title !== name ? c.title : name).replace(/\[Image #\d+\]\s*/g, ''), name);
+        const candidates = [title, `${title} (${name})`, `${title} (${c.id})`];
+        const usedHere = new Set(Object.entries(a.conversations).filter(([id, rel]) => id !== c.id && dirname(rel) === join(project, group)).map(([, rel]) => basename(rel).toLowerCase()));
+        const prior = a.conversations[c.id];
+        const keep = prior && dirname(prior) === join(project, group) && candidates.includes(basename(prior)) && !usedHere.has(basename(prior).toLowerCase());
+        a.conversations[c.id] = keep ? prior : join(project, group, assign(usedHere, candidates));
+        return a.conversations[c.id];
+    }
+    async #refresh(hub, refs, c, local, a, current) {
+        const prior = current.get(c.id), rel = this.#placeOf(c, local, a), root = join(this.root, rel);
+        if (prior && prior.rel !== rel) {
+            ensureDirs(this.root, dirname(rel));
+            rmSync(root, { recursive: true, force: true });
+            renameSync(join(this.root, prior.rel), root);
+            this.#remove(prior.rel);
+        }
+        const old = prior?.manifest, name = nameOf(c), tip = refs.get(`refs/heads/${c.branch}`);
+        const base = c.base_branch ?? local?.base_branch ?? null;
+        if (old?.landed) {
+            if (old.title !== c.title) {
+                old.title = c.title;
+                this.#writeManifest(root, old);
+            }
+            return;
+        }
+        const candidates = [refs.get(`refs/shard/base/${name}`), base && base !== c.branch ? refs.get(`refs/heads/${base}`) : undefined, c.base_commit].filter((s) => !!s);
+        let fork = await forkPoint(hub, tip, candidates);
+        if (!fork)
+            throw new Error('no fork point in the project hub');
+        const landed = c.landed?.how === 'merged' || (fork === tip && tip !== c.base_commit);
+        const note = landed ? { how: 'merged', ref: c.landed?.ref || base || '', at: c.landed?.at ?? '', note: 'Landed: these files now live in the base branch. This folder no longer updates.' } : undefined;
+        if (landed && old) {
+            old.landed = note;
+            this.#writeManifest(root, old);
+            return;
+        }
+        if (landed && fork === tip)
+            fork = (await forkPoint(hub, tip, [c.base_commit])) || fork;
+        const seed = refs.get(`refs/shard/seed/${name}`);
+        if (!landed && old && old.commit === tip && old.fork_point === fork && old.seed === seed) {
+            if (old.title !== c.title || old.base_branch !== base) {
+                old.title = c.title;
+                old.base_branch = base;
+                this.#writeManifest(root, old);
+            }
+            return;
+        }
+        const config = await hub.git(['cat-file', 'blob', `${tip}:${FILES_CONFIG}`]);
+        const limits = parseFilesConfig(config.code === 0 ? config.stdout.toString('utf8') : undefined);
+        let changes = parseDiffTree(await must(hub, ['diff-tree', '-r', '-z', '--raw', '--no-renames', '--no-abbrev', fork, tip]));
+        if (seed && seed !== fork) {
+            // The working tree it started from (uncommitted laptop edits) is not its change: a path counts only when it
+            // also differs from the seed snapshot.
+            const differs = new Set(parseDiffTree(await must(hub, ['diff-tree', '-r', '-z', '--raw', '--no-renames', '--no-abbrev', seed, tip])).map(ch => ch.path));
+            changes = changes.filter(ch => differs.has(ch.path));
+        }
+        const m = { version: 1, conversation_id: c.id, project_id: c.project_id, name, title: c.title, repository: repositoryIdentity(c, local).id, branch: c.branch, base_branch: base,
+            commit: tip, fork_point: fork, ...(seed ? { seed } : {}), max_file_bytes: limits.maxFile, max_conversation_bytes: limits.maxConversation, files: [], deleted: [], updated_at: new Date().toISOString() };
+        for (const ch of changes) {
+            if (!safeRelative(ch.path))
+                continue;
+            if (ch.status === 'D')
+                m.deleted.push(ch.path);
+            else
+                m.files.push({ path: ch.path, oid: ch.oid, size: 0, mode: ch.mode, state: 'present' });
+        }
+        const oids = m.files.filter(f => f.mode !== '160000').map(f => f.oid);
+        if (oids.length) {
+            for (const line of (await must(hub, ['cat-file', '--batch-check=%(objectname) %(objectsize)'], oids.join('\n') + '\n')).toString('utf8').split('\n')) {
+                const [oid, size] = line.split(' ');
+                for (const f of m.files)
+                    if (f.oid === oid && size)
+                        f.size = Number(size);
+            }
+        }
+        const prev = new Map((old?.files ?? []).map(f => [f.path, f]));
+        planFiles(m.files, limits, prev);
+        if (note)
+            m.landed = note;
+        await this.#apply(hub, root, m, prev);
+        this.#writeManifest(root, m);
+    }
+    async #apply(hub, root, m, prev) {
+        mkdirSync(root, { recursive: true, mode: 0o755 });
+        const next = new Map(m.files.map(f => [f.path, f]));
+        for (const [path, f] of prev) {
+            const n = next.get(path);
+            if (f.state === 'present' && n?.state !== 'present')
+                removeLeaf(root, path);
+            if (f.state === 'placeholder' && n?.state !== 'placeholder')
+                removeLeaf(root, path + PLACEHOLDER);
+        }
+        const want = [];
+        for (const f of m.files) {
+            const p = prev.get(f.path);
+            if (f.state === 'present') {
+                if (!(p?.state === 'present' && p.oid === f.oid && lstatSync(join(root, f.path), { throwIfNoEntry: false })))
+                    want.push(f);
+            }
+            else if (f.state === 'placeholder' && !next.has(f.path + PLACEHOLDER)) {
+                ensureDirs(root, posix.dirname(f.path));
+                writeAtomic(join(root, f.path + PLACEHOLDER), placeholderText(m, f), 0o444);
+            }
+        }
+        await copyFromHub(hub, root, want);
+    }
+    #writeManifest(root, m) { writeAtomic(join(root, MANIFEST), JSON.stringify(m, null, 2) + '\n', 0o444); }
+    /** files.json in the config directory: the folder and its placeholders, for the menu bar's Open files and Download. */
+    #index() {
+        const placeholders = [];
+        for (const [, { rel, manifest }] of manifests(this.root))
+            for (const f of manifest.files)
+                if (f.state === 'placeholder') {
+                    placeholders.push({ conversation_id: manifest.conversation_id, conversation: manifest.name, title: manifest.title, folder: join(this.root, rel), path: f.path, size: f.size, local_path: join(this.root, rel, f.path) });
+                }
+        mkdirSync(this.ctx.store.dir, { recursive: true, mode: 0o700 });
+        writeAtomic(this.indexFile, JSON.stringify({ root: this.root, placeholders, updated_at: new Date().toISOString() }, null, 2) + '\n', 0o600);
+    }
+    /** Find a mirrored conversation by id, name or folder name. */
+    find(ref) {
+        const all = [...manifests(this.root).values()];
+        const hits = all.filter(d => d.manifest.conversation_id === ref || d.manifest.name === ref || basename(d.rel) === ref);
+        if (hits.length === 1)
+            return hits[0];
+        if (!hits.length)
+            throw new UsageError(`No conversation ${JSON.stringify(ref)} in ${this.root}. Its folder appears once it has committed files.`);
+        throw new UsageError(`More than one conversation is called ${JSON.stringify(ref)}; use its id: ${hits.map(h => h.manifest.conversation_id).join(', ')}.`);
+    }
+    /** Download one listed file, whatever its size. */
+    async pull(ref, path, all) {
+        const clean = posix.normalize(path.trim()).replace(/^\.?\//, '');
+        if (!safeRelative(clean))
+            throw new UsageError('Give the file path inside the conversation’s repository, e.g. out/hype.mp4.');
+        return withTargetLock(join(this.ctx.store.dir, 'files-lock'), async () => {
+            const { rel, manifest } = this.find(ref), root = join(this.root, rel);
+            const f = manifest.files.find(x => x.path === clean);
+            if (!f)
+                throw new UsageError(`${clean} is not one of the files ${manifest.name} changed; ${join(root, MANIFEST)} lists them.`);
+            const local = join(root, f.path);
+            if (f.state === 'present' && existsSync(local))
+                return { conversation: manifest.name, path: f.path, local_path: local, bytes: f.size, already: true };
+            if (f.state === 'submodule' || f.state === 'symlink')
+                throw new UsageError(`${clean} is a ${f.state}, not a file to download.`);
+            const hub = await this.connect(manifest.project_id, await all());
+            try {
+                await copyFromHub(hub, root, [f]);
+            }
+            finally {
+                hub.close();
+            }
+            removeLeaf(root, f.path + PLACEHOLDER);
+            Object.assign(f, { state: 'present', fetched: true });
+            delete f.reason;
+            this.#writeManifest(root, manifest);
+            this.#index();
+            return { conversation: manifest.name, path: f.path, local_path: local, bytes: f.size, already: false };
+        }, this.ctx.signal);
+    }
+}
+/**
+ * The seed snapshot (sh; $1 repository, $2 conversation name, $3 hub): HEAD plus the working tree the conversation was
+ * seeded with, committed in the conversation's VM with a temporary index (never on this computer), kept per worktree
+ * as refs/worktree/shard/seed and in the hub as refs/shard/seed/<name>. Mirrors leave out what it already contains,
+ * so the user's own uncommitted edits never show as the conversation's change. Threads on one computer are worktrees
+ * of one repository (0.16.0+), so the seed is per worktree; the shared refs/shard/seed of earlier seeds is read, and
+ * still written, only in the repository's main worktree.
+ */
+export const SEED_SNAPSHOT = `set -eu
+cd "$1"
+main=0; [ "$(git rev-parse --absolute-git-dir)" = "$(git rev-parse --path-format=absolute --git-common-dir)" ] && main=1
+if git rev-parse -q --verify refs/worktree/shard/seed >/dev/null; then seed=$(git rev-parse refs/worktree/shard/seed)
+elif [ "$main" = 1 ] && git rev-parse -q --verify refs/shard/seed >/dev/null; then seed=$(git rev-parse refs/shard/seed); else
+idx=$(mktemp); trap 'rm -f "$idx"' EXIT
+cp "$(git rev-parse --path-format=absolute --git-path index)" "$idx" 2>/dev/null || { rm -f "$idx"; GIT_INDEX_FILE="$idx" git read-tree HEAD; }
+GIT_INDEX_FILE="$idx" git add -A
+tree=$(GIT_INDEX_FILE="$idx" git write-tree)
+if [ "$tree" = "$(git rev-parse 'HEAD^{tree}')" ]; then seed=$(git rev-parse HEAD); else
+seed=$(GIT_AUTHOR_NAME=Shardflux GIT_AUTHOR_EMAIL=seed@shardflux.dev GIT_COMMITTER_NAME=Shardflux GIT_COMMITTER_EMAIL=seed@shardflux.dev git commit-tree "$tree" -p HEAD -m "Shardflux: the working tree this conversation started from"); fi
+git update-ref refs/worktree/shard/seed "$seed"
+if [ "$main" = 1 ]; then git update-ref refs/shard/seed "$seed"; fi
+fi
+if [ -d "$3" ]; then git -c core.hooksPath=/dev/null push -q "$3" "+$seed:refs/shard/seed/$2" >/dev/null 2>&1 || true; fi
+printf '%s\n' "$seed"
+`;
+/** Best effort: without a snapshot the folder also lists the start state's own edits. */
+export async function recordSeedSnapshot(ws, c, signal) {
+    try {
+        const r = await ws.cell().exec.run(['sh', '-c', SEED_SNAPSHOT, 'shard-seed', c.worktree_path, c.branch.replace(/^shard\//, ''), HUB_PATH], { timeoutMs: 120_000, maxOutputBytes: 4096, ...(signal ? { signal } : {}) });
+        return r.exitCode === 0 ? r.stdout.trim() : null;
+    }
+    catch (error) {
+        if (signal?.aborted)
+            throw error;
+        return null;
+    }
+}
+/** A ready VM of the project (never woken), else the project's space reader, woken when needed. */
+export function workspaceHub(ctx) {
+    return async (projectId, all) => {
+        const client = conversationClient(ctx);
+        const candidates = all.filter(c => c.project_id === projectId).sort((a, b) => (b.last_activity_at ?? '').localeCompare(a.last_activity_at ?? ''));
+        for (const c of candidates) {
+            try {
+                const ws = await client.workspaces.get(c.workspace_id);
+                if (!ws.data.deleted_at && ws.ready)
+                    return cellHub(ws, ctx.signal);
+            }
+            catch { /* another binding may be ready */ }
+        }
+        const reader = await client.conversations.spaceReader(projectId, { signal: ctx.signal });
+        const ws = await client.workspaces.get(reader.workspace.id);
+        if (!ws.ready)
+            await ws.wake({ timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
+        return cellHub(ws, ctx.signal);
+    };
+}
+export async function listMirrorConversations(ctx) {
+    const all = [];
+    let cursor;
+    do {
+        const page = await conversationClient(ctx).conversations.list({ limit: 200, ...(cursor ? { cursor } : {}) });
+        all.push(...page.data.filter(c => /^conv_[a-z0-9]{26}$/.test(c.id) && /^shard\/[a-z0-9][a-z0-9-]{0,47}$/.test(c.branch ?? '')));
+        cursor = page.nextCursor ?? undefined;
+    } while (cursor);
+    return all;
+}
+/** The device helper's pass: list every few seconds; touch the hub only for conversations whose record moved. */
+export async function mirrorFilesOnce(ctx, state, intervalMs = 5000) {
+    const now = Date.now();
+    if (now < state.retryAt || now - state.listedAt < intervalMs)
+        return;
+    state.listedAt = now;
+    try {
+        await new FilesMirror(ctx, workspaceHub(ctx)).sync(await listMirrorConversations(ctx), state);
+        state.failures = 0;
+        state.retryAt = 0;
+    }
+    catch (e) {
+        if (ctx.signal.aborted || conversationsUnavailable(e))
+            return;
+        const wait = Math.min(300_000, 5000 * 2 ** Math.min(state.failures++, 6));
+        state.retryAt = Date.now() + wait;
+        const message = e instanceof Error ? e.message : String(e);
+        if (!state.reported.has(message)) {
+            state.reported.add(message);
+            ctx.io.stderr.write(`${message} (retrying in ${wait / 1000}s).\n`);
+        }
+    }
+}