@phnx-labs/agents-cli 1.22.16 → 1.22.17

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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`.

package/README.md

@@ -507,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
@@ -623,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
@@ -1072,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)

package/dist/commands/exec.js

@@ -553,7 +553,7 @@ export function registerRunCommand(program) {
         .option('--budget <tokens>', 'Loop token hard-cap: stop once cumulative tokens reach this (stoppedBy: budget), enforced outside the agent. Loop only.')
         .option('--until <signal>', 'Loop stop condition. `signal` reads <runDir>/loop-signal.json {continue,reason} each iteration; absent or continue:false stops (fail-closed). Loop only.')
         .option('--interval <dur>', 'Loop delay between iterations ("0" back-to-back, "30m" paces). Loop only.')
-        .option('--where <spec>', 'Where this run\'s body executes (one placement door): local | device:<name> | auto | lease[:backend]. Expands to --host/--lease. Do not combine with those flags. See docs/00-concepts.md#placement.')
+        .option('--where <spec>', 'Where this run\'s body executes (one placement door): local | device:<name> | auto | lease[:backend] | cloud[:provider]. Expands to --host/--lease/--cloud. Do not combine with those flags. See docs/00-concepts.md#placement.')
         .option('--host <name>', 'Offload this run onto another machine over SSH — a device name, registered host, or user@host. Pass "auto" to pick from 14d usage affinity (most-used online device has highest probability). Same as --where device:<name>. See `agents devices`.')
         .option('--device <name>', 'Alias of --host. Pass "auto" for affinity-based device pick (same as --where auto).')
         .option('--remote-cwd <dir>', "Explicit host working directory for --host runs, used VERBATIM (overrides --cwd; usually --cwd suffices — it re-roots a local-home path onto the remote home). Pass a single-quoted '$HOME/…' or a valid remote absolute path; a local ~ expands here and won't exist there (/Users/you vs /home/you).")
@@ -567,7 +567,12 @@ export function registerRunCommand(program) {
         .option('--reuse', 'With --lease, reuse the most-recently-used warm box if one exists (else provision fresh). The scriptable form of the interactive reuse picker.')
         .option('--bare', 'With --lease, skip copying your local ~/.agents setup (skills/hooks/commands/MCP) onto the box.')
         .option('--tailscale', 'Lease the box onto your tailnet (reachable only over Tailscale) rather than a public IP.')
-        .option('--no-tailscale', 'Force a public-IP lease even when a reuse context would default to Tailscale.');
+        .option('--no-tailscale', 'Force a public-IP lease even when a reuse context would default to Tailscale.')
+        .option('--cloud', 'Vendor cloud placement: dispatch to the agent\'s native cloud (claude→rush, codex→codex, droid→factory, antigravity→antigravity) and stream the result. Same dispatch as `agents cloud run --agent <agent>`; tracked by `agents cloud list/status/logs`. Same as --where cloud. Mutually exclusive with --host/--lease and local-run flags.')
+        .option('--provider <id>', 'With --cloud: override the agent\'s native cloud provider (rush | codex | factory | antigravity | host).')
+        .option('--repo <owner/repo>', 'With --cloud: GitHub repository. Repeatable for multi-repo dispatch (Rush Cloud only).', (val, prev) => [...prev, val], [])
+        .option('--branch <name>', 'With --cloud: target git branch.')
+        .option('--cloud-env <id>', 'With --cloud: Codex Cloud environment ID (run\'s --env is the KEY=VAL passthrough, so the cloud env id gets its own flag).');
     // `--on` and `--computer` are hidden aliases of `--host` — same behavior.
     runCmd.addOption(new Option('--on <name>', 'Alias of --host.').hideHelp());
     runCmd.addOption(new Option('--computer <name>', 'Alias of --host.').hideHelp());
@@ -608,6 +613,13 @@ export function registerRunCommand(program) {
       agents run claude "…" --where auto                 # = --device auto
       agents run claude "fix CI" --where lease --mode edit
 
+      # Vendor cloud placement — the agent's own cloud runs the task and
+      # agents cloud list/status/logs tracks it. Fire-and-forget: --no-follow
+      agents run claude "fix the flaky e2e" --cloud --repo acme/example
+      agents run codex "add parser tests" --cloud --cloud-env env_a1b2c3
+      agents run droid "QA the onboarding flow" --cloud --no-follow
+      agents run claude "…" --where cloud          # same as --cloud
+
       # Open the session in a terminal tab — detected from where your sessions
       # already run (Ghostty / iTerm / Terminal.app); force one with a value
       agents run claude --terminal
@@ -668,6 +680,15 @@ export function registerRunCommand(program) {
 
       Fallback: --fallback codex,antigravity retries on rate-limit failure via /continue handoff. Each entry accepts @version.
 
+      Cloud placement: --cloud sends the run to the agent's native vendor cloud
+        (claude→rush, codex→codex, droid→factory, antigravity→antigravity) — the
+        same dispatch as agents cloud run --agent <agent>, tracked by agents
+        cloud list/status/logs/cancel/message. --provider overrides the routing;
+        --repo/--branch/--cloud-env refine the task. Agents without a native
+        cloud (kimi, grok, cursor, opencode, …) fail loud unless --provider is
+        given. --cloud is mutually exclusive with --host/--lease and with
+        local-run flags (--loop, --resume, --secrets, --terminal, …).
+
       Resume: --resume <id> resolves full IDs locally first, then fleet-wide, and restores the source version/device/mode. Claude, Codex, Grok, Kimi, Droid, and Cursor use version-gated native resume; others replay via /continue. agents resume <id> infers the harness too.
 
       Passthrough: everything after -- is forwarded verbatim to the underlying agent CLI.
@@ -694,6 +715,17 @@ export function registerRunCommand(program) {
             // a native flag, not a prompt. Run interactively.
             prompt = undefined;
         }
+        // --cloud: vendor cloud placement. Validate BEFORE the terminal handoff
+        // and every local dispatch path — flags like --terminal/--loop/--resume
+        // belong to the local runner and must error, never ride along silently.
+        if (options.cloud || (typeof options.where === 'string' && /^cloud(:|$)/i.test(options.where.trim()))) {
+            const { runCloudConflicts } = await import('./run-cloud.js');
+            const conflicts = runCloudConflicts(options);
+            if (conflicts.length > 0) {
+                console.error(chalk.red(`--cloud is a vendor cloud placement; these only apply to local/machine runs: ${conflicts.join(', ')}. Drop them, or drop --cloud.`));
+                process.exit(1);
+            }
+        }
         // --terminal: this process can't host the TUI (a menu-bar click, a script),
         // so hand the run to a real terminal and exit. Resolved from the user's own
         // live sessions, so it opens where they already work. Done before every
@@ -703,9 +735,9 @@ export function registerRunCommand(program) {
             await handleTerminalHandoff(agentSpec, options, prompt);
             return;
         }
-        // Placement: --where expands into --host / --lease before any dispatch.
-        // One door for "where does the body run?" — old flags remain aliases.
-        // See lib/placement.ts and docs/00-concepts.md#placement.
+        // Placement: --where expands into --host / --lease / --cloud before any
+        // dispatch. One door for "where does the body run?" — old flags remain
+        // aliases. See lib/placement.ts and docs/00-concepts.md#placement.
         {
             const { placementFromRunFlags, expandPlacementToRunFlags, PlacementError } = await import('../lib/placement.js');
             try {
@@ -720,6 +752,10 @@ export function registerRunCommand(program) {
                         options.lease = expanded.lease;
                     if (expanded.box !== undefined)
                         options.box = expanded.box;
+                    if (expanded.cloud !== undefined)
+                        options.cloud = expanded.cloud;
+                    if (expanded.provider !== undefined)
+                        options.provider = expanded.provider;
                     // Clear the where flag so remote re-entry (host dispatch) does not
                     // re-expand and conflict with the concrete host we just set.
                     options.where = undefined;
@@ -733,6 +769,22 @@ export function registerRunCommand(program) {
                 throw err;
             }
         }
+        // Cloud refinement flags without the placement are a typo, not a no-op.
+        if (!options.cloud) {
+            const { cloudFlagsWithoutCloud } = await import('./run-cloud.js');
+            const stray = cloudFlagsWithoutCloud(options);
+            if (stray.length > 0) {
+                console.error(chalk.red(`${stray.join(', ')} ${stray.length > 1 ? 'require' : 'requires'} --cloud (vendor cloud placement).`));
+                process.exit(1);
+            }
+        }
+        // --cloud: dispatch through the cloud provider registry and return — the
+        // run never touches the local/host/lease paths below.
+        if (options.cloud) {
+            const { handleRunCloud } = await import('./run-cloud.js');
+            await handleRunCloud(agentSpec, prompt, options, command);
+            return;
+        }
         // --notify: post a desktop notification when this run finishes. Armed on
         // process exit so it covers EVERY dispatch path below (local, --host,
         // --lease, the error path) instead of one branch. Only for headless runs

package/dist/commands/feed.d.ts

@@ -20,6 +20,7 @@ import { type OpenBlock } from '../lib/feed.js';
 import { type OutcomeGroup, type SessionOutcomeHint } from '../lib/feed-outcome.js';
 import { filterBlocksForFeed } from '../lib/ask-classifier.js';
 import { type FeedSessionSignal } from '../lib/feed-ranking.js';
+export declare const FEED_POST_HELP = "\nExamples:\n  # Title (subject) + body. Phone broadcasts put title first, body after a\n  # blank line, then a \"Sent from agent/session on host\" footer.\n  agents feed post --title \"CHANGELOG pushed\" \"Watching CI and mac-mini E2E\"\n  agents feed post --title \"Cover ready\" \"render at ./out/cover.png\" --attach ./out/cover.png\n  agents feed post --title \"Ready for review\" \"PR opened, waiting on prix-cloud\" --json\n\n  # Worth interrupting someone over - reaches sinks gated on minLevel: important:\n  agents feed post --title \"npm token expired\" \"Cannot publish the release\" --level important\n\n  # Stuck: opens a needs-you block and always broadcasts at important:\n  agents feed post --title \"Force-push denied\" \"git-guard blocked PR #1749\" --blocked\n  agents feed post --title \"Publish or wait?\" \"npm publish now or after review\" --blocked --option publish --option wait\n  agents feed post --title \"Delete preview env?\" \"stale preview still running\" --blocked --default \"leave it\"\n\n  # Exhaust self-serve FIRST. A block is for what you genuinely cannot do:\n  # a credential only the user holds, a decision only they can make, an\n  # approval only they can give. Not \"should I do the obvious next step?\".\n\n  # Outside a run, pass the session explicitly:\n  agents feed post --title \"Manual note\" \"context for the next agent\" --session 00998b0e-2d15-4d2f-a58b-974a886c9b47\n\nIdentity (session, agent, host, runtime, pid, launchId) is stamped automatically\nand rides the phone footer of feed.broadcast {message}. Domain facts (tickets,\nPRs) are not CLI flags - the ticket is joined from the session index at post\ntime. No em-dashes in title/body - they are scrubbed on the way out.\n\nConfigure where a post is mirrored under feed.broadcast in agents.yaml - see\ndocs/06-observability.md. A milestone is always recorded, but it does not text\nthe owner when the sink has minLevel: important. Add --level important for a\nphone-worthy successful update. Use --blocked only when work cannot continue.\nThe owner destination comes from humans.yaml; do not duplicate it in agents.yaml.\n";
 export declare const FEED_NO_FANOUT_ENV = "AGENTS_FEED_LOCAL";
 /** Right-hand masthead summary: `N blocks · M agents`. */
 export declare function formatFeedMastheadRight(blocks: OpenBlock[]): string;

package/dist/commands/feed.js

@@ -21,6 +21,40 @@ import { GLYPH, masthead } from '../lib/comms-render.js';
 import { discoverSessions } from '../lib/session/discover.js';
 import { resolveProvider } from '../lib/cloud/registry.js';
 import { buildSessionSignals, rankFeedBlocks, synthesizeControlCards, } from '../lib/feed-ranking.js';
+export const FEED_POST_HELP = `
+Examples:
+  # Title (subject) + body. Phone broadcasts put title first, body after a
+  # blank line, then a "Sent from agent/session on host" footer.
+  agents feed post --title "CHANGELOG pushed" "Watching CI and mac-mini E2E"
+  agents feed post --title "Cover ready" "render at ./out/cover.png" --attach ./out/cover.png
+  agents feed post --title "Ready for review" "PR opened, waiting on prix-cloud" --json
+
+  # Worth interrupting someone over - reaches sinks gated on minLevel: important:
+  agents feed post --title "npm token expired" "Cannot publish the release" --level important
+
+  # Stuck: opens a needs-you block and always broadcasts at important:
+  agents feed post --title "Force-push denied" "git-guard blocked PR #1749" --blocked
+  agents feed post --title "Publish or wait?" "npm publish now or after review" --blocked --option publish --option wait
+  agents feed post --title "Delete preview env?" "stale preview still running" --blocked --default "leave it"
+
+  # Exhaust self-serve FIRST. A block is for what you genuinely cannot do:
+  # a credential only the user holds, a decision only they can make, an
+  # approval only they can give. Not "should I do the obvious next step?".
+
+  # Outside a run, pass the session explicitly:
+  agents feed post --title "Manual note" "context for the next agent" --session 00998b0e-2d15-4d2f-a58b-974a886c9b47
+
+Identity (session, agent, host, runtime, pid, launchId) is stamped automatically
+and rides the phone footer of feed.broadcast {message}. Domain facts (tickets,
+PRs) are not CLI flags - the ticket is joined from the session index at post
+time. No em-dashes in title/body - they are scrubbed on the way out.
+
+Configure where a post is mirrored under feed.broadcast in agents.yaml - see
+docs/06-observability.md. A milestone is always recorded, but it does not text
+the owner when the sink has minLevel: important. Add --level important for a
+phone-worthy successful update. Use --blocked only when work cannot continue.
+The owner destination comes from humans.yaml; do not duplicate it in agents.yaml.
+`;
 export const FEED_NO_FANOUT_ENV = 'AGENTS_FEED_LOCAL';
 /** Right-hand masthead summary: `N blocks · M agents`. */
 export function formatFeedMastheadRight(blocks) {
@@ -239,44 +273,14 @@ export function registerFeedCommand(program) {
         .description('Post a status update to the fleet activity stream (for agents)')
         .argument('<text...>', 'Body: what just happened (after --title)')
         .requiredOption('--title <title>', 'Short subject, ~4-5 words (phone first line)')
-        .option('--session <id>', 'Session id escape hatch (default: auto from env / pid registry)')
+        .option('--session <id>', 'Session id escape hatch (default: auto from env / launch activity / pid registry)')
         .option('--attach <path-or-url...>', 'Attach an artifact (local file or URL); repeatable')
         .option('--level <level>', 'How loudly to broadcast: milestone (default) or important. Configured sinks with minLevel: important only fire on the latter.', 'milestone')
         .option('--blocked', 'You are STUCK and need the user. Opens an answerable block and always broadcasts at important - do not also pass --level.')
         .option('--option <label...>', 'With --blocked: an answer the user can pick; repeatable')
         .option('--default <answer>', 'With --blocked: a safe default policy may apply if nobody answers in time')
         .option('--json', 'Emit the written event as JSON')
-        .addHelpText('after', `
-Examples:
-  # Title (subject) + body. Phone broadcasts put title first, body after a
-  # blank line, then a "Sent from agent/session on host" footer.
-  agents feed post --title "CHANGELOG pushed" "Watching CI and mac-mini E2E"
-  agents feed post --title "Cover ready" "render at ./out/cover.png" --attach ./out/cover.png
-  agents feed post --title "Ready for review" "PR opened, waiting on prix-cloud" --json
-
-  # Worth interrupting someone over - reaches sinks gated on minLevel: important:
-  agents feed post --title "npm token expired" "Cannot publish the release" --level important
-
-  # Stuck: opens a needs-you block and always broadcasts at important:
-  agents feed post --title "Force-push denied" "git-guard blocked PR #1749" --blocked
-  agents feed post --title "Publish or wait?" "npm publish now or after review" --blocked --option publish --option wait
-  agents feed post --title "Delete preview env?" "stale preview still running" --blocked --default "leave it"
-
-  # Exhaust self-serve FIRST. A block is for what you genuinely cannot do:
-  # a credential only the user holds, a decision only they can make, an
-  # approval only they can give. Not "should I do the obvious next step?".
-
-  # Outside a run, pass the session explicitly:
-  agents feed post --title "Manual note" "context for the next agent" --session 00998b0e-2d15-4d2f-a58b-974a886c9b47
-
-Identity (session, agent, host, runtime, pid, launchId) is stamped automatically
-and rides the phone footer of feed.broadcast {message}. Domain facts (tickets,
-PRs) are not CLI flags - the ticket is joined from the session index at post
-time. No em-dashes in title/body - they are scrubbed on the way out.
-
-Configure where a post is mirrored under feed.broadcast in agents.yaml - see
-docs/06-observability.md.
-`)
+        .addHelpText('after', FEED_POST_HELP)
         .action(async (textParts, opts, cmd) => {
         // Parent `feed` also declares `--json` (for the list view). Commander
         // binds the flag on the parent, so a `feed post … --json` lands on

package/dist/commands/run-cloud.d.ts

@@ -0,0 +1,26 @@
+import type { Command } from 'commander';
+import type { CloudProvider } from '../lib/cloud/types.js';
+/** Error type for run --cloud validation failures (exit 1, red message). */
+export declare class RunCloudError extends Error {
+    constructor(message: string);
+}
+/** Flags the user passed that cannot ride a cloud placement. */
+export declare function runCloudConflicts(options: Record<string, unknown>): string[];
+/** Cloud-only flags passed without the --cloud placement. */
+export declare function cloudFlagsWithoutCloud(options: Record<string, unknown>): string[];
+/** Agents that route to a native cloud provider (the registry's truth). */
+export declare function cloudCapableAgentIds(): string[];
+/**
+ * Resolve the cloud provider for a run: explicit --provider wins, else the
+ * agent's native cloud. An agent with no native cloud fails loud with the
+ * capable list — never a silent ride onto the configured default.
+ */
+export declare function resolveRunCloudProvider(agentId: string, explicitProvider?: string): CloudProvider;
+/** Validate the agent half of `agents run <agent> --cloud` and return the registry id. */
+export declare function resolveRunCloudAgent(agentSpec: string): string;
+/**
+ * Handle `agents run <agent> [prompt] --cloud`. Validation lives in the
+ * exported helpers above (unit-tested); this wires them to the shared
+ * dispatch core and dies on any validation failure.
+ */
+export declare function handleRunCloud(agentSpec: string, prompt: string | undefined, options: Record<string, unknown>, command: Command): Promise<void>;