brainclaw 1.20.1 → 1.20.2

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

@@ -428,11 +428,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 +462,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.2 on 2026-08-03T09:22:06.116Z
 export const FACTS = {
-  "version": "1.20.1",
-  "generated_at": "2026-08-02T21:44:51.056Z",
+  "version": "1.20.2",
+  "generated_at": "2026-08-03T09:22:06.116Z",
   "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-03T09:22:04.503Z",
     "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": 51,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -491,15 +491,15 @@ 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,
-        "payload_chars_median": 2626,
-        "payload_tokens_est_median": 657
+        "duration_ms_median": 80,
+        "payload_chars_median": 2625,
+        "payload_tokens_est_median": 656
       },
       {
         "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": 9,
         "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.2",
+  "generated_at": "2026-08-03T09:22:06.116Z",
   "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-03T09:22:04.503Z",
     "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": 51,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -489,15 +489,15 @@
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 121,
-        "payload_chars_median": 2626,
-        "payload_tokens_est_median": 657
+        "duration_ms_median": 80,
+        "payload_chars_median": 2625,
+        "payload_tokens_est_median": 656
       },
       {
         "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": 9,
         "payload_chars_median": 499,
         "payload_tokens_est_median": 125
       }

package/docs/mcp-schema-changelog.md

@@ -8,6 +8,31 @@ guarantees this changelog follows.
 
 ---
 
+## [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/package.json

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