karajan-code 4.37.0 → 4.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.37.0",
+  "version": "4.38.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/scripts/esbuild-sea.config.mjs

@@ -26,6 +26,15 @@ const seaTransformPlugin = {
       let contents = await fs.readFile(args.path, "utf8");
       let modified = false;
 
+      // KJC-TSK-0915 (ADR 0014): the Sentinel's guard modules are read as TEXT at
+      // load time, to be copied into a project's harness. A single-file bundle has
+      // no sibling files, so the text is inlined here, before import.meta.url goes.
+      const SENTINEL_READ = /readFileSync\(new URL\("(\.\/sentinel\/[\w-]+\.mjs)", import\.meta\.url\), "utf8"\)/g;
+      if (SENTINEL_READ.test(contents)) {
+        contents = contents.replace(SENTINEL_READ, (_m, rel) => JSON.stringify(readFileSync(path.resolve(path.dirname(args.path), rel), "utf8")));
+        modified = true;
+      }
+
       // Replace import.meta.dirname with __dirname
       if (contents.includes("import.meta.dirname")) {
         contents = contents.replaceAll("import.meta.dirname", "__dirname");

package/src/cli/register-meta.js

@@ -30,7 +30,7 @@ import { envInstallCommand, briefCommand } from "../commands/env.js";
 import { runReleaseCheck } from "../checks/release-check.js";
 import { agentRunCommand } from "../commands/agent-run.js";
 import { reportIssueCommand } from "../commands/report-issue.js";
-import { huCommand } from "../commands/hu.js";
+import { huCommand, HU_STATUSES } from "../commands/hu.js";
 import { worktreeCommand } from "../commands/worktree.js";
 import { addAdr, listAdrs } from "../environment/adr.js";
 import { formatAdvancedIndex } from "../commands/advanced.js";
@@ -271,6 +271,8 @@ export function registerMeta(program, { pkgVersion }) {
       });
     });
   hu.command("move <id> <status>")
+    // KJC-BUG-0257: the valid states, said before the call fails.
+    .description(`Move a card; <status> is one of: ${HU_STATUSES.join(", ")}`)
     .option("--json", "Machine-readable output")
     .action(async (id, status, flags) => {
       await withConfig(pkgVersion, "hu", flags, async ({ config }) => {

package/src/commands/rag.js

@@ -14,7 +14,7 @@ import { installPostMergeHook, maybeAutoUpdate } from "../rag/auto-update.js";
 import { indexLibrary, LIBRARY_PROJECT } from "../rag/library.js";
 import { loadGoldenQueries, runEval } from "../rag/eval.js";
 import { getKarajanHome } from "../utils/paths.js";
-import { countProjectChunks, emptyIndexRemedy, migrateProjectIndex } from "../rag/migrate.js";
+import { countProjectChunks, countProjectSources, emptyIndexRemedy, migrateProjectIndex } from "../rag/migrate.js";
 import { openLibraryStore, openProjectStore, projectDbPath } from "../rag/project-store.js";
 
 // KJC-TSK-0882 (ADR 0011): el indice es del proyecto, no de la maquina.
@@ -153,6 +153,11 @@ export async function ragQueryCommand({ text, config, logger, flags = {} }) {
       if (flags.json) process.stdout.write(`${JSON.stringify({ hits: [], empty: true, topK, scope, remedy })}\n`);
       return [];
     }
+    // KJC-BUG-0258: chunks of plans and briefs but none of the project's own files
+    // answer nothing about the code; said now, not when kj review --staged blocks.
+    if (!library && project && countProjectSources(db, project, config?.projectDir || process.cwd()) === 0) {
+      logger.warn("[rag] this project's index holds none of its own files (only plans or briefs): run kj rag index --with-sources");
+    }
     const mode = flags.mode || "hybrid";
     const alpha = Math.max(0, Math.min(1, Number(flags.alpha) || 0.6));
     // Safe by grammar: parseWhere (core where-parser.js) accepts ONLY
@@ -234,6 +239,19 @@ export async function ragCoversCommand({ file, config, flags = {} }) {
   }
 }
 
+/**
+ * KJC-BUG-0255: what `kj rag migrate` keeps. The project's own files pass the
+ * indexer's criterion of today; sources outside the tree (plans, onboarding)
+ * are kept as they are.
+ */
+export function migrateKeep(projectDir, config) {
+  const exclude = ragExclude(config);
+  return (source) => {
+    const rel = relative(projectDir, source);
+    return rel.startsWith("..") || isAbsolute(rel) || indexableReason(rel, source, { exclude, projectDir }) === null;
+  };
+}
+
 /**
  * KJC-TSK-0888 (RAG-P1a, ADR 0011) — `kj rag migrate`: copia los chunks de este
  * proyecto desde la base global a su propio indice, con sus embeddings, sin
@@ -241,11 +259,13 @@ export async function ragCoversCommand({ file, config, flags = {} }) {
  */
 export async function ragMigrateCommand({ config, flags = {} }) {
   const projectDir = config?.projectDir || process.cwd();
+  const keep = migrateKeep(projectDir, config);
   const res = migrateProjectIndex({
     slug: projectSlug(projectDir),
     legacyPath: join(getKarajanHome(), "rag.db"),
     targetPath: projectDbPath(projectDir),
     dim: config?.rag?.embedder?.dim || 768,
+    keep,
   });
   if (flags.json) process.stdout.write(`${JSON.stringify(res)}\n`);
   else process.stdout.write(`rag migrate: ${res.state} — ${res.reason}\n`);

package/src/harden/sentinel/sentinel-bash-write.mjs

@@ -0,0 +1,106 @@
+// The Sentinel's bash-write guard (KJC-BUG-0237, moved here by KJC-TSK-0919,
+// ADR 0014). Inside the repo, files are written through Edit/Write only, the path
+// every gate guards. Copied byte for byte into .karajan/harness; `root` injected.
+// The stated limit: a program you run can write files; only a sandbox stops that.
+import { existsSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
+import { headIndex, shellSegments } from "./sentinel-shell.mjs";
+
+const WRITES = ["tee", "touch", "truncate", "cp", "mv", "install", "ln", "sed", "perl", "dd", "sh", "bash", "zsh", "dash", "eval"];
+const RUNNERS = ["xargs", "find", "node", "python3", "python", "ruby", "php", "deno", "bun"];
+// touch/truncate -s SIZE, -r REF, -d DATE, -t STAMP: the value is not a file it writes.
+const VALUED = ["-s", "--size", "-r", "--reference", "-d", "--date", "-t"];
+
+/** Redirection targets: >&N and >&- duplicate or close a descriptor; >& FILE and >&FILE write FILE. */
+const redirections = (words) => {
+  const out = [];
+  words.forEach((w, k) => {
+    const m = /^\d*(>>|>[|]|>)(.*)$/.exec(w);
+    if (!m) return;
+    const dup = m[2].startsWith("&") ? m[2].slice(1) : null;
+    if (dup === null) out.push(m[2] || words[k + 1]);
+    else if (dup === "") out.push(words[k + 1]);
+    else if (!/^\d*-?$/.test(dup)) out.push(dup);
+  });
+  return out;
+};
+
+/** Destination of cp/mv/install/ln: -t DIR / --target-directory[=]DIR, else the last plain word. */
+const destination = (rest, plain) => {
+  const t = rest.findIndex((w) => w === "-t" || w === "--target-directory");
+  const tEq = rest.find((w) => w.startsWith("--target-directory="));
+  if (t >= 0) return [rest[t + 1]];
+  if (tEq) return [tEq.slice(19)];
+  return plain.length >= 2 ? [plain.at(-1)] : [];
+};
+
+/** Files sed/perl -i edit: the script is the word after -e/-f, else the first plain word; a lone plain word is the file. */
+const inPlace = (rest, plain) => {
+  if (!rest.some((w) => w.startsWith("--in-place") || /^-[a-zA-Z0-9]*i/.test(w))) return [];
+  const script = rest.findIndex((w) => ["-e", "-f", "--expression"].includes(w));
+  if (script >= 0) return plain.filter((w) => w !== rest[script + 1]);
+  return plain.length === 1 ? plain : plain.slice(1);
+};
+
+/**
+ * The files a simple command (a word list) writes from the shell. "$(...)"
+ * marks a target that only exists at run time: unknowable, so writesRepo denies it.
+ * @param {string[]} words
+ * @returns {string[]}
+ */
+export const shellWrites = (words) => {
+  const out = redirections(words);
+  const i = headIndex(words, [...WRITES, ...RUNNERS]);
+  const head = (words[i] || "").split("/").at(-1);
+  // xargs / find -exec run a writer on targets that arrive at run time.
+  if (["xargs", "find"].includes(head) && words.slice(i + 1).some((w) => WRITES.includes(w.split("/").at(-1)))) out.push(`$(${head})`);
+  // Arguments without redirections (< << <<< > >> and a detached operand).
+  const rest = [];
+  for (let k = i + 1; k < words.length; k++) {
+    if (!/^\d*[<>]/.test(words[k])) rest.push(words[k]);
+    else if (/^\d*(<{1,3}|>>?|>[|&])$/.test(words[k])) k++;
+  }
+  // Operands: words that are not options, and EVERY word after "--" (touch -- -file).
+  const cut = rest.includes("--") ? rest.indexOf("--") : rest.length;
+  const plain = [...rest.slice(0, cut).filter((w) => !w.startsWith("-")), ...rest.slice(cut + 1)];
+  if (head === "tee") out.push(...plain);
+  if (head === "dd") out.push(...rest.filter((w) => w.startsWith("of=")).map((w) => w.slice(3)));
+  // By position, not value (touch -d today today writes "today").
+  if (head === "touch" || head === "truncate") out.push(...rest.filter((w, k) => k > cut || (k < cut && !w.startsWith("-") && !VALUED.includes(rest[k - 1]))));
+  // sh -c / eval run a script of their own: its writes are this command's writes.
+  if (["sh", "bash", "zsh", "dash"].includes(head) && rest.includes("-c")) for (const seg of shellSegments(rest[rest.indexOf("-c") + 1] || "")) out.push(...shellWrites(seg));
+  if (head === "eval") for (const seg of shellSegments(rest.join(" "))) out.push(...shellWrites(seg));
+  // An inline script (node -e, python -c...) that names a write API.
+  const inline = rest[rest.findIndex((w) => ["-e", "-c", "--eval", "-p", "-r"].includes(w)) + 1] || "";
+  if (/^(node|deno|bun|python[\d.]*|ruby|perl|php)$/.test(head) && /write|append|open|copy|rename|truncate|unlink|mkdir|symlink/i.test(inline)) out.push(`$(${head})`);
+  if (["cp", "mv", "install", "ln"].includes(head)) out.push(...destination(rest, plain));
+  if (head === "sed" || head === "perl") out.push(...inPlace(rest, plain));
+  return out.filter(Boolean);
+};
+
+/**
+ * Inside the repo, or unknowable ($VAR, backtick, ~user): both deny. /dev/* and
+ * descriptor duplication (&1) are outside; ~/ is the home, where the repo may live.
+ * Real paths: a link outside (/tmp/link -> repo) points in.
+ * @param {string} t
+ * @param {string} root
+ */
+export const writesRepo = (t, root) => {
+  if (t.includes("$") || t.includes("`")) return true;
+  if (t.startsWith("&") || t.startsWith("/dev/")) return false;
+  if (t.startsWith("~") && t !== "~" && !t.startsWith("~/")) return true;
+  let a = resolve(root, t.startsWith("~") ? homedir() + t.slice(1) : t);
+  let tail = "";
+  while (!existsSync(a) && dirname(a) !== a) {
+    tail = join(a.slice(dirname(a).length + 1), tail);
+    a = dirname(a);
+  }
+  let rel;
+  try {
+    rel = relative(realpathSync(root), join(realpathSync(a), tail));
+  } catch {
+    return true;
+  }
+  return !rel.startsWith("..") && !rel.startsWith("/");
+};

package/src/harden/sentinel/sentinel-discard.mjs

@@ -0,0 +1,98 @@
+// The Sentinel's discard guard (KJC-BUG-0238/0241/0242, moved here by KJC-TSK-0916,
+// ADR 0014). An agent does not discard changes it did not make. Copied byte for
+// byte into .karajan/harness; `root` is the project root, injected.
+import { spawnSync } from "node:child_process";
+import { relative, resolve } from "node:path";
+import process from "node:process";
+import { headIndex, shortOpts } from "./sentinel-shell.mjs";
+
+export const DISCARD_VERBS = ["checkout", "restore", "reset", "stash", "switch", "clean"];
+
+/**
+ * What a git command would discard, per simple command (a word list).
+ * null = discards nothing (or is not git); {stash} = drops saved work;
+ * {unknown} = cannot be read with certainty; {clean} = untracked files;
+ * {paths} = working-tree changes (":/" = the whole tree, whatever the cwd).
+ * @param {string[]} words
+ * @param {string} root
+ */
+export const discardOf = (words, root) => {
+  let i = headIndex(words, ["git"]); // /usr/bin/git is git
+  // A $variable in command position beside a discard verb ($g checkout) cannot be read.
+  if (words[i]?.startsWith("$") && words.some((w) => DISCARD_VERBS.includes(w))) return { unknown: true };
+  if (words[i]?.split("/").at(-1) !== "git") return null;
+  let cwd = root;
+  for (i++; i < words.length && words[i].startsWith("-"); i++) {
+    if (words[i] === "-C") cwd = resolve(cwd, words[++i] || ".");
+    else if (words[i] === "-c") i++;
+    else if (!["--no-pager", "-P", "--paginate", "-p", "--no-optional-locks"].includes(words[i])) return words.some((w) => DISCARD_VERBS.includes(w)) ? { unknown: true } : null;
+  }
+  const sub = words[i];
+  const args = [];
+  for (let j = i + 1; j < words.length; j++) {
+    // Options that take a value: the value is not a flag (-e -n excludes "-n").
+    // Dropping clean's excludes only makes its probe list MORE files.
+    if (["-s", "--source", "-e", "--exclude"].includes(words[j]) || (sub === "clean" && /^-[a-zA-Z]*e$/.test(words[j]))) j++;
+    else args.push(words[j]);
+  }
+  const has = (...f) => f.some((x) => args.includes(x));
+  const dd = args.indexOf("--");
+  const pos = (dd < 0 ? args : args.slice(0, dd)).filter((a) => !a.startsWith("-"));
+  const after = dd < 0 ? [] : args.slice(dd + 1);
+  const ALL = { cwd, paths: [":/"] };
+  if (sub === "stash") return has("drop", "clear") ? { cwd, stash: true } : null;
+  if (sub === "reset") return has("--hard") ? ALL : null;
+  // Every clean but a dry run (-n in a short cluster BEFORE "--"): clean.requireForce=false deletes without -f.
+  const opts = dd < 0 ? args : args.slice(0, dd);
+  // Interactive clean decides at the prompt: nothing to probe, fail-closed.
+  if (sub === "clean" && opts.some((a) => a === "--interactive" || shortOpts(a).includes("i"))) return { unknown: true };
+  if (sub === "clean") return opts.some((a) => a === "--dry-run" || shortOpts(a).includes("n")) ? null : { cwd, clean: [opts, args.slice(opts.length)] };
+  if (sub === "switch") return has("--discard-changes", "-f", "--force") ? ALL : null;
+  if (sub === "restore") return has("--staged", "-S") && !has("--worktree", "-W") ? null : { cwd, paths: [...pos, ...after] };
+  if (sub !== "checkout") return null;
+  if (has("-f", "--force")) return ALL;
+  if (has("-b", "-B", "--orphan") || !(pos.length || after.length)) return null;
+  if (after.length) return { cwd, paths: after };
+  const isRef = spawnSync("git", ["-C", cwd, "rev-parse", "--verify", "--quiet", `${pos[0]}^{commit}`]).status === 0;
+  if (!isRef) return { cwd, paths: pos };
+  return pos.length > 1 ? { cwd, paths: pos.slice(1) } : null;
+};
+
+/**
+ * Files the discard would lose that the session did not own: dirty now and not
+ * clean at first touch. Anything unreadable, or another repo, is foreign.
+ * @param {object} d what discardOf returned
+ * @param {Record<string, string>} touch the session's first_touch ledger
+ * @param {string} root
+ * @returns {string[]}
+ */
+export const foreignLost = (d, touch, root) => {
+  if (d.stash) return ["git stash"];
+  if (d.unknown) return ["(comando no verificable: ejecutalo como git simple)"];
+  const top = spawnSync("git", ["-C", d.cwd, "rev-parse", "--show-toplevel"], { encoding: "utf8" });
+  const sameRepo = top.status === 0 && resolve(String(top.stdout).trim()) === resolve(root);
+  const own = (f) => sameRepo && Object.hasOwn(touch, f) && touch[f] === "clean";
+  if (d.clean) {
+    // Ask git what it would remove: -n wins over -f, so the same flags (-ff included) are kept,
+    // minus -q (it silences the listing) and every exclude (dropping one only lists MORE).
+    // -n FIRST: after "--" it is a pathspec. LC_ALL=C: lines are parsed.
+    const [opts, rest] = d.clean;
+    const loud = opts.map((a) => (a.startsWith("--") ? a : `-${shortOpts(a).replaceAll("q", "")}`)).filter((a) => a !== "-" && a !== "--quiet" && !a.startsWith("--exclude"));
+    const r = spawnSync("git", ["-C", d.cwd, "clean", "-n", ...loud, ...rest], { encoding: "utf8", env: { ...process.env, LC_ALL: "C" } });
+    if (r.status !== 0) return ["(git clean -n fallo)"];
+    return String(r.stdout).split("\n").filter((l) => l.startsWith("Would remove ")).map((l) => relative(root, resolve(d.cwd, l.slice(13)))).filter((f) => !own(f));
+  }
+  // Fail-closed: a path git does not know (misparsed, $VAR, substitution) cannot
+  // be proven safe; git would refuse to check it out anyway.
+  if (spawnSync("git", ["-C", d.cwd, "ls-files", "--error-unmatch", "--", ...d.paths]).status !== 0) return [`(ruta no resoluble: ${d.paths.join(" ")})`];
+  const r = spawnSync("git", ["-C", d.cwd, "status", "--porcelain", "-z", "--untracked-files=no", "--", ...d.paths], { encoding: "utf8" });
+  if (r.status !== 0) return ["(git status fallo)"];
+  const files = [];
+  const parts = String(r.stdout).split("\0");
+  for (let k = 0; k < parts.length; k++) {
+    if (parts[k].length < 4) continue;
+    files.push(parts[k].slice(3));
+    if ("RC".includes(parts[k][0])) k++;
+  }
+  return files.filter((f) => !own(f));
+};

package/src/harden/sentinel/sentinel-reminders.mjs

@@ -0,0 +1,57 @@
+// The method's reminders (KJC-TSK-0917, ADR 0014). An agent reads its rules at
+// the start and loses them when the context is compacted; a hook does not forget.
+// These are reminders, not gates: never a block. Each comes AFTER the action that
+// precedes the one its rule is about (git add before a commit, gh pr create before
+// a merge), from PostToolUse: a PreToolUse reminder would need permissionDecision
+// "allow", which skips the user's permission prompt. Copied byte for byte into
+// .karajan/harness.
+import { headIndex, shellSegments } from "./sentinel-shell.mjs";
+
+/** The git or gh subcommand of a simple command, or null: "git commit" -> ["git", "commit"]. */
+const verbOf = (words) => {
+  const i = headIndex(words, ["git", "gh"]);
+  const tool = (words[i] || "").split("/").at(-1);
+  if (tool !== "git" && tool !== "gh") return null;
+  let j = i + 1;
+  while (j < words.length && words[j].startsWith("-")) j += ["-C", "-c", "-R", "--repo"].includes(words[j]) ? 2 : 1;
+  return [tool, words[j] || "", words[j + 1] || ""];
+};
+
+const REMINDERS = [
+  {
+    id: "commit",
+    when: (verbs) => verbs.some(([t, a]) => t === "git" && a === "add"),
+    say: "kj, antes de commitear: cabecera de 100 caracteres como máximo con el sujeto en minúscula, líneas del cuerpo de 100 como máximo y sin atribución a IA. Valida el mensaje con npx commitlint --edit <fichero> y stagea por nombre (nunca git add -A).",
+  },
+  {
+    id: "gh-account",
+    when: (verbs) => verbs.some(([t]) => t === "gh") && !verbs.some(([t, a, b]) => t === "gh" && a === "auth" && b === "switch"),
+    say: "kj: gh sin cuenta explícita. La cuenta activa puede haberla cambiado otra sesión; antepón gh auth switch --user <cuenta-del-proyecto> && en el mismo comando.",
+  },
+  {
+    id: "merge",
+    when: (verbs) => verbs.some(([t, a, b]) => t === "gh" && a === "pr" && b === "create"),
+    say: "kj, PR abierta; antes de mergearla: si la card no está terminada, pártela ahora (lo hecho en su card, el resto en una nueva). Tras el merge, muévela con sus commits.",
+  },
+  {
+    id: "sync-main",
+    when: (verbs, segs) => segs.some((w) => w.includes("main")) && verbs.some(([t, a]) => t === "git" && ["checkout", "switch", "pull"].includes(a)),
+    say: "kj: tras sincronizar main, crea ya la rama de la siguiente tarea desde origin/main. En main nunca se commitea.",
+  },
+];
+
+/**
+ * The reminders due after a Bash command ran, minus those already shown within
+ * the last `every` actions.
+ * @param {string} cmd
+ * @param {{seen?: Record<string, number>, step?: number, every?: number}} [opts]
+ *   seen: action number at which each reminder was last shown; step: this action's number.
+ * @returns {{id: string, say: string}[]}
+ */
+export const remindersFor = (cmd, { seen = {}, step = 0, every = 25 } = {}) => {
+  const segs = shellSegments(cmd);
+  const verbs = segs.map(verbOf).filter(Boolean);
+  return REMINDERS.filter((r) => r.when(verbs, segs))
+    .filter((r) => !Object.hasOwn(seen, r.id) || step - seen[r.id] > every)
+    .map(({ id, say }) => ({ id, say }));
+};

package/src/harden/sentinel/sentinel-shell.mjs

@@ -0,0 +1,95 @@
+// The Sentinel's shell reader (KJC-TSK-0915, ADR 0014). A real module with no
+// dependencies: kj harden copies it byte for byte into .karajan/harness as
+// sentinel-shell.mjs, so the hooks stay autonomous and this code is unit-tested.
+// It reads command TEXT; whatever it cannot read with certainty, the guards that
+// use it treat as unknowable and deny.
+
+/**
+ * Simple commands as word lists, quote-aware: an operator or blank inside
+ * quotes belongs to the word ('user;work.txt' is one path).
+ * @param {string} cmd
+ * @returns {string[][]}
+ */
+export const shellSegments = (cmd) => {
+  const segs = [[]];
+  let word = null;
+  let quote = null;
+  let escaped = false;
+  const end = () => {
+    if (word !== null) segs.at(-1).push(word);
+    word = null;
+  };
+  for (const ch of String(cmd)) {
+    // A backslash keeps the next char literal (an escaped blank joins the word),
+    // except inside single quotes.
+    if (escaped) { word += ch; escaped = false; continue; }
+    if (ch === "\\" && quote !== "'") { escaped = true; word ??= ""; continue; }
+    if (quote) {
+      if (ch === quote) quote = null;
+      else word += ch;
+      continue;
+    }
+    if (ch === "'" || ch === '"') { quote = ch; word ??= ""; continue; }
+    // >| and >& are redirections, not a pipe or a fork.
+    if ((ch === "|" || ch === "&") && word?.endsWith(">")) { word += ch; continue; }
+    // x>file: end "x" and start the redirection word ">" (the target follows in it).
+    if (ch === ">" && word !== null && !/^\d*>?$/.test(word)) { end(); word = ">"; continue; }
+    // ( ) { } and backticks also cut: what runs inside $( ), a subshell or a group
+    // is a command of its own. A backtick leaves "$" in the word it interrupts, as
+    // $( does: that word is no longer readable.
+    if (ch === "`") word = (word ?? "") + "$";
+    if (";&|(){}\n`".includes(ch)) { end(); segs.push([]); continue; }
+    if (ch.trim() === "") { end(); continue; }
+    word = (word ?? "") + ch;
+  }
+  end();
+  return segs.filter((s) => s.length);
+};
+
+const WRAPPERS = new Set(["command", "exec", "sudo", "doas", "nice", "nohup", "time", "env"]);
+
+/**
+ * Index of the command word. Skips NAME=value assignments AND wrappers (env,
+ * sudo, command...) in any interleaving: env MODE=prod tee -> tee. After a
+ * wrapper with options (sudo -u root, env -i FOO=1) the command is the first of
+ * `heads`; none found means there is no command to read.
+ * @param {string[]} words
+ * @param {string[]} heads
+ */
+export const headIndex = (words, heads) => {
+  let i = 0;
+  while (i < words.length && (/^[A-Za-z_]\w*=/.test(words[i]) || WRAPPERS.has(words[i].split("/").at(-1)))) i++;
+  if (!words[i]?.startsWith("-")) return i;
+  const k = words.slice(i).findIndex((x) => heads.includes(x.split("/").at(-1)));
+  return k < 0 ? words.length : i + k;
+};
+
+/**
+ * KJC-BUG-0243: blank the quoted text that cannot run: single-quoted spans, and
+ * double-quoted spans with no $ or backtick. What remains is what the shell can
+ * still expand or execute, so operator and substitution checks read only that.
+ * @param {string} cmd
+ */
+export const stripInertQuotes = (cmd) => {
+  let out = "";
+  for (let i = 0; i < cmd.length; i++) {
+    const q = cmd[i];
+    if (q !== "'" && q !== '"') { out += q; continue; }
+    let j = i + 1;
+    while (j < cmd.length && cmd[j] !== q) j += q === '"' && cmd[j] === "\\" ? 2 : 1;
+    if (j >= cmd.length) return out + cmd.slice(i); // unclosed: left as is, for the caller to deny
+    const body = cmd.slice(i + 1, j);
+    out += q === "'" || !/[$`]/.test(body) ? q + q : q + body + q;
+    i = j;
+  }
+  return out;
+};
+
+// Options whose value is prose, never a path (gh, git, kj).
+const TEXT_OPTION = /(^|\s)(--title|--body|--message|-m|--notes|--description|--ac|--criteria|--reason|--decision|--context|--consequences)(=|\s+)("[^"$`\\]*"|'[^']*')/g;
+
+/** KJC-BUG-0243: blank the inert quoted value of a text option (--title "a/b c"): prose, not a path. */
+export const stripTextOptionValues = (cmd) => cmd.replace(TEXT_OPTION, (_m, pre, opt, sep, val) => `${pre}${opt}${sep}${val[0]}${val[0]}`);
+
+/** Short flags of a cluster stop at "e": the rest is -e's value (-fen = -f -e n). */
+export const shortOpts = (a) => (/^-[a-zA-Z]/.test(a) ? a.slice(1).split("e")[0] : "");

package/src/harden/sentinel/sessionstart.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// kj sentinel SessionStart hook (KJC-TSK-0918, ADR 0014), managed by `kj harden`.
+// A compaction takes exactly what the agent needs most: the rules it read at the
+// start. After a compaction or a resume, this gives them back, short, with the
+// state of the session. A new session gets nothing: CLAUDE.md already brings them.
+// Copied byte for byte into .karajan/harness; never fails a session (exit 0).
+import process from "node:process";
+import { CARD, branchOf, load, pendingMoves } from "./sentinel-lib.mjs";
+
+const RULES = [
+  "1. Karajan gobierna y se le obedece: no cambies políticas, configuración de gates ni exclusiones para pasar un gate. Si uno parece injusto, díselo a tu usuario o usa kj report-issue.",
+  "2. Card antes de código; rama desde origin/main; nunca se commitea en main.",
+  "3. kj rag query antes de tocar código que no has consultado en esta sesión.",
+  "4. El test que falla va primero; la suite nunca se deja en rojo.",
+  "5. kj review --staged antes de cada commit: el veredicto va atado al diff exacto.",
+  "6. PR atómica: unas 150 líneas, 200 como máximo; mídela con kj pr-size y parte antes, no en el gate.",
+  "7. Conventional Commits, cabecera de 100 caracteres como máximo y sin atribución a IA.",
+  "8. Card sin terminar con PR mergeada: pártela antes de mergear; tras el merge, muévela con sus commits.",
+  "9. Dentro del repo se escribe solo con Edit/Write; los escapes KJ_ALLOW_* son de tu usuario, no tuyos.",
+];
+
+let raw = "";
+process.stdin.on("data", (d) => { raw += d; });
+process.stdin.on("end", () => {
+  try {
+    const { session_id: sid = "default", source } = JSON.parse(raw || "{}");
+    if (source !== "compact" && source !== "resume") process.exit(0);
+    const branch = branchOf() || "?";
+    const card = CARD.exec(branch)?.[0]?.toUpperCase() ?? "ninguna en la rama";
+    const pending = pendingMoves(load().sessions?.[sid]).map((p) => `${p.card ?? "?"} (PR #${p.pr})`);
+    const state = `Estado: rama ${branch}, card ${card}${pending.length ? `; cards mergeadas sin mover: ${pending.join(", ")}` : ""}.`;
+    const context = ["Karajan (reglas que la compactación se lleva):", ...RULES, state].join("\n");
+    process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: context } }));
+  } catch { /* never fails a session */ }
+  process.exit(0);
+});

package/src/harden/sentinel-hooks.js

@@ -8,7 +8,7 @@
  * hooks, which is why the guaranteed level requires Claude as host (ADR).
  */
 
-import { readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { join } from "node:path";
@@ -136,6 +136,7 @@ import process from "node:process";
 import { relative } from "node:path";
 import { spawnSync } from "node:child_process";
 import { CODE, TESTS, ROOT, CARD, branchOf, load, save, session } from "./sentinel-lib.mjs";
+import { remindersFor } from "./sentinel-reminders.mjs";
 const ESCAPES = ["KJ_ALLOW_WRITE", "KJ_ALLOW_REWRITE", "KJ_ALLOW_NO_CARD", "KJ_ALLOW_NO_TESTS", "KJ_ALLOW_PII", "KJ_ALLOW_POLICY", "KJ_ALLOW_IDENTITY", "KJ_ALLOW_BOARD", "KJ_ALLOW_NO_RAG", "KJ_ALLOW_NO_VERIFY"];
 let raw = "";
 process.stdin.on("data", (d) => { raw += d; });
@@ -273,6 +274,15 @@ process.stdin.on("end", () => {
       // "not found" counts as failure (KJC-BUG-0154): a move that moved nothing must not
       // clear a pending — that would discard a LEGITIMATE one without touching the tracker.
       if (moved && CLOSING.includes(moved[2].toLowerCase()) && !/error|fail|not found/i.test(text)) clearPending(moved[1].toUpperCase());
+      // KJC-TSK-0917 (ADR 0014): the method's reminders, after the action that precedes
+      // the one each rule is about; at most once every 25 Bash actions each. Never a block.
+      const st = load();
+      const ss = session(st, sid);
+      ss.step = (ss.step || 0) + 1;
+      const due = remindersFor(cmdText, { seen: ss.reminded || {}, step: ss.step });
+      for (const r of due) (ss.reminded ||= {})[r.id] = ss.step;
+      save(st);
+      if (due.length) process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: due.map((r) => r.say).join(" ") } }));
       process.exit(0);
     }
     const file = input.file_path || input.notebook_path;
@@ -445,6 +455,10 @@ import { spawnSync } from "node:child_process";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { doc, CODE, TESTS, ROOT, BASE_BRANCHES, CARD, branchOf, foreignLane, load, save, session, violations, recordEscape, pendingMoves, pendingText } from "./sentinel-lib.mjs";
+// KJC-TSK-0915 (ADR 0014): the shell reader is a real, unit-tested module copied here as is.
+import { shellSegments, stripInertQuotes, stripTextOptionValues } from "./sentinel-shell.mjs";
+import { DISCARD_VERBS, discardOf, foreignLost } from "./sentinel-discard.mjs";
+import { shellWrites, writesRepo } from "./sentinel-bash-write.mjs";
 const EDIT_TOOLS = ["Write", "Edit", "MultiEdit", "NotebookEdit"];
 // KJC-BUG-0204: el comando real lleva flags EN MEDIO del verbo
 // (firebase --account a@b --project p deploy --only hosting:main), asi que la
@@ -463,6 +477,10 @@ process.stdin.on("data", (d) => { raw += d; });
 process.stdin.on("end", () => {
   try {
     const { session_id: sid = "default", tool_name: tool, tool_input: input = {}, transcript_path: transcript = null } = JSON.parse(raw);
+    // KJC-TSK-0920 (SNT-E): every deny ends with the same line, whatever gate it was.
+    process.on("exit", (code) => {
+      if (code === 2) console.error("karajan: Karajan gobierna y se le obedece. No rodees el gate ni cambies la politica para pasarlo; si te parece injusto, diselo a tu usuario o usa kj report-issue.");
+    });
     // Self-protection (KJC-TSK-0715) rules run BEFORE any escape, including
     // KJ_SENTINEL_OFF: the sentinel is not dismantled from inside a session —
     // only the human, editing outside it.
@@ -473,6 +491,28 @@ process.stdin.on("end", () => {
         console.error("karajan sentinel: ese fichero es parte del supervisor (" + relT + ") — solo el humano desmonta el sentinel, editalo fuera de la sesion." + doc("supervisor"));
         process.exit(2);
       }
+      // KJC-TSK-0920 (SNT-E): policies, gate settings and exclusions are the human's,
+      // like the supervisor: a session does not loosen the rules that govern it.
+      if ([".karajan/policy.yml", ".karajan/kj.config.yml", ".ragignore"].includes(relT) || relT.endsWith("/.ragignore")) {
+        console.error("karajan sentinel: " + relT + " es configuracion de gobierno (politicas, gates, exclusiones): la cambia tu usuario, no la sesion. Si un gate te parece injusto, proponselo a tu usuario o usa kj report-issue." + doc("governance"));
+        process.exit(2);
+      }
+      // KJC-BUG-0238 (#1886): de quien es cada cambio. La primera vez que la
+      // sesion toca un fichero se anota si estaba limpio: solo entonces un
+      // descarte posterior pierde nada mas que lo de la sesion. Antes de
+      // cualquier escape; git que falla cuenta como sucio (fail-closed).
+      if (relT && !relT.startsWith("..") && !relT.startsWith("/")) {
+        const st = load();
+        const touch = (session(st, sid).first_touch ||= {});
+        // hasOwn + defineProperty: a file named __proto__ or toString is a path, not a prototype key.
+        if (!Object.hasOwn(touch, relT)) {
+          // --ignored: a user's ignored .env is theirs too (git clean -x deletes it).
+          const gs = spawnSync("git", ["-C", ROOT, "status", "--porcelain", "--ignored", "--", relT], { encoding: "utf8" });
+          const value = gs.status === 0 && String(gs.stdout).trim() === "" ? "clean" : "dirty";
+          Object.defineProperty(touch, relT, { value, enumerable: true, writable: true, configurable: true });
+          save(st);
+        }
+      }
     }
     // Any Bash that NAMES the supervisor's files is denied — a write-verb
     // blocklist is bypassable (cp, dd, one-liners), and reading them is what
@@ -535,6 +575,28 @@ process.stdin.on("end", () => {
         process.exit(2);
       }
     }
+    // KJC-BUG-0238 (#1886): un agente no descarta cambios que no hizo. Sin
+    // escape y antes de KJ_SENTINEL_OFF: es perdida de datos del usuario, y
+    // guardarlo (git stash push) nunca pierde nada.
+    if (tool === "Bash") {
+      const cmdD = String(input.command || "");
+      // A git discard nested in $( ), <( ), backticks, eval, xargs or sh -c cannot be read: fail-closed.
+      const nested = ["$(", "<(", ">(", String.fromCharCode(96)].some((n) => cmdD.includes(n)) || /(^|[ ;&|])(eval|xargs|bash|sh|zsh|env)( |$)/.test(cmdD);
+      if (nested && /(^|[^a-z])git([^a-z]|$)/.test(cmdD) && DISCARD_VERBS.some((v) => cmdD.includes(v))) {
+        console.error("karajan sentinel: un descarte git dentro de $( ), backticks, eval, xargs o sh -c no es verificable — ejecutalo como comando simple." + doc("discard"));
+        process.exit(2);
+      }
+      const touch = load().sessions?.[sid]?.first_touch || {};
+      for (const words of shellSegments(cmdD)) {
+        const d = discardOf(words, ROOT);
+        const lost = d ? foreignLost(d, touch, ROOT) : [];
+        if (lost.length === 0) continue;
+        console.error(d.stash
+          ? "karajan sentinel: git stash drop/clear borra trabajo guardado que puede no ser de esta sesion — pideselo a tu usuario." + doc("discard")
+          : "karajan sentinel: ese comando descarta cambios que esta sesion no hizo (" + lost.slice(0, 5).join(", ") + (lost.length > 5 ? ", +" + (lost.length - 5) : "") + ") — pueden ser trabajo sin commitear de tu usuario. Si estorban, guardalos recuperables (git stash push -- <ficheros>) y avisale; si el cambio es tuyo sobre su trabajo, deshazlo con Edit. Sin escape: es perdida de datos." + doc("discard"));
+        process.exit(2);
+      }
+    }
     if (process.env.KJ_SENTINEL_OFF === "1") process.exit(0);
     // KJC-BUG-0142: cada deny anuncia su escape como prefijo del comando
     // (KJ_ALLOW_X=1 cmd), pero el hook corre con el env del HOST — el
@@ -747,7 +809,8 @@ process.stdin.on("end", () => {
       // (find fuera: -delete/-exec mutan — reviewer catch; sus tokens de
       // carril los caza el escaner de abajo.)
       const READONLY = /^[ \\t]*(grep|rg|cat|head|tail|less|ls|wc|diff|stat|file|du|tree|git (log|show|diff|status|blame))\\b[^;|&<>$\`(){}\\n\\r]*$/;
-      if (!READONLY.test(cmd)) {
+      // KJC-BUG-0243: operators inside inert quotes (grep -e "a|b") do not chain anything.
+      if (!READONLY.test(stripInertQuotes(cmd))) {
         // cd/pushd invalida TODO razonamiento textual de rutas posteriores
         // (carrera de bypasses confirmada en review: destino bare, con $,
         // relativas post-cd...): en un comando NO-read-only, cambiar de
@@ -838,7 +901,9 @@ process.stdin.on("end", () => {
           if (q !== null) return true; // comilla sin cerrar: no verificable
           return flush();
         };
-        if (/\\$\\(|\`/.test(cmd) || quotedPathWithSpaces(cmd)) {
+        // KJC-BUG-0243: inert quoted text is not a substitution, and the prose value
+        // of a text option (--title, -m...) is not a path.
+        if (/\\$\\(|\`/.test(stripInertQuotes(cmd)) || quotedPathWithSpaces(stripTextOptionValues(cmd))) {
           if (escOn("KJ_ALLOW_CROSS_LANE")) { recordEscape(sid, "KJ_ALLOW_CROSS_LANE", tool); }
           else {
             console.error("karajan sentinel: sustitucion de comandos o ruta entrecomillada con espacios en un comando mutador — no verificable por el guard de carriles (MONO-0); usa valores/rutas LITERALES sin sustitucion (o KJ_ALLOW_CROSS_LANE=1, queda registrado)." + doc("cross-lane"));
@@ -868,6 +933,21 @@ process.stdin.on("end", () => {
         }
       }
     }
+    // KJC-BUG-0237 (#1886): the repo is written through Edit/Write only, the path every gate
+    // guards. After the lane guard, whose message is the precise one for another lane.
+    if (tool === "Bash") {
+      let moved = false; // after cd/pushd/popd, a relative target cannot be placed: fail-closed
+      // $( ) and backticks run even inside double quotes: their bodies, read from the raw text, are commands too.
+      const raw = String(input.command || "");
+      const subs = [...[...raw.matchAll(/[$][(]([^()]*)[)]/g)].map((m) => m[1]), ...raw.split(String.fromCharCode(96)).filter((_, k) => k % 2 === 1)];
+      for (const words of [...shellSegments(raw), ...subs.flatMap((s) => shellSegments(s))]) {
+        if (["cd", "pushd", "popd"].includes(words[0])) moved = true;
+        const inRepo = shellWrites(words).filter((t) => writesRepo(t, ROOT) || (moved && !t.startsWith("/")));
+        if (inRepo.length === 0) continue;
+        console.error("karajan sentinel: escribir ficheros del repo desde Bash (" + inRepo.slice(0, 3).join(", ") + ") se salta los gates de Edit/Write — usa la tool Edit/Write; para renombrar, git mv; fuera del repo (/tmp, scratchpad) Bash es libre." + doc("bash-write"));
+        process.exit(2);
+      }
+    }
     // KJC-TSK-0734 (PL-B): con .karajan/policy.yml presente, la evaluacion
     // la hace el MOTOR via kj policy eval --strict (exit 2 = deny, contrato
     // PL-A); los defaults del supervisor viven en el motor y el check
@@ -1143,6 +1223,14 @@ const SCRIPT_BODIES = {
   "posttooluse.mjs": POST_BODY,
   "stop.mjs": STOP_BODY,
   "pretooluse-sentinel.mjs": PRETOOL_BODY,
+  // KJC-TSK-0915 (ADR 0014): real modules, copied byte for byte under the SAME name
+  // (so they can import each other in both places). Being here, the installed
+  // record, the tamper check and the human seal cover them as well.
+  "sentinel-shell.mjs": readFileSync(new URL("./sentinel/sentinel-shell.mjs", import.meta.url), "utf8"),
+  "sentinel-discard.mjs": readFileSync(new URL("./sentinel/sentinel-discard.mjs", import.meta.url), "utf8"),
+  "sentinel-bash-write.mjs": readFileSync(new URL("./sentinel/sentinel-bash-write.mjs", import.meta.url), "utf8"),
+  "sentinel-reminders.mjs": readFileSync(new URL("./sentinel/sentinel-reminders.mjs", import.meta.url), "utf8"),
+  "sessionstart.mjs": readFileSync(new URL("./sentinel/sessionstart.mjs", import.meta.url), "utf8"),
 };
 
 /**
@@ -1246,6 +1334,7 @@ export function verifySentinelScripts({ projectDir, readFileFn = readFileSync, g
   // first attempt at this fix, and the review was right to reject it.
   const sealed = sealedByPath(root, gitShowFn);
   const ownRecord = readInstalledRecord(dir);
+  const hasRecord = existsSync(join(dir, INSTALLED_RECORD));
   const drift = [];
   const tampered = [];
   const regenerated = [];
@@ -1254,6 +1343,10 @@ export function verifySentinelScripts({ projectDir, readFileFn = readFileSync, g
     const hash = text === undefined ? null : sha256(text);
     if (hash && sealed.get(`.karajan/harness/${name}`) === hash) drift.push(name);
     else if (hash && ownRecord[name] === hash) regenerated.push(name);
+    // KJC-TSK-0915: absent from an install kj RECORDED (installed.json exists), never
+    // recorded and never sealed = a guard newer than this install, not a deleted
+    // one. Writing it only adds. A dir with no record is not a kj install at all.
+    else if (!hash && hasRecord && !Object.hasOwn(ownRecord, name) && !sealed.has(`.karajan/harness/${name}`)) regenerated.push(name);
     else tampered.push(name);
   }
   // KJC-BUG-0224 caso 1: lo que kj escribio y nadie sello ni toco se pone al
@@ -1333,7 +1426,13 @@ export function installSentinelHooks({ projectDir = process.cwd(), logger = cons
       // edit matchers wired, the board-sync recorder never ran in production.
       { event: "PostToolUse", matcher: "Bash", script: "posttooluse.mjs" },
       { event: "PostToolUse", matcher: "mcp__.*__update_card", script: "posttooluse.mjs" },
+      // KJC-BUG-0236 (#1886): the rag-first ledger records MCP answers here;
+      // unwired, the official tool never satisfied the gate.
+      { event: "PostToolUse", matcher: "mcp__.*__kj_rag_query", script: "posttooluse.mjs" },
       { event: "Stop", script: "stop.mjs" },
+      // KJC-TSK-0918 (ADR 0014): the critical rules back after a compaction or a resume.
+      { event: "SessionStart", matcher: "compact", script: "sessionstart.mjs" },
+      { event: "SessionStart", matcher: "resume", script: "sessionstart.mjs" },
     ],
   });
   return { scripts: [lib, post, stop, pre], wired, deferred };

package/src/harden/supervisor-commit.js

@@ -117,6 +117,16 @@ export async function commitSupervisorRegeneration({
       `harden --commit es un acto humano y este proceso desciende de un agente (${anc.match}) — ni con pty falso ni con el entorno limpio (ADR 0009)`,
     );
   }
+  const run = gitFn || ((args) => execFileSync("git", args, { cwd: projectDir, encoding: "utf8" }));
+  // KJC-BUG-0244 (grebla #958): el commit sellado solo lleva el supervisor, pero
+  // un stage ajeno se quedaba en esta rama y el siguiente commit caía aquí con la
+  // card equivocada. Se para ANTES de pedir nada al humano y se nombra.
+  const foreign = run(["diff", "--cached", "--name-only"]).split("\n").filter((f) => f && !f.startsWith(HOOKS_PREFIX) && f !== PROVENANCE_FILE);
+  if (foreign.length > 0) {
+    throw new Error(
+      `harden --commit: hay cambios en el stage que no son del supervisor (${foreign.slice(0, 5).join(", ")}${foreign.length > 5 ? ", …" : ""}): commitéalos en su rama o sácalos del stage (git restore --staged <ficheros>) antes de sellar`,
+    );
+  }
   // Capa 4 (test adversarial 6-sep: un huérfano a init con pty falso y
   // prompts a ciegas llegó hasta aquí): nonce aleatorio tecleado de vuelta.
   // Un alimentador ciego no conoce el código; automatizar su lectura exige
@@ -126,7 +136,6 @@ export async function commitSupervisorRegeneration({
   if (answer !== nonce) {
     throw new Error(`harden --commit: confirmación humana fallida (esperaba "${nonce}") — ADR 0009`);
   }
-  const run = gitFn || ((args) => execFileSync("git", args, { cwd: projectDir, encoding: "utf8" }));
   const drift = supervisorDrift({ projectDir, gitFn: run });
   // La provenance describe SIEMPRE el estado COMPLETO del supervisor (cazado
   // en el primer estreno real: un sello parcial pisaba al anterior y dejaba

package/src/rag/migrate.js

@@ -7,11 +7,22 @@
  * toca: borrarla es decision del usuario, no efecto de una migracion.
  */
 import { existsSync } from "node:fs";
+import { sep } from "node:path";
 
 import { openVecStore, insertChunk, getLastIndexedCommit, setLastIndexedCommit } from "./vec-store.js";
 
 export const countProjectChunks = (db, slug) => db.prepare("SELECT COUNT(*) AS n FROM chunks WHERE project_slug = ?").get(slug).n;
 
+/**
+ * KJC-BUG-0258: chunks of the project's OWN files (sources under projectDir), as
+ * opposed to its plans and briefs. A prefix compare, not LIKE: paths may hold % or _.
+ */
+export const countProjectSources = (db, slug, projectDir) => {
+  // path.sep: sources are stored as native paths (backslashes on Windows).
+  const prefix = projectDir.replace(/[\\/]+$/, "") + sep;
+  return db.prepare("SELECT COUNT(*) AS n FROM chunks WHERE project_slug = ? AND substr(source, 1, ?) = ?").get(slug, prefix.length, prefix).n;
+};
+
 /**
  * KJC-TSK-0882: que decir cuando el indice del proyecto no tiene nada suyo.
  * Si la base global tiene sus chunks, migrar (segundos); si no, indexar.
@@ -29,9 +40,12 @@ export function emptyIndexRemedy({ slug, legacyPath, dim = 768 }) {
 }
 
 /**
- * @returns {{state: "migrated"|"already"|"nothing", migrated: number, reason: string}}
+ * KJC-BUG-0255: `keep(source)` is the indexer's criterion today (generated,
+ * excluded, .ragignore, sensitive, gone). The global index was filled before
+ * those rules, so copying it blind brought vendor/*.min.js along as noise.
+ * @returns {{state: "migrated"|"already"|"nothing", migrated: number, skipped?: number, reason: string}}
  */
-export function migrateProjectIndex({ slug, legacyPath, targetPath, dim = 768 }) {
+export function migrateProjectIndex({ slug, legacyPath, targetPath, dim = 768, keep = () => true }) {
   const nothing = { state: "nothing", migrated: 0, reason: `the global index holds nothing for ${slug}: kj rag index --with-sources` };
   if (!existsSync(legacyPath)) return nothing;
 
@@ -49,8 +63,10 @@ export function migrateProjectIndex({ slug, legacyPath, targetPath, dim = 768 })
       const rows = legacy.prepare("SELECT id, source, kind, text, metadata, content_hash FROM chunks WHERE project_slug = ?").all(slug);
       if (rows.length === 0) return nothing;
       const vecOf = legacy.prepare("SELECT embedding FROM vec_chunks WHERE rowid = ?");
+      let skipped = 0;
       const copy = target.transaction(() => {
         for (const r of rows) {
+          if (!keep(r.source)) { skipped++; continue; }
           const raw = vecOf.get(BigInt(r.id))?.embedding;
           if (!raw) continue; // un chunk sin vector no se puede buscar: no se inventa
           const embedding = new Float32Array(raw.buffer.slice(raw.byteOffset, raw.byteOffset + raw.byteLength));
@@ -63,7 +79,8 @@ export function migrateProjectIndex({ slug, legacyPath, targetPath, dim = 768 })
       const migrated = countProjectChunks(target, slug);
       const parts = [`${migrated} chunks of ${slug} copied with their embeddings`];
       if (stamp) parts.push(`indexed at ${stamp.slice(0, 9)}`);
-      return { state: "migrated", migrated, reason: parts.join(", ") };
+      if (skipped) parts.push(`${skipped} left out (the indexer would not take them today: generated, excluded or gone)`);
+      return { state: "migrated", migrated, skipped, reason: parts.join(", ") };
     } finally {
       legacy.close();
     }