@nemus-cli/nemus 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### 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.
+
 ## [0.3.0] - 2026-08-27
 
 ### Added

package/dist/commands/reflect.js

@@ -21,11 +21,11 @@ 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);
         if (opts.dryRun) {
@@ -45,9 +45,20 @@ 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 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 });
+        }
+        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 +86,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,45 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+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 util_1 = require("util");
 const agent_config_1 = require("./agent-config");
-const DEFAULT_TIMEOUT_MS = 180000; // judging N transcripts is heavier than extraction
+const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
+/**
+ * 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).
+ */
+function agentAttempts(agentType, prompt, schema) {
+    if (agentType === 'claude') {
+        const preferred = ['-p', prompt, '--output-format', 'json', '--bare', '--strict-mcp-config', '--disable-slash-commands'];
+        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] }];
+    }
+    if (agentType === 'opencode') {
+        return [{ cmd: 'opencode', args: ['run', prompt] }];
+    }
+    // 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] }];
+}
+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
@@ -18,36 +52,40 @@ function runAgentRaw(prompt, opts = {}) {
     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]);
-            }
+    const attempts = agentAttempts(agentType, prompt, opts.schema);
+    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 ??
+        (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);
+    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 +96,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.js

@@ -45,10 +45,14 @@ const workspace_meta_1 = require("./workspace-meta");
 const agent_config_1 = require("./agent-config");
 const claude_sessions_1 = require("./claude-sessions");
 // --------------------------------------------------------- transcript distill
-const MAX_PROMPTS = 25;
-const MAX_ERRORS = 25;
-const PROMPT_CHARS = 600;
-const ERROR_CHARS = 300;
+// Kept deliberately lean: the judge runs on the user's own (often local, slow)
+// agent, and a 10-workspace corpus at full verbosity produced a ~200KB prompt
+// that timed pi out. These bounds capture the pattern of a session at a
+// fraction of the tokens (~halving the prompt), so the judge actually finishes.
+const MAX_PROMPTS = 12;
+const MAX_ERRORS = 15;
+const PROMPT_CHARS = 400;
+const ERROR_CHARS = 200;
 /** Flatten a message `content` (string or content-block array) to plain text. */
 function contentToText(content) {
     if (typeof content === 'string')
@@ -237,9 +241,10 @@ async function contextFilesFor(workspacePath) {
  * Build the corpus the judge reasons over: the `limit` most **recently active**
  * workspaces (by their latest agent session, not creation date — a retrospective
  * is about recent *work*), each with its repos, context files, and distilled
- * session, plus the globally-available skills.
+ * session, plus the globally-available skills. `onProgress` (optional) fires
+ * once per workspace as it finishes, for a live progress display.
  */
-async function gatherReflectionCorpus(limit) {
+async function gatherReflectionCorpus(limit, onProgress) {
     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),
@@ -248,15 +253,18 @@ async function gatherReflectionCorpus(limit) {
     const metaByName = new Map(workspaces.map((w) => [w.name, w]));
     const recent = sessions.slice(0, limit);
     const digests = [];
-    for (const s of recent) {
+    for (let index = 0; index < recent.length; index++) {
+        const s = recent[index];
         const meta = metaByName.get(s.workspaceName);
-        digests.push({
+        const digest = {
             name: s.workspaceName,
             repoCount: meta?.metadata?.repositories?.length ?? 0,
             repos: (meta?.metadata?.repositories ?? []).map((r) => r.name),
             contextFiles: await contextFilesFor(s.workspacePath),
             session: await readDigestForSession(s),
-        });
+        };
+        digests.push(digest);
+        onProgress?.({ index, total: recent.length, digest });
     }
     return { generatedAt: new Date().toISOString(), availableSkills, workspaces: digests };
 }

package/package.json

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

package/src/commands/reflect.ts

@@ -8,9 +8,10 @@ import {
   parseReflectionReport,
   REFLECT_SCHEMA,
   ReflectionReport,
+  ReflectProgress,
   Recommendation,
 } from '../utils/reflect';
-import { runAgentJson } from '../utils/agent-judge';
+import { runAgentJsonAsync } from '../utils/agent-judge';
 
 export function registerReflectCommand(parent: Command) {
   parent
@@ -28,12 +29,12 @@ export function registerReflectCommand(parent: Command) {
 async function handleReflect(opts: { limit?: string; json?: boolean; dryRun?: boolean }) {
   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) {
       logStep(`Analyzing your ${colorize(String(limit), 'cyan')} most recent workspaces…`);
-      logInfo('Reading sessions and distilling prompts + failures…');
     }
 
-    const corpus = await gatherReflectionCorpus(limit);
+    const corpus = await gatherReflectionCorpus(limit, showProgress ? printProgress : undefined);
     const withSessions = corpus.workspaces.filter((w) => w.session).length;
     const prompt = buildJudgePrompt(corpus);
 
@@ -53,8 +54,19 @@ async function handleReflect(opts: { limit?: string; json?: boolean; dryRun?: bo
       process.exit(1);
     }
 
-    if (!opts.json) logInfo(`Judging ${withSessions} session(s) with your configured agent…`);
-    const parsed = runAgentJson(prompt, { schema: 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 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 });
+    } finally {
+      stopSpinner();
+    }
     const report = parseReflectionReport(parsed);
 
     if (opts.json) {
@@ -83,6 +95,46 @@ const KIND_LABEL: Record<Recommendation['kind'], string> = {
   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: string): () => void {
+  if (!process.stderr.isTTY) {
+    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${colorize(frames[(i = (i + 1) % frames.length)], 'cyan')} ${text} ${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: ReflectProgress): void {
+  const n = colorize(`${p.index + 1}/${p.total}`, 'dim');
+  const d = p.digest.session;
+  if (!d) {
+    process.stderr.write(`  ${colorize('·', 'dim')} ${n} ${p.digest.name} ${colorize('— no session', 'dim')}\n`);
+    return;
+  }
+  const failures = `${d.errors.length} ${d.errors.length === 1 ? 'failure' : 'failures'}`;
+  const stats = colorize(`${d.turns} turns · ${d.userPrompts.length} prompts · ${failures}`, 'dim');
+  process.stderr.write(`  ${colorize('✓', 'green')} ${n} ${p.digest.name}  ${stats}\n`);
+}
+
 function priorityBadge(p: Recommendation['priority']): string {
   if (p === 'high') return colorize('● high', 'red');
   if (p === 'medium') return colorize('● med', 'yellow');

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

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { parseAgentJson, runAgentRaw } from './agent-judge';
+import { parseAgentJson, runAgentRaw, runAgentRawAsync, agentAttempts } from './agent-judge';
 
 describe('parseAgentJson', () => {
   it('unwraps the common agent envelopes and shapes', () => {
@@ -16,6 +16,40 @@ describe('parseAgentJson', () => {
   });
 });
 
+describe('agentAttempts', () => {
+  it('claude: preferred (schema + lean flags) then a plain fallback', () => {
+    const a = agentAttempts('claude', 'P', '{"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'] });
+  });
+  it('pi: lean then plain; opencode: single run', () => {
+    const pi = agentAttempts('pi', 'P');
+    expect(pi[0].args).toEqual(expect.arrayContaining(['--no-tools', '--no-skills', '-p', 'P']));
+    expect(pi[1]).toEqual({ cmd: 'pi', args: ['-p', 'P'] });
+    expect(agentAttempts('opencode', 'P')).toEqual([{ cmd: 'opencode', args: ['run', 'P'] }]);
+  });
+});
+
+describe('runAgentRawAsync', () => {
+  it('runs the preferred attempt and returns stdout', async () => {
+    const calls: string[][] = [];
+    const execAsync = async (cmd: string, args: string[]) => {
+      calls.push([cmd, ...args]);
+      return '{"ok":true}';
+    };
+    const out = await runAgentRawAsync('P', { agentType: 'pi', execAsync });
+    expect(out).toBe('{"ok":true}');
+    expect(calls).toHaveLength(1); // first attempt succeeded, no fallback
+  });
+
+  it('turns a timeout into an actionable error', async () => {
+    const execAsync = async () => {
+      throw Object.assign(new Error('spawn pi ETIMEDOUT'), { code: 'ETIMEDOUT', killed: true });
+    };
+    await expect(runAgentRawAsync('P', { agentType: 'pi', execAsync })).rejects.toThrow(/timed out.*NEMUS_JUDGE_TIMEOUT_MS/s);
+  });
+});
+
 describe('runAgentRaw', () => {
   it('claude: passes the schema + lean flags, falls back on a rejected flag', () => {
     const calls: string[][] = [];

package/src/utils/agent-judge.ts

@@ -1,6 +1,9 @@
-import { execFileSync } from 'child_process';
+import { execFile, execFileSync } from 'child_process';
+import { promisify } from 'util';
 import { getPrimaryAgent } from './agent-config';
 
+const execFileAsync = promisify(execFile);
+
 /**
  * Run the user's configured coding agent headlessly as an "LLM-as-a-judge":
  * feed it a prompt, get back a parsed JSON object. This reuses whatever agent
@@ -16,13 +19,54 @@ export interface JudgeOptions {
   schema?: string;
   timeoutMs?: number;
   maxBuffer?: number;
-  /** Injected for tests. Defaults to the real child_process runner. */
+  /** Injected for tests. Defaults to the real (blocking) child_process runner. */
   exec?: (cmd: string, args: string[], opts: { timeout: number; maxBuffer: number }) => string;
+  /** Injected for tests. Async runner used by the non-blocking variants. */
+  execAsync?: (cmd: string, args: string[], opts: { timeout: number; maxBuffer: number }) => Promise<string>;
   /** Injected for tests. Defaults to the configured primary agent. */
   agentType?: 'claude' | 'pi' | 'opencode' | 'codex' | 'gemini';
 }
 
-const DEFAULT_TIMEOUT_MS = 180_000; // judging N transcripts is heavier than extraction
+export type JudgeAgentType = NonNullable<JudgeOptions['agentType']>;
+
+export interface AgentAttempt {
+  cmd: string;
+  args: string[];
+}
+
+/**
+ * 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).
+ */
+export function agentAttempts(agentType: JudgeAgentType, prompt: string, schema?: string): AgentAttempt[] {
+  if (agentType === 'claude') {
+    const preferred = ['-p', prompt, '--output-format', 'json', '--bare', '--strict-mcp-config', '--disable-slash-commands'];
+    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] }];
+  }
+  if (agentType === 'opencode') {
+    return [{ cmd: 'opencode', args: ['run', prompt] }];
+  }
+  // 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] }];
+}
+
+function wrapJudgeError(err: any, agentType: string): Error {
+  // A timeout is the common failure (big prompt + slow local model), so make it
+  // actionable instead of surfacing a raw `spawn … ETIMEDOUT`.
+  if (err?.killed || err?.code === 'ETIMEDOUT' || err?.signal === 'SIGTERM' || /ETIMEDOUT/.test(String(err?.message ?? ''))) {
+    return new Error(
+      `agent judge (${agentType}) timed out. Try a smaller --limit, a faster agent, or raise the cap with NEMUS_JUDGE_TIMEOUT_MS.`,
+    );
+  }
+  const detail = (err?.stderr || err?.stdout || err?.message || 'unknown error').toString().trim().slice(0, 500);
+  return new Error(`agent judge failed (${agentType}): ${detail}`);
+}
+
+const DEFAULT_TIMEOUT_MS = 300_000; // judging N transcripts is heavier than extraction; a big prompt + slow model can run minutes
 const DEFAULT_MAX_BUFFER = 32 * 1024 * 1024;
 
 /**
@@ -38,33 +82,42 @@ export function runAgentRaw(prompt: string, opts: JudgeOptions = {}): string {
     opts.exec ??
     ((cmd, args, o) => execFileSync(cmd, args, { encoding: 'utf-8', timeout: o.timeout, maxBuffer: o.maxBuffer }));
 
-  const attempt = (cmd: string, args: string[]) => exec(cmd, args, { timeout, maxBuffer });
-
-  try {
-    if (agentType === 'claude') {
-      const preferred = ['-p', prompt, '--output-format', 'json', '--bare', '--strict-mcp-config', '--disable-slash-commands'];
-      if (opts.schema) preferred.push('--json-schema', opts.schema);
-      try {
-        return attempt('claude', preferred);
-      } catch {
-        // Older claude may reject the newer flags — fall back to the plainest form.
-        return attempt('claude', ['-p', prompt]);
-      }
-    }
-    if (agentType === 'opencode') {
-      return attempt('opencode', ['run', prompt]);
+  const attempts = agentAttempts(agentType, prompt, opts.schema);
+  let lastErr: any;
+  for (const a of attempts) {
+    try {
+      return exec(a.cmd, a.args, { timeout, maxBuffer });
+    } catch (err) {
+      lastErr = err; // try the next (fallback) form
     }
-    // pi (and any other): run as lean as possible so a bloated env can't hang it.
-    const piLean = ['--no-extensions', '--no-skills', '--no-prompt-templates', '--no-context-files', '--no-tools', '--no-session'];
+  }
+  throw wrapJudgeError(lastErr, agentType);
+}
+
+/**
+ * Non-blocking twin of {@link runAgentRaw}. Uses `execFile` (async) so the
+ * caller's event loop stays free — letting a spinner/progress UI animate while
+ * the judge (which can take minutes) runs. Prefer this in interactive commands.
+ */
+export async function runAgentRawAsync(prompt: string, opts: JudgeOptions = {}): Promise<string> {
+  const agentType = opts.agentType ?? getPrimaryAgent().type;
+  const timeout = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const maxBuffer = opts.maxBuffer ?? DEFAULT_MAX_BUFFER;
+  const exec =
+    opts.execAsync ??
+    (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);
+  let lastErr: any;
+  for (const a of attempts) {
     try {
-      return attempt('pi', [...piLean, '-p', prompt]);
-    } catch {
-      return attempt('pi', ['-p', prompt]);
+      return await exec(a.cmd, a.args, { timeout, maxBuffer });
+    } catch (err) {
+      lastErr = err; // try the next (fallback) form
     }
-  } catch (err: any) {
-    const detail = (err?.stderr || err?.stdout || err?.message || 'unknown error').toString().trim().slice(0, 500);
-    throw new Error(`agent judge failed (${agentType}): ${detail}`);
   }
+  throw wrapJudgeError(lastErr, agentType);
 }
 
 /**
@@ -77,6 +130,12 @@ export function runAgentJson(prompt: string, opts: JudgeOptions = {}): unknown {
   return parseAgentJson(raw);
 }
 
+/** Non-blocking twin of {@link runAgentJson}. */
+export async function runAgentJsonAsync(prompt: string, opts: JudgeOptions = {}): Promise<unknown> {
+  const raw = await runAgentRawAsync(prompt, opts);
+  return parseAgentJson(raw);
+}
+
 /** Extract a JSON object from an agent's raw stdout. Exported for tests. */
 export function parseAgentJson(raw: string): unknown {
   let text = raw.trim();

package/src/utils/reflect.ts

@@ -56,10 +56,14 @@ export interface ReflectionReport {
 
 // --------------------------------------------------------- transcript distill
 
-const MAX_PROMPTS = 25;
-const MAX_ERRORS = 25;
-const PROMPT_CHARS = 600;
-const ERROR_CHARS = 300;
+// Kept deliberately lean: the judge runs on the user's own (often local, slow)
+// agent, and a 10-workspace corpus at full verbosity produced a ~200KB prompt
+// that timed pi out. These bounds capture the pattern of a session at a
+// fraction of the tokens (~halving the prompt), so the judge actually finishes.
+const MAX_PROMPTS = 12;
+const MAX_ERRORS = 15;
+const PROMPT_CHARS = 400;
+const ERROR_CHARS = 200;
 
 /** Flatten a message `content` (string or content-block array) to plain text. */
 function contentToText(content: unknown): string {
@@ -251,13 +255,25 @@ async function contextFilesFor(workspacePath: string): Promise<string[]> {
   return present;
 }
 
+/** Fired as each workspace is read + distilled, so the CLI can show live,
+ *  per-workspace progress during the (I/O-bound) gather phase. */
+export interface ReflectProgress {
+  index: number;
+  total: number;
+  digest: WorkspaceDigest;
+}
+
 /**
  * Build the corpus the judge reasons over: the `limit` most **recently active**
  * workspaces (by their latest agent session, not creation date — a retrospective
  * is about recent *work*), each with its repos, context files, and distilled
- * session, plus the globally-available skills.
+ * session, plus the globally-available skills. `onProgress` (optional) fires
+ * once per workspace as it finishes, for a live progress display.
  */
-export async function gatherReflectionCorpus(limit: number): Promise<ReflectionCorpus> {
+export async function gatherReflectionCorpus(
+  limit: number,
+  onProgress?: (p: ReflectProgress) => void,
+): Promise<ReflectionCorpus> {
   const [sessions, workspaces, availableSkills] = await Promise.all([
     getWorkspaceSessions(), // already sorted by last-active, one per workspace
     listWorkspaces(false),
@@ -267,15 +283,18 @@ export async function gatherReflectionCorpus(limit: number): Promise<ReflectionC
   const recent = sessions.slice(0, limit);
 
   const digests: WorkspaceDigest[] = [];
-  for (const s of recent) {
+  for (let index = 0; index < recent.length; index++) {
+    const s = recent[index];
     const meta = metaByName.get(s.workspaceName);
-    digests.push({
+    const digest: WorkspaceDigest = {
       name: s.workspaceName,
       repoCount: meta?.metadata?.repositories?.length ?? 0,
       repos: (meta?.metadata?.repositories ?? []).map((r) => r.name),
       contextFiles: await contextFilesFor(s.workspacePath),
       session: await readDigestForSession(s),
-    });
+    };
+    digests.push(digest);
+    onProgress?.({ index, total: recent.length, digest });
   }
 
   return { generatedAt: new Date().toISOString(), availableSkills, workspaces: digests };