@phnx-labs/agents-cli 1.22.57 → 1.22.59

package/dist/lib/self-update.js

@@ -292,6 +292,56 @@ export function deriveGlobalPrefix(packageRoot) {
     const parent = path.dirname(nodeModulesDir);
     return path.basename(parent) === 'lib' ? path.dirname(parent) : parent;
 }
+/**
+ * Sweep npm arborist's "retired" staging dir for `packageRoot` before a
+ * reify (PHNX-3393).
+ *
+ * npm (@npmcli/arborist) reifies an install by first renaming the tree it is
+ * about to replace out of the way into a sibling directory —
+ * `retirePath(from)` in arborist's own source names it
+ * `.<basename>-<8-char sha1 hash of the full path>`, sibling to `from` — then
+ * stages the new tree and renames it into place. Because the hash is a pure
+ * function of `packageRoot`'s path, that staging path is IDENTICAL on every
+ * reify of this install. A crash between the retire-rename and the final
+ * rename (SIGKILL, a killed terminal, a box that lost power mid-upgrade)
+ * leaves that exact directory behind, non-empty. `rename(2)` cannot replace a
+ * non-empty directory, so every subsequent upgrade's reify fails ENOTEMPTY at
+ * the same path forever — nothing about a plain retry ever clears it.
+ *
+ * Removing any stale `.<basename>-*` sibling before install self-heals this:
+ * npm re-stages cleanly once the collision is gone. Matches only the
+ * retire-path shape (a dot-prefixed sibling starting with the package's own
+ * basename), so an unrelated dotfile in the same directory is left alone.
+ * Best-effort per entry: one unremovable sibling must not block the rest.
+ */
+export function sweepStaleInstallStaging(packageRoot) {
+    const resolved = path.resolve(packageRoot);
+    const dir = path.dirname(resolved);
+    const base = path.basename(resolved);
+    const escapedBase = base.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const stagingPattern = new RegExp(`^\\.${escapedBase}-[a-zA-Z0-9]+$`);
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const swept = [];
+    for (const entry of entries) {
+        if (!stagingPattern.test(entry))
+            continue;
+        const full = path.join(dir, entry);
+        try {
+            fs.rmSync(full, { recursive: true, force: true });
+            swept.push(full);
+        }
+        catch {
+            /* best-effort — one unremovable stager must not block the rest */
+        }
+    }
+    return swept;
+}
 /**
  * Install `spec` into an explicit global prefix. `--prefix` pins the
  * destination no matter which npm binary PATH resolves. `--ignore-scripts`
@@ -404,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/active.d.ts

@@ -55,7 +55,7 @@ export declare function attributedSetLostPids(prev: Set<number>, next: Set<numbe
 export declare function filterCachedUnattributed(sessions: ActiveSession[], attributed: Set<number>, alive: (pid: number, startedAtMs?: number) => boolean): ActiveSession[];
 type ActiveContext = 'terminal' | 'teams' | 'cloud' | 'headless';
 /** The SessionMeta fields the live-row backfill reads — the enrichment a running process cannot report. */
-export type BackfillMeta = Pick<SessionMeta, 'version' | 'timestamp' | 'label' | 'ticketId' | 'prUrl' | 'prNumber' | 'origin' | 'routineName' | 'harness'>;
+export type BackfillMeta = Pick<SessionMeta, 'version' | 'account' | 'timestamp' | 'label' | 'ticketId' | 'prUrl' | 'prNumber' | 'origin' | 'routineName' | 'harness'>;
 export declare function backfillActiveRowsFromMeta(sessions: ActiveSession[], metaById: Map<string, BackfillMeta>): void;
 export declare function backfillActiveRowsFromIndex(sessions: ActiveSession[]): void;
 export declare function isRunningLiveSession(s: ActiveSession): boolean;
@@ -201,6 +201,18 @@ export interface ActiveSession {
      * id (RUSH-2205), never asserted by a source.
      */
     version?: string;
+    /**
+     * Email of the account that produced the session (display-only). Like
+     * {@link version}, a running process does not report which account a
+     * `--strategy balanced` launch selected, so it is backfilled at render time
+     * from the indexed {@link SessionMeta} by session id (PHNX-3184). This is what
+     * the AGI EXT status bar renders as the session's account — it reads it off the
+     * `sessions watch --json` row instead of spawning a per-tab `agents sessions
+     * <id> --device <host> --json` (the 2026-08-25 CPU incident, agi-cli#3019).
+     * Never group on this — two orgs can share one email; group on the index's
+     * `accountKey`.
+     */
+    account?: string;
     /**
      * Last-activity epoch — the transcript's last write (mtime). Distinct from
      * {@link startedAtMs} (session START): a session begun 3h ago but last touched

package/dist/lib/session/active.js

@@ -145,6 +145,8 @@ export function backfillActiveRowsFromMeta(sessions, metaById) {
             continue;
         if (!s.version && m.version)
             s.version = m.version;
+        if (!s.account && m.account)
+            s.account = m.account;
         if (!s.label && m.label)
             s.label = m.label;
         if (!s.ticket && m.ticketId)

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) {

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

@@ -9,10 +9,11 @@
 import Database from '../sqlite.js';
 import type { SessionAgentId, SessionEvent, SessionMeta } from './types.js';
 import { type IndexedToolCall } from './tool-calls.js';
+import { type ToolScanResumePoint } from './tool-store.js';
 /** Current schema version; bumped when migrations are added. Exported so tests
  * assert against the constant instead of hardcoding a number that every bump
  * then has to chase (docs/sessions.md calls the constant the source of truth). */
-export declare const SCHEMA_VERSION = 42;
+export declare const SCHEMA_VERSION = 44;
 /**
  * Bump to force the content extractor (assistant-answer text, alongside the
  * user-prompt text every harness already accumulates) to re-derive on every
@@ -35,6 +36,8 @@ export declare const CONTENT_INDEX_VERSION = 1;
 export declare const INSIGHTS_EXTRACTOR_VERSION = 7;
 /** Bump when classifyTopic's output changes so cached topics recompute (human task taxonomy v2). */
 export declare const SESSION_TOPIC_EXTRACTOR_VERSION = 2;
+/** Bump when classifyPhenotype's output changes so cached phenotypes recompute (PHNX-3327 v1). */
+export declare const SESSION_PHENOTYPE_EXTRACTOR_VERSION = 1;
 /** File stat snapshot used to detect changes between scan runs. */
 export interface ScanStamp {
     fileMtimeMs: number;
@@ -249,6 +252,13 @@ export declare function upsertSessionsBatch(entries: Array<{
     toolCalls?: IndexedToolCall[];
     toolScan?: ScanStamp;
     toolIndexMode?: 'replace' | 'append';
+    /**
+     * Where the NEXT scan of this full-file-harness session may resume its tool
+     * index (PHNX-3411). Computed internally in the enrichment map below; not
+     * supplied by callers. Persisted alongside the tool ledger so an active
+     * session re-derives only its newly appended tool calls next tick.
+     */
+    toolResume?: ToolScanResumePoint | null;
 }>): void;
 /**
  * Sync labels for a set of sessions. For each id in the map, if the stored
@@ -307,6 +317,16 @@ export declare function getSessionExistenceCacheStats(): {
 };
 /** Query sessions from the database, applying filters and ordering by last-activity descending (default). */
 export declare function querySessions(options?: QueryOptions): SessionMeta[];
+/**
+ * Cheap query for the daemon's deferred tool-index pass (PHNX-3411).
+ *
+ * Returns the most-recently-active sessions whose parseSession reads a large
+ * flat transcript (kimi: wire.jsonl, grok: chat_history.jsonl). Their scanners
+ * produce no events, so upsertSessionsBatch skips them in the warm tick to
+ * avoid wedging the event loop. ensureToolIndex uses tool_scan_ledger stamps
+ * to skip already-current rows and applies byte/file budget caps.
+ */
+export declare function querySessionsForDeferredToolIndex(limit: number): SessionMeta[];
 /** Count sessions matching the given filter options. */
 export declare function countSessions(options?: QueryOptions): number;
 /** One grouped row in a cost/duration rollup. */
@@ -377,6 +397,15 @@ export declare function writeSessionTopics<T>(entries: Array<{
     fileSize: number | null;
     topic: T;
 }>): void;
+/** Read cached failure phenotypes only when their transcript byte stamps still match. */
+export declare function readSessionPhenotypes<T>(ids: string[]): Map<string, T>;
+/** Persist failure phenotypes against the exact transcript bytes used to classify them. */
+export declare function writeSessionPhenotypes<T>(entries: Array<{
+    id: string;
+    fileMtimeMs: number | null;
+    fileSize: number | null;
+    phenotype: T;
+}>): void;
 /** Read one derived preview only when it matches the transcript bytes on disk. */
 export declare function readSessionPreviewCache<T>(id: string, sourceStamp: {
     fileMtimeMs: number | null;
@@ -500,14 +529,30 @@ export declare function queryResourceUsageStats(options: QueryOptions & {
     limit?: number;
 }): ResourceStatRow[];
 /**
- * Coverage of the resource-usage signal: how many distinct sessions carry any
- * row in session_resource_usage vs. the total indexed. A low ratio means the
- * historical backfill (`agents sessions backfill resources`) hasn't run — the
- * stats surface uses this to tell the user their zero-counts may just be
- * un-scanned history, not genuine non-use.
+ * Coverage of the resource-usage signal, as three honest facts:
+ *
+ * - `scanned`  — sessions the resource extractor has actually processed, i.e.
+ *   those carrying a `resource_scan_ledger` row at the current
+ *   `RESOURCE_INDEX_VERSION`. This is the true "has the historical backfill run"
+ *   signal: the ledger is stamped for EVERY scanned session, including ones that
+ *   invoked nothing (`resource_count = 0`), so `scanned/total` rises to ~1 after
+ *   `agents sessions backfill resources` regardless of how sparse explicit
+ *   invocations are.
+ * - `covered`  — distinct sessions that carry AT LEAST ONE row in
+ *   `session_resource_usage`, i.e. that actually recorded an explicit invocation.
+ *   This is an ABSOLUTE signal count, not a coverage ratio: it stays small even
+ *   at full scan coverage because most sessions invoke no skill/command, and a
+ *   non-recording harness contributes none by construction.
+ * - `total`    — sessions indexed.
+ *
+ * The two were previously conflated: `covered/total` was framed as coverage and
+ * read ~1.2% even after a full backfill (most sessions genuinely invoke nothing),
+ * so the "run the backfill" hint never cleared. Keying the hint on `scanned/total`
+ * fixes that — see `commands/sessions-stats.ts` (PHNX-2301).
  */
 export declare function resourceUsageCoverage(): {
     covered: number;
+    scanned: number;
     total: number;
 };
 /** Outcome of a resource-usage backfill run. */