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

package/dist/modules/workspace/startup/kb-startup-runner.js

@@ -5,13 +5,16 @@ 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 { git, lsRemoteHeads, stampIdentity, withTempDir } from './kb-git.js';
 import { GitRunError } from '../../../shared/git.contract.js';
 import { ClassifiedFailure, classifyGitFailure, failureOf, gitFailure, } 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 } from '../kb-repository.js';
+import { fetchInstant } from '../fetch-instant.js';
+import { assertValidBranchName } from '../../kb-fs/branch-name.js';
 const UNFINISHED_CLONE_QUIET_MS = 60_000;
 /** The floor `kb-git.ts` gives a startup git command, a clone included. */
 const LONGEST_CLONE_MS = 600_000;
@@ -21,9 +24,15 @@ 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;
-/** Whether `git clone` failed because its destination already held something, having written nothing. */
+/**
+ * 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` or `git worktree add` failed because its destination already held something, having written nothing. */
 function refusedAnOccupiedFolder(err) {
-    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);
 }
 /**
  * When anything under `dir` was last written, as a time in milliseconds. Now,
@@ -104,8 +113,23 @@ export function bootMaySurvive(err) {
 }
 export class KbStartupRunner {
     opts;
+    repository;
+    /**
+     * 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.
+     */
+    goneFromRemote = new Set();
+    /**
+     * 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`).
+     */
+    listedAt = 0;
     constructor(opts) {
         this.opts = opts;
+        this.repository = opts.repository;
     }
     /** The run in progress, so two invokers share one rather than racing clones. */
     inFlight = null;
@@ -283,11 +307,19 @@ export class KbStartupRunner {
                     'process listings. Remove them from the URL and configure the token via the setup ' +
                     '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) {
                 const started = Date.now();
@@ -338,6 +370,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
@@ -517,21 +554,35 @@ export class KbStartupRunner {
      */
     async reconcileClonesWithConfiguredRepository() {
         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;
         try {
             entries = await fs.readdir(this.opts.workspacesRoot, { withFileTypes: true });
         }
-        catch {
-            return; // no workspaces yet
+        catch (err) {
+            const code = err.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;
@@ -565,6 +616,264 @@ 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.
+     */
+    async reconcileRepositoryWithConfigured(configured, dest) {
+        // 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 () => {
+            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 = [];
+        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.
+     */
+    async convertLegacyClones() {
+        let entries;
+        try {
+            entries = await fs.readdir(this.opts.workspacesRoot, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        let converted = 0;
+        const kept = [];
+        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;
+            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(', ')})` : '') +
+                '.');
+        }
+    }
+    async convertOneClone(branch, repoDir, aside, converted) {
+        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.
+     */
+    async importLocalRefs(cloneDir, branch) {
+        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. */
+    async undoConversion(repoDir, aside) {
+        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.
+     */
+    async removeConvertedClone(branch, converted) {
+        await fs.rm(converted, { recursive: true, force: true }).catch((err) => {
+            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.
+     */
+    async copyIgnoredFiles(from, to) {
+        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. */
+    async finishInterruptedConversion(repoDir, aside, converted) {
+        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 —
      * asked of git, not guessed from the two addresses. The configured
@@ -576,7 +885,7 @@ export class KbStartupRunner {
      * a wrong true would push a stranger's commits into the configured
      * repository.
      */
-    async sharesHistoryWithConfigured(repoDir, configured) {
+    async sharesHistoryWithConfigured(repoDir, configured, ours = 'HEAD') {
         const probe = 'refs/hexis-probe';
         let theirs = [];
         try {
@@ -590,7 +899,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 {
@@ -644,9 +953,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');
             }
@@ -709,8 +1022,10 @@ export class KbStartupRunner {
         await this.announceDiscarded(id);
     }
     async isUnfinishedClone(repoDir) {
-        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));
     }
     /**
      * Wait until nothing under the unfinished clone's `.git` has been written
@@ -729,7 +1044,11 @@ export class KbStartupRunner {
         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;
@@ -763,16 +1082,21 @@ export class KbStartupRunner {
     }
     async cloneFresh(branch, workspaceDir, repoDir) {
         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));
         }
@@ -781,12 +1105,42 @@ 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;
     }
-    async updateClone(branch, repoDir) {
-        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.
+     */
+    fetchedSince() {
+        return Math.max(this.listedAt, Date.now() - STARTUP_FETCH_WINDOW_MS);
+    }
+    fetchWindow() {
+        return { maxAgeMs: STARTUP_FETCH_WINDOW_MS, fetchedSince: this.fetchedSince() };
+    }
+    async updateClone(branch, repoDir, worktree = false) {
+        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) {
@@ -798,6 +1152,23 @@ 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.
+     */
+    async hasRemoteBranch(repoDir, branch) {
+        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.
@@ -825,8 +1196,15 @@ export class KbStartupRunner {
     async finalize(h) {
         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