brainclaw 1.9.1 → 1.10.1

package/README.md

@@ -6,6 +6,15 @@
 
 <p align="center"><strong>Local-first coordination and shared memory for coding agents.</strong></p>
 
+<p align="center">
+  <a href="https://github.com/jberdah/brainclaw/actions/workflows/ci.yml"><img src="https://github.com/jberdah/brainclaw/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/brainclaw"><img src="https://img.shields.io/npm/v/brainclaw?logo=npm" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/brainclaw"><img src="https://img.shields.io/npm/dm/brainclaw" alt="npm downloads"></a>
+  <img src="https://img.shields.io/node/v/brainclaw" alt="node version">
+  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/brainclaw" alt="MIT license"></a>
+  <img src="https://img.shields.io/badge/MCP-stdio-blue" alt="MCP">
+</p>
+
 ---
 
 If you've ever:
@@ -35,6 +44,7 @@ It sits alongside your coding agents and gives them a shared state layer they ca
 | **Project memory**               | constraints, decisions, traps, handoffs, and layered instructions agents can resume from                                                                                                            |
 | **Coordination state**           | shared plans, file claims (dispatched work isolated in Git Worktrees), runtime notes, and board views for active work                                                                                                 |
 | **Agent-ready context**          | compact, prompt-sized context built from real workspace state instead of stale instructions                                                                                                         |
+| **Code Map**                     | a Tree-sitter symbol + import index (JS/TS, Python, PHP, Java) so agents ask "where is X / what should I read first" before editing, with related decisions/traps attached — `bclaw_code_find` / `bclaw_code_brief`, see [code map](docs/code-map.md) |
 | **Native agent files**           | auto-writes `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursor/rules/`, `.windsurfrules`, and similar local guidance                                                                         |
 | **Multi-turn loops**             | review and ideation loops with structured phases, iteration semantics, and per-phase memory filters — see[loop engine](docs/concepts/loop-engine.md) and [ideation loop](docs/concepts/ideation-loop.md) |
 | **Machine AI surface discovery** | detects local coding agents plus desktop AI work surfaces such as ChatGPT Desktop and Gemini CLI                                                                                                    |
@@ -43,6 +53,19 @@ It sits alongside your coding agents and gives them a shared state layer they ca
 
 ---
 
+## Code Map
+
+When an agent (or you) is about to edit unfamiliar code, the first question is *"where is this, and what should I read first?"* Code Map answers it without grepping: a per-project [Tree-sitter](https://tree-sitter.github.io/) index of the symbols each file defines (functions, classes, types, React components/hooks), what it imports/exports, and how files relate — across **JS / TS / TSX, Python, PHP, and Java**.
+
+```bash
+brainclaw code-map find useAuth        # locate a symbol / component / hook by name
+brainclaw code-map brief src/App.tsx   # ranked "read these first" list + related decisions/traps
+```
+
+Capable agents use the MCP equivalents `bclaw_code_find` / `bclaw_code_brief`, each carrying a freshness badge. Code Map is a **discovery aid, not a build artifact**: it never changes your code, never blocks `bclaw_work`, and degrades gracefully — a stale or missing index says so instead of answering wrong. Pull-based (no daemon) and monorepo-aware. Full guide: **[Code Map](docs/code-map.md)**.
+
+---
+
 ## Agent Surfaces
 
 brainclaw exposes the same collaboration state through three surfaces, but they do not have the same role in an agent-first workflow.
@@ -97,7 +120,7 @@ brainclaw is most effective today when one agent works at a time in a given chec
 
 ## Platform Support
 
-brainclaw declares support for Node.js 20+ in `package.json` (`engines.node = ">=20.0.0"`). CI actively exercises Node 22 (Active LTS) and Node 24 (current LTS) on Linux; Windows runs on Node 24. Node 20 still works as a minimum runtime but is no longer CI-verified — it reached EOL in April 2026 and was removed from GitHub-hosted runners. The recommended runtime is Node 22 LTS or Node 24 LTS. Real-world support is still not perfectly even yet.
+brainclaw requires Node.js 22.12+ (`engines.node = ">=22.12.0"`). CI exercises Node 22 (Active LTS) and Node 24 (current LTS) on Linux; Windows runs on Node 24. Node 20 reached EOL in April 2026 and is no longer supported — the commander 15 upgrade requires Node ≥22.12. The recommended runtime is Node 22 LTS or Node 24 LTS.
 
 | Logo                                                                                                                                            | Platform                                                          | Status today              | Notes                                                                                                                    |
 | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
@@ -346,33 +369,34 @@ The same surface is available through the canonical grammar for agents: `bclaw_c
 
 ## Documentation
 
-The npm package includes the Markdown docs below under `docs/`. Public web docs on `brainclaw.dev` are still being rolled out, so the npm README does not depend on private GitHub links.
+The Markdown docs below ship in the npm package under `docs/` and are versioned in the repo. The links resolve on GitHub and are rewritten to the package repo on the npm page.
 
 If you are integrating Brainclaw into an agent workflow, start with the agent-facing docs first:
 
-|                                            |                                                                                               |
-| ------------------------------------------ | --------------------------------------------------------------------------------------------- |
-| `docs/index.md`                          | Documentation index grouped by getting started, guides, reference, and design                 |
-| `docs/integrations/overview.md`          | Start here for agent integrations                                                             |
-| `docs/integrations/mcp.md`               | MCP runtime path for capable agents                                                           |
-| `docs/quickstart.md`                     | First-time setup on a new project (greenfield)                                                |
-| `docs/quickstart-existing-project.md`    | Joining a project that already has `.brainclaw/`                                            |
-| `docs/server-operations.md`              | Operator and remote-server workflow guide                                                     |
-| `docs/cli.md`                            | CLI reference for operators, scripts, and fallback use                                        |
-| `docs/concepts/memory.md`                | What "memory" means in brainclaw                                                              |
-| `docs/concepts/plans-and-claims.md`      | Coordination layer                                                                            |
-| `docs/concepts/runtime-notes.md`         | Ephemeral observations                                                                        |
-| `docs/concepts/multi-agent-workflows.md` | The four common scenarios — orchestration, agent switching, project recovery, team async     |
-| `docs/concepts/troubleshooting.md`       | Runbook for degraded coordination state — stale claims, missing dist, octopus failures, etc. |
-| `docs/integrations/cursor.md`            | Cursor                                                                                        |
-| `docs/integrations/claude-code.md`       | Claude Code                                                                                   |
-| `docs/integrations/copilot.md`           | GitHub Copilot                                                                                |
-| `docs/integrations/codex.md`             | Codex                                                                                         |
-| `docs/storage.md`                        | Storage model                                                                                 |
-| `docs/security.md`                       | Security model                                                                                |
-| `docs/review.md`                         | Reflective review                                                                             |
-| `docs/reputation.md`                     | Reputation signals                                                                            |
-| `docs/playbooks/`                        | Audience design constraints for brainclaw development                                         |
+| Doc | What it covers |
+| --- | --- |
+| [docs/index.md](docs/index.md) | Documentation index grouped by getting started, guides, reference, and design |
+| [docs/integrations/overview.md](docs/integrations/overview.md) | Start here for agent integrations |
+| [docs/integrations/mcp.md](docs/integrations/mcp.md) | MCP runtime path for capable agents |
+| [docs/quickstart.md](docs/quickstart.md) | First-time setup on a new project (greenfield) |
+| [docs/quickstart-existing-project.md](docs/quickstart-existing-project.md) | Joining a project that already has `.brainclaw/` |
+| [docs/server-operations.md](docs/server-operations.md) | Operator and remote-server workflow guide |
+| [docs/cli.md](docs/cli.md) | CLI reference for operators, scripts, and fallback use |
+| [docs/code-map.md](docs/code-map.md) | Code Map — symbol/import index, freshness model, monorepo behavior |
+| [docs/concepts/memory.md](docs/concepts/memory.md) | What "memory" means in brainclaw |
+| [docs/concepts/plans-and-claims.md](docs/concepts/plans-and-claims.md) | Coordination layer |
+| [docs/concepts/runtime-notes.md](docs/concepts/runtime-notes.md) | Ephemeral observations |
+| [docs/concepts/multi-agent-workflows.md](docs/concepts/multi-agent-workflows.md) | The four common scenarios — orchestration, agent switching, project recovery, team async |
+| [docs/concepts/troubleshooting.md](docs/concepts/troubleshooting.md) | Runbook for degraded coordination state — stale claims, missing dist, octopus failures, etc. |
+| [docs/integrations/cursor.md](docs/integrations/cursor.md) | Cursor |
+| [docs/integrations/claude-code.md](docs/integrations/claude-code.md) | Claude Code |
+| [docs/integrations/copilot.md](docs/integrations/copilot.md) | GitHub Copilot |
+| [docs/integrations/codex.md](docs/integrations/codex.md) | Codex |
+| [docs/storage.md](docs/storage.md) | Storage model |
+| [docs/security.md](docs/security.md) | Security model |
+| [docs/review.md](docs/review.md) | Reflective review |
+| [docs/reputation.md](docs/reputation.md) | Reputation signals |
+| [docs/playbooks/](docs/playbooks/) | Audience design constraints for brainclaw development |
 
 ---
 
@@ -393,6 +417,35 @@ npm run test:coverage      # with coverage report
 
 For older releases (v0.x and the early v1.0 launch series), `git log` on `master` is the source of truth — every release commit follows the `chore(release): bump version to <semver>` convention, and the matching feature/fix commits reference their plan id (e.g. `feat(mcp): self-heal ... (pln#478)`).
 
+### v1.10.1
+
+Code Map fast-follows from the 1.10.0 dogfood, plus a lint cleanup:
+
+- A git branch switch now flags the index stale (new `stale_git_head` freshness reason); `refresh` honors `.gitignore` (gitignored output dirs no longer indexed); `brief("<path>")` resolves the exact file instead of token-flooding; and the freshness badge distinguishes index freshness from a call's spot-check (`index_status`).
+- The `brainclaw-session` skill + agent instruction surface now point agents at `bclaw_code_find` / `bclaw_code_brief` before grep. Lint baseline cleared to zero (stylistic rules ratcheted to `error`); README doc links clickable; `docs/code-map.md` lists JS / TS / JSX / TSX · Python · PHP · Java.
+
+### v1.10.0
+
+- **Code Map** — a new per-project [Tree-sitter](docs/code-map.md) symbol + import
+  index for **JS / TS / TSX, Python, PHP, and Java**. Ask *"where is X / what should I
+  read first"* before editing: `bclaw_code_find`, `bclaw_code_brief`,
+  `bclaw_code_status`, `bclaw_code_refresh` (CLI: `brainclaw code-map …`). Pull-based
+  freshness with a per-response badge; never blocks `bclaw_work`; monorepo-aware. See
+  [code map](docs/code-map.md).
+- **Monorepo multi-project safety** — agents working in different child projects of a
+  monorepo are now genuinely independent:
+  - an anchored agent working *inside* a child project resolves **that** child, not the
+    repo root — no more "plans / index target the repo root";
+  - CLI `brainclaw switch` is **session-scoped by default** (two agents no longer clobber
+    a shared pointer); the new `--global` flag is the only path that sets the shared
+    workspace default; `switch --list` / show are session-aware;
+  - a session-less agent physically inside a child project beats a stale shared global
+    pointer (resolves the child it is in);
+  - dispatched / CoDev workers spawn with a **clean identity** — the coordinator's
+    session / project / agent env no longer leaks into a worker.
+- Internal — MCP public surface fingerprint re-pinned for the Code Map tools (additive;
+  no tool removed or renamed).
+
 ### v1.9.1
 
 - **Multi-project scoping fixes for monorepos** — MCP reads/writes resolve the

package/dist/cli.js

@@ -19,6 +19,7 @@ import { runListPlans } from './commands/list-plans.js';
 import { runUpdatePlan } from './commands/update-plan.js';
 import { runDeletePlan } from './commands/delete-plan.js';
 import { runPlanResource } from './commands/plan-resource.js';
+import { runCodeMap } from './commands/code-map.js';
 import { runSequenceResource } from './commands/sequence.js';
 import { runAddStep } from './commands/add-step.js';
 import { runDeleteStep } from './commands/delete-step.js';
@@ -598,6 +599,20 @@ program
     .action((subcommand, args, options) => {
     runPlanResource(subcommand, args, { ...options, actualEffort: options.actualEffort, localOnly: options.localOnly });
 });
+// --- code-map ---
+program
+    .command('code-map <subcommand> [args...]')
+    .description('Query the per-project Code Map (status, refresh, find, brief)')
+    .option('--json', 'Output as JSON')
+    .option('--all', 'For refresh: enumerate all supported files (full refresh)')
+    .option('--changed', 'For refresh: only changed files (default)')
+    .option('--limit <n>', 'Max results for find/brief', (v) => parseInt(v, 10))
+    .action((subcommand, args, options) => {
+    void runCodeMap(subcommand, args, options).catch((err) => {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    });
+});
 // --- list-plans ---
 program
     .command('list-plans')
@@ -1806,15 +1821,17 @@ program
 });
 program
     .command('switch [project]')
-    .description('Set the active project for subsequent commands')
+    .description('Set the active project for subsequent commands (session-scoped by default)')
     .option('--list', 'List available projects in the workspace')
     .option('--clear', 'Clear the active project (revert to cwd)')
+    .option('--global', 'Set/clear the SHARED workspace default for ALL agents (writes active-project.json). Without it, switch is session-scoped and isolated.')
     .option('--json', 'Output as JSON')
     .action((project, options) => {
     const globalOpts = options.parent?.parent ? program.opts() : {};
     runSwitch(project, {
         list: options.list,
         clear: options.clear,
+        global: options.global,
         json: options.json,
         cwd: globalOpts.cwd,
     });

package/dist/commands/code-map.js

@@ -0,0 +1,129 @@
+/**
+ * `brainclaw code-map <subcommand>` — CLI surface over the Code Map backend
+ * (spec §9). Mirrors plan-resource.ts: a switch over the subcommand delegating
+ * to a JsonlBackend (status | refresh | find | brief). The backend owns all
+ * query logic; this file only adapts it to argv + stdout (text or --json), and
+ * every output carries the freshness_badge.
+ */
+import { JsonlBackend } from '../core/code-map/backend.js';
+const KNOWN_SUBCOMMANDS = new Set(['status', 'refresh', 'find', 'brief']);
+function backend() {
+    return new JsonlBackend();
+}
+function badgeLine(badge) {
+    const detailKeys = Object.keys(badge.details ?? {}).filter((k) => badge.details[k] !== null && badge.details[k] !== undefined);
+    const detail = detailKeys.length
+        ? ` (${detailKeys.map((k) => `${k}=${JSON.stringify(badge.details[k])}`).join(', ')})`
+        : '';
+    return `Freshness: ${badge.status}${detail}`;
+}
+export async function runCodeMap(subcommand, args, options = {}) {
+    const normalized = (subcommand ?? '').trim().toLowerCase();
+    const be = backend();
+    const cwd = options.cwd;
+    if (normalized === 'status') {
+        const status = await be.status({ cwd });
+        printStatus(status, options);
+        return;
+    }
+    if (normalized === 'refresh') {
+        const scope = options.all ? 'all' : 'changed';
+        const result = await be.refresh({ scope, cwd });
+        printRefresh(result, options);
+        return;
+    }
+    if (normalized === 'find') {
+        const query = args.join(' ').trim();
+        if (!query) {
+            console.error('Error: code-map find requires <query>.');
+            console.error('  Usage: brainclaw code-map find <query>');
+            process.exit(1);
+        }
+        const result = await be.find({ query, limit: options.limit, cwd });
+        printFind(result, options);
+        return;
+    }
+    if (normalized === 'brief') {
+        const target = args.join(' ').trim();
+        if (!target) {
+            console.error('Error: code-map brief requires <symbol-or-path>.');
+            console.error('  Usage: brainclaw code-map brief <symbol-or-path>');
+            process.exit(1);
+        }
+        const result = await be.brief({ target, limit: options.limit, cwd });
+        printBrief(result, options);
+        return;
+    }
+    console.error(`Error: unknown code-map subcommand "${subcommand}".`);
+    console.error(`  Available: ${[...KNOWN_SUBCOMMANDS].join(', ')}`);
+    process.exit(1);
+}
+function printStatus(status, options) {
+    if (options.json) {
+        console.log(JSON.stringify(status, null, 2));
+        return;
+    }
+    console.log('Code Map status');
+    console.log(`  Store:    ${status.store_exists ? 'present' : 'absent'}`);
+    console.log(`  ${badgeLine(status.freshness_badge)}`);
+    if (status.stats) {
+        console.log(`  Files:    ${status.stats.files_indexed}`);
+        console.log(`  Nodes:    ${status.stats.nodes}`);
+        console.log(`  Edges:    ${status.stats.edges}`);
+    }
+    else {
+        console.log('  Stats:    (none — index not built)');
+    }
+}
+function printRefresh(result, options) {
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(`Code Map refresh [${result.scope}]`);
+    console.log(`  Ran:      ${result.ran}`);
+    console.log(`  Lock:     ${result.lock_acquired ? 'acquired' : 'not acquired'}`);
+    if (result.lock_status)
+        console.log(`  Status:   ${result.lock_status}`);
+    console.log(`  ${badgeLine(result.freshness_badge)}`);
+}
+function printFind(result, options) {
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(`Code Map find: "${result.query}"`);
+    console.log(`  ${badgeLine(result.freshness_badge)}`);
+    if (result.matches.length === 0) {
+        console.log('  (no matches)');
+        return;
+    }
+    for (const m of result.matches) {
+        const sub = m.subtype ? ` ${m.subtype}` : '';
+        console.log(`  [${m.score.toFixed(1)}] ${m.name}${sub} — ${m.path}`);
+    }
+}
+function printBrief(result, options) {
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(`Code Map brief: "${result.target}"`);
+    console.log(`  ${badgeLine(result.freshness_badge)}`);
+    if (result.suggested_files_to_read.length === 0) {
+        console.log('  Suggested files: (none)');
+    }
+    else {
+        console.log('  Suggested files to read:');
+        for (const f of result.suggested_files_to_read) {
+            console.log(`    [${f.score.toFixed(1)}] ${f.path} — ${f.reason}`);
+        }
+    }
+    if (result.related_memory.length > 0) {
+        console.log('  Related memory:');
+        for (const mem of result.related_memory) {
+            console.log(`    ${mem.id} (${mem.kind}): ${mem.text.slice(0, 80)}`);
+        }
+    }
+}
+//# sourceMappingURL=code-map.js.map

package/dist/commands/codev.js

@@ -26,6 +26,7 @@ import { buildContext } from '../core/context.js';
 import { buildCoordinationSnapshot } from '../core/coordination.js';
 import { getDefaultInvokeTemplate, getSpawnableAgents } from '../core/agent-capability.js';
 import { executeRound } from '../core/codev-rounds.js';
+import { buildWorkerIdentityEnv } from '../core/execution-profile.js';
 import { loadIdeationRound } from '../core/ideation.js';
 import { summarizeMetrics, summarizeMetricsByRound } from '../core/codev-metrics.js';
 import { generatePlansFromConvergence, generateSummaryNote } from '../core/codev-plan-gen.js';
@@ -422,12 +423,16 @@ function spawnConsultant(brief, threadId, personaName, cwd, agent) {
             console.warn(`  ⚠ Spawn error for ${agentName}/${personaName}: ${err.message}`);
         });
     };
+    // F7 (trp_0e5150d3): scrub coordinator identity so a consultant worker is an
+    // independent agent — these spawns previously inherited the full parent env.
+    const workerEnv = buildWorkerIdentityEnv(process.env, { agent: agentName });
     if (agentName === 'codex') {
         // Codex: use temp file via shell to avoid Windows .cmd ENOENT issues
         const child = spawn('sh', ['-c', `cat "${briefFile}" | "${binaryPath}" exec --full-auto - ; rm -f "${briefFile}"`], {
             detached: true,
             stdio: 'ignore',
             cwd,
+            env: workerEnv,
         });
         attachErrorHandler(child);
         child.unref();
@@ -438,6 +443,7 @@ function spawnConsultant(brief, threadId, personaName, cwd, agent) {
             detached: true,
             stdio: 'ignore',
             cwd,
+            env: workerEnv,
         });
         attachErrorHandler(child);
         child.unref();
@@ -448,6 +454,7 @@ function spawnConsultant(brief, threadId, personaName, cwd, agent) {
             detached: true,
             stdio: 'ignore',
             cwd,
+            env: workerEnv,
         });
         attachErrorHandler(child);
         child.unref();

package/dist/commands/dispatch-watch.js

@@ -94,7 +94,7 @@ export async function runDispatchWatch(targetId, options = {}) {
     const baseRef = options.base ?? 'master';
     const startedAt = Date.now();
     let poll = 0;
-    let lastState = 'running';
+    let lastState;
     let lastStatus;
     for (;;) {
         poll += 1;

package/dist/commands/doctor.js

@@ -747,7 +747,6 @@ export function runDoctor(options = {}) {
         const msg = e instanceof Error ? e.message : String(e);
         checks.push({ name: 'config', status: 'error', message: `config.yaml is invalid: ${msg}` });
         console.error(`✗ config.yaml is invalid: ${msg}`);
-        hasIssues = true;
         if (options.json) {
             console.log(JSON.stringify({ ok: false, checks, metrics: {} }, null, 2));
         }
@@ -807,7 +806,6 @@ export function runDoctor(options = {}) {
         const msg = e instanceof Error ? e.message : String(e);
         checks.push({ name: 'state', status: 'error', message: `state is invalid: ${msg}` });
         console.error(`✗ state is invalid: ${msg}`);
-        hasIssues = true;
         if (options.json) {
             console.log(JSON.stringify({ ok: false, checks, metrics: {} }, null, 2));
         }
@@ -2202,7 +2200,7 @@ export function runDoctor(options = {}) {
             }
             // Find duplicates (same text at different levels)
             const duplicates = [];
-            allConstraints.forEach((items, key) => {
+            allConstraints.forEach((items, _key) => {
                 if (items.length > 1 && new Set(items.map((i) => i.store)).size > 1) {
                     duplicates.push({
                         type: 'constraint',
@@ -2211,7 +2209,7 @@ export function runDoctor(options = {}) {
                     });
                 }
             });
-            allDecisions.forEach((items, key) => {
+            allDecisions.forEach((items, _key) => {
                 if (items.length > 1 && new Set(items.map((i) => i.store)).size > 1) {
                     duplicates.push({
                         type: 'decision',
@@ -2220,7 +2218,7 @@ export function runDoctor(options = {}) {
                     });
                 }
             });
-            allTraps.forEach((items, key) => {
+            allTraps.forEach((items, _key) => {
                 if (items.length > 1 && new Set(items.map((i) => i.store)).size > 1) {
                     duplicates.push({
                         type: 'trap',

package/dist/commands/loops-handlers.js

@@ -84,7 +84,10 @@ function validateSemanticRequest(req) {
     return null;
 }
 function requestPayload(req) {
-    const { agent, agentId, client_request_id, ...rest } = req;
+    const rest = { ...req };
+    delete rest.agent;
+    delete rest.agentId;
+    delete rest.client_request_id;
     return rest;
 }
 function currentLoopVersion(loopId, cwd) {

package/dist/commands/mcp-read-handlers.js

@@ -1,3 +1,11 @@
+/**
+ * MCP read-only tool handlers.
+ *
+ * Extracted from mcp.ts to reduce file size. These handlers do not mutate
+ * state — they build context, list items, search, and inspect.
+ *
+ * @module
+ */
 import { applyBootstrapImport, renderBootstrapInterview, renderBootstrapSummary, runBootstrapProfile, uninstallBootstrapImport } from '../core/bootstrap.js';
 import { buildAgentToolingContext, renderAgentToolingSummary } from '../core/agent-context.js';
 import { buildCoordinationSnapshot, buildCrossProjectSnapshot } from '../core/coordination.js';

package/dist/commands/mcp.js

@@ -48,6 +48,7 @@ import { dispatch, dispatchReview, generateDispatchBrief } from '../core/dispatc
 import { deleteMemoryItem, updateMemoryItem } from '../core/operations/memory-mutation.js';
 import { assessMemoryPressure, buildCompactionTemplate, applyCompaction } from '../core/gc-semantic.js';
 import { WorkRequestSchema, CoordinateRequestSchema } from '../core/facade-schema.js';
+import { codeMapWorkSection, codeMapRefreshNextActions } from '../core/code-map/work-section.js';
 import { getSpawnableAgents, getCapabilityProfile, buildInvokeCommand, validateAgentForDispatch } from '../core/agent-capability.js';
 import { attemptExecution } from '../core/execution.js';
 import { createAgentRun, transitionAgentRun } from '../core/agentruns.js';
@@ -449,8 +450,54 @@ export const MCP_READ_TOOLS = [
             required: ['target_id'],
         },
     },
+    {
+        name: 'bclaw_code_status',
+        description: 'Code Map status for this project: store presence, freshness badge (fresh / stale_changed_files / stale_extractor / stale_grammar / stale_git_head / partial / missing_index), and index stats (files, nodes, edges). Read-only; never refreshes. Pair with bclaw_code_refresh when freshness is missing_index or stale.',
+        annotations: { tier: 'standard', category: 'discovery', headlessApproval: 'auto' },
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    {
+        name: 'bclaw_code_find',
+        description: 'Search the Code Map symbol index for a query (function/class/component/hook/type names). Returns ranked matches with path + score, plus a freshness_badge from the lazy read-path check. Read-only; never refreshes — a missing_index badge means run bclaw_code_refresh first.',
+        annotations: { tier: 'standard', category: 'discovery', headlessApproval: 'auto' },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Symbol or token to search for (e.g. "App", "useAuth", "dispatch").' },
+                limit: { type: 'number', description: 'Max matches to return.' },
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'bclaw_code_brief',
+        description: 'Before editing, ask Code Map what to read: returns a ranked suggested_files_to_read list (cap 12) for a symbol or path, related brainclaw memory (cap 5), and a freshness_badge. Read-only; never refreshes.',
+        annotations: { tier: 'standard', category: 'discovery', headlessApproval: 'auto' },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                target: { type: 'string', description: 'Symbol name or file path to build a reading brief for.' },
+                limit: { type: 'number', description: 'Max suggested files (hard-capped at 12 by the spec).' },
+            },
+            required: ['target'],
+        },
+    },
 ];
 const MCP_WRITE_TOOLS = [
+    {
+        name: 'bclaw_code_refresh',
+        description: 'Rebuild the Code Map index for this project (Tree-sitter parse + shards + indexes, behind the per-project lock). scope="changed" (default) reparses changed files; scope="all" does a full refresh + compaction. A live competing lock fails fast with a clear status — refresh never blocks. Returns the resulting freshness_badge.',
+        annotations: { tier: 'standard', category: 'discovery', headlessApproval: 'prompt' },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                scope: { type: 'string', enum: ['changed', 'all'], description: 'changed (default) reparses changed files only; all does a full refresh with orphan compaction.' },
+            },
+        },
+    },
     {
         name: 'bclaw_dispatch',
         description: 'Unified dispatch entry for sequence-lane parallelization (parallelize plans across lanes). To open a NEW review of a commit/branch, use `bclaw_coordinate(intent="review", open_loop=true, targetAgents=[…])` instead — bclaw_dispatch is for sequence-driven execution, NOT for opening new reviews. `intent` discriminator: analysis (sequence lane status, read-only), execute (default — analyze + generate briefs + send to agents), review (routes an EXISTING already-reflected handoff to a reviewer — only for handoffs produced by `session-end --reflect-handoff` or similar). Consolidates the legacy bclaw_dispatch_analysis / bclaw_dispatch / bclaw_dispatch_review. Returns FacadeResponse; for verification semantics see the same response-validation guidance documented on `bclaw_coordinate`.',
@@ -2599,6 +2646,59 @@ async function _executeMcpToolCallInner(payload) {
             const { handleCheckSecurity } = await import('./check-security-mcp.js');
             return { response: toolResponse(await handleCheckSecurity(args, cwd)) };
         }
+        // Code Map tools (spec §9). These delegate to the async JsonlBackend, so
+        // they are handled here rather than via the synchronous read-tool path.
+        // status/find/brief are reads; refresh is a write (prompt approval).
+        if (name === 'bclaw_code_status' || name === 'bclaw_code_find' || name === 'bclaw_code_brief' || name === 'bclaw_code_refresh') {
+            const { JsonlBackend } = await import('../core/code-map/backend.js');
+            const be = new JsonlBackend();
+            if (name === 'bclaw_code_status') {
+                const status = await be.status({ cwd });
+                return {
+                    response: toolResponse({
+                        content: [{ type: 'text', text: `Code Map: ${status.store_exists ? 'store present' : 'no store'} — freshness=${status.freshness_badge.status}` }],
+                        structuredContent: { ...status, freshness_badge: status.freshness_badge },
+                    }),
+                };
+            }
+            if (name === 'bclaw_code_refresh') {
+                const scope = args.scope === 'all' ? 'all' : 'changed';
+                const result = await be.refresh({ scope, cwd });
+                return {
+                    response: toolResponse({
+                        content: [{ type: 'text', text: `Code Map refresh [${result.scope}]: ran=${result.ran} freshness=${result.freshness_badge.status}${result.lock_status ? ` (${result.lock_status})` : ''}` }],
+                        structuredContent: { ...result, freshness_badge: result.freshness_badge },
+                    }),
+                };
+            }
+            if (name === 'bclaw_code_find') {
+                const query = typeof args.query === 'string' ? args.query : '';
+                if (!query.trim()) {
+                    return { response: createToolErrorResponse('validation_error', 'bclaw_code_find requires a non-empty query.') };
+                }
+                const limit = typeof args.limit === 'number' ? args.limit : undefined;
+                const result = await be.find({ query, limit, cwd });
+                return {
+                    response: toolResponse({
+                        content: [{ type: 'text', text: `Code Map find "${result.query}": ${result.matches.length} match(es), freshness=${result.freshness_badge.status}` }],
+                        structuredContent: { ...result, freshness_badge: result.freshness_badge },
+                    }),
+                };
+            }
+            // bclaw_code_brief
+            const target = typeof args.target === 'string' ? args.target : '';
+            if (!target.trim()) {
+                return { response: createToolErrorResponse('validation_error', 'bclaw_code_brief requires a non-empty target.') };
+            }
+            const limit = typeof args.limit === 'number' ? args.limit : undefined;
+            const result = await be.brief({ target, limit, cwd });
+            return {
+                response: toolResponse({
+                    content: [{ type: 'text', text: `Code Map brief "${result.target}": ${result.suggested_files_to_read.length} file(s) to read, freshness=${result.freshness_badge.status}` }],
+                    structuredContent: { ...result, freshness_badge: result.freshness_badge },
+                }),
+            };
+        }
         if (MCP_READ_TOOLS.some((tool) => tool.name === name) || LEGACY_READ_TOOL_HANDLERS.has(name)) {
             return {
                 response: appendLegacyMcpToolWarning(toolResponse(handleMcpReadToolCall(name, args, { cwd, connectionSessionId, effectiveScope: scopeInfo })), name),
@@ -4854,6 +4954,26 @@ async function _executeMcpToolCallInner(payload) {
                 nextActions.push({ tool: 'bclaw_context', args: { kind: 'memory' }, when: 'to read the full changed items behind context_diff' });
             }
             nextActions.push({ tool: 'bclaw_quick_capture', args: { text: '<finding>', type: '<decision|trap|constraint|note>' }, when: 'capture decisions/traps as you work' });
+            // Code Map opt-in section (spec §10). Single live seam: returns null
+            // (and does no work) unless the project's Code Map manifest carries
+            // code_map_enabled:true. Never refreshes; bounded ≤2500ms on an active
+            // lock; surfaces a missing_index hint or stale results with the badge.
+            let codeMapSection = null;
+            try {
+                codeMapSection = await codeMapWorkSection(targetCwd, {
+                    query: workReq.scope ?? workReq.contextTarget,
+                });
+            }
+            catch {
+                // Best-effort: Code Map must never break or block bclaw_work.
+            }
+            // Code Map onboarding/freshness nudge (pln#588): promote the actionable
+            // refresh to a first-class next_action so a fresh or stale project's first
+            // bclaw_work TELLS the agent to build/update the index — the passive
+            // missing_index hint alone was easy to skip. Still never refreshes here.
+            for (const action of codeMapRefreshNextActions(codeMapSection)) {
+                nextActions.push(action);
+            }
             const facadeResponse = {
                 status: 'ok',
                 intent: workReq.intent,
@@ -4868,6 +4988,7 @@ async function _executeMcpToolCallInner(payload) {
                 bootstrap_verdict: bootstrapVerdict,
                 next_action: nextAction,
                 next_actions: nextActions,
+                ...(codeMapSection ? { code_map: codeMapSection } : {}),
             };
             const summaryParts = [`✔ bclaw_work [${workReq.intent}] session=${sessionResult.session_id}`];
             if (claimId)
@@ -5239,7 +5360,6 @@ async function _executeMcpToolCallInner(payload) {
                         }));
                         continue;
                     }
-                    const profile = check.profile;
                     // Ensure target agent is registered before creating claims/messages
                     ensureAgentRegisteredForDispatch(agentName, dispatchCwd);
                     const assignScope = req.scope ?? req.task;

package/dist/commands/metrics.js

@@ -12,7 +12,6 @@ export function runMetrics(options = {}) {
     }
     const config = loadConfig();
     const slaHours = config.governance?.review_sla_hours ?? 24;
-    const now = new Date();
     const report = buildMetricsReport(slaHours, options.since);
     if (options.json) {
         console.log(JSON.stringify(report, null, 2));

package/dist/commands/release-claims.js

@@ -39,7 +39,7 @@ export function runReleaseClaims(options = {}) {
         process.exit(0);
     let released = 0;
     mutate({ cwd: options.cwd }, () => {
-        let state = loadState(options.cwd);
+        let state;
         for (const claim of toRelease) {
             try {
                 releaseClaim(claim.id, options.cwd);