@phnx-labs/agents-cli 1.20.74 → 1.20.76

package/dist/lib/devices/resolve-target.d.ts

@@ -1,4 +1,6 @@
-import { type DeviceProfile, type DeviceRegistry } from './registry.js';
+import { splitUserHost } from '../hosts/registry.js';
+import { type DeviceProfile } from './registry.js';
+export { splitUserHost };
 /** A dialable peer: the ssh target, the machine id used to tag its rows, a
  * display name, and the OS family that picks the remote shell dialect. */
 export interface ResolvedSshTarget {
@@ -7,35 +9,21 @@ export interface ResolvedSshTarget {
     name: string;
     os?: string;
 }
-/** Split a `user@host` / `host` token into its login user (if any) and host part. */
-export declare function splitUserHost(token: string): {
-    user?: string;
-    host: string;
-};
-/**
- * Resolve one `--host`/`--device` token to a concrete ssh target through the
- * registry. Registry hit → the device's real address + platform (so the machine
- * id, route, and OS all match the auto-discovery sweep), with any `user@`
- * overriding the login account. Miss → a literal `user@host` fallback, its OS
- * taken from the host overlay if enrolled. Returns undefined only when the token
- * fails the shared ssh-target injection guard.
- */
-export declare function resolveSshTarget(token: string, reg: DeviceRegistry): ResolvedSshTarget | undefined;
 /**
  * Resolve a target token to a full {@link DeviceProfile} for `agents ssh`. Same
- * grammar as {@link resolveSshTarget}, but returns the whole profile (auth,
- * shell, tailscale metadata) `buildSshInvocation` needs — not just a target
- * string. A registered `name` or `user@device` yields that profile (with the
- * login user overridden by any `user@`); an ad-hoc `user@host`/`host` literal
- * yields a synthesized key-auth profile. A bare unregistered alias (no `@`/dot)
- * returns undefined so the caller reports "Unknown device" rather than dialing a
- * literal — the strict behaviour the interactive wrapper has always had.
+ * grammar as the fan-out, but returns the whole profile (auth, shell, tailscale
+ * metadata) `buildSshInvocation` needs. A registered `name` / `user@device`
+ * yields that profile (login user overridden by any `user@`); an ad-hoc
+ * `user@host` / IP / FQDN literal yields a synthesized key-auth profile. A bare
+ * unregistered alias (no `@`/dot) — or an ssh_config-only alias, which `agents
+ * ssh` has never dialed — returns undefined so the caller reports "Unknown
+ * device" rather than dialing a literal.
  */
-export declare function resolveDeviceTarget(token: string, reg: DeviceRegistry): DeviceProfile | undefined;
+export declare function resolveDeviceTarget(token: string): Promise<DeviceProfile | undefined>;
 /**
- * Resolve an explicit `--host`/`--device` list to dialable targets, reading the
- * registry once. A token that fails the injection guard is skipped with a
- * stderr note (never fatal — one bad token must not blank the fan-out). Shared
- * by every cross-machine fan-out so they can never diverge onto two routes.
+ * Resolve an explicit `--host`/`--device` list to dialable targets. A token that
+ * fails the injection guard or names nothing reachable is skipped with a stderr
+ * note (never fatal — one bad token must not blank the fan-out). Shared by every
+ * cross-machine fan-out so they can never diverge onto two routes.
  */
 export declare function resolveExplicitTargets(hosts: string[]): Promise<ResolvedSshTarget[]>;

package/dist/lib/devices/resolve-target.js

@@ -1,86 +1,31 @@
 /**
- * The one place a `--host` / `--device` token becomes a real ssh target.
+ * Fan-out + `agents ssh` adapters over the single host/device resolver.
  *
- * A device and a host are the same thing addressed two ways, so resolution must
- * go through the device registry — the single source of truth. A token that
- * names a registered device dials that device's real address (its Tailscale
- * dnsName/ip + user, via `sshTargetFor`), *identical* to the auto-discovery
- * sweep and `agents ssh`. Before this module, the explicit `--host` fan-out
- * instead passed the bare token straight to `ssh`, so `--host yosemite-s0`
- * dialed whatever `~/.ssh/config`/LAN DNS resolved `yosemite-s0` to — a
- * different route than the sweep's `yosemite-s0.<tailnet>.ts.net`. That
- * divergence broke ControlMaster socket reuse (different target → different
- * `%C` hash → a cold dial every time) and could read a perfectly reachable box
- * as "unreachable" when only the non-Tailscale route was down.
+ * Every `--host` / `--device` token becomes a concrete target through one core,
+ * {@link matchHost} in ../hosts/registry.ts — the merged directory that reads the
+ * devices registry, the agents.yaml overlay, AND ssh_config (RUSH-1967). This
+ * module is only the two thin adapters the fan-out and interactive-ssh paths
+ * need on top of that core:
+ *   - {@link resolveExplicitTargets} — a token list → dialable `{target, machine,
+ *     name, os}` rows, so `sessions --host` / session bundles / remote agents-json
+ *     dial the exact same address (and machine id) `run --host` does.
+ *   - {@link resolveDeviceTarget} — a token → the full {@link DeviceProfile}
+ *     `agents ssh` needs (auth, shell, tailscale metadata), with the same
+ *     grammar; a bare unregistered alias returns undefined ("Unknown device").
  *
- * The grammar is uniform across the fleet: `mac-mini` (device name), and
- * `muqsit@mac-mini` (same device, login user overridden) both resolve through
- * the registry to the device's Tailscale route — the `user@` form no longer
- * short-circuits to a bare `ssh muqsit@mac-mini` (LAN DNS). A `user@host` that
- * matches no registered device falls back to a literal target so ad-hoc boxes
- * still work.
+ * The grammar is uniform across the fleet: `name`, `user@name` (same device,
+ * login user overridden), a tailnet FQDN, an ssh_config alias, and an ad-hoc
+ * `user@host` all resolve identically no matter which subcommand called.
  */
 import chalk from 'chalk';
-import { assertValidSshTarget } from '../ssh-exec.js';
+import { sshTargetFor } from '../hosts/types.js';
+import { matchHost, splitUserHost } from '../hosts/registry.js';
 import { normalizeHost } from '../machine-id.js';
 import { resolveRemoteOsSync } from '../hosts/remote-os.js';
-import { sshTargetFor } from './connect.js';
-import { loadDevices } from './registry.js';
-/** Split a `user@host` / `host` token into its login user (if any) and host part. */
-export function splitUserHost(token) {
-    const at = token.indexOf('@');
-    return at === -1 ? { host: token } : { user: token.slice(0, at), host: token.slice(at + 1) };
-}
-/**
- * Match a host part (the piece after any `user@`) to a registered device: exact
- * registry key first, then a normalized-host match so `yosemite-s0` and
- * `yosemite-s0.<tailnet>.ts.net` land on the same profile. The single source of
- * truth both `resolveSshTarget` (fan-out) and `resolveDeviceTarget` (`agents
- * ssh`) share, so a `user@device` can never resolve two different routes.
- */
-function matchDevice(host, reg) {
-    return reg[host] ?? Object.values(reg).find((d) => normalizeHost(d.name) === normalizeHost(host));
-}
-/**
- * Resolve one `--host`/`--device` token to a concrete ssh target through the
- * registry. Registry hit → the device's real address + platform (so the machine
- * id, route, and OS all match the auto-discovery sweep), with any `user@`
- * overriding the login account. Miss → a literal `user@host` fallback, its OS
- * taken from the host overlay if enrolled. Returns undefined only when the token
- * fails the shared ssh-target injection guard.
- */
-export function resolveSshTarget(token, reg) {
-    try {
-        assertValidSshTarget(token);
-    }
-    catch {
-        return undefined;
-    }
-    const { user, host } = splitUserHost(token);
-    // A device and a `user@device` are the same box; resolve the host part through
-    // the registry so both dial the Tailscale route, and let an explicit `user@`
-    // override only the login account.
-    const device = matchDevice(host, reg);
-    if (device) {
-        try {
-            const effective = user ? { ...device, user } : device;
-            return { target: sshTargetFor(effective), machine: normalizeHost(device.name), name: device.name, os: device.platform };
-        }
-        catch {
-            // Registered but has no address to dial — fall through to the literal token.
-        }
-    }
-    return { target: token, machine: normalizeHost(host), name: token, os: resolveRemoteOsSync(token) };
-}
+export { splitUserHost };
 /** Timestamps for a synthesized ad-hoc profile — never persisted, so a constant
  * keeps the value deterministic (and side-effect free) without reading the clock. */
 const SYNTH_TS = '1970-01-01T00:00:00.000Z';
-/** True when a token is clearly a network target (a `user@`, or a dotted/IPv6
- * host / IP) rather than a bare alias. A bare unknown word is a typo, so `agents
- * ssh foo` still says "Unknown device" instead of dialing a literal `foo`. */
-function looksLikeHostLiteral(token) {
-    return token.includes('@') || token.includes('.') || token.includes(':');
-}
 /** Synthesize a throwaway device profile for an ad-hoc `user@host` / `host`
  * literal so `agents ssh` can dial a box that was never registered. */
 function adHocDevice(token, host, user) {
@@ -97,49 +42,65 @@ function adHocDevice(token, host, user) {
     };
 }
 /**
- * Resolve a target token to a full {@link DeviceProfile} for `agents ssh`. Same
- * grammar as {@link resolveSshTarget}, but returns the whole profile (auth,
- * shell, tailscale metadata) `buildSshInvocation` needs — not just a target
- * string. A registered `name` or `user@device` yields that profile (with the
- * login user overridden by any `user@`); an ad-hoc `user@host`/`host` literal
- * yields a synthesized key-auth profile. A bare unregistered alias (no `@`/dot)
- * returns undefined so the caller reports "Unknown device" rather than dialing a
- * literal — the strict behaviour the interactive wrapper has always had.
+ * Resolve one token to a dialable {@link ResolvedSshTarget}, or undefined when it
+ * fails the injection guard or names nothing reachable. A registered device (or
+ * `user@device`) dials its live Tailscale route; an ssh_config-only alias dials
+ * by its bare name (ssh applies the stanza) — now visible to the fan-out too; an
+ * ad-hoc `user@host` dials the literal.
  */
-export function resolveDeviceTarget(token, reg) {
+async function toResolvedTarget(token) {
+    const host = await matchHost(token);
+    if (!host)
+        return undefined;
+    let target;
     try {
-        assertValidSshTarget(token);
+        target = sshTargetFor(host);
     }
     catch {
+        return undefined; // matched a device/host with no address to dial
+    }
+    const hostPart = host.device ? host.device.name : splitUserHost(host.name).host;
+    const name = host.device ? host.device.name : host.name;
+    return { target, machine: normalizeHost(hostPart), name, os: host.os ?? resolveRemoteOsSync(name) };
+}
+/**
+ * Resolve a target token to a full {@link DeviceProfile} for `agents ssh`. Same
+ * grammar as the fan-out, but returns the whole profile (auth, shell, tailscale
+ * metadata) `buildSshInvocation` needs. A registered `name` / `user@device`
+ * yields that profile (login user overridden by any `user@`); an ad-hoc
+ * `user@host` / IP / FQDN literal yields a synthesized key-auth profile. A bare
+ * unregistered alias (no `@`/dot) — or an ssh_config-only alias, which `agents
+ * ssh` has never dialed — returns undefined so the caller reports "Unknown
+ * device" rather than dialing a literal.
+ */
+export async function resolveDeviceTarget(token) {
+    const host = await matchHost(token, { allowBareLiteral: true });
+    if (!host)
         return undefined;
+    if (host.device) {
+        const { user } = splitUserHost(token);
+        return user ? { ...host.device, user } : host.device;
     }
-    const { user, host } = splitUserHost(token);
-    const device = matchDevice(host, reg);
-    if (device)
-        return user ? { ...device, user } : device;
-    if (looksLikeHostLiteral(token))
-        return adHocDevice(token, host, user);
+    if (host.adhoc) {
+        const { user, host: hostPart } = splitUserHost(token);
+        return adHocDevice(token, hostPart, user);
+    }
+    // An overlay / ssh_config-only match is not a device — `agents ssh` stays
+    // devices-and-literals only, so report it as unknown.
     return undefined;
 }
 /**
- * Resolve an explicit `--host`/`--device` list to dialable targets, reading the
- * registry once. A token that fails the injection guard is skipped with a
- * stderr note (never fatal — one bad token must not blank the fan-out). Shared
- * by every cross-machine fan-out so they can never diverge onto two routes.
+ * Resolve an explicit `--host`/`--device` list to dialable targets. A token that
+ * fails the injection guard or names nothing reachable is skipped with a stderr
+ * note (never fatal — one bad token must not blank the fan-out). Shared by every
+ * cross-machine fan-out so they can never diverge onto two routes.
  */
 export async function resolveExplicitTargets(hosts) {
-    let reg;
-    try {
-        reg = await loadDevices();
-    }
-    catch {
-        reg = {};
-    }
     const out = [];
     for (const h of hosts) {
-        const resolved = resolveSshTarget(h, reg);
+        const resolved = await toResolvedTarget(h);
         if (!resolved) {
-            process.stderr.write(chalk.gray(`  ${h}: not a valid ssh target — skipped\n`));
+            process.stderr.write(chalk.gray(`  ${h}: not a resolvable ssh target — skipped\n`));
             continue;
         }
         out.push(resolved);

package/dist/lib/devices/sync.d.ts

@@ -45,6 +45,24 @@ export interface DeviceSyncResult {
     /** Populated when ok is false: why discovery was skipped. */
     reason?: string;
 }
+/**
+ * The nodes automatic discovery is allowed to see: sharee nodes (shared INTO
+ * the tailnet by another user, e.g. a funnel ingress relay) are not the
+ * operator's machines, so they must never be bootstrap-registered nor surfaced
+ * as pending. Explicit paths (`devices register <name>`, `devices add`, the
+ * `fleet:` manifest bootstrap) are deliberate user actions and stay unfiltered.
+ * Pure so the policy is unit-testable without a tailnet.
+ */
+export declare function discoverableNodes(nodes: TailscaleNode[]): TailscaleNode[];
+/**
+ * Default checked-state for a node in the interactive sync picker. Pressing
+ * Enter registers every checked node, so "checked" must mean "auto-sync would
+ * register this": not dismissed, and not a sharee node — unless the user
+ * already deliberately registered that sharee node, in which case Enter must
+ * keep the fleet as-is. Pure so the default matrix is unit-testable without a
+ * prompt.
+ */
+export declare function defaultPickerChecked(node: TailscaleNode, registered: Set<string>, ignored: Set<string>): boolean;
 /**
  * Node names present on the tailnet but neither already in the registry nor on
  * the ignore-list — i.e. genuinely new devices worth surfacing. Pure so the

package/dist/lib/devices/sync.js

@@ -59,6 +59,28 @@ export function withDefaultUser(input, prevUser, localUser) {
         return input;
     return { ...input, user: localUser };
 }
+/**
+ * The nodes automatic discovery is allowed to see: sharee nodes (shared INTO
+ * the tailnet by another user, e.g. a funnel ingress relay) are not the
+ * operator's machines, so they must never be bootstrap-registered nor surfaced
+ * as pending. Explicit paths (`devices register <name>`, `devices add`, the
+ * `fleet:` manifest bootstrap) are deliberate user actions and stay unfiltered.
+ * Pure so the policy is unit-testable without a tailnet.
+ */
+export function discoverableNodes(nodes) {
+    return nodes.filter((n) => !n.sharee);
+}
+/**
+ * Default checked-state for a node in the interactive sync picker. Pressing
+ * Enter registers every checked node, so "checked" must mean "auto-sync would
+ * register this": not dismissed, and not a sharee node — unless the user
+ * already deliberately registered that sharee node, in which case Enter must
+ * keep the fleet as-is. Pure so the default matrix is unit-testable without a
+ * prompt.
+ */
+export function defaultPickerChecked(node, registered, ignored) {
+    return !ignored.has(node.name) && (!node.sharee || registered.has(node.name));
+}
 /**
  * Node names present on the tailnet but neither already in the registry nor on
  * the ignore-list — i.e. genuinely new devices worth surfacing. Pure so the
@@ -101,7 +123,7 @@ export async function runDeviceSync(opts = {}) {
     // the same host at once) would otherwise abort the whole `agents sync`. The
     // whole body is inside the guard so the "never a sync failure" promise holds.
     try {
-        const nodes = parseTailscaleStatus(tailscaleStatusJson());
+        const nodes = discoverableNodes(parseTailscaleStatus(tailscaleStatusJson()));
         const [registeredBefore, ignored] = await Promise.all([loadDevices(), loadIgnored()]);
         const registered = new Set(Object.keys(registeredBefore));
         const pendingNames = computePendingDevices(nodes, registered, ignored);

package/dist/lib/devices/tailscale.d.ts

@@ -9,6 +9,9 @@ export interface TailscaleNode {
     direct: boolean;
     relay?: string;
     lastSeen?: string;
+    /** True for a node another user shared INTO this tailnet — not the operator's
+     * own machine, so discovery must never auto-register or suggest it. */
+    sharee: boolean;
 }
 /**
  * Slugify a raw Tailscale HostName into a valid logical device name (ssh alias

package/dist/lib/devices/tailscale.js

@@ -69,6 +69,7 @@ function toNode(raw) {
         direct,
         relay: raw.Relay || undefined,
         lastSeen: raw.LastSeen,
+        sharee: Boolean(raw.ShareeNode),
     };
 }
 /**

package/dist/lib/events.d.ts

@@ -12,7 +12,7 @@
  * - Performance tracking: withTiming() wrapper for any async function
  */
 export type EventLevel = 'audit' | 'warn' | 'info' | 'debug';
-export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'secrets.get' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'cloud.cancel' | 'cloud.message' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'teams.disband' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'mcp.add' | 'mcp.remove' | 'mcp.register' | 'resource.sync' | 'rotation.resolved' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created' | 'file.edited' | 'error' | 'warn' | 'info' | 'debug';
+export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'secrets.get' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'cloud.cancel' | 'cloud.message' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'teams.disband' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'mcp.add' | 'mcp.remove' | 'mcp.register' | 'resource.sync' | 'rotation.resolved' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created' | 'status.posted' | 'file.edited' | 'error' | 'warn' | 'info' | 'debug';
 export declare function levelFor(event: EventType): EventLevel;
 export interface EventMeta {
     ts: string;

package/dist/lib/exec.d.ts

@@ -144,6 +144,15 @@ export interface ExecOptions {
      * (output is mirrored to the parent's stdout exactly like stdio:'inherit').
      */
     captureStdoutTail?: boolean;
+    /**
+     * Print the run's resolved session id to stdout as a one-line sentinel once the
+     * child exits (see hosts/session-marker.ts). Set by the `--host` dispatch so the
+     * LAUNCHER can relate the remote-created session back to itself — Claude's id is
+     * forced up front, but every other agent coins its own id on the remote box, and
+     * this marker is how that id rides the followed log home. Headless-only and inert
+     * for interactive runs (no combined log to parse).
+     */
+    emitSessionId?: boolean;
     /**
      * Escape hatch for the interactive tmux spawn-wrap (see shouldWrapInTmux):
      * when true, spawn the agent directly instead of inside a shared-socket tmux
@@ -339,6 +348,63 @@ export declare const BUDGET_KILL_EXIT_CODE = 7;
 export declare const RATE_LIMIT_PATTERNS: RegExp[];
 /** Return true if the text contains any known rate-limit or overload indicator. */
 export declare function detectRateLimit(text: string): boolean;
+/**
+ * Patterns that indicate an authentication failure — the agent is logged out,
+ * its token was revoked, or the session expired. These are the user-visible
+ * strings a logged-out agent surfaces (observed across the routine-run corpus).
+ * Unlike a rate limit, an auth failure is NOT self-healing by failover — every
+ * chain entry on the same account fails identically — so it is classified
+ * separately and never triggers a fallback attempt.
+ *
+ * The bare `401` is deliberately paired with an auth keyword: a plain "401" can
+ * appear in legitimate output (an HTTP-status table, a log line), so it only
+ * counts when it co-occurs with OAuth/authentication/credentials/Unauthorized.
+ */
+export declare const AUTH_FAILURE_PATTERNS: RegExp[];
+/**
+ * Return true if the text contains any known authentication-failure indicator.
+ * Agent-agnostic: matches the user-visible error string wherever it surfaces
+ * (stdout tail, a captured error message, a plain-text agent's output).
+ */
+export declare function detectAuthFailure(text: string): boolean;
+/**
+ * Return true if a stream-json log carries the structural markers of an auth
+ * failure. This is the authoritative signal for Claude: a logged-out run emits
+ *   {"type":"system","subtype":"api_retry","error":"authentication_failed",…}
+ *   {"type":"assistant",…,"error":"authentication_failed"}
+ *   {"type":"result","is_error":true,"result":"Failed to authenticate…"}
+ * Note `terminal_reason` is "completed" on such a run, so exit-code / terminal-
+ * reason logic can never catch it — the `error:"authentication_failed"` marker
+ * and the `result`+`is_error` text are the reliable signals.
+ *
+ * Gated on the Claude stream-json shape; other agents don't emit these fields,
+ * so callers pass their agent and this returns false for non-claude.
+ */
+export declare function detectAuthFailureEvent(logText: string, agent: AgentId): boolean;
+/**
+ * Return the first human-readable auth-failure phrase found in the text, for use
+ * as a stable, short run `errorMessage` reason. Falls back to null when the only
+ * signal was the structural `error:"authentication_failed"` marker with no
+ * user-visible string.
+ */
+export declare function authFailureReason(text: string): string | null;
+/**
+ * Decide whether a run's stream-json log is an authentication failure. The
+ * single source of truth for both the foreground and detached run paths.
+ *
+ * The structural marker (`detectAuthFailureEvent`, gated on `is_error:true`) is
+ * authoritative and safe on ANY exit — it catches a logged-out Claude that exits
+ * 0 (its `result` event carries `is_error:true` while `terminal_reason` is
+ * "completed"). The raw user-visible string (`detectAuthFailure`) is only
+ * consulted when the process actually FAILED, as a fallback for a run that died
+ * mid-stream before emitting a `result` event. That gate is what prevents a
+ * genuinely-completed run whose output merely *mentions* an auth phrase (e.g. a
+ * routine documenting a login flow) from being misclassified and having its
+ * legitimate report suppressed.
+ */
+export declare function isAuthFailureFromLog(logText: string, agent: AgentId, opts: {
+    processFailed: boolean;
+}): boolean;
 /** An agent (with optional pinned version) in a fallback chain. */
 export interface FallbackEntry {
     agent: AgentId;