@shardflux/cli 0.20.0 → 0.22.0

package/dist/agent-repository.js

@@ -54,13 +54,12 @@ export async function seedAgentRepository(ctx, ws, folder, options = {}) {
     const state = new AgentStateStore(ctx.store.dir);
     state.update(doc => { const seeds = (doc.git_seeding ?? {}); seeds[ws.id] = { api_url: ctx.apiUrl, folder: project.folder }; doc.git_seeding = seeds; });
     const cell = ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs });
-    await cell.files.mkdir(root, { parents: true });
     let initialReady = false;
     const initial = options.onInitialFiles ? { paths: new Set(options.initialFiles ?? []), ready: () => { if (!initialReady) {
             initialReady = true;
             options.onInitialFiles();
         } } } : undefined;
-    await initializeProjectGit(cell, project.folder, root, ctx.signal, options.populate, retry, message => { ctx.io.stderr.write(`${message}\n`); }, initial);
+    await initializeProjectGit(cell, project.folder, root, ctx.signal, options.populate, retry, message => { ctx.io.stderr.write(`${message}\n`); }, initial, options.changes, options.background, options.beforeHistory);
     initial?.ready();
     state.update(doc => { const seeds = (doc.git_seeding ?? {}); delete seeds[ws.id]; doc.git_seeding = seeds; });
 }
@@ -80,6 +79,22 @@ async function optionalGit(folder, args, signal) {
     }
 }
 const tail = (text) => text.trim().split('\n').slice(-3).join(' ').slice(-400);
+/** Another Git process in the VM holds this repository's index or config lock (the agent starting there, its hook). */
+const LOCKED = /\.lock'?: File exists|could not lock config file/;
+/**
+ * A Git step of the seed that writes the workspace repository's index, refs or config: run again, for up to ~5 s,
+ * while another Git process in the VM holds the lock (a conversation's agent starts as soon as its repository appears,
+ * and its own `git status` takes the index lock). Every step passed here is safe to repeat.
+ */
+export async function runGitStep(cell, argv, options, attempts = 50) {
+    for (let attempt = 1;; attempt++) {
+        const result = await cell.exec.run(argv, options);
+        if (result.exitCode === 0 || attempt >= attempts || !LOCKED.test(result.stderr))
+            return result;
+        options.signal?.throwIfAborted();
+        await new Promise(resolve => setTimeout(resolve, 100));
+    }
+}
 /** The repository's object store size, an upper bound of any one branch's history bundle. Reads sizes only. */
 export async function historyEstimate(folder, signal) {
     const counts = new Map((await optionalGit(folder, ['count-objects', '-v'], signal)).split('\n').map(line => line.split(': ')));
@@ -89,18 +104,37 @@ export async function historyEstimate(folder, signal) {
 // every commit and tree. Alongside it, a depth-1 fetch of the same ref brings the tip's files in one pack, moved in
 // beside the history, so the checkout reads them locally instead of asking for each blob. Prints the commit. A failed
 // history fetch leaves a plain repository, so the bundle fallback is not a partial clone of an origin it cannot reach.
+// The VM's own prefetch of this worktree (a guest that starts one when its conversation waits for the seed, coding 53+;
+// $HOME/.cache/shardflux/prefetch/<16 hex of sha256(worktree)>: history/ and tip/ bare repositories, remote, commit)
+// is waited for and its packs adopted (0.21.1+): when its commit is $4 (this computer's upstream), nothing more is
+// fetched; otherwise only what is newer, and the checkout fetches any missing tip files in one request.
 export const FETCH_ORIGIN = [
     'set -eu',
     'git init -q "$1"; git -C "$1" config remote.origin.url "$2"',
     'case "$3" in HEAD) dst=refs/shard-sync/origin ;; *) dst="refs/remotes/origin/${3#refs/heads/}" ;; esac',
-    'tip="$1/.git/shard-sync-tip"; rm -rf "$tip"; git init -q --bare "$tip"',
-    'git -C "$tip" -c core.hooksPath=/dev/null -c credential.interactive=false -c fetch.unpackLimit=1 fetch -q --no-tags --depth=1 "$2" "+$3:refs/tip" >/dev/null 2>&1 &',
-    'job=$!',
+    'key=$(printf %s "$1" | sha256sum 2>/dev/null | cut -c1-16); pre=; have=',
+    'case "$key" in [0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]) pre="${HOME:-/home/user}/.cache/shardflux/prefetch/$key" ;; esac',
+    'if [ -n "$pre" ] && { [ -e "$pre.lock" ] || [ -d "$pre" ]; }; then',
+    '  exec 8>"$pre.lock"; flock -w 30 8 || true',
+    '  if [ -d "$pre/history" ] && [ "$(cat "$pre/remote" 2>/dev/null)" = "$2" ] && have=$(cat "$pre/commit" 2>/dev/null) && [ -n "$have" ]; then',
+    '    for p in "$pre"/history/objects/pack/pack-* "$pre"/tip/objects/pack/pack-*; do if [ -f "$p" ]; then mv "$p" "$1/.git/objects/pack/"; fi; done',
+    '    git -C "$1" config remote.origin.promisor true; git -C "$1" config remote.origin.partialclonefilter blob:none',
+    '    git -C "$1" update-ref "$dst" "$have" || have=',
+    '  else have=; fi',
+    '  rm -rf "$pre" "$pre.lock"; exec 8>&-',
+    // No prefetch yet: one starting now would only fetch the same again (the guest's sweep removes this marker).
+    'elif [ -n "$pre" ]; then mkdir -p "$pre" 2>/dev/null || true; fi',
+    'if [ -n "$have" ] && [ "$have" = "${4:-}" ]; then git -C "$1" rev-parse --verify "$dst^{commit}"; exit 0; fi',
+    'tip="$1/.git/shard-sync-tip"; rm -rf "$tip"; job=',
+    'if [ -z "$have" ]; then git init -q --bare "$tip"',
+    '  git -C "$tip" -c core.hooksPath=/dev/null -c credential.interactive=false -c fetch.unpackLimit=1 fetch -q --no-tags --depth=1 "$2" "+$3:refs/tip" >/dev/null 2>&1 &',
+    '  job=$!; fi',
     'if ! git -C "$1" -c core.hooksPath=/dev/null -c credential.interactive=false fetch -q --no-tags --filter=blob:none origin "+$3:$dst" >&2; then',
-    '  wait "$job" || true; rm -rf "$tip"',
+    '  if [ -n "$job" ]; then wait "$job" || true; fi; rm -rf "$tip"',
+    '  if [ -n "$have" ]; then git -C "$1" rev-parse --verify "$dst^{commit}"; exit 0; fi',
     '  git -C "$1" config --unset remote.origin.promisor || true; git -C "$1" config --unset remote.origin.partialclonefilter || true; exit 1',
     'fi',
-    'if wait "$job"; then for pack in "$tip"/objects/pack/pack-*.pack; do [ -f "$pack" ] || continue; base=${pack%.pack}',
+    'if [ -n "$job" ] && wait "$job"; then for pack in "$tip"/objects/pack/pack-*.pack; do [ -f "$pack" ] || continue; base=${pack%.pack}',
     '  for ext in idx rev pack; do if [ -f "$base.$ext" ]; then mv "$base.$ext" "$1/.git/objects/pack/"; fi; done; done; fi',
     'rm -rf "$tip"',
     'git -C "$1" rev-parse --verify "$dst^{commit}"',
@@ -110,7 +144,8 @@ export const FETCH_ORIGIN = [
 export const BACKFILL = 'set -eu; cd "$1"; git -c core.hooksPath=/dev/null -c credential.interactive=false fetch -q --no-tags --no-write-fetch-head --refetch --no-filter origin "$2"; ' +
     'git config --unset remote.origin.partialclonefilter || true; git config --unset remote.origin.promisor || true';
 // Applies an optional bundle of HEAD (plus its branch and upstream) and points the workspace HEAD at the laptop's.
-const APPLY_HISTORY = 'set -eu; git init -q "$1"; if [ -n "$2" ]; then git -C "$1" -c core.hooksPath=/dev/null fetch -q --update-head-ok "$2" HEAD:refs/shard-sync/initial ' +
+// $5: a shallow clone's boundary (its .git/shallow), written before the fetch so the bundle's cut history is accepted.
+const APPLY_HISTORY = 'set -eu; git init -q "$1"; if [ -n "${5:-}" ]; then cp "$5" "$1/.git/shallow"; fi; if [ -n "$2" ]; then git -C "$1" -c core.hooksPath=/dev/null fetch -q --update-head-ok "$2" HEAD:refs/shard-sync/initial ' +
     '"+refs/heads/*:refs/heads/*" "+refs/tags/*:refs/tags/*" "+refs/remotes/*:refs/remotes/*"; fi; ' +
     'if [ -n "$4" ]; then git -C "$1" symbolic-ref HEAD "$4"; else git -C "$1" update-ref --no-deref HEAD "$3"; fi; git -C "$1" update-ref HEAD "$3"; git -C "$1" read-tree HEAD; ' +
     'for ref in refs/shard-sync/initial refs/shard-sync/origin; do if git -C "$1" rev-parse -q --verify "$ref" >/dev/null; then git -C "$1" update-ref -d "$ref"; fi; done';
@@ -131,7 +166,7 @@ if missing and git('config','--bool','--default','false','remote.origin.promisor
  absent={l[1:] for l in git('rev-list','--objects','--no-walk','--missing=print','HEAD').split(b'\n') if l.startswith(b'?')}
  want&=absent
  if want: git('-c','fetch.negotiationAlgorithm=noop','fetch','-q','--no-tags','--no-write-fetch-head','--recurse-submodules=no','--filter=blob:none','--stdin','origin',data=b'\n'.join(sorted(want))+b'\n')
-for at in range(0,len(missing),4096): git('checkout-index','-z','--stdin',data=b'\0'.join(missing[at:at+4096])+b'\0')
+for at in range(0,len(missing),4096): git('-c','checkout.workers=0','checkout-index','-z','--stdin',data=b'\0'.join(missing[at:at+4096])+b'\0')
 print(len(missing))
 `;
 /** `git bundle create` streamed straight into the workspace in chunks: any size, no temporary file, no time limit. */
@@ -168,16 +203,19 @@ async function streamBundle(cell, folder, remote, revs, signal) {
  * 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 async function importProjectHistory(cell, folder, root, head, branch, origin, signal, originFirst = ORIGIN_FIRST_BYTES, report = () => undefined) {
+export async function importProjectHistory(cell, folder, root, head, branch, origin, signal, originFirst = ORIGIN_FIRST_BYTES, report = () => undefined, configure) {
     const upstream = branch ? await optionalGit(folder, ['rev-parse', '--symbolic-full-name', `${branch.slice(11)}@{upstream}`], signal) : '';
     const tracked = upstream.startsWith('refs/remotes/') ? upstream : '';
     const tips = ['HEAD', ...(branch ? [branch] : []), ...(tracked ? [tracked] : [])];
     const remote = `/tmp/shard-sync-${randomUUID()}.bundle`;
+    let shallowFile = '', bundled = false;
     try {
         let revs = tips, partial = null;
         if (origin && await historyEstimate(folder, signal) > originFirst) {
             const ref = upstream.startsWith('refs/remotes/origin/') ? `refs/heads/${upstream.slice(20)}` : 'HEAD';
-            const fetched = await cell.exec.run(['sh', '-c', FETCH_ORIGIN, 'shard-sync', root, origin, ref], { timeoutMs: 600_000, maxOutputBytes: 8192, env: { GIT_TERMINAL_PROMPT: '0' }, signal });
+            // This computer's view of that branch on origin: a prefetch at that commit needs no fetch at all.
+            const expected = ref !== 'HEAD' ? await optionalGit(folder, ['rev-parse', '--verify', `${upstream}^{commit}`], signal) : '';
+            const fetched = await cell.exec.run(['sh', '-c', FETCH_ORIGIN, 'shard-sync', root, origin, ref, expected], { timeoutMs: 600_000, maxOutputBytes: 8192, env: { GIT_TERMINAL_PROMPT: '0' }, signal });
             seedPhase('origin_fetch');
             const base = fetched.stdout.trim();
             if (fetched.exitCode === 0 && /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(base)) {
@@ -201,20 +239,75 @@ export async function importProjectHistory(cell, folder, root, head, branch, ori
                 report(`Sending the history from this computer: the workspace could not fetch ${origin} (${tail(fetched.stderr)}).`);
         }
         if (revs) {
+            bundled = true;
             await streamBundle(cell, folder, remote, revs, signal);
             seedPhase('bundle');
         }
-        const result = await cell.exec.run(['sh', '-c', APPLY_HISTORY, 'shard-sync', root, revs ? remote : '', head, branch], { timeoutMs: 600_000, maxOutputBytes: 4096, signal });
+        // A shallow clone (git clone --depth N) has no parents for its oldest commits: Git refuses its bundle ("did not send
+        // all necessary objects") unless the workspace repository has the same shallow boundary.
+        const boundary = revs ? await shallowBoundary(folder, signal) : null;
+        if (boundary) {
+            shallowFile = `${remote}.shallow`;
+            await cell.files.write(shallowFile, boundary, { mode: '0600' });
+        }
+        // With `configure`, the repository's config and exclude rules are set in the same request (0.21.1+).
+        const apply = ['sh', '-c', APPLY_HISTORY, 'shard-sync', root, revs ? remote : '', head, branch, shallowFile];
+        const result = configure
+            ? await runGitStep(cell, ['sh', '-c', APPLY_THEN_CONFIGURE, 'shard-sync', root, revs ? remote : '', head, branch, shallowFile, root, ...configure.settings], { stdin: configure.excludes, env: { SHARD_APPLY: APPLY_HISTORY, SHARD_CONFIGURE: CONFIGURE_GIT }, timeoutMs: 600_000, maxOutputBytes: 4096, ...(signal ? { signal } : {}) })
+            : await runGitStep(cell, apply, { timeoutMs: 600_000, maxOutputBytes: 4096, ...(signal ? { signal } : {}) });
         if (result.exitCode !== 0)
             throw new Error(`initial Git bundle failed: ${result.stderr.trim()}`);
         seedPhase('apply_history');
         return { partial };
     }
     finally {
-        await cell.files.remove(remote).catch(() => undefined);
+        if (bundled)
+            await cell.files.remove(remote).catch(() => undefined);
+        if (shallowFile)
+            await cell.files.remove(shallowFile).catch(() => undefined);
+    }
+}
+/** A shallow clone's boundary commits (its shallow file), or null for a complete history. */
+async function shallowBoundary(folder, signal) {
+    if (await optionalGit(folder, ['rev-parse', '--is-shallow-repository'], signal) !== 'true')
+        return null;
+    const file = await optionalGit(folder, ['rev-parse', '--git-path', 'shallow'], signal);
+    return file ? await readFile(resolve(folder, file)).catch(() => null) : null;
+}
+// APPLY_HISTORY ($1-$5), then CONFIGURE_GIT (the rest; the exclude rules on standard input), in one request.
+const APPLY_THEN_CONFIGURE = 'set -eu; sh -c "$SHARD_APPLY" shard-sync "$1" "$2" "$3" "$4" "$5" </dev/null; shift 5; exec sh -c "$SHARD_CONFIGURE" shard-sync "$@"';
+// Sets the workspace repository's Git config (key value pairs) and its exclude file (standard input) in one request.
+const CONFIGURE_GIT = 'set -eu; umask 077; root=$1; shift; f="$root/.git/shard-sync-excludes"; cat > "$f"; git -C "$root" config core.excludesFile "$f"; ' +
+    'while [ $# -ge 2 ]; do git -C "$root" config "$1" "$2"; shift 2; done';
+/** Git's info/exclude and this computer's excludes file: selection metadata, never credentials or .git data. */
+async function localExcludes(folder, signal) {
+    const readOptional = async (path) => {
+        try {
+            return await readFile(path, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return '';
+            throw error;
+        }
+    };
+    const info = (await projectGit(folder, ['rev-parse', '--git-path', 'info/exclude'], signal)).trim();
+    let global = '';
+    try {
+        global = (await projectGit(folder, ['config', '--path', '--get', 'core.excludesFile'], signal)).trim();
+    }
+    catch (error) {
+        if (signal?.aborted)
+            throw error;
     }
+    return await readOptional(resolve(folder, info)) + '\n' + await readOptional(global ? resolve(folder, global) : join(process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config'), 'git', 'ignore'));
+}
+async function configureWorkspaceGit(cell, root, settings, excludes, signal) {
+    const result = await runGitStep(cell, ['sh', '-c', CONFIGURE_GIT, 'shard-sync', root, ...settings], { stdin: excludes, timeoutMs: 10_000, maxOutputBytes: 4096, ...(signal ? { signal } : {}) });
+    if (result.exitCode !== 0)
+        throw new Error(`could not configure the workspace Git repository: ${tail(result.stderr)}`);
 }
-async function initializeProjectGit(cell, folder, root, signal, populate = false, retry = false, report = () => undefined, initial) {
+async function initializeProjectGit(cell, folder, root, signal, populate = false, retry = false, report = () => undefined, initial, changes, background, beforeHistory) {
     let top;
     try {
         top = (await projectGit(folder, ['rev-parse', '--show-toplevel'], signal)).trim();
@@ -222,16 +315,20 @@ async function initializeProjectGit(cell, folder, root, signal, populate = false
     catch (error) {
         if (signal?.aborted || error.code !== 128)
             throw error;
+        await cell.files.mkdir(root, { parents: true });
         if (populate)
             await copyProjectFiles(cell, folder, root, await missingInWorkspace(cell, root, await selectedProjectPaths(folder, signal), signal), [], signal, report, initial, false);
         return;
     }
     if (top !== folder)
         throw new UsageError('project sync requires the Git repository root; run shard there');
-    const existing = await cell.exec.run(['git', '-C', root, 'rev-parse', '--verify', 'HEAD'], { timeoutMs: 5000, signal });
+    // The workspace folder and whether it already has history, in one request.
+    const existing = await cell.exec.run(['sh', '-c', 'mkdir -p "$1" && exec git -C "$1" rev-parse --verify HEAD', 'shard-sync', root], { timeoutMs: 5000, signal });
     if (existing.exitCode !== 0 && existing.exitCode !== 128)
         throw new Error('could not check workspace Git history');
     if (existing.exitCode === 128 || retry) {
+        // What must be in the VM before its repository appears (a conversation's setup intent, read when its agent starts).
+        await beforeHistory;
         const importHistory = existing.exitCode === 128;
         let head = '', branch = '';
         try {
@@ -248,16 +345,9 @@ async function initializeProjectGit(cell, folder, root, signal, populate = false
             if (signal?.aborted)
                 throw error;
         }
-        let partial = null;
-        if (head && importHistory) {
-            const remote = projectIdentity(folder).remote;
-            ({ partial } = await importProjectHistory(cell, folder, root, head, branch, remote && !remote.startsWith('file:') ? remote : null, signal, ORIGIN_FIRST_BYTES, report));
-        }
-        else if (importHistory) {
-            const result = await cell.exec.run(['git', 'init', '-q', ...(branch.startsWith('refs/heads/') ? ['--initial-branch', branch.slice(11)] : []), root], { timeoutMs: 5000, signal });
-            if (result.exitCode !== 0)
-                throw new Error(`initial Git repository failed: ${result.stderr.trim()}`);
-        }
+        // The author identity, origin, the branch's upstream (it keeps tracking its origin branch, as on this computer) and
+        // the exclude rules: set with the history's import, else in a request of their own.
+        const settings = [];
         for (const key of ['user.name', 'user.email']) {
             let value = '';
             try {
@@ -267,61 +357,50 @@ async function initializeProjectGit(cell, folder, root, signal, populate = false
                 if (signal?.aborted)
                     throw error;
             }
-            if (value) {
-                const result = await cell.exec.run(['git', '-C', root, 'config', key, value], { timeoutMs: 5000, signal });
-                if (result.exitCode !== 0)
-                    throw new Error(`could not copy Git ${key}`);
-            }
+            if (value)
+                settings.push(key, value);
         }
         const origin = projectIdentity(folder).remote;
         if (origin && !origin.startsWith('file:')) {
-            const result = await cell.exec.run(['git', '-C', root, 'config', 'remote.origin.url', origin], { timeoutMs: 5000, signal });
-            if (result.exitCode !== 0)
-                throw new Error('could not copy Git origin');
-            // The imported branch keeps tracking its origin branch, as on this computer.
+            settings.push('remote.origin.url', origin);
             const upstream = importHistory && branch ? await optionalGit(folder, ['rev-parse', '--symbolic-full-name', `${branch.slice(11)}@{upstream}`], signal) : '';
             if (upstream.startsWith('refs/remotes/origin/'))
-                for (const [key, value] of [[`branch.${branch.slice(11)}.remote`, 'origin'], [`branch.${branch.slice(11)}.merge`, `refs/heads/${upstream.slice(20)}`]]) {
-                    const set = await cell.exec.run(['git', '-C', root, 'config', key, value], { timeoutMs: 5000, signal });
-                    if (set.exitCode !== 0)
-                        throw new Error('could not copy Git upstream');
-                }
+                settings.push(`branch.${branch.slice(11)}.remote`, 'origin', `branch.${branch.slice(11)}.merge`, `refs/heads/${upstream.slice(20)}`);
+        }
+        const excludes = await localExcludes(folder, signal);
+        let partial = null;
+        if (head && importHistory) {
+            const remote = projectIdentity(folder).remote;
+            ({ partial } = await importProjectHistory(cell, folder, root, head, branch, remote && !remote.startsWith('file:') ? remote : null, signal, ORIGIN_FIRST_BYTES, report, { settings, excludes }));
         }
+        else {
+            if (importHistory) {
+                const result = await cell.exec.run(['git', 'init', '-q', ...(branch.startsWith('refs/heads/') ? ['--initial-branch', branch.slice(11)] : []), root], { timeoutMs: 5000, signal });
+                if (result.exitCode !== 0)
+                    throw new Error(`initial Git repository failed: ${result.stderr.trim()}`);
+            }
+            await configureWorkspaceGit(cell, root, settings, excludes, signal);
+        }
+        seedPhase('git_config');
         if (head)
-            await seedFromHead(cell, folder, root, populate, signal, report, initial);
+            await seedFromHead(cell, folder, root, populate, signal, report, initial, changes);
         else
             await seedUnborn(cell, folder, root, populate, signal, report, initial);
         // Optional work, after the start's own: the lowest priority, and a failure only leaves the clone partial.
-        if (partial)
-            await cell.exec.start({ argv: ['nice', '-n', '19', 'sh', '-c', BACKFILL, 'shard-backfill', root, partial], env: { GIT_TERMINAL_PROMPT: '0' }, timeout_ms: 3_600_000 }, signal).catch(() => undefined);
-    }
-    // Git's info/exclude and laptop-wide excludes are selection metadata, copied
-    // into a dedicated Git exclude file without syncing credentials or .git data.
-    const readOptional = async (path) => {
-        try {
-            return await readFile(path, 'utf8');
-        }
-        catch (error) {
-            if (error.code === 'ENOENT')
-                return '';
-            throw error;
+        // A caller that collects background work (a conversation start) gets the request instead of waiting for it.
+        if (partial) {
+            const started = cell.exec.start({ argv: ['nice', '-n', '19', 'sh', '-c', BACKFILL, 'shard-backfill', root, partial], env: { GIT_TERMINAL_PROMPT: '0' }, timeout_ms: 3_600_000 }, signal).catch(() => undefined);
+            if (background)
+                background(started);
+            else
+                await started;
         }
-    };
-    const info = (await projectGit(folder, ['rev-parse', '--git-path', 'info/exclude'], signal)).trim();
-    let global = '';
-    try {
-        global = (await projectGit(folder, ['config', '--path', '--get', 'core.excludesFile'], signal)).trim();
     }
-    catch (error) {
-        if (signal?.aborted)
-            throw error;
+    else {
+        // An existing repository keeps its config; its exclude rules follow this computer's.
+        await configureWorkspaceGit(cell, root, [], await localExcludes(folder, signal), signal);
+        seedPhase('git_config');
     }
-    const excludes = await readOptional(resolve(folder, info)) + '\n' + await readOptional(global ? resolve(folder, global) : join(process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config'), 'git', 'ignore'));
-    await cell.files.write(`${root}/.git/shard-sync-excludes`, excludes, { mode: '0600' });
-    const result = await cell.exec.run(['git', '-C', root, 'config', 'core.excludesFile', `${root}/.git/shard-sync-excludes`], { timeoutMs: 5000, signal });
-    if (result.exitCode !== 0)
-        throw new Error('could not apply project Git exclude rules');
-    seedPhase('excludes');
 }
 const nul = (text) => text.split('\0').filter(Boolean);
 /** Git's NUL-separated output of any size, streamed (no output buffer or time bound). */
@@ -330,11 +409,6 @@ async function gitList(folder, args, signal) {
     await projectGitPaths(folder, args, path => { out.push(path); }, { signal });
     return out;
 }
-/**
- * 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 async function localChanges(folder, signal) {
     const [fields, untracked, env, lfs] = await Promise.all([
         gitList(folder, ['diff', '--name-status', '-z', '--no-renames', '--ignore-submodules=all', 'HEAD', '--'], signal),
@@ -374,7 +448,7 @@ export async function localChanges(folder, signal) {
     return { copy, remove, skipped };
 }
 /** HEAD's files come from the workspace's own Git; then only this computer's changes are copied. */
-async function seedFromHead(cell, folder, root, populate, signal, report, initial) {
+async function seedFromHead(cell, folder, root, populate, signal, report, initial, precomputed) {
     if (!populate) {
         // Ignore files must exist before the first remote scan; otherwise a template's dependency outputs would look like
         // agent-created source.
@@ -382,7 +456,8 @@ async function seedFromHead(cell, folder, root, populate, signal, report, initia
         await copyProjectFiles(cell, folder, root, await missingInWorkspace(cell, root, ignores, signal), [], signal, report, undefined, false);
         return;
     }
-    const changes = await localChanges(folder, signal);
+    // A conversation start reads them while its VM starts (0.21.1+).
+    const changes = await (precomputed ?? localChanges(folder, signal));
     seedPhase('local_changes');
     const skip = changes.remove.length ? `/tmp/shard-sync-${randomUUID()}.skip` : '';
     try {

package/dist/agent-setup.d.ts

@@ -5,25 +5,36 @@
  */
 export declare const AGENT_SHELL_VARIABLES: readonly ["CLAUDECODE", "CODEX_SANDBOX", "CODEX_THREAD_ID", "CURSOR_AGENT", "GEMINI_CLI"];
 export declare function codingAgentShell(env: Record<string, string | undefined>): boolean;
-export declare const SETUP_QUESTION = "Is Shardflux for a SaaS platform (your product runs VMs for its own customers through the API, SDK or MCP), or for your personal setup (your own cloud coding agents: each Claude or Codex conversation gets its own VM)?";
+/**
+ * How the agent runs the setup (0.20.1+): it does the work, the person only decides. Onboarding testers (2026-10-12)
+ * found agents handing them commands, links and codes, writing paragraphs and asking open questions.
+ */
+export declare const SETUP_RULES: readonly ["Do every permitted step yourself: run each command and open each link. Never ask your user to paste a secret or sign-in code into the chat.", "Your user answers your questions, agrees to the Terms, approves sign-ins in the browser tabs shard opens, and types secrets into the page shard opens (you never see them).", "If your permission system or auto-mode classifier refuses an action, stop that action. Do not change permissions, wrap it in a script or use another tool to bypass the refusal. Explain the reason and give your user the exact refused command to run in their own terminal; continue independent permitted steps.", "After a refused action, ask for only its non-secret result and resume permitted steps when your user confirms it. Never ask for credentials, credential files or raw logs. Plugin installation needs confirmation that the plugin is installed; machine opening needs its workspace key, not local files or environment variables.", "To check saved account state without printing credentials, use shard setup --guide --json: guide.signed_in.email and guide.api_key_saved. It is a local check, not proof that a key works. If reading setup output or checking state is refused, have your user run this command and confirm those fields; do not read redirected output or credential files instead.", "A command exiting successfully is not proof of setup. Check its non-secret result and the requested behavior; keep any blocked or unobserved step unverified.", "Ask one question at a time as multiple choice, recommended answer first (use your question tool if you have one).", "Keep each message to one or two short sentences: what you are doing or what you need, never how it works.", "Commands that wait for your user in the browser (sign-ins, --ask) take up to 10 minutes: run them with a long timeout or in the background, and tell your user once what to do there."];
+export declare const SETUP_QUESTION = "What are you setting up Shardflux for?";
+/** The answers to SETUP_QUESTION, the usual one first. */
+export declare const SETUP_CHOICES: readonly ["Your own cloud coding agents: each Claude or Codex conversation gets its own VM", "Your product: it runs VMs for its customers through the API, SDK or MCP"];
 export declare const AGENT_SETUP_DOCS = "https://docs.shardflux.dev/guides/agent-setup.md";
-/** One step of a path: what it does, what to ask the user first (if anything), and the commands in order. */
+/** One step of a path: what it does, the one question to ask first (if any) with its answers, and the commands. */
 export interface GuideStep {
     step: string;
     ask?: string;
+    /** Multiple-choice answers to `ask`, the recommended one first. */
+    choices?: string[];
     commands: string[];
     note?: string;
 }
 /** What `shard setup --guide --json` prints. */
 export interface SetupGuide {
+    rules: string[];
     question: string;
+    choices: string[];
     signed_in: {
         email: string | null;
     } | null;
     api_key_saved: boolean;
     account: GuideStep;
-    saas: GuideStep[];
     personal: GuideStep[];
+    saas: GuideStep[];
     terms_url: string;
     privacy_url: string;
     docs: string;

package/dist/agent-setup.js

@@ -1,13 +1,16 @@
 /**
- * Setting Shardflux up from a coding agent (0.17.1+): the one question the agent asks its user first, and the ordered
- * steps of both answers. `shard setup --guide` prints it; so does a bare `shard` without a terminal or in a coding
- * agent's shell, where the command center would wait for keys nobody presses. Local only: no network call and nothing
- * to answer, so it returns at once.
+ * Setting Shardflux up from a coding agent (0.17.1+): how the agent runs it, the one question it asks first, and the
+ * ordered steps of both answers. `shard setup --guide` prints it; so does a bare `shard` without a terminal or in a
+ * coding agent's shell, where the command center would wait for keys nobody presses. Local only: no network call and
+ * nothing to answer, so it returns at once.
  *
- * - SaaS platform: the user's product runs VMs for its own customers (API, SDK, MCP). An account, an API key, the
+ * - Own cloud coding agents (the usual answer): sign in, connect Claude and Codex, set the machine up from this
+ *   computer, choose where conversations open, set up the project and open the first conversation (0.20.1+).
+ * - A product (SaaS platform) running VMs for its own customers (API, SDK, MCP): an account, an API key, the
  *   integration and templates for the customers' workspaces; no agent sign-ins, menu bar or machine.
- * - Personal setup: the user's own cloud coding agents. Sign in, connect Claude and Codex, build the machine from what
- *   the user asks for, set up the project and hand over `shard ./`.
+ *
+ * The agent does permitted steps; the person answers multiple-choice questions, approves browser sign-ins and types
+ * secrets into the page shard opens. A real permission refusal requires a precise user handoff (SETUP_RULES).
  */
 import { legalFields } from "./legal.js";
 /**
@@ -19,7 +22,27 @@ export const AGENT_SHELL_VARIABLES = ['CLAUDECODE', 'CODEX_SANDBOX', 'CODEX_THRE
 export function codingAgentShell(env) {
     return AGENT_SHELL_VARIABLES.some((name) => (env[name]?.trim() ?? '') !== '');
 }
-export const SETUP_QUESTION = 'Is Shardflux for a SaaS platform (your product runs VMs for its own customers through the API, SDK or MCP), or for your personal setup (your own cloud coding agents: each Claude or Codex conversation gets its own VM)?';
+/**
+ * How the agent runs the setup (0.20.1+): it does the work, the person only decides. Onboarding testers (2026-10-12)
+ * found agents handing them commands, links and codes, writing paragraphs and asking open questions.
+ */
+export const SETUP_RULES = [
+    'Do every permitted step yourself: run each command and open each link. Never ask your user to paste a secret or sign-in code into the chat.',
+    'Your user answers your questions, agrees to the Terms, approves sign-ins in the browser tabs shard opens, and types secrets into the page shard opens (you never see them).',
+    'If your permission system or auto-mode classifier refuses an action, stop that action. Do not change permissions, wrap it in a script or use another tool to bypass the refusal. Explain the reason and give your user the exact refused command to run in their own terminal; continue independent permitted steps.',
+    'After a refused action, ask for only its non-secret result and resume permitted steps when your user confirms it. Never ask for credentials, credential files or raw logs. Plugin installation needs confirmation that the plugin is installed; machine opening needs its workspace key, not local files or environment variables.',
+    'To check saved account state without printing credentials, use shard setup --guide --json: guide.signed_in.email and guide.api_key_saved. It is a local check, not proof that a key works. If reading setup output or checking state is refused, have your user run this command and confirm those fields; do not read redirected output or credential files instead.',
+    'A command exiting successfully is not proof of setup. Check its non-secret result and the requested behavior; keep any blocked or unobserved step unverified.',
+    'Ask one question at a time as multiple choice, recommended answer first (use your question tool if you have one).',
+    'Keep each message to one or two short sentences: what you are doing or what you need, never how it works.',
+    'Commands that wait for your user in the browser (sign-ins, --ask) take up to 10 minutes: run them with a long timeout or in the background, and tell your user once what to do there.',
+];
+export const SETUP_QUESTION = 'What are you setting up Shardflux for?';
+/** The answers to SETUP_QUESTION, the usual one first. */
+export const SETUP_CHOICES = [
+    'Your own cloud coding agents: each Claude or Codex conversation gets its own VM',
+    'Your product: it runs VMs for its customers through the API, SDK or MCP',
+];
 export const AGENT_SETUP_DOCS = 'https://docs.shardflux.dev/guides/agent-setup.md';
 const { terms_url: TERMS, privacy_url: PRIVACY } = legalFields();
 export function setupGuide(state) {
@@ -27,46 +50,61 @@ export function setupGuide(state) {
         ? { step: 'Account', commands: ['shard setup --json'], note: `Signed in${state.email ? ` as ${state.email}` : ''}. shard setup saves the organization, project and API key (safe to run again).` }
         : {
             step: 'Account',
-            ask: `Do you agree to the Terms of Service (${TERMS}) and the Privacy Policy (${PRIVACY})? Continue once they do.`,
+            ask: `Do you agree to the Terms of Service (${TERMS}) and the Privacy Policy (${PRIVACY})?`,
+            choices: ['Yes, I agree', 'No'],
             commands: ['shard signup --accept-terms --json'],
-            note: 'It signs up or signs in with this computer’s Codex login and saves an API key. Without a Codex login, or for an account they already have: shard auth login --browser --no-wait --json (give your user the link and the code), then shard auth login --browser --json (returns once they approved) and shard setup --json.',
+            note: 'Signs up or signs in with this computer’s Codex login. Without one, or for an existing account: shard auth login --browser --json opens the sign-in page; tell your user to approve it there (if your command times out, run it again: it waits for the same request), then shard setup --json.',
         };
     return {
+        rules: [...SETUP_RULES],
         question: SETUP_QUESTION,
+        choices: [...SETUP_CHOICES],
         signed_in: state.signedIn ? { email: state.email } : null,
         api_key_saved: state.apiKey,
         account,
-        saas: [
-            { step: 'API key for your product', commands: ['eval "$(shard env)"'], note: 'Exports SHARDFLUX_API_KEY for the SDKs, the MCP server and your product’s server. Keep it in server-side secrets, never in client code.' },
-            {
-                step: 'Integrate',
-                commands: ['npm install @shardflux/sdk', 'pip install shardflux'],
-                note: 'Or the HTTP API (https://api.shardflux.dev/v1) or the MCP server (https://mcp.shardflux.dev/mcp). Your customers’ workspaces start from a template: shard templates build template.yaml. Start at https://docs.shardflux.dev/quickstart.md',
-            },
-        ],
         personal: [
             {
                 step: 'Connect Claude and Codex',
-                ask: 'Which agents do you use: Claude, Codex or both?',
-                commands: ['shard setup --inspect --connect --json --apps claude,codex'],
-                note: 'Claude: your user runs shard agents credentials login claude in their own terminal, once (a claude.ai link and a code). Codex: codex login on this computer; --connect copies it and starts the account’s Codex remote device. Pass only the apps they use.',
+                ask: 'Which coding agents do you use?',
+                choices: ['Claude Code and Codex', 'Claude Code', 'Codex'],
+                commands: ['shard setup --inspect --json', 'shard agents credentials login claude --json', 'shard setup --inspect --connect --json --apps claude,codex'],
+                note: 'Recommend what setup --inspect finds on this computer. The Claude sign-in opens claude.ai and a page for its code in your user’s browser. Codex uses this computer’s Codex login: run codex login yourself if it is missing. Pass only the apps they use.',
+            },
+            {
+                step: 'Set up the machine',
+                ask: 'Set up your cloud machine from this computer? It copies your tools, runtimes, shell, git identity and dotfiles.',
+                choices: ['Yes, copy this computer', 'Not now'],
+                commands: ['shard machine setup --from-this-computer --json', 'shard machine setup --status --json'],
+                note: 'This computer’s Claude Code or Codex does it read-only and saves the machine, in up to 10 minutes: tell your user once, then wait. Their tools carry over once machine.state in --status is ready; when it is failed, tell them its line and run its machine.action.command. Anything else they want on it: shard machine open --json, shard ws exec <key> -- bash -lc \'<install>\', shard files write <key> <path> --ask for a secret file (your user types it in the page), then shard machine save --wait --json.',
             },
             {
-                step: 'Build the machine',
-                ask: 'What should every cloud agent start with? Languages and runtimes, CLIs and tools, dotfiles and shell, secrets and credentials, editor and agent config.',
-                commands: ['shard machine setup --from-this-computer --json', 'shard machine open --json', "shard ws exec <key> -- bash -lc '<install commands>'", 'shard files write <key> <path> --from -', 'shard machine save --wait --json'],
-                note: 'machine setup recreates this computer’s tools, runtimes, shell, git identity and dotfiles on the machine with this computer’s Claude Code or Codex, and saves it (0.20.0+). For the rest: machine open prints the machine VM’s workspace key. Install with ws exec, write dotfiles and secret files with files write (contents on standard input, never in arguments), then save: every new conversation starts from it.',
+                step: 'Choose where conversations open',
+                ask: 'Where should your conversations open?',
+                choices: ['The terminal you use now', 'Claude app', 'Codex app', 'T3 Code'],
+                commands: ['shard agents targets --json', 'shard agents targets --open-in <target> --terminal <app> --json'],
+                note: 'Offer only what targets --json lists as installed, the terminal shard runs in first (for example Ghostty, iTerm2, Warp).',
             },
             {
                 step: 'Set up the project',
-                ask: 'Which repository, which project secrets, and what does a good first run look like (tests, a dev server)?',
-                commands: ['shard ./ --json --prompt "Set up this project and run its tests"', 'shard conversations wait <conversation-id> --timeout 90', 'shard template --json'],
-                note: 'Run it in the project folder (shard ./ codex … for Codex): the conversation gets its own VM, and setup installs the dependencies and saves the project template. Run the wait again while it says Still working. Project secrets: shard secrets import --from <hsec|1password|bitwarden|keychain> NAME, or printf %s "$VALUE" | shard secrets create NAME.',
+                ask: 'Does this project need secrets (API keys, tokens)?',
+                choices: ['No', 'Yes, I’ll type them in a secure page', 'Yes, from my vault (1Password, Bitwarden, Keychain, hsec)'],
+                commands: ['shard secrets create <NAME> --ask --json', 'shard secrets import --from <vault> <item> --as <NAME> --json', 'shard ./ --json --prompt "Set up this project and run its tests"', 'shard conversations wait <conversation-id> --timeout 90', 'shard template --json'],
+                note: 'secrets create --ask opens a page where your user types the value; you only see that it was saved. Run shard ./ in the project folder (shard ./ codex … for Codex): its VM installs the dependencies and saves the project template. Run the wait again while it says Still working.',
             },
             {
-                step: 'Hand over',
+                step: 'Open the first conversation',
                 commands: ['shard ./'],
-                note: 'Your user runs it in their own terminal (shard ./ codex for Codex). Claude conversations continue on claude.ai and in the Claude app; Codex threads in the Codex app, on the web and on the phone.',
+                note: 'It opens in the app your user chose. Tell them, in one sentence, that shard ./ in any project folder starts the next one.',
+            },
+        ],
+        saas: [
+            { step: 'API key for your product', commands: ['eval "$(shard env)"'], note: 'Exports SHARDFLUX_API_KEY for the SDKs, the MCP server and your product’s server. Keep it in server-side secrets, never in client code.' },
+            {
+                step: 'Integrate',
+                ask: 'How will your product call Shardflux?',
+                choices: ['TypeScript SDK', 'Python SDK', 'HTTP API', 'MCP server'],
+                commands: ['npm install @shardflux/sdk', 'pip install shardflux'],
+                note: 'Or the HTTP API (https://api.shardflux.dev/v1) or the MCP server (https://mcp.shardflux.dev/mcp). Your customers’ workspaces start from a template: shard templates build template.yaml. Start at https://docs.shardflux.dev/quickstart.md',
             },
         ],
         terms_url: TERMS,
@@ -94,23 +132,27 @@ function stepText(n, s) {
     const head = `${n}. ${s.step}.${s.ask ? ` Ask: ${s.ask}` : ''}`;
     return [
         `  ${wrap(head, '     ')}`,
+        ...(s.choices ? [`     ${wrap(`Choices: ${s.choices.join(' | ')}`, '     ', 96)}`] : []),
         ...s.commands.map((c) => `       ${c}`),
         ...(s.note ? [`     ${wrap(s.note, '     ', 96)}`] : []),
     ].join('\n');
 }
 export function setupGuideText(g) {
     return [
-        'Set up Shardflux. Ask your user one question first:',
-        `  ${wrap(g.question, '  ')}`,
+        'Set up Shardflux for your user. How:',
+        ...g.rules.map((r) => `  - ${wrap(r, '    ', 98)}`),
         '',
-        stepText(1, g.account),
+        'First ask, as multiple choice:',
+        `  ${wrap(`${g.question} Choices: ${g.choices.join(' | ')}`, '  ')}`,
         '',
-        'SaaS platform:',
-        ...g.saas.map((s, i) => stepText(i + 2, s)),
+        stepText(1, g.account),
         '',
-        'Personal setup:',
+        'Own cloud coding agents:',
         ...g.personal.map((s, i) => stepText(i + 2, s)),
         '',
+        'Product (SaaS platform):',
+        ...g.saas.map((s, i) => stepText(i + 2, s)),
+        '',
         `Every step in detail: ${g.docs}. Every command: shard --help.`,
     ].join('\n') + '\n';
 }