@nemus-cli/nemus 0.3.0 → 0.3.2

package/src/utils/agent-judge.ts

@@ -1,6 +1,52 @@
-import { execFileSync } from 'child_process';
+import { execFileSync, spawn } from 'child_process';
 import { getPrimaryAgent } from './agent-config';
 
+/**
+ * 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":
  * feed it a prompt, get back a parsed JSON object. This reuses whatever agent
@@ -14,15 +60,97 @@ import { getPrimaryAgent } from './agent-config';
 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 child_process runner. */
+  /** Injected for tests. Defaults to the real (blocking) child_process runner. */
   exec?: (cmd: string, args: string[], opts: { timeout: number; maxBuffer: number }) => string;
+  /** Injected for tests. Async runner used by the non-blocking variants. */
+  execAsync?: (cmd: string, args: string[], opts: { timeout: number; maxBuffer: number }) => Promise<string>;
   /** Injected for tests. Defaults to the configured primary agent. */
   agentType?: 'claude' | 'pi' | 'opencode' | 'codex' | 'gemini';
 }
 
-const DEFAULT_TIMEOUT_MS = 180_000; // judging N transcripts is heavier than extraction
+export type JudgeAgentType = NonNullable<JudgeOptions['agentType']>;
+
+export interface AgentAttempt {
+  cmd: string;
+  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). `--model` applies to all; pi also
+ * takes `--thinking` (the speed lever); both are ignored where unsupported.
+ */
+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.
+    const plain = ['-p', prompt];
+    if (model) plain.push('--model', model);
+    return [{ cmd: 'claude', args: preferred }, { cmd: 'claude', args: plain }];
+  }
+  if (agentType === 'opencode') {
+    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'];
+  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 {
+  // A timeout is the common failure (big prompt + slow local model), so make it
+  // actionable instead of surfacing a raw `spawn … ETIMEDOUT`.
+  if (err?.killed || err?.code === 'ETIMEDOUT' || err?.signal === 'SIGTERM' || /ETIMEDOUT/.test(String(err?.message ?? ''))) {
+    return new Error(
+      `agent judge (${agentType}) timed out. Try a smaller --limit, a faster agent, or raise the cap with NEMUS_JUDGE_TIMEOUT_MS.`,
+    );
+  }
+  const detail = (err?.stderr || err?.stdout || err?.message || 'unknown error').toString().trim().slice(0, 500);
+  return new Error(`agent judge failed (${agentType}): ${detail}`);
+}
+
+const DEFAULT_TIMEOUT_MS = 300_000; // judging N transcripts is heavier than extraction; a big prompt + slow model can run minutes
 const DEFAULT_MAX_BUFFER = 32 * 1024 * 1024;
 
 /**
@@ -36,35 +164,43 @@ 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 attempt = (cmd: string, args: string[]) => exec(cmd, args, { timeout, maxBuffer });
-
-  try {
-    if (agentType === 'claude') {
-      const preferred = ['-p', prompt, '--output-format', 'json', '--bare', '--strict-mcp-config', '--disable-slash-commands'];
-      if (opts.schema) preferred.push('--json-schema', opts.schema);
-      try {
-        return attempt('claude', preferred);
-      } catch {
-        // Older claude may reject the newer flags — fall back to the plainest form.
-        return attempt('claude', ['-p', prompt]);
-      }
-    }
-    if (agentType === 'opencode') {
-      return attempt('opencode', ['run', prompt]);
+  const attempts = agentAttempts(agentType, prompt, attemptOptions(agentType, opts));
+  let lastErr: any;
+  for (const a of attempts) {
+    try {
+      return exec(a.cmd, a.args, { timeout, maxBuffer });
+    } catch (err) {
+      lastErr = err; // try the next (fallback) form
     }
-    // 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'];
+  }
+  throw wrapJudgeError(lastErr, agentType);
+}
+
+/**
+ * Non-blocking twin of {@link runAgentRaw}. Uses `execFile` (async) so the
+ * caller's event loop stays free — letting a spinner/progress UI animate while
+ * the judge (which can take minutes) runs. Prefer this in interactive commands.
+ */
+export async function runAgentRawAsync(prompt: string, opts: JudgeOptions = {}): Promise<string> {
+  const agentType = opts.agentType ?? getPrimaryAgent().type;
+  const timeout = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const maxBuffer = opts.maxBuffer ?? DEFAULT_MAX_BUFFER;
+  const exec = opts.execAsync ?? ((cmd, args, o) => spawnCollect(cmd, args, o));
+
+  const attempts = agentAttempts(agentType, prompt, attemptOptions(agentType, opts));
+  let lastErr: any;
+  for (const a of attempts) {
     try {
-      return attempt('pi', [...piLean, '-p', prompt]);
-    } catch {
-      return attempt('pi', ['-p', prompt]);
+      return await exec(a.cmd, a.args, { timeout, maxBuffer });
+    } catch (err) {
+      lastErr = err; // try the next (fallback) form
     }
-  } catch (err: any) {
-    const detail = (err?.stderr || err?.stdout || err?.message || 'unknown error').toString().trim().slice(0, 500);
-    throw new Error(`agent judge failed (${agentType}): ${detail}`);
   }
+  throw wrapJudgeError(lastErr, agentType);
 }
 
 /**
@@ -77,6 +213,12 @@ export function runAgentJson(prompt: string, opts: JudgeOptions = {}): unknown {
   return parseAgentJson(raw);
 }
 
+/** Non-blocking twin of {@link runAgentJson}. */
+export async function runAgentJsonAsync(prompt: string, opts: JudgeOptions = {}): Promise<unknown> {
+  const raw = await runAgentRawAsync(prompt, opts);
+  return parseAgentJson(raw);
+}
+
 /** Extract a JSON object from an agent's raw stdout. Exported for tests. */
 export function parseAgentJson(raw: string): unknown {
   let text = raw.trim();

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');
+}