karajan-code 2.34.0 → 3.0.0

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/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) => {
@@ -310,6 +322,27 @@ export function registerMeta(program, { pkgVersion }) {
       });
     });
 
+  // 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) });
+      });
+    });
+
   program
     .command("clean")
     .description("Garbage-collect stale plans, sessions and HU batches (dry-run by default)")

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(),

package/src/commands/init.js

@@ -12,6 +12,7 @@ import { createWizard, isTTY } from "../utils/wizard.js";
 import { runCommand } from "../utils/process.js";
 import { getInstallCommand } from "../utils/os-detect.js";
 import { detectOsLocale, SUPPORTED_LANGUAGES } from "../utils/locale.js";
+import { buildTelemetryPayload, sendTelemetryEvent } from "../utils/telemetry.js";
 import { detectRtk } from "../utils/rtk-detect.js";
 import { installRtk } from "../utils/rtk-install.js";
 import { detectProjectStack } from "../utils/stack-detect.js";
@@ -256,6 +257,42 @@ async function askBoardSecurity(wizard, config, logger) {
   logger.info(`  -> HU Board port: ${config.hu_board.port}`);
 }
 
+/**
+ * Explicit, opt-in telemetry consent. We do NOT inherit a "Karajan-installed
+ * users want to help" assumption — silence and missing config keys both mean
+ * "no". The prompt is rendered in the OS locale (EN/ES today; falls back to
+ * EN for everything else) so users see it in their own language even before
+ * they've set `config.language`. See src/utils/telemetry.js and the
+ * "Privacy & Telemetry" section of README.md for what gets sent.
+ */
+async function askTelemetry(wizard, config, logger) {
+  const locale = detectOsLocale();
+  const prompts = {
+    es: {
+      question: "¿Quieres ayudar a mejorar Karajan enviando telemetría anónima al proyecto?",
+      detail: "  (versión, OS, comandos, duración del pipeline — sin código, sin tareas, sin datos personales)",
+      previewIntro: "  Ejemplo del payload exacto que se enviaría al ejecutar `kj run` (puedes inspeccionar más con `kj telemetry preview`):",
+      enabled: "  -> Telemetría: activada (¡gracias!)",
+      disabled: "  -> Telemetría: desactivada",
+    },
+    en: {
+      question: "Help improve Karajan by sending anonymous telemetry to the project?",
+      detail: "  (version, OS, commands, pipeline duration — no code, no tasks, no personal data)",
+      previewIntro: "  Example of the exact payload that would be sent when you run `kj run` (inspect more with `kj telemetry preview`):",
+      enabled: "  -> Telemetry: enabled (thank you!)",
+      disabled: "  -> Telemetry: disabled",
+    },
+  };
+  const t = prompts[locale] || prompts.en;
+  logger.info(t.detail);
+  const example = buildTelemetryPayload("cli_command", { version: "x.y.z", command: "run" });
+  logger.info(t.previewIntro);
+  logger.info(`    ${JSON.stringify(example)}`);
+  const enabled = await wizard.confirm(t.question, false);
+  config.telemetry = enabled;
+  logger.info(enabled ? t.enabled : t.disabled);
+}
+
 async function runWizard(config, logger) {
   const agents = await detectAvailableAgents();
   const available = agents.filter((a) => a.available);
@@ -318,6 +355,10 @@ async function runWizard(config, logger) {
       await askBoardSecurity(wizard, config, logger);
     }
 
+    logger.info("");
+    logger.info("Privacy:");
+    await askTelemetry(wizard, config, logger);
+
     logger.info("");
   } finally {
     wizard.close();
@@ -735,7 +776,6 @@ export async function initCommand({ logger, flags = {} }) {
   await writeInitConfig(configPath, config);
 
   // Telemetry: anonymous install event (non-blocking)
-  const { sendTelemetryEvent } = await import("../utils/telemetry.js");
   const { readFileSync } = await import("node:fs");
   const { fileURLToPath } = await import("node:url");
   try {

package/src/commands/rag-mcp.js

@@ -0,0 +1,18 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { pathToFileURL } from "node:url";
+
+/**
+ * `kj rag mcp` — spawn the standalone RAG MCP server inline.
+ *
+ * KJC-TSK-0492 PR3. Adds CLI discoverability for the `kj-rag-mcp` binary
+ * so external IDE users can find it via the same `kj rag <subcommand>`
+ * surface they already know. The implementation dynamic-imports the
+ * binary entry so behavior stays identical to running `kj-rag-mcp`
+ * directly — same handlers, same transport, same orphan guard.
+ */
+export async function ragMcpCommand() {
+  const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+  const binPath = path.resolve(moduleDir, "../../bin/kj-rag-mcp.js");
+  await import(pathToFileURL(binPath).href);
+}

package/src/commands/telemetry.js

@@ -0,0 +1,70 @@
+import { TELEMETRY_ENDPOINT, buildTelemetryPayload, isTelemetryEnabled } from "../utils/telemetry.js";
+
+/**
+ * Render the exact payload that would be POSTed for every event type.
+ *
+ * Read-only by design: this never opens a socket. It exists so users
+ * can inspect what telemetry sends before (or after) opting in,
+ * without grepping the source. The contract here MUST stay in sync
+ * with the producers in src/cli/_shared.js and the pipeline emitter
+ * in src/orchestrator/flow-runner.js — if a new field appears there,
+ * mirror it in the example below.
+ */
+function buildPreview(version) {
+  const v = version || "x.y.z";
+  return {
+    endpoint: TELEMETRY_ENDPOINT,
+    events: [
+      buildTelemetryPayload("install", { version: v }),
+      buildTelemetryPayload("cli_command", { version: v, command: "run" }),
+      buildTelemetryPayload("pipeline_complete", {
+        version: v,
+        mode: "standard",
+        agent: "claude",
+        duration_s: 42,
+        success: true,
+        taskType: "feature"
+      })
+    ]
+  };
+}
+
+export async function telemetryPreviewCommand({ config, logger, version, json }) {
+  const preview = buildPreview(version);
+  if (json) {
+    logger.info(JSON.stringify(preview, null, 2));
+    return preview;
+  }
+  const enabled = isTelemetryEnabled(config);
+  logger.info(`Telemetry endpoint: ${preview.endpoint}`);
+  logger.info(`Telemetry enabled:  ${enabled ? "yes" : "no"}`);
+  logger.info("");
+  logger.info("Exact payloads that would be POSTed (one per event type):");
+  logger.info("");
+  for (const payload of preview.events) {
+    logger.info(`  [${payload.event}]`);
+    logger.info(`    ${JSON.stringify(payload)}`);
+    logger.info("");
+  }
+  logger.info("No data was sent — `kj telemetry preview` never opens a socket.");
+  return preview;
+}
+
+export async function telemetryStatusCommand({ config, logger, json }) {
+  const enabled = isTelemetryEnabled(config);
+  const report = {
+    enabled,
+    endpoint: TELEMETRY_ENDPOINT,
+    flipHint: enabled
+      ? "Set `telemetry: false` in ~/.karajan/kj.config.yml (or re-run `kj init`) to turn it off."
+      : "Set `telemetry: true` in ~/.karajan/kj.config.yml (or re-run `kj init`) to turn it on."
+  };
+  if (json) {
+    logger.info(JSON.stringify(report, null, 2));
+    return report;
+  }
+  logger.info(`Telemetry: ${enabled ? "enabled" : "disabled"}`);
+  logger.info(`Endpoint:  ${report.endpoint}`);
+  logger.info(report.flipHint);
+  return report;
+}

package/src/config/defaults.js

@@ -196,7 +196,10 @@ const DEFAULTS = {
     // hook. Both default ON; flip to false to opt out without uninstalling.
     autoUpdate: { onCommit: true, onRun: true }
   },
-  telemetry: true,
+  // Opt-in. Set by the `kj init` wizard (explicit consent prompt in the OS
+  // locale). When the key is absent or false, no events are sent. See
+  // src/utils/telemetry.js and the Privacy & Telemetry section of README.md.
+  telemetry: false,
   guards: {
     output: {
       enabled: true,

package/src/orchestrator/stages/coder-stage.js

@@ -19,6 +19,7 @@ import { invokeSolomon } from "../solomon-escalation.js";
 import { detectRateLimit } from "../../utils/rate-limit-detector.js";
 import { createStallDetector } from "../../utils/stall-detector.js";
 import { buildStandbyState } from "../../brain/standby-store.js";
+import { applyQuotaSimulation } from "../../utils/quota-simulator.js";
 import { snapshotHomeTopLevel, detectNewHomeEntries, formatLeakMessage, verifyLeaksAgainstTranscript, detectTranscriptCdLeaks } from "../fs-leak-detector.js";
 
 export async function runCoderStage({ coderRoleInstance, coderRole, config, logger, emitter, eventBase, session, plannedTask, trackBudget, iteration, brainCtx, acceptanceTests = null, adrs = null, specSection = null, reviewerFindings = null, huId = null }) {
@@ -76,6 +77,7 @@ export async function runCoderStage({ coderRoleInstance, coderRole, config, logg
     coderStall.stop();
   }
   trackBudget({ role: "coder", provider: coderRole.provider, model: coderRole.model, result: coderExecResult.result, duration_ms: Date.now() - coderStart });
+  applyQuotaSimulation(coderExecResult, { iteration, agent: coderRole.provider });
 
   if (!coderExecResult.ok) {
     const details = coderExecResult.result?.error || coderExecResult.summary || "unknown error";
@@ -281,6 +283,7 @@ export async function runRefactorerStage({ refactorerRole, config, logger, emitt
     refactorerStall.stop();
   }
   trackBudget({ role: "refactorer", provider: refactorerRole.provider, model: refactorerRole.model, result: refResult.result, duration_ms: Date.now() - refactorerStart });
+  applyQuotaSimulation(refResult, { iteration, agent: refactorerRole.provider });
   if (!refResult.ok) {
     const details = refResult.result?.error || refResult.summary || "unknown error";
     // Quota cap → hibernate cleanly, same as the coder stage above.

package/src/orchestrator/stages/reviewer-stage.js

@@ -13,6 +13,7 @@ import { runReviewerWithFallback } from "../reviewer-fallback.js";
 import { invokeSolomon } from "../solomon-escalation.js";
 import { detectRateLimit } from "../../utils/rate-limit-detector.js";
 import { createStallDetector } from "../../utils/stall-detector.js";
+import { applyQuotaSimulation } from "../../utils/quota-simulator.js";
 
 function categorizeIssues(issues) {
   const categories = { security: 0, correctness: 0, tests: 0, style: 0, other: 0 };
@@ -269,6 +270,16 @@ export async function runReviewerStage({ reviewerRole, config, logger, emitter,
     reviewerStall.stop();
   }
 
+  if (applyQuotaSimulation(reviewerExec.execResult, { iteration, agent: reviewerRole.provider })) {
+    // Reviewer wraps the agent call: detectRateLimit reads `lastAttempt.result.error`,
+    // so propagate the synthetic line into the most recent attempt too.
+    const last = reviewerExec.attempts?.at(-1);
+    if (last) {
+      if (!last.result || typeof last.result !== "object") last.result = {};
+      last.result.error = reviewerExec.execResult.result.error;
+    }
+  }
+
   if (!reviewerExec.execResult?.ok) {
     const lastAttempt = reviewerExec.attempts.at(-1);
     const details =

package/src/roles/audit-role.js

@@ -8,6 +8,7 @@ import { collectOsvFindings } from "../audit/osv-findings.js";
 import { collectSemgrepFindings } from "../audit/semgrep-findings.js";
 import { collectCircularDeps } from "../audit/circular-deps.js";
 import { collectDeadExports } from "../audit/dead-exports.js";
+import { collectInjectionFindings } from "../audit/injection-findings.js";
 
 function parseDimensions(dimensionsStr) {
   if (!dimensionsStr || dimensionsStr === "all") return null;
@@ -51,6 +52,7 @@ export class AuditRole extends AgentRole {
     const noSemgrep = typeof input === "object" ? Boolean(input?.noSemgrep) : false;
     const noMadge = typeof input === "object" ? Boolean(input?.noMadge) : false;
     const noKnip = typeof input === "object" ? Boolean(input?.noKnip) : false;
+    const noInjectionScan = typeof input === "object" ? Boolean(input?.noInjectionScan) : false;
     const projectDir = this.config?.projectDir || process.cwd();
     let basalCost = null;
     let growthDelta = null;
@@ -61,6 +63,7 @@ export class AuditRole extends AgentRole {
     let semgrepFindings = null;
     let circularDeps = null;
     let deadExports = null;
+    let injectionFindings = null;
     try {
       basalCost = await measureBasalCost(projectDir);
       const previous = await loadPreviousAudit(projectDir);
@@ -108,7 +111,12 @@ export class AuditRole extends AgentRole {
         deadExports = await collectDeadExports(projectDir, stack, this.config, this.logger);
       } catch { /* knip is best-effort */ }
     }
-    return { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports };
+    if (!noInjectionScan) {
+      try {
+        injectionFindings = await collectInjectionFindings(projectDir, this.logger);
+      } catch { /* injection scan is best-effort (KJC-TSK-0498) */ }
+    }
+    return { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports, injectionFindings };
   }
 
   /**

package/src/sonar/scanner.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import fsPromises from "node:fs/promises";
 import path from "node:path";
+import os from "node:os";
 import { runCommand } from "../utils/process.js";
 import { sonarUp } from "./manager.js";
 import { resolveSonarProjectKey } from "./project-key.js";
@@ -10,6 +11,32 @@ import {
   resolveSonarCredentials,
 } from "./config-resolver.js";
 
+export async function findNativeSonarScanner() {
+  const which = await runCommand("sh", ["-c", "command -v sonar-scanner"]);
+  if (which.exitCode === 0) {
+    const bin = String(which.stdout || "").trim();
+    if (bin) return bin;
+  }
+  return null;
+}
+
+export async function pickSonarScanner(scannerConfig = {}, deps = {}) {
+  const find = deps.findNativeSonarScanner || findNativeSonarScanner;
+  const arch = deps.arch || os.arch();
+  const forced = String(scannerConfig.command || "").trim().toLowerCase();
+  if (forced === "docker") return { type: "docker" };
+  if (forced === "native" || forced === "sonar-scanner" || forced.endsWith("/sonar-scanner")) {
+    const bin = (forced === "native" || forced === "sonar-scanner") ? await find() : forced;
+    if (bin) return { type: "native", bin };
+    return { type: "docker", reason: "native sonar-scanner not found on PATH" };
+  }
+  if (arch === "arm64") {
+    const bin = await find();
+    if (bin) return { type: "native", bin, reason: "ARM64 host — preferring native binary" };
+  }
+  return { type: "docker" };
+}
+
 export function buildScannerOpts(projectKey, scanner = {}) {
   const opts = [`-Dsonar.projectKey=${projectKey}`];
   if (scanner.sources) opts.push(`-Dsonar.sources=${scanner.sources}`);
@@ -236,31 +263,39 @@ export async function runSonarScan(config, projectKey = null) {
     ...coverage.scannerPatch
   });
 
-  const args = [
-    "run",
-    "--rm",
-    "-v",
-    `${process.cwd()}:/usr/src`,
-    ...(isLocalHost ? ["--add-host", "host.docker.internal:host-gateway"] : []),
-    ...(isLocalHost || isExternalSonar ? [] : ["--network", sonarNetwork]),
-    "-e", "SONAR_HOST_URL",
-    "-e", "SONAR_TOKEN",
-    "-e", "SONAR_SCANNER_OPTS",
-    "sonarsource/sonar-scanner-cli"
-  ];
-
-  // Pass secrets via process env, not CLI args — invisible in `ps aux`
+  const pick = await pickSonarScanner(sonarConfig.scanner);
   const env = {
     ...process.env,
-    SONAR_HOST_URL: host,
+    SONAR_HOST_URL: pick.type === "native" ? rawHost : host,
     SONAR_TOKEN: token || "",
     SONAR_SCANNER_OPTS: buildScannerOpts(effectiveProjectKey, scannerConfig)
   };
 
-  const result = await runCommand("docker", args, { timeout: scannerTimeout, env });
+  let cmd, args;
+  if (pick.type === "native") {
+    cmd = pick.bin;
+    args = [];
+  } else {
+    cmd = "docker";
+    args = [
+      "run",
+      "--rm",
+      "-v",
+      `${process.cwd()}:/usr/src`,
+      ...(isLocalHost ? ["--add-host", "host.docker.internal:host-gateway"] : []),
+      ...(isLocalHost || isExternalSonar ? [] : ["--network", sonarNetwork]),
+      "-e", "SONAR_HOST_URL",
+      "-e", "SONAR_TOKEN",
+      "-e", "SONAR_SCANNER_OPTS",
+      "sonarsource/sonar-scanner-cli"
+    ];
+  }
+
+  const result = await runCommand(cmd, args, { timeout: scannerTimeout, env });
   return {
     ok: result.exitCode === 0,
     projectKey: effectiveProjectKey,
+    scanner: pick.type,
     stdout: result.stdout,
     stderr: result.stderr,
     exitCode: result.exitCode

package/src/utils/quota-simulator.js

@@ -0,0 +1,56 @@
+// KJ_SIMULATE_QUOTA — testing hook for the standby flow. See
+// docs/quota-simulation.md. KJC-TSK-0493.
+
+let _warned = false;
+
+export function parseQuotaSimulationConfig(env = process.env) {
+  const trigger = env.KJ_SIMULATE_QUOTA;
+  if (!trigger) return null;
+  const m = /^after-iter-(\d+)$/i.exec(String(trigger).trim());
+  if (!m) {
+    if (!_warned) {
+      // eslint-disable-next-line no-console
+      console.warn(`[KJ_SIMULATE_QUOTA] Ignoring malformed value "${trigger}". Expected "after-iter-<N>".`);
+      _warned = true;
+    }
+    return null;
+  }
+  return {
+    afterIter: Number.parseInt(m[1], 10),
+    resetIso: env.KJ_SIMULATE_QUOTA_RESET || new Date(Date.now() + 3600_000).toISOString(),
+    agent: String(env.KJ_SIMULATE_QUOTA_AGENT || "claude").toLowerCase(),
+  };
+}
+
+const SYNTHETIC_MSG = {
+  claude: (iso) => `[KJ_SIMULATE_QUOTA] Claude Pro usage limit reached. weekly limit. resets at ${iso}`,
+  codex: () => `[KJ_SIMULATE_QUOTA] You have exceeded your current quota. retry after 60 seconds`,
+  gemini: () => `[KJ_SIMULATE_QUOTA] Resource exhausted: quota exceeded. retry after 60 seconds`,
+};
+
+export function buildSyntheticQuotaMessage(agent, resetIso) {
+  return (SYNTHETIC_MSG[agent] || SYNTHETIC_MSG.claude)(resetIso);
+}
+
+export function shouldSimulateQuota({ iteration, agent }, env = process.env) {
+  const cfg = parseQuotaSimulationConfig(env);
+  if (!cfg) return null;
+  if (Number(iteration) < cfg.afterIter) return null;
+  const a = String(agent || "").toLowerCase();
+  if (cfg.agent !== "any" && cfg.agent !== a) return null;
+  return { resetIso: cfg.resetIso, agent: a || cfg.agent };
+}
+
+// Mutates execResult: forces ok=false and prepends the synthetic quota
+// line to result.error so the existing detectRateLimit branch fires.
+export function applyQuotaSimulation(execResult, { iteration, agent }, env = process.env) {
+  const fire = shouldSimulateQuota({ iteration, agent }, env);
+  if (!fire || !execResult || typeof execResult !== "object") return false;
+  if (!execResult.result || typeof execResult.result !== "object") execResult.result = {};
+  execResult.result.error = `${buildSyntheticQuotaMessage(fire.agent, fire.resetIso)}\n${execResult.result.error || ""}`;
+  execResult.ok = false;
+  return true;
+}
+
+// Test seam — reset the one-shot warning between unit tests.
+export function _resetSimulatorWarning() { _warned = false; }