@phnx-labs/agents-cli 1.20.92 → 1.20.93

package/dist/lib/project-resources.js

@@ -127,9 +127,37 @@ function record(kind, name, relPaths, result, manifestPaths) {
         manifestPaths.add(toPosixRel(rel));
 }
 function skip(dest, projectRoot, result) {
-    const rel = path.relative(projectRoot, dest);
-    result.skipped.push(rel);
-    console.warn(`Skipping project resource target ${rel}: already exists and is user-owned`);
+    result.skipped.push(path.relative(projectRoot, dest));
+}
+/**
+ * One human line for the files a project sync left alone because you already
+ * wrote them. This is the normal steady state — every sync of a project whose
+ * `.claude/commands/` you hand-authored hits it — so it is a single grouped
+ * line, not one wrapped warning per file, and it says "yours" rather than the
+ * internal "user-owned". Returns null when nothing was skipped.
+ */
+export function formatKeptProjectResources(skipped) {
+    if (skipped.length === 0)
+        return null;
+    const rels = [...skipped].sort((a, b) => a.localeCompare(b)).map(toPosixRel);
+    if (rels.length === 1)
+        return `Kept your existing ${rels[0]}`;
+    const byDir = new Map();
+    for (const rel of rels) {
+        const dir = rel.includes('/') ? rel.slice(0, rel.lastIndexOf('/')) : '.';
+        const names = byDir.get(dir) ?? [];
+        names.push(rel.slice(rel.lastIndexOf('/') + 1));
+        byDir.set(dir, names);
+    }
+    if (byDir.size === 1) {
+        const [dir, names] = [...byDir.entries()][0];
+        const PREVIEW = 3;
+        const preview = names.slice(0, PREVIEW).join(', ');
+        const more = names.length > PREVIEW ? `, +${names.length - PREVIEW} more` : '';
+        return `Kept ${rels.length} of your own files in ${dir}: ${preview}${more}`;
+    }
+    const dirs = [...byDir.entries()].map(([dir, names]) => `${dir} (${names.length})`).join(', ');
+    return `Kept ${rels.length} of your own files in ${dirs}`;
 }
 function syncProjectCommands(agent, version, projectAgentsDir, agentRoot, result, manifestPaths) {
     const cfg = AGENTS[agent];

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

@@ -13,6 +13,17 @@
  */
 import type { ActiveSession, ActiveStatus } from './session/active.js';
 import { type ProjectDef } from './projects.js';
+/** One live agent on a project — the WHO behind the byStatus count. */
+export interface ProjectMember {
+    /** Harness name (claude / codex / …), from the session's `kind`. */
+    agent: string;
+    /** Lifecycle status (running / idle / …). */
+    status: string;
+    /** Tracker ticket the session is tied to, when any. */
+    ticket?: string;
+    /** Machine the session runs on (provenance host / fleet peer), when known. */
+    host?: string;
+}
 /** One project's live session rollup. */
 export interface ProjectSessionRollup {
     name: string;
@@ -20,6 +31,8 @@ export interface ProjectSessionRollup {
     agents: number;
     /** Count per lifecycle status. */
     byStatus: Partial<Record<ActiveStatus, number>>;
+    /** Which agents are on the project (one per matched session). */
+    members: ProjectMember[];
     /** Summed checklist progress across this project's sessions. */
     plan: {
         done: number;
@@ -46,7 +59,20 @@ export declare function planPct(plan: {
     done: number;
     total: number;
 }): number | undefined;
-/** Harvested signals not on the session list: repo-global merged PRs + local artifacts, in a time window. */
+/** Sort members for the card: running first, then idle, then the rest; agent name asc within a state. */
+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;
+/**
+ * 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.
+ */
+export declare function formatProjectMembers(members: ProjectMember[], limit?: number): string;
+/** Harvested signals not on the session list: repo-global merged PRs + releases, local artifacts, in a time window. */
 export interface ProjectRemoteSignals {
     windowDays: number;
     /** PRs merged into the primary repo within the window (via `gh`). */
@@ -55,6 +81,11 @@ export interface ProjectRemoteSignals {
     artifacts: number;
     /** Basename of the most recent artifact, when any. */
     lastArtifact?: string;
+    /** Latest release of the PRIMARY repo (via `gh release list`), when any. */
+    latestRelease?: {
+        tag: string;
+        publishedAt: string;
+    };
 }
 /**
  * Harvest the signals that don't live on the active-session list: recently

package/dist/lib/project-status.js

@@ -13,11 +13,21 @@
  */
 import { execFile } from 'child_process';
 import { promisify } from 'util';
+import chalk from 'chalk';
 import { projectNameForCwd } from './projects.js';
 import { readRecentActivity } from './activity.js';
 const execFileAsync = promisify(execFile);
 function blank(name) {
-    return { name, agents: 0, byStatus: {}, plan: { done: 0, total: 0 }, openPrs: [], tickets: [], worktrees: 0 };
+    return {
+        name,
+        agents: 0,
+        byStatus: {},
+        members: [],
+        plan: { done: 0, total: 0 },
+        openPrs: [],
+        tickets: [],
+        worktrees: 0,
+    };
 }
 /**
  * Roll active sessions up by project. Returns a map keyed by project name,
@@ -41,6 +51,12 @@ export function rollupSessionsByProject(defs, sessions) {
         }
         r.agents++;
         r.byStatus[s.status] = (r.byStatus[s.status] ?? 0) + 1;
+        const member = { agent: s.kind, status: s.status };
+        if (s.ticket?.id)
+            member.ticket = s.ticket.id;
+        if (s.machine)
+            member.host = s.machine;
+        r.members.push(member);
         if (s.todos) {
             r.plan.done += s.todos.done;
             r.plan.total += s.todos.total;
@@ -67,6 +83,59 @@ export function planPct(plan) {
         return undefined;
     return Math.round((plan.done / plan.total) * 100);
 }
+/**
+ * Display order for the members line: the states a human scans for first
+ * (running, then idle, then need-input, then queued), everything else after,
+ * status name then agent name ascending within a state.
+ */
+const MEMBER_STATUS_RANK = { running: 0, idle: 1, input_required: 2, queued: 3 };
+/** Sort members for the card: running first, then idle, then the rest; agent name asc within a state. */
+export function sortProjectMembers(members) {
+    return [...members].sort((a, b) => {
+        const ra = MEMBER_STATUS_RANK[a.status] ?? 4;
+        const rb = MEMBER_STATUS_RANK[b.status] ?? 4;
+        if (ra !== rb)
+            return ra - rb;
+        if (ra === 4 && a.status !== b.status)
+            return a.status.localeCompare(b.status);
+        return a.agent.localeCompare(b.agent);
+    });
+}
+/** Cap for the members line before it collapses to `+N more`. */
+export const MEMBERS_LINE_LIMIT = 6;
+/**
+ * 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.
+ */
+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.
+    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 key = cell.toLowerCase();
+        const entry = counts.get(key);
+        if (entry)
+            entry.n++;
+        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`) : '');
+}
 /**
  * Harvest the signals that don't live on the active-session list: recently
  * merged PRs (from GitHub via `gh`) and artifacts agents produced (from the
@@ -96,6 +165,18 @@ export async function enrichProjectSignals(def, windowDays, nowMs, opts = {}) {
         catch {
             /* gh missing / unauthenticated / repo not found — skip this signal */
         }
+        // Latest release of the PRIMARY repo only (repos[] is deliberately not
+        // scanned — one release line per card). Same best-effort degradation.
+        try {
+            const { stdout } = await execFileAsync('gh', ['release', 'list', '-R', def.repo, '-L', '1', '--json', 'tagName,publishedAt'], { timeout: 8000, encoding: 'utf8' });
+            const rows = JSON.parse(stdout);
+            const first = rows[0];
+            if (first?.tagName)
+                out.latestRelease = { tag: first.tagName, publishedAt: first.publishedAt ?? '' };
+        }
+        catch {
+            /* gh missing / unauthenticated / repo has no releases — skip this signal */
+        }
     }
     return out;
 }

package/dist/lib/projects.d.ts

@@ -24,6 +24,12 @@ export interface ProjectRepo {
     slug: string;
     /** Optional path within the repo an agent working this project cares about. */
     subpath?: string;
+    /**
+     * Optional home-relative local checkout of this repo. The def's `root` only
+     * knows the primary repo on disk; `path` opts an additional repo into
+     * workspace probing (`projects status --fleet`).
+     */
+    path?: string;
 }
 /**
  * A described context anchor: a subdirectory plus what it is. Agents starting on

package/dist/lib/projects.js

@@ -86,9 +86,15 @@ export function validateProjectDef(raw, sourceName) {
         def.repos = o.repos.flatMap((r) => {
             if (r && typeof r === 'object' && typeof r.slug === 'string') {
                 const rr = r;
+                // A malformed `path` sinks the whole entry, like any other malformed
+                // list row — a half-valid repo must not probe a surprising location.
+                if (rr.path !== undefined && typeof rr.path !== 'string')
+                    return [];
                 const repo = { slug: rr.slug };
                 if (typeof rr.subpath === 'string')
                     repo.subpath = rr.subpath;
+                if (typeof rr.path === 'string')
+                    repo.path = rr.path;
                 return [repo];
             }
             return [];
@@ -192,6 +198,12 @@ export function writeProjectDef(def) {
         defaultPath: validated.defaultPath
             ? toHomeRelative(expandLocalHome(validated.defaultPath))
             : undefined,
+        repos: validated.repos?.map((r) => {
+            const repo = { ...r };
+            if (r.path)
+                repo.path = toHomeRelative(expandLocalHome(r.path));
+            return repo;
+        }),
     };
     // Drop undefined keys so the YAML stays clean.
     const clean = Object.fromEntries(Object.entries(normalized).filter(([, v]) => v !== undefined));

package/dist/lib/routine-notify.d.ts

@@ -26,6 +26,17 @@ import { type DesktopNotification } from './menubar/notify-desktop.js';
 type RoutineKind = 'agent' | 'workflow' | 'command';
 /** Which flavor of routine a config/meta describes — drives the notify threshold. */
 export declare function routineKind(r: Pick<JobConfig, 'agent' | 'workflow' | 'command'>): RoutineKind;
+/**
+ * The harness a routine runs on, for the notification's right-hand avatar, or
+ * undefined when none owns it. A command routine is deterministic housekeeping
+ * with no agent, so it gets no avatar. An agent routine names its own harness.
+ * A workflow routine has no `agent` field (the schema omits it — routines.ts
+ * `JobConfig.agent` and the validation that rejects setting both), and it runs
+ * via `agents run <workflow>`, which delegates to claude under the hood — so its
+ * avatar is the Claude mark, matching `effectiveAgent` on the finish path
+ * (runner.ts). Start and finish banners therefore show the same avatar.
+ */
+export declare function routineAgent(r: Pick<JobConfig, 'agent' | 'workflow' | 'command'>): string | undefined;
 /** "1m 20s" / "45s" / "2h 3m" from a millisecond duration, or null when unknown. */
 export declare function formatDuration(ms: number | undefined): string | null;
 /**

package/dist/lib/routine-notify.js

@@ -33,6 +33,24 @@ export function routineKind(r) {
         return 'workflow';
     return 'agent';
 }
+/**
+ * The harness a routine runs on, for the notification's right-hand avatar, or
+ * undefined when none owns it. A command routine is deterministic housekeeping
+ * with no agent, so it gets no avatar. An agent routine names its own harness.
+ * A workflow routine has no `agent` field (the schema omits it — routines.ts
+ * `JobConfig.agent` and the validation that rejects setting both), and it runs
+ * via `agents run <workflow>`, which delegates to claude under the hood — so its
+ * avatar is the Claude mark, matching `effectiveAgent` on the finish path
+ * (runner.ts). Start and finish banners therefore show the same avatar.
+ */
+export function routineAgent(r) {
+    const kind = routineKind(r);
+    if (kind === 'command')
+        return undefined;
+    if (kind === 'workflow')
+        return 'claude';
+    return r.agent?.trim() || undefined;
+}
 /** Human label for the routine body ("agent claude", "workflow deploy", "command"). */
 function routineLabel(r) {
     if (r.command)
@@ -90,6 +108,7 @@ export function routineStartNotification(config) {
         subtitle: config.name,
         body: `Running ${routineLabel(config)}`,
         action: 'routines:list',
+        agent: routineAgent(config),
     };
 }
 /**
@@ -108,6 +127,7 @@ export function routineStartFailedNotification(config, error) {
         subtitle: config.name,
         body: `Failed to start: ${error}`,
         action: 'routines:list',
+        agent: routineAgent(config),
     };
 }
 /**
@@ -131,6 +151,7 @@ export function routineFinishNotification(meta, opts = {}) {
             subtitle: meta.jobName,
             body: snippet ?? (dur ? `Completed in ${dur}` : 'Completed'),
             action,
+            agent: routineAgent(meta),
         };
     }
     // failed | timeout
@@ -144,6 +165,7 @@ export function routineFinishNotification(meta, opts = {}) {
         subtitle: meta.jobName,
         body: reason,
         action,
+        agent: routineAgent(meta),
     };
 }
 /** Read a finished run's report text + the best artifact to open on click. */

package/dist/lib/run-notify.js

@@ -34,6 +34,9 @@ export function buildRunFinishNotification(ctx, exitCode) {
     const n = {
         title: exitCode === 0 ? `${label} finished` : `${label} failed`,
         body: shorten(ctx.prompt?.trim() || `${ctx.agent} run`),
+        // The harness that ran becomes the banner's right-hand avatar, so a finished
+        // run is identifiable at a glance even when `--name` renamed the title.
+        agent: ctx.agent,
     };
     if (where)
         n.subtitle = where;

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

@@ -1,4 +1,4 @@
-export type SecretAuditEvent = 'secrets.get' | 'secrets.unlocked';
+export type SecretAuditEvent = 'secrets.get' | 'secrets.unlocked' | 'secrets.create' | 'secrets.import' | 'secrets.export' | 'secrets.view';
 export interface SecretAuditParams {
     /** Which audit event this is — a read (`secrets.get`) or an unlock grant. */
     event: SecretAuditEvent;

package/dist/lib/secrets/audit.js

@@ -1,16 +1,23 @@
 /**
- * Canonical audit emitter for `agents secrets` value access and unlock grants.
+ * Canonical audit emitter for every `agents secrets` lifecycle/access event.
  *
- * Every path that reads a secret VALUE or grants an unlock funnels its audit
- * through here, so the operational event stream — `agents events`, backed by the
- * append-only `~/.agents/events.jsonl` audit log — carries a uniform, value-free
- * provenance record: bundle, key NAMES, the resolving agent/harness identity,
- * operation, source, status. The ts / host / session / caller fields are filled
- * in by `emit()` itself. The secret VALUE is never part of the payload; this
- * helper only ever receives metadata, and `emit()`'s `sanitizePayload` is a
- * second redaction layer.
+ * This is the ONE write path for secret events. Every path that creates,
+ * imports, exports, views, reads a VALUE from, or unlocks a bundle funnels its
+ * audit through here, so the operational event stream — `agents events`, backed
+ * by the append-only `~/.agents/events.jsonl` audit log — carries a uniform,
+ * value-free provenance record: bundle, key NAMES, the resolving agent/harness
+ * identity, operation, source, status. The ts / host / session / caller fields
+ * are filled in by `emit()` itself. The secret VALUE is never part of the
+ * payload; this helper only ever receives metadata, and `emit()`'s
+ * `sanitizePayload` is a second redaction layer.
  *
- * Two event types, both audit-level and non-milestone (so they surface in
+ * The same call also mirrors the event into the per-bundle usage read-model DB
+ * (`~/.agents/secrets/secrets.db`, lib/secrets/usage-db.ts) so `secrets view` /
+ * `list` / `activity` can answer "how often / how recently / by whom was this
+ * bundle used?" without scanning the whole event stream — a DERIVED index fed
+ * off this chokepoint, not a second write path a caller has to remember.
+ *
+ * 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):
  *  - `secrets.get`      — a value was READ (exec inject, export, `view --reveal`,
@@ -19,8 +26,27 @@
  *  - `secrets.unlocked` — a bundle was GRANTED into the secrets broker / durable
  *                         session by `agents secrets unlock`, then readable
  *                         prompt-free for the grant TTL.
+ *  - `secrets.create`   — a new bundle was created.
+ *  - `secrets.import`   — keys were imported into a bundle (file / ssh / 1password).
+ *  - `secrets.export`   — a bundle's values were exported (file / shell / ssh /
+ *                         1password). Exporting also READS the values, so the
+ *                         underlying resolve emits its own `secrets.get`.
+ *  - `secrets.view`     — a bundle's (masked) metadata was inspected via `view`.
  */
 import { emit } from '../events.js';
+import { recordSecretUsage } from './usage-db.js';
+/**
+ * Map each audit event onto the usage-DB kind it is counted as. `secrets.get` is
+ * the injection/read access; the rest map 1:1 to their lifecycle kind.
+ */
+const USAGE_KIND = {
+    'secrets.get': 'access',
+    'secrets.unlocked': 'unlock',
+    'secrets.create': 'create',
+    'secrets.import': 'import',
+    'secrets.export': 'export',
+    'secrets.view': 'view',
+};
 /**
  * The agent/harness identity to attribute a secret access to. Explicit callers
  * (the bundle reader knows the scope it resolved under) win; otherwise fall back
@@ -53,4 +79,21 @@ export function emitSecretAudit(p) {
         ...(p.ttlMs !== undefined ? { ttlMs: p.ttlMs } : {}),
         ...(p.error !== undefined ? { error: p.error } : {}),
     });
+    // Mirror the event into the per-bundle usage read-model so `secrets view` /
+    // `list` / `activity` can report frequency and recency without scanning the
+    // whole event stream. Fed off THIS chokepoint alongside the events.jsonl
+    // write, never a second write path. Per-bundle only — a raw `secrets get
+    // <item>` has no bundle, so it stays in the events.jsonl audit but is not
+    // counted as bundle usage. Best-effort inside usage-db (swallows errors).
+    if (p.bundle) {
+        recordSecretUsage({
+            bundle: p.bundle,
+            event: USAGE_KIND[p.event],
+            agent,
+            host: p.host,
+            source: p.source,
+            status: p.status,
+            keyCount: p.keyCount,
+        });
+    }
 }

package/dist/lib/secrets/list-filter.d.ts

@@ -79,14 +79,29 @@ export interface FilterContext {
 }
 /** Does this bundle satisfy every set axis? Pure. */
 export declare function bundleMatchesFilter(b: SecretsBundle, f: SecretsListFilter, ctx: FilterContext): boolean;
-/** Sort fields for `--sort`. `name` is the default and matches `listBundles()`. */
-export declare const SORT_FIELDS: readonly ["name", "used", "created", "updated", "expiry"];
+/** Sort fields for `--sort`. `name` is the default and matches `listBundles()`.
+ * `used` is most-recently-used first and `uses` is most-frequently-accessed
+ * first; both read the value-free usage read-model (lib/secrets/usage-db.ts). */
+export declare const SORT_FIELDS: readonly ["name", "used", "uses", "created", "updated", "expiry"];
 export type SortField = typeof SORT_FIELDS[number];
+/**
+ * The two value-free usage facts `--sort used|uses` needs, keyed by bundle name.
+ * Kept as a minimal shape (not the full BundleUsageSummary) so this module stays
+ * pure and unit-testable without opening the SQLite read-model.
+ */
+export interface BundleUsageHint {
+    /** Most recent recorded event across all kinds, ISO 8601, or null. */
+    lastUsedAt: string | null;
+    /** Recorded `access` (read/inject) count — what `--sort uses` ranks on. */
+    uses: number;
+}
 export declare function parseSortField(raw: string | undefined): SortField;
 /** Sort a copy. Time fields are most-recent-first (the useful direction for
- * "what did I touch lately"); `expiry` is soonest-first; ties fall back to name
- * so the order is stable. */
-export declare function sortBundles(bundles: SecretsBundle[], field: SortField): SecretsBundle[];
+ * "what did I touch lately"); `uses` is most-frequently-accessed first; `expiry`
+ * is soonest-first; ties fall back to name so the order is stable. `usage`
+ * carries the value-free read-model facts `used`/`uses` rank on — when omitted,
+ * `used` falls back to the throttled `last_used` stamp and `uses` sees zero. */
+export declare function sortBundles(bundles: SecretsBundle[], field: SortField, usage?: Map<string, BundleUsageHint>): SecretsBundle[];
 /** Human summary of the active filters, for the empty state. `sessions` only
  * echoes --project/--all on a miss, which leaves you guessing which flag emptied
  * the list; naming every active axis is the difference between "nothing matched"

package/dist/lib/secrets/list-filter.js

@@ -171,8 +171,10 @@ export function bundleMatchesFilter(b, f, ctx) {
     }
     return true;
 }
-/** Sort fields for `--sort`. `name` is the default and matches `listBundles()`. */
-export const SORT_FIELDS = ['name', 'used', 'created', 'updated', 'expiry'];
+/** Sort fields for `--sort`. `name` is the default and matches `listBundles()`.
+ * `used` is most-recently-used first and `uses` is most-frequently-accessed
+ * first; both read the value-free usage read-model (lib/secrets/usage-db.ts). */
+export const SORT_FIELDS = ['name', 'used', 'uses', 'created', 'updated', 'expiry'];
 export function parseSortField(raw) {
     if (!raw)
         return 'name';
@@ -196,11 +198,17 @@ function soonestExpiry(b) {
     return soonest;
 }
 /** Sort a copy. Time fields are most-recent-first (the useful direction for
- * "what did I touch lately"); `expiry` is soonest-first; ties fall back to name
- * so the order is stable. */
-export function sortBundles(bundles, field) {
+ * "what did I touch lately"); `uses` is most-frequently-accessed first; `expiry`
+ * is soonest-first; ties fall back to name so the order is stable. `usage`
+ * carries the value-free read-model facts `used`/`uses` rank on — when omitted,
+ * `used` falls back to the throttled `last_used` stamp and `uses` sees zero. */
+export function sortBundles(bundles, field, usage) {
     const stamp = (iso) => (iso ? new Date(iso).getTime() : 0);
     const byName = (a, z) => a.name.localeCompare(z.name);
+    // `used` combines the throttled keychain stamp with the exact usage-DB recency
+    // so a just-recorded access ranks a bundle even before its stamp catches up.
+    const usedMs = (b) => Math.max(stamp(b.last_used), stamp(usage?.get(b.name)?.lastUsedAt));
+    const usesOf = (b) => usage?.get(b.name)?.uses ?? 0;
     const out = [...bundles];
     if (field === 'name')
         return out.sort(byName);
@@ -209,7 +217,15 @@ export function sortBundles(bundles, field) {
             const d = soonestExpiry(a) - soonestExpiry(z);
             return d !== 0 ? d : byName(a, z);
         }
-        const key = field === 'used' ? 'last_used' : field === 'created' ? 'created_at' : 'updated_at';
+        if (field === 'used') {
+            const d = usedMs(z) - usedMs(a);
+            return d !== 0 ? d : byName(a, z);
+        }
+        if (field === 'uses') {
+            const d = usesOf(z) - usesOf(a);
+            return d !== 0 ? d : byName(a, z);
+        }
+        const key = field === 'created' ? 'created_at' : 'updated_at';
         const d = stamp(z[key]) - stamp(a[key]);
         return d !== 0 ? d : byName(a, z);
     });

package/dist/lib/secrets/usage-db.d.ts

@@ -0,0 +1,106 @@
+/**
+ * SQLite-backed usage read-model for `agents secrets`.
+ *
+ * A small local database at ~/.agents/secrets/secrets.db that records one
+ * value-free row for every secret lifecycle/access event a bundle accrues over
+ * its life — created, imported, exported, viewed, accessed (read for injection),
+ * unlocked. It is the queryable, per-bundle counterpart to the append-only
+ * ~/.agents/events.jsonl audit log: the SAME chokepoint (`emitSecretAudit`,
+ * lib/secrets/audit.ts) feeds both, and this store answers "how often / how
+ * recently / by whom was THIS bundle used?" without scanning the whole event
+ * stream. It is a DERIVED index fed off the real access flow — the way
+ * sessions.db indexes session metadata — never a second write path an operation
+ * has to remember to call.
+ *
+ * Contract, mirroring the audit log: NEVER a secret value. Only metadata — the
+ * bundle name, the event kind, key counts, the resolving agent/host, a status.
+ *
+ * Every write is best-effort: a failure here (missing runtime SQLite, a locked
+ * db, a read-only fs) is swallowed so usage telemetry can never break secret
+ * resolution. Set AGENTS_NO_USAGE_TRACK=1 to disable recording entirely (used by
+ * tests and by callers that must stay perfectly silent).
+ */
+/** The lifecycle/access events a bundle accrues over its life. */
+export type SecretUsageEvent = 'access' | 'unlock' | 'import' | 'export' | 'create' | 'view';
+/** All event kinds, in the order `view` prints them. */
+export declare const SECRET_USAGE_EVENTS: readonly SecretUsageEvent[];
+export interface RecordUsageParams {
+    /** Bundle the event applies to (required — usage is always per-bundle). */
+    bundle: string;
+    /** What happened. */
+    event: SecretUsageEvent;
+    /** Resolving agent/harness identity, when known (`*` = a global grant). */
+    agent?: string;
+    /** Remote host the value was pulled from / pushed to, when applicable. */
+    host?: string;
+    /** Free-form origin label, e.g. 'agent', 'reveal', 'ssh', '1password'. */
+    source?: string;
+    /** Outcome; defaults to 'success'. */
+    status?: 'success' | 'error';
+    /** How many keys the event touched (names only are ever known here). */
+    keyCount?: number;
+}
+/** One event kind's rollup for a bundle. */
+export interface UsageStat {
+    count: number;
+    /** ISO 8601 timestamp of the most recent occurrence, or null if never. */
+    last: string | null;
+}
+/** Per-bundle usage summary for the `view` / `list` surfaces. */
+export interface BundleUsageSummary {
+    bundle: string;
+    /** Every recorded event, all kinds. */
+    total: number;
+    /** Rollup per event kind (every kind present, zeroed when unused). */
+    events: Record<SecretUsageEvent, UsageStat>;
+    /** Most recent event across all kinds, or null. */
+    lastUsedAt: string | null;
+    /** Earliest event across all kinds, or null. */
+    firstUsedAt: string | null;
+    /** Event count grouped by resolving agent, most-first. `*` = a global grant. */
+    byAgent: Array<{
+        agent: string;
+        count: number;
+    }>;
+}
+/** One recorded event, for the `secrets activity` timeline. */
+export interface SecretUsageHistoryEntry {
+    ts: string;
+    bundle: string;
+    event: SecretUsageEvent;
+    agent: string | null;
+    host: string | null;
+    source: string | null;
+    status: string | null;
+    keyCount: number | null;
+}
+/**
+ * Record one usage event. Best-effort and value-free — swallows every error and
+ * honors AGENTS_NO_USAGE_TRACK so telemetry never blocks or slows a read. Rows
+ * with an empty bundle name are ignored (usage is per-bundle by definition).
+ *
+ * This is called from ONE place only — `emitSecretAudit` (lib/secrets/audit.ts)
+ * — so every recorded event has already been written to the events.jsonl audit
+ * log through the same chokepoint. Do not call it from a command handler; emit
+ * the audit event instead.
+ */
+export declare function recordSecretUsage(p: RecordUsageParams): void;
+/**
+ * Usage summary for one bundle, or undefined when nothing has ever been
+ * recorded (or the DB is unavailable). Never throws.
+ */
+export declare function getBundleUsage(bundle: string): BundleUsageSummary | undefined;
+/**
+ * Usage summaries for every bundle that has any recorded event, keyed by bundle
+ * name. Powers `secrets list --sort uses|used`. Empty map when the DB is
+ * unavailable or has no rows. Never throws.
+ */
+export declare function getAllBundleUsage(): Map<string, BundleUsageSummary>;
+/**
+ * Recent events for the `secrets activity` timeline — one bundle when named,
+ * else across all bundles — newest first. Empty when the DB is unavailable.
+ * Never throws.
+ */
+export declare function getUsageHistory(bundle: string | undefined, limit?: number): SecretUsageHistoryEntry[];
+/** Close the cached handle. Used by tests between temp-db swaps. */
+export declare function closeSecretsUsageDb(): void;