@phnx-labs/agents-cli 1.22.15 → 1.22.17

package/dist/commands/exec.js

@@ -532,7 +532,7 @@ export function registerRunCommand(program) {
         .option('--headless', 'Force headless mode. Auto-enabled when a prompt is provided; pass explicitly to stay headless with no prompt (reads the prompt from stdin).', false)
         .option('--no-auth-check', 'Skip the pre-launch "looks logged out" warning on an interactive run (advisory; never blocks anyway). Also silenced by AGENTS_NO_AUTH_CHECK=1.')
         .option('-i, --interactive', 'Force interactive mode even when a prompt is provided. Mutually exclusive with --headless.')
-        .option('--resume [id]', 'Resume a previous conversation. Accepts a full or partial session id (prefix-matched against the index); omit the id to pick from recent sessions interactively. Resumes under the version that started the session. claude/codex resume natively; other agents replay via a /continue first message. Pair with a prompt to continue headlessly.')
+        .option('--resume [id]', 'Resume a previous conversation. Full IDs resolve locally first, then fleet-wide. Claude, Codex, Grok, Kimi, Droid, and Cursor use version-gated native resume; other agents replay via /continue. Pair with a prompt to continue headlessly.')
         .option('--session-id <id>', 'Force a NEW conversation to use this exact session UUID (Claude only). This CREATES a session — to resume an existing one, use --resume.')
         .option('--name <slug>', 'Name the run — seeds the session label so it shows up as `<name>` in `agents sessions` and resolves by it (and `agents hosts logs <name>` for --host runs) instead of an opaque id. An agent-generated title later refines the label; your name shows until then. Optional.')
         .option('--notify', 'Post a desktop notification when a headless run finishes. Fired by this process on exit, so it survives whatever launched the run (the menu bar dispatching it, a terminal you closed).')
@@ -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,7 +680,16 @@ export function registerRunCommand(program) {
 
       Fallback: --fallback codex,antigravity retries on rate-limit failure via /continue handoff. Each entry accepts @version.
 
-      Resume: --resume <id> continues a prior conversation (full or partial id; omit to pick interactively). claude/codex resume natively; others replay via a /continue first message. Add a prompt to continue headlessly.
+      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.
         agents run kimi -- --plan --some-native-flag value
@@ -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
@@ -781,7 +833,89 @@ export function registerRunCommand(program) {
                 `Pin a concrete harness instead: agents run <harness>@<version>.`));
             process.exit(1);
         }
-        const autoHarnessRequested = normalizedAgentSpec === RUN_AUTO_KEYWORD;
+        let autoHarnessRequested = normalizedAgentSpec === RUN_AUTO_KEYWORD;
+        let resolvedResumeSource;
+        // Concrete resume ids resolve BEFORE placement. Full UUIDs take the local
+        // SQLite fast path; only a local miss fans out to the fleet. This lets a
+        // command entered on zion discover that the owning version-home is on a
+        // worker, while a command entered on that worker never pays for SSH.
+        if (typeof options.resume === 'string' && options.resume.trim()) {
+            const selector = options.resume.trim();
+            const injectedSource = (() => {
+                try {
+                    const parsed = JSON.parse(process.env.AGENTS_RESUME_SOURCE_JSON ?? 'null');
+                    return parsed?.id === selector ? parsed : undefined;
+                }
+                catch {
+                    return undefined;
+                }
+            })();
+            delete process.env.AGENTS_RESUME_SOURCE_JSON;
+            const outcome = injectedSource
+                ? { kind: 'resolved', session: injectedSource }
+                : await (await import('./sessions.js')).resolveSessionMetadataValue(selector);
+            if (outcome.kind === 'partial') {
+                console.error(chalk.red(`Could not resolve session while these devices were unavailable: ${outcome.failedPeers.join(', ')}`));
+                process.exit(2);
+            }
+            if (outcome.kind === 'not-found') {
+                console.error(chalk.red(`No session matching "${selector}".`));
+                process.exit(1);
+            }
+            if (outcome.kind === 'ambiguous') {
+                console.error(chalk.red(`"${selector}" matches ${outcome.candidates.length} sessions. Pass the full session id.`));
+                process.exit(1);
+            }
+            resolvedResumeSource = outcome.session;
+            const [requestedAgent, requestedVersion] = normalizedAgentSpec.split('@');
+            if (!autoHarnessRequested && requestedAgent !== resolvedResumeSource.agent) {
+                console.error(chalk.red(`Session ${resolvedResumeSource.shortId} belongs to ${resolvedResumeSource.agent}, not ${requestedAgent}. ` +
+                    `Use: agents resume ${resolvedResumeSource.id}`));
+                process.exit(1);
+            }
+            if (!autoHarnessRequested && requestedVersion && requestedVersion !== resolvedResumeSource.version) {
+                console.error(chalk.red(`Session ${resolvedResumeSource.shortId} started with ${resolvedResumeSource.agent}@${resolvedResumeSource.version ?? 'unknown'}, ` +
+                    `not @${requestedVersion}.`));
+                process.exit(1);
+            }
+            // Omitted --mode inherits the effective source mode. Commander keeps
+            // the normal new-run default as a real value, so consult its provenance
+            // rather than mistaking the default for an explicit override.
+            if (command.getOptionValueSource('mode') === 'default') {
+                if (resolvedResumeSource.mode)
+                    options.mode = resolvedResumeSource.mode;
+                else if (!options.quiet)
+                    process.stderr.write(chalk.yellow(`[agents] session ${resolvedResumeSource.shortId} predates stored launch modes; using --mode ${options.mode}\n`));
+            }
+            const { machineId } = await import('../lib/machine-id.js');
+            const sourceMachine = resolvedResumeSource.machine;
+            const explicitPlacement = hostTargetGiven(options).length > 0;
+            if (sourceMachine && sourceMachine !== machineId() && !explicitPlacement) {
+                options.host = sourceMachine;
+            }
+            else if (!autoHarnessRequested && sourceMachine && sourceMachine !== machineId() && explicitPlacement && !hostTargetGiven(options).includes(sourceMachine)) {
+                console.error(chalk.red(`Strict resume must run on ${sourceMachine}, where session ${resolvedResumeSource.shortId} is owned. ` +
+                    `Use agents run auto --resume ${resolvedResumeSource.id} to hand off elsewhere.`));
+                process.exit(1);
+            }
+            // On the owning machine, `auto` first asks the existing account router
+            // whether the exact source version is healthy. If it is, native resume
+            // wins. If not, keep `auto` so the normal harness/account router selects
+            // a healthy local target and the later resume block performs /continue.
+            if (autoHarnessRequested && (!sourceMachine || sourceMachine === machineId())) {
+                const sourceAgent = resolvedResumeSource.agent;
+                if (sourceAgent in AGENTS && resolvedResumeSource.version) {
+                    const { resolveRunVersion } = await import('../lib/rotate.js');
+                    const health = await resolveRunVersion(sourceAgent, 'available', resolvedResumeSource.cwd ?? process.cwd());
+                    if (!health.exhausted && health.version === resolvedResumeSource.version) {
+                        normalizedAgentSpec = `${sourceAgent}@${resolvedResumeSource.version}`;
+                        autoHarnessRequested = false;
+                        if (!options.quiet)
+                            process.stderr.write(chalk.gray(`[agents] auto resume → native ${normalizedAgentSpec} on ${sourceMachine ?? machineId()}\n`));
+                    }
+                }
+            }
+        }
         if (autoHarnessRequested) {
             // `auto` is reserved. If a future harness registers that id, the
             // keyword collides — fail loud rather than silently shadow the harness.
@@ -797,7 +931,7 @@ export function registerRunCommand(program) {
             // Host layer: with no explicit --host/--device, default to the
             // affinity pick. Skipped on a host-dispatched run — its dispatcher
             // already resolved this layer (see runAutoDefaultsToAffinity).
-            if (runAutoDefaultsToAffinity(options))
+            if (!resolvedResumeSource && runAutoDefaultsToAffinity(options))
                 options.device = 'auto';
         }
         // --device auto / --host auto (and deprecated --smart): affinity-pick host.
@@ -2013,7 +2147,8 @@ export function registerRunCommand(program) {
             // AgentId is wider than SessionAgentId (amp/kiro/goose/copilot keep no transcripts);
             // those simply yield no matches and fall through to the not-found error.
             const sessionAgent = agent;
-            await discoverSessions({ agent: sessionAgent, version });
+            if (!resolvedResumeSource)
+                await discoverSessions({ agent: sessionAgent, version });
             // Resume is interactive unless a follow-on prompt makes it headless.
             const wantsInteractive = resolveInteractive({ interactive: options.interactive, headless: options.headless, prompt });
             const idArg = typeof options.resume === 'string' ? options.resume.trim() : '';
@@ -2024,9 +2159,9 @@ export function registerRunCommand(program) {
             catch {
                 scopeCwd = cwd;
             }
-            let session;
+            let session = resolvedResumeSource;
             if (idArg) {
-                let matches = findSessionsById(idArg, { agent: sessionAgent, version, cwd: scopeCwd });
+                let matches = session ? [session] : findSessionsById(idArg, { agent: sessionAgent, version, cwd: scopeCwd });
                 if (matches.length === 0) {
                     const wide = findSessionsById(idArg, { agent: sessionAgent, version });
                     if (wide.length > 0) {
@@ -2076,10 +2211,12 @@ export function registerRunCommand(program) {
                 session = picked.session;
                 forceInteractive = true; // bare resume always lands in the agent's TUI
             }
-            // Pin to the chosen session's own version (the isolated HOME the transcript
-            // lives in) and route by tier.
-            version = session.version;
-            if (nativeResume(agent)) {
+            // Native resume is valid only for the source harness + exact isolated
+            // version. `auto` may have selected another healthy harness/account; in
+            // that case keep the target version and hand off through /continue.
+            const canResumeNatively = session.agent === agent && nativeResume(agent, session.version);
+            if (canResumeNatively) {
+                version = session.version;
                 resumeNative = true;
                 resumeSessionId = session.id;
                 // Native `--resume` (claude/codex) resolves the transcript relative to the

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/humans.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `agents humans` — owner identity and notification channel management.
+ *
+ * Reads from ~/.agents/humans.yaml (created by migration from owner.md and
+ * agents.yaml notify.owner). Provides inspection commands for the current
+ * owner config.
+ */
+import type { Command } from 'commander';
+/** Register the `agents humans` command tree. */
+export declare function registerHumansCommands(program: Command): void;

package/dist/commands/humans.js

@@ -0,0 +1,91 @@
+/**
+ * `agents humans` — owner identity and notification channel management.
+ *
+ * Reads from ~/.agents/humans.yaml (created by migration from owner.md and
+ * agents.yaml notify.owner). Provides inspection commands for the current
+ * owner config.
+ */
+import { setHelpSections } from '../lib/help.js';
+import { readHumans, getOwnerFromHumans } from '../lib/humans.js';
+/** Register the `agents humans` command tree. */
+export function registerHumansCommands(program) {
+    const humansCmd = program
+        .command('humans')
+        .description('Inspect owner identity and notification channel config (humans.yaml)');
+    setHelpSections(humansCmd, {
+        examples: `
+      # Show owner identity and channel config as JSON
+      agents humans show owner --json
+
+      # Show owner identity in human-readable form
+      agents humans show owner
+    `,
+        notes: `
+      humans.yaml is the canonical owner identity file at ~/.agents/humans.yaml.
+      It is populated by migrating notify.owner from agents.yaml and frontmatter
+      from owner.md. Use \`agents humans show owner\` to inspect the current config.
+    `,
+    });
+    const showCmd = humansCmd
+        .command('show')
+        .description('Show config from humans.yaml');
+    setHelpSections(showCmd, {
+        examples: `
+      agents humans show owner
+      agents humans show owner --json
+    `,
+    });
+    showCmd
+        .command('owner')
+        .description('Show the configured owner identity and notification channels')
+        .option('--json', 'Output as JSON')
+        .action((opts) => {
+        const humans = readHumans();
+        if (!humans) {
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(null) + '\n');
+            }
+            else {
+                process.stderr.write('humans.yaml not found — run `agents` once to trigger migration\n');
+                process.exitCode = 1;
+            }
+            return;
+        }
+        const owner = getOwnerFromHumans();
+        if (opts.json) {
+            process.stdout.write(JSON.stringify(owner ?? null, null, 2) + '\n');
+        }
+        else {
+            if (!owner) {
+                process.stdout.write('No owner configured in humans.yaml\n');
+                return;
+            }
+            if (owner.name)
+                process.stdout.write(`Name:     ${owner.name}\n`);
+            if (owner.timezone)
+                process.stdout.write(`Timezone: ${owner.timezone}\n`);
+            if (owner.quiet_hours)
+                process.stdout.write(`Quiet:    ${owner.quiet_hours}\n`);
+            if (owner.default_severity)
+                process.stdout.write(`Severity: ${owner.default_severity}\n`);
+            if (owner.notify) {
+                process.stdout.write(`Notify:   channel=${owner.notify.channel} to=${owner.notify.to}\n`);
+            }
+            if (owner.channels?.length) {
+                process.stdout.write(`Channels:\n`);
+                for (const ch of owner.channels) {
+                    const extra = [ch.transport, ch.intrusive ? 'intrusive' : null].filter(Boolean).join(', ');
+                    process.stdout.write(`  - ${ch.id}${extra ? ` (${extra})` : ''}\n`);
+                }
+            }
+            if (owner.policy) {
+                process.stdout.write(`Policy:\n`);
+                for (const [sev, channels] of Object.entries(owner.policy)) {
+                    if (Array.isArray(channels) && channels.length) {
+                        process.stdout.write(`  ${sev}: ${channels.join(', ')}\n`);
+                    }
+                }
+            }
+        }
+    });
+}

package/dist/commands/resume.d.ts

@@ -0,0 +1,17 @@
+import type { Command } from 'commander';
+interface ResumeOptions {
+    mode?: string;
+    interactive?: boolean;
+    headless?: boolean;
+    cwd?: string;
+    quiet?: boolean;
+}
+/** Translate `agents resume <id>` to the canonical `agents run` surface after
+ * resolving the source identity. The run command remains the only executor. */
+export declare function buildResumeRunArgs(session: {
+    id: string;
+    agent: string;
+    version?: string;
+}, prompt: string | undefined, options: ResumeOptions): string[];
+export declare function registerResumeCommand(program: Command): void;
+export {};

package/dist/commands/resume.js

@@ -0,0 +1,80 @@
+/** Strict session resume convenience command. */
+import { spawn } from 'child_process';
+import chalk from 'chalk';
+import { setHelpSections } from '../lib/help.js';
+import { resolveSessionMetadataValue } from './sessions.js';
+/** Translate `agents resume <id>` to the canonical `agents run` surface after
+ * resolving the source identity. The run command remains the only executor. */
+export function buildResumeRunArgs(session, prompt, options) {
+    const spec = session.version ? `${session.agent}@${session.version}` : session.agent;
+    const args = ['run', spec, ...(prompt === undefined ? [] : [prompt]), '--resume', session.id];
+    if (options.mode)
+        args.push('--mode', options.mode);
+    if (options.interactive)
+        args.push('--interactive');
+    if (options.headless)
+        args.push('--headless');
+    if (options.cwd)
+        args.push('--cwd', options.cwd);
+    if (options.quiet)
+        args.push('--quiet');
+    return args;
+}
+export function registerResumeCommand(program) {
+    const cmd = program
+        .command('resume <session-id> [prompt]')
+        .description('Resume a session with its original harness, version, device, account, cwd, and mode')
+        .option('-m, --mode <mode>', 'Override the recorded launch mode')
+        .option('-i, --interactive', 'Resume interactively even when a prompt is provided')
+        .option('--headless', 'Resume headlessly (a prompt is required)')
+        .option('--cwd <path>', 'Override the recorded working directory')
+        .option('-q, --quiet', 'Suppress routing banners')
+        .action(async (sessionId, prompt, options) => {
+        const outcome = await resolveSessionMetadataValue(sessionId.trim());
+        if (outcome.kind === 'partial') {
+            console.error(chalk.red(`Could not resolve session while these devices were unavailable: ${outcome.failedPeers.join(', ')}`));
+            process.exitCode = 2;
+            return;
+        }
+        if (outcome.kind === 'not-found') {
+            console.error(chalk.red(`No session matching "${sessionId}".`));
+            process.exitCode = 1;
+            return;
+        }
+        if (outcome.kind === 'ambiguous') {
+            console.error(chalk.red(`"${sessionId}" matches ${outcome.candidates.length} sessions. Pass the full session id.`));
+            process.exitCode = 1;
+            return;
+        }
+        const args = buildResumeRunArgs(outcome.session, prompt, options);
+        const child = spawn(process.execPath, [process.argv[1], ...args], {
+            stdio: 'inherit',
+            env: {
+                ...process.env,
+                // Avoid repeating the fleet lookup in the delegated local `run`
+                // process. The value is metadata-only and is not forwarded over SSH;
+                // the owner performs its own local SQLite lookup.
+                AGENTS_RESUME_SOURCE_JSON: JSON.stringify(outcome.session),
+            },
+        });
+        const exitCode = await new Promise((resolve) => {
+            child.once('error', () => resolve(127));
+            child.once('exit', (code, signal) => resolve(code ?? (signal ? 1 : 0)));
+        });
+        process.exitCode = exitCode;
+    });
+    setHelpSections(cmd, {
+        examples: `
+      # Resume by full id
+      agents resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897
+
+      # Resume and continue headlessly
+      agents resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897 "finish the tests"
+
+      # Deliberately change permissions
+      agents resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897 --mode edit`,
+        notes: `
+      Full IDs resolve from the local session database first; an SSH fleet lookup runs only after a local miss.
+      Use agents run auto --resume <id> when the original account is unavailable and another harness may continue.`,
+    });
+}

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>;