brainclaw 1.24.0 → 1.25.0

package/dist/core/federation-push.js

@@ -179,16 +179,22 @@ export async function pushPending(options = {}) {
         throw new Error('Adresse du cloud inconnue : passez --url. Elle n\'est pas conservée par l\'appairage ' +
             '(état de connexion sans champ d\'URL), et aucune adresse n\'est devinée.');
     }
+    const pending = list('pending', cwd);
+    // File vide = rien à signer : sortir AVANT de résoudre l'identité. Le signataire est
+    // déduit de la première entrée pending ; le chercher sur une file vide transformait
+    // « tout est déjà parti » en erreur d'identité — vécu le 2026-08-10, juste après un
+    // envoi complet dont il ne restait que des conflits.
+    if (pending.length === 0)
+        return result;
     // L'identité SIGNATAIRE du transport : celle de l'agent qui a produit les enveloppes.
     // Elle est portée par l'entrée d'outbox, donc le transport n'a pas à deviner qui signe.
-    const agentId = options.agentId ?? list('pending', cwd)[0]?.origin_agent_id;
+    const agentId = options.agentId ?? pending[0]?.origin_agent_id;
     const identity = agentId ? loadAgentSigningKey(agentId) : undefined;
     if (!identity) {
         throw new Error('Identité de signature introuvable : le cloud vérifie une signature de TRANSPORT ' +
             'liant envelope_id, rev et base_rev. Sans elle, chaque envoi est refusé en 422.');
     }
     const identityPem = identity.privateKeyPem;
-    const pending = list('pending', cwd);
     const batch = options.limit ? pending.slice(0, options.limit) : pending;
     result.attempted = batch.length;
     if (options.dryRun)
@@ -214,7 +220,14 @@ export async function pushPending(options = {}) {
             // réel en écrasement silencieux du travail d'un autre appareil.
             if (res.status === 409) {
                 const detail = (await res.clone().json().catch(() => ({})));
-                const expected = detail['expected_base_rev'] ?? detail['expected'];
+                // `current_head_rev` est le nom que le serveur DÉPLOYÉ répond (projection.ts,
+                // REV_CONFLICT). Les deux autres sont des noms historiques gardés en repli.
+                // Dérive constatée le 2026-08-10 : le client lisait `expected_base_rev` sur une
+                // réponse qui ne l'a jamais porté — le recalage ne se déclenchait donc JAMAIS et
+                // chaque mise à jour finissait en conflit. Le test unitaire rejoue depuis la
+                // forme de réponse RÉELLE du serveur ; leçon dec#160/162, un contrat inter-
+                // services ne se vérifie que contre le service.
+                const expected = detail['current_head_rev'] ?? detail['expected_base_rev'] ?? detail['expected'];
                 if (typeof expected === 'string' || typeof expected === 'number') {
                     // On RESIGNE avec la nouvelle base_rev : c'est précisément ce que la signature
                     // au niveau du transport rend possible, et qu'une signature figée à l'émission

package/dist/core/protocol-tool-policy.js

@@ -48,6 +48,9 @@ export const MCP_HEADLESS_AUTO_TOOL_NAMES = [
     'bclaw_code_status',
     'bclaw_code_find',
     'bclaw_code_brief',
+    'bclaw_code_impact',
+    'bclaw_code_export',
+    'bclaw_code_outline',
     'bclaw_send_message',
     'bclaw_ack_message',
     'bclaw_write_note',

package/dist/core/worktree.js

@@ -7,6 +7,7 @@ import yaml from 'yaml';
 import { logger } from './logger.js';
 import { loadConfig } from './config.js';
 import { parsePorcelainZ, isSystemDirtyPath } from './dirty-scope.js';
+import { entityRecordDirs } from './io.js';
 /** Normalizes a path for use in git CLI arguments (forward slashes on Windows). */
 function gitPath(p) {
     return p.replace(/\\/g, '/');
@@ -1548,6 +1549,68 @@ export function probeLocalBranch(mainWorktreePath, branchName) {
 export function isGitRepo(cwd) {
     return runGit(['rev-parse', '--is-inside-work-tree'], cwd).ok;
 }
+/**
+ * Comparison key for worktree paths: PHYSICAL identity when the path exists
+ * (realpath expands Windows 8.3 short names — `RUNNER~1` and `runneradmin`
+ * are the same directory but different strings, and git always reports the
+ * long form while a claim may carry the short one), else plain resolution.
+ * Forward slashes, case-folded on win32.
+ */
+function worktreePathKey(p) {
+    let resolved;
+    try {
+        resolved = fs.realpathSync.native(p);
+    }
+    catch {
+        resolved = path.resolve(p);
+    }
+    resolved = resolved.replace(/\\/g, '/').replace(/\/+$/, '');
+    return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+/**
+ * Worktree paths referenced by an ACTIVE, non-expired claim — the set the GC
+ * must never touch.
+ *
+ * Read directly from the claims record dirs (both layouts, pln#649) instead of
+ * claims.ts: claims.ts imports worktree.ts, so the dependency can only point
+ * this way. The parse is deliberately lenient — an unreadable claim simply does
+ * not protect anything; it never blocks the GC of OTHER worktrees.
+ *
+ * Scope note: dispatch claims are project-local, so the project store is the
+ * right authority here; workspace-level claims (cross-project) never carry a
+ * lane worktree_path.
+ */
+function activeClaimWorktreePaths(cwd) {
+    const out = new Set();
+    const now = new Date();
+    for (const dir of entityRecordDirs('claims', cwd)) {
+        let files;
+        try {
+            files = fs.readdirSync(dir).filter((f) => f.endsWith('.json'));
+        }
+        catch {
+            continue;
+        }
+        for (const f of files) {
+            try {
+                const claim = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf-8'));
+                if (claim.status !== 'active')
+                    continue;
+                if (typeof claim.worktree_path !== 'string' || !claim.worktree_path)
+                    continue;
+                // Mirror isClaimExpired: a zombie claim past its expiry must not make a
+                // worktree un-GC-able forever.
+                if (claim.expires_at && new Date(claim.expires_at) < now)
+                    continue;
+                out.add(worktreePathKey(claim.worktree_path));
+            }
+            catch {
+                /* lenient by design — see above */
+            }
+        }
+    }
+    return out;
+}
 /**
  * Removes worktrees whose branch has been fully merged into the current branch
  * (typically master/main after a merge). Also removes brainclaw-managed
@@ -1561,6 +1624,16 @@ export function isGitRepo(cwd) {
  *   - content (`git cherry HEAD <branch>`, patch-id): catches squash merges,
  *     which is GitHub's default merge strategy on this repo and previously left
  *     every squashed lane un-GC-able forever.
+ *
+ * ACTIVE-CLAIM GATE (incident 2026-08-10): a freshly-dispatched lane worktree
+ * has no commits of its own — its branch IS an ancestor of HEAD, so both merged
+ * probes say "merged" — and before the agent's first write it has no uncommitted
+ * changes either. Both historical gates therefore pass during a lane's startup
+ * window, and the post-merge hook destroyed a live codex lane 7 minutes after
+ * spawn (worktree emptied under the running agent). The coordination store is
+ * the authority on liveness: a worktree referenced by an active claim is
+ * untouchable — merged or not, clean or not, force or not. The escape hatch is
+ * releasing the claim, never bypassing it.
  */
 export function cleanMergedWorktrees(mainWorktreePath, options = {}) {
     const result = { removed: [], skipped: [], pruned: false };
@@ -1580,9 +1653,16 @@ export function cleanMergedWorktrees(mainWorktreePath, options = {}) {
             .filter(Boolean)
         : []);
     const worktrees = listWorktrees(mainWorktreePath);
+    const protectedPaths = activeClaimWorktreePaths(mainWorktreePath);
     for (const wt of worktrees) {
         if (wt.is_main)
             continue;
+        // Active-claim gate — see the function doc. Checked BEFORE the merged
+        // probes and BEFORE `force`: a live dispatched lane is never GC-able.
+        if (protectedPaths.has(worktreePathKey(wt.path))) {
+            result.skipped.push({ path: wt.path, reason: 'active claim' });
+            continue;
+        }
         // trp#926 — a lane's branch is "merged" if EITHER git says its commits are
         // ancestors of HEAD (fast-forward / merge-commit) OR every commit's patch
         // is already on HEAD (squash-merge, catching GitHub's default strategy).
@@ -1621,7 +1701,7 @@ export function cleanMergedWorktrees(mainWorktreePath, options = {}) {
         }
     }
     // Clean orphan brainclaw worktree directories (no matching git worktree)
-    cleanOrphanWorktreeDirs(mainWorktreePath, worktrees, result, options.dryRun);
+    cleanOrphanWorktreeDirs(mainWorktreePath, worktrees, result, options.dryRun, protectedPaths);
     return result;
 }
 /** A worker whose heartbeat file was touched within this window looks alive. */
@@ -1722,7 +1802,7 @@ export function gcWorktreeIfHarvested(mainWorktreePath, worktreePath, options =
  * Removes brainclaw-managed worktree directories under ~/.brainclaw/worktrees/
  * that no longer have a corresponding git worktree entry.
  */
-function cleanOrphanWorktreeDirs(mainWorktreePath, activeWorktrees, result, dryRun) {
+function cleanOrphanWorktreeDirs(mainWorktreePath, activeWorktrees, result, dryRun, protectedPaths = new Set()) {
     const base = worktreesBaseDir(mainWorktreePath);
     if (!fs.existsSync(base))
         return;
@@ -1740,6 +1820,13 @@ function cleanOrphanWorktreeDirs(mainWorktreePath, activeWorktrees, result, dryR
         const dirPath = path.resolve(path.join(base, entry.name));
         if (activePaths.has(dirPath))
             continue;
+        // Active-claim gate: a dir whose git admin entry vanished can still host a
+        // LIVE agent (the 2026-08-10 incident left exactly this state behind). If a
+        // claim still points here, it is not debris.
+        if (protectedPaths.has(worktreePathKey(dirPath))) {
+            result.skipped.push({ path: dirPath, reason: 'active claim' });
+            continue;
+        }
         // This directory is not referenced by any git worktree — it's orphaned
         if (dryRun) {
             result.removed.push(dirPath);

package/dist/facts.js

@@ -1,11 +1,11 @@
 // Generated by scripts/emit-site-facts.mjs at build time. Do not edit manually.
-// Source: brainclaw v1.24.0 on 2026-08-10T18:03:29.240Z
+// Source: brainclaw v1.25.0 on 2026-08-10T23:31:26.947Z
 export const FACTS = {
-  "version": "1.24.0",
-  "generated_at": "2026-08-10T18:03:29.240Z",
+  "version": "1.25.0",
+  "generated_at": "2026-08-10T23:31:26.947Z",
   "tools": {
-    "count": 67,
-    "published_count": 65,
+    "count": 70,
+    "published_count": 68,
     "names": [
       "bclaw_bootstrap",
       "bclaw_release_notes",
@@ -34,6 +34,9 @@ export const FACTS = {
       "bclaw_code_status",
       "bclaw_code_find",
       "bclaw_code_brief",
+      "bclaw_code_impact",
+      "bclaw_code_export",
+      "bclaw_code_outline",
       "bclaw_code_refresh",
       "bclaw_dispatch",
       "bclaw_send_message",
@@ -474,7 +477,7 @@ export const FACTS = {
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-10T18:03:27.087Z",
+    "generated_at": "2026-08-10T23:31:25.464Z",
     "node_version": "v24.18.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -483,7 +486,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": 71,
+        "duration_ms_median": 59,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -491,9 +494,9 @@ 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": 107,
-        "payload_chars_median": 2626,
-        "payload_tokens_est_median": 657
+        "duration_ms_median": 88,
+        "payload_chars_median": 2625,
+        "payload_tokens_est_median": 656
       },
       {
         "name": "first_edit",

package/dist/facts.json

@@ -1,9 +1,9 @@
 {
-  "version": "1.24.0",
-  "generated_at": "2026-08-10T18:03:29.240Z",
+  "version": "1.25.0",
+  "generated_at": "2026-08-10T23:31:26.947Z",
   "tools": {
-    "count": 67,
-    "published_count": 65,
+    "count": 70,
+    "published_count": 68,
     "names": [
       "bclaw_bootstrap",
       "bclaw_release_notes",
@@ -32,6 +32,9 @@
       "bclaw_code_status",
       "bclaw_code_find",
       "bclaw_code_brief",
+      "bclaw_code_impact",
+      "bclaw_code_export",
+      "bclaw_code_outline",
       "bclaw_code_refresh",
       "bclaw_dispatch",
       "bclaw_send_message",
@@ -472,7 +475,7 @@
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-10T18:03:27.087Z",
+    "generated_at": "2026-08-10T23:31:25.464Z",
     "node_version": "v24.18.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -481,7 +484,7 @@
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 71,
+        "duration_ms_median": 59,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -489,9 +492,9 @@
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 107,
-        "payload_chars_median": 2626,
-        "payload_tokens_est_median": 657
+        "duration_ms_median": 88,
+        "payload_chars_median": 2625,
+        "payload_tokens_est_median": 656
       },
       {
         "name": "first_edit",

package/docs/cli.md

@@ -652,6 +652,14 @@ Search the symbol index by name (function / class / component / hook / type). Re
 ### `brainclaw code-map brief <target> [--limit <n>]`
 
 Given a symbol or path, return a ranked reading list (`suggested_files_to_read`) plus related memory (decisions/traps/constraints) — what to read before editing.
+### `brainclaw code-map export <symbol-or-path> [--direction outgoing|incoming|both]`
+
+Export a compact **local** Code Map subgraph around one symbol or file. The default
+is one hop in both directions; hard caps always apply (depth 4, 100 nodes, 200
+edges), so the command never defaults to a whole-graph export. `--max-nodes`,
+`--max-edges`, and `--depth` only tighten the result; `--min-confidence` has a
+hard floor of 0.5. JSON keeps each edge's `kind`, `source`, and `confidence`.
+Use `--format mermaid` for a diagram projected from that same JSON model.
 
 ```bash
 brainclaw code-map refresh --all

package/docs/code-map.md

@@ -24,6 +24,7 @@ rebuilds it.
   brainclaw memory.
 - **To locate** a function/class/component/hook by name without grepping:
   `code-map find <query>` (or `bclaw_code_find`).
+- **To inspect a bounded local dependency neighborhood**: `code-map export <symbol-or-path>` (or `bclaw_code_export`) returns compact nodes and edges, not a repository graph dump.
 - **To check coverage / staleness**: `code-map status` (or `bclaw_code_status`).
 - **After pulling changes or doing work**: `code-map refresh` to bring the index
   back to `fresh`.
@@ -95,9 +96,30 @@ Read-only. Builds a reading brief for a symbol or file: a ranked
 brainclaw code-map brief App
 ```
 
+### `brainclaw code-map export <symbol-or-path>`
+
+Read-only export of a **local** persisted subgraph around one symbol or file. It
+never refreshes, reparses, calls a service, or silently turns into a whole-project
+graph export. The default is one hop in both directions; limits are always
+reported and hard-capped at depth 4, 100 nodes, and 200 edges.
+
+```bash
+brainclaw code-map export useAuth --direction incoming --depth 2 --json
+brainclaw code-map export src/hooks/useAuth.ts --format mermaid
+```
+
+`--direction` is `outgoing`, `incoming`, or `both` (default). `--max-nodes` and
+`--max-edges` can tighten the response only; `--min-confidence` cannot be set
+below 0.5. JSON is canonical and includes compact `nodes`, `edges`, root IDs,
+limits, truncation flags, and a freshness badge. Every edge retains `kind`,
+`source`, and `confidence`; low-confidence nodes/relations are excluded so an
+extraction heuristic cannot appear indistinguishable from a high-confidence
+relation. `--format mermaid` adds a Mermaid rendering projected from those exact
+JSON nodes and edges—never from a second traversal.
+
 ## MCP tools
 
-Capable agents should prefer the MCP surface. The four tools mirror the CLI and
+Capable agents should prefer the MCP surface. The read tools mirror the CLI and
 all return a `freshness_badge`:
 
 | Tool | Kind | Purpose |
@@ -105,6 +127,7 @@ all return a `freshness_badge`:
 | `bclaw_code_status` | read | Store presence, freshness badge, index stats. 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. |
 
 The read tools never trigger a parse — if `bclaw_code_status` /

package/docs/integrations/mcp.md

@@ -25,7 +25,7 @@ The default dynamic workflow is:
 1. `bclaw_work` to start the session and load the relevant context in one call (returns compact payload by default — pass `compact: false` for the full context result)
 2. `bclaw_context({ kind: "execution" })` early when the agent needs local tooling signals or package update visibility
 3. `bclaw_context({ kind: "memory" })`, `bclaw_context({ kind: "board" })`, or `bclaw_context({ kind: "delta" })` when the target path changes or full memory is needed beyond the compact summary
-4. `bclaw_code_brief({ target })` / `bclaw_code_find({ query })` before editing unfamiliar code — get a ranked reading list (with related decisions/traps) and locate symbols from the Code Map instead of grepping blind. A `missing_index` badge means run `bclaw_code_refresh` first. See [code map](../code-map.md)
+4. `bclaw_code_brief({ target })` / `bclaw_code_find({ query })` before editing unfamiliar code — get a ranked reading list (with related decisions/traps) and locate symbols from the Code Map instead of grepping blind. Use `bclaw_code_impact({ target, depth: 2 })` when you need an explainable local blast radius; its `tests_for` separates resolved imports from low-confidence filename suggestions. Use `bclaw_code_export({ target, direction, depth, maxNodes, maxEdges })` when you need a compact bounded subgraph; every returned edge keeps `kind`, `source`, and `confidence`, and `format: 'mermaid'` is projected from that same JSON model. A `missing_index` badge means run `bclaw_code_refresh` first. See [code map](../code-map.md)
 5. `bclaw_find` / `bclaw_get` / `bclaw_create` / `bclaw_update` / `bclaw_remove` / `bclaw_transition` for entity reads and writes
 6. `bclaw_coordinate`, `bclaw_dispatch`, or `bclaw_loop` for assign, consult, review, reroute, summarize, dispatch, or multi-turn loop flows
 7. `bclaw_read_inbox` when resuming delegated work
@@ -47,7 +47,7 @@ Every tool has one of three tiers in its `annotations.tier` field:
 - **standard** — Day-to-day coordination tools: plans, claims, messaging, sequences, dispatch, review, memory. Returned by default alongside facades.
 - **advanced** — Specialized governance, audit, registry, and power tools.
 
-By default, `tools/list` returns **facade + standard** tools (46 tools). To get all tools including advanced, pass `{ "catalog": "all" }`, `{ "include": "all" }`, or `{ "advanced": true }`. To filter by a single tier, pass `{ "tier": "facade" }`, `{ "tier": "standard" }`, or `{ "tier": "advanced" }`.
+By default, `tools/list` returns **facade + standard** tools (49 tools). To get all tools including advanced, pass `{ "catalog": "all" }`, `{ "include": "all" }`, or `{ "advanced": true }`. To filter by a single tier, pass `{ "tier": "facade" }`, `{ "tier": "standard" }`, or `{ "tier": "advanced" }`.
 
 Published tools remain callable regardless of catalog filtering — the tier only affects discovery via `tools/list`.
 
@@ -111,6 +111,9 @@ Each tool also has an `annotations.category` field: `session`, `context`, `memor
 | `bclaw_code_status` | discovery | Code Map freshness badge + index stats (store presence, files/nodes/edges) |
 | `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`) |
 
 See [code map](../code-map.md) for the full Code Map reference (CLI, freshness model, supported languages).

package/docs/mcp-schema-changelog.md

@@ -408,7 +408,17 @@ will still succeed. A follow-up PR will strip the dead handler code.
   changelog records the published MCP surface fingerprint. When a tool
   name, tier, category, or input schema changes, the test fails until
   this section is updated.
-- MCP public surface fingerprint: `sha256:8241fa50b8cb4805`
+- MCP public surface fingerprint: `sha256:b8dbb80bae8f6e36`
+  (updated 2026-08-10 for pln#665: `bclaw_code_export` — additive Tier-B read tool for a required, bounded local Code Map subgraph. Its target, direction, depth, node/edge caps, confidence threshold, and optional Mermaid projection are explicit; JSON retains each relation's kind/source/confidence and never defaults to a whole-graph export.)
+  Previous: `sha256:9ed35ed6cc49ea9a`
+  (updated 2026-08-10 for pln#661: `bclaw_code_impact` — additive Tier-B read tool
+  for local, resolved-import impact analysis. It exposes definition, direct causes,
+  optional bounded transitives, tests, and a count-based risk score; its required
+  `target` plus optional `depth` and `limit` input surface are explicitly bounded.)
+  Previous: `sha256:2a9f7d4cd72609df`
+  (updated 2026-08-10 for pln#660: `bclaw_code_outline` — new Tier-B read tool,
+  source-ordered symbols of one indexed file from the existing shard; no reparse,
+  no mutation, bounded output. Purely additive.)
   (updated 2026-07-25 for pln#632: `bclaw_loop` gains the `bind` intent — an
   implementation loop dispatches its linked sequence and advances bind→execute — plus
   its typed inputSchema properties `dry_run`, `lanes`, `auto_execute`, `model`, and

package/package.json

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