graph-indexer 3.0.0 → 3.1.0

package/src/cli/hook.mjs

@@ -29,10 +29,10 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { findRepoRoot, dataDir, DATA_DIR_NAME } from '../util/paths.mjs';
-import { specForPath } from '../parse/languages.mjs';
+import { findRepoRoot, dataDir, DATA_DIR_NAME, readRepoFile } from '../util/paths.mjs';
+import { codeSpecForPath as specForPath } from '../parse/languages.mjs'; // hooks report on code files only
 
 const MAX_CONTEXT = 1500;
 const EDIT_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit', 'edit', 'write', 'apply_patch', 'replace', 'write_file']);
@@ -78,30 +78,88 @@ function responseText(input) {
 /** Navigation calls since the last edit and definitions already shown, per session (crawl detector). */
 function sessionState(input) {
     const id = String(input.session_id ?? input.sessionId ?? input.conversation_id ?? 'default').replace(/[^\w.-]/g, '_').slice(0, 80);
-    const file = path.join(os.tmpdir(), 'graph-indexer-hooks', `${id}.json`);
+    // a per-user directory closed to others: in a shared temp dir another user could otherwise read
+    // the state or plant links that the next save writes through
+    const dir = path.join(os.tmpdir(), `graph-indexer-hooks-${process.getuid?.() ?? 'user'}`);
+    const file = path.join(dir, `${id}.json`);
+    const privateDir = () => {
+        if (process.platform === 'win32') return true;
+        try { const d = fs.lstatSync(dir); return d.isDirectory() && d.uid === process.getuid() && (d.mode & 0o077) === 0; } catch { return false; }
+    };
     let st = { nav: 0, shown: [] };
-    try { st = { ...st, ...JSON.parse(fs.readFileSync(file, 'utf8')) }; } catch { /* first call */ }
+    try { if (privateDir() && fs.lstatSync(file).isFile()) st = { ...st, ...JSON.parse(fs.readFileSync(file, 'utf8')) }; } catch { /* first call */ }
     return {
         st,
         save() {
             try {
-                fs.mkdirSync(path.dirname(file), { recursive: true });
+                fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+                if (!privateDir()) return;
                 st.shown = st.shown.slice(-400);
-                fs.writeFileSync(file, JSON.stringify(st));
+                const tmp = `${file}.${process.pid}.tmp`;
+                fs.writeFileSync(tmp, JSON.stringify(st), { flag: 'wx', mode: 0o600 });
+                fs.renameSync(tmp, file);
             } catch { /* optional */ }
         },
     };
 }
 
+/**
+ * The commands of a shell line, split at `;`, `&&`, `||` and newlines outside quotes, with heredoc
+ * bodies dropped and `cd DIR` steps left out (agents write `cd repo; sed -n …; grep …`).
+ */
+export function shellSegments(command) {
+    return splitShell(command).filter(x => !/^cd\s+\S+$/.test(x));
+}
+
+function splitShell(command) {
+    const src = String(command ?? '');
+    const out = [];
+    let cur = '', q = null;
+    const lines = src.split('\n');
+    for (let li = 0; li < lines.length; li++) {
+        const line = lines[li];
+        for (let i = 0; i < line.length; i++) {
+            const ch = line[i];
+            if (q) { cur += ch; if (ch === q) q = null; else if (ch === '\\' && q === '"' && i + 1 < line.length) cur += line[++i]; continue; }
+            if (ch === '"' || ch === "'") { q = ch; cur += ch; continue; }
+            if (ch === '\\' && i + 1 < line.length) { cur += ch + line[++i]; continue; }
+            if (ch === ';' || (ch === '&' && line[i + 1] === '&') || (ch === '|' && line[i + 1] === '|')) {
+                out.push(cur); cur = '';
+                if (ch !== ';') i++;
+                continue;
+            }
+            cur += ch;
+        }
+        if (q) { cur += '\n'; continue; } // a quoted string spanning lines
+        // a heredoc (`<<'EOF'`): skip its body up to the delimiter
+        const hd = /<<-?\s*['"]?(\w+)['"]?/.exec(cur);
+        out.push(cur); cur = '';
+        if (hd) while (li + 1 < lines.length && lines[li + 1].trim() !== hd[1]) li++;
+        if (hd) li++;
+    }
+    if (cur) out.push(cur);
+    return out.map(x => x.trim()).filter(Boolean);
+}
+
 /** A file read through the shell: [file, from, to] for `sed -n 'a,bp' f`, `head -n N f`, `cat f`, `nl -ba f | sed -n …`. */
 export function shellRead(command) {
-    const c = String(command ?? '').replace(/^\s*cd\s+\S+\s*&&\s*/, '');
-    let m;
-    if ((m = /^(?:nl\s+-ba\s+|cat\s+-n\s+)(\S+)\s*\|\s*sed\s+-n\s+['"]?(\d+),(\d+)p['"]?\s*$/.exec(c))) return [m[1], +m[2], +m[3]];
-    if ((m = /^sed\s+-n\s+['"]?(\d+),(\d+)p['"]?\s+(\S+)\s*$/.exec(c))) return [m[3], +m[1], +m[2]];
-    if ((m = /^head\s+-(?:n\s*)?(\d+)\s+(\S+)\s*$/.exec(c))) return [m[2], 1, +m[1]];
-    if ((m = /^cat\s+(?:-n\s+)?(\S+\.\w+)\s*$/.exec(c))) return [m[1], 1, 2000];
-    return null;
+    return shellReads(command)[0] ?? null;
+}
+
+/** Every file read in a shell line (`cd repo; sed -n 10,40p a.py; sed -n 5,9p b.py`), relative paths resolved against a `cd` before them. */
+export function shellReads(command) {
+    const out = [];
+    let dir = null;
+    const at = (f) => (dir && !path.isAbsolute(f) ? path.join(dir, f) : f);
+    for (const c of splitShell(command)) {
+        let m;
+        if ((m = /^cd\s+(['"]?)(\S+)\1$/.exec(c))) { dir = path.isAbsolute(m[2]) ? m[2] : path.join(dir ?? '', m[2]); continue; }
+        if ((m = /^(?:nl\s+-ba\s+|cat\s+-n\s+)(\S+)\s*\|\s*sed\s+-n\s+['"]?(\d+),(\d+)p['"]?\s*$/.exec(c))) out.push([at(m[1]), +m[2], +m[3]]);
+        else if ((m = /^sed\s+-n\s+['"]?(\d+),(\d+)p['"]?\s+(\S+)\s*$/.exec(c))) out.push([at(m[3]), +m[1], +m[2]]);
+        else if ((m = /^head\s+-(?:n\s*)?(\d+)\s+(\S+)\s*$/.exec(c))) out.push([at(m[2]), 1, +m[1]]);
+        else if ((m = /^cat\s+(?:-n\s+)?(\S+\.\w+)\s*$/.exec(c))) out.push([at(m[1]), 1, 2000]);
+    }
+    return out;
 }
 
 /** Minimal shell-words split (quotes and escapes) for extracting a grep pattern. */
@@ -148,17 +206,20 @@ function localIndex(root) {
     };
 }
 
-async function afterEdit(root, input, acquire) {
-    const file = input.tool_input?.file_path ?? input.tool_input?.notebook_path ?? input.tool_input?.path ?? null;
-    if (!file) return null;
-    const rel = path.isAbsolute(file) ? path.relative(root, file).split(path.sep).join('/') : file;
-    if (rel.startsWith('..') || !specForPath(rel)) return null;
+async function afterEdit(root, input, acquire, files = null) {
+    if (!files) {
+        const file = input.tool_input?.file_path ?? input.tool_input?.notebook_path ?? input.tool_input?.path ?? null;
+        if (!file) return null;
+        files = [path.isAbsolute(file) ? path.relative(root, file).split(path.sep).join('/') : file];
+    }
+    files = files.filter(rel => !rel.startsWith('..') && specForPath(rel)).slice(0, 6);
+    if (!files.length) return null;
     const ix = await acquire();
     if (!ix) return null;
     const { intel } = ix;
     try {
         const { checkChanges } = await import('../query/check.mjs');
-        const r = await checkChanges(intel, { files: [rel], tests: false });
+        const r = await checkChanges(intel, { files, tests: false });
         if (r.error) return null;
         const lines = [];
         for (const e of r.syntax.slice(0, 3)) lines.push(`${e.path}:${e.line} has a syntax error introduced since the last commit (${e.missing ? `missing ${e.missing}` : 'unexpected code'}): ${e.text.slice(0, 100)}`);
@@ -225,51 +286,73 @@ async function afterGrep(root, input, crawling, acquire) {
  * silent when there is none; and while the agent is crawling, where the names the lines use are defined.
  */
 async function afterRead(root, input, state, crawling, acquire) {
-    let file = null, from = 1, to = 2000;
+    let reads = [];
     if (READ_TOOLS.has(input.tool_name)) {
-        file = input.tool_input?.file_path ?? input.tool_input?.path ?? input.tool_input?.absolute_path ?? null;
+        const file = input.tool_input?.file_path ?? input.tool_input?.path ?? input.tool_input?.absolute_path ?? null;
+        let from = 1, to = 2000;
         const off = Number(input.tool_input?.offset ?? 0), lim = Number(input.tool_input?.limit ?? 0);
         if (off > 0) from = off;
         if (lim > 0) to = from + lim - 1;
-    } else {
-        const r = shellRead(input.tool_input?.command);
-        if (!r) return null;
-        [file, from, to] = r;
-    }
-    if (!file) return null;
+        if (file) reads = [[file, from, to]];
+    } else reads = shellReads(input.tool_input?.command);
     const cwd = input.cwd || root;
-    const abs = path.isAbsolute(file) ? file : path.join(cwd, file);
-    const rel = path.relative(root, abs).split(path.sep).join('/');
-    if (rel.startsWith('..') || !specForPath(rel)) return null;
+    const ranges = reads.map(([file, from, to]) => {
+        const abs = path.isAbsolute(file) ? file : path.join(cwd, file);
+        return { rel: path.relative(root, abs).split(path.sep).join('/'), from, to };
+    }).filter(r => !r.rel.startsWith('..') && specForPath(r.rel)).slice(0, 4);
+    if (!ranges.length) return null;
     const ix = await acquire();
     if (!ix) return null;
     const { intel } = ix;
     try {
-        await intel.revalidate([rel]); // a long-lived index may not have seen the file change yet
-        const out = [];
+        await intel.revalidate([...new Set(ranges.map(r => r.rel))]); // a long-lived index may not have seen the file change yet
+        const facts = [], defs = [];
         const { factsForRange, renderFacts } = await import('../query/facts.mjs');
+        const { definitionsUsed } = await import('../query/read.mjs');
         state.st.facts ??= [];
-        const facts = factsForRange(intel, rel, from, to, { max: 4, shown: new Set(state.st.facts) });
-        if (facts.length) {
-            for (const f of facts) state.st.facts.push(f.key);
-            out.push(`graph-indexer, resolved for these lines:\n${renderFacts(facts).map(l => `  ${l}`).join('\n')}`);
-        }
-        if (crawling) {
-            const { definitionsUsed } = await import('../query/read.mjs');
-            const n = Math.max(1, to - from + 1);
-            const { rows } = definitionsUsed(intel, rel, from, to, { max: Math.min(12, Math.max(4, Math.round(n / 15))), skipIds: new Set(state.st.shown) });
-            for (const r of rows) state.st.shown.push(r.id);
-            if (rows.length) out.push(`graph-indexer: where names used in these lines are defined (read them directly instead of searching):\n${rows.map(r => `  ${r.qname} → ${r.path}:${r.start_line}  ${String(r.sig || r.kind).replace(/\s+/g, ' ').replace(/\s+#.*$/, '').slice(0, 100)}`).join('\n')}`);
+        for (const { rel, from, to } of ranges) {
+            const fs1 = factsForRange(intel, rel, from, to, { max: Math.max(1, 4 - facts.length), shown: new Set(state.st.facts) });
+            for (const f of fs1) { state.st.facts.push(f.key); facts.push(f); }
+            if (crawling) {
+                const n = Math.max(1, to - from + 1);
+                const { rows } = definitionsUsed(intel, rel, from, to, { max: Math.min(12, Math.max(4, Math.round(n / 15))), skipIds: new Set(state.st.shown) });
+                for (const r of rows) { state.st.shown.push(r.id); if (defs.length < 12) defs.push(r); }
+            }
         }
+        const out = [];
+        if (facts.length) out.push(`graph-indexer, resolved for these lines:\n${renderFacts(facts).map(l => `  ${l}`).join('\n')}`);
+        if (defs.length) out.push(`graph-indexer: where names used in these lines are defined (read them directly instead of searching):\n${defs.map(r => `  ${r.qname} → ${r.path}:${r.start_line}  ${String(r.sig || r.kind).replace(/\s+/g, ' ').replace(/\s+#.*$/, '').slice(0, 100)}`).join('\n')}`);
         return out.length ? out.join('\n') : null;
     } finally { ix.release(); }
 }
 
+/**
+ * Source files a shell command changed (`sed -i`, a Python heredoc that rewrites a file, a patch):
+ * the working tree's modified and new files whose modification time moved since the hook last
+ * looked, so the edit checker also follows edits made without the edit tool.
+ */
+function shellEdits(root, state) {
+    let r;
+    try { r = spawnSync('git', ['-C', root, 'status', '--porcelain', '--untracked-files=all', '-z'], { encoding: 'utf8', timeout: 1500 }); } catch { return []; }
+    if (r.status !== 0 || typeof r.stdout !== 'string') return [];
+    const seen = state.st.mtimes ??= {};
+    const changed = [];
+    for (const e of r.stdout.split('\0')) {
+        if (e.length < 4 || e.startsWith('D') || e[1] === 'D') continue;
+        const rel = e.slice(3);
+        if (!specForPath(rel) || rel.startsWith(DATA_DIR_NAME + '/')) continue;
+        let m;
+        try { m = fs.statSync(path.join(root, rel)).mtimeMs; } catch { continue; }
+        if (seen[rel] !== m) { seen[rel] = m; changed.push(rel); }
+    }
+    return changed;
+}
+
 // the lookup rules, for sessions and subagents whose instruction files do not carry them
 const RULES = `How to look code up in this repository (graph-indexer):
 - Several things at once: several tool calls in one message, or one search with alternatives — not one search per turn.
 - The function or the 50–100 lines you need, not whole files; to find a definition, search for its definition line (\`def name\`, \`class Name\`) across the package in one search.
-- Exact uses of a function or class, even when other code shares its name: find_references (\`npx graph-indexer refs NAME\` in a shell). Before changing what other code relies on: change_impact; when you are done: check_changes, then run the tests it names, once.`;
+- Exact uses of a function or class, even when other code shares its name: find_references (\`npx -y --prefix / graph-indexer@3 refs NAME\` in a shell). Before changing what other code relies on: change_impact; when you are done: check_changes, then run the tests it names, once.`;
 
 async function sessionLine(root, { rules = false, acquire }) {
     if (!hasIndex(root)) return null; // being built in the background (spawnResident); say nothing yet
@@ -278,9 +361,9 @@ async function sessionLine(root, { rules = false, acquire }) {
     const { intel } = ix;
     try {
         const st = intel.stats();
-        const line = `graph-indexer has a live index of this repository (${st.files} files, ${st.symbols} symbols). Its MCP tools answer with exact locations: find_references (exact uses, even when other code shares the name), change_impact (what a change affects and which tests to run), check_changes (what an edit broke, and the closest tests), call_graph, read_code (symbols or ranges by name, with where each name they use is defined), search_text, search_code and outline.`;
+        const line = `graph-indexer has a live index of this repository (${st.files} files, ${st.symbols} symbols). Its MCP tools answer with exact locations: explore (the code relevant to a task, its callers, the definitions it uses and its tests, in one call), find_references (exact uses, even when other code shares the name), change_impact (what a change affects and which tests to run), check_changes (what an edit broke, and the closest tests), call_graph, read_code (symbols or ranges by name, with where each name they use is defined), search_text, search_code and outline.`;
         // the managed block of `init` already carries the rules; otherwise add them
-        const carried = ['CLAUDE.md', 'AGENTS.md'].some(f => { try { return fs.readFileSync(path.join(root, f), 'utf8').includes('<!-- graph-indexer:start -->'); } catch { return false; } });
+        const carried = ['CLAUDE.md', 'AGENTS.md'].some(f => (readRepoFile(root, f) ?? '').includes('<!-- graph-indexer:start -->'));
         return rules || !carried ? `${line}\n${RULES}` : line;
     } finally { ix.release(); }
 }
@@ -298,6 +381,7 @@ export async function handleHook(event, input, { root, acquire }) {
         const state = sessionState(input);
         if (EDIT_TOOLS.has(tool)) {
             state.st.nav = 0;
+            shellEdits(root, state); // so a later shell command does not report this edit again
             state.save();
             text = await afterEdit(root, input, acquire);
         } else if (GREP_TOOLS.has(tool) || (SHELL_TOOLS.has(tool) && grepPattern(command))) {
@@ -308,6 +392,12 @@ export async function handleHook(event, input, { root, acquire }) {
             state.st.nav++;
             text = await afterRead(root, input, state, state.st.nav >= CRAWL, acquire);
             state.save();
+        } else if (SHELL_TOOLS.has(tool)) {
+            // any other command may have edited files (`sed -i`, a script): check what it changed
+            const changed = shellEdits(root, state);
+            if (changed.length) state.st.nav = 0;
+            state.save();
+            if (changed.length) text = await afterEdit(root, input, acquire, changed);
         }
     } else if (event === 'session-start' || event === 'subagent-start') {
         name ??= event === 'session-start' ? 'SessionStart' : 'SubagentStart';
@@ -341,7 +431,9 @@ export async function runHook(event, { repo = null, version = null } = {}) {
     const timer = setTimeout(() => process.exit(0), deadlineMs); // fail open: never hold the agent up
     try {
         const input = await readStdin();
-        const root = findRepoRoot(input.cwd || repo || process.cwd());
+        // an explicit --repo wins over the session's directory (a session started elsewhere, with
+        // the repository added to it)
+        const root = findRepoRoot(repo || input.cwd || process.cwd());
         const { askResident, residentRequired } = await import('./resident.mjs');
         const reply = await askResident(root, { op: 'hook', event, input }, { version, totalMs: 2000 });
         let out = null;

package/src/cli/init.mjs

@@ -26,6 +26,8 @@ const SNIPPET = `${BLOCK_START}
 - Check once: run the tests that cover your change when you are done; do not re-run a check nothing has changed.
 
 The \`graph-indexer\` MCP server answers what a text search cannot answer exactly:
+- Fixing an issue or bug report: make your first call \`explore\` with the names and terms the issue uses (or its text as written). It ranks the code where the names the issue uses meet (usually what you will change) and shows it with its callers, the definitions it uses and the tests to run; read further only what it leaves out.
+- Starting on any other task in code you have not read: \`explore\` with the task in words.
 - Uses of a function, method or class that other code shares a name with: \`find_references\` (exact call sites, says when the list is complete; kind \`inherit\` for subclasses and implementations). Callers of callers: \`call_graph\`.
 - Before changing a signature other code relies on: \`change_impact\`; after: \`check_changes\`.
 ${BLOCK_END}`;
@@ -52,13 +54,17 @@ function readJson(p) {
     try { return JSON.parse(fs.readFileSync(p, 'utf8').replace(/^\s*\/\/.*$/gm, '')); } catch { return null; }
 }
 
+// --prefix /: npx would otherwise run a graph-indexer 3.x found in the repository's own node_modules
+// (code the repository ships) instead of the published package
+const NPX_ARGS = ['-y', '--prefix', '/', 'graph-indexer@3'];
+
 function serverEntry(agent, { local }) {
     const here = path.dirname(fileURLToPath(import.meta.url));
     const bin = path.resolve(here, '../../bin/graph-indexer.mjs');
     const repoArgs = agent.workspaceVar ? ['--repo', agent.workspaceVar] : [];
     const base = local
         ? { command: process.execPath, args: [bin, 'serve', ...repoArgs] }
-        : { command: 'npx', args: ['-y', 'graph-indexer@3', 'serve', ...repoArgs] };
+        : { command: 'npx', args: [...NPX_ARGS, 'serve', ...repoArgs] };
     if (agent.opencode) return { type: 'local', command: [base.command, ...base.args], enabled: true };
     if (agent.zed) return { ...base, env: {} };
     return agent.vscode ? { type: 'stdio', ...base } : base;
@@ -70,7 +76,24 @@ function configFile(agent, repo) {
     return agent.file;
 }
 
-function upsertBlock(file, dryRun) {
+/**
+ * Write `file` under `repo` without following a link the repository committed (`CLAUDE.md` →
+ * ~/.zshrc, `.claude` → ~/.claude): such a target is refused instead of written through.
+ */
+function writeInRepo(repo, file, content) {
+    const rootReal = fs.realpathSync(repo);
+    const inside = (p) => { const r = fs.realpathSync(p); return r === rootReal || r.startsWith(rootReal + path.sep); };
+    let dir = path.dirname(file);
+    while (!fs.existsSync(dir)) dir = path.dirname(dir);
+    let link = false;
+    try { link = fs.lstatSync(file).isSymbolicLink(); } catch { /* a new file */ }
+    if (link || !inside(dir)) throw new Error(`${path.relative(repo, file)} leads outside the repository (a symbolic link); not written`);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    if (!inside(path.dirname(file))) throw new Error(`${path.relative(repo, file)} leads outside the repository (a symbolic link); not written`);
+    fs.writeFileSync(file, content);
+}
+
+function upsertBlock(repo, file, dryRun) {
     const exists = fs.existsSync(file);
     const text = exists ? fs.readFileSync(file, 'utf8') : '';
     let next;
@@ -80,7 +103,7 @@ function upsertBlock(file, dryRun) {
         next = (text.trimEnd() ? text.trimEnd() + '\n\n' : '') + SNIPPET + '\n';
     }
     if (next === text) return 'unchanged';
-    if (!dryRun) fs.writeFileSync(file, next);
+    if (!dryRun) writeInRepo(repo, file, next);
     return exists ? 'updated' : 'created';
 }
 
@@ -100,7 +123,7 @@ function cliCommand(local) {
     const bin = path.resolve(here, '../../bin/graph-indexer.mjs');
     if (local) return `${JSON.stringify(process.execPath)} ${JSON.stringify(bin)}`;
     const installed = installedBin();
-    return installed ? JSON.stringify(installed) : 'npx -y graph-indexer@3';
+    return installed ? JSON.stringify(installed) : ['npx', ...NPX_ARGS].join(' ');
 }
 
 /** The command that starts graph-indexer, as an argv array (for the OpenCode/Kilo Code plugin). */
@@ -108,7 +131,7 @@ function cliArgv(local) {
     const here = path.dirname(fileURLToPath(import.meta.url));
     if (local) return [process.execPath, path.resolve(here, '../../bin/graph-indexer.mjs')];
     const installed = installedBin();
-    return installed ? [installed] : ['npx', '-y', 'graph-indexer@3'];
+    return installed ? [installed] : ['npx', ...NPX_ARGS];
 }
 
 /**
@@ -128,8 +151,7 @@ function writeOpenCodePlugin(repo, local, dryRun) {
         const file = path.join(repo, rel);
         const same = fs.existsSync(file) && fs.readFileSync(file, 'utf8') === src;
         if (!same && !dryRun) {
-            fs.mkdirSync(path.dirname(file), { recursive: true });
-            fs.writeFileSync(file, src);
+            writeInRepo(repo, file, src);
         }
         out.push(`${same ? 'already in' : 'written to'} ${rel}`);
     }
@@ -160,8 +182,7 @@ function upsertClaudeHooks(repo, local, dryRun) {
     }
     const changed = before !== JSON.stringify(cfg.hooks);
     if (changed && !dryRun) {
-        fs.mkdirSync(path.dirname(file), { recursive: true });
-        fs.writeFileSync(file, JSON.stringify(cfg, null, 2) + '\n');
+        writeInRepo(repo, file, JSON.stringify(cfg, null, 2) + '\n');
     }
     return `Claude Code hooks: ${changed ? 'written to' : 'already in'} .claude/settings.json (post-edit check, grep disambiguation, session line)`;
 }
@@ -178,8 +199,7 @@ function upsertClaudeHelper(repo, dryRun) {
     if (have === want) return `Claude Code: structural helper already in ${rel}`;
     if (have != null && !have.includes("graph-indexer's index")) return `Claude Code: ${rel} exists and is not graph-indexer's, so it was left as is`;
     if (!dryRun) {
-        fs.mkdirSync(path.dirname(file), { recursive: true });
-        fs.writeFileSync(file, want);
+        writeInRepo(repo, file, want);
     }
     return `Claude Code: structural helper ${have == null ? 'written to' : 'updated in'} ${rel} (a sub-agent on a small model that answers call-site, caller, subclass and impact questions from the index)`;
 }
@@ -191,6 +211,7 @@ export async function runInit({ opt, flag, repo: repoArg = null }) {
     const hooks = flag('--hooks');
     const noInstructions = flag('--no-instructions');
     const noHelper = flag('--no-helper');
+    const noDemo = flag('--no-demo');
     const all = flag('--all');
     const agentList = opt('--agents');
     let chosen;
@@ -221,8 +242,7 @@ export async function runInit({ opt, flag, repo: repoArg = null }) {
             cfg[a.key]['graph-indexer'] = entry;
             const changed = before !== JSON.stringify(entry);
             if (changed && !dryRun) {
-                fs.mkdirSync(path.dirname(file), { recursive: true });
-                fs.writeFileSync(file, JSON.stringify(cfg, null, 2) + '\n');
+                writeInRepo(repo, file, JSON.stringify(cfg, null, 2) + '\n');
             }
             report.push(`${a.label}: ${changed ? (before === 'null' ? 'added' : 'updated') : 'already configured'} ${rel}`);
         } else if (key === 'codex') {
@@ -239,17 +259,29 @@ export async function runInit({ opt, flag, repo: repoArg = null }) {
     if (hooks && chosen.includes('opencode')) report.push(writeOpenCodePlugin(repo, local, dryRun));
     if (!noInstructions) {
         const targets = [...new Set(chosen.map(k => AGENTS[k].instructions))];
-        for (const t of targets) report.push(`${t}: ${upsertBlock(path.join(repo, t), dryRun)} graph-indexer instructions block`);
+        for (const t of targets) report.push(`${t}: ${upsertBlock(repo, path.join(repo, t), dryRun)} graph-indexer instructions block`);
     }
     // keep the index out of version control
     const gi = path.join(repo, '.gitignore');
     const giText = fs.existsSync(gi) ? fs.readFileSync(gi, 'utf8') : '';
     if (!/^\/?\.graph-indexer\/?$/m.test(giText)) {
-        if (!dryRun) fs.writeFileSync(gi, (giText.trimEnd() ? giText.trimEnd() + '\n' : '') + '.graph-indexer/\n');
+        if (!dryRun) writeInRepo(repo, gi, (giText.trimEnd() ? giText.trimEnd() + '\n' : '') + '.graph-indexer/\n');
         report.push('.gitignore: added .graph-indexer/');
     }
     process.stdout.write(`graph-indexer init ${dryRun ? '(dry run) ' : ''}in ${repo}\n  ${report.join('\n  ')}\n\n` +
-        `Other agents (Claude Desktop, JetBrains AI Assistant, Cline): add an MCP server with command "npx" and args ["-y","graph-indexer@3","serve","--repo","${repo}"].\n` +
-        `Build the index now with: npx graph-indexer index   (the server also builds it on first start)\n` +
+        `Other agents (Claude Desktop, JetBrains AI Assistant, Cline): add an MCP server with command "npx" and args ${JSON.stringify([...NPX_ARGS, 'serve', '--repo', repo])}.\n` +
+        (dryRun || noDemo ? `Build the index now with: npx ${NPX_ARGS.join(' ')} index   (the server also builds it on first start)\n` : '') +
         (hooks ? '' : `Optional: graph-indexer init --hooks adds Claude Code hooks (edit check after each edit, grep disambiguation).\n`));
+    if (dryRun || noDemo) return;
+    // build the index now (the server would on first start) and show what it answers here
+    const { CodeIntel } = await import('../query/intel.mjs');
+    const { showcaseText } = await import('../query/showcase.mjs');
+    const intel = new CodeIntel({ root: repo });
+    try {
+        let last = 0;
+        await intel.open({ onProgress: (d, n) => { const now = Date.now(); if (now - last > 1000 || d === n) { last = now; process.stderr.write(`\r[graph-indexer] indexing ${d}/${n} files`); if (d === n) process.stderr.write('\n'); } } });
+        process.stdout.write(`\n${await showcaseText(intel)}\n`);
+    } catch (e) {
+        process.stdout.write(`\nThe index could not be built now (${e.message}); the server builds it on first start.\n`);
+    } finally { intel.close(); }
 }

package/src/cli/resident.mjs

@@ -16,7 +16,7 @@
  *   { v, version, op: 'hook', event, input }     → { ok, out }   out: what the hook prints, or null
  *   { v, version, op: 'tool', calls }            → { ok, out }   out: the CLI's output text
  * A request from another graph-indexer version gets { ok: false } and the client falls back, except
- * from thin clients that only relay hooks (`any: true`, integrations/claude-code/hooks/gi-hook.mjs).
+ * from thin clients that only relay hooks (`any: true`, integrations/claude-code-local/hooks/gi-hook.mjs).
  *
  * The socket is only reachable by its owner: inside the repository's .graph-indexer/ directory,
  * or, when that path is too long for a Unix socket, in a per-user directory with mode 0700 that
@@ -44,15 +44,25 @@ export function socketPath(root) {
     return path.join(os.tmpdir(), `graph-indexer-${process.getuid?.() ?? 'user'}`, `${hash}.sock`);
 }
 
-/** A per-user directory in the temp dir must belong to us and be closed to everyone else. */
+const mine = (st) => (process.getuid ? st.uid === process.getuid() : true);
+
+/**
+ * The socket's directory must be a real directory of ours (not a link the repository committed);
+ * a per-user directory in the temp dir must also be closed to everyone else.
+ */
 function privateDir(dir, root) {
-    if (WIN || dir === path.join(path.resolve(root), DATA_DIR_NAME)) return true;
+    if (WIN) return true;
     try {
         const st = fs.lstatSync(dir);
-        return st.isDirectory() && (process.getuid ? st.uid === process.getuid() : true) && (st.mode & 0o077) === 0;
+        return st.isDirectory() && mine(st) && (dir === path.join(path.resolve(root), DATA_DIR_NAME) || (st.mode & 0o077) === 0);
     } catch { return false; }
 }
 
+/** A socket of ours, not a file or a listener someone else put there. */
+function ownSocket(file) {
+    try { const st = fs.lstatSync(file); return st.isSocket() && mine(st); } catch { return false; }
+}
+
 const disabled = () => process.env.GRAPH_INDEXER_RESIDENT === '0';
 /** GRAPH_INDEXER_RESIDENT=require: answer only through a resident, never by opening the index (tests, debugging). */
 export const residentRequired = () => process.env.GRAPH_INDEXER_RESIDENT === 'require';
@@ -64,7 +74,7 @@ export const residentRequired = () => process.env.GRAPH_INDEXER_RESIDENT === 're
 export function askResident(root, request, { version, connectMs = 250, totalMs = 5000 } = {}) {
     if (disabled()) return Promise.resolve(null);
     const file = socketPath(root);
-    if (!WIN && (!fs.existsSync(file) || !privateDir(path.dirname(file), root))) return Promise.resolve(null);
+    if (!WIN && (!ownSocket(file) || !privateDir(path.dirname(file), root))) return Promise.resolve(null);
     return new Promise((resolve) => {
         let done = false, connected = false, buf = '';
         const sock = net.createConnection(file);

package/src/index/discover.mjs

@@ -6,7 +6,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { spawnSync } from 'node:child_process';
+import { gitSync } from '../util/git.mjs';
 import { specForPath } from '../parse/languages.mjs';
 
 export const MAX_FILE_BYTES = 1_500_000;
@@ -24,14 +24,12 @@ const SKIP_DIRS = new Set([
 const GENERATED_FILE = /(\.min\.(js|css|mjs)$|\.bundle\.js$|[.-]bundle\.[cm]?js$|\.chunk\.js$|\.map$|\.pb\.go$|_pb2(_grpc)?\.py$|\.pb\.(cc|h)$|\.generated\.\w+$|\.g\.dart$|\.designer\.cs$|(^|\/)generated\/|\.d\.ts\.map$)/i;
 
 function isGitRepo(root) {
-    const r = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd: root, encoding: 'utf8' });
+    const r = gitSync(root, ['rev-parse', '--is-inside-work-tree']);
     return r.status === 0 && r.stdout.trim() === 'true';
 }
 
 function gitListFiles(root) {
-    const r = spawnSync('git', ['ls-files', '-z', '--cached', '--others', '--exclude-standard'], {
-        cwd: root, encoding: 'utf8', maxBuffer: 1 << 30,
-    });
+    const r = gitSync(root, ['ls-files', '-z', '--cached', '--others', '--exclude-standard'], { maxBuffer: 1 << 30 });
     if (r.status !== 0) return null;
     return r.stdout.split('\0').filter(Boolean);
 }