@shardflux/cli 0.16.0 → 0.18.0-next.4

package/dist/worktree-twin-engine.d.ts

@@ -56,19 +56,46 @@ export interface EngineDeps {
     hub?: string;
     vmTmp?: string;
     quietMs?: number;
+    /**
+     * Long-polls the conversation's next finished turn after `after` (RFC 3339): the turn's conversation and report time,
+     * null when the wait timed out. Throws TurnWaitUnsupported when the API has no turn waits.
+     */
+    waitTurn?(c: TwinConversation, after: string, signal: AbortSignal): Promise<{
+        conversation: TwinConversation;
+        reported_at: string;
+    } | null | 'ended'>;
 }
 /** A turn ended with committed work only; the agent is not asking anything. */
 export declare function finished(c: TwinConversation, agents: TwinAgent[]): TwinAgent | 'state' | null;
 export declare function eligible(c: TwinConversation, ledger: TwinLedger, now: number): boolean;
 export declare function conflictMessage(into: string, files: string[]): string;
+type Ready = {
+    c: TwinConversation;
+    record: LocalConversation;
+    mode: Exclude<LandingMode, 'off'>;
+    agent: TwinAgent | null;
+    at: number;
+};
+/** Refused by an API without turn waits (POST /wait with turn_after, 422): the twin polls instead. */
+export declare class TurnWaitUnsupported extends Error {
+}
 export declare class TwinEngine {
     #private;
     constructor(deps: EngineDeps);
-    /** 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(): Promise<void>;
+    /** Stops every turn wait. */
+    stop(): void;
+    /**
+     * 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.
+     */
     tick(signal?: AbortSignal): Promise<number>;
     /** Back online or awake: every conversation's retry backoff is cleared, so the next pass tries all of them. */
     resetBackoff(): void;
     landOne(c: TwinConversation, record: LocalConversation, mode: Exclude<LandingMode, 'off'>, agent: TwinAgent | null, signal?: AbortSignal): Promise<number | undefined>;
+    /** Several finished conversations for one branch: merged in their VMs at once, the files written once. */
+    landBatch(items: Ready[], signal?: AbortSignal): Promise<number | undefined>;
 }
 export interface LoopDeps {
     tick(signal: AbortSignal): Promise<number>;
@@ -81,6 +108,8 @@ export interface LoopDeps {
     network(): string;
     /** Whether the API host answers now (a TCP connect, no request). */
     reachable(): Promise<boolean>;
+    /** Resolves when a pushed turn waits to land: the loop's sleep ends at once. */
+    kicked?(): Promise<void>;
     log(line: string): void;
 }
 /**
@@ -93,3 +122,4 @@ export declare function runTwinLoop(deps: LoopDeps, signal: AbortSignal): Promis
 /** The device helper's twin. Nothing here asks the user anything. */
 export declare function runWorktreeTwin(ctx: Ctx, device: string, signal: AbortSignal): Promise<void>;
 export declare const TWIN_HANDLERS: Record<string, Handler>;
+export {};

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;