dorfl 0.1.2 → 0.2.1

package/dist/needs-attention.js

@@ -3,10 +3,12 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { workFolderPrefix, workFolderRel, workItemRel, isWorkItemFile, } from './work-layout.js';
 import { run, runAsync } from './git.js';
-import { branchAheadOf } from './continue-branch.js';
+import { branchAheadOf, rebaseContinuedBranchOntoMain, } from './continue-branch.js';
 import { acquireItemLock, releaseItemLock, readItemLock, itemLockRef, lockEntryFor, parseLockEntry, } from './item-lock.js';
 import { ledgerWrite } from './ledger-write.js';
 import { workBranchRef } from './slug-namespace.js';
+import { appendQuestions, newSidecar, parseSidecar, resolveSidecarIdentity, serialiseSidecar, sidecarPathFor, } from './sidecar.js';
+import { parseFrontmatter, setNeedsAnswersMarker } from './frontmatter.js';
 import { retryWithBackoff, realSleep, } from './retry-backoff.js';
 /**
  * The **needs-attention mechanism** (ADR `ledger-status-on-per-item-lock-refs`;
@@ -146,7 +148,7 @@ export async function routeToNeedsAttention(options) {
 }
 /**
  * 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
@@ -162,12 +164,26 @@ export async function routeToNeedsAttention(options) {
  *     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.
@@ -189,6 +205,43 @@ async function readLocalItemLock(slug, cwd, env) {
     }
     return parseLockEntry(show.stdout);
 }
+/**
+ * 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) {
+    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) {
     const note = options.note ?? (() => { });
     const { cwd, slug, env } = options;
@@ -249,6 +302,62 @@ export async function returnToBacklog(options) {
                 'in-progress run).',
         };
     }
+    // `--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;
+    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
@@ -262,38 +371,26 @@ export async function returnToBacklog(options) {
     // 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], cwd, 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 };
-            }
+        const dropped = await deleteRemoteWorkBranchIfPresent({
+            cwd,
+            arbiter,
+            slug,
+            env,
+        });
+        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-
     // branch MUST be reachable by ANY worker, so before releasing the lock verify
@@ -304,14 +401,34 @@ export async function returnToBacklog(options) {
     // discards the branch by design).
     if (!options.reset) {
         const branch = workBranchRef('task', slug);
-        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 };
+        // 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, env);
+        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 };
+            }
         }
     }
     const commitMessage = `chore(${slug}): return to backlog for re-claiming`;
@@ -394,7 +511,85 @@ export async function returnToBacklog(options) {
         return { moved: false, reasonNotMoved: message };
     }
     note(`Returned '${slug}' to backlog (released the lock; body rests in pool).`);
-    return { moved: true, commitMessage, deletedRemoteBranch };
+    return { moved: true, commitMessage, deletedRemoteBranch, reconciled };
+}
+/**
+ * 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) {
+    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);
+    }
 }
 export async function promoteFromPreBacklog(options) {
     const note = options.note ?? (() => { });
@@ -456,13 +651,13 @@ export async function promoteFromPreBacklog(options) {
         const hasSource = (await gitSoftAsync(['cat-file', '-e', `${arbiter}/main:${sourceRel}`], cwd, env)).status === 0;
         const hasDest = (await gitSoftAsync(['cat-file', '-e', `${arbiter}/main:${destRel}`], cwd, env)).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?).';
+            const message = `'${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,
@@ -490,7 +685,7 @@ export async function promoteFromPreBacklog(options) {
                     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,
@@ -500,12 +695,12 @@ export async function promoteFromPreBacklog(options) {
             },
         });
         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 };
     }
@@ -545,7 +740,7 @@ export async function promoteFromPreSpec(options) {
     // (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({
@@ -622,7 +817,7 @@ export async function promoteFromPreSpec(options) {
 }
 /**
  * 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
@@ -785,6 +980,286 @@ 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) {
+    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 = 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 = (questions ?? []).map((q) => ({
+        ...q,
+        kind: q.kind ?? 'stuck',
+    }));
+    const additions = [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 = {
+        ...(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 });
+    }
+}
+/**
+ * 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) {
+    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) {
+    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 = {
+    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).