@bridge4dev/runner 0.52.0 → 0.54.0

package/dist/git.js

@@ -6,10 +6,94 @@ import { previewsDir, worktreesDir } from './paths.js';
 import { firstUnreachableAncestor, inspectPath, looksLikeDubiousOwnership, runnerIdentity, safeDirectoryCommand, } from './environment.js';
 const execFileAsync = promisify(execFile);
 const GIT_TIMEOUT_MS = 30_000;
+/**
+ * Laying out a worktree is the one git command here that is bounded by DISK,
+ * not by git (#360). Thirty seconds is the right budget for a question; it is
+ * the wrong budget for writing 2693 files on a machine whose swap is full, and
+ * the SIGTERM that ended it was read as «git failed» by everyone downstream.
+ * Ninety seconds is the owner's number (plan §9, 06.09.2026).
+ */
+const WORKTREE_ADD_TIMEOUT_MS = 90_000;
 async function git(cwd, ...args) {
     const { stdout } = await execFileAsync('git', args, { cwd, timeout: GIT_TIMEOUT_MS });
     return stdout.trim();
 }
+async function gitSlow(cwd, timeoutMs, ...args) {
+    const { stdout } = await execFileAsync('git', args, { cwd, timeout: timeoutMs });
+    return stdout.trim();
+}
+/**
+ * Why git stopped, in a sentence a person can act on.
+ *
+ * `git worktree add` prints its progress to stderr as carriage-return-overwritten
+ * frames, so a process killed mid-checkout leaves «Updating files: 1% (51/2693)»
+ * as the last thing anybody sees — a number, with no verb. The real cause lives
+ * on the error object (`killed`, `signal`, `code`) and nobody was reading it
+ * (#360). Keep the last progress frame, because «how far did it get» is the one
+ * useful thing in it, and put the cause in front of it.
+ */
+export function describeGitFailure(error, context = {}) {
+    const err = error;
+    const raw = String(err?.stderr || err?.message || error || '');
+    const lines = raw
+        .split('\n')
+        .map((line) => {
+        // Only the last frame of a \r-overwritten line was ever on screen.
+        const frames = line
+            .split('\r')
+            .map((frame) => frame.trim())
+            .filter(Boolean);
+        return frames.at(-1) ?? '';
+    })
+        // `Command failed: git …` is Node's own wrapper line, not git's answer, and
+        // it repeats the command that is already in the log next to this text.
+        .filter((line) => line.length > 0 && !line.startsWith('Command failed'));
+    // Two lines and 180 characters, not three and 300: this text is wrapped in a
+    // sentence that says what was cleaned up and what to press, and the whole
+    // thing passes through a 500-character mask on its way to the feed. Git's
+    // hint lines are the least useful part of it, and they were crowding out the
+    // only part a person can act on.
+    const tail = lines.slice(-2).join('; ').slice(0, 180);
+    let cause;
+    if (err?.killed && context.timeoutMs) {
+        cause = `git was stopped after ${Math.round(context.timeoutMs / 1000)} s`;
+    }
+    else if (err?.killed) {
+        cause = 'git was stopped by the runner';
+    }
+    else if (err?.signal) {
+        cause = `git was killed by ${err.signal} (the machine most likely ran out of memory)`;
+    }
+    else if (typeof err?.code === 'number') {
+        cause = `git exited with code ${err.code}`;
+    }
+    else {
+        cause = 'git failed';
+    }
+    return tail ? `${cause}: ${tail}` : cause;
+}
+/**
+ * A preparation failure that already knows its own fork point.
+ *
+ * The fork point matters precisely BECAUSE preparation failed: without it the
+ * API keeps `base_sha = null` for the session's whole life, and «Continue» can
+ * never prove that the branch it is about to adopt is the empty one this very
+ * session created a moment ago (#360, plan Р6).
+ */
+export class WorktreePrepareError extends Error {
+    code;
+    baseBranch;
+    baseSha;
+    constructor(message, code, base = {}) {
+        super(message);
+        this.name = 'WorktreePrepareError';
+        this.code = code;
+        if (base.baseBranch)
+            this.baseBranch = base.baseBranch;
+        if (base.baseSha)
+            this.baseSha = base.baseSha;
+    }
+}
 /**
  * Can this runner actually work in this directory — as the user it runs as?
  *
@@ -107,7 +191,54 @@ export async function validateWorkspacePath(workspacePath) {
         };
     }
     const branch = await git(workspacePath, 'rev-parse', '--abbrev-ref', 'HEAD');
-    return { ok: true, exists: true, isGitRepo: true, branch };
+    // Binding is the one moment we are guaranteed to be looking at this repository
+    // with somebody waiting for the answer, so it is where the main branch is
+    // learned (ADR 0004). `branch` above is «what the folder is on right now» — a
+    // drifting value, and the reason #361 exists; these two must not be confused.
+    const defaultBranch = await remoteDefaultBranch(workspacePath);
+    return {
+        ok: true,
+        exists: true,
+        isGitRepo: true,
+        branch,
+        ...(defaultBranch ? { defaultBranch } : {}),
+    };
+}
+/**
+ * The repository's main branch, read locally (ADR 0004).
+ *
+ * `origin/HEAD` is the honest answer and it is already on disk — set by `clone`,
+ * refreshed by `git remote set-head`. Never asked over the network: this runs
+ * inside a 4-second probe budget, and a repository whose origin is unreachable
+ * must still bind.
+ */
+export async function remoteDefaultBranch(workspacePath) {
+    const symbolic = await git(workspacePath, 'symbolic-ref', '--short', 'refs/remotes/origin/HEAD')
+        .then((value) => value.replace(/^origin\//, '').trim())
+        .catch(() => '');
+    if (symbolic)
+        return sanitizeBranch(symbolic);
+    // No origin (or no HEAD recorded for it): fall back to the conventional names,
+    // but only if they actually exist here. Guessing a branch that is not in the
+    // repository would be worse than answering «unknown».
+    return firstConventionalBranch(workspacePath);
+}
+/**
+ * `main`, then `master`, and only if the repository really has one.
+ *
+ * The order and the list are one decision, not two: `gitops.ts` asks the same
+ * question when «Apply» has no pinned base, and two copies would drift the day
+ * somebody adds `develop` to one of them (ADR 0004).
+ */
+export async function firstConventionalBranch(workspacePath) {
+    for (const candidate of ['main', 'master']) {
+        const exists = await git(workspacePath, 'rev-parse', '--verify', '--quiet', candidate)
+            .then(() => true)
+            .catch(() => false);
+        if (exists)
+            return candidate;
+    }
+    return null;
 }
 /** The real `.git` directory of a work tree (a linked worktree has a file there). */
 async function resolveGitDir(workspacePath) {
@@ -184,14 +315,31 @@ export async function ensureSessionWorktree(workspacePath, sessionId, branchHint
     const planned = options.plan ? sanitizeBranch(options.plan.branch) : null;
     const branch = planned ?? sanitizeBranch(branchHint) ?? `devbridge/s-${short}`;
     const worktreePath = sessionWorktreePath(sessionId);
+    // With a plan, both mismatches are failures worth stopping for. Without one
+    // (an API from before session 13) the historical guesswork is kept exactly as
+    // it was, so an old server does not start failing after a runner update.
+    const plan = planned ? options.plan : undefined;
     if (fs.existsSync(path.join(worktreePath, '.git'))) {
         // Runner restart — reuse, but verify the worktree really is ours: a
         // short-id collision would silently share a worktree between sessions.
         const head = await git(worktreePath, 'rev-parse', '--abbrev-ref', 'HEAD').catch(() => null);
-        if (head !== branch) {
+        if (head === branch)
+            return { branch, worktreePath };
+        // Gotcha 175 named two states, «not created yet» and «already gone». This is
+        // the third: created halfway. A worktree whose `git worktree add` was
+        // SIGKILLed mid-checkout keeps its registration, a detached HEAD and a lock
+        // reading `initializing` — so «the registration is alive and HEAD answers»
+        // is TRUE for it, and the old check read that as «somebody else's worktree»
+        // and refused forever (#360).
+        const halfCreated = await looksHalfCreated(workspacePath, worktreePath, head, branch);
+        if (!halfCreated) {
             throw new Error(`Worktree ${worktreePath} is on branch ${head ?? 'unknown'}, expected ${branch}`);
         }
-        return { branch, worktreePath };
+        const discarded = await discardWorktreeFolder(workspacePath, worktreePath);
+        if (!discarded.ok) {
+            throw new WorktreePrepareError(`The working folder ${worktreePath} was left half-created by an earlier attempt and could not be cleaned up: ${discarded.leftovers.join('; ')}. ` +
+                `Remove it on the server (\`git -C ${workspacePath} worktree unlock ${worktreePath}; git -C ${workspacePath} worktree remove --force ${worktreePath}\`), then press "Continue".`, 'worktree_cleanup_failed');
+        }
     }
     fs.mkdirSync(worktreesDir(), { recursive: true, mode: 0o700 });
     // Repair stale registrations left by a deleted worktree dir.
@@ -199,12 +347,24 @@ export async function ensureSessionWorktree(workspacePath, sessionId, branchHint
     const branchExists = await git(workspacePath, 'rev-parse', '--verify', '--quiet', branch)
         .then(() => true)
         .catch(() => false);
-    // With a plan, both mismatches are failures worth stopping for. Without one
-    // (an API from before session 13) the historical guesswork is kept exactly as
-    // it was, so an old server does not start failing after a runner update.
-    const plan = planned ? options.plan : undefined;
+    // Set only when the branch we are about to attach is provably the empty
+    // leftover of THIS session's own failed start. It is the one case in which
+    // the branch tip and the fork point are the same commit — everywhere else
+    // reporting the tip as a fork point would move the base of «Apply» onto the
+    // work itself.
+    let adoptedOwnEmpty = false;
     if (plan?.source === 'NEW' && branchExists) {
-        throw new Error(`branch ${branch} already exists in ${workspacePath} — a new session must not silently continue somebody else's work`);
+        // «Continue» onto our OWN empty branch. The refusal below is right and stays
+        // (QA-107: a new session must not sit down on a stranger's commits), but the
+        // stranger it was protecting against was, in #360, this same session's own
+        // leftover — a branch created by a `worktree add -b` that then died laying
+        // out files. Provable, not guessed: the name is the planned one, the API
+        // pinned a fork point, the branch tip is exactly that fork point, so it
+        // carries no commits, and nobody has it checked out.
+        const adoption = await canAdoptOwnEmptyBranch(workspacePath, branch, plan);
+        if (!adoption.ok)
+            throw adoption.error;
+        adoptedOwnEmpty = true;
     }
     if (plan?.source === 'CONTINUE' && !branchExists) {
         throw new Error(`branch ${branch} no longer exists in ${workspacePath}`);
@@ -216,8 +376,32 @@ export async function ensureSessionWorktree(workspacePath, sessionId, branchHint
         if (holder) {
             throw new Error(`branch ${branch} is already checked out in ${holder}`);
         }
-        await git(workspacePath, 'worktree', 'add', worktreePath, branch);
-        return { branch, worktreePath };
+        try {
+            // Laying out files, so the long budget — the same work `worktree add -b`
+            // was doing when #360's session died at 1%.
+            await gitSlow(workspacePath, WORKTREE_ADD_TIMEOUT_MS, 'worktree', 'add', worktreePath, branch);
+        }
+        catch (error) {
+            throw await cleanUpAfterFailure(workspacePath, worktreePath, {
+                error,
+                branch,
+                // The branch was here before us — the ladder must not touch it.
+                branchWasOurs: false,
+                ...(plan?.baseBranch ? { baseBranch: plan.baseBranch } : {}),
+                ...(plan?.baseSha ? { startSha: plan.baseSha } : {}),
+            });
+        }
+        return {
+            branch,
+            worktreePath,
+            // Nothing new is learned by attaching a branch that already existed: its
+            // tip is where the WORK is, not where it forked, and reporting it as the
+            // base would move the target of «Apply» onto the work itself. The one
+            // exception is the leftover we just proved empty, where the two commits
+            // are the same one and the API may still be missing it.
+            ...(adoptedOwnEmpty && plan?.baseBranch ? { baseBranch: plan.baseBranch } : {}),
+            ...(adoptedOwnEmpty && plan?.baseSha ? { baseSha: plan.baseSha } : {}),
+        };
     }
     if (options.requireExistingBranch) {
         // The caller is restoring a session that already produced work. Creating
@@ -229,6 +413,11 @@ export async function ensureSessionWorktree(workspacePath, sessionId, branchHint
     // A pinned sha that is not in this repository is not worth guessing around —
     // branching off the wrong commit is the failure this whole plan removes.
     const startPoint = await resolveStartPoint(workspacePath, plan);
+    // Resolved to a full sha BEFORE anything is written. Two reasons: a DIRECT
+    // neighbour can move HEAD between these lines, and the fork point has to be
+    // known even if the next step dies — it is what makes the leftover branch
+    // provably empty afterwards (#360).
+    const startSha = await git(workspacePath, 'rev-parse', '--verify', `${startPoint}^{commit}`);
     // What HEAD points at, read BEFORE the worktree is added. This is the only
     // chance to learn the fork point for a session created while the runner was
     // offline: the API had nobody to ask, so `branchPlan.baseBranch` is empty and
@@ -239,15 +428,294 @@ export async function ensureSessionWorktree(workspacePath, sessionId, branchHint
         : await git(workspacePath, 'rev-parse', '--abbrev-ref', 'HEAD')
             .then((name) => (name && name !== 'HEAD' ? name : undefined))
             .catch(() => undefined);
-    await git(workspacePath, 'worktree', 'add', '-b', branch, worktreePath, startPoint);
-    const baseSha = await git(workspacePath, 'rev-parse', startPoint).catch(() => undefined);
+    // Files first, branch second (#360, plan Р6). `git worktree add -b` does both
+    // in one command and in the opposite order: it registers the branch, THEN
+    // spends minutes writing files — so every death in between left a branch that
+    // no worktree held and that the next start refused to touch. Split in two, the
+    // expensive half creates nothing that can outlive it, and `checkout -b` at the
+    // end is instant. (`checkout -b`, not `switch -c`: `switch` needs git ≥ 2.23
+    // and the runner never checks the git version.)
+    try {
+        await addDetachedWorktree(workspacePath, worktreePath, startSha);
+        await git(worktreePath, 'checkout', '-b', branch);
+    }
+    catch (error) {
+        throw await cleanUpAfterFailure(workspacePath, worktreePath, {
+            error,
+            branch,
+            branchWasOurs: true,
+            startSha,
+            baseBranch: headBranch,
+        });
+    }
     return {
         branch,
         worktreePath,
         ...(headBranch ? { baseBranch: headBranch } : {}),
-        ...(baseSha ? { baseSha } : {}),
+        baseSha: startSha,
     };
 }
+/**
+ * Is this branch the empty leftover of this very session's failed start (#360)?
+ *
+ * Every part of the answer is checked against the repository right now, not
+ * remembered: this decides whether a `branch -D` is allowed later, and the cost
+ * of being wrong is somebody's commits.
+ */
+async function canAdoptOwnEmptyBranch(workspacePath, branch, plan) {
+    const tip = await git(workspacePath, 'rev-parse', `${branch}^{commit}`).catch(() => null);
+    const refuse = (why, hint) => ({
+        ok: false,
+        error: new WorktreePrepareError(`Branch ${branch} already exists in ${workspacePath}${tip ? ` (tip ${tip.slice(0, 12)})` : ''} and ${why}, ` +
+            `so this session will not adopt it. ${hint}`, 'branch_taken', { baseBranch: plan.baseBranch, baseSha: plan.baseSha }),
+    });
+    if (!plan.baseSha) {
+        // A session created while the runner was unreachable by an API older than
+        // stage 1: nothing pinned the fork point, so emptiness cannot be proven at
+        // all. Say so, and say what to type.
+        return refuse('this session never recorded a fork point, so the runner cannot prove it is empty', `If it is not anybody's work, delete it there (\`git -C ${workspacePath} branch -D ${branch}\`) and press "Continue".`);
+    }
+    // The API may ship a shortened sha (protocol.ts) — resolve both sides.
+    const pinned = await git(workspacePath, 'rev-parse', `${plan.baseSha}^{commit}`).catch(() => null);
+    if (!tip || !pinned) {
+        return refuse('its tip could not be read', `Check it on the server, and press "Continue" once it is gone.`);
+    }
+    if (tip !== pinned) {
+        return refuse(`has commits of its own (fork point ${pinned.slice(0, 12)})`, `If it is not anybody's work, delete it there (\`git -C ${workspacePath} branch -D ${branch}\`) and press "Continue".`);
+    }
+    const holder = await worktreeHolding(workspacePath, branch);
+    if (holder) {
+        return refuse(`is checked out in ${holder}`, `Free that worktree, or delete the branch, and press "Continue".`);
+    }
+    return { ok: true };
+}
+/**
+ * `git worktree add --detach` — shared by sessions and by the preview slot.
+ *
+ * The one command in this file bounded by disk rather than by git, which is why
+ * it has a budget of its own.
+ */
+async function addDetachedWorktree(workspacePath, worktreePath, sha) {
+    await gitSlow(workspacePath, WORKTREE_ADD_TIMEOUT_MS, 'worktree', 'add', '--detach', worktreePath, sha);
+}
+/**
+ * The cleanup ladder (#360, plan Р6). Every rung is «undo what may exist», and
+ * the whole ladder runs before the original error is re-thrown — a failure to
+ * lay out files must not also leave a folder and a branch behind.
+ */
+async function cleanUpAfterFailure(workspacePath, worktreePath, input) {
+    const cause = describeGitFailure(input.error, { timeoutMs: WORKTREE_ADD_TIMEOUT_MS });
+    const base = { baseBranch: input.baseBranch, baseSha: input.startSha };
+    const discarded = await discardWorktreeFolder(workspacePath, worktreePath);
+    const leftovers = [...discarded.leftovers];
+    let branchRemoved = false;
+    if (input.branchWasOurs && input.startSha) {
+        const dropped = await dropEmptySessionBranch(workspacePath, input.branch, input.startSha);
+        branchRemoved = dropped.removed;
+        if (!dropped.removed && dropped.leftover)
+            leftovers.push(dropped.leftover);
+    }
+    if (leftovers.length > 0) {
+        return new WorktreePrepareError(`Could not prepare the working folder for this session: ${cause}. ` +
+            `Cleaning up after it did not finish either: ${leftovers.join('; ')}. ` +
+            `Clear that on the server, then press "Continue".`, 'worktree_cleanup_failed', base);
+    }
+    return new WorktreePrepareError(`Could not prepare the working folder for this session: ${cause}. ` +
+        (branchRemoved
+            ? `The branch ${input.branch} it had just created was removed and nothing of yours was touched. `
+            : `Nothing was left behind and nothing of yours was touched. `) +
+        `Press "Continue" to try again.`, 'worktree_prepare_failed', base);
+}
+/**
+ * Delete a session branch that provably carries no commits (#360).
+ *
+ * Shares its safety rungs with {@link deleteSessionBranch} — prune, then the
+ * folder's own branch, then the holder — and adds the one this caller needs:
+ * the tip must still be exactly the fork point we started from. `-D`, not `-d`,
+ * because `-d` asks «is it merged into the branch THIS folder is on», which is
+ * a different question and answers «no» for a branch that is empty.
+ */
+export async function dropEmptySessionBranch(workspacePath, branch, expectedSha) {
+    const safe = sanitizeBranch(branch);
+    if (!safe)
+        return { removed: false, leftover: `unsafe branch name ${branch}` };
+    await git(workspacePath, 'worktree', 'prune').catch(() => undefined);
+    // `--verify --quiet` so that «no such ref» is exit 1 with no output. Without
+    // it a missing branch exits 128 with a fatal, which is indistinguishable from
+    // git being unable to look at all — and those two need opposite answers.
+    const tip = await git(workspacePath, 'rev-parse', '--verify', '--quiet', `${safe}^{commit}`).then((value) => ({ ok: true, value }), (error) => ({ ok: false, code: error.code }));
+    // Exit 1 with no output is «there is no such ref» — the good case, nothing to
+    // delete. Anything else is git failing to LOOK, and reporting that as «clean»
+    // is how a leftover branch gets announced as tidied up (QA #255).
+    if (!tip.ok) {
+        return tip.code === 1
+            ? { removed: false }
+            : {
+                removed: false,
+                leftover: `could not check whether branch ${safe} was left behind`,
+            };
+    }
+    const expected = await git(workspacePath, 'rev-parse', `${expectedSha}^{commit}`).catch(() => null);
+    if (!expected || tip.value !== expected) {
+        return {
+            removed: false,
+            leftover: `branch ${safe} was left in place (it is not at ${expectedSha.slice(0, 12)})`,
+        };
+    }
+    const blocked = await branchInUse(workspacePath, safe);
+    if (blocked)
+        return { removed: false, leftover: `branch ${safe} was left in place (${blocked})` };
+    try {
+        await git(workspacePath, 'branch', '-D', safe);
+        return { removed: true };
+    }
+    catch (error) {
+        return {
+            removed: false,
+            leftover: `branch ${safe} could not be deleted (${describeGitFailure(error)})`,
+        };
+    }
+}
+/** Why `branch` must not be deleted right now, or `null` if nothing objects. */
+async function branchInUse(workspacePath, safe) {
+    const current = await git(workspacePath, 'rev-parse', '--abbrev-ref', 'HEAD').catch(() => null);
+    if (current === safe)
+        return 'the project folder is on it';
+    const holder = await worktreeHolding(workspacePath, safe);
+    if (holder)
+        return `it is checked out in ${holder}`;
+    return null;
+}
+/** Read `git worktree list --porcelain`, treating a failure as «no answer». */
+async function listWorktrees(workspacePath) {
+    return parseWorktrees(await git(workspacePath, 'worktree', 'list', '--porcelain').catch(() => ''));
+}
+/** Parse `git worktree list --porcelain` into one record per worktree. */
+function parseWorktrees(raw) {
+    const entries = [];
+    let current = null;
+    for (const line of raw.split('\n')) {
+        const text = line.trim();
+        if (text.startsWith('worktree ')) {
+            current = {
+                path: text.slice('worktree '.length).trim(),
+                branch: null,
+                detached: false,
+                locked: null,
+            };
+            entries.push(current);
+        }
+        else if (!current) {
+            continue;
+        }
+        else if (text.startsWith('branch ')) {
+            current.branch = text
+                .slice('branch '.length)
+                .trim()
+                .replace(/^refs\/heads\//, '');
+        }
+        else if (text === 'detached') {
+            current.detached = true;
+        }
+        else if (text === 'locked' || text.startsWith('locked ')) {
+            current.locked = text.slice('locked'.length).trim();
+        }
+    }
+    return entries;
+}
+/** The `.git/worktrees/<name>` directory behind a linked worktree, from its `.git` pointer file. */
+function linkedGitDir(worktreePath) {
+    const gitFile = path.join(worktreePath, '.git');
+    try {
+        if (!fs.existsSync(gitFile) || !fs.statSync(gitFile).isFile())
+            return null;
+        const pointer = fs
+            .readFileSync(gitFile, 'utf8')
+            .match(/^gitdir:\s*(.+)$/m)?.[1]
+            ?.trim();
+        return pointer ? path.resolve(worktreePath, pointer) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Did an earlier `git worktree add` die halfway through this folder? (#360)
+ *
+ * The reliable tell is the lock git itself takes while laying out files: it
+ * reads `initializing`, it survives SIGKILL, and neither `worktree remove
+ * --force` («cannot remove a locked working tree») nor `worktree prune` clears
+ * it. The second tell is a detached HEAD with no branch of ours anywhere — what
+ * is left when the crash happened before `checkout -b`.
+ */
+async function looksHalfCreated(workspacePath, worktreePath, head, branch) {
+    const entry = (await listWorktrees(workspacePath)).find((candidate) => path.resolve(candidate.path) === path.resolve(worktreePath));
+    if (entry && entry.locked !== null)
+        return true;
+    const gitDir = linkedGitDir(worktreePath);
+    if (gitDir && fs.existsSync(path.join(gitDir, 'locked')))
+        return true;
+    // «git could not answer» is NOT «the folder is detached». What this predicate
+    // authorises is `worktree remove --force` on a folder that may hold somebody's
+    // uncommitted work, so it only ever runs on a POSITIVE answer. A runner that
+    // lost `safe.directory` (a `--user` reinstall, a `--repair`) makes every
+    // `rev-parse` here reject; reading that silence as «half-created» would have
+    // deleted a live session's worktree on the next restart.
+    if (head !== 'HEAD' && entry?.detached !== true)
+        return false;
+    // The same silence, the other way round: a branch probe that could not run
+    // must not be read as «the branch is not there».
+    const branchProbe = await git(workspacePath, 'rev-parse', '--verify', '--quiet', branch).then(() => 'exists', (error) => 
+    // `--verify --quiet` exits 1 with no output when the ref is simply absent;
+    // anything else (128, a signal, a dubious-ownership fatal) is git failing
+    // to look, which is a different fact.
+    error.code === 1 ? 'absent' : 'unknown');
+    return branchProbe === 'absent';
+}
+/**
+ * Take the folder back: unlock, remove, prune. The unlock goes FIRST — a lock
+ * left by a killed `worktree add` blocks every other rung of the ladder.
+ */
+async function discardWorktreeFolder(workspacePath, worktreePath) {
+    await git(workspacePath, 'worktree', 'unlock', worktreePath).catch(() => undefined);
+    const removed = await git(workspacePath, 'worktree', 'remove', '--force', worktreePath)
+        .then(() => true)
+        .catch(() => false);
+    if (!removed) {
+        try {
+            fs.rmSync(worktreePath, { recursive: true, force: true });
+        }
+        catch (error) {
+            // Deliberately NOT `describeGitFailure`: git was never asked. Telling the
+            // operator «git failed: EACCES» sends them to look at the wrong program.
+            const detail = String(error instanceof Error ? error.message : error).slice(0, 180);
+            return {
+                ok: false,
+                leftovers: [`the folder ${worktreePath} could not be removed (${detail})`],
+            };
+        }
+    }
+    await git(workspacePath, 'worktree', 'prune').catch(() => undefined);
+    if (fs.existsSync(worktreePath)) {
+        return { ok: false, leftovers: [`the folder ${worktreePath} is still there`] };
+    }
+    const registrations = await git(workspacePath, 'worktree', 'list', '--porcelain').then((raw) => parseWorktrees(raw), () => null);
+    if (registrations === null) {
+        // Same rule as `dropEmptySessionBranch`: a check that could not run is not
+        // a check that passed.
+        return {
+            ok: false,
+            leftovers: [`could not check whether git still lists ${worktreePath} as a worktree`],
+        };
+    }
+    if (registrations.some((entry) => path.resolve(entry.path) === path.resolve(worktreePath))) {
+        return {
+            ok: false,
+            leftovers: [`git still lists ${worktreePath} as a worktree (it may still be locked)`],
+        };
+    }
+    return { ok: true, leftovers: [] };
+}
 /**
  * DIRECT mode (session 16): the session's workplace IS the project folder.
  *
@@ -310,21 +778,8 @@ async function resolveStartPoint(workspacePath, plan) {
 }
 /** Which worktree, if any, currently has `branch` checked out. */
 async function worktreeHolding(workspacePath, branch) {
-    const raw = await git(workspacePath, 'worktree', 'list', '--porcelain').catch(() => '');
-    let current = null;
-    for (const line of raw.split('\n')) {
-        if (line.startsWith('worktree '))
-            current = line.slice('worktree '.length).trim();
-        else if (line.startsWith('branch ') && current) {
-            if (line
-                .slice('branch '.length)
-                .trim()
-                .replace(/^refs\/heads\//, '') === branch) {
-                return current;
-            }
-        }
-    }
-    return null;
+    const entry = (await listWorktrees(workspacePath)).find((item) => item.branch === branch);
+    return entry ? entry.path : null;
 }
 // ─── Preview worktree (session 14) ───────────────────────────────────
 /**
@@ -363,7 +818,7 @@ export async function ensurePreviewWorktree(input) {
         await git(worktreePath, 'clean', '-fd').catch(() => undefined);
         return { worktreePath, branch, sha };
     }
-    await git(input.workspacePath, 'worktree', 'add', '--detach', worktreePath, sha);
+    await addDetachedWorktree(input.workspacePath, worktreePath, sha);
     return { worktreePath, branch, sha };
 }
 /** Give the slot back. The branch is untouched — it was never checked out. */
@@ -411,13 +866,9 @@ export async function deleteSessionBranch(workspacePath, branch) {
     // its stale registration would answer «still checked out» and leave a branch
     // behind on every ordinary purge.
     await git(workspacePath, 'worktree', 'prune').catch(() => undefined);
-    const current = await git(workspacePath, 'rev-parse', '--abbrev-ref', 'HEAD').catch(() => null);
-    if (current === safe) {
-        throw new Error(`refusing to delete ${safe}: the project folder is on it`);
-    }
-    const holder = await worktreeHolding(workspacePath, safe);
-    if (holder) {
-        throw new Error(`refusing to delete ${safe}: it is checked out in ${holder}`);
+    const blocked = await branchInUse(workspacePath, safe);
+    if (blocked) {
+        throw new Error(`refusing to delete ${safe}: ${blocked}`);
     }
     await git(workspacePath, 'branch', '-D', safe);
 }

package/dist/gitops.d.ts

@@ -325,6 +325,11 @@ export interface GitBranchesResult {
     /** What the project folder is on right now. */
     currentBranch: string | null;
     currentSha: string | null;
+    /**
+     * The repository's own main branch (ADR 0004) — not the same question as
+     * `currentBranch`, which is «where the folder happens to stand today».
+     */
+    defaultBranch: string | null;
     remotes: string[];
     truncated: boolean;
 }

package/dist/gitops.js

@@ -2,7 +2,7 @@ import { execFile } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { promisify } from 'node:util';
-import { sanitizeBranch } from './git.js';
+import { firstConventionalBranch, remoteDefaultBranch, sanitizeBranch } from './git.js';
 import { isSecretPath, maskString } from './policy.js';
 const execFileAsync = promisify(execFile);
 const GIT_TIMEOUT_MS = 30_000;
@@ -250,13 +250,11 @@ async function guessBase(workspacePath, sessionBranch) {
     if (current !== sessionBranch && current !== 'HEAD') {
         return { baseBranch: current, baseRef: current };
     }
-    for (const candidate of ['main', 'master']) {
-        const exists = await git(workspacePath, 'rev-parse', '--verify', '--quiet', candidate)
-            .then(() => true)
-            .catch(() => false);
-        if (exists)
-            return { baseBranch: candidate, baseRef: candidate };
-    }
+    // One list, one order, one place — the same helper the binding uses to learn
+    // the project's main branch (ADR 0004).
+    const conventional = await firstConventionalBranch(workspacePath);
+    if (conventional)
+        return { baseBranch: conventional, baseRef: conventional };
     throw new Error(`Cannot determine the base branch (workspace is on ${current})`);
 }
 /** How far apart two refs are, in one call: `[behind, ahead]`. */
@@ -1384,6 +1382,7 @@ export async function gitBranches(workspacePath) {
         branches,
         currentBranch: currentBranch === 'HEAD' ? null : currentBranch,
         currentSha: await git(workspacePath, 'rev-parse', 'HEAD').catch(() => null),
+        defaultBranch: await remoteDefaultBranch(workspacePath).catch(() => null),
         remotes: remotesRaw.split('\n').filter(Boolean).slice(0, 20),
         truncated,
     };