karajan-code 1.58.2 → 1.59.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "1.58.2",
+  "version": "1.59.1",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/agents/aider-agent.js

@@ -1,6 +1,7 @@
 import { BaseAgent } from "./base-agent.js";
 import { runCommand } from "../utils/process.js";
 import { resolveBin } from "./resolve-bin.js";
+import { getProxyEnv } from "../proxy/proxy-lifecycle.js";
 
 export class AiderAgent extends BaseAgent {
   async runTask(task) {
@@ -28,7 +29,13 @@ export class AiderAgent extends BaseAgent {
   async _exec(task, model) {
     const args = ["--yes", "--message", task.prompt];
     if (model) args.push("--model", model);
+    const proxyEnv = getProxyEnv();
+    if (proxyEnv) {
+      args.push("--api-base", proxyEnv.OPENAI_BASE_URL);
+    }
+    const env = proxyEnv ? { ...process.env, ...proxyEnv } : undefined;
     const res = await runCommand(resolveBin("aider"), args, {
+      ...(env && { env }),
       onOutput: task.onOutput,
       silenceTimeoutMs: task.silenceTimeoutMs,
       timeout: task.timeoutMs

package/src/agents/claude-agent.js

@@ -11,6 +11,37 @@ function tryParseJson(line) {
   } catch { return null; }
 }
 
+/**
+ * Extract a human-readable error message from Claude's raw NDJSON stderr output.
+ * Claude emits system init, api_retry, assistant error, and result lines.
+ * We extract just the meaningful error text, discarding the JSON noise.
+ */
+export function sanitizeClaudeError(raw) {
+  if (!raw) return "Unknown error";
+  const lines = raw.split("\n").filter(Boolean);
+
+  // Look for a result line with the actual error
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const obj = tryParseJson(lines[i]);
+    if (!obj) continue;
+    if (obj.type === "result" && obj.result) return String(obj.result);
+    if (obj.type === "assistant" && obj.message?.content) {
+      const text = obj.message.content
+        .filter(b => b.type === "text" && b.text)
+        .map(b => b.text)
+        .join(" ");
+      if (text) return text;
+    }
+  }
+
+  // If no JSON parsed, return first non-JSON line or truncated raw
+  for (const line of lines) {
+    if (!line.startsWith("{")) return line.slice(0, 200);
+  }
+
+  return raw.slice(0, 200);
+}
+
 /**
  * Try to extract a result string from a parsed JSON object.
  * Returns the result string or null if the object is not a result message.
@@ -134,6 +165,9 @@ function createStreamJsonFilter(onOutput) {
  */
 function cleanExecaOpts(extra = {}) {
   const { CLAUDECODE, ...env } = process.env;
+  // NOTE: Claude Code CLI does not respect ANTHROPIC_BASE_URL — proxy env
+  // injection is skipped for claude to avoid ECONNREFUSED errors.
+  // Other agents (codex, gemini, aider) use SDKs that do respect base URL vars.
   return { env, stdin: "ignore", ...extra };
 }
 
@@ -194,7 +228,7 @@ export class ClaudeAgent extends BaseAgent {
       const raw = pickOutput(res);
       const output = extractTextFromStreamJson(raw);
       const usage = extractUsageFromStreamJson(raw);
-      return { ok: res.exitCode === 0, output, error: res.exitCode === 0 ? "" : raw, exitCode: res.exitCode, ...usage };
+      return { ok: res.exitCode === 0, output, error: res.exitCode === 0 ? "" : sanitizeClaudeError(raw), exitCode: res.exitCode, ...usage };
     }
 
     // Without streaming, use json output to get structured response via stderr
@@ -203,7 +237,7 @@ export class ClaudeAgent extends BaseAgent {
     const raw = pickOutput(res);
     const output = extractTextFromStreamJson(raw);
     const usage = extractUsageFromStreamJson(raw);
-    return { ok: res.exitCode === 0, output, error: res.exitCode === 0 ? "" : raw, exitCode: res.exitCode, ...usage };
+    return { ok: res.exitCode === 0, output, error: res.exitCode === 0 ? "" : sanitizeClaudeError(raw), exitCode: res.exitCode, ...usage };
   }
 
   async _reviewTaskExec(task, model) {

package/src/agents/codex-agent.js

@@ -1,6 +1,7 @@
 import { BaseAgent } from "./base-agent.js";
 import { runCommand } from "../utils/process.js";
 import { resolveBin } from "./resolve-bin.js";
+import { getProxyEnv } from "../proxy/proxy-lifecycle.js";
 
 /**
  * Extract token usage from Codex CLI stdout.
@@ -45,7 +46,10 @@ export class CodexAgent extends BaseAgent {
     if (model) args.push("--model", model);
     if (role !== "reviewer" && this.isAutoApproveEnabled(role)) args.push("--full-auto");
     args.push("-");
+    const proxyEnv = getProxyEnv();
+    const env = proxyEnv ? { ...process.env, ...proxyEnv } : undefined;
     const res = await runCommand(resolveBin("codex"), args, {
+      ...(env && { env }),
       onOutput: task.onOutput,
       silenceTimeoutMs: task.silenceTimeoutMs,
       timeout: task.timeoutMs,

package/src/agents/gemini-agent.js

@@ -1,6 +1,7 @@
 import { BaseAgent } from "./base-agent.js";
 import { runCommand } from "../utils/process.js";
 import { resolveBin } from "./resolve-bin.js";
+import { getProxyEnv } from "../proxy/proxy-lifecycle.js";
 
 export class GeminiAgent extends BaseAgent {
   async runTask(task) {
@@ -29,7 +30,10 @@ export class GeminiAgent extends BaseAgent {
     const args = ["-p", task.prompt];
     if (mode === "review") args.push("--output-format", "json");
     if (model) args.push("--model", model);
+    const proxyEnv = getProxyEnv();
+    const env = proxyEnv ? { ...process.env, ...proxyEnv } : undefined;
     const res = await runCommand(resolveBin("gemini"), args, {
+      ...(env && { env }),
       onOutput: task.onOutput,
       silenceTimeoutMs: task.silenceTimeoutMs,
       timeout: task.timeoutMs

package/src/agents/opencode-agent.js

@@ -1,6 +1,7 @@
 import { BaseAgent } from "./base-agent.js";
 import { runCommand } from "../utils/process.js";
 import { resolveBin } from "./resolve-bin.js";
+import { getProxyEnv } from "../proxy/proxy-lifecycle.js";
 
 export class OpenCodeAgent extends BaseAgent {
   async runTask(task) {
@@ -30,7 +31,10 @@ export class OpenCodeAgent extends BaseAgent {
     if (jsonFormat) args.push("--format", "json");
     if (model) args.push("--model", model);
     args.push(task.prompt);
+    const proxyEnv = getProxyEnv();
+    const env = proxyEnv ? { ...process.env, ...proxyEnv } : undefined;
     const res = await runCommand(resolveBin("opencode"), args, {
+      ...(env && { env }),
       onOutput: task.onOutput,
       silenceTimeoutMs: task.silenceTimeoutMs,
       timeout: task.timeoutMs

package/src/bootstrap.js

@@ -42,12 +42,22 @@ async function checkGitRepo() {
   } catch { /* git may not be installed */
     ok = false;
   }
-  return {
-    name: "gitRepo",
-    ok,
-    detail: ok ? "Inside a git repository" : "Not a git repository",
-    fix: "Run 'git init' in your project directory."
-  };
+
+  if (!ok) {
+    // Auto-init: initialize git repo for new projects
+    const initResult = await runCommand("git", ["init"]);
+    if (initResult.exitCode !== 0) {
+      return {
+        name: "gitRepo",
+        ok: false,
+        detail: "Not a git repository and git init failed",
+        fix: "Ensure git is installed and you have write permissions to this directory."
+      };
+    }
+    return { name: "gitRepo", ok: true, detail: "Initialized new git repository", fix: null };
+  }
+
+  return { name: "gitRepo", ok: true, detail: "Inside a git repository", fix: null };
 }
 
 async function checkGitRemote() {
@@ -57,11 +67,12 @@ async function checkGitRemote() {
       return { name: "gitRemote", ok: true, detail: res.stdout.trim(), fix: null };
     }
   } catch { /* fall through */ }
+  // No remote is acceptable for new projects — non-blocking
   return {
     name: "gitRemote",
-    ok: false,
-    detail: "origin remote not configured",
-    fix: "Run 'git remote add origin <your-repo-url>'."
+    ok: true,
+    detail: "No remote configured (new project)",
+    fix: null
   };
 }
 

package/src/cli.js

@@ -127,6 +127,7 @@ program
   .option("--smart-models", "Enable smart model selection based on triage complexity")
   .option("--no-smart-models", "Disable smart model selection")
   .option("--design", "Activate design refactoring mode (impeccable role applies design changes)")
+  .option("--domain <text-or-path>", "Domain knowledge: inline text or path to .md file")
   .option("--dry-run", "Show what would be executed without running anything")
   .option("--json", "Output JSON only (no styled display)")
   .option("-q, --quiet", "Show only stage status lines, suppress raw agent output (default)")

package/src/commands/doctor.js

@@ -12,6 +12,7 @@ import { ensureGitRepo } from "../utils/git.js";
 import { checkBinary, KNOWN_AGENTS } from "../utils/agent-detect.js";
 import { getInstallCommand } from "../utils/os-detect.js";
 import { withDocLink } from "../utils/doc-links.js";
+import { isProxyRunning } from "../proxy/proxy-lifecycle.js";
 
 function getPackageVersion() {
   const pkgPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../package.json");
@@ -342,6 +343,23 @@ async function checkAgentConfigs() {
   return checks;
 }
 
+async function checkProxy(config) {
+  if (config.proxy?.enabled === false) {
+    return { name: "proxy", label: "Proxy", ok: true, detail: "Disabled in config", fix: null };
+  }
+  let running = false;
+  try {
+    running = await isProxyRunning();
+  } catch { /* proxy check failed */ }
+  return {
+    name: "proxy",
+    label: "Proxy",
+    ok: true,
+    detail: running ? "Running" : "Available (starts on kj run)",
+    fix: null
+  };
+}
+
 export async function runChecks({ config }) {
   const checks = [];
 
@@ -366,6 +384,7 @@ export async function runChecks({ config }) {
   checks.push(...await checkAgentConfigs());
   checks.push(...await checkRuleFiles(config));
   checks.push(await checkRtk());
+  checks.push(await checkProxy(config));
 
   return checks;
 }

package/src/commands/report.js

@@ -153,6 +153,7 @@ async function buildReport(dir, sessionId) {
   if (session.pg_task_id) report.pg_task_id = session.pg_task_id;
   if (session.pg_project_id) report.pg_project_id = session.pg_project_id;
   if (session.rtk_savings) report.rtk_savings = session.rtk_savings;
+  if (session.proxy_stats) report.proxy_stats = session.proxy_stats;
   return report;
 }
 
@@ -199,6 +200,7 @@ function printTextReport(report) {
   console.log(formatBudgetText(report.budget_consumed));
   console.log("Commits Generated:");
   console.log(formatCommitsText(report.commits_generated));
+  printProxyStats(report.proxy_stats);
 }
 
 function formatDuration(ms) {
@@ -327,6 +329,16 @@ async function resolveTraceOptions(currency) {
   return { cur, rate };
 }
 
+function printProxyStats(proxyStats) {
+  if (!proxyStats) return;
+  const orig = proxyStats.originalTokens ?? 0;
+  const comp = proxyStats.compressedTokens ?? 0;
+  const pct = orig > 0 ? ((1 - comp / orig) * 100).toFixed(1) : "0.0";
+  const hits = proxyStats.cacheHits ?? 0;
+  console.log("");
+  console.log(`Proxy: ${orig} original tokens, ${comp} compressed tokens, ${pct}% savings, ${hits} cache hits`);
+}
+
 function printRtkSavings(rtkSavings) {
   if (!rtkSavings || !rtkSavings.callCount) return;
   const tokens = rtkSavings.estimatedTokensSaved ?? 0;
@@ -345,6 +357,7 @@ function printTraceReport(report, currency, exchangeRate) {
   console.log("");
   printTraceTable(report.budget_trace, { currency, exchangeRate });
   printRtkSavings(report.rtk_savings);
+  printProxyStats(report.proxy_stats);
 }
 
 async function handlePgTaskReport({ dir, pgTask, list, sessionId, format, trace, currency }) {

package/src/commands/status.js

@@ -5,6 +5,7 @@
 import { readRunLog } from "../utils/run-log.js";
 import { loadMostRecentSession } from "../session-store.js";
 import { buildDashboard } from "../utils/status-dashboard.js";
+import { getProxyStats } from "../proxy/proxy-lifecycle.js";
 
 /**
  * Run the `kj status` command: print a human-readable dashboard to stdout.
@@ -32,4 +33,10 @@ export async function statusCommand({ lines = 50, projectDir } = {}) {
 
   const dashboard = buildDashboard(session, logResult.lines || [], { stories });
   console.log(dashboard);
+
+  const proxyStats = getProxyStats();
+  if (proxyStats) {
+    console.log("");
+    console.log(`Proxy: port ${proxyStats.port}, ${proxyStats.requests} requests, ${proxyStats.bytes_in} bytes in, ${proxyStats.bytes_out} bytes out`);
+  }
 }

package/src/config.js

@@ -172,6 +172,37 @@ const DEFAULTS = {
     thresholds: { lcp: 2500, cls: 0.1, inp: 200 }
   },
   telemetry: true,
+  proxy: {
+    enabled: true,
+    port: "auto",
+    compression: {
+      enabled: true,
+      ai_compression: false,
+      ai_model: "haiku",
+      ai_provider: "anthropic",
+      layers: {
+        git: true,
+        tests: true,
+        build: true,
+        infra: true,
+        packages: true,
+        read_dedup: true,
+        glob_truncate: true,
+        grep_collapse: true,
+      },
+      pressure_thresholds: {
+        low: 0.5,
+        medium: 0.8,
+        high: 0.9,
+      },
+    },
+    cache: {
+      persist_to_disk: true,
+      flush_interval_ms: 5000,
+    },
+    inject_prompts: true,
+    monitor: true,
+  },
   guards: {
     output: {
       enabled: true,
@@ -401,6 +432,10 @@ function applyMiscOverrides(out, flags) {
   if (flags.pgTask) out.planning_game.enabled = true;
   if (flags.pgProject) out.planning_game.project_id = flags.pgProject;
 
+  out.proxy = out.proxy || {};
+  if (flags.noProxy) out.proxy.enabled = false;
+  if (flags.proxyPort) out.proxy.port = flags.proxyPort;
+
   out.model_selection = out.model_selection || { enabled: true, tiers: {}, role_overrides: {} };
   if (flags.smartModels === true) out.model_selection.enabled = true;
   if (flags.smartModels === false || flags.noSmartModels === true) out.model_selection.enabled = false;

package/src/domains/domain-loader.js

@@ -5,8 +5,8 @@
  * Project-local domains override user-global domains by directory name.
  */
 
-import { readdir, readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { readdir, readFile, mkdir, writeFile, stat } from "node:fs/promises";
+import { join, isAbsolute } from "node:path";
 import yaml from "js-yaml";
 import { getKarajanHome } from "../utils/paths.js";
 
@@ -103,8 +103,52 @@ function parseSections(content) {
   return sections;
 }
 
+/**
+ * Auto-detect project context files (README.md, CLAUDE.md) as lightweight domains.
+ * Used as fallback when no explicit .karajan/domains/ are configured.
+ *
+ * @param {string} projectDir — absolute path to project root
+ * @returns {Promise<DomainFile[]>}
+ */
+export async function autoDetectDomains(projectDir) {
+  if (!projectDir) return [];
+
+  const candidates = ["README.md", "CLAUDE.md", "docs/README.md"];
+  const detected = [];
+
+  for (const rel of candidates) {
+    const filePath = join(projectDir, rel);
+    let content;
+    try {
+      content = await readFile(filePath, "utf-8");
+    } catch { continue; }
+
+    if (!content || content.trim().length < 20) continue;
+
+    // Truncate to first 4000 chars to avoid bloating context
+    const trimmed = content.length > 4000 ? content.slice(0, 4000) + "\n\n[...truncated]" : content;
+
+    detected.push({
+      name: `auto:${rel}`,
+      description: `Auto-detected from ${rel}`,
+      tags: [],
+      version: "0.0.0",
+      author: "",
+      visibility: "private",
+      sources: [{ type: "auto-detect", note: rel }],
+      content: trimmed,
+      sections: parseSections(trimmed),
+      filePath,
+      origin: "auto-detect"
+    });
+  }
+
+  return detected;
+}
+
 /**
  * Load all domains from project-local and user-global directories.
+ * Falls back to auto-detecting README.md/CLAUDE.md when no explicit domains found.
  * Project-local domains override user-global domains when directory names match.
  *
  * @param {string|null} projectDir — absolute path to project root (null = user-global only)
@@ -119,7 +163,6 @@ export async function loadDomains(projectDir) {
   const projectDomains = projectDomainDir ? await scanDomainDir(projectDomainDir, "project") : [];
 
   // Build a map keyed by directory name for merge.
-  // We track by directory name (not domain name) because the override is by directory.
   const merged = new Map();
 
   for (const { dirName, domain } of userDomains) {
@@ -129,7 +172,14 @@ export async function loadDomains(projectDir) {
     merged.set(dirName, domain); // project overrides user
   }
 
-  return Array.from(merged.values());
+  const explicit = Array.from(merged.values());
+
+  // Fallback: auto-detect README.md, CLAUDE.md when no explicit domains found
+  if (explicit.length === 0 && projectDir) {
+    return autoDetectDomains(projectDir);
+  }
+
+  return explicit;
 }
 
 /**
@@ -162,3 +212,34 @@ async function scanDomainDir(dir, origin) {
 
   return results;
 }
+
+/**
+ * Persist an inline domain (text or file path) to .karajan/domains/inline/DOMAIN.md.
+ * If domainInput is a path to an existing .md file, reads its content.
+ * Otherwise treats it as inline text.
+ *
+ * @param {string} domainInput — inline text or absolute path to a .md file
+ * @param {string} projectDir — project root
+ */
+export async function persistInlineDomain(domainInput, projectDir) {
+  if (!domainInput || !projectDir) return;
+
+  let content = domainInput;
+
+  // If it looks like a file path, try to read it
+  if (isAbsolute(domainInput) && domainInput.endsWith(".md")) {
+    try {
+      const s = await stat(domainInput);
+      if (s.isFile()) {
+        content = await readFile(domainInput, "utf-8");
+      }
+    } catch { /* treat as inline text */ }
+  }
+
+  const domainDir = join(projectDir, ".karajan", "domains", "inline");
+  await mkdir(domainDir, { recursive: true });
+
+  const domainFile = join(domainDir, DOMAIN_FILE);
+  const wrapped = `---\nname: inline-domain\ndescription: Domain knowledge provided via --domain parameter\ntags: []\nversion: "0.0.0"\n---\n\n${content}\n`;
+  await writeFile(domainFile, wrapped, "utf-8");
+}

package/src/git/automation.js

@@ -7,6 +7,7 @@ import { addCheckpoint } from "../session-store.js";
 import {
   ensureGitRepo,
   currentBranch,
+  hasCommits,
   fetchBase,
   syncBaseBranch,
   ensureBranchUpToDateWithBase,
@@ -34,18 +35,45 @@ export async function prepareGitAutomation({ config, task, logger, session }) {
 
   const baseBranch = config.base_branch;
   const autoRebase = config.git.auto_rebase !== false;
-  await fetchBase(baseBranch);
+  const repoHasCommits = await hasCommits();
+
+  // New repo without commits: create branch directly (no fetch/sync possible)
+  if (!repoHasCommits) {
+    const created = buildBranchName(config.git.branch_prefix || "feat/", task);
+    // git checkout -b works even without commits (creates orphan-like branch on first commit)
+    await createBranch(created);
+    logger.info(`New repo — created working branch: ${created}`);
+    await addCheckpoint(session, { stage: "git-prep", branch: created, created: true, newRepo: true });
+    return { enabled: true, branch: created, baseBranch, autoRebase };
+  }
+
+  await fetchBase(baseBranch).catch(() => {
+    // No remote — skip fetch (new project without push)
+    logger.info("No remote configured — skipping fetch");
+  });
+
+  let branch;
+  try {
+    branch = await currentBranch();
+  } catch {
+    // HEAD exists but branch detection failed — unusual, treat as main
+    branch = baseBranch;
+  }
 
-  let branch = await currentBranch();
   if (branch === baseBranch) {
-    await syncBaseBranch({ baseBranch, autoRebase });
+    await syncBaseBranch({ baseBranch, autoRebase }).catch(() => {
+      // No remote tracking — skip sync for new projects
+    });
     const created = buildBranchName(config.git.branch_prefix || "feat/", task);
     await createBranch(created);
     branch = created;
     logger.info(`Created working branch: ${branch}`);
     await addCheckpoint(session, { stage: "git-prep", branch, created: true });
   } else {
-    await ensureBranchUpToDateWithBase({ branch, baseBranch, autoRebase });
+    await ensureBranchUpToDateWithBase({ branch, baseBranch, autoRebase }).catch(() => {
+      // No remote tracking — skip rebase for new projects
+      logger.info("No remote tracking — skipping rebase check");
+    });
     await addCheckpoint(session, { stage: "git-prep", branch, created: false });
   }
 

package/src/guards/policy-guard.js

@@ -0,0 +1,90 @@
+/**
+ * Policy guard for kj_resume answers.
+ *
+ * Detects host-AI attempts to bypass pipeline policies (skip TDD, ignore
+ * reviewer, disable security, etc.) and rejects them with context-aware
+ * suggestions for valid alternatives.
+ */
+
+const BYPASS_PATTERNS = [
+  { regex: /\b(?:skip|omit|drop)\s+(?:the\s+)?(?:tests?|tdd|testing)\b/i, policy: "tdd" },
+  { regex: /\bdisable\s+(?:the\s+)?(?:tests?|tdd|testing)\b/i, policy: "tdd" },
+  { regex: /\b(?:don'?t|do\s+not|no\s+need\s+(?:for|to))\s+(?:run\s+)?tests?\b/i, policy: "tdd" },
+  { regex: /\bcontinue\s+without\s+test/i, policy: "tdd" },
+  { regex: /\bswitch\s+(?:to\s+)?(?:standard\s+)?methodology/i, policy: "tdd" },
+  { regex: /\bswitch\s+methodology/i, policy: "tdd" },
+  { regex: /\b(?:skip|ignore|bypass|disable)\s+(?:the\s+)?(?:review(?:er)?|code\s+review)\b/i, policy: "reviewer" },
+  { regex: /\b(?:approve|pass)\s+without\s+review/i, policy: "reviewer" },
+  { regex: /\bmark\s+as\s+approved\b/i, policy: "reviewer" },
+  { regex: /\bjust\s+ship\s+it/i, policy: "reviewer" },
+  { regex: /\bignore\s+(?:the\s+)?(?:review(?:er)?\s+)?feedback\b/i, policy: "reviewer" },
+  { regex: /\b(?:skip|ignore|bypass|disable)\s+(?:the\s+)?(?:sonar|sonarqube|quality\s+gate)/i, policy: "sonar" },
+  { regex: /\bignore\s+sonar\s+issues?\b/i, policy: "sonar" },
+  { regex: /\b(?:skip|ignore|bypass|disable)\s+(?:the\s+)?security(?:\s+checks?)?\b/i, policy: "security" },
+];
+
+const SUGGESTIONS_BY_POLICY = {
+  tdd: [
+    "Provide specific guidance for the coder on how to fix the failing tests",
+    "Describe the expected behavior so the coder can write correct tests",
+    "Suggest a different approach to implement the feature that is easier to test",
+  ],
+  reviewer: [
+    "Provide technical guidance to address the reviewer's feedback",
+    "Explain why the current approach is correct if you disagree with the review",
+    "Suggest alternative implementations that satisfy the reviewer's concerns",
+  ],
+  sonar: [
+    "Provide guidance on how to resolve the SonarQube issues",
+    "Explain the code changes needed to satisfy quality gate requirements",
+  ],
+  security: [
+    "Provide guidance on how to fix the security issues found",
+    "Explain the secure alternative for the flagged pattern",
+  ],
+};
+
+const CONTEXT_SUGGESTIONS = {
+  reviewer_fail_fast: [
+    "Provide specific technical guidance for the coder to address the reviewer's feedback",
+    "Suggest a different approach that resolves the reviewer's concerns",
+  ],
+  max_iterations: [
+    "Provide focused guidance to help the coder converge on a solution",
+    "Narrow the scope: specify exactly which file/function to change and how",
+    "Continue with additional iterations by choosing option 1 or 2",
+  ],
+  standby_exhausted: [
+    "Wait and retry — the provider may be temporarily overloaded",
+    "Continue to resume from where the pipeline left off",
+  ],
+};
+
+/**
+ * Validate a resume answer against pipeline policies.
+ *
+ * @param {string|null} answer - The resume answer from the host
+ * @param {string} [pauseContext] - The context of the pause (e.g. "reviewer_fail_fast")
+ * @returns {{ valid: boolean, reason?: string, suggestions?: string[] }}
+ */
+export function validatePolicyCompliance(answer, pauseContext) {
+  if (answer == null || answer === "") return { valid: true };
+  if (typeof answer !== "string") return { valid: true };
+
+  const text = answer.trim();
+  for (const { regex, policy } of BYPASS_PATTERNS) {
+    if (regex.test(text)) {
+      const suggestions = [
+        ...(CONTEXT_SUGGESTIONS[pauseContext] || []),
+        ...(SUGGESTIONS_BY_POLICY[policy] || []),
+      ];
+      return {
+        valid: false,
+        reason: `Pipeline policy "${policy}" cannot be bypassed. Provide technical guidance instead.`,
+        suggestions: [...new Set(suggestions)],
+      };
+    }
+  }
+
+  return { valid: true };
+}