@phnx-labs/agents-cli 1.21.3 → 1.22.1

package/dist/lib/app-bundle-install.js

@@ -0,0 +1,94 @@
+/**
+ * Atomic, serialized install of a macOS `.app` bundle to a stable user path.
+ *
+ * Shared by the two helpers agents-cli installs on darwin — the secrets keychain
+ * helper (`lib/secrets/install-helper.ts`) and the menu-bar helper
+ * (`lib/menubar/install-menubar.ts`) — both of which are (re)installed on the hot
+ * path of ordinary `agents` invocations. Both previously did a non-atomic
+ * `rm -rf dest` + `cp -R src dest` straight onto the live bundle. That copy takes
+ * long enough that a concurrent reader (Gatekeeper, or an exec of the bundle) sees
+ * a half-written `.app` — a truncated Mach-O / mismatched `_CodeSignature` hash —
+ * which macOS reports as **"is damaged and can't be opened."** On a busy box dozens
+ * of concurrent invocations raced the same path, so the dialog fired intermittently.
+ *
+ * {@link copyAppBundle} stages the copy in a sibling directory and swaps it into
+ * place with renames, so a reader sees either the old or the new complete bundle,
+ * never a half-written one — the only moment `dest` is briefly absent is the
+ * sub-millisecond gap between the two renames (vs the seconds-long `cp`), and a
+ * failed copy never touches the live bundle. {@link withInstallLock} serializes concurrent
+ * installers (via the shared `withFileLock`) so a burst of invocations installs
+ * once instead of stampeding.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { spawnSync } from 'child_process';
+import { withFileLock, ensureLockTarget } from './fs-atomic.js';
+// A helper `cp -R` under load can take a few seconds; the lock must outlast it so
+// a peer never treats a live installer as crashed and interleaves a second swap.
+// (fs-atomic's 5s default is tuned for sub-second read-modify-writes.)
+const INSTALL_LOCK_STALE_MS = 60_000;
+const INSTALL_LOCK_ACQUIRE_TIMEOUT_MS = 60_000;
+/**
+ * Copy an `.app` bundle to `dest` atomically. Stages into a sibling dir, then
+ * swaps with renames — the window where `dest` is absent shrinks from the
+ * seconds-long `cp` to a single microsecond rename, and a failed copy leaves the
+ * existing bundle untouched. Serialize concurrent callers with {@link withInstallLock}
+ * so the two-step swap never races another swap.
+ */
+export function copyAppBundle(src, dest, io = {}) {
+    const rename = io.renameSync ?? fs.renameSync;
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    const staging = `${dest}.installing.${process.pid}`;
+    const backup = `${dest}.replaced.${process.pid}`;
+    fs.rmSync(staging, { recursive: true, force: true });
+    fs.rmSync(backup, { recursive: true, force: true });
+    // `cp -R` preserves the bundle's signature, symlinks, and resource forks;
+    // `fs.cpSync({recursive:true})` has historically mishandled xattrs on `.app`
+    // bundles, breaking codesign.
+    const r = spawnSync('cp', ['-R', src, staging], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8' });
+    if (r.status !== 0) {
+        fs.rmSync(staging, { recursive: true, force: true });
+        const msg = (r.stderr || r.stdout || '').toString().trim();
+        throw new Error(`Failed to copy ${src} -> ${staging}: ${msg || 'unknown error'}`);
+    }
+    // rename(2) cannot replace a non-empty directory, so move the current bundle
+    // aside, then move staging into place. If the second rename fails, restore the
+    // backup so `dest` is never left missing.
+    try {
+        if (fs.existsSync(dest))
+            rename(dest, backup);
+        rename(staging, dest);
+    }
+    catch (err) {
+        if (!fs.existsSync(dest) && fs.existsSync(backup)) {
+            try {
+                rename(backup, dest);
+            }
+            catch {
+                /* best-effort restore */
+            }
+        }
+        fs.rmSync(staging, { recursive: true, force: true });
+        throw new Error(`Failed to install ${src} -> ${dest}: ${err.message}`);
+    }
+    fs.rmSync(backup, { recursive: true, force: true });
+}
+/**
+ * Serialize installs across the many concurrent `agents` invocations that pass
+ * through the helper-install path, so a burst copies once instead of stampeding
+ * the atomic swap. Locks a sentinel file beside the bundle (the bundle itself may
+ * not exist yet on first install) via the shared {@link withFileLock}.
+ */
+export function withInstallLock(dest, fn) {
+    const lockTarget = `${dest}.install-lock`;
+    ensureLockTarget(lockTarget);
+    // Pass proper-lockfile's `heartbeat` straight through: the install body is a
+    // fully SYNCHRONOUS chain of blocking `spawnSync`s (`cp -R`, then codesign /
+    // spctl), so the event loop never turns and proper-lockfile's own async mtime
+    // refresh can't fire. Callers invoke heartbeat() between those steps to keep a
+    // long hold from ageing past staleMs and being broken by a contending peer.
+    withFileLock(lockTarget, (heartbeat) => fn(heartbeat), {
+        staleMs: INSTALL_LOCK_STALE_MS,
+        acquireTimeoutMs: INSTALL_LOCK_ACQUIRE_TIMEOUT_MS,
+    });
+}

package/dist/lib/daemon.d.ts

@@ -43,7 +43,11 @@ export declare function writeHeartbeat(pid?: number): void;
 export declare function readHeartbeat(): DaemonHeartbeat | null;
 export declare function removeHeartbeat(): void;
 export declare function isDaemonWedged(): boolean;
-/** Check if the daemon process is alive by sending signal 0 to the stored PID. */
+/**
+ * Check whether a daemon is alive — via the pid file, or a fresh heartbeat when
+ * the pid file has been lost (see resolveLiveDaemonPid). Heals the pid file as a
+ * side effect so a subsequent read is consistent.
+ */
 export declare function isDaemonRunning(): boolean;
 /**
  * Single-instance claim for the daemon foreground entrypoint.

package/dist/lib/daemon.js

@@ -172,6 +172,16 @@ export function removeHeartbeat() {
     }
     catch { /* already removed */ }
 }
+/**
+ * A heartbeat is "fresh" when its last tick falls inside the wedge window — the
+ * same threshold isDaemonWedged() uses to decide a still-present daemon has gone
+ * unresponsive. A fresh heartbeat whose pid is alive is proof of a live, ticking
+ * daemon even when the pid file has been lost.
+ */
+function isHeartbeatFresh(hb) {
+    const elapsed = Date.now() - Date.parse(hb.lastTick);
+    return elapsed <= WEDGE_THRESHOLD_TICKS * MONITOR_TICK_MS;
+}
 export function isDaemonWedged() {
     const pid = readDaemonPid();
     if (!pid)
@@ -183,22 +193,49 @@ export function isDaemonWedged() {
         return false;
     if (hb.pid !== pid)
         return false;
-    const elapsed = Date.now() - Date.parse(hb.lastTick);
-    return elapsed > WEDGE_THRESHOLD_TICKS * MONITOR_TICK_MS;
+    return !isHeartbeatFresh(hb);
 }
 /** How long stopDaemon waits for a SIGTERMed daemon to exit before escalating. */
 const STOP_GRACE_MS = 5000;
 /** How long it waits after the hard tree-kill before giving up. */
 const STOP_KILL_GRACE_MS = 2000;
-/** Check if the daemon process is alive by sending signal 0 to the stored PID. */
-export function isDaemonRunning() {
+/**
+ * Resolve the PID of the live daemon, tolerant of a pid-file/heartbeat desync.
+ *
+ * The daemon writes the pid file once (on claim/start) but rewrites the
+ * heartbeat every tick. If the pid file is lost while the daemon keeps ticking
+ * — e.g. an earlier isDaemonRunning() found a stale/reused/dead pid and cleared
+ * the file, or it was removed out from under a live daemon — the pid file reads
+ * empty even though a daemon is genuinely alive and firing jobs. Reading only
+ * the pid file then reports "stopped" for a running scheduler, and (worse) lets
+ * claimDaemonInstance() start a SECOND daemon that double-fires every routine.
+ *
+ * So: trust the pid file when its pid is alive; otherwise trust a FRESH
+ * heartbeat whose pid is alive, and re-adopt the pid file so the desync heals.
+ * Returns null only when neither points at a live process (clearing a stale pid
+ * file on the way out).
+ */
+function resolveLiveDaemonPid() {
     const pid = readDaemonPid();
-    if (!pid)
-        return false;
-    if (isAlive(pid))
-        return true;
-    removeDaemonPid();
-    return false;
+    if (pid !== null && isAlive(pid))
+        return pid;
+    const hb = readHeartbeat();
+    if (hb && isAlive(hb.pid) && isHeartbeatFresh(hb)) {
+        if (pid !== hb.pid)
+            writeDaemonPid(hb.pid); // heal the pid-file/heartbeat desync
+        return hb.pid;
+    }
+    if (pid !== null)
+        removeDaemonPid();
+    return null;
+}
+/**
+ * Check whether a daemon is alive — via the pid file, or a fresh heartbeat when
+ * the pid file has been lost (see resolveLiveDaemonPid). Heals the pid file as a
+ * side effect so a subsequent read is consistent.
+ */
+export function isDaemonRunning() {
+    return resolveLiveDaemonPid() !== null;
 }
 /**
  * Single-instance claim for the daemon foreground entrypoint.
@@ -217,16 +254,28 @@ export function isDaemonRunning() {
  */
 export function claimDaemonInstance() {
     const release = acquireStartLock();
+    // acquireStartLock() returns null only when another __daemon-run currently
+    // holds the O_EXCL lock — a dead holder's lock is reclaimed and retried inside
+    // acquireStartLock, so null means a *live* claimer is mid-claim. Bail rather
+    // than run the read-decide-write unlocked: otherwise two first-start processes
+    // could each see no pid file (before either writes one) and both claim,
+    // running the concurrent JobScheduler this guard exists to prevent.
+    if (!release)
+        return false;
     try {
-        const existing = readDaemonPid();
-        if (existing !== null && existing !== process.pid && isAlive(existing)) {
-            return false; // another live daemon already owns the pid file
+        // resolveLiveDaemonPid() also consults a fresh heartbeat, so a live daemon
+        // whose pid file was lost still blocks a second claim — otherwise a missing
+        // pid file would let this instance start a concurrent JobScheduler and
+        // double-fire every routine.
+        const existing = resolveLiveDaemonPid();
+        if (existing !== null && existing !== process.pid) {
+            return false; // another live daemon already owns the instance
         }
         writeDaemonPid(process.pid);
         return true;
     }
     finally {
-        release?.();
+        release();
     }
 }
 /**

package/dist/lib/devices/doctor-findings.js

@@ -304,8 +304,12 @@ export function buildLocalFindings(input) {
             }
         }
         if (neverSynced) {
-            // Everything is "missing" because it was never synced — one line, and a
-            // CRITICAL one: nothing this version declares is actually installed.
+            // Everything is "missing" because it was never synced — collapse to ONE
+            // line. A never-synced version is almost always an old/unused install (you
+            // don't run a version you never synced), so this is a WARNING, not a "needs
+            // you now" critical: it isn't hurting anything until you actually launch it.
+            // The real criticals are a logged-out account or a hook/plugin missing from
+            // a version you DO keep synced (the `else` branch below).
             const total = missingHooks.length + missingPlugins.length + missingOther.length;
             if (total > 0) {
                 const breakdown = [
@@ -313,7 +317,7 @@ export function buildLocalFindings(input) {
                     missingPlugins.length ? `${missingPlugins.length} plugin${missingPlugins.length === 1 ? '' : 's'}` : '',
                 ].filter(Boolean).join(', ');
                 out.push(finding({
-                    severity: 'critical', kind: 'never-synced', device, agent, version,
+                    severity: 'warning', kind: 'never-synced', device, agent, version,
                     message: `never synced — ${total} resource${total === 1 ? '' : 's'}${breakdown ? ` (incl. ${breakdown})` : ''} not installed`,
                 }));
             }
@@ -464,7 +468,11 @@ function duplicateHookFindings(device, dups) {
                 `${versions.length} version${versions.length === 1 ? '' : 's'} ` +
                 `(incl. ${group.slice(0, 2).map((d) => `'${d.name}'`).join(', ')}) — ${authority}`;
         out.push({
-            severity: drift ? 'critical' : 'warning',
+            // A hook that DIFFERS across versions is still installed and firing — it's
+            // stale/sync drift, not a missing hook. Resolvable by one sync; a WARNING,
+            // not a "needs you now" critical. (A genuinely MISSING hook stays critical
+            // via the missing-hook path.)
+            severity: 'warning',
             kind: drift ? 'duplicate-hook-drift' : 'duplicate-hook',
             device, agent, versions, message,
             remediation: `agents sync ${agent}@all --yes`,

package/dist/lib/devices/doctor-overview-cache.d.ts

@@ -0,0 +1,45 @@
+/** Serve a cached snapshot without recomputing while it is younger than this. */
+export declare const DOCTOR_OVERVIEW_FRESH_MS = 90000;
+/** Injectable IO + clock so tests exercise the real fs at a temp dir, no mocks. */
+export interface DoctorOverviewCacheDeps {
+    /** Cache directory (default: the real `~/.agents/.cache`). */
+    dir?: string;
+    /** Clock (default: {@link Date.now}). */
+    now?: () => number;
+}
+/** Read the last snapshot (best-effort; missing/corrupt/wrong-version → null). */
+export declare function readDoctorOverviewCache(deps?: DoctorOverviewCacheDeps): {
+    fetchedAt: number;
+    payload: unknown;
+} | null;
+/** Persist a fresh overview payload (best-effort; tmp+rename so reads are atomic). */
+export declare function writeDoctorOverviewCache(payload: unknown, deps?: DoctorOverviewCacheDeps): void;
+/**
+ * Result of {@link enterDoctorOverviewGate}.
+ *  - `cached` non-null → the caller MUST print this string and return; no compute.
+ *  - `cached` null     → the caller holds the singleflight lock: compute the
+ *    overview, call {@link writeDoctorOverviewCache}, and invoke `release()` on
+ *    the way out. Call `release()` in a `finally` so a compute that throws still
+ *    frees the lock promptly (idempotent).
+ */
+export interface OverviewGate {
+    cached: string | null;
+    release?: () => void;
+}
+/**
+ * Enter the doctor-overview singleflight gate. Returns a cached string to print,
+ * or a lock token telling the caller to compute (and then write + release).
+ *
+ * Contract:
+ *  - Fresh snapshot present (and not `forceRefresh`) → `{ cached }`, no lock.
+ *  - Otherwise exactly one caller holds the lock and gets `{ cached: null,
+ *    release }`; everyone else blocks on the lock, then (on acquiring it)
+ *    double-checks and serves the winner's fresh write — or, if the winner runs
+ *    past the wait budget, serves the last snapshot — rather than recomputing.
+ *  - Never throws: any IO/lock failure degrades to a compute token or a served
+ *    snapshot.
+ */
+export declare function enterDoctorOverviewGate(opts?: {
+    forceRefresh?: boolean;
+    freshMs?: number;
+}, deps?: DoctorOverviewCacheDeps): Promise<OverviewGate>;

package/dist/lib/devices/doctor-overview-cache.js

@@ -0,0 +1,168 @@
+/**
+ * Singleflight + short-TTL disk cache for the `agents doctor --json` OVERVIEW
+ * payload (the bare, no-target form the menu-bar helper and other pollers read).
+ *
+ * Why this exists (RUSH-2153): the bare `doctor --json` overview is expensive —
+ * it probes every host CLI, spawns every installed agent CLI for its sign-in,
+ * and diffs every agent×version against its source. On an idle box that is a few
+ * seconds; on a loaded one it is minutes. The menu-bar helper polls it on a 60s
+ * timer with a per-*process* in-flight guard, so nothing coalesces ACROSS
+ * processes: a helper relaunch (or any second poller) each launches its own
+ * live compute, and a helper killed mid-run orphans its `doctor --json` child,
+ * which keeps spinning. In steady state this stacked to dozens of concurrent
+ * `doctor --json` processes pinning ~14 cores and driving load to ~300.
+ *
+ * The fix mirrors the {@link readStatsCache}/`writeStatsCache` mirror-file
+ * convention: reads are cache-first, and when a live compute IS needed exactly
+ * ONE runs at a time. The singleflight is the shared `proper-lockfile` lock (via
+ * `ensureLockTarget` + `lockfile.lock`) — the SAME battle-tested lock the rest of
+ * the CLI uses (fs-atomic.ts) — which owns two things a hand-rolled lock got
+ * wrong: (1) it auto-refreshes the lock's mtime on a timer while held, so a live
+ * computer whose compute runs for minutes is never mistaken for a crashed one
+ * and stolen; (2) `release()` only ever releases the lock THIS caller acquired,
+ * so a slow computer can't delete a successor's lock. Waiters block on the lock
+ * up to a bounded budget, then serve the last snapshot rather than pile on.
+ *
+ * The cache write is tmp+rename so a concurrent reader never sees a partial file.
+ * All IO is best-effort: a failure degrades to a live compute, never a throw.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import lockfile from 'proper-lockfile';
+import { getCacheDir } from '../state.js';
+import { ensureLockTarget } from '../fs-atomic.js';
+const CACHE_FILE = '.doctor-overview.json';
+const LOCK_TARGET_FILE = '.doctor-overview.lock-target';
+/** Serve a cached snapshot without recomputing while it is younger than this. */
+export const DOCTOR_OVERVIEW_FRESH_MS = 90_000;
+/**
+ * A held lock older than this is treated as a crashed computer and broken. The
+ * lock's mtime is auto-refreshed by proper-lockfile every `stale/2` while a live
+ * computer holds it (the event loop turns during the compute's `await`ed
+ * subprocess spawns), so this only ever breaks a genuinely dead holder.
+ */
+const LOCK_STALE_MS = 60_000;
+/**
+ * How long a waiter blocks on the lock before giving up and serving the last
+ * snapshot. Sized to comfortably exceed a slow (multi-second-to-minutes) compute
+ * so a waiter normally gets the winner's fresh write; capped so a truly wedged
+ * holder never hangs the CLI (it serves stale instead).
+ */
+const LOCK_RETRIES = { retries: 240, factor: 1, minTimeout: 500, maxTimeout: 500 };
+function cachePath(dir) {
+    return path.join(dir, CACHE_FILE);
+}
+/** Read the last snapshot (best-effort; missing/corrupt/wrong-version → null). */
+export function readDoctorOverviewCache(deps = {}) {
+    const dir = deps.dir ?? getCacheDir();
+    try {
+        const parsed = JSON.parse(fs.readFileSync(cachePath(dir), 'utf-8'));
+        if (parsed && parsed.version === 1 && typeof parsed.fetchedAt === 'number') {
+            return { fetchedAt: parsed.fetchedAt, payload: parsed.payload };
+        }
+    }
+    catch {
+        // missing or corrupt — treat as no snapshot
+    }
+    return null;
+}
+/** Persist a fresh overview payload (best-effort; tmp+rename so reads are atomic). */
+export function writeDoctorOverviewCache(payload, deps = {}) {
+    const dir = deps.dir ?? getCacheDir();
+    const now = deps.now ?? Date.now;
+    try {
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        const body = { version: 1, fetchedAt: now(), payload };
+        const tmp = `${cachePath(dir)}.tmp.${process.pid}`;
+        fs.writeFileSync(tmp, JSON.stringify(body, null, 2));
+        fs.renameSync(tmp, cachePath(dir));
+    }
+    catch {
+        // best-effort; a failed write just means the next read falls back to live
+    }
+}
+/**
+ * Enter the doctor-overview singleflight gate. Returns a cached string to print,
+ * or a lock token telling the caller to compute (and then write + release).
+ *
+ * Contract:
+ *  - Fresh snapshot present (and not `forceRefresh`) → `{ cached }`, no lock.
+ *  - Otherwise exactly one caller holds the lock and gets `{ cached: null,
+ *    release }`; everyone else blocks on the lock, then (on acquiring it)
+ *    double-checks and serves the winner's fresh write — or, if the winner runs
+ *    past the wait budget, serves the last snapshot — rather than recomputing.
+ *  - Never throws: any IO/lock failure degrades to a compute token or a served
+ *    snapshot.
+ */
+export async function enterDoctorOverviewGate(opts = {}, deps = {}) {
+    const dir = deps.dir ?? getCacheDir();
+    const now = deps.now ?? Date.now;
+    const freshMs = opts.freshMs ?? DOCTOR_OVERVIEW_FRESH_MS;
+    const serveFresh = () => {
+        if (opts.forceRefresh)
+            return null;
+        const c = readDoctorOverviewCache({ dir });
+        if (c && now() - c.fetchedAt < freshMs)
+            return JSON.stringify(c.payload, null, 2);
+        return null;
+    };
+    // 1. Fast path: a fresh snapshot serves without any compute or lock.
+    const fast = serveFresh();
+    if (fast !== null)
+        return { cached: fast };
+    try {
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+    }
+    catch {
+        // Can't even make the cache dir — fall back to an unguarded compute.
+        return { cached: null, release: () => { } };
+    }
+    const lockTarget = path.join(dir, LOCK_TARGET_FILE);
+    ensureLockTarget(lockTarget);
+    // 2. Singleflight via proper-lockfile: one caller holds the lock and computes;
+    //    the rest block here until it releases.
+    let release = null;
+    try {
+        release = await lockfile.lock(lockTarget, {
+            stale: LOCK_STALE_MS,
+            retries: LOCK_RETRIES,
+            // A peer broke our lock (only possible if we somehow went stale). Don't
+            // crash on the async callback; we re-check the cache and serve/recompute.
+            onCompromised: () => { },
+        });
+    }
+    catch {
+        // 3. Winner held the lock past our wait budget. Serve the last snapshot
+        //    (even if stale) rather than pile on; only if there is genuinely none do
+        //    we compute unguarded (rare cold-start under sustained load).
+        const c = readDoctorOverviewCache({ dir });
+        if (c)
+            return { cached: JSON.stringify(c.payload, null, 2) };
+        return { cached: null, release: () => { } };
+    }
+    // 4. Acquired. The winner may have written a fresh snapshot while we waited —
+    //    serve it and release, instead of recomputing.
+    const afterWait = serveFresh();
+    if (afterWait !== null) {
+        // AWAIT, don't fire-and-forget: returning while the lockfile is still on
+        // disk makes the next caller retry against a lock that is logically free —
+        // the same pile-up this gate exists to prevent, just narrowed to the window
+        // between return and unlink. We are already in an async function, so the
+        // wait costs one unlink.
+        await release().catch(() => { });
+        return { cached: afterWait };
+    }
+    const rel = release;
+    let released = false;
+    return {
+        cached: null,
+        release: () => {
+            if (released)
+                return;
+            released = true;
+            void rel();
+        },
+    };
+}

package/dist/lib/devices/fleet.js

@@ -9,6 +9,7 @@
  */
 import { spawnSync } from 'child_process';
 import { isControlDevice } from './registry.js';
+import { isSelfHost } from './self-host.js';
 import { buildSshInvocation, sshTargetFor, writeAskpassShim } from './connect.js';
 /** npm dist-tags / semver pins only — rejects shell metacharacters. */
 export const FLEET_VERSION_RE = /^[A-Za-z0-9._-]+$/;
@@ -52,7 +53,11 @@ export function planFleetTargets(reg) {
  * surface — so their `skip` reason still flows through as an `unreachable` row.
  */
 export function remoteFleetTargets(planned, self) {
-    return planned.filter((t) => t.device.name !== self && t.skip !== 'control');
+    // Exclude self by name AND by full identity (tailscale dnsName, loopback): a
+    // device referenced by its dnsName slipped past the bare name check and got a
+    // remote version+doctor dial back to THIS box, which orphaned on timeout and
+    // piled up (RUSH-2114). `isSelfHost` matches every alias the box answers to.
+    return planned.filter((t) => t.device.name !== self && !isSelfHost(t.device.name) && t.skip !== 'control');
 }
 /**
  * Decide whether a fleet-health target should skip the expensive version+doctor
@@ -189,7 +194,7 @@ export function runFleet(targets, cmd, opts = {}) {
             continue;
         }
         try {
-            const isSelf = opts.self !== undefined && t.device.name === opts.self;
+            const isSelf = (opts.self !== undefined && t.device.name === opts.self) || isSelfHost(t.device.name);
             const res = isSelf ? localRunner(cmd) : runner(t.device, cmd);
             const ok = res.code === 0;
             const detail = (res.stderr || res.stdout).trim().slice(0, 200);

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

@@ -9,6 +9,10 @@ export interface ResolvedSshTarget {
     name: string;
     os?: string;
 }
+export interface ResolvedExplicitTargetSet {
+    targets: ResolvedSshTarget[];
+    unresolved: string[];
+}
 /**
  * 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
@@ -27,3 +31,5 @@ export declare function resolveDeviceTarget(token: string): Promise<DeviceProfil
  * cross-machine fan-out so they can never diverge onto two routes.
  */
 export declare function resolveExplicitTargets(hosts: string[]): Promise<ResolvedSshTarget[]>;
+/** Resolve explicit tokens while retaining failures for coverage-sensitive callers. */
+export declare function resolveExplicitTargetSet(hosts: string[]): Promise<ResolvedExplicitTargetSet>;

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

@@ -96,14 +96,20 @@ export async function resolveDeviceTarget(token) {
  * cross-machine fan-out so they can never diverge onto two routes.
  */
 export async function resolveExplicitTargets(hosts) {
-    const out = [];
+    return (await resolveExplicitTargetSet(hosts)).targets;
+}
+/** Resolve explicit tokens while retaining failures for coverage-sensitive callers. */
+export async function resolveExplicitTargetSet(hosts) {
+    const targets = [];
+    const unresolved = [];
     for (const h of hosts) {
         const resolved = await toResolvedTarget(h);
         if (!resolved) {
             process.stderr.write(chalk.gray(`  ${h}: not a resolvable ssh target — skipped\n`));
+            unresolved.push(h);
             continue;
         }
-        out.push(resolved);
+        targets.push(resolved);
     }
-    return out;
+    return { targets, unresolved };
 }

package/dist/lib/devices/self-host.d.ts

@@ -0,0 +1,9 @@
+/**
+ * True when `name` refers to the local machine. Case-insensitive and
+ * trailing-dot-tolerant. Use this everywhere a `--host`/fleet target is compared
+ * against "self" so a tailscale-name reference short-circuits to a local run
+ * instead of self-SSHing.
+ */
+export declare function isSelfHost(name: string | undefined | null): boolean;
+/** Test hook: drop the memoized alias set so a fresh registry/env is re-read. */
+export declare function resetSelfHostCache(): void;

package/dist/lib/devices/self-host.js

@@ -0,0 +1,61 @@
+/**
+ * "Is this hostname the local machine?" — matched against every identity the box
+ * answers to, not just its short id.
+ *
+ * The self-checks that gate `--host` dispatch and the fleet-health fan-out used to
+ * compare only against {@link machineId} (the lowercased short hostname, e.g.
+ * `zion`). A caller that referenced the box by its **tailscale MagicDNS name**
+ * (`zion.tail1a85a1.ts.net`) — which is exactly what `fleetDialTarget` and the
+ * Factory floor's `--host` probes use — slipped past the check and SSH'd to the
+ * LOCAL box over its own tailscale name. On a loaded machine that self-SSH'd
+ * `doctor --json` orphaned on timeout and piled up until the host was crushed
+ * (RUSH-2114). Matching the full identity set closes that gap at the source.
+ */
+import { machineId } from '../machine-id.js';
+import { loadDevicesSync } from './registry.js';
+const LOOPBACK = ['localhost', '127.0.0.1', '::1'];
+/** Lowercase + strip a trailing dot (FQDNs are equivalent with or without it). */
+function normalize(name) {
+    return name.trim().toLowerCase().replace(/\.$/, '');
+}
+let cached = null;
+/**
+ * Every name that resolves to THIS machine: the short id, loopback, and the self
+ * device's tailscale dnsName plus its short form. Computed once per process — the
+ * self identity does not change under a running CLI — and reads the registry
+ * best-effort (an unreadable registry still leaves the short id + loopback).
+ */
+function selfAliases() {
+    if (cached)
+        return cached;
+    const aliases = new Set([machineId(), ...LOOPBACK]);
+    try {
+        const dns = loadDevicesSync()[machineId()]?.address?.dnsName;
+        if (dns) {
+            const d = normalize(dns);
+            aliases.add(d);
+            aliases.add(d.split('.')[0]); // the short form of the FQDN
+        }
+    }
+    catch {
+        /* registry unreadable — the short id + loopback aliases still hold */
+    }
+    cached = aliases;
+    return cached;
+}
+/**
+ * True when `name` refers to the local machine. Case-insensitive and
+ * trailing-dot-tolerant. Use this everywhere a `--host`/fleet target is compared
+ * against "self" so a tailscale-name reference short-circuits to a local run
+ * instead of self-SSHing.
+ */
+export function isSelfHost(name) {
+    if (!name)
+        return false;
+    const n = normalize(name);
+    return n.length > 0 && selfAliases().has(n);
+}
+/** Test hook: drop the memoized alias set so a fresh registry/env is re-read. */
+export function resetSelfHostCache() {
+    cached = null;
+}