@phnx-labs/agents-cli 1.22.106 → 1.22.107

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 1.22.107
+
+- **A bare interactive run places itself like `--device auto` (PHNX-4083).**
+  `agents run <harness>` with no prompt on a real TTY (no `--json`) now
+  auto-places onto a fleet worker — the same engine, pool, and banner as
+  `--device auto` — instead of always running on the machine you typed it at;
+  headless runs (any prompt, `--json`, teams/routines/hooks) are unchanged and
+  still run in place. To keep a local interactive run, pass
+  `--device <this machine>` or pick this machine (listed first) in the
+  `<harness>@` device picker; when placement finds no healthy device (empty
+  pool, or the PHNX-4051 stale-usage refusal) the run fails loud with the
+  placement error plus `Run here instead: agents run <harness> --device
+  <this machine>` — never a silent local fallback. Source:
+  `src/commands/exec.ts`, `src/commands/run-account-picker.ts`.
+
+- **Run pickers move to `#` (account) and `@` (device), `#@` asks both
+  (PHNX-4083).** `agents run claude#` now opens the account picker (the old
+  `claude@` menu, same rows and code path); `agents run claude@` opens the new
+  fleet device picker — this machine first, offline rows disabled, cached-state
+  age in the prompt — and `claude#@` asks the account first, then the device,
+  dispatching with the picked account label. A picker combined with an explicit
+  pin of the same thing (`claude@2.1.218#`, `claude#work#`, `claude@@`) or a
+  conflicting flag (`--account`, `--device`/`--on`/`--computer`/`--host`) fails
+  loud; a cancelled menu launches nothing. Source: `src/commands/exec.ts`,
+  `src/lib/hosts/dispatch.ts`.
+
 ## 1.22.106
 
 - Fixed release packages omitting the session-tracking hook. Release qualification now uses the complete CLI build, so installed agents can record the account that owns each native session.

package/README.md

@@ -202,11 +202,15 @@ agents run claude "refactor auth module" --mode edit --fallback codex,antigravit
 # Picks the signed-in account you haven't used recently.
 agents run claude "summarize recent commits" --strategy balanced
 
-# Or choose one account/version interactively for only this run.
-agents run claude@
-agents run codex@ "review this branch"
-agents run claude@ --device auto        # pick the device, then choose there
-agents run claude@ --device yosemite-s0 # choose from one device's accounts
+# Or choose one account/version interactively for only this run (# = account picker).
+agents run claude#
+agents run codex# "review this branch"
+agents run claude# --device auto        # pick the device, then choose there
+agents run claude# --device yosemite-s0 # choose from one device's accounts
+
+# @ picks the device instead; #@ asks both (account first, then device).
+agents run claude@                      # pick the device for this run
+agents run claude#@                     # pick the account, then the device
 ```
 
 `--strategy balanced` spreads work across available versions of the same agent -- useful when you have multiple accounts and want to avoid burning through one. When a Claude run reports a session limit, agents-cli records the stated reset time, shows `session-limited` in `agents view`, and excludes that account until the reset. When every account is rate-limited, the run exits nonzero naming each excluded account and the earliest window reset (use `--strategy pinned` to force a rate-limited default) -- it never launches into an exhausted account. A logged-out default is never forced: unpinned dispatch picks a signed-in version on the execution device instead of dying on a credential-less default home.

package/dist/commands/exec.d.ts

@@ -10,13 +10,24 @@ import type { ExecEffort } from '../lib/exec.js';
 import { RUN_AUTO_KEYWORD } from '../lib/types.js';
 /** Validate a caller-supplied session id before it reaches tmux, paths, indexes, or remote dispatch. */
 export declare function parseExplicitSessionId(value: string): string;
-export interface RunAccountPickerRequest {
-    requested: boolean;
+export interface RunPickerMarkers {
+    accountPicker: boolean;
+    devicePicker: boolean;
     normalizedAgentSpec: string;
     valid: boolean;
+    reason?: string;
 }
-/** Distinguish a terminal account-picker marker from an explicit @version pin. */
-export declare function parseRunAccountPickerRequest(agentSpec: string): RunAccountPickerRequest;
+/**
+ * Parse the trailing picker markers on an `agents run` agent spec. A terminal
+ * run of `#`/`@` characters requests the account picker (`#`) and/or the
+ * device picker (`@`) — each at most once, in either order (`claude#@`,
+ * `claude@#`). Stripping them yields the normalized spec (`claude#work@` →
+ * `claude#work`, version pins and `#label` account pins intact). A picker
+ * cannot combine with an explicit pin of what it picks: `claude@2.1.218#`
+ * (the account picker already chooses the version — the old `claude@2.1.218@`
+ * rule), `claude#work#`, `claude@@`.
+ */
+export declare function parseRunPickerMarkers(agentSpec: string): RunPickerMarkers;
 /**
  * The `--device` alias family — the flags that mean "dispatch this run to another
  * machine over SSH". `--device` is canonical; `--on`/`--computer` are hidden
@@ -31,11 +42,29 @@ export declare function hostTargetGiven(options: {
     on?: string;
     computer?: string;
 }): string[];
-/** Return every option whose selection semantics conflict with an account choice. */
+/**
+ * Return every option whose selection semantics conflict with an account
+ * choice (`agent#`). Device routing is deliberately absent: the marker rides
+ * the hop and the peer picks from ITS slots.
+ */
 export declare function runAccountPickerConflicts(options: {
     resume?: string | boolean;
     strategy?: string;
     balanced?: boolean;
+    lease?: string | boolean;
+    box?: string;
+    account?: string;
+    host?: string;
+    device?: string;
+    on?: string;
+    computer?: string;
+}): string[];
+/**
+ * Return every option that already decides where the run lands, so a device
+ * choice (`agent@`) would be silently ignored: any explicit host flag, and the
+ * lease/box paths, which own placement outright.
+ */
+export declare function runDevicePickerConflicts(options: {
     lease?: string | boolean;
     box?: string;
     host?: string;
@@ -47,11 +76,15 @@ export { RUN_AUTO_KEYWORD };
 /**
  * Whether `run auto` should default its host layer to the affinity pick (the
  * same machinery as `--device auto`). False when the caller pinned any host
- * flag, and false when this process was itself dispatched by a host run — the
- * dispatcher exports AGENTS_RUN_AUTO_HOST_RESOLVED=1 into the remote SHELL
+ * flag, and false when this process was itself dispatched by a host run —
+ * the dispatcher exports AGENTS_RUN_AUTO_HOST_RESOLVED=1 into the remote SHELL
  * (hosts/dispatch.ts remoteRunShellPrelude) because it already resolved the
  * host layer, and re-picking here would chain-hop the run across the fleet.
- * Pure so the pinning matrix is unit-testable.
+ * An INTERACTIVE dispatch of a named harness also reaches the remote as a bare
+ * `agents run <harness>` (its argv forwards without the routing flag), so the
+ * interactive prelude's AGENTS_REMOTE_INTERACTIVE=1 counts as "already placed"
+ * too — without it the remote would re-place the run and ping-pong across the
+ * fleet. Pure so the pinning matrix is unit-testable.
  */
 export declare function runAutoDefaultsToAffinity(options: {
     host?: string;
@@ -59,6 +92,43 @@ export declare function runAutoDefaultsToAffinity(options: {
     on?: string;
     computer?: string;
 }, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Whether a bare human-facing `agents run <harness>` — no prompt, so an
+ * interactive TUI run — defaults its placement to `--device auto` (PHNX-4083).
+ * A marker left off is decided for you: no `#` means balanced rotation, and no
+ * `@` (and no other placement flag) now means automatic device placement — the
+ * same engine as `--device auto`, whose pool never contains a box marked
+ * `personal`. ALL of these must hold:
+ *
+ * - no prompt (headless runs — teams, routines, hooks, `run <agent> "…"` —
+ *   keep running in place, unchanged);
+ * - a human-facing surface: a real TTY and no `--json`. This is the same
+ *   two-condition gate `signInLaunchDecision` uses in run-account-picker.ts —
+ *   reused here through isHumanFacingRun, not re-derived;
+ * - no device-picker marker (`agent@` already chose the device; picking this
+ *   machine there is a plain local run);
+ * - no `--resume` / `--lease` / `--box` / `--cloud` (those own placement);
+ * - the host layer is unpinned and this process is not itself a dispatched
+ *   hop — delegated to runAutoDefaultsToAffinity, which encodes both.
+ *
+ * Pure so the default-placement matrix is unit-testable.
+ */
+export declare function bareInteractiveRunDefaultsToDeviceAuto(options: {
+    host?: string;
+    device?: string;
+    on?: string;
+    computer?: string;
+    resume?: string | boolean;
+    lease?: string | boolean;
+    box?: string;
+    cloud?: boolean;
+}, run: {
+    prompt?: string;
+    devicePickerRequested?: boolean;
+}, surface: {
+    tty: boolean;
+    json?: boolean;
+}, env?: NodeJS.ProcessEnv): boolean;
 /**
  * Whether an interactive host dispatch must mint a correlation launch id and
  * resolve the remote session via the launch-id join (RUSH-2034), rather than

package/dist/commands/exec.js

@@ -11,6 +11,7 @@ import { isTierToken } from '../lib/model-tiers.js';
 import { RUN_AUTO_KEYWORD } from '../lib/types.js';
 import { setHelpSections } from '../lib/help.js';
 import { isInteractiveTerminal, isPromptCancelled, requireInteractiveSelection } from './utils.js';
+import { isHumanFacingRun } from './run-account-picker.js';
 import { getUserAgentsDir, readMeta } from '../lib/state.js';
 import { parseLoopInterval } from '../lib/loop.js';
 import { AGENTS, resolveAgentName, isAgentHardDeprecated, hardDeprecationError } from '../lib/agents.js';
@@ -36,15 +37,47 @@ export function parseExplicitSessionId(value) {
     }
     return value;
 }
-/** Distinguish a terminal account-picker marker from an explicit @version pin. */
-export function parseRunAccountPickerRequest(agentSpec) {
-    const requested = agentSpec.endsWith('@');
-    const normalizedAgentSpec = requested ? agentSpec.slice(0, -1) : agentSpec;
-    return {
-        requested,
-        normalizedAgentSpec,
-        valid: !requested || (!!normalizedAgentSpec && !normalizedAgentSpec.includes('@')),
-    };
+/**
+ * Parse the trailing picker markers on an `agents run` agent spec. A terminal
+ * run of `#`/`@` characters requests the account picker (`#`) and/or the
+ * device picker (`@`) — each at most once, in either order (`claude#@`,
+ * `claude@#`). Stripping them yields the normalized spec (`claude#work@` →
+ * `claude#work`, version pins and `#label` account pins intact). A picker
+ * cannot combine with an explicit pin of what it picks: `claude@2.1.218#`
+ * (the account picker already chooses the version — the old `claude@2.1.218@`
+ * rule), `claude#work#`, `claude@@`.
+ */
+export function parseRunPickerMarkers(agentSpec) {
+    let rest = agentSpec;
+    let accountPicker = false;
+    let devicePicker = false;
+    let reason;
+    while (rest.endsWith('#') || rest.endsWith('@')) {
+        const marker = rest.endsWith('#') ? '#' : '@';
+        if (marker === '#') {
+            if (accountPicker && reason === undefined)
+                reason = `the # picker marker may appear at most once in '${agentSpec}'`;
+            accountPicker = true;
+        }
+        else {
+            if (devicePicker && reason === undefined)
+                reason = `the @ picker marker may appear at most once in '${agentSpec}'`;
+            devicePicker = true;
+        }
+        rest = rest.slice(0, -1);
+    }
+    if (reason === undefined) {
+        if (!rest) {
+            reason = `'${agentSpec}' names no agent before the picker markers`;
+        }
+        else if (accountPicker && (rest.includes('@') || rest.includes('#'))) {
+            reason = `an explicit pin in '${rest}' already selects what the # account picker chooses`;
+        }
+        else if (devicePicker && rest.includes('@')) {
+            reason = `an explicit pin in '${rest}' cannot combine with the @ device picker`;
+        }
+    }
+    return { accountPicker, devicePicker, normalizedAgentSpec: rest, valid: reason === undefined, reason };
 }
 /**
  * The `--device` alias family — the flags that mean "dispatch this run to another
@@ -57,7 +90,11 @@ export function parseRunAccountPickerRequest(agentSpec) {
 export function hostTargetGiven(options) {
     return [options.host, options.device, options.on, options.computer].filter((v) => !!v);
 }
-/** Return every option whose selection semantics conflict with an account choice. */
+/**
+ * Return every option whose selection semantics conflict with an account
+ * choice (`agent#`). Device routing is deliberately absent: the marker rides
+ * the hop and the peer picks from ITS slots.
+ */
 export function runAccountPickerConflicts(options) {
     const conflicts = [];
     if (options.resume !== undefined)
@@ -66,6 +103,21 @@ export function runAccountPickerConflicts(options) {
         conflicts.push('--strategy');
     if (options.balanced)
         conflicts.push('--balanced');
+    if (options.lease)
+        conflicts.push('--lease');
+    if (options.box)
+        conflicts.push('--box');
+    if (options.account)
+        conflicts.push(`--account ${options.account}`);
+    return conflicts;
+}
+/**
+ * Return every option that already decides where the run lands, so a device
+ * choice (`agent@`) would be silently ignored: any explicit host flag, and the
+ * lease/box paths, which own placement outright.
+ */
+export function runDevicePickerConflicts(options) {
+    const conflicts = hostTargetGiven(options).map((h) => `--device ${h}`);
     if (options.lease)
         conflicts.push('--lease');
     if (options.box)
@@ -82,16 +134,54 @@ export { RUN_AUTO_KEYWORD };
 /**
  * Whether `run auto` should default its host layer to the affinity pick (the
  * same machinery as `--device auto`). False when the caller pinned any host
- * flag, and false when this process was itself dispatched by a host run — the
- * dispatcher exports AGENTS_RUN_AUTO_HOST_RESOLVED=1 into the remote SHELL
+ * flag, and false when this process was itself dispatched by a host run —
+ * the dispatcher exports AGENTS_RUN_AUTO_HOST_RESOLVED=1 into the remote SHELL
  * (hosts/dispatch.ts remoteRunShellPrelude) because it already resolved the
  * host layer, and re-picking here would chain-hop the run across the fleet.
- * Pure so the pinning matrix is unit-testable.
+ * An INTERACTIVE dispatch of a named harness also reaches the remote as a bare
+ * `agents run <harness>` (its argv forwards without the routing flag), so the
+ * interactive prelude's AGENTS_REMOTE_INTERACTIVE=1 counts as "already placed"
+ * too — without it the remote would re-place the run and ping-pong across the
+ * fleet. Pure so the pinning matrix is unit-testable.
  */
 export function runAutoDefaultsToAffinity(options, env = process.env) {
     if (hostTargetGiven(options).length > 0)
         return false;
-    return env.AGENTS_RUN_AUTO_HOST_RESOLVED !== '1';
+    if (env.AGENTS_RUN_AUTO_HOST_RESOLVED === '1')
+        return false;
+    return env.AGENTS_REMOTE_INTERACTIVE !== '1';
+}
+/**
+ * Whether a bare human-facing `agents run <harness>` — no prompt, so an
+ * interactive TUI run — defaults its placement to `--device auto` (PHNX-4083).
+ * A marker left off is decided for you: no `#` means balanced rotation, and no
+ * `@` (and no other placement flag) now means automatic device placement — the
+ * same engine as `--device auto`, whose pool never contains a box marked
+ * `personal`. ALL of these must hold:
+ *
+ * - no prompt (headless runs — teams, routines, hooks, `run <agent> "…"` —
+ *   keep running in place, unchanged);
+ * - a human-facing surface: a real TTY and no `--json`. This is the same
+ *   two-condition gate `signInLaunchDecision` uses in run-account-picker.ts —
+ *   reused here through isHumanFacingRun, not re-derived;
+ * - no device-picker marker (`agent@` already chose the device; picking this
+ *   machine there is a plain local run);
+ * - no `--resume` / `--lease` / `--box` / `--cloud` (those own placement);
+ * - the host layer is unpinned and this process is not itself a dispatched
+ *   hop — delegated to runAutoDefaultsToAffinity, which encodes both.
+ *
+ * Pure so the default-placement matrix is unit-testable.
+ */
+export function bareInteractiveRunDefaultsToDeviceAuto(options, run, surface, env = process.env) {
+    if (run.prompt !== undefined)
+        return false;
+    if (!isHumanFacingRun({ tty: surface.tty, json: surface.json === true }))
+        return false;
+    if (run.devicePickerRequested)
+        return false;
+    if (options.resume !== undefined || options.lease || options.box || options.cloud)
+        return false;
+    return runAutoDefaultsToAffinity(options, env);
 }
 /**
  * Whether an interactive host dispatch must mint a correlation launch id and
@@ -426,7 +516,7 @@ async function handleTerminalHandoff(agentSpec, options, prompt) {
     // isValidAgent / profileExists / resolveWorkflowRef chain below), so this must
     // accept all three. Gating on the agent table alone rejected every profile —
     // the whole Kimi/DeepSeek/Qwen/GLM path — for `--terminal` runs only.
-    const rawTarget = parseRunAccountPickerRequest(agentSpec).normalizedAgentSpec.split('#')[0].split('@')[0];
+    const rawTarget = parseRunPickerMarkers(agentSpec).normalizedAgentSpec.split('#')[0].split('@')[0];
     const knownAgent = resolveAgentName(rawTarget);
     const [{ profileExists }, { resolveWorkflowRef }] = await Promise.all([
         import('../lib/profiles.js'),
@@ -587,12 +677,22 @@ export function registerRunCommand(program) {
       # Headless, can edit: have the agent make changes
       agents run claude "fix lint errors in src/" --mode edit
 
-      # Interactive (TUI) with the pinned default version
+      # Interactive (TUI): a bare run places itself like --device auto (a fleet
+      # worker, TUI forwarded over SSH); pin the device to stay on this machine
       agents run claude
+      agents run claude --device zion      # stay local (or pick this machine in claude@)
+
+      # Pick a signed-in account/version for only this run (# = account picker)
+      agents run claude#
 
-      # Pick a signed-in account/version for only this run
+      # Pick the device this run lands on (@ = device picker); this machine
+      # first, offline rows disabled, fleet state aged in the prompt
       agents run claude@
 
+      # Ask both, account first, then device — the run dispatches with the
+      # picked account to the picked device
+      agents run claude#@
+
       # Full-auto: affinity-pick the host, then the harness with the most
       # account headroom, then a balanced account on it
       agents run auto "fix the flaky test" --mode edit
@@ -677,9 +777,21 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
       best-account headroom), and the account (the strategy above). Zero
       healthy accounts on any harness exits nonzero with the earliest reset.
 
-      Account picker: append @ with no version (agents run claude@) to choose one
-        installed account for this run. Rows show identity, login state, plan,
-        and available limits; unsafe accounts stay visible but disabled.
+      Pickers: a trailing # opens the account picker (agents run claude#) to
+        choose one installed account for this run — rows show identity, login
+        state, plan, and available limits; unsafe accounts stay visible but
+        disabled. A trailing @ opens the device picker (agents run claude@);
+        #@ asks both, account first, then device. The pickers cannot combine
+        with an explicit pin of the same thing (--account, --device/--on/
+        --computer/--host) or with --strategy/--balanced/--resume/--lease/--box.
+
+      Interactive placement: a bare 'agents run <harness>' (no prompt, real TTY)
+        places itself like --device auto — a fleet worker runs it, with the TUI
+        forwarded over SSH. Headless runs (any prompt, --json, no TTY) are
+        unchanged: they run in place. To stay on this machine, pass
+        --device <this machine>, or pick this machine (listed first) in the
+        '<harness>@' device picker. When placement finds no healthy device the
+        run fails loud and names the local spellings.
 
       Fallback: --fallback codex,antigravity retries on rate-limit failure via /continue handoff. Each entry accepts @version.
 
@@ -834,19 +946,25 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 host: options.host,
             });
         }
-        // A trailing @ is an explicit request to choose one installed account.
-        // Strip only that terminal marker; concrete agent@version pins retain
-        // their existing meaning in every dispatch path below.
-        const accountPicker = parseRunAccountPickerRequest(agentSpec);
-        const accountPickerRequested = accountPicker.requested;
-        let normalizedAgentSpec = accountPicker.normalizedAgentSpec;
-        if (!accountPicker.valid) {
-            console.error(chalk.red(`Invalid account picker target: ${agentSpec}. Use agents run <agent>@.`));
+        // Trailing picker markers request an interactive choice: `#` picks the
+        // account (and the version it signs in with), `@` picks the device, and
+        // `#@`/`@#` ask both. Strip only those terminal markers; concrete
+        // agent@version pins and `#label` account pins retain their meaning in
+        // every dispatch path below.
+        const pickerMarkers = parseRunPickerMarkers(agentSpec);
+        const accountPickerRequested = pickerMarkers.accountPicker;
+        const devicePickerRequested = pickerMarkers.devicePicker;
+        let normalizedAgentSpec = pickerMarkers.normalizedAgentSpec;
+        if (!pickerMarkers.valid) {
+            console.error(chalk.red(`Invalid run picker target: ${agentSpec}. ` +
+                `${pickerMarkers.reason ?? 'unrecognized picker markers'}. ` +
+                'Use agents run <agent># to pick an account, <agent>@ to pick a device, <agent>#@ for both.'));
             process.exit(1);
         }
         // Peel `#name` off before --device dispatch so the selector rides the hop
         // unchanged and the peer resolves ITS slot (PHNX-3940 T5). The later local
-        // parse is idempotent when the values match.
+        // parse is idempotent when the values match. A bare trailing `#` was the
+        // picker marker above, so it can never land here as an empty label.
         {
             const labelParts = normalizedAgentSpec.split('#');
             if (labelParts.length > 2 || labelParts[1] === '') {
@@ -890,14 +1008,22 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             console.error(chalk.red(hardDeprecationError(runBaseAgentId)));
             process.exit(1);
         }
-        // Account-picker conflict check runs BEFORE device=auto may set balanced,
-        // so an implicit balanced preference never surfaces as a fake
-        // "cannot be combined with --balanced" when the user only typed trailing @.
+        // Picker conflict checks run BEFORE --resume/--device auto may place the
+        // run implicitly, so an implied placement never surfaces as a fake
+        // "cannot be combined with --device" when the user only typed a marker.
         if (accountPickerRequested) {
             const conflicts = runAccountPickerConflicts(options);
             if (conflicts.length > 0) {
                 console.error(chalk.red(`Account selection with ${agentSpec} cannot be combined with ${conflicts.join(', ')}. ` +
-                    'Remove the conflicting selector, or use an explicit agent@version target.'));
+                    'Remove the conflicting selector, or pin the target explicitly (agent@version or agent#label).'));
+                process.exit(1);
+            }
+        }
+        if (devicePickerRequested) {
+            const conflicts = runDevicePickerConflicts(options);
+            if (conflicts.length > 0) {
+                console.error(chalk.red(`Device selection with ${agentSpec} cannot be combined with ${conflicts.join(', ')}. ` +
+                    'Remove one — the picker already chooses where the run lands.'));
                 process.exit(1);
             }
         }
@@ -1013,7 +1139,11 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 process.exit(1);
             }
             if (accountPickerRequested) {
-                console.error(chalk.red(`agents run auto picks the harness and account itself — the trailing-@ account picker needs a concrete harness (agents run <harness>@).`));
+                console.error(chalk.red(`agents run auto picks the harness and account itself — the trailing-# account picker needs a concrete harness (agents run <harness>#).`));
+                process.exit(1);
+            }
+            if (devicePickerRequested) {
+                console.error(chalk.red(`agents run auto picks the harness and its placement itself — the trailing-@ device picker needs a concrete harness (agents run <harness>@).`));
                 process.exit(1);
             }
             // Host layer: with no explicit --device, default to the
@@ -1022,19 +1152,100 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             if (!resolvedResumeSource && runAutoDefaultsToAffinity(options))
                 options.device = 'auto';
         }
+        // The picker menus run HERE — after every conflict check, before
+        // placement resolves — so the picked account labels the device rows and
+        // the picked device is concrete for every host branch below.
+        //   `#@`/`@#`: account first, against THIS machine's slots; the picked
+        //     account becomes options.account and the device menu shows its
+        //     ✓/– per-device mark. A remote device pick dispatches with
+        //     `<agent>#<label>` so the peer resolves its own slot.
+        //   `@`: just the device menu; picking this machine is a plain local run.
+        // Either menu cancelled (Esc/Ctrl-C) launches nothing and exits 0.
+        let upFrontAccountPick = null;
+        if (accountPickerRequested && devicePickerRequested) {
+            const baseName = normalizedAgentSpec.split('#')[0].split('@')[0];
+            const baseAgentId = resolveAgentName(baseName);
+            const { profileExists: baseProfileExists } = await import('../lib/profiles.js');
+            if (!baseAgentId || baseProfileExists(baseName)) {
+                console.error(chalk.red(baseProfileExists(baseName)
+                    ? `Account selection is not available for custom harness '${baseName}'. Run its concrete host agent with # instead.`
+                    : `Account selection is not available for '${baseName}'. Run a concrete agent with # instead.`));
+                process.exit(1);
+            }
+            const { supportsAccountInspection: baseSupportsInspection, agentLabel: baseAgentLabel, ACCOUNT_INSPECTION_AGENT_IDS: inspectionAgentIds } = await import('../lib/agents.js');
+            if (!baseSupportsInspection(baseAgentId)) {
+                console.error(chalk.red(`${baseAgentLabel(baseAgentId)} does not expose local account state, so agents-cli cannot safely select an account.`));
+                console.error(chalk.gray(`Supported account pickers: ${inspectionAgentIds.join(', ')}`));
+                process.exit(1);
+            }
+            const { pickRunAccountCandidate } = await import('./run-account-picker.js');
+            const selected = await pickRunAccountCandidate(baseAgentId);
+            if (!selected)
+                return; // Esc/Ctrl-C: launch nothing.
+            if (selected.nativeAccount)
+                options.account = selected.nativeAccount;
+            upFrontAccountPick = selected;
+            if (!options.quiet) {
+                const identity = selected.accountLabel || 'signed-in account';
+                process.stderr.write(chalk.gray(`[agents] selected ${identity} · ${baseAgentId}@${selected.version} for this run\n`));
+            }
+        }
+        if (devicePickerRequested) {
+            // --resume above may have pinned the host implicitly (recovery to the
+            // source peer); a device menu against it would be a silent no-op.
+            const impliedHost = hostTargetGiven(options);
+            if (impliedHost.length > 0) {
+                console.error(chalk.red(`Device selection with ${agentSpec} cannot be combined with the placement --resume already chose (${impliedHost.join(', ')}). ` +
+                    'Remove one — both pick where the run lands.'));
+                process.exit(1);
+            }
+            const { pickRunDevice } = await import('./run-device-picker.js');
+            const baseName = normalizedAgentSpec.split('#')[0].split('@')[0];
+            const pickedDevice = await pickRunDevice({
+                agent: (resolveAgentName(baseName) ?? baseName),
+                accountLabel: options.account,
+            });
+            if (pickedDevice === null)
+                return; // Esc/Ctrl-C: launch nothing.
+            const { isSelfHost } = await import('../lib/devices/self-host.js');
+            // Picking this machine is a plain local run — leave options.device unset.
+            if (!isSelfHost(pickedDevice))
+                options.device = pickedDevice;
+        }
+        // Default placement (PHNX-4083): a bare human-facing `agents run
+        // <harness>` (no prompt, real TTY, no placement flags, not a dispatched
+        // hop) places itself like `--device auto` — a marker left off is decided
+        // for you. Headless runs (a prompt, --json, teams/routines/hooks) keep
+        // running in place, unchanged.
+        const defaultPlacement = bareInteractiveRunDefaultsToDeviceAuto(options, { prompt, devicePickerRequested }, { tty: isInteractiveTerminal(), json: options.json });
+        if (defaultPlacement)
+            options.device = 'auto';
         // --device auto (and deprecated --smart): live fleet pick.
         // Harness is always the agent the user typed — never auto-picked.
         // Placement failure propagates; an automatic request never becomes local.
         {
             const { applyDeviceAutoToOptions } = await import('../lib/smart-launch.js');
-            const result = await applyDeviceAutoToOptions(options, {
-                accountPickerRequested,
-                // `run auto` selects its harness after placement, so do not filter
-                // candidates against an arbitrary proxy harness at this stage.
-                agent: normalizedAgentSpec.split('#')[0].split('@')[0] === RUN_AUTO_KEYWORD
-                    ? undefined
-                    : (resolveAgentName(normalizedAgentSpec.split('#')[0].split('@')[0]) ?? undefined),
-            });
+            let result;
+            try {
+                result = await applyDeviceAutoToOptions(options, {
+                    accountPickerRequested,
+                    // `run auto` selects its harness after placement, so do not filter
+                    // candidates against an arbitrary proxy harness at this stage.
+                    agent: normalizedAgentSpec.split('#')[0].split('@')[0] === RUN_AUTO_KEYWORD
+                        ? undefined
+                        : (resolveAgentName(normalizedAgentSpec.split('#')[0].split('@')[0]) ?? undefined),
+                });
+            }
+            catch (err) {
+                // Placement the DEFAULT chose must fail loud AND name the local
+                // escape hatch — never silently fall back to a local launch.
+                if (!defaultPlacement)
+                    throw err;
+                console.error(chalk.red(err.message));
+                const { machineId } = await import('../lib/machine-id.js');
+                console.error(chalk.gray(`Run here instead: agents run ${runBaseAgentName} --device ${machineId()}`));
+                process.exit(1);
+            }
             if (!options.quiet && result.deprecationSmart) {
                 process.stderr.write(chalk.yellow('[agents] --smart is deprecated; use --device auto\n'));
             }
@@ -1512,9 +1723,11 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                     process.exit(1);
                 }
                 const interactiveHost = options.interactive === true || (prompt === undefined && options.headless !== true);
-                if (accountPickerRequested && !interactiveHost) {
+                // When the account was already picked up front (`#@`), the dispatch
+                // forwards `#label` and the peer needs no interactive picker.
+                if (accountPickerRequested && !upFrontAccountPick && !interactiveHost) {
                     console.error(chalk.red(`Account selection with ${agentSpec} requires an interactive host run. ` +
-                        `Use agents run ${runAgent}@ --device ${host.name} --interactive.`));
+                        `Use agents run ${runAgent}# --device ${host.name} --interactive.`));
                     process.exit(1);
                 }
                 if (interactiveHost) {
@@ -1576,7 +1789,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                     const exitCode = await runInteractiveOnHost(host, {
                         agent: runAgent,
                         version: resumeId ? undefined : runVersion,
-                        accountPicker: accountPickerRequested,
+                        accountPicker: accountPickerRequested && !upFrontAccountPick,
                         strategy: resumeId ? undefined : runStrategy,
                         account: options.account,
                         fallback: options.fallback,
@@ -1908,12 +2121,12 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
         let workflowHasSubagents = false;
         const cwd = options.cwd ?? process.cwd();
         if (accountPickerRequested && profileExists(rawAgent)) {
-            console.error(chalk.red(`Account selection is not available for custom harness '${rawAgent}'. Run its concrete host agent with @ instead.`));
+            console.error(chalk.red(`Account selection is not available for custom harness '${rawAgent}'. Run its concrete host agent with # instead.`));
             process.exit(1);
         }
         if (accountPickerRequested && !isValidAgent(rawAgent)) {
             if (resolveWorkflowRef(rawAgent, cwd)) {
-                console.error(chalk.red(`Account selection is not available for workflow '${rawAgent}'. Run a concrete agent with @ instead.`));
+                console.error(chalk.red(`Account selection is not available for workflow '${rawAgent}'. Run a concrete agent with # instead.`));
                 process.exit(1);
             }
         }
@@ -2194,7 +2407,10 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 process.exit(1);
             }
         }
-        if (accountPickerRequested) {
+        // `#@` already asked the account up front (before the device menu) — a
+        // remote device pick never reaches here, so apply the local pick's
+        // version/home and skip the on-the-spot menu.
+        if (accountPickerRequested && !upFrontAccountPick) {
             if (!supportsAccountInspection(agent)) {
                 console.error(chalk.red(`${agentLabel(agent)} does not expose local account state, so agents-cli cannot safely select an account.`));
                 console.error(chalk.gray(`Supported account pickers: ${ACCOUNT_INSPECTION_AGENT_IDS.join(', ')}`));
@@ -2220,6 +2436,11 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 process.exit(1);
             }
         }
+        if (upFrontAccountPick) {
+            version = upFrontAccountPick.version;
+            if (upFrontAccountPick.slotDir)
+                execHome = upFrontAccountPick.slotDir;
+        }
         version = resolveVersionAlias(agent, version);
         const { resolveSpawnAccount } = await import('../lib/account-registry.js');
         let spawnAccount = null;
@@ -2437,7 +2658,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                         // - 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`
+                        //   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');
@@ -2450,7 +2671,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                             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.
+                            // trailing-# account picker above.
                             if (!signInVersion)
                                 return;
                             version = signInVersion;
@@ -2488,7 +2709,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                         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.
+                            // trailing-# account picker and the sign-in launch above.
                             if (!selected)
                                 return;
                             version = selected.version;

package/dist/commands/run-account-picker.d.ts

@@ -35,6 +35,17 @@ export declare function buildSwitchAccountChoices(rows: SwitchAccountRow[]): Run
  * A cancelled picker writes nothing.
  */
 export declare function pickSwitchAccount(agent: AgentId, rows: SwitchAccountRow[]): Promise<string | null>;
+/**
+ * The two-condition "human-facing" gate behind signInLaunchDecision and
+ * noVerifiedUsageDecision: a real TTY and no `--json`. Off a TTY nobody can
+ * answer a prompt, and `--json` marks a MACHINE consumer, which must never be
+ * handed a picker or dropped into a login TUI. Mirrors the canonical
+ * `Surface.interactive = tty && !json` in `commands/utils.ts`.
+ */
+export declare function isHumanFacingRun(input: {
+    tty: boolean;
+    json: boolean;
+}): boolean;
 /**
  * Whether a zero-healthy run may recover by launching for a login, or must keep
  * failing loud. Three inputs, all of which have to hold:

package/dist/commands/run-account-picker.js

@@ -204,6 +204,16 @@ export async function pickSwitchAccount(agent, rows) {
         throw err;
     }
 }
+/**
+ * The two-condition "human-facing" gate behind signInLaunchDecision and
+ * noVerifiedUsageDecision: a real TTY and no `--json`. Off a TTY nobody can
+ * answer a prompt, and `--json` marks a MACHINE consumer, which must never be
+ * handed a picker or dropped into a login TUI. Mirrors the canonical
+ * `Surface.interactive = tty && !json` in `commands/utils.ts`.
+ */
+export function isHumanFacingRun(input) {
+    return input.tty && !input.json;
+}
 /**
  * Whether a zero-healthy run may recover by launching for a login, or must keep
  * failing loud. Three inputs, all of which have to hold:
@@ -217,7 +227,7 @@ export async function pickSwitchAccount(agent, rows) {
  *   gets the parseable fail-loud error instead.
  */
 export function signInLaunchDecision(input) {
-    const humanPresent = input.tty && !input.json;
+    const humanPresent = isHumanFacingRun(input);
     return input.recoverable > 0 && humanPresent ? 'launch' : 'fail-loud';
 }
 /**

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

@@ -182,7 +182,7 @@ 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. */
+    /** 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;

package/dist/lib/hosts/dispatch.js

@@ -362,7 +362,7 @@ async function launchDetached(host, target, opts) {
 /** Compose `agent[@version][#account]` so the peer resolves ITS slot (PHNX-3940 T5). */
 export function runAgentSpecArg(opts) {
     if (opts.accountPicker)
-        return `${opts.agent}@`;
+        return `${opts.agent}#`;
     let spec = opts.agent;
     if (opts.version)
         spec += `@${opts.version}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.106",
+  "version": "1.22.107",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",