karajan-code 4.70.4 → 5.0.0

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

@@ -1,318 +0,0 @@
-/**
- * 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);
-  // KJC-BUG-0250: two starts racing past the session check, only one takes the lock.
-  if (!runLog.owned) {
-    runLog.close();
-    return failPayload("A pipeline is already running for this project. Wait for it to complete or use kj_status to check progress.");
-  }
-  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);
-}

package/src/mcp/sovereignty-guard.js

@@ -1,113 +0,0 @@
-/**
- * Sovereignty guard for MCP inputs.
- *
- * Validates kj_run parameters and rejects host-AI attempts to override
- * pipeline decisions that Karajan makes internally (triage, hu-reviewer, etc.).
- */
-
-import fs from "node:fs";
-import path from "node:path";
-import { isPidAlive } from "../utils/run-log.js";
-
-/** Parameters that the host AI is allowed to pass through without restriction. */
-const ALLOWED_PARAMS = new Set([
-  "task", "projectDir", "pgTask", "pgProject",
-  "planner", "coder", "reviewer", "refactorer",
-  "plannerModel", "coderModel", "reviewerModel", "refactorerModel",
-  "enablePlanner", "enableReviewer", "enableRefactorer", "enableResearcher",
-  "enableTester", "enableSecurity", "enableImpeccable", "enablePerf",
-  "enableDiscover", "enableArchitect",
-  "architectModel", "huFile",
-  "enableSerena", "enableCi",
-  "reviewerFallback", "reviewerRetries",
-  "mode", "maxIterations", "maxIterationMinutes", "maxTotalMinutes",
-  "baseBranch", "baseRef", "methodology",
-  "autoCommit", "autoPush", "autoPr", "autoRebase", "branchPrefix",
-  "autoSimplify", "smartModels", "checkpointInterval",
-  "taskType", "quiet", "noSonar", "enableSonarcloud",
-  "kjHome", "sonarToken", "timeoutMs", "domain",
-  // Sovereign flags — validated below but still "known"
-  "enableTriage", "enableHuReviewer",
-]);
-
-const MIN_ITERATIONS = 1;
-const MAX_ITERATIONS = 10;
-
-
-/**
- * Check if a pipeline is already running for this project.
- * KJC-BUG-0250 (#1897, #1892): the fact is the run lock (.kj/run.lock) held by
- * a live process. The old signal, a recent write to run.log, also fired after
- * a run that failed in preflight or any short command, blocking the next run.
- *
- * @param {string} projectDir - Project root directory
- * @returns {{ active: boolean, message?: string }}
- */
-export function checkActiveSession(projectDir) {
-  if (!projectDir) return { active: false };
-  let holder;
-  try {
-    holder = JSON.parse(fs.readFileSync(path.join(projectDir, ".kj", "run.lock"), "utf8"));
-  } catch {
-    return { active: false }; // no lock, or unreadable: nothing holds the project
-  }
-  if (!isPidAlive(holder?.pid)) return { active: false }; // stale: its process is gone
-  const since = holder.startedAt ? ", since " + holder.startedAt : "";
-  return {
-    active: true,
-    message:
-      `A pipeline is already running for this project (pid ${holder.pid}${since}). ` +
-      "Wait for it to complete or use kj_status to check progress.",
-  };
-}
-
-/**
- * Validate and sanitise kj_run parameters.
- *
- * @param {Record<string, unknown>} params - Raw parameters from the MCP call
- * @param {{ projectDir?: string }} context - Runtime context
- * @returns {{ params: Record<string, unknown>, warnings: string[], error?: string }}
- */
-export function validateSovereignty(params, context = {}) {
-  const warnings = [];
-  const sanitized = { ...params };
-
-  // 1. Strip unknown parameters
-  for (const key of Object.keys(sanitized)) {
-    if (!ALLOWED_PARAMS.has(key)) {
-      warnings.push(`Unknown parameter "${key}" stripped`);
-      delete sanitized[key];
-    }
-  }
-
-  // 2. Sovereign flags — pipeline decides, not the host AI
-  if (sanitized.enableHuReviewer === false) {
-    warnings.push("Pipeline decides hu-reviewer activation, ignoring override");
-    delete sanitized.enableHuReviewer;
-  }
-
-  if (sanitized.enableTriage === false) {
-    warnings.push("Triage is mandatory, ignoring override");
-    delete sanitized.enableTriage;
-  }
-
-  // 3. Clamp maxIterations to [1, 10]
-  if (sanitized.maxIterations !== undefined) {
-    const n = Number(sanitized.maxIterations);
-    if (!Number.isFinite(n) || n < MIN_ITERATIONS) {
-      warnings.push(`maxIterations ${sanitized.maxIterations} clamped to ${MIN_ITERATIONS}`);
-      sanitized.maxIterations = MIN_ITERATIONS;
-    } else if (n > MAX_ITERATIONS) {
-      warnings.push(`maxIterations ${sanitized.maxIterations} clamped to ${MAX_ITERATIONS}`);
-      sanitized.maxIterations = MAX_ITERATIONS;
-    }
-  }
-
-  // 4. Active session detection
-  const session = checkActiveSession(context.projectDir);
-  if (session.active) {
-    return { params: sanitized, warnings, error: session.message };
-  }
-
-  return { params: sanitized, warnings };
-}

package/src/mcp/tool-arg-normalizers.js

@@ -1,16 +0,0 @@
-export function normalizePlanArgs(args = {}) {
-  const normalized = { ...args };
-
-  if (!normalized.planner && normalized.coder) {
-    normalized.planner = normalized.coder;
-  }
-
-  if (!normalized.plannerModel && normalized.coderModel) {
-    normalized.plannerModel = normalized.coderModel;
-  }
-
-  delete normalized.coder;
-  delete normalized.coderModel;
-
-  return normalized;
-}

package/src/mutate/reviewer-signal.js

@@ -1,76 +0,0 @@
-/**
- * Reviewer opt-in mutation signal (KJC-TSK-0588). OFF by default: only when
- * `KJ_REVIEW_MUTATION` is set does the reviewer run `kj mutate` scoped to the
- * diff and fold surviving mutants into its verdict as a weak-test signal.
- * A null return means "add nothing" → the default-off prompt stays identical.
- */
-
-import { mutateCommand } from "../commands/mutate.js";
-
-const DEFAULT_SINCE = "HEAD~1";
-const ENABLED = /^(1|true|yes|on)$/i;
-
-/** True when the reviewer mutation opt-in is switched on via env. */
-export function isMutationReviewEnabled(env = process.env) {
-  return ENABLED.test(String(env?.KJ_REVIEW_MUTATION ?? "").trim());
-}
-
-// Drives `kj mutate --json` over the diff, capturing its output instead of
-// printing it, and returns {code, result} where result is the normalized JSON.
-async function defaultRun({ since, projectDir }) {
-  const lines = [];
-  const code = await mutateCommand({
-    since,
-    projectDir,
-    json: true,
-    maxSurvivors: Number.POSITIVE_INFINITY,
-    logger: { info: (m) => lines.push(String(m)) },
-  });
-  const jsonLine = [...lines].reverse().find((l) => l.trim().startsWith("{"));
-  return { code, result: jsonLine ? JSON.parse(jsonLine) : null };
-}
-
-function unavailableNote() {
-  return [
-    "## Mutation testing (advisory)",
-    "Mutation testing was requested but could not run on this diff (unsupported",
-    "stack or tool unavailable). Treat it as unavailable — do not infer test",
-    "quality from its absence.",
-  ].join("\n");
-}
-
-function survivorSection(survivors) {
-  const lines = survivors.map((s) => `- ${s.file}:${s.line ?? "?"} (${s.mutator ?? s.status})`);
-  return [
-    "## Mutation testing (advisory signal)",
-    "The following mutants survived over the changed lines — the tests did not",
-    "catch these deliberate defects, so the covering tests are weak. Weigh this",
-    "as a signal about test quality, not as a hard blocker on its own:",
-    ...lines,
-  ].join("\n");
-}
-
-/**
- * Build the reviewer's mutation-signal prompt section, or null to add nothing.
- * `run` ({since, projectDir}) → {code, result} is injectable for tests.
- * @returns {Promise<string|null>}
- */
-export async function buildReviewerMutationSignal({
-  enabled,
-  since = DEFAULT_SINCE,
-  projectDir = process.cwd(),
-  run = defaultRun,
-} = {}) {
-  if (!enabled) return null;
-  let outcome;
-  try {
-    outcome = await run({ since, projectDir });
-  } catch {
-    return unavailableNote();
-  }
-  const { code, result } = outcome ?? {};
-  if (code === 1 || code === 2) return unavailableNote();
-  const survivors = result?.survived ?? [];
-  if (survivors.length === 0) return null;
-  return survivorSection(survivors);
-}

package/src/orchestrator/agent-fallback.js

@@ -1,81 +0,0 @@
-import { createAgent } from "../agents/index.js";
-import { addCheckpoint } from "../session/store.js";
-import { detectRateLimit } from "../utils/rate-limit-detector.js";
-
-/**
- * Run a coder-like role with fallback on rate limit.
- * Tries the primary agent first. If it fails with a rate limit,
- * switches to the fallback agent (if configured).
- * Non-rate-limit failures stop immediately (no fallback).
- *
- * Returns { execResult, attempts, allRateLimited }
- */
-export async function runCoderWithFallback({
-  coderName,
-  fallbackCoder,
-  config,
-  logger,
-  emitter,
-  RoleClass,
-  roleInput,
-  session,
-  iteration,
-  onAttemptResult
-}) {
-  const candidates = [coderName];
-  if (fallbackCoder && fallbackCoder !== coderName) {
-    candidates.push(fallbackCoder);
-  }
-
-  const attempts = [];
-
-  for (const name of candidates) {
-    const agentConfig = {
-      ...config,
-      roles: { ...config.roles, coder: { ...config.roles?.coder, provider: name } }
-    };
-
-    const role = new RoleClass({ config: agentConfig, logger, emitter, createAgentFn: createAgent });
-    await role.init();
-
-    const execResult = await role.execute(roleInput);
-
-    if (onAttemptResult) {
-      await onAttemptResult({ coder: name, result: execResult.result });
-    }
-
-    const rateLimited = !execResult.ok && detectRateLimit({
-      stderr: execResult.result?.error || "",
-      stdout: execResult.result?.output || ""
-    }).isRateLimit;
-
-    attempts.push({
-      coder: name,
-      ok: execResult.ok,
-      rateLimited,
-      result: execResult.result,
-      execResult
-    });
-
-    await addCheckpoint(session, {
-      stage: "coder-attempt",
-      iteration,
-      coder: name,
-      ok: execResult.ok,
-      rateLimited
-    });
-
-    if (execResult.ok) {
-      return { execResult, attempts, allRateLimited: false };
-    }
-
-    // Only fallback on rate limit errors
-    if (!rateLimited) {
-      return { execResult: null, attempts, allRateLimited: false };
-    }
-
-    logger.warn(`Agent ${name} hit rate limit, trying fallback...`);
-  }
-
-  return { execResult: null, attempts, allRateLimited: true };
-}