dorfl 0.14.2 → 0.15.0

package/dist/needs-attention.js

@@ -3,7 +3,7 @@ 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, rebaseContinuedBranchOntoMain, } from './continue-branch.js';
+import { branchAheadOf, rebaseContinuedBranchOntoMain, describeContinueRebaseFailure, } from './continue-branch.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';
@@ -11,6 +11,7 @@ import { refreshArbiterRefs, resolveArbiterBranch } from './arbiter-refs.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';
+import { saveCrashedRunWork, } from './crashed-run-save.js';
 /**
  * The **needs-attention mechanism** (ADR `ledger-status-on-per-item-lock-refs`;
  * spec `ledger-status-per-item-lock-refs`; ADR §12 for the original folder model).
@@ -91,18 +92,7 @@ export async function routeToNeedsAttention(options) {
     //    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 hadWip = commitAbortedWork({ cwd, slug, 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}`);
@@ -123,6 +113,9 @@ export async function routeToNeedsAttention(options) {
         if (branchAheadOf(cwd, branch, 'main', env)) {
             const arbiter = options.arbiter;
             const result = await retryWithBackoff(async () => {
+                // Write-seam implementation: `routeToNeedsAttention` is reached only
+                // through `ledgerWrite.applyNeedsAttentionTransition` or
+                // `refWrite.saveWorkBranch` (guard: `write-sites-through-seams.test.ts`).
                 const r = gitSoftRun(['push', arbiter, `${branch}:${branch}`], cwd, env);
                 return r.status === 0
                     ? { ok: true, value: undefined }
@@ -147,6 +140,31 @@ export async function routeToNeedsAttention(options) {
     }
     return { moved: true, commitMessage, moveCommit, branchPush, pushError };
 }
+/**
+ * The LOCAL half of {@link routeToNeedsAttention}'s save: commit whatever the
+ * agent left uncommitted (`git add -A`) as a plain wip commit on the current
+ * branch tip. Returns whether a commit was made (a clean tree makes none).
+ *
+ * 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).
+ *
+ * The CI agent phase (task `ci-split-build-path-non-integrate-intents`) runs
+ * this on its own when its pipeline halts at a needs-attention bounce, so the
+ * wip travels in the handoff bundle; the apply phase then re-runs the whole
+ * route on the bundle's tip, where this finds a clean tree and commits nothing.
+ */
+export function commitAbortedWork(params) {
+    const { cwd, slug, env } = params;
+    gitHard(['add', '-A'], cwd, env);
+    if (nothingStaged(cwd, env)) {
+        return false;
+    }
+    gitHard(['commit', '-q', '-m', `chore(${slug}): save aborted work (wip)`], cwd, env);
+    return true;
+}
 /**
  * The clean re-queue (ADR §12 / WORK-CONTRACT return path): once the human has
  * resolved the cause, move the stuck item back to `work/tasks/ready/<slug>.md` and
@@ -185,9 +203,10 @@ export async function routeToNeedsAttention(options) {
  *     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.
+ *   - **`-m "<note>"` = HANDOFF NOTE.** When `message` is set, ADD a dated
+ *     `## Requeue YYYY-MM-DD` section to the item BODY, just before
+ *     `## Acceptance criteria` (additive; accumulates over repeated requeues,
+ *     oldest first) for the next agent. Applies to BOTH modes.
  *
  * Like the move, NEVER throws for the expected "not in needs-attention" case.
  */
@@ -233,6 +252,10 @@ export async function deleteRemoteWorkBranchIfPresent(options) {
     const branch = workBranchRef('task', slug);
     await gitSoftAsync(['update-ref', '-d', `refs/remotes/${arbiter}/${branch}`], cwd, env);
     await gitSoftAsync(['branch', '-D', branch], cwd, env);
+    // Write-seam implementation: callers reach this through
+    // `refWrite.deleteRemoteWorkBranch`, or through `returnToBacklog` behind
+    // `ledgerWrite.applyReturnToBacklogTransition` (guard:
+    // `write-sites-through-seams.test.ts`).
     const del = await gitSoftAsync(['push', arbiter, '--delete', branch], cwd, env);
     if (del.status === 0) {
         return { branch, status: 'deleted', stderr: '' };
@@ -270,6 +293,17 @@ export async function returnToBacklog(options) {
             reasonNotMoved: `no git remote named '${arbiter}' (set one, or pass --arbiter).`,
         };
     }
+    // Destructive vs non-destructive are exclusive verbs on the same escalation.
+    // Checked up front (before any lock is read or taken) so the refusal is the
+    // same whether the item's lock is held or already released by a surface.
+    if (options.reconcile && options.reset) {
+        return {
+            moved: false,
+            reasonNotMoved: `requeue for '${slug}': --reconcile and --reset are mutually ` +
+                'exclusive (non-destructive recovery vs destructive last resort). ' +
+                'Pick one.',
+        };
+    }
     // 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.
@@ -310,7 +344,53 @@ export async function returnToBacklog(options) {
     catch {
         held = await readLocalItemLock(slug, cwd, env);
     }
+    // RELEASED-LOCK RECOVERY (task
+    // `requeue-reset-and-reconcile-work-after-the-lock-was-released`). A surface
+    // (`surfaceStuckToNeedsAttention`) RELEASES the per-item lock after landing the
+    // question sidecar, so a surfaced item with a KEPT work branch has no held lock,
+    // yet it is exactly what `--reconcile` (re-sync + retry) and `--reset` (discard,
+    // start fresh) exist for. When the item's body rests in the pool/staging on
+    // `<arbiter>/main` AND its `work/task-<slug>` branch is on the arbiter, take a
+    // SHORT per-item lock (create-only, like claim) so no claim can continue from
+    // the branch while it is being rebased or deleted, run the ordinary held-lock
+    // path, and give the short lock back on every outcome. Plain `requeue` stays a
+    // no-op (the next claim already continues from the kept branch).
+    let shortLock = false;
+    let releasedRecoverable;
     if (!held) {
+        releasedRecoverable = await probeReleasedRecoverableItem({
+            cwd,
+            slug,
+            arbiter,
+            branch: continueBranchName,
+            env,
+        });
+        if (releasedRecoverable !== undefined &&
+            (options.reset || options.reconcile)) {
+            const verb = options.reset ? '--reset' : '--reconcile';
+            const acquired = await acquireItemLock({
+                item: `task:${slug}`,
+                action: 'implement',
+                cwd,
+                arbiter,
+                env,
+            });
+            if (acquired.outcome !== 'acquired') {
+                const message = `requeue ${verb} for '${slug}': its lock was already released, ` +
+                    'but the short lock this recovery needs could not be taken ' +
+                    (acquired.outcome === 'lost'
+                        ? '(another run claimed the item meanwhile); nothing was changed.'
+                        : `(${acquired.message}); nothing was changed. Try again shortly.`);
+                note(message);
+                return { moved: false, reasonNotMoved: message };
+            }
+            shortLock = true;
+            note(`'${slug}' has no held lock (a surface or earlier requeue already ` +
+                `released it); took a short lock to ${options.reset ? 'discard' : 'reconcile'} ` +
+                `the kept ${continueBranchName} (${verb}).`);
+        }
+    }
+    if (!held && !shortLock) {
         // CROSS-NAMESPACE HINT (observation
         // `crashed-do-spec-strands-a-tasking-lock-no-verb-releases`). `requeue` is a
         // TASK-only verb, so a bare `<slug>` resolves to `task:<slug>` and finds no
@@ -351,15 +431,139 @@ export async function returnToBacklog(options) {
         catch {
             // Best-effort hint only: fall through to the plain refusal.
         }
+        // A released item that DOES rest in the pool with a kept branch (plain
+        // requeue only; `--reset`/`--reconcile` took the short-lock path above):
+        // nothing to release, and the next claim already continues from the branch.
+        // Say so, and name the two verbs that DO act on a released item.
+        const keptHint = releasedRecoverable !== undefined
+            ? ` NOTE: '${slug}' rests in the pool (${releasedRecoverable.bodyRel}) ` +
+                `with a kept work branch ${continueBranchName} on ${arbiter}; the ` +
+                'next claim continues from it, so plain requeue has nothing to do. ' +
+                'To act on the kept branch: `requeue --reconcile` (non-destructive ' +
+                're-sync + rebase retry) or `requeue --reset` (DESTRUCTIVELY discard ' +
+                'it and start fresh).'
+            : '';
         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).' +
-                specHint,
+                specHint +
+                keptHint,
         };
     }
+    // CRASHED-RUN SAVE (task
+    // `a-crashed-runs-local-work-is-saved-before-its-lock-is-released`). A run
+    // killed mid-agent leaves its lock held and its job worktree retained, possibly
+    // with commits (or a wip residue) the arbiter's work branch lacks. Releasing
+    // the lock over them hands the item to a next claim (or a `gc --force`) that
+    // cuts that worktree away, so SAVE them first: wip-commit + push the work
+    // branch. A failed save KEEPS the lock (and the worktree) and says so. Only on
+    // a HELD lock (a short recovery lock means the run already surfaced, its lock
+    // released) and never on `--reset` (which discards the branch by design).
+    let crashedRunSave;
+    if (held && !options.reset && options.workspacesDir !== undefined) {
+        crashedRunSave = await saveCrashedRunWork({
+            cwd,
+            arbiter,
+            slug,
+            workspacesDir: options.workspacesDir,
+            env,
+            note,
+            ...(options.sleep !== undefined ? { sleep: options.sleep } : {}),
+        });
+        if (crashedRunSave.kind === 'not-saved') {
+            const message = `requeue for '${slug}': its crashed run left work in ` +
+                `${crashedRunSave.dir} that the arbiter's ${crashedRunSave.branch} ` +
+                `lacks, and it could not be saved: ${crashedRunSave.detail}. The lock ` +
+                'is KEPT (not released) and the worktree left in place, so nothing is ' +
+                `lost. Push ${crashedRunSave.branch} from that worktree by hand, then ` +
+                '`requeue` again.';
+            note(message);
+            return { moved: false, reasonNotMoved: message, crashedRunSave };
+        }
+        if (crashedRunSave.kind === 'saved') {
+            // The guard below reads the arbiter's branch from THIS clone: bring the
+            // just-pushed tip (and its objects) in.
+            await refreshArbiterRefs({
+                cwd,
+                arbiter,
+                branches: ['main', continueBranchName],
+                env,
+            });
+        }
+    }
+    const heldResult = await requeueHeldItem({
+        options,
+        arbiter,
+        continueBranchName,
+        note,
+    });
+    const result = crashedRunSave !== undefined ? { ...heldResult, crashedRunSave } : heldResult;
+    if (shortLock && !result.moved) {
+        // Give the SHORT lock back: the item returns to exactly the released,
+        // surfaced state it was in (its question sidecar untouched). A failed
+        // release here is reported, never thrown.
+        const back = await releaseItemLock({
+            item: `task:${slug}`,
+            cwd,
+            arbiter,
+            env,
+        });
+        const tail = back.outcome === 'error'
+            ? ` WARNING: could not release the short recovery lock this requeue ` +
+                `took (${back.message}); clear it with \`dorfl release-lock ` +
+                `task:${slug}\`.`
+            : ' (The short recovery lock this requeue took was released again; ' +
+                'the item stays as it was before this requeue.)';
+        note(tail.trim());
+        return { ...result, reasonNotMoved: (result.reasonNotMoved ?? '') + tail };
+    }
+    return result;
+}
+/**
+ * Is `<slug>` a RELEASED-lock task that `requeue --reset`/`--reconcile` can act
+ * on? True iff its body rests in `tasks/ready/` or `tasks/backlog/` on
+ * `<arbiter>/main` (the D1 probe a surface uses) AND the arbiter HAS its
+ * `work/task-<slug>` branch (arbiter-authoritative `ls-remote`). A surfaced item
+ * (question sidecar + `needsAnswers:true`, lock released) is the motivating
+ * case, but the sidecar is NOT required: a plain requeue that already released
+ * the lock leaves the same recoverable shape. An unknown slug (no body) or a
+ * pooled item with no kept branch answers `undefined`, so the refusal for those
+ * is unchanged. Best-effort: an unreachable arbiter answers `undefined`.
+ */
+async function probeReleasedRecoverableItem(params) {
+    const { cwd, slug, arbiter, branch, env } = params;
+    try {
+        const bodyRel = await resolveBounceItemBodyPathOnMain({
+            cwd,
+            item: `task:${slug}`,
+            arbiter,
+            env,
+        });
+        if (bodyRel === undefined) {
+            return undefined;
+        }
+        const resolved = await resolveArbiterBranch({ cwd, arbiter, branch, env });
+        if (!resolved.trustworthy || resolved.sha === undefined) {
+            return undefined;
+        }
+        return { bodyRel, branchSha: resolved.sha };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The body of {@link returnToBacklog} once the item's per-item lock is HELD
+ * (either a pre-existing stuck/active hold, or the short lock a released-lock
+ * `--reset`/`--reconcile` just took): the reconcile / reset / keep+continue
+ * guard, the optional handoff note, and the lock release.
+ */
+async function requeueHeldItem(params) {
+    const { options, arbiter, continueBranchName, note } = params;
+    const { cwd, slug, env } = options;
     // `--reconcile`: the NON-DESTRUCTIVE recovery rung (task
     // `requeue-reconcile-nondestructive-recovery-verb`, parent observation
     // `rebase-conflict-on-continue-needs-nondestructive-recovery-not-reset`).
@@ -377,14 +581,6 @@ export async function returnToBacklog(options) {
     // 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,
@@ -396,7 +592,9 @@ export async function returnToBacklog(options) {
             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 ` +
+                (attempt.genuineConflict === false
+                    ? `the rebase still fails (${attempt.detail}). The `
+                    : `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, ' +
@@ -532,8 +730,9 @@ export async function returnToBacklog(options) {
         '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
+    // `-m "<note>"` (the handoff steer): ADD a dated `## Requeue YYYY-MM-DD`
+    // section (before `## Acceptance criteria`, clear of a kept branch's done-move
+    // tail) 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
@@ -564,7 +763,7 @@ export async function returnToBacklog(options) {
                     base,
                     sourceRel: bodyRel,
                     destRel: bodyRel,
-                    transformBody: (body) => appendRequeueNoteText(body, handoff),
+                    transformBody: (body) => insertRequeueNoteText(body, handoff),
                     commitMessage: `chore(${slug}): requeue handoff note`,
                     refNamespace: 'requeue',
                     env,
@@ -663,12 +862,20 @@ async function attemptReconcile(params) {
     }
     try {
         const rebase = rebaseContinuedBranchOntoMain(worktree, arbMainRef, env);
-        if (rebase.kind === 'conflict') {
-            return { kind: 'conflict', detail: 'rebase conflicted after re-sync' };
+        if (rebase.kind !== 'clean') {
+            return {
+                kind: 'conflict',
+                detail: `rebase after re-sync ${describeContinueRebaseFailure(rebase)}`,
+                genuineConflict: rebase.kind === 'conflict',
+            };
         }
         // 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}`;
+        // WRITE-SEAM EXEMPT: `attemptReconcile` backs the human-only
+        // `requeue --reconcile` verb, never a CI path, so this reconciled
+        // kept-branch push stays direct (task
+        // `ci-split-route-direct-writes-through-seams`).
         const push = gitSoftRun([
             'push',
             arbiter,
@@ -2055,20 +2262,50 @@ const BOUNCE_BODY_PROBE_ORDER = {
     spec: ['specs-ready', 'specs-proposed'],
     observation: ['observations'],
 };
+/** The body headings a requeue handoff note is inserted BEFORE, in preference
+ * order (see {@link insertRequeueNoteText}). `## Prompt` is the fallback anchor:
+ * every BUILDABLE task has one (`resolveTask` refuses a body without it), so a
+ * buildable body never falls through to the tail. */
+const REQUEUE_NOTE_ANCHORS = [
+    /^##\s+Acceptance criteria\s*$/m,
+    /^##\s+Prompt\s*$/m,
+];
 /**
- * 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.
+ * Add a dated `## Requeue YYYY-MM-DD` handoff section to an item body's TEXT
+ * (additive — never overwrites; repeated requeues accumulate a handoff log,
+ * oldest first). 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 blocks.
+ *
+ * PLACEMENT (task `requeue-handoff-note-does-not-conflict-with-the-kept-done-move`):
+ * the section is inserted immediately BEFORE the `## Acceptance criteria`
+ * heading, NOT at the end of the body. A kept work branch the next claim
+ * CONTINUES from may already have done-moved this body AND appended its
+ * `## Decisions` block at the END; a tail-appended note on `main` then collided
+ * with that tail in the continue rebase (which never auto-resolves, ADR §10) and
+ * bounced the item. Mid-body, the two edits are disjoint hunks and the rebase
+ * merges them cleanly. A body with no `## Acceptance criteria` heading anchors on
+ * `## Prompt` instead (a chore task written without acceptance criteria used to
+ * fall back to the tail and still collide); only a body with NEITHER heading
+ * (which is not buildable anyway) falls back to the end. The continue prompt reads every `## Requeue`
+ * section wherever it sits (`extractRequeueNotes`), so the note still reaches
+ * the continuing agent.
  *
  * 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) {
+export function insertRequeueNoteText(content, message) {
     const date = new Date().toISOString().slice(0, 10);
-    const base = content.replace(/\s*$/, '');
-    return [base, '', `${REQUEUE_HEADING_PREFIX} ${date}`, '', message, ''].join('\n');
+    const section = `${REQUEUE_HEADING_PREFIX} ${date}\n\n${message}\n`;
+    const anchor = REQUEUE_NOTE_ANCHORS.map((re) => re.exec(content)).find((m) => m !== null);
+    if (anchor === undefined || anchor === null) {
+        const base = content.replace(/\s*$/, '');
+        return `${base}\n\n${section}`;
+    }
+    const before = content.slice(0, anchor.index).replace(/\s*$/, '');
+    const after = content.slice(anchor.index);
+    return `${before}\n\n${section}\n${after}`;
 }
 /**
  * Extract the prose written under the `## Needs attention` heading from an item