nexusmem 0.3.2 → 0.4.0

package/dist/cli/index.js

@@ -2,7 +2,7 @@
 
 // src/cli/index.ts
 import { Command } from "commander";
-import pc14 from "picocolors";
+import pc17 from "picocolors";
 
 // src/config/workspace.ts
 import { existsSync } from "fs";
@@ -147,7 +147,15 @@ var ConfigSchema = z.object({
       maxCommits: z.number().int().positive().default(200),
       maxFilesPerCommit: z.number().int().positive().default(20),
       contextLines: z.number().int().nonnegative().default(3)
-    }).default({ enabled: true, maxCommits: 200, maxFilesPerCommit: 20, contextLines: 3 })
+    }).default({ enabled: true, maxCommits: 200, maxFilesPerCommit: 20, contextLines: 3 }),
+    /**
+     * JS/TS import-graph edges (`file_edges` table), derived from the
+     * working tree. On by default like git/shell/docs: no secrets risk,
+     * just structural relationships between files already tracked in git.
+     */
+    structure: z.object({
+      enabled: z.boolean().default(true)
+    }).default({ enabled: true })
   }).default({
     git: { enabled: true, since: null, includeMerges: true },
     shell: { enabled: true, tailLines: 300 },
@@ -160,7 +168,8 @@ var ConfigSchema = z.object({
       maxPromptChars: 12e3
     },
     docs: { enabled: true, include: ["*.md"] },
-    diff: { enabled: true, maxCommits: 200, maxFilesPerCommit: 20, contextLines: 3 }
+    diff: { enabled: true, maxCommits: 200, maxFilesPerCommit: 20, contextLines: 3 },
+    structure: { enabled: true }
   }),
   limits: z.object({
     maxFilesPerNode: z.number().int().positive().default(40),
@@ -549,20 +558,165 @@ async function hookStatus(target) {
   return { installed: isHookInstalled(current) };
 }
 
-// src/cli/commands/hook.ts
+// src/hooks/install-git-precommit.ts
+import { chmod, mkdir as mkdir3, readFile as readFile3, unlink, writeFile as writeFile3 } from "fs/promises";
+import { dirname as dirname2, join as join4 } from "path";
+
+// src/hooks/git-pre-commit.ts
+var MARK_START2 = "# >>> nexusmem precommit hook >>>";
+var MARK_END2 = "# <<< nexusmem precommit hook <<<";
+var SHEBANG = "#!/bin/sh";
+function renderHookSnippet2() {
+  return [
+    MARK_START2,
+    "# Runs `nexusmem precheck` before each commit -- advisory only, never",
+    "# blocks a commit on its own (this hook does not pass --strict).",
+    "# Installed by: nexusmem hook git install",
+    "# Remove with:  nexusmem hook git remove",
+    "if command -v nexusmem >/dev/null 2>&1; then",
+    "  nexusmem precheck",
+    "fi",
+    MARK_END2,
+    ""
+  ].join("\n");
+}
+function isHookInstalled2(content) {
+  return content.includes(MARK_START2);
+}
+function isForeignHook(content) {
+  return content.trim().length > 0 && !isHookInstalled2(content);
+}
+function stripHookSnippet2(content) {
+  const startIdx = content.indexOf(MARK_START2);
+  const endIdx = content.indexOf(MARK_END2);
+  if (startIdx === -1 || endIdx === -1) return content;
+  const afterBlock = content.slice(endIdx + MARK_END2.length).replace(/^\r?\n/, "");
+  return content.slice(0, startIdx) + afterBlock;
+}
+function upsertHookSnippet2(content) {
+  const stripped = stripHookSnippet2(content).replace(/\s+$/, "");
+  const prefix = stripped.length > 0 ? `${stripped}
+
+` : "";
+  return `${prefix}${renderHookSnippet2()}`;
+}
+function ensureShebang(content) {
+  if (content.startsWith("#!")) return content;
+  return content.length > 0 ? `${SHEBANG}
+${content}` : `${SHEBANG}
+`;
+}
+
+// src/hooks/install-git-precommit.ts
+var ForeignGitHookError = class extends Error {
+  constructor(hookPath) {
+    super(
+      `${hookPath} already has a pre-commit hook NexusMem did not install. Pass --force to append nexusmem's check to the end of it, or integrate manually.`
+    );
+    this.hookPath = hookPath;
+    this.name = "ForeignGitHookError";
+  }
+  hookPath;
+};
+function resolveGitHookTarget(repoRoot) {
+  return { hookPath: join4(repoRoot, ".git", "hooks", "pre-commit") };
+}
+async function readHook(path) {
+  try {
+    return await readFile3(path, "utf8");
+  } catch {
+    return "";
+  }
+}
+async function installGitHook(target, opts = {}) {
+  const current = await readHook(target.hookPath);
+  const alreadyInstalled = isHookInstalled2(current);
+  const foreign = isForeignHook(current);
+  if (foreign && !alreadyInstalled && !opts.force) {
+    throw new ForeignGitHookError(target.hookPath);
+  }
+  const next = upsertHookSnippet2(ensureShebang(current));
+  if (next === current) return { changed: false, alreadyInstalled, appendedToForeign: false };
+  await mkdir3(dirname2(target.hookPath), { recursive: true });
+  await writeFile3(target.hookPath, next, "utf8");
+  await chmod(target.hookPath, 493).catch(() => {
+  });
+  return { changed: true, alreadyInstalled, appendedToForeign: foreign && !alreadyInstalled };
+}
+async function removeGitHook(target) {
+  const current = await readHook(target.hookPath);
+  if (!isHookInstalled2(current)) return { changed: false };
+  const stripped = stripHookSnippet2(current).trim();
+  if (stripped === "" || stripped === SHEBANG) {
+    await unlink(target.hookPath).catch(() => {
+    });
+  } else {
+    await writeFile3(target.hookPath, `${stripped}
+`, "utf8");
+  }
+  return { changed: true };
+}
+async function gitHookStatus(target) {
+  const current = await readHook(target.hookPath);
+  return { installed: isHookInstalled2(current), foreign: isForeignHook(current) };
+}
+
+// src/cli/commands/hook-git.ts
 import pc from "picocolors";
+async function runHookGitInstall(opts) {
+  const repo = await readRepoInfo(opts.cwd);
+  const target = resolveGitHookTarget(repo.root);
+  const result = await installGitHook(target, { force: opts.force });
+  const lines = [
+    result.changed ? `${pc.green(result.alreadyInstalled ? "updated" : "installed")} git pre-commit hook` : `${pc.dim("already up to date")}`,
+    `  hook ${target.hookPath}`
+  ];
+  if (result.appendedToForeign) {
+    lines.push(`  ${pc.yellow("appended after an existing pre-commit hook -- review")} ${target.hookPath}`);
+  }
+  lines.push(
+    "",
+    `Runs ${pc.bold("nexusmem precheck")} before each commit -- advisory only, never blocks a commit on its own.`,
+    `Run ${pc.bold("nexusmem hook git remove")} to undo this.`,
+    ""
+  );
+  process.stdout.write(lines.join("\n"));
+  return 0;
+}
+async function runHookGitRemove(opts) {
+  const repo = await readRepoInfo(opts.cwd);
+  const target = resolveGitHookTarget(repo.root);
+  const result = await removeGitHook(target);
+  process.stdout.write(
+    result.changed ? `${pc.green("removed")} nexusmem's block from ${target.hookPath}
+` : `${pc.dim("nothing to remove")} \u2014 no nexusmem block found in ${target.hookPath}
+`
+  );
+  return 0;
+}
+async function runHookGitStatus(opts) {
+  const repo = await readRepoInfo(opts.cwd);
+  const target = resolveGitHookTarget(repo.root);
+  const result = await gitHookStatus(target);
+  const statusLabel = result.installed ? pc.green("installed") : result.foreign ? pc.yellow("a foreign hook exists (not nexusmem) -- install --force to append") : pc.yellow("not installed");
+  process.stdout.write([`${pc.dim("hook  ")} ${target.hookPath}`, `${pc.dim("status")} ${statusLabel}`, ""].join("\n"));
+  return 0;
+}
+
+// src/cli/commands/hook.ts
+import pc2 from "picocolors";
 async function runHookInstall(opts) {
   const target = await resolveHookTarget(opts.profile, opts.logPath);
   const result = await installHook(target);
   process.stdout.write(
     [
-      result.changed ? `${pc.green(result.alreadyInstalled ? "updated" : "installed")} shell hook` : `${pc.dim("already up to date")}`,
+      result.changed ? `${pc2.green(result.alreadyInstalled ? "updated" : "installed")} shell hook` : `${pc2.dim("already up to date")}`,
       `  profile ${target.profilePath}`,
       `  log     ${target.logPath}`,
       "",
       `New commands in any PowerShell session using this profile will now log their timestamp, cwd and exit code.`,
       `Open a new PowerShell window (or run \`. $PROFILE\`) for it to take effect.`,
-      `Run ${pc.bold("nexusmem hook remove")} to undo this.`,
+      `Run ${pc2.bold("nexusmem hook remove")} to undo this.`,
       ""
     ].join("\n")
   );
@@ -572,8 +726,8 @@ async function runHookRemove(opts) {
   const target = await resolveHookTarget(opts.profile, opts.logPath);
   const result = await removeHook(target);
   process.stdout.write(
-    result.changed ? `${pc.green("removed")} shell hook from ${target.profilePath}
-` : `${pc.dim("nothing to remove")} \u2014 no hook block found in ${target.profilePath}
+    result.changed ? `${pc2.green("removed")} shell hook from ${target.profilePath}
+` : `${pc2.dim("nothing to remove")} \u2014 no hook block found in ${target.profilePath}
 `
   );
   return 0;
@@ -583,9 +737,9 @@ async function runHookStatus(opts) {
   const result = await hookStatus(target);
   process.stdout.write(
     [
-      `${pc.dim("profile")} ${target.profilePath}`,
-      `${pc.dim("log    ")} ${target.logPath}`,
-      `${pc.dim("status ")} ${result.installed ? pc.green("installed") : pc.yellow("not installed")}`,
+      `${pc2.dim("profile")} ${target.profilePath}`,
+      `${pc2.dim("log    ")} ${target.logPath}`,
+      `${pc2.dim("status ")} ${result.installed ? pc2.green("installed") : pc2.yellow("not installed")}`,
       ""
     ].join("\n")
   );
@@ -594,12 +748,12 @@ async function runHookStatus(opts) {
 
 // src/cli/commands/init.ts
 import { relative } from "path";
-import pc2 from "picocolors";
+import pc3 from "picocolors";
 
 // src/config/registry.ts
 import { existsSync as existsSync2 } from "fs";
-import { mkdir as mkdir3, readFile as readFile3, rename, writeFile as writeFile3 } from "fs/promises";
-import { join as join4 } from "path";
+import { mkdir as mkdir4, readFile as readFile4, rename, writeFile as writeFile4 } from "fs/promises";
+import { join as join5 } from "path";
 import { z as z2 } from "zod";
 var ENTRY_SCHEMA = z2.object({
   projectId: z2.string().min(1),
@@ -614,12 +768,12 @@ var REGISTRY_SCHEMA = z2.object({
   projects: z2.array(ENTRY_SCHEMA).default([])
 });
 function registryPath() {
-  return join4(globalWorkspaceDir(), "projects.json");
+  return join5(globalWorkspaceDir(), "projects.json");
 }
 async function readRegistry() {
   let raw;
   try {
-    raw = await readFile3(registryPath(), "utf8");
+    raw = await readFile4(registryPath(), "utf8");
   } catch {
     return [];
   }
@@ -658,8 +812,8 @@ async function forgetProjects(projectIds) {
 async function writeRegistry(projects) {
   const path = registryPath();
   const tmp = `${path}.${process.pid}.tmp`;
-  await mkdir3(globalWorkspaceDir(), { recursive: true });
-  await writeFile3(tmp, `${JSON.stringify({ version: 1, projects }, null, 2)}
+  await mkdir4(globalWorkspaceDir(), { recursive: true });
+  await writeFile4(tmp, `${JSON.stringify({ version: 1, projects }, null, 2)}
 `, "utf8");
   await rename(tmp, path);
 }
@@ -693,7 +847,7 @@ function makeProjectId({ root, originUrl }) {
 // src/store/store.ts
 import Database from "better-sqlite3";
 import { mkdirSync } from "fs";
-import { dirname as dirname2 } from "path";
+import { dirname as dirname3 } from "path";
 import * as sqliteVec from "sqlite-vec";
 
 // src/store/fts.ts
@@ -710,11 +864,6 @@ function toMatchQuery(input) {
   if (kept.length === 0) return null;
   return kept.map((t) => `"${t}"*`).join(" OR ");
 }
-function toStrictMatchQuery(input) {
-  const kept = significantTokens(input);
-  if (kept.length === 0) return null;
-  return kept.map((t) => `"${t}"*`).join(" AND ");
-}
 
 // src/store/schema.ts
 var V1 = `
@@ -825,10 +974,29 @@ CREATE TABLE node_links (
 -- direction yet, so only the forward lookup gets an index.
 CREATE INDEX idx_node_links_from ON node_links (from_node_id);
 `;
+var V4 = `
+-- File-to-file structural relationships (currently: JS/TS import edges),
+-- derived from the working tree rather than from any node's content. A
+-- source file is not a node, so this cannot reuse node_links (both of its
+-- columns FK to nodes.id) -- project_id has to be stored here explicitly
+-- since there is no node to join through for it.
+CREATE TABLE file_edges (
+  project_id TEXT NOT NULL,
+  from_path  TEXT NOT NULL,
+  to_path    TEXT NOT NULL,
+  kind       TEXT NOT NULL,
+  PRIMARY KEY (project_id, from_path, to_path, kind)
+);
+
+-- "What imports this file" (e.g. blast-radius of a change) is the query a
+-- future feature needs; the primary key already covers the forward direction.
+CREATE INDEX idx_file_edges_to ON file_edges (project_id, to_path);
+`;
 var MIGRATIONS = [
   { version: 1, up: (db) => db.exec(V1) },
   { version: 2, up: (db) => db.exec(V2) },
-  { version: 3, up: (db) => db.exec(V3) }
+  { version: 3, up: (db) => db.exec(V3) },
+  { version: 4, up: (db) => db.exec(V4) }
 ];
 var LATEST_SCHEMA_VERSION = MIGRATIONS[MIGRATIONS.length - 1]?.version ?? 0;
 function currentSchemaVersion(db) {
@@ -857,7 +1025,7 @@ var MemoryStore = class _MemoryStore {
   }
   db;
   static open(dbPath) {
-    mkdirSync(dirname2(dbPath), { recursive: true });
+    mkdirSync(dirname3(dbPath), { recursive: true });
     const db = new Database(dbPath);
     db.pragma("journal_mode = WAL");
     db.pragma("synchronous = NORMAL");
@@ -893,6 +1061,13 @@ var MemoryStore = class _MemoryStore {
       (r) => r.id
     );
   }
+  /** Total nodes held under the given project identities. */
+  countProjectNodes(projectIds) {
+    if (projectIds.length === 0) return 0;
+    const placeholders = projectIds.map(() => "?").join(", ");
+    const row = this.db.prepare(`SELECT COUNT(*) AS n FROM nodes WHERE project_id IN (${placeholders})`).get(...projectIds);
+    return row.n;
+  }
   /**
    * Write a batch of nodes in one transaction.
    *
@@ -1096,6 +1271,29 @@ var MemoryStore = class _MemoryStore {
       return this.db.prepare(`DELETE FROM nodes WHERE ${scope}`).run(params).changes;
     })();
   }
+  /**
+   * Replace this project's entire `file_edges` snapshot in one transaction.
+   *
+   * Edges describe the current working tree, not history -- unlike
+   * `pruneSourceNodes`'s incremental diff-against-a-scan, there is no cursor
+   * to walk, so every `scan-structure`/sync run is a full rescan and this is
+   * always a delete-then-insert of the whole set, never a partial update.
+   */
+  replaceFileEdges(projectId, edges) {
+    this.db.transaction(() => {
+      this.db.prepare("DELETE FROM file_edges WHERE project_id = ?").run(projectId);
+      const insert = this.db.prepare(
+        "INSERT OR IGNORE INTO file_edges (project_id, from_path, to_path, kind) VALUES (?, ?, ?, ?)"
+      );
+      for (const edge of edges) insert.run(projectId, edge.fromPath, edge.toPath, edge.kind);
+    })();
+  }
+  /** Edge count + distinct source-file count, for `nexusmem status`'s `structure` line. */
+  fileEdgeStats(projectId) {
+    const edges = this.db.prepare("SELECT COUNT(*) AS c FROM file_edges WHERE project_id = ?").get(projectId).c;
+    const files = this.db.prepare("SELECT COUNT(DISTINCT from_path) AS c FROM file_edges WHERE project_id = ?").get(projectId).c;
+    return { edges, files };
+  }
   /**
    * Nodes for this project that have no embedding yet (new, or invalidated
    * by a content change).
@@ -1219,9 +1417,9 @@ async function runInit(opts) {
   if (already && !opts.force) {
     const existing = await readConfig(ws);
     process.stderr.write(
-      `${pc2.yellow("already initialized")} ${relative(process.cwd(), ws.configPath) || ws.configPath}
-  project ${pc2.cyan(existing.projectId)}
-  use ${pc2.bold("--force")} to reset the config (the database is kept)
+      `${pc3.yellow("already initialized")} ${relative(process.cwd(), ws.configPath) || ws.configPath}
+  project ${pc3.cyan(existing.projectId)}
+  use ${pc3.bold("--force")} to reset the config (the database is kept)
 `
     );
     return 0;
@@ -1238,14 +1436,14 @@ async function runInit(opts) {
   }
   await recordProject({ projectId, root: repo.root, dbPath: ws.dbPath, originUrl: repo.originUrl });
   const lines = [
-    `${pc2.green("initialized")} ${ws.dir}`,
-    `  project  ${pc2.cyan(projectId)}`,
+    `${pc3.green("initialized")} ${ws.dir}`,
+    `  project  ${pc3.cyan(projectId)}`,
     `  repo     ${repo.root}`,
-    `  branch   ${repo.branch ?? pc2.yellow("(detached)")}`,
+    `  branch   ${repo.branch ?? pc3.yellow("(detached)")}`,
     `  schema   v${LATEST_SCHEMA_VERSION}`
   ];
   if (opts.enableConversation) {
-    lines.push(`  ${pc2.yellow("conversation source enabled")} -- transcripts will be redacted-but-indexed on sync`);
+    lines.push(`  ${pc3.yellow("conversation source enabled")} -- transcripts will be redacted-but-indexed on sync`);
   }
   if (opts.hook) {
     try {
@@ -1253,26 +1451,26 @@ async function runInit(opts) {
       const result = await installHook(target);
       lines.push(
         "",
-        `${pc2.green(result.changed ? "installed" : "already installed")} shell hook`,
+        `${pc3.green(result.changed ? "installed" : "already installed")} shell hook`,
         `  profile ${target.profilePath}`,
         `  log     ${target.logPath}`,
         `  open a new PowerShell window (or run \`. $PROFILE\`) for it to take effect`
       );
     } catch (err) {
       if (err instanceof ProfileNotFoundError) {
-        lines.push("", `${pc2.yellow("hook not installed")} ${err.message}`);
+        lines.push("", `${pc3.yellow("hook not installed")} ${err.message}`);
       } else {
         throw err;
       }
     }
   }
-  lines.push("", `Next: ${pc2.bold("nexusmem sync")}`, "");
+  lines.push("", `Next: ${pc3.bold("nexusmem sync")}`, "");
   out(lines.join("\n"));
   return 0;
 }
 
 // src/cli/commands/projects.ts
-import pc3 from "picocolors";
+import pc4 from "picocolors";
 async function runProjects(opts) {
   const { entries, missing } = await readLiveRegistry();
   const rows = entries.map((entry) => {
@@ -1291,7 +1489,7 @@ async function runProjects(opts) {
   });
   if (opts.prune) {
     const removed = await forgetProjects(missing.map((entry) => entry.projectId));
-    process.stderr.write(`${pc3.yellow("pruned")} ${removed} project(s) whose database is gone
+    process.stderr.write(`${pc4.yellow("pruned")} ${removed} project(s) whose database is gone
 `);
   }
   if (opts.json) {
@@ -1299,28 +1497,28 @@ async function runProjects(opts) {
 `);
     return 0;
   }
-  process.stderr.write(`${pc3.dim("registry")} ${registryPath()}
+  process.stderr.write(`${pc4.dim("registry")} ${registryPath()}
 
 `);
   if (rows.length === 0) {
-    process.stderr.write(`${pc3.yellow("no projects registered")} -- run ${pc3.bold("nexusmem sync")} in a repository
+    process.stderr.write(`${pc4.yellow("no projects registered")} -- run ${pc4.bold("nexusmem sync")} in a repository
 `);
     return 0;
   }
   for (const row of rows) {
     const seen = new Date(row.lastSeenAt).toISOString().slice(0, 16).replace("T", " ");
-    const count = row.nodes === null ? pc3.yellow("unreadable") : `${row.nodes} node(s)`;
-    process.stdout.write(`${pc3.cyan(row.projectId.slice(0, 8))}  ${row.root}
-    ${pc3.dim(`${count}, last seen ${seen}`)}
+    const count = row.nodes === null ? pc4.yellow("unreadable") : `${row.nodes} node(s)`;
+    process.stdout.write(`${pc4.cyan(row.projectId.slice(0, 8))}  ${row.root}
+    ${pc4.dim(`${count}, last seen ${seen}`)}
 `);
   }
   if (!opts.prune && missing.length > 0) {
     process.stderr.write(
       `
-${pc3.yellow(`${missing.length} registered project(s) have no database on disk`)} ${pc3.dim("-- run with --prune to forget them")}
+${pc4.yellow(`${missing.length} registered project(s) have no database on disk`)} ${pc4.dim("-- run with --prune to forget them")}
 `
     );
-    for (const entry of missing) process.stderr.write(`    ${pc3.dim(entry.root)}
+    for (const entry of missing) process.stderr.write(`    ${pc4.dim(entry.root)}
 `);
   }
   return 0;
@@ -1521,6 +1719,23 @@ var RESOLVED_BY_DISCUSSION = "resolved_by:discussion";
 function normalizeCommand(command) {
   return command.trim().replace(/\s+/g, " ").toLowerCase();
 }
+var MAX_TOKEN_DOC_FREQUENCY = 0.2;
+var MIN_CORPUS_FOR_FREQUENCY_FILTER = 10;
+var DEFAULT_BOILERPLATE_KINDS = ["conversation_turn", "session_summary"];
+function filterBoilerplateTokens(db, projectId, tokens, kinds = DEFAULT_BOILERPLATE_KINDS) {
+  if (tokens.length === 0) return tokens;
+  const kindsPlaceholder = kinds.map(() => "?").join(", ");
+  const total = db.prepare(`SELECT COUNT(*) AS c FROM nodes WHERE project_id = ? AND kind IN (${kindsPlaceholder})`).get(projectId, ...kinds).c;
+  if (total < MIN_CORPUS_FOR_FREQUENCY_FILTER) return tokens;
+  const countMatching = db.prepare(
+    `SELECT COUNT(*) AS c FROM nodes_fts JOIN nodes n ON n.rowid = nodes_fts.rowid
+     WHERE nodes_fts MATCH ? AND n.project_id = ? AND n.kind IN (${kindsPlaceholder})`
+  );
+  return tokens.filter((t) => {
+    const matching = countMatching.get(`"${t}"*`, projectId, ...kinds).c;
+    return matching / total <= MAX_TOKEN_DOC_FREQUENCY;
+  });
+}
 function correlateFailures(store, projectId, opts = {}) {
   const retryWindowMs = opts.retryWindowMs ?? DEFAULT_RETRY_WINDOW_MS;
   const discussionWindowMs = opts.discussionWindowMs ?? DEFAULT_DISCUSSION_WINDOW_MS;
@@ -1565,7 +1780,8 @@ function correlateFailures(store, projectId, opts = {}) {
       store.linkNodes(failure.id, retry.id, RESOLVED_BY_RETRY);
       linkedByRetry += 1;
     }
-    const match = toStrictMatchQuery(failure.command);
+    const tokens = filterBoilerplateTokens(db, projectId, significantTokens(failure.command));
+    const match = tokens.length > 0 ? tokens.map((t) => `"${t}"*`).join(" AND ") : null;
     if (match) {
       const discussion = findDiscussion.get(match, projectId, failure.ts_epoch, failure.ts_epoch + discussionWindowMs);
       if (discussion) {
@@ -1576,6 +1792,25 @@ function correlateFailures(store, projectId, opts = {}) {
   }
   return { failuresExamined: failures.length, linkedByRetry, linkedByDiscussion };
 }
+function getChainStats(store, projectId) {
+  const db = store.raw;
+  const failuresTotal = db.prepare(
+    `SELECT COUNT(*) AS c FROM nodes
+         WHERE project_id = ? AND kind = 'shell_command'
+           AND json_extract(meta, '$.exitCode') IS NOT NULL AND json_extract(meta, '$.exitCode') != 0`
+  ).get(projectId).c;
+  const countDistinctLinked = (relations) => db.prepare(
+    `SELECT COUNT(DISTINCT nl.from_node_id) AS c
+           FROM node_links nl JOIN nodes n ON n.id = nl.from_node_id
+           WHERE n.project_id = ? AND nl.relation IN (${relations.map(() => "?").join(", ")})`
+  ).get(projectId, ...relations).c;
+  return {
+    failuresTotal,
+    resolvedByRetry: countDistinctLinked([RESOLVED_BY_RETRY]),
+    resolvedByDiscussion: countDistinctLinked([RESOLVED_BY_DISCUSSION]),
+    resolvedTotal: countDistinctLinked([RESOLVED_BY_RETRY, RESOLVED_BY_DISCUSSION])
+  };
+}
 
 // src/retrieval/fuse.ts
 var RRF_K = 60;
@@ -1833,7 +2068,7 @@ var OllamaEmbeddingProvider = class {
 };
 
 // src/cli/commands/sync.ts
-import pc4 from "picocolors";
+import pc5 from "picocolors";
 
 // src/conversation/chunk.ts
 var HEADING_LINE = /^#{1,6}\s+(.+)$/;
@@ -2821,25 +3056,25 @@ function collectShellHistory(entries, projectId, opts = {}) {
 }
 
 // src/conversation/claude-code-reader.ts
-import { readFile as readFile4 } from "fs/promises";
+import { readFile as readFile5 } from "fs/promises";
 import { basename as basename2 } from "path";
 
 // src/conversation/paths.ts
 import { existsSync as existsSync3 } from "fs";
 import { readdir } from "fs/promises";
 import { homedir as homedir3 } from "os";
-import { join as join5 } from "path";
+import { join as join6 } from "path";
 function claudeProjectSlug(repoRoot) {
   return repoRoot.replace(/[\\/:]/g, "-");
 }
 function claudeProjectTranscriptDir(repoRoot) {
-  return join5(homedir3(), ".claude", "projects", claudeProjectSlug(repoRoot));
+  return join6(homedir3(), ".claude", "projects", claudeProjectSlug(repoRoot));
 }
 async function listTranscriptFiles(repoRoot) {
   const dir = claudeProjectTranscriptDir(repoRoot);
   if (!existsSync3(dir)) return [];
   const entries = await readdir(dir, { withFileTypes: true });
-  return entries.filter((e) => e.isFile() && e.name.endsWith(".jsonl")).map((e) => join5(dir, e.name));
+  return entries.filter((e) => e.isFile() && e.name.endsWith(".jsonl")).map((e) => join6(dir, e.name));
 }
 
 // src/conversation/claude-code-reader.ts
@@ -2914,15 +3149,15 @@ async function collectClaudeCodeTranscripts(repoRoot) {
   const files = await listTranscriptFiles(repoRoot);
   const turns = [];
   for (const file of files) {
-    const raw = await readFile4(file, "utf8");
+    const raw = await readFile5(file, "utf8");
     turns.push(...parseClaudeCodeTranscript(raw, { sessionId: basename2(file, ".jsonl") }));
   }
   return turns;
 }
 
 // src/docs/read.ts
-import { readFile as readFile5, stat } from "fs/promises";
-import { join as join6 } from "path";
+import { readFile as readFile6, stat } from "fs/promises";
+import { join as join7 } from "path";
 var DEFAULT_PATHSPECS = ["*.md"];
 async function listDocFiles(repoRoot, opts = {}) {
   const pathspecs = opts.include ?? DEFAULT_PATHSPECS;
@@ -2935,11 +3170,11 @@ async function readDocFiles(repoRoot, opts = {}) {
   const unreadable = [];
   for (const relPath of paths) {
     const path = relPath.replace(/\\/g, "/");
-    const absPath = join6(repoRoot, relPath);
+    const absPath = join7(repoRoot, relPath);
     let content;
     let mtime;
     try {
-      [content, { mtime }] = await Promise.all([readFile5(absPath, "utf8"), stat(absPath)]);
+      [content, { mtime }] = await Promise.all([readFile6(absPath, "utf8"), stat(absPath)]);
     } catch {
       unreadable.push(path);
       continue;
@@ -2951,11 +3186,11 @@ async function readDocFiles(repoRoot, opts = {}) {
 
 // src/shell/detect.ts
 import { existsSync as existsSync4 } from "fs";
-import { readFile as readFile7, stat as stat2 } from "fs/promises";
+import { readFile as readFile8, stat as stat2 } from "fs/promises";
 
 // src/shell/hook-log.ts
-import { appendFile, mkdir as mkdir4, readFile as readFile6 } from "fs/promises";
-import { dirname as dirname3 } from "path";
+import { appendFile, mkdir as mkdir5, readFile as readFile7 } from "fs/promises";
+import { dirname as dirname4 } from "path";
 function parseHookLogLine(line) {
   const trimmed = line.trim();
   if (!trimmed) return null;
@@ -2979,7 +3214,7 @@ function parseHookLogLine(line) {
 async function readHookLog(path, fromLine) {
   let raw;
   try {
-    raw = await readFile6(path, "utf8");
+    raw = await readFile7(path, "utf8");
   } catch {
     return { entries: [], totalLines: fromLine };
   }
@@ -3113,7 +3348,7 @@ function hookEntryToRaw(e) {
 }
 async function tryReadScrapeSource(path, parse, tailLines) {
   if (!existsSync4(path)) return null;
-  const [raw, stats] = await Promise.all([readFile7(path, "utf8"), stat2(path)]);
+  const [raw, stats] = await Promise.all([readFile8(path, "utf8"), stat2(path)]);
   return parse(raw, stats.mtimeMs, { tailLines });
 }
 async function collectAvailableShellHistory(opts = {}) {
@@ -3234,6 +3469,101 @@ function reconcileProjectId(db, oldProjectId, newProjectId) {
   })();
 }
 
+// src/structure/collect.ts
+import { readFile as readFile9 } from "fs/promises";
+import { join as join8 } from "path";
+
+// src/structure/extract.ts
+var IMPORT_PATTERNS = [
+  // import ... from '...'; export ... from '...'
+  /\b(?:import|export)\b[^'"\n]*?\bfrom\s*['"]([^'"]+)['"]/g,
+  // import '...'; (side-effect only)
+  /\bimport\s*['"]([^'"]+)['"]/g,
+  // require('...')
+  /\brequire\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+  // dynamic import('...')
+  /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g
+];
+function extractImportSpecifiers(source) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const pattern of IMPORT_PATTERNS) {
+    pattern.lastIndex = 0;
+    let match;
+    while ((match = pattern.exec(source)) !== null) {
+      const specifier = match[1];
+      if (specifier && (specifier.startsWith("./") || specifier.startsWith("../"))) {
+        seen.add(specifier);
+      }
+    }
+  }
+  return [...seen];
+}
+
+// src/structure/resolve.ts
+import { posix } from "path";
+var REWRITE_EXTENSIONS = {
+  ".js": [".ts", ".tsx", ".js"],
+  ".jsx": [".tsx", ".jsx"],
+  ".mjs": [".mts", ".mjs"],
+  ".cjs": [".cts", ".cjs"]
+};
+var APPEND_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".d.ts", ".json"];
+var INDEX_FILES = ["index.ts", "index.tsx", "index.js", "index.jsx"];
+function resolveSpecifier(fromPath, specifier, trackedPaths) {
+  const fromDir = posix.dirname(fromPath);
+  const joined = posix.normalize(posix.join(fromDir, specifier));
+  if (trackedPaths.has(joined)) return joined;
+  const ext = posix.extname(joined);
+  const rewrites = REWRITE_EXTENSIONS[ext];
+  if (rewrites) {
+    const base = joined.slice(0, -ext.length);
+    for (const replacement of rewrites) {
+      const candidate = base + replacement;
+      if (trackedPaths.has(candidate)) return candidate;
+    }
+    return null;
+  }
+  if (ext) return null;
+  for (const suffix of APPEND_EXTENSIONS) {
+    const candidate = joined + suffix;
+    if (trackedPaths.has(candidate)) return candidate;
+  }
+  for (const indexFile of INDEX_FILES) {
+    const candidate = posix.join(joined, indexFile);
+    if (trackedPaths.has(candidate)) return candidate;
+  }
+  return null;
+}
+
+// src/structure/collect.ts
+var TRACKED_PATHSPECS = ["*.ts", "*.tsx", "*.js", "*.jsx"];
+async function collectFileEdges(repoRoot) {
+  const out = await git(repoRoot, ["ls-files", "--", ...TRACKED_PATHSPECS]);
+  const paths = out.split("\n").map((line) => line.trim().replace(/\\/g, "/")).filter(Boolean);
+  const trackedPaths = new Set(paths);
+  const edges = [];
+  const seenEdges = /* @__PURE__ */ new Set();
+  const unreadable = [];
+  for (const path of paths) {
+    let content;
+    try {
+      content = await readFile9(join8(repoRoot, path), "utf8");
+    } catch {
+      unreadable.push(path);
+      continue;
+    }
+    for (const specifier of extractImportSpecifiers(content)) {
+      const target = resolveSpecifier(path, specifier, trackedPaths);
+      if (!target || target === path) continue;
+      const key = `${path}\0${target}`;
+      if (seenEdges.has(key)) continue;
+      seenEdges.add(key);
+      edges.push({ fromPath: path, toPath: target, kind: "import" });
+    }
+  }
+  return { edges, filesScanned: paths.length, unreadable };
+}
+
 // src/vector/sync.ts
 var EMBEDDING_IDENTITY_KEY = "embedding.identity";
 var DEFAULT_BATCH_SIZE = 32;
@@ -3328,25 +3658,25 @@ function addStats(into, from) {
 async function syncGit(store, projectId, opts, repo, config, log) {
   const totals = { inserted: 0, updated: 0, unchanged: 0 };
   if (!repo.head) {
-    log(`${pc4.yellow("git")} skipped -- repository has no commits yet`);
+    log(`${pc5.yellow("git")} skipped -- repository has no commits yet`);
     return { totals, seen: 0 };
   }
   if (!config.sources.git.enabled) {
-    log(`${pc4.dim("git")} disabled in config`);
+    log(`${pc5.dim("git")} disabled in config`);
     return { totals, seen: 0 };
   }
   let cursor = opts.full || opts.rebuild ? null : store.getSyncCursor(projectId, GIT_SOURCE);
   if (cursor && !await isAncestor(repo.root, cursor, repo.head)) {
-    log(`${pc4.yellow("git cursor stale")} ${cursor.slice(0, 7)} is not an ancestor of HEAD \u2014 falling back to a full walk`);
+    log(`${pc5.yellow("git cursor stale")} ${cursor.slice(0, 7)} is not an ancestor of HEAD \u2014 falling back to a full walk`);
     cursor = null;
   }
   if (cursor === repo.head) {
-    log(`${pc4.green("git up to date")} at ${repo.head.slice(0, 7)}`);
+    log(`${pc5.green("git up to date")} at ${repo.head.slice(0, 7)}`);
     store.setSyncCursor(projectId, GIT_SOURCE, repo.head);
     return { totals, seen: 0 };
   }
   log(
-    `${pc4.dim("git syncing")} ${repo.branch ?? "HEAD"} ${cursor ? `${cursor.slice(0, 7)}..${repo.head.slice(0, 7)}` : "(full history)"}`
+    `${pc5.dim("git syncing")} ${repo.branch ?? "HEAD"} ${cursor ? `${cursor.slice(0, 7)}..${repo.head.slice(0, 7)}` : "(full history)"}`
   );
   let batch = [];
   let seen = 0;
@@ -3354,7 +3684,7 @@ async function syncGit(store, projectId, opts, repo, config, log) {
     if (batch.length === 0) return;
     addStats(totals, store.upsertNodes(batch));
     batch = [];
-    log(`  ${pc4.dim(`${seen} commits read, ${totals.inserted} new`)}`);
+    log(`  ${pc5.dim(`${seen} commits read, ${totals.inserted} new`)}`);
   };
   const nodes = collectGitCommits(repo.root, projectId, {
     afterCommit: cursor,
@@ -3376,12 +3706,12 @@ async function syncDiffs(store, projectId, opts, repo, config, log) {
   const totals = { inserted: 0, updated: 0, unchanged: 0 };
   if (!repo.head) return { totals, seen: 0 };
   if (!config.sources.diff.enabled) {
-    log(`${pc4.dim("diff")} disabled in config`);
+    log(`${pc5.dim("diff")} disabled in config`);
     return { totals, seen: 0 };
   }
   let cursor = opts.full || opts.rebuild ? null : store.getSyncCursor(projectId, DIFF_SOURCE);
   if (cursor && !await isAncestor(repo.root, cursor, repo.head)) {
-    log(`${pc4.yellow("diff cursor stale")} ${cursor.slice(0, 7)} is not an ancestor of HEAD \u2014 falling back to a bounded walk`);
+    log(`${pc5.yellow("diff cursor stale")} ${cursor.slice(0, 7)} is not an ancestor of HEAD \u2014 falling back to a bounded walk`);
     cursor = null;
   }
   if (cursor === repo.head) {
@@ -3410,13 +3740,13 @@ async function syncDiffs(store, projectId, opts, repo, config, log) {
   }
   flush();
   store.setSyncCursor(projectId, DIFF_SOURCE, repo.head);
-  log(`  ${pc4.dim(`${DIFF_SOURCE}: ${seen} file diff(s) read`)}`);
+  log(`  ${pc5.dim(`${DIFF_SOURCE}: ${seen} file diff(s) read`)}`);
   return { totals, seen };
 }
 async function syncShell(store, projectId, opts, repoRoot, config, log) {
   const totals = { inserted: 0, updated: 0, unchanged: 0 };
   if (!config.sources.shell.enabled) {
-    log(`${pc4.dim("shell")} disabled in config`);
+    log(`${pc5.dim("shell")} disabled in config`);
     return { totals, seen: 0 };
   }
   const results = await collectAvailableShellHistory({
@@ -3425,7 +3755,7 @@ async function syncShell(store, projectId, opts, repoRoot, config, log) {
     hookCursor: store.getSyncCursor(projectId, "shell:pwsh-hook")
   });
   if (results.length === 0) {
-    log(`${pc4.dim("shell")} no history source found on this machine`);
+    log(`${pc5.dim("shell")} no history source found on this machine`);
     return { totals, seen: 0 };
   }
   let seen = 0;
@@ -3437,7 +3767,7 @@ async function syncShell(store, projectId, opts, repoRoot, config, log) {
       addStats(totals, store.upsertNodes(nodes));
     }
     store.setSyncCursor(projectId, sourceKey, result.cursorAfter ?? `scanned:${result.entries.length}`);
-    log(`  ${pc4.dim(`${sourceKey}: ${nodes.length} entr${nodes.length === 1 ? "y" : "ies"} read`)}`);
+    log(`  ${pc5.dim(`${sourceKey}: ${nodes.length} entr${nodes.length === 1 ? "y" : "ies"} read`)}`);
   }
   return { totals, seen };
 }
@@ -3449,13 +3779,13 @@ function syncConversation(store, projectId, turns, config, log, forceEnabled) {
     return { totals, seen: 0 };
   }
   if (turns.length === 0) {
-    log(`${pc4.dim("conversation")} no transcripts found`);
+    log(`${pc5.dim("conversation")} no transcripts found`);
     return { totals, seen: 0 };
   }
   const nodes = collectConversationTurns(turns, projectId, { maxBodyChars: config.limits.maxBodyChars });
   if (nodes.length > 0) addStats(totals, store.upsertNodes(nodes));
   store.setSyncCursor(projectId, CONVERSATION_SOURCE, `scanned:${nodes.length}`);
-  log(`  ${pc4.dim(`${CONVERSATION_SOURCE}: ${nodes.length} of ${turns.length} exchange(s) kept`)}`);
+  log(`  ${pc5.dim(`${CONVERSATION_SOURCE}: ${nodes.length} of ${turns.length} exchange(s) kept`)}`);
   return { totals, seen: nodes.length };
 }
 var SESSION_SOURCE = "session:claude-code";
@@ -3464,7 +3794,7 @@ async function syncSessions(store, projectId, turns, config, log) {
   const settings = config.sources.session;
   if (!settings.enabled) return { totals, seen: 0 };
   if (turns.length === 0) {
-    log(`${pc4.dim("session")} no transcripts found`);
+    log(`${pc5.dim("session")} no transcripts found`);
     return { totals, seen: 0 };
   }
   const result = await collectSessionSummaries(turns, projectId, new OllamaChatProvider({ model: settings.model }), {
@@ -3476,12 +3806,12 @@ async function syncSessions(store, projectId, turns, config, log) {
       const meta = store.getNodeMeta(makeNodeId(projectId, "session_summary", sessionKey));
       return typeof meta?.contentHash === "string" ? meta.contentHash : null;
     },
-    onProgress: (done, total) => log(`  ${pc4.dim(`session: summarizing ${done}/${total}`)}`)
+    onProgress: (done, total) => log(`  ${pc5.dim(`session: summarizing ${done}/${total}`)}`)
   });
   if (result.nodes.length > 0) addStats(totals, store.upsertNodes(result.nodes));
   if (result.providerUnavailable) {
     log(
-      `${pc4.dim("session")} summarization model unavailable (is Ollama running with \`${settings.model}\` pulled?) -- skipped`
+      `${pc5.dim("session")} summarization model unavailable (is Ollama running with \`${settings.model}\` pulled?) -- skipped`
     );
   } else {
     const parts = [`${result.nodes.length} summarized`];
@@ -3489,7 +3819,7 @@ async function syncSessions(store, projectId, turns, config, log) {
     if (result.deferred > 0) parts.push(`${result.deferred} queued for the next sync`);
     if (result.unsettled > 0) parts.push(`${result.unsettled} still active`);
     if (result.failed > 0) parts.push(`${result.failed} failed`);
-    log(`  ${pc4.dim(`${SESSION_SOURCE}: ${parts.join(", ")}`)}`);
+    log(`  ${pc5.dim(`${SESSION_SOURCE}: ${parts.join(", ")}`)}`);
   }
   store.setSyncCursor(projectId, SESSION_SOURCE, `scanned:${result.nodes.length}`);
   return { totals, seen: result.nodes.length };
@@ -3498,7 +3828,7 @@ var DOCS_SOURCE = "docs";
 async function syncDocs(store, projectId, repoRoot, config, log) {
   const totals = { inserted: 0, updated: 0, unchanged: 0 };
   if (!config.sources.docs.enabled) {
-    log(`${pc4.dim("docs")} disabled in config`);
+    log(`${pc5.dim("docs")} disabled in config`);
     return { totals, seen: 0 };
   }
   const { files, unreadable } = await readDocFiles(repoRoot, { include: config.sources.docs.include });
@@ -3512,14 +3842,25 @@ async function syncDocs(store, projectId, repoRoot, config, log) {
   );
   store.setSyncCursor(projectId, DOCS_SOURCE, `scanned:${nodes.length}`);
   if (files.length === 0 && unreadable.length === 0) {
-    log(`${pc4.dim("docs")} no tracked .md files found`);
+    log(`${pc5.dim("docs")} no tracked .md files found`);
   } else {
-    const prunedPart = pruned > 0 ? `, ${pc4.yellow(`${pruned} stale removed`)}` : "";
+    const prunedPart = pruned > 0 ? `, ${pc5.yellow(`${pruned} stale removed`)}` : "";
     const skippedPart = unreadable.length > 0 ? `, ${unreadable.length} unreadable (kept)` : "";
-    log(`  ${pc4.dim(`${DOCS_SOURCE}: ${nodes.length} section(s) from ${files.length} file(s)`)}${prunedPart}${pc4.dim(skippedPart)}`);
+    log(`  ${pc5.dim(`${DOCS_SOURCE}: ${nodes.length} section(s) from ${files.length} file(s)`)}${prunedPart}${pc5.dim(skippedPart)}`);
   }
   return { totals, seen: nodes.length };
 }
+async function syncStructure(store, projectId, repoRoot, config, log) {
+  if (!config.sources.structure.enabled) {
+    log(`${pc5.dim("structure")} disabled in config`);
+    return { edges: 0, filesScanned: 0 };
+  }
+  const { edges, filesScanned, unreadable } = await collectFileEdges(repoRoot);
+  store.replaceFileEdges(projectId, edges);
+  const skippedPart = unreadable.length > 0 ? `, ${unreadable.length} unreadable (skipped)` : "";
+  log(`  ${pc5.dim(`structure: ${edges.length} edge(s) from ${filesScanned} file(s)`)}${pc5.dim(skippedPart)}`);
+  return { edges: edges.length, filesScanned };
+}
 var STALE_SHELL_SOURCES = ["shell:pwsh", "shell:bash", "shell:zsh"];
 function collectPruneSources(opts) {
   const sources = /* @__PURE__ */ new Set();
@@ -3534,15 +3875,15 @@ function runPruneSources(store, projectId, otherProjectIds, sources, yes, out) {
   const counts = sources.flatMap((source) => scopeIds.map((id) => ({ source, id, count: store.countSourceNodes(id, source) })));
   const total = counts.reduce((sum, c) => sum + c.count, 0);
   if (total === 0) {
-    out(`${pc4.dim("prune-source")} no node(s) match ${sources.join(", ")} -- nothing to do
+    out(`${pc5.dim("prune-source")} no node(s) match ${sources.join(", ")} -- nothing to do
 `);
     return 0;
   }
-  const describe = (c) => `  ${pc4.dim(c.source)}${c.id !== projectId ? pc4.dim(` (prior identity ${c.id.slice(0, 8)})`) : ""}: ${c.count} node(s)`;
+  const describe = (c) => `  ${pc5.dim(c.source)}${c.id !== projectId ? pc5.dim(` (prior identity ${c.id.slice(0, 8)})`) : ""}: ${c.count} node(s)`;
   if (!yes) {
     const lines = counts.filter((c) => c.count > 0).map(describe);
     out(
-      [`${pc4.yellow("would remove")} ${total} node(s):`, ...lines, pc4.dim("re-run with --yes to actually delete these -- this cannot be undone"), ""].join(
+      [`${pc5.yellow("would remove")} ${total} node(s):`, ...lines, pc5.dim("re-run with --yes to actually delete these -- this cannot be undone"), ""].join(
         "\n"
       )
     );
@@ -3551,7 +3892,7 @@ function runPruneSources(store, projectId, otherProjectIds, sources, yes, out) {
   let removed = 0;
   for (const { source, id } of counts) removed += store.pruneSourceNodes(id, source, []);
   const identityPart = otherProjectIds.length > 0 ? `, ${scopeIds.length} project identit${scopeIds.length === 1 ? "y" : "ies"}` : "";
-  out(`${pc4.green("pruned")} ${removed} node(s) across ${sources.length} source(s)${identityPart}
+  out(`${pc5.green("pruned")} ${removed} node(s) across ${sources.length} source(s)${identityPart}
 `);
   return 0;
 }
@@ -3568,7 +3909,7 @@ async function runSync(opts) {
     store.upsertProject({ id: projectId, root: repo.root, originUrl: repo.originUrl });
     if (opts.rebuild) {
       const removed = store.clearProject(projectId);
-      log(`${pc4.dim("rebuild")} dropped ${removed} existing node(s)`);
+      log(`${pc5.dim("rebuild")} dropped ${removed} existing node(s)`);
     }
     const staleProjectIds = store.listOtherProjectIds(projectId);
     for (const staleId of staleProjectIds) {
@@ -3581,7 +3922,7 @@ async function runSync(opts) {
       ].filter((part) => part !== null);
       if (parts.length > 0) {
         log(
-          `${pc4.yellow("reconciled")} previous project identity ${pc4.dim(staleId)} (remote URL likely changed): ${parts.join(", ")}`
+          `${pc5.yellow("reconciled")} previous project identity ${pc5.dim(staleId)} (remote URL likely changed): ${parts.join(", ")}`
         );
       }
     }
@@ -3605,31 +3946,32 @@ async function runSync(opts) {
     const conversation = syncConversation(store, projectId, turns, config, log, opts.conversationOverride);
     const sessions = await syncSessions(store, projectId, turns, config, log);
     const docs = await syncDocs(store, projectId, repo.root, config, log);
+    const structure = await syncStructure(store, projectId, repo.root, config, log);
     let embedLine = "";
     if (!opts.noEmbed) {
       let lastLogged = 0;
       const result = await embedPendingNodes(store, new OllamaEmbeddingProvider(), projectId, {
         maxNodes: opts.embedLimit,
-        onInvalidated: (count) => log(`${pc4.yellow("vector")} embedding model changed -- dropped ${count} vector(s), re-embedding from scratch`),
+        onInvalidated: (count) => log(`${pc5.yellow("vector")} embedding model changed -- dropped ${count} vector(s), re-embedding from scratch`),
         onProgress: (attempted, total) => {
           if (total < PROGRESS_THRESHOLD || attempted - lastLogged < PROGRESS_EVERY) return;
           lastLogged = attempted;
-          log(`  ${pc4.dim(`vector: ${attempted}/${total} embedded`)}`);
+          log(`  ${pc5.dim(`vector: ${attempted}/${total} embedded`)}`);
         }
       });
       if (result.embedded > 0) {
-        const skippedPart = result.skipped > 0 ? pc4.dim(`, ${result.skipped} skipped`) : "";
-        const remainingPart = result.remaining > 0 ? pc4.yellow(`, ${result.remaining} still pending`) : "";
-        embedLine = `  ${pc4.dim(`vector: ${result.embedded} node(s) embedded`)}${skippedPart}${remainingPart}
+        const skippedPart = result.skipped > 0 ? pc5.dim(`, ${result.skipped} skipped`) : "";
+        const remainingPart = result.remaining > 0 ? pc5.yellow(`, ${result.remaining} still pending`) : "";
+        embedLine = `  ${pc5.dim(`vector: ${result.embedded} node(s) embedded`)}${skippedPart}${remainingPart}
 `;
       } else if (result.providerUnavailable) {
-        log(`${pc4.dim("vector")} embedding provider unavailable (is Ollama running with nomic-embed-text pulled?) -- BM25-only for now`);
+        log(`${pc5.dim("vector")} embedding provider unavailable (is Ollama running with nomic-embed-text pulled?) -- BM25-only for now`);
       }
     }
     let linkLine = "";
     if (opts.linkFailures) {
       const linkStats = correlateFailures(store, projectId);
-      linkLine = `  ${pc4.dim(`chains: ${linkStats.failuresExamined} failure(s) examined, ${linkStats.linkedByRetry} linked by retry, ${linkStats.linkedByDiscussion} by discussion`)}
+      linkLine = `  ${pc5.dim(`chains: ${linkStats.failuresExamined} failure(s) examined, ${linkStats.linkedByRetry} linked by retry, ${linkStats.linkedByDiscussion} by discussion`)}
 `;
     }
     store.markSynced(projectId);
@@ -3646,11 +3988,12 @@ async function runSync(opts) {
     const sessionPart = config.sources.session.enabled ? `, ${sessions.seen} session summar${sessions.seen === 1 ? "y" : "ies"}` : "";
     const docsPart = config.sources.docs.enabled ? `, ${docs.seen} doc section(s)` : "";
     const diffPart = config.sources.diff.enabled ? `, ${diffs.seen} file diff(s)` : "";
+    const structurePart = config.sources.structure.enabled ? `, ${structure.edges} import edge(s)` : "";
     out(
       [
-        `${pc4.green("synced")} ${git2.seen} commit(s)${diffPart}, ${shell.seen} shell entr${shell.seen === 1 ? "y" : "ies"}${conversationPart}${sessionPart}${docsPart} in ${elapsed}s`,
-        `  ${pc4.green(`+${totals.inserted} new`)}  ${pc4.yellow(`~${totals.updated} updated`)}  ${pc4.dim(`=${totals.unchanged} unchanged`)}`,
-        `  ${pc4.dim(`${stats.total} node(s) total across ${stats.distinctFiles} file path(s)`)}`,
+        `${pc5.green("synced")} ${git2.seen} commit(s)${diffPart}, ${shell.seen} shell entr${shell.seen === 1 ? "y" : "ies"}${conversationPart}${sessionPart}${docsPart}${structurePart} in ${elapsed}s`,
+        `  ${pc5.green(`+${totals.inserted} new`)}  ${pc5.yellow(`~${totals.updated} updated`)}  ${pc5.dim(`=${totals.unchanged} unchanged`)}`,
+        `  ${pc5.dim(`${stats.total} node(s) total across ${stats.distinctFiles} file path(s)`)}`,
         ""
       ].join("\n") + embedLine + linkLine
     );
@@ -3845,8 +4188,116 @@ async function runMcpServer() {
   await server.connect(transport);
 }
 
+// src/cli/commands/precheck.ts
+import pc6 from "picocolors";
+
+// src/correlate/precheck.ts
+var DEFAULT_RECENT_DAYS = 30;
+function tokensForFile(path) {
+  const base = path.split("/").pop() ?? path;
+  const stem = base.replace(/\.[a-zA-Z0-9]+$/, "");
+  const words = stem.split(/[^a-zA-Z0-9]+/).filter(Boolean);
+  return significantTokens(words.join(" "));
+}
+function assessFiles(store, projectId, paths, opts = {}) {
+  const db = store.raw;
+  const recentDays = opts.recentDays ?? DEFAULT_RECENT_DAYS;
+  const cutoffEpoch = Date.now() - recentDays * 24 * 60 * 60 * 1e3;
+  const findFailures = db.prepare(
+    `SELECT n.id AS id, json_extract(n.meta, '$.command') AS command, n.ts AS ts
+     FROM nodes_fts
+     JOIN nodes n ON n.rowid = nodes_fts.rowid
+     WHERE nodes_fts MATCH ?
+       AND n.project_id = ?
+       AND n.kind = 'shell_command'
+       AND json_extract(n.meta, '$.exitCode') IS NOT NULL
+       AND json_extract(n.meta, '$.exitCode') != 0
+       AND n.ts_epoch >= ?
+       AND n.id NOT IN (SELECT from_node_id FROM node_links WHERE relation IN (?, ?))
+     ORDER BY n.ts_epoch DESC`
+  );
+  const countCommits = db.prepare(
+    `SELECT COUNT(DISTINCT nf.node_id) AS c
+     FROM node_files nf
+     JOIN nodes n ON n.id = nf.node_id
+     WHERE n.project_id = ? AND n.kind = 'git_commit' AND nf.path = ? AND n.ts_epoch >= ?`
+  );
+  return paths.map((path) => {
+    const tokens = filterBoilerplateTokens(db, projectId, tokensForFile(path), ["shell_command"]);
+    const match = tokens.length > 0 ? tokens.map((t) => `"${t}"*`).join(" AND ") : null;
+    const unresolvedFailures = match ? findFailures.all(match, projectId, cutoffEpoch, RESOLVED_BY_RETRY, RESOLVED_BY_DISCUSSION).filter((row) => Boolean(row.command)).map((row) => ({ id: row.id, command: row.command, ts: row.ts })) : [];
+    const commitsRecent = countCommits.get(projectId, path, cutoffEpoch).c;
+    return { path, unresolvedFailures, commitsRecent };
+  });
+}
+
+// src/cli/commands/precheck.ts
+var HIGH_CHURN_THRESHOLD = 4;
+async function stagedFiles(repoRoot) {
+  const out = await git(repoRoot, ["diff", "--cached", "--name-only", "--diff-filter=ACM"]);
+  return out.split("\n").map((line) => line.trim()).filter(Boolean);
+}
+async function workingTreeFiles(repoRoot) {
+  const out = await git(repoRoot, ["diff", "--name-only", "--diff-filter=ACM"]);
+  return out.split("\n").map((line) => line.trim()).filter(Boolean);
+}
+async function runPrecheck(opts) {
+  const out = opts.out ?? ((chunk2) => void process.stderr.write(chunk2));
+  const { repo, ws, projectId } = await loadContext(opts.cwd);
+  const targetFiles = opts.files ?? (opts.working ? await workingTreeFiles(repo.root) : await stagedFiles(repo.root));
+  if (targetFiles.length === 0) {
+    if (!opts.quiet) out(`${pc6.dim("precheck")} no files to check
+`);
+    return 0;
+  }
+  const store = MemoryStore.open(ws.dbPath);
+  let risks;
+  try {
+    risks = assessFiles(store, projectId, targetFiles);
+  } finally {
+    store.close();
+  }
+  const flagged = risks.filter((r) => r.unresolvedFailures.length > 0 || r.commitsRecent >= HIGH_CHURN_THRESHOLD);
+  if (flagged.length === 0) {
+    if (!opts.quiet) out(`${pc6.green("precheck")} no warnings \u2014 looking good
+`);
+    return 0;
+  }
+  out(`
+${pc6.bold("nexusmem precheck")}
+${pc6.dim("-".repeat(40))}
+
+`);
+  for (const risk of flagged) {
+    out(`  ${pc6.bold(risk.path)}
+`);
+    if (risk.unresolvedFailures.length > 0) {
+      out(`    ${pc6.yellow("WARN")}  What already failed here (${risk.unresolvedFailures.length} unresolved):
+`);
+      for (const f of risk.unresolvedFailures.slice(0, 3)) {
+        out(`           ${pc6.dim(`${f.ts.slice(0, 10)}  ${f.command.slice(0, 90)}`)}
+`);
+      }
+      if (risk.unresolvedFailures.length > 3) {
+        out(`           ${pc6.dim(`... and ${risk.unresolvedFailures.length - 3} more`)}
+`);
+      }
+    }
+    if (risk.commitsRecent >= HIGH_CHURN_THRESHOLD) {
+      out(`    ${pc6.yellow("WARN")}  high churn: ${risk.commitsRecent} commits touched this file recently
+`);
+    }
+    out("\n");
+  }
+  const failureCount = flagged.filter((r) => r.unresolvedFailures.length > 0).length;
+  out(`${pc6.dim(`${flagged.length} file(s) flagged, ${failureCount} with unresolved failures.`)}
+`);
+  if (opts.strict && failureCount > 0) return 1;
+  return 0;
+}
+
 // src/cli/commands/query.ts
-import pc5 from "picocolors";
+import pc7 from "picocolors";
 async function runQuery(opts) {
   const { repo, ws, projectId } = await loadContext(opts.cwd);
   const opened = opts.allProjects ? await openAllProjectSources({ projectId, root: repo.root, dbPath: ws.dbPath }) : null;
@@ -3868,15 +4319,15 @@ async function runQuery(opts) {
     const { bm25Count, vectorCount, hits, packed } = result;
     if (opened && !opts.json) {
       const searched = opened.sources.map((s) => s.label).join(", ");
-      process.stderr.write(`${pc5.dim("scope  ")} ${opened.sources.length} project(s): ${searched}
+      process.stderr.write(`${pc7.dim("scope  ")} ${opened.sources.length} project(s): ${searched}
 `);
       for (const { entry } of opened.unreadable) {
-        process.stderr.write(`${pc5.yellow("unreadable")} ${entry.root} -- skipped
+        process.stderr.write(`${pc7.yellow("unreadable")} ${entry.root} -- skipped
 `);
       }
       if (opened.missing.length > 0) {
         process.stderr.write(
-          `${pc5.dim("skipped")} ${opened.missing.length} registered project(s) whose database is not on disk ${pc5.dim("(nexusmem projects --prune to forget them)")}
+          `${pc7.dim("skipped")} ${opened.missing.length} registered project(s) whose database is not on disk ${pc7.dim("(nexusmem projects --prune to forget them)")}
 `
         );
       }
@@ -3906,15 +4357,15 @@ async function runQuery(opts) {
       return 0;
     }
     if (matched === 0) {
-      process.stderr.write(`${pc5.yellow("no matches")} for "${opts.query}"
+      process.stderr.write(`${pc7.yellow("no matches")} for "${opts.query}"
 `);
       return 0;
     }
     process.stderr.write(
       [
-        `${pc5.dim("matched")} ${bm25Count} bm25${vectorCount > 0 ? ` + ${vectorCount} vector` : ""}, packed ${pc5.bold(String(packed.nodes.length))} into budget`,
-        `${pc5.dim("tokens ")} ${packed.tokensUsed}/${packed.tokensBudget}` + (packed.droppedForBudget ? pc5.dim(`  (${packed.droppedForBudget} dropped for budget)`) : "") + (packed.droppedForDiversity ? pc5.dim(`  (${packed.droppedForDiversity} dropped for diversity)`) : ""),
-        rawTokens > 0 ? `${pc5.dim("vs raw ")} ${rawTokens} tokens if these same matches were sent unpacked  ${packerEfficiency >= 0 ? pc5.green(`(${(packerEfficiency * 100).toFixed(0)}% packer efficiency)`) : pc5.yellow(`(${(-packerEfficiency * 100).toFixed(0)}% larger -- overhead dominates on small result sets)`)}` : "",
+        `${pc7.dim("matched")} ${bm25Count} bm25${vectorCount > 0 ? ` + ${vectorCount} vector` : ""}, packed ${pc7.bold(String(packed.nodes.length))} into budget`,
+        `${pc7.dim("tokens ")} ${packed.tokensUsed}/${packed.tokensBudget}` + (packed.droppedForBudget ? pc7.dim(`  (${packed.droppedForBudget} dropped for budget)`) : "") + (packed.droppedForDiversity ? pc7.dim(`  (${packed.droppedForDiversity} dropped for diversity)`) : ""),
+        rawTokens > 0 ? `${pc7.dim("vs raw ")} ${rawTokens} tokens if these same matches were sent unpacked  ${packerEfficiency >= 0 ? pc7.green(`(${(packerEfficiency * 100).toFixed(0)}% packer efficiency)`) : pc7.yellow(`(${(-packerEfficiency * 100).toFixed(0)}% larger -- overhead dominates on small result sets)`)}` : "",
         ""
       ].filter(Boolean).join("\n")
     );
@@ -3928,10 +4379,10 @@ async function runQuery(opts) {
 }
 
 // src/cli/commands/scan-conversation.ts
-import pc7 from "picocolors";
+import pc9 from "picocolors";
 
 // src/cli/format.ts
-import pc6 from "picocolors";
+import pc8 from "picocolors";
 var GIT_SIGNAL_BANDS = { high: 0.7, medium: 0.45 };
 var SHELL_SIGNAL_BANDS = { high: 0.6, medium: 0.4 };
 var CONVERSATION_SIGNAL_BANDS = { high: 0.55, medium: 0.35 };
@@ -3943,9 +4394,9 @@ function signalBand(signal, bands) {
   return "low";
 }
 var BAND_COLOR = {
-  high: pc6.green,
-  medium: pc6.yellow,
-  low: pc6.dim
+  high: pc8.green,
+  medium: pc8.yellow,
+  low: pc8.dim
 };
 function formatSignal(signal, bands) {
   return BAND_COLOR[signalBand(signal, bands)](signal.toFixed(2));
@@ -3958,9 +4409,9 @@ async function runScanConversation(opts) {
   const files = await listTranscriptFiles(repo.root);
   if (!opts.json) {
     process.stderr.write(
-      files.length ? `${pc7.dim("transcripts")} ${files.length} file(s) in ${claudeProjectTranscriptDir(repo.root)}
+      files.length ? `${pc9.dim("transcripts")} ${files.length} file(s) in ${claudeProjectTranscriptDir(repo.root)}
 
-` : `${pc7.yellow("no transcripts found")} at ${claudeProjectTranscriptDir(repo.root)}
+` : `${pc9.yellow("no transcripts found")} at ${claudeProjectTranscriptDir(repo.root)}
 `
     );
   }
@@ -3977,7 +4428,7 @@ async function runScanConversation(opts) {
   const approxTotal = nodes.reduce((n, x) => n + approxTokens(x.body), 0);
   process.stderr.write(
     `
-${pc7.bold(String(nodes.length))} of ${turns.length} exchange(s) above threshold  ${pc7.dim(`~${approxTotal.toLocaleString()} tokens if sent raw`)}` + (redactedTotal > 0 ? `  ${pc7.yellow(`${redactedTotal} secret-like value(s) redacted`)}` : "") + "\n"
+${pc9.bold(String(nodes.length))} of ${turns.length} exchange(s) above threshold  ${pc9.dim(`~${approxTotal.toLocaleString()} tokens if sent raw`)}` + (redactedTotal > 0 ? `  ${pc9.yellow(`${redactedTotal} secret-like value(s) redacted`)}` : "") + "\n"
   );
   return 0;
 }
@@ -3986,20 +4437,20 @@ function formatNode(node) {
 }
 
 // src/cli/commands/scan-diff.ts
-import pc9 from "picocolors";
+import pc11 from "picocolors";
 
 // src/cli/commands/scan-git.ts
-import pc8 from "picocolors";
+import pc10 from "picocolors";
 async function runScanGit(opts) {
   const repo = await readRepoInfo(opts.cwd);
   const projectId = makeProjectId({ root: repo.root, originUrl: repo.originUrl });
   if (!opts.json) {
     process.stderr.write(
       [
-        `${pc8.dim("repo   ")} ${repo.root}`,
-        `${pc8.dim("branch ")} ${repo.branch ?? pc8.yellow("(detached)")}`,
-        `${pc8.dim("origin ")} ${repo.originUrl ?? pc8.dim("(none)")}`,
-        `${pc8.dim("project")} ${pc8.cyan(projectId)}`,
+        `${pc10.dim("repo   ")} ${repo.root}`,
+        `${pc10.dim("branch ")} ${repo.branch ?? pc10.yellow("(detached)")}`,
+        `${pc10.dim("origin ")} ${repo.originUrl ?? pc10.dim("(none)")}`,
+        `${pc10.dim("project")} ${pc10.cyan(projectId)}`,
         ""
       ].join("\n")
     );
@@ -4033,14 +4484,14 @@ function formatNode2(node) {
   const churn = `+${node.meta.insertions ?? 0}/-${node.meta.deletions ?? 0}`;
   return [
     formatSignal(node.signal, GIT_SIGNAL_BANDS),
-    pc8.dim(date),
-    pc8.magenta(sha),
+    pc10.dim(date),
+    pc10.magenta(sha),
     node.title,
-    pc8.dim(`(${files} file${files === 1 ? "" : "s"}, ${churn})`)
+    pc10.dim(`(${files} file${files === 1 ? "" : "s"}, ${churn})`)
   ].join(" ");
 }
 function summarize2(nodes) {
-  if (nodes.length === 0) return pc8.yellow("no commits matched");
+  if (nodes.length === 0) return pc10.yellow("no commits matched");
   const timestamps = nodes.map((n) => n.ts).sort();
   const avgSignal = nodes.reduce((n, x) => n + x.signal, 0) / nodes.length;
   const totalTokens = nodes.reduce((n, x) => n + approxTokens(x.body), 0);
@@ -4050,7 +4501,7 @@ function summarize2(nodes) {
   }
   const hottest = [...fileHits.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5).map(([path, count]) => `    ${String(count).padStart(3)}x ${path}`);
   return [
-    `${pc8.bold(String(nodes.length))} nodes  ${pc8.dim(`${timestamps[0]?.slice(0, 10)} .. ${timestamps.at(-1)?.slice(0, 10)}`)}`,
+    `${pc10.bold(String(nodes.length))} nodes  ${pc10.dim(`${timestamps[0]?.slice(0, 10)} .. ${timestamps.at(-1)?.slice(0, 10)}`)}`,
     `  avg signal ${avgSignal.toFixed(3)}   ~${totalTokens.toLocaleString()} tokens if sent raw`,
     hottest.length ? `  hottest files:
 ${hottest.join("\n")}` : ""
@@ -4065,9 +4516,9 @@ async function runScanDiff(opts) {
   if (!opts.json) {
     process.stderr.write(
       [
-        `${pc9.dim("repo   ")} ${repo.root}`,
-        `${pc9.dim("branch ")} ${repo.branch ?? pc9.yellow("(detached)")}`,
-        `${pc9.dim("project")} ${pc9.cyan(projectId)}`,
+        `${pc11.dim("repo   ")} ${repo.root}`,
+        `${pc11.dim("branch ")} ${repo.branch ?? pc11.yellow("(detached)")}`,
+        `${pc11.dim("project")} ${pc11.cyan(projectId)}`,
         ""
       ].join("\n")
     );
@@ -4097,28 +4548,28 @@ function formatNode3(node) {
   const churn = `+${node.meta.insertions ?? 0}/-${node.meta.deletions ?? 0}`;
   return [
     formatSignal(node.signal, DIFF_SIGNAL_BANDS),
-    pc9.dim(node.ts.slice(0, 10)),
-    pc9.magenta(sha),
+    pc11.dim(node.ts.slice(0, 10)),
+    pc11.magenta(sha),
     String(node.meta.path ?? ""),
-    pc9.dim(`(${churn}, ${node.meta.hunkCount ?? 0} hunk(s))`)
+    pc11.dim(`(${churn}, ${node.meta.hunkCount ?? 0} hunk(s))`)
   ].join(" ");
 }
 
 // src/cli/commands/scan-docs.ts
-import pc10 from "picocolors";
+import pc12 from "picocolors";
 async function runScanDocs(opts) {
   const repo = await readRepoInfo(opts.cwd);
   const projectId = makeProjectId({ root: repo.root, originUrl: repo.originUrl });
   const { files, unreadable } = await readDocFiles(repo.root);
   if (!opts.json) {
     process.stderr.write(
-      files.length ? `${pc10.dim("tracked .md files")} ${files.map((f) => f.path).join(", ")}
+      files.length ? `${pc12.dim("tracked .md files")} ${files.map((f) => f.path).join(", ")}
 
-` : `${pc10.yellow("no tracked .md files found")}
+` : `${pc12.yellow("no tracked .md files found")}
 `
     );
     if (unreadable.length > 0) {
-      process.stderr.write(`${pc10.yellow("unreadable")} ${unreadable.join(", ")}
+      process.stderr.write(`${pc12.yellow("unreadable")} ${unreadable.join(", ")}
 
 `);
     }
@@ -4134,7 +4585,7 @@ async function runScanDocs(opts) {
   const approxTotal = nodes.reduce((n, x) => n + approxTokens(x.body), 0);
   process.stderr.write(
     `
-${pc10.bold(String(nodes.length))} section(s) from ${files.length} file(s) above threshold  ${pc10.dim(`~${approxTotal.toLocaleString()} tokens if sent raw`)}
+${pc12.bold(String(nodes.length))} section(s) from ${files.length} file(s) above threshold  ${pc12.dim(`~${approxTotal.toLocaleString()} tokens if sent raw`)}
 `
   );
   return 0;
@@ -4144,13 +4595,13 @@ function formatNode4(node) {
 }
 
 // src/cli/commands/scan-session.ts
-import pc11 from "picocolors";
+import pc13 from "picocolors";
 async function runScanSession(opts) {
   const repo = await readRepoInfo(opts.cwd);
   const projectId = makeProjectId({ root: repo.root, originUrl: repo.originUrl });
   const turns = await collectClaudeCodeTranscripts(repo.root);
   if (turns.length === 0) {
-    process.stderr.write(`${pc11.yellow("no transcripts found")} at ${claudeProjectTranscriptDir(repo.root)}
+    process.stderr.write(`${pc13.yellow("no transcripts found")} at ${claudeProjectTranscriptDir(repo.root)}
 `);
     return 0;
   }
@@ -4158,7 +4609,7 @@ async function runScanSession(opts) {
   const settled = selectSettledSessions(sessions, opts.settleMinutes);
   if (!opts.json) {
     process.stderr.write(
-      `${pc11.dim("sessions")} ${sessions.length} found, ${settled.length} settled (quiet ${opts.settleMinutes}m+)
+      `${pc13.dim("sessions")} ${sessions.length} found, ${settled.length} settled (quiet ${opts.settleMinutes}m+)
 
 `
     );
@@ -4184,7 +4635,7 @@ async function runScanSession(opts) {
     }
     for (const preview of previews) {
       process.stdout.write(
-        `${pc11.bold(preview.sessionKey)}  ${preview.startedAt.slice(0, 16).replace("T", " ")}  ${preview.includedTurns}/${preview.turns} turn(s), ${preview.promptChars} chars
+        `${pc13.bold(preview.sessionKey)}  ${preview.startedAt.slice(0, 16).replace("T", " ")}  ${preview.includedTurns}/${preview.turns} turn(s), ${preview.promptChars} chars
 ${preview.prompt}
 
 `
@@ -4196,7 +4647,7 @@ ${preview.prompt}
     settleMinutes: opts.settleMinutes,
     maxSessions: opts.maxSessions,
     onProgress: (done, total) => {
-      if (!opts.json) process.stderr.write(`  ${pc11.dim(`summarizing ${done}/${total}`)}
+      if (!opts.json) process.stderr.write(`  ${pc13.dim(`summarizing ${done}/${total}`)}
 `);
     }
   });
@@ -4206,21 +4657,21 @@ ${preview.prompt}
     return 0;
   }
   for (const node of result.nodes) {
-    process.stdout.write(`${pc11.bold(node.title)}
-${pc11.dim(node.ts.slice(0, 16).replace("T", " "))}
+    process.stdout.write(`${pc13.bold(node.title)}
+${pc13.dim(node.ts.slice(0, 16).replace("T", " "))}
 ${node.body}
 
 `);
   }
   if (result.providerUnavailable) {
     process.stderr.write(
-      `${pc11.yellow("model unavailable")} -- is Ollama running with \`${opts.model}\` pulled? (\`ollama pull ${opts.model}\`)
+      `${pc13.yellow("model unavailable")} -- is Ollama running with \`${opts.model}\` pulled? (\`ollama pull ${opts.model}\`)
 `
     );
     return 0;
   }
   process.stderr.write(
-    `${pc11.bold(String(result.nodes.length))} summarized` + (result.failed > 0 ? `, ${pc11.yellow(`${result.failed} failed`)}` : "") + ` ${pc11.dim(`(model ${opts.model})`)}
+    `${pc13.bold(String(result.nodes.length))} summarized` + (result.failed > 0 ? `, ${pc13.yellow(`${result.failed} failed`)}` : "") + ` ${pc13.dim(`(model ${opts.model})`)}
 `
   );
   return 0;
@@ -4228,16 +4679,16 @@ ${node.body}
 var SCAN_SESSION_DEFAULT_MODEL = DEFAULT_SLM_MODEL;
 
 // src/cli/commands/scan-shell.ts
-import pc12 from "picocolors";
+import pc14 from "picocolors";
 async function runScanShell(opts) {
   const repo = await readRepoInfo(opts.cwd);
   const projectId = makeProjectId({ root: repo.root, originUrl: repo.originUrl });
   const results = await collectAvailableShellHistory({ tailLines: opts.tailLines, repoRoot: repo.root });
   if (!opts.json) {
     process.stderr.write(
-      results.length ? `${pc12.dim("sources found")} ${results.map((r) => r.name).join(", ")}
+      results.length ? `${pc14.dim("sources found")} ${results.map((r) => r.name).join(", ")}
 
-` : `${pc12.yellow("no shell history source found on this machine")}
+` : `${pc14.yellow("no shell history source found on this machine")}
 `
     );
   }
@@ -4246,7 +4697,7 @@ async function runScanShell(opts) {
     const nodes = collectShellHistory(result.entries, projectId).filter((n) => n.signal >= opts.minSignal);
     allNodes.push(...nodes);
     if (!opts.json) {
-      process.stdout.write(`${pc12.bold(`shell:${result.name}`)} ${pc12.dim(`(${nodes.length} of ${result.entries.length} above threshold)`)}
+      process.stdout.write(`${pc14.bold(`shell:${result.name}`)} ${pc14.dim(`(${nodes.length} of ${result.entries.length} above threshold)`)}
 `);
       for (const node of nodes) process.stdout.write(`${formatNode5(node)}
 `);
@@ -4259,20 +4710,47 @@ async function runScanShell(opts) {
     return 0;
   }
   const approxTotal = allNodes.reduce((n, x) => n + approxTokens(x.body), 0);
-  process.stderr.write(`${pc12.bold(String(allNodes.length))} node(s) total  ${pc12.dim(`~${approxTotal.toLocaleString()} tokens if sent raw`)}
+  process.stderr.write(`${pc14.bold(String(allNodes.length))} node(s) total  ${pc14.dim(`~${approxTotal.toLocaleString()} tokens if sent raw`)}
 `);
   return 0;
 }
 function formatNode5(node) {
-  const approx = node.meta.tsApprox ? pc12.dim("~") : " ";
+  const approx = node.meta.tsApprox ? pc14.dim("~") : " ";
   const exit = node.meta.exitCode;
-  const exitLabel = typeof exit === "number" && exit !== 0 ? pc12.red(`exit ${exit}`) : "";
+  const exitLabel = typeof exit === "number" && exit !== 0 ? pc14.red(`exit ${exit}`) : "";
   return [formatSignal(node.signal, SHELL_SIGNAL_BANDS), approx + node.ts.slice(0, 16).replace("T", " "), node.title, exitLabel].filter(Boolean).join(" ");
 }
 
+// src/cli/commands/scan-structure.ts
+import pc15 from "picocolors";
+async function runScanStructure(opts) {
+  const repo = await readRepoInfo(opts.cwd);
+  const { edges, filesScanned, unreadable } = await collectFileEdges(repo.root);
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(edges, null, 2)}
+`);
+    return 0;
+  }
+  if (unreadable.length > 0) {
+    process.stderr.write(`${pc15.yellow("unreadable")} ${unreadable.join(", ")}
+
+`);
+  }
+  for (const edge of edges) {
+    process.stdout.write(`${edge.fromPath} ${pc15.dim("->")} ${edge.toPath}
+`);
+  }
+  process.stderr.write(
+    `
+${pc15.bold(String(edges.length))} edge(s) from ${filesScanned} tracked .ts/.tsx/.js/.jsx file(s)
+`
+  );
+  return 0;
+}
+
 // src/cli/commands/status.ts
 import { statSync } from "fs";
-import pc13 from "picocolors";
+import pc16 from "picocolors";
 function humanBytes(bytes) {
   if (bytes < 1024) return `${bytes} B`;
   if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
@@ -4286,6 +4764,7 @@ function fileSize(path) {
   }
 }
 async function runStatus(opts) {
+  const out = opts.out ?? ((chunk2) => void process.stdout.write(chunk2));
   const { repo, ws, projectId } = await loadContext(opts.cwd);
   const store = MemoryStore.open(ws.dbPath);
   try {
@@ -4293,28 +4772,38 @@ async function runStatus(opts) {
     const sources = store.listSyncState(projectId);
     const gitCursor = sources.find((s) => s.source === "git")?.cursor ?? null;
     const schema = currentSchemaVersion(store.raw);
+    const chains = getChainStats(store, projectId);
+    const otherProjectIds = store.listOtherProjectIds(projectId);
+    const otherProjectNodes = store.countProjectNodes(otherProjectIds);
+    const structure = store.fileEdgeStats(projectId);
     const dbBytes = fileSize(ws.dbPath) + fileSize(`${ws.dbPath}-wal`);
     const kinds = Object.entries(stats.byKind).sort((a, b) => b[1] - a[1]).map(([kind, n]) => `    ${String(n).padStart(6)}  ${kind}`);
-    process.stdout.write(
+    const staleProjectWarning = otherProjectIds.length ? `${pc16.yellow("stale   ")} ${otherProjectIds.length} prior project ${otherProjectIds.length === 1 ? "identity holds" : "identities hold"} ${otherProjectNodes} node(s) \u2014 run ${pc16.bold(
+      "nexusmem sync --prune-source <name>"
+    )} to remove stale source data` : "";
+    out(
       [
-        `${pc13.dim("repo    ")} ${repo.root}`,
-        `${pc13.dim("branch  ")} ${repo.branch ?? pc13.yellow("(detached)")}`,
-        `${pc13.dim("project ")} ${pc13.cyan(projectId)}`,
-        `${pc13.dim("schema  ")} v${schema}${schema === LATEST_SCHEMA_VERSION ? "" : pc13.yellow(` (latest is v${LATEST_SCHEMA_VERSION})`)}`,
-        `${pc13.dim("database")} ${ws.dbPath} ${pc13.dim(`(${humanBytes(dbBytes)})`)}`,
+        `${pc16.dim("repo    ")} ${repo.root}`,
+        `${pc16.dim("branch  ")} ${repo.branch ?? pc16.yellow("(detached)")}`,
+        `${pc16.dim("project ")} ${pc16.cyan(projectId)}`,
+        `${pc16.dim("schema  ")} v${schema}${schema === LATEST_SCHEMA_VERSION ? "" : pc16.yellow(` (latest is v${LATEST_SCHEMA_VERSION})`)}`,
+        `${pc16.dim("database")} ${ws.dbPath} ${pc16.dim(`(${humanBytes(dbBytes)})`)}`,
+        staleProjectWarning,
         "",
-        `${pc13.bold(String(stats.total))} node(s)${stats.total ? ` ${pc13.dim(`${stats.oldest?.slice(0, 10)} .. ${stats.newest?.slice(0, 10)}`)}` : ""}`,
+        `${pc16.bold(String(stats.total))} node(s)${stats.total ? ` ${pc16.dim(`${stats.oldest?.slice(0, 10)} .. ${stats.newest?.slice(0, 10)}`)}` : ""}`,
         ...kinds,
-        stats.total ? `    ${pc13.dim(`${stats.distinctFiles} distinct file path(s)`)}` : "",
+        stats.total ? `    ${pc16.dim(`${stats.distinctFiles} distinct file path(s)`)}` : "",
         "",
-        sources.length ? pc13.dim("sources") : pc13.yellow("no sources synced yet"),
+        sources.length ? pc16.dim("sources") : pc16.yellow("no sources synced yet"),
         ...sources.map((s) => {
           const when = s.lastRunAt ? new Date(s.lastRunAt).toISOString().slice(0, 16).replace("T", " ") : "never";
           const cursorLabel = s.source === "git" ? s.cursor?.slice(0, 7) ?? "-" : s.cursor ?? "-";
-          return `    ${s.source.padEnd(14)} ${pc13.dim(`last run ${when}`)}  ${pc13.dim(`cursor ${cursorLabel}`)}`;
+          return `    ${s.source.padEnd(14)} ${pc16.dim(`last run ${when}`)}  ${pc16.dim(`cursor ${cursorLabel}`)}`;
         }),
-        gitCursor && gitCursor !== repo.head ? `${pc13.yellow("git behind HEAD")} \u2014 run ${pc13.bold("nexusmem sync")}` : "",
-        ""
+        gitCursor && gitCursor !== repo.head ? `${pc16.yellow("git behind HEAD")} \u2014 run ${pc16.bold("nexusmem sync")}` : "",
+        "",
+        chains.failuresTotal ? `${pc16.dim("chains  ")} ${pc16.bold(String(chains.resolvedTotal))}/${chains.failuresTotal} failure(s) resolved ${pc16.dim(`(${chains.resolvedByRetry} retry, ${chains.resolvedByDiscussion} discussion)`)}${chains.resolvedTotal < chains.failuresTotal ? ` \u2014 run ${pc16.bold("nexusmem sync --link-failures")} to link more` : ""}` : "",
+        structure.edges ? `${pc16.dim("structure")} ${pc16.bold(String(structure.edges))} import edge(s) across ${structure.files} file(s)` : ""
       ].filter((line) => line !== "").join("\n").concat("\n")
     );
     return 0;
@@ -4329,7 +4818,7 @@ function isExpected(err) {
   // the user fixes, not stack traces they debug.
   err instanceof GitSpawnError || // Survived every retry, so git is genuinely unstable on this machine
   // (antivirus, a bad install). Actionable, and not our stack to print.
-  err instanceof GitCrashError || err instanceof ConfigError || err instanceof ProfileNotFoundError;
+  err instanceof GitCrashError || err instanceof ConfigError || err instanceof ProfileNotFoundError || err instanceof ForeignGitHookError;
 }
 function guard(run) {
   return async () => {
@@ -4337,7 +4826,7 @@ function guard(run) {
       process.exitCode = await run();
     } catch (err) {
       if (isExpected(err)) {
-        process.stderr.write(`${pc14.red("error")} ${err.message}
+        process.stderr.write(`${pc17.red("error")} ${err.message}
 `);
         process.exitCode = 1;
         return;
@@ -4390,6 +4879,14 @@ program.command("hook").description("Manage the opt-in PowerShell hook that logs
   new Command("remove").description("Remove the hook block from your PowerShell profile").option("--profile <path>", "override the auto-detected $PROFILE path").action((options) => guard(() => runHookRemove({ profile: options.profile }))())
 ).addCommand(
   new Command("status").description("Show whether the hook is installed").option("--profile <path>", "override the auto-detected $PROFILE path").action((options) => guard(() => runHookStatus({ profile: options.profile }))())
+).addCommand(
+  new Command("git").description("Manage the opt-in git pre-commit hook that runs `nexusmem precheck` before each commit").addCommand(
+    new Command("install").description("Install (or update) the hook in .git/hooks/pre-commit").option("-C, --cwd <path>", "repository path", process.cwd()).option("--force", "append after an existing foreign pre-commit hook instead of refusing", false).action((options) => guard(() => runHookGitInstall({ cwd: options.cwd, force: options.force }))())
+  ).addCommand(
+    new Command("remove").description("Remove nexusmem's block from .git/hooks/pre-commit").option("-C, --cwd <path>", "repository path", process.cwd()).action((options) => guard(() => runHookGitRemove({ cwd: options.cwd }))())
+  ).addCommand(
+    new Command("status").description("Show whether the git pre-commit hook is installed").option("-C, --cwd <path>", "repository path", process.cwd()).action((options) => guard(() => runHookGitStatus({ cwd: options.cwd }))())
+  )
 );
 program.command("status").description("Show what is currently remembered for this repository").option("-C, --cwd <path>", "repository path", process.cwd()).action((options) => guard(() => runStatus({ cwd: options.cwd }))());
 program.command("query").description("Search remembered history and print a token-budgeted context block").argument("<text>", "free-text query").option("-C, --cwd <path>", "repository path", process.cwd()).option("-b, --budget <tokens>", "max tokens in the packed context", (v) => Number.parseInt(v, 10), 2e3).option("-n, --candidates <count>", "how many search hits to rank before packing", (v) => Number.parseInt(v, 10), 30).option("--half-life <days>", "days for a node's recency weight to halve", (v) => Number.parseFloat(v)).option("--no-vector", "BM25 only -- skip embedding the query and vector search").option("-a, --all-projects", "search every registered repository, not just this one", false).option("--json", "emit the packed result as JSON on stdout", false).action(
@@ -4451,10 +4948,22 @@ program.command("scan-session").description("Preview the session summaries a loc
   )()
 );
 program.command("scan-docs").description("Preview the MemoryNodes tracked .md files would produce (writes nothing)").option("-C, --cwd <path>", "repository path", process.cwd()).option("--min-signal <score>", "drop nodes below this signal", (v) => Number.parseFloat(v), 0).option("--json", "emit MemoryNodes as JSON on stdout", false).action((options) => guard(() => runScanDocs({ cwd: options.cwd, minSignal: options.minSignal, json: options.json }))());
+program.command("precheck").description("Warn about staged files with unresolved past failures or high recent churn (advisory, exits 0 unless --strict)").option("-C, --cwd <path>", "repository path", process.cwd()).option("--files <paths...>", "check exactly these repo-relative paths instead of what is staged").option("--working", "check the working tree (unstaged changes) instead of what is staged for commit", false).option("--strict", "exit 1 when any file has an unresolved failure", false).option("-q, --quiet", "only print output when there is something to warn about", false).action(
+  (options) => guard(
+    () => runPrecheck({
+      cwd: options.cwd,
+      files: options.files,
+      working: options.working,
+      strict: options.strict,
+      quiet: options.quiet
+    })
+  )()
+);
+program.command("scan-structure").description("Preview the JS/TS import-graph edges a sync would produce (writes nothing)").option("-C, --cwd <path>", "repository path", process.cwd()).option("--json", "emit edges as JSON on stdout", false).action((options) => guard(() => runScanStructure({ cwd: options.cwd, json: options.json }))());
 program.command("mcp").description("Start the MCP server (stdio transport) for Claude Desktop, Cursor, Windsurf, etc.").action(() => guard(() => runMcpServer().then(() => 0))());
 program.parseAsync(process.argv).catch((err) => {
   const message = err instanceof Error ? err.message : String(err);
-  process.stderr.write(`${pc14.red("error")} ${message}
+  process.stderr.write(`${pc17.red("error")} ${message}
 `);
   process.exitCode = 1;
 });