brainclaw 1.10.1 → 1.11.0

package/README.md

@@ -417,6 +417,19 @@ npm run test:coverage      # with coverage report
 
 For older releases (v0.x and the early v1.0 launch series), `git log` on `master` is the source of truth — every release commit follows the `chore(release): bump version to <semver>` convention, and the matching feature/fix commits reference their plan id (e.g. `feat(mcp): self-heal ... (pln#478)`).
 
+### v1.11.0
+
+Monorepo project-resolution + Code Map, cross-project relocation, and dispatch-worktree hygiene — from a multi-project (monorepo) dogfood:
+
+- **`bclaw_switch` to the monorepo root now works, and a switch is honored everywhere.** An agent inside a child project could not switch *up* to the workspace-root project, and a session-scoped switch was silently lost (sessions are stored per-cwd, but the resolver read them only at the workspace anchor). The resolver now matches the root project by `project_name`/`project_id` and probes the anchor / physical cwd / workspace root for the session, so `bclaw_switch` is authoritative for every subsequent call — including Code Map — without `--cwd`.
+- **`code-map refresh --cascade`** — monorepo-native, per-project indexing: one command at the root refreshes **every** nested project into its own store plus a child-scoped root store, with **zero double-indexing** (even under nesting). `code-map status --cascade` adds a per-child recap. Opt-in; single-project repos are unchanged.
+- **`brainclaw move <entity> <id> --to <project>` / `bclaw_move`** — id-preserving cross-project relocation, closing the gap the switch bug exposed (items created in the wrong store). Execution-local entities (claim/assignment/agent_run/session) stay put; refuses id collisions and active-claim moves; audits both stores.
+- **Sub-agent worktrees auto-clean on loop close** — a completed review/dispatch loop garbage-collects its worktrees (junction-safe; keeps any that are alive, un-harvested, or carry unmerged commits). Opt out with `BRAINCLAW_NO_WORKTREE_GC=1`.
+
+### v1.10.2
+
+Dispatch worktree-creation hardening (parallel-lane dispatch on a large repo): the claim-scope branch slug is length-capped *before* its trailing-dot strip (a scope ending in `…Page.astro` no longer truncates to an invalid `feat/…Page.` ref), and `git worktree add` gets a dedicated timeout (120s default; override `BRAINCLAW_WORKTREE_ADD_TIMEOUT_MS`) so a several-hundred-file checkout isn't SIGTERM-killed mid-materialize.
+
 ### v1.10.1
 
 Code Map fast-follows from the 1.10.0 dogfood, plus a lint cleanup:

package/dist/cli.js

@@ -20,6 +20,7 @@ import { runUpdatePlan } from './commands/update-plan.js';
 import { runDeletePlan } from './commands/delete-plan.js';
 import { runPlanResource } from './commands/plan-resource.js';
 import { runCodeMap } from './commands/code-map.js';
+import { runMove } from './commands/move.js';
 import { runSequenceResource } from './commands/sequence.js';
 import { runAddStep } from './commands/add-step.js';
 import { runDeleteStep } from './commands/delete-step.js';
@@ -606,6 +607,7 @@ 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('--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', (v) => parseInt(v, 10))
     .action((subcommand, args, options) => {
     void runCodeMap(subcommand, args, options).catch((err) => {
@@ -613,6 +615,15 @@ program
         process.exit(1);
     });
 });
+// --- move (cross-project relocation, pln#595) ---
+program
+    .command('move <entity> <id>')
+    .description('Relocate a brainclaw item to another project, id-preserving (multi-project workspaces). Relocatable: plan, decision, constraint, trap, handoff, sequence.')
+    .requiredOption('--to <project>', 'Target project (name, path, or basename)')
+    .option('--from <project>', 'Source project (defaults to the current project)')
+    .option('--force', 'Move even if an active claim references the item')
+    .option('--json', 'Output as JSON')
+    .action((entity, id, options) => runMove(entity, id, options));
 // --- list-plans ---
 program
     .command('list-plans')

package/dist/commands/code-map.js

@@ -22,13 +22,13 @@ export async function runCodeMap(subcommand, args, options = {}) {
     const be = backend();
     const cwd = options.cwd;
     if (normalized === 'status') {
-        const status = await be.status({ cwd });
+        const status = await be.status({ cwd, cascade: options.cascade });
         printStatus(status, options);
         return;
     }
     if (normalized === 'refresh') {
         const scope = options.all ? 'all' : 'changed';
-        const result = await be.refresh({ scope, cwd });
+        const result = await be.refresh({ scope, cwd, cascade: options.cascade });
         printRefresh(result, options);
         return;
     }
@@ -74,6 +74,13 @@ function printStatus(status, options) {
     else {
         console.log('  Stats:    (none — index not built)');
     }
+    if (status.cascade) {
+        console.log(`  Workspace: ${status.cascade.indexed_children}/${status.cascade.total_children} child project(s) indexed`);
+        for (const child of status.cascade.children) {
+            const files = child.files_indexed === null ? '' : ` (${child.files_indexed} files)`;
+            console.log(`    [${child.freshness}] ${child.path}${files}`);
+        }
+    }
 }
 function printRefresh(result, options) {
     if (options.json) {
@@ -86,6 +93,14 @@ function printRefresh(result, options) {
     if (result.lock_status)
         console.log(`  Status:   ${result.lock_status}`);
     console.log(`  ${badgeLine(result.freshness_badge)}`);
+    if (result.cascade) {
+        const c = result.cascade;
+        console.log(`  Cascade:  ${c.children_refreshed} child project(s) + root (scoped)`);
+        console.log(`    [root] . — ${c.root_result.files_parsed} files parsed`);
+        for (const child of c.children) {
+            console.log(`    ${child.path} — ${child.files_parsed} files parsed (${child.freshness})`);
+        }
+    }
 }
 function printFind(result, options) {
     if (options.json) {

package/dist/commands/mcp.js

@@ -17,6 +17,7 @@ import { generateIdWithLabel } from '../core/ids.js';
 import { memoryExists } from '../core/io.js';
 import { generateCandidateIdWithLabel, loadCandidate, saveCandidate } from '../core/candidates.js';
 import { createEntity, getEntity, listEntities, boundListResult, DEFAULT_FIND_CHAR_BUDGET, removeEntity, transitionEntity, updateEntity, } from '../core/entity-operations.js';
+import { relocateEntity } from '../core/operations/relocate.js';
 import { handoffDiffPreviewNote } from '../core/handoff-snapshot.js';
 import { ENTITY_REGISTRY } from '../core/entity-registry.js';
 import { generateClaimId, listClaims, loadClaim, saveClaim, createCoordinatorClaim, adoptClaimSession, attachAssignmentMessageToClaim, linkClaimToAssignment, releaseClaimWithCascade } from '../core/claims.js';
@@ -452,11 +453,13 @@ 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.',
+        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).',
         annotations: { tier: 'standard', category: 'discovery', headlessApproval: 'auto' },
         inputSchema: {
             type: 'object',
-            properties: {},
+            properties: {
+                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.' },
+            },
         },
     },
     {
@@ -489,12 +492,13 @@ 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.',
+        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.',
         annotations: { tier: 'standard', category: 'discovery', headlessApproval: 'prompt' },
         inputSchema: {
             type: 'object',
             properties: {
                 scope: { type: 'string', enum: ['changed', 'all'], description: 'changed (default) reparses changed files only; all does a full refresh with orphan compaction.' },
+                cascade: { type: 'boolean', description: 'Multi-project cascade: refresh every nested brainclaw project + a child-scoped root store. No-op outside a multi-project workspace.' },
             },
         },
     },
@@ -1265,6 +1269,22 @@ const MCP_WRITE_TOOLS = [
             required: ['entity', 'id', 'to'],
         },
     },
+    {
+        name: 'bclaw_move',
+        description: 'Relocate a brainclaw item to another project in a multi-project workspace, PRESERVING its id (so pln#/dec# references stay stable). Relocatable entities: plan, decision, constraint, trap, handoff, sequence. Execution-local entities (claim, assignment, agent_run, session) are NOT relocatable — they stay in the project where the work ran. Refuses on id collision in the target, a missing source, or an active claim on the item (unless force). Audits both stores.',
+        annotations: { tier: 'standard', category: 'memory', headlessApproval: 'prompt' },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                entity: { type: 'string', description: 'Entity name (plan, decision, constraint, trap, handoff, sequence).' },
+                id: { type: 'string', description: 'Entity id to move.' },
+                to_project: { type: 'string', description: 'Target project: name, path, or basename.' },
+                from_project: { type: 'string', description: 'Source project (defaults to the current project).' },
+                force: { type: 'boolean', description: 'Move even if an active claim references the item. Default false.' },
+            },
+            required: ['entity', 'id', 'to_project'],
+        },
+    },
 ];
 /**
  * Combined catalog of every brainclaw MCP tool descriptor (read + write).
@@ -2653,7 +2673,7 @@ async function _executeMcpToolCallInner(payload) {
             const { JsonlBackend } = await import('../core/code-map/backend.js');
             const be = new JsonlBackend();
             if (name === 'bclaw_code_status') {
-                const status = await be.status({ cwd });
+                const status = await be.status({ cwd, cascade: args.cascade === true });
                 return {
                     response: toolResponse({
                         content: [{ type: 'text', text: `Code Map: ${status.store_exists ? 'store present' : 'no store'} — freshness=${status.freshness_badge.status}` }],
@@ -2663,10 +2683,11 @@ async function _executeMcpToolCallInner(payload) {
             }
             if (name === 'bclaw_code_refresh') {
                 const scope = args.scope === 'all' ? 'all' : 'changed';
-                const result = await be.refresh({ scope, cwd });
+                const result = await be.refresh({ scope, cwd, cascade: args.cascade === true });
+                const cascadeNote = result.cascade ? ` cascade=${result.cascade.children_refreshed} child(ren)+root` : '';
                 return {
                     response: toolResponse({
-                        content: [{ type: 'text', text: `Code Map refresh [${result.scope}]: ran=${result.ran} freshness=${result.freshness_badge.status}${result.lock_status ? ` (${result.lock_status})` : ''}` }],
+                        content: [{ type: 'text', text: `Code Map refresh [${result.scope}]: ran=${result.ran} freshness=${result.freshness_badge.status}${cascadeNote}${result.lock_status ? ` (${result.lock_status})` : ''}` }],
                         structuredContent: { ...result, freshness_badge: result.freshness_badge },
                     }),
                 };
@@ -6619,6 +6640,27 @@ async function _executeMcpToolCallInner(payload) {
                 return { response: createToolErrorResponse('validation_error', error.message) };
             }
         }
+        if (name === 'bclaw_move') {
+            try {
+                const entity = String(args.entity ?? '');
+                const id = String(args.id ?? '');
+                const toProject = String(args.to_project ?? '');
+                const fromProject = typeof args.from_project === 'string' ? args.from_project : undefined;
+                const force = args.force === true;
+                const { agent_name, agent_id } = resolveCanonicalAuthor(args, cwd, connectionSessionId);
+                const result = relocateEntity({ entity, id, toProject, fromProject, force, cwd, actor: agent_name, actorId: agent_id });
+                const warn = result.warnings.length ? ` (${result.warnings.length} warning(s))` : '';
+                return {
+                    response: toolResponse({
+                        content: [{ type: 'text', text: `✔ moved ${entity} ${id} → ${result.to}${warn}` }],
+                        structuredContent: { ...result },
+                    }),
+                };
+            }
+            catch (error) {
+                return { response: createToolErrorResponse('validation_error', error.message) };
+            }
+        }
         if (name === 'bclaw_transition') {
             try {
                 const entity = String(args.entity ?? '');

package/dist/commands/move.js

@@ -0,0 +1,35 @@
+/**
+ * `brainclaw move <entity> <id> --to <project>` — id-preserving cross-project
+ * relocation (pln#595). Thin CLI adapter over core relocateEntity().
+ */
+import os from 'node:os';
+import { relocateEntity } from '../core/operations/relocate.js';
+export function runMove(entity, id, options) {
+    if (!options.to) {
+        console.error('Error: --to <project> is required.');
+        process.exit(1);
+    }
+    try {
+        const result = relocateEntity({
+            entity: entity,
+            id,
+            toProject: options.to,
+            fromProject: options.from,
+            force: options.force,
+            cwd: options.cwd ?? process.cwd(),
+            actor: process.env.BRAINCLAW_AGENT_NAME || os.userInfo().username || 'unknown',
+        });
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`✔ Moved ${result.entity} ${result.id} (${result.subdir}) → ${result.to}`);
+        for (const w of result.warnings)
+            console.log(`  ⚠ ${w}`);
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=move.js.map

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

@@ -15,6 +15,8 @@ import { refresh as runRefresh } from './refresh.js';
 import { applyGitHeadDrift } from './freshness.js';
 import { brief as runBrief, find as runFind } from './query.js';
 import { defaultMemoryReader } from './memory-reader.js';
+import { listNestedProjects, refreshWorkspaceCascade } from './cascade.js';
+import { loadConfig } from '../config.js';
 /** spec §9 caps the brief reading list at 12 files. */
 export const BRIEF_FILE_CAP = 12;
 function badge(status, details = {}) {
@@ -45,6 +47,30 @@ function readCurrentGitHead(root) {
         return null;
     }
 }
+/** True when `cwd` is a multi-project workspace (gates the cascade paths). */
+function isMultiProjectWorkspace(cwd) {
+    try {
+        return loadConfig(cwd).project_mode === 'multi-project';
+    }
+    catch {
+        return false;
+    }
+}
+/** 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 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,
+        };
+    });
+    const indexed = children.filter((c) => c.freshness !== 'missing_index').length;
+    return { children, indexed_children: indexed, total_children: children.length };
+}
 /**
  * P0 JSONL-backed query backend. Reads the durable file store (manifest +
  * shards + indexes); no graph DB. find()/brief() are stubbed for Sprint 1.
@@ -63,26 +89,31 @@ export class JsonlBackend {
     }
     async status(input) {
         const manifest = readManifest(input.cwd, input.preferredDirName);
-        if (!manifest) {
-            return {
+        const result = manifest
+            ? {
+                store_exists: true,
+                freshness_badge: this.withHeadDrift(badge(manifest.freshness.status, {
+                    stale_file_count: manifest.freshness.stale_file_count,
+                    partial_reason: manifest.freshness.partial_reason,
+                }), manifest, input.cwd),
+                stats: {
+                    files_indexed: manifest.stats.files_indexed,
+                    nodes: manifest.stats.nodes,
+                    edges: manifest.stats.edges,
+                },
+            }
+            : {
                 store_exists: storeExists(input.cwd, input.preferredDirName),
                 freshness_badge: badge('missing_index'),
                 stats: null,
             };
+        // Multi-project recap (opt-in): per-child store presence + freshness, so a
+        // status at the monorepo root surfaces the 27-children-missing-index state
+        // instead of just the (now child-scoped) root store. DGX Finding 2.
+        if (input.cascade && isMultiProjectWorkspace(input.cwd)) {
+            result.cascade = buildCascadeStatus(input.cwd);
         }
-        const base = badge(manifest.freshness.status, {
-            stale_file_count: manifest.freshness.stale_file_count,
-            partial_reason: manifest.freshness.partial_reason,
-        });
-        return {
-            store_exists: true,
-            freshness_badge: this.withHeadDrift(base, manifest, input.cwd),
-            stats: {
-                files_indexed: manifest.stats.files_indexed,
-                nodes: manifest.stats.nodes,
-                edges: manifest.stats.edges,
-            },
-        };
+        return result;
     }
     /**
      * Real refresh (spec §7): resolves project identity (input -> manifest ->
@@ -92,6 +123,36 @@ export class JsonlBackend {
      */
     async refresh(input) {
         const scope = input.scope ?? 'changed';
+        // Multi-project cascade (opt-in): refresh every nested brainclaw project +
+        // a child-scoped root store. No-op outside a multi-project workspace — fall
+        // through to the normal single-project refresh below. DGX Finding 2.
+        if (input.cascade && isMultiProjectWorkspace(input.cwd)) {
+            const cascade = await refreshWorkspaceCascade({
+                rootCwd: input.cwd ?? process.cwd(),
+                scope,
+                ownerAgent: input.ownerAgent ?? null,
+                ownerAgentId: input.ownerAgentId ?? null,
+            });
+            const root = cascade.root_result;
+            const allProjects = [root, ...cascade.children];
+            // 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);
+            return {
+                ran: allProjects.some((p) => p.ran),
+                scope,
+                lock_acquired: skipped.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(', ')}` }
+                    : {}),
+                cascade,
+            };
+        }
         const manifest = readManifest(input.cwd, input.preferredDirName);
         const projectRoot = input.projectRoot ?? manifest?.project_root ?? input.cwd ?? process.cwd();
         const projectId = input.projectId ?? manifest?.project_id ?? `prj_${path.basename(path.resolve(projectRoot))}`;

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

@@ -0,0 +1,116 @@
+/**
+ * Monorepo Code Map cascade (DGX Finding 2, 2026-06-22).
+ *
+ * Plain `refresh` is topology-blind: run at a multi-project workspace root it
+ * builds ONE monolithic index that descends every child subtree, while the 27
+ * sibling projects keep `missing_index`. The cascade (opt-in: `--cascade` /
+ * `bclaw_code_refresh(cascade=true)`) instead refreshes EACH nested brainclaw
+ * project into its own `<child>/.brainclaw/code/` store, and refreshes the root
+ * store SCOPED to the files no child owns.
+ *
+ * Zero double-indexing — and correct under nesting — by a single rule: when
+ * refreshing project P, exclude the subtree of every OTHER discovered project
+ * that sits strictly under P. So a file is indexed by exactly one project: the
+ * most specific brainclaw project that contains it.
+ *
+ * Topology source = `scanNestedBrainclawProjects` (a pure filesystem scan for
+ * nested `.brainclaw/config.yaml`), so it works regardless of
+ * `projects.strategy` (folder/manual) and matches what `bclaw_switch --list`
+ * shows. Children without a `.brainclaw/` are NOT created here — the cascade
+ * refreshes existing brainclaw projects, it does not initialise new ones.
+ */
+import path from 'node:path';
+import { scanNestedBrainclawProjects } from '../workspace-projects.js';
+import { loadConfig } from '../config.js';
+import { refresh as runRefresh } from './refresh.js';
+import { readManifest } from './store.js';
+function toPosix(p) {
+    return p.replace(/\\/g, '/');
+}
+/** True when `dir` is strictly below `ancestor` (not equal, not above, same drive). */
+function isStrictlyUnder(dir, ancestor) {
+    const rel = path.relative(path.resolve(ancestor), path.resolve(dir));
+    return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+function projectIdFor(cwd, fallbackId) {
+    const manifest = readManifest(cwd);
+    if (manifest?.project_id)
+        return manifest.project_id;
+    if (fallbackId)
+        return fallbackId;
+    try {
+        const id = loadConfig(cwd).project_id;
+        if (id)
+            return id;
+    }
+    catch {
+        /* no config — fall through to a cwd-derived default */
+    }
+    return `prj_${path.basename(path.resolve(cwd))}`;
+}
+/**
+ * Nested brainclaw projects strictly under `rootCwd`, as absolute paths, deduped
+ * and sorted. Pure filesystem scan (strategy-agnostic). Shared by the refresh
+ * cascade and the `status --cascade` recap so both agree on the project set.
+ */
+export function listNestedProjects(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();
+}
+/**
+ * Refresh the whole multi-project workspace: every nested brainclaw project +
+ * a child-scoped root store. Callers should only invoke this when the root is a
+ * multi-project workspace (the backend gates on `project_mode`).
+ */
+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);
+    // Every project to refresh, root first.
+    const allProjects = [rootCwd, ...childAbsPaths];
+    const refreshOne = async (projectCwd, isRoot) => {
+        // Exclude the subtree of every OTHER project that sits strictly under this
+        // one → each file is owned by exactly the most specific project.
+        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 } : {}),
+        };
+    };
+    // Children first, then the root (sequential — each holds its own project lock
+    // briefly; never blocks bclaw_work, rule 8).
+    const children = [];
+    for (const childCwd of childAbsPaths) {
+        children.push(await refreshOne(childCwd, false));
+    }
+    const rootResult = await refreshOne(rootCwd, true);
+    return {
+        is_cascade: true,
+        root: rootCwd,
+        root_result: rootResult,
+        children,
+        children_refreshed: children.length,
+    };
+}
+//# sourceMappingURL=cascade.js.map

package/dist/core/instruction-templates.js

@@ -319,7 +319,7 @@ function renderAvailableTools() {
         '## brainclaw — available tools',
         '',
         '**Entry:** `bclaw_work(intent, compact?, budget_tokens?)` · `bclaw_context(kind=memory|execution|board|board_summary|delta)`',
-        '**Canonical grammar** (entities: plan, decision, constraint, trap, handoff, runtime_note, candidate, sequence, claim, action, assignment, agent_run): `bclaw_find`, `bclaw_get`, `bclaw_create`, `bclaw_update`, `bclaw_remove`, `bclaw_transition`. Reads accept `budget_tokens` and `project` (cross-project routing — unknown names throw).',
+        '**Canonical grammar** (entities: plan, decision, constraint, trap, handoff, runtime_note, candidate, sequence, claim, action, assignment, agent_run): `bclaw_find`, `bclaw_get`, `bclaw_create`, `bclaw_update`, `bclaw_remove`, `bclaw_transition`. Reads accept `budget_tokens` and `project` (cross-project routing — unknown names throw). `bclaw_move(entity, id, to_project)` relocates an item to another project id-preserving in a multi-project workspace (plan/decision/constraint/trap/handoff/sequence; execution entities stay local).',
         '**Session/claims:** `bclaw_session_start`, `bclaw_session_end`, `bclaw_claim`, `bclaw_release_claim` · **steps:** `bclaw_add_step`, `bclaw_complete_step`, `bclaw_update_step`, `bclaw_delete_step` · **sequences:** `bclaw_list_sequences`, `bclaw_create_sequence`, `bclaw_update_sequence`, `bclaw_delete_sequence`',
         '**Inbox:** `bclaw_read_inbox`, `bclaw_ack_message`, `bclaw_send_message`, `bclaw_correct_handoff` · **capture:** `bclaw_write_note`, `bclaw_quick_capture(text, type?)` · **search:** `bclaw_search` · **setup:** `bclaw_setup`, `bclaw_bootstrap`, `bclaw_switch`, `bclaw_release_notes`',
         '**Escalation (orchestrators):** `bclaw_coordinate(intent=review|consult|assign|ideate)` · `bclaw_dispatch(intent=execute)` on an active sequence · `bclaw_loop(intent=turn|complete_turn|advance|close)` to drive turns · `bclaw_dispatch_status(target_id)` to verify',

package/dist/core/loops/store.js

@@ -3,7 +3,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { memoryDir, writeFileAtomic } from '../io.js';
 import { nowISO } from '../ids.js';
-import { convergeAssignmentToTerminal } from '../assignments.js';
+import { logger } from '../logger.js';
+import { convergeAssignmentToTerminal, loadAssignment } from '../assignments.js';
+import { gcWorktreeIfHarvested } from '../worktree.js';
 import { writeProjectMdSafe } from './hooks/bootstrap-write.js';
 import { notifyOperatorOnInputRequested } from './hooks/notify-operator.js';
 import { DEFAULT_PROTOCOLS, LoopArtifactSchema, LoopEventSchema, LoopThreadSchema, } from './types.js';
@@ -433,6 +435,34 @@ export function closeLoop(input, cwd) {
         }
         catch { /* never block loop close on assignment convergence */ }
     }
+    // pln#594: GC the dispatched sub-agent worktrees now the loop is done, so
+    // review/dispatch worktrees stop accumulating under ~/.brainclaw/worktrees/.
+    // Only on a COMPLETED close — cancelled/blocked keep their worktree (+ run
+    // logs) for forensics. Best-effort (never blocks the close) and each removal
+    // is guarded inside gcWorktreeIfHarvested (skips alive / dirty / un-integrated
+    // worktrees, junction-safe). Opt out with BRAINCLAW_NO_WORKTREE_GC=1.
+    if (input.final_status === 'completed' && process.env.BRAINCLAW_NO_WORKTREE_GC !== '1') {
+        const mainCwd = cwd ?? process.cwd();
+        const seen = new Set();
+        for (const slot of next.slots) {
+            if (!slot.assignment_id)
+                continue;
+            try {
+                const worktreePath = loadAssignment(slot.assignment_id, cwd)?.worktree_path;
+                if (!worktreePath || seen.has(worktreePath))
+                    continue;
+                seen.add(worktreePath);
+                const decision = gcWorktreeIfHarvested(mainCwd, worktreePath);
+                if (decision.removed) {
+                    logger.info(`loop ${input.id} close: removed worktree ${decision.path} (${decision.reason})`);
+                }
+                else if (decision.reason !== 'already gone') {
+                    logger.debug(`loop ${input.id} close: kept worktree ${decision.path} — ${decision.reason}`);
+                }
+            }
+            catch { /* never block loop close on worktree GC */ }
+        }
+    }
     return next;
 }
 //# sourceMappingURL=store.js.map

package/dist/core/operations/relocate.js

@@ -0,0 +1,130 @@
+/**
+ * Cross-project relocation (pln#595) — `bclaw move` / `bclaw_move`.
+ *
+ * Moves a brainclaw item from one project store to another in a multi-project
+ * workspace, PRESERVING ITS ID (so `pln#`/`dec#` references stay stable). Born
+ * from the monorepo switch bug (DGX Finding 1): items were created in the wrong
+ * store and there was no relocation helper — only raw file surgery or a recreate
+ * that mints a new id and breaks references.
+ *
+ * Scope (v1): the portable knowledge / coordination entities stored one file per
+ * id under a single directory — plan, decision, constraint, trap, handoff,
+ * sequence. Execution-local entities (claim, assignment, agent_run, session) are
+ * intentionally NOT relocatable — they belong to the project where the work ran
+ * (cross_project_signaling_vs_execution). candidate/runtime_note are deferred
+ * (inbox / visibility-split storage) — a follow-up.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveEntityDir, writeFileAtomic } from '../io.js';
+import { getEntitySpec } from '../entity-registry.js';
+import { appendAuditEntry } from '../audit.js';
+import { resolveProjectCwd } from '../cross-project.js';
+import { listClaims } from '../claims.js';
+import { listSequences } from '../sequence.js';
+/**
+ * Relocatable entity → the store subdir holding its flat `<id>.json` files.
+ *
+ * v1 covers only the SHARED, flat-per-id stores. Trap is deliberately limited to
+ * the shared `traps/` dir: the host/private visibility variants are host-SCOPED
+ * (`traps-hosts/<host>/<id>.json`, `traps-private/<host>/<id>.json` — see
+ * saveOperationalTrap), so a flat `<variant>/<id>.json` lookup would both miss
+ * them and, if it found one, flatten away the host directory (codex review of
+ * pln#595). Host/private traps are deferred alongside candidate/runtime_note
+ * until relocation preserves the host scope.
+ */
+const RELOCATABLE_SUBDIRS = {
+    plan: ['plans'],
+    decision: ['decisions'],
+    constraint: ['constraints'],
+    trap: ['traps'],
+    handoff: ['handoffs'],
+    sequence: ['sequences'],
+};
+export const RELOCATABLE_ENTITIES = Object.keys(RELOCATABLE_SUBDIRS);
+/**
+ * Relocate one entity, id-preserving. Throws on every unsafe condition
+ * (non-relocatable entity, same source/target, missing source, target collision,
+ * unknown target project, or a live claim unless `force`). Audits BOTH stores.
+ */
+export function relocateEntity(input) {
+    const baseCwd = input.cwd ?? process.cwd();
+    const subdirs = RELOCATABLE_SUBDIRS[input.entity];
+    if (!subdirs) {
+        throw new Error(`Cannot move entity '${input.entity}': only portable knowledge/coordination entities are relocatable `
+            + `(${RELOCATABLE_ENTITIES.join(', ')}). Execution-local entities (claim, assignment, agent_run, session, …) `
+            + `stay in the project where the work ran.`);
+    }
+    if (!input.id?.trim())
+        throw new Error('move requires an entity id.');
+    const fromCwd = path.resolve(input.fromProject ? resolveProjectCwd(input.fromProject, baseCwd) : baseCwd);
+    const toCwd = path.resolve(resolveProjectCwd(input.toProject, baseCwd)); // throws on unknown target
+    if (fromCwd === toCwd) {
+        throw new Error(`Source and target are the same project (${toCwd}). Nothing to move.`);
+    }
+    // Locate the source file across the entity's candidate subdirs.
+    let srcFile;
+    let foundSubdir;
+    for (const sd of subdirs) {
+        const candidate = path.join(resolveEntityDir(sd, fromCwd, 'read'), `${input.id}.json`);
+        if (fs.existsSync(candidate)) {
+            srcFile = candidate;
+            foundSubdir = sd;
+            break;
+        }
+    }
+    if (!srcFile || !foundSubdir) {
+        throw new Error(`${input.entity} '${input.id}' not found in source project (${fromCwd}).`);
+    }
+    // Validate before moving — never silently relocate a corrupt record.
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(srcFile, 'utf-8'));
+    }
+    catch (err) {
+        throw new Error(`${input.entity} '${input.id}' is unreadable JSON: ${err.message}`, { cause: err });
+    }
+    getEntitySpec(input.entity).schema.parse(raw);
+    // Collision guard — never overwrite an item already in the target.
+    const dstDir = resolveEntityDir(foundSubdir, toCwd, 'write');
+    const dstFile = path.join(dstDir, `${input.id}.json`);
+    if (fs.existsSync(dstFile)) {
+        throw new Error(`${input.entity} '${input.id}' already exists in the target project — refusing to overwrite.`);
+    }
+    // Reference guards (plans): refuse to move work under a live claim; warn on
+    // sequences that still point at it (v1 does not rewrite refs).
+    const warnings = [];
+    if (input.entity === 'plan') {
+        const liveClaims = listClaims(fromCwd).filter((c) => c.status === 'active' && c.plan_id === input.id);
+        if (liveClaims.length > 0 && !input.force) {
+            throw new Error(`${input.id} has ${liveClaims.length} active claim(s) in the source project — refusing to move work mid-flight. `
+                + `Release the claim(s) first, or pass force to override.`);
+        }
+        if (liveClaims.length > 0) {
+            warnings.push(`moved despite ${liveClaims.length} active claim(s) still in the source project (force).`);
+        }
+        const refSeqs = listSequences(fromCwd).filter((s) => (s.items ?? []).some((it) => it.planId === input.id));
+        for (const s of refSeqs) {
+            warnings.push(`sequence ${s.id} in the source project still references this plan (items not rewritten).`);
+        }
+    }
+    // Perform the move: write target first (atomic), then remove the source — so a
+    // crash mid-move leaves a duplicate (recoverable) rather than nothing.
+    fs.mkdirSync(dstDir, { recursive: true });
+    writeFileAtomic(dstFile, `${JSON.stringify(raw, null, 2)}\n`);
+    fs.rmSync(srcFile);
+    // Audit BOTH stores so provenance survives the move.
+    const actor = input.actor ?? 'unknown';
+    const auditCommon = {
+        action: 'move',
+        actor,
+        ...(input.actorId ? { actor_id: input.actorId } : {}),
+        item_id: input.id,
+        item_type: input.entity,
+        scope: foundSubdir,
+    };
+    appendAuditEntry({ ...auditCommon, reason: `moved to ${toCwd}` }, fromCwd);
+    appendAuditEntry({ ...auditCommon, reason: `moved from ${fromCwd}` }, toCwd);
+    return { entity: input.entity, id: input.id, from: fromCwd, to: toCwd, subdir: foundSubdir, warnings };
+}
+//# sourceMappingURL=relocate.js.map

package/dist/core/store-resolution.js

@@ -130,16 +130,44 @@ export function resolveEffectiveCwdInfo(options = {}) {
         if (resolved)
             return { cwd: resolved, active_source: 'env_project', resolved_project: projectInfo(resolved) };
     }
-    // 4. Session-scoped active project (per-agent, no cross-agent interference)
-    const session = options.sessionId
-        ? loadSessionById(options.sessionId, anchorCwd)
-        : loadCurrentSession(anchorCwd);
-    if (session?.active_project) {
-        const sp = session.active_project;
-        if (fs.existsSync(path.join(sp.path, MEMORY_DIR, 'config.yaml'))) {
+    // 4. Session-scoped active project (per-agent, no cross-agent interference).
+    //    A session can be persisted under a DIFFERENT store than the anchor we read
+    //    from: an agent physically inside a child project gets its session created
+    //    AND switched under that child (cwd_child / the switch handler use the
+    //    physical cwd), while resolution here anchors at the workspace
+    //    (BRAINCLAW_CWD). Sessions are stored per-cwd (sessionsDir(cwd)) with no
+    //    chain search, so reading only the anchor makes a successful bclaw_switch
+    //    invisible — resolution then silently falls through to cwd_child and pins
+    //    the agent to the wrong project (DGX Finding 1, 2026-06-22). Probe the
+    //    anchor, the physical baseCwd, and the workspace root for each; the first
+    //    session carrying a still-valid active_project wins (anchor first preserves
+    //    prior precedence when the session lives where we expect).
+    const probedSessionCwds = new Set();
+    const probeSessionAt = (candidate) => {
+        if (!candidate)
+            return undefined;
+        const probeCwd = path.resolve(candidate);
+        if (probedSessionCwds.has(probeCwd))
+            return undefined; // dedup — no double read
+        probedSessionCwds.add(probeCwd);
+        const session = options.sessionId
+            ? loadSessionById(options.sessionId, probeCwd)
+            : loadCurrentSession(probeCwd);
+        const sp = session?.active_project;
+        if (sp && fs.existsSync(path.join(sp.path, MEMORY_DIR, 'config.yaml'))) {
             return { cwd: sp.path, active_source: 'session', resolved_project: { path: sp.path, name: sp.name } };
         }
-    }
+        return undefined;
+    };
+    // `??` short-circuits: the common case (agent at the anchor, session there)
+    // costs exactly one session load and never walks for the workspace root. The
+    // baseCwd / workspace-root probes only run when the cheap ones miss — i.e. the
+    // monorepo case where the session was stored under the physical child.
+    const sessionHit = probeSessionAt(anchorCwd)
+        ?? probeSessionAt(baseCwd)
+        ?? probeSessionAt(resolveWorkspaceRoot(baseCwd, options.storeChainOptions));
+    if (sessionHit)
+        return sessionHit;
     // 5. cwd_child — when anchored and the agent is physically inside a child store
     //    STRICTLY under the anchor, resolve THAT child rather than the shared global
     //    pointer or the anchor root. This is the independence rule: physical location
@@ -243,6 +271,22 @@ export function resolveProjectRef(ref, cwd = process.cwd(), storeChainOptions) {
     if (fs.existsSync(path.join(asPath, MEMORY_DIR, 'config.yaml'))) {
         return asPath;
     }
+    // The workspace root itself is a legal target — it is the "umbrella" project
+    // of a monorepo. The chain scan below deliberately skips wsRoot (so a child
+    // can never be shadowed by the root), but an agent must still be able to
+    // target the root by its own project_name/project_id. Without this, an agent
+    // working inside a child cannot switch UP to the monorepo root: bclaw_switch
+    // (and project="<root-name>" routing) failed with "Cannot resolve project"
+    // (DGX dogfood 2026-06-22, Finding 1). Matching by name/id — not by arbitrary
+    // path — preserves the path-injection trust boundary enforced above.
+    try {
+        const rootConfig = loadConfig(wsRoot);
+        if (rootConfig.project_name === ref || rootConfig.project_id === ref)
+            return wsRoot;
+    }
+    catch {
+        // unreadable workspace-root config — fall through to the child scan
+    }
     // Try by project name or project ID: scan child stores
     const chain = resolveStoreChain(wsRoot, storeChainOptions);
     for (const store of chain) {

package/dist/core/worktree.js

@@ -18,6 +18,13 @@ function gitPath(p) {
  *
  * Rules covered: no leading dots/dashes, no trailing dots, no `..`, no
  * `@{`, no control/space/`~^:?*[\\` characters, no trailing `.lock`.
+ *
+ * Order matters: the 48-char length cap is applied BEFORE the trailing-dot/dash
+ * and `.lock` strips — never after. Dogfood 1.10.1: a multi-file scope ending in
+ * `…IntegrationHubPage.astro` sanitized fine, but the final `.slice(0, 48)` cut
+ * landed on the dot before `astro`, yielding `…IntegrationHubPage.` — a trailing
+ * dot git rejects (`fatal: not a valid branch name`). Truncating first, then
+ * stripping, guarantees the cap can never re-introduce an invalid ref.
  */
 export function sanitizeBranchComponent(raw, fallback = 'scope') {
     let slug = raw
@@ -27,12 +34,13 @@ export function sanitizeBranchComponent(raw, fallback = 'scope') {
         .replace(/[^a-zA-Z0-9._-]/g, '-') // conservative whitelist for the rest
         .replace(/-+/g, '-') // collapse dashes
         .replace(/^[.-]+/, '') // no leading dot/dash
-        .replace(/[.-]+$/, ''); // no trailing dot/dash
+        .slice(0, 48) // length cap BEFORE the trailing strips
+        .replace(/[.-]+$/, ''); // no trailing dot/dash (cut may have made one)
     if (/\.lock$/i.test(slug))
-        slug = slug.slice(0, -'.lock'.length);
+        slug = slug.slice(0, -'.lock'.length).replace(/[.-]+$/, '');
     if (!slug)
         slug = fallback;
-    return slug.slice(0, 48);
+    return slug;
 }
 /**
  * Stack marker → shared directories mapping.
@@ -181,8 +189,40 @@ export function resolveWorktreePath(mainWorktreePath, branchName) {
     const slug = branchName.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 64);
     return path.join(worktreesBaseDir(mainWorktreePath), slug);
 }
-function runGit(args, cwd) {
-    const result = spawnSync('git', args, { cwd, encoding: 'utf-8', timeout: 15000 });
+/**
+ * Default timeout for quick git metadata queries (rev-parse, status, branch…).
+ * `git worktree add` is the exception — it materialises the entire working tree
+ * and on a large repo / Windows (Defender) easily exceeds this, so it passes an
+ * explicit, much larger timeout (see resolveWorktreeAddTimeoutMs).
+ *
+ * Dogfood 1.10.1: a 662-file site checkout was SIGTERM-killed at ~94% by this
+ * flat 15s cap, surfacing as a misleading "git worktree add failed: …Updating
+ * files: 94%" — the branch name was fine; the checkout simply ran out of time.
+ */
+const GIT_QUERY_TIMEOUT_MS = 15000;
+/**
+ * Timeout for `git worktree add` (full working-tree checkout). Defaults to 120s;
+ * override with BRAINCLAW_WORKTREE_ADD_TIMEOUT_MS (milliseconds) for very large
+ * repos or slow filesystems.
+ */
+export function resolveWorktreeAddTimeoutMs() {
+    const raw = process.env.BRAINCLAW_WORKTREE_ADD_TIMEOUT_MS;
+    const n = raw ? Number.parseInt(raw, 10) : NaN;
+    return Number.isFinite(n) && n > 0 ? n : 120_000;
+}
+function runGit(args, cwd, timeoutMs = GIT_QUERY_TIMEOUT_MS) {
+    const result = spawnSync('git', args, { cwd, encoding: 'utf-8', timeout: timeoutMs });
+    // spawnSync kills on timeout (SIGTERM) and sets error.code=ETIMEDOUT; the raw
+    // stderr is then just partial progress ("Updating files: …%"), which reads as
+    // a cryptic failure. Surface the real cause — the timeout — instead.
+    if (result.error?.code === 'ETIMEDOUT') {
+        const hint = args[0] === 'worktree' ? ' (large checkout? raise BRAINCLAW_WORKTREE_ADD_TIMEOUT_MS)' : '';
+        return {
+            ok: false,
+            stdout: result.stdout ?? '',
+            stderr: `git ${args[0]} timed out after ${timeoutMs}ms and was killed${hint}.`,
+        };
+    }
     return {
         ok: result.status === 0,
         stdout: result.stdout ?? '',
@@ -496,7 +536,7 @@ export function createWorktree(mainWorktreePath, branchName, options = {}) {
     const worktreeArgs = branchExists
         ? ['worktree', 'add', gitTargetPath, branchName]
         : ['worktree', 'add', '-b', branchName, gitTargetPath, baseRef];
-    const result = runGit(worktreeArgs, mainWorktreePath);
+    const result = runGit(worktreeArgs, mainWorktreePath, resolveWorktreeAddTimeoutMs());
     if (!result.ok) {
         throw new Error(`git worktree add failed: ${result.stderr.trim()}`);
     }
@@ -945,6 +985,92 @@ export function cleanMergedWorktrees(mainWorktreePath, options = {}) {
     cleanOrphanWorktreeDirs(mainWorktreePath, worktrees, result, options.dryRun);
     return result;
 }
+/** A worker whose heartbeat file was touched within this window looks alive. */
+const WORKTREE_GC_LIVENESS_WINDOW_MS = 120_000;
+/**
+ * A worker still looks alive when a `.brainclaw-heartbeat-*` sentinel in its
+ * worktree was modified within `windowMs`. Cheap liveness signal that needs no
+ * agent_run lookup — the spawn wrapper touches the heartbeat periodically.
+ */
+function workerLooksAlive(worktreePath, windowMs) {
+    try {
+        const now = Date.now();
+        for (const name of fs.readdirSync(worktreePath)) {
+            if (!name.startsWith('.brainclaw-heartbeat-'))
+                continue;
+            try {
+                if (now - fs.statSync(path.join(worktreePath, name)).mtimeMs < windowMs)
+                    return true;
+            }
+            catch { /* ignore unreadable sentinel */ }
+        }
+    }
+    catch { /* worktree dir unreadable — treat as not-alive */ }
+    return false;
+}
+/**
+ * Garbage-collect a single dispatched sub-agent worktree once its work is safely
+ * harvested (pln#594). Used by the loop-close cascade so review/dispatch
+ * worktrees stop accumulating under ~/.brainclaw/worktrees/.
+ *
+ * SAFE BY DEFAULT — returns { removed: false, reason } instead of removing when:
+ *   - a worker still looks alive (recent heartbeat) — never bypassed, even by force;
+ *   - the worktree has un-harvested edits (anything beyond brainclaw birth-noise /
+ *     LANE-RESULT.json / heartbeat — i.e. real uncommitted work);
+ *   - the lane branch has commits NOT reachable from the main repo HEAD
+ *     (un-integrated work that `branch -D` would drop).
+ * `force` bypasses the dirty + unmerged guards (NOT the liveness guard).
+ * Removal is junction-safe (delegates to removeWorktree → detachWorktreeJunctions).
+ */
+export function gcWorktreeIfHarvested(mainWorktreePath, worktreePath, options = {}) {
+    const out = (removed, reason, branch) => ({
+        path: worktreePath, branch, removed, reason,
+    });
+    if (!worktreePath || !fs.existsSync(worktreePath))
+        return out(false, 'already gone');
+    if (workerLooksAlive(worktreePath, options.livenessWindowMs ?? WORKTREE_GC_LIVENESS_WINDOW_MS)) {
+        return out(false, 'worker still active (recent heartbeat)');
+    }
+    const branchRes = runGit(['rev-parse', '--abbrev-ref', 'HEAD'], worktreePath);
+    const branch = branchRes.ok ? branchRes.stdout.trim() : undefined;
+    if (!options.force) {
+        // FAIL CLOSED (codex review): every safety probe that cannot be read must
+        // KEEP the worktree, never fall through to removal. A transient `git status`
+        // timeout on a real, dirty worktree previously skipped the dirty check and
+        // force-removed it — losing un-harvested edits. Same for the HEAD reads.
+        const status = runGit(['status', '--porcelain=v1', '-z', '--untracked-files=normal'], worktreePath);
+        if (!status.ok) {
+            return out(false, 'could not read worktree status — keeping (fail-closed)', branch);
+        }
+        if (!worktreeHasOnlyBirthNoise(status.stdout)) {
+            return out(false, 'un-harvested changes in worktree', branch);
+        }
+        // The lane HEAD must be reachable from the main repo HEAD, else the branch
+        // carries un-integrated commits that `branch -D` would silently drop.
+        const laneHead = runGit(['rev-parse', 'HEAD'], worktreePath);
+        const mainHead = runGit(['rev-parse', 'HEAD'], mainWorktreePath);
+        if (!laneHead.ok || !mainHead.ok) {
+            return out(false, 'could not verify merge status — keeping (fail-closed)', branch);
+        }
+        const ancestor = runGit(['merge-base', '--is-ancestor', laneHead.stdout.trim(), mainHead.stdout.trim()], mainWorktreePath);
+        // exit 0 = ancestor (safe). Non-zero = not an ancestor OR a git error — both
+        // mean "cannot prove integrated", so keep.
+        if (!ancestor.ok)
+            return out(false, 'lane branch has un-integrated commits (or unverifiable)', branch);
+    }
+    try {
+        removeWorktree(mainWorktreePath, worktreePath, { force: true });
+    }
+    catch (err) {
+        return out(false, `removal failed: ${err.message}`, branch);
+    }
+    // Delete the now-redundant dispatch branch (force: it may be a squash-merge
+    // descendant that `-d` would refuse). Best-effort — a kept branch is harmless.
+    if (branch && branch !== 'HEAD' && branch !== '(detached)') {
+        runGit(['branch', '-D', branch], mainWorktreePath);
+    }
+    return out(true, options.force ? 'force-removed' : 'harvested + merged', branch);
+}
 /**
  * Removes brainclaw-managed worktree directories under ~/.brainclaw/worktrees/
  * that no longer have a corresponding git worktree entry.

package/dist/facts.js

@@ -1,11 +1,11 @@
 // Generated by scripts/emit-site-facts.mjs at build time. Do not edit manually.
-// Source: brainclaw v1.10.1 on 2026-06-21T19:26:16.599Z
+// Source: brainclaw v1.11.0 on 2026-06-24T07:26:01.488Z
 export const FACTS = {
-  "version": "1.10.1",
-  "generated_at": "2026-06-21T19:26:16.599Z",
+  "version": "1.11.0",
+  "generated_at": "2026-06-24T07:26:01.488Z",
   "tools": {
-    "count": 66,
-    "published_count": 65,
+    "count": 67,
+    "published_count": 66,
     "names": [
       "bclaw_bootstrap",
       "bclaw_release_notes",
@@ -72,7 +72,8 @@ export const FACTS = {
       "bclaw_create",
       "bclaw_update",
       "bclaw_remove",
-      "bclaw_transition"
+      "bclaw_transition",
+      "bclaw_move"
     ]
   },
   "entities": {

package/dist/facts.json

@@ -1,9 +1,9 @@
 {
-  "version": "1.10.1",
-  "generated_at": "2026-06-21T19:26:16.599Z",
+  "version": "1.11.0",
+  "generated_at": "2026-06-24T07:26:01.488Z",
   "tools": {
-    "count": 66,
-    "published_count": 65,
+    "count": 67,
+    "published_count": 66,
     "names": [
       "bclaw_bootstrap",
       "bclaw_release_notes",
@@ -70,7 +70,8 @@
       "bclaw_create",
       "bclaw_update",
       "bclaw_remove",
-      "bclaw_transition"
+      "bclaw_transition",
+      "bclaw_move"
     ]
   },
   "entities": {

package/docs/cli.md

@@ -65,6 +65,24 @@ brainclaw --cwd /other/path status   # one-off override without switching
 
 **MCP usage:** The active project also affects MCP tools. When `bclaw_context(kind="memory")` is called without an explicit path, it resolves context from the active project's store. Agents can also use the `BRAINCLAW_PROJECT=<name>` environment variable for the same effect.
 
+### `brainclaw move <entity> <id> --to <project>`
+
+Relocate a brainclaw item to another project in a multi-project workspace, **preserving its id** — so `pln#`/`dec#` references stay stable. Useful when an item was created in the wrong store (e.g. before a project switch took effect). MCP equivalent: `bclaw_move(entity, id, to_project, …)`.
+
+| Option | Description |
+|---|---|
+| `--to <project>` | Target project (name, path, or basename) — required |
+| `--from <project>` | Source project (defaults to the current project) |
+| `--force` | Move even if an active claim references the item |
+| `--json` | Output as JSON |
+
+Relocatable entities: `plan`, `decision`, `constraint`, `trap`, `handoff`, `sequence`. **Execution-local entities** (`claim`, `assignment`, `agent_run`, `session`) are rejected — they belong to the project where the work ran. The move refuses an id collision in the target or a plan under an active claim (unless `--force`), audits both stores, and warns about sequences that still reference a moved plan.
+
+```bash
+brainclaw move plan pln_a1b2c3d4 --to global          # move a misplaced plan to the root project
+brainclaw move decision dec_99 --from app_a --to app_b
+```
+
 ---
 
 ## Initialize and Inspect
@@ -613,13 +631,13 @@ can ask "where is X / what should I read first" before editing. The MCP equivale
 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`
+### `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.
+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).
 
-### `brainclaw code-map refresh [--all|--changed]`
+### `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.
+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).
 
 ### `brainclaw code-map find <query> [--limit <n>]`
 

package/docs/code-map.md

@@ -165,11 +165,12 @@ Code Map is **per project**: the index lives at `<project>/.brainclaw/code/`, an
 into subdirectories but skipping `node_modules`, `dist`, `.git`, `.brainclaw`,
 `vendor`, `target`, … at any depth.
 
-There is no nested-project *boundary*, so the scope follows **where you run it**:
+By default there is no nested-project *boundary*, so a plain (non-cascade) scope
+follows **where you run it**:
 
 | You run refresh / find / brief … | … against |
 |---|---|
-| at the monorepo root | one index covering the whole tree (every child project's source) |
+| at the monorepo root (plain) | one index covering the whole tree (every child project's source) |
 | inside a child project (e.g. `apps/api`) | that child's own index, at `apps/api/.brainclaw/code/` |
 
 When an agent works inside a child project, brainclaw's project resolution routes
@@ -178,10 +179,33 @@ Code Map to **that child** — the same per-project scoping that powers `bclaw_w
 juggling. A submodule that is itself an application (under e.g. `apps/`) is indexed
 like any other directory.
 
+### Cascading a multi-project workspace (`--cascade`)
+
+In a `project_mode: multi-project` workspace, one refresh at the root can index
+the whole monorepo **per project** instead of building one monolithic root index:
+
+```bash
+brainclaw code-map refresh --all --cascade     # CLI
+# bclaw_code_refresh(scope="all", cascade=true) # MCP
+```
+
+This refreshes **every nested brainclaw project** into its own
+`<child>/.brainclaw/code/` store, and refreshes the **root** store *scoped to the
+files no child owns*. The rule is "each file is indexed by exactly the most
+specific brainclaw project that contains it" — so there is **zero
+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.
+
 **Not yet supported** (roadmap):
 
-- A single aggregated view that keeps **separate per-child indexes and federates
-  them** at the root (a query spanning services without double-indexing).
+- A single **federated query** at the root that fans out across the per-child
+  indexes and merges the results (today, `--cascade` builds the per-child indexes;
+  `find` / `brief` still run against one store at a time).
 - **Cross-service edges** — e.g. linking an API call to the route that defines it in
   another service. Code Map indexes language *symbols* and *module imports*, not
   framework routes or runtime HTTP calls, so it does not (today) map "service A calls

package/docs/concepts/dispatch-lifecycle.md

@@ -165,6 +165,32 @@ The on-behalf commit is guarded by the linked-worktree check (`isLinkedWorktree`
 
 Integration is strictly additive and opt-in. Plain `brainclaw harvest <assignment_id>` remains report-only; it reads and reports the lane result without committing or mutating assignment / claim state. The on-behalf commit and lifecycle completion happen only when the coordinator passes `--integrate`.
 
+### Worktree garbage collection on loop close (pln#594)
+
+Closing a loop as **`completed`** garbage-collects the worktrees of its slot
+assignments, so review/dispatch worktrees stop accumulating under
+`~/.brainclaw/worktrees/`. The cascade runs inside `closeLoop` (so it covers MCP,
+CLI, and reconciler-driven closes) and is **safe by default** — each worktree is
+removed only when all of these hold:
+
+- the worker no longer looks alive (no `.brainclaw-heartbeat-*` touched within the
+  liveness window) — this guard is never bypassed, even with force;
+- the worktree has no un-harvested edits — anything beyond brainclaw birth-noise
+  (`.gitignore`, the sidecar), `LANE-RESULT.json`, and the heartbeat counts as
+  real work and is preserved;
+- the lane branch carries no commits unreachable from the main repo HEAD (so
+  deleting the branch can't drop un-integrated work).
+
+A worktree that fails a guard is **kept** (with a debug-log reason) so you can
+harvest or inspect it. A **`cancelled`/`blocked`** close keeps the worktree and
+its run logs for forensics. Removal is junction-safe (`removeWorktree` detaches
+`node_modules`/`dist` junctions first), then the redundant dispatch branch is
+deleted. The whole step is best-effort — it never blocks the close — and can be
+disabled with `BRAINCLAW_NO_WORKTREE_GC=1`. The reusable primitive is
+`gcWorktreeIfHarvested(mainWorktreePath, worktreePath, { force? })` in
+`core/worktree.ts`; `brainclaw worktree clean` remains the manual/TTL backstop
+for anything the cascade keeps.
+
 ---
 
 ## Diagnostic playbook

package/docs/integrations/mcp.md

@@ -107,6 +107,7 @@ Each tool also has an `annotations.category` field: `session`, `context`, `memor
 | `bclaw_update` | memory | Partially update mutable fields on a canonical entity |
 | `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_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 |
@@ -162,6 +163,7 @@ for the full 1.0.0 changelog.
 | `bclaw_update(entity, id, patch)` | Partial merge (updatable fields only) | `bclaw_update_plan`, `bclaw_update_memory` |
 | `bclaw_remove(entity, id, purge?)` | Archive (default) or hard-delete | `bclaw_delete_memory`, `bclaw_delete_plan` |
 | `bclaw_transition(entity, id, to, reason?)` | State machine transition with side-effect tags | `bclaw_accept`, `bclaw_reject`, status-update flows |
+| `bclaw_move(entity, id, to_project, from_project?, force?)` | Id-preserving cross-project relocation (plan/decision/constraint/trap/handoff/sequence; execution entities rejected) | — (new in 1.11.0) |
 
 Supported entities: plan, decision, constraint, trap, handoff,
 runtime_note, candidate, sequence, claim, action, assignment, agent_run

package/docs/mcp-schema-changelog.md

@@ -10,6 +10,24 @@ guarantees this changelog follows.
 
 ## Unreleased
 
+**Added — `bclaw_move` cross-project relocation (pln#595)**
+- New canonical-grammar verb `bclaw_move(entity, id, to_project, from_project?, force?)`:
+  relocates a brainclaw item to another project in a multi-project workspace,
+  PRESERVING its id. Relocatable: plan, decision, constraint, trap, handoff,
+  sequence. Execution-local entities (claim, assignment, agent_run, session) are
+  rejected. Refuses id collisions / active-claim moves (unless force); audits both
+  stores. Additive — no tool removed or renamed.
+
+**Changed — Code Map monorepo cascade (DGX Finding 2)**
+- `bclaw_code_refresh` gains an optional `cascade: boolean`. In a
+  `project_mode: multi-project` workspace it refreshes every nested
+  brainclaw project into its own store + a child-scoped root store
+  (zero double-indexing). No-op outside a multi-project workspace.
+- `bclaw_code_status` gains an optional `cascade: boolean` that adds a
+  per-child store-presence / freshness recap.
+- No tool was removed or renamed; no required argument changed.
+- Surface fingerprint bumped in the `(current)` section below.
+
 **Changed — agent-UX read-path surface (pln#542)**
 - `bclaw_work`, `bclaw_context`, `bclaw_find`, `bclaw_get`, `bclaw_search`
   gain an optional `budget_tokens` argument (relevance-ranked fill).
@@ -104,10 +122,16 @@ 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:35fd83b0d124df94`
-  (updated 2026-06-20 for 1.10.0: Code Map tools added to the published surface —
+- MCP public surface fingerprint: `sha256:188d2eba8828e4fe`
+  (updated 2026-06-24 for 1.11.0: `bclaw_move` added (pln#595) AND a `cascade`
+  boolean added to `bclaw_code_refresh` / `bclaw_code_status` (DGX Finding 2).
+  Additive: one new tool; nothing removed or renamed; no required argument changed.
+  Supersedes the per-branch interim hashes sha256:dffcc868ae90e013 and
+  sha256:41eb6d55010cdfb5.)
+  Previous: `sha256:35fd83b0d124df94`,
+  updated 2026-06-20 for 1.10.0: Code Map tools added to the published surface —
   `bclaw_code_find`, `bclaw_code_brief`, `bclaw_code_refresh`, `bclaw_code_status`.
-  Additive: no tool removed or renamed.)
+  Additive: no tool removed or renamed.
   Previous: `sha256:70cf80b9615f631f`,
   updated 2026-06-18 for 1.9.1: monorepo project-scoping fix — session-aware
   effective-cwd resolution and read-path project scoping shift the published

package/package.json

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