@bendyline/gezel-service 0.1.0 → 1.0.0

package/dist/index-store/static-index-worker.js

@@ -4,10 +4,10 @@
 import { parentPort } from "worker_threads";
 
 // src/index-store/content-indexer.ts
-import { readFile as readFile3 } from "fs/promises";
-import { extname as extname3 } from "path";
+import { readFile as readFile3, readdir as readdir2, rm as rm4, stat as stat3 } from "fs/promises";
+import { extname as extname3, join as join10 } from "path";
 import { nowIso as nowIso2 } from "@bendyline/gezel";
-import { projectLocalIndexDbFile } from "@bendyline/gezel/paths";
+import { PROJECT_SHADOW_DIR_NAME as PROJECT_SHADOW_DIR_NAME2, projectLocalIndexDbFile } from "@bendyline/gezel/paths";
 
 // src/security/code-patterns.ts
 var EVIDENCE_CAP = 160;
@@ -560,7 +560,17 @@ var CODE_LANGS = {
   bash: "bash",
   zsh: "bash",
   lua: "lua",
-  sql: "sql"
+  sql: "sql",
+  // Web-source formats. Without these a project's index.html fell through to
+  // kind 'other' — no review rubric, no security scan, excluded from every
+  // coverage denominator — while the status popover read "complete". Symbol
+  // extraction still gates on GRAMMAR_FILE separately, so a lang here without
+  // a wired grammar degrades to zero symbols, not an error.
+  html: "html",
+  htm: "html",
+  css: "css",
+  vue: "vue",
+  svelte: "svelte"
 };
 var MARKDOWN_EXTS = /* @__PURE__ */ new Set(["md", "mdx", "markdown"]);
 var DOC_EXTS = /* @__PURE__ */ new Set(["docx", "pptx", "xlsx", "pdf", "odt", "odp", "ods", "rtf"]);
@@ -612,14 +622,11 @@ var BINARY_EXTS = /* @__PURE__ */ new Set([
   "avi",
   "mkv",
   "webm",
-  "mp3",
-  "wav",
-  "flac",
-  "ogg",
   "db",
   "sqlite",
   "lock"
 ]);
+var AUDIO_EXTS = /* @__PURE__ */ new Set(["mp3", "wav", "flac", "ogg", "oga", "m4a", "aac", "opus"]);
 var MAX_INDEXABLE_BYTES = 512 * 1024;
 var DENSE_BLOB_MIN_BYTES = 100 * 1024;
 var DENSE_BLOB_BYTES_PER_LINE = 1e3;
@@ -645,6 +652,7 @@ function classifyFile(path, size) {
   }
   if (DOC_EXTS.has(ext)) return { lang: null, kind: "doc", modality: "doc", trivial: false };
   if (IMAGE_EXTS.has(ext)) return { lang: null, kind: "image", modality: "image", trivial: false };
+  if (AUDIO_EXTS.has(ext)) return { lang: null, kind: "audio", modality: "audio", trivial: false };
   if (CONFIG_EXTS.has(ext)) {
     return { lang: ext, kind: "config", modality: "text", trivial: size > MAX_INDEXABLE_BYTES };
   }
@@ -663,8 +671,8 @@ function triv(kind) {
 
 // src/index-store/docs.ts
 import { mkdir, readFile as readFile2, stat as stat2 } from "fs/promises";
-import { basename as basename2, dirname as dirname4, extname as extname2, join as join5, relative as relative2 } from "path";
-import { projectLocalFilesDir } from "@bendyline/gezel/paths";
+import { basename as basename3, dirname as dirname5, extname as extname2, join as join6, relative as relative2 } from "path";
+import { PROJECT_SHADOW_DIR_NAME } from "@bendyline/gezel/paths";
 
 // src/fs/atomic.ts
 import { randomUUID } from "crypto";
@@ -737,12 +745,101 @@ async function renameWithWindowsRetry(from, to) {
   }
 }
 
+// src/fs/safe-paths.ts
+import { realpath as realpath2 } from "fs/promises";
+import { basename as basename2, dirname as dirname2, isAbsolute, join as join2, normalize, sep } from "path";
+function pathEq(a, b) {
+  if (process.platform === "win32" || process.platform === "darwin") {
+    return a.toLowerCase() === b.toLowerCase();
+  }
+  return a === b;
+}
+function pathStartsWithDir(candidate, base) {
+  if (process.platform === "win32" || process.platform === "darwin") {
+    return candidate.toLowerCase().startsWith(base.toLowerCase() + sep.toLowerCase());
+  }
+  return candidate.startsWith(base + sep);
+}
+function safeJoin(base, relPath) {
+  if (typeof relPath !== "string") return null;
+  if (hasUnsafePortableSegment(relPath)) return null;
+  if (isAbsolute(relPath)) return null;
+  const normalizedBase = normalize(base);
+  const candidate = normalize(join2(normalizedBase, relPath));
+  if (pathEq(candidate, normalizedBase)) return candidate;
+  if (pathStartsWithDir(candidate, normalizedBase)) return candidate;
+  return null;
+}
+async function realpathContained(base, fullPath) {
+  const realBase = await realpathSafe(base);
+  if (!realBase) return false;
+  const realTarget = await realpathNearest(fullPath);
+  if (!realTarget) return false;
+  if (pathEq(realTarget, realBase)) return true;
+  return pathStartsWithDir(realTarget, realBase);
+}
+async function realpathSafe(p) {
+  try {
+    return normalize(await realpath2(p));
+  } catch {
+    return null;
+  }
+}
+async function realpathNearest(p) {
+  const direct = await realpathSafe(p);
+  if (direct) return direct;
+  const parent = dirname2(p);
+  if (parent === p) return null;
+  const realParent = await realpathNearest(parent);
+  if (!realParent) return null;
+  return normalize(join2(realParent, basename2(p)));
+}
+var RESERVED_WINDOWS_BASENAMES = /* @__PURE__ */ new Set([
+  "CON",
+  "PRN",
+  "AUX",
+  "NUL",
+  "COM1",
+  "COM2",
+  "COM3",
+  "COM4",
+  "COM5",
+  "COM6",
+  "COM7",
+  "COM8",
+  "COM9",
+  "LPT1",
+  "LPT2",
+  "LPT3",
+  "LPT4",
+  "LPT5",
+  "LPT6",
+  "LPT7",
+  "LPT8",
+  "LPT9"
+]);
+function isReservedWindowsName(name) {
+  if (!name) return false;
+  const normalized = name.replace(/[ .]+$/g, "");
+  const base = (normalized.split(".")[0] ?? "").replace(/[ ]+$/g, "");
+  return RESERVED_WINDOWS_BASENAMES.has(base.toUpperCase());
+}
+function hasUnsafePortableSegment(relPath) {
+  if (relPath.includes("\0") || relPath.startsWith("\\\\")) return true;
+  const segments = relPath.split(/[\\/]+/);
+  return segments.some((segment) => {
+    if (!segment || segment === "." || segment === "..") return false;
+    if (segment.includes(":") || /[ .]$/.test(segment)) return true;
+    return isReservedWindowsName(segment);
+  });
+}
+
 // src/index-store/sandbox-convert.ts
 import { existsSync as existsSync2 } from "fs";
-import { mkdtemp as mkdtemp2, readFile, realpath as realpath3, rm as rm3, stat, writeFile as writeFile3 } from "fs/promises";
+import { mkdtemp as mkdtemp2, readFile, realpath as realpath4, rm as rm3, stat, writeFile as writeFile3 } from "fs/promises";
 import { createRequire } from "module";
 import { tmpdir as tmpdir2 } from "os";
-import { dirname as dirname3, join as join4 } from "path";
+import { dirname as dirname4, join as join5 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { createLogger } from "@bendyline/gezel";
 
@@ -911,9 +1008,9 @@ function sniffContainer(bytes, ext) {
 
 // src/sandbox/runner.ts
 import { spawn as spawn2 } from "child_process";
-import { mkdtemp, realpath as realpath2, rm as rm2, writeFile as writeFile2 } from "fs/promises";
+import { mkdtemp, realpath as realpath3, rm as rm2, writeFile as writeFile2 } from "fs/promises";
 import { tmpdir } from "os";
-import { isAbsolute, join as join2 } from "path";
+import { isAbsolute as isAbsolute2, join as join3 } from "path";
 import { pathToFileURL } from "url";
 import { windowsDetachedSpawnOptions } from "@bendyline/gezel/native";
 
@@ -966,11 +1063,11 @@ async function runInSandbox(opts) {
     for (const line of splitLines(result.stderr)) opts.onStderr?.(line);
     return result;
   }
-  const workdir = await realpath2(await mkdtemp(join2(tmpdir(), "gezel-task-")));
+  const workdir = await realpath3(await mkdtemp(join3(tmpdir(), "gezel-task-")));
   try {
-    const cwd = await realpath2(opts.cwd).catch(() => opts.cwd);
-    const entryCandidate = isAbsolute(opts.entry) ? opts.entry : join2(cwd, opts.entry);
-    const entry = await realpath2(entryCandidate).catch(() => opts.entry);
+    const cwd = await realpath3(opts.cwd).catch(() => opts.cwd);
+    const entryCandidate = isAbsolute2(opts.entry) ? opts.entry : join3(cwd, opts.entry);
+    const entry = await realpath3(entryCandidate).catch(() => opts.entry);
     const readPaths = await expandPermissionPaths([
       opts.cwd,
       workdir,
@@ -979,7 +1076,7 @@ async function runInSandbox(opts) {
     const writePaths = await expandPermissionPaths([opts.cwd, workdir]);
     const netBlockArgs = [];
     if (opts.denyNet) {
-      const preloadPath = join2(workdir, "__net_block.mjs");
+      const preloadPath = join3(workdir, "__net_block.mjs");
       await writeFile2(preloadPath, NET_BLOCK_PRELOAD, "utf8");
       netBlockArgs.push(`--import=${pathToFileURL(preloadPath).href}`);
     }
@@ -1210,7 +1307,7 @@ async function expandPermissionPaths(paths) {
   const expanded = [];
   const seen = /* @__PURE__ */ new Set();
   for (const p of paths) {
-    for (const candidate of [p, await realpath2(p).catch(() => p)]) {
+    for (const candidate of [p, await realpath3(p).catch(() => p)]) {
       if (seen.has(candidate)) continue;
       seen.add(candidate);
       expanded.push(candidate);
@@ -1448,7 +1545,7 @@ syncBuiltinESMExports();
 
 // src/utils/service-worker-entry.ts
 import { existsSync } from "fs";
-import { dirname as dirname2, join as join3, resolve } from "path";
+import { dirname as dirname3, join as join4, resolve } from "path";
 import { fileURLToPath } from "url";
 var SERVICE_WORKER_ENTRIES = {
   embeddings: { built: "memory/embed-worker.js" },
@@ -1461,10 +1558,10 @@ var SERVICE_WORKER_ENTRIES = {
 };
 var MAX_ANCESTOR_DEPTH = 8;
 function findServiceBundleResource(moduleUrl, relativePaths) {
-  let dir = dirname2(fileURLToPath(moduleUrl));
+  let dir = dirname3(fileURLToPath(moduleUrl));
   const visited = /* @__PURE__ */ new Set();
   for (let depth = 0; depth < MAX_ANCESTOR_DEPTH; depth++) {
-    for (const root of [dir, join3(dir, "dist")]) {
+    for (const root of [dir, join4(dir, "dist")]) {
       for (const relativePath of relativePaths) {
         const candidate = resolve(root, relativePath);
         if (visited.has(candidate)) continue;
@@ -1472,7 +1569,7 @@ function findServiceBundleResource(moduleUrl, relativePaths) {
         if (existsSync(candidate)) return candidate;
       }
     }
-    const parent = dirname2(dir);
+    const parent = dirname3(dir);
     if (parent === dir) break;
     dir = parent;
   }
@@ -1494,8 +1591,8 @@ function findRepoRoot(start) {
   let dir = start;
   let highest = null;
   for (; ; ) {
-    if (existsSync2(join4(dir, "node_modules"))) highest = dir;
-    const parent = dirname3(dir);
+    if (existsSync2(join5(dir, "node_modules"))) highest = dir;
+    const parent = dirname4(dir);
     if (parent === dir) break;
     dir = parent;
   }
@@ -1505,12 +1602,12 @@ var readRootsCache;
 function sandboxReadRoots() {
   if (readRootsCache !== void 0) return readRootsCache;
   const roots = /* @__PURE__ */ new Set();
-  const repoRoot = findRepoRoot(dirname3(fileURLToPath2(import.meta.url)));
+  const repoRoot = findRepoRoot(dirname4(fileURLToPath2(import.meta.url)));
   if (repoRoot) roots.add(repoRoot);
   try {
     const require2 = createRequire(import.meta.url);
     const resolved = require2.resolve("@bendyline/squisq-formats");
-    const linkedRoot = findRepoRoot(dirname3(resolved));
+    const linkedRoot = findRepoRoot(dirname4(resolved));
     if (linkedRoot) roots.add(linkedRoot);
   } catch {
     readRootsCache = null;
@@ -1557,10 +1654,10 @@ async function convertInSandbox(absPath, ext) {
     log.warn("sandbox unavailable (worker or node_modules root unresolved); skipping conversion");
     return { markdown: null };
   }
-  const scratch = await realpath3(await mkdtemp2(join4(tmpdir2(), "gezel-convert-")));
+  const scratch = await realpath4(await mkdtemp2(join5(tmpdir2(), "gezel-convert-")));
   try {
     const inputName = `input.${ext}`;
-    await writeFile3(join4(scratch, inputName), bytes);
+    await writeFile3(join5(scratch, inputName), bytes);
     const res = await runInSandbox({
       entry: worker.path,
       cwd: scratch,
@@ -1585,7 +1682,7 @@ async function convertInSandbox(absPath, ext) {
       );
       return { markdown: null };
     }
-    const md = await readFile(join4(scratch, "output.md"), "utf8").catch(() => null);
+    const md = await readFile(join5(scratch, "output.md"), "utf8").catch(() => null);
     return { markdown: md };
   } finally {
     await rm3(scratch, { recursive: true, force: true });
@@ -1603,16 +1700,19 @@ async function convertDocToMarkdown(absPath) {
   if (!isConvertibleDoc(ext)) return { markdown: null };
   return convertInSandbox(absPath, ext);
 }
-function filesPaths(filesRoot, relPath, relativeRoot) {
-  const base = basename2(relPath);
-  const nameNoExt = base.replace(/\.[^.]+$/, "");
-  const parent = dirname4(relPath);
-  const dir = join5(filesRoot, parent === "." ? "" : parent, `${nameNoExt}_files`);
-  const mdPath = join5(dir, `${nameNoExt}.md`);
-  return { dir, mdPath, mdRel: relative2(relativeRoot, mdPath).replaceAll("\\", "/") };
-}
-function docFilesPaths(workspaceDir, relPath) {
-  return filesPaths(projectLocalFilesDir(workspaceDir), relPath, workspaceDir);
+function shadowDocFilesPaths(artifactsDir, relPath) {
+  const base = basename3(relPath);
+  const nameNoExt = base.replace(/\.[^.]+$/, "") || base;
+  const parent = dirname5(relPath);
+  const relMd = join6(parent === "." ? "" : parent, `${base}_files`, `${nameNoExt}.md`);
+  const shadowRoot = join6(artifactsDir, PROJECT_SHADOW_DIR_NAME);
+  const mdPath = safeJoin(shadowRoot, relMd);
+  if (!mdPath) return null;
+  return {
+    dir: dirname5(mdPath),
+    mdPath,
+    mdRel: relative2(artifactsDir, mdPath).replaceAll("\\", "/")
+  };
 }
 async function writeConvertedMarkdownAt(paths, markdown) {
   await mkdir(paths.dir, { recursive: true });
@@ -1637,6 +1737,15 @@ async function ensureConvertedMarkdownSidecar(sourcePath, paths) {
   }
   return { ...converted, paths };
 }
+async function ensureShadowDocSidecar(sourceAbs, artifactsDir, relPath) {
+  const paths = shadowDocFilesPaths(artifactsDir, relPath);
+  if (!paths) return null;
+  const shadowRoot = join6(artifactsDir, PROJECT_SHADOW_DIR_NAME);
+  await mkdir(shadowRoot, { recursive: true }).catch(() => {
+  });
+  if (!await realpathContained(shadowRoot, paths.mdPath)) return null;
+  return ensureConvertedMarkdownSidecar(sourceAbs, paths);
+}
 function chunkMarkdown(md) {
   const lines = md.split(/\r?\n/);
   const headIdx = [];
@@ -1684,8 +1793,8 @@ function parseFrontmatter(content) {
 
 // src/index-store/gitignore.ts
 import { mkdir as mkdir2, writeFile as writeFile4 } from "fs/promises";
-import { join as join6 } from "path";
-import { projectLocalFilesDir as projectLocalFilesDir2, projectLocalIndexDir } from "@bendyline/gezel/paths";
+import { join as join7 } from "path";
+import { projectLocalIndexDir } from "@bendyline/gezel/paths";
 
 // src/index-store/hash.ts
 import { createHash } from "crypto";
@@ -1994,7 +2103,7 @@ import { createLogger as createLogger3 } from "@bendyline/gezel";
 
 // src/transformers-cache.ts
 import { mkdir as mkdir3 } from "fs/promises";
-import { join as join7 } from "path";
+import { join as join8 } from "path";
 import { createLogger as createLogger2 } from "@bendyline/gezel";
 var log2 = createLogger2("service");
 
@@ -2103,6 +2212,10 @@ CREATE TABLE IF NOT EXISTS summaries (
   summary_md TEXT,
   tags TEXT,
   model TEXT,
+  provider TEXT,
+  gezel_id TEXT,
+  gezel_name TEXT,
+  app_version TEXT,
   created_at TEXT
 );
 
@@ -2219,6 +2332,10 @@ CREATE TABLE IF NOT EXISTS symbol_summaries (
   symbol_name TEXT NOT NULL,
   summary TEXT NOT NULL,
   model TEXT,
+  provider TEXT,
+  gezel_id TEXT,
+  gezel_name TEXT,
+  app_version TEXT,
   created_at TEXT,
   PRIMARY KEY (collection_id, file_path, file_hash, symbol_name)
 );
@@ -2235,6 +2352,10 @@ CREATE TABLE IF NOT EXISTS area_summaries (
   input_hash TEXT NOT NULL,
   summary_md TEXT NOT NULL,
   model TEXT,
+  provider TEXT,
+  gezel_id TEXT,
+  gezel_name TEXT,
+  app_version TEXT,
   created_at TEXT,
   PRIMARY KEY (collection_id, area_path)
 );
@@ -2258,12 +2379,30 @@ CREATE TABLE IF NOT EXISTS file_reviews (
   health INTEGER,
   health_reason TEXT,
   model TEXT,
+  provider TEXT,
+  gezel_id TEXT,
+  gezel_name TEXT,
+  app_version TEXT,
   reviewed_at TEXT,
   attempt_rubric_hash TEXT,
   attempts INTEGER DEFAULT 0,
   last_attempt_at TEXT
 );
 
+-- AI-shadow gate (images described by the vision model, audio transcribed by
+-- STT into artifacts/shadow markdown). Same content-addressed discipline as
+-- enrichments: 'ok' rows survive renames/reverts; failures retry up to a cap
+-- per hash. The sidecar file is the artifact; this row is only the work gate.
+CREATE TABLE IF NOT EXISTS shadow_state (
+  content_hash TEXT PRIMARY KEY,
+  collection_id TEXT,
+  file_path TEXT,
+  state TEXT,
+  attempts INTEGER DEFAULT 0,
+  model TEXT,
+  updated_at TEXT
+);
+
 -- Mirror of the append-only history JSONL (the audit log). kind/project/gezel/at
 -- are real columns so HistoryFilter fields stay SQL-filterable; only the q text
 -- goes through fts_history. INSERT OR IGNORE on the event id makes JSONL
@@ -2292,7 +2431,7 @@ CREATE VIRTUAL TABLE IF NOT EXISTS fts_metadata
 CREATE VIRTUAL TABLE IF NOT EXISTS fts_history
   USING fts5(body, event_id UNINDEXED, collection_id UNINDEXED);
 `;
-var SCHEMA_VERSION = 9;
+var SCHEMA_VERSION = 10;
 function addColumnIfMissing(db, table, column, decl) {
   try {
     const cols = db.prepare(`PRAGMA table_info(${table})`).all();
@@ -2316,6 +2455,12 @@ function applySchema(db) {
       WHERE fingerprint IS NULL OR fingerprint = ''`);
   } catch {
   }
+  for (const table of ["summaries", "symbol_summaries", "area_summaries", "file_reviews"]) {
+    addColumnIfMissing(db, table, "provider", "TEXT");
+    addColumnIfMissing(db, table, "gezel_id", "TEXT");
+    addColumnIfMissing(db, table, "gezel_name", "TEXT");
+    addColumnIfMissing(db, table, "app_version", "TEXT");
+  }
   let fts = true;
   try {
     db.exec(FTS_DDL);
@@ -2343,7 +2488,7 @@ function applySchema(db) {
 // src/index-store/sqlite-driver.ts
 import { mkdir as mkdir4, rename as rename2 } from "fs/promises";
 import { createRequire as createRequire2 } from "module";
-import { dirname as dirname5 } from "path";
+import { dirname as dirname6 } from "path";
 import { createLogger as createLogger4 } from "@bendyline/gezel";
 var nodeRequire = createRequire2(import.meta.url);
 var log4 = createLogger4("sqlite");
@@ -2366,7 +2511,7 @@ async function openIndexDatabase(dbPath) {
   }
   if (dbPath !== ":memory:") {
     try {
-      await mkdir4(dirname5(dbPath), { recursive: true });
+      await mkdir4(dirname6(dbPath), { recursive: true });
     } catch (error) {
       if (isUnavailableIndexError(error)) return null;
       throw error;
@@ -2375,6 +2520,7 @@ async function openIndexDatabase(dbPath) {
   let db;
   try {
     db = new DatabaseSync(dbPath, { allowExtension: true });
+    setBusyTimeout(db);
     assertReadableHeader(db);
   } catch (error) {
     if (dbPath === ":memory:" || !isCorruptDatabaseError(error)) {
@@ -2391,6 +2537,7 @@ async function openIndexDatabase(dbPath) {
     await quarantineCorruptDatabase(dbPath);
     log4.warn(`[sqlite] quarantined corrupt rebuildable index ${dbPath}`);
     db = new DatabaseSync(dbPath, { allowExtension: true });
+    setBusyTimeout(db);
   }
   if (!db) throw new Error("failed to open sqlite index");
   let vecAvailable = false;
@@ -2439,6 +2586,12 @@ async function openIndexDatabase(dbPath) {
 function assertReadableHeader(db) {
   db.prepare("PRAGMA schema_version").get();
 }
+function setBusyTimeout(db) {
+  try {
+    db.exec("PRAGMA busy_timeout=5000;");
+  } catch {
+  }
+}
 function isCorruptDatabaseError(error) {
   const message = error instanceof Error ? error.message : String(error);
   return /SQLITE_CORRUPT|SQLITE_NOTADB|database disk image is malformed|file is not a database/i.test(
@@ -2447,9 +2600,7 @@ function isCorruptDatabaseError(error) {
 }
 function isUnavailableIndexError(error) {
   const message = error instanceof Error ? error.message : String(error);
-  return /SQLITE_READONLY|SQLITE_CANTOPEN|SQLITE_BUSY|SQLITE_LOCKED|EACCES|EPERM|read-only/i.test(
-    message
-  );
+  return /SQLITE_READONLY|SQLITE_CANTOPEN|EACCES|EPERM|read-only/i.test(message);
 }
 async function quarantineCorruptDatabase(dbPath) {
   const suffix = `.corrupt-${Date.now()}`;
@@ -2728,7 +2879,9 @@ var IndexStore = class _IndexStore {
       `SELECT f.* FROM files f
          LEFT JOIN enrichments e ON e.content_hash = f.hash
          WHERE f.collection_id = ? AND f.trivial = 0 AND f.hash IS NOT NULL
-           AND f.modality IN ('code','text','doc')
+           AND (f.modality IN ('code','text','doc')
+                OR EXISTS (SELECT 1 FROM shadow_state s
+                           WHERE s.content_hash = f.hash AND s.state = 'ok'))
            AND (e.content_hash IS NULL
                 OR (e.embedded_at IS NULL AND COALESCE(e.attempts, 0) < ${MAX_ENRICH_ATTEMPTS}))
          ORDER BY f.path LIMIT ?`
@@ -2742,12 +2895,45 @@ var IndexStore = class _IndexStore {
       `SELECT COUNT(*) AS n FROM files f
          LEFT JOIN enrichments e ON e.content_hash = f.hash
          WHERE f.collection_id = ? AND f.trivial = 0 AND f.hash IS NOT NULL
-           AND f.modality IN ('code','text','doc')
+           AND (f.modality IN ('code','text','doc')
+                OR EXISTS (SELECT 1 FROM shadow_state s
+                           WHERE s.content_hash = f.hash AND s.state = 'ok'))
            AND (e.content_hash IS NULL
                 OR (e.embedded_at IS NULL AND COALESCE(e.attempts, 0) < ${MAX_ENRICH_ATTEMPTS}))`
     ).get(this.collectionId);
     return row?.n ?? 0;
   }
+  /**
+   * Image/audio files whose AI shadow (description / transcript) is missing
+   * or stale for the current content hash. Same capped-retry discipline as
+   * {@link filesNeedingEnrichment}; an 'ok' row is the terminal success.
+   */
+  filesNeedingAiShadow(limit = 5, maxAttempts = MAX_ENRICH_ATTEMPTS) {
+    return this.db.prepare(
+      `SELECT f.* FROM files f
+         LEFT JOIN shadow_state s ON s.content_hash = f.hash
+         WHERE f.collection_id = ? AND f.trivial = 0 AND f.hash IS NOT NULL
+           AND f.modality IN ('image','audio')
+           AND (s.content_hash IS NULL
+                OR (s.state <> 'ok' AND COALESCE(s.attempts, 0) < ?))
+         ORDER BY f.path LIMIT ?`
+    ).all(this.collectionId, maxAttempts, limit).map(rowToFile);
+  }
+  markAiShadowOk(contentHash, filePath, model) {
+    this.db.prepare(
+      `INSERT OR REPLACE INTO shadow_state (content_hash, collection_id, file_path, state, attempts, model, updated_at)
+         VALUES (?, ?, ?, 'ok', 0, ?, ?)`
+    ).run(contentHash, this.collectionId, filePath, model ?? null, nowIso());
+  }
+  markAiShadowAttempt(contentHash, filePath) {
+    this.db.prepare(
+      `INSERT INTO shadow_state (content_hash, collection_id, file_path, state, attempts, updated_at)
+         VALUES (?, ?, ?, 'failed', 1, ?)
+         ON CONFLICT(content_hash) DO UPDATE SET
+           state='failed', attempts=COALESCE(shadow_state.attempts, 0) + 1,
+           updated_at=excluded.updated_at`
+    ).run(contentHash, this.collectionId, filePath, nowIso());
+  }
   /**
    * Enrichment coverage counts. `summarized` counts real summaries (join on
    * the summaries table), deliberately NOT the enrichments gate — the gate also
@@ -2766,15 +2952,39 @@ var IndexStore = class _IndexStore {
       `SELECT COUNT(*) AS n FROM files f JOIN enrichments e ON e.content_hash = f.hash
        WHERE e.embedded_at IS NOT NULL AND ${ELIGIBLE}`
     );
+    const skipped = count(
+      `SELECT COUNT(*) AS n FROM files f JOIN enrichments e ON e.content_hash = f.hash
+       WHERE e.embedded_at IS NULL AND COALESCE(e.attempts, 0) >= ${MAX_ENRICH_ATTEMPTS}
+         AND ${ELIGIBLE}`
+    );
     const embedModel = this.getMeta("embed_model");
     return {
       eligible,
       summarized,
       embedded,
       pending: this.countNeedingEnrichment(),
+      skipped,
+      shadowsPending: this.countNeedingAiShadow(),
       ...embedModel ? { embedModel } : {}
     };
   }
+  /**
+   * COUNT twin of `filesNeedingAiShadow` — media files still awaiting an AI
+   * description, attempt-capped ones excluded. The drive works this tier
+   * before summaries, so status must surface it or a fresh scan looks stuck.
+   */
+  countNeedingAiShadow(maxAttempts = MAX_ENRICH_ATTEMPTS) {
+    return Number(
+      this.db.prepare(
+        `SELECT COUNT(*) AS n FROM files f
+           LEFT JOIN shadow_state s ON s.content_hash = f.hash
+           WHERE f.collection_id = ? AND f.trivial = 0 AND f.hash IS NOT NULL
+             AND f.modality IN ('image','audio')
+             AND (s.content_hash IS NULL
+                  OR (s.state <> 'ok' AND COALESCE(s.attempts, 0) < ?))`
+      ).get(this.collectionId, maxAttempts)?.n ?? 0
+    );
+  }
   /** Mark a content hash as enriched (vectors built) so it isn't reprocessed. */
   markEnriched(contentHash) {
     this.db.prepare("INSERT OR REPLACE INTO enrichments (content_hash, embedded_at) VALUES (?, ?)").run(contentHash, nowIso());
@@ -2790,6 +3000,23 @@ var IndexStore = class _IndexStore {
       `INSERT INTO enrichments (content_hash, embedded_at, attempts) VALUES (?, NULL, 1)
          ON CONFLICT(content_hash) DO UPDATE SET attempts = COALESCE(enrichments.attempts, 0) + 1`
     ).run(contentHash);
+    return Number(
+      this.db.prepare("SELECT attempts FROM enrichments WHERE content_hash = ?").get(contentHash)?.attempts ?? 1
+    );
+  }
+  /**
+   * Jump a hash straight to the attempt cap — for deterministic failures
+   * (a provider policy-blocking the file's content) where every retry would
+   * fail identically. The file drops off the work list and counts as
+   * `skipped` in {@link enrichmentCounts} until its content changes.
+   */
+  markEnrichSkipped(contentHash) {
+    this.db.prepare(
+      `INSERT INTO enrichments (content_hash, embedded_at, attempts)
+         VALUES (?, NULL, ${MAX_ENRICH_ATTEMPTS})
+         ON CONFLICT(content_hash) DO UPDATE
+           SET attempts = MAX(COALESCE(enrichments.attempts, 0), ${MAX_ENRICH_ATTEMPTS})`
+    ).run(contentHash);
   }
   /**
    * Keyword search over enrichment summaries. fts_summaries rows are
@@ -2942,11 +3169,15 @@ var IndexStore = class _IndexStore {
   upsertSummary(rec) {
     this.db.transaction(() => {
       this.db.prepare(
-        `INSERT INTO summaries (content_hash, collection_id, file_path, summary_md, tags, model, created_at)
-           VALUES (?, ?, ?, ?, ?, ?, ?)
+        `INSERT INTO summaries (content_hash, collection_id, file_path, summary_md, tags, model,
+                                  provider, gezel_id, gezel_name, app_version, created_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
            ON CONFLICT(content_hash) DO UPDATE SET
              file_path=excluded.file_path, summary_md=excluded.summary_md,
-             tags=excluded.tags, model=excluded.model, created_at=excluded.created_at`
+             tags=excluded.tags, model=excluded.model,
+             provider=excluded.provider, gezel_id=excluded.gezel_id,
+             gezel_name=excluded.gezel_name, app_version=excluded.app_version,
+             created_at=excluded.created_at`
       ).run(
         rec.contentHash,
         this.collectionId,
@@ -2954,6 +3185,10 @@ var IndexStore = class _IndexStore {
         rec.summaryMd,
         rec.tags ?? null,
         rec.model,
+        rec.provenance?.provider ?? null,
+        rec.provenance?.gezelId ?? null,
+        rec.provenance?.gezelName ?? null,
+        rec.provenance?.appVersion ?? null,
         nowIso()
       );
       if (this.caps.fts) {
@@ -2982,16 +3217,29 @@ var IndexStore = class _IndexStore {
    * for any other (stale) hash of the same file. Keyed by symbol name only —
    * overloads/same-name symbols share a line (accepted v1 simplification).
    */
-  putSymbolSummaries(filePath, fileHash, entries, model) {
+  putSymbolSummaries(filePath, fileHash, entries, model, provenance) {
     this.db.transaction(() => {
       this.db.prepare("DELETE FROM symbol_summaries WHERE collection_id = ? AND file_path = ?").run(this.collectionId, filePath);
       const ins = this.db.prepare(
-        `INSERT OR REPLACE INTO symbol_summaries (collection_id, file_path, file_hash, symbol_name, summary, model, created_at)
-         VALUES (?, ?, ?, ?, ?, ?, ?)`
+        `INSERT OR REPLACE INTO symbol_summaries (collection_id, file_path, file_hash, symbol_name, summary, model,
+                                                  provider, gezel_id, gezel_name, app_version, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
       );
       const at = nowIso();
       for (const e of entries) {
-        ins.run(this.collectionId, filePath, fileHash, e.name, e.summary, model ?? null, at);
+        ins.run(
+          this.collectionId,
+          filePath,
+          fileHash,
+          e.name,
+          e.summary,
+          model ?? null,
+          provenance?.provider ?? null,
+          provenance?.gezelId ?? null,
+          provenance?.gezelName ?? null,
+          provenance?.appVersion ?? null,
+          at
+        );
       }
     });
   }
@@ -3009,14 +3257,17 @@ var IndexStore = class _IndexStore {
   upsertFileReview(rec) {
     this.db.prepare(
       `INSERT INTO file_reviews (content_hash, collection_id, file_path, rubric_hash, notes_md,
-                                   issues, health, health_reason, model, reviewed_at,
+                                   issues, health, health_reason, model,
+                                   provider, gezel_id, gezel_name, app_version, reviewed_at,
                                    attempt_rubric_hash, attempts, last_attempt_at)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, 0, NULL)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, 0, NULL)
          ON CONFLICT(content_hash) DO UPDATE SET
            collection_id=excluded.collection_id, file_path=excluded.file_path,
            rubric_hash=excluded.rubric_hash, notes_md=excluded.notes_md,
            issues=excluded.issues, health=excluded.health,
            health_reason=excluded.health_reason, model=excluded.model,
+           provider=excluded.provider, gezel_id=excluded.gezel_id,
+           gezel_name=excluded.gezel_name, app_version=excluded.app_version,
            reviewed_at=excluded.reviewed_at,
            attempt_rubric_hash=NULL, attempts=0, last_attempt_at=NULL`
     ).run(
@@ -3029,9 +3280,32 @@ var IndexStore = class _IndexStore {
       rec.health,
       rec.healthReason,
       rec.model,
+      rec.provenance?.provider ?? null,
+      rec.provenance?.gezelId ?? null,
+      rec.provenance?.gezelName ?? null,
+      rec.provenance?.appVersion ?? null,
       nowIso()
     );
   }
+  /**
+   * Terminal skip for content that CANNOT be reviewed under its current hash
+   * — a doc whose conversion was blocked/failed, an empty file, a source
+   * deleted between scan and review. Burns the whole attempt budget in one
+   * write (success fields untouched) so `filesNeedingReview` stops selecting
+   * the file; without this, one blocked doc permanently steals a batch slot
+   * from its kind on every sweep. A content change (new hash) or a rubric
+   * edit re-admits it exactly like any capped-out attempt.
+   */
+  markReviewUnavailable(contentHash, filePath, rubricHash, maxAttempts) {
+    this.db.prepare(
+      `INSERT INTO file_reviews (content_hash, collection_id, file_path, attempt_rubric_hash, attempts, last_attempt_at)
+         VALUES (?, ?, ?, ?, ?, ?)
+         ON CONFLICT(content_hash) DO UPDATE SET
+           attempts = excluded.attempts,
+           attempt_rubric_hash = excluded.attempt_rubric_hash,
+           last_attempt_at = excluded.last_attempt_at`
+    ).run(contentHash, this.collectionId, filePath, rubricHash, maxAttempts, nowIso());
+  }
   /**
    * Record a non-empty-but-unparseable review reply WITHOUT touching any
    * success field — a stale-rubric review keeps serving until a new one
@@ -3052,7 +3326,8 @@ var IndexStore = class _IndexStore {
   /** The successful review for a content hash (attempt-only rows excluded). */
   getFileReview(contentHash) {
     const row = this.db.prepare(
-      `SELECT notes_md, issues, health, health_reason, rubric_hash, model, reviewed_at
+      `SELECT notes_md, issues, health, health_reason, rubric_hash, model,
+                provider, gezel_id, gezel_name, app_version, reviewed_at
          FROM file_reviews
          WHERE content_hash = ? AND notes_md IS NOT NULL AND health IS NOT NULL`
     ).get(contentHash);
@@ -3064,6 +3339,10 @@ var IndexStore = class _IndexStore {
       healthReason: row.health_reason ?? "",
       rubricHash: row.rubric_hash ?? "",
       model: row.model,
+      provider: row.provider,
+      gezelId: row.gezel_id,
+      gezelName: row.gezel_name,
+      appVersion: row.app_version,
       reviewedAt: row.reviewed_at
     };
   }
@@ -3236,6 +3515,17 @@ var IndexStore = class _IndexStore {
       return out;
     };
     const bySeverity = tally(`COALESCE(json_extract(j.value, '$.severity'), 'info')`);
+    const reviewers = this.db.prepare(
+      `SELECT r.model, r.provider, r.gezel_name, COUNT(DISTINCT r.content_hash) AS files
+         ${FROM}
+         GROUP BY r.model, r.provider, r.gezel_name
+         ORDER BY files DESC LIMIT 5`
+    ).all(...params).map((r) => ({
+      model: r.model,
+      provider: r.provider,
+      gezelName: r.gezel_name,
+      files: Number(r.files)
+    }));
     return {
       issues: rows.filter((r) => r.message).map((r) => ({
         path: r.path,
@@ -3248,18 +3538,34 @@ var IndexStore = class _IndexStore {
         total: Object.values(bySeverity).reduce((a, b) => a + b, 0),
         bySeverity,
         byCategory: tally(`COALESCE(json_extract(j.value, '$.category'), 'general')`)
-      }
+      },
+      reviewers
     };
   }
   // ── area summaries (deep pass) ─────────────────────────────────────────
   upsertAreaSummary(rec) {
     this.db.prepare(
-      `INSERT INTO area_summaries (collection_id, area_path, input_hash, summary_md, model, created_at)
-         VALUES (?, ?, ?, ?, ?, ?)
+      `INSERT INTO area_summaries (collection_id, area_path, input_hash, summary_md, model,
+                                     provider, gezel_id, gezel_name, app_version, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
          ON CONFLICT(collection_id, area_path) DO UPDATE SET
            input_hash=excluded.input_hash, summary_md=excluded.summary_md,
-           model=excluded.model, created_at=excluded.created_at`
-    ).run(this.collectionId, rec.areaPath, rec.inputHash, rec.summaryMd, rec.model, nowIso());
+           model=excluded.model,
+           provider=excluded.provider, gezel_id=excluded.gezel_id,
+           gezel_name=excluded.gezel_name, app_version=excluded.app_version,
+           created_at=excluded.created_at`
+    ).run(
+      this.collectionId,
+      rec.areaPath,
+      rec.inputHash,
+      rec.summaryMd,
+      rec.model,
+      rec.provenance?.provider ?? null,
+      rec.provenance?.gezelId ?? null,
+      rec.provenance?.gezelName ?? null,
+      rec.provenance?.appVersion ?? null,
+      nowIso()
+    );
   }
   getAreaSummary(areaPath) {
     const row = this.db.prepare(
@@ -4025,7 +4331,7 @@ function parseBindings(raw) {
 
 // src/index-store/symbols.ts
 import { createRequire as createRequire3 } from "module";
-import { dirname as dirname6, join as join8 } from "path";
+import { dirname as dirname7, join as join9 } from "path";
 var nodeRequire2 = createRequire3(import.meta.url);
 var SIG_CAP = 160;
 var GRAMMAR_FILE = {
@@ -4098,8 +4404,8 @@ async function ensureInit() {
   initPromise = (async () => {
     try {
       const mod = nodeRequire2("web-tree-sitter");
-      const wtsDir = dirname6(nodeRequire2.resolve("web-tree-sitter"));
-      await mod.Parser.init({ locateFile: (f) => join8(wtsDir, f) });
+      const wtsDir = dirname7(nodeRequire2.resolve("web-tree-sitter"));
+      await mod.Parser.init({ locateFile: (f) => join9(wtsDir, f) });
       ParserCtor = mod.Parser;
       LanguageMod = mod.Language;
       return true;
@@ -4110,7 +4416,7 @@ async function ensureInit() {
   return initPromise;
 }
 function grammarDir() {
-  return join8(dirname6(nodeRequire2.resolve("tree-sitter-wasms/package.json")), "out");
+  return join9(dirname7(nodeRequire2.resolve("tree-sitter-wasms/package.json")), "out");
 }
 async function loadLanguage(langId) {
   const file = GRAMMAR_FILE[langId];
@@ -4118,7 +4424,7 @@ async function loadLanguage(langId) {
   if (langCache.has(langId)) return langCache.get(langId) ?? null;
   let lang = null;
   try {
-    lang = await LanguageMod.load(join8(grammarDir(), file));
+    lang = await LanguageMod.load(join9(grammarDir(), file));
   } catch {
     lang = null;
   }
@@ -4387,7 +4693,7 @@ function firstLine(text) {
 
 // src/index-store/content-indexer.ts
 var MAX_FILES = 5e4;
-var EXTRACTOR_VERSION = 2;
+var EXTRACTOR_VERSION = 3;
 var INDEXED_PNG_TEXT_KEYS = ["parameters", "prompt", "Description", "Comment", "Title"];
 var MAX_INDEXED_PNG_TEXT = 2e3;
 function embeddablePngText(text) {
@@ -4402,7 +4708,7 @@ function embeddablePngText(text) {
   }
   return parts.length > 0 ? ` ${parts.join(" ")}` : "";
 }
-async function indexWorkspaceContent(store, workspaceDir) {
+async function indexWorkspaceContent(store, workspaceDir, artifactsDir) {
   const stats = {
     scanned: 0,
     changed: 0,
@@ -4490,6 +4796,39 @@ async function indexWorkspaceContent(store, workspaceDir) {
       ]);
       continue;
     }
+    if (cls.modality === "audio") {
+      let bytes;
+      try {
+        bytes = await readFile3(file.abs);
+      } catch {
+        stats.skipped++;
+        continue;
+      }
+      const hash2 = sha256(bytes);
+      const record = {
+        path: file.path,
+        hash: hash2,
+        size: file.size,
+        mtimeMs: file.mtimeMs,
+        lang: cls.lang,
+        kind: cls.kind,
+        modality: cls.modality,
+        trivial: cls.trivial,
+        indexedAt,
+        loc: null
+      };
+      if (existing && existing.hash === hash2) {
+        store.upsertFile(record);
+        continue;
+      }
+      stats.changed++;
+      store.upsertFile(record);
+      const nameWords = file.path.replace(/\.[^.]+$/, "").split(/[^a-zA-Z0-9]+/).filter(Boolean).join(" ");
+      store.putChunks(file.path, hash2, [
+        { kind: "audio", lineStart: 1, lineEnd: 1, text: `${nameWords} audio recording` }
+      ]);
+      continue;
+    }
     if (cls.modality === "doc") {
       let bytes;
       try {
@@ -4511,21 +4850,32 @@ async function indexWorkspaceContent(store, workspaceDir) {
         indexedAt,
         loc: null
       };
+      const convertible = isConvertibleDoc(extname3(file.path));
       if (existing && existing.hash === hash2) {
         store.upsertFile(record);
+        if (!convertible) continue;
+        const paths = shadowDocFilesPaths(artifactsDir, file.path);
+        const sidecarPresent = paths ? await stat3(paths.mdPath).then(
+          (s) => s.isFile(),
+          () => false
+        ) : true;
+        if (sidecarPresent) continue;
+        const state = store.getMetadata(file.path)["doc:convert"];
+        if (state && state !== "ok") continue;
+        const conv = await ensureShadowDocSidecar(file.abs, artifactsDir, file.path);
+        store.setMetadata(file.path, [{ key: "doc:convert", value: convState(conv) }]);
+        if (conv?.markdown != null) stats.docsConverted++;
         continue;
       }
       stats.changed++;
       store.upsertFile(record);
-      if (isConvertibleDoc(extname3(file.path))) {
-        const conv = await ensureConvertedMarkdownSidecar(
-          file.abs,
-          docFilesPaths(workspaceDir, file.path)
-        );
-        if (conv.markdown != null) {
+      if (convertible) {
+        const conv = await ensureShadowDocSidecar(file.abs, artifactsDir, file.path);
+        store.setMetadata(file.path, [{ key: "doc:convert", value: convState(conv) }]);
+        if (conv?.markdown != null) {
           store.putChunks(file.path, hash2, chunkMarkdown(conv.markdown));
           stats.docsConverted++;
-        } else if (conv.blocked) {
+        } else if (conv?.blocked) {
           store.putChunks(file.path, hash2, [
             {
               kind: "doc",
@@ -4604,11 +4954,51 @@ async function indexWorkspaceContent(store, workspaceDir) {
     if (!seen.has(f.path)) {
       store.deleteFile(f.path);
       stats.removed++;
+      if (isConvertibleDoc(extname3(f.path))) {
+        const paths = shadowDocFilesPaths(artifactsDir, f.path);
+        if (paths) await rm4(paths.dir, { recursive: true, force: true }).catch(() => {
+        });
+      }
     }
   }
+  await sweepShadowOrphans(artifactsDir, seen);
   if (forceCode) store.setMeta("extractor_version", String(EXTRACTOR_VERSION));
   return stats;
 }
+var SHADOW_SWEEP_MAX_DIRS = 5e4;
+async function sweepShadowOrphans(artifactsDir, seen) {
+  const shadowRoot = join10(artifactsDir, PROJECT_SHADOW_DIR_NAME2);
+  const queue = [""];
+  let visited = 0;
+  while (queue.length > 0) {
+    const rel = queue.shift();
+    let entries;
+    try {
+      entries = await readdir2(join10(shadowRoot, rel), { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      if (++visited > SHADOW_SWEEP_MAX_DIRS) return;
+      const childRel = rel ? `${rel}/${e.name}` : e.name;
+      if (e.name.endsWith("_files")) {
+        const sourceRel = childRel.slice(0, -"_files".length);
+        if (!seen.has(sourceRel)) {
+          await rm4(join10(shadowRoot, childRel), { recursive: true, force: true }).catch(() => {
+          });
+        }
+      } else {
+        queue.push(childRel);
+      }
+    }
+  }
+}
+function convState(conv) {
+  if (conv?.markdown != null) return "ok";
+  if (conv?.blocked) return "blocked";
+  return "failed";
+}
 
 // src/index-store/static-index-worker.ts
 if (!parentPort) throw new Error("static-index-worker must be run as a worker thread");
@@ -4624,7 +5014,11 @@ port.on("message", (request) => {
       });
       if (!index) throw new Error(`content index unavailable at ${request.dbPath}`);
       try {
-        const stats = await indexWorkspaceContent(index, request.workspaceDir);
+        const stats = await indexWorkspaceContent(
+          index,
+          request.workspaceDir,
+          request.artifactsDir
+        );
         port.postMessage({ id: request.id, stats });
       } finally {
         index.close();