@quolu/lattice 0.70.0 → 0.71.1

package/sensor/dist/bin/lattice-sensor.js

@@ -61,6 +61,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 // launcher is (almost certainly) still alive. A launcher killed mid-startup
 // otherwise blinds the PPID watchdog forever (#1185) — see early-ppid.ts.
 require("../mcp/early-ppid");
+// The browser viewer is not part of a release yet (see viewer-gate). Refuse
+// `ui` / `web` — also as `help ui` or `ui --help` — before any startup work,
+// unless LATTICE_SENSOR_UI=1 opts in.
+const viewer_gate_1 = require("./viewer-gate");
+{
+    const viewerCommand = (0, viewer_gate_1.requestedViewerCommand)(process.argv.slice(2));
+    if (viewerCommand && !(0, viewer_gate_1.viewerEnabled)()) {
+        process.stderr.write(`error: 'lattice sensor ${viewerCommand}' is not in this release yet. The browser viewer is coming in an upcoming release.\n`);
+        process.exit(1);
+    }
+}
 // Persist V8 compile artifacts across runs (Node ≥22.8). Every invocation —
 // and every worker thread, which re-requires the whole extraction module
 // graph — skips recompiling unchanged sources. Worth hundreds of ms of
@@ -87,6 +98,11 @@ const command_supervision_1 = require("./command-supervision");
 const exact_traversal_1 = require("./exact-traversal");
 const extraction_version_1 = require("../extraction/extraction-version");
 const telemetry_1 = require("../telemetry");
+// Value import, but dependency-free by design so `--help` text can name the
+// default port without dragging node:http into every other subcommand; the
+// server itself is loaded lazily inside the `ui` action. See ui-server/constants.
+const constants_1 = require("../ui-server/constants");
+const symbol_lookup_1 = require("../graph/symbol-lookup");
 // Decided once, before `--color`/`--no-color` are stripped from argv below
 // (#1281). Piped/redirected stdout, NO_COLOR, or --no-color -> plain output.
 const COLORS_ENABLED = (0, color_1.ansiColorsEnabled)();
@@ -355,11 +371,31 @@ function main() {
     function warn(message) {
         console.log(chalk.yellow((0, glyphs_1.getGlyphs)().warn) + ' ' + message);
     }
+    /** "not found" (+ optional did-you-mean) when no exact symbol matches. */
+    function formatSymbolNotFound(symbol, fuzzyNames) {
+        const suggestions = [...new Set(fuzzyNames.filter((n) => n !== symbol))].slice(0, 3);
+        if (suggestions.length === 0)
+            return `Symbol "${symbol}" not found`;
+        return `Symbol "${symbol}" not found — did you mean: ${suggestions.join(', ')}?`;
+    }
+    /** Compact node shape retained by the CLI's existing JSON lists. */
+    function cliNode(node) {
+        return { name: node.name, kind: node.kind, filePath: node.filePath, startLine: node.startLine };
+    }
+    /** Attribute a group's edges to every overload of this definition. */
+    function cliDefinition(group) {
+        const head = group[0];
+        return {
+            definition: { ...cliNode(head), id: head.id, qualifiedName: head.qualifiedName, language: head.language },
+            roots: group.map((node) => node.id),
+        };
+    }
     /**
      * Print indexing results using clack log methods
      */
     function printIndexResult(clack, result, projectPath) {
         const hasErrors = result.filesErrored > 0;
+        const parseWarnings = result.errors.filter((e) => e.code === 'parse_error' && e.severity === 'warning');
         // Surface non-file-level failures (e.g. lock-acquisition failure
         // when another indexer is running) before the file-count branches.
         // Without this the CLI falls through to "No files found to index",
@@ -384,6 +420,10 @@ function main() {
                 clack.log.success(`Indexed ${formatNumber(result.filesIndexed)} files`);
             }
             clack.log.info(`${formatNumber(result.nodesCreated)} nodes, ${formatNumber(result.edgesCreated)} edges in ${formatDuration(result.durationMs)}`);
+            // Warning-only parse failures keep indexing successful, but must be visible.
+            for (const warning of parseWarnings) {
+                clack.log.warn(warning.message);
+            }
             // A PARTIAL index (files silently dropped mid-pipeline) must not pass
             // as a clean run — it's the difference between "indexed the repo" and
             // "indexed most of the repo, quietly". Only the completeness
@@ -392,10 +432,33 @@ function main() {
             for (const w of result.errors.filter((e) => e.code === 'index_partial')) {
                 clack.log.warn(w.message);
             }
+            // Files salvaged from comment-stripped source after repeated parser
+            // failures are indexed but possibly incomplete — say so here, or the run
+            // reads as fully clean and the index quietly disagrees with a later
+            // re-parse of the same bytes (#1565).
+            const salvaged = result.errors.filter((e) => e.code === 'salvaged_stripped');
+            if (salvaged.length > 0) {
+                const sample = salvaged.slice(0, 3).map((e) => e.filePath).filter(Boolean).join(', ');
+                const more = salvaged.length > 3 ? ', ...' : '';
+                clack.log.warn(`${formatNumber(salvaged.length)} file(s) indexed from comment-stripped source after repeated parse failures ${(0, glyphs_1.getGlyphs)().dash} symbols may be incomplete (${sample}${more})`);
+            }
         }
         else if (hasErrors) {
             clack.log.error(`Indexing failed ${(0, glyphs_1.getGlyphs)().dash} all ${formatNumber(result.filesErrored)} files had errors`);
         }
+        else if (result.filesSkippedUnsupported) {
+            // A project LatticeSensor has no grammar for used to be indistinguishable from
+            // an empty one: same message, same `complete` state, same exit 0. Say which
+            // files were there and that the graph is empty on purpose, so nobody — and
+            // no agent trusting the graph — reads silence as "this code doesn't exist"
+            // (#1502).
+            const top = (result.topUnsupportedExtensions ?? [])
+                .map(e => `${e.ext} (${formatNumber(e.count)})`)
+                .join(', ');
+            clack.log.warn(`No supported source files found ${(0, glyphs_1.getGlyphs)().dash} ${formatNumber(result.filesSkippedUnsupported)} file(s) present, none in a language LatticeSensor indexes`
+                + (top ? `: ${top}` : ''));
+            clack.log.info('LatticeSensor is inactive for this workspace — searches will return nothing. Use your own file tools here.');
+        }
         else {
             clack.log.warn('No files found to index');
         }
@@ -428,9 +491,17 @@ function main() {
             }
         }
         else if (projectPath) {
-            const logPath = path.join((0, directory_1.getLatticeSensorDir)(projectPath), 'errors.log');
-            if (fs.existsSync(logPath)) {
-                fs.unlinkSync(logPath);
+            // No hard errors. Salvaged-file warnings still belong in the log — it
+            // carries the per-file detail behind the one-line summary above.
+            if (result.errors.some((e) => e.code === 'salvaged_stripped')) {
+                writeErrorLog(projectPath, result.errors);
+                clack.log.info('See .lattice/sensor/errors.log for details');
+            }
+            else {
+                const logPath = path.join((0, directory_1.getLatticeSensorDir)(projectPath), 'errors.log');
+                if (fs.existsSync(logPath)) {
+                    fs.unlinkSync(logPath);
+                }
             }
         }
     }
@@ -550,16 +621,14 @@ function main() {
     // Commands
     // =============================================================================
     /**
-     * lattice sensor init [path]
+     * The `init` flow — shared by `lattice sensor init` and `lattice sensor install --init`
+     * (#1578): refuse an unsafe root, create `.lattice/sensor/`, build the initial
+     * index under supervision, then the post-index offers. `yes` makes every
+     * offer non-interactive (defaults only), so a container / CI bootstrap never
+     * blocks on a prompt. An unsafe root sets `process.exitCode = 1` and returns
+     * (no `--force` is implied by any caller); an index failure exits 1.
      */
-    program
-        .command('init [path]')
-        .description('Initialize LatticeSensor in a project directory and build the initial index')
-        .option('-i, --index', 'Deprecated: indexing now runs by default; flag accepted for backward compatibility')
-        .option('-f, --force', 'Initialize even if the path looks like your home directory or a filesystem root')
-        .option('-v, --verbose', 'Show detailed worker lifecycle and memory info')
-        .action(async (pathArg, options) => {
-        const projectPath = path.resolve(pathArg || process.cwd());
+    async function runInit(projectPath, options) {
         const clack = await importESM('@clack/prompts');
         clack.intro('Initializing LatticeSensor');
         try {
@@ -580,9 +649,27 @@ function main() {
                 clack.outro('');
                 return;
             }
+            if ((0, directory_1.hasForeignDbFile)(projectPath)) {
+                const dbFile = path.join((0, directory_1.getLatticeSensorDir)(projectPath), 'sensor.db');
+                clack.log.error(`${dbFile} is not a SQLite database, so it cannot be rebuilt in place.`);
+                clack.log.info('Move or delete that file, then run "lattice sensor init" again.');
+                clack.outro('');
+                process.exitCode = 1;
+                return;
+            }
+            if ((0, directory_1.hasSchemalessDb)(projectPath)) {
+                clack.log.warn(`Found a sensor.db without the lattice sensor schema in ${(0, directory_1.getLatticeSensorDir)(projectPath)} (left by an interrupted init?) — rebuilding it.`);
+            }
             const { default: LatticeSensor, getDatabasePath } = await loadLatticeSensor();
             const cg = await LatticeSensor.init(projectPath, { index: false });
             clack.log.success(`Initialized in ${projectPath}`);
+            // A fresh index on a Windows drive under WSL gets its own directory (#995).
+            // It isn't the documented name, so say where it went and why.
+            const dataDir = path.basename((0, directory_1.getLatticeSensorDir)(projectPath));
+            if (dataDir !== (0, directory_1.latticeSensorRelativeDir)()) {
+                clack.log.info(`The index is in ${dataDir}/: this project is on a Windows drive, so WSL keeps its own index ` +
+                    `rather than share ${directory_1.DEFAULT_LATTICE_SENSOR_DIR}/ with LatticeSensor on Windows. Set LATTICE_SENSOR_DIR to choose the name yourself.`);
+            }
             // Indexing runs by default now. The legacy -i/--index flag is still
             // accepted (so existing muscle memory and scripts don't break) but is a
             // no-op — initializing always builds the initial index.
@@ -614,8 +701,10 @@ function main() {
             // An empty graph at a git super-repo usually means `.gitignore` excludes
             // the child repos that hold the code — surface them and offer to opt in
             // rather than leaving the user with a silent 0-node "Done". (#1156)
+            // Under --yes the offer prints its one-line opt-in snippet instead of
+            // prompting (same as a non-TTY run).
             if (result.nodesCreated === 0) {
-                await offerIndexIgnoredRepos(clack, projectPath, runIndex, { interactive: true });
+                await offerIndexIgnoredRepos(clack, projectPath, runIndex, { interactive: !options.yes });
             }
             clack.outro('Done');
             cg.destroy();
@@ -624,6 +713,19 @@ function main() {
             clack.log.error(`Failed: ${err instanceof Error ? err.message : String(err)}`);
             process.exit(1);
         }
+    }
+    /**
+     * lattice sensor init [path]
+     */
+    program
+        .command('init [path]')
+        .description('Initialize LatticeSensor in a project directory and build the initial index')
+        .option('-i, --index', 'Deprecated: indexing now runs by default; flag accepted for backward compatibility')
+        .option('-f, --force', 'Initialize even if the path looks like your home directory or a filesystem root')
+        .option('-v, --verbose', 'Show detailed worker lifecycle and memory info')
+        .option('-y, --yes', 'Non-interactive: skip every prompt and take the defaults (for scripts / CI / container bootstraps)')
+        .action(async (pathArg, options) => {
+        await runInit(path.resolve(pathArg || process.cwd()), options);
     });
     /**
      * lattice sensor uninit [path]
@@ -688,7 +790,13 @@ function main() {
         .option('-q, --quiet', 'Suppress progress output')
         .option('-v, --verbose', 'Show detailed worker lifecycle and memory info')
         .action(async (pathArg, options) => {
-        const projectPath = resolveProjectPath(pathArg);
+        // An EXPLICIT path names the project to rebuild — it is never a hint to go
+        // looking for one. resolveProjectPath walks up to the nearest initialized
+        // ancestor, which is right for `lattice sensor query` run from a subdirectory,
+        // but for a full re-index it silently rebuilt the parent's graph under a
+        // normal "Done" when <path> had no index of its own (#1524). Only a bare
+        // `lattice sensor index` (cwd) may resolve upward.
+        const projectPath = pathArg ? path.resolve(pathArg) : resolveProjectPath();
         try {
             // Don't (re)index your home directory / a filesystem root (#845). --force
             // doubles as the override.
@@ -699,66 +807,97 @@ function main() {
             }
             if (!(0, directory_1.isInitialized)(projectPath)) {
                 error(`LatticeSensor not initialized in ${projectPath}`);
-                info('Run "lattice sensor init" first');
+                const ancestor = pathArg ? resolveProjectPath(pathArg) : projectPath;
+                if (ancestor !== projectPath) {
+                    info(`The nearest initialized project is ${ancestor} — pass that path to rebuild it, or run "lattice sensor init" in ${projectPath} to index it on its own.`);
+                }
+                else {
+                    info('Run "lattice sensor init" first');
+                }
                 process.exit(1);
             }
-            const { default: LatticeSensor, getDatabasePath } = await loadLatticeSensor();
-            // `index` is a FULL re-index — identical to a fresh `init`. RECREATE the
-            // database from scratch (discard .lattice/sensor/sensor.db + its WAL) rather
-            // than opening the old graph and DELETE-ing every row. The clear-then-index
-            // approach reported "0 nodes" without the clear (#874); the recreate keeps
-            // that fixed AND avoids the failure mode where, on a large or pre-fix
-            // poisoned index, the per-row FTS delete churn wedged the main thread long
-            // enough to trip the liveness watchdog before scanning even began (#1067).
-            // recreate() hands back a fresh, empty instance — no clear() needed. For
-            // fast incremental updates use `sync`.
-            const cg = await LatticeSensor.recreate(projectPath);
-            // Supervise the indexer: self-terminate if orphaned (parent shim killed)
-            // or if the main thread wedges — neither was guarded on this path (#999).
-            // The DB + WAL paths let the liveness watchdog tell a slow store on
-            // degraded storage from a true wedge (#1231).
-            const dbPath = getDatabasePath(projectPath);
-            const supervision = (0, command_supervision_1.installCommandSupervision)('index', { progressPaths: [dbPath, `${dbPath}-wal`] });
+            const { tryAcquireWriterLock, releaseWriterLock, writerLockHeldMessage } = await Promise.resolve().then(() => __importStar(require('../mcp/writer-lock')));
+            const rebuild = tryAcquireWriterLock(projectPath, 'rebuild', 'rebuild.pid');
+            if (rebuild.kind === 'taken')
+                throw new Error('Another index rebuild is already in progress.');
             try {
-                if (options.quiet) {
-                    // Quiet mode: no UI, just run against the freshly-recreated graph.
-                    const result = await cg.indexAll();
-                    if (!result.success)
-                        process.exit(1);
-                    cg.destroy();
-                    return;
+                // A live MCP daemon keeps SQLite handles open. Verify it by its socket
+                // before stopping it so a stale pidfile can never signal another process.
+                const { stopDaemonAt } = await Promise.resolve().then(() => __importStar(require('../mcp/daemon-registry')));
+                const daemonStop = await stopDaemonAt(fs.realpathSync(projectPath), { preserveUnverified: true });
+                if (daemonStop.outcome === 'unverified' || daemonStop.outcome === 'still-running') {
+                    throw new Error('Could not verify that the active LatticeSensor daemon has stopped. Run `lattice sensor daemon stop` to stop it, then retry `lattice sensor index`.');
                 }
-                const clack = await importESM('@clack/prompts');
-                clack.intro('Indexing project');
-                // A closure so a re-index (after opting gitignored child repos in, #1156)
-                // renders identically. Supervision already wraps the whole command.
-                const renderIndex = async () => {
-                    if (options.verbose) {
-                        return await cg.indexAll({ onProgress: createVerboseProgress(), verbose: true });
+                // Keep the writer slot through recreation AND indexing. A reconnecting
+                // proxy/daemon must not open the replacement database halfway through.
+                const writer = tryAcquireWriterLock(projectPath, 'rebuild');
+                if (writer.kind === 'taken')
+                    throw new Error(writerLockHeldMessage(writer.existing, writer.pidPath));
+                try {
+                    const { default: LatticeSensor, getDatabasePath } = await loadLatticeSensor();
+                    // `index` is a FULL re-index — identical to a fresh `init`. RECREATE the
+                    // database from scratch (discard .lattice/sensor/sensor.db + its WAL) rather
+                    // than opening the old graph and DELETE-ing every row. The clear-then-index
+                    // approach reported "0 nodes" without the clear (#874); the recreate keeps
+                    // that fixed AND avoids the failure mode where, on a large or pre-fix
+                    // poisoned index, the per-row FTS delete churn wedged the main thread long
+                    // enough to trip the liveness watchdog before scanning even began (#1067).
+                    // recreate() hands back a fresh, empty instance — no clear() needed. For
+                    // fast incremental updates use `sync`.
+                    const cg = await LatticeSensor.recreate(projectPath);
+                    // Supervise the indexer: self-terminate if orphaned (parent shim killed)
+                    // or if the main thread wedges — neither was guarded on this path (#999).
+                    // The DB + WAL paths let the liveness watchdog tell a slow store on
+                    // degraded storage from a true wedge (#1231).
+                    const dbPath = getDatabasePath(projectPath);
+                    const supervision = (0, command_supervision_1.installCommandSupervision)('index', { progressPaths: [dbPath, `${dbPath}-wal`] });
+                    try {
+                        if (options.quiet) {
+                            // Quiet mode: no UI, just run against the freshly-recreated graph.
+                            const result = await cg.indexAll();
+                            if (!result.success)
+                                process.exit(1);
+                            return;
+                        }
+                        const clack = await importESM('@clack/prompts');
+                        clack.intro('Indexing project');
+                        // A closure so a re-index (after opting gitignored child repos in, #1156)
+                        // renders identically. Supervision already wraps the whole command.
+                        const renderIndex = async () => {
+                            if (options.verbose) {
+                                return await cg.indexAll({ onProgress: createVerboseProgress(), verbose: true });
+                            }
+                            process.stdout.write(`${colors.dim}${(0, glyphs_1.getGlyphs)().rail}${colors.reset}\n`);
+                            const progress = (0, shimmer_progress_1.createShimmerProgress)();
+                            const r = await cg.indexAll({ onProgress: progress.onProgress });
+                            await progress.stop();
+                            return r;
+                        };
+                        const result = await renderIndex();
+                        printIndexResult(clack, result, projectPath);
+                        await recordIndexTelemetry(cg, result);
+                        // Empty graph at a git super-repo → likely `.gitignore`d child repos;
+                        // name them and offer to opt in instead of a silent 0-node result (#1156).
+                        let finalResult = result;
+                        if (result.nodesCreated === 0) {
+                            finalResult = (await offerIndexIgnoredRepos(clack, projectPath, renderIndex, { interactive: true })) ?? result;
+                        }
+                        if (!finalResult.success) {
+                            process.exit(1);
+                        }
+                        clack.outro('Done');
+                    }
+                    finally {
+                        supervision.stop();
+                        cg.destroy();
                     }
-                    process.stdout.write(`${colors.dim}${(0, glyphs_1.getGlyphs)().rail}${colors.reset}\n`);
-                    const progress = (0, shimmer_progress_1.createShimmerProgress)();
-                    const r = await cg.indexAll({ onProgress: progress.onProgress });
-                    await progress.stop();
-                    return r;
-                };
-                const result = await renderIndex();
-                printIndexResult(clack, result, projectPath);
-                await recordIndexTelemetry(cg, result);
-                // Empty graph at a git super-repo → likely `.gitignore`d child repos;
-                // name them and offer to opt in instead of a silent 0-node result (#1156).
-                let finalResult = result;
-                if (result.nodesCreated === 0) {
-                    finalResult = (await offerIndexIgnoredRepos(clack, projectPath, renderIndex, { interactive: true })) ?? result;
                 }
-                if (!finalResult.success) {
-                    process.exit(1);
+                finally {
+                    releaseWriterLock(projectPath);
                 }
-                clack.outro('Done');
-                cg.destroy();
             }
             finally {
-                supervision.stop();
+                releaseWriterLock(projectPath, 'rebuild.pid');
             }
         }
         catch (err) {
@@ -784,36 +923,43 @@ function main() {
             }
             const { default: LatticeSensor } = await loadLatticeSensor();
             const cg = await LatticeSensor.open(projectPath);
-            if (options.quiet) {
-                await cg.sync();
-                cg.destroy();
-                return;
-            }
-            const clack = await importESM('@clack/prompts');
-            clack.intro('Syncing LatticeSensor');
-            process.stdout.write(`${colors.dim}${(0, glyphs_1.getGlyphs)().rail}${colors.reset}\n`);
-            const progress = (0, shimmer_progress_1.createShimmerProgress)();
-            const result = await cg.sync({
-                onProgress: progress.onProgress,
-            });
-            await progress.stop();
-            const totalChanges = result.filesAdded + result.filesModified + result.filesRemoved;
-            if (totalChanges === 0) {
-                clack.log.info('Already up to date');
+            try {
+                if (options.quiet) {
+                    await cg.sync();
+                    return;
+                }
+                const clack = await importESM('@clack/prompts');
+                clack.intro('Syncing LatticeSensor');
+                process.stdout.write(`${colors.dim}${(0, glyphs_1.getGlyphs)().rail}${colors.reset}\n`);
+                const progress = (0, shimmer_progress_1.createShimmerProgress)();
+                const result = await cg.sync({
+                    onProgress: progress.onProgress,
+                }).finally(() => progress.stop());
+                const totalChanges = result.filesAdded + result.filesModified + result.filesRemoved;
+                if (totalChanges === 0 && !result.pendingRefsProcessed) {
+                    clack.log.info('Already up to date');
+                }
+                else if (totalChanges > 0) {
+                    clack.log.success(`Synced ${formatNumber(totalChanges)} changed files`);
+                    const details = [];
+                    if (result.filesAdded > 0)
+                        details.push(`Added: ${result.filesAdded}`);
+                    if (result.filesModified > 0)
+                        details.push(`Modified: ${result.filesModified}`);
+                    if (result.filesRemoved > 0)
+                        details.push(`Removed: ${result.filesRemoved}`);
+                    clack.log.info(`${details.join(', ')} ${(0, glyphs_1.getGlyphs)().dash} ${formatNumber(result.nodesUpdated)} nodes in ${formatDuration(result.durationMs)}`);
+                }
+                if (result.pendingRefsProcessed) {
+                    const unresolved = result.pendingRefsUnresolved
+                        ? ` (${formatNumber(result.pendingRefsUnresolved)} unresolved)` : '';
+                    clack.log.info(`Resolved ${formatNumber(result.pendingRefsResolved ?? 0)} pending references${unresolved}`);
+                }
+                clack.outro('Done');
             }
-            else {
-                clack.log.success(`Synced ${formatNumber(totalChanges)} changed files`);
-                const details = [];
-                if (result.filesAdded > 0)
-                    details.push(`Added: ${result.filesAdded}`);
-                if (result.filesModified > 0)
-                    details.push(`Modified: ${result.filesModified}`);
-                if (result.filesRemoved > 0)
-                    details.push(`Removed: ${result.filesRemoved}`);
-                clack.log.info(`${details.join(', ')} ${(0, glyphs_1.getGlyphs)().dash} ${formatNumber(result.nodesUpdated)} nodes in ${formatDuration(result.durationMs)}`);
+            finally {
+                cg.destroy();
             }
-            clack.outro('Done');
-            cg.destroy();
         }
         catch (err) {
             if (!options.quiet) {
@@ -1051,20 +1197,27 @@ function main() {
             const cg = await LatticeSensor.open(projectPath);
             const limit = parseInt(options.limit || '10', 10);
             const rawResults = cg.searchNodes(search, {
-                limit,
+                // Fetch one extra row so the CLI can report a cut without changing the
+                // long-standing bare-array contract of `query --json` (#1639).
+                limit: limit + 1,
                 kinds: options.kind ? [options.kind] : undefined,
             });
             // Mirror the MCP search down-rank so the CLI also surfaces the
             // hand-written implementation before protobuf/gRPC scaffolding
             // when both share a name. See extraction/generated-detection.ts.
-            const { isGeneratedFile } = await Promise.resolve().then(() => __importStar(require('../extraction/generated-detection')));
-            const results = [...rawResults].sort((a, b) => {
-                const aGen = isGeneratedFile(a.node.filePath) ? 1 : 0;
-                const bGen = isGeneratedFile(b.node.filePath) ? 1 : 0;
+            const isGen = cg.generatedFilePredicate(rawResults.map((r) => r.node.filePath));
+            const rankedResults = [...rawResults].sort((a, b) => {
+                const aGen = isGen(a.node.filePath) ? 1 : 0;
+                const bGen = isGen(b.node.filePath) ? 1 : 0;
                 return aGen - bGen;
             });
+            const truncated = rankedResults.length > limit;
+            const results = rankedResults.slice(0, limit);
+            const truncationMessage = `Results truncated at ${limit}; pass --limit to widen.`;
             if (options.json) {
                 console.log(JSON.stringify(results, null, 2));
+                if (truncated)
+                    console.error(truncationMessage);
             }
             else {
                 if (results.length === 0) {
@@ -1088,6 +1241,8 @@ function main() {
                         }
                         console.log();
                     }
+                    if (truncated)
+                        console.log(chalk.dim(truncationMessage));
                 }
             }
             cg.destroy();
@@ -1136,6 +1291,60 @@ function main() {
             process.exit(1);
         }
     });
+    /**
+     * lattice sensor context <task...>
+     *
+     * The CLI face of the public `buildContext` API (ContextBuilder): FTS entry
+     * points + graph expansion + code blocks, formatted as markdown or JSON.
+     * Advertised in the usage header since the first release but never actually
+     * registered (#1611); external integrations (e.g. Memorix) invoke it as
+     * `lattice sensor context --path <root> --format json --max-nodes 8 --no-code <task>`.
+     */
+    program
+        .command('context <task...>')
+        .description('Build context for a task: relevant symbols, relationships, and code blocks')
+        .option('-p, --path <path>', 'Project path')
+        .option('-f, --format <format>', 'Output format: markdown or json', 'markdown')
+        .option('-n, --max-nodes <number>', 'Maximum number of symbols to include')
+        .option('--no-code', 'Omit code blocks (structure only)')
+        .action(async (taskParts, options) => {
+        const projectPath = resolveProjectPath(options.path);
+        const format = options.format ?? 'markdown';
+        if (format !== 'markdown' && format !== 'json') {
+            error(`Unknown format "${options.format}" — use "markdown" or "json".`);
+            process.exit(1);
+        }
+        let maxNodes;
+        if (options.maxNodes !== undefined) {
+            maxNodes = parseInt(options.maxNodes, 10);
+            if (Number.isNaN(maxNodes) || maxNodes < 1) {
+                error(`--max-nodes expects a positive integer, got "${options.maxNodes}".`);
+                process.exit(1);
+            }
+        }
+        try {
+            if (!(0, directory_1.isInitialized)(projectPath)) {
+                error(`LatticeSensor not initialized in ${projectPath}`);
+                process.exit(1);
+            }
+            const { default: LatticeSensor } = await loadLatticeSensor();
+            const cg = await LatticeSensor.open(projectPath);
+            const result = await cg.buildContext(taskParts.join(' '), {
+                format,
+                includeCode: options.code !== false,
+                ...(maxNodes !== undefined ? { maxNodes } : {}),
+            });
+            // Both supported formats return a formatted string; print it verbatim so
+            // `--format json` stays machine-parseable on stdout (error()/warnings go
+            // to stderr only).
+            console.log(typeof result === 'string' ? result : JSON.stringify(result, null, 2));
+            cg.destroy();
+        }
+        catch (err) {
+            error(`Context build failed: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    });
     /**
      * lattice sensor prompt-hook  (hidden)
      *
@@ -1176,6 +1385,10 @@ function main() {
                 return;
             }
             const prompt = String(input.prompt || '');
+            // System-injected task notifications are not user prompts: exit before
+            // any project lookup or explore work (#1832).
+            if ((0, directory_1.isTaskNotification)(prompt))
+                return;
             // Gate telemetry: how often each tier fires vs. no-ops — counter names
             // only, NEVER prompt content (see TELEMETRY.md). This is the data that
             // turns "is the gate any good" from vibes into a measured recall rate.
@@ -1240,8 +1453,11 @@ function main() {
                         const text = result.content[0]?.text ?? '';
                         if (!result.isError && text.trim()) {
                             // Cap the injection so a large-repo explore can't flood the prompt.
-                            const MAX = 16000;
-                            const body = text.length > MAX ? `${text.slice(0, MAX)}\n…(truncated; call lattice_sensor_explore for the rest)` : text;
+                            // Claude Code shows hook stdout inline only up to 10,000 characters;
+                            // above that it persists the output to a file and the model sees a
+                            // 2 KB preview (#1694). PROMPT_HOOK_INJECTION_MAX (9,000) leaves
+                            // room for the wrapper and the projectPath nudge lines below.
+                            const body = (0, directory_1.capPromptHookInjection)(text);
                             // For a front-loaded SUB-project, a follow-up explore needs its path.
                             const more = plan.viaSubScan
                                 ? `call lattice_sensor_explore with projectPath: "${plan.exploreRoot}" for more`
@@ -1651,9 +1867,9 @@ function main() {
         .aliases(['daemons'])
         .description('Manage running LatticeSensor background daemons — pick one and press enter to stop it')
         .action(async () => {
-        const { listDaemons, stopDaemonAt, stopAllDaemons } = await Promise.resolve().then(() => __importStar(require('../mcp/daemon-registry')));
+        const { listVerifiedDaemons, stopDaemonAt, stopAllDaemons } = await Promise.resolve().then(() => __importStar(require('../mcp/daemon-registry')));
         const { runDaemonPicker } = await Promise.resolve().then(() => __importStar(require('../mcp/daemon-manager')));
-        const daemons = listDaemons();
+        const daemons = await listVerifiedDaemons();
         if (daemons.length === 0) {
             info('No LatticeSensor daemons running.');
             return;
@@ -1680,7 +1896,7 @@ function main() {
         const clack = await importESM('@clack/prompts');
         clack.intro('LatticeSensor daemons');
         await runDaemonPicker({
-            list: listDaemons,
+            list: listVerifiedDaemons,
             stop: stopDaemonAt,
             stopAll: stopAllDaemons,
             cwdRoot,
@@ -1691,6 +1907,172 @@ function main() {
             done: (m) => clack.outro(m),
         });
     });
+    /**
+     * Print the "no index here" guidance.
+     *
+     * The viewer READS an index; it never builds one — indexing stays the user's
+     * decision, exactly as it is for the MCP tools. So a missing index is normal
+     * input, not a failure to apologize for: say what is missing, say the one
+     * command that fixes it, and never print a stack trace.
+     */
+    function printNoIndexGuidance(projectPath) {
+        error(`No LatticeSensor index found for ${projectPath}`);
+        console.error('');
+        // getGlyphs() (not a literal em dash): a legacy Windows console decodes raw
+        // UTF-8 with its OEM codepage and renders one as mojibake (#168).
+        console.error(`  The viewer reads an index that already exists ${(0, glyphs_1.getGlyphs)().dash} it never creates one.`);
+        console.error('  To index this project:');
+        console.error('');
+        console.error(`    ${chalk.cyan('lattice sensor init')}`);
+        console.error('');
+        console.error('  Already indexed somewhere else? Point the viewer at it:');
+        console.error('');
+        console.error(`    ${chalk.cyan('lattice sensor ui /path/to/indexed/project')}`);
+        console.error('');
+    }
+    /**
+     * lattice sensor ui [path]  (alias: web)
+     *
+     * The browser reader: serves the built viewer (`dist/viewer/`) over loopback
+     * and opens it. It opens the index for reading and never writes to it, never
+     * indexes, and never changes a line of the project's code. The single thing it
+     * writes is a trail the reader saved, as JSON under `.lattice/sensor/ui/trails/`;
+     * `--read-only` turns even that off.
+     *
+     * Deliberately absent from TELEMETRY_FLUSH_COMMANDS above: the command's own
+     * banner tells the user nothing leaves their machine, so it must not be the
+     * thing that triggers a telemetry send. The usage count still buffers locally
+     * like every other quick command.
+     */
+    program
+        .command('ui [path]', { hidden: !(0, viewer_gate_1.viewerEnabled)() })
+        .alias('web')
+        .description('Open the LatticeSensor viewer in your browser — read your indexed project as a graph')
+        .option('--port <number>', `Port to listen on (default: ${constants_1.DEFAULT_UI_PORT}, or the next free one)`)
+        .option('--no-open', 'Print the URL instead of opening a browser')
+        .option('--read-only', 'Refuse every write — saved trails can be opened but not saved or deleted')
+        .addHelpText('after', `
+Examples:
+  $ lattice sensor ui                    Read the project you're standing in
+  $ lattice sensor ui ~/code/my-app      Read a specific indexed project
+  $ lattice sensor ui --port 8080        Use one specific port (fails if it's taken)
+  $ lattice sensor ui --no-open          Just print the URL (headless boxes, SSH)
+  $ lattice sensor web                 Same command under its alias
+
+Pick a symbol and you see who calls it on the left, its source in the middle,
+and what it calls on the right at the height of the line that calls it. Search
+with / (or Cmd-K), click a file path for the file's outline and its imports.
+
+Ask "how does execute reach getFile" (or "execute -> getFile") in the search
+box for the flow between two symbols: one card per hop, opened at the line that
+makes the next call, with dynamic-dispatch hops drawn dashed and named. The Map
+tab draws the whole project by module, with dependencies pointing down.
+
+Never opened this codebase before? The Entry points tab lists the routes with
+the symbols that serve them, the files that run something when they load, the
+tests, and what the most code depends on — and starts a flow from any of them.
+
+The page keeps up with the project while it is open: save a file and it says so
+within about a third of a second, and whatever is on screen re-reads the graph
+when something re-indexes it. It watches for that; it never polls.
+
+Save a walk you want to keep: name the trail and it is written to
+.lattice/sensor/ui/trails/ (already gitignored) as plain JSON, listed on the empty
+screen, and reopened at the symbol you left. Hops are remembered by name rather
+than by position, so a saved trail survives re-indexing and says which hop moved
+when one does. Pass --read-only to refuse every write.
+
+The viewer listens on 127.0.0.1 only, so nothing on your network can reach it.
+It opens an index that already exists, never indexes, and never changes a line
+of your code — the one thing it writes is a trail you asked it to save.
+Requests from any other host are refused, and nothing is sent anywhere: no code,
+no paths, no analytics.
+
+Without --port it takes ${constants_1.DEFAULT_UI_PORT}, or the next free port if that one is busy.
+
+Set ${constants_1.BROWSER_ENV}=<command> to choose which browser opens, or
+${constants_1.BROWSER_ENV}=none to never open one.
+`)
+        .action(async (pathArg, options) => {
+        // An explicit --port stays explicit: a scripted `--port 8080` that quietly
+        // lands on 8081 is worse than one that says the port is busy. The default
+        // port is the only one we're free to walk away from.
+        let requestedPort;
+        if (options.port !== undefined) {
+            requestedPort = Number(options.port);
+            if (!Number.isInteger(requestedPort) || requestedPort < 0 || requestedPort > 65535) {
+                error(`--port must be a whole number between 0 and 65535 (got "${options.port}").`);
+                process.exit(1);
+            }
+        }
+        const projectPath = resolveProjectPath(pathArg);
+        // Sensitive-directory refusal before anything opens: the same guard the MCP
+        // entry points use, so `lattice sensor ui /etc` is turned away here rather than
+        // becoming a browsable view of the system.
+        const { validateProjectPath } = await Promise.resolve().then(() => __importStar(require('../utils')));
+        const rootError = validateProjectPath(projectPath);
+        if (rootError) {
+            error(rootError);
+            process.exit(1);
+        }
+        if (!(0, directory_1.isInitialized)(projectPath)) {
+            printNoIndexGuidance(projectPath);
+            process.exit(1);
+        }
+        const { startUiServer, openBrowser, createGraphApi, ViewerMissingError } = await Promise.resolve().then(() => __importStar(require('../ui-server')));
+        // The JSON API the viewer reads its screens from. It opens the index lazily
+        // on the first request, so a slow first paint is the only cost of mounting
+        // it here rather than after the browser connects.
+        const readOnly = options.readOnly === true;
+        const api = createGraphApi({
+            projectRoot: projectPath,
+            readOnly,
+            readOnlyReason: readOnly
+                ? 'This viewer was started with --read-only, so trails cannot be saved.'
+                : undefined,
+        });
+        let handle;
+        try {
+            handle = await startUiServer({
+                projectRoot: projectPath,
+                port: requestedPort,
+                portFallback: requestedPort === undefined,
+                api: api.handler,
+            });
+        }
+        catch (err) {
+            api.close();
+            // Both failure modes here (viewer assets missing, no port available) carry
+            // their own remediation — print it plainly, never a stack trace.
+            error(err instanceof ViewerMissingError || err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+        console.log('');
+        console.log(chalk.bold('LatticeSensor viewer'));
+        console.log('');
+        console.log(`  ${chalk.dim('Reading')}  ${projectPath}`);
+        console.log(`  ${chalk.dim('URL')}      ${chalk.cyan(handle.url)}`);
+        console.log(`  ${chalk.dim('Access')}   this machine only ${(0, glyphs_1.getGlyphs)().dash} ` +
+            (readOnly
+                ? 'read-only, nothing leaves your computer'
+                : 'nothing leaves your computer; saved trails are the only thing written'));
+        console.log('');
+        const opened = options.open === false ? false : openBrowser(handle.url);
+        console.log(opened
+            ? chalk.dim('  Opening your browser... press Ctrl+C to stop.')
+            : chalk.dim('  Open that URL in a browser. Press Ctrl+C to stop.'));
+        console.log('');
+        // The http server keeps the event loop alive on its own; these just make
+        // Ctrl-C hang up live sockets instead of waiting on browser keep-alives.
+        const shutdown = () => {
+            // Release the SQLite handle before the socket: the process should never
+            // exit with a live connection to the user's index.
+            api.close();
+            void handle.close().then(() => process.exit(0));
+        };
+        process.once('SIGINT', shutdown);
+        process.once('SIGTERM', shutdown);
+    });
     /**
      * lattice sensor serve
      */
@@ -1782,12 +2164,17 @@ function main() {
                 return;
             }
             const lockPath = path.join((0, directory_1.getLatticeSensorDir)(projectPath), 'sensor.lock');
-            if (!fs.existsSync(lockPath)) {
-                info(`No lock file found ${(0, glyphs_1.getGlyphs)().dash} nothing to do`);
-                return;
-            }
-            fs.unlinkSync(lockPath);
-            success('Removed lock file. You can now run indexing again.');
+            let removed = false;
+            if (fs.existsSync(lockPath)) {
+                fs.unlinkSync(lockPath);
+                removed = true;
+            }
+            const { clearStaleDaemonArtifacts } = await Promise.resolve().then(() => __importStar(require('../mcp/daemon-registry')));
+            removed = await clearStaleDaemonArtifacts(projectPath) || removed;
+            if (removed)
+                success('Removed stale lock artifacts. You can now run indexing again.');
+            else
+                info(`No stale lock files found ${(0, glyphs_1.getGlyphs)().dash} nothing to do`);
         }
         catch (err) {
             error(`Failed to remove lock: ${err instanceof Error ? err.message : String(err)}`);
@@ -1795,175 +2182,183 @@ function main() {
         }
     });
     /**
-     * lattice sensor callers <symbol>
+     * CLI parity with MCP callers/callees: resolve once, then collect and limit
+     * within each definition. The legacy JSON list remains an explicitly labeled
+     * union, with its original total/limit/truncated contract (#1674).
      *
-     * CLI parity with the MCP graph tools (lattice_sensor_callers/callees/impact) so the
-     * traversal queries work in scripts, CI, and git hooks without a running MCP
-     * server.
+     * Lattice contract on top (src/sensor-adapter.mjs, todo-structure-source-adapter,
+     * seam-cost): `--exact-path` traverses exactly the definition of `symbol` in one
+     * repo-relative file and reports `exactResolution`; every listed node carries
+     * `edgeKind`/`valueRef`/`valueWrite` from the edges that connect it.
      */
-    program
-        .command('callers <symbol>')
-        .description('Find all functions/methods that call a specific symbol')
-        .option('-p, --path <path>', 'Project path')
-        .option('-l, --limit <number>', 'Maximum results', '20')
-        .option('--exact-path <repo-relative-path>', 'Traverse one exact symbol in this repo-relative file')
-        .option('-j, --json', 'Output as JSON')
-        .action(async (symbol, options) => {
-        const projectPath = resolveProjectPath(options.path);
-        try {
-            if (!(0, directory_1.isInitialized)(projectPath)) {
-                error(`LatticeSensor not initialized in ${projectPath}`);
-                process.exit(1);
-            }
-            const { default: LatticeSensor } = await loadLatticeSensor();
-            const cg = await LatticeSensor.open(projectPath);
-            const limit = parseInt(options.limit || '20', 10);
-            const matches = cg.searchNodes(symbol, { limit: 50 });
-            if (matches.length === 0) {
-                info(`Symbol "${symbol}" not found`);
-                cg.destroy();
-                return;
-            }
-            const seen = new Set();
-            const allCallers = [];
-            const strict = options.exactPath === undefined
-                ? null : (0, exact_traversal_1.selectExactTraversalCandidate)(matches, symbol, options.exactPath);
-            const traversalMatches = strict === null
-                ? matches : strict.outcome === 'ready' ? [strict.candidate] : [];
-            for (const match of traversalMatches) {
-                const exactMatch = match.node.name === symbol || match.node.name.endsWith(`.${symbol}`) || match.node.name.endsWith(`::${symbol}`);
-                if (strict === null && !exactMatch && matches.length > 1)
-                    continue;
-                for (const c of cg.getCallers(match.node.id)) {
-                    if (!seen.has(c.node.id)) {
-                        seen.add(c.node.id);
-                        allCallers.push({ name: c.node.name, kind: c.node.kind, filePath: c.node.filePath, startLine: c.node.startLine, edgeKind: c.edge.kind, valueRef: c.edge.metadata?.valueRef === true, valueWrite: c.edge.metadata?.write === true });
-                    }
+    for (const direction of ['callers', 'callees']) {
+        const title = direction === 'callers' ? 'Callers' : 'Callees';
+        program
+            .command(`${direction} <symbol>`)
+            .description(direction === 'callers'
+            ? 'Find all functions/methods that call a specific symbol'
+            : 'Find all functions/methods called by a specific symbol')
+            .option('-p, --path <path>', 'Project path')
+            .option('-f, --file <path>', 'Narrow definitions by file path or suffix (no match: show all with a note)')
+            .option('-l, --limit <number>', 'Maximum results per definition (also caps the JSON union)', '20')
+            .option('--exact-path <repo-relative-path>', 'Traverse one exact symbol in this repo-relative file')
+            .option('-j, --json', 'Output as JSON')
+            .action(async (symbol, options) => {
+            const projectPath = resolveProjectPath(options.path);
+            try {
+                if (!(0, directory_1.isInitialized)(projectPath)) {
+                    error(`LatticeSensor not initialized in ${projectPath}`);
+                    process.exit(1);
                 }
-            }
-            // Fallback: if exact filter removed everything, use the top match
-            if (strict === null && allCallers.length === 0 && matches[0]) {
-                for (const c of cg.getCallers(matches[0].node.id)) {
-                    if (!seen.has(c.node.id)) {
-                        seen.add(c.node.id);
-                        allCallers.push({ name: c.node.name, kind: c.node.kind, filePath: c.node.filePath, startLine: c.node.startLine, edgeKind: c.edge.kind, valueRef: c.edge.metadata?.valueRef === true, valueWrite: c.edge.metadata?.write === true });
+                const { default: LatticeSensor } = await loadLatticeSensor();
+                const cg = await LatticeSensor.open(projectPath);
+                try {
+                    const limit = parseInt(options.limit || '20', 10);
+                    const { nodes: targets } = (0, symbol_lookup_1.lookupSymbolNodes)(cg, symbol);
+                    if (targets.length === 0) {
+                        info(formatSymbolNotFound(symbol, cg.searchNodes(symbol, { limit: 5 }).map((m) => m.node.name)));
+                        return;
                     }
-                }
-            }
-            const limited = allCallers.slice(0, limit);
-            if (options.json) {
-                console.log(JSON.stringify({
-                    symbol,
-                    ...(strict === null ? {} : { exactPath: options.exactPath, exactResolution: strict.outcome }),
-                    callers: limited,
-                }, null, 2));
-            }
-            else if (limited.length === 0) {
-                info(`No callers found for "${symbol}"`);
-            }
-            else {
-                console.log(chalk.bold(`\nCallers of "${symbol}" (${limited.length}):\n`));
-                for (const node of limited) {
-                    const loc = node.startLine ? `:${node.startLine}` : '';
-                    console.log(chalk.cyan(node.kind.padEnd(12)) +
-                        chalk.white(node.name));
-                    console.log(chalk.dim(`  ${node.filePath}${loc}`));
-                    console.log();
-                }
-            }
-            cg.destroy();
-        }
-        catch (err) {
-            error(`callers failed: ${err instanceof Error ? err.message : String(err)}`);
-            process.exit(1);
-        }
-    });
-    /**
-     * lattice sensor callees <symbol>
-     */
-    program
-        .command('callees <symbol>')
-        .description('Find all functions/methods that a specific symbol calls')
-        .option('-p, --path <path>', 'Project path')
-        .option('-l, --limit <number>', 'Maximum results', '20')
-        .option('--exact-path <repo-relative-path>', 'Traverse one exact symbol in this repo-relative file')
-        .option('-j, --json', 'Output as JSON')
-        .action(async (symbol, options) => {
-        const projectPath = resolveProjectPath(options.path);
-        try {
-            if (!(0, directory_1.isInitialized)(projectPath)) {
-                error(`LatticeSensor not initialized in ${projectPath}`);
-                process.exit(1);
-            }
-            const { default: LatticeSensor } = await loadLatticeSensor();
-            const cg = await LatticeSensor.open(projectPath);
-            const limit = parseInt(options.limit || '20', 10);
-            const matches = cg.searchNodes(symbol, { limit: 50 });
-            if (matches.length === 0) {
-                info(`Symbol "${symbol}" not found`);
-                cg.destroy();
-                return;
-            }
-            const seen = new Set();
-            const allCallees = [];
-            const strict = options.exactPath === undefined
-                ? null : (0, exact_traversal_1.selectExactTraversalCandidate)(matches, symbol, options.exactPath);
-            const traversalMatches = strict === null
-                ? matches : strict.outcome === 'ready' ? [strict.candidate] : [];
-            for (const match of traversalMatches) {
-                const exactMatch = match.node.name === symbol || match.node.name.endsWith(`.${symbol}`) || match.node.name.endsWith(`::${symbol}`);
-                if (strict === null && !exactMatch && matches.length > 1)
-                    continue;
-                for (const c of cg.getCallees(match.node.id)) {
-                    if (!seen.has(c.node.id)) {
-                        seen.add(c.node.id);
-                        allCallees.push({ name: c.node.name, kind: c.node.kind, filePath: c.node.filePath, startLine: c.node.startLine, edgeKind: c.edge.kind, valueRef: c.edge.metadata?.valueRef === true, valueWrite: c.edge.metadata?.write === true });
+                    const strict = options.exactPath === undefined
+                        ? null : (0, exact_traversal_1.selectExactTraversalCandidate)(targets.map((node) => ({ node })), symbol, options.exactPath);
+                    if (strict !== null && strict.outcome !== 'ready') {
+                        if (options.json) {
+                            console.log(JSON.stringify({
+                                symbol, exactPath: options.exactPath, exactResolution: strict.outcome,
+                                [direction]: [], total: 0, limit, truncated: false,
+                            }, null, 2));
+                        }
+                        else {
+                            info(`No single definition of "${symbol}" in ${options.exactPath} (${strict.outcome})`);
+                        }
+                        return;
                     }
-                }
-            }
-            if (strict === null && allCallees.length === 0 && matches[0]) {
-                for (const c of cg.getCallees(matches[0].node.id)) {
-                    if (!seen.has(c.node.id)) {
-                        seen.add(c.node.id);
-                        allCallees.push({ name: c.node.name, kind: c.node.kind, filePath: c.node.filePath, startLine: c.node.startLine, edgeKind: c.edge.kind, valueRef: c.edge.metadata?.valueRef === true, valueWrite: c.edge.metadata?.write === true });
+                    const exact = strict === null
+                        ? {} : { exactPath: options.exactPath, exactResolution: strict.outcome };
+                    const { groups, filteredOut } = (0, symbol_lookup_1.groupDefinitions)(strict === null ? targets : [strict.candidate.node], options.file);
+                    const ambiguous = groups.length > 1;
+                    const note = filteredOut
+                        ? `no definition of "${symbol}" matches file "${options.file}" — showing all definitions instead.`
+                        : undefined;
+                    const collected = groups.map((group) => {
+                        const nodes = new Map();
+                        const edges = new Map();
+                        for (const target of group) {
+                            const connections = direction === 'callers' ? cg.getCallers(target.id) : cg.getCallees(target.id);
+                            for (const { node, edge } of connections) {
+                                nodes.set(node.id, node);
+                                edges.set(`${edge.source}->${edge.target}:${edge.kind}`, edge);
+                            }
+                        }
+                        return { group, nodes: [...nodes.values()], edges: [...edges.values()] };
+                    });
+                    const relationships = (node, edges) => [...new Set(edges
+                            .filter((edge) => (direction === 'callers' ? edge.source : edge.target) === node.id)
+                            .map((edge) => edge.kind))];
+                    // Lattice: the edge facts behind each listed node. A value write on ANY
+                    // connecting edge counts — dropping one would hide a writer from seam cost.
+                    const edgeFacts = (node, edges) => {
+                        const own = edges.filter((edge) => (direction === 'callers' ? edge.source : edge.target) === node.id);
+                        return {
+                            edgeKind: own[0]?.kind ?? 'calls',
+                            valueRef: own.some((edge) => edge.metadata?.valueRef === true),
+                            valueWrite: own.some((edge) => edge.metadata?.valueWrite === true),
+                        };
+                    };
+                    if (options.json) {
+                        const definitions = collected.map(({ group, nodes, edges }) => {
+                            const limited = nodes.slice(0, limit);
+                            const shown = new Set(limited.map((node) => node.id));
+                            return {
+                                ...cliDefinition(group),
+                                [direction]: limited.map((node) => ({ id: node.id, ...cliNode(node),
+                                    relationships: relationships(node, edges), ...edgeFacts(node, edges) })),
+                                edges: edges.filter((edge) => shown.has(direction === 'callers' ? edge.source : edge.target)),
+                                total: nodes.length,
+                                limit,
+                                truncated: nodes.length > limit,
+                            };
+                        });
+                        const union = new Map();
+                        for (const { nodes } of collected) {
+                            for (const node of nodes)
+                                union.set(node.id, node);
+                        }
+                        const total = union.size;
+                        console.log(JSON.stringify({
+                            symbol,
+                            ...exact,
+                            targets: groups.flat().map((node) => cliDefinition([node]).definition),
+                            ambiguous,
+                            aggregation: ambiguous ? 'union' : 'definition',
+                            file: options.file,
+                            filteredOut,
+                            note,
+                            definitions,
+                            [direction]: [...union.values()].slice(0, limit).map((node) => {
+                                const all = collected.flatMap((entry) => entry.edges);
+                                return { ...cliNode(node), relationships: relationships(node, all), ...edgeFacts(node, all) };
+                            }),
+                            total,
+                            limit,
+                            truncated: total > limit,
+                        }, null, 2));
+                    }
+                    else {
+                        if (note)
+                            warn(note);
+                        if (ambiguous) {
+                            console.log(chalk.bold(`\n${title} of "${symbol}" — ${groups.length} distinct definitions (narrow with --file):`));
+                        }
+                        for (const { group, nodes, edges } of collected) {
+                            const limited = nodes.slice(0, limit);
+                            const total = nodes.length;
+                            const truncated = total > limit;
+                            const count = truncated ? `${limited.length} of ${total}` : String(total);
+                            if (ambiguous) {
+                                console.log(chalk.bold(`\n${(0, symbol_lookup_1.describeSymbolNode)(group[0])} (${count}):\n`));
+                            }
+                            else {
+                                console.log(chalk.bold(`\n${title} of "${symbol}" (${count}):\n`));
+                                console.log(chalk.dim((0, symbol_lookup_1.describeSymbolNode)(group[0])));
+                            }
+                            if (total === 0) {
+                                if (ambiguous)
+                                    console.log(chalk.dim(`  (no ${direction})`));
+                                else
+                                    info(`No ${direction} found for "${symbol}"`);
+                            }
+                            for (const node of limited) {
+                                const loc = node.startLine ? `:${node.startLine}` : '';
+                                const kinds = relationships(node, edges).filter((kind) => kind !== 'calls');
+                                const relation = kinds.length ? ` [${kinds.join(', ')}]` : '';
+                                console.log(chalk.cyan(node.kind.padEnd(12)) + chalk.white(node.name) + chalk.dim(relation));
+                                console.log(chalk.dim(`  ${node.filePath}${loc}`));
+                                console.log();
+                            }
+                            if (truncated)
+                                console.log(chalk.dim(`Showing ${limited.length} of ${total}; pass --limit to widen.`));
+                        }
                     }
                 }
-            }
-            const limited = allCallees.slice(0, limit);
-            if (options.json) {
-                console.log(JSON.stringify({
-                    symbol,
-                    ...(strict === null ? {} : { exactPath: options.exactPath, exactResolution: strict.outcome }),
-                    callees: limited,
-                }, null, 2));
-            }
-            else if (limited.length === 0) {
-                info(`No callees found for "${symbol}"`);
-            }
-            else {
-                console.log(chalk.bold(`\nCallees of "${symbol}" (${limited.length}):\n`));
-                for (const node of limited) {
-                    const loc = node.startLine ? `:${node.startLine}` : '';
-                    console.log(chalk.cyan(node.kind.padEnd(12)) +
-                        chalk.white(node.name));
-                    console.log(chalk.dim(`  ${node.filePath}${loc}`));
-                    console.log();
+                finally {
+                    cg.destroy();
                 }
             }
-            cg.destroy();
-        }
-        catch (err) {
-            error(`callees failed: ${err instanceof Error ? err.message : String(err)}`);
-            process.exit(1);
-        }
-    });
+            catch (err) {
+                error(`${direction} failed: ${err instanceof Error ? err.message : String(err)}`);
+                process.exit(1);
+            }
+        });
+    }
     /**
-     * lattice sensor impact <symbol>
+     * lattice sensor impact <symbol> — one blast radius per distinct definition.
      */
     program
         .command('impact <symbol>')
         .description('Analyze what code is affected by changing a symbol')
         .option('-p, --path <path>', 'Project path')
+        .option('-f, --file <path>', 'Narrow definitions by file path or suffix (no match: show all with a note)')
         .option('-d, --depth <number>', 'Traversal depth', '2')
         .option('-j, --json', 'Output as JSON')
         .action(async (symbol, options) => {
@@ -1975,72 +2370,95 @@ function main() {
             }
             const { default: LatticeSensor } = await loadLatticeSensor();
             const cg = await LatticeSensor.open(projectPath);
-            const depth = Math.min(Math.max(parseInt(options.depth || '2', 10), 1), 10);
-            const matches = cg.searchNodes(symbol, { limit: 50 });
-            if (matches.length === 0) {
-                info(`Symbol "${symbol}" not found`);
-                cg.destroy();
-                return;
-            }
-            // Merge impact subgraphs across all exact-matching symbols
-            const mergedNodes = new Map();
-            const seenEdges = new Set();
-            let edgeCount = 0;
-            for (const match of matches) {
-                const exactMatch = match.node.name === symbol || match.node.name.endsWith(`.${symbol}`) || match.node.name.endsWith(`::${symbol}`);
-                if (!exactMatch && matches.length > 1)
-                    continue;
-                const impact = cg.getImpactRadius(match.node.id, depth);
-                for (const [id, n] of impact.nodes) {
-                    mergedNodes.set(id, { name: n.name, kind: n.kind, filePath: n.filePath, startLine: n.startLine });
+            try {
+                const depth = Math.min(Math.max(parseInt(options.depth || '2', 10), 1), 10);
+                const { nodes: targets } = (0, symbol_lookup_1.lookupSymbolNodes)(cg, symbol);
+                if (targets.length === 0) {
+                    info(formatSymbolNotFound(symbol, cg.searchNodes(symbol, { limit: 5 }).map((m) => m.node.name)));
+                    return;
                 }
-                for (const e of impact.edges) {
-                    const key = `${e.source}->${e.target}:${e.kind}`;
-                    if (!seenEdges.has(key)) {
-                        seenEdges.add(key);
-                        edgeCount++;
+                const { groups, filteredOut } = (0, symbol_lookup_1.groupDefinitions)(targets, options.file);
+                const ambiguous = groups.length > 1;
+                const note = filteredOut
+                    ? `no definition of "${symbol}" matches file "${options.file}" — showing all definitions instead.`
+                    : undefined;
+                const collected = groups.map((group) => {
+                    const nodes = new Map();
+                    const edges = new Map();
+                    for (const target of group) {
+                        const impact = cg.getImpactRadius(target.id, depth);
+                        for (const [id, node] of impact.nodes)
+                            nodes.set(id, node);
+                        for (const edge of impact.edges)
+                            edges.set(`${edge.source}->${edge.target}:${edge.kind}`, edge);
                     }
+                    return { group, nodes, edges };
+                });
+                if (options.json) {
+                    const unionNodes = new Map();
+                    const unionEdges = new Map();
+                    const definitions = collected.map(({ group, nodes, edges }) => {
+                        for (const [id, node] of nodes)
+                            unionNodes.set(id, node);
+                        for (const [key, edge] of edges)
+                            unionEdges.set(key, edge);
+                        return {
+                            ...cliDefinition(group),
+                            nodeCount: nodes.size,
+                            edgeCount: edges.size,
+                            affected: [...nodes.values()].map((node) => ({ id: node.id, ...cliNode(node) })),
+                            edges: [...edges.values()],
+                        };
+                    });
+                    console.log(JSON.stringify({
+                        symbol,
+                        depth,
+                        targets: groups.flat().map((node) => cliDefinition([node]).definition),
+                        ambiguous,
+                        aggregation: ambiguous ? 'union' : 'definition',
+                        file: options.file,
+                        filteredOut,
+                        note,
+                        definitions,
+                        nodeCount: unionNodes.size,
+                        edgeCount: unionEdges.size,
+                        affected: [...unionNodes.values()].map(cliNode),
+                    }, null, 2));
                 }
-            }
-            // Fallback to top match if exact filter removed everything
-            if (mergedNodes.size === 0 && matches[0]) {
-                const impact = cg.getImpactRadius(matches[0].node.id, depth);
-                for (const [id, n] of impact.nodes) {
-                    mergedNodes.set(id, { name: n.name, kind: n.kind, filePath: n.filePath, startLine: n.startLine });
-                }
-                edgeCount = impact.edges.length;
-            }
-            if (options.json) {
-                console.log(JSON.stringify({
-                    symbol,
-                    depth,
-                    nodeCount: mergedNodes.size,
-                    edgeCount,
-                    affected: Array.from(mergedNodes.values()),
-                }, null, 2));
-            }
-            else if (mergedNodes.size === 0) {
-                info(`No affected symbols found for "${symbol}"`);
-            }
-            else {
-                console.log(chalk.bold(`\nImpact of changing "${symbol}" — ${mergedNodes.size} affected symbols:\n`));
-                // Group by file
-                const byFile = new Map();
-                for (const node of mergedNodes.values()) {
-                    const list = byFile.get(node.filePath) || [];
-                    list.push({ name: node.name, kind: node.kind, startLine: node.startLine });
-                    byFile.set(node.filePath, list);
-                }
-                for (const [file, nodes] of byFile) {
-                    console.log(chalk.cyan(file));
-                    for (const node of nodes) {
-                        const loc = node.startLine ? `:${node.startLine}` : '';
-                        console.log(`  ${chalk.dim(node.kind.padEnd(12))}${node.name}${chalk.dim(loc)}`);
+                else {
+                    if (note)
+                        warn(note);
+                    if (ambiguous) {
+                        console.log(chalk.bold(`\nImpact of changing "${symbol}" — ${groups.length} distinct definitions (each with its own blast radius; narrow with --file):`));
+                    }
+                    for (const { group, nodes } of collected) {
+                        if (ambiguous) {
+                            console.log(chalk.bold(`\n${(0, symbol_lookup_1.describeSymbolNode)(group[0])} — ${nodes.size} affected symbols:\n`));
+                        }
+                        else {
+                            console.log(chalk.bold(`\nImpact of changing "${symbol}" — ${nodes.size} affected symbols:\n`));
+                            console.log(chalk.dim((0, symbol_lookup_1.describeSymbolNode)(group[0])));
+                        }
+                        const byFile = new Map();
+                        for (const node of nodes.values()) {
+                            const list = byFile.get(node.filePath) || [];
+                            list.push(node);
+                            byFile.set(node.filePath, list);
+                        }
+                        for (const [file, affected] of byFile) {
+                            console.log(chalk.cyan(file));
+                            for (const node of affected) {
+                                const loc = node.startLine ? `:${node.startLine}` : '';
+                                console.log(`  ${chalk.dim(node.kind.padEnd(12))}${node.name}${chalk.dim(loc)}`);
+                            }
+                            console.log();
+                        }
                     }
-                    console.log();
                 }
             }
-            cg.destroy();
+            finally {
+                cg.destroy();
+            }
         }
         catch (err) {
             error(`impact failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -2106,6 +2524,11 @@ function main() {
                     .replace(/\*/g, '[^/]*');
                 customFilter = new RegExp(regex);
             }
+            // One notion of "a test" for the whole tool (#1507): the CLI used to keep
+            // its own six regexes here, which knew `.test.` and `/tests/` but not Go's
+            // `_test.go`, Python's `test_x.py` or the JVM's `FooTest.kt` — so
+            // `affected` reported "no tests" for whole ecosystems while `search` and
+            // the MCP tools counted those very files as tests.
             function matchesTestFile(filePath) {
                 if (customFilter)
                     return customFilter.test(filePath);