codedeep-mcp 0.1.0 → 0.2.0

package/dist/tools/get-context.js

@@ -1,16 +1,22 @@
 import { isCallerOf, isClassMember, } from '../indexer/code-index.js';
 import { errMsg } from '../logger.js';
+import { qualifiedSymbolName } from '../notes/note-store.js';
+import { computeNoteStatusSafe, newCommitCache, newFileProbeCache, } from '../notes/staleness.js';
 import { classNameFromFqn } from '../types.js';
-import { BEHAVIORAL_TAG, MODULE_LEVEL, NAME_MATCH_HEADER_QUALIFIER, NAME_MATCH_TAG, STRUCTURAL_TAG, displaySignature, formatComplexity, normalizeFilePath, pickByLine, plural, readinessBanner, renderAmbiguous, renderSuggestions, safeReadIndexedFile, sectionOrEmpty, sectionOrNone, textResponse, topCoChangePartners, } from './common.js';
+import { renderNote } from './note-render.js';
+import { BEHAVIORAL_TAG, MODULE_LEVEL, NAME_MATCH_HEADER_QUALIFIER, NAME_MATCH_TAG, STRUCTURAL_TAG, displaySignature, estimate, formatComplexity, normalizeFilePath, pickByLine, plural, readinessBanner, renderAmbiguous, renderSuggestions, safeReadIndexedFile, sectionOrEmpty, sectionOrNone, textResponse, topCoChangePartners, } from './common.js';
 const DEFAULT_MAX_TOKENS = 3000;
 const SUGGEST_LIMIT = 5;
 // `exported_by` is intentionally absent: the TS extractor skips re-export
 // statements (`export { x } from './y'`), so any "exported by" listing in
 // Phase 1a would only surface coincidentally same-named exports from
 // unrelated files. The section returns when re-export edges land.
-// `co_changes` and `git` sit last: they render at the end and are the
-// first casualties under max_tokens pressure (enrichment, not core).
-const ALL_SECTIONS = ['body', 'callers', 'callees', 'coupling', 'imports', 'co_changes', 'git'];
+// `notes` (anchored knowledge-layer notes, staleness-checked) sits after the
+// structural sections — enrichment must never displace body/callers — but
+// above the git tail: a curated note about THIS symbol outranks generic
+// churn data. `co_changes` and `git` sit last: they render at the end and are
+// the first casualties under max_tokens pressure (enrichment, not core).
+const ALL_SECTIONS = ['body', 'callers', 'callees', 'coupling', 'imports', 'notes', 'co_changes', 'git'];
 function truncationNote(at, maxTokens) {
     return `(Sections from \`${at}\` onward omitted to stay within max_tokens=${maxTokens}.)`;
 }
@@ -60,7 +66,7 @@ export async function runGetContext(args, deps) {
         if (file === null) {
             return textResponse(`Error: file "${args.file}" is outside the project root.`);
         }
-        const include = parseInclude(args.include);
+        const { include, note: includeNote } = parseInclude(args.include);
         const maxTokens = args.max_tokens ?? DEFAULT_MAX_TOKENS;
         const banner = readinessBanner(deps.indexer.ready);
         if (args.symbol !== undefined) {
@@ -69,25 +75,46 @@ export async function runGetContext(args, deps) {
                 return textResponse('Error: symbol must be non-empty.');
             }
             const body = await renderSymbolMode(file, trimmed, args.line, include, maxTokens, deps);
-            return textResponse(banner + body);
+            return textResponse(banner + includeNote + body);
         }
-        return textResponse(banner + (await renderFileMode(file, include, maxTokens, deps)));
+        return textResponse(banner + includeNote + (await renderFileMode(file, include, maxTokens, deps)));
     }
     catch (err) {
         return textResponse(`Error: ${errMsg(err)}`);
     }
 }
+// Unknown section names are SURFACED, never silently dropped: a typo'd
+// `include: ["callrs"]` used to yield an empty shell that read as "no data
+// here" — a false conclusion the agent then acts on. Unknown keys produce an
+// in-band note listing the valid names, and when NOTHING valid remains the
+// filter falls back to ALL_SECTIONS (a full answer with a correction beats an
+// empty one). An explicit empty array means the default too. Hyphens fold to
+// underscores so `co-changes` finds `co_changes`.
 function parseInclude(input) {
-    if (!input)
-        return new Set(ALL_SECTIONS);
+    if (!input || input.length === 0) {
+        return { include: new Set(ALL_SECTIONS), note: '' };
+    }
     const set = new Set();
+    const unknown = [];
     for (const s of input) {
-        const lower = s.toLowerCase();
-        if (ALL_SECTIONS.includes(lower)) {
-            set.add(lower);
+        const key = s.trim().toLowerCase().replace(/-/g, '_');
+        if (ALL_SECTIONS.includes(key)) {
+            set.add(key);
+        }
+        else {
+            unknown.push(s);
         }
     }
-    return set;
+    if (unknown.length === 0)
+        return { include: set, note: '' };
+    const fellBack = set.size === 0;
+    if (fellBack)
+        for (const s of ALL_SECTIONS)
+            set.add(s);
+    const note = `(Ignored unknown include section${unknown.length === 1 ? '' : 's'}: ` +
+        `${unknown.map((u) => `"${u}"`).join(', ')}. Valid: ${ALL_SECTIONS.join(', ')}.` +
+        `${fellBack ? ' Showing all sections.' : ''})\n\n`;
+    return { include: set, note };
 }
 async function renderSymbolMode(file, name, line, include, maxTokens, deps) {
     const candidates = deps.index
@@ -124,6 +151,7 @@ async function renderSymbolBlock(target, file, include, maxTokens, deps) {
     if (target.doc && target.doc.length > 0)
         headerLines.push(target.doc);
     const header = headerLines.join('\n');
+    const { item: notesSection, degradedNotice } = await notesItem(deps, file, include, target);
     // `body` is the highest-priority section and is never dropped to fit budget.
     const items = [
         {
@@ -155,9 +183,112 @@ async function renderSymbolBlock(target, file, include, maxTokens, deps) {
             render: () => renderImports(file, deps.index),
             peekNonEmpty: () => deps.index.getImports(file).length > 0,
         },
+        notesSection,
         ...gitSectionItems(target.file, deps),
     ];
-    return renderBudgeted(header, items, include, maxTokens, 'body');
+    return (await renderBudgeted(header, items, include, maxTokens, 'body')) + degradedNotice;
+}
+// --- PULL: anchored knowledge-layer notes rendered in place ---
+// Cap so a note-heavy file can't displace the structural sections; the
+// overflow line names the recall query that lists the rest.
+const MAX_CONTEXT_NOTES = 3;
+// Builds the notes SectionItem for either mode, plus a `degradedNotice` the
+// caller appends OUTSIDE the token budget. The store load + selection happen up
+// front (sync store queries after the memoized load, so the budget loop can
+// peek emptiness for free) but are GATED on the include filter — a caller
+// looping get_context({include:['body']}) must not pay a store read per call.
+// Both modes share this so the load-before-select ordering and the peek
+// contract can't drift apart.
+async function notesItem(deps, file, include, target) {
+    let selected = [];
+    let degradedNotice = '';
+    if (include.has('notes')) {
+        await deps.notes.load();
+        selected = selectContextNotes(deps.notes, file, target);
+        const degraded = deps.notes.degradedReason;
+        // Rides EVERY response — appended by the caller AFTER renderBudgeted, so a
+        // body that eats the whole token budget (dropping the notes section) can't
+        // suppress the "prior notes were quarantined; recover manually" signal.
+        // Same guarantee recall makes.
+        if (degraded)
+            degradedNotice = `\n\n(note store degraded: ${degraded})`;
+    }
+    const item = {
+        name: 'notes',
+        includeKey: 'notes',
+        render: () => renderNotesSection(selected, file, deps),
+        peekNonEmpty: () => selected.length > 0,
+    };
+    return { item, degradedNotice };
+}
+// Symbol mode: a note surfaces when one of its anchors names THIS symbol —
+// plus FILE-level anchors (notes about the whole file). An anchor names the
+// symbol when EITHER:
+//   - its stored (qualified) name equals this symbol's qualified name
+//     ("Class.member" / top-level bare name) — a RESOLVED anchor; or
+//   - it is a NAME-ONLY anchor (no symbolId — remember's ambiguous /
+//     index-still-building paths, declared "anchored by name") whose bare name
+//     equals this symbol's simple name, i.e. "about any symbol so named".
+// The name arm is GATED on symbolId===undefined: a resolved anchor pinned to
+// ONE specific symbol (e.g. top-level `foo`, symbolId set) must match by
+// qualified name ONLY, never bleed onto a same-named sibling added later (a
+// method `C.foo`) — and, symmetrically, a member-qualified anchor never bleeds
+// onto a same-named top-level target. Anchors qualified to a DIFFERENT
+// container, or to another symbol, stay out. File mode (no `target`): every
+// note with an anchor in the file.
+function selectContextNotes(notes, file, target) {
+    const all = notes.byFile(file); // newest first
+    if (target === undefined)
+        return all;
+    const qualified = qualifiedSymbolName(target.fqn, file, target.name);
+    const anchorNamesSymbol = (a) => {
+        if (a.file !== file || a.symbol === undefined)
+            return false;
+        if (a.symbol === qualified)
+            return true; // resolved to THIS symbol
+        return a.symbolId === undefined && a.symbol === target.name; // name-only
+    };
+    const symbolNotes = all.filter((n) => n.anchors.some(anchorNamesSymbol));
+    const seen = new Set(symbolNotes.map((n) => n.id));
+    const fileLevel = all.filter((n) => !seen.has(n.id) &&
+        n.anchors.some((a) => a.file === file && a.symbol === undefined));
+    return [...symbolNotes, ...fileLevel];
+}
+async function renderNotesSection(selected, file, deps) {
+    // Degraded-store signalling is handled OUTSIDE this section (notesItem's
+    // degradedNotice, appended past the budget) — an empty selection here means
+    // "no notes to render", nothing more.
+    if (selected.length === 0)
+        return '';
+    const shown = selected.slice(0, MAX_CONTEXT_NOTES);
+    // Same staleness path — and the same render grammar (note-render.ts) — as
+    // recall, so a note reads identically everywhere. The caches dedupe the
+    // per-file hash/git probe across the shown notes' anchors; per-note failure
+    // isolation lives in computeNoteStatusSafe (shared with recall).
+    const stalenessDeps = {
+        index: deps.index,
+        config: deps.config,
+        git: deps.git,
+    };
+    const fileCache = newFileProbeCache();
+    const commitCache = newCommitCache();
+    const blocks = await Promise.all(shown.map(async (note) => renderNote(note, await computeNoteStatusSafe(note, stalenessDeps, fileCache, commitCache))));
+    const lines = ['### Notes (agent-curated)', ...blocks];
+    if (selected.length > shown.length) {
+        lines.push(notesOverflowLine(selected.length - shown.length, file));
+    }
+    return lines.join('\n\n');
+}
+// The cap hid `hidden` selected notes. Point the agent at recall to BROWSE the
+// rest rather than promise reproduction: recall paginates (default 10, max 50).
+// ALWAYS recall({file}) — NOT recall({file, symbol}): symbol mode's selection
+// mixes symbol-anchored AND file-level notes, but recall's `symbol` filter is
+// bySymbol (file-level anchors excluded), so it would return a SUBSET that can
+// miss the very notes we hid. byFile ({file} only) is the true SUPERSET of the
+// selection in both modes. JSON.stringify quotes+escapes the path so the
+// suggested call is copy-paste valid even for exotic filenames.
+function notesOverflowLine(hidden, file) {
+    return `(${hidden} more not shown — recall({ file: ${JSON.stringify(file)} }) to browse notes here.)`;
 }
 // The two git sections are identical in both modes and always trail the
 // list (first to drop under budget pressure).
@@ -296,6 +427,8 @@ async function renderFileMode(file, include, maxTokens, deps) {
     });
     const exported = topLevel.filter((s) => s.exported);
     const internal = topLevel.filter((s) => !s.exported);
+    // File mode surfaces EVERY note anchored in the file (whole-file view).
+    const { item: notesSection, degradedNotice } = await notesItem(deps, file, include);
     // `body` covers the outline (Exports + Internal); `callees` has no
     // file-mode analogue. Renderers are lazy so dropped sections don't pay
     // for caller scans.
@@ -324,9 +457,10 @@ async function renderFileMode(file, include, maxTokens, deps) {
             // when the budget is already gone.
             peekNonEmpty: () => true,
         },
+        notesSection,
         ...gitSectionItems(file, deps),
     ];
-    return renderBudgeted(header, items, include, maxTokens);
+    return (await renderBudgeted(header, items, include, maxTokens)) + degradedNotice;
 }
 // Uses `getReferencesByNameOrAlias + isCallerOf` (same data path as
 // find_references) so cross-file callers — the common case for exported
@@ -365,6 +499,3 @@ function collectExportCallers(exportedSyms, index) {
 function formatFileSymbolLine(s) {
     return `- ${s.name} (${s.kind}, line ${s.startLine}) — ${displaySignature(s)}`;
 }
-function estimate(text) {
-    return Math.ceil(text.length / 4);
-}

package/dist/tools/impact.js

@@ -1,6 +1,6 @@
 import { countDistinctCallers, } from '../indexer/code-index.js';
 import { errMsg } from '../logger.js';
-import { BEHAVIORAL_TAG, MEMBER_MATCH_TAG, MODULE_LEVEL, NAME_MATCH_TAG, STRUCTURAL_TAG, normalizeFilePath, pickByLine, plural, readinessBanner, renderAmbiguous, renderSuggestions, textResponse, topCoChangePartners, } from './common.js';
+import { BEHAVIORAL_TAG, confidencePreamble, MEMBER_MATCH_TAG, estimate, MODULE_LEVEL, NAME_MATCH_TAG, STRUCTURAL_TAG, normalizeFilePath, pickByLine, plural, readinessBanner, renderAmbiguous, renderSuggestions, textResponse, topCoChangePartners, } from './common.js';
 const DEFAULT_DEPTH = 3;
 // Past 5 hops the heuristic name-match noise compounds multiplicatively and
 // the tree is mostly candidates; cap is a precision guardrail, not just budget.
@@ -72,9 +72,6 @@ function tagFor(strength) {
         return MEMBER_MATCH_TAG;
     return NAME_MATCH_TAG;
 }
-function estimate(text) {
-    return Math.ceil(text.length / 4);
-}
 function flattenByDepth(root) {
     const byDepth = new Map();
     const walk = (node) => {
@@ -165,7 +162,7 @@ function renderImpact(tree, target, depth, maxTokens, index) {
     // numbers. impact keeps tree.truncated and depthCapped SEPARATE below: they
     // map to two distinct remediation hints (raise max_tokens/narrow vs raise
     // depth), unlike the scalar BlastRadius which collapses both into one `+`.
-    const blast = countDistinctCallers(tree.root);
+    const blast = countDistinctCallers(tree.root, /* withTiers */ true);
     const depthCapped = blast.depthCapped;
     const callerCount = blast.callers;
     // A trailing `+` flags that a breadth/size cap fired, so the true total may
@@ -173,6 +170,22 @@ function renderImpact(tree, target, depth, maxTokens, index) {
     blocks.push(`${callerCount}${tree.truncated ? '+' : ''} ${plural('caller', callerCount)} across ` +
         `${blast.depths} ${plural('depth', blast.depths)} ` +
         `(${blast.files} ${plural('file', blast.files)}).`);
+    // Confidence summary, derived from blast.tiers — the SAME distinct-caller
+    // dedup that produced the "N callers" headline above, so the two reconcile by
+    // construction (a DAG diamond / cycle is one caller, not N). Carries the
+    // headline's truncation flag so a capped walk shows "+ more" here too. Pushed
+    // into the never-dropped floor so it always shows.
+    // TRADEOFF: each distinct caller is bucketed by its STRONGEST edge, while the
+    // per-row tags below are per-PATH (tagFor on each occurrence). In the rare
+    // mixed-strength DAG diamond (one caller reached via a resolved AND a
+    // name-match edge) the summary counts it once as resolved while both rows
+    // still render — reconciling with the adjacent "N callers" headline is the
+    // primary invariant; per-occurrence counting would re-break that.
+    // blast.tiers is present because we passed withTiers=true above; `?? {}` keeps
+    // the type honest (CallerCounts.tiers is optional) and degrades to no preamble.
+    const preamble = confidencePreamble(blast.tiers ?? {}, tree.truncated);
+    if (preamble)
+        blocks.push(preamble);
     let used = estimate(blocks.join('\n\n'));
     let cutoff = null;
     for (const d of depths) {

package/dist/tools/note-render.js

@@ -0,0 +1,57 @@
+// Shared renderers for staleness-checked notes. Extracted from recall.ts so
+// the PULL surfaces (a notes section inside get_context / a knowledge line in
+// overview) render notes IDENTICALLY to recall — one grammar for verdict tags,
+// ages, and anchor lines. This lives in tools/ (not notes/) on purpose: the
+// renderers depend on tools/common's formatRelativeAge + BEHAVIORAL_TAG, and a
+// notes/-located module would re-create the notes→tools layering inversion.
+import { BEHAVIORAL_TAG, formatRelativeAge } from './common.js';
+// Module-private until a PULL surface actually consumes them — renderNote is
+// the one export with a consumer today; widen the surface when real callers
+// land, not speculatively.
+const VERDICT_TAG = {
+    fresh: '✓ fresh',
+    stale: '⚠ stale',
+    unverified: '? unverified',
+    missing: '✗ missing',
+};
+const VERDICT_MARK = {
+    fresh: '✓',
+    stale: '⚠',
+    unverified: '?',
+    missing: '✗',
+};
+export function renderNote(note, status) {
+    // Guard a hand-edited / non-ISO createdAt that parses to NaN (isValidNote only
+    // checks it's a string) so the header never reads "NaNd ago".
+    const parsed = Date.parse(note.createdAt);
+    const age = Number.isNaN(parsed)
+        ? 'unknown age'
+        : `${formatRelativeAge(Date.now() - parsed)} ago`;
+    const tag = VERDICT_TAG[status.overall];
+    const lines = [`### Note ${note.id}  ${tag} · ${age}`, note.text];
+    if (status.anchors.length > 0) {
+        lines.push('Anchors:');
+        for (const a of status.anchors)
+            lines.push(renderAnchor(a));
+    }
+    else {
+        lines.push('(no anchors — not staleness-tracked)');
+    }
+    if (note.head)
+        lines.push(`Noted at commit ${note.head}.`);
+    return lines.join('\n');
+}
+function renderAnchor(a) {
+    const where = a.anchor.symbol
+        ? `${a.anchor.file}:${a.anchor.symbol}`
+        : a.anchor.file;
+    let line = `- ${VERDICT_MARK[a.verdict]} ${where} — ${a.detail}`;
+    if (a.lastCommit) {
+        // The file's most recent COMMIT — not necessarily when it went stale (a
+        // working-tree edit is uncommitted), so phrase it as provenance, not cause.
+        line +=
+            `; last commit ${a.lastCommit.hash} ${a.lastCommit.date} ` +
+                `"${a.lastCommit.subject}" ${BEHAVIORAL_TAG}`;
+    }
+    return line;
+}

package/dist/tools/overview.js

@@ -4,7 +4,7 @@ import { ENTRY_POINT_FILENAME_RE, isClassMember, zeroSymbolsByKind, } from '../i
 import { compareShallowFirst } from '../indexer/scanner.js';
 import { errMsg, log } from '../logger.js';
 import { LANGUAGE_UNKNOWN, } from '../types.js';
-import { BEHAVIORAL_TAG, formatComplexityMetrics, INDEXING_BANNER, plural, textResponse, } from './common.js';
+import { BEHAVIORAL_TAG, formatComplexityMetrics, formatRelativeAge, INDEXING_BANNER, plural, textResponse, } from './common.js';
 const MAX_DIR_GROUPS = 7;
 const MAX_KINDS_PER_GROUP = 3;
 const MAX_ENTRY_POINTS = 15;
@@ -117,13 +117,65 @@ export async function runOverview(args, deps) {
         if (kindLine)
             lines.push(`- ${kindLine}`);
         lines.push(`- ${stats.totalFiles} ${plural('file', stats.totalFiles)} indexed, ${stats.totalSymbols} total ${plural('symbol', stats.totalSymbols)}`);
-        appendGitSections(lines, await collectGitData(deps));
+        // The note-store read and the git subprocess work are independent I/O —
+        // start them concurrently (load never throws; it quarantines internally).
+        const [gitData] = await Promise.all([
+            collectGitData(deps),
+            deps.notes.load(),
+        ]);
+        appendKnowledgeSection(lines, deps.notes);
+        appendGitSections(lines, gitData);
         return textResponse(lines.join('\n'));
     }
     catch (err) {
         return textResponse(`Error: ${errMsg(err)}`);
     }
 }
+// Counts-only PULL surface of the knowledge layer: overview is the always-
+// first call, so this deliberately does NO disk re-hashing (staleness lives in
+// recall and get_context's notes section). Silently omitted when the store is
+// empty AND healthy. A degraded store gets its one-line notice — and STILL
+// reports the live counts when notes exist (after a quarantine + new
+// remembers, hiding the counts would read as "no stored knowledge"). The
+// caller has already awaited notes.load().
+function appendKnowledgeSection(lines, notes) {
+    const all = notes.all();
+    const degraded = notes.degradedReason;
+    if (all.length === 0 && degraded === null)
+        return;
+    lines.push('');
+    lines.push('### Knowledge (agent-curated)');
+    if (degraded !== null) {
+        lines.push(`- note store degraded: ${degraded}`);
+    }
+    if (all.length === 0)
+        return;
+    // Only ANCHORED notes are staleness-tracked; count them separately from
+    // unanchored ones so a mixed store never claims "N notes … recall checks
+    // staleness" over notes recall reports as "(no anchors — not tracked)".
+    const anchoredFiles = new Set();
+    let anchoredNotes = 0;
+    for (const note of all) {
+        if (note.anchors.length === 0)
+            continue;
+        anchoredNotes++;
+        for (const anchor of note.anchors)
+            anchoredFiles.add(anchor.file);
+    }
+    const unanchored = all.length - anchoredNotes;
+    if (anchoredNotes > 0) {
+        const base = `- ${anchoredNotes} anchored ${plural('note', anchoredNotes)} across ` +
+            `${anchoredFiles.size} ${plural('file', anchoredFiles.size)} — ` +
+            '`recall` checks staleness';
+        lines.push(unanchored > 0
+            ? `${base}; ${unanchored} unanchored (not tracked)`
+            : base);
+    }
+    else {
+        lines.push(`- ${unanchored} unanchored ${plural('note', unanchored)} — ` +
+            'not staleness-tracked; anchor notes to files/symbols to track them');
+    }
+}
 // Defensive catch at the tool boundary: GitService promises not to
 // throw, but a git failure must never break overview output.
 async function collectGitData(deps) {
@@ -134,6 +186,8 @@ async function collectGitData(deps) {
     catch {
         branch = null;
     }
+    // Captured once: drives both the window label and the freshness banner.
+    const gitMeta = deps.index.getGitMeta();
     return {
         branch,
         hotspots: deps.index.getHotspots(MAX_HOTSPOTS),
@@ -143,7 +197,8 @@ async function collectGitData(deps) {
         // Label with the window that PRODUCED the data (gitMeta provenance),
         // not the live config: after a gitWindow change, persisted counts
         // keep their true label until the re-analysis lands.
-        windowDays: deps.index.getGitMeta()?.windowDays ?? deps.config.gitWindow,
+        windowDays: gitMeta?.windowDays ?? deps.config.gitWindow,
+        gitMeta,
     };
 }
 // Both sections vanish entirely outside git repos (and before the first
@@ -151,6 +206,24 @@ async function collectGitData(deps) {
 // placeholder. Hotspots come from the persisted index, so a warm start
 // shows them immediately, even while the indexing banner is up.
 function appendGitSections(lines, data) {
+    // Freshness banner: the analyzed HEAD and how long ago the git analysis ran,
+    // all from gitMeta (no extra git spawn). Tag-less — it's provenance, not a
+    // behavioral signal. Gated on a git analysis having run (gitMeta !== null),
+    // which is BROADER than the Hotspots/Risk gates (those need a qualifying
+    // file): the banner can therefore appear as the sole git output. Independent
+    // of the per-call branch probe so it still shows when branchSummary degrades.
+    // Omitted off-git, preserving the silent-omission contract.
+    if (data.gitMeta !== null) {
+        // "analyzed", not "index": this is the GIT-analysis timestamp (re-run on
+        // logs/HEAD changes), distinct from the structural index (re-run by the file
+        // watcher) — labeling it "index age" would overstate index staleness after a
+        // source-edit burst with no commit.
+        const analyzed = formatRelativeAge(Date.now() - data.gitMeta.analyzedAt);
+        // head is normally a full sha (rev-parse HEAD); guard a degenerate/empty
+        // value so the line never renders "HEAD  ·" with the identity dropped.
+        const head = data.gitMeta.head.slice(0, 7) || 'unknown';
+        lines.push('', `Freshness: HEAD ${head} · analyzed ${analyzed} ago · window ${data.windowDays}d`);
+    }
     if (data.branch !== null) {
         lines.push('', `### Branch ${BEHAVIORAL_TAG}`, formatBranchLine(data.branch));
     }

package/dist/tools/recall.js

@@ -0,0 +1,165 @@
+import { errMsg } from '../logger.js';
+import { computeNoteStatusSafe, newCommitCache, newFileProbeCache, } from '../notes/staleness.js';
+import { estimate, normalizeFilePath, readinessBanner, textResponse, } from './common.js';
+import { renderNote } from './note-render.js';
+const DEFAULT_LIMIT = 10;
+const MAX_LIMIT = 50;
+const DEFAULT_MAX_TOKENS = 3000;
+// The summary line + truncation tail are emitted around the note blocks but not
+// counted per-block; reserve for their worst-case length (a full multi-lever
+// tail + count breakdown runs ~200 chars) so the response respects the soft
+// max_tokens budget rather than overshooting.
+const SUMMARY_RESERVE = 64;
+export async function runRecall(args, deps) {
+    try {
+        const limit = Math.min(args.limit ?? DEFAULT_LIMIT, MAX_LIMIT);
+        const maxTokens = args.max_tokens ?? DEFAULT_MAX_TOKENS;
+        const banner = readinessBanner(deps.indexer.ready);
+        // Ensure the store is loaded (retries a prior transient read failure so a
+        // recovered store serves its real notes instead of a stale empty view).
+        await deps.notes.load();
+        // A store-level degraded notice — set when the prior notes were quarantined
+        // (moved aside), an interrupted-swap `.bak` may hold recoverable notes, or the
+        // store is transiently unreadable. Surfaced on EVERY recall (not just the
+        // zero-match one): after a quarantine the agent may add new notes, so a later
+        // NON-empty recall must still warn that the earlier notes were moved aside and
+        // need manual recovery. A newer-version store that SERVES its notes has no
+        // notice (its zero-match filter is a normal no-match), nor does a truly-empty one.
+        const degraded = deps.notes.degradedReason;
+        const degradedNote = degraded
+            ? `\n\n(The note store is degraded: ${degraded})`
+            : '';
+        const selection = selectNotes(args, deps);
+        if ('error' in selection)
+            return textResponse(selection.error);
+        const { notes, header } = selection;
+        if (notes.length === 0) {
+            return textResponse(banner + `${header}\n\nNo notes match.${degradedNote}`);
+        }
+        // Hash each distinct anchored file — and fetch its last commit — at most
+        // once across the whole result set.
+        const fileCache = newFileProbeCache();
+        const commitCache = newCommitCache();
+        const stalenessDeps = {
+            index: deps.index,
+            config: deps.config,
+            git: deps.git,
+        };
+        // Compute staleness for the CHECKED window (top `limit`) concurrently — the
+        // fileCache dedups same-file probes and each note is independent, so this
+        // avoids serializing per-note git/disk latency.
+        const considered = notes.slice(0, limit);
+        // Per-note failure isolation lives in computeNoteStatusSafe (shared with
+        // get_context's notes section) — one bad anchor degrades its note only.
+        const statuses = await Promise.all(considered.map(async (note) => ({
+            note,
+            status: await computeNoteStatusSafe(note, stalenessDeps, fileCache, commitCache),
+        })));
+        const staleCount = statuses.filter((s) => s.status.overall === 'stale').length;
+        const missingCount = statuses.filter((s) => s.status.overall === 'missing').length;
+        // Render as many as fit the token budget.
+        const rendered = [];
+        let used = estimate(header) + SUMMARY_RESERVE;
+        for (const { note, status } of statuses) {
+            const block = renderNote(note, status);
+            const cost = estimate(block);
+            if (rendered.length > 0 && used + cost > maxTokens)
+                break;
+            rendered.push(block);
+            used += cost;
+        }
+        // Two DISTINCT kinds of omission: `limitHid` notes were never CHECKED
+        // (staleness unknown — so "0 stale" must NOT read as "area is clean"), while
+        // `budgetHid` notes were checked+counted but not rendered under the budget.
+        const limitHid = notes.length - considered.length;
+        const budgetHid = considered.length - rendered.length;
+        const flags = [
+            staleCount > 0 ? `${staleCount} stale` : '',
+            missingCount > 0 ? `${missingCount} missing` : '',
+        ]
+            .filter(Boolean)
+            .join(', ');
+        const shownDesc = rendered.length < considered.length
+            ? `${rendered.length} shown of ${considered.length} checked`
+            : `${rendered.length} shown`;
+        const summary = `${header} — ${shownDesc}${flags ? `, ${flags}` : ''}`;
+        const moreParts = [
+            budgetHid > 0 ? `${budgetHid} checked but not shown` : '',
+            limitHid > 0 ? `${limitHid} not checked` : '',
+        ].filter(Boolean);
+        const levers = [
+            limitHid > 0 && limit < MAX_LIMIT ? 'raise `limit`' : '',
+            budgetHid > 0 ? 'raise `max_tokens`' : '',
+            moreParts.length > 0 ? 'narrow with `file`/`symbol`/`query`' : '',
+        ].filter(Boolean);
+        const tail = moreParts.length
+            ? `\n\n(${moreParts.join('; ')}${levers.length ? ` — ${levers.join(', ')}` : ''}.)`
+            : '';
+        return textResponse(banner + [summary, ...rendered].join('\n\n') + tail + degradedNote);
+    }
+    catch (err) {
+        return textResponse(`Error: ${errMsg(err)}`);
+    }
+}
+function tokenize(query) {
+    return query.toLowerCase().split(/\s+/).filter(Boolean);
+}
+// True if any query token appears in the note's text or its anchors. For an
+// anchor on `excludeFile` (the file+query path — every candidate is already
+// anchored there) the PATH is dropped from the haystack but the anchored SYMBOL
+// is kept: leaving the path in would make a token that's a substring of it
+// (e.g. "auth" in "src/auth.ts") match every note, but dropping the symbol too
+// would lose a legitimate `query="login"` match on a `file:login` anchor.
+function noteMatchesTokens(note, tokens, excludeFile) {
+    const anchorHay = note.anchors
+        .map((a) => (a.file === excludeFile ? (a.symbol ?? '') : `${a.file} ${a.symbol ?? ''}`))
+        .join(' ');
+    const hay = `${note.text} ${anchorHay}`.toLowerCase();
+    return tokens.some((t) => hay.includes(t));
+}
+function selectNotes(args, deps) {
+    const symbol = args.symbol?.trim();
+    const query = args.query?.trim();
+    const fileArg = args.file?.trim(); // trim so a padded path still matches anchors
+    if (fileArg) {
+        const rel = normalizeFilePath(fileArg, deps.config.projectRoot);
+        if (rel === null) {
+            return { error: `Error: file "${args.file}" is outside the project root.` };
+        }
+        let notes = symbol ? deps.notes.bySymbol(rel, symbol) : deps.notes.byFile(rel);
+        let header = symbol
+            ? `Notes anchored to \`${rel}:${symbol}\``
+            : `Notes anchored to \`${rel}\``;
+        // Honor `query` as an additional filter over the anchored subset (matching
+        // note TEXT + OTHER anchors, not the already-known filter path).
+        if (query) {
+            const tokens = tokenize(query);
+            notes = notes.filter((n) => noteMatchesTokens(n, tokens, rel));
+            header += ` matching "${query}"`;
+        }
+        return { notes, header };
+    }
+    if (query) {
+        // A `symbol` without a `file` can't be resolved as an anchor, but if a query
+        // is present, honor the query (folding the orphan symbol in as a search term)
+        // rather than erroring or discarding it. The header reflects the ACTUAL query.
+        const q = symbol ? `${symbol} ${query}` : query;
+        return {
+            notes: deps.notes.search(q).map((r) => r.note),
+            header: `Notes matching "${q}"`,
+        };
+    }
+    // Anchors are file-scoped, so a symbol with no file and no query can't be
+    // resolved — reject in-band rather than silently returning every note.
+    if (symbol) {
+        return {
+            error: 'Error: `symbol` requires `file` (anchors are file-scoped). ' +
+                'Provide both, or use `query` to search note text.',
+        };
+    }
+    // No filter → all notes, recency-ranked.
+    return {
+        notes: deps.notes.search('').map((r) => r.note),
+        header: 'All notes',
+    };
+}