karajan-code 1.49.0 → 1.50.1

package/src/mcp/server-handlers.js

@@ -1,38 +1,28 @@
 /**
  * MCP server handler logic.
- * Extracted from server.js for testability.
+ * Shared helpers remain here; handler implementations are in ./handlers/*.
+ * Re-exports everything so existing imports continue to work.
  */
 
 import { EventEmitter } from "node:events";
 import fs from "node:fs/promises";
-import { runKjCommand } from "./run-kj.js";
-import { normalizePlanArgs } from "./tool-arg-normalizers.js";
-import { buildProgressHandler, buildProgressNotifier, buildPipelineTracker, sendTrackerLog } from "./progress.js";
-import { createStallDetector } from "../utils/stall-detector.js";
-import { runDirectRole } from "./direct-role-runner.js";
-import { runFlow, resumeFlow } from "../orchestrator.js";
-import { loadConfig, applyRunOverrides, validateConfig, 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, readRunLog } from "../utils/run-log.js";
+import { loadConfig, applyRunOverrides, validateConfig } from "../config.js";
 import { currentBranch } from "../utils/git.js";
-import { isPreflightAcked, ackPreflight, getSessionOverrides } from "./preflight.js";
-import { ensureBootstrap } from "../bootstrap.js";
-import { validateSovereignty } from "./sovereignty-guard.js";
-import { handleSuggestion } from "./suggest-handler.js";
+import { buildProgressNotifier } from "./progress.js";
+
+// ── Sub-module re-exports ────────────────────────────────────────────
+export { handleRunDirect, handleResumeDirect, validateResumeAnswer, handleRun, handleResume } from "./handlers/run-handler.js";
+export { handlePlanDirect, handleCodeDirect, handleReviewDirect, handleDiscoverDirect, handleTriageDirect, handleResearcherDirect, handleAuditDirect, handleArchitectDirect, handleCode, handleReview, handlePlan, handleDiscover, handleTriage, handleResearcher, handleArchitect, handleAudit } from "./handlers/direct-handlers.js";
+export { handleStatus, handleAgents, handlePreflight, handleRoles, handleReport, handleInit, handleDoctor, handleConfig, handleScan, handleBoard, buildPreflightRequiredResponse } from "./handlers/management-handlers.js";
+export { handleHu, handleSkills, handleSuggest } from "./handlers/hu-handlers.js";
+
+// ── Shared helpers (used by sub-modules and external consumers) ──────
 
 /**
  * Resolve the user's project directory.
  * Priority: 1) explicit projectDir param, 2) MCP roots, 3) error with instructions.
  */
-async function resolveProjectDir(server, explicitProjectDir) {
+export async function resolveProjectDir(server, explicitProjectDir) {
   // 1. Explicit projectDir from tool parameter — always wins
   if (explicitProjectDir) return explicitProjectDir;
 
@@ -157,16 +147,6 @@ export async function assertNotOnBaseBranch(config) {
   }
 }
 
-/**
- * Run bootstrap gate: validate all environment prerequisites before execution.
- * Throws if any prerequisite fails.
- */
-async function runBootstrapGate(server, a) {
-  const projectDir = await resolveProjectDir(server, a.projectDir);
-  const { config } = await loadConfig(projectDir);
-  await ensureBootstrap(projectDir, config);
-}
-
 export function enrichedFailPayload(error, toolName) {
   const msg = error?.message || String(error);
   const { category, suggestion } = classifyError(error);
@@ -207,178 +187,12 @@ 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", "bootstrap_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 { /* no session store or read error */
-    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;
-  }
-}
-
-const PIPELINE_PROVIDER_ROLES = [
-  ["triage", true],
-  ["planner", true],
-  ["refactorer", true],
-  ["researcher", true],
-  ["tester", true],
-  ["security", true]
-];
-
-function collectRequiredProviders(config) {
-  const providers = [
-    resolveRole(config, "coder").provider,
-    config.reviewer_options?.fallback_reviewer
-  ];
-  if (config.pipeline?.reviewer?.enabled !== false) {
-    providers.push(resolveRole(config, "reviewer").provider);
-  }
-  for (const [role, requireEnabled] of PIPELINE_PROVIDER_ROLES) {
-    if (requireEnabled && config.pipeline?.[role]?.enabled) {
-      providers.push(resolveRole(config, role).provider);
-    }
-  }
-  return providers;
-}
-
-export async function handleRunDirect(a, server, extra) {
-  const config = await buildConfig(a);
-  await assertNotOnBaseBranch(config);
-  const logger = createLogger(config.output.log_level, "mcp");
-
-  // Best-effort session cleanup before starting
-  try {
-    const { cleanupExpiredSessions } = await import("../session-cleanup.js");
-    await cleanupExpiredSessions({ logger });
-  } catch { /* non-blocking */ }
-
-  await assertAgentsAvailable(collectRequiredProviders(config));
-
-  const projectDir = await resolveProjectDir(server, a.projectDir);
-  const runLog = createRunLog(projectDir);
-  runLog.logText(`[kj_run] started — task="${a.task.slice(0, 80)}..."`);
-
-  const emitter = new EventEmitter();
-  emitter.on("progress", buildProgressHandler(server));
-  emitter.on("progress", (event) => runLog.logEvent(event));
-  const progressNotifier = buildProgressNotifier(extra);
-  if (progressNotifier) emitter.on("progress", progressNotifier);
-  buildPipelineTracker(config, emitter);
-
-  const askQuestion = buildAskQuestion(server);
-  const pgTaskId = a.pgTask || null;
-  const pgProject = a.pgProject || config.planning_game?.project_id || null;
-  try {
-    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();
-  }
-}
-
-export async function handleResumeDirect(a, server, extra) {
-  const config = await buildConfig(a);
-  const logger = createLogger(config.output.log_level, "mcp");
-
-  const projectDir = await resolveProjectDir(server, a.projectDir);
-  const runLog = createRunLog(projectDir);
-  runLog.logText(`[kj_resume] started — session="${a.sessionId}"`);
-
-  const emitter = new EventEmitter();
-  emitter.on("progress", buildProgressHandler(server));
-  emitter.on("progress", (event) => runLog.logEvent(event));
-  const progressNotifier = buildProgressNotifier(extra);
-  if (progressNotifier) emitter.on("progress", progressNotifier);
-
-  const askQuestion = buildAskQuestion(server);
-  try {
-    const result = await resumeFlow({
-      sessionId: a.sessionId,
-      answer: a.answer || null,
-      config,
-      logger,
-      flags: a,
-      emitter,
-      askQuestion
-    });
-    const ok = !result.paused && (result.approved !== false);
-    runLog.logText(`[kj_resume] finished — ok=${ok}`);
-    return { ok, ...result };
-  } catch (err) {
-    runLog.logText(`[kj_resume] failed: ${err.message}`);
-    throw err;
-  } finally {
-    runLog.close();
-  }
-}
-
 const EVENT_LOG_LEVELS = {
   "agent:stall": "warning",
   "agent:heartbeat": "info"
 };
 
-function buildDirectEmitter(server, runLog, extra) {
+export function buildDirectEmitter(server, runLog, extra) {
   const emitter = new EventEmitter();
   emitter.on("progress", (event) => {
     try {
@@ -392,679 +206,35 @@ function buildDirectEmitter(server, runLog, extra) {
   return emitter;
 }
 
-export async function handlePlanDirect(a, server, extra) {
-  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
-  });
-}
-
-/* ── Preflight helpers ─────────────────────────────────────────────── */
-
-const AGENT_ROLES = new Set(["coder", "reviewer", "tester", "security", "solomon"]);
-
-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.`
-  });
-}
-
-function applySessionOverrides(a, roleKeys) {
-  const sessionOvr = getSessionOverrides();
-  for (const key of roleKeys) {
-    if (sessionOvr[key] !== undefined) { a[key] = sessionOvr[key]; }
-  }
-}
-
-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");
-}
-
-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;
-}
-
-/* ── Individual tool handlers ─────────────────────────────────────── */
-
-async function handleStatus(a, server) {
-  const maxLines = a.lines || 50;
-  const projectDir = await resolveProjectDir(server, a.projectDir);
-  return readRunLog(projectDir, maxLines);
-}
-
-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) };
-}
-
-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
-  };
-}
-
-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 });
-}
-
-const RESUME_MAX_ANSWER_LENGTH = 500;
-const RESUME_INJECTION_PATTERNS = [
-  /ignore\s+(previous|all|above)\s+(instructions|rules|prompts)/i,
-  /you\s+are\s+now/i,
-  /new\s+instructions?:/i,
-  /override\s+(all|security|guardrails|rules)/i,
-  /skip\s+(all\s+)?(review|test|sonar|security|solomon|guard)s?\b/i,
-  /disable\s+(tdd|review|test|sonar|security)\b/i,
-  /set\s+(status|approved|verdict)\s*(=|to|:)/i,
-  /force\s+(approve|merge|push|commit)\b/i,
-];
-
-export function validateResumeAnswer(answer) {
-  if (answer == null || answer === "") return { valid: true, sanitized: answer ?? null };
-  if (typeof answer !== "string") return { valid: true, sanitized: String(answer) };
-  if (answer.length > RESUME_MAX_ANSWER_LENGTH) {
-    return { valid: false, reason: `Answer too long (${answer.length} chars, max ${RESUME_MAX_ANSWER_LENGTH})` };
-  }
-  for (const pattern of RESUME_INJECTION_PATTERNS) {
-    if (pattern.test(answer)) {
-      return { valid: false, reason: "Answer rejected: matches guardrail bypass pattern" };
-    }
-  }
-  return { valid: true, sanitized: answer.trim() };
-}
-
-async function handleResume(a, server, extra) {
-  if (!a.sessionId) {
-    return failPayload("Missing required field: sessionId");
-  }
-  await runBootstrapGate(server, a);
-  if (a.answer) {
-    const validation = validateResumeAnswer(a.answer);
-    if (!validation.valid) {
-      return failPayload(`Resume answer rejected: ${validation.reason}`);
-    }
-    a.answer = validation.sanitized;
-  }
-  applySessionOverrides(a, ["coder", "reviewer", "tester", "security", "solomon", "enableTester", "enableSecurity", "enableImpeccable"]);
-  return handleResumeDirect(a, server, extra);
-}
-
-async function handleRun(a, server, extra) {
-  if (!a.task) {
-    return failPayload("Missing required field: task");
-  }
-  if (a.taskType) {
-    const validTypes = new Set(["sw", "infra", "doc", "add-tests", "refactor"]);
-    if (!validTypes.has(a.taskType)) {
-      return failPayload(`Invalid taskType "${a.taskType}". Valid values: ${[...validTypes].join(", ")}`);
-    }
-  }
-
-  // Sovereignty guard: sanitise params and check for active sessions
-  const projectDir = await resolveProjectDir(server, a.projectDir);
-  const sovereignty = validateSovereignty(a, { projectDir });
-  if (sovereignty.error) {
-    return failPayload(sovereignty.error);
-  }
-  if (sovereignty.warnings.length > 0) {
-    const logger = createLogger("info", "mcp");
-    for (const w of sovereignty.warnings) logger.warn(`[sovereignty] ${w}`);
-  }
-  Object.assign(a, sovereignty.params);
-
-  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", "reviewer", "tester", "security", "solomon", "enableTester", "enableSecurity", "enableImpeccable"]);
-  return handleRunDirect(a, server, extra);
-}
-
-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);
-}
-
-async function handleReview(a, server, extra) {
-  if (!a.task) {
-    return failPayload("Missing required field: task");
-  }
-  await runBootstrapGate(server, a);
-  return handleReviewDirect(a, server, extra);
-}
-
-async function handlePlan(a, server, extra) {
-  if (!a.task) {
-    return failPayload("Missing required field: task");
-  }
-  await runBootstrapGate(server, a);
-  return handlePlanDirect(a, server, extra);
-}
-
-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);
-}
-
-async function handleTriage(a, server, extra) {
-  if (!a.task) {
-    return failPayload("Missing required field: task");
-  }
-  await runBootstrapGate(server, a);
-  return handleTriageDirect(a, server, extra);
-}
-
-async function handleResearcher(a, server, extra) {
-  if (!a.task) {
-    return failPayload("Missing required field: task");
-  }
-  await runBootstrapGate(server, a);
-  return handleResearcherDirect(a, server, extra);
-}
-
-async function handleArchitect(a, server, extra) {
-  if (!a.task) {
-    return failPayload("Missing required field: task");
-  }
-  await runBootstrapGate(server, a);
-  return handleArchitectDirect(a, server, extra);
-}
-
-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;
-}
-
-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}`);
-  }
-}
-
-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}`);
-  }
-}
-
-async function handleScan(a, server) {
-  await runBootstrapGate(server, a);
-  return runKjCommand({ command: "scan", options: a });
-}
-
-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
-  });
-}
-
-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}`);
-  }
-}
+// ── Handler dispatch map (imports from sub-modules) ──────────────────
 
-/* ── Handler dispatch map ─────────────────────────────────────────── */
+import { handleRun, handleResume } from "./handlers/run-handler.js";
+import {
+  handleCode, handleReview, handlePlan, handleDiscover,
+  handleTriage, handleResearcher, handleArchitect, handleAudit
+} from "./handlers/direct-handlers.js";
+import {
+  handleStatus, handleAgents, handlePreflight, handleRoles,
+  handleReport, handleInit, handleDoctor, handleConfig,
+  handleScan, handleBoard
+} from "./handlers/management-handlers.js";
+import { handleHu, handleSkills, handleSuggest } from "./handlers/hu-handlers.js";
 
 const toolHandlers = {
-  kj_status:    (a, server) => handleStatus(a, server),
-  kj_init:      (a) => runKjCommand({ command: "init", options: a }),
-  kj_doctor:    (a) => runKjCommand({ command: "doctor", options: a }),
-  kj_agents:    (a) => handleAgents(a),
-  kj_preflight: (a) => handlePreflight(a),
-  kj_config:    (a) => runKjCommand({ command: "config", commandArgs: a.json ? ["--json"] : [], options: a }),
-  kj_scan:      (a, server) => handleScan(a, server),
-  kj_roles:     (a) => handleRoles(a),
-  kj_report:    (a) => runKjCommand({ command: "report", commandArgs: buildReportArgs(a), options: a }),
-  kj_resume:    (a, server, extra) => handleResume(a, server, extra),
-  kj_run:       (a, server, extra) => handleRun(a, server, extra),
-  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_status:      (a, server) => handleStatus(a, server),
+  kj_init:        (a) => handleInit(a),
+  kj_doctor:      (a) => handleDoctor(a),
+  kj_agents:      (a) => handleAgents(a),
+  kj_preflight:   (a) => handlePreflight(a),
+  kj_config:      (a) => handleConfig(a),
+  kj_scan:        (a, server) => handleScan(a, server),
+  kj_roles:       (a) => handleRoles(a),
+  kj_report:      (a) => handleReport(a),
+  kj_resume:      (a, server, extra) => handleResume(a, server, extra),
+  kj_run:         (a, server, extra) => handleRun(a, server, extra),
+  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_triage:      (a, server, extra) => handleTriage(a, server, extra),
   kj_researcher:  (a, server, extra) => handleResearcher(a, server, extra),