karajan-code 2.7.4 → 2.8.0

package/src/roles/repairer-role.js

@@ -0,0 +1,181 @@
+/**
+ * RepairerRole — repairs broken acceptance tests at runtime.
+ *
+ * The Brain calls this when an HU's acceptance test has failed N
+ * consecutive iterations with the same error signature, signalling
+ * that the test ITSELF may be the bug (not the implementation).
+ * Originated from the 2026-04-29 incident where the planner emitted
+ * a syntactically-broken jq query in HU 002's acceptance_tests; the
+ * coder iterated 3× trying to make an irreparable test pass; HU 002
+ * → failed → 7 dependents blocked.
+ *
+ * The role takes the failing test + its error output + HU intent and
+ * returns either a corrected test (`verdict: "fixable"` with
+ * `fixed_test`) or an escalation (`verdict: "unfixable"` with reason).
+ *
+ * Behaviour notes:
+ *  - The role MUST NOT soften assertions to make them pass — the test
+ *    defines the contract; this role's job is to make the test ASK
+ *    its question correctly, not weakly.
+ *  - The role MUST NOT rewrite a test to pass against the current
+ *    code. Code is measured against the test, not the other way.
+ *  - One bug per repair. If the test is layered with problems, return
+ *    the most blocking fix first; subsequent invocations handle the
+ *    rest.
+ */
+
+import { AgentRole } from "./agent-role.js";
+import { extractFirstJson } from "../utils/json-extract.js";
+import { loadAvailableSkills, buildSkillSection } from "../skills/skill-loader.js";
+
+const SUBAGENT_PREAMBLE = [
+  "IMPORTANT: You are running as a Karajan sub-agent.",
+  "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
+  "Do NOT use any MCP tools. Focus only on diagnosing and (if possible) repairing a single broken acceptance test.",
+].join(" ");
+
+export class RepairerRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "repairer" });
+  }
+
+  resolveProvider() {
+    // Default to the same provider family the coder uses — keeps
+    // the repair attempt cheap and consistent. Per-role override
+    // works as for every other role.
+    return this.config?.roles?.repairer?.provider
+      || this.config?.roles?.coder?.provider
+      || this.config?.coder
+      || "claude";
+  }
+
+  /**
+   * Inputs:
+   *   - failingTest: the test object (`{ type, content }` or string).
+   *   - errorOutput: stdout+stderr from the last test run (truncated to
+   *     ~2KB to keep the prompt small).
+   *   - huTitle, huScope: intent context.
+   *   - siblingTests: the HU's other acceptance_tests (for consistency).
+   *   - iteration: how many coder iterations have already failed on this.
+   */
+  extractInput(input) {
+    if (typeof input === "string") {
+      return {
+        failingTest: input, errorOutput: "", huTitle: "", huScope: "",
+        siblingTests: [], iteration: 0, onOutput: null,
+      };
+    }
+    return {
+      failingTest: input?.failingTest ?? null,
+      errorOutput: input?.errorOutput ?? "",
+      huTitle: input?.huTitle ?? "",
+      huScope: input?.huScope ?? "",
+      siblingTests: Array.isArray(input?.siblingTests) ? input.siblingTests : [],
+      iteration: Number.isFinite(input?.iteration) ? input.iteration : 0,
+      onOutput: input?.onOutput ?? null,
+    };
+  }
+
+  async buildPrompt({ failingTest, errorOutput, huTitle, huScope, siblingTests, iteration }) {
+    const sections = [SUBAGENT_PREAMBLE];
+    if (this.instructions) sections.push(this.instructions);
+
+    const testContent = (failingTest && typeof failingTest === "object")
+      ? failingTest.content
+      : String(failingTest || "");
+    const testType = (failingTest && typeof failingTest === "object" && failingTest.type)
+      ? failingTest.type
+      : "shell";
+
+    sections.push(
+      "You are repairing a broken acceptance test. The coder has failed to satisfy it across multiple iterations,",
+      "and the Brain suspects the test ITSELF is the bug — not the implementation.",
+      "",
+      "## HU intent",
+      `Title: ${huTitle || "(unknown)"}`,
+      `Scope: ${huScope || "(unknown)"}`,
+      "",
+      `## Failing test (type: ${testType}, after ${iteration} iteration(s))`,
+      "```",
+      testContent,
+      "```",
+      "",
+      "## Last error output",
+      "```",
+      String(errorOutput || "").slice(0, 2048),
+      "```",
+    );
+
+    if (siblingTests.length > 0) {
+      sections.push("## HU's other acceptance tests (for consistency — do NOT modify these)", "```");
+      for (const t of siblingTests) {
+        const c = typeof t === "object" ? t.content : t;
+        sections.push(`- ${c}`);
+      }
+      sections.push("```");
+    }
+
+    sections.push(
+      "",
+      "## Your job",
+      "Decide whether the failing test is **fixable** (you can correct a syntactic / structural bug)",
+      "or **unfixable** (test is fundamentally impossible, or the test is correct and the code must change).",
+      "",
+      "Return ONLY a single valid JSON object:",
+      '{"verdict":"fixable"|"unfixable","fixed_test":{"type":"shell"|"gherkin","content":string}|null,"reason":string,"diagnostics":[string]}',
+      "",
+      "- When verdict=fixable, fixed_test is REQUIRED and reason describes the bug class.",
+      "- When verdict=unfixable, fixed_test is null and reason explains why.",
+      "- NEVER soften an assertion. NEVER rewrite to pass against current code.",
+    );
+
+    const projectDir = this.config?.projectDir || process.cwd();
+    const skills = await loadAvailableSkills(projectDir);
+    const skillSection = buildSkillSection(skills, {
+      provider: this._resolvedProvider || (typeof this.resolveProvider === "function" ? this.resolveProvider() : null),
+      role: "repairer",
+    });
+    if (skillSection) sections.push(skillSection);
+
+    return { prompt: sections.join("\n\n") };
+  }
+
+  parseOutput(raw) { return extractFirstJson(raw); }
+
+  isSuccessful(parsed) {
+    if (!parsed || typeof parsed !== "object") return false;
+    if (parsed.verdict === "fixable") {
+      // Must produce a complete fixed_test object.
+      const ft = parsed.fixed_test;
+      return Boolean(ft && typeof ft === "object" && typeof ft.content === "string" && ft.content.trim());
+    }
+    if (parsed.verdict === "unfixable") {
+      // Unfixable is a valid OUTCOME (escalation), not a role failure.
+      return Boolean(parsed.reason && String(parsed.reason).trim());
+    }
+    return false;
+  }
+
+  buildSuccessResult(parsed, provider) {
+    return {
+      verdict: parsed.verdict,
+      fixed_test: parsed.fixed_test || null,
+      reason: parsed.reason || "",
+      diagnostics: Array.isArray(parsed.diagnostics) ? parsed.diagnostics : [],
+      provider,
+    };
+  }
+
+  buildSummary(parsed) {
+    if (!parsed) return "Repairer: no parseable output";
+    if (parsed.verdict === "fixable") {
+      const reason = (parsed.reason || "").slice(0, 120);
+      return `Repairer: fixable — ${reason}`;
+    }
+    if (parsed.verdict === "unfixable") {
+      const reason = (parsed.reason || "").slice(0, 120);
+      return `Repairer: unfixable — ${reason}`;
+    }
+    return `Repairer: unexpected verdict "${parsed.verdict}"`;
+  }
+}

package/src/roles/tester-role.js

@@ -48,16 +48,26 @@ export class TesterRole extends AgentRole {
   }
 
   extractInput(input) {
-    if (typeof input === "string") return { task: input, diff: null, sonarIssues: null };
+    if (typeof input === "string") return { task: input, diff: null, sonarIssues: null, pendingGherkinTests: null, shellTestResults: null };
     return {
       task: input?.task || this.context?.task || "",
       diff: input?.diff || null,
       sonarIssues: input?.sonarIssues || null,
+      // Tests-first Phase 3 (v2.7.5): the tester now has two extra inputs.
+      //   - pendingGherkinTests: HU-declared Gherkin scenarios that need
+      //     translation into executable code tests in the project's
+      //     framework. The tester writes the test files and includes them
+      //     in the suite run before computing verdict.
+      //   - shellTestResults: results of running the HU's shell-type
+      //     acceptance_tests (already run upstream, passed at this point).
+      //     Passed for context so the tester doesn't re-run them redundantly.
+      pendingGherkinTests: input?.pendingGherkinTests || null,
+      shellTestResults: input?.shellTestResults || null,
       onOutput: input?.onOutput || null
     };
   }
 
-  async buildPrompt({ task, diff, sonarIssues }) {
+  async buildPrompt({ task, diff, sonarIssues, pendingGherkinTests, shellTestResults }) {
     const projectDir = this.config?.projectDir || process.cwd();
     const detection = await detectTestFramework(projectDir);
 
@@ -97,14 +107,65 @@ export class TesterRole extends AgentRole {
       );
     }
 
+    // Tests-first Phase 3 (v2.7.5): include the upstream shell-test results
+    // so the tester knows which part of the contract is already green.
+    if (Array.isArray(shellTestResults) && shellTestResults.length > 0) {
+      const passedCount = shellTestResults.filter((r) => r.passed).length;
+      sections.push(
+        "## Acceptance gate — shell tests",
+        `The HU's shell-type acceptance_tests already ran upstream: ${passedCount}/${shellTestResults.length} passed.`,
+        "Do NOT re-run them. Use the coverage/translation steps below to decide your verdict."
+      );
+    }
+
+    // Gherkin translation block — only when the HU carries Gherkin
+    // scenarios. Tester must produce real test files (in the detected
+    // framework's language) that encode Given/When/Then. This is how
+    // behaviour-level specs become enforceable.
+    if (Array.isArray(pendingGherkinTests) && pendingGherkinTests.length > 0) {
+      sections.push(
+        "## Gherkin acceptance tests to translate",
+        "These Gherkin scenarios are the HU's behavioural contract. They are NOT yet",
+        "executable — your job is to turn each one into a concrete test case in the",
+        "project's test framework, WRITE the test files, and INCLUDE them in the suite",
+        "run that determines your verdict.",
+        "",
+        "For each scenario below:",
+        "1. Pick the appropriate test file (use `target` hint if present; otherwise",
+        "   put the test next to the module it exercises).",
+        "2. Write a test that asserts the Given/When/Then as-is. Do NOT soften the",
+        "   assertion — if it's ambiguous, pick the stricter reading.",
+        "3. Make sure the test runs as part of the normal suite (no separate invocation).",
+        "",
+        "If ANY translated test fails on the current code, return verdict: \"fail\" with",
+        "a failing_scenarios array listing the scenarios that didn't pass. The coder",
+        "will iterate.",
+        ""
+      );
+      pendingGherkinTests.forEach((entry, i) => {
+        const content = typeof entry === "string" ? entry : entry?.content || "";
+        const target = entry && entry.file ? ` · target: \`${entry.file}\`` : "";
+        sections.push(
+          `### Scenario ${i + 1}${target}`,
+          "```gherkin",
+          content,
+          "```",
+          ""
+        );
+      });
+    }
+
     sections.push(
       "",
       "Return ONLY a single valid JSON object:",
-      '{"tests_pass":boolean,"coverage":{"overall":number,"services":number,"utilities":number},"missing_scenarios":[string],"quality_issues":[string],"verdict":"pass"|"fail"}',
+      '{"tests_pass":boolean,"coverage":{"overall":number,"services":number,"utilities":number},"missing_scenarios":[string],"quality_issues":[string],"failing_scenarios":[string],"translated_scenarios":[string],"verdict":"pass"|"fail"}',
       "",
       "- coverage.overall MUST be a real number from the test runner output, NOT an estimate",
       "- If coverage tool is not available, set coverage.overall to null (not 0, not a guess)",
       "- tests_pass must reflect whether the actual test run succeeded",
+      "- failing_scenarios: when Gherkin was given, list the scenarios your translated tests CAUGHT as failing",
+      "- translated_scenarios: when Gherkin was given, list the scenarios you successfully turned into passing tests",
+      "- verdict MUST be \"fail\" if any translated scenario still fails (even if coverage is green)",
       `## Task\n${task}`
     );
     if (diff) sections.push(`## Git diff\n${diff}`);
@@ -136,6 +197,9 @@ export class TesterRole extends AgentRole {
       coverage: parsed.coverage || {},
       missing_scenarios: parsed.missing_scenarios || [],
       quality_issues: parsed.quality_issues || [],
+      // Tests-first Phase 3: Gherkin translation outcomes.
+      failing_scenarios: Array.isArray(parsed.failing_scenarios) ? parsed.failing_scenarios : [],
+      translated_scenarios: Array.isArray(parsed.translated_scenarios) ? parsed.translated_scenarios : [],
       verdict,
       provider
     };
@@ -147,6 +211,8 @@ export class TesterRole extends AgentRole {
     const coverageStr = coverage.overall != null ? `${coverage.overall}%` : "not measured";
     const missingPart = parsed.missing_scenarios?.length ? `; ${parsed.missing_scenarios.length} missing scenario(s)` : "";
     const qualityPart = parsed.quality_issues?.length ? `; ${parsed.quality_issues.length} quality issue(s)` : "";
-    return `Verdict: ${verdict}; Coverage: ${coverageStr}${missingPart}${qualityPart}`;
+    const failingPart = parsed.failing_scenarios?.length ? `; ${parsed.failing_scenarios.length} failing scenario(s)` : "";
+    const translatedPart = parsed.translated_scenarios?.length ? `; ${parsed.translated_scenarios.length} scenario(s) translated` : "";
+    return `Verdict: ${verdict}; Coverage: ${coverageStr}${translatedPart}${failingPart}${missingPart}${qualityPart}`;
   }
 }

package/src/session/mutators.js

@@ -0,0 +1,304 @@
+/**
+ * Session mutators — the single site where the orchestrator mutates a
+ * session object in memory.
+ *
+ * Rationale (TSK-0337, KJC-PCS-0040 Oleada 3): pre-v2.7.5 there were ~68
+ * direct `session.x = value` assignments scattered across 18 files, with
+ * one file (flow-runner.js) alone accounting for 142 touches. The audit
+ * called this out as a HIGH finding: when a reviewer-retry bug landed in
+ * production, a maintainer had to grep the whole tree to find every site
+ * that writes to `session.last_reviewer_feedback` or
+ * `session.reviewer_retry_count`.
+ *
+ * The mutators below are intentionally **mechanical** — each wraps a
+ * single assignment — so the migration from `session.x = y` to
+ * `setX(session, y)` is pure plumbing and preserves exact existing
+ * semantics. The value is NOT validation or side-effects; it's that
+ * grepping `setReviewerFeedback(` finds every writer in seconds. Adding
+ * validation, event emission or persistence hooks later becomes a
+ * one-liner inside the mutator rather than a tree-wide edit.
+ *
+ * Complementary architecture test:
+ *   tests/architecture/session-write-boundary.test.js
+ * enforces a budget on the remaining direct `session.x = y` assignments
+ * outside `src/session/`. The budget only decreases; any new direct
+ * assignment requires either going through a mutator or explicit audit.
+ *
+ * Naming convention:
+ *   - setX          — overwrite field X with a new value.
+ *   - incrementX    — numeric +1 (returns the new value).
+ *   - resetX        — numeric 0 or null.
+ *   - clearX        — delete the field entirely (when `in` matters).
+ *   - appendToX     — push onto an array field.
+ *   - assignX       — shallow-merge object into an object field.
+ *
+ * No mutator persists the session — callers are still responsible for
+ * `await saveSession(session)` afterwards. This keeps the mutator
+ * functions synchronous and cheap.
+ */
+
+// --- Retry counters -------------------------------------------------------
+
+export const RETRY_KINDS = Object.freeze([
+  "reviewer",
+  "sonar",
+  "tester",
+  "security",
+  "standby",
+  "repeated_issue",
+  "auto_resume",
+  "checkpoint_stall",
+]);
+
+const RETRY_FIELD = {
+  reviewer: "reviewer_retry_count",
+  sonar: "sonar_retry_count",
+  tester: "tester_retry_count",
+  security: "security_retry_count",
+  standby: "standby_retry_count",
+  repeated_issue: "repeated_issue_count",
+  auto_resume: "auto_resume_count",
+  checkpoint_stall: "_checkpoint_stall_count",
+};
+
+export function setRetryCount(session, kind, value) {
+  const field = RETRY_FIELD[kind];
+  if (!field) throw new Error(`setRetryCount: unknown retry kind "${kind}"`);
+  session[field] = Number(value) || 0;
+  return session[field];
+}
+
+export function incrementRetryCount(session, kind) {
+  const field = RETRY_FIELD[kind];
+  if (!field) throw new Error(`incrementRetryCount: unknown retry kind "${kind}"`);
+  session[field] = (session[field] || 0) + 1;
+  return session[field];
+}
+
+export function resetRetryCount(session, kind) {
+  return setRetryCount(session, kind, 0);
+}
+
+/**
+ * Reset all well-known retry/repeat counters to 0. Called at the top of
+ * every resume path so a resumed session doesn't inherit the previous
+ * run's stall state.
+ */
+export function resetAllRetryCounters(session) {
+  for (const kind of RETRY_KINDS) {
+    // Skip checkpoint_stall: it's internal state owned by flow-control,
+    // not something resume should touch.
+    if (kind === "checkpoint_stall") continue;
+    setRetryCount(session, kind, 0);
+  }
+}
+
+// --- Feedback -------------------------------------------------------------
+
+export function setReviewerFeedback(session, text) {
+  session.last_reviewer_feedback = text;
+}
+
+export function appendReviewerFeedback(session, text) {
+  session.last_reviewer_feedback = session.last_reviewer_feedback
+    ? `${session.last_reviewer_feedback}\n${text}`
+    : text;
+}
+
+export function setSonarSummary(session, text) {
+  session.last_sonar_summary = text;
+}
+
+export function setSonarIssueSignature(session, sig) {
+  session.last_sonar_issue_signature = sig;
+}
+
+export function setReviewerIssueSignature(session, sig) {
+  session.last_reviewer_issue_signature = sig;
+}
+
+// Issue-signature repetition counters (distinct from retry_count:
+// reset only when the signature changes, not every iteration).
+export function setSonarRepeatCount(session, value) {
+  session.sonar_repeat_count = Number(value) || 0;
+}
+export function setReviewerRepeatCount(session, value) {
+  session.reviewer_repeat_count = Number(value) || 0;
+}
+
+// --- Status ---------------------------------------------------------------
+
+/**
+ * In-memory status change. The persisting variant is `markSessionStatus` in
+ * store.js, which also writes to disk; `setStatus` is for transient mutations
+ * inside the runner (e.g. standby enter/exit) where the caller persists
+ * later via `saveSession`.
+ */
+export function setStatus(session, status) {
+  session.status = status;
+}
+
+// --- Alternative agent (rate-limit recovery) ------------------------------
+
+export function setAlternativeAgent(session, stage, provider) {
+  session._alternative_agent = { stage, provider };
+}
+
+export function clearAlternativeAgent(session) {
+  delete session._alternative_agent;
+}
+
+// --- Standby state --------------------------------------------------------
+
+export function setStandby(session, { agent, cooldownMs, cooldownUntil }) {
+  session.standby_agent = agent;
+  session.standby_cooldown_ms = cooldownMs;
+  session.standby_cooldown_until = cooldownUntil;
+}
+
+export function clearStandby(session) {
+  delete session.standby_agent;
+  delete session.standby_cooldown_ms;
+  delete session.standby_cooldown_until;
+}
+
+// --- CI state -------------------------------------------------------------
+
+export function setCiEarlyPr(session, { prNumber, prUrl, commits }) {
+  session.ci_pr_number = prNumber;
+  session.ci_pr_url = prUrl;
+  session.ci_commits = commits;
+}
+
+export function appendCiCommits(session, commits) {
+  session.ci_commits = [...(session.ci_commits ?? []), ...commits];
+}
+
+// --- Pre-loop & policy metadata -------------------------------------------
+
+export function setPreflight(session, result) {
+  session.preflight = result;
+}
+
+export function setResolvedPolicies(session, policies) {
+  session.resolved_policies = policies;
+}
+
+export function setPgCard(session, card) {
+  session.pg_card = card;
+}
+
+export function setPgTaskId(session, id) {
+  session.pg_task_id = id;
+}
+
+export function appendPgCommits(session, commits) {
+  session.pg_commits = [...(session.pg_commits ?? []), ...commits];
+}
+
+export function setPreLoopContext(session, { research, architect, plan }) {
+  if (research !== undefined) session.research_context = research;
+  if (architect !== undefined) session.architect_context = architect;
+  if (plan !== undefined) session.loaded_plan = plan;
+}
+
+export function setPlanRef(session, ref) {
+  session._planRef = ref;
+}
+
+export function setPlanSyncCallback(session, fn) {
+  session._syncResultsToPlan = fn;
+}
+
+/**
+ * Live status updater: invoked by hu-sub-pipeline after every status
+ * change so the plan JSON gets the new status immediately, not only at
+ * the end of the run. Without this, the board reads an unchanged plan
+ * file during execution and the columns appear frozen until the run
+ * completes (the bug we're fixing in PR1).
+ *
+ * Signature: async (huId, status) => void
+ */
+export function setLiveStatusUpdater(session, fn) {
+  session._liveStatusUpdater = fn;
+}
+
+export function getLiveStatusUpdater(session) {
+  return session._liveStatusUpdater || null;
+}
+
+/**
+ * Live outcome updater (PR3): invoked by hu-sub-pipeline after each
+ * HU's runSingleHu finishes. The plan JSON gets the per-HU outcome
+ * stamped immediately so the board can show a "📄 ver resumen"
+ * indicator next to each card without waiting for the run to end.
+ *
+ * Signature: async (huId, outcome) => void
+ */
+export function setLiveOutcomeUpdater(session, fn) {
+  session._liveOutcomeUpdater = fn;
+}
+
+export function getLiveOutcomeUpdater(session) {
+  return session._liveOutcomeUpdater || null;
+}
+
+// --- Skills ---------------------------------------------------------------
+
+export function setAddyosmaniSkills(session, payload) {
+  session.addyosmaniSkills = payload;
+}
+
+export function setAutoInstalledSkills(session, skills) {
+  session.autoInstalledSkills = skills;
+}
+
+export function setSkillsRecommended(session, skills) {
+  session.skillsRecommended = skills;
+}
+
+// --- Journal breadcrumbs --------------------------------------------------
+
+export function setJournalContext(session, { dir, files, iterations, decisions, startedAt }) {
+  if (dir !== undefined) session._journalDir = dir;
+  if (files !== undefined) session._journalFiles = files;
+  if (iterations !== undefined) session._journalIterations = iterations;
+  if (decisions !== undefined) session._journalDecisions = decisions;
+  if (startedAt !== undefined) session._startedAt = startedAt;
+}
+
+// --- Session outcome ------------------------------------------------------
+
+export function setBudget(session, budget) {
+  session.budget = budget;
+}
+
+export function setDeferredIssues(session, issues) {
+  session.deferred_issues = issues;
+}
+
+export function setRtkSavings(session, savings) {
+  session.rtk_savings = savings;
+}
+
+// --- Paused state (resume) ------------------------------------------------
+
+export function setPausedState(session, state) {
+  session.paused_state = state;
+}
+
+// --- Brain decisions (decisor tracker) -----------------------------------
+
+export function setBrainDecisions(session, decisions) {
+  session.brainDecisions = decisions;
+}
+
+// --- Suggestions (MCP) ----------------------------------------------------
+
+export function setSuggestions(session, suggestions) {
+  session.suggestions = suggestions;
+}
+
+export function touch(session) {
+  session.updated_at = new Date().toISOString();
+}

package/src/session/runtime-overrides.js

@@ -0,0 +1,59 @@
+/**
+ * In-memory runtime overrides (e.g. `roles.coder.provider` set for the
+ * current process session, not persisted to disk).
+ *
+ * Why this lives at the session layer (not under `src/mcp/`):
+ *
+ *   Pre-v2.7.5, the overrides store lived in `src/mcp/preflight.js`. That
+ *   made `src/commands/agents.js` (CLI) do
+ *     `await import("../mcp/preflight.js")`
+ *   which is a **layer violation**: commands are the top layer, MCP is a
+ *   peer interface. A CLI command knowing about the MCP server's
+ *   preflight state coupled two runtimes that should be independent.
+ *
+ *   The "runtime override" concept is runtime-agnostic — both CLI and MCP
+ *   need an in-memory scratchpad for "this process should use this
+ *   provider for role X for the rest of its life". Putting it here makes
+ *   both layers depend on `src/session/` (a neutral module) instead of on
+ *   each other.
+ *
+ * Lifetime: the store lives for as long as the Node process. CLI
+ * invocations are short-lived (override is lost at exit — that's fine,
+ * they write to config if they want persistence). The MCP server process
+ * is long-lived; the override survives across tool calls until
+ * `clearRuntimeOverrides()` is called (typically by `ackPreflight()`).
+ *
+ * Contents: a flat `{ [key]: value }` map. Keys are typically role names
+ * (`coder`, `reviewer`, `planner`), values are provider slugs (`claude`,
+ * `codex`, `gemini`). Consumers shape-validate at read time.
+ */
+
+let overrides = {};
+
+/**
+ * Return a shallow copy of the current overrides. Never returns the
+ * internal reference so callers cannot mutate it by accident.
+ */
+export function getRuntimeOverrides() {
+  return { ...overrides };
+}
+
+/**
+ * Set a single override. Silently rejects nullish keys.
+ *
+ * @param {string} key
+ * @param {unknown} value
+ */
+export function setRuntimeOverride(key, value) {
+  if (!key) return;
+  overrides[key] = value;
+}
+
+/**
+ * Drop all overrides. Used by `ackPreflight()` after it transfers its
+ * configured overrides onto this store, to ensure we start from a clean
+ * slate per MCP session.
+ */
+export function clearRuntimeOverrides() {
+  overrides = {};
+}

package/src/{session-store.js → session/store.js}

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { ensureDir, exists } from "./utils/fs.js";
-import { getSessionRoot } from "./utils/paths.js";
+import { ensureDir, exists } from "../utils/fs.js";
+import { getSessionRoot } from "../utils/paths.js";
 
 const SESSION_ROOT = getSessionRoot();