karajan-code 2.34.0 → 3.1.0

package/src/audit/harness-scorecard.js

@@ -2,11 +2,44 @@
 // One-shot container: detect Docker, auto-pull on first run (cache hit
 // thereafter), execute `assess <repo>` with the project mounted read-only.
 // No compose, no port discovery — assess is a single process that exits.
+//
+// KJC-BUG-0077 — classify failures (docker_missing / image_inaccessible /
+// auth_required / network_error / unknown) and emit an actionable hint
+// alongside the raw stderr so `kj audit` surfaces something better than
+// the opaque "pull access denied" line the registry returns.
 import { runCommand } from "../utils/process.js";
 
 const D = { image: "markmishaev76/ai-harness-scorecard:latest", pullTimeoutMs: 300000, assessTimeoutMs: 180000 };
 const pos = (v, d) => (Number(v) > 0 ? Number(v) : d);
 
+const DOCKER_FAILURE_PATTERNS = [
+  { reason: "image_inaccessible", re: /pull access denied|repository does not exist|manifest unknown|not found: manifest|denied: requested access/i },
+  { reason: "auth_required",      re: /unauthorized|authentication required|login required|requires authentication/i },
+  { reason: "network_error",      re: /no such host|connection refused|dial tcp|i\/o timeout|TLS handshake|net\/http|temporary failure in name resolution/i },
+];
+
+export function classifyDockerFailure(stderr = "") {
+  const s = String(stderr);
+  for (const { reason, re } of DOCKER_FAILURE_PATTERNS) {
+    if (re.test(s)) return reason;
+  }
+  return "unknown";
+}
+
+export function hintForReason(reason, image) {
+  switch (reason) {
+    case "image_inaccessible":
+      return `Image \`${image}\` is not accessible from the public registry (it may have been removed, renamed, or made private). Either run \`kj audit --no-harness\` to skip this step, or override \`audit.harness.image\` with a mirror you control.`;
+    case "auth_required":
+      return `Pulling \`${image}\` requires registry authentication. Run \`docker login <registry>\` first, or override \`audit.harness.image\` with a public mirror.`;
+    case "network_error":
+      return `Network error reaching the registry while pulling \`${image}\`. Retry once connectivity is back; \`kj audit --no-harness\` skips this step in the meantime.`;
+    case "docker_missing":
+      return `Docker is not available on this machine. Install Docker (or run \`kj audit --no-harness\` to silence this).`;
+    default: return null;
+  }
+}
+
 export function normalizeHarnessConfig(h = {}) {
   return {
     enabled: h.enabled !== false,
@@ -32,20 +65,36 @@ export async function ensureHarnessImage(harness = null) {
   const cfg = normalizeHarnessConfig(harness || {});
   if (await isHarnessImagePresent(cfg.image)) return { pulled: false, reused: true, image: cfg.image };
   const r = await runCommand("docker", ["pull", cfg.image], { timeout: cfg.pullTimeoutMs });
-  if (r.exitCode !== 0) return { pulled: false, reused: false, image: cfg.image, error: r.stderr?.trim() || `exit ${r.exitCode}` };
+  if (r.exitCode !== 0) {
+    const stderr = r.stderr?.trim() || `exit ${r.exitCode}`;
+    const reason = classifyDockerFailure(stderr);
+    return { pulled: false, reused: false, image: cfg.image, error: stderr, reason };
+  }
   return { pulled: true, reused: false, image: cfg.image };
 }
 
 export async function runHarnessAssess(repoPath, harness = null) {
   const cfg = normalizeHarnessConfig(harness || {});
+  if (!(await isDockerAvailable())) {
+    return { ok: false, reason: "docker_missing", image: cfg.image, error: "Docker daemon is not available", hint: hintForReason("docker_missing", cfg.image) };
+  }
+  const pull = await ensureHarnessImage(cfg);
+  if (pull.error) {
+    const reason = pull.reason || "pull_failed";
+    return { ok: false, reason, image: cfg.image, error: pull.error, hint: hintForReason(reason, cfg.image) };
+  }
   const r = await runCommand(
     "docker",
     ["run", "--rm", "-v", `${repoPath}:/repo:ro`, cfg.image, "assess", "/repo", "--format", "json"],
     { timeout: cfg.assessTimeoutMs },
   );
-  if (r.exitCode !== 0) return { ok: false, error: r.stderr?.trim() || r.stdout?.trim() || `exit ${r.exitCode}` };
+  if (r.exitCode !== 0) {
+    const stderr = r.stderr?.trim() || r.stdout?.trim() || `exit ${r.exitCode}`;
+    const reason = classifyDockerFailure(stderr);
+    return { ok: false, reason, image: cfg.image, error: stderr, hint: hintForReason(reason, cfg.image) };
+  }
   try {
     const parsed = JSON.parse(r.stdout);
     return { ok: true, score: parsed.overall_score, grade: parsed.grade, raw: parsed };
-  } catch (e) { return { ok: false, error: `Invalid JSON from harness: ${e.message}` }; }
+  } catch (e) { return { ok: false, reason: "invalid_json", error: `Invalid JSON from harness: ${e.message}` }; }
 }

package/src/audit/harness-section.js

@@ -22,7 +22,7 @@ export async function runHarnessSection({ projectDir, harnessConfig = null, runA
   const cfg = normalizeHarnessConfig(harnessConfig || {});
   if (!cfg.enabled) return { ok: true, skipped: true, reason: "disabled" };
   const res = await runAssess(projectDir, cfg);
-  if (!res.ok) return { ok: false, error: res.error };
+  if (!res.ok) return { ok: false, error: res.error, reason: res.reason, hint: res.hint, image: cfg.image };
   const outDir = path.join(projectDir, ".karajan", "audit-runs", ts());
   await fs.mkdir(outDir, { recursive: true });
   const scorecardPath = path.join(outDir, "scorecard.json");
@@ -39,7 +39,11 @@ export async function runHarnessSection({ projectDir, harnessConfig = null, runA
 
 export function formatHarnessSection(summary) {
   if (!summary || summary.skipped) return "";
-  if (!summary.ok) return `## Harness Scorecard\n\n_skipped: ${summary.error}_\n`;
+  if (!summary.ok) {
+    const reason = summary.reason ? ` (${summary.reason})` : "";
+    const hint = summary.hint ? `\n\n${summary.hint}\n` : "";
+    return `## Harness Scorecard\n\n_skipped${reason}: ${summary.error}_${hint}\n`;
+  }
   const lines = [
     `## Harness Health Score: ${summary.score}/100 (${summary.grade})`,
     "",

package/src/audit/injection-findings.js

@@ -0,0 +1,105 @@
+/**
+ * Prompt-injection findings collector for `kj audit` (KJC-TSK-0498).
+ * Scans `.karajan/specs/**`, `.karajan/domain.md` and
+ * `.karajan/onboarding/**` reusing `src/utils/injection-guard.js`.
+ * Best-effort: missing folders return `scanned: 0`.
+ */
+
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { scanForInjection } from "../utils/injection-guard.js";
+
+const MAX_FILE_BYTES = 256 * 1024;
+const MAX_DEPTH = 6;
+const SEVERITY_BY_TYPE = { directive: "HIGH", unicode: "MEDIUM", comment_block: "LOW" };
+
+const SCAN_TARGETS = [
+  { rel: ".karajan/specs", kind: "dir" },
+  { rel: ".karajan/onboarding", kind: "dir" },
+  { rel: ".karajan/domain.md", kind: "file" },
+];
+
+export async function collectInjectionFindings(rootDir, logger = null) {
+  if (!rootDir) return { available: false, reason: "rootDir not provided" };
+  const findings = [];
+  let scanned = 0;
+  try {
+    for (const target of SCAN_TARGETS) {
+      const abs = path.join(rootDir, target.rel);
+      const files = target.kind === "dir"
+        ? await listFiles(abs, 0)
+        : (await fileExists(abs)) ? [abs] : [];
+      for (const file of files) {
+        scanned += 1;
+        const content = await safeRead(file);
+        if (!content) continue;
+        const result = scanForInjection(content);
+        if (result.clean) continue;
+        for (const f of result.findings) {
+          findings.push({
+            file: path.relative(rootDir, file),
+            type: f.type,
+            pattern: f.pattern,
+            snippet: f.snippet,
+            line: f.line,
+            severity: SEVERITY_BY_TYPE[f.type] || "LOW",
+          });
+        }
+      }
+    }
+  } catch (err) {
+    if (logger?.warn) logger.warn(`injection-findings collector failed: ${err.message}`);
+    return { available: false, reason: `collector failed: ${err.message}` };
+  }
+  return { available: true, scanned, total: findings.length, findings };
+}
+
+export function groupInjectionBySeverity(findings) {
+  const groups = { HIGH: [], MEDIUM: [], LOW: [] };
+  for (const f of findings || []) {
+    const sev = (f.severity || "LOW").toUpperCase();
+    if (groups[sev]) groups[sev].push(f);
+    else groups.LOW.push(f);
+  }
+  return groups;
+}
+
+async function listFiles(dir, depth) {
+  if (depth > MAX_DEPTH) return [];
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const entry of entries) {
+    const abs = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      const nested = await listFiles(abs, depth + 1);
+      out.push(...nested);
+    } else if (entry.isFile()) {
+      out.push(abs);
+    }
+  }
+  return out;
+}
+
+async function fileExists(file) {
+  try {
+    const s = await stat(file);
+    return s.isFile();
+  } catch {
+    return false;
+  }
+}
+
+async function safeRead(file) {
+  try {
+    const s = await stat(file);
+    if (s.size > MAX_FILE_BYTES) return null;
+    return await readFile(file, "utf8");
+  } catch {
+    return null;
+  }
+}

package/src/checks/hardware.js

@@ -0,0 +1,150 @@
+// Advisory hardware checks: warn (not fail) so the pipeline keeps running.
+// RAM < 4 GB silently OOM-kills the RAG embedder; disk < 5 GB corrupts
+// Ollama model shards. GPU detection is best-effort and never throws.
+
+import os from "node:os";
+import { statfs } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { STRATEGY } from "./types.js";
+
+const RAM_WARN_GB = 4;
+const RAM_RECOMMENDED_GB = 8;
+const DISK_WARN_GB = 5;
+const DISK_RECOMMENDED_GB = 20;
+const GPU_DETECT_TIMEOUT_MS = 1500;
+
+const bytesToGb = (bytes) => Math.round((bytes / 1024 ** 3) * 10) / 10;
+const info = (detail, extra) => ({ ok: true, severity: "info", detail, extra });
+const warn = (detail, fix, extra) => ({ ok: false, severity: "warn", detail, fix, extra });
+
+function createRamCheck() {
+  return {
+    name: "hw-ram",
+    label: "System RAM",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      const totalGb = bytesToGb(os.totalmem());
+      const freeGb = bytesToGb(os.freemem());
+      const base = `${totalGb} GB total, ${freeGb} GB free`;
+      if (totalGb < RAM_WARN_GB) {
+        return warn(
+          `${base} (RAG embedder needs >=${RAM_WARN_GB} GB)`,
+          "Disable local RAG (kj init --no-rag) or switch rag.embedder.provider to openai/voyage/cohere.",
+          { totalGb, freeGb, threshold: RAM_WARN_GB }
+        );
+      }
+      if (totalGb < RAM_RECOMMENDED_GB) {
+        return info(`${base} (>=${RAM_RECOMMENDED_GB} GB recommended for parallel runs)`, { totalGb, freeGb });
+      }
+      return info(base, { totalGb, freeGb });
+    },
+  };
+}
+
+function createCpuCheck() {
+  return {
+    name: "hw-cpu",
+    label: "CPU",
+    strategy: STRATEGY.NONE,
+    async detect() {
+      const cpus = os.cpus();
+      const model = cpus[0]?.model?.trim() || "unknown";
+      const cores = cpus.length;
+      const arch = os.arch();
+      return info(`${cores} cores, ${arch} (${model})`, { cores, arch, model });
+    },
+  };
+}
+
+function createDiskCheck() {
+  return {
+    name: "hw-disk",
+    label: "Disk space (cwd)",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      try {
+        const stat = await statfs(process.cwd());
+        const freeGb = bytesToGb(stat.bsize * stat.bavail);
+        if (freeGb < DISK_WARN_GB) {
+          return warn(
+            `${freeGb} GB free (>=${DISK_WARN_GB} GB recommended)`,
+            "Free disk space. Ollama models alone take 3-5 GB; the RAG store grows ~50 MB per 1k LOC indexed.",
+            { freeGb, threshold: DISK_WARN_GB }
+          );
+        }
+        const note = freeGb < DISK_RECOMMENDED_GB ? ` (>=${DISK_RECOMMENDED_GB} GB recommended)` : "";
+        return info(`${freeGb} GB free${note}`, { freeGb });
+      } catch (err) {
+        return info(`Cannot read free disk space: ${err.message}`);
+      }
+    },
+  };
+}
+
+function runGpuCommand(cmd, args) {
+  return new Promise((resolve) => {
+    let stdout = "";
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    try {
+      const child = spawn(cmd, args, { stdio: ["ignore", "pipe", "ignore"] });
+      const timer = setTimeout(() => {
+        try { child.kill("SIGKILL"); } catch { /* noop */ }
+        finish(null);
+      }, GPU_DETECT_TIMEOUT_MS);
+      child.stdout.on("data", (chunk) => { stdout += chunk.toString(); });
+      child.on("error", () => { clearTimeout(timer); finish(null); });
+      child.on("close", (code) => {
+        clearTimeout(timer);
+        finish(code === 0 ? stdout : null);
+      });
+    } catch {
+      finish(null);
+    }
+  });
+}
+
+async function detectGpu() {
+  const platform = process.platform;
+  if (platform === "linux" || platform === "win32") {
+    const out = await runGpuCommand("nvidia-smi", ["--query-gpu=name", "--format=csv,noheader"]);
+    const model = out?.split("\n").map((l) => l.trim()).find(Boolean);
+    if (model) return { vendor: "NVIDIA", model };
+    return null;
+  }
+  if (platform === "darwin") {
+    const out = await runGpuCommand("system_profiler", ["SPDisplaysDataType"]);
+    if (!out) return null;
+    const match = out.match(/Chipset Model:\s*(.+)/);
+    if (!match) return null;
+    const model = match[1].trim();
+    const vendor = /Apple/i.test(model) ? "Apple" : /AMD|Radeon/i.test(model) ? "AMD" : /Intel/i.test(model) ? "Intel" : "GPU";
+    return { vendor, model };
+  }
+  return null;
+}
+
+function createGpuCheck() {
+  return {
+    name: "hw-gpu",
+    label: "GPU",
+    strategy: STRATEGY.NONE,
+    async detect() {
+      const gpu = await detectGpu();
+      if (!gpu) {
+        return info("No discrete GPU detected (CPU-only)", { detected: false });
+      }
+      return info(`${gpu.vendor} ${gpu.model}`, { detected: true, vendor: gpu.vendor, model: gpu.model });
+    },
+  };
+}
+
+export function getHardwareChecks() {
+  return [createRamCheck(), createCpuCheck(), createDiskCheck(), createGpuCheck()];
+}
+
+export const __test = { RAM_WARN_GB, RAM_RECOMMENDED_GB, DISK_WARN_GB, DISK_RECOMMENDED_GB, GPU_DETECT_TIMEOUT_MS, bytesToGb, detectGpu };

package/src/checks/node.js

@@ -1,18 +1,17 @@
 /**
- * Node.js runtime version check. Requires Node >= 18 — the LTS baseline that
- * ships every runtime feature Karajan needs: ESM support, `fetch` (built-in),
- * `structuredClone` (17+), `AbortSignal.timeout` (17.3+), and
- * `Array.prototype.findLast` / `findLastIndex` (18+). Nothing in the runtime
- * code path uses Node 20+ APIs (no `Promise.withResolvers`, no
- * `Object.groupBy`, no `Set.prototype.union/intersection`, no
- * `Array.prototype.toSorted`). Strategy: manual — we cannot auto-upgrade the
- * runtime. Users on older Node get a clear upgrade instruction with nvm + brew
- * hints instead of a silent runtime crash.
+ * Node.js runtime version check. Requires Node >= 22 — the Active LTS
+ * baseline since Karajan v3.0.0 (KJC-TSK-0500, 2026-06-03). Node 20 was
+ * dropped because (a) Node 20 reaches EOL on 2026-04-30 and (b) three
+ * dependencies forced the bump: lint-staged 17 needs ≥22.22.1, commander
+ * 15 needs ≥22.12.0, and better-sqlite3 v12.10+ dropped Node 20 prebuilds.
+ * Strategy: manual — we cannot auto-upgrade the runtime. Users on older
+ * Node get a clear upgrade instruction with nvm + brew hints instead of a
+ * silent runtime crash.
  */
 
 import { STRATEGY } from "./types.js";
 
-export const MIN_NODE_MAJOR = 18;
+export const MIN_NODE_MAJOR = 22;
 
 /**
  * Accepts a version string in the form "v20.12.1" or "20.12.1" and returns

package/src/checks/runner.js

@@ -249,8 +249,15 @@ function summarize(reports) {
  *
  * @example setDotPath({}, "git.auto_pr", false) // → { git: { auto_pr: false } }
  */
+// KJC-BUG-0076: prototype-pollution guard. dot-paths come from check
+// remediation outputs (internal but LLM-generated), so a malformed
+// `__proto__.x` would mutate Object.prototype. Skip the whole write
+// when any segment matches a forbidden key.
+const UNSAFE_DOT_KEY_RE = /^(?:__proto__|constructor|prototype)$/;
+
 function setDotPath(target, dotPath, value) {
   const parts = String(dotPath).split(".");
+  if (parts.some((p) => UNSAFE_DOT_KEY_RE.test(p))) return;
   let cursor = target;
   for (let i = 0; i < parts.length - 1; i++) {
     const k = parts[i];
@@ -314,3 +321,6 @@ export function toLegacyShape(runReport) {
     fix: c.fix ?? null,
   }));
 }
+
+// Exposed for prototype-pollution regression tests (KJC-BUG-0076).
+export const __pollutionInternals = { setDotPath };

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 { ragMcpCommand } from "../commands/rag-mcp.js";
 import { watchStartCommand, watchStopCommand, watchStatusCommand } from "../commands/watch.js";
 import { auditCommand } from "../commands/audit.js";
 import { resumeCommand } from "../commands/resume.js";
@@ -12,6 +13,7 @@ import { webperfCommand } from "../commands/webperf.js";
 import { undoCommand } from "../commands/undo.js";
 import { syncCommand } from "../commands/sync.js";
 import { cleanCommand } from "../commands/clean.js";
+import { telemetryPreviewCommand, telemetryStatusCommand } from "../commands/telemetry.js";
 import { withConfig } from "./_shared.js";
 
 /**
@@ -160,6 +162,16 @@ export function registerMeta(program, { pkgVersion }) {
       });
     });
 
+  // KJC-TSK-0492 PR3 — `kj rag mcp` exposes the kj-rag-mcp binary under the
+  // familiar `kj rag <subcommand>` surface so users discover it without
+  // grepping bin/. The action dynamic-imports the binary, which takes over
+  // stdio for MCP transport; the CLI process never returns.
+  rag.command("mcp")
+    .description("Start the standalone RAG MCP server (kj_rag_query + kj_rag_index only). Same as running `kj-rag-mcp` directly")
+    .action(async () => {
+      await ragMcpCommand();
+    });
+
   // 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) => {
@@ -301,12 +313,34 @@ export function registerMeta(program, { pkgVersion }) {
 
   program
     .command("sync")
-    .description("Detect drift between code and the latest plan. Read-only report (issue #540 MVP).")
+    .description("Detect drift between code and the latest plan. Read-only by default; --apply writes a patch back to the Canvas.")
     .option("--plan <planId>", "Sync against a specific plan instead of the latest")
     .option("--json", "Emit machine-readable JSON instead of human output")
+    .option("--apply", "Write the drift report into the source Canvas (creates a .bak backup)")
     .action(async (flags) => {
       await withConfig(pkgVersion, "sync", flags, async ({ config, logger }) => {
-        await syncCommand({ config, logger, planId: flags.plan, json: flags.json });
+        await syncCommand({ config, logger, planId: flags.plan, json: flags.json, apply: Boolean(flags.apply) });
+      });
+    });
+
+  // KJC-TSK-0496 — surface the exact telemetry payload without sending it,
+  // and report whether telemetry is currently enabled. Read-only inspection
+  // commands so users can audit the contract without grepping the source.
+  const telemetry = program.command("telemetry").description("Inspect what Karajan telemetry sends and whether it's enabled (never opens a socket)");
+  telemetry.command("preview")
+    .description("Print the exact JSON payload for every event type (install, cli_command, pipeline_complete) — no network call")
+    .option("--json", "Emit the full preview as JSON")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "telemetry:preview", flags, async ({ config, logger }) => {
+        await telemetryPreviewCommand({ config, logger, version: pkgVersion, json: Boolean(flags.json) });
+      });
+    });
+  telemetry.command("status")
+    .description("Report whether telemetry is enabled and where the endpoint lives")
+    .option("--json", "Emit the status as JSON")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "telemetry:status", flags, async ({ config, logger }) => {
+        await telemetryStatusCommand({ config, logger, json: Boolean(flags.json) });
       });
     });
 
@@ -319,10 +353,22 @@ export function registerMeta(program, { pkgVersion }) {
     .option("--draft-days <n>", "Keep draft plans for N days (default: 60)")
     .option("--session-days <n>", "Keep finalised sessions for N days (default: 7)")
     .option("--hu-days <n>", "Keep HU story batches for N days (default: 14)")
+    .option("--repo", "Also report repo-level candidates (merged branches, dist/, coverage/, *.tmp, *.bak)")
+    .option("--repo-days <n>", "Age threshold for repo artifacts in days (default: 7)")
+    .option("--repo-base <ref>", "Base ref to detect merged branches (default: origin/main)")
+    .option("--vector-stores", "Also report orphan RAG vector-store entries in ~/.karajan/rag.db")
+    .option("--project-roots <list>", "Colon-separated directories to scan for live projects (default: ~/ws_*, ~/projects, ~/code)")
+    .option("--all", "Shortcut for --repo --vector-stores (full read-only cleanup audit)")
     .action(async (flags) => {
+      const allOn = Boolean(flags.all);
       await cleanCommand({
         yes: Boolean(flags.yes),
         nuke: Boolean(flags.nuke),
+        repo: Boolean(flags.repo) || allOn,
+        repoDays: flags.repoDays ? Number(flags.repoDays) : undefined,
+        repoBase: flags.repoBase || undefined,
+        vectorStores: Boolean(flags.vectorStores) || allOn,
+        projectRoots: flags.projectRoots ? flags.projectRoots.split(":").filter(Boolean) : undefined,
         planDays: flags.planDays ? Number(flags.planDays) : undefined,
         draftDays: flags.draftDays ? Number(flags.draftDays) : undefined,
         sessionDays: flags.sessionDays ? Number(flags.sessionDays) : undefined,

package/src/cli/register-plan.js

@@ -93,7 +93,16 @@ export function registerPlan(program, { pkgVersion }) {
           // Norms + Safeguards ride along under explicit headings the
           // coder prompt can grep for.
           const taskFromCanvas = canvasToTask(validation.canvas);
-          await planGenerateCommand({ task: taskFromCanvas, config, logger, flags });
+          // KJC-TSK-0348: remember WHERE the Canvas lived on disk so
+          // `kj sync --apply` later knows which file to patch.
+          let sourceCanvasPath = null;
+          if (typeof flags?.taskFile === "string" && flags.taskFile.length > 0) {
+            const path = await import("node:path");
+            sourceCanvasPath = path.isAbsolute(flags.taskFile)
+              ? flags.taskFile
+              : path.resolve(config.projectDir || process.cwd(), flags.taskFile);
+          }
+          await planGenerateCommand({ task: taskFromCanvas, config, logger, flags, sourceCanvasPath });
           return;
         }
         await planGenerateCommand({

package/src/commands/clean.js

@@ -19,11 +19,18 @@
  */
 
 import { runManualGC, summarizeGC, nukeBoardDb } from "../utils/garbage-collector.js";
+import { collectRepoCandidates } from "../utils/repo-cleaner.js";
+import { collectVectorStoreOrphans } from "../utils/vector-store-orphans.js";
 
 /**
  * @param {Object} opts
  * @param {boolean} [opts.yes=false]           - when false, dry-run only
  * @param {boolean} [opts.nuke=false]          - retention=0 for every bucket + wipe board DB
+ * @param {boolean} [opts.repo=false]          - also report repo-level candidates (branches, dist, *.tmp, *.bak)
+ * @param {number}  [opts.repoDays=7]          - age threshold for repo artifacts (default 7d)
+ * @param {string}  [opts.repoBase="origin/main"]
+ * @param {boolean} [opts.vectorStores=false]  - also report orphan RAG vector-store entries
+ * @param {string[]} [opts.projectRoots]       - directories scanned to resolve slugs (default: ~/ws_*, ~/projects, ~/code)
  * @param {number}  [opts.planDays=30]
  * @param {number}  [opts.draftDays=60]
  * @param {number}  [opts.sessionDays=7]
@@ -79,5 +86,60 @@ export async function cleanCommand(opts = {}) {
     console.log(summarizeGC(result));
   }
 
+  if (opts.repo) await printRepoReport(opts);
+  if (opts.vectorStores) await printVectorStoreReport(opts);
+
   return { ok: true, removed: result.removed.length, bytesFreed: result.bytesFreed };
 }
+
+async function printRepoReport(opts) {
+  const { candidates, errors } = await collectRepoCandidates({
+    maxAgeDays: opts.repoDays ?? 7,
+    mergedTo: opts.repoBase ?? "origin/main",
+  });
+  console.log("");
+  if (!candidates.length) {
+    console.log("[clean:repo] no repo-level candidates — branches/dist/tmp are tidy.");
+    return;
+  }
+  console.log(`[clean:repo] ${candidates.length} candidate(s) — review and run the command to remove:`);
+  for (const c of candidates) {
+    console.log(`  - ${c.kind.padEnd(11)} ${c.target}`);
+    console.log(`                ${c.reason}`);
+    console.log(`                $ ${c.command}`);
+  }
+  if (errors.length) {
+    console.log(`[clean:repo] ${errors.length} non-blocking error(s):`);
+    for (const e of errors) console.log(`  - ${e.stage}: ${e.error}`);
+  }
+  console.log("[clean:repo] read-only — commands are printed, never executed.");
+}
+
+async function printVectorStoreReport(opts) {
+  const { rows, orphans, errors } = await collectVectorStoreOrphans({
+    projectRoots: opts.projectRoots,
+  });
+  console.log("");
+  if (errors.length && !rows.length) {
+    console.log("[clean:rag] could not read rag.db — RAG may not be initialised yet.");
+    for (const e of errors) console.log(`  - ${e.stage}: ${e.error}`);
+    return;
+  }
+  console.log(`[clean:rag] ${rows.length} project_slug(s) indexed in rag.db:`);
+  for (const r of rows) {
+    const tag = r.orphan ? " ORPHAN" : "";
+    const when = r.lastAt || "n/a";
+    console.log(`  - ${r.slug.padEnd(28)} chunks=${String(r.chunkCount).padStart(5)}  last=${when}${tag}`);
+  }
+  if (!orphans.length) {
+    console.log("[clean:rag] no orphans — every indexed slug resolves to a live project directory.");
+    return;
+  }
+  console.log("");
+  console.log(`[clean:rag] ${orphans.length} orphan(s) — review and run to purge:`);
+  for (const o of orphans) {
+    console.log(`  - ${o.slug}`);
+    console.log(`                $ ${o.command}`);
+  }
+  console.log("[clean:rag] read-only — commands are printed, never executed.");
+}

package/src/commands/doctor.js

@@ -29,6 +29,7 @@ import { getMcpHealthChecks } from "../checks/mcp-health.js";
 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";
 
 /**
  * Build the list of Check objects applicable to the current config.
@@ -50,6 +51,7 @@ function buildChecks(config, { projectOnly = false } = {}) {
   return [
     ...getSystemChecks(),
     ...getNodeChecks(),
+    ...getHardwareChecks(),
     ...getDirSetupChecks(),
     ...getConfigFileChecks(),
     ...getBinaryChecks(),