dorfl 0.0.0 → 0.1.1

package/dist/needs-attention.js

@@ -0,0 +1,900 @@
+import { rmSync } from 'node:fs';
+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 { acquireItemLock, releaseItemLock, readItemLock, itemLockRef, lockEntryFor, parseLockEntry, } from './item-lock.js';
+import { ledgerWrite } from './ledger-write.js';
+import { workBranchRef } from './slug-namespace.js';
+import { retryWithBackoff, realSleep, } from './retry-backoff.js';
+/**
+ * The **needs-attention mechanism** (ADR `ledger-status-on-per-item-lock-refs`;
+ * prd `ledger-status-per-item-lock-refs`; ADR §12 for the original folder model).
+ * Every "couldn't finish, a human must look" outcome (a failed acceptance gate
+ * (red `verify`), a rebase/merge conflict (ADR §10), a task the agent reported
+ * too ambiguous to build, a timeout, or a rejected review) resolves to ONE
+ * observable move: the RUNNER AMENDS the claimed item's HELD per-item lock
+ * `active → stuck` (`refs/dorfl/lock/<entry>`), writing the reason (+ any
+ * agent-surfaced questions) into the lock-entry BODY. There is NO `git mv` to a
+ * `work/needs-attention/` folder and NO on-`main` surface (the lock cut-over,
+ * task `cutover-needs-attention-becomes-lock-stuck-recovery-surface`): so a
+ * protected-`main` bounce succeeds, and a work branch cut from `main` inherits no
+ * stuck record. The RECOVERABLE half is the kept `work/<slug>` branch.
+ *
+ * This is the conflict-safe form of "surfacing": the surface is the lock
+ * `state: stuck`, read by `scan`/`status`/`gc --ledger` reading the lock refs (a
+ * COMMAND a human runs, not an `ls` of a folder). There is **no status/label
+ * field** on `main` (honours WORK-CONTRACT rule 3). The reason is prose in the
+ * lock-entry body, never a source-of-truth frontmatter field.
+ *
+ * Ownership: this module OWNS the mechanism (the move helper + the surface
+ * reader + the return path). Consumers (`complete.ts`'s gate-failed/rebase-
+ * conflict abort paths, the runner's stuck routing in `run.ts`, the human
+ * `return` command) drive these through the ledger write seam's NEEDS-ATTENTION
+ * transition (`ledgerWrite.applyNeedsAttentionTransition` /
+ * `applyReturnToBacklogTransition` in `ledger-write.ts`), whose sole strategy
+ * delegates to `routeToNeedsAttention` / `returnToBacklog` here UNCHANGED — so
+ * the later cherry-pick-to-`main` surfacing is built AGAINST the seam, not
+ * bolted onto this move code. The build agent NEVER does this — agents do no git
+ * (ADR §12).
+ */
+/** Marker that opens the appended reason block in a needs-attention item body. */
+const REASON_HEADING = '## Needs attention';
+/**
+ * Save the RECOVERABLE half of a stuck-item bounce (ADR §12). The RUNNER calls
+ * this; the build agent never does.
+ *
+ * **Post `ledger-status-per-item-lock-refs` cut-over (tasks 9a–9d, decision i+):**
+ * a bounce is now a PURE LOCK AMEND — the seam (`bounceToStuckLock` →
+ * `markStuckItemLock`) marks the per-item lock `state: stuck` and records the
+ * reason/questions ON THE LOCK ENTRY. There is NO `git mv` to a
+ * `needs-attention/` folder and NO on-`main` surface commit. The item body never
+ * moves (it rests in `backlog/` since claim stopped moving it, task 9a). So what
+ * REMAINS here is purely the never-lose-work half:
+ *
+ *   1. A **wip** commit on the `work/<slug>` branch tip holding whatever the agent
+ *      left uncommitted (`git add -A`). Skipped when the tree is already clean
+ *      (no aborted work to save). No bookkeeping trailer — after the cut-over NO
+ *      transient-status move-only commit lands on a branch, so a branch rebases
+ *      PLAINLY with nothing to drop (`drop-bookkeeping-rebase` is deleted, 9d).
+ *   2. Optionally PUSH the work branch to the arbiter so the saved wip travels
+ *      cross-machine and a `requeue` continues from the branch tip. BEST-EFFORT
+ *      (an unreachable arbiter leaves the local branch standing — recovery
+ *      degrades, never crashes the bounce; retried with bounded backoff on an
+ *      outage), BRANCH-PARAMETERISED (default `work/<slug>`; an explicit `branch`
+ *      overrides — the tasking bounce passes `work/prds/ready-<slug>`; `pushBranch: false`
+ *      ⇒ push NOTHING), and EMPTINESS-GUARDED (a branch with no commits beyond
+ *      main, or an absent branch, is skipped). The branch MUST be the one HEAD is
+ *      on. The work-branch push is NOT a `main` write.
+ *
+ * The stuck STATE itself (the `state: stuck` + reason/questions) is owned by the
+ * lock amend in the seam, not by this function. NEVER throws for the expected
+ * case — returns `{moved, ...}` so consumers can branch cleanly; genuine git
+ * plumbing failures still throw (they are unexpected).
+ */
+export async function routeToNeedsAttention(options) {
+    const note = options.note ?? (() => { });
+    const { cwd, slug, env } = options;
+    // TASK `cutover-needs-attention-becomes-lock-stuck-recovery-surface`
+    // (decision i+): the bounce is now a PURE lock amend (done by the seam) — there
+    // is NO `git mv` to `needs-attention/` and NO on-`main` surface. What REMAINS
+    // here is the RECOVERABLE half: SAVE the agent's uncommitted work as a wip
+    // commit on the `work/<slug>` branch tip and PUSH the branch to the arbiter, so
+    // the partial work travels cross-machine and a `requeue` continues from the
+    // branch tip. The reason/questions ride on the lock entry (the seam amends it),
+    // NOT a moved `.md`. The work branch push is NOT a `main` write.
+    // 1. WIP commit: save whatever the agent left uncommitted to the work branch
+    //    tip. Skip when the tree is clean (no aborted work to save). NOTE this no
+    //    longer needs a folder source — the body rests in `backlog/` (task 9a) and
+    //    never moves on a bounce.
+    gitHard(['add', '-A'], cwd, env);
+    const hadWip = !nothingStaged(cwd, env);
+    if (hadWip) {
+        // Save the agent's uncommitted work as a plain wip commit on the work-branch
+        // tip (the RECOVERABLE half — a `requeue` continues from it). No bookkeeping
+        // trailer: after the per-item-lock cut-over (tasks 9a–9d) NO transient status
+        // (no `needs-attention/` move-only commit) lands on a branch, so a branch cut
+        // from `main` rebases PLAINLY with nothing to drop — the `drop-bookkeeping-rebase`
+        // machinery and its `Dorfl-Bookkeeping` trailer are gone (9d).
+        const wipBody = `chore(${slug}): save aborted work (wip)`;
+        gitHard(['commit', '-q', '-m', wipBody], cwd, env);
+    }
+    const commitMessage = `chore(${slug}): bounce to stuck; ${options.reason}`;
+    const moveCommit = hadWip ? revParseHead(cwd, env) : undefined;
+    note(`Bounced '${slug}' to stuck (lock): ${options.reason}`);
+    // 2. Push the work branch to the arbiter — the RECOVERABLE half of the bounce
+    //    (so the saved wip travels cross-machine and a requeue continues from the
+    //    branch tip). Three behaviours: SURFACE-ONLY (no push) when
+    //    `pushBranch === false`; an explicit `branch` target; else the default
+    //    `work/<slug>`. BEST-EFFORT (no throw on a failed/unreachable push), RETRIED
+    //    with bounded backoff on an OUTAGE, and EMPTINESS-GUARDED (a branch with no
+    //    work beyond main / an absent branch is skipped). The OUTCOME is CAPTURED +
+    //    RETURNED (`branchPush`) so the caller reports what ACTUALLY landed.
+    let branchPush = 'not-attempted';
+    let pushError;
+    if (options.arbiter && options.pushBranch !== false) {
+        // DEFAULT to the task-namespaced build-bounce branch; a non-task caller
+        // (the tasking bounce) passes its own `work/prds/ready-<slug>` via `branch`.
+        const branch = options.branch ?? workBranchRef('task', slug);
+        if (branchAheadOf(cwd, branch, 'main', env)) {
+            const arbiter = options.arbiter;
+            const result = await retryWithBackoff(async () => {
+                const r = gitSoftRun(['push', arbiter, `${branch}:${branch}`], cwd, env);
+                return r.status === 0
+                    ? { ok: true, value: undefined }
+                    : { ok: false, error: r.stderr.trim() };
+            }, { sleep: options.sleep ?? realSleep, ...options.backoff });
+            if (result.ok) {
+                branchPush = 'pushed';
+            }
+            else {
+                branchPush = 'failed';
+                pushError = result.lastError;
+                note(`Could not push ${branch} to ${arbiter} after ${result.attempts} ` +
+                    `attempt(s) (${pushError ?? 'unknown error'}) — the work is saved ` +
+                    'LOCALLY only; push the branch when online, then `requeue`.');
+            }
+        }
+        else {
+            branchPush = 'skipped-empty';
+            note(`Skipped pushing ${branch} (no work beyond main / branch absent) — ` +
+                'nothing to recover.');
+        }
+    }
+    return { moved: true, commitMessage, moveCommit, branchPush, pushError };
+}
+/**
+ * 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
+ * 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
+ * un-surfaced abort, a killed run, or an in-place requeue note; defect 2, story
+ * 4): the slug's ACTUAL current folder is resolved on the arbiter and moved to
+ * `backlog/` via the SAME tree-less CAS. Any recorded reason/handoff block stays
+ * in the body as a durable note of what happened; the resolution itself is the
+ * human's.
+ *
+ * The `requeue` verb's THREE behaviours (ADR §14 / task
+ * `requeue-continue-and-reset`) are realised here:
+ *   - **default = KEEP + CONTINUE.** The `work/<slug>` branch is left UNTOUCHED;
+ *     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.
+ *   - **`-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.
+ *
+ * Like the move, NEVER throws for the expected "not in needs-attention" case.
+ */
+/**
+ * Read the item's lock entry from the LOCAL lock ref (no fetch) — the resilient
+ * fall-back for {@link returnToBacklog} when an arbiter fetch fails (e.g. a
+ * `--reset` against a moved-away arbiter). The up-front soft fetch already
+ * refreshed the local refs, so reading them locally is the best-effort truth
+ * without throwing.
+ */
+async function readLocalItemLock(slug, cwd, env) {
+    const ref = itemLockRef(lockEntryFor(`task:${slug}`));
+    const show = await gitSoftAsync(['show', `${ref}:lock.md`], cwd, env);
+    if (show.status !== 0) {
+        return undefined;
+    }
+    return parseLockEntry(show.stdout);
+}
+export async function returnToBacklog(options) {
+    const note = options.note ?? (() => { });
+    const { cwd, slug, env } = options;
+    // Tree-less CAS, EXACTLY like `claim` (`performClaim`): the move is published
+    // to the arbiter ref via the shared `ledger-write` write seam — it NEVER stages
+    // or commits in the cwd working tree (so a `requeue` in a shared checkout can no
+    // longer sweep up a concurrent writer's uncommitted files — the `8c92f63`
+    // incident, see
+    // `work/notes/observations/drive-backlog-skill-assumes-in-place-do-not-remote.md`).
+    // `--cwd` is purely the ORIGIN SOURCE (it resolves the arbiter remote + holds
+    // the object store the plumbing writes into), never a write TARGET. A tree-less
+    // CAS needs a ref to push to, so an `arbiter` is REQUIRED (parity with `claim`).
+    if (!options.arbiter) {
+        return {
+            moved: false,
+            reasonNotMoved: `requeue for '${slug}' needs an --arbiter: the move is published as a ` +
+                'tree-less compare-and-swap to the arbiter ref (like claim), so there ' +
+                'is no local-only mode — pass --arbiter.',
+        };
+    }
+    const arbiter = options.arbiter;
+    if ((await gitSoftAsync(['remote', 'get-url', arbiter], cwd, env)).status !== 0) {
+        return {
+            moved: false,
+            reasonNotMoved: `no git remote named '${arbiter}' (set one, or pass --arbiter).`,
+        };
+    }
+    // Refresh the remote-tracking refs so every check below (the item's residence,
+    // the continue-branch guard, the CAS base) sees the arbiter's TRUTH, not a stale
+    // local copy. This is a fetch, not a checkout — the working tree is untouched.
+    await gitSoftAsync(['fetch', '--quiet', arbiter], cwd, env);
+    // Is the item LOCK-HELD on the arbiter? (task
+    // `cutover-needs-attention-becomes-lock-stuck-recovery-surface`, decision i+:
+    // stuck-state is the per-item lock `state: stuck`, NOT a `needs-attention/`
+    // folder file). `requeue` recovers a STUCK hold (the resolved-recovery path) and
+    // tolerates an ACTIVE hold (a killed run that never surfaced) — both legitimate
+    // in-flight states the human's recovery verb returns to the pool. We read the
+    // LOCK ref (arbiter-is-truth), NOT a folder. No held lock ⇒ nothing to requeue
+    // (the item is already at rest — unclaimed in `backlog/`, or terminal).
+    // Read the held lock TOLERANTLY: a broken/unreachable arbiter (e.g. a
+    // `--reset` against a moved-away arbiter) must NOT throw out of requeue — the
+    // up-front soft fetch above already refreshed the local lock refs, so on a
+    // fetch fault we fall back to the local lock ref (best-effort) rather than
+    // crashing. A genuinely absent lock still refuses below.
+    let held;
+    try {
+        held = await readItemLock({ item: `task:${slug}`, cwd, arbiter, env });
+    }
+    catch {
+        held = await readLocalItemLock(slug, cwd, env);
+    }
+    if (!held) {
+        return {
+            moved: false,
+            reasonNotMoved: `'${slug}' has no held per-item lock on ${arbiter} — nothing to requeue ` +
+                '(wrong slug, or already at rest in backlog/done?). requeue recovers a ' +
+                'task whose lock is held stuck (needs-attention) or active (a killed ' +
+                'in-progress run).',
+        };
+    }
+    // `--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
+    // deleted FIRST, THEN the arbiter `git push --delete`. The asymmetry is the
+    // point: the arbiter is the source of truth and the local ref is derived, so
+    // inverting today's arbiter-first ordering converts a dangerous failure mode
+    // (local AHEAD of arbiter — a permanent stale-continue) into a self-healing
+    // one (local BEHIND — the next fetch restores it from the arbiter). A FAILED
+    // arbiter delete still ABORTS the requeue (no backlog move); the local
+    // behind-state is recoverable by a subsequent fetch and CANNOT drive a wrong
+    // 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 };
+            }
+        }
+        deletedRemoteBranch = true;
+        note(`Deleted the remote branch ${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
+    // the ARBITER branch `<arbiter>/work/<slug>` exists + is ahead of main — the
+    // EXACT "is the continue-branch on the arbiter?" question the continue-path asks
+    // in `isolation.ts`. We check the ARBITER ref (already fetched above), NOT the
+    // local `work/<slug>` (which SURVIVES a failed push). NOT on `--reset` (which
+    // 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 };
+        }
+    }
+    const commitMessage = `chore(${slug}): return to backlog for re-claiming`;
+    const handoff = options.message && options.message.trim() !== ''
+        ? options.message.trim()
+        : undefined;
+    // The body rests EITHER in the pool (`tasks-ready`) OR — for a staged item driven
+    // with `--allow-backlog` — in staging (`tasks-backlog`). Probe in the SAME
+    // precedence `resolveTask`/`--allow-backlog` uses (ready first, then backlog), so
+    // the handoff note finds a staged body too (obs
+    // `requeue-dash-m-fails-and-strands-lock-for-staged-backlog-item`).
+    const bodyResidenceCandidates = [
+        'tasks-ready',
+        'tasks-backlog',
+    ];
+    // `-m "<note>"` (the handoff steer): APPEND a dated `## Requeue YYYY-MM-DD`
+    // section to the item BODY where it already rests (pool or staging), via the SAME
+    // tree-less CAS move (same-folder rewrite with the body transform) — it NEVER
+    // stages/commits in the cwd tree. The handoff is OPTIONAL and NON-FATAL: a failed
+    // append degrades to a WARNING and the lock release below STILL runs, because the
+    // lock release is the load-bearing recovery and must never be stranded by an
+    // optional note (obs `requeue-dash-m-fails-and-strands-lock-for-staged-backlog-item`).
+    if (handoff !== undefined) {
+        const noted = await runTreelessLedgerMove({
+            cwd,
+            slug,
+            arbiter,
+            kind: 'requeue',
+            onContended: 'requeue',
+            explicitMainRefspec: false,
+            env,
+            note,
+            plan: (base) => {
+                const bodyRel = bodyResidenceCandidates
+                    .map((folder) => workItemRel(folder, `${slug}.md`))
+                    .find((rel) => pathInCommit(base, rel, cwd, env));
+                if (bodyRel === undefined) {
+                    // The body is in neither tasks/ready/ nor tasks/backlog/ on this base —
+                    // nothing to annotate (the durable move that placed it must land first).
+                    return 'missing';
+                }
+                return prepareTreelessMoveCommit({
+                    cwd,
+                    slug,
+                    base,
+                    sourceRel: bodyRel,
+                    destRel: bodyRel,
+                    transformBody: (body) => appendRequeueNoteText(body, handoff),
+                    commitMessage: `chore(${slug}): requeue handoff note`,
+                    refNamespace: 'requeue',
+                    env,
+                });
+            },
+        });
+        if (!noted) {
+            // NON-FATAL: warn and fall through to the lock release. We do NOT strand the
+            // lock for a failed OPTIONAL note (the previous behaviour, which left a
+            // half-applied state: branch deleted on --reset, lock still held).
+            note(`requeue for '${slug}': could not append the -m handoff note (the body ` +
+                `is in neither tasks/ready/ nor tasks/backlog/ on ${arbiter}/main, or ` +
+                'main kept moving). Releasing the lock anyway — the requeue still ' +
+                'recovers the item; only the note was skipped.');
+        }
+    }
+    // RELEASE the held lock (`stuck → released` / give up the hold): the item
+    // returns to the claimable pool (its body already rests in `backlog/`). Use the
+    // tolerant {@link releaseItemLock} (idempotent) so requeue recovers BOTH a
+    // `stuck` hold (the resolved-recovery path) and an `active` hold (a killed run
+    // that never surfaced) — the human asserting "put it back".
+    const released = await releaseItemLock({
+        item: `task:${slug}`,
+        cwd,
+        arbiter,
+        env,
+    });
+    if (released.outcome === 'error') {
+        const message = `requeue for '${slug}': could not release the per-item lock ` +
+            `(${released.message}). The item is left stuck. Try again shortly.`;
+        note(message);
+        return { moved: false, reasonNotMoved: message };
+    }
+    note(`Returned '${slug}' to backlog (released the lock; body rests in pool).`);
+    return { moved: true, commitMessage, deletedRemoteBranch };
+}
+export async function promoteFromPreBacklog(options) {
+    const note = options.note ?? (() => { });
+    const { cwd, slug, env } = options;
+    if (!options.arbiter) {
+        return {
+            moved: false,
+            reasonNotMoved: `promote for '${slug}' needs an --arbiter: the move is published as a ` +
+                'tree-less compare-and-swap to the arbiter ref (like requeue/claim), so ' +
+                'there is no local-only mode — pass --arbiter.',
+        };
+    }
+    const arbiter = options.arbiter;
+    if ((await gitSoftAsync(['remote', 'get-url', arbiter], cwd, env)).status !== 0) {
+        return {
+            moved: false,
+            reasonNotMoved: `no git remote named '${arbiter}' (set one, or pass --arbiter).`,
+        };
+    }
+    // Refresh `<arbiter>/main` so the residence probe + the CAS base see the
+    // arbiter's TRUTH. A fetch, not a checkout — the working tree is untouched.
+    await gitSoftAsync(['fetch', '--quiet', arbiter], cwd, env);
+    // UNIFIED PER-ITEM LOCK around the CAS window (prd
+    // `staging-surface-and-apply-promote-safety`, task
+    // `f3b-promote-takes-per-item-advancing-lock`): promote and apply BOTH key onto
+    // the item's `refs/dorfl/lock/<entry>` ref with `action: advance` (the
+    // SAME action `apply` takes via `advancing-lock.ts`), so an apply mid-flight
+    // and a promote attempt on the SAME item are mutually exclusive BY
+    // CONSTRUCTION (the second acquirer loses the create-only ref CAS). Reusing
+    // the existing `advance` action value (rather than introducing a distinct
+    // `'promote'` axis) is deliberate — the lock entry is keyed on the item
+    // identity, and what matters is that ALL three transitions of one item
+    // (implement/task/advance) serialise on ONE ref. A lock `lost` exits CLEAN
+    // (no partial state on `main`, mirroring claim-cas loss semantics); on success
+    // or failure we release the lock in `finally`. Crash-safe release mirrors the
+    // apply rung: a crashed promote leaves an `advance`-active lock that the
+    // existing `release-lock` / `gc --ledger` recovery surface clears.
+    const item = `task:${slug}`;
+    const acquired = await acquireItemLock({
+        item,
+        action: 'advance',
+        cwd,
+        arbiter,
+        env,
+    });
+    if (acquired.outcome !== 'acquired') {
+        const message = acquired.outcome === 'lost'
+            ? `promote for '${slug}' lost the per-item lock race (another implement/task/advance hold is in flight). No move on ${arbiter}/main. Try again shortly.`
+            : `promote for '${slug}': could not acquire the per-item lock (${acquired.message}).`;
+        note(message);
+        return { moved: false, reasonNotMoved: message };
+    }
+    try {
+        const sourceRel = workItemRel('tasks-backlog', `${slug}.md`);
+        const destRel = workItemRel('tasks-ready', `${slug}.md`);
+        // Early-exit message: if NEITHER staged nor already-in-pool, there is
+        // nothing to promote (the per-attempt `plan` is the authoritative
+        // resolution against the live base).
+        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?).';
+            note(message);
+            return { moved: false, reasonNotMoved: message };
+        }
+        const commitMessage = `chore(${slug}): promote work/pre-backlog/ -> work/backlog/`;
+        const moved = await runTreelessLedgerMove({
+            cwd,
+            slug,
+            arbiter,
+            kind: 'promote',
+            onContended: 'promote',
+            // The surface direction's main-only refspec works here too: this runs in
+            // the project checkout, but we only need `<arbiter>/main` resolved, and
+            // the explicit refspec is the safer default (mirrors `surface`).
+            explicitMainRefspec: true,
+            env,
+            note,
+            plan: (base) => {
+                // If already in the pool on this base, a prior attempt landed
+                // (idempotent).
+                if (pathInCommit(base, destRel, cwd, env)) {
+                    return 'already-done';
+                }
+                if (!pathInCommit(base, sourceRel, cwd, env)) {
+                    return 'missing';
+                }
+                return prepareTreelessMoveCommit({
+                    cwd,
+                    slug,
+                    base,
+                    sourceRel,
+                    destRel,
+                    // The body is carried byte-for-byte from pre-backlog into the
+                    // pool — promotion is a placement decision, not a content transform.
+                    transformBody: (body) => body,
+                    commitMessage,
+                    refNamespace: 'promote',
+                    env,
+                });
+            },
+        });
+        if (moved) {
+            note(`Promoted '${slug}' from pre-backlog to backlog (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.';
+        note(message);
+        return { moved: false, reasonNotMoved: message };
+    }
+    finally {
+        await releaseItemLock({ item, cwd, arbiter, env });
+    }
+}
+export async function promoteFromPreSpec(options) {
+    const note = options.note ?? (() => { });
+    const { cwd, slug, env } = options;
+    if (!options.arbiter) {
+        return {
+            moved: false,
+            reasonNotMoved: `promote for '${slug}' needs an --arbiter: the move is published as ` +
+                'a tree-less compare-and-swap to the arbiter ref (like requeue/claim), so ' +
+                'there is no local-only mode — pass --arbiter.',
+        };
+    }
+    const arbiter = options.arbiter;
+    if ((await gitSoftAsync(['remote', 'get-url', arbiter], cwd, env)).status !== 0) {
+        return {
+            moved: false,
+            reasonNotMoved: `no git remote named '${arbiter}' (set one, or pass --arbiter).`,
+        };
+    }
+    // Refresh `<arbiter>/main` so the residence probe + the CAS base see the
+    // arbiter's TRUTH. A fetch, not a checkout — the working tree is untouched.
+    await gitSoftAsync(['fetch', '--quiet', arbiter], cwd, env);
+    // UNIFIED PER-ITEM LOCK around the CAS window — symmetric with
+    // {@link promoteFromPreBacklog} (prd `staging-surface-and-apply-promote-safety`,
+    // task `f3b-promote-takes-per-item-advancing-lock`, decisive prd q4 answer:
+    // specs share the apply×promote mutual-exclusion fix with tasks). The lock
+    // keys on `spec:${slug}` (a distinct ref from a task with the same slug, via
+    // {@link lockEntryFor}'s `<type>-<slug>` encoding), with `action: advance` —
+    // the SAME action an apply for a spec would take — so spec promote and spec
+    // apply on the same item are mutually exclusive by construction. MIGRATE step
+    // (prd `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.
+    // Loss / crash semantics mirror the task case.
+    const item = `spec:${slug}`;
+    const acquired = await acquireItemLock({
+        item,
+        action: 'advance',
+        cwd,
+        arbiter,
+        env,
+    });
+    if (acquired.outcome !== 'acquired') {
+        const message = acquired.outcome === 'lost'
+            ? `promote for '${slug}' lost the per-item lock race (another implement/task/advance hold is in flight). No move on ${arbiter}/main. Try again shortly.`
+            : `promote for '${slug}': could not acquire the per-item lock (${acquired.message}).`;
+        note(message);
+        return { moved: false, reasonNotMoved: message };
+    }
+    try {
+        const sourceRel = workItemRel('specs-proposed', `${slug}.md`);
+        const destRel = workItemRel('specs-ready', `${slug}.md`);
+        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 ${workFolderPrefix('specs-proposed')} on ${arbiter}/main ` +
+                `(and not already in ${workFolderPrefix('specs-ready')}) — nothing to promote ` +
+                '(wrong slug, or never staged?).';
+            note(message);
+            return { moved: false, reasonNotMoved: message };
+        }
+        const commitMessage = `chore(${slug}): promote ${workFolderPrefix('specs-proposed')} -> ${workFolderPrefix('specs-ready')}`;
+        const moved = await runTreelessLedgerMove({
+            cwd,
+            slug,
+            arbiter,
+            kind: 'promote',
+            onContended: 'promote',
+            explicitMainRefspec: true,
+            env,
+            note,
+            plan: (base) => {
+                if (pathInCommit(base, destRel, cwd, env)) {
+                    return 'already-done';
+                }
+                if (!pathInCommit(base, sourceRel, cwd, env)) {
+                    return 'missing';
+                }
+                return prepareTreelessMoveCommit({
+                    cwd,
+                    slug,
+                    base,
+                    sourceRel,
+                    destRel,
+                    // The body is carried byte-for-byte from prds/proposed into the pool —
+                    // promotion is a placement decision, not a content transform.
+                    transformBody: (body) => body,
+                    commitMessage,
+                    refNamespace: 'promote',
+                    env,
+                });
+            },
+        });
+        if (moved) {
+            note(`Promoted prd '${slug}' from prds/proposed to prds/ready (auto-taskable).`);
+            return { moved: true, commitMessage };
+        }
+        const message = `promote for '${slug}': the arbiter's main kept moving (contended) ` +
+            `after ${TREELESS_CONTENTION_ATTEMPTS} attempts — item left in prds/proposed ` +
+            '(no move). Try again shortly.';
+        note(message);
+        return { moved: false, reasonNotMoved: message };
+    }
+    finally {
+        await releaseItemLock({ item, cwd, arbiter, env });
+    }
+}
+/**
+ * LIST every staged item awaiting a runner/human promotion — the tasks in
+ * `work/pre-backlog/` and the prds in `work/prds/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
+ * the promotion functions act against, so the list and the move never disagree.
+ * Read-only: it never fetches a checkout, never moves anything.
+ */
+export async function listPromotable(options) {
+    const { cwd, arbiter, env } = options;
+    if ((await gitSoftAsync(['remote', 'get-url', arbiter], cwd, env)).status !== 0) {
+        return {
+            items: [],
+            error: `no git remote named '${arbiter}' (set one, or pass --arbiter).`,
+        };
+    }
+    // Refresh `<arbiter>/main` so the listing sees the arbiter's TRUTH (a fetch,
+    // not a checkout — the working tree is untouched), exactly as the promote
+    // functions do before their residence probe.
+    await gitSoftAsync(['fetch', '--quiet', arbiter], cwd, env);
+    const tasks = await listMarkdownSlugsInTree(`${arbiter}/main:${workFolderRel('tasks-backlog')}`, cwd, env);
+    const specs = await listMarkdownSlugsInTree(`${arbiter}/main:${workFolderRel('specs-proposed')}`, cwd, env);
+    return {
+        items: [
+            ...tasks.map((slug) => ({ namespace: 'task', slug })),
+            ...specs.map((slug) => ({ namespace: 'spec', slug })),
+        ],
+    };
+}
+/**
+ * `git ls-tree --name-only <base>` → the `.md` filenames' SLUGS (filename minus
+ * `.md`), sorted. An absent folder on the ref reads as empty (the staging folder
+ * may not exist yet). The bare-repo-safe read (`ls-tree`, no working tree), the
+ * SAME mechanism the ledger read seam uses.
+ */
+async function listMarkdownSlugsInTree(base, cwd, env) {
+    const tree = await gitSoftAsync(['ls-tree', '--name-only', base], cwd, env);
+    if (tree.status !== 0) {
+        return [];
+    }
+    return tree.stdout
+        .split('\n')
+        .map((s) => s.trim())
+        .filter((name) => isWorkItemFile(name))
+        .map((name) => name.replace(/\.md$/i, ''))
+        .sort();
+}
+/** The contention-retry cap shared by the tree-less requeue + surface moves. */
+const TREELESS_CONTENTION_ATTEMPTS = 5;
+/**
+ * The SHARED tree-less ledger-move core (ONE mechanism for BOTH directions — the
+ * requeue `needs-attention|in-progress → backlog` and the surface `in-progress →
+ * needs-attention`). It runs the contention-retry loop: fetch `<arbiter>/main`,
+ * resolve `expectedBase`, ask the caller's `plan(base)` to build the one-file move
+ * on a SCRATCH INDEX via {@link prepareTreelessMoveCommit} (so the caller's
+ * index/HEAD/working tree are NEVER touched), CAS-publish it THROUGH the shared
+ * write seam (`ledgerWrite.applyTransition`, the very push+lease+verify `claim`
+ * uses), drop the throwaway ref, and on a CONTENTION rejection refetch + REPLAN
+ * against the advanced base and retry. Re-planning per attempt is what makes the
+ * retry safe when the item itself moved under us (e.g. a prior attempt landed but
+ * the CAS verify reported rejected): the next plan sees it `already-done`.
+ */
+async function runTreelessLedgerMove(params) {
+    const { cwd, arbiter, kind, plan, onContended, explicitMainRefspec, env, note, } = params;
+    const fetchArgs = explicitMainRefspec
+        ? [
+            'fetch',
+            '--quiet',
+            arbiter,
+            `+refs/heads/main:refs/remotes/${arbiter}/main`,
+        ]
+        : ['fetch', '--quiet', arbiter];
+    for (let i = 0; i < TREELESS_CONTENTION_ATTEMPTS; i++) {
+        if (i > 0) {
+            await gitSoftAsync(fetchArgs, cwd, env);
+        }
+        const base = (await gitHardAsync(['rev-parse', `${arbiter}/main`], cwd, env)).stdout.trim();
+        // Plan the move FRESH against this (possibly re-fetched) base. The item may
+        // already be at the destination (idempotent / a prior landed-but-reported-
+        // rejected attempt) or absent — both are terminal, no push.
+        const prepared = plan(base);
+        if (prepared === 'already-done') {
+            return true;
+        }
+        if (prepared === 'missing') {
+            return false;
+        }
+        // Publish THROUGH the shared seam (the same `:main` push + force-with-lease +
+        // verify `claim` uses). The transition's WHO stays the caller's ambient env
+        // (threaded by `commit-tree` above) — tree-less is orthogonal to attribution.
+        const result = await ledgerWrite.applyTransition({
+            kind,
+            arbiter,
+            localBranch: prepared.ref,
+            expectedBase: base,
+            head: prepared.commit,
+            cwd,
+            env,
+            note,
+        });
+        // Drop the throwaway ref either way (it served only as the push source).
+        await gitSoftAsync(['update-ref', '-d', prepared.ref], cwd, env);
+        if (result.kind === 'published') {
+            // Advance the LOCAL remote-tracking `<arbiter>/main` so it INCLUDES the
+            // move (the push only moved the arbiter's main). Best-effort.
+            await gitSoftAsync(fetchArgs, cwd, env);
+            return true;
+        }
+        // rejected: main moved under us — refetch + REPLAN against the new base.
+        note(`main advanced under us — ${onContended} refetch and retry (${i + 1}/${TREELESS_CONTENTION_ATTEMPTS})...`);
+    }
+    return false;
+}
+/** True iff `path` exists in the given commit's tree (a soft cat-file probe). */
+function pathInCommit(commit, path, cwd, env) {
+    return (run('git', ['cat-file', '-e', `${commit}:${path}`], cwd, { env }).status === 0);
+}
+/**
+ * Build a one-file ledger MOVE as a commit off the arbiter's `main`, using
+ * PLUMBING on a SCRATCH INDEX — it never touches the caller's index, HEAD, or
+ * working tree (so a concurrent writer's uncommitted cwd files can never be swept
+ * in). It loads `base`'s tree into a throwaway index, relocates ONLY this slug's
+ * ledger file from `sourceRel` to `destRel` (applying `transformBody` to its body
+ * first — read from the blob on `main`, NOT from any cwd file: the requeue note,
+ * or the needs-attention reason), writes the tree, commits it parented on `base`,
+ * and points a throwaway local ref at the commit. Returns that ref + the commit
+ * sha for the seam's CAS push. The SHARED prep for BOTH tree-less directions.
+ */
+function prepareTreelessMoveCommit(params) {
+    const { cwd, slug, base, sourceRel, destRel, transformBody, commitMessage, refNamespace, env, } = params;
+    // The item's body on `main`, with the caller's body transform applied.
+    const original = catBlob(`${base}:${sourceRel}`, cwd, env);
+    const content = transformBody(original);
+    // Hash the (possibly transformed) blob INTO the cwd's object store. A blob
+    // write does not touch the working tree.
+    const blob = hashObject(content, cwd, env);
+    // A scratch index so read-tree/update-index never disturb the caller's index.
+    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);
+        // Remove the item from its source folder, add it under the dest folder. When
+        // source === dest (an idempotent re-surface), force-remove + re-add the same
+        // path is a no-op move that still carries any body change. One file changes.
+        gitHard(['update-index', '--force-remove', sourceRel], cwd, withIndex);
+        gitHard(['update-index', '--add', '--cacheinfo', `100644,${blob},${destRel}`], cwd, withIndex);
+        const tree = runHard(['write-tree'], cwd, withIndex).stdout.trim();
+        // commit-tree threads the caller's ambient identity (env) — tree-less only
+        // changed the WHERE-it-writes (the arbiter ref, not the cwd tree), not the WHO.
+        const commit = runHard(['commit-tree', tree, '-p', base, '-m', commitMessage], cwd, env).stdout.trim();
+        // A throwaway local ref the seam's push uses as its source (`<ref>:main`).
+        const ref = `refs/dorfl/${refNamespace}/${slug}`;
+        gitHard(['update-ref', ref, commit], cwd, env);
+        return { ref, commit };
+    }
+    finally {
+        rmSync(scratchIndex, { force: true });
+    }
+}
+/** The heading that opens an appended requeue handoff note in the item body. */
+const REQUEUE_HEADING_PREFIX = '## Requeue';
+/**
+ * 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).
+ * Body prose only (never a frontmatter field — WORK-CONTRACT rule 3). The date is
+ * UTC `YYYY-MM-DD`; multiple notes on the same day are distinct appended blocks.
+ *
+ * A PURE string transform (it operates on the body CONTENT, not a file path) so
+ * the tree-less requeue can apply it to the blob read from `<arbiter>/main`
+ * without touching the cwd working tree.
+ */
+function appendRequeueNoteText(content, message) {
+    const date = new Date().toISOString().slice(0, 10);
+    const base = content.replace(/\s*$/, '');
+    return [base, '', `${REQUEUE_HEADING_PREFIX} ${date}`, '', message, ''].join('\n');
+}
+/**
+ * Extract the prose written under the `## Needs attention` heading from an item
+ * body. Returns the first non-empty line(s) of the block as a single line
+ * (stops at the next `## ` heading); '' when no block is present. The
+ * needs-attention REASON is now recorded on the per-item lock entry (task
+ * `cutover-needs-attention-becomes-lock-stuck-recovery-surface`, decision i+),
+ * NOT in the body, but this extractor stays for any historical body text that
+ * still carries the heading (a tolerant best-effort read).
+ */
+export function extractReason(content) {
+    const normalized = content.replace(/\r\n/g, '\n');
+    const lines = normalized.split('\n');
+    const start = lines.findIndex((l) => l.trim() === REASON_HEADING);
+    if (start === -1) {
+        return '';
+    }
+    const collected = [];
+    for (let i = start + 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (/^##\s/.test(line)) {
+            break;
+        }
+        if (/^###\s/.test(line)) {
+            // The questions sub-section starts here; the reason itself is above it.
+            break;
+        }
+        if (line.trim() === '') {
+            if (collected.length > 0) {
+                // Stop at the first blank line AFTER we captured the reason text.
+                break;
+            }
+            continue;
+        }
+        collected.push(line.trim());
+    }
+    return collected.join(' ').trim();
+}
+/** Run git; throw on non-zero (genuinely unexpected plumbing failures). */
+function gitHard(args, cwd, env) {
+    runHard(args, cwd, env);
+}
+/** Like {@link gitHard} but returns the raw result (for plumbing that emits stdout). */
+function runHard(args, cwd, env) {
+    const result = run('git', args, cwd, { env });
+    if (result.status !== 0) {
+        throw new Error(`git ${args.join(' ')} failed (exit ${result.status}): ${result.stderr.trim()}`);
+    }
+    return result;
+}
+/** Async soft git (no throw) — for the tree-less requeue's remote checks. */
+function gitSoftAsync(args, cwd, env) {
+    return runAsync('git', args, cwd, { env });
+}
+/** Async git; throw on non-zero (unexpected plumbing failures). */
+async function gitHardAsync(args, cwd, env) {
+    const result = await runAsync('git', args, cwd, { env });
+    if (result.status !== 0) {
+        throw new Error(`git ${args.join(' ')} failed (exit ${result.status}): ${result.stderr.trim()}`);
+    }
+    return result;
+}
+/** Read an object's content (`git cat-file -p <object>`) from the cwd's store. */
+function catBlob(object, cwd, env) {
+    return runHard(['cat-file', '-p', object], cwd, env).stdout;
+}
+/** Write a blob into the cwd's object store (`git hash-object -w`), return its sha. */
+function hashObject(content, cwd, env) {
+    const result = run('git', ['hash-object', '-w', '--stdin'], cwd, {
+        env,
+        input: content,
+    });
+    if (result.status !== 0) {
+        throw new Error(`git hash-object failed (exit ${result.status}): ${result.stderr.trim()}`);
+    }
+    return result.stdout.trim();
+}
+/**
+ * Run git, returning the raw result (no throw) — for soft checks like the
+ * `--reset` remote-branch delete, whose non-zero exit is a meaningful outcome
+ * (the requeue aborts) rather than an unexpected plumbing failure.
+ */
+function gitSoftRun(args, cwd, env) {
+    return run('git', args, cwd, { env });
+}
+/** True when the index has no staged changes against HEAD (nothing to commit). */
+function nothingStaged(cwd, env) {
+    // `diff --cached --quiet` exits 0 when NOTHING is staged, 1 when there is.
+    return run('git', ['diff', '--cached', '--quiet'], cwd, { env }).status === 0;
+}
+/** The current HEAD commit sha (the just-made commit's tip). */
+function revParseHead(cwd, env) {
+    const result = run('git', ['rev-parse', 'HEAD'], cwd, { env });
+    if (result.status !== 0) {
+        throw new Error(`git rev-parse HEAD failed (exit ${result.status}): ${result.stderr.trim()}`);
+    }
+    return result.stdout.trim();
+}
+//# sourceMappingURL=needs-attention.js.map