@nemus-cli/nemus 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -7,19 +7,61 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.3] - 2026-08-30
+
+### Added
+
+- **`reflect --workspace <name>`** — analyze a single workspace by name (ignores
+  `--limit`); a clean error if that workspace has no recent Claude/pi session.
+- **`reflect` now saves each report** as timestamped JSON under
+  `~/.nemus/reflect/` (scope suffix for single-workspace runs), so runs can be
+  revisited or diffed over time. Best-effort (never fails the run); disable with
+  **`--no-save`**. The path is printed after a run (and included as `savedTo` in
+  `--json`).
+
+## [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` now shows live progress and no longer looks hung.** The judge call
-  ran synchronously (`execFileSync`), which blocked the event loop, and a
-  10-workspace run could hit the 180s cap and die with a raw
-  `spawnSync pi ETIMEDOUT`. Now: (1) the gather phase prints a **per-workspace
-  line** as each session is read (`✓ 1/3 my-workspace  635 turns · 12 prompts ·
-  13 failures`); (2) the judge runs **async** behind a live spinner with elapsed
-  seconds; (3) the timeout is raised to 300s, overridable via
-  `NEMUS_JUDGE_TIMEOUT_MS`, and a timeout now yields an **actionable** message
-  ("try a smaller --limit, a faster agent, or raise the cap"); (4) the judge
-  prompt is leaner (fewer prompts/errors per session) so a local model actually
-  finishes.
+- **`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
 

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,7 +13,11 @@ 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('-w, --workspace <name>', 'Analyze a single workspace by name (ignores --limit)')
+        .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('--no-save', 'Do not save the report to ~/.nemus/reflect/')
         .option('--dry-run', 'Print the assembled corpus + judge prompt without calling the agent')
         .action(async (opts) => {
         await handleReflect(opts);
@@ -23,22 +28,32 @@ async function handleReflect(opts) {
     try {
         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.logStep)(opts.workspace
+                ? `Analyzing workspace ${(0, colors_1.colorize)(opts.workspace, 'cyan')}…`
+                : `Analyzing your ${(0, colors_1.colorize)(String(limit), 'cyan')} most recent workspaces…`);
         }
-        const corpus = await (0, reflect_1.gatherReflectionCorpus)(limit, showProgress ? printProgress : undefined);
+        const corpus = await (0, reflect_1.gatherReflectionCorpus)(limit, showProgress ? printProgress : undefined, {
+            workspace: opts.workspace,
+        });
         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');
             }
             return;
         }
         if (withSessions === 0) {
-            const msg = 'No recent agent sessions found to analyze (need Claude/pi session transcripts).';
+            const msg = opts.workspace
+                ? `No recent agent session found for workspace "${opts.workspace}" (need a Claude/pi transcript).`
+                : 'No recent agent sessions found to analyze (need Claude/pi session transcripts).';
             if (opts.json)
                 (0, output_1.outputJsonError)(msg);
             else
@@ -49,22 +64,40 @@ async function handleReflect(opts) {
         // (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 });
+            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);
+        // Persist the report (best-effort; never fails the run) unless --no-save.
+        let savedTo;
+        if (opts.save !== false) {
+            try {
+                savedTo = await (0, reflect_1.saveReflectionReport)(report, {
+                    analyzed: withSessions,
+                    workspaces: corpus.workspaces.length,
+                    workspace: opts.workspace,
+                });
+            }
+            catch {
+                /* saving is a convenience, not the point */
+            }
+        }
         if (opts.json) {
-            (0, output_1.outputJson)({ analyzed: withSessions, workspaces: corpus.workspaces.length, ...report });
+            (0, output_1.outputJson)({ analyzed: withSessions, workspaces: corpus.workspaces.length, ...report, savedTo });
             return;
         }
         printReport(report, corpus.workspaces.length, withSessions);
+        if (savedTo)
+            (0, logger_1.logInfo)(`Saved report to ${(0, colors_1.colorize)(savedTo, 'dim')}`);
     }
     catch (error) {
         const msg = error instanceof Error ? error.message : 'reflect failed';

package/dist/utils/agent-judge.js

@@ -1,5 +1,7 @@
 "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;
@@ -7,28 +9,102 @@ exports.runAgentJson = runAgentJson;
 exports.runAgentJsonAsync = runAgentJsonAsync;
 exports.parseAgentJson = parseAgentJson;
 const child_process_1 = require("child_process");
-const util_1 = require("util");
 const agent_config_1 = require("./agent-config");
-const execFileAsync = (0, util_1.promisify)(child_process_1.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.
+ */
+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).
+ * 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, schema) {
+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.
-        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, 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
@@ -51,8 +127,10 @@ 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 attempts = agentAttempts(agentType, prompt, opts.schema);
+        // `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 {
@@ -73,9 +151,8 @@ 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 ??
-        (async (cmd, args, o) => (await execFileAsync(cmd, args, { encoding: 'utf-8', timeout: o.timeout, maxBuffer: o.maxBuffer })).stdout.toString());
-    const attempts = agentAttempts(agentType, prompt, opts.schema);
+    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 {

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