karajan-code 2.7.4 → 2.9.0

package/src/orchestrator/preflight-checks.js

@@ -16,7 +16,6 @@ import { emitProgress, makeEvent } from "../utils/events.js";
 import { msg, getLang } from "../utils/messages.js";
 import {
   resolveSonarHost,
-  resolveSonarToken,
   resolveSonarTokenAsync,
   resolveSonarCredentials,
 } from "../sonar/config-resolver.js";
@@ -30,6 +29,7 @@ import { getPortChecks } from "../checks/ports.js";
 import { getTokenChecks } from "../checks/tokens.js";
 import { getMcpHealthChecks } from "../checks/mcp-health.js";
 import { getSkillsChecks } from "../checks/skills.js";
+import { resolveTestHarness } from "../config/test-harness.js";
 
 function parseJsonSafe(text) {
   try {
@@ -168,6 +168,14 @@ async function checkSecurityAgent(config) {
  * @returns {{ ok: boolean, checks: object[], remediations: string[], configOverrides: object, warnings: string[], errors: object[] }}
  */
 export async function runPreflightChecks({ config, logger, emitter, eventBase, resolvedPolicies, securityEnabled }) {
+  // Defensive test-harness resolution for direct callers that bypass loadConfig()
+  // (notably tests/preflight-checks.test.js and tests/sonar-token-flow.test.js
+  // which construct raw configs). Production callers go through loadConfig
+  // which already populates config.testHarness once via resolveTestHarness().
+  // Idempotent — no-op when already present.
+  if (config && !config.testHarness) {
+    config.testHarness = resolveTestHarness(config.testHarness);
+  }
   // Sonar is intrinsic to Karajan for code tasks (sw/refactor/add-tests).
   // Since v2.7.4 it is NOT toggleable via `config.sonarqube.enabled` —
   // that field is ignored (deprecation warning emitted at config load).
@@ -177,11 +185,14 @@ export async function runPreflightChecks({ config, logger, emitter, eventBase, r
   // no-code skip it. Solomon may decide to skip a single iteration via
   // rule alerts — that's a runtime decision, not a config option.
   //
-  // Test-only escape hatch: globalThis.__KJ_DISABLE_SONAR_STAGE === true
-  // forces sonar OFF in preflight too, so tests that don't want sonar
-  // events in their expected sequence don't have to set up Docker mocks.
-  // Set in tests/setup.js by default; production code never sees it.
-  const sonarStageDisabledForTest = globalThis.__KJ_DISABLE_SONAR_STAGE === true;
+  // Test-harness escape hatch via config.testHarness.disableSonarStage
+  // — production code reads `config?.testHarness?.disableSonarStage`,
+  // never `globalThis.*`. The legacy `globalThis.__KJ_DISABLE_SONAR_STAGE`
+  // shape is documented (and exclusively read) in
+  // src/config/test-harness.js, where the loader translates it into
+  // the typed config slot above. ESLint rule (#557) blocks any
+  // re-introduction outside that one file.
+  const sonarStageDisabledForTest = config?.testHarness?.disableSonarStage === true;
   const sonarEnabled = !sonarStageDisabledForTest && resolvedPolicies.sonar !== false;
   const isExternalSonar = Boolean(config.sonarqube?.external);
   const sonarHost = resolveSonarHost(config.sonarqube?.host);
@@ -196,7 +207,9 @@ export async function runPreflightChecks({ config, logger, emitter, eventBase, r
   };
 
   // Resolve extended preflight opt-in early so the short-circuit below can see it.
-  const extendedDefault = globalThis.__KJ_DEFAULT_PREFLIGHT_EXTENDED ?? true;
+  // Post-v2.7.5 this no longer reads globalThis directly — config.testHarness
+  // is populated by the loader from the global or the default.
+  const extendedDefault = config?.testHarness?.defaultPreflightExtended ?? true;
   const extendedEnabled = config?.preflight?.extended ?? extendedDefault;
 
   // Preserve legacy short-circuit: if nothing at all needs checking, skip

package/src/orchestrator/repair/repair-detector.js

@@ -0,0 +1,117 @@
+/**
+ * Heuristics for classifying an acceptance-test failure as "possibly
+ * infeasible" — i.e. the test itself looks broken, not the code.
+ *
+ * Used by the HU sub-pipeline to decide when to invoke the Repairer
+ * role instead of feeding the failure back to the coder for ANOTHER
+ * iteration. Each iteration costs real money + time; classifying
+ * misroutes is the difference between a 3-minute repair and a
+ * 30-minute budget burn.
+ *
+ * The classifier is deliberately CONSERVATIVE: false negatives
+ * (treating a broken test as just-failed) cost an extra iteration;
+ * false positives (treating a real failure as infeasible) waste a
+ * Repairer call AND give the coder a spec change it shouldn't
+ * receive. We err toward false negatives.
+ */
+
+/**
+ * Signatures that strongly suggest the TEST is broken, not the code.
+ * Each is a regex applied to the failing command's stderr+stdout.
+ */
+const INFEASIBLE_SIGNATURES = [
+  // jq: `length as $n | .field` after a transform — the binding doesn't
+  // change the value flowing through, so `.field` is applied to the wrong
+  // thing. Real-world example from 2026-04-29: "Cannot index array with
+  // string \"filesOver300LOC\"".
+  { kind: "jq-as-binding-misuse", re: /Cannot index array with string/i },
+  // bash -n / shell parse errors before the command even runs.
+  { kind: "shell-parse-error", re: /syntax error|unexpected token|unexpected EOF/i },
+  // jq: invalid query syntax detected by jq itself.
+  { kind: "jq-syntax", re: /jq: error \(at .*\): (?!Cannot index)/i },
+  // command not found = test references a tool that doesn't exist in
+  // this environment. Could be a fixable typo or a real env mismatch.
+  { kind: "missing-tool", re: /command not found|: not found$|No such file or directory.*\.(sh|mjs|js|py)/im },
+  // jq fails to parse the JSON input — the input file is wrong, the
+  // path is wrong, or the assumed schema is off.
+  { kind: "jq-parse-input", re: /jq: error: Could not (open|parse)/i },
+];
+
+/**
+ * Compute a stable signature for a single failing test outcome — the
+ * test command + a normalized error fingerprint. Used to detect when
+ * the SAME test is failing the SAME way across iterations; that's the
+ * pattern that argues for a Repairer call (vs. a coder retry).
+ *
+ * @param {string} cmd
+ * @param {string} errorOutput
+ * @returns {string}
+ */
+export function failureSignature(cmd, errorOutput) {
+  const cmdNorm = String(cmd || "").trim().slice(0, 200);
+  const errNorm = String(errorOutput || "")
+    .replace(/\s+/g, " ")        // collapse whitespace
+    .replace(/\d+/g, "N")          // numbers tend to drift; line numbers, counts
+    .replace(/\/[^\s]+/g, "/PATH") // absolute paths drift across runs
+    .trim()
+    .slice(0, 300);
+  return `${cmdNorm}|||${errNorm}`;
+}
+
+/**
+ * Classify a single test failure as `infeasible` or `regular`.
+ *
+ * @param {object} args
+ * @param {string} args.cmd          — the command that ran
+ * @param {string} args.errorOutput  — stdout + stderr from the failing run
+ * @param {number} args.consecutive  — how many iterations in a row this
+ *                                      same signature has failed
+ * @param {number} [args.threshold=2] — min consecutive failures before
+ *                                       infeasibility is even considered.
+ *                                       Below this, we always say "regular"
+ *                                       (let the coder try once more).
+ * @returns {{infeasible: boolean, kind: string|null, signature: string}}
+ */
+export function classifyFailure({ cmd, errorOutput, consecutive, threshold = 2 }) {
+  const signature = failureSignature(cmd, errorOutput);
+  if (!Number.isFinite(consecutive) || consecutive < threshold) {
+    return { infeasible: false, kind: null, signature };
+  }
+  for (const sig of INFEASIBLE_SIGNATURES) {
+    if (sig.re.test(errorOutput || "")) {
+      return { infeasible: true, kind: sig.kind, signature };
+    }
+  }
+  return { infeasible: false, kind: null, signature };
+}
+
+/**
+ * Track consecutive identical failures across iterations of the same HU.
+ * Caller passes the same instance across iterations; the tracker
+ * remembers the last signature per command.
+ */
+export function createFailureTracker() {
+  // Map<cmd, { signature, count }>
+  const state = new Map();
+  return {
+    /**
+     * Record a failure and return how many consecutive iterations have
+     * produced the same signature for this cmd.
+     * @returns {number}
+     */
+    record(cmd, errorOutput) {
+      const signature = failureSignature(cmd, errorOutput);
+      const prev = state.get(cmd);
+      if (prev && prev.signature === signature) {
+        prev.count += 1;
+        return prev.count;
+      }
+      state.set(cmd, { signature, count: 1 });
+      return 1;
+    },
+    /** Reset tracker for a cmd that just passed (stops false positives). */
+    reset(cmd) { state.delete(cmd); },
+    /** Diagnostic: dump current state. */
+    snapshot() { return Object.fromEntries(state); },
+  };
+}

package/src/orchestrator/repair/repair-runner.js

@@ -0,0 +1,142 @@
+/**
+ * Repair runner — orchestrates the Repairer role end-to-end.
+ *
+ * Called from run-hu-batch when an acceptance test failure has been
+ * classified as `infeasible` by repair-detector. The runner:
+ *   1. Builds the prompt context (failing test, error output, HU
+ *      intent, sibling tests).
+ *   2. Invokes RepairerRole.
+ *   3. If verdict=fixable: patches the plan JSON's acceptance_tests
+ *      AND the in-memory batch story so the next coder iteration sees
+ *      the corrected test. Saves both. Returns { repaired: true }.
+ *   4. If verdict=unfixable: returns { repaired: false, escalate: true,
+ *      reason } so the caller can hand off to Solomon / FDE.
+ *   5. If RepairerRole itself fails (agent error): returns
+ *      { repaired: false, escalate: false, error } so the caller
+ *      decides whether to retry coder or escalate.
+ */
+
+import { RepairerRole } from "../../roles/repairer-role.js";
+import { saveHuBatch } from "../../hu/store.js";
+import { emitProgress, makeEvent } from "../../utils/events.js";
+
+/**
+ * @param {object} args
+ * @param {object} args.story       — the HU story object (in-memory batch slice). MUTATED.
+ * @param {number} args.testIndex   — index in story.acceptance_tests of the failing test.
+ * @param {string} args.errorOutput — last failing run's stderr+stdout.
+ * @param {string} args.batchSessionId
+ * @param {object} args.batch       — full batch object. MUTATED (story is a slice).
+ * @param {object} args.config
+ * @param {object} args.logger
+ * @param {object} args.emitter
+ * @param {object} args.eventBase
+ * @param {string} args.failureKind — repair-detector's `kind` (e.g. "jq-as-binding-misuse").
+ * @param {Function} [args.savePlanPatch] — async (huId, fieldPatch) => void; if provided,
+ *                                          patches the plan JSON on disk too.
+ * @returns {Promise<{repaired: boolean, escalate?: boolean, reason?: string, error?: string}>}
+ */
+export async function runRepair({
+  story, testIndex, errorOutput, batchSessionId, batch,
+  config, logger, emitter, eventBase, failureKind, savePlanPatch,
+}) {
+  if (!story || !Array.isArray(story.acceptance_tests) || !story.acceptance_tests[testIndex]) {
+    return { repaired: false, escalate: false, error: "repair-runner: invalid story or testIndex" };
+  }
+
+  const failingTest = story.acceptance_tests[testIndex];
+  const siblingTests = story.acceptance_tests.filter((_, i) => i !== testIndex);
+
+  emitProgress(emitter, makeEvent("repair:start", { ...eventBase, stage: "repair" }, {
+    message: `Repairer invoked for HU ${story.id} test #${testIndex} (kind=${failureKind})`,
+    detail: {
+      huId: story.id,
+      testIndex,
+      testContent: typeof failingTest === "object" ? failingTest.content : failingTest,
+      kind: failureKind,
+    },
+  }));
+
+  const repairer = new RepairerRole({ config, logger, emitter });
+  await repairer.init({ task: story.scope || story.title || story.id, sessionId: batchSessionId, iteration: 0 });
+
+  let result;
+  try {
+    result = await repairer.run({
+      failingTest,
+      errorOutput,
+      huTitle: story.title || story.id,
+      huScope: story.scope || "",
+      siblingTests,
+      iteration: 0,
+    });
+  } catch (err) {
+    logger.warn(`Repairer threw: ${err.message}`);
+    emitProgress(emitter, makeEvent("repair:end", { ...eventBase, stage: "repair" }, {
+      status: "fail",
+      message: `Repairer error: ${err.message}`,
+      detail: { huId: story.id, testIndex },
+    }));
+    return { repaired: false, escalate: false, error: err.message };
+  }
+
+  if (!result?.ok) {
+    logger.warn(`Repairer failed: ${result?.summary || "unknown"}`);
+    emitProgress(emitter, makeEvent("repair:end", { ...eventBase, stage: "repair" }, {
+      status: "fail",
+      message: `Repairer could not produce a verdict: ${result?.summary || "unknown"}`,
+      detail: { huId: story.id, testIndex },
+    }));
+    return { repaired: false, escalate: false, error: result?.summary || "no verdict" };
+  }
+
+  const { verdict, fixed_test: fixedTest, reason } = result.result;
+
+  if (verdict === "unfixable") {
+    logger.info(`Repairer: HU ${story.id} test #${testIndex} unfixable — ${reason}`);
+    emitProgress(emitter, makeEvent("repair:end", { ...eventBase, stage: "repair" }, {
+      status: "escalate",
+      message: `Repairer: unfixable — ${reason}`,
+      detail: { huId: story.id, testIndex, reason },
+    }));
+    return { repaired: false, escalate: true, reason };
+  }
+
+  if (verdict !== "fixable" || !fixedTest) {
+    logger.warn(`Repairer returned unexpected verdict: ${verdict}`);
+    return { repaired: false, escalate: false, error: `unexpected verdict: ${verdict}` };
+  }
+
+  // Apply the fix in-memory and persist when we have the batch handle.
+  // Some callers can't pass `batch` from their scope (closure depth);
+  // the in-memory mutation of `story.acceptance_tests` is enough for
+  // the next iteration of the same HU loop because every acceptance
+  // run reads the live story object. Disk persistence is a "next run
+  // sees the fix too" optimisation; PR #544's reconcile keeps the
+  // plan JSON consistent across runs in either case.
+  story.acceptance_tests[testIndex] = fixedTest;
+  if (batch && batchSessionId) {
+    await saveHuBatch(batchSessionId, batch);
+  }
+
+  if (typeof savePlanPatch === "function") {
+    try {
+      await savePlanPatch(story.id, { acceptance_tests: story.acceptance_tests });
+    } catch (err) {
+      logger.warn(`Repairer: in-memory + batch fixed but plan-patch failed: ${err.message}`);
+    }
+  }
+
+  logger.info(`Repairer: HU ${story.id} test #${testIndex} REPAIRED — ${reason}`);
+  emitProgress(emitter, makeEvent("repair:end", { ...eventBase, stage: "repair" }, {
+    status: "ok",
+    message: `Repairer fixed HU ${story.id} test #${testIndex}: ${reason}`,
+    detail: {
+      huId: story.id,
+      testIndex,
+      reason,
+      fixedContent: typeof fixedTest === "object" ? fixedTest.content : fixedTest,
+    },
+  }));
+  return { repaired: true, reason };
+}

package/src/orchestrator/reviewer-fallback.js

@@ -1,6 +1,6 @@
 import { ReviewerRole } from "../roles/reviewer-role.js";
 import { createAgent } from "../agents/index.js";
-import { addCheckpoint } from "../session-store.js";
+import { addCheckpoint } from "../session/store.js";
 
 export async function runReviewerWithFallback({ reviewerName, config, logger, emitter, reviewInput, session, iteration, onAttemptResult }) {
   const fallbackReviewer = config.reviewer_options?.fallback_reviewer;

package/src/orchestrator/role-output-compressor.js

@@ -187,4 +187,3 @@ export function measureCompression(original, compressed) {
   };
 }
 
-export { COMPRESSORS };

package/src/orchestrator/session-journal.js

@@ -2,7 +2,6 @@
 // Creates .reviews/session_*/ directories containing markdown files per stage.
 import fs from "node:fs/promises";
 import path from "node:path";
-import { runCommand } from "../utils/process.js";
 
 /**
  * Create the journal directory for a session.
@@ -174,29 +173,6 @@ export function formatDecision({ timestamp, trigger, context, action, reasoning
   return lines.join("\n");
 }
 
-// ── Tree of affected files ───────────────────────────────────────────────────
-
-export async function generateFileTree(baseRef) {
-  try {
-    const result = await runCommand("git", ["diff", "--name-status", `${baseRef}...HEAD`]);
-    if (result.exitCode !== 0 || !result.stdout?.trim()) return null;
-
-    const lines = ["# Affected Files\n"];
-    const statusMap = { M: "modified", A: "added", D: "deleted", R: "renamed" };
-
-    for (const line of result.stdout.trim().split("\n")) {
-      const [status, ...fileParts] = line.split("\t");
-      const file = fileParts.join("\t");
-      const label = statusMap[status?.[0]] || status;
-      lines.push(`- [${label}] ${file}`);
-    }
-
-    return lines.join("\n");
-  } catch {
-    return null;
-  }
-}
-
 // ── Summary ──────────────────────────────────────────────────────────────────
 
 export function generateSummary({ task, result, sessionId, iterations, durationMs, budget, stages, commits, files }) {
@@ -325,20 +301,7 @@ export async function writeDecisionsJournal(journalDir, decisionEntries) {
   await writeJournalFile(journalDir, "decisions.md", content);
 }
 
-/**
- * Write the file tree.
- */
-export async function writeTreeJournal(journalDir, baseRef) {
-  const tree = await generateFileTree(baseRef);
-  if (tree) await writeJournalFile(journalDir, "tree.txt", tree);
-  return Boolean(tree);
-}
-
-/**
- * Write the session summary.
- */
-export async function writeSummaryJournal(journalDir, summaryData) {
-  const files = summaryData.files || [];
-  const content = generateSummary({ ...summaryData, files: [...files, "summary.md"] });
-  await writeJournalFile(journalDir, "summary.md", content);
-}
+// writeTreeJournal / writeSummaryJournal / generateFileTree were
+// superseded in v2.7.x by src/session/journal/{tree-writer,summary-writer}.js
+// (the V2 split). post-loop.js dynamically imports the V2 versions; this
+// orchestrator-side copy is no longer wired anywhere. KJC-TSK-0354 PR-D.

package/src/orchestrator/solomon-escalation.js

@@ -1,5 +1,6 @@
 import { SolomonRole } from "../roles/solomon-role.js";
-import { addCheckpoint, pauseSession, saveSession } from "../session-store.js";
+import { addCheckpoint, pauseSession, saveSession } from "../session/store.js";
+import { setSuggestions } from "../session/mutators.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
 import { msg, getLang } from "../utils/messages.js";
 
@@ -158,7 +159,7 @@ export async function invokeSolomon({ config, logger, emitter, eventBase, stage,
 
   // Clear processed suggestions from session
   if (pendingSuggestions) {
-    session.suggestions = [];
+    setSuggestions(session, []);
     try { await saveSession(session); } catch { /* best-effort */ }
   }
 

package/src/orchestrator/solomon-rules.js

@@ -118,11 +118,15 @@ export async function buildRulesContext({ session, task, iteration, blockingIssu
 
   // Count files changed via git
   try {
-    const { execaCommand } = await import("execa");
+    // Audit follow-up: was using execaCommand with template-string
+    // interpolation of `baseRef`. baseRef comes from session state, not
+    // user input, but the shape is a known shell-injection vector.
+    // Switched to execa with arg arrays so no shell expansion happens.
+    const { execa } = await import("execa");
     const baseRef = session.session_start_sha || "HEAD~1";
 
     // Files changed
-    const diffResult = await execaCommand(`git diff --name-only ${baseRef}`, { reject: false });
+    const diffResult = await execa("git", ["diff", "--name-only", String(baseRef)], { reject: false });
     if (diffResult.stdout) {
       const files = diffResult.stdout.split("\n").filter(Boolean);
       context.filesChanged = files.length;
@@ -142,7 +146,7 @@ export async function buildRulesContext({ session, task, iteration, blockingIssu
       // Detect new dependencies
       if (files.includes("package.json")) {
         try {
-          const pkgDiff = await execaCommand(`git diff ${baseRef} -- package.json`, { reject: false });
+          const pkgDiff = await execa("git", ["diff", String(baseRef), "--", "package.json"], { reject: false });
           const addedDeps = (pkgDiff.stdout || "").split("\n")
             .filter(line => line.startsWith("+") && line.includes('"') && !line.startsWith("+++"))
             .map(line => {

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

@@ -5,10 +5,10 @@
 
 import { ArchitectRole } from "../../roles/architect-role.js";
 import { createAgent } from "../../agents/index.js";
-import { createArchitectADRs } from "../../planning-game/architect-adrs.js";
-import { addCheckpoint } from "../../session-store.js";
+import { addCheckpoint } from "../../session/store.js";
 import { emitProgress, makeEvent, emitAgentOutput } from "../../utils/events.js";
 import { createStallDetector } from "../../utils/stall-detector.js";
+import { getIntegration } from "../integrations.js";
 
 async function handleArchitectClarification({ architectOutput, askQuestion, config, logger, emitter, eventBase, session, architectOnOutput, architectProvider, coderRole, researchContext, discoverResult, triageLevel, trackBudget }) {
   if (!architectOutput.ok
@@ -140,9 +140,10 @@ export async function runArchitectStage({ config, logger, emitter, eventBase, se
 
   const architectContext = architectOutput.ok ? architectOutput.result : null;
 
-  // TODO: Move ADR creation to planning-game/pipeline-adapter.js (PG coupling still here because
-  // stageResult.adrs is consumed synchronously within runArchitectStage's return value).
-  // Generate ADRs from architect tradeoffs when PG is linked
+  // TSK-0339: ADR creation is now a tracker hook. The orchestrator ships the
+  // tradeoffs; the registered adapter decides whether/how to persist them
+  // (PG creates ADR cards, another tracker might create Jira issues, an
+  // unregistered tracker is a no-op).
   const tradeoffs = architectOutput.result?.architecture?.tradeoffs;
   if (architectOutput.ok
     && architectOutput.result?.verdict === "ready"
@@ -150,17 +151,17 @@ export async function runArchitectStage({ config, logger, emitter, eventBase, se
     && session.pg_task_id
     && session.pg_project_id) {
     try {
-      const pgClient = await import("../../planning-game/client.js");
-      const adrResult = await createArchitectADRs({
+      const adrResult = await getIntegration("tracker")?.createAdrsFromTradeoffs?.({
         tradeoffs,
         pgTaskId: session.pg_task_id,
         pgProject: session.pg_project_id,
         taskTitle: session.task,
-        mcpClient: pgClient
       });
-      stageResult.adrs = adrResult;
-      if (adrResult.created > 0) {
-        logger.info(`Architect: created ${adrResult.created} ADR(s) in Planning Game`);
+      if (adrResult) {
+        stageResult.adrs = adrResult;
+        if (adrResult.created > 0) {
+          logger.info(`Architect: created ${adrResult.created} ADR(s) in tracker`);
+        }
       }
     } catch (err) {
       logger.warn(`Architect: failed to create ADRs: ${err.message}`);

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

@@ -6,7 +6,10 @@
 import { createAgent } from "../../agents/index.js";
 import { CoderRole } from "../../roles/coder-role.js";
 import { RefactorerRole } from "../../roles/refactorer-role.js";
-import { addCheckpoint, markSessionStatus, saveSession } from "../../session-store.js";
+import { addCheckpoint, markSessionStatus, saveSession } from "../../session/store.js";
+import {
+  setReviewerFeedback, incrementRetryCount, resetRetryCount,
+} from "../../session/mutators.js";
 import { generateDiff, getUntrackedFiles } from "../../review/diff-generator.js";
 import { evaluateTddPolicy } from "../../review/tdd-policy.js";
 import { buildDeferredContext } from "../../review/scope-filter.js";
@@ -15,8 +18,9 @@ import { runCoderWithFallback } from "../agent-fallback.js";
 import { invokeSolomon } from "../solomon-escalation.js";
 import { detectRateLimit } from "../../utils/rate-limit-detector.js";
 import { createStallDetector } from "../../utils/stall-detector.js";
+import { snapshotHomeTopLevel, detectNewHomeEntries, formatLeakMessage, verifyLeaksAgainstTranscript } from "../fs-leak-detector.js";
 
-export async function runCoderStage({ coderRoleInstance, coderRole, config, logger, emitter, eventBase, session, plannedTask, trackBudget, iteration, brainCtx }) {
+export async function runCoderStage({ coderRoleInstance, coderRole, config, logger, emitter, eventBase, session, plannedTask, trackBudget, iteration, brainCtx, acceptanceTests = null, adrs = null, specSection = null, reviewerFindings = null, huId = null }) {
   logger.setContext({ iteration, stage: "coder" });
   emitProgress(
     emitter,
@@ -42,6 +46,12 @@ export async function runCoderStage({ coderRoleInstance, coderRole, config, logg
     onOutput: coderOnOutput, emitter, eventBase, stage: "coder", provider: coderRole.provider
   });
   const coderStart = Date.now();
+  // KJC-BUG-0032 (PR-I): snapshot $HOME's top-level entries BEFORE
+  // the coder runs so we can detect leaks afterwards. The bug: a HU
+  // titled "Initialize project skeleton: create assistant/…" had
+  // Claude run `cd /home/manu/assistant && pnpm init …` and 36 MB
+  // of code landed outside projectDir, outside any git repo.
+  const homeSnapshotBeforeCoder = snapshotHomeTopLevel();
   let coderExecResult;
   try {
     coderExecResult = await coderRoleInstance.execute({
@@ -49,6 +59,13 @@ export async function runCoderStage({ coderRoleInstance, coderRole, config, logg
       reviewerFeedback,
       sonarSummary: session.last_sonar_summary,
       deferredContext: buildDeferredContext(session.deferred_issues),
+      // Tests-first contract flows through to buildCoderPrompt which
+      // renders the "Acceptance Tests — MUST pass" section.
+      acceptanceTests,
+      // PR F (v2.7.5): plan-aware context. ADRs apply to every HU on
+      // the plan, the rest are scoped to this HU. All four pass through
+      // untouched when the caller omits them (legacy single-task runs).
+      adrs, specSection, reviewerFindings, huId,
       onOutput: coderStall.onOutput
     });
   } finally {
@@ -129,6 +146,38 @@ export async function runCoderStage({ coderRoleInstance, coderRole, config, logg
     throw new Error(`Coder failed: ${details}`);
   }
 
+  // KJC-BUG-0032 (PR-I): scan $HOME for new top-level entries the
+  // coder created OUTSIDE projectDir. Stop the HU loudly with a
+  // plain-Spanish message instead of letting the user discover by
+  // accident hours later that 36 MB of code is in the wrong place.
+  // Runs BEFORE the success-path verification so a leaked HU doesn't
+  // get marked as "Coder applied changes".
+  const projectDirAbs = config.projectDir || process.cwd();
+  const candidateLeaks = detectNewHomeEntries(homeSnapshotBeforeCoder, projectDirAbs);
+  // Issue #546: snapshot-diff alone produces false positives when other
+  // processes write to $HOME during the iteration window. Filter the
+  // detected entries against the coder's transcript: only flag those
+  // the coder demonstrably referenced.
+  const coderTranscript = coderExecResult.result?.output || "";
+  const fsLeaks = verifyLeaksAgainstTranscript(candidateLeaks, coderTranscript);
+  if (candidateLeaks.length > 0 && fsLeaks.length === 0) {
+    logger.warn(`fs-leak-detector: ${candidateLeaks.length} new $HOME entr(y/ies) detected but none referenced in the coder transcript — likely a concurrent host-side write, not flagging (#546).`);
+  }
+  if (fsLeaks.length > 0) {
+    const msg = formatLeakMessage(fsLeaks, projectDirAbs);
+    logger.error(msg);
+    emitProgress(
+      emitter,
+      makeEvent("coder:fs-leak", { ...eventBase, stage: "coder" }, {
+        status: "fail",
+        message: `Coder escribió fuera del projectDir: ${fsLeaks.length} ruta(s) detectada(s)`,
+        detail: { provider: coderRole.provider, leaks: fsLeaks, projectDir: projectDirAbs }
+      })
+    );
+    await markSessionStatus(session, "failed");
+    throw new Error(msg);
+  }
+
   // Measure files changed so stale detection (solomon-rules) has accurate data
   let filesChanged = 0;
   try {
@@ -252,7 +301,7 @@ function handleSolomonAction(solomonResult, session, contextPrefix) {
 async function handleSolomonContinue(solomonResult, session, counterField, brainCtx) {
   if (solomonResult.action !== "continue") return false;
   if (solomonResult.humanGuidance) {
-    session.last_reviewer_feedback += `\nUser guidance: ${solomonResult.humanGuidance}`;
+    setReviewerFeedback(session, `${session.last_reviewer_feedback ?? ""}\nUser guidance: ${solomonResult.humanGuidance}`);
     // Brain: also push user guidance into feedback queue when enabled
     if (brainCtx?.enabled) {
       const { processRoleOutput } = await import("../brain-coordinator.js");
@@ -265,13 +314,13 @@ async function handleSolomonContinue(solomonResult, session, counterField, brain
 }
 
 async function handleTddFailure({ tddEval, config, logger, emitter, eventBase, session, iteration, askQuestion, task, brainCtx }) {
-  session.last_reviewer_feedback = tddEval.message;
+  setReviewerFeedback(session, tddEval.message);
   // Brain: push TDD failure into feedback queue when enabled
   if (brainCtx?.enabled) {
     const { processRoleOutput } = await import("../brain-coordinator.js");
     processRoleOutput(brainCtx, { roleName: "tdd", output: { verdict: "fail", summary: tddEval.message }, iteration });
   }
-  session.repeated_issue_count += 1;
+  incrementRetryCount(session, "repeated_issue");
   await saveSession(session);
 
   if (session.repeated_issue_count < config.session.fail_fast_repeats) {
@@ -285,7 +334,7 @@ async function handleTddFailure({ tddEval, config, logger, emitter, eventBase, s
       message: `TDD sub-loop limit reached (${session.repeated_issue_count}/${config.session.fail_fast_repeats}) — Brain handling`,
       detail: { subloop: "tdd", retryCount: session.repeated_issue_count, reason: tddEval.reason }
     }));
-    session.repeated_issue_count = 0;
+    resetRetryCount(session, "repeated_issue");
     await saveSession(session);
     return { action: "continue" };
   }
@@ -320,7 +369,7 @@ async function handleTddFailure({ tddEval, config, logger, emitter, eventBase, s
   return { action: "continue" };
 }
 
-export async function runTddCheckStage({ config, logger, emitter, eventBase, session, trackBudget, iteration, askQuestion, task, brainCtx }) {
+export async function runTddCheckStage({ config, logger, emitter, eventBase, session, trackBudget: _trackBudget, iteration, askQuestion, task, brainCtx }) {
   logger.setContext({ iteration, stage: "tdd" });
   let tddDiff, untrackedFiles;
   try {