@phnx-labs/agents-cli 1.22.58 → 1.22.59

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

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

@@ -13,7 +13,7 @@ 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 = 43;
+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
@@ -317,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. */
@@ -519,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. */