@shardflux/cli 0.15.2 → 0.16.0

package/dist/worktree-twin-land.py

@@ -0,0 +1,331 @@
+"""Shardflux landing: runs in a conversation's VM, shipped and started by the shard CLI (worktree-twin.ts).
+
+Input: one JSON object on stdin. Output: one JSON object on stdout (exit 0; "state" says what happened).
+
+op "land" brings the conversation's committed work (its branch tip T) onto the user's branch tip B, as captured in the
+user's twin W (a snapshot commit whose first parent is B and whose tree is the user's working state):
+  B' (tip)    fast-forward to T when B is an ancestor of T and B..T holds no snapshot commit; otherwise the
+              conversation's first-parent commits since its last landed point replayed onto B (author and message
+              kept); if a replay step conflicts, one squash merge; if that conflicts too: state "conflict".
+  R (result)  merge-tree --merge-base B W B': the user's working state plus the conversation's changes. Overlapping
+              hunks keep the user's text (-X ours); any other conflicting path keeps the user's version.
+mode "pr" pushes B' to origin as the conversation branch and opens a pull request instead (gh).
+op "confirm" records T as landed (refs/shard/land/upto here) and, after the files are on the user's disk, copies the
+twin, tip, result and upto to the project hub (refs/shard/twin/<device>/<worktree>, refs/shard/land/<name>/*). The
+hub is on shared storage, so "land" never touches it: it only reads the hub's upto when nothing closer knows it.
+Small bundles travel inline (base64 in the JSON) instead of as files.
+
+Only Git plumbing: the conversation's worktree, index and HEAD are never changed.
+"""
+import base64
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import time
+
+SNAPSHOT = 'Shardflux-Snapshot:'
+INLINE_BYTES = 512 << 10
+STARTED = time.monotonic()
+PHASES = {}
+
+
+def phase(name):
+    PHASES[name] = int((time.monotonic() - STARTED) * 1000)
+
+
+class Fail(Exception):
+    def __init__(self, reason, message):
+        super().__init__(message)
+        self.reason = reason
+
+
+def git(cwd, *args, env=None, data=None, ok=(0,)):
+    full = dict(os.environ, GIT_TERMINAL_PROMPT='0', LC_ALL='C')
+    if env:
+        full.update(env)
+    p = subprocess.run(['git', '-c', 'core.hooksPath=/dev/null', *args], cwd=cwd, env=full, input=data,
+                       stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    if p.returncode not in ok:
+        tail = p.stderr.decode('utf-8', 'replace').strip()[-400:]
+        raise Fail('git', 'git %s failed (%d): %s' % (args[0], p.returncode, tail))
+    return p
+
+
+def text(cwd, *args, **kw):
+    return git(cwd, *args, **kw).stdout.decode('utf-8', 'surrogateescape').strip()
+
+
+def commit(cwd, rev):
+    p = git(cwd, 'rev-parse', '-q', '--verify', rev + '^{commit}', ok=(0, 1))
+    return p.stdout.decode().strip() if p.returncode == 0 else ''
+
+
+def ancestor(cwd, a, b):
+    return git(cwd, 'merge-base', '--is-ancestor', a, b, ok=(0, 1)).returncode == 0
+
+
+def tree_of(cwd, rev):
+    return text(cwd, 'rev-parse', rev + '^{tree}')
+
+
+def merge_tree(cwd, base, ours, theirs, strategy=None):
+    args = ['merge-tree', '--write-tree', '--name-only', '--no-messages', '-z', '--merge-base=' + base]
+    if strategy:
+        args += ['-X', strategy]
+    p = git(cwd, *args, ours, theirs, ok=(0, 1))
+    parts = p.stdout.decode('utf-8', 'surrogateescape').split('\0')
+    return parts[0].strip(), (sorted({x for x in parts[1:] if x}) if p.returncode == 1 else [])
+
+
+def message_of(cwd, rev):
+    raw = git(cwd, 'cat-file', 'commit', rev).stdout
+    return raw.split(b'\n\n', 1)[1] if b'\n\n' in raw else b''
+
+
+def author_of(cwd, rev):
+    name, email, date = text(cwd, 'log', '-1', '--format=%an%x00%ae%x00%ad', '--date=raw', rev).split('\0')
+    return {'GIT_AUTHOR_NAME': name, 'GIT_AUTHOR_EMAIL': email, 'GIT_AUTHOR_DATE': date}
+
+
+def committer(cwd):
+    name = git(cwd, 'config', 'user.name', ok=(0, 1)).stdout.decode().strip()
+    email = git(cwd, 'config', 'user.email', ok=(0, 1)).stdout.decode().strip()
+    return {'GIT_COMMITTER_NAME': name or 'Shardflux', 'GIT_COMMITTER_EMAIL': email or 'landing@shardflux.dev'}
+
+
+def commit_tree(cwd, tree, parents, message, env):
+    args = ['commit-tree', tree]
+    for p in parents:
+        args += ['-p', p]
+    return text(cwd, *args, '-F', '-', env=env, data=message)
+
+
+def snapshot(message):
+    return any(line.startswith(SNAPSHOT) for line in message.decode('utf-8', 'replace').splitlines())
+
+
+def replay(cwd, onto, commits, who):
+    cur = onto
+    for c in commits:
+        message = message_of(cwd, c)
+        if snapshot(message):
+            continue
+        parent = commit(cwd, c + '^1')
+        if not parent:
+            return None
+        tree, conflicts = merge_tree(cwd, parent, cur, c)
+        if conflicts:
+            return None
+        if tree == tree_of(cwd, cur):
+            continue  # already there (as rebase drops a commit that became empty)
+        cur = commit_tree(cwd, tree, [cur], message, dict(who, **author_of(cwd, c)))
+    return cur
+
+
+def user_side(cwd, upto, base, tip, who):
+    """The user's state the conversation already contains, as a merge base for squashing it onto base.
+
+    Normally that is upto (its starting snapshot or last landed point). When the conversation merged the user's branch
+    (resolving a conflict), it also contains that branch's commit mb: the base is then upto and mb merged (a commit
+    made here, never pushed), so neither the user's commits nor the uncommitted edits it started from count as the
+    conversation's change. None when the two cannot be merged cleanly."""
+    p = git(cwd, 'merge-base', base, tip, ok=(0, 1))
+    mb = p.stdout.decode().strip()
+    if not mb or ancestor(cwd, mb, upto):
+        return upto
+    if ancestor(cwd, upto, mb):
+        return mb
+    p = git(cwd, 'merge-base', upto, mb, ok=(0, 1))
+    common = p.stdout.decode().strip()
+    if not common:
+        return None
+    tree, conflicts = merge_tree(cwd, common, mb, upto)
+    if conflicts:
+        return None
+    return commit_tree(cwd, tree, [mb, upto], b'Shardflux: user state\n', who)
+
+
+def override(cwd, tree, source, paths):
+    """tree with each of paths (files or directories) taken from source, the user's working state, or removed when
+    source lacks it."""
+    fd, index = tempfile.mkstemp(prefix='shard-land-index-')
+    os.close(fd)
+    os.unlink(index)
+    env = {'GIT_INDEX_FILE': index}
+    try:
+        git(cwd, 'read-tree', tree, env=env)
+        git(cwd, 'rm', '-r', '-q', '--cached', '--ignore-unmatch', '--', *paths, env=env)
+        listing = git(cwd, 'ls-tree', '-r', '-z', '--full-tree', source, '--', *paths).stdout
+        lines = b''.join(item.replace(b' blob ', b' ', 1).replace(b' commit ', b' ', 1) + b'\0' for item in listing.split(b'\0') if item)
+        if lines:
+            git(cwd, 'update-index', '-z', '--index-info', env=env, data=lines)
+        return text(cwd, 'write-tree', env=env)
+    finally:
+        if os.path.exists(index):
+            os.unlink(index)
+
+
+def changed(cwd, a, b):
+    out = git(cwd, 'diff-tree', '-r', '-z', '--name-only', '--no-renames', a, b).stdout.decode('utf-8', 'surrogateescape')
+    return sorted({x for x in out.split('\0') if x})
+
+
+def hub_ref(cwd, hub, ref):
+    if not hub or not os.path.isdir(hub):
+        return ''
+    # One ref read on the shared storage (ls-remote would start upload-pack and list every ref: most of a second).
+    p = git(cwd, '--git-dir=' + hub, 'rev-parse', '-q', '--verify', ref, ok=(0, 1, 128))
+    return p.stdout.decode().strip() if p.returncode == 0 else ''
+
+
+def land(a):
+    cwd, hub, name = a['repo'], a.get('hub') or '', a['name']
+    if not os.path.isdir(hub):
+        hub = ''
+    branch = 'refs/heads/' + a['branch']
+    head = git(cwd, 'symbolic-ref', '-q', 'HEAD', ok=(0, 1)).stdout.decode().strip()
+    if head != branch:
+        raise Fail('not_on_branch', 'the conversation worktree is on %s, not %s' % (head or 'a detached HEAD', branch))
+    tip = commit(cwd, 'HEAD')
+    phase('start')
+    if a.get('bundle_b64'):
+        fd, path = tempfile.mkstemp(prefix='shard-twin-', suffix='.bundle')
+        with os.fdopen(fd, 'wb') as f:
+            f.write(base64.b64decode(a['bundle_b64']))
+        a['bundle'] = path
+    if a.get('bundle'):
+        # A VM without an earlier landing of this conversation lacks the bundle's prerequisites: the CLI then sends
+        # everything since the conversation's base.
+        try:
+            p = git(cwd, 'fetch', '-q', '--no-tags', a['bundle'], '+%s:refs/shard/twin-in' % a['twin_ref'], ok=(0, 1, 128))
+        finally:
+            if a.get('bundle_b64'):
+                os.unlink(a['bundle'])
+        phase('twin_in')
+        if p.returncode != 0:
+            reason = 'prerequisites' if b'prerequisite' in p.stderr else 'git'
+            raise Fail(reason, 'twin bundle: %s' % p.stderr.decode('utf-8', 'replace').strip()[-400:])
+    twin = commit(cwd, a['twin'])
+    if not twin:
+        raise Fail('twin_missing', 'the twin %s did not arrive' % a['twin'])
+    base = commit(cwd, twin + '^1')
+    if not base:
+        raise Fail('twin_unborn', 'the twin has no branch commit')
+    git(cwd, 'update-ref', 'refs/shard/twin-in', twin)
+    result = {'base': base, 'twin': twin, 'tip': base, 'result': twin, 'upto': tip, 'conversation_tip': tip}
+    upto = ''
+    candidates = (lambda: a.get('upto') or '', lambda: commit(cwd, 'refs/shard/land/upto'),
+                  lambda: hub_ref(cwd, hub, 'refs/shard/land/%s/upto' % name), lambda: a.get('base') or '')
+    for get in candidates:
+        candidate = get()
+        if candidate and commit(cwd, candidate) and ancestor(cwd, candidate, tip):
+            upto = commit(cwd, candidate)
+            break
+    if not upto:
+        upto = text(cwd, 'merge-base', tip, base) if git(cwd, 'merge-base', tip, base, ok=(0, 1)).returncode == 0 else ''
+    if not upto:
+        raise Fail('unrelated', 'the conversation shares no history with the twin')
+    if upto == tip or ancestor(cwd, tip, base):
+        result['state'] = 'noop'
+        return result
+    phase('upto')
+    who = committer(cwd)
+    log = git(cwd, 'log', '--format=%H%x1f%B%x1e', '%s..%s' % (base, tip)).stdout if ancestor(cwd, base, tip) else b''
+    commits = [x for x in text(cwd, 'rev-list', '--reverse', '--first-parent', tip, '^' + upto, '^' + base).split('\n') if x]
+    if ancestor(cwd, base, tip) and not any(snapshot(e.split(b'\x1f', 1)[1]) for e in log.split(b'\x1e') if b'\x1f' in e):
+        new, method = tip, 'fast-forward'
+    else:
+        new, method = replay(cwd, base, commits, who), 'replay'
+        if new is None:
+            mb = user_side(cwd, upto, base, tip, who)
+            tree, conflicts = merge_tree(cwd, mb, base, tip) if mb else ('', ['(user branch)'])
+            if conflicts:
+                result.update(state='conflict', stage='commits', conflicts=conflicts)
+                return result
+            subjects = []
+            for c in commits:
+                m = message_of(cwd, c)
+                if not snapshot(m) and not commit(cwd, c + '^2'):
+                    subjects.append('- ' + m.decode('utf-8', 'replace').split('\n', 1)[0])
+            body = '%s\n\n%s\n\nShardflux-Conversation: %s\n' % (a.get('title') or a['branch'], '\n'.join(subjects), a.get('conversation_id', ''))
+            new, method = commit_tree(cwd, tree, [base], body.encode(), dict(who, **author_of(cwd, tip))), 'squash'
+    phase('commits')
+    result.update(tip=new, method=method)
+    if new == base or tree_of(cwd, new) == tree_of(cwd, base):
+        result['state'] = 'noop'
+        return result
+    if a.get('mode') == 'pr':
+        git(cwd, 'push', '-q', '--force', 'origin', '%s:refs/heads/%s' % (new, a['branch']))
+        url = subprocess.run(['gh', 'pr', 'view', a['branch'], '--json', 'url,state', '--jq', 'select(.state == "OPEN") | .url'],
+                             cwd=cwd, stdout=subprocess.PIPE, stderr=subprocess.PIPE).stdout.decode().strip()
+        if not url:
+            p = subprocess.run(['gh', 'pr', 'create', '--base', a['into'], '--head', a['branch'], '--title', a.get('title') or a['branch'],
+                                '--body', a.get('summary') or ''], cwd=cwd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+            if p.returncode != 0:
+                raise Fail('pr', 'gh pr create failed: %s' % p.stderr.decode('utf-8', 'replace').strip()[-400:])
+            url = p.stdout.decode().strip().split('\n')[-1]
+        result.update(state='pr', url=url)
+        return result
+    tree, conflicts = merge_tree(cwd, base, twin, new)
+    shadowed = list(conflicts)
+    if conflicts:
+        tree, rest = merge_tree(cwd, base, twin, new, 'ours')
+        if rest:
+            tree = override(cwd, tree, twin, rest)
+    trailers = 'Shardflux-Conversation: %s\nShardflux-Into: %s\nShardflux-Twin: %s\nShardflux-Upto: %s\n' % (a.get('conversation_id', ''), a['into'], twin, tip)
+    res = commit_tree(cwd, tree, [new], ('Shardflux landing result\n\n' + trailers).encode(), dict(who, GIT_AUTHOR_NAME='Shardflux', GIT_AUTHOR_EMAIL='landing@shardflux.dev'))
+    git(cwd, 'update-ref', 'refs/shard/land/tip', new)
+    git(cwd, 'update-ref', 'refs/shard/land/result', res)
+    phase('result')
+    out = a['out']
+    git(cwd, 'bundle', 'create', '-q', out, 'refs/shard/land/tip', 'refs/shard/land/result', '--not', base)
+    phase('bundle')
+    size = os.path.getsize(out)
+    result.update(state='ready', result=res, files=changed(cwd, twin, res), shadowed=shadowed, bundle=out, bundle_bytes=size)
+    if size <= INLINE_BYTES:
+        with open(out, 'rb') as f:
+            result['bundle_b64'] = base64.b64encode(f.read()).decode()
+        os.unlink(out)
+        result['bundle'] = None
+    return result
+
+
+def confirm(a):
+    cwd, hub = a['repo'], a.get('hub') or ''
+    upto = commit(cwd, a['upto'])
+    if not upto:
+        raise Fail('unknown_commit', 'landed commit %s is not in this repository' % a['upto'])
+    git(cwd, 'update-ref', 'refs/shard/land/upto', upto)
+    if a.get('into'):
+        # The guest's turn-end report keeps the conversation landed while HEAD is this commit.
+        path = text(cwd, 'rev-parse', '--git-path', 'shard-landed')
+        path = path if os.path.isabs(path) else os.path.join(cwd, path)
+        with open(path + '.tmp', 'w') as f:
+            f.write('%s %s\n' % (upto, a['into']))
+        os.replace(path + '.tmp', path)
+    phase('recorded')
+    if hub and os.path.isdir(hub):
+        refs = ['+%s:refs/shard/land/%s/upto' % (upto, a['name'])]
+        for sha, ref in ((a.get('twin'), a.get('hub_twin_ref')), (a.get('tip'), 'refs/shard/land/%s/tip' % a['name']),
+                         (a.get('result'), 'refs/shard/land/%s/result' % a['name'])):
+            if sha and ref and commit(cwd, sha):
+                refs.append('+%s:%s' % (sha, ref))
+        git(cwd, 'push', '-q', '--atomic', '--no-verify', hub, *refs)
+        phase('hub')
+    return {'state': 'confirmed', 'upto': upto, 'hub': bool(hub and os.path.isdir(hub))}
+
+
+def main():
+    a = json.loads(sys.stdin.read())
+    try:
+        out = confirm(a) if a.get('op') == 'confirm' else land(a)
+    except Fail as e:
+        out = {'state': 'error', 'reason': e.reason, 'message': str(e)}
+    out['phases'] = PHASES
+    sys.stdout.write(json.dumps(out) + '\n')
+
+
+if __name__ == '__main__':
+    main()

package/dist/worktree-twin.d.ts

@@ -0,0 +1,296 @@
+import type { CellClient } from '@shardflux/sdk';
+import { AgentStateStore } from './agent-state.js';
+/** Files above this stay at HEAD's version in a twin (the bound the seed copy already uses). */
+export declare const TWIN_MAX_FILE_BYTES: number;
+/** A file the landing rewrites must be untouched this long first. */
+export declare const QUIET_MS = 2000;
+export declare const HUB_PATH = "/shardflux/project/git/hub.git";
+export interface GitResult {
+    code: number;
+    stdout: Buffer;
+    stderr: string;
+}
+export declare class TwinGitError extends Error {
+    readonly code: number;
+    readonly stderr: string;
+    constructor(args: string[], result: GitResult);
+}
+export interface GitOptions {
+    env?: Record<string, string>;
+    input?: string | Uint8Array;
+    ok?: number[];
+    signal?: AbortSignal;
+}
+/** Git with no hooks, no fsmonitor and no optional locks; binary-safe output. */
+export declare function git(cwd: string, args: string[], options?: GitOptions): Promise<GitResult>;
+export declare function gitText(cwd: string, args: string[], options?: GitOptions): Promise<string>;
+export interface WorktreeInfo {
+    root: string;
+    gitDir: string;
+    commonDir: string;
+    head: string | null;
+    branch: string | null;
+}
+export declare function inspectWorktree(root: string): Promise<WorktreeInfo>;
+/** The user's own Git operation in progress: the twin waits for it. */
+export declare function pauseReason(info: Pick<WorktreeInfo, 'gitDir' | 'commonDir'>): string | null;
+export interface WorktreeEntry {
+    root: string;
+    head: string | null;
+    branch: string | null;
+}
+export declare function listWorktrees(anyRoot: string): Promise<WorktreeEntry[]>;
+export declare const worktreeId: (root: string) => string;
+export declare const twinRef: (id: string) => string;
+export declare const hubTwinRef: (device: string, id: string) => string;
+export interface Snapshot {
+    commit: string;
+    tree: string;
+    base: string;
+    branch: string | null;
+    root: string;
+    id: string;
+    held: string[];
+    headTree: string;
+}
+/**
+ * One snapshot commit of the worktree's working state (what `git add -A` sees; `.shard/` and files above the size gate
+ * left at HEAD's version), first parent HEAD. Kept as refs/shard/twin/<worktree id>; an unchanged state reuses it.
+ */
+export declare function snapshotWorktree(info: WorktreeInfo, options: {
+    device: string;
+    stateDir: string;
+    maxFileBytes?: number;
+    now?: Date;
+    signal?: AbortSignal;
+}): Promise<Snapshot>;
+/** A twin for a branch checked out nowhere: its own tree, first parent its tip. */
+export declare function refTwin(repo: string, branch: string, device: string, now?: Date): Promise<Snapshot>;
+export interface LandingPlan {
+    /** The worktree where the branch is checked out; null lands the branch ref only. */
+    worktree: WorktreeInfo | null;
+    repo: string;
+    branch: string;
+    base: string;
+    twin: string;
+    tip: string;
+    result: string;
+}
+export interface Applied {
+    state: 'applied';
+    files: string[];
+    raced: string[];
+    backup: string | null;
+    at: number;
+}
+export type ApplyOutcome = Applied | {
+    state: 'paused';
+    reason: string;
+} | {
+    state: 'moved';
+    reason: string;
+    paths?: string[];
+} | {
+    state: 'busy';
+    waitMs: number;
+};
+export interface ApplyOptions {
+    backupRoot: string;
+    quietMs?: number;
+    now?: () => number;
+    label: {
+        conversation_id: string;
+        name: string;
+        title: string;
+    };
+    /** Called just before each file's final check (tests reproduce a save in that gap). */
+    beforeWrite?: (path: string) => void;
+}
+/** Prune twin backups older than 14 days, then the oldest while the total exceeds 1 GiB. */
+export declare function pruneBackups(root: string, now?: number, maxDays?: number, maxBytes?: number): string[];
+export interface BackupManifest {
+    version: 1;
+    created_at: string;
+    worktree: string;
+    branch: string;
+    conversation_id: string;
+    name: string;
+    title: string;
+    from: string;
+    to: string;
+    twin: string;
+    result: string;
+    files: {
+        path: string;
+        action: 'modify' | 'delete' | 'create';
+        before: string | null;
+        after: string | null;
+        saved: boolean;
+    }[];
+}
+/** Writes each backed-up file back (the current content is backed up first); files the landing created are removed. */
+export declare function restoreBackup(backup: string, options: {
+    backupRoot: string;
+    now?: () => number;
+}): Promise<{
+    restored: string[];
+    backup: string;
+}>;
+/**
+ * Moves the branch from plan.base to plan.tip and the worktree from plan.twin's tree to plan.result's tree, only where
+ * the disk still holds what the twin captured and has been quiet. Never drops a user's edit: a changed file means
+ * 'moved' (redo the round), a running Git operation 'paused', a recent write 'busy'.
+ */
+export declare function applyLanding(plan: LandingPlan, options: ApplyOptions): Promise<ApplyOutcome>;
+/** Index entries that equal the old tip move to the new tip; entries the user staged differently are merged three ways. */
+export declare function refreshIndex(root: string, base: string, tip: string, attempts?: number): Promise<void>;
+export type TwinCell = {
+    exec: Pick<CellClient['exec'], 'run'>;
+    files: Pick<CellClient['files'], 'read' | 'write' | 'remove' | 'stat'>;
+};
+export interface RoundConversation {
+    id: string;
+    name: string;
+    title: string;
+    summary: string;
+    branch: string;
+    base_commit: string;
+    worktree_path: string;
+}
+export interface RoundInput {
+    conversation: RoundConversation;
+    into: string;
+    mode: 'auto' | 'pr';
+    device: string;
+    repo: string;
+    worktree: WorktreeInfo | null;
+    stateDir: string;
+    backupRoot: string;
+    /** The conversation's last landed tip known here (the ledger), and local commits the VM is known to have. */
+    upto?: string;
+    known?: string[];
+    hub?: string;
+    vmTmp?: string;
+    quietMs?: number;
+    signal?: AbortSignal;
+    now?: () => number;
+    /**
+     * The conversation's VM is gone (it ended while this computer was away): the round runs in another VM of the project
+     * that reads the project hub, on a temporary repository holding the conversation's branch from the hub. The hub is
+     * only read; repoRemote lets `pr` push to the repository's origin.
+     */
+    fromHub?: {
+        repoRemote?: string;
+    };
+}
+export interface LandResult {
+    state: 'ready' | 'noop' | 'conflict' | 'pr' | 'error';
+    base?: string;
+    twin?: string;
+    tip?: string;
+    result?: string;
+    upto?: string;
+    conversation_tip?: string;
+    method?: string;
+    phases?: Record<string, number>;
+    files?: string[];
+    shadowed?: string[];
+    conflicts?: string[];
+    stage?: string;
+    url?: string;
+    reason?: string;
+    message?: string;
+    bundle?: string | null;
+    bundle_b64?: string;
+    bundle_bytes?: number;
+    hub?: boolean;
+}
+export type RoundOutcome = {
+    state: 'landed';
+    land: LandResult;
+    applied: Applied;
+    timings: Record<string, number>;
+    confirmed: Promise<void>;
+} | {
+    state: 'noop' | 'pr' | 'conflict' | 'error';
+    land: LandResult;
+    timings: Record<string, number>;
+} | {
+    state: 'paused' | 'moved' | 'busy';
+    reason: string;
+    waitMs?: number;
+    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;
+export declare function runLandingScript(cell: TwinCell, input: Record<string, unknown>, signal?: AbortSignal): Promise<LandResult>;
+/** 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 type LandingMode = 'auto' | 'pr' | 'off';
+export interface TwinConversationState {
+    base_branch?: string;
+    seed?: string;
+    seed_snapshot?: boolean;
+    folder?: string;
+    upto?: string;
+    tip?: string;
+    landed_revision?: string;
+    landed_at?: string;
+    method?: string;
+    conflict_tip?: string;
+    conflict_revision?: string;
+    pr_url?: string;
+    failures?: number;
+    retry_at?: number;
+    last_error?: string;
+    latency_ms?: number;
+}
+interface TwinDoc {
+    landing?: Record<string, LandingMode>;
+    conversations?: Record<string, TwinConversationState>;
+}
+export declare class TwinLedger {
+    readonly store: AgentStateStore;
+    constructor(dir: string);
+    read(): TwinDoc;
+    mode(project: string): LandingMode;
+    setMode(project: string, mode: LandingMode): void;
+    conversation(id: string): TwinConversationState;
+    patch(id: string, change: Partial<TwinConversationState>): void;
+    forget(id: string): void;
+    update(change: (doc: TwinDoc) => void): void;
+}
+export declare const backupRoot: (stateDir: string) => string;
+export declare function relativeTo(root: string, path: string): string;
+/** This computer's device id (the device helper's), created on first use. */
+export declare function deviceId(stateDir: string): string;
+export interface TwinSeed {
+    commit: string;
+    snapshot: boolean;
+}
+/**
+ * The commit a new conversation starts from: HEAD when the worktree is clean (or landing is off, or the user's Git
+ * operation is running), else the twin snapshot S (first parent HEAD). The conversation's own work is then S..T, and
+ * the user's edits stay theirs.
+ */
+export declare function twinSeed(stateDir: string, folder: string, head: string, project?: string): Promise<TwinSeed>;
+export declare function rememberTwinSeed(stateDir: string, conversation: string, folder: string, seed: TwinSeed, branch?: string): void;
+/** Carries a snapshot seed into the conversation's VM repository (one small bundle: the snapshot over HEAD). */
+export declare function sendTwinSeed(stateDir: string, cell: TwinCell, conversation: {
+    id: string;
+    base_commit: string;
+    worktree_path: string;
+}, folder: string, signal?: AbortSignal): Promise<void>;
+/**
+ * The conversation branch at its base. A snapshot base already matches the copied files: the branch starts at HEAD
+ * and moves to the snapshot without touching them (`checkout` would refuse the "local changes").
+ */
+export declare function twinCheckoutArgv(stateDir: string, conversation: {
+    id: string;
+    branch: string;
+    base_commit: string;
+    worktree_path: string;
+}): string[];
+export {};