@phnx-labs/agents-cli 1.22.15 → 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/sessions.d.ts

@@ -281,8 +281,8 @@ export declare function mergeLocalFirst(sessions: SessionMeta[], localMachine: s
  */
 export declare function serializeSessionsJson(sessions: SessionMeta[]): string;
 /** The intentionally small metadata contract emitted by `sessions --resolve`.
- * Transcript locations, extracted plans, account data, costs, and other indexed
- * payload stay local to the machine that owns them. */
+ * It includes only launch identity needed to route/resume. Transcript paths,
+ * extracted plans, costs, and content stay on the machine that owns them. */
 export declare function serializeResolvedSessionsJson(sessions: SessionMeta[]): string;
 /**
  * Whether the local machine's sessions belong in an `--active` view. Local is
@@ -636,12 +636,21 @@ export declare function fleetCandidatesByQuery(rows: SessionMeta[], query: strin
 export declare function metadataResolveForwardedArgs(selector: string, scope: Pick<SessionFilterOptions, 'agent' | 'project'>): string[];
 /** Build the local-only peer argv for a distributed tool search. */
 export declare function toolSearchForwardedArgs(argv: string[], hosts: string[]): string[];
-/** Resolution must fail closed when any selected peer did not answer. Choosing
- * from a partial fleet can turn an unseen candidate into a false unique match. */
+/** Resolution fails closed for prefixes/keywords when a peer did not answer.
+ * A full UUID is globally unique, so one exact hit is sufficient even when an
+ * unrelated registered device is offline. */
 export declare function metadataResolveOutcome(localMatches: SessionMeta[], remote: {
     sessions: SessionMeta[];
     unreachable: string[];
 }, selector: string): MetadataResolveOutcome;
+/** Reusable local-first resolver for `agents run --resume` and `agents resume`.
+ * Full UUIDs hit the local SQLite index without any SSH fan-out. */
+export declare function resolveSessionMetadataValue(selector: string, scope?: {
+    agent?: string;
+    project?: string;
+    local?: boolean;
+    hosts?: string[];
+}, deps?: Pick<FleetResolveDeps, 'gatherRemoteList'>): Promise<MetadataResolveOutcome>;
 /**
  * Locate a full session id or short id prefix across the online fleet and render it from the machine
  * that holds it. The local disk already missed; this fans `sessions <id> --json

package/dist/commands/sessions.js

@@ -814,8 +814,8 @@ export function serializeSessionsJson(sessions) {
     return JSON.stringify(serializable, null, 2) + '\n';
 }
 /** The intentionally small metadata contract emitted by `sessions --resolve`.
- * Transcript locations, extracted plans, account data, costs, and other indexed
- * payload stay local to the machine that owns them. */
+ * It includes only launch identity needed to route/resume. Transcript paths,
+ * extracted plans, costs, and content stay on the machine that owns them. */
 export function serializeResolvedSessionsJson(sessions) {
     const safe = sessions.map((session) => ({
         id: session.id,
@@ -826,6 +826,7 @@ export function serializeResolvedSessionsJson(sessions) {
         lastActivity: session.lastActivity,
         project: session.project,
         version: session.version,
+        mode: session.mode,
         label: session.label,
         topic: session.topic,
         machine: session.machine,
@@ -3447,6 +3448,7 @@ function modeFlag(mode) {
         return '--json';
     return undefined; // summary — the peer's default render
 }
+const FULL_SESSION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 /** Resolve a fleet sweep through the same canonical full-id / prefix resolver as
  * local lookups, then group copies by logical session id. Synced mirrors of one
  * session therefore stay one candidate even when several machines report them;
@@ -3501,19 +3503,46 @@ export function toolSearchForwardedArgs(argv, hosts) {
         args.push('--local');
     return args;
 }
-/** Resolution must fail closed when any selected peer did not answer. Choosing
- * from a partial fleet can turn an unseen candidate into a false unique match. */
+/** Resolution fails closed for prefixes/keywords when a peer did not answer.
+ * A full UUID is globally unique, so one exact hit is sufficient even when an
+ * unrelated registered device is offline. */
 export function metadataResolveOutcome(localMatches, remote, selector) {
-    if (remote.unreachable.length > 0) {
-        return { kind: 'partial', failedPeers: remote.unreachable };
-    }
     const candidates = fleetCandidatesByQuery([...localMatches, ...remote.sessions], selector);
+    if (FULL_SESSION_ID_RE.test(selector) && candidates.length === 1 && candidates[0].id.toLowerCase() === selector.toLowerCase()) {
+        return { kind: 'resolved', session: candidates[0].hits[0].session };
+    }
+    if (remote.unreachable.length > 0)
+        return { kind: 'partial', failedPeers: remote.unreachable };
     if (candidates.length === 0)
         return { kind: 'not-found' };
     if (candidates.length > 1)
         return { kind: 'ambiguous', candidates };
     return { kind: 'resolved', session: candidates[0].hits[0].session };
 }
+/** Reusable local-first resolver for `agents run --resume` and `agents resume`.
+ * Full UUIDs hit the local SQLite index without any SSH fan-out. */
+export async function resolveSessionMetadataValue(selector, scope = {}, deps = { gatherRemoteList }) {
+    const localMachine = machineId();
+    const includeLocal = !scope.hosts?.length || shouldIncludeLocal(scope.hosts, localMachine);
+    const indexed = includeLocal ? applyScopeFilters(querySessions(), scope) : [];
+    const localMatches = resolveIndexedMetadataRows(indexed, selector)
+        .map(session => ({ ...session, machine: session.machine || localMachine }));
+    if (FULL_SESSION_ID_RE.test(selector)) {
+        const localOutcome = metadataResolveOutcome(localMatches, { sessions: [], unreachable: [] }, selector);
+        if (localOutcome.kind === 'resolved')
+            return localOutcome;
+    }
+    if (scope.local === true)
+        return metadataResolveOutcome(localMatches, { sessions: [], unreachable: [] }, selector);
+    try {
+        const forwarded = metadataResolveForwardedArgs(selector, scope);
+        const remote = await deps.gatherRemoteList(forwarded, scope.hosts);
+        return metadataResolveOutcome(localMatches, remote, selector);
+    }
+    catch (error) {
+        return metadataResolveOutcome(localMatches, { sessions: [], unreachable: [error?.message ?? 'fleet fan-out'] }, selector);
+    }
+}
 /** Resolve one selector to indexed metadata across the fleet without reading or
  * rendering transcript events. A peer answering the parent sweep returns every
  * local candidate; the parent performs the one logical-session uniqueness gate. */
@@ -3529,18 +3558,7 @@ async function resolveSessionMetadata(selector, scope, deps = { gatherRemoteList
         process.stdout.write(serializeResolvedSessionsJson(localMatches));
         return;
     }
-    let remoteResult = { sessions: [], unreachable: [] };
-    if (scope.local !== true) {
-        try {
-            const forwarded = metadataResolveForwardedArgs(selector, scope);
-            const result = await deps.gatherRemoteList(forwarded, scope.hosts);
-            remoteResult = { sessions: result.sessions, unreachable: result.unreachable };
-        }
-        catch (error) {
-            remoteResult = { sessions: [], unreachable: [error?.message ?? 'fleet fan-out'] };
-        }
-    }
-    const outcome = metadataResolveOutcome(localMatches, remoteResult, selector);
+    const outcome = await resolveSessionMetadataValue(selector, scope, deps);
     if (outcome.kind === 'partial') {
         console.error(chalk.red(`Partial session resolution: ${outcome.failedPeers.join(', ')} did not answer.`));
         console.error(chalk.gray('No unique/no-match decision was made. Upgrade or reconnect every peer, then retry.'));

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/index.js

@@ -94,7 +94,7 @@ if (IS_DEV_BUILD) {
 // module on each invocation (which loaded the whole ~50-module tree before the
 // first byte of output), the registry maps a command name to a thunk that
 // imports only what that command needs. See src/lib/startup/command-registry.ts.
-import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadExport, loadPackages, loadRoutines, loadMonitors, loadProjects, loadRun, loadFork, loadDefaults, loadSet, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadStatus, loadSnapshot, loadProfiles, loadHarness, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadFactory, loadUsage, loadCost, loadPerf, loadTrends, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadShare, loadSend, loadFeed, loadMailboxes, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadExport, loadPackages, loadRoutines, loadMonitors, loadProjects, loadRun, loadFork, loadDefaults, loadSet, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadStatus, loadSnapshot, loadProfiles, loadHarness, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadFactory, loadUsage, loadCost, loadPerf, loadTrends, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadHumans, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadShare, loadSend, loadFeed, loadMailboxes, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { renderWhatsNew } from './lib/whats-new.js';
 import { getCliLaunch } from './lib/cli-entry.js';
@@ -980,6 +980,7 @@ async function registerAllEagerCommands() {
     await reg(loadAudit);
     await reg(loadWebhook);
     await reg(loadFunnel);
+    await reg(loadHumans);
     registerHqTombstoneCommand(program);
     await reg(loadFeed);
     await reg(loadMailboxes);
@@ -1177,7 +1178,7 @@ if (process.env.AGENTS_SKIP_MIGRATION !== '1') {
         // Bumping the suffix re-runs migrations for every user; binary releases that
         // don't change the schema must NOT re-run (they would destroy user content
         // when migration steps overlap with user-authored paths). See issue #20.
-        const sentinelValue = 'v14';
+        const sentinelValue = 'v15';
         let needRun = true;
         try {
             if (fs.existsSync(sentinel) && fs.readFileSync(sentinel, 'utf-8').trim() === sentinelValue) {

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.
@@ -59,7 +59,10 @@ export type ResolveSendResult = {
 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 notify.owner; null when either field is missing. */
+/**
+ * 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;
     to: string;

package/dist/lib/channels/send.js

@@ -1,3 +1,4 @@
+import { getOwnerNotifyFromHumans } from '../humans.js';
 import { registerBuiltinProviders } from './providers/index.js';
 import { resolveTransport } from './resolve.js';
 const OWNER_ALIAS = 'owner';
@@ -16,14 +17,17 @@ export function composeSendText(text, urls) {
         return body;
     return body ? `${body}\n${extra.join('\n')}` : extra.join('\n');
 }
-/** Read notify.owner; null when either field is missing. */
+/**
+ * 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 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` —
@@ -48,15 +52,14 @@ export function resolveSendEnvelope(input, meta) {
         };
     }
     // Owner defaults fill only missing fields (and expand the bare "owner" alias).
-    // Explicit --channel/--to always win; a complete notify.owner is NOT required
-    // when both flags are already set (same merge-then-require shape as main).
-    const ownerCfg = meta.notify?.owner;
-    const ownerChannel = ownerCfg?.channel?.trim() || '';
-    const ownerTo = ownerCfg?.to?.trim() || '';
+    // 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 owner = getOwnerNotifyFromHumans() ?? meta.notify?.owner;
+        const ownerChannel = owner?.channel ?? '';
+        const ownerTo = owner?.to ?? '';
         if (!channel)
             channel = ownerChannel;
         if (!to || usedOwnerAlias)
@@ -64,7 +67,7 @@ export function resolveSendEnvelope(input, meta) {
     }
     if (!channel || !to) {
         const hint = input.ownerMode || usedOwnerAlias
-            ? 'Set notify.owner.{channel,to} 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>;