@phnx-labs/agents-cli 1.22.5 → 1.22.7

package/dist/lib/project-focus.js

@@ -78,3 +78,26 @@ export async function readFocusAreas(root, windowDays) {
         return [];
     }
 }
+/** Compact count: 2329 → "2.3k", under 1000 stays exact. */
+export function formatFocusCount(n) {
+    if (!Number.isFinite(n) || n < 0)
+        return '0';
+    if (n < 1000)
+        return String(Math.round(n));
+    const k = n / 1000;
+    const s = k >= 10 ? String(Math.round(k)) : k.toFixed(1).replace(/\.0$/, '');
+    return `${s}k`;
+}
+/**
+ * One scannable focus line: path + count, with a single unit trailer so the
+ * bare integer is never mistaken for commits or minutes.
+ *
+ *   apps/cli/src 2.3k  ·  apps/cli/docs 302  ·  apps/factory/src 245  file-touches (7d)
+ */
+export function formatFocusAreas(areas, windowDays) {
+    if (areas.length === 0)
+        return '';
+    const body = areas.map((a) => `${a.path} ${formatFocusCount(a.touches)}`).join('  ·  ');
+    const unit = `file-touches (${windowDays}d)`;
+    return `${body}  ${unit}`;
+}

package/dist/lib/project-key.d.ts

@@ -2,7 +2,7 @@
  * The one worktree-aware cwd -> project fold.
  *
  * Several surfaces bucket work "by project": the `agents sessions` overview,
- * the `agents activity` timeline, and anything else that has a cwd and needs a
+ * the `agents feed` timeline, and anything else that has a cwd and needs a
  * stable repo-level key. They must agree, or the same session shows up under
  * `agents-cli` in one view and `my-branch-slug` in another — so the rule lives
  * here and every caller delegates.

package/dist/lib/project-key.js

@@ -2,7 +2,7 @@
  * The one worktree-aware cwd -> project fold.
  *
  * Several surfaces bucket work "by project": the `agents sessions` overview,
- * the `agents activity` timeline, and anything else that has a cwd and needs a
+ * the `agents feed` timeline, and anything else that has a cwd and needs a
  * stable repo-level key. They must agree, or the same session shows up under
  * `agents-cli` in one view and `my-branch-slug` in another — so the rule lives
  * here and every caller delegates.

package/dist/lib/project-probe.d.ts

@@ -73,3 +73,21 @@ export declare function formatWorkspaceLine(s: RepoWorkspaceStatus): string;
  * `fleet` row label.
  */
 export declare function formatFleetWorkspaces(statuses: HostWorkspaceStatus[]): string[];
+/** Severity for a workspace/repo warning on the project card. */
+export type WorkspaceWarningSeverity = 'critical' | 'continue';
+export interface WorkspaceWarning {
+    severity: WorkspaceWarningSeverity;
+    text: string;
+    remediation?: string;
+}
+/**
+ * Turn probed workspace rows into card-footer warnings.
+ *
+ * - missing / unreadable git → critical (agents there cannot share a tree)
+ * - behind upstream → critical when ≥10 commits, continue otherwise
+ * - dirty tree → continue (local work is fine; just note it)
+ * - ahead-only is not a warning (that is progress waiting to push)
+ *
+ * Pure. Caller decides whether the rows came from `--fleet` or a local probe.
+ */
+export declare function workspaceWarnings(statuses: HostWorkspaceStatus[]): WorkspaceWarning[];

package/dist/lib/project-probe.js

@@ -158,3 +158,49 @@ export function formatFleetWorkspaces(statuses) {
         return multi ? `${chalk.dim(`${p} · `)}${body}` : body;
     });
 }
+/**
+ * Turn probed workspace rows into card-footer warnings.
+ *
+ * - missing / unreadable git → critical (agents there cannot share a tree)
+ * - behind upstream → critical when ≥10 commits, continue otherwise
+ * - dirty tree → continue (local work is fine; just note it)
+ * - ahead-only is not a warning (that is progress waiting to push)
+ *
+ * Pure. Caller decides whether the rows came from `--fleet` or a local probe.
+ */
+export function workspaceWarnings(statuses) {
+    const out = [];
+    for (const s of [...statuses].sort((a, b) => a.host.localeCompare(b.host) || a.path.localeCompare(b.path))) {
+        const where = s.host ? `${s.host}` : 'local';
+        const pathBit = s.path ? ` (${s.path})` : '';
+        if (!s.present) {
+            out.push({
+                severity: 'critical',
+                text: `${where}: checkout missing${pathBit}`,
+                remediation: 'clone or sync the project root on that host before landing agents there',
+            });
+            continue;
+        }
+        if (s.error) {
+            out.push({
+                severity: 'critical',
+                text: `${where}: ${s.error}${pathBit}`,
+            });
+            continue;
+        }
+        if (s.behind !== undefined && s.behind > 0) {
+            out.push({
+                severity: s.behind >= 10 ? 'critical' : 'continue',
+                text: `${where} is ${s.behind} commit${s.behind === 1 ? '' : 's'} behind ${s.upstream ?? 'upstream'}${pathBit}`,
+                remediation: 'pull (or rebase) before agents on this host open PRs against a stale base',
+            });
+        }
+        if (s.dirty !== undefined && s.dirty > 0) {
+            out.push({
+                severity: 'continue',
+                text: `${where} has ${s.dirty} uncommitted change${s.dirty === 1 ? '' : 's'}${pathBit}`,
+            });
+        }
+    }
+    return out;
+}

package/dist/lib/project-status.d.ts

@@ -53,6 +53,13 @@ export interface ProjectSessionRollup {
  * containing only projects with at least one matched session — callers merge
  * with the full definition list to show zero-agent projects.
  */
+/**
+ * Ensure every session carries a host for the card roster. Local
+ * `getActiveSessions()` omits `machine`; remotes already set it. Pure.
+ */
+export declare function withDefaultMachine<T extends {
+    machine?: string;
+}>(sessions: T[], defaultHost: string): T[];
 export declare function rollupSessionsByProject(defs: ProjectDef[], sessions: ActiveSession[]): Map<string, ProjectSessionRollup>;
 /**
  * True when a session's status means it is over. Exported so the card can keep
@@ -84,6 +91,19 @@ export declare function liveDeadSplit(byStatus: Partial<Record<ActiveStatus, num
 export declare function sortProjectMembers(members: ProjectMember[]): ProjectMember[];
 /** Cap for the members line before it collapses to `+N more`. */
 export declare const MEMBERS_LINE_LIMIT = 6;
+/** Cap for host groups on the multi-line agents roster. */
+export declare const MEMBERS_HOST_LIMIT = 8;
+/**
+ * Collapse members into distinct state cells (`agent · status · ticket[@host]`),
+ * counting duplicates as `×N`. Pure.
+ */
+export declare function collapseMemberCells(members: ProjectMember[], opts?: {
+    includeHostOnCell?: boolean;
+}): Array<{
+    cell: string;
+    n: number;
+    members: number;
+}>;
 /**
  * The `agents` line under `live`: one cell per DISTINCT member state —
  * `claude · running · RUSH-2107 @zion` — with identical cells collapsed to a
@@ -91,8 +111,44 @@ export declare const MEMBERS_LINE_LIMIT = 6;
  * truncated duplicates), capped at {@link MEMBERS_LINE_LIMIT} cells with a
  * `+N more` tail counting members, not cells. Pure (chalk styling only); the
  * caller adds the label.
+ *
+ * Prefer {@link formatProjectMembersByHost} on the card: a flat line hides which
+ * machine is running the work when the same harness×status spans hosts.
  */
 export declare function formatProjectMembers(members: ProjectMember[], limit?: number): string;
+/**
+ * Host-grouped agents roster. One content line per host:
+ * `@zion  claude · running ×9  ·  claude · idle ×4`
+ *
+ * When no member carries a host (local-only rollup with no machine stamp), falls
+ * back to a single flat line via {@link formatProjectMembers}. Pure.
+ */
+export declare function formatProjectMembersByHost(members: ProjectMember[], opts?: {
+    cellLimit?: number;
+    hostLimit?: number;
+}): string[];
+/** A card-level warning collected for the footer. */
+export type ProjectWarningSeverity = 'critical' | 'continue';
+export interface ProjectWarning {
+    severity: ProjectWarningSeverity;
+    /** One human line. */
+    text: string;
+    /** Optional fix or next step. */
+    remediation?: string;
+}
+/**
+ * Severity markers for the warnings footer. User-facing by design: critical
+ * stops you (wrong repo, missing checkout, large drift); continue is a soft
+ * nudge (dirty tree, schedule not measurable).
+ */
+export declare function warningEmoji(severity: ProjectWarningSeverity): string;
+/** Stable sort: critical first, then continue; stable within a tier. */
+export declare function sortProjectWarnings(warnings: ProjectWarning[]): ProjectWarning[];
+/**
+ * Format one or more warning lines for the card footer. Pure (chalk only).
+ * Returns empty when there is nothing to say.
+ */
+export declare function formatProjectWarnings(warnings: ProjectWarning[]): string[];
 /** Harvested signals not on the session list: repo-global merged PRs + releases, local artifacts, in a time window. */
 export interface ProjectRemoteSignals {
     windowDays: number;

package/dist/lib/project-status.js

@@ -41,6 +41,13 @@ function blank(name) {
  * containing only projects with at least one matched session — callers merge
  * with the full definition list to show zero-agent projects.
  */
+/**
+ * Ensure every session carries a host for the card roster. Local
+ * `getActiveSessions()` omits `machine`; remotes already set it. Pure.
+ */
+export function withDefaultMachine(sessions, defaultHost) {
+    return sessions.map((s) => (s.machine ? s : { ...s, machine: defaultHost }));
+}
 export function rollupSessionsByProject(defs, sessions) {
     const map = new Map();
     const prSeen = new Map();
@@ -148,25 +155,20 @@ export function sortProjectMembers(members) {
 }
 /** Cap for the members line before it collapses to `+N more`. */
 export const MEMBERS_LINE_LIMIT = 6;
+/** Cap for host groups on the multi-line agents roster. */
+export const MEMBERS_HOST_LIMIT = 8;
 /**
- * The `agents` line under `live`: one cell per DISTINCT member state —
- * `claude · running · RUSH-2107 @zion` — with identical cells collapsed to a
- * `×N` count (35 same-harness sessions in one state are one fact, not six
- * truncated duplicates), capped at {@link MEMBERS_LINE_LIMIT} cells with a
- * `+N more` tail counting members, not cells. Pure (chalk styling only); the
- * caller adds the label.
+ * Collapse members into distinct state cells (`agent · status · ticket[@host]`),
+ * counting duplicates as `×N`. Pure.
  */
-export function formatProjectMembers(members, limit = MEMBERS_LINE_LIMIT) {
-    if (members.length === 0)
-        return '';
-    // Collapse identical cells — 35 same-harness sessions in the same state are
-    // one fact (`claude · running ×16`), not six truncated duplicates.
+export function collapseMemberCells(members, opts = {}) {
+    const includeHost = opts.includeHostOnCell !== false;
     const counts = new Map();
     for (const m of sortProjectMembers(members)) {
         const parts = [m.agent, m.status];
         if (m.ticket)
             parts.push(m.ticket);
-        const cell = parts.join(' · ') + (m.host ? ` @${m.host}` : '');
+        const cell = parts.join(' · ') + (includeHost && m.host ? ` @${m.host}` : '');
         const key = cell.toLowerCase();
         const entry = counts.get(key);
         if (entry)
@@ -174,12 +176,117 @@ export function formatProjectMembers(members, limit = MEMBERS_LINE_LIMIT) {
         else
             counts.set(key, { cell, n: 1 });
     }
-    const entries = [...counts.values()];
-    const shown = entries.slice(0, Math.max(1, limit));
-    const shownMembers = shown.reduce((acc, e) => acc + e.n, 0);
-    const more = members.length - shownMembers;
-    const cells = shown.map(({ cell, n }) => (n > 1 ? `${cell} ×${n}` : cell));
-    return cells.join(chalk.dim('  ·  ')) + (more > 0 ? chalk.dim(`  ·  +${more} more`) : '');
+    return [...counts.values()].map(({ cell, n }) => ({ cell, n, members: n }));
+}
+function formatCollapsedCells(cells, memberTotal, limit) {
+    if (cells.length === 0)
+        return '';
+    const shown = cells.slice(0, Math.max(1, limit));
+    const shownMembers = shown.reduce((acc, e) => acc + e.members, 0);
+    const more = memberTotal - shownMembers;
+    const parts = shown.map(({ cell, n }) => (n > 1 ? `${cell} ×${n}` : cell));
+    return parts.join(chalk.dim('  ·  ')) + (more > 0 ? chalk.dim(`  ·  +${more} more`) : '');
+}
+/**
+ * The `agents` line under `live`: one cell per DISTINCT member state —
+ * `claude · running · RUSH-2107 @zion` — with identical cells collapsed to a
+ * `×N` count (35 same-harness sessions in one state are one fact, not six
+ * truncated duplicates), capped at {@link MEMBERS_LINE_LIMIT} cells with a
+ * `+N more` tail counting members, not cells. Pure (chalk styling only); the
+ * caller adds the label.
+ *
+ * Prefer {@link formatProjectMembersByHost} on the card: a flat line hides which
+ * machine is running the work when the same harness×status spans hosts.
+ */
+export function formatProjectMembers(members, limit = MEMBERS_LINE_LIMIT) {
+    if (members.length === 0)
+        return '';
+    return formatCollapsedCells(collapseMemberCells(members, { includeHostOnCell: true }), members.length, limit);
+}
+/**
+ * Host-grouped agents roster. One content line per host:
+ * `@zion  claude · running ×9  ·  claude · idle ×4`
+ *
+ * When no member carries a host (local-only rollup with no machine stamp), falls
+ * back to a single flat line via {@link formatProjectMembers}. Pure.
+ */
+export function formatProjectMembersByHost(members, opts = {}) {
+    if (members.length === 0)
+        return [];
+    const cellLimit = opts.cellLimit ?? MEMBERS_LINE_LIMIT;
+    const hostLimit = opts.hostLimit ?? MEMBERS_HOST_LIMIT;
+    const byHost = new Map();
+    let anyHost = false;
+    for (const m of members) {
+        if (m.host)
+            anyHost = true;
+        const key = m.host ?? '';
+        const list = byHost.get(key);
+        if (list)
+            list.push(m);
+        else
+            byHost.set(key, [m]);
+    }
+    // Local-only (no host stamps at all) — keep the compact one-liner.
+    if (!anyHost) {
+        const line = formatProjectMembers(members, cellLimit);
+        return line ? [line] : [];
+    }
+    // Hosts with the most members first, then name; unstamped ("") last.
+    const hosts = [...byHost.entries()].sort((a, b) => {
+        if (a[0] === '' && b[0] !== '')
+            return 1;
+        if (b[0] === '' && a[0] !== '')
+            return -1;
+        if (b[1].length !== a[1].length)
+            return b[1].length - a[1].length;
+        return a[0].localeCompare(b[0]);
+    });
+    const shownHosts = hosts.slice(0, Math.max(1, hostLimit));
+    const hiddenMembers = hosts.slice(hostLimit).reduce((acc, [, ms]) => acc + ms.length, 0);
+    const hostWidth = Math.max(...shownHosts.map(([h]) => (h ? `@${h}` : '@local').length), 1);
+    const lines = shownHosts.map(([host, ms]) => {
+        const label = (host ? `@${host}` : '@local').padEnd(hostWidth);
+        // Host is the row key — do not repeat @host on every cell.
+        const cells = collapseMemberCells(ms, { includeHostOnCell: false });
+        const body = formatCollapsedCells(cells, ms.length, cellLimit);
+        return `${chalk.cyan(label)}  ${body}`;
+    });
+    if (hiddenMembers > 0) {
+        const restHosts = hosts.length - shownHosts.length;
+        lines.push(chalk.dim(`+${hiddenMembers} more on ${restHosts} host${restHosts === 1 ? '' : 's'}`));
+    }
+    return lines;
+}
+/**
+ * Severity markers for the warnings footer. User-facing by design: critical
+ * stops you (wrong repo, missing checkout, large drift); continue is a soft
+ * nudge (dirty tree, schedule not measurable).
+ */
+export function warningEmoji(severity) {
+    return severity === 'critical' ? '🔴' : '⚠️';
+}
+/** Stable sort: critical first, then continue; stable within a tier. */
+export function sortProjectWarnings(warnings) {
+    const rank = { critical: 0, continue: 1 };
+    return [...warnings].sort((a, b) => rank[a.severity] - rank[b.severity] || a.text.localeCompare(b.text));
+}
+/**
+ * Format one or more warning lines for the card footer. Pure (chalk only).
+ * Returns empty when there is nothing to say.
+ */
+export function formatProjectWarnings(warnings) {
+    if (warnings.length === 0)
+        return [];
+    const lines = [];
+    for (const w of sortProjectWarnings(warnings)) {
+        const mark = warningEmoji(w.severity);
+        const color = w.severity === 'critical' ? chalk.red : chalk.yellow;
+        lines.push(`  ${mark}  ${color(w.text)}`);
+        if (w.remediation)
+            lines.push(`      ${chalk.dim(w.remediation)}`);
+    }
+    return lines;
 }
 /**
  * Harvest the signals that don't live on the active-session list: recently

package/dist/lib/resources/mcp.js

@@ -124,6 +124,9 @@ export function getMcpConfigPath(agent, versionHome) {
             return path.join(versionHome, '.grok', 'mcp.json');
         case 'hermes':
             return path.join(versionHome, '.hermes', 'config.yaml');
+        case 'pi':
+            // omp reads user-scope MCP from ~/.omp/agent/.mcp.json (Claude schema).
+            return path.join(versionHome, '.omp', 'agent', '.mcp.json');
         default:
             return null;
     }

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

@@ -5,7 +5,7 @@
  * - Union: All resources from all layers are combined
  * - Override on name conflict: Higher layer wins (project > user > system)
  */
-export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'kiro' | 'goose' | 'antigravity' | 'grok' | 'kimi' | 'droid' | 'hermes';
+export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'kiro' | 'goose' | 'antigravity' | 'grok' | 'kimi' | 'droid' | 'hermes' | 'pi';
 export type Layer = 'system' | 'user' | 'project';
 export type ResourceKind = 'command' | 'hook' | 'skill' | 'rule' | 'mcp' | 'permission' | 'subagent' | 'workflow' | 'memory';
 /** A resolved resource with its origin layer. */

package/dist/lib/secrets/audit.js

@@ -19,7 +19,7 @@
  *
  * The event vocabulary, all audit-level and non-milestone (so they surface in
  * `agents events` and the persisted audit trail, but are NOT required in the
- * curated `agents activity` / `agents feed` surfaces):
+ * curated `agents feed` surface):
  *  - `secrets.get`      — a value was READ (exec inject, export, `view --reveal`,
  *                         raw `get <item>`, remote resolve, sync push,
  *                         `run --secrets`, and every other bundle read).

package/dist/lib/secrets/index.d.ts

@@ -121,6 +121,7 @@ export declare function withRawKeychainServiceNames<T>(fn: () => T): T;
  * the re-key migration and tests; runtime callers go through the primitives,
  * which apply this transparently. */
 export declare function hashedServiceName(item: string, key: Buffer): string;
+export declare function readHmacKeyRecord(): HmacKeyRecord | null;
 /**
  * Heal a `hmackey` item that an OLD helper (pre the metadata/hmackey no-ACL
  * migration fix) re-stamped with a biometry ACL. Such an item makes EVERY hashed

package/dist/lib/secrets/index.js

@@ -235,7 +235,7 @@ function parseHmacKeyRecord(raw) {
     }
     return null;
 }
-function readHmacKeyRecord() {
+export function readHmacKeyRecord() {
     // HMAC_KEY_ITEM is exempt from the transform, so this routes to the helper
     // (or the test backend) under its literal name. The item is no-ACL, so the
     // read is silent — attest that to the storm guard so a headless hashed-name
@@ -247,7 +247,30 @@ function readHmacKeyRecord() {
     catch {
         return null;
     }
-    return parseHmacKeyRecord(raw);
+    const record = parseHmacKeyRecord(raw);
+    // Converge a stale-ACL'd hmackey to silent, on the HOT read path. An old helper
+    // (pre the metadata/hmackey no-ACL migration fix) re-stamped this
+    // contractually-no-ACL item with a biometry ACL, so the read just above pops the
+    // generic "Agents CLI needs to authenticate" sheet on EVERY hashed lookup — the
+    // `agents devices list` stats probe the SessionStart hook runs, and every other
+    // background hashed read. `maybeAutoRekey`'s one-shot heal only fires on a
+    // cleartext-bundle resolve and is bypassed for the hmackey/hashed-name path
+    // (prepareServiceName returns early for HMAC_KEY_ITEM before maybeAutoRekey), so
+    // it never converged exactly these reads and the machine prompted forever.
+    // Re-store the record no-ACL once per machine here (the read that produced it has
+    // already happened — and already prompted if the item was ACL'd); every
+    // subsequent read, in this process and all future ones, is silent.
+    if (record && !record.healedNoAcl) {
+        try {
+            healHmacKeyNoAclOnce(record);
+            record.healedNoAcl = true;
+        }
+        catch {
+            // A failed no-ACL re-store leaves the item still ACL'd (a still-prompting
+            // read) rather than a silent wrong state; the next process retries.
+        }
+    }
+    return record;
 }
 function writeHmacKeyRecord(rec) {
     // JSON.stringify drops undefined fields (used to clear pendingDeletes).
@@ -423,19 +446,10 @@ function maybeAutoRekey() {
         return;
     const st = resolveHashState();
     if (st.active) {
-        // Heal an already-active machine whose hmackey was re-stamped ACL'd by an old
-        // helper (its read popped the generic Touch ID sheet on every hashed lookup).
-        // Runs once per machine; mutate the local so a later finishPendingDeletes write
-        // preserves the healed flag.
-        if (st.record && !st.record.healedNoAcl) {
-            try {
-                healHmacKeyNoAclOnce(st.record);
-                st.record.healedNoAcl = true;
-            }
-            catch {
-                /* next process retries */
-            }
-        }
+        // The stale-ACL'd-hmackey heal now runs on the hot read path
+        // (readHmacKeyRecord), which the resolveHashState() above just went through —
+        // so st.record is already healed here regardless of how this machine reached
+        // "hashing active". Nothing to do but finish any pending deletes.
         if (st.record?.pendingDeletes?.length) {
             try {
                 finishPendingDeletes(st.record);

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

@@ -46,7 +46,7 @@ export declare function resolveHostSshTarget(nameOrAlias: string): Promise<strin
  * Merge `--host <single>` / `--hosts <a,b,c>` (and their `--device` / `--devices`
  * aliases) into an ordered, de-duplicated list. All four flags compose; any alone
  * works. `--device`/`--devices` resolve identically to `--host`/`--hosts` so the
- * fleet-wide `--device` vocabulary (see `agents activity`, `agents run --device`)
+ * fleet-wide `--device` vocabulary (see `agents run --device`, `agents feed --host`)
  * works on the secrets remote commands too. Empty when none is set.
  */
 export declare function parseHostsOption(opts: {

package/dist/lib/secrets/remote.js

@@ -77,7 +77,7 @@ export async function resolveHostSshTarget(nameOrAlias) {
  * Merge `--host <single>` / `--hosts <a,b,c>` (and their `--device` / `--devices`
  * aliases) into an ordered, de-duplicated list. All four flags compose; any alone
  * works. `--device`/`--devices` resolve identically to `--host`/`--hosts` so the
- * fleet-wide `--device` vocabulary (see `agents activity`, `agents run --device`)
+ * fleet-wide `--device` vocabulary (see `agents run --device`, `agents feed --host`)
  * works on the secrets remote commands too. Empty when none is set.
  */
 export function parseHostsOption(opts) {

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

@@ -58,6 +58,8 @@ export interface ActiveSession {
     pid?: number;
     sessionId?: string;
     cwd?: string;
+    /** Project/repo key derived from cwd, when known. */
+    project?: string | null;
     /** User-given name from /rename command. */
     label?: string;
     /** Durable `agents run --name` launch handle, when the run was named. */

package/dist/lib/session/bash-command.d.ts

@@ -1,9 +1,8 @@
 /**
  * Parses the raw command strings agents pass to Bash tool calls into structured
  * metadata: the executable, category, subcommand, and a display summary. Used by
- * session rendering and the activity-log hook so `agents sessions` and
- * `agents activity` can summarize what actually happened instead of printing a
- * wall of shell.
+ * session rendering and the activity-log hook so `agents sessions` can
+ * summarize what actually happened instead of printing a wall of shell.
  */
 export type BashCategory = 'vcs' | 'build-test' | 'install' | 'remote' | 'http' | 'media' | 'upscaling' | 'metadata' | 'probe' | 'search' | 'shell' | 'wait' | 'other';
 export interface BashToolInfo {

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

@@ -12,7 +12,14 @@ import { type IndexedToolCall } from './tool-calls.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/05-sessions.md calls the constant the source of truth). */
-export declare const SCHEMA_VERSION = 30;
+export declare const SCHEMA_VERSION = 31;
+/**
+ * Bump to force `agents sessions backfill resources` to re-derive every
+ * session's skill/slash-command tallies on its next run (resource_scan_ledger
+ * rows with a lower version are treated as stale — the same mechanism
+ * TOOL_INDEX_VERSION gives the tool backfill).
+ */
+export declare const RESOURCE_INDEX_VERSION = 1;
 /** Raw row shape returned from the sessions table. */
 export interface SessionRow {
     id: string;
@@ -75,6 +82,8 @@ export interface QueryOptions {
     /** Match any session whose cwd equals this or is a descendant of it. */
     cwdPrefix?: string;
     project?: string;
+    /** Only sessions recorded on this machine (host), case-insensitive. */
+    machine?: string;
     /** Match the full session id or short id, case-insensitively (exact). */
     idExact?: string;
     /** Match sessions whose id or short id begins with this (case-insensitive prefix). */
@@ -324,6 +333,88 @@ export declare function queryAffinityRollup(options: {
 export declare function queryUsageRollup(options: QueryOptions & {
     groupBy: UsageRollupGroup;
 }): UsageRollupRow[];
+/** One aggregated resource (skill or slash-command) in a usage-stats rollup. */
+export interface ResourceStatRow {
+    /** 'skill' or 'command' (singular, as stored in session_resource_usage.kind). */
+    kind: string;
+    /** Stored resource name — bare, or `plugin:short` for a plugin-owned resource. */
+    name: string;
+    /** Owning plugin, or null for a flat (non-namespaced) resource. */
+    plugin: string | null;
+    /** DotAgents layer or plugin marketplace the resource resolved to at write time. */
+    source: string | null;
+    /** Distinct sessions that invoked this resource within the filter window. */
+    sessions: number;
+    /** Total invocations (sum of per-session counts) within the window. */
+    invocations: number;
+}
+/**
+ * Roll up skill / slash-command usage from session_resource_usage, joined to
+ * `sessions` for attribution so the same filter shape as querySessions
+ * (agent / project / since / machine) narrows WHICH sessions count. Grouped by
+ * resource identity (kind + name + plugin + source) and ordered by invocation
+ * volume — the read side of "which skills/commands do I actually use, and which
+ * are dead weight". `order: 'bottom'` ranks least-used first (the one-time
+ * skills); `limit` caps the returned rows.
+ *
+ * The signal only captures EXPLICIT invocations (slash commands and `Skill`
+ * tool calls). An auto-triggered skill (loaded by description match) emits no
+ * event, so it reads as zero here — a 0 means "never explicitly invoked", not
+ * "never loaded". Skill invocations are recorded for Claude and Kimi (the
+ * `Skill`-tool harnesses); slash-commands are Claude-only.
+ *
+ * `kind` / `pluginFilter` filter the RESOURCE rows directly (r.kind / r.plugin),
+ * distinct from QueryOptions.skill / QueryOptions.plugin, which filter SESSIONS
+ * — deliberately not routed through buildSessionWhere so `--plugin rush` shows
+ * only rush's resources rather than every resource used by a rush-touching
+ * session.
+ */
+export declare function queryResourceUsageStats(options: QueryOptions & {
+    kind?: 'skill' | 'command';
+    pluginFilter?: string;
+    order?: 'top' | 'bottom';
+    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.
+ */
+export declare function resourceUsageCoverage(): {
+    covered: number;
+    total: number;
+};
+/** Outcome of a resource-usage backfill run. */
+export interface ResourceBackfillResult {
+    /** Sessions considered (matched the filter, had a real transcript). */
+    scanned: number;
+    /** Sessions (re)parsed and written this run. */
+    updated: number;
+    /** Sessions already current at this extractor version, skipped. */
+    skipped: number;
+    /** Sessions whose transcript could not be stat'd or parsed. */
+    failed: number;
+    /** Total session_resource_usage rows written across updated sessions. */
+    resourceRows: number;
+}
+/**
+ * One-shot historical backfill of session_resource_usage (#12). The normal
+ * incremental scan writes resource usage only for sessions whose transcript it
+ * (re)parses; a session indexed before this feature shipped keeps a fresh
+ * scan_ledger row and is never re-derived, so its skill/slash-command tallies
+ * were never recorded. This walks the session index, re-parses each transcript
+ * FROM BYTE 0 (parseSession fully materializes — no resumable cursor, so
+ * claude/codex re-derive their tallies from scratch), writes the usage, and
+ * stamps resource_scan_ledger so reruns skip completed transcripts — the same
+ * independent-ledger shape `agents sessions backfill tools` uses.
+ *
+ * Harness-agnostic: parseSession + extractSkills/extractSlashCommands cover
+ * every agent uniformly, so there is no per-harness branch to keep in parity.
+ * Synthetic rows without a transcript (OpenClaw channels/cron) are skipped.
+ */
+export declare function backfillResourceUsage(filter?: QueryOptions, onProgress?: (done: number, total: number) => void): ResourceBackfillResult;
 /** Who spawned a team: the orchestrator session, from its transcript. */
 export interface TeamSpawner {
     sessionId: string;