dorfl 0.1.2 → 0.2.0

package/src/needs-attention.ts

@@ -9,7 +9,10 @@ import {
 	isWorkItemFile,
 } from './work-layout.js';
 import {run, runAsync, type RunResult} from './git.js';
-import {branchAheadOf} from './continue-branch.js';
+import {
+	branchAheadOf,
+	rebaseContinuedBranchOntoMain,
+} from './continue-branch.js';
 import {
 	acquireItemLock,
 	releaseItemLock,
@@ -21,6 +24,17 @@ import {
 } from './item-lock.js';
 import {ledgerWrite, type LedgerTransitionKind} from './ledger-write.js';
 import {workBranchRef} from './slug-namespace.js';
+import {
+	appendQuestions,
+	newSidecar,
+	parseSidecar,
+	resolveSidecarIdentity,
+	serialiseSidecar,
+	sidecarPathFor,
+	type NewQuestion,
+	type SidecarType,
+} from './sidecar.js';
+import {parseFrontmatter, setNeedsAnswersMarker} from './frontmatter.js';
 import {
 	retryWithBackoff,
 	realSleep,
@@ -140,11 +154,12 @@ export interface RouteToNeedsAttentionResult {
 	/** When the branch push FAILED after retries, the last git error (for the report). */
 	pushError?: string;
 	/**
-	 * When `moved`, the sha of the **move-only** commit — the tip of `work/<slug>`
-	 * that carries PURELY the `git mv → needs-attention/` + the reason (the wip
-	 * commit holding the aborted agent work sits BELOW it). A surfacing strategy
-	 * cherry-picks THIS commit to make the stuck state observable, so the wip never
-	 * reaches the ledger.
+	 * When `moved`, the sha of the `work/<slug>` tip after the RECOVERABLE-half
+	 * save. Post lock-cutover this is the **wip** commit holding the aborted agent
+	 * work (`git add -A`); there is no separate `git mv → needs-attention/`
+	 * move-only commit anymore (that folder is retired). The OBSERVABLE stuck
+	 * state rides on the per-item lock amend (`state: stuck` + reason), not on this
+	 * commit.
 	 */
 	moveCommit?: string;
 	/** When NOT moved, why (e.g. the slug was not in-progress). */
@@ -155,8 +170,9 @@ export interface ReturnToBacklogOptions {
 	/** The working clone the `work/` tree lives in. */
 	cwd: string;
 	/**
-	 * The slug of the stuck item to re-queue — recovered from `needs-attention/`
-	 * OR `in-progress/` (the actual current folder is resolved on the arbiter).
+	 * The slug of the stuck item to re-queue — recovered via its per-item lock on
+	 * the arbiter (post lock-cutover the body never moves into a status folder; it
+	 * rests in `backlog/` and stuck is the lock `state: stuck`).
 	 */
 	slug: string;
 	/** The arbiter remote to push the transition to. Optional (see above). */
@@ -176,6 +192,29 @@ export interface ReturnToBacklogOptions {
 	 * path.
 	 */
 	reset?: boolean;
+	/**
+	 * `requeue --reconcile` (the NON-DESTRUCTIVE recovery verb — the middle rung
+	 * of the escalation ladder between the default keep+continue and the
+	 * destructive `--reset`). When the item's per-item lock is held stuck AND the
+	 * arbiter's `work/<slug>` branch EXISTS and is ahead of main, re-sync the
+	 * mirror to the arbiter (a prune-fetch that clears the stale-ref residue that
+	 * historically silently resurrected a supposedly-`--reset`-ed branch) and
+	 * RETRY the rebase of the kept branch onto latest `<arbiter>/main` in a
+	 * SCRATCH worktree (never touching the caller's tree, `--force-with-lease`
+	 * only, NEVER a bare force). On a clean rebase, the reconciled tip is
+	 * pushed back to the arbiter with a lease + the reconcile completes as a
+	 * standard keep+continue requeue (lock released, branch preserved). On a
+	 * genuine content conflict after the clean mirror re-sync, the lock is LEFT
+	 * HELD (item stays stuck), the branch is LEFT UNTOUCHED on the arbiter
+	 * (NEVER deleted), and the caller is told the retry happened + pointed at the
+	 * deferred mirror-side resolve follow-on + `--reset` as the destructive last
+	 * resort. If the branch is ABSENT (never pushed, or a prior `--reset` already
+	 * deleted it), reconcile falls through to the default keep+continue path
+	 * (which itself degrades gracefully to a fresh-claim move). Incompatible
+	 * with `--reset` (destructive vs non-destructive are exclusive verbs on the
+	 * same escalation).
+	 */
+	reconcile?: boolean;
 	/**
 	 * `requeue -m "<note>"` (the handoff note): an optional human steer for the
 	 * NEXT agent. APPENDED (never overwritten) as a dated `## Requeue YYYY-MM-DD`
@@ -198,7 +237,15 @@ export interface ReturnToBacklogResult {
 	commitMessage?: string;
 	/** True iff `--reset` deleted the remote `work/<slug>` branch on the arbiter. */
 	deletedRemoteBranch?: boolean;
-	/** When NOT moved, why (e.g. the slug was in neither needs-attention/ nor in-progress/, or a failed --reset delete). */
+	/**
+	 * True iff `--reconcile` re-synced the mirror + rebased the kept branch onto
+	 * latest `<arbiter>/main` and pushed the reconciled tip back to the arbiter
+	 * (before the lock release). Absent on the default path / on `--reset` / on
+	 * a reconcile that fell through (branch absent) — for those, the ordinary
+	 * keep+continue path ran with no rebase.
+	 */
+	reconciled?: boolean;
+	/** When NOT moved, why (e.g. the slug held no recoverable per-item lock on the arbiter, or a failed --reset delete). */
 	reasonNotMoved?: string;
 }
 
@@ -358,7 +405,7 @@ export async function routeToNeedsAttention(
 
 /**
  * The clean re-queue (ADR §12 / WORK-CONTRACT return path): once the human has
- * resolved the cause, move the stuck item back to `work/backlog/<slug>.md` and
+ * resolved the cause, move the stuck item back to `work/tasks/ready/<slug>.md` and
  * commit it so the item can be re-claimed (it must not rot stuck). It recovers a
  * task stuck in EITHER `work/needs-attention/<slug>.md` (the resolved-surface
  * path) OR `work/in-progress/<slug>.md` (a claim that never surfaced — an
@@ -374,12 +421,26 @@ export async function routeToNeedsAttention(
  *     it is the durable artifact the next claim CONTINUES from (the continue-
  *     detection in `continue-branch.ts` feeds both onboarding paths). This
  *     function only does the ledger move.
- *   - **`--reset` = DISCARD + FRESH.** When `reset` is set, DELETE the remote
- *     `work/<slug>` branch on `arbiter` FIRST (+ drop any stale local branch),
- *     THEN the backlog move. Delete-before-move closes the claim-race window; a
- *     FAILED delete ABORTS (no backlog move) so the item stays in
- *     needs-attention. The next claim then finds NO arbiter branch and cuts
- *     fresh — no special claim-time logic.
+ *   - **`--reconcile` = NON-DESTRUCTIVE RECOVERY (middle rung).** When
+ *     `reconcile` is set AND the arbiter's `work/<slug>` exists + is ahead of
+ *     main, re-sync the hub mirror to the arbiter (a prune-fetch that clears
+ *     the stale-ref residue that historically resurrected a supposedly
+ *     `--reset`-ed branch) and RETRY the rebase of the kept branch onto latest
+ *     `<arbiter>/main` in a SCRATCH worktree (never touching the caller's
+ *     tree, `--force-with-lease` only, NEVER a bare force). Clean rebase =>
+ *     push the reconciled tip back to the arbiter and fall through to the
+ *     standard keep+continue path (lock released, branch preserved). Genuine
+ *     content conflict AFTER the clean mirror re-sync => item stays stuck,
+ *     branch UNTOUCHED (NEVER deleted), message references the deferred
+ *     mirror-side resolve follow-on and mentions `--reset` LAST as the
+ *     destructive last resort. Branch absent / not-ahead => fall through to
+ *     the default keep+continue path (which handles the fresh-claim case).
+ *   - **`--reset` = DISCARD + FRESH (destructive last resort).** When `reset`
+ *     is set, DELETE the remote `work/<slug>` branch on `arbiter` FIRST (+ drop
+ *     any stale local branch), THEN the backlog move. Delete-before-move
+ *     closes the claim-race window; a FAILED delete ABORTS (no backlog move)
+ *     so the item stays in needs-attention. The next claim then finds NO
+ *     arbiter branch and cuts fresh — no special claim-time logic.
  *   - **`-m "<note>"` = HANDOFF NOTE.** When `message` is set, APPEND a dated
  *     `## Requeue YYYY-MM-DD` section to the item BODY (append-only; accumulates
  *     over repeated requeues) for the next agent. Applies to BOTH modes.
@@ -406,6 +467,92 @@ async function readLocalItemLock(
 	return parseLockEntry(show.stdout);
 }
 
+/**
+ * Options the shared {@link deleteRemoteWorkBranchIfPresent} primitive consumes.
+ */
+export interface DeleteRemoteWorkBranchOptions {
+	/** Working clone whose remote `arbiter` points at the real arbiter. */
+	cwd: string;
+	/** The arbiter remote NAME in `cwd`. */
+	arbiter: string;
+	/** Bare slug (the branch is `work/task-<slug>`). */
+	slug: string;
+	/** Environment for child git processes. */
+	env?: NodeJS.ProcessEnv;
+}
+
+/** The three terminal states {@link deleteRemoteWorkBranchIfPresent} can report. */
+export type DeleteRemoteWorkBranchStatus =
+	/** The push --delete succeeded; the arbiter branch is gone. */
+	| 'deleted'
+	/**
+	 * The branch was already absent from the arbiter (`remote ref does not
+	 * exist` / `unable to delete`). Local refs may still have been cleaned up.
+	 * SEMANTICALLY equivalent to `deleted` for callers who only care that the
+	 * branch is not on the arbiter afterwards — idempotent no-op.
+	 */
+	| 'already-gone'
+	/** The push --delete failed for a reason OTHER than already-gone; caller decides. */
+	| 'failed';
+
+/** The outcome {@link deleteRemoteWorkBranchIfPresent} reports. */
+export interface DeleteRemoteWorkBranchResult {
+	/** The `work/<type>-<slug>` branch ref name that was targeted. */
+	branch: string;
+	/** See {@link DeleteRemoteWorkBranchStatus}. */
+	status: DeleteRemoteWorkBranchStatus;
+	/** The stderr from the failed `push --delete` (`''` on success/already-gone). */
+	stderr: string;
+}
+
+/**
+ * Delete the remote `work/task-<slug>` branch on the arbiter using the SAME
+ * write-through ordering the `requeue --reset` recovery verb uses:
+ *
+ *   1. Delete the LOCAL tracking ref (`refs/remotes/<arbiter>/work/<...>`)
+ *      — the ref the continue-detection path READS; if we skip this the
+ *      staleness silently resurrects a supposedly-discarded branch (verified in
+ *      `work/notes/observations/requeue-reset-does-not-prune-hub-mirror-stale-branch-ref.md`).
+ *   2. Delete any LOCAL head `work/<...>` (best-effort).
+ *   3. `git push <arbiter> --delete work/<...>` — the ARBITER delete, the
+ *      source of truth. A `remote ref does not exist` / `unable to delete`
+ *      stderr is TOLERATED as `already-gone` so the primitive is IDEMPOTENT
+ *      and safely callable on an item with no work branch (an observation, or
+ *      a task never built).
+ *
+ * Extracted from {@link returnToBacklog}'s `--reset` path so the apply-rung
+ * `kind: 'stuck'` answered `reset` verb (task
+ * `apply-resolve-reset-flag-discards-work-branch`) can dispatch through the
+ * SAME primitive without re-implementing branch deletion — the two callers
+ * MUST stay behaviourally identical (delete-before-move / delete-before-clear;
+ * local-first write-through; already-gone tolerance).
+ */
+export async function deleteRemoteWorkBranchIfPresent(
+	options: DeleteRemoteWorkBranchOptions,
+): Promise<DeleteRemoteWorkBranchResult> {
+	const {cwd, arbiter, slug, env} = options;
+	const branch = workBranchRef('task', slug);
+	await gitSoftAsync(
+		['update-ref', '-d', `refs/remotes/${arbiter}/${branch}`],
+		cwd,
+		env,
+	);
+	await gitSoftAsync(['branch', '-D', branch], cwd, env);
+	const del = await gitSoftAsync(
+		['push', arbiter, '--delete', branch],
+		cwd,
+		env,
+	);
+	if (del.status === 0) {
+		return {branch, status: 'deleted', stderr: ''};
+	}
+	const stderr = del.stderr.trim();
+	if (/remote ref does not exist|unable to delete/i.test(stderr)) {
+		return {branch, status: 'already-gone', stderr};
+	}
+	return {branch, status: 'failed', stderr};
+}
+
 export async function returnToBacklog(
 	options: ReturnToBacklogOptions,
 ): Promise<ReturnToBacklogResult> {
@@ -476,6 +623,67 @@ export async function returnToBacklog(
 		};
 	}
 
+	// `--reconcile`: the NON-DESTRUCTIVE recovery rung (task
+	// `requeue-reconcile-nondestructive-recovery-verb`, parent observation
+	// `rebase-conflict-on-continue-needs-nondestructive-recovery-not-reset`).
+	// When the kept `work/<slug>` exists + is ahead of `<arbiter>/main`, re-sync
+	// the mirror (prune-fetch — the exact step whose absence let
+	// `requeue-reset-does-not-prune-hub-mirror-stale-branch-ref` silently
+	// resurrect a stale branch) and RETRY the rebase in a SCRATCH worktree. Clean
+	// rebase => push the reconciled tip back (`--force-with-lease`, never bare
+	// force, WORK branch only — ADR §11) and fall through to the standard
+	// keep+continue path. Genuine content conflict AFTER the clean re-sync =>
+	// return with a message that LEADS with what happened, references the
+	// deferred mirror-side resolve path, and mentions `--reset` LAST as the
+	// destructive last resort. Branch absent / not-ahead => fall through to the
+	// default keep+continue path (which handles the fresh-claim case). NEVER
+	// deletes the remote branch — this verb's contract is "keep the work".
+	let reconciled: boolean | undefined;
+	if (options.reconcile) {
+		if (options.reset) {
+			return {
+				moved: false,
+				reasonNotMoved:
+					`requeue for '${slug}': --reconcile and --reset are mutually ` +
+					'exclusive (non-destructive recovery vs destructive last resort). ' +
+					'Pick one.',
+			};
+		}
+		const attempt = await attemptReconcile({
+			cwd,
+			slug,
+			arbiter,
+			env,
+			note,
+		});
+		if (attempt.kind === 'conflict') {
+			const branch = workBranchRef('task', slug);
+			const message =
+				`requeue --reconcile for '${slug}': re-synced the ${arbiter} mirror ` +
+				`and RETRIED the rebase of ${branch} onto latest ${arbiter}/main, but ` +
+				`the rebase still conflicts on genuine content (${attempt.detail}). The ` +
+				'kept branch is left UNTOUCHED on the arbiter (nothing deleted) and the ' +
+				'item is left stuck. A supported mirror-side "resolve against latest ' +
+				'main" command that fetches the kept branch into a scratch worktree, ' +
+				'rebases, and re-pushes is planned but not yet built (see observation ' +
+				'`rebase-conflict-on-continue-needs-nondestructive-recovery-not-reset`, ' +
+				'point 2 of its LIVE residue). LAST RESORT: `requeue --reset` ' +
+				'DESTRUCTIVELY discards the branch and starts fresh.';
+			note(message);
+			return {moved: false, reasonNotMoved: message};
+		}
+		if (attempt.kind === 'reconciled') {
+			reconciled = true;
+			note(
+				`Reconciled '${slug}': re-synced the ${arbiter} mirror, rebased the ` +
+					`kept ${workBranchRef('task', slug)} onto latest ${arbiter}/main, and ` +
+					'pushed the reconciled tip back (non-destructive; branch preserved).',
+			);
+		}
+		// 'no-branch' => fall through to the default keep+continue path (branch
+		// absent / not ahead — the existing default guard handles both cases).
+	}
+
 	// `--reset`: DELETE the remote work branch (before the backlog move). The
 	// deletion is WRITE-THROUGH: the LOCAL refs that drive continue-detection
 	// (`refs/remotes/<arbiter>/work/<slug>` AND any local head `work/<slug>`) are
@@ -489,49 +697,29 @@ export async function returnToBacklog(
 	// continue. Delete-before-move also closes the claim-race window.
 	let deletedRemoteBranch = false;
 	if (options.reset) {
-		const branch = workBranchRef('task', slug);
-		// LOCAL-FIRST: the tracking ref `branchAheadOf` reads (the one whose
-		// staleness today silently turns `--reset` into a no-op — verified live in
-		// `work/notes/observations/requeue-reset-does-not-prune-hub-mirror-stale-branch-ref.md`,
-		// where `--reset` deleted the arbiter branch but the local tracking ref
-		// survived and resurrected a "continue" on the next `do`). Both deletes
-		// are best-effort — their absence is fine, what matters is they are not
-		// LEFT BEHIND when the arbiter delete succeeds.
-		await gitSoftAsync(
-			['update-ref', '-d', `refs/remotes/${arbiter}/${branch}`],
-			cwd,
-			env,
-		);
-		await gitSoftAsync(['branch', '-D', branch], cwd, env);
-		// THEN the arbiter delete (explicit/guarded departure from the "never delete
-		// the remote branch" invariant; only on the `--reset` path, never the
-		// default).
-		const del = await gitSoftAsync(
-			['push', arbiter, '--delete', branch],
+		const dropped = await deleteRemoteWorkBranchIfPresent({
 			cwd,
+			arbiter,
+			slug,
 			env,
-		);
-		if (del.status !== 0) {
-			const stderr = del.stderr.trim();
-			// Tolerate "remote ref does not exist" (already gone): treat as deleted.
-			const alreadyGone = /remote ref does not exist|unable to delete/i.test(
-				stderr,
-			);
-			if (!alreadyGone) {
-				const message =
-					`requeue --reset for '${slug}': failed to delete the remote branch ` +
-					`${branch} on ${arbiter} (${stderr || 'unknown error'}); ` +
-					'aborting the requeue — item left in needs-attention (no backlog move). ' +
-					'The local tracking ref was already cleared (write-through ordering); ' +
-					'a subsequent fetch will restore it from the arbiter — the local store ' +
-					'is BEHIND the arbiter (self-healing), never AHEAD (which would drive a ' +
-					'stale continue).';
-				note(message);
-				return {moved: false, reasonNotMoved: message};
-			}
+		});
+		if (dropped.status === 'failed') {
+			const stderr = dropped.stderr;
+			const message =
+				`requeue --reset for '${slug}': failed to delete the remote branch ` +
+				`${dropped.branch} on ${arbiter} (${stderr || 'unknown error'}); ` +
+				'aborting the requeue — item left in needs-attention (no backlog move). ' +
+				'The local tracking ref was already cleared (write-through ordering); ' +
+				'a subsequent fetch will restore it from the arbiter — the local store ' +
+				'is BEHIND the arbiter (self-healing), never AHEAD (which would drive a ' +
+				'stale continue).';
+			note(message);
+			return {moved: false, reasonNotMoved: message};
 		}
 		deletedRemoteBranch = true;
-		note(`Deleted the remote branch ${branch} on ${arbiter} (--reset).`);
+		note(
+			`Deleted the remote branch ${dropped.branch} on ${arbiter} (--reset).`,
+		);
 	}
 
 	// DEFAULT (keep+continue) REQUEUE-SAFETY GUARD: a claimable item's continue-
@@ -543,20 +731,45 @@ export async function returnToBacklog(
 	// discards the branch by design).
 	if (!options.reset) {
 		const branch = workBranchRef('task', slug);
-		const onArbiter = branchAheadOf(
+		// Split the guard into TWO cases (task
+		// `default-requeue-succeeds-when-no-work-branch-exists`):
+		//   (a) the arbiter branch does NOT EXIST at all (never pushed, or a prior
+		//       `--reset` already deleted it) — there is NO continue-branch a future
+		//       worker would resume from, so the guard's precondition is vacuously
+		//       satisfied. Degrade gracefully to the same effective outcome as
+		//       `--reset` (nothing to discard) and proceed with the keep+continue
+		//       backlog move: no arbiter delete (there is nothing to delete), no
+		//       forcing the caller into the destructive `--reset` verb.
+		//   (b) the arbiter branch EXISTS but is NOT ahead of `<arbiter>/main` — a
+		//       real anomaly (the continue-branch would resume from a state already
+		//       reachable from main). Preserve today's refusal so the case surfaces.
+		const tip = gitSoftRun(
+			['rev-parse', '--verify', '--quiet', `${arbiter}/${branch}^{commit}`],
 			cwd,
-			`${arbiter}/${branch}`,
-			`${arbiter}/main`,
 			env,
 		);
-		if (!onArbiter) {
-			const message =
-				`the work branch ${branch} isn't on ${arbiter} (the continue ` +
-				`branch a cross-machine worker would resume from) — push it first, or ` +
-				'`requeue --reset` to discard and start fresh. Item left stuck (lock not ' +
-				'released).';
-			note(message);
-			return {moved: false, reasonNotMoved: message};
+		const arbiterBranchExists = tip.status === 0 && tip.stdout.trim() !== '';
+		if (!arbiterBranchExists) {
+			note(
+				`'${slug}' has no work branch on ${arbiter} — requeueing to backlog ` +
+					'for a FRESH claim (nothing to continue from; no --reset needed).',
+			);
+		} else {
+			const onArbiter = branchAheadOf(
+				cwd,
+				`${arbiter}/${branch}`,
+				`${arbiter}/main`,
+				env,
+			);
+			if (!onArbiter) {
+				const message =
+					`the work branch ${branch} isn't on ${arbiter} (the continue ` +
+					`branch a cross-machine worker would resume from) — push it first, or ` +
+					'`requeue --reset` to discard and start fresh. Item left stuck (lock not ' +
+					'released).';
+				note(message);
+				return {moved: false, reasonNotMoved: message};
+			}
 		}
 	}
 
@@ -648,7 +861,130 @@ export async function returnToBacklog(
 	note(
 		`Returned '${slug}' to backlog (released the lock; body rests in pool).`,
 	);
-	return {moved: true, commitMessage, deletedRemoteBranch};
+	return {moved: true, commitMessage, deletedRemoteBranch, reconciled};
+}
+
+/**
+ * The outcome of an in-progress `--reconcile` attempt (task
+ * `requeue-reconcile-nondestructive-recovery-verb`):
+ *   - `'reconciled'` — mirror re-synced, rebase onto latest `<arbiter>/main`
+ *     was clean AND the reconciled tip was pushed back to the arbiter. The
+ *     caller falls through to the default keep+continue path.
+ *   - `'no-branch'` — the arbiter's `work/<slug>` is absent or not ahead of
+ *     main after the re-sync. Nothing to reconcile; the caller falls through
+ *     to the default keep+continue path (which itself handles the fresh-claim
+ *     case gracefully).
+ *   - `'conflict'` — the rebase after the CLEAN mirror re-sync still
+ *     conflicted on genuine content, or the reconciled-tip push failed. The
+ *     branch is left untouched on the arbiter; the caller returns a stuck
+ *     message that leads with what was tried and mentions `--reset` LAST.
+ */
+type ReconcileAttempt =
+	| {kind: 'reconciled'}
+	| {kind: 'no-branch'}
+	| {kind: 'conflict'; detail: string};
+
+/**
+ * The `--reconcile` recovery attempt — the non-destructive middle rung of the
+ * `requeue` escalation ladder. Runs in a SCRATCH worktree so the caller's cwd
+ * tree/HEAD/index is NEVER touched (parity with the tree-less move machinery):
+ *
+ *   1. **Re-sync the mirror.** `git fetch --prune <arbiter>` on the caller's
+ *      cwd — the exact prune step whose absence let
+ *      `requeue-reset-does-not-prune-hub-mirror-stale-branch-ref` silently
+ *      resurrect a supposedly-`--reset`-ed branch. This clears the stale
+ *      remote-tracking residue that historically fooled the retry.
+ *   2. **Guard.** The arbiter's `work/<slug>` must EXIST + be ahead of main
+ *      (via {@link branchAheadOf} on the freshly-fetched
+ *      `<arbiter>/work/<slug>` vs `<arbiter>/main`). Absent / not-ahead =>
+ *      `'no-branch'` and the caller falls through to the default keep+continue
+ *      path.
+ *   3. **Rebase in a scratch worktree.** `git worktree add --detach <scratch>
+ *      <arbiter>/work/<slug>` and run {@link rebaseContinuedBranchOntoMain}
+ *      against `<arbiter>/main`. A CLEAN rebase is a full non-destructive fix;
+ *      a CONFLICT is `--abort`ed (never auto-resolved) => `'conflict'`.
+ *   4. **Push the reconciled tip back.** `git push <arbiter> HEAD:work/<slug>
+ *      --force-with-lease=work/<slug>:<observed-arbiter-tip>` from the scratch
+ *      worktree. `--force-with-lease` ONLY, NEVER bare `--force`, NEVER
+ *      `:main`, the WORK branch ONLY (ADR §11). A rejected push (stale lease
+ *      or otherwise) => `'conflict'` — non-destructive by construction, the
+ *      user can retry.
+ *
+ * Cleanup of the scratch worktree is best-effort in a `finally` (never fails
+ * the reconcile on cleanup).
+ */
+async function attemptReconcile(params: {
+	cwd: string;
+	slug: string;
+	arbiter: string;
+	env: NodeJS.ProcessEnv | undefined;
+	note: (message: string) => void;
+}): Promise<ReconcileAttempt> {
+	const {cwd, slug, arbiter, env, note} = params;
+	const branch = workBranchRef('task', slug);
+	const arbBranchRef = `refs/remotes/${arbiter}/${branch}`;
+	const arbMainRef = `refs/remotes/${arbiter}/main`;
+
+	// 1. Re-sync the mirror to the arbiter (prune-fetch clears stale refs).
+	await gitSoftAsync(['fetch', '--prune', '--quiet', arbiter], cwd, env);
+
+	// 2. Guard: branch must exist + be ahead of main.
+	if (!branchAheadOf(cwd, arbBranchRef, arbMainRef, env)) {
+		return {kind: 'no-branch'};
+	}
+
+	// 3. Scratch worktree — the caller's tree is NEVER touched.
+	const worktree = join(
+		tmpdir(),
+		`dorfl-reconcile-${slug}-${process.pid}-${Date.now()}`,
+	);
+	const wtCreate = gitSoftRun(
+		['worktree', 'add', '--quiet', '--detach', worktree, arbBranchRef],
+		cwd,
+		env,
+	);
+	if (wtCreate.status !== 0) {
+		return {
+			kind: 'conflict',
+			detail: `could not create scratch worktree (${wtCreate.stderr.trim() || `exit ${wtCreate.status}`})`,
+		};
+	}
+	try {
+		const rebase = rebaseContinuedBranchOntoMain(worktree, arbMainRef, env);
+		if (rebase.kind === 'conflict') {
+			return {kind: 'conflict', detail: 'rebase conflicted after re-sync'};
+		}
+		// 4. Push the reconciled tip back (`--force-with-lease`, WORK branch only).
+		const observedTip = gitSoftRun(
+			['rev-parse', '--verify', '--quiet', `${arbBranchRef}^{commit}`],
+			cwd,
+			env,
+		).stdout.trim();
+		const lease =
+			observedTip === '' ? `${branch}:` : `${branch}:${observedTip}`;
+		const push = gitSoftRun(
+			[
+				'push',
+				arbiter,
+				`HEAD:refs/heads/${branch}`,
+				`--force-with-lease=${lease}`,
+			],
+			worktree,
+			env,
+		);
+		if (push.status !== 0) {
+			return {
+				kind: 'conflict',
+				detail: `push of reconciled tip rejected (${push.stderr.trim() || `exit ${push.status}`})`,
+			};
+		}
+		// Advance the local remote-tracking ref so subsequent reads see the truth.
+		await gitSoftAsync(['fetch', '--quiet', arbiter], cwd, env);
+		void note;
+		return {kind: 'reconciled'};
+	} finally {
+		await gitSoftAsync(['worktree', 'remove', '--force', worktree], cwd, env);
+	}
 }
 
 /**
@@ -656,13 +992,13 @@ export async function returnToBacklog(
  * `staging-pool-position-gate-and-trust-model`, task
  * `pre-backlog-staging-folder-and-promote-step-a`, governing ADR
  * `placement-is-runner-deterministic-humanonly-is-agent-judgement`). Moves
- * `work/pre-backlog/<slug>.md → work/backlog/<slug>.md` as a durable `main`
+ * `work/tasks/backlog/<slug>.md → work/tasks/ready/<slug>.md` as a durable `main`
  * move, the same category as {@link returnToBacklog} (tree-less CAS via
  * {@link runTreelessLedgerMove}). After this transition the task is in the
  * pool and claimable.
  *
  * **RUNNER/human-owned.** There is no agent-facing path that performs this:
- * the agent's tasking output lands STAGED in `work/pre-backlog/` (the runner's
+ * the agent's tasking output lands STAGED in `work/tasks/backlog/` (the runner's
  * deterministic placement decision), and only a runner/human invocation moves
  * it into the pool. The agent does no git here, as everywhere.
  *
@@ -670,7 +1006,7 @@ export async function returnToBacklog(
  * lands; the sole strategy publishes to `<arbiter>/main`. Like
  * {@link returnToBacklog} the tree-less CAS needs a ref to push to, so an
  * `arbiter` is REQUIRED. NEVER throws for the expected
- * "not in pre-backlog/" / contention-exhausted cases — it returns
+ * "not in tasks/backlog/" / contention-exhausted cases — it returns
  * `{moved: false, reasonNotMoved}` so callers can branch cleanly.
  */
 export interface PromoteFromPreBacklogOptions {
@@ -699,7 +1035,7 @@ export interface PromoteFromPreBacklogResult {
 	moved: boolean;
 	/** When `moved`, the committed transition message. */
 	commitMessage?: string;
-	/** When NOT moved, why (no such pre-backlog item, already in backlog, contention). */
+	/** When NOT moved, why (no such staged item, already in the pool, contention). */
 	reasonNotMoved?: string;
 }
 
@@ -789,14 +1125,16 @@ export async function promoteFromPreBacklog(
 			).status === 0;
 		if (!hasSource && !hasDest) {
 			const message =
-				`'${slug}' is not staged in work/pre-backlog/ on ${arbiter}/main (and not ` +
-				'already in work/backlog/) — nothing to promote (wrong slug, or never ' +
-				'staged?).';
+				`'${slug}' is not staged in ${workFolderPrefix('tasks-backlog')} on ${arbiter}/main ` +
+				`(and not already in ${workFolderPrefix('tasks-ready')}) — nothing to promote ` +
+				'(wrong slug, or never staged?).';
 			note(message);
 			return {moved: false, reasonNotMoved: message};
 		}
 
-		const commitMessage = `chore(${slug}): promote work/pre-backlog/ -> work/backlog/`;
+		const commitMessage = `chore(${slug}): promote ${workFolderPrefix(
+			'tasks-backlog',
+		)} -> ${workFolderPrefix('tasks-ready')}`;
 		const moved = await runTreelessLedgerMove({
 			cwd,
 			slug,
@@ -824,7 +1162,7 @@ export async function promoteFromPreBacklog(
 					base,
 					sourceRel,
 					destRel,
-					// The body is carried byte-for-byte from pre-backlog into the
+					// The body is carried byte-for-byte from tasks/backlog into the
 					// pool — promotion is a placement decision, not a content transform.
 					transformBody: (body) => body,
 					commitMessage,
@@ -834,14 +1172,14 @@ export async function promoteFromPreBacklog(
 			},
 		});
 		if (moved) {
-			note(`Promoted '${slug}' from pre-backlog to backlog (claimable).`);
+			note(`Promoted '${slug}' from tasks/backlog to tasks/ready (claimable).`);
 			return {moved: true, commitMessage};
 		}
 
 		const message =
 			`promote for '${slug}': the arbiter's main kept moving (contended) after ` +
-			`${TREELESS_CONTENTION_ATTEMPTS} attempts — item left in pre-backlog (no ` +
-			'move). Try again shortly.';
+			`${TREELESS_CONTENTION_ATTEMPTS} attempts — item left in tasks/backlog ` +
+			'(no move). Try again shortly.';
 		note(message);
 		return {moved: false, reasonNotMoved: message};
 	} finally {
@@ -863,7 +1201,7 @@ export async function promoteFromPreBacklog(
  * the auto-task pool, not the gates).
  *
  * **RUNNER/human-owned.** There is no agent-facing path that performs this:
- * `intake`'s `prd` dispatch lands the spec STAGED in `work/specs/proposed/` (the
+ * `intake`'s `spec` dispatch lands the spec STAGED in `work/specs/proposed/` (the
  * runner's deterministic placement decision), and only a runner/human
  * invocation moves it into the pool. The agent does no git here, as
  * everywhere; this function is not reachable from any agent surface.
@@ -937,7 +1275,7 @@ export async function promoteFromPreSpec(
 	// (spec `prd-to-spec-vocabulary-cutover-and-migration-command`): the lock
 	// identity is `spec:${slug}` to match the `spec-<slug>` entry the tasking/apply
 	// path now acquires (`tasking.ts` releases under `spec:${slug}`); a stale
-	// `prd:${slug}` here would key a DIFFERENT ref and break the mutual exclusion.
+	// ''prd:${slug}'' here would key a DIFFERENT ref and break the mutual exclusion.
 	// Loss / crash semantics mirror the task case.
 	const item = `spec:${slug}`;
 	const acquired = await acquireItemLock({
@@ -1036,9 +1374,9 @@ export async function promoteFromPreSpec(
 	}
 }
 
-/** One staged item awaiting promotion (a task in `pre-backlog/` or a spec in `specs/proposed/`). */
+/** One staged item awaiting promotion (a task in `tasks/backlog/` or a spec in `specs/proposed/`). */
 export interface PromotableItem {
-	/** `'task'` (staged in `work/pre-backlog/`) or `'spec'` (staged in `work/specs/proposed/`). */
+	/** `'task'` (staged in `work/tasks/backlog/`) or `'spec'` (staged in `work/specs/proposed/`). */
 	namespace: 'task' | 'spec';
 	/** The slug (filename minus `.md`). */
 	slug: string;
@@ -1062,7 +1400,7 @@ export interface ListPromotableResult {
 
 /**
  * LIST every staged item awaiting a runner/human promotion — the tasks in
- * `work/pre-backlog/` and the prds in `work/specs/proposed/` on `<arbiter>/main` (the
+ * `work/tasks/backlog/` and the prds in `work/specs/proposed/` on `<arbiter>/main` (the
  * discovery half of the `promote` verb, so `promote` with no argument answers
  * "what is staged waiting for me?"). It reads the ARBITER's truth (a fetch + a
  * tree read), NOT the local working tree (which may be stale) — the same source
@@ -1341,6 +1679,441 @@ function prepareTreelessMoveCommit(params: {
 /** The heading that opens an appended requeue handoff note in the item body. */
 const REQUEUE_HEADING_PREFIX = '## Requeue';
 
+// --- Tree-less SURFACE primitive (PR-1, spec
+// `surface-stuck-as-questions-and-retire-stuck-lock-state`, task
+// `bounce-surfaces-stuck-sidecar-and-releases-lock`) --------------------
+
+/**
+ * PR-1 ADDITIVE primitive (task `bounce-surfaces-stuck-sidecar-and-releases-lock`).
+ * The 2-file SIBLING of {@link prepareTreelessMoveCommit}: pure git plumbing
+ * (`hash-object` / scratch-index `update-index` / `write-tree` /
+ * `commit-tree`, NEVER touches the caller's index/HEAD/working tree) that in
+ * ONE commit off {@link base} both
+ *
+ *   1. writes or appends to the item's `work/questions/<type>-<slug>.md`
+ *      sidecar (see {@link sidecarPathFor}) a `stuck`-kind entry carrying the
+ *      bounce {@link reason} plus any agent-surfaced {@link questions}, and
+ *   2. sets `needsAnswers: true` on the item body at {@link itemPath} (via
+ *      {@link setNeedsAnswersMarker}).
+ *
+ * The current sidecar (if any) and the current item body are read as BLOBS off
+ * `<arbiter>/main` (via {@link catBlob}) — no working tree required and no
+ * dependency on the cwd's `HEAD` matching `main`. That is what makes this the
+ * tree-less path's surface primitive: a `applyTreelessNeedsAttentionTransition`
+ * caller (`continue-push-failure` / rebase-conflict) has NO writable-`main`
+ * checkout, so `persistSurfacedQuestions` (working-tree bound) cannot be reused;
+ * the pure CONTENT builders (`newSidecar` / `appendQuestions` /
+ * `serialiseSidecar` / `setNeedsAnswersMarker`) ARE reused, only the commit
+ * mechanism differs (spec decision #7).
+ *
+ * Returns the throwaway ref + commit sha, exactly like {@link
+ * prepareTreelessMoveCommit}, so the SAME {@link runTreelessLedgerMove} CAS loop
+ * publishes the surface commit through the shared write seam. The
+ * surface-first / release-second ordering + `main`-authoritative crash-safety
+ * (spec decision #4) come FREE from routing through that loop — the caller wires
+ * the release into a `finally` AFTER a successful publish (see the harness
+ * {@link surfaceStuckToNeedsAttention}).
+ *
+ * DECISION — sidecar entry shape for a reason-only bounce (build-time, PR-1):
+ * every bounce always appends ONE engine-authored `stuck`-kind envelope entry
+ * whose `question` names the item and whose `context` is the {@link reason}
+ * prose, THEN any {@link questions} the agent surfaced. So a reason-only bounce
+ * (no agent questions) still surfaces exactly ONE entry a human can answer, and
+ * the agent's own questions (when present) are appended AFTER it, verbatim. The
+ * envelope entry is what turns a raw exit reason into a human-drainable
+ * question; the extra entries are the LLM prose the spec's decision #2 keeps
+ * untouched. Alternative considered — treating an empty `questions` array as a
+ * NO-OP surface — REJECTED because that is the spec's `stuck` retirement
+ * problem all over again (a bounced item with no on-`main` outcome).
+ * Alternative considered — dropping the envelope when agent questions are given
+ * — REJECTED because the reason is engine-authored ground truth; the agent's
+ * questions are advisory prose ABOVE it, not a replacement for it.
+ *
+ * PR-1 boundary: this primitive is EXERCISED BY TESTS ONLY; it is NOT yet
+ * called from any bounce seam. Wiring `applyNeedsAttentionTransition` /
+ * `applyTreelessNeedsAttentionTransition` to it — and migrating the existing
+ * `stuckLockOnArbiter(...).toBe(true)` assertions — is the follow-up PR-2 task
+ * `bounce-atomic-cutover-retire-stuck-lock`.
+ */
+export function prepareTreelessSurfaceCommit(params: {
+	/** The origin cwd whose object store the plumbing writes into (never a target). */
+	cwd: string;
+	/** The slug (used only to name the throwaway ref). */
+	slug: string;
+	/** The namespaced item identity (e.g. `task:foo`); drives the sidecar path. */
+	item: string;
+	/** The item body's on-`main` path (e.g. `work/tasks/ready/foo.md`). */
+	itemPath: string;
+	/** The base commit (`<arbiter>/main`) the surface commit parents on. */
+	base: string;
+	/** The bounce reason (envelope entry's context). */
+	reason: string;
+	/** Any agent-surfaced questions to append after the envelope. */
+	questions?: NewQuestion[];
+	/**
+	 * OPTIONAL engine-authored envelope entry OVERRIDE. When provided, replaces
+	 * the built-in generic `"<item> was bounced — how should we proceed?"`
+	 * envelope with a caller-supplied one — the seam the empty-diff bounce path
+	 * uses to guarantee a DISPOSE-DEFAULTED disposition question exists on the
+	 * surfaced sidecar (spec `surface-stuck-as-questions-and-retire-stuck-lock-state`
+	 * resolved decision #2, task
+	 * `empty-diff-bounce-surfaces-dispose-defaulted-question`). The override still
+	 * defaults its `kind` to `'stuck'` when unset. `reason` (envelope context)
+	 * remains the caller-owned prose; the override lets the caller set the
+	 * envelope's `question` + `default` so the human sees a one-glance
+	 * dispose/cancel prompt instead of the generic "how should we proceed?"
+	 * catch-all. When absent, the built-in envelope is used (the reason-only
+	 * bounce shape).
+	 */
+	envelope?: NewQuestion;
+	/** The commit subject for the surface commit. */
+	commitMessage: string;
+	/** The throwaway ref namespace (`refs/dorfl/<refNamespace>/<slug>`). */
+	refNamespace: string;
+	env: NodeJS.ProcessEnv | undefined;
+}): {ref: string; commit: string} {
+	const {
+		cwd,
+		slug,
+		item,
+		itemPath,
+		base,
+		reason,
+		questions,
+		envelope: envelopeOverride,
+		commitMessage,
+		refNamespace,
+		env,
+	} = params;
+
+	const sidecarPath = sidecarPathFor(item);
+
+	// Read the item body off `main` as a BLOB — never off the cwd working tree,
+	// which the tree-less caller does not have on `main`. `catBlob` throws when
+	// the path is not tracked, which is the honest signal: the tree-less bounce
+	// only fires against an item whose body already rests on `main` (the caller's
+	// plan should short-circuit `missing` beforehand).
+	const itemBody = catBlob(`${base}:${itemPath}`, cwd, env);
+	const flagged = setNeedsAnswersMarker(itemBody, true);
+
+	// Defense-in-depth (the `sidecar-without-needsAnswers` guard, mirrored from
+	// `persistSurfacedQuestions`): if the marker did not actually parse back as
+	// `true`, refuse to write the sidecar rather than tear the
+	// `needsAnswers ⟺ sidecar` invariant.
+	if (parseFrontmatter(flagged).needsAnswers !== true) {
+		throw new Error(
+			`prepareTreelessSurfaceCommit: could not set needsAnswers:true on '${itemPath}' ` +
+				`for '${item}' — refusing to surface without the flag.`,
+		);
+	}
+
+	// Compose the entries: an engine-authored envelope carrying the reason, then
+	// any agent-surfaced questions (stamped `stuck`-kind if the caller left the
+	// kind unset — this IS the stuck-surface path). Callers may OVERRIDE the
+	// envelope (e.g. the empty-diff path swaps in a dispose-defaulted question);
+	// the override still defaults `kind` to `stuck` and `context` to the bounce
+	// reason when the override leaves them unset (the caller can restate the
+	// reason in the envelope prose without duplicating it in `context`).
+	const envelope: NewQuestion = envelopeOverride
+		? {
+				kind: envelopeOverride.kind ?? 'stuck',
+				question: envelopeOverride.question,
+				context: envelopeOverride.context ?? reason,
+				...(envelopeOverride.default !== undefined
+					? {default: envelopeOverride.default}
+					: {}),
+			}
+		: {
+				question: `'${item}' was bounced — how should we proceed?`,
+				context: reason,
+				kind: 'stuck',
+			};
+	const surfaced: NewQuestion[] = (questions ?? []).map((q) => ({
+		...q,
+		kind: q.kind ?? 'stuck',
+	}));
+	const additions: NewQuestion[] = [envelope, ...surfaced];
+
+	// APPEND to an existing sidecar on `main` (never overwrite) or CREATE it
+	// first-pass — the same append-never-overwrite rule the working-tree surface
+	// path enforces. Read the current sidecar off `main` as a BLOB.
+	const sidecarExists = pathInCommit(base, sidecarPath, cwd, env);
+	const model = sidecarExists
+		? appendQuestions(
+				parseSidecar(catBlob(`${base}:${sidecarPath}`, cwd, env)),
+				additions,
+			)
+		: newSidecar(item, additions);
+	const sidecarContent = serialiseSidecar(model);
+
+	// Hash both blobs INTO the cwd's object store (no working tree write).
+	const itemBlob = hashObject(flagged, cwd, env);
+	const sidecarBlob = hashObject(sidecarContent, cwd, env);
+
+	// A scratch index so `read-tree` / `update-index` never touch the caller's
+	// index. `--add --cacheinfo` both ADDS a new entry and REPLACES an existing
+	// one (so a re-surface that rewrites the sidecar path is a no-op replace).
+	const scratchIndex = join(
+		tmpdir(),
+		`dorfl-${refNamespace}-${process.pid}-${Date.now()}.index`,
+	);
+	const withIndex: NodeJS.ProcessEnv = {
+		...(env ?? process.env),
+		GIT_INDEX_FILE: scratchIndex,
+	};
+	try {
+		gitHard(['read-tree', base], cwd, withIndex);
+		gitHard(
+			[
+				'update-index',
+				'--add',
+				'--cacheinfo',
+				`100644,${itemBlob},${itemPath}`,
+			],
+			cwd,
+			withIndex,
+		);
+		gitHard(
+			[
+				'update-index',
+				'--add',
+				'--cacheinfo',
+				`100644,${sidecarBlob},${sidecarPath}`,
+			],
+			cwd,
+			withIndex,
+		);
+		const tree = runHard(['write-tree'], cwd, withIndex).stdout.trim();
+		const commit = runHard(
+			['commit-tree', tree, '-p', base, '-m', commitMessage],
+			cwd,
+			env,
+		).stdout.trim();
+		const ref = `refs/dorfl/${refNamespace}/${slug}`;
+		gitHard(['update-ref', ref, commit], cwd, env);
+		return {ref, commit};
+	} finally {
+		rmSync(scratchIndex, {force: true});
+	}
+}
+
+export interface SurfaceStuckToNeedsAttentionOptions {
+	/**
+	 * The working clone the move is ORIGINATED from — purely the ORIGIN SOURCE
+	 * (it resolves the arbiter remote + holds the object store the plumbing
+	 * writes into), NEVER a write TARGET. Tree-less: the cwd index/HEAD/working
+	 * tree are never touched.
+	 */
+	cwd: string;
+	/** The slug of the item to surface as a stuck question. */
+	slug: string;
+	/**
+	 * The item body's on-`main` path (e.g. `work/tasks/ready/foo.md`). Provided
+	 * by the caller (parity with `persistSurfacedQuestions`). PR-2a made this
+	 * OPTIONAL: when absent the harness invokes {@link resolveBounceItemBodyPathOnMain}
+	 * to PROBE `<arbiter>/main` in the D1 order for the item's namespace
+	 * (task/spec/observation). A body-absent probe (item body never landed on
+	 * `main` — e.g. a claim that lost/raced) is a CLEAN NO-OP surface that STILL
+	 * RELEASES the lock: never throw, never leave a held lock, never drop the
+	 * bounce silently to a dead end.
+	 */
+	itemPath?: string;
+	/** The namespaced item identity. Defaults to `task:${slug}`. */
+	item?: string;
+	/** Why the item is stuck (bounce reason — envelope entry's context). */
+	reason: string;
+	/** Any questions the agent surfaced (appended after the envelope). */
+	questions?: NewQuestion[];
+	/**
+	 * OPTIONAL engine-authored envelope override, forwarded to
+	 * {@link prepareTreelessSurfaceCommit}. The empty-diff bounce path uses this
+	 * to guarantee the first surfaced entry is a DISPOSE-DEFAULTED disposition
+	 * question (task `empty-diff-bounce-surfaces-dispose-defaulted-question`,
+	 * spec resolved decision #2). Absent ⇒ the built-in generic
+	 * "how should we proceed?" envelope (a reason-only bounce).
+	 */
+	envelope?: NewQuestion;
+	/** The arbiter remote the surface commit is CAS-published to. REQUIRED. */
+	arbiter: string;
+	env?: NodeJS.ProcessEnv;
+	note?: (message: string) => void;
+}
+
+export interface SurfaceStuckToNeedsAttentionResult {
+	/** True iff the surface commit landed on `<arbiter>/main`. */
+	surfaced: boolean;
+	/** True iff the per-item lock ref was released. On a body-absent probe
+	 * (see {@link bodyAbsent}) the lock is STILL released — the bounce cannot
+	 * silently strand a held lock over an item with no `main` body. */
+	released: boolean;
+	/** When NOT surfaced, why (missing item, contention exhausted, body-absent probe). */
+	reasonNotSurfaced?: string;
+	/** True iff the D1 probe found no body on `<arbiter>/main` for this item
+	 * (task: `tasks/ready` then `tasks/backlog`; spec: `specs/ready` then
+	 * `specs/proposed`; observation: `notes/observations`). In this case
+	 * {@link surfaced} is false but {@link released} is true — the lock is
+	 * always released to prevent a dead-end held lock. */
+	bodyAbsent?: boolean;
+}
+
+/**
+ * The PR-1 thin HARNESS around {@link prepareTreelessSurfaceCommit}: run it
+ * through the EXISTING {@link runTreelessLedgerMove} CAS loop, then release the
+ * per-item lock. Ordering is LOAD-BEARING and INHERITED from that harness —
+ * the surface commit lands on `<arbiter>/main` FIRST, and the lock release only
+ * fires on a successful publish. `main` is authoritative on crash recovery
+ * (spec decision #4).
+ *
+ * PR-1 boundary: this is EXERCISED BY TESTS ONLY. Wiring the seams to call it
+ * is the PR-2 task `bounce-atomic-cutover-retire-stuck-lock`.
+ */
+export async function surfaceStuckToNeedsAttention(
+	options: SurfaceStuckToNeedsAttentionOptions,
+): Promise<SurfaceStuckToNeedsAttentionResult> {
+	const note = options.note ?? (() => {});
+	// Merge of #364 (envelope) + PR-2a (itemPath is re-declared as `let` below for
+	// the D1 probe fallback, so it must NOT be in this const destructure).
+	const {cwd, slug, reason, questions, envelope, arbiter, env} = options;
+	const item = options.item ?? `task:${slug}`;
+
+	// PR-2a D1 body-path probe: when the caller does not name an on-`main`
+	// body path, PROBE `<arbiter>/main` in a fixed order per namespace
+	// (task/spec/observation). A body-absent probe is a CLEAN NO-OP surface
+	// that STILL releases the lock — never leave a bounce as a dead-end held
+	// lock.
+	let itemPath = options.itemPath;
+	if (itemPath === undefined) {
+		const probed = await resolveBounceItemBodyPathOnMain({
+			cwd,
+			item,
+			arbiter,
+			env,
+		});
+		if (probed === undefined) {
+			// Body-absent: skip the surface commit entirely and STILL release the
+			// lock (idempotent). Signal the distinction on the result so a caller
+			// can tell a body-absent no-op apart from a `missing` plan on a
+			// caller-provided itemPath.
+			const rel = await releaseItemLock({item, cwd, arbiter, env});
+			const released = rel.outcome === 'released' || rel.outcome === 'not-held';
+			return {
+				surfaced: false,
+				released,
+				bodyAbsent: true,
+				reasonNotSurfaced:
+					`no body for '${item}' on ${arbiter}/main (probed the D1 ` +
+					'candidates in order) — surface skipped as a clean no-op; the ' +
+					'lock was still released to avoid a dead-end held lock.',
+			};
+		}
+		itemPath = probed;
+	}
+
+	const resolvedItemPath = itemPath;
+	const surfaced = await runTreelessLedgerMove({
+		cwd,
+		slug,
+		arbiter,
+		kind: 'needs-attention',
+		onContended: 'surface',
+		explicitMainRefspec: true,
+		env,
+		note,
+		plan: (base) => {
+			if (!pathInCommit(base, resolvedItemPath, cwd, env)) {
+				return 'missing';
+			}
+			return prepareTreelessSurfaceCommit({
+				cwd,
+				slug,
+				item,
+				itemPath: resolvedItemPath,
+				base,
+				reason,
+				questions,
+				envelope,
+				commitMessage: `surface ${item} (stuck): ${reason}`,
+				refNamespace: 'surface-stuck',
+				env,
+			});
+		},
+	});
+
+	if (!surfaced) {
+		return {
+			surfaced: false,
+			released: false,
+			reasonNotSurfaced:
+				`surface for '${item}' did not land on ${arbiter}/main ` +
+				'(item missing on main, or contention exhausted after retries).',
+		};
+	}
+
+	// Surface-first / release-second: only reach here on a successful publish.
+	const rel = await releaseItemLock({item, cwd, arbiter, env});
+	const released = rel.outcome === 'released' || rel.outcome === 'not-held';
+	return {surfaced: true, released};
+}
+
+/**
+ * The D1 body-path probe (PR-2a task `bounce-atomic-cutover-retire-stuck-lock`,
+ * spec `surface-stuck-as-questions-and-retire-stuck-lock-state`, decision D1):
+ * resolve the item's on-`main` body path by probing `<arbiter>/main` in a
+ * FIXED order per namespace:
+ *   - task: `work/tasks/ready/<slug>.md` then `work/tasks/backlog/<slug>.md`.
+ *   - spec: `work/specs/ready/<slug>.md` then `work/specs/proposed/<slug>.md`.
+ *   - observation: `work/notes/observations/<slug>.md`.
+ *
+ * Returns the first candidate that EXISTS on `<arbiter>/main`, or `undefined`
+ * when no candidate exists (a bounce for an item whose body never landed on
+ * `main`). The caller MUST handle `undefined` by STILL releasing the lock —
+ * never leave a held lock over a body-absent item.
+ *
+ * The probe fetches `<arbiter>/main` with an EXPLICIT refspec (the
+ * `runTreelessLedgerMove` pattern) so a job-worktree with a narrower default
+ * fetch refspec still resolves `<arbiter>/main` reliably.
+ */
+export async function resolveBounceItemBodyPathOnMain(params: {
+	cwd: string;
+	item: string;
+	arbiter: string;
+	env?: NodeJS.ProcessEnv;
+}): Promise<string | undefined> {
+	const {cwd, item, arbiter, env} = params;
+	const {type, slug} = resolveSidecarIdentity(item);
+	await gitSoftAsync(
+		[
+			'fetch',
+			'--quiet',
+			arbiter,
+			`+refs/heads/main:refs/remotes/${arbiter}/main`,
+		],
+		cwd,
+		env,
+	);
+	const base = `${arbiter}/main`;
+	const folders = BOUNCE_BODY_PROBE_ORDER[type];
+	for (const folder of folders) {
+		const rel = workItemRel(folder, `${slug}.md`);
+		if (pathInCommit(base, rel, cwd, env)) {
+			return rel;
+		}
+	}
+	return undefined;
+}
+
+/** The FIXED per-namespace probe order for {@link resolveBounceItemBodyPathOnMain}
+ * (D1): the FIRST candidate that exists on `<arbiter>/main` is the item's body
+ * path. The ordering encodes the working assumption that a claimed/in-flight
+ * item is in `ready/` and a not-yet-promoted item is in `backlog/`
+ * (spec-tasked/proposed for a spec); an observation has one location.
+ * Callers with an explicit `itemPath` bypass this probe entirely. */
+const BOUNCE_BODY_PROBE_ORDER: Record<SidecarType, readonly WorkFolderKey[]> = {
+	task: ['tasks-ready', 'tasks-backlog'],
+	spec: ['specs-ready', 'specs-proposed'],
+	observation: ['observations'],
+};
+
 /**
  * Append a dated `## Requeue YYYY-MM-DD` handoff section to an item body's TEXT
  * (append-only — never overwrites; repeated requeues accumulate a handoff log).