looply-cli 0.0.0-stage → 0.2.0

package/dist/workspace.js

@@ -0,0 +1,2026 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RunRegistry = exports.WorkspaceError = exports.nodeProbe = exports.WORKSPACES_DIR = void 0;
+exports.forgetCreationMarker = forgetCreationMarker;
+exports.workspacesRoot = workspacesRoot;
+exports.requestControlEverywhere = requestControlEverywhere;
+exports.createWorkspace = createWorkspace;
+exports.reapableCheckout = reapableCheckout;
+exports.reapVerdict = reapVerdict;
+exports.workspaceResidue = workspaceResidue;
+exports.retainEvidence = retainEvidence;
+exports.reapWorkspace = reapWorkspace;
+exports.abandonedWorkspaces = abandonedWorkspaces;
+exports.checkoutBusy = checkoutBusy;
+exports.creationMarkerHolder = creationMarkerHolder;
+exports.clearCreationMarker = clearCreationMarker;
+exports.clearAddressedControl = clearAddressedControl;
+exports.reapAbandoned = reapAbandoned;
+const node_fs_1 = require("node:fs");
+const checkout_carry_1 = require("./checkout-carry");
+const node_crypto_1 = require("node:crypto");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const git_driver_1 = require("./git-driver");
+const trusted_git_1 = require("./trusted-git");
+const run_lease_1 = require("./run-lease");
+const control_file_1 = require("./control-file");
+const workspace_residue_sweep_1 = require("./workspace-residue-sweep");
+const workspace_quarantine_1 = require("./workspace-quarantine");
+/**
+ * WHERE A SECOND EXECUTION LIVES, AND WHO IS ALLOWED TO SAY SO.
+ *
+ * Phase 1 makes two executions safe by giving each its own checkout and its own
+ * execution state directory, rather than by making a dozen single-writer stores
+ * multi-writer. That is the cheaper half of a decision the recon argued at
+ * length: every store already takes `stateDir` as its first argument, so N state
+ * directories are already expressible — what was missing was a place to put
+ * them and something that knows they exist.
+ *
+ * TWO THINGS LIVE HERE AND THEY ARE DELIBERATELY SEPARATE:
+ *
+ *   the WORKSPACE   a linked git worktree plus its own `.looply/state`. Created
+ *                   through `GitDriver`, so it inherits every Phase 0/0.5
+ *                   defence rather than reimplementing a safe-enough subset.
+ *   the REGISTRY    one exclusively-created file per live execution, under the
+ *                   PROJECT's state directory. It is what makes capacity
+ *                   countable, `status` aggregable, and an orphan identifiable.
+ *
+ * ⚠️ THE REGISTRY IS NOT A LOCK. The run lease is still the mutual exclusion,
+ * still one per execution state directory, and still the thing that decides
+ * whether a checkout is busy. The registry answers a different question — "what
+ * else is running for this project" — which no lease can answer because leases
+ * cannot see each other.
+ */
+/** How a workspace's own directory is named under the workspaces root. */
+exports.WORKSPACES_DIR = 'workspaces';
+/**
+* Clear a workspace's creation marker, by name.
+*
+* 🔴 A MARKER WHOSE PID IS RECYCLED PINS ITS WORKSPACE AS "in use" FOR EVER.
+* `looply runs` shows it, `--reap` refuses it because something appears to be
+* using it, and nothing else can ever say otherwise — the same permanent wedge
+* a recycled pid makes of a slot, in a place with no `--release` to reach it.
+*
+* ⚠️ IT CLEARS THE MARKER, NOT THE CHECKOUT. Afterwards the workspace is
+* ordinary: `--reap` judges it on residue and evidence like any other, and will
+* still keep it if it holds a person's files.
+*/
+function forgetCreationMarker(cwd, name) {
+    /**
+     * ⚠️ A DIRECTORY BASENAME, NOT A RUN ID. This used `safeRunId`, which THREW on
+     * anything outside `[A-Za-z0-9_-]` — so a directory under the workspaces root
+     * with a dot in its name was both listed as busy and permanently unclearable,
+     * and typing its name crashed the command instead of answering it.
+     *
+     * The requirement is only that it name ONE directory directly under the
+     * workspaces root: no separators, nothing that could climb.
+     */
+    if (name === '' || name === '.' || name === '..' || /[\/]/.test(name)) {
+        throw new WorkspaceError(`${JSON.stringify(name)} is not the name of a workspace`);
+    }
+    const at = (0, node_path_1.join)(workspacesRoot(cwd), name, git_driver_1.STATE_DIR, 'state', CREATING);
+    try {
+        (0, node_fs_1.unlinkSync)(at);
+        return true;
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return false;
+        throw e;
+    }
+}
+/**
+ * Where every workspace for a project lives — OUTSIDE the repository.
+ *
+ * 🔴 IT WAS INSIDE, AND THAT WAS WRONG. The first version put workspaces under
+ * `<root>/.looply/workspaces`, and `.gitignore` covers `.looply/state/` and
+ * `.looply/runs/` but not that. Measured: creating one workspace turned the main
+ * checkout's `git status --porcelain` into `?? .looply/`. Looply's own dirty
+ * check would not have noticed — `changedPaths` filters `.looply/**` — but a
+ * PERSON would, and a person who then typed `git add -A` would commit an entire
+ * second checkout into their repository.
+ *
+ * `~/.looply` is where this codebase already puts state that must survive the
+ * repository, and for the same stated reason: `git clean -fd` would delete
+ * in-tree credentials. A workspace has exactly that property.
+ *
+ * ⚠️ KEYED BY A HASH OF THE MAIN WORKTREE PATH, not by the project's name. Two
+ * checkouts of the same repository in two places are two projects here, which is
+ * the same identity rule `containerName` and `providerSessionDir` already use.
+ */
+function workspacesRoot(cwd, home = (0, node_os_1.homedir)()) {
+    /**
+     * 🔴 THE SAME IDENTITY THE REGISTRY USES, and it briefly was not.
+     *
+     * `projectStateDir` learned to fall back to the common dir for a repository
+     * with no main worktree — `clone --bare` plus two `worktree add`s — so those
+     * checkouts share ONE registry. This still keyed on `mainWorktreeRoot ??
+     * cwd`, which is null there, so each checkout got its OWN workspaces root
+     * while sharing the records. A record written from checkout A then named a
+     * path under A's root, and a `--reap` run from B computed B's root and
+     * refused it as "not under this project's workspaces root" — for ever, with a
+     * reason that was true and useless.
+     *
+     * ⚠️ AN ORDINARY CHECKOUT AND A LINKED WORKTREE ARE UNCHANGED:
+     * `repoIdentityPath` answers the main worktree root for both, which is
+     * exactly what this hashed before.
+     */
+    const root = (0, trusted_git_1.repoIdentityPath)(cwd);
+    const key = (0, node_crypto_1.createHash)('sha256').update(root.toLowerCase(), 'utf8').digest('hex').slice(0, 16);
+    return (0, node_path_1.join)(home, '.looply', exports.WORKSPACES_DIR, key);
+}
+exports.nodeProbe = run_lease_1.nodeProbe;
+/**
+ * Errno values that mean "somebody else got there", not "something is broken".
+ *
+ * 🔴 `EEXIST` ALONE IS NOT ENOUGH ON WINDOWS, and this was measured rather than
+ * assumed. An exclusive create against a path another process is deleting at
+ * that instant fails with **EPERM**, because the file sits in a pending-delete
+ * state where it can be neither opened nor re-created. Under 240 concurrent
+ * claims it happened 4 times, and each one threw straight out of `claim` and
+ * killed the run with a raw filesystem error instead of refusing politely.
+ *
+ * Every one of these reads as losing a race, which is the conservative answer in
+ * all three places it is used: the slot is not taken, the reclaim token is not
+ * held, and the stale file is not removed.
+ */
+const LOST_THE_RACE = new Set(['EEXIST', 'EPERM', 'EACCES', 'EBUSY']);
+/**
+ * A runId that is safe to use as a PATH SEGMENT.
+ *
+ * ⚠️ RUN IDS REACH THIS FILE FROM TWO UNTRUSTED DIRECTIONS, and both end in a
+ * `join` followed by an `unlink` or a recursive copy:
+ *
+ *   from disk     a registry record is a JSON file. Anything that can write the
+ *                 project's state directory can put `../../..` in a `runId`.
+ *   from a person `looply runs --release <name>` passes what was typed straight
+ *                 through to `forget`.
+ *
+ * `newId('run')` only ever mints `[A-Za-z0-9_]`, so nothing legitimate is
+ * refused. This is not defence against the owner of the machine — it is defence
+ * against a path escaping the one directory these functions are allowed to
+ * touch, which is the same rule the reaper's realpath containment enforces for
+ * workspaces.
+ */
+const RUN_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+function safeRunId(runId) {
+    if (!RUN_ID.test(runId)) {
+        throw new WorkspaceError(`${JSON.stringify(runId)} is not a run id this can address`);
+    }
+    return runId;
+}
+class WorkspaceError extends Error {
+}
+exports.WorkspaceError = WorkspaceError;
+/**
+ * The registry of live executions for one project.
+ *
+ * Entries are one file each, created with `wx`, exactly as the run lease is —
+ * the filesystem decides the winner, no read-then-write, and a crash leaves a
+ * file that can be judged rather than a lock nobody can clear.
+ */
+class RunRegistry {
+    projectState;
+    probe;
+    constructor(projectState, probe = exports.nodeProbe) {
+        this.projectState = projectState;
+        this.probe = probe;
+    }
+    get dir() {
+        return (0, node_path_1.join)(this.projectState, 'runs');
+    }
+    pathFor(runId) {
+        return (0, node_path_1.join)(this.dir, `${safeRunId(runId)}.json`);
+    }
+    /**
+     * Claim a slot. Throws if this runId is already registered.
+     *
+     * ⚠️ EXCLUSIVE CREATE, not "check then write". Two executions starting in the
+     * same moment must not both believe they took the last slot, and only the
+     * filesystem can arbitrate that without a lock of our own.
+     */
+    register(record) {
+        (0, node_fs_1.mkdirSync)(this.dir, { recursive: true });
+        try {
+            (0, node_fs_1.writeFileSync)(this.pathFor(record.runId), `${JSON.stringify(record, null, 2)}\n`, { flag: 'wx' });
+        }
+        catch (e) {
+            if (e.code === 'EEXIST') {
+                throw new WorkspaceError(`this run is already registered: ${record.runId}`);
+            }
+            throw e;
+        }
+    }
+    /**
+     * Take one of `limit` slots, or refuse. THIS is the bound.
+     *
+     * 🔴 COUNTING WAS CHECK-THEN-ACT AND CLAIMED NOT TO BE. `capacityVerdict`
+     * read `active()`, judged, and only then did anything get created — and the
+     * exclusive `wx` this class pointed at as "the arbitration" is keyed on
+     * `runId`, minted fresh per run. Two runs starting together could never
+     * collide on that name, so both passed the count and both registered. Nothing
+     * upstream helped: two workspaces hold two different leases, and a lease
+     * cannot see another checkout.
+     *
+     * The SLOT is the exclusive thing. There are at most `limit` slot names, so at
+     * most `limit` runs can hold one, and the filesystem decides — exactly as it
+     * does for the run lease and the override marker.
+     *
+     * ⚠️ A SLOT HELD BY A DEAD PROCESS IS RECLAIMED, not counted. Otherwise one
+     * crash would lower this machine's concurrency until somebody noticed, which
+     * is the capacity leak this exists to avoid.
+     */
+    claim(record, limit) {
+        (0, node_fs_1.mkdirSync)(this.dir, { recursive: true });
+        /**
+         * 🔴 TAKING A SLOT AND DECIDING WHETHER TO KEEP IT MUST BE ONE STEP.
+         *
+         * `settle` counts the other holders after winning an exclusive create — the
+         * only place the answer cannot be raced by another `wx`. But two claimants
+         * BETWEEN their own take and their own count each see a world without the
+         * other, and both keep. The first version tried to break that tie by slot
+         * number, which works only when the lower-numbered claimant takes first; a
+         * holder that vanishes mid-claim reverses the order and both keep.
+         *
+         * A count cannot be made atomic, so the WINDOW is closed instead: one
+         * claimant at a time is between its take and its decision. Contention is
+         * brief — a few filesystem calls — and rare, because starting a run is not a
+         * hot path.
+         *
+         * ⚠️ AND THE LOCK IS NOT WHAT MAKES THE BOUND HOLD, which an earlier version
+         * of this comment implied. `settle` counts the other holders AFTER its own
+         * exclusive create, so a later claimant always sees an earlier one and the
+         * total can only ever climb to the limit — without any lock at all. What the
+         * lock prevents is the opposite failure: several claimants counting at the
+         * same instant, all seeing a full machine, and ALL backing out, leaving it
+         * idle below its own limit. That distinction decides what may break a stale
+         * lock, and the answer is: anything that cannot name a live owner.
+         *
+         * ⚠️ AND A LOCK LEFT BY A CRASH IS BROKEN ONLY IF ITS OWNER IS PROVEN DEAD,
+         * exactly as the reclaim token is. Otherwise one crash mid-claim would stop
+         * this project ever starting a run again.
+         */
+        const lock = (0, node_path_1.join)(this.dir, 'claim.lock');
+        if (!this.waitForToken(lock)) {
+            return {
+                ok: false,
+                because: 'another start is deciding whether it can run, and did not finish. ' +
+                    'Try again; if this repeats, `looply runs` will show what is holding on',
+            };
+        }
+        try {
+            return this.claimUnderLock(record, limit);
+        }
+        finally {
+            /**
+             * 🔴 BY NAME, NOT BY PATH. This unlinked whatever lock was there, so once
+             * ANY break had happened — and a measured run of the previous version
+             * broke 155 live owners' locks — a second claimant's exit deleted a third
+             * claimant's lock, and the loss cascaded: up to three processes were
+             * observed inside the critical section at once.
+             *
+             * Every other release in this class is keyed on identity. This one is now
+             * too, for the same reason and by the same rule.
+             */
+            this.dropToken(lock);
+        }
+    }
+    /** Wait a short while for the claim lock, breaking one a dead process left. */
+    waitForToken(lock) {
+        const wait = new Int32Array(new SharedArrayBuffer(4));
+        for (let attempt = 0; attempt < 100; attempt += 1) {
+            if (this.takeToken(lock))
+                return true;
+            // 20ms, synchronously. `claim` is sync by design — every one of its
+            // decisions is a filesystem fact — and this is the only place it waits.
+            Atomics.wait(wait, 0, 0, 20);
+        }
+        return false;
+    }
+    claimUnderLock(record, limit) {
+        const held = [];
+        /**
+         * ⚠️ THERE IS NO PRE-COUNT, AND THERE WAS ONE.
+         *
+         * It walked every slot file before the scan, so that slots ABOVE the limit —
+         * which the `[0, limit)` scan cannot see — still counted. But a count is not
+         * arbitration: several starts could all pass it and then all win different
+         * in-range slots, which is how five executions ran at a limit of three.
+         *
+         * `settle` replaced it, and does the same job on the other side of the
+         * exclusive create, where the answer cannot be raced. Keeping both would
+         * have left the weaker one able to refuse a start the stronger one would
+         * have allowed — a stray slot file turning every start into a refusal
+         * BEFORE anything had a chance to judge it.
+         */
+        for (let slot = 0; slot < limit; slot += 1) {
+            const path = this.slotPath(slot);
+            if (!(0, node_fs_1.existsSync)(path)) {
+                if (this.take(path, record, slot))
+                    return this.settle(slot, limit, record);
+                held.push(this.readSlot(path) ?? 'unreadable');
+                continue;
+            }
+            const taken = this.readSlot(path);
+            if (taken === null) {
+                /**
+                 * 🔴 UNREADABLE FAILS CLOSED, AND IT USED TO FAIL OPEN.
+                 *
+                 * The old code read "cannot parse" as "nobody is using it", deleted the
+                 * file and took the slot. But a slot file is written by another process
+                 * and read without coordination, so the commonest way to see an
+                 * unparseable one is to catch a LIVE claim mid-write — at which point
+                 * this deletes a running execution's slot and starts a second run past
+                 * the limit. The run lease, which this class says it mirrors, fails
+                 * closed on exactly this and calls the state `ambiguous`.
+                 *
+                 * The cost is that an unreadable slot holds capacity until a person
+                 * clears it. That is why `looply runs` lists slots as well as records,
+                 * and why `--release slot-<n>` exists.
+                 */
+                held.push('unreadable');
+                continue;
+            }
+            if (this.probe(taken.pid) !== 'dead' && this.leaseAgrees(taken)) {
+                // ⚠️ BOTH WITNESSES MUST AGREE IT IS STILL RUNNING. A pid that is alive
+                // or unjudgeable is not enough on its own — a recycled pid looks exactly
+                // like that — and neither is a lease left behind by a crash. Either one
+                // saying 'gone' frees the slot; only both saying 'here' holds it.
+                held.push(taken);
+                continue;
+            }
+            if (!this.reclaim(path, taken)) {
+                held.push(this.readSlot(path) ?? 'unreadable');
+                continue;
+            }
+            if (this.take(path, record, slot))
+                return this.settle(slot, limit, record);
+            held.push(this.readSlot(path) ?? 'unreadable');
+        }
+        /**
+         * ⚠️ THE REFUSAL COUNTS EVERY HOLDER, not just the ones the scan walked.
+         * The scan sees `[0, limit)`; a person who lowered the limit has holders
+         * above it, and a message saying "2 executions and the limit is 2" while
+         * three were running would be true about the scan and false about the
+         * machine.
+         */
+        return { ok: false, because: this.atCapacity(this.allHolders(), limit) };
+    }
+    /**
+     * Having WON a slot, decide whether it may be kept.
+     *
+     * 🔴 THE OVER-LIMIT COUNT WAS CHECK-THEN-ACT, and it was the only thing that
+     * could see slots above the limit. The exclusive `wx` is the arbitration for
+     * `[0, limit)` and nothing else, so with two live runs on out-of-range slots
+     * and the limit lowered, several starts could all pass the count and then all
+     * win DIFFERENT in-range slots. Reproduced: five executions at a limit of
+     * three. The fix for one hole opened a smaller one beside it.
+     *
+     * A count cannot be made atomic, so the decision moves AFTER the exclusive
+     * create: take the slot, then look. At most `limit` in-range slots can exist,
+     * so what is left to judge is how many holders there are in total.
+     *
+     * ⚠️ THE TIE-BREAK IS THE SLOT NUMBER, so simultaneous winners do not all back
+     * out and leave the machine idle. A holder keeps its slot when the holders
+     * BELOW it, plus every out-of-range holder, still leave room; otherwise it
+     * gives the slot back and refuses. Deterministic, and it always leaves exactly
+     * as many runs as the limit allows.
+     */
+    settle(slot, limit, record) {
+        const others = this.allHolders(slot);
+        if (others.length < limit)
+            return { ok: true, slot };
+        this.releaseSlot(slot, record.runId);
+        return { ok: false, because: this.atCapacity(others, limit) };
+    }
+    /**
+     * The claim lock, if one is being held, and by whom.
+     *
+     * 🔴 A WEDGED LOCK WAS INVISIBLE TO EVERY COMMAND. It is only breakable when
+     * its owner is PROVEN dead, so a lock left by a process that is alive but
+     * hung — or by one whose pid cannot be judged — denied every start of the
+     * project with a message about "another start deciding" and no way to see or
+     * clear it. That is the same wedge the slot files had before `looply runs`
+     * listed them.
+     */
+    claimLock() {
+        const path = (0, node_path_1.join)(this.dir, 'claim.lock');
+        let text;
+        try {
+            text = (0, node_fs_1.readFileSync)(path, 'utf8').trim();
+        }
+        catch {
+            return null;
+        }
+        const pid = Number.parseInt(text, 10);
+        if (!Number.isInteger(pid))
+            return { pid: null, liveness: 'unknown' };
+        return { pid, liveness: this.probe(pid) };
+    }
+    /** Clear a held claim lock. A person's last resort, as `forgetSlot` is. */
+    forgetClaimLock() {
+        try {
+            (0, node_fs_1.unlinkSync)((0, node_path_1.join)(this.dir, 'claim.lock'));
+            return true;
+        }
+        catch (e) {
+            if (e.code === 'ENOENT')
+                return false;
+            throw e;
+        }
+    }
+    /** Every slot that is still held, whatever its number. `except` is skipped. */
+    allHolders(except) {
+        const out = [];
+        for (const s of this.slots()) {
+            if (s.slot === except)
+                continue;
+            if (s.record === null)
+                out.push('unreadable');
+            else if (this.probe(s.record.pid) !== 'dead' && this.leaseAgrees(s.record))
+                out.push(s.record);
+        }
+        return out;
+    }
+    atCapacity(held, limit) {
+        /**
+         * 🔴 A REFUSAL THAT REPORTS FEWER HOLDERS THAN THE LIMIT IS NOT A REFUSAL A
+         * PERSON CAN ACT ON. The decision and this message are two observations of
+         * the world — the scan judged, then this walks again — and holders can
+         * finish in between. "already has 0 execution(s) holding a slot and the
+         * limit is 1" is what that looks like, and it reads as a bug in looply
+         * rather than as a race that will resolve itself.
+         */
+        if (held.length < limit) {
+            return ('every slot was taken while this run was deciding, and they have since ' +
+                'been given back. Nothing is wrong — start it again');
+        }
+        const unreadable = held.filter((h) => h === 'unreadable').length;
+        const names = held
+            .filter((h) => h !== 'unreadable')
+            .map((r) => `${r.runId} in ${(0, node_path_1.basename)(r.workspace)}`)
+            .join(', ');
+        return (`this project already has ${held.length} execution(s) holding a slot and the limit is ${limit}` +
+            (names === '' ? '' : ` (${names})`) +
+            (unreadable === 0 ? '' : `, and ${unreadable} slot file(s) could not be read`) +
+            '. Raise run.max_concurrent_runs, or wait for one to finish. ' +
+            'If one of those is not really running, looply runs will say so, and ' +
+            'looply runs --release <runId|slot-N> clears it by name');
+    }
+    /**
+     * Take a free slot. The ONLY way a slot file is ever created.
+     *
+     * ⚠️ `wx` AND NOTHING ELSE. No read first, no delete first: the filesystem is
+     * the arbitration, exactly as it is for the run lease and the override marker.
+     */
+    take(path, record, slot) {
+        try {
+            (0, node_fs_1.writeFileSync)(path, `${JSON.stringify({ ...record, slot }, null, 2)}\n`, { flag: 'wx' });
+            return true;
+        }
+        catch (e) {
+            if (LOST_THE_RACE.has(e.code ?? ''))
+                return false;
+            throw e;
+        }
+    }
+    /**
+     * Remove a slot file whose holder is proven gone — or refuse to.
+     *
+     * 🔴 THE OLD RECLAIM WAS UNLINK-THEN-CREATE, WHICH IS THE CHECK-THEN-ACT THIS
+     * WHOLE CLASS EXISTS TO REMOVE. It judged a slot stale, unlinked it BY PATH,
+     * and only then tried its exclusive create. Two starters that both saw the
+     * same stale slot both unlinked — and the second unlink deleted the FIRST
+     * one's freshly created file, so both believed they held slot 0 and both ran.
+     * At limit 1. Reproduced with real concurrent processes.
+     *
+     * Two things fix it, and the second is the one that actually holds:
+     *
+     *   THE TOKEN     `slot-<n>.reclaiming`, created with `wx`. At most one
+     *                 process reclaims a given slot at a time, so the common case
+     *                 has no race to lose.
+     *   THE RE-READ   nothing is unlinked unless it is STILL the same record this
+     *                 judged, and still gone. A slot that has been re-taken names
+     *                 a different runId, and a different runId is never removed.
+     *
+     * The re-read is what makes this correct even if the token were somehow held
+     * twice — after a crash, say. The token only makes the correct path the quiet
+     * one.
+     *
+     * ⚠️ A TOKEN LEFT BY A CRASH IS BROKEN ONLY IF ITS OWN PID IS PROVEN DEAD, and
+     * then the re-read still decides. Otherwise a crash during reclaim would wedge
+     * one slot of this project for ever.
+     */
+    reclaim(path, stale) {
+        const token = `${path}.reclaiming`;
+        if (!this.takeToken(token))
+            return false;
+        try {
+            if (!(0, node_fs_1.existsSync)(path))
+                return true;
+            const now = this.readSlot(path);
+            // Unreadable now: fail closed, exactly as the caller does.
+            if (now === null)
+                return false;
+            // Somebody else's slot now. Never ours to remove.
+            if (now.runId !== stale.runId)
+                return false;
+            if (this.probe(now.pid) !== 'dead' && this.leaseAgrees(now))
+                return false;
+            try {
+                (0, node_fs_1.unlinkSync)(path);
+            }
+            catch (e) {
+                // Gone, or held open by the process that is exiting. Either way this did
+                // not take the slot, and saying so is safer than throwing.
+                if (!LOST_THE_RACE.has(e.code ?? '') && e.code !== 'ENOENT') {
+                    throw e;
+                }
+                if (e.code !== 'ENOENT')
+                    return false;
+            }
+            return true;
+        }
+        finally {
+            // By name, as the claim lock is: a token this process does not hold is
+            // not this process's to remove.
+            this.dropToken(token);
+        }
+    }
+    takeToken(token) {
+        const write = () => {
+            try {
+                (0, node_fs_1.writeFileSync)(token, `${process.pid}\n`, { flag: 'wx' });
+                return true;
+            }
+            catch (e) {
+                if (LOST_THE_RACE.has(e.code ?? ''))
+                    return false;
+                throw e;
+            }
+        };
+        if (write())
+            return true;
+        /**
+         * Held. Break it only if it cannot be DEFENDED — its owner is proven dead,
+         * or it names no owner at all.
+         *
+         * 🔴 THE SECOND CASE WAS MISSING, AND IT WEDGED EVERYTHING. `writeFileSync`
+         * creates and then writes, so a crash between the two leaves a ZERO-BYTE
+         * lock. `parseInt('')` is NaN, NaN is not an integer, so the lock could
+         * never be broken — and every `looply run` in that project waited two
+         * seconds and refused, for ever, over an empty file. Measured.
+         *
+         * Breaking an un-owned token is safe in both places it is used. The reclaim
+         * token's correctness rests on the RE-READ that follows it, not on the
+         * token. And the claim lock is not what makes the bound hold — `settle`
+         * counts the other holders AFTER an exclusive create, so a second claimant
+         * always sees the first; the lock stops the machine sitting IDLE when
+         * several claimants back out together, which is a liveness property, not a
+         * safety one.
+         */
+        let owner = Number.NaN;
+        let judged = '';
+        try {
+            judged = this.settledText(token);
+            const text = judged;
+            if (text === '') {
+                /**
+                 * 🔴 AN EMPTY TOKEN IS NOT NECESSARILY ABANDONED, and the first version
+                 * of this break assumed it was. `writeFileSync(path, data, {flag:'wx'})`
+                 * opens exclusively and THEN writes, so a LIVE claimant's token is empty
+                 * for the moment in between — and a second claimant that read it in that
+                 * moment broke a lock somebody was holding.
+                 *
+                 * `settledText` re-reads over a short window first. A live writer fills
+                 * it in microseconds; a crash between the two syscalls never will.
+                 */
+                this.breakToken(token, '');
+                return write();
+            }
+            owner = Number.parseInt(text, 10);
+        }
+        catch (e) {
+            // Gone between the failed create and this read: try again.
+            if (e.code === 'ENOENT')
+                return write();
+            return false;
+        }
+        if (!Number.isInteger(owner)) {
+            this.breakToken(token, judged);
+            return write();
+        }
+        if (this.probe(owner) !== 'dead')
+            return false;
+        this.breakToken(token, judged);
+        return write();
+    }
+    /**
+     * The token's contents, once they have stopped changing.
+     *
+     * An exclusive create is two syscalls — open, then write — so a token read in
+     * between is empty through no fault of its holder. This re-reads over a short
+     * window and only reports empty if it stays empty.
+     */
+    settledText(token) {
+        const wait = new Int32Array(new SharedArrayBuffer(4));
+        for (let attempt = 0;; attempt += 1) {
+            const text = (0, node_fs_1.readFileSync)(token, 'utf8').trim();
+            if (text !== '' || attempt >= 5)
+                return text;
+            Atomics.wait(wait, 0, 0, 10);
+        }
+    }
+    /** Give back a token THIS process holds. One held by anybody else is left. */
+    dropToken(token) {
+        let text;
+        try {
+            text = (0, node_fs_1.readFileSync)(token, 'utf8').trim();
+        }
+        catch {
+            // Gone, or unreadable. Either way not ours to remove on a guess.
+            return;
+        }
+        if (Number.parseInt(text, 10) !== process.pid)
+            return;
+        // Pass what was read, so `breakToken` can confirm nothing changed under it.
+        this.breakToken(token, text);
+    }
+    /**
+     * Remove a token judged un-defendable — and ONLY if it is still the one that
+     * was judged.
+     *
+     * 🔴 THIS UNLINKED BY PATH. Two processes could both judge the same stale lock
+     * breakable; the first broke it and won the exclusive create, and the second —
+     * still inside its own break — then unlinked the FIRST one's fresh lock and
+     * created its own. Both were inside the critical section, and the loss
+     * cascaded from there. An adversarial pass measured up to four at once.
+     *
+     * `judged` is the content this decided about. If the file no longer says that,
+     * somebody else has already acted and this must not.
+     */
+    breakToken(token, judged) {
+        try {
+            if ((0, node_fs_1.readFileSync)(token, 'utf8').trim() !== judged)
+                return;
+        }
+        catch {
+            return; // gone already, or unreadable: not ours to remove on a guess
+        }
+        try {
+            (0, node_fs_1.unlinkSync)(token);
+        }
+        catch {
+            /* somebody broke it first */
+        }
+    }
+    /**
+     * Give back the slot THIS run holds. A slot held by anybody else is left.
+     *
+     * 🔴 IT USED TO UNLINK BY INDEX, unconditionally, and that was the worst
+     * defect in this file. `releaseHold` gives the lease back BEFORE the slot, and
+     * `claim` treats a slot whose holder's lease is gone as free — so between
+     * those two lines another run could legitimately reclaim slot N, and this
+     * run's teardown would then delete the NEW holder's claim. The bound is
+     * exceeded, and it stays exceeded: the same window reopens at every teardown.
+     *
+     * Every sibling here is keyed on identity — `release(runId)`, `forget(runId)`.
+     * This one is now too. Absent is success, and so is a slot that has moved on.
+     */
+    releaseSlot(slot, runId) {
+        const path = this.slotPath(slot);
+        const held = this.readSlot(path);
+        if (held === null) {
+            // Absent is success. Unreadable is NOT ours to delete: it may be a live
+            // claim caught mid-write, and this is the one place that could delete it.
+            return;
+        }
+        if (held.runId !== runId)
+            return;
+        try {
+            (0, node_fs_1.unlinkSync)(path);
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+        }
+    }
+    /** Every slot, as a person needs to see it — including ones nothing can read. */
+    slots() {
+        let names;
+        try {
+            names = (0, node_fs_1.readdirSync)(this.dir).filter((n) => n.startsWith('slot-') && n.endsWith('.json'));
+        }
+        catch {
+            return [];
+        }
+        return (names
+            .map((n) => ({
+            slot: Number.parseInt(n.slice('slot-'.length), 10),
+            record: this.readSlot((0, node_path_1.join)(this.dir, n)),
+            path: (0, node_path_1.join)(this.dir, n),
+        }))
+            /**
+             * ⚠️ NUMBERED SLOTS ONLY. `slot-abc.json` parses to `NaN`, and NaN loses
+             * every comparison: `NaN >= limit` is false, so such a file would be
+             * invisible to the bound's over-limit count while still sitting in the
+             * directory. A slot nothing can name is not a slot — but it is still a
+             * file, so it is reported by `strayFiles()` below and printed by
+             * `looply runs`, rather than silently counted or silently ignored.
+             */
+            /**
+             * ⚠️ AND THE NUMBER MUST ROUND-TRIP THROUGH THE FILENAME. `parseInt` is
+             * lenient: `slot-01.json` parses to 1, and `forgetSlot(1)` then deletes
+             * `slot-1.json` — a different file, or none. A slot a person is shown
+             * and cannot clear is worse than one that is never shown.
+             */
+            .filter((s) => Number.isInteger(s.slot) && s.slot >= 0)
+            .filter((s) => (0, node_path_1.basename)(s.path) === `slot-${s.slot}.json`)
+            .sort((a, b) => a.slot - b.slot));
+    }
+    /**
+     * The files in the slots directory that `slots()` refuses to name.
+     *
+     * 🔴 THE DOCBLOCK ABOVE CLAIMED THESE WERE REPORTED, AND THEY WERE NOT.
+     *
+     * Filtering `slot-abc.json` and `slot-01.json` out of `slots()` is right —
+     * a slot nobody can name is not a slot, and showing a person a row that
+     * `--release slot-01` cannot clear is worse than showing nothing. But the
+     * consequence of "not a slot" was "not anywhere": no row, no count, no
+     * mention, while the file sat in the directory looking exactly like the
+     * others. That is the failure mode this whole command exists to prevent.
+     *
+     * ⚠️ IT IS INERT, NOT DANGEROUS. Nothing counts it toward the bound and
+     * nothing reads it. It is reported because a file a person can see on disk
+     * and cannot see in `looply runs` is the thing that makes people distrust
+     * the listing — and because `rm` is the fix, which they can only reach if
+     * they are told the path.
+     */
+    strayFiles() {
+        let names;
+        try {
+            names = (0, node_fs_1.readdirSync)(this.dir).filter((n) => n.startsWith('slot-') && n.endsWith('.json'));
+        }
+        catch {
+            return [];
+        }
+        const named = new Set(this.slots().map((s) => (0, node_path_1.basename)(s.path)));
+        return names
+            .filter((n) => !named.has(n))
+            .sort()
+            .map((n) => (0, node_path_1.join)(this.dir, n));
+    }
+    /**
+     * Clear one slot by NUMBER, whatever it holds or fails to hold.
+     *
+     * The companion to `forget(runId)` for the case a runId cannot answer: a slot
+     * file that is corrupt, or truncated, or written by a version that is gone.
+     * Nothing automatic reaches this either — a person types `slot-<n>`.
+     */
+    forgetSlot(slot) {
+        try {
+            (0, node_fs_1.unlinkSync)(this.slotPath(slot));
+            return true;
+        }
+        catch (e) {
+            if (e.code === 'ENOENT')
+                return false;
+            throw e;
+        }
+    }
+    /**
+     * Whether the run this slot names is still holding its own lease.
+     *
+     * ⚠️ A SECOND WITNESS, BECAUSE A PID IS A WEAK ONE. Pids are recycled, and a
+     * record left behind by a hard crash whose number a later process inherits
+     * probes as ALIVE for ever — so the slot it holds is never reclaimed and the
+     * machine's concurrency drops by one permanently, with nothing to point at.
+     *
+     * A live run always holds the lease in its own execution state directory: it
+     * is taken before the slot is claimed and given back in the same breath as
+     * the slot. So a slot whose run has NO lease is not a run, whatever its pid
+     * says — which covers the leak this cannot otherwise see, including the
+     * narrow one where releasing the lease succeeded and clearing the entry did
+     * not.
+     *
+     * ⚠️ IT DOES NOT CLOSE THE PID-RECYCLING HOLE, and saying so is the point: a
+     * hard crash leaves BOTH the lease and the record behind, so both witnesses
+     * agree and both are wrong. That residual is inherited from the lease's own
+     * liveness model, which documents it and deliberately has no heartbeat. What
+     * bounds it is that a person can always say so by name — see
+     * `looply runs --release`.
+     *
+     * ⚠️ AND IT FAILS TOWARDS "HELD". An unreadable lease is not evidence of
+     * absence; only a lease that is gone, or one that names a DIFFERENT run,
+     * frees the slot.
+     */
+    leaseAgrees(record) {
+        const path = (0, run_lease_1.leasePathIn)(record.stateDir);
+        let text;
+        try {
+            text = (0, node_fs_1.readFileSync)(path, 'utf8');
+        }
+        catch (e) {
+            // ENOENT is an answer; anything else is a failure to ask.
+            return e.code !== 'ENOENT';
+        }
+        try {
+            const lease = JSON.parse(text);
+            return typeof lease.runId !== 'string' || lease.runId === record.runId;
+        }
+        catch {
+            // Torn or half-written — a live run's lease, mid-rename, looks like this.
+            return true;
+        }
+    }
+    /**
+     * Forget a run entirely: its record and any slot it holds.
+     *
+     * ⚠️ THE ONLY THING THAT CAN CLEAR A SLOT WHOSE PID LOOKS ALIVE, and it exists
+     * for exactly one situation: a pid recycled onto a crashed run's number, where
+     * every automatic witness agrees and every one of them is wrong. It is not
+     * called by anything automatic — a person names the run.
+     */
+    forget(runId) {
+        safeRunId(runId);
+        let slot = null;
+        let names = [];
+        try {
+            // `.json` as well as the prefix: a reclaim token is `slot-N.json.reclaiming`,
+            // and it is never a slot.
+            names = (0, node_fs_1.readdirSync)(this.dir).filter((n) => n.startsWith('slot-') && n.endsWith('.json'));
+        }
+        catch {
+            names = [];
+        }
+        for (const name of names) {
+            const held = this.readSlot((0, node_path_1.join)(this.dir, name));
+            if (held?.runId !== runId)
+                continue;
+            slot = Number.parseInt(name.slice('slot-'.length), 10);
+            try {
+                (0, node_fs_1.unlinkSync)((0, node_path_1.join)(this.dir, name));
+            }
+            catch {
+                /* already gone */
+            }
+        }
+        let forgot = true;
+        try {
+            (0, node_fs_1.unlinkSync)(this.pathFor(runId));
+        }
+        catch (e) {
+            if (e.code === 'ENOENT')
+                forgot = false;
+            else
+                throw e;
+        }
+        return { forgot, slot };
+    }
+    slotPath(slot) {
+        return (0, node_path_1.join)(this.dir, `slot-${slot}.json`);
+    }
+    readSlot(path) {
+        try {
+            const r = JSON.parse((0, node_fs_1.readFileSync)(path, 'utf8'));
+            if (typeof r.runId !== 'string' || typeof r.pid !== 'number')
+                return null;
+            /**
+             * 🔴 AND THE PATH FIELDS, for the same reason `list` checks them. This
+             * validated `runId` and `pid` only, so a slot record reached `atCapacity`,
+             * which calls `basename(r.workspace)` — and `claim`, whose whole contract
+             * is `{ ok: false, because }`, THREW a TypeError instead of refusing. A
+             * bound that crashes is not a bound.
+             *
+             * `leaseAgrees` reads `stateDir` too, so both are required to be strings
+             * before this record is handed to anything.
+             */
+            if (typeof r.workspace !== 'string' || typeof r.stateDir !== 'string')
+                return null;
+            /**
+             * ⚠️ THE SAME DOORWAY RULE AS `list`. A slot file is written by another
+             * process and read without coordination, so its `runId` is untrusted for
+             * exactly the reason a record's is — and it flows on to `forget(runId)`,
+             * which builds a path from it and throws on one it cannot address. An
+             * unaddressable id makes the slot UNREADABLE, which every caller already
+             * handles by failing closed, rather than a value that reaches a path.
+             */
+            if (!RUN_ID.test(r.runId))
+                return null;
+            return r;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Give the slot back. Absent is success: releasing twice is not an error. */
+    release(runId) {
+        try {
+            (0, node_fs_1.unlinkSync)(this.pathFor(runId));
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+        }
+    }
+    /** Every entry, with its process probed. Never throws on a bad file. */
+    list() {
+        let names;
+        try {
+            // Slot files are the BOUND, not run records; counting them here would
+            // report every run twice.
+            names = (0, node_fs_1.readdirSync)(this.dir).filter((n) => n.endsWith('.json') && !n.startsWith('slot-'));
+        }
+        catch {
+            return [];
+        }
+        const out = [];
+        for (const name of names) {
+            const path = (0, node_path_1.join)(this.dir, name);
+            let record;
+            try {
+                record = JSON.parse((0, node_fs_1.readFileSync)(path, 'utf8'));
+            }
+            catch (e) {
+                out.push({ kind: 'unreadable', path, because: e.message });
+                continue;
+            }
+            if (typeof record.runId !== 'string' || typeof record.pid !== 'number') {
+                out.push({ kind: 'unreadable', path, because: 'not a run record' });
+                continue;
+            }
+            /**
+             * 🔴 THE runId IS VALIDATED HERE, WHERE IT ENTERS, and it was not.
+             *
+             * A registry record is a JSON file. `register` refuses a runId that is not
+             * a safe path segment — but `list` did not, so anything that could write
+             * the project's state directory could hand every consumer a runId with a
+             * separator in it. Measured, end to end, against the built CLI:
+             *
+             *   a record naming `x/../queue`, with a live pid
+             *   -> `looply stop` built `<state>/control.x/../queue.json`
+             *   -> which resolves to `<state>/queue.json`
+             *   -> and OVERWROTE THE PROJECT'S WORK QUEUE with a control request.
+             *
+             * Validating at each consumer would have been four places and a fifth one
+             * later. This is the doorway: a record whose id cannot be addressed is
+             * reported as unreadable, which every consumer already handles, and none
+             * of them ever sees it as a record again.
+             */
+            if (!RUN_ID.test(record.runId)) {
+                out.push({
+                    kind: 'unreadable',
+                    path,
+                    because: `its run id ${JSON.stringify(record.runId)} is not one this can address`,
+                });
+                continue;
+            }
+            /**
+             * 🔴 AND THE TWO PATH FIELDS, because validating the runId alone left the
+             * door open beside the one it closed.
+             *
+             * A record carries `workspace` and `stateDir`, both absolute paths, both
+             * read from a file. `requestControlEverywhere` WRITES into `stateDir`, so
+             * a record naming any directory on the machine turned `looply stop` into
+             * a write primitive pointed wherever the record said. `reapVerdict`
+             * contains `workspace` by realpath before removing anything, but nothing
+             * contained `stateDir` before writing to it.
+             *
+             * Every record looply writes has `stateDir === <workspace>/.looply/state`,
+             * because that is how `executionStateDir` builds it. A record that says
+             * otherwise did not come from looply, and is unreadable.
+             */
+            if (typeof record.workspace !== 'string' || typeof record.stateDir !== 'string') {
+                out.push({ kind: 'unreadable', path, because: 'its workspace or state directory is missing' });
+                continue;
+            }
+            if ((0, node_path_1.resolve)(record.stateDir) !== (0, node_path_1.resolve)((0, node_path_1.join)(record.workspace, git_driver_1.STATE_DIR, 'state'))) {
+                out.push({
+                    kind: 'unreadable',
+                    path,
+                    because: 'its state directory is not the one its workspace would have',
+                });
+                continue;
+            }
+            const liveness = this.probe(record.pid);
+            if (liveness === 'alive')
+                out.push({ kind: 'active', record });
+            else if (liveness === 'dead')
+                out.push({ kind: 'orphaned', record });
+            else
+                out.push({ kind: 'unknown', record });
+        }
+        return out;
+    }
+    /**
+     * Everything NOT PROVEN DEAD — what capacity counts and what `stop` signals.
+     *
+     * ⚠️ 'unknown' IS INCLUDED, DELIBERATELY. Both callers are safer over-counting
+     * than under-counting: capacity would otherwise start an extra execution, and
+     * `stop` would otherwise report a run as finished while it is still writing.
+     */
+    active() {
+        return this.list().flatMap((e) => (e.kind === 'active' || e.kind === 'unknown' ? [e.record] : []));
+    }
+}
+exports.RunRegistry = RunRegistry;
+/**
+ * 🔴 `capacityVerdict` WAS DELETED, and its absence is the point.
+ *
+ * It counted live records and judged them against the limit, and it read like
+ * the concurrency bound — but `claim` replaced it and nothing called it any
+ * more. A function that looks like the bound, is exported, is tested, and
+ * decides nothing is worse than no function at all: the next person to reach
+ * for it gets check-then-act semantics back, with tests that pass.
+ *
+ * The bound is `RunRegistry.claim`. There is one.
+ */
+/**
+ * Write a control request where EVERY live execution will read it.
+ *
+ * 🔴 ONE SHARED FILE PLUS N CONSUMERS IS A BRAKE THAT RELEASES ITSELF, and both
+ * writers had the same hole. `ControlStore.consume()` writes `resume` into the
+ * file it read, so the FIRST execution to reach a round boundary clears the
+ * instruction and every other one reads `resume` and carries on.
+ *
+ * `looply stop` was taught to write an addressed request per execution; the
+ * DAEMON — which is how the phone's Stop and Pause arrive — was not, and it is
+ * the path that matters most, because nobody is standing at the terminal to
+ * notice that two of three runs kept going.
+ *
+ * So there is one function, and both call it.
+ *
+ * ⚠️ THE SHARED FILE IS STILL WRITTEN, FIRST. It is what a run started AFTER
+ * this request will read, what Simple Mode has always used, and what `resume`
+ * has to clear. The addressed files are additive.
+ *
+ * ⚠️ AND A FAILURE TO REACH ONE EXECUTION IS REPORTED, not swallowed. A brake
+ * that misses a run must say which.
+ */
+async function requestControlEverywhere(projectState, live, kind, actor, fs, 
+/** Where this project's executions may legitimately keep state. See below. */
+cwd) {
+    await new control_file_1.ControlStore(projectState, fs).request(kind, actor);
+    /**
+     * 🔴 AND IT WRITES ONLY WHERE A RUN'S STATE CAN LEGITIMATELY BE.
+     *
+     * `list` refuses a record whose `stateDir` is not its workspace's — but
+     * `workspace` itself was unconstrained, so a record naming
+     * `C:\anywhere` with `stateDir` `C:\anywhere\.looply\state` passed the
+     * doorway, and `ControlStore.request` then MKDIR'd and WROTE there. `looply
+     * stop` and the phone's Stop were still a write primitive, one level further
+     * out than the runId hole they were supposed to have closed.
+     *
+     * There are exactly two places an execution's state can be: the project's own
+     * state directory (an ordinary checkout, where project and execution scope are
+     * the same path), or under this project's workspaces root. Anything else is
+     * not this project's execution, whatever the record says.
+     */
+    /**
+     * 🔴 AND THE RULE IS "A CHECKOUT OF THIS REPOSITORY", NOT "ONE OF TWO PLACES".
+     *
+     * A first version allowed only the project's own state directory or something
+     * under the workspaces root — and that broke the phase's own `--in` workflow,
+     * where a person points a run at a worktree THEY made, which is neither.
+     * Measured: `looply stop` reported a live `--in` execution as unreachable and
+     * wrote nothing, which is the silent-brake failure this whole mechanism exists
+     * to end.
+     *
+     * The honest question is not "where is this directory" but "is it a checkout
+     * of the repository I am the registry for". `list` already guarantees the
+     * state directory is its workspace's; this settles the workspace.
+     */
+    const mine = cwd === undefined ? null : (0, trusted_git_1.repoIdentityPath)(cwd);
+    const reached = [];
+    const unreachable = [];
+    for (const r of live) {
+        /**
+         * ⚠️ A CHECKOUT *ROOT* OF THIS REPOSITORY, not merely somewhere inside it.
+         * `repoIdentityPath` walks up, so `<repo>/src` answers `<repo>` and matched
+         * — and this would then have created `<repo>/src/.looply/state` and written
+         * into it. Confined to the person's own repository rather than the whole
+         * machine, but still a write nobody asked for, in a tree looply is supposed
+         * to leave alone unless a round is committing.
+         */
+        if (mine !== null && (!(0, trusted_git_1.isCheckoutRoot)(r.workspace) || (0, trusted_git_1.repoIdentityPath)(r.workspace) !== mine)) {
+            unreachable.push(r.runId);
+            continue;
+        }
+        try {
+            await control_file_1.ControlStore.addressed(r.stateDir, r.runId, fs).request(kind, actor);
+            reached.push(r.runId);
+        }
+        catch {
+            // A workspace that has gone, or one this user cannot write.
+            unreachable.push(r.runId);
+        }
+    }
+    return { reached, unreachable };
+}
+/**
+ * Create a workspace for an execution: a linked worktree on a fresh branch.
+ *
+ * ⚠️ THE GIT DRIVER DOES THE WORK, so the worktree is created by the same
+ * substrate every other verb uses — the repository-config refusal, the
+ * repository-root check, the rebuilt `GIT_` environment and the absolute git
+ * binary all apply. A provisioner with its own runner would be a second path
+ * around four defences at once.
+ */
+async function createWorkspace(git, cwd, runId, branch, baseSha, 
+/** Whose home the workspaces root lives under; the user's unless a test says otherwise (M4-1). */
+home = (0, node_os_1.homedir)(), 
+/**
+ * `run.carry_into_checkouts` — directories this fresh checkout needs that git
+ * does not carry, above all `node_modules`.
+ *
+ * 🔴 WITHOUT IT THE GATE CANNOT PASS HERE. A worktree holds what git tracks,
+ * the gate runs with no network by design, and so a second worker's every
+ * round went red on the same missing toolchain. Measured: four rounds, one
+ * output digest.
+ *
+ * ⚠️ LAST AND DEFAULTED, so every existing caller and fixture is untouched and
+ * an empty list is byte-identical to the old behaviour.
+ */
+carry = []) {
+    const root = workspacesRoot(cwd, home);
+    (0, node_fs_1.mkdirSync)(root, { recursive: true });
+    const path = (0, node_path_1.join)(root, runId);
+    if ((0, node_fs_1.existsSync)(path)) {
+        throw new WorkspaceError(`a workspace already exists at ${path} — refusing to reuse it`);
+    }
+    await git.addWorktree(path, branch, baseSha);
+    /**
+     * Immediately after the checkout and BEFORE the claim below, so a workspace is
+     * never offered to a run in a state where its gate is guaranteed to fail.
+     */
+    if (carry.length > 0) {
+        try {
+            (0, checkout_carry_1.carryIntoCheckout)(cwd, path, carry);
+        }
+        catch (e) {
+            throw new WorkspaceError(`the workspace could not be provisioned: ${e.message}`);
+        }
+    }
+    /**
+     * ⚠️ CLAIMED THE INSTANT IT EXISTS. A run does not take its lease until after
+     * the config is read and the git checks have run — seconds later — and until
+     * then nothing in the checkout says anybody is coming. `abandonedWorkspaces`
+     * would call it abandoned and a concurrent `--reap` would delete it.
+     */
+    try {
+        const stateDir = (0, node_path_1.join)(path, git_driver_1.STATE_DIR, 'state');
+        (0, node_fs_1.mkdirSync)(stateDir, { recursive: true });
+        /**
+         * ⚠️ TEMP-THEN-RENAME, so a reader can never catch it half-written. That
+         * matters because `checkoutBusy` has to decide what an unparseable marker
+         * means: written atomically, a torn one cannot exist, so a corrupt one is
+         * corruption rather than a race and can be read as stale.
+         */
+        const tmp = (0, node_path_1.join)(stateDir, `${CREATING}.${process.pid}.tmp`);
+        (0, node_fs_1.writeFileSync)(tmp, `${JSON.stringify({ pid: process.pid, at: new Date().toISOString() }, null, 2)}
+`);
+        (0, node_fs_1.renameSync)(tmp, (0, node_path_1.join)(stateDir, CREATING));
+    }
+    catch (e) {
+        /**
+         * 🔴 THIS USED TO BE SWALLOWED, and swallowing it produced exactly the state
+         * the marker exists to prevent.
+         *
+         * The marker is the ONLY thing covering the checkout between `worktree add`
+         * returning and the run acquiring its lease — no registry record exists yet,
+         * so `abandonedWorkspaces` has nothing else to go on. A `try {} catch {}`
+         * around the write meant a refused mkdir, write or rename produced an
+         * unprotected checkout with no marker and no diagnostic: a concurrent
+         * `--reap` would remove it out from under a starting run, and nothing
+         * anywhere would say why.
+         *
+         * So it fails closed: the worktree this just created is removed and the
+         * caller is told. A workspace that cannot be protected is not a workspace.
+         */
+        try {
+            await git.removeWorktree(path);
+            await git.pruneWorktrees();
+        }
+        catch {
+            // Leave it rather than force it. It is empty and `looply runs` lists it.
+        }
+        throw new WorkspaceError(`the workspace at ${path} could not be claimed for this run (${e.message}), so it was not kept`);
+    }
+    return path;
+}
+/**
+ * Whether a workspace may be reaped, and why not when it may not.
+ *
+ * 🔴 THE ORDER OF THESE CHECKS IS THE SAFETY. A reaper that deleted first and
+ * asked afterwards is a reaper that deletes a running execution's checkout. So:
+ * it must be registered as orphaned (its process gone), it must be a workspace
+ * this machine created under the workspaces root, and it must not be the main
+ * checkout. Anything else is left alone and reported.
+ */
+/**
+ * The real path of `path`, resolving as much of it as actually exists.
+ *
+ * ⚠️ A PLAIN `realpathSync` IS NOT ENOUGH HERE, and the first version was one:
+ * it throws ENOENT for anything absent, which is the ordinary case twice over —
+ * the workspaces root before any workspace has been created, and a workspace
+ * whose directory is already gone. Refusing those as "could not be resolved"
+ * made the reaper unable to clear a registry entry for a directory that no
+ * longer exists, which is precisely what it is for.
+ *
+ * So: resolve the longest EXISTING prefix, then re-append the rest. Links in the
+ * part that exists are still collapsed — which is the whole point — and the
+ * absent tail contributes no link to follow.
+ */
+function realpathDeep(path) {
+    const full = (0, node_path_1.resolve)(path);
+    const tail = [];
+    let head = full;
+    for (;;) {
+        try {
+            const real = node_fs_1.realpathSync.native(head);
+            return tail.length === 0 ? real : (0, node_path_1.join)(real, ...tail);
+        }
+        catch {
+            const parent = (0, node_path_1.dirname)(head);
+            if (parent === head)
+                return full; // reached the drive/root; nothing resolved
+            tail.unshift((0, node_path_1.basename)(head));
+            head = parent;
+        }
+    }
+}
+/**
+ * Whether `child` is strictly inside `parent`.
+ *
+ * ⚠️ THE SEPARATOR IS PART OF THE TEST. A bare `startsWith` says
+ * `C:\ws-evil` is inside `C:\ws`, and `relative()` alone says a sibling is
+ * inside when it isn't. Equality is excluded too: the root itself is never a
+ * workspace.
+ */
+function contains(parent, child) {
+    const rel = (0, node_path_1.relative)(parent, child);
+    return rel !== '' && !rel.startsWith('..') && !(0, node_path_1.isAbsolute)(rel);
+}
+/**
+ * WHY THE REAPER IS KEEPING THIS CHECKOUT, IN WORDS THAT ARE TRUE.
+ *
+ * 🔴 THE OLD SENTENCE WAS WRONG IN THREE WAYS AT ONCE WHEN THE CAUSE WAS AN
+ * UNINSPECTABLE CHECKOUT — and that is the one case that writes a durable
+ * quarantine, so it was wrong exactly where it mattered most. Measured against
+ * an empty, clean worktree during a transient git fault, it said:
+ *
+ *   "it still holds 1 file(s) nothing else has a copy of (could not be
+ *    inspected (…)). Look at <path>, then remove it yourself"
+ *
+ *   1. It claimed a file count for a checkout holding nothing. The "1 file" was
+ *      the error string itself.
+ *   2. It never said a quarantine had been written, and never named `--release`
+ *      — that guidance appeared only on the NEXT invocation.
+ *   3. It told the person to hand-delete a worktree looply had just decided
+ *      must not be touched.
+ */
+function keptBecause(residue, path, quarantined) {
+    const blind = residue.find((r) => r.startsWith('could not be inspected'));
+    if (blind !== undefined) {
+        return (`looply could not see inside it, so it cannot say whether anything there is yours — ${blind}. ` +
+            (quarantined
+                ? `It is quarantined and will not be touched. Look at ${path}, then ` +
+                    `\`looply runs --release ${(0, node_path_1.basename)(path)}\` when you have`
+                : `Look at ${path} yourself; nothing here will remove it`));
+    }
+    return (`it still holds ${residue.length} file(s) nothing else has a copy of ` +
+        `(${residue.slice(0, 3).join(', ')}${residue.length > 3 ? ', …' : ''}). ` +
+        `Look at ${path}, then remove it yourself`);
+}
+/**
+ * 🔴 THE PART OF A REAP REFUSAL THAT NEVER CHANGES, ASKED ON ITS OWN.
+ *
+ * `looply runs` counted the orphans `--reap` could take by `record.worktree`,
+ * which does not mean "a checkout looply made". It means "not the main
+ * checkout" — and it is TRUE for a worktree a PERSON made and pointed `--in`
+ * at. So a crashed `--in` run was announced as "in a checkout looply made",
+ * the person ran `--reap`, and `--reap` refused it. Correctly, permanently,
+ * and once a day for ever.
+ *
+ * ⚠️ LIVENESS IS DELIBERATELY NOT ASKED HERE. That answer changes between the
+ * listing and the reap; this one does not. `reapVerdict` calls this, so the
+ * count in the summary and the refusal that follows it cannot drift apart
+ * again — there is one test, not two spellings of nearly the same one.
+ */
+function reapableCheckout(record, cwd, 
+/** Whose home the workspaces root lives under; the user's unless a caller says otherwise (M4-4). */
+home = (0, node_os_1.homedir)()) {
+    if (!record.worktree) {
+        return { ok: false, because: 'this is the main checkout, which no execution created' };
+    }
+    /**
+     * 🔴 CONTAINMENT IS CHECKED ON THE *REAL* PATH, because `resolve` does not
+     * follow links and Windows junctions are trivial to make without privileges.
+     *
+     * The attack the first version allowed, in full: create
+     * `~/.looply/workspaces/<key>/run_x` as a JUNCTION pointing at a live
+     * sibling's checkout — or at the user's repository. `resolve` returns the
+     * junction's own path, `startsWith(root)` says "inside the workspaces root",
+     * and the reaper then runs `worktree remove` and `rm` through it, deleting
+     * somebody else's work at the far end. Nothing about the record has to be
+     * forged; only a directory has to be planted, and the record can be an
+     * ordinary orphan of a genuinely dead run.
+     *
+     * `realpathSync` collapses junctions, symlinks and 8.3 short names, so both
+     * sides are compared as the filesystem sees them. The root is realpathed too:
+     * on macOS `/var` is a link to `/private/var`, and comparing a resolved child
+     * against an unresolved parent would refuse every legitimate reap there.
+     */
+    const rootReal = realpathDeep(workspacesRoot(cwd, home));
+    const declared = (0, node_path_1.resolve)(record.workspace);
+    const ws = realpathDeep(declared);
+    if (!contains(rootReal, ws)) {
+        return {
+            ok: false,
+            because: (ws === declared
+                ? `${declared} is not under this project's workspaces root`
+                : `${declared} really lives at ${ws}, which is outside this project's workspaces root. ` +
+                    'A workspace that is a link to somewhere else is not a workspace this may remove'),
+        };
+    }
+    return { ok: true };
+}
+function reapVerdict(record, cwd, probe = exports.nodeProbe, home = (0, node_os_1.homedir)()) {
+    const liveness = probe(record.pid);
+    if (liveness !== 'dead') {
+        return {
+            ok: false,
+            because: liveness === 'alive'
+                ? `pid ${record.pid} is still alive`
+                : `pid ${record.pid} could not be judged alive or dead, and a reaper does not guess`,
+        };
+    }
+    const ours = reapableCheckout(record, cwd, home);
+    if (!ours.ok)
+        return ours;
+    const declared = (0, node_path_1.resolve)(record.workspace);
+    // Gone already: nothing to remove, but the registry entry is still ours to clear.
+    if (!(0, node_fs_1.existsSync)(declared))
+        return { ok: true };
+    /**
+     * 🔴 A DEAD RECORD DOES NOT MEAN AN IDLE CHECKOUT, and this only ever asked
+     * about the record.
+     *
+     * A crashed run leaves its registry entry naming workspace W. Somebody then
+     * starts a NEW run in W — `looply run --in W` — which is allowed, because the
+     * crashed run's lease is judged dead and taken over. Now W holds a live
+     * execution AND a stale record for a dead pid, and `--reap` would prove the
+     * STALE pid dead and delete the live run's checkout out from under it, filing
+     * its lease and ledger under the dead run's name.
+     *
+     * The workspace's own lease is the answer, exactly as it is for a slot: if
+     * anything in there is holding one, this is not a dead workspace whatever the
+     * record says.
+     */
+    if (checkoutBusy((0, node_path_1.join)(declared, git_driver_1.STATE_DIR, 'state'), probe)) {
+        return { ok: false, because: `something is still using that checkout (${busyBecause((0, node_path_1.join)(declared, git_driver_1.STATE_DIR, 'state'), probe)})` };
+    }
+    try {
+        // `lstat`, not `stat`: a link TO a directory is not a directory this owns.
+        if (!(0, node_fs_1.lstatSync)(declared).isDirectory()) {
+            return { ok: false, because: `${declared} is not a directory` };
+        }
+    }
+    catch (e) {
+        return { ok: false, because: `${declared} could not be read (${e.message})` };
+    }
+    return { ok: true };
+}
+/**
+ * Remove a proven-dead workspace, worktree record and registry entry.
+ *
+ * ⚠️ `git worktree remove` WITHOUT `--force`, then nothing. If git refuses —
+ * because the tree is dirty, or a file is held — the directory is LEFT and the
+ * refusal is returned. `--force` deletes ignored files, which is how a reaper
+ * would take somebody's `node_modules` or `.env` with it, and it fires exactly
+ * when git has already judged there is something worth refusing over.
+ */
+/**
+ * Everything in a workspace that is not a pristine checkout — INCLUDING ignored
+ * files, which is the whole reason this exists.
+ *
+ * ⚠️ THE DRIVER MUST BE BUILT FOR THE WORKSPACE, not for the main checkout.
+ * `trustedGitEnv` pins GIT_DIR and GIT_WORK_TREE from the cwd a driver was made
+ * with, and a pinned work tree beats `-C` — so a main-checkout driver asked
+ * about a workspace answers about the main checkout, confidently and wrongly.
+ *
+ * A failure to ask counts AS residue: a reaper that cannot see what is there
+ * must not delete it.
+ */
+async function workspaceResidue(gitInWorkspace, workspace, 
+/**
+ * `run.carry_into_checkouts` — paths LOOPLY PUT HERE ITSELF, and therefore not
+ * the person's.
+ *
+ * 🔴 WITHOUT THIS, PROVISIONING A WORKSPACE MAKES IT UNREAPABLE FOR EVER.
+ * `--ignored` is the whole point of this check, and a carried `node_modules`
+ * is ignored by definition — so the reaper counted the product's own copy as
+ * "file(s) nothing else has a copy of" and refused. Measured immediately after
+ * the carry landed: SIX workspaces, every one kept, each naming
+ * `!! node_modules/` as the person's content.
+ *
+ * The reasoning is the same one that drops `.looply/state/` two lines below:
+ * this is looply's own, it was copied from a source that still has it, and
+ * deleting it loses nothing. It is a COPY — that is the whole contract of
+ * `carryIntoCheckout` — so "nothing else has a copy of it" is exactly false.
+ *
+ * ⚠️ TOP-LEVEL NAMES ONLY, matching what `carryNameTrouble` permits. A path
+ * deeper than one segment is not carriable, so it cannot be excused here.
+ */
+carried = []) {
+    let lines;
+    try {
+        lines = (await gitInWorkspace.statusWithIgnored())
+            .split('\n')
+            .map((l) => l.trim())
+            .filter((l) => l !== '');
+    }
+    catch (e) {
+        return [`could not be inspected (${e.message})`];
+    }
+    const out = [];
+    for (const line of lines) {
+        /**
+         * Porcelain v1 is `XY PATH` or `XY ORIG -> PATH`. Only the path field is
+         * examined: a looser match would filter `R  secrets.env -> .looply/x` — a
+         * USER file, renamed — by the very rule meant to ignore looply's own state.
+         */
+        const field = line.slice(3).trim();
+        const shown = field.startsWith('"') ? field.slice(1) : field;
+        // Looply's own execution state, which `retainEvidence` moves to safety.
+        if (shown.startsWith('.looply/state/') || shown.startsWith('.looply\\state\\'))
+            continue;
+        /**
+         * Looply's own provisioning. Git collapses an ignored directory to one line,
+         * so a carried `node_modules` arrives as `!! node_modules/` — matched here
+         * with and without the trailing separator, in both slash spellings.
+         */
+        if (carried.some((name) => shown === name || shown === `${name}/` || shown === `${name}\\`))
+            continue;
+        /**
+         * 🔴 GIT COLLAPSES AN IGNORED DIRECTORY TO ONE LINE, and a project that
+         * ignores `.looply/` wholesale — which many do — gets `!! .looply/` and
+         * nothing else, whatever is inside it. Neither `-uall` nor a pathspec
+         * exclusion expands it: `--ignored=matching` reports the directory because
+         * the directory is what the ignore rule matched. Measured.
+         *
+         * So the filter stopped matching, every such workspace read as holding
+         * residue for ever, and `--reap` refused it with a reason about the
+         * person's files that named none of them.
+         *
+         * When git will not say what is in there, LOOK. Anything outside `state/`
+         * is the person's and is named individually; if there is nothing else, this
+         * line is looply's own and is dropped.
+         */
+        if (shown === '.looply/' || shown === '.looply' || shown === '.looply\\') {
+            out.push(...notOursUnder((0, node_path_1.join)(workspace, git_driver_1.STATE_DIR)));
+            continue;
+        }
+        out.push(line);
+    }
+    return out;
+}
+/**
+ * Everything under `<workspace>/.looply` that is not looply's own `state/`.
+ *
+ * ⚠️ A FAILURE TO LOOK IS RESIDUE. If the directory cannot be read, the honest
+ * answer is "there may be something here", not "there is nothing".
+ */
+function notOursUnder(looplyDir) {
+    const found = [];
+    const walk = (dir, rel) => {
+        let entries;
+        try {
+            entries = (0, node_fs_1.readdirSync)(dir);
+        }
+        catch (e) {
+            found.push(`${rel || '.looply'} could not be read (${e.message})`);
+            return;
+        }
+        for (const name of entries) {
+            const at = rel === '' ? name : `${rel}/${name}`;
+            if (rel === '' && name === 'state')
+                continue; // looply's own, moved to safety
+            const full = (0, node_path_1.join)(dir, name);
+            let isDir = false;
+            try {
+                isDir = (0, node_fs_1.lstatSync)(full).isDirectory();
+            }
+            catch {
+                found.push(`.looply/${at} could not be read`);
+                continue;
+            }
+            if (isDir)
+                walk(full, at);
+            else
+                found.push(`?? .looply/${at}`);
+        }
+    };
+    walk(looplyDir, '');
+    return found;
+}
+/**
+ * Move a dead execution's own state out of the workspace, so removing the
+ * checkout does not take the evidence with it.
+ *
+ * ⚠️ MOVED, NEVER DELETED, and the reap stops if this fails. A crashed run's
+ * ledger is the only account of why it crashed; a reaper that removes the
+ * checkout and loses it has destroyed the one thing somebody would come looking
+ * for. It lands in the PROJECT's state directory, which outlives every workspace.
+ *
+ * ⚠️ AND IT NEVER OVERWRITES. A second reap of the same runId — which can only
+ * happen if the first was interrupted — lands beside the first, not on it.
+ */
+function retainEvidence(record, cwd) {
+    const from = (0, node_path_1.join)(record.workspace, git_driver_1.STATE_DIR, 'state');
+    if (!(0, node_fs_1.existsSync)(from))
+        return { ok: true, at: null };
+    /**
+     * 🔴 AND IT MUST REALLY BE INSIDE THE WORKSPACE. `reapVerdict` realpaths the
+     * workspace ROOT; this then built a path two levels below it and ran a
+     * recursive copy AND a recursive delete through it. A junction at
+     * `<workspace>/.looply` — which nothing had checked — pointed both at whatever
+     * an attacker liked, and the delete is the half that does not come back.
+     */
+    const workspaceReal = realpathDeep(record.workspace);
+    if (!contains(workspaceReal, realpathDeep(from))) {
+        return {
+            ok: false,
+            because: `${from} really lives outside the workspace, so its records were not moved`,
+        };
+    }
+    // ⚠️ THE RUN ID IS A PATH SEGMENT HERE TOO, and this one ends in a recursive
+    // copy and a recursive delete. It comes off disk, so it is checked.
+    const base = (0, node_path_1.join)((0, git_driver_1.projectStateDir)(cwd), 'retired', safeRunId(record.runId));
+    let to = base;
+    for (let n = 2; (0, node_fs_1.existsSync)(to) && n < 100; n += 1)
+        to = `${base}-${n}`;
+    try {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(to), { recursive: true });
+        (0, node_fs_1.cpSync)(from, to, { recursive: true });
+        (0, node_fs_1.rmSync)(from, { recursive: true, force: true });
+        return { ok: true, at: to };
+    }
+    catch (e) {
+        return { ok: false, because: `its own records could not be moved to safety (${e.message})` };
+    }
+}
+async function reapWorkspace(git, registry, record, cwd, probe = exports.nodeProbe, 
+/** A driver bound to the given checkout. See `workspaceResidue`. */
+gitInWorkspace = (dir) => new git_driver_1.GitDriver((0, git_driver_1.nodeGitExec)(dir)), home = (0, node_os_1.homedir)(), 
+/**
+ * `run.carry_into_checkouts` - paths looply provisioned into the checkout
+ * itself. Passed through to `workspaceResidue`, which explains why.
+ */
+carried = []) {
+    const verdict = reapVerdict(record, cwd, probe, home);
+    if (!verdict.ok)
+        return { reaped: false, because: verdict.because };
+    /**
+     * 🔴 A QUARANTINE IS CHECKED BEFORE ANY OF THE WALKS, AND IT NEVER EXPIRES.
+     *
+     * Everything below re-derives its answer from the filesystem, which means a
+     * checkout that was refused yesterday for a reason that has since become
+     * invisible — a live orphaned agent, a git config that has since been fixed —
+     * is silently eligible again today. The record is the only thing that
+     * remembers looply already decided, and only a person clears it.
+     */
+    const held = (0, workspace_quarantine_1.quarantineOf)(cwd, record.workspace);
+    if (held !== null) {
+        return {
+            reaped: false,
+            because: `it is quarantined — ${held.because}. Look at ${record.workspace}, then ` +
+                `\`looply runs --release ${(0, node_path_1.basename)(record.workspace)}\` when you have`,
+        };
+    }
+    let evidenceAt = null;
+    if ((0, node_fs_1.existsSync)(record.workspace)) {
+        /**
+         * 🔴 `git worktree remove` WITHOUT `--force` DELETES IGNORED FILES, and the
+         * first version of this function said the opposite in as many words.
+         *
+         * Measured: a worktree holding only `node_modules` and `.env` — both
+         * ignored, so `git status` reads clean — was removed silently and both were
+         * destroyed. Git refuses over MODIFIED or UNTRACKED files; ignored ones it
+         * simply takes. So "git's refusal is the check" was false, and the reaper
+         * would have deleted a crashed execution's `.env`, its dependencies, and its
+         * `.looply/state` ledger — the evidence of why it crashed — while reporting
+         * success.
+         *
+         * The residue check below is the real one. `--ignored` is the whole point of
+         * it: without that flag it asks git exactly the question git already answers
+         * with a refusal, and learns nothing new.
+         */
+        const residue = await workspaceResidue(gitInWorkspace(record.workspace), record.workspace, carried);
+        if (residue.length > 0) {
+            const blind = residue.some((r) => r.startsWith('could not be inspected'));
+            const because = keptBecause(residue, record.workspace, blind);
+            /**
+             * 🔴 QUARANTINED ONLY WHEN THE ANSWER CANNOT BE RE-DERIVED, AND FILES ARE
+             * NOT THAT CASE. Caught by a Phase 1 pin the first time this was written.
+             *
+             * The obvious move is to quarantine on any refusal. It is wrong, and the
+             * failure is concrete: a workspace holding a `.env` is refused, the record
+             * is written, the person deletes their `.env` — and `--reap` refuses for
+             * ever, because a quarantine never resets. A person who tidied up their
+             * own checkout can no longer retire it without a second command they have
+             * no reason to know about. The reaper gets worse, not safer.
+             *
+             * Residue is a fact about the filesystem RIGHT NOW. Re-deriving it is
+             * cheap, it is what Phase 1 does, and it self-corrects the moment the
+             * person acts. Remembering it buys nothing and costs that.
+             *
+             * ⚠️ THE UNINSPECTABLE CASE IS THE OPPOSITE, and it is the one the plan's
+             * `repoConfigTrouble` condition names. `workspaceResidue` answers
+             * `could not be inspected (…)` when the checkout's git config trips
+             * `repoConfigTroubleAt` — looply could not form a view at all. That is not
+             * a fact about files that will change when somebody deletes one; it is a
+             * checkout looply cannot reason about, and it is exactly the judgement
+             * that has to survive the process that made it.
+             */
+            if (residue.some((r) => r.startsWith('could not be inspected'))) {
+                (0, workspace_quarantine_1.quarantine)(cwd, record.workspace, because, 'reap');
+            }
+            return { reaped: false, because };
+        }
+        // The evidence leaves before the checkout does.
+        const kept = retainEvidence(record, cwd);
+        if (!kept.ok)
+            return { reaped: false, because: kept.because };
+        evidenceAt = kept.at;
+        try {
+            await git.removeWorktree(record.workspace);
+        }
+        catch (e) {
+            return { reaped: false, because: `git would not remove it: ${e.message}` };
+        }
+    }
+    // Only after the tree is gone: the administrative record, then the claim.
+    await git.pruneWorktrees().catch(() => {
+        /* pruning is tidying; a failure here does not make the reap wrong */
+    });
+    /**
+     * 🔴 AND THE SLOT, WHICH THIS DID NOT GIVE BACK. `--reap` reported a run
+     * "retired", removed its checkout and cleared its record — and left the
+     * concurrency slot it held. So retiring a crashed run lowered the project's
+     * usable concurrency by one, permanently, and the only way back was
+     * `--release slot-<n>` on a slot whose record no longer existed to name it.
+     *
+     * `releaseSlot` is keyed on identity, so this can only ever free the slot this
+     * run actually holds.
+     */
+    for (const s of registry.slots()) {
+        if (s.record?.runId === record.runId)
+            registry.releaseSlot(s.slot, record.runId);
+    }
+    registry.release(record.runId);
+    /**
+     * 🔴 AND WHAT THE EXECUTION LEFT OUTSIDE ITS CHECKOUT — including a copy of
+     * the provider credential.
+     *
+     * Three machine-level directories are keyed on the WORKSPACE path, which is
+     * right: two executions must not share provider state or a container. What
+     * was missing is the other end. This removed the checkout, the record and the
+     * slot and left all three behind for ever, and one of them —
+     * `~/.looply/provider-sessions/<role>-<hex>` — is the transport's HOME, which
+     * is where the provider writes its credential.
+     *
+     * ⚠️ LAST, AND NEVER THE VERDICT. The reap has already succeeded by this
+     * line; a directory that will not delete is a smaller problem than a
+     * workspace that cannot be retired, and turning tidying into a refusal is how
+     * a reaper stops being usable. See `workspace-residue-sweep.ts`.
+     */
+    /**
+     * The liveness the sweep needs, from the registry it already holds.
+     *
+     * By this line the record is released and the slot freed, so `active()` can
+     * only still name this workspace if ANOTHER record does — which is exactly the
+     * case where its container identities must keep their shared-path grants. A
+     * probe that cannot answer classifies `unknown`, and the sweep treats that as
+     * in use rather than as absent.
+     */
+    (0, workspace_residue_sweep_1.sweepWorkspaceResidue)(record.workspace, undefined, {
+        usersOf: (ws) => registry.active().filter((r) => r.workspace === ws).map((r) => r.runId),
+    });
+    return evidenceAt === null ? { reaped: true } : { reaped: true, evidenceAt };
+}
+/**
+ * Workspaces on disk that no live execution and no registry record account for.
+ *
+ * 🔴 THE LIFECYCLE HAD A THIRD HOLE, and I found this one by using the command I
+ * had just written. `looply run --new-workspace` cuts the checkout BEFORE the
+ * run registers, so anything that ends the run in between — a config error, a
+ * dirty tree, `--dry-run`, a crash — leaves a real worktree that `looply runs`
+ * cannot see and `--reap` cannot reach, because both work from registry records
+ * and there is none. They accumulate silently, one per failed start.
+ *
+ * ⚠️ ABSENCE OF A RECORD IS NOT ENOUGH TO CALL ONE ABANDONED. A run that has
+ * created its workspace and not yet registered is in exactly that state for a
+ * few hundred milliseconds. So the LEASE is the second witness, as it is for a
+ * slot: a workspace whose own execution state holds a lease naming a process
+ * that is not proven dead is left alone.
+ *
+ * ⚠️ AND IT LOOKS ONLY UNDER THE WORKSPACES ROOT — never at a `--in` checkout,
+ * which is the person's and which nothing here may ever remove.
+ */
+function abandonedWorkspaces(cwd, registry, probe = exports.nodeProbe, home = (0, node_os_1.homedir)()) {
+    const root = workspacesRoot(cwd, home);
+    let names;
+    try {
+        names = (0, node_fs_1.readdirSync)(root);
+    }
+    catch {
+        return { abandoned: [], busy: [] };
+    }
+    const busy = [];
+    const claimed = new Set(registry
+        .list()
+        .flatMap((e) => (e.kind === 'unreadable' ? [] : [(0, node_path_1.resolve)(e.record.workspace).toLowerCase()])));
+    const out = [];
+    for (const name of names) {
+        const path = (0, node_path_1.join)(root, name);
+        try {
+            if (!(0, node_fs_1.lstatSync)(path).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        if (claimed.has((0, node_path_1.resolve)(path).toLowerCase()))
+            continue;
+        if (checkoutBusy((0, node_path_1.join)(path, git_driver_1.STATE_DIR, 'state'), probe)) {
+            /**
+             * 🔴 THIS USED TO `continue` SILENTLY, and the checkout then existed
+             * nowhere: no row, no count, no reason, and `looply runs` printing
+             * "nothing running, and nothing left behind" — which was false, with a
+             * real checkout on disk that nothing would ever mention again.
+             *
+             * It is BUSY, not abandoned, so it is not offered for reaping; but a
+             * person looking at a directory that is plainly there deserves to see it.
+             */
+            busy.push(path);
+            continue;
+        }
+        out.push(path);
+    }
+    return { abandoned: out.sort(), busy: busy.sort() };
+}
+/**
+ * Whether anything in a checkout is still using it.
+ *
+ * TWO FILES, AND THE SECOND ONE EXISTS BECAUSE OF A RACE THE FIRST CANNOT SEE:
+ *
+ *   run.lease.json   a run that has started. This is the real answer.
+ *   creating.json    a run that has CUT the checkout and not yet taken its
+ *                    lease. `--new-workspace` creates the worktree, then loads
+ *                    config, then runs git checks, then acquires the lease —
+ *                    seconds, on a cold repository. For that whole window the
+ *                    checkout had no lease, so `abandonedWorkspaces` called it
+ *                    abandoned and a concurrent `--reap` would delete a
+ *                    starting run's checkout out from under it.
+ *
+ * ⚠️ NEITHER FILE NEEDS CLEANING UP. Both name a pid; once that process is gone
+ * both read as "not busy", so a crash between the two leaves nothing stuck.
+ *
+ * ⚠️ AND IT FAILS TOWARDS BUSY. Absent is an answer; unreadable is not.
+ */
+/**
+ * WHICH witness is holding a checkout, in words.
+ *
+ * 🔴 BOTH REFUSALS HARD-CODED "still holding a run lease", and `checkoutBusy`
+ * has two witnesses. So a person told that went looking for a `run.lease.json`
+ * that is not there, while the thing actually holding the checkout was the
+ * creation marker — a starting run, which is a completely different situation
+ * and needs a completely different response.
+ */
+function busyBecause(stateDir, probe) {
+    if (holderAlive((0, run_lease_1.leasePathIn)(stateDir), probe))
+        return 'a run lease';
+    if (holderAlive((0, node_path_1.join)(stateDir, CREATING), probe, { corruptIsBusy: false })) {
+        /**
+         * ⚠️ "STARTING OR FINISHING", because the marker covers BOTH ends. It is
+         * written when the checkout is cut and cleared as the last thing a run does,
+         * so a marker with no lease beside it means either a run that has not taken
+         * its lease yet or one that has already given it back and is still tidying.
+         * Saying only "starting up" sent people looking for a run that was in fact
+         * on its way out.
+         */
+        return 'a run that is still starting up or finishing';
+    }
+    return 'something this could not identify';
+}
+function checkoutBusy(stateDir, probe = exports.nodeProbe) {
+    /**
+     * ⚠️ THE TWO FILES ARE JUDGED DIFFERENTLY WHEN THEY CANNOT BE PARSED.
+     *
+     * A LEASE that cannot be read fails towards busy: it is written by a live run
+     * on an ordinary schedule, so an unreadable one is most likely a live write
+     * caught mid-rename, and treating it as free starts a second run in a checkout
+     * somebody is using.
+     *
+     * A CREATING marker is written ONCE, atomically, at the instant the checkout
+     * is cut. It cannot be caught mid-write. So an unparseable one is corruption,
+     * not a race — and treating it as busy would wedge that workspace for ever,
+     * invisible to `looply runs` and unreachable by `--reap`, with no file anyone
+     * could point at.
+     */
+    if (holderAlive((0, run_lease_1.leasePathIn)(stateDir), probe))
+        return true;
+    return holderAlive((0, node_path_1.join)(stateDir, CREATING), probe, { corruptIsBusy: false });
+}
+function holderAlive(path, probe, opts = {}) {
+    /**
+     * 🔴 A PARSE FAILURE AND A READ FAILURE ARE DIFFERENT THINGS, and one flag
+     * covering both was wrong for the creation marker.
+     *
+     * CANNOT OPEN IT (EACCES, EBUSY, EPERM, an I/O error) is a failure to ASK.
+     * Nothing has been learned, so the answer is always "somebody may be here".
+     * Reading that as "free" is how `--reap` deletes a starting run's checkout —
+     * which by construction has no lease yet, so the marker is its only defence.
+     *
+     * CANNOT PARSE IT is a statement about the contents, and what it means depends
+     * on the file. A LEASE is rewritten on an ordinary schedule, so unparseable
+     * most likely means caught mid-write: busy. The MARKER is written once,
+     * temp-then-rename, so it cannot be caught mid-write at all: unparseable means
+     * corrupt, and treating corruption as busy wedges that workspace for ever.
+     */
+    const corruptIsBusy = opts.corruptIsBusy !== false;
+    let text;
+    try {
+        text = (0, node_fs_1.readFileSync)(path, 'utf8');
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return false;
+        return true; // could not ask
+    }
+    try {
+        const pid = JSON.parse(text).pid;
+        return typeof pid !== 'number' || probe(pid) !== 'dead';
+    }
+    catch {
+        return corruptIsBusy;
+    }
+}
+/** Written the moment a workspace is cut, so the gap before the lease is covered. */
+const CREATING = 'creating.json';
+/** Whose start marker a workspace carries, so a person can be warned before clearing it. */
+function creationMarkerHolder(cwd, name, probe = exports.nodeProbe) {
+    if (name === '' || /[\/]/.test(name))
+        return null;
+    try {
+        const at = (0, node_path_1.join)(workspacesRoot(cwd), name, git_driver_1.STATE_DIR, 'state', CREATING);
+        const pid = JSON.parse((0, node_fs_1.readFileSync)(at, 'utf8')).pid;
+        return typeof pid === 'number' ? { pid, liveness: probe(pid) } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Drop the creation marker — the LAST thing a run does, and only then.
+ *
+ * 🔴 THE TIMING IS THE WHOLE DESIGN, and both extremes were shipped and wrong.
+ *
+ * Cleared EARLY (the moment the run had its lease and record) it reopened the
+ * window it exists to close: `releaseHold` gives the lease and the record back
+ * at the TOP of the teardown, with work still to do below it, so a concurrent
+ * `--reap` saw no lease, no record and no marker while the run was still
+ * writing.
+ *
+ * NEVER cleared, it becomes a permanent pid-shaped claim on a finished
+ * checkout: once that pid is recycled the workspace reads as busy for ever,
+ * invisible to `--reap`, with nothing a person could point at.
+ *
+ * So: last, after everything else the run does.
+ */
+function clearCreationMarker(stateDir) {
+    try {
+        (0, node_fs_1.unlinkSync)((0, node_path_1.join)(stateDir, CREATING));
+    }
+    catch {
+        /* absent is the goal state */
+    }
+}
+/**
+ * Drop this run's addressed control file, once the run is over.
+ *
+ * ⚠️ NOT REQUIRED FOR CORRECTNESS EITHER — it is named for a runId that will
+ * never exist again, so nothing can ever read it. It is cleared because
+ * otherwise `looply stop` leaves one behind per stopped run, for ever, in a
+ * directory that never had them: an ordinary Simple Mode checkout would
+ * accumulate a `control.<runId>.json` every time a person pressed stop.
+ *
+ * ⚠️ AND AT TEARDOWN, NOT AT CONSUME. Between consuming a stop and actually
+ * ending, a run is still running and a second stop is still a thing a person
+ * may send it.
+ */
+function clearAddressedControl(stateDir, runId) {
+    try {
+        (0, node_fs_1.unlinkSync)((0, node_path_1.join)(stateDir, `control.${runId}.json`));
+    }
+    catch {
+        /* absent is the goal state */
+    }
+}
+/**
+ * Retire a workspace that no record accounts for.
+ *
+ * Everything the record-based reap checks, minus the record: containment on the
+ * real path, residue, evidence retention, and `worktree remove` without
+ * `--force`. A person's `--in` checkout can never reach this — it is not under
+ * the workspaces root, which is checked first and by realpath.
+ */
+async function reapAbandoned(git, cwd, path, probe = exports.nodeProbe, gitInWorkspace = (dir) => new git_driver_1.GitDriver((0, git_driver_1.nodeGitExec)(dir)), home = (0, node_os_1.homedir)(), 
+/**
+ * `run.carry_into_checkouts` - paths looply provisioned into the checkout
+ * itself. Passed through to `workspaceResidue`, which explains why.
+ */
+carried = []) {
+    const rootReal = realpathDeep(workspacesRoot(cwd, home));
+    const real = realpathDeep(path);
+    if (!contains(rootReal, real)) {
+        return { reaped: false, because: `${path} is not under this project's workspaces root` };
+    }
+    if (checkoutBusy((0, node_path_1.join)(path, git_driver_1.STATE_DIR, 'state'), probe)) {
+        return { reaped: false, because: `something is still using it (${busyBecause((0, node_path_1.join)(path, git_driver_1.STATE_DIR, 'state'), probe)})` };
+    }
+    /**
+     * 🔴 THE QUARANTINE IS CHECKED HERE TOO, AND LEAVING IT OUT DESTROYED THE
+     * CHECKOUT THE QUARANTINE EXISTED TO PROTECT. Measured end to end.
+     *
+     * `reapWorkspace` consulted the quarantine; this — the function `--reap`
+     * calls for every checkout with NO registry record — did not. And the two are
+     * one step apart, because looply's own refusal printed
+     * `looply runs --release <name>`, a workspace directory is NAMED for its
+     * runId, and that command's ordered chain matches the RUN RECORD branch
+     * first. So the person read the refusal, typed exactly what it said, was told
+     * "cleared — the workspace was left alone", and thereby made the checkout
+     * record-less: abandoned. The very next `--reap` printed the `quarantined`
+     * row and then `retired`, in one invocation, and the checkout was gone with
+     * the "do not touch this" record still sitting on disk.
+     *
+     * A protection that one branch honours and its sibling does not is not a
+     * protection; it is a coin toss decided by which list a directory happens to
+     * be on.
+     */
+    const held = (0, workspace_quarantine_1.quarantineOf)(cwd, path);
+    if (held !== null) {
+        return {
+            reaped: false,
+            because: `it is quarantined — ${held.because}. Look at ${path}, then ` +
+                `\`looply runs --release ${(0, node_path_1.basename)(path)}\` when you have`,
+        };
+    }
+    if (!(0, node_fs_1.existsSync)(path))
+        return { reaped: true };
+    const residue = await workspaceResidue(gitInWorkspace(path), path, carried);
+    if (residue.length > 0) {
+        const blind = residue.some((r) => r.startsWith('could not be inspected'));
+        const because = keptBecause(residue, path, blind);
+        // Same rule as `reapWorkspace`: only the answer that cannot be re-derived
+        // is written down. See the note there.
+        if (residue.some((r) => r.startsWith('could not be inspected'))) {
+            (0, workspace_quarantine_1.quarantine)(cwd, path, because, 'reap-abandoned');
+        }
+        return { reaped: false, because };
+    }
+    /**
+     * ⚠️ THE SYNTHETIC ID IS SANITISED. `retainEvidence` uses it as a path segment
+     * and `safeRunId` refuses anything that is not `[A-Za-z0-9_-]` — so a
+     * directory under the workspaces root with a dot or a space in its name would
+     * throw out of `reapAbandoned`, and out of the `--reap` loop that calls it,
+     * abandoning every workspace after it in the list.
+     */
+    const tag = `abandoned-${(0, node_path_1.basename)(path).replace(/[^A-Za-z0-9_-]/g, '-')}`.slice(0, 120);
+    const kept = retainEvidence({ runId: tag, workspace: path }, cwd);
+    if (!kept.ok)
+        return { reaped: false, because: kept.because };
+    try {
+        await git.removeWorktree(path);
+    }
+    catch (e) {
+        return { reaped: false, because: `git would not remove it: ${e.message}` };
+    }
+    await git.pruneWorktrees().catch(() => {
+        /* tidying */
+    });
+    /**
+     * 🔴 AND IT SWEEPS, WHICH IT DID NOT — so the provider-session directory, which
+     * holds a COPY OF THE PROVIDER CREDENTIAL, survived every record-less reap.
+     *
+     * Measured: six of six seeded credential files still on disk after this
+     * function reported `{reaped: true}` and removed the checkout. That is the
+     * exact exposure the sweep was added for, left open on the path that handles
+     * precisely the crashed-before-register workspaces which motivated it.
+     */
+    (0, workspace_residue_sweep_1.sweepWorkspaceResidue)(path);
+    return { reaped: true };
+}
+//# sourceMappingURL=workspace.js.map