@phnx-labs/agents-cli 1.22.116 → 1.22.117

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.22.117
+
+- **`agents run --local`, and `--device <this machine>` no longer SSHes to itself.** A bare
+  interactive run places itself like `--device auto` (PHNX-4083), and the documented way to
+  stay put was `--device <this machine>` — which took the remote path and probed its own
+  login shell over SSH, timing out on a loaded box. `--local` is the explicit local pin
+  (the same door as `--where local`, which previously expanded to nothing and was then
+  overridden by the default placement); any host flag naming this machine by short id,
+  MagicDNS name, loopback, or the `interactive` sentinel now resolves to the same local
+  run. The placement-failure hint names `--local`. Source: `cli/src/commands/exec.ts`
+  (`pinLocalWhenTargetIsSelf`), `cli/src/lib/placement.ts`, `cli/src/lib/hosts/remote-cmd.ts`.
+
 ## 1.22.116
 
 - **`agents feed answer` is bounded, exactly-once, and truthful about delivery

package/dist/commands/exec.d.ts

@@ -62,6 +62,7 @@ interface ExecCommandActionOptions {
     until?: string;
     interval?: string;
     where?: string;
+    local?: boolean;
     host?: string;
     device?: string;
     on?: string;
@@ -130,6 +131,20 @@ export declare function hostTargetGiven(options: {
     on?: string;
     computer?: string;
 }): string[];
+/**
+ * Turn a host target that names THIS machine into an explicit local pin: the
+ * host-family flags are cleared and `local` is set, so no dispatch path
+ * self-SSHes and the bare-interactive default (`bareInteractiveRunDefaultsToDeviceAuto`)
+ * sees a decided placement. Returns true when the pin was applied. Pure over
+ * the `isSelf` predicate so the rule is testable without a device registry.
+ */
+export declare function pinLocalWhenTargetIsSelf(options: {
+    host?: string;
+    device?: string;
+    on?: string;
+    computer?: string;
+    local?: boolean;
+}, isSelf: (name: string) => boolean): boolean;
 /**
  * Return every option whose selection semantics conflict with an account
  * choice (`agent#`). Device routing is deliberately absent: the marker rides
@@ -159,6 +174,7 @@ export declare function runDevicePickerConflicts(options: {
     device?: string;
     on?: string;
     computer?: string;
+    local?: boolean;
 }): string[];
 export { RUN_AUTO_KEYWORD };
 /**
@@ -179,6 +195,7 @@ export declare function runAutoDefaultsToAffinity(options: {
     device?: string;
     on?: string;
     computer?: string;
+    local?: boolean;
 }, env?: NodeJS.ProcessEnv): boolean;
 /**
  * Whether a bare human-facing `agents run <harness>` — no prompt, so an
@@ -210,6 +227,7 @@ export declare function bareInteractiveRunDefaultsToDeviceAuto(options: {
     lease?: string | boolean;
     box?: string;
     cloud?: boolean;
+    local?: boolean;
 }, run: {
     prompt?: string;
     devicePickerRequested?: boolean;

package/dist/commands/exec.js

@@ -90,6 +90,24 @@ export function parseRunPickerMarkers(agentSpec) {
 export function hostTargetGiven(options) {
     return [options.host, options.device, options.on, options.computer].filter((v) => !!v);
 }
+/**
+ * Turn a host target that names THIS machine into an explicit local pin: the
+ * host-family flags are cleared and `local` is set, so no dispatch path
+ * self-SSHes and the bare-interactive default (`bareInteractiveRunDefaultsToDeviceAuto`)
+ * sees a decided placement. Returns true when the pin was applied. Pure over
+ * the `isSelf` predicate so the rule is testable without a device registry.
+ */
+export function pinLocalWhenTargetIsSelf(options, isSelf) {
+    const targets = hostTargetGiven(options);
+    if (targets.length === 0 || !targets.every(isSelf))
+        return false;
+    options.host = undefined;
+    options.device = undefined;
+    options.on = undefined;
+    options.computer = undefined;
+    options.local = true;
+    return true;
+}
 /**
  * Return every option whose selection semantics conflict with an account
  * choice (`agent#`). Device routing is deliberately absent: the marker rides
@@ -118,6 +136,8 @@ export function runAccountPickerConflicts(options) {
  */
 export function runDevicePickerConflicts(options) {
     const conflicts = hostTargetGiven(options).map((h) => `--device ${h}`);
+    if (options.local)
+        conflicts.push('--local');
     if (options.lease)
         conflicts.push('--lease');
     if (options.box)
@@ -145,6 +165,11 @@ export { RUN_AUTO_KEYWORD };
  * fleet. Pure so the pinning matrix is unit-testable.
  */
 export function runAutoDefaultsToAffinity(options, env = process.env) {
+    // An explicit local pin (--local, --where local, --device <this machine>)
+    // is a decided host layer with an empty host set; read it here so the
+    // `run auto` and bare-interactive defaults share one rule.
+    if (options.local)
+        return false;
     if (hostTargetGiven(options).length > 0)
         return false;
     if (env.AGENTS_RUN_AUTO_HOST_RESOLVED === '1')
@@ -639,7 +664,8 @@ export function registerRunCommand(program) {
         .option('--until <signal>', 'Loop stop condition. `signal` reads <runDir>/loop-signal.json {continue,reason} each iteration; absent or continue:false stops (fail-closed). Loop only.')
         .option('--interval <dur>', 'Loop delay between iterations ("0" back-to-back, "30m" paces). Loop only.')
         .option('--where <spec>', 'Where this run\'s body executes (one placement door): local | device:<name> | auto | lease[:backend] | cloud[:provider]. Expands to --device/--lease/--cloud. Do not combine with those flags. See docs/00-concepts.md#placement.')
-        .option('-D, --device <name>', 'Offload this run onto another machine over SSH — a registered device, or user@host. Pass "auto" to pick the least-loaded reachable device where the requested agent is installed and signed in, keeping the run local when no remote is better, or "interactive" for the machine pinned as interactive.host (the box a human is sitting at). Same as --where device:<name>. See `agents devices`.')
+        .option('--local', 'Run on this machine. A bare interactive run otherwise places itself like --device auto; --local pins it here. Same as --where local or --device <this machine>.')
+        .option('-D, --device <name>', 'Offload this run onto another machine over SSH — a registered device, or user@host. Pass "auto" to pick the least-loaded reachable device where the requested agent is installed and signed in, keeping the run local when no remote is better, or "interactive" for the machine pinned as interactive.host (the box a human is sitting at). Naming this machine runs locally, no SSH. Same as --where device:<name>. See `agents devices`.')
         .option('--remote-cwd <dir>', "Explicit device working directory for --device runs, used VERBATIM (overrides --cwd; usually --cwd suffices — it re-roots a local-home path onto the remote home). Pass a single-quoted '$HOME/…' or a valid remote absolute path; a local ~ expands here and won't exist there (/Users/you vs /home/you).")
         .option('--no-follow', 'With --device, dispatch detached and return immediately (track via `agents hosts ps/logs`).')
         .option('--any', 'With --device <cap> (a capability tag), pick any matching device instead of erroring when several match.')
@@ -680,9 +706,9 @@ export function registerRunCommand(program) {
       agents run claude "fix lint errors in src/" --mode edit
 
       # 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
+      # worker, TUI forwarded over SSH); --local keeps it on this machine
       agents run claude
-      agents run claude --device zion      # stay local (or pick this machine in claude@)
+      agents run claude --local            # stay local (or pick this machine in claude@)
 
       # Pick a signed-in account/version for only this run (# = account picker)
       agents run claude#
@@ -790,10 +816,10 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
       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.
+        unchanged: they run in place. To stay on this machine, pass --local
+        (--device <this machine> means the same), 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 spelling.
 
       Fallback: --fallback codex,antigravity retries on rate-limit failure via /continue handoff. Each entry accepts @version.
 
@@ -891,6 +917,11 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             const { placementFromRunFlags, expandPlacementToRunFlags, PlacementError } = await import('../lib/placement.js');
             try {
                 const placement = placementFromRunFlags(options);
+                // An explicit local placement (--local, --where local) must outlive
+                // this block: expansion yields no host flag, and the bare-interactive
+                // default below reads an empty host set as "decide for me".
+                if (placement.kind === 'local' && placement.source !== 'default')
+                    options.local = true;
                 if (options.where) {
                     const expanded = expandPlacementToRunFlags(placement);
                     if (expanded.host !== undefined)
@@ -918,6 +949,16 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 throw err;
             }
         }
+        // --device naming this machine (short id, MagicDNS name, loopback, or the
+        // `interactive` sentinel pinned here) is a local run, not a self-SSH: the
+        // hop probes its own login shell and times out under load. Pinned here,
+        // ahead of every placement gate, so the bare-interactive default sees an
+        // explicit local choice rather than an empty host set.
+        {
+            const { isSelfHost } = await import('../lib/devices/self-host.js');
+            const { isDeviceInteractive, resolveInteractiveDevice } = await import('../lib/devices/interactive-host.js');
+            pinLocalWhenTargetIsSelf(options, (name) => isSelfHost(isDeviceInteractive(name) ? resolveInteractiveDevice() ?? name : name));
+        }
         // Cloud refinement flags without the placement are a typo, not a no-op.
         if (!options.cloud) {
             const { cloudFlagsWithoutCloud } = await import('./run-cloud.js');
@@ -1101,13 +1142,13 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             const { sessionRecoveryDestinationMatches, sessionRecoveryPeer, } = await import('../lib/session/recovery.js');
             const sourceMachine = resolvedResumeSource.machine;
             const sourcePeer = sessionRecoveryPeer(resolvedResumeSource);
-            const explicitPlacement = hostTargetGiven(options).length > 0;
+            const explicitPlacement = hostTargetGiven(options).length > 0 || options.local === true;
             if (sourcePeer && !explicitPlacement) {
                 options.host = sourcePeer;
             }
             else if (sourcePeer && explicitPlacement && !hostTargetGiven(options).some((host) => sessionRecoveryDestinationMatches(resolvedResumeSource, host))) {
                 console.error(chalk.red(`Session ${resolvedResumeSource.shortId} must recover on ${sourcePeer}, where its conversation state is stored; ` +
-                    `the requested device was ${hostTargetGiven(options).join(', ')}.`));
+                    `the requested device was ${hostTargetGiven(options).join(', ') || 'this machine'}.`));
                 process.exit(1);
             }
             // Recovery is resolved on the device that owns the transcript. A remote
@@ -1246,8 +1287,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 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()}`));
+                console.error(chalk.gray(`Run here instead: agents run ${runBaseAgentName} --local`));
                 process.exit(1);
             }
             if (!options.quiet && result.banner) {

package/dist/commands/setup-term.d.ts

@@ -2,9 +2,10 @@
  * `agents setup term` — install the standalone `term` CLI if missing (PHNX-4092).
  *
  * The PTY engine lives in `@phnx-labs/term-cli` (extracted PHNX-4091);
- * agents-cli never rebundles it. The OAuth device-code driver (`agents fleet
- * login`, `agents auth mint`) spawns `term` on demand and fails loud when it is
- * absent, so onboarding installs it here like every other standalone tool.
+ * agents-cli never rebundles it. The setup-token mint behind `agents accounts
+ * add` / `agents accounts login` (auth-mint.ts → term-driver.ts) spawns `term`
+ * on demand and fails loud when it is absent, so onboarding installs it here
+ * like every other standalone tool.
  *
  * Unlike browser/computer/secrets there is nothing to configure — no profile,
  * no OS permission, no migrate step. A missing binary is a routine install

package/dist/commands/setup-term.js

@@ -2,9 +2,10 @@
  * `agents setup term` — install the standalone `term` CLI if missing (PHNX-4092).
  *
  * The PTY engine lives in `@phnx-labs/term-cli` (extracted PHNX-4091);
- * agents-cli never rebundles it. The OAuth device-code driver (`agents fleet
- * login`, `agents auth mint`) spawns `term` on demand and fails loud when it is
- * absent, so onboarding installs it here like every other standalone tool.
+ * agents-cli never rebundles it. The setup-token mint behind `agents accounts
+ * add` / `agents accounts login` (auth-mint.ts → term-driver.ts) spawns `term`
+ * on demand and fails loud when it is absent, so onboarding installs it here
+ * like every other standalone tool.
  *
  * Unlike browser/computer/secrets there is nothing to configure — no profile,
  * no OS permission, no migrate step. A missing binary is a routine install
@@ -45,7 +46,7 @@ export async function runTermWizard() {
 export function registerSetupTermCommand(setupCmd) {
     setupCmd
         .command('term')
-        .description('Install the standalone `term` CLI (the PTY engine fleet login and auth mint spawn) if missing.')
+        .description('Install the standalone `term` CLI (the PTY engine `agents accounts add`/`login` spawn) if missing.')
         .option('--install-only', 'Install the standalone term CLI (identical to the wizard; term needs no further setup)')
         .option('--terminal [backend]', 'Open interactive setup in a detected or selected terminal')
         .action(async (options) => {

package/dist/commands/setup.js

@@ -289,7 +289,7 @@ export async function getSetupStatus() {
         { phase: 'browser', state: browserReady ? 'ready' : 'missing', detail: browserReady ? `profile ${browserProfile.name}` : browserProfile ? `profile ${browserProfile.name} cannot launch here` : installedBrowsers.length ? 'no default profile' : 'no supported browser found' },
         { phase: 'computer', state: computerState, detail: computerState === 'ready' ? 'helper trusted' : computerState === 'n/a' ? 'macOS local setup only' : 'helper not running or not trusted' },
         { phase: 'secrets', state: secretsReady ? 'ready' : 'missing', detail: secretsReady ? 'defaults chosen' : 'defaults not chosen' },
-        { phase: 'term', state: termReady ? 'ready' : 'missing', detail: termReady ? 'installed' : 'not installed (fleet login / auth mint spawn it)' },
+        { phase: 'term', state: termReady ? 'ready' : 'missing', detail: termReady ? 'installed' : 'not installed (accounts add/login spawn it)' },
         { phase: 'accounts', state: minted.ready ? 'ready' : 'missing', detail: minted.detail },
         { phase: 'fleet', state: Object.keys(devices).length ? 'ready' : 'missing', detail: Object.keys(devices).length ? `${Object.keys(devices).length} device${Object.keys(devices).length === 1 ? '' : 's'} registered` : 'no devices registered' },
         { phase: 'watchdog', state: watchdogEnabled ? 'ready' : 'missing', detail: watchdogEnabled ? 'enabled on this device' : 'disabled on this device' },
@@ -462,7 +462,7 @@ export function registerSetupCommand(program) {
         agents setup browser    # detect a browser + create the default profile
         agents setup computer    # install the signed macOS helper + grant permissions
         agents setup secrets     # choose secrets backend/policy defaults + import
-        agents setup term        # install the standalone term CLI (PTY engine for fleet login / auth mint)
+        agents setup term        # install the standalone term CLI (PTY engine agents accounts add/login spawn)
         agents setup accounts    # mint a Claude setup-token for unattended usage/probe
         agents setup fleet       # discover Tailscale devices + configure SSH access
         agents setup watchdog    # choose which devices run the daemon watchdog pass

package/dist/lib/hosts/remote-cmd.js

@@ -109,6 +109,7 @@ export const RUN_OPTION_FORWARDING = {
     disableTmux: 'local-only',
     device: 'local-only',
     where: 'local-only', // expands into host/lease before dispatch; never re-forwarded
+    local: 'local-only', // this machine by definition — a local run never reaches the SSH boundary
     on: 'local-only',
     computer: 'local-only',
     any: 'local-only',

package/dist/lib/placement.d.ts

@@ -45,6 +45,8 @@ interface RunPlacementFlags {
     cloud?: boolean;
     /** --provider: refines the cloud placement; not a placement on its own. */
     provider?: string;
+    /** --local: this machine, said explicitly — the pin a bare interactive run needs to stay off `--device auto`. */
+    local?: boolean;
 }
 export declare class PlacementError extends Error {
     constructor(message: string);

package/dist/lib/placement.js

@@ -94,9 +94,12 @@ export function placementFromRunFlags(flags) {
     const hasLease = flags.lease !== undefined && flags.lease !== false;
     const hasBox = !!flags.box;
     const hasCloud = flags.cloud === true;
+    const hasLocal = flags.local === true;
     const placementFlags = [];
     if (where)
         placementFlags.push('--where');
+    if (hasLocal)
+        placementFlags.push('--local');
     if (hostT)
         placementFlags.push('--device');
     if (hasLease)
@@ -111,6 +114,8 @@ export function placementFromRunFlags(flags) {
     }
     if (where)
         return parseWhereSpec(where, '--where');
+    if (hasLocal)
+        return { kind: 'local', source: '--local' };
     if (hasCloud)
         return { kind: 'cloud', target: flags.provider, source: '--cloud' };
     if (hasBox)

package/dist/lib/setup-tool-status.js

@@ -140,10 +140,11 @@ async function checkTool(row) {
     if (row.tool === 'secrets')
         return { ...row, checkedAtMs: Date.now(), detail: 'Installed. Secret access is checked when used; this check does not unlock secrets.' };
     // term is a headless PTY engine with no `status --json` health surface; it is
-    // spawned on demand by the OAuth device-code driver (fleet login / auth mint).
+    // spawned on demand by the setup-token mint (`agents accounts add`/`login`,
+    // via auth-mint.ts → term-driver.ts, the sole term-client consumers).
     // Presence on PATH is the whole readiness signal — do not probe it.
     if (row.tool === 'term')
-        return { ...row, readiness: 'ready', detail: 'Installed. Spawned on demand by fleet login and auth mint.', checkedAtMs: Date.now() };
+        return { ...row, readiness: 'ready', detail: 'Installed. Spawned on demand by `agents accounts add`/`login`.', checkedAtMs: Date.now() };
     try {
         const { command, prefix } = invocation(row.executable);
         const { stdout } = await probeCapture(command, [...prefix, 'status', '--json'], 8000, { acceptedExitCodes: [0, 1], maxOutputBytes: 256 * 1024 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.116",
+  "version": "1.22.117",
   "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",