brainclaw 1.28.2 → 1.28.3

package/dist/commands/mcp-catalog.js

@@ -374,7 +374,7 @@ export const MCP_READ_TOOLS = [
     },
     {
         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. In a multi-project workspace, cascade=true adds a per-child recap (which nested projects have a built index vs missing_index).',
+        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.',
         annotations: { tier: 'standard', category: 'discovery', headlessApproval: 'auto' },
         inputSchema: {
             type: 'object',
@@ -459,7 +459,7 @@ export const MCP_READ_TOOLS = [
 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. In a multi-project workspace, cascade=true refreshes EVERY nested project into its own store + the root store scoped to files no child owns (zero double-indexing) — so one call at the root indexes the whole monorepo per-project.',
+        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.',
         annotations: { tier: 'standard', category: 'discovery', headlessApproval: 'prompt' },
         inputSchema: {
             type: 'object',

package/dist/commands/mcp-write-coordination.js

@@ -12,6 +12,7 @@
  * @module
  */
 import crypto from 'node:crypto';
+import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { buildClaimEnvPrefix } from '../core/execution-profile.js';
 import { resolveProjectCwd } from '../core/cross-project.js';
@@ -387,9 +388,17 @@ export async function handleBclawCoordinate(args, ctx) {
     // for state-mutating helpers; the outer `cwd` (source) stays in scope
     // for the few cases that genuinely need source attribution.
     const dispatchCwd = resolveProjectCwd(req.project, cwd);
-    const isCrossProject = dispatchCwd !== cwd;
+    const isCrossProject = path.resolve(dispatchCwd) !== path.resolve(cwd);
     if (isCrossProject && req.autoExecute !== false) {
-        warnings.push(`cross-project dispatch (project='${req.project}') — auto-spawn disabled; the target agent picks up the brief async via its own bclaw_work.`);
+        return {
+            response: createToolErrorResponse('cross_project_auto_execute_unsupported', `cross-project dispatch (project='${req.project}') cannot auto-execute from the source process; admission refused before creating a claim, assignment, or loop.`, {
+                next_actions: [{
+                        tool: 'bclaw_coordinate',
+                        args: { ...req, autoExecute: false },
+                        when: 'create an inbox-only cross-project assignment that the target agent will pick up with bclaw_work',
+                    }],
+            }),
+        };
     }
     const effectiveAutoExecute = isCrossProject ? false : req.autoExecute;
     // pln#692 P0 — an explicit checkout ref is part of admission, not worktree
@@ -1008,7 +1017,7 @@ export async function handleBclawCoordinate(args, ctx) {
         // existing length===0 guard skips loop creation. Skipped when open_loop
         // is off, preflight=false, or BRAINCLAW_NO_SPAWN is set (handled inside
         // preflightAgents). Cross-project dispatch never auto-spawns, so skip.
-        if (req.open_loop === true && req.preflight !== false && !req.project && loopReviewerAgents.length > 0) {
+        if (req.open_loop === true && req.preflight !== false && !isCrossProject && loopReviewerAgents.length > 0) {
             try {
                 const { preflightAgents } = await import('../core/spawn-check.js');
                 const pf = await preflightAgents(loopReviewerAgents, { cwd: dispatchCwd });
@@ -1158,7 +1167,7 @@ export async function handleBclawCoordinate(args, ctx) {
                         // (that is the double-spawn hole), and do NOT release the (possibly shared) claim; leave
                         // the slot for reconcile/self-heal. LEGACY: the unchanged inline mint runs.
                         let usedTurnOwned = false;
-                        if (turnOwnedReviewEnabled() && !req.project) {
+                        if (turnOwnedReviewEnabled() && !isCrossProject) {
                             const prep = prepareTurnOwnedReviewDispatch({
                                 loopId: loop.id,
                                 slotId: slot.slot_id,

package/dist/commands/mcp-write-entities.js

@@ -479,9 +479,12 @@ export function handleBclawCreate(payload, ctx) {
         const result = createEntity(entity, data, targetCwd);
         appendAuditEntry({ actor: actor ?? 'unknown', ...(actorId ? { actor_id: actorId } : {}), action: 'create', item_id: result.id, item_type: entity }, targetCwd);
         const createText = `✔ created ${entity} ${result.id}${autoSwitched ? ` (auto-switched → ${targetScope.resolved_project.name ?? targetScope.resolved_project.path})` : ''}`;
+        const proximityText = result.nearby_items?.length
+            ? `Nearby existing ${entity} item(s): ${result.nearby_items.map((item) => `${item.id} (${item.reason})`).join(', ')}. Creation was kept; review before adding another duplicate.`
+            : undefined;
         const createContent = autoRepair
-            ? [{ type: 'text', text: createText }, { type: 'text', text: renderAutoRepairWarning(autoRepair, actor ?? 'unknown') }]
-            : [{ type: 'text', text: createText }];
+            ? [{ type: 'text', text: createText }, { type: 'text', text: renderAutoRepairWarning(autoRepair, actor ?? 'unknown') }, ...(proximityText ? [{ type: 'text', text: proximityText }] : [])]
+            : [{ type: 'text', text: createText }, ...(proximityText ? [{ type: 'text', text: proximityText }] : [])];
         // pln#634 — a freshly created plan whose steps are never added is the most
         // common half-finished shape in the store; a sequence with no readiness
         // check is the second. Only those two emit a follow-up.

package/dist/commands/mcp.js

@@ -1096,8 +1096,10 @@ async function _executeMcpToolCallInner(payload) {
         if (name === 'bclaw_code_status' || name === 'bclaw_code_find' || name === 'bclaw_code_brief' || name === 'bclaw_code_impact' || name === 'bclaw_code_export' || name === 'bclaw_code_outline' || name === 'bclaw_code_refresh') {
             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;
             if (name === 'bclaw_code_status') {
-                const status = await be.status({ cwd, cascade: args.cascade === true });
+                const status = await be.status({ cwd: codeCwd, cascade: args.cascade === true });
                 const diskVersion = readDiskBrainclawVersion();
                 return {
                     response: toolResponse({
@@ -1118,7 +1120,23 @@ async function _executeMcpToolCallInner(payload) {
             }
             if (name === 'bclaw_code_refresh') {
                 const scope = args.scope === 'all' ? 'all' : 'changed';
-                const result = await be.refresh({ scope, cwd, cascade: args.cascade === true });
+                if (args.cascade === true) {
+                    const { startCascadeRefreshJob, summarizeCascadeRefreshJob } = await import('../core/code-map/cascade-jobs.js');
+                    const job = startCascadeRefreshJob(codeCwd, scope);
+                    if (job) {
+                        return {
+                            response: toolResponse({
+                                content: [{ type: 'text', text: `Code Map cascade started: job=${job.job_id}, projects=${job.projects_total}. Follow with bclaw_code_status(cascade=true).` }],
+                                structuredContent: {
+                                    started: true,
+                                    ...summarizeCascadeRefreshJob(job),
+                                    next_actions: [{ tool: 'bclaw_code_status', args: { cascade: true }, when: 'follow progress and terminal per-project diagnostics' }],
+                                },
+                            }),
+                        };
+                    }
+                }
+                const result = await be.refresh({ scope, cwd: codeCwd, cascade: args.cascade === true });
                 const cascadeNote = result.cascade ? ` cascade=${result.cascade.children_refreshed} child(ren)+root` : '';
                 return {
                     response: toolResponse({
@@ -1133,7 +1151,7 @@ async function _executeMcpToolCallInner(payload) {
                     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 });
+                const result = await be.find({ query, limit, cwd: codeCwd });
                 return {
                     response: toolResponse({
                         content: [{ type: 'text', text: `Code Map find "${result.query}": ${result.matches.length} match(es), freshness=${result.freshness_badge.freshness}` }],
@@ -1154,7 +1172,7 @@ async function _executeMcpToolCallInner(payload) {
                 const maxEdges = typeof args.maxEdges === 'number' ? args.maxEdges : undefined;
                 const minConfidence = typeof args.minConfidence === 'number' ? args.minConfidence : undefined;
                 const format = args.format === 'mermaid' ? 'mermaid' : args.format === 'json' ? 'json' : undefined;
-                const result = await be.exportGraph({ target, targetKind, direction, depth, maxNodes, maxEdges, minConfidence, format, cwd });
+                const result = await be.exportGraph({ target, targetKind, direction, depth, maxNodes, maxEdges, minConfidence, format, cwd: codeCwd });
                 return {
                     response: toolResponse({
                         content: [{ type: 'text', text: `Code Map export "${result.target}": ${result.nodes.length} node(s), ${result.edges.length} edge(s), depth=${result.limits.max_depth}, freshness=${result.freshness_badge.freshness}` }],
@@ -1170,7 +1188,7 @@ async function _executeMcpToolCallInner(payload) {
                 }
                 const depth = typeof args.depth === 'number' ? args.depth : undefined;
                 const limit = typeof args.limit === 'number' ? args.limit : undefined;
-                const result = await be.impact({ target, depth, limit, cwd });
+                const result = await be.impact({ target, depth, limit, cwd: codeCwd });
                 return {
                     response: toolResponse({
                         content: [{ type: 'text', text: `Code Map impact "${result.target}": ${result.risk.counters.direct_dependents} direct, ${result.risk.counters.transitive_dependents} transitive dependent(s), risk=${result.risk.score}, freshness=${result.freshness_badge.freshness}` }],
@@ -1185,7 +1203,7 @@ async function _executeMcpToolCallInner(payload) {
                     return { response: createToolErrorResponse('validation_error', 'bclaw_code_outline requires a non-empty path.') };
                 }
                 const limit = typeof args.limit === 'number' ? args.limit : undefined;
-                const result = await be.outline({ path: outlinePath, limit, cwd });
+                const result = await be.outline({ path: outlinePath, limit, cwd: codeCwd });
                 return {
                     response: toolResponse({
                         content: [{ type: 'text', text: `Code Map outline "${result.path}": ${result.symbols.length}/${result.symbol_count} symbol(s), index=${result.index_status}, freshness=${result.freshness_badge.freshness}` }],
@@ -1199,7 +1217,7 @@ async function _executeMcpToolCallInner(payload) {
                 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 });
+            const result = await be.brief({ target, limit, cwd: codeCwd });
             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.freshness}` }],

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

@@ -183,10 +183,9 @@ function statusRank(s) {
     }
 }
 /**
- * Merge per-store badges into one workspace badge: worst status among the INDEXED
- * stores (a missing-index child contributes to coverage, never drags the top-line),
- * plus coverage + workspace-relative detail path-sets. Only when EVERY store is
- * un-indexed is the whole workspace `missing_index`.
+ * Merge per-store badges into one workspace badge. Missing child indexes are a
+ * PARTIAL workspace, never a fresh one: serving the indexed subset is useful,
+ * but the top-line signal must describe the coverage actually searched.
  */
 function mergeBadges(perStore) {
     const total = perStore.length;
@@ -202,14 +201,28 @@ function mergeBadges(perStore) {
         if (statusRank(p.badge.status) > statusRank(worst))
             worst = p.badge.status;
     }
+    if (unindexed.length > 0)
+        worst = 'partial';
+    const statusCounts = {};
+    for (const p of perStore) {
+        const status = p.hasIndex ? p.badge.status : 'missing_index';
+        statusCounts[status] = (statusCounts[status] ?? 0) + 1;
+    }
+    const exceptionalProjects = perStore
+        .filter((p) => p.hasIndex && p.badge.status !== 'fresh')
+        .map((p) => ({ path: p.ref.relPath || '.', status: p.badge.status }));
     const details = {
         traversal: 'workspace',
         projects_indexed: indexed.length,
         projects_total: total,
-        per_project: Object.fromEntries(perStore.map((p) => [p.ref.relPath || '.', p.badge.status])),
+        project_status_counts: statusCounts,
     };
-    if (unindexed.length)
+    if (unindexed.length) {
+        details.unindexed_project_count = unindexed.length;
         details.unindexed_projects = unindexed;
+    }
+    if (exceptionalProjects.length)
+        details.non_fresh_projects = exceptionalProjects;
     const prefixMerge = (key) => {
         const out = [];
         for (const p of indexed) {
@@ -259,7 +272,7 @@ export function aggregateFind(query, limit, resolved, currentHead) {
         const r = findInStore(query, { cwd: ref.cwd }, checker, acc);
         // Per-store badge: drive `partial` from THIS store's own budget-skips (review F2),
         // NOT the shared checker.exhausted flag — else an early store spending the budget
-        // would mislabel every fully-fresh later store as `partial` in per_project. Then
+        // would mislabel every fully-fresh later store as `partial` in diagnostics. Then
         // apply per-store HEAD drift against the one workspace HEAD (review F3) so a child
         // whose index lags the working tree is flagged even under an otherwise-fresh root.
         let badge = deriveBadge(r.base, acc, false, r.matches.length > 0, r.emptyCandidates);

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

@@ -19,7 +19,8 @@ import { exportSubgraph } from './export.js';
 import { fileId } from './ids.js';
 import { resolveTraversal, aggregateFind, aggregateBrief } from './aggregate.js';
 import { defaultMemoryReader } from './memory-reader.js';
-import { listNestedProjects, refreshWorkspaceCascade } from './cascade.js';
+import { inspectNestedProjects, refreshWorkspaceCascade } from './cascade.js';
+import { latestCascadeRefreshJob, summarizeCascadeRefreshJob } from './cascade-jobs.js';
 import { loadConfig } from '../config.js';
 import { codeMapDir } from './paths.js';
 /** spec §9 caps the brief reading list at 12 files. */
@@ -112,17 +113,26 @@ function isMultiProjectWorkspace(cwd) {
 /** Per-child store recap for `status(cascade)` in a multi-project workspace. */
 function buildCascadeStatus(rootCwd) {
     const root = rootCwd ?? process.cwd();
-    const children = listNestedProjects(root).map((abs) => {
+    const discovery = inspectNestedProjects(root);
+    const children = discovery.projects.map((abs) => {
         const m = readManifest(abs);
         return {
             path: path.relative(root, abs).replace(/\\/g, '/') || '.',
             store_exists: m ? true : storeExists(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' } : {}),
         };
     });
     const indexed = children.filter((c) => c.freshness !== 'missing_index').length;
-    return { children, indexed_children: indexed, total_children: children.length };
+    const latestJob = latestCascadeRefreshJob(root);
+    return {
+        children,
+        indexed_children: indexed,
+        total_children: children.length,
+        discovery_truncated: discovery.truncated,
+        ...(latestJob ? { refresh_job: summarizeCascadeRefreshJob(latestJob) } : {}),
+    };
 }
 /**
  * P0 JSONL-backed query backend. Reads the durable file store (manifest +
@@ -198,17 +208,17 @@ export class JsonlBackend {
             // A cascade is only fully "acquired" when EVERY project got its lock; if a
             // child or the root was skipped under a live writer, surface that instead
             // of reporting a clean lock_acquired=true over a partial cascade (codex review).
-            const skipped = allProjects.filter((p) => !p.lock_acquired);
+            const incomplete = allProjects.filter((p) => p.outcome === 'locked' || p.outcome === 'failed');
             return {
                 ran: allProjects.some((p) => p.ran),
                 scope,
-                lock_acquired: skipped.length === 0,
+                lock_acquired: incomplete.length === 0,
                 freshness_badge: badge(root.freshness, {
                     files_parsed: root.files_parsed,
                     children_refreshed: cascade.children_refreshed,
                 }),
-                ...(skipped.length > 0
-                    ? { lock_status: `${skipped.length} project(s) skipped (lock held): ${skipped.map((p) => p.path).join(', ')}` }
+                ...(incomplete.length > 0
+                    ? { lock_status: `${incomplete.length} project(s) incomplete: ${incomplete.map((p) => `${p.path} (${p.outcome})`).join(', ')}` }
                     : {}),
                 cascade,
             };

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

@@ -0,0 +1,174 @@
+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 { loadConfig } from '../config.js';
+import { writeFileAtomic } from '../io.js';
+import { codeMapDir } from './paths.js';
+import { inspectNestedProjects, refreshWorkspaceCascade } from './cascade.js';
+export function summarizeCascadeRefreshJob(job) {
+    const { result, ...summary } = job;
+    if (!result)
+        return summary;
+    const projects = [result.root_result, ...result.children];
+    const outcomeCounts = {};
+    for (const project of projects)
+        outcomeCounts[project.outcome] = (outcomeCounts[project.outcome] ?? 0) + 1;
+    const problemProjects = projects
+        .filter((project) => project.outcome !== 'indexed')
+        .map((project) => ({ path: project.path, outcome: project.outcome, ...(project.reason ? { reason: project.reason } : {}), ...(project.error ? { error: project.error } : {}) }));
+    return { ...summary, outcome_counts: outcomeCounts, ...(problemProjects.length ? { problem_projects: problemProjects } : {}) };
+}
+function jobsDir(root) {
+    return path.join(codeMapDir(root), 'cascade-jobs');
+}
+function jobPath(root, jobId) {
+    return path.join(jobsDir(root), `${jobId}.json`);
+}
+function writeJob(job) {
+    const dir = jobsDir(job.root);
+    fs.mkdirSync(dir, { recursive: true });
+    const target = jobPath(job.root, job.job_id);
+    writeFileAtomic(target, `${JSON.stringify(job, null, 2)}\n`);
+}
+export function readCascadeRefreshJob(root, jobId) {
+    try {
+        return JSON.parse(fs.readFileSync(jobPath(path.resolve(root), jobId), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function latestCascadeRefreshJob(root) {
+    const dir = jobsDir(path.resolve(root));
+    try {
+        const jobs = fs.readdirSync(dir)
+            .filter((name) => name.endsWith('.json'))
+            .map((name) => {
+            try {
+                return JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8'));
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((job) => job !== null)
+            .sort((a, b) => b.updated_at.localeCompare(a.updated_at));
+        return jobs[0] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function processAlive(pid) {
+    if (!pid)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function startCascadeRefreshJob(root, scope) {
+    const resolvedRoot = path.resolve(root);
+    try {
+        if (loadConfig(resolvedRoot).project_mode !== 'multi-project')
+            return null;
+    }
+    catch {
+        return null;
+    }
+    const previous = latestCascadeRefreshJob(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,
+        projects_total: inspectNestedProjects(resolvedRoot).projects.length + 1,
+        projects_completed: 0,
+        current_project: null,
+    };
+    writeJob(job);
+    const worker = fileURLToPath(new URL('./cascade-worker.js', import.meta.url));
+    const child = spawn(process.execPath, [worker, resolvedRoot, job.job_id, scope], {
+        cwd: resolvedRoot,
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+    });
+    const markWorkerExit = (detail) => {
+        const current = readCascadeRefreshJob(resolvedRoot, job.job_id);
+        if (!current || current.status === 'completed' || current.status === 'failed')
+            return;
+        const completed = new Date().toISOString();
+        writeJob({
+            ...current,
+            status: 'failed',
+            error: detail,
+            current_project: null,
+            completed_at: completed,
+            updated_at: completed,
+        });
+    };
+    child.once('error', (error) => {
+        markWorkerExit(`cascade worker failed to start: ${error.message}`);
+    });
+    child.once('exit', (code, signal) => {
+        // The worker writes its terminal state synchronously before exiting. If no
+        // terminal state exists here, the launch/runtime failed outside its guard.
+        markWorkerExit(`cascade worker exited before completion (code=${code ?? 'null'}, signal=${signal ?? 'none'})`);
+    });
+    child.unref();
+    const current = readCascadeRefreshJob(resolvedRoot, job.job_id) ?? job;
+    if (current.status === 'queued') {
+        current.pid = child.pid;
+        current.updated_at = new Date().toISOString();
+        writeJob(current);
+    }
+    return current;
+}
+/** Worker entry seam, exported for deterministic tests and the tiny worker file. */
+export async function runCascadeRefreshJob(root, jobId, scope) {
+    const job = readCascadeRefreshJob(root, jobId);
+    if (!job)
+        throw new Error(`cascade job not found: ${jobId}`);
+    const started = new Date().toISOString();
+    writeJob({ ...job, status: 'running', pid: process.pid, started_at: started, updated_at: started });
+    try {
+        const result = await refreshWorkspaceCascade({
+            rootCwd: root,
+            scope,
+            onProgress: (progress) => {
+                const current = readCascadeRefreshJob(root, jobId) ?? job;
+                writeJob({
+                    ...current,
+                    status: 'running',
+                    pid: process.pid,
+                    projects_total: progress.total,
+                    projects_completed: progress.completed,
+                    current_project: progress.current_project,
+                    ...(progress.last_result ? { last_result: progress.last_result } : {}),
+                    updated_at: new Date().toISOString(),
+                });
+            },
+        });
+        const current = readCascadeRefreshJob(root, jobId) ?? job;
+        const completed = new Date().toISOString();
+        writeJob({ ...current, status: 'completed', result, current_project: null, projects_completed: current.projects_total, completed_at: completed, updated_at: completed });
+    }
+    catch (error) {
+        const current = readCascadeRefreshJob(root, jobId) ?? job;
+        const completed = new Date().toISOString();
+        writeJob({ ...current, status: 'failed', error: error instanceof Error ? error.message : String(error), current_project: null, completed_at: completed, updated_at: completed });
+    }
+}
+//# sourceMappingURL=cascade-jobs.js.map

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

@@ -0,0 +1,15 @@
+import { runCascadeRefreshJob } from './cascade-jobs.js';
+const [root, jobId, rawScope] = process.argv.slice(2);
+if (!root || !jobId)
+    process.exit(2);
+const scope = rawScope === 'all' ? 'all' : 'changed';
+try {
+    await runCascadeRefreshJob(root, jobId, scope);
+    // Tree-sitter/native handles can keep Node's event loop alive after the
+    // durable terminal record has been flushed. This process owns no other work.
+    process.exit(0);
+}
+catch {
+    process.exit(1);
+}
+//# sourceMappingURL=cascade-worker.js.map

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

@@ -20,7 +20,7 @@
  * refreshes existing brainclaw projects, it does not initialise new ones.
  */
 import path from 'node:path';
-import { scanNestedBrainclawProjects } from '../workspace-projects.js';
+import { scanNestedBrainclawProjectsDetailed } from '../workspace-projects.js';
 import { loadConfig } from '../config.js';
 import { refresh as runRefresh } from './refresh.js';
 import { readManifest } from './store.js';
@@ -54,10 +54,14 @@ function projectIdFor(cwd, fallbackId) {
  * cascade and the `status --cascade` recap so both agree on the project set.
  */
 export function listNestedProjects(rootCwd) {
+    return inspectNestedProjects(rootCwd).projects;
+}
+export function inspectNestedProjects(rootCwd) {
     const root = path.resolve(rootCwd);
-    return Array.from(new Set(scanNestedBrainclawProjects(root)
-        .map((c) => path.resolve(c.path))
-        .filter((abs) => abs !== root && isStrictlyUnder(abs, root)))).sort();
+    const discovered = scanNestedBrainclawProjectsDetailed(root);
+    return { projects: Array.from(new Set(discovered.projects
+            .map((c) => path.resolve(c.path))
+            .filter((abs) => abs !== root && isStrictlyUnder(abs, root)))).sort(), truncated: discovered.truncated };
 }
 /**
  * Refresh the whole multi-project workspace: every nested brainclaw project +
@@ -68,7 +72,8 @@ export async function refreshWorkspaceCascade(input) {
     const rootCwd = path.resolve(input.rootCwd);
     // Enumerate nested brainclaw projects strictly under the root (FS scan, so it
     // is strategy-agnostic). De-dup + sort by path for deterministic output.
-    const childAbsPaths = listNestedProjects(rootCwd);
+    const discovery = inspectNestedProjects(rootCwd);
+    const childAbsPaths = discovery.projects;
     // Every project to refresh, root first.
     const allProjects = [rootCwd, ...childAbsPaths];
     const refreshOne = async (projectCwd, isRoot) => {
@@ -77,40 +82,72 @@ export async function refreshWorkspaceCascade(input) {
         const nestedUnder = allProjects.filter((p) => p !== projectCwd && isStrictlyUnder(p, projectCwd));
         const extraIgnorePatterns = nestedUnder.map((p) => `${toPosix(path.relative(projectCwd, p))}/**`);
         const projectId = projectIdFor(projectCwd);
-        const result = await runRefresh({
-            projectId,
-            projectRoot: projectCwd,
-            scope: input.scope,
-            cwd: projectCwd,
-            extraIgnorePatterns,
-            ownerAgent: input.ownerAgent ?? null,
-            ownerAgentId: input.ownerAgentId ?? null,
-        });
-        return {
-            path: isRoot ? '.' : toPosix(path.relative(rootCwd, projectCwd)),
-            project_id: projectId,
-            is_root: isRoot,
-            ran: result.ran,
-            lock_acquired: result.lock_acquired,
-            files_parsed: result.files_parsed,
-            files_compacted: result.files_compacted,
-            freshness: result.freshness.status,
-            ...(result.lock_status ? { lock_status: result.lock_status } : {}),
-        };
+        const projectPath = isRoot ? '.' : toPosix(path.relative(rootCwd, projectCwd));
+        try {
+            const result = await runRefresh({
+                projectId,
+                projectRoot: projectCwd,
+                scope: input.scope,
+                cwd: projectCwd,
+                extraIgnorePatterns,
+                ownerAgent: input.ownerAgent ?? null,
+                ownerAgentId: input.ownerAgentId ?? null,
+            });
+            const filesIndexed = readManifest(projectCwd)?.stats.files_indexed ?? 0;
+            const outcome = !result.lock_acquired
+                ? 'locked'
+                : filesIndexed === 0 ? 'no_eligible_files' : 'indexed';
+            return {
+                path: projectPath,
+                project_id: projectId,
+                is_root: isRoot,
+                ran: result.ran,
+                lock_acquired: result.lock_acquired,
+                files_parsed: result.files_parsed,
+                files_compacted: result.files_compacted,
+                files_indexed: filesIndexed,
+                freshness: result.freshness.status,
+                outcome,
+                ...(outcome === 'no_eligible_files' ? { reason: 'no eligible source files found' } : {}),
+                ...(result.lock_status ? { lock_status: result.lock_status, reason: result.lock_status } : {}),
+            };
+        }
+        catch (error) {
+            return {
+                path: projectPath,
+                project_id: projectId,
+                is_root: isRoot,
+                ran: false,
+                lock_acquired: false,
+                files_parsed: 0,
+                files_compacted: 0,
+                files_indexed: readManifest(projectCwd)?.stats.files_indexed ?? null,
+                freshness: 'partial',
+                outcome: 'failed',
+                reason: 'refresh_failed',
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
     };
     // Children first, then the root (sequential — each holds its own project lock
     // briefly; never blocks bclaw_work, rule 8).
     const children = [];
+    const total = childAbsPaths.length + 1;
+    input.onProgress?.({ completed: 0, total, current_project: childAbsPaths[0] ? toPosix(path.relative(rootCwd, childAbsPaths[0])) : '.' });
     for (const childCwd of childAbsPaths) {
-        children.push(await refreshOne(childCwd, false));
+        const result = await refreshOne(childCwd, false);
+        children.push(result);
+        input.onProgress?.({ completed: children.length, total, current_project: children.length < childAbsPaths.length ? toPosix(path.relative(rootCwd, childAbsPaths[children.length])) : '.', last_result: result });
     }
     const rootResult = await refreshOne(rootCwd, true);
+    input.onProgress?.({ completed: total, total, current_project: null, last_result: rootResult });
     return {
         is_cascade: true,
         root: rootCwd,
         root_result: rootResult,
         children,
         children_refreshed: children.length,
+        discovery_truncated: discovery.truncated,
     };
 }
 //# sourceMappingURL=cascade.js.map

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

@@ -232,7 +232,7 @@ export function isTestPath(p) {
 /**
  * Score a symbol index entry against the query. Matching is separator/case
  * INSENSITIVE (pln#601): an exact NORMALIZED match scores highest, then prefix,
- * then substring, then the sub-token floor. Exported symbols + components/hooks
+ * then substring; sub-token-only candidates score zero. Exported symbols + components/hooks
  * get a small boost; test-file symbols are biased DOWN so a test helper never
  * outranks the real definition of the same name (the Fable-audit brief-noise
  * companion to the find defect). Exported for focused ranking tests.
@@ -250,7 +250,7 @@ export function scoreEntry(entry, query) {
     else if (name.includes(q))
         score += 3; // substring
     else
-        score += 1; // matched only via a sub-token bucket
+        return 0; // shared-token noise is not a match
     score *= entry.score_hint; // exported (1.0) vs internal (0.8)
     if (entry.subtype === 'component' || entry.subtype === 'hook')
         score += 1;
@@ -367,6 +367,9 @@ export function findInStore(query, ctx, checker, acc) {
         const confident = validateEntry(entry, checker, acc, root, maxBytes, ctx.cwd, ctx.preferredDirName);
         if (!confident)
             continue;
+        const score = scoreEntry(entry, query);
+        if (score <= 0)
+            continue;
         ranked.push({
             match: {
                 node_id: entry.node_id,
@@ -375,7 +378,7 @@ export function findInStore(query, ctx, checker, acc) {
                 file_id: entry.file_id,
                 kind: entry.kind,
                 subtype: entry.subtype ?? null,
-                score: scoreEntry(entry, query),
+                score,
             },
             centrality: importCentrality(entry, resolutionIndex),
         });

package/dist/core/entity-operations.js

@@ -15,6 +15,7 @@
  */
 import path from 'node:path';
 import { loadState, mutateState } from './state.js';
+import { detectDuplicates } from './duplicates.js';
 import { archiveCandidate, listCandidates, loadCandidate, saveCandidate, } from './candidates.js';
 import { addCrossProjectLink, removeCrossProjectLink, resolveCrossProjectLinks, } from './cross-project.js';
 import { findActiveClaimsForPlan, listClaims, loadClaim, logCascadeReleaseResult, markClaimStale, releaseClaimsCascade, releaseClaimWithCascade, saveClaim, } from './claims.js';
@@ -511,6 +512,19 @@ export function getEntity(name, idOrShortLabel, cwd) {
 // ─── CREATE ────────────────────────────────────────────────────────────
 export function createEntity(name, data, cwd) {
     assertKnownEntity(name, 'create');
+    const proximityKinds = new Set(['decision', 'constraint', 'trap']);
+    const nearby = proximityKinds.has(name) && typeof data.text === 'string'
+        ? detectDuplicates(data.text, name, loadState(cwd), listCandidates(undefined, cwd).filter((candidate) => candidate.status === 'pending')).slice(0, 3).map((match) => ({
+            id: match.id,
+            source: match.source,
+            reason: match.reason,
+            preview: match.text.length > 160 ? `${match.text.slice(0, 157)}…` : match.text,
+        }))
+        : [];
+    const result = (base) => ({
+        ...base,
+        ...(nearby.length ? { nearby_items: nearby } : {}),
+    });
     switch (name) {
         case 'plan': {
             // Explicit field whitelist + required-author check brings plan create in line
@@ -530,7 +544,7 @@ export function createEntity(name, data, cwd) {
                 estimatedEffort: data.estimated_effort,
             }, cwd);
             stampProvenanceOnStateItem('plan', res.id, defaultProvenance(data), cwd);
-            return { entity: name, id: res.id, short_label: res.shortLabel };
+            return result({ entity: name, id: res.id, short_label: res.shortLabel });
         }
         case 'decision': {
             const res = createDecision({
@@ -542,7 +556,7 @@ export function createEntity(name, data, cwd) {
                 planId: data.plan_id,
             }, cwd);
             stampProvenanceOnStateItem('decision', res.id, defaultProvenance(data), cwd);
-            return { entity: name, id: res.id, short_label: res.shortLabel };
+            return result({ entity: name, id: res.id, short_label: res.shortLabel });
         }
         case 'constraint': {
             const res = createConstraint({
@@ -553,7 +567,7 @@ export function createEntity(name, data, cwd) {
                 relatedPaths: data.related_paths,
             }, cwd);
             stampProvenanceOnStateItem('constraint', res.id, defaultProvenance(data), cwd);
-            return { entity: name, id: res.id, short_label: res.shortLabel };
+            return result({ entity: name, id: res.id, short_label: res.shortLabel });
         }
         case 'trap': {
             const res = createTrap({
@@ -564,7 +578,7 @@ export function createEntity(name, data, cwd) {
                 relatedPaths: data.related_paths,
             }, cwd);
             stampProvenanceOnStateItem('trap', res.id, defaultProvenance(data), cwd);
-            return { entity: name, id: res.id, short_label: res.shortLabel };
+            return result({ entity: name, id: res.id, short_label: res.shortLabel });
         }
         case 'runtime_note': {
             const id = generateId('runtime_note');

package/dist/core/execution-adapters.js

@@ -213,6 +213,12 @@ export function withCodexWorkspaceRoot(invoke, agent, worktreePath, isWin32 = pr
     }
     return { ...invoke, args, bashCommand };
 }
+/** Refuse a stdin-delivery invoke that would otherwise inherit `/dev/null`. */
+export function assertPromptDelivery(invoke) {
+    if (invoke.promptDelivery === 'stdin_pipe' && !invoke.promptText?.trim()) {
+        throw new Error('Invalid stdin_pipe invocation: promptText is empty; refusing to spawn an agent with ignored stdin.');
+    }
+}
 export class CliExecutionAdapter {
     id = 'cli';
     canSpawn(agentName) {
@@ -281,6 +287,7 @@ export class CliExecutionAdapter {
         };
     }
     start(invoke, options) {
+        assertPromptDelivery(invoke);
         const isWin32 = process.platform === 'win32';
         invoke = withCodexWorkspaceRoot(invoke, options.agent, options.worktreePath, isWin32);
         // F7 (trp_0e5150d3): route worker env through buildWorkerIdentityEnv so the
@@ -317,7 +324,7 @@ export class CliExecutionAdapter {
         }
         const spawnExecutable = resolvedExecutable ?? invoke.executable;
         const useShell = isWin32 && /\.(cmd|bat)$/i.test(spawnExecutable);
-        const needsStdin = invoke.promptDelivery === 'stdin_pipe' && invoke.promptText;
+        const needsStdin = invoke.promptDelivery === 'stdin_pipe';
         // pln#520 step 4: when we ack-wrap, the SHELL redirects stdout/stderr to the
         // per-assignment log files (fds passed via stdio are NOT inherited through
         // the cmd.exe → .cmd → node shim — the empty-logs bug of can_f792cacd), and

package/dist/core/spawn-check.js

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

package/dist/facts.js

@@ -1,8 +1,8 @@
 // Generated by scripts/emit-site-facts.mjs at build time. Do not edit manually.
-// Source: brainclaw v1.28.2 on 2026-08-25T18:22:09.950Z
+// Source: brainclaw v1.28.3 on 2026-08-25T23:07:33.877Z
 export const FACTS = {
-  "version": "1.28.2",
-  "generated_at": "2026-08-25T18:22:09.950Z",
+  "version": "1.28.3",
+  "generated_at": "2026-08-25T23:07:33.877Z",
   "tools": {
     "count": 70,
     "published_count": 68,
@@ -478,7 +478,7 @@ export const FACTS = {
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-25T18:22:07.761Z",
+    "generated_at": "2026-08-25T23:07:31.792Z",
     "node_version": "v24.19.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -487,7 +487,7 @@ export const FACTS = {
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 82,
+        "duration_ms_median": 79,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -495,7 +495,7 @@ export const FACTS = {
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 132,
+        "duration_ms_median": 122,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },
@@ -503,7 +503,7 @@ export const FACTS = {
         "name": "first_edit",
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
-        "duration_ms_median": 13,
+        "duration_ms_median": 11,
         "payload_chars_median": 1629,
         "payload_tokens_est_median": 407
       }

package/dist/facts.json

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

package/docs/cli.md

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

package/docs/code-map.md

@@ -126,11 +126,11 @@ all return a `freshness_badge`:
 
 | Tool | Kind | Purpose |
 |---|---|---|
-| `bclaw_code_status` | read | Store presence, freshness badge, index stats. Never refreshes. |
+| `bclaw_code_status` | read | Active-session project store, freshness, index stats; `cascade=true` also follows the latest cascade job. Never refreshes. |
 | `bclaw_code_find` | read | Ranked symbol-index search (`query`, optional `limit`). Never refreshes. |
 | `bclaw_code_brief` | read | Reading brief for a symbol/path (`target`, optional `limit`, files capped at 12). Never refreshes. |
 | `bclaw_code_export` | read | Bounded local subgraph around required `target`; direction/depth/node/edge caps, confidence filtering, and optional Mermaid projection. Never refreshes. |
-| `bclaw_code_refresh` | write | Rebuild the index. `scope` = `"changed"` (default) or `"all"`. Fails fast on a live lock. |
+| `bclaw_code_refresh` | write | Rebuild the index. `scope` = `"changed"` (default) or `"all"`; MCP `cascade=true` starts a durable background job and returns immediately. |
 
 The read tools never trigger a parse — if `bclaw_code_status` /
 `bclaw_code_find` / `bclaw_code_brief` report `missing_index` or a stale badge,
@@ -178,7 +178,7 @@ No read command parses files or refreshes the index. `bclaw_work` can suggest
 that explicit refresh, but never performs it lazily.
 ## Lifecycle — pull-based, no daemon
 
-Code Map never runs in the background and never auto-reindexes. The model is lazy
+Code Map never auto-reindexes and has no daemon. The model is lazy
 reconciliation at the read path:
 
 1. You edit or pull code — the index does not change.
@@ -186,7 +186,9 @@ reconciliation at the read path:
    file-hash diff vs the stored shards), so a stale index is always *visible*,
    never silently wrong.
 3. `refresh --changed` re-parses only the changed files (incremental); `--all` does
-   a full rebuild + orphan compaction.
+   a full rebuild + orphan compaction. The one bounded background path is an
+   explicitly requested MCP monorepo cascade, whose durable progress is read
+   through `bclaw_code_status(cascade=true)`.
 4. `bclaw_work` nudges a refresh when the badge is `missing_index` or stale, so an
    agent knows to reconcile before trusting the map.
 
@@ -240,9 +242,15 @@ double-indexing**, even when projects nest inside one another. `--cascade` is
 opt-in; without it, the root refresh keeps its single-tree behaviour (above), and
 single-project repos ignore the flag entirely.
 
-`status --cascade` (or `bclaw_code_status(cascade=true)`) adds a per-child recap —
-which nested projects have a built index vs `missing_index`, plus an aggregate
-count — so you can see workspace-wide freshness from the root.
+The CLI cascade stays synchronous. MCP `bclaw_code_refresh(cascade=true)` returns
+a durable `job_id` immediately, avoiding the client timeout that a large workspace
+can hit; follow it with `bclaw_code_status(cascade=true)`. Status reports completed
+and total project counts, the project currently being indexed, and terminal
+outcomes. Successful rows are aggregated; only exceptions are named. A project
+with a valid empty index is labeled `no_eligible_files`, while lock contention and
+refresh failures remain distinct (`locked` / `failed`). `discovery_truncated=true`
+warns that the bounded nested-project scan could not inspect deeper branches, so
+the reported project total must not be treated as complete.
 
 ### Workspace-wide `find` / `brief`
 
@@ -250,8 +258,11 @@ Once the per-child indexes exist (built by `--cascade`), `find` and `brief` run
 at a multi-project workspace **root** automatically aggregate across every child
 project's store — no flag needed. Matches are project-tagged with
 workspace-relative paths, and the freshness badge merges per-store status (worst
-status wins) plus coverage (how many projects are indexed, listing any unindexed
-children). An aggregated `brief` also surfaces **cross-package reverse
+status wins) plus coverage. Missing child stores make the top-line badge
+`partial`, never `fresh`; diagnostics carry status counts and only the non-fresh
+exceptions instead of repeating every project. Weak shared-token candidates that
+do not contain the normalized query are omitted rather than returned as plausible
+score-1/2 noise. An aggregated `brief` also surfaces **cross-package reverse
 dependents**: sibling packages that import the defining package's public name
 rank into the reading list, flagged `cross_package`.
 

package/docs/integrations/mcp.md

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

package/docs/mcp-schema-changelog.md

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

package/package.json

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