brainclaw 1.28.4 → 1.28.5

package/dist/cli/register-code-map.js

@@ -7,6 +7,7 @@ export function registerCodeMapCommands(program) {
         .option('--json', 'Output as JSON')
         .option('--all', 'For refresh: enumerate all supported files (full refresh)')
         .option('--changed', 'For refresh: only changed files (default)')
+        .option('--scope <scope>', 'For refresh: changed or all (same selector as MCP)')
         .option('--cascade', 'For refresh/status in a multi-project workspace: cascade across every nested project (each gets its own store; the root store is scoped to files no child owns)')
         .option('--limit <n>', 'Max results for find/brief/impact/outline', (v) => parseInt(v, 10))
         .option('--depth <n>', 'For impact/export: maximum graph depth (export is hard-capped at 4)', (v) => parseInt(v, 10))

package/dist/commands/code-map.js

@@ -27,7 +27,10 @@ export async function runCodeMap(subcommand, args, options = {}) {
         return;
     }
     if (normalized === 'refresh') {
-        const scope = options.all ? 'all' : 'changed';
+        if (options.scope && options.scope !== 'all' && options.scope !== 'changed') {
+            throw new Error('code-map refresh --scope must be "changed" or "all".');
+        }
+        const scope = options.scope === 'all' || options.all ? 'all' : 'changed';
         const result = await be.refresh({ scope, cwd, cascade: options.cascade });
         printRefresh(result, options);
         return;
@@ -108,6 +111,7 @@ function printStatus(status, options) {
     }
     console.log('Code Map status');
     console.log(`  Store:    ${status.store_exists ? 'present' : 'absent'}`);
+    console.log(`  Index:    ${status.index_exists ? 'ready' : status.index_manifest_exists ? 'invalid manifest' : 'not built'}`);
     console.log(`  Root:     ${status.resolution.project_root}`);
     console.log(`  Path:     ${status.resolution.store_path}`);
     console.log(`  ${badgeLine(status.freshness_badge)}`);

package/dist/commands/mcp-catalog.js

@@ -374,11 +374,12 @@ export const MCP_READ_TOOLS = [
     },
     {
         name: 'bclaw_code_status',
-        description: 'Code Map status for the active session project: store presence, freshness badge, and index stats. Read-only; never refreshes. In a multi-project workspace, cascade=true adds per-child coverage plus progress/terminal diagnostics for the latest durable cascade job.',
+        description: 'Code Map status for the active session or explicit project: physical store-path presence, readable-index presence, exact resolution, freshness, stats, and latest durable refresh job. Read-only; never refreshes. In a multi-project workspace, cascade=true adds per-child coverage plus progress/terminal diagnostics for the latest durable cascade job.',
         annotations: { tier: 'standard', category: 'discovery', headlessApproval: 'auto' },
         inputSchema: {
             type: 'object',
             properties: {
+                project: { type: 'string', description: 'Optional project name, id, or workspace-relative path. Overrides the active session project for this call.' },
                 cascade: { type: 'boolean', description: 'Multi-project workspace recap: also report per-child store presence + freshness for every nested project. No-op outside a multi-project workspace.' },
             },
         },
@@ -390,6 +391,7 @@ export const MCP_READ_TOOLS = [
         inputSchema: {
             type: 'object',
             properties: {
+                project: { type: 'string', description: 'Optional project name, id, or workspace-relative path. Overrides the active session project for this call.' },
                 query: { type: 'string', description: 'Symbol or token to search for (e.g. "App", "useAuth", "dispatch").' },
                 limit: { type: 'number', description: 'Max matches to return.' },
             },
@@ -403,6 +405,7 @@ export const MCP_READ_TOOLS = [
         inputSchema: {
             type: 'object',
             properties: {
+                project: { type: 'string', description: 'Optional project name, id, or workspace-relative path. Overrides the active session project for this call.' },
                 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).' },
             },
@@ -416,6 +419,7 @@ export const MCP_READ_TOOLS = [
         inputSchema: {
             type: 'object',
             properties: {
+                project: { type: 'string', description: 'Optional project name, id, or workspace-relative path. Overrides the active session project for this call.' },
                 target: { type: 'string', description: 'Symbol name or source-file path whose impact to inspect.' },
                 depth: { type: 'number', description: 'Maximum graph depth. 1 (default) returns direct dependents only; 2+ opts into transitives. Clamped to 4.' },
                 limit: { type: 'number', description: 'Maximum rows in each dependent section and in naming suggestions. Clamped to 100.' },
@@ -430,6 +434,7 @@ export const MCP_READ_TOOLS = [
         inputSchema: {
             type: 'object',
             properties: {
+                project: { type: 'string', description: 'Optional project name, id, or workspace-relative path. Overrides the active session project for this call.' },
                 target: { type: 'string', description: 'Symbol name or source-file path around which to export a local subgraph.' },
                 targetKind: { type: 'string', enum: ['symbol', 'file'], description: 'Optional explicit target kind; otherwise a source path is detected safely.' },
                 direction: { type: 'string', enum: ['outgoing', 'incoming', 'both'], description: 'Which edge direction(s) to follow. Default: both.' },
@@ -449,6 +454,7 @@ export const MCP_READ_TOOLS = [
         inputSchema: {
             type: 'object',
             properties: {
+                project: { type: 'string', description: 'Optional project name, id, or workspace-relative path. Overrides the active session project for this call.' },
                 path: { type: 'string', description: 'Workspace-relative source file path (for example `src/app/App.tsx`).' },
                 limit: { type: 'number', description: 'Maximum symbols to return; clamped to the hard cap of 200.' },
             },
@@ -459,11 +465,12 @@ export const MCP_READ_TOOLS = [
 const MCP_WRITE_TOOLS = [
     {
         name: 'bclaw_code_refresh',
-        description: 'Rebuild the Code Map index for the active session project. scope="changed" (default) reparses changed files; scope="all" does a full refresh + compaction. In a multi-project workspace, cascade=true starts a durable background job immediately; follow it with bclaw_code_status(cascade=true), which reports progress and terminal per-project diagnostics without an MCP timeout.',
+        description: 'Accept a durable background rebuild of the Code Map index for the active or explicit project and return immediately. scope="changed" (default) reparses changed files; scope="all" does a full refresh + compaction. Follow with bclaw_code_status, which reports progress and terminal diagnostics without an MCP timeout. In a multi-project workspace, cascade=true applies the same contract across nested projects.',
         annotations: { tier: 'standard', category: 'discovery', headlessApproval: 'prompt' },
         inputSchema: {
             type: 'object',
             properties: {
+                project: { type: 'string', description: 'Optional project name, id, or workspace-relative path. Overrides the active session project for this call.' },
                 scope: { type: 'string', enum: ['changed', 'all'], description: 'changed (default) reparses changed files only; all does a full refresh with orphan compaction.' },
                 cascade: { type: 'boolean', description: 'Multi-project cascade: refresh every nested brainclaw project + a child-scoped root store. No-op outside a multi-project workspace.' },
             },

package/dist/commands/mcp.js

@@ -1097,19 +1097,32 @@ async function _executeMcpToolCallInner(payload) {
             const { JsonlBackend } = await import('../core/code-map/backend.js');
             const be = new JsonlBackend();
             // Session-scoped project selection is authoritative for Code Map too.
-            const codeCwd = scopeInfo.cwd;
+            // An explicit project selector wins, matching the canonical read grammar.
+            let codeCwd = scopeInfo.cwd;
+            let codeScope = scopeInfo;
+            if (typeof args.project === 'string' && args.project.trim()) {
+                codeCwd = resolveProjectCwd(args.project.trim(), codeCwd);
+                codeScope = {
+                    cwd: codeCwd,
+                    active_source: 'explicit',
+                    resolved_project: projectInfoForCwd(codeCwd),
+                };
+            }
             if (name === 'bclaw_code_status') {
                 const status = await be.status({ cwd: codeCwd, cascade: args.cascade === true });
                 const diskVersion = readDiskBrainclawVersion();
                 return {
                     response: toolResponse({
-                        content: [{ type: 'text', text: `Code Map: ${status.store_exists ? 'store present' : 'no store'} — freshness=${status.freshness_badge.freshness}` }],
+                        content: [{
+                                type: 'text',
+                                text: `Code Map: path=${status.store_exists ? 'present' : 'absent'}, index=${status.index_exists ? 'ready' : status.index_manifest_exists ? 'invalid' : 'missing'} — freshness=${status.freshness_badge.freshness}`,
+                            }],
                         structuredContent: {
                             ...status,
                             freshness_badge: status.freshness_badge,
                             mcp_resolution: {
-                                active_source: scopeInfo.active_source,
-                                resolved_project: scopeInfo.resolved_project,
+                                active_source: codeScope.active_source,
+                                resolved_project: codeScope.resolved_project,
                                 server_version: getInstalledBrainclawVersion(),
                                 disk_version: diskVersion,
                                 restart_required: diskVersion !== '0.0.0' && diskVersion !== getInstalledBrainclawVersion(),
@@ -1136,12 +1149,27 @@ async function _executeMcpToolCallInner(payload) {
                         };
                     }
                 }
-                const result = await be.refresh({ scope, cwd: codeCwd, cascade: args.cascade === true });
-                const cascadeNote = result.cascade ? ` cascade=${result.cascade.children_refreshed} child(ren)+root` : '';
+                const { startCodeRefreshJob, summarizeCodeRefreshJob } = await import('../core/code-map/refresh-jobs.js');
+                const job = startCodeRefreshJob(codeCwd, scope);
+                const accepted = job.status !== 'failed' && job.scope === scope;
+                const acknowledgement = accepted
+                    ? `Code Map refresh accepted: job=${job.job_id}, scope=${job.scope}, project=${codeCwd}.`
+                    : job.status === 'failed'
+                        ? `Code Map refresh failed to start: job=${job.job_id}, project=${codeCwd}, error=${job.error ?? 'unknown'}.`
+                        : `Code Map refresh not queued: active job=${job.job_id} has scope=${job.scope}; requested scope=${scope}.`;
                 return {
                     response: toolResponse({
-                        content: [{ type: 'text', text: `Code Map refresh [${result.scope}]: ran=${result.ran} freshness=${result.freshness_badge.freshness}${cascadeNote}${result.lock_status ? ` (${result.lock_status})` : ''}` }],
-                        structuredContent: { ...result, freshness_badge: result.freshness_badge },
+                        content: [{ type: 'text', text: `${acknowledgement} Follow with bclaw_code_status${typeof args.project === 'string' ? `(project=${JSON.stringify(args.project)})` : ''}.` }],
+                        structuredContent: {
+                            accepted,
+                            requested_scope: scope,
+                            ...summarizeCodeRefreshJob(job),
+                            next_actions: [{
+                                    tool: 'bclaw_code_status',
+                                    args: typeof args.project === 'string' ? { project: args.project } : {},
+                                    when: 'follow refresh progress and terminal outcome',
+                                }],
+                        },
                     }),
                 };
             }
@@ -1226,8 +1254,15 @@ async function _executeMcpToolCallInner(payload) {
             };
         }
         if (MCP_READ_TOOLS.some((tool) => tool.name === name) || LEGACY_READ_TOOL_HANDLERS.has(name)) {
+            const response = appendLegacyMcpToolWarning(toolResponse(handleMcpReadToolCall(name, args, { cwd, connectionSessionId, effectiveScope: scopeInfo })), name);
+            const switchedSessionId = name === 'bclaw_switch'
+                ? response.structuredContent?.session_id
+                : undefined;
             return {
-                response: appendLegacyMcpToolWarning(toolResponse(handleMcpReadToolCall(name, args, { cwd, connectionSessionId, effectiveScope: scopeInfo })), name),
+                response,
+                ...(typeof switchedSessionId === 'string' && switchedSessionId
+                    ? { nextConnectionSessionId: switchedSessionId }
+                    : {}),
             };
         }
         // Resolve model once for all write operations

package/dist/commands/switch.js

@@ -72,7 +72,14 @@ export function switchProject(projectRef, options = {}) {
             ...session,
             active_project: { path: resolved, name: projectName, switched_at: now },
         }, cwd);
-        return { switched: true, path: resolved, name: projectName, scope: 'session', workspace_root: wsRoot };
+        return {
+            switched: true,
+            path: resolved,
+            name: projectName,
+            scope: 'session',
+            workspace_root: wsRoot,
+            session_id: session.session_id,
+        };
     }
     if (sessionOnly) {
         throw new Error('Cannot switch project without an active agent session. Start with bclaw_work or bclaw_session_start first.');

package/dist/core/code-map/backend.js

@@ -9,8 +9,9 @@
  * `freshness_badge`, locking the response shape for later sprints.
  */
 import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
 import path from 'node:path';
-import { readManifest, readShard, storeExists } from './store.js';
+import { readManifest, readShard } from './store.js';
 import { refresh as runRefresh } from './refresh.js';
 import { applyGitHeadDrift, withFreshness } from './freshness.js';
 import { brief as runBrief, find as runFind } from './query.js';
@@ -21,8 +22,9 @@ import { resolveTraversal, aggregateFind, aggregateBrief } from './aggregate.js'
 import { defaultMemoryReader } from './memory-reader.js';
 import { inspectNestedProjects, refreshWorkspaceCascade } from './cascade.js';
 import { latestCascadeRefreshJob, summarizeCascadeRefreshJob } from './cascade-jobs.js';
+import { latestCodeRefreshJob, summarizeCodeRefreshJob } from './refresh-jobs.js';
 import { loadConfig } from '../config.js';
-import { codeMapDir } from './paths.js';
+import { codeMapDir, manifestPath } from './paths.js';
 /** spec §9 caps the brief reading list at 12 files. */
 export const BRIEF_FILE_CAP = 12;
 /**
@@ -116,9 +118,12 @@ function buildCascadeStatus(rootCwd) {
     const discovery = inspectNestedProjects(root);
     const children = discovery.projects.map((abs) => {
         const m = readManifest(abs);
+        const storePath = codeMapDir(abs);
         return {
             path: path.relative(root, abs).replace(/\\/g, '/') || '.',
-            store_exists: m ? true : storeExists(abs),
+            store_exists: fs.existsSync(storePath),
+            index_exists: m !== null,
+            index_manifest_exists: fs.existsSync(manifestPath(abs)),
             freshness: m ? m.freshness.status : 'missing_index',
             files_indexed: m ? m.stats.files_indexed : null,
             ...(m && m.stats.files_indexed === 0 ? { reason: 'no_eligible_files' } : {}),
@@ -157,9 +162,13 @@ export class JsonlBackend {
             store_path: codeMapDir(projectRoot, input.preferredDirName),
         };
         const manifest = readManifest(input.cwd, input.preferredDirName);
+        const storePathExists = fs.existsSync(resolution.store_path);
+        const manifestFileExists = fs.existsSync(manifestPath(input.cwd, input.preferredDirName));
         const result = manifest
             ? {
-                store_exists: true,
+                store_exists: storePathExists,
+                index_exists: true,
+                index_manifest_exists: true,
                 resolution,
                 freshness_badge: this.withHeadDrift(badge(manifest.freshness.status, {
                     stale_file_count: manifest.freshness.stale_file_count,
@@ -172,7 +181,9 @@ export class JsonlBackend {
                 },
             }
             : {
-                store_exists: storeExists(input.cwd, input.preferredDirName),
+                store_exists: storePathExists,
+                index_exists: false,
+                index_manifest_exists: manifestFileExists,
                 resolution,
                 freshness_badge: badge('missing_index'),
                 stats: null,
@@ -183,6 +194,9 @@ export class JsonlBackend {
         if (input.cascade && isMultiProjectWorkspace(input.cwd)) {
             result.cascade = buildCascadeStatus(input.cwd);
         }
+        const latestRefresh = latestCodeRefreshJob(projectRoot);
+        if (latestRefresh)
+            result.refresh_job = summarizeCodeRefreshJob(latestRefresh);
         return result;
     }
     /**

package/dist/core/code-map/refresh-jobs.js

@@ -0,0 +1,158 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import { writeFileAtomic } from '../io.js';
+import { codeMapDir } from './paths.js';
+function jobsDir(root) {
+    return path.join(codeMapDir(root), 'refresh-jobs');
+}
+function jobPath(root, jobId) {
+    return path.join(jobsDir(root), `${jobId}.json`);
+}
+function writeJob(job) {
+    fs.mkdirSync(jobsDir(job.root), { recursive: true });
+    writeFileAtomic(jobPath(job.root, job.job_id), `${JSON.stringify(job, null, 2)}\n`);
+}
+export function readCodeRefreshJob(root, jobId) {
+    try {
+        return JSON.parse(fs.readFileSync(jobPath(path.resolve(root), jobId), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function latestCodeRefreshJob(root) {
+    try {
+        return fs.readdirSync(jobsDir(path.resolve(root)))
+            .filter((name) => name.endsWith('.json'))
+            .map((name) => {
+            try {
+                return JSON.parse(fs.readFileSync(path.join(jobsDir(path.resolve(root)), name), 'utf8'));
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((job) => job !== null)
+            .sort((a, b) => b.updated_at.localeCompare(a.updated_at))[0] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export function summarizeCodeRefreshJob(job) {
+    return {
+        ...job,
+        ...(job.result
+            ? {
+                result: {
+                    ran: job.result.ran,
+                    scope: job.result.scope,
+                    lock_acquired: job.result.lock_acquired,
+                    ...(job.result.lock_status ? { lock_status: job.result.lock_status } : {}),
+                    freshness_badge: job.result.freshness_badge,
+                },
+            }
+            : {}),
+    };
+}
+function processAlive(pid) {
+    if (!pid)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Start a detached, durable refresh and return before parsing begins. */
+export function startCodeRefreshJob(root, scope) {
+    const resolvedRoot = path.resolve(root);
+    const previous = latestCodeRefreshJob(resolvedRoot);
+    if (previous && (previous.status === 'queued' || previous.status === 'running') && processAlive(previous.pid)) {
+        return previous;
+    }
+    const now = new Date().toISOString();
+    const job = {
+        job_id: `cmj_${crypto.randomBytes(8).toString('hex')}`,
+        root: resolvedRoot,
+        scope,
+        status: 'queued',
+        created_at: now,
+        updated_at: now,
+    };
+    writeJob(job);
+    const worker = fileURLToPath(new URL('./refresh-worker.js', import.meta.url));
+    if (!fs.existsSync(worker)) {
+        const failed = {
+            ...job,
+            status: 'failed',
+            error: `code refresh worker is missing: ${worker}`,
+            completed_at: new Date().toISOString(),
+            updated_at: new Date().toISOString(),
+        };
+        writeJob(failed);
+        return failed;
+    }
+    const child = spawn(process.execPath, [worker, resolvedRoot, job.job_id, scope], {
+        cwd: resolvedRoot,
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+    });
+    child.once('error', (error) => {
+        const current = readCodeRefreshJob(resolvedRoot, job.job_id) ?? job;
+        if (current.status === 'completed' || current.status === 'failed')
+            return;
+        const completed = new Date().toISOString();
+        writeJob({
+            ...current,
+            status: 'failed',
+            error: `code refresh worker failed to start: ${error.message}`,
+            completed_at: completed,
+            updated_at: completed,
+        });
+    });
+    child.unref();
+    const queued = readCodeRefreshJob(resolvedRoot, job.job_id) ?? job;
+    queued.pid = child.pid;
+    queued.updated_at = new Date().toISOString();
+    writeJob(queued);
+    return queued;
+}
+/** Worker seam exported for deterministic tests. */
+export async function runCodeRefreshJob(root, jobId, scope) {
+    const job = readCodeRefreshJob(root, jobId);
+    if (!job)
+        throw new Error(`code refresh job not found: ${jobId}`);
+    const started = new Date().toISOString();
+    writeJob({ ...job, status: 'running', pid: process.pid, started_at: started, updated_at: started });
+    try {
+        // Dynamic import avoids coupling the query backend's status path to worker startup.
+        const { JsonlBackend } = await import('./backend.js');
+        const result = await new JsonlBackend().refresh({ cwd: root, scope });
+        const completed = new Date().toISOString();
+        writeJob({
+            ...(readCodeRefreshJob(root, jobId) ?? job),
+            status: 'completed',
+            result,
+            completed_at: completed,
+            updated_at: completed,
+        });
+    }
+    catch (error) {
+        const completed = new Date().toISOString();
+        writeJob({
+            ...(readCodeRefreshJob(root, jobId) ?? job),
+            status: 'failed',
+            error: error instanceof Error ? error.message : String(error),
+            completed_at: completed,
+            updated_at: completed,
+        });
+    }
+}
+//# sourceMappingURL=refresh-jobs.js.map

package/dist/core/code-map/refresh-worker.js

@@ -0,0 +1,12 @@
+import { runCodeRefreshJob } from './refresh-jobs.js';
+const [root, jobId, scope] = process.argv.slice(2);
+if (!root || !jobId || (scope !== 'changed' && scope !== 'all')) {
+    process.exitCode = 2;
+}
+else {
+    await runCodeRefreshJob(root, jobId, scope);
+    // Dedicated detached process: no library-owned handle may keep the caller's
+    // project directory busy after the durable terminal state has been written.
+    process.exit(0);
+}
+//# sourceMappingURL=refresh-worker.js.map

package/dist/facts.js

@@ -1,8 +1,8 @@
 // Generated by scripts/emit-site-facts.mjs at build time. Do not edit manually.
-// Source: brainclaw v1.28.4 on 2026-08-28T07:25:30.486Z
+// Source: brainclaw v1.28.5 on 2026-08-28T18:04:39.470Z
 export const FACTS = {
-  "version": "1.28.4",
-  "generated_at": "2026-08-28T07:25:30.486Z",
+  "version": "1.28.5",
+  "generated_at": "2026-08-28T18:04:39.470Z",
   "tools": {
     "count": 71,
     "published_count": 69,
@@ -479,7 +479,7 @@ export const FACTS = {
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-28T07:25:28.367Z",
+    "generated_at": "2026-08-28T18:04:37.892Z",
     "node_version": "v24.19.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -488,7 +488,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": 80,
+        "duration_ms_median": 51,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -496,17 +496,17 @@ 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": 124,
-        "payload_chars_median": 2626,
-        "payload_tokens_est_median": 657
+        "duration_ms_median": 72,
+        "payload_chars_median": 2625,
+        "payload_tokens_est_median": 656
       },
       {
         "name": "first_edit",
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
-        "duration_ms_median": 11,
-        "payload_chars_median": 1629,
-        "payload_tokens_est_median": 407
+        "duration_ms_median": 8,
+        "payload_chars_median": 1680,
+        "payload_tokens_est_median": 420
       }
     ]
   }

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.28.4",
-  "generated_at": "2026-08-28T07:25:30.486Z",
+  "version": "1.28.5",
+  "generated_at": "2026-08-28T18:04:39.470Z",
   "tools": {
     "count": 71,
     "published_count": 69,
@@ -477,7 +477,7 @@
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-28T07:25:28.367Z",
+    "generated_at": "2026-08-28T18:04:37.892Z",
     "node_version": "v24.19.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -486,7 +486,7 @@
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 80,
+        "duration_ms_median": 51,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -494,17 +494,17 @@
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 124,
-        "payload_chars_median": 2626,
-        "payload_tokens_est_median": 657
+        "duration_ms_median": 72,
+        "payload_chars_median": 2625,
+        "payload_tokens_est_median": 656
       },
       {
         "name": "first_edit",
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
-        "duration_ms_median": 11,
-        "payload_chars_median": 1629,
-        "payload_tokens_est_median": 407
+        "duration_ms_median": 8,
+        "payload_chars_median": 1680,
+        "payload_tokens_est_median": 420
       }
     ]
   }

package/docs/cli.md

@@ -632,18 +632,18 @@ brainclaw note create "Need follow-up on launcher script" --plan pln_abc123
 
 ## Code Map
 
-A per-project Tree-sitter symbol + import index (JS/TS, Python, PHP, Java) so agents
+A per-project Tree-sitter symbol + import index across 11 languages so agents
 can ask "where is X / what should I read first" before editing. The MCP equivalents
 are `bclaw_code_status` / `bclaw_code_find` / `bclaw_code_brief` / `bclaw_code_refresh`.
 Full reference (freshness model, supported languages, WASM bundling): [docs/code-map.md](code-map.md).
 
 ### `brainclaw code-map status [--cascade]`
 
-Store presence, freshness badge (`fresh` / `stale_changed_files` / `stale_extractor` / `stale_grammar` / `partial` / `missing_index`), and index stats (files, nodes, edges). Read-only. In a multi-project workspace, `--cascade` adds compact coverage counts and names only non-fresh projects. On the MCP surface, the equivalent `bclaw_code_status(cascade=true)` also follows the latest durable cascade job.
+Physical store-path presence, readable-index presence, freshness badge (`fresh` / `stale_changed_files` / `stale_extractor` / `stale_grammar` / `partial` / `missing_index`), and index stats (files, nodes, edges). Read-only. In a multi-project workspace, `--cascade` adds compact coverage counts and names only non-fresh projects. On MCP, status also follows the latest durable refresh job and accepts `project` for explicit targeting.
 
-### `brainclaw code-map refresh [--all|--changed] [--cascade]`
+### `brainclaw code-map refresh [--all|--changed|--scope changed|all] [--cascade]`
 
-Build or update the index. `--changed` (default) re-parses only touched files; `--all` does a full re-index. Run this when status shows `missing_index` or a stale badge. Fails fast (never blocks) if another writer holds the project lock. In a multi-project workspace, `--cascade` synchronously refreshes each discovered project into its own store plus a root store scoped to files no child owns (zero double-indexing). The MCP equivalent starts a durable background job instead; follow it with `bclaw_code_status(cascade=true)`. See [docs/code-map.md](code-map.md#cascading-a-multi-project-workspace---cascade).
+Build or update the index. `--changed` (default) re-parses only touched files; `--all` does a full re-index; `--scope changed|all` is the MCP-compatible spelling. Run this when status shows `missing_index` or a stale badge. Fails fast if another writer holds the project lock. In a multi-project workspace, `--cascade` synchronously refreshes each discovered project into its own store plus a root store scoped to files no child owns. MCP refreshes return durable jobs immediately; follow them with `bclaw_code_status`, preserving the same optional `project`, or use `cascade=true` for a workspace job. See [docs/code-map.md](code-map.md#cascading-a-multi-project-workspace---cascade).
 
 ### `brainclaw code-map find <query> [--limit <n>]`
 

package/docs/code-map.md

@@ -13,7 +13,7 @@ code, never blocks `bclaw_work`, and degrades gracefully: if the index is
 missing or stale, every command says so via a freshness badge instead of
 returning silently wrong answers.
 
-The index lives under `.brainclaw/code-map/` (one JSONL shard per file, plus
+The index lives under `.brainclaw/code/` (one JSONL shard per file, plus
 named symbol/import indexes and a manifest). It is safe to delete; a refresh
 rebuilds it.
 
@@ -37,8 +37,10 @@ accepts `--json` for machine-readable output, and prints a `Freshness:` line.
 
 ### `brainclaw code-map status`
 
-Read-only. Reports whether the store exists, the freshness badge, and index
-stats (files indexed, nodes, edges). Never refreshes.
+Read-only. Reports whether the physical store path exists, whether a valid
+index is readable, the freshness badge, and index stats (files indexed, nodes,
+edges). `store_exists`, `index_exists`, and `index_manifest_exists` deliberately
+separate a directory containing job records from a usable index. Never refreshes.
 
 ```bash
 brainclaw code-map status
@@ -47,6 +49,7 @@ brainclaw code-map status
 ```
 Code Map status
   Store:    present
+  Index:    ready
   Root:     /workspace/apps/api
   Path:     /workspace/apps/api/.brainclaw/code
   Freshness: fresh
@@ -55,7 +58,7 @@ Code Map status
   Edges:    2410
 ```
 
-### `brainclaw code-map refresh [--changed | --all]`
+### `brainclaw code-map refresh [--changed | --all | --scope changed|all]`
 
 Rebuilds the index behind a per-project lock. Defaults to `--changed`.
 
@@ -63,6 +66,7 @@ Rebuilds the index behind a per-project lock. Defaults to `--changed`.
 |---|---|
 | `--changed` (default) | Re-parses files whose **content** changed (git status + file-hash diff) **and** any shard whose stored extractor-config / grammar / engine hashes no longer match the current ones (i.e. `stale_extractor` / `stale_grammar`). A config or grammar bump is therefore healed by this cheap path — not only by `--all`. Compaction is limited to git-proven deletes. |
 | `--all` | Enumerates every supported file, re-parses, and performs full orphan compaction (drops shards whose file is gone or now ignored). |
+| `--scope changed\|all` | Uses the same scope spelling as MCP. Existing `--changed` / `--all` flags remain supported. |
 
 If a live writer already holds the project lock, `refresh` **fails fast** with a
 clear status rather than blocking — it never stalls `bclaw_work`.
@@ -70,6 +74,7 @@ clear status rather than blocking — it never stalls `bclaw_work`.
 ```bash
 brainclaw code-map refresh            # changed (cheap, default)
 brainclaw code-map refresh --all      # full rebuild + compaction
+brainclaw code-map refresh --scope changed
 ```
 
 ### `brainclaw code-map find <query>`
@@ -126,11 +131,15 @@ all return a `freshness_badge`:
 
 | Tool | Kind | Purpose |
 |---|---|---|
-| `bclaw_code_status` | read | Active-session project store, freshness, index stats; `cascade=true` also follows the latest cascade job. Never refreshes. |
-| `bclaw_code_find` | read | Ranked symbol-index search (`query`, optional `limit`). Never refreshes. |
-| `bclaw_code_brief` | read | Reading brief for a symbol/path (`target`, optional `limit`, files capped at 12). Never refreshes. |
+| `bclaw_code_status` | read | Active-session or explicit `project` store/path/index diagnostics, freshness, stats, and latest refresh job; `cascade=true` also follows the latest cascade job. Never refreshes. |
+| `bclaw_code_find` | read | Ranked symbol-index search (`query`, optional `limit`/`project`). Never refreshes. |
+| `bclaw_code_brief` | read | Reading brief for a symbol/path (`target`, optional `limit`/`project`, 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"`; MCP `cascade=true` starts a durable background job and returns immediately. |
+| `bclaw_code_refresh` | write | Accept a durable background rebuild and return immediately. `scope` = `"changed"` (default) or `"all"`; optional `project` targets a named/id/path project, and `cascade=true` spans a workspace. |
+
+Every MCP Code Map tool accepts the same optional `project` selector (project
+name, id, or workspace-relative path). It overrides the active session for that
+call without mutating the session.
 
 The read tools never trigger a parse — if `bclaw_code_status` /
 `bclaw_code_find` / `bclaw_code_brief` report `missing_index` or a stale badge,
@@ -186,9 +195,9 @@ reconciliation at the read path:
    file-hash diff vs the stored shards), so a stale index is always *visible*,
    never silently wrong.
 3. `refresh --changed` re-parses only the changed files (incremental); `--all` does
-   a full rebuild + orphan compaction. The one bounded background path is an
-   explicitly requested MCP monorepo cascade, whose durable progress is read
-   through `bclaw_code_status(cascade=true)`.
+   a full rebuild + orphan compaction. MCP refreshes are explicit durable jobs;
+   their progress is read through `bclaw_code_status` (or
+   `bclaw_code_status(cascade=true)` for a workspace cascade).
 4. `bclaw_work` nudges a refresh when the badge is `missing_index` or stale, so an
    agent knows to reconcile before trusting the map.
 
@@ -219,10 +228,12 @@ like any other directory.
 Both CLI and MCP status responses disclose the exact resolved project root and
 Code Map store path. The MCP response additionally includes `active_source`, the
 resolved project identity, the running server version, and the package version
-visible on disk. In a monorepo, compare these fields before concluding that an
-index is missing: a root store and a child store are intentionally distinct. If
-the versions differ, restart the MCP server; if the roots differ, select the
-intended project/session (or pass `cascade=true` at the workspace root).
+visible on disk. `store_exists` describes the physical directory;
+`index_exists` describes a valid readable manifest. In a monorepo, compare
+these fields before concluding that an index is missing: a root store and a
+child store are intentionally distinct. If the versions differ, restart the
+MCP server; if the roots differ, use `project="<name-or-path>"`, select the
+intended session project, or pass `cascade=true` at the workspace root.
 
 ### Cascading a multi-project workspace (`--cascade`)
 
@@ -242,9 +253,10 @@ double-indexing**, even when projects nest inside one another. `--cascade` is
 opt-in; without it, the root refresh keeps its single-tree behaviour (above), and
 single-project repos ignore the flag entirely.
 
-The CLI cascade stays synchronous. MCP `bclaw_code_refresh(cascade=true)` returns
-a durable `job_id` immediately, avoiding the client timeout that a large workspace
-can hit; follow it with `bclaw_code_status(cascade=true)`. Status reports completed
+The CLI cascade stays synchronous. Every MCP refresh returns a durable `job_id`
+immediately, avoiding client timeouts; follow a normal refresh with
+`bclaw_code_status(project=...)`, or a cascade with
+`bclaw_code_status(cascade=true)`. Status reports completed
 and total project counts, the project currently being indexed, and terminal
 outcomes. Successful rows are aggregated; only exceptions are named. A project
 with a valid empty index is labeled `no_eligible_files`, while lock contention and

package/docs/integrations/mcp.md

@@ -109,13 +109,13 @@ Each tool also has an `annotations.category` field: `session`, `context`, `memor
 | `bclaw_remove` | memory | Archive or purge a canonical entity |
 | `bclaw_transition` | memory | Move an entity through its validated state machine |
 | `bclaw_move` | memory | Relocate an item to another project, id-preserving (multi-project) |
-| `bclaw_code_status` | discovery | Active-session Code Map freshness + stats; `cascade:true` follows durable monorepo refresh progress and exceptions |
-| `bclaw_code_find` | discovery | Search the Code Map symbol index by name (function/class/component/hook/type) |
-| `bclaw_code_brief` | discovery | Ranked reading list + related decisions/traps before editing a symbol or path |
+| `bclaw_code_status` | discovery | Active-session or explicit `project` Code Map path/index diagnostics + freshness/stats; follows durable refresh jobs, with `cascade:true` for workspace progress |
+| `bclaw_code_find` | discovery | Search the active or explicit `project` Code Map symbol index by name |
+| `bclaw_code_brief` | discovery | Ranked reading list + related decisions/traps before editing a symbol or path, optionally targeted by `project` |
 | `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`); `cascade:true` starts a durable background job |
+| `bclaw_code_refresh` | discovery | Accept a durable Code Map rebuild (`scope: changed \| all`, optional `project`) and return immediately; `cascade:true` spans a workspace |
 
 See [code map](../code-map.md) for the full Code Map reference (CLI, freshness model, supported languages).
 

package/docs/mcp-schema-changelog.md

@@ -8,6 +8,25 @@ guarantees this changelog follows.
 
 ---
 
+## [1.28.5] — 2026-08-28
+
+- MCP public surface fingerprint: `sha256:f410416669e7fc9a`
+
+**Changed — Code Map project targeting and durable refresh**
+
+- Every `bclaw_code_*` input schema gains the same optional `project` selector
+  (name, id, or workspace-relative path). It overrides the active session for
+  one call without mutating it.
+- `bclaw_code_refresh` now acknowledges every refresh as a durable job, not
+  only multi-project cascades. Its `scope: "changed" | "all"` contract is
+  unchanged and no new field is required.
+- `bclaw_code_status` keeps its input compatibility while its result separates
+  physical path presence (`store_exists`) from a readable index
+  (`index_exists`, `index_manifest_exists`) and exposes the latest single-project
+  refresh job.
+
+All input changes are additive; no tool was added, removed, or renamed.
+
 ## [1.28.4] — 2026-08-28
 
 - MCP public surface fingerprint: `sha256:42cd662667260792`
@@ -475,8 +494,10 @@ 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:42cd662667260792`
-  (updated 2026-08-28 for the additive `bclaw_harvest` surface, sequential
+- MCP public surface fingerprint: `sha256:f410416669e7fc9a`
+  (updated 2026-08-28 for optional `project` targeting on every Code Map MCP
+  tool. Previous: `sha256:42cd662667260792`, updated for the additive
+  `bclaw_harvest` surface, sequential
   ideation controls, compact read projections, and loop-slot perspective and
   completion fields.)
   Previous: `sha256:be86e5571fcd0226`

package/package.json

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