brainclaw 1.28.1 → 1.28.3

package/dist/core/spawn-check.js

@@ -96,7 +96,15 @@ export async function checkAgentSpawn(agent, options = {}) {
         const stderrRaw = readLogTail(root, assignmentId, 'stderr', 800).trim();
         const stderrTail = stderrRaw ? stderrRaw.split(/\r?\n/).filter(Boolean) : undefined;
         if (completed) {
-            return { agent, binary, status: 'ok', delivered, completed: true, duration_ms, detail: 'ack + completed round-trip' };
+            return {
+                agent,
+                binary,
+                status: 'ok',
+                delivered,
+                completed: true,
+                duration_ms,
+                detail: `validation probe: ack + completed round-trip (${invoke.promptDelivery}, ${invoke.promptText?.length ?? 0} prompt bytes)`,
+            };
         }
         if (failed) {
             const tail = stderrRaw || readLogTail(root, assignmentId, 'stdout', 400).trim();

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.28.1 on 2026-08-24T17:40:07.204Z
+// Source: brainclaw v1.28.3 on 2026-08-25T23:07:33.877Z
 export const FACTS = {
-  "version": "1.28.1",
-  "generated_at": "2026-08-24T17:40:07.204Z",
+  "version": "1.28.3",
+  "generated_at": "2026-08-25T23:07:33.877Z",
   "tools": {
     "count": 70,
     "published_count": 68,
@@ -478,7 +478,7 @@ export const FACTS = {
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-24T17:40:05.036Z",
+    "generated_at": "2026-08-25T23:07:31.792Z",
     "node_version": "v24.19.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -487,7 +487,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": 85,
+        "duration_ms_median": 79,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -495,7 +495,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": 128,
+        "duration_ms_median": 122,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },
@@ -504,8 +504,8 @@ export const FACTS = {
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
         "duration_ms_median": 11,
-        "payload_chars_median": 1305,
-        "payload_tokens_est_median": 326
+        "payload_chars_median": 1629,
+        "payload_tokens_est_median": 407
       }
     ]
   }

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.28.1",
-  "generated_at": "2026-08-24T17:40:07.204Z",
+  "version": "1.28.3",
+  "generated_at": "2026-08-25T23:07:33.877Z",
   "tools": {
     "count": 70,
     "published_count": 68,
@@ -476,7 +476,7 @@
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-24T17:40:05.036Z",
+    "generated_at": "2026-08-25T23:07:31.792Z",
     "node_version": "v24.19.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -485,7 +485,7 @@
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 85,
+        "duration_ms_median": 79,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -493,7 +493,7 @@
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 128,
+        "duration_ms_median": 122,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },
@@ -502,8 +502,8 @@
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
         "duration_ms_median": 11,
-        "payload_chars_median": 1305,
-        "payload_tokens_est_median": 326
+        "payload_chars_median": 1629,
+        "payload_tokens_est_median": 407
       }
     ]
   }

package/docs/cli.md

@@ -639,11 +639,11 @@ Full reference (freshness model, supported languages, WASM bundling): [docs/code
 
 ### `brainclaw code-map status [--cascade]`
 
-Store presence, freshness badge (`fresh` / `stale_changed_files` / `stale_extractor` / `stale_grammar` / `partial` / `missing_index`), and index stats (files, nodes, edges). Read-only. In a multi-project workspace, `--cascade` adds a per-child recap (which nested projects have a built index vs `missing_index`, plus an aggregate count).
+Store presence, freshness badge (`fresh` / `stale_changed_files` / `stale_extractor` / `stale_grammar` / `partial` / `missing_index`), and index stats (files, nodes, edges). Read-only. In a multi-project workspace, `--cascade` adds compact coverage counts and names only non-fresh projects. On the MCP surface, the equivalent `bclaw_code_status(cascade=true)` also follows the latest durable cascade job.
 
 ### `brainclaw code-map refresh [--all|--changed] [--cascade]`
 
-Build or update the index. `--changed` (default) re-parses only touched files; `--all` does a full re-index. Run this when status shows `missing_index` or a stale badge. Fails fast (never blocks) if another writer holds the project lock. In a multi-project workspace, `--cascade` refreshes **every nested project** into its own store plus a root store scoped to the files no child owns (zero double-indexing) — one command at the root indexes the whole monorepo per-project. See [docs/code-map.md](code-map.md#cascading-a-multi-project-workspace---cascade).
+Build or update the index. `--changed` (default) re-parses only touched files; `--all` does a full re-index. Run this when status shows `missing_index` or a stale badge. Fails fast (never blocks) if another writer holds the project lock. In a multi-project workspace, `--cascade` synchronously refreshes each discovered project into its own store plus a root store scoped to files no child owns (zero double-indexing). The MCP equivalent starts a durable background job instead; follow it with `bclaw_code_status(cascade=true)`. See [docs/code-map.md](code-map.md#cascading-a-multi-project-workspace---cascade).
 
 ### `brainclaw code-map find <query> [--limit <n>]`
 

package/docs/code-map.md

@@ -47,6 +47,8 @@ brainclaw code-map status
 ```
 Code Map status
   Store:    present
+  Root:     /workspace/apps/api
+  Path:     /workspace/apps/api/.brainclaw/code
   Freshness: fresh
   Files:    142
   Nodes:    1873
@@ -124,11 +126,11 @@ all return a `freshness_badge`:
 
 | Tool | Kind | Purpose |
 |---|---|---|
-| `bclaw_code_status` | read | Store presence, freshness badge, index stats. Never refreshes. |
+| `bclaw_code_status` | read | Active-session project store, freshness, index stats; `cascade=true` also follows the latest cascade job. Never refreshes. |
 | `bclaw_code_find` | read | Ranked symbol-index search (`query`, optional `limit`). Never refreshes. |
 | `bclaw_code_brief` | read | Reading brief for a symbol/path (`target`, optional `limit`, files capped at 12). Never refreshes. |
 | `bclaw_code_export` | read | Bounded local subgraph around required `target`; direction/depth/node/edge caps, confidence filtering, and optional Mermaid projection. Never refreshes. |
-| `bclaw_code_refresh` | write | Rebuild the index. `scope` = `"changed"` (default) or `"all"`. Fails fast on a live lock. |
+| `bclaw_code_refresh` | write | Rebuild the index. `scope` = `"changed"` (default) or `"all"`; MCP `cascade=true` starts a durable background job and returns immediately. |
 
 The read tools never trigger a parse — if `bclaw_code_status` /
 `bclaw_code_find` / `bclaw_code_brief` report `missing_index` or a stale badge,
@@ -176,7 +178,7 @@ No read command parses files or refreshes the index. `bclaw_work` can suggest
 that explicit refresh, but never performs it lazily.
 ## Lifecycle — pull-based, no daemon
 
-Code Map never runs in the background and never auto-reindexes. The model is lazy
+Code Map never auto-reindexes and has no daemon. The model is lazy
 reconciliation at the read path:
 
 1. You edit or pull code — the index does not change.
@@ -184,7 +186,9 @@ reconciliation at the read path:
    file-hash diff vs the stored shards), so a stale index is always *visible*,
    never silently wrong.
 3. `refresh --changed` re-parses only the changed files (incremental); `--all` does
-   a full rebuild + orphan compaction.
+   a full rebuild + orphan compaction. The one bounded background path is an
+   explicitly requested MCP monorepo cascade, whose durable progress is read
+   through `bclaw_code_status(cascade=true)`.
 4. `bclaw_work` nudges a refresh when the badge is `missing_index` or stale, so an
    agent knows to reconcile before trusting the map.
 
@@ -212,6 +216,14 @@ Code Map to **that child** — the same per-project scoping that powers `bclaw_w
 juggling. A submodule that is itself an application (under e.g. `apps/`) is indexed
 like any other directory.
 
+Both CLI and MCP status responses disclose the exact resolved project root and
+Code Map store path. The MCP response additionally includes `active_source`, the
+resolved project identity, the running server version, and the package version
+visible on disk. In a monorepo, compare these fields before concluding that an
+index is missing: a root store and a child store are intentionally distinct. If
+the versions differ, restart the MCP server; if the roots differ, select the
+intended project/session (or pass `cascade=true` at the workspace root).
+
 ### Cascading a multi-project workspace (`--cascade`)
 
 In a `project_mode: multi-project` workspace, one refresh at the root can index
@@ -230,9 +242,15 @@ double-indexing**, even when projects nest inside one another. `--cascade` is
 opt-in; without it, the root refresh keeps its single-tree behaviour (above), and
 single-project repos ignore the flag entirely.
 
-`status --cascade` (or `bclaw_code_status(cascade=true)`) adds a per-child recap —
-which nested projects have a built index vs `missing_index`, plus an aggregate
-count — so you can see workspace-wide freshness from the root.
+The CLI cascade stays synchronous. MCP `bclaw_code_refresh(cascade=true)` returns
+a durable `job_id` immediately, avoiding the client timeout that a large workspace
+can hit; follow it with `bclaw_code_status(cascade=true)`. Status reports completed
+and total project counts, the project currently being indexed, and terminal
+outcomes. Successful rows are aggregated; only exceptions are named. A project
+with a valid empty index is labeled `no_eligible_files`, while lock contention and
+refresh failures remain distinct (`locked` / `failed`). `discovery_truncated=true`
+warns that the bounded nested-project scan could not inspect deeper branches, so
+the reported project total must not be treated as complete.
 
 ### Workspace-wide `find` / `brief`
 
@@ -240,8 +258,11 @@ 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
+status wins) plus coverage. Missing child stores make the top-line badge
+`partial`, never `fresh`; diagnostics carry status counts and only the non-fresh
+exceptions instead of repeating every project. Weak shared-token candidates that
+do not contain the normalized query are omitted rather than returned as plausible
+score-1/2 noise. 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`.
 

package/docs/concepts/loop-engine.md

@@ -518,6 +518,11 @@ The Loop engine is a **control plane**; existing primitives remain the **data pl
 
 A Loop never copies these objects — it links them. Deleting the linked primitive does not break the loop; the reference just becomes dangling, surfaced in diagnostics.
 
+Inline `LoopArtifact.body` values are capped at **4096 UTF-8 bytes**, not 4096
+characters. Larger task and result text remains available through its source
+object or a `ref`; any inline projection is byte-truncated with an explicit
+`…[truncated]` marker. This contract is identical for review and ideation.
+
 ## Per-protocol guides
 
 Each of the five kinds has its own operator-facing guide with the same

package/docs/integrations/mcp.md

@@ -108,13 +108,13 @@ Each tool also has an `annotations.category` field: `session`, `context`, `memor
 | `bclaw_remove` | memory | Archive or purge a canonical entity |
 | `bclaw_transition` | memory | Move an entity through its validated state machine |
 | `bclaw_move` | memory | Relocate an item to another project, id-preserving (multi-project) |
-| `bclaw_code_status` | discovery | Code Map freshness badge + index stats (store presence, files/nodes/edges) |
+| `bclaw_code_status` | discovery | Active-session Code Map freshness + stats; `cascade:true` follows durable monorepo refresh progress and exceptions |
 | `bclaw_code_find` | discovery | Search the Code Map symbol index by name (function/class/component/hook/type) |
 | `bclaw_code_brief` | discovery | Ranked reading list + related decisions/traps before editing a symbol or path |
 | `bclaw_code_impact` | discovery | Explainable local blast radius from resolved imports: definition, direct dependents, opt-in bounded transitives, tests, and count-based risk |
 | `bclaw_code_export` | discovery | Compact bounded local nodes/edges around one symbol or file; preserves edge kind/source/confidence, with optional Mermaid projection |
 | `bclaw_code_outline` | discovery | Source-ordered symbols of one indexed file (span, exported, confidence) — no reparse |
-| `bclaw_code_refresh` | discovery | Rebuild the Code Map index (`scope: changed \| all`) |
+| `bclaw_code_refresh` | discovery | Rebuild the Code Map index (`scope: changed \| all`); `cascade:true` starts a durable background job |
 
 See [code map](../code-map.md) for the full Code Map reference (CLI, freshness model, supported languages).
 

package/docs/mcp-schema-changelog.md

@@ -8,6 +8,36 @@ guarantees this changelog follows.
 
 ---
 
+## [1.28.3] — 2026-08-26
+
+**Changed — durable Code Map cascade execution**
+
+- `bclaw_code_refresh({ cascade: true })` now returns a durable `job_id`
+  immediately for multi-project workspaces instead of keeping the MCP request
+  open for the whole synchronous cascade.
+- `bclaw_code_status({ cascade: true })` adds the latest job's lifecycle and
+  progress (`queued | running | completed | failed`, project counts and current
+  project), then a bounded terminal summary with outcome counts and problem
+  projects. Discovery truncation and `no_eligible_files`, `locked`, and `failed`
+  outcomes remain explicit.
+- All Code Map MCP tools now resolve against the active session project selected
+  by `bclaw_work` / `bclaw_switch`; this corrects routing behavior without
+  changing their input schemas.
+
+**Added — non-blocking proximity hints on canonical memory creation**
+
+- Successful `bclaw_create` calls for decisions, constraints, and traps may add
+  `nearby_items` (at most three bounded previews with ids and match reasons).
+  The requested creation is never rejected solely because a nearby item exists.
+
+**Changed — admission failures become pre-mutation**
+
+- Unsupported true cross-project auto-execution and empty `stdin_pipe` prompt
+  delivery now fail before claims, assignments, loops, or worker processes are
+  created. Existing successful response shapes and input schemas are unchanged.
+
+No tool was added, removed, or renamed in this release.
+
 ## [1.20.3] — 2026-08-03
 
 **Changed — `bclaw_dispatch_status` diagnosis values under the fs-activity veto (#170)**

package/package.json

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