karajan-code 4.55.0 → 4.57.0

package/src/harden/sandbox.js

@@ -0,0 +1,120 @@
+/**
+ * sandbox — kj harden turns the host's Bash sandbox on (KJC-TSK-1087, ADR 0015).
+ *
+ * Claude Code sandboxes Bash with bubblewrap on Linux and seatbelt on macOS. With
+ * allowUnsandboxedCommands off, a sandbox that cannot start leaves the session with
+ * no Bash at all (pilot KJC-TSK-1083: Ubuntu 24.04 restricts user namespaces until
+ * bwrap has an AppArmor profile). So the probe runs first, on this machine.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { delimiter, dirname, join } from "node:path";
+import { spawnSync } from "node:child_process";
+
+const USERNS_SYSCTL = "/proc/sys/kernel/apparmor_restrict_unprivileged_userns";
+
+const whichOnPath = (bin) => (process.env.PATH ?? "").split(delimiter).map((d) => join(d, bin)).find((p) => existsSync(p)) ?? null;
+const runSync = (bin, args) => spawnSync(bin, args, { encoding: "utf8", timeout: 10_000 });
+
+const missing = (tool, pkg) => ({ ok: false, reason: `${tool} is not installed`, remedy: `install ${pkg} (apt install ${pkg}, dnf install ${pkg})` });
+
+function userNamespacesRestricted(readFile) {
+  try { return readFile(USERNS_SYSCTL).trim() === "1"; } catch { return false; }
+}
+
+function probeLinux({ which, run, readFile }) {
+  const bwrap = which("bwrap");
+  if (!bwrap) return missing("bubblewrap (bwrap)", "bubblewrap");
+  if (!which("socat")) return missing("socat", "socat");
+  // The same namespaces Claude Code's sandbox asks for: user and network.
+  const res = run(bwrap, ["--ro-bind", "/", "/", "--dev", "/dev", "--unshare-user", "--unshare-net", "true"]);
+  if (res.status === 0) return { ok: true };
+  if (userNamespacesRestricted(readFile)) {
+    return {
+      ok: false,
+      reason: "AppArmor restricts unprivileged user namespaces and bwrap has no profile",
+      remedy: "add /etc/apparmor.d/bwrap allowing userns for /usr/bin/bwrap, then load it with apparmor_parser -r (your user does this)",
+    };
+  }
+  const detail = String(res.stderr ?? "").trim() || "exit " + res.status;
+  return { ok: false, reason: `bwrap cannot create its namespaces: ${detail}`, remedy: "fix bwrap on this machine, then run kj harden again" };
+}
+
+/**
+ * Can the host sandbox start on this machine? Never throws.
+ * @returns {{ok: true} | {ok: false, reason: string, remedy?: string}}
+ */
+export function probeSandbox({ platform = process.platform, which = whichOnPath, run = runSync, readFile = (p) => readFileSync(p, "utf8"), exists = existsSync } = {}) {
+  if (platform === "linux") return probeLinux({ which, run, readFile });
+  if (platform === "darwin") {
+    if (!exists("/usr/bin/sandbox-exec")) return { ok: false, reason: "sandbox-exec is missing from /usr/bin" };
+    const res = run("/usr/bin/sandbox-exec", ["-p", "(version 1)(allow default)", "/usr/bin/true"]);
+    const detail = String(res.stderr ?? "").trim() || "exit " + res.status;
+    return res.status === 0 ? { ok: true } : { ok: false, reason: `sandbox-exec cannot start a sandbox: ${detail}` };
+  }
+  return { ok: false, reason: `the host sandbox does not run on ${platform}` };
+}
+
+// KJC-TSK-1092: what the method needs from the sandbox (lessons of the pilot, KJC-TSK-1083).
+// gh keeps its tokens in the keyring over D-Bus; kj review reaches a local SonarQube,
+// which the sandbox's private localhost cannot (the reviewer agents run inside it).
+// Outside the project only kj's state and package caches are writable, and the
+// supervisor and the phone key stay out of reach.
+const METHOD_SANDBOX = {
+  excludedCommands: ["gh *", "kj review *"],
+  denyWrite: [".karajan/harness", ".karajan/supervisor-provenance.json", "~/.karajan/supervisor-phone.json"],
+  allowWrite: ["~/.karajan", "~/.npm/_cacache", "~/.npm/_logs", "~/.npm/_npx", "~/.cache", "~/.config/configstore"],
+  allowedDomains: [
+    "github.com", "api.github.com", "*.githubusercontent.com", "uploads.github.com", "registry.npmjs.org",
+    "api.openai.com", "chatgpt.com", "*.openai.com", "api.anthropic.com", "*.anthropic.com", "claude.ai",
+    "api.githubcopilot.com", "*.githubcopilot.com", "*.googleapis.com",
+  ],
+};
+
+const union = (have, add) => [...new Set([...(Array.isArray(have) ? have : []), ...add])];
+
+function withMethodSandbox(settings) {
+  const sb = settings.sandbox ?? {};
+  const fsCfg = sb.filesystem ?? {};
+  const net = sb.network ?? {};
+  return {
+    ...settings,
+    sandbox: {
+      ...sb,
+      enabled: true,
+      allowUnsandboxedCommands: false,
+      excludedCommands: union(sb.excludedCommands, METHOD_SANDBOX.excludedCommands),
+      filesystem: { ...fsCfg, denyWrite: union(fsCfg.denyWrite, METHOD_SANDBOX.denyWrite), allowWrite: union(fsCfg.allowWrite, METHOD_SANDBOX.allowWrite) },
+      network: { ...net, allowedDomains: union(net.allowedDomains, METHOD_SANDBOX.allowedDomains) },
+    },
+  };
+}
+
+/**
+ * Turn the host sandbox on in .claude/settings.local.json when it can start here.
+ * @returns {{state: "on" | "off" | "left-off" | "untouched", reason?: string}}
+ */
+export function installSandbox({ projectDir, logger = console, probe = probeSandbox }) {
+  const ready = probe();
+  if (!ready.ok) {
+    const remedy = ready.remedy ? `; ${ready.remedy}` : "";
+    logger.info?.(`kj harden: host sandbox left off, ${ready.reason}${remedy}`);
+    return { state: "off", reason: ready.reason };
+  }
+  const path = join(projectDir, ".claude", "settings.local.json");
+  let settings = {};
+  if (existsSync(path)) {
+    try {
+      settings = JSON.parse(readFileSync(path, "utf8"));
+    } catch {
+      logger.warn?.(`kj harden: ${path} is not valid JSON, the host sandbox was not written`);
+      return { state: "untouched", reason: "invalid JSON" };
+    }
+  }
+  if (settings.sandbox?.enabled === false) {
+    logger.info?.(`kj harden: the host sandbox stays off, ${path} says enabled: false`);
+    return { state: "left-off", reason: "enabled: false" };
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(withMethodSandbox(settings), null, 2)}\n`);
+  return { state: "on" };
+}

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

@@ -87,20 +87,21 @@ export const isGhIssueCreate = (cmd) => shellSegments(cmd).some((words) => {
 });
 
 // KJC-BUG-0204: the real command puts flags between the verb's words
-// (firebase --account a@b deploy), so they are read in order, not adjacent.
-const PUBLISH_VERBS = [["npm", "publish"], ["firebase", "deploy"], ["gh", "release", "create"]];
+// (npm --prefix x publish), so they are read in order, not adjacent.
+// KJC-BUG-0373: only a release of the package; a deploy (database rules, a site)
+// is not one, and gating it kept an open database open.
+const PUBLISH_VERBS = [["npm", "publish"], ["gh", "release", "create"]];
 // Known options that take a separate value: that value is not a subcommand word
 // (npm --tag publish test does not publish). An unknown option is not skipped, so
 // a real publish behind it is still read (a false positive costs less than a miss).
 const VALUE_OPTIONS = {
   npm: ["--prefix", "--tag", "--registry", "--userconfig", "--workspace", "-w", "--otp", "--access", "--cache", "--loglevel", "-C"],
-  firebase: ["--account", "--project", "-P", "--config", "-c", "--only", "--except", "--token", "--message", "-m"],
   gh: ["--repo", "-R", "--hostname"],
 };
 
 /**
- * KJC-BUG-0333 (#2093): a simple command whose head is npm, firebase or gh and
- * whose own words then say publish/deploy/release create. Words inside a quoted
+ * KJC-BUG-0333 (#2093): a simple command whose head is npm or gh and whose own
+ * words then say publish/release create. Words inside a quoted
  * argument of another command (a kj rag query text, a commit message) are one
  * word of THAT command, so they never read as a publish.
  * @param {string} cmd

package/src/harden/sentinel-hooks.js

@@ -475,7 +475,7 @@ import { appendFileSync, existsSync, readFileSync, realpathSync, statSync } from
 import { spawnSync } from "node:child_process";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
-import { doc, CODE, TESTS, ROOT, BASE_BRANCHES, CARD, STATE, branchOf, foreignLane, load, save, session, violations, boardGate, pendingMoves, pendingText } from "./sentinel-lib.mjs";
+import { doc, CODE, TESTS, ROOT, BASE_BRANCHES, CARD, STATE, branchOf, foreignLane, load, save, session, boardGate, 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 { isGhIssueCreate, isPublishCommand, optionValues, shellSegments, stripInertQuotes, stripTextOptionValues, stripTextOnlyCommandValues } from "./sentinel-shell.mjs";
 import { DISCARD_VERBS, discardOf, foreignLost, removedFiles } from "./sentinel-discard.mjs";
@@ -485,7 +485,6 @@ const inOrder = (want, got) => { let i = 0; for (const w of got) if (w === want[
 // KJC-BUG-0333: a publish is read per simple command by the shell reader, so
 // words inside a quoted argument of another command are not a publish.
 const isPublish = isPublishCommand;
-const PUSH = /\\bgit\\s+push\\b/;
 const PROTECTED = /\\.claude\\/settings\\.json\\b|\\.karajan\\/(hooks|harness)\\//;
 let raw = "";
 process.stdin.on("data", (d) => { raw += d; });
@@ -606,32 +605,17 @@ process.stdin.on("end", () => {
         }
       }
     }
-    // KJC-TSK-0822 v1.1: enrolar (o pisar) la clave del movil es acto humano
-    // — si un agente pudiera enrolar una clave SUYA, contestaria la capa 5 el
-    // solo. Ni el comando ni el fichero de enrolamiento desde la sesion.
+    // KJC-TSK-0822 v1.1: la clave del movil (capa 5) no se toca desde la sesion.
+    // KJC-TSK-1084 (ADR 0015): los comandos de acto humano (kj harden --commit,
+    // kj identity enroll-phone) ya no se leen aqui: la propia orden rechaza un
+    // proceso que desciende de un agente (src/harden/human-act.js). Queda el
+    // FICHERO de la clave, que solo esto protege hasta que el sandbox lo vete.
     {
-      // KJC-BUG-0354: un titulo o un mensaje de commit que solo lo MENCIONA no es enrolar.
-      const enrollCmd = stripTextOnlyCommandValues(String(input.command || ""));
-      const namesEnroll = (enrollCmd.includes("identity") && enrollCmd.includes("enroll-phone")) || enrollCmd.includes("supervisor-phone.json");
+      // KJC-BUG-0354: un titulo o un mensaje de commit que solo lo MENCIONA no es escribirlo.
+      const namesPhoneFile = stripTextOnlyCommandValues(String(input.command || "")).includes("supervisor-phone.json");
       const writesEnroll = EDIT_TOOLS.includes(tool) && String(input.file_path || "").includes("supervisor-phone.json");
-      if ((tool === "Bash" && namesEnroll) || writesEnroll) {
-        console.error("karajan sentinel: el enrolamiento del movil (capa 5) es un acto humano — pideselo a tu usuario; supervisor-phone.json no se toca desde la sesion." + doc("supervisor"));
-        process.exit(2);
-      }
-    }
-    // ADR 0009 (KJC-BUG-0161): kj harden --commit es un ACTO HUMANO — la
-    // sesion ni lo intenta. Sin escape (superficie de supervisor). includes()
-    // a proposito: cero ambiguedad de escapes en plantilla, y fail-closed
-    // (mencionarlo en un argumento tambien bloquea: preferible a un hueco).
-    // KJC-BUG-0354: salvo en el texto entrecomillado de kj hu add, kj adr add y
-    // git commit, que solo guardan texto (decision del usuario, 16-oct).
-    // ANTES de KJ_SENTINEL_OFF a proposito, como el guard PROTECTED de
-    // arriba: un env var lo pone tambien un agente — el supervisor no se
-    // apaga con interruptores al alcance del supervisado.
-    {
-      const kjCmd = stripTextOnlyCommandValues(String(input.command || ""));
-      if (tool === "Bash" && kjCmd.includes("harden") && kjCmd.includes("--commit")) {
-        console.error("karajan sentinel: kj harden --commit es un acto humano (ADR 0009) — pideselo a tu usuario; ninguna sesion de agente lo ejecuta." + doc("supervisor"));
+      if ((tool === "Bash" && namesPhoneFile) || writesEnroll) {
+        console.error("karajan sentinel: la clave del movil (capa 5) es del humano — supervisor-phone.json no se toca desde la sesion; enrolar es kj identity enroll-phone desde su terminal." + doc("supervisor"));
         process.exit(2);
       }
     }
@@ -676,7 +660,6 @@ process.stdin.on("end", () => {
         return v.length > 0 ? v : null;
       };
       const declaredGh = idLine("gh_user");
-      const declaredEmail = idLine("git_email");
       const ghHostsPath = join(process.env.GH_CONFIG_DIR || join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "gh"), "hosts.yml");
       const activeGh = () => {
         if (!existsSync(ghHostsPath)) return null;
@@ -699,11 +682,11 @@ process.stdin.on("end", () => {
       // $( and backticks are separators too (review catch): their payload is its own segment.
       const SEPS = [";", "&&", "||", "|", "$(", String.fromCharCode(96), "(", ")"];
       const bare = (w) => w.replaceAll(String.fromCharCode(39), "").replaceAll(String.fromCharCode(34), "");
-      const scan = (text, depth) => { if (depth > 3) return; for (const seg of SEPS.reduce((acc, s) => acc.flatMap((l) => l.split(s)), text.split(ESC_NL))) checkSeg(headOf(words(seg)), depth, words(seg)); };
-      const checkSeg = (ws, depth, raw) => {
+      const scan = (text, depth) => { if (depth > 3) return; for (const seg of SEPS.reduce((acc, s) => acc.flatMap((l) => l.split(s)), text.split(ESC_NL))) checkSeg(headOf(words(seg)), depth); };
+      const checkSeg = (ws, depth) => {
         if (ws.length === 0) return;
-        if (WRAPPERS.includes(ws[0])) { // wrapper args have arity (sudo -u bob): scan from the first gh/git/wrapper token (review catch)
-          const j = ws.findIndex((w, i) => i > 0 && ["gh", "git", ...WRAPPERS].includes(bare(w)));
+        if (WRAPPERS.includes(ws[0])) { // wrapper args have arity (sudo -u bob): scan from the first gh/wrapper token (review catch)
+          const j = ws.findIndex((w, i) => i > 0 && ["gh", ...WRAPPERS].includes(bare(w)));
           if (j > 0) scan(ws.slice(j).map(bare).join(" "), depth + 1);
           return;
         }
@@ -715,46 +698,9 @@ process.stdin.on("end", () => {
           if (!declaredGh) { problems.push("gh without a declared identity for this clone — run: kj identity set"); return; }
           const eff = switchedTo || activeGh();
           if (eff !== declaredGh) problems.push("gh as '" + (eff || "no session") + "' but this clone is declared as '" + declaredGh + "' — prefix the command: gh auth switch --user " + declaredGh + " && ...");
-          return;
-        }
-        if (ws[0] === "git") {
-          // Global options (-C, -c, --git-dir, --work-tree...) are NOT re-implemented: they
-          // are forwarded verbatim to git var, so git resolves identity exactly as the real
-          // command would (review catches: -C cumulative, --git-dir, --opt=value forms).
-          const TWO = ["-c", "-C", "--git-dir", "--work-tree", "--namespace", "--super-prefix", "--exec-path", "--config-env"];
-          let k = 1;
-          while (k < ws.length && ws[k].startsWith("-")) k += TWO.includes(ws[k]) && ws[k + 1] ? 2 : 1;
-          const globals = ws.slice(1, k).map(bare);
-          const sub = ws[k];
-          if (sub === "push") { // push authenticates with the gh session, not user.email (review catch)
-            if (!declaredGh) { problems.push("git push without a declared identity for this clone — run: kj identity set"); return; }
-            const eff = switchedTo || activeGh();
-            if (eff !== declaredGh) problems.push("git push with gh session '" + (eff || "no session") + "' but this clone is declared as '" + declaredGh + "' — prefix: gh auth switch --user " + declaredGh + " && ...");
-            return;
-          }
-          // IDN-B2: anything that authors or rewrites commits carries an identity (review catch).
-          if (!["commit", "tag", "merge", "rebase", "cherry-pick", "am", "revert"].includes(sub)) return; // am: the COMMITTER is still this user
-          if (!declaredEmail) { problems.push("git " + sub + " without a declared identity for this clone — run: kj identity set"); return; }
-          // Let GIT resolve author and committer under the command's own environment
-          // (review catch: user.email, -c, GIT_*_EMAIL, EMAIL, GIT_CONFIG_*, includeIf are
-          // its business): git var is the single source of truth.
-          const assigns = raw.slice(0, raw.length - ws.length).filter((w) => w.indexOf("=") > 0);
-          const env = Object.assign({}, process.env);
-          for (const w of assigns) env[w.slice(0, w.indexOf("="))] = bare(w.slice(w.indexOf("=") + 1));
-          const ident = (v) => {
-            const r = spawnSync("git", [...globals, "var", v], { cwd: ROOT, encoding: "utf8", env });
-            const s = r.status === 0 ? String(r.stdout) : "";
-            const a = s.indexOf("<");
-            const b = s.indexOf(">");
-            return a >= 0 && b > a ? s.slice(a + 1, b) : null;
-          };
-          const ai = ws.findIndex((w) => w.startsWith("--author"));
-          const authorRaw = ai < 0 ? null : ws[ai].includes("=") ? ws[ai].slice(ws[ai].indexOf("=") + 1) : ws.slice(ai + 1).join(" ");
-          const authorMail = authorRaw === null ? null : bare(authorRaw.includes("<") ? authorRaw.slice(authorRaw.indexOf("<") + 1, authorRaw.indexOf(">")) : authorRaw.trim());
-          const mails = [authorMail ?? ident("GIT_AUTHOR_IDENT"), ident("GIT_COMMITTER_IDENT")]; // --author overrides the author (review catch); the committer is always git's
-          const offender = mails.find((m) => m !== null && m !== declaredEmail) ?? (mails[0] === null ? "none" : null);
-          if (offender !== null) problems.push("git " + sub + " as '" + offender + "' but this clone is declared as '" + declaredEmail + "' — use: git -c user.email=" + declaredEmail + " " + sub + " ... (or git config user.email " + declaredEmail + ")");
         }
+        // KJC-TSK-1085 (ADR 0015): git commit/tag/rebase/push are no longer read here:
+        // pre-commit checks the author, pre-push every pushed commit and the gh session.
       };
       scan(CMD_TEXT, 0);
       if (problems.length > 0) {
@@ -1177,17 +1123,14 @@ process.stdin.on("end", () => {
         }
       }
       const MERGE = /\\bgh\\s+pr\\s+merge(\\s+(\\d+))?/;
-      const ADVANCE = /\\bgit\\s+commit\\b|\\bgit\\s+push\\b|\\bgh\\s+pr\\s+create\\b/; // push also falls under violations() — explicit here too (review catch)
+      // KJC-TSK-1089: git push is not read any more; pending moves still stop the turn (stop gate).
+      const ADVANCE = /\\bgit\\s+commit\\b|\\bgh\\s+pr\\s+create\\b/;
       const mergeM = cmd.match(MERGE);
       const pend = pendingMoves(load().sessions?.[sid]);
-      // KJC-BUG-0364: one board-gate decision per command; the push gate below
-      // reuses it, so a second slow gh cannot contradict the first answer.
-      let boardDecision = null;
       if (pend.length > 0 && (mergeM || ADVANCE.test(cmd))) {
         // KJC-BUG-0198: una card partida en varias PRs no puede quedar bloqueada
         // por su primera mitad (boardGate, en la lib).
-        boardDecision = boardGate(sid, pend);
-        const { blocking, carried, reason } = boardDecision;
+        const { blocking, carried, reason } = boardGate(sid, pend);
         for (const c of carried) console.error("karajan sentinel: board-sync arrastra " + c.card + " — " + c.why + ", se movera al cerrarla");
         // ADR 0015 (KJC-TSK-0925): no escape; an epic and a card split across PRs
         // are already decided above (KJC-BUG-0230, 0198).
@@ -1234,18 +1177,10 @@ process.stdin.on("end", () => {
           console.error("karajan sentinel: release check en ROJO — no se publica ni despliega hasta resolverlo:" + (items || "\\n- corre kj release check para el detalle") + "\\n(sin escape: se repara lo que el check nombra)" + doc("release"));
           process.exit(2);
         }
-      } else if (PUSH.test(cmd)) {
-        // KJC-BUG-0147: a pending move blocks the push like it blocks the commit.
-        // ADR 0015 (KJC-TSK-0925): with no escape.
-        // KJC-BUG-0262: a carried card does not block the push the commit let through.
-        const sess = load().sessions?.[sid];
-        const decision = boardDecision || boardGate(sid, pendingMoves(sess));
-        const v = violations(sess, branchOf(), decision.blocking);
-        if (v.length) {
-          console.error("karajan sentinel: git push con el metodo en rojo:\\n" + v.map((x) => "- " + x).join("\\n") + (decision.reason ? "\\n(" + decision.reason + ")" : "") + "\\nResuelve antes de empujar. Estado: kj sentinel status" + doc("push-gate"));
-          process.exit(2);
-        }
       }
+      // KJC-TSK-1089 (ADR 0015): git push is no longer read here. The base branch is
+      // protected (required checks), the card and the tests are judged at commit
+      // (kj review), and pending card moves keep the turn from ending (stop gate).
     }
   } catch { /* fail open */ }
   process.exit(0);

package/src/rag/indexer.js

@@ -173,7 +173,7 @@ export async function indexProject(projectDir, { db, embedder, karajanHome, logg
       if (source.startsWith(prefix) && outOf(source) !== null) deleteChunksBySource(db, source);
     }
     for (const s of sources) {
-      const r = await indexFile(s, { db, embedder, logger, project: slug, kind: sourceKind(s) });
+      const r = await indexFile(s, { db, embedder, logger, project: slug, kind: sourceKind() });
       totals.indexed += r.indexed; totals.failed += r.failed; totals.files += 1;
     }
   }
@@ -211,7 +211,7 @@ export async function indexProjectDelta(projectDir, { db, embedder, since, logge
       logger.info?.(`[rag-indexer] delta delete ${relative(process.cwd(), abs)}`);
     } else if (indexableReason(relative(projectDir, abs), abs, { exclude, projectDir }) === null) {
       // KJC-TSK-0891: the same criterion as the full walk, not a list of extensions.
-      const r = await indexFile(abs, { db, embedder, logger, project: slug, kind: sourceKind(abs) });
+      const r = await indexFile(abs, { db, embedder, logger, project: slug, kind: sourceKind() });
       totals.indexed += r.indexed; totals.failed += r.failed; totals.files += 1;
     }
   }

package/src/review/one-shot-review.js

@@ -55,12 +55,17 @@ export async function runOneShotReview({
   createAgentFn = createAgent,
   detectAgents = detectAvailableAgents,
   candidateStatusFn = candidateStatus,
+  // KJC-TSK-1075: a third-party PR is not the host's own work, so the reviewer
+  // it names runs even if it is the host; and nothing is stored, so the
+  // review can never unlock a commit of one's own.
+  reviewerOverride = null,
+  persist = true,
 }) {
   if (!diff || !diff.trim()) {
     throw new Error("nothing to review — the diff is empty (stage your changes or pass --range)");
   }
 
-  const reviewer = await pickCrossReviewer({ config, hostAgent, detectAgents });
+  const reviewer = reviewerOverride || await pickCrossReviewer({ config, hostAgent, detectAgents });
   if (!reviewer) {
     throw new Error(
       `cross-AI review requires an agent other than the host (${hostAgent || "unknown"}) — install codex, claude or another supported CLI`
@@ -123,7 +128,7 @@ export async function runOneShotReview({
     throw new Error(await reportUnparseableVerdict({ projectDir, reviewer: activeReviewer, output: result.output, hash: diffHash(diff) }));
   }
 
-  return saveVerdict(projectDir, diff, {
+  const record = {
     verdict: parsed.approved ? "approved" : "rejected",
     reviewer: activeReviewer,
     host: hostAgent || null,
@@ -140,5 +145,6 @@ export async function runOneShotReview({
     // the verdict, bound to this diff, like the other two proofs.
     ...(ui ? { ui } : {}),
     confidence: parsed.confidence ?? null,
-  });
+  };
+  return persist ? saveVerdict(projectDir, diff, record) : record;
 }

package/src/review/pr-requirements.js

@@ -0,0 +1,87 @@
+/**
+ * KJC-TSK-1076: the requirements of a third-party PR, checked with no tokens.
+ * Each check is {id, ok, detail}; none stops the review (the agent decides).
+ * The rules are the own-work ones: the same budget, Conventional Commits and
+ * attribution patterns, and tests-with-code.
+ */
+import { AI_ATTRIBUTION, CONVENTIONAL_TYPES } from "../harden/hook-templates.js";
+import { loadPolicy } from "../policy/engine.js";
+import { runCommand } from "../utils/process.js";
+import { budgetedAdded } from "./loc-budget.js";
+import { checkTestsWithCode } from "./tests-with-code.js";
+
+const HEADER_MAX = 100;
+const CONVENTIONAL = new RegExp(String.raw`^(${CONVENTIONAL_TYPES})(\([^)]+\))?!?: \S`);
+const ATTRIBUTION = new RegExp(AI_ATTRIBUTION, "i");
+
+const rowsOf = (numstat) => numstat.split("\n").map((l) => l.trim()).filter(Boolean).map((l) => {
+  const [a, r, ...f] = l.split(/\s+/);
+  return { file: f.join(" "), added: a === "-" ? 1 : Number(a) || 0, removed: r === "-" ? 0 : Number(r) || 0 };
+});
+
+/**
+ * The PR size budget, one source for every gate (PL-C, KJC-TSK-0735): the
+ * policy's net_lines_added invariant, else method_gates.pr_size_max, 200.
+ */
+export function prSizeLimit({ projectDir, config }) {
+  const pol = loadPolicy({ projectDir });
+  const inv = pol.errors.length === 0
+    ? (pol.policy.invariants || []).find((i) => i.kind === "diff-threshold" && i.metric === "net_lines_added")
+    : null;
+  return {
+    ideal: config?.method_gates?.pr_size_warn ?? 150,
+    limit: inv?.max ?? config?.method_gates?.pr_size_max ?? 200,
+    source: inv ? `policy [${inv.id}]` : "method_gates",
+  };
+}
+
+/** Lines added that count against the budget (generated output and human docs exempt). */
+export function sizeCheck({ numstat, limit }) {
+  const { added, exempt } = budgetedAdded(numstat);
+  const exemptNote = exempt > 0 ? ` (${exempt} exempt)` : "";
+  return added > limit
+    ? { id: "size", ok: false, detail: `${added} lines added${exemptNote}, over the ${limit}-line limit: partition the PR` }
+    : { id: "size", ok: true, detail: `${added} lines added${exemptNote}, within the ${limit}-line limit` };
+}
+
+/** Conventional Commits headers (at most 100 characters) and no AI attribution in base..head. */
+export function commitChecks(commits) {
+  const badHeader = commits.filter((c) => !CONVENTIONAL.test(c.subject) || c.subject.length > HEADER_MAX);
+  const attributed = commits.filter((c) => ATTRIBUTION.test(`${c.subject}\n${c.body}`));
+  const list = (cs) => cs.map((c) => `${c.sha.slice(0, 8)} "${c.subject}"`).join(", ");
+  return [
+    badHeader.length
+      ? { id: "conventional-commits", ok: false, detail: `not Conventional Commits or over ${HEADER_MAX} characters: ${list(badHeader)}` }
+      : { id: "conventional-commits", ok: true, detail: `${commits.length} commit(s) with Conventional Commits headers` },
+    attributed.length
+      ? { id: "ai-attribution", ok: false, detail: `AI attribution in: ${list(attributed)}` }
+      : { id: "ai-attribution", ok: true, detail: "no AI attribution in the commits" },
+  ];
+}
+
+/** Source changed with no test changed (a delete-only change needs none). */
+export function testsCheck({ config, numstat }) {
+  const rows = rowsOf(numstat);
+  const res = checkTestsWithCode({ config, stagedFiles: rows.map((r) => r.file), numstat: rows });
+  const ok = res.ok && res.mode !== "warn";
+  return { id: "tests", ok, detail: ok ? `tests: ${res.mode}` : res.reason || "source changed with no test changed" };
+}
+
+const git = async (projectDir, args) => {
+  const res = await runCommand("git", args, { cwd: projectDir });
+  if (res.exitCode !== 0) throw new Error(`git ${args.join(" ")} failed: ${(res.stderr || "").trim()}`);
+  return res.stdout;
+};
+
+/** Size, commits and tests of base...head, read from git. */
+export async function prRequirementChecks({ range, projectDir, config, run = git }) {
+  const numstat = await run(projectDir, ["diff", "--numstat", range]);
+  // The commits of a PR are base..head, whichever range notation was given.
+  const [base, head] = range.split(/\.{2,3}/);
+  const log = await run(projectDir, ["log", "--format=%H%x1f%s%x1f%b%x1e", `${base}..${head || "HEAD"}`]);
+  const commits = log.split("\x1e").map((r) => r.trim()).filter(Boolean).map((r) => {
+    const [sha, subject = "", body = ""] = r.split("\x1f");
+    return { sha, subject, body };
+  });
+  return [sizeCheck({ numstat, limit: prSizeLimit({ projectDir, config }).limit }), ...commitChecks(commits), testsCheck({ config, numstat })];
+}

package/src/review/pr-security.js

@@ -0,0 +1,70 @@
+/**
+ * KJC-TSK-1077: the security and privacy requirements of a third-party PR,
+ * with no tokens. Each check is {id, ok, detail} and never stops the review.
+ * They reuse the scanners kj applies to its own work: the output guard's
+ * credential patterns, the privacy scan, the prompt-injection catalog, the
+ * supply-chain cooldown and semgrep, limited to the PR's files.
+ */
+import { CREDENTIAL_PATTERNS, scanDiff as scanGuards } from "../guards/output-guard.js";
+import { scanDiff as scanInjection } from "../utils/injection-guard.js";
+import { loadPrivacyList, scanText } from "../privacy/scan.js";
+import { isGeneratedPath, splitAddedByFile } from "../privacy/diff-scope.js";
+import { collectSemgrepFindings } from "../audit/semgrep-findings.js";
+import { cooldownAdvisories } from "./dep-cooldown.js";
+
+const CREDENTIAL_IDS = new Set(CREDENTIAL_PATTERNS.map((p) => p.id));
+const BLOCKING_SEMGREP = new Set(["ERROR", "WARNING"]);
+const check = (id, problems, okDetail) => (problems.length
+  ? { id, ok: false, detail: problems.join("; ") }
+  : { id, ok: true, detail: okDetail });
+
+/** Credentials in added lines (AWS, private keys, tokens, URLs with passwords...). */
+export function secretsCheck(diff, config) {
+  const found = scanGuards(diff, config).violations.filter((v) => CREDENTIAL_IDS.has(v.id));
+  return check("secrets", found.map((v) => `${v.file}:${v.line} ${v.id}`), "no secrets in the added lines");
+}
+
+/** Personal data in added lines, masked; generated output only for denylist hits. */
+export function privacyCheck(diff, { list = loadPrivacyList() } = {}) {
+  const found = splitAddedByFile(diff).flatMap(({ file, added }) => {
+    const hits = scanText(added, { list, source: file });
+    return isGeneratedPath(file) ? hits.filter((f) => f.severity === "block") : hits;
+  });
+  return check("privacy", found.map((f) => `${f.source}:${f.line} ${f.type} ${f.masked}`), "no personal data in the added lines");
+}
+
+/** Prompt-injection patterns in the added lines (text an AI will read). */
+export function injectionCheck(diff) {
+  const res = scanInjection(diff);
+  return check("prompt-injection", res.clean ? [] : [res.summary], "no prompt-injection patterns");
+}
+
+/** Dependencies the lockfile adds that were published under the threshold. */
+export async function cooldownCheck(diff, { advisories = cooldownAdvisories, thresholdHours } = {}) {
+  const { young = [], unverified = [], skipped = 0 } = await advisories(diff, thresholdHours ? { thresholdHours } : {});
+  const problems = young.map((p) => `${p.name}@${p.version} published ${p.hours} h ago`);
+  const notes = [...unverified.map((p) => `${p.name}@${p.version} unverified`), ...(skipped ? [`${skipped} packages changed, none checked`] : [])];
+  const res = check("dependency-cooldown", problems, "no dependency published in the last hours");
+  return notes.length ? { ...res, detail: `${res.detail} (${notes.join("; ")})` } : res;
+}
+
+/** semgrep (the static part of kj audit --security), counted on the PR's files only. */
+export async function semgrepCheck({ projectDir, files, collect = collectSemgrepFindings }) {
+  const res = await collect(projectDir);
+  if (!res.available) return { id: "semgrep", ok: true, detail: `not available: ${res.reason}` };
+  const inPr = new Set(files);
+  const found = (res.findings ?? []).filter((f) => inPr.has(f.file) && BLOCKING_SEMGREP.has(f.severity));
+  return check("semgrep", found.map((f) => `${f.file}:${f.line} ${f.rule}`), "no semgrep findings in the PR's files");
+}
+
+/** Every security and privacy check of the PR's diff. */
+export async function prSecurityChecks({ diff, projectDir, config }) {
+  const files = splitAddedByFile(diff).map((f) => f.file);
+  return [
+    secretsCheck(diff, config),
+    privacyCheck(diff),
+    injectionCheck(diff),
+    await cooldownCheck(diff, { thresholdHours: config?.supply_chain?.cooldown_hours }),
+    await semgrepCheck({ projectDir, files }),
+  ];
+}

package/src/review/pr-sonar.js

@@ -0,0 +1,22 @@
+/**
+ * KJC-TSK-1078: Sonar on a third-party PR, when SonarQube is reachable. The
+ * own-work pre-gate scans the PR's files and only issues on the lines the PR
+ * adds can fail the check; without Sonar the check says "not available" and
+ * passes (decision of the user: Sonar if available, never demanded).
+ */
+import { addedLinesByFile, issueFile, runSonarPregate } from "./sonar-pregate.js";
+
+export async function sonarCheck({ diff, config, projectDir = process.cwd(), pregate = runSonarPregate }) {
+  const touchedLines = addedLinesByFile(diff);
+  let res;
+  try {
+    res = await pregate({ config, stagedFiles: [...touchedLines.keys()], touchedLines, projectDir });
+  } catch (err) {
+    res = { available: false, reason: err.message };
+  }
+  if (!res.available) return { id: "sonar", ok: true, detail: `not available: ${res.reason}` };
+  const blocking = res.blocking ?? [];
+  return blocking.length
+    ? { id: "sonar", ok: false, detail: blocking.map((i) => `${issueFile(i)}:${i.line} ${i.rule} ${i.severity}`).join("; ") }
+    : { id: "sonar", ok: true, detail: `no blocking Sonar issue on the added lines (${(res.advisory ?? []).length} advisory)` };
+}

package/src/review/sonar-pregate.js

@@ -82,7 +82,8 @@ export function groupByScanRoot(files, { root = process.cwd(), exists = existsSy
   return groups;
 }
 
-export async function runSonarPregate({ config, stagedFiles = [], touchedLines = null, logger = null, exists = existsSync }) {
+// KJC-TSK-1078: projectDir is where the files live (a third-party PR's clone may not be the cwd).
+export async function runSonarPregate({ config, stagedFiles = [], touchedLines = null, logger = null, exists = existsSync, projectDir = process.cwd() }) {
   if (config?.review_gate?.sonar === false) {
     return { available: false, reason: "disabled in config (review_gate.sonar: false)" };
   }
@@ -94,7 +95,9 @@ export async function runSonarPregate({ config, stagedFiles = [], touchedLines =
   let lock = null;
   try {
     lock = await acquireToolLock("sonar-scanner", { timeoutMs: 300_000, slots });
-    const groups = groupByScanRoot(stagedFiles, { exists });
+    const groups = groupByScanRoot(stagedFiles, { root: projectDir, exists });
+    // The root keeps the scanner's own default (cwd) unless the project lives elsewhere.
+    const rootCwd = projectDir === process.cwd() ? null : projectDir;
     if (groups.size === 0) groups.set("", []);
     const indexed = new Set();
     const issues = [];
@@ -103,7 +106,8 @@ export async function runSonarPregate({ config, stagedFiles = [], touchedLines =
     for (const dir of groups.keys()) {
       const prefix = dir ? `${dir}/` : "";
       // KJC-TSK-0838: verbose, so the scanner names every file it indexed.
-      const scan = await runSonarScan(config, null, { verbose: true, ...(dir ? { cwd: join(process.cwd(), dir) } : {}) });
+      const scanCwd = dir ? join(projectDir, dir) : rootCwd;
+      const scan = await runSonarScan(config, null, { verbose: true, ...(scanCwd ? { cwd: scanCwd } : {}) });
       if (scan.note) logger?.warn?.(scan.note); // KJC-BUG-0156: precedence is said, never silent
       if (!scan.ok) {
         return { available: false, reason: (scan.stderr || scan.stdout || "sonar scan failed").trim() };

package/src/review/tests-with-code.js

@@ -8,7 +8,9 @@
  * No escape (ADR 0015): deletions and comment-only cleanups already pass.
  */
 
-const DEFAULT_TEST_PATTERNS = ["/tests/", "/__tests__/", ".test.", ".spec."];
+import { isGenerated } from "./loc-budget.js";
+
+const DEFAULT_TEST_PATTERNS =["/tests/", "/__tests__/", ".test.", ".spec."];
 const DEFAULT_SOURCE_EXTS = [".js", ".jsx", ".ts", ".tsx", ".py", ".go", ".java", ".rb", ".php", ".cs"];
 
 /**
@@ -22,8 +24,9 @@ export function sourceFilesOf(config = {}, files = []) {
   // Staged paths are repo-relative (no leading slash) — normalize so the
   // "/tests/" style patterns also match the top-level tests directory.
   const isTest = (f) => patterns.some((p) => `/${f}`.includes(p));
+  // KJC-BUG-0377: build output (a rebuilt docs site's _astro/*.js) is nobody's code.
   return {
-    sources: files.filter((f) => !isTest(f) && exts.some((e) => f.endsWith(e))),
+    sources: files.filter((f) => !isTest(f) && !isGenerated(f) && exts.some((e) => f.endsWith(e))),
     hasTests: files.some(isTest),
   };
 }