brainclaw 1.17.0 → 1.18.0

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

@@ -0,0 +1,473 @@
+/**
+ * Code Map workspace AGGREGATION (pln#631 PR1 — root-aggregated find).
+ *
+ * A `find` at a multi-project workspace ROOT must surface symbols defined in ANY
+ * nested child project's store — today it reads only the root store (which, after a
+ * cascade refresh, is scoped to the files no child owns, so a root find returns
+ * almost nothing and the agent falls back to grep). This module fans `findInStore`
+ * out across the root + every nested project store at READ time (no persisted root
+ * super-index, no cross-store index writes) and merges the results.
+ *
+ * The three semantics the design pins (dec#146):
+ *  (a) ONE shared lazy-check budget across stores (the checker's memo is file_id-keyed
+ *      — unique per store — so sharing never collides same-named files across packages).
+ *  (b) Merged badge = WORST status across the *indexed* stores + coverage
+ *      (projects_indexed/total, unindexed_projects); a child with no index must NOT
+ *      drag the top-line to `missing`.
+ *  (c) Dedupe merged matches on (project_id, node_id) and rewrite paths to
+ *      workspace-relative, so the `prj_${basename}` id fallback + same-named files
+ *      across packages can never merge two distinct symbols.
+ *
+ * Cross-package import resolution + brief aggregation + child-initiated workspace
+ * scope are follow-ups (see pln#631).
+ */
+import fs from 'node:fs';
+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 { 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;
+/**
+ * pln#631 (review F2) — an aggregated find shares ONE lazy budget across N stores.
+ * A flat 32-file budget starves alphabetically-later stores (their drifted candidates
+ * get dropped once earlier stores spend it). Scale the budget with the store count so
+ * later stores keep headroom, capped so an interactive read stays bounded even on a
+ * large monorepo. Fully fresh stores cost nothing (the mtime/size gate short-circuits
+ * before the budget), so this only raises the ceiling for genuinely-drifted trees.
+ */
+const AGG_MAX_FILES_CAP = 256;
+const AGG_MAX_WALL_CAP_MS = 10_000;
+function aggregateBudget(storeCount) {
+    return {
+        maxFilesChecked: Math.min(LAZY_BUDGET.maxFilesChecked * Math.max(1, storeCount), AGG_MAX_FILES_CAP),
+        maxWallMs: Math.min(LAZY_BUDGET.maxWallMs * Math.max(1, storeCount), AGG_MAX_WALL_CAP_MS),
+    };
+}
+/**
+ * Walk UP from a child cwd and return the NEAREST ancestor that is a multi-project
+ * workspace root. Preferred over "outermost .brainclaw" (which can over-reach to an
+ * unrelated ancestor project, or a stray ~/tmp/.brainclaw): the immediate enclosing
+ * multi-project root is the child's actual workspace. Bounded ancestor walk.
+ */
+function findEnclosingWorkspaceRoot(startDir) {
+    let dir = path.dirname(path.resolve(startDir)); // the child itself is not its own workspace root
+    const fsRoot = path.parse(dir).root;
+    for (let i = 0; i < 64; i++) {
+        if (isWorkspaceRoot(dir))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir || dir === fsRoot)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}
+/** True when cwd is a multi-project workspace root (the SAME gate the cascade uses). */
+function isWorkspaceRoot(cwd) {
+    let mode;
+    try {
+        mode = loadConfig(cwd).project_mode;
+    }
+    catch {
+        return false;
+    }
+    return mode === 'multi-project' && listNestedProjects(cwd).length > 0;
+}
+/** Read a store's identity + built-against commit in ONE manifest read. */
+function storeMeta(cwd) {
+    const m = readManifest(cwd);
+    const gitHead = m?.git?.head ?? null;
+    if (m?.project_id)
+        return { projectId: m.project_id, gitHead };
+    try {
+        const id = loadConfig(cwd).project_id;
+        if (id)
+            return { projectId: id, gitHead };
+    }
+    catch {
+        /* no config — fall through to a cwd-derived default */
+    }
+    return { projectId: `prj_${path.basename(path.resolve(cwd))}`, gitHead };
+}
+/** True when `localCwd` is `storeCwd` or lives under it (case-folded on win32). */
+function storeContains(storeCwd, localCwd) {
+    const norm = (p) => (process.platform === 'win32' ? path.resolve(p).toLowerCase() : path.resolve(p));
+    const rel = path.relative(norm(storeCwd), norm(localCwd));
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+/**
+ * Build the root + nested-child StoreRefs for a workspace, flagging the caller-local one.
+ * Locality is by CONTAINMENT, not exact equality (review): the caller usually stands in a
+ * `src/…` subdir of its package, not exactly at the package root — the DEEPEST store whose
+ * cwd contains `localCwd` is the caller's own package. Case-insensitive on win32.
+ */
+function buildWorkspaceStores(root, localCwd) {
+    const rootMeta = storeMeta(root);
+    const stores = [
+        { cwd: root, relPath: '', projectId: rootMeta.projectId, gitHead: rootMeta.gitHead, isLocal: false },
+        ...listNestedProjects(root).map((childAbs) => {
+            const meta = storeMeta(childAbs);
+            return {
+                cwd: childAbs,
+                relPath: path.relative(root, childAbs).replace(/\\/g, '/'),
+                projectId: meta.projectId,
+                gitHead: meta.gitHead,
+                isLocal: false,
+            };
+        }),
+    ];
+    // The caller-local store = the DEEPEST (longest cwd) store containing localCwd.
+    let localStore;
+    for (const s of stores) {
+        if (storeContains(s.cwd, localCwd) && (!localStore || s.cwd.length > localStore.cwd.length)) {
+            localStore = s;
+        }
+    }
+    if (localStore)
+        localStore.isLocal = true;
+    return stores;
+}
+/**
+ * Resolve which stores a find/brief should read.
+ *  - `auto` (default): aggregate the whole workspace ONLY when cwd is itself a
+ *    multi-project root; otherwise single-store (a child cwd stays local, unchanged).
+ *  - `project`: force single-store.
+ *  - `workspace`: aggregate the whole workspace. At a root, same as auto. From a CHILD
+ *    cwd (pln#631 PR4), walk UP to the workspace root and aggregate from there, keeping
+ *    the caller's package flagged `isLocal` for the locality tiebreak — so an agent
+ *    inside `packages/api` can search the whole monorepo, with its own package's hits
+ *    ranked first. Degrades to single-store only when no multi-project root is found.
+ */
+export function resolveTraversal(cwd, mode) {
+    const abs = path.resolve(cwd);
+    if ((mode === 'auto' || mode === 'workspace') && isWorkspaceRoot(abs)) {
+        return { workspace: true, root: abs, stores: buildWorkspaceStores(abs, abs) };
+    }
+    if (mode === 'workspace') {
+        // Explicit workspace request from a non-root cwd: find the NEAREST enclosing
+        // multi-project root and aggregate from there (auto never does this).
+        const wsRoot = findEnclosingWorkspaceRoot(abs);
+        if (wsRoot) {
+            return { workspace: true, root: wsRoot, stores: buildWorkspaceStores(wsRoot, abs) };
+        }
+    }
+    const meta = storeMeta(abs);
+    return {
+        workspace: false,
+        root: abs,
+        stores: [{ cwd: abs, relPath: '', projectId: meta.projectId, gitHead: meta.gitHead, isLocal: true }],
+    };
+}
+/** Worst-status precedence for the merged badge (higher = worse = surfaced). */
+function statusRank(s) {
+    switch (s) {
+        case 'partial':
+            return 4;
+        case 'stale_changed_files':
+        case 'stale_extractor':
+        case 'stale_grammar':
+        case 'stale_git_head':
+            return 3;
+        case 'fresh':
+            return 1;
+        case 'missing_index':
+            return 0;
+        default: {
+            const _exhaustive = s;
+            void _exhaustive;
+            return 0;
+        }
+    }
+}
+/**
+ * Merge per-store badges into one workspace badge: worst status among the INDEXED
+ * stores (a missing-index child contributes to coverage, never drags the top-line),
+ * plus coverage + workspace-relative detail path-sets. Only when EVERY store is
+ * un-indexed is the whole workspace `missing_index`.
+ */
+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();
+    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',
+            },
+        };
+    }
+    let worst = indexed[0].badge.status;
+    for (const p of indexed) {
+        if (statusRank(p.badge.status) > statusRank(worst))
+            worst = p.badge.status;
+    }
+    const details = {
+        traversal: 'workspace',
+        projects_indexed: indexed.length,
+        projects_total: total,
+        per_project: Object.fromEntries(perStore.map((p) => [p.ref.relPath || '.', p.badge.status])),
+    };
+    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];
+            if (Array.isArray(arr)) {
+                for (const f of arr)
+                    out.push(p.ref.relPath ? `${p.ref.relPath}/${String(f)}` : String(f));
+            }
+        }
+        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 };
+}
+/**
+ * Aggregated find across a resolved multi-project workspace. Shares ONE lazy budget
+ * across stores; dedupes on (project_id, node_id); rewrites paths workspace-relative;
+ * re-ranks with the single-store comparator; caps; and merges the freshness badges.
+ */
+export function aggregateFind(query, limit, resolved, currentHead) {
+    // ONE shared budget across every store, scaled by store count (review F2) so
+    // alphabetically-later stores aren't starved by earlier dirty trees.
+    const checker = makeLazyChecker(aggregateBudget(resolved.stores.length));
+    const perStore = [];
+    const merged = [];
+    const seen = new Set(); // (project_id, node_id)
+    for (const ref of resolved.stores) {
+        const acc = newAccumulator();
+        const r = findInStore(query, { cwd: ref.cwd }, checker, acc);
+        // Per-store badge: drive `partial` from THIS store's own budget-skips (review F2),
+        // NOT the shared checker.exhausted flag — else an early store spending the budget
+        // would mislabel every fully-fresh later store as `partial` in per_project. Then
+        // apply per-store HEAD drift against the one workspace HEAD (review F3) so a child
+        // whose index lags the working tree is flagged even under an otherwise-fresh root.
+        let badge = deriveBadge(r.base, acc, false, r.matches.length > 0, r.emptyCandidates);
+        badge = applyGitHeadDrift(badge, ref.gitHead, currentHead);
+        perStore.push({ ref, badge, hasIndex: r.hasIndex });
+        for (const m of r.matches) {
+            // Dedup key scoped by store cwd (unique per store), NEVER project_id — two stores
+            // can share a project_id (review F1), which would false-merge/drop a distinct symbol.
+            // Cross-store never merges (different packages = different symbols).
+            const key = `${ref.cwd} ${m.node_id}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            merged.push({
+                ...m,
+                path: ref.relPath ? `${ref.relPath}/${m.path}` : m.path,
+                project: ref.relPath,
+                project_id: ref.projectId,
+                ...(ref.isLocal ? { local: true } : {}),
+            });
+        }
+    }
+    // Sort by score, then LOCALITY (caller's own package first — PR4 tiebreak), then path.
+    merged.sort((a, b) => b.score - a.score ||
+        (b.local ? 1 : 0) - (a.local ? 1 : 0) ||
+        a.path.localeCompare(b.path) ||
+        a.name.localeCompare(b.name));
+    const capped = merged.slice(0, limit ?? DEFAULT_FIND_LIMIT);
+    return { query, matches: capped, freshness_badge: mergeBadges(perStore) };
+}
+/** Match-tier precedence for cross-store target selection: exact > path > fuzzy > none. */
+function briefMatchTier(k) {
+    return k === 'exact' ? 3 : k === 'path' ? 2 : k === 'fuzzy' ? 1 : 0;
+}
+/** Read a store's package.json `name` (the specifier siblings import it as), or null. */
+function packageNameOf(cwd) {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf-8'));
+        return typeof pkg.name === 'string' && pkg.name.length > 0 ? pkg.name : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Cross-package reverse dependents (pln#631 PR3): sibling packages that IMPORT the
+ * defining package's public name. READ-TIME only — no cross-store index writes (the
+ * per-project-store-write invariant is inviolate). For each defining store B (package
+ * name `nameB`), scan every OTHER store A's imports index for specifiers `=== nameB`
+ * or `startsWith(nameB + '/')`; each importer file is a cross-package dependent.
+ * NAME-LEVEL precision: an importer whose `imported[]` names one of the target symbols
+ * ranks above a bare package-level import. Reverse-deps ONLY — forward cross-package
+ * deps have no single target file (deferred). Rows are graph-derived + flagged
+ * cross_package so their (name-based, lower) confidence is legible.
+ */
+function crossPackageReverseDeps(contributing, allStores, symbolNames, checker) {
+    const targetPkgNames = new Map(); // package name -> defining store B
+    for (const ref of contributing) {
+        const name = packageNameOf(ref.cwd);
+        if (name)
+            targetPkgNames.set(name, ref);
+    }
+    if (targetPkgNames.size === 0)
+        return [];
+    const matchesTarget = (spec) => {
+        for (const nameB of targetPkgNames.keys()) {
+            if (spec === nameB || spec.startsWith(`${nameB}/`))
+                return true;
+        }
+        return false;
+    };
+    // Aggregate per IMPORTER FILE across ALL matching specifiers first (review F2): a file
+    // importing the target package under two specifiers — one name-level, one bare — must
+    // be scored by its BEST precision, not by whichever specifier `Object.entries` happens
+    // to yield first. Keyed by store cwd + path (never project_id).
+    const contributingCwds = new Set(contributing.map((r) => r.cwd));
+    const byImporter = new Map();
+    for (const a of allStores) {
+        if (contributingCwds.has(a.cwd))
+            continue; // intra-package deps already covered
+        const imports = readImportsIndex(a.cwd);
+        if (!imports)
+            continue;
+        for (const [spec, importers] of Object.entries(imports.entries)) {
+            if (!matchesTarget(spec))
+                continue;
+            for (const imp of importers) {
+                const key = `${a.cwd}::${imp.path}`;
+                let agg = byImporter.get(key);
+                if (!agg) {
+                    agg = { cwd: a.cwd, relPath: a.relPath, path: imp.path, file_id: imp.file_id, local: a.isLocal, namedHits: new Set(), specs: new Set() };
+                    byImporter.set(key, agg);
+                }
+                agg.specs.add(spec);
+                for (const n of imp.imported)
+                    if (symbolNames.has(n))
+                        agg.namedHits.add(n);
+            }
+        }
+    }
+    // Emit one row per importer — but LAZY-VALIDATE it against its store first (review F1):
+    // a cross-package row is graph-derived, so a deleted/stale importer must be SUPPRESSED
+    // just like an intra-package graph row (no silent stale graph hints). Shares the one
+    // budget; a throwaway acc (row-drop only — the sibling store's manifest freshness
+    // already rides the merged badge via its per-store briefInStore).
+    const rows = [];
+    const acc = newAccumulator();
+    for (const agg of byImporter.values()) {
+        const ok = validateStoreEntry({ path: agg.path, file_id: agg.file_id }, checker, acc, agg.cwd, undefined);
+        if (!ok)
+            continue; // deleted / stale / budget-skipped → suppress (graph-derived)
+        const nameLevel = agg.namedHits.size > 0;
+        const score = nameLevel ? 5 : 3; // name-level ranks with reverse-deps; package-level below
+        const shortestSpec = [...agg.specs].sort((x, y) => x.length - y.length)[0] ?? '';
+        rows.push({
+            path: agg.relPath ? `${agg.relPath}/${agg.path}` : agg.path,
+            file_id: agg.file_id,
+            reason: nameLevel
+                ? `cross-package: imports ${[...agg.namedHits].sort().join(', ')} from ${shortestSpec}`
+                : `cross-package: imports ${shortestSpec}`,
+            score,
+            bestDelta: score,
+            graphDerived: true,
+            project: agg.relPath,
+            cross_package: true,
+            ...(agg.local ? { local: true } : {}),
+        });
+    }
+    return rows;
+}
+/**
+ * Aggregated brief across a resolved multi-project workspace (pln#631 PR2). Resolves
+ * the target in EVERY store (shared budget), then contributes reading lists ONLY from
+ * the stores at the HIGHEST match tier present (exact > path > fuzzy) — so a symbol
+ * defined exactly in one package is never diluted by fuzzy token-noise from siblings,
+ * while a name defined exactly in two packages briefs both. Reading-list paths are
+ * workspace-relative + project-tagged; the source-reserve + memory attach run on the
+ * MERGED list. Related memory comes from the ROOT project only in PR2 (cross-package
+ * memory attach = follow-up). The badge merges per-store (worst-status + coverage,
+ * per-store HEAD drift) exactly like aggregateFind.
+ */
+export function aggregateBrief(target, limit, resolved, currentHead, memoryReader) {
+    const checker = makeLazyChecker(aggregateBudget(resolved.stores.length));
+    const perStore = resolved.stores.map((ref) => {
+        const acc = newAccumulator();
+        const r = briefInStore(target, { cwd: ref.cwd }, checker, acc);
+        let badge = deriveBadge(r.base, acc, false, r.confident.length > 0, r.emptyRanked);
+        badge = applyGitHeadDrift(badge, ref.gitHead, currentHead);
+        return { ref, r, badge };
+    });
+    // Contribute reading lists from the stores at the highest match TIER present (no
+    // fuzzy dilution). But when NO store DEFINES the target (bestTier 0), fall back to
+    // any store with a non-empty reading list — rankFiles' import-specifier heuristic can
+    // surface relevant IMPORTER files even with no defining symbol (review F1: preserves
+    // single-store brief parity for an imported-but-not-locally-defined name like `axios`).
+    const bestTier = Math.max(0, ...perStore.map((p) => briefMatchTier(p.r.matchKind)));
+    const contributing = bestTier > 0
+        ? perStore.filter((p) => briefMatchTier(p.r.matchKind) === bestTier)
+        : perStore.filter((p) => p.r.confident.length > 0);
+    const merged = [];
+    const seen = new Set();
+    const mergedDefiningPaths = new Set();
+    const symbolNames = new Set();
+    for (const p of contributing) {
+        for (const e of p.r.defining)
+            symbolNames.add(e.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) {
+            const key = `${p.ref.cwd}::${rf.path}`; // store-scoped dedup (never project_id)
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            merged.push({
+                ...rf,
+                path: p.ref.relPath ? `${p.ref.relPath}/${rf.path}` : rf.path,
+                project: p.ref.relPath,
+                ...(p.ref.isLocal ? { local: true } : {}),
+            });
+        }
+    }
+    // pln#631 PR3 — cross-package reverse dependents: sibling packages importing the
+    // defining package's public name. Only when a store genuinely DEFINES the target
+    // (bestTier > 0) — the heuristic fallback has no "defining package" to find importers
+    // of. Rows are flagged cross_package; keyed by their own store so they never collide
+    // with the intra-package rows above.
+    if (bestTier > 0) {
+        // crossPackageReverseDeps dedups internally, and its rows come from NON-contributing
+        // stores (distinct workspace-relative paths from the intra-package rows above), so a
+        // direct append cannot collide.
+        merged.push(...crossPackageReverseDeps(contributing.map((p) => p.ref), resolved.stores, symbolNames, checker));
+    }
+    merged.sort((a, b) => b.score - a.score || (b.local ? 1 : 0) - (a.local ? 1 : 0) || a.path.localeCompare(b.path));
+    const cap = Math.min(limit ?? BRIEF_FILE_CAP, BRIEF_FILE_CAP);
+    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);
+    const suggested = baseEntries.map((s, i) => ({
+        ...s,
+        project: capped[i].project,
+        ...(capped[i].cross_package ? { cross_package: true } : {}),
+        ...(capped[i].local ? { local: true } : {}),
+    }));
+    return { target, suggested_files_to_read: suggested, related_memory: related, freshness_badge: mergeBadges(perStore.map((p) => ({ ref: p.ref, badge: p.badge, hasIndex: p.r.hasIndex }))) };
+}
+//# sourceMappingURL=aggregate.js.map

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

@@ -12,15 +12,18 @@ import { execFileSync } from 'node:child_process';
 import path from 'node:path';
 import { readManifest, storeExists } from './store.js';
 import { refresh as runRefresh } from './refresh.js';
-import { applyGitHeadDrift } from './freshness.js';
+import { applyGitHeadDrift, withCoarse } from './freshness.js';
 import { brief as runBrief, find as runFind } from './query.js';
+import { resolveTraversal, aggregateFind, aggregateBrief } from './aggregate.js';
 import { defaultMemoryReader } from './memory-reader.js';
 import { listNestedProjects, refreshWorkspaceCascade } from './cascade.js';
 import { loadConfig } from '../config.js';
 /** spec §9 caps the brief reading list at 12 files. */
 export const BRIEF_FILE_CAP = 12;
 function badge(status, details = {}) {
-    return { 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 });
 }
 /**
  * Read the working tree's current commit at `root` (read-path git-HEAD drift,
@@ -185,13 +188,25 @@ export class JsonlBackend {
      * as confident (§6.1); the response badge reflects any detected drift.
      */
     async find(input) {
+        const cwd = input.cwd ?? process.cwd();
+        const resolved = resolveTraversal(cwd, input.traversal ?? 'auto');
+        if (resolved.workspace) {
+            // pln#631 — root-aggregated find across the workspace's per-project stores.
+            // git-HEAD drift is resolved ONCE at the workspace root (one working tree) and
+            // compared PER STORE inside aggregateFind (review F3) — so a child whose index
+            // lags the working tree is flagged even under an otherwise-fresh root.
+            const currentHead = this.gitHeadReader(resolved.root);
+            const agg = aggregateFind(input.query, input.limit, resolved, currentHead);
+            return {
+                query: agg.query,
+                matches: agg.matches,
+                freshness_badge: agg.freshness_badge,
+            };
+        }
         const ctx = this.queryContext(input);
         const out = runFind(input.query, input.limit, ctx);
         const manifest = readManifest(input.cwd, input.preferredDirName);
-        const base = {
-            status: out.freshness_badge.status,
-            details: out.freshness_badge.details,
-        };
+        const base = badge(out.freshness_badge.status, out.freshness_badge.details);
         return {
             query: out.query,
             matches: out.matches,
@@ -204,13 +219,24 @@ export class JsonlBackend {
      * and carries a §6.1 lazy-validated freshness badge.
      */
     async brief(input) {
+        const cwd = input.cwd ?? process.cwd();
+        const resolved = resolveTraversal(cwd, input.traversal ?? 'auto');
+        if (resolved.workspace) {
+            // pln#631 PR2 — root-aggregated brief across the per-project stores (per-store
+            // HEAD drift resolved against ONE workspace HEAD, like aggregateFind).
+            const currentHead = this.gitHeadReader(resolved.root);
+            const agg = aggregateBrief(input.target, input.limit, resolved, currentHead, this.memoryReader);
+            return {
+                target: agg.target,
+                suggested_files_to_read: agg.suggested_files_to_read,
+                related_memory: agg.related_memory,
+                freshness_badge: agg.freshness_badge,
+            };
+        }
         const ctx = this.queryContext(input);
         const out = runBrief(input.target, input.limit, ctx, this.memoryReader);
         const manifest = readManifest(input.cwd, input.preferredDirName);
-        const base = {
-            status: out.freshness_badge.status,
-            details: out.freshness_badge.details,
-        };
+        const base = badge(out.freshness_badge.status, out.freshness_badge.details);
         return {
             target: out.target,
             suggested_files_to_read: out.suggested_files_to_read,

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

@@ -15,6 +15,40 @@
  *    extractor_config_hash + per-language grammar hashes.
  */
 import crypto from 'node:crypto';
+/**
+ * pln#601 — collapse the detailed 7-value {@link FreshnessStatus} into the coarse,
+ * surface-uniform signal (`fresh|stale|partial|missing`). Every `stale_*` variant
+ * rolls up to `stale`; `missing_index` → `missing`; `partial`/`fresh` pass through.
+ * This is the SINGLE definition of the rollup so no surface can disagree.
+ */
+export function coarseFreshness(status) {
+    switch (status) {
+        case 'fresh':
+            return 'fresh';
+        case 'partial':
+            return 'partial';
+        case 'missing_index':
+            return 'missing';
+        case 'stale_changed_files':
+        case 'stale_extractor':
+        case 'stale_grammar':
+        case 'stale_git_head':
+            return 'stale';
+        default: {
+            // Exhaustiveness guard (pln#601 review F4): every FreshnessStatus is mapped
+            // explicitly above. If the enum grows, this `never` assignment fails to
+            // compile — forcing a deliberate classification instead of a new status
+            // silently rolling up to 'stale'.
+            const _exhaustive = status;
+            void _exhaustive;
+            return 'stale';
+        }
+    }
+}
+/** pln#601 — stamp/refresh a badge's `coarse` rollup from its (possibly just-adjusted) status. */
+export function withCoarse(b) {
+    return { ...b, coarse: coarseFreshness(b.status) };
+}
 /** Stable serialization: sort object keys recursively so hashing is order-independent. */
 function stableStringify(value) {
     if (value === null || typeof value !== 'object')
@@ -131,10 +165,11 @@ export function summarizeFreshness(shards) {
  */
 export function applyGitHeadDrift(badge, indexHead, currentHead) {
     if (!indexHead || !currentHead || indexHead === currentHead)
-        return badge;
+        return withCoarse(badge);
     const status = badge.status === 'fresh' ? 'stale_git_head' : badge.status;
     return {
         status,
+        coarse: coarseFreshness(status),
         details: {
             ...badge.details,
             git_head_changed: { index_head: indexHead, current_head: currentHead },

package/dist/core/code-map/lang/c/imports.scm

@@ -0,0 +1,12 @@
+; Code Map — C imports (imports.scm). Provider #6 (langs batch 2).
+;
+; enclosingStatementNodeTypes = [preproc_include] (the import span/ordinal anchor).
+; A `#include` path comes in two grammar shapes:
+;   #include <stdio.h>   -> path: (system_lib_string)  text = "<stdio.h>"
+;   #include "config.h"  -> path: (string_literal)      text = "\"config.h\""
+; Both are captured as @import.source; the provider's refine() strips the angle
+; brackets (`<...>`) or the surrounding double quotes (`"..."`) to the bare header
+; path. C has no imported-name bindings, so imported_names stays empty.
+
+(preproc_include
+  path: [(system_lib_string) (string_literal)] @import.source)