karajan-code 4.30.0 → 4.31.0

package/package.json

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

package/src/cli/register-pipeline.js

@@ -34,6 +34,7 @@ export function registerPipeline(program, { pkgVersion }) {
     .option("--no-squeezr", "Skip the Squeezr auto-install (context compression). Karajan still runs but burns more tokens")
     .option("--no-qmd", "Skip the QMD auto-install + collection registration (semantic wiki over docs/, .reviews/ and plans/)")
     .option("--no-harden", "Skip the quality harness (git hooks, lint/commit config, CI gates, agent guidelines)")
+    .option("--no-sonar", "Do not start the SonarQube container (Docker). The review gate still needs it: start it later with 'kj sonar start'")
     .option("--json", "Emit a machine-readable summary of what init did (AB-B: for host agents)")
     .action(async (flags) => {
       await withConfig(pkgVersion, "init", flags, async ({ config: _config, logger }) => {

package/src/commands/env.js

@@ -115,6 +115,18 @@ export async function envInstallCommand({ config = null, logger = null, flags =
     try {
       const h = await hardenCommand({ projectDir, logger: console });
       if (h?.ok === false) throw new Error(h.error || "kj harden failed");
+      // KJC-BUG-0188: a headless harden never binds an identity by itself, and
+      // it must not. Blocking here beats the Sentinel denying every git and gh
+      // call later, with nothing on screen tying that back to this install.
+      if (h?.identityPending) {
+        result.exitCode = PENDING_EXIT_CODE;
+        result.pendingBlock = renderPendingBlock(
+          [{ tool: "identity", action: "needs-user", reason: h.identityPending, command: h.identityCommand }],
+          { retry: "kj env install", why: "this clone has no declared identity, and kj never binds one on its own" },
+        );
+        console.log(result.pendingBlock);
+        return result;
+      }
       await reviewGateCommand({ config, flags: { installGate: true } });
       console.log("✓ enforcement active: git hooks + cross-AI verdict gate — a commit outside the method is rejected, not narrated");
     } catch (err) {

package/src/commands/go.js

@@ -13,6 +13,7 @@ import { spawn } from "node:child_process";
 import { checkBinary } from "../utils/agent-detect.js";
 import { createCliAskQuestion } from "../utils/cli-ask-question.js";
 import { envInstallCommand } from "./env.js";
+import { ensureGitRepo } from "./init.js";
 import { boardCommand } from "./board.js";
 // The interactive launchers a muggle can live inside (v1: the two the epic
 // names). Auth heuristics are the same cheap file checks reviewer-fallback
@@ -44,7 +45,7 @@ export function buildGoPrompt() {
   ].join("\n");
 }
 async function defaultPrepare({ config, logger }) {
-  await envInstallCommand({ config, logger, flags: { yes: true } });
+  return envInstallCommand({ config, logger, flags: { yes: true } });
 }
 export async function defaultBoard({ config, logger, runBoard = boardCommand, openPath = "/?maggle=1" }) {
   const port = config.hu_board?.port || 4000;
@@ -95,7 +96,21 @@ export async function goCommand({ config = {}, logger = console, flags = {}, dep
   // Prepare ONCE: decisions already taken are never re-asked.
   if (!existsSync(path.join(projectDir, ".karajan", "review-gate"))) {
     logger.info?.("Preparando tu proyecto (solo la primera vez)…");
-    await (deps.prepare ?? defaultPrepare)({ config, logger });
+    // KJC-BUG-0191: empezar en una carpeta vacía es lo natural, y kj env
+    // install se niega a correr sin repositorio. Lo creamos nosotros.
+    if (!ensureGitRepo({ projectDir, logger })) {
+      logger.error?.("No he podido preparar el control de versiones de tu proyecto (git). Instálalo y vuelve a escribir: kj go");
+      process.exitCode = 1;
+      return 1;
+    }
+    const prepared = await (deps.prepare ?? defaultPrepare)({ config, logger });
+    // Algo depende de tus manos (arriba tienes el detalle). Sin eso el
+    // proyecto quedaría a medias, así que paramos aquí en vez de seguir.
+    if (prepared?.exitCode) {
+      logger.error?.("Falta una cosa que solo puedes hacer tú, la tienes justo arriba. Cuando la hagas, vuelve a escribir: kj go");
+      process.exitCode = 1;
+      return 1;
+    }
   }
   const prompt = (deps.prompt ?? buildGoPrompt)();
   // --window (MGL-E, ADR 0008): la conversación vive DENTRO del board — el

package/src/commands/harden.js

@@ -200,7 +200,10 @@ export async function hardenCommand({
   if (!dryRun) {
     const id = await ensureIdentity({ projectDir, logger });
     out.identity = id.declared ? id.identity : null;
-    if (id.pending) out.identityPending = id.pending;
+    if (id.pending) {
+      out.identityPending = id.pending;
+      out.identityCommand = id.command;
+    }
   }
   // KJC-BUG-0161 / ADR 0009 (opción A): --commit versiona la regeneración
   // del supervisor con procedencia sellada. Acto humano — el guard vive en

package/src/commands/hu.js

@@ -121,6 +121,13 @@ export async function huCommand({ config = null, action, args = [], flags = {} }
       console.warn(`⚠ possible duplicate${plural} — check before working it:\n${candidates}`);
     }
     const plan = await backlogPlan(projectDir);
+    /** Lowest free HU-#### in this plan — ids are permanent, never reused. */
+    const nextHuRef = (p) => {
+      const taken = new Set((p.hus || []).map((h) => h.short_id).filter(Boolean));
+      let n = 1;
+      while (taken.has(`HU-${String(n).padStart(4, "0")}`)) n += 1;
+      return `HU-${String(n).padStart(4, "0")}`;
+    };
     // KJC-TSK-0669 (absolute rule): cards are permanent. The delete-and-
     // recreate "fix" an agent improvises loses history and duplicates ids —
     // refuse it with the norm spelled out.
@@ -145,7 +152,12 @@ export async function huCommand({ config = null, action, args = [], flags = {} }
       .flatMap((s) => String(s).split("\n")).map((s) => s.trim()).filter(Boolean);
     const hu = addHu(plan, {
       title,
-      short_id: flags.id || null,
+      // KJC-BUG-0189: the card-first gate demands a branch that references a
+      // card, and it is this command the gate sends the agent to. The
+      // canonical plan id (hu_plan-<stamp>-<rand>_001) does not match
+      // CARD_REF_RE, so without an explicit --id the card kj just created
+      // could not satisfy kj's own gate. Sequential HU-#### does.
+      short_id: flags.id || nextHuRef(plan),
       acceptance_criteria: [...splitLines(flags.ac), ...splitLines(flags.criteria)],
       acceptance_tests: splitLines(flags.tests),
       scope: flags.scope || null,

package/src/commands/init.js

@@ -1,3 +1,4 @@
+import { execFileSync } from "node:child_process";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -743,6 +744,25 @@ export async function resolveConfigScope({ flags, interactive }) {
   return { configPath: getConfigPath(), scope: "global" };
 }
 
+/**
+ * KJC-BUG-0187: the enforcement gates live in git hooks, so a project without
+ * a repo gets no harness at all. Init creates it, exactly like `kj run` does
+ * (src/orchestrator/config-init.js), and reports failure instead of carrying
+ * on half-installed. No seed commit: that is the bootstrap commit's job.
+ */
+export function ensureGitRepo({ projectDir, logger, gitFn = null }) {
+  if (isGitRepo(projectDir)) return true;
+  const run = gitFn || ((args) => execFileSync("git", args, { cwd: projectDir, stdio: "pipe" }));
+  try {
+    run(["init"]);
+    logger?.info?.("Initialized git repository (no seed commit) — the quality harness needs it");
+    return true;
+  } catch (err) {
+    logger?.warn?.(`git init failed: ${err.message}`);
+    return false;
+  }
+}
+
 export async function initCommand({ logger, flags = {} }) {
   // AB-B (KJC-TSK-0656): with --json, stdout is a machine contract — every
   // human log moves to stderr so the only stdout line is the summary object.
@@ -888,20 +908,29 @@ export async function initCommand({ logger, flags = {} }) {
     }
   }
 
-  await setupSonarQube(config, logger, { interactive });
+  // KJC-BUG-0184: the container is a heavy side effect — opt-out: --no-sonar.
+  // Only the bootstrap is skipped; the review gate still demands Sonar.
+  const skipSonar = flags?.noSonar === true || flags?.sonar === false;
+  if (skipSonar) {
+    logger.info("SonarQube container not started (--no-sonar). Start it later with 'kj sonar start'.");
+  } else {
+    await setupSonarQube(config, logger, { interactive });
+  }
   await scaffoldCiGateway(config, flags, logger);
 
   // Install the quality harness (git hooks, lint/format/commit config, CI
   // quality gates, agent guidelines) through the SAME engine as `kj harden`,
   // so init and harden never drift. Opt-out: --no-harden. Needs a git repo.
   const skipHarden = flags?.noHarden === true || flags?.harden === false;
+  let hardened = false;
   if (skipHarden) {
     logger.info("Quality harness skipped (--no-harden).");
-  } else if (isGitRepo(process.cwd())) {
+  } else if (ensureGitRepo({ projectDir: process.cwd(), logger })) {
     logger.info("Installing quality harness (kj harden)...");
     await hardenCommand({ projectDir: process.cwd(), logger });
+    hardened = true;
   } else {
-    logger.info("Not a git repository — run `kj harden` after `git init` to add the quality harness.");
+    logger.warn("Quality harness NOT installed: this is not a git repository and `git init` failed — Karajan's guarantees live in git hooks. Fix git, then run `kj harden`.");
   }
 
   // Persist any changes setupSonarQube made (token, etc.) back to disk.
@@ -925,7 +954,7 @@ export async function initCommand({ logger, flags = {} }) {
   if (flags.json) {
     console.log(JSON.stringify({
       ok: true, configPath, scope, interactive,
-      skipped: ["ollama", "rtk", "squeezr", "qmd", "harden"].filter((t) => flags[t] === false),
+      skipped: ["ollama", "rtk", "squeezr", "qmd", "sonar", "harden"].filter((t) => flags[t] === false),
     }));
     return;
   }
@@ -933,7 +962,11 @@ export async function initCommand({ logger, flags = {} }) {
   // Clear close so a first-time user knows setup finished and what to do next,
   // instead of being left at the end of a wall of detection logs (KJC-BUG-0088).
   logger.info("");
-  logger.info("✓ Karajan is set up in this project.");
+  // KJC-BUG-0187: never declare a setup that did not happen. Without the
+  // harness there are no gates, and saying otherwise is the worst outcome.
+  logger.info(hardened || skipHarden
+    ? "✓ Karajan is set up in this project."
+    : "⚠ Karajan is set up EXCEPT the quality harness — without it there are no gates.");
   logger.info('  Next:  kj run "describe what to build or fix"');
   logger.info("  More:  kj --help   ·   kj doctor (check your setup)");
 }

package/src/harden/harness-hooks.js

@@ -16,6 +16,8 @@ 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; });

package/src/harden/hook-templates.js

@@ -60,8 +60,9 @@ function chainToGlobal(hook, globalHooksDir) {
 function baseBranchGuard(baseBranch) {
   if (!baseBranch) return [];
   return [
-    "# Branch-first guard — the base branch only moves via PR.",
-    'if [ "$KJ_ALLOW_BASE_COMMIT" != "1" ]; then',
+    "# Branch-first guard — the base branch only moves via PR. KJC-BUG-0186:",
+    "# the bootstrap commit is exempt, there is no commit to branch from yet.",
+    'if [ "$KJ_ALLOW_BASE_COMMIT" != "1" ] && git rev-parse --verify HEAD >/dev/null 2>&1; then',
     '  current_branch=$(git symbolic-ref --short HEAD 2>/dev/null || echo "")',
     `  if [ "$current_branch" = "${baseBranch}" ]; then`,
     `    echo 'kj harden: direct commits on ${baseBranch} are not allowed — create a branch and open a PR (KJ_ALLOW_BASE_COMMIT=1 to override)'; exit 1`,

package/src/harden/sentinel-hooks.js

@@ -28,6 +28,7 @@ export function resolveSentinelRoot(dir = process.cwd()) {
 const LIB_BODY = `// kj sentinel shared lib (KJC-TSK-0714) — managed by \`kj harden\`.
 // Single source for every sentinel script: state, branch, classification,
 // violations, and escape recording.
+import console from "node:console";
 import { readFileSync, writeFileSync } from "node:fs";
 import { execSync, spawnSync } from "node:child_process";
 import { dirname, join } from "node:path";
@@ -71,9 +72,18 @@ export const foreignLane = (targetDir) => {
 // 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; }
+};
 export const violations = (s, branch) => {
   const v = pendingMoves(s).map(pendingText);
   if (!s || !(s.edited_sources || []).length) return v;
+  if (bootstrapPhase()) return v;
   if (BASE_BRANCHES.has(branch)) 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");
@@ -120,9 +130,10 @@ const POST_BODY = `#!/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 process from "node:process";
 import { relative } from "node:path";
 import { spawnSync } from "node:child_process";
-import { doc, CODE, TESTS, ROOT, CARD, branchOf, load, save, session } from "./sentinel-lib.mjs";
+import { CODE, TESTS, ROOT, CARD, branchOf, load, save, session } from "./sentinel-lib.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"];
 let raw = "";
 process.stdin.on("data", (d) => { raw += d; });
@@ -151,10 +162,15 @@ process.stdin.on("end", () => {
     // 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.
-    const recordRag = (query, sources) => {
+    // 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/;
+    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 = [];
       for (const src of sources) {
         const rel = relative(ROOT, String(src)).split(String.fromCharCode(92)).join("/");
@@ -176,7 +192,7 @@ process.stdin.on("end", () => {
     const parseJson = (t) => { try { return JSON.parse(t); } catch { return null; } };
     if (/__kj_rag_query$/.test(String(tool)) && /^mcp__/.test(String(tool))) {
       const parts = Array.isArray(response?.content) ? response.content : [];
-      recordRag(input.text, parts.flatMap((p) => sourcesOf(parseJson(String(p?.text || "")))));
+      recordRag(input.text, parts.flatMap((p) => sourcesOf(parseJson(String(p?.text || "")))), parts.map((p) => String(p?.text || "")).join(String.fromCharCode(10)));
       process.exit(0);
     }
     if (/__update_card$/.test(String(tool)) && /^mcp__/.test(String(tool))) {
@@ -213,7 +229,7 @@ process.stdin.on("end", () => {
           .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()))));
+        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
@@ -275,6 +291,8 @@ const STOP_BODY = `#!/usr/bin/env node
 // 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";
@@ -382,6 +400,8 @@ const PRETOOL_BODY = `#!/usr/bin/env node
 // before the damage, not in the post-mortem. Exit 2 blocks (stderr says the
 // remediation); read-only tools are never wired here; every honored escape
 // is recorded as an auditable event. Fails OPEN on anything unexpected.
+import console from "node:console";
+import process from "node:process";
 import { dirname, join, relative, resolve } from "node:path";
 import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { spawnSync } from "node:child_process";
@@ -705,7 +725,7 @@ process.stdin.on("end", () => {
         // LITERALES (tambien dentro de sustituciones) los escanea el bucle
         // de tokens de abajo; el residuo (expansion anidada en segmentos
         // runner) queda documentado como en la regla de ficheros PROTECTED.
-        if (/>{1,2}[ \\t]*["']?[\\$\`]/.test(cmd)) {
+        if (/>{1,2}[ \\t]*["']?[$\`]/.test(cmd)) {
           if (escOn("KJ_ALLOW_CROSS_LANE")) { recordEscape(sid, "KJ_ALLOW_CROSS_LANE", tool); }
           else {
             console.error("karajan sentinel: redireccion con destino tras variable/sustitucion — el guard de carriles no puede verificarlo (MONO-0); usa una ruta LITERAL (o KJ_ALLOW_CROSS_LANE=1, queda registrado)." + doc("cross-lane"));
@@ -780,7 +800,7 @@ process.stdin.on("end", () => {
         }
         const SAFE_EXP_SEG = /^([A-Za-z_][A-Za-z0-9_]*=[^ \\t]*[ \\t]*)*((npm|pnpm|yarn|vitest|jest|kj|gh|echo|printf|true|test)\\b|git[ \\t](?![^\\n]*(-C[ \\t]|--git-dir|--work-tree)))[^;|&\\n]*$|^[A-Za-z_][A-Za-z0-9_]*=[^;|&\\n]*$/;
         const segs = cmd.split(/&&|\\|\\||[;|\\n]/).map((s) => s.trim()).filter(Boolean);
-        if (!segs.every((s) => !/[\\$]/.test(s) || SAFE_EXP_SEG.test(s))) {
+        if (!segs.every((s) => !/[$]/.test(s) || SAFE_EXP_SEG.test(s))) {
           if (escOn("KJ_ALLOW_CROSS_LANE")) { recordEscape(sid, "KJ_ALLOW_CROSS_LANE", tool); }
           else {
             console.error("karajan sentinel: expansion de shell en una herramienta generica de fichero/interprete — el objetivo no es verificable por el guard de carriles (MONO-0); usa rutas LITERALES o un runner del toolchain (o KJ_ALLOW_CROSS_LANE=1, queda registrado)." + doc("cross-lane"));
@@ -890,7 +910,9 @@ process.stdin.on("end", () => {
         const fresh = !existsSync(String(file));
         // A path outside this tree is another lane's business (the lane guard
         // above rules on it) and the ledger only holds in-repo paths.
-        const covered = rel.startsWith("..") || hits.includes(rel) || hits.some((h) => dirOf(h) === dirOf(rel)) || (fresh && (rs.rag_queries || []).length > 0);
+        // KJC-BUG-0190: with nothing indexed, no query can cover anything —
+        // the gate asks for kj rag index instead of denying the impossible.
+        const covered = rel.startsWith("..") || hits.includes(rel) || hits.some((h) => dirOf(h) === dirOf(rel)) || (fresh && (rs.rag_queries || []).length > 0) || rs.rag_index_empty === true;
         if (!covered) {
           if (escOn("KJ_ALLOW_NO_RAG")) {
             // Recorded ONCE per session: the escape is a conscious exception, not a per-edit tax.

package/src/identity/bootstrap.js

@@ -28,7 +28,7 @@ export async function ensureIdentity({ projectDir, logger = null, deps = {} }) {
     const why = !gh || !email ? "no active gh session or git email" : "non-interactive run";
     const pending = `identity not declared for this clone (${why}) — run: ${hint}`;
     logger?.warn?.(`kj identity: ${pending}`);
-    return { declared: false, identity: null, pending };
+    return { declared: false, identity: null, pending, command: hint };
   }
 
   const wizard = (deps.makeWizard || createWizard)();
@@ -37,7 +37,7 @@ export async function ensureIdentity({ projectDir, logger = null, deps = {} }) {
     if (!ok) {
       const pending = `identity not declared (declined) — run: ${hint}`;
       logger?.warn?.(`kj identity: ${pending}`);
-      return { declared: false, identity: null, pending };
+      return { declared: false, identity: null, pending, command: hint };
     }
   } finally {
     wizard.close();

package/src/review/rag-requirement.js

@@ -43,9 +43,14 @@ export function checkRagRequirement({ config = {}, stagedFiles = [], newFiles =
   const ignored = Object.keys(env || {}).filter((k) => k.startsWith("KJ_ALLOW_") && env[k] === "1");
   const overrideNote = ignored.length > 0 ? ` (${ignored.join(", ")} is not honoured here)` : "";
   const head = `The RAG must have answered about code before it is reviewed (${sources.length} staged source${sources.length === 1 ? "" : "s"})${overrideNote}`;
-  // No Sentinel in this tree = no host session that could keep a ledger: the
-  // requirement does not apply here, and the verdict says so (mode).
-  if (ledger?.harness === false) return { ok: true, mode: "no-harness", sources };
+  // KJC-BUG-0192: no Sentinel in this tree used to PASS, which made "do not
+  // harden" the comfortable way around the gate. Nobody recording the session
+  // is a reason to install the harness, or to ask for a grant, never a silent
+  // exemption: the proof of the method cannot depend on the project choosing
+  // to install whoever records it.
+  if (ledger?.harness === false) {
+    return { ok: false, mode: "block", sources, reason: `${head} — no Sentinel harness in this tree, so no session ledger can exist: install it with \`kj harden\`. ${GRANT_HINT}` };
+  }
   // A harness that does not match the installed kj (edited, emptied, or older
   // than the ledger) cannot vouch for anything: fail closed, like the tamper
   // check does, until the human regenerates it.
@@ -82,8 +87,12 @@ export function checkRagVerdict({ config = {}, stagedFiles = [], rag, harness =
   if (sources.length === 0) return { ok: true, mode: "docs-only" };
   const grant = liveGrant(standingExceptions, now);
   if (grant) return { ok: true, mode: "granted", grant, sources };
-  if (!harness) return { ok: true, mode: "no-harness", sources };
   const head = `The RAG must have answered about code before it is committed (${sources.length} staged source${sources.length === 1 ? "" : "s"})`;
+  // KJC-BUG-0192: same rule on the --check side, so the commit gate cannot be
+  // opened by removing the supervisor either.
+  if (!harness) {
+    return { ok: false, mode: "block", sources, reason: `${head} — no Sentinel harness in this tree, so no session ledger can exist: install it with \`kj harden\`. ${GRANT_HINT}` };
+  }
   if (!verified) {
     return { ok: false, mode: "block", sources, reason: `${head} — the Sentinel harness does not match the installed kj (${mismatched.join(", ") || "scripts missing"}): the human runs \`kj harden\` to regenerate it. ${GRANT_HINT}` };
   }

package/src/utils/pending-user-action.js

@@ -64,12 +64,15 @@ export function collectPending(results, { tty = Boolean(process.stdin.isTTY), ye
 }
 
 /** The PENDING USER ACTION block: exact commands for THIS OS, then wait. */
-export function renderPendingBlock(pending, { platform = process.platform, retry = "kj install-tools" } = {}) {
+export function renderPendingBlock(pending, { platform = process.platform, retry = "kj install-tools", why = null } = {}) {
   const lines = [
     "════ PENDING USER ACTION ════════════════════════════════════════",
-    "kj could not finish this install by itself (sudo or a platform",
-    "installer is required). Karajan needs a COMPLETE environment —",
-    "do not continue degraded.",
+    // `why` names the real cause when it is not an install (KJC-BUG-0188:
+    // an undeclared identity needs the human, not a package manager).
+    ...(why
+      ? [`kj could not finish by itself: ${why}.`]
+      : ["kj could not finish this install by itself (sudo or a platform", "installer is required)."]),
+    "Karajan needs a COMPLETE environment — do not continue degraded.",
     "",
     "Run in YOUR terminal:",
     "",