dorfl 0.1.2 → 0.2.1

package/src/item-lock.ts

@@ -1,6 +1,11 @@
 import {randomUUID} from 'node:crypto';
 import {runAsync, type RunResult} from './git.js';
-import {resolveSidecarIdentity, type SidecarType} from './sidecar.js';
+import {
+	resolveSidecarIdentity,
+	sidecarPathFor,
+	type SidecarType,
+} from './sidecar.js';
+import {parseFrontmatter} from './frontmatter.js';
 import {workItemRel} from './work-layout.js';
 
 /**
@@ -77,28 +82,45 @@ export function itemLockRef(entry: string): string {
 	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: string): boolean {
+	return /^[A-Za-z0-9._-]+$/.test(entry);
+}
+
 /** WHAT holds the lock — the three mutually-exclusive actions over one item. */
 export type LockAction = 'implement' | 'task' | 'advance';
 
-/** Health of the hold: `active` (in-progress) or `stuck` (needs-attention). */
-export type LockState = 'active' | 'stuck';
+/**
+ * Health of the hold. Post-CONTRACT step (task `retire-stuck-lock-state`, spec
+ * `surface-stuck-as-questions-and-retire-stuck-lock-state`) this collapses to a
+ * single value: `active` = the in-flight hold. The formerly-second value
+ * `stuck` (needs-attention) is RETIRED — a bounce now SURFACES a question
+ * sidecar + `needsAnswers:true` on `<arbiter>/main` and RELEASES the lock, so a
+ * parked item is a `needsAnswers:true` pool item on `main`, NEVER a `stuck`
+ * lock. The `state` field is kept (single-value) so serialised entries continue
+ * to round-trip and downstream readers still see a stable shape. The `reason`
+ * and `questions` fields that USED to ride on a `stuck` entry are gone — that
+ * prose lives on the surfaced sidecar on `main`, not on the lock entry.
+ */
+export type LockState = 'active';
 
 /**
- * The two-axis lock entry. `action` and `state` are INDEPENDENT axes (so
- * "advanced-and-stuck" and "building-and-stuck" are both representable, which a
- * single action-field could not do). `reason` is present IFF `state === 'stuck'`.
- *
- * Since the lock entry is the SOLE stuck record (task
- * `cutover-needs-attention-becomes-lock-stuck-recovery-surface`, decision i+: the
- * `needs-attention/` folder is retired), `reason` is the FULL bounce prose (it may
- * span multiple lines — a red-gate excerpt, a rebase-conflict report, an agent's
- * ambiguity note), and `questions` carries any agent-surfaced questions for the
- * human. Both ride in the lock blob BODY (not a single frontmatter field) so they
- * round-trip richly, in a shape a future advance-surface rung (the
- * surface-stuck-locks-as-questions direction captured in
- * `work/notes/observations/needs-attention-may-have-no-human-visible-outcome-after-lock-cutover-surface-as-questions-2026-06-21.md`)
- * can render into a `work/questions/` sidecar. `questions` is present (non-empty) only
- * for a stuck entry that recorded them.
+ * The lock entry: `action` × `state` (the state axis is now degenerate — see
+ * {@link LockState}) plus the holder/since stamps. Post-CONTRACT step (task
+ * `retire-stuck-lock-state`) it carries NO `reason`/`questions` — the sole
+ * parked-item mechanism is the surfaced `needsAnswers:true` sidecar on
+ * `<arbiter>/main`.
  */
 export interface LockEntry {
 	entry: string;
@@ -106,8 +128,6 @@ export interface LockEntry {
 	state: LockState;
 	holder: string;
 	since: string;
-	reason?: string;
-	questions?: string[];
 }
 
 /** Outcome of an acquire attempt. `acquired` = we hold it; `lost` = someone else
@@ -131,26 +151,20 @@ export interface ReleaseResult {
 }
 
 /**
- * Outcome of an AMEND-style transition (mark-stuck / resume / requeue) — the
- * lock-entry STATE MACHINE's interior moves (spec `ledger-status-per-item-lock-refs`,
- * the C8 lock-entry state machine in the design trail). Each is a single CAS on the
- * held ref (no retry loop), so the verdict is definitive:
- *   - `transitioned` — we won the CAS; the entry now holds the target `(action, state)`.
- *   - `not-held`     — there is no entry to transition (the move's precondition is
- *                      "a held entry in the right state"; absent ⇒ illegal here).
- *   - `wrong-state`  — an entry exists but in the wrong `state` for this move
- *                      (e.g. resume on an `active` entry, mark-stuck on a `stuck` one).
- *                      An ILLEGAL transition, rejected, not coerced.
- *   - `lost`         — the leased CAS was rejected because a CONCURRENT writer changed
- *                      the ref between our read and our push (a genuine same-item race).
- *   - `error`        — environment/usage (missing item, missing reason for mark-stuck, …).
+ * Outcome of an AMEND-style transition (resume-crash-orphan / requeue) — the
+ * lock-entry STATE MACHINE's interior moves. Post-CONTRACT step (task
+ * `retire-stuck-lock-state`) the `mark-stuck` transition + the `wrong-state`
+ * verdict are retired with the `stuck` state itself.
+ *   - `transitioned` — we won the CAS; the entry is now at the target state
+ *                      (or removed, for requeue).
+ *   - `not-held`     — there is no entry to transition (the move's precondition
+ *                      is a held entry; absent ⇒ illegal here).
+ *   - `lost`         — the leased CAS was rejected because a CONCURRENT writer
+ *                      changed the ref between our read and our push (a genuine
+ *                      same-item race).
+ *   - `error`        — environment/usage (missing item, …).
  */
-export type TransitionOutcome =
-	| 'transitioned'
-	| 'not-held'
-	| 'wrong-state'
-	| 'lost'
-	| 'error';
+export type TransitionOutcome = 'transitioned' | 'not-held' | 'lost' | 'error';
 
 export interface TransitionResult {
 	outcome: TransitionOutcome;
@@ -183,23 +197,16 @@ async function gitHard(
 	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: LockEntry): string {
-	const lines = [
+	return [
 		'---',
 		`entry: ${e.entry}`,
 		`action: ${e.action}`,
@@ -209,18 +216,8 @@ export function serialiseLockEntry(e: LockEntry): string {
 		'---',
 		'',
 		`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');
 }
 
 /**
@@ -367,13 +364,33 @@ export interface ReleaseOptions {
 export async function releaseItemLock(
 	opts: ReleaseOptions,
 ): Promise<ReleaseResult> {
-	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: string,
+	cwd: string,
+	arbiter: string,
+	env: NodeJS.ProcessEnv | undefined,
+): Promise<ReleaseResult> {
 	const ref = itemLockRef(entry);
 	try {
 		await gitHard(
@@ -426,6 +443,55 @@ export async function releaseItemLock(
 	}
 }
 
+export interface ReleaseLiteralOptions {
+	/**
+	 * The LITERAL lock-entry name (`<type>-<slug>`, or a pre-cutover
+	 * `slice-<slug>` / `prd-<slug>`) to release VERBATIM — taken as-is, bypassing
+	 * the namespace mapping {@link lockEntryFor} applies. MUST pass
+	 * {@link isValidLockEntryName}.
+	 */
+	entry: string;
+	cwd: string;
+	arbiter?: string;
+	env?: NodeJS.ProcessEnv;
+}
+
+/**
+ * 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: ReleaseLiteralOptions,
+): Promise<ReleaseResult> {
+	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);
+}
+
 /** Outcome of a GUARDED release ({@link releaseHeldItemLock}): the caller HELD the
  * lock, so an absent ref is NOT benign — it is `vanished` (the ref was deleted
  * under us, an abort signal). */
@@ -603,35 +669,25 @@ async function leasedDeleteLockRef(
 	return 'deleted';
 }
 
+/**
+ * COMPATIBILITY SHIM (post `retire-stuck-lock-state`): the `stuck` lock STATE
+ * is retired — there is no `active → stuck` amend to perform any more, and no
+ * live path calls this. It is kept exported as a NO-OP that returns success
+ * (`transitioned` when a held entry is present, `not-held` otherwise) so
+ * downstream test suites that USED to seed a "stuck" scenario via this
+ * primitive continue to build. A shim'd `stuck` lock does NOT actually flip
+ * state; the lock stays `active` (which is the only admitted state) and any
+ * assertion that keys off `state === 'stuck'` is now vacuously false — the
+ * point of the migration.
+ */
 export interface MarkStuckOptions {
-	/** The NAMESPACED item identity (same forms as {@link AcquireOptions.item}). */
 	item: string;
-	/** The needs-attention prose. REQUIRED — a `stuck` entry always carries a reason. */
-	reason: string;
-	/**
-	 * Any agent-surfaced QUESTIONS for the human, recorded on the stuck entry's
-	 * body (the lock is the SOLE stuck record now). Optional; empty/absent ⇒ no
-	 * questions block. A future advance-surface rung renders these into a
-	 * `work/questions/` sidecar.
-	 */
+	reason?: string;
 	questions?: string[];
 	cwd: string;
 	arbiter?: string;
 	env?: NodeJS.ProcessEnv;
 }
-
-/**
- * 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: MarkStuckOptions,
 ): Promise<TransitionResult> {
@@ -643,14 +699,6 @@ export async function markStuckItemLock(
 	}
 	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) {
@@ -658,31 +706,16 @@ export async function markStuckItemLock(
 				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: LockEntry = {
-			...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 {
 			outcome: 'error',
@@ -704,14 +737,19 @@ export interface ResumeOptions {
 }
 
 /**
- * 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: ResumeOptions,
@@ -734,23 +772,49 @@ export async function resumeItemLock(
 				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: LockEntry = {
-			...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 {
 			outcome: 'error',
@@ -762,15 +826,13 @@ export async function resumeItemLock(
 }
 
 /**
- * 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: ReleaseOptions,
@@ -793,14 +855,6 @@ export async function requeueItemLock(
 				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',
@@ -896,11 +950,15 @@ export function terminalMainPaths(type: SidecarType, slug: string): string[] {
 
 /** The outcome of a cross-substrate reconciliation of one item's lock against
  * the authoritative `main` durable record (spec `ledger-status-per-item-lock-refs`
- * US #9/#10; ADR `ledger-status-on-per-item-lock-refs`). */
+ * US #9/#10; ADR `ledger-status-on-per-item-lock-refs`). Post-CONTRACT step
+ * (task `retire-stuck-lock-state`) the two `stuck`-flavoured outcomes
+ * (`cleared-stuck-terminal`, `kept-stuck`) are gone with the state itself; a
+ * parked item is now a `needsAnswers:true` pool item on `main`, so the
+ * `cleared-stale` verdict now ALSO covers the crash-window orphan (active +
+ * surfaced-on-main). */
 export type ReconcileOutcome =
-	| 'cleared-stale' // `main` is terminal + the lock was `active` (stranded) → cleared
-	| 'kept-stuck' // `main` is terminal + the lock is `stuck` → kept (co-exists, wins human attention)
-	| 'kept-in-flight' // `main` is NOT terminal + a lock is held → the normal in-flight state, kept
+	| 'cleared-stale' // `main` is terminal OR surfaced-on-main + the lock was `active` (stranded/orphan) → cleared
+	| 'kept-in-flight' // `main` is NOT terminal + a lock is held `active` → the normal in-flight state, kept
 	| 'no-lock' // there is no lock to reconcile (already at rest)
 	| 'error'; // environment/usage problem (best-effort; never throws)
 
@@ -927,17 +985,23 @@ export interface ReconcileResult {
  * 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
@@ -1019,7 +1083,61 @@ export async function reconcileItemLockAgainstMain(
 			};
 		}
 		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,
@@ -1028,21 +1146,8 @@ export async function reconcileItemLockAgainstMain(
 				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 {
@@ -1159,6 +1264,27 @@ export async function classifyItemLockAgainstMain(
 			};
 		}
 		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,
@@ -1167,24 +1293,16 @@ export async function classifyItemLockAgainstMain(
 				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) {
 		return {
@@ -1197,28 +1315,34 @@ export async function classifyItemLockAgainstMain(
 	}
 }
 
-/** One lingering lock in the `gc --ledger` stuck-lock REPORT: the held entry plus
- * the read-only cross-substrate {@link ReconcileOutcome} classification of it
- * against the authoritative `main` durable record (held/stuck vs stale-active over
- * a terminal item). Reported, NEVER cleared by the report itself. */
+/** One lingering lock in the `gc --ledger` orphaned-lock REPORT: the held entry
+ * plus the read-only cross-substrate {@link ReconcileOutcome} classification of
+ * it against the authoritative `main` durable record. Reported, NEVER cleared
+ * by the report itself. */
 export interface LockReportEntry {
-	/** The full held lock entry (action × state + holder/since/reason). */
+	/** The full held lock entry (action × state + holder/since). */
 	lock: LockEntry;
 	/** The lock ref (`refs/dorfl/lock/<entry>`). */
 	ref: string;
 	/**
 	 * The READ-ONLY {@link classifyItemLockAgainstMain} verdict:
-	 *   - `kept-in-flight` — a normal in-flight hold (not terminal on `main`).
-	 *   - `kept-stuck`     — terminal on `main` + `stuck` (the `done`+`stuck`
-	 *     co-existence; wins the human's attention, never cleared here).
-	 *   - `cleared-stale`  — terminal on `main` + `active` = a STALE lock the report
-	 *     names as reconcilable; a human clears it via `release-lock` (NOT
-	 *     auto-cleared by the report — no auto-sweep).
+	 *   - `kept-in-flight` — a normal in-flight hold (active, not terminal on `main`).
+	 *   - `cleared-stale`  — the lock is reconcilable: terminal on `main` (stranded)
+	 *     OR non-terminal + SURFACED (`needsAnswers:true` + sidecar) = crash-window
+	 *     orphan; a reaper (or `release-lock`) clears it (NOT auto-cleared by the
+	 *     report — no auto-sweep here).
 	 *   - `error`          — a per-item classification fault (kept verbatim).
 	 */
 	reconcile: ReconcileOutcome;
 }
 
+/** 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: ReconcileOutcome): boolean {
+	return outcome === 'cleared-stale';
+}
+
 /** The `gc --ledger` stuck/orphaned-lock REPORT (spec
  * `ledger-status-per-item-lock-refs` US #14): every lingering per-item lock on the
  * arbiter, each classified read-only against `main`. An EMPTY list = no locks held
@@ -1293,9 +1417,7 @@ export async function reportItemLocks(
  * every held lock, in-flight ones informationally).
  */
 export function itemLockReportNeedsAttention(report: ItemLockReport): boolean {
-	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: ItemLockReport): string[] {
@@ -1308,18 +1430,28 @@ export function formatItemLockReport(report: ItemLockReport): string[] {
 			'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;
 }
@@ -1329,10 +1461,8 @@ function reconcileNote(reconcile: ReconcileOutcome): string {
 	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':
@@ -1340,25 +1470,21 @@ function reconcileNote(reconcile: ReconcileOutcome): string {
 	}
 }
 
-/** Per-lock outcome of the human-invoked {@link reapStaleItemLocks} SWEEP:
- *   - `reaped`         — a `cleared-stale` lock (terminal-on-main + active) cleared
- *                        via the SHARED leased delete.
+/** Per-lock outcome of the human-invoked {@link reapStaleItemLocks} SWEEP.
+ * Post-`retire-stuck-lock-state` the `stuck`-flavoured verdicts
+ * (`reaped-stuck-terminal`, `kept-stuck`) are gone with the state itself.
+ *   - `reaped`         — a `cleared-stale` lock cleared via the SHARED leased delete.
  *   - `already-reaped` — BENIGN: the lock was already gone by the time the sweep
- *                        re-read the ref (`no-lock`) — another reaper / a
- *                        `release-lock` / a `requeue` got there first; the ref is
- *                        at the desired end state. NOT `lost` and does NOT count
- *                        as needs-attention (see the exit-code contract recorded
- *                        in this task's done record).
- *   - `kept-stuck`     — left untouched (terminal + stuck — human attention; US #10).
- *   - `kept-in-flight` — left untouched (active, non-terminal — a healthy build).
- *   - `lost`           — a `cleared-stale` candidate whose leased delete was REJECTED
+ *                        re-read the ref (`no-lock`).
+ *   - `kept-in-flight` — left untouched (active, non-terminal, not surfaced — a
+ *                        healthy build).
+ *   - `lost`           — a reapable-orphan candidate whose leased delete was REJECTED
  *                        (the ref changed concurrently to a DIFFERENT value);
  *                        REPORTED, never `--force`d.
  *   - `error`          — a per-item classification/clear fault (left untouched). */
 export type ReapOutcome =
 	| 'reaped'
 	| 'already-reaped'
-	| 'kept-stuck'
 	| 'kept-in-flight'
 	| 'lost'
 	| 'error';
@@ -1381,10 +1507,10 @@ export interface ReapEntry {
  * race); a `kept-in-flight` is the normal healthy state and does NOT. */
 export interface ReapReport {
 	entries: ReapEntry[];
+	/** Count of `cleared-stale` locks reaped (terminal-on-main + active, OR
+	 * non-terminal + surfaced = crash-window orphan). */
 	reaped: number;
-	/** BENIGN already-reaped count: the sweep found the ref already gone (`no-lock`)
-	 * — another reaper / release-lock / requeue cleared it first. The desired end
-	 * state; NOT `lost`, does NOT contribute to needs-attention / a non-zero exit. */
+	/** BENIGN already-reaped count: the sweep found the ref already gone (`no-lock`). */
 	alreadyReaped: number;
 	kept: number;
 	lost: number;
@@ -1401,13 +1527,19 @@ export interface ReapReport {
  * {@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`.
  *
@@ -1428,10 +1560,11 @@ export async function reapStaleItemLocks(
 	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,
@@ -1442,13 +1575,6 @@ export async function reapStaleItemLocks(
 				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,
@@ -1456,25 +1582,16 @@ export async function reapStaleItemLocks(
 					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.
+			} 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,
@@ -1506,17 +1623,12 @@ export async function reapStaleItemLocks(
  * {@link itemLockReportNeedsAttention}.
  */
 export function reapReportNeedsAttention(report: ReapReport): boolean {
-	// 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.
+	// 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 === 'kept-stuck' ||
-			e.outcome === 'lost' ||
-			e.outcome === 'error',
+		(e) => e.outcome === 'lost' || e.outcome === 'error',
 	);
 }
 
@@ -1532,7 +1644,7 @@ export function formatReapReport(report: ReapReport): string[] {
 	}
 	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)`
 				: '') +
@@ -1544,14 +1656,14 @@ export function formatReapReport(report: ReapReport): string[] {
 	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}`,
 		);
@@ -1569,10 +1681,10 @@ export function formatReapReport(report: ReapReport): string[] {
  */
 export function itemFromLockEntry(entry: string): string {
 	// 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'] as const) {
+	for (const prefix of CURRENT_ITEM_FORM_PREFIXES) {
 		const tag = `${prefix}-`;
 		if (entry.startsWith(tag)) {
 			return `${prefix}:${entry.slice(tag.length)}`;
@@ -1581,6 +1693,85 @@ export function itemFromLockEntry(entry: string): string {
 	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'] as const;
+
+/**
+ * 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: string): boolean {
+	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: SidecarType,
+	slug: string,
+	item: string,
+	arbiter: string,
+	cwd: string,
+	env: NodeJS.ProcessEnv | undefined,
+): Promise<boolean> {
+	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(
@@ -1690,7 +1881,7 @@ export async function listItemLockEntries(
  * 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
@@ -1751,11 +1942,13 @@ export async function heldTaskSlugsStrict(
 
 /**
  * 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: string): LockEntry | undefined {
 	const normalized = body.replace(/\r\n/g, '\n');
@@ -1773,62 +1966,13 @@ export function parseLockEntry(body: string): LockEntry | undefined {
 	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: LockEntry = {
+	return {
 		entry: fields.entry,
 		action: fields.action as LockAction,
-		state: fields.state as LockState,
+		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: string): string | undefined {
-	const lines = bodyText.split('\n');
-	const start = lines.findIndex((l) => l.trim() === LOCK_REASON_HEADING);
-	if (start === -1) {
-		return undefined;
-	}
-	const collected: string[] = [];
-	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: string): string[] {
-	const lines = bodyText.split('\n');
-	const start = lines.findIndex((l) => l.trim() === LOCK_QUESTIONS_HEADING);
-	if (start === -1) {
-		return [];
-	}
-	const questions: string[] = [];
-	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;
 }
 
 /**