dorfl 0.0.0 → 0.1.0

package/dist/integration-core.js

@@ -0,0 +1,2195 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { LEDGER_STATUS_FOLDERS, workItemPath, workItemRel, workFolderPath, workFolderPrefix, } from './work-layout.js';
+import { runVerify } from './verify.js';
+import { ensurePrepared } from './prepare.js';
+import { ReviewParseError, formatBlockReason, reviewRoundsExhaustedReason, } from './review-gate.js';
+import { ledgerWrite } from './ledger-write.js';
+import { selectProvider } from './github.js';
+import { parseFrontmatter } from './frontmatter.js';
+import { git, run, runAsync } from './git.js';
+import { realSleep } from './retry-backoff.js';
+import { workBranchRef } from './slug-namespace.js';
+import { isAncestor } from './gc.js';
+/**
+ * The default LIVENESS CEILING for the merge-mode `${branch}:main` push (the
+ * durable promotions `tasks/ready → tasks/done` and, via `lifecycle`, `prds/ready
+ * → prds/tasked`). Task `c2-rebase-until-real-on-durable-main-promotions` turned
+ * the previous SMALL FIXED CAP (was 5, the `run-fleet-claim-integrate-and-sibling-
+ * rebase-concurrency-safe` Race-1 budget) into rebase-until-real-conflict: a CLEAN
+ * re-rebase no longer counts against a tiny give-up budget — only a GENUINE
+ * conflict surfaced by {@link rebaseOntoMainWithReconcile} stops the loop (the
+ * step-4 rebase IS the source-folder precondition recheck for the slug-relocation
+ * family: if the slug is GONE from its expected source folder on the new `main`,
+ * the `git mv` replay fails and `rebaseConflictRoute` routes definitively — never a
+ * silent re-push that would clobber a concurrent legitimate same-item winner).
+ *
+ * The cap survives only as a LARGE liveness ceiling that bounds the pathological
+ * livelock tail (a sustained-parallel-load hot ref where the loser's round-trip is
+ * always beaten by another winner — classic CAS livelock). Combined with the
+ * modest jitter on the refetch below it desynchronises the herd, so a route-to-
+ * needs-attention from this loop becomes a RARE livelock signal rather than the
+ * ROUTINE false-contention signal it was at the old cap of 5.
+ *
+ * SCOPE (`work/notes/ideas/ledger-lock-evolution-per-item-ref-vs-rebase-until-real-
+ * conflict.md` `### C2` SCOPE box, repeated here because over-applying C2 is the
+ * one near-fatal mistake): the durable promotions are slug RELOCATIONS, not the
+ * same-path / append family. They MUST keep their source-folder precondition
+ * recheck — reused here verbatim as `rebaseOntoMainWithReconcile`'s rebase replay
+ * + arbiter ledger-placement read. Do NOT add a new conflict-detection path; the
+ * existing one IS the genuine-conflict terminator.
+ *
+ * Tests inject a small `mergeRetries` (or `0`) to exercise the old un-retried /
+ * cap-exhausted route deterministically — that test seam is preserved.
+ */
+const DEFAULT_MERGE_RETRIES = 1000;
+/**
+ * Default modest jitter (ms) on the refetch between merge-push retries — load-
+ * bearing under sustained parallel load: an instant lockstep refetch→re-push loop
+ * maximises mutual rejection (a thundering herd), fattening the livelock tail.
+ * Modest randomisation desynchronises the herd. Each attempt sleeps a UNIFORMLY-
+ * random integer in `[0, DEFAULT_MERGE_JITTER_MS]` ms. Small enough (≤25ms) that
+ * the additional latency under realistic contention is negligible vs the
+ * round-trip cost of a rebase+push, and small enough that the in-tree concurrency
+ * tests are not slowed measurably. Tests override via `mergeJitterMs: 0`.
+ */
+const DEFAULT_MERGE_JITTER_MS = 25;
+/**
+ * Promise-based sleep, used for the {@link DEFAULT_MERGE_JITTER_MS} merge-push
+ * retry jitter (C2). Internal — the legacy non-seamed sleep this module uses
+ * for the C2 jitter (kept for byte-for-byte compatibility with existing tests).
+ * The recovery-rebase loop uses the INJECTABLE {@link Sleep} seam from
+ * `retry-backoff.ts` instead, so its timeline is test-driveable.
+ */
+function sleepMs(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * **Default cap on RE-FETCH+RE-REBASE attempts** in the committed-recovery tail
+ * (`recoverAlreadyCommitted`, task `recovery-rebase-retry-against-moving-arbiter
+ * -main`). The recovery's single fetch-then-rebase is a CONTENTION race against a
+ * concurrently-MOVING `<arbiter>/main` (a sibling `advance` run lands a burst of
+ * `advance: surface observation:…` commits); a one-shot rebase against a stale
+ * fetched base can conflict against a main that already moved AGAIN, surfacing a
+ * purely transient race as `rebase-conflict`. So the rebase is wrapped in a small
+ * bounded CONTENTION loop: re-fetch `<arbiter>/main` (it may have advanced) +
+ * re-rebase; on clean → integrate; on conflict → `--abort`, a small jitter sleep,
+ * try again. The cap stops the loop ONLY when every fresh-fetched attempt still
+ * conflicts (a genuinely persistent conflict ⇒ route to needs-attention exactly
+ * as today). Small on purpose — a few attempts ride out a `advance` burst (each
+ * burst is tens of commits over a few seconds); a real conflict surfaces fast.
+ *
+ * This is the CONTENTION model (instant re-fetch+rebuild, like `claim-cas.ts`
+ * and the Race-1 merge loop above), NOT the OUTAGE model in
+ * {@link file://./retry-backoff.ts} (exponential temporal backoff, the remote
+ * may come back). The two failure classes are deliberately kept SEPARATE; do not
+ * substitute `retryWithBackoff` here.
+ *
+ * Tests inject `recoveryRebaseRetries: 0` (no retry — the legacy one-shot shape)
+ * or a small explicit cap (assert the cap exhausts deterministically).
+ */
+const DEFAULT_RECOVERY_REBASE_RETRIES = 4;
+/**
+ * **Default max jitter (ms)** between recovery-rebase attempts — a SMALL
+ * livelock-breaking SPREAD between concurrent runners (NOT exponential outage
+ * backoff). Pure instant retry has a real hazard: two runners that begin
+ * retrying at the same instant re-fetch and re-rebase in LOCKSTEP, each moving
+ * the base the other just rebased onto, and can livelock. A uniformly-random
+ * `[0, mergeJitterMs]` ms sleep before each re-attempt de-correlates the two
+ * racers. Bounded and tiny — a contention nudge, not an outage wait. Tests pass
+ * `recoveryRebaseJitterMs: 0` for a deterministic latency-free loop, OR inject
+ * the `sleep`/`random` seams to drive the timeline reproducibly with a seeded RNG.
+ */
+const DEFAULT_RECOVERY_REBASE_JITTER_MS = 100;
+const DEFAULT_TYPE = 'feat';
+/**
+ * Run the shared gate→integrate band for a prepared (claimed, built, on-its-work-
+ * branch) item. The HEAD has already resolved `cwd`/`arbiter`/`slug`/`source`/
+ * `recovering`; this runs the gate, the review gate, the effective-mode decision,
+ * the done-move + atomic commit + rebase + integrate, and routes ANY failure to
+ * needs-attention — returning pure DATA for the caller's tail.
+ *
+ * It never throws for the expected gate-failed / review-blocked / rebase-conflict
+ * cases (those are returned with the corresponding outcome). A genuinely
+ * unexpected git plumbing failure (e.g. the done-move itself, or nothing staged)
+ * throws — the caller's existing try/catch maps it.
+ */
+export async function performIntegration(input) {
+    const cwd = input.cwd;
+    const env = input.env;
+    const arbiter = input.arbiter;
+    const slug = input.slug;
+    const source = input.source;
+    const recovering = input.recovering;
+    const note = input.note ?? (() => { });
+    // The work branch: the caller is on it (it carries the namespaced identity).
+    // Prefer the explicit `branch`; else read the branch HEAD is on; only fall
+    // back to a synthesised `work/task-<slug>` if HEAD is detached (a degenerate
+    // case that the on-branch invariant should preclude).
+    const branch = input.branch ?? resolveWorkBranch(cwd, slug, env);
+    // Captured from the Gate-2 review (when it runs + approves) so that AFTER the
+    // propose integrate — where the opened PR url is finally in scope — we can post
+    // the agent's deliberately-authored `review` prose as a PR comment (task
+    // `review-comment-prose-field`). Stays undefined when review is off / the agent
+    // emitted no `review` field, so the post is skipped (no-op). The verdict/routing
+    // decision uses neither.
+    let approvedVerdict;
+    // The resolved integration mode. `merge` lands automatically on a green gate
+    // (and an `approve` when review is on); `propose` leaves the merge to a human.
+    // MUTABLE because the untrusted-origin build-propose rule below may force it to
+    // `propose` for a task BUILD (the build transition only) — see the rule after
+    // `sourcePath` is resolved.
+    let mode = input.mode;
+    // The fresh-worktree gate (task `gate-on-rebased-tip-fresh-worktree`): when ON
+    // the deterministic acceptance gate (`prepare`+`verify`) does NOT run here on
+    // the agent's PRE-rebase `cwd`; instead it runs LATER, in a clean throwaway
+    // worktree cut from the work branch REBASED onto `<arbiter>/main` (the
+    // would-be-integrated tip), inside the rebase-to-integrate tail. So a green gate
+    // provably describes the MERGED artifact. When OFF the front prepare+verify runs
+    // here exactly as before (byte-for-byte). The band HONOURS the boolean it is
+    // handed (caller-agnostic); the `run`-fleet `perRepoMax === 1` downgrade lives
+    // in the `run` caller, not here.
+    const freshWorktreeGate = input.freshWorktreeGate === true;
+    // RECOVER an already-committed, already-done-moved STRANDED branch (prd
+    // `ledger-integrity` story 6). The work + the done-move are ALREADY committed on
+    // the work branch (a terminal push failed AFTER steps 2–3); SKIP steps 0–3
+    // (prepare / gate / review / done-move / commit) and run ONLY the
+    // rebase→integrate TAIL from the kept commit, reusing the SAME integrate
+    // primitive. Returns BEFORE any of the build-path steps run.
+    if (input.committedRecovery) {
+        return await recoverAlreadyCommitted({
+            cwd,
+            arbiter,
+            slug,
+            branch,
+            mode,
+            noPR: input.noPR,
+            providerInstance: input.providerInstance,
+            openPr: input.openPr,
+            recoveryRebaseRetries: input.recoveryRebaseRetries,
+            recoveryRebaseJitterMs: input.recoveryRebaseJitterMs,
+            recoveryRebaseSleep: input.recoveryRebaseSleep,
+            recoveryRebaseRandom: input.recoveryRebaseRandom,
+            // Answered-merge land (task `committed-recovery-honours-fresh-worktree-gate`,
+            // prd `land-time-reverify-and-parallel-merge-ceiling`): the apply-rung
+            // dispatches an answered `merge` through this committed-recovery tail (the
+            // branch already carries its done-move commit, so the build path's
+            // `git mv`+`add -A`+commit would raise `IntegrationNothingStaged`). UNLIKE
+            // the original stranded-recovery caller (whose pre-strand build already
+            // gated), `<arbiter>/main` may have MOVED since this branch's last build,
+            // so the rebased tip MUST be re-verified before it lands or the load-bearing
+            // invariant ("main never receives a tree that fails verify") cannot hold on
+            // the merge path. Thread the gate inputs through; recovery runs the EXISTING
+            // `runFreshWorktreeGate` on the rebased tip when `freshWorktreeGate` is set
+            // (and not `--skip-verify`), routing a RED gate to needs-attention via the
+            // SAME seam the build path uses. With `freshWorktreeGate` unset (the
+            // stranded-recovery caller), recovery is byte-identical to before — no
+            // extra gate, no extra fetch.
+            freshWorktreeGate,
+            skipVerify: input.skipVerify,
+            prepare: input.prepare,
+            verify: input.verify,
+            surfaceArbiter: input.surfaceArbiter,
+            env,
+            note,
+        });
+    }
+    // The file whose `title:` seeds the commit summary + PR title. For a TASKING
+    // transition (a non-task `lifecycle`) this is the held prd it supplies; for a
+    // build it is the task in its source folder. Read BEFORE any move.
+    const lifecycle = input.lifecycle;
+    // CONTINUE-BUILD (`source: 'done'`, task
+    // `complete-builds-on-already-done-moved-continue`): on a dirty continue whose
+    // kept branch already holds the slug in `work/done/`, the file we read for the
+    // title + (otherwise) untrusted-origin lives there too — not in
+    // `in-progress/`/`needs-attention/`. The step-2 `git mv` is later SKIPPED for
+    // this source (the slug is already in done/), and the originTrust read +
+    // arbiter ledger placement/divergent-done-move reconcile are EXEMPTED below.
+    const sourcePath = lifecycle
+        ? lifecycle.titlePath
+        : source === 'done'
+            ? workItemPath(cwd, 'done', slug)
+            : workItemPath(cwd, source, slug);
+    // UNTRUSTED-ORIGIN BUILD-PROPOSE RULE (task `untrusted-origin-forces-build-propose`).
+    // A task born from an UNTRUSTED issue carries `originTrust: untrusted` (stamped
+    // at intake, propagated by the tasker). Its risk is the BUILD (it becomes code),
+    // so the build transition resolves to `propose` even when the requested mode is
+    // `merge` — moving the human checkpoint onto the becomes-code build. Precedence:
+    //   explicit --merge  >  untrusted-origin ⇒ propose  >  config mode  >  default.
+    // An explicit `--merge` (input.explicitMerge) OVERRIDES the rule (the operator
+    // is present; CLI always wins, no special force-key). The autonomous/CI path
+    // passes no flag, so there an untrusted-origin task RELIABLY forces propose.
+    //
+    // SCOPE: the task BUILD transition ONLY. It NEVER fires for a `lifecycle`
+    // transition (tasking / intake-emit — a prd/task FILE landing on main is inert;
+    // intake's OWN per-emit resolver already decided that mode), and the source file
+    // here is the task being built. A `trusted`/unset task ⇒ untouched (zero
+    // behaviour change for the normal human path).
+    // CONTINUE-BUILD EXEMPTION (task
+    // `complete-builds-on-already-done-moved-continue`): the prior attempt that
+    // done-moved this task already went through the originTrust checkpoint (an
+    // untrusted task on a `merge` config proposed on that first attempt). The
+    // continue-build commit is layered on top of that kept tip, so re-evaluating
+    // the rule here would either double-checkpoint or be a no-op against the same
+    // frontmatter — exempt this state (the task file lives in `done/` and is now
+    // effectively an on-`main` artifact). The other states are unchanged.
+    if (!lifecycle &&
+        source !== 'done' &&
+        mode === 'merge' &&
+        input.explicitMerge !== true &&
+        existsSync(sourcePath) &&
+        parseFrontmatter(readFileSync(sourcePath, 'utf8')).originTrust ===
+            'untrusted') {
+        mode = 'propose';
+        note(`Untrusted-origin task '${slug}': forcing the BUILD transition to ` +
+            'propose (a human reviews the becomes-code change before it merges). ' +
+            'Pass --merge to override.');
+    }
+    // 0. Prepare: make the worktree's ENV READY before the gate (install deps,
+    //    submodules, codegen). A fresh job worktree off the hub mirror has no
+    //    `node_modules`, so `verify` would fail for lack of deps unless prepare
+    //    runs FIRST. `prepare` is the SIBLING of `verify`, NOT baked into it: it
+    //    runs ONCE before the first verify, gated by a NON-COMMITTED prepared-ness
+    //    marker in the worktree's git control area (so it does not re-install per
+    //    gate within one persistent worktree). Unset ⇒ a no-op (no default install).
+    //    A FAILING prepare is a HARD STOP distinct from a red gate (`prepare-failed`):
+    //    the env could not be made ready, so `verify` cannot be trusted — it NEVER
+    //    proceeds to verify/integrate, and routes the item the SAME way a red gate
+    //    does. (`--skip-verify` skips only the gate, not env-prep: a verify-skipped
+    //    finish still needs a ready env; the marker keeps an already-prepared tree
+    //    a no-op.)
+    //
+    //    FRESH-WORKTREE GATE: when ON, this front prepare+verify is SKIPPED here and
+    //    runs LATER on the rebased-tip throwaway worktree (see the tail). The OFF
+    //    path below is byte-for-byte today's pre-rebase gate.
+    if (!freshWorktreeGate) {
+        const prep = await ensurePrepared({ cwd, prepare: input.prepare, env });
+        if (!prep.noop && !prep.skipped) {
+            note('Running the env-prep step (prepare)…');
+        }
+        if (!prep.passed) {
+            const reason = `prepare (env-prep) failed (exit ${prep.exitCode})`;
+            // Bounce from in-progress/ straight to needs-attention/ (the SAME seam a red
+            // gate uses) — recording the prepare-failed reason + committing the move
+            // (with the agent's uncommitted work) as ONE atomic transition. We NEVER
+            // run `verify` on an env that could not be made ready.
+            const routed = await ledgerWrite.applyNeedsAttentionTransition({
+                cwd,
+                slug,
+                reason,
+                arbiter: input.surfaceArbiter,
+                env,
+                note,
+            });
+            return {
+                outcome: 'prepare-failed',
+                routedToNeedsAttention: routed.moved,
+                branch,
+                reason: routed.moved
+                    ? `Env-prep (prepare) failed (exit ${prep.exitCode}); routed '${slug}' ` +
+                        'to work/needs-attention/ (the environment could not be made ready, ' +
+                        'so the acceptance gate was NOT run). Fix the prepare command, then ' +
+                        'return it to backlog/.'
+                    : `Env-prep (prepare) failed (exit ${prep.exitCode}); not completing ` +
+                        `'${slug}' (the environment could not be made ready, so the ` +
+                        'acceptance gate was NOT run). Fix the prepare command, then retry.',
+            };
+        }
+    }
+    // 1. Gate: bad work never proceeds to done. Default-on; --skip-verify is a
+    //    human-only escape hatch (the autonomous runner never skips — ADR §8).
+    //    FRESH-WORKTREE GATE: when ON this front gate is SKIPPED and runs LATER on
+    //    the rebased-tip throwaway worktree (see the tail); the OFF branch below is
+    //    byte-for-byte today's pre-rebase gate.
+    if (input.skipVerify) {
+        note('Skipping the acceptance gate (--skip-verify).');
+    }
+    else if (!freshWorktreeGate) {
+        note('Running the acceptance gate (verify)…');
+        const gate = await runVerify({ cwd, verify: input.verify, env });
+        if (!gate.passed) {
+            // Don't leave the item dangling in in-progress/: route it to
+            // needs-attention/ with the reason (ADR §12) THROUGH the ledger write
+            // seam's needs-attention transition. The item has NOT been committed/moved
+            // yet, so the move bounces it straight from in-progress/ — recording the
+            // reason + committing the move (with the agent's uncommitted work) as ONE
+            // atomic transition. No partial state.
+            const reason = `acceptance gate failed (exit ${gate.exitCode})`;
+            const routed = await ledgerWrite.applyNeedsAttentionTransition({
+                cwd,
+                slug,
+                reason,
+                // Autonomous caller (`do`) passes the arbiter so the seam both SURFACES
+                // the stuck state on `main` (OBSERVABLE, cross-machine visible) AND
+                // pushes the `work/<slug>` branch (RECOVERABLE — a requeue-continue on
+                // another machine, reading <arbiter>/work/<slug>, lands on the saved
+                // wip). The human `complete` leaves it unset → no surface, no push,
+                // local-only (a human is right there). One operation in one place: the
+                // push lives in the seam (it is HEAD's branch — `work/<slug>` — here),
+                // no bolted-on push to forget.
+                arbiter: input.surfaceArbiter,
+                env,
+                note,
+            });
+            return {
+                outcome: 'gate-failed',
+                routedToNeedsAttention: routed.moved,
+                branch,
+                reason: routed.moved
+                    ? `Acceptance gate failed (exit ${gate.exitCode}); routed '${slug}' ` +
+                        'to work/needs-attention/ (surfaced by status; return to backlog/ ' +
+                        'once resolved). Fix the work, or use --skip-verify to override.'
+                    : `Acceptance gate failed (exit ${gate.exitCode}); not completing ` +
+                        `'${slug}'. Fix the work, or use --skip-verify to override.`,
+            };
+        }
+    }
+    // 1b. Gate 2 — the PR/code REVIEW gate (GATES prd `work/prds/tasked/review.md`). It is a
+    //     JUDGEMENT gate layered ON TOP of the deterministic `verify` floor (ADR §8)
+    //     — NEVER a replacement, and ALWAYS verify-THEN-review on the SAME tree.
+    //
+    //     WHERE it runs depends on the fresh-worktree gate (MAINTAINER DECISION 2):
+    //       - OFF: `verify` ran HERE on the pre-rebase `cwd`, so the review runs HERE
+    //         too, on `cwd`, BEFORE the done-move — byte-for-byte today's order.
+    //       - ON: the front `verify` was SKIPPED here and runs LATER on the rebased
+    //         tip (step 4c). So the review is RELOCATED to run there too, AFTER the
+    //         rebased-tip `verify` passes, inside the same fresh gate worktree — so
+    //         verify-then-review holds on the SAME merged tree (the tree that lands),
+    //         not split across two trees. (Letting verify move to the rebased tip
+    //         while review stayed on the pre-rebase `cwd` would deliver the
+    //         gate-the-merged-tree guarantee for verify but BREAK it for review,
+    //         incoherent with this task's own goal.)
+    //
+    //     Either way the verdict routes IDENTICALLY:
+    //       approve → fall through to the done-move/commit/integrate unchanged;
+    //       block   → route to needs-attention via the SAME machinery the red gate
+    //                 uses (`applyNeedsAttentionTransition`, surfaced on
+    //                 `surfaceArbiter` for the autonomous `do` path), with the
+    //                 blocking findings recorded as the reason, no integrate.
+    if (input.review && !freshWorktreeGate) {
+        const reviewOutcome = await runGate2Review({
+            reviewCwd: cwd,
+            input,
+            slug,
+            branch,
+            cwd,
+            env,
+            note,
+        });
+        if (reviewOutcome.kind === 'blocked') {
+            return reviewOutcome.result;
+        }
+        // approve: carry the verdict (post-integrate PR comment) and write the per-run
+        // non-blocking-nits observation INTO `cwd` BEFORE the done-move + atomic commit
+        // (so it is swept into that SAME done-commit). A resolved `merge` then lands
+        // automatically (`merge` IS the auto-land mode); `propose` leaves it to a human.
+        approvedVerdict = reviewOutcome.verdict;
+        writeReviewNitsObservation({
+            cwd,
+            slug,
+            findings: reviewOutcome.verdict?.findings ?? [],
+            note,
+        });
+    }
+    // Read the title now, BEFORE the move, for the default commit summary AND the
+    // synthesised propose-mode PR TITLE (the source file is about to be git-mv'd
+    // away). The PR title is a SINGLE, capped line built runner-side from the
+    // task's `title:` frontmatter + the slug (`<type>(<slug>): <title>`) so it can
+    // never be the multi-line commit-subject run-on `--fill` would derive.
+    //
+    // When the lifecycle supplies an EXPLICIT `title`, use it DIRECTLY (no file read):
+    // the intake lone-task / prd path writes its output file in `stage()`, which runs
+    // AFTER this point, so a `titlePath` read would race the write and degrade the
+    // subject/PR title to the generic fallback. The `do prd:` tasking path leaves
+    // `title` unset and keeps reading its already-existing held prd (unchanged).
+    const explicitTitle = lifecycle?.title;
+    const taskTitle = explicitTitle !== undefined ? explicitTitle : readTaskTitle(sourcePath);
+    const defaultMessage = explicitTitle !== undefined
+        ? summaryFromTitle(explicitTitle, slug)
+        : defaultSummary(sourcePath, slug);
+    const prTitle = synthesiseProposeTitle({
+        type: (input.type ?? DEFAULT_TYPE).trim() || DEFAULT_TYPE,
+        slug,
+        title: taskTitle,
+    });
+    // 2. STAGE the item move into the index. For a build that is the task done-move
+    //    (`work/<source>/<slug>.md → work/done/<slug>.md`); for a TASKING
+    //    transition (a non-task `lifecycle`) it is the caller-supplied prd
+    //    lifecycle move + emitted backlog files (the runner stages them, the agent
+    //    never does git). Either way the subsequent `git add -A` folds the agent's
+    //    uncommitted work + this staging into ONE atomic commit.
+    //
+    //    The task done-move is ATOMIC AGAINST THE ARBITER (ledger-integrity
+    //    defect 1 + its root defect 2). The LOCAL move here is the legacy clean
+    //    `git mv work/<source>/<slug>.md → work/done/<slug>.md` (one folder, no
+    //    fetch — every existing path is byte-for-byte unchanged); the ARBITER
+    //    resolution + the one-slug-one-folder enforcement happen AFTER the rebase
+    //    (step 4b, `reconcileDoneMoveAgainstArbiter`), against the freshly-fetched
+    //    `<arbiter>/main`. That ordering is deliberate: a NEW fetch in THIS step
+    //    would race a sibling job's integration on the SHARED bare-mirror refs (the
+    //    very regression that orphaned this work, ADR §2), so we reuse the existing
+    //    step-4 fetch's result instead. The reconciliation REMOVES any divergent
+    //    `in-progress/`/`needs-attention/` ghost the merge would otherwise leave (so
+    //    the move is a MOVE, not a COPY) and FAILS LOUD if the arbiter holds the slug
+    //    in two folders with differing content.
+    if (lifecycle) {
+        await lifecycle.stage();
+    }
+    else if (source === 'done') {
+        // CONTINUE-BUILD (`source: 'done'`, task
+        // `complete-builds-on-already-done-moved-continue`): the slug is ALREADY in
+        // `work/done/` on this kept branch (a prior attempt moved it there), so there
+        // is NOTHING to move — skip the step-2 `git mv`. The subsequent `git add -A`
+        // folds the agent's NEW uncommitted source edits into the atomic commit on
+        // top of the kept (already-done-moved) tip; no second move, no copy.
+    }
+    else {
+        mkdirSync(workFolderPath(cwd, 'done'), { recursive: true });
+        await gitHard([
+            'mv',
+            workItemRel(source, `${slug}.md`),
+            workItemRel('done', `${slug}.md`),
+        ], cwd, env);
+    }
+    // 3. Commit: git add -A (the agent's uncommitted work + the move) into ONE
+    //    atomic commit. Nothing to commit is FATAL (no-op-is-fatal, like claim.sh).
+    await gitHard(['add', '-A'], cwd, env);
+    if (await nothingStaged(cwd, env)) {
+        throw new IntegrationNothingStaged(`nothing to commit for '${slug}' — no work and no move staged. ` +
+            '(Did the agent produce changes? Is the task already done?)', slug);
+    }
+    // SCOOP + REPORT agent-authored CAPTURED NOTES (task `runner-scoops-captured-notes`,
+    // advance-loop's reporting-channel fold-in). A rung's agent may write capture-bucket
+    // files (`work/notes/observations/*`, `work/findings/*`) during its run — its `capture-signal`
+    // reflex — but it does NO git (Rule A). The `git add -A` above already SWEEPS them into
+    // THIS one runner-owned commit (the same way the review-nits observation rides it), so
+    // they are TRACKED, not dropped/untracked. Rule B is extended HERE: the runner REPORTS
+    // exactly which note files landed (honest reporting — what actually reached the commit,
+    // read from the staged set, not assumed). This is the ONE shared place — BOTH the build
+    // path (`do <task>`/`run`/`complete`) and the tasking path (`do prd:`, via the
+    // `lifecycle` seam) route through it, so the channel is NOT forked. Zero notes ⇒ no
+    // report (the no-note case is byte-for-byte unchanged).
+    await reportScoopedNotes(cwd, env, note);
+    const summary = input.message ?? defaultMessage;
+    const type = (input.type ?? DEFAULT_TYPE).trim() || DEFAULT_TYPE;
+    // The trailing transition tag: a build is `; done`, a TASKING transition is
+    // `; tasked` (the lifecycle supplies it). Keeps the runner-owned commit subject
+    // honest about WHICH lifecycle landed.
+    const commitMessage = `${type}(${slug}): ${summary}; ${lifecycle?.commitTag ?? 'done'}`;
+    await gitHard(['commit', '-q', '-m', commitMessage], cwd, env);
+    note(`Committed: ${commitMessage}`);
+    // The rebase-to-integrate TAIL (step 4 fetch+rebase → step 5 integrate) is the
+    // ONLY region serialised per repo under the `run` concurrency seam: it is the
+    // land-on-`main` band where two concurrent SAME-repo merge jobs would otherwise
+    // race (the loser pushing a non-fast-forward `${branch}:main`). Wrapping ONLY
+    // this tail keeps the front-of-band gate (`prepare`+`verify`) and the Gate-2
+    // review agent CONCURRENT across same-repo jobs (run's parallelism); inside the
+    // lock the loser re-fetches + rebases onto the winner's now-advanced main, so
+    // its push is a clean fast-forward (a genuine conflict routes ONE to
+    // needs-attention). Single-job callers pass no lock ⇒ the tail runs directly,
+    // byte-for-byte unchanged. The lock is keyed per repo, so cross-repo
+    // integration stays fully concurrent.
+    const runRebaseToIntegrateTail = async () => {
+        // The step-4 rebase-onto-`<arbiter>/main` (with BOTH reconciliation arms: the
+        // sibling-slug ledger arm and the divergent-done-move recovery), factored so it
+        // can run ONCE before the gate AND be RE-RUN in the Race-1 merge-push retry loop
+        // (a sibling advancing main mid-push needs the SAME reconcile, not a bare
+        // rebase). Returns `{}` on a clean rebase (fall through to gate/integrate) or
+        // `{route}` when a genuine conflict / invariant violation must stop the tail.
+        const rebaseOntoMainWithReconcile = async () => {
+            // 4. Rebase-before-integrate (ADR §10): rebase the work branch onto the
+            //    latest <arbiter>/main. Clean → continue. Conflict → abort + stop.
+            //
+            //    RECOVERY reconciliation: when completing FROM needs-attention/, the work
+            //    branch's history still carries the original `in-progress → needs-attention`
+            //    MOVE-ONLY commit, and `<arbiter>/main` was SURFACED with that same move
+            //    (the item is in needs-attention/ on main). Replaying that historical move
+            //    onto main conflicts (main has no in-progress/<slug>.md) — exactly the
+            //    rebase conflict the human hit doing this by hand. So we DROP that move-only
+            //    commit during the rebase: the replay becomes `wip + (needs-attention →
+            //    done)`, which applies cleanly onto the surfaced main (it HAS the item in
+            //    needs-attention/). The done-move thus SUPERSEDES the surfaced state — no
+            //    leftover/conflicting on-`main` surface for the human to resolve.
+            // Fetch the arbiter's `main` into the `<arbiter>/main` remote-tracking ref
+            // EXPLICITLY. A `run` JOB WORKTREE is cut from a bare hub mirror whose remote
+            // has no fetch refspec (so `<arbiter>/main` would not otherwise resolve / would
+            // be stale, causing a spurious rebase conflict); a regular clone (`do`/
+            // `complete`) already has it, where the explicit refspec is harmless (the same
+            // refspec `rebaseOntoArbiterMain` used before the convergence).
+            await gitHard([
+                'fetch',
+                '--quiet',
+                arbiter,
+                `+refs/heads/main:refs/remotes/${arbiter}/main`,
+            ], cwd, env);
+            // ONE-SLUG-ONE-FOLDER guard + divergent-base PRE-CHECK, read from the
+            // freshly-fetched `<arbiter>/main` (a READ of the tracking ref the fetch above
+            // just populated — NO new fetch, so no shared-mirror race). It (a) FAILS LOUD if
+            // the arbiter already holds the slug in >1 status folder with differing content
+            // (a corrupt ledger; never publish over it), and (b) detects the DIVERGENT base
+            // — the arbiter holds the slug's source in a DIFFERENT folder than our local
+            // done-move removed — which is the case that turns the rebased "move" into a
+            // "copy" (PR #86). The tasking lifecycle is exempt (its move is not a task
+            // done-move).
+            // CONTINUE-BUILD EXEMPTION (task
+            // `complete-builds-on-already-done-moved-continue`): on `source: 'done'`
+            // there was no first-time move on this commit (the slug was already in
+            // `done/` on the kept branch + on the arbiter), so the divergent-done-move
+            // reconcile reasoning does not apply. Skip the arbiter ledger placement
+            // pre-check too: it is structurally an instrument FOR that reconcile, and a
+            // continue-build is by construction already in `done/` on both sides.
+            if (!lifecycle && source !== 'done') {
+                const arbiterPlacement = readArbiterLedgerPlacement(cwd, arbiter, slug, env);
+                if (arbiterPlacement.error) {
+                    note(arbiterPlacement.error);
+                    return {
+                        route: {
+                            outcome: 'invariant-violation',
+                            routedToNeedsAttention: false,
+                            branch,
+                            reason: arbiterPlacement.error,
+                        },
+                    };
+                }
+            }
+            // PLAIN rebase. After the per-item-lock cut-over (prd
+            // `ledger-status-per-item-lock-refs`, tasks 9a–9d) no transient status
+            // lands on a work branch: needs-attention is the lock `state: stuck` (not a
+            // `git mv` to `needs-attention/`), the body rests in `backlog/` while
+            // claimed, and the tasking/advancing markers are gone. So a recovery
+            // complete's kept branch carries NO historical route-to-needs-attention
+            // move-only commit to drop — the old `rebaseDroppingNeedsAttentionSurface`
+            // (drop-bookkeeping-rebase) is deleted and BOTH recovering and lifecycle
+            // rebases are the same plain replay onto `<arbiter>/main`.
+            void recovering;
+            void lifecycle;
+            // RENAME-DETECTION-OFF (task
+            // `disable-rename-detection-on-continue-rebase`): scope
+            // `-c merge.directoryRenames=false` to THIS rebase invocation, so a single
+            // durable folder-transition `git mv` out of a SPARSE work/<from>/ folder is
+            // NOT misread by git's directory-rename heuristic as a whole-DIRECTORY
+            // rename `work/<from>/ → work/<to>/` (which would spuriously flag every
+            // sibling file `<arbiter>/main` added into that folder as `CONFLICT (file
+            // location)` and force a FALSE needs-attention). Content-rename detection
+            // (`-Xno-renames`/`merge.renames`/`diff.renames`) is the wrong knob and
+            // does NOT suppress this directory-rename conflict; only
+            // `merge.directoryRenames=false` does. NEVER a persistent `git config`
+            // write — the repo's config stays clean so a user's interactive
+            // `git rebase` is unaffected. A GENUINE content conflict still surfaces
+            // and still routes via `rebaseConflictRoute()` below.
+            const rebase = await gitSoft(['-c', 'merge.directoryRenames=false', 'rebase', `${arbiter}/main`], cwd, env);
+            if (rebase.status !== 0) {
+                // NEVER auto-resolve a genuine CODE conflict. But FIRST, a SIBLING-SLUG
+                // LEDGER conflict (the replay conflicts ONLY on OTHER slugs'
+                // `work/<status>/<otherslug>.md` ledger files — a sibling job landed its own
+                // status-folder move on `<arbiter>/main` between our base and this rebase) is
+                // a benign ledger-only divergence with NO semantic judgement: the reconcile
+                // ABORTS the rebase, then redoes OUR work as one clean commit on top of
+                // `<arbiter>/main` (taking the arbiter's version of every sibling ledger file
+                // automatically). It is scoped STRICTLY to other slugs' ledger files — a
+                // conflict touching ANY code file, or THIS slug's own ledger, returns `false`
+                // (and leaves the rebase in progress), so the divergent-done-move recovery /
+                // needs-attention route below handles it; it NEVER widens to code. The tasking
+                // lifecycle is exempt (its move is not a task done-move).
+                const siblingReconciled = lifecycle
+                    ? false
+                    : await reconcileSiblingLedgerConflict({
+                        cwd,
+                        arbiter,
+                        slug,
+                        env,
+                        note,
+                    });
+                if (siblingReconciled) {
+                    // The branch is now cleanly on top of `<arbiter>/main` with OUR work + the
+                    // arbiter's sibling-ledger files — fall through to the fresh-gate + integrate
+                    // band. THIS slug's own move is untouched.
+                    note(`Reconciled a sibling-slug ledger conflict during the rebase onto ` +
+                        `${arbiter}/main (took the arbiter's version of the other slugs' ` +
+                        `work/<status>/<slug>.md ledger files; no code file was touched).`);
+                }
+                else if (!lifecycle && source !== 'done') {
+                    // NEVER auto-resolve a genuine CODE conflict: abort the rebase. But FIRST, a
+                    // DIVERGENT-LEDGER conflict (the arbiter holds the slug's source in a folder
+                    // our local done-move did not remove — PR #86) is auto-RECONCILABLE without
+                    // any semantic judgement: redo the done-move arbiter-resolved (remove the
+                    // arbiter's actual source folder, add `done/`) on top of `<arbiter>/main`. We
+                    // only do this when the post-abort tree's ONLY divergence is the slug's ledger
+                    // file; a real code conflict still routes to needs-attention untouched.
+                    await gitSoft(['rebase', '--abort'], cwd, env);
+                    const recovered = await reconcileDivergentDoneMove({
+                        cwd,
+                        arbiter,
+                        slug,
+                        branch,
+                        localSource: source,
+                        env,
+                        note,
+                    });
+                    if (recovered) {
+                        // The branch is now cleanly on top of `<arbiter>/main` with the slug in
+                        // `done/` ONLY — fall through to integrate (skip the needs-attention
+                        // route below).
+                        note(`Reconciled the done-move against ${arbiter}/main: '${slug}' is in ` +
+                            'work/done/ ONLY (the divergent source folder was removed; the move ' +
+                            'is a move, not a copy).');
+                    }
+                    else {
+                        return { route: await rebaseConflictRoute() };
+                    }
+                }
+                else {
+                    await gitSoft(['rebase', '--abort'], cwd, env);
+                    return { route: await rebaseConflictRoute() };
+                }
+            }
+            // Clean rebase (or a reconciled one): fall through to the gate + integrate.
+            return {};
+        };
+        // Run the step-4 rebase ONCE up front (before the slow fresh gate).
+        const firstRebase = await rebaseOntoMainWithReconcile();
+        if (firstRebase.route) {
+            return firstRebase.route;
+        }
+        // The rebase-conflict needs-attention route, factored so the divergent-ledger
+        // recovery above can fall through to integrate while a genuine code conflict
+        // still routes here.
+        async function rebaseConflictRoute() {
+            // Then route the item to needs-attention/ with the conflict reason (ADR
+            // §12) THROUGH the ledger write seam's needs-attention transition, rather
+            // than leaving it dangling in done/. The done-move was already committed
+            // above, so the item sits in work/done/; the move bounces it from there and
+            // commits the in-progress→needs-attention move (here done→needs-attention)
+            // as ONE transition. No partial state.
+            const reason = `rebase onto ${arbiter}/main conflicted (aborted, never auto-resolved)`;
+            const routed = await ledgerWrite.applyNeedsAttentionTransition({
+                cwd,
+                slug,
+                reason,
+                // Autonomous caller (`do`) passes the arbiter so the seam both surfaces the
+                // conflict on `main` (OBSERVABLE) AND pushes the `work/<slug>` branch
+                // (RECOVERABLE, cross-machine). The human `complete` leaves it unset →
+                // no surface, no push, local-only. The push lives in the seam (HEAD's
+                // branch is `work/<slug>` here) — no bolted-on push.
+                arbiter: input.surfaceArbiter,
+                env,
+                note,
+            });
+            return {
+                outcome: 'rebase-conflict',
+                routedToNeedsAttention: routed.moved,
+                branch,
+                commitMessage,
+                reason: routed.moved
+                    ? `Rebasing ${branch} onto ${arbiter}/main conflicted; the rebase was ` +
+                        `aborted (never auto-resolved) and '${slug}' was routed to ` +
+                        'work/needs-attention/ (surfaced by status). Resolve against the ' +
+                        'latest main, then return it to backlog/ and re-run.'
+                    : `Rebasing ${branch} onto ${arbiter}/main conflicted; the rebase was ` +
+                        'aborted (never auto-resolved). Resolve against the latest main, ' +
+                        'then re-run complete.',
+            };
+        }
+        // 4c. FRESH-WORKTREE GATE (task `gate-on-rebased-tip-fresh-worktree`): when ON,
+        //     the acceptance gate (`prepare` then `verify`) runs HERE — on the work
+        //     branch tip the rebase above just produced (the would-be-integrated tip) —
+        //     rather than on the agent's pre-rebase `cwd`. We cut a CLEAN throwaway
+        //     worktree from `HEAD` (the rebased committed tip), `prepare` then `verify`
+        //     in it, REAP it (pass or fail), and only on GREEN fall through to integrate.
+        //     A gitignored/uncommitted file in `cwd` cannot leak into this gate (the
+        //     worktree is cut from the committed, rebased tip), and a change the
+        //     integration rebase introduced IS gated. A red gate routes the item the SAME
+        //     way the front gate did — EXCEPT the done-move already happened (steps 2–3),
+        //     so the bounce is from `work/done/` (the seam finds the slug wherever it
+        //     rests) instead of `work/in-progress/`. A `--skip-verify` skipped the gate
+        //     entirely at the front, so it never reaches here. The tasking `lifecycle`
+        //     path is exempt (its quality engine is the tasker loop, not this gate).
+        if (freshWorktreeGate && !input.skipVerify && !lifecycle) {
+            const tip = (await gitSoft(['rev-parse', '--verify', '--quiet', 'HEAD'], cwd, env)).stdout.trim();
+            const gated = await runFreshWorktreeGate({
+                cwd,
+                commit: tip,
+                prepare: input.prepare,
+                verify: input.verify,
+                env,
+                note,
+                // GATE-2 REVIEW relocation (MAINTAINER DECISION 2): when `review` is ON,
+                // the fresh gate runs it AFTER the rebased-tip verify, against the rebased
+                // tip (the gate worktree) — so verify-THEN-review holds on the SAME merged
+                // tree. The needs-attention ROUTING still targets `cwd` (the work branch +
+                // ledger), so the verdict handling is identical to the OFF path.
+                review: input.review
+                    ? (reviewCwd) => runGate2Review({
+                        reviewCwd,
+                        input,
+                        slug,
+                        branch,
+                        cwd,
+                        env,
+                        note,
+                    })
+                    : undefined,
+            });
+            if (!gated.passed) {
+                // prepare-failed or gate-failed on the rebased tip: route the item to
+                // needs-attention through the SAME seam the front gate / rebase-conflict use.
+                // The done-move was already committed (steps 2–3), so the slug sits in
+                // work/done/; the seam bounces it from there (done → needs-attention). The
+                // recovery path keeps it where it is (no re-route) exactly like the front gate.
+                const outcome = gated.kind === 'prepare' ? 'prepare-failed' : 'gate-failed';
+                const what = gated.kind === 'prepare'
+                    ? `Env-prep (prepare) failed (exit ${gated.exitCode})`
+                    : `Acceptance gate failed (exit ${gated.exitCode})`;
+                const reason = gated.kind === 'prepare'
+                    ? `prepare (env-prep) failed (exit ${gated.exitCode}) on the rebased tip`
+                    : `acceptance gate failed (exit ${gated.exitCode}) on the rebased tip`;
+                const routed = await ledgerWrite.applyNeedsAttentionTransition({
+                    cwd,
+                    slug,
+                    reason,
+                    arbiter: input.surfaceArbiter,
+                    env,
+                    note,
+                });
+                return {
+                    outcome,
+                    routedToNeedsAttention: routed.moved,
+                    branch,
+                    commitMessage,
+                    reason: routed.moved
+                        ? `${what} on the rebased tip; routed '${slug}' to ` +
+                            'work/needs-attention/ (surfaced by status; return to backlog/ ' +
+                            'once resolved). Fix the work, or use --skip-verify to override.'
+                        : `${what} on the rebased tip; not completing '${slug}'. Fix the ` +
+                            'work, or use --skip-verify to override.',
+                };
+            }
+            // GATE-2 REVIEW outcome on the rebased tip (MAINTAINER DECISION 2): the
+            // rebased-tip verify PASSED, so the review ran AFTER it (verify-then-review on
+            // the merged tree). Route a BLOCK exactly as the OFF-path front review does
+            // (only the reviewed tree moved, not the routing). On APPROVE: carry the
+            // verdict (post-integrate PR comment), write the per-run non-blocking-nits
+            // observation. A resolved `merge` then lands automatically; `propose` leaves
+            // the merge to a human.
+            if (gated.review) {
+                if (gated.review.kind === 'blocked') {
+                    // The done-move was already committed (steps 2–3), so the slug sits in
+                    // work/done/; the routing bounced it from there to needs-attention/.
+                    return gated.review.result;
+                }
+                approvedVerdict = gated.review.verdict;
+                // The done-move + atomic commit already happened (steps 2–3, before this
+                // rebased-tip gate), so — unlike the OFF path where the nits write rides the
+                // upcoming commit — we write the observation into `cwd` and FOLD it into the
+                // existing done-commit via `commit --amend` (the branch is not yet
+                // integrated). The observation still lands in the SAME done-commit that
+                // integrates, preserving the no-separate-commit/surface model.
+                const nitsBefore = await stagedCaptureNotes(cwd, env);
+                writeReviewNitsObservation({
+                    cwd,
+                    slug,
+                    findings: gated.review.verdict?.findings ?? [],
+                    note,
+                });
+                // Only amend when the write actually produced a new staged file (zero
+                // non-blocking findings ⇒ no write ⇒ no amend, the done-commit unchanged).
+                await gitHard(['add', '-A'], cwd, env);
+                if (!(await nothingStaged(cwd, env))) {
+                    const nitsAfter = await stagedCaptureNotes(cwd, env);
+                    if (nitsAfter.length > nitsBefore.length) {
+                        await gitHard(['commit', '-q', '--amend', '--no-edit'], cwd, env);
+                    }
+                }
+            }
+        }
+        // 5. Integrate per mode through the ledger write seam's COMPLETE transition
+        //    (ADR §6 + `docs/adr/claim-ledger-vs-protected-main.md`). The rebase above
+        //    already brought the branch up to date, so the seam's sole strategy uses
+        //    `integrate` (not `integrateWithRebase`) and never --forces. Provider
+        //    selection: an injected `openPr` wins (legacy bridge); otherwise pick by
+        //    the arbiter's remote URL (a GitHub remote ⇒ `gh pr create`, else push-only
+        //    `none`) — PURELY arbiter-derived, no override axis. A missing/unauthenticated
+        //    `gh` degrades to push-only at runtime — never a hard failure (and the
+        //    start-of-run unauthed case is caught UP FRONT by the pre-flight `gh` probe).
+        //    The seam is storage-agnostic: we hand it the work branch, the integration
+        //    mode, the provider, and the PR-INTENT (`noPR`) — `main` lives only in the
+        //    strategy.
+        // Provider precedence: an injected fully-formed provider wins (the `run`
+        // stubbed-provider seam, carrying title/body/url); else the legacy `openPr`
+        // bridge; else select PURELY from the arbiter URL (no override). The orthogonal
+        // `noPR` INTENT (suppress the PR) is threaded SEPARATELY — it does NOT pick a
+        // provider, the integrator simply skips `openRequest` when it is set.
+        const provider = input.providerInstance ??
+            (input.openPr
+                ? bridgeProvider(input.openPr)
+                : selectProvider({
+                    arbiterUrl: await arbiterUrl(cwd, arbiter, env),
+                }));
+        // Race-1 (claim-vs-integrate, task
+        // `run-fleet-claim-integrate-and-sibling-rebase-concurrency-safe`): integrate,
+        // and on a non-fast-forward `${branch}:main` push (a SIBLING same-repo CLAIM —
+        // under the SEPARATE claim lock — or a sibling integrate advanced
+        // `<arbiter>/main` during our push window) RE-RUN the step-4 rebase (which
+        // carries the sibling-ledger + divergent-done-move reconcile arms — a bare
+        // re-rebase would MISS them) and RETRY the push, up to a small cap. INSTANT
+        // retry (contention, not an outage; see `claim-cas.ts`). We NEVER `--force`
+        // main: each retry re-rebases to a clean fast-forward. A genuine code conflict
+        // on a re-rebase routes to needs-attention via the SAME `route` the up-front
+        // rebase uses. A persistent non-fast-forward past the cap also routes (never a
+        // silent drop). `input.mergeRetries` overrides the cap (tests; `0` ⇒ no retry).
+        //
+        // **C2 rebase-until-real-conflict (task `c2-rebase-until-real-on-durable-main-
+        // promotions`):** the loop's TERMINATION CHANGED. A CLEAN re-rebase no longer
+        // counts against a tiny give-up budget — only a GENUINE conflict surfaced by
+        // `rebaseOntoMainWithReconcile` (a `route` ⇒ `rebase-conflict` or
+        // `invariant-violation`) stops the loop. The step-4 rebase IS the source-folder
+        // precondition recheck reused verbatim: if the slug is GONE from its expected
+        // source folder on the new `main` (a concurrent legitimate same-item winner
+        // already moved it), the `git mv` replay fails and `rebaseConflictRoute` routes
+        // definitively — never a silent re-push that would clobber the winner. The
+        // `maxMergeRetries` cap survives ONLY as a large liveness ceiling on the
+        // pathological livelock tail (default {@link DEFAULT_MERGE_RETRIES} = 1000);
+        // modest jitter on the refetch desynchronises a herd so the tail is not
+        // reached under sustained parallel load.
+        const maxMergeRetries = input.mergeRetries ?? DEFAULT_MERGE_RETRIES;
+        const mergeJitterMs = input.mergeJitterMs ?? DEFAULT_MERGE_JITTER_MS;
+        let integration;
+        for (let mergeAttempt = 0;; mergeAttempt++) {
+            integration = await ledgerWrite.applyCompleteTransition({
+                arbiter,
+                branch,
+                mode,
+                provider,
+                // PR-INTENT: when set (propose mode), push the branch but skip the PR.
+                noPR: input.noPR,
+                // Half A: an explicit single-line PR title (propose mode), so `gh` no longer
+                // derives a run-on title from the commit subject via `--fill`.
+                title: prTitle,
+                // Half B: the propose-mode PR body — the agent's summary under a deterministic
+                // runner header (task pointer). Undefined when no body was supplied (the
+                // header is only scaffolded when there IS a body) ⇒ today's `--fill` (no
+                // regression). Ignored in merge mode by the provider/integrator.
+                body: composeProposeBody({ slug, body: input.body }),
+                // Part (b) of the merged-branch hygiene task: when WE perform the merge
+                // (this resolved `merge` mode), reap the remote `work/<slug>` HEAD branch
+                // INLINE right after the merge lands — the commits are now on `main`, so the
+                // head is provably merged and safe to delete (ancestor-guarded inside the
+                // integrator). Idempotent no-op when no remote head exists (the plain
+                // `${branch}:main` push opened none); ignored in `propose` mode (its branch is
+                // the review surface, reaped later by `gc --remote-branches`). NEVER `--force`.
+                deleteMergedHead: true,
+                cwd,
+                env,
+            });
+            // Only the merge push can be non-fast-forward (propose pushes its own ref).
+            if (integration.mergeNonFastForward !== true) {
+                break;
+            }
+            if (mergeAttempt >= maxMergeRetries) {
+                // LIVENESS CEILING hit (default 1000; previously the small Race-1 cap of 5,
+                // now reinterpreted by C2 as the pathological-livelock-tail bound, NOT a
+                // false-contention budget). Route to needs-attention rather than looping
+                // forever or force-pushing main. A RARE outcome under realistic load thanks
+                // to the jitter below + the rebase-until-real-conflict semantics; tests
+                // reach it deterministically by injecting a small `mergeRetries`.
+                return await mergeNonFastForwardRoute(`integrating ${branch} onto ${arbiter}/main kept hitting a ` +
+                    `non-fast-forward push (a sibling advanced main ${mergeAttempt + 1} ` +
+                    `times); gave up cleanly without --force`);
+            }
+            // Modest jitter on the refetch (C2): an instant lockstep refetch→re-push loop
+            // maximises mutual rejection under sustained parallel load (thundering herd).
+            // A uniformly-random `[0, mergeJitterMs]` ms sleep desynchronises the herd.
+            // Skipped when `mergeJitterMs === 0` (the test seam).
+            if (mergeJitterMs > 0) {
+                await sleepMs(Math.floor(Math.random() * (mergeJitterMs + 1)));
+            }
+            // A sibling advanced main: re-run the step-4 rebase (with the reconcile arms)
+            // before retrying the push. A genuine conflict on the re-rebase routes via
+            // `rebaseOntoMainWithReconcile`'s `route` (the existing source-folder /
+            // one-slug placement recheck IS the genuine-conflict terminator — see the
+            // `DEFAULT_MERGE_RETRIES` docstring for the C2 SCOPE box). A clean re-rebase
+            // (no route) loops without counting against a small budget.
+            const reRebase = await rebaseOntoMainWithReconcile();
+            if (reRebase.route) {
+                return reRebase.route;
+            }
+        }
+        // The Race-1 needs-attention route for a merge that could not land (a genuine
+        // re-rebase conflict is handled by `rebaseOntoMainWithReconcile`'s `route`; this
+        // covers the cap-exhausted persistent-contention case). Mirrors
+        // `rebaseConflictRoute`: the done-move was already committed (steps 2–3), so the
+        // slug sits in work/done/ and the seam bounces it from there.
+        async function mergeNonFastForwardRoute(reason) {
+            const routed = await ledgerWrite.applyNeedsAttentionTransition({
+                cwd,
+                slug,
+                reason,
+                arbiter: input.surfaceArbiter,
+                env,
+                note,
+            });
+            return {
+                outcome: 'rebase-conflict',
+                routedToNeedsAttention: routed.moved,
+                branch,
+                commitMessage,
+                reason: routed.moved
+                    ? `Integrating ${branch} onto ${arbiter}/main kept hitting a ` +
+                        `non-fast-forward push (a sibling advanced main); '${slug}' was routed ` +
+                        `to work/needs-attention/ (surfaced by status). Resolve against the ` +
+                        `latest main, then return it to backlog/ and re-run.`
+                    : `Integrating ${branch} onto ${arbiter}/main kept hitting a ` +
+                        `non-fast-forward push (a sibling advanced main). Resolve against the ` +
+                        `latest main, then re-run complete.`,
+            };
+        }
+        // 6. Make the Gate-2 review VISIBLE on the PR (task `review-comment-prose-field`,
+        //    refining `review-gate-pr-comment`): AFTER the propose integrate, where the
+        //    approved verdict (with its deliberately-authored `review` prose), the
+        //    resolved `provider`, AND the opened PR url (`integration.url`) are ALL in
+        //    scope, post `verdict.review` as a comment on that PR — INCLUDING on approve
+        //    (the audit trail; decided 2026-06-06). The `review` field is a first-class
+        //    AUTHORED review (the prompt requires it), NOT the residue around the JSON
+        //    — posting the residue was the bug
+        //    (`work/findings/review-comment-posts-agent-thinking-not-a-review.md`). It
+        //    reuses the SAME `provider` the integrate used (the core never imports `gh`).
+        //    The comment is ADVISORY: it changes no gate/verdict/merge/integration logic
+        //    — by here the verdict has ALREADY routed (block never reaches this point; it
+        //    routed to needs-attention above) and the integrate has ALREADY happened.
+        //    The PR identity is resolved in PRECEDENCE: a parsed `integration.url` wins
+        //    (the normal path — post on it directly); else, when a PR WAS opened but its
+        //    url was unparseable (`integration.requestOpened` true, `url` undefined — the
+        //    `gh pr create` exit-0-but-unparseable-stdout degradation), FALL BACK to the
+        //    BRANCH-resolved comment (task `review-comment-fallback-on-unparsed-pr-url`):
+        //    the provider resolves the branch's open PR and comments on it, instead of
+        //    silently dropping a review on a PR that genuinely exists. Only when NO PR was
+        //    opened at all (merge mode, or a degraded/push-only propose ⇒ `requestOpened`
+        //    false) is it the honest clean no-op — and the branch-resolved fallback's own
+        //    "no PR resolvable" path is a clean no-op too (it tries first). Either way
+        //    `postPRComment*` never throws; the review stays in the run output. Because
+        //    this lives in the shared core, BOTH `do`/`complete` AND `run` post the
+        //    comment — no per-caller wiring.
+        if (approvedVerdict?.review !== undefined) {
+            if (integration.url !== undefined) {
+                const posted = provider.postPRComment({
+                    cwd,
+                    url: integration.url,
+                    body: approvedVerdict.review,
+                    env,
+                });
+                note(posted.instruction);
+            }
+            else if (integration.requestOpened) {
+                // A PR opened but its url was unparseable — resolve it from the branch
+                // rather than dropping the review (the audit-trail fallback).
+                const posted = provider.postPRCommentOnBranch({
+                    cwd,
+                    branch,
+                    body: approvedVerdict.review,
+                    env,
+                });
+                note(posted.instruction);
+            }
+        }
+        return {
+            outcome: 'completed',
+            routedToNeedsAttention: false,
+            branch,
+            commitMessage,
+            integration,
+        };
+    };
+    // Serialise ONLY this tail per repo when the `run` seam is wired; absent ⇒ run
+    // it directly (an un-contended no-op, single-job behaviour unchanged).
+    return input.integrateLock && input.integrateLockKey !== undefined
+        ? await input.integrateLock(input.integrateLockKey, runRebaseToIntegrateTail)
+        : await runRebaseToIntegrateTail();
+}
+/**
+ * RECOVER an already-committed, already-done-moved STRANDED branch (prd
+ * `ledger-integrity` story 6, the `finish-already-committed-branch` task). The
+ * green work AND the `git mv → work/done/` are ALREADY committed on the work
+ * branch (a terminal push failed AFTER `performIntegration`'s steps 2–3), and the
+ * tip is NOT on the arbiter. This runs ONLY the rebase→integrate TAIL (steps 4–5)
+ * from the kept commit — NO re-done-move, NO re-commit, NO rebuild, NO orphan
+ * branch — reusing the SAME `ledgerWrite.applyCompleteTransition` integrate
+ * primitive the build path uses.
+ *
+ * RE-GATE on the REBASED TIP (task `committed-recovery-honours-fresh-worktree-
+ * gate`, prd `land-time-reverify-and-parallel-merge-ceiling`): when the caller
+ * sets `freshWorktreeGate` (and not `skipVerify`), the EXISTING
+ * `runFreshWorktreeGate` runs on the rebased tip AFTER the rebase loop and
+ * BEFORE `applyCompleteTransition`, mirroring the build path's
+ * `freshWorktreeGate && !skipVerify && !lifecycle` branch — a red gate routes
+ * to needs-attention through the SAME shared seam, never integrates a clean-
+ * rebase-but-broken merge. This is OPT-IN per caller: the original stranded-
+ * recovery caller (`complete --integration`'s already-built strand, whose pre-
+ * strand build already gated) leaves it UNSET and is byte-identical to before —
+ * no extra gate, no extra fetch. The answered-merge apply-rung SETS it because
+ * `<arbiter>/main` may have moved since the branch's last build, so the rebased
+ * tip MUST be re-verified before it lands or the load-bearing invariant
+ * ("main never receives a tree that fails verify") cannot hold on the merge
+ * path.
+ *
+ * SAFETY — UNSPOOFABLE detection: BEFORE acting it fetches `<arbiter>/main` and
+ * checks whether the kept tip is ALREADY reachable there (`isAncestor`, the SAME
+ * predicate `gc.ts` uses). If so the work is already integrated → a clean
+ * `already-integrated` no-op (never a re-push / double-integrate); a re-run after a
+ * successful recovery hits this. Only when the tip is genuinely AHEAD does it
+ * rebase + integrate. A rebase CONFLICT here is a genuine code conflict the human
+ * resolves — the branch is aborted and the outcome is `rebase-conflict` (the kept
+ * commit stays intact on the branch, recoverable), NEVER auto-resolved, NEVER
+ * `--force` to main.
+ */
+async function recoverAlreadyCommitted(params) {
+    const { cwd, arbiter, slug, branch, mode, env, note } = params;
+    const retries = params.recoveryRebaseRetries ?? DEFAULT_RECOVERY_REBASE_RETRIES;
+    const jitterMs = params.recoveryRebaseJitterMs ?? DEFAULT_RECOVERY_REBASE_JITTER_MS;
+    const sleep = params.recoveryRebaseSleep ?? realSleep;
+    const random = params.recoveryRebaseRandom ?? Math.random;
+    // Helper: the explicit-refspec fetch (the build path's step-4 fetch shape — a
+    // bare-mirror worktree's remote has no fetch refspec, so `<arbiter>/main` would
+    // not otherwise resolve / would be stale). REUSED on EACH attempt (the root cause
+    // of the moving-base race is a stale SINGLE fetch — see the loop below).
+    const refetchMain = async () => {
+        await gitHard([
+            'fetch',
+            '--quiet',
+            arbiter,
+            `+refs/heads/main:refs/remotes/${arbiter}/main`,
+        ], cwd, env);
+    };
+    await refetchMain();
+    const tip = (await gitSoft(['rev-parse', '--verify', '--quiet', 'HEAD'], cwd, env)).stdout.trim();
+    if (tip === '') {
+        throw new Error(`cannot recover '${slug}': HEAD does not resolve (no committed work on ` +
+            `${branch}?).`);
+    }
+    // UNSPOOFABLE detection: the kept tip ALREADY reachable on `<arbiter>/main`
+    // means the work is already integrated — a clean no-op, NEVER a re-integration.
+    // (`isAncestor` is the SAME reachability predicate `gc.ts` uses; do not fork it.)
+    // KEPT before the retry loop: a no-op MUST short-circuit before we burn any
+    // re-fetch/re-rebase budget.
+    if (isAncestor(cwd, tip, `refs/remotes/${arbiter}/main`, env)) {
+        const message = `Nothing to recover for '${slug}': its work branch tip is already on ` +
+            `${arbiter}/main (already integrated). No re-push, no double-integrate.`;
+        note(message);
+        return {
+            outcome: 'already-integrated',
+            routedToNeedsAttention: false,
+            branch,
+            reason: message,
+        };
+    }
+    // The tip is genuinely AHEAD — rebase the kept commit onto the latest
+    // `<arbiter>/main`. A clean rebase continues; a CONFLICT is wrapped in a
+    // bounded CONTENTION loop (task `recovery-rebase-retry-against-moving-arbiter-
+    // main`): on each conflict `--abort`, sleep a small jitter, RE-FETCH
+    // `<arbiter>/main` (it may have advanced — `advance` runs land bursts of
+    // `advance: surface observation:…` commits on main, so a one-shot rebase against
+    // a stale fetched base can conflict against a main that already moved AGAIN),
+    // then re-rebase. Only after the cap exhausts (a freshly-fetched main STILL
+    // conflicts on every attempt) do we surface `rebase-conflict` (never auto-
+    // resolved, NEVER `--force` to main — the kept commit stays on the branch,
+    // recoverable; the human resolves and re-runs).
+    //
+    // This is the CONTENTION model (instant re-fetch+rebuild against the new base,
+    // like `claim-cas.ts` / the Race-1 merge loop above), NOT the OUTAGE model in
+    // `retry-backoff.ts` (exponential temporal backoff for an unreachable remote).
+    // The jitter is a SMALL livelock-breaking SPREAD (two runners that begin
+    // retrying at the same instant must NOT re-fetch/re-rebase in lockstep) — NOT
+    // exponential outage backoff. The `--abort` is unconditional on conflict (never
+    // leave the worktree mid-rebase between attempts).
+    //
+    // RECONCILE ARMS DECISION (this task): the recovery rebase is deliberately
+    // BARE — it does NOT layer the sibling-ledger / divergent-done-move arms the
+    // build path's `rebaseOntoMainWithReconcile()` carries. Reasoning: this tail
+    // integrates a branch whose done-move was ALREADY committed in a prior run, so
+    // there is no first-time slug relocation on THIS commit for the divergent-
+    // done-move reconcile to act on, and a sibling-slug ledger conflict on the
+    // re-fetched main is the same shape it would have hit on the original run (the
+    // recovery is not the place to grow new reconcile semantics).
+    //
+    // RENAME-DETECTION composition (task
+    // `disable-rename-detection-on-continue-rebase`): the rebase carries
+    // `-c merge.directoryRenames=false` SCOPED to the invocation — written as a
+    // small args array so every retry of THIS loop carries it too — so a single
+    // durable folder-transition `git mv` out of a SPARSE source folder is NOT
+    // misread as a whole-DIRECTORY rename and the post-rename heuristic does NOT
+    // flag sibling files `<arbiter>/main` added into that folder as `CONFLICT
+    // (file location)`. Content-rename detection (`-Xno-renames`/`merge.renames`/
+    // `diff.renames`) is the WRONG knob and was verified ineffective for this
+    // directory-rename conflict; only `merge.directoryRenames=false` suppresses
+    // it. NEVER a persistent `git config` write — the repo's config stays clean.
+    // A GENUINE same-path content conflict still surfaces and still routes to
+    // `rebase-conflict` (the user's interactive `git rebase` is unaffected).
+    note(`Recovering '${slug}': rebasing the kept ${branch} onto ${arbiter}/main…`);
+    const rebaseArgs = () => [
+        '-c',
+        'merge.directoryRenames=false',
+        'rebase',
+        `${arbiter}/main`,
+    ];
+    let attempt = 0;
+    for (;;) {
+        const rebase = await gitSoft(rebaseArgs(), cwd, env);
+        if (rebase.status === 0) {
+            break; // clean rebase ⇒ fall through to integrate
+        }
+        // ALWAYS abort on conflict — never leave mid-rebase between attempts.
+        await gitSoft(['rebase', '--abort'], cwd, env);
+        if (attempt >= retries) {
+            const message = `Recovering '${slug}': rebasing the kept ${branch} onto ${arbiter}/main ` +
+                `conflicted on every attempt (${attempt + 1} total, against a freshly-` +
+                `fetched ${arbiter}/main each time); the rebase was aborted (never auto-` +
+                'resolved). The committed work is intact on the branch (recoverable). ' +
+                'Resolve against the latest main, then re-run.';
+            note(message);
+            return {
+                outcome: 'rebase-conflict',
+                routedToNeedsAttention: false,
+                branch,
+                reason: message,
+            };
+        }
+        // Small livelock-breaking jitter (contention spread, NOT outage backoff).
+        // Sleep happens BEFORE the re-fetch so a sleep-injection in tests can also
+        // drive the timeline (e.g. advance the arbiter between attempts).
+        const delay = jitterMs > 0 ? Math.floor(random() * (jitterMs + 1)) : 0;
+        await sleep(delay);
+        await refetchMain();
+        attempt++;
+    }
+    // FRESH-WORKTREE GATE on the REBASED TIP (task `committed-recovery-honours-
+    // fresh-worktree-gate`, prd `land-time-reverify-and-parallel-merge-ceiling`):
+    // when `freshWorktreeGate` is set (the answered-merge land caller) and not
+    // `--skip-verify`, re-run the acceptance gate on the rebased tip BEFORE we
+    // integrate, mirroring the build path's `freshWorktreeGate && !skipVerify &&
+    // !lifecycle` branch (recovery never carries a lifecycle, so no lifecycle
+    // guard is needed). A green gate ⇒ fall through to integrate exactly as today;
+    // a red gate routes to needs-attention through the SAME shared seam
+    // (`applyNeedsAttentionTransition`) the build path uses — NEVER integrates a
+    // clean-rebase-but-broken merge. With `freshWorktreeGate` UNSET (the original
+    // stranded-recovery caller, whose pre-strand build already gated) this whole
+    // block is skipped and behaviour is byte-identical to before.
+    if (params.freshWorktreeGate && !params.skipVerify) {
+        const tip = (await gitSoft(['rev-parse', '--verify', '--quiet', 'HEAD'], cwd, env)).stdout.trim();
+        // No `review:` callback here: the recovery tail re-verifies an already-
+        // reviewed, already-committed result, so Gate-2 review semantics do not
+        // apply on this path.
+        const gated = await runFreshWorktreeGate({
+            cwd,
+            commit: tip,
+            prepare: params.prepare,
+            verify: params.verify,
+            env,
+            note,
+        });
+        if (!gated.passed) {
+            const outcome = gated.kind === 'prepare' ? 'prepare-failed' : 'gate-failed';
+            const what = gated.kind === 'prepare'
+                ? `Env-prep (prepare) failed (exit ${gated.exitCode})`
+                : `Acceptance gate failed (exit ${gated.exitCode})`;
+            const reason = gated.kind === 'prepare'
+                ? `prepare (env-prep) failed (exit ${gated.exitCode}) on the rebased tip`
+                : `acceptance gate failed (exit ${gated.exitCode}) on the rebased tip`;
+            const routed = await ledgerWrite.applyNeedsAttentionTransition({
+                cwd,
+                slug,
+                reason,
+                arbiter: params.surfaceArbiter,
+                env,
+                note,
+            });
+            return {
+                outcome,
+                routedToNeedsAttention: routed.moved,
+                branch,
+                reason: routed.moved
+                    ? `${what} on the rebased tip during committed-recovery; routed ` +
+                        `'${slug}' to work/needs-attention/ (surfaced by status; return ` +
+                        'to backlog/ once resolved). Fix the work, or use --skip-verify ' +
+                        'to override.'
+                    : `${what} on the rebased tip during committed-recovery; not ` +
+                        `completing '${slug}'. Fix the work, or use --skip-verify to ` +
+                        'override.',
+            };
+        }
+    }
+    // Integrate the rebased kept commit through the SAME complete-transition
+    // primitive the build path uses (no duplication of the integrate mechanism; the
+    // branch is already rebased so it is the non-rebasing `integrate`, never
+    // `--force`). Provider precedence matches the build path: injected instance >
+    // legacy `openPr` bridge > arbiter-derived selection.
+    const provider = params.providerInstance ??
+        (params.openPr
+            ? bridgeProvider(params.openPr)
+            : selectProvider({ arbiterUrl: await arbiterUrl(cwd, arbiter, env) }));
+    const integration = await ledgerWrite.applyCompleteTransition({
+        arbiter,
+        branch,
+        mode,
+        provider,
+        noPR: params.noPR,
+        deleteMergedHead: true,
+        cwd,
+        env,
+    });
+    note(attempt === 0
+        ? `Recovered '${slug}': integrated the kept commit from ${branch}.`
+        : `Recovered '${slug}': integrated the kept commit from ${branch} ` +
+            `(absorbed a moving ${arbiter}/main across ${attempt} re-fetch+re-` +
+            `rebase attempt${attempt === 1 ? '' : 's'}).`);
+    return {
+        outcome: 'completed',
+        routedToNeedsAttention: false,
+        branch,
+        integration,
+    };
+}
+/**
+ * Resolve the work branch the integration runs on: the branch HEAD is currently
+ * on (the caller is ALWAYS on the work branch — the agent built there / the
+ * lifecycle stage wrote there), which carries the namespaced `work/<type>-<slug>`
+ * identity. Falls back to a synthesised `work/task-<slug>` ONLY for a detached
+ * HEAD (a degenerate case the on-branch invariant precludes), so the push target
+ * is always defined.
+ */
+function resolveWorkBranch(cwd, slug, env) {
+    try {
+        const head = git(['symbolic-ref', '--quiet', '--short', 'HEAD'], cwd, {
+            env,
+        }).trim();
+        if (head.startsWith('work/')) {
+            return head;
+        }
+    }
+    catch {
+        // detached HEAD or plumbing failure — fall through to the synthesised default
+    }
+    return workBranchRef('task', slug);
+}
+/**
+ * Raised when the atomic completion commit has NOTHING staged (no agent work and
+ * no move) — a deliberate REFUSAL, mapped by `complete`'s try/catch to its
+ * `refused` outcome (preserving its existing message verbatim). Exported so the
+ * caller can `instanceof`-route it.
+ *
+ * Carries the {@link slug} so the autonomous-strand surface in `complete.ts`
+ * (which catches this error in `performComplete`'s outer try/catch, OUTSIDE the
+ * `runComplete` slug scope) can publish the `in-progress/ → needs-attention/`
+ * tree-less move without re-deriving the slug from the error message.
+ */
+export class IntegrationNothingStaged extends Error {
+    slug;
+    constructor(message, slug) {
+        super(message);
+        this.slug = slug;
+    }
+}
+/**
+ * The arbiter's remote URL for `arbiter` in `cwd` (for provider auto-detection),
+ * or `undefined` when it cannot be resolved. Read-only; soft (never throws).
+ * Exported so the PR-INTENT pre-flight guard (`do.ts`) can resolve the arbiter
+ * URL up front to decide whether a GitHub PR is even possible for this run.
+ */
+export async function arbiterUrl(cwd, arbiter, env) {
+    const res = await gitSoft(['remote', 'get-url', arbiter], cwd, env);
+    if (res.status !== 0) {
+        return undefined;
+    }
+    const url = res.stdout.trim();
+    return url === '' ? undefined : url;
+}
+/** Adapt the legacy `openPr` callback into the new ReviewProvider seam. */
+function bridgeProvider(openPr) {
+    return {
+        name: 'none',
+        async openRequest(req) {
+            openPr({ cwd: req.cwd, branch: req.branch, env: req.env });
+            return {
+                opened: true,
+                instruction: `Opened a review for ${req.branch}.`,
+            };
+        },
+        // The legacy `openPr` bridge has no comment channel (it returns no PR url),
+        // so postPRComment degrades: it never opens a PR url to comment on, so the
+        // in-core poster no-ops anyway. Implemented for the seam, surfacing the text.
+        postPRComment(req) {
+            return {
+                posted: false,
+                instruction: 'The legacy review bridge cannot post a comment; the review:\n' +
+                    req.body,
+            };
+        },
+        // Likewise the bridge cannot resolve a PR from a branch — a clean no-op.
+        postPRCommentOnBranch(req) {
+            return {
+                posted: false,
+                instruction: 'The legacy review bridge cannot post a comment; the review:\n' +
+                    req.body,
+            };
+        },
+    };
+}
+/**
+ * Default commit summary: the task's `title` frontmatter with any leading
+ * `slug — ` (or `slug -`) prefix stripped, so a task titled
+ * "complete — gate, mark done, …" yields "gate, mark done, …". Falls back to a
+ * generic summary when the title is missing/unreadable.
+ */
+function defaultSummary(inProgressPath, slug) {
+    let title;
+    try {
+        title = readTitle(readFileSync(inProgressPath, 'utf8'));
+    }
+    catch {
+        title = undefined;
+    }
+    return summaryFromTitle(title, slug);
+}
+/**
+ * The PURE commit-summary derivation from a (possibly absent) item title — the
+ * shared core of {@link defaultSummary} (file-read path) and the lifecycle's
+ * EXPLICIT-title path (intake, whose output file is not written until {@link
+ * IntegrationLifecycle.stage}, AFTER the title read). Strips a leading `slug — `
+ * prefix; falls back to the generic summary when the title is missing/empty.
+ */
+function summaryFromTitle(title, slug) {
+    if (!title) {
+        return 'complete work task';
+    }
+    // Strip a leading "slug" followed by an em-dash / en-dash / hyphen separator.
+    const prefix = new RegExp(`^${escapeRegExp(slug)}\\s*[—–-]\\s*`, 'i');
+    return title.replace(prefix, '').trim() || title;
+}
+/**
+ * The sane single-line cap for a synthesised PR title (Half A). GitHub itself
+ * accepts long titles, but a PR list/notification truncates ugly past ~72 chars;
+ * we cap to keep the title scannable and guarantee it is never a run-on. Beyond
+ * the cap we truncate and append an ellipsis (counted within the cap).
+ */
+export const PR_TITLE_MAX = 72;
+/**
+ * The task's raw `title:` frontmatter (NOT the commit-summary-stripped form),
+ * or undefined when missing/unreadable. Used as the human-authored source for
+ * the synthesised PR title.
+ */
+function readTaskTitle(taskPath) {
+    try {
+        return readTitle(readFileSync(taskPath, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Synthesise the propose-mode PR TITLE runner-side (Half A) from data the runner
+ * already has — NO agent text: `<type>(<slug>): <title>`, reusing the `--type`
+ * convention (default `feat`). It is FORCED to a single line (newlines → spaces,
+ * runs of whitespace collapsed) and CAPPED to {@link PR_TITLE_MAX} (truncating
+ * with a trailing `…`), so it can NEVER be the multi-line run-on `gh ... --fill`
+ * derives from the commit subject. When the task `title:` is missing it falls
+ * back to the slug alone (`<type>(<slug>)`). Exported for unit tests of the
+ * single-line + cap guarantee.
+ */
+export function synthesiseProposeTitle(input) {
+    const type = input.type.trim() || DEFAULT_TYPE;
+    // Strip a leading `slug — ` / `slug -` prefix (some task titles repeat the
+    // slug; the `<slug>` scope already carries it) and flatten to one line.
+    const prefix = new RegExp(`^${escapeRegExp(input.slug)}\\s*[—–-]\\s*`, 'i');
+    const cleanTitle = (input.title ?? '')
+        .replace(prefix, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+    const composed = cleanTitle === ''
+        ? `${type}(${input.slug})`
+        : `${type}(${input.slug}): ${cleanTitle}`;
+    if (composed.length <= PR_TITLE_MAX) {
+        return composed;
+    }
+    // Cap, reserving one char for the ellipsis (counted within the cap).
+    return composed.slice(0, PR_TITLE_MAX - 1).trimEnd() + '…';
+}
+/**
+ * Compose the propose-mode PR BODY (Half B): the supplied advisory prose (the
+ * build agent's final summary, or a human `--body`) UNDER a deterministic runner
+ * header that points a reviewer back to the task file. Returns `undefined` when
+ * no body was supplied — so the provider degrades to today's `gh ... --fill` (no
+ * regression); the header is ONLY scaffolded when there IS prose to carry.
+ * Exported for unit tests of the header + pointer.
+ */
+export function composeProposeBody(input) {
+    const prose = input.body?.trim();
+    if (!prose) {
+        return undefined;
+    }
+    const header = `Task: \`${workItemRel('done', `${input.slug}.md`)}\``;
+    return `${header}\n\n${prose}`;
+}
+/**
+ * On a review APPROVE that carries ≥1 NON-BLOCKING finding, write ONE per-run
+ * observation `work/notes/observations/review-nits-<slug>-<YYYY-MM-DD>.md` capturing all
+ * of this run's non-blocking nits, so they get a durable, contract-native home
+ * instead of evaporating (the block path already routes BLOCKING findings to
+ * needs-attention/; the approve path dropped non-blocking ones — see
+ * `work/findings/review-nonblocking-findings-disposition.md`).
+ *
+ * The RUNNER writes it (the review agent stays write-free). It is a PLAIN
+ * pre-commit disk write — NOT the heavier `applyNeedsAttentionTransition`
+ * move/commit/surface — so `performIntegration`'s subsequent done-move + atomic
+ * `git add -A` commit sweeps it into the SAME done-commit on every path
+ * (merge / propose / CI, `do` AND `run`); it is never left dangling/uncommitted.
+ *
+ * ZERO non-blocking findings ⇒ writes NOTHING (no empty-file spam). The file is
+ * ONE-per-RUN (a content-derived, dated name), never an append to a shared ledger
+ * — the dated `<slug>-<date>` name makes a later-abandoned run's nit-observation
+ * trivially findable + deletable (lifecycle hygiene). Frontmatter mirrors the
+ * `work/notes/observations/*.md` convention (`title` / `date` / `status: open`) plus a
+ * `reviewOf:` back-pointer to the slug it came from, so it gets triaged like any
+ * observation. (Identity stays the FILENAME — no `slug:` frontmatter — so the
+ * lifecycle enumerate→resolve round-trip is total; see task
+ * `observation-identity-is-its-filename-not-a-foreign-slug`.)
+ */
+function writeReviewNitsObservation(params) {
+    const nits = params.findings.filter((f) => f.severity === 'non-blocking');
+    // No empty observations: an approve with zero non-blocking findings writes none.
+    if (nits.length === 0) {
+        return;
+    }
+    const date = observationDate();
+    const obsDir = workFolderPath(params.cwd, 'observations');
+    mkdirSync(obsDir, { recursive: true });
+    const filename = `review-nits-${params.slug}-${date}.md`;
+    writeFileSync(join(obsDir, filename), renderReviewNitsObservation({ slug: params.slug, date, nits }));
+    params.note(`Recorded ${nits.length} non-blocking review nit(s) for '${params.slug}' ` +
+        `in ${workItemRel('observations', filename)}.`);
+}
+/** Today's date as `YYYY-MM-DD` (UTC), for the dated observation filename. */
+function observationDate() {
+    return new Date().toISOString().slice(0, 10);
+}
+/**
+ * Render the per-run review-nits observation file body — `observations/`-convention
+ * frontmatter (`title` / `date` / `status: open`) plus a `reviewOf:` back-pointer
+ * naming the TASK the run reviewed, then each non-blocking finding (its
+ * `question` + optional `context`), and a one-line note that these are review-gate
+ * nits for triage (promote-to-task / keep / delete). Exported-free pure string
+ * builder.
+ *
+ * Identity rule (task `observation-identity-is-its-filename-not-a-foreign-slug`):
+ * the observation's IDENTITY is its FILENAME (`review-nits-<slug>-<date>.md`).
+ * The frontmatter therefore does NOT emit `slug:` — emitting the reviewed task's
+ * slug there collided with the (now-done) reviewed task AND broke the
+ * enumerate→resolve round-trip (the lifecycle pool keyed off `fm.slug`, which
+ * differed from the filename). The back-pointer lives in `reviewOf:` instead, a
+ * clearly-different field whose name cannot be mistaken for identity.
+ */
+function renderReviewNitsObservation(input) {
+    const findingBlocks = input.nits.map((f) => {
+        const ctx = f.context ? `\n  (${f.context})` : '';
+        return `- ${f.question}${ctx}`;
+    });
+    return [
+        '---',
+        `title: review-gate non-blocking nits for '${input.slug}' (Gate 2 approve)`,
+        `date: ${input.date}`,
+        'status: open',
+        `reviewOf: ${input.slug}`,
+        '---',
+        '',
+        '## Non-blocking review findings',
+        '',
+        `The PR/code review gate (Gate 2) APPROVED '${input.slug}' but raised the`,
+        'following non-blocking findings (nits). They do not block integration; this',
+        'is their durable home for triage — promote-to-task / keep / delete.',
+        '',
+        ...findingBlocks,
+        '',
+    ].join('\n');
+}
+/** Read the `title:` scalar from a task's frontmatter block, or undefined. */
+function readTitle(content) {
+    const normalized = content.replace(/\r\n/g, '\n').replace(/^\uFEFF/, '');
+    if (!normalized.startsWith('---\n')) {
+        return undefined;
+    }
+    const lines = normalized.split('\n');
+    const closing = lines.indexOf('---', 1);
+    const block = closing === -1 ? lines.slice(1) : lines.slice(1, closing);
+    for (const line of block) {
+        const match = /^title\s*:\s*(.*)$/.exec(line);
+        if (match) {
+            const value = match[1].trim();
+            return value === '' ? undefined : unquote(value);
+        }
+    }
+    return undefined;
+}
+function unquote(value) {
+    if (value.length >= 2) {
+        const first = value[0];
+        const last = value[value.length - 1];
+        if ((first === '"' || first === "'") && last === first) {
+            return value.slice(1, -1);
+        }
+    }
+    return value;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** True when the index has no staged changes against HEAD (nothing to commit). */
+async function nothingStaged(cwd, env) {
+    // `diff --cached --quiet` exits 0 when there is NOTHING staged, 1 when there is.
+    const res = await gitSoft(['diff', '--cached', '--quiet'], cwd, env);
+    return res.status === 0;
+}
+/**
+ * The capture-bucket folders a rung's agent may write notes into (its
+ * `capture-signal` reflex). REPORTED by {@link reportScoopedNotes} when the
+ * runner's atomic commit scoops them. Deliberately NARROW (only the two capture
+ * buckets) so accidental scratch files the agent left elsewhere are not announced
+ * as captured signals — matching the observation's recommended scope.
+ */
+const CAPTURE_NOTE_DIRS = [
+    workFolderPrefix('observations'),
+    workFolderPrefix('findings'),
+];
+/**
+ * SCOOP + REPORT the agent-authored CAPTURED NOTES this run's atomic commit is
+ * landing (task `runner-scoops-captured-notes`). A rung's agent writes
+ * capture-bucket files (`work/notes/observations/*`, `work/findings/*`) but does NO git
+ * (Rule A); the caller's `git add -A` already STAGED them into THIS commit, so
+ * they are tracked, not dropped. This extends Rule B: the runner REPORTS exactly
+ * which note files landed — read from the STAGED set (`git diff --cached`), so it
+ * reports what ACTUALLY reached the commit, never an assumption.
+ *
+ * It is honest reporting, the same model as the review-nits observation report:
+ * a PLAIN read + `note(...)`, no extra git (the commit owns the files). Zero
+ * captured notes ⇒ NOTHING is reported (the no-note case is byte-for-byte
+ * unchanged). Read-only / best-effort: a failed status read reports nothing
+ * rather than crashing the integrate. Because it lives in the shared core, BOTH
+ * the build path AND the tasking path report identically — the channel is not
+ * forked.
+ */
+async function reportScoopedNotes(cwd, env, note) {
+    const notes = await stagedCaptureNotes(cwd, env);
+    if (notes.length === 0) {
+        return;
+    }
+    note(`Scooped ${notes.length} agent-authored captured note` +
+        `${notes.length === 1 ? '' : 's'} into this commit: ${notes.join(', ')}.`);
+}
+/**
+ * The repo-relative paths of the capture-bucket files (`work/notes/observations/*`,
+ * `work/findings/*`) STAGED for THIS commit — i.e. new-or-changed vs HEAD, exactly
+ * what the runner is about to land. Read via `git diff --cached --name-only` so it
+ * reflects the real staged set (`git add -A` already ran), filtered to the capture
+ * buckets and sorted for a deterministic report. Best-effort: a non-zero status
+ * reads as no notes (never crashes the integrate). Exported-free; pure read.
+ */
+async function stagedCaptureNotes(cwd, env) {
+    const res = await gitSoft(['diff', '--cached', '--name-only'], cwd, env);
+    if (res.status !== 0) {
+        return [];
+    }
+    return res.stdout
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((path) => CAPTURE_NOTE_DIRS.some((dir) => path.startsWith(dir)))
+        .sort();
+}
+/**
+ * The DURABLE `work/` status folders a slug's ledger file can resting-live in (the
+ * one-slug-one-folder set the invariant is asserted over). After the capstone
+ * cut-over (task `cutover-retire-slicing-advancing-markers-and-trim-folder-sets`,
+ * prd `ledger-status-per-item-lock-refs`) the ONLY `work/` moves on `main` are the
+ * durable resting transitions, so the source a build completes FROM is `backlog/`
+ * (claim no longer moves the body, task
+ * `cutover-claim-body-stays-and-complete-sources-from-backlog`) and the canonical
+ * done-move destination is `done/`. The task regime's won't-proceed terminal
+ * `tasks/cancelled/` is also a durable resting folder, so the one-slug-one-folder
+ * guard covers it (a slug in `tasks/cancelled/` AND another durable folder is a
+ * corrupt ledger to refuse). The
+ * transient `in-progress`/`needs-attention` are GONE from `main`'s tree (they are
+ * per-item lock-ref state now).
+ */
+/**
+ * The folders {@link readArbiterLedgerPlacement} scans for a slug's source on the
+ * arbiter: the durable `LEDGER_STATUS_FOLDERS` (`tasks-ready`/`done`/`cancelled`)
+ * PLUS `tasks-backlog` (staging). Staging is included ONLY for the arbiter-side
+ * source RESOLUTION of a `--allow-backlog` done-move (prd
+ * `do-allow-backlog-drive-staged-tasks-without-promotion`) and the one-slug-one-
+ * folder guard over the malformed "same slug in `tasks/ready/` AND `tasks/backlog/`"
+ * state; it is DELIBERATELY NOT added to the shared `LEDGER_STATUS_FOLDERS` (which
+ * ledger-lint's duplicate detection + the sibling-ledger reconcile reuse and which
+ * deliberately omits the non-resting staging folder).
+ */
+const ARBITER_PLACEMENT_FOLDERS = [
+    ...LEDGER_STATUS_FOLDERS,
+    'tasks-backlog',
+];
+/**
+ * Read WHICH `work/<folder>/<slug>.md` the ARBITER currently holds the slug in,
+ * from the `<arbiter>/main` TRACKING REF (the source of truth). It is a pure READ
+ * of the ref the caller has ALREADY fetched (the step-4 rebase fetch) — it does
+ * NOT fetch, so it never races a sibling job's integration on the shared
+ * bare-mirror refs (ADR §2; a new fetch here was the regression that orphaned
+ * this very work).
+ *
+ * It ENFORCES the one-slug-one-folder invariant: if the arbiter already holds the
+ * slug in MORE THAN ONE status folder it is a pre-existing corrupt ledger — it
+ * FAILS LOUD (returns an `error`) rather than silently pick one, UNLESS it is
+ * PROVABLY SAFE (every copy is byte-identical, so the canonical `done/`
+ * destination is unambiguous), mirroring the manual `279b542` cleanup.
+ *
+ * It scans {@link ARBITER_PLACEMENT_FOLDERS} — the durable `LEDGER_STATUS_FOLDERS`
+ * PLUS `tasks-backlog`, so a `--allow-backlog` staged drive (prd
+ * `do-allow-backlog-drive-staged-tasks-without-promotion`) whose done-move sources
+ * from `tasks/backlog/` is DISCOVERED here too (the arbiter is the authority for
+ * the actual source folder; the local `source` is the fallback). Including staging
+ * also makes the one-slug-one-folder guard cover the malformed "same slug in both
+ * `tasks/ready/` and `tasks/backlog/`" state (the prd's decision 5): it FAILS LOUD
+ * rather than the resolver silently arbitrating a collision the contract forbids.
+ */
+function readArbiterLedgerPlacement(cwd, arbiter, slug, env) {
+    const arbiterRef = `${arbiter}/main`;
+    const placements = [];
+    for (const folder of ARBITER_PLACEMENT_FOLDERS) {
+        const path = workItemRel(folder, `${slug}.md`);
+        const ls = run('git', ['ls-tree', arbiterRef, path], cwd, { env });
+        const line = ls.stdout.trim();
+        if (ls.status !== 0 || line === '') {
+            continue;
+        }
+        const match = /^\d+ blob ([0-9a-f]+)\t/.exec(line);
+        if (match) {
+            placements.push({ folder, blob: match[1] });
+        }
+    }
+    const sourceFolders = placements
+        .filter((p) => p.folder !== 'done')
+        .map((p) => p.folder);
+    if (placements.length > 1) {
+        const uniqueBlobs = new Set(placements.map((p) => p.blob));
+        const folders = placements
+            .map((p) => workFolderPrefix(p.folder))
+            .join(', ');
+        if (uniqueBlobs.size !== 1) {
+            return {
+                error: `one-slug-one-folder invariant violated: '${slug}' is present in more ` +
+                    `than one status folder on ${arbiterRef} (${folders}) with DIFFERING ` +
+                    `content — refusing to publish a corrupt ledger. Resolve the duplicate ` +
+                    `(keep the correct copy, delete the stale one) and re-run; ` +
+                    `'dorfl scan'/'gc' surfaces such duplicates.`,
+                sourceFolders,
+            };
+        }
+        // Provably safe (byte-identical copies): the duplicate is auto-cleaned by the
+        // divergent-done-move reconciliation, which moves the slug to `done/` ONLY.
+    }
+    return { sourceFolders };
+}
+/** The `work/<status>/` prefixes a ledger file can live under (no trailing `/`). */
+const LEDGER_FOLDER_PREFIXES = LEDGER_STATUS_FOLDERS.map((folder) => workFolderPrefix(folder));
+/**
+ * Classify a rebase-conflicted path: is it a SIBLING-slug ledger file (a
+ * `work/<status>/<otherslug>.md` for some slug OTHER than `ourSlug`)? Returns
+ * `false` for any code file AND for THIS slug's own ledger file (both must keep
+ * routing to needs-attention — the sibling arm NEVER widens to code or own-ledger).
+ */
+function isSiblingLedgerPath(path, ourSlug) {
+    const prefix = LEDGER_FOLDER_PREFIXES.find((p) => path.startsWith(p));
+    if (prefix === undefined) {
+        return false; // not a ledger file at all — a code file (or non-ledger work/ file).
+    }
+    const rest = path.slice(prefix.length);
+    if (!rest.endsWith('.md') || rest.includes('/')) {
+        return false; // not a `<slug>.md` directly under the status folder.
+    }
+    const otherSlug = rest.slice(0, -'.md'.length);
+    return otherSlug !== ourSlug; // OUR own ledger is NOT a sibling — it routes as today.
+}
+/**
+ * Reconcile a SIBLING-SLUG ledger conflict during the step-4 rebase WITHOUT
+ * aborting it (Race 2 of `run-fleet-claim-integrate-and-sibling-rebase-concurrency-safe`).
+ * Called WHILE the rebase is still in progress (right after `git rebase` returned
+ * non-zero): a sibling same-repo job landed its OWN `work/<status>/<otherslug>.md`
+ * move on `<arbiter>/main` between our base and this rebase, so replaying our
+ * commit conflicts on that OTHER slug's ledger file — a benign ledger-only
+ * divergence, NOT a real code conflict.
+ *
+ * STRICT SCOPE (the safety fence): it reconciles ONLY when EVERY conflicted path
+ * is a SIBLING slug's ledger file ({@link isSiblingLedgerPath}). If ANY conflicted
+ * path is a CODE file, a non-ledger `work/` file, or THIS slug's OWN ledger file,
+ * it does NOTHING (returns `false`) so the caller aborts + routes to
+ * needs-attention exactly as today — it NEVER widens to code or own-ledger.
+ *
+ * The resolution takes the ARBITER's (rebased-onto) version of each sibling
+ * ledger file (`git checkout --ours` — during a rebase `--ours` is the base we are
+ * replaying ONTO, i.e. `<arbiter>/main`), stages it, and `git rebase --continue`s,
+ * looping until the rebase completes (a later replayed commit could re-conflict on
+ * a sibling ledger). Returns `true` once the rebase finished cleanly (the caller
+ * falls through to integrate); returns `false` — leaving the rebase in progress —
+ * when the conflict is out of scope (the caller aborts + routes).
+ */
+async function reconcileSiblingLedgerConflict(params) {
+    const { cwd, arbiter, slug, env } = params;
+    const arbiterRef = `${arbiter}/main`;
+    // The conflicted (unmerged) paths of the failed rebase step. Read them WHILE the
+    // rebase is still in progress (the caller invokes us right after the non-zero
+    // rebase), BEFORE we abort — so we know what conflicted.
+    const conflicted = (await gitSoft(['diff', '--name-only', '--diff-filter=U'], cwd, env)).stdout
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line !== '');
+    if (conflicted.length === 0) {
+        return false; // not a conflict we can reason about here — defer to the caller.
+    }
+    // SCOPE GATE: every conflicted path MUST be a SIBLING slug's ledger file. Any
+    // code file / own-ledger / non-ledger work file disqualifies the WHOLE
+    // reconciliation (never widen to code) — the caller aborts + routes.
+    if (!conflicted.every((path) => isSiblingLedgerPath(path, slug))) {
+        return false;
+    }
+    // Benign sibling-ledger divergence. Rather than the fragile in-progress
+    // `git rebase --continue` (which mutates the shared-worktree branch ref mid-
+    // rebase and flakes under same-repo fleet ref contention), ABORT and REDO our
+    // own work as ONE clean commit on top of `<arbiter>/main` — the SAME safe
+    // reset-and-redo pattern `reconcileDivergentDoneMove` uses. This automatically
+    // takes the arbiter's version of EVERY sibling ledger file (they live in the
+    // reset base, untouched) while preserving OUR agent edits + OUR done-move (kept
+    // in the working tree by the mixed reset). NO semantic judgement, NO `--ours`/
+    // `--theirs` heuristic on any code file.
+    await gitSoft(['rebase', '--abort'], cwd, env);
+    // Re-point the branch onto `<arbiter>/main`, KEEPING the working tree (our edits
+    // + our done-move): a mixed reset moves HEAD + index to the arbiter base but
+    // leaves the working tree intact. Our own changes stay in the tree. (`HEAD` was
+    // restored to our work-branch tip by the abort above.)
+    const reset = await gitSoft(['reset', '--mixed', '--quiet', arbiterRef], cwd, env);
+    if (reset.status !== 0) {
+        return false;
+    }
+    // Take the ARBITER's placement of every SIBLING slug whose ledger conflicted: the
+    // conflict means we touched a sibling's ledger file that the arbiter moved, so our
+    // working-tree copy is STALE. Hard-restore EVERY ledger folder for each affected
+    // sibling slug from the arbiter (index + working tree) and drop any stray copy our
+    // tree still holds, so the sibling's OWN status-folder move (e.g. its done-move) is
+    // honoured verbatim — never clobbered by our stale touch, never duplicated.
+    const siblingSlugs = new Set();
+    for (const path of conflicted) {
+        const prefix = LEDGER_FOLDER_PREFIXES.find((p) => path.startsWith(p));
+        if (prefix !== undefined) {
+            siblingSlugs.add(path.slice(prefix.length, -'.md'.length));
+        }
+    }
+    for (const otherSlug of siblingSlugs) {
+        for (const folder of LEDGER_STATUS_FOLDERS) {
+            const ledgerPath = workItemRel(folder, `${otherSlug}.md`);
+            const onArbiter = (await gitSoft(['cat-file', '-e', `${arbiterRef}:${ledgerPath}`], cwd, env)).status === 0;
+            if (onArbiter) {
+                // The arbiter holds the sibling here — take its exact copy.
+                await gitSoft(['checkout', arbiterRef, '--', ledgerPath], cwd, env);
+            }
+            else {
+                // The arbiter does NOT hold the sibling here — drop any stale copy ours has.
+                const abs = join(cwd, ledgerPath);
+                if (existsSync(abs)) {
+                    rmSync(abs, { force: true });
+                }
+            }
+        }
+    }
+    // Stage everything (our agent edits + our arbiter-aligned ledger move; the
+    // sibling ledgers are already at the arbiter version) and commit ONE clean
+    // commit on top of `<arbiter>/main`. Nothing staged ⇒ the work is already on the
+    // arbiter (an already-integrated no-op) — treat as cleanly reconciled.
+    await gitSoft(['add', '-A'], cwd, env);
+    if ((await gitSoft(['diff', '--cached', '--quiet'], cwd, env)).status === 0) {
+        return true;
+    }
+    await gitHard([
+        'commit',
+        '-q',
+        '-m',
+        `feat(${slug}): reconcile sibling-ledger rebase; done`,
+    ], cwd, env);
+    return true;
+}
+/**
+ * Recover a DIVERGENT-BASE done-move whose plain rebase CONFLICTED (ledger-
+ * integrity defect 1, the PR #86 ghost). The arbiter holds the slug's source in a
+ * DIFFERENT folder than our local done-move removed, so replaying the local
+ * `-work/<localsrc>/<slug>.md +work/done/<slug>.md` patch onto `<arbiter>/main`
+ * (which lacks `<localsrc>`) conflicts on the ledger file.
+ *
+ * It reconciles WITHOUT any semantic judgement (so it is safe automatically,
+ * unlike a real code conflict): RESET the work branch onto `<arbiter>/main` (the
+ * working tree kept), then redo the done-move ARBITER-RESOLVED — remove the slug
+ * from EVERY non-`done` folder the arbiter holds it in, write `work/done/<slug>.md`
+ * — and commit ONE done commit on top of `<arbiter>/main`. The branch ends cleanly
+ * on the arbiter with the slug in `done/` ONLY (the move is a MOVE, not a copy);
+ * no further rebase is needed.
+ *
+ * Returns `true` on success (the caller falls through to integrate). Returns
+ * `false` when this is NOT the divergent-ledger case (the arbiter holds the slug
+ * only in `done/`/nowhere, or the placement read failed) so the caller routes the
+ * genuine conflict to needs-attention unchanged.
+ */
+async function reconcileDivergentDoneMove(params) {
+    const { cwd, arbiter, slug, localSource, env } = params;
+    const arbiterRef = `${arbiter}/main`;
+    // The arbiter's current placement (read from the already-fetched ref — no
+    // fetch). This recovery applies ONLY to the divergent-LEDGER conflict: the
+    // arbiter holds the slug's source in a DIFFERENT folder than our local done-move
+    // removed it from. When the arbiter's source folder MATCHES our local source (or
+    // the arbiter holds it only in `done/`/nowhere), the rebase conflict is a
+    // genuine CODE conflict (e.g. the agent's edits vs an advanced main) — NEVER
+    // auto-resolved; defer to the needs-attention route.
+    const placement = readArbiterLedgerPlacement(cwd, arbiter, slug, env);
+    if (placement.error || placement.sourceFolders.length === 0) {
+        return false;
+    }
+    if (placement.sourceFolders.includes(localSource)) {
+        // The arbiter still holds the slug in the SAME source folder we moved from —
+        // the ledger placement agrees, so the conflict is NOT a divergent-ledger one.
+        return false;
+    }
+    // Capture the slug's ledger content (our tip's done/ copy, or any source copy)
+    // BEFORE we reset — it is what lands in `done/`.
+    let ledgerContent;
+    // Scan the ARBITER-placement set (durable folders PLUS `tasks-backlog`) so a
+    // `--allow-backlog` staged-drive's source copy is captured too. `done` first so
+    // our tip's already-moved copy wins.
+    const captureOrder = [
+        'done',
+        ...ARBITER_PLACEMENT_FOLDERS,
+    ];
+    for (const folder of captureOrder) {
+        const abs = workItemPath(cwd, folder, slug);
+        if (existsSync(abs)) {
+            ledgerContent = readFileSync(abs, 'utf8');
+            break;
+        }
+    }
+    // Re-point the branch onto `<arbiter>/main`, KEEPING the working tree (the
+    // agent's edits + our done/ file): a mixed reset moves HEAD + the index to the
+    // arbiter base but leaves the working tree intact. We then fix only the LEDGER
+    // placement against the arbiter and commit one clean done commit.
+    const reset = await gitSoft(['reset', '--mixed', '--quiet', arbiterRef], cwd, env);
+    if (reset.status !== 0) {
+        return false;
+    }
+    // Arbiter-resolved ledger placement: write `done/` from the captured content,
+    // and remove every non-`done` copy (the arbiter's source folder is now checked
+    // out by the reset; any stale local source is swept too).
+    mkdirSync(workFolderPath(cwd, 'done'), { recursive: true });
+    const donePath = workItemPath(cwd, 'done', slug);
+    if (ledgerContent !== undefined) {
+        writeFileSync(donePath, ledgerContent);
+    }
+    // Sweep every non-`done` copy the arbiter could hold the slug in, INCLUDING
+    // `tasks-backlog` (a `--allow-backlog` staged drive), so the move is a MOVE not
+    // a copy.
+    for (const folder of ARBITER_PLACEMENT_FOLDERS) {
+        if (folder === 'done') {
+            continue;
+        }
+        const abs = workItemPath(cwd, folder, slug);
+        if (existsSync(abs)) {
+            rmSync(abs, { force: true });
+        }
+    }
+    // Stage everything (agent work + the arbiter-aligned ledger move) and commit a
+    // single done commit on top of `<arbiter>/main`. Nothing staged ⇒ the slug is
+    // already done on the arbiter (an already-integrated no-op) — treat as cleanly
+    // reconciled.
+    await gitSoft(['add', '-A'], cwd, env);
+    if ((await gitSoft(['diff', '--cached', '--quiet'], cwd, env)).status === 0) {
+        return true;
+    }
+    await gitHard(['commit', '-q', '-m', `feat(${slug}): reconcile done-move; done`], cwd, env);
+    return true;
+}
+/**
+ * Run the Gate-2 PR/code REVIEW gate against a given tree ({@param reviewCwd}) and
+ * route a BLOCK to needs-attention, returning DATA the caller acts on. Factored out
+ * of {@link performIntegration} so the SAME gate can run in TWO places without
+ * forking its logic (MAINTAINER DECISION 2, task `gate-on-rebased-tip-fresh-worktree`):
+ *
+ *   - fresh-worktree gate OFF: the caller invokes it at the FRONT on the pre-rebase
+ *     `cwd`, right after the front `verify` (today's order, byte-for-byte);
+ *   - fresh-worktree gate ON: the caller invokes it on the REBASED TIP (the fresh
+ *     gate worktree), right AFTER the rebased-tip `verify` passes — so
+ *     verify-THEN-review holds on the SAME merged tree.
+ *
+ * The review AGENT inspects {@param reviewCwd} (the tree under review); the
+ * needs-attention ROUTING always targets `params.cwd` (where the work branch +
+ * ledger live), so the routing is identical whichever tree was reviewed — ONLY the
+ * source of the reviewed tree moved, not the verdict handling.
+ *
+ * It NEVER mutates `mode` or writes the nits observation itself (those are the
+ * caller's concern, because WHEN they happen differs by path — pre-commit on OFF,
+ * post-commit-amend on ON); it returns the verdict and lets the caller place those
+ * effects correctly for its band position.
+ */
+async function runGate2Review(params) {
+    const { reviewCwd, input, slug, branch, cwd, env, note } = params;
+    const reviewGate = input.reviewGate;
+    if (!reviewGate) {
+        // `review` on with no gate wired is a usage error — the floor must never be
+        // silently skipped. (Production always wires `harnessReviewGate`.) The caller's
+        // try/catch maps a thrown error to its usage-error outcome.
+        throw new Error(`review is on but no review gate is configured — cannot run Gate 2 ` +
+            `for '${slug}' (this is a wiring bug; the gate must not be skipped).`);
+    }
+    const maxRounds = Math.max(1, input.reviewMaxRounds ?? 2);
+    note('Running the PR/code review gate (Gate 2)…');
+    // CORROBORATED-APPROVAL semantics (NOT retry-until-pass): the gate runs the
+    // reviewer up to `reviewMaxRounds` times on the SAME tip and approves ONLY if
+    // EVERY round approves. A `block` is TERMINAL — it short-circuits the loop and
+    // is never re-rolled, because the reviewer is stochastic and re-reviewing an
+    // UNCHANGED tip after a block would just be a dice re-roll that could launder a
+    // real reject into a pass. The extra rounds therefore exist to make a FALSE
+    // APPROVE harder to slip through (a second reviewer gets a veto), never to give
+    // blocked work a second chance. (A future builder-REVISE step that mutates the
+    // tree between rounds is the ONLY thing that should make a block retryable; it
+    // would change the artifact under review and is not implemented here.)
+    let approved = false;
+    let lastVerdict;
+    for (let round = 1; round <= maxRounds; round++) {
+        let verdict;
+        try {
+            verdict = await reviewGate({
+                slug,
+                cwd: reviewCwd,
+                reviewModel: input.reviewModel,
+                round,
+                // `--watch` threading (task `watch-review-session`): when on, the production
+                // gate tails the review session live. OFF ⇒ the plain sync launch, unchanged.
+                watch: input.watch,
+                watchSink: input.watchSink,
+                color: input.color,
+                sessionsDir: input.sessionsDir,
+                // The review AGENT launches with the AMBIENT env, never the identity-scoped
+                // `env` (an agent must not act as the bot). Falls back to `env` when no
+                // identity is configured (unchanged for non-identity callers).
+                env: input.agentEnv ?? env,
+            });
+        }
+        catch (err) {
+            if (!(err instanceof ReviewParseError)) {
+                // Anything else (a harness/connection throw, a programmer bug) is NOT this
+                // gate's concern — re-throw so the existing catch sites classify it.
+                throw err;
+            }
+            // THE GATE RAN BUT ITS VERDICT WAS UNREADABLE (direction 1, the safety net):
+            // the reviewer did NOT block — the gate's OUTPUT could not be parsed (a
+            // malformed JSON verdict, common on large diffs + weaker models, AFTER the
+            // direction-2 repair pass could not salvage it). WITHOUT this catch the throw
+            // escapes the core and `performComplete` maps it to the generic `usage-error`
+            // (verbatim, no push, no surface) AFTER the green build but BEFORE the
+            // done-move/push — STRANDING the lock + work branch with no PR.
+            //
+            // A parse failure in ANY round is TERMINAL: route IMMEDIATELY, never re-roll
+            // the remaining rounds (mirroring the block-is-terminal rule — re-reviewing
+            // the same tip would just be the dice re-roll the corroboration loop forbids).
+            // We route through the SAME work-preserving `applyNeedsAttentionTransition`
+            // seam the block path uses (it PUSHES the work branch + surfaces the item on
+            // `surfaceArbiter` for the autonomous path), targeting `cwd` (the work branch +
+            // ledger), NOT the throwaway `reviewCwd` — so BOTH the direct `!freshWorktreeGate`
+            // path AND the fresh-worktree `review:` callback are covered by this ONE catch.
+            // The recorded reason carries the parse-failure phrase the `failure-cause.ts`
+            // signature matches → the `do`/`run` tail classifies it `transient-infra`
+            // (retry the SAME work: the gate output is STOCHASTIC, so a re-run CAN differ,
+            // and the direction-2 repair makes a re-run far more likely to parse). NEVER a
+            // silent approve.
+            const reason = `PR/code review (Gate 2) ran but its verdict could not be parsed: ` +
+                `${err.message}`;
+            const routed = await ledgerWrite.applyNeedsAttentionTransition({
+                cwd,
+                slug,
+                reason,
+                arbiter: input.surfaceArbiter,
+                env,
+                note,
+            });
+            const message = routed.moved
+                ? `PR/code review (Gate 2) produced an UNPARSEABLE verdict for '${slug}'; ` +
+                    'routed it to work/needs-attention/ (work branch pushed + surfaced; ' +
+                    'transient-infra — re-run). NOT integrated.'
+                : `PR/code review (Gate 2) produced an UNPARSEABLE verdict for '${slug}'; ` +
+                    'NOT integrating.';
+            note(message);
+            return {
+                kind: 'blocked',
+                result: {
+                    outcome: 'review-unparseable',
+                    routedToNeedsAttention: routed.moved,
+                    branch,
+                    reason,
+                },
+            };
+        }
+        lastVerdict = verdict;
+        if (verdict.verdict !== 'approve') {
+            // A `block` is TERMINAL: stop now (never re-roll an unchanged tip) and route
+            // the blocking findings to needs-attention below. `approved` stays false.
+            approved = false;
+            break;
+        }
+        // An `approve`: provisionally approved, but keep going — every remaining round
+        // must ALSO approve for the gate to pass (corroboration, not first-approve-wins).
+        approved = true;
+    }
+    if (!approved) {
+        // NON-approve verdict: route to needs-attention via the SAME seam the red gate
+        // uses, NEVER integrate. We reach here EITHER because a round returned a
+        // (terminal) block, OR because not every round corroborated the approve. The
+        // reason records the last verdict's blocking findings (the proximate cause) plus
+        // the `reviewMaxRounds` note (so a single-round block also reads correctly).
+        const findingsReason = lastVerdict ? formatBlockReason(lastVerdict) : '';
+        const reason = (findingsReason ? findingsReason + '\n' : '') +
+            reviewRoundsExhaustedReason(maxRounds);
+        const routed = await ledgerWrite.applyNeedsAttentionTransition({
+            cwd,
+            slug,
+            reason,
+            // Same autonomous-vs-human gate as the red-gate path: `do` passes the arbiter
+            // (surface on main + push the branch), the human `complete` leaves it unset.
+            arbiter: input.surfaceArbiter,
+            env,
+            note,
+        });
+        const message = routed.moved
+            ? `PR/code review (Gate 2) blocked '${slug}'; routed it to ` +
+                'work/needs-attention/ (surfaced by status; the blocking findings are ' +
+                'recorded in the item body). NOT integrated.'
+            : `PR/code review (Gate 2) blocked '${slug}'; NOT integrating.`;
+        note(message);
+        return {
+            kind: 'blocked',
+            result: {
+                outcome: 'review-blocked',
+                routedToNeedsAttention: routed.moved,
+                branch,
+                reason: message,
+                // The structured block reason (the blocking findings ONLY) for a caller
+                // doing its OWN routing (the tasking path); the build path ignores it.
+                reviewBlockReason: findingsReason || message,
+            },
+        };
+    }
+    note(`PR/code review (Gate 2) approved '${slug}'.`);
+    return {
+        kind: 'approved',
+        verdict: lastVerdict,
+    };
+}
+/**
+ * Run the acceptance gate (`prepare` then `verify`) in a CLEAN THROWAWAY worktree
+ * cut from `commit` (the work branch tip AFTER it was rebased onto `<arbiter>/main`
+ * — the would-be-integrated tip), then REAP the worktree (pass OR fail). This is
+ * the fresh-worktree gate (task `gate-on-rebased-tip-fresh-worktree`): a green
+ * gate provably describes the MERGED artifact, because the worktree is cut from the
+ * COMMITTED, rebased tip — gitignored/uncommitted state in the agent's `cwd` cannot
+ * leak in, and a change the integration rebase introduced IS gated.
+ *
+ * The worktree is registered on `cwd`'s git common dir (`git worktree add --detach`
+ * run IN `cwd`), so it works for BOTH isolation strategies: an in-place clone
+ * (`<cwd>/.git`) and a job worktree cut from a bare hub mirror (the mirror's git
+ * dir). It is a TRANSIENT gate sandbox — distinct from the agent's job worktree — and
+ * is ALWAYS removed afterwards (`git worktree remove --force` + a dir cleanup
+ * fallback), never leaked (cross-ref the worktree-hygiene/reap discipline in
+ * `gc.ts`). The throwaway worktree is fresh (no deps), so `prepare` runs in it
+ * before `verify` (forced — `useMarker: false` — since it is per-gate); a failing
+ * `prepare` short-circuits and never runs `verify` (the env could not be made
+ * ready), surfaced distinctly as `kind: 'prepare'`.
+ *
+ * GATE-2 REVIEW (MAINTAINER DECISION 2): when a `review` callback is supplied (the
+ * caller resolved `review` ON), the review runs HERE — AFTER the rebased-tip
+ * `verify` passes, against THIS fresh gate worktree (the rebased tip) — so
+ * verify-THEN-review holds on the SAME merged tree. The review runs INSIDE the
+ * worktree's lifetime (before it is reaped), so the review agent inspects the
+ * rebased tip. Its outcome is returned in {@link FreshGateResult.review} for the
+ * caller to route/act on; the worktree is reaped regardless of the verdict.
+ */
+async function runFreshWorktreeGate(params) {
+    const { cwd, commit, env, note } = params;
+    // A throwaway gate-sandbox dir OUTSIDE any tracked tree (the OS temp area), so it
+    // can never be swept into a commit and is naturally disposable.
+    const gateDir = mkdtempSync(join(tmpdir(), 'dorfl-fresh-gate-'));
+    // `git worktree add` will refuse to add into a non-empty existing dir, so add a
+    // child path under the (empty) mkdtemp dir.
+    const worktreeDir = join(gateDir, 'tip');
+    try {
+        // Cut a CLEAN DETACHED worktree from the rebased tip. Detached (no branch) so it
+        // never collides with the work branch already checked out in `cwd`.
+        await gitHard(['worktree', 'add', '--quiet', '--detach', worktreeDir, commit], cwd, env);
+        note('Running the acceptance gate (prepare then verify) on the rebased tip in ' +
+            'a clean throwaway worktree…');
+        // prepare: a fresh worktree has no deps, so install BEFORE verify. Forced per
+        // gate (`useMarker: false`) — this worktree is throwaway. Unset ⇒ a no-op.
+        const prep = await ensurePrepared({
+            cwd: worktreeDir,
+            prepare: params.prepare,
+            env,
+            useMarker: false,
+        });
+        if (!prep.passed) {
+            return { passed: false, kind: 'prepare', exitCode: prep.exitCode };
+        }
+        const gate = await runVerify({
+            cwd: worktreeDir,
+            verify: params.verify,
+            env,
+        });
+        if (!gate.passed) {
+            return { passed: false, kind: 'verify', exitCode: gate.exitCode };
+        }
+        // GATE-2 REVIEW on the rebased tip, AFTER the green verify (verify-then-review
+        // on the SAME merged tree). Runs while the worktree is still live (the review
+        // agent inspects the rebased tip). The outcome is returned for the caller to
+        // route/act on.
+        const review = params.review ? await params.review(worktreeDir) : undefined;
+        return { passed: true, review };
+    }
+    finally {
+        // REAP the throwaway fresh-gate worktree (pass or fail) — never leak it. Remove the
+        // git-registered worktree first (so the common dir has no dangling
+        // registration), then best-effort drop the temp dir + prune.
+        try {
+            await gitSoft(['worktree', 'remove', '--force', worktreeDir], cwd, env);
+        }
+        catch {
+            // best-effort
+        }
+        try {
+            await gitSoft(['worktree', 'prune'], cwd, env);
+        }
+        catch {
+            // best-effort
+        }
+        try {
+            rmSync(gateDir, { recursive: true, force: true });
+        }
+        catch {
+            // best-effort
+        }
+    }
+}
+/** Run git, returning the raw result (no throw) — for soft checks. */
+function gitSoft(args, cwd, env) {
+    return runAsync('git', args, cwd, { env });
+}
+/** Run git; throw on non-zero (genuinely unexpected plumbing failures). */
+async function gitHard(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;
+}
+//# sourceMappingURL=integration-core.js.map