brainclaw 1.10.2 → 1.11.1

package/dist/core/agent-files.js

@@ -1095,6 +1095,98 @@ function replaceBrainclawHooks(entries, canonical) {
     kept.push(canonical);
     return kept;
 }
+/**
+ * Canonical Claude Code session-hook commands.
+ *
+ * `--hook` (pln#596) makes session-start / context-diff / session-end degrade to
+ * exit 0 + ~/.brainclaw/hook.log on failure instead of hard-erroring the prompt
+ * loop (trp#917). `2>/dev/null` is kept to suppress incidental stderr noise —
+ * the actionable diagnostic now goes to hook.log, not stderr, so it survives the
+ * redirect (the bug was the non-zero EXIT, not the stream).
+ */
+function buildClaudeCodeHookCommands(bclawBin) {
+    return {
+        session: `f=.claude/.bclaw-session; if [ ! -f "$f" ]; then touch "$f"; ${bclawBin} session-start --include-context --hook 2>/dev/null; else ${bclawBin} context-diff --hook 2>/dev/null; fi`,
+        stop: `rm -f .claude/.bclaw-session; ${bclawBin} session-end --auto-release --reflect --reflect-handoff --dispatch-review --hook 2>/dev/null`,
+        checkEvents: `${bclawBin} check-events 2>/dev/null`,
+    };
+}
+/**
+ * Sanitize the brainclaw session hooks in ONE Claude Code settings file: collapse
+ * every recognized brainclaw hook (across UserPromptSubmit / Stop / PostToolUse)
+ * to a single canonical entry, repairing stale/broken forms (e.g. the legacy
+ * `node session-start` with the cli.js arg dropped, or dead install paths).
+ *
+ * Only touches events that ALREADY contain a brainclaw hook — it never injects
+ * hooks into a file (or event) that lacked them, so user-scope settings without
+ * brainclaw hooks stay untouched. This is the cross-scope counterpart to
+ * `ensureClaudeCodeSettings`, which only rewrites the cwd project file (pln#596 /
+ * trp#918: setup's git-repo discovery never reaches the launch dir or user scope,
+ * so broken hooks accumulate exactly where the agent executes them).
+ */
+export function fixClaudeCodeHooksInFile(filePath) {
+    if (!fs.existsSync(filePath))
+        return { filePath, existed: false, changed: false, collapsed: 0 };
+    const existing = readJsonObject(filePath); // returns {} for missing, undefined for unparseable
+    if (existing === undefined)
+        return { filePath, existed: true, changed: false, collapsed: 0 };
+    const hooksObj = isJsonObject(existing.hooks) ? existing.hooks : undefined;
+    if (!hooksObj)
+        return { filePath, existed: true, changed: false, collapsed: 0 };
+    const bclawBin = getBclawCliParts().map(quoteShellArg).join(' ');
+    const cmds = buildClaudeCodeHookCommands(bclawBin);
+    const countBrainclawHooks = (arr) => Array.isArray(arr)
+        ? arr.reduce((n, e) => n + (isJsonObject(e) && Array.isArray(e.hooks)
+            ? e.hooks.filter((h) => isJsonObject(h) && typeof h.command === 'string' && isBrainclawHookCommand(h.command)).length
+            : 0), 0)
+        : 0;
+    const events = [
+        ['UserPromptSubmit', buildCommandHookEntry(cmds.session)],
+        ['Stop', buildCommandHookEntry(cmds.stop)],
+        ['PostToolUse', buildMatchedCommandHookEntry('mcp__brainclaw__', cmds.checkEvents)],
+    ];
+    const nextHooks = { ...hooksObj };
+    let collapsed = 0;
+    let touched = false;
+    for (const [event, canonical] of events) {
+        const arr = Array.isArray(hooksObj[event]) ? hooksObj[event] : undefined;
+        if (!arr)
+            continue;
+        const before = countBrainclawHooks(arr);
+        if (before === 0)
+            continue; // never add hooks to an event that had none
+        nextHooks[event] = replaceBrainclawHooks(arr, canonical);
+        collapsed += Math.max(0, before - 1); // N brainclaw entries → 1 canonical
+        touched = true;
+    }
+    if (!touched)
+        return { filePath, existed: true, changed: false, collapsed: 0 };
+    const { updated } = writeJsonFileIfChanged(filePath, { ...existing, hooks: nextHooks });
+    return { filePath, existed: true, changed: updated, collapsed };
+}
+/**
+ * Run `fixClaudeCodeHooksInFile` across every Claude Code settings scope that can
+ * carry brainclaw hooks: user-scope (`~/.claude/settings*.json`) and the cwd
+ * project (`<cwd>/.claude/settings*.json`). Independent of git-repo discovery.
+ */
+export function fixClaudeCodeHooksAllScopes(cwd, homeDir) {
+    const candidates = [
+        path.join(homeDir, '.claude', 'settings.json'),
+        path.join(homeDir, '.claude', 'settings.local.json'),
+        path.join(cwd, '.claude', 'settings.json'),
+        path.join(cwd, '.claude', 'settings.local.json'),
+    ];
+    const seen = new Set();
+    const results = [];
+    for (const candidate of candidates) {
+        const resolved = path.resolve(candidate);
+        if (seen.has(resolved))
+            continue;
+        seen.add(resolved);
+        results.push(fixClaudeCodeHooksInFile(resolved));
+    }
+    return results;
+}
 export function ensureProjectDevDependency(cwd) {
     const filePath = path.join(cwd, 'package.json');
     if (!fs.existsSync(filePath))
@@ -1242,10 +1334,8 @@ export function ensureClaudeCodeSettings(cwd) {
     // binary resolution succeeded (hidden by 2>/dev/null).
     const hooks = isJsonObject(existing.hooks) ? { ...existing.hooks } : {};
     const bclawBin = getBclawCliParts().map(quoteShellArg).join(' ');
-    const sessionCommand = `f=.claude/.bclaw-session; if [ ! -f "$f" ]; then touch "$f"; ${bclawBin} session-start --include-context 2>/dev/null; else ${bclawBin} context-diff 2>/dev/null; fi`;
-    const stopCommand = `rm -f .claude/.bclaw-session; ${bclawBin} session-end --auto-release --reflect --reflect-handoff --dispatch-review 2>/dev/null`;
     // PostToolUse — check for unseen events after any brainclaw MCP tool call
-    const checkEventsCommand = `${bclawBin} check-events 2>/dev/null`;
+    const { session: sessionCommand, stop: stopCommand, checkEvents: checkEventsCommand } = buildClaudeCodeHookCommands(bclawBin);
     hooks.UserPromptSubmit = replaceBrainclawHooks(Array.isArray(hooks.UserPromptSubmit) ? hooks.UserPromptSubmit : [], buildCommandHookEntry(sessionCommand));
     hooks.Stop = replaceBrainclawHooks(Array.isArray(hooks.Stop) ? hooks.Stop : [], buildCommandHookEntry(stopCommand));
     hooks.PostToolUse = replaceBrainclawHooks(Array.isArray(hooks.PostToolUse) ? hooks.PostToolUse : [], buildMatchedCommandHookEntry('mcp__brainclaw__', checkEventsCommand));

package/dist/core/agent-registry.js

@@ -314,6 +314,18 @@ export function resolveCurrentAgentIdentity(cwd, preferredDirName, _homeDir) {
     // In multi-agent setups this always resolves to the wrong agent.
     // The field remains in config for display (status, doctor) and for resolveExistingCurrentAgent
     // which is used during setup/init only.
+    // Single-registered-agent fallback (pln#596). When there is NO identity signal
+    // at all — no env id/name AND no detected native agent — but exactly one agent
+    // is registered in this scope, resolving it is unambiguous. This is the
+    // solo-dev / single-CLI case (a fresh hook with no BRAINCLAW_AGENT_NAME). The
+    // pln#562 guard against config.current_agent only matters at ≥2 agents, so this
+    // preserves multi-agent safety: ≥2 registered → still falls through to undefined.
+    if (!envAgentId && !envAgentName && !detected) {
+        const registered = listAgentIdentities(cwd, preferredDirName);
+        if (registered.length === 1) {
+            return registered[0];
+        }
+    }
     return undefined;
 }
 export function resolveRegisteredAgentIdentity(options = {}) {
@@ -416,7 +428,10 @@ export function requireRegisteredAgentIdentity(options = {}) {
             throw new AgentIdentityResolutionError(`Environment agent '${normalizedEnv}' is not registered.`, { agent_name: normalizedEnv });
         }
     }
-    throw new AgentIdentityResolutionError('No registered agent identity resolved. Use --agent/--agent-id or configure a current agent with `brainclaw register-agent <name> --set-current`.');
+    throw new AgentIdentityResolutionError('No registered agent identity resolved. Pass `--agent <name>` or `--agent-id <id>`, '
+        + 'set $BRAINCLAW_AGENT_NAME, or register an agent with `brainclaw register-agent <name>` '
+        + '— a single registered agent is then resolved automatically. '
+        + '(`--set-current` alone does NOT affect resolution.)');
 }
 /**
  * Resolve agent identity for session start, returning both the resolved identity and whether

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/hook-log.js

@@ -0,0 +1,43 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/**
+ * Append a one-line, timestamped diagnostic to ~/.brainclaw/hook.log.
+ *
+ * brainclaw session hooks (UserPromptSubmit / Stop) historically wrapped every
+ * CLI call in `2>/dev/null`, which turned an actionable failure (e.g. "no
+ * registered agent identity resolved") into a contentless "hook error: No
+ * stderr output" on every prompt (trp#917). Hook-mode commands now degrade to
+ * exit 0 and drop a line here instead, so the failure is silent to the agent's
+ * prompt loop but still debuggable.
+ *
+ * Best-effort and never throws — a logging failure must not break a hook.
+ */
+const MAX_LOG_BYTES = 256 * 1024;
+export function hookLogPath(homeDir = os.homedir()) {
+    return path.join(homeDir, '.brainclaw', 'hook.log');
+}
+export function logHookDiagnostic(message, homeDir = os.homedir()) {
+    try {
+        const file = hookLogPath(homeDir);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        // Size-cap: when the log grows past the cap, keep only the tail so it never
+        // balloons unbounded across thousands of prompts.
+        try {
+            const stat = fs.statSync(file);
+            if (stat.size > MAX_LOG_BYTES) {
+                const tail = fs.readFileSync(file, 'utf-8').slice(-Math.floor(MAX_LOG_BYTES / 2));
+                fs.writeFileSync(file, tail, 'utf-8');
+            }
+        }
+        catch {
+            /* no existing file — nothing to truncate */
+        }
+        const line = `${new Date().toISOString()} ${message.replace(/\s+/g, ' ').trim()}\n`;
+        fs.appendFileSync(file, line, 'utf-8');
+    }
+    catch {
+        /* best-effort — never break a hook over logging */
+    }
+}
+//# sourceMappingURL=hook-log.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