brainclaw 1.10.2 → 1.11.1

package/README.md

@@ -417,6 +417,27 @@ 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.1
+
+Agent-identity & session-hook resilience, from a fresh-CLI dogfood on a monorepo:
+
+- **Session hooks no longer spam `UserPromptSubmit hook error` on every prompt.** Root cause was an agent-identity error whose own remediation (`register-agent --set-current`) the resolver ignored, swallowed by `2>/dev/null`. Now: the error hint points at what actually works (`--agent` / `$BRAINCLAW_AGENT_NAME`), a **single registered agent auto-resolves** with no env signal, and `session-start`/`context-diff`/`session-end` run with `--hook` so they degrade to exit 0 + `~/.brainclaw/hook.log` instead of erroring the prompt loop. Multi-agent safety (pln#562) is unchanged.
+- **`brainclaw doctor --fix-hooks`** purges stale/broken/duplicate brainclaw hooks across all Claude Code settings scopes (user + cwd) and rewrites the canonical ones — for the broken hooks that accumulate where `setup`'s git-repo discovery never reached.
+- **`setup` repo discovery recurses** (bounded, skipping `node_modules`/build dirs) so repos nested deep in a workspace are found instead of silently missed, and it registers the detected agent so the hooks it installs can resolve an identity.
+
+### 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')
@@ -763,6 +774,7 @@ program
     .option('--json', 'Output as JSON dashboard')
     .option('--migration-check', 'Report versioned documents that need schema migration')
     .option('--fix-agent-ignore', 'Add missing .gitignore entries for generated local Brainclaw agent files')
+    .option('--fix-hooks', 'Purge stale/broken/duplicate brainclaw session hooks across all Claude Code settings scopes (user + cwd) and rewrite the canonical ones')
     .option('--fix', 'Fix auto-resolvable issues (e.g. drifting MCP configs)')
     .option('--repair', 'Rebuild dist/ when the MCP runtime is missing or stale')
     .option('--after-migration', 'Run the v1.0 post-migration health check only (exits non-zero on any failure)')
@@ -1424,6 +1436,7 @@ program
     .option('--model <id>', 'Model identifier (e.g. claude-sonnet-4-6)')
     .option('--maintenance-mode <mode>', 'Maintenance mode: full (default) or fast')
     .option('--include-context', 'Output full project context after starting session (replaces separate context call)')
+    .option('--hook', 'Hook mode: degrade to exit 0 + ~/.brainclaw/hook.log on failure (advisory session hooks)')
     .option('--json', 'Output as JSON')
     .action(async (options) => {
     await runSessionStart(options);
@@ -1441,6 +1454,7 @@ program
     .option('--dispatch-review', 'When used with --reflect-handoff, auto-dispatch a code review if the handoff is reviewable')
     .option('--reviewer <name>', 'Explicit reviewer to route the reflected handoff review to')
     .option('--no-reflect', 'Suppress the dogfooding reflection prompt (project + your surfaces/skills/tools), shown by default')
+    .option('--hook', 'Hook mode: degrade to exit 0 + ~/.brainclaw/hook.log on failure (advisory Stop hook)')
     .option('--json', 'Output as JSON')
     .action(async (options) => {
     await runSessionEnd({
@@ -1451,6 +1465,7 @@ program
         dispatchReview: options.dispatchReview,
         reviewer: options.reviewer,
         reflect: options.reflect,
+        hook: options.hook,
     });
 });
 // --- whoami ---
@@ -1742,9 +1757,10 @@ program
     .description('Show what changed in memory since last context read, a session start, or a given timestamp')
     .option('--since <date>', 'Show changes since this ISO date')
     .option('--session <id>', 'Show changes since the start of this session')
+    .option('--hook', 'Hook mode: exit 0 silently when there is no diff baseline (advisory session hooks)')
     .option('--json', 'Output as JSON')
     .action((options) => {
-    runContextDiff({ since: options.since, session: options.session, json: options.json });
+    runContextDiff({ since: options.since, session: options.session, json: options.json, hook: options.hook });
 });
 program
     .command('capability <subcommand> [args...]')

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/context-diff.js

@@ -4,18 +4,45 @@ import { loadInstructions, resolveInstructions } from '../core/instructions.js';
 import { memoryExists } from '../core/io.js';
 import { loadState } from '../core/state.js';
 import { isTrapActive } from '../core/traps.js';
+import { logHookDiagnostic } from '../core/hook-log.js';
 /**
  * Hybrid context-diff: always includes critical anchors (active claims,
  * top traps, instructions) so the agent stays grounded, plus the memory
  * delta since last context read.
  */
 export function runContextDiff(options = {}) {
+    try {
+        contextDiffBody(options);
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        if (options.hook) {
+            // Advisory hook (trp#917): any failure past the early guards — e.g. a
+            // corrupt session snapshot / claim / instruction file feeding buildContextDiff
+            // or buildCriticalAnchors — must NOT error the prompt loop. Log + exit 0.
+            logHookDiagnostic(`context-diff skipped: ${message}`);
+            return;
+        }
+        console.error(`Error: ${message}`);
+        process.exit(1);
+    }
+}
+function contextDiffBody(options) {
     if (!memoryExists(options.cwd)) {
+        if (options.hook) {
+            logHookDiagnostic('context-diff skipped: .brainclaw/ not found');
+            return;
+        }
         console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
         process.exit(1);
     }
     const resolved = resolveContextDiffSince(options);
     if (!resolved.since) {
+        if (options.hook) {
+            // No diff baseline yet (e.g. first prompt before a session marker exists).
+            // Nothing to surface — exit 0 silently so the hook never errors (trp#917).
+            return;
+        }
         if (options.session) {
             console.error(`Error: session '${options.session}' not found in session snapshots or audit log.`);
             process.exit(1);
@@ -25,6 +52,10 @@ export function runContextDiff(options = {}) {
     }
     const diff = buildContextDiff({ ...options, includeItems: true });
     if (!diff) {
+        if (options.hook) {
+            logHookDiagnostic('context-diff skipped: unable to build diff');
+            return;
+        }
         console.error('Error: unable to build context diff.');
         process.exit(1);
     }

package/dist/commands/doctor.js

@@ -1,5 +1,6 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import * as childProcess from 'node:child_process';
 import { reconcileAllOpenRuns } from '../core/agentrun-reconciler.js';
@@ -35,7 +36,7 @@ import { assessBrainclawVersion, detectConcurrentInstallations } from '../core/b
 import { resolveStoreChain } from '../core/store-resolution.js';
 import { listWorktrees, detectSharedCheckoutRisk } from '../core/worktree.js';
 import { resolveCrossProjectLinks, detectCrossProjectCycles } from '../core/cross-project.js';
-import { auditLocalAgentWorkspaceFiles, ensureGitignoreEntries, patchAllMcpConfigs } from '../core/agent-files.js';
+import { auditLocalAgentWorkspaceFiles, ensureGitignoreEntries, patchAllMcpConfigs, fixClaudeCodeHooksAllScopes } from '../core/agent-files.js';
 import { summarizeWorkspaceProjects } from '../core/workspace-projects.js';
 import { detectStaleness, staleSummary } from '../core/staleness.js';
 import { InboxMessageSchema } from '../core/schema.js';
@@ -654,6 +655,27 @@ export function runDoctor(options = {}) {
             process.exit(report.exit_code);
         return;
     }
+    if (options.fixHooks) {
+        const cwd = options.cwd ?? process.cwd();
+        const results = fixClaudeCodeHooksAllScopes(cwd, os.homedir());
+        const fixed = results.filter((r) => r.changed);
+        if (options.json) {
+            console.log(JSON.stringify({ ok: true, action: 'fix-hooks', results }, null, 2));
+        }
+        else if (fixed.length === 0) {
+            console.log('✔ No stale/broken brainclaw session hooks found across Claude Code settings scopes.');
+        }
+        else {
+            for (const r of fixed) {
+                const suffix = r.collapsed > 0
+                    ? ` (collapsed ${r.collapsed} stale/duplicate entr${r.collapsed === 1 ? 'y' : 'ies'})`
+                    : '';
+                console.log(`✔ Sanitized brainclaw session hooks in ${r.filePath}${suffix}`);
+            }
+            console.log('  → Restart your Claude Code session to pick up the canonical hooks.');
+        }
+        return;
+    }
     if (options.repair) {
         try {
             const result = repairDistRuntime(options);

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/commands/session-end.js

@@ -39,6 +39,7 @@ import { extractFilesFromDiff } from '../commands/handoff.js';
 import { capHandoffDiff } from '../core/handoff-snapshot.js';
 import { suggestCompaction } from '../core/memory-compactor.js';
 import { dispatchReview } from '../core/dispatcher.js';
+import { logHookDiagnostic } from '../core/hook-log.js';
 export const REFLECTION_QUESTIONS = [
     'Dogfooding the project — using brainclaw to do real work this session, what friction did you hit (slow reads, confusing surfaces, missing affordances, awkward workflows)? What concrete change to the project would have removed it?',
     'Your surfaces, skills & tools — did your generated surface files (CLAUDE.md / agent surface), skills (SKILL.md), or tools (MCP / CLI) help or get in the way? Name at least one concrete edit that would make them serve you better next time.',
@@ -113,7 +114,13 @@ export async function runSessionEnd(options = {}) {
         }
     }
     catch (e) {
-        console.error(`Error: ${e instanceof Error ? e.message : String(e)}`);
+        const message = e instanceof Error ? e.message : String(e);
+        if (options.hook) {
+            // Advisory Stop hook (trp#917): never fail the prompt loop. Log + exit 0.
+            logHookDiagnostic(`session-end skipped: ${message}`);
+            return;
+        }
+        console.error(`Error: ${message}`);
         process.exit(1);
     }
 }

package/dist/commands/session-start.js

@@ -11,6 +11,7 @@ import { writeContextMarker } from '../core/freshness.js';
 import { saveRuntimeNote, generateRuntimeNoteId } from '../core/runtime.js';
 import { nowISO, generateId } from '../core/ids.js';
 import { appendAuditEntry } from '../core/audit.js';
+import { logHookDiagnostic } from '../core/hook-log.js';
 import { releaseStaleClaimsFromOtherAgents } from '../core/claims.js';
 import { SessionSnapshotSchema } from '../core/schema.js';
 import { auditLocalAgentWorkspaceFiles } from '../core/agent-files.js';
@@ -93,7 +94,13 @@ export async function runSessionStart(options = {}) {
         }
     }
     catch (e) {
-        console.error(`Error: ${e instanceof Error ? e.message : String(e)}`);
+        const message = e instanceof Error ? e.message : String(e);
+        if (options.hook) {
+            // Advisory hook (trp#917): never fail the prompt loop. Log + exit 0.
+            logHookDiagnostic(`session-start skipped: ${message}`);
+            return;
+        }
+        console.error(`Error: ${message}`);
         process.exit(1);
     }
 }

package/dist/commands/setup.js

@@ -12,6 +12,7 @@ import { ensureClaudeCodeUserSettings, ensureClaudeCodeUserCommand, ensureCursor
 import { MEMORY_DIR, memoryExists } from '../core/io.js';
 import { ensureUserStore, readSetupState, resolveHomeDir, writeSetupState } from '../core/setup-state.js';
 import { writeDetectedAgentHooks } from './hooks.js';
+import { normalizeAgentName, findAgentIdentityByName, registerAgentIdentity } from '../core/agent-registry.js';
 export { readSetupState } from '../core/setup-state.js';
 // ─── Constants ────────────────────────────────────────────────────────────────
 export const ALL_KNOWN_AGENTS = [
@@ -83,37 +84,59 @@ export function parseRoots(input, env = process.env) {
     return results;
 }
 // ─── Step 2: Scan repos ───────────────────────────────────────────────────────
-export function scanGitRepos(roots) {
+/** Heavy / generated directories never worth descending into when hunting repos. */
+const SCAN_SKIP_DIRS = new Set([
+    'node_modules', '.git', 'dist', 'dist-test', 'build', 'out', '.next',
+    'coverage', 'vendor', '.venv', 'venv', '__pycache__', '.cache', 'target', '.gradle',
+]);
+/**
+ * Discover git repositories under each root, recursing up to `maxDepth` levels.
+ *
+ * trp#918: the previous scan was depth-1 only (root + immediate children), so in
+ * a workspace like /srv with repos nested at /srv/dev/repos/global/<svc> it found
+ * just the shallow ones and silently missed the rest. This walk descends (skipping
+ * heavy/build/hidden dirs, bounded by `maxDepth`) and surfaces every directory
+ * that contains a `.git`. It keeps descending past a found repo because a
+ * workspace repo can legitimately contain independent child repos (the prior
+ * depth-1 scan already surfaced depth-1 children); the user selects which to init.
+ */
+export function scanGitRepos(roots, maxDepth = 6) {
     const repos = [];
     const seen = new Set();
-    for (const root of roots) {
-        const candidates = [root];
-        try {
-            const entries = fs.readdirSync(root, { withFileTypes: true });
-            for (const entry of entries) {
-                if (!entry.isDirectory())
-                    continue;
-                candidates.push(path.join(root, entry.name));
-            }
-        }
-        catch {
-            // skip unreadable dirs
-        }
-        for (const candidate of candidates) {
-            const repoPath = path.resolve(candidate);
-            if (seen.has(repoPath))
-                continue;
-            if (isBrainclawInternalPath(repoPath))
-                continue;
-            if (!fs.existsSync(path.join(repoPath, '.git')))
-                continue;
+    const walk = (dir, depth) => {
+        const repoPath = path.resolve(dir);
+        if (seen.has(repoPath))
+            return;
+        if (isBrainclawInternalPath(repoPath))
+            return;
+        if (fs.existsSync(path.join(repoPath, '.git'))) {
             seen.add(repoPath);
             repos.push({
                 path: repoPath,
                 name: path.basename(repoPath) || repoPath,
                 alreadyInitialised: memoryExists(repoPath),
             });
+            // Keep descending — a workspace repo may contain independent child repos.
+        }
+        if (depth >= maxDepth)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(repoPath, { withFileTypes: true });
+        }
+        catch {
+            return; // unreadable dir — skip
         }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (SCAN_SKIP_DIRS.has(entry.name) || entry.name.startsWith('.'))
+                continue;
+            walk(path.join(repoPath, entry.name), depth + 1);
+        }
+    };
+    for (const root of roots) {
+        walk(root, 0);
     }
     return repos;
 }
@@ -309,6 +332,39 @@ export async function initReposAndConfigureAgents(selectedRepos, selectedAgents,
     }
     return { initialisedRepos, configActions };
 }
+/**
+ * Ensure a resolvable session identity exists (pln#596 / trp#917). setup installs
+ * session hooks that need an agent identity; a hook with no identity now degrades
+ * silently (exit 0, logs to ~/.brainclaw/hook.log) but won't inject context. If we
+ * detected the running agent, register it in each selected repo so the hook resolves
+ * immediately. Otherwise emit a clear, actionable note — we don't guess an agent (a
+ * wrong identity is worse than none, and the single-registered-agent fallback wants
+ * exactly one).
+ */
+export function ensureSessionIdentityForRepos(repoPaths, detectedName) {
+    if (detectedName) {
+        const normalized = normalizeAgentName(detectedName);
+        let registered = 0;
+        for (const repoPath of repoPaths) {
+            try {
+                if (!findAgentIdentityByName(normalized, repoPath)) {
+                    registerAgentIdentity({ agentName: normalized, kind: 'agent', trustLevel: 'contributor', cwd: repoPath });
+                    registered++;
+                }
+            }
+            catch {
+                /* best-effort — identity registration must not abort setup */
+            }
+        }
+        if (registered > 0) {
+            console.log(`  ✔ Registered session identity '${normalized}' in ${registered} repo(s) so session hooks resolve immediately.`);
+        }
+        return;
+    }
+    console.log('\n⚠ No agent identity registered yet — session hooks will no-op (exit 0) until one resolves.');
+    console.log('  Set `export BRAINCLAW_AGENT_NAME=<agent>` in your shell, or run `brainclaw register-agent <name>`.');
+    console.log('  (A single registered agent then resolves automatically; running inside a detected agent auto-registers on first session.)');
+}
 // ─── Step 7: Reload reminder ──────────────────────────────────────────────────
 export function printReloadReminder(detectedAgent) {
     console.log('');
@@ -540,6 +596,8 @@ export async function runSetup(options = {}) {
     // Step 6: Init repos + configure agents
     console.log('\n→ Initialising repositories and configuring agents...');
     const { initialisedRepos, configActions } = await initReposAndConfigureAgents(selectedRepos, selectedAgents, env);
+    // Step 6.5: ensure a resolvable session identity for the hooks we just installed.
+    ensureSessionIdentityForRepos(selectedRepos.map((r) => r.path), detectedName);
     // Step 7: VS Code extension
     installVscodeExtension();
     // Save state