@shardflux/cli 0.20.0 → 0.23.0

package/dist/project-preparation.d.ts

@@ -0,0 +1,62 @@
+import type { Ctx, Handler } from './commands.js';
+import type { PreparedTransfer } from './prepared-repository.js';
+import { CodedError } from './errors.js';
+export interface SelectedProject {
+    api_url: string;
+    folder: string;
+    enabled: boolean;
+    state: 'queued' | 'syncing' | 'setup' | 'ready' | 'paused' | 'error';
+    revision?: string;
+    deps_hash?: string;
+    workspace_id?: string;
+    project_id?: string;
+    /** What the last preparation saw: HEAD, the index, and each changed file's size and times (a change detector only). */
+    observed?: {
+        head: string;
+        index: string;
+        files: Record<string, string>;
+    };
+    updated_at?: string;
+    prepared_at?: string;
+    error?: string;
+    transfer?: PreparedTransfer;
+    /** The project's setup failed as it stands (no check to run, a failing install): tried again once it changes. */
+    blocked?: boolean;
+    /** Preparation VMs this revision's attempts deleted: the next open is a new one, never the deleted one again. */
+    attempt?: number;
+}
+/** The guest's setup state (`sf-agent template --json`): its steps, each failed one with the guest's error. */
+export interface SetupStatus {
+    state?: string;
+    tasks?: {
+        name: string;
+        state: string;
+        error?: {
+            code?: string;
+            message: string;
+        };
+    }[];
+}
+export declare function setupFailure(status: SetupStatus): CodedError;
+/** New content past this, or a dependency change, makes a quiet project worth preparing again. */
+export declare const PREPARE_AGAIN_BYTES: number;
+/** Quiet this long after the last edit before preparing again. */
+export declare const QUIET_MS = 30000;
+export declare const selectionId: (api: string, folder: string) => string;
+export declare function selectedProjects(ctx: Pick<Ctx, 'store' | 'apiUrl'>): SelectedProject[];
+export declare function selectProject(ctx: Pick<Ctx, 'store' | 'apiUrl'>, path: string): SelectedProject;
+/** HEAD, the index and each changed file's metadata: cheap (no hashing), a detector of change, never of content. */
+export declare function observeProject(folder: string, signal?: AbortSignal): Promise<NonNullable<SelectedProject['observed']>>;
+/** Bytes of new or changed content since `before` (sizes of files whose metadata moved), and whether Git state moved. */
+export declare function changedSince(before: SelectedProject['observed'], now: NonNullable<SelectedProject['observed']>): {
+    bytes: number;
+    git: boolean;
+};
+/** One selected project, one short-lived VM. Never touches a running chat's worktree. */
+export declare function prepareSelectedProject(ctx: Ctx, selected: SelectedProject): Promise<void>;
+/**
+ * Watches the selected projects only. Prepares a new selection at once; after edits, waits until the project is quiet
+ * and prepares again only when that would make a start faster. Offline failures retry with backoff.
+ */
+export declare function runProjectPreparation(ctx: Ctx): Promise<void>;
+export declare const PROJECT_PREPARATION_HANDLERS: Record<string, Handler>;

package/dist/project-preparation.js

@@ -0,0 +1,316 @@
+/**
+ * Selected projects, prepared ahead of a start (0.22.0+). The user picks them (onboarding, settings, or
+ * `shard projects sync add`); nothing else is scanned or sent. For each, a short-lived preparation VM puts the
+ * project's current revision into the project cache, and when its dependencies changed, installs them and saves the
+ * project template, so a new chat sends only what changed since and boots with its dependencies installed.
+ *
+ * Preparation follows edits without chasing them: once a project has been quiet for a while it is prepared again
+ * when the change would slow a start (new content past a threshold, or a dependency change), never for a few lines
+ * a start sends in milliseconds anyway. No VM stays up: each preparation deletes its own.
+ */
+import { createHash } from 'node:crypto';
+import { watch } from 'node:fs';
+import { lstat } from 'node:fs/promises';
+import { setTimeout as delay } from 'node:timers/promises';
+import { join, resolve } from 'node:path';
+import { ShardfluxApiError } from '@shardflux/sdk';
+import { out } from "./commands.js";
+import { AgentStateStore } from "./agent-state.js";
+import { localConversations } from "./conversations.js";
+import { projectIdentity } from "./project-identity.js";
+import { localChanges, preflightProjectSeed } from "./agent-repository.js";
+import { projectGit } from "./project-sync-manifest.js";
+import { inspectWorktree, pauseReason, twinSeed, worktreeId } from "./worktree-twin.js";
+import { applyPreparedSnapshot, capturePreparedSnapshot, preparedCachePath, preparedGitConfig, pruneLocalPrepared, prunePreparedCache, releaseLocalSnapshot, transferPreparedSnapshot } from "./prepared-repository.js";
+import { withTargetLock } from "./target-lock.js";
+import { CodedError, UsageError } from "./errors.js";
+import { dependencyHash } from "./project-template-setup.js";
+/**
+ * A setup that ran and failed: the same files fail again, so it waits for a change instead of a timer. Reported as
+ * `project_setup_failed` with the failed step and its own message (0.23.0+; before, `internal_error`).
+ */
+class SetupFailed extends CodedError {
+}
+export function setupFailure(status) {
+    const step = status.tasks?.find(t => t.state === 'failed');
+    const message = step ? `Project setup failed at ${step.name}: ${step.error?.message ?? 'the step failed'}` : 'Project setup failed.';
+    // A step setup could not work out (a missing lockfile) or a command that failed; the repository's own command for the
+    // step is the other way forward.
+    const first = step?.error?.code === 'setup_detection_unresolved' ? 'commit what the message names' : 'fix the cause in the repository and commit';
+    const fix = `${first}${step ? `, or set run for ${step.name} under steps in .shardflux/setup.yaml` : ''}; the project is prepared again after the change`;
+    return new SetupFailed('project_setup_failed', message, fix, step ? { step: step.name, ...(step.error?.code ? { error_code: step.error.code } : {}) } : undefined);
+}
+/** New content past this, or a dependency change, makes a quiet project worth preparing again. */
+export const PREPARE_AGAIN_BYTES = 8 << 20;
+/** Quiet this long after the last edit before preparing again. */
+export const QUIET_MS = 30_000;
+export const selectionId = (api, folder) => createHash('sha256').update(api).update('\0').update(folder).digest('hex');
+export function selectedProjects(ctx) {
+    return Object.values(new AgentStateStore(ctx.store.dir).read().prepared_projects ?? {}).filter(p => p.api_url === ctx.apiUrl);
+}
+function patch(ctx, folder, update) {
+    new AgentStateStore(ctx.store.dir).update(doc => {
+        const selections = (doc.prepared_projects ?? {}), id = selectionId(ctx.apiUrl, folder), current = selections[id];
+        if (current)
+            selections[id] = { ...current, ...update, ...(!current.enabled && update.enabled === undefined ? { state: 'paused' } : {}), updated_at: new Date().toISOString() };
+        doc.prepared_projects = selections;
+    });
+}
+export function selectProject(ctx, path) {
+    const { folder } = projectIdentity(path), id = selectionId(ctx.apiUrl, folder);
+    new AgentStateStore(ctx.store.dir).update(doc => {
+        const selections = (doc.prepared_projects ?? {});
+        selections[id] = { ...selections[id], api_url: ctx.apiUrl, folder, enabled: true, state: 'queued', error: undefined, blocked: undefined };
+        doc.prepared_projects = selections;
+    });
+    return selectedProjects(ctx).find(p => p.folder === folder);
+}
+/** HEAD, the index and each changed file's metadata: cheap (no hashing), a detector of change, never of content. */
+export async function observeProject(folder, signal) {
+    const head = (await projectGit(folder, ['rev-parse', 'HEAD'], signal)).trim();
+    const index = createHash('sha256').update(await projectGit(folder, ['ls-files', '--stage', '-z'], signal)).digest('hex');
+    const files = {};
+    for (const path of (await localChanges(folder, signal)).copy) {
+        try {
+            const st = await lstat(join(folder, path));
+            files[path] = `${st.size}:${st.mtimeMs}:${st.ctimeMs}:${st.ino}:${st.mode}`;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    return { head, index, files };
+}
+/** Bytes of new or changed content since `before` (sizes of files whose metadata moved), and whether Git state moved. */
+export function changedSince(before, now) {
+    let bytes = 0;
+    for (const [path, meta] of Object.entries(now.files))
+        if (before?.files[path] !== meta)
+            bytes += Number(meta.split(':')[0]) || 0;
+    return { bytes, git: !before || before.head !== now.head || before.index !== now.index || Object.keys(before.files).some(path => !(path in now.files)) };
+}
+/** One selected project, one short-lived VM. Never touches a running chat's worktree. */
+export async function prepareSelectedProject(ctx, selected) {
+    await withTargetLock(join(ctx.store.dir, 'project-prepare-locks', selectionId(ctx.apiUrl, selected.folder)), async () => {
+        const current = selectedProjects(ctx).find(p => p.folder === selected.folder);
+        if (!current?.enabled)
+            return;
+        const cancel = new AbortController();
+        const watcher = watch(ctx.store.dir, (_event, name) => {
+            if (name?.toString() === 'agents.json' && !selectedProjects(ctx).find(p => p.folder === current.folder)?.enabled)
+                cancel.abort(new Error('Project preparation paused or removed.'));
+        });
+        ctx = { ...ctx, signal: AbortSignal.any([ctx.signal, cancel.signal]) };
+        let owned, setupStarted = false, revision, observed;
+        const identity = projectIdentity(current.folder), remote = identity.remote ?? `file://${identity.folder}`;
+        try {
+            const info = await inspectWorktree(identity.folder);
+            const paused = pauseReason(info);
+            if (paused)
+                throw new UsageError(paused);
+            await preflightProjectSeed(identity.folder, ctx.signal);
+            if (!info.head)
+                throw new UsageError('Commit this project once before preparing it.');
+            observed = await observeProject(identity.folder, ctx.signal);
+            const seed = await twinSeed(ctx.store.dir, identity.folder, info.head, ctx.store.profile(ctx.apiUrl).project_id);
+            const snapshot = await capturePreparedSnapshot(ctx.store.dir, identity.folder, seed, identity.remote, ctx.signal);
+            revision = snapshot.revision;
+            const deps = snapshot.manifest.deps_hash;
+            patch(ctx, identity.folder, { state: 'syncing', error: undefined });
+            const opened = await ctx.cloud().projectTemplates.prepare({ repoRemote: remote, depsHash: deps, worktreeId: worktreeId(identity.folder),
+                projectId: ctx.store.profile(ctx.apiUrl).project_id }, { signal: ctx.signal, idempotencyKey: `prepare-${snapshot.revision}-${current.attempt ?? 0}` });
+            owned = opened.workspace_id;
+            patch(ctx, identity.folder, { workspace_id: owned });
+            const ws = await ctx.cloud().workspaces.get(owned);
+            if (!ws.ready)
+                await ws.wake({ timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
+            if (ws.labels.shard_preparation !== 'true')
+                throw new Error('The API did not bind a preparation workspace.');
+            const cell = ws.cell(), cache = preparedCachePath(remote);
+            const pin = `prepare-${selectionId(ctx.apiUrl, identity.folder).slice(0, 32)}`;
+            const transfer = await transferPreparedSnapshot(cell, identity.folder, cache, snapshot, { signal: ctx.signal, pin });
+            if (opened.setup_required) {
+                // Dependencies changed: install them in a checkout of this revision and save the project template from it. The
+                // checkout sits where a conversation's worktree does, so a chat from the template starts with them in place.
+                const root = ws.labels.repo_path;
+                if (!root?.startsWith('/home/user/'))
+                    throw new Error('Preparation workspace omitted its repository path.');
+                patch(ctx, identity.folder, { state: 'setup' });
+                await applyPreparedSnapshot(cell, cache, snapshot.revision, root, `shard/prepare-${worktreeId(identity.folder)}`, { signal: ctx.signal, preparation: true,
+                    replacePreparation: true, dissociate: 'now', git: await preparedGitConfig(identity.folder, snapshot.manifest, ctx.signal), releasePin: pin });
+                const setup = await cell.exec.run(['sf-agent', 'setup-start', '--deps-hash', deps], { cwd: root, timeoutMs: 30_000, maxOutputBytes: 8192, signal: ctx.signal });
+                if (setup.exitCode !== 0)
+                    throw new Error(`Project setup could not start: ${setup.stderr.trim()}`);
+                setupStarted = true;
+                // Ready means the dependency-keyed template is published, not just that an install command exited.
+                for (const deadline = Date.now() + 30 * 60_000;;) {
+                    ctx.signal.throwIfAborted();
+                    try {
+                        if ((await ctx.cloud().projectTemplates.get(remote, { signal: ctx.signal })).deps_hash === deps)
+                            break;
+                    }
+                    catch (error) {
+                        if (!(error instanceof ShardfluxApiError && error.status === 404))
+                            throw error;
+                    }
+                    const status = await cell.exec.run(['sf-agent', 'template', '--json'], { cwd: root, timeoutMs: 30_000, maxOutputBytes: 32768, signal: ctx.signal });
+                    if (status.exitCode !== 0)
+                        throw new Error(`Project setup status failed: ${status.stderr.trim()}`);
+                    const state = JSON.parse(status.stdout);
+                    if (state.state === 'failed')
+                        throw setupFailure(state);
+                    if (Date.now() > deadline)
+                        throw new Error('The project template is still being saved; the next preparation picks it up.');
+                    await delay(5000, undefined, { signal: ctx.signal });
+                }
+            }
+            await prunePreparedCache(cell, cache, ctx.signal).catch(() => undefined);
+            patch(ctx, identity.folder, { state: 'ready', revision: snapshot.revision, deps_hash: deps, observed, transfer, project_id: ws.data.project_id,
+                prepared_at: new Date().toISOString(), error: undefined, blocked: undefined, attempt: undefined });
+            await ctx.cloud().workspaces.delete(owned);
+            owned = undefined;
+            patch(ctx, identity.folder, { workspace_id: undefined });
+        }
+        catch (error) {
+            // An interrupted setup keeps its VM: the same keyed open resumes its install. A failed one, and anything else,
+            // leaves nothing behind.
+            const failed = error instanceof SetupFailed;
+            if (owned && (!setupStarted || failed)) {
+                await ctx.cloud().workspaces.delete(owned).catch(() => undefined);
+                patch(ctx, current.folder, { workspace_id: undefined, attempt: (current.attempt ?? 0) + 1 });
+            }
+            patch(ctx, current.folder, { state: ctx.signal.aborted ? 'queued' : 'error', error: (error instanceof Error ? error.message : String(error)).slice(0, 2000),
+                ...(failed ? { blocked: true, observed } : {}) });
+            throw error;
+        }
+        finally {
+            watcher.close();
+            if (revision)
+                await releaseLocalSnapshot(identity.folder, revision);
+            await pruneLocalPrepared(ctx.store.dir).catch(() => undefined);
+        }
+    }, ctx.signal);
+}
+/**
+ * Watches the selected projects only. Prepares a new selection at once; after edits, waits until the project is quiet
+ * and prepares again only when that would make a start faster. Offline failures retry with backoff.
+ */
+export async function runProjectPreparation(ctx) {
+    const watchers = new Map(), changed = new Map(), retry = new Map();
+    try {
+        while (!ctx.signal.aborted) {
+            const projects = selectedProjects(ctx), active = new Set(projects.filter(p => p.enabled).map(p => p.folder));
+            for (const [folder, watcher] of watchers)
+                if (!active.has(folder)) {
+                    watcher.close();
+                    watchers.delete(folder);
+                    changed.delete(folder);
+                }
+            for (const p of projects) {
+                if (!p.enabled)
+                    continue;
+                if (!watchers.has(p.folder)) {
+                    try {
+                        const watcher = watch(p.folder, { recursive: true }, (_event, path) => {
+                            const name = path?.toString() ?? '';
+                            if (name.startsWith('.git/') && !/^\.git\/(?:index|HEAD|refs\/heads\/|packed-refs)$/.test(name))
+                                return;
+                            changed.set(p.folder, Date.now());
+                        });
+                        watcher.on('error', () => { watcher.close(); watchers.delete(p.folder); });
+                        watchers.set(p.folder, watcher);
+                    }
+                    catch { /* the periodic pass below still notices changes */ }
+                }
+                const backoff = retry.get(p.folder);
+                if (backoff && backoff.at > Date.now())
+                    continue;
+                const touched = changed.get(p.folder);
+                if (touched !== undefined && Date.now() - touched < QUIET_MS)
+                    continue;
+                // A setup that failed as the project stands waits for an edit (its files, setup.yaml, a commit), not a timer.
+                if (p.state === 'error' && p.blocked) {
+                    const delta = changedSince(p.observed, await observeProject(p.folder, ctx.signal).catch(() => p.observed));
+                    if (!delta.bytes && !delta.git) {
+                        changed.delete(p.folder);
+                        continue;
+                    }
+                }
+                // A ready project without edits is rechecked every ten minutes (a missed watcher event, a branch switch).
+                if (p.state === 'ready' && touched === undefined && Date.now() - Date.parse(p.updated_at ?? '1970-01-01') < 600_000)
+                    continue;
+                try {
+                    if (p.state === 'ready') {
+                        const now = await observeProject(p.folder, ctx.signal), delta = changedSince(p.observed, now);
+                        const settled = delta.bytes < PREPARE_AGAIN_BYTES && !delta.git;
+                        if (settled) {
+                            patch(ctx, p.folder, {});
+                            changed.delete(p.folder);
+                            continue;
+                        }
+                        // Small edits travel with the start; only a dependency change or bulk content is worth a VM now.
+                        if (delta.bytes < PREPARE_AGAIN_BYTES && dependencyHash(p.folder) === p.deps_hash) {
+                            patch(ctx, p.folder, {});
+                            changed.delete(p.folder);
+                            continue;
+                        }
+                    }
+                    const before = changed.get(p.folder);
+                    await prepareSelectedProject(ctx, p);
+                    retry.delete(p.folder);
+                    if (changed.get(p.folder) === before)
+                        changed.delete(p.folder);
+                }
+                catch (error) {
+                    if (ctx.signal.aborted)
+                        break;
+                    if (error instanceof SetupFailed) {
+                        retry.delete(p.folder);
+                        continue;
+                    }
+                    const wait = Math.min((backoff?.wait ?? 30_000) * 2, 30 * 60_000);
+                    retry.set(p.folder, { at: Date.now() + wait, wait });
+                }
+            }
+            await delay(2000, undefined, { signal: ctx.signal }).catch(() => undefined);
+        }
+    }
+    finally {
+        for (const watcher of watchers.values())
+            watcher.close();
+    }
+}
+export const PROJECT_PREPARATION_HANDLERS = {
+    'projects sync list'(ctx) {
+        const selected = selectedProjects(ctx), known = [...new Set(Object.values(localConversations(ctx)).map(r => r.folder))];
+        out(ctx, selected.map(p => `${p.folder}\t${p.state}${p.error ? `\t${p.error}` : ''}`).join('\n') + (selected.length ? '\n' : ''), { data: selected, known });
+        return Promise.resolve(0);
+    },
+    async 'projects sync add'(ctx, values, [path]) {
+        if (!path)
+            throw new UsageError('Choose a local project path.');
+        const p = selectProject(ctx, path);
+        if (values.wait === true)
+            await prepareSelectedProject(ctx, p);
+        out(ctx, `Selected ${p.folder}; it is prepared in the background.\n`, { project: selectedProjects(ctx).find(s => s.folder === p.folder) });
+        return 0;
+    },
+    'projects sync pause'(ctx, _values, [path]) {
+        if (!path)
+            throw new UsageError('Choose a selected project path.');
+        const folder = selectedProjects(ctx).find(p => p.folder === resolve(path))?.folder ?? projectIdentity(path).folder;
+        patch(ctx, folder, { enabled: false, state: 'paused' });
+        out(ctx, `Paused ${folder}.\n`, { project: selectedProjects(ctx).find(p => p.folder === folder) });
+        return Promise.resolve(0);
+    },
+    'projects sync remove'(ctx, _values, [path]) {
+        if (!path)
+            throw new UsageError('Choose a selected project path.');
+        const folder = selectedProjects(ctx).find(p => p.folder === resolve(path))?.folder ?? projectIdentity(path).folder;
+        new AgentStateStore(ctx.store.dir).update(doc => { const selections = (doc.prepared_projects ?? {}); delete selections[selectionId(ctx.apiUrl, folder)]; doc.prepared_projects = selections; });
+        out(ctx, `Removed ${folder} from background preparation.\n`, { removed: true, folder });
+        return Promise.resolve(0);
+    },
+    async 'projects sync run'(ctx) { await runProjectPreparation(ctx); return 0; },
+};

package/dist/project-sync-manifest.d.ts

@@ -8,6 +8,10 @@ export interface SyncChange {
 }
 export declare function validSyncPath(path: string): boolean;
 export declare function excludedSyncPath(path: string): boolean;
+/**
+ * A symbolic link's identity is its target: its own mode is not content (Linux reports 0777, macOS the mode it was
+ * made with, 0755), so a link that is the same on both sides is never a change or a conflict (0.21.1+).
+ */
 export declare function contentIdentity(entry?: FileManifestEntry): string;
 /** Deletions have an observation timestamp: a detached filesystem has no deletion clock. Ties favor the laptop. */
 export declare function diffManifests(local: Manifest, remote: Manifest, common: Common, observedAt?: number, blocked?: Set<string>): SyncChange[];

package/dist/project-sync-manifest.js

@@ -8,8 +8,12 @@ export function validSyncPath(path) {
     return path.length > 0 && Buffer.byteLength(path) <= 4096 && !path.includes('\0') && !path.includes('\\') && !path.startsWith('/') && !path.split('/').some((part) => !part || part === '.' || part === '..' || part === '.git' || part === '.shard');
 }
 export function excludedSyncPath(path) { return path.split('/').some((part) => part === '.git' || part === '.shard' || part.includes('.shard-tmp-')); }
+/**
+ * A symbolic link's identity is its target: its own mode is not content (Linux reports 0777, macOS the mode it was
+ * made with, 0755), so a link that is the same on both sides is never a change or a conflict (0.21.1+).
+ */
 export function contentIdentity(entry) {
-    return entry ? `${entry.sha256}:${entry.mode}:${entry.symlink ? 'link' : 'file'}` : 'absent';
+    return entry ? `${entry.sha256}:${entry.symlink ? 0o777 : entry.mode}:${entry.symlink ? 'link' : 'file'}` : 'absent';
 }
 /** Deletions have an observation timestamp: a detached filesystem has no deletion clock. Ties favor the laptop. */
 export function diffManifests(local, remote, common, observedAt = Date.now(), blocked = new Set()) {

package/dist/project-sync-transfer.js

@@ -45,7 +45,7 @@ export async function readLocalSyncFile(folder, entry) {
             await file.close();
         }
     }
-    if ((st.mode & 0o777) !== entry.mode)
+    if (!entry.symlink && (st.mode & 0o777) !== entry.mode)
         throw new Error(`${entry.path} mode changed during sync`);
     verifySyncBytes(entry, data);
     return { entry, data };

package/dist/project-sync.d.ts

@@ -1,7 +1,7 @@
 import type { Workspace } from '@shardflux/sdk';
 import type { Ctx } from './commands.js';
 import type { projectIdentity } from './project-identity.js';
-import type { Common } from './project-sync-manifest.js';
+import type { Common, LocalHashCache } from './project-sync-manifest.js';
 import type { SyncCell } from './project-sync-transfer.js';
 export interface ProjectSyncConflict {
     path: string;
@@ -19,6 +19,8 @@ export interface ProjectSync {
     root: string;
     conflicts(): readonly ProjectSyncConflict[];
     reconcile(): Promise<void>;
+    /** The last reconcile found both sides equal, so its baseline is current (0.21.1+). */
+    settled(): boolean;
     stop(): Promise<void>;
 }
 export { projectWorkspacePath } from './agent-repository.js';
@@ -34,9 +36,25 @@ export declare function projectReconciler(options: {
     save: (state: ProjectSyncState) => void;
     report: (message: string) => void;
     signal?: AbortSignal;
-}): () => Promise<void>;
-export declare function startProjectSync(ctx: Ctx, ws: Workspace, project: ReturnType<typeof projectIdentity>, options?: {
+    vmBaseline?: boolean;
+    cache?: LocalHashCache;
+    inFlight?: () => Iterable<string>;
+}): (() => Promise<void>) & {
+    settled(): boolean;
+};
+export type ProjectSyncBoundary = Pick<ProjectSync, 'root' | 'conflicts' | 'reconcile' | 'settled'>;
+export interface ProjectSyncOptions {
     root?: string;
     agent?: string;
     seed?: boolean;
-}): Promise<ProjectSync>;
+    stateKey?: string;
+    /** The VM has run nothing since this checkout seeded it: a boundary with no saved state starts from its files (0.21.1+). */
+    vmBaseline?: boolean;
+    /** This computer's file hashes, filled ahead of the first reconcile (localManifest with the same map, 0.21.1+). */
+    cache?: LocalHashCache;
+    /** Paths another transfer is still bringing to the VM (a prepared start's large media, 0.22.0+): left alone until then. */
+    inFlight?: () => Iterable<string>;
+}
+/** Editors reconcile between turns without a watcher keeping an idle VM active. */
+export declare function projectSyncBoundary(ctx: Ctx, ws: Workspace, project: ReturnType<typeof projectIdentity>, options?: ProjectSyncOptions): Promise<ProjectSyncBoundary>;
+export declare function startProjectSync(ctx: Ctx, ws: Workspace, project: ReturnType<typeof projectIdentity>, options?: ProjectSyncOptions): Promise<ProjectSync>;

package/dist/project-sync.js

@@ -15,9 +15,10 @@ export function projectSyncConflicts(dir, key) {
 /** Core reconciler used by the attach module and by the real Linux harness. */
 export function projectReconciler(options) {
     const { folder, root, cell, agent, state, save, report, signal } = options;
+    let settled = false, vmBaseline = options.vmBaseline === true;
     if (!/^[a-z0-9][a-z0-9._-]{0,63}$/.test(agent))
         throw new Error('invalid conflict agent name');
-    const cache = new Map();
+    const cache = options.cache ?? new Map();
     let serial = Promise.resolve();
     const run = async () => {
         signal?.throwIfAborted();
@@ -35,7 +36,21 @@ export function projectReconciler(options) {
                 report(`Project sync skipped ${side} ${skip.path}: ${skip.reason}`);
             }
         }
-        const changes = diffManifests(local, remote, state.common, Date.now(), blocked);
+        // Files another transfer is still bringing to the VM: this pass leaves them alone (a later one sees them landed).
+        for (const path of options.inFlight?.() ?? [])
+            blocked.add(path);
+        // Until a pass completes, a VM that has run nothing since this checkout seeded it holds the baseline of every file
+        // both sides have: an edit made here before the first pass is this computer's change, not a conflict (0.21.1+).
+        let common = state.common;
+        if (vmBaseline) {
+            common = Object.assign(Object.create(null), state.common);
+            for (const path of Object.keys(remote))
+                if (local[path] && !Object.hasOwn(common, path))
+                    common[path] = contentIdentity(remote[path]);
+        }
+        const changes = diffManifests(local, remote, common, Date.now(), blocked);
+        // A pass that moved files advances the baseline only for paths it already had: the next pass settles the rest.
+        settled = changes.length === 0;
         // Laptop-side deletions run before writes and VM-side deletions before uploads, so a directory can become a file.
         const pushes = [], removals = [];
         const expected = Object.create(null);
@@ -105,10 +120,12 @@ export function projectReconciler(options) {
             }
         }
         save(state);
+        vmBaseline = false;
     };
-    return () => { const next = serial.then(run); serial = next.catch(() => undefined); return next; };
+    return Object.assign(() => { settled = false; const next = serial.then(run); serial = next.catch(() => undefined); return next; }, { settled: () => settled });
 }
-export async function startProjectSync(ctx, ws, project, options = {}) {
+/** Editors reconcile between turns without a watcher keeping an idle VM active. */
+export async function projectSyncBoundary(ctx, ws, project, options = {}) {
     if (!options.root && ws.labels.agent && ws.labels.agent !== 'main')
         throw new Error('two-way project sync requires a conversation worktree');
     const root = options.root ?? projectWorkspacePath(project);
@@ -117,9 +134,10 @@ export async function startProjectSync(ctx, ws, project, options = {}) {
     if (options.seed !== false)
         await seedAgentRepository(ctx, ws, project.folder, { root });
     const store = new AgentStateStore(ctx.store.dir);
-    const key = `${ws.id}:${project.folder}`;
+    const key = options.stateKey ?? `${ws.id}:${project.folder}`;
     const states = store.read().project_sync;
-    const state = states?.[key] ?? { common: Object.create(null), conflicts: [] };
+    const stored = states?.[key];
+    const state = stored ?? { common: Object.create(null), conflicts: [] };
     const save = (value) => {
         store.update(doc => {
             const current = (doc.project_sync ?? {});
@@ -128,7 +146,15 @@ export async function startProjectSync(ctx, ws, project, options = {}) {
         });
     };
     const report = (message) => { ctx.io.stderr.write(`${message}\n`); };
-    const reconcile = projectReconciler({ folder: project.folder, root, agent: options.agent ?? ws.labels.agent ?? 'main', cell, state, save, report, signal: ctx.signal });
+    const reconcile = projectReconciler({ folder: project.folder, root, agent: options.agent ?? ws.labels.agent ?? 'main', cell, state, save, report, signal: ctx.signal,
+        vmBaseline: options.vmBaseline === true && !stored, ...(options.cache ? { cache: options.cache } : {}), ...(options.inFlight ? { inFlight: options.inFlight } : {}) });
+    return { root, conflicts: () => state.conflicts.slice(), reconcile, settled: () => reconcile.settled() };
+}
+export async function startProjectSync(ctx, ws, project, options = {}) {
+    const boundary = await projectSyncBoundary(ctx, ws, project, options);
+    const { root, reconcile } = boundary;
+    const cell = ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs });
+    const report = (message) => { ctx.io.stderr.write(`${message}\n`); };
     const abort = new AbortController();
     const signal = ctx.signal ? AbortSignal.any([ctx.signal, abort.signal]) : abort.signal;
     let stopped = false, dirty = false;
@@ -219,7 +245,7 @@ export async function startProjectSync(ctx, ws, project, options = {}) {
         throw error;
     }
     return {
-        root, conflicts: () => state.conflicts.slice(), reconcile,
+        ...boundary,
         async stop() {
             if (stopped)
                 return;

package/dist/project-template-setup.d.ts

@@ -1,4 +1,4 @@
-import type { Workspace } from '@shardflux/sdk';
+import type { CellClient, Workspace } from '@shardflux/sdk';
 import type { Ctx, Handler } from './commands.js';
 import { projectIdentity } from './project-identity.js';
 export declare function dependencyHash(folder: string): string;
@@ -14,4 +14,36 @@ export declare function prepareProjectTemplate(ctx: Ctx, project: ReturnType<typ
         shard_repo_remote: string;
     };
 }>;
+/** A new conversation's project setup: the hash its worktree is set up with, once its VM carries the setup labels. */
+export interface ConversationSetup {
+    hash: string;
+    labelled: Promise<void>;
+}
+/**
+ * Whether a new conversation sets its repository up (0.21.1+): when the project has no template for the repository's
+ * current dependency hash. Read as the conversation starts, so the hash is of the files it is seeded with; the API
+ * read runs while its VM starts. Never fails the start: an unreadable answer is reported and the conversation runs
+ * without setup.
+ */
+export declare function readConversationSetup(ctx: Ctx, project: ReturnType<typeof projectIdentity>): Promise<{
+    depsHash: string;
+    labels: Record<string, string>;
+} | undefined>;
+/**
+ * The conversation's VM gets the labels a project workspace has, with its worktree as the repository, so the setup
+ * that passes there saves the project template the next conversation starts from. Runs beside the agent's start; the
+ * setup itself is queued once it is done. A failed label write is reported: setup still prepares this conversation.
+ */
+export declare function labelConversationSetup(ctx: Ctx, ws: Workspace, worktree: string, setup: {
+    depsHash: string;
+    labels: Record<string, string>;
+} | undefined): ConversationSetup | undefined;
+/**
+ * The hash a new conversation's worktree is set up with, recorded in its VM before the seed. Its guest starts the agent
+ * as soon as the repository appears, and with this record starts it with the setup's context and toolchains on PATH
+ * (services/guest-agent conversation_runtime.go setupIntent; a guest without it ignores the record).
+ */
+export declare function recordSetupIntent(cell: Pick<CellClient, 'exec'>, c: {
+    id: string;
+}, depsHash: string, signal?: AbortSignal): Promise<void>;
 export declare const PROJECT_TEMPLATE_HANDLERS: Record<string, Handler>;