brainclaw 1.25.0 → 1.26.1

package/dist/commands/code-map.js

@@ -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();

package/dist/commands/mcp.js

@@ -1097,7 +1097,7 @@ async function _executeMcpToolCallInner(payload) {
                 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,7 @@ 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 },
                     }),
                 };
@@ -1143,7 +1143,7 @@ async function _executeMcpToolCallInner(payload) {
                 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.status}` }],
+                        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 },
                     }),
                 };
@@ -1159,7 +1159,7 @@ async function _executeMcpToolCallInner(payload) {
                 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.status}` }],
+                        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 },
                     }),
                 };
@@ -1174,7 +1174,7 @@ async function _executeMcpToolCallInner(payload) {
                 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.status}` }],
+                        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 },
                     }),
                 };
@@ -1188,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,9 +2,9 @@ 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 { assertSafeSessionId, isSessionSnapshotRecordFilename, memoryExists, resolveEntityDir, sessionSnapshotRecordPaths } from '../core/io.js';
 import { loadVersionedJsonFile, saveVersionedJsonFile } from '../core/migration.js';
-import { buildOperationalIdentity, loadAllSessions, saveCurrentSession } from '../core/identity.js';
+import { buildOperationalIdentity, describeIgnoredSessionIdEnv, loadAllSessions, saveCurrentSession } from '../core/identity.js';
 import { requireMinimumTrustLevel, resolveCurrentModel, resolveOrAutoRegisterAgentIdentity } from '../core/agent-registry.js';
 import { buildContext, renderContextPromptTemplate } from '../core/context.js';
 import { writeContextMarker } from '../core/freshness.js';
@@ -25,11 +25,86 @@ 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`);
+    // pln#672 review P1 — THE SECOND WRITER. This builder was unguarded while
+    // sessionFilePathIn / sessionSnapshotRecordPaths were hardened, so an
+    // env-controlled traversal still escaped the store HERE, before the
+    // current_session write refused it (reproduced by the reviewer:
+    // `ESCAPED.snapshot.json` landed outside, and the later throw did not undo
+    // the escaped write). A guard on some builders is not a guard.
+    assertSafeSessionId(sessionId);
+    return path.join(sessionSnapshotWriteDir(cwd), `${sessionId}.snapshot.json`);
+}
+/**
+ * pln#672 review P2 — the snapshot write needs the same positive proof the
+ * current_session write already has. On a case-insensitive filesystem
+ * `CaseSnapshot` and `casesnapshot` name the SAME file, so a second session
+ * silently overwrote the first one's snapshot. Refuse to replace a record
+ * that names a different session; identical-id rewrites (heartbeat, restart)
+ * stay allowed.
+ */
+function assertSnapshotSlotFree(filepath, sessionId) {
+    if (!fs.existsSync(filepath))
+        return;
+    try {
+        const raw = JSON.parse(fs.readFileSync(filepath, 'utf-8'));
+        if (typeof raw.session_id === 'string' && raw.session_id !== sessionId) {
+            throw new Error(`Refusing to overwrite the session_snapshot of '${raw.session_id}' at '${filepath}' with '${sessionId}' — the two ids resolve to the same filename on this filesystem`);
+        }
+    }
+    catch (err) {
+        // A deliberate refusal propagates; an unreadable record does not block a
+        // fresh write (it is not proof that another session owns the slot).
+        if (err instanceof Error && err.message.startsWith('Refusing to overwrite'))
+            throw err;
+    }
+}
+/**
+ * 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 {
@@ -101,6 +176,11 @@ export async function runSessionStart(options = {}) {
         if (snapshot.stale_surfaces) {
             console.warn(`⚠ ${snapshot.stale_surfaces.message}`);
         }
+        // pln#672 — a dropped env session id must reach the human too: the whole
+        // point of the warning is that the session identity is NOT the one asked for.
+        if (snapshot.invalid_session_id_ignored) {
+            console.warn(`⚠ ${snapshot.invalid_session_id_ignored.message}`);
+        }
         // Fifth instance of the computed-then-dropped class, caught by the new seam
         // guard on its first run: built since the shared-checkout detection landed,
         // read by nothing. Two agents editing one checkout is precisely what a human
@@ -155,10 +235,12 @@ 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));
+    const snapshotPath = sessionSnapshotPath(snapshot.session_id, options.cwd);
+    assertSnapshotSlotFree(snapshotPath, snapshot.session_id);
+    saveVersionedJsonFile('session_snapshot', snapshotPath, SessionSnapshotSchema.parse(snapshot));
     // Resolve git branch and worktree for session tracking
     let currentBranch;
     let currentWorktreePath;
@@ -218,6 +300,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
@@ -319,6 +409,18 @@ export async function startSession(options = {}) {
         staleSurfaces = staleSurfaceWarning(freshness, currentVersion);
     }
     catch { /* non-fatal */ }
+    // pln#672 — report a DROPPED env session id. Never echo the raw value: it is
+    // attacker-influenced and would land straight in logs; the variable name and
+    // its length are enough to diagnose.
+    let invalidSessionIdIgnored;
+    const droppedSessionEnv = describeIgnoredSessionIdEnv();
+    if (droppedSessionEnv) {
+        invalidSessionIdIgnored = {
+            code: 'invalid_session_id_ignored',
+            message: `${droppedSessionEnv.variable} carries a session id that cannot be a record filename (${droppedSessionEnv.length} chars) — it was ignored and this session runs under '${snapshot.session_id}'. Unset or fix the variable to resume the intended session.`,
+            data: { variable: droppedSessionEnv.variable, length: droppedSessionEnv.length, effective_session_id: snapshot.session_id },
+        };
+    }
     // Materialize incoming federation signals from linked projects (Phase 0 — local)
     if (maintenanceMode === 'full') {
         try {
@@ -354,6 +456,7 @@ export async function startSession(options = {}) {
         ...(staleClaimsReleased ? { stale_claims_released: staleClaimsReleased } : {}),
         ...(memoryPressure ? { memory_pressure: memoryPressure } : {}),
         ...(staleSurfaces ? { stale_surfaces: toWarningDetail(staleSurfaces) } : {}),
+        ...(invalidSessionIdIgnored ? { invalid_session_id_ignored: toWarningDetail(invalidSessionIdIgnored) } : {}),
         ...(autoRegistered ? { auto_registered: true } : {}),
     };
 }
@@ -367,14 +470,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,

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

@@ -12,7 +12,7 @@ import { execFileSync } from 'node:child_process';
 import path from 'node:path';
 import { readManifest, readShard, storeExists } from './store.js';
 import { refresh as runRefresh } from './refresh.js';
-import { applyGitHeadDrift, withCoarse } from './freshness.js';
+import { applyGitHeadDrift, withFreshness } from './freshness.js';
 import { brief as runBrief, find as runFind } from './query.js';
 import { impact as runImpact } from './impact.js';
 import { exportSubgraph } from './export.js';
@@ -32,9 +32,9 @@ export const OUTLINE_SYMBOL_CAP = 200;
 /** Diagnostics are useful context, but unbounded provider facts are not. */
 export const OUTLINE_DIAGNOSTIC_CAP = 20;
 function badge(status, details = {}) {
-    // pln#601 — stamp the coarse rollup at construction so every backend-built badge
-    // (status, missing_index fallbacks, find/brief base) carries it uniformly.
-    return withCoarse({ status, details });
+    // pln#601 — build the uniform freshness envelope for every backend surface
+    // It always includes index and spot-check details.
+    return withFreshness({ status, details });
 }
 /**
  * Convert a user path into the POSIX project-relative identity used by shards.

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

@@ -15,6 +15,7 @@ function fileOnlyResult(input, parseStatus) {
         imports: [],
         exports: [],
         tests: [],
+        usages: [],
         facts: [{ code: 'skipped_unsupported', message: `no provider for ${input.path}` }],
         attributes: { parseStatus },
     }, input);

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

@@ -3,7 +3,7 @@
  * model; it never takes a second, potentially different graph traversal.
  */
 import path from 'node:path';
-import { withCoarse } from './freshness.js';
+import { withFreshness } from './freshness.js';
 import { listShards, readManifest } from './store.js';
 /** Absolute traversal and response ceilings: a whole-graph export is impossible. */
 export const CODE_EXPORT_MAX_DEPTH = 4;
@@ -113,12 +113,12 @@ export function exportSubgraph(targetInput, options, ctx) {
         min_confidence: clampConfidence(options?.minConfidence),
     };
     const manifest = readManifest(ctx.cwd, ctx.preferredDirName);
-    const missing = withCoarse({ status: 'missing_index', details: { hint: 'run refresh' } });
+    const missing = withFreshness({ status: 'missing_index', details: { hint: 'run refresh' } });
     if (!manifest || manifest.freshness.status === 'missing_index' || !target)
         return emptyOutput(target, targetKind, limits, missing, format);
     const targetPath = targetKind === 'file' ? normalizeFileTarget(target, manifest.project_root) : null;
     if (targetKind === 'file' && !targetPath) {
-        return emptyOutput(target, targetKind, limits, withCoarse({
+        return emptyOutput(target, targetKind, limits, withFreshness({
             status: manifest.freshness.status, details: { invalid_target: 'file path must be inside the indexed project' },
         }), format);
     }
@@ -187,7 +187,7 @@ export function exportSubgraph(targetInput, options, ctx) {
         nodes: [...selected].map((id) => nodes.get(id)).filter((node) => node !== undefined).sort(compareNodes).map(graphNode),
         edges: [...selectedEdges.values()].sort(compareEdges).map(graphEdge),
         limits, truncated: { roots: rootsTruncated, nodes: nodesTruncated, edges: edgesTruncated, depth: depthTruncated },
-        freshness_badge: withCoarse({ status: manifest.freshness.status,
+        freshness_badge: withFreshness({ status: manifest.freshness.status,
             details: { stale_file_count: manifest.freshness.stale_file_count, partial_reason: manifest.freshness.partial_reason } }),
     };
     return format === 'mermaid' ? { ...graph, format, mermaid: toMermaid(graph) } : { ...graph, format };

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

@@ -82,6 +82,9 @@ export function finalize(draft, input) {
     const byName = new Map();
     // node id -> index in `nodes`, so an export clause can flip `exported` in place.
     const nodeIndexById = new Map();
+    // P4 resolves provider draft ordinals to final symbol ids only here, after the
+    // identity authority has minted them. This keeps providers id-free.
+    const definitionIdsByOrdinal = new Map();
     const pushSymbol = (subtype, name, span, exported, confidence) => {
         const id = symNodeId(projectId, path, lang, subtype, name, span);
         nodeIndexById.set(id, nodes.length);
@@ -127,7 +130,8 @@ export function finalize(draft, input) {
     for (const item of items) {
         if (item.kind === 'def') {
             const d = item.ref;
-            pushSymbol(d.subtype, d.name, d.span, d.exported === true, d.confidence ?? 1.0);
+            const id = pushSymbol(d.subtype, d.name, d.span, d.exported === true, d.confidence ?? 1.0);
+            definitionIdsByOrdinal.set(d.ordinal, id);
         }
         else if (item.kind === 'import') {
             const im = item.ref;
@@ -179,6 +183,46 @@ export function finalize(draft, input) {
             });
         }
     }
+    // P4 lexical usages. Local targets are already proven by the provider's tree
+    // walk; imported bindings become candidates and are materialized only by the
+    // whole-project resolver when the target symbol is unique and importable.
+    const referenceCandidates = [];
+    for (const usage of draft.usages ?? []) {
+        const from = usage.fromDefinitionOrdinal === undefined
+            ? fileNode
+            : definitionIdsByOrdinal.get(usage.fromDefinitionOrdinal);
+        if (!from)
+            continue;
+        const confidence = usage.confidence ?? 1.0;
+        const source = { path, line: usage.span.start_line };
+        if (usage.target.kind === 'import') {
+            // Textual hints are deliberately local-only. An imported binding gets no
+            // graph edge until `resolveProjectImports` proves its target symbol.
+            if (usage.kind === 'calls' || usage.kind === 'references') {
+                referenceCandidates.push({
+                    from,
+                    kind: usage.kind,
+                    module: usage.target.module,
+                    imported_name: usage.target.importedName,
+                    confidence,
+                    source,
+                });
+            }
+            continue;
+        }
+        const to = definitionIdsByOrdinal.get(usage.target.definitionOrdinal);
+        if (!to)
+            continue;
+        edges.push({
+            id: edgeId({ projectId, from, to, kind: usage.kind }),
+            from,
+            to,
+            kind: usage.kind,
+            confidence,
+            source,
+            origin: usage.kind === 'possible_textual_match' ? 'usage_textual' : 'usage_local',
+        });
+    }
     const parseStatus = draft.attributes?.parseStatus ?? 'parsed';
     const diagnostics = draft.facts.map((f) => ({ ...f }));
     // Validate the finalized output against the durable schemas (spec §6).
@@ -186,6 +230,17 @@ export function finalize(draft, input) {
         NodeSchema.parse(n);
     for (const e of edges)
         EdgeSchema.parse(e);
-    return { parseStatus, nodes, edges, diagnostics };
+    const result = { parseStatus, nodes, edges, diagnostics };
+    // P1's oracle intentionally compares the enumerable JSON result. Keep the
+    // resolver hand-off available to refresh without changing that stable shape.
+    if (referenceCandidates.length > 0) {
+        Object.defineProperty(result, 'referenceCandidates', {
+            value: referenceCandidates,
+            enumerable: false,
+            configurable: false,
+            writable: false,
+        });
+    }
+    return result;
 }
 //# sourceMappingURL=finalizer.js.map