@phnx-labs/agents-cli 1.20.42 → 1.20.44

package/dist/lib/session/run-names.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Run-name index: the join between a `agents run --name <slug>` handle and the
+ * session id of the run it named.
+ *
+ * `agents run` records `<sessionId>.json` here at launch whenever both a name
+ * and a session id are known up front (Claude pre-mints its id — see
+ * spawnAgent). The session-discovery pass reads these sidecars and applies the
+ * names onto the SQLite index by id (via syncNames), the same idempotent,
+ * re-applied-every-scan pattern as Claude `/rename` labels. Names therefore
+ * survive transcript rescans without being parsed out of the transcript itself.
+ *
+ * Mirrors the host-task sidecar convention (`~/.agents/.cache/hosts/<id>.json`),
+ * one small JSON per run under `~/.agents/.cache/run-names/`.
+ */
+export interface RunNameRecord {
+    sessionId: string;
+    name: string;
+    agent: string;
+    cwd?: string;
+    ts: number;
+}
+export declare function runNamesDir(): string;
+/**
+ * Record a run's `--name` handle keyed by its session id. Best-effort: a failed
+ * write must never break the run itself. No-op without both a name and id.
+ */
+export declare function recordRunName(rec: Omit<RunNameRecord, 'ts'>): void;
+/**
+ * Build the sessionId → name map from every run-name sidecar, for syncNames to
+ * apply onto the index. Returns an empty map when the dir doesn't exist yet.
+ */
+export declare function buildRunNameMap(): Map<string, string | null>;

package/dist/lib/session/run-names.js

@@ -0,0 +1,63 @@
+/**
+ * Run-name index: the join between a `agents run --name <slug>` handle and the
+ * session id of the run it named.
+ *
+ * `agents run` records `<sessionId>.json` here at launch whenever both a name
+ * and a session id are known up front (Claude pre-mints its id — see
+ * spawnAgent). The session-discovery pass reads these sidecars and applies the
+ * names onto the SQLite index by id (via syncNames), the same idempotent,
+ * re-applied-every-scan pattern as Claude `/rename` labels. Names therefore
+ * survive transcript rescans without being parsed out of the transcript itself.
+ *
+ * Mirrors the host-task sidecar convention (`~/.agents/.cache/hosts/<id>.json`),
+ * one small JSON per run under `~/.agents/.cache/run-names/`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getCacheDir } from '../state.js';
+export function runNamesDir() {
+    return path.join(getCacheDir(), 'run-names');
+}
+function recordFile(sessionId) {
+    return path.join(runNamesDir(), `${sessionId}.json`);
+}
+/**
+ * Record a run's `--name` handle keyed by its session id. Best-effort: a failed
+ * write must never break the run itself. No-op without both a name and id.
+ */
+export function recordRunName(rec) {
+    if (!rec.sessionId || !rec.name)
+        return;
+    try {
+        fs.mkdirSync(runNamesDir(), { recursive: true });
+        fs.writeFileSync(recordFile(rec.sessionId), JSON.stringify({ ...rec, ts: Date.now() }, null, 2));
+    }
+    catch {
+        /* the run is already launching; the name is a convenience, not load-bearing */
+    }
+}
+/**
+ * Build the sessionId → name map from every run-name sidecar, for syncNames to
+ * apply onto the index. Returns an empty map when the dir doesn't exist yet.
+ */
+export function buildRunNameMap() {
+    const map = new Map();
+    let files;
+    try {
+        files = fs.readdirSync(runNamesDir()).filter((f) => f.endsWith('.json'));
+    }
+    catch {
+        return map;
+    }
+    for (const f of files) {
+        try {
+            const rec = JSON.parse(fs.readFileSync(path.join(runNamesDir(), f), 'utf-8'));
+            if (rec.sessionId && rec.name)
+                map.set(rec.sessionId, rec.name);
+        }
+        catch {
+            /* skip a corrupt sidecar */
+        }
+    }
+    return map;
+}

package/dist/lib/session/types.d.ts

@@ -67,6 +67,14 @@ export interface SessionMeta {
     topic?: string;
     /** Custom name the user gave the session (e.g. Claude Code /rename). */
     label?: string;
+    /**
+     * Durable launch handle from `agents run --name <slug>` — an alias chosen at
+     * launch (not derived from the session id), used to resolve the run in
+     * `agents sessions <name>`. Distinct from `label` (post-hoc /rename): a run's
+     * name is immutable; both are searchable. Absent for runs launched without
+     * `--name`.
+     */
+    name?: string;
     /** Set when this session was spawned by `agents teams`. */
     teamOrigin?: TeamOrigin;
     /** Durable state signals extracted at scan time by the session-state engine. */

package/dist/lib/shims.d.ts

@@ -77,7 +77,7 @@ export interface ConflictInfo {
  *         top-level entry add/remove — deep edits to plugin contents won't
  *         trigger auto-resync, run `agents sync` for that.
  */
-export declare const SHIM_SCHEMA_VERSION = 24;
+export declare const SHIM_SCHEMA_VERSION = 25;
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.

package/dist/lib/shims.js

@@ -211,7 +211,10 @@ async function promptConflictStrategy(conflictInfos) {
 // v22 — export DISABLE_AUTOUPDATER=1 for claude shims so a pinned per-version
 //        install can't self-mutate: Claude Code's background auto-updater would
 //        otherwise rewrite the pinned binary in place. Explicit user value wins.
-export const SHIM_SCHEMA_VERSION = 24;
+// v25 — dispatcher self-recovery: if the baked AGENTS_BIN is gone (a removed/moved
+//        dev build that generated the shim), resolve `agents` on PATH instead of
+//        exiting 127, so a stale/vanished dev build can't brick every launch.
+export const SHIM_SCHEMA_VERSION = 25;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
 function shellQuote(value) {
@@ -291,8 +294,19 @@ AGENT="${agent}"
 CLI_COMMAND="${cliCommand}"
 
 if [ -z "$AGENTS_BIN" ] || [ ! -x "$AGENTS_BIN" ]; then
-  echo "agents: agents-cli entrypoint missing or not executable: $AGENTS_BIN" >&2
-  exit 127
+  # The baked dispatcher is gone — e.g. the build that generated this shim (often
+  # a dev build under ~/.local/agents-cli-dev) was removed, moved, or its version
+  # dir rotated. Self-recover to whatever 'agents' now resolves to on PATH instead
+  # of bricking every managed launch. 'agents' is the CLI itself, never a per-agent
+  # shim, so this cannot re-enter this dispatcher.
+  RECOVERED_BIN="$(command -v agents 2>/dev/null || true)"
+  if [ -n "$RECOVERED_BIN" ] && [ -x "$RECOVERED_BIN" ]; then
+    AGENTS_BIN="$RECOVERED_BIN"
+  else
+    echo "agents: agents-cli entrypoint missing or not executable: $AGENTS_BIN" >&2
+    echo "agents: could not resolve 'agents' on PATH to recover. Reinstall: npm i -g @phnx-labs/agents-cli" >&2
+    exit 127
+  fi
 fi
 
 # When agents-cli "adopts" a harness's own launcher (symlinks the native binary

package/dist/lib/teams/agents.js

@@ -20,6 +20,7 @@ import { debug } from './debug.js';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from '../gemini-settings.js';
 import { getAgentsDir as getSystemAgentsDir, getShimsDir } from '../state.js';
 import { AGENTS, getAccountInfo } from '../agents.js';
+import { resolveVersion, isVersionInstalled } from '../versions.js';
 import { sanitizeProcessEnv } from '../secrets/bundles.js';
 let lastMemoryWarnAt = 0;
 // On macOS, os.freemem() returns only the truly-free pool and ignores the
@@ -326,18 +327,26 @@ export async function ensureGeminiPlanMode() {
  * (for CLIs the user installed outside agents-cli).
  */
 export function checkCliAvailable(agentType) {
-    const executable = AGENTS[agentType]?.cliCommand;
+    const agent = agentType;
+    const executable = AGENTS[agent]?.cliCommand;
     if (!executable) {
         return [false, `Unknown agent type: ${agentType}`];
     }
     const shimPath = path.join(getShimsDir(), executable);
-    if (fsSync.existsSync(shimPath)) {
-        return [true, shimPath];
+    const dispatch = fsSync.existsSync(shimPath) ? shimPath : findExecutable(executable);
+    if (!dispatch) {
+        return [false, `CLI tool '${executable}' not found in PATH. Install it first.`];
     }
-    const resolved = findExecutable(executable);
-    return resolved
-        ? [true, resolved]
-        : [false, `CLI tool '${executable}' not found in PATH. Install it first.`];
+    // A shim file (or a PATH entry) existing does NOT mean the agent is runnable:
+    // the managed default version's binary can be a stub or gutted (a partial/raced
+    // npm extract leaves the version dir + JS wrapper but no real binary). Verify
+    // the resolved default version is actually installed so `teams doctor` reports
+    // the truth instead of a false `installed: true` that ENOENTs at spawn.
+    const version = resolveVersion(agent);
+    if (version && !isVersionInstalled(agent, version)) {
+        return [false, `${executable}@${version} is not runnable — its binary is missing/incomplete. Repair: agents add ${agent}@${version}`];
+    }
+    return [true, dispatch];
 }
 /** Check availability of all known agent CLIs. Returns a map of agent type to install status. */
 export function checkAllClis() {

package/dist/lib/tmux/session.d.ts

@@ -126,6 +126,46 @@ export declare function paneExitStatus(pane: string, socket?: string): Promise<P
  * Best-effort — a failed hook just means the user Ctrl-b d's out manually.
  */
 export declare function setSessionHook(name: string, hook: string, command: string, socket?: string): Promise<void>;
+/**
+ * Schema version of the `pane-died` hook installed on managed `agents run`
+ * sessions. Bump whenever the hook's SHAPE changes so the daemon reconcile
+ * (reconcileSessionHooks) knows to re-stamp live sessions a prior binary left on
+ * an older shape.
+ *   v1 — the original unconditional `detach-client`: ANY pane death (including a
+ *        user exiting a split they opened) tore down the whole client.
+ *   v2 — `#{hook_pane}`-guarded: only the AGENT pane dying detaches; a user
+ *        split's death runs `kill-pane`, closing just that split.
+ */
+export declare const AGENT_HOOK_SCHEMA = 2;
+/**
+ * The guarded `pane-died` hook. Detach the client ONLY when the agent pane dies
+ * (so the blocking attach in runInTmux returns and the exit status can be read);
+ * a user split's death falls through to `kill-pane`, which — because the hook
+ * runs in the dead pane's context — closes that split in place. Single source of
+ * truth: both the spawn-wrap (exec.ts) and the daemon reconcile build the hook
+ * here, so the two can never drift.
+ */
+export declare function agentPaneDiedHook(sessionName: string, agentPane: string): string;
+/** Stamp a session's hook-schema marker to the current version. */
+export declare function markSessionHookSchema(name: string, socket?: string): Promise<void>;
+/**
+ * Retrofit the current guarded `pane-died` hook onto every managed `agents run`
+ * session whose hook predates AGENT_HOOK_SCHEMA. Idempotent and NON-DESTRUCTIVE:
+ * it only `set-hook`s (never kills a pane or detaches a client), so a long-lived
+ * shared server started by a pre-fix binary — whose still-running sessions carry
+ * the old unconditional hook that kicked the user out of the whole view when they
+ * exited a split — self-heals in place, without waiting for those agents to exit
+ * or for the server to be recycled.
+ *
+ * The daemon calls this on a light interval. The per-session `@ag_hook_schema`
+ * marker makes steady-state a cheap no-op: a session already at the current
+ * schema is skipped. Only run-wrapped sessions (`ag-` prefix) are touched — an
+ * externally-created session on the socket keeps whatever hook it set.
+ */
+export declare function reconcileSessionHooks(socket?: string): Promise<{
+    scanned: number;
+    reconciled: number;
+}>;
 /**
  * List live sessions on the socket. Reconciles meta JSONs against tmux's view:
  *  - tmux session with no meta → returned without `meta` (external session)

package/dist/lib/tmux/session.js

@@ -269,6 +269,98 @@ export async function setSessionHook(name, hook, command, socket) {
     const sock = socket ?? getDefaultSocketPath();
     await runTmux({ socket: sock, args: ['set-hook', '-t', name, hook, command], throwOnError: false }).catch(() => { });
 }
+/**
+ * Schema version of the `pane-died` hook installed on managed `agents run`
+ * sessions. Bump whenever the hook's SHAPE changes so the daemon reconcile
+ * (reconcileSessionHooks) knows to re-stamp live sessions a prior binary left on
+ * an older shape.
+ *   v1 — the original unconditional `detach-client`: ANY pane death (including a
+ *        user exiting a split they opened) tore down the whole client.
+ *   v2 — `#{hook_pane}`-guarded: only the AGENT pane dying detaches; a user
+ *        split's death runs `kill-pane`, closing just that split.
+ */
+export const AGENT_HOOK_SCHEMA = 2;
+/** Per-session tmux user-option that records which AGENT_HOOK_SCHEMA a session's hook is at. */
+const HOOK_SCHEMA_OPTION = '@ag_hook_schema';
+/**
+ * The guarded `pane-died` hook. Detach the client ONLY when the agent pane dies
+ * (so the blocking attach in runInTmux returns and the exit status can be read);
+ * a user split's death falls through to `kill-pane`, which — because the hook
+ * runs in the dead pane's context — closes that split in place. Single source of
+ * truth: both the spawn-wrap (exec.ts) and the daemon reconcile build the hook
+ * here, so the two can never drift.
+ */
+export function agentPaneDiedHook(sessionName, agentPane) {
+    return `if -F '#{==:#{hook_pane},${agentPane}}' 'detach-client -s =${sessionName}' 'kill-pane'`;
+}
+/** Stamp a session's hook-schema marker to the current version. */
+export async function markSessionHookSchema(name, socket) {
+    const sock = socket ?? getDefaultSocketPath();
+    await runTmux({ socket: sock, args: ['set-option', '-t', name, HOOK_SCHEMA_OPTION, String(AGENT_HOOK_SCHEMA)], throwOnError: false }).catch(() => { });
+}
+/** Read a session's hook-schema marker; undefined when unset (pre-marker sessions). */
+async function readHookSchema(name, socket) {
+    const res = await runTmux({ socket, args: ['show-options', '-v', '-t', name, HOOK_SCHEMA_OPTION], throwOnError: false }).catch(() => null);
+    if (!res || res.code !== 0)
+        return undefined;
+    const v = res.stdout.trim();
+    return v === '' ? undefined : v;
+}
+/**
+ * Lowest pane id (`%N`) in a session — the first pane created, i.e. the agent
+ * pane, since user splits are always created later and get higher ids. Fallback
+ * for sessions whose SessionMeta (which records the agent pane) predates meta
+ * persistence. Undefined when the session has no panes (already torn down).
+ */
+async function lowestPaneId(name, socket) {
+    const res = await runTmux({ socket, args: ['list-panes', '-t', name, '-F', '#{pane_id}'], throwOnError: false }).catch(() => null);
+    if (!res || res.code !== 0)
+        return undefined;
+    const ids = res.stdout.split('\n').map(l => l.trim()).filter(id => /^%\d+$/.test(id));
+    if (!ids.length)
+        return undefined;
+    return ids.reduce((lo, id) => (parseInt(id.slice(1), 10) < parseInt(lo.slice(1), 10) ? id : lo));
+}
+/**
+ * Retrofit the current guarded `pane-died` hook onto every managed `agents run`
+ * session whose hook predates AGENT_HOOK_SCHEMA. Idempotent and NON-DESTRUCTIVE:
+ * it only `set-hook`s (never kills a pane or detaches a client), so a long-lived
+ * shared server started by a pre-fix binary — whose still-running sessions carry
+ * the old unconditional hook that kicked the user out of the whole view when they
+ * exited a split — self-heals in place, without waiting for those agents to exit
+ * or for the server to be recycled.
+ *
+ * The daemon calls this on a light interval. The per-session `@ag_hook_schema`
+ * marker makes steady-state a cheap no-op: a session already at the current
+ * schema is skipped. Only run-wrapped sessions (`ag-` prefix) are touched — an
+ * externally-created session on the socket keeps whatever hook it set.
+ */
+export async function reconcileSessionHooks(socket) {
+    const sock = socket ?? getDefaultSocketPath();
+    if (!fs.existsSync(sock))
+        return { scanned: 0, reconciled: 0 };
+    let sessions;
+    try {
+        sessions = await listSessions({ socket: sock });
+    }
+    catch {
+        return { scanned: 0, reconciled: 0 };
+    }
+    let reconciled = 0;
+    for (const s of sessions) {
+        if (!s.name.startsWith('ag-'))
+            continue; // only run-wrapped sessions
+        if (await readHookSchema(s.name, sock) === String(AGENT_HOOK_SCHEMA))
+            continue;
+        const agentPane = s.meta?.pane ?? await lowestPaneId(s.name, sock);
+        if (!agentPane)
+            continue;
+        await setSessionHook(s.name, 'pane-died', agentPaneDiedHook(s.name, agentPane), sock);
+        await markSessionHookSchema(s.name, sock);
+        reconciled++;
+    }
+    return { scanned: sessions.length, reconciled };
+}
 /**
  * List live sessions on the socket. Reconciles meta JSONs against tmux's view:
  *  - tmux session with no meta → returned without `meta` (external session)

package/dist/lib/usage.d.ts

@@ -88,9 +88,11 @@ export declare function getUsageInfoForIdentity(input: UsageIdentityInput): Prom
 export declare function formatUsageSummary(plan: string | null, snapshot: UsageSnapshot | null, planWidth?: number): string;
 /**
  * Derive an account's real throttle state from its live usage windows — the
- * same signal `agents usage` shows and balanced rotation trusts
- * (`getRoutingUsedPercent` in rotate.ts). A window at 100% utilization means
- * the account is throttled until that window resets.
+ * single signal both the `agents view` badge and run-rotation eligibility share
+ * (`hasUsageAvailable` in rotate.ts treats a `rate_limited` verdict here as
+ * ineligible). A window at 100% utilization means the account is throttled until
+ * that window resets. Rotation *weighting* still ranks eligible accounts by
+ * weekly headroom (`getRoutingUsedPercent`); this function is the yes/no gate.
  *
  * Returns `null` when there is no snapshot, so callers render no badge rather
  * than a misleading one. This deliberately never consults

package/dist/lib/usage.js

@@ -212,9 +212,11 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3) {
 }
 /**
  * Derive an account's real throttle state from its live usage windows — the
- * same signal `agents usage` shows and balanced rotation trusts
- * (`getRoutingUsedPercent` in rotate.ts). A window at 100% utilization means
- * the account is throttled until that window resets.
+ * single signal both the `agents view` badge and run-rotation eligibility share
+ * (`hasUsageAvailable` in rotate.ts treats a `rate_limited` verdict here as
+ * ineligible). A window at 100% utilization means the account is throttled until
+ * that window resets. Rotation *weighting* still ranks eligible accounts by
+ * weekly headroom (`getRoutingUsedPercent`); this function is the yes/no gate.
  *
  * Returns `null` when there is no snapshot, so callers render no badge rather
  * than a misleading one. This deliberately never consults

package/dist/lib/versions.d.ts

@@ -180,7 +180,9 @@ export declare function setGlobalDefault(agent: AgentId, version: string | undef
 /**
  * Install a specific version of an agent.
  */
-export declare function installVersion(agent: AgentId, version: string, onProgress?: (message: string) => void): Promise<{
+export declare function installVersion(agent: AgentId, version: string, onProgress?: (message: string) => void, opts?: {
+    clean?: boolean;
+}): Promise<{
     success: boolean;
     installedVersion: string;
     error?: string;
@@ -291,6 +293,57 @@ export { compareVersions };
  * Get actual version from an installed 'latest' directory.
  */
 export declare function getInstalledVersion(agent: AgentId, version: string): Promise<string | null>;
+/**
+ * True when a probe's combined output/error looks like the runnable binary (or a
+ * native sub-binary it execs) is MISSING — the "gutted install" signature. This
+ * is the exact class of failure behind the ENOENT crash: an npm package whose JS
+ * wrapper landed at node_modules/.bin/<cli> while its native platform binary
+ * (shipped via an optional per-arch dependency, e.g. @openai/codex-<platform>)
+ * did not — so the wrapper spawns and immediately dies with `spawn … ENOENT`.
+ *
+ * Deliberately narrow: only the missing-file signature counts. An agent that
+ * merely dislikes `--version` (nonzero exit, ordinary error text) or ignores it
+ * (times out) must NOT match, so a healthy install is never falsely condemned.
+ */
+export declare function isMissingBinarySignature(output: string): boolean;
+/**
+ * Verify a freshly-installed agent can actually LAUNCH — not merely that its JS
+ * wrapper exists. getBinaryPath()/isVersionInstalled() only check the wrapper, so
+ * a gutted install (wrapper present, native binary missing) reads as healthy,
+ * gets pinned as the default, and gets picked to run — then dies with ENOENT the
+ * instant it spawns (which, wrapped in tmux, showed up as a silent `[detached]`).
+ *
+ * We probe `<binary> --version` under the version's isolated HOME so config
+ * resolution matches a real launch. Because the ENOENT originates in the child
+ * (the wrapper spawns fine, then fails to exec the absent native binary), we
+ * inspect the child's OUTPUT, not just whether our spawn succeeded. Only the
+ * missing-binary signature (see isMissingBinarySignature) fails the check; a
+ * plain nonzero exit or a timeout is treated as healthy so we never false-fail.
+ */
+export declare function verifyInstalledBinaryLaunches(agent: AgentId, version: string): Promise<{
+    ok: boolean;
+    detail?: string;
+}>;
+/**
+ * Launch-path self-heal. Given the concrete version `agents run` is about to
+ * spawn, make sure it will actually run — and if not, repair it instead of
+ * letting the agent die with a raw `ENOENT` deep inside its own wrapper.
+ *
+ * Steps, cheapest first:
+ *   1. Probe the version (verifyInstalledBinaryLaunches). Healthy → return it.
+ *   2. Broken → **clean** reinstall in place (wipes the partial node_modules so
+ *      npm actually re-fetches the platform binary). Re-probe; good → return it.
+ *   3. Still broken → fall back to another INSTALLED version that launches,
+ *      re-pinning it as the default so the shim path heals too. Return it.
+ *   4. Nothing runnable installed → install `latest`, pin it, return it.
+ *   5. Give up → return null (caller surfaces a clear error).
+ *
+ * Gated to npm-package agents: their native binary ships as an optional per-arch
+ * dependency whose tarball can extract partially (interrupted/raced install) —
+ * the exact failure this repairs. Agents with a global/native binary (grok,
+ * droid) have no such tarball and are returned unchanged.
+ */
+export declare function ensureAgentRunnable(agent: AgentId, version: string, log?: (message: string) => void): Promise<string | null>;
 /** Outcome of syncing resources to a version home, keyed by resource type. */
 export interface SyncResult {
     commands: boolean;

package/dist/lib/versions.js

@@ -1054,7 +1054,7 @@ export function setGlobalDefault(agent, version) {
 /**
  * Install a specific version of an agent.
  */
-export async function installVersion(agent, version, onProgress) {
+export async function installVersion(agent, version, onProgress, opts) {
     const agentConfig = AGENTS[agent];
     // Validate before deriving filesystem paths or npm package specs. The CLI
     // parser already enforces this for user input; this guard protects direct
@@ -1143,6 +1143,14 @@ export async function installVersion(agent, version, onProgress) {
     }
     ensureAgentsDir();
     const versionDir = getVersionDir(agent, version);
+    // A `clean` (repair) reinstall wipes a possibly partially-extracted
+    // node_modules first. npm treats a present-but-gutted platform package (its
+    // package.json landed, its vendored native binary did not) as already
+    // installed and would skip re-fetching it — so without this the corrupt
+    // vendor/ survives the reinstall and the ENOENT persists. home/ is preserved.
+    if (opts?.clean && fs.existsSync(versionDir)) {
+        removeInstallArtifacts(versionDir);
+    }
     // Create version directory and isolated home
     fs.mkdirSync(versionDir, { recursive: true });
     fs.mkdirSync(path.join(versionDir, 'home'), { recursive: true });
@@ -1218,6 +1226,24 @@ export async function installVersion(agent, version, onProgress) {
                 /* non-fatal; the install itself succeeded */
             }
         }
+        // Integrity gate: confirm the install actually launches, not just that the
+        // JS wrapper landed. A gutted install (wrapper present, native platform
+        // binary missing) otherwise gets silently pinned as the default and crashes
+        // with ENOENT on run. Fail loudly here so `agents add` never records a
+        // broken version as healthy — the caller then won't set it as default.
+        const health = await verifyInstalledBinaryLaunches(agent, installedVersion);
+        if (!health.ok) {
+            if (fs.existsSync(versionDir))
+                removeInstallArtifacts(versionDir);
+            const detail = health.detail ? ` (${health.detail})` : '';
+            emit('version.install', { agent, version: installedVersion, error: `binary failed to launch${detail}` });
+            return {
+                success: false,
+                installedVersion,
+                error: `${agentConfig.name}@${installedVersion} installed but its binary failed to launch${detail}. `
+                    + `The install is incomplete — the platform binary is missing. Re-run: agents add ${agent}@${installedVersion}`,
+            };
+        }
         emit('version.install', { agent, version: installedVersion });
         return { success: true, installedVersion };
     }
@@ -1566,6 +1592,117 @@ export async function getInstalledVersion(agent, version) {
         return version;
     }
 }
+/**
+ * True when a probe's combined output/error looks like the runnable binary (or a
+ * native sub-binary it execs) is MISSING — the "gutted install" signature. This
+ * is the exact class of failure behind the ENOENT crash: an npm package whose JS
+ * wrapper landed at node_modules/.bin/<cli> while its native platform binary
+ * (shipped via an optional per-arch dependency, e.g. @openai/codex-<platform>)
+ * did not — so the wrapper spawns and immediately dies with `spawn … ENOENT`.
+ *
+ * Deliberately narrow: only the missing-file signature counts. An agent that
+ * merely dislikes `--version` (nonzero exit, ordinary error text) or ignores it
+ * (times out) must NOT match, so a healthy install is never falsely condemned.
+ */
+export function isMissingBinarySignature(output) {
+    return /\bENOENT\b|no such file|cannot find|command not found|is not recognized/i.test(output);
+}
+/**
+ * Verify a freshly-installed agent can actually LAUNCH — not merely that its JS
+ * wrapper exists. getBinaryPath()/isVersionInstalled() only check the wrapper, so
+ * a gutted install (wrapper present, native binary missing) reads as healthy,
+ * gets pinned as the default, and gets picked to run — then dies with ENOENT the
+ * instant it spawns (which, wrapped in tmux, showed up as a silent `[detached]`).
+ *
+ * We probe `<binary> --version` under the version's isolated HOME so config
+ * resolution matches a real launch. Because the ENOENT originates in the child
+ * (the wrapper spawns fine, then fails to exec the absent native binary), we
+ * inspect the child's OUTPUT, not just whether our spawn succeeded. Only the
+ * missing-binary signature (see isMissingBinarySignature) fails the check; a
+ * plain nonzero exit or a timeout is treated as healthy so we never false-fail.
+ */
+export async function verifyInstalledBinaryLaunches(agent, version) {
+    // Windows: `getBinaryPath` returns the extensionless `.bin/<cli>` (a shell
+    // wrapper), NOT the `.cmd`/`.exe` that actually launches there — `execFile`ing
+    // it would ENOENT on a perfectly healthy install, and the integrity gate would
+    // then WIPE it. The gutted-native-binary failure this guards against is a POSIX
+    // concern in practice; treat win32 as healthy rather than risk destroying a
+    // good install. (isVersionInstalled already validates presence on Windows.)
+    if (process.platform === 'win32')
+        return { ok: true };
+    const binary = getBinaryPath(agent, version);
+    if (!fs.existsSync(binary)) {
+        return { ok: false, detail: `binary not found at ${binary}` };
+    }
+    try {
+        await execFileAsync(binary, ['--version'], {
+            timeout: 15000,
+            env: { ...process.env, HOME: getVersionHomePath(agent, version) },
+        });
+        return { ok: true };
+    }
+    catch (err) {
+        const blob = `${err?.code ?? ''} ${err?.stdout ?? ''} ${err?.stderr ?? ''} ${err?.message ?? ''}`;
+        if (err?.code === 'ENOENT' || isMissingBinarySignature(blob)) {
+            const detail = String(err?.stderr || err?.message || '')
+                .split('\n').map((s) => s.trim()).filter(Boolean)[0];
+            return { ok: false, detail: detail || 'native binary missing (ENOENT)' };
+        }
+        // Launched but exited nonzero without a missing-file signature, or timed out
+        // waiting for input: the binary is present and runnable. Healthy.
+        return { ok: true };
+    }
+}
+/**
+ * Launch-path self-heal. Given the concrete version `agents run` is about to
+ * spawn, make sure it will actually run — and if not, repair it instead of
+ * letting the agent die with a raw `ENOENT` deep inside its own wrapper.
+ *
+ * Steps, cheapest first:
+ *   1. Probe the version (verifyInstalledBinaryLaunches). Healthy → return it.
+ *   2. Broken → **clean** reinstall in place (wipes the partial node_modules so
+ *      npm actually re-fetches the platform binary). Re-probe; good → return it.
+ *   3. Still broken → fall back to another INSTALLED version that launches,
+ *      re-pinning it as the default so the shim path heals too. Return it.
+ *   4. Nothing runnable installed → install `latest`, pin it, return it.
+ *   5. Give up → return null (caller surfaces a clear error).
+ *
+ * Gated to npm-package agents: their native binary ships as an optional per-arch
+ * dependency whose tarball can extract partially (interrupted/raced install) —
+ * the exact failure this repairs. Agents with a global/native binary (grok,
+ * droid) have no such tarball and are returned unchanged.
+ */
+export async function ensureAgentRunnable(agent, version, log) {
+    const cfg = AGENTS[agent];
+    if (!cfg?.npmPackage)
+        return version;
+    if ((await verifyInstalledBinaryLaunches(agent, version)).ok)
+        return version;
+    log?.(`${cfg.name}@${version} is broken (platform binary missing) — repairing…`);
+    const repair = await installVersion(agent, version, undefined, { clean: true });
+    if (repair.success && (await verifyInstalledBinaryLaunches(agent, version)).ok) {
+        log?.(`repaired ${cfg.name}@${version}.`);
+        return version;
+    }
+    // In-place repair failed → adopt another installed version that launches.
+    const others = listInstalledVersions(agent).filter(v => v !== version).sort(compareVersions).reverse();
+    for (const cand of others) {
+        if ((await verifyInstalledBinaryLaunches(agent, cand)).ok) {
+            setGlobalDefault(agent, cand);
+            log?.(`${cfg.name}@${version} could not be repaired — using ${cfg.name}@${cand} instead (now the default).`);
+            return cand;
+        }
+    }
+    // Nothing runnable installed → last resort: install latest and pin it.
+    log?.(`no runnable ${cfg.name} version installed — installing ${cfg.name}@latest…`);
+    const latest = await installVersion(agent, 'latest', undefined, { clean: true });
+    if (latest.success) {
+        setGlobalDefault(agent, latest.installedVersion);
+        log?.(`installed ${cfg.name}@${latest.installedVersion} and set it as the default.`);
+        return latest.installedVersion;
+    }
+    return null;
+}
 async function getCliVersionFromPath(agent) {
     const agentConfig = AGENTS[agent];
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.42",
+  "version": "1.20.44",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",