dorfl 0.1.1 → 0.2.0

package/src/lifecycle-pools.ts

@@ -24,9 +24,13 @@ import type {LifecycleSelectedItem} from './select-priority.js';
  * **Three lifecycle sub-pools, gated by PURPOSE (ADR `ci-config-policy-and-gate-
  * family.md` \u00a74 \u2014 gates govern CREATE only; CONSUME is always-on):**
  *
- *   - **triage** \u2014 UNTRIAGED observations (no `triaged:` settled marker). A CREATE
- *     act (the bot mints a promote/keep/delete question), so gated by
- *     {@link LifecyclePoolGates.triage} (the future `observationTriage` gate).
+ *   - **triage** \u2014 UNTRIAGED observations (no `triaged:` settled marker) with NO
+ *     sidecar yet. A CREATE act (the bot mints the deterministic triage question),
+ *     so gated by {@link LifecyclePoolGates.triage} (the future `observationTriage`
+ *     gate). Like SURFACE, a PENDING sidecar is NOT enumerated (already surfaced +
+ *     awaiting the human, so re-enumerating only re-spawns the additive surface
+ *     agent for a no-outcome no-op); it re-enters only when ANSWERED (to apply) or
+ *     settled by a `triaged:` marker.
  *   - **surface** \u2014 `needsAnswers`-blocked tasks/prds with NO all-answered sidecar
  *     (no sidecar yet, or a still-pending one). A CREATE act (the bot mints the
  *     blocker question), so gated by {@link LifecyclePoolGates.surface} (the future
@@ -70,7 +74,7 @@ export interface LifecyclePoolGates {
 	surface?: boolean;
 	/**
 	 * Does the SURFACE candidate set widen to include STAGING (`tasks/backlog/` +
-	 * `prds/proposed/`), or stay POOL-ONLY? This field is CONSUMED BY THE
+	 * `specs/proposed/`), or stay POOL-ONLY? This field is CONSUMED BY THE
 	 * GATHER (`lifecycle-gather.ts`), NOT by {@link buildLifecyclePools} — the
 	 * builder is pure and only routes already-resolved candidates between surface
 	 * / apply by sidecar-answered-state. The gather decides WHICH items become
@@ -80,6 +84,39 @@ export interface LifecyclePoolGates {
 	 * default is `true`). Spec `staging-surface-and-apply-promote-safety` F2.
 	 * BUILD/claim eligibility is UNCHANGED in either mode — staging items stay
 	 * non-claimable, the trust model is untouched.
+	 *
+	 * CREATE-vs-CONSUME EDGE (accepted, spec
+	 * `staging-surface-and-apply-promote-safety` F2 follow-up): `surfaceStaging`
+	 * gates the CREATE half (surface-side ENUMERATION of staged candidates).
+	 * APPLY (the consume half) reads through the SAME enumeration, so flipping
+	 * `surfaceStaging` true→false AFTER a surface tick has minted+answered a
+	 * staged sidecar can STRAND that sidecar in staging until the flag is flipped
+	 * back on. The realistic flip direction is off→on (opt-in widening), and an
+	 * answered staged sidecar only exists if surfacing (opt-in) minted it, so the
+	 * strand window is narrow and accepted. Revisit only if the create-vs-consume
+	 * invariant must hold strictly (e.g. re-route `apply` to consume regardless of
+	 * the surface gate).
+	 *
+	 * ## Decisions (ratified by task
+	 * `f2-mirror-path-staging-test-and-ratify-decisions`, follow-up to slice
+	 * `f2-surface-staging-config-and-pool-extension` — gate-2 review nits)
+	 *
+	 * 1. **Split default is intentional.** `LifecyclePoolGates.surfaceStaging`
+	 *    defaults `false` at the library boundary; `Config.surfaceStaging` defaults
+	 *    `true` at the user-visible layer. The calm library default is load-bearing
+	 *    for any direct caller of `gatherLifecycle*` that does NOT thread CLI gates
+	 *    — they get pool-only behaviour by default and opt IN to staging.
+	 * 2. **Four new public methods on `LedgerReadStrategy` are intentional**
+	 *    (`resolveLocalTaskStaging`, `resolveLocalSpecStaging`,
+	 *    `resolveMirrorTaskStaging`, `resolveMirrorSpecStaging`), rather than
+	 *    overloading `resolveLocalState` / `resolveMirrorState` with a flag. Keeps
+	 *    the state vs. staging axes orthogonal at the interface.
+	 * 3. **The `surfaceStaging` gate is consumed by the GATHER, not by pure
+	 *    `buildLifecyclePools`,** even though the field lives on
+	 *    `LifecyclePoolGates`. Placement acknowledged above; ratified as intentional
+	 *    so the gate colocates with its sibling create-side gates.
+	 * 4. **`surfaceStaging` in `REPO_ALLOWED_KEYS` is intentional** so a repo's
+	 *    `.dorfl.json` can flip it via the normal resolution chain.
 	 */
 	surfaceStaging?: boolean;
 }
@@ -112,7 +149,7 @@ export interface NeedsAnswersCandidate {
  * to the always-on APPLY pool (a CONSUME act — the human's answer is never
  * stranded), while a NO/PENDING sidecar UNTRIAGED observation stays a TRIAGE
  * candidate (gated) as today. PURE: the caller resolves the active sidecar (via
- * {@link sidecarPathFor} — the SAME resolver the task/prd `needsAnswers`
+ * {@link sidecarPathFor} — the SAME resolver the task/spec `needsAnswers`
  * candidates use); this unit only routes.
  */
 export interface ObservationCandidate {
@@ -142,7 +179,7 @@ export interface LifecyclePoolsInput {
 	 */
 	observations: ObservationCandidate[];
 	/**
-	 * Every `needsAnswers:true` task/prd (the create-side blocked items), each
+	 * Every `needsAnswers:true` task/spec (the create-side blocked items), each
 	 * with its resolved active sidecar. This unit routes each to SURFACE or APPLY.
 	 */
 	needsAnswers: NeedsAnswersCandidate[];
@@ -172,7 +209,7 @@ export interface LifecyclePools {
  * Build the three lifecycle sub-pools from the raw candidates + the gates, PURE.
  * Each selected item carries the lifecycle `namespace` discriminator so the
  * driver's per-item dispatch can map it to the right TICK arg (observation \u2192
- * `obs:<slug>`; a blocked task/prd \u2192 `task:`/`prd:<slug>`, which the tick then
+ * `obs:<slug>`; a blocked task/spec \u2192 `task:`/`spec:<slug>`, which the tick then
  * classifies into surface/apply/no-op). This unit decides WHICH sub-pool each item
  * belongs to (and whether its gate lets it through); the TICK re-classifies and
  * runs the actual rung (the classifier + rung bodies are unchanged).
@@ -201,23 +238,44 @@ export function buildLifecyclePools(
 			// with the triage create-gate off (the create-vs-consume invariant, ADR
 			// `ci-config-policy-and-gate-family` §4). An answered sidecar wins even
 			// when the observation body also carries a `triaged:` marker: a human's
-			// answer must never be stranded (task `## Decisions`).
+			// answer must never be stranded (ADR
+			// `answered-observation-sidecar-dominates-triaged-marker.md`).
 			apply.push({
 				repoPath: input.repoPath,
 				slug: obs.slug,
 				namespace: 'observation',
 			});
-		} else if (obs.triaged === undefined && triageOn) {
-			// CREATE (mint the promote/keep/delete question) — gated by
-			// `observationTriage`. An untriaged observation with NO sidecar or a
-			// PENDING sidecar is a triage candidate as today.
+		} else if (
+			obs.triaged === undefined &&
+			obs.sidecar === undefined &&
+			triageOn
+		) {
+			// CREATE (mint the deterministic triage question) — gated by
+			// `observationTriage`. ONLY an untriaged observation with NO sidecar yet is
+			// a triage candidate: it has never been surfaced. A PENDING sidecar (surfaced
+			// already, awaiting the human's answer) is DELIBERATELY DROPPED here — mirror
+			// of the SURFACE pool. The triage question is DETERMINISTIC (engine-built) +
+			// already present, so re-enumerating a pending observation every tick would
+			// only re-run a leg + re-spawn the additive surface agent for a NO-OUTCOME
+			// no-op (the persist appends no duplicate). It re-enters only when it is
+			// ANSWERED (→ apply, above) or a `triaged:` marker settles it. This is the
+			// enumerate-smartness fix: do NOT re-evaluate items that produce no outcome.
 			triage.push({
 				repoPath: input.repoPath,
 				slug: obs.slug,
 				namespace: 'observation',
 			});
+		} else if (obs.triaged !== undefined) {
+			// EXPLICIT DROP: SETTLED (`triaged:` non-empty) with no answered sidecar
+			// — deliberately NOT enumerated. A pending sidecar on a settled
+			// observation would only no-op if re-enumerated, and a settled body is
+			// already resolved on the create side (ADR
+			// `answered-observation-sidecar-dominates-triaged-marker.md`). Codified
+			// as an explicit branch so a future reader does not resurface this cell.
+			continue;
 		}
-		// else: SETTLED (triaged:) with no answered sidecar — NOT enumerated.
+		// else: UNTRIAGED with no answered sidecar + triage gate OFF — implicit
+		// drop (the gate deliberately silences the pool).
 	}
 
 	// --- surface / apply: split `needsAnswers` items by sidecar answered-state ---

package/src/merge-question-surfacer.ts

@@ -16,7 +16,7 @@ import {
 import {workItemRel, type WorkFolderKey} from './work-layout.js';
 
 /**
- * The **MERGE-QUESTION SURFACER** (prd `land-time-reverify-and-parallel-merge-ceiling`,
+ * The **MERGE-QUESTION SURFACER** (spec `land-time-reverify-and-parallel-merge-ceiling`,
  * task `merge-question-surfacer`, US #14) — the SECOND, STATE-sourced surfacer
  * in the advance loop. It is a clean SIBLING to the existing
  * `surface-questions` JUDGEMENT surfacer (`surface-gate.ts` +
@@ -41,7 +41,7 @@ import {workItemRel, type WorkFolderKey} from './work-layout.js';
  * layered on top when a GitHub host is configured; the surfacer functions
  * identically without it.
  *
- * OUT OF SCOPE for this task (covered by sibling tasks of the same prd):
+ * OUT OF SCOPE for this task (covered by sibling tasks of the same spec):
  *
  *   - The APPLY rung dispatch that lands an answered `kind: merge` through the
  *     land primitive (rebase → re-verify → advance). Task
@@ -139,10 +139,19 @@ export interface MergeQuestionSurfaced {
 	prUrl?: string;
 }
 
-/** One branch the surfacer considered but did not surface (with the reason). */
+/**
+ * One branch the surfacer considered but did not surface (with the reason).
+ *
+ * PROVISIONAL vocabulary. The `reason` union is scoped to this surfacer — no
+ * sibling surfacer exists yet, so it is deliberately NOT lifted to a shared
+ * skip-reason type. When a second STATE-sourced surfacer lands (e.g. a
+ * stuck-lock surfacer), promote this to a shared skip-reason vocabulary via a
+ * dedicated decision; until then it may change without notice.
+ */
 export interface MergeQuestionSkipped {
 	ref: string;
 	slug: string;
+	/** PROVISIONAL vocabulary — see {@link MergeQuestionSkipped}. */
 	reason: 'no-item-body' | 'already-pending-merge-question' | 'persist-nothing';
 }
 
@@ -164,9 +173,19 @@ export class MergeQuestionSurfacerError extends Error {
 	}
 }
 
-/** The lifecycle folders a task body may rest in (the FOLDERS the persist
- * needs to find the item file to set `needsAnswers:true` on). Matches
- * `advance.ts`'s `findItemPath` task-folder set. */
+/**
+ * The lifecycle folders {@link findTaskItemPath} scans for a task body to flip
+ * `needsAnswers:true` on. This set DELIBERATELY DIVERGES from `advance.ts`'s
+ * `FOLDERS_FOR_TYPE.task` (`['tasks-backlog','tasks-ready','in-progress','done']`):
+ *
+ *   - OMITS `in-progress` (and `needs-attention`): an unmerged `work/<slug>`
+ *     branch whose body is mid-build should NOT trigger a merge-question — the
+ *     build is still active, and surfacing a land-decision now would race the
+ *     builder. Such tasks fall through to the `no-item-body` skip.
+ *   - ADDS `cancelled`: a cancelled task with a lingering unmerged `work/*`
+ *     branch SHOULD surface a merge-question so the operator explicitly decides
+ *     whether to merge the branch or drop it.
+ */
 const TASK_FOLDERS: readonly WorkFolderKey[] = [
 	'tasks-ready',
 	'tasks-backlog',
@@ -185,7 +204,7 @@ const TASK_FOLDERS: readonly WorkFolderKey[] = [
  * Idempotency: a branch whose sidecar ALREADY carries a PENDING `kind: merge`
  * entry is SKIPPED (with `already-pending-merge-question`). A branch with no
  * item body on `main` is SKIPPED (with `no-item-body`) — the cross-cutting
- * branch-keyed sidecar identity (PRD sidecar Q5-i) is OOS for this task; an
+ * branch-keyed sidecar identity (SPEC sidecar Q5-i) is OOS for this task; an
  * unmerged-branch-with-no-body lands on the same skip path until that
  * generalisation arrives.
  */
@@ -248,7 +267,7 @@ export function surfaceMergeQuestions(
 
 		const itemPath = findTaskItemPath(cwd, branch.slug);
 		if (itemPath === undefined) {
-			// The `branch:`/`ref:`-keyed sidecar identity (PRD sidecar Q5-i, the
+			// The `branch:`/`ref:`-keyed sidecar identity (SPEC sidecar Q5-i, the
 			// cross-cutting open question SHARED with the stuck-lock surfacer) is
 			// OUT OF SCOPE for this task — without a body to flip `needsAnswers`
 			// on, persist would tear the invariant. Skip with the reason so the
@@ -440,6 +459,11 @@ export function listUnmergedWorkBranchesViaGit(
  * results by their `headRefName` so the surfacer can enrich the matching
  * branch's question. A non-zero / missing `gh` is treated as "no host
  * metadata available" — the floor still surfaces every unmerged branch.
+ *
+ * Best-effort enrichment. The git-reachability FLOOR is authoritative; the
+ * `--state open`, `--base <base>`, and `--limit 200` arguments are DELIBERATE
+ * ceilings — a PR targeting a non-`main` base (e.g. a stacked PR) or the case
+ * of >200 open PRs degrades to floor-only output, never corrupts it.
  */
 export function listOpenPullRequestsViaGh(
 	input: ListPullRequestsInput,

package/src/migrate-stuck-locks.ts

@@ -0,0 +1,451 @@
+/**
+ * ONE-SHOT migration of pre-existing `stuck` per-item lock refs into the
+ * post-`retire-stuck-lock-state` resting shape (surface-on-`main` +
+ * `needsAnswers:true` + release the lock).
+ *
+ * Context (spec `surface-stuck-as-questions-and-retire-stuck-lock-state`,
+ * resolved decision #3, user story 5; task
+ * `migrate-existing-stuck-locks-one-shot`):
+ *   - Before the retirement, a bounced item was recorded as a `state: stuck`
+ *     lock ref (`refs/dorfl/lock/<entry>`) with the bounce reason (+ any
+ *     agent-surfaced questions) on the ref's blob body.
+ *   - After the retirement (task `retire-stuck-lock-state`), `LockState`
+ *     admits only `active`. {@link parseLockEntry} silently COERCES a legacy
+ *     `state: stuck` blob to `active` on read, and the `stuck`-only body
+ *     sections (`## Reason` / `## Questions`) are no longer emitted or
+ *     parsed. So a legacy stuck ref is now invisible to the runner (it looks
+ *     like a healthy in-flight `active` hold) and its reason/questions would
+ *     rot forever if the state were not migrated at rollout.
+ *
+ * This module runs the migration ONCE per arbiter at rollout: for every held
+ * lock ref whose RAW blob body still carries `state: stuck` in its
+ * frontmatter, it extracts the reason (+ questions) directly from the legacy
+ * body (bypassing the coercing {@link parseLockEntry}) and drives the SAME
+ * ordered surface-first-release-second transition the new bounce uses
+ * ({@link surfaceStuckToNeedsAttention}) — writing the `stuck`-kind
+ * `work/questions/<entry>.md` sidecar + flipping `needsAnswers:true` on the
+ * item body on `<arbiter>/main`, then releasing the ref. After the migration
+ * no `stuck` lock ref remains and every previously-stuck item rests as a
+ * `needsAnswers:true` pool item with a sidecar (the same resting shape a
+ * fresh bounce produces).
+ *
+ * IDEMPOTENT by construction: the legacy shape is identified from the raw
+ * blob's `state: stuck` frontmatter line, which the new lock module NEVER
+ * writes; a re-run therefore finds no legacy stuck ref → the report has zero
+ * `migrated` entries and no arbiter mutation occurs. Bare-arbiter safe (a ref
+ * is a ref): every operation goes through the same lock-ref plumbing the
+ * live path uses, so it works on a `--bare file://` arbiter identically to a
+ * real remote.
+ *
+ * SCOPE FENCE: this migrates ONLY lock entries whose name reverse-derives to
+ * a CURRENT item-form (`task-*` / `spec-*` / `observation-*` via
+ * {@link hasCurrentItemForm}); a pre-cutover `slice-*` / `prd-*` legacy stuck
+ * ref has no on-`main` body to flip and is out of scope for the surface
+ * transition — such entries are reported as `skipped-no-item-form` and left
+ * for the existing `release-lock --entry <literal>` escape hatch to clear (a
+ * human still asserts the clear on those; the migration never `--force`s or
+ * deletes them). See the CLI verb `dorfl migrate-stuck-locks` for the
+ * user-facing surface + its help text.
+ */
+
+import {runAsync, type RunResult} from './git.js';
+import {
+	itemFromLockEntry,
+	itemLockRef,
+	hasCurrentItemForm,
+	listItemLocks,
+} from './item-lock.js';
+import {
+	surfaceStuckToNeedsAttention,
+	type SurfaceStuckToNeedsAttentionResult,
+} from './needs-attention.js';
+import {resolveSidecarIdentity} from './sidecar.js';
+
+/** Per-lock outcome of the migration sweep. */
+export type MigrateStuckLockOutcome =
+	| 'migrated' // legacy stuck ref → surfaced on main + released
+	| 'migrated-body-absent' // legacy stuck ref → lock released, but no `main` body existed to flip (bounce D1 probe found nothing); still a no-op-safe drain of the stale lock
+	| 'not-stuck' // ref present but its blob is not the legacy `state: stuck` shape (healthy active hold, or already migrated)
+	| 'skipped-no-item-form' // legacy stuck ref but its `<entry>` does not reverse-derive to a current item-form (pre-cutover `slice-*` / `prd-*`); clear via `release-lock --entry <literal>`
+	| 'lost' // the surface CAS or the release lost the race to a concurrent writer; reported, never `--force`d
+	| 'error'; // read/plumbing fault on this ref; reported, ref left untouched
+
+/** One lock's disposition in the {@link MigrateStuckLocksReport}. */
+export interface MigrateStuckLockEntry {
+	/** The lock-entry name (`<type>-<slug>` or a pre-cutover `slice-*` / `prd-*`). */
+	entry: string;
+	/** The lock ref (`refs/dorfl/lock/<entry>`). */
+	ref: string;
+	/**
+	 * The namespaced item form the entry reverse-derives to (`task:<slug>` /
+	 * `spec:<slug>` / `observation:<slug>`), or the raw entry when it does not
+	 * carry a current item-form prefix.
+	 */
+	item: string;
+	outcome: MigrateStuckLockOutcome;
+	/** Human-readable note (why it was left, or the surface + release result). */
+	message: string;
+}
+
+/** Result of {@link migrateStuckLocks}. A one-shot sweep report. */
+export interface MigrateStuckLocksReport {
+	entries: MigrateStuckLockEntry[];
+	/** Count of legacy stuck refs surfaced on main + released. */
+	migrated: number;
+	/** Count of legacy stuck refs whose lock was released but had no on-`main` body
+	 * to flip (body-absent D1 probe). Still a successful drain. */
+	migratedBodyAbsent: number;
+	/** Count of refs that were not the legacy stuck shape (healthy active holds
+	 * or already-migrated). No mutation. */
+	notStuck: number;
+	/** Count of legacy stuck refs skipped because their entry has no current
+	 * item-form (pre-cutover `slice-*` / `prd-*`). */
+	skippedNoItemForm: number;
+	/** Count of refs whose surface/release lost the CAS race. */
+	lost: number;
+	/** Count of refs where a read/plumbing fault prevented migration. */
+	errors: number;
+}
+
+export interface MigrateStuckLocksOptions {
+	cwd: string;
+	arbiter?: string;
+	env?: NodeJS.ProcessEnv;
+	/** Optional progress note sink (parity with `surfaceStuckToNeedsAttention`). */
+	note?: (message: string) => void;
+}
+
+/**
+ * Run the one-shot migration against the arbiter. Enumerates every held
+ * per-item lock ref, and for each whose RAW blob body carries `state: stuck`
+ * (the legacy shape the retired `stuck` state produced) drives the shared
+ * surface-first-release-second transition (reason + questions extracted from
+ * the legacy body). Idempotent: a re-run finds no legacy stuck refs and is a
+ * clean no-op.
+ */
+export async function migrateStuckLocks(
+	options: MigrateStuckLocksOptions,
+): Promise<MigrateStuckLocksReport> {
+	const cwd = options.cwd;
+	const arbiter = options.arbiter ?? 'origin';
+	const env = options.env;
+	const note = options.note ?? (() => {});
+
+	const entries: MigrateStuckLockEntry[] = [];
+	let migrated = 0;
+	let migratedBodyAbsent = 0;
+	let notStuck = 0;
+	let skippedNoItemForm = 0;
+	let lost = 0;
+	let errors = 0;
+
+	// Enumerate every held lock entry on the arbiter. `listItemLocks` fetches the
+	// lock refs first (hard-fails on a fetch fault) so the enumeration reads a
+	// fresh arbiter snapshot; if the fetch throws we surface it as a single
+	// terminal error rather than degrading to `[]` (which would silently claim
+	// "nothing to migrate").
+	let heldEntries: string[];
+	try {
+		heldEntries = await listItemLocks(cwd, arbiter, env);
+	} catch (err) {
+		return {
+			entries: [
+				{
+					entry: '',
+					ref: '',
+					item: '',
+					outcome: 'error',
+					message: `failed to enumerate lock refs on ${arbiter}: ${
+						err instanceof Error ? err.message : String(err)
+					}`,
+				},
+			],
+			migrated: 0,
+			migratedBodyAbsent: 0,
+			notStuck: 0,
+			skippedNoItemForm: 0,
+			lost: 0,
+			errors: 1,
+		};
+	}
+
+	for (const entry of heldEntries) {
+		const ref = itemLockRef(entry);
+		const item = itemFromLockEntry(entry);
+		let body: string;
+		try {
+			body = await readLockBlob(ref, cwd, env);
+		} catch (err) {
+			errors++;
+			entries.push({
+				entry,
+				ref,
+				item,
+				outcome: 'error',
+				message: `read failed: ${err instanceof Error ? err.message : String(err)}`,
+			});
+			continue;
+		}
+		if (!isLegacyStuckBlob(body)) {
+			notStuck++;
+			entries.push({
+				entry,
+				ref,
+				item,
+				outcome: 'not-stuck',
+				message: `${entry} is not a legacy stuck lock (state != stuck on the ref blob) — left untouched.`,
+			});
+			continue;
+		}
+		if (!hasCurrentItemForm(entry)) {
+			// A pre-cutover `slice-*` / `prd-*` stuck ref has no current
+			// item-form and therefore no on-`main` body path to flip. The
+			// existing `release-lock --entry <literal>` escape hatch is the
+			// supported clear here; the migration NEVER `--force`s such a ref.
+			skippedNoItemForm++;
+			entries.push({
+				entry,
+				ref,
+				item,
+				outcome: 'skipped-no-item-form',
+				message:
+					`'${entry}' is a legacy stuck ref with no current item-form ` +
+					`(pre-cutover slice-*/prd-*); clear via ` +
+					`\`dorfl release-lock --entry ${entry}\` (no auto-force).`,
+			});
+			continue;
+		}
+		const {slug} = resolveSidecarIdentity(item);
+		const reason = extractLegacyReason(body) ?? '(no reason recorded)';
+		const questions = extractLegacyQuestions(body).map((q) => ({question: q}));
+		let result: SurfaceStuckToNeedsAttentionResult;
+		try {
+			result = await surfaceStuckToNeedsAttention({
+				cwd,
+				slug,
+				item,
+				reason,
+				questions,
+				arbiter,
+				env,
+				note,
+			});
+		} catch (err) {
+			errors++;
+			entries.push({
+				entry,
+				ref,
+				item,
+				outcome: 'error',
+				message: `surface transition threw: ${
+					err instanceof Error ? err.message : String(err)
+				}`,
+			});
+			continue;
+		}
+		if (result.surfaced && result.released) {
+			migrated++;
+			entries.push({
+				entry,
+				ref,
+				item,
+				outcome: 'migrated',
+				message:
+					`migrated '${entry}' → surfaced on ${arbiter}/main ` +
+					'(needsAnswers:true + sidecar) and released the lock.',
+			});
+			continue;
+		}
+		if (!result.surfaced && result.released && result.bodyAbsent === true) {
+			// D1 body-absent probe: no `main` body existed to flip. The bounce
+			// primitive STILL released the lock so the legacy stuck ref no longer
+			// dangles; there is just nothing to surface. Counted as a drained
+			// migration (the goal — no stuck ref remains).
+			migratedBodyAbsent++;
+			entries.push({
+				entry,
+				ref,
+				item,
+				outcome: 'migrated-body-absent',
+				message:
+					`released legacy stuck lock '${entry}': no body for '${item}' on ` +
+					`${arbiter}/main (D1 probe) — sidecar surface skipped, but the ` +
+					'stale lock was drained (the migration goal).',
+			});
+			continue;
+		}
+		// The surface CAS or the release did not converge (contention exhausted,
+		// or the leased release lost the race). Reported, never forced.
+		lost++;
+		entries.push({
+			entry,
+			ref,
+			item,
+			outcome: 'lost',
+			message:
+				result.reasonNotSurfaced ??
+				`surface/release for '${entry}' did not converge (surfaced=${result.surfaced}, released=${result.released}); re-run.`,
+		});
+	}
+
+	return {
+		entries,
+		migrated,
+		migratedBodyAbsent,
+		notStuck,
+		skippedNoItemForm,
+		lost,
+		errors,
+	};
+}
+
+/**
+ * True iff the migration report leaves a state a human should look at: a
+ * `lost` (CAS race) or an `error` (read/plumbing fault). A `not-stuck` /
+ * `skipped-no-item-form` outcome is INFORMATIONAL (the former is the normal
+ * healthy-hold state; the latter is deferred to `release-lock --entry`) and
+ * does NOT count. A pure "0 migrated, 0 lost, 0 error" report is exit-0.
+ */
+export function migrateStuckLocksNeedsAttention(
+	report: MigrateStuckLocksReport,
+): boolean {
+	return report.lost > 0 || report.errors > 0;
+}
+
+/** Format the sweep for the terminal. An empty enumeration (no lock refs at
+ * all) yields no lines (silent, like the gc lock report). */
+export function formatMigrateStuckLocksReport(
+	report: MigrateStuckLocksReport,
+): string[] {
+	if (report.entries.length === 0) {
+		return [
+			'Migrate stuck locks: no per-item lock refs held on the arbiter — nothing to migrate.',
+		];
+	}
+	const lines = [
+		`Migrate stuck locks: migrated ${report.migrated}` +
+			(report.migratedBodyAbsent > 0
+				? ` (+${report.migratedBodyAbsent} body-absent — lock drained, no on-main body to surface)`
+				: '') +
+			`, left ${report.notStuck} healthy active hold(s) untouched` +
+			(report.skippedNoItemForm > 0
+				? `, skipped ${report.skippedNoItemForm} pre-cutover entry (clear via release-lock --entry)`
+				: '') +
+			(report.lost > 0
+				? `, ${report.lost} could not converge (lease lost — re-run)`
+				: '') +
+			(report.errors > 0
+				? `, ${report.errors} error(s) (left untouched)`
+				: '') +
+			':',
+	];
+	for (const e of report.entries) {
+		const tag =
+			e.outcome === 'migrated'
+				? '[migrated]           '
+				: e.outcome === 'migrated-body-absent'
+					? '[migrated:body-absent]'
+					: e.outcome === 'not-stuck'
+						? '[healthy]            '
+						: e.outcome === 'skipped-no-item-form'
+							? '[skipped:no-item-form]'
+							: e.outcome === 'lost'
+								? '[lost]               '
+								: '[error]              ';
+		lines.push(`  ${tag} ${e.entry}  ${e.message}`);
+	}
+	return lines;
+}
+
+/** Read the raw `lock.md` blob body from a lock ref, or throw. Bypasses
+ * {@link parseLockEntry} on purpose — the caller needs the untouched legacy
+ * text (which the coercing parser strips). */
+async function readLockBlob(
+	ref: string,
+	cwd: string,
+	env: NodeJS.ProcessEnv | undefined,
+): Promise<string> {
+	const show: RunResult = await runAsync(
+		'git',
+		['show', `${ref}:lock.md`],
+		cwd,
+		{env},
+	);
+	if (show.status !== 0) {
+		throw new Error(
+			`git show ${ref}:lock.md failed (exit ${show.status}): ${show.stderr.trim()}`,
+		);
+	}
+	return show.stdout;
+}
+
+/** True iff `body` is the legacy `state: stuck` shape (the pre-retirement
+ * lock-entry blob). Matched on the raw frontmatter line so this is unaffected
+ * by the current parser's coercion to `active`. */
+export function isLegacyStuckBlob(body: string): boolean {
+	const normalized = body.replace(/\r\n/g, '\n');
+	const fm = /^---\n([\s\S]*?)\n---/.exec(normalized);
+	if (!fm) {
+		return false;
+	}
+	return /^state:\s*stuck\s*$/m.test(fm[1]);
+}
+
+/**
+ * Extract the bounce reason from a legacy stuck lock blob. Preference order
+ * (the two shapes the retired serialiser produced):
+ *   1. A `## Reason` block in the body (multi-line, blank-trimmed).
+ *   2. A one-line `reason:` field in the frontmatter (pre-cutover shape).
+ * Returns `undefined` when neither is present.
+ */
+export function extractLegacyReason(body: string): string | undefined {
+	const normalized = body.replace(/\r\n/g, '\n');
+	const fm = /^---\n([\s\S]*?)\n---/.exec(normalized);
+	const bodyText = fm ? normalized.slice(fm[0].length) : normalized;
+	const lines = bodyText.split('\n');
+	const start = lines.findIndex((l) => l.trim() === '## Reason');
+	if (start !== -1) {
+		const collected: string[] = [];
+		for (let i = start + 1; i < lines.length; i++) {
+			if (/^##\s/.test(lines[i])) {
+				break;
+			}
+			collected.push(lines[i]);
+		}
+		const text = collected.join('\n').replace(/^\n+/, '').replace(/\n+$/, '');
+		if (text !== '') {
+			return text;
+		}
+	}
+	if (fm) {
+		const m = /^reason:\s*(.*)$/m.exec(fm[1]);
+		if (m && m[1].trim() !== '') {
+			return m[1].trim();
+		}
+	}
+	return undefined;
+}
+
+/** Extract the `## Questions` bulleted list from a legacy stuck lock blob (or
+ * `[]` when absent). Each bullet becomes one question string. */
+export function extractLegacyQuestions(body: string): string[] {
+	const normalized = body.replace(/\r\n/g, '\n');
+	const fm = /^---\n[\s\S]*?\n---/.exec(normalized);
+	const bodyText = fm ? normalized.slice(fm[0].length) : normalized;
+	const lines = bodyText.split('\n');
+	const start = lines.findIndex((l) => l.trim() === '## Questions');
+	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;
+}