dorfl 0.1.1 → 0.2.0

package/src/ledger-write.ts

@@ -9,6 +9,7 @@ import type {IntegrationMode} from './config.js';
 import {
 	routeToNeedsAttention,
 	returnToBacklog,
+	surfaceStuckToNeedsAttention,
 	type RouteToNeedsAttentionOptions,
 	type RouteToNeedsAttentionResult,
 	type ReturnToBacklogOptions,
@@ -17,11 +18,7 @@ import {
 	type SurfaceToNeedsAttentionResult,
 	type BranchPushOutcome,
 } from './needs-attention.js';
-import {
-	markStuckItemLock,
-	resumeItemLock,
-	type TransitionOutcome,
-} from './item-lock.js';
+import type {NewQuestion} from './sidecar.js';
 
 /**
  * The **write half** of the ledger-transition seam (ADR
@@ -89,9 +86,9 @@ export type LedgerTransitionKind =
 	| 'tasking'
 	| 'advancing'
 	/**
-	 * The **promote** transition (prd `staging-pool-position-gate-and-trust-model`,
+	 * The **promote** transition (spec `staging-pool-position-gate-and-trust-model`,
 	 * task `pre-backlog-staging-folder-and-promote-step-a`): move a STAGED task
-	 * `work/pre-backlog/<slug>.md → work/backlog/<slug>.md` to enter the
+	 * `work/tasks/backlog/<slug>.md → work/tasks/ready/<slug>.md` to enter the
 	 * agent-eligible pool. A durable `main` move, the same category as `requeue`
 	 * (tree-less CAS via {@link applyTransition}). RUNNER/human-owned — no
 	 * agent-facing path performs it (governing ADR
@@ -158,14 +155,15 @@ export interface ApplyCompleteTransitionInput {
 export type ApplyCompleteTransitionResult = IntegrateResult;
 
 /**
- * A *prepared* NEEDS-ATTENTION transition the caller asks the seam to apply: a
- * stuck claimed item to bounce to `work/needs-attention/` with its reason. Like
- * the other inputs it is storage-agnostic — it names the slug, the reason prose,
- * any surfaced questions, and an OPTIONAL arbiter to also push the branch to,
- * NOT *where* the move commits/publishes (the sole strategy decides that: a
- * `git mv` from whichever of in-progress/ or done/ holds the item, the
- * reason-in-the-body, the ONE atomic commit, the optional branch push). This
- * mirrors {@link RouteToNeedsAttentionOptions} so the move mechanism is unchanged.
+ * A *prepared* NEEDS-ATTENTION transition the caller asks the seam to apply:
+ * mark a stuck claimed item on its per-item lock with the reason. Like the
+ * other inputs it is storage-agnostic — it names the slug, the reason prose,
+ * any surfaced questions, and an OPTIONAL arbiter to also push the work branch
+ * to, NOT *where* the surface commits/publishes (the sole strategy decides
+ * that: post lock-cutover, a lock amend to `state: stuck` with the reason on
+ * the lock entry — no `work/needs-attention/` folder write — plus the optional
+ * branch push). This mirrors {@link RouteToNeedsAttentionOptions} so the
+ * mechanism stays unchanged.
  */
 export type ApplyNeedsAttentionTransitionInput = RouteToNeedsAttentionOptions;
 
@@ -174,16 +172,17 @@ export type ApplyNeedsAttentionTransitionInput = RouteToNeedsAttentionOptions;
  * move result the folder-native mechanism produces. The RECOVERABLE branch push
  * outcome rides on `branchPush` (the caller reads it rather than assuming
  * "pushed" off the local move). The OBSERVABLE half is now the per-item lock
- * `state: stuck` amend (prd `ledger-status-per-item-lock-refs`); there is no
+ * `state: stuck` amend (spec `ledger-status-per-item-lock-refs`); there is no
  * separate on-`main` surface outcome to report.
  */
 export type ApplyNeedsAttentionTransitionResult = RouteToNeedsAttentionResult;
 
 /**
  * A *prepared* RETURN-TO-BACKLOG transition: re-queue a STUCK item so it can be
- * re-claimed — recovered from EITHER `needs-attention/` (the resolved-surface
- * path) OR `in-progress/` (a claim that never surfaced), the slug's actual
- * current folder resolved on the arbiter and moved to `backlog/`.
+ * re-claimed — recovered via its per-item lock on the arbiter (post lock-cutover
+ * the body never moved into a status folder; it rests in `backlog/`, so requeue
+ * releases/clears the lock rather than moving a `.md`). Covers both a resolved
+ * stuck hold and a claim that never surfaced.
  * Storage-agnostic, mirroring {@link ReturnToBacklogOptions}.
  */
 export type ApplyReturnToBacklogTransitionInput = ReturnToBacklogOptions;
@@ -198,11 +197,12 @@ export type ApplyReturnToBacklogTransitionResult =
 
 /**
  * A *prepared* TREE-LESS NEEDS-ATTENTION (surface) transition: surface a stuck
- * AFTER-COMMIT, LEDGER-ONLY item (`in-progress/ → needs-attention/`, with the
- * reason in the body) WITHOUT a checkout — the SURFACE-direction sibling of the
+ * AFTER-COMMIT, LEDGER-ONLY item (post lock-cutover — mark its per-item lock
+ * `state: stuck` with the reason, no `in-progress/ → needs-attention/` folder
+ * move) WITHOUT a checkout — the SURFACE-direction sibling of the
  * tree-less requeue, sharing its exact mechanism. The work is ALREADY committed
  * on the kept `work/<slug>` branch (intact on the arbiter, recoverable), so the
- * surface is purely the one-file `.md` move + reason — no `pushBranch`, no
+ * surface is purely the lock amend + reason — no `pushBranch`, no
  * worktree. Storage-agnostic, mirroring {@link SurfaceToNeedsAttentionOptions}.
  * NOT for the wip-save / gate-failed / agent-failed surfaces (which may carry
  * uncommitted work — those keep {@link applyNeedsAttentionTransition}, the
@@ -322,21 +322,22 @@ export interface LedgerWriteStrategy {
 		input: ApplyCompleteTransitionInput,
 	): Promise<ApplyCompleteTransitionResult>;
 	/**
-	 * Apply a NEEDS-ATTENTION transition: bounce a stuck claimed item to
-	 * `work/needs-attention/` with its reason recorded in the body. The sole
-	 * strategy delegates to the folder-native move mechanism unchanged; a future
-	 * strategy could surface the stuck item elsewhere (e.g. the cherry-pick-to-
-	 * `main` follow-on) without `complete.ts`/`run.ts` changing.
+	 * Apply a NEEDS-ATTENTION transition: mark a stuck claimed item on its
+	 * per-item lock with its reason (post lock-cutover — no folder write). The
+	 * sole strategy delegates to the underlying mechanism unchanged; a future
+	 * strategy could surface the stuck item elsewhere without
+	 * `complete.ts`/`run.ts` changing.
 	 */
 	applyNeedsAttentionTransition(
 		input: ApplyNeedsAttentionTransitionInput,
 	): Promise<ApplyNeedsAttentionTransitionResult>;
 	/**
 	 * Apply a TREE-LESS NEEDS-ATTENTION (surface) transition: surface a stuck
-	 * AFTER-COMMIT, LEDGER-ONLY item (`in-progress/ → needs-attention/`) WITHOUT a
+	 * AFTER-COMMIT, LEDGER-ONLY item (post lock-cutover — mark its per-item lock
+	 * `state: stuck`, no `in-progress/ → needs-attention/` folder move) WITHOUT a
 	 * checkout, reusing the SAME tree-less mechanism `requeue` uses for the reverse
-	 * direction. The sole strategy delegates to the tree-less surface (now a pure lock amend)
-	 * (fetch + scratch-index move + throwaway-ref + leased fast-forward push). NOT
+	 * direction. The sole strategy delegates to the tree-less surface (a pure lock
+	 * amend CAS-published to the arbiter's lock ref). NOT
 	 * for the uncommitted-wip surfaces, which keep {@link
 	 * applyNeedsAttentionTransition} (the cwd-bound path that can commit wip first).
 	 */
@@ -344,10 +345,11 @@ export interface LedgerWriteStrategy {
 		input: ApplyTreelessNeedsAttentionTransitionInput,
 	): ApplyTreelessNeedsAttentionTransitionResult;
 	/**
-	 * Apply a RETURN-TO-BACKLOG transition: re-queue a STUCK item (in
-	 * `needs-attention/` OR `in-progress/` — resolved on the arbiter) for
+	 * Apply a RETURN-TO-BACKLOG transition: re-queue a STUCK item (recovered via
+	 * its per-item lock on the arbiter — post lock-cutover the body rests in
+	 * `backlog/`, not a status folder) for
 	 * re-claiming, routed through the SAME seam. Like `claim`, it is TREE-LESS —
-	 * the move is a compare-and-swap push to the arbiter ref (it never writes the
+	 * the amend is a compare-and-swap push to the arbiter ref (it never writes the
 	 * cwd tree).
 	 */
 	applyReturnToBacklogTransition(
@@ -630,12 +632,12 @@ export const currentLedgerWrite: LedgerWriteStrategy = {
 	 *     bounce its `work/prd-<slug>`, a temp-branch caller pushes NOTHING.)
 	 *
 	 * Both halves are ONE operation done in ONE place: it delegates to {@link
-	 * routeToNeedsAttention}, which appends the reason as body prose (never a
-	 * frontmatter field — WORK-CONTRACT rule 3), saves the aborted work as a
-	 * **wip** commit, `git mv`s the item to `work/needs-attention/` as the
-	 * **move-only** commit (the tip), and — when an `arbiter` is given — pushes the
-	 * work branch (best-effort, branch-parameterised, emptiness-guarded; SURFACE-
-	 * ONLY when `pushBranch: false`). The seam does NOT strip the arbiter: the same
+	 * routeToNeedsAttention}, which saves the aborted work as a **wip** commit
+	 * on the work branch (post lock-cutover no `work/needs-attention/` folder
+	 * write ever fires here) and — when an `arbiter` is given — pushes the work
+	 * branch (best-effort, branch-parameterised, emptiness-guarded; SURFACE-
+	 * ONLY when `pushBranch: false`). The OBSERVABLE lock amend rides on
+	 * {@link bounceToStuckLock} directly below. The seam does NOT strip the arbiter: the same
 	 * arbiter both publishes the surface (here) AND drives the helper's branch push,
 	 * so "record stuck" and "save the work" can never drift apart. The human-vs-
 	 * autonomous gate rides on whether an `arbiter` is given at all (human
@@ -657,9 +659,10 @@ export const currentLedgerWrite: LedgerWriteStrategy = {
 		// outage-retried), so the partial work travels cross-machine and a `requeue`
 		// continues from the tip. The work-branch push is NOT a `main` write.
 		const saved = await routeToNeedsAttention(input);
-		const stuck = await bounceToStuckLock({
+		const surfaced = await bounceThroughSurface({
 			cwd: input.cwd,
 			slug: input.slug,
+			item: `task:${input.slug}`,
 			reason: input.reason,
 			questions: input.questions,
 			arbiter: input.arbiter,
@@ -667,11 +670,12 @@ export const currentLedgerWrite: LedgerWriteStrategy = {
 			note: input.note,
 		});
 		return {
-			// `moved` reflects the OBSERVABLE half (the stuck record): the lock amend.
-			moved: stuck.moved,
-			reasonNotMoved: stuck.reasonNotMoved,
+			// `moved` reflects the OBSERVABLE half (the surface record): the sidecar +
+			// `needsAnswers:true` on `<arbiter>/main` (or the human-local no-op).
+			moved: surfaced.moved,
+			reasonNotMoved: surfaced.reasonNotMoved,
 			// The branch push outcome is the honest RECOVERABLE report (`do`/`run` read
-			// it). The on-`main` surface half is GONE (the lock is the surface now).
+			// it).
 			branchPush: saved.branchPush,
 			pushError: saved.pushError,
 		};
@@ -680,7 +684,7 @@ export const currentLedgerWrite: LedgerWriteStrategy = {
 	/**
 	 * The return-to-backlog transition under the SAME strategy: re-queue the
 	 * stuck item by delegating to {@link returnToBacklog}, which moves the slug's
-	 * current `work/<needs-attention|in-progress>/<slug>.md → work/backlog/<slug>.md`
+	 * current `work/<needs-attention|in-progress>/<slug>.md → work/tasks/ready/<slug>.md`
 	 * TREE-LESSLY — it
 	 * builds the move off `<arbiter>/main` with plumbing and CAS-publishes it back
 	 * THROUGH this same write seam (`applyTransition`, the very push+lease+verify
@@ -693,165 +697,146 @@ export const currentLedgerWrite: LedgerWriteStrategy = {
 	},
 
 	/**
-	 * The tree-less surface transition under the SAME strategy: surface the stuck
-	 * AFTER-COMMIT, LEDGER-ONLY item by delegating to the tree-less surface (now a pure lock amend),
-	 * which moves `work/in-progress/<slug>.md → work/needs-attention/<slug>.md`
-	 * (reason in the body) TREE-LESSLY — it builds the move off `<arbiter>/main` with
-	 * plumbing and CAS-publishes it THROUGH this same write seam
-	 * (`applyTransition`, the very push+lease+verify `claim`/`requeue` use), never
-	 * staging/committing in the cwd working tree. The reverse of
+	 * The tree-less surface transition under the SAME strategy: surface the
+	 * stuck AFTER-COMMIT, LEDGER-ONLY item by delegating to the tree-less
+	 * surface — post lock-cutover a pure LOCK AMEND (`state: stuck` with the
+	 * reason on the lock entry), CAS-published to the arbiter's lock ref via
+	 * the same push+lease+verify seam `claim`/`requeue` use, never staging or
+	 * committing in the cwd working tree. The reverse of
 	 * {@link applyReturnToBacklogTransition}, the same one mechanism.
 	 */
 	async applyTreelessNeedsAttentionTransition(
 		input: ApplyTreelessNeedsAttentionTransitionInput,
 	): ApplyTreelessNeedsAttentionTransitionResult {
-		// PURE LOCK AMEND (task
-		// `cutover-needs-attention-becomes-lock-stuck-recovery-surface`, decision i+):
-		// the after-commit / ledger-only surface (continue-push-failure /
-		// continue-rebase-conflict) is now the SAME `active → stuck` lock amend as the
-		// cwd-bound bounce — NO `git mv`, NO `main` write. The recoverable work is
-		// already committed on the kept `work/<slug>` branch (intact on the arbiter);
-		// the stuck reason + questions ride on the lock entry. A re-surface of an
-		// already-stuck item is a tolerated idempotent no-op (`wrong-state`).
-		const moved = await bounceToStuckLock({
+		// PR-2b surface cutover (spec
+		// `surface-stuck-as-questions-and-retire-stuck-lock-state`, decision #1): the
+		// after-commit / ledger-only surface (continue-push-failure / continue-rebase-
+		// conflict) surfaces the item on `<arbiter>/main` (a `stuck`-kind sidecar +
+		// `needsAnswers:true` on the item body in ONE commit) THEN releases the per-
+		// item lock. Surface-FIRST, release-SECOND, with `main`-authoritative crash
+		// recovery inherited from {@link runTreelessLedgerMove}. The recoverable work
+		// is already committed on the kept `work/<slug>` branch (intact on the arbiter).
+		const surfaced = await bounceThroughSurface({
 			cwd: input.cwd,
 			slug: input.slug,
+			item: `task:${input.slug}`,
 			reason: input.reason,
 			questions: input.questions,
 			arbiter: input.arbiter,
 			env: input.env,
 			note: input.note,
 		});
-		return {moved: moved.moved, reasonNotMoved: moved.reasonNotMoved};
+		return {moved: surfaced.moved, reasonNotMoved: surfaced.reasonNotMoved};
 	},
 
 	/**
 	 * The resolve-needs-attention transition under the SAME strategy — satisfying
-	 * the INTENT "clear the stuck surface + restore in-progress." It delegates to
-	 * the resume lock amend (reverse `git mv` needs-attention →
-	 * in-progress, committed) and, when an `arbiter` is given, publishes that
-	 * reverse move-only commit to the arbiter's `main` — CLEARING the stuck surface
-	 * there (the item is back in in-progress on the ledger). Same all-or-nothing,
-	 * never-`--force` publish. "Reverse-move on `main`" is a detail of THIS
-	 * strategy; the seam's contract is only the intent "clear the surface."
+	 * the INTENT "clear the stuck surface + restore active." It delegates to
+	 * the resume lock amend (post lock-cutover — `stuck → active` on the per-item
+	 * lock, no reverse `needs-attention/ → in-progress/` folder move) and, when an
+	 * `arbiter` is given, CAS-publishes that lock amend to the arbiter's lock ref —
+	 * CLEARING the stuck surface there (the item is active again). Same
+	 * all-or-nothing, never-`--force` publish. The lock-ref amend is a detail of
+	 * THIS strategy; the seam's contract is only the intent "clear the surface."
 	 */
 	async applyResolveNeedsAttentionTransition(
-		input: ApplyResolveNeedsAttentionTransitionInput,
+		_input: ApplyResolveNeedsAttentionTransitionInput,
 	): Promise<ApplyResolveNeedsAttentionTransitionResult> {
-		// PURE LOCK AMEND (task
-		// `cutover-needs-attention-becomes-lock-stuck-recovery-surface`, decision i+):
-		// resolving a stuck item is `stuck → active` on the per-item lock (a human is
-		// picking it up), NOT a `needs-attention/ → in-progress/` folder move. NO `main`
-		// write — the body already rests in `backlog/` (task 9a) and the work stays on
-		// the kept `work/<slug>` branch. Without an arbiter there is no lock ref to
-		// amend (the human-local face), so it is a recorded no-op success.
-		if (!input.arbiter) {
-			return {moved: true};
-		}
-		const r = await resumeItemLock({
-			item: `task:${input.slug}`,
-			cwd: input.cwd,
-			arbiter: input.arbiter,
-			env: input.env,
-		});
-		if (r.outcome === 'transitioned') {
-			return {moved: true};
-		}
-		// `wrong-state` (already active — not actually stuck) is tolerated as a no-op
-		// success: the item is already in-flight, the caller onboards onto it anyway.
-		if (r.outcome === 'wrong-state') {
-			return {moved: true};
-		}
-		return {
-			moved: false,
-			reasonNotMoved: `could not resume '${input.slug}' (${r.outcome}: ${r.message}).`,
-		};
+		// Post-`retire-stuck-lock-state`: the `stuck` lock state is retired, so
+		// there is no `stuck → active` lock amend to perform. A parked item is
+		// now a `needsAnswers:true` pool item on `main` with a sidecar, drained
+		// by the apply rung (answer the sidecar), not by a resolve verb. The seam
+		// is kept for source compatibility of its remaining legacy callers
+		// (start.ts's legacy `needs-attention/` folder branch), where it is a
+		// recorded no-op success.
+		return {moved: true};
 	},
 };
 
 /**
- * The SOLE stuck-state RECORD: amend the item's HELD per-item lock
- * `active → stuck` + the FULL reason prose + any agent-surfaced questions, via the
- * state machine's mark-stuck CAS amend ({@link markStuckItemLock}) — task
- * `cutover-needs-attention-becomes-lock-stuck-recovery-surface` (decision i+; prd
- * `ledger-status-per-item-lock-refs` US #5/#8; ADR
- * `ledger-status-on-per-item-lock-refs`). This REPLACES the `git mv →
- * needs-attention/` folder bounce + its on-`main` surface + branch push: the
- * bounce now touches ONLY the lock ref (NO `main` write — so a protected-`main`
- * bounce succeeds, and a work branch cut from `main` inherits no stuck record).
- *
- * The bounce holds the TASK's `implement` lock that `claim` acquired (task
- * `claim-acquires-unified-lock-no-body-move`), so the normal stuck path is a plain
- * `active → stuck` amend (`transitioned`). The OUTCOME MAPPING onto `{moved}`:
- *   - `transitioned`  — the lock is now stuck (the stuck state is recorded) ⇒
- *     `moved: true`.
- *   - `wrong-state`   — the lock is ALREADY `stuck` (an idempotent re-surface of a
- *     still-stuck item) ⇒ `moved: true` (the stuck record stands).
- *   - `not-held`      — there is NO held lock to amend (an item that predates the
- *     lock, or a flow where claim did not acquire) ⇒ `moved: false` honestly: with
- *     the folder retired there is no other substrate to record the stuck state on,
- *     so the caller reports the bounce did NOT land (retry/resolve) rather than
- *     fake a success.
- *   - `lost`/`error`  — a concurrent CAS race / environment fault ⇒ `moved: false`.
- *   - no arbiter      — a human local-only `complete` (no arbiter handle): the lock
- *     ref lives on the arbiter, so there is no lock to amend; treat as a recorded
- *     no-op (`moved: true`) — a human is right there (the same human-vs-autonomous
- *     posture the old local-only folder move took). NOTE this records nothing
- *     durable, by design: the human is in the loop.
+ * The SOLE stuck-state RECORD (PR-2b, spec
+ * `surface-stuck-as-questions-and-retire-stuck-lock-state`, user stories 1/3/8,
+ * decisions #1/#4): surface the bounced item as a `stuck`-kind sidecar +
+ * `needsAnswers:true` on the item body in ONE commit on `<arbiter>/main`, THEN
+ * release the per-item lock. Surface-FIRST, release-SECOND — the ordering is
+ * load-bearing so a crash between them is recoverable from `main` (the classifier
+ * fold in `item-lock.ts` re-derives `cleared-stale` from the main-side truth
+ * PR-2a landed). This REPLACES the retired `active → stuck` lock amend: no
+ * bounce leaves a `stuck` lock; a bounced item rests as a plain `needsAnswers:true`
+ * pool item (`eligible:false` by construction).
  *
- * Keyed on `task:<slug>` (the bounce surfaces a TASK; the prd/observation locks
- * are tasking/advance holds whose own bounce paths are separate).
+ * The OUTCOME MAPPING onto `{moved}`:
+ *   - `surfaced`        — the sidecar + `needsAnswers:true` commit landed on
+ *     `<arbiter>/main` and the lock was released ⇒ `moved: true`.
+ *   - `bodyAbsent`      — the D1 probe found no body for the item on `main` (a
+ *     bounce for an item whose body never landed — e.g. a claim that lost/raced).
+ *     The surface is a CLEAN NO-OP; the lock is STILL released so the bounce is
+ *     never a dead-end held lock ⇒ `moved: true` (nothing to record, nothing left
+ *     stuck).
+ *   - `!surfaced`       — the surface commit did NOT land (contention exhausted,
+ *     item missing on main by explicit path, environment fault) ⇒ `moved: false`
+ *     with `reasonNotMoved` so the caller reports the honest not-landed state.
+ *   - no arbiter        — a human local-only `complete` (no arbiter handle): the
+ *     surface primitive requires an arbiter, so this is a recorded no-op (`moved:
+ *     true`) — a human is right there (the same human-vs-autonomous posture the
+ *     retired lock amend took). NOTE this records nothing durable, by design.
  */
-async function bounceToStuckLock(params: {
+async function bounceThroughSurface(params: {
 	cwd: string;
 	slug: string;
+	item: string;
 	reason: string;
 	questions?: string[];
 	arbiter?: string;
 	env?: NodeJS.ProcessEnv;
 	note?: (message: string) => void;
 }): Promise<{moved: boolean; reasonNotMoved?: string}> {
-	const {cwd, slug, reason, questions, arbiter, env} = params;
+	const {cwd, slug, item, reason, questions, arbiter, env} = params;
 	const note = params.note ?? (() => {});
 	if (!arbiter) {
-		// No arbiter handle ⇒ no lock ref to amend. A human local-only `complete`:
-		// the human is right there, so this is a recorded no-op (parity with the old
-		// local-only folder move that wrote nothing cross-machine).
+		// No arbiter handle ⇒ no `<arbiter>/main` to surface on. A human local-only
+		// `complete`: the human is right there, so this is a recorded no-op (parity
+		// with the retired local-only lock amend that wrote nothing cross-machine).
 		note(
-			`'${slug}' bounced locally (no arbiter) — the stuck reason is not recorded ` +
-				'on a lock ref (a human is right here).',
+			`'${slug}' bounced locally (no arbiter) — the stuck reason is not surfaced ` +
+				'on <arbiter>/main (a human is right here).',
 		);
 		return {moved: true};
 	}
+	const asNewQuestions: NewQuestion[] | undefined = questions?.map((q) => ({
+		question: q,
+		kind: 'stuck' as const,
+	}));
 	try {
-		const r = await markStuckItemLock({
-			item: `task:${slug}`,
-			reason,
-			questions,
+		const r = await surfaceStuckToNeedsAttention({
 			cwd,
+			slug,
+			item,
+			reason,
+			questions: asNewQuestions,
 			arbiter,
 			env,
+			note,
 		});
-		const movedOutcomes: TransitionOutcome[] = ['transitioned', 'wrong-state'];
-		if (movedOutcomes.includes(r.outcome)) {
-			if (r.outcome === 'transitioned') {
-				note(`Marked the per-item lock for '${slug}' stuck: ${reason}`);
-			} else {
-				note(`The per-item lock for '${slug}' is already stuck (re-surface).`);
-			}
+		if (r.surfaced) {
+			note(`Surfaced '${item}' on ${arbiter}/main (stuck): ${reason}`);
+			return {moved: true};
+		}
+		if (r.bodyAbsent) {
+			note(
+				`'${item}' has no body on ${arbiter}/main — surface skipped as a clean ` +
+					'no-op; the lock was still released to avoid a dead-end held lock.',
+			);
 			return {moved: true};
 		}
 		const reasonNotMoved =
-			r.outcome === 'not-held'
-				? `'${slug}' has no held lock to mark stuck (the bounce could not record ` +
-					'the stuck state — the item is not lock-held).'
-				: `could not mark the per-item lock for '${slug}' stuck (${r.outcome}: ` +
-					`${r.message}).`;
+			r.reasonNotSurfaced ??
+			`could not surface '${item}' on ${arbiter}/main (unknown reason).`;
 		note(reasonNotMoved);
 		return {moved: false, reasonNotMoved};
 	} catch (err) {
 		const reasonNotMoved =
-			`could not mark the per-item lock for '${slug}' stuck ` +
+			`could not surface '${item}' on ${arbiter}/main ` +
 			`(${err instanceof Error ? err.message : String(err)}).`;
 		note(reasonNotMoved);
 		return {moved: false, reasonNotMoved};

package/src/lifecycle-gather.ts

@@ -65,8 +65,8 @@ function readSidecarInPlace(
 }
 
 /**
- * Collect every `needsAnswers:true` task (from `work/backlog`) + prd (from
- * `work/prds`) for the in-place repo, through the read seam (the SAME readers the
+ * Collect every `needsAnswers:true` task (from `work/backlog`) + spec (from
+ * `work/specs`) for the in-place repo, through the read seam (the SAME readers the
  * build-pool scan uses). These are the SURFACE/APPLY candidates this task draws
  * into the selection (today they are build/task-INELIGIBLE, so nothing else
  * surfaces them).
@@ -89,25 +89,25 @@ function blockedItemsInPlace(
 			out.push({namespace: 'spec', slug: spec.slug});
 		}
 	}
-	// TASKED resting prds (`prds/tasked/`) — enumerated UNCONDITIONALLY (NOT behind
-	// `surfaceStaging`), because a prd may legitimately carry `needsAnswers:true`
-	// while resting in `prds/tasked/` (WORK-CONTRACT "A PRD that has drifted AFTER
-	// it was TASKED"). This is NOT a staging widening: a tasked prd is a durable
+	// TASKED resting prds (`specs/tasked/`) — enumerated UNCONDITIONALLY (NOT behind
+	// `surfaceStaging`), because a spec may legitimately carry `needsAnswers:true`
+	// while resting in `specs/tasked/` (WORK-CONTRACT "A SPEC that has drifted AFTER
+	// it was TASKED"). This is NOT a staging widening: a tasked spec is a durable
 	// resting state, like the pool, so it is enumerated like the pool. Routing
 	// still respects the gates in `buildLifecyclePools` (an ANSWERED sidecar -> the
 	// always-on APPLY pool so the human's answer is never STRANDED; a NO-sidecar
-	// tasked prd -> SURFACE, still gated by `surfaceBlockers`). Without this, a
-	// tasked prd's answered sidecar is enumerated by no pool and apply never runs
+	// tasked spec -> SURFACE, still gated by `surfaceBlockers`). Without this, a
+	// tasked spec's answered sidecar is enumerated by no pool and apply never runs
 	// on it (observation `tasked-prd-needsanswers-sidecar-stranded-no-apply-pool`).
 	for (const spec of read.resolveLocalSpecTasked({repoPath})) {
 		if (spec.needsAnswers === true) {
 			out.push({namespace: 'spec', slug: spec.slug});
 		}
 	}
-	// SURFACE-on-STAGING widening (prd
+	// SURFACE-on-STAGING widening (spec
 	// `staging-surface-and-apply-promote-safety` F2): when `surfaceStaging` is
 	// ON, the candidate set ADDITIONALLY enumerates `needsAnswers` items resting
-	// in STAGING (`tasks/backlog/` + `prds/proposed/`), so a tasked item
+	// in STAGING (`tasks/backlog/` + `specs/proposed/`), so a tasked item
 	// surfaces its questions BEFORE the human promotes it. BUILD/claim still
 	// reads POOL-only (`scoreItems` over `state.ready`); only the surface polarity
 	// widens here.
@@ -136,9 +136,27 @@ export function gatherLifecycleInPlace(input: {
 	repoPath: string;
 	read?: LedgerReadStrategy;
 	gates?: LifecyclePoolGates;
+	/**
+	 * The HELD TASK slugs to SUBTRACT from the triage/surface/apply candidate
+	 * inputs before {@link buildLifecyclePools} routes them (task
+	 * `in-place-scan-subtracts-held-locked-slugs-from-propose-matrix`).
+	 *
+	 * Symmetric to the pool-side subtraction `scoreItems` already runs on
+	 * `state.ready`: without it, a `needsAnswers` TASK whose per-item lock is
+	 * currently held (state `active`/`stuck`) still slips into the surface / apply
+	 * pool, so `scan --json` enumerates a matrix leg for it that then always loses
+	 * the claim CAS (`claim-cas.ts:127-132`) — reddening the propose tick every
+	 * cadence for as long as the item is held. Narrowly TASK-scoped (this is what
+	 * {@link heldTaskSlugs} returns): an observation triage entry / a spec surface
+	 * entry is NOT filtered here, because the lock ref prefix `task-<slug>` only
+	 * gates the task namespace. Defaults empty (byte-identical to pre-fix
+	 * behaviour) so callers who cannot resolve a lock read still work.
+	 */
+	heldSlugs?: Set<string>;
 }): SelectedLifecyclePools {
 	const read = input.read ?? ledgerRead;
 	const repoPath = input.repoPath;
+	const heldSlugs = input.heldSlugs ?? new Set<string>();
 
 	const rawObservations = read.resolveLocalState({repoPath}).observations;
 	const observations: ObservationCandidate[] = rawObservations.map((obs) => ({
@@ -151,12 +169,17 @@ export function gatherLifecycleInPlace(input: {
 		read,
 		repoPath,
 		surfaceStaging,
-	).map((item) => ({
-		repoPath,
-		namespace: item.namespace,
-		slug: item.slug,
-		sidecar: readSidecarInPlace(repoPath, item.namespace, item.slug),
-	}));
+	)
+		// Held-slug subtraction (task-scoped): a `needsAnswers` TASK whose per-item
+		// lock is currently held is EXCLUDED from surface/apply enumeration. Spec /
+		// observation entries are untouched — the lock ref set here is task-only.
+		.filter((item) => !(item.namespace === 'task' && heldSlugs.has(item.slug)))
+		.map((item) => ({
+			repoPath,
+			namespace: item.namespace,
+			slug: item.slug,
+			sidecar: readSidecarInPlace(repoPath, item.namespace, item.slug),
+		}));
 
 	return buildLifecyclePools({
 		repoPath,
@@ -195,7 +218,7 @@ async function readSidecarMirror(
  * Gather + build the lifecycle pools for a MIRROR-SIDE bare hub mirror (async).
  * Reads the SAME logical inputs as {@link gatherLifecycleInPlace} \u2014 observations +
  * the `needsAnswers` pool from the mirror's committed `main` (via
- * `resolveMirrorState`), the prd pool via `resolveMirrorSpecPool`, and each item's
+ * `resolveMirrorState`), the spec pool via `resolveMirrorSpecPool`, and each item's
  * sidecar via `git show` \u2014 then hands them to the SAME shared
  * {@link buildLifecyclePools}, so the in-place + mirror enumerations AGREE.
  */
@@ -232,9 +255,9 @@ export async function gatherLifecycleMirror(input: {
 			blocked.push({namespace: 'spec', slug: spec.slug});
 		}
 	}
-	// TASKED resting prds (`<ref>:work/prds/tasked/`) — enumerated UNCONDITIONALLY,
-	// the mirror-side counterpart of the in-place tasked-prd enumeration above
-	// (so a `needsAnswers` tasked prd's answered sidecar is never stranded on the
+	// TASKED resting prds (`<ref>:work/specs/tasked/`) — enumerated UNCONDITIONALLY,
+	// the mirror-side counterpart of the in-place tasked-spec enumeration above
+	// (so a `needsAnswers` tasked spec's answered sidecar is never stranded on the
 	// mirror/CI advance path either). Routing still respects the gates.
 	const specTasked = await read.resolveMirrorSpecTasked({mirrorPath, ref, env});
 	for (const spec of specTasked) {
@@ -242,10 +265,10 @@ export async function gatherLifecycleMirror(input: {
 			blocked.push({namespace: 'spec', slug: spec.slug});
 		}
 	}
-	// SURFACE-on-STAGING widening (prd
+	// SURFACE-on-STAGING widening (spec
 	// `staging-surface-and-apply-promote-safety` F2): mirror-side counterpart of
 	// the in-place widening above — enumerate `needsAnswers` items in
-	// STAGING (`tasks/backlog/` + `prds/proposed/`) from the bare mirror's
+	// STAGING (`tasks/backlog/` + `specs/proposed/`) from the bare mirror's
 	// committed `<ref>` tree, so the in-place + mirror surfaces AGREE. The
 	// staging reads are skipped entirely when the gate is OFF (no extra git
 	// ls-tree work in the legacy mode).