brainclaw 1.9.1 → 1.10.0

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                                                                                                                    |
 | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
@@ -359,6 +382,7 @@ If you are integrating Brainclaw into an agent workflow, start with the agent-fa
 | `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/code-map.md`                       | Code Map — symbol/import index, freshness model, monorepo behavior                            |
 | `docs/concepts/memory.md`                | What "memory" means in brainclaw                                                              |
 | `docs/concepts/plans-and-claims.md`      | Coordination layer                                                                            |
 | `docs/concepts/runtime-notes.md`         | Ephemeral observations                                                                        |
@@ -393,6 +417,28 @@ 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.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/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 / 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)

package/dist/commands/run-profile.js

@@ -37,8 +37,9 @@ export function runRunProfile(profileName, options = {}) {
             console.error(`Unknown agent: ${options.agent}. Using profile invoke template.`);
         }
     }
-    // Replace {prompt} placeholder with the profile prompt
-    const command = invoke.replace(/\{prompt\}/g, profile.prompt.replace(/"/g, '\\"'));
+    // Replace {prompt} placeholder with the profile prompt. Escape backslashes
+    // before quotes so a backslash in the prompt can't break out of the quoting.
+    const command = invoke.replace(/\{prompt\}/g, profile.prompt.replace(/\\/g, '\\\\').replace(/"/g, '\\"'));
     if (options.dry) {
         console.log(`[dry-run] Profile: ${profile.name}`);
         console.log(`[dry-run] Command: ${command}`);