@shardflux/cli 0.20.0 → 0.23.0

package/dist/agent-config-return.js

@@ -16,16 +16,20 @@
 import { createHash, randomBytes } from 'node:crypto';
 import { appendFileSync, chmodSync, closeSync, copyFileSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, writeSync } from 'node:fs';
 import { homedir } from 'node:os';
+import { setTimeout as delay } from 'node:timers/promises';
 import { basename, dirname, extname, join } from 'node:path';
 import { ShardfluxApiError } from '@shardflux/sdk';
-import { listConversations, localConversations } from "./conversations.js";
+import { conversationsUnavailable, listConversations, localConversations } from "./conversations.js";
 import { MEMORY_PATH, localConfigPath, memoryRoot, returnablePath } from "./agent-config-files.js";
 import { writePrivateFile } from "./credentials.js";
 import { conversationClient } from "./conversation-commands.js";
 import { configManifests } from "./agent-config-sync.js";
 import { savedMachine } from "./filesystem-state.js";
 import { openMachine } from "./filesystem-commands.js";
+import { thisComputer } from "./this-computer.js";
 export const RETURN_ROOT = '/shardflux/project/agent-config';
+/** The latest agent-config line ({notice, at}), for the Linux app's top-bar panel (CLI 0.20.2+). */
+export const AGENT_CONFIG_NOTICE = 'agent-config-notice.json';
 const HASH = /^[0-9a-f]{64}$/;
 const MAX_BYTES = 16 << 20;
 const READ_CHUNK = 8 << 20;
@@ -328,7 +332,7 @@ function list(names) {
  */
 export function returnNotice(app, items, platform = process.platform) {
     const who = app === 'codex' ? 'Codex' : 'Claude';
-    const here = platform === 'darwin' ? 'this Mac' : 'this computer';
+    const here = thisComputer(platform);
     // A memory's MEMORY.md index line is part of saving that memory, not a memory of its own.
     const memoryNotes = items.some(i => MEMORY_PATH.test(i.vm_path) && !i.vm_path.endsWith('/memory/MEMORY.md') && ['created', 'updated', 'trashed'].includes(i.action));
     const saved = items.filter(i => (i.action === 'created' || i.action === 'updated') && !(memoryNotes && i.vm_path.endsWith('/memory/MEMORY.md'))).map(i => itemName(i.vm_path).name);
@@ -379,9 +383,104 @@ async function projectCell(ctx, c, all) {
 }
 /** How often the device helper looks for agent config to bring back: its own loop, never behind a files or transcript pass. */
 export const AGENT_CONFIG_POLL_MS = 2000;
-/** One pass of the device helper's own agent-config loop: list the account's conversations and apply what came back. */
+/** With none of this user's conversations active, the full listing backs off (doubling) to this. */
+export const AGENT_CONFIG_IDLE_MS = 60_000;
+/** While backed off, one cheap request (`state=working`, usually empty) this often notices a turn starting anywhere. */
+export const AGENT_CONFIG_PROBE_MS = 10_000;
+/** A conversation counts as active for this long after its last activity (a turn's start or end). */
+export const AGENT_CONFIG_ACTIVE_WINDOW_MS = 5 * 60_000;
+/**
+ * A working conversation counts as active only this long after its last activity: one left "working" by a VM that went
+ * away (staging QA FE1: 60 such, all more than a day old) must not hold every computer at the fast cadence. A longer
+ * turn still comes back, at the idle cadence.
+ */
+export const AGENT_CONFIG_WORKING_WINDOW_MS = 60 * 60_000;
+/** This user's conversations that are working (recently) or ended a turn within the active window. */
+export function activeConversations(all, records, me, now = Date.now()) {
+    return all.filter(c => {
+        if (c.route === 'codex-cloud' || c.ended_at || !ownConversation(c, records, me))
+            return false;
+        const idle = now - Date.parse(c.last_activity_at ?? c.created_at);
+        return idle < (c.state === 'working' ? AGENT_CONFIG_WORKING_WINDOW_MS : AGENT_CONFIG_ACTIVE_WINDOW_MS);
+    });
+}
+export const CADENCE = { activeMs: AGENT_CONFIG_POLL_MS, idleMs: AGENT_CONFIG_IDLE_MS, probeMs: AGENT_CONFIG_PROBE_MS };
+/**
+ * When the next listing is due. Active (one of this user's conversations works or just ended a turn): every 2 s.
+ * Idle: the interval doubles to 60 s, with a cheap working-only probe every 10 s and a check of this computer's own
+ * conversation records each second; either snaps it back to 2 s at once.
+ */
+export class AgentConfigCadence {
+    options;
+    interval;
+    fullAt = 0;
+    probeAt = 0;
+    recordsMtime = 0;
+    constructor(options = CADENCE) { this.options = options; this.interval = options.activeMs; }
+    /** After a full pass: active keeps 2 s, idle doubles toward the idle ceiling. */
+    listed(active, now = Date.now()) {
+        this.fullAt = now;
+        this.probeAt = now;
+        this.interval = active ? this.options.activeMs : Math.min(this.options.idleMs, Math.max(this.options.activeMs, this.interval * 2));
+    }
+    snap() { this.interval = this.options.activeMs; this.fullAt = 0; }
+    fullDue(now = Date.now()) { return now - this.fullAt >= this.interval; }
+    probeDue(now = Date.now()) { return this.interval > this.options.probeMs && now - this.probeAt >= this.options.probeMs; }
+}
+/** One full pass: list the account's conversations, apply what came back; true while one of this user's is active. */
 export async function returnAgentConfigsOnce(ctx, state) {
-    return returnAgentConfigs(ctx, localConversations(ctx), await listConversations(ctx), state);
+    const records = localConversations(ctx), all = await listConversations(ctx);
+    await returnAgentConfigs(ctx, records, all, state);
+    const me = all.some(c => c.started_by?.user_id) ? await myUserId(ctx, state) : undefined;
+    return activeConversations(all, records, me).length > 0;
+}
+/** The cheap probe: is any of this user's conversations working right now (one request, usually an empty page)? */
+export async function workingProbe(ctx, state) {
+    const page = await conversationClient(ctx).conversations.list({ state: 'working', limit: 200 });
+    const working = page.data;
+    const me = working.some(c => c.started_by?.user_id) ? await myUserId(ctx, state) : undefined;
+    return activeConversations(working, localConversations(ctx), me).length > 0;
+}
+/** The device helper's agent-config loop: activity-driven cadence, its own backoff on errors, never another loop's. */
+export async function runAgentConfigLoop(ctx, state, signal, cadence = new AgentConfigCadence(), tickMs = 1000) {
+    let failures = 0, retryAt = 0;
+    const reported = new Set();
+    const agents = join(ctx.store.dir, 'agents.json');
+    while (!signal.aborted) {
+        const now = Date.now();
+        // A conversation started on this computer is recorded in agents.json: back to 2 s before its first turn ends.
+        try {
+            const m = statSync(agents).mtimeMs;
+            if (cadence.recordsMtime && m !== cadence.recordsMtime)
+                cadence.snap();
+            cadence.recordsMtime = m;
+        }
+        catch { /* none yet */ }
+        if (now >= retryAt) {
+            try {
+                if (cadence.fullDue(now))
+                    cadence.listed(await returnAgentConfigsOnce(ctx, state));
+                else if (cadence.probeDue(now)) {
+                    cadence.probeAt = now;
+                    if (await workingProbe(ctx, state))
+                        cadence.snap();
+                }
+                failures = 0;
+            }
+            catch (e) {
+                if (signal.aborted)
+                    break;
+                const wait = Math.min(300_000, 5000 * 2 ** Math.min(failures++, 6));
+                retryAt = Date.now() + wait;
+                const message = e instanceof Error ? e.message : String(e);
+                if (!conversationsUnavailable(e) && !reported.has(message)) {
+                    reported.add(message);
+                    ctx.io.stderr.write(`Agent config: ${message} (retrying in ${wait / 1000}s).\n`);
+                }
+            }
+        }
+        await delay(tickMs, undefined, { signal }).catch(() => undefined);
+    }
 }
 /**
  * This computer's checkout of a conversation's repository: the folder it was started from here, else the folder of
@@ -498,6 +597,13 @@ export async function returnAgentConfigs(ctx, records, all, state) {
     if (line) {
         ctx.io.stdout.write(JSON.stringify({ type: 'agent_config', notice: line }) + '\n');
         ctx.io.stderr.write(`${new Date().toISOString()} ${line}\n`);
+        // The Linux app reads the line here (its helper runs under systemd, whose standard output no app sees).
+        try {
+            writePrivateFile(ctx.store.dir, join(ctx.store.dir, AGENT_CONFIG_NOTICE), JSON.stringify({ notice: line, at: new Date().toISOString() }) + '\n');
+        }
+        catch (error) {
+            ctx.io.stderr.write(`Agent config notice: ${error instanceof Error ? error.message : String(error)}\n`);
+        }
     }
     // SHARDFLUX_AGENT_CONFIG_FOLD=off holds machine folds (an operator testing that machine); the queue keeps them.
     if (!state.folding && ctx.io.env.SHARDFLUX_AGENT_CONFIG_FOLD !== 'off')

package/dist/agent-credentials.js

@@ -3,7 +3,8 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { json } from "./format.js";
 import { UsageError } from "./errors.js";
-import { loginClaudeInWorkspace, requireClaudeTerminal, cloudClaudeLogin } from "./claude-cloud-login.js";
+import { claudeTerminal, cloudClaudeLogin, loginClaudeInWorkspace } from "./claude-cloud-login.js";
+import { askTimeout } from "./secret-ask.js";
 import { resolveWorkspace } from "./commands.js";
 import { projectIdentity, projectLabels } from "./project-identity.js";
 async function optionalFile(file) {
@@ -74,7 +75,10 @@ export const AGENT_CREDENTIAL_HANDLERS = {
             output(ctx, existing);
             return 0;
         }
-        requireClaudeTerminal(ctx);
+        // In a coding agent's shell, with --json, without a terminal or with --ask (0.20.1+): the claude.ai sign-in and a
+        // page for its code open in the browser. On a terminal the sign-in attaches to it.
+        const headless = values.ask === true || !claudeTerminal(ctx);
+        const timeoutMs = askTimeout(values);
         const project = projectIdentity('./');
         let ws;
         if (typeof values.workspace === 'string')
@@ -85,7 +89,7 @@ export const AGENT_CREDENTIAL_HANDLERS = {
             const current = await cloud.workspaces.findByKey(key, { includeDeleted: false, signal: ctx.signal });
             ws = await cloud.workspaces.open({ key, template: 'coding', labels: { ...current?.labels, ...projectLabels(project, 'main', 'claude') }, wait: { signal: ctx.signal, timeoutMs: ctx.wakeTimeoutMs } });
         }
-        output(ctx, await loginClaudeInWorkspace(ctx, ws));
+        output(ctx, await loginClaudeInWorkspace(ctx, ws, headless ? { headless: { timeoutMs } } : {}));
         return 0;
     },
     'agents credentials sync': async (ctx) => { output(ctx, await syncAgentCredentials(ctx.cloud(), { home: ctx.io.env.HOME ?? ctx.io.env.USERPROFILE, redact: (value) => ctx.addSecret(value) })); return 0; },

package/dist/agent-repository.d.ts

@@ -22,12 +22,21 @@ export declare function seedAgentRepository(ctx: Ctx, ws: Workspace, folder: str
     populate?: boolean;
     initialFiles?: readonly string[];
     onInitialFiles?: () => void;
+    changes?: Promise<LocalChanges>;
+    background?: (started: Promise<unknown>) => void;
+    beforeHistory?: Promise<unknown>;
 }): Promise<void>;
 /**
  * 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;
+/**
+ * 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 declare function runGitStep(cell: Pick<SyncCell, 'exec'>, argv: string[], options: Parameters<SyncCell['exec']['run']>[1] & object, attempts?: number): Promise<Awaited<ReturnType<SyncCell['exec']['run']>>>;
 /** 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;
@@ -39,7 +48,10 @@ export declare const CHECKOUT_HEAD: string;
  * 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<{
+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, configure?: {
+    settings: string[];
+    excludes: string;
+}): Promise<{
     partial: string | null;
 }>;
 /**
@@ -47,11 +59,12 @@ export declare function importProjectHistory(cell: SyncCell, folder: string, roo
  * 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 localChanges(folder: string, signal?: AbortSignal): Promise<{
+export type LocalChanges = {
     copy: string[];
     remove: string[];
     skipped: {
         path: string;
         reason: string;
     }[];
-}>;
+};
+export declare function localChanges(folder: string, signal?: AbortSignal): Promise<LocalChanges>;

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 {