@phnx-labs/agents-cli 1.22.0 → 1.22.3

package/dist/commands/watchdog.js

@@ -29,6 +29,7 @@ import { mailboxIdForActiveSession } from '../lib/mailbox-target.js';
 import { gcMailbox } from '../lib/mailbox-gc.js';
 import { ensureWatchdogRoutine, isWatchdogRoutineEnabled, watchdogRoutineExists, WATCHDOG_ROUTINE_NAME, WATCHDOG_ROUTINE_SCHEDULE, } from '../lib/watchdog/routine.js';
 import { runWatchdogTick, writePolicySentinel, DEFAULT_THRESHOLDS, } from '../lib/watchdog/runner.js';
+import { isWatchdogRotateEnabled, listRotateStates, setWatchdogRotateEnabled } from '../lib/watchdog/rotate.js';
 /** Default state dir the runner and these subcommands share. */
 function stateDir() {
     return path.join(getRuntimeStateDir(), 'watchdog');
@@ -79,6 +80,8 @@ async function runMailboxGc(sessions) {
 function colorForOutcome(o) {
     if (o.injected)
         return chalk.green;
+    if (o.decision === 'rotate')
+        return chalk.magenta;
     if (o.addressable === false)
         return chalk.yellow;
     if (o.stall === 'stalled' && o.decision === 'nudge')
@@ -92,12 +95,14 @@ function printTick(result, willInject) {
     console.log(`${chalk.bold('watchdog')} ${mode}  ` +
         `${counts.total} live · ${counts.stalled} stalled · ` +
         `${chalk.green(String(counts.nudged))} nudged · ` +
-        `${chalk.yellow(String(counts.unaddressable))} un-addressable`);
+        `${chalk.yellow(String(counts.unaddressable))} un-addressable` +
+        (counts.rotating > 0 ? ` · ${chalk.magenta(String(counts.rotating))} rotating` : ''));
     for (const o of result.outcomes) {
         const tag = o.injected ? 'NUDGED'
-            : o.addressable === false ? 'FLAGGED'
-                : o.decision === 'nudge' ? 'WOULD-NUDGE'
-                    : 'skip';
+            : o.decision === 'rotate' ? (o.rotatePhase === 'failed' ? 'ROTATE-FAIL' : 'ROTATE')
+                : o.addressable === false ? 'FLAGGED'
+                    : o.decision === 'nudge' ? 'WOULD-NUDGE'
+                        : 'skip';
         const c = colorForOutcome(o);
         const who = o.label || o.sessionId?.slice(0, 8) || o.kind;
         const where = o.host ? chalk.dim(`[${o.host}]`) : '';
@@ -194,8 +199,14 @@ export function registerWatchdogCommand(program) {
       # Turn on the ALWAYS-ON watchdog (a daemon-fired routine)
       agents watchdog enable
 
+      # Show the routine, rotate config, and any in-flight in-place rotates
+      agents watchdog status
+
       # Leave one session detected-but-untouched
       agents watchdog policy <sessionId> handsoff
+
+      # Opt out of in-place rotate only (nudging stays on)
+      agents watchdog rotate off
     `,
         notes: `
       Decision path: a cheap deterministic pre-filter resolves the obvious cases
@@ -217,6 +228,20 @@ export function registerWatchdogCommand(program) {
       Ghostty with no tmux) is flagged for the menu-bar and SKIPPED -- never a
       guessed or frontmost target.
 
+      Rotate: a stalled session whose tail shows a HARD account limit ("You've
+      hit your weekly limit - resets ...") is ROTATED IN PLACE instead of nudged:
+      the tick gates on the same healthy-account selection 'agents run auto'
+      makes (zero healthy -> one skip event per cooldown window, terminal
+      untouched), injects the harness's exit sequence, relaunches
+      'agents run auto --interactive --session-id <uuid>' in the SAME tab, waits
+      (bounded, 60s) for the new TUI, then injects the resume replay for the old
+      session. On timeout the session is flagged and never blind-typed into; the
+      flag says the terminal may sit at a bare shell and needs a manual
+      'agents run auto'. A failed rotate is suppressed for 15m before retry.
+      Default ON; disable with 'agents watchdog rotate off' (writes
+      'watchdog.rotate: off' to ~/.agents/agents.yaml; nudging stays on).
+      State machine: ~/.agents/.cache/state/watchdog/rotate/<sessionId>.json.
+
       Always-on: 'agents watchdog enable' creates + enables a 'watchdog' command
       routine ('${WATCHDOG_ROUTINE_SCHEDULE}' -> agents watchdog --nudge) and reloads the
       daemon; 'disable' pauses it. Inspect it with 'agents routines list'. Defaults
@@ -244,6 +269,20 @@ export function registerWatchdogCommand(program) {
         await reloadDaemonForRoutine(false);
         console.log(chalk.yellow('watchdog: DISABLED (routine paused)'));
     });
+    cmd.command('rotate <state>')
+        .description('Turn in-place rotate of rate-limited sessions on|off (watchdog.rotate in agents.yaml). ' +
+        'Rotate-only: nudging stays on — unlike `watchdog disable`, which pauses the whole watchdog.')
+        .action((state) => {
+        const s = state.toLowerCase();
+        if (s !== 'on' && s !== 'off') {
+            console.error(chalk.red(`invalid state '${state}'. Use: on | off`));
+            process.exitCode = 1;
+            return;
+        }
+        setWatchdogRotateEnabled(s === 'on');
+        console.log(`watchdog: rotate ${s === 'on' ? chalk.green('ON') : chalk.yellow('OFF')} ` +
+            chalk.dim(`(watchdog.rotate: ${s} in agents.yaml)`));
+    });
     cmd.command('status')
         .description('Show whether the always-on watchdog routine is enabled and where state is written.')
         .option('--json', 'Emit status as JSON (for the menu-bar / scripts)')
@@ -254,11 +293,31 @@ export function registerWatchdogCommand(program) {
         // read it correctly regardless of which command commander bound it to.
         const json = command.optsWithGlobals().json === true;
         const on = isWatchdogRoutineEnabled();
+        const rotate = isWatchdogRotateEnabled() ? 'on' : 'off';
+        const rotates = listRotateStates(stateDir());
+        const inflight = rotates.filter((r) => r.phase !== 'done' && r.phase !== 'failed');
         if (json) {
-            console.log(JSON.stringify({ enabled: on, routine: WATCHDOG_ROUTINE_NAME, stateDir: stateDir() }));
+            console.log(JSON.stringify({
+                enabled: on,
+                routine: WATCHDOG_ROUTINE_NAME,
+                stateDir: stateDir(),
+                rotate,
+                rotates: rotates.map((r) => ({
+                    sessionId: r.sessionId,
+                    newSessionId: r.newSessionId,
+                    agent: r.agent,
+                    phase: r.phase,
+                    updatedAtMs: r.updatedAtMs,
+                    error: r.error,
+                })),
+            }));
             return;
         }
         console.log(`always-on watchdog: ${on ? chalk.green('ON') : chalk.dim('off')} (routine '${WATCHDOG_ROUTINE_NAME}')`);
+        console.log(`rotate: ${rotate === 'on' ? chalk.green('on') : chalk.yellow('off')} (watchdog.rotate in agents.yaml) · ${inflight.length} in-flight`);
+        for (const r of inflight) {
+            console.log(`  ${chalk.magenta(r.phase.padEnd(12))} ${chalk.bold(r.sessionId.slice(0, 8))} → ${r.newSessionId.slice(0, 8)}${r.error ? chalk.red(`  ${r.error}`) : ''}`);
+        }
         console.log(`state dir: ${chalk.dim(stateDir())}`);
     });
     // --- per-session policy ----------------------------------------------------

package/dist/lib/app-bundle-install.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 declare function copyAppBundle(src: string, dest: string, io?: {
+    renameSync?: (from: string, to: string) => void;
+}): void;
+/**
+ * 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 declare function withInstallLock(dest: string, fn: (heartbeat: () => void) => void): void;

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/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/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;
+}

package/dist/lib/hosts/passthrough.js

@@ -25,6 +25,7 @@ import { stripRoutingFlags, buildRemoteAgentsInvocation, HOST_ROUTING_SPECS, } f
 import { resolveRemoteOsSync } from './remote-os.js';
 import { machineId } from '../session/sync/config.js';
 import { loadDevices } from '../devices/registry.js';
+import { isSelfHost } from '../devices/self-host.js';
 import { fanOutDevices, planFleetTargets, runLocalCommand, runOnDevice, } from '../devices/fleet.js';
 import { platformGroupLabel } from '../devices/health-report.js';
 /**
@@ -334,7 +335,7 @@ export async function runFleetPassthrough(command, allArgs, spec, opts = {}) {
     const localRunner = opts.localRunner ?? runLocalCommand;
     const results = await fanOutDevices(targets, async (target) => {
         const cmd = ['agents', ...forwarded];
-        const isSelf = target.device.name.toLowerCase() === self.toLowerCase();
+        const isSelf = target.device.name.toLowerCase() === self.toLowerCase() || isSelfHost(target.device.name);
         const res = isSelf ? localRunner(cmd) : runner(target.device, cmd);
         if (res.code !== 0) {
             const detail = (res.stderr || res.stdout || 'unreachable').trim().slice(0, 200);
@@ -443,11 +444,12 @@ export async function maybeRunOnHost(command, allArgs, opts) {
     if (!hostName)
         return false;
     // Running against your own machine is just a local run — skip the SSH round-trip.
-    // `machineId()` is the same self-identifier the device registry and session
-    // sync use (lowercased short hostname); compare case-insensitively.
-    // Strip the routing flags from process.argv so the local command never sees
-    // an unregistered `--host`/`--device` and dies with "unknown option".
-    if (hostName.toLowerCase() === machineId()) {
+    // Match EVERY identity the box answers to (short id, loopback, tailscale
+    // dnsName), not just machineId() — a `--host <self-dnsName>` used to slip past a
+    // short-hostname-only check and self-SSH (RUSH-2114). Strip the routing flags
+    // from process.argv so the local command never sees an unregistered
+    // `--host`/`--device` and dies with "unknown option".
+    if (isSelfHost(hostName)) {
         const stripped = stripRoutingFlags(allArgs, STRIP_SPECS);
         process.argv = [process.argv[0], process.argv[1], ...stripped];
         return false;