@phnx-labs/agents-cli 1.20.43 → 1.20.45

package/dist/lib/session/state.js

@@ -37,6 +37,16 @@ const PR_URL_RE = /https:\/\/github\.com\/[^\s"'()<>]+\/pull\/(\d+)/;
 const WORKTREE_RE = /\/\.agents\/worktrees\/([^/]+)/;
 /** gh invocations that create/open a PR. */
 const GH_PR_CREATE_RE = /\bgh\s+pr\s+(?:create|new)\b/;
+/** gh invocation that opens an issue — the created number is read from its result. */
+const GH_ISSUE_CREATE_RE = /\bgh\s+issue\s+create\b/;
+/** A created GitHub issue URL (…/issues/123) in tool-result output. */
+const GH_ISSUE_URL_RE = /https:\/\/github\.com\/[^\s"'()<>]+\/issues\/(\d+)/;
+/**
+ * `agents teams create <name>` / `agents teams add <team> …` (also the `ag` alias).
+ * The team NAME is the first bareword after the sub-verb, skipping any flags. This
+ * is the structural signal that a session SPAWNED a team (vs. was spawned by one).
+ */
+const TEAMS_SPAWN_RE = /\bag(?:ents)?\s+teams?\s+(?:create|add)\s+(?:--?[a-z][\w-]*(?:[= ]\S+)?\s+)*([A-Za-z0-9][\w-]*)/;
 /** Collapse to a single trimmed line for a one-row preview cell. */
 function oneLine(s) {
     return s.replace(/\s+/g, ' ').trim();
@@ -80,6 +90,46 @@ export function extractPrUrl(output) {
 export function isPrCreateCommand(command) {
     return !!command && GH_PR_CREATE_RE.test(command);
 }
+/**
+ * The team a session SPAWNED, from an `agents teams create/add <name>` command.
+ * Returns the team name, or undefined if the command isn't a team spawn. Note this
+ * is the opposite of `isTeamOrigin` (which marks sessions spawned BY a team).
+ */
+export function detectSpawnedTeam(command) {
+    if (!command)
+        return undefined;
+    const m = command.match(TEAMS_SPAWN_RE);
+    return m ? m[1] : undefined;
+}
+/**
+ * True when a tool_use call CREATES a tracker ticket — a Linear MCP `create_issue`
+ * tool, or a Bash `gh issue create`. The created id is then read from the matching
+ * tool_result via {@link extractCreatedTicket}.
+ */
+export function isTicketCreateTool(name, command) {
+    if (typeof name === 'string' && /linear/i.test(name) && /create[_-]?issue/i.test(name))
+        return true;
+    // Any shell tool (Bash / shell / local_shell) running `gh issue create`.
+    if (!!command && GH_ISSUE_CREATE_RE.test(command))
+        return true;
+    return false;
+}
+/**
+ * Pull a created ticket ref out of a create-issue tool_result. Linear returns a
+ * key like `RUSH-1234`; `gh issue create` returns the issue URL, from which we
+ * take `#<number>`. Returns undefined when neither shape is present.
+ */
+export function extractCreatedTicket(text) {
+    if (!text)
+        return undefined;
+    const lin = text.match(TICKET_RE);
+    if (lin && !TICKET_DENYLIST.has(lin[1].split('-')[0]))
+        return lin[1];
+    const gh = text.match(GH_ISSUE_URL_RE);
+    if (gh)
+        return `#${gh[1]}`;
+    return undefined;
+}
 /** Does an assistant message read as a question directed at the user? */
 function looksLikeQuestion(text) {
     const t = text.trim();
@@ -181,14 +231,19 @@ export function inferActivity(events, ctx = {}) {
     return base;
 }
 /**
- * Scan an event slice for the durable signals (PR opened, ticket) that aren't
- * about the cwd. Correlates each `gh pr create` with the nearest following
- * tool_result URL; keeps the last PR found.
+ * Scan an event slice for the durable signals that aren't about the cwd: the PR
+ * opened, the injected ticket, plus the artifacts the session PRODUCED — tracker
+ * refs it created and any team it spawned. Each `gh pr create` / create-issue tool
+ * call is correlated with the nearest following tool_result; the team name comes
+ * straight off the `agents teams create/add` command.
  */
 export function detectDurableSignals(events) {
     let pr;
     let sawPrCreate = false;
     let ticket;
+    let sawTicketCreate = false;
+    let spawnedTeam;
+    const createdTickets = new Set();
     for (const e of events) {
         // Structural PR signal: a real `gh pr create` tool call, then the pull URL
         // from a following tool_result — never a bare URL mentioned in prose.
@@ -201,21 +256,45 @@ export function detectDurableSignals(events) {
                 sawPrCreate = false;
             }
         }
+        // Produced artifacts: a team spawn is read off the command; a created ticket
+        // is a create-issue tool call whose following tool_result carries the new ref.
+        if (e.type === 'tool_use') {
+            if (!spawnedTeam) {
+                const team = detectSpawnedTeam(e.command);
+                if (team)
+                    spawnedTeam = team;
+            }
+            if (isTicketCreateTool(e.tool, e.command))
+                sawTicketCreate = true;
+        }
+        if (sawTicketCreate && e.type === 'tool_result') {
+            const t = extractCreatedTicket(e.output);
+            if (t)
+                createdTickets.add(t);
+            sawTicketCreate = false;
+        }
         if (!ticket && e.type === 'message' && e.role === 'user') {
             ticket = detectTicket(e.content);
         }
     }
-    return { pr, ticket };
+    return {
+        pr,
+        ticket,
+        createdTickets: createdTickets.size > 0 ? [...createdTickets] : undefined,
+        spawnedTeam,
+    };
 }
 /** Full inference: activity + preview + durable signals + worktree/ticket from ctx. */
 export function inferSessionState(events, ctx = {}) {
     const state = inferActivity(events, ctx);
-    const { pr, ticket } = detectDurableSignals(events);
+    const { pr, ticket, createdTickets, spawnedTeam } = detectDurableSignals(events);
     const worktree = detectWorktree(ctx.cwd, ctx.gitBranch);
     return {
         ...state,
         pr: pr ?? state.pr,
         worktree: worktree ?? state.worktree,
         ticket: ticket ?? detectTicket(undefined, ctx.gitBranch) ?? state.ticket,
+        createdTickets,
+        spawnedTeam,
     };
 }

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

@@ -65,16 +65,16 @@ export interface SessionMeta {
     version?: string;
     account?: string;
     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`.
+     * The session's human-readable name — one field, several sources with a plain
+     * priority: an agent-generated title / Claude `/rename` wins; else the launch
+     * handle seeded from `agents run --name <slug>` (interactive, headless, remote
+     * host, or a teams teammate); else it stays unset and the listing falls back to
+     * `topic`. Searchable via `agents sessions <label>`. (Before v10 the launch
+     * handle lived in a separate immutable `name` column; `--name` now just seeds
+     * this label.)
      */
-    name?: string;
+    label?: string;
     /** Set when this session was spawned by `agents teams`. */
     teamOrigin?: TeamOrigin;
     /** Durable state signals extracted at scan time by the session-state engine. */
@@ -86,6 +86,17 @@ export interface SessionMeta {
     worktreeSlug?: string;
     /** Tracker ticket ref (e.g. RUSH-1234) from the prompt or branch. */
     ticketId?: string;
+    /**
+     * Tracker refs the session CREATED during its run — Linear `create_issue` MCP
+     * calls or `gh issue create` shell commands — read from the tool result. Distinct
+     * from `ticketId` (the injected/worked-on ticket from the prompt or branch).
+     */
+    createdTickets?: string[];
+    /**
+     * Team name this session SPAWNED via `agents teams create/add`. The inverse of
+     * `isTeamOrigin` (which marks sessions spawned BY a team).
+     */
+    spawnedTeam?: string;
     /**
      * True when the session was spawned programmatically (SDK entrypoint) rather
      * than by a human at the Claude CLI. Captured at scan time from the JSONL

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,7 +20,9 @@ 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';
+import { recordRunName } from '../session/run-names.js';
 let lastMemoryWarnAt = 0;
 // On macOS, os.freemem() returns only the truly-free pool and ignores the
 // large inactive+purgeable cache the kernel will reclaim under pressure, so
@@ -326,18 +328,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() {
@@ -1058,6 +1068,14 @@ export class AgentManager {
             throw new Error(`Failed to create agent directory: ${err.message}`);
         }
         this.agents.set(agentId, agent);
+        // Seed the teammate's session label with its friendly team name, so the run
+        // shows up as `<name>` in `agents sessions` and resolves by it — consistent
+        // with `agents run --name`. For Claude the agent id IS the session id (passed
+        // via --session-id in buildCommand); other agents don't expose a launch-time
+        // id, so they're seeded once discovery captures one. Best-effort.
+        if (agentType === 'claude' && name && !isCloudBacked) {
+            recordRunName({ sessionId: agentId, name, agent: agentType, cwd: resolvedCwd ?? undefined });
+        }
         if (isStaged) {
             await agent.saveMeta();
             debug(`Staged ${agentType} teammate '${name}' in team '${taskName}' (after: ${cleanAfter.join(', ')})`);

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/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;