karajan-code 4.65.1 → 4.66.0

package/bin/kj-hook.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * kj-hook <guard>: runs one Sentinel guard from the installed kj package
+ * (KJC-TSK-1203, ADR 0030). The project's hooks name the guard; its code lives
+ * here, outside the project tree, so editing the project cannot change it.
+ * Only the guard is loaded, never the CLI: a hook pays node, not kj's start.
+ * A name outside the closed list blocks (exit 2): a wiring that names no known
+ * guard cannot be trusted to guard anything.
+ */
+import process from "node:process";
+import { runGuard } from "../src/harden/sentinel-guards.js";
+
+await runGuard(process.argv[2]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.65.1",
+  "version": "4.66.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -67,6 +67,7 @@
   ],
   "bin": {
     "kj": "bin/kj.js",
+    "kj-hook": "bin/kj-hook.js",
     "kj-tail": "bin/kj-tail",
     "kj-trash": "packages/ai-trash/bin/kj-trash.js",
     "karajan-mcp": "bin/karajan-mcp.js",

package/scripts/esbuild-sea.config.mjs

@@ -29,9 +29,13 @@ const seaTransformPlugin = {
       // 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.
+      // KJC-BUG-0402: a guard's own import.meta.url is text here; spelled with an
+      // escaped dot it stays the same string at run time and out of the rewrite below.
       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")));
+        const escapedDot = `${String.fromCodePoint(92)}u002e`;
+        const asText = (rel) => JSON.stringify(readFileSync(path.resolve(path.dirname(args.path), rel), "utf8")).replaceAll("import.meta.url", `import.meta${escapedDot}url`);
+        contents = contents.replace(SENTINEL_READ, (_m, rel) => asText(rel));
         modified = true;
       }
 

package/src/checks/guarantee-level.js

@@ -9,6 +9,8 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { detectHostAgent } from "../utils/agent-detect.js";
+import { wiringState } from "../harden/harness-hooks.js";
+import { SENTINEL_WIRING } from "../harden/sentinel-hooks.js";
 
 /** Pure: computes the three tiers from observable facts. */
 export function guaranteeLevel({ host, harnessWired, policyDeclared, policyWorkflow }) {
@@ -28,10 +30,11 @@ export function guaranteeLevel({ host, harnessWired, policyDeclared, policyWorkf
 
 /** Facts from disk + env; injectable for tests. */
 export function collectGuaranteeFacts({ projectDir = process.cwd(), deps = {} } = {}) {
-  const { detectHost = detectHostAgent, exists = existsSync } = deps;
+  // KJC-TSK-1208 (ADR 0030): the Sentinel is its wiring now, not files in the project.
+  const { detectHost = detectHostAgent, exists = existsSync, sentinelWired = () => wiringState({ projectDir, entries: SENTINEL_WIRING }).missing.length === 0 } = deps;
   return guaranteeLevel({
     host: detectHost(),
-    harnessWired: exists(join(projectDir, ".karajan", "harness", "pretooluse-sentinel.mjs")),
+    harnessWired: sentinelWired(),
     policyDeclared: exists(join(projectDir, ".karajan", "policy.yml")),
     policyWorkflow: exists(join(projectDir, ".github", "workflows", "kj-policy.yml")),
   });

package/src/cli/register-meta.js

@@ -42,8 +42,8 @@ import { policyAddCommand } from "../policy/add.js";
 import { withConfig } from "./_shared.js";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { spawnSync } from "node:child_process";
 import { verifySentinelScripts, resolveSentinelRoot } from "../harden/sentinel-hooks.js";
+import { runGuard } from "../harden/sentinel-guards.js";
 import { boardGate } from "../review/board-pending.js";
 import { panelDeviation } from "../environment/panel.js";
 import { detectHostAgent } from "../utils/agent-detect.js";
@@ -697,14 +697,15 @@ export function registerMeta(program, { pkgVersion }) {
   const sentinel = program.command("sentinel").description("Deterministic method supervisor wired into the harness hooks (Claude Code)");
   sentinel.command("status")
     .description("Print the per-session method facts (sources/tests edited, escapes used) and any open violation the Stop gate would block on")
-    .action(() => {
-      const script = join(resolveSentinelRoot(), ".karajan", "harness", "stop.mjs");
-      if (!existsSync(script)) {
+    .action(async () => {
+      if (!existsSync(join(resolveSentinelRoot(), ".karajan", "harness"))) {
         console.log("sentinel: not installed in this project — run `kj harden` (standard profile or higher)");
         process.exitCode = 1;
         return;
       }
-      process.exitCode = spawnSync("node", [script, "--status"], { stdio: "inherit" }).status ?? 0;
+      // KJC-TSK-1208 (ADR 0030): the Stop guard of this kj, in its report mode.
+      process.argv.push("--status");
+      await runGuard("stop");
     });
   sentinel.command("verify")
     .description("Verify the harness scripts match this kj install — the root of trust is the installed package, not the project tree; exit 1 lists what was modified")
@@ -720,6 +721,13 @@ export function registerMeta(program, { pkgVersion }) {
       else console.log(res.ok ? "sentinel verify: scripts intactos" : `sentinel verify: modificados fuera de kj harden: ${res.mismatched.join(", ")} — restaura con kj harden`);
       process.exitCode = res.ok ? 0 : 1;
     });
+  // KJC-TSK-1204 (ADR 0030): the single-file binary has no kj-hook, so its
+  // wiring runs the guards through here, from the same closed list.
+  sentinel.command("hook <guard>")
+    .description("Run one Sentinel guard from this kj install, reading the hook's input from stdin (the wiring of a single-file kj; npm installs use kj-hook)")
+    .action(async (guard) => {
+      await runGuard(guard);
+    });
   // KJC-TSK-0868: el anfitrión escribiendo con otro coder declarado no se
   // bloquea, se registra. El Stop gate pregunta una vez por sesión.
   sentinel.command("panel-check")

package/src/harden/advisory.js

@@ -13,6 +13,8 @@ import { join } from "node:path";
 
 import { findManagedBlock } from "../utils/managed-markers.js";
 import { findAlternative } from "./alternatives.js";
+import { wiringState } from "./harness-hooks.js";
+import { SENTINEL_WIRING } from "./sentinel-hooks.js";
 import { CONFIGS_BY_LANGUAGE, UNIVERSAL_CONFIGS } from "./config-templates.js";
 import { detectStackRoots } from "./stack-roots.js";
 
@@ -169,14 +171,15 @@ export function classifyArtifact(searchDir, artifact, altDirs = [searchDir]) {
 // KJC-BUG-0335 (#2094): the method's own pieces, not only the configs. Without
 // them the report said "0 missing" while the review gate demanded the Sentinel.
 const METHOD_PIECES = [
+  // KJC-TSK-1208 (ADR 0030): the Sentinel is its wiring to the installed kj, not files.
   { id: "sentinel", what: "the Sentinel (it records the session, the RAG queries the review gate needs among them)",
-    files: [".karajan/harness/pretooluse-sentinel.mjs", ".karajan/harness/posttooluse.mjs", ".karajan/harness/stop.mjs"] },
+    files: [".claude/settings.json"], missingOf: (projectDir) => wiringState({ projectDir, entries: SENTINEL_WIRING }).missing },
   { id: "git-hooks", what: "the git hooks", files: [".karajan/hooks/pre-commit", ".karajan/hooks/commit-msg", ".karajan/hooks/pre-push"] },
 ];
 
-function methodPiece(projectDir, { id, what, files }) {
+function methodPiece(projectDir, { id, what, files, missingOf }) {
   const head = { dir: ".", id, file: files[0], currentVersion: null, managedVersion: null, upToDate: null, improvements: [], mergeable: false };
-  const missing = files.filter((f) => !existsSync(join(projectDir, f)));
+  const missing = missingOf ? missingOf(projectDir) : files.filter((f) => !existsSync(join(projectDir, f)));
   return missing.length === 0
     ? { ...head, status: "KJ_MANAGED", foundAt: files[0], recommendation: "keep", rationale: `${what}: installed` }
     : { ...head, status: "MISSING", foundAt: null, missing, recommendation: "install", rationale: `kj harden (without --report) installs ${what}; missing: ${missing.join(", ")}` };

package/src/harden/harness-hooks.js

@@ -10,30 +10,14 @@
  * supports tool hooks.
  */
 
-import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { isSea } from "node:sea";
 
-const SCRIPT_BODY = `#!/usr/bin/env node
-// kj tool gate (KJC-TSK-0710) — managed by \`kj harden\`. Exit 2 blocks the
-// tool call (stderr explains why); anything unexpected fails OPEN (exit 0)
-// so a gate bug never bricks the session.
-import console from "node:console";
-import process from "node:process";
-import { existsSync } from "node:fs";
-let raw = "";
-process.stdin.on("data", (d) => { raw += d; });
-process.stdin.on("end", () => {
-  try {
-    const { tool_name: tool, tool_input: input = {} } = JSON.parse(raw);
-    if (tool === "Write" && input.file_path && existsSync(input.file_path)) {
-      console.error("kj tool gate: Write over an EXISTING file destroys unseen changes — use Edit for targeted changes.");
-      process.exit(2);
-    }
-  } catch { /* fail open */ }
-  process.exit(0);
-});
-`;
+// KJC-TSK-1204 (ADR 0030): the tool gate is a module of the package, like the
+// Sentinel's guards, so kj-hook can run it from there.
+const SCRIPT_BODY = readFileSync(new URL("./sentinel/pretooluse.mjs", import.meta.url), "utf8");
 
 /** Write a managed hook script under .karajan/harness/ and return its path. */
 /**
@@ -50,6 +34,62 @@ export function writeHarnessScript(projectDir, name, body) {
   return abs;
 }
 
+/**
+ * KJC-TSK-1204 (ADR 0030): the hook runs the guard from the installed kj, never
+ * a copy in the project. npm installs have kj-hook; the single-file kj, or an
+ * install whose kj-hook is not on the PATH yet (a linked kj predating it), runs
+ * it through `kj sentinel hook`, which exists wherever kj harden ran. Without
+ * the runner, a hook before a tool blocks (no kj, no governance: the
+ * maintainer's decision) and any other one warns.
+ */
+export const kjHookOnPath = () => spawnSync("sh", ["-c", "command -v kj-hook"], { stdio: "ignore" }).status === 0;
+
+export function guardCommand(guard, { blocking = false, viaKj = isSea() || !kjHookOnPath() } = {}) {
+  const [bin, run] = viaKj ? ["kj", `kj sentinel hook ${guard}`] : ["kj-hook", `kj-hook ${guard}`];
+  const missing = `echo "karajan: ${bin} no está en el PATH — instala kj (npm i -g @karajan-family/code); sin él el Sentinel no gobierna esta sesión" >&2`;
+  return `if command -v ${bin} >/dev/null 2>&1; then ${run}; else ${missing}${blocking ? "; exit 2" : ""}; fi`;
+}
+
+/** The wiring kj harden wrote before ADR 0030: node running the project's copy. */
+const withoutLegacy = (list, script) => {
+  const legacy = `node ${join(".karajan", "harness", script)}`;
+  return list.flatMap((e) => {
+    if (!Array.isArray(e?.hooks) || !e.hooks.some((h) => h?.command === legacy)) return [e];
+    const hooks = e.hooks.filter((h) => h?.command !== legacy);
+    return hooks.length ? [{ ...e, hooks }] : [];
+  });
+};
+
+/**
+ * KJC-TSK-1206 (ADR 0030): the wiring is what decides which guard runs, so it is
+ * what gets verified. Every expected entry must call its guard, by the package
+ * runner or by the old `node .karajan/harness/<script>`; `missing` names each
+ * one that does not, and an unreadable settings file is missing everything.
+ * "files" = some entry still runs the project's copies, so those copies are live
+ * and verified as before; "wiring" = every entry runs the installed kj.
+ */
+export function wiringState({ projectDir, entries }) {
+  let hooks;
+  try {
+    hooks = JSON.parse(readFileSync(join(projectDir, ".claude", "settings.json"), "utf8"))?.hooks;
+  } catch {
+    hooks = null;
+  }
+  if (!hooks || typeof hooks !== "object") return { mode: "wiring", missing: [".claude/settings.json (sin hooks legibles)"] };
+  const missing = [];
+  let legacy = false;
+  for (const { event, matcher, script } of entries) {
+    const guard = script.replace(/\.mjs$/, "");
+    const runner = [true, false].map((viaKj) => guardCommand(guard, { blocking: event === "PreToolUse", viaKj }));
+    const old = `node ${join(".karajan", "harness", script)}`;
+    const here = (Array.isArray(hooks[event]) ? hooks[event] : []).filter((e) => e?.matcher === matcher).flatMap((e) => (Array.isArray(e?.hooks) ? e.hooks : []));
+    if (here.some((h) => runner.includes(h?.command))) continue;
+    if (here.some((h) => h?.command === old)) legacy = true;
+    else missing.push(`${event} → ${guard}`);
+  }
+  return { mode: legacy ? "files" : "wiring", missing: [...new Set(missing)] };
+}
+
 /**
  * Merge hook entries into .claude/settings.json. Preserve, never clobber:
  * invalid JSON or a hook event with an unexpected (non-array) shape is the
@@ -76,13 +116,15 @@ export function mergeClaudeHooks({ projectDir, logger = console, entries }) {
       return { wired: false };
     }
   }
+  const viaKj = isSea() || !kjHookOnPath();
   for (const { event, matcher, script } of entries) {
-    const list = Array.isArray(settings.hooks[event]) ? settings.hooks[event] : [];
+    const list = withoutLegacy(Array.isArray(settings.hooks[event]) ? settings.hooks[event] : [], script);
+    const command = guardCommand(script.replace(/\.mjs$/, ""), { blocking: event === "PreToolUse", viaKj });
     const present = list.some(
-      (e) => JSON.stringify(e).includes(script) && (matcher === undefined || e?.matcher === matcher),
+      (e) => (e?.hooks || []).some((h) => h?.command === command) && (matcher === undefined || e?.matcher === matcher),
     );
     if (!present) {
-      const cmd = { type: "command", command: `node ${join(".karajan", "harness", script)}` };
+      const cmd = { type: "command", command };
       list.push(matcher === undefined ? { hooks: [cmd] } : { matcher, hooks: [cmd] });
     }
     settings.hooks[event] = list;
@@ -105,7 +147,17 @@ function resolveProjectRoot(dir) {
   }
 }
 
-/** Write the script and merge the PreToolUse entries into .claude/settings.json. */
+/** The tool gate's place in the host settings. */
+export const HARNESS_WIRING = [
+  { event: "PreToolUse", matcher: "Write", script: "pretooluse.mjs" },
+  { event: "PreToolUse", matcher: "Bash", script: "pretooluse.mjs" },
+];
+
+/**
+ * Merge the tool gate's PreToolUse entries into .claude/settings.json. KJC-TSK-1208
+ * (ADR 0030): the gate runs from the installed kj, so the copy an older kj wrote
+ * into the project is retired once the hooks call the package's.
+ */
 export function installHarnessHooks({ projectDir = process.cwd(), logger = console } = {}) {
   // KJC-BUG-0223: el harness es del proyecto y vive en su raiz. Instalado desde
   // un subdirectorio sembraba ahi un segundo `.karajan/harness` que no gobierna
@@ -113,14 +165,8 @@ export function installHarnessHooks({ projectDir = process.cwd(), logger = conso
   const root = resolveProjectRoot(projectDir);
   if (root !== projectDir) logger?.info?.(`kj harden: el harness es del proyecto, se instala en su raíz (${root})`);
   projectDir = root;
-  const scriptAbs = writeHarnessScript(projectDir, "pretooluse.mjs", SCRIPT_BODY);
-  const { wired } = mergeClaudeHooks({
-    projectDir,
-    logger,
-    entries: [
-      { event: "PreToolUse", matcher: "Write", script: "pretooluse.mjs" },
-      { event: "PreToolUse", matcher: "Bash", script: "pretooluse.mjs" },
-    ],
-  });
-  return { script: scriptAbs, wired };
+  const { wired } = mergeClaudeHooks({ projectDir, logger, entries: HARNESS_WIRING });
+  const copy = join(projectDir, ".karajan", "harness", "pretooluse.mjs");
+  if (wired && existsSync(copy)) rmSync(copy);
+  return { wired };
 }

package/src/harden/hook-templates.js

@@ -159,6 +159,11 @@ export function hookBody(hook, cmds = {}, { globalHooksDir = null, baseBranch =
         "if git diff --cached --name-only --diff-filter=d | grep -qE '^(\\.claude/[^/]*\\.lock|\\.claude/scheduled_tasks\\.lock|\\.kj/|\\.karajan/identity\\.local\\.yml|\\.karajan/harness/sentinel-state\\.json)'; then",
         "  echo 'kj harden: agent runtime files are staged (.claude/*.lock, .kj/, identity.local.yml, sentinel-state.json) — unstage them: git restore --staged <path>'; exit 1",
         "fi",
+        "# KJC-TSK-1205 (ADR 0030): a tampered Sentinel is caught before each commit,",
+        "# not only when the turn ends. Only where it is installed; no kj, no check.",
+        "if [ -d .karajan/harness ] && command -v kj >/dev/null 2>&1; then",
+        "  kj sentinel verify >/dev/null 2>&1 || { echo 'kj harden: the Sentinel is tampered with (kj sentinel verify says how) — restore it with kj harden'; exit 1; }",
+        "fi",
         "# v4 review gate (ENV-C1, opt-in via `kj review --install-gate`):",
         "# a staged diff only enters with a recorded cross-AI approved verdict.",
         "# KJC-BUG-0165: the gate is active once the marker is COMMITTED (HEAD),",

package/src/harden/sentinel/posttooluse.mjs

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+// kj sentinel state writer (KJC-TSK-0713) — managed by `kj harden`.
+// Records deterministic method facts per session; never blocks, never fails
+// a tool call (PostToolUse, always exit 0).
+import console from "node:console";
+import process from "node:process";
+import { realpathSync } from "node:fs";
+import { basename, dirname, join, 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";
+let raw = "";
+process.stdin.on("data", (d) => { raw += d; });
+process.stdin.on("end", () => {
+  try {
+    const { session_id: sid = "default", tool_name: tool, tool_input: input = {}, tool_response: response = {} } = JSON.parse(raw);
+    // KJC-TSK-0765 board-sync: a merge that gh CONFIRMS leaves its card pending
+    // in the tracker (the PreToolUse gate then refuses to advance until it is
+    // moved). Recorded here, after the fact, so a failed merge never blocks.
+    const text = typeof response === "string" ? response : JSON.stringify(response);
+    // Closing states that count as "registered in the tracker" (PG statuses and
+    // HU Board moves). The pending entry is cleared by the REAL tool call that
+    // moved the card — never by a promise in the agent's prose.
+    const CLOSING = ["to validate", "to-validate", "fixed", "verified", "closed", "done", "done&validated", "validated"];
+    const clearPending = (cardId) => {
+      const state = load();
+      const s = session(state, sid);
+      s.pending_moves = (s.pending_moves || []).filter((p) => p.card !== null && p.card !== cardId);
+      // KJC-TSK-0774: a card closed this turn is what the Stop hook points the
+      // user at when the focus comes back (the board is where to look).
+      if (cardId && !(s.closed_cards ||= []).includes(cardId)) s.closed_cards.push(cardId);
+      save(state);
+    };
+    // KJC-TSK-0847 (ADR 0010, RAG-A): the ledger of what the RAG answered in
+    // this session — every kj_rag_query (MCP) and kj rag query (CLI) with the
+    // repo-relative sources it returned. Neither the CLI nor the MCP know the
+    // host's session id: the harness records, they do not. Hits outside the
+    // repo (another indexed project) are not ours and are dropped.
+    // KJC-BUG-0190: an index with nothing in it (a brand new project) answers
+    // every question with silence, so the gate would demand what no query can
+    // deliver. kj says so explicitly, in both its human and json forms.
+    const EMPTY_INDEX = /No chunks indexed yet|"empty"\s*:\s*true/;
+    // KJC-BUG-0293 (#1996, #1995): the index names its sources through whatever
+    // spelling of the project directory indexed them (a symlinked workspace, an
+    // alias). Compared as TEXT against the harness root, every hit fell outside
+    // the tree and was dropped in silence: rag_hits stayed empty and only new
+    // files passed. Both sides are compared by REAL path, and what still falls
+    // outside is written down for the gate to name.
+    // A path whose file is gone (or not yet there) resolves through its deepest
+    // existing ancestor, so an alias of the directory still lands in the tree.
+    const realOf = (p) => {
+      try { return realpathSync(p); } catch { /* resolve the parent instead */ }
+      const d = dirname(p);
+      return !d || d === p ? p : join(realOf(d), basename(p));
+    };
+    const ROOT_REAL = realOf(ROOT);
+    const recordRag = (query, sources, answer = "") => {
+      const state = load();
+      const s = session(state, sid);
+      s.at = Date.now();
+      if (EMPTY_INDEX.test(String(answer))) s.rag_index_empty = true;
+      const hits = [];
+      const dropped = [];
+      for (const src of sources) {
+        const rel = relative(ROOT_REAL, realOf(String(src))).split(String.fromCharCode(92)).join("/");
+        if (!rel || rel === ".." || rel.startsWith("../") || rel.startsWith("/")) { dropped.push(String(src)); continue; }
+        if (!hits.includes(rel)) hits.push(rel);
+      }
+      (s.rag_queries ||= []).push({ ts: Date.now(), text: String(query || "").slice(0, 200), hits });
+      const all = (s.rag_hits ||= []);
+      for (const h of hits) if (!all.includes(h)) all.push(h);
+      if (hits.length === 0 && dropped.length > 0) s.rag_dropped = { root: ROOT_REAL, count: dropped.length, sample: dropped.slice(0, 3) };
+      else if (hits.length > 0) delete s.rag_dropped; // an answer inside the tree ends the diagnosis
+      save(state);
+    };
+    // Sources are read STRUCTURALLY, never through the stringified response:
+    // a JSON document (the MCP {content:[{text}]} parts, the CLI --json array)
+    // is parsed and its hits[].source / [].source collected.
+    const sourcesOf = (doc) => {
+      const list = Array.isArray(doc) ? doc : Array.isArray(doc?.hits) ? doc.hits : [];
+      return list.map((h) => h?.source).filter((x) => typeof x === "string");
+    };
+    const parseJson = (t) => { try { return JSON.parse(t); } catch { return null; } };
+    if (/__kj_rag_query$/.test(String(tool)) && /^mcp__/.test(String(tool))) {
+      // KJC-BUG-0293: the host may hand the answer as {content:[parts]}, as the
+      // bare array of parts, or as the text itself; all three are the same answer.
+      const parts = Array.isArray(response?.content) ? response.content : Array.isArray(response) ? response : [{ text: typeof response === "string" ? response : "" }];
+      let found = parts.flatMap((p) => sourcesOf(parseJson(String(p?.text || ""))));
+      // KJC-BUG-0365 (#2208): an answer cut short (whole code chunks) is no
+      // longer valid JSON, but every "source" it carries still names a hit.
+      if (found.length === 0) found = [...text.matchAll(/\\?"source\\?"\s*:\s*\\?"([^"\\]+)\\?"/g)].map((m) => m[1]);
+      recordRag(input.text, found, parts.map((p) => String(p?.text || "")).join(String.fromCharCode(10)));
+      process.exit(0);
+    }
+    if (/__update_card$/.test(String(tool)) && /^mcp__/.test(String(tool))) {
+      // The MCP response reaches the hook as {content:[{text:"<json>"}]}: once
+      // stringified, the inner quotes are ESCAPED — match both forms (found live:
+      // the first real update_card did not clear its pending entry).
+      const cid = /\\?"cardId\\?"\s*:\s*\\?"([A-Za-z0-9-]+)\\?"/.exec(text);
+      const st = /\\?"status\\?"\s*:\s*\\?"([^"\\]+)\\?"/.exec(text);
+      if (cid && st && CLOSING.includes(st[1].toLowerCase())) {
+        clearPending(cid[1].toUpperCase());
+        // KJC-BUG-0157: a pending whose card-id NEVER existed (branch named
+        // before the tracker confirmed the create) could not be cleared by any
+        // verified route. The pending's TRUE identity is its PR: a CONFIRMED
+        // closing update whose request names that PR clears it too — still a
+        // real tracker call seen by this hook, never a promise in prose.
+        const prIn = Number(input?.updates?.pipelineStatus?.prCreated?.prNumber);
+        if (Number.isFinite(prIn) && prIn > 0) {
+          const state = load();
+          const s = session(state, sid);
+          s.pending_moves = (s.pending_moves || []).filter((p) => Number(p.pr) !== prIn);
+          save(state);
+        }
+      }
+      process.exit(0);
+    }
+    if (tool === "Bash") {
+      const cmdText = String(input.command || "");
+      // CLI form of the ledger: the human output lists one hit per line as
+      // "[kind · label · score=…] <path>"; --json prints an array with "source".
+      const ragCmd = /kj +rag +query/.exec(cmdText);
+      if (ragCmd) {
+        const out = typeof response === "string" ? response : String(response.stdout || "") + String(response.stderr || "");
+        const fromLines = out.split(String.fromCharCode(10))
+          .filter((l) => l.includes("score=") && l.includes("] "))
+          .map((l) => l.slice(l.lastIndexOf("] ") + 2).trim())
+          .filter(Boolean);
+        recordRag(cmdText.slice(ragCmd.index), fromLines.concat(sourcesOf(parseJson(out.trim()))), out);
+        process.exit(0);
+      }
+      // gh prints "merged pull request #N" only on a TTY: under a tool call the
+      // success line is ABSENT (found live on the first dogfood merge). The
+      // authoritative signal is the PR state itself: one gh pr view per merge.
+      const mergeCmd = /\bgh\s+pr\s+merge(\s+(\d+))?/.exec(cmdText);
+      const said = /merged pull request #(\d+)/i.exec(text);
+      let mergedPr = said ? Number(said[1]) : null;
+      // KJC-BUG-0148: the card belongs to the PR's HEAD branch, not to whatever
+      // branch the working tree happens to be on (found live: a merge issued
+      // from another card's lane pinned the pending move on the wrong card).
+      let headRef = null;
+      if (mergeCmd || said) {
+        const n = said ? said[1] : mergeCmd[2];
+        const args = ["pr", "view", ...(n ? [n] : []), "--json", "number,state,headRefName"];
+        const r = spawnSync("gh", args, { cwd: ROOT, encoding: "utf8" });
+        try {
+          const v = JSON.parse(r.status === 0 ? r.stdout : "null");
+          if (v && v.state === "MERGED") { mergedPr = Number(v.number); headRef = v.headRefName || null; }
+        } catch { /* unknown = not confirmed (or confirmed only by the printed line) */ }
+      }
+      if (mergedPr !== null) {
+        const state = load();
+        const s = session(state, sid);
+        const ref = CARD.exec(headRef || branchOf() || "");
+        // KJC-BUG-0230: una EPICA (…-PCS-…) no tiene estado que mover: el PG
+        // la deja en To Do por mas status que reciba y kj hu move no la
+        // conoce. Registrarla como pendiente era un bloqueo sin cauce. Se dice
+        // en el momento, para que no parezca que el board dejo de mirar.
+        const epic = ref && /-PCS-/i.test(ref[0]);
+        if (epic) {
+          console.error("karajan sentinel: board-sync — la PR #" + mergedPr + " pertenece a la epica " + ref[0].toUpperCase() + ", que no tiene estado que mover: no queda pendiente (su cierre va en la descripcion de la epica)");
+        } else {
+          (s.pending_moves ||= []).push({ card: ref ? ref[0].toUpperCase() : null, pr: mergedPr, at: Date.now(), ...(headRef ? {} : { head: "unknown" }) });
+        }
+        save(state);
+      }
+      const moved = /kj\s+hu\s+move\s+([A-Za-z0-9-]+)\s+([a-z&-]+)/i.exec(String(input.command || ""));
+      // "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;
+    if (!["Write", "Edit", "MultiEdit", "NotebookEdit"].includes(tool) || !file) process.exit(0);
+    const state = load();
+    const s = session(state, sid);
+    s.at = Date.now();
+    const rel = relative(ROOT, file).replaceAll("\\", "/");
+    // KJC-BUG-0279 (#1981): a file outside the repository is not one of its sources.
+    const inside = rel && rel !== ".." && !rel.startsWith("../") && !rel.startsWith("/");
+    const bucket = !inside ? null : TESTS.test(rel) ? s.edited_tests : CODE.test(rel) ? s.edited_sources : null;
+    if (bucket && !bucket.includes(rel)) bucket.push(rel);
+    // KJC-TSK-0910: the branch size while it is written, with the CI budget
+    // (kj pr-size), said once per threshold crossed. Context, never a block.
+    let sizeNote = null;
+    if (bucket) {
+      const ps = spawnSync("kj", ["pr-size", "--json"], { cwd: ROOT, encoding: "utf8", timeout: 5000 });
+      let size = null;
+      try { size = JSON.parse(String(ps.stdout || "").trim().split(String.fromCharCode(10)).pop()); } catch { size = null; }
+      const crossed = size ? [200, 150].find((t) => size.added > t) : undefined;
+      if (crossed && (s.size_warned || 0) < crossed) {
+        s.size_warned = crossed;
+        sizeNote = "karajan sentinel: la rama ya suma " + size.added + " lineas contables (" + size.testAdded + " de tests); " + (crossed >= 200 ? "pasa el limite de 200 del CI: parte antes de seguir" : "pasa de 150: planea la particion ahora, no en el stage");
+      }
+    }
+    const ids = Object.keys(state.sessions);
+    if (ids.length > 5) delete state.sessions[ids.sort((a, b) => (state.sessions[a].at || 0) - (state.sessions[b].at || 0))[0]];
+    save(state);
+    if (sizeNote) process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: sizeNote } }));
+  } catch { /* fail open — the sentinel never breaks a tool call */ }
+  process.exit(0);
+});