@nemus-cli/nemus 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -7,19 +7,49 @@ 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` 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,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) => {
@@ -27,11 +30,15 @@ async function handleReflect(opts) {
         }
         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');
             }
@@ -49,12 +56,14 @@ 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();

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

package/dist/utils/reflect.js

@@ -34,10 +34,11 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.REFLECT_SCHEMA = void 0;
+exports.isCorrectionPrompt = isCorrectionPrompt;
 exports.distillTranscript = distillTranscript;
+exports.classifyAgentsMd = classifyAgentsMd;
 exports.findLatestTranscriptFile = findLatestTranscriptFile;
 exports.gatherReflectionCorpus = gatherReflectionCorpus;
-exports.buildJudgePrompt = buildJudgePrompt;
 exports.parseReflectionReport = parseReflectionReport;
 const fs = __importStar(require("fs/promises"));
 const path = __importStar(require("path"));
@@ -51,8 +52,18 @@ const claude_sessions_1 = require("./claude-sessions");
 // fraction of the tokens (~halving the prompt), so the judge actually finishes.
 const MAX_PROMPTS = 12;
 const MAX_ERRORS = 15;
+const MAX_RESTEER = 6;
 const PROMPT_CHARS = 400;
 const ERROR_CHARS = 200;
+const RESTEER_CHARS = 240;
+// A conservative “the user corrected / redirected the agent” cue. Soft signal:
+// used to count re-steers and to capture the verbatim message for the judge.
+const CORRECTION_RE = /\b(no|nope|wrong|incorrect|revert|undo|instead|actually|you (missed|forgot|broke|didn'?t)|that'?s? (wrong|not right|incorrect)|not what|don'?t)\b/i;
+/** Whether a single user prompt reads like a correction/redirect. Exported +
+ *  shared with the analyzer so the two never diverge. */
+function isCorrectionPrompt(prompt) {
+    return CORRECTION_RE.test(prompt ?? '');
+}
 /** Flatten a message `content` (string or content-block array) to plain text. */
 function contentToText(content) {
     if (typeof content === 'string')
@@ -90,6 +101,7 @@ function isToolFailure(flag, text) {
  */
 function distillTranscript(raw, meta) {
     const userPrompts = [];
+    const reSteerSamples = [];
     const errors = [];
     const tools = new Set();
     let turns = 0;
@@ -143,13 +155,57 @@ function distillTranscript(raw, meta) {
             const isToolResultOnly = Array.isArray(content) && content.length > 0 && content.every((b) => b?.type === 'tool_result');
             if (!isToolResultOnly) {
                 const text = contentToText(content).trim();
-                if (text && !text.startsWith('<') && userPrompts.length < MAX_PROMPTS) {
-                    userPrompts.push(text.slice(0, PROMPT_CHARS));
+                if (text && !text.startsWith('<')) {
+                    if (userPrompts.length < MAX_PROMPTS)
+                        userPrompts.push(text.slice(0, PROMPT_CHARS));
+                    // Capture corrections verbatim (bounded) — the sharpest coaching signal.
+                    if (reSteerSamples.length < MAX_RESTEER && isCorrectionPrompt(text)) {
+                        reSteerSamples.push(text.slice(0, RESTEER_CHARS));
+                    }
                 }
             }
         }
     }
-    return { sessionId: meta.sessionId, agentType: meta.agentType, turns, userPrompts, errors, tools: [...tools] };
+    return { sessionId: meta.sessionId, agentType: meta.agentType, turns, userPrompts, reSteerSamples, errors, tools: [...tools] };
+}
+// ------------------------------------------------------- context classification
+// Lines that are structural/boilerplate rather than real, custom guidance.
+const BOILERPLATE_MARKERS = [
+    'ws-rules:',
+    'this workspace was created with',
+    'workspace manager',
+    'saved context',
+    'add your own notes here',
+    'common workflows',
+];
+/**
+ * Classify an AGENTS.md/CLAUDE.md by how much *real* guidance it carries, so the
+ * judge can tell “no context” from “has a file but it's the generated template.”
+ * Heuristic + pure.
+ *
+ * Deliberately **newline-independent**: it measures the volume of non-boilerplate
+ * prose (word count) plus heading count via a whitespace-tolerant regex, rather
+ * than splitting on lines. A line-anchored version would misclassify any excerpt
+ * whose newlines were collapsed to spaces upstream (a real bug class caught in a
+ * sibling implementation) — here even a fully single-lined file classifies the
+ * same as its multi-line original.
+ */
+function classifyAgentsMd(content) {
+    if (!content || !content.trim())
+        return 'missing';
+    let s = content.replace(/\r\n/g, '\n').toLowerCase();
+    s = s.replace(/```[\s\S]*?```/g, ' '); // drop fenced code
+    s = s.replace(/<!--[\s\S]*?-->/g, ' '); // drop HTML comments
+    for (const m of BOILERPLATE_MARKERS)
+        s = s.split(m).join(' '); // drop generated boilerplate (markers are lowercase)
+    // Headings: a `#` run at start OR after any whitespace (so a collapsed,
+    // single-line excerpt still counts them), followed by a space.
+    const headings = (s.match(/(?:^|\s)#{1,6}\s/g) || []).length;
+    // Remaining non-boilerplate words (markdown punctuation stripped).
+    const words = s.replace(/[#|>*_`~-]/g, ' ').split(/\s+/).filter((w) => w.length > 1).length;
+    if (words < 40)
+        return 'boilerplate';
+    return headings >= 2 || words >= 60 ? 'substantive' : 'boilerplate';
 }
 // --------------------------------------------------------- corpus gathering
 /** Locate the most recent `.jsonl` transcript for a workspace under an agent. */
@@ -224,18 +280,25 @@ async function listAvailableSkills() {
     }
     return [...names].sort();
 }
+/** Which context files exist at the workspace root, plus how substantive the
+ *  primary one is (missing/boilerplate/substantive). One read per present file. */
 async function contextFilesFor(workspacePath) {
     const present = [];
+    let quality = 'missing';
     for (const name of (0, agent_config_1.getAllKnownContextFileNames)()) {
         try {
-            await fs.access(path.join(workspacePath, name));
+            const content = await fs.readFile(path.join(workspacePath, name), 'utf-8');
             present.push(name);
+            // Classify the first present file, then keep the best classification seen.
+            const c = classifyAgentsMd(content);
+            if (quality === 'missing' || (quality === 'boilerplate' && c === 'substantive'))
+                quality = c;
         }
         catch {
-            /* not present */
+            /* not present / unreadable */
         }
     }
-    return present;
+    return { files: present, quality };
 }
 /**
  * Build the corpus the judge reasons over: the `limit` most **recently active**
@@ -256,11 +319,13 @@ async function gatherReflectionCorpus(limit, onProgress) {
     for (let index = 0; index < recent.length; index++) {
         const s = recent[index];
         const meta = metaByName.get(s.workspaceName);
+        const context = await contextFilesFor(s.workspacePath);
         const digest = {
             name: s.workspaceName,
             repoCount: meta?.metadata?.repositories?.length ?? 0,
             repos: (meta?.metadata?.repositories ?? []).map((r) => r.name),
-            contextFiles: await contextFilesFor(s.workspacePath),
+            contextFiles: context.files,
+            contextQuality: context.quality,
             session: await readDigestForSession(s),
         };
         digests.push(digest);
@@ -292,37 +357,8 @@ exports.REFLECT_SCHEMA = JSON.stringify({
     },
     required: ['summary', 'recommendations'],
 });
-/**
- * Build the LLM-as-a-judge prompt. The judge sees distilled recent sessions and
- * is asked to recommend concrete improvements to the user's SETUP (skills,
- * AGENTS.md/context rules, connectivity/tests, prompt habits, workflow) — not to
- * redo the tasks. Output is strict JSON matching REFLECT_SCHEMA.
- */
-function buildJudgePrompt(corpus) {
-    const lines = [];
-    lines.push('You are an expert reviewer ("LLM as a judge") analyzing an engineer\'s recent AI coding-agent sessions.', '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 habits to change. Judge the setup, do NOT redo the tasks.', '', 'Base every recommendation on evidence in the sessions below (repeated failures, retries, vague', 'prompts, missing context). Prefer a few high-signal, actionable items over many generic ones.', 'When you suggest a skill or an AGENTS.md rule, include a short concrete `example` snippet.', '', `Globally installed skills (don't re-suggest these; suggest genuinely missing ones): ${corpus.availableSkills.join(', ') || '(none)'}`, '', `Recent workspaces (${corpus.workspaces.length}):`);
-    for (const ws of corpus.workspaces) {
-        lines.push(`\n## ${ws.name}`);
-        lines.push(`repos: ${ws.repos.join(', ') || '(none)'} | context files: ${ws.contextFiles.join(', ') || 'NONE'}`);
-        if (!ws.session) {
-            lines.push('session: (no recent agent session found)');
-            continue;
-        }
-        lines.push(`session: ${ws.session.turns} turns, tools used: ${ws.session.tools.join(', ') || '(none)'}`);
-        if (ws.session.userPrompts.length) {
-            lines.push('user prompts:');
-            for (const p of ws.session.userPrompts)
-                lines.push(`  - ${p.replace(/\n/g, ' ')}`);
-        }
-        if (ws.session.errors.length) {
-            lines.push('errors/failures observed:');
-            for (const e of ws.session.errors)
-                lines.push(`  - ${e.replace(/\n/g, ' ')}`);
-        }
-    }
-    lines.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 lines.join('\n');
-}
+// The judge prompt is now built from pre-computed FACTS (see reflect-analyze.ts
+// `buildAnalysisPrompt`), not raw transcripts, so the LLM call stays small/fast.
 // ----------------------------------------------------------- response parse
 const KINDS = ['skill', 'context', 'test', 'prompt', 'connectivity', 'workflow', 'other'];
 const PRIORITIES = ['high', 'medium', 'low'];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nemus-cli/nemus",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "workspaces": [
     "packages/*"
   ],

package/src/cli/ai-prompt.ts

@@ -140,6 +140,10 @@ function runExtraction(cmd: string, fullArgs: string[], fallbackArgs?: string[])
   const exec = (args: string[]) =>
     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,
     });