@shardflux/cli 0.15.2 → 0.17.0

package/dist/worktree-twin-engine.js

@@ -0,0 +1,615 @@
+/**
+ * The device helper's live twin loop (0.16.0+): watches the API (conversations and agent sessions, never a VM) for
+ * conversations whose turn ended with committed work and lands each into the local branch it started from, with no
+ * input. One landing at a time, in the order the turns finished; anything unsafe pauses and retries. A conversation
+ * that ended while this computer was away (its VM reclaimed) lands from the project hub. After being offline or asleep
+ * the loop retries at once (runTwinLoop). See worktree-twin.ts.
+ */
+import { connect } from 'node:net';
+import { networkInterfaces } from 'node:os';
+import { existsSync } from 'node:fs';
+import { setTimeout as delay } from 'node:timers/promises';
+import { out } from "./commands.js";
+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, 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). */
+export const ended = (c) => !!c.ended_at || c.state === 'archived';
+const revision = (c) => JSON.stringify([c.changes, c.summary]);
+/** A turn ended with committed work only; the agent is not asking anything. */
+export function finished(c, agents) {
+    if (ended(c))
+        return 'state';
+    const agent = agents.find(a => a.workspace_id === c.workspace_id && c.harness_session_id && a.id === `${c.workspace_id}:${c.harness_session_id}`);
+    if (agent)
+        return agent.state === 'working' ? null : agent;
+    return c.state === 'unresolved' || c.state === 'done' ? 'state' : null;
+}
+export function eligible(c, ledger, now) {
+    if (c.route === 'codex-cloud' || c.join_mode === 'reviewer' || c.state === 'needs_you')
+        return false;
+    if (!c.changes || c.changes.commits <= 0 || c.changes.uncommitted || c.landed?.how === 'discarded')
+        return false;
+    const st = ledger.conversation(c.id);
+    // An ended conversation is landed here unless someone landed it some other way before it ended.
+    if (ended(c) && c.landed && !st.landed_revision)
+        return false;
+    if ((st.retry_at ?? 0) > now)
+        return false;
+    if (st.landed_revision === revision(c) && (ended(c) || c.landed?.how === 'merged' || c.landed?.how === 'pr'))
+        return false;
+    return st.conflict_revision !== revision(c);
+}
+export function conflictMessage(into, files) {
+    const list = files.length > 8 ? `${files.slice(0, 8).join(', ')} and ${files.length - 8} more` : files.join(', ');
+    return `Shardflux could not land your commits into ${into} on the user's computer: ${list} also changed in the user's newer commits on ${into}. `
+        + `Merge their branch into yours and commit: git merge refs/shard/twin-in^1 (refs/shard/twin-in is the user's working state as of now; its first parent is the tip of their ${into}). `
+        + `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);
+    } }
+    /** 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;
+        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 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) : [];
+            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));
+        }
+        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() {
+        this.#deps.ledger.update(doc => { for (const st of Object.values(doc.conversations ?? {})) {
+            st.failures = 0;
+            st.retry_at = 0;
+        } });
+        this.#reported.clear();
+        this.#nextFull = -Infinity;
+    }
+    /** 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);
+        const label = `${c.title || name} (${c.id})`;
+        if (!into || into.startsWith('shard/')) {
+            this.#report(c.id, `Twin: ${label} has no local base branch to land into.`);
+            return;
+        }
+        if (!existsSync(record.folder)) {
+            this.#report(c.id, `Twin: ${record.folder} is gone; ${label} stays in the cloud.`);
+            return;
+        }
+        // Landed at this revision already; only the API record is missing (a later report reset it on an older guest).
+        if (st.landed_revision === rev) {
+            if (ended(c))
+                return;
+            if ((this.#posted.get(c.id) ?? 0) + 30_000 < d.now()) {
+                this.#posted.set(c.id, d.now());
+                await d.land(c, st.pr_url ? 'pr' : 'merge', st.pr_url ?? into);
+            }
+            return;
+        }
+        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);
+            // The VM is gone (reclaimed while this computer was away): its branch is in the project hub.
+            if (!vm) {
+                vm = await d.hubCell(c.project_id);
+                fromHub = true;
+            }
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw error;
+            return this.#fail(c, p.label, error instanceof Error ? error.message : String(error));
+        }
+        let outcome;
+        try {
+            let worktree = p.worktree;
+            for (let attempt = 0; attempt < 3; attempt++) {
+                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;
+            }
+        }
+        catch (error) {
+            vm.close();
+            if (signal?.aborted)
+                throw 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;
+        }
+        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))
+                return;
+            this.#posted.set(c.id, d.now());
+            await d.land(c, action, ref);
+        };
+        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.
+                void o.confirmed.catch((error) => { this.#report(c.id, `Twin: ${label} landed; recording it in its VM failed: ${error instanceof Error ? error.message : String(error)}.`); })
+                    .finally(() => vm.close());
+                const latency = agent ? o.applied.at - Date.parse(agent.since) : undefined;
+                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 ${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(', ')}).`);
+                return;
+            }
+            case 'noop':
+                d.ledger.patch(c.id, { upto: o.land.upto, landed_revision: rev, failures: 0, retry_at: 0 });
+                if (c.landed?.how !== 'merged')
+                    await post('merge', into);
+                return;
+            case 'pr':
+                d.ledger.patch(c.id, { tip: o.land.tip, landed_revision: rev, pr_url: o.land.url, failures: 0, retry_at: 0 });
+                await post('pr', o.land.url);
+                d.log(`Twin: opened ${o.land.url} for ${label}.`);
+                return;
+            case 'conflict':
+                if (st.conflict_tip !== o.land.conversation_tip) {
+                    // Its agent resolves it; an ended conversation is restored into a fresh VM first.
+                    if (ended(c))
+                        await d.resume(c);
+                    await d.message(c, conflictMessage(into, o.land.conflicts ?? []));
+                }
+                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;
+            case 'paused': return 1000;
+            case 'moved':
+                d.ledger.patch(c.id, { retry_at: d.now() + 2000 });
+                return 2000;
+            case 'error': return this.#fail(c, label, `${o.land.reason}: ${o.land.message ?? ''}`);
+        }
+    }
+    #fail(c, label, message) {
+        const d = this.#deps, failures = (d.ledger.conversation(c.id).failures ?? 0) + 1, wait = Math.min(300_000, 5000 * 2 ** Math.min(failures - 1, 6));
+        d.ledger.patch(c.id, { failures, retry_at: d.now() + wait, last_error: message });
+        this.#report(c.id, `Twin: ${label} could not land yet: ${message} (retrying in ${Math.round(wait / 1000)} s).`);
+        return wait;
+    }
+}
+const PROBE_MS = 5000, JUMP_MS = 5000;
+/**
+ * Runs the twin's passes. A failing pass (offline) backs off up to 5 minutes, but the wait ends at once when the
+ * computer wakes from sleep (the wall clock jumps past the monotonic one), when its network changes, or when the API
+ * host answers again (probed every 5 s while failing); every conversation's retry backoff is then cleared and a pass
+ * runs immediately. The first pass that succeeds after failures clears them too and runs again at once.
+ */
+export async function runTwinLoop(deps, signal) {
+    let failures = 0, net = deps.network();
+    const reported = new Set();
+    while (!signal.aborted) {
+        let wait;
+        try {
+            wait = await deps.tick(signal);
+            if (failures) {
+                failures = 0;
+                deps.resetBackoff();
+                wait = 0;
+            }
+        }
+        catch (error) {
+            if (signal.aborted)
+                break;
+            wait = Math.min(300_000, 5000 * 2 ** Math.min(failures++, 6));
+            const message = error instanceof Error ? error.message : String(error);
+            if (!conversationsUnavailable(error) && !reported.has(message)) {
+                reported.add(message);
+                deps.log(`Twin: ${message} (retrying in ${wait / 1000} s).`);
+            }
+        }
+        let left = wait, probed = deps.mono();
+        while (left > 0 && !signal.aborted) {
+            const slice = Math.min(1000, left), wall = deps.wall(), mono = deps.mono();
+            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;
+            net = now;
+            let back = false;
+            if (failures && deps.mono() - probed >= PROBE_MS) {
+                probed = deps.mono();
+                back = await deps.reachable().catch(() => false);
+            }
+            if (woke || changed || back) {
+                deps.resetBackoff();
+                left = 0;
+            }
+        }
+    }
+}
+function networkSignature() {
+    const all = [];
+    for (const [name, list] of Object.entries(networkInterfaces()))
+        for (const a of list ?? [])
+            if (!a.internal)
+                all.push(`${name} ${a.address}`);
+    return all.sort().join(',');
+}
+function reachable(url) {
+    const u = new URL(url), port = Number(u.port || (u.protocol === 'http:' ? 80 : 443));
+    return new Promise(resolve => {
+        const socket = connect({ host: u.hostname, port, timeout: 3000 });
+        const done = (ok) => { socket.destroy(); resolve(ok); };
+        socket.once('connect', () => done(true));
+        socket.once('timeout', () => done(false));
+        socket.once('error', () => done(false));
+    });
+}
+const gone = (error) => error.status === 404 || error.details?.reason === 'workspace_deleted';
+/** The device helper's twin. Nothing here asks the user anything. */
+export async function runWorktreeTwin(ctx, device, signal) {
+    const client = () => conversationClient(ctx);
+    const open = (ws) => {
+        const cell = ws.cell({ agentLabel: 'shard-twin' });
+        return { cell, close: () => cell.close() };
+    };
+    const engine = new TwinEngine({
+        records: () => Object.values(localConversations(ctx)),
+        conversations: async (projectId) => await listConversations(ctx, projectId),
+        agents: async (projectId) => {
+            // A signed-in session without a project key has no agent list here; the conversation state then decides.
+            const api = client(), all = [];
+            if (!('agents' in api))
+                return all;
+            let cursor;
+            do {
+                const page = await api.agents.list({ projectId, limit: 200, ...(cursor ? { cursor } : {}) });
+                all.push(...page.data);
+                cursor = page.nextCursor ?? undefined;
+            } while (cursor);
+            return all;
+        },
+        cell: async (c) => {
+            let ws;
+            try {
+                ws = await client().workspaces.get(c.workspace_id);
+            }
+            catch (error) {
+                if (gone(error))
+                    return null;
+                throw error;
+            }
+            if (ws.data.deleted_at)
+                return null;
+            if (!ws.ready)
+                await ws.wake({ timeoutMs: ctx.wakeTimeoutMs, signal });
+            return open(ws);
+        },
+        hubCell: async (projectId) => {
+            // An awake VM of the project reads the hub without waking anything; else the project's small space reader.
+            const all = (await listConversations(ctx, projectId)).filter(c => !ended(c))
+                .sort((a, b) => (b.last_activity_at ?? '').localeCompare(a.last_activity_at ?? ''));
+            for (const c of all) {
+                try {
+                    const ws = await client().workspaces.get(c.workspace_id);
+                    if (!ws.data.deleted_at && ws.ready)
+                        return open(ws);
+                }
+                catch { /* another may be awake */ }
+            }
+            const reader = await client().conversations.spaceReader(projectId, { signal });
+            const ws = await client().workspaces.get(reader.workspace.id);
+            if (!ws.ready)
+                await ws.wake({ timeoutMs: ctx.wakeTimeoutMs, signal });
+            return open(ws);
+        },
+        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), kicked: () => engine.pushed(),
+        log: line => { ctx.io.stderr.write(line + '\n'); },
+    }, signal);
+}
+const MODES = ['auto', 'pr', 'off'];
+function projectOf(ctx, path) {
+    const folder = projectIdentity(path ?? process.cwd()).folder;
+    const local = Object.values(localConversations(ctx)).find(r => r.folder === folder);
+    const project = local?.project_id ?? ctx.store.profile(ctx.apiUrl).project_id;
+    if (!project)
+        throw new UsageError('No Shardflux project for this checkout: start a conversation here first, or run shard setup.');
+    return project;
+}
+export const TWIN_HANDLERS = {
+    /** shard conversations landing [auto|pr|off|restore <backup>|backups] */
+    async 'conversations landing'(ctx, values, [action, arg]) {
+        const ledger = new TwinLedger(ctx.store.dir), project = projectOf(ctx, typeof values.path === 'string' ? values.path : undefined), root = backupRoot(ctx.store.dir);
+        if (action === 'restore') {
+            if (!arg || !/^[\w.:-]+$/.test(arg))
+                throw new UsageError('Name a backup: shard conversations landing backups');
+            const r = await restoreBackup(join(root, arg), { backupRoot: root });
+            out(ctx, `Restored ${r.restored.length} file${r.restored.length === 1 ? '' : 's'}. The replaced versions are in backup ${r.backup.split('/').at(-1)}.\n`, r);
+            return 0;
+        }
+        if (action === 'backups') {
+            const list = (existsSync(root) ? readdirSync(root) : []).filter(n => existsSync(join(root, n, 'manifest.json'))).sort().reverse()
+                .map(id => { const m = JSON.parse(readFileSync(join(root, id, 'manifest.json'), 'utf8')); return { id, created_at: m.created_at, worktree: m.worktree, title: m.title, files: m.files.map(f => f.path) }; });
+            out(ctx, list.map(b => `${b.id}\t${b.title}\t${b.files.length} files\t${b.worktree}`).join('\n') + (list.length ? '\n' : 'No landing backups.\n'), { backups: list });
+            return 0;
+        }
+        if (action !== undefined) {
+            if (!MODES.includes(action))
+                throw new UsageError('Choose auto, pr or off (or restore <backup>, backups).');
+            ledger.setMode(project, action);
+        }
+        const mode = ledger.mode(project);
+        const text = mode === 'auto' ? 'Finished conversations land in your local branch automatically.' : mode === 'pr' ? 'Finished conversations open a pull request instead of landing locally.' : 'Automatic landing is off for this project.';
+        out(ctx, `${text}\n`, { project_id: project, landing: mode });
+        return 0;
+    },
+};