@xdelivered/emberflow 0.2.0 → 0.4.0

package/dist/server/subflowRunner.js

@@ -12,6 +12,11 @@ export const SUBFLOW_DEPTH_CAP = 8;
  */
 export function makeSubflowRunner(opts, ancestry) {
     return async (workflowId, input, callerNodeId) => {
+        // A cancelled stepped run's unwinding parents (their runSubflow was
+        // rejected) may retry: never push a new child that nothing will step.
+        if (opts.drill?.cancelled) {
+            return { status: 'failed', error: 'run cancelled' };
+        }
         if (ancestry.length >= SUBFLOW_DEPTH_CAP) {
             return { status: 'failed', error: `subflow depth cap (${SUBFLOW_DEPTH_CAP}) exceeded` };
         }
@@ -40,17 +45,39 @@ export function makeSubflowRunner(opts, ancestry) {
                 mocks: childFlow.mocks ?? {},
                 trace: opts.trace,
                 subflowRunner: makeSubflowRunner(opts, [...ancestry, workflowId]),
-                events: opts.onLog
+                events: opts.onLog || (opts.drill && opts.onNodeState)
                     ? {
-                        onLog: (line) => opts.onLog({
-                            ...line,
-                            nodeLabel: `${childFlow.name} › ${line.nodeLabel ?? ''}`,
-                            nodeId: line.nodeId ? `${callerNodeId}/${line.nodeId}` : callerNodeId,
-                        }),
+                        ...(opts.onLog
+                            ? {
+                                onLog: (line) => opts.onLog({
+                                    ...line,
+                                    nodeLabel: `${childFlow.name} › ${line.nodeLabel ?? ''}`,
+                                    nodeId: line.nodeId ? `${callerNodeId}/${line.nodeId}` : callerNodeId,
+                                }),
+                            }
+                            : {}),
+                        // Stepped children stream their node states into the ROOT
+                        // run's SSE stream, tagged with the child flow's id.
+                        ...(opts.drill && opts.onNodeState
+                            ? {
+                                onNodeStateChange: (nodeId, state) => opts.onNodeState(childFlow.id, nodeId, state),
+                            }
+                            : {}),
                     }
                     : undefined,
             });
-            const childRun = await childHandle.runToEnd();
+            // Stepped run: don't run the child here. Push it onto the shared drill
+            // stack and block this Subflow node until the registry's composite
+            // step() drives the child to completion and pops the entry — resolving
+            // with the completed child run, which flows into the exact same
+            // output-extraction / failure-mapping path runToEnd feeds today.
+            const childRun = opts.drill
+                ? await new Promise((resolve, reject) => {
+                    const entry = { handle: childHandle, workflowId, viaNodeId: callerNodeId, resolve, reject };
+                    opts.drill.stack.push(entry);
+                    opts.drill.onChildStarted?.(entry);
+                })
+                : await childHandle.runToEnd();
             if (childRun.status !== 'succeeded') {
                 // Surface the child's actual failure (e.g. the Mock-mode "would touch
                 // real infrastructure" boundary message) through the Subflow node's

package/dist/server/updateCheck.d.ts

@@ -0,0 +1,68 @@
+import { spawn } from 'node:child_process';
+/**
+ * Update notifier + installer plumbing for consumer projects (they install
+ * @xdelivered/emberflow from npm and run `npx emberflow dev`).
+ *
+ * - checkForUpdate: asks the npm registry for the latest published version and
+ *   compares it against the running one. Fail-SILENT by design: any network,
+ *   HTTP, or parse failure returns null — an update nudge must never break or
+ *   slow the studio. Results (including failures) are cached in-memory for an
+ *   hour so /update-status stays cheap and the registry isn't hammered.
+ * - runNpmInstall: the actual one-click updater — `npm install <pkg>@latest`
+ *   spawned (no shell) in the project root. Injectable spawn for tests.
+ */
+export declare const EMBERFLOW_PACKAGE = "@xdelivered/emberflow";
+export interface UpdateCheckResult {
+    current: string;
+    latest: string;
+    updateAvailable: boolean;
+}
+export interface CheckForUpdateOpts {
+    /** Registry base URL. Defaults to EMBERFLOW_REGISTRY env, then npmjs. */
+    registry?: string;
+    /** Cache TTL in ms (default 1h). */
+    ttlMs?: number;
+    /** Injectable clock for TTL tests. */
+    now?: () => number;
+    /** Injectable fetch for tests. */
+    fetchFn?: typeof fetch;
+}
+/** Test hook: clear the in-memory check cache. */
+export declare function resetUpdateCheckCache(): void;
+/**
+ * Latest-version check against the npm registry. Returns null when the check
+ * is disabled (EMBERFLOW_UPDATE_CHECK=0) or unavailable for ANY reason —
+ * never throws.
+ */
+export declare function checkForUpdate(currentVersion: string, opts?: CheckForUpdateOpts): Promise<UpdateCheckResult | null>;
+/**
+ * The running package's own version, read from its package.json. Two layouts,
+ * same probe as prompt.ts's EMBERFLOW_BIN: in the source repo this file is
+ * server/updateCheck.ts and the package root is one level up; in the shipped
+ * package it runs from dist/server/updateCheck.js and the root is two up.
+ */
+export declare function ownVersion(): string | null;
+/**
+ * True when the consumer's node_modules/@xdelivered/emberflow is a symlink —
+ * a `file:`/`npm link` dev setup that an npm install would clobber. POST
+ * /update refuses in that case.
+ */
+export declare function isLinkedInstall(projectRoot: string): boolean;
+export type InstallResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+export interface RunNpmInstallOpts {
+    /** Injectable spawner so tests never actually npm install. */
+    spawnFn?: typeof spawn;
+    /** Kill-and-fail deadline (default 5min). */
+    timeoutMs?: number;
+}
+/**
+ * Runs `npm install @xdelivered/emberflow@latest` in the project root via
+ * spawn (no shell). Captures the last ~4KB of combined output; on failure
+ * that tail is the error. Never rejects.
+ */
+export declare function runNpmInstall(projectRoot: string, opts?: RunNpmInstallOpts): Promise<InstallResult>;

package/dist/server/updateCheck.js

@@ -0,0 +1,142 @@
+import { spawn } from 'node:child_process';
+import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { newer } from './agents/detect.js';
+/**
+ * Update notifier + installer plumbing for consumer projects (they install
+ * @xdelivered/emberflow from npm and run `npx emberflow dev`).
+ *
+ * - checkForUpdate: asks the npm registry for the latest published version and
+ *   compares it against the running one. Fail-SILENT by design: any network,
+ *   HTTP, or parse failure returns null — an update nudge must never break or
+ *   slow the studio. Results (including failures) are cached in-memory for an
+ *   hour so /update-status stays cheap and the registry isn't hammered.
+ * - runNpmInstall: the actual one-click updater — `npm install <pkg>@latest`
+ *   spawned (no shell) in the project root. Injectable spawn for tests.
+ */
+export const EMBERFLOW_PACKAGE = '@xdelivered/emberflow';
+const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+const DEFAULT_TTL_MS = 60 * 60 * 1000; // 1h
+const INSTALL_TIMEOUT_MS = 5 * 60 * 1000; // 5min
+const OUTPUT_TAIL_BYTES = 4096;
+// Single-entry cache: the runner only ever checks one package/version pair.
+// Failures are cached too — a flaky network shouldn't retrigger a fetch on
+// every /update-status poll.
+let cache = null;
+/** Test hook: clear the in-memory check cache. */
+export function resetUpdateCheckCache() {
+    cache = null;
+}
+/**
+ * Latest-version check against the npm registry. Returns null when the check
+ * is disabled (EMBERFLOW_UPDATE_CHECK=0) or unavailable for ANY reason —
+ * never throws.
+ */
+export async function checkForUpdate(currentVersion, opts = {}) {
+    if (process.env.EMBERFLOW_UPDATE_CHECK === '0')
+        return null;
+    const now = opts.now ?? Date.now;
+    const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+    if (cache && now() - cache.at < ttlMs)
+        return cache.result;
+    const registry = opts.registry ?? process.env.EMBERFLOW_REGISTRY ?? DEFAULT_REGISTRY;
+    const fetchFn = opts.fetchFn ?? fetch;
+    let result = null;
+    try {
+        const res = await fetchFn(`${registry}/${EMBERFLOW_PACKAGE}/latest`);
+        if (res.ok) {
+            const body = (await res.json());
+            if (typeof body.version === 'string' && body.version.length > 0) {
+                result = {
+                    current: currentVersion,
+                    latest: body.version,
+                    updateAvailable: newer(body.version, currentVersion),
+                };
+            }
+        }
+    }
+    catch {
+        result = null; // fail-silent: network error, bad JSON, anything
+    }
+    cache = { at: now(), result };
+    return result;
+}
+/**
+ * The running package's own version, read from its package.json. Two layouts,
+ * same probe as prompt.ts's EMBERFLOW_BIN: in the source repo this file is
+ * server/updateCheck.ts and the package root is one level up; in the shipped
+ * package it runs from dist/server/updateCheck.js and the root is two up.
+ */
+export function ownVersion() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    for (const root of [resolve(here, '..'), resolve(here, '../..')]) {
+        const file = join(root, 'package.json');
+        if (!existsSync(file))
+            continue;
+        try {
+            const pkg = JSON.parse(readFileSync(file, 'utf8'));
+            if (typeof pkg.version === 'string')
+                return pkg.version;
+        }
+        catch {
+            // malformed — try the next candidate
+        }
+    }
+    return null;
+}
+/**
+ * True when the consumer's node_modules/@xdelivered/emberflow is a symlink —
+ * a `file:`/`npm link` dev setup that an npm install would clobber. POST
+ * /update refuses in that case.
+ */
+export function isLinkedInstall(projectRoot) {
+    try {
+        return lstatSync(join(projectRoot, 'node_modules', '@xdelivered', 'emberflow')).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Runs `npm install @xdelivered/emberflow@latest` in the project root via
+ * spawn (no shell). Captures the last ~4KB of combined output; on failure
+ * that tail is the error. Never rejects.
+ */
+export function runNpmInstall(projectRoot, opts = {}) {
+    const spawnFn = opts.spawnFn ?? spawn;
+    const timeoutMs = opts.timeoutMs ?? INSTALL_TIMEOUT_MS;
+    return new Promise((resolveInstall) => {
+        let tail = '';
+        const append = (chunk) => {
+            tail = (tail + String(chunk)).slice(-OUTPUT_TAIL_BYTES);
+        };
+        let child;
+        try {
+            child = spawnFn('npm', ['install', `${EMBERFLOW_PACKAGE}@latest`], {
+                cwd: projectRoot,
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+        }
+        catch (err) {
+            resolveInstall({ ok: false, error: err instanceof Error ? err.message : String(err) });
+            return;
+        }
+        child.stdout?.on('data', append);
+        child.stderr?.on('data', append);
+        let settled = false;
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolveInstall(result);
+        };
+        const timer = setTimeout(() => {
+            child.kill('SIGKILL');
+            settle({ ok: false, error: `npm install timed out after ${Math.round(timeoutMs / 1000)}s\n${tail}`.trim() });
+        }, timeoutMs);
+        child.on('error', (err) => settle({ ok: false, error: err.message }));
+        child.on('close', (code) => settle(code === 0 ? { ok: true } : { ok: false, error: tail.trim() || `npm install exited with code ${code}` }));
+    });
+}

package/dist/src/engine/executor.js

@@ -42,10 +42,11 @@ function envRefName(value) {
 function resolveEnvRef(name, vars) {
     if (!(name in vars)) {
         // The most common cause is not a missing key but a run with NO environment
-        // at all: the in-tab engine has no vars, so flows seeded with $env refs
-        // need the server runner. Say so, instead of a bare "missing".
+        // at all: an environment-less run (e.g. a scenario test) has no vars, so
+        // flows seeded with $env refs need a real environment. Say so, instead of a
+        // bare "missing".
         const hint = Object.keys(vars).length === 0
-            ? ' — this run has no environment variables (in-tab/browser runs never do; make sure the runner is online and the engine is set to Server or Auto)'
+            ? ' — this run has no environment variables; run it against an environment that defines them'
             : '';
         throw new Error(`Missing environment variable: ${name}${hint}`);
     }

package/package.json

@@ -1,16 +1,27 @@
 {
   "name": "@xdelivered/emberflow",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "Visual builder and runner for API operations modelled as node graphs, with scenarios, mocks and agent skills.",
-  "keywords": ["api", "workflow", "node-graph", "low-code", "visual-builder", "agent-skills"],
+  "keywords": [
+    "api",
+    "workflow",
+    "node-graph",
+    "low-code",
+    "visual-builder",
+    "agent-skills"
+  ],
   "license": "MIT",
-  "publishConfig": { "access": "public" },
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/pmccurley87/emberflow.git"
   },
-  "bin": { "emberflow": "bin/emberflow.mjs" },
+  "bin": {
+    "emberflow": "bin/emberflow.mjs"
+  },
   "exports": {
     ".": {
       "types": "./dist/src/config.d.ts",
@@ -25,7 +36,15 @@
       "default": "./dist/server/environments.js"
     }
   },
-  "files": ["bin", "server", "src", "dist", "studio-dist", "templates", "README.md"],
+  "files": [
+    "bin",
+    "server",
+    "src",
+    "dist",
+    "studio-dist",
+    "templates",
+    "README.md"
+  ],
   "scripts": {
     "dev": "vite",
     "build": "tsc -b && vite build",
@@ -73,7 +92,9 @@
     "tsx": "^4.22.5"
   },
   "peerDependenciesMeta": {
-    "tsx": { "optional": true }
+    "tsx": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/express": "^5.0.6",

package/server/agentRoute.test.ts

@@ -124,6 +124,26 @@ describe('POST /agent — setup-environments route validation', () => {
   });
 });
 
+describe('POST /agent — guided-setup route validation', () => {
+  it('accepts a guided-setup intent WITHOUT flowId or environment (instruction-only, like setup-environments)', async () => {
+    const res = await postAgentWhenFree({ intent: { action: 'guided-setup', instruction: 'dev and prod please' } });
+    expect(res.status).toBe(201);
+    const body = await res.json();
+    expect(typeof body.agentRunId).toBe('string');
+    expect(body.agentRunId.length).toBeGreaterThan(0);
+  });
+
+  it('accepts a guided-setup intent with an empty instruction (the no-notes start)', async () => {
+    const res = await postAgentWhenFree({ intent: { action: 'guided-setup', instruction: '' } });
+    expect(res.status).toBe(201);
+  });
+
+  it('400s a guided-setup intent with no instruction field', async () => {
+    const res = await postAgent({ intent: { action: 'guided-setup' } });
+    expect(res.status).toBe(400);
+  });
+});
+
 /** The run manager is single-flight per project (409 while a previous stub run
  *  winds down) — retry briefly so route-validation asserts don't race it. */
 async function postAgentWhenFree(body: unknown): Promise<Response> {

package/server/agents/codexParse.test.ts

@@ -55,4 +55,41 @@ describe('parseCodexLine', () => {
     expect(parseCodexLine('')).toBeNull();
     expect(parseCodexLine('not json')).toBeNull();
   });
+
+  // Captured live from codex 0.142.5 rejecting the default model: the failure
+  // arrives as a top-level `error` line + a terminal `turn.failed`, both with
+  // the human-readable cause double-encoded as JSON-in-a-string. Unhandled,
+  // the adapter could only report a generic "codex exited with code 1".
+  const REJECTION =
+    '{"type":"error","status":400,"error":{"type":"invalid_request_error","message":"The \'gpt-5.6-sol\' model requires a newer version of Codex. Please upgrade to the latest app or CLI and try again."}}';
+
+  it('maps turn.failed to a terminal error with the inner message unwrapped and the stale-CLI hint', () => {
+    const line = JSON.stringify({ type: 'turn.failed', error: { message: REJECTION } });
+    const event = parseCodexLine(line);
+    expect(event?.type).toBe('error');
+    const text = (event as { text: string }).text;
+    expect(text).toContain("The 'gpt-5.6-sol' model requires a newer version of Codex");
+    expect(text).toContain('hint: your codex CLI may be too old');
+  });
+
+  it('maps a top-level error line to a non-terminal ⚠ message with the inner message unwrapped', () => {
+    const line = JSON.stringify({ type: 'error', message: REJECTION });
+    const event = parseCodexLine(line);
+    expect(event?.type).toBe('message');
+    expect((event as { text: string }).text).toContain(
+      "⚠ The 'gpt-5.6-sol' model requires a newer version of Codex",
+    );
+  });
+
+  it('turn.failed with a plain (non-JSON) message passes it through verbatim', () => {
+    const line = JSON.stringify({ type: 'turn.failed', error: { message: 'boom' } });
+    expect(parseCodexLine(line)).toEqual({ type: 'error', text: 'boom' });
+  });
+
+  it('turn.failed with no error payload still terminates with a generic message', () => {
+    expect(parseCodexLine('{"type":"turn.failed"}')).toEqual({
+      type: 'error',
+      text: 'codex turn failed',
+    });
+  });
 });

package/server/agents/codexParse.ts

@@ -1,4 +1,5 @@
 import type { AgentEvent } from './types';
+import { modelRejectionHint } from './modelRejectionHint';
 
 interface CodexCommandExecutionItem {
   type: 'command_execution';
@@ -55,6 +56,24 @@ interface CodexLine {
   type: string;
   item?: CodexItem;
   usage?: Record<string, number>;
+  message?: string;
+  error?: { message?: string };
+}
+
+/**
+ * Codex wraps API failures as JSON-in-a-string: `turn.failed`'s error.message
+ * (and top-level `error`'s message) is often itself a serialized
+ * `{"type":"error","status":400,"error":{"message":"…"}}` payload. Dig out the
+ * innermost human-readable message, falling back to the raw string.
+ */
+function extractCodexErrorMessage(raw: string | undefined): string {
+  if (!raw) return 'codex turn failed';
+  try {
+    const inner = JSON.parse(raw) as { error?: { message?: string }; message?: string };
+    return inner.error?.message ?? inner.message ?? raw;
+  } catch {
+    return raw;
+  }
 }
 
 export function parseCodexLine(line: string): AgentEvent | null {
@@ -120,6 +139,21 @@ export function parseCodexLine(line: string): AgentEvent | null {
     case 'turn.completed':
       return { type: 'done', usage: parsed.usage };
 
+    // The turn itself failed (e.g. the API rejected the request) — this IS the
+    // run failing, unlike an `error` ITEM above. Codex exits 1 after emitting
+    // it; without handling it here the adapter can only synthesize a generic
+    // "codex exited with code 1" and the real cause stays buried.
+    case 'turn.failed': {
+      const text = extractCodexErrorMessage(parsed.error?.message);
+      const hint = modelRejectionHint('codex', text);
+      return { type: 'error', text: hint ? `${text} (${hint})` : text };
+    }
+
+    // Top-level `error` lines precede turn.failed with the same payload —
+    // surface as a visible diagnostic, let turn.failed be the terminal event.
+    case 'error':
+      return { type: 'message', text: `⚠ ${extractCodexErrorMessage(parsed.message)}` };
+
     default:
       return null;
   }

package/server/agents/detect.test.ts

@@ -7,19 +7,19 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const fixture = (name: string) => path.join(__dirname, '__fixtures__', name);
 
 describe('detectAgents', () => {
-  it('returns only the CLIs the injected probe reports as present, with parsed versions', () => {
+  it('returns only the CLIs the injected probe reports as present, with parsed versions and the bin', () => {
     expect(detectAgents((bin) => (bin === 'codex' ? { version: '0.142.5' } : undefined))).toEqual([
-      { kind: 'codex', version: '0.142.5' },
+      { kind: 'codex', version: '0.142.5', bin: 'codex' },
     ]);
     expect(detectAgents((bin) => (bin === 'claude' ? { version: '1.2.3' } : undefined))).toEqual([
-      { kind: 'claude', version: '1.2.3' },
+      { kind: 'claude', version: '1.2.3', bin: 'claude' },
     ]);
   });
 
   it('returns both when both are present', () => {
-    expect(detectAgents(() => ({ version: '1.0.0' }))).toEqual([
-      { kind: 'codex', version: '1.0.0' },
-      { kind: 'claude', version: '1.0.0' },
+    expect(detectAgents((bin) => (bin === 'codex' || bin === 'claude' ? { version: '1.0.0' } : undefined))).toEqual([
+      { kind: 'codex', version: '1.0.0', bin: 'codex' },
+      { kind: 'claude', version: '1.0.0', bin: 'claude' },
     ]);
   });
 
@@ -29,10 +29,29 @@ describe('detectAgents', () => {
 
   it('reports null version when present but the output has no parseable semver token', () => {
     expect(detectAgents((bin) => (bin === 'codex' ? { version: null } : undefined))).toEqual([
-      { kind: 'codex', version: null },
+      { kind: 'codex', version: null, bin: 'codex' },
     ]);
   });
 
+  it('picks the NEWEST version across candidate locations, not the PATH shim', () => {
+    // PATH `codex` is pinned old; the ChatGPT.app bundle is newer — the bundle wins.
+    const versions: Record<string, string> = {
+      codex: '0.142.5',
+      '/Applications/ChatGPT.app/Contents/Resources/codex': '0.156.0',
+    };
+    const found = detectAgents((bin) => (versions[bin] ? { version: versions[bin] } : undefined));
+    expect(found).toEqual([
+      { kind: 'codex', version: '0.156.0', bin: '/Applications/ChatGPT.app/Contents/Resources/codex' },
+    ]);
+  });
+
+  it('a parseable version beats a null one regardless of probe order', () => {
+    const found = detectAgents((bin) =>
+      bin === 'codex' ? { version: null } : bin === '/opt/homebrew/bin/codex' ? { version: '0.1.0' } : undefined,
+    );
+    expect(found).toEqual([{ kind: 'codex', version: '0.1.0', bin: '/opt/homebrew/bin/codex' }]);
+  });
+
   it('defaults to a real PATH probe that returns an array', () => {
     expect(Array.isArray(detectAgents())).toBe(true);
   });

package/server/agents/detect.ts

@@ -1,20 +1,40 @@
 import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
 import type { AgentKind } from './types';
 
-const CANDIDATES: AgentKind[] = ['codex', 'claude'];
-
 const VERSION_RE = /\d+\.\d+\.\d+/;
 
+/**
+ * Where each agent CLI may live, beyond whatever PATH resolves. PATH shims can
+ * pin an OLD version (e.g. a superset-managed ~/.superset/bin/codex frozen at
+ * a release the API no longer accepts) while a newer binary sits elsewhere —
+ * so we probe every known location and pick the NEWEST, never just the first.
+ */
+const CANDIDATE_BINS: Record<AgentKind, string[]> = {
+  codex: [
+    'codex', // PATH resolution (may be a pinned shim)
+    join(homedir(), '.local', 'bin', 'codex'),
+    '/opt/homebrew/bin/codex',
+    '/usr/local/bin/codex',
+    // The ChatGPT desktop app bundles its own codex, updated with the app.
+    '/Applications/ChatGPT.app/Contents/Resources/codex',
+  ],
+  claude: ['claude', join(homedir(), '.local', 'bin', 'claude'), '/opt/homebrew/bin/claude', '/usr/local/bin/claude'],
+};
+
 export interface DetectedAgent {
   kind: AgentKind;
   version: string | null;
+  /** The concrete binary the newest version was found at — what spawns should use. */
+  bin: string;
 }
 
 /**
- * Real PATH probe: runs `<bin> --version` and parses the first semver-ish
- * token out of stdout. Returns `undefined` when the binary isn't present/
- * runnable (spawn error, timeout, or nonzero exit); `null` version when it
- * ran but produced no parseable version string.
+ * Real probe: runs `<bin> --version` and parses the first semver-ish token out
+ * of stdout. Returns `undefined` when the binary isn't present/runnable (spawn
+ * error, timeout, or nonzero exit); `null` version when it ran but produced no
+ * parseable version string.
  */
 export function probe(bin: string): { version: string | null } | undefined {
   const result = spawnSync(bin, ['--version'], {
@@ -27,17 +47,65 @@ export function probe(bin: string): { version: string | null } | undefined {
   return { version: match ? match[0] : null };
 }
 
+/** Numeric segment compare; a parseable version always beats null.
+ *  Shared: agent-CLI detection here, and the package update check
+ *  (server/updateCheck.ts) both rank semver-ish strings with it. */
+export function newer(a: string | null, b: string | null): boolean {
+  if (a === null) return false;
+  if (b === null) return true;
+  const as = a.split('.').map(Number);
+  const bs = b.split('.').map(Number);
+  for (let i = 0; i < Math.max(as.length, bs.length); i++) {
+    const d = (as[i] ?? 0) - (bs[i] ?? 0);
+    if (d !== 0) return d > 0;
+  }
+  return false;
+}
+
 /**
- * Detects which coding-agent CLIs are available on PATH, and the version
- * each reports (null when present but unparseable). `probeBin` is
- * injectable so tests can stub PATH presence/version without shelling out
- * for real binaries.
+ * Detects which coding-agent CLIs are available — probing PATH plus the known
+ * install locations for each kind — and keeps the NEWEST version found per
+ * kind, with the binary path it came from. `probeBin` is injectable so tests
+ * can stub presence/version per location without shelling out.
  */
-export function detectAgents(probeBin: (bin: string) => { version: string | null } | undefined = probe): DetectedAgent[] {
+export function detectAgents(
+  probeBin: (bin: string) => { version: string | null } | undefined = probe,
+): DetectedAgent[] {
   const found: DetectedAgent[] = [];
-  for (const kind of CANDIDATES) {
-    const result = probeBin(kind);
-    if (result) found.push({ kind, version: result.version });
+  for (const kind of Object.keys(CANDIDATE_BINS) as AgentKind[]) {
+    let best: DetectedAgent | undefined;
+    const seen = new Set<string>();
+    for (const bin of CANDIDATE_BINS[kind]) {
+      if (seen.has(bin)) continue;
+      seen.add(bin);
+      const result = probeBin(bin);
+      if (!result) continue;
+      if (!best || newer(result.version, best.version)) {
+        best = { kind, version: result.version, bin };
+      }
+    }
+    if (best) found.push(best);
   }
   return found;
 }
+
+// Probing every candidate spawns several subprocesses; /setup-status and
+// /agent/available are polled by the studio, so cache briefly.
+const RESOLVE_TTL_MS = 30_000;
+let cachedAt = 0;
+let cached: DetectedAgent[] | null = null;
+
+/** Cached detection — the newest binary per kind, refreshed every 30s. */
+export function detectAgentsCached(): DetectedAgent[] {
+  const now = Date.now();
+  if (!cached || now - cachedAt > RESOLVE_TTL_MS) {
+    cached = detectAgents();
+    cachedAt = now;
+  }
+  return cached;
+}
+
+/** The concrete binary path spawns should use for `kind` — the newest found. */
+export function resolveAgentBin(kind: AgentKind): string | undefined {
+  return detectAgentsCached().find((a) => a.kind === kind)?.bin;
+}

package/server/agents/modelRejectionHint.ts

@@ -1,6 +1,7 @@
 import type { AgentKind } from './types';
 
-const MODEL_REJECTION_RE = /unknown model|unsupported model|invalid model|model.*not.*(found|supported)/i;
+const MODEL_REJECTION_RE =
+  /unknown model|unsupported model|invalid model|model.*not.*(found|supported)|model requires a newer version/i;
 
 /**
  * When an agent CLI exits nonzero without ever emitting a terminal `done`,