@phnx-labs/agents-cli 1.20.63 → 1.20.65

package/dist/commands/browser.js

@@ -4,7 +4,7 @@ import { listProfiles, getProfile, createProfile, deleteProfile, ensureDefaultBr
 import { updateMeta } from '../lib/state.js';
 import { loginsForProfile, profilesLoggedInto, serviceForUrl, loginsWithAccountsForProfile, accountsForProfile, credKeysForService, AUTH_SIGNATURES, } from '../lib/browser/login-detection.js';
 import { parseSecretRef } from '../lib/browser/secret-ref.js';
-import { readAndResolveBundleEnv, bundleExists, readBundle, describeBundle } from '../lib/secrets/bundles.js';
+import { readAndResolveBundleEnv, isHeadlessSecretsContext, bundleExists, readBundle, describeBundle } from '../lib/secrets/bundles.js';
 import { findBrowserPath, getPortOccupant, isLauncherScript } from '../lib/browser/chrome.js';
 import { listProfileCacheDirs, removeProfileCache, listAllProfileSnapshots, } from '../lib/browser/runtime-state.js';
 import { DEFAULT_VIEWPORT } from '../lib/browser/devices.js';
@@ -1420,7 +1420,7 @@ function registerTaskCommands(browser) {
                 process.exit(1);
             }
             try {
-                const { env } = readAndResolveBundleEnv(parsed.bundle, { caller: 'browser type', keys: [parsed.key] });
+                const { env } = readAndResolveBundleEnv(parsed.bundle, { caller: 'browser type', keys: [parsed.key], agentOnly: isHeadlessSecretsContext() });
                 if (!(parsed.key in env)) {
                     console.error(`Key "${parsed.key}" not in bundle "${parsed.bundle}".`);
                     process.exit(1);

package/dist/commands/cloud.js

@@ -8,6 +8,7 @@ import { insertTask, updateTaskStatus, getTaskById, listTasks as listStoredTasks
 import { renderStream } from '../lib/cloud/stream.js';
 import { MissingTargetError, MAX_IMAGES_PER_DISPATCH } from '../lib/cloud/types.js';
 import { normalizeTriggerEvent, validateTrigger, writeJob, jobExists, GITHUB_TRIGGER_EVENTS } from '../lib/routines.js';
+import { machineId } from '../lib/machine-id.js';
 import { emit } from '../lib/events.js';
 /** Map a supported image file extension to its wire mimeType. Rejects anything else. */
 function imageMimeFromPath(file) {
@@ -145,7 +146,7 @@ Examples:
     cloud
         .command('run [prompt]')
         .description('Dispatch a task to a cloud agent.')
-        .option('--provider <id>', 'Cloud backend: rush, codex, factory, antigravity (overrides agent auto-routing)')
+        .option('--provider <id>', 'Cloud backend: rush, codex, factory, antigravity, host (overrides agent auto-routing)')
         .option('--agent <name>', 'Agent to run: claude, codex, droid, antigravity (auto-routes to its native cloud)')
         .option('--repo <owner/repo>', 'GitHub repository. Repeatable for multi-repo dispatch (Rush Cloud only).', (value, previous) => {
         const acc = Array.isArray(previous) ? previous : [];
@@ -160,6 +161,9 @@ Examples:
         .option('--model <model>', 'Model override')
         .option('--env <id>', 'Codex Cloud environment ID')
         .option('--computer <name>', 'Factory/Droid computer target')
+        .option('--host <name>', 'One of your machines as the target (a registered host, device, capability tag, or user@host). Implies --provider host.')
+        .option('--remote-cwd <dir>', 'Working directory on the host (--provider host only)')
+        .option('--any', 'With --host <cap> (a capability tag), pick any matching host instead of erroring when several match')
         .option('--autonomy <level>', 'Factory/Droid autonomy: low, medium, high (default high)')
         .option('--mode <mode>', 'Execution mode (e.g., plan, edit, full)')
         .option('--image <path>', `Attach an image (.png/.jpg/.webp) for vision dispatch. Repeatable, up to ${MAX_IMAGES_PER_DISPATCH} (Rush Cloud only).`, (value, previous) => {
@@ -189,6 +193,10 @@ Examples:
   # Codex Cloud
   agents cloud run "add auth tests" --provider codex --env env_abc123
 
+  # One of your own machines (agents hosts / agents devices), over SSH
+  agents cloud run "run the nightly benchmark" --host gpu-box --agent claude
+  agents cloud run "rebuild the index" --host gpu --any --remote-cwd ~/proj
+
   # Default provider (set in ~/.agents/agents.yaml)
   agents cloud run "refactor auth module" --repo user/repo
 `)
@@ -208,9 +216,16 @@ Examples:
                 process.stderr.write(chalk.dim(`Reading prompt from ${filePath} (${sizeKB} KB)\n`));
             }
         }
+        // --host names one of YOUR machines as the target — that only means
+        // something to the host provider, so it implies --provider host rather
+        // than silently riding along to a cloud backend that would ignore it.
+        if (options.host && options.provider && options.provider !== 'host') {
+            die(`--host targets your own machines (--provider host), not ${options.provider}. Drop --host, or use --provider host.`);
+        }
+        const explicitProvider = options.provider ?? (options.host ? 'host' : undefined);
         // Agent-aware: with no --provider, the agent routes to its native cloud
         // (claude→rush, codex→codex, droid→factory, antigravity→antigravity).
-        const provider = resolveProvider(options.provider, options.agent);
+        const provider = resolveProvider(explicitProvider, options.agent);
         // --repo is repeatable: commander gives us an array via our collector.
         // A single --repo value arrives as a one-element array; keep the legacy
         // singular `repo` field in sync so providers that only know that field
@@ -234,6 +249,12 @@ Examples:
             dispatchOptions.providerOptions.env = options.env;
         if (options.computer)
             dispatchOptions.providerOptions.computer = options.computer;
+        if (options.host)
+            dispatchOptions.providerOptions.host = options.host;
+        if (options.remoteCwd)
+            dispatchOptions.providerOptions.remoteCwd = options.remoteCwd;
+        if (options.any)
+            dispatchOptions.providerOptions.any = true;
         if (options.autonomy)
             dispatchOptions.providerOptions.autonomy = options.autonomy;
         if (options.mode)
@@ -279,6 +300,15 @@ Examples:
             };
             if (repoValues[0])
                 routine.repo = repoValues[0];
+            // --host with --on: the webhook-fired run places on that machine (the
+            // routine carries the placement, and firing pins to THIS device so a
+            // fleet of receivers can't each dispatch a duplicate).
+            if (options.host) {
+                routine.host = options.host;
+                if (options.remoteCwd)
+                    routine.remoteCwd = options.remoteCwd;
+                routine.devices = [machineId()];
+            }
             writeJob(routine);
             if (json) {
                 console.log(JSON.stringify({ ok: true, registered: routineName, trigger }, null, 2));

package/dist/commands/doctor.js

@@ -1,6 +1,6 @@
 import { addHostOption } from '../lib/hosts/option.js';
 import { buildRemoteAgentsInvocation } from '../lib/hosts/remote-cmd.js';
-import { loadDevices } from '../lib/devices/registry.js';
+import { loadDevices, isControlDevice } from '../lib/devices/registry.js';
 import { resolveHost } from '../lib/hosts/registry.js';
 import { sshExec } from '../lib/ssh-exec.js';
 import { sshTargetFor } from '../lib/hosts/types.js';
@@ -249,6 +249,9 @@ async function resolveFleetTargets(opts) {
     const localName = machineId();
     return Object.values(registry)
         .filter((d) => d.name.toLowerCase() !== localName)
+        // Control devices (a cockpit) never run agents — skip them in the fleet
+        // fan-out (an explicit --device <name> still resolves above).
+        .filter((d) => !isControlDevice(d))
         .map((d) => ({
         name: d.name,
         sshTarget: d.name,

package/dist/commands/exec.js

@@ -329,41 +329,69 @@ export function registerRunCommand(program) {
                 process.exit(1);
             }
             const backend = typeof options.lease === 'string' ? options.lease : undefined;
-            const { detectSignedInRuntimes, pickRuntimes, resolveClaudeCredentialsBlob } = await import('../lib/crabbox/runtimes.js');
+            // First-run: no provider credential resolves (no env var, no config, no
+            // detectable bundle) → guide the user through one-time setup, then continue.
+            const { resolveLeaseBundle } = await import('../lib/crabbox/cli.js');
+            if (!resolveLeaseBundle()) {
+                const { runLeaseSetup } = await import('./lease.js');
+                const ok = await runLeaseSetup({ provider: backend ?? 'hetzner' });
+                if (!ok) {
+                    console.error(chalk.yellow('Leasing needs a cloud provider set up. Run `agents lease setup` and retry.'));
+                    process.exit(1);
+                }
+            }
+            const { detectSignedInRuntimes, resolveClaudeCredentialsBlob, inferLeaseRuntime } = await import('../lib/crabbox/runtimes.js');
             const { leaseAndRun } = await import('../lib/crabbox/lease.js');
-            const { confirm } = await import('@inquirer/prompts');
+            const { getConfiguredRunStrategy, resolveRunVersion } = await import('../lib/rotate.js');
             const detected = await detectSignedInRuntimes();
-            const runtimes = await pickRuntimes(detected);
-            if (runtimes.length === 0) {
-                console.error(chalk.yellow('No runtimes selected. Sign into one locally (e.g. run `claude` once) then retry.'));
+            const agentName = agentSpec.split('@')[0];
+            const leaseCwd = options.cwd ?? process.cwd();
+            // `--lease` requires a prompt (guarded above), so it is headless by
+            // contract — never block on an interactive picker. Provision exactly the
+            // one runtime this run needs, inferred from the agent, not every
+            // signed-in CLI (which would ship unrelated tokens to a throwaway box).
+            const runtime = inferLeaseRuntime(agentName, detected);
+            if (!runtime) {
+                console.error(chalk.yellow('No signed-in runtime to provision on the box. Sign into one locally (e.g. run `claude` once) then retry.'));
                 process.exit(1);
             }
-            // Security gate: copying auth tokens to an ephemeral cloud box is opt-in
-            // per run. Name the runtimes + accounts so the user sees what ships.
-            const names = runtimes
-                .map((id) => {
-                const d = detected.find((x) => x.id === id);
-                return `${d?.label ?? id}${d?.email ? ` (${d.email})` : ''}`;
-            })
-                .join(', ');
-            // Claude ships its OAuth token (not just the .claude.json config) — name it
-            // explicitly so the consent covers the actual credential transferred.
-            const whatShips = runtimes.includes('claude') ? 'credentials + Claude OAuth token' : 'credentials';
-            const ok = await confirm({
-                message: `Copy ${whatShips} for ${names} to a disposable cloud box, run there, then destroy it?`,
-                default: false,
-            });
-            if (!ok) {
-                console.error(chalk.yellow('Aborted — no credentials pushed, no box leased.'));
-                process.exit(1);
+            const runtimes = [runtime];
+            // Copy the account the run's OWN strategy would pick (default `balanced`:
+            // a healthy, non-rate-limited account weighted by remaining headroom) —
+            // never the raw default signed-in one, which could be throttled or out of
+            // credits and would boot the box straight into a wall.
+            //
+            // Only claude's token is account-switched: resolveClaudeCredentialsBlob
+            // honors preferEmail across version-homes. The other runtimes'
+            // buildCredentialScript copies the single currently-active credential file
+            // with no switching, so run the balanced picker only for claude — otherwise
+            // the notice below would name a balanced-picked account that is NOT the one
+            // actually shipped. Best-effort: fall back to the default account on error.
+            let leaseEmail = detected.find((d) => d.id === runtime)?.email ?? null;
+            if (runtime === 'claude') {
+                try {
+                    const strategy = getConfiguredRunStrategy(runtime, leaseCwd);
+                    const { rotation } = await resolveRunVersion(runtime, strategy, leaseCwd);
+                    if (rotation?.picked.email)
+                        leaseEmail = rotation.picked.email;
+                }
+                catch {
+                    /* strategy resolution is best-effort; keep the default signed-in account */
+                }
             }
+            // Headless-by-contract: don't prompt, but print exactly what ships and
+            // where — copying an auth token to a cloud box is a credential transfer.
+            // The box is destroyed after the run, so the credential's lifetime is
+            // bounded by the run.
+            const whatShips = runtime === 'claude' ? 'credentials + Claude OAuth token' : 'credentials';
+            console.error(chalk.gray(`Leasing a ${backend ?? 'hetzner'} box · shipping ${runtime}${leaseEmail ? ` (${leaseEmail})` : ''} ${whatShips}; the box is destroyed after the run.`));
             // Read the Claude OAuth token from the local Keychain (silent) so it can be
             // written to ~/.claude/.credentials.json on the box — otherwise Claude boots
-            // "Not logged in". Consent above already covered this transfer.
+            // "Not logged in". `preferEmail` targets the strategy-picked account so the
+            // token matches the account this run resolved to.
             let claudeCredentialsJson = null;
-            if (runtimes.includes('claude')) {
-                const claudeEmail = detected.find((d) => d.id === 'claude')?.email ?? null;
-                claudeCredentialsJson = await resolveClaudeCredentialsBlob({ preferEmail: claudeEmail });
+            if (runtime === 'claude') {
+                claudeCredentialsJson = await resolveClaudeCredentialsBlob({ preferEmail: leaseEmail });
                 if (!claudeCredentialsJson) {
                     console.error(chalk.yellow('Warning: could not read the local Claude OAuth token — the box may come up "Not logged in".'));
                 }
@@ -374,7 +402,6 @@ export function registerRunCommand(program) {
             // box-side marker. Rule: only ONE spinner phase is active at a time, and no
             // other output is written to stderr while it spins — so it can never storm.
             const { createLeaseOutputRouter, createSpinner } = await import('../lib/crabbox/progress.js');
-            const agentName = agentSpec.split('@')[0];
             const spinner = createSpinner({ stream: process.stderr });
             let warmupTimer;
             const stopTimer = () => { if (warmupTimer) {
@@ -480,33 +507,45 @@ export function registerRunCommand(program) {
                 process.exit(1);
             }
             const hostName = hostGiven[0];
-            const { resolveHost, resolveHostByCap } = await import('../lib/hosts/registry.js');
-            const { dispatchToHost, runInteractiveOnHost } = await import('../lib/hosts/dispatch.js');
-            const { registerHostSession, registerInteractiveHostSession } = await import('../lib/hosts/session-index.js');
+            const { resolveHostRunTarget, dispatchPromptToHost, HostResolutionError } = await import('../lib/hosts/run-target.js');
+            const { runInteractiveOnHost } = await import('../lib/hosts/dispatch.js');
+            const { registerInteractiveHostSession } = await import('../lib/hosts/session-index.js');
+            const { RUN_OPTION_REJECT_MESSAGES } = await import('../lib/hosts/remote-cmd.js');
             const { normalizeRunStrategy, RUN_STRATEGIES } = await import('../lib/rotate.js');
-            // A password-auth device throws DeviceOffloadUnsupportedError here; it's
-            // printed cleanly by the top-level catch in index.ts (covers every
-            // resolveHost caller), so it never falls through to capability routing.
-            let host = await resolveHost(hostName);
-            if (!host) {
-                // Not a host name — try capability routing (e.g. --host gpu). A
-                // "Multiple hosts tagged…" error is actionable and must surface;
-                // only "no host tagged" falls through to the generic unknown-host msg.
-                try {
-                    host = await resolveHostByCap(hostName, options.any);
-                }
-                catch (e) {
-                    const msg = e.message ?? '';
-                    if (msg.startsWith('Multiple hosts')) {
-                        console.error(chalk.red(msg));
-                        process.exit(1);
-                    }
-                }
-            }
-            if (!host) {
-                console.error(chalk.red(`Unknown host "${hostName}". List hosts: agents hosts list`));
+            // The forwarding contract (RUN_OPTION_FORWARDING): options that cannot
+            // cross the SSH boundary fail loud BEFORE dispatch — never a silent
+            // drop. Value-aware: only reject what was actually passed.
+            const hostRejects = [];
+            if (options.secrets.length > 0)
+                hostRejects.push(RUN_OPTION_REJECT_MESSAGES.secrets);
+            if (options.secretsKeys)
+                hostRejects.push(RUN_OPTION_REJECT_MESSAGES.secretsKeys);
+            if (options.allowExpired)
+                hostRejects.push(RUN_OPTION_REJECT_MESSAGES.allowExpired);
+            if (options.resumeCheckpoint)
+                hostRejects.push(RUN_OPTION_REJECT_MESSAGES.resumeCheckpoint);
+            if (options.resume === true)
+                hostRejects.push(RUN_OPTION_REJECT_MESSAGES.resumeBare);
+            if (hostRejects.length > 0) {
+                for (const msg of hostRejects)
+                    console.error(chalk.red(msg));
                 process.exit(1);
             }
+            // Shared resolution (name → capability tag → error). A password-auth
+            // device throws DeviceOffloadUnsupportedError inside the helper and
+            // propagates untouched — it's printed cleanly by the top-level catch in
+            // index.ts (covers every resolveHost caller).
+            let host;
+            try {
+                host = await resolveHostRunTarget(hostName, { any: options.any });
+            }
+            catch (e) {
+                if (e instanceof HostResolutionError) {
+                    console.error(chalk.red(e.message));
+                    process.exit(1);
+                }
+                throw e;
+            }
             try {
                 const [runAgent, rawRunVersion] = agentSpec.split('@');
                 // Forward the explicit @version pin verbatim. Resolving aliases like
@@ -609,10 +648,12 @@ export function registerRunCommand(program) {
                         agent: runAgent,
                         version: resumeId ? undefined : runVersion,
                         strategy: resumeId ? undefined : runStrategy,
+                        fallback: options.fallback,
                         prompt,
                         mode: options.mode,
                         model: options.model,
                         effort: options.effort,
+                        env: options.env,
                         addDir: hostAddDirs,
                         json: options.json,
                         verbose: options.verbose,
@@ -636,32 +677,37 @@ export function registerRunCommand(program) {
                     console.error(chalk.red('A prompt is required for headless host runs: agents run <agent> "<task>" --host <name>'));
                     process.exit(1);
                 }
-                const hostSessionId = runAgent === 'claude' && !resumeId ? randomUUID() : undefined;
-                const { task, exitCode } = await dispatchToHost(host, {
+                // Session-id mint, detached dispatch, and local session-index
+                // registration all live in the shared helper (lib/hosts/run-target.ts).
+                const { task, exitCode } = await dispatchPromptToHost(host, {
                     agent: runAgent,
                     version: resumeId ? undefined : runVersion,
                     strategy: resumeId ? undefined : runStrategy,
+                    fallback: options.fallback,
                     prompt,
                     mode: options.mode,
                     model: options.model,
                     effort: options.effort,
+                    env: options.env,
                     addDir: hostAddDirs,
+                    timeout: options.timeout,
+                    loop: options.loop,
+                    maxIterations: options.maxIterations,
+                    budget: options.budget,
+                    until: options.until,
+                    interval: options.interval,
                     json: options.json,
                     verbose: options.verbose,
-                    timeout: options.timeout,
                     yes: options.yes,
                     acp: options.acp,
+                    autoSecrets: options.autoSecrets,
                     remoteCwd: hostCwd,
-                    sessionId: hostSessionId,
                     name: options.name,
                     resume: resumeId,
                     follow: options.follow !== false,
+                    passthroughArgs,
                     copyCreds: hostCopyCreds,
                 });
-                // Register the dispatched run in the LOCAL session index so it shows
-                // up in `agents sessions` and resolves by id/name, even though its
-                // transcript lives on the host. No-op when no session id was captured.
-                registerHostSession(task, { cwd: process.cwd(), prompt });
                 if (options.follow === false) {
                     // The handle the caller uses to check on the run: the name if given,
                     // else the real host-task id (never the old literal `<id>`). Steer
@@ -776,7 +822,7 @@ export function registerRunCommand(program) {
                 await warnUnpushedWork(resumeExec.cwd ?? process.cwd());
             process.exit(resumeExit);
         }
-        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, headlessPlanStallCommand, nativeResume, resolveInteractive }, { ALL_AGENT_IDS }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle, assertRemoteBundleFlagsUnsupported }, { splitBundleRef, resolveSshTarget, remoteResolveEnv }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, rotationFailoverChain, shouldArmRotationFailover, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias, ensureAgentRunnable }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef, resolveAllowedSubagents, pruneStaleWorkflowSubagents }, { resolveRunDefaults }, { getMcpServersByName, buildWorkflowMcpConfig }, { supports },] = await Promise.all([
+        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, headlessPlanStallCommand, nativeResume, resolveInteractive }, { ALL_AGENT_IDS }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle, assertRemoteBundleFlagsUnsupported, isHeadlessSecretsContext }, { splitBundleRef, resolveSshTarget, remoteResolveEnv }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, rotationFailoverChain, shouldArmRotationFailover, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias, ensureAgentRunnable }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef, resolveAllowedSubagents, pruneStaleWorkflowSubagents, ensureSubagentDispatchTool }, { resolveRunDefaults }, { getMcpServersByName, buildWorkflowMcpConfig }, { supports },] = await Promise.all([
             import('../lib/exec.js'),
             import('../lib/agents.js'),
             import('../lib/profiles.js'),
@@ -814,6 +860,11 @@ export function registerRunCommand(program) {
         // produced item, and drives the teams supervisor to drain — no `teams`
         // subcommands needed.
         let workflowForEach;
+        // True once this run copies ≥1 dispatchable subagent into the shared agents
+        // dir. Used below to keep the `Task` tool in a `tools:`-restricted workflow —
+        // an orchestrator handed subagents but denied `Task` cannot reach them and
+        // degenerates to a no-op ("I'll wait for the completion notification").
+        let workflowHasSubagents = false;
         const cwd = options.cwd ?? process.cwd();
         if (isValidAgent(rawAgent)) {
             agent = rawAgent;
@@ -895,6 +946,8 @@ export function registerRunCommand(program) {
                     workflowSubagentTargets.push(dest);
                     copied++;
                 }
+                if (copied > 0)
+                    workflowHasSubagents = true;
                 if (allowedAgents !== undefined) {
                     // Surface any allowedAgents entry with no matching subagent file, and
                     // report how many were filtered out, so the scope is auditable.
@@ -938,7 +991,9 @@ export function registerRunCommand(program) {
             }
             // Auto-inject secrets bundles declared in the workflow's frontmatter `secrets:` field.
             // Union with any --secrets flags the user passed; dedupe. Skip when --no-auto-secrets is set.
-            if (!options.noAutoSecrets) {
+            // (Commander stores the negated flag as `autoSecrets: false` — the old
+            // `noAutoSecrets` read was never populated, making the flag a no-op.)
+            if (options.autoSecrets !== false) {
                 const declared = workflowFrontmatter?.secrets ?? [];
                 if (declared.length > 0) {
                     const existing = new Set(options.secrets);
@@ -975,8 +1030,14 @@ export function registerRunCommand(program) {
             }
             else if (hasScoping) {
                 if (tools && tools.length > 0) {
-                    workflowToolsRestrict = tools;
-                    process.stderr.write(chalk.gray(`[workflow] restricting available tools to: ${tools.join(', ')} (Write/Bash/Edit unavailable unless listed)\n`));
+                    // An orchestrator with dispatchable subagents MUST retain the `Task`
+                    // tool, or it can't reach the subagents this run just installed for it
+                    // — the run silently no-ops ("I'll wait for the completion notification").
+                    workflowToolsRestrict = ensureSubagentDispatchTool(tools, workflowHasSubagents);
+                    process.stderr.write(chalk.gray(`[workflow] restricting available tools to: ${workflowToolsRestrict.join(', ')} (Write/Bash/Edit unavailable unless listed)\n`));
+                    if (workflowToolsRestrict.length !== tools.length) {
+                        process.stderr.write(chalk.gray(`[workflow] kept Task tool: workflow ships subagents to dispatch\n`));
+                    }
                 }
                 if (mcpServerNames && mcpServerNames.length > 0) {
                     const servers = getMcpServersByName(mcpServerNames, { cwd });
@@ -1159,8 +1220,12 @@ export function registerRunCommand(program) {
             process.exit(1);
         }
         const strategy = options.balanced ? 'balanced' : explicitStrategy ?? configuredStrategy;
-        // Strategy only applies to bare agent invocations. Explicit @version,
-        // profiles, and fallback chains already define their execution target.
+        // Strategy only applies to bare agent invocations. Explicit @version and
+        // profiles already define their execution target. A --fallback chain does
+        // NOT pin the primary: it only names where to cascade on a rate limit, so
+        // the bare primary still resolves through the strategy — otherwise every
+        // `agents run claude --fallback codex` run lands on the pinned default
+        // account and account rotation silently stops (the gh-monitor heal bug).
         if (strategy !== 'pinned' || options.balanced || explicitStrategy) {
             if (version) {
                 process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} ignored: version ${version} is pinned\n`));
@@ -1168,9 +1233,6 @@ export function registerRunCommand(program) {
             else if (fromProfile) {
                 process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} ignored: profile pins its own version/auth\n`));
             }
-            else if (options.fallback) {
-                process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} ignored: --fallback pins versions directly\n`));
-            }
             else {
                 try {
                     const resolved = await resolveRunVersion(agent, strategy, cwd);
@@ -1323,6 +1385,10 @@ export function registerRunCommand(program) {
                         caller: `agent ${agent}`,
                         keys: secretsKeysSubset,
                         allowExpired: options.allowExpired,
+                        // A headless/background run (routine, teammate, detached) must not
+                        // pop a Touch ID sheet nobody can answer — resolve broker-only and
+                        // fail fast with an actionable error. Interactive runs still prompt.
+                        agentOnly: isHeadlessSecretsContext(),
                     });
                     const entries = describeBundle(bundle);
                     const counts = {};
@@ -1443,17 +1509,23 @@ export function registerRunCommand(program) {
         // path (continuing the session via /continue). Because this injects into
         // the same `fallback` array `--fallback` uses, it must only arm for run
         // shapes that accept a fallback chain — shouldArmRotationFailover excludes
-        // acp/loop/resume-checkpoint (which reject a non-empty fallback below),
-        // interactive/no-prompt runs, and runs that already have an explicit or
-        // profile fallback. Pinned/single-account runs stay unchanged because
-        // rotationResult is null or rotationFailoverChain returns []. version is
-        // set here because rotationResult is only populated when resolveRunVersion
-        // picked one.
+        // acp/loop/resume-checkpoint (which reject a non-empty fallback below)
+        // and interactive/no-prompt runs. Pinned/single-account runs stay
+        // unchanged because rotationResult is null or rotationFailoverChain
+        // returns []. version is set here because rotationResult is only
+        // populated when resolveRunVersion picked one.
+        //
+        // Composes with an explicit --fallback chain: the same-agent accounts are
+        // UNSHIFTED ahead of the user's cross-agent entries, so a rate limit
+        // first tries the other accounts of the same agent (cheapest recovery —
+        // same CLI, session continues) and only then cascades to codex/gemini/etc.
+        // Profiles never compose: strategy is skipped for them, rotationResult
+        // stays null. (fromProfile's model-swap unshift above is therefore never
+        // displaced by this one.)
         if (shouldArmRotationFailover({
             hasRotation: !!rotationResult,
             hasVersion: !!version,
             hasPrompt: prompt !== undefined,
-            explicitFallback: fallback.length > 0,
             interactive: !!options.interactive,
             acp: !!options.acp,
             loop: !!options.loop,
@@ -1461,7 +1533,7 @@ export function registerRunCommand(program) {
         })) {
             const failover = rotationFailoverChain(rotationResult, version);
             if (failover.length > 0) {
-                fallback.push(...failover);
+                fallback.unshift(...failover);
                 if (!options.quiet) {
                     const accounts = failover.map(f => `${f.agent}@${f.version}`).join(', ');
                     process.stderr.write(chalk.gray(`[agents] rate-limit failover armed: ${accounts}\n`));

package/dist/commands/feed.d.ts

@@ -13,6 +13,10 @@ import type { Command } from 'commander';
 import { type OpenBlock } from '../lib/feed.js';
 import { type OutcomeGroup, type SessionOutcomeHint } from '../lib/feed-outcome.js';
 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;
+/** Reply hint matching the shared fleet-comms reply line. */
+export declare function formatFeedReplyHint(mailboxId: string): string;
 export declare function parseRemoteFeed(stdout: string, machine: string): OpenBlock[];
 /** Merge local and remote rows, keeping the first copy of a host/session block. */
 export declare function mergeFeedBlocks(...groups: OpenBlock[][]): OpenBlock[];