karajan-code 1.49.0 → 1.50.1

package/README.md

@@ -243,7 +243,7 @@ Not nostalgia, not stubbornness. I've been using JavaScript since 1997, when Bre
 git clone https://github.com/manufosela/karajan-code.git
 cd karajan-code
 npm install
-npm test              # Run 2318 tests with Vitest
+npm test              # Run ~2473 tests with Vitest
 npm run validate      # Lint + test
 ```
 

package/docs/README.es.md

@@ -213,7 +213,7 @@ No es nostalgia ni cabezoneria. Es que llevo usando JavaScript desde 1997, cuand
 git clone https://github.com/manufosela/karajan-code.git
 cd karajan-code
 npm install
-npm test              # Ejecutar 2318 tests con Vitest
+npm test              # Ejecutar ~2473 tests con Vitest
 npm run validate      # Lint + test
 ```
 

package/package.json

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

package/src/mcp/handlers/direct-handlers.js

@@ -0,0 +1,393 @@
+/**
+ * Direct role handler logic (code, review, plan, audit, discover, triage, researcher, architect, impeccable).
+ * Extracted from server-handlers.js for maintainability.
+ */
+
+import { EventEmitter } from "node:events";
+import fs from "node:fs/promises";
+import { resolveRole } from "../../config.js";
+import { createLogger } from "../../utils/logger.js";
+import { assertAgentsAvailable } from "../../agents/availability.js";
+import { createAgent } from "../../agents/index.js";
+import { buildPlannerPrompt } from "../../prompts/planner.js";
+import { buildCoderPrompt } from "../../prompts/coder.js";
+import { buildReviewerPrompt } from "../../prompts/reviewer.js";
+import { parseMaybeJsonString } from "../../review/parser.js";
+import { computeBaseRef, generateDiff } from "../../review/diff-generator.js";
+import { resolveReviewProfile } from "../../review/profiles.js";
+import { createRunLog } from "../../utils/run-log.js";
+import { createStallDetector } from "../../utils/stall-detector.js";
+import { sendTrackerLog } from "../progress.js";
+import { runDirectRole } from "../direct-role-runner.js";
+import { isPreflightAcked, ackPreflight, getSessionOverrides } from "../preflight.js";
+import { ensureBootstrap } from "../../bootstrap.js";
+import { loadConfig } from "../../config.js";
+import {
+  resolveProjectDir,
+  failPayload,
+  assertNotOnBaseBranch,
+  buildConfig,
+  buildDirectEmitter,
+} from "../server-handlers.js";
+
+/**
+ * Run bootstrap gate: validate all environment prerequisites before execution.
+ */
+async function runBootstrapGate(server, a) {
+  const projectDir = await resolveProjectDir(server, a.projectDir);
+  const { config } = await loadConfig(projectDir);
+  await ensureBootstrap(projectDir, config);
+}
+
+function applySessionOverrides(a, roleKeys) {
+  const sessionOvr = getSessionOverrides();
+  for (const key of roleKeys) {
+    if (sessionOvr[key] !== undefined) { a[key] = sessionOvr[key]; }
+  }
+}
+
+export async function handlePlanDirect(a, server, extra) {
+  const { normalizePlanArgs } = await import("../tool-arg-normalizers.js");
+  const options = normalizePlanArgs(a);
+  const config = await buildConfig(options, "plan");
+  const logger = createLogger(config.output.log_level, "mcp");
+
+  const plannerRole = resolveRole(config, "planner");
+  await assertAgentsAvailable([plannerRole.provider]);
+
+  const projectDir = await resolveProjectDir(server, a.projectDir);
+  const runLog = createRunLog(projectDir);
+  const silenceTimeoutMs = Number(config?.session?.max_agent_silence_minutes) > 0
+    ? Math.round(Number(config.session.max_agent_silence_minutes) * 60 * 1000)
+    : undefined;
+  const plannerTimeoutMs = Number(config?.session?.max_planner_minutes) > 0
+    ? Math.round(Number(config.session.max_planner_minutes) * 60 * 1000)
+    : undefined;
+  const silenceLabel = silenceTimeoutMs ? `${Math.round(silenceTimeoutMs / 1000)}s` : "disabled";
+  const runtimeLabel = plannerTimeoutMs ? `${Math.round(plannerTimeoutMs / 1000)}s` : "disabled";
+  runLog.logText(
+    `[kj_plan] started — provider=${plannerRole.provider}, max_silence=${silenceLabel}, max_runtime=${runtimeLabel}`
+  );
+  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: "planner", message: line, detail: { stream, agent: plannerRole.provider } });
+  };
+  const stallDetector = createStallDetector({
+    onOutput, emitter, eventBase, stage: "planner", provider: plannerRole.provider
+  });
+
+  const planner = createAgent(plannerRole.provider, config, logger);
+  const prompt = buildPlannerPrompt({ task: a.task, context: a.context });
+  sendTrackerLog(server, "planner", "running", plannerRole.provider);
+  runLog.logText(`[planner] agent launched, waiting for response...`);
+  let result;
+  let plannerStats = null;
+  try {
+    result = await planner.runTask({
+      prompt,
+      role: "planner",
+      onOutput: stallDetector.onOutput,
+      silenceTimeoutMs,
+      timeoutMs: plannerTimeoutMs
+    });
+  } finally {
+    stallDetector.stop();
+    plannerStats = stallDetector.stats();
+    runLog.logText(
+      `[planner] finished — lines=${plannerStats.lineCount}, bytes=${plannerStats.bytesReceived}, elapsed=${Math.round(plannerStats.elapsedMs / 1000)}s`
+    );
+    runLog.close();
+  }
+
+  if (!result.ok) {
+    sendTrackerLog(server, "planner", "failed");
+    const baseError = result.error || result.output || "Planner failed";
+    const statsSuffix = plannerStats
+      ? ` [lines=${plannerStats.lineCount}, bytes=${plannerStats.bytesReceived}, elapsed=${Math.round(plannerStats.elapsedMs / 1000)}s]`
+      : "";
+    throw new Error(`${baseError}${statsSuffix}`);
+  }
+
+  sendTrackerLog(server, "planner", "done");
+  const parsed = parseMaybeJsonString(result.output);
+  return { ok: true, plan: parsed || result.output, raw: result.output };
+}
+
+export async function handleCodeDirect(a, server, extra) {
+  const config = await buildConfig(a, "code");
+  await assertNotOnBaseBranch(config);
+  const logger = createLogger(config.output.log_level, "mcp");
+
+  const coderRole = resolveRole(config, "coder");
+  await assertAgentsAvailable([coderRole.provider]);
+
+  const projectDir = await resolveProjectDir(server, a.projectDir);
+  const runLog = createRunLog(projectDir);
+  runLog.logText(`[kj_code] started — provider=${coderRole.provider}`);
+  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: "coder", message: line, detail: { stream, agent: coderRole.provider } });
+  };
+  const stallDetector = createStallDetector({
+    onOutput, emitter, eventBase, stage: "coder", provider: coderRole.provider
+  });
+
+  const coder = createAgent(coderRole.provider, config, logger);
+  let coderRules = null;
+  if (config.coder_rules) {
+    try {
+      coderRules = await fs.readFile(config.coder_rules, "utf8");
+    } catch { /* configured coder_rules path not found */
+      try { coderRules = await fs.readFile("coder-rules.md", "utf8"); } catch { /* no coder rules file */ }
+    }
+  }
+  const prompt = await buildCoderPrompt({ task: a.task, coderRules, methodology: config.development?.methodology || "tdd" });
+  sendTrackerLog(server, "coder", "running", coderRole.provider);
+  runLog.logText(`[coder] agent launched, waiting for response...`);
+  let result;
+  try {
+    result = await coder.runTask({ prompt, role: "coder", onOutput: stallDetector.onOutput });
+  } finally {
+    stallDetector.stop();
+    const stats = stallDetector.stats();
+    runLog.logText(`[coder] finished — lines=${stats.lineCount}, bytes=${stats.bytesReceived}, elapsed=${Math.round(stats.elapsedMs / 1000)}s`);
+    runLog.close();
+  }
+
+  if (!result.ok) {
+    sendTrackerLog(server, "coder", "failed");
+    throw new Error(result.error || result.output || `Coder failed (exit ${result.exitCode})`);
+  }
+
+  sendTrackerLog(server, "coder", "done");
+  return { ok: true, output: result.output, exitCode: result.exitCode };
+}
+
+export async function handleReviewDirect(a, server, extra) {
+  const config = await buildConfig(a, "review");
+  await assertNotOnBaseBranch(config);
+  const logger = createLogger(config.output.log_level, "mcp");
+
+  const reviewerRole = resolveRole(config, "reviewer");
+  await assertAgentsAvailable([reviewerRole.provider, config.reviewer_options?.fallback_reviewer]);
+
+  const projectDir = await resolveProjectDir(server, a.projectDir);
+  const runLog = createRunLog(projectDir);
+  runLog.logText(`[kj_review] started — provider=${reviewerRole.provider}`);
+  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: "reviewer", message: line, detail: { stream, agent: reviewerRole.provider } });
+  };
+  const stallDetector = createStallDetector({
+    onOutput, emitter, eventBase, stage: "reviewer", provider: reviewerRole.provider
+  });
+
+  const reviewer = createAgent(reviewerRole.provider, config, logger);
+  const resolvedBase = await computeBaseRef({ baseBranch: config.base_branch, baseRef: a.baseRef });
+  const diff = await generateDiff({ baseRef: resolvedBase });
+  const { rules } = await resolveReviewProfile({ mode: config.review_mode, projectDir: process.cwd() });
+
+  const prompt = await buildReviewerPrompt({ task: a.task, diff, reviewRules: rules, mode: config.review_mode });
+  sendTrackerLog(server, "reviewer", "running", reviewerRole.provider);
+  runLog.logText(`[reviewer] agent launched, waiting for response...`);
+  let result;
+  try {
+    result = await reviewer.reviewTask({ prompt, role: "reviewer", onOutput: stallDetector.onOutput });
+  } finally {
+    stallDetector.stop();
+    const stats = stallDetector.stats();
+    runLog.logText(`[reviewer] finished — lines=${stats.lineCount}, bytes=${stats.bytesReceived}, elapsed=${Math.round(stats.elapsedMs / 1000)}s`);
+    runLog.close();
+  }
+
+  if (!result.ok) {
+    sendTrackerLog(server, "reviewer", "failed");
+    throw new Error(result.error || result.output || `Reviewer failed (exit ${result.exitCode})`);
+  }
+
+  sendTrackerLog(server, "reviewer", "done");
+  const parsed = parseMaybeJsonString(result.output);
+  return { ok: true, review: parsed || result.output, raw: result.output };
+}
+
+export async function handleDiscoverDirect(a, server, extra) {
+  // Build context from pgTask if provided
+  let context = a.context || null;
+  if (a.pgTask && a.pgProject) {
+    try {
+      const pgContext = `Planning Game card: ${a.pgTask} (project: ${a.pgProject})`;
+      context = context ? `${context}\n\n${pgContext}` : pgContext;
+    } catch { /* PG not available — proceed without */ }
+  }
+
+  return runDirectRole({
+    roleName: "discover",
+    importRole: async () => {
+      const { DiscoverRole } = await import("../../roles/discover-role.js");
+      return { RoleClass: DiscoverRole };
+    },
+    initContext: { task: a.task },
+    runInput: { task: a.task, mode: a.mode || "gaps", context },
+    logStartMsg: `[kj_discover] started — mode=${a.mode || "gaps"}`,
+    args: a, server, extra,
+    resolveProjectDir, buildConfig, buildDirectEmitter
+  });
+}
+
+export async function handleTriageDirect(a, server, extra) {
+  return runDirectRole({
+    roleName: "triage",
+    importRole: async () => {
+      const { TriageRole } = await import("../../roles/triage-role.js");
+      return { RoleClass: TriageRole };
+    },
+    initContext: { task: a.task },
+    runInput: { task: a.task },
+    args: a, server, extra,
+    resolveProjectDir, buildConfig, buildDirectEmitter
+  });
+}
+
+export async function handleResearcherDirect(a, server, extra) {
+  return runDirectRole({
+    roleName: "researcher",
+    importRole: async () => {
+      const { ResearcherRole } = await import("../../roles/researcher-role.js");
+      return { RoleClass: ResearcherRole };
+    },
+    initContext: { task: a.task },
+    runInput: { task: a.task },
+    args: a, server, extra,
+    resolveProjectDir, buildConfig, buildDirectEmitter
+  });
+}
+
+export async function handleAuditDirect(a, server, extra) {
+  const task = a.task || "Analyze the full codebase";
+  return runDirectRole({
+    roleName: "audit",
+    importRole: async () => {
+      const { AuditRole } = await import("../../roles/audit-role.js");
+      return { RoleClass: AuditRole };
+    },
+    initContext: { task },
+    runInput: { task, dimensions: a.dimensions || null },
+    logStartMsg: `[kj_audit] started — dimensions=${a.dimensions || "all"}`,
+    args: a, server, extra,
+    resolveProjectDir, buildConfig, buildDirectEmitter
+  });
+}
+
+export async function handleArchitectDirect(a, server, extra) {
+  return runDirectRole({
+    roleName: "architect",
+    importRole: async () => {
+      const { ArchitectRole } = await import("../../roles/architect-role.js");
+      return { RoleClass: ArchitectRole };
+    },
+    initContext: { task: a.task },
+    runInput: { task: a.task, researchContext: a.context || null },
+    args: a, server, extra,
+    resolveProjectDir, buildConfig, buildDirectEmitter
+  });
+}
+
+export async function handleCode(a, server, extra) {
+  if (!a.task) {
+    return failPayload("Missing required field: task");
+  }
+  await runBootstrapGate(server, a);
+  if (!isPreflightAcked()) {
+    // Auto-acknowledge with defaults for autonomous operation
+    ackPreflight({});
+    const logger = createLogger("info", "mcp");
+    logger.info("Preflight auto-acknowledged with default agent config");
+  }
+  applySessionOverrides(a, ["coder"]);
+  return handleCodeDirect(a, server, extra);
+}
+
+export async function handleReview(a, server, extra) {
+  if (!a.task) {
+    return failPayload("Missing required field: task");
+  }
+  await runBootstrapGate(server, a);
+  return handleReviewDirect(a, server, extra);
+}
+
+export async function handlePlan(a, server, extra) {
+  if (!a.task) {
+    return failPayload("Missing required field: task");
+  }
+  await runBootstrapGate(server, a);
+  return handlePlanDirect(a, server, extra);
+}
+
+export async function handleDiscover(a, server, extra) {
+  if (!a.task) {
+    return failPayload("Missing required field: task");
+  }
+  const validModes = new Set(["gaps", "momtest", "wendel", "classify", "jtbd"]);
+  if (a.mode && !validModes.has(a.mode)) {
+    return failPayload(`Invalid mode "${a.mode}". Valid values: ${[...validModes].join(", ")}`);
+  }
+  await runBootstrapGate(server, a);
+  return handleDiscoverDirect(a, server, extra);
+}
+
+export async function handleTriage(a, server, extra) {
+  if (!a.task) {
+    return failPayload("Missing required field: task");
+  }
+  await runBootstrapGate(server, a);
+  return handleTriageDirect(a, server, extra);
+}
+
+export async function handleResearcher(a, server, extra) {
+  if (!a.task) {
+    return failPayload("Missing required field: task");
+  }
+  await runBootstrapGate(server, a);
+  return handleResearcherDirect(a, server, extra);
+}
+
+export async function handleArchitect(a, server, extra) {
+  if (!a.task) {
+    return failPayload("Missing required field: task");
+  }
+  await runBootstrapGate(server, a);
+  return handleArchitectDirect(a, server, extra);
+}
+
+export async function handleAudit(a, server, extra) {
+  await runBootstrapGate(server, a);
+  const result = await handleAuditDirect(a, server, extra);
+
+  // Return compact summary for MCP (full details in session log)
+  if (result?.ok && result?.summary) {
+    const compact = {
+      ok: true,
+      overallHealth: result.summary?.overallHealth || result.summary,
+      totalFindings: result.summary?.totalFindings,
+      critical: result.summary?.critical,
+      high: result.summary?.high,
+      topRecommendations: (result.topRecommendations || []).slice(0, 5).map(r => ({
+        priority: r.priority,
+        dimension: r.dimension,
+        action: r.action,
+        impact: r.impact
+      })),
+      textSummary: result.textSummary || result.summary,
+      basalCost: result.basalCost ? {
+        totalLines: result.basalCost.totalLines,
+        totalFiles: result.basalCost.totalFiles,
+        dependencies: result.basalCost.dependencies
+      } : undefined
+    };
+    return { content: [{ type: "text", text: JSON.stringify(compact, null, 2) }] };
+  }
+  return result;
+}

package/src/mcp/handlers/hu-handlers.js

@@ -0,0 +1,93 @@
+/**
+ * HU, Skills, and Suggest handler logic.
+ * Extracted from server-handlers.js for maintainability.
+ */
+
+import { handleSuggestion } from "../suggest-handler.js";
+import {
+  resolveProjectDir,
+  failPayload,
+} from "../server-handlers.js";
+
+export async function handleHu(a, server) {
+  const action = a.action;
+  if (!action) return failPayload("Missing required field: action");
+
+  const projectDir = await resolveProjectDir(server, a.projectDir);
+  const { createManualHu, listHus, getHu, updateHuStatus } = await import("../../hu/store.js");
+
+  switch (action) {
+    case "create": {
+      if (!a.title) return failPayload("Missing required field: title (required for create)");
+      const hu = await createManualHu(projectDir, {
+        title: a.title,
+        description: a.description,
+        status: a.status,
+        acceptanceCriteria: a.acceptanceCriteria
+      });
+      return { ok: true, hu };
+    }
+    case "list": {
+      const hus = await listHus(projectDir);
+      return { ok: true, hus };
+    }
+    case "get": {
+      if (!a.huId) return failPayload("Missing required field: huId (required for get)");
+      const hu = await getHu(projectDir, a.huId);
+      return { ok: true, hu };
+    }
+    case "update": {
+      if (!a.huId) return failPayload("Missing required field: huId (required for update)");
+      if (!a.status) return failPayload("Missing required field: status (required for update)");
+      const hu = await updateHuStatus(projectDir, a.huId, a.status);
+      return { ok: true, hu };
+    }
+    default:
+      return failPayload(`Unknown hu action: ${action}`);
+  }
+}
+
+export async function handleSkills(a) {
+  const action = a.action;
+  if (!action) return failPayload("Missing required field: action");
+
+  const { isOpenSkillsAvailable, installSkill, removeSkill, listSkills, readSkill } =
+    await import("../../skills/openskills-client.js");
+
+  const opts = { projectDir: a.projectDir || null };
+
+  switch (action) {
+    case "install": {
+      if (!a.source) return failPayload("Missing required field: source (required for install)");
+      const available = await isOpenSkillsAvailable();
+      if (!available) {
+        return failPayload("OpenSkills CLI is not available. Install it with: npm install -g openskills");
+      }
+      return installSkill(a.source, { ...opts, global: a.global || false });
+    }
+    case "remove": {
+      if (!a.name) return failPayload("Missing required field: name (required for remove)");
+      return removeSkill(a.name, opts);
+    }
+    case "list": {
+      return listSkills(opts);
+    }
+    case "read": {
+      if (!a.name) return failPayload("Missing required field: name (required for read)");
+      return readSkill(a.name, opts);
+    }
+    default:
+      return failPayload(`Unknown skills action: ${action}`);
+  }
+}
+
+export async function handleSuggest(a) {
+  if (!a.suggestion) {
+    return failPayload("Missing required field: suggestion");
+  }
+  return handleSuggestion({
+    suggestion: a.suggestion,
+    context: a.context || null,
+    projectDir: a.projectDir || null
+  });
+}

package/src/mcp/handlers/management-handlers.js

@@ -0,0 +1,182 @@
+/**
+ * Management handler logic (init, doctor, config, scan, report, roles, agents, preflight, status, board).
+ * Extracted from server-handlers.js for maintainability.
+ */
+
+import { runKjCommand } from "../run-kj.js";
+import { loadConfig } from "../../config.js";
+import { readRunLog } from "../../utils/run-log.js";
+import { isPreflightAcked, ackPreflight, getSessionOverrides } from "../preflight.js";
+import { ensureBootstrap } from "../../bootstrap.js";
+import {
+  resolveProjectDir,
+  failPayload,
+  responseText,
+  buildConfig,
+} from "../server-handlers.js";
+
+const AGENT_ROLES = new Set(["coder", "reviewer", "tester", "security", "solomon"]);
+
+/**
+ * Run bootstrap gate: validate all environment prerequisites before execution.
+ */
+async function runBootstrapGate(server, a) {
+  const projectDir = await resolveProjectDir(server, a.projectDir);
+  const { config } = await loadConfig(projectDir);
+  await ensureBootstrap(projectDir, config);
+}
+
+export async function handleStatus(a, server) {
+  const maxLines = a.lines || 50;
+  const projectDir = await resolveProjectDir(server, a.projectDir);
+  return readRunLog(projectDir, maxLines);
+}
+
+export async function handleAgents(a) {
+  const action = a.action || "list";
+  if (action === "set") {
+    if (!a.role || !a.provider) {
+      return failPayload("Missing required fields: role and provider");
+    }
+    const { setAgent } = await import("../../commands/agents.js");
+    const result = await setAgent(a.role, a.provider, { global: false });
+    return { ok: true, ...result, message: `${result.role} now uses ${result.provider} (scope: ${result.scope})` };
+  }
+  const config = await buildConfig(a);
+  const { listAgents } = await import("../../commands/agents.js");
+  const sessionOvr = getSessionOverrides();
+  return { ok: true, agents: listAgents(config, sessionOvr) };
+}
+
+function parseHumanResponseOverrides(humanResponse, overrides) {
+  for (const role of AGENT_ROLES) {
+    const patterns = [
+      new RegExp(String.raw`use\s+(\w+)\s+(?:as|for)\s+${role}`, "i"),
+      new RegExp(String.raw`${role}\s*[:=]\s*(\w+)`, "i"),
+      new RegExp(String.raw`set\s+${role}\s+(?:to|=)\s*(\w+)`, "i")
+    ];
+    for (const pat of patterns) {
+      const m = pat.exec(humanResponse);
+      if (m && !overrides[role]) {
+        overrides[role] = m[1];
+        break;
+      }
+    }
+  }
+}
+
+function buildPreflightOverrides(a) {
+  const overrides = {};
+  for (const role of AGENT_ROLES) {
+    if (a[role]) overrides[role] = a[role];
+  }
+  if (a.enableTester !== undefined) overrides.enableTester = a.enableTester;
+  if (a.enableSecurity !== undefined) overrides.enableSecurity = a.enableSecurity;
+
+  const resp = (a.humanResponse || "").toLowerCase();
+  if (resp !== "ok") {
+    parseHumanResponseOverrides(a.humanResponse || "", overrides);
+  }
+  return overrides;
+}
+
+function formatPreflightConfig(agents, overrides) {
+  const lines = agents
+    .filter(ag => ag.provider !== "-")
+    .map(ag => {
+      const ovr = overrides[ag.role] ? ` -> ${overrides[ag.role]} (session override)` : "";
+      const modelSuffix = ag.model === "-" ? "" : ` (${ag.model})`;
+      return `  ${ag.role}: ${ag.provider}${modelSuffix}${ovr}`;
+    });
+  const overrideLines = Object.entries(overrides)
+    .filter(([k]) => !AGENT_ROLES.has(k))
+    .map(([k, v]) => `  ${k}: ${v}`);
+  return [...lines, ...overrideLines].join("\n");
+}
+
+export async function handlePreflight(a) {
+  const overrides = buildPreflightOverrides(a);
+  ackPreflight(overrides);
+
+  const config = await buildConfig(a);
+  const { listAgents } = await import("../../commands/agents.js");
+  const agents = listAgents(config);
+
+  return {
+    ok: true,
+    message: `Preflight acknowledged. Agent configuration confirmed.`,
+    config: formatPreflightConfig(agents, overrides),
+    overrides
+  };
+}
+
+export function handleRoles(a) {
+  const action = a.action || "list";
+  const commandArgs = [action];
+  if (action === "show" && a.roleName) commandArgs.push(a.roleName);
+  return runKjCommand({ command: "roles", commandArgs, options: a });
+}
+
+function buildReportArgs(a) {
+  const commandArgs = [];
+  if (a.list) commandArgs.push("--list");
+  if (a.sessionId) commandArgs.push("--session-id", String(a.sessionId));
+  if (a.format) commandArgs.push("--format", String(a.format));
+  if (a.trace) commandArgs.push("--trace");
+  if (a.currency) commandArgs.push("--currency", String(a.currency));
+  if (a.pgTask) commandArgs.push("--pg-task", String(a.pgTask));
+  return commandArgs;
+}
+
+export function handleReport(a) {
+  return runKjCommand({ command: "report", commandArgs: buildReportArgs(a), options: a });
+}
+
+export function handleInit(a) {
+  return runKjCommand({ command: "init", options: a });
+}
+
+export function handleDoctor(a) {
+  return runKjCommand({ command: "doctor", options: a });
+}
+
+export function handleConfig(a) {
+  return runKjCommand({ command: "config", commandArgs: a.json ? ["--json"] : [], options: a });
+}
+
+export async function handleScan(a, server) {
+  await runBootstrapGate(server, a);
+  return runKjCommand({ command: "scan", options: a });
+}
+
+export async function handleBoard(a) {
+  const action = a.action || "status";
+  const { loadConfig: lc } = await import("../../config.js");
+  const { config } = await lc();
+  const port = a.port || config.hu_board?.port || 4000;
+  const { startBoard, stopBoard, boardStatus } = await import("../../commands/board.js");
+  switch (action) {
+    case "start": return startBoard(port);
+    case "stop": return stopBoard();
+    case "status": return boardStatus(port);
+    default: return failPayload(`Unknown board action: ${action}`);
+  }
+}
+
+export async function buildPreflightRequiredResponse(toolName) {
+  const { config } = await loadConfig();
+  const { listAgents } = await import("../../commands/agents.js");
+  const agents = listAgents(config);
+  const agentSummary = agents
+    .filter(ag => ag.provider !== "-")
+    .map(ag => {
+      const modelSuffix = ag.model === "-" ? "" : ` (${ag.model})`;
+      return `  ${ag.role}: ${ag.provider}${modelSuffix}`;
+    })
+    .join("\n");
+  return responseText({
+    ok: false,
+    preflightRequired: true,
+    message: `PREFLIGHT REQUIRED\n\nCurrent agent configuration:\n${agentSummary}\n\nAsk the human to confirm or adjust this configuration, then call kj_preflight with their response.\n\nDo NOT pass coder/reviewer parameters to ${toolName} — use kj_preflight to set them.`
+  });
+}