@nemus-cli/nemus 0.3.1 → 0.3.2

package/src/commands/reflect.ts

@@ -4,13 +4,13 @@ import { outputJson, outputJsonError } from '../utils/output';
 import { colorize } from '../utils/colors';
 import {
   gatherReflectionCorpus,
-  buildJudgePrompt,
   parseReflectionReport,
   REFLECT_SCHEMA,
   ReflectionReport,
   ReflectProgress,
   Recommendation,
 } from '../utils/reflect';
+import { analyzeCorpus, buildAnalysisPrompt } from '../utils/reflect-analyze';
 import { runAgentJsonAsync } from '../utils/agent-judge';
 
 export function registerReflectCommand(parent: Command) {
@@ -19,6 +19,8 @@ export function registerReflectCommand(parent: Command) {
     .alias('retro')
     .description('Analyze your recent workspace sessions and suggest skill/prompt/context improvements (LLM-as-a-judge)')
     .option('-n, --limit <n>', 'How many recent workspaces to analyze', '10')
+    .option('--model <model>', 'Judge model override (agent-native pattern/id)')
+    .option('--thinking <level>', 'Judge thinking level for pi: off|minimal|low|medium|high|xhigh|max')
     .option('--json', 'Output the report as JSON')
     .option('--dry-run', 'Print the assembled corpus + judge prompt without calling the agent')
     .action(async (opts) => {
@@ -26,7 +28,7 @@ export function registerReflectCommand(parent: Command) {
     });
 }
 
-async function handleReflect(opts: { limit?: string; json?: boolean; dryRun?: boolean }) {
+async function handleReflect(opts: { limit?: string; model?: string; thinking?: string; json?: boolean; dryRun?: boolean }) {
   const limit = Math.max(1, Number.parseInt(opts.limit ?? '10', 10) || 10);
   try {
     const showProgress = !opts.json && !opts.dryRun;
@@ -36,11 +38,15 @@ async function handleReflect(opts: { limit?: string; json?: boolean; dryRun?: bo
 
     const corpus = await gatherReflectionCorpus(limit, showProgress ? printProgress : undefined);
     const withSessions = corpus.workspaces.filter((w) => w.session).length;
-    const prompt = buildJudgePrompt(corpus);
+    // A script does the heavy analysis (clustering failures, counting tools,
+    // spotting correction loops); the LLM only ever sees these compact facts,
+    // so the judge call stays small + fast regardless of workspace count.
+    const analysis = analyzeCorpus(corpus);
+    const prompt = buildAnalysisPrompt(analysis);
 
     if (opts.dryRun) {
-      // No LLM call — surface exactly what the judge would see.
-      if (opts.json) outputJson({ corpus, prompt });
+      // No LLM call — surface the computed facts + exactly what the judge sees.
+      if (opts.json) outputJson({ analysis, prompt });
       else {
         process.stdout.write(prompt + '\n');
       }
@@ -58,12 +64,14 @@ async function handleReflect(opts: { limit?: string; json?: boolean; dryRun?: bo
     // (non-blocking) so a live spinner shows it's alive, not hung. Timeout is
     // overridable for slow local models.
     const timeoutMs = Number.parseInt(process.env.NEMUS_JUDGE_TIMEOUT_MS ?? '', 10) || undefined;
+    const model = opts.model ?? process.env.NEMUS_JUDGE_MODEL ?? undefined;
+    const thinking = opts.thinking ?? process.env.NEMUS_JUDGE_THINKING ?? undefined;
     const stopSpinner = opts.json
       ? () => {}
       : startSpinner(`Judging ${withSessions} session(s) with your configured agent (this can take a minute)…`);
     let parsed: unknown;
     try {
-      parsed = await runAgentJsonAsync(prompt, { schema: REFLECT_SCHEMA, timeoutMs });
+      parsed = await runAgentJsonAsync(prompt, { schema: REFLECT_SCHEMA, timeoutMs, model, thinking });
     } finally {
       stopSpinner();
     }

package/src/utils/agent-judge.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { parseAgentJson, runAgentRaw, runAgentRawAsync, agentAttempts } from './agent-judge';
+import { parseAgentJson, runAgentRaw, runAgentRawAsync, agentAttempts, spawnCollect } from './agent-judge';
 
 describe('parseAgentJson', () => {
   it('unwraps the common agent envelopes and shapes', () => {
@@ -16,9 +16,24 @@ describe('parseAgentJson', () => {
   });
 });
 
+describe('spawnCollect (stdin-hang regression)', () => {
+  it('gives the child stdin EOF so a stdin-reading process does NOT hang', async () => {
+    // `cat` with no args reads stdin to EOF. If stdin were an open pipe (the old
+    // execFile default) this would block until the timeout and reject; with
+    // stdin ignored it gets immediate EOF and exits 0 fast. 2s timeout << any hang.
+    const out = await spawnCollect('cat', [], { timeout: 2000, maxBuffer: 1 << 20 });
+    expect(out).toBe('');
+  });
+
+  it('captures stdout and rejects on non-zero exit', async () => {
+    await expect(spawnCollect('node', ['-e', 'process.stdout.write("hi")'], { timeout: 5000, maxBuffer: 1 << 20 })).resolves.toBe('hi');
+    await expect(spawnCollect('node', ['-e', 'process.exit(3)'], { timeout: 5000, maxBuffer: 1 << 20 })).rejects.toThrow(/exit 3/);
+  });
+});
+
 describe('agentAttempts', () => {
   it('claude: preferred (schema + lean flags) then a plain fallback', () => {
-    const a = agentAttempts('claude', 'P', '{"type":"object"}');
+    const a = agentAttempts('claude', 'P', { schema: '{"type":"object"}' });
     expect(a[0]).toEqual({ cmd: 'claude', args: expect.arrayContaining(['-p', 'P', '--output-format', 'json', '--json-schema', '{"type":"object"}']) });
     expect(a[1]).toEqual({ cmd: 'claude', args: ['-p', 'P'] });
   });
@@ -28,6 +43,26 @@ describe('agentAttempts', () => {
     expect(pi[1]).toEqual({ cmd: 'pi', args: ['-p', 'P'] });
     expect(agentAttempts('opencode', 'P')).toEqual([{ cmd: 'opencode', args: ['run', 'P'] }]);
   });
+  it('threads --model (all) + --thinking (pi only); fallback keeps model, drops --thinking', () => {
+    const pi = agentAttempts('pi', 'P', { model: 'haiku', thinking: 'low' });
+    expect(pi[0].args).toEqual(expect.arrayContaining(['--model', 'haiku', '--thinking', 'low', '-p', 'P']));
+    // Safety net: model stays (stable flag), --thinking is dropped so an old pi
+    // that rejects --thinking still has a working fallback.
+    expect(pi[1].args).toEqual(['--model', 'haiku', '-p', 'P']);
+    expect(pi[1].args).not.toContain('--thinking');
+    const cl = agentAttempts('claude', 'P', { model: 'sonnet' });
+    expect(cl[0].args).toEqual(expect.arrayContaining(['--model', 'sonnet']));
+    expect(cl[0].args).not.toContain('--thinking'); // thinking is pi-only
+    expect(agentAttempts('opencode', 'P', { model: 'gpt' })[0].args).toEqual(['run', 'P', '--model', 'gpt']);
+  });
+});
+
+describe('runAgentRaw thinking default', () => {
+  it('applies the low-thinking default for pi', () => {
+    let seen: string[] = [];
+    runAgentRaw('P', { agentType: 'pi', exec: (cmd, args) => ((seen = [cmd, ...args]), 'ok') });
+    expect(seen).toEqual(expect.arrayContaining(['--thinking', 'low']));
+  });
 });
 
 describe('runAgentRawAsync', () => {

package/src/utils/agent-judge.ts

@@ -1,8 +1,51 @@
-import { execFile, execFileSync } from 'child_process';
-import { promisify } from 'util';
+import { execFileSync, spawn } from 'child_process';
 import { getPrimaryAgent } from './agent-config';
 
-const execFileAsync = promisify(execFile);
+/**
+ * Run a child to completion, capturing stdout, with stdin set to /dev/null.
+ *
+ * The stdin part is load-bearing: agents like `pi` block waiting on stdin if
+ * it's an open pipe (the default for execFile), which made the judge hang until
+ * the timeout regardless of prompt size or model speed. `stdio: ['ignore', …]`
+ * gives the child an immediate EOF, exactly like a non-interactive shell.
+ */
+export function spawnCollect(
+  cmd: string,
+  args: string[],
+  opts: { timeout: number; maxBuffer: number },
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: opts.timeout,
+      killSignal: 'SIGKILL',
+    });
+    // Decode as UTF-8 at the stream boundary so a multi-byte char split across
+    // two chunks isn't corrupted (which would break JSON.parse downstream).
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    let stdout = '';
+    let stderr = '';
+    let overflow = false;
+    child.stdout.on('data', (d) => {
+      stdout += d;
+      if (stdout.length > opts.maxBuffer) {
+        overflow = true;
+        child.kill('SIGKILL');
+      }
+    });
+    child.stderr.on('data', (d) => {
+      stderr += d;
+    });
+    child.on('error', (e) => reject(e));
+    child.on('close', (code, signal) => {
+      if (overflow) return reject(Object.assign(new Error('maxBuffer exceeded'), { stdout, stderr }));
+      if (signal) return reject(Object.assign(new Error(`killed by ${signal}`), { killed: true, signal, stdout, stderr }));
+      if (code !== 0) return reject(Object.assign(new Error(`exit ${code}`), { code, stdout, stderr }));
+      resolve(stdout);
+    });
+  });
+}
 
 /**
  * Run the user's configured coding agent headlessly as an "LLM-as-a-judge":
@@ -17,6 +60,10 @@ const execFileAsync = promisify(execFile);
 export interface JudgeOptions {
   /** JSON schema string passed to `claude --json-schema` (ignored by others). */
   schema?: string;
+  /** Model override (`--model`), agent-native pattern/id. */
+  model?: string;
+  /** Thinking level (`--thinking`, pi only): off|minimal|low|medium|high|xhigh|max. */
+  thinking?: string;
   timeoutMs?: number;
   maxBuffer?: number;
   /** Injected for tests. Defaults to the real (blocking) child_process runner. */
@@ -34,24 +81,61 @@ export interface AgentAttempt {
   args: string[];
 }
 
+export interface AttemptOptions {
+  schema?: string;
+  model?: string;
+  thinking?: string;
+}
+
+/**
+ * Default thinking level for the judge. The judge is a mechanical transform
+ * (facts → recommendations), not deep reasoning, so a heavy default like Opus
+ * @ medium thinking just makes it slow. `low` keeps pi fast; override per-run.
+ */
+export const DEFAULT_JUDGE_THINKING = 'low';
+
 /**
  * The ordered invocation attempts for an agent (preferred → fallback), as pure
  * data so both the sync and async runners share ONE flag ladder (and it's
- * unit-testable without spawning anything).
+ * unit-testable without spawning anything). `--model` applies to all; pi also
+ * takes `--thinking` (the speed lever); both are ignored where unsupported.
  */
-export function agentAttempts(agentType: JudgeAgentType, prompt: string, schema?: string): AgentAttempt[] {
+export function agentAttempts(agentType: JudgeAgentType, prompt: string, opts: AttemptOptions = {}): AgentAttempt[] {
+  const { schema, model, thinking } = opts;
   if (agentType === 'claude') {
     const preferred = ['-p', prompt, '--output-format', 'json', '--bare', '--strict-mcp-config', '--disable-slash-commands'];
+    if (model) preferred.push('--model', model);
     if (schema) preferred.push('--json-schema', schema);
     // Older claude may reject the newer flags — fall back to the plainest form.
-    return [{ cmd: 'claude', args: preferred }, { cmd: 'claude', args: ['-p', prompt] }];
+    const plain = ['-p', prompt];
+    if (model) plain.push('--model', model);
+    return [{ cmd: 'claude', args: preferred }, { cmd: 'claude', args: plain }];
   }
   if (agentType === 'opencode') {
-    return [{ cmd: 'opencode', args: ['run', prompt] }];
+    const args = ['run', prompt];
+    if (model) args.push('--model', model);
+    return [{ cmd: 'opencode', args }];
   }
   // pi (and any other): run as lean as possible so a bloated env can't hang it.
   const piLean = ['--no-extensions', '--no-skills', '--no-prompt-templates', '--no-context-files', '--no-tools', '--no-session'];
-  return [{ cmd: 'pi', args: [...piLean, '-p', prompt] }, { cmd: 'pi', args: ['-p', prompt] }];
+  const modelArgs = model ? ['--model', model] : [];
+  const tune = thinking ? [...modelArgs, '--thinking', thinking] : modelArgs;
+  // Fallback keeps the stable --model but DROPS --thinking: --thinking is the
+  // newest flag and the most likely reason an older pi rejects the first
+  // attempt, so the safety net must not carry it (else both attempts fail).
+  return [
+    { cmd: 'pi', args: [...piLean, ...tune, '-p', prompt] },
+    { cmd: 'pi', args: [...modelArgs, '-p', prompt] },
+  ];
+}
+
+/** Resolve the attempt options for a run, applying the pi thinking default. */
+function attemptOptions(agentType: JudgeAgentType, opts: JudgeOptions): AttemptOptions {
+  return {
+    schema: opts.schema,
+    model: opts.model,
+    thinking: opts.thinking ?? (agentType === 'pi' ? DEFAULT_JUDGE_THINKING : undefined),
+  };
 }
 
 function wrapJudgeError(err: any, agentType: string): Error {
@@ -80,9 +164,11 @@ export function runAgentRaw(prompt: string, opts: JudgeOptions = {}): string {
   const maxBuffer = opts.maxBuffer ?? DEFAULT_MAX_BUFFER;
   const exec =
     opts.exec ??
-    ((cmd, args, o) => execFileSync(cmd, args, { encoding: 'utf-8', timeout: o.timeout, maxBuffer: o.maxBuffer }));
+    // `input: ''` closes the child's stdin (EOF) so a stdin-reading agent (pi)
+    // can't hang the synchronous call — the sync twin of spawnCollect's fix.
+    ((cmd, args, o) => execFileSync(cmd, args, { encoding: 'utf-8', input: '', timeout: o.timeout, maxBuffer: o.maxBuffer }));
 
-  const attempts = agentAttempts(agentType, prompt, opts.schema);
+  const attempts = agentAttempts(agentType, prompt, attemptOptions(agentType, opts));
   let lastErr: any;
   for (const a of attempts) {
     try {
@@ -103,12 +189,9 @@ export async function runAgentRawAsync(prompt: string, opts: JudgeOptions = {}):
   const agentType = opts.agentType ?? getPrimaryAgent().type;
   const timeout = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   const maxBuffer = opts.maxBuffer ?? DEFAULT_MAX_BUFFER;
-  const exec =
-    opts.execAsync ??
-    (async (cmd, args, o) =>
-      (await execFileAsync(cmd, args, { encoding: 'utf-8', timeout: o.timeout, maxBuffer: o.maxBuffer })).stdout.toString());
+  const exec = opts.execAsync ?? ((cmd, args, o) => spawnCollect(cmd, args, o));
 
-  const attempts = agentAttempts(agentType, prompt, opts.schema);
+  const attempts = agentAttempts(agentType, prompt, attemptOptions(agentType, opts));
   let lastErr: any;
   for (const a of attempts) {
     try {

package/src/utils/reflect-analyze.test.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect } from 'vitest';
+import { normalizeErrorSignature, analyzeCorpus, buildAnalysisPrompt } from './reflect-analyze';
+import { ReflectionCorpus, isCorrectionPrompt } from './reflect';
+
+describe('normalizeErrorSignature', () => {
+  it('collapses paths, numbers, and hashes so variants cluster', () => {
+    const a = normalizeErrorSignature('fatal: not a git repository (or any parent up to /Users/alice/work/repo)');
+    const b = normalizeErrorSignature('fatal: not a git repository (or any parent up to /home/bob/src/thing)');
+    expect(a).toBe(b);
+    expect(a).toContain('<path>');
+
+    expect(normalizeErrorSignature('exit code 137 after 4200ms')).toBe(
+      normalizeErrorSignature('exit code 2 after 9ms'),
+    );
+    expect(normalizeErrorSignature('object abc1234def not found')).toBe(
+      normalizeErrorSignature('object 0f9e8d7c6b not found'),
+    );
+  });
+
+  it('is bounded and safe on empty input', () => {
+    expect(normalizeErrorSignature('')).toBe('');
+    expect(normalizeErrorSignature('x'.repeat(500)).length).toBeLessThanOrEqual(100);
+  });
+});
+
+describe('isCorrectionPrompt', () => {
+  it('flags corrections, not normal instructions', () => {
+    expect(isCorrectionPrompt('no, that is wrong — revert it')).toBe(true);
+    expect(isCorrectionPrompt('actually use the other repo instead')).toBe(true);
+    expect(isCorrectionPrompt('you forgot to run the tests')).toBe(true);
+    expect(isCorrectionPrompt('add a health check to the api')).toBe(false);
+    expect(isCorrectionPrompt('create a workspace for payments')).toBe(false);
+  });
+});
+
+const corpus: ReflectionCorpus = {
+  generatedAt: 'now',
+  availableSkills: ['redash'],
+  workspaces: [
+    {
+      name: 'pay-app',
+      repoCount: 1,
+      repos: ['api'],
+      contextFiles: ['AGENTS.md'],
+      contextQuality: 'substantive',
+      session: {
+        sessionId: 's1',
+        agentType: 'pi',
+        turns: 40,
+        userPrompts: ['fix the sync bug', 'no that is wrong, revert'],
+        reSteerSamples: ['no that is wrong, revert'],
+        errors: [
+          'fatal: not a git repository (at /Users/a/pay-app/api)',
+          'fatal: not a git repository (at /Users/a/pay-app/web)',
+          'gh: Not Found (HTTP 404)',
+        ],
+        tools: ['bash', 'edit'],
+      },
+    },
+    {
+      name: 'ledger',
+      repoCount: 0,
+      repos: [],
+      contextFiles: [], // missing context
+      contextQuality: 'missing',
+      session: {
+        sessionId: 's2',
+        agentType: 'pi',
+        turns: 12,
+        userPrompts: ['add tests'],
+        reSteerSamples: [],
+        errors: ['fatal: not a git repository (at /home/b/ledger)'],
+        tools: ['bash'],
+      },
+    },
+    { name: 'idle-ws', repoCount: 0, repos: [], contextFiles: ['CLAUDE.md'], contextQuality: 'boilerplate', session: null },
+  ],
+};
+
+describe('analyzeCorpus', () => {
+  const a = analyzeCorpus(corpus);
+
+  it('aggregates totals and correction signals', () => {
+    expect(a.totalWorkspaces).toBe(3);
+    expect(a.sessionsAnalyzed).toBe(2); // idle-ws has no session
+    expect(a.totalTurns).toBe(52);
+    expect(a.correctionSignals).toBe(1); // "no that is wrong, revert"
+  });
+
+  it('clusters the recurring failure across workspaces, most frequent first', () => {
+    const top = a.topErrors[0];
+    expect(top.signature).toContain('not a git repository');
+    expect(top.count).toBe(3); // 2 in pay-app + 1 in ledger
+    expect(top.workspaces.sort()).toEqual(['ledger', 'pay-app']);
+    expect(top.example).toContain('fatal: not a git repository');
+  });
+
+  it('reports tools, context quality, re-steers, and per-workspace facts', () => {
+    expect(a.topTools[0]).toEqual({ tool: 'bash', sessions: 2 });
+    expect(a.workspacesMissingContext).toEqual(['ledger']);
+    expect(a.workspacesBoilerplateContext).toEqual(['idle-ws']);
+    expect(a.reSteerSamples).toEqual(['no that is wrong, revert']);
+    const pay = a.workspaces.find((w) => w.name === 'pay-app')!;
+    expect(pay).toMatchObject({ turns: 40, failures: 3, contextQuality: 'substantive' });
+    expect(pay.topFailure).toContain('not a git repository');
+    expect(a.workspaces.find((w) => w.name === 'idle-ws')).toMatchObject({ turns: 0, failures: 0, contextQuality: 'boilerplate' });
+  });
+});
+
+describe('buildAnalysisPrompt', () => {
+  it('is compact and fact-based (no raw transcripts)', () => {
+    const p = buildAnalysisPrompt(analyzeCorpus(corpus));
+    expect(p).toContain('A script has already analyzed');
+    expect(p).toContain('Sessions analyzed: 2 across 3 workspaces (52 total turns).');
+    expect(p).toContain('Top recurring failures');
+    expect(p).toMatch(/\[3\u00d7 in 2 ws\]/); // the clustered failure
+    expect(p).toContain('NO context file (AGENTS.md/CLAUDE.md): ledger');
+    expect(p).toContain('boilerplate/template: idle-ws');
+    expect(p).toContain('Verbatim user corrections');
+    expect(p).toContain('no that is wrong, revert');
+    expect(p).toContain('bash(2)');
+    expect(p).toMatch(/ONLY a JSON object/);
+    // Compact: even this corpus stays well under a few KB.
+    expect(p.length).toBeLessThan(3000);
+  });
+});

package/src/utils/reflect-analyze.ts

@@ -0,0 +1,246 @@
+import { ReflectionCorpus, ContextQuality, isCorrectionPrompt } from './reflect';
+
+/**
+ * Deterministic analysis layer for `reflect`.
+ *
+ * The LLM used to read raw transcripts (every prompt + every error) for every
+ * workspace, which made the judge prompt large and slow (timeouts on local
+ * models). Instead, a *script* does the heavy lifting here — clustering repeated
+ * failures, counting tools, spotting correction/retry loops — and the LLM only
+ * ever sees a small, pre-computed set of FACTS. That keeps the judge call fast
+ * and bounded no matter how many workspaces are analyzed, and grounds every
+ * recommendation in real counts rather than a wall of text.
+ *
+ * Everything here is pure (corpus in → report out) so it's exhaustively
+ * unit-tested without spawning an agent.
+ */
+
+// ------------------------------------------------------------------ types
+
+export interface ErrorCluster {
+  /** Normalized signature (paths/numbers/hashes stripped) used to group. */
+  signature: string;
+  /** Total occurrences across all analyzed sessions. */
+  count: number;
+  /** Distinct workspaces the signature appeared in (recurrence = strong signal). */
+  workspaces: string[];
+  /** One representative raw example (bounded). */
+  example: string;
+}
+
+export interface ToolStat {
+  tool: string;
+  /** Number of sessions that used the tool (not raw invocation count — the
+   *  digest only records distinct tools per session). */
+  sessions: number;
+}
+
+export interface WorkspaceFact {
+  name: string;
+  turns: number;
+  failures: number;
+  /** Whether the primary context file is missing / boilerplate / substantive. */
+  contextQuality: ContextQuality;
+  /** The workspace's single most frequent failure signature, if any. */
+  topFailure?: string;
+}
+
+export interface AnalysisReport {
+  totalWorkspaces: number;
+  sessionsAnalyzed: number;
+  totalTurns: number;
+  /** Recurring failures, most frequent first. */
+  topErrors: ErrorCluster[];
+  /** Most-used tools, most sessions first. */
+  topTools: ToolStat[];
+  /** How many user prompts looked like corrections/retries (a friction signal). */
+  correctionSignals: number;
+  /** Verbatim user re-steer messages across sessions (the sharpest coaching
+   *  signal), most-recent-workspace first, bounded. */
+  reSteerSamples: string[];
+  /** Workspaces with NO context file at all. */
+  workspacesMissingContext: string[];
+  /** Workspaces whose context file exists but is just boilerplate/template. */
+  workspacesBoilerplateContext: string[];
+  /** Skills already installed (so the judge suggests genuine gaps). */
+  availableSkills: string[];
+  /** One compact line of facts per workspace, for grounding. */
+  workspaces: WorkspaceFact[];
+}
+
+// --------------------------------------------------------------- normalizing
+
+/**
+ * Reduce a raw error string to a stable signature so near-identical failures
+ * cluster together: lowercase, drop quotes, replace filesystem paths, hashes,
+ * hex ids and bare numbers with placeholders, collapse whitespace, and cap the
+ * length. `"fatal: not a git repository (or any of the parent up to /Users/x)"`
+ * and the same from another path collapse to one signature.
+ */
+export function normalizeErrorSignature(raw: string): string {
+  let s = (raw ?? '').toLowerCase();
+  s = s.replace(/[`'"]/g, ' ');
+  // Windows paths first (contain ':' and '\'), then unix paths.
+  s = s.replace(/[a-z]:\\[^\s]+/g, '<path>');
+  s = s.replace(/\/[^\s:)'"]+/g, '<path>');
+  // Long hex / uuids / sha-like tokens before bare numbers.
+  s = s.replace(/\b[0-9a-f]{7,}\b/g, '<hash>');
+  // No trailing \b, so a number glued to a unit ('4200ms', '9ms') still clusters.
+  s = s.replace(/\b\d[\d.,:]*/g, '<n>');
+  s = s.replace(/\s+/g, ' ').trim();
+  return s.slice(0, 100);
+}
+
+// ------------------------------------------------------------------ analyze
+
+export interface AnalyzeOptions {
+  /** Max error clusters to surface (default 8). */
+  topErrors?: number;
+  /** Max tools to surface (default 10). */
+  topTools?: number;
+  /** Max chars of a raw error kept as the example (default 160). */
+  exampleChars?: number;
+  /** Max verbatim re-steer samples to surface to the judge (default 8). */
+  maxReSteer?: number;
+}
+
+/**
+ * Turn a distilled corpus into aggregated facts. This is the "script processes
+ * the data" step — the LLM never sees the raw corpus, only the returned report.
+ */
+export function analyzeCorpus(corpus: ReflectionCorpus, opts: AnalyzeOptions = {}): AnalysisReport {
+  const topErrorsK = opts.topErrors ?? 8;
+  const topToolsK = opts.topTools ?? 10;
+  const exampleChars = opts.exampleChars ?? 160;
+  const maxReSteer = opts.maxReSteer ?? 8;
+
+  const errorMap = new Map<string, { count: number; ws: Set<string>; example: string }>();
+  const toolMap = new Map<string, number>();
+  const workspacesMissingContext: string[] = [];
+  const workspacesBoilerplateContext: string[] = [];
+  const reSteerSamples: string[] = [];
+  const workspaces: WorkspaceFact[] = [];
+  let sessionsAnalyzed = 0;
+  let totalTurns = 0;
+  let correctionSignals = 0;
+
+  for (const ws of corpus.workspaces) {
+    if (ws.contextQuality === 'missing') workspacesMissingContext.push(ws.name);
+    else if (ws.contextQuality === 'boilerplate') workspacesBoilerplateContext.push(ws.name);
+
+    const s = ws.session;
+    if (!s) {
+      workspaces.push({ name: ws.name, turns: 0, failures: 0, contextQuality: ws.contextQuality });
+      continue;
+    }
+
+    sessionsAnalyzed++;
+    totalTurns += s.turns;
+    for (const t of s.tools) toolMap.set(t, (toolMap.get(t) ?? 0) + 1);
+    correctionSignals += s.userPrompts.filter(isCorrectionPrompt).length;
+    for (const q of s.reSteerSamples) {
+      if (reSteerSamples.length < maxReSteer) reSteerSamples.push(q);
+    }
+
+    // Per-workspace signature tally (drives the global map + this ws's topFailure).
+    const localSig = new Map<string, number>();
+    for (const e of s.errors) {
+      const sig = normalizeErrorSignature(e);
+      if (!sig) continue;
+      localSig.set(sig, (localSig.get(sig) ?? 0) + 1);
+      let entry = errorMap.get(sig);
+      if (!entry) {
+        entry = { count: 0, ws: new Set(), example: e.slice(0, exampleChars) };
+        errorMap.set(sig, entry);
+      }
+      entry.count++;
+      entry.ws.add(ws.name);
+    }
+    const topFailure = [...localSig.entries()].sort((a, b) => b[1] - a[1])[0]?.[0];
+
+    workspaces.push({ name: ws.name, turns: s.turns, failures: s.errors.length, contextQuality: ws.contextQuality, topFailure });
+  }
+
+  const topErrors: ErrorCluster[] = [...errorMap.entries()]
+    .map(([signature, v]) => ({ signature, count: v.count, workspaces: [...v.ws], example: v.example }))
+    // Most frequent first; break ties by cross-workspace spread (recurrence).
+    .sort((a, b) => b.count - a.count || b.workspaces.length - a.workspaces.length)
+    .slice(0, topErrorsK);
+
+  const topTools: ToolStat[] = [...toolMap.entries()]
+    .map(([tool, sessions]) => ({ tool, sessions }))
+    .sort((a, b) => b.sessions - a.sessions || a.tool.localeCompare(b.tool))
+    .slice(0, topToolsK);
+
+  return {
+    totalWorkspaces: corpus.workspaces.length,
+    sessionsAnalyzed,
+    totalTurns,
+    topErrors,
+    topTools,
+    correctionSignals,
+    reSteerSamples,
+    workspacesMissingContext,
+    workspacesBoilerplateContext,
+    availableSkills: corpus.availableSkills,
+    workspaces,
+  };
+}
+
+// --------------------------------------------------------------- judge prompt
+
+/**
+ * Build the judge prompt from the pre-computed facts. Compact by construction
+ * (a handful of clusters + counts), so the LLM call stays small and fast no
+ * matter how many workspaces were analyzed. Output contract is unchanged
+ * (REFLECT_SCHEMA), so parsing/rendering are shared with the old path.
+ */
+export function buildAnalysisPrompt(a: AnalysisReport): string {
+  const L: string[] = [];
+  L.push(
+    'You are an expert reviewer ("LLM as a judge"). A script has already analyzed an engineer\'s',
+    'recent AI coding-agent sessions and distilled them into the FACTS below. Do not ask for the',
+    'raw transcripts — reason only from these facts.',
+    '',
+    'Goal: recommend concrete improvements to their SETUP so the agent works better next time —',
+    'which skills to add and WHERE, which AGENTS.md/context rules are missing, missing connectivity/',
+    'smoke tests, and prompt/workflow habits. Ground every recommendation in a fact below',
+    '(a recurring failure, a correction loop, a missing context file). Prefer a few high-signal',
+    'items over many generic ones. Include a concrete `example` snippet for skills/context rules.',
+    '',
+    `Sessions analyzed: ${a.sessionsAnalyzed} across ${a.totalWorkspaces} workspaces (${a.totalTurns} total turns).`,
+    `Installed skills (don't re-suggest; find genuine gaps): ${a.availableSkills.join(', ') || '(none)'}`,
+    `User correction/retry signals: ${a.correctionSignals} prompt(s) looked like corrections.`,
+    `Workspaces with NO context file (AGENTS.md/CLAUDE.md): ${a.workspacesMissingContext.join(', ') || '(none)'}`,
+    `Workspaces whose context file is just boilerplate/template: ${a.workspacesBoilerplateContext.join(', ') || '(none)'}`,
+  );
+
+  if (a.reSteerSamples.length) {
+    L.push('', 'Verbatim user corrections/re-steers (the sharpest signal — quote/act on these):');
+    for (const q of a.reSteerSamples) L.push(`  - “${q.replace(/\n/g, ' ')}”`);
+  }
+
+  L.push('', 'Top recurring failures (count × workspaces — example):');
+  if (a.topErrors.length === 0) L.push('  (none captured)');
+  for (const e of a.topErrors) {
+    L.push(`  - [${e.count}× in ${e.workspaces.length} ws] ${e.signature}`);
+    L.push(`      e.g. ${e.example.replace(/\n/g, ' ')}`);
+  }
+
+  L.push('', `Most-used tools: ${a.topTools.map((t) => `${t.tool}(${t.sessions})`).join(', ') || '(none)'}`);
+
+  L.push('', 'Per-workspace:');
+  for (const w of a.workspaces) {
+    const top = w.topFailure ? ` · top failure: ${w.topFailure}` : '';
+    L.push(`  - ${w.name}: ${w.turns} turns, ${w.failures} failures, context:${w.contextQuality}${top}`);
+  }
+
+  L.push(
+    '',
+    'Respond with ONLY a JSON object of this shape (no prose, no markdown fence):',
+    '{"summary": string, "recommendations": [{"kind":"skill|context|test|prompt|connectivity|workflow|other",',
+    '"title": string, "detail": string, "target": string(optional workspace/repo/path),',
+    '"priority":"high|medium|low", "example": string(optional snippet)}]}',
+  );
+  return L.join('\n');
+}