@aroman22/codegraph-vba-darwin-arm64 1.5.1 → 1.6.0

package/bin/codegraph

@@ -10,5 +10,10 @@ while [ -L "$SELF" ]; do
   esac
 done
 DIR="$(cd "$(dirname "$SELF")/.." && pwd)"
+# Thread the MCP host's pid to the server's orphan watchdog (issue #1185).
+# $PPID is our parent — the host itself when it launched this script directly;
+# an already-threaded value (the npm shim sets the true host pid) wins.
+CODEGRAPH_HOST_PPID="${CODEGRAPH_HOST_PPID:-$PPID}"
+export CODEGRAPH_HOST_PPID
 # --liftoff-only: avoid the V8 turboshaft WASM Zone OOM (issues #293/#298).
 exec "$DIR/node" --liftoff-only "$DIR/lib/dist/bin/codegraph.js" "$@"

package/lib/dist/bin/codegraph.d.ts

@@ -22,5 +22,5 @@
  *   codegraph affected [files]   Find test files affected by changes
  *   codegraph upgrade [version]  Update CodeGraph to the latest release
  */
-export {};
+import '../mcp/early-ppid';
 //# sourceMappingURL=codegraph.d.ts.map

package/lib/dist/bin/codegraph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codegraph.d.ts","sourceRoot":"","sources":["../../src/bin/codegraph.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;GAsBG"}
+{"version":3,"file":"codegraph.d.ts","sourceRoot":"","sources":["../../src/bin/codegraph.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH,OAAO,mBAAmB,CAAC"}

package/lib/dist/bin/codegraph.js

@@ -57,10 +57,15 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+// FIRST import, before anything else loads: capture process.ppid while our
+// 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");
 const commander_1 = require("commander");
 const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 const directory_1 = require("../directory");
+const identifier_segments_1 = require("../search/identifier-segments");
 const worktree_1 = require("../sync/worktree");
 const shimmer_progress_1 = require("../ui/shimmer-progress");
 const glyphs_1 = require("../ui/glyphs");
@@ -339,6 +344,14 @@ 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)}`);
+            // 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
+            // reconciliation warning; per-file extractor warnings stay in the
+            // error-code summary below.
+            for (const w of result.errors.filter((e) => e.code === 'index_partial')) {
+                clack.log.warn(w.message);
+            }
         }
         else if (hasErrors) {
             clack.log.error(`Indexing failed ${(0, glyphs_1.getGlyphs)().dash} all ${formatNumber(result.filesErrored)} files had errors`);
@@ -381,6 +394,68 @@ function main() {
             }
         }
     }
+    /**
+     * When an `init`/`index` produced an EMPTY graph and the reason is that the
+     * project's own `.gitignore` excludes nested git repositories — the "super-repo
+     * gitignores its child repos" layout (#1156), where `init` at the parent
+     * correctly indexes ~nothing while `init` inside each child works — name those
+     * repos and offer to index them. An interactive terminal gets a yes/no prompt
+     * that writes `includeIgnored` to codegraph.json and re-indexes; a
+     * non-interactive run just prints the one-line opt-in snippet. The caller gates
+     * this on `nodesCreated === 0`, so a project that DID index real content is
+     * never nagged about the gitignored reference clones it deliberately keeps out
+     * (#970, #1065). Best-effort throughout: detection never breaks the command.
+     */
+    async function offerIndexIgnoredRepos(clack, projectPath, reindex, opts) {
+        let repos;
+        try {
+            const { findUnindexedIgnoredRepos } = await Promise.resolve().then(() => __importStar(require('../extraction')));
+            repos = findUnindexedIgnoredRepos(projectPath);
+        }
+        catch {
+            return; // detection is advisory — never let it break the command
+        }
+        if (repos.length === 0)
+            return;
+        const { PROJECT_CONFIG_FILENAME } = await Promise.resolve().then(() => __importStar(require('../project-config')));
+        const isOne = repos.length === 1;
+        const SHOWN = 6;
+        const names = repos.slice(0, SHOWN).map((r) => r.replace(/\/$/, ''));
+        const extra = repos.length > SHOWN ? ` (+${formatNumber(repos.length - SHOWN)} more)` : '';
+        const snippet = `{ "includeIgnored": [${repos.map((p) => JSON.stringify(p)).join(', ')}] }`;
+        clack.log.warn(`Your .gitignore excludes ${isOne ? 'a nested git repository' : `${formatNumber(repos.length)} nested git repositories`} here, ` +
+            `so ${isOne ? 'it was' : 'they were'} not indexed: ${names.join(', ')}${extra}.`);
+        const manualHint = () => {
+            clack.log.info(`If ${isOne ? "it's" : "they're"} your code, add ${isOne ? 'it' : 'them'} to ${PROJECT_CONFIG_FILENAME} and re-index:`);
+            clack.log.info(`  ${snippet}`);
+        };
+        if (!opts.interactive || !process.stdin.isTTY) {
+            manualHint();
+            return;
+        }
+        const yes = await clack.confirm({
+            message: `Index ${isOne ? 'it' : `these ${formatNumber(repos.length)}`} now? Adds ${isOne ? 'it' : 'them'} to ${PROJECT_CONFIG_FILENAME}.`,
+            initialValue: true,
+        });
+        if (clack.isCancel(yes) || !yes) {
+            manualHint();
+            return;
+        }
+        let added;
+        try {
+            const { addIncludeIgnoredPatterns } = await Promise.resolve().then(() => __importStar(require('../project-config')));
+            added = addIncludeIgnoredPatterns(projectPath, repos);
+        }
+        catch (err) {
+            clack.log.error(`Could not update ${PROJECT_CONFIG_FILENAME}: ${err instanceof Error ? err.message : String(err)}`);
+            manualHint();
+            return;
+        }
+        clack.log.success(`Added ${formatNumber(added)} ${added === 1 ? 'entry' : 'entries'} to ${PROJECT_CONFIG_FILENAME} ${(0, glyphs_1.getGlyphs)().dash} re-indexing…`);
+        const result = await reindex();
+        printIndexResult(clack, result, projectPath);
+        return result;
+    }
     /**
      * Write detailed error log to .codegraph/errors.log
      */
@@ -470,36 +545,43 @@ function main() {
                 clack.outro('');
                 return;
             }
-            const { default: CodeGraph } = await loadCodeGraph();
+            const { default: CodeGraph, getDatabasePath } = await loadCodeGraph();
             const cg = await CodeGraph.init(projectPath, { index: false });
             clack.log.success(`Initialized in ${projectPath}`);
             // 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.
             // Supervise the index: self-terminate if orphaned or wedged (#999).
-            const supervision = (0, command_supervision_1.installCommandSupervision)('init');
-            let result;
-            try {
-                if (options.verbose) {
-                    result = await cg.indexAll({
-                        onProgress: createVerboseProgress(),
-                        verbose: true,
-                    });
-                }
-                else {
+            // The DB + WAL paths let the liveness watchdog tell a slow store on
+            // degraded storage from a true wedge (#1231).
+            // A closure so we can re-run the exact same supervised, progress-rendered
+            // index if the user opts gitignored child repos in below (#1156).
+            const dbPath = getDatabasePath(projectPath);
+            const runIndex = async () => {
+                const supervision = (0, command_supervision_1.installCommandSupervision)('init', { progressPaths: [dbPath, `${dbPath}-wal`] });
+                try {
+                    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)();
-                    result = await cg.indexAll({
-                        onProgress: progress.onProgress,
-                    });
+                    const r = await cg.indexAll({ onProgress: progress.onProgress });
                     await progress.stop();
+                    return r;
                 }
-            }
-            finally {
-                supervision.stop();
-            }
+                finally {
+                    supervision.stop();
+                }
+            };
+            const result = await runIndex();
             printIndexResult(clack, result, projectPath);
             await recordIndexTelemetry(cg, result);
+            // 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)
+            if (result.nodesCreated === 0) {
+                await offerIndexIgnoredRepos(clack, projectPath, runIndex, { interactive: true });
+            }
             try {
                 const { offerWatchFallback } = await Promise.resolve().then(() => __importStar(require('../installer')));
                 await offerWatchFallback(clack, projectPath);
@@ -590,16 +672,26 @@ function main() {
                 info('Run "codegraph init" first');
                 process.exit(1);
             }
-            const { default: CodeGraph } = await loadCodeGraph();
-            const cg = await CodeGraph.open(projectPath);
+            const { default: CodeGraph, getDatabasePath } = await loadCodeGraph();
+            // `index` is a FULL re-index — identical to a fresh `init`. RECREATE the
+            // database from scratch (discard .codegraph/codegraph.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 CodeGraph.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).
-            const supervision = (0, command_supervision_1.installCommandSupervision)('index');
+            // 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. `index` is a full re-index, so clear the
-                    // existing graph and rebuild from scratch (see the note below — #874).
-                    cg.clear();
+                    // Quiet mode: no UI, just run against the freshly-recreated graph.
                     const result = await cg.indexAll();
                     if (!result.success)
                         process.exit(1);
@@ -608,30 +700,28 @@ function main() {
                 }
                 const clack = await importESM('@clack/prompts');
                 clack.intro('Indexing project');
-                // `index` is a FULL re-index: clear the existing graph and rebuild it from
-                // scratch so the result is identical to a fresh `init`. Without the clear,
-                // indexAll() skips every unchanged file by its content hash and reports
-                // "0 nodes, 0 edges" against the already-populated graph — which reads as
-                // "index wiped my index" (#874). For fast incremental updates use `sync`.
-                cg.clear();
-                let result;
-                if (options.verbose) {
-                    result = await cg.indexAll({
-                        onProgress: createVerboseProgress(),
-                        verbose: true,
-                    });
-                }
-                else {
+                // 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)();
-                    result = await cg.indexAll({
-                        onProgress: progress.onProgress,
-                    });
+                    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);
-                if (!result.success) {
+                // 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');
@@ -742,6 +832,10 @@ function main() {
             const journalMode = cg.getJournalMode();
             const buildInfo = cg.getIndexBuildInfo();
             const reindexRecommended = cg.isIndexStale();
+            const indexState = cg.getIndexState();
+            // Zero on a healthy index; non-zero at rest means a resolution pass was
+            // interrupted, so some files' call edges are missing (#1187).
+            const pendingRefs = cg.getPendingReferenceCount();
             // JSON output mode
             if (options.json) {
                 const lastIndexedMs = cg.getLastIndexedAt();
@@ -772,6 +866,14 @@ function main() {
                         builtWithExtractionVersion: buildInfo.extractionVersion,
                         currentExtractionVersion: extraction_version_1.EXTRACTION_VERSION,
                         reindexRecommended,
+                        // 'complete' | 'partial' (files silently dropped) | 'indexing'
+                        // (a run was killed mid-index — the index is truncated) |
+                        // 'failed' | null (predates the marker).
+                        state: indexState,
+                        // References awaiting resolution. Non-zero at rest means an
+                        // interrupted resolution pass left edges missing; the next
+                        // sync sweeps them (#1187).
+                        pendingRefs,
                     },
                 }));
                 cg.destroy();
@@ -783,6 +885,18 @@ function main() {
             if (worktreeMismatch) {
                 warn((0, worktree_1.worktreeMismatchWarning)(worktreeMismatch));
             }
+            if (indexState === 'indexing') {
+                warn('The last index run never finished (killed mid-index?) — the index is truncated. Re-run "codegraph index".');
+            }
+            else if (indexState === 'partial') {
+                warn('The last index run silently dropped files — the index is partial. Re-run "codegraph index".');
+            }
+            else if (indexState === 'failed') {
+                warn('The last index run failed — results may be incomplete. Re-run "codegraph index".');
+            }
+            if (pendingRefs > 0) {
+                warn(`${formatNumber(pendingRefs)} references from an interrupted run are awaiting resolution — some callers/impact edges are missing. Run "codegraph sync" to resolve them.`);
+            }
             console.log();
             // Index stats
             console.log(chalk.bold('Index Statistics:'));
@@ -897,13 +1011,16 @@ function main() {
                 }
                 else {
                     console.log(chalk.bold(`\nSearch Results for "${search}":\n`));
+                    // Results arrive already ranked by relevance, so the order conveys
+                    // it. We don't print the raw score: it's an unbounded BM25/FTS value
+                    // (relative-ranking only), and the old `(score * 100)%` rendered it
+                    // as nonsensical percentages like "12042%" (#1045). The MCP search
+                    // tool likewise shows no score. Raw `score` stays in --json output.
                     for (const result of results) {
                         const node = result.node;
                         const location = `${node.filePath}:${node.startLine}`;
-                        const score = chalk.dim(`(${(result.score * 100).toFixed(0)}%)`);
                         console.log(chalk.cyan(node.kind.padEnd(12)) +
-                            chalk.white(node.qualifiedName || node.name) +
-                            ' ' + score);
+                            chalk.white(node.qualifiedName || node.name));
                         console.log(chalk.dim(`  ${location}`));
                         if (node.signature) {
                             console.log(chalk.dim(`  ${node.signature}`));
@@ -998,16 +1115,35 @@ function main() {
                 return;
             }
             const prompt = String(input.prompt || '');
-            // Gate: only structural / flow / impact / where-how prompts get context, so
-            // every other prompt ("fix this typo") stays a zero-cost no-op. Language-aware
-            // (English + CJK keywords, plus code-shaped tokens) so it fires for non-English
-            // prompts too (issue #994). A keyword fires on its own; a code-token is only a
-            // CANDIDATE — verified against the graph below, so a tech brand ("JavaScript")
-            // that looks like a symbol but isn't one here doesn't inject spurious context.
+            // 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.
+            const gate = (outcome) => {
+                try {
+                    (0, telemetry_1.getTelemetry)().recordUsage('cli_command', `prompt-hook-gate-${outcome}`, true);
+                }
+                catch { /* never break the hook */ }
+            };
+            // Gate, tiered by confidence (#994, #1126):
+            //   HIGH   — a structural keyword (any covered language), or a code-shaped
+            //            token verified in the index → full explore injection.
+            //   MEDIUM — no keyword/token, but prose words match indexed symbol-name
+            //            SEGMENTS ("state machine" → OrderStateMachine, in any
+            //            language): inject a short list of the matching symbols and
+            //            let the AGENT write the explore query — the graph-derived
+            //            tier, no vocabulary involved.
+            //   silent — nothing verified. Every other prompt ("fix this typo")
+            //            stays a zero-cost no-op.
+            // Keywords fire on their own; a token or prose word is only a CANDIDATE
+            // verified against the graph below, so a tech brand ("JavaScript") that
+            // merely looks like code doesn't inject spurious context.
             const keyworded = (0, directory_1.hasStructuralKeyword)(prompt);
             const codeTokens = keyworded ? [] : (0, directory_1.extractCodeTokens)(prompt);
-            if (!keyworded && codeTokens.length === 0)
+            const proseWords = keyworded ? [] : (0, identifier_segments_1.extractProseCandidates)(prompt);
+            if (!keyworded && codeTokens.length === 0 && proseWords.length === 0) {
+                gate('noop-shape');
                 return;
+            }
             // Decide what to inject, shaped by WHERE the index(es) are: the nearest
             // indexed ancestor of cwd, or — when cwd is an un-indexed workspace root
             // whose indexed project(s) live in sub-dirs (the monorepo case, #964) —
@@ -1016,8 +1152,10 @@ function main() {
             // root (it only walked up), so the validated adoption lever never fired
             // exactly where the agent most needs it.
             const plan = (0, directory_1.planFrontload)(String(input.cwd || process.cwd()), prompt);
-            if (!plan.exploreRoot && plan.nudgeProjects.length === 0)
-                return; // nothing reachable — the agent's normal tools apply
+            if (!plan.exploreRoot && plan.nudgeProjects.length === 0) {
+                gate('noop-no-index');
+                return;
+            } // nothing reachable — the agent's normal tools apply
             // A "pass projectPath" line for indexed sub-projects we did NOT front-load.
             // Follow-up codegraph_explore calls against a sub-project (cwd isn't its
             // index root) need an explicit projectPath, so spell it out.
@@ -1026,30 +1164,72 @@ function main() {
                 const { default: CodeGraph } = await loadCodeGraph();
                 const cg = await CodeGraph.open(plan.exploreRoot);
                 try {
-                    // Code-token-only prompt: require that at least one token is a REAL symbol
-                    // in THIS index before front-loading. Without it, a brand name or common
-                    // word that merely looks like code ("JavaScript", "GitHub") would run
-                    // explore and inject ~16KB of low-relevance context (issue #994 follow-up).
-                    // A keyword-bearing prompt skips this — the keyword is signal enough.
-                    if (!keyworded && !codeTokens.some((t) => cg.getNodesByName(t).length > 0))
+                    const others = plan.nudgeProjects.length
+                        ? `\n${nudge(plan.nudgeProjects, 'Other indexed projects in this workspace — pass projectPath to query them:')}`
+                        : '';
+                    // Tier decision against THIS index (issue #994 follow-up: candidates
+                    // must be real here — a brand name or prose about another domain
+                    // must not inject). Keyword-bearing prompts skip verification — the
+                    // keyword is signal enough.
+                    const tokenVerified = !keyworded && codeTokens.some((t) => cg.getNodesByName(t).length > 0);
+                    if (keyworded || tokenVerified) {
+                        const { ToolHandler } = await Promise.resolve().then(() => __importStar(require('../mcp/tools')));
+                        const handler = new ToolHandler(cg);
+                        const result = await handler.execute('codegraph_explore', { query: prompt });
+                        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 codegraph_explore for the rest)` : text;
+                            // For a front-loaded SUB-project, a follow-up explore needs its path.
+                            const more = plan.viaSubScan
+                                ? `call codegraph_explore with projectPath: "${plan.exploreRoot}" for more`
+                                : 'call codegraph_explore for more';
+                            process.stdout.write(`<codegraph_context note="Structural context from CodeGraph for this prompt — treat returned source as already read; ${more}.">\n${body}${others}\n</codegraph_context>\n`);
+                            gate(keyworded ? 'high-keyword' : 'high-token');
+                        }
+                        else {
+                            // A high-* outcome must mean context was actually delivered —
+                            // the funnel's noop-vs-high split is how gate recall is
+                            // measured (#1143). An explore error or empty result is a
+                            // delivery failure, not a gate success.
+                            gate(keyworded ? 'noop-explore-keyword' : 'noop-explore-token');
+                        }
+                        return;
+                    }
+                    // MEDIUM: prose words → symbol-name segments, co-occurrence/rarity
+                    // scored, each hit re-verified to exist (see getSegmentMatches). The
+                    // payload names the symbols but does NOT run explore — the agent owns
+                    // the query where the hook's confidence is only "these are related".
+                    //
+                    // A database indexed before the vocab table existed starts with it
+                    // EMPTY, and only sync() backfills it — which this hook never runs
+                    // (#1142). Heal it here: on a populated vocab this is one SELECT;
+                    // the actual backfill is a one-time batched pass whose cost the MCP
+                    // server's own catch-up sync usually pays first (it runs at every
+                    // session start). A distinct noop outcome keeps a dormant vocab
+                    // from polluting the noop-unverified recall signal.
+                    const vocabReady = await cg.healSegmentVocabIfEmpty().catch(() => false);
+                    if (!vocabReady) {
+                        gate('noop-vocab-empty');
+                        return;
+                    }
+                    const related = cg.getSegmentMatches(proseWords);
+                    if (related.length === 0) {
+                        gate('noop-unverified');
                         return;
-                    const { ToolHandler } = await Promise.resolve().then(() => __importStar(require('../mcp/tools')));
-                    const handler = new ToolHandler(cg);
-                    const result = await handler.execute('codegraph_explore', { query: prompt });
-                    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 codegraph_explore for the rest)` : text;
-                        // For a front-loaded SUB-project, a follow-up explore needs its path.
-                        const more = plan.viaSubScan
-                            ? `call codegraph_explore with projectPath: "${plan.exploreRoot}" for more`
-                            : 'call codegraph_explore for more';
-                        const others = plan.nudgeProjects.length
-                            ? `\n${nudge(plan.nudgeProjects, 'Other indexed projects in this workspace — pass projectPath to query them:')}`
-                            : '';
-                        process.stdout.write(`<codegraph_context note="Structural context from CodeGraph for this prompt — treat returned source as already read; ${more}.">\n${body}${others}\n</codegraph_context>\n`);
                     }
+                    const lines = related
+                        .map((m) => `  - ${m.name} (${m.kind} — ${m.filePath}:${m.startLine})`)
+                        .join('\n');
+                    const exampleQuery = related.slice(0, 3).map((m) => m.name).join(' ');
+                    const projectHint = plan.viaSubScan ? ` with projectPath: "${plan.exploreRoot}"` : '';
+                    process.stdout.write(`<codegraph_context note="CodeGraph found indexed symbols matching this prompt — query the graph before searching files.">\n` +
+                        `This project's CodeGraph index contains symbols matching this request:\n${lines}\n` +
+                        `Call codegraph_explore ONCE${projectHint} with the relevant names in one query (e.g. "${exampleQuery}") ` +
+                        `to get their source, call paths, and blast radius — cheaper and more complete than Read/Grep.\n${others}` +
+                        `</codegraph_context>\n`);
+                    gate('medium-segment');
                 }
                 finally {
                     cg.destroy();
@@ -1061,6 +1241,7 @@ function main() {
                 process.stdout.write(`<codegraph_context note="CodeGraph is available for this workspace's indexed sub-projects — query one by passing projectPath to codegraph_explore.">\n` +
                     nudge(plan.nudgeProjects, "This workspace's CodeGraph indexes live in sub-projects. To use CodeGraph, call codegraph_explore with the projectPath of the relevant one:") +
                     `</codegraph_context>\n`);
+                gate('nudge-projects');
             }
         }
         catch {
@@ -1068,14 +1249,17 @@ function main() {
         }
     });
     /**
-     * codegraph node <name>
+     * codegraph node [name]
      *
      * The CLI face of the MCP codegraph_node tool: one symbol's source +
      * caller/callee trail, or a whole file with line numbers + dependents
      * (Read-parity). Same subagent/non-MCP rationale as `explore`.
+     *
+     * `name` is OPTIONAL because `--file` (file-read mode) carries no symbol —
+     * a required `<name>` made `codegraph node -f <file>` unreachable (#1044).
      */
     program
-        .command('node <name>')
+        .command('node [name]')
         .description('One symbol\'s source + caller/callee trail, or read a file with line numbers + dependents (same output as the codegraph_node MCP tool)')
         .option('-p, --path <path>', 'Project path')
         .option('-f, --file <file>', 'Treat as file mode (or disambiguate a symbol to this file)')
@@ -1083,6 +1267,13 @@ function main() {
         .option('--limit <number>', 'File mode: maximum lines')
         .option('--symbols-only', 'File mode: just the symbol map + dependents')
         .action(async (name, options) => {
+        // Need a symbol (positional) OR a file (--file / a path-like positional).
+        // With [name] optional, a bare `codegraph node` reaches here with neither
+        // and must be told what to pass, rather than crashing downstream.
+        if (!name && !options.file) {
+            error("Pass a symbol name (e.g. 'codegraph node parseToken') or a file (e.g. 'codegraph node -f src/auth.ts', or 'codegraph node src/auth.ts').");
+            process.exit(1);
+        }
         const projectPath = resolveProjectPath(options.path);
         try {
             if (!(0, directory_1.isInitialized)(projectPath)) {
@@ -1104,10 +1295,10 @@ function main() {
                 if (name && name !== options.file)
                     args.symbol = name;
             }
-            else if (name.includes('/') || name.includes('\\')) {
+            else if (name && (name.includes('/') || name.includes('\\'))) {
                 args.file = name.replace(/\\/g, '/');
             }
-            else {
+            else if (name) {
                 args.symbol = name;
                 args.includeCode = true;
             }
@@ -1851,6 +2042,7 @@ function main() {
         .option('-y, --yes', 'Non-interactive: defaults to --location=global --target=auto, auto-allow on')
         .option('--no-permissions', 'Skip writing the auto-allow permissions list (Claude Code only)')
         .option('--print-config <id>', 'Print MCP config snippet for the named agent and exit (no file writes)')
+        .option('--refresh', 'Rewrite what previous installs configured, for already-configured agents only (never adds new ones). Run automatically by `codegraph upgrade`')
         .action(async (opts) => {
         if (opts.printConfig) {
             const { getTarget, listTargetIds } = await Promise.resolve().then(() => __importStar(require('../installer/targets/registry')));
@@ -1864,6 +2056,36 @@ function main() {
             process.stdout.write(target.printConfig(loc));
             return;
         }
+        // --refresh: non-interactive sweep that re-writes what previous
+        // installs configured (instructions section, MCP entry, legacy-hook
+        // cleanups) for already-configured agents, so those surfaces match
+        // THIS binary's templates. Skips everything else — never a first
+        // install, never touches permissions or the prompt hook. Sweeps both
+        // locations unless --location narrows it.
+        if (opts.refresh) {
+            const { refreshTargets } = await Promise.resolve().then(() => __importStar(require('../installer')));
+            const { ALL_TARGETS } = await Promise.resolve().then(() => __importStar(require('../installer/targets/registry')));
+            if (opts.location && opts.location !== 'global' && opts.location !== 'local') {
+                error(`--location must be "global" or "local" (got "${opts.location}").`);
+                process.exit(1);
+            }
+            const locs = opts.location
+                ? [opts.location]
+                : ['global', 'local'];
+            let changed = 0;
+            for (const loc of locs) {
+                for (const report of refreshTargets(ALL_TARGETS, loc)) {
+                    for (const p of report.changedPaths) {
+                        changed += 1;
+                        console.log(`  ${report.displayName}: refreshed ${p}`);
+                    }
+                }
+            }
+            if (changed === 0) {
+                console.log('All configured agent surfaces are already current.');
+            }
+            return;
+        }
         const { runInstallerWithOptions } = await Promise.resolve().then(() => __importStar(require('../installer')));
         if (opts.location && opts.location !== 'global' && opts.location !== 'local') {
             error(`--location must be "global" or "local" (got "${opts.location}").`);
@@ -1908,6 +2130,7 @@ function main() {
         .option('-t, --target <ids>', 'Target agent(s): comma-separated ids, or "all". Default: all')
         .option('-l, --location <where>', 'Uninstall location: "global" or "local". Default: prompt')
         .option('-y, --yes', 'Non-interactive: defaults to --location=global --target=all')
+        .option('--keep-cli', 'Remove agent configs only — leave the codegraph CLI installed')
         .action(async (opts) => {
         const { runUninstaller } = await Promise.resolve().then(() => __importStar(require('../installer')));
         if (opts.location && opts.location !== 'global' && opts.location !== 'local') {
@@ -1919,6 +2142,8 @@ function main() {
                 target: opts.target,
                 location: opts.location,
                 yes: opts.yes,
+                keepCli: opts.keepCli,
+                cliFilename: __filename,
             });
         }
         catch (err) {
@@ -1990,6 +2215,7 @@ function main() {
             method,
             resolveLatest: () => up.resolveLatestVersion(),
             run: up.defaultRun,
+            capture: up.defaultCapture,
             hasCommand: up.hasCommand,
             log: (m) => console.log(m),
             warn: (m) => warn(m),