karajan-code 3.1.0 → 3.3.0

package/src/brain/standby-scheduler.js

@@ -1,92 +1,10 @@
-// KJC-TSK-0414 PR 1: scheduler event-driven para hibernación.
-//
-// Diseño: setTimeout único por sesión, dispara EXACTAMENTE en cooldownUntil.
-// Cero polling. Si el proceso muere antes del fire, reconcileAll() al
-// arrancar el board re-programa los timeouts pendientes (o reanuda
-// inmediatamente los expirados).
-
-import { listPendingStandby, acquireStandbyLock, markStandbyDone } from "./standby-store.js";
-
-// Mapa sessionId → NodeJS.Timeout — accesible para test/cancel.
-const _scheduled = new Map();
-
-export function _resetScheduledForTests() {
-  for (const t of _scheduled.values()) clearTimeout(t);
-  _scheduled.clear();
-}
-
-/**
- * Programa un único setTimeout que dispara `onResume(sessionId)` en cooldownUntil.
- *
- * @param {object} args
- * @param {string} args.sessionId
- * @param {string} args.cooldownUntil - ISO timestamp
- * @param {Function} args.onResume - callback(sessionId) cuando llega el momento
- * @param {object} [args.logger]
- * @returns {{ scheduled: boolean, msUntil?: number, immediate?: boolean }}
- */
-export function scheduleResume({ sessionId, cooldownUntil, onResume, logger }) {
-  if (!sessionId || !cooldownUntil || typeof onResume !== "function") {
-    return { scheduled: false };
-  }
-  cancelScheduled(sessionId);
-  const targetMs = new Date(cooldownUntil).getTime();
-  if (Number.isNaN(targetMs)) return { scheduled: false };
-  const delay = targetMs - Date.now();
-  if (delay <= 0) {
-    // Ya expiró — reanudar inmediato (caso: board reiniciado tras llegar la hora).
-    logger?.info?.(`[standby-scheduler] ${sessionId}: cooldown ya expirado, resume inmediato`);
-    Promise.resolve().then(() => onResume(sessionId)).catch(() => { /* swallow */ });
-    return { scheduled: true, immediate: true };
-  }
-  const timer = setTimeout(() => {
-    _scheduled.delete(sessionId);
-    logger?.info?.(`[standby-scheduler] ${sessionId}: cooldown alcanzado, disparando resume`);
-    try { onResume(sessionId); } catch (err) { logger?.warn?.(`[standby-scheduler] onResume threw: ${err.message}`); }
-  }, delay);
-  if (typeof timer.unref === "function") timer.unref();
-  _scheduled.set(sessionId, timer);
-  logger?.info?.(`[standby-scheduler] ${sessionId}: scheduled in ${Math.round(delay / 1000)}s (until ${cooldownUntil})`);
-  return { scheduled: true, msUntil: delay };
-}
-
-/** Cancela el setTimeout de una sesión (caso: usuario hizo kj resume manual). */
-export function cancelScheduled(sessionId) {
-  const t = _scheduled.get(sessionId);
-  if (!t) return false;
-  clearTimeout(t);
-  _scheduled.delete(sessionId);
-  return true;
-}
-
-/**
- * Reconciliación al arrancar el board / kj. Lee todas las sesiones pendientes
- * y para cada una:
- *   - cooldownUntil < now → onResume inmediato
- *   - cooldownUntil > now → re-programa setTimeout
- *
- * Idempotente: el lockfile en standby-store previene dobles spawns si
- * reconcileAll() corre dos veces concurrentes (board reload).
- *
- * @param {object} args
- * @param {Function} args.onResume - callback(sessionId)
- * @param {object} [args.logger]
- * @returns {{ scheduled: number, immediate: number, total: number }}
- */
-export function reconcileAll({ onResume, logger }) {
-  const sessions = listPendingStandby();
-  let scheduled = 0;
-  let immediate = 0;
-  for (const s of sessions) {
-    if (!s?.sessionId || !s?.cooldownUntil) continue;
-    const r = scheduleResume({ sessionId: s.sessionId, cooldownUntil: s.cooldownUntil, onResume, logger });
-    if (r.scheduled && r.immediate) immediate += 1;
-    else if (r.scheduled) scheduled += 1;
-  }
-  logger?.info?.(`[standby-scheduler] reconcile: ${sessions.length} sesiones (${immediate} resume inmediato, ${scheduled} programadas)`);
-  return { scheduled, immediate, total: sessions.length };
-}
-
-// Re-export para que callers no tengan que importar standby-store si solo
-// necesitan el flow scheduler → lock → done.
-export { acquireStandbyLock, markStandbyDone };
+// Shim de compatibilidad: standby-scheduler vive ahora en @karajan/core.
+// Mantiene la ruta para callers internos del CLI.
+export {
+  _resetScheduledForTests,
+  scheduleResume,
+  cancelScheduled,
+  reconcileAll,
+  acquireStandbyLock,
+  markStandbyDone,
+} from "@karajan/core/standby-scheduler";

package/src/brain/standby-store.js

@@ -1,168 +1,12 @@
-// KJC-TSK-0414 PR 1: persistencia de sesiones hibernadas al disco.
-//
-// Cuando Brain decide hibernar (QUOTA_EXHAUSTED_DAILY con retryAfter > 5min),
-// serializa el estado completo del run en ~/.kj/standby/<sessionId>.json.
-// El proceso de kj run muere (exit 0) tras persistir; el board (o kj resume)
-// lo reanuda cuando llega cooldownUntil.
-//
-// Layout en disco:
-//   ~/.kj/standby/
-//     <sessionId>.json    ← sesiones pendientes (scheduler les mete setTimeout)
-//     <sessionId>.lock    ← lockfile durante spawn de kj resume
-//     done/
-//       <sessionId>.json  ← finalizadas (consumibles por GC en TSK-0414 PR3)
-
-import fs from "node:fs";
-import path from "node:path";
-import { writeJsonAtomicSync } from "../utils/atomic-write.js";
-import { resolveHome } from "../utils/paths.js";
-
-const FILENAME_RE = /^[a-zA-Z0-9._-]+\.json$/;
-
-// Delegates to the unified resolver. PR 3 of KJC-PCS-0047 switched
-// the default to `.karajan` — hibernated sessions now persist under
-// `~/.karajan/standby/`, migrated automatically from the legacy
-// `~/.kj/standby/` on the next `kj` invocation.
-function getKjHome() {
-  return resolveHome({ defaultSegment: ".karajan" });
-}
-
-export function standbyDir() {
-  return path.join(getKjHome(), "standby");
-}
-
-export function standbyDoneDir() {
-  return path.join(standbyDir(), "done");
-}
-
-function sanitizeId(sessionId) {
-  if (!sessionId || typeof sessionId !== "string") throw new Error("sessionId requerido");
-  return sessionId.replaceAll(/[^a-zA-Z0-9._-]/g, "_").slice(0, 120);
-}
-
-/**
- * Persiste el estado completo de un run hibernado.
- *
- * @param {object} state - shape:
- *   { sessionId, planId?, huId?, role, iteration?, prompt, agentConfig,
- *     retryCount?, cooldownUntil, reason, snapshot_sha?, outcome_so_far? }
- * @returns {string} path absoluto del JSON escrito
- */
-export function persistStandby(state) {
-  if (!state || !state.sessionId) throw new Error("state.sessionId requerido");
-  if (!state.cooldownUntil) throw new Error("state.cooldownUntil requerido");
-  const dir = standbyDir();
-  fs.mkdirSync(dir, { recursive: true });
-  const file = path.join(dir, `${sanitizeId(state.sessionId)}.json`);
-  const payload = {
-    ...state,
-    createdAt: state.createdAt || new Date().toISOString(),
-    persistedAt: new Date().toISOString(),
-  };
-  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}
- */
-export function loadStandby(sessionId) {
-  const file = path.join(standbyDir(), `${sanitizeId(sessionId)}.json`);
-  if (!fs.existsSync(file)) return null;
-  try {
-    return JSON.parse(fs.readFileSync(file, "utf-8"));
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Lista todas las sesiones pendientes (no las de done/).
- * @returns {object[]}
- */
-export function listPendingStandby() {
-  const dir = standbyDir();
-  if (!fs.existsSync(dir)) return [];
-  return fs.readdirSync(dir)
-    .filter((f) => FILENAME_RE.test(f))
-    .map((f) => {
-      try {
-        return JSON.parse(fs.readFileSync(path.join(dir, f), "utf-8"));
-      } catch {
-        return null;
-      }
-    })
-    .filter(Boolean);
-}
-
-/**
- * Mueve una sesión a done/ — consumible por GC en TSK-0414 PR3.
- * @param {string} sessionId
- * @returns {boolean} true si se movió
- */
-export function markStandbyDone(sessionId) {
-  const id = sanitizeId(sessionId);
-  const src = path.join(standbyDir(), `${id}.json`);
-  if (!fs.existsSync(src)) return false;
-  const doneDir = standbyDoneDir();
-  fs.mkdirSync(doneDir, { recursive: true });
-  const dst = path.join(doneDir, `${id}-${Date.now()}.json`);
-  fs.renameSync(src, dst);
-  return true;
-}
-
-/**
- * Lockfile para evitar dobles spawns de kj resume sobre la misma sesión.
- * Devuelve { acquired: true, release: () => void } o { acquired: false } si ya hay lock.
- *
- * @param {string} sessionId
- * @returns {{ acquired: boolean, release?: Function }}
- */
-export function acquireStandbyLock(sessionId) {
-  const id = sanitizeId(sessionId);
-  const lockFile = path.join(standbyDir(), `${id}.lock`);
-  try {
-    fs.mkdirSync(standbyDir(), { recursive: true });
-    fs.writeFileSync(lockFile, String(process.pid), { flag: "wx" });
-    return { acquired: true, release: () => { try { fs.unlinkSync(lockFile); } catch { /* */ } } };
-  } catch {
-    return { acquired: false };
-  }
-}
+// Shim de compatibilidad: standby-store vive ahora en @karajan/core.
+// Mantiene la ruta para callers internos del CLI.
+export {
+  standbyDir,
+  standbyDoneDir,
+  persistStandby,
+  buildStandbyState,
+  loadStandby,
+  listPendingStandby,
+  markStandbyDone,
+  acquireStandbyLock,
+} from "@karajan/core/standby-store";

package/src/checks/ai-trash.js

@@ -0,0 +1,34 @@
+/**
+ * ai-trash safety net availability check (KJC-TSK-0391).
+ * Surfaces a WARN in `kj doctor` when the `kj-trash` binary is missing,
+ * since the PreToolUse hook cannot snapshot destructive ops without it.
+ * The remediation is `kj-trash install --claude-code` once the binary is
+ * on PATH (the workspace ships it with karajan-code).
+ */
+
+import { detectAiTrash } from "../utils/ai-trash.js";
+import { STRATEGY } from "./types.js";
+
+function createAiTrashCheck() {
+  return {
+    name: "ai-trash",
+    label: "ai-trash safety net",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      const res = await detectAiTrash();
+      if (res.available) {
+        return { ok: true, severity: "info", detail: "kj-trash present — preventive safety net active" };
+      }
+      return {
+        ok: false,
+        severity: "warn",
+        detail: "kj-trash not found — destructive ops unprotected",
+        fix: "Reinstall karajan-code (kj-trash ships with the workspace) and run `kj-trash install --claude-code`",
+      };
+    },
+  };
+}
+
+export function getAiTrashChecks() {
+  return [createAiTrashCheck()];
+}

package/src/checks/qmd.js

@@ -0,0 +1,41 @@
+/**
+ * QMD availability check. Manual strategy — installation
+ * depends on the host platform and is handled by getInstallCommand().
+ *
+ * QMD (Quick Markdown Search) provides semantic search over the
+ * user's wiki / docs / notes collections. Karajan ships it as a
+ * default integration (mirror of Squeezr): kj init installs it,
+ * kj doctor reports its presence.
+ */
+
+import { runCommand } from "../utils/process.js";
+import { getInstallCommand } from "../utils/os-detect.js";
+import { withDocLink } from "../utils/doc-links.js";
+import { STRATEGY } from "./types.js";
+
+function createQmdCheck() {
+  return {
+    name: "qmd",
+    label: "QMD",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      try {
+        const res = await runCommand("qmd", ["--version"]);
+        if (res.exitCode === 0) {
+          return { ok: true, severity: "info", detail: `${res.stdout.trim()} — semantic wiki active` };
+        }
+      } catch { /* not installed */ }
+      const installCmd = getInstallCommand("qmd");
+      return {
+        ok: false,
+        severity: "warn",
+        detail: "Not found — semantic wiki via QMD available",
+        fix: withDocLink(`Install: ${installCmd}`, "qmd_install"),
+      };
+    },
+  };
+}
+
+export function getQmdChecks() {
+  return [createQmdCheck()];
+}

package/src/checks/squeezr.js

@@ -0,0 +1,36 @@
+/**
+ * Squeezr availability check. Manual strategy — installation
+ * depends on the host platform and is handled by getInstallCommand().
+ */
+
+import { runCommand } from "../utils/process.js";
+import { getInstallCommand } from "../utils/os-detect.js";
+import { withDocLink } from "../utils/doc-links.js";
+import { STRATEGY } from "./types.js";
+
+function createSqueezrCheck() {
+  return {
+    name: "squeezr",
+    label: "Squeezr",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      try {
+        const res = await runCommand("squeezr", ["--version"]);
+        if (res.exitCode === 0) {
+          return { ok: true, severity: "info", detail: `${res.stdout.trim()} — context compression active` };
+        }
+      } catch { /* not installed */ }
+      const installCmd = getInstallCommand("squeezr");
+      return {
+        ok: false,
+        severity: "warn",
+        detail: "Not found — context compression via Squeezr available",
+        fix: withDocLink(`Install: ${installCmd}`, "squeezr_install"),
+      };
+    },
+  };
+}
+
+export function getSqueezrChecks() {
+  return [createSqueezrCheck()];
+}

package/src/cli/register-meta.js

@@ -4,6 +4,7 @@ import { researcherCommand } from "../commands/researcher.js";
 import { architectCommand } from "../commands/architect.js";
 import { onboardCommand } from "../commands/onboard.js";
 import { ragIndexCommand, ragQueryCommand, ragInstallHooksCommand, ragEvalCommand } from "../commands/rag.js";
+import { qmdQueryCommand } from "../commands/qmd.js";
 import { ragMcpCommand } from "../commands/rag-mcp.js";
 import { watchStartCommand, watchStopCommand, watchStatusCommand } from "../commands/watch.js";
 import { auditCommand } from "../commands/audit.js";
@@ -172,6 +173,24 @@ export function registerMeta(program, { pkgVersion }) {
       await ragMcpCommand();
     });
 
+  // KJC-TSK-0509 — `kj qmd query` is a thin wrapper around the upstream
+  // `qmd` binary that auto-resolves the project's collection (rag = agent
+  // context; qmd = human wiki). One subcommand for now; index/add live in
+  // `kj init` and `kj rag install-hooks` (post-merge reindex).
+  const qmd = program.command("qmd").description("Semantic search over the per-project QMD wiki (docs/, .reviews/, .karajan/plans/)");
+  qmd.command("query <text>")
+    .description("Run a qmd query against the wiki collection of the current project")
+    .option("--collection <name>", "Override the auto-resolved <slug>-<suffix> collection name")
+    .option("--scope <name>", "docs (default) | reviews | plans", "docs")
+    .option("--top-k <n>", "Number of hits to return (1..50, default 10)", "10")
+    .option("--fast", "Skip the LLM reranker (faster, slightly noisier hits)")
+    .option("--json", "Emit the raw JSON array for piping to jq")
+    .action(async (text, flags) => {
+      await withConfig(pkgVersion, "qmd-query", flags, async ({ config, logger }) => {
+        await qmdQueryCommand({ text, config, logger, flags });
+      });
+    });
+
   // KJC-TSK-0441 — `kj watch [start|stop|status]` for live RAG re-index.
   const watch = program.command("watch").description("Live RAG re-index daemon");
   watch.command("start").description("Start the watcher daemon").option("--foreground", "Run in foreground (do not detach)").option("--with-sources", "Watch project source files too").action(async (flags) => {
@@ -197,6 +216,7 @@ export function registerMeta(program, { pkgVersion }) {
     .option("--no-osv", "Skip the OSV-Scanner vulnerability collector. Findings are also skipped automatically when osv-scanner is not installed.")
     .option("--no-semgrep", "Skip the Semgrep SAST collector. Findings are also skipped automatically when semgrep is not installed (install via 'pipx install semgrep' or 'brew install semgrep').")
     .option("--no-harness", "Skip the AI Harness Scorecard stage (Docker one-shot). Auto-skipped when Docker is unavailable. Each run is also persisted to .karajan/audit-history.db (KJC-TSK-0472) for diff/trend tracking.")
+    .option("--no-ai-slop", "Skip the AI-slop tells collector (deterministic regex scan for tautologic comments, banner separators, boilerplate docstrings, magic fallbacks, redundant JSDoc). KJC-TSK-0503.")
     .option("--trend", "Append a sparkline of the harness score across the last 10 runs (uses .karajan/audit-history.db). KJC-TSK-0473.")
     .option("--report-file <path>", "Write the audit report to disk in addition to stdout. <path> may be a file (extension drives format: .md or .json) or a directory (creates audit-<ISO>.<md|json> inside). $KJ_AUDIT_REPORT_DIR env var is used as default directory if no --report-file is given.")
     .option("--deterministic-only", "Skip the LLM analysis entirely. Print/persist only the deterministic findings (basalCost, sonar, stack, growth-delta, webperf). Zero tokens spent. Compatible with --report-file and --json.")
@@ -220,6 +240,7 @@ export function registerMeta(program, { pkgVersion }) {
           noOsv: flags.osv === false,
           noSemgrep: flags.semgrep === false,
           noHarness: flags.harness === false,
+          noAiSlop: flags.aiSlop === false,
           reportFile: flags.reportFile || null,
           deterministicOnly: Boolean(flags.deterministicOnly),
           yes: Boolean(flags.yes),

package/src/cli/register-pipeline.js

@@ -27,6 +27,9 @@ export function registerPipeline(program, { pkgVersion }) {
     .option("--global", "Save config to ~/.karajan/kj.config.yml (skip the scope wizard)")
     .option("--local", "Save config to ./.karajan/kj.config.yml (skip the scope wizard)")
     .option("--no-ollama", "Skip the RAG embedder bootstrap (Ollama-in-Docker). Useful on modest hardware or when an external embedder will be wired manually")
+    .option("--no-rtk", "Skip the RTK auto-install (token savings on Bash outputs). Karajan still runs but burns more tokens")
+    .option("--no-squeezr", "Skip the Squeezr auto-install (context compression). Karajan still runs but burns more tokens")
+    .option("--no-qmd", "Skip the QMD auto-install + collection registration (semantic wiki over docs/, .reviews/ and plans/)")
     .action(async (flags) => {
       await withConfig(pkgVersion, "init", flags, async ({ config: _config, logger }) => {
         await initCommand({ logger, flags });

package/src/commands/audit.js

@@ -216,7 +216,7 @@ function loadAuditHistoryContext(projectDir, currentHarness, { showTrend = false
   finally { try { db?.close(); } catch { /* noop */ } }
 }
 
-function describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, noHarness, json, deterministicOnly, yes }) {
+function describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, noHarness, noAiSlop, json, deterministicOnly, yes }) {
   const parts = ["kj audit"];
   if (task && task !== "Analyze the full codebase") parts.push(JSON.stringify(task));
   if (dimensions && dimensions !== "all") parts.push(`--dimensions=${dimensions}`);
@@ -224,13 +224,14 @@ function describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, noHar
   if (noOsv) parts.push("--no-osv");
   if (noSemgrep) parts.push("--no-semgrep");
   if (noHarness) parts.push("--no-harness");
+  if (noAiSlop) parts.push("--no-ai-slop");
   if (deterministicOnly) parts.push("--deterministic-only");
   if (yes) parts.push("--yes");
   if (json) parts.push("--json");
   return parts.join(" ");
 }
 
-export async function auditCommand({ task, config, logger, dimensions, json, agentReadiness, path: pathArg, noSonar = false, noOsv = false, noSemgrep = false, noHarness = false, reportFile = null, deterministicOnly = false, yes = false, trend = false, promptFn = null }) {
+export async function auditCommand({ task, config, logger, dimensions, json, agentReadiness, path: pathArg, noSonar = false, noOsv = false, noSemgrep = false, noHarness = false, noAiSlop = false, reportFile = null, deterministicOnly = false, yes = false, trend = false, promptFn = null }) {
   // --agent-readiness is a STANDALONE, deterministic, LLM-free audit
   // dimension. It scores any third-party repo for AI-agent readability
   // (llms.txt presence, page token budgets, robots allowlist, etc.).
@@ -269,6 +270,7 @@ export async function auditCommand({ task, config, logger, dimensions, json, age
       noSonar,
       noOsv,
       noSemgrep,
+      noAiSlop,
     };
     const deterministicCtx = await role.collectDeterministic(roleInput);
     const deterministicMd = formatDeterministicSummary(deterministicCtx);
@@ -324,7 +326,7 @@ export async function auditCommand({ task, config, logger, dimensions, json, age
         if (reportPath.endsWith(".json")) {
           payload = JSON.stringify({ deterministic: deterministicCtx, harnessScore: harnessJson, harnessScoreDiff: history.diff, mode: "deterministic-only" }, null, 2);
         } else {
-          const header = await buildReportHeader(config?.projectDir, describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, noHarness, json, deterministicOnly, yes }));
+          const header = await buildReportHeader(config?.projectDir, describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, noHarness, noAiSlop, json, deterministicOnly, yes }));
           payload = `${header}${deterministicMd}\n${harnessMd}${historyMd}`;
         }
         await fs.writeFile(reportPath, payload, "utf8");
@@ -385,7 +387,7 @@ export async function auditCommand({ task, config, logger, dimensions, json, age
           : { ...roleResult, harnessScore: harnessJson, harnessScoreDiff: history.diff, usage: usage || undefined };
         payload = JSON.stringify(jsonPayload, null, 2);
       } else {
-        const header = await buildReportHeader(config?.projectDir, describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, noHarness, json, deterministicOnly, yes }));
+        const header = await buildReportHeader(config?.projectDir, describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, noHarness, noAiSlop, json, deterministicOnly, yes }));
         payload = header + stdoutContent + "\n";
       }
       await fs.writeFile(reportPath, payload, "utf8");

package/src/commands/board.js

@@ -122,6 +122,29 @@ export function waitForEarlyExit(child, logPath) {
   });
 }
 
+// KJC-BUG-0080: waitForEarlyExit only catches an exit, not a hung
+// daemon that survived the window without ever bind()ing the port.
+// Poll /api/dashboard until it answers or the readiness budget runs
+// out, so we never announce "HU Board started" for an unreachable
+// server. Overridable with KJ_BOARD_READY_TIMEOUT_MS (tests set it
+// low to stay fast).
+export async function waitForBoardReachable(port, totalTimeoutMs) {
+  const envTimeout = Number(process.env.KJ_BOARD_READY_TIMEOUT_MS);
+  const budget = Number.isFinite(envTimeout) && envTimeout >= 0
+    ? envTimeout
+    : (Number.isFinite(totalTimeoutMs) ? totalTimeoutMs : 5000);
+  const intervalMs = budget <= 200 ? Math.max(10, Math.floor(budget / 5)) : 200;
+  const deadline = Date.now() + budget;
+  while (Date.now() < deadline) {
+    const remaining = deadline - Date.now();
+    const probeTimeout = Math.min(750, Math.max(50, remaining));
+    if (await isBoardReachable(port, probeTimeout)) return true;
+    const wait = Math.min(intervalMs, deadline - Date.now());
+    if (wait > 0) await new Promise((r) => setTimeout(r, wait));
+  }
+  return false;
+}
+
 export async function startBoard(desiredPort = 4000, opts = {}) {
   const { projectSlug = null, bind = "127.0.0.1" } = opts;
   const existingPid = readPid();
@@ -199,6 +222,17 @@ export async function startBoard(desiredPort = 4000, opts = {}) {
   if (failure) {
     throw new Error(failure);
   }
+  // KJC-BUG-0080: even after a clean window, the server may have
+  // failed to bind (e.g. port race vs the parent's findAvailablePort)
+  // or be still booting. Probe /api/dashboard before announcing
+  // success — without this the CLI used to print "HU Board started
+  // at http://localhost:4000" while :4000 actually returned nothing.
+  const reachable = await waitForBoardReachable(port);
+  if (!reachable) {
+    throw new Error(
+      `HU Board daemon spawned (PID ${child.pid}) but did not answer on http://localhost:${port} in time. See ${logPath} for the cause.`
+    );
+  }
   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

package/src/commands/doctor.js

@@ -22,6 +22,9 @@ import { getOllamaChecks } from "../checks/ollama.js";
 import { getHarnessScorecardChecks } from "../checks/harness-scorecard.js";
 import { getCiChecks } from "../checks/ci.js";
 import { getRtkChecks } from "../checks/rtk.js";
+import { getSqueezrChecks } from "../checks/squeezr.js";
+import { getAiTrashChecks } from "../checks/ai-trash.js";
+import { getQmdChecks } from "../checks/qmd.js";
 import { getNodeChecks } from "../checks/node.js";
 import { getPortChecks } from "../checks/ports.js";
 import { getTokenChecks } from "../checks/tokens.js";
@@ -64,6 +67,9 @@ function buildChecks(config, { projectOnly = false } = {}) {
     ...getSkillsChecks(),
     ...getCiChecks(),
     ...getRtkChecks(),
+    ...getSqueezrChecks(),
+    ...getAiTrashChecks(),
+    ...getQmdChecks(),
     ...getProjectChecks({ projectDir }),
   ];
 }