@karajan-family/code 4.21.0

package/src/mutate/runner.js

@@ -0,0 +1,72 @@
+/**
+ * Mutation runner + report normalizer. Executes a mutation tool and parses its
+ * report (the shared mutation-testing-report-schema, `files[].mutants[]`) into a
+ * tool-agnostic result the CLI, reviewer and CI can all consume the same way.
+ * `exec` and `readReport` are injectable so the logic is testable without a
+ * real mutation tool installed.
+ */
+
+import { runCommand } from "../utils/process.js";
+
+// A mutant the test suite detected (killed or forced to time out).
+const KILLED = new Set(["Killed", "Timeout"]);
+// A real survivor: the mutation went undetected (or no test covered it).
+const SURVIVED = new Set(["Survived", "NoCoverage"]);
+// Not a real result: equivalent, config-ignored, or uncompilable mutants.
+const EXCLUDED = new Set(["Ignored", "CompileError", "RuntimeError"]);
+
+/**
+ * Normalize a standard-schema report into `{score, killed, survived, total, excluded}`.
+ * `score` is the covered mutation score `killed / (killed + survived) * 100`, or
+ * null when there is nothing to mutate. Excluded mutants never count as survivors.
+ * @param {{files?: Record<string, {mutants?: Array<object>}>}} report
+ */
+export function parseStandardReport(report) {
+  const files = report?.files ?? {};
+  let killed = 0;
+  let excluded = 0;
+  const survived = [];
+  for (const [file, entry] of Object.entries(files)) {
+    for (const mutant of entry?.mutants ?? []) {
+      const { status } = mutant;
+      if (EXCLUDED.has(status)) {
+        excluded += 1;
+      } else if (KILLED.has(status)) {
+        killed += 1;
+      } else if (SURVIVED.has(status)) {
+        survived.push({
+          file,
+          line: mutant.location?.start?.line ?? null,
+          mutator: mutant.mutatorName ?? null,
+          status,
+        });
+      }
+    }
+  }
+  const total = killed + survived.length;
+  const score = total === 0 ? null : Number(((killed / total) * 100).toFixed(2));
+  return { score, killed, survived, total, excluded };
+}
+
+/**
+ * Run a mutation tool and normalize the report it produced.
+ * @param {object} params
+ * @param {string} params.binary
+ * @param {string[]} [params.args]
+ * @param {string} [params.cwd]
+ * @param {Function} [params.exec] - injectable command runner (default runCommand)
+ * @param {() => Promise<object>} [params.readReport] - reads/parses the tool's report file
+ */
+export async function runMutation({ binary, args = [], cwd, exec = runCommand, readReport }) {
+  const run = await exec(binary, args, { cwd }).catch((err) => ({
+    exitCode: 1,
+    stdout: "",
+    stderr: String(err?.message ?? err),
+  }));
+  let result = null;
+  if (readReport) {
+    const report = await readReport().catch(() => null);
+    if (report) result = parseStandardReport(report);
+  }
+  return { exitCode: run.exitCode, result, stdout: run.stdout, stderr: run.stderr };
+}

package/src/mutate/tool-registry.js

@@ -0,0 +1,90 @@
+/**
+ * Mutation-tool registry.
+ *
+ * Maps a detected stack language (see `src/harden/stack-roots.js`) to the
+ * mutation-testing runner Karajan drives for it. Unknown or native-mobile
+ * languages resolve to an explicit `{ supported: false, reason }` object —
+ * never a silent fallback to another tool.
+ *
+ * `scope` describes how the runner limits mutation to a subset of files, so
+ * diff-scoped runs (`kj mutate --since <ref>`) can pass only the changed paths:
+ *   - flag:      the CLI flag that accepts the file list
+ *   - separator: how multiple paths are joined for that flag
+ */
+
+const TOOLS_BY_LANGUAGE = {
+  javascript: {
+    id: "stryker",
+    binary: "stryker",
+    installHint: "npm install --save-dev @stryker-mutator/core",
+    scope: { flag: "--mutate", separator: "," },
+    reportFormat: "json",
+  },
+  typescript: {
+    id: "stryker",
+    binary: "stryker",
+    installHint: "npm install --save-dev @stryker-mutator/core",
+    scope: { flag: "--mutate", separator: "," },
+    reportFormat: "json",
+  },
+  python: {
+    id: "mutmut",
+    binary: "mutmut",
+    installHint: "pip install mutmut",
+    scope: { flag: "--paths-to-mutate", separator: "," },
+    reportFormat: "json",
+  },
+  php: {
+    id: "infection",
+    binary: "infection",
+    installHint: "composer require --dev infection/infection",
+    scope: { flag: "--filter", separator: "," },
+    reportFormat: "json",
+  },
+  go: {
+    id: "go-mutesting",
+    binary: "go-mutesting",
+    installHint: "go install github.com/avito-tech/go-mutesting/cmd/go-mutesting@latest",
+    scope: { flag: "", separator: " " },
+    reportFormat: "json",
+  },
+  java: {
+    id: "pitest",
+    binary: "pitest",
+    installHint: "add org.pitest:pitest-maven (Maven) or gradle-pitest-plugin",
+    scope: { flag: "targetClasses", separator: "," },
+    reportFormat: "json",
+  },
+};
+
+const UNSUPPORTED_REASONS = {
+  swift: "Swift (iOS) has no mutation runner wired into Karajan",
+  kotlin: "Kotlin (Android) has no mutation runner wired into Karajan",
+};
+
+function normalize(language) {
+  if (typeof language !== "string") return "";
+  return language.trim().toLowerCase();
+}
+
+/**
+ * @param {string} language - language id from `detectStackRoots`
+ * @returns {{supported: true, id, binary, language, installHint, scope, reportFormat}
+ *          | {supported: false, language, reason: string}}
+ */
+export function getMutationTool(language) {
+  const key = normalize(language);
+  const tool = TOOLS_BY_LANGUAGE[key];
+  if (tool) {
+    return { supported: true, language: key, ...tool };
+  }
+  const reason =
+    UNSUPPORTED_REASONS[key] ??
+    `no mutation-testing tool is registered for language "${key || "(none)"}"`;
+  return { supported: false, language: key, reason };
+}
+
+/** @returns {string[]} languages with a registered mutation tool */
+export function listSupportedLanguages() {
+  return Object.keys(TOOLS_BY_LANGUAGE);
+}

package/src/onboarder/cache.js

@@ -0,0 +1,24 @@
+// KJC-TSK-0384 PR 3 — read the cached Architecture Brief deterministically.
+// briefPath() is exported by src/commands/onboard.js so the writer and
+// reader share the same slug rule.
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+
+import { briefPath } from "../commands/onboard.js";
+
+/**
+ * Read the cached Architecture Brief for `projectDir`. Returns:
+ *   { found: true,  path, content }  — when the file exists
+ *   { found: false, path }           — when it does not
+ * Never throws.
+ */
+export async function readCachedBrief(projectDir) {
+  const p = briefPath(projectDir);
+  if (!existsSync(p)) return { found: false, path: p };
+  try {
+    const content = await readFile(p, "utf8");
+    return { found: true, path: p, content };
+  } catch {
+    return { found: false, path: p };
+  }
+}

package/src/onboarder/collectors/framework-multilang.js

@@ -0,0 +1,64 @@
+// KJC-TSK-0477 — Detectores mínimos de framework por stack (Python/Rust/Go).
+// Consume el sniff de manifests (PR-C) para conocer deps + presencia de
+// archivos canónicos. Cero deps externas, fail-soft (devuelve null o lista
+// vacía). El brief markdown se sintetiza río abajo desde estos campos.
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+const PY_FW = [
+  { name: "django", deps: ["django"], file: "manage.py" },
+  { name: "flask", deps: ["flask"], file: "app.py" },
+  { name: "fastapi", deps: ["fastapi"], file: "main.py" },
+];
+const RUST_FW = [
+  { name: "axum", deps: ["axum"] },
+  { name: "actix-web", deps: ["actix-web"] },
+  { name: "rocket", deps: ["rocket"] },
+];
+const GO_FW = [
+  { name: "gin", deps: ["github.com/gin-gonic/gin"] },
+  { name: "echo", deps: ["github.com/labstack/echo"] },
+  { name: "fiber", deps: ["github.com/gofiber/fiber"] },
+];
+
+function matchFw(manifestRaw, projectDir, table) {
+  const found = [];
+  for (const fw of table) {
+    const hasDep = fw.deps.some((d) => manifestRaw?.includes(d));
+    const hasFile = fw.file ? existsSync(path.join(projectDir, fw.file)) : false;
+    if (hasDep || hasFile) found.push({ name: fw.name, viaDep: hasDep, viaFile: hasFile });
+  }
+  return found;
+}
+
+function detectLayout(projectDir, expected) {
+  return expected.filter((d) => existsSync(path.join(projectDir, d)));
+}
+
+// Detect frameworks + canonical layout per stack. Returns one entry per
+// detected manifest stack (skips Node — the existing JS path already covers
+// that with detectProjectStack).
+export function detectFrameworksMultiLang(projectDir, manifests = [], { readManifest } = {}) {
+  const out = [];
+  for (const m of manifests) {
+    if (m.stack === "node") continue;
+    const raw = readManifest ? readManifest(m) : "";
+    if (m.stack === "python") {
+      out.push({ stack: "python", manifest: m.manifest,
+        frameworks: matchFw(raw, projectDir, PY_FW),
+        layout: detectLayout(projectDir, ["apps", "src", "tests"]) });
+    } else if (m.stack === "rust") {
+      const isBin = existsSync(path.join(projectDir, "src", "main.rs"));
+      const isLib = existsSync(path.join(projectDir, "src", "lib.rs"));
+      out.push({ stack: "rust", manifest: m.manifest,
+        crateType: isBin && isLib ? "mixed" : isBin ? "binary" : isLib ? "library" : null,
+        frameworks: matchFw(raw, projectDir, RUST_FW),
+        layout: detectLayout(projectDir, ["src", "tests", "examples", "benches"]) });
+    } else if (m.stack === "go") {
+      out.push({ stack: "go", manifest: m.manifest, modulePath: m.name || null,
+        frameworks: matchFw(raw, projectDir, GO_FW),
+        layout: detectLayout(projectDir, ["cmd", "internal", "pkg"]) });
+    }
+  }
+  return out;
+}

package/src/onboarder/collectors/index.js

@@ -0,0 +1,136 @@
+// Onboarder collectors — deterministic, zero-LLM extractors. Each pure,
+// JSON-serialisable, fail-soft (returns null on the slot, never throws).
+// Output bundle is consumed by PR 2 synthesis or dumped via `--no-synth`.
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { join, relative } from "node:path";
+
+import { detectProjectStack } from "../../utils/stack-detect.js";
+import { sniffManifests } from "../../utils/manifest-sniff.js";
+import { detectFrameworksMultiLang } from "./framework-multilang.js";
+
+const IGNORED_DIRS = new Set(["node_modules", ".git", "dist", "build", "coverage", ".karajan", ".next", "__pycache__"]);
+
+function safeRun(cmd, args, opts = {}) {
+  try { return execFileSync(cmd, args, { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"], ...opts }).trim(); }
+  catch { return null; }
+}
+
+// Tree summary: immediate dirs with rough byte count. Ignores noise dirs.
+export async function collectTree(projectDir, { maxDepth = 2 } = {}) {
+  async function walk(dir, depth) {
+    if (depth > maxDepth) return [];
+    let entries;
+    try { entries = await readdir(dir, { withFileTypes: true }); } catch { return []; }
+    const out = [];
+    for (const ent of entries) {
+      if (ent.name.startsWith(".") && ent.name !== ".github") continue;
+      if (IGNORED_DIRS.has(ent.name)) continue;
+      const sub = join(dir, ent.name);
+      if (ent.isDirectory()) {
+        const children = await walk(sub, depth + 1);
+        let bytes = 0;
+        for (const c of children) bytes += c.bytes || 0;
+        out.push({ path: relative(projectDir, sub), kind: "dir", bytes, children });
+      } else if (ent.isFile()) {
+        try { out.push({ path: relative(projectDir, sub), kind: "file", bytes: statSync(sub).size }); } catch { /* race */ }
+      }
+    }
+    return out;
+  }
+  return walk(projectDir, 0);
+}
+
+// Git log + branches + hot files. Returns null on non-git (greenfield).
+export function collectGitHistory(projectDir, { maxHotFiles = 10 } = {}) {
+  const inside = safeRun("git", ["rev-parse", "--is-inside-work-tree"], { cwd: projectDir });
+  if (inside !== "true") return null;
+  const commitsRaw = safeRun("git", ["log", "--oneline", "-n", "100"], { cwd: projectDir }) || "";
+  const branchesRaw = safeRun("git", ["branch", "--list", "--all", "--format=%(refname:short)"], { cwd: projectDir }) || "";
+  const hotRaw = safeRun("git", ["log", "--name-only", "--pretty=format:", "-n", "200"], { cwd: projectDir }) || "";
+  const counts = {};
+  for (const line of hotRaw.split("\n").map((s) => s.trim()).filter(Boolean)) {
+    counts[line] = (counts[line] || 0) + 1;
+  }
+  const hotFiles = Object.entries(counts)
+    .sort((a, b) => b[1] - a[1]).slice(0, maxHotFiles)
+    .map(([file, touches]) => ({ file, touches }));
+  return {
+    commitCount: commitsRaw ? commitsRaw.split("\n").length : 0,
+    branches: branchesRaw.split("\n").filter(Boolean),
+    hotFiles,
+    headSha: safeRun("git", ["rev-parse", "HEAD"], { cwd: projectDir }) || null,
+  };
+}
+
+// Presence-check of known config files + package.json scripts.
+export function collectConfigs(projectDir) {
+  const configFiles = [
+    "package.json", "pyproject.toml", "Cargo.toml", "go.mod",
+    "tsconfig.json", "jsconfig.json",
+    ".eslintrc.js", ".eslintrc.json", "eslint.config.js",
+    "vitest.config.js", "vitest.config.ts", "jest.config.js", "jest.config.ts",
+    "firebase.json", ".gcloudignore", "Dockerfile", "docker-compose.yml",
+    ".github/workflows", ".gitlab-ci.yml", "Makefile",
+  ];
+  const present = configFiles.filter((f) => existsSync(join(projectDir, f)));
+  let scripts = null;
+  try {
+    const pkg = JSON.parse(readFileSync(join(projectDir, "package.json"), "utf8"));
+    scripts = pkg.scripts || null;
+  } catch { /* not a node project */ }
+  return { present, scripts };
+}
+
+// Discover ADR files under docs/adr/, docs/adrs/, docs/architecture/, root.
+export async function collectAdrs(projectDir) {
+  const dirs = ["docs/adr", "docs/adrs", "docs/architecture", "."];
+  const found = [];
+  for (const d of dirs) {
+    const abs = join(projectDir, d);
+    if (!existsSync(abs)) continue;
+    try {
+      const entries = await readdir(abs);
+      for (const f of entries) {
+        if (/^adr-?\d|^\d{4}-.+\.md$/i.test(f) || /architecture.*\.md$/i.test(f)) {
+          found.push(relative(projectDir, join(abs, f)));
+        }
+      }
+    } catch { /* unreadable */ }
+  }
+  return found;
+}
+
+// Read a manifest file as raw text (best-effort) for framework dep matching.
+function readManifestRaw(projectDir) {
+  return (m) => {
+    try { return readFileSync(join(projectDir, m.manifest), "utf8"); }
+    catch { return ""; }
+  };
+}
+
+// One-shot bundle: every slot is independent; missing slots → null/[].
+// KJC-TSK-0477: manifests (multi-stack) + frameworksMultiLang (Python/Rust/Go)
+// se añaden de forma aditiva para que el brief pueda incluir secciones
+// condicionales sin romper consumidores existentes.
+export async function collectAll(projectDir) {
+  const [stack, tree, adrs, manifests] = await Promise.all([
+    detectProjectStack(projectDir).catch(() => null),
+    collectTree(projectDir).catch(() => []),
+    collectAdrs(projectDir).catch(() => []),
+    sniffManifests(projectDir).catch(() => []),
+  ]);
+  const frameworksMultiLang = detectFrameworksMultiLang(projectDir, manifests, { readManifest: readManifestRaw(projectDir) });
+  return {
+    projectDir,
+    stack,
+    manifests,
+    frameworksMultiLang,
+    tree,
+    git: collectGitHistory(projectDir),
+    configs: collectConfigs(projectDir),
+    adrs,
+    collectedAt: new Date().toISOString(),
+  };
+}

package/src/orchestrator/agent-fallback.js

@@ -0,0 +1,81 @@
+import { createAgent } from "../agents/index.js";
+import { addCheckpoint } from "../session/store.js";
+import { detectRateLimit } from "../utils/rate-limit-detector.js";
+
+/**
+ * Run a coder-like role with fallback on rate limit.
+ * Tries the primary agent first. If it fails with a rate limit,
+ * switches to the fallback agent (if configured).
+ * Non-rate-limit failures stop immediately (no fallback).
+ *
+ * Returns { execResult, attempts, allRateLimited }
+ */
+export async function runCoderWithFallback({
+  coderName,
+  fallbackCoder,
+  config,
+  logger,
+  emitter,
+  RoleClass,
+  roleInput,
+  session,
+  iteration,
+  onAttemptResult
+}) {
+  const candidates = [coderName];
+  if (fallbackCoder && fallbackCoder !== coderName) {
+    candidates.push(fallbackCoder);
+  }
+
+  const attempts = [];
+
+  for (const name of candidates) {
+    const agentConfig = {
+      ...config,
+      roles: { ...config.roles, coder: { ...config.roles?.coder, provider: name } }
+    };
+
+    const role = new RoleClass({ config: agentConfig, logger, emitter, createAgentFn: createAgent });
+    await role.init();
+
+    const execResult = await role.execute(roleInput);
+
+    if (onAttemptResult) {
+      await onAttemptResult({ coder: name, result: execResult.result });
+    }
+
+    const rateLimited = !execResult.ok && detectRateLimit({
+      stderr: execResult.result?.error || "",
+      stdout: execResult.result?.output || ""
+    }).isRateLimit;
+
+    attempts.push({
+      coder: name,
+      ok: execResult.ok,
+      rateLimited,
+      result: execResult.result,
+      execResult
+    });
+
+    await addCheckpoint(session, {
+      stage: "coder-attempt",
+      iteration,
+      coder: name,
+      ok: execResult.ok,
+      rateLimited
+    });
+
+    if (execResult.ok) {
+      return { execResult, attempts, allRateLimited: false };
+    }
+
+    // Only fallback on rate limit errors
+    if (!rateLimited) {
+      return { execResult: null, attempts, allRateLimited: false };
+    }
+
+    logger.warn(`Agent ${name} hit rate limit, trying fallback...`);
+  }
+
+  return { execResult: null, attempts, allRateLimited: true };
+}

package/src/orchestrator/brain-coordinator.js

@@ -0,0 +1,186 @@
+// Brain Coordinator: integrates Karajan Brain + 5 support modules into the pipeline.
+// Replaces ad-hoc role-to-role communication with a central intelligence.
+
+import * as queue from "./feedback-queue.js";
+import * as enrich from "./feedback-enrichment.js";
+import { verifyCoderOutput, VerificationTracker } from "./verification-gate.js";
+import { executeActions } from "./direct-actions.js";
+import { compressRoleOutput, measureCompression } from "./role-output-compressor.js";
+
+/**
+ * @typedef {Object} BrainContext
+ * @property {Object} feedbackQueue - structured feedback queue
+ * @property {VerificationTracker} verificationTracker - tracks coder changes
+ * @property {Object} compressionStats - token savings per role
+ * @property {boolean} enabled - whether brain coordination is active
+ */
+
+/**
+ * Create a new brain context for a pipeline session.
+ */
+export function createBrainContext({ enabled = false } = {}) {
+  return {
+    feedbackQueue: queue.createQueue(),
+    verificationTracker: new VerificationTracker(),
+    compressionStats: { totalSaved: 0, perRole: {} },
+    extensionCount: 0,
+    enabled
+  };
+}
+
+/**
+ * Check if brain coordination is enabled for this config.
+ */
+export function isBrainEnabled(config) {
+  return Boolean(config?.brain?.enabled) || Boolean(config?.pipeline?.brain?.enabled);
+}
+
+/**
+ * After a role completes, push its feedback to the queue and compress.
+ * Returns the compressed output for passing to next role.
+ */
+export function processRoleOutput(ctx, { roleName, output, iteration }) {
+  if (!ctx.enabled) return output;
+
+  // Compress for next-role context
+  const compressed = compressRoleOutput(roleName, output);
+  const stats = measureCompression(output, compressed);
+  ctx.compressionStats.totalSaved += stats.savedTokens;
+  ctx.compressionStats.perRole[roleName] = stats;
+
+  // Extract feedback entries from specific role outputs
+  const entries = extractFeedbackEntries(roleName, output, iteration);
+  if (entries.length > 0) {
+    queue.addEntries(ctx.feedbackQueue, entries);
+    enrich.enrichQueue(ctx.feedbackQueue);
+    queue.deduplicate(ctx.feedbackQueue);
+    queue.prioritize(ctx.feedbackQueue);
+  }
+
+  return compressed;
+}
+
+/**
+ * Extract structured feedback entries from a role's output.
+ */
+function extractFeedbackEntries(roleName, output, iteration) {
+  if (!output || typeof output !== "object") return [];
+
+  const entries = [];
+  if (roleName === "reviewer" && output.blocking_issues) {
+    for (const issue of output.blocking_issues) {
+      entries.push({
+        source: "reviewer",
+        severity: issue.severity || "medium",
+        description: issue.description || "",
+        file: issue.file || null,
+        line: issue.line || null,
+        suggestedFix: issue.suggested_fix || null,
+        id: issue.id || null,
+        iteration
+      });
+    }
+  } else if (roleName === "tester" && output.verdict === "fail") {
+    const missing = output.missing_scenarios || [];
+    for (const scenario of missing) {
+      entries.push({
+        source: "tester",
+        severity: "high",
+        category: "tests",
+        description: `Missing scenario: ${scenario}`,
+        iteration
+      });
+    }
+    if (output.coverage?.overall != null && output.coverage.overall < 80) {
+      entries.push({
+        source: "tester",
+        severity: "high",
+        category: "tests",
+        description: `Coverage below 80% (${output.coverage.overall}%)`,
+        iteration
+      });
+    }
+    // Catch-all: tester failed but no structured detail → still record the failure
+    if (entries.length === 0) {
+      entries.push({
+        source: "tester",
+        severity: "high",
+        category: "tests",
+        description: output.summary || "Tester failed (no structured detail available)",
+        iteration
+      });
+    }
+  } else if (roleName === "security" && output.verdict === "fail") {
+    for (const vuln of output.vulnerabilities || []) {
+      entries.push({
+        source: "security",
+        severity: vuln.severity || "high",
+        category: "security",
+        description: vuln.description || "",
+        file: vuln.file || null,
+        line: vuln.line || null,
+        suggestedFix: vuln.fix_suggestion || null,
+        iteration
+      });
+    }
+    // Catch-all: security failed but no structured vulnerabilities → still record
+    if (entries.length === 0) {
+      entries.push({
+        source: "security",
+        severity: "high",
+        category: "security",
+        description: output.summary || "Security gate failed (no structured detail available)",
+        iteration
+      });
+    }
+  }
+  return entries;
+}
+
+/**
+ * Before coder runs, format the feedback queue as an actionable prompt.
+ */
+export function buildCoderFeedbackPrompt(ctx) {
+  if (!ctx.enabled || ctx.feedbackQueue.entries.length === 0) return null;
+  return enrich.formatEnrichedForCoder(ctx.feedbackQueue.entries);
+}
+
+/**
+ * After coder runs, verify changes were made. Returns verification result.
+ */
+export function verifyCoderRan(ctx, { baseRef, projectDir }) {
+  if (!ctx.enabled) return { passed: true, filesChanged: 0, reason: "brain disabled" };
+  const result = verifyCoderOutput({ baseRef, projectDir });
+  ctx.verificationTracker.record(result);
+  return result;
+}
+
+/**
+ * Execute direct actions (npm install, gitignore updates, etc.).
+ */
+export async function runDirectActions(ctx, actions, { cwd } = {}) {
+  if (!ctx.enabled || !actions?.length) return [];
+  return executeActions(actions, { cwd });
+}
+
+/**
+ * Clear feedback queue after coder addresses it.
+ */
+export function clearFeedback(ctx) {
+  if (!ctx.enabled) return;
+  queue.clear(ctx.feedbackQueue);
+}
+
+/**
+ * Get a summary of brain activity for the session.
+ */
+export function summarize(ctx) {
+  if (!ctx.enabled) return null;
+  return {
+    feedbackQueueSize: ctx.feedbackQueue.entries.length,
+    queueCategories: queue.countByCategory(ctx.feedbackQueue),
+    consecutiveVerificationFailures: ctx.verificationTracker.consecutiveFailures,
+    compressionSaved: ctx.compressionStats.totalSaved,
+    compressionPerRole: ctx.compressionStats.perRole
+  };
+}