karajan-code 1.20.0 → 1.21.1

package/package.json

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

package/src/cli.js

@@ -97,6 +97,8 @@ program
   .option("--methodology <name>")
   .option("--no-auto-rebase")
   .option("--no-sonar")
+  .option("--enable-sonarcloud", "Enable SonarCloud scan (complementary to SonarQube)")
+  .option("--no-sonarcloud")
   .option("--checkpoint-interval <n>", "Minutes between interactive checkpoints (default: 5)")
   .option("--pg-task <cardId>", "Planning Game card ID (e.g., KJC-TSK-0042)")
   .option("--pg-project <projectId>", "Planning Game project ID")

package/src/commands/architect.js

@@ -3,56 +3,53 @@ import { assertAgentsAvailable } from "../agents/availability.js";
 import { resolveRole } from "../config.js";
 import { buildArchitectPrompt, parseArchitectOutput } from "../prompts/architect.js";
 
-function formatArchitect(result) {
-  const lines = [];
-  lines.push(`## Architecture Design`);
-  lines.push(`**Verdict:** ${result.verdict || "unknown"}`, "");
+function formatLayers(layers, lines) {
+  lines.push("### Layers");
+  for (const l of layers) {
+    lines.push(typeof l === "string" ? `- ${l}` : `- **${l.name}**: ${l.responsibility || ""}`);
+  }
+  lines.push("");
+}
 
-  const arch = result.architecture;
-  if (arch) {
-    if (arch.type) lines.push(`**Type:** ${arch.type}`, "");
+function formatTradeoffs(tradeoffs, lines) {
+  lines.push("### Tradeoffs");
+  for (const t of tradeoffs) {
+    lines.push(`- **${t.decision}**: ${t.rationale || ""}`);
+    if (t.alternatives?.length) lines.push(`  Alternatives: ${t.alternatives.join(", ")}`);
+  }
+  lines.push("");
+}
 
-    if (arch.layers?.length) {
-      lines.push("### Layers");
-      for (const l of arch.layers) {
-        if (typeof l === "string") {
-          lines.push(`- ${l}`);
-        } else {
-          lines.push(`- **${l.name}**: ${l.responsibility || ""}`);
-        }
-      }
-      lines.push("");
-    }
+function formatApiContracts(contracts, lines) {
+  lines.push("### API Contracts");
+  for (const c of contracts) {
+    lines.push(`- \`${c.method || "GET"} ${c.endpoint}\``);
+  }
+  lines.push("");
+}
 
-    if (arch.patterns?.length) {
-      lines.push("### Patterns");
-      for (const p of arch.patterns) lines.push(`- ${p}`);
-      lines.push("");
-    }
+function formatArchitecture(arch, lines) {
+  if (arch.type) lines.push(`**Type:** ${arch.type}`, "");
+  if (arch.layers?.length) formatLayers(arch.layers, lines);
+  if (arch.patterns?.length) {
+    lines.push("### Patterns");
+    for (const p of arch.patterns) lines.push(`- ${p}`);
+    lines.push("");
+  }
+  if (arch.tradeoffs?.length) formatTradeoffs(arch.tradeoffs, lines);
+  if (arch.apiContracts?.length) formatApiContracts(arch.apiContracts, lines);
+}
 
-    if (arch.tradeoffs?.length) {
-      lines.push("### Tradeoffs");
-      for (const t of arch.tradeoffs) {
-        lines.push(`- **${t.decision}**: ${t.rationale || ""}`);
-        if (t.alternatives?.length) lines.push(`  Alternatives: ${t.alternatives.join(", ")}`);
-      }
-      lines.push("");
-    }
+function formatArchitect(result) {
+  const lines = [];
+  lines.push(`## Architecture Design`);
+  lines.push(`**Verdict:** ${result.verdict || "unknown"}`, "");
 
-    if (arch.apiContracts?.length) {
-      lines.push("### API Contracts");
-      for (const c of arch.apiContracts) {
-        lines.push(`- \`${c.method || "GET"} ${c.endpoint}\``);
-      }
-      lines.push("");
-    }
-  }
+  if (result.architecture) formatArchitecture(result.architecture, lines);
 
   if (result.questions?.length) {
     lines.push("### Clarification Questions");
-    for (const q of result.questions) {
-      lines.push(`- ${q.question || q}`);
-    }
+    for (const q of result.questions) lines.push(`- ${q.question || q}`);
     lines.push("");
   }
 

package/src/commands/discover.js

@@ -2,57 +2,61 @@ import { createAgent } from "../agents/index.js";
 import { assertAgentsAvailable } from "../agents/availability.js";
 import { resolveRole } from "../config.js";
 import { buildDiscoverPrompt, parseDiscoverOutput } from "../prompts/discover.js";
-import { parseMaybeJsonString } from "../review/parser.js";
 
-function formatDiscover(result, mode) {
-  const lines = [];
-  lines.push(`## Discovery (${mode})`);
-  lines.push(`**Verdict:** ${result.verdict || "unknown"}`, "");
-
-  if (result.gaps?.length) {
-    lines.push("## Gaps");
-    for (const g of result.gaps) {
-      const sev = g.severity ? ` [${g.severity}]` : "";
-      lines.push(`- ${g.description || g}${sev}`);
-      if (g.suggestedQuestion) lines.push(`  → ${g.suggestedQuestion}`);
-    }
-    lines.push("");
+function formatGaps(gaps, lines) {
+  lines.push("## Gaps");
+  for (const g of gaps) {
+    const sev = g.severity ? ` [${g.severity}]` : "";
+    lines.push(`- ${g.description || g}${sev}`);
+    if (g.suggestedQuestion) lines.push(`  → ${g.suggestedQuestion}`);
   }
+  lines.push("");
+}
 
-  if (result.momTestQuestions?.length) {
-    lines.push("## Mom Test Questions");
-    for (const q of result.momTestQuestions) {
-      lines.push(`- ${q.question || q}`);
-      if (q.rationale) lines.push(`  _${q.rationale}_`);
-    }
-    lines.push("");
+function formatMomTest(questions, lines) {
+  lines.push("## Mom Test Questions");
+  for (const q of questions) {
+    lines.push(`- ${q.question || q}`);
+    if (q.rationale) lines.push(`  _${q.rationale}_`);
   }
+  lines.push("");
+}
 
-  if (result.wendelChecklist?.length) {
-    lines.push("## Wendel Checklist");
-    for (const w of result.wendelChecklist) {
-      const icon = w.status === "pass" ? "✓" : w.status === "fail" ? "✗" : "?";
-      lines.push(`- [${icon}] ${w.condition}: ${w.justification || ""}`);
-    }
-    lines.push("");
+function formatWendel(checklist, lines) {
+  lines.push("## Wendel Checklist");
+  for (const w of checklist) {
+    const icon = w.status === "pass" ? "✓" : w.status === "fail" ? "✗" : "?";
+    lines.push(`- [${icon}] ${w.condition}: ${w.justification || ""}`);
   }
+  lines.push("");
+}
 
-  if (result.classification) {
-    lines.push("## Classification");
-    lines.push(`- Type: ${result.classification.type}`);
-    if (result.classification.adoptionRisk) lines.push(`- Adoption risk: ${result.classification.adoptionRisk}`);
-    if (result.classification.frictionEstimate) lines.push(`- Friction: ${result.classification.frictionEstimate}`);
-    lines.push("");
-  }
+function formatClassification(classification, lines) {
+  lines.push("## Classification");
+  lines.push(`- Type: ${classification.type}`);
+  if (classification.adoptionRisk) lines.push(`- Adoption risk: ${classification.adoptionRisk}`);
+  if (classification.frictionEstimate) lines.push(`- Friction: ${classification.frictionEstimate}`);
+  lines.push("");
+}
 
-  if (result.jtbds?.length) {
-    lines.push("## Jobs-to-be-Done");
-    for (const j of result.jtbds) {
-      lines.push(`- **${j.id || ""}**: ${j.functional || j}`);
-    }
-    lines.push("");
+function formatJtbds(jtbds, lines) {
+  lines.push("## Jobs-to-be-Done");
+  for (const j of jtbds) {
+    lines.push(`- **${j.id || ""}**: ${j.functional || j}`);
   }
+  lines.push("");
+}
+
+function formatDiscover(result, mode) {
+  const lines = [];
+  lines.push(`## Discovery (${mode})`);
+  lines.push(`**Verdict:** ${result.verdict || "unknown"}`, "");
 
+  if (result.gaps?.length) formatGaps(result.gaps, lines);
+  if (result.momTestQuestions?.length) formatMomTest(result.momTestQuestions, lines);
+  if (result.wendelChecklist?.length) formatWendel(result.wendelChecklist, lines);
+  if (result.classification) formatClassification(result.classification, lines);
+  if (result.jtbds?.length) formatJtbds(result.jtbds, lines);
   if (result.summary) lines.push(`---\n${result.summary}`);
   return lines.join("\n");
 }

package/src/config.js

@@ -101,6 +101,18 @@ const DEFAULTS = {
       disabled_rules: ["javascript:S1116", "javascript:S3776"]
     }
   },
+  sonarcloud: {
+    enabled: false,
+    organization: null,
+    token: null,
+    project_key: null,
+    host: "https://sonarcloud.io",
+    scanner: {
+      sources: "src,public,lib",
+      exclusions: "**/node_modules/**,**/dist/**,**/build/**,**/*.min.js",
+      test_inclusions: "**/*.test.js,**/*.spec.js,**/tests/**,**/__tests__/**"
+    }
+  },
   policies: {},
   serena: { enabled: false },
   planning_game: { enabled: false, project_id: null, codeveloper: null },
@@ -129,6 +141,7 @@ const DEFAULTS = {
     max_reviewer_retries: 3,
     max_tester_retries: 1,
     max_security_retries: 1,
+    max_auto_resumes: 2,
     expiry_days: 30
   },
   failFast: {
@@ -347,6 +360,9 @@ function applyBecariaOverride(out, flags) {
 
 function applyMiscOverrides(out, flags) {
   if (flags.noSonar || flags.sonar === false) out.sonarqube.enabled = false;
+  out.sonarcloud = out.sonarcloud || {};
+  if (flags.enableSonarcloud === true) out.sonarcloud.enabled = true;
+  if (flags.noSonarcloud === true || flags.sonarcloud === false) out.sonarcloud.enabled = false;
 
   out.planning_game = out.planning_game || {};
   if (flags.pgTask) out.planning_game.enabled = true;

package/src/mcp/server-handlers.js

@@ -171,6 +171,69 @@ export function buildAskQuestion(server) {
   };
 }
 
+const MAX_AUTO_RESUMES = 2;
+const NON_RECOVERABLE_CATEGORIES = new Set([
+  "config_error", "auth_error", "agent_missing", "branch_error", "git_error"
+]);
+
+async function attemptAutoResume({ err, config, logger, emitter, askQuestion, runLog }) {
+  const { category } = classifyError(err);
+  if (NON_RECOVERABLE_CATEGORIES.has(category)) return null;
+
+  // Find session ID from most recent session file
+  const { loadMostRecentSession } = await import("../session-store.js");
+  let session;
+  try {
+    session = await loadMostRecentSession();
+  } catch {
+    return null;
+  }
+  if (!session || !["failed", "stopped"].includes(session.status)) return null;
+
+  const maxRetries = config.session?.max_auto_resumes ?? MAX_AUTO_RESUMES;
+  const autoResumeCount = session.auto_resume_count || 0;
+  if (autoResumeCount >= maxRetries) {
+    runLog.logText(`[resilient] auto-resume limit reached (${maxRetries}), giving up`);
+    return null;
+  }
+
+  runLog.logText(`[resilient] run failed (${category}), auto-resuming (${autoResumeCount + 1}/${maxRetries})...`);
+  emitter.emit("progress", {
+    type: "resilient:auto_resume",
+    attempt: autoResumeCount + 1,
+    maxRetries,
+    errorCategory: category,
+    sessionId: session.id
+  });
+
+  // Increment counter and save before resuming
+  const { saveSession } = await import("../session-store.js");
+  session.auto_resume_count = autoResumeCount + 1;
+  await saveSession(session);
+
+  try {
+    const result = await resumeFlow({
+      sessionId: session.id,
+      config,
+      logger,
+      flags: {},
+      emitter,
+      askQuestion
+    });
+    const ok = !result.paused && (result.approved !== false);
+    runLog.logText(`[resilient] auto-resume ${ok ? "succeeded" : "finished"} — ok=${ok}`);
+    return { ok, ...result, autoResumed: true, autoResumeAttempt: autoResumeCount + 1 };
+  } catch (error) {
+    // Recursive: try again if still within limits
+    const nestedResult = await attemptAutoResume({
+      err: error, config, logger, emitter, askQuestion, runLog
+    });
+    if (nestedResult) return nestedResult;
+    runLog.logText(`[resilient] auto-resume failed: ${error.message}`);
+    return null;
+  }
+}
+
 export async function handleRunDirect(a, server, extra) {
   const config = await buildConfig(a);
   await assertNotOnBaseBranch(config);
@@ -209,6 +272,12 @@ export async function handleRunDirect(a, server, extra) {
     const result = await runFlow({ task: a.task, config, logger, flags: a, emitter, askQuestion, pgTaskId, pgProject });
     runLog.logText(`[kj_run] finished — ok=${!result.paused && (result.approved !== false)}`);
     return { ok: !result.paused && (result.approved !== false), ...result };
+  } catch (err) {
+    const autoResumeResult = await attemptAutoResume({
+      err, config, logger, emitter, askQuestion, runLog, progressNotifier, extra
+    });
+    if (autoResumeResult) return autoResumeResult;
+    throw err;
   } finally {
     runLog.close();
   }
@@ -469,6 +538,138 @@ export async function handleDiscoverDirect(a, server, extra) {
   return { ok: true, ...result.result, summary: result.summary };
 }
 
+export async function handleTriageDirect(a, server, extra) {
+  const config = await buildConfig(a, "triage");
+  const logger = createLogger(config.output.log_level, "mcp");
+
+  const triageRole = resolveRole(config, "triage");
+  await assertAgentsAvailable([triageRole.provider]);
+
+  const projectDir = await resolveProjectDir(server);
+  const runLog = createRunLog(projectDir);
+  runLog.logText(`[kj_triage] started`);
+  const emitter = buildDirectEmitter(server, runLog, extra);
+  const eventBase = { sessionId: null, iteration: 0, startedAt: Date.now() };
+  const onOutput = ({ stream, line }) => {
+    emitter.emit("progress", { type: "agent:output", stage: "triage", message: line, detail: { stream, agent: triageRole.provider } });
+  };
+  const stallDetector = createStallDetector({
+    onOutput, emitter, eventBase, stage: "triage", provider: triageRole.provider
+  });
+
+  const { TriageRole } = await import("../roles/triage-role.js");
+  const triage = new TriageRole({ config, logger, emitter });
+  await triage.init({ task: a.task });
+
+  sendTrackerLog(server, "triage", "running", triageRole.provider);
+  runLog.logText(`[triage] agent launched, waiting for response...`);
+  let result;
+  try {
+    result = await triage.run({ task: a.task, onOutput: stallDetector.onOutput });
+  } finally {
+    stallDetector.stop();
+    const stats = stallDetector.stats();
+    runLog.logText(`[triage] finished — lines=${stats.lineCount}, bytes=${stats.bytesReceived}, elapsed=${Math.round(stats.elapsedMs / 1000)}s`);
+    runLog.close();
+  }
+
+  if (!result.ok) {
+    sendTrackerLog(server, "triage", "failed");
+    throw new Error(result.result?.error || result.summary || "Triage failed");
+  }
+
+  sendTrackerLog(server, "triage", "done");
+  return { ok: true, ...result.result, summary: result.summary };
+}
+
+export async function handleResearcherDirect(a, server, extra) {
+  const config = await buildConfig(a, "researcher");
+  const logger = createLogger(config.output.log_level, "mcp");
+
+  const researcherRole = resolveRole(config, "researcher");
+  await assertAgentsAvailable([researcherRole.provider]);
+
+  const projectDir = await resolveProjectDir(server);
+  const runLog = createRunLog(projectDir);
+  runLog.logText(`[kj_researcher] started`);
+  const emitter = buildDirectEmitter(server, runLog, extra);
+  const eventBase = { sessionId: null, iteration: 0, startedAt: Date.now() };
+  const onOutput = ({ stream, line }) => {
+    emitter.emit("progress", { type: "agent:output", stage: "researcher", message: line, detail: { stream, agent: researcherRole.provider } });
+  };
+  const stallDetector = createStallDetector({
+    onOutput, emitter, eventBase, stage: "researcher", provider: researcherRole.provider
+  });
+
+  const { ResearcherRole } = await import("../roles/researcher-role.js");
+  const researcher = new ResearcherRole({ config, logger, emitter });
+  await researcher.init({ task: a.task });
+
+  sendTrackerLog(server, "researcher", "running", researcherRole.provider);
+  runLog.logText(`[researcher] agent launched, waiting for response...`);
+  let result;
+  try {
+    result = await researcher.run({ task: a.task, onOutput: stallDetector.onOutput });
+  } finally {
+    stallDetector.stop();
+    const stats = stallDetector.stats();
+    runLog.logText(`[researcher] finished — lines=${stats.lineCount}, bytes=${stats.bytesReceived}, elapsed=${Math.round(stats.elapsedMs / 1000)}s`);
+    runLog.close();
+  }
+
+  if (!result.ok) {
+    sendTrackerLog(server, "researcher", "failed");
+    throw new Error(result.result?.error || result.summary || "Researcher failed");
+  }
+
+  sendTrackerLog(server, "researcher", "done");
+  return { ok: true, ...result.result, summary: result.summary };
+}
+
+export async function handleArchitectDirect(a, server, extra) {
+  const config = await buildConfig(a, "architect");
+  const logger = createLogger(config.output.log_level, "mcp");
+
+  const architectRole = resolveRole(config, "architect");
+  await assertAgentsAvailable([architectRole.provider]);
+
+  const projectDir = await resolveProjectDir(server);
+  const runLog = createRunLog(projectDir);
+  runLog.logText(`[kj_architect] started`);
+  const emitter = buildDirectEmitter(server, runLog, extra);
+  const eventBase = { sessionId: null, iteration: 0, startedAt: Date.now() };
+  const onOutput = ({ stream, line }) => {
+    emitter.emit("progress", { type: "agent:output", stage: "architect", message: line, detail: { stream, agent: architectRole.provider } });
+  };
+  const stallDetector = createStallDetector({
+    onOutput, emitter, eventBase, stage: "architect", provider: architectRole.provider
+  });
+
+  const { ArchitectRole } = await import("../roles/architect-role.js");
+  const architect = new ArchitectRole({ config, logger, emitter });
+  await architect.init({ task: a.task });
+
+  sendTrackerLog(server, "architect", "running", architectRole.provider);
+  runLog.logText(`[architect] agent launched, waiting for response...`);
+  let result;
+  try {
+    result = await architect.run({ task: a.task, researchContext: a.context || null, onOutput: stallDetector.onOutput });
+  } finally {
+    stallDetector.stop();
+    const stats = stallDetector.stats();
+    runLog.logText(`[architect] finished — lines=${stats.lineCount}, bytes=${stats.bytesReceived}, elapsed=${Math.round(stats.elapsedMs / 1000)}s`);
+    runLog.close();
+  }
+
+  if (!result.ok) {
+    sendTrackerLog(server, "architect", "failed");
+    throw new Error(result.result?.error || result.summary || "Architect failed");
+  }
+
+  sendTrackerLog(server, "architect", "done");
+  return { ok: true, ...result.result, summary: result.summary };
+}
+
 /* ── Preflight helpers ─────────────────────────────────────────────── */
 
 const AGENT_ROLES = new Set(["coder", "reviewer", "tester", "security", "solomon"]);
@@ -662,6 +863,27 @@ async function handleDiscover(a, server, extra) {
   return handleDiscoverDirect(a, server, extra);
 }
 
+async function handleTriage(a, server, extra) {
+  if (!a.task) {
+    return failPayload("Missing required field: task");
+  }
+  return handleTriageDirect(a, server, extra);
+}
+
+async function handleResearcher(a, server, extra) {
+  if (!a.task) {
+    return failPayload("Missing required field: task");
+  }
+  return handleResearcherDirect(a, server, extra);
+}
+
+async function handleArchitect(a, server, extra) {
+  if (!a.task) {
+    return failPayload("Missing required field: task");
+  }
+  return handleArchitectDirect(a, server, extra);
+}
+
 /* ── Handler dispatch map ─────────────────────────────────────────── */
 
 const toolHandlers = {
@@ -679,7 +901,10 @@ const toolHandlers = {
   kj_code:      (a, server, extra) => handleCode(a, server, extra),
   kj_review:    (a, server, extra) => handleReview(a, server, extra),
   kj_plan:      (a, server, extra) => handlePlan(a, server, extra),
-  kj_discover:  (a, server, extra) => handleDiscover(a, server, extra)
+  kj_discover:    (a, server, extra) => handleDiscover(a, server, extra),
+  kj_triage:      (a, server, extra) => handleTriage(a, server, extra),
+  kj_researcher:  (a, server, extra) => handleResearcher(a, server, extra),
+  kj_architect:   (a, server, extra) => handleArchitect(a, server, extra)
 };
 
 export async function handleToolCall(name, args, server, extra) {

package/src/mcp/tools.js

@@ -93,6 +93,7 @@ export const tools = [
         checkpointInterval: { type: "number", description: "Minutes between interactive checkpoints (default: 5). Set 0 to disable." },
         taskType: { type: "string", enum: ["sw", "infra", "doc", "add-tests", "refactor"], description: "Explicit task type for policy resolution. Overrides triage classification." },
         noSonar: { type: "boolean" },
+        enableSonarcloud: { type: "boolean", description: "Enable SonarCloud scan (complementary to SonarQube)" },
         kjHome: { type: "string" },
         sonarToken: { type: "string" },
         timeoutMs: { type: "number" }
@@ -242,5 +243,42 @@ export const tools = [
         kjHome: { type: "string" }
       }
     }
+  },
+  {
+    name: "kj_triage",
+    description: "Classify task complexity and recommend which pipeline roles to activate. Returns level (trivial/simple/medium/complex), taskType, recommended roles, and optional decomposition.",
+    inputSchema: {
+      type: "object",
+      required: ["task"],
+      properties: {
+        task: { type: "string", description: "Task description to classify" },
+        kjHome: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "kj_researcher",
+    description: "Research the codebase for a task. Identifies affected files, patterns, constraints, prior decisions, risks, and test coverage.",
+    inputSchema: {
+      type: "object",
+      required: ["task"],
+      properties: {
+        task: { type: "string", description: "Task description to research" },
+        kjHome: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "kj_architect",
+    description: "Design solution architecture for a task. Returns layers, patterns, data model, API contracts, tradeoffs, and a verdict (ready/needs_clarification).",
+    inputSchema: {
+      type: "object",
+      required: ["task"],
+      properties: {
+        task: { type: "string", description: "Task description to architect" },
+        context: { type: "string", description: "Additional context (e.g., researcher output)" },
+        kjHome: { type: "string" }
+      }
+    }
   }
 ];

package/src/orchestrator/iteration-stages.js

@@ -427,6 +427,47 @@ export async function runSonarStage({ config, logger, emitter, eventBase, sessio
   return { action: "ok", stageResult };
 }
 
+export async function runSonarCloudStage({ config, logger, emitter, eventBase, session, trackBudget, iteration }) {
+  logger.setContext({ iteration, stage: "sonarcloud" });
+  emitProgress(
+    emitter,
+    makeEvent("sonarcloud:start", { ...eventBase, stage: "sonarcloud" }, {
+      message: "SonarCloud scanning"
+    })
+  );
+
+  const { runSonarCloudScan } = await import("../sonar/cloud-scanner.js");
+  const scanStart = Date.now();
+  const result = await runSonarCloudScan(config);
+  trackBudget({ role: "sonarcloud", provider: "sonarcloud", result: { ok: result.ok }, duration_ms: Date.now() - scanStart });
+
+  await addCheckpoint(session, {
+    stage: "sonarcloud",
+    iteration,
+    project_key: result.projectKey,
+    exitCode: result.exitCode,
+    provider: "sonarcloud",
+    model: null
+  });
+
+  const status = result.ok ? "ok" : "warn";
+  const message = result.ok
+    ? `SonarCloud scan passed (project: ${result.projectKey})`
+    : `SonarCloud scan issue: ${(result.stderr || "").slice(0, 200)}`;
+
+  emitProgress(
+    emitter,
+    makeEvent("sonarcloud:end", { ...eventBase, stage: "sonarcloud" }, {
+      status,
+      message,
+      detail: { projectKey: result.projectKey, exitCode: result.exitCode }
+    })
+  );
+
+  // SonarCloud is advisory — never blocks the pipeline
+  return { action: "ok", stageResult: { ok: result.ok, projectKey: result.projectKey, message } };
+}
+
 async function handleReviewerStalledSolomon({ review, repeatCounts, repeatState, config, logger, emitter, eventBase, session, iteration, task, askQuestion, budgetSummary, repeatDetector }) {
   logger.warn(`Reviewer stalled (${repeatCounts.reviewer} repeats). Invoking Solomon mediation.`);
   emitProgress(

package/src/orchestrator.js

@@ -30,7 +30,7 @@ import { resolveReviewProfile } from "./review/profiles.js";
 import { CoderRole } from "./roles/coder-role.js";
 import { invokeSolomon } from "./orchestrator/solomon-escalation.js";
 import { runTriageStage, runResearcherStage, runArchitectStage, runPlannerStage, runDiscoverStage } from "./orchestrator/pre-loop-stages.js";
-import { runCoderStage, runRefactorerStage, runTddCheckStage, runSonarStage, runReviewerStage } from "./orchestrator/iteration-stages.js";
+import { runCoderStage, runRefactorerStage, runTddCheckStage, runSonarStage, runSonarCloudStage, runReviewerStage } from "./orchestrator/iteration-stages.js";
 import { runTesterStage, runSecurityStage } from "./orchestrator/post-loop-stages.js";
 import { waitForCooldown, MAX_STANDBY_RETRIES } from "./orchestrator/standby.js";
 
@@ -910,6 +910,15 @@ async function runQualityGateStages({ config, logger, emitter, eventBase, sessio
     }
   }
 
+  if (config.sonarcloud?.enabled) {
+    const cloudResult = await runSonarCloudStage({
+      config, logger, emitter, eventBase, session, trackBudget, iteration: i
+    });
+    if (cloudResult.stageResult) {
+      stageResults.sonarcloud = cloudResult.stageResult;
+    }
+  }
+
   return { action: "ok" };
 }
 

package/src/session-store.js

@@ -63,6 +63,24 @@ export async function pauseSession(session, { question, context: pauseContext })
   await saveSession(session);
 }
 
+export async function loadMostRecentSession() {
+  let entries;
+  try {
+    entries = await fs.readdir(SESSION_ROOT, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+  const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort();
+  for (let i = dirs.length - 1; i >= 0; i--) {
+    try {
+      return await loadSession(dirs[i]);
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
 export async function resumeSessionWithAnswer(sessionId, answer) {
   const session = await loadSession(sessionId);
   if (session.status !== "paused") {

package/src/sonar/cloud-scanner.js

@@ -0,0 +1,76 @@
+import { runCommand } from "../utils/process.js";
+import { resolveSonarProjectKey } from "./project-key.js";
+
+function buildCloudScannerArgs(projectKey, config) {
+  const sc = config.sonarcloud || {};
+  const scanner = sc.scanner || {};
+  const host = sc.host || "https://sonarcloud.io";
+  const token = process.env.KJ_SONARCLOUD_TOKEN || sc.token;
+  const organization = process.env.KJ_SONARCLOUD_ORG || sc.organization;
+
+  const args = [
+    `-Dsonar.host.url=${host}`,
+    `-Dsonar.projectKey=${projectKey}`
+  ];
+
+  if (token) args.push(`-Dsonar.token=${token}`);
+  if (organization) args.push(`-Dsonar.organization=${organization}`);
+  if (scanner.sources) args.push(`-Dsonar.sources=${scanner.sources}`);
+  if (scanner.exclusions) args.push(`-Dsonar.exclusions=${scanner.exclusions}`);
+  if (scanner.test_inclusions) args.push(`-Dsonar.test.inclusions=${scanner.test_inclusions}`);
+
+  return args;
+}
+
+export async function runSonarCloudScan(config, projectKey = null) {
+  const sc = config.sonarcloud || {};
+  const token = process.env.KJ_SONARCLOUD_TOKEN || sc.token;
+  const organization = sc.organization || process.env.KJ_SONARCLOUD_ORG;
+
+  if (!token) {
+    return {
+      ok: false,
+      projectKey: null,
+      stdout: "",
+      stderr: "SonarCloud token not configured. Set sonarcloud.token in kj.config.yml or KJ_SONARCLOUD_TOKEN env var.",
+      exitCode: 1
+    };
+  }
+
+  if (!organization) {
+    return {
+      ok: false,
+      projectKey: null,
+      stdout: "",
+      stderr: "SonarCloud organization not configured. Set sonarcloud.organization in kj.config.yml or KJ_SONARCLOUD_ORG env var.",
+      exitCode: 1
+    };
+  }
+
+  let effectiveProjectKey;
+  try {
+    effectiveProjectKey = projectKey || sc.project_key || await resolveSonarProjectKey(config, { projectKey });
+  } catch (error) {
+    return {
+      ok: false,
+      projectKey: null,
+      stdout: "",
+      stderr: error?.message || String(error),
+      exitCode: 1
+    };
+  }
+
+  const scannerTimeout = 15 * 60 * 1000;
+  const args = buildCloudScannerArgs(effectiveProjectKey, config);
+
+  // Use npx @sonar/scan (no Docker needed)
+  const result = await runCommand("npx", ["@sonar/scan", ...args], { timeout: scannerTimeout });
+
+  return {
+    ok: result.exitCode === 0,
+    projectKey: effectiveProjectKey,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    exitCode: result.exitCode
+  };
+}

package/src/utils/run-log.js

@@ -183,13 +183,15 @@ export function readRunLog(projectDir, maxLines = 50) {
     const total = lines.length;
     const shown = lines.slice(-maxLines);
     const status = parseRunStatus(lines);
+    const MAX_LINE_CHARS = 2000;
+    const truncated = shown.map(l => l.length > MAX_LINE_CHARS ? l.slice(0, MAX_LINE_CHARS) + "… [truncated]" : l);
     return {
       ok: true,
       path: logPath,
       totalLines: total,
       status,
-      lines: shown,
-      summary: shown.join("\n")
+      lines: truncated,
+      summary: truncated.join("\n")
     };
   } catch (err) {
     return {