@phnx-labs/agents-cli 1.22.106 → 1.22.109

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
+      # Pick a signed-in account/version for only this run (# = account picker)
+      agents run claude#
+
+      # 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] === '') {
@@ -868,6 +986,8 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 throw new Error('--resume cannot be combined with --session-id, --loop, --fallback, --resume-checkpoint, or --lease.');
             }
             const { sessionsResumeAction } = await import('./sessions-resume.js');
+            const { toRemotePortable } = await import('../lib/project-root.js');
+            const device = options.host || options.device || options.on || options.computer;
             await sessionsResumeAction(undefined, prompt, {
                 agent: normalizedAgentSpec.split('#')[0] === RUN_AUTO_KEYWORD ? undefined : normalizedAgentSpec.split('#')[0],
                 account: options.account,
@@ -875,9 +995,9 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 mode: command.getOptionValueSource('mode') === 'default' ? undefined : options.mode,
                 interactive: options.interactive,
                 headless: options.headless,
-                cwd: options.cwd,
+                cwd: device ? options.remoteCwd ?? (options.cwd ? toRemotePortable(options.cwd) : undefined) : options.cwd,
                 quiet: options.quiet,
-                device: options.host || options.device || options.on || options.computer,
+                device,
                 runArgs: rawArgs.slice(2),
             });
             return;
@@ -890,14 +1010,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 +1141,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 +1154,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 +1725,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 +1791,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 +2123,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 +2409,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 +2438,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 +2660,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 +2673,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 +2711,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/monitors.js

@@ -12,7 +12,7 @@ import { withAliases } from '../lib/verbs.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
-import { isDaemonRunning, signalDaemonReload, startDaemon, } from '../lib/daemon/daemon.js';
+import { isDaemonRunning, signalDaemonReload, startDaemon, RedirectedHomeDaemonError, } from '../lib/daemon/daemon.js';
 import { findDuplicateMonitor, monitorFingerprint } from '../lib/monitors/fingerprint.js';
 import { gatherFleetMonitors, NO_MONITOR_FANOUT_ENV } from '../lib/monitors/remote.js';
 import { listMonitors, readMonitor, writeMonitor, deleteMonitor, setMonitorEnabled, getMonitorPath, validateMonitor, monitorRunsOnThisDevice, requiresSingleOwner, monitorSharedInputOwner, parseInterval, } from '../lib/monitors/config.js';
@@ -246,7 +246,20 @@ function ensureDaemonRunning() {
         stderrLine(chalk.gray('Daemon reloaded'));
         return true;
     }
-    const result = startDaemon();
+    let result;
+    try {
+        result = startDaemon();
+    }
+    catch (err) {
+        // The redirected-HOME refusal (W4) is an auto-start policy, not a failure
+        // of the monitor just added — state it and leave the foreground command
+        // green. Anything else (a genuinely unspawnable binary) still fails loud.
+        if (err instanceof RedirectedHomeDaemonError) {
+            stderrLine(chalk.yellow(err.message));
+            return true;
+        }
+        throw err;
+    }
     if (result.pid) {
         console.log(chalk.green(`Daemon started (PID: ${result.pid}). It will watch monitors in the background.`));
         console.log(chalk.gray('Disable only monitor polling with: agents daemon services disable monitors'));

package/dist/commands/routines.js

@@ -10,7 +10,7 @@ import ora from 'ora';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
-import { isDaemonRunning, signalDaemonReload, startDaemon, readDaemonLog, getDaemonStatus, getDaemonLogPath, } from '../lib/daemon/daemon.js';
+import { isDaemonRunning, signalDaemonReload, startDaemon, readDaemonLog, getDaemonStatus, getDaemonLogPath, RedirectedHomeDaemonError, } from '../lib/daemon/daemon.js';
 import { isDaemonServiceEnabled, setDaemonServiceEnabled } from '../lib/daemon-services.js';
 import { assertSchedulerEnabled, assertDaemonEnabled, isDaemonEnabled, isSchedulerEnabled, } from '../lib/device-config.js';
 import { parseAgentVersionSpec, isAgentHardDeprecated, hardDeprecationError, ROUTINE_AGENT_IDS } from '../lib/agents.js';
@@ -327,7 +327,22 @@ function ensureSchedulerRunning(opts = {}) {
         }
         return;
     }
-    const result = startDaemon();
+    let result;
+    try {
+        result = startDaemon();
+    }
+    catch (err) {
+        // The redirected-HOME refusal (W4) is an auto-start policy, not a failure
+        // of the routine just added — state it and leave the foreground command
+        // green, the same tier split as the auto-start circuit breaker. Anything
+        // else (a genuinely unspawnable binary) still fails loud.
+        if (err instanceof RedirectedHomeDaemonError) {
+            if (!opts.quiet)
+                log(chalk.yellow(err.message));
+            return;
+        }
+        throw err;
+    }
     if (opts.quiet)
         return;
     if (result.pid) {
@@ -1851,9 +1866,22 @@ export function registerRoutinesCommands(program) {
                 console.log(chalk.yellow(`Daemon is disabled (daemon.enabled=false) — run(s) below fire but are not monitored. Re-enable with: agents daemon enable`));
             }
             else {
-                const started = startDaemon();
-                if (started.pid) {
-                    console.log(chalk.gray(`Started scheduler (PID: ${started.pid}) so webhook runs are monitored.`));
+                try {
+                    const started = startDaemon();
+                    if (started.pid) {
+                        console.log(chalk.gray(`Started scheduler (PID: ${started.pid}) so webhook runs are monitored.`));
+                    }
+                }
+                catch (err) {
+                    // Same contract as the daemon.enabled=false branch above: a refused
+                    // auto-start (W4's redirected-HOME guard) never cancels the fire —
+                    // the runs below fire but are not monitored. Anything else rethrows.
+                    if (err instanceof RedirectedHomeDaemonError) {
+                        console.log(chalk.yellow(err.message));
+                    }
+                    else {
+                        throw err;
+                    }
                 }
             }
         }
@@ -2185,7 +2213,19 @@ export function registerRoutinesCommands(program) {
             process.exit(1);
         }
         setDaemonServiceEnabled('scheduler', true);
-        const result = startDaemon();
+        let result;
+        try {
+            result = startDaemon();
+        }
+        catch (err) {
+            // The redirected-HOME refusal (W4) is user-actionable — print it
+            // without a stack, same as the asserts above.
+            if (err instanceof RedirectedHomeDaemonError) {
+                console.error(chalk.red(err.message));
+                process.exit(1);
+            }
+            throw err;
+        }
         if (result.method === 'already-running') {
             // Signal a reload even here: if the daemon booted while this device had
             // scheduler.enabled=false, the reload re-evaluates the gate and boots

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: