brainclaw 1.20.1 → 1.20.3

package/dist/commands/harvest.js

@@ -27,6 +27,7 @@ import { closeIdeationLoopFromLaneResult } from '../core/ideation-loop-close.js'
 import { dispatchReviewLoopTurn, turnOwnedReviewEnabled } from '../core/review-loop-turn-dispatch.js';
 import { reconcileTurn } from '../core/loops/reconcile-turn.js';
 import { findReservationByAssignmentId } from '../core/loops/attempt-reservation.js';
+import { getLoop } from '../core/loops/store.js';
 import { readCompletionSignals } from '../core/runtime-signals.js';
 import { reconcileClaimConformity } from '../core/claim-conformity.js';
 import { toWarningDetail } from '../core/warnings.js';
@@ -70,8 +71,8 @@ function turnOwnedLaneEvidence(lane, cwd) {
         return undefined; // reservation but NO turn-keyed evidence → legacy finalization
     return { reservation, nonce };
 }
-function reconcileTurnOwnedReviewLane(lane, cwd) {
-    const ev = turnOwnedLaneEvidence(lane, cwd);
+function reconcileTurnOwnedReviewLane(lane, cwd, evidence) {
+    const ev = evidence ?? turnOwnedLaneEvidence(lane, cwd);
     if (!ev)
         return undefined; // legacy lane OR no turn-keyed evidence — caller runs the legacy path
     const { reservation, nonce } = ev;
@@ -99,6 +100,62 @@ function reconcileToReviewLoopResult(reservation, rr, lane) {
         loop_status: rr.loop_status,
     };
 }
+/**
+ * pln#644 — the warn-only branches must stay QUIET for a lane whose turn is no
+ * longer the live one: a prior round's LANE-RESULT re-scanned by `harvest --all`
+ * after the loop advanced (superseded) or closed (terminal) is a healthy flow,
+ * not a stall. Warning there would train operators to ignore the one warning
+ * that matters. Only an OPEN loop whose slot still points at THIS turn is
+ * actually awaiting convergence.
+ */
+function loopTurnAwaitsConvergence(reservation, cwd) {
+    const loop = getLoop(reservation.loop_id, cwd);
+    if (!loop)
+        return false;
+    // Only a live, advancing loop is awaiting convergence (PR #171 review P2-1).
+    // 'blocked' (iteration cap) is in reconcileTurn's LOOP_TERMINAL set, and a
+    // 'paused' loop refuses advancement until resumed — advising `--integrate`
+    // on either would be a false alarm. 'open' is the only non-terminal,
+    // advancing status (LoopStatus non-terminal = 'open' | 'paused').
+    if (loop.status !== 'open')
+        return false;
+    const slot = loop.slots.find((s) => s.slot_id === reservation.slot_id);
+    if (!slot)
+        return false;
+    // Mirror reconcileTurn's superseded guard exactly: an UNSET current_turn_id is
+    // "not superseded" (a dispatch whose turn() never rebound the slot pointer is
+    // still this turn's attempt), only a pointer to a DIFFERENT turn means the
+    // slot moved on and the stale lane deserves silence, not a warning.
+    return slot.current_turn_id === undefined || slot.current_turn_id === reservation.turn_id;
+}
+/**
+ * pln#644 — the loud half of "converge or fail loudly". The message names the
+ * exact command that finalizes the turn (`harvest --integrate`) AND the manual
+ * loop-drive alternative, because the two lived stalls (2026-08-02/03) were
+ * both resolved manually once the coordinator finally noticed the open turn.
+ */
+function reviewTurnNotConvergedWarning(lane, reservation, why) {
+    return toWarningDetail({
+        code: 'review_turn_not_converged',
+        message: `Turn-owned review lane ${lane.assignment_id} harvested report-only: loop ${reservation.loop_id} ` +
+            `turn ${reservation.turn_id} is NOT converged — ${why}. ` +
+            `Run \`brainclaw harvest --integrate ${lane.assignment_id}\` to finalize it ` +
+            `(records the verdict; on request_changes it also drives the fix cycle), ` +
+            `or drive the loop manually (bclaw_loop add_artifact + complete_turn).`,
+        data: {
+            assignment_id: lane.assignment_id,
+            loop_id: reservation.loop_id,
+            turn_id: reservation.turn_id,
+            review_verdict: lane.review_verdict ?? null,
+            reason: why,
+        },
+        next_actions: [{
+                tool: 'bclaw_loop',
+                args: { intent: 'get', loop_id: reservation.loop_id },
+                when: 'inspect the open turn before converging it via --integrate or a manual complete_turn',
+            }],
+    });
+}
 /**
  * Auto-detect all worktree directories under the brainclaw-managed base dir.
  * Returns subdirectories that exist on disk (may or may not have an inbox).
@@ -358,20 +415,54 @@ export function harvestLaneResults(options = {}) {
         // PR2: cycleOnRequestChanges=false — the report path only closes on approve;
         // it must NOT advance a request_changes cycle it cannot follow through on
         // (no re-dispatch, no claim retention). `harvest --integrate` owns the cycle.
+        // Hoisted for the catch below (PR #171 review P2-2): if turn-owned evidence was
+        // found before a throw, the swallowed failure must still surface as a warning.
+        let turnEvidenceForCatch;
         try {
             const laneAssignment = loadAssignment(lane.assignment_id, cwd);
             if (laneAssignment) {
-                // pln#630 PR3a — a TURN-OWNED review lane (reservation + turn-keyed evidence) is finalized
-                // ONLY by reconcileTurn on the `--integrate` path (which owns claim/worktree teardown). The
-                // report path must NOT pre-empt it with a legacy close (which would terminalize the loop and
-                // strand the turn-owned run). So skip the legacy review-close for such a lane. Kill-switch
-                // (=0), a legacy lane (no reservation), OR a reservation WITHOUT evidence (review Finding 1:
-                // an inbox_only/non-ack-wrapped dispatch that never wrote a sentinel) → false → the lane
-                // takes the unchanged legacy close so it still converges. Ideation stays legacy (review-only).
-                const laneIsTurnOwned = turnOwnedReviewEnabled() && !!turnOwnedLaneEvidence(lane, cwd);
-                if (!laneIsTurnOwned) {
+                // pln#644 (supersedes the pln#630 PR3a report-path deferral) — a TURN-OWNED review lane
+                // used to be skipped ENTIRELY here (finalization deferred to `--integrate`) with no
+                // signal at all: the operator ran `brainclaw harvest <asgn>`, read "1 harvested", and
+                // the loop turn silently stayed open. That stalled two live loops on 2026-08-02/03
+                // (lop_626271ee10ad09d8, lop_4d869568bd99ddc0), both converged by hand. The report
+                // path now converges what it safely CAN and says what it can't:
+                //   - APPROVE → reconcileTurn right here — the same exactly-once idempotent finalizer
+                //     `--integrate` uses (mirrors the pln#638 1c ideation closer firing on this path).
+                //     Read-strict is NOT weakened: evidence still comes from the lane keys or the
+                //     wrapper sentinel, and a mismatch still refuses (loudly, below).
+                //   - REQUEST_CHANGES / no verdict / refused evidence → the loop is left alone (the
+                //     report path still cannot follow through on a fix cycle: no re-dispatch, no
+                //     commit-on-behalf — `--integrate` owns that) but a `review_turn_not_converged`
+                //     WARNING now names the open turn and the recovery. Never a silent stall.
+                // Kill-switch (=0), a legacy lane (no reservation), OR a reservation WITHOUT evidence
+                // (review Finding 1: an inbox_only/non-ack-wrapped dispatch that never wrote a
+                // sentinel) → the lane takes the unchanged legacy close so it still converges.
+                // Ideation stays legacy (review-only).
+                const laneTurnEvidence = turnOwnedReviewEnabled() ? turnOwnedLaneEvidence(lane, cwd) : undefined;
+                turnEvidenceForCatch = laneTurnEvidence;
+                if (!laneTurnEvidence) {
                     closeReviewLoopFromLaneResult(laneAssignment, lane, agent, cwd, { cycleOnRequestChanges: false });
                 }
+                else if (lane.review_verdict === 'approve') {
+                    const rr = reconcileTurnOwnedReviewLane(lane, cwd, laneTurnEvidence);
+                    // Reason-based quietness (PR #171 review P2-1 refinement): a terminal loop
+                    // returns reconciled:true (idempotent no-op) and a superseded turn is the one
+                    // healthy decline (`harvest --all` over a prior round's lane) — everything
+                    // else (refused evidence, deferred lock, loop/slot not found, contradiction,
+                    // paused complete_turn refusal) is a live approve that did NOT land and must
+                    // say so. No getLoop re-read here: the decline reason already discriminates,
+                    // and the loop store itself may be the failing component.
+                    if (rr && !rr.result.reconciled && !/superseded/.test(rr.result.reason ?? '')) {
+                        result.warnings.push(reviewTurnNotConvergedWarning(lane, laneTurnEvidence.reservation, `reconcileTurn refused: ${rr.result.reason ?? 'no reason given'}`));
+                    }
+                }
+                else if (loopTurnAwaitsConvergence(laneTurnEvidence.reservation, cwd)) {
+                    const why = lane.review_verdict === 'request_changes'
+                        ? 'a request_changes fix cycle needs re-dispatch + commit-on-behalf, which the report path does not do'
+                        : 'the lane carries no review_verdict, so nothing proves the reviewer reached a verdict';
+                    result.warnings.push(reviewTurnNotConvergedWarning(lane, laneTurnEvidence.reservation, why));
+                }
                 // pln#521 P2-bis — the ideation analog: a critic lane records its critique +
                 // advances the ideation loop. Returns undefined for non-ideate scopes (no-op here).
                 ideationLoop = closeIdeationLoopFromLaneResult(laneAssignment, lane, agent, cwd);
@@ -393,7 +484,22 @@ export function harvestLaneResults(options = {}) {
                 }
             }
         }
-        catch { /* never block harvest on loop-close */ }
+        catch (err) {
+            // Never block harvest on loop-close — but a swallowed failure must not be
+            // SILENT for a turn-owned lane (PR #171 review P2-2): before this warning,
+            // an unexpected reconcile/store error left the operator with "1 harvested,
+            // 0 error(s)" and an open loop turn — the exact stall pln#644 exists to
+            // kill. Deliberately no liveness/superseded re-check here: that would
+            // re-read the loop store, which may be the very component that just threw
+            // (getLoop propagates parse errors). A rare over-warning on a broken store
+            // beats a silent stall on a live turn.
+            if (turnEvidenceForCatch) {
+                try {
+                    result.warnings.push(reviewTurnNotConvergedWarning(lane, turnEvidenceForCatch.reservation, `loop-close failed unexpectedly: ${err instanceof Error ? err.message : String(err)}`));
+                }
+                catch { /* truly never block harvest */ }
+            }
+        }
         const marker = laneHarvestedMarkerPath(cwd, lane.assignment_id);
         if (fs.existsSync(marker)) {
             result.skipped.push(lane.assignment_id);
@@ -1043,6 +1149,10 @@ export async function runHarvestLane(assignmentId, options = {}) {
             harvested: result.harvested,
             skipped: result.skipped,
             errors: result.errors,
+            // pln#644 — warnings (review_turn_not_converged, claim conformity) were
+            // collected but never emitted on ANY channel; the silent half of the
+            // 2026-08-02/03 review-loop stalls.
+            warnings: result.warnings,
         }, null, 2));
         return;
     }
@@ -1074,6 +1184,12 @@ export async function runHarvestLane(assignmentId, options = {}) {
     for (const err of result.errors) {
         console.error(`  ✗ ${err}`);
     }
-    console.log(`\n✔ Lane harvest complete${dryTag}: ${result.harvested.length} harvested, ${result.skipped.length} skipped, ${result.errors.length} error(s).`);
+    // pln#644 — warnings must reach the operator's eyes: a turn-owned review lane
+    // whose loop turn did not converge used to vanish behind "N harvested".
+    for (const w of result.warnings) {
+        console.log(`  ⚠ ${w.message}`);
+    }
+    const warnTag = result.warnings.length > 0 ? `, ${result.warnings.length} warning(s)` : '';
+    console.log(`\n✔ Lane harvest complete${dryTag}: ${result.harvested.length} harvested, ${result.skipped.length} skipped, ${result.errors.length} error(s)${warnTag}.`);
 }
 //# sourceMappingURL=harvest.js.map

package/dist/core/agentrun-reconciler.js

@@ -40,6 +40,7 @@ import { createRuntimeEvent } from './events.js';
 import { nowISO } from './ids.js';
 import { readHeartbeat, readLogTail, signalExists, latestActivityMs, readCompletionSignals } from './runtime-signals.js';
 import { findReservationByRunId, evidenceMatchesAttempt, launchGrant, revokeLaunchGrant } from './loops/attempt-reservation.js';
+import { reconcileFailedTurn } from './loops/reconcile-turn.js';
 // ── Constants ──────────────────────────────────────────────────────────────
 /**
  * Minimum age before a run is eligible for reconciliation. Below this, the
@@ -250,12 +251,33 @@ function fsActiveWithin(evidence, windowMs) {
  * accumulating for manual cleanup. Best-effort + idempotent: only an active claim
  * is released, and any error is swallowed (GC must never break reconciliation).
  * Inference only fires after the stale window with no life evidence, so this is
- * conservative. (Loop auto-close on failure is a follow-up.)
+ * conservative.
+ *
+ * pln#641 (dec#151 option b): a TURN-OWNED run's claim is business state owned
+ * by its LOOP, and the pln#638 6c effects boundary forbids a transport verdict
+ * from carrying business effects. So a run with a reservation routes through
+ * reconcileFailedTurn — the failure is recorded ON the loop (complete_turn
+ * outcome:'failed') and the release is that convergence's business decision,
+ * in the same lazy pass. When the loop path DECLINES (lock contention, loop
+ * missing, containment), the claim deliberately stays for the next read-path
+ * pass — never a forced fallback release, that would re-open the boundary hole.
+ * Non-turn-owned runs keep the trp#433 cascade unchanged.
  */
-function cascadeReleaseOnFailure(run, actor, cwd, terminalStatus = 'failed') {
+function cascadeReleaseOnFailure(run, actor, cwd, terminalStatus = 'failed', reason) {
     if (!run.claim_id)
         return;
     try {
+        const reservation = findReservationByRunId(run.id, cwd);
+        if (reservation) {
+            reconcileFailedTurn({
+                reservation,
+                run,
+                reason: reason ?? `run reconciled to ${terminalStatus}`,
+                actor,
+                cwd,
+            });
+            return;
+        }
         const claim = loadClaim(run.claim_id, cwd);
         if (claim && claim.status === 'active') {
             releaseClaim(run.claim_id, cwd);
@@ -274,6 +296,46 @@ function cascadeReleaseOnFailure(run, actor, cwd, terminalStatus = 'failed') {
     }
     catch { /* best-effort — never let GC break reconciliation */ }
 }
+/**
+ * pln#641 review P1 — the stranded-failure retry the read path was missing.
+ *
+ * `cascadeReleaseOnFailure` fires exactly once, on the failed/cancelled
+ * TRANSITION. When the business convergence declines in that pass (loop-lock
+ * contention, transient loop read failure) or the process crashes between the
+ * loop's WAL record and the release, the run is already terminal — and every
+ * read path deliberately skips terminal runs, so the "next pass retries"
+ * promise was unreachable: the claim stranded until the 24h stale sweep,
+ * contrary to the same-lazy-pass/non-famine guarantee of dec#151.
+ *
+ * This is that retry, called from the read-path walk ON terminal runs
+ * (entity-operations.ts loadAgentRunsWithReconciliation). Cheap by
+ * construction: in-memory status/claim_id/recency guards first, ONE claim
+ * read only for RECENT failed/cancelled runs that still name a claim; the
+ * cascade re-checks everything and stays idempotent. The recency window keeps
+ * the walk from re-reading a claim file for every historical failure forever —
+ * anything older has long been the stale sweep's business anyway.
+ */
+export const STRANDED_RELEASE_RETRY_WINDOW_MS = 48 * 60 * 60_000;
+export function reconcileStrandedFailureClaimAtRead(run, cwd, options = {}) {
+    if (run.status !== 'failed' && run.status !== 'cancelled')
+        return false;
+    if (!run.claim_id)
+        return false;
+    const now = options.nowMs ?? Date.now();
+    const anchor = Date.parse(run.completed_at ?? run.updated_at ?? run.created_at);
+    if (Number.isFinite(anchor) && now - anchor > STRANDED_RELEASE_RETRY_WINDOW_MS)
+        return false;
+    try {
+        const claim = loadClaim(run.claim_id, cwd);
+        if (!claim || claim.status !== 'active')
+            return false;
+    }
+    catch {
+        return false;
+    }
+    cascadeReleaseOnFailure(run, options.actor ?? 'reconciler', cwd, run.status, run.status_reason ?? `stranded ${run.status} run — read-path retry`);
+    return true;
+}
 function anyCompletionEvidence(evidence) {
     // pln#630 PR2b-c (§13 R3): a turn-owned run is completed ONLY on turn-keyed
     // evidence — never a bare presence sentinel or an assignment-keyed proxy
@@ -462,7 +524,7 @@ export function reconcileAgentRun(runId, cwd, options = {}) {
     const failHere = (reason) => {
         try {
             transitionAgentRun(runId, 'failed', { actor, status_reason: reason }, cwd);
-            cascadeReleaseOnFailure(run, actor, cwd);
+            cascadeReleaseOnFailure(run, actor, cwd, 'failed', reason);
             return { run_id: runId, action: 'inferred_failed', reason, evidence, previous_status, current_status: 'failed' };
         }
         catch (err) {
@@ -579,7 +641,7 @@ function reconcileTurnOwnedPreRunLease(run, reservation, evidence, cwd, options)
     }
     try {
         transitionAgentRun(run.id, targetStatus, { actor, status_reason: reason }, cwd);
-        cascadeReleaseOnFailure(run, actor, cwd, targetStatus);
+        cascadeReleaseOnFailure(run, actor, cwd, targetStatus, reason);
         return { run_id: run.id, action, reason, evidence, previous_status, current_status: targetStatus };
     }
     catch (err) {
@@ -638,7 +700,7 @@ export function reconcileDeadPidRunningAgentRunAtRead(runId, cwd, options = {})
     const failRun = (reason) => {
         try {
             transitionAgentRun(run.id, 'failed', { actor, status_reason: reason }, cwd);
-            cascadeReleaseOnFailure(run, actor, cwd);
+            cascadeReleaseOnFailure(run, actor, cwd, 'failed', reason);
             return { run_id: run.id, action: 'inferred_failed', reason, evidence, previous_status: run.status, current_status: 'failed' };
         }
         catch (err) {

package/dist/core/claims.js

@@ -275,6 +275,38 @@ export function releaseClaim(id, cwd, auth) {
     }
     return released;
 }
+/**
+ * Release a claim ONLY if it is still `active`, reporting whether THIS call
+ * performed the active→released transition.
+ *
+ * pln#641 review round-2 P1: `releaseClaim` sets `released` unconditionally —
+ * an already-released claim is silently re-released — so any caller that
+ * check-then-releases to decide whether to AUDIT the transition lies under a
+ * concurrent external release (the check passes, the write "succeeds", the
+ * caller emits an event for a transition it never performed). Here the status
+ * check runs INSIDE the same store mutation that writes the release, so the
+ * answer is exact: `released: true` means this call, and no one else, moved
+ * the claim out of `active`.
+ */
+export function releaseClaimIfActive(id, cwd, auth) {
+    let overrideUsed = false;
+    let transitioned = false;
+    const result = mutate({ cwd }, () => {
+        const claim = loadClaim(id, cwd);
+        if (!claim || claim.status !== 'active')
+            return claim;
+        overrideUsed = assertReleaseOwnership(claim, auth).overrideUsed;
+        claim.status = 'released';
+        claim.released_at = nowISO();
+        saveClaimUnlocked(claim, cwd);
+        transitioned = true;
+        return claim;
+    });
+    if (transitioned && overrideUsed && auth && result) {
+        auditReleaseOverride(result, auth, cwd);
+    }
+    return { released: transitioned, claim: result };
+}
 /**
  * Mark an active claim as `stale` — a distinct terminal state from `released`
  * used when a claim is being torn down because its owner is gone (session
@@ -844,6 +876,10 @@ export function releaseStaleClaimsFromOtherAgents(currentAgent, cwd, currentSess
 export function createCoordinatorClaim(options) {
     // Scope lock is GLOBAL: any active claim on the same scope blocks, regardless of agent.
     const existingScopeClaim = listClaims(options.cwd).find((claim) => claim.status === 'active' && claim.scope === options.scope);
+    // Set when the reuse candidate turns out to be RELEASED under the store lock
+    // (review PR#167 P1): the scope is genuinely free, so control falls through
+    // to the fresh-claim path instead of handing the dispatcher a dead claim.
+    let reuseCandidateGone = false;
     if (existingScopeClaim) {
         if (existingScopeClaim.agent === options.agent) {
             // Same agent already has this scope — reuse the claim (backward compat,
@@ -853,33 +889,75 @@ export function createCoordinatorClaim(options) {
             // worktree — the same silent false-negative the guard exists to prevent
             // (pln#520 Tier 2 / codex r2).
             let reuseWarning;
-            if (options.worktreeBaseRef) {
-                if (existingScopeClaim.worktree_path) {
-                    const reset = resetWorktreeToRef(existingScopeClaim.worktree_path, options.worktreeBaseRef);
+            let reusedWorktreePath = existingScopeClaim.worktree_path;
+            if (reusedWorktreePath) {
+                if (options.worktreeBaseRef) {
+                    const reset = resetWorktreeToRef(reusedWorktreePath, options.worktreeBaseRef);
                     if (!reset.ok) {
                         reuseWarning = `Reused claim ${existingScopeClaim.id} pinned to ref "${options.worktreeBaseRef}": ${reset.stderr.trim()}`;
                     }
                 }
-                else {
-                    reuseWarning = `Reused claim ${existingScopeClaim.id} has no worktree to pin to ref "${options.worktreeBaseRef}".`;
+            }
+            else {
+                // trp_72b4e9b3(2) — a claim persisted after a failed worktree creation
+                // (e.g. the path collision this trap documents) used to WEDGE the scope:
+                // every later dispatch reused this worktree-less claim and the spawn
+                // refused ("Reused claim has no worktree to pin"). Heal it here:
+                // provision the worktree the claim should have had (createWorktree now
+                // ADOPTS an existing same-branch worktree, so the original collision
+                // cause resolves too) and patch the claim. On failure the old warning
+                // stands — visible, and the next call retries.
+                try {
+                    reusedWorktreePath = createWorktree(options.cwd, `feat/${sanitizeBranchComponent(options.scope)}`, {
+                        sessionId: options.sessionId,
+                        agent: options.agent,
+                        baseRef: options.worktreeBaseRef,
+                        resetExistingBranch: options.resetExistingWorktreeBranch || Boolean(options.worktreeBaseRef),
+                    });
+                    const healedPath = reusedWorktreePath;
+                    // Review PR#167 P1 — the patch REVALIDATES under the store lock.
+                    // Provisioning takes seconds; if a release wins that window, the
+                    // reused claim id must NEVER reach the dispatcher (it would spawn an
+                    // assignment bound to a RELEASED claim). 'gone' falls through to the
+                    // fresh-claim path below — the scope is genuinely free now, and the
+                    // just-provisioned worktree is re-found by createWorktree's adoption.
+                    const healed = mutate({ cwd: options.cwd }, () => {
+                        const fresh = loadClaim(existingScopeClaim.id, options.cwd);
+                        if (!fresh || fresh.status !== 'active')
+                            return 'gone';
+                        if (!fresh.worktree_path) {
+                            fresh.worktree_path = healedPath;
+                            saveClaimUnlocked(fresh, options.cwd);
+                        }
+                        return fresh.worktree_path === healedPath ? 'patched' : 'already';
+                    });
+                    if (healed === 'gone')
+                        reuseCandidateGone = true;
+                }
+                catch (err) {
+                    reuseWarning = `Reused claim ${existingScopeClaim.id} has no worktree, and provisioning one failed: ${err instanceof Error ? err.message : String(err)}`;
                 }
             }
+            if (!reuseCandidateGone) {
+                return {
+                    claimId: existingScopeClaim.id,
+                    worktreePath: reusedWorktreePath,
+                    worktreeWarning: reuseWarning,
+                    reusedExisting: true,
+                };
+            }
+        }
+        else {
+            // DIFFERENT agent has an active claim on this scope — scope is locked.
+            // Return the existing claim info + a conflict flag so the dispatcher can skip.
             return {
                 claimId: existingScopeClaim.id,
                 worktreePath: existingScopeClaim.worktree_path,
-                worktreeWarning: reuseWarning,
                 reusedExisting: true,
+                scopeConflict: true,
+                conflictAgent: existingScopeClaim.agent,
             };
         }
-        // DIFFERENT agent has an active claim on this scope — scope is locked.
-        // Return the existing claim info + a conflict flag so the dispatcher can skip.
-        return {
-            claimId: existingScopeClaim.id,
-            worktreePath: existingScopeClaim.worktree_path,
-            reusedExisting: true,
-            scopeConflict: true,
-            conflictAgent: existingScopeClaim.agent,
-        };
     }
     const claimId = generateClaimId();
     // Resolved OUTSIDE the lock below, for the same reason acquireClaimScope does

package/dist/core/dispatch-status.js

@@ -324,7 +324,27 @@ function computeDiagnosis(assignment, agentRun, runtime, options) {
     // status is running / launching / waiting_input / blocked → check liveness
     const lastEventMs = new Date(agentRun.last_event_at ?? agentRun.started_at ?? agentRun.created_at).getTime();
     const stallAge = options.nowMs - lastEventMs;
+    // pln#527 — a stale last_event_at is NOT "stalled" when the filesystem is still
+    // active (logs streaming / worktree files edited). Workers emit no heartbeat
+    // during a long single operation (codex→stderr, claude -p buffering stdout),
+    // so fs activity is the truer liveness signal and vetoes the false-stalled.
+    const fsAge = runtime.last_fs_activity_ms;
+    const fsActive = fsAge !== undefined && fsAge < options.stallMs;
     if (runtime.pid_alive === false) {
+        // pln#621 pack (review of PR #170) — the fs-activity veto applies HERE too,
+        // not only to the stalled branch below. On an ack-wrapped spawn the tracked
+        // pid is the WRAPPER, dead by design while the worker keeps writing — the
+        // exact pln#520 shape (6 workers "dead", committing minutes later). This
+        // branch used to skip the veto and advise "cancel + reroute" on a worker
+        // that was demonstrably mid-write: a destructive recommendation on
+        // ambiguous evidence, which is the one thing the regression pack forbids.
+        if (fsActive) {
+            return {
+                health: 'healthy',
+                summary: `pid ${runtime.pid} is dead but the filesystem is ACTIVE (${Math.round((fsAge ?? 0) / 1000)}s ago) — on an ack-wrapped spawn the tracked pid is the wrapper, which exits by design while the worker keeps writing (pln#520)`,
+                recommended_next_action: 'No destructive action — the worker is writing. Re-check until a terminal signal appears (LANE-RESULT, completion sentinel, or a commit on the lane branch).',
+            };
+        }
         // pln#527 (#5) — surface a TARGETED diagnosis when the captured stderr matches
         // a known fatal boot signature (codex model/service_tier mismatch, API 400)
         // instead of a generic "silent_death".
@@ -338,12 +358,6 @@ function computeDiagnosis(assignment, agentRun, runtime, options) {
                 ?? 'Read .stderr.log for the exit reason; then trigger reconciliation by calling bclaw_find(entity="agent_run") again, or cancel + reroute.',
         };
     }
-    // pln#527 — a stale last_event_at is NOT "stalled" when the filesystem is still
-    // active (logs streaming / worktree files edited). Workers emit no heartbeat
-    // during a long single operation (codex→stderr, claude -p buffering stdout),
-    // so fs activity is the truer liveness signal and vetoes the false-stalled.
-    const fsAge = runtime.last_fs_activity_ms;
-    const fsActive = fsAge !== undefined && fsAge < options.stallMs;
     if (runtime.pid_alive === true && stallAge > options.stallMs && fsActive) {
         return {
             health: 'healthy',
@@ -428,11 +442,22 @@ export function getDispatchStatus(options) {
     }
     // pln#532 — the #1 verdict signal: a LANE-RESULT.json at the worktree root means
     // the worker FINISHED (even if it couldn't self-update the run). Read + validate it.
+    // trp_e824d2af — validate OWNERSHIP too: assignment_id is required on the schema,
+    // and a reused worktree keeps the prior turn's file at the root. Unmatched, that
+    // file declared a freshly-spawned round 2 terminal with round 1's verdict (observed
+    // live 2026-08-02, lop_626271ee10ad09d8). A mismatch is surfaced as stale, never
+    // as this dispatch's result.
     let laneResult;
+    let laneResultStale;
     if (worktreeForFs) {
         try {
             const parsed = LaneResultSchema.parse(JSON.parse(fs.readFileSync(path.join(worktreeForFs, 'LANE-RESULT.json'), 'utf-8')));
-            laneResult = { status: parsed.status, summary: parsed.summary };
+            if (parsed.assignment_id === assignmentId) {
+                laneResult = { status: parsed.status, summary: parsed.summary };
+            }
+            else {
+                laneResultStale = { assignment_id: parsed.assignment_id, status: parsed.status, summary: parsed.summary };
+            }
         }
         catch { /* no / invalid LANE-RESULT.json */ }
     }
@@ -451,6 +476,7 @@ export function getDispatchStatus(options) {
         },
         last_fs_activity_ms: lastFsActivityMs,
         lane_result: laneResult,
+        ...(laneResultStale ? { lane_result_stale: laneResultStale } : {}),
         commits_ahead: evidence?.commitsAhead,
         commits_ahead_raw: evidence?.commitsAheadRaw,
         commits_ahead_base: evidence?.baseRef,

package/dist/core/entity-operations.js

@@ -26,7 +26,7 @@ import { loadAllSessions } from './identity.js';
 import { loadInstructions } from './instructions.js';
 import { deleteAssignment, listAssignments, loadAssignment, saveAssignment, transitionAssignment } from './assignments.js';
 import { listAgentRuns } from './agentruns.js';
-import { reconcileAgentRun, reconcileDeadPidRunningAgentRunAtRead, TERMINAL_STATUSES } from './agentrun-reconciler.js';
+import { reconcileAgentRun, reconcileDeadPidRunningAgentRunAtRead, reconcileStrandedFailureClaimAtRead, TERMINAL_STATUSES } from './agentrun-reconciler.js';
 import { isObserverMode } from './observer-mode.js';
 import { deleteRuntimeNote, listRuntimeNotes, saveRuntimeNote, } from './runtime.js';
 import { createSequence, deleteSequence, listSequences, updateSequence, } from './sequence.js';
@@ -244,7 +244,17 @@ function loadAgentRunsWithReconciliation(cwd) {
                 reconcileAgentRun(run.id, cwd);
             }
             catch { /* best-effort: never block reads on reconciliation errors */ }
+            continue;
+        }
+        // pln#641 review P1 — the failure cascade fires only on the terminal
+        // TRANSITION, and this walk used to skip terminal runs entirely, so a
+        // declined/crashed business release stranded its claim until the 24h
+        // sweep. Recent failed/cancelled runs still holding an active claim
+        // retry the (idempotent) convergence here.
+        try {
+            reconcileStrandedFailureClaimAtRead(run, cwd);
         }
+        catch { /* best-effort: never block reads on reconciliation errors */ }
     }
     // Re-list to capture any transitions made above.
     return listAgentRuns(cwd);

package/dist/core/hint-aging.js

@@ -8,10 +8,12 @@
  * exactly the reflex we cannot afford.
  *
  * Contract: an entry is served in detail `k` times, then folded into a single
- * aggregate line that carries the exact next_action (`bclaw_find …`) so the
- * agent still has one clear pointer. The counter is a small JSON file, safe to
- * lose — hitting it twice per stale item is worse than losing it once, and a
- * missing file just resets counts to zero.
+ * aggregate line that carries the folded IDS themselves (trp_336e8054: it used
+ * to point at `bclaw_find(status:'stale')`, a filter that returns nothing
+ * because staleness is computed, not stored) so the agent still has one clear,
+ * WORKING pointer. The counter is a small JSON file, safe to lose — hitting it
+ * twice per stale item is worse than losing it once, and a missing file just
+ * resets counts to zero.
  *
  * @module
  */
@@ -63,8 +65,9 @@ function bump(counter, nowIso) {
 }
 /**
  * Fold stale warnings served ≥ k times into a single aggregate line. The
- * aggregate carries a bclaw_find pointer so the agent still has one exact
- * next-action instead of guessing which filter to use.
+ * aggregate carries the folded item IDS (grouped by entity) so the agent has
+ * an exact, executable next-action — never a filter the engine cannot resolve
+ * (trp_336e8054).
  *
  * Idempotence: calling with recordServe=false is pure — the returned split is
  * derived from the current registry alone. With recordServe=true the counter
@@ -103,11 +106,24 @@ export function ageStaleWarnings(warnings, cwd, options = {}) {
     }
     let aggregate;
     if (folded.length > 0) {
+        // trp_336e8054 — the aggregate used to recommend `bclaw_find(status:'stale')`,
+        // a filter that returns NOTHING: staleness is COMPUTED at session-start, never
+        // stored as a status, so the operator could not retrieve the very items the
+        // line announced. The folded items are in hand right here — carry their ids,
+        // grouped by entity, so the recovery (`bclaw_get` each id) works verbatim.
         const byEntity = new Map();
-        for (const w of folded)
-            byEntity.set(w.entity, (byEntity.get(w.entity) ?? 0) + 1);
-        const parts = [...byEntity.entries()].map(([entity, n]) => `${n} ${entity}${n === 1 ? '' : 's'}`);
-        aggregate = `${folded.length} stale item${folded.length === 1 ? '' : 's'} you've already been offered (${parts.join(', ')}) — bclaw_find(status:'stale') to review, or bclaw_transition to retire.`;
+        for (const w of folded) {
+            const ids = byEntity.get(w.entity) ?? [];
+            ids.push(w.id);
+            byEntity.set(w.entity, ids);
+        }
+        const ID_CAP = 8;
+        const parts = [...byEntity.entries()].map(([entity, ids]) => {
+            const shown = ids.slice(0, ID_CAP);
+            const overflow = ids.length - shown.length;
+            return `${ids.length} ${entity}${ids.length === 1 ? '' : 's'}: ${shown.join(', ')}${overflow > 0 ? ` +${overflow} more` : ''}`;
+        });
+        aggregate = `${folded.length} stale item${folded.length === 1 ? '' : 's'} you've already been offered (${parts.join('; ')}) — bclaw_get each id to review, or bclaw_transition to retire.`;
     }
     return { warnings: detail, aggregate, served_ids, folded_ids };
 }

package/dist/core/loops/reconcile-turn.js

@@ -5,7 +5,7 @@ import { complete_turn, add_artifact, advance } from './verbs.js';
 import { reducerForKind } from './result-reducers.js';
 import { loadAgentRun, transitionAgentRun } from '../agentruns.js';
 import { loadAssignment, transitionAssignment } from '../assignments.js';
-import { loadClaim, releaseClaim } from '../claims.js';
+import { loadClaim, releaseClaim, releaseClaimIfActive } from '../claims.js';
 import { createRuntimeEvent } from '../events.js';
 import { readCompletionSignals } from '../runtime-signals.js';
 import { buildFixCycleTask } from '../review-loop-close.js';
@@ -366,4 +366,139 @@ function convergeLockedTurn(reservation, input, actor, cwd) {
         ...(next_turn ? { next_turn } : {}),
     };
 }
+/**
+ * Converge a TURN-OWNED lane whose worker died at the TRANSPORT level (no lane
+ * result will ever arrive). dec#151, operator-decided option (b): the lane's
+ * claim is business state owned by its loop, so its release must be a business
+ * decision recorded ON the loop — through the same convergence family harvest
+ * uses (reconcileTurn) — never a side-effect of a transport verdict. Before
+ * this, the trp#433 GC cascade released the claim straight from the transport
+ * reconciler, which is exactly what the pln#638 6c effects boundary forbids.
+ *
+ * What "business decision" means concretely here: complete_turn(outcome:
+ * 'failed') writes the failure into the loop journal FIRST (crash-atomic WAL),
+ * and only then is the claim released — so a released claim always has a loop
+ * record explaining WHY, and a crash between the two converges on the next
+ * read-path pass (release is idempotent). Retry lanes are not starved: the
+ * release happens in the same lazy pass that inferred the failure, just via
+ * the loop's machinery instead of around it.
+ *
+ * Declines (converged:false — the claim STAYS, a later read-path pass retries):
+ *   - containment mismatch (never converge another store's loop/claim);
+ *   - lock contention (LockTimeout/LockLost);
+ *   - loop missing (a claim should not be stripped on evidence we cannot read).
+ * SUPERSEDED is converged:true WITHOUT release: a newer turn owns the slot, and
+ * claim REUSE across rounds is real (trp_e824d2af) — releasing the old round's
+ * claim would strip the live one.
+ */
+export function reconcileFailedTurn(input) {
+    const { reservation, run, cwd } = input;
+    const actor = input.actor ?? 'reconciler';
+    // Containment gate — same rule as reconcileTurn (§8 Q6), same win32 case-fold.
+    const operatingRoot = path.resolve(cwd ?? process.cwd());
+    const reservationRoot = path.resolve(reservation.store_root);
+    const sameStore = process.platform === 'win32'
+        ? reservationRoot.toLowerCase() === operatingRoot.toLowerCase()
+        : reservationRoot === operatingRoot;
+    if (!sameStore) {
+        return { converged: false, claim_released: false, reason: `containment: reservation store_root ${reservation.store_root} != operating store ${operatingRoot}` };
+    }
+    try {
+        return withLoopLock({
+            cwd,
+            intent: 'reconcile-failed-turn',
+            agentId: actor,
+            scope: { kind: 'loop', loopId: reservation.loop_id },
+            work: () => convergeFailedLockedTurn(reservation, run, input.reason, actor, cwd),
+        });
+    }
+    catch (err) {
+        if (err instanceof LockTimeoutError || err instanceof LockLostError) {
+            return { converged: false, claim_released: false, reason: `deferred (${err.name}); the next read-path pass retries` };
+        }
+        throw err;
+    }
+}
+function convergeFailedLockedTurn(reservation, run, transportReason, actor, cwd) {
+    // Audit-exact release (review PR#166 round-2 P1): the event is emitted only
+    // when THIS call performed the active→released transition. The check lives
+    // INSIDE the claim store's own mutation (releaseClaimIfActive), so an
+    // external bclaw_release_claim landing concurrently can no longer slip
+    // between a caller-side check and the write and produce a phantom
+    // business-release event.
+    const releaseAudited = (claimId, why) => {
+        if (!claimId)
+            return false;
+        try {
+            if (!releaseClaimIfActive(claimId, cwd).released)
+                return false;
+        }
+        catch {
+            return false;
+        }
+        try {
+            createRuntimeEvent({
+                agent: actor,
+                event_type: 'run_failed',
+                text: `Released claim ${claimId} as the BUSINESS convergence of failed turn ${reservation.turn_id}: ${why}`,
+                tags: ['loops', 'reconcile', 'claim-release', 'effects-boundary'],
+                assignment_id: reservation.child_ids.assignment_id,
+                run_id: run.id,
+                claim_id: claimId,
+                status_reason: 'turn_failure_business_release',
+            }, cwd);
+        }
+        catch { /* observability best-effort — never undo the release */ }
+        return true;
+    };
+    const loop = getLoop(reservation.loop_id, cwd);
+    if (!loop) {
+        // No loop to record on — do NOT strip the claim on evidence we cannot read.
+        // A genuinely deleted loop leaves the claim to the staleness sweep.
+        return { converged: false, claim_released: false, reason: `loop ${reservation.loop_id} not found — claim retained for the staleness sweep` };
+    }
+    const authoritativeClaimId = loadAssignment(reservation.child_ids.assignment_id, cwd)?.claim_id ?? reservation.claim_id;
+    // Terminal loop: the business story is already over — releasing is pure
+    // idempotent cleanup, mirroring reconcileTurn's terminal early-return.
+    if (LOOP_TERMINAL.has(loop.status)) {
+        const released = releaseAudited(authoritativeClaimId, `loop already ${loop.status}`);
+        return { converged: true, claim_released: released, reason: `loop already ${loop.status} — release-only cleanup` };
+    }
+    const slot = loop.slots.find((s) => s.slot_id === reservation.slot_id);
+    if (!slot) {
+        return { converged: false, claim_released: false, reason: `slot ${reservation.slot_id} not in loop ${reservation.loop_id} — claim retained` };
+    }
+    // Superseded: a NEWER turn owns this slot. Claim reuse across rounds is real
+    // (trp_e824d2af — round 2 rode round 1's claim), so releasing here would strip
+    // the LIVE attempt. Nothing to do for the dead round; the live one converges it.
+    if (slot.current_turn_id !== undefined && slot.current_turn_id !== reservation.turn_id) {
+        return { converged: true, claim_released: false, reason: `turn ${reservation.turn_id} superseded by ${slot.current_turn_id} — claim belongs to the live turn` };
+    }
+    // Record the business failure on the loop FIRST (crash-atomic WAL), then
+    // release. A slot already terminal means a prior pass recorded it — skip the
+    // double-record, still release (idempotent).
+    const slotTerminal = slot.status === 'done' || slot.status === 'failed' || slot.status === 'cancelled';
+    if (!slotTerminal) {
+        try {
+            complete_turn({
+                id: loop.id,
+                slot_id: slot.slot_id,
+                actor,
+                outcome: 'failed',
+                failure_reason: transportReason,
+            }, cwd);
+        }
+        catch (err) {
+            return { converged: false, claim_released: false, reason: `complete_turn failed: ${err instanceof Error ? err.message : String(err)} — claim retained, next pass retries` };
+        }
+    }
+    const released = releaseAudited(authoritativeClaimId, transportReason);
+    return {
+        converged: true,
+        claim_released: released,
+        reason: slotTerminal
+            ? `turn ${reservation.turn_id} failure already recorded — release re-attempted`
+            : `turn ${reservation.turn_id} failure recorded on loop ${loop.id}; claim ${released ? 'released' : 'not active'}`,
+    };
+}
 //# sourceMappingURL=reconcile-turn.js.map

package/dist/core/worktree.js

@@ -515,6 +515,24 @@ export function resetWorktreeToRef(worktreePath, ref) {
     if (!res.ok) {
         return { ok: false, stderr: res.stderr };
     }
+    // trp_e824d2af — LANE-RESULT.json is a TERMINAL SIGNAL, and `reset --hard`
+    // does not touch untracked files: left at the root, the PRIOR turn's result
+    // reads as the NEXT turn's completion (dispatch_status declared a
+    // freshly-spawned round 2 "worker reported done" with round 1's verdict,
+    // observed live 2026-08-02). Archive it into the worktree's .brainclaw/
+    // sidecar — preserved for forensics, out of the signal path, and already
+    // excluded from the residue check below. Best-effort: an archive failure
+    // falls through to the residue check, which then names the file loudly
+    // instead of passing it silently.
+    try {
+        const laneResultPath = path.join(worktreePath, 'LANE-RESULT.json');
+        if (fs.existsSync(laneResultPath)) {
+            const archiveDir = path.join(worktreePath, '.brainclaw');
+            fs.mkdirSync(archiveDir, { recursive: true });
+            fs.renameSync(laneResultPath, path.join(archiveDir, `LANE-RESULT.prev-${fs.statSync(laneResultPath).mtimeMs.toFixed(0)}.json`));
+        }
+    }
+    catch { /* best-effort — the residue check below surfaces what remains */ }
     // `reset --hard` realigns HEAD + tracked files, but leaves UNTRACKED residue
     // from a prior use of the worktree — files the worker could still compile or
     // test against even though they don't exist at the pinned ref (codex r3).
@@ -555,6 +573,32 @@ export function resetWorktreeToRef(worktreePath, ref) {
     }
     return { ok: true, stderr: '' };
 }
+/**
+ * trp_72b4e9b3 — on worktree ADOPTION, re-stamp the sidecar's base anchor.
+ *
+ * The sidecar's `base_ref_sha` (trp#926) is the anchor `commits_ahead` counts
+ * from. An adopted worktree keeps its ROUND-1 creation stamp, so round 2's git
+ * evidence counted commits since the previous round's base — observed live as
+ * a nonsensical `commits_ahead: 2` on a freshly re-pointed worktree. Best-effort:
+ * a missing/unreadable sidecar (hand-made worktree) is left untouched.
+ */
+function refreshSidecarBaseSha(worktreePath, mainWorktreePath, baseRef) {
+    const sidecarPath = path.join(worktreePath, '.brainclaw-worktree.json');
+    try {
+        if (!fs.existsSync(sidecarPath))
+            return;
+        const meta = JSON.parse(fs.readFileSync(sidecarPath, 'utf-8'));
+        const rev = runGit(['rev-parse', baseRef], mainWorktreePath);
+        meta.base_ref = baseRef;
+        if (rev.ok)
+            meta.base_ref_sha = rev.stdout.trim();
+        else
+            delete meta.base_ref_sha;
+        meta.adopted_at = new Date().toISOString();
+        fs.writeFileSync(sidecarPath, JSON.stringify(meta, null, 2));
+    }
+    catch { /* best-effort — stale anchor is observability-only */ }
+}
 /**
  * Detects whether multiple distinct brainclaw sessions are using the same
  * physical worktree directory (shared-checkout risk).
@@ -765,6 +809,68 @@ export function createWorktree(mainWorktreePath, branchName, options = {}) {
     }
     const targetPath = resolveWorktreePath(mainWorktreePath, branchName);
     if (fs.existsSync(targetPath)) {
+        // trp_72b4e9b3 — the path derives from the branch name, and loop-scoped
+        // dispatches derive the SAME branch every round (feat/review-loop-<lop>).
+        // A fresh claim on round 2 therefore collided here and the whole spawn
+        // failed (spawn_no_worktree) — worse, the claim persisted without a
+        // worktree and wedged every later dispatch on the scope. When the existing
+        // path is a REGISTERED worktree of this repo checked out on EXACTLY the
+        // requested branch, ADOPT it: honor the reused-branch contract first
+        // (can_2e282880 — never destroy unharvested commits unless the caller
+        // explicitly pinned a reset), then re-point it to the base. Anything else
+        // at the path (foreign dir, other branch) still refuses loudly.
+        const attachedPath = findWorktreePathForBranch(listWorktrees(mainWorktreePath), branchName);
+        const sameTarget = attachedPath !== undefined && (process.platform === 'win32'
+            ? path.resolve(attachedPath).toLowerCase() === path.resolve(targetPath).toLowerCase()
+            : path.resolve(attachedPath) === path.resolve(targetPath));
+        if (sameTarget) {
+            // Resolve the base to a SHA in the MAIN repo first: resetWorktreeToRef
+            // runs inside the worktree, where a symbolic ref like "HEAD" resolves to
+            // the WORKTREE's own tip — a silent no-op reset onto the stale round.
+            const requestedBase = options.baseRef ?? 'HEAD';
+            const baseRev = runGit(['rev-parse', requestedBase], mainWorktreePath);
+            if (!baseRev.ok) {
+                throw new Error(`Cannot adopt worktree ${targetPath}: base ref ${requestedBase} does not resolve: ${baseRev.stderr.trim()}`);
+            }
+            const adoptBase = baseRev.stdout.trim();
+            // Review PR#167 P1 — TRACKED dirt is unharvested work, unconditionally.
+            // A sandboxed codex CANNOT commit (.git read-only): its entire review
+            // output lives as staged/unstaged edits the coordinator harvests via
+            // `git diff HEAD`. The commit guard below never sees those, and the
+            // hard reset would destroy them silently — even under an explicit
+            // reset pin, because the pin means "start from this base", never
+            // "discard a worker's unharvested output". Untracked files are fine:
+            // the reset leaves them and resetWorktreeToRef's residue check governs.
+            const dirt = runGit(['status', '--porcelain=v1', '-z', '--untracked-files=no'], targetPath);
+            if (!dirt.ok) {
+                throw new Error(`Cannot adopt worktree ${targetPath}: dirty-state check failed: ${dirt.stderr.trim()}`);
+            }
+            if (dirt.stdout.length > 0) {
+                const files = dirt.stdout.split('\0').filter(Boolean).map((e) => e.slice(3)).slice(0, 5).join(', ');
+                throw new Error(`Refusing to adopt worktree ${targetPath}: it has uncommitted TRACKED changes (${files}) — a sandboxed worker's ` +
+                    `unharvested output. Harvest the diff first (git diff HEAD in that worktree) or remove the worktree.`);
+            }
+            if (!options.resetExistingBranch) {
+                const ahead = runGit(['rev-list', '--count', `${adoptBase}..${branchName}`], mainWorktreePath);
+                const aheadCount = ahead.ok ? parseInt(ahead.stdout.trim(), 10) : NaN;
+                if (!Number.isFinite(aheadCount)) {
+                    throw new Error(`Cannot assess divergence of existing worktree branch ${branchName} vs ${adoptBase}: ${ahead.stderr.trim()}`);
+                }
+                if (aheadCount > 0) {
+                    const commits = runGit(['log', '--oneline', '-n', '5', `${adoptBase}..${branchName}`], mainWorktreePath);
+                    throw new Error(`Refusing to adopt worktree ${targetPath}: branch ${branchName} has ${aheadCount} commit(s) not on ${adoptBase} (unharvested work). ` +
+                        `Harvest/merge or remove the worktree first. Divergent commits:\n${commits.stdout.trim()}`);
+                }
+            }
+            const reset = resetWorktreeToRef(targetPath, adoptBase);
+            if (!reset.ok) {
+                throw new Error(`Worktree path already exists and could not be adopted (reset to ${adoptBase} failed: ${reset.stderr.trim()}). ` +
+                    `Remove it first with 'brainclaw worktree remove'.`);
+            }
+            logger.warn(`[worktree] adopted existing worktree ${targetPath} (branch ${branchName}) and re-pointed it to ${adoptBase}`);
+            refreshSidecarBaseSha(targetPath, mainWorktreePath, adoptBase);
+            return targetPath;
+        }
         throw new Error(`Worktree path already exists: ${targetPath}. Remove it first with 'brainclaw worktree remove'.`);
     }
     // Ensure parent directory exists

package/dist/facts.js

@@ -1,8 +1,8 @@
 // Generated by scripts/emit-site-facts.mjs at build time. Do not edit manually.
-// Source: brainclaw v1.20.1 on 2026-08-02T21:44:51.056Z
+// Source: brainclaw v1.20.3 on 2026-08-03T12:57:46.375Z
 export const FACTS = {
-  "version": "1.20.1",
-  "generated_at": "2026-08-02T21:44:51.056Z",
+  "version": "1.20.3",
+  "generated_at": "2026-08-03T12:57:46.375Z",
   "tools": {
     "count": 67,
     "published_count": 65,
@@ -474,7 +474,7 @@ export const FACTS = {
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-02T21:44:48.979Z",
+    "generated_at": "2026-08-03T12:57:44.250Z",
     "node_version": "v24.18.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -483,7 +483,7 @@ export const FACTS = {
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 76,
+        "duration_ms_median": 79,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -491,7 +491,7 @@ export const FACTS = {
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 121,
+        "duration_ms_median": 129,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },
@@ -499,7 +499,7 @@ export const FACTS = {
         "name": "first_edit",
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
-        "duration_ms_median": 12,
+        "duration_ms_median": 13,
         "payload_chars_median": 499,
         "payload_tokens_est_median": 125
       }

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.20.1",
-  "generated_at": "2026-08-02T21:44:51.056Z",
+  "version": "1.20.3",
+  "generated_at": "2026-08-03T12:57:46.375Z",
   "tools": {
     "count": 67,
     "published_count": 65,
@@ -472,7 +472,7 @@
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-02T21:44:48.979Z",
+    "generated_at": "2026-08-03T12:57:44.250Z",
     "node_version": "v24.18.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -481,7 +481,7 @@
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 76,
+        "duration_ms_median": 79,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -489,7 +489,7 @@
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 121,
+        "duration_ms_median": 129,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },
@@ -497,7 +497,7 @@
         "name": "first_edit",
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
-        "duration_ms_median": 12,
+        "duration_ms_median": 13,
         "payload_chars_median": 499,
         "payload_tokens_est_median": 125
       }

package/docs/mcp-schema-changelog.md

@@ -8,6 +8,46 @@ guarantees this changelog follows.
 
 ---
 
+## [1.20.3] — 2026-08-03
+
+**Changed — `bclaw_dispatch_status` diagnosis values under the fs-activity veto (#170)**
+- A dead tracked pid combined with FRESH filesystem activity (log/worktree
+  mtime within the activity window) now yields `diagnosis.health: "healthy"`
+  with a "worker is writing" summary — previously this combination could
+  reach the `silent_death` branch and recommend "cancel + reroute" against a
+  live worker. Value change only on `diagnosis.health` /
+  `diagnosis.recommended_next_action` for that evidence combination; no field
+  added/removed, no inputSchema change. Consumers gating on
+  `health === "silent_death"` see strictly FEWER (more accurate) firings.
+- No MCP contract change from pln#644 (#171): the `review_turn_not_converged`
+  warning lives on the CLI harvest surface (`brainclaw harvest` text/`--json`
+  output), not on an MCP tool response.
+
+## [1.20.2] — 2026-08-03
+
+**Added — `lane_result_stale` on the dispatch_status runtime snapshot (#167)**
+- Additive sibling of `runtime.lane_result`: a LANE-RESULT.json found at the
+  worktree root that belongs to a DIFFERENT assignment (a prior turn in a
+  reused worktree) now lands here — `{ assignment_id, status, summary }` —
+  and is NEVER treated as this dispatch's terminal signal. `lane_result`
+  itself is unchanged in shape; it is simply no longer populated by a foreign
+  file (that population was the trp_e824d2af defect, not a contract).
+
+**Added — new audited runtime-event reason (#166)**
+- `status_reason: "turn_failure_business_release"` on `run_failed` events:
+  the business release of a turn-owned lane's claim after a transport
+  failure, emitted by the loop convergence (replaces the GC cascade's
+  `gc_cascade_release_on_failure` for turn-owned lanes only; non-turn-owned
+  runs keep emitting the GC reason).
+
+**Changed — stale-warnings aggregate text now carries ids (#167)**
+- The `stale_warnings_aggregate` string embeds the folded item ids grouped by
+  entity (cap 8 per entity + overflow note) instead of recommending
+  `bclaw_find(status:'stale')`, which the engine cannot resolve. Prose-only;
+  no structured field changed.
+- Read contract only across all three: no tool added/removed/renamed, no
+  inputSchema change, no surface-fingerprint movement.
+
 ## [1.20.1] — 2026-08-02
 
 **Changed — `generated_surfaces_stale` recovery data is now true, and structured (#163)**

package/docs/playbooks/autonomy-regression-pack.md

@@ -0,0 +1,91 @@
+# Autonomy-safety regression pack (pln#621)
+
+Every scenario below is a REAL incident from the dogfood store (trap ids), mapped
+to the non-destruction invariant it taught us and to the test that now pins it.
+The acceptance bar: **zero false destructive verdicts on this corpus** — a
+coordination engine may be wrong about liveness, but it must never destroy work
+(kill a working agent, reset an unharvested diff, strand or steal a claim,
+double-apply a verdict) on ambiguous evidence.
+
+Classification (step 3 of the plan): ✅ pinned = trap resolved with a
+counterfactual/regression test · 📋 mitigated = documented operator rule, not
+engine-enforceable · 🔴 red = open defect → the only candidates for new
+implementation work.
+
+Baseline corpus: snapshot `2026-08-03T09-38-35-129Z`
+(hash `399599d1…`, see docs/playbooks/store-snapshot.md). Shape fixtures for
+synthetic scenario stores: `tests/fixtures/store-corpus/`.
+
+## Kill / reroute — liveness verdicts must never destroy work
+
+| Incident | Invariant | Status |
+|---|---|---|
+| pln#520 — 6 workers killed on a dead WRAPPER pid, they committed 4-7 min later | Commits ahead + clean tree ⇒ verdict "harvest it", never kill/reroute, even with a dead pid | ✅ `dispatch-status.test.ts` "never kill-and-reroute" |
+| pln#520 variant — dead pid but the worker is WRITING (logs/worktree mtime fresh) | Fresh fs activity ⇒ the recommendation never contains ANY destructive instruction (kill/cancel/reroute) and the verdict is never silent_death | ✅ `dispatch-status.test.ts` "never says kill" — building this pin found a REAL gap: the silent_death branch skipped the fs-activity veto and advised "cancel + reroute" on a writing worker; fixed with the pin (review of PR #170) |
+| pln#527 — stale heartbeat during a long single operation | Stale heartbeat + fresh fs activity ⇒ "working, not stalled" (no fail inference) | ✅ `agentrun-reconciler.test.ts` heartbeat/fs-veto cases |
+| trp#292 — spawn deaths mis-diagnosed; stderr never read | Known fatal boot signatures in stderr yield a TARGETED diagnosis instead of a generic silent_death | ✅ `fs-activity-liveness.test.ts` recognizeStderrSignature cases (narrower than "every failure verdict carries the tail" — the reconciler's logTailSuffix covers the fail-inference side) |
+| Operator rule — never blanket-kill agents by process name (IDE runs them too) | Kill only pids from `agent_run.pid` cross-checked with `launched_at` | 📋 mitigated (operator rule; engine cannot see foreign processes) |
+
+## Harvest — verdicts and results are exactly-once and owned
+
+| Incident | Invariant | Status |
+|---|---|---|
+| trp_e824d2af — round 1's LANE-RESULT read as round 2's terminal signal | A lane result is terminal ONLY for the assignment named in its own `assignment_id`; foreign ⇒ `lane_result_stale` | ✅ `dispatch-status-lane-result.test.ts` |
+| Same trap, write side — stale terminal file survives worktree reuse | `resetWorktreeToRef` archives the prior LANE-RESULT out of the signal path | ✅ `worktree.test.ts` re-dispatch hygiene |
+| Double harvest of one lane | Re-ingesting the same LANE-RESULT is an idempotent no-op (marker) | ✅ `lane-result-harvest.test.ts` "skips on re-run" |
+| Double integration of a turn-owned approve lane | Exactly-once finalization — no duplicate verdict, loop stays terminal | ✅ `loops-pr3a-harvest-reconcile.test.ts` T7 |
+| pln#638 1c — CLI-harvested ideation lane never converged its loop | The ideation closer fires on the CLI harvest path too | ✅ `lane-harvest-cli-convergence.test.ts` |
+| 2026-08-02/03 ×2 — CLI-harvested REVIEW lane (file protocol, no turn keys) left its loop turn open; coordinator converged manually both times | A review lane harvested by assignment_id converges its turn on the report path (approve → reconcileTurn) or warns loudly naming the recovery (`review_turn_not_converged`), never a silent stall | ✅ `loops-pr3a-harvest-reconcile.test.ts` pln#644 suite (counterfactual: 8 tests red pre-fix) |
+
+## Worktrees — the workspace carries unharvested work
+
+| Incident | Invariant | Status |
+|---|---|---|
+| trp_72b4e9b3 — round-2 path collision wedged the scope | Same-branch registered worktree is ADOPTED, not refused | ✅ `worktree.test.ts` adoption |
+| PR#167 review P1 — adoption would hard-reset a sandboxed worker's uncommitted output | ANY tracked dirt refuses adoption, unconditionally (a reset pin is not a discard order) | ✅ `worktree.test.ts` tracked-dirt refusal |
+| can_2e282880 — branch reuse ran a worker on an April base / would destroy commits | Unharvested commits refuse silent reuse/adoption | ✅ `worktree.test.ts` unharvested-commits guards |
+| trp (2026-08-01) — `git worktree remove` follows Windows junctions, wiped main-repo node_modules | brainclaw's own removal detaches junctions first; raw git remove remains dangerous | ✅ engine path (`detachWorktreeJunctions`) · 📋 the raw-git variant stays an operator rule |
+| trp#950 — two >48-char scopes collapsed to one branch slug | Distinct scopes yield distinct valid slugs | ✅ `worktree.test.ts` slug suite |
+| trp#926 — a squash-merged lane read as "worker delivered" again (`commits_ahead` counted the ancestry, not the patches) | Squash-merged work counts 0 via patch-id refinement — no false delivered verdict, no false GC | ✅ `worktree-squash-aware.test.ts` (row added on review of PR #170 — the audit found the incident missing from the catalog) |
+| Duplicate spawn — a respawned assignment ran beside its "dead" predecessor in one worktree | Two live workers must never share a worktree unknowingly | 📋 mitigated (heartbeat-file coordination; pln#630 launch fence covers the turn-owned path: reservation + grant make a duplicate launch DENIED) — engine-wide guard tracked in pln#644 classification notes |
+
+## Claims / cascades — advisory locks that cannot lie or leak
+
+| Incident | Invariant | Status |
+|---|---|---|
+| trp#433 — dead runs left active claims accumulating | Failed runs release their claim (GC cascade, non-turn-owned) | ✅ `agentrun-reconciler.test.ts` trp#433 cases |
+| pln#638 6c — transport completion released claims / triggered reviews | Transport completion never RELEASES the claim (`inferred_completed` with the claim still active) | ✅ `agentrun-reconciler.test.ts` 6c pin — narrower than the full boundary: the no-review-trigger half was audited true in the 6c pass but has no dedicated pin (honest gap, not a defect) |
+| dec#151 — turn-owned failure released via transport GC | Turn-owned release is a LOOP business decision (recorded on the loop first, audited) | ✅ `agentrun-reconciler.test.ts` pln#641 cases |
+| PR#166 review P1 — the promised lazy retry was unreachable (read paths skip terminal runs) | A stranded claim converges from a plain `bclaw_find(agent_run)` read | ✅ `agentrun-reconciler.test.ts` P1 cases incl. `listEntities` surface test |
+| PR#166 review P1 round 2 — the release audit could lie under a concurrent release | `releaseClaimIfActive`: check+transition atomic; the event fires only for the call that transitioned | ✅ `loops-reconcile-turn.test.ts` atomic-contract cases |
+| trp_72b4e9b3(2) — a worktree-less claim wedged all dispatch on its scope | Reuse heals the claim (provisions + patches under the store lock) | ✅ `worktree.test.ts` heal test — the concurrently-released-claim window is guarded by locked revalidation ('gone' → fresh-claim path, codex-verified control flow, PR #167) but is not injection-testable; the heal pin covers the wedge only |
+| trp#928 — any caller could release any claim | Ownership-checked release; coordinator override is explicit + audited | ✅ claim auth suites |
+| Claim reuse across review rounds (trp_e824d2af context) | A SUPERSEDED turn's convergence never releases the live turn's reused claim | ✅ `loops-reconcile-turn.test.ts` superseded case |
+
+## Loop closure — verdicts recorded once, loops never wedged
+
+| Incident | Invariant | Status |
+|---|---|---|
+| pln#630 — double reconcile spawned both rounds | Exactly-once iteration bump under the loop lock | ✅ `loops-reconcile-turn.test.ts` findings 1/2 |
+| §13 R4 — completed+failed contradiction auto-accepted | Contradiction WITHHOLDS convergence, journals a conflict | ✅ `loops-reconcile-turn.test.ts` R4 cases |
+| pln#639 — empty artifacts satisfied phase gates | Gates reject empty artifact bodies | ✅ gate suites |
+| Stale/mismatched lane evidence converging the wrong attempt | Read-strict turn keys (turn_id+run_id+nonce) or no convergence | ✅ `loops-reconcile-turn.test.ts` read-strict case |
+
+## Red defects opened by this classification
+
+- **pln#644 — review-loop CLI-harvest turn convergence** *(RESOLVED)*: a review
+  lane delivered via the file protocol without turn keys was harvested into the
+  assignment but its loop turn stayed open silently; the coordinator converged
+  by hand twice on 2026-08-02/03 (loops `lop_626271ee10ad09d8`,
+  `lop_4d869568bd99ddc0`). Fixed at the CLI harvest site: the report path now
+  finalizes an APPROVE turn-owned lane via the same exactly-once
+  `reconcileTurn` that `--integrate` uses (evidence sourced from the lane keys
+  or the wrapper sentinel — read-strict untouched), and every other
+  non-converged case (request_changes, missing verdict, refused evidence)
+  emits a `review_turn_not_converged` warning naming the open turn and the
+  recovery, surfaced on both the CLI text and `--json` outputs. Pinned in
+  `loops-pr3a-harvest-reconcile.test.ts` (pln#644 suite, counterfactual-red).
+
+Everything else in the corpus is pinned or explicitly an operator rule. New
+incidents: add the trap, add the row, add the counterfactual test — in that
+order.

package/docs/playbooks/store-snapshot.md

@@ -0,0 +1,68 @@
+# Store snapshot — the snapshot-before-curation rule (pln#619)
+
+The loaded dogfood store IS a corpus: months of real claims, loops, assignments,
+journals and debris that no synthetic fixture reproduces. Every curation
+(candidate triage, GC, migration, mass-ack) destroys part of it. The rule:
+
+> **Take a snapshot before ANY curation of the store.** Cleanup must be
+> reversible and traceable; the regression pack (pln#621) needs a stable
+> baseline to reproduce metrics against.
+
+## Tool
+
+`scripts/store-snapshot.mjs` — zero dependencies, four commands:
+
+```
+node scripts/store-snapshot.mjs create  [--store <dir>] [--out <dir>] [--brainclaw-version <v>]
+node scripts/store-snapshot.mjs verify  --snapshot <dir>
+node scripts/store-snapshot.mjs restore --snapshot <dir> --to <empty-dir>
+node scripts/store-snapshot.mjs fixtures [--store <dir>] --out <dir>
+```
+
+- **create** copies the store into `<out>/store/`, writes `manifest.json`
+  (schema version, timestamp, source path + git HEAD, per-directory totals,
+  per-entity counts, one deterministic `corpus_hash` over path+size+sha256 of
+  every file), then marks the snapshot files read-only. Default destination is
+  `~/.brainclaw/snapshots/<project>/<stamp>/` — deliberately OUTSIDE any git
+  repo: the store carries private coordination content and must never transit
+  through a public remote. The hash is computed on the COPY, so a live store
+  mutating mid-copy still yields an internally consistent manifest (for a
+  perfectly quiescent capture, snapshot while the MCP is idle).
+- **verify** recomputes totals, entity counts and the corpus hash and compares
+  them to the manifest — immutability is checked, never assumed. Exit 1 on any
+  divergence.
+- **restore** copies into an EMPTY target only (never in place), clears the
+  read-only bits, then verifies the restored tree against the manifest — the
+  pln#619 acceptance criterion ("a restored store reproduces the metrics")
+  executed on every restore.
+- **fixtures** exports SHAPE summaries per entity collection (field names,
+  value types, presence ratios) and observed values for an ALLOWLIST of
+  enum-like field names only (status, type, severity, …). Free text and
+  identity values are never exported, whatever their length — the rule is
+  allowlist-only because two heuristics failed before it: a length gate leaked
+  the hostname and OS username, and its identity-field patch still leaked
+  short free text (adversarial review of PR #169 caught it in the shipped
+  fixtures). Committed under `tests/fixtures/store-corpus/` for the
+  regression pack.
+
+The corpus hash serializes records NUL-delimited: a POSIX filename may legally
+contain a newline, so newline-delimited records would let two distinct trees
+share a preimage (same review, finding 2).
+
+## Baseline of record
+
+The pre-curation baseline of 2026-08-03 (brainclaw 1.20.2, store at ~1.9 GB /
+12 121 files, 644 claims / 296 assignments / 243 loops):
+
+```
+~/.brainclaw/snapshots/shared_agent_memory_mvp/2026-08-03T09-53-14-067Z
+corpus_hash 2732797349b1d61c38ba838f8d03ccba6fe901c755788ba212f0375db479094c
+```
+
+(The candidate-triage curation of 2026-08-03 was performed against the earlier
+capture of the same morning; this retake follows the hash-encoding fix and
+supersedes it.)
+
+Restore-verified on capture day (hash + entity counts reproduced in an
+isolated target). Any later "did the curation lose something?" question is
+answered against this manifest.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainclaw",
-  "version": "1.20.1",
+  "version": "1.20.3",
   "description": "Shared project memory for humans and coding agents.",
   "type": "module",
   "repository": {