@phnx-labs/agents-cli 1.22.35 → 1.22.38

package/dist/lib/self-update.js

@@ -16,9 +16,19 @@ import * as os from 'os';
 import * as path from 'path';
 import { createHash, timingSafeEqual } from 'crypto';
 import { spawnSync } from 'child_process';
-import { compareVersions } from './versions.js';
+// Leaf comparator only — do not pull the full versions.ts graph into every
+// bootstrap that imports self-update (RUSH-2331).
+import { compareVersions } from './agent-spec/primitives.js';
 import { needsWindowsShell } from './platform/index.js';
 export const NPM_PACKAGE_NAME = '@phnx-labs/agents-cli';
+/**
+ * First published release that stopped the usage/auth-health probe from reading
+ * Claude Code's interactive login (commit 3f3554c51). Pre-this versions on a
+ * macOS box re-introduce the Touch ID storm + fleet-wide revocation class
+ * (RUSH-2415 / RUSH-1822). Anything older is a latent regression while a fixed
+ * copy sits next to it.
+ */
+export const TOUCH_ID_STORM_FIXED_SINCE = '1.22.30';
 /**
  * The directory bun installs global packages into:
  *   <BUN_INSTALL>/install/global   (BUN_INSTALL defaults to ~/.bun)
@@ -116,6 +126,84 @@ export function shouldPromptUpgrade(cache, currentVersion) {
         compareVersions(cache.latestVersion, currentVersion) > 0 &&
         cache.latestVersion !== cache.dismissed);
 }
+/**
+ * Short TTL for the multi-install PATH scan cache (RUSH-2324). The full
+ * `findAgentsCliInstalls` walk over PATH + known roots costs ~1ms on a warm
+ * box and runs on every ordinary CLI invocation via `maybeWarnMultiInstall`.
+ * Same 5-minute window as the detached-sync spawn gate so both bootstrap
+ * savings share one recency policy.
+ */
+export const MULTI_INSTALL_SCAN_TTL_MS = 5 * 60 * 1000;
+/** Read a multi-install scan cache. Returns null if missing or corrupt. */
+export function readMultiInstallScanCache(file) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        if (typeof raw.scannedAt !== 'number' ||
+            typeof raw.pathEnv !== 'string' ||
+            typeof raw.runningRoot !== 'string' ||
+            typeof raw.runningVersion !== 'string' ||
+            !Array.isArray(raw.inventory)) {
+            return null;
+        }
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+/** Persist a multi-install scan result. Best-effort. */
+export function writeMultiInstallScanCache(file, cache) {
+    try {
+        const dir = path.dirname(file);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(cache));
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/**
+ * Whether a multi-install scan cache is still usable for this invocation.
+ * Invalid when missing, past TTL, PATH changed, or the running copy identity
+ * (root / version) changed — those are exactly the cases where a re-scan can
+ * surface a different inventory and re-fire the warning.
+ */
+export function isMultiInstallScanFresh(cache, pathEnv, runningRoot, runningVersion, now = Date.now(), ttlMs = MULTI_INSTALL_SCAN_TTL_MS) {
+    if (!cache)
+        return false;
+    if (now - cache.scannedAt >= ttlMs)
+        return false;
+    if (cache.pathEnv !== pathEnv)
+        return false;
+    if (cache.runningRoot !== runningRoot)
+        return false;
+    if (cache.runningVersion !== runningVersion)
+        return false;
+    return true;
+}
+/**
+ * Resolve the multi-install inventory, hitting the on-disk scan cache when
+ * fresh. Callers that only need the inventory (the bootstrap multi-install
+ * warning) avoid the ~1ms PATH walk on the warm path (RUSH-2324).
+ */
+export function resolveMultiInstallInventory(runningRoot, runningVersion, pathEnv, cacheFile, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const ttlMs = opts.ttlMs ?? MULTI_INSTALL_SCAN_TTL_MS;
+    const cached = readMultiInstallScanCache(cacheFile);
+    if (isMultiInstallScanFresh(cached, pathEnv, runningRoot, runningVersion, now, ttlMs)) {
+        return cached.inventory;
+    }
+    const inventory = buildMultiInstallInventory(runningRoot, runningVersion, findAgentsCliInstalls(pathEnv, opts.findOpts));
+    writeMultiInstallScanCache(cacheFile, {
+        scannedAt: now,
+        pathEnv,
+        runningRoot,
+        runningVersion,
+        inventory,
+    });
+    return inventory;
+}
 /**
  * Whether `p` is Bun's embedded virtual filesystem — where a standalone
  * executable exposes its bundled sources. Nothing there exists on disk: it
@@ -346,6 +434,193 @@ export function buildMultiInstallInventory(runningRoot, runningVersion, installs
     }
     return [...byRoot.values()];
 }
+/** True when the package root lives under npm's `_npx` cache (ephemeral runs). */
+export function isNpxCacheInstall(packageRoot) {
+    // Split on either separator so a POSIX-shaped path is still recognized when
+    // this runs on Windows (doctor --fix / tests pass forward literal `_npx`
+    // paths from other boxes). `path.sep` alone missed `/home/…/_npx/…` on win32.
+    const parts = packageRoot.split(/[\\/]/);
+    return parts.includes('_npx');
+}
+/**
+ * A release string that is at least TOUCH_ID_STORM_FIXED_SINCE, or a side-by-side
+ * dev build (`0.0.0-dev.*`) which tracks main and therefore carries the fix.
+ * Non-semver junk never qualifies as "fixed" — better to leave a weird copy
+ * alone than delete the only working install.
+ */
+export function isTouchIdStormFixedVersion(version) {
+    if (version.startsWith('0.0.0-dev.') || version === '0.0.0-dev')
+        return true;
+    // compareVersions is numeric-segment only; refuse anything that does not
+    // look like a release before treating it as "older than fixed".
+    if (!/^\d+(\.\d+)*/.test(version))
+        return false;
+    return compareVersions(version, TOUCH_ID_STORM_FIXED_SINCE) >= 0;
+}
+/**
+ * Classify discovered installs that doctor --fix / upgrade may delete.
+ *
+ * Never marks the running package root. Auto-purge is limited to copies that
+ * cannot be the intended primary install:
+ *   - npx-cache trees (ephemeral)
+ *   - pre-atomic-helper-installer trees ("unsafe legacy helper installer")
+ *   - pre-TOUCH_ID_STORM_FIXED_SINCE trees, but only when at least one fixed
+ *     copy already exists on the box (so we never strand the machine)
+ *
+ * A pre-fixed copy that is also the only install stays — the user must upgrade
+ * it in place rather than delete it.
+ */
+export function classifyRemovableAgentsCliInstalls(runningRoot, installs, opts = {}) {
+    const fixedSince = opts.fixedSince ?? TOUCH_ID_STORM_FIXED_SINCE;
+    let runningCanonical = runningRoot;
+    try {
+        runningCanonical = fs.realpathSync(runningRoot);
+    }
+    catch {
+        /* keep as given */
+    }
+    // A fixed peer is any install (including the running copy) that carries the
+    // Touch-ID-storm fix. Pre-fixed trees are only deleted when such a peer
+    // exists, so a lone stale install is never purged out from under the user.
+    const hasFixedPeer = installs.some((install) => isTouchIdStormFixedVersion(install.version));
+    const out = [];
+    for (const install of installs) {
+        let root = install.packageRoot;
+        try {
+            root = fs.realpathSync(install.packageRoot);
+        }
+        catch {
+            /* keep */
+        }
+        if (root === runningCanonical)
+            continue;
+        const reasons = [];
+        if (isNpxCacheInstall(root) || isNpxCacheInstall(install.packageRoot)) {
+            reasons.push('npx-cache');
+        }
+        if (!install.atomicHelperInstall) {
+            reasons.push('unsafe-legacy-helper');
+        }
+        if (hasFixedPeer
+            && /^\d+(\.\d+)*/.test(install.version)
+            && compareVersions(install.version, fixedSince) < 0) {
+            reasons.push('pre-fixed-version');
+        }
+        if (reasons.length === 0)
+            continue;
+        out.push({ packageRoot: root, version: install.version, reasons });
+    }
+    return out;
+}
+/**
+ * Delete classified removable package roots from disk. Re-reads package.json
+ * immediately before the unlink so a path that is no longer @phnx-labs/agents-cli
+ * is never removed. Best-effort: one failure does not stop the rest.
+ */
+export function purgeRemovableAgentsCliInstalls(candidates, opts = {}) {
+    const result = {
+        removed: [],
+        failed: [],
+        skippedRunning: 0,
+    };
+    let runningCanonical;
+    if (opts.runningRoot) {
+        try {
+            runningCanonical = fs.realpathSync(opts.runningRoot);
+        }
+        catch {
+            runningCanonical = opts.runningRoot;
+        }
+    }
+    for (const candidate of candidates) {
+        let root = candidate.packageRoot;
+        try {
+            root = fs.realpathSync(candidate.packageRoot);
+        }
+        catch {
+            /* keep */
+        }
+        if (runningCanonical && root === runningCanonical) {
+            result.skippedRunning += 1;
+            continue;
+        }
+        // Refuse anything that no longer looks like our package.
+        try {
+            const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf-8'));
+            if (pkg.name !== NPM_PACKAGE_NAME) {
+                result.failed.push({
+                    ...candidate,
+                    packageRoot: root,
+                    error: `package.json name is ${String(pkg.name)}, not ${NPM_PACKAGE_NAME}`,
+                });
+                continue;
+            }
+        }
+        catch (err) {
+            result.failed.push({
+                ...candidate,
+                packageRoot: root,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            continue;
+        }
+        if (opts.dryRun) {
+            result.removed.push({ ...candidate, packageRoot: root });
+            continue;
+        }
+        try {
+            fs.rmSync(root, { recursive: true, force: true });
+            result.removed.push({ ...candidate, packageRoot: root });
+        }
+        catch (err) {
+            result.failed.push({
+                ...candidate,
+                packageRoot: root,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return result;
+}
+/**
+ * Scan + classify + purge in one call. Used by `agents doctor --fix` and
+ * `agents upgrade` so both paths remediate the same set of latent copies.
+ */
+export function remediateStaleAgentsCliInstalls(opts) {
+    const pathEnv = opts.pathEnv ?? (process.env.PATH || '');
+    const installs = findAgentsCliInstalls(pathEnv, opts.findOpts);
+    // Ensure the running root participates in "has a fixed peer" even when the
+    // PATH scan missed it (source tree, unusual layout).
+    if (opts.runningVersion) {
+        const already = installs.some((i) => {
+            try {
+                return fs.realpathSync(i.packageRoot) === fs.realpathSync(opts.runningRoot);
+            }
+            catch {
+                return i.packageRoot === opts.runningRoot;
+            }
+        });
+        if (!already) {
+            installs.push({
+                packageRoot: opts.runningRoot,
+                version: opts.runningVersion,
+                // Unknown for a synthetic entry — classify only uses version for the
+                // fixed-peer check; the running root is never deleted regardless.
+                atomicHelperInstall: true,
+            });
+        }
+    }
+    const candidates = classifyRemovableAgentsCliInstalls(opts.runningRoot, installs);
+    const purge = purgeRemovableAgentsCliInstalls(candidates, {
+        dryRun: opts.dryRun,
+        runningRoot: opts.runningRoot,
+    });
+    return {
+        ...purge,
+        candidates,
+        inventory: buildMultiInstallInventory(opts.runningRoot, opts.runningVersion ?? 'unknown', installs),
+    };
+}
 function childDirectories(parent) {
     try {
         return fs.readdirSync(parent, { withFileTypes: true })

package/dist/lib/session/active.d.ts

@@ -108,7 +108,7 @@ export interface ActiveSession {
     activity?: SessionActivity;
     /**
      * Output-token throughput (tokens/sec) over a rolling 60s window, from the
-     * transcript tail. The number the Factory Floor shows next to a running agent;
+     * transcript tail. The number the Fleet shows next to a running agent;
      * absent when no transcript is resolvable or the agent format reports no usage.
      */
     tokPerSec?: number;
@@ -124,7 +124,7 @@ export interface ActiveSession {
     plan?: string;
     /**
      * Live plan progress from the most recent `TodoWrite` (RUSH-1380): the checklist
-     * items + a done/total tally + the current step. The Factory Floor renders this
+     * items + a done/total tally + the current step. The Fleet renders this
      * as an N/M pill + checklist for every session — including remote and
      * device-dispatched agents that have no local tool-call stream to parse.
      */
@@ -227,8 +227,19 @@ export interface ActiveSession {
      * form). Set when merging cross-machine results so the grouped `--active`
      * view can bucket by computer. Absent for a purely local query (the renderer
      * falls back to provenance.host, then the local machine).
+     *
+     * For a host-dispatched run this is the EXECUTION host, not the box holding
+     * the live shim process — see {@link foldExecutionMachine}.
      */
     machine?: string;
+    /**
+     * Set only on the dispatching box's own row for a host-dispatched run
+     * (`agents run --device <peer>`): the live process here is the ssh/TTY shim,
+     * while the agent itself runs on {@link machine}. Names the box the dispatch
+     * was issued from, so a merged fleet view can prefer the executing machine's
+     * own richer row over this shim (see `dedupeByMachineSession`).
+     */
+    offloadedFrom?: string;
     teamName?: string;
     /**
      * For a teams teammate: the session id of the ORCHESTRATOR that spawned the
@@ -553,11 +564,16 @@ export declare function readAncestorSessionEntry(pid: number, ppidMap: Map<numbe
  * as its own headless row. Two exceptions keep their own row: a candidate with
  * its own registry entry — on its pid OR on a wrapper ancestor strictly below
  * the pid it would fold into (the shim's entry lands on the cmd.exe
- * intermediary on Windows) — and a child of a *different* agent kind (claude
- * shelling out to codex is a real second session, not a fork).
+ * intermediary on Windows) — a child whose live argv carries `--session-id`
+ * (RUSH-2384: empty by-pid must not fold a real session into a parent and
+ * drop it from the active set) — and a child of a *different* agent kind
+ * (claude shelling out to codex is a real second session, not a fork).
  * Returns the kept roots plus, per root pid, how many descendants folded in.
+ *
+ * `hasLiveSessionId` defaults to reading `--session-id` from the live process
+ * argv; tests inject a pure predicate so they do not need real agent pids.
  */
-export declare function foldSubordinateAgents(candidates: AgentCandidate[], ppidMap: Map<number, number>, readEntry: (pid: number) => PidSessionEntry | undefined): {
+export declare function foldSubordinateAgents(candidates: AgentCandidate[], ppidMap: Map<number, number>, readEntry: (pid: number) => PidSessionEntry | undefined, hasLiveSessionId?: (pid: number) => boolean): {
     kept: AgentCandidate[];
     foldedByRoot: Map<number, number>;
 };
@@ -625,6 +641,21 @@ export declare function listTmuxAgentSessions(): Promise<ActiveSession[]>;
  * terminal/headless row for the same session id.
  */
 export declare function getActiveSessions(opts?: ActiveQueryOptions): Promise<ActiveSession[]>;
+/**
+ * True when a live agent process on this host carries `--session-id <id>` in
+ * its argv. RUSH-2384 last-resort for `agents message`: getActiveSessions can
+ * still miss a row (teams status flap, attributed-ancestor skip), but the
+ * process table + argv are ground truth for "this session is alive and
+ * mailbox-reachable". Only UUID-shaped ids are accepted so a short prefix
+ * never false-matches.
+ */
+export declare function isSessionIdLiveOnProcessTable(sessionId: string, deps?: {
+    readTable?: () => Promise<Array<{
+        pid: number;
+        kind?: string;
+    }>>;
+    sessionIdOf?: (pid: number) => string | undefined;
+}): Promise<boolean>;
 /**
  * Fold tmux's attached-client count onto every tmux-hosted row.
  *
@@ -662,6 +693,59 @@ export declare function foldTmuxClients(rows: ActiveSession[]): Promise<void>;
  *     bury the real signal. A session sitting idle — or worse, waiting on a
  *     question — with no client attached is the stranded case: nobody is coming.
  */
+/**
+ * Attribute each live row to the machine the session actually EXECUTES on.
+ *
+ * A host-dispatched run (`agents run --device <peer>`) leaves a live process on
+ * the DISPATCHING box — the ssh/TTY shim — carrying the remote run's session id.
+ * Nothing about that local process knows the agent is on the peer, so the row
+ * was tagged with THIS machine: `--device <dispatcher>` then claimed a session
+ * that is not running here, and its preview dead-ended at "full transcript not
+ * indexed here" because the transcript lives on the peer (RUSH-2479).
+ *
+ * The dispatch already recorded the truth. `registerHostSession` /
+ * `registerInteractiveHostSession` write the index row with
+ * `machine: normalizeHost(task.host)` (`lib/hosts/session-index.ts:55,134`), so
+ * this folds that recorded machine back onto the live row. Every consumer then
+ * agrees on one owner: the `--host`/`--device` scope, the browser's device
+ * filter, `_remote`/preview routing (`liveSessionToMeta`), and the id resolver.
+ *
+ * Two rows are deliberately left alone:
+ *   - one the cross-machine fan-out already attributed to a peer — that is the
+ *     peer's own self-report, which outranks this box's index copy;
+ *   - one whose indexed machine IS this box — nothing was offloaded.
+ *
+ * Pure over the array; `machineOf` is injected so the join is unit-tested
+ * without a SQLite index.
+ */
+export declare function foldExecutionMachine(rows: ActiveSession[], machineOf: (sessionId: string) => string | undefined, self: string): void;
+/**
+ * Is the PROCESS behind this row running on this machine?
+ *
+ * `machine` answers a different question — "where does the agent execute" —
+ * which is what a `--device` scope, preview routing, and resume ownership need.
+ * For an offloaded run the two answers diverge: {@link foldExecutionMachine}
+ * points `machine` at the peer, while the shim process, its tmux pane, and its
+ * terminal window are all still HERE. `offloadedFrom` marks exactly that row.
+ *
+ * Any caller reaching for a LOCAL pid, pane, or window must ask this rather
+ * than `machine === self`. A local tmux pane id (`%N`) handed to a peer's tmux
+ * server does not fail — pane ids are small per-server integers, so it can
+ * resolve against an unrelated pane and attach the user to someone else's
+ * session. That is why this predicate exists instead of ten copies of the
+ * comparison.
+ */
+export declare function sessionProcessIsLocal(s: Pick<ActiveSession, 'machine' | 'offloadedFrom'>, self: string): boolean;
+/**
+ * The machine to reach for this session's PROCESS — its pid, tmux pane, and
+ * window — or `undefined` when that process is right here.
+ *
+ * Not the same as `machine`, which is where the AGENT executes. For an offloaded
+ * run the process lives on the dispatcher (`offloadedFrom`) while the agent runs
+ * on the peer, so a caller that ssh'd to `machine` would carry the dispatcher's
+ * pane id to a box that never had it.
+ */
+export declare function sessionProcessHost(s: Pick<ActiveSession, 'machine' | 'offloadedFrom'>, self: string): string | undefined;
 export declare function foldHostLink(rows: ActiveSession[]): void;
 /**
  * Resolve each teams row's `orchestratorLabel` from the orchestrator's own row,