dorfl 0.14.2 → 0.15.0

package/src/needs-attention.ts

@@ -12,6 +12,7 @@ import {run, runAsync, type RunResult} from './git.js';
 import {
 	branchAheadOf,
 	rebaseContinuedBranchOntoMain,
+	describeContinueRebaseFailure,
 } from './continue-branch.js';
 import {
 	acquireItemLock,
@@ -45,6 +46,10 @@ import {
 	type BackoffOptions,
 	type Sleep,
 } from './retry-backoff.js';
+import {
+	saveCrashedRunWork,
+	type CrashedRunSaveOutcome,
+} from './crashed-run-save.js';
 
 /**
  * The **needs-attention mechanism** (ADR `ledger-status-on-per-item-lock-refs`;
@@ -221,13 +226,29 @@ export interface ReturnToBacklogOptions {
 	reconcile?: boolean;
 	/**
 	 * `requeue -m "<note>"` (the handoff note): an optional human steer for the
-	 * NEXT agent. APPENDED (never overwritten) as a dated `## Requeue YYYY-MM-DD`
-	 * section to the item BODY before the move — the ledger file is the durable,
+	 * NEXT agent. ADDED (never overwritten) as a dated `## Requeue YYYY-MM-DD`
+	 * section to the item BODY, just before `## Acceptance criteria` (so it never
+	 * collides with a kept branch's done-move tail; see `insertRequeueNoteText`),
+	 * before the move — the ledger file is the durable,
 	 * conflict-safe, cross-machine home (same place the needs-attention reason
 	 * lives). Repeated requeues ACCUMULATE a handoff log. Applies to BOTH modes
 	 * (a steer is relevant even on `--reset`).
 	 */
 	message?: string;
+	/**
+	 * The execution working area (config `workspacesDir`) where `do --isolated`
+	 * retains job worktrees. When given, a HELD lock's retained job worktree is
+	 * checked BEFORE the release (task
+	 * `a-crashed-runs-local-work-is-saved-before-its-lock-is-released`): a crashed
+	 * run's local-only commits / uncommitted residue are committed + pushed to
+	 * `work/task-<slug>` first (see {@link saveCrashedRunWork}), and a failed save
+	 * KEEPS the lock. Not consulted on `--reset` (which discards the work by
+	 * design). Omitted ⇒ no worktree is looked at (the in-process callers, e.g.
+	 * the deadline checkpoint, which saved its own branch already).
+	 */
+	workspacesDir?: string;
+	/** No-wait sleep for the crashed-run save push's backoff (tests). */
+	sleep?: Sleep;
 	/** Environment for child git processes. */
 	env?: NodeJS.ProcessEnv;
 	/** Sink for human-readable progress notes. */
@@ -251,6 +272,12 @@ export interface ReturnToBacklogResult {
 	reconciled?: boolean;
 	/** When NOT moved, why (e.g. the slug held no recoverable per-item lock on the arbiter, or a failed --reset delete). */
 	reasonNotMoved?: string;
+	/**
+	 * What the crashed-run save found/did in the slug's retained job worktree
+	 * (only when {@link ReturnToBacklogOptions.workspacesDir} was given and a lock
+	 * was held; absent otherwise).
+	 */
+	crashedRunSave?: CrashedRunSaveOutcome;
 	/**
 	 * **The ONE resolved continue-branch state** this requeue decided from — so a
 	 * CALLER reports the same reality the requeue acted on instead of running its
@@ -383,18 +410,7 @@ export async function routeToNeedsAttention(
 	//    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}`);
@@ -417,6 +433,9 @@ export async function routeToNeedsAttention(
 			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,
@@ -451,6 +470,40 @@ export async function routeToNeedsAttention(
 	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: {
+	cwd: string;
+	slug: string;
+	env?: NodeJS.ProcessEnv;
+}): boolean {
+	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
@@ -489,9 +542,10 @@ export async function routeToNeedsAttention(
  *     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.
  */
@@ -586,6 +640,10 @@ export async function deleteRemoteWorkBranchIfPresent(
 		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,
@@ -636,6 +694,19 @@ export async function returnToBacklog(
 		};
 	}
 
+	// 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.
@@ -676,7 +747,58 @@ export async function returnToBacklog(
 	} 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: ReleasedRecoverableItem | undefined;
 	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
@@ -716,6 +838,19 @@ export async function returnToBacklog(
 		} 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:
@@ -723,10 +858,147 @@ export async function returnToBacklog(
 				'(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: CrashedRunSaveOutcome | undefined;
+	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;
+}
+
+/** A task whose lock is RELEASED but which rests in the pool with a kept branch. */
+interface ReleasedRecoverableItem {
+	/** The body's on-`main` path (`work/tasks/ready/<slug>.md` or staging). */
+	bodyRel: string;
+	/** The kept branch's tip on the arbiter. */
+	branchSha: string;
+}
+
+/**
+ * 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: {
+	cwd: string;
+	slug: string;
+	arbiter: string;
+	branch: string;
+	env: NodeJS.ProcessEnv | undefined;
+}): Promise<ReleasedRecoverableItem | undefined> {
+	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: {
+	options: ReturnToBacklogOptions;
+	arbiter: string;
+	continueBranchName: string;
+	note: (message: string) => void;
+}): Promise<ReturnToBacklogResult> {
+	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`).
@@ -744,15 +1016,6 @@ export async function returnToBacklog(
 	// deletes the remote branch — this verb's contract is "keep the work".
 	let reconciled: boolean | undefined;
 	if (options.reconcile) {
-		if (options.reset) {
-			return {
-				moved: false,
-				reasonNotMoved:
-					`requeue for '${slug}': --reconcile and --reset are mutually ` +
-					'exclusive (non-destructive recovery vs destructive last resort). ' +
-					'Pick one.',
-			};
-		}
 		const attempt = await attemptReconcile({
 			cwd,
 			slug,
@@ -765,7 +1028,9 @@ export async function returnToBacklog(
 			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, ' +
@@ -914,8 +1179,9 @@ export async function returnToBacklog(
 		'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
@@ -946,7 +1212,7 @@ export async function returnToBacklog(
 					base,
 					sourceRel: bodyRel,
 					destRel: bodyRel,
-					transformBody: (body) => appendRequeueNoteText(body, handoff),
+					transformBody: (body) => insertRequeueNoteText(body, handoff),
 					commitMessage: `chore(${slug}): requeue handoff note`,
 					refNamespace: 'requeue',
 					env,
@@ -1019,7 +1285,7 @@ export async function returnToBacklog(
 type ReconcileAttempt =
 	| {kind: 'reconciled'}
 	| {kind: 'no-branch'}
-	| {kind: 'conflict'; detail: string};
+	| {kind: 'conflict'; detail: string; genuineConflict?: boolean};
 
 /**
  * The `--reconcile` recovery attempt — the non-destructive middle rung of the
@@ -1088,8 +1354,12 @@ 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(
@@ -1099,6 +1369,10 @@ async function attemptReconcile(params: {
 		).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',
@@ -3160,22 +3434,56 @@ const BOUNCE_BODY_PROBE_ORDER: Record<SidecarType, readonly WorkFolderKey[]> = {
 	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: readonly RegExp[] = [
+	/^##\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: string, message: string): string {
+export function insertRequeueNoteText(
+	content: string,
+	message: string,
+): string {
 	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}`;
 }
 
 /**