@ctrl-spc/cs 0.7.1 → 0.7.3

package/dist/panel3/checkout.js

@@ -5,9 +5,18 @@
  * this machine keeps the folder in `codebase-paths.json`. Nothing falls back to
  * a project folder or a machine-wide working copy, because either could put an
  * agent in a different repository while the record names this one.
+ *
+ * ═══ AND SINCE worktrees-8, THE FOLDER A RUN IS GIVEN IS NOT THAT ONE. ═══ The
+ * located checkout is the repository a copy is MADE FROM; the copy is the card's
+ * own worktree on the card's own branch. Both questions are answered here rather
+ * than in a module beside this one: "which folder does this codebase resolve to"
+ * and "which folder does this CARD resolve to" are one question asked twice, and
+ * two owners of it is how two answers are born.
  */
-import { statSync } from 'node:fs';
-import { readCodebasePaths } from '../config.js';
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { configDir, readCodebasePaths } from '../config.js';
 function isDirectory(path) {
     try {
         return statSync(path).isDirectory();
@@ -27,3 +36,514 @@ export function checkoutForCodebase(codebase, machineName) {
         return located;
     throw new Error(`Open the companion on ${machineName} and locate ${codebase.name} before sending code work there.`);
 }
+// ---------------------------------------------------------------------------
+// GIT.
+//
+// ═══ THREE LINES RATHER THAN A NAME ON THE ISOLATION LIST. ═══ `folders.ts:59`
+// is this repo's idiom for `git -C <folder> …` and CANNOT be imported:
+// `PANEL3_MAY_REACH` in `panel3-isolation.contract.test.mjs` is an exhaustive
+// list of seven specifiers and `../folders.js` is not one of them. Adding a name
+// there for one helper would widen a deliberate seam for a convenience, so the
+// wrapper lives here, knowingly duplicated and three lines long.
+//
+// ═══ AND ITS FAILURE MAY NEVER BE HANDED ON AS IT ARRIVES. ═══ `execFile`'s own
+// message begins `Command failed: git -C <absolute path> …`, and the callers of
+// these functions write their failure to `panel3_runs.failed_because`, which is
+// a cloud column a browser renders. Every throw below is composed from the
+// codebase's name and the branch, never from git's own text.
+/** A failure whose text was composed here and is therefore safe to write to the
+ *  cloud. Git's own text never is, so the wrapper below can tell them apart by
+ *  something better than matching on its wording. */
+const pathFree = (message) => Object.assign(new Error(message), { pathFree: true });
+function git(folder, args) {
+    return execFileSync('git', ['-C', folder, ...args], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim();
+}
+/**
+ * Remove a worktree, standing in ITS REPOSITORY rather than in the folder being
+ * removed.
+ *
+ * ═══ NEVER `-C` THE FOLDER BEING REMOVED. ═══ `git -C X` makes git's own
+ * current directory X, and Windows refuses to delete a directory that is any
+ * live process's current directory: `failed to delete '<path>': Permission
+ * denied`, every time, on a worktree nothing else has open. POSIX unlinks it
+ * happily, which is the only reason this was invisible on the Mac.
+ *
+ * The parent is NOT the answer: these copies live under a plain directory that
+ * belongs to no repository, so `-C parent` either finds nothing or finds some
+ * unrelated repository the home directory happens to be, and says the worktree
+ * "is not a working tree". The worktree knows its own repository, so it is asked
+ * first, while it still exists, and the removal is run from there.
+ */
+function removeWorktree(folder) {
+    const repo = git(folder, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+    git(repo, ['worktree', 'remove', '--force', folder]);
+}
+/** Whether this exact folder is a repository root, rather than merely sitting
+ *  somewhere beneath one. `--show-prefix` is empty only at the root, so a plain
+ *  folder inside a repository answers false here where `--git-dir` said true. */
+function isNotRepositoryRoot(folder) {
+    try {
+        return git(folder, ['rev-parse', '--show-prefix']) !== '';
+    }
+    catch {
+        return true;
+    }
+}
+/** Whether a git command succeeds, for the questions whose answer IS the exit
+ *  code: does this ref exist, is this folder a worktree. */
+function gitOk(folder, args) {
+    try {
+        git(folder, args);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Everything under `<config dir>/worktrees`, which is the one place on this
+ *  machine the product makes folders of its own. Machine-local by construction:
+ *  a card resumed on another machine finds nothing here and says so. */
+export function worktreeRoot() {
+    return join(configDir(), 'worktrees');
+}
+const folderSlug = (branch) => branch.replace(/\//g, '-');
+/** Where one card's copy lives, derived from the two facts the run row carries.
+ *  Pure, so the sweep can ask it of a row without resolving a codebase. */
+export function worktreeFolder(codebaseId, branch) {
+    return join(worktreeRoot(), codebaseId, folderSlug(branch));
+}
+/** The pattern a codebase nobody configured gets, and the one the mock renders.
+ *  `{task}` is the only token. */
+export const DEFAULT_BRANCH_PATTERN = 'agent/{task}';
+/**
+ * ═══ THE BRANCH IS DERIVED FROM THE CARD ID, AND THE TITLE IS DECORATION. ═══
+ *
+ * Immutable, pure, and identical for every run of one card, so two cards cannot
+ * collide on one branch and a resumed run needs no lookup to find its own. The
+ * id half is load-bearing and the title half is not: two cards may carry the
+ * same title, and a branch named only from the title would put both of them in
+ * one worktree, which is the whole of what this slice exists to prevent.
+ */
+export function branchNameFor(cardId, cardTitle, 
+/* ═══ THE TEAM'S PATTERN, AND `{task}` IS THE ONLY TOKEN. ═══ A team with a
+   naming convention has it for a reason and will not adopt a tool that
+   ignores it. There is deliberately no `{card}`: a card is the name of a thing
+   on screen, and what the person sent is a task. */
+pattern = null) {
+    const slug = cardTitle
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 40)
+        .replace(/-+$/, '');
+    const short = cardId.replace(/-/g, '').slice(0, 6);
+    const task = slug ? `${short}-${slug}` : short;
+    const named = (pattern ?? DEFAULT_BRANCH_PATTERN).replace(/\{task\}/g, task);
+    /* A PATTERN THAT NAMED NO TASK WOULD PUT EVERY CARD ON ONE BRANCH, which is
+       the defect this whole feature exists to prevent, so the task is appended
+       rather than the setting being refused: a person who typed `release/` gets
+       `release/<task>` and their work stays separated. */
+    return named.includes(task) ? named : `${named.replace(/\/+$/, '')}/${task}`;
+}
+/**
+ * WHAT WORK STARTS FROM, when nobody has said.
+ *
+ * `origin/HEAD` is written by `git clone` and by nothing else, so a checkout
+ * made with `git init` plus a remote has no such ref and the obvious answer
+ * would fail without the second step. Exactly one of `main`/`master` is that
+ * answer; both, or neither, is genuinely ambiguous and is a failure rather than
+ * a guess. Slice B replaces this throw with the stored setting.
+ */
+function baseBranchOf(folder, codebase, 
+/* WHAT THE TEAM SET, WHICH BEATS EVERY DETECTION BELOW. Null when nobody has
+   said, which is the ordinary case and the one detection is for. */
+stored = null) {
+    if (stored) {
+        if (gitOk(folder, ['rev-parse', '--verify', `refs/heads/${stored}`])
+            || gitOk(folder, ['rev-parse', '--verify', `refs/remotes/origin/${stored}`])) {
+            return stored;
+        }
+        throw pathFree(`${codebase.name} has no branch called ${stored} on this machine, and Project settings says `
+            + 'work starts from it. Fetch it, or change the main branch in Project settings.');
+    }
+    try {
+        const head = git(folder, ['symbolic-ref', 'refs/remotes/origin/HEAD']);
+        const named = head.replace(/^refs\/remotes\/origin\//, '');
+        if (named && named !== head)
+            return named;
+    }
+    catch { /* no origin/HEAD: fall through to the one obvious local answer */ }
+    const candidates = ['main', 'master']
+        .filter((name) => gitOk(folder, ['rev-parse', '--verify', `refs/heads/${name}`]));
+    if (candidates.length === 1)
+        return candidates[0];
+    throw pathFree(`Set the main branch for ${codebase.name} in Project settings: this machine cannot tell which `
+        + 'branch work should start from.');
+}
+/**
+ * Which worktree of this repository has `<branch>` checked out, or null when
+ * nothing does.
+ *
+ * One parse of `git worktree list --porcelain`, two questions asked of it: the
+ * base lock asks whether the base is held anywhere, and the landing asks WHERE,
+ * because that is the working tree the merge has to happen in.
+ */
+function worktreeHolding(folder, branch) {
+    const listed = git(folder, ['worktree', 'list', '--porcelain']);
+    let at = null;
+    for (const raw of listed.split('\n')) {
+        const line = raw.trim();
+        if (line.startsWith('worktree '))
+            at = line.slice('worktree '.length);
+        else if (line === `branch refs/heads/${branch}`)
+            return at;
+    }
+    return null;
+}
+/**
+ * ═══ THE BASE BRANCH IS HELD IN A WORKTREE THE PRODUCT OWNS, AND THAT IS WHAT
+ *     MAKES THE REFUSAL REAL. ═══
+ *
+ * Git refuses to check out a branch that is already checked out in another
+ * worktree of the same repository. So with the base held, no agent inside a
+ * card's copy can check the base out at all, and therefore cannot commit to it:
+ * the refusal is git's own, it happens before any commit exists, and
+ * `git commit --no-verify` has nothing to bypass because there was never a hook.
+ *
+ * ═══ AND WHEN THE PERSON IS STANDING ON IT, THERE IS NOTHING TO DO. ═══ Their
+ * own checkout is usually on the base branch, which already satisfies the
+ * invariant, and `git worktree add` would refuse for exactly the reason the
+ * invariant exists. So the lock is created only when the base is checked out
+ * nowhere, which is the honest reading of "held somewhere the product owns or
+ * somewhere it can see".
+ */
+function holdBaseBranch(source, codebaseId, base) {
+    if (worktreeHolding(source, base) !== null)
+        return;
+    const lock = join(worktreeRoot(), codebaseId, 'base');
+    mkdirSync(join(worktreeRoot(), codebaseId), { recursive: true });
+    git(source, ['worktree', 'prune']);
+    git(source, ['worktree', 'add', lock, base]);
+}
+/**
+ * ═══ WHETHER THIS MACHINE CAN SETTLE THE BASE BRANCH ON ITS OWN, AND WHAT IT
+ *     WOULD OFFER IF IT CANNOT. ═══
+ *
+ * The coordinator is the only thing that can ask a person, and it has to know
+ * before it dispatches, so this answers the question WITHOUT starting any work:
+ * settled and the name, or unsettled and the branches to offer as options.
+ *
+ * A codebase this machine has not located is neither: it returns null, because
+ * "we cannot tell" is not "it is ambiguous", and asking a person to choose a
+ * branch on a repository nobody has is a question with no right answer.
+ */
+export function baseBranchState(codebase, stored) {
+    if (!hasCheckoutForCodebase(codebase))
+        return null;
+    const folder = readCodebasePaths()[codebase.gitRemoteUrl];
+    try {
+        return { settled: baseBranchOf(folder, codebase, stored) };
+    }
+    catch {
+        /* THE REPOSITORY'S OWN BRANCHES, which is what story 3 offers as the
+           options: a person who does not know git can still recognise the name of
+           the branch their team works on. Local heads and remote branches alike,
+           because a fresh clone has one and a long-lived checkout has both. */
+        try {
+            return {
+                candidates: [...new Set(git(folder, ['for-each-ref', '--format=%(refname:short)', 'refs/heads', 'refs/remotes/origin'])
+                        .split('\n')
+                        .map((name) => name.trim().replace(/^origin\//, ''))
+                        .filter((name) => name.length > 0 && name !== 'HEAD'))].sort(),
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/**
+ * ═══ WHETHER THE BASE BRANCH IS PROTECTED ON THE REMOTE, ANSWERED BY THE
+ *     MACHINE THAT HOLDS THE CHECKOUT. ═══
+ *
+ * The browser cannot answer this: it has no platform credential and the product
+ * stores none. The developer's own `gh` is already authenticated, already
+ * installed on the machines this runs on, and needs nothing this product keeps.
+ * So no token reaches a row, no API client is written, and the web gains no
+ * platform dependency.
+ *
+ * ═══ NULL MEANS UNKNOWN, AND UNKNOWN IS NOT FALSE. ═══ `gh` may be absent,
+ * signed out, or the remote may not be GitHub. The one wrong answer available
+ * here is `false`, because false is the answer that bypasses a review, so
+ * everything that is not a clear yes or a clear no is null. That is why the
+ * repository is asked about FIRST: `gh api …/protection` answers 404 both for a
+ * branch that is not protected and for a repository this account cannot see,
+ * and only the first of those is a `false`.
+ */
+export function detectBaseProtection(folder, base) {
+    const gh = (args) => {
+        try {
+            return {
+                ok: true,
+                out: execFileSync('gh', args, {
+                    cwd: folder,
+                    encoding: 'utf8',
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                    timeout: 15_000,
+                }),
+            };
+        }
+        catch (error) {
+            return { ok: false, out: `${error?.stderr ?? ''}` };
+        }
+    };
+    if (!gh(['api', 'repos/{owner}/{repo}', '--jq', '.name']).ok)
+        return null;
+    const protection = gh(['api', 'repos/{owner}/{repo}/branches/' + base + '/protection', '--jq', '.url']);
+    if (protection.ok)
+        return true;
+    return /not protected|404/i.test(protection.out) ? false : null;
+}
+/**
+ * ═══ ONE CARD, ONE COPY, ONE BRANCH. ═══
+ *
+ * The located checkout is the repository this is made FROM and is never handed
+ * to an agent as a cwd: it is the person's own, and no product action may move
+ * its branch, index or working tree.
+ *
+ * `stamped` is what this card's earlier runs already recorded. When the branch
+ * is given and no such branch exists here, this FAILS rather than cutting a new
+ * empty branch of the same name: the branch and the copy are local to one
+ * machine and one config dir, and a card resumed elsewhere has to say so rather
+ * than silently starting again from the base with the work left behind.
+ *
+ * ═══ AND A STAMPED BASE IS THE BASE, WITHOUT DETECTION. ═══ The stored setting
+ * is any member's to change at any time, so a card whose copy was cut from
+ * `develop` on Monday must not be told on Tuesday that it goes back to `main`.
+ * The branch already follows that rule and the base now follows it beside.
+ */
+export function worktreeForCard(codebase, cardId, cardTitle, stamped, machineName, 
+/* ═══ WHAT THE TEAM DECIDED, OR NOTHING AT ALL. ═══ Both are nullable and both
+   are correct empty: a codebase nobody configured detects its base branch and
+   names branches the product's own way, which is contract point 10. */
+settings = {}) {
+    const source = checkoutForCodebase(codebase, machineName);
+    const branch = stamped.branch ?? branchNameFor(cardId, cardTitle, settings.branchPattern ?? null);
+    const folder = worktreeFolder(codebase.id, branch);
+    try {
+        /* ASKED FIRST, SO THE FAILURE NAMES THE RIGHT THING. Without it a located
+           folder that is not a repository at all comes back as "set the main
+           branch", which is a true sentence about a machine that has no branches
+           and useless advice to the person reading it.
+    
+           ═══ THE ROOT, NOT ANY DESCENDANT OF ONE. ═══ `rev-parse --git-dir`
+           answers for the nearest repository ABOVE the folder, so every folder
+           beneath one passed this guard: a person whose projects sit under a
+           git-managed home directory located a plain folder and was told to go and
+           set a main branch. `--show-prefix` is the question actually meant here,
+           because it is empty at a repository root and the path down from it
+           anywhere else. */
+        if (isNotRepositoryRoot(source)) {
+            throw pathFree(`${codebase.name} on ${machineName} is not a git repository. Locate it again in the `
+                + 'companion, or point it at the repository itself.');
+        }
+        const base = stamped.base ?? baseBranchOf(source, codebase, settings.baseBranch ?? null);
+        /* BROUGHT UP TO DATE, AND ITS FAILURE IS NOT THE CARD'S. A machine with no
+           remote, no network or no credentials can still do every part of this that
+           matters; only the freshness of the start point is lost, and refusing the
+           card over it would make working offline impossible. */
+        try {
+            git(source, ['fetch', 'origin', base]);
+        }
+        catch { /* best effort */ }
+        holdBaseBranch(source, codebase.id, base);
+        const exists = gitOk(source, ['rev-parse', '--verify', `refs/heads/${branch}`]);
+        if (stamped.branch !== null && !exists) {
+            throw pathFree(`${codebase.name} on ${machineName} does not have the branch ${branch} this card's work is `
+                + 'on. That work is on the machine the card started on; resume it there.');
+        }
+        /* THE SECOND VISIT TO A CARD IS ALWAYS THE EXISTING-BRANCH CASE, because
+           cleanup removes worktrees and never removes branches. A worktree's `.git`
+           is a FILE pointing back at the repository, not a directory. */
+        if (existsSync(join(folder, '.git')))
+            return { folder, branch, base, source };
+        /* ═══ A FOLDER THAT IS THERE AND IS NOT A WORKTREE IS NAMED FOR WHAT IT IS.
+           ═══ Found by walking C1. `git worktree add` refuses a directory that
+           exists and is not empty, so this card failed every poll with the generic
+           sentence below, which says the codebase is not a git repository. That is
+           untrue and sends the person to look at the wrong thing. What is really
+           there is the wreckage of a copy: a build output an agent wrote, or an add
+           that failed after making its directory. The product does not delete it,
+           because it never successfully made it. */
+        if (existsSync(folder)) {
+            throw pathFree(`${codebase.name}'s copy of this card on branch ${branch} is on this machine but is not a `
+                + 'working copy any more. Delete that folder and the product will make it again; `cs show` '
+                + 'names where it is.');
+        }
+        mkdirSync(join(worktreeRoot(), codebase.id), { recursive: true });
+        git(source, ['worktree', 'prune']);
+        /* `origin/<base>` when there is one, the local base when there is not: a
+           repository with a remote it cannot reach, or none at all, still branches
+           from the only base it has. */
+        const startPoint = gitOk(source, ['rev-parse', '--verify', `refs/remotes/origin/${base}`])
+            ? `origin/${base}`
+            : base;
+        if (exists)
+            git(source, ['worktree', 'add', folder, branch]);
+        else
+            git(source, ['worktree', 'add', '-b', branch, folder, startPoint]);
+        return { folder, branch, base, source };
+    }
+    catch (error) {
+        /* ═══ PATH-FREE, BECAUSE THE CALLER WRITES THIS TO THE CLOUD. ═══ What was
+           composed here says so and passes through; anything from git carries
+           `-C <absolute path>` in its first line and is replaced outright. */
+        if (error?.pathFree)
+            throw error;
+        throw pathFree(`This machine could not make ${codebase.name}'s working copy for this card on branch `
+            + `${branch}. Check that ${codebase.name} is a git repository on ${machineName}.`);
+    }
+}
+/**
+ * ═══ THE CARD IS OVER: COMMIT WHAT IS THERE, THEN TAKE THE COPY AWAY. ═══
+ *
+ * The commit comes first and is unconditional on there being something to
+ * commit, so removing the copy cannot lose work. The BRANCH is never touched:
+ * work that never landed survives until a person deals with it.
+ *
+ * It takes the folder alone, and that is deliberate: a worktree knows its own
+ * repository, so the sweep needs neither the located checkout nor the codebase
+ * row to clean one up.
+ */
+/**
+ * ═══ EVERYTHING IN A CARD'S COPY, ON ITS BRANCH. ═══
+ *
+ * `settleCardWorktree`'s own first three lines, extracted rather than rewritten,
+ * because the landing needs the commit BEFORE the merge and the sweep needs it
+ * before the removal. Committing in two places with two messages is how one card
+ * comes to have two ideas of what its work is.
+ *
+ * ═══ ITS FAILURE IS COMPOSED, WHICH THE SWEEP NEVER NEEDED. ═══ The sweep
+ * writes to stderr, so git's own text was harmless there. On the landing path a
+ * failure reaches a person through an agent, and `execFileSync`'s message begins
+ * `Command failed: git -C <absolute path>`. So this wraps in `worktreeForCard`'s
+ * shape: what was composed here passes through, anything else is replaced.
+ */
+export function commitCardWork(folder, 
+/* WHAT THE COPY IS, IN WORDS AND NEVER AS A PATH. The sweep has only the
+   folder and says so; the landing has the codebase and the branch and names
+   both, which is what a person reading the failure needs. */
+describe) {
+    try {
+        git(folder, ['add', '-A']);
+        if (git(folder, ['status', '--porcelain']).length > 0) {
+            git(folder, ['commit', '--no-verify', '-m', 'Work from this card']);
+        }
+    }
+    catch (error) {
+        if (error?.pathFree)
+            throw error;
+        throw pathFree(`This machine could not commit what is in ${describe}. Nothing was merged and the work is `
+            + 'still where it was.');
+    }
+}
+/**
+ * ═══ THE CARD'S BRANCH, ONTO THE BASE IT WAS CUT FROM, WHERE THE BASE ALREADY
+ *     LIVES. ═══
+ *
+ * The base is checked out in exactly one working tree: the lock the product
+ * holds, or the person's own checkout when they are standing on it. "Merge into
+ * the worktree that holds the base" resolves to whichever it is, so there is one
+ * rule here rather than two cases.
+ *
+ * A FAST-FORWARD IS ALLOWED. No requirement names a merge commit, and `--no-ff`
+ * would be a shape invented for the history.
+ */
+export function mergeIntoBase(source, branch, base, codebaseName) {
+    const holder = worktreeHolding(source, base);
+    if (holder === null) {
+        throw pathFree(`${codebaseName}'s ${base} is not checked out anywhere on this machine, so there is nowhere `
+            + `to put this work. Nothing was merged and it is still on ${branch}.`);
+    }
+    /* ═══ A MERGE OF THEIR OWN, IN PROGRESS, IS NOT THIS PRODUCT'S TO ABORT. ═══
+       The worktree holding the base may be the person's own checkout, and the
+       step below would abort on failure. So a conflicted merge already sitting
+       there stops this before anything is attempted. */
+    if (existsSync(join(holder, '.git', 'MERGE_HEAD')) || existsSync(join(holder, 'MERGE_HEAD'))) {
+        throw pathFree(`A merge is already in progress in the copy of ${codebaseName} holding ${base} on this `
+            + `machine. Nothing was done, and this card's work is still on ${branch}.`);
+    }
+    try {
+        git(holder, ['merge', '--no-edit', branch]);
+    }
+    catch {
+        /* ITS OWN TRY, SO A FAILED ABORT CANNOT REPLACE THE COMPOSED FAILURE with
+           git's own text, which names a folder. */
+        try {
+            git(holder, ['merge', '--abort']);
+        }
+        catch { /* nothing to abort */ }
+        throw pathFree(`This card's work will not go back onto ${base} in ${codebaseName} cleanly. Nothing was `
+            + `merged, ${base} is where it was, and the work is still on ${branch}.`);
+    }
+}
+export function settleCardWorktree(folder) {
+    commitCardWork(folder, 'this card\'s working copy');
+    /* FORCE, AFTER THE COMMIT. Everything tracked is now committed on the branch,
+       so what `--force` overrides is only ignored files: an installed
+       `node_modules`, a build output, which the next copy makes again. */
+    removeWorktree(folder);
+}
+/**
+ * Every card copy this machine currently holds, as `<codebase id>/<folder>`
+ * pairs. The filesystem is asked first so a machine with no copies asks the
+ * database nothing at all.
+ *
+ * ═══ A FOLDER THAT IS NOT A WORKTREE IS NOT A COPY. ═══ Found by walking C1: a
+ * `git worktree add` that failed after its directory existed, or a copy whose
+ * `.git` file was removed underneath the product, leaves a directory here that
+ * belongs to no repository. `settleCardWorktree` cannot commit it or remove it,
+ * so the sweep failed on it EVERY POLL, forever, saying the same sentence to
+ * stderr. The filter is what stops the loop: the product cleans up the copies it
+ * really made and leaves anything else on disk for a person, rather than
+ * retrying something that can never succeed.
+ */
+export function worktreesOnThisMachine() {
+    const root = worktreeRoot();
+    if (!isDirectory(root))
+        return [];
+    return readdirSync(root, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .flatMap((codebase) => readdirSync(join(root, codebase.name), { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && entry.name !== 'base')
+        .map((entry) => ({
+        codebaseId: codebase.name,
+        slug: entry.name,
+        folder: join(root, codebase.name, entry.name),
+    }))
+        .filter((one) => existsSync(join(one.folder, '.git'))));
+}
+/** Whether a run row's branch names this folder. The folder is the branch with
+ *  its slashes flattened, and the comparison lives beside the derivation so the
+ *  two cannot disagree. */
+export const folderIsBranch = (slug, branch) => folderSlug(branch) === slug;
+/** The base-branch lock, once the codebase has no card copies left. Never while
+ *  one survives: it is what makes their refusal real. */
+export function releaseBaseBranch(codebaseId) {
+    const codebaseRoot = join(worktreeRoot(), codebaseId);
+    const lock = join(codebaseRoot, 'base');
+    if (!isDirectory(lock))
+        return;
+    /* REAL COPIES ONLY, for the reason `worktreesOnThisMachine` gives: a directory
+       that belongs to no repository is not a card's copy, and letting one hold the
+       base-branch lock would hold it forever. */
+    const remaining = readdirSync(codebaseRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && entry.name !== 'base')
+        .filter((entry) => existsSync(join(codebaseRoot, entry.name, '.git')));
+    if (remaining.length > 0)
+        return;
+    removeWorktree(lock);
+}