@phnx-labs/agents-cli 1.20.92 → 1.21.0

package/dist/lib/routines.js

@@ -81,10 +81,67 @@ export function finalizeRunMeta(meta, status, exitCode, opts) {
  * catchup/overdue, manual run) gates on this.
  */
 export function jobRunsOnThisDevice(config) {
-    if (!config.devices || config.devices.length === 0)
+    const owner = routineOwnerDevice(config);
+    // Unrestricted: no pin means fleet-wide by design (`watchdog`, `check-updates`).
+    if (owner === null)
         return true;
-    const self = machineId();
-    return config.devices.some((d) => normalizeHost(d) === self);
+    return owner === machineId();
+}
+/**
+ * The ONE device that owns a routine — the single daemon allowed to fire it.
+ *
+ * `devices` is an allowlist, and every listed device used to fire
+ * independently, so a routine pinned to two boxes ran **twice** per schedule:
+ * two full agent sessions doing identical work, burning double the quota. On
+ * this fleet seven routines were in that state, e.g. `security-sweep` running
+ * at 15:30:02 on one box and 15:30:03 on the other, both completing.
+ *
+ * Ownership is a pure function of the config — the first entry in normalized
+ * sort order — so every daemon independently reaches the same answer with no
+ * lease, no cross-device coordination, and no split brain when the fleet
+ * partitions. A multi-entry pin is a misconfiguration
+ * ({@link hasAmbiguousDevicePin}); this keeps such a routine running exactly
+ * once instead of silently dropping it, while `validateJob` refuses to create
+ * a new one and `agents doctor` surfaces the existing ones.
+ *
+ * Returns null when the routine is unrestricted (empty or omitted `devices`).
+ */
+export function routineOwnerDevice(config) {
+    // A non-array `devices` is a separate validation error; don't throw here and
+    // don't double-report it.
+    if (!Array.isArray(config.devices))
+        return null;
+    const devices = config.devices.map((d) => normalizeHost(String(d))).filter(Boolean);
+    if (devices.length === 0)
+        return null;
+    return [...devices].sort()[0];
+}
+/**
+ * Does this routine name more than one distinct device? Such a pin used to mean
+ * "fire on each of them"; it now means "fire only on the first", which is
+ * almost certainly not what the author intended either way — so it is reported
+ * as a misconfiguration rather than silently reinterpreted.
+ */
+export function hasAmbiguousDevicePin(config) {
+    if (!Array.isArray(config.devices))
+        return false;
+    const devices = new Set(config.devices.map((d) => normalizeHost(String(d))).filter(Boolean));
+    return devices.size > 1;
+}
+/**
+ * Every routine carrying a multi-device pin. Surfaced by `agents doctor` and
+ * `agents routines list` so an existing misconfiguration is visible rather than
+ * silently reinterpreted: before ownership became singular each of these fired
+ * once per listed device, doubling the work and the agent spend.
+ */
+export function findAmbiguousDevicePins(cwd) {
+    return listJobs(cwd)
+        .filter((job) => job.enabled && hasAmbiguousDevicePin(job))
+        .map((job) => ({
+        name: job.name,
+        devices: (job.devices ?? []).map((d) => normalizeHost(d)),
+        owner: routineOwnerDevice(job) ?? '',
+    }));
 }
 /**
  * Resolve the effective host strategy for a job.
@@ -130,7 +187,10 @@ export function checkJobDeviceEligibility(config) {
         return null;
     const allowed = (config.devices ?? []).map((d) => normalizeHost(d));
     const allowedLabel = allowed.join(', ');
-    const firstHost = allowed[0] ?? 'HOST';
+    // The owner is the lowest normalized name, not the first entry as written —
+    // suggesting allowed[0] on an unsorted list points at a device that will
+    // refuse the run for exactly the same reason.
+    const firstHost = routineOwnerDevice(config) ?? allowed[0] ?? 'HOST';
     const message = `Job '${config.name}' can only run on: ${allowedLabel}`;
     const suggestion = `agents routines run ${config.name} --host ${firstHost}`;
     return { message, suggestion, allowedLabel, firstHost };
@@ -251,6 +311,17 @@ function readJobFile(filePath) {
         // treated as unavailable/inert rather than unrestricted.
         if (Object.prototype.hasOwnProperty.call(parsed, 'device'))
             return null;
+        // Fail closed on a malformed `devices` too. Ownership treats a non-array as
+        // "no pin", and the daemon's load path never calls validateJob — so a YAML
+        // typo (`devices: yosemite-s0` instead of a list) would silently promote the
+        // routine to fleet-wide and fire it on EVERY box. Inert-and-loud beats
+        // unrestricted-and-silent.
+        if (Object.prototype.hasOwnProperty.call(parsed, 'devices')
+            && parsed.devices !== undefined
+            && parsed.devices !== null
+            && !Array.isArray(parsed.devices)) {
+            return null;
+        }
         return {
             ...JOB_DEFAULTS,
             ...parsed,
@@ -523,6 +594,14 @@ export function validateJob(config) {
             }
         }
     }
+    // A routine belongs to exactly one device. Listing several used to fire it
+    // once per device — duplicate work, duplicate spend — and making them elect
+    // one owner at runtime would need cross-device coordination nobody wants.
+    if (hasAmbiguousDevicePin(config)) {
+        errors.push(`devices lists ${new Set(config.devices.map((d) => normalizeHost(String(d)))).size} devices; a routine runs on exactly one. ` +
+            'Pin the single device that should own it, e.g. devices: [yosemite-s0]. ' +
+            'Omit devices entirely for a routine that genuinely belongs on every machine.');
+    }
     if (config.catchup !== undefined && typeof config.catchup !== 'boolean') {
         errors.push('catchup must be a boolean (false to skip running a missed fire late)');
     }
@@ -946,6 +1025,28 @@ export function getJobPath(name) {
     }
     return null;
 }
+/**
+ * Resolve a routine's YAML across EVERY layer `listJobs`/`readJob` read — user
+ * then system — not just the user dir.
+ *
+ * `getJobPath` is user-layer only because its callers write there. Read paths
+ * that ask "when did this routine come to exist" need the system layer too:
+ * a built-in shipped in the system repo has no user-layer file and no
+ * `createdAt`, so a user-layer-only lookup returns null, the overdue floor is
+ * skipped, and the routine reads as instantly overdue on first daemon start —
+ * exactly the case the floor exists to prevent.
+ */
+export function resolveJobFilePath(name) {
+    const userPath = getJobPath(name);
+    if (userPath)
+        return userPath;
+    for (const ext of ['.yml', '.yaml']) {
+        const filePath = safeJoin(getSystemRoutinesDir(), name + ext);
+        if (fs.existsSync(filePath))
+            return filePath;
+    }
+    return null;
+}
 /**
  * Parse an "at" time string into a one-shot cron expression.
  * Supports formats like:

package/dist/lib/rules/run-sync.d.ts

@@ -0,0 +1,18 @@
+import type { AgentId } from '../types.js';
+/**
+ * Re-apply the active rules preset for (agent, version) into its version
+ * home when the composed source set has drifted since the last time this ran.
+ * Returns true when the version-home rules file was (re)written.
+ *
+ * No-cwd fingerprint on purpose: the version-home rules file never includes
+ * the project layer (see `staleness/writers/rules.ts` — project rules are
+ * resolved separately, at launch, into the workspace `AGENTS.md` by
+ * `compileRulesForProject`). Fingerprinting with a cwd would pull the project
+ * layer's subrules into the comparison and trigger a pointless version-home
+ * rewrite every time a project's own `.agents/rules/` changes.
+ *
+ * Silent on any failure (no rules.yaml, unknown preset, unsupported agent) —
+ * mirrors `syncResourcesToVersion`'s own catch-and-skip for rules: a bad
+ * preset must never block a launch, and this now also runs on the hot path.
+ */
+export declare function applyActiveRulesPresetAtRun(agent: AgentId, version: string, versionHome: string): boolean;

package/dist/lib/rules/run-sync.js

@@ -0,0 +1,92 @@
+/**
+ * Rules preset auto-apply at `agents run` launch time.
+ *
+ * `agents rules switch <agent>@<version> --preset <name>` persists the active
+ * preset (`state.ts:setActiveRulesPreset`) and immediately recompiles it into
+ * the version home via `syncResourcesToVersion` → the rules writer
+ * (`staleness/writers/rules.ts`). Same for `agents add`/`use`. But nothing
+ * re-applies the preset on a LATER `agents run` — if `setActiveRulesPreset`
+ * is ever called without a follow-up sync (or a subrule file changes after
+ * the last sync), the harness launches against a stale rules file until the
+ * next explicit `agents rules switch` / `agents sync`.
+ *
+ * This closes that gap the same way `runLaunchSync` (project-launch.ts)
+ * recompiles PROJECT rules on every launch: idempotent, and skip-fast when
+ * nothing changed. The skip-fast reuses the staleness checkers' mtime+size
+ * fingerprint comparison (`staleness/checkers/rules.ts`,
+ * `staleness/fingerprint.ts`) against a small per-(agent,version) sentinel —
+ * the same "hash the cheap inputs, compare, skip the write on a match" shape
+ * `installScope` (project-launch.ts) uses for plugin marketplaces. The common
+ * case (no preset or subrule change since the last run) costs one JSON read
+ * plus a handful of `stat()` calls — no recompose, no write.
+ *
+ * Version-level scope only — the active preset is keyed by (agent, version),
+ * matching `getActiveRulesPreset`. Per-model preset scoping is a follow-up.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { AGENTS } from '../agents.js';
+import { getActiveRulesPreset, getCacheDir } from '../state.js';
+import { getWriter } from '../staleness/registry.js';
+import { buildRules, isRulesStale } from '../staleness/checkers/rules.js';
+/** ~/.agents/.cache/rules-run-sync/ — regenerable; a lost sentinel just costs one extra compose+write. */
+function sentinelPath(agent, version) {
+    const key = `${agent}@${version}`.replace(/[^a-zA-Z0-9@._-]/g, '_');
+    return path.join(getCacheDir(), 'rules-run-sync', `${key}.json`);
+}
+function loadSentinel(agent, version) {
+    try {
+        return JSON.parse(fs.readFileSync(sentinelPath(agent, version), 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function saveSentinel(agent, version, sentinel) {
+    const p = sentinelPath(agent, version);
+    try {
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(p, JSON.stringify(sentinel));
+    }
+    catch {
+        // Best-effort — a failed write just means the next run redoes the compose+write.
+    }
+}
+/**
+ * Re-apply the active rules preset for (agent, version) into its version
+ * home when the composed source set has drifted since the last time this ran.
+ * Returns true when the version-home rules file was (re)written.
+ *
+ * No-cwd fingerprint on purpose: the version-home rules file never includes
+ * the project layer (see `staleness/writers/rules.ts` — project rules are
+ * resolved separately, at launch, into the workspace `AGENTS.md` by
+ * `compileRulesForProject`). Fingerprinting with a cwd would pull the project
+ * layer's subrules into the comparison and trigger a pointless version-home
+ * rewrite every time a project's own `.agents/rules/` changes.
+ *
+ * Silent on any failure (no rules.yaml, unknown preset, unsupported agent) —
+ * mirrors `syncResourcesToVersion`'s own catch-and-skip for rules: a bad
+ * preset must never block a launch, and this now also runs on the hot path.
+ */
+export function applyActiveRulesPresetAtRun(agent, version, versionHome) {
+    const cap = AGENTS[agent].capabilities.rules;
+    if (cap === false)
+        return false;
+    const rulesWriter = getWriter('rules', agent);
+    if (!rulesWriter)
+        return false;
+    const preset = getActiveRulesPreset(agent, version);
+    const current = buildRules(agent, version, '');
+    const stored = loadSentinel(agent, version);
+    if (stored && stored.preset === preset && !isRulesStale(stored.entry, agent, version, '')) {
+        return false; // skip-fast: preset unchanged AND composed source set unchanged
+    }
+    try {
+        rulesWriter.write({ version, versionHome, selection: { preset }, cwd: '' });
+    }
+    catch {
+        return false;
+    }
+    saveSentinel(agent, version, { preset, entry: current });
+    return true;
+}

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/scheduler.js

@@ -6,7 +6,7 @@
  * on startup and reloads them on SIGHUP.
  */
 import { Cron } from 'croner';
-import { listJobs, deleteJob, isPastEndAt, isPastOneShotRoutine, isOneShotRoutine, setJobEnabled, shouldPurgeCompletedOneShotRoutine, jobRunsOnThisDevice, } from './routines.js';
+import { listJobs, deleteJob, isPastEndAt, isPastOneShotRoutine, isOneShotRoutine, setJobEnabled, shouldPurgeCompletedOneShotRoutine, jobRunsOnThisDevice, hasAmbiguousDevicePin, routineOwnerDevice, } from './routines.js';
 /** In-memory cron scheduler that triggers a callback when jobs fire. */
 export class JobScheduler {
     jobs = new Map();
@@ -20,7 +20,17 @@ export class JobScheduler {
             // Trigger-only jobs (no cron schedule) fire via the webhook receiver,
             // not the cron loop — skip them here. Jobs pinned to another device
             // (routines are fleet-synced) never enter this machine's cron loop.
-            if (!config.enabled || !config.schedule || !jobRunsOnThisDevice(config))
+            if (!config.enabled || !config.schedule)
+                continue;
+            // A multi-device pin is a misconfiguration: it used to fire the routine
+            // once per listed device. It now fires only on the owner, but say so —
+            // silently reinterpreting someone's config is how this went unnoticed.
+            if (hasAmbiguousDevicePin(config)) {
+                const owner = routineOwnerDevice(config);
+                console.warn(`Job '${config.name}' pins ${config.devices.length} devices; a routine runs on exactly one. ` +
+                    `Firing only on '${owner}'. Fix with: agents routines devices ${config.name} --set ${owner}`);
+            }
+            if (!jobRunsOnThisDevice(config))
                 continue;
             if (shouldPurgeCompletedOneShotRoutine(config)) {
                 deleteJob(config.name);

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/index.d.ts

@@ -193,11 +193,10 @@ export declare function rekeyStatus(): {
  * Throws when the item cannot be reached — on macOS, when the signed helper is
  * unavailable. That is deliberate: this primitive gates destructive writes as
  * well as reads. Through `bundleExists()` it guards the `--force` overwrite
- * checks in `agents secrets create` (`../../commands/secrets.ts`), the
- * bundle-rename purge (`./bundles.ts`), the pull-rollback bookkeeping
- * (`./sync.ts`), and the reuse-never-overwrite rule for `R2_SYNC_ENC_KEY`
- * (`../session/sync/provision.ts`). A false "absent" silently disarms every one
- * of them, so an unreachable keychain must fail loudly rather than answer "no".
+ * checks in `agents secrets create` (`../../commands/secrets.ts`) and the
+ * bundle-rename purge (`./bundles.ts`), and the pull-rollback bookkeeping
+ * (`./sync.ts`). A false "absent" silently disarms every one of them, so an
+ * unreachable keychain must fail loudly rather than answer "no".
  *
  * Tests needing this path without a helper install a backend via
  * `setKeychainBackendForTest()`, which short-circuits on the next line.

package/dist/lib/secrets/index.js

@@ -680,11 +680,10 @@ export function rekeyStatus() {
  * Throws when the item cannot be reached — on macOS, when the signed helper is
  * unavailable. That is deliberate: this primitive gates destructive writes as
  * well as reads. Through `bundleExists()` it guards the `--force` overwrite
- * checks in `agents secrets create` (`../../commands/secrets.ts`), the
- * bundle-rename purge (`./bundles.ts`), the pull-rollback bookkeeping
- * (`./sync.ts`), and the reuse-never-overwrite rule for `R2_SYNC_ENC_KEY`
- * (`../session/sync/provision.ts`). A false "absent" silently disarms every one
- * of them, so an unreachable keychain must fail loudly rather than answer "no".
+ * checks in `agents secrets create` (`../../commands/secrets.ts`) and the
+ * bundle-rename purge (`./bundles.ts`), and the pull-rollback bookkeeping
+ * (`./sync.ts`). A false "absent" silently disarms every one of them, so an
+ * unreachable keychain must fail loudly rather than answer "no".
  *
  * Tests needing this path without a helper install a backend via
  * `setKeychainBackendForTest()`, which short-circuits on the next line.

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;