@karajan-family/code 4.21.0

package/src/orchestrator/stages/rag-context-stage.js

@@ -0,0 +1,77 @@
+// KJC-PCS-0049 Camino C — pre-loop RAG retrieval stage.
+// Runs between triage and domainCurator. When `config.rag.preload.enabled`
+// is true and the corpus has chunks, queries the retriever with the
+// task text and returns a markdown block ready to prepend to the task.
+// Failures degrade gracefully (warn + continue); the rest of the pipeline
+// never sees an exception from this stage.
+import { emitProgress, makeEvent } from "../../utils/events.js";
+import { openVecStore, countChunks } from "../../rag/vec-store.js";
+import { makeGovernedEmbedder } from "../../rag/governed-embedder.js";
+import { query } from "../../rag/retriever.js";
+
+const DEFAULT_TOP_K = 5;
+const DEFAULT_SCOPE = "all";
+const DEFAULT_SEARCH_MODE = "hybrid";
+const DEFAULT_SEARCH_ALPHA = 0.6;
+const MAX_CHUNK_CHARS = 600;
+
+// KJC-TSK-0463 — pull search-time knobs from config so the HU Board
+// modal (rag.search.{mode,alpha,rerank}) actually steers retrieval at
+// pipeline time. Returns the args object query() expects; unset fields
+// fall back to the retriever's own defaults.
+export function resolveSearchOpts(config) {
+  const s = config?.rag?.search ?? {};
+  const out = {
+    mode: typeof s.mode === "string" ? s.mode : DEFAULT_SEARCH_MODE,
+    alpha: Number.isFinite(s.alpha) ? s.alpha : DEFAULT_SEARCH_ALPHA,
+  };
+  if (s.rerank && typeof s.rerank === "object") out.rerankOpts = s.rerank;
+  else if (s.rerank === true) out.rerankOpts = {};
+  return out;
+}
+
+/**
+ * Runs the RAG preload stage. Returns:
+ *   { skipped: true, reason }                  — when disabled / empty / error
+ *   { skipped: false, contextBlock, hits }     — markdown block + raw hits
+ *
+ * The caller decides whether to mutate `task` with the contextBlock. We
+ * keep that responsibility at the call site so this module stays pure.
+ */
+export async function runRagContextStage({ config, logger, emitter, eventBase, task }) {
+  const preload = config?.rag?.preload;
+  if (!preload?.enabled) return { skipped: true, reason: "disabled" };
+  if (typeof task !== "string" || task.length === 0) return { skipped: true, reason: "no-task" };
+  try {
+    const dim = config?.rag?.embedder?.dim || 768;
+    const db = openVecStore({ dim });
+    try {
+      if (countChunks(db) === 0) {
+        logger?.info?.("[rag-preload] corpus is empty, skipping (run `kj rag index` to seed)");
+        return { skipped: true, reason: "empty" };
+      }
+      const topK = preload.topK || DEFAULT_TOP_K;
+      const scope = preload.scope || DEFAULT_SCOPE;
+      const embedder = makeGovernedEmbedder(config);
+      const searchOpts = resolveSearchOpts(config);
+      const hits = await query(db, embedder, task, { topK, scope, ...searchOpts });
+      if (hits.length === 0) return { skipped: true, reason: "no-hits" };
+      const lines = hits.map((h) => {
+        const label = h.metadata?.hu_id || h.metadata?.symbol || h.metadata?.headingPath?.join(" > ") || "block";
+        const text = h.text.length > MAX_CHUNK_CHARS ? `${h.text.slice(0, MAX_CHUNK_CHARS)}…` : h.text;
+        return `### [${h.kind} · ${label}] ${h.source}\n\n${text}`;
+      });
+      const contextBlock = `## Prior context from RAG (auto-retrieved, top ${hits.length})\n\n${lines.join("\n\n")}`;
+      emitProgress(emitter, makeEvent("rag-preload:hits", { ...eventBase, stage: "rag-preload" }, {
+        message: `RAG preload: injected ${hits.length} chunk(s) into the task context`,
+        detail: { topK, scope, hits: hits.length, mode: searchOpts.mode, alpha: searchOpts.alpha, rerank: Boolean(searchOpts.rerankOpts) },
+      }));
+      return { skipped: false, contextBlock, hits };
+    } finally {
+      db.close();
+    }
+  } catch (err) {
+    logger?.warn?.(`[rag-preload] failed (non-blocking): ${err.message}`);
+    return { skipped: true, reason: "error", error: err.message };
+  }
+}

package/src/orchestrator/stages/rag-preload-decisor.js

@@ -0,0 +1,58 @@
+// KJC-TSK-0434 — RAG Camino D: Brain decisor heuristic for retrieval.
+// Decides WHETHER to pay the cost of running the RAG preload stage based
+// on signals from triage + task shape, instead of pre-fetching every run.
+//
+// Returns `{ pull: boolean, reason: string }`. The pre-loop driver
+// skips `runRagContextStage` when `pull === false`.
+//
+// Policies (config.rag.preload.policy):
+//   - "always"  : pull regardless (back-compat with v2.24.0 behaviour)
+//   - "never"   : never pull (useful for benchmarking, debugging)
+//   - "auto"    : heuristic — pull only when triage signals complexity,
+//                 decomposition, or when the task body is long enough
+//                 to suggest non-trivial scope. Default.
+
+const DEFAULT_POLICY = "auto";
+const COMPLEX_LEVELS = new Set(["complex", "high", "epic"]);
+const LONG_TASK_CHARS = 200;
+
+/**
+ * @param {object} params
+ * @param {object} [params.triage]   - triage stage result (may be null)
+ * @param {string} [params.task]     - the user task text
+ * @param {object} [params.config]   - full karajan config
+ * @returns {{ pull: boolean, reason: string }}
+ */
+export function shouldPreloadRag({ triage, task, config } = {}) {
+  const policy = config?.rag?.preload?.policy || DEFAULT_POLICY;
+
+  if (policy === "always") return { pull: true, reason: "policy:always" };
+  if (policy === "never") return { pull: false, reason: "policy:never" };
+
+  // policy === "auto" — apply heuristic.
+  // Brownfield is an explicit user signal — if onboarding produced a
+  // brief and config marks the project as brownfield, prior context is
+  // almost always worth pulling.
+  if (config?.rag?.preload?.brownfield === true) {
+    return { pull: true, reason: "auto:brownfield" };
+  }
+
+  // Triage said this is big enough to decompose → multi-HU run benefits
+  // from prior context fed to researcher/architect/planner.
+  if (triage?.shouldDecompose === true) {
+    return { pull: true, reason: "auto:decompose" };
+  }
+
+  // Triage classified the task as complex / high-effort.
+  if (triage?.level && COMPLEX_LEVELS.has(String(triage.level).toLowerCase())) {
+    return { pull: true, reason: "auto:complex" };
+  }
+
+  // Long task body usually means a brief with context, motivation and
+  // non-trivial scope — worth checking the RAG.
+  if (typeof task === "string" && task.length >= LONG_TASK_CHARS) {
+    return { pull: true, reason: "auto:long-task" };
+  }
+
+  return { pull: false, reason: "auto:low-value" };
+}

package/src/orchestrator/stages/research-stage.js

@@ -0,0 +1,69 @@
+/**
+ * Researcher stage logic.
+ * Extracted from pre-loop-stages.js for maintainability.
+ */
+
+import { ResearcherRole } from "../../roles/researcher-role.js";
+import { addCheckpoint } from "../../session/store.js";
+import { emitProgress, makeEvent, emitAgentOutput } from "../../utils/events.js";
+import { createStallDetector } from "../../utils/stall-detector.js";
+
+export async function runResearcherStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget }) {
+  logger.setContext({ iteration: 0, stage: "researcher" });
+
+  const researcherProvider = config?.roles?.researcher?.provider || coderRole.provider;
+  emitProgress(
+    emitter,
+    makeEvent("researcher:start", { ...eventBase, stage: "researcher" }, {
+      message: "Researcher investigating codebase",
+      detail: { researcher: researcherProvider, provider: researcherProvider, executorType: "agent" }
+    })
+  );
+
+  const researcherOnOutput = (payload) => emitAgentOutput(emitter, eventBase, "researcher", researcherProvider, payload);
+  const researcherStall = createStallDetector({
+    onOutput: researcherOnOutput, emitter, eventBase, stage: "researcher", provider: researcherProvider
+  });
+
+  const researcher = new ResearcherRole({ config, logger, emitter });
+  await researcher.init({ task: session.task });
+  const researchStart = Date.now();
+  let researchOutput;
+  try {
+    researchOutput = await researcher.run({ task: session.task, onOutput: researcherStall.onOutput });
+  } catch (err) {
+    logger.warn(`Researcher threw: ${err.message}`);
+    researchOutput = { ok: false, summary: `Researcher error: ${err.message}`, result: { error: err.message } };
+  } finally {
+    researcherStall.stop();
+  }
+  trackBudget({
+    role: "researcher",
+    provider: config?.roles?.researcher?.provider || coderRole.provider,
+    model: config?.roles?.researcher?.model || coderRole.model,
+    result: researchOutput,
+    duration_ms: Date.now() - researchStart
+  });
+
+  await addCheckpoint(session, {
+    stage: "researcher",
+    iteration: 0,
+    ok: researchOutput.ok,
+    provider: config?.roles?.researcher?.provider || coderRole.provider,
+    model: config?.roles?.researcher?.model || coderRole.model || null
+  });
+
+  emitProgress(
+    emitter,
+    makeEvent("researcher:end", { ...eventBase, stage: "researcher" }, {
+      status: researchOutput.ok ? "ok" : "fail",
+      message: researchOutput.ok ? "Research completed" : `Research failed: ${researchOutput.summary}`,
+      detail: { provider: researcherProvider, executorType: "agent" }
+    })
+  );
+
+  const stageResult = { ok: researchOutput.ok, summary: researchOutput.summary || null };
+  const researchContext = researchOutput.ok ? researchOutput.result : null;
+
+  return { researchContext, stageResult };
+}

package/src/orchestrator/stages/reviewer-stage.js

@@ -0,0 +1,422 @@
+/**
+ * Reviewer stage logic + fetchReviewDiff.
+ * Extracted from iteration-stages.js for maintainability.
+ */
+
+import { addCheckpoint, markSessionStatus, saveSession } from "../../session/store.js";
+import { setReviewerFeedback, setDeferredIssues } from "../../session/mutators.js";
+import { generateDiff } from "../../review/diff-generator.js";
+import { redactSecrets } from "../../guards/secret-redactor.js";
+import { validateReviewResult } from "../../review/schema.js";
+import { filterReviewScope } from "../../review/scope-filter.js";
+import { emitProgress, makeEvent, emitAgentOutput } from "../../utils/events.js";
+import { runReviewerWithFallback } from "../reviewer-fallback.js";
+import { invokeSolomon } from "../solomon-escalation.js";
+import { detectRateLimit } from "../../utils/rate-limit-detector.js";
+import { createStallDetector } from "../../utils/stall-detector.js";
+import { applyQuotaSimulation } from "../../utils/quota-simulator.js";
+
+function categorizeIssues(issues) {
+  const categories = { security: 0, correctness: 0, tests: 0, style: 0, other: 0 };
+  const securityKw = /inject(?:ion)?|xss|csrf|secret.?leak|credential.?expos|auth(?:entication|orization).?(?:bypass|fail|miss|broken|weak)|vulnerab|exploit|httponly|token.?expos/i;
+  const styleKw = /naming|name|rename|style|format|indent|spacing|convention|cosmetic|readability|comment|jsdoc|whitespace/i;
+  const testKw = /test|coverage|assert|spec|mock/i;
+
+  for (const issue of issues || []) {
+    const desc = issue.description || "";
+    const sev = (issue.severity || "").toLowerCase();
+    if (sev === "critical" || securityKw.test(desc)) categories.security++;
+    else if (testKw.test(desc)) categories.tests++;
+    else if (sev === "low" || sev === "minor" || styleKw.test(desc)) categories.style++;
+    else categories.correctness++;
+  }
+  return categories;
+}
+
+function buildReviewHistory(session) {
+  return (session.checkpoints || [])
+    .filter(cp => cp.stage === "reviewer")
+    .map(cp => ({ iteration: cp.iteration, note: cp.note || "" }));
+}
+
+async function handleReviewerStalledSolomon({ review, repeatCounts, repeatState, config, logger, emitter, eventBase, session, iteration, task, askQuestion, budgetSummary, repeatDetector, brainCtx }) {
+  // DETERMINISTIC GUARD: security issues NEVER go to Solomon — always return to coder
+  const categories = categorizeIssues(review.blocking_issues);
+  if (categories.security > 0) {
+    logger.info(`Reviewer found ${categories.security} security issue(s) — returning to coder (Solomon bypassed)`);
+    emitProgress(emitter, makeEvent("reviewer:security-block", { ...eventBase, stage: "reviewer" }, {
+      message: `${categories.security} security issue(s) detected — must be fixed before approval`,
+      detail: { securityCount: categories.security, blockingIssues: review.blocking_issues }
+    }));
+    return { review, solomonApproved: false };
+  }
+
+  // Brain: when enabled, ALL paths go through Brain, not Solomon
+  if (brainCtx?.enabled) {
+    const logPrefix = repeatState.stalled
+      ? `Reviewer stalled (${repeatCounts.reviewer} repeats)`
+      : `Reviewer rejected (first rejection)`;
+    logger.info(`Brain: ${logPrefix} — Brain will handle (Solomon bypassed)`);
+    emitProgress(emitter, makeEvent("brain:escalate", { ...eventBase, stage: "reviewer" }, {
+      message: `${logPrefix} — Brain handling`,
+      detail: { repeats: repeatCounts.reviewer || 1, reason: repeatState.reason || "first_rejection" }
+    }));
+    // Push reviewer feedback into Brain queue
+    const { processRoleOutput } = await import("../brain-coordinator.js");
+    processRoleOutput(brainCtx, { roleName: "reviewer", output: review, iteration });
+    return { review, solomonApproved: false };
+  }
+
+  const logPrefix = repeatState.stalled
+    ? `Reviewer stalled (${repeatCounts.reviewer} repeats)`
+    : `Reviewer rejected (first rejection)`;
+  logger.warn(`${logPrefix}. Invoking Solomon mediation.`);
+  emitProgress(
+    emitter,
+    makeEvent("solomon:escalate", { ...eventBase, stage: "reviewer" }, {
+      message: `${logPrefix} — Solomon mediating`,
+      detail: { repeats: repeatCounts.reviewer || 1, reason: repeatState.reason || "first_rejection" }
+    })
+  );
+
+  const solomonResult = await invokeSolomon({
+    config, logger, emitter, eventBase, stage: "reviewer", askQuestion, session, iteration,
+    conflict: {
+      stage: "reviewer",
+      task,
+      iterationCount: repeatCounts.reviewer || 1,
+      maxIterations: config.session?.fail_fast_repeats ?? 2,
+      isFirstRejection: !repeatState.stalled,
+      isRepeat: repeatState.stalled,
+      stalledReason: repeatState.reason || "first_rejection",
+      blockingIssues: review.blocking_issues,
+      issueCategories: categorizeIssues(review.blocking_issues),
+      history: [
+        ...buildReviewHistory(session),
+        { agent: "reviewer", feedback: review.blocking_issues.map(x => x.description).join("; ") }
+      ]
+    }
+  });
+
+  if (solomonResult.action === "approve") {
+    logger.info("Solomon overrode reviewer — approving code");
+    emitProgress(emitter, makeEvent("solomon:override", { ...eventBase, stage: "solomon" }, {
+      message: "Solomon overrode reviewer rejection — code approved",
+      detail: { ruling: solomonResult.ruling?.result?.ruling }
+    }));
+    return { review: { ...review, approved: true, solomon_override: true }, solomonApproved: true };
+  }
+  if (solomonResult.action === "pause") {
+    await markSessionStatus(session, "stalled");
+    return { review, stalled: true, stalledResult: { paused: true, sessionId: session.id, question: solomonResult.question, context: "reviewer_stalled" } };
+  }
+  if (solomonResult.action === "continue") {
+    repeatDetector.reviewer = { lastHash: null, repeatCount: 0 };
+    if (solomonResult.humanGuidance) {
+      setReviewerFeedback(session, `Solomon/user guidance: ${solomonResult.humanGuidance}`);
+      await saveSession(session);
+    }
+    return { review };
+  }
+  if (solomonResult.action === "subtask") {
+    return { review, stalled: true, stalledResult: { paused: true, sessionId: session.id, subtask: solomonResult.subtask, context: "reviewer_subtask" } };
+  }
+
+  // Fallback
+  const message = `Manual intervention required: reviewer issues repeated ${repeatCounts.reviewer || 1} times.`;
+  await markSessionStatus(session, "stalled");
+  emitProgress(
+    emitter,
+    makeEvent("session:end", { ...eventBase, stage: "reviewer" }, {
+      status: "stalled",
+      message,
+      detail: { reason: repeatState.reason, repeats: repeatCounts.reviewer, budget: budgetSummary() }
+    })
+  );
+  return { review, stalled: true, stalledResult: { approved: false, sessionId: session.id, reason: "stalled" } };
+}
+
+async function handleReviewerRejection({ review, repeatDetector, config, logger, emitter, eventBase, session, iteration, task, askQuestion, budgetSummary, brainCtx }) {
+  repeatDetector.addIteration([], review.blocking_issues);
+  const repeatState = repeatDetector.isStalled();
+
+  const solomonEnabled = Boolean(config.pipeline?.solomon?.enabled);
+
+  // Brain: if enabled and bypass_solomon_on_correctness, push issues to queue and skip Solomon
+  // for non-style rejections. Solomon is still consulted on genuine dilemmas (style-only, deadlock).
+  if (brainCtx?.enabled && config.brain?.bypass_solomon_on_correctness !== false) {
+    const cats = categorizeIssues(review.blocking_issues);
+    const nonStyleIssues = cats.security + cats.correctness + cats.tests;
+    // Only bypass if there ARE non-style issues (correctness, tests, security, or "other" is correctness)
+    // If it's style-only, let Solomon evaluate whether to override
+    if (nonStyleIssues > 0 || cats.other > 0) {
+      const { processRoleOutput } = await import("../brain-coordinator.js");
+      processRoleOutput(brainCtx, { roleName: "reviewer", output: review, iteration });
+      logger.info(`Brain: reviewer rejected with ${nonStyleIssues} non-style issue(s) — bypassing Solomon, returning to coder`);
+      emitProgress(emitter, makeEvent("brain:bypass-solomon", { ...eventBase, stage: "reviewer" }, {
+        message: `Brain: ${nonStyleIssues} non-style issue(s) — sending to coder without Solomon`,
+        detail: { categories: cats, queueSize: brainCtx.feedbackQueue.entries.length }
+      }));
+      // Persist flat feedback for compat with non-Brain flow
+      setReviewerFeedback(session, review.blocking_issues
+        .map((x, idx) => `R-${idx + 1} [${x.severity || "medium"}]: ${x.description}`)
+        .join("\n"));
+      await saveSession(session);
+      return null; // null = continue to next iteration (coder fixes)
+    }
+    logger.info("Brain: reviewer rejected with style-only issues — consulting Solomon for dilemma");
+  }
+
+  // When Solomon is disabled, only act on stalls (legacy behavior)
+  if (!solomonEnabled) {
+    if (!repeatState.stalled) return null;
+    const repeatCounts = repeatDetector.getRepeatCounts();
+    return handleReviewerStalledSolomon({
+      review, repeatCounts, repeatState, config, logger, emitter,
+      eventBase, session, iteration, task, askQuestion,
+      budgetSummary, repeatDetector, brainCtx
+    });
+  }
+
+  // Solomon evaluates EVERY rejection
+  const repeatCounts = repeatDetector.getRepeatCounts();
+  const evaluateEventName = brainCtx?.enabled ? "brain:evaluate" : "solomon:evaluate";
+  logger.info(`Reviewer rejected — ${brainCtx?.enabled ? "Brain" : "Solomon"} evaluating ${review.blocking_issues.length} blocking issue(s)`);
+  emitProgress(emitter, makeEvent(evaluateEventName, { ...eventBase, stage: brainCtx?.enabled ? "brain" : "solomon" }, {
+    message: `${brainCtx?.enabled ? "Brain" : "Solomon"} evaluating reviewer rejection`,
+    detail: { blockingCount: review.blocking_issues.length, isRepeat: repeatState.stalled }
+  }));
+
+  return handleReviewerStalledSolomon({
+    review, repeatCounts, repeatState, config, logger, emitter,
+    eventBase, session, iteration, task, askQuestion,
+    budgetSummary, repeatDetector, brainCtx
+  });
+}
+
+export async function fetchReviewDiff(session, logger, projectDir = null) {
+  let diff;
+  if (session.ci_pr_number) {
+    const { getPrDiff } = await import("../../ci/pr-diff.js");
+    diff = await getPrDiff(session.ci_pr_number);
+    logger.info(`Reviewer reading PR diff #${session.ci_pr_number}`);
+  } else {
+    diff = await generateDiff({ baseRef: session.session_start_sha, stageNewFiles: true, projectDir });
+  }
+  // Inbound boundary: mask hardcoded secrets before the diff reaches the
+  // (possibly cloud) reviewer model. Runs BEFORE the injection guard below so
+  // that guard still sees the real prompt-injection phrasing (KJC-TSK-0583).
+  return redactSecrets(diff);
+}
+
+export async function runReviewerStage({ reviewerRole, config, logger, emitter, eventBase, session, trackBudget, iteration, reviewRules, task, repeatDetector, budgetSummary, askQuestion, brainCtx }) {
+  logger.setContext({ iteration, stage: "reviewer" });
+  emitProgress(
+    emitter,
+    makeEvent("reviewer:start", { ...eventBase, stage: "reviewer" }, {
+      message: `Reviewer (${reviewerRole.provider}) running`,
+      detail: { reviewer: reviewerRole.provider, provider: reviewerRole.provider, executorType: "agent" }
+    })
+  );
+
+  let diff;
+  try {
+    diff = await fetchReviewDiff(session, logger, config?.projectDir || null);
+  } catch (err) {
+    logger.warn(`Review diff generation failed: ${err.message}`);
+    return { approved: false, blocking_issues: [{ description: `Diff generation failed: ${err.message}` }], non_blocking_suggestions: [], summary: `Reviewer failed: cannot generate diff — ${err.message}`, confidence: 0 };
+  }
+
+  // Injection guard: scan diff before sending to AI reviewer
+  const { scanDiff } = await import("../../utils/injection-guard.js");
+  const guardResult = scanDiff(diff);
+  if (!guardResult.clean) {
+    logger.warn(`Injection guard: ${guardResult.summary}`);
+    emitProgress(emitter, makeEvent("guard:injection", { ...eventBase, stage: "reviewer" }, {
+      message: `Injection guard blocked review: ${guardResult.summary}`,
+      detail: { findings: guardResult.findings, summary: guardResult.summary }
+    }));
+    return {
+      approved: false,
+      blocking_issues: guardResult.findings.map((f) => ({
+        id: `INJECTION_${f.type.toUpperCase()}`,
+        severity: "critical",
+        description: `Potential prompt injection (${f.type}): ${f.snippet}`,
+        line: f.line,
+      })),
+      non_blocking_suggestions: [],
+      summary: `Review blocked by injection guard: ${guardResult.summary}`,
+      confidence: 1,
+    };
+  }
+
+  const reviewerOnOutput = (payload) => emitAgentOutput(emitter, eventBase, "reviewer", reviewerRole.provider, payload);
+  const reviewerStall = createStallDetector({
+    onOutput: reviewerOnOutput, emitter, eventBase, stage: "reviewer", provider: reviewerRole.provider
+  });
+  const reviewerStart = Date.now();
+  let reviewerExec;
+  try {
+    reviewerExec = await runReviewerWithFallback({
+      reviewerName: reviewerRole.provider,
+      config,
+      logger,
+      emitter,
+      reviewInput: { task, diff, reviewRules, onOutput: reviewerStall.onOutput },
+      session,
+      iteration,
+      onAttemptResult: ({ reviewer, result }) => {
+        trackBudget({ role: "reviewer", provider: reviewer, model: reviewerRole.model, result, duration_ms: Date.now() - reviewerStart });
+      }
+    });
+  } catch (err) {
+    logger.warn(`Reviewer threw: ${err.message}`);
+    reviewerExec = { execResult: { ok: false, error: err.message }, attempts: [{ reviewer: reviewerRole.provider, result: { ok: false, error: err.message } }] };
+  } finally {
+    reviewerStall.stop();
+  }
+
+  if (applyQuotaSimulation(reviewerExec.execResult, { iteration, agent: reviewerRole.provider })) {
+    // Reviewer wraps the agent call: detectRateLimit reads `lastAttempt.result.error`,
+    // so propagate the synthetic line into the most recent attempt too.
+    const last = reviewerExec.attempts?.at(-1);
+    if (last) {
+      if (!last.result || typeof last.result !== "object") last.result = {};
+      last.result.error = reviewerExec.execResult.result.error;
+    }
+  }
+
+  if (!reviewerExec.execResult?.ok) {
+    const lastAttempt = reviewerExec.attempts.at(-1);
+    const details =
+      lastAttempt?.result?.error ||
+      lastAttempt?.execResult?.summary ||
+      `reviewer=${lastAttempt?.reviewer || "unknown"}`;
+
+    const rateLimitCheck = detectRateLimit({
+      stderr: lastAttempt?.result?.error || "",
+      stdout: lastAttempt?.result?.output || ""
+    });
+
+    if (rateLimitCheck.isRateLimit) {
+      // Enter standby instead of pausing
+      return {
+        action: "standby",
+        standbyInfo: {
+          agent: reviewerRole.provider,
+          cooldownMs: rateLimitCheck.cooldownMs || (rateLimitCheck.isProviderOutage ? 30000 : null),
+          cooldownUntil: rateLimitCheck.cooldownUntil,
+          message: rateLimitCheck.message,
+          isProviderOutage: rateLimitCheck.isProviderOutage || false
+        }
+      };
+    }
+
+    await markSessionStatus(session, "failed");
+    emitProgress(
+      emitter,
+      makeEvent("reviewer:end", { ...eventBase, stage: "reviewer" }, {
+        status: "fail",
+        message: `Reviewer failed: ${details}`,
+        detail: { provider: reviewerRole.provider, executorType: "agent" }
+      })
+    );
+    throw new Error(`Reviewer failed: ${details}`);
+  }
+
+  const reviewResult = reviewerExec.execResult.result;
+  let review;
+  try {
+    review = validateReviewResult({
+      approved: reviewResult.approved,
+      blocking_issues: reviewResult.blocking_issues || [],
+      non_blocking_suggestions: reviewResult.non_blocking_suggestions || [],
+      summary: reviewResult.raw_summary || "",
+      confidence: reviewResult.confidence ?? 0
+    });
+  } catch (error_) {
+    logger.warn(`Reviewer output validation failed: ${error_.message}`);
+    review = {
+      approved: false,
+      blocking_issues: [{
+        id: "PARSE_ERROR",
+        severity: "high",
+        description: `Reviewer output could not be parsed: ${error_.message}`
+      }],
+      non_blocking_suggestions: [],
+      summary: `Parse error: ${error_.message}`,
+      confidence: 0
+    };
+  }
+  // --- Scope filter: auto-defer out-of-scope blocking issues ---
+  const { review: filteredReview, demoted, deferred, allDemoted } = filterReviewScope(review, diff);
+  review = filteredReview;
+
+  if (demoted.length > 0) {
+    logger.info(`Scope filter: deferred ${demoted.length} out-of-scope issue(s)${allDemoted ? " — auto-approved" : ""}`);
+
+    // Accumulate deferred issues in session for tracking
+    if (!session.deferred_issues) setDeferredIssues(session, []);
+    session.deferred_issues.push(...deferred);
+    await saveSession(session);
+
+    emitProgress(
+      emitter,
+      makeEvent("reviewer:scope_filter", { ...eventBase, stage: "reviewer" }, {
+        message: `Scope filter deferred ${demoted.length} out-of-scope issue(s)`,
+        detail: {
+          demotedCount: demoted.length,
+          autoApproved: allDemoted,
+          totalDeferred: session.deferred_issues.length,
+          deferred: deferred.map(d => ({ file: d.file, id: d.id, description: d.description }))
+        }
+      })
+    );
+    await addCheckpoint(session, {
+      stage: "reviewer-scope-filter",
+      iteration,
+      demoted_count: demoted.length,
+      auto_approved: allDemoted,
+      total_deferred: session.deferred_issues.length
+    });
+  }
+
+  // Feedback signature for stale detection: concatenated issue descriptions
+  const feedbackSignature = review.blocking_issues
+    .map(x => (x.description || "").slice(0, 120))
+    .join("|") || "approved";
+
+  await addCheckpoint(session, {
+    stage: "reviewer",
+    iteration,
+    approved: review.approved,
+    blocking_issues: review.blocking_issues.length,
+    provider: reviewerRole.provider,
+    model: reviewerRole.model || null,
+    note: feedbackSignature
+  });
+
+  emitProgress(
+    emitter,
+    makeEvent("reviewer:end", { ...eventBase, stage: "reviewer" }, {
+      status: review.approved ? "ok" : "fail",
+      message: review.approved ? "Review approved" : `Review rejected (${review.blocking_issues.length} blocking)`,
+      detail: {
+        approved: review.approved,
+        blockingCount: review.blocking_issues.length,
+        issues: review.blocking_issues.map(
+          (x) => `${x.id || "ISSUE"}: ${x.description || "Missing description"}`
+        ),
+        provider: reviewerRole.provider,
+        executorType: "agent"
+      }
+    })
+  );
+
+  if (!review.approved) {
+    const rejectionResult = await handleReviewerRejection({ review, repeatDetector, config, logger, emitter, eventBase, session, iteration, task, askQuestion, budgetSummary, brainCtx });
+    if (rejectionResult) return rejectionResult;
+  }
+
+  return { review };
+}