@shardflux/cli 0.18.1 → 0.19.1

package/dist/agent-config-sync.js

@@ -1,13 +1,17 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { closeSync, mkdirSync, openSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { parse, stringify } from 'smol-toml';
-import { ShardfluxApiError } from '@shardflux/sdk';
+import { ShardfluxApiError, tarEnd, tarHeader, tarPadding } from '@shardflux/sdk';
 import { AgentStateStore } from "./agent-state.js";
 import { UsageError } from "./errors.js";
 import { collectPlugins, collectUserFiles, object, readObject, readOptional, rewritePaths } from "./agent-config-files.js";
 import { digest, prepareMcp } from "./agent-config-mcp.js";
 import { configIssueLines } from "./agent-config-report.js";
 const missing = (e) => e instanceof ShardfluxApiError && e.status === 404;
+const parseFailure = (e) => e instanceof SyntaxError || (e instanceof Error && /^expected an object in /.test(e.message));
 const markerPath = '.config/shardflux/agent-config.json';
 const safePath = (path) => !path.split('/').some(p => !p || p === '.' || p === '..') &&
     (/^(?:\.claude\/(?:settings\.json|CLAUDE\.md)|\.codex\/(?:config\.toml|AGENTS\.md))$/.test(path) ||
@@ -96,19 +100,129 @@ async function bindMcpSecret(ctx, ws, secrets, spec) {
     ctx.io.stderr.write(`MCP secret bound to ${ws.key}; an already running agent picks it up when restarted.\n`);
     return true;
 }
-export async function applyConfigFiles(cell, home, files, previous, trustManifest, issues, signal, deleteMissing = true, progress = () => { }) {
+/** At least this many files to check go into the VM as one archive and one command instead of a stat and a write each. */
+export const BULK_MIN_FILES = 8;
+/**
+ * Applies a whole pass in two requests (0.19.0+): one tar archive written into the VM, and one command that compares
+ * each member with what is there (a regular file with the same SHA-256 and mode is left alone; anything else that is
+ * not a regular file is reported and kept), replaces the rest atomically, and removes the owned files that are gone
+ * locally while they still hold what this sync wrote. A 3,000-file config took ~6,000 sequential requests (5 minutes)
+ * file by file. Undefined when the VM cannot run it (no python3): the caller applies the pass file by file.
+ */
+const BULK_APPLY = String.raw `
+import hashlib, json, os, sys, tarfile
+archive, home = sys.argv[1], sys.argv[2]
+remove = json.loads(sys.stdin.read() or '[]')
+out = {'existed': [], 'written': [], 'not_file': [], 'removed': [], 'changed': []}
+def digest(path):
+    h = hashlib.sha256()
+    with open(path, 'rb') as f:
+        for chunk in iter(lambda: f.read(1 << 20), b''): h.update(chunk)
+    return h.hexdigest()
+try:
+    with tarfile.open(archive) as tar:
+        for m in tar:
+            if not m.isfile(): continue
+            dest = os.path.join(home, m.name)
+            data = tar.extractfile(m).read()
+            mode = m.mode & 0o7777
+            if os.path.lexists(dest):
+                out['existed'].append(m.name)
+                if os.path.islink(dest) or not os.path.isfile(dest):
+                    out['not_file'].append(m.name); continue
+                if (os.stat(dest).st_mode & 0o7777) == mode and digest(dest) == hashlib.sha256(data).hexdigest(): continue
+            os.makedirs(os.path.dirname(dest), exist_ok=True)
+            tmp = dest + '.sf-sync'
+            fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, mode)
+            with os.fdopen(fd, 'wb') as f: f.write(data)
+            os.chmod(tmp, mode)
+            os.replace(tmp, dest)
+            out['written'].append(m.name)
+finally:
+    os.unlink(archive)
+for name, expected in remove:
+    dest = os.path.join(home, name)
+    if not os.path.lexists(dest): continue
+    if os.path.islink(dest) or not os.path.isfile(dest) or digest(dest) != expected: out['changed'].append(name); continue
+    os.unlink(dest); out['removed'].append(name)
+print(json.dumps(out))
+`;
+async function bulkApply(cell, home, files, remove, signal) {
+    const parts = [];
+    let size = 0;
+    const push = (bytes) => { parts.push(bytes); size += bytes.length; };
+    for (const [path, file] of files) {
+        push(tarHeader({ path, type: 'file', mode: Number.parseInt(file.mode, 8), size: file.content.length }));
+        push(file.content);
+        push(tarPadding(file.content.length));
+    }
+    push(tarEnd(size));
+    const archive = Buffer.concat(parts);
+    const path = `${home}/.config/shardflux/.config-sync-${randomUUID()}.tar`;
+    await cell.files.write(path, archive, { mode: '0600', createParents: true });
+    const run = await cell.exec.run(['python3', '-c', BULK_APPLY, path, home], { stdin: JSON.stringify(remove), signal, timeoutMs: 120_000, maxOutputBytes: 16 << 20 });
+    if (run.exitCode !== 0) {
+        await cell.files.remove(path).catch(() => undefined);
+        return undefined;
+    }
+    try {
+        const result = JSON.parse(run.stdout);
+        return Array.isArray(result.written) && Array.isArray(result.existed) ? result : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function applyConfigFiles(cell, home, files, previous, trustManifest, issues, signal, deleteMissing = true, progress = () => { }, trusted = new Set()) {
     const next = {};
     const copied = [], removed = [];
+    const pending = [];
     for (const [path, file] of files) {
-        signal.throwIfAborted();
         if (!safePath(path))
             throw new Error('agent config attempted to write outside its allowlist');
-        const hash = digest(file.content);
         const old = previous[path];
-        if (trustManifest && old?.hash === hash && old.mode === file.mode) {
+        if ((trustManifest || trusted.has(path)) && old?.hash === digest(file.content) && old.mode === file.mode)
             next[path] = old;
+        else
+            pending.push([path, file]);
+    }
+    const gone = [];
+    for (const [path, old] of Object.entries(deleteMissing ? previous : {})) {
+        if (files.has(path))
             continue;
+        if (!safePath(path))
+            throw new Error('agent config manifest contains a path outside its allowlist');
+        if (old.created)
+            gone.push([path, old]);
+    }
+    if (pending.length + gone.length >= BULK_MIN_FILES) {
+        signal.throwIfAborted();
+        const bulk = await bulkApply(cell, home, pending, gone.map(([path, old]) => [path, old.hash]), signal);
+        if (bulk) {
+            const existed = new Set(bulk.existed), notFile = new Set(bulk.not_file), written = new Set(bulk.written);
+            for (const [path, file] of pending) {
+                if (notFile.has(path)) {
+                    issues.push({ item: path, reason: 'remote path is not a regular file' });
+                    continue;
+                }
+                if (written.has(path))
+                    copied.push(path);
+                next[path] = { hash: digest(file.content), mode: file.mode, created: previous[path]?.created ?? !existed.has(path) };
+                progress(path, next[path]);
+            }
+            for (const path of bulk.changed)
+                issues.push({ item: path, reason: 'remote file was changed; deletion preserved it' });
+            for (const path of bulk.removed) {
+                removed.push(path);
+                progress(path, undefined);
+            }
+            return { files: inOrder(files, next), copied, removed };
         }
+    }
+    for (const [path, file] of pending) {
+        signal.throwIfAborted();
+        const hash = digest(file.content);
+        const old = previous[path];
         let exists = false, same = false;
         try {
             const info = await cell.files.stat(`${home}/${path}`, { revision: true });
@@ -130,14 +244,8 @@ export async function applyConfigFiles(cell, home, files, previous, trustManifes
         next[path] = { hash, mode: file.mode, created: old?.created ?? !exists };
         progress(path, next[path]);
     }
-    for (const [path, old] of Object.entries(deleteMissing ? previous : {})) {
+    for (const [path, old] of gone) {
         signal.throwIfAborted();
-        if (files.has(path))
-            continue;
-        if (!safePath(path))
-            throw new Error('agent config manifest contains a path outside its allowlist');
-        if (!old.created)
-            continue;
         try {
             const info = await cell.files.stat(`${home}/${path}`, { revision: true });
             if (info.type !== 'file' || info.revision !== old.hash) {
@@ -153,7 +261,29 @@ export async function applyConfigFiles(cell, home, files, previous, trustManifes
                 throw error;
         }
     }
-    return { files: next, copied, removed };
+    return { files: inOrder(files, next), copied, removed };
+}
+/** The manifest lists files in the local order, so an unchanged config hashes the same whichever path applied it. */
+function inOrder(files, next) {
+    const ordered = {};
+    for (const path of files.keys())
+        if (next[path])
+            ordered[path] = next[path];
+    return ordered;
+}
+/** Plugins named in the plan are installed by the VM's own Claude Code, from their marketplaces (one command). */
+async function installPlugins(cell, plan, issues, signal) {
+    const script = 'command -v claude >/dev/null 2>&1 || { echo "missing"; exit 0; }\n' +
+        'n=$1; shift; while [ "$n" -gt 0 ]; do claude plugin marketplace add "$1" >/dev/null 2>&1 || true; shift; n=$((n-1)); done\n' +
+        'for id in "$@"; do claude plugin install "$id" --scope user >/dev/null 2>&1 || echo "failed $id"; done\n';
+    const run = await cell.exec.run(['sh', '-c', script, 'shard-plugins', String(plan.marketplaces.length), ...plan.marketplaces.map(m => m.source), ...plan.plugins], { signal, timeoutMs: 300_000, maxOutputBytes: 65536 });
+    if (run.stdout.trim() === 'missing') {
+        issues.push({ item: 'plugins', reason: 'Claude Code is not installed in this VM' });
+        return;
+    }
+    for (const line of run.stdout.split('\n'))
+        if (line.startsWith('failed '))
+            issues.push({ item: `plugin:${line.slice(7)}`, reason: 'could not be installed in the VM' });
 }
 export async function syncAgentConfig(ctx, ws) {
     const home = ctx.io.env.HOME || homedir();
@@ -162,8 +292,18 @@ export async function syncAgentConfig(ctx, ws) {
     const issues = [];
     const files = await collectUserFiles(home, issues);
     const codexBytes = await readOptional(join(home, '.codex/config.toml'));
-    const claude = await readObject(join(home, '.claude.json'));
-    const hasPlugins = await readOptional(join(home, '.claude/plugins/installed_plugins.json')) || await readOptional(join(home, '.claude/plugins/known_marketplaces.json'));
+    // One file that does not parse is skipped with a reason; it never stops the rest of the sync.
+    let claude;
+    try {
+        claude = await readObject(join(home, '.claude.json'));
+    }
+    catch (error) {
+        if (!parseFailure(error))
+            throw error;
+        issues.push({ item: '.claude.json', reason: 'not valid JSON; its MCP servers were not copied' });
+    }
+    const plugins = await collectPlugins(home, issues);
+    const hasPlugins = plugins.marketplaces.length > 0 || plugins.plugins.length > 0;
     const empty = { workspace_id: ws.id, workspace_key: ws.key, copied: [], removed: [], skipped: issues, mcp: [], synced_at: null };
     if (!files.size && !codexBytes && !hasPlugins && !Object.keys(object(claude?.mcpServers)).length && !previous)
         return empty;
@@ -172,17 +312,6 @@ export async function syncAgentConfig(ctx, ws) {
     const remoteHome = run.stdout.trim();
     if (run.exitCode !== 0 || !/^\/(?:[a-zA-Z0-9._-]+\/)*[a-zA-Z0-9._-]+$/.test(remoteHome) || remoteHome.split('/').some(p => p === '..' || p === '.'))
         throw new Error('agent config could not resolve the VM user home');
-    const skippedPlugins = await collectPlugins(home, remoteHome, files, issues);
-    if (skippedPlugins.size && files.has('.claude/settings.json')) {
-        const file = files.get('.claude/settings.json');
-        const settings = object(JSON.parse(file.content.toString('utf8')));
-        const enabled = object(settings.enabledPlugins);
-        for (const id of skippedPlugins)
-            if (id in enabled)
-                enabled[id] = false;
-        settings.enabledPlugins = enabled;
-        file.content = Buffer.from(JSON.stringify(settings) + '\n');
-    }
     // Claude settings stay the user's. sf-agent hooks are in /etc/claude-code/managed-settings.json.
     const secrets = { ...previous?.secrets, ...object(object(store.read().agent_config_secrets)[key(ctx, ws.id)]) };
     const commandCache = new Map();
@@ -200,45 +329,44 @@ export async function syncAgentConfig(ctx, ws) {
     const partial = { v: 1, workspace_id: ws.id, workspace_key: ws.key, api_url: ctx.apiUrl, home: remoteHome,
         sync_state: 'applying', remote_hash: previous?.remote_hash, synced_at: previous?.synced_at ?? null, files: { ...previous?.files },
         claude_mcp: previous?.claude_mcp ?? [], claude_mcp_owned: previous?.claude_mcp_owned, secrets, skipped: issues, mcp: previous?.mcp ?? [], tunnels: previous?.tunnels ?? [] };
+    // Progress is recorded at most every 250 ms and at the end of each pass, never once per file of thousands.
+    let savedAt = 0;
+    const flushPartial = () => {
+        savedAt = Date.now();
+        store.update(doc => { const all = object(doc.agent_config); all[key(ctx, ws.id)] = partial; doc.agent_config = all; });
+    };
     const savePartial = (path, file) => {
         if (file)
             partial.files[path] = file;
         else
             delete partial.files[path];
-        store.update(doc => { const all = object(doc.agent_config); all[key(ctx, ws.id)] = partial; doc.agent_config = all; });
+        if (Date.now() - savedAt >= 250)
+            flushPartial();
     };
     const marker = await optionalRemote(cell, `${remoteHome}/${markerPath}`);
     const trust = marker?.workspace_id === ws.id && typeof previous?.remote_hash === 'string' && marker.manifest_hash === previous.remote_hash;
     // Stage executable payloads before checking stdio paths. Structured configuration is prepared before transfer.
     const payload = new Map([...files].filter(([path]) => !/\.(?:json|toml)$/.test(path) && path !== '.claude/settings.json'));
-    const staged = await applyConfigFiles(cell, remoteHome, payload, previous?.files ?? {}, trust, issues, ctx.signal, false, savePartial);
+    const staged = await applyConfigFiles(cell, remoteHome, payload, previous?.files ?? {}, trust, issues, ctx.signal, false, savePartial).finally(flushPartial);
     const mcpCtx = { home, remoteHome, workspaceId: ws.id, files, issues, env: ctx.io.env, exists, bind: (secret) => bindMcpSecret(ctx, ws, secrets, secret) };
-    // Installed plugins can declare MCP servers inline or in .mcp.json. Treat their env exactly like user MCP env.
-    for (const [path, file] of files) {
-        if (!path.startsWith('.claude/plugins/cache/') || !(path.endsWith('/.mcp.json') || path.endsWith('/.claude-plugin/plugin.json')))
-            continue;
-        const doc = object(JSON.parse(file.content.toString('utf8')));
-        const isManifest = path.endsWith('/plugin.json');
-        const inline = doc.mcpServers;
-        if (isManifest && (typeof inline === 'string' || Array.isArray(inline)))
-            continue; // Referenced .mcp.json files are handled in this same pass.
-        const servers = isManifest || inline ? object(inline) : doc;
-        if (!Object.keys(servers).length)
-            continue;
-        const root = `${remoteHome}/${path.slice(0, path.lastIndexOf(isManifest ? '/.claude-plugin/' : '/'))}`;
-        const pluginCtx = { ...mcpCtx, namespace: path, exists: (command) => exists(command.replaceAll('${CLAUDE_PLUGIN_ROOT}', root)) };
-        const portable = await prepareMcp('claude', servers, pluginCtx, mcp, tunnels);
-        file.content = Buffer.from(JSON.stringify(isManifest || inline ? { ...doc, mcpServers: portable } : portable) + '\n');
-    }
     const claudeMcp = await prepareMcp('claude', object(claude?.mcpServers), mcpCtx, mcp, tunnels);
     if (codexBytes) {
-        const config = parse(codexBytes.toString('utf8'));
-        const servers = await prepareMcp('codex', object(config.mcp_servers), mcpCtx, mcp, tunnels);
-        delete config.mcp_servers;
-        const portable = object(rewritePaths(config, home, remoteHome, files, issues, 'codex:config'));
-        if (Object.keys(servers).length || 'mcp_servers' in parse(codexBytes.toString('utf8')))
-            portable.mcp_servers = servers;
-        files.set('.codex/config.toml', { content: Buffer.from(stringify(portable)), mode: '0600' });
+        let config;
+        try {
+            config = parse(codexBytes.toString('utf8'));
+        }
+        catch {
+            issues.push({ item: '.codex/config.toml', reason: 'not valid TOML; not copied' });
+        }
+        if (config) {
+            const declared = 'mcp_servers' in config;
+            const servers = await prepareMcp('codex', object(config.mcp_servers), mcpCtx, mcp, tunnels);
+            delete config.mcp_servers;
+            const portable = object(rewritePaths(config, home, remoteHome, files, issues, 'codex:config'));
+            if (Object.keys(servers).length || declared)
+                portable.mcp_servers = servers;
+            files.set('.codex/config.toml', { content: Buffer.from(stringify(portable)), mode: '0600' });
+        }
     }
     // Retain encrypted secret records for later re-use, but stop injecting credentials for removed/skipped servers.
     const ownedSecrets = Object.keys(secrets);
@@ -252,8 +380,13 @@ export async function syncAgentConfig(ctx, ws) {
                 await ws.secrets.set(names);
         }
     }
-    const applied = await applyConfigFiles(cell, remoteHome, files, partial.files, trust, issues, ctx.signal, true, savePartial);
+    // The payload staged above is in the VM already; the second pass checks only what changed since.
+    const applied = await applyConfigFiles(cell, remoteHome, files, partial.files, trust, issues, ctx.signal, true, savePartial, new Set(Object.keys(staged.files))).finally(flushPartial);
     applied.copied.unshift(...staged.copied);
+    // Plugins are installed by the VM's Claude Code from their marketplaces, once per changed plan.
+    const pluginsHash = hasPlugins ? digest(JSON.stringify(plugins)) : undefined;
+    if (pluginsHash && !(trust && pluginsHash === previous?.plugins_hash))
+        await installPlugins(cell, plugins, issues, ctx.signal);
     // L2 owns oauthAccount and credentials. Patch just mcpServers under a revision check; preserve every other field.
     if (Object.keys(claudeMcp).length || previous?.claude_mcp.length) {
         const path = `${remoteHome}/.claude.json`;
@@ -296,7 +429,8 @@ export async function syncAgentConfig(ctx, ws) {
         store.update(doc => { const all = object(doc.agent_config); all[key(ctx, ws.id)] = partial; doc.agent_config = all; });
     }
     const manifest = { v: 1, workspace_id: ws.id, workspace_key: ws.key, api_url: ctx.apiUrl, home: remoteHome,
-        sync_state: 'synced', synced_at, files: applied.files, claude_mcp: Object.keys(claudeMcp), claude_mcp_owned: partial.claude_mcp_owned, secrets, skipped: issues, mcp, tunnels };
+        sync_state: 'synced', synced_at, files: applied.files, claude_mcp: Object.keys(claudeMcp), claude_mcp_owned: partial.claude_mcp_owned, secrets, skipped: issues, mcp, tunnels,
+        ...(pluginsHash ? { plugins_hash: pluginsHash } : {}) };
     manifest.remote_hash = digest(JSON.stringify({ files: applied.files, claude_mcp: claudeMcp, mcp, tunnels }));
     if (marker?.workspace_id !== ws.id || marker.manifest_hash !== manifest.remote_hash)
         await cell.files.write(`${remoteHome}/${markerPath}`, JSON.stringify({ workspace_id: ws.id, manifest_hash: manifest.remote_hash }) + '\n', { createParents: true, mode: '0600' });
@@ -311,6 +445,36 @@ export async function syncAgentConfig(ctx, ws) {
     }
     return result;
 }
+/**
+ * Copies the laptop's agent config into a new conversation's VM after its agent started (0.19.0+): the first prompt
+ * never waits for it. From an installed shard it runs as its own detached process (`shard agents config-sync`, its
+ * output in agent-config-sync.log of the config directory), so the command that started the conversation reports the
+ * start at once; without a runtime (tests, an embedding) it runs here and the returned promise settles when it ends.
+ */
+export function syncAgentConfigAfterStart(ctx, ws) {
+    if (ctx.runtime?.script) {
+        try {
+            mkdirSync(ctx.store.dir, { recursive: true, mode: 0o700 });
+            const log = openSync(join(ctx.store.dir, 'agent-config-sync.log'), 'a', 0o600);
+            try {
+                const child = spawn(ctx.runtime.node, [ctx.runtime.script, 'agents', 'config-sync', ws.id], {
+                    detached: true, stdio: ['ignore', log, log],
+                    env: { ...process.env, ...ctx.io.env, SHARDFLUX_CONFIG_DIR: ctx.store.dir, SHARDFLUX_API_URL: ctx.apiUrl, SHARDFLUX_NO_UPDATE_CHECK: '1' }
+                });
+                child.on('error', () => undefined);
+                child.unref();
+            }
+            finally {
+                closeSync(log);
+            }
+            return undefined;
+        }
+        catch { /* runs in this process below */ }
+    }
+    return syncAgentConfig(ctx, ws).then(() => undefined, (error) => {
+        ctx.io.stderr.write(`Agent config not copied to ${ws.key}: ${error instanceof Error ? error.message : String(error)}\n`);
+    });
+}
 /** Tunnels are owned by the attachment, and close even if the terminal fails or the user detaches. */
 export async function startAgentConfigTunnels(ctx, ws) {
     const owned = [];
@@ -336,6 +500,16 @@ export async function startAgentConfigTunnels(ctx, ws) {
     }
 }
 export const AGENT_CONFIG_HANDLERS = {
+    /** The detached copy syncAgentConfigAfterStart starts; one line per run in agent-config-sync.log. */
+    async 'agents config-sync'(ctx, _values, [id]) {
+        const ws = await ctx.cloud().workspaces.get(id);
+        const started = Date.now();
+        const result = await syncAgentConfig({ ...ctx, json: true }, ws);
+        ctx.io.stderr.write(`${new Date().toISOString()} ${ws.key}: ${result.copied.length} copied, ${result.removed.length} removed, ${result.skipped.length} skipped in ${Date.now() - started} ms\n`);
+        for (const line of configIssueLines(result.skipped))
+            ctx.io.stderr.write(`  ${line}\n`);
+        return 0;
+    },
     'agents config status'(ctx, values) {
         const workspace = typeof values.workspace === 'string' ? values.workspace : undefined;
         const manifests = Object.values(configManifests(ctx)).filter(m => m.api_url === ctx.apiUrl && (!workspace || m.workspace_id === workspace || m.workspace_key === workspace));

package/dist/agent-repository.d.ts

@@ -1,6 +1,5 @@
 import type { Workspace } from '@shardflux/sdk';
 import type { Ctx } from './commands.js';
-import { CodedError } from './errors.js';
 import type { SyncCell } from './project-sync-transfer.js';
 export declare function projectWorkspacePath(project: {
     slug: string;
@@ -8,20 +7,51 @@ export declare function projectWorkspacePath(project: {
 /** New workspaces label this path explicitly; custom remote paths remain available to Git callers. */
 export declare function workspaceRepositoryPath(ws: Pick<Workspace, 'labels' | 'key'>): string;
 export declare function needsGitSeed(ctx: Ctx, ws: Workspace): boolean;
-/** One history seed for C5 and C11. Bundles use the bounded files path, without a Git helper or second connection. */
+/**
+ * The checks a start can fail on, run on this computer before a VM is allocated (0.19.0+). A project's size, file
+ * count or history never refuses a start; only a folder inside another repository does.
+ */
+export declare function preflightProjectSeed(folder: string, signal?: AbortSignal): Promise<void>;
+/**
+ * One seed for every start (C5, C11). A Git project's files come from Git in the VM: HEAD is checked out there and only
+ * what differs from HEAD on this computer (changes, untracked files, deletions, .env files) is copied (0.19.0+). Its
+ * size, file count and history length do not change what is sent.
+ */
 export declare function seedAgentRepository(ctx: Ctx, ws: Workspace, folder: string, options?: {
     root?: string;
     populate?: boolean;
     initialFiles?: readonly string[];
     onInitialFiles?: () => void;
 }): Promise<void>;
-/** History above this goes through the project's origin instead of the bounded files path. */
-export declare const HISTORY_BUNDLE_LIMIT: number;
-/** A history the first copy cannot carry (repository_too_large, 0.13.3+): the facts, and the next step as the hint. */
-export declare function tooLarge(message: string, hint: string, branch: string, origin: string | null): CodedError;
+/**
+ * Above this (an estimate: the repository's packed and loose objects) the workspace fetches the history from origin as a
+ * blobless partial clone, and receives only the commits origin lacks (0.19.0+). Below it, one small bundle is faster.
+ */
+export declare const ORIGIN_FIRST_BYTES: number;
+/** The repository's object store size, an upper bound of any one branch's history bundle. Reads sizes only. */
+export declare function historyEstimate(folder: string, signal?: AbortSignal): Promise<number>;
+export declare const FETCH_ORIGIN: string;
+export declare const BACKFILL: string;
+export declare const CHECKOUT_HEAD: string;
 /**
  * Imports the checked-out branch's history into an empty workspace repository. Only HEAD, its branch and that branch's
- * upstream are bundled: other branches, worktrees and stashes stay on this computer. When that is still above `limit`,
- * the workspace fetches `origin` itself (with its own Git credentials) and receives only the commits origin lacks.
+ * upstream are sent: other branches, worktrees and stashes stay on this computer. A history above `originFirst` comes
+ * from origin as a blobless partial clone (the workspace's own Git credentials), plus a bundle of the commits origin
+ * lacks. Without a reachable origin the whole bundle is streamed in chunks: no history size refuses (0.19.0+).
+ */
+export declare function importProjectHistory(cell: SyncCell, folder: string, root: string, head: string, branch: string, origin: string | null, signal?: AbortSignal, originFirst?: number, report?: (message: string) => void): Promise<{
+    partial: string | null;
+}>;
+/**
+ * What differs between HEAD and this computer's working tree, from Git's own status (0.19.0+): changed, added and
+ * untracked files Git does not ignore, the .env files we always carry, Git LFS files (their content lives outside Git),
+ * and deletions. Ignored files, nested repositories and submodule contents stay out.
  */
-export declare function importProjectHistory(cell: SyncCell, folder: string, root: string, head: string, branch: string, origin: string | null, signal?: AbortSignal, limit?: number): Promise<void>;
+export declare function localChanges(folder: string, signal?: AbortSignal): Promise<{
+    copy: string[];
+    remove: string[];
+    skipped: {
+        path: string;
+        reason: string;
+    }[];
+}>;