@phnx-labs/agents-cli 1.20.31 → 1.20.32

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## Unreleased
 
+## 1.20.31
+
+**`agents sessions <id>`: a catch-up digest for switching between many agents (#502)**
+
+- Opening a single session now leads with its auto-inferred title (user `/rename` > Claude `ai-title` > first-prompt topic) and PR / worktree / ticket badges, then a **Changes** section that groups touched files by directory and tags each as created / modified / deleted (with a `+N ~N -N` summary) instead of the old flat "Modified" list, a **Tools** histogram (per-tool call counts), and a **Tests** verdict parsed from the last `vitest` / `jest` / `pytest` / `go test` / `cargo test` / `tsc` run. The same signals are folded into the interactive picker preview.
+- `agents sessions --active` now collapses the many subagent/fork PIDs of one session into a single row with a `×N` count instead of printing dozens of identical lines. Source: `src/lib/session/digest.ts`, `src/lib/session/render.ts`, `src/lib/session/active.ts`, `src/commands/sessions.ts`, `src/commands/sessions-picker.ts`.
+
+## 1.20.30
+
+**`agents sessions` live state engine: waiting / PR / worktree / ticket detection + reliable preview (#494)**
+
+- `agents sessions --active` infers real activity from each transcript's tail — **working** / **waiting** / **idle** — rather than the old mtime-only running/idle guess, using structural signals (Claude `ExitPlanMode` / `AskUserQuestion`) plus a question + mtime heuristic for Codex. It detects and badges a PR opened during the session (`gh pr create` + the resulting pull URL), a git worktree (`.agents/worktrees/<slug>/`), and a Linear/Jira ticket (from the prompt or branch), and shows the latest turn as the preview instead of the first prompt.
+- `--waiting` filters `--active` to only sessions blocked on your input and exits non-zero (a scriptable gate); `--tree` groups the listing by directory, dropping the id/version columns while keeping the short-id handle.
+- The preview line is now width-correct: measurement is ANSI- and wide-char-aware and reads `$COLUMNS` first, so it no longer wraps or drifts under tmux or over `--host` SSH (the remote is handed the caller's width). Session index schema v7 persists the PR / worktree / ticket signals so historical listings carry them too. Source: `src/lib/session/state.ts`, `src/lib/session/tail.ts`, `src/lib/session/width.ts`, `src/lib/session/{discover,db,active}.ts`, `src/commands/sessions.ts`.
+
 **`agents sessions --host <machine>`: query a remote machine's sessions live over SSH**
 
 - `agents sessions "<query>" --host <alias|user@host>` runs the same session query on a remote machine's own index over SSH and streams the result back — repeat `--host` (or pass several) to fan out across machines. SSH access is the only auth; there's no daemon or shared store. Targets are validated against a strict allowlist (`SSH_TARGET_RE`) to block flag-smuggling, and the forwarded invocation is double-quoted (`shellQuote`) so a query like `$(whoami)` survives as a literal string on both shell layers. Source: `src/lib/session/remote.ts`, `src/commands/sessions.ts`, `docs/05-sessions.md`.

package/dist/commands/ssh.js

@@ -20,6 +20,7 @@ import { machineId } from '../lib/session/sync/config.js';
 import { addIgnored, getDevice, loadDevices, loadIgnored, removeDevice, removeIgnored, upsertDevice, } from '../lib/devices/registry.js';
 import { nodeToDeviceInput, parseTailscaleStatus, tailscaleStatusJson, } from '../lib/devices/tailscale.js';
 import { planDeviceReconciliation, runDeviceSync } from '../lib/devices/sync.js';
+import { clearPendingSentinel } from '../lib/devices/pending.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { hostNameFor, renderSshConfig } from '../lib/devices/ssh-config.js';
 import { ASKPASS_BUNDLE_ENV, ASKPASS_KEY_ENV, buildSshInvocation, writeAskpassShim, } from '../lib/devices/connect.js';
@@ -154,6 +155,27 @@ Typical workflow:
             process.exit(1);
         }
     });
+    devicesCmd
+        .command('register <name>')
+        .description('Register a discovered (pending) node by name — used by the menu-bar "NEW DEVICES → Register" action.')
+        .action(async (name) => {
+        try {
+            const nodes = parseTailscaleStatus(tailscaleStatusJson());
+            const node = nodes.find((n) => n.name === name);
+            if (!node) {
+                console.error(chalk.red(`'${name}' is not a current tailscale node. See 'agents devices sync'.`));
+                process.exit(1);
+            }
+            await removeIgnored(name); // a re-registered node is no longer dismissed
+            const d = await upsertDevice(name, nodeToDeviceInput(node));
+            clearPendingSentinel(name); // drop the notification immediately
+            console.log(chalk.green(`Registered '${name}'`) + chalk.gray(` (${d.platform})`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
     devicesCmd
         .command('ignore <name>')
         .description('Dismiss a node from auto-discovery so it is never re-suggested (and remove it from the registry if present).')
@@ -161,6 +183,7 @@ Typical workflow:
         try {
             await removeDevice(name);
             await addIgnored(name);
+            clearPendingSentinel(name); // drop the notification immediately
             console.log(chalk.green(`Ignored '${name}'`) + chalk.gray(" — it won't be suggested again. Undo with `agents devices unignore`."));
         }
         catch (err) {

package/dist/commands/view.js

@@ -5,7 +5,7 @@ import * as path from 'path';
 import { AGENTS, ALL_AGENT_IDS, getAllCliStates, getAccountInfo, resolveAgentName, formatAgentError, agentLabel, colorAgent, } from '../lib/agents.js';
 import { deriveUsageStatusFromSnapshot, formatUsageSection, formatUsageSummary, formatUsageStatusBadge, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
 import { readManifest } from '../lib/manifest.js';
-import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, resolveVersionAlias, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, printTrashFooter, } from '../lib/versions.js';
+import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, resolveVersionAlias, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, printTrashFooter, reconcileStaleLatestForAgent, } from '../lib/versions.js';
 import { ensureVersionedAliasCurrent, removeShim, } from '../lib/shims.js';
 import { getAgentResources } from '../lib/resources.js';
 import { listCliStatus } from '../lib/cli-resources.js';
@@ -1262,6 +1262,16 @@ export async function viewAction(agentArg, options) {
         cli: options?.cli,
     };
     const filterIsSet = SECTION_KEYS.some((k) => filter[k]);
+    // RUSH-1320: fold any stale literal `latest` version-home into its concrete
+    // version before rendering, so it stops appearing as a bogus "version" next
+    // to the real ones. Best-effort — must never break `agents view`. Scoped to
+    // the queried agent when one is given (cheap no-op for agents with no
+    // `latest` dir, i.e. almost all of them).
+    {
+        const target = agentArg ? resolveAgentName(agentArg.split('@')[0]) : null;
+        const toReconcile = agentArg ? (target ? [target] : []) : ALL_AGENT_IDS;
+        await Promise.all(toReconcile.map((a) => reconcileStaleLatestForAgent(a).catch(() => { })));
+    }
     if (!agentArg) {
         if (prune) {
             await pruneDuplicates(undefined, yes, dryRun);

package/dist/lib/daemon.js

@@ -290,6 +290,36 @@ export async function runDaemon() {
     };
     const healInterval = setInterval(() => { void runHealCheck(); }, 6 * 60 * 60_000);
     const healKickoff = setTimeout(() => { void runHealCheck(); }, 30_000);
+    // Device probe: refresh registered devices' reachability and detect newly
+    // appeared tailnet nodes, dropping a sentinel per pending device so the
+    // menu-bar helper can surface "NEW DEVICES → Register / Ignore". Refresh mode
+    // never auto-registers a newcomer. Soft + overlap-guarded like session sync;
+    // a machine without tailscale is a clean no-op. ~every 3 min.
+    let probingDevices = false;
+    const runDeviceProbe = async () => {
+        if (probingDevices)
+            return;
+        probingDevices = true;
+        try {
+            const { runDeviceSync } = await import('./devices/sync.js');
+            const { reconcilePendingSentinels } = await import('./devices/pending.js');
+            const dev = await runDeviceSync({ soft: true, mode: 'refresh' });
+            if (dev.ok) {
+                reconcilePendingSentinels(dev.pending);
+                if (dev.pending.length) {
+                    log('INFO', `devices: ${dev.pending.length} new pending (${dev.pending.map((p) => p.name).join(', ')})`);
+                }
+            }
+        }
+        catch (err) {
+            log('ERROR', `device probe failed: ${err.message}`);
+        }
+        finally {
+            probingDevices = false;
+        }
+    };
+    const deviceProbeInterval = setInterval(() => { void runDeviceProbe(); }, 3 * 60_000);
+    const deviceProbeKickoff = setTimeout(() => { void runDeviceProbe(); }, 15_000);
     const handleReload = () => {
         log('INFO', 'Reloading jobs (SIGHUP)');
         scheduler.reloadAll();
@@ -307,6 +337,8 @@ export async function runDaemon() {
         clearInterval(syncInterval);
         clearInterval(healInterval);
         clearTimeout(healKickoff);
+        clearInterval(deviceProbeInterval);
+        clearTimeout(deviceProbeKickoff);
         removeDaemonPid();
         process.exit(0);
     };

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

@@ -0,0 +1,18 @@
+export interface PendingDevice {
+    name: string;
+    platform: string;
+}
+/**
+ * Make the sentinel dir exactly match `pending`: create a file per pending
+ * device (content = platform), and delete any leftover sentinel whose device is
+ * no longer pending (it got registered, ignored, or left the tailnet). Best-
+ * effort — a filesystem error here must never crash the daemon, so callers pass
+ * this through their existing try/catch.
+ */
+export declare function reconcilePendingSentinels(pending: PendingDevice[]): void;
+/** Remove one device's pending sentinel (after the user registers or ignores it).
+ * No-op if it doesn't exist. */
+export declare function clearPendingSentinel(name: string): void;
+/** Read the current pending sentinels (name + platform). Used by tests and any
+ * TS-side consumer; the menu-bar helper reads the dir directly in Swift. */
+export declare function readPendingSentinels(): PendingDevice[];

package/dist/lib/devices/pending.js

@@ -0,0 +1,103 @@
+/**
+ * "Pending device" sentinels.
+ *
+ * When the daemon's tailscale probe finds a node that is neither registered nor
+ * ignored, it drops a sentinel file under ~/.agents/.cache/state/devices-pending/
+ * — the same filesystem-signal pattern the attention hook uses for the menu bar.
+ * The Swift helper polls that dir every 10s and renders a "NEW DEVICES" section
+ * with Register / Ignore. The file NAME is the device name; the file CONTENT is
+ * the platform (one line), so the tray can show "zion (macos)" without opening
+ * the registry.
+ *
+ * The daemon owns writes (reconcile to match the current pending set); the CLI
+ * `agents devices register|ignore` clears a single sentinel the moment the user
+ * acts, so the badge updates immediately instead of waiting for the next probe.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getDevicesPendingDir } from '../state.js';
+/** Device-name sentinels must be safe filenames (no path traversal). The device
+ * name charset is already the ssh-alias set, but guard defensively. */
+function isSafeName(name) {
+    return /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name);
+}
+/**
+ * Make the sentinel dir exactly match `pending`: create a file per pending
+ * device (content = platform), and delete any leftover sentinel whose device is
+ * no longer pending (it got registered, ignored, or left the tailnet). Best-
+ * effort — a filesystem error here must never crash the daemon, so callers pass
+ * this through their existing try/catch.
+ */
+export function reconcilePendingSentinels(pending) {
+    const dir = getDevicesPendingDir();
+    const want = new Map(pending.filter((p) => isSafeName(p.name)).map((p) => [p.name, p.platform]));
+    // Whole body is best-effort: a filesystem error here must never propagate into
+    // the daemon loop or `agents sync`. The top-level mkdir/readdir are guarded
+    // too, so no caller needs its own try/catch.
+    let existing;
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        existing = fs.readdirSync(dir).filter((n) => !n.startsWith('.'));
+    }
+    catch {
+        return;
+    }
+    // Remove sentinels that are no longer pending.
+    for (const name of existing) {
+        if (!want.has(name)) {
+            try {
+                fs.unlinkSync(path.join(dir, name));
+            }
+            catch { /* already gone */ }
+        }
+    }
+    // Write/refresh the sentinels that should exist.
+    for (const [name, platform] of want) {
+        const p = path.join(dir, name);
+        const body = `${platform}\n`;
+        // Only write when missing or changed, to avoid needless mtime churn.
+        let current = null;
+        try {
+            current = fs.readFileSync(p, 'utf-8');
+        }
+        catch {
+            current = null;
+        }
+        if (current !== body) {
+            try {
+                fs.writeFileSync(p, body);
+            }
+            catch { /* best-effort */ }
+        }
+    }
+}
+/** Remove one device's pending sentinel (after the user registers or ignores it).
+ * No-op if it doesn't exist. */
+export function clearPendingSentinel(name) {
+    if (!isSafeName(name))
+        return;
+    try {
+        fs.unlinkSync(path.join(getDevicesPendingDir(), name));
+    }
+    catch { /* already gone */ }
+}
+/** Read the current pending sentinels (name + platform). Used by tests and any
+ * TS-side consumer; the menu-bar helper reads the dir directly in Swift. */
+export function readPendingSentinels() {
+    const dir = getDevicesPendingDir();
+    let names;
+    try {
+        names = fs.readdirSync(dir).filter((n) => !n.startsWith('.'));
+    }
+    catch {
+        return [];
+    }
+    return names.map((name) => {
+        let platform = 'unknown';
+        try {
+            platform = fs.readFileSync(path.join(dir, name), 'utf-8').trim() || 'unknown';
+        }
+        catch { /* keep default */ }
+        return { name, platform };
+    });
+}

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

@@ -1,11 +1,22 @@
 import { type TailscaleNode } from './tailscale.js';
+import type { PendingDevice } from './pending.js';
+/**
+ * bootstrap — register every non-ignored node (opt-out). First-run `agents
+ *   setup` and manual `agents devices sync`, so the fleet is usable out of box.
+ * refresh — only refresh reachability of already-registered nodes; a brand-new
+ *   node is NOT auto-added, it is surfaced as `pending` for the user to approve
+ *   (opt-in). Ongoing autosync and the daemon probe use this, so newcomers flow
+ *   through the menu-bar "NEW DEVICES → Register / Ignore" gate instead of
+ *   silently landing in the registry.
+ */
+export type DeviceSyncMode = 'bootstrap' | 'refresh';
 export interface DeviceSyncResult {
     /** False when discovery could not run (e.g. tailscale absent) in soft mode. */
     ok: boolean;
     /** Number of tailscale nodes upserted into the registry. */
     synced: number;
-    /** Node names discovered but neither registered-before nor ignored. */
-    pending: string[];
+    /** Nodes discovered but neither registered-before nor ignored (name+platform). */
+    pending: PendingDevice[];
     /** Populated when ok is false: why discovery was skipped. */
     reason?: string;
 }
@@ -15,6 +26,13 @@ export interface DeviceSyncResult {
  * flag matrix is unit-testable without a live tailnet.
  */
 export declare function computePendingDevices(nodes: TailscaleNode[], registered: Iterable<string>, ignored: Iterable<string>): string[];
+/**
+ * Which discovered nodes to upsert this run — the mode-defining decision, pure
+ * so it is unit-testable without a tailnet. Ignored nodes are always skipped.
+ * In `refresh` mode a node that isn't already registered is skipped too (it
+ * stays pending for approval); `bootstrap` includes every non-ignored node.
+ */
+export declare function selectNodesToUpsert(nodes: TailscaleNode[], registered: Set<string>, ignored: Set<string>, mode: DeviceSyncMode): TailscaleNode[];
 /**
  * Ingest `tailscale status --json` into the registry. In soft mode a missing
  * tailscale binary / unreachable daemon resolves to `{ ok: false }` instead of
@@ -24,6 +42,7 @@ export declare function computePendingDevices(nodes: TailscaleNode[], registered
  */
 export declare function runDeviceSync(opts?: {
     soft?: boolean;
+    mode?: DeviceSyncMode;
 }): Promise<DeviceSyncResult>;
 /**
  * The register/remove/ignore decision for the interactive curation picker.

package/dist/lib/devices/sync.js

@@ -28,6 +28,21 @@ export function computePendingDevices(nodes, registered, ignored) {
         .map((n) => n.name)
         .filter((name) => !known.has(name) && !skip.has(name));
 }
+/**
+ * Which discovered nodes to upsert this run — the mode-defining decision, pure
+ * so it is unit-testable without a tailnet. Ignored nodes are always skipped.
+ * In `refresh` mode a node that isn't already registered is skipped too (it
+ * stays pending for approval); `bootstrap` includes every non-ignored node.
+ */
+export function selectNodesToUpsert(nodes, registered, ignored, mode) {
+    return nodes.filter((n) => {
+        if (ignored.has(n.name))
+            return false;
+        if (mode === 'refresh' && !registered.has(n.name))
+            return false;
+        return true;
+    });
+}
 /**
  * Ingest `tailscale status --json` into the registry. In soft mode a missing
  * tailscale binary / unreachable daemon resolves to `{ ok: false }` instead of
@@ -36,6 +51,7 @@ export function computePendingDevices(nodes, registered, ignored) {
  * "new" means "not previously registered and not ignored".
  */
 export async function runDeviceSync(opts = {}) {
+    const mode = opts.mode ?? 'bootstrap';
     // Soft mode must be non-fatal for ANY failure, not just a missing tailscale:
     // a corrupted registry/ignore file (both throw by design), a disk error, or
     // registry lock contention (plausible when many agents SessionStart-autosync
@@ -44,18 +60,18 @@ export async function runDeviceSync(opts = {}) {
     try {
         const nodes = parseTailscaleStatus(tailscaleStatusJson());
         const [registeredBefore, ignored] = await Promise.all([loadDevices(), loadIgnored()]);
-        const pending = computePendingDevices(nodes, Object.keys(registeredBefore), ignored);
-        // Register/refresh every node the user has NOT dismissed. Skipping ignored
-        // nodes is what makes the "register all" default safe: a phone or someone
-        // else's laptop the user once dismissed never silently comes back.
-        let synced = 0;
-        for (const node of nodes) {
-            if (ignored.has(node.name))
-                continue;
+        const registered = new Set(Object.keys(registeredBefore));
+        const pendingNames = computePendingDevices(nodes, registered, ignored);
+        const byName = new Map(nodes.map((n) => [n.name, n]));
+        const pending = pendingNames.map((name) => ({
+            name,
+            platform: byName.get(name)?.platform ?? 'unknown',
+        }));
+        const toUpsert = selectNodesToUpsert(nodes, registered, ignored, mode);
+        for (const node of toUpsert) {
             await upsertDevice(node.name, nodeToDeviceInput(node));
-            synced++;
         }
-        return { ok: true, synced, pending };
+        return { ok: true, synced: toUpsert.length, pending };
     }
     catch (err) {
         if (opts.soft) {

package/dist/lib/state.d.ts

@@ -158,6 +158,8 @@ export declare function getTeamsRegistryPath(): string;
 export declare function getDevicesRegistryPath(): string;
 /** Path to the device ignore-list — tailscale node names the user dismissed, so auto-discovery never re-suggests them. Per-machine, same dir as the registry. */
 export declare function getDevicesIgnoredPath(): string;
+/** Dir of "pending device" sentinels (~/.agents/.cache/state/devices-pending/) — one empty-ish file per newly-discovered, not-yet-approved tailnet node. Written by the daemon probe, read by the menu-bar helper (mirrors the attention sentinel dir). */
+export declare function getDevicesPendingDir(): string;
 /** Path to cloud dispatch cache (~/.agents/.cache/cloud/). */
 export declare function getCloudDir(): string;
 /** Path to terminal session metadata (~/.agents/.cache/terminals/). */

package/dist/lib/state.js

@@ -354,6 +354,8 @@ export function getTeamsRegistryPath() { return path.join(HISTORY_DIR, 'teams',
 export function getDevicesRegistryPath() { return path.join(HISTORY_DIR, 'devices', 'registry.json'); }
 /** Path to the device ignore-list — tailscale node names the user dismissed, so auto-discovery never re-suggests them. Per-machine, same dir as the registry. */
 export function getDevicesIgnoredPath() { return path.join(HISTORY_DIR, 'devices', 'ignored.json'); }
+/** Dir of "pending device" sentinels (~/.agents/.cache/state/devices-pending/) — one empty-ish file per newly-discovered, not-yet-approved tailnet node. Written by the daemon probe, read by the menu-bar helper (mirrors the attention sentinel dir). */
+export function getDevicesPendingDir() { return path.join(RUNTIME_STATE_DIR, 'devices-pending'); }
 /** Path to cloud dispatch cache (~/.agents/.cache/cloud/). */
 export function getCloudDir() { return CLOUD_DIR; }
 /** Path to terminal session metadata (~/.agents/.cache/terminals/). */

package/dist/lib/sync-umbrella.js

@@ -120,15 +120,19 @@ export async function runUmbrellaSync(args) {
         const { refresh } = await import('./refresh.js');
         await refresh({ skipPrompts: yes });
         result.reconciled = true;
-        // Keep the local device registry current with the tailnet. Soft: a machine
-        // without tailscale is a clean no-op, never a sync failure. This is the
-        // wiring that fixes the "registry stays empty until you remember to run
-        // `agents devices sync`" gap — the SessionStart autosync now populates it.
+        // Keep already-registered devices' reachability current, and surface newly
+        // appeared tailnet nodes as "pending" for the menu-bar Register/Ignore gate
+        // rather than silently adding them (refresh mode). Soft: a machine without
+        // tailscale is a clean no-op, never a sync failure. First-run population is
+        // `agents setup` / manual `agents devices sync` (bootstrap).
         const { runDeviceSync } = await import('./devices/sync.js');
-        const dev = await runDeviceSync({ soft: true });
+        const { reconcilePendingSentinels } = await import('./devices/pending.js');
+        const dev = await runDeviceSync({ soft: true, mode: 'refresh' });
+        if (dev.ok)
+            reconcilePendingSentinels(dev.pending);
         result.devices = { synced: dev.synced, pending: dev.pending.length, skipped: !dev.ok };
         if (dev.ok) {
-            log(`devices: ${dev.synced} synced${dev.pending.length ? `, ${dev.pending.length} new` : ''}`);
+            log(`devices: ${dev.synced} refreshed${dev.pending.length ? `, ${dev.pending.length} new pending` : ''}`);
         }
     }
     return result;

package/dist/lib/versions.d.ts

@@ -197,6 +197,17 @@ export declare function installVersion(agent: AgentId, version: string, onProgre
  * when nothing was resolved or no stale dir is present, so it is safe to call
  * on every script-based install. Returns the action taken (for tests/logging).
  */
+/**
+ * Proactively fold a stale `latest` version-home into its concrete version,
+ * WITHOUT needing a fresh install (RUSH-1320). `reconcileStaleLatestDir` only
+ * fires at install time, so a `latest` dir left by an old probe-failed install
+ * lingers in `agents view` indefinitely. This resolves the live CLI version and
+ * reconciles — cheap no-op when there's no `latest` dir (the common case, so
+ * `agents view` pays a `--version` shell-out only the once, until it's folded).
+ * Skipped when the active config symlink still points at `latest`, since
+ * renaming that dir would dangle the live symlink.
+ */
+export declare function reconcileStaleLatestForAgent(agent: AgentId): Promise<void>;
 export declare function reconcileStaleLatestDir(agent: AgentId, installedVersion: string): Promise<'none' | 'renamed' | 'trashed'>;
 /**
  * Soft-delete a version directory by moving it to ~/.agents/.system/trash/versions/.

package/dist/lib/versions.js

@@ -1209,6 +1209,26 @@ function removeInstallArtifacts(versionDir) {
  * when nothing was resolved or no stale dir is present, so it is safe to call
  * on every script-based install. Returns the action taken (for tests/logging).
  */
+/**
+ * Proactively fold a stale `latest` version-home into its concrete version,
+ * WITHOUT needing a fresh install (RUSH-1320). `reconcileStaleLatestDir` only
+ * fires at install time, so a `latest` dir left by an old probe-failed install
+ * lingers in `agents view` indefinitely. This resolves the live CLI version and
+ * reconciles — cheap no-op when there's no `latest` dir (the common case, so
+ * `agents view` pays a `--version` shell-out only the once, until it's folded).
+ * Skipped when the active config symlink still points at `latest`, since
+ * renaming that dir would dangle the live symlink.
+ */
+export async function reconcileStaleLatestForAgent(agent) {
+    if (!fs.existsSync(getVersionDir(agent, 'latest')))
+        return;
+    if (getConfigSymlinkVersion(agent) === 'latest')
+        return;
+    const concrete = await getCliVersionFromPath(agent);
+    if (concrete && concrete !== 'latest') {
+        await reconcileStaleLatestDir(agent, concrete);
+    }
+}
 export async function reconcileStaleLatestDir(agent, installedVersion) {
     if (installedVersion === 'latest')
         return 'none';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.31",
+  "version": "1.20.32",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",