@phnx-labs/agents-cli 1.22.15 → 1.22.17

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 1.22.17
+
+- **Codex versions no longer share one account — each keeps its own login.** Installing a new Codex version used to copy the current default version's `.codex/auth.json` into the new version home, so `agents view` reported the same ChatGPT account for every installed Codex and you could never sign two versions into two accounts. The credential is now excluded from settings carry-forward (config, prompts, and rules still carry), matching how Claude omits `.claude.json`. A fresh Codex version installs signed-out; run `codex login` (or `agents run codex --version <v>`) inside it to authenticate that version's own account. Source: `apps/cli/src/lib/settings-manifest.ts`, `apps/cli/src/commands/versions.ts`.
+
+- **`agents feed post` now resolves owner delivery and session identity from their canonical indexes (RUSH-2193).** `agents notify` and `channel: owner` consume the normal addressable channel from `humans.yaml`, so the phone destination is no longer duplicated in `agents.yaml`. When a harness leaves `AGENT_SESSION_ID` empty, feed posting joins `AGENT_LAUNCH_ID` to recent activity before requiring `--session`. `agents feed post --help` now states that the default `milestone` is recorded but a sink gated at `minLevel: important` only texts for `--level important`; `--blocked` remains reserved for work that cannot continue. Source: `apps/cli/src/lib/humans.ts`, `apps/cli/src/lib/feed-post.ts`, `apps/cli/src/commands/feed.ts`.
+
+- **The macOS menu bar keeps its ACTIVE project accordion open and opens Quick Dispatch without blocking.** Project headers now mutate their session rows inside the existing `NSMenu` tracking session instead of closing the dropdown and attempting a synthetic reopen. `Cmd-Shift-O` prebuilds and focuses its panel before any session-history, attachment scan, thumbnail decode, or Linear-cache work; those sections hydrate asynchronously from warm data. Source: `apps/cli/menubar/Sources/MenubarHelper/{StatusItemController,PromptPanel,AgentsCLI}.swift`, `apps/cli/docs/menubar.md`. (#2051)
+
+- **`agents doctor` now accepts symbolic version qualifiers; `agents view` no longer prompts to sync resources.** `agents doctor claude@latest`, `@oldest`, `@pinned`, `@all`, and exact semver qualifiers are resolved through the shared `resolveAgentTargets` engine instead of falling through to a "not installed" error. Bare `agents doctor <agent>` still sweeps all installed versions with `versionExplicit: false` (so `--fix` excludes isolated copies). Separately, the implicit resource-drift scan and interactive sync prompt that ran at the end of `agents view <agent>` have been removed — `view` is read-only and must not mutate version-home state. Source: `apps/cli/src/commands/doctor.ts`, `apps/cli/src/commands/view.ts`. (#2058)
+
+- **`agents run <agent> --cloud` — the vendor cloud becomes a run placement.** `--cloud` dispatches the run to the agent's native cloud through the existing provider registry (claude→rush, codex→codex, droid→factory, antigravity→antigravity) — the exact same dispatch as `agents cloud run --agent <agent>`, tracked by `agents cloud list/status/logs/cancel/message`. It sits alongside `--host`/`--device`/`--lease` as the third placement (local, machine, cloud) and is mutually exclusive with them; `--where cloud[:provider]` is the one-door spelling. `--provider` overrides routing; `--repo` (repeatable), `--branch`, and `--cloud-env` refine the task (run's `--env` stays the KEY=VAL passthrough, so the Codex Cloud environment id gets its own flag). Agents without a native cloud (kimi, grok, cursor, opencode, …) fail loud with the capable list unless `--provider` is given, and local-run flags (`--loop`, `--resume`, `--secrets`, `--terminal`, `--cwd`, account strategy, …) are rejected rather than silently dropped. The dispatch core is now shared: `agents cloud run` and `agents run --cloud` both call `src/lib/cloud/dispatch.ts` (`executeCloudDispatch`), so capability checks, the missing-target picker, persistence, streaming, and the budget kill-switch cannot diverge. Source: `apps/cli/src/commands/run-cloud.ts`, `apps/cli/src/lib/cloud/dispatch.ts`, `apps/cli/src/lib/placement.ts`, `apps/cli/src/commands/exec.ts`.
+
+## 1.22.16
+
+- **Resume exact sessions locally or across the fleet with `agents resume <id>` and `agents run <agent|auto> --resume <id>`.** Full IDs use the local SQLite index before any SSH fan-out; remote owners route to the recorded device and version home. Session metadata now records launch mode alongside harness, version, account, cwd, and machine so strict resume reconstructs the original run. Claude, Codex, Grok, Kimi, Droid, and Cursor use their verified version-specific native resume syntax; `run auto --resume` can select another healthy harness/account and continue through `/continue` when native resume is unavailable. Source: `apps/cli/src/commands/{exec,resume,sessions}.ts`, `apps/cli/src/lib/{exec,session/db}.ts`, `packages/session-tracker/src/hook.sh`.
+
+- **Hooks: one-level event dirs (`hooks/<event-name>/<script>`) are first-class.**
+  System hooks organize by harness event (`session-start/`, `pre-tool-use/`, …).
+  Install names stay the file basename. Dirs with top-level scripts expand into
+  individual hooks; fixture-only dirs remain directory bundles. Manifest `script:`
+  may be a relative path under `hooks/`. Source: `apps/cli/src/lib/hooks.ts`,
+  `apps/cli/src/lib/staleness/writers/sources.ts`, `apps/cli/src/lib/versions.ts`,
+  `apps/cli/src/lib/__tests__/hooks-nested-groups.test.ts`.
+
+- **`agents humans show owner [--json]`** — new command to display the owner config from `~/.agents/humans.yaml`. The file is written automatically on first run when `notify.owner` exists in `agents.yaml`. Source: `apps/cli/src/lib/humans.ts`, `apps/cli/src/commands/humans.ts`.
+
+- **`humans.yaml` — typed, versioned owner config.** `~/.agents/humans.yaml` (`version: 1`) now stores owner identity (name, timezone, quiet hours, severity), notification channels, and escalation policy. `notify.owner` in `agents.yaml` is migrated into it on first run and the `notify.owner` key is removed from `agents.yaml`; unrelated keys are preserved. `agents send --to owner` / `agents notify` prefer `humans.yaml` with a fallback to `agents.yaml` during the migration window. Source: `apps/cli/src/lib/humans.ts`, `apps/cli/src/commands/humans.ts`, `apps/cli/src/lib/migrate.ts`.
+
+- **`agents memory` ignores `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and `MEMORY.md`.** These rule/index files lived in `~/.agents/memory/` but were incorrectly surfaced as memory facts. `isFactFile()` now excludes them by name (case-insensitive). Source: `apps/cli/src/lib/memory.ts`.
+
+- **Permissions write path fixed — `groups/` subdirectory.** `installPermissionSet`, `removePermissionSet`, and `savePermissionSet` now all write to the `groups/` subdirectory (matching `discoverPermissionGroups()` which already reads from `groups/`). Source: `apps/cli/src/lib/permissions.ts`.
+
+- **Stop eagerly creating webhooks directories.** `ensureAgentsDir()` no longer creates `~/.agents/webhooks/` or `~/.agents/.system/webhooks/` on startup — both dirs are created on first actual use. Source: `apps/cli/src/lib/state.ts`.
+
+- **Terminals canonically under `.cache/`.** The stale migration comment that blocked `terminals/` from moving to `~/.agents/.cache/terminals/` is replaced by the actual move. Factory already writes to `.cache/terminals/` (`foreman.registry.ts:9`), so no app-level change is needed. Source: `apps/cli/src/lib/migrate.ts`.
+
+- **Menu bar warns when a device is under high load (local or remote).** The
+  agents-cli menu bar now shows a `⚠ <device> — high load N%` row in NEEDS YOU when
+  a machine's load or memory crosses the `headroom()` "loaded" threshold (≥75%), and
+  a red `✕` when critical. The local machine is probed natively via `getloadavg`
+  (zero subprocess); fleet peers come from the daemon-warmed `.fleet-stats.json`
+  cache with a freshness guard — never the slow `agents doctor` path. Action-required
+  rows are now emphasized so items that need you stand out. Source:
+  `apps/cli/menubar/Sources/MenubarHelper/LocalState.swift`,
+  `apps/cli/menubar/Sources/MenubarHelper/StatusItemController.swift`.
+
+- **Projects canonicalization contract.** `agents projects import --from-factory` / `--min-confidence` / `--all` are gone; import is `--from-linear` only, and `~/.agents/factory/projects.json` is never read or migrated. `agents projects list --json` returns definitions only (zero session scan / SSH); `--with-agents` is an explicit opt-in for local active counts. New `agents projects save --json` reads one complete `ProjectDef` from stdin, validates, writes atomically under `~/.agents/projects/`, and prints the saved def. `agents projects rm <name> --json` returns machine-readable success/error. Factory's `managedProjects.ts` shells only through `agents projects list|save|rm` — never reads or writes project YAML/JSON directly, never seeds or migrates legacy Factory state; errors stay explicit for inline UI display. Source: `apps/cli/src/commands/projects.ts`, `apps/cli/src/lib/projects.ts`, `apps/factory/src/core/managedProjects.ts`, `apps/cli/docs/11-projects.md`.
+
+- **`ProjectDef` YAML gains `dispatch` block and `linear.name`.** `~/.agents/projects/<name>.yaml` now accepts a `dispatch:` block (`enabled`, `maxAgents`, `provider`, `host`) that opts a project into auto-dispatch and is read directly by `agents __auto-dispatch` — previously these fields lived only in Factory's own registry. `linear.name` stores the Linear project display name alongside the existing `projectId` and `url`. Both fields are optional; existing YAMLs are unchanged. Source: `apps/cli/src/lib/projects.ts`, `apps/cli/src/lib/auto-dispatch.ts`.
+
+- **`agents secrets` no longer pops a generic "Agents CLI needs to authenticate" Touch ID sheet on every agent launch.** `listBundles` — which runs on essentially every secrets touch (session-title generation, `agents devices list`, every `agents run`, every remote launch that resolves secrets on the host) — could not ask the keychain for just the bundle *metadata* items: with hashed service names (#316) those names are opaque, so it fell back to a **broad `agents-cli.` keychain scan** that also matched the ACL'd secret *value* items. On machines where a bundle carries a biometric ACL (e.g. a `hold`-tier bundle holding an SSN or a password), macOS evaluated that value ACL during the attributes-only scan and raised a **generic, context-less** Touch ID prompt — on every launch, so a busy fleet felt like a machine-wide bombardment. Neither `kSecUseAuthenticationUIFail` nor `LAContext.interactionNotAllowed` can list the no-ACL items while skipping the ACL'd ones (both return nothing), so the fix is to stop doing the broad scan: a per-machine **no-ACL metadata-name index** (opaque hashes only, in the regenerable helpers dir — it leaks nothing #316 didn't) is read as a silent file instead. The write paths keep it current; an absent/stale index self-heals by rebuilding from the one-time scan, and a missing entry only makes `secrets list` cosmetically incomplete — it never affects a resolve-by-name. Your sensitive bundles keep their biometric gate on real value reads; only the bundle *listing* goes silent. Source: `apps/cli/src/lib/secrets/bundles.ts`.
+
 ## 1.22.15
 
 - **Separate routine definitions from device activation (#2023).** Enable a routine by listing its name in `~/.agents/devices/<hostname>/agents.yaml`; built-in Watchdog setup and `watchdog on|off` now update that host-owned manifest without rewriting the routine definition. Source: `apps/cli/src/lib/routine-activation.ts`, `apps/cli/src/commands/setup-watchdog.ts`.

package/README.md

@@ -341,9 +341,11 @@ agents sessions resume                     # multi-select; packs two sessions pe
 agents sessions resume "auth middleware"   # pre-filter the pool, then choose
 agents sessions resume --tmux              # into persistent tmux — survives editor restarts
 agents sessions resume --host zion --tmux  # resume on another machine over SSH
+agents resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897  # original harness/version/device/mode
+agents run auto --resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897  # adapt if its account is unavailable
 ```
 
-`agents sessions resume` reopens sessions in whatever terminal you're in -- auto-detected across iTerm, Ghostty, tmux, and the VSCodium agent-terminal, or forced with `--iterm` / `--ghostty` / `--tmux` / `--vscodium`. Back them with **tmux** and the runs turn durable: detach, close your editor, reboot the GUI -- the session is still alive to `agents tmux attach`. The whole `agents tmux` subsystem (persistent multiplexer sessions that survive editor restarts and can be shared with other tools) sits underneath.
+`agents sessions resume` reopens several sessions in whatever terminal you're in -- auto-detected across iTerm, Ghostty, tmux, and the VSCodium agent-terminal, or forced with `--iterm` / `--ghostty` / `--tmux` / `--vscodium`. `agents resume <id>` resumes one session without requiring you to name its harness: exact IDs take a local SQLite fast path, then resolve fleet-wide and restore the source harness, version, device, cwd, and recorded launch mode. Back them with **tmux** and the runs turn durable: detach, close your editor, reboot the GUI -- the session is still alive to `agents tmux attach`. The whole `agents tmux` subsystem (persistent multiplexer sessions that survive editor restarts and can be shared with other tools) sits underneath.
 
 ### Send an agent to the background — and bring it back
 
@@ -505,6 +507,13 @@ agents logs <id> --full                 # the full raw transcript / stdout (toke
 agents logs <id> -f                     # re-attach to a running one and follow
 agents view claude --host gpu-box       # inspect the remote install
 agents sync --host gpu-box              # make the remote machine current
+agents doctor claude                    # diagnose every installed claude version
+agents doctor claude@latest             # diagnose only the newest installed version
+agents doctor claude@oldest             # diagnose only the oldest installed version
+agents doctor claude@pinned             # diagnose the global-default (pinned) version
+agents doctor claude@all                # diagnose all versions, including isolated copies
+agents doctor claude@latest --fix       # auto-fix the newest installed version
+agents doctor claude@latest --device mac-mini  # diagnose newest claude on mac-mini
 agents doctor --devices                 # readiness matrix for every registered device
 agents doctor --devices --json          # machine-readable fleet readiness
 agents doctor --device mac-mini         # same matrix, scoped to one device
@@ -621,6 +630,8 @@ Four managed backends behind one interface (`agents cloud providers`):
 
 Auto-routes each `--agent` to its native cloud, or pin the backend with `--provider`. Instead of dispatching now, register a run as an **event trigger** with `--on pull_request` (also `push`, `issue_comment`, `workflow_run`) -- it persists as a trigger-bound routine that fires on the event. `--json` on every subcommand for scripting.
 
+The same dispatch is a placement on `agents run`: `agents run claude "fix the flaky e2e" --cloud --repo acme/api` routes through the identical provider registry and tracks in `agents cloud list/status/logs` alike. `--cloud` sits alongside `--host`/`--device`/`--lease` as one of three placements (local, machine, cloud) and is mutually exclusive with them; `--where cloud[:provider]` is the one-door spelling. Agents without a native cloud fail loud unless `--provider` is given.
+
 ---
 
 ## Workflows
@@ -1070,7 +1081,7 @@ The dropdown surfaces a **NEEDS YOU** queue (agents waiting on a question, a pla
 
 ### Quick-issue bar (⌘⇧O)
 
-Press `Cmd-Shift-O` anywhere for a thin capture surface: type a one-line note, `Cmd-V` to paste, and attach one or more recent screenshots (double-click a thumbnail to preview it in full). Submit, and a headless agent picks the right project from your recent sessions, investigates, and files the Linear ticket itself -- you never leave what you were doing.
+Press `Cmd-Shift-O` anywhere for a thin capture surface: the prepared text field appears immediately while repo, thumbnail, and ticket rows hydrate in the background. Type a one-line note, `Cmd-V` to paste, and attach one or more recent screenshots (double-click a thumbnail to preview it in full). Submit, and a headless agent picks the right project from your recent sessions, investigates, and files the Linear ticket itself -- you never leave what you were doing.
 
 The bar also lists the **open Linear tickets of the repo you picked**, urgent first. Switching the repo switches the Linear project; typing filters the list, so an existing ticket shows up before you file a duplicate; and clicking a row (or `⌘1`-`⌘5`) dispatches that ticket to the selected agents -- **Run** implements it, **Plan** posts a plan as a ticket comment.
 

package/dist/commands/cloud.d.ts

@@ -6,7 +6,6 @@
  * All tasks are tracked locally in a SQLite database for cross-provider listing.
  */
 import type { Command } from 'commander';
-/** Print an error message to stderr and exit. */
 /** Return a chalk color function appropriate for the given task status. */
 export declare function statusColor(status: string): (s: string) => string;
 /** Register the `agents cloud` command tree (run, list, status, logs, cancel, message, providers). */

package/dist/commands/cloud.js

@@ -1,43 +1,12 @@
 import chalk from 'chalk';
 import { die, relTime, truncate, isJsonMode } from '../lib/format.js';
-import * as fs from 'fs';
-import * as path from 'path';
-import ora from 'ora';
 import { resolveProvider, getAllProviders, getDefaultProviderId } from '../lib/cloud/registry.js';
 import { insertTask, updateTaskStatus, getTaskById, listTasks as listStoredTasks, listActiveTasks } from '../lib/cloud/store.js';
 import { renderStream } from '../lib/cloud/stream.js';
-import { MissingTargetError, MAX_IMAGES_PER_DISPATCH } from '../lib/cloud/types.js';
+import { MAX_IMAGES_PER_DISPATCH } from '../lib/cloud/types.js';
+import { resolveCloudPrompt, executeCloudDispatch } from '../lib/cloud/dispatch.js';
 import { normalizeTriggerEvent, validateTrigger, writeJob, setJobEnabled, jobExists, GITHUB_TRIGGER_EVENTS } from '../lib/routines.js';
 import { emit } from '../lib/events.js';
-import { shareRuntimeEnv } from '../lib/share/config.js';
-/** Map a supported image file extension to its wire mimeType. Rejects anything else. */
-function imageMimeFromPath(file) {
-    const ext = path.extname(file).toLowerCase();
-    if (ext === '.png')
-        return 'image/png';
-    if (ext === '.jpg' || ext === '.jpeg')
-        return 'image/jpeg';
-    if (ext === '.webp')
-        return 'image/webp';
-    die(`Unsupported image type ${JSON.stringify(ext || file)}. Use .png, .jpg/.jpeg, or .webp.`);
-}
-/** Read one image file into a base64 ImageAttachment, dying with a clear error if it's missing. */
-function readImageAttachment(file) {
-    if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {
-        die(`Image not found: ${file}`);
-    }
-    const mimeType = imageMimeFromPath(file);
-    return { data: fs.readFileSync(file).toString('base64'), mimeType };
-}
-/** Parse a `--skill <id>` value (`id` or `id@version`) into a SkillRef. */
-function parseSkillRef(raw) {
-    const at = raw.lastIndexOf('@');
-    if (at > 0) {
-        return { id: raw.slice(0, at), version: raw.slice(at + 1) };
-    }
-    return { id: raw };
-}
-/** Print an error message to stderr and exit. */
 /** Return a chalk color function appropriate for the given task status. */
 export function statusColor(status) {
     switch (status) {
@@ -52,47 +21,6 @@ export function statusColor(status) {
         default: return chalk.white;
     }
 }
-/**
- * After a `MissingTargetError`, try to resolve the target interactively.
- * Returns the chosen id, or undefined when no interactive resolution is
- * possible (non-TTY/JSON, provider can't enumerate, or user cancels) — the
- * caller then prints the error's guidance.
- *
- * Codex has no `listTargets` (no list-environments CLI), so it always returns
- * undefined here and the user sees the `codex cloud` guidance. Factory lists
- * Droid Computers; if listing fails (not signed in) or parses to nothing, we
- * fall back to a free-text prompt so a dispatch is never hard-blocked.
- */
-async function pickMissingTarget(provider, err, json) {
-    if (json || !process.stdout.isTTY)
-        return undefined;
-    if (!provider.listTargets)
-        return undefined;
-    const { select, input } = await import('@inquirer/prompts');
-    const promptName = err.kind === 'env' ? 'environment' : 'computer';
-    let targets;
-    try {
-        targets = await provider.listTargets();
-    }
-    catch (listErr) {
-        process.stderr.write(chalk.dim(`Could not list ${promptName}s: ${listErr.message}\n`));
-        targets = [];
-    }
-    try {
-        if (targets.length > 0) {
-            return await select({
-                message: `Select a ${promptName}`,
-                choices: targets.map((t) => ({ value: t.id, name: t.label ? `${t.id}  ${chalk.dim(t.label)}` : t.id })),
-            });
-        }
-        const typed = (await input({ message: `No ${promptName}s found. Enter a ${promptName} name (blank to cancel):` })).trim();
-        return typed || undefined;
-    }
-    catch {
-        // User hit Ctrl-C / Esc on the prompt.
-        return undefined;
-    }
-}
 /** Register the `agents cloud` command tree (run, list, status, logs, cancel, message, providers). */
 export function registerCloudCommands(program) {
     const cloud = program
@@ -201,23 +129,16 @@ Examples:
 
   # Default provider (set in ~/.agents/agents.yaml)
   agents cloud run "refactor auth module" --repo user/repo
+
+  # Same dispatch as a run placement: agents run <agent> "<task>" --cloud
 `)
         .action(async (positionalPrompt, options) => {
         const json = isJsonMode(options);
         // Resolve prompt: --prompt flag, positional arg, or file
-        let prompt = options.prompt || positionalPrompt;
-        if (!prompt)
-            die('Prompt is required. Pass it as an argument or with --prompt.', 1, { json, hint: 'agents cloud run "<task>" --repo <owner/repo>' });
-        // If prompt is a file path, read it and tell the user
-        if (fs.existsSync(prompt) && fs.statSync(prompt).isFile()) {
-            const filePath = prompt;
-            const stat = fs.statSync(filePath);
-            const sizeKB = (stat.size / 1024).toFixed(1);
-            prompt = fs.readFileSync(filePath, 'utf-8').trim();
-            if (process.stderr.isTTY) {
-                process.stderr.write(chalk.dim(`Reading prompt from ${filePath} (${sizeKB} KB)\n`));
-            }
-        }
+        const prompt = resolveCloudPrompt(options.prompt || positionalPrompt, {
+            json,
+            hint: 'agents cloud run "<task>" --repo <owner/repo>',
+        });
         // --host names one of YOUR machines as the target — that only means
         // something to the host provider, so it implies --provider host rather
         // than silently riding along to a cloud backend that would ignore it.
@@ -247,9 +168,6 @@ Examples:
             model: options.model,
             providerOptions: {},
         };
-        const shareEnv = shareRuntimeEnv();
-        if (shareEnv)
-            dispatchOptions.env = shareEnv;
         if (options.env)
             dispatchOptions.providerOptions.env = options.env;
         if (options.computer)
@@ -329,101 +247,17 @@ Examples:
             }
             return;
         }
-        // Vision attachments + ride-along skills. Only wire them when the resolved
-        // provider advertises support — otherwise fail loud rather than silently
-        // drop the flags the user passed.
-        const imagePaths = Array.isArray(options.image) ? options.image : [];
-        const skillIds = Array.isArray(options.skill) ? options.skill : [];
-        const caps = provider.capabilities();
-        if (imagePaths.length > 0) {
-            if (!caps.images)
-                die(`${provider.name} does not support image attachments.`, 1, { json });
-            if (imagePaths.length > MAX_IMAGES_PER_DISPATCH) {
-                die(`Too many images: ${imagePaths.length}. Max is ${MAX_IMAGES_PER_DISPATCH} per dispatch.`, 1, { json });
-            }
-            dispatchOptions.images = imagePaths.map(readImageAttachment);
-        }
-        if (skillIds.length > 0) {
-            if (!caps.skills)
-                die(`${provider.name} does not support ride-along skills.`, 1, { json });
-            dispatchOptions.skills = skillIds.map(parseSkillRef);
-        }
-        // Dispatch. On a missing pre-provisioned target (Codex env / Factory
-        // computer), offer an interactive picker instead of a raw error.
-        const dispatchOnce = async () => {
-            const spinner = ora({ text: `Dispatching to ${provider.name}...`, stream: process.stderr }).start();
-            try {
-                const t = await provider.dispatch(dispatchOptions);
-                spinner.succeed(`Task ${t.id} dispatched to ${provider.name}`);
-                return t;
-            }
-            catch (err) {
-                spinner.fail('Dispatch failed');
-                throw err;
-            }
-        };
-        let task;
-        try {
-            task = await dispatchOnce();
-        }
-        catch (err) {
-            if (err instanceof MissingTargetError) {
-                const picked = await pickMissingTarget(provider, err, json);
-                if (!picked) {
-                    die(err.guidance ? `${err.message}\n\n${err.guidance}` : err.message, 1, { json });
-                }
-                dispatchOptions.providerOptions[err.kind] = picked;
-                try {
-                    task = await dispatchOnce();
-                }
-                catch (err2) {
-                    die(err2.message, 1, { json });
-                }
-            }
-            else {
-                die(err.message, 1, { json });
-            }
-        }
-        // Persist locally
-        insertTask(task);
-        emit('cloud.dispatch', { module: 'cloud', taskId: task.id, agent: task.agent, provider: task.provider, status: task.status });
-        if (json) {
-            process.stdout.write(JSON.stringify(task) + '\n');
-        }
-        // Stream output unless --no-follow
-        if (options.follow === false)
-            return;
-        try {
-            // Live budget kill-switch (issue #399). Reuses makeLiveSpendWatcher to
-            // feed the provider's `usage` events into a shared watcher; on a cap
-            // breach we call provider.cancel(task.id) mid-stream. Dormant (returns
-            // null) when no caps are configured, so the raw stream flows unchanged.
-            const { wrapStreamWithBudgetGate } = await import('../lib/budget/live-cloud.js');
-            const gated = wrapStreamWithBudgetGate({
-                provider,
-                taskId: task.id,
-                project: task.repo ?? task.repos?.[0] ?? process.cwd(),
-                agent: task.agent ?? 'cloud',
-                cwd: process.cwd(),
-            });
-            const eventSource = gated ? gated.wrap(provider.stream(task.id)) : provider.stream(task.id);
-            const result = await renderStream(eventSource, { json });
-            updateTaskStatus(task.id, result.status, {
-                summary: result.summary,
-                prUrl: result.prUrl,
-            });
-            emit('cloud.complete', { module: 'cloud', taskId: task.id, status: result.status, prUrl: result.prUrl });
-            if (gated?.gate.breached()) {
-                const b = gated.gate.breach();
-                process.stderr.write(`[budget] cap ${b?.cap} exceeded — cancelled cloud task ${task.id}\n`);
-                process.exitCode = 7; // Mirrors BUDGET_KILL_EXIT_CODE for CI/headless.
-            }
-        }
-        catch (err) {
-            // Stream disconnect is OK — task keeps running
-            process.stderr.write(chalk.dim(`\nStream disconnected. Task ${task.id} continues running.\n`));
-            process.stderr.write(chalk.dim(`Check status: agents cloud status ${task.id}\n`));
-        }
+        // One dispatch path for every cloud surface — lib/cloud/dispatch.ts owns
+        // capability checks, the missing-target picker, persistence, streaming,
+        // and the budget kill-switch.
+        await executeCloudDispatch({
+            provider,
+            dispatchOptions,
+            imagePaths: Array.isArray(options.image) ? options.image : [],
+            skillIds: Array.isArray(options.skill) ? options.skill : [],
+            follow: options.follow !== false,
+            json,
+        });
     });
     // ── agents cloud list ─────────────────────────────────────────────────
     cloud

package/dist/commands/doctor.js

@@ -18,7 +18,8 @@ import { findAmbiguousDevicePins } from '../lib/routines.js';
 import chalk from 'chalk';
 import { checkAllClis, collectTeamsDoctorData } from '../lib/teams/agents.js';
 import { AGENTS, ALL_AGENT_IDS, resolveAgentName, formatAgentError, getAccountInfo } from '../lib/agents.js';
-import { getGlobalDefault, getVersionHomePath, isVersionInstalled, listInstalledVersions, parseAgentSpec, } from '../lib/versions.js';
+import { getVersionHomePath, listInstalledVersions, } from '../lib/versions.js';
+import { resolveAgentTargets, AgentSpecError } from '../lib/agent-spec/index.js';
 import { loadManifest, isStale } from '../lib/staleness/index.js';
 import { diffVersionResources, DOCTOR_ALL_KINDS, } from '../lib/doctor-diff.js';
 import { checkVersionHookWiring, inspectDuplicateVersionHooks, registerHooksToSettings } from '../lib/hooks.js';
@@ -370,29 +371,30 @@ async function runDevicesDoctor(opts) {
 function parseTargetArg(arg) {
     const at = arg.indexOf('@');
     const agentPart = at === -1 ? arg : arg.slice(0, at);
-    const versionPart = at === -1 ? '' : arg.slice(at + 1);
+    const qualifier = at === -1 ? '' : arg.slice(at + 1);
     const agent = resolveAgentName(agentPart);
     if (!agent)
         return { error: formatAgentError(agentPart) };
-    if (!versionPart) {
+    // No qualifier → non-isolated sweep of every installed version; --fix uses the non-isolated path
+    if (!qualifier) {
         const versions = listInstalledVersions(agent);
         if (versions.length === 0)
             return { error: `${AGENTS[agent].name} has no installed versions. Run \`agents add ${agent}@<version>\` first.` };
         return { agent, versions, versionExplicit: false };
     }
-    if (versionPart === 'default') {
-        const def = getGlobalDefault(agent);
-        if (!def)
-            return { error: `${AGENTS[agent].name} has no default version pinned. Run \`agents use ${agent}@<version>\`.` };
-        return { agent, versions: [def], versionExplicit: true };
+    // All explicit qualifiers (@all, @latest, @oldest, @default, @pinned, @x.y.z) → shared resolver
+    try {
+        const targets = resolveAgentTargets(`${agent}@${qualifier}`, { availableAgents: [agent] });
+        const versions = targets.map((t) => t.version).filter((v) => v !== null);
+        if (versions.length === 0)
+            return { error: `${AGENTS[agent].name} has no installed versions. Run \`agents add ${agent}@<version>\` first.` };
+        return { agent, versions, versionExplicit: true };
     }
-    const spec = parseAgentSpec(`${agent}@${versionPart}`);
-    if (!spec)
-        return { error: `Invalid version: ${versionPart}` };
-    if (!isVersionInstalled(agent, versionPart)) {
-        return { error: `${AGENTS[agent].name}@${versionPart} is not installed. Installed: ${listInstalledVersions(agent).join(', ') || '(none)'}` };
+    catch (e) {
+        if (e instanceof AgentSpecError)
+            return { error: e.message };
+        throw e;
     }
-    return { agent, versions: [versionPart], versionExplicit: true };
 }
 function parseKindFilter(arg) {
     if (!arg)