@nemus-cli/nemus 0.3.1 → 0.3.3

package/dist/utils/reflect.js

@@ -33,14 +33,17 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.REFLECT_SCHEMA = void 0;
+exports.REFLECT_REPORTS_DIR = 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;
+exports.saveReflectionReport = saveReflectionReport;
 const fs = __importStar(require("fs/promises"));
 const path = __importStar(require("path"));
+const config_1 = require("./config");
 const workspace_meta_1 = require("./workspace-meta");
 const agent_config_1 = require("./agent-config");
 const claude_sessions_1 = require("./claude-sessions");
@@ -51,8 +54,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 +103,7 @@ function isToolFailure(flag, text) {
  */
 function distillTranscript(raw, meta) {
     const userPrompts = [];
+    const reSteerSamples = [];
     const errors = [];
     const tools = new Set();
     let turns = 0;
@@ -143,13 +157,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 +282,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**
@@ -244,23 +309,28 @@ async function contextFilesFor(workspacePath) {
  * session, plus the globally-available skills. `onProgress` (optional) fires
  * once per workspace as it finishes, for a live progress display.
  */
-async function gatherReflectionCorpus(limit, onProgress) {
+async function gatherReflectionCorpus(limit, onProgress, opts = {}) {
     const [sessions, workspaces, availableSkills] = await Promise.all([
         (0, claude_sessions_1.getWorkspaceSessions)(), // already sorted by last-active, one per workspace
         (0, workspace_meta_1.listWorkspaces)(false),
         listAvailableSkills(),
     ]);
     const metaByName = new Map(workspaces.map((w) => [w.name, w]));
-    const recent = sessions.slice(0, limit);
+    // A single named workspace (ignores limit), else the N most recently active.
+    const recent = opts.workspace
+        ? sessions.filter((s) => s.workspaceName === opts.workspace)
+        : sessions.slice(0, limit);
     const digests = [];
     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 +362,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'];
@@ -351,3 +392,19 @@ function parseReflectionReport(parsed) {
         .filter((r) => r !== null);
     return { summary, recommendations };
 }
+// -------------------------------------------------------------- report saving
+/** Where saved reflection reports live: `~/.nemus/reflect/`. */
+exports.REFLECT_REPORTS_DIR = path.join(config_1.CACHE_DIR, 'reflect');
+/**
+ * Persist a reflection report as timestamped JSON under `~/.nemus/reflect/`, so
+ * a run can be revisited or diffed over time. Returns the written path. Pure
+ * side-effect (mkdir -p + write); callers treat failure as non-fatal.
+ */
+async function saveReflectionReport(report, meta) {
+    await fs.mkdir(exports.REFLECT_REPORTS_DIR, { recursive: true });
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const scope = meta.workspace ? `-${meta.workspace.replace(/[^a-zA-Z0-9_-]+/g, '_')}` : '';
+    const file = path.join(exports.REFLECT_REPORTS_DIR, `${stamp}${scope}.json`);
+    await fs.writeFile(file, JSON.stringify({ generatedAt: new Date().toISOString(), ...meta, ...report }, null, 2));
+    return file;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nemus-cli/nemus",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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,
     });

package/src/commands/reflect.ts

@@ -4,13 +4,14 @@ import { outputJson, outputJsonError } from '../utils/output';
 import { colorize } from '../utils/colors';
 import {
   gatherReflectionCorpus,
-  buildJudgePrompt,
   parseReflectionReport,
+  saveReflectionReport,
   REFLECT_SCHEMA,
   ReflectionReport,
   ReflectProgress,
   Recommendation,
 } from '../utils/reflect';
+import { analyzeCorpus, buildAnalysisPrompt } from '../utils/reflect-analyze';
 import { runAgentJsonAsync } from '../utils/agent-judge';
 
 export function registerReflectCommand(parent: Command) {
@@ -19,28 +20,50 @@ export function registerReflectCommand(parent: Command) {
     .alias('retro')
     .description('Analyze your recent workspace sessions and suggest skill/prompt/context improvements (LLM-as-a-judge)')
     .option('-n, --limit <n>', 'How many recent workspaces to analyze', '10')
+    .option('-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);
     });
 }
 
-async function handleReflect(opts: { limit?: string; json?: boolean; dryRun?: boolean }) {
+async function handleReflect(opts: {
+  limit?: string;
+  workspace?: string;
+  model?: string;
+  thinking?: string;
+  json?: boolean;
+  save?: boolean; // commander sets `save: false` for --no-save
+  dryRun?: boolean;
+}) {
   const limit = Math.max(1, Number.parseInt(opts.limit ?? '10', 10) || 10);
   try {
     const showProgress = !opts.json && !opts.dryRun;
     if (showProgress) {
-      logStep(`Analyzing your ${colorize(String(limit), 'cyan')} most recent workspaces…`);
+      logStep(
+        opts.workspace
+          ? `Analyzing workspace ${colorize(opts.workspace, 'cyan')}…`
+          : `Analyzing your ${colorize(String(limit), 'cyan')} most recent workspaces…`,
+      );
     }
 
-    const corpus = await gatherReflectionCorpus(limit, showProgress ? printProgress : undefined);
+    const corpus = await gatherReflectionCorpus(limit, showProgress ? printProgress : undefined, {
+      workspace: opts.workspace,
+    });
     const withSessions = corpus.workspaces.filter((w) => w.session).length;
-    const prompt = buildJudgePrompt(corpus);
+    // A script does the heavy analysis (clustering failures, counting tools,
+    // spotting correction loops); the LLM only ever sees these compact facts,
+    // so the judge call stays small + fast regardless of workspace count.
+    const analysis = analyzeCorpus(corpus);
+    const prompt = buildAnalysisPrompt(analysis);
 
     if (opts.dryRun) {
-      // No LLM call — surface exactly what the judge would see.
-      if (opts.json) outputJson({ corpus, prompt });
+      // No LLM call — surface the computed facts + exactly what the judge sees.
+      if (opts.json) outputJson({ analysis, prompt });
       else {
         process.stdout.write(prompt + '\n');
       }
@@ -48,7 +71,9 @@ async function handleReflect(opts: { limit?: string; json?: boolean; dryRun?: bo
     }
 
     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) outputJsonError(msg);
       else logError(msg);
       process.exit(1);
@@ -58,22 +83,39 @@ async function handleReflect(opts: { limit?: string; json?: boolean; dryRun?: bo
     // (non-blocking) so a live spinner shows it's alive, not hung. Timeout is
     // overridable for slow local models.
     const timeoutMs = Number.parseInt(process.env.NEMUS_JUDGE_TIMEOUT_MS ?? '', 10) || undefined;
+    const model = opts.model ?? process.env.NEMUS_JUDGE_MODEL ?? undefined;
+    const thinking = opts.thinking ?? process.env.NEMUS_JUDGE_THINKING ?? undefined;
     const stopSpinner = opts.json
       ? () => {}
       : startSpinner(`Judging ${withSessions} session(s) with your configured agent (this can take a minute)…`);
     let parsed: unknown;
     try {
-      parsed = await runAgentJsonAsync(prompt, { schema: REFLECT_SCHEMA, timeoutMs });
+      parsed = await runAgentJsonAsync(prompt, { schema: REFLECT_SCHEMA, timeoutMs, model, thinking });
     } finally {
       stopSpinner();
     }
     const report = parseReflectionReport(parsed);
 
+    // Persist the report (best-effort; never fails the run) unless --no-save.
+    let savedTo: string | undefined;
+    if (opts.save !== false) {
+      try {
+        savedTo = await saveReflectionReport(report, {
+          analyzed: withSessions,
+          workspaces: corpus.workspaces.length,
+          workspace: opts.workspace,
+        });
+      } catch {
+        /* saving is a convenience, not the point */
+      }
+    }
+
     if (opts.json) {
-      outputJson({ analyzed: withSessions, workspaces: corpus.workspaces.length, ...report });
+      outputJson({ analyzed: withSessions, workspaces: corpus.workspaces.length, ...report, savedTo });
       return;
     }
     printReport(report, corpus.workspaces.length, withSessions);
+    if (savedTo) logInfo(`Saved report to ${colorize(savedTo, 'dim')}`);
   } catch (error) {
     const msg = error instanceof Error ? error.message : 'reflect failed';
     if (opts.json) outputJsonError(msg);

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

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

package/src/utils/agent-judge.ts

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