agentproc 0.3.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentproc",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "AgentProc Protocol SDK + CLI for Node.js — connect any Agent CLI to a messaging platform",
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -8,7 +8,7 @@
     "agentproc": "src/cli.js"
   },
   "scripts": {
-    "test": "node --test src/index.test.js src/runner.test.js"
+    "test": "node --test src/index.test.js src/runner.test.js src/hub.test.js src/conformance.test.js"
   },
   "keywords": ["agentproc", "agent", "bridge", "protocol", "cli", "ai", "runner"],
   "license": "MIT",

package/src/cli.js

@@ -1,12 +1,17 @@
 #!/usr/bin/env node
 'use strict';
 /**
- * agentproc CLI — run any AgentProc profile against a message.
+ * agentproc CLI — drive any AgentProc profile against a message.
  *
- * Usage:
+ * Quick start (hub):
+ *   agentproc hub list
+ *   agentproc hub run echo-agent -p "hello"
+ *   cd ~/projects/my-app && agentproc hub run claude-code -p "explain this"
+ *
+ * Advanced (local profile YAML, no hub fetch):
  *   agentproc --profile <path.yaml> --prompt "hello" [options]
  *
- * Options:
+ * Options (local-profile mode):
  *   --profile, -p <path>      Profile YAML path (required)
  *   --prompt <text>           User message (required, unless --stdin)
  *   --session <id>            Previous session id for multi-turn
@@ -119,9 +124,51 @@ async function runHubSubcommand(args) {
     return 0;
   }
 
-  // Parse common flags
+  // Any subcommand with --help/-h shows the hub help (covers `hub run --help`,
+  // `hub install --help`, etc. — useful for muscle-memory discovery).
+  if (rest.includes('--help') || rest.includes('-h')) {
+    showHubHelp();
+    return 0;
+  }
+
+  // Parse hub args. We can't reuse parseArgs() here because it throws on
+  // any unknown `--flag`, and hub supports `--refresh` which the runner
+  // parser doesn't know about. Instead, walk the args ourselves, separating
+  // hub-level flags (--refresh, --help) from runner-level flags (-p/--prompt,
+  // --cwd, --env, ...) and positional args (the profile name).
   const refresh = rest.includes('--refresh');
-  const positional = rest.filter(a => !a.startsWith('--'));
+  const positional = [];
+  const runnerArgs = [];
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === '--refresh' || a === '-h' || a === '--help') continue;
+    // Runner flags that take a value (next arg): match both long and short.
+    // In the `hub run` context, `-p` means `--prompt` (the profile name is
+    // positional, not a path), so we normalize it before handing off.
+    const takesValue =
+      a === '--prompt' || a === '-p' ||
+      a === '--session' || a === '--session-name' || a === '--from' ||
+      a === '--cwd' || a === '--env' || a === '--timeout';
+    if (takesValue) {
+      runnerArgs.push(a === '-p' ? '--prompt' : a);
+      if (i + 1 < rest.length) runnerArgs.push(rest[++i]);
+      continue;
+    }
+    // Other known runner flags (boolean).
+    if (a === '--no-stream' || a === '--verbose' || a === '--quiet' ||
+        a === '--raw' || a === '--stdin') {
+      runnerArgs.push(a);
+      continue;
+    }
+    // Anything else starting with - or -- is unknown to us — surface it
+    // as an explicit error instead of silently treating it as a positional.
+    if (a.startsWith('-')) {
+      process.stderr.write(`error: unknown option: ${a}\n\n`);
+      showHubHelp();
+      return 2;
+    }
+    positional.push(a);
+  }
 
   if (sub === 'list') {
     const profiles = await hub.listProfiles({
@@ -157,10 +204,16 @@ async function runHubSubcommand(args) {
       return 2;
     }
     const target = process.cwd();
-    await hub.installProfile(positional[0], target, {
+    const dest = await hub.installProfile(positional[0], target, {
       refresh,
       onLog: m => process.stderr.write(m + '\n'),
     });
+    // After-the-fact hint: tell the user exactly what they got and how to
+    // run it. Without this, "installed to: ./echo-agent/" leaves them
+    // guessing what to type next.
+    process.stderr.write(`\n`);
+    process.stderr.write(`Next: edit ${path.relative(target, path.join(dest, 'profile.yaml'))} if you want, then run:\n`);
+    process.stderr.write(`  agentproc --profile ${path.relative(target, path.join(dest, 'profile.yaml'))} --prompt "hi" --cwd <your-project>\n`);
     return 0;
   }
 
@@ -176,13 +229,21 @@ async function runHubSubcommand(args) {
     });
     const profilePath = path.join(cacheDir, 'profile.yaml');
 
-    // Re-parse the remaining args as the runner options (--prompt, --cwd, etc.).
-    const { opts: runOpts } = parseArgs(rest);
+    // Parse the runner-level flags we separated out above.
+    const { opts: runOpts } = parseArgs(runnerArgs);
     if (!runOpts.prompt && !runOpts.stdin) {
       process.stderr.write('error: hub run requires --prompt <text> or --stdin\n');
       return 2;
     }
 
+    // hub run uses the user's current directory as the agent's cwd when
+    // --cwd is not given. This matches the hub docs ("uses your current
+    // directory as cwd") and is the right default for AI-CLI profiles
+    // where the agent should operate on the user's project.
+    if (!runOpts.cwd) {
+      runOpts.cwd = process.cwd();
+    }
+
     return await runAgent(profilePath, runOpts);
   }
 
@@ -231,6 +292,7 @@ Profiles are cached at ~/.agentproc/cache/hub/<name>/ (24h TTL).
  */
 async function runAgent(profilePath, opts) {
   let profileRaw;
+  const profileDir = path.dirname(path.resolve(profilePath));
   try {
     const yamlText = fs.readFileSync(path.resolve(profilePath), 'utf8');
     profileRaw = parseYaml(yamlText);
@@ -270,6 +332,7 @@ async function runAgent(profilePath, opts) {
       fromUser: opts.from || '',
       streaming,
       cwd: opts.cwd,
+      profileDir,
       extraEnv,
       timeoutSecs: opts.timeout,
     });
@@ -278,7 +341,8 @@ async function runAgent(profilePath, opts) {
     return r.exitCode === 0 ? 0 : 1;
   }
 
-  const verbose = opts.verbose || !opts.quiet || (opts.verbose === undefined && opts.quiet === undefined) || opts.verbose;
+  // verbose: default true, --verbose keeps it true, --quiet sets it false.
+  const verbose = opts.verbose !== false;
 
   const r = await runner.run(profileRaw, {
     message: prompt,
@@ -287,6 +351,7 @@ async function runAgent(profilePath, opts) {
     fromUser: opts.from || '',
     streaming,
     cwd: opts.cwd,
+    profileDir,
     extraEnv,
     timeoutSecs: opts.timeout,
     onPartial: (t) => { if (verbose) process.stderr.write(`AGENT_PARTIAL:${JSON.stringify(t)}\n`); },
@@ -307,6 +372,27 @@ async function runAgent(profilePath, opts) {
 function showHelp() {
   process.stdout.write(`agentproc v${PKG_VERSION} (protocol ${PROTOCOL_VERSION})
 
+The fastest way in:
+  agentproc hub list                          # see what's available
+  agentproc hub run echo-agent -p "hello"     # smoke test (no API key)
+  cd ~/projects/my-app && agentproc hub run claude-code -p "explain this"
+
+The CLI fetches the profile from the GitHub hub on first use, caches it at
+~/.agentproc/cache/hub/<name>/ (24h TTL), and uses your current directory as
+the agent's cwd. Set GITHUB_TOKEN to raise the rate limit (see \`agentproc hub --help\`).
+
+Hub subcommands:
+  hub list                          List all profiles in the hub
+  hub show <name>                   Show a profile's README
+  hub run <name> [run-options]      Fetch (if needed) and run a profile
+  hub install <name>                Copy a profile to the current directory
+
+Run \`agentproc hub --help\` for the full hub reference.
+
+───────────────────────────────────────────────────────────────────────────────
+
+Advanced: run a local profile YAML directly (no hub fetch)
+
 Usage:
   agentproc --profile <path.yaml> --prompt "hello" [options]
 
@@ -320,7 +406,8 @@ Session:
   --from <user>             Sender identifier
 
 Execution:
-  --cwd <path>              Override profile.cwd
+  --cwd <path>              Override profile.cwd (relative paths resolve
+                            against the profile.yaml's directory)
   --env KEY=VALUE           Extra env var (repeatable)
   --timeout <secs>          Override profile.timeout_secs
   --no-stream               Set AGENT_STREAMING=0
@@ -343,9 +430,16 @@ Output semantics:
 The final session id is printed on stderr as: agentproc:session:<id>
 
 Examples:
-  agentproc --profile hub/echo-agent/profile.yaml --prompt "hi"
-  agentproc -p hub/claude-code/profile.yaml --prompt "hello" --verbose
-  cat prompt.txt | agentproc -p prof.yaml --stdin
+  # Local profile (relative cwd resolves next to profile.yaml):
+  agentproc --profile ./hub/echo-agent/profile.yaml --prompt "hi"
+
+  # Local claude-code profile, claude runs against your project:
+  agentproc --profile ./hub/claude-code/profile.yaml \\
+            --prompt "explain this codebase" \\
+            --cwd /path/to/your/project
+
+  # Prompt from stdin:
+  cat prompt.txt | agentproc --profile prof.yaml --stdin
 `);
 }
 
@@ -624,10 +718,35 @@ async function main() {
 
 // Run main() only when invoked directly as a script, not when required for tests.
 if (require.main === module) {
-  main().catch(e => {
-    process.stderr.write(`[agentproc] unhandled error: ${e && (e.stack || e)}\n`);
-    process.exit(1);
-  });
+  main().then(
+    (code) => {
+      // main() returns an explicit exit code from its various return paths;
+      // honor it so shell scripts can distinguish success from failure.
+      process.exit(typeof code === 'number' ? code : 0);
+    },
+    (e) => {
+      // Friendly handling for known hub errors: print the message + remediation
+      // hint, never a raw Node stack trace.
+      if (e && e.name === 'HubError') {
+        process.stderr.write(`error: ${e.message}\n`);
+        if (e.hint) process.stderr.write(`\n${e.hint}\n`);
+        process.exit(1);
+        return;
+      }
+      // For fetch() network errors wrapped by hub.js (also HubError, but be
+      // defensive in case some path throws a plain TypeError from fetch).
+      if (e && typeof e.message === 'string' && /fetch failed|ENOTFOUND|ECONNREFUSED|ECONNRESET/.test(e.message)) {
+        process.stderr.write(`error: network error talking to GitHub: ${e.message}\n`);
+        process.stderr.write(`\nThis is usually transient. Re-run the command, or run against a local checkout:\n`);
+        process.stderr.write(`  agentproc --profile ./hub/<name>/profile.yaml --prompt "hi"\n`);
+        process.exit(1);
+        return;
+      }
+      // Everything else: still avoid dumping the stack. Show the message only.
+      process.stderr.write(`error: ${e && (e.message || e)}\n`);
+      process.exit(1);
+    }
+  );
 }
 
 module.exports = { parseArgs, parseYaml, showHelp, main };

package/src/conformance.test.js

@@ -0,0 +1,29 @@
+'use strict';
+/**
+ * Cross-implementation conformance tests.
+ *
+ * Drives the shared `spec/conformance/cases.json` fixture through the Node
+ * runner's `classifyLine` and asserts the result matches the expected
+ * {kind, value}. The Python SDK runs the same fixture through its
+ * `classify_line` in `sdk/python/tests/test_conformance.py` — together they
+ * guarantee the two reference implementations classify stdout identically.
+ *
+ * When you change the spec's line-recognition rules, add a case to the JSON
+ * file first; both SDKs will fail until they agree.
+ */
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { classifyLine } = require('./runner.js');
+
+const CASES_PATH = path.resolve(__dirname, '../../../spec/conformance/cases.json');
+const data = JSON.parse(fs.readFileSync(CASES_PATH, 'utf8'));
+
+for (const c of data.cases) {
+  test(`classifyLine: ${c.line.slice(0, 60)}`, () => {
+    assert.deepStrictEqual(classifyLine(c.line), c.expect);
+  });
+}

package/src/hub.js

@@ -74,36 +74,170 @@ function writeCacheMeta(name) {
 // HTTP helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * Custom error type for hub fetch failures. Carries a short, user-facing
+ * `hint` with remediation, so the CLI can print something helpful instead
+ * of a raw Node stack trace.
+ */
+class HubError extends Error {
+  constructor(message, { hint = '', cause = null, status = 0 } = {}) {
+    super(message);
+    this.name = 'HubError';
+    this.hint = hint;
+    this.status = status;
+    if (cause) this.cause = cause;
+  }
+}
+
+function authHeaders({ json = false } = {}) {
+  // Optional: an explicit token raises GitHub's anonymous rate limit from
+  // 60 req/hour to 5,000. We accept either GITHUB_TOKEN (the env var GitHub
+  // Actions injects) or GH_TOKEN (what `gh` CLI users typically have).
+  const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN || '';
+  const h = { 'User-Agent': 'agentproc-cli' };
+  if (json) h.Accept = 'application/vnd.github+json';
+  if (token) h.Authorization = `Bearer ${token}`;
+  return h;
+}
+
 async function httpGetJson(url) {
-  const r = await fetch(url, {
-    headers: {
-      Accept: 'application/vnd.github+json',
-      'User-Agent': 'agentproc-cli',
-    },
-  });
+  let r;
+  try {
+    r = await fetch(url, { headers: authHeaders({ json: true }) });
+  } catch (e) {
+    throw new HubError(
+      `could not reach GitHub while fetching hub profile`,
+      {
+        status: 0,
+        cause: e,
+        hint: [
+          'This is usually a transient network issue. Try:',
+          '  1. Re-run the command (often succeeds on retry).',
+          '  2. If your network requires a proxy, set HTTPS_PROXY.',
+          '  3. To avoid the network entirely, run against a local checkout:',
+          '       agentproc --profile ./hub/<name>/profile.yaml --prompt "hi"',
+        ].join('\n'),
+      }
+    );
+  }
   if (!r.ok) {
     const text = await r.text().catch(() => '');
-    throw new Error(`GitHub API ${r.status}: ${text.slice(0, 200)}`);
+    if (r.status === 403 || r.status === 429) {
+      const authed = !!(process.env.GITHUB_TOKEN || process.env.GH_TOKEN);
+      throw new HubError(
+        `GitHub rate-limited the hub fetch (HTTP ${r.status})`,
+        {
+          status: r.status,
+          hint: authed
+            ? [
+              'Your GITHUB_TOKEN is set but still rate-limited. Wait a few minutes and retry,',
+              'or run against a local checkout instead:',
+              '  agentproc --profile ./hub/<name>/profile.yaml --prompt "hi"',
+              '',
+              `Not sure the profile name is right? Check with: agentproc hub list`,
+            ].join('\n')
+            : [
+              'GitHub limits anonymous hub fetches to ~60/hour. To raise this to 5,000/hour:',
+              '  export GITHUB_TOKEN=$(gh auth token)   # if you have the GitHub CLI',
+              '  # or set GITHUB_TOKEN to any personal access token',
+              '',
+              'To skip the network entirely, run against a local checkout:',
+              '  git clone https://github.com/jeffkit/agentproc && cd agentproc',
+              '  agentproc --profile ./hub/<name>/profile.yaml --prompt "hi"',
+              '',
+              `Not sure the profile name is right? Check with: agentproc hub list`,
+            ].join('\n'),
+        }
+      );
+    }
+    if (r.status === 404) {
+      throw new HubError(`profile not found on GitHub (HTTP 404)`, {
+        status: 404,
+        hint: 'Check the profile name with `agentproc hub list`. (Typos are case-sensitive.)',
+      });
+    }
+    throw new HubError(`GitHub returned HTTP ${r.status} for hub fetch`, {
+      status: r.status,
+      hint: text.slice(0, 200) || 'No additional detail from GitHub.',
+    });
   }
   return r.json();
 }
 
 async function httpGetText(url) {
-  const r = await fetch(url, { headers: { 'User-Agent': 'agentproc-cli' } });
+  const r = await fetch(url, { headers: authHeaders({ json: false }) });
+  if (!r.ok) {
+    // raw.githubusercontent.com is essentially unrate-limited; a failure
+    // here is more likely a genuine 404 (profile file missing) than 403.
+    throw new HubError(`fetch failed (HTTP ${r.status}) for ${url}`, {
+      status: r.status,
+      hint: 'Profile files should exist in the hub repo. Try `agentproc hub list` to verify.',
+    });
+  }
+  return r.text();
+}
+
+/**
+ * Like httpGetText, but returns null on 404 instead of throwing. Used for
+ * probing optional profile files (e.g. bridge.sh only exists for echo-agent)
+ * and for detecting "profile does not exist" without burning an API call.
+ */
+async function httpGetTextOptional(url) {
+  const r = await fetch(url, { headers: authHeaders({ json: false }) });
+  if (r.status === 404) return null;
   if (!r.ok) {
-    throw new Error(`fetch ${r.status}: ${url}`);
+    throw new HubError(`fetch failed (HTTP ${r.status}) for ${url}`, {
+      status: r.status,
+      hint: 'Profile files should exist in the hub repo. Try `agentproc hub list` to verify.',
+    });
   }
   return r.text();
 }
 
 /**
  * Fetch the entire repo tree (1 API call, returns all paths under hub/).
- * Cached in memory for the lifetime of the process.
+ * Cached two ways: in-memory for the lifetime of the process, and on disk
+ * at ~/.agentproc/cache/hub/tree.json with the same 24h TTL as profiles.
+ *
+ * The disk cache is the important one for rate-limit relief: the GitHub
+ * Trees API is the single call that rate-limits anonymous users to ~60/hr,
+ * and every CLI invocation is a fresh process (so the in-memory cache never
+ * survives). With the disk cache, a normal user makes at most ~1 Trees API
+ * call per day regardless of how many `hub list` / `hub run` they run.
  * @returns {Promise<Array<{path: string, type: 'blob'|'tree'}>>}
  */
 let _treeCache = null;
+
+function treeCachePath() {
+  return path.join(cacheRoot(), 'tree.json');
+}
+
+function clearTreeCache() {
+  _treeCache = null;
+  const p = treeCachePath();
+  if (fs.existsSync(p)) {
+    try { fs.unlinkSync(p); } catch { /* best effort */ }
+  }
+}
+
 async function getTree() {
   if (_treeCache) return _treeCache;
+
+  const tp = treeCachePath();
+  if (fs.existsSync(tp)) {
+    try {
+      const meta = JSON.parse(fs.readFileSync(tp, 'utf8'));
+      const age = Math.max(0, Date.now() / 1000 - (meta.fetched_at || 0));
+      if (age < HUB_CACHE_TTL_SECS && Array.isArray(meta.tree)) {
+        _treeCache = meta.tree.map((e) => ({
+          path: String((e && e.path) || ''),
+          type: String((e && e.type) || ''),
+        }));
+        return _treeCache;
+      }
+    } catch { /* corrupt cache file — refetch */ }
+  }
+
   const data = await httpGetJson(GITHUB_TREES);
   if (!data || !Array.isArray(data.tree)) {
     throw new Error('unexpected tree API response');
@@ -114,6 +248,16 @@ async function getTree() {
       path: String(e.path || ''),
       type: String(e.type || ''),  // 'blob' or 'tree'
     }));
+
+  fs.mkdirSync(cacheRoot(), { recursive: true });
+  try {
+    fs.writeFileSync(tp, JSON.stringify({
+      fetched_at: Date.now() / 1000,
+      ref: HUB_REF,
+      tree: _treeCache,
+    }), 'utf8');
+  } catch { /* disk cache is best-effort */ }
+
   return _treeCache;
 }
 
@@ -145,34 +289,104 @@ async function listRemoteFiles(subpath) {
 }
 
 /**
- * List actual files inside a hub/<name>/ directory.
- * @param {string} name
- * @returns {Promise<Array<{name: string, path: string}>>}
+ * List top-level profile names (the directories directly under hub/).
+ * Cheap: uses the same disk-cached tree as getTree(), so calling this
+ * after listRemoteFiles does not cost an extra API request.
+ * @returns {Promise<string[]>}
  */
-async function listRemoteProfileFiles(name) {
-  const prefix = `hub/${name}/`;
+async function listProfileNames() {
   const tree = await getTree();
-  return tree
-    .filter((e) => e.type === 'blob' && e.path.startsWith(prefix))
-    .map((e) => ({
-      name: e.path.slice(prefix.length).split('/').pop(),
-      path: e.path,
-    }));
+  const seen = new Set();
+  for (const e of tree) {
+    if (!e.path.startsWith('hub/')) continue;
+    const seg = e.path.slice('hub/'.length).split('/')[0];
+    // Directories prefixed with `_` (e.g. `_shared`) hold bridge utilities,
+    // not profiles — exclude them from listings and "did you mean" suggestions.
+    if (seg && !seg.startsWith('_') && !seen.has(seg)) seen.add(seg);
+  }
+  return [...seen].sort();
 }
 
-async function downloadFile(remotePath, localPath) {
-  const text = await httpGetText(GITHUB_RAW(remotePath));
-  fs.mkdirSync(path.dirname(localPath), { recursive: true });
-  fs.writeFileSync(localPath, text, 'utf8');
+/**
+ * Lightweight "did you mean" hint using edit distance + prefix matching.
+ * Returns the best candidate name, or '' if none is close enough.
+ *
+ * Two paths to a match:
+ *   1. Prefix match — `claude` matches `claude-code`, `echo` matches
+ *      `echo-agent`. This is the common typo pattern (user forgot a suffix).
+ *      Only accepts an unambiguous prefix — if multiple candidates share
+ *      the prefix, none is returned (better no suggestion than a wrong one).
+ *   2. Edit distance — tolerate ~1/3 of the input length in edits. Catches
+ *      transpositions (`calude`) and small typos (`coudex` → `codex`).
+ */
+function suggestCloseName(input, candidates) {
+  if (!input || !candidates || candidates.length === 0) return '';
+
+  const n = input.toLowerCase();
+
+  // Path 1: unique prefix match.
+  const prefixMatches = candidates.filter(c => c.toLowerCase().startsWith(n));
+  if (prefixMatches.length === 1) return prefixMatches[0];
+
+  // Path 2: edit distance. Threshold scales with input length:
+  //   - short (≤6): allow 1 edit (typos in `agy`, `codex`)
+  //   - medium (7-12): allow 2 edits (transpositions in `calude-code`)
+  //   - long (>12): allow 3 edits
+  const threshold = input.length <= 6 ? 1 : input.length <= 12 ? 2 : 3;
+  let best = '';
+  let bestDist = Infinity;
+  for (const c of candidates) {
+    const dist = editDistance(n, c.toLowerCase());
+    if (dist < bestDist) { bestDist = dist; best = c; }
+  }
+  if (best && bestDist <= threshold) return best;
+  return '';
+}
+
+function editDistance(a, b) {
+  const m = a.length, n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  const prev = new Array(n + 1);
+  const curr = new Array(n + 1);
+  for (let j = 0; j <= n; j++) prev[j] = j;
+  for (let i = 1; i <= m; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(
+        prev[j] + 1,        // deletion
+        curr[j - 1] + 1,    // insertion
+        prev[j - 1] + cost  // substitution
+      );
+    }
+    for (let j = 0; j <= n; j++) prev[j] = curr[j];
+  }
+  return prev[n];
 }
 
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
 
+// Every hub profile is this fixed set of files (see hub/README.md):
+//   profile.yaml (required) + bridge.py + bridge.js + README.md,
+// with echo-agent additionally shipping bridge.sh. We fetch them directly
+// via raw.githubusercontent.com (CDN, not rate-limited) so `hub run` never
+// calls the GitHub Trees API in the happy path. If a future profile adds a
+// new file type, extend this list.
+const PROFILE_FILE_CANDIDATES = [
+  'profile.yaml', 'bridge.py', 'bridge.js', 'bridge.sh', 'README.md',
+];
+
 /**
  * Fetch a profile directory to local cache. Returns the cache path.
  *
+ * Fetches files directly via raw.githubusercontent.com (CDN, not
+ * rate-limited) — no GitHub Trees API call in the happy path. Only an
+ * unknown profile name (profile.yaml 404) falls back to the disk-cached
+ * tree to produce a "did you mean" suggestion.
+ *
  * @param {string} name
  * @param {{refresh?: boolean, onLog?: function(string): void}} [opts]
  * @returns {Promise<string>} absolute cache path
@@ -180,9 +394,8 @@ async function downloadFile(remotePath, localPath) {
 async function fetchProfile(name, opts = {}) {
   const { refresh = false, onLog = null } = opts;
 
-  // On refresh, also clear the in-memory tree cache so we see new files
-  // (e.g. profiles added since the process started).
-  if (refresh) _treeCache = null;
+  // On refresh, clear the tree cache so we see newly-added profiles.
+  if (refresh) clearTreeCache();
 
   const age = cacheAgeSecs(name);
   const dir = cacheDir(name);
@@ -201,21 +414,41 @@ async function fetchProfile(name, opts = {}) {
     }
   }
 
-  const entries = await listRemoteProfileFiles(name);
-  if (entries.length === 0) {
-    throw new Error(`profile '${name}' not found in hub`);
+  // Probe profile.yaml via raw URL. raw.githubusercontent.com is CDN-backed
+  // and not subject to the 60/hr anonymous API limit, so this does not burn
+  // rate-limit budget.
+  const probe = await httpGetTextOptional(GITHUB_RAW(`hub/${name}/profile.yaml`));
+  if (probe === null) {
+    // profile.yaml 404 → the name is wrong. Fall back to the (disk-cached)
+    // tree to produce a "did you mean" suggestion. This is the only path
+    // that may call the Trees API for `hub run`, and it's cached for 24h.
+    const known = await listProfileNames();
+    const suggestion = suggestCloseName(name, known);
+    const hint = suggestion
+      ? [`Did you mean \`${suggestion}\`?`, '', 'Available profiles:', ...known.map(n => `  - ${n}`)].join('\n')
+      : ['Available profiles:', ...known.map(n => `  - ${n}`)].join('\n');
+    throw new HubError(`profile '${name}' not found in hub`, {
+      status: 404,
+      hint,
+    });
   }
 
-  // Clear cache, then re-download every file in the profile directory.
+  // Clear cache, then download the candidate file set via raw URLs.
   if (fs.existsSync(dir)) {
     fs.rmSync(dir, { recursive: true, force: true });
   }
   fs.mkdirSync(dir, { recursive: true });
 
-  for (const entry of entries) {
-    const local = path.join(dir, entry.name);
-    await downloadFile(entry.path, local);
-    if (onLog) onLog(`  - ${entry.name}`);
+  // profile.yaml already fetched via the probe.
+  fs.writeFileSync(path.join(dir, 'profile.yaml'), probe, 'utf8');
+  if (onLog) onLog(`  - profile.yaml`);
+
+  for (const fname of PROFILE_FILE_CANDIDATES) {
+    if (fname === 'profile.yaml') continue;
+    const text = await httpGetTextOptional(GITHUB_RAW(`hub/${name}/${fname}`));
+    if (text === null) continue;  // optional file not present for this profile
+    fs.writeFileSync(path.join(dir, fname), text, 'utf8');
+    if (onLog) onLog(`  - ${fname}`);
   }
 
   writeCacheMeta(name);
@@ -235,6 +468,9 @@ async function listProfiles(opts = {}) {
   for (const entry of entries) {
     if (entry.type !== 'dir') continue;
     const name = entry.name;
+    // Skip utility directories like `_shared/` — they hold shared bridge
+    // helpers, not a runnable profile (no profile.yaml).
+    if (name.startsWith('_')) continue;
     try {
       const yamlText = await httpGetText(GITHUB_RAW(`hub/${name}/profile.yaml`));
       const { parseYaml } = require('./cli.js');
@@ -300,9 +536,11 @@ module.exports = {
   HUB_REPO,
   HUB_REF,
   HUB_CACHE_TTL_SECS,
+  HubError,
   cacheRoot,
   cacheDir,
   cacheAgeSecs,
+  clearTreeCache,
   fetchProfile,
   listProfiles,
   showReadme,

package/src/hub.test.js

@@ -23,6 +23,10 @@ const hub = require('./hub.js');
 
 const FAKE_TREE = [
   { path: 'hub', type: 'tree' },
+  { path: 'hub/_shared', type: 'tree' },
+  { path: 'hub/_shared/stream_utils.py', type: 'blob' },
+  { path: 'hub/_shared/stream_utils.js', type: 'blob' },
+  { path: 'hub/_shared/README.md', type: 'blob' },
   { path: 'hub/echo-agent', type: 'tree' },
   { path: 'hub/echo-agent/profile.yaml', type: 'blob' },
   { path: 'hub/echo-agent/bridge.py', type: 'blob' },
@@ -105,7 +109,11 @@ function installFakeFetch(tree = FAKE_TREE, contents = FAKE_FILE_CONTENTS) {
         return { ok: true, text: async () => content };
       }
     }
-    throw new Error(`unexpected text URL: ${url}`);
+    // Unmatched raw URL → 404. This is now legitimate: `hub run` probes a
+    // fixed candidate file set via raw URLs, and optional files (e.g.
+    // bridge.sh on a non-echo profile) or a wrong profile name legitimately
+    // 404 without burning GitHub's rate-limited Trees API.
+    return { ok: false, status: 404, text: async () => '' };
   };
   counter.restore = () => { global.fetch = orig; };
   return counter;
@@ -179,6 +187,35 @@ describe('hub', { concurrency: false }, () => {
       }
     });
 
+    test('happy path does not call the rate-limited Trees API', async () => {
+      // `hub run` fetches profile files via raw.githubusercontent.com (CDN,
+      // not rate-limited). A known profile must not trigger any api.github.com
+      // call — that's the whole point of the rate-limit fix.
+      const counter = installFakeFetch();
+      try {
+        await hub.fetchProfile('echo-agent');
+        assert.strictEqual(counter.json, 0);
+      } finally {
+        counter.restore();
+      }
+    });
+
+    test('skips optional files that 404 (e.g. bridge.sh on claude-code)', async () => {
+      const counter = installFakeFetch();
+      try {
+        const dir = await hub.fetchProfile('claude-code');
+        const names = fs.readdirSync(dir);
+        assert.ok(names.includes('profile.yaml'));
+        assert.ok(names.includes('bridge.py'));
+        assert.ok(names.includes('bridge.js'));
+        assert.ok(names.includes('README.md'));
+        // claude-code has no bridge.sh — the 404 is swallowed, not stored.
+        assert.ok(!names.includes('bridge.sh'));
+      } finally {
+        counter.restore();
+      }
+    });
+
     test('unknown profile raises', async () => {
       const counter = installFakeFetch([{ path: 'hub', type: 'tree' }]);
       try {
@@ -205,9 +242,11 @@ describe('hub', { concurrency: false }, () => {
       const counter = installFakeFetch();
       try {
         await hub.fetchProfile('echo-agent');
-        const first = counter.json;
+        const firstText = counter.text;
         await hub.fetchProfile('echo-agent', { refresh: true });
-        assert.ok(counter.json > first);
+        // hub run fetches files via raw URLs (CDN), not the rate-limited
+        // Trees API — so a refresh re-fetches the file set, not the tree.
+        assert.ok(counter.text > firstText);
       } finally {
         counter.restore();
       }
@@ -245,6 +284,38 @@ describe('hub', { concurrency: false }, () => {
         counter.restore();
       }
     });
+
+    test('skips underscore-prefixed utility dirs like _shared', async () => {
+      // _shared/ has no profile.yaml; it must not appear in the listing and
+      // must not trigger a "could not read metadata" warning/fetch.
+      const counter = installFakeFetch();
+      try {
+        const profiles = await hub.listProfiles({ refresh: true });
+        const names = profiles.map(p => p.name);
+        assert.ok(!names.some(n => n.startsWith('_')),
+          `utility dir leaked into listing: ${names}`);
+      } finally {
+        counter.restore();
+      }
+    });
+
+    test('disk-caches the tree so repeat calls skip the Trees API', async () => {
+      // The first listProfiles hits the Trees API (counter.json 0→1) and
+      // writes ~/.agentproc/cache/hub/tree.json. A second call in the same
+      // process reuses the cached tree and must not make another API call.
+      const counter = installFakeFetch();
+      try {
+        hub.clearTreeCache();  // reset in-memory + disk from prior tests
+        await hub.listProfiles();
+        assert.strictEqual(counter.json, 1);
+        const treeCache = path.join(hub.cacheRoot(), 'tree.json');
+        assert.ok(fs.existsSync(treeCache), 'tree.json not written to disk');
+        await hub.listProfiles();
+        assert.strictEqual(counter.json, 1, 'second call hit the Trees API again');
+      } finally {
+        counter.restore();
+      }
+    });
   });
 
   // ----- showReadme -----

package/src/runner.js

@@ -4,7 +4,7 @@
  * protocol-compliant agent invocation.
  *
  * This module is the canonical implementation of the AgentProc bridge-side
- * contract (spec/protocol.md). The CLI (cli.js) is a thin wrapper around it.
+ * contract (spec/protocol.md, wire protocol 0.1). The CLI (cli.js) is a thin wrapper around it.
  *
  * Responsibilities:
  *   - Parse and validate a profile object
@@ -26,6 +26,7 @@
  */
 
 const { spawn } = require('node:child_process');
+const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
 
@@ -74,17 +75,43 @@ function normalizeProfile(raw) {
     throw new Error('profile.command must be a non-empty string');
   }
 
-  // Split command into argv on whitespace, no shell (per spec).
-  const argv = p.command.trim().split(/\s+/);
-  if (argv.length === 0) {
+  // Per spec: `command` is argv[0]; `args` is argv[1..]. Two mutually
+  // exclusive forms:
+  //   (a) `args` absent + command has whitespace → split command into argv
+  //       (the legacy shorthand: `command: python3 ./bridge.py`)
+  //   (b) `args` present (even empty `[]`) → command is a single token,
+  //       never split. Lets paths with spaces stay whole:
+  //         command: "/path with spaces/my agent"
+  //         args: []
+  // `args: []` (explicit empty array) is DISTINCT from "args absent": the
+  // explicit form means "do not split command"; the absent form falls back
+  // to the whitespace-splitting shorthand.
+  const argsFieldPresent = raw.agentproc
+    ? (Object.prototype.hasOwnProperty.call(raw.agentproc, 'args') && raw.agentproc.args != null)
+    : (Object.prototype.hasOwnProperty.call(raw, 'args') && raw.args != null);
+  const argv = argsFieldPresent ? [p.command.trim()] : p.command.trim().split(/\s+/);
+  if (argv.length === 0 || argv[0] === '') {
     throw new Error('profile.command produced empty argv');
   }
 
+  // env_allowlist (optional): when present, ${VAR} references in the env
+  // block whose name is NOT in the list expand to empty + a stderr warning.
+  // Absent ⇒ current behaviour (expand against the full bridge environment).
+  // Opt-in: existing profiles keep working unchanged.
+  let envAllowlist = null;
+  if (p.env_allowlist !== undefined && p.env_allowlist !== null) {
+    if (!Array.isArray(p.env_allowlist)) {
+      throw new Error('profile.env_allowlist must be a list');
+    }
+    envAllowlist = new Set(p.env_allowlist.map(String));
+  }
+
   return {
     argv,
     args: Array.isArray(p.args) ? p.args.map(String) : [],
     cwd: p.cwd ? expandPath(String(p.cwd)) : undefined,
     env: p.env && typeof p.env === 'object' ? p.env : {},
+    env_allowlist: envAllowlist,
     stdin: p.stdin === 'message' ? 'message' : 'none',
     timeout_secs: Number.isFinite(p.timeout_secs) ? p.timeout_secs : DEFAULT_TIMEOUT_SECS,
     kill_grace_secs: Number.isFinite(p.kill_grace_secs) ? p.kill_grace_secs : DEFAULT_KILL_GRACE_SECS,
@@ -100,22 +127,147 @@ function expandPath(p) {
 }
 
 /**
- * Substitute {{MESSAGE}}, {{SESSION_ID}}, {{SESSION_NAME}} placeholders
- * in a string value. Per spec, no shell is involved.
+ * Best-effort pattern check against the agent's accumulated stderr to spot
+ * common "bridge file not found" / "module not found" failures that the
+ * wrapped interpreter writes to its own stderr before exiting non-zero.
+ * Returns a human-friendly hint, or '' if nothing recognizable.
+ *
+ * This is intentionally narrow — we only flag high-confidence patterns to
+ * avoid mis-diagnosing genuine agent errors.
+ */
+function diagnoseStderrFailure(stderrText, { argv }) {
+  if (!stderrText) return '';
+  const lower = stderrText.toLowerCase();
+
+  // python3: "can't open file '/path/x.py': [Errno 2] No such file or directory"
+  // Also covers "cannot open file" (localized variants).
+  const pyMatch = stderrText.match(/(?:can'?t|cannot) open file '([^']+)': \[Errno 2\] No such file or directory/);
+  if (pyMatch) {
+    const file = pyMatch[1];
+    return `agent script not found: ${file}. Check the profile's command path (likely a {{PROFILE_DIR}} issue or a typo).`;
+  }
+
+  // node: "Error: Cannot find module '/path/x.js'"
+  const nodeMatch = stderrText.match(/Cannot find module '([^']+)'/);
+  if (nodeMatch) {
+    const mod = nodeMatch[1];
+    return `agent script not found: ${mod}. Check the profile's command path (likely a {{PROFILE_DIR}} issue or a typo).`;
+  }
+
+  // bash: "bash: line N: ./x.sh: No such file or directory"
+  const bashMatch = stderrText.match(/(?:^|\n)[^:]+: line \d+: ([^:]+): No such file or directory/);
+  if (bashMatch) {
+    const file = bashMatch[1];
+    return `agent script not found: ${file}. Check the profile's command path.`;
+  }
+
+  // Generic Errno 2 sentinel, in case the interpreter phrasing differs.
+  if (/errno 2|enoent|no such file or directory/.test(lower)) {
+    return `agent reported a missing file. Check the profile's command and cwd.`;
+  }
+
+  return '';
+}
+
+/**
+ * Produce a human-friendly hint for a spawn ENOENT-style error.
+ *
+ * Node's spawn attributes the error to argv[0] regardless of whether it was
+ * the command itself or a referenced file (e.g. `./bridge.py`) that wasn't
+ * found, which is very confusing. We inspect cwd + argv to give a better
+ * diagnosis. Returns '' when nothing useful can be said.
+ */
+function diagnoseSpawnError(err, { argv, cwd, env }) {
+  const code = err && err.code;
+  const message = (err && err.message) || '';
+  if (code !== 'ENOENT' && !/ENOENT/.test(message)) return '';
+
+  // (a) cwd doesn't exist or isn't a directory
+  if (cwd) {
+    try {
+      const stat = fs.statSync(cwd);
+      if (!stat.isDirectory()) {
+        return `profile.cwd is not a directory: ${cwd}`;
+      }
+    } catch (e) {
+      if (e && (e.code === 'EACCES' || e.code === 'EPERM')) {
+        return `profile.cwd is not accessible (permission denied): ${cwd}`;
+      }
+      return `profile.cwd does not exist: ${cwd}. Pass --cwd <path> to point at a real directory.`;
+    }
+  }
+
+  // (b) the command (argv[0]) is not on PATH
+  const cmd = argv[0];
+  const isPathed = /[\\/]/.test(cmd);
+  if (!isPathed) {
+    // Bare command like 'python3' or 'claude' — check PATH ourselves.
+    const PATH = (env && env.PATH) || '';
+    if (PATH) {
+      const found = PATH.split(path.delimiter).some(d => {
+        try {
+          const p = path.join(d, cmd);
+          fs.accessSync(p, fs.constants.X_OK);
+          return true;
+        } catch { return false; }
+      });
+      if (!found) {
+        return `'${cmd}' not found on PATH. Install it, or if it's installed, make sure PATH is set correctly when the bridge spawns the agent.`;
+      }
+    }
+    return `'${cmd}' could not be executed. Verify it is installed and on PATH.`;
+  }
+
+  // (c) argv[0] looks like a path — check whether the file itself exists
+  try {
+    fs.accessSync(cmd, fs.constants.X_OK);
+  } catch {
+    return `command path does not exist or is not executable: ${cmd}`;
+  }
+
+  // (d) Command exists; suspect an argv file argument (e.g. python3 ./bridge.py).
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith('-') && (a.includes('/') || a.includes('\\'))) {
+      // Resolve relative to cwd (mirrors spawn's resolution)
+      const resolved = path.isAbsolute(a) ? a : (cwd ? path.resolve(cwd, a) : path.resolve(a));
+      try {
+        fs.accessSync(resolved, fs.constants.R_OK);
+      } catch {
+        return `argument file not found: ${a} (resolved to ${resolved}). The profile likely needs --cwd or the bundled script path is wrong.`;
+      }
+    }
+  }
+
+  return '';
+}
+
+/**
+ * Substitute {{MESSAGE}}, {{SESSION_ID}}, {{SESSION_NAME}}, {{PROFILE_DIR}}
+ * placeholders in a string value. Per spec, no shell is involved.
  */
 function substitute(value, ctx) {
   return String(value)
     .replace(/\{\{MESSAGE\}\}/g, ctx.message || '')
     .replace(/\{\{SESSION_ID\}\}/g, ctx.sessionId || '')
-    .replace(/\{\{SESSION_NAME\}\}/g, ctx.sessionName || '');
+    .replace(/\{\{SESSION_NAME\}\}/g, ctx.sessionName || '')
+    .replace(/\{\{PROFILE_DIR\}\}/g, ctx.profileDir || '');
 }
 
 /**
- * Expand ${VAR} references against process.env, like a typical shell would.
+ * Expand ${VAR} references against `env`, like a typical shell would.
  * Unknown variables expand to empty string (POSIX sh behavior).
+ *
+ * When `allowlist` is a Set of names, references to names NOT in the set
+ * expand to empty and `onBlocked` (if given) is called with each blocked
+ * name. When `allowlist` is null, all references expand normally.
  */
-function expandEnvRef(value, env) {
+function expandEnvRef(value, env, allowlist = null, onBlocked = null) {
   return String(value).replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, name) => {
+    if (allowlist && !allowlist.has(name)) {
+      if (onBlocked) onBlocked(name);
+      return '';
+    }
     const v = env[name];
     return v !== undefined ? v : '';
   });
@@ -132,13 +284,18 @@ function expandEnvRef(value, env) {
 function decodeJsonValue(raw) {
   const text = raw.trim();
   if (text === '') return '';
+  let v;
   try {
-    const v = JSON.parse(text);
-    return typeof v === 'string' ? v : String(v);
+    v = JSON.parse(text);
   } catch {
     // Lenient: treat as plain string.
     return text;
   }
+  // Only JSON strings are meaningful payloads — a sentinel's value is text
+  // for the user. Non-string JSON (number/bool/null/array/object) means the
+  // agent misused the API; fall back to the raw text so the result is
+  // language-independent (String(true) != str(True) across runtimes).
+  return typeof v === 'string' ? v : text;
 }
 
 /**
@@ -211,17 +368,28 @@ async function run(profileRaw, options) {
   const sessionName = options.sessionName || 'default';
   const streaming = options.streaming !== undefined ? !!options.streaming : profile.streaming;
   const timeoutSecs = options.timeoutSecs !== undefined ? options.timeoutSecs : profile.timeout_secs;
-  const cwd = options.cwd || profile.cwd;
+  let cwd = options.cwd || profile.cwd;
+  // Resolve relative cwd against the profile's directory (if known) so that
+  // profiles written as `cwd: .` work no matter where the user invokes from.
+  // Absolute paths and `~`-prefixed paths are already absolute post-expand.
+  if (cwd && !path.isAbsolute(cwd) && options.profileDir) {
+    cwd = path.resolve(options.profileDir, cwd);
+  }
 
   // Build the substitution context for {{MESSAGE}} etc.
+  // {{PROFILE_DIR}} resolves to the directory the profile YAML lives in
+  // (passed by the CLI; undefined when run programmatically without it),
+  // letting profiles reference bundled scripts via absolute paths while
+  // still allowing the agent's cwd to be anywhere.
   const substCtx = {
     message: options.message,
     sessionId,
     sessionName,
+    profileDir: options.profileDir || '',
   };
 
   // Build argv: command + args (with placeholders substituted).
-  const argv = [...profile.argv];
+  const argv = profile.argv.map(a => substitute(a, substCtx));
   for (const a of profile.args) {
     argv.push(substitute(a, substCtx));
   }
@@ -229,8 +397,13 @@ async function run(profileRaw, options) {
   // Build env: start with process.env (so PATH etc. work), add profile.env
   // (with ${VAR} refs expanded against process.env), then add AGENT_* vars.
   const env = { ...process.env };
+  const allowlist = profile.env_allowlist;
   for (const [k, v] of Object.entries(profile.env)) {
-    env[k] = expandEnvRef(substitute(v, substCtx), process.env);
+    env[k] = expandEnvRef(substitute(v, substCtx), process.env, allowlist, (name) => {
+      if (options.onStderr) {
+        options.onStderr(`[agentproc runner] env_allowlist blocked \${${name}} (not in allowlist); expanded to empty`);
+      }
+    });
   }
   if (options.extraEnv) {
     for (const [k, v] of Object.entries(options.extraEnv)) {
@@ -303,8 +476,23 @@ async function run(profileRaw, options) {
 
   // ---- stderr: forward as debug ----
   let stderrBuf = '';
+  // Two views on stderr:
+  //   - stderrWindow: bounded sliding window (8 KB) — reserved for future
+  //     UI/display use so a noisy agent cannot exhaust memory.
+  //   - stderrFull:   unbounded capture used for post-mortem pattern
+  //     diagnosis. Without the full text, a chatty agent can push the real
+  //     error out of the window and the friendly hint goes missing.
+  let stderrWindow = '';
+  let stderrFull = '';
+  const STDERR_CAP = 8192;
   child.stderr.on('data', chunk => {
-    stderrBuf += chunk.toString();
+    const text = chunk.toString();
+    stderrBuf += text;
+    stderrFull += text;
+    stderrWindow += text;
+    if (stderrWindow.length > STDERR_CAP) {
+      stderrWindow = stderrWindow.slice(stderrWindow.length - STDERR_CAP);
+    }
     let nl;
     while ((nl = stderrBuf.indexOf('\n')) >= 0) {
       const line = stderrBuf.slice(0, nl);
@@ -320,6 +508,11 @@ async function run(profileRaw, options) {
   }
 
   // ---- timeout handling per spec: SIGTERM → grace → SIGKILL ----
+  // On POSIX, child.kill('SIGTERM') is a real signal the agent can trap and
+  // flush; on Windows, Node translates any signal name to TerminateProcess,
+  // so the grace period is effectively a no-op there. The two-step shape is
+  // preserved so POSIX behaviour is correct; Windows callers get a hard kill
+  // at the deadline (acceptable per the spec's Windows caveat).
   let timer = null;
   if (timeoutSecs > 0) {
     timer = setTimeout(() => {
@@ -340,8 +533,20 @@ async function run(profileRaw, options) {
   const exitCode = await new Promise(resolve => {
     child.on('close', code => resolve(code));
     child.on('error', err => {
-      // spawn error (ENOENT etc.)
-      if (options.onStderr) options.onStderr(`[agentproc runner] spawn error: ${err.message}`);
+      // spawn error — usually ENOENT. Node attributes it to argv[0]
+      // regardless of whether it was the command or a referenced file that
+      // wasn't found, so disambiguate for the user.
+      const tip = diagnoseSpawnError(err, { argv, cwd, env });
+      if (options.onStderr) {
+        options.onStderr(`[agentproc runner] spawn error: ${err.message}`);
+        if (tip) options.onStderr(`[agentproc runner] hint: ${tip}`);
+      }
+      // Surface as an AGENT_ERROR so the user sees it on the bridge too.
+      if (options.onError) {
+        const msg = tip || err.message;
+        options.onError(`failed to start agent: ${msg}`);
+      }
+      if (!result.error) result.error = tip || err.message;
       resolve(EXIT_ERROR);
     });
   });
@@ -353,7 +558,23 @@ async function run(profileRaw, options) {
     handleLine(stdoutBuf.replace(/\r$/, ''));
   }
 
-  // Compose reply body.
+  // Flush any remaining stderr (the chunk handler only emits on newlines).
+  if (stderrBuf.length > 0) {
+    if (options.onStderr) options.onStderr(stderrBuf.replace(/\r$/, ''));
+  }
+
+  // If the agent exited non-zero with no AGENT_ERROR, peek at its stderr for
+  // common "command/file not found" patterns and surface a friendly hint.
+  // Uses the FULL stderr — a noisy agent can fill the 8 KB window with
+  // progress junk before the real error lands at the end.
+  if (!killed && !result.error && exitCode !== 0) {
+    const hint = diagnoseStderrFailure(stderrFull, { argv });
+    if (hint) {
+      result.error = hint;
+      if (options.onError) options.onError(hint);
+    }
+  }
+
   result.reply = bodyLines.join('\n');
   if (result.reply.length > profile.max_reply_chars) {
     const suffix = profile.max_reply_chars === DEFAULT_MAX_REPLY_CHARS