dorfl 0.1.2 → 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
@@ -91,7 +88,7 @@ export type LedgerTransitionKind =
 	/**
 	 * 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;
 
@@ -181,9 +179,10 @@ 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+; spec
- * `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

@@ -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,

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
@@ -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;
 }
@@ -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 ---