@karajan-family/code 4.21.0

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

@@ -0,0 +1,265 @@
+/**
+ * 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 { ackPreflight, getSessionOverrides } from "../preflight.js";
+import { ensureBootstrap } from "../../bootstrap.js";
+import {
+  resolveProjectDir,
+  failPayload,
+  responseText,
+  buildConfig,
+} from "../shared-helpers.js";
+import { buildDashboardJson } from "../../utils/status-dashboard.js";
+import { loadMostRecentSession } from "../../session/store.js";
+import { escapeRegExp } from "../../utils/escape-regexp.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);
+  const logResult = readRunLog(projectDir, maxLines);
+
+  // Enrich with dashboard data when possible
+  try {
+    const session = await loadMostRecentSession();
+    const stories = [];
+    if (session) {
+      try {
+        const { loadHuBatch } = await import("../../hu/store.js");
+        const batch = await loadHuBatch(session.id);
+        if (batch?.stories) stories.push(...batch.stories);
+      } catch { /* no HU batch for this session */ }
+    }
+
+    const dashboard = buildDashboardJson(session, logResult.lines || [], { stories });
+    return { ...logResult, dashboard };
+  } catch {
+    // Fallback: return raw log without dashboard
+    return logResult;
+  }
+}
+
+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+${escapeRegExp(role)}`, "i"),
+      new RegExp(String.raw`${escapeRegExp(role)}\s*[:=]\s*(\w+)`, "i"),
+      new RegExp(String.raw`set\s+${escapeRegExp(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 = {}) {
+  const commandArgs = [];
+  if (a.checkOnly) commandArgs.push("--check-only");
+  if (a.yes) commandArgs.push("--yes");
+  if (a.json) commandArgs.push("--json");
+  if (a.verbose) commandArgs.push("--verbose");
+  return runKjCommand({ command: "doctor", commandArgs, 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";
+  // TSK-0340: loadConfig is already statically imported at the top.
+  const { config } = await loadConfig();
+  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 handleUndo(a, server) {
+  const projectDir = await resolveProjectDir(server, a.projectDir);
+  const origCwd = process.cwd();
+  try {
+    process.chdir(projectDir);
+    const { undoCommand } = await import("../../commands/undo.js");
+    return undoCommand({ hard: !!a.hard });
+  } finally {
+    process.chdir(origCwd);
+  }
+}
+
+/**
+ * Garbage-collect stale Karajan state. Routed here (not through the
+ * generic `runKjCommand`) because the user needs a structured result
+ * payload: MCP clients (Claude Desktop, Cursor, …) render lists, not
+ * ANSI-styled stdout. Shared implementation lives in
+ * `src/utils/garbage-collector.js` so CLI and MCP stay in sync.
+ */
+export async function handleClean(a) {
+  const { runManualGC, nukeBoardDb, summarizeGC } = await import("../../utils/garbage-collector.js");
+
+  const dryRun = !a?.yes;
+  const retention = a?.nuke
+    ? { planRetentionDays: 0, draftRetentionDays: 0, sessionRetentionDays: 0, huRetentionDays: 0 }
+    : {
+      planRetentionDays: a?.planDays,
+      draftRetentionDays: a?.draftDays,
+      sessionRetentionDays: a?.sessionDays,
+      huRetentionDays: a?.huDays,
+    };
+
+  const result = await runManualGC({ ...retention, dryRun });
+  if (a?.nuke) {
+    const boardResult = await nukeBoardDb({ dryRun });
+    result.removed.push(...boardResult.removed);
+    result.bytesFreed += boardResult.bytesFreed;
+    result.errors.push(...boardResult.errors);
+  }
+
+  const byKind = {};
+  for (const r of result.removed) byKind[r.kind] = (byKind[r.kind] || 0) + 1;
+
+  return {
+    ok: true,
+    dryRun,
+    nuke: Boolean(a?.nuke),
+    removed: result.removed.length,
+    bytesFreed: result.bytesFreed,
+    breakdown: byKind,
+    items: result.removed.map((r) => ({ path: r.path, kind: r.kind, reason: r.reason })),
+    errors: result.errors,
+    summary: summarizeGC(result) || "[clean] nothing to clean — ~/.kj/ and ~/.karajan/ are tidy.",
+  };
+}
+
+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.`
+  });
+}

package/src/mcp/handlers/rag-handler.js

@@ -0,0 +1,52 @@
+// KJC-PCS-0049 Step 7 — MCP handlers calling src/rag/* directly. Imports
+// from src/commands/* are forbidden by the layer-boundaries test
+// (MCP and CLI are peer layers); we hit the pure rag/* modules instead.
+import { countChunks, openVecStore } from "../../rag/vec-store.js";
+import { makeGovernedEmbedder } from "../../rag/governed-embedder.js";
+import { indexProject } from "../../rag/indexer.js";
+import { query } from "../../rag/retriever.js";
+import { getKarajanHome } from "../../utils/paths.js";
+import { resolveProjectDir, buildConfig, responseText, failPayload } from "../shared-helpers.js";
+
+const silentLogger = {
+  info: () => {}, warn: () => {}, error: () => {}, debug: () => {}, setContext: () => {},
+};
+
+export async function handleRagQuery(args, server) {
+  const text = args?.text;
+  if (typeof text !== "string" || text.length === 0) {
+    return failPayload("kj_rag_query: 'text' is required and must be a non-empty string");
+  }
+  try {
+    const projectDir = await resolveProjectDir(server, args?.projectDir);
+    const config = await buildConfig({ ...args, projectDir }, "rag-query");
+    const topK = Number(args?.topK) || 5;
+    const scope = args?.scope || "all";
+    const db = openVecStore({ dim: config?.rag?.embedder?.dim || 768 });
+    try {
+      if (countChunks(db) === 0) return responseText({ hits: [], empty: true, topK, scope });
+      const hits = await query(db, makeGovernedEmbedder(config), text, { topK, scope });
+      return responseText({ hits, empty: false, topK, scope });
+    } finally { db.close(); }
+  } catch (err) {
+    return failPayload(`kj_rag_query failed: ${err.message}`);
+  }
+}
+
+export async function handleRagIndex(args, server) {
+  try {
+    const projectDir = await resolveProjectDir(server, args?.projectDir);
+    const config = await buildConfig({ ...args, projectDir }, "rag-index");
+    const db = openVecStore({ dim: config?.rag?.embedder?.dim || 768 });
+    try {
+      const totals = await indexProject(projectDir, {
+        db, embedder: makeGovernedEmbedder(config),
+        karajanHome: getKarajanHome(), logger: silentLogger,
+        withSources: Boolean(args?.withSources),
+      });
+      return responseText(totals);
+    } finally { db.close(); }
+  } catch (err) {
+    return failPayload(`kj_rag_index failed: ${err.message}`);
+  }
+}

package/src/mcp/handlers/run-handler.js

@@ -0,0 +1,313 @@
+/**
+ * Run and Resume handler logic.
+ * Extracted from server-handlers.js for maintainability.
+ */
+
+import { EventEmitter } from "node:events";
+import { runFlow, resumeFlow } from "../../orchestrator.js";
+import { loadConfig, resolveRole } from "../../config.js";
+import { createLogger } from "../../utils/logger.js";
+import { assertAgentsAvailable } from "../../agents/availability.js";
+import { validatePolicyCompliance } from "../../guards/policy-guard.js";
+import { createRunLog } from "../../utils/run-log.js";
+import { buildProgressHandler, buildProgressNotifier, buildPipelineTracker } from "../progress.js";
+import { isPreflightAcked, ackPreflight, getSessionOverrides } from "../preflight.js";
+import { ensureBootstrap } from "../../bootstrap.js";
+import { validateSovereignty } from "../sovereignty-guard.js";
+import {
+  resolveProjectDir,
+  failPayload,
+  classifyError,
+  assertNotOnBaseBranch,
+  buildConfig,
+  buildAskQuestion,
+  ensureTaskFromFile,
+} from "../shared-helpers.js";
+
+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");
+  const { setRetryCount } = await import("../../session/mutators.js");
+  setRetryCount(session, "auto_resume", 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
+  ];
+  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) {
+  // KJC-PCS-0048 PR 3b: respect specReviewMode without changing the
+  // existing handler contract. "skip" maps to the same flag the CLI
+  // honours; "auto" (default) leaves the reviewer enabled but the
+  // non-TTY runSpecReview path never blocks the pipeline.
+  if (a.specReviewMode === "skip") a.skipSpecReview = true;
+  const config = await buildConfig(a);
+  await assertNotOnBaseBranch(config, { allowForRun: true });
+  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) {
+  // Use a minimal config only for the logger; let resumeFlow use the session's
+  // config_snapshot so that flags like --no-sonar from the original run are preserved.
+  const freshConfig = await buildConfig(a);
+  const logger = createLogger(freshConfig.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: null,  // Use session.config_snapshot (preserves --no-sonar, etc.)
+      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 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, pauseContext) {
+  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" };
+    }
+  }
+  // Policy compliance: reject attempts to bypass TDD, reviewer, security, etc.
+  const policy = validatePolicyCompliance(answer, pauseContext);
+  if (!policy.valid) {
+    const suggestionsText = policy.suggestions.length > 0
+      ? `\nValid alternatives:\n${policy.suggestions.map(s => `  - ${s}`).join("\n")}`
+      : "";
+    return { valid: false, reason: `${policy.reason}${suggestionsText}` };
+  }
+  return { valid: true, sanitized: answer.trim() };
+}
+
+/**
+ * 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);
+}
+
+function applySessionOverrides(a, roleKeys) {
+  const sessionOvr = getSessionOverrides();
+  for (const key of roleKeys) {
+    if (sessionOvr[key] !== undefined) { a[key] = sessionOvr[key]; }
+  }
+}
+
+export async function handleResume(a, server, extra) {
+  if (!a.sessionId) {
+    return failPayload("Missing required field: sessionId");
+  }
+  await runBootstrapGate(server, a);
+  if (a.answer) {
+    // Load session to get pause context for policy-aware validation
+    let pauseContext;
+    try {
+      const { loadSession } = await import("../../session/store.js");
+      const session = await loadSession(a.sessionId);
+      const ctx = session?.paused_state?.context;
+      pauseContext = typeof ctx === "string" ? ctx : ctx?.reason;
+    } catch { /* session read error — validate without context */ }
+    const validation = validateResumeAnswer(a.answer, pauseContext);
+    if (!validation.valid) {
+      return failPayload(`Resume answer rejected: ${validation.reason}`);
+    }
+    a.answer = validation.sanitized;
+  }
+  applySessionOverrides(a, ["coder", "reviewer", "tester", "security", "solomon", "enableTester", "enableSecurity", "enableImpeccable", "enablePerf"]);
+  return handleResumeDirect(a, server, extra);
+}
+
+export async function handleRun(a, server, extra) {
+  // TSK-0340: was `await import(...)` — both helpers now come from the static import block.
+  try {
+    await ensureTaskFromFile(a, a.projectDir || (await resolveProjectDir(server, a.projectDir).catch(() => null)));
+  } catch (err) {
+    return failPayload(`taskFile read failed: ${err.message}`);
+  }
+  if (!a.task) {
+    return failPayload("Missing required field: task (or pass taskFile with a .md path)");
+  }
+  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", "enablePerf"]);
+  return handleRunDirect(a, server, extra);
+}