@shardflux/cli 0.15.2 → 0.17.0

package/dist/conversations.js

@@ -7,6 +7,13 @@ import { ensureProjectGit } from "./project-git.js";
 import { seedAgentRepository } from "./agent-repository.js";
 import { UsageError } from "./errors.js";
 import { conversationClient } from "./conversation-commands.js";
+import { recordSeedSnapshot } from "./files-mirror.js";
+import { rememberTwinSeed, sendTwinSeed, twinCheckoutArgv, twinSeed } from "./worktree-twin.js";
+/**
+ * Whether the conversation has ended: its VM was reclaimed, or it was archived or discarded. A finished turn is `done`
+ * while its VM still takes the next turn; on Codex Cloud, `done` ends the conversation.
+ */
+export const conversationEnded = (c) => !!c.ended_at || c.state === 'archived' || c.landed?.how === 'discarded' || (c.route === 'codex-cloud' && c.state === 'done');
 export const conversationName = (c) => {
     const name = c.key.split('/').at(-1);
     if (!/^[a-z0-9][a-z0-9-]{0,47}$/.test(name) || c.branch !== `shard/${name}`)
@@ -23,11 +30,12 @@ export function localConversations(ctx) {
     const records = new AgentStateStore(ctx.store.dir).read().conversations ?? {};
     return Object.fromEntries(Object.entries(records).filter(([, r]) => r.api_url === ctx.apiUrl));
 }
-export function rememberConversation(ctx, c, folder, handedOff = false) {
+export function rememberConversation(ctx, c, folder, handedOff = false, baseBranch) {
     validateConversation(c);
     new AgentStateStore(ctx.store.dir).update(doc => {
         const records = doc.conversations ?? {};
-        records[c.id] = { api_url: ctx.apiUrl, folder, project_id: c.project_id, conversation: c, ...(handedOff ? { handed_off: true } : {}) };
+        const base = baseBranch ?? records[c.id]?.base_branch;
+        records[c.id] = { api_url: ctx.apiUrl, folder, project_id: c.project_id, conversation: c, ...(handedOff ? { handed_off: true } : {}), ...(base ? { base_branch: base } : {}) };
         doc.conversations = records;
     });
 }
@@ -68,9 +76,36 @@ export async function conversationWorkspace(ctx, c) {
         await ws.wake({ timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
     return ws;
 }
+/**
+ * A thread on an existing computer (a join) is prepared by that computer's guest: its worktree, then its harness. Waits
+ * until the guest confirms it (the conversation no longer carries restore instructions), within the wake timeout.
+ */
+export async function waitThreadReady(ctx, c, pollMs = 1000) {
+    const deadline = Date.now() + ctx.wakeTimeoutMs;
+    for (;;) {
+        const current = await getConversation(ctx, c.id);
+        if (!current.restore || current.restore.kind !== 'join')
+            return current;
+        if (current.state === 'done' || current.state === 'archived' || current.ended_at)
+            throw new UsageError('This thread ended before it started.');
+        if (Date.now() >= deadline)
+            throw new UsageError(`The computer is still preparing this thread; open it with shard agents open ${c.id} in a moment.`);
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(done, Math.min(pollMs, Math.max(1, deadline - Date.now())));
+            function done() { ctx.signal.removeEventListener('abort', abort); resolve(); }
+            function abort() { clearTimeout(timer); reject(ctx.signal.reason ?? new Error('interrupted')); }
+            ctx.signal.addEventListener('abort', abort, { once: true });
+        });
+    }
+}
 export async function restoreConversationBinding(ctx, c, ws) {
     if (!c.restore || c.restore.kind === 'new')
         return;
+    // Threads on an existing computer (0.16.0+): its guest prepares them, never this command.
+    if (c.restore.kind === 'join') {
+        await waitThreadReady(ctx, c);
+        return;
+    }
     const cell = ws.cell();
     if (c.restore.kind === 'join' && c.restore.read_only === true) {
         const review = await cell.exec.run(['sf-agent', 'conversation', 'restore', '--args', '{"start":false}'], { cwd: c.worktree_path, env: { SF_CONVERSATION_ID: c.id }, timeoutMs: 120_000, signal: ctx.signal });
@@ -86,32 +121,38 @@ export async function restoreConversationBinding(ctx, c, ws) {
     if (result.exitCode !== 0)
         throw new Error(`Conversation restore failed: ${result.stderr.trim()}`);
 }
-export async function createConversationRecord(ctx, folder, harness, route, name, allocated, idempotencyKey = randomUUID()) {
+export async function createConversationRecord(ctx, folder, harness, route, name, allocated, idempotencyKey = randomUUID(), choice = {}) {
     const project = projectIdentity(folder);
     await ensureProjectGit(ctx, project.folder);
     // Both the conversation API and its legacy workspace fallback need a usable local HEAD.
     await conversationClient(ctx).conversations.list({ limit: 1 });
     const git = gitRunner(project.folder, { ...process.env, ...ctx.io.env }, ctx.signal);
-    const commit = await git(['rev-parse', 'HEAD']);
+    const head = await git(['rev-parse', 'HEAD']);
     const branch = await git(['symbolic-ref', '--quiet', '--short', 'HEAD']).catch(() => undefined);
+    // Uncommitted edits ride along as the twin snapshot the conversation starts from (worktree-twin.ts).
+    const seed = await twinSeed(ctx.store.dir, project.folder, head, ctx.store.profile(ctx.apiUrl).project_id).catch(() => ({ commit: head, snapshot: false }));
+    const commit = seed.commit;
     const response = await conversationClient(ctx).conversations.create({ repoRemote: project.remote ?? `file://${project.folder}`, harness, route, mode: 'new',
-        base: { commit, ...(branch ? { branch } : {}) }, ...(name ? { name } : {}), projectId: ctx.store.profile(ctx.apiUrl).project_id }, { idempotencyKey, signal: ctx.signal });
+        base: { commit, ...(branch ? { branch } : {}) }, ...(name ? { name } : {}), ...choice, projectId: ctx.store.profile(ctx.apiUrl).project_id }, { idempotencyKey, signal: ctx.signal });
     const c = validateConversation({ ...response.conversation, restore: response.restore });
     allocated?.(response.workspace);
-    rememberConversation(ctx, c, project.folder);
+    rememberTwinSeed(ctx.store.dir, c.id, project.folder, seed, branch);
+    rememberConversation(ctx, c, project.folder, false, branch);
     return c;
 }
-export async function createConversation(ctx, folder, harness, route, name) {
+export async function createConversation(ctx, folder, harness, route, name, choice = {}) {
     const project = projectIdentity(folder);
-    const c = await createConversationRecord(ctx, project.folder, harness, route, name);
+    const c = await createConversationRecord(ctx, project.folder, harness, route, name, undefined, undefined, choice);
     try {
         const ws = await conversationWorkspace(ctx, c);
         // This is a one-time seed. A conversation never watches or writes the owner's checkout.
         await seedAgentRepository(ctx, ws, project.folder, { root: c.worktree_path, populate: true });
         const cell = ws.cell();
-        const result = await cell.exec.run(['git', '-C', c.worktree_path, 'checkout', '-B', c.branch, c.base_commit], { timeoutMs: 30_000, signal: ctx.signal });
+        await sendTwinSeed(ctx.store.dir, cell, c, project.folder, ctx.signal);
+        const result = await cell.exec.run(twinCheckoutArgv(ctx.store.dir, c), { timeoutMs: 30_000, signal: ctx.signal });
         if (result.exitCode !== 0)
             throw new Error(`Conversation branch could not be prepared: ${result.stderr.trim()}`);
+        await recordSeedSnapshot(ws, c, ctx.signal);
         return { conversation: c, workspace: ws };
     }
     catch (error) {
@@ -127,8 +168,10 @@ export async function createConversation(ctx, folder, harness, route, name) {
     }
 }
 export async function resumeConversation(ctx, c) {
-    if (c.state !== 'done' && c.state !== 'archived')
+    if (!conversationEnded(c))
         return getConversation(ctx, c.id);
     const response = await conversationClient(ctx).conversations.resume(c.id, { idempotencyKey: randomUUID(), signal: ctx.signal });
     return validateConversation({ ...response.conversation, restore: response.restore });
 }
+/** The model and effort a conversation's harness starts with, as its record keeps them. */
+export const recordedChoice = (c) => ({ ...(c.model ? { model: c.model } : {}), ...(c.effort ? { effort: c.effort } : {}) });

package/dist/device-approvals.d.ts

@@ -0,0 +1,12 @@
+import type { DeviceApproval, DeviceChoice } from './device-bridge.js';
+import type { Ctx, Handler } from './commands.js';
+type Pending = DeviceApproval & {
+    nonce: string;
+    pid: number;
+};
+export declare function pendingDeviceApprovals(dir: string): Pending[];
+export declare function answerDeviceApproval(dir: string, id: string, choice: DeviceChoice): void;
+/** Local user-owned files carry approvals; cloud data can never answer its own request. */
+export declare function askLocalDeviceApproval(ctx: Ctx, approval: DeviceApproval): Promise<DeviceChoice>;
+export declare const DEVICE_HANDLERS: Record<string, Handler>;
+export {};

package/dist/device-approvals.js

@@ -0,0 +1,73 @@
+import { spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { readdirSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { writePrivateFile } from "./credentials.js";
+import { UsageError } from "./errors.js";
+import { json } from "./format.js";
+const paths = (dir, id) => {
+    if (!/^[a-zA-Z0-9_-]{1,96}$/.test(id))
+        throw new UsageError('Invalid device request id.');
+    return { pending: join(dir, 'device-approvals', `${id}.json`), answer: join(dir, 'device-answers', `${id}.json`) };
+};
+export function pendingDeviceApprovals(dir) {
+    let names;
+    try {
+        names = readdirSync(join(dir, 'device-approvals'));
+    }
+    catch {
+        return [];
+    }
+    return names.filter(n => n.endsWith('.json')).flatMap(n => {
+        try {
+            const p = JSON.parse(readFileSync(paths(dir, n.slice(0, -5)).pending, 'utf8'));
+            process.kill(p.pid, 0);
+            return [p];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+export function answerDeviceApproval(dir, id, choice) {
+    const pending = pendingDeviceApprovals(dir).find(p => p.request_id === id);
+    if (!pending)
+        throw new UsageError('That request is no longer waiting for approval. Run shard device requests.');
+    writePrivateFile(join(dir, 'device-answers'), paths(dir, id).answer, JSON.stringify({ nonce: pending.nonce, choice }));
+}
+/** Local user-owned files carry approvals; cloud data can never answer its own request. */
+export async function askLocalDeviceApproval(ctx, approval) {
+    const file = paths(ctx.store.dir, approval.request_id), nonce = randomUUID();
+    rmSync(file.answer, { force: true });
+    writePrivateFile(join(ctx.store.dir, 'device-approvals'), file.pending, JSON.stringify({ ...approval, nonce, pid: process.pid }));
+    spawnSync('notify-send', ['--', 'Shardflux approval', `${approval.summary}\nReview: shard device requests`], { env: ctx.io.env, stdio: 'ignore', timeout: 2000 });
+    try {
+        while (!ctx.signal.aborted) {
+            try {
+                const answer = JSON.parse(readFileSync(file.answer, 'utf8'));
+                if (answer.nonce === nonce && ['once', 'always', 'deny'].includes(answer.choice))
+                    return answer.choice;
+            }
+            catch { /* wait for the local CLI */ }
+            await delay(200, undefined, { signal: ctx.signal }).catch(() => undefined);
+        }
+        return 'deny';
+    }
+    finally {
+        rmSync(file.pending, { force: true });
+        rmSync(file.answer, { force: true });
+    }
+}
+export const DEVICE_HANDLERS = {
+    'device requests'(ctx) {
+        const requests = pendingDeviceApprovals(ctx.store.dir);
+        ctx.io.stdout.write(ctx.json ? json({ requests }) : requests.length ? requests.map(r => `${r.request_id}: ${r.summary}\n  Project: ${r.project_name ?? r.project_id}; conversation: ${r.conversation_title ?? r.conversation_id}\n  Local: ${r.local_path ?? '(none)'}; remote: ${r.remote_path ?? '(none)'}${r.argv ? `\n  Command: ${JSON.stringify(r.argv)}` : ''}${r.local_port ? `\n  Ports: ${r.local_port} → ${r.remote_port}` : ''}\n  shard device approve ${r.request_id} | shard device deny ${r.request_id}\n`).join('') : 'No device requests waiting for approval.\n');
+        return Promise.resolve(0);
+    },
+    ...Object.fromEntries(['approve', 'deny'].map(action => [`device ${action}`, (ctx, _values, [id]) => {
+            answerDeviceApproval(ctx.store.dir, id, action === 'approve' ? 'once' : 'deny');
+            ctx.io.stdout.write(ctx.json ? json({ request_id: id, choice: action }) : `Device request ${id}: ${action === 'approve' ? 'approved once' : 'denied'}.\n`);
+            return Promise.resolve(0);
+        }])),
+};

package/dist/device-helper.d.ts

@@ -1,3 +1,5 @@
 import type { Ctx } from './commands.js';
 /** The menu bar owns this helper and its stdin; VM data can request actions but cannot answer approvals. */
-export declare function runDeviceHelper(ctx: Ctx): Promise<number>;
+export declare function runDeviceHelper(ctx: Ctx, options?: {
+    service?: boolean;
+}): Promise<number>;

package/dist/device-helper.js

@@ -1,6 +1,7 @@
 import { setTimeout as delay } from 'node:timers/promises';
 import { DeviceExecutor, askConnectedAcp } from "./device-bridge.js";
 import { ConversationMirrorState, mirrorProjectConversations } from "./conversation-stash.js";
+import { FilesMirrorState, mirrorFilesOnce } from "./files-mirror.js";
 import { withTargetLock } from "./target-lock.js";
 import { join } from 'node:path';
 import { conversationsUnavailable } from "./conversations.js";
@@ -10,13 +11,15 @@ import { readFileSync } from 'node:fs';
 import { writePrivateFile } from "./credentials.js";
 import { conversationClient } from "./conversation-commands.js";
 import { Readable } from 'node:stream';
+import { runWorktreeTwin } from "./worktree-twin-engine.js";
+import { askLocalDeviceApproval } from "./device-approvals.js";
 /** The menu bar owns this helper and its stdin; VM data can request actions but cannot answer approvals. */
-export async function runDeviceHelper(ctx) {
+export async function runDeviceHelper(ctx, options = {}) {
     const abort = new AbortController(), signal = AbortSignal.any([ctx.signal, abort.signal]);
     ctx = { ...ctx, signal };
     const pending = new Map();
     const inputSource = Readable.from(ctx.io.stdin, { objectMode: false, signal });
-    const input = (async () => {
+    const input = options.service ? Promise.resolve() : (async () => {
         let tail = '';
         for await (const bytes of inputSource) {
             tail += Buffer.from(bytes).toString();
@@ -39,6 +42,8 @@ export async function runDeviceHelper(ctx) {
         const acp = await askConnectedAcp(ctx.store.dir, approval, signal);
         if (acp)
             return acp;
+        if (options.service)
+            return askLocalDeviceApproval(ctx, approval);
         return new Promise(resolve => {
             const denied = () => { pending.delete(approval.request_id); resolve('deny'); };
             signal.addEventListener('abort', denied, { once: true });
@@ -50,7 +55,7 @@ export async function runDeviceHelper(ctx) {
             ctx.io.stdout.write(JSON.stringify({ type: 'approval_resolved', request_id: approval.request_id }) + '\n'); });
     };
     const working = new Map();
-    const mirrored = new ConversationMirrorState();
+    const mirrored = new ConversationMirrorState(), files = new FilesMirrorState();
     const deviceFile = join(ctx.store.dir, 'device-id');
     let deviceId;
     try {
@@ -62,15 +67,19 @@ export async function runDeviceHelper(ctx) {
     }
     const executor = new DeviceExecutor(ctx, ask, deviceId);
     const report = (e) => { ctx.io.stderr.write(`Device bridge: ${e instanceof Error ? e.message : String(e)}\n`); };
-    let mirroring;
+    let mirroring, twin;
     try {
         return await withTargetLock(join(ctx.store.dir, 'device-helper-lock'), async () => {
+            // Finished conversations land in their local branches (worktree-twin-engine.ts); its own loop and backoff.
+            twin = runWorktreeTwin(ctx, deviceId, signal).catch(report);
             // A slow or failed transcript copy must not delay heartbeats, request polling or approvals.
             mirroring = (async () => {
                 let failures = 0;
                 const reported = new Set();
                 while (!signal.aborted) {
                     let wait = 1000;
+                    // Committed files of every conversation, under ~/Shardflux; its own interval and backoff.
+                    await mirrorFilesOnce(ctx, files);
                     try {
                         await mirrorProjectConversations(ctx, mirrored);
                         failures = 0;
@@ -124,6 +133,7 @@ export async function runDeviceHelper(ctx) {
         await executor.close();
         await Promise.all([...working.values()]);
         await mirroring;
+        await twin;
         await input.catch(() => undefined);
     }
 }

package/dist/errors.d.ts

@@ -114,6 +114,8 @@ export declare class ExecSessionRunningError extends HintedError {
 export interface ErrorInfo {
     code: string;
     message: string;
+    /** A refusal `shard` detects itself (CodedError, 0.17.0+): the next step, as plain text (the `hint:` line). */
+    fix?: string;
     status?: number;
     request_id?: string;
     retryable?: boolean;
@@ -121,6 +123,11 @@ export interface ErrorInfo {
     details?: Record<string, unknown>;
     source?: 'api' | 'cell' | 'unknown';
     last_state?: string;
+    /** A wait that timed out (0.16.0+): the operation's last state_reason. */
+    last_reason?: string;
+    /** A wait that timed out on a queued start (0.16.0+): its deadline (RFC 3339) and place in the queue. */
+    deadline_at?: string;
+    queue_position?: number;
     operation?: unknown;
     /** A file-first execution the error is about (failed, lost, still running, or left running by Ctrl-C). */
     execution_id?: string;

package/dist/errors.js

@@ -199,7 +199,17 @@ export function describeError(err) {
         };
     }
     if (err instanceof OperationTimeoutError) {
-        return { code: 'timeout', message: err.message, operation_id: err.operationId, last_state: err.lastState, ...(err.durable ? { details: { durable: false, state: 'pending' } } : {}) };
+        // A queued start (0.16.0+): its last reason, deadline and place in the queue.
+        return {
+            code: 'timeout',
+            message: err.message,
+            operation_id: err.operationId,
+            last_state: err.lastState,
+            ...(err.lastReason ? { last_reason: err.lastReason } : {}),
+            ...(err.deadlineAt ? { deadline_at: err.deadlineAt } : {}),
+            ...(err.queuePosition !== null ? { queue_position: err.queuePosition } : {}),
+            ...(err.durable ? { details: { durable: false, state: 'pending' } } : {}),
+        };
     }
     // --durable (0.7.0+): the suspend succeeded; its durable copy could not be made (see the lifecycle reference).
     if (err instanceof DurabilityLostError) {
@@ -231,7 +241,7 @@ export function describeError(err) {
     if (err instanceof GitError)
         return { code: 'git_error', message: err.message, retryable: false };
     if (err instanceof CodedError)
-        return { code: err.code, message: err.message, retryable: false, ...(err.details ? { details: err.details } : {}) };
+        return { code: err.code, message: err.message, retryable: false, ...(err.hint ? { fix: err.hint } : {}), ...(err.details ? { details: err.details } : {}) };
     if (err instanceof CheckoutTimeoutError) {
         return { code: 'timeout', message: `${err.message}; the checkout stays open (pay at its URL, then check with: shard billing status)`, last_state: err.checkout.status, details: { checkout_id: err.checkout.id, status: err.checkout.status, url: err.checkout.url } };
     }

package/dist/files-mirror.d.ts

@@ -0,0 +1,164 @@
+import type { Workspace } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+import type { Conversation, LocalConversation } from './conversations.js';
+/**
+ * Files across conversations on the Mac (docs/progress/cross-conversation-files.md): a read-only folder per
+ * conversation, `~/Shardflux/<repository>/<base branch>/<conversation>/`, holding what that conversation committed
+ * relative to its fork point. Git (the project hub) is the only channel; the user's own checkouts are never written.
+ * Files above the per-file limit, or past the conversation's total, are placeholders until `shard files pull`.
+ */
+export declare const HUB_PATH = "/shardflux/project/git/hub.git";
+export declare const MANIFEST = ".shardflux-manifest.json";
+export declare const PLACEHOLDER = ".placeholder.txt";
+export declare const FILES_CONFIG = ".shardflux/files.yaml";
+export declare const DEFAULT_MAX_FILE: number;
+export declare const DEFAULT_MAX_CONVERSATION: number;
+export type MirrorConversation = Conversation & {
+    name?: string;
+    join_mode?: string | null;
+    base_branch?: string | null;
+    repo_remote?: string;
+    landed?: {
+        how: string;
+        ref?: string;
+        at?: string;
+    } | null;
+};
+export interface ManifestFile {
+    path: string;
+    oid: string;
+    size: number;
+    mode: string;
+    state: 'present' | 'placeholder' | 'submodule' | 'symlink';
+    reason?: 'file_limit' | 'conversation_limit';
+    fetched?: boolean;
+}
+export interface Manifest {
+    version: 1;
+    conversation_id: string;
+    project_id: string;
+    name: string;
+    title: string;
+    repository: string;
+    branch: string;
+    base_branch: string | null;
+    commit: string;
+    fork_point: string;
+    seed?: string;
+    max_file_bytes: number;
+    max_conversation_bytes: number;
+    files: ManifestFile[];
+    deleted: string[];
+    landed?: {
+        how: string;
+        ref: string;
+        at: string;
+        note: string;
+    };
+    updated_at: string;
+}
+export interface Limits {
+    maxFile: number;
+    maxConversation: number;
+}
+export interface Change {
+    status: string;
+    mode: string;
+    oid: string;
+    path: string;
+}
+export declare function filesRoot(env: Record<string, string | undefined>): string;
+/** A base branch as one path component: slashes and other separators become "-". */
+export declare function branchFolder(branch: string | null | undefined): string;
+/** A human name as one Finder path component. */
+export declare function humanFolder(text: string, fallback: string): string;
+export declare function repositoryName(identity: string): string;
+export declare function parseFilesConfig(text: string | undefined): Limits;
+export declare function parseDiffTree(bytes: Buffer): Change[];
+export declare function safeRelative(path: string): boolean;
+/** Smallest first while the conversation's total stays within its limit; fetched files stay while unchanged. */
+export declare function planFiles(files: ManifestFile[], limits: Limits, prev: Map<string, ManifestFile>): ManifestFile[];
+export declare function humanBytes(n: number): string;
+export declare function placeholderText(m: Manifest, f: ManifestFile): string;
+export interface GitResult {
+    code: number;
+    stdout: Buffer;
+    stderr: string;
+}
+/**
+ * Read-only git against the project hub. `blobs` delivers `git cat-file --batch` output for the given ids, any number
+ * of files at once. (The hub's upload-pack, reached through the platform Git bridge, serves advertised refs only, so a
+ * fetch of single blobs by id is refused; this needs no hub configuration.)
+ */
+export interface Hub {
+    git(args: string[], stdin?: string): Promise<GitResult>;
+    blobs(oids: string[], onData: (chunk: Uint8Array) => void): Promise<void>;
+    close(): void;
+}
+/** A hub on this machine (tests). */
+export declare function localHub(path: string): Hub;
+/** The project hub through a ready VM of the project: git runs there, file contents stream back over the same exec API. */
+export declare function cellHub(ws: Workspace, signal: AbortSignal): Hub;
+/** Copy files' contents from the hub into root, in one stream. */
+export declare function copyFromHub(hub: Hub, root: string, files: ManifestFile[]): Promise<void>;
+export interface PlaceholderEntry {
+    conversation_id: string;
+    conversation: string;
+    title: string;
+    folder: string;
+    path: string;
+    size: number;
+    local_path: string;
+}
+export declare class FilesMirrorState {
+    readonly revisions: Map<string, string>;
+    retryAt: number;
+    failures: number;
+    listedAt: number;
+    readonly reported: Set<string>;
+}
+/** The repository a conversation belongs to: its normalized remote; worktrees of an origin-less repository share its Git common directory. */
+export declare function repositoryIdentity(c: MirrorConversation, local?: LocalConversation): {
+    id: string;
+    name: string;
+};
+export declare class FilesMirror {
+    #private;
+    readonly root: string;
+    readonly ctx: Pick<Ctx, 'io' | 'store' | 'apiUrl' | 'signal'>;
+    readonly connect: (projectId: string, all: MirrorConversation[]) => Promise<Hub>;
+    constructor(ctx: Pick<Ctx, 'io' | 'store' | 'apiUrl' | 'signal'>, connect: (projectId: string, all: MirrorConversation[]) => Promise<Hub>, root?: string);
+    get stateFile(): string;
+    get indexFile(): string;
+    /** One pass: only conversations whose API record moved touch the hub. */
+    sync(all: MirrorConversation[], state?: FilesMirrorState): Promise<void>;
+    /** Find a mirrored conversation by id, name or folder name. */
+    find(ref: string): {
+        rel: string;
+        manifest: Manifest;
+    };
+    /** Download one listed file, whatever its size. */
+    pull(ref: string, path: string, all: () => Promise<MirrorConversation[]>): Promise<{
+        conversation: string;
+        path: string;
+        local_path: string;
+        bytes: number;
+        already: boolean;
+    }>;
+}
+/**
+ * The seed snapshot (sh; $1 repository, $2 conversation name, $3 hub): HEAD plus the working tree the conversation was
+ * seeded with, committed in the conversation's VM with a temporary index (never on this computer), kept per worktree
+ * as refs/worktree/shard/seed and in the hub as refs/shard/seed/<name>. Mirrors leave out what it already contains,
+ * so the user's own uncommitted edits never show as the conversation's change. Threads on one computer are worktrees
+ * of one repository (0.16.0+), so the seed is per worktree; the shared refs/shard/seed of earlier seeds is read, and
+ * still written, only in the repository's main worktree.
+ */
+export declare const SEED_SNAPSHOT = "set -eu\ncd \"$1\"\nmain=0; [ \"$(git rev-parse --absolute-git-dir)\" = \"$(git rev-parse --path-format=absolute --git-common-dir)\" ] && main=1\nif git rev-parse -q --verify refs/worktree/shard/seed >/dev/null; then seed=$(git rev-parse refs/worktree/shard/seed)\nelif [ \"$main\" = 1 ] && git rev-parse -q --verify refs/shard/seed >/dev/null; then seed=$(git rev-parse refs/shard/seed); else\nidx=$(mktemp); trap 'rm -f \"$idx\"' EXIT\ncp \"$(git rev-parse --path-format=absolute --git-path index)\" \"$idx\" 2>/dev/null || { rm -f \"$idx\"; GIT_INDEX_FILE=\"$idx\" git read-tree HEAD; }\nGIT_INDEX_FILE=\"$idx\" git add -A\ntree=$(GIT_INDEX_FILE=\"$idx\" git write-tree)\nif [ \"$tree\" = \"$(git rev-parse 'HEAD^{tree}')\" ]; then seed=$(git rev-parse HEAD); else\nseed=$(GIT_AUTHOR_NAME=Shardflux GIT_AUTHOR_EMAIL=seed@shardflux.dev GIT_COMMITTER_NAME=Shardflux GIT_COMMITTER_EMAIL=seed@shardflux.dev git commit-tree \"$tree\" -p HEAD -m \"Shardflux: the working tree this conversation started from\"); fi\ngit update-ref refs/worktree/shard/seed \"$seed\"\nif [ \"$main\" = 1 ]; then git update-ref refs/shard/seed \"$seed\"; fi\nfi\nif [ -d \"$3\" ]; then git -c core.hooksPath=/dev/null push -q \"$3\" \"+$seed:refs/shard/seed/$2\" >/dev/null 2>&1 || true; fi\nprintf '%s\n' \"$seed\"\n";
+/** Best effort: without a snapshot the folder also lists the start state's own edits. */
+export declare function recordSeedSnapshot(ws: Pick<Workspace, 'cell'>, c: Pick<Conversation, 'worktree_path' | 'branch'>, signal?: AbortSignal): Promise<string | null>;
+/** A ready VM of the project (never woken), else the project's space reader, woken when needed. */
+export declare function workspaceHub(ctx: Ctx): (projectId: string, all: MirrorConversation[]) => Promise<Hub>;
+export declare function listMirrorConversations(ctx: Ctx): Promise<MirrorConversation[]>;
+/** The device helper's pass: list every few seconds; touch the hub only for conversations whose record moved. */
+export declare function mirrorFilesOnce(ctx: Ctx, state: FilesMirrorState, intervalMs?: number): Promise<void>;