brainclaw 1.24.0 → 1.26.0

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

@@ -3,12 +3,19 @@ export function registerCodeMapCommands(program) {
     // --- code-map ---
     program
         .command('code-map <subcommand> [args...]')
-        .description('Query the per-project Code Map (status, refresh, find, brief)')
+        .description('Query the per-project Code Map (status, refresh, find, brief, impact, export, outline)')
         .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))
+        .option('--limit <n>', 'Max results for find/brief/impact/outline', (v) => parseInt(v, 10))
+        .option('--depth <n>', 'For impact/export: maximum graph depth (export is hard-capped at 4)', (v) => parseInt(v, 10))
+        .option('--direction <direction>', 'For export: outgoing, incoming, or both')
+        .option('--format <format>', 'For export: json (default) or mermaid')
+        .option('--max-nodes <n>', 'For export: maximum nodes (hard-capped at 100)', (v) => parseInt(v, 10))
+        .option('--max-edges <n>', 'For export: maximum edges (hard-capped at 200)', (v) => parseInt(v, 10))
+        .option('--min-confidence <n>', 'For export: persisted confidence floor (minimum 0.5)', (v) => parseFloat(v))
+        .option('--target-kind <kind>', 'For export: symbol or file (auto-detected by default)')
         .action((subcommand, args, options) => {
         void runCodeMap(subcommand, args, options).catch((err) => {
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);

package/dist/commands/code-map.js

@@ -1,12 +1,12 @@
 /**
  * `brainclaw code-map <subcommand>` — CLI surface over the Code Map backend
  * (spec §9). Mirrors plan-resource.ts: a switch over the subcommand delegating
- * to a JsonlBackend (status | refresh | find | brief). The backend owns all
+ * to a JsonlBackend (status | refresh | find | brief | impact | export | outline). The backend owns
  * query logic; this file only adapts it to argv + stdout (text or --json), and
  * every output carries the freshness_badge.
  */
 import { JsonlBackend } from '../core/code-map/backend.js';
-const KNOWN_SUBCOMMANDS = new Set(['status', 'refresh', 'find', 'brief']);
+const KNOWN_SUBCOMMANDS = new Set(['status', 'refresh', 'find', 'brief', 'impact', 'export', 'outline']);
 function backend() {
     return new JsonlBackend();
 }
@@ -15,10 +15,7 @@ function badgeLine(badge) {
     const detail = detailKeys.length
         ? ` (${detailKeys.map((k) => `${k}=${JSON.stringify(badge.details[k])}`).join(', ')})`
         : '';
-    // pln#601 — lead with the coarse rollup (uniform across all read surfaces), then
-    // the precise status + details. `coarse` may be absent on legacy/hand-built badges.
-    const coarse = badge.coarse ? `${badge.coarse} · ` : '';
-    return `Freshness: ${coarse}${badge.status}${detail}`;
+    return `Freshness: ${badge.freshness}${detail}`;
 }
 export async function runCodeMap(subcommand, args, options = {}) {
     const normalized = (subcommand ?? '').trim().toLowerCase();
@@ -57,6 +54,49 @@ export async function runCodeMap(subcommand, args, options = {}) {
         printBrief(result, options);
         return;
     }
+    if (normalized === 'impact') {
+        const target = args.join(' ').trim();
+        if (!target) {
+            console.error('Error: code-map impact requires <symbol-or-path>.');
+            console.error('  Usage: brainclaw code-map impact <symbol-or-path> [--depth 2]');
+            process.exit(1);
+        }
+        const result = await be.impact({ target, depth: options.depth, limit: options.limit, cwd });
+        printImpact(result, options);
+        return;
+    }
+    if (normalized === 'export') {
+        const target = args.join(' ').trim();
+        if (!target) {
+            console.error('Error: code-map export requires <symbol-or-path>.');
+            console.error('  Usage: brainclaw code-map export <symbol-or-path> [--direction both] [--depth 1] [--max-nodes 100] [--max-edges 200]');
+            process.exit(1);
+        }
+        const result = await be.exportGraph({
+            target,
+            targetKind: options.targetKind,
+            direction: options.direction,
+            depth: options.depth,
+            maxNodes: options.maxNodes,
+            maxEdges: options.maxEdges,
+            minConfidence: options.minConfidence,
+            format: options.format,
+            cwd,
+        });
+        printExport(result, options);
+        return;
+    }
+    if (normalized === 'outline') {
+        const target = args.join(' ').trim();
+        if (!target) {
+            console.error('Error: code-map outline requires <file>.');
+            console.error('  Usage: brainclaw code-map outline <file>');
+            process.exit(1);
+        }
+        const result = await be.outline({ path: target, limit: options.limit, cwd });
+        printOutline(result, options);
+        return;
+    }
     console.error(`Error: unknown code-map subcommand "${subcommand}".`);
     console.error(`  Available: ${[...KNOWN_SUBCOMMANDS].join(', ')}`);
     process.exit(1);
@@ -144,4 +184,78 @@ function printBrief(result, options) {
         }
     }
 }
+function printImpact(result, options) {
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    const cause = (row) => row.causes.map((item) => `${item.kind}${item.module ? ` ${item.module}` : ''}${item.source_line ? `:${item.source_line}` : ''}`).join(', ');
+    console.log(`Code Map impact: "${result.target}"`);
+    console.log(`  ${badgeLine(result.freshness_badge)}`);
+    console.log(`  Definition: ${result.definition.entries.length} (${result.definition.match_kind})`);
+    for (const entry of result.definition.entries)
+        console.log(`    ${entry.name} — ${entry.path}`);
+    console.log(`  Direct dependents: ${result.direct_dependents.length}${result.limits.direct_truncated ? '+' : ''}`);
+    for (const dependent of result.direct_dependents)
+        console.log(`    ${dependent.path} — ${cause(dependent)}`);
+    if (result.limits.max_depth > 1) {
+        console.log(`  Transitive dependents: ${result.transitive_dependents.length}${result.limits.transitive_truncated ? '+' : ''}`);
+        for (const dependent of result.transitive_dependents)
+            console.log(`    [depth ${dependent.depth}] ${dependent.path} — ${cause(dependent)}`);
+    }
+    console.log(`  Tests: ${result.risk.counters.resolved_test_files} resolved, ${result.risk.counters.suggested_test_files} naming suggestion(s)`);
+    for (const test of result.tests_for)
+        console.log(`    [${test.relation}, confidence=${test.confidence}] ${test.path} — ${test.reason}`);
+    console.log(`  Risk: ${result.risk.score} (${result.risk.formula}; direct=${result.risk.counters.direct_dependents}, transitive=${result.risk.counters.transitive_dependents})`);
+}
+function printExport(result, options) {
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(`Code Map export: "${result.target}" (${result.target_kind})`);
+    console.log(`  ${badgeLine(result.freshness_badge)}`);
+    console.log(`  Roots: ${result.root_node_ids.length}; nodes=${result.nodes.length}/${result.limits.max_nodes}; edges=${result.edges.length}/${result.limits.max_edges}; depth=${result.limits.max_depth}; direction=${result.limits.direction}; min-confidence=${result.limits.min_confidence}`);
+    const truncation = Object.entries(result.truncated).filter(([, value]) => value).map(([key]) => key);
+    if (truncation.length > 0)
+        console.log(`  Truncated: ${truncation.join(', ')}`);
+    if (result.format === 'mermaid' && result.mermaid) {
+        console.log(result.mermaid);
+        return;
+    }
+    for (const edge of result.edges) {
+        const source = edge.source ? ` @ ${edge.source.path}${edge.source.line === null || edge.source.line === undefined ? '' : `:${edge.source.line}`}` : '';
+        console.log(`  ${edge.from} -[${edge.kind}, confidence=${edge.confidence}${source}]-> ${edge.to}`);
+    }
+}
+function printOutline(result, options) {
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(`Code Map outline: "${result.path}"`);
+    console.log(`  Index:    ${result.index_status}`);
+    console.log(`  ${badgeLine(result.freshness_badge)}`);
+    if (!result.file_indexed) {
+        console.log('  Symbols:  (file not indexed)');
+        return;
+    }
+    console.log(`  Parse:    ${result.parse_status}`);
+    if (result.symbols.length === 0) {
+        console.log('  Symbols:  (none)');
+    }
+    else {
+        for (const symbol of result.symbols) {
+            const subtype = symbol.subtype ? ` ${symbol.subtype}` : '';
+            const span = symbol.span ? `${symbol.span.start_line}:${symbol.span.start_col}` : 'unknown';
+            const exported = symbol.exported ? ' export' : '';
+            console.log(`  [${span}] ${symbol.kind}${subtype} ${symbol.name}${exported} confidence=${symbol.confidence}`);
+        }
+    }
+    if (result.truncated)
+        console.log(`  … ${result.symbol_count - result.symbols.length} more indexed symbol(s)`);
+    if (result.diagnostics.length > 0) {
+        console.log(`  Diagnostics: ${result.diagnostics.length}${result.diagnostics_truncated ? '+' : ''}`);
+    }
+}
 //# sourceMappingURL=code-map.js.map

package/dist/commands/mcp-catalog.js

@@ -409,6 +409,52 @@ export const MCP_READ_TOOLS = [
             required: ['target'],
         },
     },
+    {
+        name: 'bclaw_code_impact',
+        description: 'Explain a symbol or source file\'s local blast radius from existing resolved imports: definition, direct dependents with edge causes, optional bounded transitives, affected test files, low-confidence naming suggestions kept separate, and a count-based risk score. Read-only; never refreshes.',
+        annotations: { tier: 'standard', category: 'discovery', headlessApproval: 'auto' },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                target: { type: 'string', description: 'Symbol name or source-file path whose impact to inspect.' },
+                depth: { type: 'number', description: 'Maximum graph depth. 1 (default) returns direct dependents only; 2+ opts into transitives. Clamped to 4.' },
+                limit: { type: 'number', description: 'Maximum rows in each dependent section and in naming suggestions. Clamped to 100.' },
+            },
+            required: ['target'],
+        },
+    },
+    {
+        name: 'bclaw_code_export',
+        description: 'Export a compact, deterministic, confidence-filtered local Code Map subgraph around one symbol or file. Requires a target; defaults to one hop and hard caps nodes (100), edges (200), and depth (4), so it never exports a whole graph. JSON retains every edge kind, source, and confidence. format="mermaid" adds a projection of the same JSON nodes/edges. Read-only; never refreshes or calls an external service.',
+        annotations: { tier: 'standard', category: 'discovery', headlessApproval: 'auto' },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                target: { type: 'string', description: 'Symbol name or source-file path around which to export a local subgraph.' },
+                targetKind: { type: 'string', enum: ['symbol', 'file'], description: 'Optional explicit target kind; otherwise a source path is detected safely.' },
+                direction: { type: 'string', enum: ['outgoing', 'incoming', 'both'], description: 'Which edge direction(s) to follow. Default: both.' },
+                depth: { type: 'number', description: 'Maximum graph distance from the root(s). Default 1; clamped to 0..4.' },
+                maxNodes: { type: 'number', description: 'Maximum nodes returned. Default 100; hard-capped at 100.' },
+                maxEdges: { type: 'number', description: 'Maximum edges returned. Default 200; hard-capped at 200.' },
+                minConfidence: { type: 'number', description: 'Persisted confidence threshold for nodes and relationships. Default/minimum 0.5.' },
+                format: { type: 'string', enum: ['json', 'mermaid'], description: 'Default json; mermaid adds a projection derived from the same bounded graph.' },
+            },
+            required: ['target'],
+        },
+    },
+    {
+        name: 'bclaw_code_outline',
+        description: 'Return a bounded source-ordered outline for one indexed file: symbol name, kind, subtype, span, exported flag, and persisted confidence. Read-only: it reads the existing file shard only, never parses or refreshes. `index_status` distinguishes a missing index, a file not indexed, and an indexed file with zero symbols.',
+        annotations: { tier: 'standard', category: 'discovery', headlessApproval: 'auto' },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Workspace-relative source file path (for example `src/app/App.tsx`).' },
+                limit: { type: 'number', description: 'Maximum symbols to return; clamped to the hard cap of 200.' },
+            },
+            required: ['path'],
+        },
+    },
 ];
 const MCP_WRITE_TOOLS = [
     {

package/dist/commands/mcp.js

@@ -1089,15 +1089,15 @@ async function _executeMcpToolCallInner(payload) {
         }
         // Code Map tools (spec §9). These delegate to the async JsonlBackend, so
         // they are handled here rather than via the synchronous read-tool path.
-        // status/find/brief are reads; refresh is a write (prompt approval).
-        if (name === 'bclaw_code_status' || name === 'bclaw_code_find' || name === 'bclaw_code_brief' || name === 'bclaw_code_refresh') {
+        // status/find/brief/impact/export/outline are reads; refresh is a write (prompt approval).
+        if (name === 'bclaw_code_status' || name === 'bclaw_code_find' || name === 'bclaw_code_brief' || name === 'bclaw_code_impact' || name === 'bclaw_code_export' || name === 'bclaw_code_outline' || name === 'bclaw_code_refresh') {
             const { JsonlBackend } = await import('../core/code-map/backend.js');
             const be = new JsonlBackend();
             if (name === 'bclaw_code_status') {
                 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}` }],
+                        content: [{ type: 'text', text: `Code Map: ${status.store_exists ? 'store present' : 'no store'} — freshness=${status.freshness_badge.freshness}` }],
                         structuredContent: { ...status, freshness_badge: status.freshness_badge },
                     }),
                 };
@@ -1108,7 +1108,7 @@ async function _executeMcpToolCallInner(payload) {
                 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}${cascadeNote}${result.lock_status ? ` (${result.lock_status})` : ''}` }],
+                        content: [{ type: 'text', text: `Code Map refresh [${result.scope}]: ran=${result.ran} freshness=${result.freshness_badge.freshness}${cascadeNote}${result.lock_status ? ` (${result.lock_status})` : ''}` }],
                         structuredContent: { ...result, freshness_badge: result.freshness_badge },
                     }),
                 };
@@ -1122,7 +1122,59 @@ async function _executeMcpToolCallInner(payload) {
                 const result = await be.find({ query, limit, cwd });
                 return {
                     response: toolResponse({
-                        content: [{ type: 'text', text: `Code Map find "${result.query}": ${result.matches.length} match(es), freshness=${result.freshness_badge.status}` }],
+                        content: [{ type: 'text', text: `Code Map find "${result.query}": ${result.matches.length} match(es), freshness=${result.freshness_badge.freshness}` }],
+                        structuredContent: { ...result, freshness_badge: result.freshness_badge },
+                    }),
+                };
+            }
+            // bclaw_code_export
+            if (name === 'bclaw_code_export') {
+                const target = typeof args.target === 'string' ? args.target : '';
+                if (!target.trim()) {
+                    return { response: createToolErrorResponse('validation_error', 'bclaw_code_export requires a non-empty target.') };
+                }
+                const targetKind = args.targetKind === 'symbol' || args.targetKind === 'file' ? args.targetKind : undefined;
+                const direction = args.direction === 'outgoing' || args.direction === 'incoming' || args.direction === 'both' ? args.direction : undefined;
+                const depth = typeof args.depth === 'number' ? args.depth : undefined;
+                const maxNodes = typeof args.maxNodes === 'number' ? args.maxNodes : undefined;
+                const maxEdges = typeof args.maxEdges === 'number' ? args.maxEdges : undefined;
+                const minConfidence = typeof args.minConfidence === 'number' ? args.minConfidence : undefined;
+                const format = args.format === 'mermaid' ? 'mermaid' : args.format === 'json' ? 'json' : undefined;
+                const result = await be.exportGraph({ target, targetKind, direction, depth, maxNodes, maxEdges, minConfidence, format, cwd });
+                return {
+                    response: toolResponse({
+                        content: [{ type: 'text', text: `Code Map export "${result.target}": ${result.nodes.length} node(s), ${result.edges.length} edge(s), depth=${result.limits.max_depth}, freshness=${result.freshness_badge.freshness}` }],
+                        structuredContent: { ...result, freshness_badge: result.freshness_badge },
+                    }),
+                };
+            }
+            // bclaw_code_impact
+            if (name === 'bclaw_code_impact') {
+                const target = typeof args.target === 'string' ? args.target : '';
+                if (!target.trim()) {
+                    return { response: createToolErrorResponse('validation_error', 'bclaw_code_impact requires a non-empty target.') };
+                }
+                const depth = typeof args.depth === 'number' ? args.depth : undefined;
+                const limit = typeof args.limit === 'number' ? args.limit : undefined;
+                const result = await be.impact({ target, depth, limit, cwd });
+                return {
+                    response: toolResponse({
+                        content: [{ type: 'text', text: `Code Map impact "${result.target}": ${result.risk.counters.direct_dependents} direct, ${result.risk.counters.transitive_dependents} transitive dependent(s), risk=${result.risk.score}, freshness=${result.freshness_badge.freshness}` }],
+                        structuredContent: { ...result, freshness_badge: result.freshness_badge },
+                    }),
+                };
+            }
+            // bclaw_code_outline
+            if (name === 'bclaw_code_outline') {
+                const outlinePath = typeof args.path === 'string' ? args.path : '';
+                if (!outlinePath.trim()) {
+                    return { response: createToolErrorResponse('validation_error', 'bclaw_code_outline requires a non-empty path.') };
+                }
+                const limit = typeof args.limit === 'number' ? args.limit : undefined;
+                const result = await be.outline({ path: outlinePath, limit, cwd });
+                return {
+                    response: toolResponse({
+                        content: [{ type: 'text', text: `Code Map outline "${result.path}": ${result.symbols.length}/${result.symbol_count} symbol(s), index=${result.index_status}, freshness=${result.freshness_badge.freshness}` }],
                         structuredContent: { ...result, freshness_badge: result.freshness_badge },
                     }),
                 };
@@ -1136,7 +1188,7 @@ async function _executeMcpToolCallInner(payload) {
             const result = await be.brief({ target, limit, cwd });
             return {
                 response: toolResponse({
-                    content: [{ type: 'text', text: `Code Map brief "${result.target}": ${result.suggested_files_to_read.length} file(s) to read, freshness=${result.freshness_badge.status}` }],
+                    content: [{ type: 'text', text: `Code Map brief "${result.target}": ${result.suggested_files_to_read.length} file(s) to read, freshness=${result.freshness_badge.freshness}` }],
                     structuredContent: { ...result, freshness_badge: result.freshness_badge },
                 }),
             };

package/dist/commands/session-start.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { execSync } from 'node:child_process';
-import { memoryExists, resolveEntityDir } from '../core/io.js';
+import { isSessionSnapshotRecordFilename, memoryExists, resolveEntityDir, sessionSnapshotRecordPaths } from '../core/io.js';
 import { loadVersionedJsonFile, saveVersionedJsonFile } from '../core/migration.js';
 import { buildOperationalIdentity, loadAllSessions, saveCurrentSession } from '../core/identity.js';
 import { requireMinimumTrustLevel, resolveCurrentModel, resolveOrAutoRegisterAgentIdentity } from '../core/agent-registry.js';
@@ -25,11 +25,55 @@ import { loadHygienePolicy } from '../core/hygiene-policy.js';
 import { maybeCreateCheckpoint } from '../core/events/checkpoint.js';
 import { pullSignalsFromLinkedProjects, markSignalProcessed } from '../core/federation-transport.js';
 import { materializeFederationSignal } from '../core/federation-materialize.js';
-function sessionsDir(cwd) {
-    return resolveEntityDir('sessions', cwd ?? process.cwd(), 'read');
+/**
+ * pln#670 — snapshot writes always target the canonical directory ('write' mode).
+ * The previous 'read'-mode resolution meant a fresh store (no coordination/sessions
+ * yet) landed the snapshot in the legacy dir — the current_session home — where
+ * saveCurrentSession then clobbered it (same `<session_id>.json` name, same id).
+ */
+function sessionSnapshotWriteDir(cwd) {
+    return resolveEntityDir('sessions', cwd ?? process.cwd(), 'write');
 }
 function sessionSnapshotPath(sessionId, cwd) {
-    return path.join(sessionsDir(cwd), `${sessionId}.json`);
+    return path.join(sessionSnapshotWriteDir(cwd), `${sessionId}.snapshot.json`);
+}
+/**
+ * pln#670 — lazy migration of pre-split snapshot records: rename `<id>.json` to
+ * `<id>.snapshot.json` in the CANONICAL sessions directory only. The legacy
+ * directory is never scanned — it is the current_session home. Only files that
+ * validate as session_snapshot are touched; anything else is left in place.
+ */
+export function migrateLegacySnapshotNames(cwd) {
+    const dir = sessionSnapshotWriteDir(cwd);
+    if (!fs.existsSync(dir))
+        return 0;
+    let renamed = 0;
+    for (const file of fs.readdirSync(dir)) {
+        // Case-insensitive suffix checks (codex review P1): Windows filesystems
+        // match names case-insensitively — an upper-cased `.SNAPSHOT.json` is the
+        // same record a lower-case probe reads, and must not be re-suffixed.
+        if (!file.toLowerCase().endsWith('.json') || isSessionSnapshotRecordFilename(file))
+            continue;
+        const from = path.join(dir, file);
+        try {
+            // Discriminate on the RAW file — the migration loader zod-strips unknown
+            // keys, so a current_session record parses as a clean snapshot after it.
+            // Key PRESENCE, not value type (codex review P1): the invariant is
+            // "never touch a record CARRYING last_seen_at", and `last_seen_at: null`
+            // must be rejected too.
+            const raw = JSON.parse(fs.readFileSync(from, 'utf-8'));
+            if (Object.hasOwn(raw, 'last_seen_at'))
+                continue;
+            SessionSnapshotSchema.parse(loadVersionedJsonFile('session_snapshot', from).document);
+            const to = path.join(dir, `${file.slice(0, -'.json'.length)}.snapshot.json`);
+            if (!fs.existsSync(to)) {
+                fs.renameSync(from, to);
+                renamed++;
+            }
+        }
+        catch { /* not a session_snapshot — leave it alone */ }
+    }
+    return renamed;
 }
 export async function runSessionStart(options = {}) {
     try {
@@ -155,7 +199,7 @@ export async function startSession(options = {}) {
         ...(model ? { model } : {}),
     };
     // Persist snapshot
-    const dir = sessionsDir(options.cwd);
+    const dir = sessionSnapshotWriteDir(options.cwd);
     if (!fs.existsSync(dir))
         fs.mkdirSync(dir, { recursive: true });
     saveVersionedJsonFile('session_snapshot', sessionSnapshotPath(snapshot.session_id, options.cwd), SessionSnapshotSchema.parse(snapshot));
@@ -218,6 +262,14 @@ export async function startSession(options = {}) {
                 inventoryAdvisory = lines;
         }
         catch { /* non-fatal — inventory scan failure should not block session start */ }
+        // pln#670 — lazy rename of pre-split snapshot records to the type-suffixed
+        // name. Session-start full maintenance is the natural sweep point (no daemon,
+        // feedback_lazy_reconcile_pattern); dual-read keeps unrenamed records readable
+        // in the meantime.
+        try {
+            migrateLegacySnapshotNames(options.cwd);
+        }
+        catch { /* non-fatal — name migration must never block session start */ }
         // pln#564 step B — cap the runtime-note tree on session start (no LLM gate,
         // unlike the compaction-phase archiveSessionNotes). Keeps the newest N
         // session/lifecycle notes per agent + all genuine observations, parks the
@@ -367,14 +419,33 @@ function isPidAlive(pid) {
     }
 }
 export function loadSessionSnapshot(sessionId, cwd) {
-    const p = sessionSnapshotPath(sessionId, cwd);
-    if (!fs.existsSync(p))
-        return undefined;
-    try {
-        return SessionSnapshotSchema.parse(loadVersionedJsonFile('session_snapshot', p).document);
-    }
-    catch {
-        return undefined;
+    // pln#670 — probe the type-suffixed name first, then the pre-split `<id>.json`
+    // layouts. SessionSnapshotSchema is non-strict, so a current_session record for
+    // the same id would parse too (zod strips unknown keys) — the negative
+    // discriminant is `last_seen_at`, which only current_session carries.
+    for (const p of sessionSnapshotRecordPaths(sessionId, cwd)) {
+        if (!fs.existsSync(p))
+            continue;
+        try {
+            // Discriminate on the RAW file: the migration loader zod-strips unknown
+            // keys, so a current_session record would come back looking like a clean
+            // snapshot. Key PRESENCE, not value type (codex review P1) — a record
+            // carrying `last_seen_at: null` must be rejected too.
+            const raw = JSON.parse(fs.readFileSync(p, 'utf-8'));
+            if (Object.hasOwn(raw, 'last_seen_at'))
+                continue;
+            const snapshot = SessionSnapshotSchema.parse(loadVersionedJsonFile('session_snapshot', p).document);
+            // The filename is not a type-safe identity boundary by itself (codex
+            // review): querying `sess_x.snapshot` also constructs `sess_x.snapshot.json`
+            // — the snapshot of sess_x. Only return a payload that names the caller's id.
+            if (snapshot.session_id !== sessionId)
+                continue;
+            return snapshot;
+        }
+        catch {
+            continue;
+        }
     }
+    return undefined;
 }
 //# sourceMappingURL=session-start.js.map

package/dist/core/bootstrap.js

@@ -9,6 +9,7 @@ import { mutate } from './mutation-pipeline.js';
 import { BootstrapApplicationReceiptSchema, BootstrapInterviewAnswerSchema, BootstrapInterviewPlanSchema, BootstrapInterviewQuestionSchema, BootstrapImportPlanDocumentSchema, BootstrapProfileDocumentSchema, BootstrapSuggestionDocumentSchema, MemorySeedDocumentSchema, } from './schema.js';
 import { loadVersionedJsonFile, saveVersionedJsonFile } from './migration.js';
 import { analyzeRepository, findNestedAgentsFiles } from './repo-analysis.js';
+import { isManagedByBrainclaw } from './project-discovery.js';
 import { buildExecutionContext, compactExecutionContext } from './execution-context.js';
 import { buildAgentToolingContext } from './agent-context.js';
 import { createInstruction, loadInstructions, saveInstruction } from './instructions.js';
@@ -256,15 +257,38 @@ function buildBootstrapArtifacts(input) {
         sourcesScanned.push('README');
         seeds.push(...extractReadmeSeeds(readmePath, input.target));
     }
+    // pln#671 — instruction files generated by `brainclaw export` derive FROM
+    // brainclaw memory: deriving seeds from them feeds the store its own output
+    // back as "new" knowledge. Seed extraction skips managed files; DETECTION
+    // (agentsPresent, native_instruction_files, source fingerprint) stays
+    // complete — that is environment inventory, not knowledge to import. The
+    // skip is traced in sources_scanned so the exclusion is never silent.
     const agentsPath = path.join(scanRoot, 'AGENTS.md');
     const agentsPresent = fs.existsSync(agentsPath);
     if (agentsPresent) {
-        sourcesScanned.push('AGENTS.md');
-        seeds.push(...extractAgentsSeeds(agentsPath, input.target));
+        if (isManagedByBrainclaw(agentsPath)) {
+            sourcesScanned.push('AGENTS.md (brainclaw-managed — skipped)');
+        }
+        else {
+            sourcesScanned.push('AGENTS.md');
+            seeds.push(...extractAgentsSeeds(agentsPath, input.target));
+        }
     }
     if (nativeInstructionFiles.length > 0) {
-        sourcesScanned.push('native_instructions');
-        seeds.push(...extractNativeInstructionSeeds(nativeInstructionFiles.map((relativePath) => path.join(scanRoot, relativePath)), scanRoot, input.target));
+        // AGENTS.md is handled by its own extractor above — keep it out of the
+        // native accounting so a managed AGENTS.md is not counted as skipped twice.
+        const nativeCandidates = nativeInstructionFiles
+            .filter((relativePath) => path.basename(relativePath) !== 'AGENTS.md');
+        const humanAuthored = nativeCandidates
+            .filter((relativePath) => !isManagedByBrainclaw(path.join(scanRoot, relativePath)));
+        const skippedManaged = nativeCandidates.length - humanAuthored.length;
+        if (humanAuthored.length > 0) {
+            sourcesScanned.push('native_instructions');
+            seeds.push(...extractNativeInstructionSeeds(humanAuthored.map((relativePath) => path.join(scanRoot, relativePath)), scanRoot, input.target));
+        }
+        if (skippedManaged > 0) {
+            sourcesScanned.push(`native_instructions (${skippedManaged} brainclaw-managed — skipped)`);
+        }
     }
     const manifestResult = extractManifestSeeds(scanRoot, input.target);
     if (manifestResult.seeds.length > 0) {

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

@@ -26,7 +26,7 @@ import path from 'node:path';
 import { loadConfig } from '../config.js';
 import { listNestedProjects } from './cascade.js';
 import { readManifest, readImportsIndex } from './store.js';
-import { coarseFreshness, applyGitHeadDrift } from './freshness.js';
+import { makeFreshnessBadge, applyGitHeadDrift } from './freshness.js';
 import { findInStore, briefInStore, makeLazyChecker, newAccumulator, deriveBadge, reserveSourceSlots, attachRelatedMemory, attachMemoryIds, validateStoreEntry, BRIEF_FILE_CAP, LAZY_BUDGET, } from './query.js';
 /** Same default cap as the single-store find (query.ts DEFAULT_FIND_LIMIT). */
 const DEFAULT_FIND_LIMIT = 20;
@@ -191,22 +191,11 @@ function statusRank(s) {
 function mergeBadges(perStore) {
     const total = perStore.length;
     const indexed = perStore.filter((p) => p.hasIndex);
-    const unindexed = perStore
-        .filter((p) => !p.hasIndex)
-        .map((p) => p.ref.relPath || '.')
-        .sort();
+    const unindexed = perStore.filter((p) => !p.hasIndex).map((p) => p.ref.relPath || '.').sort();
     if (indexed.length === 0) {
-        return {
-            status: 'missing_index',
-            coarse: 'missing',
-            details: {
-                traversal: 'workspace',
-                projects_indexed: 0,
-                projects_total: total,
-                unindexed_projects: unindexed,
-                hint: 'run refresh --cascade',
-            },
-        };
+        return makeFreshnessBadge('missing_index', {
+            extra: { traversal: 'workspace', projects_indexed: 0, projects_total: total, unindexed_projects: unindexed, hint: 'run refresh --cascade' },
+        });
     }
     let worst = indexed[0].badge.status;
     for (const p of indexed) {
@@ -221,12 +210,11 @@ function mergeBadges(perStore) {
     };
     if (unindexed.length)
         details.unindexed_projects = unindexed;
-    // Merge the per-store detail path-sets, prefixing each with its store's
-    // workspace-relative dir so a bare `src/index.ts` isn't ambiguous across packages.
     const prefixMerge = (key) => {
         const out = [];
         for (const p of indexed) {
-            const arr = p.badge.details?.[key];
+            const spot = p.badge.details.spot_check;
+            const arr = spot?.[key];
             if (Array.isArray(arr)) {
                 for (const f of arr)
                     out.push(p.ref.relPath ? `${p.ref.relPath}/${String(f)}` : String(f));
@@ -234,16 +222,25 @@ function mergeBadges(perStore) {
         }
         return out.sort();
     };
-    for (const key of ['stale_changed_files', 'deleted_files', 'unchecked_files']) {
-        const merged = prefixMerge(key);
-        if (merged.length)
-            details[key] = merged;
-    }
-    const partialStore = indexed.find((p) => p.badge.status === 'partial');
-    if (partialStore) {
-        details.partial_reason = partialStore.badge.details?.partial_reason ?? 'lazy_check_budget_exhausted';
-    }
-    return { status: worst, coarse: coarseFreshness(worst), details };
+    const spotChecks = indexed.map((p) => p.badge.details.spot_check);
+    const spotStatus = spotChecks.some((spot) => spot?.status === 'partial')
+        ? 'partial'
+        : spotChecks.some((spot) => spot?.status === 'stale')
+            ? 'stale'
+            : spotChecks.some((spot) => spot?.status === 'fresh') ? 'fresh' : 'not_run';
+    const partialSpot = spotChecks.find((spot) => spot?.status === 'partial');
+    return makeFreshnessBadge(worst, {
+        spotCheck: {
+            status: spotStatus,
+            checked_files: spotChecks.reduce((sum, spot) => sum + (spot?.checked_files ?? 0), 0),
+            stale_changed_files: prefixMerge('stale_changed_files'),
+            deleted_files: prefixMerge('deleted_files'),
+            unchecked_files: prefixMerge('unchecked_files'),
+            budget_exhausted: spotChecks.some((spot) => spot?.budget_exhausted === true),
+            partial_reason: partialSpot?.partial_reason ?? null,
+        },
+        extra: details,
+    });
 }
 /**
  * Aggregated find across a resolved multi-project workspace. Shares ONE lazy budget
@@ -426,9 +423,15 @@ export function aggregateBrief(target, limit, resolved, currentHead, memoryReade
     const seen = new Set();
     const mergedDefiningPaths = new Set();
     const symbolNames = new Set();
+    const memorySymbolNames = new Set();
+    const memoryImportNames = new Set();
     for (const p of contributing) {
         for (const e of p.r.defining)
             symbolNames.add(e.name);
+        for (const name of p.r.memorySymbolNames)
+            memorySymbolNames.add(name);
+        for (const name of p.r.memoryImportNames)
+            memoryImportNames.add(name);
         for (const dp of p.r.definingPaths)
             mergedDefiningPaths.add(p.ref.relPath ? `${p.ref.relPath}/${dp}` : dp);
         for (const rf of p.r.confident) {
@@ -460,8 +463,10 @@ export function aggregateBrief(target, limit, resolved, currentHead, memoryReade
     const capped = reserveSourceSlots(merged, cap, mergedDefiningPaths);
     if (symbolNames.size === 0)
         symbolNames.add(target);
-    const related = attachRelatedMemory(memoryReader({ cwd: resolved.root }), capped.map((f) => f.path), [...symbolNames]);
-    const baseEntries = attachMemoryIds(capped, related);
+    if (memorySymbolNames.size === 0)
+        memorySymbolNames.add(target);
+    const related = attachRelatedMemory(memoryReader({ cwd: resolved.root }), capped.map((f) => f.path), [...memorySymbolNames], [...memoryImportNames]);
+    const baseEntries = attachMemoryIds(capped, related, mergedDefiningPaths);
     const suggested = baseEntries.map((s, i) => ({
         ...s,
         project: capped[i].project,