@ai-dossier/sched 0.31.0 → 0.33.0

package/dist/batch-dispatch.js

@@ -95,6 +95,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.memberBranchFor = memberBranchFor;
 exports.evictMemberAndContinue = evictMemberAndContinue;
 exports.resumeBlockedGate = resumeBlockedGate;
 exports.runBatchTick = runBatchTick;
@@ -529,7 +530,312 @@ function runBatchSetup(deps, batch, now) {
     }
     return { ok: true, branch, worktree, runId: mintedRunId, poolClaimed: false };
 }
-/** Spawn one batch member's `slot-cycle` agent into the slot batch-setup (or a prior member) just released. */
+// --- Member worktrees (#677, RFC-0001 §J.3) ---
+/**
+ * The current member's own branch: `batch/<id>-m<n>-<issue>` (#677) — member
+ * index and issue both in the name, and deterministic from persisted state,
+ * so a takeover redispatch, a `sched resume --batch` recheck, and teardown
+ * all re-derive the same string without a lookup table. Distinct from the
+ * integration branch (`batch/<id>-<date>`): the member commits here, the
+ * scheduler lands it there.
+ */
+function memberBranchFor(batchId, memberIndex, issue) {
+    return `batch/${batchId}-m${memberIndex}-${issue}`;
+}
+/** The worktree path a cold member-worktree prep creates for one member. */
+function memberWorktreePathFor(deps, batchId, memberIndex, issue) {
+    return path.join(deps.repoDir, 'worktrees', `batch-${batchId}-m${memberIndex}-${issue}`);
+}
+/**
+ * Prepare the CURRENT member's own worktree and branch (#677, AC5): a
+ * worktree whose checked-out branch is `memberBranchFor(...)` created OFF the
+ * integration branch, warm before the member's first command, and pushed so
+ * the member agent can commit and push to it — `member-cycle`'s Step 0
+ * preconditions (inside a worktree, on YOUR member branch, clean, env warm).
+ * The agent never creates either; a prompt change without this preparation
+ * fails every member on precondition 2 (the reason #677 exists).
+ *
+ * Pool claim first — warm by construction, mirroring `runBatchSetup`. A pool
+ * spare sits on the default branch, so the claimed tree is re-pointed at the
+ * member branch off the INTEGRATION branch (`git checkout -B` against the
+ * `origin/<integration>` ref `runBatchSetup`'s push already created
+ * repo-wide); checkout preserves the installed `node_modules`. Cold fallback:
+ * `git worktree add` at the integration branch tip + `warmColdBatchWorktree`
+ * (#561 — a cold member is an evicted member).
+ *
+ * An on-disk worktree for the SAME member is reused as-is (takeover
+ * redispatch, api-error hold retry): the branch is already checked out, the
+ * tree already warm, and a takeover agent resumes in place — possibly dirty,
+ * which is the parent's state to reason about, not something to reset.
+ *
+ * All-or-nothing like `runBatchSetup`; the exec calls run OUTSIDE any store
+ * lock (the caller's contract), with results landed as pure data.
+ */
+/**
+ * The pool CLI's stdout hardening shared by `runBatchSetup` and the member
+ * prep (no NUL/newline, absolute, resolved, on disk) — our own CLI's
+ * output, but garbage would otherwise be trusted as a `BatchEntry`
+ * worktree path and used as a spawn/exec cwd.
+ */
+function usablePoolClaim(deps, w) {
+    return (!!w &&
+        !w.includes('\0') &&
+        !w.includes('\n') &&
+        path.isAbsolute(w) &&
+        path.resolve(w) === w &&
+        (deps.fsExists ?? ((p) => fs.existsSync(p)))(w));
+}
+function prepareMemberWorktree(deps, batch, memberIndex, issue, now) {
+    if (batch.branch === null)
+        return { ok: false, reason: 'no-integration-branch' };
+    const branch = memberBranchFor(batch.id, memberIndex, issue);
+    const worktree = memberWorktreePathFor(deps, batch.id, memberIndex, issue);
+    if (!attribution_1.SAFE_REF_RE.test(branch))
+        return { ok: false, reason: 'invalid-member-branch-name' };
+    const fsExists = deps.fsExists ?? ((p) => fs.existsSync(p));
+    const root = deps.exec('git', ['rev-parse', '--show-toplevel'], deps.repoDir) ?? deps.repoDir;
+    if (!(0, teardown_1.isSafeWorktree)(path.resolve(root), worktree)) {
+        return { ok: false, reason: 'invalid-member-worktree-path' };
+    }
+    // All-or-nothing rollback for the cold path (same contract as
+    // `runBatchSetup`): a warm or push failure otherwise leaves a cold
+    // worktree the NEXT retry's exists-check reuses forever cold — exactly
+    // the env-cold eviction #561 removed.
+    const rollbackColdPrep = () => {
+        deps.exec('git', ['worktree', 'remove', '--force', '--', worktree], deps.repoDir);
+        deps.exec('git', ['branch', '-D', branch], deps.repoDir);
+    };
+    const exists = fsExists(worktree);
+    if (exists) {
+        // Crash-window reuse: the derived-path tree exists on disk but the
+        // spawn never landed (fields null) — OR a pool-claimed tree whose
+        // directory name equals the derived slug (the pool renames claims to
+        // the branch slug, so a pool tree CAN sit at the derived path; the
+        // persisted `member_pool_claimed` is the only record of which). In
+        // either case the on-disk tree wins: reuse it rather than re-branching.
+        // #632: fires once per crash window, not per tick — the call sites run
+        // at spawn time (a transition point), and `claimMemberResolution`
+        // gates the member advance; the capacity pre-check in
+        // `spawnMemberContinuation` keeps the wedge path from re-entering
+        // while no slot is free.
+        deps.journal.append((0, journal_1.unitEvent)('member-worktree-reused', unit(batch.id), {
+            issue,
+            detail: worktree,
+        }), now);
+        return {
+            ok: true,
+            branch: batch.member_branch ?? branch,
+            worktree: batch.member_worktree ?? worktree,
+            poolClaimed: batch.member_pool_claimed,
+        };
+    }
+    const claimed = deps.exec(teardown_1.POOL_BIN, [...teardown_1.POOL_ARGS_PREFIX, 'claim', '--issue', String(issue), '--branch', branch], deps.repoDir);
+    const claimedWorktree = claimed?.trim();
+    if (claimedWorktree && usablePoolClaim(deps, claimedWorktree)) {
+        // Re-point the warm spare at the member branch off the integration
+        // branch — `origin/<integration>` exists repo-wide (runBatchSetup pushed
+        // it), and `checkout -B` preserves the installed node_modules.
+        if (deps.exec('git', ['checkout', '-B', branch, `origin/${batch.branch}`], claimedWorktree) ===
+            null) {
+            deps.exec(teardown_1.POOL_BIN, [...teardown_1.POOL_ARGS_PREFIX, 'return', '--path', claimedWorktree, '--json'], deps.repoDir);
+            return { ok: false, reason: 'member-branch-checkout-failed' };
+        }
+        if (deps.exec('git', ['push', '-u', 'origin', '--', branch], claimedWorktree) === null) {
+            deps.exec(teardown_1.POOL_BIN, [...teardown_1.POOL_ARGS_PREFIX, 'return', '--path', claimedWorktree, '--json'], deps.repoDir);
+            return { ok: false, reason: 'member-branch-push-failed' };
+        }
+        return { ok: true, branch, worktree: claimedWorktree, poolClaimed: true };
+    }
+    const poolNote = claimedWorktree ? 'pool-claim-invalid:' : '';
+    const added = deps.exec('git', ['worktree', 'add', '-b', branch, worktree, batch.branch], deps.repoDir) !== null;
+    if (!added) {
+        // Self-heal the crash window a teardown died in (branch kept, tree
+        // gone): `worktree add -b` fails while the stale branch exists. The
+        // member branch is disposable by construction — a member whose branch
+        // still matters is CURRENT, and a current member's tree is reused by
+        // the exists-check above, never re-added. Force-delete the stale ref
+        // and retry the add once.
+        if (deps.exec('git', ['branch', '-D', branch], deps.repoDir) === null) {
+            return { ok: false, reason: 'member-worktree-add-failed' };
+        }
+        if (deps.exec('git', ['worktree', 'add', '-b', branch, worktree, batch.branch], deps.repoDir) === null) {
+            return { ok: false, reason: 'member-worktree-add-failed' };
+        }
+    }
+    const warmed = warmColdBatchWorktree(deps, batch, worktree, now, poolNote);
+    if (!warmed.ok) {
+        rollbackColdPrep();
+        return { ok: false, reason: warmed.reason };
+    }
+    if (deps.exec('git', ['push', '-u', 'origin', '--', branch], worktree) === null) {
+        rollbackColdPrep();
+        return { ok: false, reason: 'member-branch-push-failed' };
+    }
+    return { ok: true, branch, worktree, poolClaimed: false };
+}
+/**
+ * Land the CURRENT member's work on the integration branch (#677, §J.3: "a
+ * member lands its commit onto the integration branch when its own
+ * verification passes"): `git merge --ff-only <member_branch>` in the shared
+ * batch worktree (which holds the integration branch), then push.
+ *
+ * Fast-forward is always available under the SERIAL dispatch model — only
+ * the member moved its branch since it was cut, and nothing else moves the
+ * integration branch mid-`executing` (fix agents only run from the
+ * post-last-member aggregate validation). A failed merge therefore means the
+ * serial invariant broke, not a conflict to resolve: the batch BLOCKS for an
+ * operator instead of silently merging or reverting. Linear history is also
+ * what `boundaryCommits`/`memberRanges` attribution expects — the member's
+ * `(#<issue>)`-trailed subjects stay first-parent-readable after the landing.
+ */
+function landMemberBranch(deps, batchId, now) {
+    const state = deps.store.load();
+    const batch = (0, state_1.findBatch)(state, batchId);
+    if (!batch || batch.worktree === null || batch.branch === null || batch.member_branch === null) {
+        return { ok: true };
+    }
+    const memberIssue = batch.members[batch.executing_member - 1];
+    // #677 review (defense in depth, matching `branchMergedIntoBase`'s bar):
+    // the persisted ref reaches git argv below — re-validate its shape.
+    if (!attribution_1.SAFE_REF_RE.test(batch.member_branch) || !attribution_1.SAFE_REF_RE.test(batch.branch)) {
+        journalEvent(deps, 'landing-failed', unit(batchId), {
+            issue: memberIssue,
+            reason: 'invalid-branch-name',
+            detail: `persisted member/integration branch failed SAFE_REF_RE: ${batch.member_branch} → ${batch.branch}`,
+        });
+        return { ok: false, reason: 'invalid-branch-name' };
+    }
+    if (deps.exec('git', ['merge', '--ff-only', batch.member_branch], batch.worktree) === null) {
+        journalEvent(deps, 'landing-failed', unit(batchId), {
+            issue: memberIssue,
+            reason: 'landing-merge-failed',
+            detail: `git merge --ff-only ${batch.member_branch} into ${batch.branch} failed — serial-landing invariant broken; blocking for an operator`,
+        });
+        return { ok: false, reason: 'landing-merge-failed' };
+    }
+    if (deps.exec('git', ['push', 'origin', '--', batch.branch], batch.worktree) === null) {
+        journalEvent(deps, 'landing-failed', unit(batchId), {
+            issue: memberIssue,
+            reason: 'landing-push-failed',
+            detail: `landed ${batch.member_branch} on ${batch.branch} locally but the push failed — blocking so origin stays the durable copy`,
+        });
+        return { ok: false, reason: 'landing-push-failed' };
+    }
+    deps.journal.append((0, journal_1.unitEvent)('member-landed', unit(batchId), {
+        issue: memberIssue,
+        detail: `${batch.member_branch} fast-forwarded onto ${batch.branch}`,
+    }), now);
+    return { ok: true };
+}
+/**
+ * Tear the CURRENT member's worktree down and clear the member fields
+ * (#677): pool-claimed trees are RETURNED to the pool (a raw remove leaves a
+ * dangling pool entry — the corrupted-entry state `worktree-pool status`
+ * reports), cold trees are removed. The member branch is deleted locally —
+ * `-d` after a landing (fully merged into the integration branch), `-D` on
+ * the eviction path (its commits never landed; the requeue carries the work
+ * forward). The REMOTE member branch is deleted only on the landed path, and
+ * deliberately KEPT on eviction — the pushed sha is the evicted work's only
+ * recoverable copy.
+ *
+ * Best-effort and idempotent: null fields are a no-op, and a failed cleanup
+ * journals `teardown-failed` rather than throwing into the caller's
+ * advance/dissolve path.
+ */
+function teardownMemberWorktree(deps, batchId, now, 
+/** Whether the member's branch was ff-landed onto the integration branch. Passed explicitly by the callers that KNOW — deriving it from `batch.ranges` would silently force-delete a merged branch if a caller ever reached teardown after the member pointer advanced. */
+landed) {
+    const state = deps.store.load();
+    const batch = (0, state_1.findBatch)(state, batchId);
+    if (!batch || batch.member_worktree === null)
+        return;
+    const worktree = batch.member_worktree;
+    const branch = batch.member_branch;
+    // #677 review (defense in depth, matching `branchMergedIntoBase`'s bar):
+    // persisted state reaches git argv here — re-validate the ref shape before
+    // interpolating it.
+    if (branch !== null && !attribution_1.SAFE_REF_RE.test(branch)) {
+        journalEvent(deps, 'teardown-failed', unit(batchId), {
+            cleanup: 'failed-invalid-branch-name',
+            detail: branch,
+        });
+        return;
+    }
+    // Route through `runTeardown` for the same guarantees `teardownBatch`
+    // gets: pool returns are verify-first idempotent and refuse to claim
+    // success unless the pool's own self-check reports the entry `warm`;
+    // cold removes post-verify the path is gone and unlisted. Nulls first —
+    // clear the fields BEFORE the exec so a crash mid-teardown doesn't retry
+    // into a half-cleaned tree (the re-derived path is deterministic if a
+    // leftover does survive).
+    deps.store.withLock((s) => {
+        const b = (0, state_1.findBatch)(s, batchId);
+        if (!b)
+            return { state: s, result: undefined };
+        return {
+            state: (0, state_1.patchBatch)(s, batchId, { member_branch: null, member_worktree: null, member_pool_claimed: false }, now),
+            result: undefined,
+        };
+    });
+    const t = (0, teardown_1.runTeardown)(deps.exec, deps.repoDir, { worktree, poolClaimed: batch.member_pool_claimed === true, branch }, deps.fsExists);
+    const treeCleared = !t.cleanup.startsWith('failed');
+    let branchCleanup = 'skipped';
+    if (branch !== null && treeCleared) {
+        // `-d` refuses an unmerged branch; the eviction path forces it
+        // deliberately (see doc). Run from repoDir — the worktree is gone.
+        const flag = landed ? '-d' : '-D';
+        branchCleanup =
+            deps.exec('git', ['branch', flag, branch], deps.repoDir) === null
+                ? `failed-branch-delete-${flag}`
+                : `branch-deleted-${flag}`;
+        if (landed) {
+            deps.exec('git', ['push', 'origin', '--delete', branch], deps.repoDir);
+        }
+    }
+    const failed = !treeCleared || branchCleanup.startsWith('failed');
+    journalEvent(deps, failed ? 'teardown-failed' : 'member-worktree-torn-down', unit(batchId), {
+        cleanup: t.cleanup,
+        branch_cleanup: branchCleanup,
+        detail: t.detail,
+        worktree,
+    });
+}
+/**
+ * The shared "block the batch for an operator" tail (#677 review — the same
+ * load → `recoveryDeps` → `blockBatch` → re-apply sequence
+ * `runValidate`'s suite-unreadable path and `runIncrementalGate`'s
+ * inconclusive path each grew): releases nothing itself — callers release
+ * their own slot first — and always reports the unit under `failed`.
+ */
+function blockBatchForOperator(deps, config, batchId, opts, now, result) {
+    const stateNow = deps.store.load();
+    const fresh = (0, state_1.findBatch)(stateNow, batchId);
+    if (!fresh)
+        return;
+    const blocked = (0, recovery_1.blockBatch)(stateNow, batchId, opts, recoveryDeps(deps, config, fresh, now));
+    deps.store.withLock((s) => ({
+        state: applyBatchAndIssues(s, blocked.state, batchId, []),
+        result: undefined,
+    }));
+    result.failed.push(unit(batchId));
+}
+/**
+ * Block the batch on a mechanical landing failure (#677): release the slot,
+ * persist `blocked_reason`, and journal — the same operator-inspection path
+ * `suite-unreadable` uses. The member's work is safe (its branch is pushed);
+ * only the integration step failed.
+ */
+function blockLandingFailure(deps, config, batch, reason, now, result) {
+    deps.store.withLock((s) => ({ state: releaseSlot(s, batch.id, now), result: undefined }));
+    blockBatchForOperator(deps, config, batch.id, { reason }, now, result);
+}
+/**
+ * Spawn one batch member's member-cycle agent (#677) into the slot a prior
+ * member (or batch-setup) just released — each member in its OWN worktree
+ * off the integration branch, dispatched serially as before. Prepared by
+ * {@link prepareMemberWorktree} at the spawn site (outside the lock); this
+ * function only patches state and spawns.
+ */
 /**
  * Drive a member's `QueueEntry` through the D.1 slot-line states it must pass
  * through before `shipped-in-batch` becomes a legal edge (`validated` is the
@@ -567,15 +873,15 @@ function advanceMemberToValidated(state, memberIssue, now) {
     }
     return next;
 }
-function spawnMember(deps, dispatch, state, slot, batchId, now, result) {
+function spawnMember(deps, dispatch, state, slot, batchId, now, result, member) {
     const batch = (0, state_1.findBatch)(state, batchId);
-    if (!batch || batch.worktree === null) {
+    if (!batch || batch.worktree === null || batch.branch === null) {
         // A leaked `assigned` slot with `pid: null` is invisible to `dead`
         // detection (nothing ever kills/reclaims it) — release it here rather
         // than leaving the batch permanently down one slot of capacity.
         journalEvent(deps, 'unit-failed', unit(batchId), {
             reason: 'no-worktree',
-            detail: 'spawnMember: batch has no worktree — batch-setup has not landed',
+            detail: 'spawnMember: batch has no worktree/branch — batch-setup has not landed',
         });
         return releaseSlot(state, batchId, now);
     }
@@ -591,7 +897,10 @@ function spawnMember(deps, dispatch, state, slot, batchId, now, result) {
     const tier = (0, state_1.findEntry)(withStatus, memberIssue)?.tier ?? 'mid';
     const spawnSpec = (0, dispatch_1.resolveTierSpawn)(dispatch, tier, memberIssue);
     const cmd = spawnSpec.cmd;
-    const prompt = (0, dispatch_1.buildMemberPrompt)(dispatch.memberPrompt, memberIssue, batchId, batch.worktree);
+    // #677: the prompt carries THIS member's own worktree and the integration
+    // branch it was cut from — `member-cycle`'s `worktree`/`integration_branch`
+    // inputs. The shared batch worktree is no longer a member surface at all.
+    const prompt = (0, dispatch_1.buildMemberPrompt)(dispatch.memberPrompt, memberIssue, batchId, member.worktree, batch.branch);
     const logFile = (0, dispatch_1.batchMemberLogPath)(deps.store.runsDir, batchId, batch.executing_member, memberIssue);
     // #629: captured BEFORE spawning, mirroring `engine.ts`'s own
     // `spawnAndRecord` — the log is per-role and append-mode, so the size at
@@ -622,9 +931,18 @@ function spawnMember(deps, dispatch, state, slot, batchId, now, result) {
         spawned_at: now.toISOString(),
         log_offset_at_spawn: logOffset,
     };
-    const next = slot.status === 'assigned' || slot.status === 'recovering'
+    let next = slot.status === 'assigned' || slot.status === 'recovering'
         ? (0, state_1.transitionSlot)(withStatus, slot.id, 'running', patch, now)
         : withStatus;
+    // #677: persist the member's worktree context — a takeover redispatch or a
+    // `sched resume --batch` recheck after an engine restart must land in the
+    // SAME worktree/branch this prompt names, not re-derive (or worse,
+    // re-create) it.
+    next = (0, state_1.patchBatch)(next, batchId, {
+        member_branch: member.branch,
+        member_worktree: member.worktree,
+        member_pool_claimed: member.poolClaimed,
+    }, now);
     deps.journal.append((0, journal_1.unitEvent)('spawned', unit(batchId), {
         pid,
         tier,
@@ -632,6 +950,7 @@ function spawnMember(deps, dispatch, state, slot, batchId, now, result) {
         issue: memberIssue,
         ...(0, dispatch_1.journalCmdModelFields)(spawnSpec),
         log: logFile,
+        worktree: member.worktree,
         detail: `member ${batch.executing_member}/${batch.members.length}`,
     }), now);
     result.spawned.push(unit(batchId));
@@ -703,6 +1022,45 @@ function claimAndSetup(deps, config, dispatch, batchId, now, result) {
         },
     });
     deps.journal.append((0, journal_1.unitEvent)('batch-setup-done', unit(batchId), { detail: setup.worktree }), now);
+    // #677: prepare member 1's OWN worktree before claiming the spawn — real
+    // git/network work, so OUTSIDE the store lock (the same contract
+    // `runBatchSetup` just followed). All-or-nothing: a failed prep posts the
+    // blocked milestone and releases the slot rather than spawning into a
+    // worktree that does not exist (every member would fail Step 0).
+    const firstIssue = batch.members[0];
+    // Shared abort tail of every setup-stage failure (#677 review): post the
+    // blocked milestone when a run id exists, journal, report, release.
+    const abortSetup = (kvReason, detail) => {
+        if (batch.anchor !== null && setup.runId !== null) {
+            poster(batch.anchor, setup.runId, {
+                phase: 'batch-setup',
+                status: 'blocked',
+                kv: { reason: kvReason },
+            });
+        }
+        else {
+            journalEvent(deps, 'milestone-post-failed', unit(batchId), {
+                detail: `batch-setup blocked (${kvReason}) — no run id to post to yet`,
+            });
+        }
+        deps.journal.append((0, journal_1.unitEvent)('batch-setup-failed', unit(batchId), { detail }), now);
+        result.failed.push(unit(batchId));
+        deps.store.withLock((s) => ({ state: releaseSlot(s, batchId, now), result: undefined }));
+    };
+    if (firstIssue === undefined) {
+        abortSetup('no-member', 'claimAndSetup: batch has no members');
+        return;
+    }
+    const freshForPrep = (0, state_1.findBatch)(deps.store.load(), batchId);
+    const memberPrep = prepareMemberWorktree(deps, 
+    // The setup patch (branch/worktree/run_id) lands under the lock BELOW —
+    // prep needs the integration branch, so overlay `setup.branch` on the
+    // fresh state rather than waiting for the patch.
+    { ...(freshForPrep ?? batch), branch: setup.branch }, 1, firstIssue, now);
+    if (!memberPrep.ok) {
+        abortSetup(`member-worktree-prep-failed:${memberPrep.reason}`, `member worktree prep failed: ${memberPrep.reason} (member 1 #${firstIssue}, branch ${memberBranchFor(batchId, 1, firstIssue)})`);
+        return;
+    }
     deps.store.withLock((s) => {
         const b = (0, state_1.findBatch)(s, batchId);
         if (!b || b.status !== 'ready') {
@@ -727,7 +1085,7 @@ function claimAndSetup(deps, config, dispatch, batchId, now, result) {
         next = (0, state_1.transitionBatch)(next, batchId, 'executing', { executing_member: 1 }, now);
         const slot = slotFor(next, batchId);
         if (slot)
-            next = spawnMember(deps, dispatch, next, slot, batchId, now, result);
+            next = spawnMember(deps, dispatch, next, slot, batchId, now, result, memberPrep);
         return { state: next, result: undefined };
     });
 }
@@ -753,7 +1111,65 @@ function claimAndSpawn(deps, config, batchId, phase, now, spawn) {
     });
 }
 function spawnMemberContinuation(deps, config, dispatch, batchId, now, result) {
-    claimAndSpawn(deps, config, batchId, 'member', now, (state, slot) => spawnMember(deps, dispatch, state, slot, batchId, now, result));
+    // #677: make sure the current member's worktree exists before claiming a
+    // slot for the redispatch — git exec work, so OUTSIDE the store lock (the
+    // contract `prepareMemberWorktree` documents). The wedge arm of
+    // `runBatchTick` calls this EVERY tick while the batch is `executing`
+    // with no slot, so the cheap gates run first:
+    // - capacity: prep before the free-capacity check would do pool/git/npm
+    //   work (and journal) per tick against a full scheduler — the #610/#630/
+    //   #632 per-tick emission trap. `claimAndSpawn` re-checks under the lock;
+    //   this pre-check only avoids wasted prep, it is not the gate.
+    // - identity: persisted member fields are reused only when they belong to
+    //   the CURRENT member (they can be stale after a failed teardown that
+    //   kept them, or a crash between an eviction and its teardown) and the
+    //   tree still EXISTS on disk (state-first, because a pool-claimed path
+    //   is not re-derivable from batchId+index+issue).
+    const state = deps.store.load();
+    const batch = (0, state_1.findBatch)(state, batchId);
+    if (!batch || batch.status !== 'executing' || batch.worktree === null)
+        return;
+    const memberIssue = batch.members[batch.executing_member - 1];
+    if (memberIssue === undefined)
+        return;
+    if ((0, scheduler_1.freeCapacity)(state, config) === 0)
+        return;
+    const expectedBranch = memberBranchFor(batchId, batch.executing_member, memberIssue);
+    const fsExists = deps.fsExists ?? ((p) => fs.existsSync(p));
+    const reusable = batch.member_worktree !== null &&
+        batch.member_branch === expectedBranch &&
+        fsExists(batch.member_worktree);
+    let member;
+    if (reusable) {
+        member = {
+            branch: batch.member_branch,
+            worktree: batch.member_worktree,
+            poolClaimed: batch.member_pool_claimed,
+        };
+    }
+    else {
+        if (batch.member_worktree !== null) {
+            // Stale context for a DIFFERENT member (or a vanished tree): journal
+            // it before overwriting — the disposition of that tree is the
+            // operator's to inspect if it was real.
+            journalEvent(deps, 'stale-member-worktree', unit(batchId), {
+                issue: memberIssue,
+                detail: `persisted ${batch.member_branch ?? '?'} @ ${batch.member_worktree} does not match expected ${expectedBranch} (or tree gone) — preparing fresh`,
+            });
+        }
+        const prep = prepareMemberWorktree(deps, batch, batch.executing_member, memberIssue, now);
+        if (!prep.ok) {
+            journalEvent(deps, 'unit-failed', unit(batchId), {
+                issue: memberIssue,
+                reason: 'member-worktree-prep-failed',
+                detail: `member worktree prep failed on continuation: ${prep.reason} (branch ${expectedBranch})`,
+            });
+            result.failed.push(unit(batchId));
+            return;
+        }
+        member = prep;
+    }
+    claimAndSpawn(deps, config, batchId, 'member', now, (nextState, slot) => spawnMember(deps, dispatch, nextState, slot, batchId, now, result, member));
 }
 /**
  * Tail/report/fix dispatches (this function, `spawnReportAgent`,
@@ -1124,6 +1540,12 @@ function evictMemberAndContinue(deps, config, dispatch, batchId, batch, memberIs
         result.failed.push(unit(batchId));
         return;
     }
+    // #677: the evicted member's commits never landed (eviction is the
+    // pre-landing rail), so there is nothing to revert on the integration
+    // branch — but its worktree/branch must go, or the next tick's prep for
+    // the NEXT member collides with a stale tree. `teardownBatch` already
+    // handled it on the dissolved path (the fields are cleared there).
+    teardownMemberWorktree(deps, batchId, now, false);
     advanceMemberOrValidate(deps, config, dispatch, batchId, batch.members.length, batch.executing_member, memberIssue, now, result);
 }
 /**
@@ -1160,7 +1582,11 @@ function evictMemberAndContinue(deps, config, dispatch, batchId, batch, memberIs
 function runIncrementalGate(deps, config, dispatch, batchId, batch, memberIssue, now, result) {
     if (batch.worktree === null || !deps.runCapability)
         return false;
-    const worktree = batch.worktree;
+    // #677: the gate judges the member's OWN work — pre-landing, its diff
+    // exists only in the member worktree/branch. The shared batch worktree is
+    // the fallback for a batch dispatched before member worktrees existed (its
+    // members' commits landed directly on the integration branch).
+    const worktree = batch.member_worktree ?? batch.worktree;
     const runCapability = deps.runCapability;
     const gateResults = ['typecheck.run', 'test.focused'].map((id) => ({
         id,
@@ -1180,9 +1606,9 @@ function runIncrementalGate(deps, config, dispatch, batchId, batch, memberIssue,
     // extend to an id nobody wrote down.
     //
     // `warmColdBatchWorktree` in this same file already draws exactly this
-    // distinction for `worktree.prepare`, and `slot-cycle`'s own Step 4/5 fall
-    // back to reasoning on `capability-unavailable`. This was the one place that
-    // treated it as fatal.
+    // distinction for `worktree.prepare`, and the member workflow (member-cycle,
+    // #677) runs its own relevance-scoped tests rather than treating a broken
+    // capability as fatal. This was the one place that treated it as fatal.
     //
     // Skipping costs EARLY detection, not correctness: the aggregate `test.full`
     // gate still runs before ship, CI still runs on the batch PR, and #562's
@@ -1281,14 +1707,19 @@ function runIncrementalGate(deps, config, dispatch, batchId, batch, memberIssue,
             detail: withExcerpt(`cap run ${inconclusive.id} ${describeInconclusive(inconclusive)} after member review done`, excerpt),
         });
         deps.store.withLock((s) => ({ state: releaseSlot(s, batchId, now), result: undefined }));
-        const stateNow = deps.store.load();
-        const rDeps = recoveryDeps(deps, config, batch, now);
-        const blocked = (0, recovery_1.blockBatch)(stateNow, batchId, { reason, milestonePhase: 'batch-review' }, rDeps);
-        deps.store.withLock((s) => ({
-            state: applyBatchAndIssues(s, blocked.state, batchId, []),
-            result: undefined,
-        }));
-        result.failed.push(unit(batchId));
+        // #677: F.11's block semantics are "the member's commit stays on the
+        // branch, nothing requeued/reverted" — under member worktrees that is
+        // true only if the member LANDS before the batch blocks. The block means
+        // the gate could not reach a verdict, not that the work is bad, so the
+        // verified member joins the integration branch and is there for an
+        // operator (or the #686 out-of-band reconcile) to act on. A landing
+        // failure blocks the batch with its own reason — same operator outcome.
+        const landed = landMemberBranch(deps, batchId, now);
+        if (!landed.ok) {
+            blockLandingFailure(deps, config, batch, landed.reason, now, result);
+            return true;
+        }
+        blockBatchForOperator(deps, config, batchId, { reason, milestonePhase: 'batch-review' }, now, result);
         return true;
     }
     return false;
@@ -1304,6 +1735,16 @@ function runIncrementalGate(deps, config, dispatch, batchId, batch, memberIssue,
  * this is safe to call whether or not the caller already released it.
  */
 function completeMemberGate(deps, config, dispatch, batchId, batch, memberIssue, now, result) {
+    // #677 (§J.3): land the member's verified work on the integration branch
+    // BEFORE anything reads it — the range recompute below runs `git log` on
+    // the batch branch, which only sees the member's commits once landed. The
+    // exec calls run OUTSIDE the lock (same invariant as the range recompute's
+    // own comment below).
+    const landed = landMemberBranch(deps, batchId, now);
+    if (!landed.ok) {
+        blockLandingFailure(deps, config, batch, landed.reason, now, result);
+        return;
+    }
     // The commit-range recompute (`git log`) is a blocking subprocess call — it
     // must run OUTSIDE the lock, like every other exec in this module; the
     // result then lands as a pure data patch under the lock (Convention review:
@@ -1324,6 +1765,10 @@ function completeMemberGate(deps, config, dispatch, batchId, batch, memberIssue,
         return { state: n, result: undefined };
     });
     result.completed.push(unit(batchId));
+    // #677: the member's tree is done serving — landed, ranges recomputed.
+    // Teardown before the advance so the next member's prep cannot collide
+    // with this tree's cleanup.
+    teardownMemberWorktree(deps, batchId, now, true);
     advanceMemberOrValidate(deps, config, dispatch, batchId, batch.members.length, batch.executing_member, memberIssue, now, result);
 }
 /**
@@ -1360,6 +1805,12 @@ function resumeBlockedGate(deps, config, dispatch, batchId, now) {
     if (!batch)
         throw new types_1.SchedNotFoundError(`Batch not found: ${batchId}`);
     if (batch.status !== 'blocked' || !batch.blocked_reason?.startsWith('gate-inconclusive:')) {
+        // #677 review: the landing-failure blocks have no resume verb (same as
+        // `suite-unreadable`) — name the actual reason and the operator path
+        // instead of a bare illegal-transition error that reads like a bug.
+        if (batch.status === 'blocked') {
+            throw new types_1.SchedNotFoundError(`Batch ${batchId} is blocked on '${batch.blocked_reason ?? '?'}', which has no gate recheck: inspect the batch worktree/state named in its journal, then \`sched abandon --batch ${batchId}\` if it is a dead end`);
+        }
         throw new types_1.IllegalTransitionError('batch', batch.status, 'executing');
     }
     const capabilityId = batch.blocked_reason.slice('gate-inconclusive:'.length);
@@ -1367,7 +1818,13 @@ function resumeBlockedGate(deps, config, dispatch, batchId, now) {
     if (batch.worktree === null || !deps.runCapability || memberIssue === undefined) {
         throw new types_1.SchedNotFoundError(`Batch ${batchId} has no worktree/current member/gate hook to recheck`);
     }
-    const recheck = deps.runCapability(batch.worktree, capabilityId);
+    const recheck = deps.runCapability(
+    // #677: recheck the member's OWN tree — pre-landing, the member's diff
+    // exists only in its worktree; a batch-worktree recheck would test a
+    // tree missing the change and trivially pass it. The fallback preserves
+    // the pre-#677 behavior for a batch blocked before member worktrees
+    // existed (its member's commits were already on the integration branch).
+    batch.member_worktree ?? batch.worktree, capabilityId);
     const result = emptyResult();
     const excerpt = gateDetailExcerpt(recheck.outputTail, recheck.reason);
     // #681: a recheck can classify what the batch blocked on as a TIMEOUT —
@@ -2048,6 +2505,232 @@ function reconcilePrWatch(deps, now, result) {
         }
     }
 }
+// --- #686: stale-BLOCKED batch reconciliation (ground truth beats the ledger) ---
+/**
+ * #686: how long after a batch `blocked` its merge evidence may still arrive
+ * and reconcile it — measured from `updated_at`, which is when the batch
+ * became blocked (dedup writes don't touch it). Same window semantics as the
+ * per-issue path's `STALE_RECONCILE_WINDOW_MS` (engine.ts): past it, an
+ * abandoned batch is left as-is rather than polled (one `gh pr view` plus git
+ * probes) forever. A local constant rather than an import: engine.ts already
+ * imports THIS module, so the arrow points one way only.
+ */
+const STALE_BLOCKED_RECONCILE_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * The forward rail a surviving member walks to `done` on a stale-blocked
+ * reconcile — every step an ALREADY-LEGAL `ISSUE_BASE_TRANSITIONS` edge, so
+ * the walk invents no new state-machine surface (AC3: a member whose commits
+ * are in the base must not stay `in-work`, and `in-work → shipped-in-batch`
+ * is not an edge — but `in-work → committed → validated → shipped-in-batch →
+ * done` is). Members whose current status has no entry here (`waiting`, i.e.
+ * never dispatched) are not walked: no recorded work, nothing shipped.
+ */
+const MEMBER_RECONCILE_CHAIN = {
+    'in-work': 'committed',
+    committed: 'validated',
+    validated: 'shipped-in-batch',
+    'shipped-in-batch': 'done',
+};
+/**
+ * Whether every SURVIVING member of `batch` was actually dispatched — i.e. no
+ * surviving member is still sitting in a pre-dispatch status (`queued`,
+ * `classified`, `batched`, `waiting`). Surviving = a `batch.members` issue
+ * that is still a slot-mode entry, not evicted (its work was reverted and it
+ * requeued full-cycle), and not already preserved (shipped/terminal through
+ * another rail).
+ *
+ * This is the safety rail behind AC1: a member that never ran has NO work on
+ * the branch, so a batch carrying one is NOT reconcilable to shipped —
+ * reconciling it would call an issue `done` that shipped nothing, minting the
+ * exact ledger/ground-truth drift (#675-class) this issue exists to cure,
+ * just with the signs flipped. A dispatched member, by contrast, put its work
+ * ON the branch (even when the gate blocked before its range was recorded —
+ * the b-20260909-01 shape, where the only surviving member sat `in-work`),
+ * and the branch is exactly what the merge evidence below covers.
+ */
+function everySurvivingMemberDispatched(state, batch) {
+    const evicted = new Set(batch.evictions.map((e) => e.issue));
+    for (const issue of batch.members) {
+        const entry = (0, state_1.findEntry)(state, issue);
+        if (!entry)
+            continue;
+        if (entry.mode !== 'slot' || evicted.has(issue) || (0, state_1.isPreservedMember)(entry))
+            continue;
+        // Pre-dispatch statuses: queued/classified/batched/waiting. `in-work` is
+        // stamped at SPAWN (`spawnMember`), `committed`/`validated` at verified
+        // completion — everything the entry can reach afterwards means the
+        // member was dispatched and its work is on the branch.
+        if (!DISPATCHED_MEMBER_STATUSES.has(entry.status))
+            return false;
+    }
+    return true;
+}
+/** Slot-line statuses that prove a member was actually dispatched (see above). */
+const DISPATCHED_MEMBER_STATUSES = new Set([
+    'in-work',
+    'committed',
+    'validated',
+]);
+/**
+ * Whether the batch branch has landed in the base — the b-20260909-01 shape
+ * of merge evidence ("The batch branch is in `main` at c277ff59b", `pr=None`):
+ * the branch was merged out of band, so its commits are IN the base even
+ * though the batch never shipped a PR of its own. Two probes against the
+ * remote-tracking ref (refreshed best-effort first — a merge that landed on
+ * the remote is invisible to `rev-list` until fetched; fetch failure leaves
+ * the stale ref, the same degradation the per-issue path tolerates):
+ *
+ * - `git rev-list --count origin/<base>..<branch>` is 0 — nothing of the
+ *   branch is missing from the base, i.e. every member commit on it is an
+ *   ancestor of the base (AC1's wording);
+ * - the branch tip is NOT the base tip — the branch actually carried work.
+ *   A batch branch starts AT the base tip, so a branch that never received a
+ *   member commit still probes 0 on the range; requiring a different tip is
+ *   what separates "shipped" from "vacuously empty".
+ */
+function branchMergedIntoBase(deps, batch) {
+    if (batch.worktree === null || batch.branch === null)
+        return false;
+    // CWE-88 (the repo's own trap index): both refs are interpolated into git
+    // argv below. They are state values written by batch-setup, not remote
+    // input, but `runBatchSetup` refuses to CREATE anything this pattern would
+    // reject (SAFE_REF_RE at the branch-creation site) — hold the reader to
+    // the same bar instead of trusting upstream state shape.
+    if (!attribution_1.SAFE_REF_RE.test(batch.branch) || !attribution_1.SAFE_REF_RE.test(batch.base_branch))
+        return false;
+    const base = `origin/${batch.base_branch}`;
+    deps.exec('git', ['fetch', 'origin', batch.base_branch], deps.repoDir);
+    const ahead = deps.exec('git', ['rev-list', '--count', `${base}..${batch.branch}`], deps.repoDir);
+    if ((ahead ?? '').trim() !== '0')
+        return false;
+    const branchTip = deps.exec('git', ['rev-parse', batch.branch], deps.repoDir);
+    const baseTip = deps.exec('git', ['rev-parse', base], deps.repoDir);
+    return branchTip !== null && baseTip !== null && branchTip.trim() !== '' && branchTip !== baseTip;
+}
+/**
+ * #686: reconcile a `blocked` batch whose work demonstrably shipped anyway.
+ * `reconcilePrWatch` above only watches `awaiting-merge` batches, and
+ * `resumeBlockedGate` only re-runs the gate — so a batch blocked on a stale
+ * verdict (the concrete case: `gate-inconclusive:test.focused`, itself often
+ * a #690-declined gate TIMEOUT) whose PR merged out of band — or whose every
+ * member commit is already in the base — stayed blocked FOREVER: no report,
+ * no teardown, an operator-visible `blocked` row, and members stuck
+ * `in-work`. Sibling of the per-issue `reconcileStaleFailedParks`
+ * (engine.ts) under the same principle: ground truth beats the ledger, for
+ * ANY stale verdict — the blocked_reason is deliberately not examined.
+ *
+ * Evidence (either suffices, cheapest first): the batch PR is MERGED with a
+ * real timestamp (a merged batch PR contains the whole batch branch), or the
+ * batch branch has fully landed in the base branch. A survivability guard
+ * applies to BOTH paths (see `everySurvivingMemberDispatched`) — a batch with
+ * a surviving member that was never dispatched is not reconcilable.
+ *
+ * On reconcile the batch joins the SAME rail a normally-merged batch takes:
+ * `blocked → merged → deployed` (the `blocked → merged` edge exists for
+ * exactly this caller), surviving members walked to `done` along legal
+ * edges, and — when `batch.pr` is set — the ordinary `deployed` machinery
+ * dispatches the report agent next tick, with teardown after `batch-report
+ * done`. With `pr === null` no report agent can be prompted (it names the
+ * PR), so the same lock continues `deployed → reported → done` and the
+ * worktree is torn down here instead; the journal line says why no report
+ * agent was dispatched rather than leaving the gap silent.
+ *
+ * Bounded by construction: only `blocked` batches within the window are
+ * examined, the PR check is one `gh` call, git runs only when PR evidence
+ * didn't already reconcile, and a reconciled batch leaves `blocked` — the
+ * one journal line fires on the one-way transition, never per-tick (the
+ * #632 lesson: no journal inside a loop that doesn't terminate the unit).
+ */
+function reconcileStaleBlockedBatches(deps, now, result) {
+    const state = deps.store.load();
+    const nowMs = now.getTime();
+    for (const batch of state.batches) {
+        if (batch.status !== 'blocked')
+            continue;
+        if (nowMs - Date.parse(batch.updated_at) >= STALE_BLOCKED_RECONCILE_WINDOW_MS)
+            continue;
+        if (!everySurvivingMemberDispatched(state, batch))
+            continue;
+        let evidence = null;
+        if (batch.pr !== null) {
+            const truth = deps.groundTruth.prState(batch.pr);
+            if (truth !== undefined && truth.state === 'MERGED' && truth.mergedAt !== null) {
+                evidence = { kind: 'pr-merged', pr: batch.pr, mergedAt: truth.mergedAt };
+            }
+        }
+        if (evidence === null && branchMergedIntoBase(deps, batch)) {
+            evidence = { kind: 'commits-in-base' };
+        }
+        if (evidence === null)
+            continue;
+        const blockedReason = batch.blocked_reason ?? 'blocked';
+        const failedAt = batch.updated_at;
+        let reconciled = false;
+        let unwalkable = [];
+        deps.store.withLock((s) => {
+            const b = (0, state_1.findBatch)(s, batch.id);
+            // Re-check under the lock: `sched resume --batch` (a passing recheck)
+            // or `sched abandon` may have moved the batch out from under the
+            // snapshot this pass started from.
+            if (!b || b.status !== 'blocked')
+                return { state: s, result: undefined };
+            let n = (0, state_1.transitionBatch)(s, batch.id, 'merged', {}, now);
+            n = (0, state_1.transitionBatch)(n, batch.id, 'deployed', {}, now);
+            unwalkable = [];
+            for (const issue of b.members) {
+                let entry = (0, state_1.findEntry)(n, issue);
+                if (!entry || (0, state_1.isPreservedMember)(entry))
+                    continue;
+                let guard = 0;
+                while (entry !== undefined) {
+                    const nextStatus = MEMBER_RECONCILE_CHAIN[entry.status];
+                    if (nextStatus === undefined || guard++ > 8)
+                        break; // chain is 4 long; never loop forever on a bad table
+                    try {
+                        n = (0, state_1.transitionIssue)(n, issue, nextStatus, {}, now);
+                    }
+                    catch {
+                        // Not reachable along legal edges from here — name it in the
+                        // journal rather than forcing an illegal transition.
+                        unwalkable.push(issue);
+                        break;
+                    }
+                    entry = (0, state_1.findEntry)(n, issue);
+                }
+            }
+            if (b.pr === null) {
+                // No PR → no report agent is possible (its prompt names the PR).
+                // Finish the terminal rail and let teardown run below.
+                n = (0, state_1.transitionBatch)(n, batch.id, 'reported', {}, now);
+                n = (0, state_1.transitionBatch)(n, batch.id, 'done', {}, now);
+            }
+            reconciled = true;
+            return { state: n, result: undefined };
+        });
+        if (!reconciled)
+            continue;
+        journalEvent(deps, 'stale-failure-reconciled', unit(batch.id), {
+            pr: batch.pr ?? undefined,
+            reason: blockedReason,
+            failedAt,
+            evidence: evidence.kind,
+            ...(evidence.kind === 'pr-merged' ? { mergedAt: evidence.mergedAt } : {}),
+            detail: (evidence.kind === 'pr-merged'
+                ? `PR #${evidence.pr} is MERGED — ledger reconciled blocked (${blockedReason}) to the merged rail (blocked at ${failedAt}); report and teardown will now dispatch`
+                : `every member commit is an ancestor of ${batch.base_branch} — ledger reconciled blocked (${blockedReason}) to shipped (blocked at ${failedAt})`) +
+                (batch.pr === null
+                    ? ' — no PR of its own, so no report agent can be prompted; teardown dispatched inline'
+                    : '') +
+                (unwalkable.length > 0
+                    ? `; members NOT walked (no legal edge): ${unwalkable.join(',')}`
+                    : ''),
+        });
+        result.mergeAccepted.push(unit(batch.id));
+        if (batch.pr === null) {
+            teardownBatch(deps, batch.id);
+        }
+    }
+}
 /**
  * Remove the batch's shared worktree — called both on the happy path
  * (`reconcileReportSlot`, after `batch-report done`) and on every dissolve
@@ -2056,6 +2739,17 @@ function reconcilePrWatch(deps, now, result) {
  * left on disk forever, since nothing else ever calls this for it.
  */
 function teardownBatch(deps, batchId) {
+    // #677: the current member's worktree goes first — it is batch-owned
+    // state on the same teardown path as the shared tree, and a blocked or
+    // dissolved batch must not leak a member tree (its branch/fields are
+    // cleared by the helper; a gate-inconclusive BLOCK that intends to resume
+    // never reaches this function). The batch is terminal here, so the
+    // ranges-recorded membership of the last current member is a safe landed
+    // signal (a range exists only for a member whose verified work landed).
+    const terminal = (0, state_1.findBatch)(deps.store.load(), batchId);
+    const lastMemberLanded = terminal?.ranges.some((r) => r.issue === terminal.members[terminal.executing_member - 1]) ===
+        true;
+    teardownMemberWorktree(deps, batchId, deps.now(), lastMemberLanded);
     const state = deps.store.load();
     const batch = (0, state_1.findBatch)(state, batchId);
     if (!batch || batch.worktree === null)
@@ -2188,8 +2882,11 @@ function runBatchTick(deps, config, dispatch) {
             // A prior spawn threw, or `claimAndSpawn` found zero free capacity —
             // either way the batch is stuck mid-member with no slot and nothing
             // else will ever retry it (Conformance review AC5 caveat; Supportability
-            // review #12). Retrying every tick is safe: `claimAndSpawn` itself is
-            // the capacity gate, so this is a no-op until a slot actually frees up.
+            // review #12). Retrying every tick is cheap-by-contract (#677 review):
+            // `spawnMemberContinuation` runs the free-capacity and member-identity
+            // pre-checks BEFORE any pool/git work, so a full scheduler (or stale
+            // member context) exits here without exec'ing, and `claimAndSpawn`
+            // remains the authoritative capacity gate.
             spawnMemberContinuation(deps, config, dispatch, batch.id, now, result);
         }
         else if (batch.status === 'reviewing' || batch.status === 'shipping') {
@@ -2219,6 +2916,7 @@ function runBatchTick(deps, config, dispatch) {
         }
     }
     reconcilePrWatch(deps, now, result);
+    reconcileStaleBlockedBatches(deps, now, result);
     return result;
 }
 //# sourceMappingURL=batch-dispatch.js.map