brainclaw 1.20.0 → 1.20.2

package/dist/commands/export.js

@@ -6,7 +6,7 @@ import { loadConfig, saveConfig } from '../core/config.js';
 import { isAgentIntegrationName, upsertAgentIntegrationDeclaration } from '../core/agent-integrations.js';
 import { resolveInstructions, loadInstructions } from '../core/instructions.js';
 import { detectAiAgent } from '../core/ai-agent-detection.js';
-import { AGENT_EXPORT_REGISTRY, resolveExportTarget, resolveExportTargetByFormat, writeExportFile, writeLiveCompanionFile, buildHygieneSection, describeAutoConfigWrite, writeExportCompanionFiles, collectExportGitignoreEntries, ensureGitignoreEntries, BRAINCLAW_EXCLUSIVE_DIRECTORIES, } from '../core/agent-files.js';
+import { AGENT_EXPORT_REGISTRY, resolveExportTarget, resolveExportTargetByFormat, resolveLiveCompanionPath, writeExportFile, writeLiveCompanionFile, buildHygieneSection, describeAutoConfigWrite, writeExportCompanionFiles, collectExportGitignoreEntries, ensureGitignoreEntries, BRAINCLAW_EXCLUSIVE_DIRECTORIES, } from '../core/agent-files.js';
 import { buildCoordinationSnapshot } from '../core/coordination.js';
 import { listClaims } from '../core/claims.js';
 import { listCandidates } from '../core/candidates.js';
@@ -187,18 +187,23 @@ export function refreshLiveCompanions(cwd) {
         const instructions = getInstructionText({ project: undefined, agent: undefined }, effectiveCwd);
         const activeClaims = listClaims(effectiveCwd).filter((c) => c.status === 'active');
         const pendingCandidates = listCandidates('pending', effectiveCwd);
-        const seen = new Set();
-        const targets = AGENT_EXPORT_REGISTRY.filter((t) => {
-            if (seen.has(t.format))
-                return false;
-            seen.add(t.format);
-            return true;
-        });
         let written = 0;
         const errors = [];
         const liveGitignoreEntries = [];
-        for (const target of targets) {
+        // trp_6a49f976 F1 (codex review): dedupe by RESOLVED LIVE PATH, never by
+        // stable export format. Format-dedup dropped every agents-md agent after
+        // codex — including mistral-vibe, whose REGISTERED live companion
+        // (.vibe/live.md) then never got refreshed, while the stale-surface
+        // advisory told the operator `brainclaw refresh` would fix exactly that
+        // file. A path counts as taken only once something was actually RENDERED
+        // for it, so a tier with no live companion (codex, Tier A) does not shadow
+        // a rendering agent that shares its default path (hermes → AGENTS.live.md).
+        const renderedLivePaths = new Set();
+        for (const target of AGENT_EXPORT_REGISTRY) {
             try {
+                const livePath = resolveLiveCompanionPath(target.agentName, target.relativePath);
+                if (renderedLivePaths.has(livePath))
+                    continue;
                 const profile = getAgentCapabilityProfile(target.agentName);
                 if (!profile)
                     continue;
@@ -214,7 +219,8 @@ export function refreshLiveCompanions(cwd) {
                 };
                 const live = renderLiveSection(input);
                 if (!live)
-                    continue; // Tier A — no live companion needed
+                    continue; // no live companion for this tier
+                renderedLivePaths.add(livePath);
                 const writeResult = writeLiveCompanionFile(live.content, target.agentName, target.relativePath, effectiveCwd);
                 if (writeResult.created || writeResult.updated) {
                     written++;

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/instruction-templates.js

@@ -220,15 +220,18 @@ function renderHeader(input) {
 function renderLiveHeader(input) {
     // pln#638 volet 2a — HONESTY FIX. This header used to say "auto-refreshed",
     // but regeneration is EXPLICIT: it happens on session-end, handoff, and
-    // `export --write`. An agent tier that never fires those events (no hooks, no
-    // MCP) read a file claiming to be fresh while being arbitrarily stale. A claim
-    // that is false for half the tiers is worse than no claim, so the header now
+    // `brainclaw refresh`. An agent tier that never fires those events (no hooks,
+    // no MCP) read a file claiming to be fresh while being arbitrarily stale. A
+    // claim that is false for half the tiers is worse than no claim, so the header
     // names the actual triggers and tells the reader how to force a refresh.
+    // trp_6a49f976: the 1.20.0 header cited `brainclaw export --write`, which the
+    // CLI rejects outright AND which never wrote a live companion — the honest
+    // recovery for THIS file is `brainclaw refresh`.
     // Guarded by tests/unit/guidance-engine-consistency.test.ts.
     return [
-        `> Brainclaw live state — do not edit. Regenerated on: session-end, handoff, \`brainclaw export --write\`.`,
+        `> Brainclaw live state — do not edit. Regenerated on: session-end, handoff, \`brainclaw refresh\`.`,
         `> Written by brainclaw v${input.brainclawVersion} at ${new Date().toISOString().slice(0, 19)}`,
-        `> Older than your last session? It is stale — run \`brainclaw export --write\` to refresh.`,
+        `> Older than your last session? It is stale — run \`brainclaw refresh\`.`,
     ].join('\n');
 }
 // Kept deliberately small (pln#542): entry point + grammar + escalation

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/surface-freshness.js

@@ -3,7 +3,7 @@
  *
  * WHY THIS EXISTS. 2a made the live header HONEST: it stopped claiming
  * "auto-refreshed" and started naming its real triggers (session-end, handoff,
- * `export --write`) plus the version and timestamp that wrote it. Honesty alone
+ * `brainclaw refresh`) plus the version and timestamp that wrote it. Honesty alone
  * does not help an agent tier that never fires any of those triggers, though — it
  * just tells that tier, truthfully, that the file might be arbitrarily old. 2b
  * closes the loop by USING the stamp: compare it against the running version and
@@ -63,16 +63,23 @@ export function assessSurfaceFreshness(content, currentVersion) {
         return { kind: 'fresh', version };
     return { kind: 'stale', stampedVersion: version, currentVersion };
 }
+/** The command that regenerates every stable surface. `export --write` alone is rejected by the CLI (a mode flag is required — see runExport). */
+export const STABLE_SURFACE_REFRESH_COMMAND = 'brainclaw export --all --write';
+/** The command that regenerates every live companion. */
+export const LIVE_SURFACE_REFRESH_COMMAND = 'brainclaw refresh';
 /**
  * The set of surfaces this project could have on disk, derived from the export
  * registries rather than listed here. Deduplicated because several agents share
- * a target (four of them write AGENTS.md).
+ * a target (four of them write AGENTS.md); a path claimed by both registries
+ * counts as stable, since `export` regenerates it.
  */
-function candidateSurfacePaths() {
-    return [...new Set([
-            ...AGENT_EXPORT_REGISTRY.map((t) => t.relativePath),
-            ...LIVE_COMPANION_EXPORT_REGISTRY.map((t) => t.relativePath),
-        ])];
+function candidateSurfaces() {
+    const stable = new Set(AGENT_EXPORT_REGISTRY.map((t) => t.relativePath));
+    const live = new Set(LIVE_COMPANION_EXPORT_REGISTRY.map((t) => t.relativePath));
+    return [
+        ...[...stable].map((relativePath) => ({ relativePath, kind: 'stable' })),
+        ...[...live].filter((p) => !stable.has(p)).map((relativePath) => ({ relativePath, kind: 'live' })),
+    ];
 }
 /**
  * Scan the project's generated surfaces and report the ones stamped with a
@@ -85,7 +92,7 @@ function candidateSurfacePaths() {
  */
 export function reconcileSurfaceFreshness(cwd, currentVersion) {
     const result = { stale: [], freshCount: 0, unknownCount: 0 };
-    for (const relativePath of candidateSurfacePaths()) {
+    for (const { relativePath, kind } of candidateSurfaces()) {
         const full = path.join(cwd, relativePath);
         let head;
         try {
@@ -107,7 +114,7 @@ export function reconcileSurfaceFreshness(cwd, currentVersion) {
         }
         const verdict = assessSurfaceFreshness(head, currentVersion);
         if (verdict.kind === 'stale')
-            result.stale.push({ relativePath, stampedVersion: verdict.stampedVersion });
+            result.stale.push({ relativePath, stampedVersion: verdict.stampedVersion, kind });
         else if (verdict.kind === 'fresh')
             result.freshCount += 1;
         else
@@ -119,31 +126,48 @@ export function reconcileSurfaceFreshness(cwd, currentVersion) {
  * Build the advisory for a stale-surface scan, or `undefined` when there is
  * nothing to say.
  *
- * NO `next_actions`, deliberately. The recovery is `brainclaw export --write`,
- * and there is no MCP tool that performs it — `bclaw_setup` is the onboarding
- * wizard and takes no write flag. Pointing at it anyway would ship a next_action
- * whose args the engine rejects, which is the precise class of drift this plan
- * exists to eliminate; and per pln#634's own rule, a builder with no genuine
- * follow-up returns nothing rather than inventing one. The command therefore
- * travels in the message, where it is true.
+ * NO `next_actions`, deliberately. The recovery is a CLI command, and there is
+ * no MCP tool that performs it — `bclaw_setup` is the onboarding wizard and
+ * takes no write flag. Pointing at it anyway would ship a next_action whose
+ * args the engine rejects, which is the precise class of drift this plan exists
+ * to eliminate; and per pln#634's own rule, a builder with no genuine follow-up
+ * returns nothing rather than inventing one. The command therefore travels in
+ * the message, where it is true.
+ *
+ * WHICH command depends on what is stale (trp_6a49f976): this advisory shipped
+ * in 1.20.0 recommending `brainclaw export --write`, which the CLI rejects
+ * (a mode flag is required) and which — even corrected to `--all` — never
+ * touches live companions, the very files the first real-world firing listed.
+ * The recovery must be per kind, and only for the kinds actually stale.
  */
 export function staleSurfaceWarning(result, currentVersion) {
     if (result.stale.length === 0)
         return undefined;
     const shown = result.stale.slice(0, 8);
     const overflow = result.stale.length - shown.length;
+    const kinds = new Set(result.stale.map((s) => s.kind));
+    const commands = [
+        ...(kinds.has('stable') ? [STABLE_SURFACE_REFRESH_COMMAND] : []),
+        ...(kinds.has('live') ? [LIVE_SURFACE_REFRESH_COMMAND] : []),
+    ];
+    const recovery = kinds.size === 2
+        ? ` Run \`${STABLE_SURFACE_REFRESH_COMMAND}\` (stable surfaces) and \`${LIVE_SURFACE_REFRESH_COMMAND}\` (live companions) to refresh them.`
+        : ` Run \`${commands[0]}\` to refresh them.`;
     return {
         code: 'generated_surfaces_stale',
         message: `${result.stale.length} generated guidance surface(s) were written by an older brainclaw than v${currentVersion}: `
             + shown.map((s) => `${s.relativePath} (v${s.stampedVersion})`).join(', ')
             + (overflow > 0 ? ` (+${overflow} more)` : '')
             + '. An agent tier that never triggers a regeneration is reading them as-is.'
-            + ' Run `brainclaw export --write` to refresh them.',
+            + recovery,
         data: {
             current_version: currentVersion,
-            stale_surfaces: shown.map((s) => ({ path: s.relativePath, stamped_version: s.stampedVersion })),
+            stale_surfaces: shown.map((s) => ({ path: s.relativePath, stamped_version: s.stampedVersion, kind: s.kind })),
             ...(overflow > 0 ? { stale_surfaces_omitted: overflow } : {}),
-            refresh_command: 'brainclaw export --write',
+            // Kept as a single runnable string for consumers that shipped against
+            // 1.20.0; refresh_commands is the structured form.
+            refresh_command: commands.join(' && '),
+            refresh_commands: commands,
         },
     };
 }

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.0 on 2026-08-02T17:17:41.989Z
+// Source: brainclaw v1.20.2 on 2026-08-03T09:22:06.116Z
 export const FACTS = {
-  "version": "1.20.0",
-  "generated_at": "2026-08-02T17:17:41.989Z",
+  "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-02T17:17:40.300Z",
+    "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": 65,
+        "duration_ms_median": 51,
         "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": 101,
+        "duration_ms_median": 80,
         "payload_chars_median": 2625,
         "payload_tokens_est_median": 656
       },
@@ -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": 10,
+        "duration_ms_median": 9,
         "payload_chars_median": 499,
         "payload_tokens_est_median": 125
       }

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.20.0",
-  "generated_at": "2026-08-02T17:17:41.989Z",
+  "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-02T17:17:40.300Z",
+    "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": 65,
+        "duration_ms_median": 51,
         "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": 101,
+        "duration_ms_median": 80,
         "payload_chars_median": 2625,
         "payload_tokens_est_median": 656
       },
@@ -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": 10,
+        "duration_ms_median": 9,
         "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.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)**
+- The VALUE of `data.refresh_command` changes: it was `brainclaw export --write`,
+  which the CLI rejects (a mode flag is required), and is now a runnable command
+  derived from what is actually stale — `brainclaw export --all --write` (stable
+  surfaces), `brainclaw refresh` (live companions), or both joined with ` && `
+  when both kinds are stale. The field keeps its type (string); consumers that
+  displayed it verbatim now display something that works.
+- Additive fields on the same warning's `data`: `refresh_commands: string[]`
+  (the structured form of the above) and `kind: "stable" | "live"` on each
+  `stale_surfaces[]` entry.
+- Read contract only: no tool added/removed/renamed, no inputSchema change,
+  no surface-fingerprint movement.
+
 ## [1.20.0] — 2026-08-02
 
 **Fixed — 1.19.0 contract entries now actually emitted (#158)**

package/package.json

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