karajan-code 2.7.4 → 2.8.0

package/src/orchestrator/drivers/error-recovery.js

@@ -0,0 +1,287 @@
+/**
+ * Error-recovery driver — extracted from src/orchestrator/flow-runner.js
+ * in TSK-0335 (Oleada 3 of the v2.7.4 audit refactor).
+ *
+ * Five handlers that react to pipeline-level failure signals and decide
+ * whether to retry, pause, or escalate to Solomon:
+ *
+ *   - handleStandbyResult:            rate-limit / provider-outage →
+ *                                     Solomon decides skip/retry/wait/pause.
+ *   - emitSolomonAlerts:              forward Solomon-rules findings to
+ *                                     the progress stream.
+ *   - handleSolomonCheck:             evaluate Solomon-rules context,
+ *                                     escalate critical alerts (direct to
+ *                                     human without Brain, via Solomon
+ *                                     with Brain).
+ *   - checkSolomonCriticalAlerts:     non-Brain branch — ask the user
+ *                                     whether to continue/pause/stop on
+ *                                     critical alerts.
+ *   - handleReviewerRetryAndSolomon:  reviewer sub-loop limit → invoke
+ *                                     Solomon to resolve the stall.
+ *
+ * These were extracted verbatim; no behavior change. flow-runner.js now
+ * imports them instead of defining them. Part of breaking up the 2254-LOC
+ * god-module — see docs/ARCHITECTURE.md and the TSK-0335 acceptance
+ * criteria.
+ */
+
+import { invokeSolomon } from "../solomon-escalation.js";
+import { saveSession, pauseSession } from "../../session/store.js";
+import {
+  setReviewerFeedback, setAlternativeAgent, resetRetryCount,
+  incrementRetryCount,
+} from "../../session/mutators.js";
+import { emitProgress, makeEvent } from "../../utils/events.js";
+import { tryCiComment } from "../ci-integration.js";
+
+export async function handleStandbyResult({ stageResult, session, emitter, eventBase, i, stage, logger, config, askQuestion }) {
+  if (stageResult?.action !== "standby") {
+    return { handled: false };
+  }
+
+  const isOutage = stageResult.standbyInfo.isProviderOutage;
+  const agent = stageResult.standbyInfo.agent;
+  const cooldownUntil = stageResult.standbyInfo.cooldownUntil;
+  const cooldownMs = stageResult.standbyInfo.cooldownMs;
+
+  // Rate limit = out of normal flow → Solomon decides immediately
+  const solomonResult = await invokeSolomon({
+    config, logger, emitter, eventBase, stage: `${stage}_rate_limit`, askQuestion, session,
+    iteration: i,
+    conflict: {
+      stage: `${stage}_rate_limit`,
+      task: session.task,
+      iterationCount: i,
+      maxIterations: config?.max_iterations || 5,
+      cooldownUntil,
+      cooldownMs,
+      history: [{
+        agent: stage,
+        feedback: `Agent "${agent}" rate-limited. ${isOutage ? "Provider outage (5xx)." : "API rate limit (429)."} ${cooldownUntil ? `Cooldown until ${cooldownUntil}.` : ""}`
+      }]
+    }
+  });
+
+  if (solomonResult.action === "approve") {
+    // Solomon says skip is safe — only allowed after exhausting alternatives
+    logger.info(`Solomon: skip ${stage} after evaluating risk (agent "${agent}" rate-limited)`);
+    emitProgress(emitter, makeEvent(`${stage}:rate_limit`, { ...eventBase, stage }, {
+      status: "ok",
+      message: `Solomon: skip ${stage} (low risk, agent "${agent}" unavailable)`,
+      detail: { agent, solomonAction: "approve" }
+    }));
+    return { handled: true, action: "skip" };
+  }
+
+  if (solomonResult.action === "continue") {
+    // Solomon says: wait for cooldown, or retry with alternative agent
+    const altAgent = solomonResult.alternativeAgent;
+    const waitTarget = solomonResult.waitUntil;
+
+    if (waitTarget) {
+      const waitMs = Math.max(0, new Date(waitTarget).getTime() - Date.now());
+      if (waitMs > 0 && waitMs < 10 * 60 * 1000) {
+        logger.info(`Solomon: wait ${Math.round(waitMs / 1000)}s for cooldown, then retry ${stage}`);
+        await new Promise(r => setTimeout(r, waitMs));
+      }
+    }
+
+    if (altAgent) {
+      logger.info(`Solomon: retry ${stage} with alternative agent "${altAgent}"`);
+      setAlternativeAgent(session, stage, altAgent);
+    }
+
+    if (solomonResult.humanGuidance) {
+      setReviewerFeedback(session, `Solomon guidance: ${solomonResult.humanGuidance}`);
+    }
+    await saveSession(session);
+    return { handled: true, action: "retry_reviewer_only" };
+  }
+
+  if (solomonResult.action === "pause") {
+    return {
+      handled: true,
+      action: "return",
+      result: { paused: true, sessionId: session.id, question: solomonResult.question, context: "rate_limit" }
+    };
+  }
+
+  // Solomon couldn't resolve — pause
+  await pauseSession(session, {
+    question: `Agent "${agent}" rate-limited. Solomon could not resolve.`,
+    context: { iteration: i, stage, reason: "rate_limit" }
+  });
+  return {
+    handled: true,
+    action: "return",
+    result: { paused: true, sessionId: session.id, question: `Agent "${agent}" rate-limited`, context: "rate_limit" }
+  };
+}
+
+
+export function emitSolomonAlerts(alerts, emitter, eventBase, logger) {
+  for (const alert of alerts) {
+    emitProgress(emitter, makeEvent("brain:rules-alert", { ...eventBase, stage: "brain" }, {
+      status: alert.severity === "critical" ? "fail" : "warn",
+      message: alert.message,
+      detail: alert.detail
+    }));
+    logger.warn(`Rules alert [${alert.rule}]: ${alert.message}`);
+  }
+}
+
+export async function handleSolomonCheck({ config, session, emitter, eventBase, logger, task, i, askQuestion, ciEnabled, blockingIssues, brainCtx }) {
+  if (config.pipeline?.solomon?.enabled === false) return { action: "continue" };
+
+  try {
+    const { evaluateRules, buildRulesContext } = await import("../solomon-rules.js");
+    const rulesContext = await buildRulesContext({ session, task, iteration: i, blockingIssues });
+    const rulesResult = evaluateRules(rulesContext, config.solomon?.rules);
+
+    if (rulesResult.alerts.length > 0) {
+      emitSolomonAlerts(rulesResult.alerts, emitter, eventBase, logger);
+      // Brain gateway: when Brain is the orchestrator, rule alerts are telemetry.
+      // On critical alerts Brain consults Solomon (AI judge). Only if Solomon can't
+      // resolve does Brain escalate to human. Solomon-rules never prompts directly.
+      if (!brainCtx?.enabled) {
+        const pauseResult = await checkSolomonCriticalAlerts({ rulesResult, askQuestion, session, i });
+        if (pauseResult) return pauseResult;
+      } else if (rulesResult.hasCritical) {
+        const criticalAlerts = rulesResult.alerts.filter(a => a.severity === "critical");
+        brainCtx.ruleAlerts = brainCtx.ruleAlerts || [];
+        brainCtx.ruleAlerts.push(...criticalAlerts);
+        logger.info(`Brain: ${criticalAlerts.length} critical rule alert(s) — consulting Solomon`);
+
+        const alertSummary = criticalAlerts.map(a => a.message).join("; ");
+        const solomonOpinion = await invokeSolomon({
+          config, logger, emitter, eventBase, stage: "brain-dilemma", askQuestion, session, iteration: i,
+          conflict: {
+            stage: "brain-dilemma",
+            task,
+            iterationCount: i,
+            maxIterations: config.max_iterations,
+            dilemma: `Brain detected critical rule alerts: ${alertSummary}. Should we continue iterating, pause for human, or stop?`,
+            ruleAlerts: criticalAlerts,
+            blockingIssues: blockingIssues || [],
+            history: (session.checkpoints || []).filter(cp => cp.stage === "reviewer").slice(-5).map(cp => ({ iteration: cp.iteration, feedback: cp.note || "" }))
+          }
+        });
+
+        if (solomonOpinion.action === "pause") {
+          logger.info("Brain: Solomon advised pause — escalating to human");
+          return { action: "return", result: { paused: true, sessionId: session.id, question: solomonOpinion.question || `Brain+Solomon paused: ${alertSummary}`, context: "brain_solomon_dilemma" } };
+        }
+        if (solomonOpinion.action === "approve") {
+          logger.info("Brain: Solomon advised proceeding — treating as approved");
+          return { action: "continue", approved: true };
+        }
+        // action === "continue" | "subtask" | fallback → Brain continues the loop
+        logger.info(`Brain: Solomon said '${solomonOpinion.action}' — continuing loop`);
+      }
+    }
+
+    if (ciEnabled && session.ci_pr_number) {
+      const alerts = rulesResult.alerts || [];
+      const alertMsg = alerts.length > 0
+        ? alerts.map(a => `- [${a.severity}] ${a.message}`).join("\n")
+        : "No anomalies detected";
+      await tryCiComment({
+        config, session, logger,
+        agent: "Solomon",
+        body: `Supervisor check iteration ${i}: ${alertMsg}`
+      });
+    }
+  } catch (err) {
+    logger.warn(`Solomon rules evaluation failed: ${err.message}`);
+  }
+
+  return { action: "continue" };
+}
+
+export async function checkSolomonCriticalAlerts({ rulesResult, askQuestion, session, i }) {
+  if (!rulesResult.hasCritical || !askQuestion) return null;
+
+  const alertSummary = rulesResult.alerts
+    .filter(a => a.severity === "critical")
+    .map(a => a.message)
+    .join("\n");
+  const question = [
+    "Solomon detected critical issues:",
+    alertSummary,
+    "",
+    "What should we do?",
+    "1 = Continue anyway",
+    "2 = Pause the session",
+    "3 = Stop the session",
+    "",
+    "Type 1, 2, or 3:"
+  ].join("\n");
+  const answer = await askQuestion(question, { iteration: i, stage: "solomon" });
+  const trimmed = (answer || "").trim().toLowerCase();
+  const shouldPause = !answer
+    || trimmed === "2" || trimmed === "3"
+    || trimmed.startsWith("pause") || trimmed.startsWith("stop");
+  if (shouldPause) {
+    await pauseSession(session, {
+      question: `Solomon supervisor paused: ${alertSummary}`,
+      context: { iteration: i, stage: "solomon", alerts: rulesResult.alerts }
+    });
+    return { action: "pause", result: { paused: true, sessionId: session.id, reason: "solomon_alert" } };
+  }
+  return null;
+}
+
+export async function handleReviewerRetryAndSolomon({ config, session, emitter, eventBase, logger, review, task, i, askQuestion }) {
+  setReviewerFeedback(session, review.blocking_issues
+    .map((x) => {
+      const parts = [`[${x.severity || "high"}] ${x.id || "ISSUE"}: ${x.description || "Missing description"}`];
+      if (x.file) parts.push(`  File: ${x.file}${x.line ? `:${x.line}` : ""}`);
+      if (x.suggested_fix) parts.push(`  Fix: ${x.suggested_fix}`);
+      return parts.join("\n");
+    })
+    .join("\n\n"));
+  incrementRetryCount(session, "reviewer");
+  await saveSession(session);
+
+  const maxReviewerRetries = config.session.max_reviewer_retries ?? config.session.fail_fast_repeats;
+  if (session.reviewer_retry_count < maxReviewerRetries) {
+    return { action: "continue" };
+  }
+
+  emitProgress(
+    emitter,
+    makeEvent("solomon:escalate", { ...eventBase, stage: "reviewer" }, {
+      message: `Reviewer sub-loop limit reached (${session.reviewer_retry_count}/${maxReviewerRetries})`,
+      detail: { subloop: "reviewer", retryCount: session.reviewer_retry_count, limit: maxReviewerRetries }
+    })
+  );
+
+  const solomonResult = await invokeSolomon({
+    config, logger, emitter, eventBase, stage: "reviewer", askQuestion, session, iteration: i,
+    conflict: {
+      stage: "reviewer",
+      task,
+      iterationCount: session.reviewer_retry_count,
+      maxIterations: maxReviewerRetries,
+      history: [{ agent: "reviewer", feedback: session.last_reviewer_feedback }]
+    }
+  });
+
+  if (solomonResult.action === "pause") {
+    return { action: "return", result: { paused: true, sessionId: session.id, question: solomonResult.question, context: "reviewer_fail_fast" } };
+  }
+  if (solomonResult.action === "continue") {
+    if (solomonResult.humanGuidance) {
+      // Append, not overwrite — keep the reviewer's blocking issues context.
+      setReviewerFeedback(session, `${session.last_reviewer_feedback}\nUser guidance: ${solomonResult.humanGuidance}`);
+    }
+    resetRetryCount(session, "reviewer");
+    await saveSession(session);
+    return { action: "continue" };
+  }
+  if (solomonResult.action === "subtask") {
+    return { action: "return", result: { paused: true, sessionId: session.id, subtask: solomonResult.subtask, context: "reviewer_subtask" } };
+  }
+
+  return { action: "continue" };
+}

package/src/orchestrator/drivers/init-context.js

@@ -0,0 +1,222 @@
+/**
+ * Init-context driver — extracted from src/orchestrator/flow-runner.js in
+ * TSK-0335 (Oleada 3 of the v2.7.4 audit refactor).
+ *
+ * Builds the PipelineContext for runFlow: loads config, resolves roles,
+ * wires budget tracker, attaches RTK wrappers, starts the HU Board,
+ * loads product context, creates the session, runs the pre-loop stages,
+ * and sets up the session journal + git automation.
+ *
+ * Extracted verbatim; no behavior change. Split from pre-loop.js because
+ * together they would exceed the 600-LOC/driver ceiling set by the
+ * TSK-0335 acceptance criteria.
+ */
+
+import { createAgent } from "../../agents/index.js";
+import { resolveRole } from "../../config.js";
+import { resolveReviewProfile } from "../../review/profiles.js";
+import { RepeatDetector, getRepeatThreshold } from "../../repeat-detector.js";
+import { emitProgress, makeEvent } from "../../utils/events.js";
+import { prepareGitAutomation } from "../../git/automation.js";
+import { CoderRole } from "../../roles/coder-role.js";
+import { PipelineContext } from "../pipeline-context.js";
+import { detectRtk } from "../../utils/rtk-detect.js";
+import { createRtkRunner, RtkSavingsTracker } from "../../utils/rtk-wrapper.js";
+import { setRunner as setDiffRunner, setProjectDir as setDiffProjectDir } from "../../review/diff-generator.js";
+import { setRunner as setGitRunner } from "../../utils/git.js";
+import {
+  loadProductContext, resolvePipelineFlags, createBudgetManager,
+  initializeSession, autoInit,
+} from "../config-init.js";
+import {
+  createJournalDir, writePreLoopJournal, buildPlanSummary,
+} from "../session-journal.js";
+import { setPgCard, setJournalContext } from "../../session/mutators.js";
+import { getRunContext } from "../../utils/run-context.js";
+import { getIntegration } from "../integrations.js";
+import { tryAutoStartBoard } from "./post-loop.js";
+import { runPreLoopStages } from "./pre-loop.js";
+
+export async function initFlowContext({ task, config, logger, emitter, askQuestion, pgTaskId, pgProject, flags }) {
+  // Auto-init .karajan/ if missing (copies coder-rules, review-rules, role templates)
+  const initProjectDir = config.projectDir || process.cwd();
+  await autoInit(initProjectDir, logger);
+
+  // Smart role assignment: detect installed AIs and assign to roles
+  // Only runs if: (a) no roles configured AND (b) not in test environment
+  const needsAssignment = !config.roles?.coder?.provider && !config.coder && process.env.NODE_ENV !== "test" && !process.env.VITEST;
+  if (needsAssignment) {
+    try {
+      const { autoAssignRoles, applyRoleAssignments } = await import("../../utils/role-assigner.js");
+      const { assignments } = await autoAssignRoles(logger);
+      if (assignments) config = applyRoleAssignments({ ...config }, assignments);
+    } catch { /* non-blocking — defaults will be used */ }
+  }
+
+  // Scope all git diffs to projectDir (prevents leaking unrelated branch changes)
+  // When running from a subdirectory of a git repo, use relative path as scope
+  let diffScope = config.projectDir || null;
+  if (!diffScope) {
+    try {
+      // Audit follow-up: same execSync→execFileSync migration as #555.
+      const { execFileSync } = await import("node:child_process");
+      const repoRoot = execFileSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();
+      const cwd = process.cwd();
+      if (cwd !== repoRoot && cwd.startsWith(repoRoot)) {
+        diffScope = cwd.slice(repoRoot.length + 1);
+        logger.info(`Running from subdirectory — diff scoped to ${diffScope}/`);
+      }
+    } catch { /* git not available */ }
+  }
+  // TSK-0338: write into the per-run AsyncLocalStorage context instead of
+  // mutating module-level state. Falls back to setDiffProjectDir() when no
+  // run context is active (legacy CLI callers, tests not going through
+  // runFlow). The write-to-both keeps back-compat without trading isolation.
+  const runCtx = getRunContext();
+  if (runCtx) runCtx.projectDir = diffScope;
+  else setDiffProjectDir(diffScope);
+
+  // Auto-detect Chrome DevTools MCP
+  const { detectDevToolsMcp } = await import("../../webperf/devtools-detect.js");
+  const devToolsAvailable = await detectDevToolsMcp(logger);
+  if (devToolsAvailable) {
+    config = { ...config, webperf: { ...config.webperf, devtools_mcp: true } };
+  }
+
+  const ctx = new PipelineContext({ config, session: null, logger, emitter, task, flags });
+  ctx.askQuestion = askQuestion;
+  ctx.pgTaskId = pgTaskId;
+  ctx.pgProject = pgProject;
+
+  ctx.coderRole = resolveRole(config, "coder");
+  ctx.reviewerRole = resolveRole(config, "reviewer");
+  ctx.refactorerRole = resolveRole(config, "refactorer");
+  ctx.pipelineFlags = resolvePipelineFlags(config);
+  ctx.repeatDetector = new RepeatDetector({ threshold: getRepeatThreshold(config) });
+  ctx.coderRoleInstance = new CoderRole({ config, logger, emitter, createAgentFn: createAgent, askHost: askQuestion });
+  ctx.startedAt = Date.now();
+  ctx.eventBase = { sessionId: null, iteration: 0, stage: null, startedAt: ctx.startedAt };
+  const { budgetTracker, budgetLimit, budgetSummary, trackBudget } = createBudgetManager({
+    config,
+    emitter,
+    eventBase: ctx.eventBase,
+    // Provides fresh compression data for "With KJ vs Without KJ" comparison
+    // (KJC-TSK-0274). Invoked on every budgetSummary() call.
+    getCompressionStats: () => ({
+      rtkSavings: ctx.rtkTracker?.hasData() ? ctx.rtkTracker.summary() : (ctx.session?.rtk_savings || null),
+      brainCtx: ctx.brainCtx || null,
+    }),
+  });
+  ctx.budgetTracker = budgetTracker;
+  ctx.budgetLimit = budgetLimit;
+  ctx.budgetSummary = budgetSummary;
+  ctx.trackBudget = trackBudget;
+
+  // --- RTK detection ---
+  const rtkResult = await detectRtk();
+  if (rtkResult.available) {
+    config = { ...config, rtk: { available: true, version: rtkResult.version } };
+    const rtkTracker = new RtkSavingsTracker();
+    const rtkRunner = createRtkRunner(true, rtkTracker);
+    // TSK-0338: install rtkRunner into the per-run context; module-level
+    // setters are the back-compat path for runs outside a withRunContext scope.
+    if (runCtx) runCtx.runner = rtkRunner;
+    else {
+      setDiffRunner(rtkRunner);
+      setGitRunner(rtkRunner);
+    }
+    ctx.rtkTracker = rtkTracker;
+    logger.info(`RTK detected (${rtkResult.version}) — wrapping internal git/diff commands with rtk`);
+    emitProgress(emitter, makeEvent("rtk:detected", ctx.eventBase, {
+      message: "RTK detected — internal commands wrapped for token optimization",
+      detail: { version: rtkResult.version, executorType: "local" }
+    }));
+  }
+
+  // --- HU Board auto-start ---
+  await tryAutoStartBoard(config, logger, emitter, ctx.eventBase);
+
+  // --- Product Context ---
+  const ctxProjectDir = config.projectDir || process.cwd();
+  const { content: productContext, source: productContextSource } = await loadProductContext(ctxProjectDir);
+  if (productContext) {
+    config = { ...config, productContext };
+    logger.info(`Product context loaded from ${productContextSource}`);
+    emitProgress(emitter, makeEvent("context:loaded", ctx.eventBase, {
+      message: "Product context loaded",
+      detail: { source: productContextSource }
+    }));
+  }
+
+  ctx.session = await initializeSession({ task, config, flags, pgTaskId, pgProject });
+  ctx.eventBase.sessionId = ctx.session.id;
+
+  // Karajan Brain: initialize runtime context (opt-in via config.brain.enabled)
+  const { createBrainContext, isBrainEnabled } = await import("../brain-coordinator.js");
+  ctx.brainCtx = createBrainContext({ enabled: isBrainEnabled(config) });
+  if (ctx.brainCtx.enabled) {
+    logger.info("Karajan Brain enabled — feedback queue, verification, compression active");
+  }
+
+  const trackerResult = await getIntegration("tracker")?.onSessionStart?.({
+    session: ctx.session, config, logger, pgTaskId, pgProject,
+  });
+  ctx.pgCard = trackerResult?.pgCard ?? null;
+  setPgCard(ctx.session, ctx.pgCard || null);
+
+  emitProgress(
+    emitter,
+    makeEvent("session:start", ctx.eventBase, {
+      message: "Session started",
+      detail: { task, coder: ctx.coderRole.provider, reviewer: ctx.reviewerRole.provider, maxIterations: config.max_iterations }
+    })
+  );
+
+  ctx.stageResults = {};
+  ctx.sonarState = { issuesInitial: null, issuesFinal: null };
+
+  const preLoopResult = await runPreLoopStages({ config, logger, emitter, eventBase: ctx.eventBase, session: ctx.session, flags, pipelineFlags: ctx.pipelineFlags, coderRole: ctx.coderRole, trackBudget: ctx.trackBudget, task, askQuestion, pgTaskId, pgProject, stageResults: ctx.stageResults, brainCtx: ctx.brainCtx });
+  ctx.plannedTask = preLoopResult.plannedTask;
+  ctx.config = preLoopResult.updatedConfig;
+
+  // --- Session Journal: persist pre-loop outputs + display plan summary ---
+  const reportDir = ctx.config.output?.report_dir || ".reviews";
+  try {
+    ctx.journalDir = await createJournalDir(reportDir, ctx.session.id);
+    const journalFiles = await writePreLoopJournal(ctx.journalDir, ctx.stageResults);
+    ctx.journalFiles = journalFiles;
+    ctx.journalIterations = [];
+    ctx.journalDecisions = [];
+
+    // Attach journal state to session so finalizeApprovedSession can access it
+    setJournalContext(ctx.session, {
+      dir: ctx.journalDir,
+      files: journalFiles,
+      iterations: ctx.journalIterations,
+      decisions: ctx.journalDecisions,
+      startedAt: ctx.startedAt,
+    });
+
+    // Display plan summary in console before iteration loop
+    const planSummary = buildPlanSummary({
+      pipelineFlags: ctx.pipelineFlags,
+      config: ctx.config,
+      stageResults: ctx.stageResults,
+      task
+    });
+    console.log(planSummary);
+  } catch (err) {
+    logger.warn(`Journal init failed (non-blocking): ${err.message}`);
+    ctx.journalDir = null;
+    ctx.journalFiles = [];
+    ctx.journalIterations = [];
+    ctx.journalDecisions = [];
+  }
+
+  ctx.gitCtx = await prepareGitAutomation({ config: ctx.config, task, logger, session: ctx.session });
+  const projectDir = ctx.config.projectDir || process.cwd();
+  ctx.reviewRules = (await resolveReviewProfile({ mode: ctx.config.review_mode, projectDir })).rules;
+  await ctx.coderRoleInstance.init();
+
+  return ctx;
+}