karajan-code 2.17.0 → 2.18.0

package/README.md

@@ -23,7 +23,13 @@
 
 ---
 
-> **v2.17.0 released** — Minor. `kj audit` gains two new deterministic structural collectors and the v2.16 Sonar false-positive filter is generalised to apply across every collector. **Knip dead-exports collector** (codeQuality dim): reports unused exports/types (MINOR) and unused files (MAJOR), stack-aware (JS/TS only, needs package.json), subprocess via `--reporter json`, 120s timeout. **Madge circular-import collector** (architecture dim): detects import cycles, severity by chain length (≥4 files = MAJOR), honours tsconfig.json path aliases, 60s timeout. **Generalised FP filter**: every collector (sonar, knip, madge, osv, semgrep) now uses the same `config.audit.false_positives` shape with `tool` field plus inline marker `// karajan-audit-ignore: <tool>:<ruleId>`; legacy `config.sonar.false_positives` and `// karajan-sonar-ignore:` keep working. **Built-in catalogue** ships 4 entries by default (knip:unused-files in tests/fixtures + examples, knip:unused-exports on barrel files, madge cycles in node_modules). **BREAKING(engines)**: Node `>=20.10` → `>=20.19` (knip 6.x requirement; same flavour as the v2.8 18→20.10 bump). 4 872/4 872 tests passing across 402 files. Safe upgrade from 2.16.0 if you're on Node ≥ 20.19.
+> **v2.18.0 released** — Minor. Closes the **resilience audit** triggered by the public launch: 15 PRs across 5 phases hardening Karajan against the silent-failure family of bugs — *the problem is not that something fails, the problem is failing without telling the user why.* **Phase 1 — hibernation end to end** (#756–#759): a quota cap is classified as a recoverable quota class (incl. Claude Code's `"You've hit your session limit · resets 10:10pm"`); `withBrainRecovery` persists a standby JSON; the orchestrator consumes `action:"hibernate"`, seals the session `hibernated` (resumable) instead of `failed`; the last line printed is the exact resume command (`kj standby resume <id>`). **Phase 2 — don't lie** (#761–#763): `runCommand` surfaces ENOENT so a missing agent CLI gets an actionable error (not an empty one); `silenceTimeoutMs` is forwarded to every role so a hung agent is killed, not waited on forever; all 6 state-file writers go through `writeJsonAtomic` (write-temp + rename) — interrupted writes can no longer truncate plans, sessions, standby snapshots. **Phase 3 — don't lose or block** (#764–#767): a corrupt plan JSON is renamed aside with a loud warn (was silently dropped from `kj plan list`); `kj.config.yml` parse errors throw `Invalid YAML in <path>` (used to brick every kj command including `kj doctor`); `injectLoadedPlan` reconciles HUs left in `coding`/`reviewing`/`running` by a killed `kj run` (cross-checked against the run-registry); board SQLite gets `busy_timeout`, a `user_version` schema gate and corruption recovery. **Phase 4 — don't degrade silently** (#768–#769): `TriageRole` warns loudly when LLM output is unparseable (used to skip researcher/architect/security/tester with a chirpy "fallback defaults" summary); `verifyCoderOutput` distinguishes a git failure from "the coder did nothing" (`gitError` + `retryStrategy: null`) — no more iterations blaming the agent for infra. **Phase 5 — safety net** (#770): a `tests/resilience/` suite indexes every silent-failure mode and pins each one with a test, plus an end-to-end tripwire for the whole quota → hibernate → resume flow. Plus CI runs the `packages/hu-board` suite on every PR (#755). 4 959/4 959 tests passing across 416 files. Safe upgrade from 2.17.2.
+>
+> **v2.17.2** — Patch. Wires quota-exhaustion **hibernation end to end**. A `kj run` / `kj plan` that hits a provider session or usage cap used to abort the task with an opaque `UNKNOWN_FATAL`; now it suspends and tells you how to resume. **Session-limit classification (#756)**: `"You've hit your session limit · resets 10:10pm"` matched no rate-limit pattern → `session limit`/`weekly limit` added, and `parseCooldown` learns the 12-hour `resets 10:10pm` clock. **Hibernation persists (#757)**: `withBrainRecovery` only wrote `~/.kj/standby/<id>.json` with a `sessionState`, which no caller passed — new `buildStandbyState()` assembles it with an allowlisted env subset (never the full `process.env`). **Orchestrator consumes `action:"hibernate"` (#758)**: no code checked for it, so a hibernation sealed the HU `failed`; the coder/refactorer stages now stop cleanly and the session is sealed `hibernated` (resumable). **Resume hint (#759)**: a stopped run's last line is now the exact command — `kj standby resume <id>` for a hibernation, `kj resume <id>` otherwise. Plus CI now runs the `packages/hu-board` suite (#755). 4 931/4 931 tests passing across 410 files. Safe upgrade from 2.17.1.
+>
+> **v2.17.1** — Patch. Fixes **KJC-BUG-0055**: a project deleted from the HU Board (🗑️) no longer resurrects on the next `kj plan` or board restart. Four independent leaks closed: (1) **`sync.js` temporal gate** — the unconditional `removeTombstone` from KJC-BUG-0050 becomes a `plan.updatedAt > tombstone.deleted_at` comparison, so a tombstoned project revives only when the plan is genuinely newer than the delete; (2) **`ephemeral-cleaner.js`** now writes a tombstone and `rm -rf`'s `hu-stories/`, `sessions/` and `~/.kj/plans/` dirs when wiping ephemeral projects at boot — previously the orphan directories revived the project on the next scan; (3) **`fullScan` boot GC** sweeps orphan tombstoned dirs (the manual DB-wipe case); (4) **`DELETE /api/projects/:id`** honours `KJ_PLANS_DIR` instead of the hardcoded path. New `getTombstone()` helper in `db.js`. **Also fixes a silent `kj board start` failure (#753)**: the daemon's entry-point guard compared `import.meta.url` to a hand-built `file://` path, which wrongly returned false on Windows, symlinked/global installs and paths with spaces — the board exited 0 with an empty log. `server.js` now trusts a `KJ_BOARD_DAEMON` launcher flag, adds `uncaughtException`/`unhandledRejection` handlers and an actionable `better-sqlite3` load error; `board.js` detects an early daemon exit instead of reporting a phantom PID. 4 909/4 909 tests passing across 408 files. Safe upgrade from 2.17.0.
+>
+> **v2.17.0** — Minor. `kj audit` gains two new deterministic structural collectors and the v2.16 Sonar false-positive filter is generalised to apply across every collector. **Knip dead-exports collector** (codeQuality dim): reports unused exports/types (MINOR) and unused files (MAJOR), stack-aware (JS/TS only, needs package.json), subprocess via `--reporter json`, 120s timeout. **Madge circular-import collector** (architecture dim): detects import cycles, severity by chain length (≥4 files = MAJOR), honours tsconfig.json path aliases, 60s timeout. **Generalised FP filter**: every collector (sonar, knip, madge, osv, semgrep) now uses the same `config.audit.false_positives` shape with `tool` field plus inline marker `// karajan-audit-ignore: <tool>:<ruleId>`; legacy `config.sonar.false_positives` and `// karajan-sonar-ignore:` keep working. **Built-in catalogue** ships 4 entries by default (knip:unused-files in tests/fixtures + examples, knip:unused-exports on barrel files, madge cycles in node_modules). **BREAKING(engines)**: Node `>=20.10` → `>=20.19` (knip 6.x requirement; same flavour as the v2.8 18→20.10 bump). 4 872/4 872 tests passing across 402 files. Safe upgrade from 2.16.0 if you're on Node ≥ 20.19.
 >
 > **v2.16.0** — Minor. Quality-focused release: **deterministic Sonar false-positive filter** (KJC-TSK-0416), wire universal de Brain Recovery completado en `semantic-detector` (TSK-0413 step D), codemod `replace(/regex/g, …)` → `replaceAll(/regex/g, …)` en 41 sitios, y limpieza de hallazgos del propio `kj audit` v2.15.0. The Sonar filter combines two mechanisms: (1) **static rules** `{ rule, filePattern, reason }` from a built-in catalog (covering common false positives like `javascript:S2699` on `tests/architecture/`) plus extensible via `config.sonar.false_positives`; (2) **inline ignores** with `// karajan-sonar-ignore: <ruleId>` on the issue line. Result: the coder stops burning tokens "fixing" non-broken assertions. Brain Recovery now wraps **every** AI call in the pipeline — `semantic-detector` was the last legacy caller. 4 846/4 846 tests passing across 401 files. Safe upgrade from 2.15.0.
 >

package/package.json

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

package/src/brain/agent-error-classifier.js

@@ -33,7 +33,11 @@ const ONE_WEEK_MS = 7 * 24 * 60 * 60 * 1000;
 
 const AUTH_PATTERNS = /\b401\b|\b403\b|unauthorized|invalid\s+api\s+key|authentication\s+failed|expired\s+token/i;
 const SILENCED_PATTERNS = /killed\s+after\s+\d+\s*ms|silence\s*timeout|no\s+output\s+for\s+\d+/i;
-const RATE_LIMIT_PATTERNS = /usage\s+limit|rate\s*limit|too\s+many\s+requests|\b429\b|throttl|exceeded\s+your\s+current\s+quota|resource\s+exhausted|quota\s+exceeded|token\s+limit\s+reached|monthly\s+limit|daily\s+limit/i;
+// `session\s+limit` / `weekly\s+limit` cover Claude Code's usage caps
+// ("You've hit your session limit · resets 10:10pm"). Without them the
+// message fell through to UNKNOWN_FATAL and the run aborted instead of
+// hibernating until the reset.
+const RATE_LIMIT_PATTERNS = /usage\s+limit|rate\s*limit|too\s+many\s+requests|\b429\b|throttl|exceeded\s+your\s+current\s+quota|resource\s+exhausted|quota\s+exceeded|token\s+limit\s+reached|monthly\s+limit|weekly\s+limit|daily\s+limit|session\s+limit/i;
 const API_DOWN_PATTERNS = /\b50[0-4]\b|bad\s+gateway|service\s+unavailable|gateway\s+timeout|overloaded|internal\s+server\s+error/i;
 const NETWORK_PATTERNS = /ECONNREFUSED|ECONNRESET|ETIMEDOUT|socket\s+hang\s+up|fetch\s+failed|network\s+error/i;
 

package/src/brain/standby-store.js

@@ -15,6 +15,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
+import { writeJsonAtomicSync } from "../utils/atomic-write.js";
 
 const FILENAME_RE = /^[a-zA-Z0-9._-]+\.json$/;
 
@@ -56,10 +57,46 @@ export function persistStandby(state) {
     createdAt: state.createdAt || new Date().toISOString(),
     persistedAt: new Date().toISOString(),
   };
-  fs.writeFileSync(file, JSON.stringify(payload, null, 2), "utf-8");
+  writeJsonAtomicSync(file, payload);
   return file;
 }
 
+// Only these env vars are carried into the standby snapshot. NEVER
+// persist the whole `process.env` — that would leak API keys and other
+// secrets into ~/.kj/standby/*.json. `kj standby resume` re-spawns with
+// the live env merged on top, so the snapshot only needs what is needed
+// to relaunch from the right place.
+const STANDBY_ENV_ALLOWLIST = ["KJ_HOME", "HOME", "PATH"];
+
+/**
+ * Builds the `sessionState` object that `withBrainRecovery` persists when
+ * a run hibernates. Pulls the session id, the relaunch metadata and an
+ * allowlisted env subset so `kj standby resume` can re-spawn the command.
+ * @param {object} args
+ * @param {object} args.session    - the pipeline session ({ id, plan_id? })
+ * @param {object} [args.config]   - resolved config ({ projectDir?, plan? })
+ * @param {string|null} [args.huId]
+ * @returns {object|null} sessionState, or null when there is no session id
+ */
+export function buildStandbyState({ session, config = {}, huId = null } = {}) {
+  if (!session?.id) return null;
+  const env = {};
+  for (const key of STANDBY_ENV_ALLOWLIST) {
+    if (process.env[key] != null) env[key] = process.env[key];
+  }
+  for (const [key, value] of Object.entries(process.env)) {
+    if (key.startsWith("KJ_") && value != null) env[key] = value;
+  }
+  return {
+    sessionId: session.id,
+    planId: session.plan_id || config.plan || null,
+    huId: huId || null,
+    argv: process.argv.slice(2),
+    cwd: config.projectDir || process.cwd(),
+    env,
+  };
+}
+
 /**
  * @param {string} sessionId
  * @returns {object|null}

package/src/checks/binaries.js

@@ -15,6 +15,7 @@
 import { checkBinary, KNOWN_AGENTS } from "../utils/agent-detect.js";
 import { runCommand } from "../utils/process.js";
 import { withDocLink } from "../utils/doc-links.js";
+import { getInstallHint, appliesToStack } from "../utils/install-hints.js";
 import { STRATEGY } from "./types.js";
 
 /**
@@ -105,6 +106,56 @@ function createSerenaCheck() {
   };
 }
 
+/**
+ * Audit-side external tool (semgrep, osv-scanner, lighthouse) check.
+ *
+ * These are not blockers: `kj audit` and `kj webperf` degrade to
+ * available:false when missing. We surface them in `kj doctor` so the
+ * user can see at a glance which audit dimensions are active, and we
+ * point to `kj install-tools` for one-line remediation.
+ *
+ * `lighthouse` is stack-gated: only flagged when the project is
+ * frontend / fullstack. On backend-only projects the check is a no-op
+ * (returns ok:true with detail "n/a") to keep doctor output focused.
+ */
+function createAuditToolCheck(tool, { gatedByStack = false, label }) {
+  return {
+    name: `audit-tool:${tool}`,
+    label,
+    strategy: STRATEGY.MANUAL,
+    async detect({ config } = {}) {
+      if (gatedByStack) {
+        // Stack detection is best-effort — failing here just means we
+        // treat the project as backend-only (skip the check). Keeps the
+        // doctor pipeline resilient to weird repos.
+        let stack = null;
+        try {
+          const { detectProjectStack } = await import("../utils/stack-detect.js");
+          stack = await detectProjectStack(config?.projectDir || process.cwd());
+        } catch { /* ignore */ }
+        if (!appliesToStack(tool, stack)) {
+          return { ok: true, severity: "info", detail: "n/a (no frontend stack detected)" };
+        }
+      }
+      const result = await checkBinary(tool);
+      if (result.ok) {
+        return { ok: true, severity: "info", detail: result.version || "available" };
+      }
+      const hint = await getInstallHint(tool);
+      const fixLine = hint.command
+        ? `Run \`kj install-tools --only ${tool}\` or: ${hint.command}`
+        : `Run \`kj install-tools --only ${tool}\` or see ${hint.manualUrl}`;
+      return {
+        ok: false,
+        severity: "warn",
+        detail: "Not found — `kj audit` dimension will degrade",
+        fix: fixLine,
+        extra: { tool, suggested: hint.command, manager: hint.manager, manualUrl: hint.manualUrl },
+      };
+    },
+  };
+}
+
 /**
  * Aggregate: all binary-related checks for the current config.
  * @returns {import("./types.js").Check[]}
@@ -119,5 +170,10 @@ export function getBinaryChecks() {
   }
   checks.push(createDockerCheck());
   checks.push(createSerenaCheck());
+  // KJC-TSK v2.18 — surface audit-side tools in doctor so the user knows
+  // which dimensions will work. lighthouse is gated to frontend stacks.
+  checks.push(createAuditToolCheck("semgrep", { label: "Semgrep (audit/security)" }));
+  checks.push(createAuditToolCheck("osv-scanner", { label: "OSV-Scanner (audit/security)" }));
+  checks.push(createAuditToolCheck("lighthouse", { label: "Lighthouse (webperf)", gatedByStack: true }));
   return checks;
 }

package/src/checks/runner.js

@@ -196,6 +196,10 @@ export async function runChecks(checks, ctx, options = {}) {
     detail: e.detail ?? "",
     fix: e.detectResult?.fix,
     runMs: e.runMs,
+    // Forward optional structured metadata so the doctor printer can
+    // surface per-tool remediation tips (KJC-TSK v2.18). Undefined when
+    // the check didn't set one — kept minimal so JSON output stays tight.
+    extra: e.detectResult?.extra,
   }));
 
   const summary = summarize(reports);

package/src/cli/register-pipeline.js

@@ -3,6 +3,7 @@ import { configCommand } from "../commands/config.js";
 import { codeCommand } from "../commands/code.js";
 import { reviewCommand } from "../commands/review.js";
 import { scanCommand } from "../commands/scan.js";
+import { installToolsCommand } from "../commands/install-tools.js";
 import { doctorCommand } from "../commands/doctor.js";
 import { reportCommand } from "../commands/report.js";
 import { runCommandHandler } from "../commands/run.js";
@@ -192,6 +193,26 @@ export function registerPipeline(program, { pkgVersion }) {
       if (Number.isInteger(exitCode)) process.exit(exitCode);
     });
 
+  program
+    .command("install-tools")
+    .description("Install external audit tools (semgrep, osv-scanner, lighthouse, docker, sonar) using the package manager available on your system")
+    .option("--only <tools>", "Comma-separated subset (e.g. \"semgrep,osv-scanner\"). Bypasses stack-gating.")
+    .option("-y, --yes", "Auto-accept all prompts (non-interactive)")
+    .option("--dry-run", "Show what would be installed without running anything")
+    .action(async (flags) => {
+      try {
+        const { exitCode } = await installToolsCommand({
+          only: flags.only,
+          yes: !!flags.yes,
+          dryRun: !!flags.dryRun,
+        });
+        if (Number.isInteger(exitCode)) process.exit(exitCode);
+      } catch (err) {
+        console.error(`kj install-tools: ${err?.message || err}`);
+        process.exit(1);
+      }
+    });
+
   program
     .command("status")
     .description("Show pipeline dashboard with HU progress")

package/src/commands/board.js

@@ -88,6 +88,40 @@ function buildBoardUrl(port, projectSlug) {
   return projectSlug ? `${base}/p/${projectSlug}` : base;
 }
 
+/**
+ * After spawning the board daemon, watch for an early exit. Resolves to
+ * an error string when the child dies within the window — a broken
+ * native module, a crash on boot, or the silent entry-point mismatch
+ * that made the daemon exit 0 without a trace — and to `null` when it
+ * survives. This is what stops `startBoard` from reporting `ok` for a
+ * daemon that died milliseconds after spawn. The window is overridable
+ * via KJ_BOARD_START_WINDOW_MS (tests set it low to stay fast).
+ * @param {import('node:child_process').ChildProcess} child
+ * @param {string} logPath
+ * @returns {Promise<string|null>}
+ */
+export function waitForEarlyExit(child, logPath) {
+  const envWindow = Number(process.env.KJ_BOARD_START_WINDOW_MS);
+  const windowMs = Number.isFinite(envWindow) && envWindow >= 0 ? envWindow : 1500;
+  return new Promise((resolve) => {
+    let settled = false;
+    let timer = null;
+    const onExit = (code, signal) => {
+      const how = signal ? `signal ${signal}` : `exit code ${code}`;
+      finish(`HU Board daemon died on startup (${how}). See ${logPath} for the cause.`);
+    };
+    function finish(value) {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      child.removeListener("exit", onExit);
+      resolve(value);
+    }
+    child.once("exit", onExit);
+    timer = setTimeout(() => finish(null), windowMs);
+  });
+}
+
 export async function startBoard(desiredPort = 4000, opts = {}) {
   const { projectSlug = null, bind = "127.0.0.1" } = opts;
   const existingPid = readPid();
@@ -141,8 +175,11 @@ export async function startBoard(desiredPort = 4000, opts = {}) {
 
   // Use process.execPath (absolute path to current node binary) instead of "node".
   // Fixes ENOENT on nvm setups where `node` is not in the spawned process's PATH.
+  // KJ_BOARD_DAEMON=1 tells server.js to run main() regardless of how
+  // its entry-point path compares — the symlink/Windows/space-in-path
+  // mismatch that used to make the daemon exit 0 in total silence.
   const child = spawn(process.execPath, [serverPath], {
-    env: { ...process.env, PORT: String(port), BIND_HOST: bind },
+    env: { ...process.env, PORT: String(port), BIND_HOST: bind, KJ_BOARD_DAEMON: "1" },
     detached: true,
     stdio: ["ignore", logFd, logFd],
     cwd: BOARD_DIR
@@ -154,6 +191,14 @@ export async function startBoard(desiredPort = 4000, opts = {}) {
   if (!child.pid) {
     throw new Error("Failed to spawn HU Board server");
   }
+  // Don't report success blindly: a crash on boot (e.g. broken
+  // better-sqlite3, or the silent entry-point mismatch) used to be
+  // reported as ok:true, leaving the user with a dead board and a log
+  // showing only the start line. Catch the early exit here.
+  const failure = await waitForEarlyExit(child, logPath);
+  if (failure) {
+    throw new Error(failure);
+  }
   fs.writeFileSync(PID_FILE, String(child.pid));
   // Detach for real: `detached: true` only sets up the new session;
   // without `unref()` the parent's event loop still holds a reference
@@ -289,7 +334,18 @@ export function renderBoardBanner({ url, status, projectName }) {
 export async function boardCommand({ action = "start", port = 4000, bind = "127.0.0.1", logger }) {
   switch (action) {
     case "start": {
-      const result = await startBoard(port, { bind });
+      let result;
+      try {
+        result = await startBoard(port, { bind });
+      } catch (err) {
+        // The daemon died on boot (broken native module, crash) or no
+        // free port was found. Surface it cleanly — the whole point of
+        // this fix is that `kj board start` never reports a phantom
+        // success while leaving a dead board behind.
+        logger.error(`HU Board failed to start: ${err.message}`);
+        process.exitCode = 1;
+        return { ok: false, error: err.message };
+      }
       if (result.alreadyRunning) {
         logger.info(`HU Board already running (PID ${result.pid}) at ${result.url}`);
       } else {

package/src/commands/doctor.js

@@ -171,4 +171,21 @@ function printHuman(report, { verbose }) {
   if (Object.keys(report.overrides).length > 0) {
     console.log(`Runtime overrides applied: ${JSON.stringify(report.overrides)}`);
   }
+
+  // KJC-TSK v2.18 — if any external audit tool (semgrep, osv-scanner,
+  // lighthouse) reported missing, surface the one-line remediation so
+  // the user doesn't have to dig the fix lines out of the wall of
+  // checks. The audit-tool checks emit names like "audit-tool:semgrep"
+  // and embed { tool, suggested } in `extra` (see binaries.js).
+  const installable = report.checks
+    .filter((c) => c.name?.startsWith("audit-tool:") && c.status === STATUS.WARN && c.extra?.tool)
+    .map((c) => c.extra.tool);
+  if (installable.length > 0) {
+    console.log();
+    const list = installable.join(", ");
+    const only = installable.length === 1 ? ` --only ${installable[0]}` : "";
+    console.log(`Tip: run \`kj install-tools${only}\` to install: ${list}.`);
+  }
 }
+
+export const __test = { printHuman };

package/src/commands/install-tools.js

@@ -0,0 +1,211 @@
+// `kj install-tools` — install the external audit tools that `kj audit`
+// and `kj webperf` rely on but does not bundle.
+//
+// Covers semgrep, osv-scanner, lighthouse, docker, sonar. Picks the
+// install command per tool from `getInstallHint` (HU1) so the command
+// matches the package manager available on the user's system.
+//
+// Lighthouse is stack-gated: by default we only prompt about it when
+// the project is frontend/fullstack. Pass `--only lighthouse` to bypass
+// the gate.
+//
+// Docker and sonar are special cases — see TOOL_HANDLERS below.
+
+import readline from "node:readline";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { checkBinary } from "../utils/agent-detect.js";
+import { getInstallHint, detectPackageManagers, appliesToStack } from "../utils/install-hints.js";
+import { detectProjectStack } from "../utils/stack-detect.js";
+
+const execFileAsync = promisify(execFile);
+
+const ALL_TOOLS = ["semgrep", "osv-scanner", "lighthouse", "docker", "sonar"];
+
+function parseOnlyList(raw) {
+  if (!raw) return null;
+  const wanted = String(raw).split(",").map((t) => t.trim()).filter(Boolean);
+  const invalid = wanted.filter((t) => !ALL_TOOLS.includes(t));
+  if (invalid.length > 0) {
+    throw new Error(`Unknown tool(s) in --only: ${invalid.join(", ")}. Valid: ${ALL_TOOLS.join(", ")}`);
+  }
+  return wanted;
+}
+
+function promptYesNo(question, defaultYes = true) {
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY) { resolve(defaultYes); return; } // non-TTY → assume default
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const hint = defaultYes ? "Y/n" : "y/N";
+    rl.question(`${question} [${hint}] `, (answer) => {
+      rl.close();
+      const a = (answer || "").trim().toLowerCase();
+      if (!a) return resolve(defaultYes);
+      resolve(a === "y" || a === "yes");
+    });
+  });
+}
+
+async function isInstalled(tool) {
+  // sonar is a Docker container, not a binary. We check it separately
+  // by looking at running containers via `docker ps`.
+  if (tool === "sonar") return checkSonarRunning();
+  if (tool === "lighthouse") return (await checkBinary("lighthouse")).ok;
+  if (tool === "docker") return (await checkBinary("docker")).ok;
+  return (await checkBinary(tool)).ok;
+}
+
+async function checkSonarRunning() {
+  try {
+    const { stdout } = await execFileAsync("docker", ["ps", "--format", "{{.Names}}", "--filter", "name=sonarqube"], { timeout: 5000 });
+    return stdout.trim().length > 0;
+  } catch { return false; }
+}
+
+async function runInstall(command) {
+  // Split on whitespace (commands here are simple, no nested quoting).
+  const [bin, ...args] = command.split(/\s+/);
+  try {
+    const { stdout, stderr } = await execFileAsync(bin, args, { timeout: 300_000, maxBuffer: 32 * 1024 * 1024 });
+    return { ok: true, stdout, stderr };
+  } catch (err) {
+    return { ok: false, error: err?.shortMessage || err?.message || String(err), stderr: err?.stderr };
+  }
+}
+
+/**
+ * Sonar handler: special case. Cannot install Sonar via package manager;
+ * the install is `docker compose -f <our-template> up -d` if Docker is
+ * available. Falls back to a manual URL otherwise.
+ */
+async function handleSonar({ available, dryRun }) {
+  if (!available.docker) {
+    return {
+      tool: "sonar",
+      action: "manual",
+      reason: "docker not available — sonar needs docker. Install docker first.",
+      manualUrl: "https://docs.docker.com/get-docker/",
+    };
+  }
+  const composePath = path.join(process.cwd(), "docker-compose.yml");
+  let composeExists = false;
+  try { await fs.access(composePath); composeExists = true; } catch { /* missing */ }
+  const command = composeExists
+    ? "docker compose up -d"
+    : "docker run -d --name sonarqube -p 9000:9000 sonarqube:lts-community";
+  return {
+    tool: "sonar",
+    action: dryRun ? "dry-run" : "ready",
+    command,
+    manualUrl: "https://docs.sonarsource.com/sonarqube-community-build/try-out-sonarqube/",
+  };
+}
+
+/**
+ * Docker handler: never auto-install (platform-specific, invasive).
+ * Always point at the official docs.
+ */
+function handleDocker(available) {
+  return {
+    tool: "docker",
+    action: "manual",
+    reason: "Docker install is platform-specific — see official docs.",
+    manualUrl: "https://docs.docker.com/get-docker/",
+    suggested: available.brew ? "brew install --cask docker" : null,
+  };
+}
+
+/**
+ * Plan + (optionally execute) the install of every requested tool.
+ *
+ * @param {Object} opts
+ * @param {string|null} [opts.only] - comma-separated subset
+ * @param {boolean} [opts.yes] - skip prompts
+ * @param {boolean} [opts.dryRun] - plan-only, no execution
+ * @param {Object} [opts.logger]
+ * @returns {Promise<{ results: Array<Object>, exitCode: number }>}
+ */
+export async function installToolsCommand(opts = {}) {
+  const only = parseOnlyList(opts.only);
+  const yes = !!opts.yes;
+  const dryRun = !!opts.dryRun;
+  const logger = opts.logger || console;
+
+  const targetTools = only || ALL_TOOLS;
+  const available = await detectPackageManagers();
+  const stack = await detectProjectStack(process.cwd()).catch(() => null);
+
+  const results = [];
+  for (const tool of targetTools) {
+    // Stack gating — lighthouse on backend-only projects is skipped
+    // UNLESS the user passed --only lighthouse explicitly.
+    if (tool === "lighthouse" && !only && !appliesToStack(tool, stack)) {
+      results.push({ tool, action: "skipped", reason: "no frontend stack detected" });
+      logger.info?.(`⊘ ${tool}: skipped (no frontend stack detected; use --only lighthouse to force)`);
+      continue;
+    }
+
+    if (await isInstalled(tool)) {
+      results.push({ tool, action: "already-installed" });
+      logger.info?.(`✓ ${tool}: already installed`);
+      continue;
+    }
+
+    if (tool === "sonar") {
+      const result = await handleSonar({ available, dryRun });
+      results.push(result);
+      logger.info?.(`▸ sonar: ${result.command || result.manualUrl}`);
+      if (!dryRun && result.action === "ready") {
+        const proceed = yes || await promptYesNo(`Start SonarQube with: ${result.command}?`);
+        if (proceed) {
+          const r = await runInstall(result.command);
+          result.action = r.ok ? "installed" : "failed";
+          if (!r.ok) result.error = r.error;
+        }
+      }
+      continue;
+    }
+
+    if (tool === "docker") {
+      const result = handleDocker(available);
+      results.push(result);
+      logger.info?.(`▸ docker: ${result.suggested || result.manualUrl}`);
+      continue;
+    }
+
+    // semgrep / osv-scanner / lighthouse — package-manager driven.
+    const hint = await getInstallHint(tool, available);
+    if (!hint.command || !hint.manager) {
+      results.push({ tool, action: "manual", reason: "no compatible package manager found", manualUrl: hint.manualUrl, suggested: hint.command });
+      logger.warn?.(`✗ ${tool}: no compatible package manager. Manual: ${hint.manualUrl}`);
+      continue;
+    }
+    if (dryRun) {
+      results.push({ tool, action: "dry-run", command: hint.command, manager: hint.manager });
+      logger.info?.(`▸ ${tool}: would run \`${hint.command}\` (manager: ${hint.manager})`);
+      continue;
+    }
+    const proceed = yes || await promptYesNo(`Install ${tool} with: ${hint.command}?`);
+    if (!proceed) {
+      results.push({ tool, action: "declined", command: hint.command });
+      logger.info?.(`⊘ ${tool}: declined`);
+      continue;
+    }
+    logger.info?.(`▸ ${tool}: running \`${hint.command}\`...`);
+    const r = await runInstall(hint.command);
+    if (r.ok) {
+      results.push({ tool, action: "installed", command: hint.command, manager: hint.manager });
+      logger.info?.(`✓ ${tool}: installed via ${hint.manager}`);
+    } else {
+      results.push({ tool, action: "failed", command: hint.command, error: r.error });
+      logger.warn?.(`✗ ${tool}: install failed (${r.error})`);
+    }
+  }
+
+  const failures = results.filter((r) => r.action === "failed").length;
+  return { results, exitCode: failures > 0 ? 1 : 0 };
+}
+
+export const __test = { parseOnlyList, isInstalled, ALL_TOOLS };

package/src/commands/plan/generate.js

@@ -11,6 +11,8 @@ import { applyReviewerFeedback, applyFixerPatch } from "../../plan/plan-fixer.js
 import { runStructuralPass } from "../../plan/plan-structural-pass.js";
 import { recommendModelsForHu, complexityFromTaskType } from "../../hu/model-router.js";
 import { withBrainRecovery } from "../../brain/with-brain-recovery.js";
+import { buildStandbyState } from "../../brain/standby-store.js";
+import { printResumeHint } from "../../utils/display/resume-hint.js";
 import { formatPlan, formatHuTable } from "./_shared.js";
 
 /**
@@ -61,6 +63,13 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
   // self-fix iter N por delante.
   const progress = createCliProgressReporter({ role: "planner:initial", quiet: Boolean(json) });
   let result;
+  // `kj plan` has no pipeline session, so synthesise a standby id
+  // (`plan_<stamp>`). If the planner hits a quota cap, withBrainRecovery
+  // persists it and `kj standby resume` re-spawns via the saved argv.
+  const plannerSessionState = buildStandbyState({
+    session: { id: `plan_${new Date().toISOString().replaceAll(/[:.]/g, "-")}` },
+    config,
+  });
   try {
     // KJC-TSK-0413: planner inicial pasa por Brain Recovery — clasifica
     // 401/429/5xx/SILENCED/etc y decide retry/standby/hibernate/abort.
@@ -69,6 +78,7 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
       taskArgs: { prompt, role: "planner", silenceTimeoutMs, timeoutMs, onOutput: progress.onOutput },
       role: "planner",
       logger,
+      sessionState: plannerSessionState,
     });
     progress.finish(result.ok ? "done" : (result.action || "failed"));
   } catch (err) {
@@ -76,6 +86,18 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
     throw err;
   }
 
+  if (!result.ok && result.action === "hibernate") {
+    // Quota cap: Brain Recovery persisted a standby snapshot. Stop
+    // cleanly with a resume hint instead of throwing a generic error.
+    const hibResult = {
+      ok: false, hibernated: true,
+      sessionId: plannerSessionState?.sessionId || null,
+      standbyFile: result.standbyFile || null,
+    };
+    if (!json) printResumeHint(hibResult);
+    process.exitCode = 1;
+    return hibResult;
+  }
   if (!result.ok) throw new Error(result.error || result.output || "Planner failed");
 
   const parsed = parseMaybeJsonString(result.output);

package/src/commands/run.js

@@ -7,6 +7,7 @@ import { withCliRunLog } from "../utils/cli-run-log.js";
 import { registerRun, unregisterRun } from "../utils/run-registry.js";
 import { printHeader } from "../utils/display/header.js";
 import { printEvent } from "../utils/display/event-handlers.js";
+import { printResumeHint } from "../utils/display/resume-hint.js";
 import { resolveRole } from "../config.js";
 import { parseCardId } from "../planning-game/adapter.js";
 import { confirmCwd } from "../utils/cwd-confirm.js";
@@ -175,6 +176,10 @@ export async function runCommandHandler({ task, config, logger, flags }) {
 
     if (jsonMode) {
       console.log(JSON.stringify(result, null, 2));
+    } else {
+      // Last line printed: if the run stopped (hibernated / paused /
+      // failed), tell the user the exact command to resume it.
+      printResumeHint(result);
     }
     return { ok: !result?.paused && result?.approved !== false };
   });