dorfl 0.0.0 → 0.1.0

package/dist/item-lock.js

@@ -0,0 +1,1381 @@
+import { randomUUID } from 'node:crypto';
+import { runAsync } from './git.js';
+import { resolveSidecarIdentity } from './sidecar.js';
+import { workItemRel } from './work-layout.js';
+/**
+ * The **unified item-lock module** (prd `ledger-status-per-item-lock-refs`, ADR
+ * `ledger-status-on-per-item-lock-refs`). The runner's ONE lock primitive: ONE
+ * lock per item, on a PER-ITEM hidden ref `refs/dorfl/lock/<entry>`,
+ * acquired by an ATOMIC create-only push and released by DELETING the ref, with a
+ * two-axis (`action` × `state`) entry. It collapses the old transient status
+ * folders (`in-progress`, `needs-attention`, `tasking`, `advancing`) into ONE
+ * lock keyed by item identity; `in-progress` = lock held active for `implement`,
+ * `needs-attention` = lock held `stuck`.
+ *
+ * It GENERALISES the green tracer that proved the dangerous core end-to-end on a
+ * bare `file://` arbiter (the tracer is now this file). The one production
+ * difference from the tracer is the IDENTITY SEAM: callers pass a NAMESPACED item
+ * identity (`task:<slug>` / `prd:<slug>` / `observation:<slug>` / `obs:<slug>`,
+ * or a bare `<slug>` = task), and this module derives the type-encoded lock
+ * `<entry>` (`<type>-<slug>`) through {@link resolveSidecarIdentity} — the SAME
+ * single source of truth the sidecar (`work/questions/<type>-<slug>.md`) and the
+ * work branch (`work/<type>-<slug>`) already use. There is deliberately NO second
+ * identity scheme: a task, a prd,
+ * and an observation that share a slug get DISTINCT lock refs, and the SAME item
+ * under different actions shares ONE ref (so implement / task / advance on one
+ * item are mutually exclusive by construction).
+ *
+ * It is NOT yet wired into claim/task/advance — those are separate, dependent
+ * tasks — and deliberately does NOT touch `main`.
+ *
+ * WHY a per-item ref (not a marker on `main` or a tree on one shared ref):
+ *   - **No false contention, no retry.** The ONLY writer that can contend on item
+ *     X's lock is another writer FOR X — a GENUINE conflict the loser SHOULD lose.
+ *     Two writers for DIFFERENT items touch DIFFERENT refs and never serialise. So
+ *     acquire needs NO refetch-retry budget (contrast the shared-`main` CAS, which
+ *     falsely-contends under parallelism and exhausts its retry cap → exit 3).
+ *   - **Self-cleaning, no storage growth.** Acquire CREATES the ref; release
+ *     DELETES it (not "empties" it), so the live ref set = currently-held items
+ *     only. The lock commit is PARENTLESS (no `main` parent), so on ref-delete it
+ *     is immediately unreachable and reclaimed by normal git gc — and the lock ref
+ *     is fully decoupled from `main`'s object graph.
+ *   - **Branch-inheritance impossible.** Nothing is in `main`'s tree, so a work
+ *     branch cut from `main` inherits no lock state.
+ *   - **Provider-agnostic.** A ref is a ref: the create-only / delete pushes work
+ *     identically on a `--bare file://` arbiter and a real remote.
+ *
+ * ATOMICITY is the `--force-with-lease=<ref>:` (EMPTY expected) create-only push:
+ * the arbiter accepts it ONLY if the ref is still absent; a racer who lost finds
+ * the ref present and is rejected. No nonce gymnastics are needed here (unlike the
+ * shared-`main` CAS) because the ref NAME is the identity — two acquires for the
+ * same item race the SAME ref, and ref-level create-only is itself the mutex.
+ */
+/** The ref namespace for per-item locks. HIDDEN (not `refs/heads/*`): invisible
+ * in the GitHub UI, not swept by branch automation, not fetched by a default
+ * clone. Deletion = "all locks released" (recoverable; work is on the work
+ * branches + `main`). */
+export const LOCK_REF_PREFIX = 'refs/dorfl/lock';
+/**
+ * The single IDENTITY SEAM for the lock: derive the type-encoded lock `<entry>`
+ * (`<type>-<slug>`) from a NAMESPACED item identity, through the shared
+ * {@link resolveSidecarIdentity} resolver (the single source of truth, which the
+ * sidecar filename + the advancing-lock marker also key onto). Accepts the same
+ * forms as that resolver: `task:<slug>` / `prd:<slug>` / `observation:<slug>` /
+ * `obs:<slug>`, or a bare `<slug>` (= task). Acquire/release/read ALL key
+ * through THIS function, so there is one — and only one — addressing scheme.
+ */
+export function lockEntryFor(item) {
+    const { type, slug } = resolveSidecarIdentity(item);
+    return `${type}-${slug}`;
+}
+/** The lock ref for a type-encoded `<entry>` (`<type>-<slug>`). */
+export function itemLockRef(entry) {
+    return `${LOCK_REF_PREFIX}/${entry}`;
+}
+function gitSoft(args, cwd, env) {
+    return runAsync('git', args, cwd, { env });
+}
+async function gitHard(args, cwd, env) {
+    const r = await runAsync('git', args, cwd, { env });
+    if (r.status !== 0) {
+        throw new Error(`git ${args.join(' ')} failed (exit ${r.status}): ${r.stderr.trim()}`);
+    }
+    return r;
+}
+/** The body heading that opens the (possibly multi-line) stuck reason prose. */
+const LOCK_REASON_HEADING = '## Reason';
+/** The body heading that opens the agent-surfaced questions list. */
+const LOCK_QUESTIONS_HEADING = '## Questions';
+/**
+ * Serialise a lock entry to the ref's blob body (markdown frontmatter, like the
+ * advancing marker, so it round-trips and is previewable). The two-axis state
+ * (`entry`/`action`/`state`/`holder`/`since`) lives in the frontmatter; a stuck
+ * entry's FULL reason prose + any surfaced questions live in the BODY (under
+ * `## Reason` / `## Questions`) so they round-trip RICHLY (multi-line reason,
+ * bulleted questions) — the lock entry is the SOLE stuck record now, in a shape a
+ * future advance-surface rung can render. {@link parseLockEntry} is the exact
+ * inverse.
+ */
+export function serialiseLockEntry(e) {
+    const lines = [
+        '---',
+        `entry: ${e.entry}`,
+        `action: ${e.action}`,
+        `state: ${e.state}`,
+        `holder: ${e.holder}`,
+        `since: ${e.since}`,
+        '---',
+        '',
+        `Lock held for \`${e.entry}\` (${e.action}/${e.state}).`,
+    ];
+    if (e.state === 'stuck' && e.reason) {
+        lines.push('', LOCK_REASON_HEADING, '', ...e.reason.split('\n'));
+    }
+    if (e.state === 'stuck' && e.questions && e.questions.length > 0) {
+        lines.push('', LOCK_QUESTIONS_HEADING, '');
+        for (const q of e.questions) {
+            lines.push(`- ${q}`);
+        }
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * Build a PARENTLESS commit whose tree contains the single lock-entry blob, and
+ * return its sha. Parentless (no `-p`) so it is decoupled from `main` and becomes
+ * unreachable the instant the ref is deleted (gc reclaims it). Uses plumbing
+ * (`hash-object` → `mktree` → `commit-tree`), never the working tree/index/HEAD,
+ * so it is safe to call from any worktree.
+ */
+async function buildLockCommit(entry, cwd, env) {
+    const body = serialiseLockEntry(entry);
+    const blob = (await gitHardInput(['hash-object', '-w', '--stdin'], cwd, env, body)).stdout.trim();
+    // One tree entry: `lock.md` → the blob.
+    const treeInput = `100644 blob ${blob}\tlock.md\n`;
+    const tree = (await gitHardInput(['mktree'], cwd, env, treeInput)).stdout.trim();
+    const message = `lock: ${entry.entry} (${entry.action}/${entry.state})`;
+    // PARENTLESS commit (no -p): the lock graph never joins main's history.
+    const commit = (await gitHard(['commit-tree', tree, '-m', message], cwd, env)).stdout.trim();
+    return commit;
+}
+/** `gitHard` variant that pipes `input` to stdin (for hash-object/mktree). */
+async function gitHardInput(args, cwd, env, input) {
+    const r = await runAsync('git', args, cwd, { env, input });
+    if (r.status !== 0) {
+        throw new Error(`git ${args.join(' ')} failed (exit ${r.status}): ${r.stderr.trim()}`);
+    }
+    return r;
+}
+/**
+ * Acquire the per-item lock atomically: build a parentless lock commit and push it
+ * to `refs/dorfl/lock/<entry>` with `--force-with-lease=<ref>:` (the EMPTY
+ * expected value = create-only). The arbiter accepts ONLY if the ref is still
+ * absent. A racer who lost finds the ref present → its lease fails → `lost`. No
+ * retry loop: a rejection here is a GENUINE same-item conflict, not false
+ * contention.
+ */
+export async function acquireItemLock(opts) {
+    const arbiter = opts.arbiter ?? 'origin';
+    const env = opts.env;
+    const cwd = opts.cwd;
+    if (!opts.item) {
+        return { outcome: 'error', entry: '', ref: '', message: 'missing item' };
+    }
+    const entry = lockEntryFor(opts.item);
+    const ref = itemLockRef(entry);
+    try {
+        // Fetch the current lock refs so the lease sees the real state.
+        await gitHard([
+            'fetch',
+            '--quiet',
+            arbiter,
+            `+${LOCK_REF_PREFIX}/*:${LOCK_REF_PREFIX}/*`,
+        ], cwd, env);
+        const holder = opts.holder ?? (await resolveHolder(cwd, env));
+        const commit = await buildLockCommit({
+            entry,
+            action: opts.action,
+            state: 'active',
+            holder,
+            since: new Date().toISOString(),
+        }, cwd, env);
+        // CREATE-ONLY push: --force-with-lease=<ref>: (empty) succeeds iff ref absent.
+        const push = await gitSoft(['push', arbiter, `${commit}:${ref}`, `--force-with-lease=${ref}:`], cwd, env);
+        if (push.status === 0) {
+            return { outcome: 'acquired', entry, ref, message: `locked ${entry}` };
+        }
+        // Rejected: the ref already exists (held by someone for the SAME item).
+        return {
+            outcome: 'lost',
+            entry,
+            ref,
+            message: `'${entry}' is already locked (held by another). Back off.`,
+        };
+    }
+    catch (err) {
+        return {
+            outcome: 'error',
+            entry,
+            ref,
+            message: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * Release the per-item lock by DELETING the ref (`git push <arbiter>
+ * :refs/dorfl/lock/<entry>`). Deleting (not emptying) is what makes the
+ * lock set self-cleaning: a released item has NO ref, and its parentless commit
+ * becomes unreachable for gc. Idempotent: deleting an absent ref is `not-held`.
+ */
+export async function releaseItemLock(opts) {
+    const arbiter = opts.arbiter ?? 'origin';
+    const env = opts.env;
+    const cwd = opts.cwd;
+    if (!opts.item) {
+        return { outcome: 'error', entry: '', ref: '', message: 'missing item' };
+    }
+    const entry = lockEntryFor(opts.item);
+    const ref = itemLockRef(entry);
+    try {
+        await gitHard([
+            'fetch',
+            '--quiet',
+            arbiter,
+            `+${LOCK_REF_PREFIX}/*:${LOCK_REF_PREFIX}/*`,
+        ], cwd, env);
+        const held = (await gitSoft(['rev-parse', '--verify', '--quiet', ref], cwd, env))
+            .status === 0;
+        if (!held) {
+            return {
+                outcome: 'not-held',
+                entry,
+                ref,
+                message: `'${entry}' not locked`,
+            };
+        }
+        // Delete the ref on the arbiter. Lease on the current value guards against a
+        // concurrent change between our fetch and the delete.
+        const cur = (await gitHard(['rev-parse', ref], cwd, env)).stdout.trim();
+        const del = await gitSoft(['push', arbiter, '--delete', ref, `--force-with-lease=${ref}:${cur}`], cwd, env);
+        if (del.status === 0) {
+            // Drop our local copy of the ref too (best-effort).
+            await gitSoft(['update-ref', '-d', ref], cwd, env);
+            return { outcome: 'released', entry, ref, message: `released ${entry}` };
+        }
+        return {
+            outcome: 'error',
+            entry,
+            ref,
+            message: `release push rejected: ${del.stderr.trim()}`,
+        };
+    }
+    catch (err) {
+        return {
+            outcome: 'error',
+            entry,
+            ref,
+            message: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * GUARDED release for a runner that KNOWS it acquired and HELD the lock (prd
+ * `ledger-status-per-item-lock-refs` US #13): unlike {@link releaseItemLock} —
+ * whose `not-held` is a BENIGN idempotent case the complete/tasking/needs-attention
+ * callers tolerate (the body may predate the lock, or a crash-recovery may have
+ * already cleared it) — here the absence of OUR ref is an ABORT SIGNAL. A held
+ * runner whose own lock VANISHED mid-build (someone `release-lock`-ed it, or a
+ * `gc`/recovery cleared it) must DETECT it on release and route to
+ * needs-attention rather than silently "clean-release" a lock it no longer holds:
+ * the work it just did was NOT protected by the exclusion it thought it had.
+ *
+ * So this maps {@link releaseItemLock}'s `not-held` to a DISTINCT `vanished`
+ * outcome the caller branches on (abort / needs-attention), while a genuine
+ * `released` is the happy path and `error` stays `error`. It is otherwise the
+ * SAME leased delete (no second mechanism): a clean `released` deletes the ref we
+ * held. Use this ONLY where the caller provably HELD the lock (the in-flight
+ * runner's own release); the tolerant idempotent callers keep using
+ * {@link releaseItemLock}.
+ */
+export async function releaseHeldItemLock(opts) {
+    const rel = await releaseItemLock(opts);
+    if (rel.outcome === 'not-held') {
+        return {
+            outcome: 'vanished',
+            entry: rel.entry,
+            ref: rel.ref,
+            message: `'${rel.entry}' lock VANISHED before our release (the ref is gone) — our hold was lost mid-build; abort / route to needs-attention rather than clean-release.`,
+        };
+    }
+    return {
+        outcome: rel.outcome,
+        entry: rel.entry,
+        ref: rel.ref,
+        message: rel.message,
+    };
+}
+/**
+ * Fetch the lock refs and return the held entry + its current ref sha, or
+ * `undefined` when the item is at REST (no ref). Shared read-before-CAS step for
+ * the amend-style transitions (mark-stuck / resume / requeue): they all need BOTH
+ * the current entry (to check the state precondition + carry forward `action` /
+ * `holder` / `since`) and the current sha (to lease the CAS on it).
+ */
+async function fetchHeldEntry(entry, ref, cwd, arbiter, env) {
+    await gitHard(['fetch', '--quiet', arbiter, `+${LOCK_REF_PREFIX}/*:${LOCK_REF_PREFIX}/*`], cwd, env);
+    const rev = await gitSoft(['rev-parse', '--verify', '--quiet', ref], cwd, env);
+    if (rev.status !== 0 || rev.stdout.trim() === '') {
+        return undefined;
+    }
+    const sha = rev.stdout.trim();
+    const show = await gitSoft(['show', `${ref}:lock.md`], cwd, env);
+    const lock = show.status === 0 ? parseLockEntry(show.stdout) : undefined;
+    if (!lock) {
+        return undefined;
+    }
+    return { lock, sha };
+}
+/**
+ * AMEND the held entry in place via a leased CAS: build a NEW parentless commit
+ * carrying `next` and push it to the SAME ref with `--force-with-lease=<ref>:<sha>`
+ * (the sha we just read). The arbiter accepts ONLY if the ref is unchanged since
+ * our read — a concurrent writer who moved it makes our lease fail (`lost`). No
+ * retry loop: a rejection is a genuine same-item race the caller should lose.
+ */
+async function amendHeldEntry(next, ref, expectedSha, cwd, arbiter, env) {
+    const commit = await buildLockCommit(next, cwd, env);
+    const push = await gitSoft([
+        'push',
+        arbiter,
+        `${commit}:${ref}`,
+        `--force-with-lease=${ref}:${expectedSha}`,
+    ], cwd, env);
+    if (push.status === 0) {
+        // Move our local copy to the new commit too (best-effort) so a subsequent
+        // read in the same clone sees the amended entry without a refetch.
+        await gitSoft(['update-ref', ref, commit], cwd, env);
+        return {
+            outcome: 'transitioned',
+            entry: next.entry,
+            ref,
+            message: `${next.entry} → ${next.action}/${next.state}`,
+            lock: next,
+        };
+    }
+    return {
+        outcome: 'lost',
+        entry: next.entry,
+        ref,
+        message: `'${next.entry}' lock changed concurrently (CAS lost). Back off.`,
+    };
+}
+/**
+ * The ONE leased-delete CLEAR path shared by every code path that removes a held
+ * lock ref by lease (the recovery {@link reconcileItemLockAgainstMain}, the
+ * human-invoked {@link reapStaleItemLocks} sweep, …): delete `ref` on the arbiter
+ * with `--force-with-lease=<ref>:<expectedSha>`, so the arbiter accepts ONLY if the
+ * ref is UNCHANGED since the caller read `expectedSha`. A concurrent writer who
+ * moved the ref (e.g. a racer who just marked it `stuck`) makes the lease FAIL →
+ * `lost` (reported, NEVER force-deleted). On success the local copy is dropped too
+ * (best-effort). It is the SAME leased delete `release-lock` / requeue use — there
+ * is no second clear mechanism.
+ */
+async function leasedDeleteLockRef(ref, expectedSha, cwd, arbiter, env) {
+    const del = await gitSoft([
+        'push',
+        arbiter,
+        '--delete',
+        ref,
+        `--force-with-lease=${ref}:${expectedSha}`,
+    ], cwd, env);
+    if (del.status !== 0) {
+        return 'lost';
+    }
+    // Drop our local copy of the ref too (best-effort) so a subsequent read in the
+    // same clone does not see the now-deleted lock.
+    await gitSoft(['update-ref', '-d', ref], cwd, env);
+    return 'deleted';
+}
+/**
+ * mark-stuck (transition 2): `[action, active] -> [action, stuck] + reason`. The
+ * runner bounces (red gate, agent failure, decomposition-unclear). A leased CAS
+ * amend of the SAME entry's `state` + `reason`, keeping `action`/`holder`/`since`.
+ * It is the source of the needs-attention SURFACE (now read from the lock ref,
+ * not a `work/needs-attention/` folder).
+ *
+ * PRECONDITIONS (the state machine + invariants):
+ *   - the entry must be HELD and `active` (`not-held` / `wrong-state` otherwise) —
+ *     stuck is reachable only FROM active, never from absent or already-stuck.
+ *   - `reason` must be non-empty (the `reason` PRESENT iff `state: stuck` invariant).
+ */
+export async function markStuckItemLock(opts) {
+    const arbiter = opts.arbiter ?? 'origin';
+    const env = opts.env;
+    const cwd = opts.cwd;
+    if (!opts.item) {
+        return { outcome: 'error', entry: '', ref: '', message: 'missing item' };
+    }
+    const entry = lockEntryFor(opts.item);
+    const ref = itemLockRef(entry);
+    if (!opts.reason || opts.reason.trim() === '') {
+        return {
+            outcome: 'error',
+            entry,
+            ref,
+            message: 'mark-stuck requires a reason (reason iff stuck)',
+        };
+    }
+    try {
+        const held = await fetchHeldEntry(entry, ref, cwd, arbiter, env);
+        if (!held) {
+            return {
+                outcome: 'not-held',
+                entry,
+                ref,
+                message: `'${entry}' not locked`,
+            };
+        }
+        if (held.lock.state !== 'active') {
+            return {
+                outcome: 'wrong-state',
+                entry,
+                ref,
+                message: `'${entry}' is ${held.lock.state}, not active; cannot mark-stuck`,
+            };
+        }
+        const next = {
+            ...held.lock,
+            state: 'stuck',
+            reason: opts.reason.trim(),
+        };
+        const questions = (opts.questions ?? [])
+            .map((q) => q.trim())
+            .filter((q) => q !== '');
+        if (questions.length > 0) {
+            next.questions = questions;
+        }
+        else {
+            delete next.questions;
+        }
+        return await amendHeldEntry(next, ref, held.sha, cwd, arbiter, env);
+    }
+    catch (err) {
+        return {
+            outcome: 'error',
+            entry,
+            ref,
+            message: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * resume (transition 3): `[action, stuck] -> [action, active]`. A human (or a
+ * `continue`) picks the stuck item up: amend `state` back to `active` and CLEAR
+ * `reason` (the `reason` iff `stuck` invariant — an active entry never carries a
+ * stuck reason). Keeps the same `action`; `holder` may be reassigned. The
+ * lock-entry analogue of the old `needs-attention -> in-progress` folder move.
+ *
+ * PRECONDITION: the entry must be HELD and `stuck` (`not-held` / `wrong-state`
+ * otherwise) — active is reachable from stuck only, not from absent.
+ */
+export async function resumeItemLock(opts) {
+    const arbiter = opts.arbiter ?? 'origin';
+    const env = opts.env;
+    const cwd = opts.cwd;
+    if (!opts.item) {
+        return { outcome: 'error', entry: '', ref: '', message: 'missing item' };
+    }
+    const entry = lockEntryFor(opts.item);
+    const ref = itemLockRef(entry);
+    try {
+        const held = await fetchHeldEntry(entry, ref, cwd, arbiter, env);
+        if (!held) {
+            return {
+                outcome: 'not-held',
+                entry,
+                ref,
+                message: `'${entry}' not locked`,
+            };
+        }
+        if (held.lock.state !== 'stuck') {
+            return {
+                outcome: 'wrong-state',
+                entry,
+                ref,
+                message: `'${entry}' is ${held.lock.state}, not stuck; nothing to resume`,
+            };
+        }
+        const next = {
+            ...held.lock,
+            state: 'active',
+            holder: opts.holder ?? held.lock.holder,
+        };
+        // reason + questions are PRESENT iff stuck: drop them on the way to active.
+        delete next.reason;
+        delete next.questions;
+        return await amendHeldEntry(next, ref, held.sha, cwd, arbiter, env);
+    }
+    catch (err) {
+        return {
+            outcome: 'error',
+            entry,
+            ref,
+            message: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * requeue (transition 4): `[action, stuck] -> (absent)`. Give up on a STUCK hold
+ * and return the item to the pool by REMOVING the entry. The body never moved
+ * (Amendment 5 — it is already resting in `backlog/` on `main`), so requeue is
+ * purely "release the lock"; the kept `work/<slug>` branch remains for recovery.
+ *
+ * Distinct from {@link releaseItemLock} (transition 6, abort from ACTIVE): requeue
+ * is the GUARDED give-up from `stuck` only, so it rejects (`wrong-state`) an
+ * `active` entry — abandoning an in-flight active hold goes through `release`, not
+ * `requeue`. The removal itself is a leased delete (a concurrent change ⇒ `lost`).
+ */
+export async function requeueItemLock(opts) {
+    const arbiter = opts.arbiter ?? 'origin';
+    const env = opts.env;
+    const cwd = opts.cwd;
+    if (!opts.item) {
+        return { outcome: 'error', entry: '', ref: '', message: 'missing item' };
+    }
+    const entry = lockEntryFor(opts.item);
+    const ref = itemLockRef(entry);
+    try {
+        const held = await fetchHeldEntry(entry, ref, cwd, arbiter, env);
+        if (!held) {
+            return {
+                outcome: 'not-held',
+                entry,
+                ref,
+                message: `'${entry}' not locked`,
+            };
+        }
+        if (held.lock.state !== 'stuck') {
+            return {
+                outcome: 'wrong-state',
+                entry,
+                ref,
+                message: `'${entry}' is ${held.lock.state}, not stuck; use release to abort an active hold`,
+            };
+        }
+        const del = await gitSoft([
+            'push',
+            arbiter,
+            '--delete',
+            ref,
+            `--force-with-lease=${ref}:${held.sha}`,
+        ], cwd, env);
+        if (del.status === 0) {
+            await gitSoft(['update-ref', '-d', ref], cwd, env);
+            return {
+                outcome: 'transitioned',
+                entry,
+                ref,
+                message: `requeued ${entry} (lock released, body still in pool)`,
+            };
+        }
+        return {
+            outcome: 'lost',
+            entry,
+            ref,
+            message: `'${entry}' lock changed concurrently (CAS lost). Back off.`,
+        };
+    }
+    catch (err) {
+        return {
+            outcome: 'error',
+            entry,
+            ref,
+            message: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * Read the current lock entry for an item from the arbiter (the `status`/`scan`
+ * read path): fetch the lock refs, read `lock.md` from the ref's tree. Returns
+ * `undefined` when the item is not locked.
+ */
+export async function readItemLock(opts) {
+    const arbiter = opts.arbiter ?? 'origin';
+    const env = opts.env;
+    const cwd = opts.cwd;
+    const ref = itemLockRef(lockEntryFor(opts.item));
+    await gitHard(['fetch', '--quiet', arbiter, `+${LOCK_REF_PREFIX}/*:${LOCK_REF_PREFIX}/*`], cwd, env);
+    const show = await gitSoft(['show', `${ref}:lock.md`], cwd, env);
+    if (show.status !== 0) {
+        return undefined;
+    }
+    return parseLockEntry(show.stdout);
+}
+/**
+ * The DURABLE-`main` terminal record paths for an item, by its type — the
+ * authoritative resting records the cross-substrate reconciliation reads. An
+ * item is TERMINAL on `main` iff ANY of these paths exists on `<arbiter>/main`.
+ * The won't-proceed terminal is PER-REGIME (the slug-collision correctness fix:
+ * a dropped task and a dropped prd sharing a slug used to collide on one
+ * bare-slug `work/dropped/<slug>.md`):
+ *   - a TASK: `work/tasks/done/<slug>.md` (completed) OR
+ *     `work/tasks/cancelled/<slug>.md` (the task regime's won't-proceed terminal).
+ *   - a PRD: `work/prds/tasked/<slug>.md` (tasked) OR `work/prds/dropped/<slug>.md`
+ *     (the prd regime's won't-proceed terminal).
+ *   - an OBSERVATION: NONE. A note has no durable terminal folder — it leaves by
+ *     deletion (its absence, not a terminal record, is the end state). A promoted
+ *     observation becomes a NEW task/prd with its own ref.
+ */
+export function terminalMainPaths(type, slug) {
+    const file = `${slug}.md`;
+    switch (type) {
+        case 'task':
+            return [workItemRel('done', file), workItemRel('cancelled', file)];
+        // The parent-spec regime's durable terminals (`specs/tasked` tasked,
+        // `specs/dropped` won't-proceed) — a `spec:<slug>` lock resolves to these
+        // `work/specs/*` records.
+        case 'spec':
+            return [
+                workItemRel('specs-tasked', file),
+                workItemRel('specs-dropped', file),
+            ];
+        case 'observation':
+            return [];
+    }
+}
+/**
+ * Reconcile ONE item's per-item lock against the AUTHORITATIVE `main` durable
+ * record — the heart of complete's cross-substrate crash-safety (prd
+ * `ledger-status-per-item-lock-refs` US #9/#10; ADR
+ * `ledger-status-on-per-item-lock-refs`; the design trail's Amendment 6).
+ *
+ * complete's order is hold lock → land the DURABLE `main` move FIRST → release
+ * the lock SECOND. A crash BETWEEN the move and the release leaves a
+ * terminal-on-`main` item (a completed/cancelled task or a tasked/dropped prd,
+ * per {@link terminalMainPaths}) with a STILL-HELD lock — a stale lock with no
+ * in-flight work behind it. This is the recovery that converges it.
+ *
+ * THE RECOVERY RULE (the `main` record is authoritative over a stale lock):
+ *   - `main` is TERMINAL + the held lock is `active`  → the item is RESTED, the
+ *     lock is STALE (the crash was after the move) → CLEAR it (`cleared-stale`).
+ *   - `main` is TERMINAL + the held lock is `stuck`   → KEEP it (`kept-stuck`).
+ *     `done` + `stuck` may legitimately CO-EXIST (a rebase-conflict bounce of a
+ *     just-completed item — US #10). The stuck lock wins the human's attention;
+ *     the `main` record wins dependency resolution. NOT corruption, never cleared
+ *     here (a human resolves it via `resume`/`requeue`/`release-lock`).
+ *   - `main` is NOT terminal + a lock is held         → the NORMAL in-flight
+ *     state (`kept-in-flight`); the lock is doing its job, leave it.
+ *   - no lock at all                                   → `no-lock` (at rest).
+ *
+ * Best-effort + idempotent: it NEVER throws (a fetch/read fault degrades to
+ * `error`, leaving the lock untouched — the safe direction), and re-running it
+ * on an already-reconciled item is a clean `no-lock`. The clear is the SAME
+ * leased delete {@link releaseItemLock} uses, so it cannot race off a concurrent
+ * change.
+ *
+ * BROADENED CONTRACT (leased-delete-rejection arm, task
+ * `reaper-no-lock-outcome-benign-not-lost`, promote-slice follow-up
+ * `reconcile-item-lock-broadened-contract-audit`, review 2026-06-20): when the
+ * SHARED leased delete is REJECTED (the arbiter ref moved between our read and
+ * our write) this function performs an EXTRA `git ls-remote <arbiter> <ref>`
+ * round-trip to distinguish the two rejection sub-cases, and applies to ALL
+ * callers — NOT only the reaper:
+ *   - REMOTE REF IS EMPTY (a concurrent reaper / release-lock / requeue cleared
+ *     the SAME stale lock first): the desired end state — benign. This function
+ *     ALSO `git update-ref -d`s the LOCAL stale tracking ref as a SIDE-EFFECT
+ *     (so a subsequent read in this clone sees the correct deleted state; a
+ *     non-pruning fetch would otherwise leave a dangling local ref), then
+ *     returns `no-lock`. Note the outcome-shape change: this rejection USED TO
+ *     surface as `error` — it now surfaces as `no-lock` for EVERY caller. A
+ *     caller that keys recovery / surfacing off `error` on this arm must be
+ *     audited (see the follow-up task's `## Decisions` block).
+ *   - REMOTE REF STILL EXISTS AT A DIFFERENT SHA (a genuine concurrent mutation
+ *     — e.g. a racer just marked it `stuck`): back off rather than force —
+ *     `error`.
+ * Because the function name reads "reconcile" (read-style), the local
+ * `update-ref -d` is a deliberate SIDE-EFFECT on the local clone's refs — it
+ * only fires on this specific rejection arm and is otherwise invisible.
+ */
+export async function reconcileItemLockAgainstMain(opts) {
+    const arbiter = opts.arbiter ?? 'origin';
+    const env = opts.env;
+    const cwd = opts.cwd;
+    if (!opts.item) {
+        return {
+            outcome: 'error',
+            entry: '',
+            ref: '',
+            terminalOnMain: false,
+            message: 'missing item',
+        };
+    }
+    const { type, slug } = resolveSidecarIdentity(opts.item);
+    const entry = lockEntryFor(opts.item);
+    const ref = itemLockRef(entry);
+    try {
+        // One fetch refreshes BOTH the lock refs and `<arbiter>/main` so the lock and
+        // the durable record are read from the SAME live arbiter snapshot.
+        await gitHard([
+            'fetch',
+            '--quiet',
+            arbiter,
+            `+${LOCK_REF_PREFIX}/*:${LOCK_REF_PREFIX}/*`,
+        ], cwd, env);
+        await gitHard(['fetch', '--quiet', arbiter], cwd, env);
+        const held = await fetchHeldEntry(entry, ref, cwd, arbiter, env);
+        const terminalOnMain = await isTerminalOnMain(type, slug, arbiter, cwd, env);
+        if (!held) {
+            return {
+                outcome: 'no-lock',
+                entry,
+                ref,
+                terminalOnMain,
+                message: `'${entry}' has no lock to reconcile`,
+            };
+        }
+        if (!terminalOnMain) {
+            // A held lock + a non-terminal `main` is the NORMAL in-flight state.
+            return {
+                outcome: 'kept-in-flight',
+                entry,
+                ref,
+                terminalOnMain,
+                message: `'${entry}' is in flight (held, not terminal on ${arbiter}/main)`,
+            };
+        }
+        if (held.lock.state === 'stuck') {
+            // a terminal-on-main record + `stuck` co-exist legitimately (US #10) —
+            // NOT corruption. Keep the stuck lock (it wins the human's attention).
+            return {
+                outcome: 'kept-stuck',
+                entry,
+                ref,
+                terminalOnMain,
+                message: `'${entry}' is terminal on ${arbiter}/main but STUCK — kept for human attention (resume/requeue/release-lock)`,
+            };
+        }
+        // Terminal on `main` + an `active` lock = a STALE lock (the crash was after
+        // the durable move, before the release). The `main` record is authoritative:
+        // clear the stale lock with the SHARED leased delete (the SAME one
+        // `release-lock` / requeue / the reaper use).
+        const cleared = await leasedDeleteLockRef(ref, held.sha, cwd, arbiter, env);
+        if (cleared === 'deleted') {
+            return {
+                outcome: 'cleared-stale',
+                entry,
+                ref,
+                terminalOnMain,
+                message: `cleared the stale lock for '${entry}' (terminal on ${arbiter}/main; the durable record is authoritative)`,
+            };
+        }
+        // The leased delete was REJECTED. Distinguish two sub-cases at the recovery
+        // boundary so callers (the reaper) can route them differently:
+        //   (a) the remote ref is ALREADY GONE — a concurrent reaper / release-lock /
+        //       requeue cleared the SAME stale lock first. The desired end state;
+        //       benign — we report `no-lock` (the existing "already at rest" verdict).
+        //   (b) the remote ref still exists but at a DIFFERENT sha than we leased
+        //       against — a genuine concurrent mutation (e.g. a racer just marked it
+        //       `stuck`). Back off rather than force; this is the real `error`.
+        const remote = await gitSoft(['ls-remote', arbiter, ref], cwd, env);
+        const remoteEmpty = remote.status === 0 && remote.stdout.trim() === '';
+        if (remoteEmpty) {
+            // Drop our stale local copy too — a non-pruning fetch left it pointing at
+            // the now-gone sha; with it gone locally a subsequent read in this clone
+            // sees the correct (deleted) state.
+            await gitSoft(['update-ref', '-d', ref], cwd, env);
+            return {
+                outcome: 'no-lock',
+                entry,
+                ref,
+                terminalOnMain,
+                message: `'${entry}' has no lock to reconcile (already cleared by another reaper / release-lock / requeue)`,
+            };
+        }
+        return {
+            outcome: 'error',
+            entry,
+            ref,
+            terminalOnMain,
+            message: `stale-lock clear for '${entry}' rejected (changed concurrently to a different value); a racer may have moved the ref. Re-run after re-checking.`,
+        };
+    }
+    catch (err) {
+        return {
+            outcome: 'error',
+            entry,
+            ref,
+            terminalOnMain: false,
+            message: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * The READ-ONLY classifier behind {@link reconcileItemLockAgainstMain}: it derives
+ * the SAME {@link ReconcileOutcome} verdict, but NEVER mutates the arbiter — it
+ * does NOT clear a stale-active lock, it only REPORTS that the lock IS
+ * reconcilable. This is what the `gc --ledger` stuck-lock report keys off (the
+ * forward-pointer's wiring): per the no-auto-sweep ADR rule, the plain report
+ * surfaces a stale-active lock as `cleared-stale`-eligible WITHOUT clearing it —
+ * a human still asserts the clear via `release-lock` (or runs complete's recovery,
+ * which DOES clear via {@link reconcileItemLockAgainstMain}). The classification
+ * is identical so the report and the recovery never disagree about WHAT a lock is;
+ * only the ACTION differs (report vs clear).
+ *
+ * A `cleared-stale` outcome here therefore means "would be cleared by recovery /
+ * `release-lock`" (the lock is terminal-on-`main` + `active` = stale), NOT that
+ * anything was cleared. Best-effort + never throws (a fetch/read fault degrades to
+ * `error`).
+ */
+export async function classifyItemLockAgainstMain(opts) {
+    const arbiter = opts.arbiter ?? 'origin';
+    const env = opts.env;
+    const cwd = opts.cwd;
+    if (!opts.item) {
+        return {
+            outcome: 'error',
+            entry: '',
+            ref: '',
+            terminalOnMain: false,
+            message: 'missing item',
+        };
+    }
+    const { type, slug } = resolveSidecarIdentity(opts.item);
+    const entry = lockEntryFor(opts.item);
+    const ref = itemLockRef(entry);
+    try {
+        await gitHard([
+            'fetch',
+            '--quiet',
+            arbiter,
+            `+${LOCK_REF_PREFIX}/*:${LOCK_REF_PREFIX}/*`,
+        ], cwd, env);
+        await gitHard(['fetch', '--quiet', arbiter], cwd, env);
+        const held = await fetchHeldEntry(entry, ref, cwd, arbiter, env);
+        const terminalOnMain = await isTerminalOnMain(type, slug, arbiter, cwd, env);
+        if (!held) {
+            return {
+                outcome: 'no-lock',
+                entry,
+                ref,
+                terminalOnMain,
+                message: `'${entry}' has no lock to reconcile`,
+            };
+        }
+        if (!terminalOnMain) {
+            return {
+                outcome: 'kept-in-flight',
+                entry,
+                ref,
+                terminalOnMain,
+                message: `'${entry}' is in flight (held, not terminal on ${arbiter}/main)`,
+            };
+        }
+        if (held.lock.state === 'stuck') {
+            return {
+                outcome: 'kept-stuck',
+                entry,
+                ref,
+                terminalOnMain,
+                message: `'${entry}' is terminal on ${arbiter}/main but STUCK — kept for human attention (resume/requeue/release-lock)`,
+            };
+        }
+        // Terminal on `main` + an `active` lock = a STALE lock. Unlike
+        // `reconcileItemLockAgainstMain` we do NOT clear it here — the report only
+        // names it as reconcilable; the human asserts the clear (no auto-sweep).
+        return {
+            outcome: 'cleared-stale',
+            entry,
+            ref,
+            terminalOnMain,
+            message: `'${entry}' is terminal on ${arbiter}/main but the lock is ACTIVE — reconcilable (stale); clear via 'release-lock' (NOT auto-cleared by the report)`,
+        };
+    }
+    catch (err) {
+        return {
+            outcome: 'error',
+            entry,
+            ref,
+            terminalOnMain: false,
+            message: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * Build the `gc --ledger` stuck/orphaned-lock REPORT (prd
+ * `ledger-status-per-item-lock-refs` US #12/#13/#14; ADR
+ * `ledger-status-on-per-item-lock-refs`): enumerate every per-item lock currently
+ * held on the arbiter ({@link listItemLockEntries} — held active + stuck, with
+ * holder/since/reason) and classify EACH read-only against the authoritative
+ * `main` durable record via {@link classifyItemLockAgainstMain} (the wiring the
+ * `complete-lock-then-durable-main-move-crash-safe` task's
+ * `reconcileItemLockAgainstMain` had no production caller for). This is the
+ * generalisation of the (now-retired) advancing-marker report from advancing-only
+ * to the UNIFIED lock (the `gc --ledger` stuck-lock report).
+ *
+ * It is a REPORT, never a sweep: it CLEARS nothing (no liveness heartbeat, no
+ * auto-sweep — the same trust model as the advancing report; a human asserts a
+ * lock is dead via `release-lock`). A stale-active lock over a terminal-on-`main`
+ * item is surfaced as `cleared-stale`-eligible ("reconcilable") but left in place.
+ *
+ * Best-effort + degrades safely: an absent lock-ref namespace ⇒ an EMPTY report
+ * ({@link listItemLockEntries} returns `[]`) — so a deleted lock ref reads as "all
+ * locks released" (recoverable; work is safe on the `work/<slug>` branches +
+ * `main`).
+ */
+export async function reportItemLocks(cwd, arbiter = 'origin', env) {
+    const entries = await listItemLockEntries(cwd, arbiter, env);
+    const locks = [];
+    for (const lock of entries) {
+        const ref = itemLockRef(lock.entry);
+        // Read-only classification against `main` — NEVER clears (the report is
+        // advisory; a human asserts the clear via `release-lock`).
+        const verdict = await classifyItemLockAgainstMain({
+            item: itemFromLockEntry(lock.entry),
+            cwd,
+            arbiter,
+            env,
+        });
+        locks.push({ lock, ref, reconcile: verdict.outcome });
+    }
+    return { locks };
+}
+/**
+ * Format the `gc --ledger` stuck/orphaned-lock REPORT for the terminal: one block
+ * per lingering lock (entry, action/state, holder, since, the stuck `reason`, the
+ * read-only `main`-reconciliation note, and a copy-pasteable `release-lock`
+ * hint). An EMPTY report yields NO lines (a clean lock set is silent here, like
+ * the duplicate-slug surface). It REPORTS only — the matching wording makes the
+ * no-auto-sweep contract explicit (a human asserts a lock is dead).
+ */
+/**
+ * Does the `gc --ledger` lock report contain a lock that NEEDS HUMAN ATTENTION
+ * (prd US#14/#21; ADR `ledger-status-on-per-item-lock-refs`: this surface is the
+ * STUCK / crash-orphaned lock, NOT every held one)? TRUE iff some lock is
+ * `kept-stuck` (terminal-on-`main` + stuck) or `cleared-stale`-eligible
+ * (terminal-on-`main` + a stale active orphan). A `kept-in-flight` (active,
+ * non-terminal) lock is the NORMAL in-flight state of a healthy concurrent build
+ * (read by `status` as healthy) and does NOT count — so a routine `gc --ledger`
+ * health check whose only locks are healthy in-flight holds exits 0. This is the
+ * fail-loud EXIT predicate for the gc lock surface (the report itself still lists
+ * every held lock, in-flight ones informationally).
+ */
+export function itemLockReportNeedsAttention(report) {
+    return report.locks.some((l) => l.reconcile === 'kept-stuck' || l.reconcile === 'cleared-stale');
+}
+export function formatItemLockReport(report) {
+    if (report.locks.length === 0) {
+        return [];
+    }
+    const lines = [
+        `Per-item locks: ${report.locks.length} lock(s) held on the arbiter ` +
+            '(REPORT only — no automatic sweep; the lock has no liveness heartbeat, so ' +
+            'a human asserts a stuck/stale lock is dead via `release-lock`):',
+    ];
+    for (const { lock, reconcile } of report.locks) {
+        const item = itemFromLockEntry(lock.entry);
+        lines.push(`  ${lock.entry}  [${lock.action}/${lock.state}]`);
+        lines.push(`    holder: ${lock.holder || '(unknown)'}  since: ${lock.since || '(unknown)'}`);
+        if (lock.state === 'stuck' && lock.reason) {
+            lines.push(`    reason: ${lock.reason}`);
+        }
+        lines.push(`    ${reconcileNote(reconcile)}`);
+        lines.push(`    resolve (if the lock is dead): \`dorfl release-lock ${item}\` (never --force).`);
+    }
+    return lines;
+}
+/** The human-readable line for a lock's read-only `main`-reconciliation verdict. */
+function reconcileNote(reconcile) {
+    switch (reconcile) {
+        case 'kept-in-flight':
+            return 'in flight (held, not terminal on main) — normal; left untouched.';
+        case 'kept-stuck':
+            return 'terminal on main + STUCK (done+stuck co-exist) — kept for human attention.';
+        case 'cleared-stale':
+            return 'terminal on main + ACTIVE = STALE (reconcilable) — NOT auto-cleared; a human clears it.';
+        case 'no-lock':
+            return 'no lock (already at rest).';
+        case 'error':
+            return 'reconciliation against main could not be determined (left untouched — the safe direction).';
+    }
+}
+/**
+ * The OPT-IN `gc --ledger --reap-stale-locks` SWEEP (prd
+ * `ledger-status-per-item-lock-refs` US #14): a human asserting "clear the dead
+ * TERMINAL locks now", so one command sweeps every orphaned terminal lock instead
+ * of N hand-run `release-lock`s. It is the WRITE twin of {@link reportItemLocks}
+ * (the default report-only surface): it enumerates the SAME held locks, classifies
+ * each read-only, and for EXACTLY the `cleared-stale` class (terminal-on-`main` +
+ * `active` = stranded) performs the SHARED leased delete via
+ * {@link reconcileItemLockAgainstMain} (the recovery's clear, re-checked fresh per
+ * item) — there is NO parallel clear mechanism.
+ *
+ * SCOPE FENCE (the trust model the default preserves):
+ *   - it clears ONLY `cleared-stale`. A `kept-stuck` (terminal + stuck — human
+ *     attention) and a `kept-in-flight` (active + non-terminal — a healthy build)
+ *     are NEVER reaped, even here. Because each clear goes through
+ *     {@link reconcileItemLockAgainstMain}, which RE-reads + RE-classifies before
+ *     deleting, a lock that turned stuck/in-flight between the report and the sweep
+ *     is still safe (reconcile returns `kept-*`, not a delete).
+ *   - the clear is a LEASED delete: a concurrent change to the ref makes it REJECT
+ *     (`lost`), reported — never a blind `--force`.
+ *
+ * The DEFAULT `gc --ledger` (no flag) never calls this: it stays report-only,
+ * fail-loud, delete-nothing. This is gated behind the explicit `--reap-stale-locks`
+ * flag (a human authorising the clear), exactly as `release-lock`'s trust model.
+ */
+export async function reapStaleItemLocks(cwd, arbiter = 'origin', env) {
+    const report = await reportItemLocks(cwd, arbiter, env);
+    const entries = [];
+    let reaped = 0;
+    let alreadyReaped = 0;
+    let kept = 0;
+    let lost = 0;
+    for (const { lock, ref, reconcile } of report.locks) {
+        const item = itemFromLockEntry(lock.entry);
+        if (reconcile === 'cleared-stale') {
+            // Re-check + clear through the recovery's SHARED leased delete. Reconcile
+            // re-reads the live ref, so a lock that turned stuck/in-flight since the
+            // report is left alone; a concurrent change to the ref makes the lease lose.
+            const rec = await reconcileItemLockAgainstMain({
+                item,
+                cwd,
+                arbiter,
+                env,
+            });
+            if (rec.outcome === 'cleared-stale') {
+                reaped++;
+                entries.push({ lock, ref, outcome: 'reaped', message: rec.message });
+            }
+            else if (rec.outcome === 'no-lock') {
+                // BENIGN: the ref is already gone — the desired end state. The LOSER of
+                // a concurrent double-reap (another reaper deleted the ref between our
+                // report and our re-read), or a `release-lock`/`requeue` that cleared
+                // the same stale lock in the meantime. NOT a lost lease (the lease was
+                // not REJECTED; there was simply nothing left to delete), so this does
+                // NOT count as needs-attention. Kept SEPARATE from `reaped` so the
+                // summary does not lie about who did the deleting.
+                alreadyReaped++;
+                entries.push({
+                    lock,
+                    ref,
+                    outcome: 'already-reaped',
+                    message: rec.message,
+                });
+            }
+            else if (rec.outcome === 'kept-stuck' ||
+                rec.outcome === 'kept-in-flight') {
+                // The lock changed between the report and the sweep — no longer stale.
+                kept++;
+                entries.push({ lock, ref, outcome: rec.outcome, message: rec.message });
+            }
+            else {
+                // A lost lease (the ref was REJECTED because it changed concurrently to
+                // a DIFFERENT value) or a per-item error — REPORTED, never forced.
+                // Counts as needing attention after the sweep.
+                lost++;
+                entries.push({ lock, ref, outcome: 'lost', message: rec.message });
+            }
+            continue;
+        }
+        // NOT a cleared-stale candidate: a stuck or in-flight lock the reaper must
+        // NEVER touch, even with the flag.
+        if (reconcile === 'kept-stuck' || reconcile === 'kept-in-flight') {
+            kept++;
+            entries.push({
+                lock,
+                ref,
+                outcome: reconcile,
+                message: reconcileNote(reconcile),
+            });
+        }
+        else {
+            // no-lock / error from the classifier — nothing to reap; surface verbatim.
+            lost++;
+            entries.push({
+                lock,
+                ref,
+                outcome: 'error',
+                message: reconcileNote(reconcile),
+            });
+        }
+    }
+    return { entries, reaped, alreadyReaped, kept, lost };
+}
+/**
+ * Does a {@link reapStaleItemLocks} sweep leave a lock that STILL needs human
+ * attention? TRUE iff some entry is `kept-stuck` (a stuck lock the reaper rightly
+ * left) or `lost`/`error` (a `cleared-stale` whose leased delete lost the race, or
+ * an unresolvable fault). A `reaped` (successfully cleared) or a `kept-in-flight`
+ * (healthy build) lock does NOT count — so a sweep that cleared every stale lock
+ * and left only healthy in-flight holds exits 0. This is the post-sweep analogue of
+ * {@link itemLockReportNeedsAttention}.
+ */
+export function reapReportNeedsAttention(report) {
+    // EXIT-CODE CONTRACT (recorded in this task's done record): the reaper exits 0
+    // when all stale locks are reaped and only healthy in-flight locks remain;
+    // exits 1 when a `kept-stuck` survives or a delete genuinely lost the race /
+    // errored. An `already-reaped` (the loser of a concurrent double-reap saw the
+    // ref already gone via `no-lock`) is BENIGN — the desired end state — and is
+    // NOT in this set.
+    return report.entries.some((e) => e.outcome === 'kept-stuck' ||
+        e.outcome === 'lost' ||
+        e.outcome === 'error');
+}
+/**
+ * Format the `gc --ledger --reap-stale-locks` sweep for the terminal: a header
+ * line with the reaped/kept counts, then one line per lock (what was reaped vs
+ * kept vs lost). An EMPTY sweep (no locks held) yields NO lines (silent, like the
+ * report). The wording keeps the no-blind-force contract explicit.
+ */
+export function formatReapReport(report) {
+    if (report.entries.length === 0) {
+        return [];
+    }
+    const lines = [
+        `Per-item lock sweep (--reap-stale-locks): reaped ${report.reaped} stale ` +
+            `terminal lock(s), kept ${report.kept} (stuck/in-flight, never reaped)` +
+            (report.alreadyReaped > 0
+                ? `, ${report.alreadyReaped} already reaped by another sweep (no-lock — benign, the desired end state)`
+                : '') +
+            (report.lost > 0
+                ? `, ${report.lost} could not be cleared (lease lost / error — reported, NEVER forced)`
+                : '') +
+            ':',
+    ];
+    for (const { lock, outcome, message } of report.entries) {
+        const tag = outcome === 'reaped'
+            ? '[reaped]  '
+            : outcome === 'already-reaped'
+                ? '[already] '
+                : outcome === 'lost'
+                    ? '[lost]    '
+                    : outcome === 'error'
+                        ? '[error]   '
+                        : '[kept]    ';
+        lines.push(`  ${tag} ${lock.entry}  [${lock.action}/${lock.state}]  ${message}`);
+    }
+    return lines;
+}
+/**
+ * Convert a type-encoded lock `<entry>` (`<type>-<slug>`) back into the namespaced
+ * item form (`<namespace>:<slug>`) that {@link lockEntryFor} /
+ * {@link resolveSidecarIdentity} accept — so the report's suggested `release-lock`
+ * command is copy-pasteable and the classifier can re-key off the SAME identity.
+ * Unknown prefixes fall back to the raw entry (still copyable). The inverse of
+ * {@link lockEntryFor} for the three known namespaces.
+ */
+export function itemFromLockEntry(entry) {
+    // The lock-entry prefixes: `spec` is the parent-spec type token (the legacy
+    // `prd` token is GONE after the hard cutover), so a `spec-<slug>` lock entry
+    // round-trips back to its namespaced `spec:<slug>` form (the inverse of
+    // `lockEntryFor('spec:<slug>')`).
+    for (const prefix of ['task', 'spec', 'observation']) {
+        const tag = `${prefix}-`;
+        if (entry.startsWith(tag)) {
+            return `${prefix}:${entry.slice(tag.length)}`;
+        }
+    }
+    return entry;
+}
+/** True iff `<arbiter>/main` shows the item TERMINAL — any of
+ * {@link terminalMainPaths} present in `<arbiter>/main`'s tree. */
+async function isTerminalOnMain(type, slug, arbiter, cwd, env) {
+    for (const path of terminalMainPaths(type, slug)) {
+        const exists = (await gitSoft(['cat-file', '-e', `${arbiter}/main:${path}`], cwd, env))
+            .status === 0;
+        if (exists) {
+            return true;
+        }
+    }
+    return false;
+}
+/** List the entries (`<type>-<slug>`) currently locked on the arbiter (the
+ * stuck-lock report / `status` read path). */
+export async function listItemLocks(cwd, arbiter = 'origin', env) {
+    await gitHard(['fetch', '--quiet', arbiter, `+${LOCK_REF_PREFIX}/*:${LOCK_REF_PREFIX}/*`], cwd, env);
+    const out = await gitSoft(['for-each-ref', '--format=%(refname)', `${LOCK_REF_PREFIX}/*`], cwd, env);
+    if (out.status !== 0) {
+        return [];
+    }
+    return out.stdout
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l.startsWith(`${LOCK_REF_PREFIX}/`))
+        .map((l) => l.slice(`${LOCK_REF_PREFIX}/`.length))
+        .sort();
+}
+/**
+ * Read the FULL lock entries currently held on the arbiter — the `status`/`scan`
+ * in-flight read path (prd `ledger-status-per-item-lock-refs` US #8; task
+ * `needs-attention-as-stuck-lock-state`). One fetch of the lock refs, then read
+ * each held entry's `lock.md` blob, returning the parsed {@link LockEntry} for
+ * every ref (so a caller can surface `active` (in-progress) and `stuck`
+ * (needs-attention) holds + their reasons WITHOUT N fetches). Sorted by `entry`.
+ * Best-effort: a fetch/read fault yields an EMPTY list, so the read-only
+ * `status`/`scan` views degrade to "no in-flight locks" rather than erroring
+ * (parity with {@link heldTaskSlugs}).
+ */
+export async function listItemLockEntries(cwd, arbiter = 'origin', env) {
+    try {
+        await gitHard([
+            'fetch',
+            '--quiet',
+            arbiter,
+            `+${LOCK_REF_PREFIX}/*:${LOCK_REF_PREFIX}/*`,
+        ], cwd, env);
+        const out = await gitSoft(['for-each-ref', '--format=%(refname)', `${LOCK_REF_PREFIX}/*`], cwd, env);
+        if (out.status !== 0) {
+            return [];
+        }
+        const refs = out.stdout
+            .split('\n')
+            .map((l) => l.trim())
+            .filter((l) => l.startsWith(`${LOCK_REF_PREFIX}/`))
+            .sort();
+        const entries = [];
+        for (const ref of refs) {
+            const show = await gitSoft(['show', `${ref}:lock.md`], cwd, env);
+            if (show.status !== 0) {
+                continue;
+            }
+            const lock = parseLockEntry(show.stdout);
+            if (lock) {
+                entries.push(lock);
+            }
+        }
+        return entries;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * List the TASK slugs currently lock-held on the arbiter — the held-slug set the
+ * `ready/` pool readers SUBTRACT (prd `ledger-status-per-item-lock-refs` US #15;
+ * task `claim-acquires-unified-lock-no-body-move`). Enumerates {@link listItemLocks}
+ * and keeps only the `task-<slug>` entries (a prd/observation lock does not gate
+ * the TASK pool), mapping each to its bare `<slug>`.
+ *
+ * LOAD-BEARING since the lock cut-over: the claim NO LONGER moves the body to
+ * `in-progress/` (it stays in the pool on `main`; the held lock IS the claim), so
+ * this held-slug set is the ONLY signal that keeps a claimed / in-flight item out
+ * of the eligible pool, NOT the redundant subtraction it was while the body-move
+ * still removed claimed items.
+ *
+ * GRACEFUL (fail-OPEN) by design — this is the SURFACE reader: a fetch fault
+ * yields an EMPTY set so the read-only `status`/`scan` views degrade to "no
+ * in-flight locks" rather than erroring. That is WRONG for SELECTION (an empty set
+ * on a read FAULT lets a continuously-held in-flight item leak back into the
+ * eligible pool → re-claimed → empty diff → spurious `stuck`). The SELECTION path
+ * must instead use {@link heldTaskSlugsStrict}, which THROWS on a read fault so
+ * the caller can fail CLOSED (refuse to enumerate an untrusted pool) rather than
+ * subtract nothing. This graceful variant delegates to the strict one and only
+ * swallows the fault.
+ */
+export async function heldTaskSlugs(cwd, arbiter = 'origin', env) {
+    try {
+        return await heldTaskSlugsStrict(cwd, arbiter, env);
+    }
+    catch {
+        return new Set();
+    }
+}
+/**
+ * STRICT (fail-CLOSED) twin of {@link heldTaskSlugs} for the SELECTION path: read
+ * the held TASK slugs from the arbiter and THROW on any read fault (offline / dead
+ * arbiter / unreadable lock refs) instead of degrading to an empty set. The
+ * held-lock set lives ONLY on the arbiter and is the LOAD-BEARING signal that
+ * keeps a claimed / in-flight item out of the eligible pool, so a SELECTION read
+ * that cannot reach the arbiter must NOT pretend "no locks held" — it must fail so
+ * the caller refuses to enumerate a pool it cannot trust (the
+ * `scan-cwd-selection-pool-read-local-skips-held-lock-subtraction-offline-must-fail`
+ * decision: offline selection FAILS, there is no `--local` fallback). The
+ * read-only surface keeps the graceful {@link heldTaskSlugs}.
+ */
+export async function heldTaskSlugsStrict(cwd, arbiter = 'origin', env) {
+    // `listItemLocks` fetches the lock refs with `gitHard` (throws on a failed
+    // fetch) and returns the held entries; we do NOT swallow that throw here.
+    const entries = await listItemLocks(cwd, arbiter, env);
+    const prefix = 'task-';
+    return new Set(entries
+        .filter((e) => e.startsWith(prefix))
+        .map((e) => e.slice(prefix.length)));
+}
+/**
+ * Parse a serialised lock entry body back into a {@link LockEntry} — the exact
+ * inverse of {@link serialiseLockEntry}. Reads the two-axis state from the
+ * frontmatter and, for a stuck entry, the FULL reason prose + any questions from
+ * the body (`## Reason` / `## Questions`). Tolerates a LEGACY entry whose reason
+ * lived in a one-line frontmatter `reason:` field (the pre-cutover shape) so a
+ * lock written by an older binary still reads.
+ */
+export function parseLockEntry(body) {
+    const normalized = body.replace(/\r\n/g, '\n');
+    const fm = /^---\n([\s\S]*?)\n---/.exec(normalized);
+    if (!fm) {
+        return undefined;
+    }
+    const fields = {};
+    for (const line of fm[1].split('\n')) {
+        const m = /^([a-zA-Z]+):\s*(.*)$/.exec(line);
+        if (m) {
+            fields[m[1]] = m[2];
+        }
+    }
+    if (!fields.entry || !fields.action || !fields.state) {
+        return undefined;
+    }
+    const bodyText = normalized.slice(fm[0].length);
+    const reason = extractBodyReason(bodyText) ?? fields.reason;
+    const questions = extractBodyQuestions(bodyText);
+    const entry = {
+        entry: fields.entry,
+        action: fields.action,
+        state: fields.state,
+        holder: fields.holder ?? '',
+        since: fields.since ?? '',
+    };
+    if (reason !== undefined && reason !== '') {
+        entry.reason = reason;
+    }
+    if (questions.length > 0) {
+        entry.questions = questions;
+    }
+    return entry;
+}
+/** Extract the `## Reason` block's prose (joined multi-line), or undefined. */
+function extractBodyReason(bodyText) {
+    const lines = bodyText.split('\n');
+    const start = lines.findIndex((l) => l.trim() === LOCK_REASON_HEADING);
+    if (start === -1) {
+        return undefined;
+    }
+    const collected = [];
+    for (let i = start + 1; i < lines.length; i++) {
+        if (/^##\s/.test(lines[i])) {
+            break;
+        }
+        collected.push(lines[i]);
+    }
+    // Trim leading/trailing blank lines but PRESERVE interior newlines (rich prose).
+    const text = collected.join('\n').replace(/^\n+/, '').replace(/\n+$/, '');
+    return text === '' ? undefined : text;
+}
+/** Extract the `## Questions` block's bulleted list, or [] when absent. */
+function extractBodyQuestions(bodyText) {
+    const lines = bodyText.split('\n');
+    const start = lines.findIndex((l) => l.trim() === LOCK_QUESTIONS_HEADING);
+    if (start === -1) {
+        return [];
+    }
+    const questions = [];
+    for (let i = start + 1; i < lines.length; i++) {
+        if (/^##\s/.test(lines[i])) {
+            break;
+        }
+        const m = /^-\s+(.*)$/.exec(lines[i].trim());
+        if (m) {
+            questions.push(m[1]);
+        }
+    }
+    return questions;
+}
+/**
+ * Advisory holder id: git user.name, else $USER, else a uuid fragment. Exported
+ * as {@link resolveLockHolder} so callers (e.g. claim's stale-lock self-heal) can
+ * resolve THE SAME holder string the lock would stamp, to compare against a held
+ * entry's `holder` without duplicating the resolution order.
+ */
+export async function resolveLockHolder(cwd, env) {
+    return resolveHolder(cwd, env);
+}
+/** Advisory holder id: git user.name, else $USER, else a uuid fragment. */
+async function resolveHolder(cwd, env) {
+    const name = await gitSoft(['config', 'user.name'], cwd, env);
+    if (name.status === 0 && name.stdout.trim() !== '') {
+        return name.stdout.trim();
+    }
+    const e = env ?? process.env;
+    return e.USER ?? e.USERNAME ?? randomUUID().slice(0, 8);
+}
+//# sourceMappingURL=item-lock.js.map