codedeep-mcp 0.1.0 → 0.2.0

package/dist/notes/staleness.js

@@ -0,0 +1,168 @@
+import { hashContent } from '../indexer/pipeline.js';
+import { errMsg } from '../logger.js';
+import { safeReadIndexedFile } from '../fs-util.js';
+import { qualifiedSymbolName } from './note-store.js';
+const SEVERITY = {
+    fresh: 0,
+    unverified: 1,
+    stale: 2,
+    missing: 3,
+};
+// Note-level verdict = the worst of its anchors. A note with NO anchors is
+// "unverified" (stored, but not staleness-tracked).
+export async function computeNoteStatus(note, deps, 
+// Optional caches so a whole recall hashes each distinct file, and fetches
+// each file's last commit, at most once across the entire result set.
+fileCache, commitCache) {
+    if (note.anchors.length === 0) {
+        return { overall: 'unverified', anchors: [] };
+    }
+    // Anchors are independent — check them concurrently (the caches dedup any
+    // shared file probe / git call).
+    const anchors = await Promise.all(note.anchors.map((a) => computeAnchorStatus(a, deps, fileCache, commitCache)));
+    let overall = 'fresh';
+    for (const a of anchors) {
+        if (SEVERITY[a.verdict] > SEVERITY[overall])
+            overall = a.verdict;
+    }
+    return { overall, anchors };
+}
+// computeNoteStatus that can never throw out of a tool call: one bad anchor
+// degrades ITS note to unverified (with the cause in the detail) instead of
+// sinking the whole response. Shared by recall and get_context's notes section
+// so the two surfaces keep identical degradation semantics.
+export async function computeNoteStatusSafe(note, deps, fileCache, commitCache) {
+    try {
+        return await computeNoteStatus(note, deps, fileCache, commitCache);
+    }
+    catch (err) {
+        return {
+            overall: 'unverified',
+            anchors: note.anchors.map((anchor) => ({
+                anchor,
+                verdict: 'unverified',
+                detail: `staleness check failed: ${errMsg(err)}`,
+            })),
+        };
+    }
+}
+export function newFileProbeCache() {
+    return new Map();
+}
+export function newCommitCache() {
+    return new Map();
+}
+async function probeFile(relPath, config) {
+    try {
+        const content = await safeReadIndexedFile(relPath, config);
+        return { state: 'ok', liveHash: hashContent(content) };
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === 'ENOENT')
+            return { state: 'missing' };
+        return { state: 'unreadable', reason: err?.message };
+    }
+}
+export async function computeAnchorStatus(anchor, deps, fileCache, commitCache) {
+    // 1. Read the file from DISK and hash it — index-independent, so a disabled
+    //    or lagging watcher can't produce a false "fresh".
+    let probePromise = fileCache?.get(anchor.file);
+    if (!probePromise) {
+        probePromise = probeFile(anchor.file, deps.config);
+        fileCache?.set(anchor.file, probePromise);
+    }
+    const probe = await probePromise;
+    if (probe.state === 'missing') {
+        return { anchor, verdict: 'missing', detail: 'file no longer exists' };
+    }
+    if (probe.state === 'unreadable') {
+        return {
+            anchor,
+            verdict: 'unverified',
+            detail: `file could not be read (${probe.reason ?? 'unknown'})`,
+        };
+    }
+    if (anchor.fileContentHash === undefined) {
+        return {
+            anchor,
+            verdict: 'unverified',
+            detail: 'no baseline captured at note time (file was unindexed)',
+        };
+    }
+    if (probe.liveHash === anchor.fileContentHash) {
+        // Byte-identical file ⇒ the anchored symbol is unchanged too.
+        return { anchor, verdict: 'fresh', detail: 'unchanged' };
+    }
+    // 2. File changed. Refine the detail (and attach a live commit) for stale.
+    const detail = describeChange(anchor, deps, probe.liveHash);
+    let commitPromise = commitCache?.get(anchor.file);
+    if (!commitPromise) {
+        commitPromise = deps.git.recentCommits(anchor.file, 1).then((c) => c[0]);
+        commitCache?.set(anchor.file, commitPromise);
+    }
+    const lastCommit = await commitPromise;
+    return lastCommit
+        ? { anchor, verdict: 'stale', detail, lastCommit }
+        : { anchor, verdict: 'stale', detail };
+}
+// For a symbol anchor on a changed file, say WHAT changed by consulting the
+// index AS-IS. recall is read-only, so it must NOT re-index (indexFile mutates
+// the shared index — and can DELETE symbols other tools rely on when a file is
+// now unparseable/excluded). When the watcher is on (default) the index is
+// current, so signature-change detection is precise; with the watcher off the
+// index may lag, so this DETAIL is best-effort — the note is still correctly
+// flagged stale by the authoritative disk-hash comparison above.
+function describeChange(anchor, deps, liveHash) {
+    if (anchor.symbolId === undefined || anchor.symbol === undefined) {
+        return 'file changed since this note';
+    }
+    // Trust the index's symbols ONLY when they reflect the CURRENT disk bytes. If
+    // the index lags disk (watch off / mid-debounce / cap-skipped) its stored
+    // symbolId still matches the note's, which would give a WRONG "signature
+    // intact" detail for a signature that actually changed — so fall back to the
+    // generic detail rather than mislead. (The note is already correctly stale.)
+    const indexed = deps.index.getFile(anchor.file);
+    if (indexed === undefined) {
+        // The file isn't in the index at all — excluded by config, unknown-language,
+        // or not re-scanned after a cache wipe. Re-indexing can't surface its symbols
+        // (that's exactly why it's absent), so DON'T advise it; say symbol-level
+        // detail is unavailable for this file.
+        return 'file changed since this note (not indexed — no symbol-level detail)';
+    }
+    if (indexed.contentHash !== liveHash) {
+        return 'file changed since this note (re-index for symbol-level detail)';
+    }
+    // anchor.symbol is the QUALIFIED name (e.g. "Class.member"), so reconstruct
+    // each candidate's qualified name the same way remember stored it — matching
+    // the simple Symbol.name here would never hit for a member anchor and would
+    // falsely report every member as "renamed or removed".
+    const candidates = deps.index
+        .getSymbolsInFile(anchor.file)
+        .filter((s) => qualifiedSymbolName(s.fqn, anchor.file, s.name) === anchor.symbol);
+    if (candidates.length === 0) {
+        return `\`${anchor.symbol}\` was renamed or removed`;
+    }
+    const match = pickSymbol(candidates, anchor);
+    if (match.id === anchor.symbolId) {
+        // symbolId is body-insensitive, so an intact id means the SIGNATURE is
+        // unchanged — the file edit was the body (or elsewhere in the file).
+        return `file edited; \`${anchor.symbol}\` signature intact, body may have changed`;
+    }
+    const was = anchor.signature ? ` (was \`${anchor.signature}\`)` : '';
+    return `\`${anchor.symbol}\` signature changed${was}`;
+}
+// Prefer a candidate whose id matches the snapshot (so an overloaded/duplicated
+// name still reports "intact" when the right one survives); otherwise prefer a
+// kind match; otherwise the first.
+function pickSymbol(candidates, anchor) {
+    const byId = candidates.find((s) => s.id === anchor.symbolId);
+    if (byId)
+        return byId;
+    if (anchor.symbolKind) {
+        const byKind = candidates.find((s) => s.kind === anchor.symbolKind);
+        if (byKind)
+            return byKind;
+    }
+    return candidates[0];
+}

package/dist/notes/types.js

@@ -0,0 +1,19 @@
+// Persisted shape for the agent-curated knowledge layer (the `remember` /
+// `recall` / `forget` tools). This store is DELIBERATELY separate from the
+// code index's `index.json`:
+//
+//   - index.json is a DISPOSABLE derived cache — CodeIndex.load() fs.unlink's
+//     it on any schema/projectRoot mismatch or corruption, because it can be
+//     rebuilt from source in seconds.
+//   - notes are PRIMARY user/agent-authored data — NOT rebuildable. They must
+//     survive every index invalidation, so they live in their own file with
+//     their own version, and on corruption they are QUARANTINED (renamed
+//     aside), never deleted. See note-store.ts.
+//
+// Consequently this version is INDEPENDENT of the index SCHEMA_VERSION: adding
+// notes did not (and must not) bump the index schema, and a future index-schema
+// bump leaves these notes untouched.
+// Bump ONLY on a backward-incompatible Note/Anchor shape change. Additive
+// OPTIONAL fields (the expected evolution — e.g. a future per-symbol body hash)
+// need NO bump: a missing field already reads as the "unknown" dimension.
+export const NOTES_STORE_VERSION = 1;

package/dist/server.js

@@ -1,12 +1,17 @@
 // SDK v1.29 takes `inputSchema` as a RAW Zod shape ({ k: z.string() }), not
 // `z.object({...})`. The v2 alpha uses the wrapped form — do not confuse them.
+import { readFileSync } from "node:fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
+import { errMsg, log } from "./logger.js";
 import { runFindReferences } from "./tools/find-references.js";
 import { runFindSymbol } from "./tools/find-symbol.js";
+import { runForget } from "./tools/forget.js";
 import { runGetContext } from "./tools/get-context.js";
 import { runImpact } from "./tools/impact.js";
 import { runOverview } from "./tools/overview.js";
+import { runRecall } from "./tools/recall.js";
+import { runRemember } from "./tools/remember.js";
 import { runSearchStructure } from "./tools/search-structure.js";
 const SHARED_ANNOTATIONS = {
     readOnlyHint: true,
@@ -14,20 +19,58 @@ const SHARED_ANNOTATIONS = {
     idempotentHint: true,
     openWorldHint: false,
 };
+// remember/forget write the .codedeep note store (never source). readOnlyHint
+// is false so MCP clients surface the write; destructiveHint false (append /
+// scoped single-note removal, no source touched). The store write is the only
+// mutation in the server.
+const WRITE_ANNOTATIONS = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+};
+// Single source of truth for the advertised server version: the package's own
+// version field. Resolves from both src/ (tests) and dist/ (shipped) — each is
+// one directory below the package root. A hardcoded copy here drifted silently
+// (deferred v0.1.0 release note); reading it makes `npm version` sufficient.
+// Guarded: a bundled/relocated dist (no package.json one level up — or a
+// FOREIGN one that legally omits `version`, e.g. a private monorepo root) must
+// fall back to a placeholder STRING, never crash at import time and never let
+// `undefined` reach McpServer (serverInfo.version is required by the spec — an
+// undefined field would be dropped from the initialize response and can fail
+// client-side schema validation). The fallback is warned, not silent: a
+// placeholder version in a bug report should be traceable to its cause.
+const PACKAGE_VERSION = (() => {
+    try {
+        const version = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+        if (typeof version === "string" && version.length > 0)
+            return version;
+        log.warn("server: ../package.json has no usable `version` field (foreign/rootless " +
+            "package.json?); advertising 0.0.0-unknown");
+    }
+    catch (err) {
+        log.warn(`server: could not read ../package.json for the server version ` +
+            `(${errMsg(err)}); advertising 0.0.0-unknown`);
+    }
+    return "0.0.0-unknown";
+})();
 export function createServer(deps) {
     const server = new McpServer({
         name: "codedeep-mcp",
-        version: "0.1.0",
+        version: PACKAGE_VERSION,
     });
     server.registerTool("overview", {
-        description: "Get a structural overview of the codebase: language breakdown, top-level directories, entry points, and symbol counts — plus branch summary, git hotspots, and risk hotspots (churn × call-graph coupling) when in a git repo.",
+        description: "Start here. 'What is this codebase?' — language breakdown, top-level structure, entry points, symbol counts, and remembered-knowledge counts; in a git repo, also branch/hotspots, risk ranking (churn × coupling × complexity), and index freshness. Orient with this before grepping; then drill in with find_symbol / get_context.",
         inputSchema: {
-            path: z.string().optional().describe("Project root (default: cwd)"),
+            path: z
+                .string()
+                .optional()
+                .describe("Sanity check only: must equal the server's configured project root if given (errors otherwise — one server indexes one root). Omit it; it does NOT scope the overview to a subdirectory."),
         },
         annotations: SHARED_ANNOTATIONS,
     }, async (args) => runOverview(args, deps));
     server.registerTool("find_symbol", {
-        description: "AST-aware symbol lookup. Returns definitions matching a name (exact, prefix, or fuzzy), each with fan-in (references), fan-out (callees), and complexity — cyclomatic and cognitive, available for all 14 supported languages. Optional kind/scope/limit filters.",
+        description: "'Where is X defined?' Use instead of grep when you want the definition of a named symbol (exact/prefix/fuzzy) with fan-in, fan-out, and cyclomatic+cognitive complexity — not every text occurrence. Then get_context for the body or find_references for callers. Optional kind/scope/limit filters.",
         inputSchema: {
             name: z.string().describe("Symbol name (exact, prefix, or fuzzy)"),
             kind: z
@@ -57,7 +100,7 @@ export function createServer(deps) {
         annotations: SHARED_ANNOTATIONS,
     }, async (args) => runFindSymbol(args, deps));
     server.registerTool("get_context", {
-        description: "Return everything needed to understand a symbol: full body, within-file callers/callees, coupling (fan-in/fan-out/cyclomatic+cognitive complexity/blast radius), and imports — plus co-change partners and recent commits when git is available.",
+        description: "'Tell me everything about this symbol.' Full body (verbatim), within-file callers/callees, coupling (fan-in/out, cyclomatic+cognitive complexity, blast radius), imports, and any remembered notes anchored here (staleness-tagged ✓/⚠) — plus co-change partners and recent commits when git is available. Reach for this after find_symbol instead of opening the file by hand.",
         inputSchema: {
             file: z.string().describe("File path (relative to project root)"),
             symbol: z
@@ -78,12 +121,12 @@ export function createServer(deps) {
             include: z
                 .array(z.string())
                 .optional()
-                .describe("Sections to include: body, callers, callees, coupling, imports, co_changes, git"),
+                .describe("Sections to include: body, callers, callees, coupling, imports, notes, co_changes, git"),
         },
         annotations: SHARED_ANNOTATIONS,
     }, async (args) => runGetContext(args, deps));
     server.registerTool("find_references", {
-        description: "Cross-file usage navigation. Returns approximate AST name-matched callers for a symbol, ranked by directory and import proximity — plus co-change partners from git history when available. LSP-precise tiers ship in Phase 2.",
+        description: "'Who uses X?' Cross-file callers ranked by confidence (directory + import proximity), not raw text matches like grep — each row tagged [name match] or the weaker [member call]. Rows are AST-derived and confidence-tiered, not compiler-verified — verify before asserting. For the transitive blast radius use impact.",
         inputSchema: {
             file: z.string().describe("File containing the symbol (relative to project root)"),
             symbol: z.string().describe("Symbol name"),
@@ -93,13 +136,7 @@ export function createServer(deps) {
                 .optional()
                 .describe("Disambiguate when multiple symbols share a name"),
             kind: z
-                .enum([
-                "callers",
-                "callees",
-                "implementations",
-                "type_references",
-                "all",
-            ])
+                .enum(["callers", "callees", "all"])
                 .optional()
                 .describe("Result kind (default: 'all')"),
             limit: z
@@ -112,7 +149,7 @@ export function createServer(deps) {
         annotations: SHARED_ANNOTATIONS,
     }, async (args) => runFindReferences(args, deps));
     server.registerTool("impact", {
-        description: "Trace the transitive blast radius of changing a symbol: upstream callers grouped by hop (depth 1, 2, …), with co-change partners from git history. Edges are AST name-matches, not compiler-verified; downstream callees and inheritance ship with LSP in Phase 2.",
+        description: "'What breaks if I change X?' Transitive upstream caller tree grouped by hop, with a distinct-caller blast count and git co-change partners — something grep can't compute. Each edge tagged by confidence. For direct callers only, use find_references. (Edges are AST name-matches, not compiler-verified — verify before asserting; downstream callees and inheritance are not traversed.)",
         inputSchema: {
             file: z
                 .string()
@@ -143,7 +180,7 @@ export function createServer(deps) {
         annotations: SHARED_ANNOTATIONS,
     }, async (args) => runImpact(args, deps));
     server.registerTool("search_structure", {
-        description: "Keyword and structural code search. Fuzzy-matches symbol names, signatures, and docstrings; with `pattern`, runs an ast-grep structural query instead (TypeScript/TSX/JavaScript only for now).",
+        description: "'Find code by keyword or shape.' Fuzzy search over symbol names, signatures, and docstrings (git-churn-boosted), or with `pattern` an ast-grep structural query (TS/TSX/JS only). Use over grep for symbol-aware or structural matches; use plain grep for arbitrary string/comment text. To locate a known symbol by name, find_symbol is more direct.",
         inputSchema: {
             query: z
                 .string()
@@ -166,5 +203,57 @@ export function createServer(deps) {
         },
         annotations: SHARED_ANNOTATIONS,
     }, async (args) => runSearchStructure(args, deps));
+    server.registerTool("remember", {
+        description: "Write a durable note about code that grep/AST can't infer — a cross-file router chain, an invariant, a footgun, an architecture decision. Anchor it to the file(s)/symbol(s) it's about; codedeep then tracks STALENESS — recall flags the note when its anchors change (unlike memories that rot silently), and get_context surfaces anchored notes inline. Writes only to the .codedeep note store, never to source.",
+        inputSchema: {
+            note: z
+                .string()
+                .describe("The knowledge to store (markdown ok). Be specific."),
+            anchors: z
+                .array(z.string())
+                .optional()
+                .describe("Files/symbols this note is about, e.g. 'src/auth.ts' or 'src/auth.ts:authenticate' (add ':<line>' to disambiguate). Strongly recommended — anchors are what make the note staleness-tracked."),
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async (args) => runRemember(args, deps));
+    server.registerTool("recall", {
+        description: "Retrieve previously-remembered notes, each tagged ✓ fresh / ⚠ stale / ? unverified by re-checking its anchors against the current source. Call before editing a file/symbol ('what do I already know here, and is it still true?'). Filter by `file`/`symbol` (what's anchored here) or `query` (keyword); omit all to list every note.",
+        inputSchema: {
+            query: z
+                .string()
+                .optional()
+                .describe("Keywords matched against note text and anchors"),
+            file: z
+                .string()
+                .optional()
+                .describe("Return notes anchored to this file (relative path)"),
+            symbol: z
+                .string()
+                .optional()
+                .describe("With `file`, narrow to notes anchored to this symbol"),
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Max notes (default: 10, max: 50)"),
+            max_tokens: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Soft response budget (default: 3000)"),
+        },
+        annotations: SHARED_ANNOTATIONS,
+    }, async (args) => runRecall(args, deps));
+    server.registerTool("forget", {
+        description: "Delete a note by its id (shown by recall) — for superseded or wrong notes. Writes only to the .codedeep note store.",
+        inputSchema: {
+            noteId: z.string().describe("The note id to delete (from recall)"),
+        },
+        // destructiveHint: a forget is an irreversible delete of stored data (not
+        // additive like remember), so clients may gate it on confirmation.
+        annotations: { ...WRITE_ANNOTATIONS, destructiveHint: true, idempotentHint: true },
+    }, async (args) => runForget(args, deps));
     return server;
 }

package/dist/tools/common.js

@@ -1,6 +1,9 @@
-import { promises as fs } from 'node:fs';
-import { join, relative, resolve, sep } from 'node:path';
+import { relative, resolve } from 'node:path';
 import { partnerOf } from '../git/analyzer.js';
+// Re-exported for the tools' convenience — the implementation lives in the
+// neutral fs-util module so lower layers (notes/staleness) can use it without
+// importing the tools layer.
+export { safeReadIndexedFile } from '../fs-util.js';
 export function textResponse(text) {
     return { content: [{ type: 'text', text }] };
 }
@@ -14,44 +17,6 @@ export function normalizeFilePath(input, projectRoot) {
         return null;
     return rel;
 }
-// projectRoot is fixed for the process lifetime, so its realpath is too —
-// caching it spares one syscall per safeReadIndexedFile call (pattern
-// scans call this once per candidate file).
-const realRootCache = new Map();
-async function realProjectRoot(projectRoot) {
-    let cached = realRootCache.get(projectRoot);
-    if (cached === undefined) {
-        cached = await fs.realpath(projectRoot);
-        realRootCache.set(projectRoot, cached);
-    }
-    return cached;
-}
-// Re-check scanner admission rules at read time so stale on-disk
-// state (symlink-swap, growth past cap, became-directory) can't
-// bypass the indexer's contract.
-export async function safeReadIndexedFile(relPath, config) {
-    const abs = join(config.projectRoot, relPath);
-    const stats = await fs.lstat(abs);
-    if (stats.isSymbolicLink()) {
-        throw new Error('refusing to follow symlink');
-    }
-    if (!stats.isFile()) {
-        throw new Error('not a regular file');
-    }
-    if (stats.size > config.maxFileSize) {
-        throw new Error(`exceeds maxFileSize (${stats.size} > ${config.maxFileSize})`);
-    }
-    // lstat only checks the final component. Resolve parent-directory
-    // symlinks so a swap higher up in the path can't escape projectRoot.
-    const [real, realRoot] = await Promise.all([
-        fs.realpath(abs),
-        realProjectRoot(config.projectRoot),
-    ]);
-    if (real !== realRoot && !real.startsWith(realRoot + sep)) {
-        throw new Error('path escapes project root');
-    }
-    return fs.readFile(abs, 'utf8');
-}
 // Among ranges that contain `line`, pick the smallest — targets the innermost
 // match (e.g. a method inside a same-named class). Returns null when no
 // candidate spans `line`; callers that want a fallback handle it themselves.
@@ -133,7 +98,7 @@ export const INDEXING_BANNER = '⏳ Indexing in progress. Results may be incompl
 // Caller-row label for refs at file scope (no enclosing source symbol).
 export const MODULE_LEVEL = '(module-level)';
 // Per-line tag stamped on every approximate-name-match caller row so
-// consumers can distinguish AST-only matches from precise (LSP) refs.
+// consumers never mistake an AST name-match for a compiler-verified ref.
 // Shared between `find_references` and `get_context`'s file-mode export
 // caller summary — both render the same data path.
 export const NAME_MATCH_TAG = '[name match, unverified]';
@@ -177,6 +142,46 @@ export function formatComplexity(sym) {
 // code structure. Pairs with the design-notes tier vocabulary
 // ([structural] / [approximate] / [behavioral]).
 export const BEHAVIORAL_TAG = '[behavioral]';
+// One-line trust distribution that leads a tiered response, e.g.
+// "Confidence: 3 resolved · 2 name-match (verify) · 1 weak", or '' when there
+// are no rows. Omits zero tiers so it never names a tier the response can't
+// show. The inline "(verify)" makes the line self-describing — there is no
+// separate static tag legend (one would disagree with this pruned summary, and
+// the per-row tags like "[name match, unverified]" already carry the meaning).
+// `truncated` appends a "+ more" marker so the line carries the same
+// incompleteness signal as the caller headline (which appends `+`). Used only
+// by `impact` — the one tool with a mixed-tier caller tree.
+export function confidencePreamble(counts, truncated = false) {
+    const parts = [];
+    if (counts.structural)
+        parts.push(`${counts.structural} resolved`);
+    if (counts.nameMatch)
+        parts.push(`${counts.nameMatch} name-match (verify)`);
+    if (counts.weakMember)
+        parts.push(`${counts.weakMember} weak`);
+    if (parts.length === 0)
+        return '';
+    const marker = truncated ? ' (+ more callers not shown)' : '';
+    return `Confidence: ${parts.join(' · ')}${marker}`;
+}
+// Compact relative age ("4m" / "2h" / "3d", or "<1m" sub-minute) for an
+// elapsed-ms duration. Used by the overview freshness banner to show how long
+// ago the git analysis ran. Tool handlers run at request time, so `Date.now()`
+// is available to the caller computing the elapsed value.
+export function formatRelativeAge(ms) {
+    // Clamp negative elapsed (clock skew / a cache written by a faster clock, or
+    // a cache dir copied between machines) to 0 so it reads "<1m" deterministically
+    // rather than from undefined negative arithmetic.
+    const mins = Math.floor(Math.max(0, ms) / 60_000);
+    if (mins < 1)
+        return '<1m';
+    if (mins < 60)
+        return `${mins}m`;
+    const hours = Math.floor(mins / 60);
+    if (hours < 24)
+        return `${hours}h`;
+    return `${Math.floor(hours / 24)}d`;
+}
 // The confidence direction is the most invertible bug in the git layer —
 // confidenceAB is the from-self direction only when the queried file is
 // fileA. Centralized (sharing analyzer's partnerOf for the orientation
@@ -202,6 +207,11 @@ export function topCoChangePartners(coChanges, selfPath, limit = 5) {
 export function readinessBanner(ready) {
     return ready ? '' : `${INDEXING_BANNER}\n\n`;
 }
+// Token-budget approximation (CLAUDE.md "Token Budget"): chars / 4. Shared so a
+// new budgeted tool reuses it rather than adding another inline copy.
+export function estimate(text) {
+    return Math.ceil(text.length / 4);
+}
 export function plural(word, count) {
     return count === 1 ? word : `${word}s`;
 }

package/dist/tools/find-references.js

@@ -13,7 +13,6 @@ const WEAK_MEMBER_TIER = 5;
 const WEAK_MEMBER_ROW_CAP = 8;
 const CALLERS_HEADER = `### Callers ${NAME_MATCH_HEADER_QUALIFIER}`;
 const CALLEES_HEADER = '### Callees (within-file — from AST resolution)';
-const PHASE_2_NOTE = '(none — ships with LSP in Phase 2)';
 export async function runFindReferences(args, deps) {
     try {
         const file = normalizeFilePath(args.file, deps.config.projectRoot);
@@ -51,18 +50,18 @@ export async function runFindReferences(args, deps) {
         const kind = args.kind ?? 'all';
         const sections = [];
         sections.push(`## References for \`${target.name}\` (${target.file}:${target.startLine})`);
+        // No confidence summary here: find_references is reference-granular (one
+        // row per call SITE, not per distinct caller) and never emits a [structural]
+        // row — the section header already announces the approximate tier and each
+        // row carries its own tag. The Confidence summary lives in `impact`, where
+        // the caller tree mixes all three tiers and reconciles with the
+        // distinct-caller headline.
         if (kind === 'callers' || kind === 'all') {
             sections.push(renderCallers(target, deps.index, limit));
         }
         if (kind === 'callees' || kind === 'all') {
             sections.push(renderCallees(target, deps.index, limit));
         }
-        if (kind === 'implementations' || kind === 'all') {
-            sections.push(renderPhase2('Implementations'));
-        }
-        if (kind === 'type_references' || kind === 'all') {
-            sections.push(renderPhase2('Type References'));
-        }
         // Behavioral coupling rides along with kind 'all' only: it is
         // file-granularity enrichment, not a reference kind, and it stays a
         // separate section rather than a rankRefs tier — a co-committing
@@ -143,7 +142,9 @@ function renderCallers(target, index, limit) {
     return sectionOrNone(CALLERS_HEADER, body);
 }
 function renderCallees(target, index, limit) {
-    // Within-file only — cross-file callee resolution waits for LSP (Phase 2).
+    // Within-file only by design — callees are bound at extract time from the
+    // one file's AST; cross-file callee resolution is not modeled (the header
+    // says so, so an empty list reads as a scope limit, not an all-clear).
     const callees = index.getCallees(target.id);
     const body = callees
         .slice(0, limit)
@@ -153,9 +154,6 @@ function renderCallees(target, index, limit) {
     }
     return sectionOrNone(CALLEES_HEADER, body);
 }
-function renderPhase2(label) {
-    return `### ${label}\n${PHASE_2_NOTE}`;
-}
 // Confidence-only rows — find_references is the breadth view; the
 // shared-commit detail lives in get_context's co-change section.
 function renderCoChangePartners(file, index) {

package/dist/tools/forget.js

@@ -0,0 +1,26 @@
+import { errMsg } from '../logger.js';
+import { textResponse } from './common.js';
+// A note delete is entirely index-independent, so — unlike remember/recall — it
+// does NOT prepend the readiness banner (which would misleadingly imply the
+// delete was deferred while the index is still building).
+export async function runForget(args, deps) {
+    try {
+        const id = (args.noteId ?? '').trim();
+        if (id.length === 0) {
+            return textResponse('Error: noteId must be non-empty.');
+        }
+        // load() first so a prior transient read failure is retried before we read
+        // (and act on) the write-block flag.
+        await deps.notes.load();
+        const blocked = deps.notes.writeBlockReason;
+        if (blocked)
+            return textResponse(`Error: ${blocked}`);
+        const removed = await deps.notes.remove(id);
+        return textResponse(removed
+            ? `✓ Forgot note ${id}.`
+            : `No note ${id} found. Use recall to list note ids.`);
+    }
+    catch (err) {
+        return textResponse(`Error: ${errMsg(err)}`);
+    }
+}