dorfl 0.13.2 → 0.13.4

package/dist/needs-attention.js

@@ -4,11 +4,11 @@ import { join } from 'node:path';
 import { workFolderPrefix, workFolderRel, workItemRel, isWorkItemFile, } from './work-layout.js';
 import { run, runAsync } from './git.js';
 import { branchAheadOf, rebaseContinuedBranchOntoMain, } from './continue-branch.js';
-import { acquireItemLock, releaseItemLock, readItemLock, itemLockRef, lockEntryFor, parseLockEntry, } from './item-lock.js';
+import { acquireItemLock, releaseItemLock, readItemLock, itemLockRef, lockEntryFor, refreshMainRef, parseLockEntry, } from './item-lock.js';
 import { ledgerWrite } from './ledger-write.js';
 import { workBranchRef } from './slug-namespace.js';
 import { refreshArbiterRefs, resolveArbiterBranch } from './arbiter-refs.js';
-import { appendQuestions, isEntryAnswered, newSidecar, parseSidecar, resolveSidecarIdentity, serialiseSidecar, sidecarPathFor, } from './sidecar.js';
+import { appendQuestions, isEntryAnswered, newSidecar, parseSidecar, resolveSidecarIdentity, serialiseSidecar, sidecarPathFor, sidecarPathCandidates, } from './sidecar.js';
 import { parseFrontmatter, setNeedsAnswersMarker } from './frontmatter.js';
 import { retryWithBackoff, realSleep, } from './retry-backoff.js';
 /**
@@ -1306,6 +1306,599 @@ export function prepareTreelessSurfaceCommit(params) {
         rmSync(scratchIndex, { force: true });
     }
 }
+/**
+ * The terminal `work/` paths for an item, tagged by {@link TerminalKind}, so a
+ * reader can tell "the work happened" from "the item was abandoned".
+ *
+ * Same SHAPE as `terminalMainPaths` in `item-lock.ts`, but deliberately NOT the
+ * same folder set, and the difference must not be "tidied" away: locks treat
+ * `specs/tasked/` as terminal (correctly, a tasked spec must release its lock),
+ * whereas QUESTION state there is still live. This map is keyed to "is the
+ * question loop CLOSED at this resting place?", not "has the item stopped
+ * moving?". See the `case 'spec'` comment below.
+ */
+export function terminalMainPathsByKind(type, slug) {
+    const file = `${slug}.md`;
+    switch (type) {
+        case 'task':
+            return [
+                { path: workItemRel('done', file), kind: 'completed' },
+                { path: workItemRel('cancelled', file), kind: 'wont-proceed' },
+            ];
+        case 'spec':
+            // `specs/tasked/` is deliberately NOT listed. WORK-CONTRACT ("A SPEC that
+            // has drifted AFTER it was TASKED") makes a bare `needsAnswers:true` on a
+            // tasked spec LEGAL and load-bearing: it means "tasked, but the spec has
+            // drifted, do not RE-task or rely on it until reconciled", and the
+            // contract says to set it *while the spec stays in `specs/tasked/`*
+            // (moving it back would falsely un-record a tasking that really happened
+            // and orphan the tasks it already emitted).
+            //
+            // So the reasoning that makes a task's question state moot at its terminal
+            // does NOT transfer: a tasked spec is still IN the question loop.
+            // `lifecycle-gather.ts` enumerates tasked resting specs UNCONDITIONALLY,
+            // routing a bare flag to the SURFACE rung and an answered sidecar to the
+            // APPLY rung, so BOTH halves are live inputs to a rung that WILL run.
+            // Draining either would disarm a live drift gate and let a stale spec be
+            // re-tasked. That is precisely the "clearing a live needsAnswers hands gated work
+            // to agents" harm this pass exists to avoid.
+            //
+            // `specs/dropped/` needs no such carve-out: a dropped spec is abandoned,
+            // and no rung enumerates it.
+            return [{ path: workItemRel('specs-dropped', file), kind: 'wont-proceed' }];
+        case 'observation':
+            // A note has no durable terminal folder: it leaves by DELETION, so there
+            // is no resting record to reconcile against.
+            return [];
+    }
+}
+/** Every SUCCESS-terminal folder that can hold a stranded `needsAnswers` flag,
+ * paired with the item type that rests there. Derived from
+ * {@link terminalMainPathsByKind} with a sentinel slug so the folder set stays
+ * SINGLE-SOURCED: adding a regime there adds it here, and the `wont-proceed`
+ * terminals are excluded by the SAME `kind` split the drain already branches on
+ * (a cancelled item's flag is accurate history, not residue). `observation`
+ * contributes nothing, having no durable terminal. */
+function successTerminalFolders() {
+    const out = [];
+    for (const type of ['task', 'spec', 'observation']) {
+        for (const candidate of terminalMainPathsByKind(type, '__slug__')) {
+            if (candidate.kind !== 'completed') {
+                continue;
+            }
+            out.push({
+                folder: candidate.path.slice(0, candidate.path.lastIndexOf('/')),
+                type,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Classify the arbiter's STRANDED QUESTION STATE, read-only (observation
+ * `a-rebuilt-task-leaves-its-bounce-question-asking-to-cancel-a-merged-task`).
+ *
+ * THE BUG THIS EXISTS FOR. When a build bounces, the surface path atomically
+ * writes BOTH halves of the question state in ONE commit: the sidecar
+ * `work/questions/<type>-<slug>.md` AND `needsAnswers: true` on the item body.
+ * That is correct, and the atomicity is what makes this reconciliation decidable
+ * at all. But if the human DISAGREES with the bounce and simply re-dispatches,
+ * and the rebuild SUCCEEDS (PR opened, gate green, merged, body done-moved),
+ * NEITHER half is ever cleared. The item comes to rest in `tasks/done/` still
+ * carrying a question asking whether to CANCEL it, with a destructive default.
+ *
+ * The flag is the harmful half. A stranded sidecar is a stale question in a
+ * folder a human scans; a stranded `needsAnswers` is a GATE LEFT ARMED, and it
+ * makes `status` report shipped (sometimes released) work under "open questions
+ * block autonomous work".
+ *
+ * Dorfl ALREADY knows this state is illegal: `advance-classify.ts` refuses it as
+ * `invariant-violation` / `sidecar-without-needsAnswers`. The defect is purely
+ * that the detector lives in the `advance` tick's classifier, and a human driving
+ * `do` and merging a PR never enters that loop. So this is the same shape as the
+ * propose-path lock leak, settled by the same reconcile pass at the same moment
+ * (the done-move), rather than by a second mechanism.
+ *
+ * THE TRAP, and why the TERMINAL POSITION is the discriminator rather than the
+ * flag/sidecar disagreement: the MIRROR state (`needsAnswers:true` with NO
+ * sidecar) is LEGAL and COMMON. An item authored with open questions carries the
+ * flag and has no sidecar until `surface` runs, and that flagged-but-unsurfaced
+ * item is precisely the `surface` rung's INPUT. Clearing the flag there would
+ * silently disarm every un-surfaced item in the repo and hand gated work to
+ * agents. So this only ever considers items whose body has reached a TERMINAL
+ * folder on `main`; an item resting in a pool or staging folder keeps whatever
+ * state it has, untouched.
+ *
+ * TWO ENUMERATIONS, because the two halves can be separated in either order and
+ * a sweep anchored on one is blind to the other:
+ *   1. the SIDECAR SET (`work/questions/` on `main`), small and cheap to list,
+ *      which finds a stale sidecar and the flag paired with it; and
+ *   2. the SUCCESS-TERMINAL BODIES that are flagged with NO sidecar beside them
+ *      ({@link collectStrandedTerminalFlags}), which finds the armed gate ALONE.
+ *
+ * (2) is not optional tidiness. It is the half that actually gates work, and a
+ * sweep anchored only on (1) reports success while any gate it cannot see stays
+ * armed. The sidecar is the
+ * half a human deletes by hand (it is the visible one, in a folder they scan),
+ * and deleting it REMOVES the only handle (1) has, stranding the flag for good.
+ * The discriminator that keeps (2) safe is POSITION, exactly as for (1): a bare
+ * flag is LEGAL on a pool/staging item (the `surface` rung's input) and residue
+ * only once the item has shipped, where `surface` can never run again.
+ *
+ * Best-effort and never throws.
+ */
+export async function classifyTerminalQuestionResidue(params) {
+    const { cwd, mainRef, env } = params;
+    // REFRESH `mainRef` FIRST, with an explicit refspec that writes exactly the ref
+    // we are about to read. Without this the pass reads a STALE view: the caller
+    // may not have fetched, and the lock sub-pass of the combined reconciliation
+    // early-returns (so does not refresh) when no locks are held. A failed refresh
+    // is NOT fatal, but it does mean the view may be stale in EITHER direction (an
+    // item may have left a terminal folder, or acquired an answer, since we last
+    // looked), which is exactly why the WRITE path re-derives this same
+    // classification against its own freshly-resolved base rather than trusting
+    // this snapshot.
+    await refreshMainRef(mainRef, params.arbiter, cwd, env);
+    return deriveTerminalQuestionResidue(mainRef, cwd, env);
+}
+/**
+ * The SYNC, PURE-of-network derivation of the question residue AT ONE COMMIT.
+ *
+ * Split out of {@link classifyTerminalQuestionResidue} so the WRITE path can
+ * re-derive the SAME classification against the base it is actually about to
+ * commit on, per contention attempt. That matters for correctness, not tidiness:
+ * a classification taken before a contention retry can be stale in two ways that
+ * both break a documented guarantee. An item may have LEFT its terminal folder
+ * (re-opened), in which case its sidecar is live again and must not be deleted;
+ * and a human may have written an ANSWER into a sidecar in the window, which must
+ * never be auto-deleted. Re-deriving against `base` closes both, because the
+ * commit is built on exactly that base.
+ */
+function deriveTerminalQuestionResidue(base, cwd, env) {
+    const mainRef = base;
+    const out = {
+        drainable: [],
+        answeredHeld: [],
+        staleFlags: [],
+        errors: [],
+    };
+    // The SECOND half of the residue, enumerated from the OTHER side. The sidecar
+    // sweep below can only ever see items that still HAVE a sidecar; this one finds
+    // the SUCCESS-terminal bodies whose gate is armed with no sidecar left to point
+    // at them. Both must run: they are the same defect observed through the two
+    // halves the surface path writes atomically, and either half can outlive the
+    // other.
+    collectStrandedTerminalFlags(mainRef, cwd, env, out);
+    const questionsDir = workFolderRel('questions');
+    const ls = run('git', ['ls-tree', '--name-only', `${mainRef}:${questionsDir}`], cwd, { env });
+    if (ls.status !== 0) {
+        // No `work/questions/` on main at all: nothing surfaced, nothing to drain.
+        return out;
+    }
+    for (const name of ls.stdout.split('\n').map((l) => l.trim())) {
+        if (name === '' || !isWorkItemFile(name)) {
+            continue;
+        }
+        const sidecarPath = `${questionsDir}/${name}`;
+        try {
+            // `<type>-<slug>.md` → `<type>:<slug>`. Only the CURRENT namespaces are
+            // addressable; a legacy `prd-` file has no current item-form and is left
+            // for the migration command.
+            const stem = name.replace(/\.md$/, '');
+            const dash = stem.indexOf('-');
+            const type = stem.slice(0, dash);
+            const slug = stem.slice(dash + 1);
+            if (!['task', 'spec', 'observation'].includes(type) || slug === '') {
+                continue;
+            }
+            const item = `${type}:${slug}`;
+            // Is the body at rest in a terminal folder on `main`?
+            const terminalHit = terminalMainPathsByKind(type, slug).find((c) => pathInCommit(mainRef, c.path, cwd, env));
+            if (terminalHit === undefined) {
+                // NOT terminal: a live item. Its question state is its own business
+                // a pending sidecar is a human's outstanding decision, and clearing a
+                // flag here is the trap above. Untouched.
+                continue;
+            }
+            // N5 GUARD: a mid-migration spec can have BOTH `spec-<slug>.md` and the
+            // legacy `prd-<slug>.md` on main (`sidecarPathCandidates` still resolves
+            // the legacy name for readers). Draining only the canonical one while
+            // clearing the flag would leave the legacy sidecar live against
+            // `needsAnswers:false`, which is precisely the
+            // `sidecar-without-needsAnswers` invariant violation this change exists
+            // to remove. If any OTHER candidate for this item still exists, leave the
+            // whole item to `dorfl prd-to-spec`, which renames the DATA.
+            const hasLegacyAlias = sidecarPathCandidates(item).some((c) => c !== sidecarPath && pathInCommit(mainRef, c, cwd, env));
+            if (hasLegacyAlias) {
+                continue;
+            }
+            const model = parseSidecar(catBlob(`${mainRef}:${sidecarPath}`, cwd, env));
+            const answered = model.entries.some((e) => isEntryAnswered(e));
+            const body = catBlob(`${mainRef}:${terminalHit.path}`, cwd, env);
+            const flagged = parseFrontmatter(body).needsAnswers === true;
+            const residue = {
+                item,
+                sidecarPath,
+                itemPath: terminalHit.path,
+                terminal: terminalHit.kind,
+                flagged,
+                answered,
+            };
+            if (answered) {
+                // A human WROTE an answer here and the apply rung never consumed it.
+                // Deleting it would discard prose the tool did not author, so this is
+                // surfaced for a human instead. (That the drain never runs on the
+                // human-answer path either is a SEPARATE defect; this pass must not
+                // paper over it by destroying the evidence.)
+                out.answeredHeld.push(residue);
+            }
+            else {
+                out.drainable.push(residue);
+            }
+        }
+        catch (err) {
+            out.errors.push({
+                item: sidecarPath,
+                message: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Find every SUCCESS-terminal body on `base` carrying `needsAnswers:true` with NO
+ * sidecar beside it, appending them to `out.staleFlags`.
+ *
+ * ENUMERATION COST is why this is a `git grep` and not a walk. The terminal
+ * folders are the repo's largest and most monotonically growing (this repo holds
+ * 404 done tasks), and this runs on the CLAIM path, so reading every terminal
+ * body per claim would be a real tax on a hot path. One `git grep -l` returns
+ * only the candidates, and the frontmatter parse runs over that short list.
+ *
+ * The pattern is ANCHORED to match the PARSER rather than the word.
+ * `parseFrontmatter` reads keys with `/^([A-Za-z0-9_.]+)\s*:\s*(.*)$/`, so a key
+ * it will honour is always at column 0; an unanchored needle instead matches
+ * every body that merely DISCUSSES the flag, which in `work/tasks/done/` here is
+ * 77 files against 18 anchored, and the truthy form narrows it to 1.
+ *
+ * The value part is matched LOOSELY on purpose (optional quote, any case),
+ * because `toBoolean` unquotes and lower-cases before comparing, so
+ * `needsAnswers: 'True'` is a real armed gate. A needle of `:\s*true` would read
+ * tighter and be WRONG: it would silently skip those bodies for ever, which is
+ * the blind-spot class this function exists to remove. A superset is the safe
+ * direction for a shortlist; a subset is not.
+ *
+ * The grep is still only a CANDIDATE FILTER, never the decision: prose can sit
+ * at column 0 too (`needsAnswers: true?` appears in this repo's own bodies), so
+ * every hit is confirmed by actually PARSING the frontmatter.
+ *
+ * Two git-isms are pinned rather than left to the environment:
+ *   - `core.quotePath=false`, or git C-quotes any non-ASCII path
+ *     (`"work/.../caf\303\251.md"`). A quoted line still starts with the
+ *     `<base>:` prefix but then fails the folder-prefix test, so such a body
+ *     would be SILENTLY skipped for ever, a permanent blind spot of exactly the
+ *     class this function exists to remove.
+ *   - `--full-name` + `:(top,literal)` pathspecs, because `git grep`'s pathspecs
+ *     are CWD-RELATIVE (unlike the `ls-tree`/`cat-file` probes elsewhere here,
+ *     which are tree-relative) and are globs. Without these, running any dorfl
+ *     command from a SUBDIRECTORY makes this half a silent no-op while the
+ *     sidecar half keeps working.
+ *
+ * Never throws; a failed grep yields no candidates, which leaves state alone.
+ */
+function collectStrandedTerminalFlags(base, cwd, env, out) {
+    const folders = successTerminalFolders();
+    if (folders.length === 0) {
+        return;
+    }
+    // `-l` names files only, `-I` skips binaries. Exit 1 means NO MATCH, which
+    // ALSO covers "the folder does not exist on this base yet" (verified: an
+    // absent pathspec folder exits 1 with no stderr), and an absent lifecycle
+    // folder is legal per WORK-CONTRACT rule 3. Any OTHER non-zero is a genuine
+    // fault and is REPORTED rather than swallowed: degrading silently to "no
+    // candidates" would leave this half a no-op while the sidecar half keeps
+    // reporting success, which is the very "reports success while the gate stays
+    // armed" shape this change exists to correct.
+    const grep = run('git', [
+        '-c',
+        'core.quotePath=false',
+        'grep',
+        '-l',
+        '-I',
+        '--full-name',
+        '-E',
+        '^needsAnswers:[[:space:]]*[\'"]?[Tt][Rr][Uu][Ee]',
+        base,
+        '--',
+        ...folders.map((f) => `:(top,literal)${f.folder}`),
+    ], cwd, { env });
+    if (grep.status !== 0) {
+        if (grep.status !== 1) {
+            out.errors.push({
+                item: '(stranded-flag scan)',
+                message: `git grep over the terminal folders failed (exit ${grep.status}): ` +
+                    `${grep.stderr.trim() || 'no stderr'}; stranded gates were NOT scanned.`,
+            });
+        }
+        return;
+    }
+    const prefix = `${base}:`;
+    for (const line of grep.stdout.split('\n')) {
+        const raw = line.trim();
+        if (raw === '' || !raw.startsWith(prefix)) {
+            continue;
+        }
+        const path = raw.slice(prefix.length);
+        try {
+            const home = folders.find((f) => path.startsWith(`${f.folder}/`));
+            if (home === undefined) {
+                continue;
+            }
+            const name = path.slice(home.folder.length + 1);
+            // Direct children only: a nested path is not an item body.
+            if (name.includes('/') || !isWorkItemFile(name)) {
+                continue;
+            }
+            // Case-INSENSITIVE to match `isWorkItemFile` above: a `Foo.MD` body must
+            // yield the slug `Foo`, or the sidecar-existence guard below would probe
+            // the wrong path and could clear a gate whose sidecar holds an answer.
+            const slug = name.replace(/\.md$/i, '');
+            if (slug === '') {
+                continue;
+            }
+            const item = `${home.type}:${slug}`;
+            // A sidecar STILL EXISTS for this item (canonical or legacy alias) ⇒ this
+            // is the sidecar-anchored sweep's business, not ours. Skipping keeps the
+            // two enumerations DISJOINT, so an item is never planned twice in one
+            // commit and the answered-sidecar carve-out cannot be bypassed through
+            // this path (an item held for an unapplied human answer keeps its flag).
+            if (sidecarPathCandidates(item).some((c) => pathInCommit(base, c, cwd, env))) {
+                continue;
+            }
+            // CONFIRM against the parsed frontmatter: the grep only shortlisted.
+            const body = catBlob(`${base}:${path}`, cwd, env);
+            if (parseFrontmatter(body).needsAnswers !== true) {
+                continue;
+            }
+            out.staleFlags.push({ item, itemPath: path });
+        }
+        catch (err) {
+            out.errors.push({
+                item: path,
+                message: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+}
+/**
+ * Drain the stranded question state {@link classifyTerminalQuestionResidue}
+ * finds, in ONE tree-less commit CAS-published to the arbiter's `main` through
+ * the SAME {@link runTreelessLedgerMove} core the surface path uses (same
+ * contention-retry, same lease, same write seam; there is no second mechanism).
+ *
+ * WHAT IT CLEARS, and the deliberate asymmetry between the two terminals. Note
+ * the terminal SET first: `specs/tasked/` is deliberately NOT in this map at all
+ * (see {@link terminalMainPathsByKind}), so nothing below applies to a tasked
+ * spec, whose question state stays untouched in both halves.
+ *   - the SIDECAR is deleted for EITHER terminal in the map. A question asking
+ *     whether to cancel an item that has already come to rest is stale in both
+ *     cases, and it sits in a folder a human scans carrying a destructive
+ *     default.
+ *   - the `needsAnswers` FLAG is cleared ONLY for a `completed` terminal
+ *     (`tasks/done/`). On a `wont-proceed` terminal
+ *     (`tasks/cancelled/`, `specs/dropped/`) the flag is KEPT, because an item
+ *     can be cancelled precisely BECAUSE its questions were never answered: there
+ *     the flag is accurate history, not residue, and the body may carry a real
+ *     `## Open questions` section saying so. Keeping it is harmless, a terminal
+ *     item is in no pool, so the flag gates nothing.
+ *   - a SUCCESS-terminal item whose gate is armed with NO sidecar left beside it
+ *     has that FLAG cleared and nothing deleted (there is nothing to delete).
+ *     Restricted to the `completed` terminal by the same asymmetry above.
+ *
+ * A sidecar with ANY answered entry is never touched (see the classifier), and
+ * an item still holding such a sidecar is excluded from the flag-only half too,
+ * so the carve-out cannot be bypassed by clearing its gate.
+ *
+ * Best-effort: it never throws, and any fault leaves the state exactly as it was.
+ */
+export async function reconcileTerminalQuestionResidue(params) {
+    const { cwd, arbiter, mainRef, env } = params;
+    const note = params.note ?? (() => { });
+    const result = {
+        drained: [],
+        unflagged: [],
+        answeredHeld: [],
+        errors: [],
+    };
+    let report;
+    try {
+        report = await classifyTerminalQuestionResidue({
+            cwd,
+            arbiter,
+            mainRef,
+            env,
+            mainAlreadyFresh: params.mainAlreadyFresh,
+        });
+    }
+    catch (err) {
+        result.errors.push({
+            item: '(classify)',
+            message: err instanceof Error ? err.message : String(err),
+        });
+        return result;
+    }
+    result.answeredHeld = report.answeredHeld.map((r) => r.item);
+    result.errors.push(...report.errors);
+    if (report.drainable.length === 0 && report.staleFlags.length === 0) {
+        return result;
+    }
+    // What the LANDED commit ACTUALLY did, filled in by the plan against the base
+    // it committed on. The pre-plan `report` above is only a fast "is there
+    // anything to do?" probe; reporting from it would claim a gate was disarmed
+    // when a contention retry re-derived the residue and skipped the item.
+    let applied = [];
+    // Filled by the PLAN with what it actually STAGED (not what it intended), so a
+    // body the marker writer cannot annotate is never reported as unflagged.
+    const clearedSidecarFlags = [];
+    const clearedStaleFlags = [];
+    // NEVER THROW. `runTreelessLedgerMove` and the git plumbing inside the plan
+    // both throw on any non-zero git, and this pass runs from the CLAIM path as
+    // OPPORTUNISTIC HYGIENE on unrelated items. A fault here (a stale scratch ref,
+    // a protected `main`, a permission refusal) must degrade to "left it alone",
+    // never fail the caller's actual work.
+    let landed = false;
+    try {
+        landed = await runTreelessLedgerMove({
+            cwd,
+            // The ref name only has to be unique for the scratch ref; this pass is
+            // batch (many items, one commit), so it is not keyed to a single slug.
+            slug: 'terminal-question-drain',
+            arbiter,
+            kind: 'needs-attention',
+            onContended: 'drain stranded questions',
+            explicitMainRefspec: true,
+            env,
+            note,
+            // RE-PLANNED per attempt against the freshly-fetched base: the residue is
+            // RE-DERIVED from that base, never reused from the probe above, so an item
+            // re-opened out of its terminal folder, or a sidecar a human answered, in the
+            // contention window is correctly left alone.
+            plan: (base) => {
+                const fresh = deriveTerminalQuestionResidue(base, cwd, env);
+                applied = fresh.drainable;
+                result.answeredHeld = fresh.answeredHeld.map((r) => r.item);
+                return prepareTerminalQuestionDrainCommit({
+                    cwd,
+                    base,
+                    residue: fresh.drainable,
+                    staleFlags: fresh.staleFlags,
+                    clearedSidecarFlags,
+                    clearedStaleFlags,
+                    env,
+                });
+            },
+        });
+    }
+    catch (err) {
+        result.errors.push({
+            item: '(publish)',
+            message: err instanceof Error ? err.message : String(err),
+        });
+        return result;
+    }
+    if (!landed) {
+        result.errors.push({
+            item: '(publish)',
+            message: 'the stranded-question drain did not land on the arbiter’s main ' +
+                '(contention exhausted, or nothing to do); state left untouched.',
+        });
+        return result;
+    }
+    for (const r of applied) {
+        result.drained.push(r.item);
+    }
+    // `unflagged` reports what the commit ACTUALLY staged, from both halves. The
+    // flag-only half never appears in `drained`: it deletes nothing.
+    for (const r of [...clearedSidecarFlags, ...clearedStaleFlags]) {
+        result.unflagged.push(r.item);
+    }
+    return result;
+}
+/**
+ * Stage `itemPath` with `needsAnswers` cleared, into the scratch index the drain
+ * commit is being built in. Shared by BOTH halves of the residue (the
+ * sidecar-paired flag and the stranded flag-only one) so they can never disagree
+ * about what clearing a gate means.
+ *
+ * Defense-in-depth, mirroring the surface path's guard in the opposite
+ * direction: if the marker does not parse back as `false`, the body is left
+ * ALONE rather than written as something we cannot vouch for. Every uncertainty
+ * resolves to LEAVING STATE ALONE.
+ *
+ * RETURNS whether the gate was actually STAGED, so callers report EFFECT rather
+ * than INTENT. That distinction is load-bearing here: a body this cannot
+ * annotate (e.g. duplicate `needsAnswers` keys, where the writer replaces the
+ * FIRST and the parser reads the LAST) would otherwise be reported as unflagged
+ * on every claim for ever while its gate stayed armed, the precise
+ * "reports success while the defect remains" failure this whole change exists to
+ * correct.
+ */
+function clearNeedsAnswersInIndex(itemPath, base, cwd, env, withIndex) {
+    if (!pathInCommit(base, itemPath, cwd, env)) {
+        return false;
+    }
+    const body = catBlob(`${base}:${itemPath}`, cwd, env);
+    const cleared = setNeedsAnswersMarker(body, false);
+    if (parseFrontmatter(cleared).needsAnswers !== false) {
+        return false;
+    }
+    const blob = hashObject(cleared, cwd, env);
+    gitHard(['update-index', '--add', '--cacheinfo', `100644,${blob},${itemPath}`], cwd, withIndex);
+    return true;
+}
+/**
+ * Build the ONE tree-less commit that removes every drainable sidecar and clears
+ * the `needsAnswers` flag on every `completed`-terminal body, using PLUMBING on a
+ * SCRATCH INDEX (the caller's index/HEAD/working tree are never touched)
+ * exactly as {@link prepareTreelessSurfaceCommit} does in the opposite direction.
+ *
+ * Batched into a single commit on purpose: the residue is a SET, one commit is
+ * one CAS against `main` instead of N, and the whole drain then lands or does not
+ * land atomically.
+ */
+function prepareTerminalQuestionDrainCommit(params) {
+    const { cwd, base, residue, env, clearedSidecarFlags, clearedStaleFlags } = params;
+    clearedSidecarFlags.length = 0;
+    clearedStaleFlags.length = 0;
+    // RE-DERIVE against THIS base: anything already gone is not our business.
+    const live = residue.filter((r) => pathInCommit(base, r.sidecarPath, cwd, env));
+    const liveFlags = params.staleFlags.filter((r) => pathInCommit(base, r.itemPath, cwd, env));
+    if (live.length === 0 && liveFlags.length === 0) {
+        return 'already-done';
+    }
+    const scratchIndex = join(tmpdir(), `dorfl-question-drain-${process.pid}-${Date.now()}.index`);
+    const withIndex = {
+        ...(env ?? process.env),
+        GIT_INDEX_FILE: scratchIndex,
+    };
+    try {
+        gitHard(['read-tree', base], cwd, withIndex);
+        for (const r of live) {
+            // Remove the stale sidecar.
+            gitHard(['update-index', '--force-remove', r.sidecarPath], cwd, withIndex);
+            // Clear the flag ONLY on a `completed` terminal (see the doc above).
+            if (r.terminal !== 'completed' || !r.flagged) {
+                continue;
+            }
+            if (clearNeedsAnswersInIndex(r.itemPath, base, cwd, env, withIndex)) {
+                clearedSidecarFlags.push(r);
+            }
+        }
+        // The FLAG-ONLY half: a SUCCESS terminal whose sidecar is already gone. No
+        // `--force-remove` here, because there is nothing to delete; the armed gate IS the
+        // whole residue.
+        // Record what was actually STAGED: a body we could not annotate is dropped
+        // from the report rather than claimed as cleared.
+        for (const r of liveFlags) {
+            if (clearNeedsAnswersInIndex(r.itemPath, base, cwd, env, withIndex)) {
+                clearedStaleFlags.push(r);
+            }
+        }
+        const tree = runHard(['write-tree'], cwd, withIndex).stdout.trim();
+        const touched = live.length + liveFlags.length;
+        const only = live[0]?.item ?? liveFlags[0]?.item;
+        const subject = touched === 1
+            ? `drain stranded question state for ${only} (terminal on main)`
+            : `drain stranded question state for ${touched} terminal items`;
+        const commit = runHard(['commit-tree', tree, '-p', base, '-m', subject], cwd, env).stdout.trim();
+        const ref = 'refs/dorfl/question-drain/batch';
+        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