karajan-code 4.1.9 → 4.1.11

package/package.json

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

package/src/audit/osv-findings.js

@@ -19,10 +19,7 @@
  *     out-of-control result list cannot blow the token budget.
  */
 
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-
-const execFileAsync = promisify(execFile);
+import { runGoverned } from "../utils/tool-governor.js";
 
 const SCAN_TIMEOUT_MS = 60_000;
 const SEVERITY_ORDER = ["CRITICAL", "HIGH", "MEDIUM", "LOW", "MODERATE"];
@@ -42,7 +39,10 @@ export async function collectOsvFindings(projectDir, logger = null) {
   }
   let stdout;
   try {
-    const { stdout: out } = await execFileAsync(
+    // KJC-TSK-0668: governed run — single-flight across kj processes and a
+    // timeout that kills the whole process tree (osv-scanner is I/O-bound,
+    // no jobs flag to cap).
+    const { stdout: out } = await runGoverned(
       "osv-scanner",
       ["--format=json", "--recursive", projectDir || "."],
       { cwd: projectDir, timeout: SCAN_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024 }

package/src/audit/semgrep-findings.js

@@ -18,10 +18,7 @@
  *     into the `security` dimension using the rule ID as the rule field.
  */
 
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-
-const execFileAsync = promisify(execFile);
+import { runGoverned, jobsCap } from "../utils/tool-governor.js";
 
 const SCAN_TIMEOUT_MS = 120_000;
 const SEVERITY_ORDER = ["ERROR", "WARNING", "INFO"];
@@ -44,9 +41,12 @@ export async function collectSemgrepFindings(projectDir, logger = null) {
   }
   let stdout;
   try {
-    const { stdout: out } = await execFileAsync(
+    // KJC-TSK-0668: governed run — machine-wide single-flight, --jobs capped
+    // at half the CPUs (semgrep grabs 14 by default), nice +10, and a timeout
+    // that kills the whole process tree (no more orphaned semgrep-core).
+    const { stdout: out } = await runGoverned(
       "semgrep",
-      ["--config", "auto", "--json", "--quiet", `--timeout=${Math.floor(SCAN_TIMEOUT_MS / 1000)}`, projectDir || "."],
+      ["--config", "auto", "--json", "--quiet", `--jobs=${jobsCap()}`, `--timeout=${Math.floor(SCAN_TIMEOUT_MS / 1000)}`, projectDir || "."],
       { cwd: projectDir, timeout: SCAN_TIMEOUT_MS + 5000, maxBuffer: 32 * 1024 * 1024 }
     );
     stdout = out;

package/src/checks/orphans.js

@@ -0,0 +1,77 @@
+/**
+ * Orphaned scanner detection for `kj doctor` (KJC-TSK-0668). After the CPU
+ * storm, timed-out scans left semgrep-core processes reparented to init /
+ * systemd, silently burning cores. This check finds processes of tools kj
+ * governs whose parent is init (pid 1) or a systemd reaper, reports them,
+ * and — strategy "prompt" — offers to kill them.
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { STRATEGY } from "./types.js";
+
+const execFileAsync = promisify(execFile);
+const GOVERNED_TOOLS = new Set(["semgrep", "semgrep-core", "osv-scanner", "lighthouse"]);
+
+/**
+ * Scan the process table for governed tools whose parent is init or a
+ * systemd reaper (where the kernel sends orphans). `runPs` injectable.
+ */
+export async function findOrphanToolProcesses(runPs = execFileAsync) {
+  if (process.platform === "win32") return { supported: false, orphans: [] };
+  let stdout;
+  try {
+    ({ stdout } = await runPs("ps", ["-eo", "pid=,ppid=,comm="]));
+  } catch {
+    return { supported: false, orphans: [] };
+  }
+  const rows = [];
+  const commByPid = new Map();
+  for (const line of String(stdout).split("\n")) {
+    const m = line.trim().match(/^(\d+)\s+(\d+)\s+(.+)$/);
+    if (!m) continue;
+    const row = { pid: Number(m[1]), ppid: Number(m[2]), comm: m[3].trim() };
+    rows.push(row);
+    commByPid.set(row.pid, row.comm);
+  }
+  const orphans = rows.filter((r) =>
+    GOVERNED_TOOLS.has(r.comm) && (r.ppid === 1 || commByPid.get(r.ppid) === "systemd")
+  );
+  return { supported: true, orphans };
+}
+
+function createOrphanCheck() {
+  return {
+    name: "tool-orphans",
+    label: "Orphaned scanner processes",
+    strategy: STRATEGY.PROMPT,
+    describe: "Kill orphaned scanner processes left behind by interrupted runs",
+    async detect({ runPs } = {}) {
+      const { supported, orphans } = await findOrphanToolProcesses(runPs || execFileAsync);
+      if (!supported) return { ok: true, severity: "info", detail: "orphan detection not supported on this platform" };
+      if (orphans.length === 0) return { ok: true, severity: "info", detail: "no orphaned scanner processes" };
+      const list = orphans.map((o) => `${o.comm}(${o.pid})`).join(", ");
+      return {
+        ok: false,
+        severity: "warn",
+        detail: `${orphans.length} orphaned scanner process(es) burning CPU: ${list}`,
+        fix: `kill -9 ${orphans.map((o) => o.pid).join(" ")}`,
+        extra: { orphans },
+      };
+    },
+    async remediate({ extra, kill = process.kill } = {}) {
+      let killed = 0;
+      for (const o of extra?.orphans || []) {
+        try {
+          kill(o.pid, "SIGKILL");
+          killed += 1;
+        } catch { /* already gone */ }
+      }
+      return { fixed: killed > 0, detail: `killed ${killed} orphaned scanner process(es)` };
+    },
+  };
+}
+
+export function getOrphanChecks() {
+  return [createOrphanCheck()];
+}

package/src/cli/register-meta.js

@@ -403,10 +403,14 @@ export function registerMeta(program, { pkgVersion }) {
     .description("Resume a paused session")
     .argument("<sessionId>")
     .option("--answer <text>", "Answer to the question that caused the pause")
+    .option("--non-interactive", "Agents/CI: auto-answer prompts with their safe defaults; stop when there is none. Also enabled by KJ_NON_INTERACTIVE=1.")
     .option("--json", "Output JSON only")
     .action(async (sessionId, flags) => {
       await withConfig(pkgVersion, "resume", flags, async ({ config, logger }) => {
-        await resumeCommand({ sessionId, answer: flags.answer, config, logger, flags });
+        const res = await resumeCommand({ sessionId, answer: flags.answer, config, logger, flags });
+        // KJC-TSK-0674 (issue #1289): same contract as kj run — an aborted
+        // resume must be observable by CI.
+        if (res?.aborted) process.exitCode = 1;
       });
     });
 

package/src/cli/register-pipeline.js

@@ -54,6 +54,7 @@ export function registerPipeline(program, { pkgVersion }) {
     .argument("[task]", "Task description (REQUIRED — provide as argument or via --task-file)")
     .option("--task-file <path>", "Read the task from a file (e.g. .md). Alternative to the positional task argument.")
     .option("-y, --yes", "Skip the cwd confirmation prompt (CI / scripted runs).")
+    .option("--non-interactive", "Agents/CI: auto-answer prompts with their safe defaults (warn → continue) and stop with exit code 1 when there is none (fail). Also enabled by KJ_NON_INTERACTIVE=1.")
     .option("--planner <name>")
     .option("--coder <name>")
     .option("--reviewer <name>")
@@ -145,7 +146,10 @@ export function registerPipeline(program, { pkgVersion }) {
         }
         const { resolveTaskInput } = await import("../utils/task-file.js");
         const resolvedTask = await resolveTaskInput({ task: effectiveTask, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
-        await runCommandHandler({ task: resolvedTask, config, logger, flags });
+        const res = await runCommandHandler({ task: resolvedTask, config, logger, flags });
+        // KJC-TSK-0674 (issue #1289): an aborted run (spec-review cancel,
+        // unanswerable non-interactive gate) must be observable by CI.
+        if (res?.aborted) process.exitCode = 1;
       });
     });
 

package/src/commands/doctor.js

@@ -35,6 +35,7 @@ import { getSkillsChecks } from "../checks/skills.js";
 import { getDirSetupChecks } from "../checks/dir-setup.js";
 import { getProjectChecks } from "../checks/project-checks.js";
 import { getHardwareChecks } from "../checks/hardware.js";
+import { getOrphanChecks } from "../checks/orphans.js";
 
 /**
  * Build the list of Check objects applicable to the current config.
@@ -72,6 +73,7 @@ function buildChecks(config, { projectOnly = false } = {}) {
     ...getRtkChecks(),
     ...getSqueezrChecks(),
     ...getAiTrashChecks(),
+    ...getOrphanChecks(),
     ...getQmdChecks(),
     ...getRagHooksChecks({ projectDir }),
     ...getProjectChecks({ projectDir }),

package/src/commands/hu.js

@@ -20,6 +20,29 @@ export function creatorLabel() {
 export const HU_STATUSES = ["pending", "running", "done", "failed", "skipped"];
 const BACKLOG_NAME = "brain-backlog";
 
+// KJC-TSK-0675 (issue #1288): agents that skip `kj hu list` created twins of
+// existing work — sometimes in a DIFFERENT plan. Titles are compared
+// normalized (case/punctuation-insensitive) across every live HU of every
+// plan: identical → refuse; mostly-overlapping tokens → warn with candidates.
+const normTitle = (t) => String(t || "").toLowerCase().replaceAll(/[^\p{L}\p{N}]+/gu, " ").trim();
+const titleTokens = (t) => new Set(normTitle(t).split(" ").filter((w) => w.length > 2));
+
+export function findTitleMatches(title, allHus) {
+  const norm = normTitle(title);
+  const toks = titleTokens(title);
+  const identical = [];
+  const similar = [];
+  for (const h of allHus) {
+    if (h.status === "skipped") continue; // discarded cards don't reserve titles
+    if (normTitle(h.title) === norm) { identical.push(h); continue; }
+    const other = titleTokens(h.title);
+    const shared = [...toks].filter((w) => other.has(w)).length;
+    const smaller = Math.min(toks.size, other.size);
+    if (smaller > 0 && shared / smaller >= 0.8) similar.push(h);
+  }
+  return { identical, similar };
+}
+
 async function backlogPlan(projectDir) {
   const plans = await listPlans(projectDir);
   const existing = plans.find((p) => p.alias === BACKLOG_NAME || p.name === BACKLOG_NAME);
@@ -65,6 +88,26 @@ export async function huCommand({ config = null, action, args = [], flags = {} }
   if (action === "add") {
     const title = args[0];
     if (!title || !title.trim()) throw new Error("kj hu add requires a title: kj hu add \"<story>\"");
+    // Cross-plan title dedup (KJC-TSK-0675) — check BEFORE creating anything.
+    const allHus = [];
+    for (const meta of await listPlans(projectDir)) {
+      const p = await loadPlan(projectDir, meta.planId);
+      for (const h of p.hus || []) allHus.push({ ...h, plan: p.alias || p.name || p.planId });
+    }
+    const { identical, similar } = findTitleMatches(title, allHus);
+    if (identical.length > 0) {
+      const ref = identical[0];
+      throw new Error(
+        `An HU with this title already exists: ${ref.short_id || ref.id} (status: ${ref.status}, plan: ${ref.plan}). `
+        + `HUs are never duplicated — work that card, move it with: kj hu move ${ref.short_id || ref.id} <status>, `
+        + `or run kj hu list before adding.`
+      );
+    }
+    if (similar.length > 0) {
+      const plural = similar.length === 1 ? "" : "s";
+      const candidates = similar.map((h) => `  · ${h.short_id || h.id} (${h.status}, plan: ${h.plan}) "${h.title}"`).join("\n");
+      console.warn(`⚠ possible duplicate${plural} — check before working it:\n${candidates}`);
+    }
     const plan = await backlogPlan(projectDir);
     // KJC-TSK-0669 (absolute rule): cards are permanent. The delete-and-
     // recreate "fix" an agent improvises loses history and duplicates ids —

package/src/environment/briefs.js

@@ -87,9 +87,10 @@ const B = {
     render: () => brief("Board",
       "the HU Board is the permanent record of work: every card traces to who created it and what happened to it — a dashboard warning is fixed with the command it names, never by rebuilding the board.",
       [
+        "Before `kj hu add`, ALWAYS run `kj hu list`: if a card already covers the work (same scope, any plan), work THAT card instead of creating a twin.",
         "Cards are NEVER deleted or recreated — not to fix warnings, not to tidy up. Discard = `kj hu move <id> skipped` (archived, history kept).",
         "States move only via `kj hu move <id> <pending|running|done|failed|skipped>`.",
-        "A duplicate short_id means the card already exists: update that card, never add a twin.",
+        "A duplicate short_id or title means the card already exists: update that card, never add a twin.",
         "A warning is information, not damage: run the command it names; if it looks like a kj bug, `kj report-issue` — never work around it by destroying state.",
       ],
       "the board reflects reality: the same cards before and after your action, with truthful states and provenance intact."),

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 hu add` / `kj board`) before it starts. Cards are permanent — never delete or recreate one; discard with `kj hu move <id> skipped`. `kj brief board` explains the board.",
+  "hu-board": "Every piece of work has a tracked story/bug in the HU Board (`kj hu add` / `kj board`) before it starts — and `kj hu list` BEFORE `kj hu add`: reuse the existing card if one covers the work. Cards are permanent — never delete or recreate one; discard with `kj hu move <id> skipped`. `kj brief board` explains the board.",
   "planning-game": "Every piece of work has a tracked card in the Planning Game MCP before it starts (In Progress while you work it).",
 };
 

package/src/spec-review/run-spec-review.js

@@ -78,17 +78,24 @@ export async function runSpecReview({ spec, config, logger, askQuestion, flags =
       action = await decideGateAutonomously(resolve, { severity, findings });
     } else {
       if (!askQuestion) return { proceed: true, severity, findings, finalSpec: currentSpec };
+      // KJC-TSK-0674 (issue #1289): at severity FAIL the default flips to
+      // cancel — continuing past fails requires an explicit answer, both
+      // interactively (Enter cancels) and unattended (no declared default,
+      // so --yes / KJ_NON_INTERACTIVE stops with exit ≠ 0). warn/info keep
+      // the KJC-BUG-0109 contract: --yes presses Enter → continue.
+      const fallback = severity === "fail" ? "cancel" : "continue";
       const answer = await askQuestion(
-        `Spec review: ${findings.length} finding${findings.length === 1 ? "" : "s"} at severity ${severity}. [c]ontinue / [r]efine / [x]cancel? (default: continue)`,
+        `Spec review: ${findings.length} finding${findings.length === 1 ? "" : "s"} at severity ${severity}. [c]ontinue / [r]efine / [x]cancel? (default: ${fallback})`,
         {
           detail: { severity, findingCount: findings.length, categories: [...new Set(findings.map((f) => f.category))], iteration: iter + 1, findings: findingsForPrompt(findings) },
-          // KJC-BUG-0109: mirrors the interactive default — --yes presses Enter.
-          defaultAnswer: "continue",
+          defaultAnswer: severity === "fail" ? undefined : "continue",
         },
       );
       if (answer === null) return { proceed: false, cancelled: true, severity, findings };
-      const n = String(answer).trim().toLowerCase();
-      action = n.startsWith("x") || n === "cancel" ? "cancel" : n.startsWith("r") || n === "refine" ? "refine" : "continue";
+      const n = String(answer).trim().toLowerCase() || fallback;
+      if (n.startsWith("x") || n === "cancel") action = "cancel";
+      else if (n.startsWith("r") || n === "refine") action = "refine";
+      else action = "continue";
     }
     if (action === "cancel") return { proceed: false, cancelled: true, severity, findings };
     if (action === "refine") {

package/src/utils/cli-ask-question.js

@@ -28,22 +28,28 @@ export function createCliAskQuestion(opts = {}) {
   return async (question, context) => {
     const stdinReadable = process.stdin && process.stdin.readable !== false;
     const isInteractive = Boolean(process.stdin?.isTTY) && stdinReadable;
-    if (!isInteractive) {
-      if (flags?.yes) {
+    // KJC-TSK-0674 (issue #1289): agents and CI enable the same contract
+    // as --yes explicitly, via --non-interactive or KJ_NON_INTERACTIVE=1,
+    // instead of blocking forever on a board modal nobody is watching.
+    // Explicit mode wins even when a (pseudo-)TTY is attached.
+    const forcedNonInteractive = flags?.nonInteractive || process.env.KJ_NON_INTERACTIVE === "1";
+    if (!isInteractive || forcedNonInteractive) {
+      const nonInteractive = forcedNonInteractive || flags?.yes;
+      if (nonInteractive) {
         // KJC-BUG-0109: a question that declares a safe default is answered
         // with it — --yes means "press Enter for me", not "abort on any
         // gate". Questions without a declared default keep failing loud.
         const fallback = typeof context?.defaultAnswer === "string" && context.defaultAnswer.trim()
           ? context.defaultAnswer.trim() : null;
         if (fallback) {
-          process.stderr.write(`\n[non-interactive --yes] Auto-answering with declared default "${fallback}": ${question}\n`);
+          process.stderr.write(`\n[non-interactive] Auto-answering with declared default "${fallback}": ${question}\n`);
           return fallback;
         }
         process.stderr.write(
-          `\n[non-interactive --yes] Pipeline asked a question that cannot be auto-answered:\n`
+          `\n[non-interactive] Pipeline asked a question that cannot be auto-answered:\n`
           + `  ❓ ${question}\n`
           + (context?.detail ? `  Context: ${JSON.stringify(context.detail)}\n` : "")
-          + `  Stopping the session. Re-run without --yes (TTY or HU Board) to answer it,\n`
+          + `  Stopping the session. Re-run interactively (TTY or HU Board) to answer it,\n`
           + `  or pass --skip-spec-review / a more complete spec so the question never appears.\n`
         );
         return null;
@@ -56,7 +62,9 @@ export function createCliAskQuestion(opts = {}) {
       console.log(
         "\n[non-interactive] Routing the prompt to the HU Board.\n"
         + "  Open http://localhost:4000 — a modal will appear asking for your answer.\n"
-        + "  This process is now waiting; closing the board does NOT cancel the run."
+        + "  This process is now waiting; closing the board does NOT cancel the run.\n"
+        + "  Running from an agent or CI with nobody watching the board? Re-run with\n"
+        + "  --non-interactive (or KJ_NON_INTERACTIVE=1) to auto-answer safe defaults instead."
       );
       try {
         return await askThroughBoard({ sessionId, question, context });

package/src/utils/tool-governor.js

@@ -0,0 +1,116 @@
+/**
+ * tool-governor — resource governance for external tools launched by kj
+ * (KJC-TSK-0668), born from a real semgrep CPU storm: single-flight across
+ * processes (pid-stamped lockfile, stale locks stolen), jobs cap (half the
+ * CPUs), nice +10 best-effort, and hard timeouts that kill the PROCESS TREE
+ * (own process group on POSIX). In-process cousin: async-lock.js.
+ */
+
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const DEFAULT_LOCKS_DIR = path.join(os.homedir(), ".karajan", "locks");
+const NICENESS = 10;
+
+/** Parallelism cap for scanner `--jobs` flags: half the CPUs, min 1. */
+export function jobsCap(cpuCount = os.cpus().length) {
+  return Math.max(1, Math.floor(cpuCount / 2));
+}
+
+function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM"; // alive but owned by another user
+  }
+}
+
+/** Machine-wide lock for `tool` → {release}; ELOCKTIMEOUT if the live holder outlasts `timeoutMs`. */
+export async function acquireToolLock(tool, { locksDir = DEFAULT_LOCKS_DIR, timeoutMs = 180_000, pollMs = 500 } = {}) {
+  fs.mkdirSync(locksDir, { recursive: true });
+  const lockPath = path.join(locksDir, `${tool}.lock`);
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    try {
+      // wx = atomic create-or-fail: the filesystem is the arbiter.
+      const fd = fs.openSync(lockPath, "wx");
+      fs.writeSync(fd, JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() }));
+      fs.closeSync(fd);
+      return { release: () => fs.rmSync(lockPath, { force: true }) };
+    } catch (err) {
+      if (err.code !== "EEXIST") throw err;
+      let holder = null;
+      try {
+        holder = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+      } catch { /* unreadable → stale */ }
+      if (!holder || !Number.isInteger(holder.pid) || !isPidAlive(holder.pid)) {
+        fs.rmSync(lockPath, { force: true });
+        continue;
+      }
+      if (Date.now() >= deadline) {
+        const e = new Error(`${tool} is already running (pid ${holder.pid}, since ${holder.startedAt}) — gave up waiting after ${timeoutMs}ms`);
+        e.code = "ELOCKTIMEOUT";
+        throw e;
+      }
+      await new Promise((r) => setTimeout(r, pollMs));
+    }
+  }
+}
+
+/**
+ * Governed spawn: own process group (POSIX), lowered priority, timeout kills
+ * the whole tree. Rejections mirror execFile's contract (err.code /
+ * err.killed / err.stdout) so scanner collectors keep their error handling.
+ */
+export function governedExecFile(bin, args, { cwd, timeout = 0, maxBuffer = 16 * 1024 * 1024, niceness = NICENESS } = {}) {
+  return new Promise((resolve, reject) => {
+    const posix = process.platform !== "win32";
+    const child = spawn(bin, args, { cwd, detached: posix, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    let killedByGovernor = false, timer = null;
+    const killTree = () => {
+      killedByGovernor = true;
+      try {
+        if (posix) process.kill(-child.pid, "SIGKILL");
+        else child.kill("SIGKILL");
+      } catch { /* tree already gone */ }
+    };
+    if (timeout > 0) timer = setTimeout(killTree, timeout);
+    child.on("spawn", () => {
+      try {
+        os.setPriority(child.pid, niceness);
+      } catch { /* best-effort */ }
+    });
+    const bufferBlown = () => stdout.length + stderr.length > maxBuffer;
+    child.stdout.on("data", (d) => { stdout += d; if (bufferBlown()) killTree(); });
+    child.stderr.on("data", (d) => { stderr += d; if (bufferBlown()) killTree(); });
+    child.on("error", (err) => {
+      if (timer) clearTimeout(timer);
+      reject(Object.assign(err, { stdout, stderr }));
+    });
+    child.on("close", (code) => {
+      if (timer) clearTimeout(timer);
+      if (killedByGovernor) {
+        reject(Object.assign(new Error(`${bin} killed by governor after ${timeout}ms (process tree included)`), { killed: true, stdout, stderr }));
+      } else if (code === 0) {
+        resolve({ stdout, stderr });
+      } else {
+        reject(Object.assign(new Error(`${bin} exited with code ${code}`), { code, stdout, stderr }));
+      }
+    });
+  });
+}
+
+/** Lock + governed exec + guaranteed release. `opts.bin` overrides the executable. */
+export async function runGoverned(tool, args, opts = {}) {
+  const lock = await acquireToolLock(tool, opts.lock);
+  try {
+    return await governedExecFile(opts.bin || tool, args, opts);
+  } finally {
+    lock.release();
+  }
+}