@event4u/agent-config 9.8.0 → 9.9.0

package/src/scripts/code_graph/cli.ts

@@ -4,26 +4,73 @@
  *
  *   build    [--root P] [--out P] [--force]   (re)build the deterministic graph
  *   validate [--graph P]                       schema-gate a graph.json
+ *   detect   [--root P] [--format json]        three-state freshness verdict
+ *   refresh  [--root P] [--out P] [--budget-seconds N]
+ *                                               build --update (STALE) / no-op
+ *                                               (FRESH) / full build (ABSENT)
  *
- * Query subcommands (query/path/explain/affected/detect) are added by the
- * Phase-3 query tier. Deterministic, LLM-free, no network. Exit codes:
- * 0 ok · 1 not-found / validation-failed · 2 usage · 3 internal.
+ * `detect --format json` (Phase 2, road-to-reachable-code-memory) emits a
+ * single-line, stable-key-order JSON verdict on stdout — no timestamps, safe
+ * to diff or pipe to `jq`:
+ *
+ *   { "verdict": "ABSENT" | "STALE" | "FRESH",
+ *     "behind_commits": <n> | null,
+ *     "source": { "kind": "consumer" | "scip" | "native", "path": "…" } | null,
+ *     "sources": [ { "kind": …, "path": "…", "present": true, … }, … ] }
+ *
+ * `refresh` never blocks on a hung build: it spawns the actual `build` in a
+ * CHILD process against a temp `--out` path, under a hard wall-clock
+ * `--budget-seconds` (default 60, via SIGKILL). The real cache at `--out` is
+ * only ever touched by a same-directory atomic rename of that child's
+ * completed temp output — on budget-exceeded, build failure, or the child
+ * never producing output, the rename never happens and the OLD cache is left
+ * byte-for-byte untouched. The cache itself (default
+ * `agents/runtime/state/code-graph-v1.json`) is local-only and disposable —
+ * gitignored, rebuildable from source at any time; never a source of truth.
+ *
+ * Query subcommands (query/path/explain/affected) are added by the Phase-3
+ * query tier. Deterministic, LLM-free, no network. Exit codes:
+ * 0 ok · 1 not-found / validation-failed / refresh-budget-exceeded ·
+ * 2 usage · 3 internal.
+ *
+ *   suggest-verb "<question>"                  (Phase 9 D3) print the verb
+ *                                               (query/affected/path/explain)
+ *                                               a regex table thinks best
+ *                                               answers a free-text structure
+ *                                               question — a standalone hint,
+ *                                               never auto-run against a
+ *                                               graph.
  */
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
 import { hardenedSpawnEnv } from '../_lib/spawn_env.js';
-import { buildFromRepo } from './build.js';
-import { detectSources, pickSource } from './detect.js';
-import { affected, explain, loadGraph, type LoadedGraph, path as graphPath, query, type QueryResult } from './query.js';
+import { buildFromRepo, sidecarPath } from './build.js';
+import { computeVerdict, detectSources, pickSource } from './detect.js';
+import { suggestVerb } from './intent.js';
+import {
+    affected,
+    explain,
+    loadGraph,
+    type LoadedGraph,
+    mergeRecommendedReads,
+    path as graphPath,
+    query,
+    type QueryResult,
+} from './query.js';
 import { validateGraph } from './validate.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..', '..');
 export const DEFAULT_CACHE = path.join(REPO_ROOT, 'agents', 'runtime', 'state', 'code-graph-v1.json');
+/** Local `tsx` binary — `refresh` spawns `build` as a child of THIS file
+ * through it, so a budget-exceeded kill only ever terminates the child. */
+const TSX_BIN = path.join(REPO_ROOT, 'node_modules', '.bin', process.platform === 'win32' ? 'tsx.cmd' : 'tsx');
+const DEFAULT_BUDGET_SECONDS = 60;
 
 function flag(argv: string[], name: string): string | null {
     const i = argv.indexOf(name);
@@ -93,6 +140,10 @@ function render(r: QueryResult, staleNote: string): number {
     for (const l of r.lines) process.stdout.write(`  ${l}\n`);
     if (r.truncated) process.stdout.write('  … (budget reached — narrow the seed or raise --budget)\n');
     if (!r.lines.length) process.stdout.write('  (no matching relations)\n');
+    if (r.recommended_reads.length) {
+        process.stdout.write('recommended reads (dropped by the budget, or a low-confidence seed match):\n');
+        for (const rr of r.recommended_reads) process.stdout.write(`  ${rr.path}${rr.lines ? `:${rr.lines[0]}-${rr.lines[1]}` : ''}\n`);
+    }
     return 0;
 }
 
@@ -130,12 +181,16 @@ function cmdQuery(kind: 'query' | 'explain' | 'affected' | 'path', argv: string[
     if (kind === 'affected' && flag(argv, '--since')) {
         const root = flag(argv, '--root') ?? REPO_ROOT;
         const seeds = changedNodeSeeds(r.g, root, flag(argv, '--since') as string);
-        const merged: QueryResult = { source: r.g.source, seeds: [], lines: [], truncated: false };
+        const merged: QueryResult = { source: r.g.source, seeds: [], lines: [], truncated: false, recommended_reads: [] };
+        const perSeed: QueryResult[] = [];
         for (const s of seeds) {
             const one = affected(r.g, s, 2, budget);
             merged.seeds.push(...one.seeds);
             merged.lines.push(...one.lines);
+            merged.truncated = merged.truncated || one.truncated;
+            perSeed.push(one);
         }
+        merged.recommended_reads = mergeRecommendedReads(perSeed);
         return render(merged, r.note);
     }
     const a = positional[0];
@@ -162,6 +217,12 @@ function isFlagValue(argv: string[], token: string): boolean {
 
 function cmdDetect(argv: string[]): number {
     const root = flag(argv, '--root') ?? REPO_ROOT;
+    if (flag(argv, '--format') === 'json') {
+        // Machine-readable three-state verdict (Phase 2). Existing human-text
+        // output below is unchanged for existing consumers.
+        process.stdout.write(`${JSON.stringify(computeVerdict(root, DEFAULT_CACHE))}\n`);
+        return 0;
+    }
     const verdicts = detectSources(root, DEFAULT_CACHE);
     if (!verdicts.length) {
         process.stdout.write('no code-graph source detected\n');
@@ -176,16 +237,127 @@ function cmdDetect(argv: string[]): number {
     return 0;
 }
 
+function budgetSecondsOf(argv: string[]): number {
+    const raw = flag(argv, '--budget-seconds');
+    if (raw === null) return DEFAULT_BUDGET_SECONDS;
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : DEFAULT_BUDGET_SECONDS;
+}
+
+/** Best-effort removal of a temp build output + its sidecar. Never throws —
+ * cleanup failure must not mask the real result (budget-exceeded / error). */
+function cleanupTemp(tmpOut: string): void {
+    for (const p of [tmpOut, sidecarPath(tmpOut)]) {
+        try {
+            fs.unlinkSync(p);
+        } catch {
+            /* already absent, or never materialised — fine */
+        }
+    }
+}
+
+/**
+ * Run `build` (optionally `--update`) as a CHILD process against a temp
+ * `--out` path, under a hard wall-clock budget. Only on a clean, in-budget
+ * exit does the temp output get promoted into `out` — via a same-directory
+ * `renameSync`, atomic at the OS level, exactly the technique `write_atomic`
+ * itself uses. Any other outcome (timeout, non-zero exit, missing output)
+ * cleans up the temp files and leaves `out` untouched.
+ */
+function runBudgetedBuild(root: string, out: string, update: boolean, budgetSeconds: number): number {
+    if (!(budgetSeconds > 0)) {
+        // Node's own `timeout` option treats 0 as "no limit" — a genuinely
+        // zero-or-negative budget is an immediate, deterministic abort
+        // instead of silently becoming unlimited.
+        process.stderr.write(`code-graph: refresh budget exceeded (${budgetSeconds}s) — old cache kept\n`);
+        return 1;
+    }
+    const dir = path.dirname(out);
+    const tmpOut = path.join(dir, `.${path.basename(out)}.refresh-tmp-${process.pid}-${randomBytes(4).toString('hex')}.json`);
+    if (update) {
+        const realSidecar = sidecarPath(out);
+        if (fs.existsSync(realSidecar)) {
+            try {
+                fs.copyFileSync(realSidecar, sidecarPath(tmpOut));
+            } catch {
+                /* fall back to a full re-extraction inside the child */
+            }
+        }
+    }
+    const args = ['build', '--root', root, '--out', tmpOut, ...(update ? ['--update'] : [])];
+    const res = spawnSync(TSX_BIN, [_HERE, ...args], {
+        env: hardenedSpawnEnv(),
+        stdio: 'ignore',
+        timeout: Math.round(budgetSeconds * 1000),
+        killSignal: 'SIGKILL',
+    });
+    const timedOut = res.signal !== null || (res.error !== undefined && (res.error as NodeJS.ErrnoException).code === 'ETIMEDOUT');
+    if (timedOut) {
+        cleanupTemp(tmpOut);
+        process.stderr.write(`code-graph: refresh budget exceeded (${budgetSeconds}s) — old cache kept\n`);
+        return 1;
+    }
+    if (res.status !== 0) {
+        cleanupTemp(tmpOut);
+        const detail = res.error ? `: ${res.error.message}` : res.status !== null ? ` (exit ${res.status})` : '';
+        process.stderr.write(`code-graph: refresh build failed${detail} — old cache kept\n`);
+        return 1;
+    }
+    if (!fs.existsSync(tmpOut)) {
+        cleanupTemp(tmpOut);
+        process.stderr.write('code-graph: refresh produced no output — old cache kept\n');
+        return 3;
+    }
+    fs.renameSync(tmpOut, out); // same-dir → atomic; real cache only ever changes here
+    const tmpSidecar = sidecarPath(tmpOut);
+    if (fs.existsSync(tmpSidecar)) fs.renameSync(tmpSidecar, sidecarPath(out));
+    process.stdout.write(`✅  code-graph refreshed — cache: ${path.relative(REPO_ROOT, out)}\n`);
+    return 0;
+}
+
+function cmdRefresh(argv: string[]): number {
+    const root = flag(argv, '--root') ?? REPO_ROOT;
+    const out = flag(argv, '--out') ?? DEFAULT_CACHE;
+    const budgetSeconds = budgetSecondsOf(argv);
+    if (!fs.existsSync(root)) {
+        process.stderr.write(`code-graph: root not found: ${root}\n`);
+        return 1;
+    }
+    const v = computeVerdict(root, out);
+    if (v.verdict === 'FRESH') {
+        process.stdout.write('fresh — nothing to do\n');
+        return 0;
+    }
+    return runBudgetedBuild(root, out, v.verdict === 'STALE', budgetSeconds);
+}
+
+/**
+ * `suggest-verb "<question>"` (Phase 9 D3) — print the `code_graph` verb a
+ * pure regex table thinks best answers a free-text structure question. A
+ * standalone hint only: never resolves a graph, never runs a query itself.
+ */
+function cmdSuggestVerb(argv: string[]): number {
+    const question = argv.filter((a) => !a.startsWith('--')).join(' ').trim();
+    if (!question) {
+        process.stderr.write('usage: code_graph/cli.ts suggest-verb "<question>"\n');
+        return 2;
+    }
+    process.stdout.write(`${suggestVerb(question)}\n`);
+    return 0;
+}
+
 export async function main(argv: string[] = process.argv.slice(2)): Promise<number> {
     const sub = argv[0];
     try {
         if (sub === 'build') return await cmdBuild(argv.slice(1));
         if (sub === 'validate') return cmdValidate(argv.slice(1));
         if (sub === 'detect') return cmdDetect(argv.slice(1));
+        if (sub === 'refresh') return cmdRefresh(argv.slice(1));
         if (sub === 'query' || sub === 'explain' || sub === 'affected' || sub === 'path')
             return cmdQuery(sub, argv.slice(1));
+        if (sub === 'suggest-verb') return cmdSuggestVerb(argv.slice(1));
         process.stderr.write(
-            'usage: code_graph/cli.ts <build|validate|detect|query|explain|affected|path> [options]\n',
+            'usage: code_graph/cli.ts <build|validate|detect|refresh|query|explain|affected|path|suggest-verb> [options]\n',
         );
         return 2;
     } catch (e) {

package/src/scripts/code_graph/detect.ts

@@ -132,3 +132,55 @@ export function pickSource(verdicts: SourceVerdict[]): SourceVerdict | null {
     if (native) return native;
     return verdicts.find((v) => v.kind === 'consumer') ?? null;
 }
+
+/** A single detected source, JSON-shaped (only defined fields are emitted —
+ * key order fixed by construction so `JSON.stringify` output is stable). */
+export interface DetectedSourceJSON {
+    kind: SourceKind;
+    path: string;
+    present: boolean;
+    stale?: boolean;
+    commits_behind?: number;
+    note?: string;
+}
+
+/** The `code-graph detect --format json` verdict shape (Phase 2). Deterministic:
+ * fixed key order, no timestamps, paths relative to `root`. */
+export interface VerdictJSON {
+    verdict: 'ABSENT' | 'STALE' | 'FRESH';
+    /** commits behind, when known from the picked source; else null. */
+    behind_commits: number | null;
+    /** the source `refresh`/queries would use, or null when ABSENT. */
+    source: { kind: SourceKind; path: string } | null;
+    /** every detected source (for diagnostics), not just the picked one. */
+    sources: DetectedSourceJSON[];
+}
+
+/**
+ * Three-state freshness verdict for `root`, reusing `detectSources` +
+ * `pickSource` (no duplicated precedence logic). ABSENT = no usable source
+ * (a bare `scip` presence or nothing at all); STALE = the picked source is
+ * stale; FRESH = picked source is fresh, or freshness is unknown (mirrors the
+ * nudge hook's `picked.stale ? STALE : FRESH` reading — unknown is not
+ * treated as stale).
+ */
+export function computeVerdict(root: string, nativeCache: string): VerdictJSON {
+    const abs = path.resolve(root);
+    const verdicts = detectSources(root, nativeCache);
+    const picked = pickSource(verdicts);
+    const rel = (p: string): string => path.relative(abs, p).split(path.sep).join('/');
+    const verdict: VerdictJSON['verdict'] = picked === null ? 'ABSENT' : picked.stale ? 'STALE' : 'FRESH';
+    const sources: DetectedSourceJSON[] = verdicts.map((v) => {
+        const s: DetectedSourceJSON = { kind: v.kind, path: rel(v.path), present: v.present };
+        if (v.stale !== undefined) s.stale = v.stale;
+        if (v.commits_behind !== undefined) s.commits_behind = v.commits_behind;
+        if (v.note !== undefined) s.note = v.note;
+        return s;
+    });
+    return {
+        verdict,
+        behind_commits: picked?.commits_behind ?? null,
+        source: picked ? { kind: picked.kind, path: rel(picked.path) } : null,
+        sources,
+    };
+}

package/src/scripts/code_graph/intent.ts

@@ -0,0 +1,45 @@
+/**
+ * Intent-conditioned verb selection (Phase 9 D3, road-to-reachable-code-memory)
+ * — a PURE regex table, no model call. `suggestVerb` maps a natural-language
+ * structure question to the `code_graph` subcommand most likely to answer it:
+ *
+ *   affected — "who calls / uses / references this", "what would break",
+ *              "blast radius" — a reverse (who-depends-on-it) lookup.
+ *   path     — "how does X reach/connect to Y", "is A reachable from B",
+ *              "trace the route between A and B" — connectivity between
+ *              two named seeds.
+ *   explain  — "overview", "what's around X", "the neighbourhood of X",
+ *              "walk me through X" — a broader 2-hop neighbourhood, not a
+ *              single direct-relations answer.
+ *   query    — the default: a seed's own direct (1-hop) relations.
+ *
+ * Order matters — first pattern class to match wins: affected → path →
+ * explain → query. Ship gate (pre-registered in
+ * `tests/fixtures/code-graph-intent/queries.json`, written BEFORE this file):
+ * `suggestVerb` must beat the always-`query` baseline's correct-verb rate
+ * over that 30-query set, or this module stays unwired (evidence only, per
+ * the D3 evidence note in `agents/evidence/reports/`).
+ */
+
+export type Verb = 'query' | 'affected' | 'path' | 'explain';
+
+const AFFECTED_RE =
+    /\b(who\s+(calls?|uses?|else|references?)|where\s+(is|are|'s)?\s*.*\bused\b|impact(s|ed|ing)?|blast\s+radius|break(s|ing)?|would\s+break|caller(s)?|referenc(e|es|ed|ing)|touch(es|ed)?)\b/i;
+
+const PATH_RE =
+    /\b(reach(able|es|ing)?|connect(s|ed|ion|ing)?|\btrace\b|\broute\b|\bpath\b|shortest)\b/i;
+
+const EXPLAIN_RE =
+    /\b(overview|explain(s|ed|ing)?|\baround\b|surround(ing|s)?|\bcontext\b|big\s+picture|neighbo[u]?rhood|walk\s+me\s+through|summar(y|ize|ise))\b/i;
+
+/**
+ * Suggest the `code_graph` verb a free-text structure question most likely
+ * needs. Deterministic, side-effect-free, no network, no model call.
+ */
+export function suggestVerb(question: string): Verb {
+    const q = question.trim();
+    if (AFFECTED_RE.test(q)) return 'affected';
+    if (PATH_RE.test(q)) return 'path';
+    if (EXPLAIN_RE.test(q)) return 'explain';
+    return 'query';
+}

package/src/scripts/code_graph/query.ts

@@ -9,6 +9,7 @@ import * as fs from 'node:fs';
 
 import { LexicalIndex, tokenize } from '../_lib/lexical_index.js';
 import { sanitizeLabel } from './sanitize.js';
+import { emitSqliteTwin, loadSerializedFromTwin } from './sqlite_store.js';
 import type { CodeEdge, CodeGraph } from './types.js';
 import { validateGraph } from './validate.js';
 
@@ -24,10 +25,19 @@ export interface LoadedGraph {
 }
 
 export function loadGraph(graphPath: string, source = graphPath): LoadedGraph {
-    const parsed = JSON.parse(fs.readFileSync(graphPath, 'utf-8')) as unknown;
+    // Prefer the derived SQLite twin (ADR-129): checksum/stat-verified against
+    // the canonical JSON, byte-identical content, ~1/90 the load cost at
+    // consumer scale. Fallback = parse the JSON — and best-effort re-emit the
+    // twin from it (zero-touch rebuild-on-drift, Phase 7).
+    const fromTwin = loadSerializedFromTwin(graphPath);
+    const raw = fromTwin ?? fs.readFileSync(graphPath, 'utf-8');
+    const parsed = JSON.parse(raw) as unknown;
     const v = validateGraph(parsed);
     if (!v.ok) throw new Error(`invalid graph at ${graphPath}: ${v.errors.slice(0, 3).join('; ')}`);
     const graph = parsed as CodeGraph;
+    if (fromTwin === null) {
+        emitSqliteTwin(graph, raw, graphPath);
+    }
     const byId = new Map(graph.nodes.map((n) => [n.id, n]));
     const outM = new Map<string, CodeEdge[]>();
     const inM = new Map<string, CodeEdge[]>();
@@ -44,13 +54,25 @@ export function loadGraph(graphPath: string, source = graphPath): LoadedGraph {
     return { graph, source, byId, out: outM, in: inM, lex };
 }
 
+interface SeedResolution {
+    ids: string[];
+    /** true when NEITHER an exact-id nor an exact-label match was found and
+     * resolution fell back to BM25 — a best-guess, not a confirmed hit. */
+    weak: boolean;
+}
+
 /** Resolve a free-text seed to node ids: exact id → exact label → BM25. */
-export function resolveSeeds(g: LoadedGraph, seed: string, limit = 5): string[] {
-    if (g.byId.has(seed)) return [seed];
+function resolveSeedsTiered(g: LoadedGraph, seed: string, limit = 5): SeedResolution {
+    if (g.byId.has(seed)) return { ids: [seed], weak: false };
     const exactLabel = g.graph.nodes.filter((n) => n.label === seed).map((n) => n.id);
-    if (exactLabel.length) return exactLabel.slice(0, limit);
+    if (exactLabel.length) return { ids: exactLabel.slice(0, limit), weak: false };
     const ranked = g.lex.rank(tokenize(seed)).filter((r) => r.score > 0);
-    return ranked.slice(0, limit).map((r) => r.id);
+    return { ids: ranked.slice(0, limit).map((r) => r.id), weak: true };
+}
+
+/** Resolve a free-text seed to node ids: exact id → exact label → BM25. */
+export function resolveSeeds(g: LoadedGraph, seed: string, limit = 5): string[] {
+    return resolveSeedsTiered(g, seed, limit).ids;
 }
 
 function label(g: LoadedGraph, id: string): string {
@@ -61,42 +83,109 @@ function edgeLine(g: LoadedGraph, e: CodeEdge): string {
     return `${e.confidence} ${sanitizeLabel(e.source)} --${e.relation}--> ${sanitizeLabel(e.target)}${cand}`;
 }
 
+/**
+ * A file + (when known) a 1-based inclusive line range worth reading directly
+ * — surfaced whenever the engine dropped or under-trusted something instead
+ * of silently truncating it (Phase 9 D4: "a read plan instead of silent
+ * truncation").
+ */
+export interface RecommendedRead {
+    path: string;
+    lines: [number, number] | null;
+}
+
 export interface QueryResult {
     source: string;
     seeds: string[];
     lines: string[];
     truncated: boolean;
+    recommended_reads: RecommendedRead[];
+}
+
+function readKey(r: RecommendedRead): string {
+    return r.lines ? `${r.path}:${r.lines[0]}-${r.lines[1]}` : r.path;
 }
 
-function budgetedLines(source: string, seeds: string[], lines: string[], budget: number): QueryResult {
+/** A node's file + line range, or `null` for an unresolved `symbol:*`
+ * placeholder (nothing real to read) or a node with no location info. */
+function recommendedReadFor(g: LoadedGraph, id: string): RecommendedRead | null {
+    const n = g.byId.get(id);
+    if (!n) return null;
+    const loc = n.source_location;
+    return { path: n.source_file, lines: loc.length >= 3 ? [loc[0] as number, loc[2] as number] : null };
+}
+
+/** One relation line plus the node id (if any) a reader should go inspect
+ * directly when this line gets dropped by the budget. */
+interface LineEntry {
+    text: string;
+    focusId?: string;
+}
+
+/**
+ * Apply the token budget to `entries`, then translate BOTH failure classes
+ * this delta targets into a deterministic `recommended_reads` list: every
+ * entry the budget dropped, plus every read the caller already flagged as
+ * weak (an under-threshold/BM25-fallback seed match) — deduped by
+ * path+line-range, insertion-ordered for determinism.
+ */
+function budgetedLines(
+    g: LoadedGraph,
+    source: string,
+    seeds: string[],
+    entries: LineEntry[],
+    budget: number,
+    weakSeedReads: RecommendedRead[] = [],
+): QueryResult {
     const cap = budget * APPROX_CHARS_PER_TOKEN;
     const kept: string[] = [];
+    const dropped: LineEntry[] = [];
     let used = 0;
     let truncated = false;
-    for (const l of lines) {
-        if (used + l.length > cap) {
+    for (const entry of entries) {
+        if (!truncated && used + entry.text.length <= cap) {
+            kept.push(entry.text);
+            used += entry.text.length + 1;
+        } else {
             truncated = true;
-            break;
+            dropped.push(entry);
         }
-        kept.push(l);
-        used += l.length + 1;
     }
-    return { source, seeds, lines: kept, truncated };
+    const recommended = new Map<string, RecommendedRead>();
+    for (const r of weakSeedReads) recommended.set(readKey(r), r);
+    for (const entry of dropped) {
+        if (!entry.focusId) continue;
+        const r = recommendedReadFor(g, entry.focusId);
+        if (r) recommended.set(readKey(r), r);
+    }
+    return { source, seeds, lines: kept, truncated, recommended_reads: [...recommended.values()] };
+}
+
+function weakSeedReads(g: LoadedGraph, resolution: SeedResolution): RecommendedRead[] {
+    if (!resolution.weak) return [];
+    const out: RecommendedRead[] = [];
+    for (const id of resolution.ids) {
+        const r = recommendedReadFor(g, id);
+        if (r) out.push(r);
+    }
+    return out;
 }
 
 /** `query <seed>` — the seed's direct (1-hop) outgoing relations. */
 export function query(g: LoadedGraph, seed: string, budget = 1500): QueryResult {
-    const seeds = resolveSeeds(g, seed);
-    const lines: string[] = [];
-    for (const s of seeds) for (const e of g.out.get(s) ?? []) lines.push(edgeLine(g, e));
-    return budgetedLines(g.source, seeds.map((s) => label(g, s)), lines, budget);
+    const resolution = resolveSeedsTiered(g, seed);
+    const seeds = resolution.ids;
+    const entries: LineEntry[] = [];
+    for (const s of seeds) for (const e of g.out.get(s) ?? []) entries.push({ text: edgeLine(g, e), focusId: e.target });
+    return budgetedLines(g, g.source, seeds.map((s) => label(g, s)), entries, budget, weakSeedReads(g, resolution));
 }
 
 /** `explain <seed>` — 2-hop neighbourhood (out-edges of seeds + their targets). */
 export function explain(g: LoadedGraph, seed: string, budget = 1500): QueryResult {
-    const seeds = resolveSeeds(g, seed);
+    const resolution = resolveSeedsTiered(g, seed);
+    const seeds = resolution.ids;
     const seen = new Set<string>();
-    const lines: string[] = [];
+    const entries: LineEntry[] = [];
     const frontier = [...seeds];
     for (let hop = 0; hop < 2 && frontier.length; hop += 1) {
         const next: string[] = [];
@@ -104,26 +193,30 @@ export function explain(g: LoadedGraph, seed: string, budget = 1500): QueryResul
             if (seen.has(s)) continue;
             seen.add(s);
             for (const e of g.out.get(s) ?? []) {
-                lines.push(edgeLine(g, e));
+                entries.push({ text: edgeLine(g, e), focusId: e.target });
                 next.push(e.target);
             }
         }
         frontier.push(...next);
     }
-    return budgetedLines(g.source, seeds.map((s) => label(g, s)), lines, budget);
+    return budgetedLines(g, g.source, seeds.map((s) => label(g, s)), entries, budget, weakSeedReads(g, resolution));
 }
 
 /** `affected <target>` — reverse BFS: who calls / references the target. */
 export function affected(g: LoadedGraph, target: string, depth = 2, budget = 1500): QueryResult {
-    const seeds = resolveSeeds(g, target);
+    const resolution = resolveSeedsTiered(g, target);
+    const seeds = resolution.ids;
     const seen = new Set<string>(seeds);
-    const lines: string[] = [];
+    const entries: LineEntry[] = [];
     let frontier = [...seeds];
     for (let d = 0; d < depth && frontier.length; d += 1) {
         const next: string[] = [];
         for (const t of frontier) {
             for (const e of g.in.get(t) ?? []) {
-                lines.push(edgeLine(g, e));
+                // the newly-discovered node here is the CALLER (e.source) —
+                // e.target is already a known seed, so that side carries no
+                // new read-plan information.
+                entries.push({ text: edgeLine(g, e), focusId: e.source });
                 if (!seen.has(e.source)) {
                     seen.add(e.source);
                     next.push(e.source);
@@ -132,14 +225,16 @@ export function affected(g: LoadedGraph, target: string, depth = 2, budget = 150
         }
         frontier = next;
     }
-    return budgetedLines(g.source, seeds.map((s) => label(g, s)), lines, budget);
+    return budgetedLines(g, g.source, seeds.map((s) => label(g, s)), entries, budget, weakSeedReads(g, resolution));
 }
 
 /** `path <a> <b>` — shortest undirected path (direction preserved per edge). */
 export function path(g: LoadedGraph, a: string, b: string, budget = 1500): QueryResult {
-    const starts = resolveSeeds(g, a, 1);
-    const goals = new Set(resolveSeeds(g, b, 1));
-    if (!starts.length || !goals.size) return { source: g.source, seeds: [], lines: [], truncated: false };
+    const startRes = resolveSeedsTiered(g, a, 1);
+    const goalRes = resolveSeedsTiered(g, b, 1);
+    const starts = startRes.ids;
+    const goals = new Set(goalRes.ids);
+    if (!starts.length || !goals.size) return { source: g.source, seeds: [], lines: [], truncated: false, recommended_reads: [] };
     const start = starts[0] as string;
     const prev = new Map<string, CodeEdge>();
     const seen = new Set<string>([start]);
@@ -164,7 +259,16 @@ export function path(g: LoadedGraph, a: string, b: string, budget = 1500): Query
         }
         frontier = next;
     }
-    if (!hit) return { source: g.source, seeds: [label(g, start)], lines: ['(no path found)'], truncated: false };
+    const seedReads = [...weakSeedReads(g, startRes), ...weakSeedReads(g, goalRes)];
+    if (!hit) {
+        return {
+            source: g.source,
+            seeds: [label(g, start)],
+            lines: ['(no path found)'],
+            truncated: false,
+            recommended_reads: [...new Map(seedReads.map((r) => [readKey(r), r])).values()],
+        };
+    }
     const chain: CodeEdge[] = [];
     let cur = hit;
     while (prev.has(cur)) {
@@ -172,5 +276,15 @@ export function path(g: LoadedGraph, a: string, b: string, budget = 1500): Query
         chain.unshift(e);
         cur = e.source === cur ? e.target : e.source;
     }
-    return budgetedLines(g.source, [label(g, start), label(g, hit)], chain.map((e) => edgeLine(g, e)), budget);
+    const entries = chain.map((e) => ({ text: edgeLine(g, e), focusId: e.target }));
+    return budgetedLines(g, g.source, [label(g, start), label(g, hit)], entries, budget, seedReads);
+}
+
+/** Merge several `QueryResult`s (e.g. one per `--since` seed) into one,
+ * de-duplicating `recommended_reads` by path+line-range so a read plan never
+ * repeats the same file twice across merged seeds. */
+export function mergeRecommendedReads(results: readonly QueryResult[]): RecommendedRead[] {
+    const merged = new Map<string, RecommendedRead>();
+    for (const r of results) for (const rr of r.recommended_reads) merged.set(readKey(rr), rr);
+    return [...merged.values()];
 }