@polycode-projects/seonix 0.6.0 → 0.7.0

package/src/extract.mjs

@@ -18,15 +18,18 @@
 //   mgx:subclassOf          Class  → Class    (inheritance; internal base resolved, else ext:)
 
 import { spawn } from "node:child_process";
-import { writeFile, mkdir, readdir, stat } from "node:fs/promises";
+import { writeFile, readFile, rename, rm, mkdir, readdir, stat } from "node:fs/promises";
 import { basename, dirname, join, parse, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import * as codegraph from "./codegraph.mjs"; // optional renderToolsCatalog (other agent owns this file)
-import { ingestRepo, LANG_EXTS } from "./extract_lang.mjs";
+import { ingestRepo, LANG_EXTS, REGISTRY } from "./extract_lang.mjs";
 import { loadIgnores } from "./walk.mjs";
 import { attachProseTokens, buildProseIndex } from "./prose.mjs";
 import { ingestSchemaDocs } from "./schema-docs.mjs";
 import { foldInSessions, readSessionRecords } from "./sessions.mjs";
+import { encodeGraphV2 } from "./graph-format.mjs";
+import { buildSummary, writeSummaryArtifacts } from "./summary.mjs";
+import { fingerprintRepo, readManifest, writeManifest, diffManifest } from "./manifest.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const AST_SCRIPT = join(here, "extract_ast.py");
@@ -64,17 +67,39 @@ function historySymbolDepth(env = process.env) {
   return Number.isFinite(n) && n >= 0 ? Math.floor(n) : HISTORY_SYMBOL_DEPTH;
 }
 
-/** spawn, collect stdout; resolve {code, stdout, stderr} (never reject). */
-function exec(cmd, args, { cwd, maxBuffer = 512 * 1024 * 1024 } = {}) {
+// Git-history passes are the one place seonix shells an unbounded command over
+// arbitrary repo history, so they get a hard wall-clock timeout (A5): a wedged or
+// pathological `git log` can never hang an index. On fire we SIGKILL the child and
+// resolve a synthetic failure ({code:-1, timedOut:true}) rather than rejecting.
+const GIT_TIMEOUT_MS = 300_000;
+
+/** spawn, collect stdout; resolve {code, stdout, stderr, timedOut, truncated}
+ *  (never reject). `timeout` (ms, >0) arms a SIGKILL wall-clock; `truncated` is set
+ *  when stdout exceeded maxBuffer (silently dropped bytes → an incomplete result the
+ *  caller must NOT treat as authoritative). Exported for the A5 timeout unit test. */
+export function exec(cmd, args, { cwd, maxBuffer = 512 * 1024 * 1024, timeout = 0 } = {}) {
   return new Promise((resolve) => {
     const child = spawn(cmd, args, { cwd });
     let stdout = "";
     let stderr = "";
     let size = 0;
-    child.stdout?.on("data", (d) => { size += d.length; if (size <= maxBuffer) stdout += d; });
+    let truncated = false;
+    let timedOut = false;
+    const timer = timeout > 0 ? setTimeout(() => { timedOut = true; child.kill("SIGKILL"); }, timeout) : null;
+    child.stdout?.on("data", (d) => { size += d.length; if (size <= maxBuffer) stdout += d; else truncated = true; });
     child.stderr?.on("data", (d) => (stderr += d));
-    child.on("close", (code) => resolve({ code: code ?? -1, stdout, stderr }));
-    child.on("error", (err) => resolve({ code: -1, stdout, stderr: stderr + String(err) }));
+    child.on("close", (code) => {
+      if (timer) clearTimeout(timer);
+      if (timedOut) {
+        resolve({ code: -1, stdout, stderr: stderr + `timed out after ${Math.round(timeout / 1000)}s`, timedOut: true, truncated });
+      } else {
+        resolve({ code: code ?? -1, stdout, stderr, timedOut: false, truncated });
+      }
+    });
+    child.on("error", (err) => {
+      if (timer) clearTimeout(timer);
+      resolve({ code: -1, stdout, stderr: stderr + String(err), timedOut, truncated });
+    });
   });
 }
 
@@ -108,16 +133,30 @@ async function runAst(repoPath, python) {
 export const GIT_LOG_EXCLUDE = ["corpus", "target", "vendor", "infra/cdk.out", "results"];
 const gitPathspecExcludes = () => GIT_LOG_EXCLUDE.map((p) => `:(exclude)${p}`);
 
-/** git log → [{sha, author, date, subject, files[]}] over the last N commits
- *  (best-effort; [] if no repo). Header record fields are \x1e-separated; commits
- *  are \x1f-separated; the subject (%s) is single-line so it never collides with
- *  the per-file lines that follow. */
+/** A one-line failure reason for a git-history exec, or null on clean success.
+ *  Partial parseable output is ALWAYS kept by the caller — this only records WHY the
+ *  result may be incomplete (timeout / non-zero exit / maxBuffer truncation) so an
+ *  index never silently loses history edges without saying so. */
+function gitPassError({ code, stderr, timedOut, truncated }) {
+  if (timedOut) return "timed out after 300s";
+  if (code !== 0) {
+    const tail = String(stderr || "").trim().split("\n").pop()?.slice(-200) || "";
+    return `git exited ${code}${tail ? `: ${tail}` : ""}`;
+  }
+  if (truncated) return "output truncated — history incomplete";
+  return null;
+}
+
+/** git log → {commits:[{sha, author, date, subject, files[]}], error}. Header
+ *  record fields are \x1e-separated; commits are \x1f-separated; the subject (%s) is
+ *  single-line so it never collides with the per-file lines that follow. Parseable
+ *  output is always returned even on failure; `error` is a one-line reason or null. */
 async function runGitLog(repoPath, depth = gitDepth()) {
-  const { code, stdout } = await exec("git",
+  const res = await exec("git",
     ["log", `-n`, String(depth), "--no-renames", "--name-only",
       "--pretty=format:%x1f%H%x1e%an%x1e%aI%x1e%s", "--", ".", ...gitPathspecExcludes()],
-    { cwd: repoPath });
-  if (code !== 0) return [];
+    { cwd: repoPath, timeout: GIT_TIMEOUT_MS });
+  const { stdout } = res;
   const out = [];
   for (const chunk of stdout.split("\x1f")) {
     const nl = chunk.indexOf("\n");
@@ -129,21 +168,22 @@ async function runGitLog(repoPath, depth = gitDepth()) {
       .split("\n").map((l) => l.trim()).filter(isIndexedFile);
     out.push({ sha: sha.trim(), author, date, subject, files });
   }
-  return out;
+  return { commits: out, error: gitPassError(res) };
 }
 
-/** git log -p --unified=0 → [{sha, ranges: {path: [[start,end], …]}}] for the
- *  symbol-granular history pass. Parses the NEW-side hunk header (`+c,d`) into the
- *  changed line range; extract.mjs intersects those with the (current) symbol spans.
- *  This is the costly history pass, so it runs at the budgeted (capped) depth.
- *  Best-effort: [] on any git failure or depth 0. */
+/** git log -p --unified=0 → {hunks:[{sha, ranges: {path: [[start,end], …]}}], error}
+ *  for the symbol-granular history pass. Parses the NEW-side hunk header (`+c,d`) into
+ *  the changed line range; extract.mjs intersects those with the (current) symbol
+ *  spans. This is the costly history pass, so it runs at the budgeted (capped) depth.
+ *  Parseable output is always returned even on failure; `error` is a one-line reason
+ *  or null. Depth 0 → no pass ({hunks:[], error:null}). */
 async function runGitLogHunks(repoPath, depth = historySymbolDepth()) {
-  if (!depth) return [];
-  const { code, stdout } = await exec("git",
+  if (!depth) return { hunks: [], error: null };
+  const res = await exec("git",
     ["log", `-n`, String(depth), "--no-renames", "--no-color", "--unified=0",
       "--pretty=format:%x1f%H", "--", ".", ...gitPathspecExcludes()],
-    { cwd: repoPath });
-  if (code !== 0) return [];
+    { cwd: repoPath, timeout: GIT_TIMEOUT_MS });
+  const { stdout } = res;
   const out = [];
   let cur = null;
   let file = null;
@@ -170,7 +210,7 @@ async function runGitLogHunks(repoPath, depth = historySymbolDepth()) {
       cur.ranges[file].push(count > 0 ? [start, start + count - 1] : [start, start]);
     }
   }
-  return out;
+  return { hunks: out, error: gitPassError(res) };
 }
 
 /** Build the `entities` payload from the parsed modules + git history.
@@ -618,35 +658,119 @@ function localToolsCatalog(cliPath) {
 
 const DEFAULT_PYTHON = () => process.env.SEONIX_PYTHON || process.env.SEON_PYTHON || "python3";
 
+/** Emit one immediate stderr WARNING per collected gitError so a git-history pass that
+ *  failed (timeout / truncation / broken repo) is never invisible — the graph is still
+ *  built, just without those edges. `who` is the repo prefix (multi) or path (single). */
+function warnGitErrors(gitErrors, who) {
+  for (const { pass, message } of gitErrors || []) {
+    process.stderr.write(`seonix: WARNING ${who}: git history pass '${pass}' failed — ${message} (graph built without those edges)\n`);
+  }
+}
+
+/** OR-combine two ignore matchers (either may be null). Returns null when both are null, the
+ *  sole non-null matcher when only one is set (reference-preserving → byte-identical default),
+ *  or a predicate true when EITHER matches. */
+function combineIgnores(a, b) {
+  if (a && b) return (rel) => a(rel) || b(rel);
+  return a || b || null;
+}
+
+/** Extension → language gate for the `languages` allowlist. A module survives when its
+ *  extension belongs to an allowed language (python owns `.py`; the front-end languages own
+ *  their REGISTRY exts). `null` allowlist → every module (today's behavior, byte-identical). */
+function moduleLangAllowed(path, langAllowed) {
+  if (!langAllowed) return true;
+  const dot = path.lastIndexOf(".");
+  const ext = dot >= 0 ? path.slice(dot).toLowerCase() : "";
+  if (ext === ".py") return langAllowed.has("python");
+  for (const [lang, r] of Object.entries(REGISTRY)) {
+    if (r.exts.includes(ext)) return langAllowed.has(lang);
+  }
+  return true; // extension owned by no known language — never dropped by the gate
+}
+
+// seonix.toml [index].languages uses friendly names ("javascript", "typescript", "csharp");
+// the extractor REGISTRY is keyed "js/ts" / "c#". Canonicalise the allowlist to the extractor
+// keys — WITHOUT this, a languages list of friendly names silently drops every JS/TS/C# module
+// (none would match a REGISTRY key), as this repo's own seonix.toml self-index did.
+const LANG_CANON = {
+  javascript: "js/ts", typescript: "js/ts", js: "js/ts", ts: "js/ts", jsts: "js/ts", "js/ts": "js/ts",
+  csharp: "c#", cs: "c#", dotnet: "c#", "c#": "c#",
+  python: "python", py: "python", java: "java",
+};
+const canonicalLang = (l) => LANG_CANON[String(l).toLowerCase()] ?? String(l).toLowerCase();
+
 /** One repo's raw extraction — parsers + git, NO graph assembly. Both index modes
  *  build on this; multi-repo runs it repo-by-repo so only one repo's raw source
- *  (parser/git-log output) is in memory at a time. */
-async function extractRepo(repoPath, { python = DEFAULT_PYTHON(), ignores = true } = {}) {
+ *  (parser/git-log output) is in memory at a time.
+ *  `extraIgnores` (a matcher, e.g. compileGlobs of seonix.toml [index].exclude/secret_exclude)
+ *  composes with the repo's .seonixignore; `languages` (allowlist) gates which extractors run
+ *  and which modules survive. Both absent → today's behavior byte-identical. */
+async function extractRepo(repoPath, { python = DEFAULT_PYTHON(), ignores = true, historyDepth, extraIgnores = null, languages } = {}) {
   const t0 = Date.now();
-  // `.seonixignore` (opt-out: `ignores:false`, the benchmark rig's flag). The matcher
-  // prunes the in-process walkers (extract_lang) at parse time; the module filter below
+  // `.seonixignore` (opt-out: `ignores:false`, the benchmark rig's flag), OR-composed with the
+  // seonix.toml [index] exclude/secret_exclude matcher forwarded as `extraIgnores`. The combined
+  // matcher prunes the in-process walkers (extract_lang) at parse time; the module filter below
   // is the AUTHORITATIVE cut — it also covers extractors that walk on their own
   // (extract_ast.py, the Java fat-jar, Roslyn), and buildEntities drops history edges
   // for any module not in the list, so the whole graph honours the same exclusions.
-  const ignore = ignores ? await loadIgnores(repoPath) : null;
+  // Absent extraIgnores → the bare .seonixignore matcher (same reference → byte-identical).
+  const baseIgnore = ignores ? await loadIgnores(repoPath) : null;
+  const ignore = combineIgnores(baseIgnore, extraIgnores);
+  // `languages` (seonix.toml [index].languages) — an allowlist gating which extractors run and
+  // which modules survive. Absent (or empty) → every language, byte-identical to today. Present →
+  // the Python `runAst` runs only when "python" is listed, the language front-end only when a
+  // language it owns is listed, and any surviving module whose extension belongs to a non-listed
+  // language is dropped from the final set (buildEntities then drops that module's history too).
+  const langAllowed = Array.isArray(languages) && languages.length ? new Set(languages.map(canonicalLang)) : null;
+  const runPython = !langAllowed || langAllowed.has("python");
+  const runLangs = !langAllowed || Object.keys(REGISTRY).some((k) => langAllowed.has(k));
+
+  // A5 `history_depth` — unified cap over BOTH git passes:
+  //   undefined → today's defaults exactly (gitDepth()/historySymbolDepth()), byte-identical.
+  //   0         → skip BOTH passes entirely (no git shelled, no commits/touches/cochange).
+  //   N>0       → both passes capped at N (`git log -n N`; the symbol pass uses N, not 120).
+  const skipHistory = historyDepth === 0;
+  const nameDepth = historyDepth === undefined ? gitDepth() : historyDepth;
+  const symbolDepth = historyDepth === undefined ? historySymbolDepth() : historyDepth;
+  // A git-less repo is a first-class supported case — no `.git` means no history, silently.
+  // A PRESENT-but-broken `.git` (e.g. a `gitdir:` pointer to nowhere) is a real failure we
+  // surface as a gitError, so we only skip-silently when there is genuinely no repo to read.
+  const hasGit = skipHistory ? false : await stat(join(repoPath, ".git")).then(() => true).catch(() => false);
+
+  const gitErrors = []; // [{pass, message}] — one-line reasons the history may be incomplete
   // base extraction: ast (Python) + multi-language front-end (TS/JS, C#) + module-level
   // git history (the cheap, full-depth pass). The Python and language passes are
   // independent parsers; their `{modules:[…]}` outputs share one contract and are merged
   // (dedupe by path — Python from runAst wins) before buildEntities.
-  const [pyModules, langResult, commits] = await Promise.all([
-    runAst(repoPath, python),
-    ingestRepo(repoPath, { ignore }),
-    runGitLog(repoPath, gitDepth()),
+  const [pyModules, langResult, gitLog] = await Promise.all([
+    runPython ? runAst(repoPath, python) : Promise.resolve([]),
+    runLangs ? ingestRepo(repoPath, { ignore }) : Promise.resolve({ modules: [], perLang: {} }),
+    hasGit ? runGitLog(repoPath, nameDepth) : Promise.resolve({ commits: [], error: null }),
   ]);
+  const commits = gitLog.commits;
+  if (gitLog.error) gitErrors.push({ pass: "name-only", message: gitLog.error });
   const seenPaths = new Set(pyModules.map((m) => m.path));
   const merged = [...pyModules, ...langResult.modules.filter((m) => !seenPaths.has(m.path))];
-  const modules = ignore ? merged.filter((m) => !ignore(m.path)) : merged;
+  // Authoritative cut: drop ignored paths AND modules of a non-listed language (both no-ops when
+  // extraIgnores/languages are absent → byte-identical). perLang is filtered to listed languages.
+  const modules = merged.filter((m) => (!ignore || !ignore(m.path)) && moduleLangAllowed(m.path, langAllowed));
+  const perLang = langAllowed
+    ? Object.fromEntries(Object.entries(langResult.perLang).filter(([lang]) => langAllowed.has(lang)))
+    : langResult.perLang;
   const baseMs = Date.now() - t0;
   // added symbol-history pass (the costly per-commit hunk diff) — budgeted via depth
   const tHist = Date.now();
-  const symbolHistory = await runGitLogHunks(repoPath, historySymbolDepth());
+  const runSymbol = hasGit && symbolDepth > 0;
+  const hunks = runSymbol ? await runGitLogHunks(repoPath, symbolDepth) : { hunks: [], error: null };
+  const symbolHistory = hunks.hunks;
+  if (hunks.error) gitErrors.push({ pass: "symbol-hunk", message: hunks.error });
   const historyMs = Date.now() - tHist;
-  return { modules, perLang: langResult.perLang, commits, symbolHistory, baseMs, historyMs };
+  return {
+    modules, perLang, commits, symbolHistory, baseMs, historyMs, gitErrors,
+    // effective depths actually applied (0 when a pass was skipped: history_depth:0 or no .git)
+    historyDepth: { name: hasGit ? nameDepth : 0, symbol: runSymbol ? symbolDepth : 0 },
+  };
 }
 
 /** Assemble entities from (possibly merged) extractions and write the artifacts
@@ -665,7 +789,35 @@ async function assembleAndWrite(rootDir, { modules, commits, symbolHistory, gene
   if (sessions.length) foldInSessions(entities, sessions);
   const graphFile = join(rootDir, ".seonix", "graph.json");
   await mkdir(dirname(graphFile), { recursive: true });
-  await writeFile(graphFile, JSON.stringify(entities));
+  // A6 wire format. The interned v2 form is the on-disk DEFAULT: it is fully wired on the READ
+  // side (source.mjs / parseEntities / sessions write-back / chronograph all expand it
+  // transparently) and proven byte-transparent by test/graph-format.test.mjs (digest/locate/
+  // describe parity) + the multi-repo golden. Any reader of the RAW graph.json must run it
+  // through `expandGraphPayload` first. Opt OUT to the legacy v1 form with SEONIX_GRAPH_FORMAT=1.
+  // `encodeGraphV2` does NOT mutate `entities`, so the C12 writeStore below still consumes the
+  // format-agnostic in-memory object (stamped with the SAME on-disk bytes via `sourceText`).
+  const wireV2 = process.env.SEONIX_GRAPH_FORMAT !== "1";
+  const payload = JSON.stringify(wireV2 ? encodeGraphV2(entities) : entities);
+  await writeFile(graphFile, payload);
+  const graphBytes = payload.length; // chars ≈ bytes; feeds the A1 summary's size + cap headroom
+
+  // C12 (opt-in): SEONIX_STORE=sqlite → also build the resident node:sqlite store from
+  // the same in-memory payload, stamped with the JSON's stat for freshness. Mirrors the
+  // SEONIX_PROSE_INDEX env-gate precedent; unset → no import of node:sqlite, no graph.db,
+  // byte-identical default path. Best-effort: graph.json stays authoritative on any failure.
+  if (process.env.SEONIX_STORE === "sqlite") {
+    try {
+      const { writeStore, storeFileFor } = await import("./store.mjs");
+      const sourceStat = await stat(graphFile);
+      // `sourceText: payload` = the exact bytes just written to graph.json (v2 by default, or v1).
+      // Without it writeStore would hash JSON.stringify(entities) — the v1 form — against a v2 disk
+      // file, so verifyStore/readPayload-freshness would fail on every fresh v2 store. Mirrors
+      // bin/cli.mjs store_rebuild (which passes sourceText: text).
+      await writeStore(storeFileFor(graphFile), entities, { sourceStat, sourceText: payload });
+    } catch (e) {
+      process.stderr.write(`seonix: sqlite store build failed (${e?.message || e}) — graph.json is authoritative\n`);
+    }
+  }
 
   // TOOLS.md catalog (prefer the other agent's renderToolsCatalog when it lands).
   // TODO: switch to codegraph.renderToolsCatalog(CLI_SCRIPT) once that export exists.
@@ -673,7 +825,7 @@ async function assembleAndWrite(rootDir, { modules, commits, symbolHistory, gene
     ? codegraph.renderToolsCatalog(CLI_SCRIPT)
     : localToolsCatalog(CLI_SCRIPT);
   await writeFile(join(rootDir, ".seonix", "TOOLS.md"), toolsMd);
-  return { entities, graphFile };
+  return { entities, graphFile, graphBytes };
 }
 
 function buildCounts(entities, { modules, languages, commits, proseEnabled, baseMs, historyMs }) {
@@ -703,15 +855,36 @@ function buildCounts(entities, { modules, languages, commits, proseEnabled, base
  * symbol-history (line-range) pass so the latter can be kept within the ≤10% budget.
  * @returns {Promise<{graphFile, counts}>}
  */
-export async function indexRepository(repoPath, { python = DEFAULT_PYTHON(), generatedAt = "", ignores = true } = {}) {
+export async function indexRepository(repoPath, { python = DEFAULT_PYTHON(), generatedAt = "", ignores = true, historyDepth, extraIgnores = null, languages } = {}) {
   // Second pass (PLAN_PROSE_INDEX.md): on by default; SEONIX_PROSE_INDEX=0 disables it
   // (mirrors SEONIX_HISTORY_SYMBOL_DEPTH=0's disable convention above).
   const proseEnabled = process.env.SEONIX_PROSE_INDEX !== "0";
-  const { modules, perLang, commits, symbolHistory, baseMs, historyMs } = await extractRepo(repoPath, { python, ignores });
+  const r = await extractRepo(repoPath, { python, ignores, historyDepth, extraIgnores, languages });
+  const { modules, perLang, commits, symbolHistory, baseMs, historyMs, gitErrors } = r;
+  warnGitErrors(gitErrors, repoPath); // surface any history-pass failure immediately (never fatal)
   const sessions = await readSessionRecords(repoPath); // recorded chat sessions (.seonix/sessions/*.jsonl), [] when none
-  const { entities, graphFile } = await assembleAndWrite(repoPath, { modules, commits, symbolHistory, generatedAt, proseEnabled, sessions });
+  const { entities, graphFile, graphBytes } = await assembleAndWrite(repoPath, { modules, commits, symbolHistory, generatedAt, proseEnabled, sessions });
+  // A1 post-index summary: SUMMARY.md + summary.json next to graph.json (NEW files; the
+  // graph.json bytes are untouched). The rendered MD is also printed to stdout by cli.mjs.
+  const summary = buildSummary(entities, {
+    mode: "single",
+    repos: [{
+      name: basename(resolve(repoPath)),
+      modules: modules.length,
+      commits: commits.length,
+      historyDepth: r.historyDepth,
+      gitErrors,
+    }],
+    skipped: [],
+    languages: perLang,
+    graphBytes,
+  });
+  await writeSummaryArtifacts(dirname(graphFile), summary);
   return {
     graphFile,
+    gitErrors,               // [{pass, message}] — [] on a clean build (A5; for the later summary/manifest)
+    historyDepth: r.historyDepth, // effective per-pass depths actually applied
+    summary,                 // A1: the buildSummary object (cli renders it to stdout)
     counts: buildCounts(entities, { modules: modules.length, languages: perLang, commits: commits.length, proseEnabled, baseMs, historyMs }),
   };
 }
@@ -775,7 +948,8 @@ export function defaultOutRoot(repoPaths, cwd = process.cwd()) {
 /** Discovery for the estate case: every immediate child directory of `multiRoot`
  *  that carries a `.git` (dir OR file — worktrees/submodules have .git files) is a
  *  repo. Dot-dirs are ignored outright; plain child dirs without .git are returned
- *  as `skipped` so the caller can log them. */
+ *  as `skipped` ([{name, reason}]) so the caller can log them and the A1 summary can
+ *  record why each was left out. */
 export async function discoverRepos(multiRoot) {
   const root = resolve(multiRoot);
   const entries = await readdir(root, { withFileTypes: true });
@@ -788,7 +962,7 @@ export async function discoverRepos(multiRoot) {
       await stat(join(root, e.name, ".git"));
       repos.push(join(root, e.name));
     } catch {
-      skipped.push(e.name);
+      skipped.push({ name: e.name, reason: "no .git marker" });
     }
   }
   return { repos, skipped };
@@ -802,7 +976,7 @@ export async function discoverRepos(multiRoot) {
  * `log` (optional) receives one progress line per repo.
  * @returns {Promise<{graphFile, outRoot, repos, counts}>}
  */
-export async function indexRepositories(repoPaths, { python = DEFAULT_PYTHON(), generatedAt = "", ignores = true, outRoot = "", log = () => {} } = {}) {
+export async function indexRepositories(repoPaths, { python = DEFAULT_PYTHON(), generatedAt = "", ignores = true, outRoot = "", log = () => {}, historyDepth, skipped = [], extraIgnores = null, languages: languageAllow } = {}) {
   const paths = [...new Set((repoPaths || []).map((p) => resolve(p)))];
   if (!paths.length) throw new Error("indexRepositories requires at least one repo path");
   const proseEnabled = process.env.SEONIX_PROSE_INDEX !== "0";
@@ -818,7 +992,8 @@ export async function indexRepositories(repoPaths, { python = DEFAULT_PYTHON(),
   let historyMs = 0;
   for (const rp of paths) {
     const prefix = prefixes.get(rp);
-    const r = await extractRepo(rp, { python, ignores });
+    const r = await extractRepo(rp, { python, ignores, historyDepth, extraIgnores, languages: languageAllow });
+    warnGitErrors(r.gitErrors, prefix); // surface any history-pass failure immediately (never fatal)
     applyRepoPrefix(r, prefix);
     allModules.push(...r.modules);
     allCommits.push(...r.commits);
@@ -829,20 +1004,202 @@ export async function indexRepositories(repoPaths, { python = DEFAULT_PYTHON(),
       const agg = languages[lang] || (languages[lang] = { lib: s.lib, files: 0, modules: 0, symbols: 0, failures: 0, ms: 0 });
       agg.files += s.files; agg.modules += s.modules; agg.symbols += s.symbols; agg.failures += s.failures; agg.ms += s.ms;
     }
-    repos.push({ path: rp, prefix, modules: r.modules.length, commits: r.commits.length });
+    // per-repo return rows carry the effective history depth + any git errors (A5;
+    // consumed by the later summary/manifest items — buildEntities stays untouched here).
+    repos.push({ path: rp, prefix, modules: r.modules.length, commits: r.commits.length, gitErrors: r.gitErrors, historyDepth: r.historyDepth });
     log(`indexed ${prefix} (${rp}): ${r.modules.length} modules, ${r.commits.length} commits in ${r.baseMs + r.historyMs}ms`);
   }
 
   // TODO(sessions): multi-repo merges don't fold in the member repos' .seonix/sessions
   // yet — their recorded ids would need the same repo-name prefixing as modules to
   // re-resolve against the merged graph. Deferred; single-path fold-in is the contract.
-  const { entities, graphFile } = await assembleAndWrite(root, {
+  const { entities, graphFile, graphBytes } = await assembleAndWrite(root, {
     modules: allModules, commits: allCommits, symbolHistory: allSymbolHistory, generatedAt, proseEnabled,
   });
+  // A1 post-index summary (merged): per-repo rows (name = prefix) + any discovery
+  // `skipped` rows threaded through by the cli. NEW files next to graph.json.
+  const summary = buildSummary(entities, {
+    mode: "multi",
+    repos: repos.map((rr) => ({
+      name: rr.prefix,
+      modules: rr.modules,
+      commits: rr.commits,
+      historyDepth: rr.historyDepth,
+      gitErrors: rr.gitErrors,
+    })),
+    skipped,
+    languages,
+    graphBytes,
+  });
+  await writeSummaryArtifacts(dirname(graphFile), summary);
   return {
     graphFile,
     outRoot: root,
     repos,
+    summary,                 // A1: the buildSummary object (cli renders it to stdout)
+    counts: buildCounts(entities, { modules: allModules.length, languages, commits: allCommits.length, proseEnabled, baseMs, historyMs }),
+  };
+}
+
+// ── A7: estate manifest + incremental sync ───────────────────────────────────
+// syncRepositories re-indexes a multi_root estate incrementally: fingerprint every
+// child repo (manifest.mjs), diff against the on-disk manifest, and RE-EXTRACT only the
+// added/changed repos (plus any unchanged repo whose extraction cache is missing —
+// self-heal). Every other repo's (post-prefix) extraction is reloaded from a per-repo
+// cache at `.seonix/cache/<name>.json`. The union of all repos' extractions then flows
+// through ONE buildEntities pass, exactly as a from-scratch multi index would.
+//
+// SEMANTIC CAVEAT: buildEntities resolves calls/inherits/bases through a GLOBAL
+// unique-name registry that spans EVERY repo, so per-repo sub-graphs can NOT simply be
+// concatenated (cross-repo name collisions change resolution). That is why the default
+// sync path re-runs the single union buildEntities over the cached+fresh extractions —
+// it is bit-for-bit the full-re-index result. graph-ops.dropByRepoPrefix is the
+// removals-only fast path (approximate for additions; see its header), not used here.
+//
+// The per-repo cache is written ONLY on sync runs; a normal index writes no cache, so
+// its artifacts stay byte-identical.
+
+const CACHE_SUBDIR = "cache";
+const cachePath = (artifactDir, name) => join(artifactDir, CACHE_SUBDIR, `${name}.json`);
+
+async function readCache(artifactDir, name) {
+  return JSON.parse(await readFile(cachePath(artifactDir, name), "utf8"));
+}
+async function writeCache(artifactDir, name, payload) {
+  await mkdir(join(artifactDir, CACHE_SUBDIR), { recursive: true });
+  const p = cachePath(artifactDir, name);
+  const tmp = `${p}.tmp-${process.pid}`;
+  await writeFile(tmp, JSON.stringify(payload));
+  await rename(tmp, p);
+}
+const cacheExists = (artifactDir, name) => stat(cachePath(artifactDir, name)).then(() => true).catch(() => false);
+
+/** Every immediate, non-dot child DIRECTORY of `root` (absolute paths, sorted). Broader
+ *  than discoverRepos (which requires a .git marker) because sync fingerprints plain-dir
+ *  and git-subdir members too — classification is manifest.fingerprintRepo's job. */
+async function discoverSyncRepos(root) {
+  const entries = await readdir(root, { withFileTypes: true });
+  return entries
+    .filter((e) => e.isDirectory() && !e.name.startsWith("."))
+    .map((e) => e.name)
+    .sort()
+    .map((name) => join(root, name));
+}
+
+/**
+ * Incrementally (re-)index a multi_root estate. Fingerprint → diff manifest → re-extract
+ * only the changed members → ONE buildEntities over the union (cached + fresh) →
+ * assembleAndWrite + summary + manifest, all via temp+rename. When NOTHING changed
+ * (and every cache is present) it is a byte-stable no-op — no artifact is rewritten.
+ * `log` receives one line per re-extracted repo (and the "N unchanged" no-op line).
+ * @returns {Promise<{graphFile, outRoot, noop, added, changed, removed, reextracted, unchanged, summary?, counts?}>}
+ */
+export async function syncRepositories(multiRoot, { python = DEFAULT_PYTHON(), generatedAt = "", ignores = true, historyDepth, log = () => {} } = {}) {
+  const root = resolve(multiRoot);
+  const artifactDir = join(root, ".seonix");
+  const proseEnabled = process.env.SEONIX_PROSE_INDEX !== "0";
+
+  const paths = await discoverSyncRepos(root);
+  if (!paths.length) throw new Error(`sync: ${root} has no child repositories`);
+  const prefixes = assignRepoPrefixes(paths);
+
+  // Fingerprint every member → the "current" rows (name = the graph-id prefix so the
+  // manifest, the cache keys and dropByRepoPrefix all agree on one repo identity).
+  const current = [];
+  for (const rp of paths) {
+    const name = prefixes.get(rp);
+    const fp = await fingerprintRepo(rp, { multiRoot: root });
+    current.push({ name, path: rp, kind: fp.kind, fingerprint: fp.fingerprint });
+  }
+
+  const prev = await readManifest(artifactDir);
+  const diff = diffManifest(current, prev.repos || []);
+
+  // Members to re-extract: added + changed, plus any UNCHANGED member whose per-repo
+  // cache file is missing (self-heal — the cache is the reuse contract).
+  const reason = new Map();
+  for (const r of diff.added) reason.set(r.name, "added");
+  for (const r of diff.changed) reason.set(r.name, "changed");
+  for (const r of diff.unchanged) {
+    if (!(await cacheExists(artifactDir, r.name))) reason.set(r.name, "cache-miss");
+  }
+
+  // Byte-stable no-op: nothing added/changed/removed and every cache present → do NOT
+  // rewrite any artifact (graph.json keeps its exact bytes + mtime).
+  if (reason.size === 0 && !diff.removed.length) {
+    log(`${current.length} repo(s) unchanged`);
+    return {
+      graphFile: join(artifactDir, "graph.json"), outRoot: root, noop: true,
+      added: [], changed: [], removed: [], reextracted: [],
+      unchanged: current.map((r) => r.name),
+    };
+  }
+
+  const allModules = [];
+  const allCommits = [];
+  const allSymbolHistory = [];
+  const languages = {};
+  const repoRows = [];      // → buildSummary repos
+  const manifestRows = [];  // → the rewritten manifest
+  const reextracted = [];
+  let baseMs = 0;
+  let historyMs = 0;
+
+  for (const rp of paths) {
+    const name = prefixes.get(rp);
+    const row = current.find((r) => r.name === name);
+    let ext;
+    if (reason.has(name)) {
+      log(`re-extracting ${name} (${reason.get(name)})`);
+      const r = await extractRepo(rp, { python, ignores, historyDepth });
+      warnGitErrors(r.gitErrors, name);
+      applyRepoPrefix(r, name); // prefix in place → the cache stores the POST-prefix extraction
+      ext = {
+        modules: r.modules, commits: r.commits, symbolHistory: r.symbolHistory,
+        perLang: r.perLang, historyDepth: r.historyDepth, gitErrors: r.gitErrors,
+        fingerprint: row.fingerprint,
+      };
+      await writeCache(artifactDir, name, ext);
+      baseMs += r.baseMs; historyMs += r.historyMs;
+      reextracted.push(name);
+    } else {
+      ext = await readCache(artifactDir, name); // reused post-prefix extraction
+    }
+    allModules.push(...ext.modules);
+    allCommits.push(...ext.commits);
+    allSymbolHistory.push(...ext.symbolHistory);
+    for (const [lang, s] of Object.entries(ext.perLang || {})) {
+      const agg = languages[lang] || (languages[lang] = { lib: s.lib, files: 0, modules: 0, symbols: 0, failures: 0, ms: 0 });
+      agg.files += s.files; agg.modules += s.modules; agg.symbols += s.symbols; agg.failures += s.failures; agg.ms += s.ms;
+    }
+    repoRows.push({ name, modules: ext.modules.length, commits: ext.commits.length, historyDepth: ext.historyDepth, gitErrors: ext.gitErrors || [] });
+    const head = row.fingerprint.head ?? row.fingerprint.walk ?? "";
+    manifestRows.push({
+      name, path: rp, kind: row.kind, fingerprint: row.fingerprint,
+      history_depth: ext.historyDepth, indexed_at_head: head,
+      modules: ext.modules.length, commits: ext.commits.length,
+    });
+  }
+
+  // Drop stale caches for removed members (their rows/ids fall out of the union rebuild).
+  for (const r of diff.removed) await rm(cachePath(artifactDir, r.name), { force: true }).catch(() => {});
+
+  // ONE buildEntities over the union (cached + fresh) → the exact full-re-index graph.
+  const { entities, graphFile, graphBytes } = await assembleAndWrite(root, {
+    modules: allModules, commits: allCommits, symbolHistory: allSymbolHistory, generatedAt, proseEnabled,
+  });
+  const summary = buildSummary(entities, { mode: "multi", repos: repoRows, skipped: [], languages, graphBytes });
+  await writeSummaryArtifacts(dirname(graphFile), summary);
+  await writeManifest(artifactDir, { format: 1, generated_at: generatedAt, repos: manifestRows });
+
+  return {
+    graphFile, outRoot: root, noop: false,
+    added: diff.added.map((r) => r.name),
+    changed: diff.changed.map((r) => r.name),
+    removed: diff.removed.map((r) => r.name),
+    reextracted,
+    unchanged: diff.unchanged.map((r) => r.name).filter((n) => !reextracted.includes(n)),
+    summary,
     counts: buildCounts(entities, { modules: allModules.length, languages, commits: allCommits.length, proseEnabled, baseMs, historyMs }),
   };
 }