@xdelivered/emberflow 0.2.0 → 0.5.0

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/dist/src/engine/registry.d.ts

@@ -3,10 +3,30 @@ export interface RegisteredNode {
     definition: NodeDefinition;
     implementation: NodeImplementation;
 }
+/** Where a node was registered from: absolute file path + 1-based line of the register() call. */
+export interface SourceRef {
+    file: string;
+    line?: number;
+}
+export interface RegisterOptions {
+    /** Explicit provenance escape hatch — wins over automatic capture. */
+    sourceRef?: SourceRef;
+}
 export declare class NodeRegistry {
     nodes: Map<string, RegisteredNode>;
     sources: Map<string, string>;
-    register(definition: NodeDefinition, implementation: NodeImplementation): void;
+    /** Registration provenance per node type. Populated only when capture is on or opts.sourceRef given. */
+    sourceRefs: Map<string, SourceRef>;
+    /** Types the RUNNER flagged builtin (registered from the package, not the project). */
+    builtinTypes: Set<string>;
+    /** Automatic caller capture is opt-in (server registries only) so browser registries never pay/leak. */
+    private captureSourceRefs;
+    constructor(opts?: {
+        captureSourceRefs?: boolean;
+    });
+    register(definition: NodeDefinition, implementation: NodeImplementation, opts?: RegisterOptions): void;
+    /** Where `type` was registered from, when known. */
+    getSourceRef(type: string): SourceRef | undefined;
     get(type: string): RegisteredNode;
     has(type: string): boolean;
     /**
@@ -17,13 +37,18 @@ export declare class NodeRegistry {
      * process restart (which would kill in-flight agent runs).
      */
     adopt(other: NodeRegistry): void;
+    /** Whether the runner flagged `type` as a package built-in (no servable source file). */
+    isBuiltin(type: string): boolean;
     list(): NodeDefinition[];
     /**
      * Register a definition-only node (metadata fetched from the runner). Its
      * implementation is a stub that fails loudly if browser-executed — such
      * nodes run on the server. Never overwrites a real registration.
      */
-    registerDefinition(definition: NodeDefinition, source?: string): void;
+    registerDefinition(definition: NodeDefinition, source?: string, opts?: {
+        sourceRef?: SourceRef;
+        builtin?: boolean;
+    }): void;
     /** Source text for display: stored source for definition-only nodes, else the impl's toString(). */
     getSource(type: string): string | undefined;
     /**

package/dist/src/engine/registry.js

@@ -1,11 +1,78 @@
+/**
+ * Read the CALLER's file:line via a one-frame V8 stack capture.
+ * `Error.prepareStackTrace` is swapped for the duration of a single `new
+ * Error()` and restored in `finally`, so source-map hooks installed by
+ * tsx/vitest are back in place immediately. Frames arrive either as
+ * `file:///abs/path.ts` URLs (ESM) or plain absolute paths (CJS/transpilers);
+ * both normalize to a plain path. Returns undefined on any non-V8 runtime or
+ * anonymous/eval frames — capture is best-effort by design.
+ */
+function captureCallerSourceRef(skip) {
+    if (typeof Error.captureStackTrace !== 'function')
+        return undefined;
+    const original = Error.prepareStackTrace;
+    try {
+        Error.prepareStackTrace = (_err, frames) => frames;
+        const holder = {};
+        Error.captureStackTrace(holder, skip);
+        const frames = holder.stack;
+        if (!Array.isArray(frames) || frames.length === 0)
+            return undefined;
+        const frame = frames[0];
+        const raw = typeof frame.getFileName === 'function' ? frame.getFileName() : undefined;
+        if (typeof raw !== 'string' || raw.length === 0)
+            return undefined;
+        const lineRaw = typeof frame.getLineNumber === 'function' ? frame.getLineNumber() : undefined;
+        const line = typeof lineRaw === 'number' && lineRaw > 0 ? lineRaw : undefined;
+        let file = raw;
+        if (file.startsWith('file://')) {
+            // No node:url here (browser-safe module): URL parsing covers the
+            // file:///abs/path form these frames take on POSIX platforms.
+            try {
+                file = decodeURIComponent(new URL(file).pathname);
+            }
+            catch {
+                return undefined;
+            }
+        }
+        // Loaders (vite-node hot imports) may suffix ?t=... cache-busters.
+        const q = file.indexOf('?');
+        if (q !== -1)
+            file = file.slice(0, q);
+        return line !== undefined ? { file, line } : { file };
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        Error.prepareStackTrace = original;
+    }
+}
 export class NodeRegistry {
     nodes = new Map();
     sources = new Map();
-    register(definition, implementation) {
+    /** Registration provenance per node type. Populated only when capture is on or opts.sourceRef given. */
+    sourceRefs = new Map();
+    /** Types the RUNNER flagged builtin (registered from the package, not the project). */
+    builtinTypes = new Set();
+    /** Automatic caller capture is opt-in (server registries only) so browser registries never pay/leak. */
+    captureSourceRefs;
+    constructor(opts) {
+        this.captureSourceRefs = opts?.captureSourceRefs ?? false;
+    }
+    register(definition, implementation, opts) {
         if (this.nodes.has(definition.type)) {
             throw new Error(`Node type already registered: ${definition.type}`);
         }
         this.nodes.set(definition.type, { definition, implementation });
+        const ref = opts?.sourceRef ??
+            (this.captureSourceRefs ? captureCallerSourceRef(this.register) : undefined);
+        if (ref)
+            this.sourceRefs.set(definition.type, ref);
+    }
+    /** Where `type` was registered from, when known. */
+    getSourceRef(type) {
+        return this.sourceRefs.get(type);
     }
     get(type) {
         const node = this.nodes.get(type);
@@ -26,6 +93,12 @@ export class NodeRegistry {
     adopt(other) {
         this.nodes = other.nodes;
         this.sources = other.sources;
+        this.sourceRefs = other.sourceRefs;
+        this.builtinTypes = other.builtinTypes;
+    }
+    /** Whether the runner flagged `type` as a package built-in (no servable source file). */
+    isBuiltin(type) {
+        return this.builtinTypes.has(type);
     }
     list() {
         return [...this.nodes.values()].map((n) => n.definition);
@@ -35,7 +108,14 @@ export class NodeRegistry {
      * implementation is a stub that fails loudly if browser-executed — such
      * nodes run on the server. Never overwrites a real registration.
      */
-    registerDefinition(definition, source) {
+    registerDefinition(definition, source, opts) {
+        // Provenance is recorded even for already-registered types: the studio's
+        // bundled built-ins are real registrations, and the runner's builtin flag
+        // (or a project sourceRef shadowing one) must still land on them.
+        if (opts?.sourceRef)
+            this.sourceRefs.set(definition.type, opts.sourceRef);
+        if (opts?.builtin)
+            this.builtinTypes.add(definition.type);
         if (this.nodes.has(definition.type))
             return;
         this.nodes.set(definition.type, {
@@ -62,6 +142,8 @@ export class NodeRegistry {
         const next = new NodeRegistry();
         next.nodes = this.nodes;
         next.sources = this.sources;
+        next.sourceRefs = this.sourceRefs;
+        next.builtinTypes = this.builtinTypes;
         return next;
     }
 }

package/dist/src/nodes/index.d.ts

@@ -1,3 +1,9 @@
 import type { NodeRegistry } from '../engine/index.js';
-/** All built-in nodes: login examples, Open-Meteo weather, anomaly-detection API, EV charging demo, HTTP Response, requireAuth. */
-export declare function createDefaultRegistry(delayMs?: number): NodeRegistry;
+/**
+ * All built-in nodes: login examples, Open-Meteo weather, anomaly-detection API, EV charging demo, HTTP Response, requireAuth.
+ * `opts.captureSourceRefs` is threaded from SERVER callers only (buildRegistries)
+ * — this function is shared with the browser bundle, where capture stays off.
+ */
+export declare function createDefaultRegistry(delayMs?: number, opts?: {
+    captureSourceRefs?: boolean;
+}): NodeRegistry;

package/dist/src/nodes/index.js

@@ -6,9 +6,13 @@ import { registerLoopNodes } from './loops.js';
 import { registerPradarNodesModule } from './pradar/index.js';
 import { registerResponseNodes } from './response.js';
 import { registerRequireAuthNode } from './requireAuth.js';
-/** All built-in nodes: login examples, Open-Meteo weather, anomaly-detection API, EV charging demo, HTTP Response, requireAuth. */
-export function createDefaultRegistry(delayMs) {
-    const registry = createLoginRegistry(delayMs);
+/**
+ * All built-in nodes: login examples, Open-Meteo weather, anomaly-detection API, EV charging demo, HTTP Response, requireAuth.
+ * `opts.captureSourceRefs` is threaded from SERVER callers only (buildRegistries)
+ * — this function is shared with the browser bundle, where capture stays off.
+ */
+export function createDefaultRegistry(delayMs, opts) {
+    const registry = createLoginRegistry(delayMs, opts);
     registerWeatherNodes(registry);
     registerAnomalyNodes(registry);
     registerFlowControlNodes(registry);

package/dist/src/nodes/login.d.ts

@@ -4,4 +4,6 @@ import { NodeRegistry } from '../engine/index.js';
  * `delayMs` is injected into every implementation via `await sleep(delayMs)`
  * so tests can run with no delay by passing `0`.
  */
-export declare function createLoginRegistry(delayMs?: number): NodeRegistry;
+export declare function createLoginRegistry(delayMs?: number, opts?: {
+    captureSourceRefs?: boolean;
+}): NodeRegistry;

package/dist/src/nodes/login.js

@@ -9,8 +9,8 @@ function usernamePart(userId) {
  * `delayMs` is injected into every implementation via `await sleep(delayMs)`
  * so tests can run with no delay by passing `0`.
  */
-export function createLoginRegistry(delayMs = 300) {
-    const registry = new NodeRegistry();
+export function createLoginRegistry(delayMs = 300, opts) {
+    const registry = new NodeRegistry(opts);
     registry.register({
         type: 'ValidateCredentials',
         label: 'Validate Credentials',

package/package.json

@@ -1,16 +1,27 @@
 {
   "name": "@xdelivered/emberflow",
-  "version": "0.2.0",
+  "version": "0.5.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",
@@ -67,13 +86,16 @@
     "tailwind-merge": "^3.6.0",
     "tailwindcss": "^4.3.2",
     "tw-animate-css": "^1.4.0",
+    "typescript": "~6.0.2",
     "zustand": "^5.0.14"
   },
   "peerDependencies": {
     "tsx": "^4.22.5"
   },
   "peerDependenciesMeta": {
-    "tsx": { "optional": true }
+    "tsx": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/express": "^5.0.6",
@@ -85,7 +107,6 @@
     "@vitejs/plugin-react": "^6.0.3",
     "oxlint": "^1.71.0",
     "tsx": "^4.22.5",
-    "typescript": "~6.0.2",
     "vite": "^8.1.1",
     "vitest": "^4.1.9"
   }

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