@phnx-labs/agents-cli 1.22.16 → 1.22.17

package/dist/commands/run-cloud.js

@@ -0,0 +1,162 @@
+/**
+ * `agents run <agent> [prompt] --cloud` — the vendor-cloud placement for a run.
+ *
+ * One of three run placements: local (default), machine (--host/--device,
+ * --lease), cloud (--cloud). Routing goes through the cloud provider registry
+ * exactly like `agents cloud run --agent <agent>`: the agent's native
+ * `cloudProvider` wins, `--provider` overrides. The dispatch itself is the
+ * shared core in lib/cloud/dispatch.ts — this module only validates the run
+ * surface and translates run flags into a DispatchOptions.
+ */
+import chalk from 'chalk';
+import { AGENTS, resolveAgentName, isAgentHardDeprecated, hardDeprecationError } from '../lib/agents.js';
+import { RUN_AUTO_KEYWORD } from '../lib/types.js';
+import { resolveProvider, nativeProviderForAgent } from '../lib/cloud/registry.js';
+import { resolveCloudPrompt, executeCloudDispatch } from '../lib/cloud/dispatch.js';
+/** Error type for run --cloud validation failures (exit 1, red message). */
+export class RunCloudError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RunCloudError';
+    }
+}
+/**
+ * Run flags that are meaningless on a cloud placement. Each entry maps the
+ * option field to the flag the user typed. Cloud tasks run in the provider's
+ * workspace on the provider's accounts, so local-run knobs (account strategy,
+ * secrets injection, loop guards, resume, terminal handoff, cwd) have nothing
+ * to act on — passing one is an error, never a silent ignore.
+ */
+const RUN_CLOUD_CONFLICTS = [
+    { field: 'terminal', flag: '--terminal', set: (v) => v !== undefined && v !== false },
+    { field: 'interactive', flag: '--interactive', set: (v) => v === true },
+    { field: 'acp', flag: '--acp', set: (v) => v === true },
+    { field: 'loop', flag: '--loop', set: (v) => v === true },
+    { field: 'resumeCheckpoint', flag: '--resume-checkpoint', set: (v) => v !== undefined },
+    { field: 'maxIterations', flag: '--max-iterations', set: (v) => v !== undefined },
+    { field: 'budget', flag: '--budget', set: (v) => v !== undefined },
+    { field: 'until', flag: '--until', set: (v) => v !== undefined },
+    { field: 'interval', flag: '--interval', set: (v) => v !== undefined },
+    { field: 'resume', flag: '--resume', set: (v) => v !== undefined && v !== false },
+    { field: 'sessionId', flag: '--session-id', set: (v) => v !== undefined },
+    { field: 'secrets', flag: '--secrets', set: (v) => Array.isArray(v) && v.length > 0 },
+    { field: 'secretsKeys', flag: '--secrets-keys', set: (v) => v !== undefined },
+    { field: 'allowExpired', flag: '--allow-expired', set: (v) => v === true },
+    { field: 'autoSecrets', flag: '--no-auto-secrets', set: (v) => v === false },
+    { field: 'copyCreds', flag: '--copy-creds', set: (v) => v === true },
+    { field: 'fallback', flag: '--fallback', set: (v) => v !== undefined },
+    { field: 'strategy', flag: '--strategy', set: (v) => v !== undefined },
+    { field: 'balanced', flag: '--balanced', set: (v) => v === true },
+    { field: 'cwd', flag: '--cwd', set: (v) => v !== undefined },
+    { field: 'project', flag: '--project', set: (v) => v !== undefined },
+    { field: 'addDir', flag: '--add-dir', set: (v) => Array.isArray(v) && v.length > 0 },
+    { field: 'remoteCwd', flag: '--remote-cwd', set: (v) => v !== undefined },
+    { field: 'env', flag: '--env', set: (v) => Array.isArray(v) && v.length > 0 },
+    { field: 'notify', flag: '--notify', set: (v) => v === true },
+    // effort defaults to 'auto' on run; only an explicit non-default value is a
+    // conflict (no provider consumes an effort option — it would be dropped).
+    { field: 'effort', flag: '--effort', set: (v) => v !== undefined && v !== 'auto' },
+    // --name seeds the LOCAL session label; a cloud task has no local session.
+    { field: 'name', flag: '--name', set: (v) => v !== undefined },
+];
+/** Flags that refine a cloud dispatch; meaningless without the placement. */
+const CLOUD_ONLY_FLAGS = [
+    { field: 'provider', flag: '--provider', set: (v) => v !== undefined },
+    { field: 'repo', flag: '--repo', set: (v) => Array.isArray(v) && v.length > 0 },
+    { field: 'branch', flag: '--branch', set: (v) => v !== undefined },
+    { field: 'cloudEnv', flag: '--cloud-env', set: (v) => v !== undefined },
+];
+/** Flags the user passed that cannot ride a cloud placement. */
+export function runCloudConflicts(options) {
+    return RUN_CLOUD_CONFLICTS.filter((c) => c.set(options[c.field])).map((c) => c.flag);
+}
+/** Cloud-only flags passed without the --cloud placement. */
+export function cloudFlagsWithoutCloud(options) {
+    return CLOUD_ONLY_FLAGS.filter((c) => c.set(options[c.field])).map((c) => c.flag);
+}
+/** Agents that route to a native cloud provider (the registry's truth). */
+export function cloudCapableAgentIds() {
+    return Object.values(AGENTS)
+        .filter((a) => a.cloudProvider)
+        .map((a) => a.id)
+        .sort();
+}
+/**
+ * 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 function resolveRunCloudProvider(agentId, explicitProvider) {
+    if (explicitProvider)
+        return resolveProvider(explicitProvider);
+    if (!nativeProviderForAgent(agentId)) {
+        throw new RunCloudError(`${agentId} has no native cloud. Cloud-capable agents: ${cloudCapableAgentIds().join(', ')}. ` +
+            `Override with --provider <id> (rush | codex | factory | antigravity | host).`);
+    }
+    return resolveProvider(undefined, agentId);
+}
+/** Validate the agent half of `agents run <agent> --cloud` and return the registry id. */
+export function resolveRunCloudAgent(agentSpec) {
+    if (agentSpec === RUN_AUTO_KEYWORD || agentSpec.startsWith(`${RUN_AUTO_KEYWORD}@`)) {
+        throw new RunCloudError(`agents run auto --cloud: auto harness-pick is a local-run feature. ` +
+            `Name a cloud-capable agent: ${cloudCapableAgentIds().join(', ')}.`);
+    }
+    if (agentSpec.includes('@')) {
+        throw new RunCloudError(`Version pins (<agent>@<version>) do not apply to --cloud — the provider runs its own agent version. ` +
+            `Drop the pin: agents run ${agentSpec.split('@')[0]} "<task>" --cloud.`);
+    }
+    const agentId = resolveAgentName(agentSpec);
+    if (!agentId) {
+        throw new RunCloudError(`Unknown agent: ${agentSpec}. Cloud-capable agents: ${cloudCapableAgentIds().join(', ')}.`);
+    }
+    if (isAgentHardDeprecated(agentId)) {
+        throw new RunCloudError(hardDeprecationError(agentId));
+    }
+    return agentId;
+}
+/**
+ * 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 async function handleRunCloud(agentSpec, prompt, options, command) {
+    const json = options.json === true;
+    try {
+        const agentId = resolveRunCloudAgent(agentSpec);
+        const provider = resolveRunCloudProvider(agentId, options.provider);
+        const resolvedPrompt = resolveCloudPrompt(prompt, {
+            json,
+            hint: `agents run ${agentId} "<task>" --cloud${agentId === 'claude' ? ' --repo <owner/repo>' : ''}`,
+        });
+        const repoValues = Array.isArray(options.repo) ? options.repo : [];
+        const dispatchOptions = {
+            prompt: resolvedPrompt,
+            agent: agentId,
+            repo: repoValues[0],
+            repos: repoValues.length > 0 ? repoValues : undefined,
+            branch: options.branch,
+            timeout: options.timeout,
+            model: options.model,
+            providerOptions: {},
+        };
+        if (options.cloudEnv)
+            dispatchOptions.providerOptions.env = options.cloudEnv;
+        // --mode defaults to 'plan' on run; forward it only when the user set it.
+        if (command.getOptionValueSource('mode') === 'cli') {
+            dispatchOptions.providerOptions.mode = options.mode;
+        }
+        await executeCloudDispatch({
+            provider,
+            dispatchOptions,
+            follow: options.follow !== false,
+            json,
+        });
+    }
+    catch (err) {
+        if (err instanceof RunCloudError) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+        throw err;
+    }
+}

package/dist/commands/versions.js

@@ -438,8 +438,10 @@ export function registerVersionsCommands(program) {
                         console.log(chalk.gray(`  Created shim: ${getShimsDir()}/${agentConfig.cliCommand}`));
                     }
                     // Seed the fresh version home with user settings from the current
-                    // default version (settings.json, keybindings, codex config/auth).
-                    // Gap-filling only — never overwrites what the new home has.
+                    // default version (settings.json, keybindings, codex config).
+                    // Credentials are deliberately excluded so each version keeps its own
+                    // login (see SETTINGS_MANIFEST). Gap-filling only — never overwrites
+                    // what the new home has.
                     const carrySource = getGlobalDefault(agent);
                     if (carrySource && carrySource !== installedVersion) {
                         const carried = carryForwardSettings(agent, getVersionHomePath(agent, carrySource), getVersionHomePath(agent, installedVersion));

package/dist/commands/view.js

@@ -10,8 +10,7 @@ import { machineId } from '../lib/machine-id.js';
 import { authCacheKey, formatCheckedAge, readAuthHealthCache } from '../lib/auth-health.js';
 import { agentReportsUsage, deriveUsageStatusFromSnapshot, formatUsageSection, formatUsageSummary, formatUsageStatusBadge, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
 import { readManifest } from '../lib/manifest.js';
-import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, printTrashFooter, reconcileStaleLatestForAgent, isGlobalBinaryAgent, getLiveVersion, isVersionIsolated, getIsolatedDefault, } from '../lib/versions.js';
-import { formatKeptProjectResources } from '../lib/project-resources.js';
+import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, removeVersion, printTrashFooter, reconcileStaleLatestForAgent, isGlobalBinaryAgent, getLiveVersion, isVersionIsolated, getIsolatedDefault, } from '../lib/versions.js';
 import { ensureVersionedAliasCurrent, removeShim, } from '../lib/shims.js';
 import { getAgentResources } from '../lib/resources.js';
 import { renderMergedResources } from '../lib/merged-resources.js';
@@ -29,7 +28,6 @@ import { resolveConfiguredModel } from '../lib/models.js';
 import { listProfiles, profileExists, profileSummary, readProfile } from '../lib/profiles.js';
 import { getByokUsageForHarness, hasByokProvider, renderByokBar } from '../lib/byok-usage.js';
 import { renderHarnessDetail } from './harness.js';
-import { loadManifest, isStale } from '../lib/staleness/index.js';
 import { confirm } from '@inquirer/prompts';
 import { formatPath, isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { terminalWidth, truncateToWidth, stringWidth, padToWidth } from '../lib/session/width.js';
@@ -781,57 +779,6 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
     if (!filterAgentId) {
         renderHostClisSection(process.cwd());
     }
-    // Check for new resources when viewing a specific agent
-    if (filterAgentId && versionManaged.length > 0) {
-        const defaultVersion = getGlobalDefault(filterAgentId);
-        if (defaultVersion) {
-            const manifest = loadManifest(filterAgentId, defaultVersion);
-            const cwd = process.cwd();
-            if (manifest && !isStale(manifest, filterAgentId, defaultVersion, cwd)) {
-                return;
-            }
-            const available = getAvailableResources();
-            const synced = getActuallySyncedResources(filterAgentId, defaultVersion);
-            const projectOnly = getProjectOnlyResources();
-            const newResources = getNewResources(available, synced, projectOnly);
-            if (hasNewResources(newResources, filterAgentId, defaultVersion)) {
-                try {
-                    const selection = await promptNewResourceSelection(filterAgentId, newResources, defaultVersion);
-                    if (selection && Object.keys(selection).length > 0) {
-                        const result = syncResourcesToVersion(filterAgentId, defaultVersion, selection);
-                        const synced = [];
-                        if (result.commands)
-                            synced.push('commands');
-                        if (result.skills)
-                            synced.push('skills');
-                        if (result.hooks)
-                            synced.push('hooks');
-                        if (result.memory.length > 0)
-                            synced.push('memory');
-                        if (result.permissions)
-                            synced.push('permissions');
-                        if (result.mcp.length > 0)
-                            synced.push('mcp');
-                        if (result.plugins.length > 0)
-                            synced.push('plugins');
-                        if (result.workflows.length > 0)
-                            synced.push('workflows');
-                        if (synced.length > 0) {
-                            console.log(chalk.green(`\nSynced to ${agentLabel(filterAgentId)}@${defaultVersion}: ${synced.join(', ')}`));
-                        }
-                        const kept = formatKeptProjectResources(result.projectSkipped);
-                        if (kept)
-                            console.log(chalk.gray(kept));
-                    }
-                }
-                catch (err) {
-                    if (isPromptCancelled(err))
-                        return;
-                    throw err;
-                }
-            }
-        }
-    }
 }
 /**
  * Show detailed resources for a specific agent version.

package/dist/lib/agents.js

@@ -212,8 +212,10 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: true,
-        // Claude Code has no headless Anthropic-hosted dispatch CLI (only
-        // --remote-control, which bridges a *local* session). Its cloud is Rush.
+        // Claude Code grew a native `claude --cloud "<prompt>"` (Anthropic-managed
+        // infra, claude.ai/code; requires claude.ai subscription auth). Routing
+        // still goes to Rush Cloud deliberately — it keeps cloud tasks in one
+        // tracked fleet (agents cloud list/status/logs) regardless of harness.
         cloudProvider: 'rush',
         capabilities: { hooks: true, mcp: true, mcpHttp: true, mcpHeaders: true, allowlist: true, skills: true, commands: true, plugins: true, subagents: true, rules: { file: 'CLAUDE.md' }, workflows: true, memory: true, modes: ['plan', 'edit', 'auto', 'skip'], rulesImports: true, interactiveRepl: true },
     },

package/dist/lib/channels/send.d.ts

@@ -3,7 +3,7 @@
  *
  * One primitive: resolve a destination (channel + target), compose text + urls +
  * attachments, hand off to a channel provider. `notify` is the same path with
- * destination defaulted to `notify.owner` in agents.yaml — owner is an address
+ * destination defaulted from `humans.yaml` — owner is an address
  * alias (`--to owner`), not a separate stack.
  *
  * Agent control (`agents message`, `sessions inject`) stays outside this module.
@@ -60,8 +60,8 @@ export declare function isOwnerAlias(to: string | undefined): boolean;
 /** Compose body + optional URL lines (skip urls already present in the body). */
 export declare function composeSendText(text: string, urls?: string[]): string;
 /**
- * Read the owner destination; humans.yaml is the primary source, agents.yaml
- * notify.owner is the fallback. Returns null when neither is set.
+ * Read the owner destination. humans.yaml is canonical; notify.owner remains a
+ * migration fallback for installations that have not run the schema migration.
  */
 export declare function readOwnerDest(meta: Meta): {
     channel: string;

package/dist/lib/channels/send.js

@@ -18,19 +18,16 @@ export function composeSendText(text, urls) {
     return body ? `${body}\n${extra.join('\n')}` : extra.join('\n');
 }
 /**
- * Read the owner destination; humans.yaml is the primary source, agents.yaml
- * notify.owner is the fallback. Returns null when neither is set.
+ * Read the owner destination. humans.yaml is canonical; notify.owner remains a
+ * migration fallback for installations that have not run the schema migration.
  */
 export function readOwnerDest(meta) {
-    const humansOwner = getOwnerNotifyFromHumans();
-    if (humansOwner)
-        return humansOwner;
-    const owner = meta.notify?.owner;
-    const channel = owner?.channel?.trim();
-    const to = owner?.to?.trim();
-    if (!channel || !to)
-        return null;
-    return { channel, to };
+    const canonical = getOwnerNotifyFromHumans();
+    if (canonical)
+        return canonical;
+    const channel = meta.notify?.owner?.channel?.trim();
+    const to = meta.notify?.owner?.to?.trim();
+    return channel && to ? { channel, to } : null;
 }
 /**
  * Resolve CLI/config into a send envelope. Pure except for reading `meta` —
@@ -55,16 +52,14 @@ export function resolveSendEnvelope(input, meta) {
         };
     }
     // Owner defaults fill only missing fields (and expand the bare "owner" alias).
-    // humans.yaml is the primary source; notify.owner in agents.yaml is the
-    // fallback for the migration window. Explicit --channel/--to always win.
+    // humans.yaml is the canonical source. Explicit --channel/--to always win.
     let channel = (input.channel ?? '').trim();
     let to = (input.to ?? '').trim();
     const usedOwnerAlias = isOwnerAlias(to);
     if (input.ownerMode || usedOwnerAlias) {
-        const humansOwner = getOwnerNotifyFromHumans();
-        const fallbackOwner = meta.notify?.owner;
-        const ownerChannel = humansOwner?.channel ?? fallbackOwner?.channel?.trim() ?? '';
-        const ownerTo = humansOwner?.to ?? fallbackOwner?.to?.trim() ?? '';
+        const owner = getOwnerNotifyFromHumans() ?? meta.notify?.owner;
+        const ownerChannel = owner?.channel ?? '';
+        const ownerTo = owner?.to ?? '';
         if (!channel)
             channel = ownerChannel;
         if (!to || usedOwnerAlias)
@@ -72,7 +67,7 @@ export function resolveSendEnvelope(input, meta) {
     }
     if (!channel || !to) {
         const hint = input.ownerMode || usedOwnerAlias
-            ? 'Set notify.{channel,to} in humans.yaml (or notify.owner in agents.yaml), or pass --channel and --to explicitly.'
+            ? 'Set owner.channels and owner.policy.normal in humans.yaml, or pass --channel and --to explicitly.'
             : 'Need --channel and --to (or --to owner with notify.owner configured). ' +
                 'Example: agents send --channel desktop --to local --text "hi"';
         return { ok: false, error: hint };

package/dist/lib/cloud/dispatch.d.ts

@@ -0,0 +1,27 @@
+import type { CloudProvider, DispatchOptions } from './types.js';
+/**
+ * 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 declare function resolveCloudPrompt(raw: string | undefined, opts: {
+    json: boolean;
+    hint: string;
+}): string;
+export interface ExecuteCloudDispatchParams {
+    provider: CloudProvider;
+    dispatchOptions: DispatchOptions;
+    /** Image file paths for vision dispatch (checked against provider capability). */
+    imagePaths?: string[];
+    /** Raw skill refs (`id` or `id@version`) for ride-along skills. */
+    skillIds?: string[];
+    /** Stream the task output after dispatch; false = fire-and-forget. */
+    follow: boolean;
+    json: boolean;
+}
+/**
+ * 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 declare function executeCloudDispatch(params: ExecuteCloudDispatchParams): Promise<void>;

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`). */