@phnx-labs/agents-cli 1.22.16 → 1.22.18

package/dist/lib/cloud/dispatch.js

@@ -0,0 +1,214 @@
+/**
+ * Shared cloud dispatch core — the ONE path every cloud dispatch goes through.
+ *
+ * Both `agents cloud run` (commands/cloud.ts) and `agents run <agent> --cloud`
+ * (commands/run-cloud.ts) build a DispatchOptions + resolve a provider, then
+ * call executeCloudDispatch here. Behavior — capability checks, the missing-
+ * target picker, local persistence, event emission, streaming, and the live
+ * budget kill-switch — must not diverge between the two surfaces.
+ */
+import chalk from 'chalk';
+import * as fs from 'fs';
+import * as path from 'path';
+import ora from 'ora';
+import { die } from '../format.js';
+import { insertTask, updateTaskStatus } from './store.js';
+import { renderStream } from './stream.js';
+import { MissingTargetError, MAX_IMAGES_PER_DISPATCH } from './types.js';
+import { emit } from '../events.js';
+import { shareRuntimeEnv } from '../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 };
+}
+/**
+ * Resolve the prompt for a cloud dispatch: the raw value, or the contents of
+ * the file it points at (with a dim note on TTY). Dies when empty.
+ */
+export function resolveCloudPrompt(raw, opts) {
+    let prompt = raw;
+    if (!prompt)
+        die('Prompt is required. Pass it as an argument or with --prompt.', 1, { json: opts.json, hint: opts.hint });
+    // 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`));
+        }
+    }
+    return prompt;
+}
+/**
+ * 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;
+    }
+}
+/**
+ * Dispatch a cloud task and (unless follow=false) stream it to completion.
+ * Owns: share-env injection, capability checks, the dispatch spinner +
+ * missing-target picker, local persistence, event emission, and the budget
+ * kill-switch. Dies on any dispatch failure — callers never see a partial.
+ */
+export async function executeCloudDispatch(params) {
+    const { provider, dispatchOptions, follow, json } = params;
+    const imagePaths = params.imagePaths ?? [];
+    const skillIds = params.skillIds ?? [];
+    const shareEnv = shareRuntimeEnv();
+    if (shareEnv)
+        dispatchOptions.env = shareEnv;
+    // 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 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 (!follow)
+        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('../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`));
+    }
+}

package/dist/lib/feed-post.d.ts

@@ -72,10 +72,10 @@ export interface PostIdentity {
  * Resolve who is posting. Order:
  *  1. Explicit --session flag
  *  2. Env: AGENT_SESSION_ID / AGENTS_SESSION_ID / basename(AGENTS_MAILBOX_DIR)
- *  3. Env AGENT_LAUNCH_ID → match in pid registry
+ *  3. Env AGENT_LAUNCH_ID → match in pid registry or activity index
  *  4. Walk parent PIDs from startPid (default process.ppid) through by-pid registry
  */
-export declare function resolvePostIdentity(input: Pick<FeedPostInput, 'sessionId' | 'env' | 'cwd' | 'startPid' | 'getParentPid' | 'readEntry' | 'listEntries'>): PostIdentity | undefined;
+export declare function resolvePostIdentity(input: Pick<FeedPostInput, 'sessionId' | 'env' | 'cwd' | 'activityRoot' | 'startPid' | 'getParentPid' | 'readEntry' | 'listEntries'>): PostIdentity | undefined;
 /** Walk up to 16 ancestors looking for a by-pid registry entry with a session. */
 export declare function walkPidRegistry(startPid: number, getParent: (pid: number) => number | undefined, readEntry: (pid: number) => PidSessionEntry | undefined): PidSessionEntry | undefined;
 /** Best-effort parent pid of `pid` (Linux /proc, else `ps`). */

package/dist/lib/feed-post.js

@@ -16,7 +16,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { spawnSync } from 'child_process';
-import { appendActivityEvent, } from './activity.js';
+import { appendActivityEvent, readRecentActivity, } from './activity.js';
 import { resolveProjectNameForCwd, listProjectDefs } from './projects.js';
 import { getHistoryDir } from './state.js';
 import { machineId } from './machine-id.js';
@@ -30,7 +30,7 @@ export const STATUS_TITLE_MAX_CHARS = 60;
  * Resolve who is posting. Order:
  *  1. Explicit --session flag
  *  2. Env: AGENT_SESSION_ID / AGENTS_SESSION_ID / basename(AGENTS_MAILBOX_DIR)
- *  3. Env AGENT_LAUNCH_ID → match in pid registry
+ *  3. Env AGENT_LAUNCH_ID → match in pid registry or activity index
  *  4. Walk parent PIDs from startPid (default process.ppid) through by-pid registry
  */
 export function resolvePostIdentity(input) {
@@ -55,8 +55,12 @@ export function resolvePostIdentity(input) {
             registry = walkPidRegistry(start, getParent, readEntry);
         }
     }
+    const activity = launchId && !envSession && !registry?.sessionId
+        ? readRecentActivity({ root: input.activityRoot, maxBytesPerSession: 64 * 1024 })
+            .find((event) => event.launchId === launchId)
+        : undefined;
     // Prefer env session (explicit + managed run), fill gaps from registry.
-    const sessionId = envSession ?? registry?.sessionId;
+    const sessionId = envSession ?? registry?.sessionId ?? activity?.sessionId;
     if (!sessionId || !isValidMailboxId(sessionId))
         return undefined;
     const mailboxFromEnv = mailboxIdFromEnv(env);
@@ -66,17 +70,18 @@ export function resolvePostIdentity(input) {
     return {
         sessionId,
         mailboxId,
-        host: machineIdFromEnv(env),
-        runtime: env.AGENTS_RUNTIME?.trim() || 'headless',
+        host: activity?.host ?? machineIdFromEnv(env),
+        runtime: env.AGENTS_RUNTIME?.trim() || activity?.runtime || 'headless',
         agent: env.AGENTS_AGENT_NAME?.trim()
             || registry?.agent
+            || activity?.agent
             || detectAgentKind(env),
         cwd: input.cwd
-            ?? (env.AGENTS_CWD?.trim() || registry?.cwd || process.cwd()),
-        pid: registry?.pid,
-        launchId: launchId || registry?.launchId,
-        terminalId: env.AGENT_TERMINAL_ID?.trim() || registry?.terminalId,
-        tmuxPane: env.TMUX_PANE?.trim() || registry?.tmuxPane,
+            ?? (env.AGENTS_CWD?.trim() || registry?.cwd || activity?.cwd || process.cwd()),
+        pid: registry?.pid ?? activity?.pid,
+        launchId: launchId || registry?.launchId || activity?.launchId,
+        terminalId: env.AGENT_TERMINAL_ID?.trim() || registry?.terminalId || activity?.terminalId,
+        tmuxPane: env.TMUX_PANE?.trim() || registry?.tmuxPane || activity?.tmuxPane,
     };
 }
 function firstValidId(candidates) {

package/dist/lib/hosts/remote-cmd.js

@@ -118,6 +118,14 @@ export const RUN_OPTION_FORWARDING = {
     bare: 'local-only', // skips the local setup-copy push; lease-only concern
     tailscale: 'local-only', // --tailscale/--no-tailscale gate the lease net mode; never forwarded
     copyCreds: 'local-only', // copies creds TO the host before dispatch — local concern only
+    // Cloud placement: chosen and dispatched from THIS machine via the provider
+    // registry; mutually exclusive with --host (placement conflict dies before
+    // dispatch), so these never have a remote argv to ride.
+    cloud: 'local-only',
+    provider: 'local-only',
+    repo: 'local-only',
+    branch: 'local-only',
+    cloudEnv: 'local-only',
     authCheck: 'local-only', // --no-auth-check gates the local interactive login preflight; --host runs skip that preflight entirely
     // The notification must land on the box the PERSON is at — the one that
     // dispatched — not on a headless worker with no desktop to post to. The local

package/dist/lib/humans.d.ts

@@ -12,8 +12,9 @@ export declare function readHumans(): HumansConfig | null;
  */
 export declare function writeHumans(config: HumansConfig): void;
 /**
- * Return the effective owner notification config from humans.yaml if
- * available, otherwise return null (caller falls back to agents.yaml).
+ * Return the effective owner notification destination from humans.yaml.
+ * The owner's normal-severity policy selects the channel; when no normal
+ * policy is declared, the first addressable channel is the default.
  */
 export declare function getOwnerNotifyFromHumans(): {
     channel: string;

package/dist/lib/humans.js

@@ -5,8 +5,7 @@
  * Schema version: 1
  *
  * This module is the single read/write seam for humans.yaml. All channel/
- * notify consumers should read owner config from here (with a fallback to
- * the legacy notify.owner in agents.yaml during the migration window).
+ * notify consumers should read owner config from here.
  */
 import * as fs from 'fs';
 import * as yaml from 'yaml';
@@ -47,14 +46,23 @@ export function writeHumans(config) {
     fs.writeFileSync(filePath, HUMANS_HEADER + body, { encoding: 'utf-8', mode: 0o600 });
 }
 /**
- * Return the effective owner notification config from humans.yaml if
- * available, otherwise return null (caller falls back to agents.yaml).
+ * Return the effective owner notification destination from humans.yaml.
+ * The owner's normal-severity policy selects the channel; when no normal
+ * policy is declared, the first addressable channel is the default.
  */
 export function getOwnerNotifyFromHumans() {
-    const humans = readHumans();
-    const notify = humans?.owner?.notify;
-    if (notify?.channel && notify?.to)
-        return notify;
+    const owner = readHumans()?.owner;
+    const channels = owner?.channels ?? [];
+    const preferredIds = owner?.policy?.normal ?? [];
+    const preferred = preferredIds
+        .map((id) => channels.find((entry) => entry.id === id))
+        .find((entry) => entry?.to);
+    const selected = preferred ?? channels.find((entry) => entry.to);
+    if (selected?.id && selected.to)
+        return { channel: selected.id, to: selected.to };
+    const migrated = owner?.notify;
+    if (migrated?.channel && migrated.to)
+        return migrated;
     return null;
 }
 /**

package/dist/lib/notify.d.ts

@@ -4,7 +4,7 @@
  * Every human-facing owner notification (feed urgent-block dispatch, monitor
  * `notify` action, `agents notify`) funnels through the single channel seam:
  * `lookupTransport(channel, meta).provider.send(text, opts)`. The recipient comes
- * from `notify.owner` in agents.yaml — never a hardcoded chat id — so changing the
+ * from `humans.yaml` — never a hardcoded chat id — so changing the
  * owner is honoured by every path at once. `notify.transports` picks the actual
  * provider per host (rush telegram on zion, openclaw-telegram on mac-mini).
  * Best-effort: a delivery failure is returned to the caller, never thrown, so a
@@ -19,9 +19,9 @@ import type { SendResult } from './channels/registry.js';
 export interface OwnerNotifyOptions {
     /** Config source (defaults to `readMeta()`); lets callers/tests inject it. */
     meta?: Meta;
-    /** Override the owner channel from `notify.owner.channel`. */
+    /** Override the owner channel resolved from humans.yaml. */
     channel?: string;
-    /** Override the owner target from `notify.owner.to`. */
+    /** Override the owner target resolved from humans.yaml. */
     target?: string;
     /** Resolve + build the delivery but do not actually send. */
     dryRun?: boolean;
@@ -44,7 +44,7 @@ export declare function buildOpenClawNotifyArgs(text: string, opts: {
 }): string[];
 /**
  * Deliver a message to the configured owner through the one channel seam.
- * `channel`/`target` default to `notify.owner.{channel,to}`; `notify.transports`
+ * `channel`/`target` default to the normal owner channel in humans.yaml; `notify.transports`
  * selects the provider per host. A missing owner config or a delivery failure
  * (e.g. openclaw not on PATH) returns a clean `SendResult` error — never a raw
  * ENOENT — so callers surface a consistent, best-effort failure.

package/dist/lib/notify.js

@@ -34,17 +34,14 @@ export function buildOpenClawNotifyArgs(text, opts) {
 }
 /**
  * Deliver a message to the configured owner through the one channel seam.
- * `channel`/`target` default to `notify.owner.{channel,to}`; `notify.transports`
+ * `channel`/`target` default to the normal owner channel in humans.yaml; `notify.transports`
  * selects the provider per host. A missing owner config or a delivery failure
  * (e.g. openclaw not on PATH) returns a clean `SendResult` error — never a raw
  * ENOENT — so callers surface a consistent, best-effort failure.
  */
 export async function sendToOwner(text, options = {}) {
     const meta = options.meta ?? readMeta();
-    // humans.yaml is the primary source; agents.yaml notify.owner is the fallback.
-    const humansOwner = getOwnerNotifyFromHumans();
-    const legacyOwner = meta.notify?.owner;
-    const owner = humansOwner ?? legacyOwner;
+    const owner = getOwnerNotifyFromHumans() ?? meta.notify?.owner;
     const channel = options.channel ?? owner?.channel;
     const target = options.target ?? owner?.to;
     if (!channel || !target) {
@@ -52,7 +49,7 @@ export async function sendToOwner(text, options = {}) {
             ok: false,
             channel: channel ?? 'unknown',
             id: target ?? '',
-            error: 'notify.owner.{channel,to} not set in humans.yaml or agents.yaml',
+            error: 'No addressable owner channel configured in humans.yaml or legacy notify.owner',
         };
     }
     registerBuiltinProviders();
@@ -60,7 +57,11 @@ export async function sendToOwner(text, options = {}) {
     if (!provider) {
         return { ok: false, channel, id: target, error };
     }
-    return provider.send(text, { target, dryRun: options.dryRun });
+    return provider.send(text, {
+        target,
+        ownerScoped: options.target === undefined,
+        dryRun: options.dryRun,
+    });
 }
 export async function notifyUrgentBlock(block, options = {}) {
     if (block.notifiedAt) {

package/dist/lib/placement.d.ts

@@ -2,7 +2,7 @@
  * Placement — one model for "where does the body run?"
  *
  * The CLI grew several doors that all mean execution target:
- *   run --host / --device / --lease / --box
+ *   run --host / --device / --lease / --box / --cloud
  *   routines --placement / --run-on / hostStrategy
  *   monitors --run-on (body) vs --device (owner — NOT placement)
  *   teams --device (teammate pin)
@@ -41,6 +41,10 @@ export interface RunPlacementFlags {
     computer?: string;
     lease?: string | boolean;
     box?: string;
+    /** --cloud: vendor cloud placement (the agent's native cloud provider). */
+    cloud?: boolean;
+    /** --provider: refines the cloud placement; not a placement on its own. */
+    provider?: string;
 }
 export declare class PlacementError extends Error {
     constructor(message: string);
@@ -68,10 +72,10 @@ export declare function placementFromRunFlags(flags: RunPlacementFlags): Placeme
  * Expand a resolved placement into the concrete run option fields the
  * existing dispatch paths already understand. Pure — does not mutate input.
  *
- * `cloud` and `fleet` are not valid for a bare `agents run` (use `cloud run`
- * / routines); they throw so callers fail loud.
+ * `fleet` is not valid for a bare `agents run` (it is a routines placement);
+ * it throws so callers fail loud.
  */
-export declare function expandPlacementToRunFlags(placement: Placement): Pick<RunPlacementFlags, 'host' | 'device' | 'lease' | 'box'>;
+export declare function expandPlacementToRunFlags(placement: Placement): Pick<RunPlacementFlags, 'host' | 'device' | 'lease' | 'box' | 'cloud' | 'provider'>;
 /** Map routines hostStrategy (+ optional host) onto the shared Placement. */
 export declare function placementFromHostStrategy(strategy: 'local' | 'host' | 'fleet' | 'cloud', host?: string): Placement;
 /** One-line human form for logs / help. */

package/dist/lib/placement.js

@@ -2,7 +2,7 @@
  * Placement — one model for "where does the body run?"
  *
  * The CLI grew several doors that all mean execution target:
- *   run --host / --device / --lease / --box
+ *   run --host / --device / --lease / --box / --cloud
  *   routines --placement / --run-on / hostStrategy
  *   monitors --run-on (body) vs --device (owner — NOT placement)
  *   teams --device (teammate pin)
@@ -93,6 +93,7 @@ export function placementFromRunFlags(flags) {
     const hostT = hostFamilyTarget(flags);
     const hasLease = flags.lease !== undefined && flags.lease !== false;
     const hasBox = !!flags.box;
+    const hasCloud = flags.cloud === true;
     const placementFlags = [];
     if (where)
         placementFlags.push('--where');
@@ -102,12 +103,16 @@ export function placementFromRunFlags(flags) {
         placementFlags.push('--lease');
     if (hasBox)
         placementFlags.push('--box');
+    if (hasCloud)
+        placementFlags.push('--cloud');
     if (placementFlags.length > 1) {
         throw new PlacementError(`Conflicting placement flags: ${placementFlags.join(' + ')}. ` +
-            `Use one door — prefer --where (device:<name> | auto | lease | local).`);
+            `Use one door — prefer --where (device:<name> | auto | lease | cloud | local).`);
     }
     if (where)
         return parseWhereSpec(where, '--where');
+    if (hasCloud)
+        return { kind: 'cloud', target: flags.provider, source: '--cloud' };
     if (hasBox)
         return { kind: 'lease', target: flags.box, source: '--box' };
     if (hasLease) {
@@ -122,8 +127,8 @@ export function placementFromRunFlags(flags) {
  * Expand a resolved placement into the concrete run option fields the
  * existing dispatch paths already understand. Pure — does not mutate input.
  *
- * `cloud` and `fleet` are not valid for a bare `agents run` (use `cloud run`
- * / routines); they throw so callers fail loud.
+ * `fleet` is not valid for a bare `agents run` (it is a routines placement);
+ * it throws so callers fail loud.
  */
 export function expandPlacementToRunFlags(placement) {
     switch (placement.kind) {
@@ -140,12 +145,13 @@ export function expandPlacementToRunFlags(placement) {
             if (placement.source === '--box')
                 return { box: placement.target };
             return placement.target ? { lease: placement.target } : { lease: true };
+        case 'cloud':
+            // Vendor cloud placement — `--where cloud[:provider]` expands to the
+            // --cloud flag (+ --provider refinement) the run action dispatches on.
+            return placement.target ? { cloud: true, provider: placement.target } : { cloud: true };
         case 'fleet':
             throw new PlacementError(`fleet placement is for routines (agents routines add … --placement fleet), not agents run. ` +
                 `Use --where device:auto for an affinity pick, or --where device:<name>.`);
-        case 'cloud':
-            throw new PlacementError(`cloud placement is agents cloud run (vendor cloud), not agents run. ` +
-                `For a disposable box use --where lease; for your fleet use --where device:<name>.`);
     }
 }
 /** Map routines hostStrategy (+ optional host) onto the shared Placement. */
@@ -180,9 +186,9 @@ export const PLACEMENT_MATRIX = `
   Affinity pick (14d usage)      --where auto            (= --device auto)
   Disposable cloud box           --where lease           (= --lease)
   Reuse warm crabbox             --box <slug>
+  Vendor cloud task              --cloud   (= --where cloud[:provider])
   Routines: body on one box      --run-on <name> / --placement host
   Routines: pick any online      --placement fleet
-  Vendor cloud task              agents cloud run …
   Monitors: who evaluates        --device <owner>   (NOT body placement)
   Monitors: where action runs    --run-on <host>
 `.trim();