@phnx-labs/agents-cli 1.22.58 → 1.22.60

package/dist/lib/monitors/remote.d.ts

@@ -20,10 +20,28 @@ import { type GatherRemoteAgentsJsonDeps } from '../remote-agents-json.js';
 import type { MonitorConfig } from './config.js';
 /** Recursion guard: a peer answering the fan-out must not fan out again. */
 export declare const NO_MONITOR_FANOUT_ENV = "AGENTS_MONITORS_LOCAL";
+/**
+ * The owning box's view of a remote monitor, beyond its behavioral identity —
+ * enough for `monitors list` to render it (enabled/placement/scope) and show a
+ * one-line liveness note without a second round-trip. All optional: a peer on an
+ * older CLI may omit them, and the duplicate guard never reads them.
+ */
+export interface RemoteMonitorDisplay {
+    enabled?: boolean;
+    owner?: string;
+    scope?: 'user' | 'system';
+    stalled?: boolean;
+    checkCount?: number;
+    lastCheckedAt?: string | null;
+    lastFiredAt?: string | null;
+    lastActionFailed?: boolean;
+}
 /** One monitor as seen on a peer, tagged with the box it lives on. */
 export interface RemoteMonitor {
     machine: string;
     monitor: Pick<MonitorConfig, 'name' | 'source' | 'condition' | 'action'>;
+    /** The owning box's enabled/placement/scope/liveness view, for `list` display. */
+    display?: RemoteMonitorDisplay;
 }
 /**
  * Parse a peer's `monitors list --json`. Defensive against version skew: a peer

package/dist/lib/monitors/remote.js

@@ -48,9 +48,20 @@ export function parseRemoteMonitors(stdout, machine) {
         // row cannot participate in the duplicate check either way.
         if (!m.name || !m.source || !m.condition || !m.action)
             continue;
+        const display = {
+            enabled: typeof m.enabled === 'boolean' ? m.enabled : undefined,
+            owner: typeof m.owner === 'string' ? m.owner : undefined,
+            scope: m.scope === 'system' || m.scope === 'user' ? m.scope : undefined,
+            stalled: typeof m.stalled === 'boolean' ? m.stalled : undefined,
+            checkCount: typeof m.checkCount === 'number' ? m.checkCount : undefined,
+            lastCheckedAt: typeof m.lastCheckedAt === 'string' ? m.lastCheckedAt : undefined,
+            lastFiredAt: typeof m.lastFiredAt === 'string' ? m.lastFiredAt : undefined,
+            lastActionFailed: typeof m.lastActionFailed === 'boolean' ? m.lastActionFailed : undefined,
+        };
         out.push({
             machine,
             monitor: { name: m.name, source: m.source, condition: m.condition, action: m.action },
+            display,
         });
     }
     return out;

package/dist/lib/perf/db.d.ts

@@ -6,7 +6,7 @@
  */
 import Database from '../sqlite.js';
 import type { AggregateOptions, PerfAggregateRow } from './types.js';
-export type { AggregateOptions, PerfAggregateRow, PerfSample } from './types.js';
+export type { AggregateOptions, PerfAggregateRow, PerfPhaseStat, PerfSample } from './types.js';
 export { recordSample, shortSessionId, resolveSpoolPath } from './spool.js';
 export { percentile } from '../percentile.js';
 export declare const PERF_SCHEMA_VERSION = 1;

package/dist/lib/perf/db.js

@@ -12,6 +12,31 @@ import { localMachineId } from '../origin-machine.js';
 import { resolveProjectKey } from '../project-key.js';
 import { percentile } from '../percentile.js';
 import { resolveSpoolPath, shortSessionId, _resetPerfSpoolForTest } from './spool.js';
+/**
+ * Parse the `phases` map from a sample's meta_json. Fail-soft: a row with no
+ * meta_json, malformed JSON, or a non-numeric phase value contributes nothing
+ * rather than throwing (the warehouse must survive any writer's shape).
+ */
+function parsePhases(metaJson) {
+    if (!metaJson)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(metaJson);
+    }
+    catch {
+        return undefined;
+    }
+    const phases = parsed?.phases;
+    if (!phases || typeof phases !== 'object')
+        return undefined;
+    const out = {};
+    for (const [name, val] of Object.entries(phases)) {
+        if (typeof val === 'number' && Number.isFinite(val))
+            out[name] = val;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
 export { recordSample, shortSessionId, resolveSpoolPath } from './spool.js';
 export { percentile } from '../percentile.js';
 export const PERF_SCHEMA_VERSION = 1;
@@ -222,7 +247,7 @@ export function aggregateSamples(opts = {}) {
         clauses.push('agent = ?');
         params.push(opts.agent);
     }
-    const rows = db.prepare(`SELECT kind, label, duration_ms, cache, exit_code, status, cwd
+    const rows = db.prepare(`SELECT kind, label, duration_ms, cache, exit_code, status, cwd, meta_json
      FROM samples WHERE ${clauses.join(' AND ')}`).all(...params);
     // Memoize cwd -> project key: resolveProjectKey walks the filesystem for
     // a repo root, and many rows in one warehouse query share the same cwd.
@@ -244,10 +269,21 @@ export function aggregateSamples(opts = {}) {
         const key = `${r.kind}\0${r.label}`;
         let b = map.get(key);
         if (!b) {
-            b = { kind: r.kind, label: r.label, durations: [], hits: 0, stale: 0, misses: 0, errors: 0, blocks: 0, timeouts: 0 };
+            b = { kind: r.kind, label: r.label, durations: [], hits: 0, stale: 0, misses: 0, errors: 0, blocks: 0, timeouts: 0, phases: new Map() };
             map.set(key, b);
         }
         b.durations.push(Number(r.duration_ms));
+        const phases = parsePhases(r.meta_json);
+        if (phases) {
+            for (const [name, ms] of Object.entries(phases)) {
+                let arr = b.phases.get(name);
+                if (!arr) {
+                    arr = [];
+                    b.phases.set(name, arr);
+                }
+                arr.push(ms);
+            }
+        }
         if (r.cache === 'hit')
             b.hits++;
         else if (r.cache === 'stale-prefetch')
@@ -301,6 +337,21 @@ export function aggregateSamples(opts = {}) {
         }
         if (b.timeouts > 0)
             row.timeoutRate = Math.round((b.timeouts / n) * 1000) / 1000;
+        if (b.phases.size > 0) {
+            const phases = {};
+            for (const [name, durs] of b.phases) {
+                if (durs.length === 0)
+                    continue;
+                const ps = durs.slice().sort((a, c) => a - c);
+                phases[name] = {
+                    n: ps.length,
+                    p50Ms: Math.round(percentile(ps, 50)),
+                    p90Ms: Math.round(percentile(ps, 90)),
+                };
+            }
+            if (Object.keys(phases).length > 0)
+                row.phases = phases;
+        }
         if (opts.project)
             row.project = opts.project;
         out.push(row);

package/dist/lib/perf/types.d.ts

@@ -21,6 +21,13 @@ export interface PerfSample {
     status?: string;
     metaJson?: string;
 }
+/** Percentiles for one sub-phase (e.g. agent.run's `startup`) across a bucket. */
+export interface PerfPhaseStat {
+    /** Samples that carried this phase (may be < the row's `n`). */
+    n: number;
+    p50Ms: number;
+    p90Ms: number;
+}
 export interface PerfAggregateRow {
     kind: string;
     label: string;
@@ -31,6 +38,13 @@ export interface PerfAggregateRow {
     meanMs: number;
     maxMs: number;
     minMs: number;
+    /**
+     * Per-sub-phase percentiles parsed from each sample's meta_json `phases`.
+     * Present only when at least one sample in the bucket recorded a phase
+     * (agent.run records `startup` — time from spawnAgent entry to child spawn —
+     * so boot cost is trackable independently of the total run, PHNX-3468).
+     */
+    phases?: Record<string, PerfPhaseStat>;
     cacheHitPct?: number;
     cacheStalePct?: number;
     cacheMissPct?: number;

package/dist/lib/permissions.js

@@ -323,8 +323,13 @@ export function buildPermissionsFromGroups(groupNames) {
             const content = fs.readFileSync(filePath, 'utf-8');
             // Extract rules using line-by-line regex (more robust than YAML parsing)
             // Matches lines like: - "Bash(git *)" or   - "WebFetch(domain:example.com)"
-            // Handles nested quotes that break YAML parsers
-            const lines = content.split('\n');
+            // Handles nested quotes that break YAML parsers.
+            // Split on CRLF or LF: git checks group yaml out with CRLF on Windows
+            // (core.autocrlf), and a plain split('\n') leaves a trailing '\r' so the
+            // closing-quote anchor `"$` never matches — extracting ZERO rules, which
+            // wrote an empty permission set and left `agents doctor --fix` unable to
+            // reconcile permissions on Windows forever (PHNX-3187).
+            const lines = content.split(/\r?\n/);
             let section = null;
             for (const line of lines) {
                 const sectionMatch = line.match(/^\s*(allow|deny)\s*:\s*(?:#.*)?$/);

package/dist/lib/plugins/plugins.d.ts

@@ -254,12 +254,26 @@ export declare function removePluginFromVersion(pluginName: string, pluginRoot:
     mcp: number;
 };
 /**
- * Remove orphaned plugin entries from a version home. An entry is "orphan" if
- * its plugin name is not in the active plugin set. Soft-deletes the affected
+ * The active plugin set, either as bare names (legacy callers / the dual-dash
+ * sweep, which has no marketplace to key on) or as the discovered plugins
+ * themselves (which carry marketplace provenance, enabling per-marketplace
+ * orphan detection — the PHNX-2618 shadow case below).
+ */
+export type ActivePluginsInput = Set<string> | Array<{
+    name: string;
+    marketplace?: string;
+}>;
+/**
+ * Remove orphaned plugin entries from a version home. A marketplace-plugin
+ * install is "orphan" when no active source plugin matches its (marketplace,
+ * name) pair (see isOrphanMarketplacePlugin). Soft-deletes the affected
  * marketplace plugin dir to ~/.agents/.trash/plugins/. Also cleans up any
  * legacy dual-dash skills/ directories from older agents-cli versions.
+ *
+ * Pass the discovered plugins (`discoverPlugins()`) for marketplace-aware
+ * detection; a bare `Set<string>` of names keeps the original name-only behavior.
  */
-export declare function cleanOrphanedPluginSkills(agent: AgentId, versionHome: string, activePluginNames: Set<string>, version?: string): string[];
+export declare function cleanOrphanedPluginSkills(agent: AgentId, versionHome: string, activePlugins: ActivePluginsInput, version?: string): string[];
 export interface VersionPluginDiff {
     agent: AgentId;
     version: string;

package/dist/lib/plugins/plugins.js

@@ -1430,14 +1430,88 @@ function cleanLegacyFlatLayout(pluginName, pluginRoot, agent, versionHome, resul
         catch { /* ignore */ }
     }
 }
-// ─── Orphan cleanup ───────────────────────────────────────────────────────────
+function pairKey(marketplace, name) {
+    return `${marketplace}${name}`;
+}
+function indexActivePlugins(input) {
+    if (input instanceof Set)
+        return { names: input, pairs: null };
+    const names = new Set();
+    const pairs = new Set();
+    for (const p of input) {
+        names.add(p.name);
+        // A discovered plugin always carries provenance; the type allows undefined,
+        // so mirror discovery's own default (a marketplace-less plugin is the user
+        // "agents-cli" marketplace — see discoverPlugins / buildDiscoveredPlugin).
+        pairs.add(pairKey(p.marketplace ?? MARKETPLACE_NAME, p.name));
+    }
+    return { names, pairs };
+}
+/**
+ * Does the SOURCE repo backing a synthesized marketplace exist on disk? A
+ * marketplace's version-home install is only authoritative-cleanable when its
+ * source repo is present: a present repo missing a plugin means that plugin was
+ * genuinely removed, while an absent repo (a project we're not in, a removed
+ * extra repo) is merely unreachable and must not be mistaken for deletion.
+ *
+ * We check the REPO root, not the plugins/ subdir: the user repo (~/.agents/)
+ * always exists but its plugins/ dir may not, and "user repo present, no `code`
+ * plugin in it" is exactly what makes an `agents-cli` `code` shadow a real
+ * orphan (PHNX-2618).
+ */
+function marketplaceSourceRepoExists(marketplaceName, cwd) {
+    const spec = marketplaceSpecForName(marketplaceName, cwd);
+    switch (spec.kind) {
+        case 'user': return fs.existsSync(path.dirname(getPluginsDir()));
+        case 'system': return fs.existsSync(path.dirname(getSystemPluginsDir()));
+        case 'extra': return fs.existsSync(path.dirname(getExtraPluginsDir(spec.alias)));
+        case 'project': {
+            const root = getProjectPluginsDir(cwd);
+            return root != null && fs.existsSync(path.dirname(root));
+        }
+    }
+}
+/**
+ * Is a version-home marketplace-plugin install an orphan (safe to trash)?
+ *
+ * A version-home plugin is keyed by (marketplace, name), not name alone — the
+ * bug PHNX-2618 exposed. When the same plugin name lives in two marketplaces
+ * (e.g. a legacy `code` under `agents-cli` and the current `code` under
+ * `agents-system`), a name-only test keeps BOTH alive because the name is active
+ * somewhere, so the stale copy never gets cleaned and serves deleted skills.
+ *
+ *   - Pair still active → keep.
+ *   - Pair gone, but the marketplace's source repo is present (authoritative) →
+ *     orphan. Trash it even though another marketplace still ships that name.
+ *   - Pair gone AND the source repo is absent (unreachable) → fall back to the
+ *     original name-only test so an unrelated sync can't trash a plugin whose
+ *     source simply isn't on this box / in this cwd right now.
+ *
+ * When `pairs` is null (a legacy bare-name caller), this reduces to the original
+ * name-only behavior unchanged.
+ */
+function isOrphanMarketplacePlugin(marketplaceName, pluginName, active, cwd) {
+    if (active.pairs === null)
+        return !active.names.has(pluginName);
+    if (active.pairs.has(pairKey(marketplaceName, pluginName)))
+        return false;
+    if (marketplaceSourceRepoExists(marketplaceName, cwd))
+        return true;
+    return !active.names.has(pluginName);
+}
 /**
- * Remove orphaned plugin entries from a version home. An entry is "orphan" if
- * its plugin name is not in the active plugin set. Soft-deletes the affected
+ * Remove orphaned plugin entries from a version home. A marketplace-plugin
+ * install is "orphan" when no active source plugin matches its (marketplace,
+ * name) pair (see isOrphanMarketplacePlugin). Soft-deletes the affected
  * marketplace plugin dir to ~/.agents/.trash/plugins/. Also cleans up any
  * legacy dual-dash skills/ directories from older agents-cli versions.
+ *
+ * Pass the discovered plugins (`discoverPlugins()`) for marketplace-aware
+ * detection; a bare `Set<string>` of names keeps the original name-only behavior.
  */
-export function cleanOrphanedPluginSkills(agent, versionHome, activePluginNames, version) {
+export function cleanOrphanedPluginSkills(agent, versionHome, activePlugins, version) {
+    const active = indexActivePlugins(activePlugins);
+    const cwd = process.cwd();
     const removed = [];
     // 1. Walk every marketplace's install dir and trash entries no longer active.
     for (const name of listVersionMarketplaceNames(agent, versionHome)) {
@@ -1449,7 +1523,7 @@ export function cleanOrphanedPluginSkills(agent, versionHome, activePluginNames,
         for (const entry of fs.readdirSync(mktPluginsDir, { withFileTypes: true })) {
             if (!entry.isDirectory() || entry.name.startsWith('.'))
                 continue;
-            if (activePluginNames.has(entry.name))
+            if (!isOrphanMarketplacePlugin(name, entry.name, active, cwd))
                 continue;
             try {
                 const stamp = new Date().toISOString().replace(/[:.]/g, '-');
@@ -1488,7 +1562,7 @@ export function cleanOrphanedPluginSkills(agent, versionHome, activePluginNames,
             if (dashIdx === -1)
                 continue;
             const pluginName = entry.name.slice(0, dashIdx);
-            if (activePluginNames.has(pluginName))
+            if (active.names.has(pluginName))
                 continue;
             try {
                 const stamp = new Date().toISOString().replace(/[:.]/g, '-');
@@ -1505,7 +1579,8 @@ export function cleanOrphanedPluginSkills(agent, versionHome, activePluginNames,
 }
 export function diffVersionPlugins(agent, version) {
     const versionHome = getVersionHomePath(agent, version);
-    const activePlugins = new Set(discoverPlugins().map(p => p.name));
+    const active = indexActivePlugins(discoverPlugins());
+    const cwd = process.cwd();
     const orphans = [];
     for (const name of listVersionMarketplaceNames(agent, versionHome)) {
         const mktPluginsDir = path.join(marketplaceRoot(name, agent, versionHome), 'plugins');
@@ -1514,7 +1589,7 @@ export function diffVersionPlugins(agent, version) {
         for (const entry of fs.readdirSync(mktPluginsDir, { withFileTypes: true })) {
             if (!entry.isDirectory() || entry.name.startsWith('.'))
                 continue;
-            if (!activePlugins.has(entry.name)) {
+            if (isOrphanMarketplacePlugin(name, entry.name, active, cwd)) {
                 orphans.push(entry.name);
             }
         }
@@ -1529,7 +1604,7 @@ export function diffVersionPlugins(agent, version) {
             if (dashIdx === -1)
                 continue;
             const pluginName = entry.name.slice(0, dashIdx);
-            if (!activePlugins.has(pluginName)) {
+            if (!active.names.has(pluginName)) {
                 orphans.push(entry.name);
             }
         }

package/dist/lib/pty-server.d.ts

@@ -21,6 +21,20 @@ export { captureProcessStartTime };
  * (the authoritative code comes from node-pty's onExit).
  */
 export declare function buildSentinelCommand(shell: string, command: string): string;
+/**
+ * Turn a native-binding load failure into an actionable, platform-aware message.
+ *
+ * The binding is `@homebridge/node-pty-prebuilt-multiarch`'s `pty.node`. On Linux
+ * it is baked into the npm tarball and always present; on macOS/Windows it is
+ * fetched per host + Node ABI at install time by the package's `prebuild-install`
+ * postinstall. The common failure is a Node runtime whose ABI has no published
+ * prebuild (the PHNX-2740 darwin-arm64 case): `prebuild-install` finds nothing,
+ * the build-from-source fallback also fails, and the loader throws a bare
+ * `Cannot find module '.../pty.node'` / MODULE_NOT_FOUND with no clue what to do.
+ *
+ * Pure (returns the lines) so it can be unit-tested without spawning the server.
+ */
+export declare function describeNativePtyLoadFailure(err: unknown): string[];
 /**
  * Resolve the IPC endpoint for a given platform + PTY scratch dir. Pure so both
  * branches are testable without stubbing process.platform.

package/dist/lib/pty-server.js

@@ -88,6 +88,43 @@ export function buildSentinelCommand(shell, command) {
     }
     return `${command}; echo "${SENTINEL}:$?"`;
 }
+/**
+ * Turn a native-binding load failure into an actionable, platform-aware message.
+ *
+ * The binding is `@homebridge/node-pty-prebuilt-multiarch`'s `pty.node`. On Linux
+ * it is baked into the npm tarball and always present; on macOS/Windows it is
+ * fetched per host + Node ABI at install time by the package's `prebuild-install`
+ * postinstall. The common failure is a Node runtime whose ABI has no published
+ * prebuild (the PHNX-2740 darwin-arm64 case): `prebuild-install` finds nothing,
+ * the build-from-source fallback also fails, and the loader throws a bare
+ * `Cannot find module '.../pty.node'` / MODULE_NOT_FOUND with no clue what to do.
+ *
+ * Pure (returns the lines) so it can be unit-tested without spawning the server.
+ */
+export function describeNativePtyLoadFailure(err) {
+    const detail = err instanceof Error ? (err.stack || err.message) : String(err);
+    const abi = process.versions.modules;
+    const nodeVersion = process.version;
+    const platform = `${process.platform}-${process.arch}`;
+    const lines = [
+        `agents pty could not load its native terminal binding (@homebridge/node-pty-prebuilt-multiarch).`,
+        `  platform: ${platform}   node: ${nodeVersion} (ABI ${abi})`,
+        ``,
+        `The prebuilt binary for this platform + Node ABI is missing. On macOS/Windows`,
+        `it is downloaded at install time; a Node version newer than any published`,
+        `prebuild, or an install that skipped the postinstall, leaves it absent.`,
+        ``,
+        `Fix it by reinstalling so the native binding is fetched or built:`,
+        `  npm rebuild @homebridge/node-pty-prebuilt-multiarch   # rebuild for this Node`,
+        `  # or reinstall the CLI:  npm i -g @phnx-labs/agents-cli`,
+        `If your Node (ABI ${abi}) is newer than the shipped prebuilds, install an LTS`,
+        `Node and retry, or ensure a C++ toolchain is present for the source build.`,
+        ``,
+        `Underlying error:`,
+        ...detail.split('\n').map(l => `  ${l}`),
+    ];
+    return lines;
+}
 /** Get the PTY helper directory, creating it if needed. */
 function getPtyDir() {
     const dir = getPtyDirRoot();
@@ -181,9 +218,16 @@ export async function runPtyServer() {
     let nodePty;
     let XtermTerminal;
     try {
-        // The Homebridge multiarch fork of node-pty: API-identical (same 1.x N-API
-        // codebase) but ships prebuilt binaries for Linux glibc + musl, x64 + arm64
-        // (plus macOS/Windows), so no compiler is needed on Linux/Alpine/arm64.
+        // The Homebridge multiarch fork of node-pty (API-identical to the 1.x N-API
+        // upstream). Its npm tarball BAKES IN the Linux prebuilds (glibc + musl, every
+        // arch + Node ABI), so Linux never needs a compiler or a network fetch. The
+        // darwin-arm64 / win32 binaries are NOT in the tarball — they are downloaded
+        // per host+Node-ABI at install time by the package's own `prebuild-install`
+        // postinstall (gated by bun's `trustedDependencies`). That fetch fails when the
+        // running Node ABI is newer than any published prebuild (e.g. 0.13.1 shipped no
+        // darwin-arm64 above Node 24 / ABI 137, so Node 25/26 fell through to a
+        // build-from-source that also failed — PHNX-2740), leaving a raw MODULE_NOT_FOUND.
+        // Fail loud with the platform/ABI and a concrete remediation instead.
         nodePty = await import('@homebridge/node-pty-prebuilt-multiarch');
         // Handle ESM default export
         if (nodePty.default?.spawn)
@@ -205,8 +249,8 @@ export async function runPtyServer() {
         catch { }
     }
     catch (err) {
-        console.error('node-pty (@homebridge/node-pty-prebuilt-multiarch) is required for PTY support.');
-        console.error('Install: bun add @homebridge/node-pty-prebuilt-multiarch');
+        for (const line of describeNativePtyLoadFailure(err))
+            console.error(line);
         process.exit(1);
     }
     try {

package/dist/lib/secrets/drivers/rush.js

@@ -26,6 +26,11 @@ function readRushToken() {
     if (!token) {
         throw new Error('No session token in ~/.rush/user.yaml. Run `rush login` first.');
     }
+    const expiresAt = data.session?.expires_at;
+    if (typeof expiresAt === 'number' && expiresAt <= Date.now() / 1000) {
+        const expiredAt = new Date(expiresAt * 1000).toISOString();
+        throw new Error(`Rush session expired at ${expiredAt}. Run \`rush login\` to refresh.`);
+    }
     return token;
 }
 async function api(method, endpoint, body) {

package/dist/lib/self-update.d.ts

@@ -204,6 +204,48 @@ export declare function verifyInstalledVersion(packageRoot: string, expectedVers
  * upgraded) package root.
  */
 export declare function refreshAliasShims(packageRoot: string): void;
+/** One global bin link the upgrade reconciled: what it is and what happened. */
+export interface BinLinkRepair {
+    /** The `package.json#bin` key (`agents`, `ag`, `browser`, `computer`). */
+    name: string;
+    /** `<prefix>/bin/<name>` — the PATH entry the box's shell resolves. */
+    linkPath: string;
+    /** Absolute path the link must resolve to (`<packageRoot>/<bin target>`). */
+    target: string;
+    /**
+     * `ok` — already resolved to the freshly-installed target.
+     * `repaired` — was missing / dangling / pointing elsewhere, now relinked.
+     * `failed` — could not be made to resolve (see `error`).
+     */
+    action: 'ok' | 'repaired' | 'failed';
+    /** Set only for `failed`: why the relink did not take. */
+    error?: string;
+}
+/**
+ * The global bin links the upgrade OWNS: `<prefix>/bin/<name>` for every
+ * `package.json#bin` entry (`agents`, `ag`, `browser`, `computer`).
+ *
+ * npm creates these on a normal `install -g`, but a box with several installs
+ * (or a reify interrupted after the old links were retired) can end an upgrade
+ * with the package at the new version and these links **missing** — the state
+ * that stranded zion (PHNX-2768): `/opt/homebrew/lib/node_modules/...` at
+ * 1.22.40 but `/opt/homebrew/bin/{agents,ag,browser,computer}` gone, so every
+ * `agents` invocation was "command not found" until the links were relinked by
+ * hand. The rollout probe reported it `unverified`; the box was left broken.
+ *
+ * So the upgrade verifies these links right after installing and **restores any
+ * that are wrong** — covering the sibling entrypoints, not just `agents`, since
+ * `ag`/`browser`/`computer` share the same failure. Each link is reconciled
+ * independently; a link that cannot be made to resolve is reported `failed` so
+ * the caller can fail loud (the rollout then marks the box failed, not merely
+ * unverified) instead of returning a box the package upgraded but cannot run.
+ *
+ * POSIX only — Windows npm bins are `.cmd`/`.ps1` shims, not symlinks, so this
+ * relink shape does not apply and the caller skips it there. `prefix` is the
+ * npm global prefix from {@link deriveGlobalPrefix}; the bun path uses its own
+ * bin layout and is out of scope.
+ */
+export declare function ensureGlobalBinLinks(packageRoot: string, prefix: string): BinLinkRepair[];
 export interface AgentsCliInstall {
     /** The PATH entry (`<dir>/agents`) that resolves to this install, when found through PATH. */
     binPath?: string;

package/dist/lib/self-update.js

@@ -454,6 +454,94 @@ export function refreshAliasShims(packageRoot) {
         stdio: 'ignore',
     });
 }
+/** Resolve `p` through symlinks, or null when it does not resolve (missing/dangling). */
+function realpathOrNull(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Reconcile one `<binDir>/<name>` link to `target`. A link that already resolves
+ * to `target` is left untouched (`ok`); anything else — absent, dangling, or
+ * pointing at a stale/foreign path — is replaced with a fresh **relative**
+ * symlink (`../lib/node_modules/@phnx-labs/agents-cli/dist/index.js`), the exact
+ * shape npm and the by-hand zion repair both produced, then re-verified. A
+ * repair that still does not resolve (target missing, unwritable bin dir) is
+ * reported `failed` with the reason rather than silently swallowed.
+ */
+function reconcileBinLink(name, linkPath, target) {
+    const wanted = realpathOrNull(target);
+    if (wanted !== null && realpathOrNull(linkPath) === wanted) {
+        return { name, linkPath, target, action: 'ok' };
+    }
+    try {
+        fs.mkdirSync(path.dirname(linkPath), { recursive: true });
+        // Replace whatever is there (a dangling link, a stale link, or nothing).
+        fs.rmSync(linkPath, { force: true });
+        fs.symlinkSync(path.relative(path.dirname(linkPath), target), linkPath);
+        const resolved = realpathOrNull(linkPath);
+        if (resolved !== null && resolved === realpathOrNull(target)) {
+            return { name, linkPath, target, action: 'repaired' };
+        }
+        return {
+            name,
+            linkPath,
+            target,
+            action: 'failed',
+            error: resolved === null
+                ? `link created but still does not resolve (is ${target} present?)`
+                : `link resolves to ${resolved}, not ${target}`,
+        };
+    }
+    catch (err) {
+        return { name, linkPath, target, action: 'failed', error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * The global bin links the upgrade OWNS: `<prefix>/bin/<name>` for every
+ * `package.json#bin` entry (`agents`, `ag`, `browser`, `computer`).
+ *
+ * npm creates these on a normal `install -g`, but a box with several installs
+ * (or a reify interrupted after the old links were retired) can end an upgrade
+ * with the package at the new version and these links **missing** — the state
+ * that stranded zion (PHNX-2768): `/opt/homebrew/lib/node_modules/...` at
+ * 1.22.40 but `/opt/homebrew/bin/{agents,ag,browser,computer}` gone, so every
+ * `agents` invocation was "command not found" until the links were relinked by
+ * hand. The rollout probe reported it `unverified`; the box was left broken.
+ *
+ * So the upgrade verifies these links right after installing and **restores any
+ * that are wrong** — covering the sibling entrypoints, not just `agents`, since
+ * `ag`/`browser`/`computer` share the same failure. Each link is reconciled
+ * independently; a link that cannot be made to resolve is reported `failed` so
+ * the caller can fail loud (the rollout then marks the box failed, not merely
+ * unverified) instead of returning a box the package upgraded but cannot run.
+ *
+ * POSIX only — Windows npm bins are `.cmd`/`.ps1` shims, not symlinks, so this
+ * relink shape does not apply and the caller skips it there. `prefix` is the
+ * npm global prefix from {@link deriveGlobalPrefix}; the bun path uses its own
+ * bin layout and is out of scope.
+ */
+export function ensureGlobalBinLinks(packageRoot, prefix) {
+    let bin;
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8'));
+        bin = pkg && typeof pkg.bin === 'object' && pkg.bin !== null ? pkg.bin : {};
+    }
+    catch (err) {
+        throw new Error(`could not read bin entries from ${path.join(packageRoot, 'package.json')}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const binDir = path.join(prefix, 'bin');
+    const repairs = [];
+    for (const [name, rel] of Object.entries(bin)) {
+        if (typeof rel !== 'string' || !rel)
+            continue;
+        repairs.push(reconcileBinLink(name, path.join(binDir, name), path.resolve(packageRoot, rel)));
+    }
+    return repairs;
+}
 /**
  * The package root a resolved `agents` entrypoint belongs to, or null when the
  * path is not an agents-cli entry at all. Two shipped shapes:

package/dist/lib/session/cloud.js

@@ -29,6 +29,11 @@ function readToken() {
     if (!token) {
         throw new Error('No session token in ~/.rush/user.yaml. Run `rush login` first.');
     }
+    const expiresAt = data.session?.expires_at;
+    if (typeof expiresAt === 'number' && expiresAt <= Date.now() / 1000) {
+        const expiredAt = new Date(expiresAt * 1000).toISOString();
+        throw new Error(`Rush session expired at ${expiredAt}. Run \`rush login\` to refresh.`);
+    }
     return token;
 }
 async function api(method, endpoint, token) {