karajan-code 4.65.0 → 4.66.0

package/src/harden/sentinel/pretooluse.mjs

@@ -0,0 +1,19 @@
+#!/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);
+});

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

@@ -0,0 +1,114 @@
+// kj sentinel shared lib (KJC-TSK-0714) — managed by `kj harden`.
+// Single source for every sentinel script: state, branch, classification,
+// and violations.
+import process from "node:process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { execSync, spawnSync } from "node:child_process";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const here = dirname(fileURLToPath(import.meta.url));
+// KJC-TSK-1202 (ADR 0030): installed in a project the guard sits in .karajan/harness,
+// two levels below its root; run from the kj package, the project is the one the
+// host names (CLAUDE_PROJECT_DIR) or the working directory, at its git root.
+const installed = basename(here) === "harness" && basename(dirname(here)) === ".karajan";
+const projectRoot = () => {
+  const start = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  try { return execSync("git rev-parse --show-toplevel", { cwd: start, stdio: ["ignore", "pipe", "ignore"] }).toString().trim() || start; }
+  catch { return start; }
+};
+export const ROOT = installed ? join(here, "..", "..") : projectRoot();
+export const STATE = join(ROOT, ".karajan", "harness", "sentinel-state.json");
+// INF-A (KJC-TSK-0758): infra IS source — terraform/k8s/shell/Docker edits
+// engage the method like app code; *_test.* files (terratest) are tests.
+export const TESTS = /(^|\/)(tests?|__tests__|spec)\/|\.(test|spec)\.[a-z]+$|_test\.[a-z]+$/;
+export const CODE = /\.(m?[jt]sx?|c[jt]s|py|go|rs|java|rb|php|cs|swift|kt|astro|svelte|vue|c|h|cc|cpp|hpp|tf|hcl|ya?ml|sh)$|(^|\/)(Dockerfile|Makefile|Vagrantfile)$/;
+export const CARD = new RegExp("\\b[a-z][a-z0-9]{1,9}(?:-[a-z][a-z0-9]{1,9})*-\\d{1,6}\\b(?!\\.\\d)", "i");
+export const BASE_BRANCHES = new Set(["main", "master"]);
+export const load = () => { try { return JSON.parse(readFileSync(STATE, "utf8")); } catch { return {}; } };
+export const save = (state) => {
+  mkdirSync(dirname(STATE), { recursive: true });
+  writeFileSync(STATE, JSON.stringify(state, null, 2));
+};
+export const doc = (a) => " — doc: https://karajancode.com/docs/guides/sentinel/#" + a;
+export const session = (state, sid) => {
+  state.sessions ||= {};
+  return (state.sessions[sid] ||= { edited_sources: [], edited_tests: [], escapes: [], errors: [], blocks: 0 });
+};
+export const branchOf = () => {
+  try { return execSync("git rev-parse --abbrev-ref HEAD", { cwd: ROOT, stdio: ["ignore", "pipe", "ignore"] }).toString().trim(); }
+  catch { return null; }
+};
+const _git = (args, cwd) => {
+  try { return execSync("git " + args, { cwd, stdio: ["ignore", "pipe", "ignore"] }).toString().trim(); } catch { return ""; }
+};
+let _home;
+// MONO-0 (ADR 0002): lane identity = worktree toplevel; repo identity =
+// git-common-dir. Same repo but another toplevel than OUR root => foreign
+// lane (returns its toplevel); anything else => null.
+export const foreignLane = (targetDir) => {
+  const top = _git("rev-parse --show-toplevel", targetDir);
+  if (!top) return null;
+  _home ||= { top: _git("rev-parse --show-toplevel", ROOT), common: _git("rev-parse --path-format=absolute --git-common-dir", ROOT) };
+  if (!_home.top || top === _home.top) return null;
+  const common = _git("rev-parse --path-format=absolute --git-common-dir", targetDir);
+  return common && common === _home.common ? top : null;
+};
+// KJC-TSK-0765 board-sync: cards merged in this session but not yet moved in
+// the tracker. The method does not advance until the board is true.
+export const pendingMoves = (s) => (s && Array.isArray(s.pending_moves) ? s.pending_moves : []);
+export const pendingText = (p) => (p.card ? p.card : "card sin identificar") + " (PR #" + p.pr + ") mergeada sin mover en el tracker — muevela a To Validate / Fixed con sus commits (update_card del PG o kj hu move)";
+// KJC-BUG-0185: bootstrap phase = the repo has no commit yet. There is no base
+// branch to protect and no coverage to demand over a tree that does not exist,
+// and `git diff HEAD` cannot even run. The phase is a verifiable FACT, never a
+// flag, and it ends at the first commit.
+export const bootstrapPhase = () => {
+  try { execSync("git rev-parse --verify HEAD", { cwd: ROOT, stdio: ["ignore", "ignore", "ignore"] }); return false; }
+  catch { return true; }
+};
+// KJC-BUG-0198/0262: a card split across PRs is carried while another PR of it is
+// open. kj decides with that checkable fact, the same answer for commit and push
+// (the Stop gate still holds the turn: the board owes the move); when kj does not
+// answer, every pending move blocks.
+export const boardGate = (sid, pend) => {
+  if (!pend.length) return { blocking: [], carried: [] };
+  const bg = spawnSync("kj", ["sentinel", "board-gate", "--session", sid, "--json"], { cwd: ROOT, encoding: "utf8" });
+  if (!bg.error && (bg.status === 0 || bg.status === 2)) {
+    try { const d = JSON.parse(bg.stdout); return { blocking: d.blocking || [], carried: d.carried || [], reason: d.reason || "" }; } catch { /* unreadable: as always */ }
+  }
+  return { blocking: pend, carried: [] };
+};
+// KJC-BUG-0265: on the base branch what counts is work still there (the session's
+// files dirty, or local commits the remote does not have), not the ledger: after a
+// merged PR and a sync of main the ledger stays full while the base holds nothing.
+// Anything git cannot answer (no upstream, odd path) counts as work: fail closed.
+const baseHoldsWork = (files) => {
+  if (files.some((f) => !/^[A-Za-z0-9._/-]+$/.test(f))) return true;
+  try {
+    if (execSync("git status --porcelain -- " + files.join(" "), { cwd: ROOT, stdio: ["ignore", "pipe", "ignore"] }).toString().trim()) return true;
+    return execSync("git rev-list @{u}..HEAD", { cwd: ROOT, stdio: ["ignore", "pipe", "ignore"] }).toString().trim() !== "";
+  } catch { return true; }
+};
+export const violations = (s, branch, pending = pendingMoves(s)) => {
+  const v = pending.map(pendingText);
+  if (!s || !(s.edited_sources || []).length) return v;
+  if (bootstrapPhase()) return v;
+  if (BASE_BRANCHES.has(branch)) { if (baseHoldsWork(s.edited_sources)) v.push("Fuentes editadas en la rama base '" + branch + "' — crea una rama: git checkout -b feat/<CARD-ID>-descripcion"); }
+  else if (branch && !CARD.test(branch)) v.push("La rama '" + branch + "' no referencia ninguna card — usa feat/<CARD-ID>-descripcion (y una card VIVA en el board)");
+  if (!(s.edited_tests || []).length && sessionAddsCode(s)) v.push("Fuentes editadas sin tocar un solo test (" + s.edited_sources.join(", ") + ") — escribe o actualiza el test que prueba el cambio");
+  return v;
+};
+// KJC-TSK-0795 AC1: deleting code adds no behavior to test — a session whose
+// source edits only REMOVED lines owes no test. Unreadable git = conservative
+// (the violation stands): a gate must never stand down on a shrug.
+const sessionAddsCode = (s) => {
+  const files = s.edited_sources || [];
+  // _git builds a shell string: any path outside a strict charset stays out of
+  // it — and the gate stays ARMED for it (conservative, and injection-proof).
+  if (files.some((f) => !/^[A-Za-z0-9._/-]+$/.test(f))) return true;
+  const stat = _git("diff HEAD --numstat -- " + files.join(" "), ROOT);
+  if (!stat) return true;
+  return stat.split(String.fromCharCode(10)).some((l) => {
+    const a = l.trim().replaceAll(String.fromCharCode(9), " ").split(" ").filter(Boolean)[0];
+    return a === "-" || Number(a) > 0;
+  });
+};

package/src/harden/sentinel/sessionstart.mjs

@@ -38,13 +38,23 @@ process.stdin.on("end", () => {
       lines.push("Karajan (reglas que la compactación se lleva):", ...RULES, `Estado: rama ${branch}, card ${card}${unmoved}.`);
     }
     if (drift) lines.push(`Karajan: ${drift}`);
+    // KJC-TSK-1205 (ADR 0030): integrity is checked when the session starts, not only
+    // when a turn ends. Said first, to the agent and to the person; kj missing says nothing.
+    const ver = spawnSync("kj", ["sentinel", "verify", "--json"], { cwd: ROOT, encoding: "utf8", timeout: 15000 });
+    let alarm = null;
+    if (!ver.error && ver.status !== 0 && ver.status !== null) {
+      let what = ["?"];
+      try { what = JSON.parse(ver.stdout).mismatched || what; } catch { /* unreadable: still tampered */ }
+      alarm = `el supervisor está manipulado (${what.join(", ")}): restaura con kj harden y avisa a tu usuario antes de seguir.`;
+      lines.unshift(`Karajan: ${alarm}`);
+    }
     // KJC-TSK-0986 (HUM-F, ADR 0018): once per kj version, the invitation to
     // enroll the phone when none is; kj decides and remembers, the hook relays.
     const invite = spawnSync("kj", ["identity", "phone-invite"], { encoding: "utf8", timeout: 8000 });
     const inviteText = invite.status === 0 ? String(invite.stdout || "").trim() : "";
     if (inviteText) lines.push(`Karajan: ${inviteText}`);
     if (lines.length === 0) process.exit(0);
-    process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: lines.join("\n") } }));
+    process.stdout.write(JSON.stringify({ ...(alarm ? { systemMessage: `Karajan: ${alarm}` } : {}), hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: lines.join("\n") } }));
   } catch { /* never fails a session */ }
   process.exit(0);
 });

package/src/harden/sentinel/stop.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// kj sentinel stop gate (KJC-TSK-0713) — managed by `kj harden`. Exit 2
+// BLOCKS ending the turn while method violations are open (stderr lists each
+// one with its remediation). Fails OPEN on corrupt state, git errors, or
+// after 3 unresolved blocks — a sentinel bug never bricks the session — and
+// the fail-open is recorded in the state. `--status` prints, never blocks.
+import console from "node:console";
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { doc, load, save, branchOf, violations, ROOT } from "./sentinel-lib.mjs";
+// KJC-TSK-0774: when the turn ends green with cards closed, remind the user
+// where to look — the board URL if it runs (pid file alive), else how to start it.
+const boardHint = () => {
+  const home = process.env.KARAJAN_HOME || process.env.KJ_HOME || join(homedir(), ".karajan");
+  try {
+    process.kill(Number(readFileSync(join(home, "hu-board.pid"), "utf8").trim()), 0);
+    return "http://localhost:" + (process.env.KJ_BOARD_PORT || "4000") + "/#governance";
+  } catch { return "no esta arrancado: kj board start (luego http://localhost:4000/#governance)"; }
+};
+if (process.argv.includes("--status")) {
+  const st = load();
+  const branch = branchOf();
+  const sessions = Object.entries(st.sessions || {});
+  if (!sessions.length) console.log("sentinel: sin actividad registrada en esta sesion");
+  for (const [sid, s] of sessions) {
+    console.log("session " + sid + ": sources=[" + (s.edited_sources || []).join(", ") + "] tests=[" + (s.edited_tests || []).join(", ") + "] escapes=[" + (s.escapes || []).join(", ") + "] blocks=" + (s.blocks || 0) + ((s.errors || []).length ? " errors=" + s.errors.length : "") + " rag=" + (s.rag_queries || []).length + " queries/" + (s.rag_hits || []).length + " sources");
+    for (const x of violations(s, branch)) console.log("  ROJO: " + x);
+  }
+  process.exit(0);
+}
+let raw = "";
+process.stdin.on("data", (d) => { raw += d; });
+process.stdin.on("end", () => {
+  try {
+    if (process.env.KJ_SENTINEL_OFF === "1") process.exit(0);
+    const { session_id: sid = "default", transcript_path: transcript = null } = JSON.parse(raw);
+    const state = load();
+    // Tamper check runs regardless of session state: shell indirection leaves
+    // no edit-tool record, but it cannot survive `kj sentinel verify`, whose
+    // root of trust is the INSTALLED kj package (outside this project tree) —
+    // nothing under .karajan can vouch for itself. No kj on PATH → fail open.
+    const ver = spawnSync("kj", ["sentinel", "verify", "--json"], { cwd: ROOT, encoding: "utf8" });
+    let tampered = [];
+    if (!ver.error && ver.status !== null && ver.status !== 0) {
+      try { tampered = JSON.parse(ver.stdout).mismatched || ["unknown"]; } catch { tampered = ["unknown"]; }
+    }
+    if (tampered.length) {
+      // KJC-TSK-1205 (ADR 0030): tampering is not a Sentinel failure, so it never
+      // fails open; the count stays as a record of how long it went unrestored.
+      state.tamper_blocks = (state.tamper_blocks || 0) + 1;
+      save(state);
+      console.error("karajan sentinel: scripts del supervisor modificados fuera de kj harden (" + tampered.join(", ") + ") — restaura con kj harden antes de terminar; si lo cambiaste tu (humano), reinstalar lo deja en verde." + doc("supervisor"));
+      process.exit(2);
+    }
+    state.tamper_blocks = 0;
+    // CLM-B (KJC-TSK-0802, claims-with-evidence ADR): the hard data of the turn's
+    // final message, crossed against that turn's outputs. It runs even without a
+    // tracked session — a turn with no edits still ends with a final message. The
+    // hook carries no policy: kj reads method_gates.claims and answers 0 (off,
+    // clean, or warn) or 2 (a datum DENIED by its own source, in block mode). A
+    // missing kj or an errored spawn fails open.
+    let claimsNote = "";
+    let claimsBlock = null;
+    if (transcript) {
+      const c = spawnSync("kj", ["claims", "gate", "--transcript", transcript], { cwd: ROOT, encoding: "utf8" });
+      if (!c.error && c.status === 2) claimsBlock = "claims: un dato del mensaje final esta DESMENTIDO por las salidas de este turno — verificalo o marcalo como no comprobado. Detalle: kj claims check --transcript " + transcript;
+      else if (!c.error && c.status === 0 && (c.stderr || "").trim()) claimsNote = "kj claims: " + c.stderr.trim().split(String.fromCharCode(10))[0] + " — datos sin respaldo en este turno (informa, no bloquea).";
+    }
+    const s = state.sessions?.[sid];
+    if (!s) {
+      if (claimsBlock) { console.error("karajan sentinel: el turno NO puede terminar:" + String.fromCharCode(10) + "- " + claimsBlock + doc("claims")); process.exit(2); }
+      if (claimsNote) console.log(JSON.stringify({ systemMessage: claimsNote }));
+      process.exit(0);
+    }
+    // KJC-TSK-0868: si el anfitrion ha escrito codigo teniendo otro coder
+    // declarado, eso no se bloquea, se REGISTRA: el usuario eligio quien
+    // escribe y merece enterarse por el decision log, no por casualidad. Una
+    // vez por sesion, y si kj no responde se reintenta en el turno siguiente.
+    if (!s.panel_sealed && (s.edited_sources || []).length > 0) {
+      const p = spawnSync("kj", ["sentinel", "panel-check", "--session", sid], { cwd: ROOT, encoding: "utf8" });
+      if (!p.error && p.status === 0) {
+        s.panel_sealed = true;
+        save(state);
+        if ((p.stdout || "").trim()) console.error(p.stdout.trim());
+      }
+    }
+    const v = violations(s, branchOf());
+    if (claimsBlock) v.push(claimsBlock);
+    if (!v.length) {
+      s.blocks = 0;
+      const notes = [];
+      if (claimsNote) notes.push(claimsNote);
+      if ((s.closed_cards || []).length) {
+        notes.push("karajan sentinel: card(s) cerrada(s) en este turno: " + s.closed_cards.join(", ") + " — el board las muestra: " + boardHint());
+        s.closed_cards = [];
+      }
+      save(state);
+      if (notes.length) console.log(JSON.stringify({ systemMessage: notes.join("\n") }));
+      process.exit(0);
+    }
+    s.blocks = (s.blocks || 0) + 1;
+    if (s.blocks > 3) {
+      (s.errors ||= []).push("fail-open: 3 bloqueos consecutivos sin resolver — el sentinel se aparta para no colgar la sesion");
+      save(state);
+      console.error("karajan sentinel: fail-open tras 3 bloqueos sin resolver — revisa kj sentinel status con tu usuario" + doc("stop-gate"));
+      process.exit(0);
+    }
+    save(state);
+    console.error("karajan sentinel: el turno NO puede terminar con el metodo en rojo:\n" + v.map((x) => "- " + x).join("\n") + "\nResuelve las violaciones (o pide a tu usuario el escape) y termina de nuevo. Estado: kj sentinel status" + doc("stop-gate"));
+    process.exit(2);
+  } catch { /* fail open */ }
+  process.exit(0);
+});

package/src/harden/sentinel-guards.js

@@ -0,0 +1,28 @@
+/**
+ * The Sentinel's guards as the hooks name them (KJC-TSK-1204, ADR 0030): one
+ * closed list for both ways of running them from the installed package, the
+ * kj-hook bin and `kj sentinel hook` (the single-file binary has no kj-hook).
+ * Each entry loads only its module, so running a guard never pays the CLI.
+ */
+export const SENTINEL_GUARDS = {
+  pretooluse: () => import("./sentinel/pretooluse.mjs"),
+  "pretooluse-sentinel": () => import("./sentinel/pretooluse-sentinel.mjs"),
+  "pretooluse-rules": () => import("./sentinel/pretooluse-rules.mjs"),
+  posttooluse: () => import("./sentinel/posttooluse.mjs"),
+  stop: () => import("./sentinel/stop.mjs"),
+  sessionstart: () => import("./sentinel/sessionstart.mjs"),
+};
+
+/**
+ * Run one guard: it reads the hook's input from stdin and exits on its own.
+ * A name outside the list exits 2, because a wiring that names no known guard
+ * cannot be trusted to guard anything.
+ */
+export async function runGuard(name, { logger = console, exit = (code) => process.exit(code) } = {}) {
+  if (!Object.hasOwn(SENTINEL_GUARDS, name ?? "")) {
+    logger.error(`kj-hook: "${name ?? ""}" is not a Sentinel guard (${Object.keys(SENTINEL_GUARDS).join(", ")}) — run kj harden to rewrite the wiring`);
+    exit(2);
+    return;
+  }
+  await SENTINEL_GUARDS[name]();
+}