@shardflux/cli 0.16.0 → 0.17.0

package/dist/worktree-twin-engine.js

@@ -14,7 +14,7 @@ import { conversationClient } from "./conversation-commands.js";
 import { conversationName, conversationsUnavailable, listConversations, localConversations } from "./conversations.js";
 import { UsageError } from "./errors.js";
 import { projectIdentity } from "./project-identity.js";
-import { TwinLedger, backupRoot, inspectWorktree, landingRound, listWorktrees, pauseReason, restoreBackup } from "./worktree-twin.js";
+import { TwinLedger, backupRoot, inspectWorktree, landingBatch, landingRound, listWorktrees, pauseReason, restoreBackup } from "./worktree-twin.js";
 import { readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 /** Its VM is gone: the conversation ended (archived after the retention window, or done). */
@@ -51,41 +51,165 @@ export function conflictMessage(into, files) {
         + `Resolve each conflict without asking: where you and the user changed the same lines, keep the user's lines and keep your change only where it fits around them; then run the checks and commit. `
         + `Your work lands on the user's computer automatically when you finish. Ask the user only if the result cannot work either way.`;
 }
+/** Refused by an API without turn waits (POST /wait with turn_after, 422): the twin polls instead. */
+export class TurnWaitUnsupported extends Error {
+}
+/** The full pass's interval when finished turns are pushed (a safety net), and when they are not. */
+const PUSHED_PASS_MS = 15_000, POLLED_PASS_MS = 1000;
 export class TwinEngine {
     #deps;
     #reported = new Map();
     #posted = new Map();
+    #watchers = new Map();
+    /** Conversations whose turn just ended (pushed by a turn wait), landed by the next pass without listing anything. */
+    #pushed = new Map();
+    #wake;
+    #pushes;
+    #nextFull = -Infinity;
     constructor(deps) { this.#deps = deps; }
     #report(key, line) { if (this.#reported.get(key) !== line) {
         this.#reported.set(key, line);
         this.#deps.log(line);
     } }
-    /** One pass over every project with a local conversation; returns the suggested wait before the next. */
+    /** Resolves when a pushed turn is waiting to land (the loop's sleep ends at once). */
+    pushed() {
+        if (this.#pushed.size)
+            return Promise.resolve();
+        return new Promise(resolve => { this.#wake = resolve; });
+    }
+    /** Stops every turn wait. */
+    stop() { for (const w of this.#watchers.values())
+        w.abort(); this.#watchers.clear(); }
+    /**
+     * One pass; returns the suggested wait before the next. Turns pushed by the waits land first, without a listing;
+     * otherwise (and at least every 15 s, or every second when the API has no turn waits) every project is listed.
+     */
     async tick(signal) {
-        const d = this.#deps, records = d.records().filter(r => !r.handed_off);
-        let wait = 1000;
+        const d = this.#deps;
+        if (this.#pushed.size) {
+            const pushed = [...this.#pushed.values()];
+            this.#pushed.clear();
+            const records = new Map(d.records().filter(r => !r.handed_off).map(r => [r.conversation.id, r]));
+            const ready = [];
+            for (const { c, at } of pushed) {
+                const record = records.get(c.id), mode = record ? d.ledger.mode(record.project_id) : 'off';
+                if (!record || mode === 'off' || !eligible(c, d.ledger, d.now()))
+                    continue;
+                ready.push({ c, record, mode, agent: { id: '', workspace_id: c.workspace_id, state: 'waiting', since: new Date(at).toISOString() }, at });
+            }
+            const wait = await this.#land(ready, signal);
+            // A landing that has to wait (quiet period, a Git operation) is retried by a full pass at that time.
+            if (wait < POLLED_PASS_MS)
+                this.#nextFull = Math.min(this.#nextFull, d.now() + wait);
+            return this.#pushed.size ? 0 : Math.max(0, Math.min(wait, this.#nextFull - d.now()));
+        }
+        const interval = this.#pushes ? PUSHED_PASS_MS : POLLED_PASS_MS;
+        if (d.now() < this.#nextFull)
+            return this.#nextFull - d.now();
+        const records = d.records().filter(r => !r.handed_off);
+        let wait = interval;
+        const watched = new Set();
         for (const project of new Set(records.map(r => r.project_id))) {
             signal?.throwIfAborted();
             const mode = d.ledger.mode(project);
             if (mode === 'off')
                 continue;
             const mine = new Map(records.filter(r => r.project_id === project).map(r => [r.conversation.id, r]));
-            const candidates = (await d.conversations(project)).filter(c => mine.has(c.id) && eligible(c, d.ledger, d.now()));
+            const listedAt = d.now();
+            const all = (await d.conversations(project)).filter(c => mine.has(c.id));
+            for (const c of all)
+                if (!ended(c) && c.route !== 'codex-cloud' && c.join_mode !== 'reviewer') {
+                    watched.add(c.id);
+                    this.#watch(c, listedAt, signal);
+                }
+            const candidates = all.filter(c => eligible(c, d.ledger, d.now()));
             if (!candidates.length)
                 continue;
             const agents = candidates.some(c => !ended(c)) ? await d.agents(project) : [];
-            // In the order the turns finished (several may have finished while this computer was away); each lands against
-            // the checkout as it is when its turn comes.
-            const ready = candidates.map(c => ({ c, turn: finished(c, agents) })).filter((x) => x.turn !== null)
-                .map(x => ({ ...x, at: x.turn === 'state' ? Date.parse(x.c.last_activity_at ?? x.c.created_at) : Date.parse(x.turn.since) }))
-                .sort((a, b) => (a.at || 0) - (b.at || 0));
-            for (const { c, turn } of ready) {
-                const next = await this.landOne(c, mine.get(c.id), mode, turn === 'state' ? null : turn, signal);
-                if (next !== undefined)
-                    wait = Math.min(wait, next);
+            const ready = [];
+            for (const c of candidates) {
+                const turn = finished(c, agents);
+                if (!turn)
+                    continue;
+                ready.push({ c, record: mine.get(c.id), mode, agent: turn === 'state' ? null : turn,
+                    at: turn === 'state' ? Date.parse(c.last_activity_at ?? c.created_at) : Date.parse(turn.since) });
             }
+            wait = Math.min(wait, await this.#land(ready, signal));
         }
-        return wait;
+        for (const [id, w] of this.#watchers)
+            if (!watched.has(id)) {
+                w.abort();
+                this.#watchers.delete(id);
+            }
+        this.#nextFull = d.now() + Math.min(wait, interval);
+        return this.#pushed.size ? 0 : Math.min(wait, interval);
+    }
+    /**
+     * In the order the turns finished (several may have finished at once, or while this computer was away), each
+     * against the checkout as it is when its turn comes; finished conversations for the same branch land together.
+     */
+    async #land(ready, signal) {
+        let wait = Infinity;
+        ready.sort((a, b) => (a.at || 0) - (b.at || 0));
+        const key = (r) => `${r.record.folder}\0${r.c.base_branch ?? r.record.base_branch ?? ''}`;
+        for (let i = 0; i < ready.length;) {
+            let j = i + 1;
+            while (j < ready.length && key(ready[j]) === key(ready[i]))
+                j++;
+            const group = ready.slice(i, j);
+            i = j;
+            const batchable = group.filter(r => r.mode === 'auto' && !ended(r.c));
+            const next = batchable.length > 1 ? await this.landBatch(batchable, signal) : undefined;
+            for (const r of group)
+                if (batchable.length <= 1 || !batchable.includes(r)) {
+                    const one = await this.landOne(r.c, r.record, r.mode, r.agent, signal);
+                    if (one !== undefined)
+                        wait = Math.min(wait, one);
+                }
+            if (next !== undefined)
+                wait = Math.min(wait, next);
+        }
+        return wait === Infinity ? POLLED_PASS_MS : wait;
+    }
+    /** One long-poll per active conversation: its next finished turn is pushed to the loop. */
+    #watch(c, listedAt, signal) {
+        const d = this.#deps;
+        if (!d.waitTurn || this.#pushes === false || this.#watchers.has(c.id))
+            return;
+        const abort = new AbortController();
+        this.#watchers.set(c.id, abort);
+        const stop = AbortSignal.any([abort.signal, ...(signal ? [signal] : [])]);
+        // A turn that ended just before the listing is caught by the listing itself; the overlap only repeats it.
+        let after = new Date(listedAt - 2000).toISOString(), failures = 0;
+        void (async () => {
+            while (!stop.aborted) {
+                try {
+                    const turn = await d.waitTurn(c, after, stop);
+                    this.#pushes = true;
+                    failures = 0;
+                    if (turn === 'ended') {
+                        this.#watchers.delete(c.id);
+                        return;
+                    }
+                    if (!turn)
+                        continue;
+                    after = turn.reported_at;
+                    this.#pushed.set(c.id, { c: turn.conversation, at: Date.parse(turn.reported_at) });
+                    this.#wake?.();
+                    this.#wake = undefined;
+                }
+                catch (error) {
+                    if (stop.aborted)
+                        return;
+                    if (error instanceof TurnWaitUnsupported) {
+                        this.#pushes = false;
+                        this.stop();
+                        return;
+                    }
+                    await delay(Math.min(60_000, 1000 * 2 ** Math.min(failures++, 6)), undefined, { signal: stop }).catch(() => undefined);
+                }
+            }
+        })();
     }
     /** Back online or awake: every conversation's retry backoff is cleared, so the next pass tries all of them. */
     resetBackoff() {
@@ -94,8 +218,10 @@ export class TwinEngine {
             st.retry_at = 0;
         } });
         this.#reported.clear();
+        this.#nextFull = -Infinity;
     }
-    async landOne(c, record, mode, agent, signal) {
+    /** Everything a landing needs here, or undefined (nothing to do now; reported). */
+    async #prepare(c, record, agent) {
         const d = this.#deps, st = d.ledger.conversation(c.id), rev = revision(c);
         const into = c.base_branch ?? record.base_branch ?? st.base_branch;
         const name = c.name ?? conversationName(c);
@@ -118,15 +244,17 @@ export class TwinEngine {
             }
             return;
         }
-        const branch = `refs/heads/${into}`;
-        let worktree = null;
-        const target = (await listWorktrees(record.folder)).find(w => w.branch === branch);
-        if (target) {
-            worktree = await inspectWorktree(target.root);
-            if (pauseReason(worktree))
-                return 1000;
-        }
-        const started = d.now();
+        const target = (await listWorktrees(record.folder)).find(w => w.branch === `refs/heads/${into}`);
+        const worktree = target ? await inspectWorktree(target.root) : null;
+        if (worktree && pauseReason(worktree))
+            return 1000;
+        return { c, record, agent, into, name, label, rev, st, target, worktree };
+    }
+    async landOne(c, record, mode, agent, signal) {
+        const d = this.#deps, started = d.now();
+        const p = await this.#prepare(c, record, agent);
+        if (p === undefined || typeof p === 'number')
+            return p;
         let vm, fromHub = false;
         try {
             vm = ended(c) ? null : await d.cell(c);
@@ -139,31 +267,92 @@ export class TwinEngine {
         catch (error) {
             if (signal?.aborted)
                 throw error;
-            return this.#fail(c, label, error instanceof Error ? error.message : String(error));
+            return this.#fail(c, p.label, error instanceof Error ? error.message : String(error));
         }
-        let outcome, keep = false;
+        let outcome;
         try {
+            let worktree = p.worktree;
             for (let attempt = 0; attempt < 3; attempt++) {
-                if (target && attempt)
-                    worktree = await inspectWorktree(target.root);
-                outcome = await landingRound(vm.cell, { conversation: { id: c.id, name, title: c.title, summary: c.summary, branch: c.branch, base_commit: c.base_commit, worktree_path: c.worktree_path },
-                    into, mode: mode === 'pr' ? 'pr' : 'auto', device: d.device, repo: target?.root ?? record.folder, worktree, stateDir: d.stateDir, backupRoot: backupRoot(d.stateDir),
-                    upto: st.upto, known: [st.tip, st.upto].filter((x) => !!x), hub: d.hub, vmTmp: d.vmTmp, quietMs: d.quietMs, signal, now: () => d.now(),
+                if (p.target && attempt)
+                    worktree = await inspectWorktree(p.target.root);
+                outcome = await landingRound(vm.cell, { ...this.#input(p, worktree, signal), mode: mode === 'pr' ? 'pr' : 'auto',
                     ...(fromHub ? { fromHub: { ...(c.repo_remote ? { repoRemote: c.repo_remote } : {}) } } : {}) });
                 if (outcome.state !== 'moved')
                     break;
             }
-            keep = outcome?.state === 'landed';
         }
         catch (error) {
+            vm.close();
             if (signal?.aborted)
                 throw error;
-            return this.#fail(c, label, error instanceof Error ? error.message : String(error));
+            return this.#fail(c, p.label, error instanceof Error ? error.message : String(error));
+        }
+        return this.#settle(p, outcome, vm, started, fromHub);
+    }
+    /** Several finished conversations for one branch: merged in their VMs at once, the files written once. */
+    async landBatch(items, signal) {
+        const d = this.#deps, started = d.now();
+        const prepared = [];
+        let wait;
+        for (const r of items) {
+            const p = await this.#prepare(r.c, r.record, r.agent);
+            if (typeof p === 'number')
+                wait = Math.min(wait ?? p, p);
+            else if (p)
+                prepared.push(p);
+        }
+        if (prepared.length < 2) {
+            for (const p of prepared) {
+                const one = await this.landOne(p.c, p.record, 'auto', p.agent, signal);
+                if (one !== undefined)
+                    wait = Math.min(wait ?? one, one);
+            }
+            return wait;
         }
-        finally {
-            if (!keep)
+        const vms = await Promise.all(prepared.map(p => d.cell(p.c).catch((error) => error instanceof Error ? error : new Error(String(error)))));
+        const ok = prepared.flatMap((p, i) => { const vm = vms[i]; return vm && !(vm instanceof Error) ? [{ p, vm }] : []; });
+        for (const [i, vm] of vms.entries()) {
+            // Without its VM now, it lands on its own (from the hub, or after a retry).
+            if (!vm || vm instanceof Error) {
+                const one = await this.landOne(prepared[i].c, prepared[i].record, 'auto', prepared[i].agent, signal);
+                if (one !== undefined)
+                    wait = Math.min(wait ?? one, one);
+            }
+        }
+        if (!ok.length)
+            return wait;
+        const first = ok[0].p;
+        let outcomes;
+        try {
+            outcomes = await landingBatch(ok.map(({ p, vm }) => ({ cell: vm.cell, conversation: this.#input(p, p.worktree, signal).conversation, upto: p.st.upto,
+                known: [p.st.tip, p.st.upto].filter((x) => !!x) })), { ...this.#input(first, first.worktree, signal) });
+        }
+        catch (error) {
+            for (const { vm } of ok)
                 vm.close();
+            if (signal?.aborted)
+                throw error;
+            for (const { p } of ok)
+                wait = Math.min(wait ?? Infinity, this.#fail(p.c, p.label, error instanceof Error ? error.message : String(error)));
+            return wait;
+        }
+        for (const [i, { p, vm }] of ok.entries()) {
+            const next = await this.#settle(p, outcomes[i], vm, started, false);
+            if (next !== undefined)
+                wait = Math.min(wait ?? next, next);
         }
+        return wait;
+    }
+    #input(p, worktree, signal) {
+        const d = this.#deps, c = p.c;
+        return { conversation: { id: c.id, name: p.name, title: c.title, summary: c.summary, branch: c.branch, base_commit: c.base_commit, worktree_path: c.worktree_path },
+            into: p.into, mode: 'auto', device: d.device, repo: p.target?.root ?? p.record.folder, worktree, stateDir: d.stateDir, backupRoot: backupRoot(d.stateDir),
+            upto: p.st.upto, known: [p.st.tip, p.st.upto].filter((x) => !!x), hub: d.hub, vmTmp: d.vmTmp, quietMs: d.quietMs, signal, now: () => d.now() };
+    }
+    async #settle(p, o, vm, started, fromHub) {
+        const d = this.#deps, { c, into, label, rev, st, agent } = p;
+        if (o.state !== 'landed')
+            vm.close();
         const post = async (action, ref) => {
             // An ended conversation cannot record a landing any more (the API refuses); the ledger keeps it.
             if (ended(c))
@@ -171,7 +360,6 @@ export class TwinEngine {
             this.#posted.set(c.id, d.now());
             await d.land(c, action, ref);
         };
-        const o = outcome;
         switch (o.state) {
             case 'landed': {
                 // The VM records the landing and copies it to the project hub on its own time; the connection closes after.
@@ -181,7 +369,7 @@ export class TwinEngine {
                 d.ledger.patch(c.id, { upto: o.land.upto, tip: o.land.tip, landed_revision: rev, landed_at: new Date(o.applied.at).toISOString(), method: o.land.method,
                     failures: 0, retry_at: 0, last_error: undefined, ...(latency !== undefined ? { latency_ms: latency } : {}) });
                 await post('merge', into);
-                d.log(`Twin: landed ${label} into ${into} in ${target?.root ?? record.folder}${fromHub ? ' from the project hub' : ''} (${o.land.method}; ${o.applied.files.length} file${o.applied.files.length === 1 ? '' : 's'}`
+                d.log(`Twin: landed ${label} into ${into} in ${p.target?.root ?? p.record.folder}${fromHub ? ' from the project hub' : ''} (${o.land.method}; ${o.applied.files.length} file${o.applied.files.length === 1 ? '' : 's'}`
                     + `${o.applied.raced.length ? `, kept your version of ${o.applied.raced.join(', ')}` : ''}${o.land.shadowed?.length ? `, your edits win in ${o.land.shadowed.join(', ')}` : ''}`
                     + `${latency !== undefined ? `; ${(latency / 1000).toFixed(1)} s after the turn ended, round started at ${((started - Date.parse(agent.since)) / 1000).toFixed(1)} s` : ''}`
                     + `; round ${Object.entries(o.timings).map(([k, v]) => `${k} ${v} ms`).join(', ')}; in the VM ${Object.entries(o.land.phases ?? {}).map(([k, v]) => `${k} ${v}`).join(', ')}).`);
@@ -207,6 +395,10 @@ export class TwinEngine {
                 d.ledger.patch(c.id, { conflict_tip: o.land.conversation_tip, conflict_revision: rev });
                 d.log(`Twin: ${label} conflicts with your commits on ${into} (${(o.land.conflicts ?? []).join(', ')}); its agent is resolving it.`);
                 return;
+            // It lands next, against the state the others left.
+            case 'deferred':
+                this.#pushed.set(c.id, { c, at: agent ? Date.parse(agent.since) : d.now() });
+                return 0;
             case 'busy':
                 d.ledger.patch(c.id, { retry_at: d.now() + (o.waitMs ?? 1000) });
                 return o.waitMs ?? 1000;
@@ -257,7 +449,12 @@ export async function runTwinLoop(deps, signal) {
         let left = wait, probed = deps.mono();
         while (left > 0 && !signal.aborted) {
             const slice = Math.min(1000, left), wall = deps.wall(), mono = deps.mono();
-            await deps.sleep(slice, signal);
+            let kicked = false;
+            const sleeping = new AbortController(), both = AbortSignal.any([signal, sleeping.signal]);
+            await Promise.race([deps.sleep(slice, both), ...(deps.kicked ? [deps.kicked().then(() => { kicked = true; })] : [])]);
+            sleeping.abort();
+            if (kicked)
+                break;
             left -= slice;
             const woke = deps.wall() - wall - (deps.mono() - mono) > JUMP_MS;
             const now = deps.network(), changed = now !== net;
@@ -353,13 +550,29 @@ export async function runWorktreeTwin(ctx, device, signal) {
         resume: async (c) => { await client().conversations.resume(c.id, { signal }); },
         land: async (c, action, into) => { await client().conversations.land(c.id, action, { into, signal }); },
         message: async (c, text) => { await client().conversations.send(c.id, text, { signal }); },
+        waitTurn: async (c, after, s) => {
+            let r;
+            try {
+                r = await client().conversations.wait(c.id, { until: ['archived'], timeoutSeconds: 300, turnAfter: after, signal: s });
+            }
+            catch (error) {
+                if (error.status === 422)
+                    throw new TurnWaitUnsupported('the API has no turn waits');
+                throw error;
+            }
+            if ('timeout' in r)
+                return null;
+            if (r.event.kind !== 'turn_ended' || !r.event.reported_at)
+                return 'ended';
+            return { conversation: r.conversation, reported_at: r.event.reported_at };
+        },
         ledger: new TwinLedger(ctx.store.dir), stateDir: ctx.store.dir, device,
         log: line => { ctx.io.stderr.write(line + '\n'); }, now: Date.now,
     });
     await runTwinLoop({
         tick: s => engine.tick(s), resetBackoff: () => engine.resetBackoff(),
         sleep: (ms, s) => delay(ms, undefined, { signal: s }).catch(() => undefined),
-        wall: Date.now, mono: () => performance.now(), network: networkSignature, reachable: () => reachable(ctx.apiUrl),
+        wall: Date.now, mono: () => performance.now(), network: networkSignature, reachable: () => reachable(ctx.apiUrl), kicked: () => engine.pushed(),
         log: line => { ctx.io.stderr.write(line + '\n'); },
     }, signal);
 }

package/dist/worktree-twin.d.ts

@@ -221,6 +221,11 @@ export type RoundOutcome = {
     waitMs?: number;
     land?: LandResult;
     timings: Record<string, number>;
+} | {
+    state: 'deferred';
+    reason: string;
+    land: LandResult;
+    timings: Record<string, number>;
 };
 /** The landing script, shipped next to this module (src in the monorepo, dist when published). */
 export declare function landingScript(): string;
@@ -228,6 +233,18 @@ export declare function runLandingScript(cell: TwinCell, input: Record<string, u
 /** A temporary repository in the cell with the conversation's branch (and its earlier landing refs) from the hub. */
 export declare const HUB_CHECKOUT = "set -eu\nd=$(mktemp -d \"${TMPDIR:-/tmp}/shard-land-XXXXXX\")\ngit init -q \"$d\"\ncd \"$d\"\ngit fetch -q --no-tags \"$1\" \"+refs/heads/$2:refs/heads/$2\"\ngit fetch -q --no-tags \"$1\" \"+refs/shard/land/$3/upto:refs/shard/land/upto\" 2>/dev/null || true\ngit symbolic-ref HEAD \"refs/heads/$2\"\nif [ -n \"$4\" ]; then git remote add origin \"$4\"; fi\nprintf '%s\\n' \"$d\"\n";
 export declare function landingRound(cell: TwinCell, input: RoundInput): Promise<RoundOutcome>;
+export interface BatchItem {
+    cell: TwinCell;
+    conversation: RoundConversation;
+    upto?: string;
+    known?: string[];
+}
+/**
+ * Lands several finished conversations into one branch with one apply: one twin, the merges in their VMs in parallel,
+ * then their new commits stacked here in the given (finish) order and the files written once. A conversation whose
+ * commits do not stack cleanly on the earlier ones is 'deferred' (it lands next, against the new state).
+ */
+export declare function landingBatch(items: BatchItem[], shared: Omit<RoundInput, 'conversation' | 'upto' | 'known' | 'fromHub' | 'mode'>): Promise<RoundOutcome[]>;
 export type LandingMode = 'auto' | 'pr' | 'off';
 export interface TwinConversationState {
     base_branch?: string;

package/dist/worktree-twin.js

@@ -516,19 +516,23 @@ export async function landingRound(cell, input) {
         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';
+/** The twin of the checkout where the branch is checked out (or of the branch itself), or why not now. */
+async function takeSnapshot(input) {
+    const branch = `refs/heads/${input.into}`;
     if (input.worktree) {
         const reason = pauseReason(input.worktree);
         if (reason)
-            return { state: 'paused', reason, timings };
+            return { state: 'paused', reason };
     }
     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');
+        return { state: 'moved', reason: 'branch_switched' };
+    return snap;
+}
+const landRefs = (name) => ({ tip: `refs/shard/land/${name}/tip`, result: `refs/shard/land/${name}/result` });
+/** The landing script in the conversation's VM against the twin; a ready landing's tip and result are fetched here. */
+async function mergeInVm(cell, input, snap, mark) {
+    const c = input.conversation, hub = input.hub ?? HUB_PATH, vmTmp = input.vmTmp ?? '/tmp';
     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.
@@ -582,9 +586,8 @@ async function landingRoundIn(cell, input) {
         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`;
+        return land;
+    const fetched = join(tmpdir(), `shard-land-${randomUUID()}.bundle`), refs = landRefs(c.name);
     try {
         let bytes;
         if (land.bundle_b64)
@@ -598,8 +601,8 @@ async function landingRoundIn(cell, input) {
                 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)
+        await git(input.repo, ['fetch', '-q', '--no-tags', fetched, `+refs/shard/land/tip:${refs.tip}`, `+refs/shard/land/result:${refs.result}`]);
+        if (await verifyCommit(input.repo, refs.tip) !== land.tip || await verifyCommit(input.repo, refs.result) !== land.result)
             throw new Error('the landing bundle does not match the landing');
     }
     finally {
@@ -608,22 +611,144 @@ async function landingRoundIn(cell, input) {
             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.
+    return land;
+}
+async function dropLandRefs(repo, name) {
+    const refs = landRefs(name);
+    await git(repo, ['update-ref', '-d', refs.result], { ok: [0, 1] });
+    await git(repo, ['update-ref', '-d', refs.tip], { ok: [0, 1] });
+}
+/**
+ * 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.
+ */
+function confirmInVm(cell, input, snap, land, timings, since, now) {
+    const c = input.conversation, hub = input.hub ?? HUB_PATH;
     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;
+        timings.confirm = now() - since;
     });
     confirmed.catch(() => undefined);
-    return { state: 'landed', land, applied: outcome, timings, confirmed };
+    return confirmed;
+}
+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}`;
+    const snap = await takeSnapshot(input);
+    if ('state' in snap)
+        return { ...snap, timings };
+    mark('snapshot');
+    const land = await mergeInVm(cell, input, snap, mark);
+    if (land.state !== 'ready')
+        return { state: land.state === 'error' ? 'error' : land.state, land, timings };
+    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 dropLandRefs(input.repo, c.name);
+    if (outcome.state !== 'applied')
+        return { ...outcome, reason: 'reason' in outcome ? outcome.reason : 'busy', land, timings };
+    return { state: 'landed', land, applied: outcome, timings, confirmed: confirmInVm(cell, input, snap, land, timings, t0, now) };
+}
+async function mergeTree(repo, base, ours, theirs, strategy) {
+    const r = await git(repo, ['merge-tree', '--write-tree', '--name-only', '--no-messages', '-z', `--merge-base=${base}`, ...(strategy ? ['-X', strategy] : []), ours, theirs], { ok: [0, 1] });
+    const parts = r.stdout.toString('utf8').split('\0');
+    return { tree: parts[0].trim(), conflicts: r.code === 1 ? [...new Set(parts.slice(1).filter(Boolean))].sort() : [] };
+}
+/** cur with each first-parent commit of base..tip replayed on it (author and message kept), or null on a conflict. */
+async function replayOnto(repo, cur, base, tip) {
+    const commits = (await gitText(repo, ['rev-list', '--reverse', '--first-parent', tip, `^${base}`])).split('\n').filter(Boolean);
+    for (const x of commits) {
+        const parent = await verifyCommit(repo, `${x}^1`);
+        if (!parent)
+            return null;
+        const { tree, conflicts } = await mergeTree(repo, parent, cur, x);
+        if (conflicts.length)
+            return null;
+        if (tree === await gitText(repo, ['rev-parse', `${cur}^{tree}`]))
+            continue;
+        const [name, email, date] = (await gitText(repo, ['log', '-1', '--format=%an%x00%ae%x00%ad', '--date=raw', x])).split('\0');
+        const raw = (await git(repo, ['cat-file', 'commit', x])).stdout, message = raw.subarray(raw.indexOf('\n\n') + 2);
+        cur = await gitText(repo, ['commit-tree', tree, '-p', cur, '-F', '-'], { input: message, env: { GIT_AUTHOR_NAME: name, GIT_AUTHOR_EMAIL: email, GIT_AUTHOR_DATE: date } });
+    }
+    return cur;
+}
+/** The user's working state with the branch's new commits merged in; where both changed the same lines, the user's text. */
+async function resultCommit(repo, base, twin, tip) {
+    let { tree, conflicts } = await mergeTree(repo, base, twin, tip);
+    const shadowed = conflicts;
+    if (conflicts.length) {
+        ({ tree, conflicts } = await mergeTree(repo, base, twin, tip, 'ours'));
+        if (conflicts.length) {
+            const dir = join(tmpdir(), `shard-index-${randomUUID()}`), env = { GIT_INDEX_FILE: dir };
+            try {
+                await git(repo, ['read-tree', tree], { env });
+                await git(repo, ['rm', '-r', '-q', '--cached', '--ignore-unmatch', '--', ...conflicts], { env });
+                const listing = (await git(repo, ['ls-tree', '-r', '-z', '--full-tree', twin, '--', ...conflicts])).stdout.toString('utf8').split('\0').filter(Boolean)
+                    .map(l => l.replace(/ (blob|commit) /, ' '));
+                if (listing.length)
+                    await git(repo, ['update-index', '-z', '--index-info'], { env, input: listing.join('\0') + '\0' });
+                tree = await gitText(repo, ['write-tree'], { env });
+            }
+            finally {
+                rmSync(dir, { force: true });
+            }
+        }
+    }
+    const commit = await gitText(repo, ['commit-tree', tree, '-p', tip, '-F', '-'], { input: 'Shardflux landing result\n', env: { GIT_AUTHOR_NAME: 'Shardflux', GIT_AUTHOR_EMAIL: 'landing@shardflux.dev', GIT_COMMITTER_NAME: 'Shardflux', GIT_COMMITTER_EMAIL: 'landing@shardflux.dev' } });
+    return { commit, shadowed };
+}
+/**
+ * Lands several finished conversations into one branch with one apply: one twin, the merges in their VMs in parallel,
+ * then their new commits stacked here in the given (finish) order and the files written once. A conversation whose
+ * commits do not stack cleanly on the earlier ones is 'deferred' (it lands next, against the new state).
+ */
+export async function landingBatch(items, shared) {
+    const now = shared.now ?? Date.now, t0 = now(), timings = {};
+    const mark = (name) => { timings[name] = now() - t0; };
+    const snap = await takeSnapshot(shared);
+    if ('state' in snap)
+        return items.map(() => ({ ...snap, timings }));
+    mark('snapshot');
+    const inputs = items.map(it => ({ ...shared, mode: 'auto', conversation: it.conversation, upto: it.upto, known: it.known }));
+    const lands = await Promise.all(items.map((it, i) => mergeInVm(it.cell, inputs[i], snap, () => undefined)
+        .catch((error) => ({ state: 'error', reason: 'exception', message: error instanceof Error ? error.message : String(error) }))));
+    mark('merge');
+    const outcomes = lands.map(land => land.state === 'ready' ? undefined : { state: land.state === 'error' ? 'error' : land.state, land, timings });
+    const branch = `refs/heads/${shared.into}`, base = snap.base, included = [];
+    let cur = base;
+    for (const [i, land] of lands.entries()) {
+        if (land.state !== 'ready')
+            continue;
+        const next = cur === base ? land.tip : await replayOnto(shared.repo, cur, base, land.tip);
+        if (next) {
+            cur = next;
+            included.push(i);
+        }
+        else
+            outcomes[i] = { state: 'deferred', reason: 'stacked', land, timings };
+    }
+    try {
+        if (!included.length)
+            return outcomes.map(o => o);
+        const result = included.length === 1 ? { commit: lands[included[0]].result, shadowed: lands[included[0]].shadowed ?? [] } : await resultCommit(shared.repo, base, snap.commit, cur);
+        mark('stack');
+        const first = items[included[0]].conversation;
+        const applied = await applyLanding({ worktree: shared.worktree, repo: shared.repo, branch, base, twin: snap.commit, tip: cur, result: result.commit }, { backupRoot: shared.backupRoot, quietMs: shared.quietMs, now, label: { conversation_id: first.id, name: included.map(i => items[i].conversation.name).join('+'), title: first.title } });
+        mark('apply');
+        for (const i of included) {
+            const land = { ...lands[i], shadowed: result.shadowed };
+            outcomes[i] = applied.state === 'applied'
+                ? { state: 'landed', land, applied, timings, confirmed: confirmInVm(items[i].cell, inputs[i], snap, land, timings, t0, now) }
+                : { ...applied, reason: 'reason' in applied ? applied.reason : 'busy', land, timings };
+        }
+        return outcomes.map(o => o);
+    }
+    finally {
+        for (const it of items)
+            await dropLandRefs(shared.repo, it.conversation.name);
+    }
 }
 export class TwinLedger {
     store;