@phnx-labs/agents-cli 1.22.115 → 1.22.117

package/dist/commands/exec.js

@@ -90,6 +90,24 @@ export function parseRunPickerMarkers(agentSpec) {
 export function hostTargetGiven(options) {
     return [options.host, options.device, options.on, options.computer].filter((v) => !!v);
 }
+/**
+ * Turn a host target that names THIS machine into an explicit local pin: the
+ * host-family flags are cleared and `local` is set, so no dispatch path
+ * self-SSHes and the bare-interactive default (`bareInteractiveRunDefaultsToDeviceAuto`)
+ * sees a decided placement. Returns true when the pin was applied. Pure over
+ * the `isSelf` predicate so the rule is testable without a device registry.
+ */
+export function pinLocalWhenTargetIsSelf(options, isSelf) {
+    const targets = hostTargetGiven(options);
+    if (targets.length === 0 || !targets.every(isSelf))
+        return false;
+    options.host = undefined;
+    options.device = undefined;
+    options.on = undefined;
+    options.computer = undefined;
+    options.local = true;
+    return true;
+}
 /**
  * Return every option whose selection semantics conflict with an account
  * choice (`agent#`). Device routing is deliberately absent: the marker rides
@@ -118,6 +136,8 @@ export function runAccountPickerConflicts(options) {
  */
 export function runDevicePickerConflicts(options) {
     const conflicts = hostTargetGiven(options).map((h) => `--device ${h}`);
+    if (options.local)
+        conflicts.push('--local');
     if (options.lease)
         conflicts.push('--lease');
     if (options.box)
@@ -145,6 +165,11 @@ export { RUN_AUTO_KEYWORD };
  * fleet. Pure so the pinning matrix is unit-testable.
  */
 export function runAutoDefaultsToAffinity(options, env = process.env) {
+    // An explicit local pin (--local, --where local, --device <this machine>)
+    // is a decided host layer with an empty host set; read it here so the
+    // `run auto` and bare-interactive defaults share one rule.
+    if (options.local)
+        return false;
     if (hostTargetGiven(options).length > 0)
         return false;
     if (env.AGENTS_RUN_AUTO_HOST_RESOLVED === '1')
@@ -639,7 +664,8 @@ export function registerRunCommand(program) {
         .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] | cloud[:provider]. Expands to --device/--lease/--cloud. Do not combine with those flags. See docs/00-concepts.md#placement.')
-        .option('-D, --device <name>', 'Offload this run onto another machine over SSH — a registered device, or user@host. Pass "auto" to pick the least-loaded reachable device where the requested agent is installed and signed in, keeping the run local when no remote is better, or "interactive" for the machine pinned as interactive.host (the box a human is sitting at). Same as --where device:<name>. See `agents devices`.')
+        .option('--local', 'Run on this machine. A bare interactive run otherwise places itself like --device auto; --local pins it here. Same as --where local or --device <this machine>.')
+        .option('-D, --device <name>', 'Offload this run onto another machine over SSH — a registered device, or user@host. Pass "auto" to pick the least-loaded reachable device where the requested agent is installed and signed in, keeping the run local when no remote is better, or "interactive" for the machine pinned as interactive.host (the box a human is sitting at). Naming this machine runs locally, no SSH. Same as --where device:<name>. See `agents devices`.')
         .option('--remote-cwd <dir>', "Explicit device working directory for --device 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).")
         .option('--no-follow', 'With --device, dispatch detached and return immediately (track via `agents hosts ps/logs`).')
         .option('--any', 'With --device <cap> (a capability tag), pick any matching device instead of erroring when several match.')
@@ -680,9 +706,9 @@ export function registerRunCommand(program) {
       agents run claude "fix lint errors in src/" --mode edit
 
       # Interactive (TUI): a bare run places itself like --device auto (a fleet
-      # worker, TUI forwarded over SSH); pin the device to stay on this machine
+      # worker, TUI forwarded over SSH); --local keeps it on this machine
       agents run claude
-      agents run claude --device zion      # stay local (or pick this machine in claude@)
+      agents run claude --local            # stay local (or pick this machine in claude@)
 
       # Pick a signed-in account/version for only this run (# = account picker)
       agents run claude#
@@ -790,10 +816,10 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
       Interactive placement: a bare 'agents run <harness>' (no prompt, real TTY)
         places itself like --device auto — a fleet worker runs it, with the TUI
         forwarded over SSH. Headless runs (any prompt, --json, no TTY) are
-        unchanged: they run in place. To stay on this machine, pass
-        --device <this machine>, or pick this machine (listed first) in the
-        '<harness>@' device picker. When placement finds no healthy device the
-        run fails loud and names the local spellings.
+        unchanged: they run in place. To stay on this machine, pass --local
+        (--device <this machine> means the same), or pick this machine (listed
+        first) in the '<harness>@' device picker. When placement finds no
+        healthy device the run fails loud and names the local spelling.
 
       Fallback: --fallback codex,antigravity retries on rate-limit failure via /continue handoff. Each entry accepts @version.
 
@@ -891,6 +917,11 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             const { placementFromRunFlags, expandPlacementToRunFlags, PlacementError } = await import('../lib/placement.js');
             try {
                 const placement = placementFromRunFlags(options);
+                // An explicit local placement (--local, --where local) must outlive
+                // this block: expansion yields no host flag, and the bare-interactive
+                // default below reads an empty host set as "decide for me".
+                if (placement.kind === 'local' && placement.source !== 'default')
+                    options.local = true;
                 if (options.where) {
                     const expanded = expandPlacementToRunFlags(placement);
                     if (expanded.host !== undefined)
@@ -918,6 +949,16 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 throw err;
             }
         }
+        // --device naming this machine (short id, MagicDNS name, loopback, or the
+        // `interactive` sentinel pinned here) is a local run, not a self-SSH: the
+        // hop probes its own login shell and times out under load. Pinned here,
+        // ahead of every placement gate, so the bare-interactive default sees an
+        // explicit local choice rather than an empty host set.
+        {
+            const { isSelfHost } = await import('../lib/devices/self-host.js');
+            const { isDeviceInteractive, resolveInteractiveDevice } = await import('../lib/devices/interactive-host.js');
+            pinLocalWhenTargetIsSelf(options, (name) => isSelfHost(isDeviceInteractive(name) ? resolveInteractiveDevice() ?? name : name));
+        }
         // Cloud refinement flags without the placement are a typo, not a no-op.
         if (!options.cloud) {
             const { cloudFlagsWithoutCloud } = await import('./run-cloud.js');
@@ -1101,13 +1142,13 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             const { sessionRecoveryDestinationMatches, sessionRecoveryPeer, } = await import('../lib/session/recovery.js');
             const sourceMachine = resolvedResumeSource.machine;
             const sourcePeer = sessionRecoveryPeer(resolvedResumeSource);
-            const explicitPlacement = hostTargetGiven(options).length > 0;
+            const explicitPlacement = hostTargetGiven(options).length > 0 || options.local === true;
             if (sourcePeer && !explicitPlacement) {
                 options.host = sourcePeer;
             }
             else if (sourcePeer && explicitPlacement && !hostTargetGiven(options).some((host) => sessionRecoveryDestinationMatches(resolvedResumeSource, host))) {
                 console.error(chalk.red(`Session ${resolvedResumeSource.shortId} must recover on ${sourcePeer}, where its conversation state is stored; ` +
-                    `the requested device was ${hostTargetGiven(options).join(', ')}.`));
+                    `the requested device was ${hostTargetGiven(options).join(', ') || 'this machine'}.`));
                 process.exit(1);
             }
             // Recovery is resolved on the device that owns the transcript. A remote
@@ -1246,8 +1287,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 if (!defaultPlacement)
                     throw err;
                 console.error(chalk.red(err.message));
-                const { machineId } = await import('../lib/machine-id.js');
-                console.error(chalk.gray(`Run here instead: agents run ${runBaseAgentName} --device ${machineId()}`));
+                console.error(chalk.gray(`Run here instead: agents run ${runBaseAgentName} --local`));
                 process.exit(1);
             }
             if (!options.quiet && result.banner) {
@@ -2045,7 +2085,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
         const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, implicitModeFor, headlessPlanStallCommand, nativeResume, resolveInteractive, inferredInteractiveWithoutTty }, { ALL_AGENT_IDS, ACCOUNT_INSPECTION_AGENT_IDS, agentLabel, supportsAccountInspection }, { profileExists, readProfile, resolveProfileForRun }, 
         // Engine DATA ops resolve through the standalone `secrets` process client
         // (PHNX-3989); the agents-owned `bundle@host` policy helpers stay in agents-cli.
-        { readAndResolveBundleEnv, describeBundle, remoteResolveEnv }, { assertRemoteBundleFlagsUnsupported, splitBundleRef, resolveSecretsContextForRun }, { resolveHostSshTarget }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, rotationFailoverChain, shouldArmRotationFailover, RUN_STRATEGIES, collectHarnessCandidates, pickHarnessWeighted, classifyHarnessCandidates, formatHarnessPickBanner, formatNoHealthyHarnessError, formatNoHealthyAccountError, formatNoVerifiedUsageError, signInRecoverableCandidates }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias, ensureAgentRunnable }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef, resolveAllowedSubagents, pruneStaleWorkflowSubagents, ensureSubagentDispatchTool }, { resolveRunDefaults }, { getMcpServersByName, buildWorkflowMcpConfig }, { supports, capableAgents }, { shareRuntimeEnv },] = await Promise.all([
+        { readAndResolveBundleEnv, describeBundle, remoteResolveEnv }, { assertRemoteBundleFlagsUnsupported, splitBundleRef, resolveSecretsContextForRun }, { resolveHostSshTarget }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, rotationFailoverChain, DEFAULT_ROTATION_FAILOVER_LIMIT, shouldArmRotationFailover, preflightFallbackHandoff, preflightHandoffEligible, RUN_STRATEGIES, collectHarnessCandidates, pickHarnessWeighted, classifyHarnessCandidates, formatHarnessPickBanner, formatNoHealthyHarnessError, formatNoHealthyAccountError, formatNoVerifiedUsageError, signInRecoverableCandidates }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias, ensureAgentRunnable }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef, resolveAllowedSubagents, pruneStaleWorkflowSubagents, ensureSubagentDispatchTool }, { resolveRunDefaults }, { getMcpServersByName, buildWorkflowMcpConfig }, { supports, capableAgents }, { shareRuntimeEnv },] = await Promise.all([
             import('../lib/exec.js'),
             import('../lib/agents.js'),
             import('../lib/profiles.js'),
@@ -2590,6 +2630,21 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
         // synthesize a same-agent fallback chain from the other healthy accounts
         // (issue #348). Stays null unless a non-pinned strategy actually rotated.
         let rotationResult = null;
+        /**
+         * The PRIMARY harness's configured run-default mode/effort, carried across a
+         * preflight alternate-harness handoff (PHNX-3999 F19).
+         *
+         * Run defaults are resolved after the harness is known, so without this a
+         * handoff would silently adopt the ALTERNATE's configured defaults — a
+         * primary configured `mode: plan` becoming the alternate's `mode: skip`
+         * escalates a read-only intent into an unattended writable run. The
+         * canonical mid-run cascade keeps the primary's resolved mode for the same
+         * reason (`runWithFallback` forwards `options.mode` and only re-derives the
+         * mode that was never configured at all). An IMPLICIT mode is deliberately
+         * not carried: it is the harness's own safe default, so the alternate's
+         * applies (identical to `modeWasImplicit ? implicitModeFor(agent)`).
+         */
+        let handoffRunDefaults;
         // Precomputed launchable-signed-in verdict for the ACTUAL launched
         // candidate, fed to the pre-launch `run.launch` event so it need not
         // re-probe. Sourced per resolution branch from the candidate that WON, not
@@ -2622,155 +2677,202 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
         // account and account rotation silently stops (the gh-monitor heal bug).
         // `pinned` still resolves so a logged-out default can yield to a signed-in
         // sibling on this device (PHNX-2685); an explicit @version pin is unchanged.
-        if (!accountPickerRequested && !configuredAccount && (!version || strategy !== 'pinned' || options.balanced || explicitStrategy)) {
-            if (version) {
-                process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} ignored: version ${version} is pinned\n`));
-            }
-            else if (fromProfile) {
-                process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} ignored: custom harness pins its own version/auth\n`));
-            }
-            else {
-                try {
-                    // Account-centric candidate list: native version-home logins PLUS
-                    // provider accounts (setup-token / API-key) that can auth this agent,
-                    // so `--strategy balanced` spreads across ALL accounts, not just the
-                    // ones sitting in a version home (RUSH-3182). Run-path only — the
-                    // picker's other callers keep the native-only collector.
-                    const { collectRunCandidatesForRun } = await import('../lib/accounting/account-pool-collect.js');
-                    bootMark('resolve-version:start');
-                    const routingModel = options.model ?? resolvedResumeSource?.model ?? workflowModel
-                        ?? (options.fallback ? undefined : resolveRunDefaults(agent, resolveVersion(agent, cwd), cwd).model);
-                    const resolved = await resolveRunVersion(agent, strategy, cwd, collectRunCandidatesForRun, routingModel);
-                    bootMark('resolve-version:done');
-                    if (resolved.exhausted) {
-                        // Zero healthy accounts splits two ways, and conflating them is what
-                        // stranded a logged-out harness with no way in at all (RUSH-2334):
-                        //
-                        // - THROTTLED (rate_limited / out_of_credits) -> fail loud (RUSH-2132).
-                        //   The old behavior warned "found no usable version; falling back to
-                        //   defaults" and launched the pinned default anyway — the exact move
-                        //   that loops a rotate into an exhausted account. Only a window reset
-                        //   clears it. The message text is a contract the Factory watchdog
-                        //   tail-detects; do not reword it.
-                        // - NEEDS A SIGN-IN (signed_out / revoked) -> launching IS the fix,
-                        //   because the harness's own TUI is the login surface. So on a TTY we
-                        //   carry the user into that login instead of erroring. Exiting here
-                        //   made `agents run <agent>`, `agents run <agent>#`, and `agents use`
-                        //   all dead-end with no reachable way to authenticate.
-                        const recoverable = signInRecoverableCandidates(resolved.exhausted);
-                        const { signInLaunchDecision } = await import('./run-account-picker.js');
-                        const decision = signInLaunchDecision({
-                            recoverable: recoverable.length,
-                            tty: isInteractiveTerminal(),
-                            json: options.json === true,
-                        });
-                        if (decision === 'launch') {
-                            const { pickSignInLaunchVersion } = await import('./run-account-picker.js');
-                            const signInVersion = await pickSignInLaunchVersion(agent, recoverable, !!options.quiet);
-                            // A cancelled prompt launches nothing — same contract as the
-                            // trailing-# account picker above.
-                            if (!signInVersion)
-                                return;
-                            version = signInVersion;
-                            // We just told the user this account is logged out and why we're
-                            // launching it, so suppress the downstream login preflight — it
-                            // would print a second, near-identical "looks logged out" warning.
-                            signInLaunch = true;
+        // Bounded handoff loop: each iteration resolves an account for `agent`, and
+        // the only `continue` is the preflight exhaustion handoff below, which
+        // consumes one entry of the `--fallback` spec before retrying as that
+        // alternate. The spec is finite, so this terminates (PHNX-3999 F19).
+        preflight: for (;;) {
+            if (!accountPickerRequested && !configuredAccount && (!version || strategy !== 'pinned' || options.balanced || explicitStrategy)) {
+                if (version) {
+                    process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} ignored: version ${version} is pinned\n`));
+                }
+                else if (fromProfile) {
+                    process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} ignored: custom harness pins its own version/auth\n`));
+                }
+                else {
+                    try {
+                        // Account-centric candidate list: native version-home logins PLUS
+                        // provider accounts (setup-token / API-key) that can auth this agent,
+                        // so `--strategy balanced` spreads across ALL accounts, not just the
+                        // ones sitting in a version home (RUSH-3182). Run-path only — the
+                        // picker's other callers keep the native-only collector.
+                        const { collectRunCandidatesForRun } = await import('../lib/accounting/account-pool-collect.js');
+                        bootMark('resolve-version:start');
+                        const routingModel = options.model ?? resolvedResumeSource?.model ?? workflowModel
+                            ?? (options.fallback ? undefined : resolveRunDefaults(agent, resolveVersion(agent, cwd), cwd).model);
+                        const resolved = await resolveRunVersion(agent, strategy, cwd, collectRunCandidatesForRun, routingModel);
+                        bootMark('resolve-version:done');
+                        if (resolved.exhausted) {
+                            // Zero healthy accounts splits two ways, and conflating them is what
+                            // stranded a logged-out harness with no way in at all (RUSH-2334):
+                            //
+                            // - THROTTLED (rate_limited / out_of_credits) -> fail loud (RUSH-2132).
+                            //   The old behavior warned "found no usable version; falling back to
+                            //   defaults" and launched the pinned default anyway — the exact move
+                            //   that loops a rotate into an exhausted account. Only a window reset
+                            //   clears it. The message text is a contract the Factory watchdog
+                            //   tail-detects; do not reword it.
+                            // - NEEDS A SIGN-IN (signed_out / revoked) -> launching IS the fix,
+                            //   because the harness's own TUI is the login surface. So on a TTY we
+                            //   carry the user into that login instead of erroring. Exiting here
+                            //   made `agents run <agent>`, `agents run <agent>#`, and `agents use`
+                            //   all dead-end with no reachable way to authenticate.
+                            const recoverable = signInRecoverableCandidates(resolved.exhausted);
+                            const { signInLaunchDecision } = await import('./run-account-picker.js');
+                            const decision = signInLaunchDecision({
+                                recoverable: recoverable.length,
+                                tty: isInteractiveTerminal(),
+                                json: options.json === true,
+                            });
+                            if (decision === 'launch') {
+                                const { pickSignInLaunchVersion } = await import('./run-account-picker.js');
+                                const signInVersion = await pickSignInLaunchVersion(agent, recoverable, !!options.quiet);
+                                // A cancelled prompt launches nothing — same contract as the
+                                // trailing-# account picker above.
+                                if (!signInVersion)
+                                    return;
+                                version = signInVersion;
+                                // We just told the user this account is logged out and why we're
+                                // launching it, so suppress the downstream login preflight — it
+                                // would print a second, near-identical "looks logged out" warning.
+                                signInLaunch = true;
+                            }
+                            else {
+                                // Every account of this harness is throttled. A configured
+                                // alternate exists for exactly this case, so hand off to it here
+                                // rather than exiting — `runWithFallback` would only reach it
+                                // after a run that can no longer start (PHNX-3999 F19). The
+                                // alternate becomes the primary and is dropped from the spec, so
+                                // the chain that remains never lists the agent now running.
+                                //
+                                // ONLY for a run shape `--fallback` is valid on. The handoff
+                                // consumes the entry it uses, and the canonical --fallback
+                                // validation runs later (it rejects interactive/--acp/--loop/
+                                // --resume-checkpoint chains and requires a prompt) — so
+                                // switching first on an ineligible shape would empty the spec,
+                                // leave that guard nothing to reject, and start the alternate
+                                // harness on a run the CLI refuses today. An ineligible shape
+                                // never switches, so the spec survives and still fails there
+                                // with its own message. See preflightHandoffEligible.
+                                const handoff = preflightHandoffEligible({
+                                    hasPrompt: prompt !== undefined,
+                                    interactive: options.interactive === true,
+                                    acp: options.acp === true,
+                                    loop: options.loop === true,
+                                    resumeCheckpoint: !!options.resumeCheckpoint,
+                                    resume: !!options.resume,
+                                    workflowScoped: !!workflowToolsRestrict || !!workflowMcpConfigPath,
+                                })
+                                    ? preflightFallbackHandoff(options.fallback, agent, resolved.exhausted)
+                                    : null;
+                                if (handoff) {
+                                    process.stderr.write(chalk.yellow(`[agents] every ${agent} account is exhausted — handing off to ${handoff.agent}${handoff.version ? `@${handoff.version}` : ''}\n`));
+                                    // Snapshot the PRIMARY's configured defaults BEFORE the switch —
+                                    // this is the operator's intent for this run, not the alternate's.
+                                    handoffRunDefaults ??= fromProfile ? undefined : resolveRunDefaults(agent, version ?? resolveVersion(agent, cwd), cwd);
+                                    agent = handoff.agent;
+                                    // Alias-resolve against the NEW harness's installs, exactly as
+                                    // the canonical --fallback parse does for its own entries.
+                                    version = resolveVersionAlias(agent, handoff.version);
+                                    options.fallback = handoff.remainingSpec;
+                                    rotationResult = null;
+                                    continue preflight;
+                                }
+                                console.error(chalk.red(formatNoHealthyAccountError(agent, strategy, resolved.exhausted)));
+                                if (recoverable.length > 0) {
+                                    // Off a TTY nobody can complete a login, so we still exit — but
+                                    // name the actual fix rather than only offering --strategy pinned,
+                                    // which would just pin the same unauthenticated account.
+                                    const { loginHint } = await import('../lib/signin-badge.js');
+                                    console.error(chalk.gray(`To sign in: ${loginHint(agent)} — or run \`agents run ${agent}\` from a terminal.`));
+                                }
+                                process.exit(1);
+                            }
                         }
-                        else {
-                            console.error(chalk.red(formatNoHealthyAccountError(agent, strategy, resolved.exhausted)));
-                            if (recoverable.length > 0) {
-                                // Off a TTY nobody can complete a login, so we still exit — but
-                                // name the actual fix rather than only offering --strategy pinned,
-                                // which would just pin the same unauthenticated account.
-                                const { loginHint } = await import('../lib/signin-badge.js');
-                                console.error(chalk.gray(`To sign in: ${loginHint(agent)} — or run \`agents run ${agent}\` from a terminal.`));
+                        else if (resolved.noVerifiedUsage) {
+                            // Entirely stale usage (PHNX-2526): every eligible account carries
+                            // a stale-but-present usage number and none is verified, so the
+                            // route would be a guess. NEVER auto-pick it. Interactive: show the
+                            // account picker so a human chooses with the (stale) numbers in
+                            // view. Unattended: fail loud with NO_VERIFIED_USAGE. The stale
+                            // pool survives ONLY as `resolved.rotation.healthy` for bounded
+                            // post-rejection failover, never as the initial pick.
+                            const { noVerifiedUsageDecision, pickRunAccountCandidate } = await import('./run-account-picker.js');
+                            const decision = noVerifiedUsageDecision({
+                                tty: isInteractiveTerminal(),
+                                json: options.json === true,
+                                headless: options.headless === true,
+                            });
+                            if (decision === 'picker') {
+                                const selected = await pickRunAccountCandidate(agent);
+                                // A cancelled picker launches nothing — same contract as the
+                                // trailing-# account picker and the sign-in launch above.
+                                if (!selected)
+                                    return;
+                                version = selected.version;
+                                // Source the run.launch verdict from the account the user ACTUALLY
+                                // picked — the picker may deliberately return a logged-out one
+                                // (RUSH-2334), so it can differ from rotationResult.picked.
+                                launchSignedIn = selected.signedIn;
+                                launchEmail = selected.email;
+                                // Keep the rotation so mid-run failover can still cascade across
+                                // the other (stale) healthy accounts after a real rejection.
+                                rotationResult = resolved.rotation;
+                                if (!options.quiet) {
+                                    const identity = selected.accountLabel || 'signed-in account';
+                                    process.stderr.write(chalk.gray(`[agents] no fresh usage for any ${agent} account — you picked ${identity} · ${agent}@${selected.version}\n`));
+                                }
+                            }
+                            else {
+                                console.error(chalk.red(formatNoVerifiedUsageError(agent, strategy, resolved.rotation?.healthy ?? [])));
+                                process.exit(1);
                             }
-                            process.exit(1);
                         }
-                    }
-                    else if (resolved.noVerifiedUsage) {
-                        // Entirely stale usage (PHNX-2526): every eligible account carries
-                        // a stale-but-present usage number and none is verified, so the
-                        // route would be a guess. NEVER auto-pick it. Interactive: show the
-                        // account picker so a human chooses with the (stale) numbers in
-                        // view. Unattended: fail loud with NO_VERIFIED_USAGE. The stale
-                        // pool survives ONLY as `resolved.rotation.healthy` for bounded
-                        // post-rejection failover, never as the initial pick.
-                        const { noVerifiedUsageDecision, pickRunAccountCandidate } = await import('./run-account-picker.js');
-                        const decision = noVerifiedUsageDecision({
-                            tty: isInteractiveTerminal(),
-                            json: options.json === true,
-                            headless: options.headless === true,
-                        });
-                        if (decision === 'picker') {
-                            const selected = await pickRunAccountCandidate(agent);
-                            // A cancelled picker launches nothing — same contract as the
-                            // trailing-# account picker and the sign-in launch above.
-                            if (!selected)
-                                return;
-                            version = selected.version;
-                            // Source the run.launch verdict from the account the user ACTUALLY
-                            // picked — the picker may deliberately return a logged-out one
-                            // (RUSH-2334), so it can differ from rotationResult.picked.
-                            launchSignedIn = selected.signedIn;
-                            launchEmail = selected.email;
-                            // Keep the rotation so mid-run failover can still cascade across
-                            // the other (stale) healthy accounts after a real rejection.
+                        else if (resolved.version) {
+                            version = resolved.version;
                             rotationResult = resolved.rotation;
-                            if (!options.quiet) {
-                                const identity = selected.accountLabel || 'signed-in account';
-                                process.stderr.write(chalk.gray(`[agents] no fresh usage for any ${agent} account — you picked ${identity} · ${agent}@${selected.version}\n`));
+                            // The auto-pick already computed the launchable-signed-in verdict for
+                            // this exact version via the same gate — reuse it for run.launch.
+                            if (resolved.rotation) {
+                                launchSignedIn = resolved.rotation.picked.signedIn;
+                                launchEmail = resolved.rotation.picked.email;
                             }
-                        }
-                        else {
-                            console.error(chalk.red(formatNoVerifiedUsageError(agent, strategy, resolved.rotation?.healthy ?? [])));
-                            process.exit(1);
-                        }
-                    }
-                    else if (resolved.version) {
-                        version = resolved.version;
-                        rotationResult = resolved.rotation;
-                        // The auto-pick already computed the launchable-signed-in verdict for
-                        // this exact version via the same gate — reuse it for run.launch.
-                        if (resolved.rotation) {
-                            launchSignedIn = resolved.rotation.picked.signedIn;
-                            launchEmail = resolved.rotation.picked.email;
-                        }
-                        // A balanced/available pick of a PROVIDER account (setup-token /
-                        // API-key) carries `providerAccount`. Resolve its env through the
-                        // same `resolveSpawnAccount` path an explicit `--account` uses, so
-                        // exec injects the credential; a native pick has no providerAccount
-                        // and runs from its own version home unchanged (RUSH-3182).
-                        const pickedProviderAccount = resolved.rotation?.picked.providerAccount;
-                        if (pickedProviderAccount) {
-                            try {
-                                const picked = resolveSpawnAccount(pickedProviderAccount, agent, resolved.version, readMeta(), { useDefault: false });
-                                if (picked?.kind === 'provider')
-                                    accountEnv = picked.env;
+                            // A balanced/available pick of a PROVIDER account (setup-token /
+                            // API-key) carries `providerAccount`. Resolve its env through the
+                            // same `resolveSpawnAccount` path an explicit `--account` uses, so
+                            // exec injects the credential; a native pick has no providerAccount
+                            // and runs from its own version home unchanged (RUSH-3182).
+                            const pickedProviderAccount = resolved.rotation?.picked.providerAccount;
+                            if (pickedProviderAccount) {
+                                try {
+                                    const picked = resolveSpawnAccount(pickedProviderAccount, agent, resolved.version, readMeta(), { useDefault: false });
+                                    if (picked?.kind === 'provider')
+                                        accountEnv = picked.env;
+                                }
+                                catch (err) {
+                                    console.error(chalk.red(err.message));
+                                    process.exit(1);
+                                }
                             }
-                            catch (err) {
-                                console.error(chalk.red(err.message));
-                                process.exit(1);
+                            if (resolved.rotation && !options.quiet) {
+                                const banner = formatRotationBanner(resolved.rotation, strategy);
+                                process.stderr.write(chalk.gray(banner + '\n'));
                             }
                         }
-                        if (resolved.rotation && !options.quiet) {
-                            const banner = formatRotationBanner(resolved.rotation, strategy);
-                            process.stderr.write(chalk.gray(banner + '\n'));
+                        else if (!options.quiet) {
+                            // No installed version at all (not "accounts exhausted" — that
+                            // fails loud above): keep the pre-existing default resolution.
+                            process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} found no usable ${agent} version; falling back to defaults\n`));
                         }
                     }
-                    else if (!options.quiet) {
-                        // No installed version at all (not "accounts exhausted" — that
-                        // fails loud above): keep the pre-existing default resolution.
-                        process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} found no usable ${agent} version; falling back to defaults\n`));
-                    }
-                }
-                catch (err) {
-                    if (!options.quiet) {
-                        process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} skipped: ${err.message}\n`));
+                    catch (err) {
+                        if (!options.quiet) {
+                            process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} skipped: ${err.message}\n`));
+                        }
                     }
                 }
             }
+            break;
         }
         // Self-heal the launch target. A gutted install (JS wrapper present,
         // native binary missing — a partial/raced npm extraction of the optional
@@ -2899,9 +3001,12 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
         // alias for 'skip' (rewritten downstream by normalizeMode in exec.ts).
         let mode = options.mode;
         const modeSource = runCmd.getOptionValueSource('mode');
-        const modeFromRunDefault = modeSource === 'default' && !!runDefaults.mode;
+        // A configured mode carried across a preflight handoff wins over the
+        // alternate harness's own configured default (see handoffRunDefaults).
+        const configuredMode = handoffRunDefaults?.mode ?? runDefaults.mode;
+        const modeFromRunDefault = modeSource === 'default' && !!configuredMode;
         if (modeFromRunDefault) {
-            mode = runDefaults.mode;
+            mode = configuredMode;
         }
         if (!['plan', 'edit', 'auto', 'skip', 'full'].includes(mode)) {
             console.error(chalk.red(`Invalid mode: ${mode}. Use plan, edit, auto, or skip ('full' accepted as alias for skip).`));
@@ -2952,7 +3057,8 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             process.exit(1);
         }
         const effortSource = runCmd.getOptionValueSource('effort');
-        const effort = (effortSource === 'default' && runDefaults.effort ? runDefaults.effort : options.effort);
+        const configuredEffort = handoffRunDefaults?.effort ?? runDefaults.effort;
+        const effort = (effortSource === 'default' && configuredEffort ? configuredEffort : options.effort);
         if (!['low', 'medium', 'high', 'xhigh', 'max', 'auto'].includes(effort)) {
             console.error(chalk.red(`Invalid effort: ${effort}. Use 'low', 'medium', 'high', 'xhigh', 'max', or 'auto'`));
             process.exit(1);
@@ -3190,7 +3296,12 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             loop: !!options.loop,
             resumeCheckpoint: !!options.resumeCheckpoint,
         })) {
-            const failover = rotationFailoverChain(rotationResult, version);
+            // With an explicit alternate harness configured, "use the alternate once
+            // the primary's accounts are exhausted" is the policy — so EVERY healthy
+            // same-agent account has to be tried first, not the default cap of three
+            // (PHNX-3999 F19). Without one, the cap stands: it bounds how long a
+            // rate-limited run keeps retrying itself.
+            const failover = rotationFailoverChain(rotationResult, version, fallback.length > 0 ? (rotationResult.healthy.length || DEFAULT_ROTATION_FAILOVER_LIMIT) : undefined);
             if (failover.length > 0) {
                 fallback.unshift(...failover);
                 if (!options.quiet) {