brainclaw 1.20.2 → 1.20.3

package/dist/commands/harvest.js

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

package/dist/core/dispatch-status.js

@@ -324,7 +324,27 @@ function computeDiagnosis(assignment, agentRun, runtime, options) {
     // status is running / launching / waiting_input / blocked → check liveness
     const lastEventMs = new Date(agentRun.last_event_at ?? agentRun.started_at ?? agentRun.created_at).getTime();
     const stallAge = options.nowMs - lastEventMs;
+    // pln#527 — a stale last_event_at is NOT "stalled" when the filesystem is still
+    // active (logs streaming / worktree files edited). Workers emit no heartbeat
+    // during a long single operation (codex→stderr, claude -p buffering stdout),
+    // so fs activity is the truer liveness signal and vetoes the false-stalled.
+    const fsAge = runtime.last_fs_activity_ms;
+    const fsActive = fsAge !== undefined && fsAge < options.stallMs;
     if (runtime.pid_alive === false) {
+        // pln#621 pack (review of PR #170) — the fs-activity veto applies HERE too,
+        // not only to the stalled branch below. On an ack-wrapped spawn the tracked
+        // pid is the WRAPPER, dead by design while the worker keeps writing — the
+        // exact pln#520 shape (6 workers "dead", committing minutes later). This
+        // branch used to skip the veto and advise "cancel + reroute" on a worker
+        // that was demonstrably mid-write: a destructive recommendation on
+        // ambiguous evidence, which is the one thing the regression pack forbids.
+        if (fsActive) {
+            return {
+                health: 'healthy',
+                summary: `pid ${runtime.pid} is dead but the filesystem is ACTIVE (${Math.round((fsAge ?? 0) / 1000)}s ago) — on an ack-wrapped spawn the tracked pid is the wrapper, which exits by design while the worker keeps writing (pln#520)`,
+                recommended_next_action: 'No destructive action — the worker is writing. Re-check until a terminal signal appears (LANE-RESULT, completion sentinel, or a commit on the lane branch).',
+            };
+        }
         // pln#527 (#5) — surface a TARGETED diagnosis when the captured stderr matches
         // a known fatal boot signature (codex model/service_tier mismatch, API 400)
         // instead of a generic "silent_death".
@@ -338,12 +358,6 @@ function computeDiagnosis(assignment, agentRun, runtime, options) {
                 ?? 'Read .stderr.log for the exit reason; then trigger reconciliation by calling bclaw_find(entity="agent_run") again, or cancel + reroute.',
         };
     }
-    // pln#527 — a stale last_event_at is NOT "stalled" when the filesystem is still
-    // active (logs streaming / worktree files edited). Workers emit no heartbeat
-    // during a long single operation (codex→stderr, claude -p buffering stdout),
-    // so fs activity is the truer liveness signal and vetoes the false-stalled.
-    const fsAge = runtime.last_fs_activity_ms;
-    const fsActive = fsAge !== undefined && fsAge < options.stallMs;
     if (runtime.pid_alive === true && stallAge > options.stallMs && fsActive) {
         return {
             health: 'healthy',

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.2 on 2026-08-03T09:22:06.116Z
+// Source: brainclaw v1.20.3 on 2026-08-03T12:57:46.375Z
 export const FACTS = {
-  "version": "1.20.2",
-  "generated_at": "2026-08-03T09:22:06.116Z",
+  "version": "1.20.3",
+  "generated_at": "2026-08-03T12:57:46.375Z",
   "tools": {
     "count": 67,
     "published_count": 65,
@@ -474,7 +474,7 @@ export const FACTS = {
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-03T09:22:04.503Z",
+    "generated_at": "2026-08-03T12:57:44.250Z",
     "node_version": "v24.18.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -483,7 +483,7 @@ export const FACTS = {
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 51,
+        "duration_ms_median": 79,
         "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": 80,
-        "payload_chars_median": 2625,
-        "payload_tokens_est_median": 656
+        "duration_ms_median": 129,
+        "payload_chars_median": 2626,
+        "payload_tokens_est_median": 657
       },
       {
         "name": "first_edit",
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
-        "duration_ms_median": 9,
+        "duration_ms_median": 13,
         "payload_chars_median": 499,
         "payload_tokens_est_median": 125
       }

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.20.2",
-  "generated_at": "2026-08-03T09:22:06.116Z",
+  "version": "1.20.3",
+  "generated_at": "2026-08-03T12:57:46.375Z",
   "tools": {
     "count": 67,
     "published_count": 65,
@@ -472,7 +472,7 @@
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-03T09:22:04.503Z",
+    "generated_at": "2026-08-03T12:57:44.250Z",
     "node_version": "v24.18.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -481,7 +481,7 @@
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 51,
+        "duration_ms_median": 79,
         "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": 80,
-        "payload_chars_median": 2625,
-        "payload_tokens_est_median": 656
+        "duration_ms_median": 129,
+        "payload_chars_median": 2626,
+        "payload_tokens_est_median": 657
       },
       {
         "name": "first_edit",
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
-        "duration_ms_median": 9,
+        "duration_ms_median": 13,
         "payload_chars_median": 499,
         "payload_tokens_est_median": 125
       }

package/docs/mcp-schema-changelog.md

@@ -8,6 +8,21 @@ guarantees this changelog follows.
 
 ---
 
+## [1.20.3] — 2026-08-03
+
+**Changed — `bclaw_dispatch_status` diagnosis values under the fs-activity veto (#170)**
+- A dead tracked pid combined with FRESH filesystem activity (log/worktree
+  mtime within the activity window) now yields `diagnosis.health: "healthy"`
+  with a "worker is writing" summary — previously this combination could
+  reach the `silent_death` branch and recommend "cancel + reroute" against a
+  live worker. Value change only on `diagnosis.health` /
+  `diagnosis.recommended_next_action` for that evidence combination; no field
+  added/removed, no inputSchema change. Consumers gating on
+  `health === "silent_death"` see strictly FEWER (more accurate) firings.
+- No MCP contract change from pln#644 (#171): the `review_turn_not_converged`
+  warning lives on the CLI harvest surface (`brainclaw harvest` text/`--json`
+  output), not on an MCP tool response.
+
 ## [1.20.2] — 2026-08-03
 
 **Added — `lane_result_stale` on the dispatch_status runtime snapshot (#167)**

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

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

package/docs/playbooks/store-snapshot.md

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

package/package.json

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