karajan-code 4.1.2 → 4.1.4

package/package.json

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

package/src/cli/advanced-commands.js

@@ -31,7 +31,7 @@ export const ADVANCED_GROUPS = [
   { title: "Análisis pre-run", commands: ["discover", "triage", "researcher", "architect", "onboard", "brief"] },
   { title: "Búsqueda / RAG", commands: ["rag", "qmd", "watch"] },
   { title: "Calidad / auditoría", commands: ["audit", "check", "mutate", "webperf", "sonar"] },
-  { title: "Sesión / board", commands: ["resume", "report", "board", "undo", "standby"] },
+  { title: "Sesión / board", commands: ["resume", "report", "board", "hu", "adr", "undo", "standby"] },
   { title: "Infra / setup", commands: ["install-tools", "ollama", "skills", "roles", "agents", "env"] },
   { title: "Mantenimiento", commands: ["clean", "sync", "telemetry", "report-issue"] },
 ];

package/src/cli/register-meta.js

@@ -22,6 +22,8 @@ import { telemetryPreviewCommand, telemetryStatusCommand } from "../commands/tel
 import { envInstallCommand, briefCommand } from "../commands/env.js";
 import { agentRunCommand } from "../commands/agent-run.js";
 import { reportIssueCommand } from "../commands/report-issue.js";
+import { huCommand } from "../commands/hu.js";
+import { addAdr, listAdrs } from "../environment/adr.js";
 import { formatAdvancedIndex } from "../commands/advanced.js";
 import { withConfig } from "./_shared.js";
 
@@ -133,7 +135,10 @@ export function registerMeta(program, { pkgVersion }) {
     .option("--no-rag", "Skip building the RAG index when the project has none (ENV-E1)")
     .action(async (flags) => {
       await withConfig(pkgVersion, "env-install", flags, async ({ config, logger }) => {
-        await envInstallCommand({ config, logger, flags });
+        const r = await envInstallCommand({ config, logger, flags });
+        // KJC-TSK-0659: exit 3 = pending user action (RAG cannot index) —
+        // a driving agent must stop and wait, never continue degraded.
+        if (Number.isInteger(r?.exitCode) && r.exitCode !== 0) process.exit(r.exitCode);
       });
     });
 
@@ -149,6 +154,55 @@ export function registerMeta(program, { pkgVersion }) {
       });
     });
 
+  // AB-H (KJC-TSK-0658): board writes + repo ADRs for the brain.
+  const hu = program.command("hu").description("Track work in the HU Board from any host agent (card first)");
+  hu.command("add <title>")
+    .option("--id <shortId>", "Human-readable short id")
+    .option("--criteria <text>", "Acceptance criteria")
+    .option("--json", "Machine-readable output")
+    .action(async (title, flags) => {
+      await withConfig(pkgVersion, "hu", flags, async ({ config }) => {
+        await huCommand({ config, action: "add", args: [title], flags });
+      });
+    });
+  hu.command("move <id> <status>")
+    .option("--json", "Machine-readable output")
+    .action(async (id, status, flags) => {
+      await withConfig(pkgVersion, "hu", flags, async ({ config }) => {
+        await huCommand({ config, action: "move", args: [id, status], flags });
+      });
+    });
+  hu.command("list")
+    .option("--json", "Machine-readable output")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "hu", flags, async ({ config }) => {
+        await huCommand({ config, action: "list", flags });
+      });
+    });
+
+  const adr = program.command("adr").description("Architecture decision records in .karajan/adrs/ (git-tracked)");
+  adr.command("add <title>")
+    .requiredOption("--decision <text>", "The decision itself")
+    .option("--context <text>", "Why this came up")
+    .option("--consequences <text>", "Trade-offs accepted")
+    .option("--json", "Machine-readable output")
+    .action(async (title, flags) => {
+      await withConfig(pkgVersion, "adr", flags, async ({ config }) => {
+        const res = await addAdr(config?.projectDir || process.cwd(), { title, ...flags });
+        console.log(flags.json ? JSON.stringify(res) : `✓ ADR ${res.number} created: ${res.file} — commit it`);
+      });
+    });
+  adr.command("list")
+    .option("--json", "Machine-readable output")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "adr", flags, async ({ config }) => {
+        const adrs = await listAdrs(config?.projectDir || process.cwd());
+        if (flags.json) { console.log(JSON.stringify(adrs)); return; }
+        for (const a of adrs) console.log(`${String(a.number).padStart(4, "0")}  ${a.status.padEnd(10)} ${a.title}`);
+        if (adrs.length === 0) console.log("no ADRs yet — create one with: kj adr add \"<title>\" --decision \"...\"");
+      });
+    });
+
   // AB-F (KJC-TSK-0655): self-healing — the brain files kj frictions upstream.
   program
     .command("report-issue")

package/src/commands/env.js

@@ -8,6 +8,7 @@ import { installPlaybook } from "../environment/playbook.js";
 import { renderBrief, listBriefs } from "../environment/briefs.js";
 import { openVecStore, projectSlug, getLastIndexedCommit } from "../rag/vec-store.js";
 import { ragIndexCommand } from "./rag.js";
+import { renderPendingBlock, PENDING_EXIT_CODE } from "../utils/pending-user-action.js";
 
 function hasRagIndex(config, projectDir) {
   const db = openVecStore({ dim: config?.rag?.embedder?.dim || 768 });
@@ -42,21 +43,38 @@ export async function envInstallCommand({ config = null, logger = null, flags =
   console.log(`✓ Karajan playbook installed in: ${result.files.join(", ")}`);
 
   // ENV-E1: RAG-first — the playbook orders "query the RAG before coding",
-  // so installing the environment guarantees the index exists. An indexing
-  // failure is reported but never blocks the playbook install.
+  // so installing the environment guarantees the index exists. KJC-TSK-0659
+  // stop-on-sudo: an index that cannot be built is a BLOCKING condition —
+  // "success" with 0 chunks would leave every future session running the
+  // method against an empty RAG (field-reproduced: 0/727 without Ollama).
+  // The playbook stays installed; the command exits 3 so the driving agent
+  // stops, shows the block, and waits for the user.
   if (flags.rag !== false) {
+    const provider = config?.rag?.embedder?.provider || "ollama";
+    const blockRag = (why) => {
+      result.ragError = why;
+      result.exitCode = PENDING_EXIT_CODE;
+      const item = provider === "ollama"
+        ? { tool: "ollama", action: "needs-user", reason: `the RAG cannot index: ${why}` }
+        : { tool: `${provider} embedder`, action: "needs-user", reason: `the RAG cannot index: ${why} — check rag.embedder in kj config`, manualUrl: "kj config" };
+      console.log(renderPendingBlock([item], { retry: "kj rag index --with-sources   (then re-run: kj env install)" }));
+    };
     try {
       if (hasRagIndex(config, projectDir)) {
         console.log("✓ RAG index present");
       } else {
         console.log("⏳ no RAG index for this project — building it (first time only)…");
-        await ragIndexCommand({ config, logger, flags: { withSources: true } });
+        const totals = await ragIndexCommand({ config, logger, flags: { withSources: true } });
+        if ((totals?.indexed ?? 0) === 0 && (totals?.files ?? 0) > 0) {
+          blockRag(`0 of ${totals.files} files indexed — is the embedder running?`);
+        }
       }
     } catch (err) {
-      result.ragError = err.message;
-      console.log(`⚠ RAG index could not be built (${err.message}) — run \`kj rag index --with-sources\` later`);
+      blockRag(err.message);
     }
   }
-  console.log("  The host agent now follows the method: RAG first, TDD, cross-AI review before commit.");
+  if (result.exitCode !== PENDING_EXIT_CODE) {
+    console.log("  The host agent now follows the method: RAG first, TDD, cross-AI review before commit.");
+  }
   return result;
 }

package/src/commands/hu.js

@@ -0,0 +1,92 @@
+/**
+ * `kj hu add|move|list` (AB-H, KJC-TSK-0658) — board writes for the brain.
+ * The v4 playbook orders "card first", but until now only the headless
+ * planner could create HUs. These commands operate on a per-project
+ * "brain-backlog" plan (created on first use) so any host agent can track
+ * work in the HU Board without the subprocess pipeline.
+ */
+import { addHu, updateHuStatus } from "../plan/plan-hu-ops.js";
+import { generatePlanId } from "../plan/plan-id.js";
+import { savePlan, listPlans, loadPlan } from "../plan/plan-store.js";
+
+export const HU_STATUSES = ["pending", "running", "done", "failed", "skipped"];
+const BACKLOG_NAME = "brain-backlog";
+
+async function backlogPlan(projectDir) {
+  const plans = await listPlans(projectDir);
+  const existing = plans.find((p) => p.alias === BACKLOG_NAME || p.name === BACKLOG_NAME);
+  if (existing) return loadPlan(projectDir, existing.planId);
+  const plan = {
+    version: 2, planId: generatePlanId(), name: BACKLOG_NAME,
+    task: "Host-agent tracked work (v4 environment)",
+    status: "ready", hus: [], createdAt: new Date().toISOString(),
+  };
+  const planId = await savePlan(projectDir, plan);
+  return loadPlan(projectDir, planId);
+}
+
+export async function huCommand({ config = null, action, args = [], flags = {} }) {
+  const projectDir = config?.projectDir || process.cwd();
+  const emit = (obj, human) => { console.log(flags.json ? JSON.stringify(obj) : human); return obj; };
+
+  if (action === "list") {
+    const plans = await listPlans(projectDir);
+    const rows = [];
+    for (const meta of plans) {
+      const plan = await loadPlan(projectDir, meta.planId);
+      for (const h of plan.hus || []) {
+        rows.push({ id: h.id, short_id: h.short_id, title: h.title, status: h.status, plan: plan.alias || plan.planId });
+      }
+    }
+    if (flags.json) { console.log(JSON.stringify(rows)); return rows; }
+    for (const r of rows) console.log(`${(r.short_id || r.id).padEnd(28)} ${r.status.padEnd(8)} ${r.title}`);
+    if (rows.length === 0) console.log("no HUs yet — create one with: kj hu add \"<story>\"");
+    return rows;
+  }
+
+  if (action === "add") {
+    const title = args[0];
+    if (!title || !title.trim()) throw new Error("kj hu add requires a title: kj hu add \"<story>\"");
+    const plan = await backlogPlan(projectDir);
+    const hu = addHu(plan, {
+      title,
+      short_id: flags.id || null,
+      acceptance_criteria: flags.criteria ? [flags.criteria] : [],
+    });
+    await savePlan(projectDir, plan);
+    return emit({ id: hu.id, short_id: hu.short_id, status: hu.status },
+      `✓ HU created: ${hu.short_id || hu.id} (pending) — it shows up in \`kj board\``);
+  }
+
+  if (action === "move") {
+    const [ref, status] = args;
+    if (!ref || !status) throw new Error("usage: kj hu move <id> <status>");
+    if (!HU_STATUSES.includes(status)) {
+      throw new Error(`invalid status "${status}" — valid: ${HU_STATUSES.join(", ")}`);
+    }
+    // Exact canonical id wins outright (it IS the disambiguator); only then
+    // fall back to short_id matches — which can repeat between plans, so
+    // silently moving the first hit could move the wrong card.
+    const byId = [];
+    const byShort = [];
+    for (const meta of await listPlans(projectDir)) {
+      const plan = await loadPlan(projectDir, meta.planId);
+      for (const hu of plan.hus || []) {
+        if (hu.id === ref) byId.push({ plan, hu });
+        else if (hu.short_id === ref) byShort.push({ plan, hu });
+      }
+    }
+    const matches = byId.length > 0 ? byId : byShort;
+    if (matches.length === 0) throw new Error(`HU "${ref}" not found — see kj hu list`);
+    if (matches.length > 1) {
+      const ids = matches.map((m) => m.hu.id).join(", ");
+      throw new Error(`"${ref}" is ambiguous (${matches.length} matches: ${ids}) — use the full id`);
+    }
+    const { plan, hu } = matches[0];
+    updateHuStatus(plan, hu.id, status);
+    await savePlan(projectDir, plan);
+    return emit({ id: hu.id, status }, `✓ ${hu.short_id || hu.id} → ${status}`);
+  }
+
+  throw new Error(`unknown action "${action}" — use: add | move | list`);
+}

package/src/commands/install-tools.js

@@ -23,6 +23,7 @@ import { detectProjectStack } from "../utils/stack-detect.js";
 import { resolveStandalone } from "../utils/binary-sources.js";
 import { downloadBinary, binDir, runInstallCommand } from "../utils/tool-installer.js";
 import { dockerInstallPlan } from "../utils/docker-install.js";
+import { collectPending, renderPendingBlock, PENDING_EXIT_CODE } from "../utils/pending-user-action.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -416,8 +417,16 @@ export async function installToolsCommand(opts = {}) {
     }
   }
 
+  // KJC-TSK-0659 stop-on-sudo: anything that still needs the user's hands
+  // becomes ONE block with the exact per-OS commands, and a distinctive exit
+  // code so a driving agent stops and waits instead of continuing degraded.
+  const pending = dryRun ? [] : collectPending(results, { yes });
+  if (pending.length > 0) {
+    logger.warn?.(renderPendingBlock(pending));
+    return { results, pending, exitCode: PENDING_EXIT_CODE };
+  }
   const failures = results.filter((r) => r.action === "failed").length;
-  return { results, exitCode: failures > 0 ? 1 : 0 };
+  return { results, pending, exitCode: failures > 0 ? 1 : 0 };
 }
 
 export const __test = { parseOnlyList, isInstalled, ALL_TOOLS };

package/src/environment/adr.js

@@ -0,0 +1,45 @@
+/**
+ * ADRs in the repo (AB-H, KJC-TSK-0658) — `kj adr add|list`. Architecture
+ * decisions live as numbered markdown under .karajan/adrs/, git-tracked so
+ * the whole team (and every brain) inherits them. The architect brief's
+ * "check the ADRs before deciding" now has a target on every backend.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const ADR_DIR = path.join(".karajan", "adrs");
+
+const slugify = (t) => t.toLowerCase().replaceAll(/[^a-z0-9]+/g, "-").replaceAll(/^-|-$/g, "").slice(0, 60);
+
+export async function listAdrs(projectDir) {
+  const dir = path.join(projectDir, ADR_DIR);
+  let files;
+  try { files = await fs.readdir(dir); } catch { return []; }
+  const adrs = [];
+  for (const f of files.filter((f) => /^\d{4}-.*\.md$/.test(f)).sort()) {
+    const text = await fs.readFile(path.join(dir, f), "utf8");
+    const title = text.match(/^# (.+)$/m)?.[1] || f;
+    const status = text.match(/^Status: (.+)$/m)?.[1] || "accepted";
+    adrs.push({ file: path.join(ADR_DIR, f), number: Number(f.slice(0, 4)), title, status });
+  }
+  return adrs;
+}
+
+export async function addAdr(projectDir, { title, decision, context = "", consequences = "" }) {
+  if (!title?.trim() || !decision?.trim()) {
+    throw new Error("kj adr add requires a title and --decision");
+  }
+  const existing = await listAdrs(projectDir);
+  const number = (existing.at(-1)?.number || 0) + 1;
+  const file = path.join(ADR_DIR, `${String(number).padStart(4, "0")}-${slugify(title)}.md`);
+  const body = [
+    `# ${title}`, "",
+    `Status: accepted`, `Date: ${new Date().toISOString().slice(0, 10)}`, "",
+    ...(context ? ["## Context", "", context, ""] : []),
+    "## Decision", "", decision, "",
+    ...(consequences ? ["## Consequences", "", consequences, ""] : []),
+  ].join("\n");
+  await fs.mkdir(path.join(projectDir, ADR_DIR), { recursive: true });
+  await fs.writeFile(path.join(projectDir, file), body);
+  return { number, file, title };
+}

package/src/environment/playbook.js

@@ -29,7 +29,7 @@ const TARGET_FILES = {
 // ENV-D1 (KJC-TSK-0642): the tracking invariant names the CHOSEN state
 // backend — a playbook that says "board or PG" makes the host guess.
 const BACKEND_TRACKING = {
-  "hu-board": "Every piece of work has a tracked story/bug in the HU Board (`kj board`) before it starts.",
+  "hu-board": "Every piece of work has a tracked story/bug in the HU Board (`kj hu add` / `kj board`) before it starts.",
   "planning-game": "Every piece of work has a tracked card in the Planning Game MCP before it starts (In Progress while you work it).",
 };
 
@@ -58,8 +58,9 @@ Invariants (the git gates enforce these — they are not suggestions):
   through an atomic PR (~150 net lines, Conventional Commits).
 
 Commands: \`kj rag query\` · \`kj brief <role>\` (triage, planner, researcher,
-architect, tester, security, audit) · \`kj review --staged\` · \`kj review --check\` ·
-\`kj solomon --position\` · \`kj agent run <agent>\` · \`kj report\` · \`kj check\`
+architect, tester, security, audit) · \`kj hu add|move|list\` · \`kj adr add|list\` ·
+\`kj review --staged\` · \`kj review --check\` · \`kj solomon --position\` ·
+\`kj agent run <agent>\` · \`kj report\` · \`kj check\`
 
 Hit a kj bug or friction? Diagnose it and file it upstream with
 \`kj report-issue\` (sanitized; ask your user before \`--publish\`).

package/src/harden/advisory.js

@@ -21,11 +21,38 @@ const BLOCK_VERSION = 1; // current version every markered config ships at
 // Other filenames/formats for the same artifact, so kj never reports a false
 // "missing". `pkgKey` is a package.json field that can hold inline config.
 const EQUIVALENTS = {
-  commitlint: { files: [".commitlintrc", ".commitlintrc.js", ".commitlintrc.json", ".commitlintrc.yaml"], pkgKey: "commitlint" },
-  eslint: { files: ["eslint.config.mjs", ".eslintrc.js", ".eslintrc.cjs", ".eslintrc.json", ".eslintrc.yaml"], pkgKey: "eslintConfig" },
-  prettier: { files: [".prettierrc", ".prettierrc.js", ".prettierrc.yaml", "prettier.config.js"], pkgKey: "prettier" },
+  commitlint: { files: [".commitlintrc", ".commitlintrc.js", ".commitlintrc.cjs", ".commitlintrc.mjs", ".commitlintrc.json", ".commitlintrc.yaml", ".commitlintrc.yml", "commitlint.config.mjs", "commitlint.config.cjs", "commitlint.config.ts"], pkgKey: "commitlint" },
+  eslint: { files: ["eslint.config.mjs", "eslint.config.cjs", "eslint.config.ts", "eslint.config.mts", "eslint.config.cts", ".eslintrc.js", ".eslintrc.cjs", ".eslintrc.json", ".eslintrc.yaml", ".eslintrc.yml"], pkgKey: "eslintConfig" },
+  prettier: { files: [".prettierrc", ".prettierrc.js", ".prettierrc.yaml", ".prettierrc.yml", ".prettierrc.json5", ".prettierrc.toml", "prettier.config.js", "prettier.config.mjs", "prettier.config.cjs", "prettier.config.ts"], pkgKey: "prettier" },
 };
 
+/**
+ * KJC-BUG-0119 — same-tool filename variant for `artifactId` in any of
+ * `searchDirs` (file or inline package.json config); null when none exists.
+ * Seeding kj's default filename NEXT TO a variant eclipses the user's real
+ * config (eslint resolves eslint.config.js before .mjs), so config-engine
+ * must consult this before treating an artifact as absent.
+ */
+export function findEquivalentIn(searchDirs, artifactId) {
+  const spec = EQUIVALENTS[artifactId];
+  if (!spec) return null;
+  for (const dir of searchDirs) {
+    for (const rel of spec.files) {
+      if (existsSync(join(dir, rel))) return rel;
+    }
+    if (spec.pkgKey && existsSync(join(dir, "package.json"))) {
+      try {
+        if (JSON.parse(readFileSync(join(dir, "package.json"), "utf8"))[spec.pkgKey] != null) {
+          return `package.json#${spec.pkgKey}`;
+        }
+      } catch {
+        /* unreadable package.json → not a match */
+      }
+    }
+  }
+  return null;
+}
+
 // Concrete gains kj's standard would add to a USER_OWNED config, detected by
 // substring probes (no AST parse): each probe absent from the user's content
 // becomes one improvement. Heuristic by design — conservative, never a false
@@ -70,19 +97,8 @@ function toArtifact(cfg) {
 
 /** Locate the user's file for an artifact under `searchDir`; null if absent. */
 function findArtifactFile(searchDir, artifact) {
-  for (const rel of [artifact.file, ...artifact.equivalents]) {
-    if (existsSync(join(searchDir, rel))) return rel;
-  }
-  if (artifact.pkgKey && existsSync(join(searchDir, "package.json"))) {
-    try {
-      if (JSON.parse(readFileSync(join(searchDir, "package.json"), "utf8"))[artifact.pkgKey] != null) {
-        return `package.json#${artifact.pkgKey}`;
-      }
-    } catch {
-      /* unreadable package.json → not a match */
-    }
-  }
-  return null;
+  if (existsSync(join(searchDir, artifact.file))) return artifact.file;
+  return findEquivalentIn([searchDir], artifact.id);
 }
 
 /** Read the artifact body, or the JSON of an inline package.json key. */

package/src/harden/config-engine.js

@@ -9,6 +9,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
 import { upsertManagedBlock } from "../utils/managed-markers.js";
+import { findEquivalentIn } from "./advisory.js";
 import { artifactIdForConfig, findAlternative } from "./alternatives.js";
 import { CONFIGS_BY_LANGUAGE, UNIVERSAL_CONFIGS } from "./config-templates.js";
 
@@ -37,6 +38,15 @@ function seedInto(targetDir, configs, dryRun, prefix, results, altDirs = [target
         results.push({ file, action: "covered", by: alt.foundAt });
         continue;
       }
+      // KJC-BUG-0119: a same-tool variant (eslint.config.mjs, .eslintrc.json,
+      // package.json#eslintConfig…) means the config already EXISTS — seeding
+      // kj's default filename next to it would silently ECLIPSE the user's
+      // real config (eslint resolves eslint.config.js before .mjs).
+      const variant = findEquivalentIn(altDirs, artifactIdForConfig(cfg));
+      if (variant) {
+        results.push({ file, action: "covered", by: variant });
+        continue;
+      }
     }
 
     if (cfg.json) {

package/src/utils/binary-sources.js

@@ -44,6 +44,12 @@ export function osvScannerSource(platform = process.platform, arch = process.arc
  */
 export function semgrepFallback(available = {}) {
   if (available.docker) return { via: "docker", command: "docker pull semgrep/semgrep" };
+  // KJC-BUG-0120 (issue #1256): on Debian/Ubuntu-like systems the system
+  // Python is externally managed (PEP 668) and often ships without pip at
+  // all — `python3 -m pip install --user` is guaranteed to fail there.
+  // pipx must come from the distro's own package manager.
+  if (available.apt) return { via: "apt", command: "sudo apt update && sudo apt install -y pipx && pipx install semgrep" };
+  if (available.dnf) return { via: "dnf", command: "sudo dnf install -y pipx && pipx install semgrep" };
   return { via: "pipx", command: "python3 -m pip install --user pipx && pipx install semgrep" };
 }
 

package/src/utils/display/header.js

@@ -4,7 +4,6 @@ import { fileURLToPath } from "node:url";
 import { printBanner } from "../banner.js";
 import { ANSI } from "./formatters.js";
 
-// TODO: i18n display messages
 const DISPLAY_PKG_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../package.json");
 const DISPLAY_VERSION = JSON.parse(readFileSync(DISPLAY_PKG_PATH, "utf8")).version;
 

package/src/utils/install-hints.js

@@ -80,8 +80,13 @@ export async function getInstallHint(tool, available = null) {
   for (const { manager, command } of candidates) {
     if (avail[manager]) return { command, manager, manualUrl: MANUAL_URLS[tool] };
   }
-  // Nothing matched — fall back to the first candidate's command as a
-  // suggestion, so the user at least sees a working recipe.
+  // Nothing matched — suggest a recipe that actually works on this system.
+  // KJC-BUG-0120 (issue #1256): distro-aware fallbacks first (PEP 668 makes
+  // the generic pip bootstrap fail on Debian/Ubuntu); these are display-only
+  // (manager: null), never auto-run — sudo stays in the user's hands.
+  for (const { when, command } of DISTRO_FALLBACKS[tool] || []) {
+    if (avail[when]) return { command, manager: null, manualUrl: MANUAL_URLS[tool] };
+  }
   const first = candidates[0];
   return {
     command: first ? first.command : null,
@@ -90,6 +95,13 @@ export async function getInstallHint(tool, available = null) {
   };
 }
 
+const DISTRO_FALLBACKS = {
+  semgrep: [
+    { when: "apt", command: "sudo apt update && sudo apt install -y pipx && pipx install semgrep" },
+    { when: "dnf", command: "sudo dnf install -y pipx && pipx install semgrep" },
+  ],
+};
+
 const INSTALL_CANDIDATES = {
   semgrep: [
     { manager: "pipx", command: "pipx install semgrep" },

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

@@ -0,0 +1,95 @@
+/**
+ * Stop-on-sudo policy (KJC-TSK-0659). When a tool cannot be installed
+ * automatically (sudo needed, no package-manager route, or the attempt
+ * failed), kj must NOT continue degraded — a RAG with 0 chunks because
+ * Docker was missing helps nobody. Instead: emit ONE block with the exact
+ * commands for this machine's OS and exit with a distinctive code so a
+ * driving agent stops, shows the block, and waits for the user.
+ */
+
+export const PENDING_EXIT_CODE = 3;
+
+const PENDING = new Set(["manual", "failed", "needs-user"]);
+
+// Exact per-OS commands for the tools kj cannot install unattended.
+// Multiple lines when the route depends on the distro/package manager.
+const OS_COMMANDS = {
+  docker: {
+    linux: ["sudo apt-get install -y docker.io   # Debian/Ubuntu", "sudo dnf install -y docker          # Fedora/RHEL"],
+    darwin: ["brew install --cask docker   # Docker Desktop, then open it once"],
+    win32: ["winget install Docker.DockerDesktop", "wsl --install   # if WSL2 is not set up yet"],
+  },
+  git: {
+    linux: ["sudo apt-get install -y git   # Debian/Ubuntu", "sudo dnf install -y git        # Fedora/RHEL"],
+    darwin: ["brew install git   # or: xcode-select --install"],
+    win32: ["winget install Git.Git"],
+  },
+  semgrep: {
+    // PEP 668 (#1256): system Python is externally managed on modern
+    // distros — pipx comes from the distro package manager, never from pip.
+    linux: ["sudo apt update && sudo apt install -y pipx && pipx install semgrep   # Debian/Ubuntu", "sudo dnf install -y pipx && pipx install semgrep   # Fedora/RHEL"],
+    darwin: ["brew install semgrep"],
+    win32: ["python -m pip install --user semgrep"],
+  },
+  "osv-scanner": {
+    linux: ["go install github.com/google/osv-scanner/v2/cmd/osv-scanner@v2   # or download from GitHub releases"],
+    darwin: ["brew install osv-scanner"],
+    win32: ["winget install Google.OSVScanner   # or download from GitHub releases"],
+  },
+  lighthouse: {
+    linux: ["npm install -g lighthouse"],
+    darwin: ["npm install -g lighthouse"],
+    win32: ["npm install -g lighthouse"],
+  },
+  ollama: {
+    linux: ["curl -fsSL https://ollama.com/install.sh | sh   # official installer (uses sudo)", "ollama pull nomic-embed-text"],
+    darwin: ["brew install ollama && brew services start ollama", "ollama pull nomic-embed-text"],
+    win32: ["winget install Ollama.Ollama", "ollama pull nomic-embed-text"],
+  },
+};
+
+/** Exact commands to install `tool` on `platform` (empty when unknown). */
+export function osCommandsFor(tool, platform = process.platform) {
+  return OS_COMMANDS[tool]?.[platform] ?? [];
+}
+
+/**
+ * Results that require the USER's hands. `manual`/`failed`/`needs-user`
+ * always qualify; `declined` only when nobody actually declined — a non-TTY
+ * run without --yes auto-answers the default, which for sudo installs is
+ * "no". A real interactive decline stays the user's own decision.
+ */
+export function collectPending(results, { tty = Boolean(process.stdin.isTTY), yes = false } = {}) {
+  return results.filter((r) => PENDING.has(r.action) || (r.action === "declined" && !tty && !yes));
+}
+
+/** The PENDING USER ACTION block: exact commands for THIS OS, then wait. */
+export function renderPendingBlock(pending, { platform = process.platform, retry = "kj install-tools" } = {}) {
+  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.",
+    "",
+    "Run in YOUR terminal:",
+    "",
+  ];
+  for (const r of pending) {
+    const why = r.error ? `install failed: ${r.error}` : r.reason || "no automatic route on this machine";
+    lines.push(`  ▸ ${r.tool}  (${why})`);
+    const os = osCommandsFor(r.tool, platform);
+    const own = r.commands ?? (r.command ? [r.command] : null) ?? (r.suggested ? [r.suggested] : null);
+    // A FAILED install must not be re-suggested verbatim (#1256: the pip
+    // route that just broke) — the curated per-OS route goes first there.
+    const commands = (r.action === "failed" ? (os.length > 0 ? os : own) : (own ?? (os.length > 0 ? os : null)))
+      ?? [`see ${r.manualUrl || "the tool's install docs"}`];
+    for (const c of commands) lines.push(`      ${c}`);
+    lines.push("");
+  }
+  lines.push(
+    `When done, re-run: ${retry}`,
+    "Agents: STOP here, show this block to your user, and WAIT for their",
+    `go-ahead. Exit code ${PENDING_EXIT_CODE} means "pending user action" — never proceed past it.`,
+  );
+  return lines.join("\n");
+}