@phnx-labs/agents-cli 1.22.42 → 1.22.44

package/dist/lib/github/pr-mergeable.d.ts

@@ -0,0 +1,49 @@
+/**
+ * List this user's mergeable PRs across registered project repos.
+ *
+ * The built-in `pr-merge-on-green` monitor used to run `gh pr list --author @me`
+ * with no `--repo`. `gh` then infers the repository from the working directory,
+ * and the daemon's cwd is not a git repo, so every poll returned empty.
+ *
+ * This helper:
+ *   1. Collects GitHub slugs from `~/.agents/projects/*.yaml` (`repo` / `repos[].slug`).
+ *   2. Canonicalizes each slug (`gh repo view` — `phnx-labs/agents-cli` lists
+ *      nothing; the live name is `phnx-labs/agi-cli`).
+ *   3. Runs `gh pr list --repo <slug> --author @me` (cwd-independent).
+ *   4. Keeps CI-green PRs with a merge-guard verdict (formal APPROVED review
+ *      OR an APPROVE comment on THIS PR).
+ *
+ * Stdout is a single line of `owner/repo#n` refs (or empty). Empty is a silent
+ * observation under `condition.mode: every` — do not write to stderr on the
+ * no-match path, or command.ts will treat stderr as the observation and fire.
+ */
+import { type ProjectDef } from '../projects.js';
+import { type MergeablePrInput, type StatusCheck } from './pr-verdict.js';
+export type GhExec = (args: string[]) => Promise<string>;
+/** Default runner: `gh` with a 30s timeout. Non-zero exit throws. */
+export declare function ghExec(args: string[]): Promise<string>;
+/** Unique GitHub slugs declared on project definitions. */
+export declare function projectRepoSlugs(defs: readonly ProjectDef[]): string[];
+/**
+ * Resolve a slug to GitHub's current `nameWithOwner`. A renamed repo
+ * (`phnx-labs/agents-cli` → `phnx-labs/agi-cli`) lists zero PRs under the old
+ * name; `gh repo view` returns the live one. On error, keep the input slug.
+ */
+export declare function canonicalizeRepo(slug: string, gh: GhExec): Promise<string>;
+interface ListedPr {
+    number: number;
+    reviewDecision?: string | null;
+    statusCheckRollup?: StatusCheck[] | null;
+}
+/**
+ * Given PRs already listed for one repo, attach verdict payloads only for the
+ * CI-green ones that lack a formal APPROVED reviewDecision, then select.
+ */
+export declare function selectListedMergeable(repo: string, listed: readonly ListedPr[], gh: GhExec): Promise<MergeablePrInput[]>;
+/** List mergeable `owner/repo#n` refs, space-separated. Empty string if none. */
+export declare function listMergeableRefs(opts?: {
+    gh?: GhExec;
+    defs?: ProjectDef[];
+    repos?: string[];
+}): Promise<string>;
+export {};

package/dist/lib/github/pr-mergeable.js

@@ -0,0 +1,157 @@
+/**
+ * List this user's mergeable PRs across registered project repos.
+ *
+ * The built-in `pr-merge-on-green` monitor used to run `gh pr list --author @me`
+ * with no `--repo`. `gh` then infers the repository from the working directory,
+ * and the daemon's cwd is not a git repo, so every poll returned empty.
+ *
+ * This helper:
+ *   1. Collects GitHub slugs from `~/.agents/projects/*.yaml` (`repo` / `repos[].slug`).
+ *   2. Canonicalizes each slug (`gh repo view` — `phnx-labs/agents-cli` lists
+ *      nothing; the live name is `phnx-labs/agi-cli`).
+ *   3. Runs `gh pr list --repo <slug> --author @me` (cwd-independent).
+ *   4. Keeps CI-green PRs with a merge-guard verdict (formal APPROVED review
+ *      OR an APPROVE comment on THIS PR).
+ *
+ * Stdout is a single line of `owner/repo#n` refs (or empty). Empty is a silent
+ * observation under `condition.mode: every` — do not write to stderr on the
+ * no-match path, or command.ts will treat stderr as the observation and fire.
+ */
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { listProjectDefs } from '../projects.js';
+import { formatMergeableRef, hasApproveVerdict, isCiGreen, } from './pr-verdict.js';
+const execFileAsync = promisify(execFile);
+/**
+ * `gh --json` is not color-safe when this fleet exports FORCE_COLOR /
+ * CLICOLOR_FORCE: gh paints the payload and JSON.parse / jq die on the ANSI
+ * prefix (live miss on the sibling poll script). Strip the force vars and
+ * pin GH_NO_COLOR for every gh spawn.
+ */
+function ghEnv() {
+    const env = { ...process.env };
+    env.CLICOLOR = '0';
+    env.NO_COLOR = '1';
+    env.GH_NO_COLOR = '1';
+    env.GH_PAGER = 'cat';
+    delete env.CLICOLOR_FORCE;
+    delete env.FORCE_COLOR;
+    delete env.GH_FORCE_TTY;
+    return env;
+}
+/** Default runner: `gh` with a 30s timeout. Non-zero exit throws. */
+export async function ghExec(args) {
+    const { stdout } = await execFileAsync('gh', args, {
+        timeout: 30_000,
+        maxBuffer: 8 * 1024 * 1024,
+        encoding: 'utf-8',
+        env: ghEnv(),
+    });
+    return String(stdout ?? '');
+}
+/** Unique GitHub slugs declared on project definitions. */
+export function projectRepoSlugs(defs) {
+    const slugs = new Set();
+    for (const d of defs) {
+        if (d.repo)
+            slugs.add(d.repo);
+        for (const r of d.repos ?? []) {
+            if (r.slug)
+                slugs.add(r.slug);
+        }
+    }
+    return [...slugs].sort();
+}
+/**
+ * Resolve a slug to GitHub's current `nameWithOwner`. A renamed repo
+ * (`phnx-labs/agents-cli` → `phnx-labs/agi-cli`) lists zero PRs under the old
+ * name; `gh repo view` returns the live one. On error, keep the input slug.
+ */
+export async function canonicalizeRepo(slug, gh) {
+    try {
+        const out = (await gh([
+            'repo', 'view', slug, '--json', 'nameWithOwner', '--jq', '.nameWithOwner',
+        ])).trim();
+        return out || slug;
+    }
+    catch {
+        return slug;
+    }
+}
+async function fetchVerdict(repo, number, gh) {
+    const [reviewsRaw, commentsRaw] = await Promise.all([
+        gh(['api', `repos/${repo}/pulls/${number}/reviews`, '--cache', '60s']),
+        gh(['api', `repos/${repo}/issues/${number}/comments`, '--cache', '60s']),
+    ]);
+    const reviews = JSON.parse(reviewsRaw);
+    const comments = JSON.parse(commentsRaw);
+    return {
+        reviews: Array.isArray(reviews) ? reviews : [],
+        comments: Array.isArray(comments) ? comments : [],
+    };
+}
+/**
+ * Given PRs already listed for one repo, attach verdict payloads only for the
+ * CI-green ones that lack a formal APPROVED reviewDecision, then select.
+ */
+export async function selectListedMergeable(repo, listed, gh) {
+    const candidates = [];
+    for (const row of listed) {
+        if (!isCiGreen(row.statusCheckRollup))
+            continue;
+        const base = {
+            number: row.number,
+            repo,
+            reviewDecision: row.reviewDecision ?? '',
+            statusCheckRollup: row.statusCheckRollup,
+            reviews: [],
+            comments: [],
+        };
+        if (base.reviewDecision === 'APPROVED') {
+            candidates.push(base);
+            continue;
+        }
+        try {
+            const extra = await fetchVerdict(repo, row.number, gh);
+            candidates.push({ ...base, ...extra });
+        }
+        catch {
+            // A single PR's reviews/comments probe failed — skip it, keep the rest.
+            continue;
+        }
+    }
+    return candidates.filter((pr) => pr.reviewDecision === 'APPROVED' || hasApproveVerdict(pr.reviews, pr.comments));
+}
+/** List mergeable `owner/repo#n` refs, space-separated. Empty string if none. */
+export async function listMergeableRefs(opts) {
+    const gh = opts?.gh ?? ghExec;
+    const slugs = opts?.repos ?? projectRepoSlugs(opts?.defs ?? listProjectDefs());
+    const seen = new Set();
+    const refs = [];
+    for (const raw of slugs) {
+        const repo = await canonicalizeRepo(raw, gh);
+        if (seen.has(repo))
+            continue;
+        seen.add(repo);
+        let listed = [];
+        try {
+            const rawList = await gh([
+                'pr', 'list',
+                '--repo', repo,
+                '--author', '@me',
+                '--state', 'open',
+                '--limit', '50',
+                '--json', 'number,reviewDecision,statusCheckRollup',
+            ]);
+            const parsed = JSON.parse(rawList);
+            listed = Array.isArray(parsed) ? parsed : [];
+        }
+        catch {
+            continue;
+        }
+        const mergeable = await selectListedMergeable(repo, listed, gh);
+        for (const pr of mergeable)
+            refs.push(formatMergeableRef(pr));
+    }
+    return refs.join(' ');
+}

package/dist/lib/github/pr-verdict.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Non-author PR approval + CI-green checks for merge-on-green.
+ *
+ * Verdict rules are copied from merge-guard.sh (the PreToolUse hook in
+ * phnx-labs/.agents-system `rules/subrules/gh-merge-guard/merge-guard.sh`).
+ * That hook accepts EITHER a formal GitHub `APPROVED` review OR an APPROVE
+ * verdict comment on THIS PR, and rejects a comment that only cites another
+ * PR ("carried from #N" / "APPROVE on #N") — the #2736 laundering pattern.
+ *
+ * Do not invent a third rule. If the hook's regexes change, change these in
+ * the same delivery.
+ */
+/** A GitHub pull-request review, shaped after `GET .../pulls/{n}/reviews`. */
+export interface PrReview {
+    state?: string;
+}
+/** An issue comment on a PR, shaped after `GET .../issues/{n}/comments`. */
+export interface PrComment {
+    body?: string;
+}
+/**
+ * One status-check rollup item from `gh pr list --json statusCheckRollup`.
+ * `gh` exposes conclusion/state/status under those names; empty fields are
+ * pending/in-progress.
+ */
+export interface StatusCheck {
+    conclusion?: string;
+    state?: string;
+    status?: string;
+}
+/** One open PR with the fields the mergeable selector reads. */
+export interface MergeablePrInput {
+    number: number;
+    /** `owner/repo`. Required so a daemon with no git cwd can still merge. */
+    repo: string;
+    reviewDecision?: string | null;
+    statusCheckRollup?: StatusCheck[] | null;
+    reviews?: PrReview[] | null;
+    comments?: PrComment[] | null;
+}
+/**
+ * True when a non-author verdict exists ON this PR.
+ *
+ * Mirrors merge-guard.sh: a GitHub review with `state == "APPROVED"`, or an
+ * issue comment whose body contains `\bAPPROVE\b` and is not a carried-from
+ * citation (`\bcarried\s+(?:over\s+)?from\b` or `\bAPPROVE\s+(?:on|from)\s+#\d+`).
+ */
+export declare function hasApproveVerdict(reviews: readonly PrReview[] | null | undefined, comments: readonly PrComment[] | null | undefined): boolean;
+/**
+ * True when every check is a terminal success-class conclusion.
+ *
+ * Matches the built-in monitor's original jq: SUCCESS / NEUTRAL / SKIPPED
+ * (ascii-uppercased conclusion, else state, else status). An empty rollup
+ * is green — jq `all([])` is true, and a PR with no checks is mergeable
+ * from this filter's point of view.
+ */
+export declare function isCiGreen(rollup: readonly StatusCheck[] | null | undefined): boolean;
+/**
+ * Keep PRs that are CI-green AND non-author-approved.
+ *
+ * `reviewDecision == "APPROVED"` is sufficient (a formal review). When that
+ * field is empty — the fleet convention: reviewers post an APPROVE *comment*
+ * rather than a GitHub review — fall through to {@link hasApproveVerdict}.
+ */
+export declare function selectMergeablePrs(prs: readonly MergeablePrInput[]): MergeablePrInput[];
+/** `owner/repo#n` — the poll observation the merge action can parse without a cwd. */
+export declare function formatMergeableRef(pr: Pick<MergeablePrInput, 'repo' | 'number'>): string;

package/dist/lib/github/pr-verdict.js

@@ -0,0 +1,72 @@
+/**
+ * Non-author PR approval + CI-green checks for merge-on-green.
+ *
+ * Verdict rules are copied from merge-guard.sh (the PreToolUse hook in
+ * phnx-labs/.agents-system `rules/subrules/gh-merge-guard/merge-guard.sh`).
+ * That hook accepts EITHER a formal GitHub `APPROVED` review OR an APPROVE
+ * verdict comment on THIS PR, and rejects a comment that only cites another
+ * PR ("carried from #N" / "APPROVE on #N") — the #2736 laundering pattern.
+ *
+ * Do not invent a third rule. If the hook's regexes change, change these in
+ * the same delivery.
+ */
+/**
+ * True when a non-author verdict exists ON this PR.
+ *
+ * Mirrors merge-guard.sh: a GitHub review with `state == "APPROVED"`, or an
+ * issue comment whose body contains `\bAPPROVE\b` and is not a carried-from
+ * citation (`\bcarried\s+(?:over\s+)?from\b` or `\bAPPROVE\s+(?:on|from)\s+#\d+`).
+ */
+export function hasApproveVerdict(reviews, comments) {
+    if (Array.isArray(reviews) && reviews.some((r) => r?.state === 'APPROVED')) {
+        return true;
+    }
+    if (!Array.isArray(comments))
+        return false;
+    for (const c of comments) {
+        const body = c?.body ?? '';
+        if (!/\bAPPROVE\b/.test(body))
+            continue;
+        // A verdict that only points at another PR is laundering, not review.
+        if (/\bcarried\s+(?:over\s+)?from\b|\bAPPROVE\s+(?:on|from)\s+#\d+/.test(body)) {
+            continue;
+        }
+        return true;
+    }
+    return false;
+}
+/**
+ * True when every check is a terminal success-class conclusion.
+ *
+ * Matches the built-in monitor's original jq: SUCCESS / NEUTRAL / SKIPPED
+ * (ascii-uppercased conclusion, else state, else status). An empty rollup
+ * is green — jq `all([])` is true, and a PR with no checks is mergeable
+ * from this filter's point of view.
+ */
+export function isCiGreen(rollup) {
+    const items = rollup ?? [];
+    return items.every((c) => {
+        const v = (c.conclusion || c.state || c.status || '').toUpperCase();
+        return v === 'SUCCESS' || v === 'NEUTRAL' || v === 'SKIPPED';
+    });
+}
+/**
+ * Keep PRs that are CI-green AND non-author-approved.
+ *
+ * `reviewDecision == "APPROVED"` is sufficient (a formal review). When that
+ * field is empty — the fleet convention: reviewers post an APPROVE *comment*
+ * rather than a GitHub review — fall through to {@link hasApproveVerdict}.
+ */
+export function selectMergeablePrs(prs) {
+    return prs.filter((pr) => {
+        if (!isCiGreen(pr.statusCheckRollup))
+            return false;
+        if (pr.reviewDecision === 'APPROVED')
+            return true;
+        return hasApproveVerdict(pr.reviews, pr.comments);
+    });
+}
+/** `owner/repo#n` — the poll observation the merge action can parse without a cwd. */
+export function formatMergeableRef(pr) {
+    return `${pr.repo}#${pr.number}`;
+}

package/dist/lib/harness/adapter.d.ts

@@ -73,9 +73,10 @@ export interface ExecLaunchArgsCtx {
 }
 /**
  * Context for the routine (daemon-job) launch-arg quirks (mapping B, runner.ts
- * side). This idiom mutates a pre-baked token array from ROUTINE_AGENT_COMMANDS,
- * distinct from buildExecCommand's declarative modeFlags — so it is a separate
- * method on the same adapter, one source of truth per harness across both.
+ * side). This idiom mutates a token array baked from AGENT_COMMANDS
+ * (bakeRoutineArgv), distinct from buildExecCommand's declarative modeFlags —
+ * so it is a separate method on the same adapter, one source of truth per
+ * harness across both.
  */
 export interface RoutineLaunchCtx {
     /** normalizeMode(config.mode) — the canonicalized mode. */
@@ -131,8 +132,8 @@ export interface HarnessAdapter {
     execModeArgs?(ctx: ExecLaunchArgsCtx): string[] | undefined;
     /**
      * This harness's routine (daemon-job) launch-arg quirks for buildJobCommand
-     * (runner.ts). Mutates the ROUTINE_AGENT_COMMANDS token array in place, exactly
-     * as the old per-agent arm did; runner appends model/reasoning flags after.
+     * (runner.ts). Mutates the bakeRoutineArgv token array in place, exactly as
+     * the old per-agent arm did; runner appends model/reasoning flags after.
      * Omitted for a harness with no routine launch quirks.
      */
     routineModeArgs?(cmd: string[], ctx: RoutineLaunchCtx): void;

package/dist/lib/hosts/dispatch.d.ts

@@ -168,6 +168,8 @@ export interface InteractiveDispatchOptions {
     agent: string;
     /** Explicit agent version pin (e.g. "2.1.207") to forward as `agent@version`. */
     version?: string;
+    /** Preserve the trailing-@ account picker so selection happens on the execution host. */
+    accountPicker?: boolean;
     /** Explicit run strategy (e.g. "balanced") to forward as `--strategy <strategy>`. */
     strategy?: string;
     /** Named provider account to resolve on the remote host. */

package/dist/lib/hosts/dispatch.js

@@ -417,7 +417,14 @@ export function buildRunForwardedArgs(opts) {
  * infer headless from the prompt).
  */
 export function buildInteractiveRunForwardedArgs(opts) {
-    const agentArg = opts.version ? `${opts.agent}@${opts.version}` : opts.agent;
+    if (opts.version && opts.accountPicker) {
+        throw new Error('Interactive host dispatch cannot combine an account picker with a version pin');
+    }
+    const agentArg = opts.accountPicker
+        ? `${opts.agent}@`
+        : opts.version
+            ? `${opts.agent}@${opts.version}`
+            : opts.agent;
     const args = ['run', agentArg];
     if (opts.prompt && opts.forceInteractive)
         args.push(opts.prompt);

package/dist/lib/hosts/passthrough.d.ts

@@ -48,6 +48,16 @@ export declare const REMOTE_PASSTHROUGH: Record<string, RemoteSpec>;
  * these to {@link REMOTE_PASSTHROUGH}.
  */
 export declare const OWN_HOST_COMMANDS: Set<string>;
+/**
+ * Argv forwarded over SSH for a `--device` passthrough.
+ *
+ * `sync`'s umbrella spec appends `--yes` when there is no TTY so a remote
+ * reconcile does not hang on a picker. `sync status` is inspect-only unless the
+ * caller typed `--yes` themselves: `--yes` on that command is reconcile, not
+ * "don't prompt". Nesting it under `sync` must not inherit the umbrella flag
+ * (RUSH-2864).
+ */
+export declare function buildPassthroughForwardedArgs(command: string, allArgs: string[], interactive: boolean): string[];
 /** Injectable dependencies for {@link runFleetPassthrough} — used by tests. */
 export interface FleetPassthroughOptions {
     /** Override the device registry loader (tests). */

package/dist/lib/hosts/passthrough.js

@@ -52,11 +52,10 @@ export { flagValue, hasHostRoutingFlag } from './routing-flag.js';
  * `add`/`use`/`list`, and none) and were removed.
  */
 export const REMOTE_PASSTHROUGH = {
-    // status / inspect
+    // inspect
     view: {},
     inspect: {},
     doctor: {},
-    status: {},
     check: {},
     list: {},
     usage: {},
@@ -81,7 +80,6 @@ export const REMOTE_PASSTHROUGH = {
     workflows: {},
     models: {},
     defaults: {},
-    alias: {},
     // Installations are per-machine, so updating one on a peer means running it
     // there — the same local/remote shape `add` would need.
     update: {},
@@ -97,7 +95,6 @@ export const REMOTE_PASSTHROUGH = {
     restore: {},
     worktree: {},
     events: {},
-    audit: {},
     feedback: {},
     pty: {},
     tmux: {},
@@ -137,6 +134,32 @@ const STRIP_SPECS = [
     { long: 'hosts', takesValue: true },
     { long: 'devices', takesValue: true },
 ];
+/** First non-flag token after `group` in argv (the subcommand, robust to leading flags). */
+function firstSubcommand(allArgs, group) {
+    const idx = allArgs.indexOf(group);
+    return idx >= 0 ? allArgs.slice(idx + 1).find((a) => !a.startsWith('-')) : undefined;
+}
+/**
+ * Argv forwarded over SSH for a `--device` passthrough.
+ *
+ * `sync`'s umbrella spec appends `--yes` when there is no TTY so a remote
+ * reconcile does not hang on a picker. `sync status` is inspect-only unless the
+ * caller typed `--yes` themselves: `--yes` on that command is reconcile, not
+ * "don't prompt". Nesting it under `sync` must not inherit the umbrella flag
+ * (RUSH-2864).
+ */
+export function buildPassthroughForwardedArgs(command, allArgs, interactive) {
+    const spec = REMOTE_PASSTHROUGH[command];
+    let forwarded = stripRoutingFlags(allArgs, STRIP_SPECS);
+    // Detect the subcommand on the *stripped* argv. On the raw argv,
+    // `sync --device peer status` would treat `peer` as the first non-flag
+    // token and inherit umbrella `--yes` (RUSH-2864 review).
+    const skipInheritedYes = command === 'sync' && firstSubcommand(forwarded, 'sync') === 'status';
+    if (!interactive && spec?.nonInteractive && !skipInheritedYes) {
+        forwarded = [...forwarded, ...spec.nonInteractive];
+    }
+    return forwarded;
+}
 /** Synthesize a `Host` for a raw `user@host` / bare-alias target (not enrolled). */
 function syntheticHost(target) {
     const at = target.indexOf('@');
@@ -531,9 +554,7 @@ export async function maybeRunOnHost(command, allArgs, opts) {
     // out — otherwise force the command's non-interactive path so no half-drawn
     // picker is piped into a file or another program.
     const interactive = !!process.stdout.isTTY && !allArgs.includes('--no-tty');
-    let forwarded = stripRoutingFlags(allArgs, STRIP_SPECS);
-    if (!interactive && spec.nonInteractive)
-        forwarded = [...forwarded, ...spec.nonInteractive];
+    const forwarded = buildPassthroughForwardedArgs(command, allArgs, interactive);
     // The one long-running case: keep the remote team supervisor alive past a
     // disconnect by dispatching it detached (nohup), still streaming live.
     const isWatchedTeamStart = command === 'teams' && forwarded[1] === 'start' && forwarded.includes('--watch');

package/dist/lib/hosts/providers/devices.js

@@ -17,7 +17,7 @@
  * enrolled host shadows a same-name device in both list dedup and resolve
  * order, exactly like the old tier-2 devices fall-through in resolveHost.
  */
-import { loadDevices, getDevice, isControlDevice } from '../../devices/registry.js';
+import { loadDevices, getDevice } from '../../devices/registry.js';
 import { resolveDeviceProfile } from '../../devices/resolve-profile.js';
 import { DeviceOffloadUnsupportedError } from '../types.js';
 /** Tailscale's own presence bit, when the sync captured one. */
@@ -34,12 +34,6 @@ function statusOf(device) {
  * precedence, carrying the caps.
  */
 function deviceToPoolHost(rawDevice) {
-    // A control device (a cockpit, e.g. a paired iPhone) drives the fleet but
-    // never runs agents — it must never enter the host pool or be resolvable as a
-    // dispatch target, whatever platform it reports (an iPhone syncs as `unknown`,
-    // which remoteShellFor would otherwise default to POSIX and try to SSH).
-    if (isControlDevice(rawDevice))
-        return null;
     // Effective profile: central config (ssh.*/platform) overlays discovery.
     const device = resolveDeviceProfile(rawDevice);
     const address = device.address.dnsName ?? device.address.ip;
@@ -78,12 +72,6 @@ export class DevicesHostProvider {
         const raw = await getDevice(name);
         if (!raw)
             return null;
-        // Resolving is asking to dispatch. A control device can't run agents — fail
-        // loud with a clear message instead of attempting an SSH dispatch onto a
-        // phone (which remoteShellFor would treat as a POSIX host).
-        if (isControlDevice(raw)) {
-            throw new Error(`Device "${raw.name}" is a control device (a cockpit), not an executor — it can't run agents. Dispatch to a worker device instead.`);
-        }
         // Effective profile: central config (ssh.*/platform) overlays discovery —
         // the password-auth refusal and the dial shape both follow the config.
         const device = resolveDeviceProfile(raw);

package/dist/lib/hosts/ready.d.ts

@@ -88,11 +88,20 @@ export declare function viewAgentVersions(view: string, agent: string): string[]
 export declare function viewHasAgentVersion(view: string, agent: string, version: string): boolean | undefined;
 /** Actionable fail-loud message for a missing remote pin (RUSH-2313). */
 export declare function missingPinnedVersionMessage(hostName: string, agent: string, version: string, installed?: string[]): string;
+/** Account eligibility extracted from one device's `agents view --json`. */
+export interface ViewAgentAccountEligibility {
+    /** At least one account can launch immediately. */
+    signedIn: boolean | undefined;
+    /** At least one account can launch immediately or enter the harness login flow. */
+    pickerEligible: boolean | undefined;
+}
 /**
- * Read whether the requested harness has at least one launch-eligible account
- * from `agents view --json`. Signed-in accounts that are rate-limited or out of
- * credits are deliberately false so automatic placement cannot select them.
+ * Read the two account gates automatic placement needs from `agents view
+ * --json`. A picker may route to a signed-out version because launching it is
+ * the login flow, but it must not route to a device whose every signed-in
+ * account is throttled.
  */
+export declare function viewAgentAccountEligibility(view: string, agent: string): ViewAgentAccountEligibility;
 export declare function viewAgentSignedIn(view: string, agent: string): boolean | undefined;
 export interface EnsureReadyOptions {
     agent: string;

package/dist/lib/hosts/ready.js

@@ -12,6 +12,7 @@ import { sshExec, shellQuote } from '../ssh-exec.js';
 import { hostIdentityArgs, sshTargetFor } from './types.js';
 import { remoteShellFor, buildWindowsAgentsCommand, encodePowershell, powershellQuote, POWERSHELL_PROGRESS_SILENCE } from './remote-cmd.js';
 import { resolveRemoteOsSync } from './remote-os.js';
+import { isDeadVerdict } from '../auth-health.js';
 /** Resolve this CLI's own version by walking up to the nearest package.json. */
 export function localCliVersion() {
     let dir = path.dirname(fileURLToPath(import.meta.url));
@@ -208,27 +209,41 @@ export function missingPinnedVersionMessage(hostName, agent, version, installed)
         `Install it on that box: agents ssh ${hostName} -- agents add ${agent}@${version}`);
 }
 /**
- * Read whether the requested harness has at least one launch-eligible account
- * from `agents view --json`. Signed-in accounts that are rate-limited or out of
- * credits are deliberately false so automatic placement cannot select them.
+ * Read the two account gates automatic placement needs from `agents view
+ * --json`. A picker may route to a signed-out version because launching it is
+ * the login flow, but it must not route to a device whose every signed-in
+ * account is throttled.
  */
-export function viewAgentSignedIn(view, agent) {
+export function viewAgentAccountEligibility(view, agent) {
     try {
         const rows = JSON.parse(view);
         const row = rows.find((candidate) => candidate.agent?.toLowerCase() === agent.toLowerCase());
         if (!row)
-            return undefined;
-        const verdicts = (row.versions ?? [])
-            .map((version) => typeof version.signedIn === 'boolean'
-            ? version.signedIn && version.usageStatus !== 'rate_limited' && version.usageStatus !== 'out_of_credits'
-            : undefined)
-            .filter((value) => typeof value === 'boolean');
-        return verdicts.length === 0 ? undefined : verdicts.some(Boolean);
+            return { signedIn: undefined, pickerEligible: undefined };
+        const verdicts = (row.versions ?? []).flatMap((version) => {
+            if (typeof version.signedIn !== 'boolean')
+                return [];
+            const throttled = version.usageStatus === 'rate_limited' || version.usageStatus === 'out_of_credits';
+            const authBlocked = version.authVerdict !== null
+                && version.authVerdict !== undefined
+                && isDeadVerdict(version.authVerdict);
+            const ready = version.signedIn && !authBlocked && !throttled;
+            return [{ ready, pickerEligible: ready || !version.signedIn || authBlocked }];
+        });
+        if (verdicts.length === 0)
+            return { signedIn: undefined, pickerEligible: undefined };
+        return {
+            signedIn: verdicts.some((verdict) => verdict.ready),
+            pickerEligible: verdicts.some((verdict) => verdict.pickerEligible),
+        };
     }
     catch {
-        return undefined;
+        return { signedIn: undefined, pickerEligible: undefined };
     }
 }
+export function viewAgentSignedIn(view, agent) {
+    return viewAgentAccountEligibility(view, agent).signedIn;
+}
 /**
  * Pure readiness verdict for the agent/version half of {@link ensureHostReady}
  * (unit-tested without SSH). Returns warnings for soft agent-missing cases, or

package/dist/lib/hosts/registry.d.ts

@@ -27,8 +27,8 @@ export declare function getAllProviders(): HostProvider[];
  * A resolved host, carrying the live {@link DeviceProfile} when the token
  * matched a registered device (by normalized name). The device reference lets
  * the `agents ssh` wrapper reach auth/shell/tailscale metadata a plain `Host`
- * doesn't hold, and lets dispatch callers apply the device-only refusals
- * (control device, password auth) without re-reading the registry.
+ * doesn't hold, and lets dispatch callers apply the device-only refusal
+ * (password auth) without re-reading the registry.
  */
 export interface ResolvedHost extends Host {
     device?: DeviceProfile;
@@ -65,7 +65,7 @@ export interface MatchHostOptions {
  * all resolve the same way regardless of which subcommand called.
  *
  * Non-throwing: returns null on an injection-guard failure or an unresolved bare
- * token. Device-only refusals (control device, password auth) are NOT applied
+ * token. The device-only refusal (password auth) is NOT applied
  * here — that is the dispatch wrapper's job ({@link resolveHost}), so the fan-out
  * and `agents ssh` paths, which handle those cases differently, aren't forced
  * into a dispatch verdict.
@@ -81,8 +81,7 @@ export declare function listAllHosts(): Promise<Host[]>;
  * caller consumes (`run --device`, the generic passthrough, teams placement, the
  * cloud host provider, doctor, funnel, remote secrets). Grammar and merge come
  * from {@link matchHost}; on top, this layer applies the device-only dispatch
- * refusals so they hold even when an inline overlay shadows the device:
- *   - a control device (a paired iPhone) can never be a dispatch target;
+ * refusal so it holds even when an inline overlay shadows the device:
  *   - a password-auth device throws the typed {@link DeviceOffloadUnsupportedError}
  *     (offload rides `BatchMode=yes` ssh, which can't answer a prompt);
  *   - an addressless device has nothing to dial.