@phnx-labs/agents-cli 1.22.114 → 1.22.116

package/dist/commands/exec.js

@@ -660,8 +660,6 @@ export function registerRunCommand(program) {
     // `--on` and `--computer` are hidden aliases of `--device` — same behavior.
     runCmd.addOption(new Option('--on <name>', 'Alias of --device.').hideHelp());
     runCmd.addOption(new Option('--computer <name>', 'Alias of --device.').hideHelp());
-    // Deprecated one-release alias: `agents run … --smart` → treat as `--device auto`.
-    runCmd.addOption(new Option('--smart', 'Deprecated: use --device auto (affinity host pick).').hideHelp());
     // Internal: the `--device` dispatch forwards this so the REMOTE run prints its
     // resolved session id as a one-line stdout sentinel (hosts/session-marker.ts),
     // letting the launcher relate the remote-created session back to itself for
@@ -1226,7 +1224,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
         const defaultPlacement = bareInteractiveRunDefaultsToDeviceAuto(options, { prompt, devicePickerRequested }, { tty: isInteractiveTerminal(), json: options.json });
         if (defaultPlacement)
             options.device = 'auto';
-        // --device auto (and deprecated --smart): live fleet pick.
+        // --device auto: live fleet pick.
         // Harness is always the agent the user typed — never auto-picked.
         // Placement failure propagates; an automatic request never becomes local.
         {
@@ -1252,9 +1250,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 console.error(chalk.gray(`Run here instead: agents run ${runBaseAgentName} --device ${machineId()}`));
                 process.exit(1);
             }
-            if (!options.quiet && result.deprecationSmart) {
-                process.stderr.write(chalk.yellow('[agents] --smart is deprecated; use --device auto\n'));
-            }
             if (!options.quiet && result.banner) {
                 const { hostLabel, deviceHint, acctNote } = result.banner;
                 process.stderr.write(chalk.gray(`[agents] device=auto → ${hostLabel}` +
@@ -2050,7 +2045,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'),
@@ -2064,7 +2059,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             import('../lib/run-defaults.js'),
             import('../lib/mcp.js'),
             import('../lib/capabilities.js'),
-            import('../lib/share/config.js'),
+            import('../lib/share-runtime.js'),
         ]);
         bootMark('run-deps:imported');
         const isValidAgent = (agent) => ALL_AGENT_IDS.includes(agent);
@@ -2595,6 +2590,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
@@ -2627,155 +2637,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
@@ -2904,9 +2961,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).`));
@@ -2957,7 +3017,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);
@@ -3195,7 +3256,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) {

package/dist/commands/feed-watch.js

@@ -1,10 +1,51 @@
-import { machineId } from '../lib/machine-id.js';
 import { setHelpSections } from '../lib/help.js';
-import { watchFleetFeed, watchLocalFeed } from '../lib/feed/watch.js';
+import { streamFeedFromHub, waitForHub } from '../lib/feed/hub-server.js';
+import { ensureDaemonStarted } from '../lib/daemon/daemon.js';
+/**
+ * Attach to the daemon's shared collector, starting the daemon if it is not up.
+ *
+ * There is deliberately no in-process fallback: running `watchFleetFeed` here
+ * would give this reader its own ssh child per peer, which is exactly the
+ * per-caller fan-out the hub exists to collapse (see `lib/feed/hub.ts`). So a
+ * missing hub is answered by starting its owner and WAITING for it.
+ *
+ * The wait is what makes that honest. `ensureDaemonStarted()` returns once the
+ * process is spawned, long before it has loaded its services and bound the
+ * socket, so retrying immediately raced the bind and reported a daemon that was
+ * about to be perfectly healthy as unavailable. The final error is the one from
+ * the last real attempt, not the first.
+ */
+async function attachToHub(signal, emit, scope) {
+    try {
+        await streamFeedFromHub({ signal, emit, scope });
+        return;
+    }
+    catch (first) {
+        if (signal.aborted)
+            return;
+        ensureDaemonStarted();
+        if (!await waitForHub()) {
+            throw new Error(`the shared feed stream did not come up: ${first.message}\n`
+                + 'Next: agents daemon status, then agents daemon services enable feed-stream');
+        }
+        try {
+            await streamFeedFromHub({ signal, emit, scope });
+        }
+        catch (second) {
+            throw new Error(`the shared feed stream is unavailable: ${second.message}\n`
+                + 'Next: agents daemon status, then agents daemon services enable feed-stream');
+        }
+    }
+}
 export function registerFeedWatchCommand(parent) {
-    const command = parent.command('watch').description('Stream the canonical agent, attention, and activity projection as NDJSON')
+    const command = parent.command('watch').description('Stream the canonical agent, attention, tool, and activity projection as NDJSON')
         .option('--json', 'Emit versioned NDJSON envelopes').option('--local', 'Watch only this machine');
-    setHelpSections(command, { examples: `agents feed watch --json\nagents feed watch --json --local`, notes: 'Order by streamId + sequence. Unavailable scopes retain their last rows until reset on reconnect.' });
+    setHelpSections(command, {
+        examples: `agents feed watch --json\nagents feed watch --json --local`,
+        notes: 'Order by streamId + sequence. Unavailable scopes retain their last rows until reset on reconnect. '
+            + 'The fleet stream is served by the daemon\'s shared collector, so several readers cost one connection per peer; '
+            + '--local is the per-machine stream the collector itself subscribes to over ssh.',
+    });
     command.action(async (_opts, invoked) => {
         const opts = invoked.optsWithGlobals();
         if (!opts.json)
@@ -15,10 +56,13 @@ export function registerFeedWatchCommand(parent) {
         process.once('SIGINT', stop);
         process.once('SIGTERM', stop);
         try {
-            if (opts.local)
-                await watchLocalFeed({ scope: machineId(), signal: controller.signal, emit });
-            else
-                await watchFleetFeed({ signal: controller.signal, emit });
+            // BOTH scopes go through the daemon's shared collectors. `--local` used to
+            // run its own `watchLocalFeed`, so every observing box's ssh subscription
+            // built a separate activity cursor set, tool watcher and setup subscription
+            // on the SAME peer. The local collector is a distinct hub from the fleet one
+            // (`feed-stream-service.ts`) and its watcher dials no peer at all, so a
+            // local reader can never trigger a fan-out, recursively or otherwise.
+            await attachToHub(controller.signal, emit, opts.local ? 'local' : 'fleet');
         }
         finally {
             process.off('SIGINT', stop);