dorfl 0.1.2 → 0.2.0

package/dist/item-lock.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { runAsync } from './git.js';
-import { resolveSidecarIdentity } from './sidecar.js';
+import { resolveSidecarIdentity, sidecarPathFor, } from './sidecar.js';
+import { parseFrontmatter } from './frontmatter.js';
 import { workItemRel } from './work-layout.js';
 /**
  * The **unified item-lock module** (spec `ledger-status-per-item-lock-refs`, ADR
@@ -72,6 +73,21 @@ export function lockEntryFor(item) {
 export function itemLockRef(entry) {
     return `${LOCK_REF_PREFIX}/${entry}`;
 }
+/**
+ * The character class a LITERAL lock-entry name must match to be addressable
+ * through `release-lock --entry <literal>` (task
+ * `release-lock-entry-escape-hatch-and-literal-entry-reporting`): a NON-EMPTY run
+ * of `[A-Za-z0-9._-]` — the SAME shape the minting side produces (`<type>-<slug>`,
+ * and the pre-cutover `slice-<slug>` / `prd-<slug>` entries it must be able to
+ * name). It deliberately EXCLUDES `/` and whitespace so a literal can never escape
+ * the `refs/dorfl/lock/` namespace (a `/` would address a different ref path; a
+ * space would break the push refspec). This is the ONLY validation the `--entry`
+ * escape hatch performs before the git operation — the entry name is taken
+ * literally otherwise, bypassing the namespace mapping the item-form path uses.
+ */
+export function isValidLockEntryName(entry) {
+    return /^[A-Za-z0-9._-]+$/.test(entry);
+}
 function gitSoft(args, cwd, env) {
     return runAsync('git', args, cwd, { env });
 }
@@ -82,22 +98,16 @@ async function gitHard(args, cwd, env) {
     }
     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.
+ * advancing marker, so it round-trips and is previewable). Post-CONTRACT step
+ * (task `retire-stuck-lock-state`) the body carries ONLY the identity block —
+ * no `## Reason` / `## Questions` sections, because the retired `stuck` state
+ * was the only state that populated them. {@link parseLockEntry} is the inverse
+ * and tolerates a legacy body with those headings by ignoring them.
  */
 export function serialiseLockEntry(e) {
-    const lines = [
+    return [
         '---',
         `entry: ${e.entry}`,
         `action: ${e.action}`,
@@ -107,18 +117,8 @@ export function serialiseLockEntry(e) {
         '---',
         '',
         `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');
+        '',
+    ].join('\n');
 }
 /**
  * Build a PARENTLESS commit whose tree contains the single lock-entry blob, and
@@ -208,13 +208,22 @@ export async function acquireItemLock(opts) {
  * 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);
+    return releaseLockEntry(lockEntryFor(opts.item), opts.cwd, opts.arbiter ?? 'origin', opts.env);
+}
+/**
+ * The ONE entry-keyed release core shared by BOTH the item-form path
+ * ({@link releaseItemLock}, which derives the `<entry>` through the namespace
+ * mapping) AND the LITERAL escape hatch ({@link releaseLiteralLockEntry}, which
+ * takes the `<entry>` verbatim). It fetches the lock refs, checks the ref, and
+ * performs the SAME leased delete (`--force-with-lease=<ref>:<cur>`) with the SAME
+ * `not-held` / `released` / `error` semantics — there is deliberately NO second
+ * delete mechanism (task `release-lock-entry-escape-hatch-and-literal-entry-reporting`).
+ * The ONLY difference between the two callers is HOW the `<entry>` is obtained.
+ */
+async function releaseLockEntry(entry, cwd, arbiter, env) {
     const ref = itemLockRef(entry);
     try {
         await gitHard([
@@ -258,6 +267,39 @@ export async function releaseItemLock(opts) {
         };
     }
 }
+/**
+ * The `release-lock --entry <literal>` ESCAPE HATCH (task
+ * `release-lock-entry-escape-hatch-and-literal-entry-reporting`): release a lock
+ * whose `<entry>` name is NOT derivable from any CURRENT item-form — a lock minted
+ * BEFORE the slice→task / `prd-to-spec` vocabulary cutover (`slice-<slug>`,
+ * `prd-<slug>`), which the item-form path can no longer name because there is no
+ * item-form that produces those entries anymore.
+ *
+ * It takes the `<entry>` LITERALLY (bypassing {@link lockEntryFor} /
+ * {@link resolveSidecarIdentity}, the namespace mapping the item-form path uses)
+ * and targets `refs/dorfl/lock/<entry>` directly, then reuses the SAME entry-keyed
+ * leased-delete core {@link releaseItemLock} uses ({@link releaseLockEntry}) — the
+ * SAME lock-lease acquisition, push, absent-is-success no-op, exit codes, and
+ * mirror handling. There is NO second delete path.
+ *
+ * The trust model is UNCHANGED: a human still asserts the lock is dead by NAMING
+ * it; the only thing `--entry` drops is the assumption that the entry name is
+ * derivable from a current item-form. Rejects (`error`) an `<entry>` that fails
+ * {@link isValidLockEntryName} BEFORE any git operation, so a literal can never
+ * escape the `refs/dorfl/lock/` namespace.
+ */
+export async function releaseLiteralLockEntry(opts) {
+    const entry = opts.entry ?? '';
+    if (!isValidLockEntryName(entry)) {
+        return {
+            outcome: 'error',
+            entry,
+            ref: '',
+            message: `invalid --entry '${entry}': a lock-entry name must be a non-empty run of [A-Za-z0-9._-] (no slashes, no whitespace) so it cannot escape the ${LOCK_REF_PREFIX}/ namespace.`,
+        };
+    }
+    return releaseLockEntry(entry, opts.cwd, opts.arbiter ?? 'origin', opts.env);
+}
 /**
  * GUARDED release for a runner that KNOWS it acquired and HELD the lock (spec
  * `ledger-status-per-item-lock-refs` US #13): unlike {@link releaseItemLock} —
@@ -376,18 +418,6 @@ async function leasedDeleteLockRef(ref, expectedSha, cwd, arbiter, env) {
     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;
@@ -397,14 +427,6 @@ export async function markStuckItemLock(opts) {
     }
     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) {
@@ -412,32 +434,16 @@ export async function markStuckItemLock(opts) {
                 outcome: 'not-held',
                 entry,
                 ref,
-                message: `'${entry}' not locked`,
+                message: `'${entry}' not locked (mark-stuck is a no-op shim post retire-stuck-lock-state)`,
             };
         }
-        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(),
+        return {
+            outcome: 'transitioned',
+            entry,
+            ref,
+            message: `'${entry}' left active (mark-stuck is a no-op shim post retire-stuck-lock-state; a parked item is now a needsAnswers:true sidecar on main)`,
+            lock: held.lock,
         };
-        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 {
@@ -449,14 +455,19 @@ export async function markStuckItemLock(opts) {
     }
 }
 /**
- * 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.
+ * resume (crash-orphan recovery only, post `retire-stuck-lock-state`): with the
+ * `stuck` lock state retired, the ONLY thing to "resume" is the crash-window
+ * orphan the ordered bounce transition (surface-FIRST-release-SECOND) leaves
+ * when the surface lands on `<arbiter>/main` but the release never runs. If the
+ * held lock is `active` AND the item is SURFACED on `<arbiter>/main`
+ * (`needsAnswers:true` + sidecar) AND not terminal, `main` is authoritative:
+ * clear the ref via the SHARED leased delete (never `--force`) so the lock
+ * converges rather than dangling forever. Every OTHER combination is a no-op
+ * from this verb's perspective: an in-flight active hold that is NOT surfaced
+ * is a healthy build (`wrong-state` — nothing to resume); no lock is
+ * `not-held`. There is no `stuck → active` transition anymore: a parked item
+ * is a `needsAnswers:true` pool item on `main`, drained by answering the
+ * sidecar (via the apply rung), not by "resuming" a lock.
  */
 export async function resumeItemLock(opts) {
     const arbiter = opts.arbiter ?? 'origin';
@@ -477,23 +488,35 @@ export async function resumeItemLock(opts) {
                 message: `'${entry}' not locked`,
             };
         }
-        if (held.lock.state !== 'stuck') {
+        const { type, slug } = resolveSidecarIdentity(opts.item);
+        // Refresh `<arbiter>/main` so the surfaced-on-main probe reads the live
+        // snapshot rather than a stale local tracking ref.
+        await gitSoft(['fetch', '--quiet', arbiter], cwd, env);
+        const terminalOnMain = await isTerminalOnMain(type, slug, arbiter, cwd, env);
+        if (!terminalOnMain &&
+            (await isItemSurfacedOnMain(type, slug, opts.item, arbiter, cwd, env))) {
+            const cleared = await leasedDeleteLockRef(ref, held.sha, cwd, arbiter, env);
+            if (cleared === 'deleted') {
+                return {
+                    outcome: 'transitioned',
+                    entry,
+                    ref,
+                    message: `cleared the crash-window orphan lock for '${entry}' (item is SURFACED on ${arbiter}/main via needsAnswers + sidecar; the surface landed but the release never ran) — answer the question sidecar to drain it.`,
+                };
+            }
             return {
-                outcome: 'wrong-state',
+                outcome: 'lost',
                 entry,
                 ref,
-                message: `'${entry}' is ${held.lock.state}, not stuck; nothing to resume`,
+                message: `'${entry}' crash-orphan clear lost the CAS race (concurrent writer); back off and re-run.`,
             };
         }
-        const next = {
-            ...held.lock,
-            state: 'active',
-            holder: opts.holder ?? held.lock.holder,
+        return {
+            outcome: 'not-held',
+            entry,
+            ref,
+            message: `'${entry}' is active and not surfaced on ${arbiter}/main — nothing to resume (a healthy in-flight hold; a parked item is drained via its needsAnswers sidecar).`,
         };
-        // 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 {
@@ -505,15 +528,13 @@ export async function resumeItemLock(opts) {
     }
 }
 /**
- * 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`).
+ * requeue: give up on a held lock and return the item to the pool by REMOVING
+ * the entry. Post-CONTRACT step (task `retire-stuck-lock-state`) there is NO
+ * `stuck` state to guard against — the held lock is always `active`, so
+ * requeue works on any held entry (a leased delete; a concurrent change ⇒
+ * `lost`). The body never moved (it rests in the pool on `main`), so requeue
+ * is purely "release the lock"; the kept `work/<slug>` branch remains for
+ * recovery.
  */
 export async function requeueItemLock(opts) {
     const arbiter = opts.arbiter ?? 'origin';
@@ -534,14 +555,6 @@ export async function requeueItemLock(opts) {
                 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,
@@ -635,17 +648,23 @@ export function terminalMainPaths(type, slug) {
  * 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
+ * THE RECOVERY RULE (the `main` record is authoritative over an ORPHAN lock,
+ * broadened by task `reaper-reap-terminal-stuck-lock-orphans`; ADR
+ * `ledger-status-on-per-item-lock-refs` § Addendum 2026-07-10):
+ *   - `main` is TERMINAL + the held lock is `active` → STRANDED (the crash was
+ *     after the durable move, before the release) → CLEAR it (`cleared-stale`).
+ *   - `main` is TERMINAL + the held lock is `stuck`  → CRASH-ORPHAN (`done` +
+ *     `stuck` LEGITIMATELY co-existed during a rebase-conflict bounce, US #10,
+ *     but the item then reached its terminal folder by ANY path — human finish,
+ *     re-drive, manual fixup+merge — leaving the stuck lock as an orphan the
+ *     `main` record supersedes) → CLEAR it (`cleared-stuck-terminal`).
+ *   - `main` is NOT terminal + the held lock is `stuck` → the GENUINE
+ *     human-attention case (`kept-stuck`); NEVER auto-cleared here (a human
+ *     resolves via `resume`/`requeue`/`release-lock`). This is the invariant
+ *     the contract loosening MUST preserve.
+ *   - `main` is NOT terminal + the held lock is `active` → the NORMAL in-flight
  *     state (`kept-in-flight`); the lock is doing its job, leave it.
- *   - no lock at all                                   → `no-lock` (at rest).
+ *   - 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
@@ -714,7 +733,48 @@ export async function reconcileItemLockAgainstMain(opts) {
             };
         }
         if (!terminalOnMain) {
-            // A held lock + a non-terminal `main` is the NORMAL in-flight state.
+            // Post-`retire-stuck-lock-state`: the held lock is ALWAYS `active`. The
+            // split is now solely on whether the item is SURFACED on `<arbiter>/main`
+            // (`needsAnswers:true` + sidecar):
+            //   - surfaced   ⇒ the CRASH-WINDOW ORPHAN the ordered bounce transition
+            //     (surface-FIRST-release-SECOND) leaves when step 1 lands but step 2
+            //     never runs. `main` is authoritative — CLEAR via the SHARED leased
+            //     delete (`cleared-stale`).
+            //   - not surfaced ⇒ the NORMAL in-flight hold (`kept-in-flight`).
+            const surfaced = await isItemSurfacedOnMain(type, slug, opts.item, arbiter, cwd, env);
+            if (surfaced) {
+                const cleared = await leasedDeleteLockRef(ref, held.sha, cwd, arbiter, env);
+                if (cleared === 'deleted') {
+                    return {
+                        outcome: 'cleared-stale',
+                        entry,
+                        ref,
+                        terminalOnMain,
+                        message: `cleared the crash-window orphan lock for '${entry}' (item is SURFACED on ${arbiter}/main via needsAnswers:true + sidecar; the surface landed but the release never ran)`,
+                    };
+                }
+                // Leased delete rejected: fall through to the shared rejection
+                // arm below (same distinguish-then-report shape).
+                const remote = await gitSoft(['ls-remote', arbiter, ref], cwd, env);
+                const remoteEmpty = remote.status === 0 && remote.stdout.trim() === '';
+                if (remoteEmpty) {
+                    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: `crash-orphan clear for '${entry}' rejected (changed concurrently to a different value); a racer may have moved the ref. Re-run after re-checking.`,
+                };
+            }
             return {
                 outcome: 'kept-in-flight',
                 entry,
@@ -723,21 +783,8 @@ export async function reconcileItemLockAgainstMain(opts) {
                 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).
+        // Terminal on `main` + a held (active) lock = an ORPHAN over a
+        // durably-completed item. Clear via the SHARED leased delete.
         const cleared = await leasedDeleteLockRef(ref, held.sha, cwd, arbiter, env);
         if (cleared === 'deleted') {
             return {
@@ -842,6 +889,20 @@ export async function classifyItemLockAgainstMain(opts) {
             };
         }
         if (!terminalOnMain) {
+            // Post-`retire-stuck-lock-state`: the held lock is ALWAYS `active`. If the
+            // item is SURFACED on `<arbiter>/main` (`needsAnswers:true` + sidecar),
+            // the lock is a CRASH-WINDOW ORPHAN (reconcilable, NOT auto-cleared by
+            // the report); otherwise it is the normal in-flight hold.
+            const surfaced = await isItemSurfacedOnMain(type, slug, opts.item, arbiter, cwd, env);
+            if (surfaced) {
+                return {
+                    outcome: 'cleared-stale',
+                    entry,
+                    ref,
+                    terminalOnMain,
+                    message: `'${entry}' is a CRASH-WINDOW ORPHAN — SURFACED on ${arbiter}/main (needsAnswers:true + sidecar) but the release never ran; reconcilable, auto-reapable by 'gc --ledger --reap-stale-locks' (NOT auto-cleared by the report)`,
+                };
+            }
             return {
                 outcome: 'kept-in-flight',
                 entry,
@@ -850,24 +911,16 @@ export async function classifyItemLockAgainstMain(opts) {
                 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).
+        // Terminal on `main` + a held (active) lock = an ORPHAN over a
+        // durably-completed item. Unlike `reconcileItemLockAgainstMain` we do NOT
+        // clear it here — the report only names it as reconcilable; the reaper (or
+        // a human) asserts the clear (no auto-sweep from the report path).
         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)`,
+            message: `'${entry}' is terminal on ${arbiter}/main — reconcilable (stale); auto-reapable by 'gc --ledger --reap-stale-locks' (NOT auto-cleared by the report)`,
         };
     }
     catch (err) {
@@ -880,6 +933,12 @@ export async function classifyItemLockAgainstMain(opts) {
         };
     }
 }
+/** True iff a {@link ReconcileOutcome} names an ORPHAN class the
+ * `--reap-stale-locks` sweep can auto-clear via the shared leased delete.
+ * Post-`retire-stuck-lock-state` this is just `cleared-stale`. */
+export function isReapableTerminalOrphan(outcome) {
+    return outcome === 'cleared-stale';
+}
 /**
  * Build the `gc --ledger` stuck/orphaned-lock REPORT (spec
  * `ledger-status-per-item-lock-refs` US #12/#13/#14; ADR
@@ -940,7 +999,7 @@ export async function reportItemLocks(cwd, arbiter = 'origin', env) {
  * every held lock, in-flight ones informationally).
  */
 export function itemLockReportNeedsAttention(report) {
-    return report.locks.some((l) => l.reconcile === 'kept-stuck' || l.reconcile === 'cleared-stale');
+    return report.locks.some((l) => isReapableTerminalOrphan(l.reconcile));
 }
 export function formatItemLockReport(report) {
     if (report.locks.length === 0) {
@@ -952,14 +1011,21 @@ export function formatItemLockReport(report) {
             '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).`);
+        // The copy-pasteable clear hint. An entry that reverse-derives to a CURRENT
+        // item-form (`task-`/`spec-`/`observation-`) points at `release-lock <item>`.
+        // A PRE-CUTOVER entry (`slice-<slug>` / `prd-<slug>`) has NO current item-form,
+        // so it is UN-NAMEABLE that way — print ONLY the literal entry name and hint at
+        // the `release-lock --entry <literal>` escape hatch (task
+        // `release-lock-entry-escape-hatch-and-literal-entry-reporting`).
+        if (hasCurrentItemForm(lock.entry)) {
+            lines.push(`    resolve (if the lock is dead): \`dorfl release-lock ${itemFromLockEntry(lock.entry)}\` (never --force).`);
+        }
+        else {
+            lines.push(`    # no current item-form; clear with: dorfl release-lock --entry ${lock.entry}`);
+        }
     }
     return lines;
 }
@@ -968,10 +1034,8 @@ 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.';
+            return 'STALE / crash-window orphan (reconcilable) — auto-reapable by --reap-stale-locks (NOT auto-cleared by the report).';
         case 'no-lock':
             return 'no lock (already at rest).';
         case 'error':
@@ -989,13 +1053,19 @@ function reconcileNote(reconcile) {
  * {@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).
+ * SCOPE FENCE (the trust model the default preserves; broadened by task
+ * `reaper-reap-terminal-stuck-lock-orphans`; ADR
+ * `ledger-status-on-per-item-lock-refs` § Addendum 2026-07-10):
+ *   - it clears the TWO terminal-on-`main` ORPHAN classes ONLY: `cleared-stale`
+ *     (terminal + `active` = stranded between move and release) AND
+ *     `cleared-stuck-terminal` (terminal + `stuck` = crash-orphan the auto-reaper
+ *     used to leave forever). A `kept-stuck` (STUCK + NON-terminal — the
+ *     genuine human-attention case) 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 whose item was un-completed on
+ *     `main` 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`.
  *
@@ -1012,10 +1082,11 @@ export async function reapStaleItemLocks(cwd, arbiter = 'origin', env) {
     let lost = 0;
     for (const { lock, ref, reconcile } of report.locks) {
         const item = itemFromLockEntry(lock.entry);
-        if (reconcile === 'cleared-stale') {
+        if (isReapableTerminalOrphan(reconcile)) {
             // 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.
+            // re-reads the live ref, so a lock that turned in-flight since the
+            // report is left alone; a concurrent change to the ref makes the lease
+            // lose.
             const rec = await reconcileItemLockAgainstMain({
                 item,
                 cwd,
@@ -1027,13 +1098,6 @@ export async function reapStaleItemLocks(cwd, arbiter = 'origin', env) {
                 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,
@@ -1042,24 +1106,17 @@ export async function reapStaleItemLocks(cwd, arbiter = 'origin', env) {
                     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.
+            else if (rec.outcome === 'kept-in-flight') {
                 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') {
+        if (reconcile === 'kept-in-flight') {
             kept++;
             entries.push({
                 lock,
@@ -1091,15 +1148,11 @@ export async function reapStaleItemLocks(cwd, arbiter = 'origin', env) {
  * {@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');
+    // EXIT-CODE CONTRACT: the reaper exits 0 when all stale locks are reaped and
+    // only healthy in-flight locks remain; exits 1 when a delete genuinely lost
+    // the race / errored. An `already-reaped` is BENIGN. Post-`retire-stuck-
+    // lock-state` there is no `kept-stuck` outcome to trip this.
+    return report.entries.some((e) => e.outcome === 'lost' || e.outcome === 'error');
 }
 /**
  * Format the `gc --ledger --reap-stale-locks` sweep for the terminal: a header
@@ -1113,7 +1166,7 @@ export function formatReapReport(report) {
     }
     const lines = [
         `Per-item lock sweep (--reap-stale-locks): reaped ${report.reaped} stale ` +
-            `terminal lock(s), kept ${report.kept} (stuck/in-flight, never reaped)` +
+            `lock(s), kept ${report.kept} (in-flight, never reaped)` +
             (report.alreadyReaped > 0
                 ? `, ${report.alreadyReaped} already reaped by another sweep (no-lock — benign, the desired end state)`
                 : '') +
@@ -1124,14 +1177,14 @@ export function formatReapReport(report) {
     ];
     for (const { lock, outcome, message } of report.entries) {
         const tag = outcome === 'reaped'
-            ? '[reaped]  '
+            ? '[reaped]              '
             : outcome === 'already-reaped'
-                ? '[already] '
+                ? '[already]             '
                 : outcome === 'lost'
-                    ? '[lost]    '
+                    ? '[lost]                '
                     : outcome === 'error'
-                        ? '[error]   '
-                        : '[kept]    ';
+                        ? '[error]               '
+                        : '[kept]                ';
         lines.push(`  ${tag} ${lock.entry}  [${lock.action}/${lock.state}]  ${message}`);
     }
     return lines;
@@ -1146,10 +1199,10 @@ export function formatReapReport(report) {
  */
 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
+    // ''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']) {
+    for (const prefix of CURRENT_ITEM_FORM_PREFIXES) {
         const tag = `${prefix}-`;
         if (entry.startsWith(tag)) {
             return `${prefix}:${entry.slice(tag.length)}`;
@@ -1157,6 +1210,73 @@ export function itemFromLockEntry(entry) {
     }
     return entry;
 }
+/** The CURRENT lock-entry type prefixes an `<entry>` can reverse-derive to an
+ * item-form (`<type>:<slug>`). After the slice→task / `prd-to-spec` vocabulary
+ * cutover these are `task`/`spec`/`observation` ONLY — a pre-cutover `slice-`/
+ * `prd-` prefix is NOT here, so its entry has NO current item-form. */
+const CURRENT_ITEM_FORM_PREFIXES = ['task', 'spec', 'observation'];
+/**
+ * Does `<entry>` reverse-derive to a CURRENT item-form (`<type>:<slug>`), i.e.
+ * does it carry a known post-cutover type prefix (`task-`/`spec-`/`observation-`)?
+ * FALSE for a pre-cutover `slice-<slug>` / `prd-<slug>` entry (task
+ * `release-lock-entry-escape-hatch-and-literal-entry-reporting`): such an entry is
+ * UN-NAMEABLE through the item-form `release-lock <item>` path and must be cleared
+ * via the `release-lock --entry <literal>` escape hatch instead. This is the
+ * predicate the `gc --ledger` report keys off to decide whether to print the
+ * copy-pasteable item-form hint or the literal-`--entry` hint.
+ */
+export function hasCurrentItemForm(entry) {
+    return CURRENT_ITEM_FORM_PREFIXES.some((p) => entry.startsWith(`${p}-`));
+}
+/**
+ * True iff `<arbiter>/main` shows the item SURFACED as a needs-attention
+ * question (PR-2a classifier fold, task
+ * `bounce-atomic-cutover-retire-stuck-lock`, spec
+ * `surface-stuck-as-questions-and-retire-stuck-lock-state`): the item body
+ * carries `needsAnswers: true` in its frontmatter AND a matching sidecar
+ * (`work/questions/<type>-<slug>.md`) exists on `<arbiter>/main`. This is the
+ * on-`main`-authoritative signature of the ordered bounce transition
+ * (surface-to-main FIRST, release SECOND) that a crash BETWEEN steps 1 and 2
+ * leaves behind: the surface commit landed but the lock ref release never ran.
+ *
+ * Best-effort + degrades safely (`false` on any read fault or absent body):
+ * the recovery direction is to DECIDE the lock is NOT surfaced (fall through
+ * to `kept-in-flight`) when we cannot prove the surface — never a
+ * false-positive clear.
+ */
+async function isItemSurfacedOnMain(type, slug, item, arbiter, cwd, env) {
+    const sidecar = sidecarPathFor(item);
+    const sidecarExists = (await gitSoft(['cat-file', '-e', `${arbiter}/main:${sidecar}`], cwd, env))
+        .status === 0;
+    if (!sidecarExists) {
+        return false;
+    }
+    // Probe the two bounce body-folder candidates (D1 order) for a body carrying
+    // `needsAnswers: true`. Kept in sync with `resolveBounceItemBodyPathOnMain`
+    // in `needs-attention.ts`; duplicated here (a small closed list) to avoid a
+    // cyclic import between `item-lock.ts` and `needs-attention.ts`.
+    const candidates = type === 'task'
+        ? [
+            workItemRel('tasks-ready', `${slug}.md`),
+            workItemRel('tasks-backlog', `${slug}.md`),
+        ]
+        : type === 'spec'
+            ? [
+                workItemRel('specs-ready', `${slug}.md`),
+                workItemRel('specs-proposed', `${slug}.md`),
+            ]
+            : [workItemRel('observations', `${slug}.md`)];
+    for (const path of candidates) {
+        const show = await gitSoft(['show', `${arbiter}/main:${path}`], cwd, env);
+        if (show.status !== 0) {
+            continue;
+        }
+        if (parseFrontmatter(show.stdout).needsAnswers === true) {
+            return true;
+        }
+    }
+    return false;
+}
 /** 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) {
@@ -1233,7 +1353,7 @@ export async function listItemLockEntries(cwd, arbiter = 'origin', env) {
  * List the TASK slugs currently lock-held on the arbiter — the held-slug set the
  * `ready/` pool readers SUBTRACT (spec `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
+ * and keeps only the `task-<slug>` entries (a spec/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
@@ -1283,11 +1403,13 @@ export async function heldTaskSlugsStrict(cwd, arbiter = 'origin', env) {
 }
 /**
  * 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.
+ * inverse of {@link serialiseLockEntry}. Post-`retire-stuck-lock-state` a lock
+ * entry whose serialised state is not the single admitted `'active'` value
+ * (e.g. a legacy `state: stuck` blob written by an older binary before the
+ * one-shot migration ran) is COERCED to `'active'` on read — the state is
+ * degenerate, and a lingering stuck ref is left for the migration/recovery
+ * verbs to clear via `main`-authoritative reconciliation rather than surfaced
+ * as a second live state.
  */
 export function parseLockEntry(body) {
     const normalized = body.replace(/\r\n/g, '\n');
@@ -1305,60 +1427,13 @@ export function parseLockEntry(body) {
     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 = {
+    return {
         entry: fields.entry,
         action: fields.action,
-        state: fields.state,
+        state: 'active',
         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