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

package/dist/modules/workspace/kb-repository.js

@@ -0,0 +1,811 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { logger } from '../../shared/logging.js';
+import { isAbsence } from '../../shared/fs.contract.js';
+import { redactSecret, urlQuerySecrets } from '../../shared/redact-secret.js';
+import { fetchInstant } from './fetch-instant.js';
+import { readGitfile } from '../kb-fs/index.js';
+import { cloneCredentialConfigArgs, cloneTrackingConfigArgs, ORIGIN_FETCH_REFSPEC, SAFE_IMPLICIT_FETCH_ARGS, } from '../kb-fs/clone-config.js';
+const log = logger('kb-repository');
+/**
+ * ONE repository per knowledge base, and every branch workspace a worktree of
+ * it.
+ *
+ * A branch workspace used to be a full clone: every object of the history
+ * once per branch, and a fetch per branch. A workspace is only ever checked
+ * out on its own branch and never switches, so almost all of that was the
+ * same history copied over and over (142 branches, 60 GB, on 2026-10-14).
+ * Git's own answer to "many checkouts, one history" is a worktree: this
+ * repository holds the objects, the remote-tracking refs and each branch's
+ * local ref, and `<workspacesRoot>/<branch id>/<kb folder>` — the path a
+ * clone had — is a worktree of it. Its `.git` is a FILE pointing here.
+ *
+ * Bare, so no branch is checked out in the repository itself (a non-bare
+ * clone would hold the default branch, which is one of the workspaces), and
+ * with no local branches at all until a worktree adds one: the remote's
+ * branches arrive under `refs/remotes/origin/*`, exactly where a clone keeps
+ * them, so `origin/<branch>` reads the same from a worktree as from a clone.
+ *
+ * It lives OUTSIDE the workspaces root, so the orphan sweep (which removes
+ * every folder there that is not a known branch's) never sees it.
+ *
+ * Git was built for many worktrees of one repository and protects what they
+ * share with its own locks: one per ref while it is written, one for
+ * `packed-refs` (which git waits for, `core.packedRefsTimeout`), one per
+ * worktree's index, objects written to a temp file and renamed into place,
+ * and a worktree being added marked locked until it is. So git operations
+ * in two worktrees run side by side here, as two developers' worktrees do,
+ * under nothing but the per-workspace mutex the git layer always held.
+ *
+ * What git does NOT wait for is its one config file — a second writer is
+ * refused, not queued — and what nothing in git serializes is the making of
+ * the repository and the moving of its folders. Those three run as the
+ * repository's one administrator, {@link exclusive}: the only lock this
+ * class adds.
+ *
+ * Automatic garbage collection is off (`gc.auto 0`): a commit in one
+ * worktree would otherwise collect beside every other worktree's work. The
+ * startup phase runs {@link maintain} once per boot instead, when nothing
+ * is served.
+ */
+/** A first fetch of a large knowledge base takes minutes; the floor under its deadline. */
+const FIRST_FETCH_TIMEOUT_MS = 600_000;
+/**
+ * Git waits this long for another process's `packed-refs.lock` before failing
+ * (the default is one second). A fetch that prunes and a branch delete in
+ * another worktree both rewrite `packed-refs`, which is now one file for every
+ * workspace.
+ */
+const PACKED_REFS_TIMEOUT_MS = '10000';
+/** Written into the repository last, once its first fetch has landed — see `exists`. */
+const READY_MARKER = 'hexis-repository-ready';
+/** Where a converted clone's stash and other local refs are kept, per workspace (see `importLocalRefs`). */
+export const CONVERTED_REFS = 'refs/kb-converted';
+/** Fallback committer identity; every workflow commit overrides it with `--author`. */
+const BOT_NAME = 'Bevel Workflow';
+const BOT_EMAIL = 'bevel-workflow@bevel.software';
+/**
+ * Where the repository is: `<root>/<kb folder>.git`, under `override` when the
+ * composition root names one (a folder on a persistent volume beside the
+ * workspaces root), else a folder next to the workspaces root named after it.
+ *
+ * The fallback is derived from the root's own name, so two workspaces roots
+ * that share a parent (every suite's temporary roots) never share a repository.
+ */
+export function repositoryDirFor(workspacesRoot, kbDirName, override) {
+    const root = override ?? `${path.resolve(workspacesRoot)}.repository`;
+    return path.join(root, `${kbDirName}.git`);
+}
+export async function workingCopyShape(checkoutDir) {
+    const dotGit = path.join(checkoutDir, '.git');
+    let stat;
+    try {
+        stat = await fs.stat(dotGit);
+    }
+    catch (err) {
+        if (isAbsence(err))
+            return 'none';
+        throw err;
+    }
+    if (stat.isDirectory())
+        return 'clone';
+    const gitdir = await readGitfile(dotGit);
+    if (gitdir === null)
+        return 'broken';
+    let held;
+    try {
+        held = await fs.stat(gitdir);
+    }
+    catch (err) {
+        // Only absence shows the worktree gone; EACCES or EIO shows nothing, and a
+        // `broken` answer would have the checkout recreated over it.
+        if (isAbsence(err))
+            return 'broken';
+        throw err;
+    }
+    return held.isDirectory() ? 'worktree' : 'broken';
+}
+/**
+ * Replace the contents of a file that exists, keeping the file. Git for
+ * Windows marks a worktree's `.git` file hidden, and Windows refuses to
+ * re-create a hidden file (`fs.writeFile` opens with `w`: EPERM) — so the
+ * file is opened as it is and truncated instead.
+ */
+async function rewriteFile(file, text) {
+    const handle = await fs.open(file, 'r+');
+    try {
+        await handle.truncate(0);
+        await handle.write(text, 0);
+    }
+    finally {
+        await handle.close();
+    }
+}
+export class KbRepository {
+    dir;
+    kbRepoUrl;
+    gitRunner;
+    /** The administrator's queue: `exclusive` sections run one after another, in call order. */
+    admin = Promise.resolve();
+    /** See the contract: the repository's one administrator for `fn`'s duration. Never nested. */
+    async exclusive(fn) {
+        const next = this.admin.catch(() => undefined).then(fn);
+        this.admin = next;
+        return next;
+    }
+    /** When the last fetch succeeded, and when the last attempt failed. */
+    lastSuccessAt = 0;
+    lastFailureAt = 0;
+    lastOk = null;
+    inFlightFetch = null;
+    /** When the fetch in flight started: a caller that needs one from `fetchedSince` on joins only a later one. */
+    inFlightStartedAt = 0;
+    /**
+     * Bumped whenever the repository is taken away (set aside): a fetch that was
+     * in flight for the one that went must not stamp its result on the new one.
+     */
+    generation = 0;
+    /** The credential fingerprint last stamped into the repository's config, this process. */
+    stampedCredentials = null;
+    /** Whether this process has stamped the repository's own configuration yet. */
+    configStamped = false;
+    constructor(opts) {
+        this.dir = path.resolve(opts.dir);
+        this.kbRepoUrl = opts.kbRepoUrl;
+        this.gitRunner = opts.gitRunner;
+    }
+    redact(text) {
+        return redactSecret(text, [this.gitRunner.credentials.token(), ...urlQuerySecrets(this.kbRepoUrl())]);
+    }
+    async git(args, timeoutMs) {
+        const { stdout } = await this.gitRunner.run(this.dir, args, timeoutMs ? { timeoutMs } : undefined);
+        return stdout;
+    }
+    /**
+     * Whether the repository is on disk and FINISHED: a bare repository whose
+     * first fetch landed. The marker is written last, so a repository whose
+     * making was cut short (a crash, a full disk) is not taken for one.
+     */
+    async exists() {
+        try {
+            await fs.access(path.join(this.dir, READY_MARKER));
+            return true;
+        }
+        catch (err) {
+            // Only absence is "not there". A marker that could not be read (EACCES,
+            // EIO, a process out of file descriptors) has shown nothing, and a false
+            // answer would have `ensureHeld` clear a repository that is whole, with
+            // every worktree's unpushed commits in it.
+            if (isAbsence(err))
+                return false;
+            throw err;
+        }
+    }
+    /**
+     * Make sure the repository exists and has been fetched at least once; create
+     * it when it does not. As the administrator. Throws when it cannot be
+     * created or its first fetch fails — with git's words, redacted.
+     */
+    async ensure() {
+        await this.exclusive(() => this.ensureHeld());
+    }
+    async ensureHeld() {
+        if (await this.exists()) {
+            await this.stampConfigIfNeeded();
+            return;
+        }
+        const url = this.kbRepoUrl().trim();
+        if (url === '')
+            throw new Error('The knowledge-base repository address is not configured.');
+        // Made in place, and marked finished only once it has the remote's refs.
+        // What a making cut short left here holds no worktree (none is added
+        // before the marker) and nothing that is not on the remote: it is
+        // cleared and made again.
+        await fs.rm(this.dir, { recursive: true, force: true });
+        await fs.mkdir(this.dir, { recursive: true });
+        let fetchedAt = fetchInstant();
+        let credentialsStamped = true;
+        try {
+            await this.gitRunner.run(this.dir, ['init', '--bare', '--quiet', this.dir]);
+            for (const args of this.configArgs(url))
+                await this.gitRunner.run(this.dir, args);
+            // The helper's write is not what makes the repository: one that failed
+            // is tried again by `refreshCredentials`, which is why it is not
+            // recorded as stamped below.
+            for (const args of cloneCredentialConfigArgs(this.gitRunner.credentials)) {
+                await this.gitRunner.run(this.dir, args).catch((err) => {
+                    if (!(args.includes('--unset-all') && err.exitCode === 5))
+                        credentialsStamped = false;
+                });
+            }
+            fetchedAt = fetchInstant();
+            await this.gitRunner.run(this.dir, ['fetch', '--prune', '--no-write-fetch-head', '--quiet', 'origin'], {
+                timeoutMs: Math.max(this.gitRunner.defaultTimeoutMs, FIRST_FETCH_TIMEOUT_MS),
+            });
+            await fs.writeFile(path.join(this.dir, READY_MARKER), 'The knowledge base repository every branch workspace is a worktree of. Made by Hexis.\n');
+        }
+        catch (err) {
+            await fs.rm(this.dir, { recursive: true, force: true }).catch(() => undefined);
+            throw err;
+        }
+        this.configStamped = true;
+        this.stampedCredentials = credentialsStamped ? this.credentialFingerprint() : null;
+        this.noteFetched(true, fetchedAt);
+        log.info(`created the knowledge-base repository at ${this.dir}`);
+    }
+    /** The repository's own configuration — what every worktree of it reads. */
+    configArgs(url) {
+        return [
+            ['config', 'remote.origin.url', url],
+            ['config', '--replace-all', 'remote.origin.fetch', ORIGIN_FETCH_REFSPEC],
+            // A KB has paths over 260 characters; without this a Windows checkout drops them.
+            ['config', 'core.longpaths', 'true'],
+            ['config', 'core.packedRefsTimeout', PACKED_REFS_TIMEOUT_MS],
+            // No automatic collection: it would run inside whichever worktree's
+            // commit tripped it, beside every other worktree's work. The startup
+            // phase collects once per boot instead (`maintain`).
+            ['config', 'gc.auto', '0'],
+            // See `cloneTrackingConfigArgs`: an automatic gc forked into the
+            // background becomes a zombie under a node server.
+            ['config', 'gc.autoDetach', 'false'],
+            ['config', 'user.name', BOT_NAME],
+            ['config', 'user.email', BOT_EMAIL],
+        ];
+    }
+    credentialFingerprint() {
+        const { credentials } = this.gitRunner;
+        return `${credentials.username()}::${credentials.token() ? '1' : '0'}`;
+    }
+    /**
+     * Stamp the repository's configuration once per process, and its credential
+     * helper again whenever the deployment's credential changed — once for every
+     * worktree, since they all read this one config. Never throws: a stamp that
+     * failed leaves the repository as usable as it was, and is tried again next
+     * time.
+     */
+    async stampConfigIfNeeded() {
+        if (!this.configStamped) {
+            try {
+                // The address is NOT rewritten here: a repository of another address
+                // is set aside, never re-pointed (see `isOfAnotherRepository`).
+                for (const args of this.configArgs('').slice(1))
+                    await this.git(args);
+                this.configStamped = true;
+            }
+            catch (err) {
+                log.warn('could not stamp the knowledge-base repository configuration:', {
+                    detail: this.redact(err instanceof Error ? err.message : String(err)),
+                });
+            }
+        }
+        if (this.stampedCredentials === this.credentialFingerprint())
+            return;
+        let argLists;
+        try {
+            argLists = cloneCredentialConfigArgs(this.gitRunner.credentials);
+        }
+        catch (err) {
+            log.warn('refusing to stamp the credential helper of the knowledge-base repository:', {
+                detail: this.redact(err instanceof Error ? err.message : String(err)),
+            });
+            return;
+        }
+        let stamped = true;
+        for (const args of argLists) {
+            try {
+                await this.git(args);
+            }
+            catch (err) {
+                // `--unset-all` of a helper that is not there exits 5: nothing to do.
+                if (!(args.includes('--unset-all') && err.exitCode === 5))
+                    stamped = false;
+            }
+        }
+        this.stampedCredentials = stamped ? this.credentialFingerprint() : null;
+    }
+    /**
+     * Bring the credential helper into line with the deployment's credential when
+     * it changed since it was last stamped. As the administrator, as every write
+     * to the shared config is. A no-op for a repository not yet made.
+     */
+    async refreshCredentials() {
+        if (this.stampedCredentials === this.credentialFingerprint() && this.configStamped)
+            return;
+        await this.exclusive(async () => {
+            if (await this.exists())
+                await this.stampConfigIfNeeded();
+        });
+    }
+    /**
+     * Run `git config` arguments against the repository's shared configuration
+     * (from a worktree or the repository, it is one file), one writer at a time:
+     * git refuses a second writer while `config.lock` is held rather than
+     * waiting for it.
+     */
+    async writeConfig(cwd, argLists) {
+        await this.exclusive(async () => {
+            for (const args of argLists)
+                await this.gitRunner.run(cwd, args);
+        });
+    }
+    /** See the contract. `gc --auto` decides for itself whether there is enough loose to pack. */
+    async maintain() {
+        try {
+            if (!(await this.exists()))
+                return;
+            await this.git(['-c', 'gc.auto=6700', 'gc', '--auto', '--quiet'], Math.max(this.gitRunner.defaultTimeoutMs, FIRST_FETCH_TIMEOUT_MS));
+        }
+        catch (err) {
+            log.warn('garbage collection of the knowledge-base repository failed; it is tried again at the next start:', {
+                detail: this.redact(err instanceof Error ? err.message : String(err)),
+            });
+        }
+    }
+    /**
+     * `at` for a success is when its fetch STARTED: the refs it wrote are at
+     * least that fresh, and no fresher — a deletion on the remote while it ran
+     * may be missing from them.
+     */
+    noteFetched(ok, at = Date.now()) {
+        this.lastOk = ok;
+        if (ok)
+            this.lastSuccessAt = at;
+        else
+            this.lastFailureAt = at;
+    }
+    /** The last time the repository reached the remote and whether it worked; null before any attempt. */
+    lastContact() {
+        if (this.lastOk === null)
+            return null;
+        return { at: Math.max(this.lastSuccessAt, this.lastFailureAt), ok: this.lastOk };
+    }
+    /** Why the last fetch failed, redacted; null when it did not. For a fail-closed caller's message. */
+    lastFetchFailure() {
+        return this.lastOk === false ? this.lastFailure : null;
+    }
+    lastFailure = null;
+    /**
+     * `git fetch --prune origin` in the repository — ONCE for every workspace.
+     * Throttled by `maxAgeMs` and joined while in flight (ten callers in one
+     * tick share one fetch). Not serialized against the worktrees' own git:
+     * a fetch writes remote-tracking refs and packs, which git locks itself.
+     * Answers whether the remote-tracking refs are provably fresh: this call's
+     * fetch (or the one it joined) succeeded, or one succeeded within the
+     * window. Never throws; a caller that must not act on stale refs reads the
+     * answer.
+     */
+    async fetch(opts) {
+        const now = Date.now();
+        if (!opts.force &&
+            now - this.lastSuccessAt < opts.maxAgeMs &&
+            (opts.fetchedSince === undefined || this.lastSuccessAt > opts.fetchedSince)) {
+            return true;
+        }
+        if (this.inFlightFetch) {
+            if (opts.fetchedSince === undefined || this.inFlightStartedAt > opts.fetchedSince)
+                return this.inFlightFetch;
+            // Started before the caller's instant: its refs may be older than what
+            // the caller must see (a branch deleted since). Waited for, then a
+            // fetch after the instant is joined or run: forced, so neither the
+            // waited-for one's success nor its failure (the backoff) stands in for
+            // it. Any fetch in flight now started after the instant, so this ends.
+            await this.inFlightFetch;
+            return this.fetch({ ...opts, force: true });
+        }
+        if (!opts.force && opts.failureBackoffMs && now - this.lastFailureAt < opts.failureBackoffMs) {
+            return false;
+        }
+        const generation = this.generation;
+        let startedAt = fetchInstant();
+        const promise = (async () => {
+            startedAt = fetchInstant();
+            // A repository not made yet is made here, which fetches it once: that
+            // first fetch is this one.
+            const existed = await this.exists();
+            await this.ensure();
+            if (!existed)
+                return;
+            await this.git([
+                // A transfer that stalls below 1 KB/s for ten seconds is abandoned,
+                // so a hung host cannot park every workspace behind it.
+                '-c', 'http.lowSpeedLimit=1000',
+                '-c', 'http.lowSpeedTime=10',
+                ...SAFE_IMPLICIT_FETCH_ARGS,
+            ]);
+        })()
+            .then(() => {
+            // When this fetch made the repository, ensureHeld() already stamped its
+            // own (later) first-fetch start: keep that one.
+            if (generation === this.generation)
+                this.noteFetched(true, Math.max(startedAt, this.lastSuccessAt));
+            return true;
+        }, (err) => {
+            if (generation === this.generation) {
+                this.noteFetched(false);
+                this.lastFailure = this.redact(err instanceof Error ? err.message : String(err));
+            }
+            log.warn('git fetch origin failed:', {
+                detail: this.redact(err instanceof Error ? err.message : String(err)),
+            });
+            return false;
+        })
+            .finally(() => {
+            if (this.inFlightFetch === promise)
+                this.inFlightFetch = null;
+        });
+        this.inFlightFetch = promise;
+        this.inFlightStartedAt = startedAt;
+        return promise;
+    }
+    /**
+     * Forget what this process knows about the repository — it was set aside,
+     * and the next use makes a fresh one.
+     */
+    forget() {
+        this.generation++;
+        this.lastSuccessAt = 0;
+        this.lastFailureAt = 0;
+        this.lastOk = null;
+        this.inFlightFetch = null;
+        this.configStamped = false;
+        this.stampedCredentials = null;
+    }
+    async revParse(ref) {
+        try {
+            return (await this.git(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`])).trim() || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async isAncestor(ancestor, of) {
+        try {
+            await this.git(['merge-base', '--is-ancestor', ancestor, of]);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Add the worktree of `branch` at `checkoutDir`. Copies no history: the
+     * repository already has it, and is fetched first when the remote's branch
+     * is not known to it yet.
+     *
+     * The branch's local ref is created from `origin/<branch>`, tracking it. A
+     * local ref already there (a converted clone's tip, a worktree that was lost
+     * with commits the remote lacks) is KEPT when it holds commits the remote
+     * does not have, and fast-forwarded to the remote when it is behind.
+     *
+     * A branch the remote does not have fails with git's own words for a clone
+     * of it ("Remote branch … not found in upstream origin"), so the callers
+     * that tell a deleted branch from one that never existed read it as they
+     * read a clone's failure — unless `allowLocalOnly` (a converted clone whose
+     * branch was never pushed) and the local ref exists.
+     *
+     * `keepLocalTip` (a conversion) leaves a local ref that is behind the
+     * remote where it is: the worktree comes up at the clone's own tip, and the
+     * phase's own update moves it on, as it moved the clone.
+     *
+     * `fetchedSince` (the startup phase, opening every branch) skips asking
+     * the remote when the repository's own fetch succeeded, starting after it,
+     * and already has `origin/<branch>`: that fetch brought every branch, so
+     * opening a hundred branches costs one fetch, not a hundred. A branch it
+     * does not know yet is asked for as usual.
+     */
+    async addWorktree(branch, checkoutDir, opts = {}) {
+        await this.ensure();
+        {
+            // The remote is ASKED for the branch, as a clone of it asked: the
+            // repository's tracking ref may be from before the branch moved, or was
+            // deleted, on the host. One branch, not the whole remote. Not as the
+            // administrator: a fetch may take a while, and git locks what it writes.
+            let missing = false;
+            const fresh = opts.fetchedSince !== undefined &&
+                this.lastSuccessAt > 0 &&
+                this.lastSuccessAt > opts.fetchedSince &&
+                (await this.revParse(`refs/remotes/origin/${branch}`)) !== null;
+            if (!fresh) {
+                try {
+                    await this.git(['fetch', '--no-write-fetch-head', '--quiet', 'origin',
+                        `+refs/heads/${branch}:refs/remotes/origin/${branch}`]);
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    if (!/couldn't find remote ref/i.test(message))
+                        throw err;
+                    missing = true;
+                    // What the repository still says about it is stale.
+                    await this.git(['update-ref', '-d', `refs/remotes/origin/${branch}`]).catch(() => undefined);
+                }
+            }
+            // As the administrator, from reading the local ref to the config
+            // writes: the worktree list is the one thing git does not lock (a prune
+            // beside another branch's `worktree add` can take the entry being
+            // made), `worktree add --track` writes the shared config, which git
+            // refuses a second writer of, and a `removeWorktree` queued before this
+            // section deletes the branch's local ref — read here, it is the ref
+            // the add uses, not one read before that removal and gone by then.
+            await this.exclusive(async () => {
+                const local = await this.revParse(`refs/heads/${branch}`);
+                if (missing && !(opts.allowLocalOnly && local !== null)) {
+                    throw new Error(`Remote branch ${branch} not found in upstream origin`);
+                }
+                await fs.mkdir(path.dirname(checkoutDir), { recursive: true });
+                // A registration left behind by a folder deleted without git (a crash,
+                // an operator) would make git refuse the path, or the branch, as taken.
+                await this.git(['worktree', 'prune']);
+                if (local === null) {
+                    await this.git(['worktree', 'add', '--quiet', '--track', '-b', branch, checkoutDir, `refs/remotes/origin/${branch}`]);
+                }
+                else {
+                    const remote = missing ? null : await this.revParse(`refs/remotes/origin/${branch}`);
+                    if (!opts.keepLocalTip && remote !== null && local !== remote && (await this.isAncestor(local, remote))) {
+                        await this.git(['update-ref', `refs/heads/${branch}`, remote, local]);
+                    }
+                    await this.git(['worktree', 'add', '--quiet', checkoutDir, branch]);
+                }
+                // The branch tracks `origin/<branch>`, exactly one fetch refspec and
+                // one upstream ref, as a fresh clone of it would.
+                for (const args of cloneTrackingConfigArgs(branch))
+                    await this.git(args);
+            });
+        }
+    }
+    /**
+     * Remove the worktree at `checkoutDir` and prune it from the repository,
+     * with its branch's local ref: deleting a workspace takes what a deleted
+     * clone took. The repository's objects and every other worktree are left
+     * exactly as they were. A folder git will not remove (it is not a worktree
+     * any more, or is locked) is deleted by hand, then pruned.
+     */
+    async removeWorktree(checkoutDir, branch) {
+        if (!(await this.exists())) {
+            await fs.rm(checkoutDir, { recursive: true, force: true });
+            return;
+        }
+        // As the administrator, the branch delete included: the worktree list
+        // is the repository's to serialize (see `addWorktree`), the delete
+        // removes the branch's section from the shared config, and an
+        // `addWorktree` of the same branch must find the ref either there or
+        // gone, not read it and then lose it.
+        await this.exclusive(async () => {
+            await this.git(['worktree', 'remove', '--force', '--force', checkoutDir]).catch(async () => {
+                await fs.rm(checkoutDir, { recursive: true, force: true });
+            });
+            await this.git(['worktree', 'prune']);
+            await this.git(['branch', '-D', '--', branch]).catch(() => undefined);
+        });
+    }
+    /**
+     * After worktree folders were deleted by hand (the orphan sweep): prune them
+     * from the repository and drop their branches' local refs. A branch still
+     * checked out in a worktree that exists is refused by git and kept.
+     */
+    async forgetWorktrees(branches) {
+        if (!(await this.exists()))
+            return;
+        // As the administrator, prune and deletes together: the worktree list is
+        // the repository's to serialize, and a branch delete writes the shared
+        // config (see `removeWorktree`).
+        await this.exclusive(async () => {
+            await this.git(['worktree', 'prune']);
+            for (const branch of branches) {
+                if ((await this.revParse(`refs/heads/${branch}`)) === null)
+                    continue;
+                await this.git(['branch', '-D', '--', branch]).catch(() => undefined);
+            }
+        });
+    }
+    /**
+     * `git worktree prune`: forget worktrees whose folders are gone. As the
+     * administrator: a prune beside a `worktree add` can take the entry being
+     * made, before git has marked it as in the making.
+     */
+    async prune() {
+        if (!(await this.exists()))
+            return;
+        await this.exclusive(() => this.git(['worktree', 'prune']));
+    }
+    /** The folders of the repository's worktrees, as git lists them. */
+    async listWorktrees() {
+        if (!(await this.exists()))
+            return [];
+        const out = await this.git(['worktree', 'list', '--porcelain']);
+        const dirs = [];
+        for (const line of out.split('\n')) {
+            if (!line.startsWith('worktree '))
+                continue;
+            const dir = path.resolve(line.slice('worktree '.length).trim());
+            if (dir !== this.dir)
+                dirs.push(dir);
+        }
+        return dirs;
+    }
+    /**
+     * Bring the tip of `branch` from the full clone at `cloneDir` into the
+     * repository as `refs/heads/<branch>` — its commits the remote lacks
+     * included — without touching the remote. Answers the tip, after checking
+     * the repository now has it.
+     */
+    async importBranch(cloneDir, branch) {
+        await this.ensure();
+        const tip = (await this.gitRunner.run(cloneDir, ['rev-parse', '--verify', `refs/heads/${branch}^{commit}`])).stdout.trim();
+        await this.git(['fetch', '--no-tags', '--no-write-fetch-head', '--quiet', cloneDir,
+            `+refs/heads/${branch}:refs/heads/${branch}`]);
+        const imported = await this.revParse(`refs/heads/${branch}`);
+        if (imported !== tip) {
+            throw new Error(`the repository holds ${imported ?? 'nothing'} for "${branch}" after the import, not ${tip}`);
+        }
+        return tip;
+    }
+    /**
+     * Bring what else the full clone at `cloneDir` holds of its own into the
+     * repository, under `refs/kb-converted/<workspaceId>/`, before the clone
+     * goes: every entry of its stash (`stash/0` the latest), and every local
+     * ref but its own branch's and the remote-tracking ones — other local
+     * branches, tags — that the repository does not already hold with the same
+     * value. Nothing in the clone changes: each object is pushed by its id.
+     * Answers the refs written, after checking the repository holds each at the
+     * clone's value; throws, the clone untouched, when one cannot be written.
+     *
+     * The refs are no workspace's: deleting the branch's workspace leaves them,
+     * and the repository's collection keeps what they reach.
+     */
+    async importLocalRefs(cloneDir, branch, workspaceId) {
+        await this.ensure();
+        const inClone = async (args) => (await this.gitRunner.run(cloneDir, args)).stdout;
+        const namespace = `${CONVERTED_REFS}/${workspaceId}`;
+        const wanted = [];
+        let stashTop = null;
+        for (const line of (await inClone(['for-each-ref', '--format=%(objectname) %(refname)'])).split('\n')) {
+            const [sha, name] = line.trim().split(' ');
+            if (!sha || !name)
+                continue;
+            if (name === 'refs/stash') {
+                stashTop = sha;
+                continue;
+            }
+            if (name.startsWith('refs/remotes/') || name === `refs/heads/${branch}`)
+                continue;
+            if ((await this.refValue(name)) === sha)
+                continue;
+            if (name.startsWith('refs/heads/') && (await this.refValue(`refs/remotes/origin/${name.slice('refs/heads/'.length)}`)) === sha)
+                continue;
+            wanted.push({ sha, dest: `${namespace}/${name.slice('refs/'.length)}` });
+        }
+        if (stashTop !== null) {
+            // Every entry, not only the latest: the older ones are the stash's log.
+            // Git reads a log it cannot open (EACCES, EIO) as an empty one and
+            // exits 0, so the log is read here first: only an absent one means the
+            // stash is its tip alone, and any other failure throws, the clone kept.
+            const logFile = path.resolve(cloneDir, (await inClone(['rev-parse', '--git-path', 'logs/refs/stash'])).trim());
+            let logged;
+            try {
+                logged = (await fs.readFile(logFile, 'utf8')).split('\n').filter((l) => l.trim() !== '').length;
+            }
+            catch (err) {
+                if (!isAbsence(err))
+                    throw err;
+                logged = 0;
+            }
+            const entries = (await inClone(['reflog', 'show', '--format=%H', 'refs/stash']))
+                .split('\n').map((l) => l.trim()).filter(Boolean);
+            if (entries.length !== logged) {
+                throw new Error(`the stash log of ${cloneDir} holds ${logged} entries, git read ${entries.length}`);
+            }
+            if (logged > 0 && entries[0] !== stashTop) {
+                throw new Error(`the stash log of ${cloneDir} starts at ${entries[0]}, not at the stash tip ${stashTop}`);
+            }
+            (logged > 0 ? entries : [stashTop]).forEach((sha, i) => wanted.push({ sha, dest: `${namespace}/stash/${i}` }));
+        }
+        if (wanted.length === 0)
+            return [];
+        await this.gitRunner.run(cloneDir, ['push', '--quiet', '--no-verify', this.dir,
+            ...wanted.map(({ sha, dest }) => `+${sha}:${dest}`)]);
+        for (const { sha, dest } of wanted) {
+            const held = await this.refValue(dest);
+            if (held !== sha)
+                throw new Error(`the repository holds ${held ?? 'nothing'} at ${dest} after the import, not ${sha}`);
+        }
+        return wanted.map(({ dest }) => dest);
+    }
+    /** The object a ref names, as it is (a tag is not peeled), or null. */
+    async refValue(ref) {
+        try {
+            return (await this.git(['rev-parse', '--verify', '--quiet', ref])).trim() || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * The address the repository fetches from, or null when it cannot be read
+     * (no repository, no `origin`).
+     */
+    async originUrl() {
+        if (!(await this.exists()))
+            return null;
+        try {
+            return (await this.git(['config', '--get', 'remote.origin.url'])).trim() || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Re-link a repository and its worktrees that were moved together (set
+     * aside), so `git log` in a moved worktree reads the moved repository.
+     *
+     * Both links are written here rather than left to `git worktree repair`,
+     * which cannot follow a link whose two ends BOTH moved: the worktree's
+     * `.git` file names `<repository>/worktrees/<name>`, and that folder's
+     * `gitdir` names the worktree's `.git`. The name is the last part of the
+     * path the worktree's `.git` file still holds. Answers the moved worktrees
+     * that could not be re-linked (git had already lost track of them, or a
+     * write failed) — their files are all there, only `git` in them is not.
+     * A worktree whose second link cannot be written gets its first one back,
+     * so neither link names a place the other does not.
+     */
+    async relinkMovedCopy(movedRepository, movedWorktrees) {
+        const gitPath = (p) => (process.platform === 'win32' ? p.replace(/\\/g, '/') : p);
+        const unlinked = [];
+        for (const worktree of movedWorktrees) {
+            try {
+                const gitfile = path.join(worktree, '.git');
+                const old = await readGitfile(gitfile);
+                if (old === null)
+                    throw new Error('its .git file names no folder');
+                const admin = path.join(movedRepository, 'worktrees', path.basename(old));
+                if (!(await fs.stat(admin).then((st) => st.isDirectory(), () => false))) {
+                    throw new Error(`the repository has no ${admin}`);
+                }
+                // Both links or neither: a `.git` re-pointed while the record behind
+                // it still names the old checkout is a worktree git calls prunable,
+                // and a `worktree prune` in the set-aside repository would drop it.
+                const before = await fs.readFile(gitfile, 'utf8');
+                // Written as the file system names them, as git itself writes them:
+                // on Windows a path held by its 8.3 short name (`RUNNER~1`) would
+                // otherwise be what `git worktree list` shows.
+                const realAdmin = await fs.realpath(admin);
+                const realGitfile = path.join(await fs.realpath(worktree), '.git');
+                await rewriteFile(gitfile, `gitdir: ${gitPath(realAdmin)}\n`);
+                try {
+                    await rewriteFile(path.join(admin, 'gitdir'), `${gitPath(realGitfile)}\n`);
+                }
+                catch (err) {
+                    await rewriteFile(gitfile, before).catch((backErr) => {
+                        log.error(`the .git file of the set-aside worktree ${worktree} could not be restored:`, {
+                            detail: this.redact(backErr instanceof Error ? backErr.message : String(backErr)),
+                        });
+                    });
+                    throw err;
+                }
+            }
+            catch (err) {
+                unlinked.push(worktree);
+                log.warn(`the set-aside worktree ${worktree} could not be re-linked to the set-aside repository:`, {
+                    detail: this.redact(err instanceof Error ? err.message : String(err)),
+                });
+            }
+        }
+        return unlinked;
+    }
+    /**
+     * Point the repository at `url` — the same repository at a new address.
+     * What this process knew of the old address's fetches is forgotten with it,
+     * so the next fetch reaches the new one rather than reading a success from
+     * the old one as fresh.
+     */
+    async setOriginUrl(url) {
+        await this.exclusive(async () => {
+            await this.git(['remote', 'set-url', 'origin', url]);
+            this.generation++;
+            this.lastSuccessAt = 0;
+            this.lastFailureAt = 0;
+            this.lastOk = null;
+            this.lastFailure = null;
+        });
+    }
+}
+//# sourceMappingURL=kb-repository.js.map