karajan-code 4.1.9 → 4.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.1.9",
+  "version": "4.1.10",
   "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/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/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();
+  }
+}