@phnx-labs/agents-cli 1.22.45 → 1.22.47

package/dist/lib/feed/watch.d.ts

@@ -0,0 +1,59 @@
+import { type SessionWatchEnvelope, type SessionWatchRow, type SessionWatchScopeStatus } from '../session/watch.js';
+import { type AttentionItem } from './attention.js';
+import { type ActivityEvent } from './activity.js';
+export declare const FEED_WATCH_VERSION: 1;
+type Base = {
+    v: 1;
+    type: string;
+    streamId: string;
+    sequence: number;
+    scope: string;
+};
+export type FeedWatchEnvelope = Base & {
+    type: 'reset';
+    capturedAt: number;
+    agents: SessionWatchRow[];
+    attention: AttentionItem[];
+} | Base & {
+    type: 'agent.upsert';
+    rowKey: string;
+    agent: SessionWatchRow;
+} | Base & {
+    type: 'attention.upsert';
+    rowKey: string;
+    attention: AttentionItem;
+} | Base & {
+    type: 'attention.remove';
+    rowKey: string;
+} | Base & {
+    type: 'activity.append';
+    event: ActivityEvent;
+} | Base & {
+    type: 'scope';
+    capturedAt: number;
+    status: SessionWatchScopeStatus;
+    reason?: string;
+} | Base & {
+    type: 'heartbeat';
+    capturedAt: number;
+};
+type FeedWatchPayload = FeedWatchEnvelope extends infer Envelope ? Envelope extends FeedWatchEnvelope ? Omit<Envelope, 'v' | 'streamId' | 'sequence'> : never : never;
+export declare class FeedWatchState {
+    readonly streamId: string;
+    private sequence;
+    constructor(streamId?: `${string}-${string}-${string}-${string}-${string}`);
+    emit(event: FeedWatchPayload): FeedWatchEnvelope;
+}
+export declare function projectSessionEnvelope(event: SessionWatchEnvelope, state: FeedWatchState): Promise<FeedWatchEnvelope[]>;
+export declare function watchLocalFeed(options: {
+    scope: string;
+    signal: AbortSignal;
+    emit: (event: FeedWatchEnvelope) => void;
+    activityPollMs?: number;
+}): Promise<void>;
+export declare function watchFleetFeed(options: {
+    signal: AbortSignal;
+    emit: (event: FeedWatchEnvelope) => void;
+    reconnectMs?: number;
+}): Promise<void>;
+export {};

package/dist/lib/feed/watch.js

@@ -0,0 +1,180 @@
+import { randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { loadDevices, isDialableDevice } from '../devices/registry.js';
+import { deviceIdentityArgs, sshTargetFor } from '../devices/connect.js';
+import { machineId, normalizeHost } from '../machine-id.js';
+import { SSH_OPTS, controlOpts, shellQuote } from '../ssh-exec.js';
+import { buildWindowsAgentsCommand, remoteShellFor } from '../hosts/remote-cmd.js';
+import { watchLocalSessions } from '../session/watch.js';
+import { readBlock, readResolution, blockIdForSession } from './feed.js';
+import { reconcileAttention } from './attention.js';
+import { readRecentActivity } from './activity.js';
+import { readPullRequestStatus } from './pr-status.js';
+export const FEED_WATCH_VERSION = 1;
+export class FeedWatchState {
+    streamId;
+    sequence = 0;
+    constructor(streamId = randomUUID()) { this.streamId = streamId; }
+    emit(event) {
+        return { v: 1, streamId: this.streamId, sequence: ++this.sequence, ...event };
+    }
+}
+async function attentionFor(agent) {
+    if (!agent.sessionId)
+        return undefined;
+    const blockId = blockIdForSession(agent.sessionId);
+    // ActiveSession.host names the terminal app; the feed contract's host is the
+    // device scope. Normalize only the reconciler input so lifecycle/PR keys are
+    // routable across the fleet while the projected agent row stays compatible.
+    const session = { ...agent, host: agent.sourceDevice, viewingIn: undefined };
+    return reconcileAttention({
+        block: readBlock(blockId), session,
+        resolution: readResolution(blockId),
+        pullRequest: await readPullRequestStatus(session), nowMs: Date.now(),
+    });
+}
+export async function projectSessionEnvelope(event, state) {
+    if (event.type === 'reset') {
+        const attention = (await Promise.all(event.rows.map(attentionFor))).filter((item) => item !== undefined);
+        return [state.emit({ type: 'reset', capturedAt: event.capturedAt, scope: event.scope, agents: event.rows, attention })];
+    }
+    if (event.type === 'upsert') {
+        const attention = await attentionFor(event.row);
+        return [
+            state.emit({ type: 'agent.upsert', scope: event.scope, rowKey: event.rowKey, agent: event.row }),
+            attention
+                ? state.emit({ type: 'attention.upsert', scope: event.scope, rowKey: event.rowKey, attention })
+                : state.emit({ type: 'attention.remove', scope: event.scope, rowKey: event.rowKey }),
+        ];
+    }
+    if (event.type === 'remove')
+        return [state.emit({ type: 'attention.remove', scope: event.scope, rowKey: event.rowKey })];
+    if (event.type === 'scope')
+        return [state.emit({ type: 'scope', capturedAt: event.capturedAt, scope: event.scope, status: event.status, ...(event.reason ? { reason: event.reason } : {}) })];
+    return [state.emit({ type: 'heartbeat', capturedAt: event.capturedAt, scope: event.scope })];
+}
+export async function watchLocalFeed(options) {
+    const state = new FeedWatchState();
+    let activityCursor = Date.now();
+    const agents = new Map();
+    const attention = new Map();
+    let pending = Promise.resolve();
+    const reconcileRows = async () => {
+        for (const [rowKey, agent] of agents) {
+            const item = await attentionFor(agent);
+            const next = item ? JSON.stringify(item) : '';
+            if (attention.get(rowKey) === next)
+                continue;
+            attention.set(rowKey, next);
+            options.emit(item
+                ? state.emit({ type: 'attention.upsert', scope: options.scope, rowKey, attention: item })
+                : state.emit({ type: 'attention.remove', scope: options.scope, rowKey }));
+        }
+    };
+    const activityTimer = setInterval(() => {
+        pending = pending.then(async () => {
+            const events = readRecentActivity({ sinceMs: activityCursor + 1 }).reverse();
+            for (const event of events) {
+                activityCursor = Math.max(activityCursor, Date.parse(event.ts));
+                options.emit(state.emit({ type: 'activity.append', scope: options.scope, event }));
+            }
+            await reconcileRows();
+        });
+    }, options.activityPollMs ?? 500);
+    const stopActivity = () => clearInterval(activityTimer);
+    options.signal.addEventListener('abort', stopActivity, { once: true });
+    try {
+        await watchLocalSessions({ scope: options.scope, signal: options.signal, emit: (event) => {
+                if (event.type === 'reset') {
+                    agents.clear();
+                    for (const row of event.rows)
+                        agents.set(row.rowKey, row);
+                }
+                else if (event.type === 'upsert')
+                    agents.set(event.rowKey, event.row);
+                else if (event.type === 'remove') {
+                    agents.delete(event.rowKey);
+                    attention.delete(event.rowKey);
+                }
+                pending = pending.then(() => projectSessionEnvelope(event, state)).then((events) => {
+                    for (const projected of events) {
+                        if (projected.type === 'reset') {
+                            attention.clear();
+                            for (const row of projected.agents)
+                                attention.set(row.rowKey, '');
+                            for (const item of projected.attention) {
+                                const row = projected.agents.find((agent) => agent.sessionId === item.sessionId);
+                                if (row)
+                                    attention.set(row.rowKey, JSON.stringify(item));
+                            }
+                        }
+                        else if (projected.type === 'attention.upsert')
+                            attention.set(projected.rowKey, JSON.stringify(projected.attention));
+                        else if (projected.type === 'attention.remove')
+                            attention.set(projected.rowKey, '');
+                        options.emit(projected);
+                    }
+                });
+            } });
+        await pending;
+    }
+    finally {
+        stopActivity();
+    }
+}
+function remoteFeedWatchCommand(os) {
+    const args = ['feed', 'watch', '--json', '--local'];
+    return remoteShellFor(os) === 'powershell'
+        ? buildWindowsAgentsCommand({ args })
+        : `bash -lc ${shellQuote(`agents ${args.map(shellQuote).join(' ')}`)}`;
+}
+export async function watchFleetFeed(options) {
+    const coordinator = new FeedWatchState();
+    const forward = (event) => {
+        const { v: _v, streamId: peerStreamId, sequence: peerSequence, ...payload } = event;
+        options.emit(coordinator.emit({ ...payload, peerStreamId, peerSequence }));
+    };
+    const local = watchLocalFeed({ scope: machineId(), signal: options.signal, emit: forward });
+    let devices;
+    try {
+        devices = await loadDevices();
+    }
+    catch {
+        await local;
+        return;
+    }
+    const self = machineId();
+    const peers = Object.values(devices).filter((device) => isDialableDevice(device) && normalizeHost(device.name) !== self && ['windows', 'linux', 'macos'].includes(device.platform));
+    const tasks = peers.map(async (device) => {
+        const scope = normalizeHost(device.name);
+        while (!options.signal.aborted) {
+            let target;
+            try {
+                target = sshTargetFor(device);
+            }
+            catch (error) {
+                options.emit(coordinator.emit({ type: 'scope', capturedAt: Date.now(), scope, status: 'unavailable', reason: String(error) }));
+                break;
+            }
+            const child = spawn('ssh', [...SSH_OPTS, ...controlOpts(), ...deviceIdentityArgs(device), target, remoteFeedWatchCommand(device.platform)], { stdio: ['ignore', 'pipe', 'ignore'] });
+            const stop = () => child.kill('SIGTERM');
+            options.signal.addEventListener('abort', stop, { once: true });
+            const reader = createInterface({ input: child.stdout });
+            reader.on('line', (line) => { try {
+                const event = JSON.parse(line);
+                if (event.v === 1)
+                    forward(event);
+            }
+            catch { /* protocol only */ } });
+            const code = await new Promise((resolve) => { child.once('error', () => resolve(null)); child.once('close', resolve); });
+            reader.close();
+            options.signal.removeEventListener('abort', stop);
+            if (options.signal.aborted)
+                break;
+            options.emit(coordinator.emit({ type: 'scope', capturedAt: Date.now(), scope, status: 'unavailable', reason: code == null ? 'ssh failed' : `ssh exited ${code}` }));
+            await new Promise((resolve) => { const timer = setTimeout(resolve, options.reconnectMs ?? 2_000); options.signal.addEventListener('abort', () => { clearTimeout(timer); resolve(); }, { once: true }); });
+        }
+    });
+    await Promise.all([local, ...tasks]);
+}

package/dist/lib/fleet/capture.js

@@ -58,6 +58,12 @@ export function captureFleet(prev, inputs) {
     if (prev?.discovery && Object.keys(prev.discovery).length > 0) {
         manifest.discovery = { ...prev.discovery };
     }
+    // Dismissals are operator state, not live state — a capture must never wipe
+    // them (fleet.ignored syncs; losing it re-suggests every dismissed node
+    // fleet-wide). Carry forward verbatim, same contract as `discovery`.
+    if (prev?.ignored && prev.ignored.length > 0) {
+        manifest.ignored = prev.ignored.map((e) => ({ ...e }));
+    }
     const bundles = inputs.secretsBundles ?? prev?.secrets?.bundles;
     if (bundles && bundles.length > 0)
         manifest.secrets = { bundles: [...bundles].sort() };

package/dist/lib/fleet/remote-login.js

@@ -33,7 +33,7 @@ import { planFleetTargets } from '../devices/fleet.js';
 import { assertValidSshTarget, shellQuote, sshExecAsync } from '../ssh-exec.js';
 import { machineId } from '../session/sync/config.js';
 import { ptyRequest } from '../pty-client.js';
-import { openUrl } from '../open-url.js';
+import { showUrl } from '../open-url.js';
 import { readAuthHealthCache, } from '../auth-health.js';
 import { FLEET_LOGIN_FLOWS, KEYCHAIN_BOUND_ON_MAC, } from './auth-sync.js';
 /**
@@ -500,8 +500,13 @@ export async function runFleetLogin(opts = {}) {
     if (!opts.json) {
         console.log(`Dashboard: ${dashUrl}`);
     }
-    if (opts.open !== false)
-        openUrl(dashUrl);
+    if (opts.open !== false) {
+        const shown = await showUrl(dashUrl);
+        if (shown.via === 'none') {
+            console.error('Could not open a browser — open this yourself:');
+            console.error(`  ${dashUrl}`);
+        }
+    }
     const driver = opts.driver ?? defaultPtyDriver();
     const remotable = pending.filter((p) => p.remotable);
     const driveOne = async (p) => {

package/dist/lib/fleet/types.d.ts

@@ -80,6 +80,23 @@ export interface FleetManifest {
      * machine's local device registry and is never committed.
      */
     discovery?: Record<string, 'approved' | 'ignored'>;
+    /**
+     * Tailnet node names the user dismissed from auto-discovery, with who
+     * dismissed each and when. Lives here rather than in a per-device doc because
+     * a dismissed node is deliberately NOT a device — it never enters the
+     * registry, so it has no per-device folder. Syncs fleet-wide with the rest of
+     * `agents.yaml`, so a dismissal on one box stops the suggestion on every box.
+     */
+    ignored?: IgnoredDeviceEntry[];
+}
+/** One dismissal record in {@link FleetManifest.ignored}. */
+export interface IgnoredDeviceEntry {
+    /** Tailscale node name the user dismissed. */
+    name: string;
+    /** ISO-8601 timestamp of the dismissal. */
+    ignoredAt: string;
+    /** machineId() of the box the dismissal was made on. */
+    ignoredOn: string;
 }
 /**
  * A device's desired state after merging defaults with its override and

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

@@ -28,6 +28,7 @@
  */
 import type { AgentId, Mode } from '../types.js';
 import type { JobConfig } from '../scheduling/routines.js';
+import type { ConfiguredDeviceRole } from '../device-config.js';
 /**
  * Context for the exec-time config-env pin (mapping A, exec.ts side). The caller
  * resolves the interactive/version facts once; the adapter only expresses the
@@ -42,6 +43,16 @@ export interface ExecConfigEnvCtx {
     versionHome: string | null;
     /** resolveInteractive(options) — computed once by the caller. */
     interactive: boolean;
+    /**
+     * The role marked on THIS machine (worker | personal | undefined), resolved
+     * once by the caller from selfConfiguredDeviceRole(). A `personal` device is
+     * the user's own interactive box: it holds a real per-version login and the
+     * credential decision MUST defer to it for EVERY run — interactive OR headless
+     * — never the worker-only setup-token (RUSH-2395). Injected as a plain value
+     * (not imported) to keep the adapter import-leaf. Absent/undefined is treated
+     * as non-personal (worker-equivalent).
+     */
+    deviceRole?: ConfiguredDeviceRole;
     /**
      * claude-account-token's resolveClaudeSetupToken, injected. The adapters MUST
      * stay import-leaf: claude-account-token pulls in the secrets stack, which

package/dist/lib/harness/adapters/claude.js

@@ -26,35 +26,49 @@ export const claudeAdapter = {
         }
         // The `auth` bundle's setup-token exists so a run with NO human present
         // authenticates without the Touch-ID-gated login item — usage probes,
-        // routines, dispatched runs (claude-account-token.ts). An interactive run
-        // has a human at the TTY, and their own per-version login is the credential
-        // they established and expect; overriding it made `/status` report
-        // `Auth token: CLAUDE_CODE_OAUTH_TOKEN` on a personal machine and took every
-        // hand-driven session off that login. macOS cannot cheaply confirm a home's
-        // login first (probing the Keychain raises an authorization sheet per
-        // installed version on the `agents run` hot path — agents.ts
-        // `isClaudeCredentialFileBlank`), so interactive simply defers to Claude
-        // Code, which prompts a present human to log in if the login is missing.
-        if (ctx.interactive) {
-            // Drop an INHERITED copy of OUR OWN setup-token: an interactive launch from
-            // inside a headless agent's shell inherits that agent's injected value via
-            // sanitizeProcessEnv(process.env) and would keep authenticating as it.
-            // Matched by VALUE, so a token the user exported deliberately is a different
-            // string and is left alone (#2383). This is NARROWER than the non-interactive
-            // path below, which overwrites-or-deletes unconditionally and never inspects
-            // the inherited value — a DIFFERENT account's inherited setup-token passing
-            // through this equality check is the adjacent hole RUSH-2360 leaves as
-            // follow-up (it does not silently run on a *shared, rotating* token, which is
-            // what caused the RUSH-1822 logout storm).
+        // routines, dispatched runs (claude-account-token.ts). It is a WORKER
+        // credential. Two kinds of run defer to the per-version login instead:
+        //
+        //   1. An interactive run: a human is at the TTY, and their per-version login
+        //      is the credential they established and expect. Overriding it made
+        //      `/status` report `Auth token: CLAUDE_CODE_OAUTH_TOKEN` on a personal
+        //      machine and took every hand-driven session off that login.
+        //   2. ANY run on a `personal` device — the user's own interactive box (zion),
+        //      marked `config.role: personal`. That box holds a real per-version login
+        //      and is the single origin of it, so every run there — interactive TUI OR
+        //      a headless one-shot like `agents run claude "fix the bug"` — MUST use
+        //      that login, not the setup-token. Gating on run mode ALONE
+        //      (resolveInteractive = "this opens a TUI", NOT "a human is present")
+        //      sent a headless run on the laptop onto the setup-token and hijacked the
+        //      login. Keying the credential on DEVICE ROLE is the fix — RUSH-2395.
+        //
+        // macOS cannot cheaply confirm a home's login first (probing the Keychain
+        // raises an authorization sheet per installed version on the `agents run` hot
+        // path — agents.ts `isClaudeCredentialFileBlank`), so this path defers to
+        // Claude Code, which reads its own ACL-trusted login item without a prompt and
+        // asks a present human to log in only if the login is missing.
+        const personalDevice = ctx.deviceRole === 'personal';
+        if (ctx.interactive || personalDevice) {
+            // Drop an INHERITED copy of OUR OWN setup-token: a launch from inside a
+            // headless agent's shell inherits that agent's injected value via
+            // sanitizeProcessEnv(process.env) and would keep authenticating as it,
+            // overriding the login this branch is protecting. Matched by VALUE, so a
+            // token the user exported deliberately is a different string and is left
+            // alone (#2383). This is NARROWER than the worker path below, which
+            // overwrites-or-deletes unconditionally and never inspects the inherited
+            // value — a DIFFERENT account's inherited setup-token passing through this
+            // equality check is the adjacent hole RUSH-2360 leaves as follow-up (it does
+            // not silently run on a *shared, rotating* token, which is what caused the
+            // RUSH-1822 logout storm).
             if (setupToken && result.CLAUDE_CODE_OAUTH_TOKEN === setupToken) {
                 delete result.CLAUDE_CODE_OAUTH_TOKEN;
             }
         }
         else {
-            // Non-interactive (routines, dispatched, provisioned box): mirror the routines
-            // path (`runner.ts:1017-1021`) UNCONDITIONALLY. Inject the per-account
-            // setup-token when one resolves — it replaces any ambient shared value
-            // inherited from the launcher. When NONE resolves, STRIP the ambient
+            // Headless run on a NON-personal device (worker, dispatched, provisioned
+            // box): mirror the routines path (`runner.ts`) UNCONDITIONALLY. Inject the
+            // per-account setup-token when one resolves — it replaces any ambient shared
+            // value inherited from the launcher. When NONE resolves, STRIP the ambient
             // CLAUDE_CODE_OAUTH_TOKEN so a run on a provisioned box can never silently
             // authenticate as the shared, rotating token an earlier version of this path
             // let through — the RUSH-1822 fleet-wide-logout hazard, tracked by RUSH-2360.

package/dist/lib/harness/adapters/codex.js

@@ -63,21 +63,19 @@ fi
 exec "$BINARY"${launchArgs} "$@"`;
     },
     execModeArgs(ctx) {
-        const policyMode = ctx.resolvedMode === 'plan' || ctx.resolvedMode === 'skip' ? ctx.resolvedMode : 'edit';
         const writableRoots = [
             ...codexEditWritableRoots(ctx.cwd),
             ...ctx.addDirs,
         ];
-        return codexPolicyArgs(policyMode, writableRoots);
+        return codexPolicyArgs(ctx.resolvedMode, writableRoots);
     },
     routineModeArgs(cmd, ctx) {
-        const policyMode = ctx.mode === 'plan' || ctx.mode === 'skip' ? ctx.mode : 'edit';
         const routineRoots = (ctx.config.allow?.dirs ?? []).map((dir) => {
             if (dir.startsWith('-')) {
                 throw new Error(`allow.dirs entries must not start with '-': ${JSON.stringify(dir)}`);
             }
             return dir.replace(/^~/, os.homedir());
         });
-        cmd.push(...codexPolicyArgs(policyMode, [...codexEditWritableRoots(), ...routineRoots]));
+        cmd.push(...codexPolicyArgs(ctx.mode, [...codexEditWritableRoots(), ...routineRoots]));
     },
 };

package/dist/lib/hooks/cache.js

@@ -275,6 +275,14 @@ def should_fire():
             if not tn or tn not in allowed:
                 return False
 
+    v = m.get("permission_mode")
+    if v is not None:
+        allowed = arr(v)
+        if allowed:
+            pm = inp.get("permission_mode") or inp.get("permissionMode")
+            if pm and pm not in allowed:
+                return False
+
     v = m.get("tool_args_match")
     if v is not None:
         ta = inp.get("tool_args")

package/dist/lib/hooks/match.d.ts

@@ -20,6 +20,9 @@ export interface HookInput {
     tool_name?: string;
     tool_args?: unknown;
     cwd?: string;
+    permission_mode?: string;
+    /** Grok-style camelCase spelling of permission_mode. */
+    permissionMode?: string;
 }
 export declare function isSafeHookRegex(source: string): boolean;
 /**

package/dist/lib/hooks/match.js

@@ -131,6 +131,31 @@ export function shouldFire(matches, input) {
                 return false;
         }
     }
+    if (matches.permission_mode !== undefined) {
+        const allowed = arrayOf(matches.permission_mode);
+        if (allowed.length > 0) {
+            // Fail-open on absence: only some harnesses (Claude Code) report the
+            // live mode. An input with no mode field passes; an explicit value not
+            // in the allowed list skips.
+            const mode = input.permission_mode || input.permissionMode;
+            if (mode && !allowed.includes(mode))
+                return false;
+        }
+    }
+    if (matches.permission_mode_not !== undefined) {
+        const denied = arrayOf(matches.permission_mode_not);
+        if (denied.length > 0) {
+            // The negative form exists because the positive one cannot express
+            // "everywhere except plan" without enumerating every other mode — and an
+            // enumeration silently stops firing the moment a harness adds or renames
+            // one, which for a guard means it quietly stops guarding. Naming the mode
+            // to skip keeps every unknown mode firing, so the failure direction is
+            // "ran unnecessarily", never "did not run".
+            const mode = input.permission_mode || input.permissionMode;
+            if (mode && denied.includes(mode))
+                return false;
+        }
+    }
     if (matches.tool_args_match !== undefined) {
         const serialized = typeof input.tool_args === 'string'
             ? input.tool_args

package/dist/lib/hosts/passthrough.js

@@ -28,6 +28,7 @@ import { resolveRemoteOsSync } from './remote-os.js';
 // 6–7× cheaper graph (RUSH-2374 proposal 2).
 import { machineId } from '../machine-id.js';
 import { isDeviceAuto, resolveDeviceAffinity } from '../smart-launch.js';
+import { isDeviceInteractive, resolveInteractiveDevice, interactiveUnsetError, } from '../devices/interactive-host.js';
 import { flagValue, hasHostRoutingFlag } from './routing-flag.js';
 import { loadDevices } from '../devices/registry.js';
 import { isSelfHost } from '../devices/self-host.js';
@@ -527,6 +528,21 @@ export async function maybeRunOnHost(command, allArgs, opts) {
         process.stderr.write(chalk.gray(`[agents] device=auto → ${plan.host}\n`));
         hostName = plan.host;
     }
+    // `interactive` is the second affinity sentinel: the box the human sits at
+    // (`interactive.host`). Resolved here, ahead of the isSelfHost check below, for
+    // the same reason `auto` is — a pin naming THIS machine must run locally rather
+    // than self-SSH. It never falls back to the local box when unset: rendering to
+    // a screen nobody is watching is the exact failure the sentinel prevents.
+    if (isDeviceInteractive(hostName)) {
+        const pinned = resolveInteractiveDevice();
+        if (!pinned) {
+            process.stderr.write(`${interactiveUnsetError()}\n`);
+            process.exitCode = 1;
+            return true;
+        }
+        process.stderr.write(chalk.gray(`[agents] device=interactive → ${pinned}\n`));
+        hostName = pinned;
+    }
     // Running against your own machine is just a local run — skip the SSH round-trip.
     // Match EVERY identity the box answers to (short id, loopback, tailscale
     // dnsName), not just machineId() — a `--device <self-dnsName>` used to slip past a

package/dist/lib/hosts/registry.js

@@ -27,6 +27,7 @@ import { resolveRemoteOsSync } from './remote-os.js';
 import { loadDevices } from '../devices/registry.js';
 import { resolveDeviceProfile } from '../devices/resolve-profile.js';
 import { isDeviceAuto, resolveDeviceAffinity } from '../smart-launch.js';
+import { isDeviceInteractive, resolveInteractiveDevice, interactiveUnsetError, } from '../devices/interactive-host.js';
 import { localMachineId } from '../session/origin-machine.js';
 // Re-export so existing importers (tests, commands) keep their path; the class
 // itself lives in types.ts so providers can throw it without a circular import.
@@ -161,6 +162,12 @@ export async function matchHost(name, opts = {}) {
     // returning nothing — callers that already special-case "target is this
     // machine" (teams add/create, the passthrough self-host check) then treat it as
     // local exactly as they would if the user had typed the local name.
+    if (isDeviceInteractive(name)) {
+        const pinned = resolveInteractiveDevice();
+        if (!pinned)
+            throw new Error(interactiveUnsetError());
+        name = pinned;
+    }
     if (isDeviceAuto(name)) {
         const plan = (opts.resolveAuto ?? (() => resolveDeviceAffinity({})))();
         const picked = plan.host ?? normalizeHost(localMachineId());

package/dist/lib/identity/client.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The ONE place agents-cli talks to its account backend (Phoenix ID).
+ *
+ * Why a seam at all: the removed Prix-coupled layer (RUSH-2581) had no single
+ * entry point — the backend URL was hardcoded in five files and the session
+ * token was re-read from `~/.rush/user.yaml` by seven separate functions, so
+ * re-pointing identity meant editing a dozen call sites and rewriting error
+ * strings scattered through the tree. This module is the correction: one base
+ * URL, one token reader, one HTTP funnel, one error type. Commands import from
+ * here and nothing else.
+ *
+ * The shape mirrors the seams this repo already proved elsewhere —
+ * `SyncBackend` (`lib/secrets/sync-backend.ts`) and `CloudProvider`
+ * (`lib/cloud/types.ts`) — so a second identity backend, if one is ever
+ * needed, is a swap here rather than a sweep across commands.
+ */
+/**
+ * Where the account backend lives. Config, never a literal at a call site.
+ *
+ * The default is the deployed Phoenix ID Worker. It is a `workers.dev` URL
+ * rather than a vanity hostname because no custom domain is attached yet — and
+ * a default naming an unregistered domain is worse than an ugly one: every
+ * `agents auth login` would fail DNS with nothing to point at.
+ */
+export declare const PHOENIX_ID_BASE: string;
+/** Our own session file. agents-cli never reads another product's credentials. */
+export declare function sessionFilePath(): string;
+export interface PhoenixSession {
+    access_token: string;
+    email?: string;
+    userId?: string;
+    /** Unix ms; absent means the server did not scope the token's lifetime. */
+    expires_at?: number;
+}
+export declare function readSession(): PhoenixSession | null;
+export declare function writeSession(session: PhoenixSession): void;
+export declare function clearSession(): void;
+/** An error carrying the server's status and message, so callers can branch on it. */
+export declare class PhoenixApiError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+interface RequestOptions {
+    body?: unknown;
+    /** Send the stored session token. Default true; the device-flow start does not. */
+    auth?: boolean;
+    /** Use this token instead of the stored one (mid-login, before the write). */
+    token?: string;
+    timeoutMs?: number;
+}
+/** The single HTTP funnel. Every request to the account backend goes through here. */
+export declare function phoenixRequest<T>(method: 'GET' | 'POST' | 'PATCH' | 'DELETE', route: string, opts?: RequestOptions): Promise<T>;
+export {};