@karajan-family/code 4.21.0

package/src/review/verdict-store.js

@@ -0,0 +1,87 @@
+/**
+ * Verdict store (ENV-B1, KJC-TSK-0637) — persists cross-AI review verdicts
+ * keyed by the sha256 of the RAW diff they reviewed.
+ *
+ * The hash is the contract: a verdict only counts for byte-identical
+ * content, so any change after the review voids it and forces a new one
+ * (resolve-until-pass by construction). The pre-commit hook (ENV-C)
+ * calls checkVerdict() with the staged diff to decide whether the
+ * commit may enter. Diffs must be raw git output — never rtk-compressed
+ * (KJC-BUG-0115).
+ */
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { runCommand } from "../utils/process.js";
+
+const STORE_DIR = path.join(".karajan", "reviews");
+
+export function diffHash(diff) {
+  // trimEnd: runners differ on the final newline (execa strips it, raw
+  // git keeps it) — trailing whitespace must not void a verdict.
+  return crypto.createHash("sha256").update(diff.trimEnd(), "utf8").digest("hex");
+}
+
+function verdictPath(projectDir, hash) {
+  return path.join(projectDir, STORE_DIR, `${hash}.json`);
+}
+
+export async function saveVerdict(projectDir, diff, verdict) {
+  const hash = diffHash(diff);
+  const record = {
+    ...verdict,
+    diffHash: hash,
+    timestamp: new Date().toISOString(),
+  };
+  const file = verdictPath(projectDir, hash);
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  await fs.writeFile(file, `${JSON.stringify(record, null, 2)}\n`);
+  return record;
+}
+
+export async function loadVerdict(projectDir, hash) {
+  try {
+    return JSON.parse(await fs.readFile(verdictPath(projectDir, hash), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * ENV-F1 (KJC-TSK-0643): headless pipeline sessions call this after staging
+ * and before committing. Their reviewer ALREADY cross-AI-reviewed the work,
+ * so the verdict is recorded for the staged diff and the v4 pre-commit gate
+ * accepts the pipeline's commit. No gate marker → no-op (zero overhead for
+ * repos that never opted in). Raw git only — never a wrapped runner
+ * (KJC-BUG-0115).
+ * @returns {Promise<{stamped: boolean}>}
+ */
+export async function stampStagedVerdict({ projectDir, reviewer, summary = "" }) {
+  const dir = projectDir || process.cwd();
+  try {
+    await fs.access(path.join(dir, ".karajan", "review-gate"));
+  } catch {
+    return { stamped: false };
+  }
+  const res = await runCommand("git", ["diff", "--cached"], { cwd: dir });
+  if (res.exitCode !== 0 || !res.stdout?.trim()) return { stamped: false };
+  await saveVerdict(dir, res.stdout, {
+    verdict: "approved", reviewer, host: "kj-pipeline", issues: [], summary,
+  });
+  return { stamped: true };
+}
+
+/**
+ * Is there an APPROVED verdict for exactly this diff?
+ * @returns {Promise<{ok: boolean, verdict?: object, reason?: string}>}
+ */
+export async function checkVerdict(projectDir, diff) {
+  const verdict = await loadVerdict(projectDir, diffHash(diff));
+  if (!verdict) {
+    return { ok: false, reason: "no verdict recorded for the current diff — run `kj review`" };
+  }
+  if (verdict.verdict !== "approved") {
+    return { ok: false, verdict, reason: `review was rejected by ${verdict.reviewer} — fix the issues and run \`kj review\` again` };
+  }
+  return { ok: true, verdict };
+}

package/src/review/workspace.js

@@ -0,0 +1,21 @@
+/**
+ * Workspace detection for the review gate (KJC-TSK-0680). Field case: an
+ * agent claimed worktree isolation while editing the project root. The
+ * verdict now stamps WHERE the review actually ran, using the same proof
+ * the playbook demands: in a linked worktree, `git rev-parse --git-dir`
+ * differs from `--git-common-dir`. "root" | "worktree:<name>" | null
+ * (not a git repo — the gate itself will fail later with its own error).
+ */
+import path from "node:path";
+import { runCommand } from "../utils/process.js";
+
+export async function detectWorkspace(dir) {
+  const res = await runCommand("git", ["rev-parse", "--git-dir", "--git-common-dir", "--show-toplevel"], { cwd: dir });
+  if (res.exitCode !== 0) return null;
+  const [gitDir, commonDir, toplevel] = String(res.stdout).trim().split("\n").map((l) => l.trim());
+  if (!gitDir || !commonDir) return null;
+  const resolvedGit = path.resolve(dir, gitDir);
+  const resolvedCommon = path.resolve(dir, commonDir);
+  if (resolvedGit === resolvedCommon) return "root";
+  return `worktree:${path.basename(toplevel || dir)}`;
+}

package/src/roles/agent-role.js

@@ -0,0 +1,194 @@
+/**
+ * Base class for LLM-backed roles.
+ * Handles the common execute() flow: resolve provider → create agent → call LLM → parse output.
+ * Subclasses override hooks (buildPrompt, parseOutput, buildSuccessResult, buildSummary)
+ * instead of reimplementing the full execute() boilerplate.
+ *
+ * Conceptual mapping: `AgentRole` is a Karajan Role that delegates to an AI CLI
+ * subprocess (not to a provider HTTP API). From the outside it plays the same
+ * role as a Genkit Flow — named unit of work with a prompt and a parsed output —
+ * but every invocation spawns a fresh `execa` subprocess (claude, codex, gemini,
+ * aider, opencode) and the state lives in Karajan's session store, not in a
+ * provider-side conversation. See `docs/COMPARISON.md`.
+ *
+ * @alias Flow — similar to Genkit Flow but executed over subprocess CLIs, not API calls.
+ */
+import { BaseRole } from "./base-role.js";
+import { createAgent as defaultCreateAgent } from "../agents/index.js";
+import { withBrainRecovery } from "../brain/with-brain-recovery.js";
+
+/**
+ * Silence timeout (ms) for an agent subprocess, from
+ * config.session.max_agent_silence_minutes. runCommand kills a child
+ * that produces no output for this long — without it a hung coder /
+ * reviewer leaves `kj run` waiting forever. Returns null when unset.
+ * @param {object} config
+ * @returns {number|null}
+ */
+function resolveAgentSilenceTimeoutMs(config) {
+  const minutes = Number(config?.session?.max_agent_silence_minutes);
+  return Number.isFinite(minutes) && minutes > 0 ? Math.round(minutes * 60 * 1000) : null;
+}
+
+export class AgentRole extends BaseRole {
+  constructor({ name, config, logger, emitter = null, createAgentFn = null }) {
+    super({ name, config, logger, emitter });
+    this._createAgent = createAgentFn || defaultCreateAgent;
+  }
+
+  /** Provider fallback chain. Override for roles with non-standard chains. */
+  resolveProvider() {
+    return (
+      this.config?.roles?.[this.name]?.provider ||
+      this.config?.roles?.coder?.provider ||
+      "claude"
+    );
+  }
+
+  /** Agent method to call. Override with "reviewTask" for reviewer. */
+  get agentMethod() { return "runTask"; }
+
+  /** Create the agent. Override for special logic (e.g. HostAgent in coder). */
+  createAgentInstance(provider) {
+    return this._createAgent(provider, this.config, this.logger);
+  }
+
+  /**
+   * Build the prompt for this role. MUST be overridden.
+   * @param {*} input - raw input from pipeline
+   * @returns {Promise<{prompt: string, onOutput?: Function}>|{prompt: string, onOutput?: Function}|string}
+   */
+  async buildPrompt(_input) {
+    throw new Error(`${this.name}: buildPrompt() not implemented`);
+  }
+
+  /**
+   * Parse raw LLM output into structured data. Return null to trigger handleParseNull.
+   * @param {string} raw - raw agent output
+   * @returns {*} parsed result
+   */
+  parseOutput(raw) { return raw; }
+
+  /**
+   * Build the result object for a successful parse.
+   * @param {*} parsed - output of parseOutput
+   * @param {string} provider
+   * @param {object} agentResult - full agent result (for accessing .usage, .output, etc.)
+   * @returns {object} result to include in { ok, result, summary, usage }
+   */
+  buildSuccessResult(parsed, provider, _agentResult) { return { ...parsed, provider }; }
+
+  /** Build human-readable summary from parsed output. */
+  buildSummary(_parsed) { return `${this.name} completed`; }
+
+  /** Determine ok status from parsed result. Default: true. Override for verdict-based roles. */
+  isSuccessful(_parsed) { return true; }
+
+  /** Handle null parse (no JSON found). Default returns error. Override for lenient roles. */
+  handleParseNull(agentResult, provider) {
+    return {
+      ok: false,
+      result: { error: `Failed to parse ${this.name} output: no JSON found`, provider },
+      summary: `${this.name} output parse error: no JSON found`,
+      usage: agentResult.usage
+    };
+  }
+
+  /** Handle parse exception. Default returns error. Override for lenient roles. */
+  handleParseError(err, agentResult, provider) {
+    return {
+      ok: false,
+      result: { error: `Failed to parse ${this.name} output: ${err.message}`, provider },
+      summary: `${this.name} output parse error: ${err.message}`,
+      usage: agentResult.usage
+    };
+  }
+
+  /**
+   * Extract input fields from raw input. Default handles string-or-object.
+   * Override for roles needing extra fields.
+   */
+  extractInput(input) {
+    if (typeof input === "string") return { task: input, onOutput: null };
+    return {
+      task: input?.task || this.context?.task || "",
+      onOutput: input?.onOutput || null,
+      ...input
+    };
+  }
+
+  async execute(input) {
+    const extracted = this.extractInput(input);
+    const provider = this.resolveProvider();
+    const agent = this.createAgentInstance(provider);
+
+    const promptResult = await this.buildPrompt(extracted);
+    const { prompt, onOutput, stablePrompt, volatilePrompt } = typeof promptResult === "string"
+      ? { prompt: promptResult, onOutput: extracted.onOutput }
+      : { onOutput: extracted.onOutput, ...promptResult };
+
+    const runArgs = { prompt, role: this.name };
+    if (onOutput) runArgs.onOutput = onOutput;
+    // PAR-H (KJC-TSK-0631): per-call env additions for the agent
+    // subprocess (lane slot vars). Agents that ignore task.env simply
+    // run without them.
+    if (extracted.env) runArgs.env = extracted.env;
+    // Φ1-D (KJC-PCS-0057): roles that build their prompt as a
+    // stable/volatile layout forward both buckets so cache-aware agents
+    // (ClaudeAgent) can ship the stable block as system prompt. Agents
+    // that don't know the fields keep reading `prompt` as before.
+    if (stablePrompt && volatilePrompt) {
+      runArgs.stablePrompt = stablePrompt;
+      runArgs.volatilePrompt = volatilePrompt;
+    }
+    // Kill a hung agent: without a silence timeout a coder / reviewer
+    // that stalls with no output left `kj run` waiting indefinitely.
+    // PlannerRole set this itself; every other role was unprotected.
+    const silenceTimeoutMs = resolveAgentSilenceTimeoutMs(this.config);
+    if (silenceTimeoutMs) runArgs.silenceTimeoutMs = silenceTimeoutMs;
+
+    // KJC-TSK-0413 step B: TODAS las roles que heredan de AgentRole pasan
+    // por Brain Recovery aquí — cubre AuditRole, SecurityRole, HuReviewerRole,
+    // CoderRole, ArchitectRole, DiscoverRole, ImpeccableRole, RefactorerRole,
+    // ResearcherRole, TriageRole, etc. Roles con agentMethod custom (ej.
+    // reviewer usa reviewTask) también funcionan: el wrapper sólo necesita
+    // un objeto con la firma `runTask(args) → { ok, output, error, exitCode }`.
+    const result = await withBrainRecovery({
+      agent: { runTask: (args) => agent[this.agentMethod](args), provider },
+      taskArgs: runArgs,
+      role: this.name,
+      provider,
+      emitter: this.emitter,
+      logger: this.logger,
+      // KJC: sessionState lets withBrainRecovery persist a hibernating run
+      // to ~/.kj/standby/ so it can be resumed. Without it a quota-exhausted
+      // run had nothing to resume from. Caller (coder-stage etc.) passes it
+      // through the input object; extractInput forwards it via `...input`.
+      sessionState: extracted.sessionState || this.context?.sessionState || null,
+    });
+
+    if (!result.ok) {
+      const recoveryNote = result.recovery?.class ? ` [${result.recovery.class}]` : "";
+      return {
+        ok: false,
+        result: { error: result.error || result.output || `${this.name} failed${recoveryNote}`, provider, recovery: result.recovery, action: result.action, standbyFile: result.standbyFile || null },
+        summary: `${this.name} failed${recoveryNote}: ${result.recovery?.message || result.error || "unknown error"}`,
+        usage: result.usage
+      };
+    }
+
+    try {
+      const parsed = this.parseOutput(result.output);
+      if (parsed === null) return this.handleParseNull(result, provider);
+
+      return {
+        ok: this.isSuccessful(parsed),
+        result: this.buildSuccessResult(parsed, provider, result),
+        summary: this.buildSummary(parsed),
+        usage: result.usage
+      };
+    } catch (err) {
+      return this.handleParseError(err, result, provider);
+    }
+  }
+}

package/src/roles/architect-role.js

@@ -0,0 +1,77 @@
+import { AgentRole } from "./agent-role.js";
+import { buildArchitectPrompt, parseArchitectOutput } from "../prompts/architect.js";
+
+const EMPTY_ARCHITECTURE = {
+  type: "", layers: [], patterns: [], dataModel: { entities: [] },
+  apiContracts: [], dependencies: [], tradeoffs: []
+};
+
+export class ArchitectRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "architect" });
+  }
+
+  extractInput(input) {
+    if (typeof input === "string") return { task: input, researchContext: null, onOutput: null };
+    return {
+      task: input?.task || this.context?.task || "",
+      researchContext: input?.researchContext || null,
+      onOutput: input?.onOutput || null
+    };
+  }
+
+  async buildPrompt({ task, researchContext }) {
+    const prompt = await buildArchitectPrompt({
+      task, instructions: this.instructions, researchContext,
+      productContext: this.config?.productContext || null,
+      domainContext: this.config?.domainContext || null,
+      projectDir: this.config?.projectDir || null,
+      provider: this._resolvedProvider || (typeof this.resolveProvider === "function" ? this.resolveProvider() : null)
+    });
+    return { prompt };
+  }
+
+  parseOutput(raw) { return parseArchitectOutput(raw); }
+
+  buildSuccessResult(parsed, provider) {
+    return {
+      verdict: parsed.verdict,
+      architecture: parsed.architecture,
+      questions: parsed.questions,
+      provider
+    };
+  }
+
+  buildSummary(parsed) {
+    const parts = [];
+    const arch = parsed.architecture;
+    if (arch.type) parts.push(arch.type);
+    const layers = arch.layers?.length || 0;
+    if (layers) parts.push(`${layers} layer${layers === 1 ? "" : "s"}`);
+    const patterns = arch.patterns?.length || 0;
+    if (patterns) parts.push(`${patterns} pattern${patterns === 1 ? "" : "s"}`);
+    const entities = arch.dataModel?.entities?.length || 0;
+    if (entities) parts.push(`${entities} entit${entities === 1 ? "y" : "ies"}`);
+    const questions = parsed.questions?.length || 0;
+    if (questions) parts.push(`${questions} question${questions === 1 ? "" : "s"}`);
+    return parts.length
+      ? `Architecture complete: ${parts.join(", ")} (verdict: ${parsed.verdict})`
+      : "Architecture complete";
+  }
+
+  handleParseNull(agentResult, provider) {
+    return {
+      ok: true,
+      result: {
+        verdict: "needs_clarification", architecture: { ...EMPTY_ARCHITECTURE },
+        questions: [], raw: agentResult.output, provider
+      },
+      summary: "Architecture complete (unstructured output)",
+      usage: agentResult.usage
+    };
+  }
+
+  handleParseError(_err, agentResult, provider) {
+    return this.handleParseNull(agentResult, provider);
+  }
+}

package/src/roles/audit-role.js

@@ -0,0 +1,258 @@
+import { AgentRole } from "./agent-role.js";
+import { buildAuditPrompt, parseAuditOutput, AUDIT_DIMENSIONS } from "../prompts/audit.js";
+import { measureBasalCost, loadPreviousAudit, saveAuditSnapshot, computeGrowthDelta } from "../audit/basal-cost.js";
+import { detectProjectStack } from "../utils/stack-detect.js";
+import { collectSonarFindings } from "../audit/sonar-findings.js";
+import { collectWebPerfInput } from "../audit/webperf-input.js";
+import { collectOsvFindings } from "../audit/osv-findings.js";
+import { collectSemgrepFindings } from "../audit/semgrep-findings.js";
+import { collectInfraFindings } from "../audit/infra-findings.js";
+import { collectCircularDeps } from "../audit/circular-deps.js";
+import { collectDeadExports } from "../audit/dead-exports.js";
+import { collectInjectionFindings } from "../audit/injection-findings.js";
+import { collectAiSlop } from "../audit/ai-slop-findings.js";
+
+function parseDimensions(dimensionsStr) {
+  if (!dimensionsStr || dimensionsStr === "all") return null;
+  const requested = dimensionsStr.split(",").map(d => d.trim().toLowerCase());
+  const mapped = requested.map(d => d === "quality" ? "codeQuality" : d);
+  const valid = mapped.filter(d => AUDIT_DIMENSIONS.includes(d));
+  return valid.length > 0 ? valid : null;
+}
+
+function buildSummary(parsed) {
+  const { summary } = parsed;
+  const parts = [];
+  if (summary.critical > 0) parts.push(`${summary.critical} critical`);
+  if (summary.high > 0) parts.push(`${summary.high} high`);
+  if (summary.medium > 0) parts.push(`${summary.medium} medium`);
+  if (summary.low > 0) parts.push(`${summary.low} low`);
+  const findingsStr = parts.length > 0 ? parts.join(", ") : "no issues";
+  return `Overall health: ${summary.overallHealth}. ${summary.totalFindings} findings (${findingsStr})`;
+}
+
+export class AuditRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "audit" });
+  }
+
+  /**
+   * Run the deterministic side of an audit — basalCost, stack detection,
+   * Sonar issues, WebPerf input — without invoking the LLM. Cheap (no
+   * tokens, no API call). KJC-TSK-0364 splits the original execute() into
+   * this collector + executeWithDeterministic() so the CLI can show
+   * deterministic findings first and ask the user before paying for the
+   * LLM phase.
+   *
+   * @param {object|string} input - same shape execute() accepts
+   * @returns {Promise<object>} deterministic context (the same data
+   *   execute() would gather internally)
+   */
+  async collectDeterministic(input) {
+    // KJC-TSK-0695: securityOnly = the focused pass an agent self-invokes
+    // when a task touches sensitive surface. Only the security collectors
+    // run (sonar, osv, semgrep, injection) — zero tokens, fast.
+    const securityOnly = typeof input === "object" ? Boolean(input?.securityOnly) : false;
+    const noSonar = typeof input === "object" ? Boolean(input?.noSonar) : false;
+    const noOsv = typeof input === "object" ? Boolean(input?.noOsv) : false;
+    const noSemgrep = typeof input === "object" ? Boolean(input?.noSemgrep) : false;
+    const noMadge = (typeof input === "object" ? Boolean(input?.noMadge) : false) || securityOnly;
+    const noKnip = (typeof input === "object" ? Boolean(input?.noKnip) : false) || securityOnly;
+    const noInjectionScan = typeof input === "object" ? Boolean(input?.noInjectionScan) : false;
+    const noInfraScan = typeof input === "object" ? Boolean(input?.noInfraScan) : false;
+    const noAiSlop = (typeof input === "object" ? Boolean(input?.noAiSlop) : false) || securityOnly;
+    const projectDir = this.config?.projectDir || process.cwd();
+    let basalCost = null;
+    let growthDelta = null;
+    let stack = null;
+    let sonarFindings = null;
+    let webperf = null;
+    let osvFindings = null;
+    let semgrepFindings = null;
+    let circularDeps = null;
+    let deadExports = null;
+    let injectionFindings = null;
+    let infraFindings = null;
+    let aiSlop = null;
+    if (!securityOnly) {
+      try {
+        basalCost = await measureBasalCost(projectDir);
+        const previous = await loadPreviousAudit(projectDir);
+        growthDelta = computeGrowthDelta(basalCost, previous);
+      } catch { /* basal cost is best-effort */ }
+    }
+    try {
+      stack = await detectProjectStack(projectDir);
+    } catch { /* stack detect is best-effort */ }
+    if (!noSonar) {
+      try {
+        sonarFindings = await collectSonarFindings(this.config, this.logger);
+      } catch { /* sonar fetch is best-effort */ }
+    }
+    if (!securityOnly) {
+      try {
+        webperf = collectWebPerfInput(stack, this.config);
+      } catch { /* webperf input is best-effort */ }
+    }
+    // OSV vulnerabilities — KJC-TSK-0365. Best-effort: missing
+    // osv-scanner binary returns available:false and the audit
+    // continues without the section.
+    if (!noOsv) {
+      try {
+        osvFindings = await collectOsvFindings(projectDir, this.logger);
+      } catch { /* osv-scanner is best-effort */ }
+    }
+    // Semgrep SAST — KJC-TSK-0366. Best-effort: missing semgrep binary
+    // returns available:false and the audit continues without the section.
+    if (!noSemgrep) {
+      try {
+        semgrepFindings = await collectSemgrepFindings(projectDir, this.logger);
+      } catch { /* semgrep is best-effort */ }
+    }
+    // Madge circular-import deps — KJC-TSK v2.17. Stack-aware: skipped for
+    // non-JS/TS projects. Best-effort: any failure returns available:false
+    // and the audit continues without the section.
+    if (!noMadge) {
+      try {
+        circularDeps = await collectCircularDeps(projectDir, stack, this.config, this.logger);
+      } catch { /* madge is best-effort */ }
+    }
+    // Knip dead-exports — KJC-TSK v2.17. Stack-aware, JS/TS only, needs
+    // package.json. Best-effort: any failure returns available:false and
+    // the audit continues without the section.
+    if (!noKnip) {
+      try {
+        deadExports = await collectDeadExports(projectDir, stack, this.config, this.logger);
+      } catch { /* knip is best-effort */ }
+    }
+    if (!noInjectionScan) {
+      try {
+        injectionFindings = await collectInjectionFindings(projectDir, this.logger);
+      } catch { /* injection scan is best-effort (KJC-TSK-0498) */ }
+    }
+    // Checkov infra misconfigs — INF-C (KJC-TSK-0760). Security surface, so
+    // it ALSO runs in securityOnly. Best-effort: no infra markers or missing
+    // checkov return available:false declaring why.
+    if (!noInfraScan) {
+      try {
+        infraFindings = await collectInfraFindings(projectDir, this.logger);
+      } catch { /* checkov is best-effort */ }
+    }
+    // AI-slop tells (KJC-TSK-0503). Deterministic, offline, regex-based.
+    // Local equivalent of Deslopify-style review. Best-effort.
+    if (!noAiSlop) {
+      try {
+        aiSlop = await collectAiSlop(projectDir);
+      } catch { /* ai-slop scan is best-effort */ }
+    }
+    return { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports, injectionFindings, infraFindings, aiSlop };
+  }
+
+  /**
+   * Run the LLM phase of an audit using a pre-collected deterministic
+   * context. KJC-TSK-0364: separated from execute() so the CLI can run
+   * collectDeterministic() first, show findings, prompt, and only then
+   * call this if the user wants to spend tokens.
+   */
+  async executeWithDeterministic(input, deterministicCtx) {
+    const task = typeof input === "string" ? input : input?.task || this.context?.task || "";
+    const onOutput = typeof input === "string" ? null : input?.onOutput || null;
+    const rawDimensions = typeof input === "object" ? input?.dimensions || null : null;
+    const context = typeof input === "object" ? input?.context || null : null;
+    const dimensions = typeof rawDimensions === "string" ? parseDimensions(rawDimensions) : rawDimensions;
+
+    const { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports } = deterministicCtx;
+
+    const provider = this.resolveProvider();
+    const agent = this.createAgentInstance(provider);
+    const prompt = buildAuditPrompt({ task, instructions: this.instructions, dimensions, context, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports });
+    const runArgs = { prompt, role: "audit" };
+    if (onOutput) runArgs.onOutput = onOutput;
+    const startedAt = Date.now();
+    const result = await agent.runTask(runArgs);
+    const durationMs = Date.now() - startedAt;
+
+    const usage = extractUsage(result, { provider, durationMs });
+
+    if (!result.ok) {
+      return { ok: false, result: { error: result.error || result.output || "Audit failed", provider }, summary: `Audit failed: ${result.error || "unknown error"}`, usage };
+    }
+
+    try {
+      const parsed = parseAuditOutput(result.output);
+      if (!parsed) {
+        return { ok: true, result: { raw: result.output, provider }, summary: "Audit complete (unstructured output)", usage };
+      }
+      if (basalCost) { try { await saveAuditSnapshot(projectDir, basalCost); } catch { /* best-effort */ } }
+
+      return {
+        ok: true,
+        result: {
+          summary: parsed.summary, dimensions: parsed.dimensions,
+          topRecommendations: parsed.topRecommendations,
+          textSummary: parsed.textSummary || undefined,
+          basalCost: basalCost || undefined, growthDelta: growthDelta || undefined,
+          stack: stack || undefined,
+          sonarFindings: sonarFindings?.available ? sonarFindings : undefined,
+          webperf: webperf?.available ? webperf : undefined,
+          osvFindings: osvFindings?.available ? osvFindings : undefined,
+          semgrepFindings: semgrepFindings?.available ? semgrepFindings : undefined,
+          circularDeps: circularDeps?.available ? circularDeps : undefined,
+          deadExports: deadExports?.available ? deadExports : undefined,
+          provider
+        },
+        summary: buildSummary(parsed),
+        usage
+      };
+    } catch {
+      return { ok: true, result: { raw: result.output, provider }, summary: "Audit complete (unstructured output)", usage };
+    }
+  }
+
+  /**
+   * Convenience: run both phases in one call. Identical to the previous
+   * (single-phase) execute() so MCP and pipeline callers don't change.
+   */
+  async execute(input) {
+    const deterministicCtx = await this.collectDeterministic(input);
+    return this.executeWithDeterministic(input, deterministicCtx);
+  }
+}
+
+/**
+ * Consolidate the usage telemetry the agent spreads across its top-level
+ * result fields. Returns a single object so consumers (CLI formatter,
+ * report-file writer, MCP) don't need to know about the spread shape.
+ *
+ * Consumed by tests via vi.importActual (knip blind spot) — keep exported.
+ * @public
+ * @param {object} result - raw agent.runTask() return
+ * @param {{provider: string, durationMs: number}} ctx
+ * @returns {{available: boolean, provider: string, model?: string, tokens_in?: number, tokens_out?: number, cached_tokens?: number, total_tokens?: number, cost_usd?: number, durationMs: number, reason?: string}}
+ */
+export function extractUsage(result, { provider, durationMs }) {
+  if (!result || typeof result !== "object") {
+    return { available: false, provider, durationMs, reason: "no agent result" };
+  }
+  const tokens_in = Number.isFinite(result.tokens_in) ? result.tokens_in : null;
+  const tokens_out = Number.isFinite(result.tokens_out) ? result.tokens_out : null;
+  if (tokens_in === null && tokens_out === null) {
+    return { available: false, provider, model: result.model, durationMs, reason: `provider "${provider}" did not report token usage` };
+  }
+  // KJC-BUG-0085: cached_tokens must survive this consolidation — the
+  // budget chain (computeUsage → BudgetTracker → summary.md Cache hits →
+  // telemetry) reads it from `usage` and the audit is the most expensive
+  // role of the session.
+  const cached_tokens = Number.isFinite(result.cached_tokens) ? result.cached_tokens : 0;
+  return {
+    available: true,
+    provider,
+    model: result.model,
+    tokens_in: tokens_in ?? 0,
+    tokens_out: tokens_out ?? 0,
+    cached_tokens,
+    total_tokens: (tokens_in ?? 0) + (tokens_out ?? 0),
+    cost_usd: typeof result.cost_usd === "number" ? result.cost_usd : null,
+    durationMs,
+  };
+}