@bevel-software/platform-core-backend 0.29.0 → 0.31.0

package/src/modules/workspace/startup/kb-startup-runner.ts

@@ -6,7 +6,7 @@ import { logger } from '../../../shared/logging.js';
 // callback of its own, and a module logger of the same name would be
 // shadowed exactly where it is meant to be the default.
 const startupLog = logger('kb-startup');
-import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
+import { branchForWorkspaceId, workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import type { KbBranch, OnServerStart, ServerStartContext } from './on-server-start.js';
 import { git, lsRemoteHeads, stampIdentity, withTempDir } from './kb-git.js';
 import { GitRunError, type IGitRunner } from '../../../shared/git.contract.js';
@@ -20,7 +20,11 @@ import {
 } from '../../../shared/git-failure.js';
 import { redactSecret, urlQuerySecrets } from '../../../shared/redact-secret.js';
 import { normalizeRepositoryAddress, sameRepository } from '../../kb-fs/remote-url.js';
-import { setAsideClone, setAsideRootFor, setAsideStamp } from '../set-aside-clone.js';
+import { setAsideClone, setAsideRepository, setAsideRootFor, setAsideStamp } from '../set-aside-clone.js';
+import { workingCopyShape, type WorkingCopyShape } from '../kb-repository.js';
+import type { FetchOptions, IKbRepository } from '../kb-repository.contract.js';
+import { fetchInstant } from '../fetch-instant.js';
+import { assertValidBranchName } from '../../kb-fs/branch-name.js';
 
 /**
  * The KB startup phase: run every registered {@link OnServerStart} step, in
@@ -129,6 +133,12 @@ export interface KbStartupRunnerOptions {
    * minute; a suite passes a short one.
    */
   unfinishedCloneQuietMs?: number;
+  /**
+   * The knowledge base's one repository, every branch workspace a worktree of
+   * it — THE SAME INSTANCE THE WORKSPACE SERVICE IS GIVEN (see
+   * `kb-repository.ts`). Built by the composition root, never here.
+   */
+  repository: IKbRepository;
 }
 
 const UNFINISHED_CLONE_QUIET_MS = 60_000;
@@ -140,10 +150,16 @@ const LONGEST_CLONE_MS = 600_000;
  * on every one of these is being worked on by something that will not stop.
  */
 const PASSES_OVER_ONE_WORKING_COPY = 4;
+/**
+ * How recent a fetch of the repository the phase takes as current. Every
+ * branch it visits is a worktree of the one repository, so one fetch serves
+ * them all; a boot that visits 142 branches fetches once, not 142 times.
+ */
+const STARTUP_FETCH_WINDOW_MS = 30_000;
 
-/** Whether `git clone` failed because its destination already held something, having written nothing. */
+/** Whether `git clone` or `git worktree add` failed because its destination already held something, having written nothing. */
 function refusedAnOccupiedFolder(err: unknown): boolean {
-  return err instanceof Error && /already exists and is not an empty directory/.test(err.message);
+  return err instanceof Error && /already exists and is not an empty directory|' already exists$/m.test(err.message);
 }
 
 /**
@@ -239,7 +255,24 @@ export interface RetryOptions {
 }
 
 export class KbStartupRunner {
-  constructor(private readonly opts: KbStartupRunnerOptions) {}
+  private readonly repository: IKbRepository;
+  /**
+   * Branches deleted on the remote after the phase listed them: the
+   * repository's fetch (`--prune`) took their `origin/<branch>` away. Their
+   * worktrees are left as they are, and the phase commits and pushes nothing
+   * to them — a push would bring a deleted branch back.
+   */
+  private readonly goneFromRemote = new Set<string>();
+  /**
+   * When this run listed the remote's branches. A fetch that started before
+   * it may lack a deletion the listing already saw, so only a fetch since
+   * counts as current for the branches the run opens (`fetchedSince`).
+   */
+  private listedAt = 0;
+
+  constructor(private readonly opts: KbStartupRunnerOptions) {
+    this.repository = opts.repository;
+  }
 
   /** The run in progress, so two invokers share one rather than racing clones. */
   private inFlight: Promise<void> | null = null;
@@ -431,11 +464,19 @@ export class KbStartupRunner {
             'screen or GITHUB_TOKEN instead.',
         );
       }
+      // What a previous run found deleted may have been pushed again since:
+      // each run asks afresh.
+      this.goneFromRemote.clear();
+      this.listedAt = fetchInstant();
       const heads = await this.ensureRemote();
       // AFTER the remote answered: the configured address is known to be a
       // repository we can reach, so a clone of a different one is stale, not
       // a casualty of a typo in the address.
       await this.reconcileClonesWithConfiguredRepository();
+      // Full clones from a release before worktrees become worktrees of the
+      // one repository — after the address check, so a clone of another
+      // repository is set aside rather than imported.
+      await this.convertLegacyClones();
       const ctx = this.buildContext(heads, handles);
 
       for (const step of this.opts.steps) {
@@ -486,6 +527,11 @@ export class KbStartupRunner {
       for (const h of handles.values()) {
         await this.finalize(h);
       }
+      // The repository's garbage collection, once per boot, with every
+      // branch's work landed and nothing served yet: automatic collection is
+      // off on the repository, where a commit in one worktree would collect
+      // beside every other worktree's work.
+      await this.repository.maintain();
     } catch (err) {
       // Every exit carries a scrubbed message: the port scrubs only what the
       // environment holds, and a token saved on the setup screen is the one
@@ -674,19 +720,32 @@ export class KbStartupRunner {
    */
   private async reconcileClonesWithConfiguredRepository(): Promise<void> {
     const configured = this.opts.kbRepoUrl();
+    // One folder per run, so what was set aside together stays together.
+    const stamp = setAsideStamp();
+    const setAsideRoot = setAsideRootFor(this.opts.workspacesRoot, this.opts.setAsideRoot);
+    // The repository first: its address is every worktree's. Even with no
+    // workspaces root — the repository lives outside it, and a worktree added
+    // later would fetch from whatever address it holds.
+    //
+    // The root is read BEFORE anything moves, and only an absent root counts
+    // as "no workspaces": one that cannot be read (a permission or I/O error)
+    // stops the phase, rather than letting the repository move without the
+    // worktrees it could not see.
     let entries: import('node:fs').Dirent[];
     try {
       entries = await fs.readdir(this.opts.workspacesRoot, { withFileTypes: true });
-    } catch {
-      return; // no workspaces yet
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code !== 'ENOENT' && code !== 'ENOTDIR') throw err;
+      entries = []; // no workspaces yet
     }
-    // One folder per run, so what was set aside together stays together.
-    const stamp = setAsideStamp();
-    const setAsideRoot = setAsideRootFor(this.opts.workspacesRoot, this.opts.setAsideRoot);
+    await this.reconcileRepositoryWithConfigured(configured, path.join(setAsideRoot, stamp));
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
       const repoDir = path.join(this.opts.workspacesRoot, entry.name, this.opts.kbDirName);
-      const hasGit = await fs.access(path.join(repoDir, '.git')).then(() => true, () => false);
+      // A full clone only: a worktree reads the repository's address, and went
+      // (or stayed) with it above.
+      const hasGit = await fs.stat(path.join(repoDir, '.git')).then((s) => s.isDirectory(), () => false);
       if (!hasGit) continue;
       let origin: string;
       try {
@@ -721,6 +780,272 @@ export class KbStartupRunner {
       await this.announceDiscarded(entry.name);
     }
   }
+  /**
+   * The repository's half of {@link reconcileClonesWithConfiguredRepository}.
+   * The address is the repository's, shared by every worktree, so it is
+   * decided once: the same repository at a new address is re-pointed and
+   * kept; another repository is set aside TOGETHER WITH EVERY WORKTREE OF IT,
+   * into `dest` — a worktree's commits live in the repository, so neither is
+   * of use without the other. Nothing is deleted.
+   */
+  private async reconcileRepositoryWithConfigured(configured: string, dest: string): Promise<void> {
+    // Read and probed as itself (reads, and a probe fetch into a throwaway
+    // ref, which git locks); the one write, the re-pointing, is made by
+    // `setOriginUrl` as the repository's administrator. The phase runs before
+    // anything is served, so nothing opens a branch between the two.
+    const verdict = await (
+      async (): Promise<{ was: string } | 'keep' | 'repointed'> => {
+        const origin = await this.repository.originUrl();
+        if (origin === null || sameRepository(origin, configured)) return 'keep';
+        const was = this.redact(normalizeRepositoryAddress(origin));
+        // Any commit of ours will do: a common ancestor of one is a common
+        // ancestor of the repository's history.
+        const ours = (
+          await git(this.opts.gitRunner, this.repository.dir, [
+            'for-each-ref', '--count=1', '--format=%(objectname)', 'refs/heads', 'refs/remotes/origin',
+          ]).catch(() => '')
+        ).trim();
+        if (ours !== '' && (await this.sharesHistoryWithConfigured(this.repository.dir, configured, ours))) {
+          await this.repository.setOriginUrl(configured);
+          startupLog.warn(
+            `the knowledge-base repository was fetched from ${was}, whose history the configured repository ` +
+              'holds: the same repository at a new address. Pointed at the configured address and kept, with ' +
+              'every worktree and their unpushed work.',
+          );
+          return 'repointed';
+        }
+        return { was };
+      }
+    )();
+    if (typeof verdict === 'string') return;
+    const { was } = verdict;
+    // Every worktree's work leaves first, and may stop the phase: see
+    // `beforeCloneSetAside`.
+    const worktreeIds: string[] = [];
+    for (const entry of await fs.readdir(this.opts.workspacesRoot, { withFileTypes: true }).catch(() => [])) {
+      if (!entry.isDirectory()) continue;
+      const dir = path.join(this.opts.workspacesRoot, entry.name, this.opts.kbDirName);
+      if (await fs.stat(path.join(dir, '.git')).then((s) => s.isFile(), () => false)) worktreeIds.push(entry.name);
+    }
+    for (const id of worktreeIds) await this.opts.beforeCloneSetAside?.(id);
+    const moved = await setAsideRepository(this.repository, this.opts.workspacesRoot, this.opts.kbDirName, dest);
+    startupLog.warn(
+      `the knowledge-base repository is of another repository (${was}). It and its ${moved.length} worktree(s) were ` +
+        `set aside together at ${dest}; nothing was deleted, and a fresh repository is made from the configured ` +
+        'one. Work that was never pushed is in that folder: `git log` in a worktree there shows it.',
+    );
+    for (const id of moved) await this.announceDiscarded(id);
+  }
+
+  /**
+   * Convert every full clone under the workspaces root — what a release before
+   * worktrees left there — into a worktree of the one repository, ONE AT A
+   * TIME, without losing a commit:
+   *
+   *  1. the clone's branch tip is imported into the repository as the branch's
+   *     local ref (`git fetch <clone> +refs/heads/<b>:refs/heads/<b>`), so
+   *     commits the remote lacks are in the repository before anything moves,
+   *     and with it every stash entry and other local ref the clone holds,
+   *     under `refs/kb-converted/<workspace id>/`;
+   *  2. the clone is moved aside, beside where it was (one rename);
+   *  3. the worktree is added at the imported tip, and checked to be there;
+   *  4. the files git ignores in the clone, in no commit, are copied into it;
+   *  5. the clone is renamed `.<kb>.converted`: the one step that says the
+   *     copy is complete, taken before the worktree is used, so a clone left
+   *     behind after it is never copied from again (it would overwrite edits
+   *     made since); a rename that fails undoes the conversion;
+   *  6. only then is the clone removed. A removal that fails leaves the
+   *     `.converted` folder, which the next boot removes and nothing reads.
+   *
+   * A clone that cannot be converted — unreadable objects, uncommitted changes
+   * that are not anybody's to discard, a branch it is not on — is put back
+   * where it was and keeps working as a clone; the branch is logged, and the
+   * next boot tries again. One clone never stops the phase.
+   *
+   * A conversion a crash cut short is finished or undone first: the moved
+   * clone's ignored files are copied and it is removed when its worktree is
+   * in place (its tip was imported before it moved, and the worktree was not
+   * used yet: the rename of step 5 comes first), and put back when it is not.
+   */
+  private async convertLegacyClones(): Promise<void> {
+    let entries: import('node:fs').Dirent[];
+    try {
+      entries = await fs.readdir(this.opts.workspacesRoot, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    let converted = 0;
+    const kept: string[] = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const workspaceDir = path.join(this.opts.workspacesRoot, entry.name);
+      const repoDir = path.join(workspaceDir, this.opts.kbDirName);
+      const aside = path.join(workspaceDir, `.${this.opts.kbDirName}.converting`);
+      const convertedClone = path.join(workspaceDir, `.${this.opts.kbDirName}.converted`);
+      await this.removeConvertedClone(branchForWorkspaceId(entry.name), convertedClone);
+      try {
+        await this.finishInterruptedConversion(repoDir, aside, convertedClone);
+      } catch (err) {
+        // Both folders stay as they are; the next start looks again.
+        kept.push(branchForWorkspaceId(entry.name));
+        startupLog.warn(
+          `an interrupted conversion of the "${branchForWorkspaceId(entry.name)}" working copy could not be finished (` +
+            `${this.redact(err instanceof Error ? err.message : String(err))}). The moved clone is kept as it is, and the next start tries again.`,
+        );
+        continue;
+      }
+      const branch = branchForWorkspaceId(entry.name);
+      let shape: WorkingCopyShape;
+      try {
+        shape = await workingCopyShape(repoDir);
+      } catch (err) {
+        // A `.git` that could not be read has shown nothing: left as it is,
+        // named, and looked at again by the next start.
+        kept.push(branch);
+        startupLog.warn(
+          `the "${branch}" working copy could not be inspected for conversion (` +
+            `${this.redact(err instanceof Error ? err.message : String(err))}). It is left as it is, and the next start tries again.`,
+        );
+        continue;
+      }
+      if (shape !== 'clone') continue;
+      try {
+        if (workspaceIdForBranch(branch) !== entry.name) continue;
+        assertValidBranchName(branch);
+      } catch {
+        continue;
+      }
+      // A clone with no commit on its branch is an unfinished one, which the
+      // branch's own pass sets aside: there is no tip to import.
+      const tip = await git(this.opts.gitRunner, repoDir, [
+        'for-each-ref', '--format=%(objectname)', `refs/heads/${branch}`,
+      ]).catch(() => 'unreadable');
+      if (tip.trim() === '') continue;
+      try {
+        await this.convertOneClone(branch, repoDir, aside, convertedClone);
+        converted++;
+      } catch (err) {
+        kept.push(branch);
+        startupLog.warn(
+          `the "${branch}" working copy is still a full clone: it could not be converted to a worktree (` +
+            `${this.redact(err instanceof Error ? err.message : String(err))}). It keeps working as a clone, ` +
+            'nothing in it was changed, and the next start tries again.',
+        );
+      }
+    }
+    if (converted > 0 || kept.length > 0) {
+      startupLog.info(
+        `converted ${converted} full clone(s) to worktrees of the knowledge-base repository` +
+          (kept.length > 0 ? `; ${kept.length} left as they are, to be tried again at the next start (${kept.join(', ')})` : '') +
+          '.',
+      );
+    }
+  }
+
+  private async convertOneClone(branch: string, repoDir: string, aside: string, converted: string): Promise<void> {
+    const onBranch = (await git(this.opts.gitRunner, repoDir, ['symbolic-ref', '--quiet', '--short', 'HEAD'])).trim();
+    if (onBranch !== branch) throw new Error(`it is on "${onBranch}", not on its own branch`);
+    // Uncommitted work is in the working tree, not in a commit the import can
+    // carry; the clone keeps it, and is converted once it is committed.
+    const dirty = (await git(this.opts.gitRunner, repoDir, ['status', '--porcelain=v1'])).trim();
+    if (dirty !== '') throw new Error('it has uncommitted changes');
+    const tip = await this.repository.importBranch(repoDir, branch);
+    await this.importLocalRefs(repoDir, branch);
+    await fs.rename(repoDir, aside);
+    try {
+      await this.repository.addWorktree(branch, repoDir, { allowLocalOnly: true, keepLocalTip: true });
+      const head = (await git(this.opts.gitRunner, repoDir, ['rev-parse', 'HEAD'])).trim();
+      if (head !== tip) throw new Error(`the worktree came up at ${head}, not at the clone's tip ${tip}`);
+      await this.copyIgnoredFiles(aside, repoDir);
+      await fs.rename(aside, converted);
+    } catch (err) {
+      await this.undoConversion(repoDir, aside);
+      throw err;
+    }
+    await this.removeConvertedClone(branch, converted);
+  }
+
+  /**
+   * The clone's stash and its other local refs, into the repository before
+   * the clone goes (see `KbRepository.importLocalRefs`), and said where.
+   */
+  private async importLocalRefs(cloneDir: string, branch: string): Promise<void> {
+    const kept = await this.repository.importLocalRefs(cloneDir, branch, workspaceIdForBranch(branch));
+    if (kept.length === 0) return;
+    startupLog.info(
+      `the "${branch}" clone's stash and other local refs are kept in the knowledge-base repository (${kept.length}): ` +
+        `${kept.join(', ')}. \`git log <ref>\` in its worktree shows each.`,
+    );
+  }
+
+  /** Undone: the worktree goes, the clone comes back exactly as it was. */
+  private async undoConversion(repoDir: string, aside: string): Promise<void> {
+    await fs.rm(repoDir, { recursive: true, force: true }).catch(() => undefined);
+    await this.repository.prune().catch(() => undefined);
+    await fs.rename(aside, repoDir);
+  }
+
+  /**
+   * Remove a converted clone: its commits and ignored files are in the
+   * worktree already. One that cannot be removed is said and left; the next
+   * boot tries again, and nothing ever copies from it.
+   */
+  private async removeConvertedClone(branch: string, converted: string): Promise<void> {
+    await fs.rm(converted, { recursive: true, force: true }).catch((err: unknown) => {
+      startupLog.warn(
+        `the converted clone of "${branch}" could not be removed (` +
+          `${this.redact(err instanceof Error ? err.message : String(err))}). Nothing reads it; the next start tries again.`,
+      );
+    });
+  }
+
+  /**
+   * Copy the files git ignores in the clone at `from` into the worktree at
+   * `to`: they are in no commit the import carried, yet they are the
+   * clone's. Copied, not moved, so an undo puts the clone back whole; and
+   * over whatever is there, so a copy a crash cut short (a partial file) is
+   * made whole again before the clone goes.
+   */
+  private async copyIgnoredFiles(from: string, to: string): Promise<void> {
+    const ignored = (
+      await git(this.opts.gitRunner, from, ['ls-files', '-z', '--others', '--ignored', '--exclude-standard', '--directory'])
+    )
+      .split('\0')
+      .map((rel) => rel.replace(/\/$/, ''))
+      .filter(Boolean);
+    for (const rel of ignored) {
+      await fs.mkdir(path.dirname(path.join(to, rel)), { recursive: true });
+      await fs.cp(path.join(from, rel), path.join(to, rel), { recursive: true, force: true, verbatimSymlinks: true });
+    }
+  }
+
+  /** See {@link convertLegacyClones}: a conversion a crash cut short. */
+  private async finishInterruptedConversion(repoDir: string, aside: string, converted: string): Promise<void> {
+    if (!(await fs.access(aside).then(() => true, () => false))) return;
+    // Only a checkout shown to be no worktree is removed: a link that could
+    // not be read has shown nothing, and the error leaves both folders alone.
+    if ((await workingCopyShape(repoDir)) === 'worktree') {
+      // Not used since it was added: the clone is still `.converting`, so
+      // the copy is finished (over a partial one) as the conversion would
+      // have, and undone when it cannot be.
+      try {
+        // Imported before the clone moved; again, in case that was by a
+        // release that imported its branch only.
+        await this.importLocalRefs(aside, branchForWorkspaceId(path.basename(path.dirname(repoDir))));
+        await this.copyIgnoredFiles(aside, repoDir);
+        await fs.rename(aside, converted);
+      } catch (err) {
+        await this.undoConversion(repoDir, aside);
+        throw err;
+      }
+      await this.removeConvertedClone(branchForWorkspaceId(path.basename(path.dirname(repoDir))), converted);
+      return;
+    }
+    await fs.rm(repoDir, { recursive: true, force: true });
+    await this.repository.prune().catch(() => undefined);
+    await fs.rename(aside, repoDir);
+  }
+
 
   /**
    * Whether the configured repository holds history this clone has too —
@@ -733,7 +1058,7 @@ export class KbStartupRunner {
    * a wrong true would push a stranger's commits into the configured
    * repository.
    */
-  private async sharesHistoryWithConfigured(repoDir: string, configured: string): Promise<boolean> {
+  private async sharesHistoryWithConfigured(repoDir: string, configured: string, ours = 'HEAD'): Promise<boolean> {
     const probe = 'refs/hexis-probe';
     let theirs: string[] = [];
     try {
@@ -746,7 +1071,7 @@ export class KbStartupRunner {
       // One question for all of them: a common ancestor of HEAD and ANY of
       // their branches is a common ancestor of HEAD and their merge. Capped,
       // so a remote with thousands of branches cannot outgrow a command line.
-      await git(this.opts.gitRunner, repoDir, ['merge-base', 'HEAD', ...theirs.slice(0, 200)]);
+      await git(this.opts.gitRunner, repoDir, ['merge-base', ours, ...theirs.slice(0, 200)]);
       return true;
     } catch {
       return false;
@@ -800,8 +1125,13 @@ export class KbStartupRunner {
     const workspaceDir = path.join(this.opts.workspacesRoot, workspaceIdForBranch(branch));
     const repoDir = path.join(workspaceDir, this.opts.kbDirName);
     for (let pass = 1; ; pass++) {
-      const hasGit = await fs.access(path.join(repoDir, '.git')).then(() => true, () => false);
-      if (hasGit && (await this.hasCommit(repoDir))) return this.updateClone(branch, repoDir);
+      // A worktree whose link to the repository is broken has a `.git` and is
+      // no working copy: it is set aside as an unfinished clone is, below.
+      const shape = await workingCopyShape(repoDir);
+      const hasGit = shape !== 'none';
+      if ((shape === 'worktree' || shape === 'clone') && (await this.hasCommit(repoDir))) {
+        return this.updateClone(branch, repoDir, shape === 'worktree');
+      }
       if (pass > PASSES_OVER_ONE_WORKING_COPY) {
         throw new Error('it kept changing while this start was preparing it; something else is working on it');
       }
@@ -862,8 +1192,9 @@ export class KbStartupRunner {
   }
 
   private async isUnfinishedClone(repoDir: string): Promise<boolean> {
-    const hasGit = await fs.access(path.join(repoDir, '.git')).then(() => true, () => false);
-    return hasGit && !(await this.hasCommit(repoDir));
+    const shape = await workingCopyShape(repoDir);
+    if (shape === 'broken') return true;
+    return shape !== 'none' && !(await this.hasCommit(repoDir));
   }
 
   /**
@@ -882,7 +1213,11 @@ export class KbStartupRunner {
     const giveUpAt = Date.now() + Math.max(this.opts.gitRunner.defaultTimeoutMs, LONGEST_CLONE_MS) + quietMs;
     for (;;) {
       if (!(await this.isUnfinishedClone(repoDir))) return false;
-      const lastWrite = await newestChangeUnder(path.join(repoDir, '.git'));
+      // A clone writes under its `.git` folder; a worktree being added
+      // writes its checkout, its `.git` being a file.
+      const dotGit = path.join(repoDir, '.git');
+      const watched = (await fs.stat(dotGit).then((s) => s.isDirectory(), () => false)) ? dotGit : repoDir;
+      const lastWrite = await newestChangeUnder(watched);
       const quietFor = Date.now() - lastWrite;
       if (quietFor >= quietMs) return true;
       if (Date.now() > giveUpAt) throw new Error('an unfinished clone at its path is still being written to');
@@ -914,16 +1249,21 @@ export class KbStartupRunner {
 
   private async cloneFresh(branch: string, workspaceDir: string, repoDir: string): Promise<string> {
     await fs.mkdir(workspaceDir, { recursive: true });
-    // Only what cannot be a clone is cleared out of the way: a folder that
-    // gained a `.git` since the caller looked is somebody's clone, and git
+    // Only what cannot be a working copy is cleared out of the way: a folder
+    // that gained a `.git` since the caller looked is somebody's, and git
     // refuses it below rather than this removing it.
     if (!(await fs.access(path.join(repoDir, '.git')).then(() => true, () => false))) {
       await fs.rm(repoDir, { recursive: true, force: true });
     }
-    await git(this.opts.gitRunner, workspaceDir, ['clone', '-b', branch, this.opts.kbRepoUrl(), repoDir]);
-    // Said as soon as the clone is there, before its configuration: if a
-    // command below fails, the clone stays on disk, and the retry finds it
-    // and never comes back through here.
+    // A worktree of the one repository, which is made (and fetched) by the
+    // first branch that needs it: no history is copied per branch. The
+    // repository carries the identity, the long-paths setting and the
+    // credential helper for every worktree.
+    // The phase opens every branch: the repository's one fetch in the window
+    // brought them all, so each add reads it instead of asking the remote
+    // for its branch again. A fetch that failed leaves the add to ask.
+    await this.repository.fetch(this.fetchWindow());
+    await this.repository.addWorktree(branch, repoDir, { fetchedSince: this.fetchedSince() });
     try {
       this.opts.onCloneCreated?.(workspaceIdForBranch(branch));
     } catch (err) {
@@ -931,13 +1271,44 @@ export class KbStartupRunner {
         detail: this.redact(err instanceof Error ? err.message : String(err)),
       });
     }
-    await git(this.opts.gitRunner, repoDir, ['config', 'core.longpaths', 'true']);
-    await stampIdentity(this.opts.gitRunner, repoDir);
     return repoDir;
   }
 
-  private async updateClone(branch: string, repoDir: string): Promise<string> {
-    await git(this.opts.gitRunner, repoDir, ['fetch', 'origin', branch]);
+  /**
+   * The earliest a fetch of the repository may have started and still count
+   * for this run: never before its listing, never older than the window. An
+   * instant, so the repository compares it when it gets the reservation and
+   * time spent waiting for it does not age the fetch out.
+   */
+  private fetchedSince(): number {
+    return Math.max(this.listedAt, Date.now() - STARTUP_FETCH_WINDOW_MS);
+  }
+
+  private fetchWindow(): FetchOptions {
+    return { maxAgeMs: STARTUP_FETCH_WINDOW_MS, fetchedSince: this.fetchedSince() };
+  }
+
+  private async updateClone(branch: string, repoDir: string, worktree = false): Promise<string> {
+    if (worktree) {
+      // ONE fetch for every worktree the phase visits, within the window: the
+      // repository's. The phase is fail-closed, so a failed fetch stops it
+      // with git's words, as the clone's own fetch did.
+      if (!(await this.repository.fetch(this.fetchWindow()))) {
+        const raw = `git fetch origin failed: ${String(this.repository.lastFetchFailure() ?? 'unknown failure')}`;
+        throw new ClassifiedFailure(this.redact(raw), classifyGitFailure(raw));
+      }
+      // The branch was listed before the fetch and deleted on the remote
+      // since: nothing to move the worktree to. Its commits stay where they
+      // are, reachable from its branch, as any other branch's do.
+      if (!(await this.hasRemoteBranch(repoDir, branch))) {
+        this.goneFromRemote.add(branch);
+        startupLog.warn(`branch "${branch}" was deleted on the remote during this start: its working copy is left as it is`);
+        return repoDir;
+      }
+      this.goneFromRemote.delete(branch);
+    } else {
+      await git(this.opts.gitRunner, repoDir, ['fetch', 'origin', branch]);
+    }
     const local = (await git(this.opts.gitRunner, repoDir, ['rev-parse', 'HEAD'])).trim();
     const remote = (await git(this.opts.gitRunner, repoDir, ['rev-parse', `origin/${branch}`])).trim();
     if (local !== remote) {
@@ -950,6 +1321,22 @@ export class KbStartupRunner {
     return repoDir;
   }
 
+  /**
+   * Whether the repository's remote-tracking ref for `branch` exists. False
+   * only when git answered that it does not (`--verify --quiet`, exit 1);
+   * any other failure is thrown.
+   */
+  private async hasRemoteBranch(repoDir: string, branch: string): Promise<boolean> {
+    try {
+      await git(this.opts.gitRunner, repoDir, ['rev-parse', '--quiet', '--verify', `refs/remotes/origin/${branch}^{commit}`]);
+      return true;
+    } catch (err) {
+      const ran = err instanceof Error ? err.cause : undefined;
+      if (ran instanceof GitRunError && !ran.timedOut && ran.exitCode === 1) return false;
+      throw err;
+    }
+  }
+
   /**
    * Whether the repository at `repoDir` has a commit checked out. False for a
    * clone that was cut short.
@@ -975,8 +1362,14 @@ export class KbStartupRunner {
   /** One commit per dirty branch; push; the replica carve-out on rejection. */
   private async finalize(h: BranchHandle): Promise<void> {
     if (!h.dirty) return;
+    if (this.goneFromRemote.has(h.name)) {
+      startupLog.warn(`${h.name}: deleted on the remote during this start; the phase's changes are not committed or pushed`);
+      return;
+    }
     const repoDir = await h.repoDir();
-    await stampIdentity(this.opts.gitRunner, repoDir);
+    // A worktree's identity is the repository's, stamped when it was made; a
+    // config write from here would contend with every other worktree's.
+    if ((await workingCopyShape(repoDir)) !== 'worktree') await stampIdentity(this.opts.gitRunner, repoDir);
     // Drop any PRE-EXISTING index state first (a crashed tool may have left
     // edits staged): `git commit` publishes the whole index, and the phase
     // must commit exactly its own staged set. The edits stay in the working

package/src/modules/workspace/startup/steps/__tests__/steps.test.ts

@@ -5,7 +5,6 @@ import { promisify } from 'node:util';
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { KbStartupRunner } from '../../kb-startup-runner.js';
 import { NodeGitRunner } from '../../../../workflow/git/node-git-runner.js';
 import type { OnServerStart, ServerStartContext, StepResult } from '../../on-server-start.js';
 import { GroupsToPluginsStep } from '../groups-to-plugins.step.js';
@@ -21,6 +20,7 @@ import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
 import { renderTemplateText } from '../template-source.js';
 import { TOOL_PREFIX_LINE, composeAgentInstructions, platformInstructions } from '../../../../agent-instructions/index.js';
 import { testKbContext } from '../../../../../__tests__/kb-context.js';
+import { newKbStartupRunner } from '../../../../../__tests__/workspace-service.js';
 
 const execFileAsync = promisify(execFile);
 
@@ -102,7 +102,7 @@ async function seedUpstream(
 }
 
 function makeRunner(steps: OnServerStart[], templateDir: string = TEMPLATE_DIR) {
-  return new KbStartupRunner({
+  return newKbStartupRunner({
     gitRunner: new NodeGitRunner(),
     kbRepoUrl: () => upstream,
     workspacesRoot,
@@ -781,7 +781,8 @@ describe('TemplateFilesStep: the guide copies earlier releases wrote', () => {
 
     const dir = await checkout(DEFAULT_BRANCH);
     expect((await fs.lstat(path.join(dir, 'AGENTS.md'))).isSymbolicLink()).toBe(true);
-    expect(await fs.readlink(path.join(dir, 'AGENTS.md'))).toBe('conventions/ours.md');
+    // Windows reads the link back with its own separator.
+    expect((await fs.readlink(path.join(dir, 'AGENTS.md'))).replace(/\\/g, '/')).toBe('conventions/ours.md');
     expect(norm(await fs.readFile(path.join(dir, 'conventions/ours.md'), 'utf8'))).toBe(MANAGED_GUIDE_COPY);
   });
 });