@phnx-labs/agents-cli 1.22.115 → 1.22.116

package/dist/commands/exec.js

@@ -2045,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'),
@@ -2590,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
@@ -2622,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
@@ -2899,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).`));
@@ -2952,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);
@@ -3190,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.js

@@ -1,5 +1,5 @@
 import chalk from 'chalk';
-import { ensureFeedPublishHook, listAskStats, listBlocks, recordNotified, buildDeclaredBlock, publishBlock, } from '../lib/feed/feed.js';
+import { ensureFeedPublishHook, listAskStats, listBlocks, recordNotified, buildDeclaredBlock, deriveBlockState, publishBlock, } from '../lib/feed/feed.js';
 import { ensureActivityLogHook, readRecentActivity, formatActivityLine, formatProgressUpdate, mergeActivityEvents, parseActivityPayload, } from '../lib/feed/activity.js';
 import { projectKeyFromCwd } from '../lib/project-key.js';
 import { postFeedStatus } from '../lib/feed-post.js';
@@ -16,7 +16,7 @@ import { gatherRemoteAgentsJson } from '../lib/remote-agents-json.js';
 import { loadPolicy, applyPolicyToBlock, isPhoneUrgent } from '../lib/feed-policy.js';
 import { notifyUrgentBlock } from '../lib/notify.js';
 import { registerFeedWatchCommand } from './feed-watch.js';
-import { claimAndRouteAttentionAnswer, forwardFeedAnswer } from '../lib/feed/answer.js';
+import { AnswerError, answerOwnerIsLocal, checkAnswerDelivery, claimAndRouteAttentionAnswer, forwardFeedAnswer, parseAttentionKey, } from '../lib/feed/answer.js';
 import { gcMailbox } from '../lib/mailbox-gc.js';
 import { isValidMailboxId } from '../lib/mailbox.js';
 import { getActiveSessions } from '../lib/session/active.js';
@@ -171,7 +171,10 @@ function renderBlock(b, localHost, indent = '') {
     const cost = b.costOfDelay ? chalk.gray(`cost:${b.costOfDelay}`) : '';
     const rank = b.delayRank ? chalk.gray(`rank:${Math.round(b.delayRank.score)}`) : '';
     // Shared fleet-comms glyphs: ▲ open ask, ✓ answered (see comms-render GLYPH).
-    const marker = b.answer
+    // A PENDING claim carries an answer record while the block is still open, so
+    // the delivered glyph is driven by the canonical state, not by `b.answer`
+    // being set — a claimed-but-undelivered ask must keep reading as needs-you.
+    const marker = deriveBlockState(b) !== 'open'
         ? chalk.green(GLYPH.delivered)
         : b.kind === 'control'
             ? chalk.red('!')
@@ -197,7 +200,9 @@ function renderBlock(b, localHost, indent = '') {
     if (b.answer) {
         const verified = b.answer.verified ? chalk.green(GLYPH.delivered) : chalk.yellow('?');
         const who = b.answer.answeredFrom + (b.answer.answeredBy ? ` (${b.answer.answeredBy})` : '');
-        console.log(`${indent}  ${chalk.green('answered')} by ${who} ${verified}`);
+        const pending = deriveBlockState(b) === 'open';
+        const label = pending ? chalk.yellow('claimed (delivery unconfirmed)') : chalk.green('answered');
+        console.log(`${indent}  ${label} by ${who} ${verified}`);
     }
     if (b.parkedAt) {
         console.log(`${indent}  ${chalk.red('hard-parked')} ${relTime(b.parkedAt)}`);
@@ -314,6 +319,23 @@ export async function loadSessionMetasForFeedEnrichment(load) {
         throw err;
     }
 }
+/**
+ * One human line per answer outcome. The three states the operator has to tell
+ * apart are a real receipt, a hand-off no rail can confirm, and a refusal —
+ * never collapsed into a single "Delivered" (PHNX-3999).
+ */
+function renderAnswerResult(result) {
+    switch (result.status) {
+        case 'failed':
+            return `Not delivered: ${result.reason ?? 'unknown failure'} — answering again is safe.`;
+        case 'unknown':
+            return `Delivery unconfirmed: ${result.reason ?? 'no rail reported a receipt.'} Run \`agents feed answer ${result.attentionKey} --check\` rather than resending.`;
+        case 'already_answered':
+            return `Already answered — ${result.receipt?.status ?? 'claimed'}${result.receipt ? ` as ${result.receipt.msgId}` : ''} at ${result.receipt?.at ?? result.attempt}.`;
+        default:
+            return `Delivered ${result.receipt?.msgId} (${result.receipt?.status}).`;
+    }
+}
 export function registerFeedCommand(program) {
     const feed = program
         .command('feed')
@@ -334,23 +356,52 @@ export function registerFeedCommand(program) {
         .option('--choice <choice-id>', 'Stable choice id from the attention item')
         .option('--text <answer>', 'Free-text answer')
         .option('--as <operator>', 'Verified operator id for high-consequence answers')
+        .option('--check', 'Read-only: report this item\'s delivery state without claiming, routing or resending')
+        .option('--attempt <at>', 'With --check: the attempt timestamp being checked, so a newer one is reported as such')
         .option('--json', 'Emit the delivery result as JSON')
         .action(async (attentionKey, opts, invoked) => {
+        const wantsJson = Boolean(opts.json || invoked.parent?.opts()?.json);
         try {
-            const ownerHost = attentionKey.slice(0, attentionKey.indexOf('/'));
-            const result = ownerHost && ownerHost !== machineId()
-                ? await forwardFeedAnswer({ host: ownerHost, attentionKey, choiceId: opts.choice, text: opts.text, operatorId: opts.as })
-                : await claimAndRouteAttentionAnswer({
-                    attentionKey, choiceId: opts.choice, text: opts.text,
-                    operator: { id: opts.as, verified: Boolean(opts.as), label: opts.as },
-                });
-            if (opts.json || invoked.parent?.opts()?.json)
+            // The key's own host decides the rail; `answerOwnerIsLocal` normalizes
+            // both sides so a `.local` suffix is not read as a different machine.
+            const { host: ownerHost } = parseAttentionKey(attentionKey);
+            const local = answerOwnerIsLocal(ownerHost);
+            if (opts.check && (opts.choice != null || opts.text != null)) {
+                throw new AnswerError('--check is read-only; it takes no --choice or --text.', 'empty_answer');
+            }
+            if (opts.attempt != null && !opts.check) {
+                throw new AnswerError('--attempt only applies to --check.', 'empty_answer');
+            }
+            const result = opts.check
+                ? (local
+                    ? checkAnswerDelivery(attentionKey, undefined, opts.attempt)
+                    : await forwardFeedAnswer({ host: ownerHost, attentionKey, check: true, attempt: opts.attempt, operatorId: opts.as }))
+                : local
+                    ? await claimAndRouteAttentionAnswer({
+                        attentionKey, choiceId: opts.choice, text: opts.text,
+                        operator: { id: opts.as, verified: Boolean(opts.as), label: opts.as },
+                    })
+                    : await forwardFeedAnswer({ host: ownerHost, attentionKey, choiceId: opts.choice, text: opts.text, operatorId: opts.as });
+            if (wantsJson)
                 console.log(JSON.stringify(result));
             else
-                console.log(result.status === 'delivered' ? `Delivered ${result.receipt.msgId}.` : `Already answered (${result.receipt.at}).`);
+                console.log(renderAnswerResult(result));
         }
         catch (error) {
-            invoked.error(`error: ${error instanceof Error ? error.message : String(error)}`);
+            // A failure is a first-class outcome for the operator UI, not a parse
+            // error: `--json` still gets a result object it can branch on, with a
+            // non-zero exit so a scripted caller sees the failure too.
+            const message = error instanceof Error ? error.message : String(error);
+            if (wantsJson) {
+                const failure = {
+                    status: 'failed', delivery: 'failed', resolved: false, reason: message,
+                    code: error instanceof AnswerError ? error.code : 'rail_failed', attentionKey,
+                };
+                console.log(JSON.stringify(failure));
+                process.exitCode = 1;
+                return;
+            }
+            invoked.error(`error: ${message}`);
         }
     });
     feed

package/dist/commands/sessions-picker.d.ts

@@ -153,6 +153,17 @@ export interface SessionPreviewDigest {
     firstError?: string;
     toolHistogram: ReturnType<typeof toolHistogram>;
     test: ReturnType<typeof detectTestResult>;
+    /**
+     * True when this digest was built WITHOUT parsing the transcript (PHNX-3999):
+     * the file exceeded {@link PREVIEW_DIGEST_MAX_PARSE_BYTES} and no cached
+     * digest existed yet. `firstUser`/`lastAssistant` fall back to the already-
+     * indexed `SessionMeta.firstUserMessage`/`lastUserMessage` (cheap, no parse)
+     * rather than being silently empty; every event-derived field (toolCalls,
+     * changedFiles, artifacts, etc.) stays at its zero-value default because it
+     * genuinely was not computed, not because nothing happened.
+     */
+    partial?: boolean;
+    partialReason?: string;
 }
 /** Fold a harness-normalized event stream into the stable preview data model. */
 export declare function buildSessionPreviewDigest(events: SessionEvent[], session: SessionMeta): SessionPreviewDigest;