brainclaw 1.17.0 → 1.19.0

package/dist/core/schema.js

@@ -479,6 +479,13 @@ export const InboxMessageSchema = z.object({
     read_at: z.string().optional(),
     /** When the message was acknowledged */
     ack_at: z.string().optional(),
+    /** True when the body was truncated at WRITE time because it exceeded the
+     *  inline size cap (pln#627 Phase B). Unlike read-time previews, the omitted
+     *  tail is NOT stored inline — the full artifact belongs in a dedicated store
+     *  (e.g. ideation responses), with the message carrying only a pointer. */
+    truncated_at_write: z.boolean().optional(),
+    /** Original body length in characters before write-time truncation. */
+    original_text_length: z.number().int().nonnegative().optional(),
     created_at: z.string(),
     updated_at: z.string(),
     author: z.string(),
@@ -708,6 +715,28 @@ export const ClaimSchema = z.object({
     assignment_message_id: z.string().optional(),
     /** Assignment ID from the Agent SDK runtime protocol. Links claim to its Assignment lifecycle entity. */
     assignment_id: z.string().optional(),
+    /**
+     * pln#636 C0-b — commit the claim's work started FROM, recorded at creation.
+     *
+     * This is the immutable baseline any "what did this claim actually touch?"
+     * comparison needs. The design review settled the question by rejecting both
+     * options it offered: neither `git diff` against HEAD nor the worktree's dirty
+     * set is authoritative, because a lane that commits mid-work moves the ground
+     * under both. A fixed point recorded up front is the only honest basis.
+     *
+     * Optional and never backfilled: the 613 claims that predate this field simply
+     * have no baseline, and a conformity check must treat that as `unverifiable`
+     * rather than guessing one (see core/claim-scope.ts on the inverted default).
+     */
+    base_sha: z.string().optional(),
+    /**
+     * pln#636 C0-b — file footprint the claim DECLARES, when its creator knows it.
+     *
+     * Raises conformity coverage above what classifying a free-string `scope` can
+     * reach (57.6% of the live corpus is path-resolvable). Purely additive: absent
+     * means "fall back to classifying `scope`", never "no files allowed".
+     */
+    paths: z.array(z.string()).optional(),
 });
 // --- Assignment schemas (Agent SDK runtime protocol) ---
 export const AssignmentStatusSchema = z.enum([
@@ -956,6 +985,9 @@ export const RuntimeEventTypeSchema = z.enum([
     'candidate_harvested',
     'lane_result_harvested',
     'lane_integrated',
+    // pln#521 P4 — a turn-owned loop artifact was harvested + integrated into the loop
+    // by reconcileTurn (observability for the harvest path).
+    'loop_artifact_harvested',
 ]);
 /**
  * pln#526 — LANE-RESULT convention. A dispatched worker writes a single
@@ -964,8 +996,24 @@ export const RuntimeEventTypeSchema = z.enum([
  * environment, e.g. a genuinely MCP-less agent). The coordinator ingests it with
  * `brainclaw harvest <assignment_id>`.
  */
+/**
+ * Largest inline worker body accepted in a LANE-RESULT. This is deliberately
+ * larger than a loop artifact body: harvest persists the original body in its
+ * durable runtime event before a loop closer applies its smaller display cap.
+ */
+export const LANE_RESULT_BODY_MAX_BYTES = 64 * 1024;
 export const LaneResultSchema = z.object({
     assignment_id: z.string(),
+    /**
+     * pln#630 PR2b-a (§13 R2/R3) — turn-attempt correlation keys. Optional for
+     * backward compat (legacy lanes are assignment-keyed only); a loop-dispatched
+     * lane echoes all three so the read-strict acceptance path can prove WHICH
+     * attempt+generation produced this result. `nonce` == the consumed launch
+     * token (the epoch-unique generation id), NOT a turn_id-bound value.
+     */
+    turn_id: z.string().optional(),
+    run_id: z.string().optional(),
+    nonce: z.string().optional(),
     status: z.enum(['completed', 'blocked', 'failed']),
     summary: z.string(),
     /** Paths or refs the worker produced (commits, files, docs). */
@@ -974,6 +1022,18 @@ export const LaneResultSchema = z.object({
     files_changed: z.array(z.string()).optional(),
     /** Free-form notes (blockers, follow-ups). */
     notes: z.string().optional(),
+    /**
+     * Full worker reasoning or review content. Unlike `summary`, this is the
+     * durable handoff payload and is copied into the coordinator-side harvest
+     * event, so it survives worktree cleanup. Optional for legacy workers.
+     */
+    body: z.string().refine((body) => Buffer.byteLength(body, 'utf8') <= LANE_RESULT_BODY_MAX_BYTES, `LANE-RESULT.body must be ≤ ${LANE_RESULT_BODY_MAX_BYTES} bytes`).optional(),
+    /**
+     * Type the worker associated with `body`. Optional because legacy
+     * `artifacts` remains a list of opaque labels/refs. A loop harvester may
+     * reconcile this to its phase's required artifact type.
+     */
+    artifact_type: z.string().min(1).optional(),
     /**
      * pln#628 Focus 4B — review-loop verdict. A worker running a review-loop turn
      * sets this to signal whether the change is good to merge (`approve`) or needs
@@ -999,6 +1059,10 @@ export const RuntimeEventSchema = z.object({
     tags: TagsWithDefaultSchema,
     assignment_id: z.string().optional(),
     run_id: z.string().optional(),
+    // pln#630 PR2b-a (§13 R2/R3) — turn-attempt correlation on runtime signals.
+    // `run_id` already present above; `nonce` == launch-generation token.
+    turn_id: z.string().optional(),
+    nonce: z.string().optional(),
     claim_id: z.string().optional(),
     message_id: z.string().optional(),
     plan_id: z.string().optional(),

package/dist/core/surface-freshness.js

@@ -0,0 +1,150 @@
+/**
+ * pln#638 volet 2b — lazy freshness reconcile for generated guidance surfaces.
+ *
+ * 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
+ * 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
+ * say so, once, at a path we already visit.
+ *
+ * NO DAEMON, NO WATCHER — the validated lazy-reconcile pattern. The check is a
+ * pure comparison plus a directory scan of a registry that already exists
+ * (`AGENT_EXPORT_REGISTRY` / `LIVE_COMPANION_EXPORT_REGISTRY`), so it is DERIVED
+ * rather than enumerated. That is review finding F1 applied here: a hand-kept
+ * list of generated surfaces would itself be an unguarded generated surface, and
+ * would reproduce the exact defect this plan exists to fix.
+ *
+ * ADVISORY, AND SILENT ON DOUBT. A surface with no stamp is not stale — it is
+ * unknown (it may predate the stamp, or be hand-written by the operator). Only a
+ * stamp that PARSES and names a DIFFERENT version is reported. Nothing here
+ * rewrites a file: regeneration stays the explicit act it always was.
+ *
+ * @module
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { AGENT_EXPORT_REGISTRY, LIVE_COMPANION_EXPORT_REGISTRY } from './agent-files.js';
+/**
+ * Matches the provenance line emitted by `renderLiveHeader`
+ * (instruction-templates.ts) and by the protocol-skill front-matter.
+ *
+ * Deliberately tolerant about what follows the version: the timestamp format is
+ * not what this parser is for, and a stricter pattern would go stale the first
+ * time the header gains a field.
+ */
+const PROVENANCE_RE = /Written by brainclaw v(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)/;
+/** `brainclaw_version: X` in a generated SKILL.md front-matter. */
+const SKILL_PROVENANCE_RE = /^\s*brainclaw_version:\s*v?(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)\s*$/m;
+/** Read the provenance stamp out of a generated surface's content. Never throws. */
+export function parseSurfaceProvenance(content) {
+    const header = PROVENANCE_RE.exec(content);
+    if (header?.[1])
+        return { version: header[1] };
+    const skill = SKILL_PROVENANCE_RE.exec(content);
+    if (skill?.[1])
+        return { version: skill[1] };
+    return {};
+}
+/**
+ * Compare one surface's stamp against the running version.
+ *
+ * An UNKNOWN stamp is never reported as stale. Treating "no stamp" as "out of
+ * date" would fire on every hand-written AGENTS.md in every project that ever
+ * adopted brainclaw — the false-positive failure mode that teaches agents to
+ * ignore a channel.
+ */
+export function assessSurfaceFreshness(content, currentVersion) {
+    const { version } = parseSurfaceProvenance(content);
+    if (!version)
+        return { kind: 'unknown', reason: 'no brainclaw provenance stamp' };
+    if (version === currentVersion)
+        return { kind: 'fresh', version };
+    return { kind: 'stale', stampedVersion: version, currentVersion };
+}
+/**
+ * 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).
+ */
+function candidateSurfacePaths() {
+    return [...new Set([
+            ...AGENT_EXPORT_REGISTRY.map((t) => t.relativePath),
+            ...LIVE_COMPANION_EXPORT_REGISTRY.map((t) => t.relativePath),
+        ])];
+}
+/**
+ * Scan the project's generated surfaces and report the ones stamped with a
+ * different brainclaw version.
+ *
+ * Cheap by construction: it only stats/reads files the registries name (~25
+ * paths, most absent in any given project), and reads at most the head of each —
+ * the stamp is in the header, so there is no reason to pull a whole file into
+ * memory. Never throws; an unreadable file is simply not reported.
+ */
+export function reconcileSurfaceFreshness(cwd, currentVersion) {
+    const result = { stale: [], freshCount: 0, unknownCount: 0 };
+    for (const relativePath of candidateSurfacePaths()) {
+        const full = path.join(cwd, relativePath);
+        let head;
+        try {
+            if (!fs.existsSync(full))
+                continue;
+            // The stamp lives in the header; 4KB covers it with room to spare.
+            const fd = fs.openSync(full, 'r');
+            try {
+                const buf = Buffer.alloc(4096);
+                const read = fs.readSync(fd, buf, 0, buf.length, 0);
+                head = buf.subarray(0, read).toString('utf-8');
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        }
+        catch {
+            continue; // unreadable → not reported, never a crash
+        }
+        const verdict = assessSurfaceFreshness(head, currentVersion);
+        if (verdict.kind === 'stale')
+            result.stale.push({ relativePath, stampedVersion: verdict.stampedVersion });
+        else if (verdict.kind === 'fresh')
+            result.freshCount += 1;
+        else
+            result.unknownCount += 1;
+    }
+    return result;
+}
+/**
+ * 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.
+ */
+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;
+    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.',
+        data: {
+            current_version: currentVersion,
+            stale_surfaces: shown.map((s) => ({ path: s.relativePath, stamped_version: s.stampedVersion })),
+            ...(overflow > 0 ? { stale_surfaces_omitted: overflow } : {}),
+            refresh_command: 'brainclaw export --write',
+        },
+    };
+}
+//# sourceMappingURL=surface-freshness.js.map

package/dist/core/warnings.js

@@ -0,0 +1,98 @@
+/**
+ * Codes that historically shipped as a JSON blob keep shipping that exact blob,
+ * so no existing consumer sees a changed string. The set is enumerated rather
+ * than inferred so a NEW code cannot accidentally start emitting JSON at a
+ * consumer that only ever saw prose.
+ */
+const LEGACY_JSON_CODES = new Set([
+    'agent_validation_failed',
+    'plan_already_assigned',
+    'scope_already_claimed',
+]);
+/** Derive the legacy `warnings` string for a structured warning. */
+export function renderLegacyWarning(detail) {
+    if (LEGACY_JSON_CODES.has(detail.code)) {
+        return JSON.stringify({ warning: detail.code, ...(detail.data ?? {}) });
+    }
+    return detail.message;
+}
+/**
+ * Build the structured record without touching any legacy channel.
+ *
+ * Used by surfaces that have NO historical `warnings: string[]` to stay
+ * compatible with — a field introduced already-structured (pln#636 C2's
+ * `LaneHarvestResult.warnings`, for one) should not have to invent a throwaway
+ * string array just to reach this shape.
+ */
+export function toWarningDetail(input) {
+    return {
+        code: input.code,
+        message: input.message,
+        ...(input.data ? { data: input.data } : {}),
+        ...(input.next_actions?.length ? { next_actions: input.next_actions } : {}),
+    };
+}
+/**
+ * Record a structured warning into BOTH channels at once.
+ *
+ * Taking the two arrays as parameters (rather than owning them) is what keeps
+ * this additive: the caller's `warnings: string[]` stays the same object it
+ * already passes by reference to its own helpers.
+ */
+export function pushStructuredWarning(warnings, details, input) {
+    const detail = toWarningDetail(input);
+    details.push(detail);
+    warnings.push(renderLegacyWarning(detail));
+}
+// ── Builders for the migrated sites ─────────────────────────────────────────
+// Each owns its recovery path, which is the entire point of the structured
+// channel: `scope_already_claimed` used to be a dead-end string; now it names
+// the two calls that resolve it.
+export function agentValidationFailedWarning(input) {
+    return {
+        code: 'agent_validation_failed',
+        message: `Agent '${input.agent}' cannot be dispatched to${input.reason ? `: ${input.reason}` : ''}.`,
+        data: { agent: input.agent, code: input.code, reason: input.reason },
+        next_actions: [{
+                tool: 'bclaw_find',
+                args: { entity: 'agent', filter: { scope: 'global' } },
+                when: 'list the dispatchable agents and pick a target that is actually spawnable',
+            }],
+    };
+}
+export function planAlreadyAssignedWarning(input) {
+    return {
+        code: 'plan_already_assigned',
+        message: `'${input.planId}' already has an active assignment for ${input.existingAgent} — this call adds a second one.`,
+        data: { plan_id: input.planId, existing_agent: input.existingAgent },
+        next_actions: [{
+                tool: 'bclaw_find',
+                args: { entity: 'assignment', filter: { agent: input.existingAgent, status: 'offered' } },
+                when: 'inspect the existing assignment before letting two agents work the same scope',
+            }],
+    };
+}
+export function scopeAlreadyClaimedWarning(input) {
+    return {
+        code: 'scope_already_claimed',
+        message: `Scope '${input.scope}' is already claimed by ${input.existingAgent} (${input.existingClaimId}).`,
+        data: {
+            scope: input.scope,
+            existing_agent: input.existingAgent,
+            existing_claim_id: input.existingClaimId,
+        },
+        next_actions: [
+            {
+                tool: 'bclaw_get',
+                args: { entity: 'claim', id: input.existingClaimId },
+                when: 'see who holds the scope and since when before creating a second claim on it',
+            },
+            {
+                tool: 'bclaw_coordinate',
+                args: { intent: 'reroute', task: `Reassign work on ${input.scope}`, scope: input.scope },
+                when: 'hand the existing claim to another agent instead of double-claiming the scope',
+            },
+        ],
+    };
+}
+//# sourceMappingURL=warnings.js.map

package/dist/core/worktree.js

@@ -1360,6 +1360,30 @@ export function isBranchMergedByContent(mainWorktreePath, branchName, baseRef =
     }
     return true;
 }
+/**
+ * True when a LOCAL git branch of this exact name exists (pln#529). Lets the
+ * gated-sequence base selector distinguish "predecessor branch gone (merged +
+ * cleaned → code is on HEAD)" from "branch present but not yet integrated →
+ * fork the dependent lane from it". Returns false on any git failure.
+ */
+export function localBranchExists(mainWorktreePath, branchName) {
+    return probeLocalBranch(mainWorktreePath, branchName) === 'present';
+}
+export function probeLocalBranch(mainWorktreePath, branchName) {
+    const r = runGit(['rev-parse', '--verify', '--quiet', `refs/heads/${branchName}`], mainWorktreePath);
+    if (r.ok)
+        return 'present';
+    return r.stderr.trim() === '' ? 'absent' : 'unknown';
+}
+/**
+ * True when `cwd` is inside a git work tree. pln#529 uses this to distinguish a
+ * NON-git project (where branch/worktree propagation is inapplicable — fall back
+ * to the legacy HEAD base) from a git repo whose branch probe transiently failed
+ * (which must fail SAFE, not silently assume HEAD).
+ */
+export function isGitRepo(cwd) {
+    return runGit(['rev-parse', '--is-inside-work-tree'], cwd).ok;
+}
 /**
  * Removes worktrees whose branch has been fully merged into the current branch
  * (typically master/main after a merge). Also removes brainclaw-managed

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.17.0 on 2026-07-19T20:01:41.172Z
+// Source: brainclaw v1.19.0 on 2026-08-01T21:36:53.526Z
 export const FACTS = {
-  "version": "1.17.0",
-  "generated_at": "2026-07-19T20:01:41.172Z",
+  "version": "1.19.0",
+  "generated_at": "2026-08-01T21:36:53.526Z",
   "tools": {
     "count": 67,
     "published_count": 65,
@@ -474,7 +474,7 @@ export const FACTS = {
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-07-19T20:01:39.038Z",
+    "generated_at": "2026-08-01T21:36:51.459Z",
     "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": 74,
         "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": 135,
+        "duration_ms_median": 124,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },
@@ -499,9 +499,9 @@ 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": 7,
-        "payload_chars_median": 442,
-        "payload_tokens_est_median": 111
+        "duration_ms_median": 14,
+        "payload_chars_median": 499,
+        "payload_tokens_est_median": 125
       }
     ]
   }

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.17.0",
-  "generated_at": "2026-07-19T20:01:41.172Z",
+  "version": "1.19.0",
+  "generated_at": "2026-08-01T21:36:53.526Z",
   "tools": {
     "count": 67,
     "published_count": 65,
@@ -472,7 +472,7 @@
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-07-19T20:01:39.038Z",
+    "generated_at": "2026-08-01T21:36:51.459Z",
     "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": 74,
         "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": 135,
+        "duration_ms_median": 124,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },
@@ -497,9 +497,9 @@
         "name": "first_edit",
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
-        "duration_ms_median": 7,
-        "payload_chars_median": 442,
-        "payload_tokens_est_median": 111
+        "duration_ms_median": 14,
+        "payload_chars_median": 499,
+        "payload_tokens_est_median": 125
       }
     ]
   }

package/docs/cli.md

@@ -2011,7 +2011,7 @@ The default catalog is intentionally small and centred on the canonical grammar.
 |---|---|
 | `bclaw_coordinate(intent)` | Assign, consult, review, reroute, or summarize across agents. Pass `open_loop: true` on `intent="review"` to also dispatch the reviewer turn. |
 | `bclaw_dispatch(intent)` | Parallelize execute across a sequence's lanes (analysis / execute / review). |
-| `bclaw_loop(intent)` | Drive a turn in an existing multi-turn loop (`turn`, `complete_turn`, `advance`, `close`). Do not call `bclaw_loop(intent="open")` directly without dispatch — use `bclaw_coordinate(intent="review", open_loop: true)` instead. |
+| `bclaw_loop(intent)` | Drive a turn in an existing multi-turn loop (`turn`, `complete_turn`, `advance`, `close`; implementation loops add `bind` to dispatch the linked sequence and `verify` to run the opener-configured `command_green` check). Do not call `bclaw_loop(intent="open")` directly without dispatch — use `bclaw_coordinate(intent="review", open_loop: true)` instead. |
 
 **Sequences**:
 

package/docs/code-map.md

@@ -1,7 +1,8 @@
 # Code Map
 
-Code Map is a per-project structural index of your JavaScript / TypeScript / JSX /
-TSX, Python, PHP, and Java codebase. It parses each supported file with Tree-sitter and records the
+Code Map is a per-project structural index of your codebase across 11 languages:
+JavaScript / TypeScript (including JSX / TSX), Python, PHP, Java, Go, Rust, C#,
+Ruby, C, and C++. It parses each supported file with Tree-sitter and records the
 symbols it defines (functions, classes, types, interfaces, React components and
 hooks), what it imports and exports, and how files relate — then answers fast
 "what should I read before I edit this?" questions for both human operators and
@@ -201,11 +202,24 @@ single-project repos ignore the flag entirely.
 which nested projects have a built index vs `missing_index`, plus an aggregate
 count — so you can see workspace-wide freshness from the root.
 
+### Workspace-wide `find` / `brief`
+
+Once the per-child indexes exist (built by `--cascade`), `find` and `brief` run
+at a multi-project workspace **root** automatically aggregate across every child
+project's store — no flag needed. Matches are project-tagged with
+workspace-relative paths, and the freshness badge merges per-store status (worst
+status wins) plus coverage (how many projects are indexed, listing any unindexed
+children). An aggregated `brief` also surfaces **cross-package reverse
+dependents**: sibling packages that import the defining package's public name
+rank into the reading list, flagged `cross_package`.
+
+From **inside** a child project, reads stay single-store by default (locality).
+An explicit `traversal: "workspace"` (backend option) walks up to the nearest
+enclosing multi-project root and aggregates from there, with the caller's own
+package ranked first (`local: true` on its rows).
+
 **Not yet supported** (roadmap):
 
-- A single **federated query** at the root that fans out across the per-child
-  indexes and merges the results (today, `--cascade` builds the per-child indexes;
-  `find` / `brief` still run against one store at a time).
 - **Cross-service edges** — e.g. linking an API call to the route that defines it in
   another service. Code Map indexes language *symbols* and *module imports*, not
   framework routes or runtime HTTP calls, so it does not (today) map "service A calls
@@ -215,7 +229,9 @@ count — so you can see workspace-wide freshness from the root.
 
 The parser is [Tree-sitter](https://tree-sitter.github.io/) compiled to
 WebAssembly. The engine glue (`web-tree-sitter`) and the prebuilt grammar `.wasm`
-files (JavaScript / TypeScript / JSX / TSX, Python, PHP, Java) are **bundled into the package** during the
+files — 12 grammars covering the 11 supported languages: `javascript` (also
+handles JSX), `typescript`, `tsx`, `python`, `php`, `java`, `go`, `rust`,
+`c_sharp`, `ruby`, `c`, `cpp` — are **bundled into the package** during the
 build (`scripts/copy-code-map-wasm.mjs` copies them into `dist/wasm/` and vendors
 the engine glue into `dist/vendor/web-tree-sitter/`).
 

package/docs/concepts/loop-engine.md

@@ -486,6 +486,29 @@ The three rules are independent: `hard_deadline` bounds pathological "heartbeat
 - Execution loops (`implementation`) route by `claim_id` — preserved from the claim-routed model already in use.
 - `session_id` is not a routing key; it remains observability-only. This is consistent with `architecture_session_centric_identity` in memory.
 
+### Project resolution gate (pln#521 P1)
+
+`bclaw_coordinate(intent='review', open_loop=true)` resolves WHICH project the
+loop belongs to before it writes anything. A loop that lands in the wrong store
+persists a candidate, claim, assignment and loop where nobody is watching, and
+spawns the reviewer against the wrong repo.
+
+The ladder, in order: an explicit `project` argument; then any selector that
+already won upstream (`--cwd`, `BRAINCLAW_PROJECT`, a session switch, the
+physical child store, the workspace `active-project.json`); then the bare cwd
+fallback. The fallback is accepted in a single-project store — there is exactly
+one answer — and **refused** with `needs_project_selection` when the store can
+host several projects (`project_mode: multi-project`, or a `store_type: workspace`
+parent with nested project stores). The error lists the candidates and creates
+nothing; fix it by passing `project='<name>'` or by making the choice sticky with
+`bclaw_switch`. Ref, scope and path are never used to guess the project (B3
+rejected in `art_e29e88878209`: a wrong guess costs more than an explicit choice).
+
+Both `bclaw_coordinate` (open_loop reviews) and `bclaw_dispatch_status` echo the
+decision as `project_name` / `project_cwd`. `dispatch_status` additionally carries
+`_resolution_trace` (`source_cwd`, `effective_cwd`, `active_source`, `project_arg`)
+so a misroute can be diagnosed without reverse-engineering cwd and store state.
+
 ## Open questions (resolved / deferred)
 
 Status after Codex schema review (cnd#574 / `dec_be66ccbf`, verdict `needs_revision` → addressed in v8):
@@ -519,6 +542,7 @@ Status after Codex schema review (cnd#574 / `dec_be66ccbf`, verdict `needs_revis
 The loop surface exposed over MCP is intentionally narrow:
 
 - **Review loops** — `bclaw_coordinate(intent="review", open_loop=true, review_mode="asymmetric"|"symmetric", targetAgents=[…])` opens the loop and dispatches the first turn. The reviewer's verdict is then harvested from `LANE-RESULT.json` (`review_verdict`) and **auto-advances/closes the loop on approve** — no manual driving needed for the approve path (pln#628 Focus 4B). `bclaw_loop(intent="turn"|"complete_turn"|"advance"|"close")` remains available to drive turns by hand (e.g. the `request_changes` fix cycle, or a human-operated slot).
+  - **Turn-owned exactly-once fix cycle (default, pln#630).** The autonomous `request_changes` fix-cycle re-dispatch runs through the turn-owned attempt state machine (immutable attempt record + atomic launch fence → spawned at most once; `reconcileTurn` finalizes from read-strict, turn-keyed evidence — the ack-wrapper's completion sentinel). It falls back to the legacy closer when a reviewer resolves to inbox/manual (no sentinel) so the loop still converges. **Kill-switch:** set `BRAINCLAW_TURN_OWNED_REVIEW=0` (also `false`/`off`/`no`) to revert review finalization to the legacy presence-based closer.
 - **Ideation loops** — `bclaw_coordinate(intent="ideate", preset="bootstrap")` opens an ideation loop from a preset.
 
 Custom phase lists (`LoopPhase[]`) and bespoke `StopCondition` logic exist in the loop engine internally, but are **not** exposed through the MCP facade today: `CoordinateRequestSchema` accepts only `open_loop`, `review_mode`, `preflight`, `ref`, and `preset` — no `phases` or `stop_condition` — and the standalone `bclaw_loop` tool does not expose an `open` intent. Programmatic construction of ad-hoc loops is therefore internal / future work until the facade is extended.

package/docs/concepts/observer-protocol.md

@@ -213,6 +213,28 @@ the projection rule).
 > from the seed otherwise. `agents`/`sessions` are never journaled → always seed.
 > A store that has NOT run the supplement keeps the seed (no regression).
 >
+> **Section CONTENT cutover (pln#560 completion):** once `registryAuthoritative()`
+> is set, the registry/coordination sections (ATTENTION, IN_PROGRESS, SPRINTS,
+> and the flat claims/assignments/runs/actions/candidates drill-downs) serve
+> their entity content from the projection too — zero MCP display fetches on
+> expand. The non-journaled extras on the composites (server-computed
+> `workflow_hints`, loops via `bclaw_loop(intent='list')`, and the
+> `bclaw_dispatch_status` evidence digests of §6/§7) remain best-effort reads
+> through the observer-flagged client: when no client resolves, the section
+> still renders its entities. SYSTEM keeps its MCP fetch regardless — it mixes
+> private/machine runtime_notes (never journaled, visibility boundary) and
+> cross-project config, neither derivable from the shared journal.
+>
+> Two parity notes: (a) sections whose MCP fetch pre-filtered `status:
+> 'pending'` server-side (actions, candidates) apply the equivalent pure
+> filter on the projection, because renderers admit broader statuses; (b)
+> journal-served sections are **legacy-inclusive** — the genesis backfill
+> journals `provenance.kind='legacy'` records that the MCP default read
+> filter excludes, and the projection trim drops the nested `provenance`
+> object, so parity with the MCP default is not reconstructable client-side.
+> Accepted deliberately: the operator tree already passes `includeLegacy:
+> true` wherever it fetches explicitly.
+>
 > The historical (pre-pln#568) description below is kept for context.
 
 The journal classifies records into five classes (§2). In phase 1 / `dual`