@nemus-cli/nemus 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -7,6 +7,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-08-30
+
+### Fixed
+
+- **`reflect` no longer hangs/times out — the real root cause was open stdin.**
+  The judge was spawned with its **stdin left as an open pipe** (`execFile`'s
+  default), so a stdin-reading agent like `pi` blocked forever waiting on input
+  and the run died at the timeout — regardless of prompt size or model. The
+  child now gets stdin `ignore` (async) / `input: ''` (sync) → immediate EOF,
+  and a real run drops from *timeout* to **~40s**. Regression-tested with a
+  stdin-reading child that would otherwise hang.
+
+### Changed
+
+- **`reflect` now does the analysis in code and hands the LLM only compact
+  facts.** A new deterministic layer (`reflect-analyze.ts`) clusters recurring
+  failures into normalized **signatures** (paths/numbers/hashes stripped) with
+  counts + which workspaces they span, tallies tool usage, flags
+  correction/retry loops, and lists workspaces missing a context file. The judge
+  prompt is built from those aggregates, so it stays **~5KB regardless of how
+  many workspaces** are analyzed (was ~25KB and growing), the call is faster and
+  cheaper, less raw prompt text leaves your machine, and every recommendation is
+  grounded in a real count. Output shape (`--json`, the report) is unchanged;
+  `--dry-run` now shows the computed facts.
+- **Faster judge + richer signal.** The judge now runs pi at **`--thinking low`**
+  by default (it's a mechanical facts→recommendations transform, not deep
+  reasoning) — overridable with `--thinking`/`NEMUS_JUDGE_THINKING` and
+  `--model`/`NEMUS_JUDGE_MODEL` (threaded through for claude/opencode where
+  supported; thinking is pi-only). The digest now includes **verbatim “re-steer”
+  quotes** (the user corrections/redirects that are the sharpest coaching signal)
+  and classifies each workspace's context file as **missing / boilerplate /
+  substantive** (distinguishing “has an AGENTS.md” from “has a *useful* one”), on
+  top of the error-signature clusters.
+
+## [0.3.1] - 2026-08-30
+
+### Fixed
+
+- **`reflect` shows live progress instead of looking hung.** The gather phase
+  prints a **per-workspace line** as each session is read (`✓ 1/3 my-workspace
+  635 turns · 12 prompts · 13 failures`); the judge runs **async** behind a live
+  spinner with elapsed seconds; the timeout is raised to 300s (overridable via
+  `NEMUS_JUDGE_TIMEOUT_MS`) with an **actionable** message on timeout.
+
 ## [0.3.0] - 2026-08-27
 
 ### Added

package/dist/cli/ai-prompt.js

@@ -161,6 +161,10 @@ const EXTRACTION_TIMEOUT_MS = 120000;
 function runExtraction(cmd, fullArgs, fallbackArgs) {
     const exec = (args) => (0, child_process_1.execFileSync)(cmd, args, {
         encoding: 'utf-8',
+        // `input: ''` closes the child's stdin (EOF) so a stdin-reading agent (pi)
+        // can't block this synchronous call forever in a headless/piped context
+        // — the same hang the async judge hit, guarded here for `nemus -- "…"`.
+        input: '',
         timeout: EXTRACTION_TIMEOUT_MS,
         maxBuffer: 10 * 1024 * 1024,
     });

package/dist/commands/reflect.js

@@ -5,6 +5,7 @@ const logger_1 = require("../utils/logger");
 const output_1 = require("../utils/output");
 const colors_1 = require("../utils/colors");
 const reflect_1 = require("../utils/reflect");
+const reflect_analyze_1 = require("../utils/reflect-analyze");
 const agent_judge_1 = require("../utils/agent-judge");
 function registerReflectCommand(parent) {
     parent
@@ -12,6 +13,8 @@ function registerReflectCommand(parent) {
         .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) => {
@@ -21,17 +24,21 @@ function registerReflectCommand(parent) {
 async function handleReflect(opts) {
     const limit = Math.max(1, Number.parseInt(opts.limit ?? '10', 10) || 10);
     try {
-        if (!opts.json && !opts.dryRun) {
+        const showProgress = !opts.json && !opts.dryRun;
+        if (showProgress) {
             (0, logger_1.logStep)(`Analyzing your ${(0, colors_1.colorize)(String(limit), 'cyan')} most recent workspaces…`);
-            (0, logger_1.logInfo)('Reading sessions and distilling prompts + failures…');
         }
-        const corpus = await (0, reflect_1.gatherReflectionCorpus)(limit);
+        const corpus = await (0, reflect_1.gatherReflectionCorpus)(limit, showProgress ? printProgress : undefined);
         const withSessions = corpus.workspaces.filter((w) => w.session).length;
-        const prompt = (0, reflect_1.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 = (0, reflect_analyze_1.analyzeCorpus)(corpus);
+        const prompt = (0, reflect_analyze_1.buildAnalysisPrompt)(analysis);
         if (opts.dryRun) {
-            // No LLM call — surface exactly what the judge would see.
+            // No LLM call — surface the computed facts + exactly what the judge sees.
             if (opts.json)
-                (0, output_1.outputJson)({ corpus, prompt });
+                (0, output_1.outputJson)({ analysis, prompt });
             else {
                 process.stdout.write(prompt + '\n');
             }
@@ -45,9 +52,22 @@ async function handleReflect(opts) {
                 (0, logger_1.logError)(msg);
             process.exit(1);
         }
-        if (!opts.json)
-            (0, logger_1.logInfo)(`Judging ${withSessions} session(s) with your configured agent…`);
-        const parsed = (0, agent_judge_1.runAgentJson)(prompt, { schema: reflect_1.REFLECT_SCHEMA });
+        // The judge shells the user's own agent and can take minutes; run it async
+        // (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;
+        try {
+            parsed = await (0, agent_judge_1.runAgentJsonAsync)(prompt, { schema: reflect_1.REFLECT_SCHEMA, timeoutMs, model, thinking });
+        }
+        finally {
+            stopSpinner();
+        }
         const report = (0, reflect_1.parseReflectionReport)(parsed);
         if (opts.json) {
             (0, output_1.outputJson)({ analyzed: withSessions, workspaces: corpus.workspaces.length, ...report });
@@ -75,6 +95,44 @@ const KIND_LABEL = {
     workflow: 'Workflow',
     other: 'Other',
 };
+/**
+ * A minimal stderr spinner with elapsed seconds. Returns a stop() that clears
+ * the line. No-op (single log line) when stderr isn't a TTY (piped/CI), so it
+ * never pollutes captured output. Kept local + tiny — no new dependency.
+ */
+function startSpinner(text) {
+    if (!process.stderr.isTTY) {
+        (0, logger_1.logInfo)(text);
+        return () => { };
+    }
+    const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+    const start = Date.now();
+    let i = 0;
+    const render = () => {
+        const secs = Math.floor((Date.now() - start) / 1000);
+        process.stderr.write(`\r${(0, colors_1.colorize)(frames[(i = (i + 1) % frames.length)], 'cyan')} ${text} ${(0, colors_1.colorize)(`(${secs}s)`, 'dim')}`);
+    };
+    render();
+    const timer = setInterval(render, 100);
+    timer.unref?.(); // never keep the process alive on our account
+    return () => {
+        clearInterval(timer);
+        process.stderr.write('\r' + ' '.repeat(text.length + 24) + '\r');
+    };
+}
+/** Live per-workspace line during the gather phase (to stderr — stdout stays
+ *  reserved for the report / JSON). */
+function printProgress(p) {
+    const n = (0, colors_1.colorize)(`${p.index + 1}/${p.total}`, 'dim');
+    const d = p.digest.session;
+    if (!d) {
+        process.stderr.write(`  ${(0, colors_1.colorize)('·', 'dim')} ${n} ${p.digest.name} ${(0, colors_1.colorize)('— no session', 'dim')}\n`);
+        return;
+    }
+    const failures = `${d.errors.length} ${d.errors.length === 1 ? 'failure' : 'failures'}`;
+    const stats = (0, colors_1.colorize)(`${d.turns} turns · ${d.userPrompts.length} prompts · ${failures}`, 'dim');
+    process.stderr.write(`  ${(0, colors_1.colorize)('✓', 'green')} ${n} ${p.digest.name}  ${stats}\n`);
+}
 function priorityBadge(p) {
     if (p === 'high')
         return (0, colors_1.colorize)('● high', 'red');

package/dist/utils/agent-judge.js

@@ -1,11 +1,121 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_JUDGE_THINKING = void 0;
+exports.spawnCollect = spawnCollect;
+exports.agentAttempts = agentAttempts;
 exports.runAgentRaw = runAgentRaw;
+exports.runAgentRawAsync = runAgentRawAsync;
 exports.runAgentJson = runAgentJson;
+exports.runAgentJsonAsync = runAgentJsonAsync;
 exports.parseAgentJson = parseAgentJson;
 const child_process_1 = require("child_process");
 const agent_config_1 = require("./agent-config");
-const DEFAULT_TIMEOUT_MS = 180000; // judging N transcripts is heavier than extraction
+/**
+ * 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.
+ */
+function spawnCollect(cmd, args, opts) {
+    return new Promise((resolve, reject) => {
+        const child = (0, child_process_1.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);
+        });
+    });
+}
+/**
+ * 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.
+ */
+exports.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.
+ */
+function agentAttempts(agentType, prompt, opts = {}) {
+    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, opts) {
+    return {
+        schema: opts.schema,
+        model: opts.model,
+        thinking: opts.thinking ?? (agentType === 'pi' ? exports.DEFAULT_JUDGE_THINKING : undefined),
+    };
+}
+function wrapJudgeError(err, agentType) {
+    // 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 = 300000; // judging N transcripts is heavier than extraction; a big prompt + slow model can run minutes
 const DEFAULT_MAX_BUFFER = 32 * 1024 * 1024;
 /**
  * Invoke the agent with `prompt` and return the raw stdout. Throws a clear error
@@ -17,37 +127,42 @@ function runAgentRaw(prompt, opts = {}) {
     const timeout = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const maxBuffer = opts.maxBuffer ?? DEFAULT_MAX_BUFFER;
     const exec = opts.exec ??
-        ((cmd, args, o) => (0, child_process_1.execFileSync)(cmd, args, { encoding: 'utf-8', timeout: o.timeout, maxBuffer: o.maxBuffer }));
-    const attempt = (cmd, args) => 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]);
-            }
+        // `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) => (0, child_process_1.execFileSync)(cmd, args, { encoding: 'utf-8', input: '', timeout: o.timeout, maxBuffer: o.maxBuffer }));
+    const attempts = agentAttempts(agentType, prompt, attemptOptions(agentType, opts));
+    let lastErr;
+    for (const a of attempts) {
+        try {
+            return exec(a.cmd, a.args, { timeout, maxBuffer });
         }
-        if (agentType === 'opencode') {
-            return attempt('opencode', ['run', prompt]);
+        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.
+ */
+async function runAgentRawAsync(prompt, opts = {}) {
+    const agentType = opts.agentType ?? (0, agent_config_1.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;
+    for (const a of attempts) {
         try {
-            return attempt('pi', [...piLean, '-p', prompt]);
+            return await exec(a.cmd, a.args, { timeout, maxBuffer });
         }
-        catch {
-            return attempt('pi', ['-p', prompt]);
+        catch (err) {
+            lastErr = err; // try the next (fallback) form
         }
     }
-    catch (err) {
-        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);
 }
 /**
  * Run the agent and parse its reply as JSON, tolerating the shapes different
@@ -58,6 +173,11 @@ function runAgentJson(prompt, opts = {}) {
     const raw = runAgentRaw(prompt, opts);
     return parseAgentJson(raw);
 }
+/** Non-blocking twin of {@link runAgentJson}. */
+async function runAgentJsonAsync(prompt, opts = {}) {
+    const raw = await runAgentRawAsync(prompt, opts);
+    return parseAgentJson(raw);
+}
 /** Extract a JSON object from an agent's raw stdout. Exported for tests. */
 function parseAgentJson(raw) {
     let text = raw.trim();

package/dist/utils/reflect-analyze.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeErrorSignature = normalizeErrorSignature;
+exports.analyzeCorpus = analyzeCorpus;
+exports.buildAnalysisPrompt = buildAnalysisPrompt;
+const reflect_1 = require("./reflect");
+// --------------------------------------------------------------- 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.
+ */
+function normalizeErrorSignature(raw) {
+    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);
+}
+/**
+ * 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.
+ */
+function analyzeCorpus(corpus, opts = {}) {
+    const topErrorsK = opts.topErrors ?? 8;
+    const topToolsK = opts.topTools ?? 10;
+    const exampleChars = opts.exampleChars ?? 160;
+    const maxReSteer = opts.maxReSteer ?? 8;
+    const errorMap = new Map();
+    const toolMap = new Map();
+    const workspacesMissingContext = [];
+    const workspacesBoilerplateContext = [];
+    const reSteerSamples = [];
+    const workspaces = [];
+    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(reflect_1.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();
+        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 = [...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 = [...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.
+ */
+function buildAnalysisPrompt(a) {
+    const L = [];
+    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');
+}