@phnx-labs/agents-cli 1.20.90 → 1.20.91

package/dist/commands/routines.js

@@ -19,9 +19,10 @@ import { fireWebhookJobs, matchJobsToWebhook } from '../lib/triggers/webhook.js'
 import { getRoutinesDir } from '../lib/state.js';
 import { IS_WINDOWS } from '../lib/platform/index.js';
 import { safeJoin } from '../lib/paths.js';
-import { executeJob, executeJobDetached, monitorRunningJobs, ROUTINE_AGENT_IDS } from '../lib/runner.js';
+import { executeJob, monitorRunningJobs, ROUTINE_AGENT_IDS } from '../lib/runner.js';
 import { JobScheduler } from '../lib/scheduler.js';
 import { detectOverdueJobs } from '../lib/overdue.js';
+import { runCatchup } from '../lib/catchup.js';
 import { isInteractiveTerminal, requireInteractiveSelection } from './utils.js';
 import { setHelpSections } from '../lib/help.js';
 import { loadDevices, loadDevicesSync } from '../lib/devices/registry.js';
@@ -242,7 +243,10 @@ function renderRoutineRows({ jobs, scheduler, overdueSet, link, now, local = tru
         const statusColor = lastStatus === 'completed' ? chalk.green
             : lastStatus === 'failed' ? chalk.red
                 : lastStatus === 'timeout' ? chalk.yellow
-                    : chalk.gray;
+                    // A miss is an infrastructure problem, not a task failure — the routine
+                    // never ran. Distinct from red so the two prompt different reactions.
+                    : lastStatus === 'missed' ? chalk.magenta
+                        : chalk.gray;
         const overdueTag = overdueSet.has(job.name) ? chalk.yellow(' (overdue)') : '';
         const agentLabelPadded = job.command
             ? chalk.magenta('command'.padEnd(10))
@@ -544,6 +548,7 @@ export function registerRoutinesCommands(program) {
                     sourceRepo: job.source?.repo ?? job.repo ?? null,
                     sourceBranch: job.source?.branch ?? null,
                     runOnce: Boolean(job.runOnce),
+                    catchup: job.catchup !== false,
                     oneShot: isOneShotRoutine(job),
                     expired: isPastOneShotRoutine(job, nowJson),
                     runsHere: jobRunsOnThisDevice(job),
@@ -622,6 +627,7 @@ export function registerRoutinesCommands(program) {
         .option('--state-to <name>', 'Linear current-state filter for --on linear:<event> (e.g. Plan)')
         .option('--state-from <name>', 'Linear previous-state filter for --on linear:<event> (e.g. Triage)')
         .option('--end-at <iso>', 'Stop firing on or after this ISO 8601 timestamp (e.g., "2026-12-31T23:59:00Z"); routine auto-disables.')
+        .option('--no-catchup', 'Do not run this routine late if its fire is missed (daemon down/asleep). The miss is still recorded. For routines whose value expires with their slot, e.g. a 9am brief.')
         .option('--disabled', 'Create the routine but keep it paused (enable later with resume)')
         .option('--resume <sessionId>', 'At fire time, resume this existing session id (via `agents run <agent> --resume`) instead of starting fresh — the actual session reopens with full context and the prompt becomes its next turn. Powers self-scheduled wake-ups (e.g. /hibernate). Requires --agent claude or codex; runs un-sandboxed (the session store lives in the real home, not the job overlay).')
         .option('--json', 'Emit machine-readable JSON with the created routine id and status')
@@ -734,6 +740,7 @@ export function registerRoutinesCommands(program) {
                 ...(hostStrategy ? { hostStrategy } : {}),
                 ...(options.runCwd ? { remoteCwd: options.runCwd } : {}),
                 ...(runOnce ? { runOnce: true } : {}),
+                ...(options.catchup === false ? { catchup: false } : {}),
                 ...(options.endAt ? { endAt: options.endAt } : {}),
                 ...(options.resume ? { resume: options.resume } : {}),
             };
@@ -1109,44 +1116,42 @@ export function registerRoutinesCommands(program) {
     });
     routinesCmd
         .command('catchup')
-        .description('Run any routines that missed their last scheduled fire (e.g. because your laptop was off). Detached — runs in the background under the scheduler.')
-        .option('--dry-run', 'List overdue routines without running them')
+        .description('Run any routines that missed their last scheduled fire on demand. The daemon already does this every 5 minutes — use this to force a pass now. Detached: runs in the background under the scheduler.')
+        .option('--dry-run', 'Record the misses and list them without running anything')
         .action(async (options) => {
         const overdue = detectOverdueJobs();
         if (overdue.length === 0) {
-            console.log(chalk.gray('No overdue routines.'));
+            console.log(chalk.gray('No missed fires.'));
             return;
         }
-        console.log(chalk.bold(`${overdue.length} overdue routine(s):\n`));
+        console.log(chalk.bold(`${overdue.length} missed fire(s):\n`));
         for (const job of overdue) {
             const last = job.lastRanAt ? job.lastRanAt.toLocaleString() : 'never';
             console.log(`  ${chalk.cyan(job.name)} — missed ${chalk.gray(job.expectedAt.toLocaleString())}, last ran ${chalk.gray(last)}`);
         }
-        if (options.dryRun) {
-            console.log(chalk.gray('\n(dry run — no jobs triggered)'));
-            return;
-        }
         // Need the daemon alive so spawned jobs are monitored and meta.json is
         // finalized. Start it if it isn't already running.
-        if (!isDaemonRunning()) {
+        if (!options.dryRun && !isDaemonRunning()) {
             const started = startDaemon();
             if (started.pid) {
                 console.log(chalk.gray(`\nStarted scheduler (PID: ${started.pid}) so catchup runs are monitored.`));
             }
         }
-        console.log(chalk.bold('\nTriggering catchup runs...'));
-        for (const job of overdue) {
-            const config = readJob(job.name);
-            if (!config) {
-                console.log(`  ${job.name} → ${chalk.red('config not found')}`);
-                continue;
+        console.log(chalk.bold(options.dryRun ? '\nRecording misses...' : '\nTriggering catchup runs...'));
+        const outcomes = await runCatchup({ overdue, dryRun: options.dryRun });
+        for (const o of outcomes) {
+            if (o.result === 'ran') {
+                console.log(`  ${o.name} → ${chalk.green('started')} (run: ${o.runId})`);
             }
-            try {
-                const meta = await executeJobDetached(config);
-                console.log(`  ${job.name} → ${chalk.green('started')} (run: ${meta.runId}, PID: ${meta.pid ?? 'n/a'})`);
+            else if (o.result === 'recorded') {
+                const why = options.dryRun ? 'dry run' : 'catchup: false';
+                console.log(`  ${o.name} → ${chalk.yellow('recorded as missed')} (${why})`);
             }
-            catch (err) {
-                console.log(`  ${job.name} → ${chalk.red('failed to start')}: ${err.message}`);
+            else if (o.result === 'claimed-elsewhere') {
+                console.log(`  ${o.name} → ${chalk.gray('already claimed by the scheduler')}`);
+            }
+            else {
+                console.log(`  ${o.name} → ${chalk.red('failed to start')}: ${o.error}`);
             }
         }
         console.log(chalk.gray('\nTrack progress with: agents routines runs <name>'));
@@ -1270,8 +1275,9 @@ export function registerRoutinesCommands(program) {
         // is the concise view. Falls back to a bounded stdout tail when no report
         // was extracted (e.g. the run failed before finishing).
         const statusColor = run.status === 'completed' ? chalk.green
-            : run.status === 'failed' || run.status === 'timeout' ? chalk.red
-                : chalk.yellow;
+            : run.status === 'missed' ? chalk.magenta
+                : run.status === 'failed' || run.status === 'timeout' ? chalk.red
+                    : chalk.yellow;
         console.log(chalk.bold(name) + chalk.gray(`  run ${runId}`));
         console.log(statusColor(run.status) +
             chalk.gray(`  ${run.startedAt}`) +

package/dist/commands/secrets.d.ts

@@ -9,6 +9,7 @@ import { type Command } from 'commander';
 import { SSH_TARGET_RE, assertValidSshTarget } from '../lib/ssh-exec.js';
 import { quoteWin32ExecArg } from '../lib/platform/index.js';
 import { type SecretsBackend, type SecretsBundle, type SecretsPolicy } from '../lib/secrets/bundles.js';
+import { type SecretsListFilterOpts } from '../lib/secrets/list-filter.js';
 /** Read all available data from stdin synchronously, trimmed. */
 /**
  * Read the raw `.env` text for `import --from <path|->`. A `-` reads the .env
@@ -51,6 +52,21 @@ export declare function buildRemoteUnlockArgs(names: string[], opts: {
     ttl?: string;
     durable?: boolean;
 }): string[];
+/**
+ * Build the remote `agents secrets list` argv for `list --host`. Every filter
+ * must be forwarded: `browseRemote` sends this argv verbatim, so a flag left out
+ * here is not an error — the remote just lists everything, and
+ * `secrets list --host zion --expired` reports every bundle on zion as expired.
+ * Silent and wrong beats loud and wrong only for the person who wrote the bug.
+ *
+ * Values pass through unparsed so the REMOTE validates them under its own rules,
+ * matching how `--ttl` is forwarded by buildRemoteUnlockArgs.
+ */
+export declare function buildRemoteListArgs(opts: SecretsListFilterOpts & {
+    json?: boolean;
+    sort?: string;
+    limit?: string;
+}, query?: string): string[];
 export { SSH_TARGET_RE, assertValidSshTarget };
 /**
  * Build the child environment for `agents secrets exec`. Strips
@@ -79,11 +95,19 @@ export declare function exportBundleToFile(env: Record<string, string>, filePath
  * Throws on a missing file, an invalid JSON envelope, or a wrong passphrase.
  */
 export declare function importBundleFromFile(filePath: string, passphrase: string): Record<string, string>;
-/** The POLICY column for `secrets list`: the prompt policy, plus a concise
- * state hint. `hold` shows `held Nh` when the secrets-agent is currently
- * caching the bundle; `always` and `never` show whether they prompt. `held`
+/** Compact span for a fixed duration: "45m" / "19h" / "2d". Shared by
+ * `compactRemaining` (a countdown) and the POLICY column's hold-window
+ * annotation (a fixed length) so the two can never round onto different unit
+ * thresholds and disagree about the same number of milliseconds. */
+export declare function compactDurationMs(ms: number): string;
+/** The POLICY column for `secrets list`. `hold` is a duration, not a mode — it
+ * means "prompt once, then stay silent for this long" — so the column states
+ * the window (`hold 7d`) rather than the bare tier name, and appends `· held Nd`
+ * while the secrets-agent is actually caching the bundle. `always` and `never`
+ * carry no window and gain nothing here. `holdMs` is the configured global hold
+ * (`secretsHoldMs()`), passed in rather than read so this stays pure; `held`
  * maps bundle name → expiry epoch-ms (from agentStatus()). */
-export declare function renderPolicyCol(b: SecretsBundle, held?: Map<string, number>): string;
+export declare function renderPolicyCol(b: SecretsBundle, holdMs: number, held?: Map<string, number>): string;
 /** The hold-window line at the top of `secrets status`. Names the `hold` policy
  * the window belongs to — the rename in #1604 left this surface still saying
  * "daily", the one name the CLI no longer accepts in its own help. Pure so the
@@ -97,6 +121,21 @@ export declare const NO_BUNDLES_HELD_LINE = "No bundles held. The next read of e
  * minutes (so a near-floor `holdMs` never shows a confusing "0 hours"), whole
  * hours up to 2 days, whole days beyond. Pure — unit-tested. */
 export declare function formatHoldWindow(ms: number): string;
+/** A broker hold expiry, or null once it has lapsed. One definition of "held",
+ * shared by the POLICY column, the `--held` filter, and the JSON payload, so the
+ * three can never disagree about the same bundle. */
+export declare function liveHold(expiresAt: number | undefined, now?: number): number | null;
+/**
+ * The EXPIRING cell. Counts keys needing attention — already expired plus due
+ * within 30 days — and colours by the worst of the two: red once anything has
+ * lapsed, yellow while everything is merely upcoming.
+ *
+ * Expired keys used to be invisible here. `countExpiringSoon` requires
+ * `d >= 0`, so a bundle whose token died last month rendered `-`, identical to
+ * one with no expiry at all; the only places it surfaced were `secrets view`
+ * and a hard abort at inject time, i.e. after it had already broken something.
+ */
+export declare function renderExpiringCol(b: SecretsBundle, now?: number): string;
 /** Register the `agents secrets` command tree. */
 export declare function registerSecretsCommands(program: Command): void;
 /** Validate a prompt-policy value, throwing a clear message on a bad one (the

package/dist/commands/secrets.js

@@ -18,7 +18,8 @@ import { ensureDaemonStarted, isDaemonRunning } from '../lib/daemon.js';
 import { parseHostsOption, remoteResolveEnv, remoteSecretsRaw, remoteSecretsStream, resolveHostSshTarget, verifyRemoteKeychainPush, keychainWriteFailureMessage, } from '../lib/secrets/remote.js';
 import { remoteShellFor, buildWindowsStdinImportCommand } from '../lib/hosts/remote-cmd.js';
 import { resolveRemoteOsSync } from '../lib/hosts/remote-os.js';
-import { bundleBackend, bundleExists, bundleItemStore, bundlePolicy, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, isHeadlessSecretsContext, readBundle, readBundleIfDecryptable, renameBundle, rotateBundleSecret, sanitizeProcessEnv, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, writeBundleWithItems, } from '../lib/secrets/bundles.js';
+import { bundleBackend, bundleExists, bundleItemStore, bundlePolicy, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, isHeadlessSecretsContext, readBundle, readBundleIfDecryptable, renameBundle, rotateBundleSecret, sanitizeProcessEnv, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, writeBundleWithItems, SECRET_TYPES, } from '../lib/secrets/bundles.js';
+import { parseListFilters, bundleMatchesFilter, bundleExpiry, filterIsActive, describeFilter, parseSortField, sortBundles, SORT_FIELDS, REF_KINDS, DEFAULT_EXPIRING_DAYS, } from '../lib/secrets/list-filter.js';
 import { encryptForFallback, decryptForFallback } from '../lib/secrets/filestore.js';
 import { getKeychainToken, getKeychainTokens, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from '../lib/secrets/index.js';
 import { assertOpAvailable, createPasswordItem, deleteItemByTitle, extractSecrets, itemExistsByTitle, listItems, listVaults, } from '../lib/onepassword.js';
@@ -274,6 +275,35 @@ export function buildRemoteUnlockArgs(names, opts) {
         ...(opts.durable ? ['--durable'] : []),
     ];
 }
+/**
+ * Build the remote `agents secrets list` argv for `list --host`. Every filter
+ * must be forwarded: `browseRemote` sends this argv verbatim, so a flag left out
+ * here is not an error — the remote just lists everything, and
+ * `secrets list --host zion --expired` reports every bundle on zion as expired.
+ * Silent and wrong beats loud and wrong only for the person who wrote the bug.
+ *
+ * Values pass through unparsed so the REMOTE validates them under its own rules,
+ * matching how `--ttl` is forwarded by buildRemoteUnlockArgs.
+ */
+export function buildRemoteListArgs(opts, query) {
+    return [
+        'list',
+        ...(query ? [query] : []),
+        ...(opts.json ? ['--json'] : []),
+        ...(opts.policy ? ['--policy', opts.policy] : []),
+        ...(opts.backend ? ['--backend', opts.backend] : []),
+        ...(opts.type ? ['--type', opts.type] : []),
+        ...(opts.kind ? ['--kind', opts.kind] : []),
+        ...(opts.held ? ['--held'] : []),
+        ...(opts.notHeld ? ['--not-held'] : []),
+        ...(opts.expired ? ['--expired'] : []),
+        // `--expiring` is optional-value: `true` means the bare flag was passed.
+        ...(opts.expiring === true ? ['--expiring'] : opts.expiring ? ['--expiring', String(opts.expiring)] : []),
+        ...(opts.unused ? ['--unused', opts.unused] : []),
+        ...(opts.sort ? ['--sort', opts.sort] : []),
+        ...(opts.limit ? ['--limit', opts.limit] : []),
+    ];
+}
 // SSH target validation is defined canonically in src/lib/ssh-exec.ts and
 // re-exported here for back-compat with existing importers of these symbols.
 export { SSH_TARGET_RE, assertValidSshTarget };
@@ -446,11 +476,11 @@ function humanAge(iso) {
         return age;
     return `${age} ago`;
 }
-/** Compact remaining-time for the list POLICY column: "19h" / "45m" / "2d". */
-function compactRemaining(expiresAt) {
-    const ms = expiresAt - Date.now();
-    if (ms <= 0)
-        return 'expired';
+/** Compact span for a fixed duration: "45m" / "19h" / "2d". Shared by
+ * `compactRemaining` (a countdown) and the POLICY column's hold-window
+ * annotation (a fixed length) so the two can never round onto different unit
+ * thresholds and disagree about the same number of milliseconds. */
+export function compactDurationMs(ms) {
     const mins = Math.round(ms / 60000);
     if (mins < 60)
         return `${mins}m`;
@@ -459,18 +489,33 @@ function compactRemaining(expiresAt) {
         return `${hours}h`;
     return `${Math.round(hours / 24)}d`;
 }
-/** The POLICY column for `secrets list`: the prompt policy, plus a concise
- * state hint. `hold` shows `held Nh` when the secrets-agent is currently
- * caching the bundle; `always` and `never` show whether they prompt. `held`
+/** Compact remaining-time for the list POLICY column: "19h" / "45m" / "2d". */
+function compactRemaining(expiresAt) {
+    const ms = expiresAt - Date.now();
+    if (ms <= 0)
+        return 'expired';
+    return compactDurationMs(ms);
+}
+/** The POLICY column for `secrets list`. `hold` is a duration, not a mode — it
+ * means "prompt once, then stay silent for this long" — so the column states
+ * the window (`hold 7d`) rather than the bare tier name, and appends `· held Nd`
+ * while the secrets-agent is actually caching the bundle. `always` and `never`
+ * carry no window and gain nothing here. `holdMs` is the configured global hold
+ * (`secretsHoldMs()`), passed in rather than read so this stays pure; `held`
  * maps bundle name → expiry epoch-ms (from agentStatus()). */
-export function renderPolicyCol(b, held) {
+export function renderPolicyCol(b, holdMs, held) {
     // `never` is loud on purpose — it's the only tier with no user-presence gate.
     if (bundlePolicy(b) === 'never')
         return chalk.red.bold('never · no prompt');
     if (bundlePolicy(b) === 'always')
         return chalk.yellow('always · prompt');
-    const exp = held?.get(b.name);
-    return exp ? chalk.green(`hold · held ${compactRemaining(exp)}`) : chalk.gray('hold');
+    const window = compactDurationMs(holdMs);
+    // A lapsed entry is not held. Without this guard a stale broker row renders
+    // the countdown's `expired` sentinel as if it were a live hold.
+    const exp = liveHold(held?.get(b.name));
+    return exp !== null
+        ? chalk.green(`hold ${window} · held ${compactRemaining(exp)}`)
+        : chalk.gray(`hold ${window}`);
 }
 /** The hold-window line at the top of `secrets status`. Names the `hold` policy
  * the window belongs to — the rename in #1604 left this surface still saying
@@ -502,12 +547,21 @@ export function formatHoldWindow(ms) {
 }
 /** Below this width the fixed date columns no longer fit; `list` uses cards. */
 const SECRETS_WIDE = 96;
+/** A broker hold expiry, or null once it has lapsed. One definition of "held",
+ * shared by the POLICY column, the `--held` filter, and the JSON payload, so the
+ * three can never disagree about the same bundle. */
+export function liveHold(expiresAt, now = Date.now()) {
+    return expiresAt !== undefined && expiresAt > now ? expiresAt : null;
+}
+/** Width of the POLICY column. The widest cell is `hold 30d · held 30d` (19
+ * visible chars) — `clampHoldMs` caps the window at 30d and `renderPolicyCol`
+ * drops lapsed holds, so nothing longer can be produced. */
+const POLICY_COL_WIDTH = 20;
 /** Format a single bundle as a table row for the `secrets list` output. */
-function renderBundleRow(b, held, cols = terminalWidth()) {
+function renderBundleRow(b, holdMs, held, cols = terminalWidth()) {
     const entries = describeBundle(b);
     const keys = entries.length;
-    const expiringCount = countExpiringSoon(b.meta);
-    const expiring = expiringCount > 0 ? chalk.yellow(String(expiringCount)) : chalk.gray('-');
+    const expiring = renderExpiringCol(b);
     // Timestamp distinction:
     //   "?"     -> legacy bundle, never written under the timestamping code.
     //   "never" -> bundle has been written but the action never happened
@@ -521,7 +575,7 @@ function renderBundleRow(b, held, cols = terminalWidth()) {
         : (b.created_at ? chalk.gray('never') : chalk.gray('?'));
     const head = `${chalk.cyan(b.name.padEnd(20))} ` +
         `${String(keys).padEnd(5)} ` +
-        `${padVisible(renderPolicyCol(b, held), 18)} ` +
+        `${padVisible(renderPolicyCol(b, holdMs, held), POLICY_COL_WIDTH)} ` +
         `${padVisible(expiring, 9)} ` +
         `${padVisible(created, 9)} ` +
         `${padVisible(updated, 9)} ` +
@@ -542,7 +596,7 @@ function renderBundleRow(b, held, cols = terminalWidth()) {
     return trailer ? `${head} ${trailer}` : head.trimEnd();
 }
 /** Narrow-terminal card: name + compact meta on one line, description below. */
-function renderBundleCard(b, held, cols) {
+function renderBundleCard(b, holdMs, held, cols) {
     const keys = describeBundle(b).length;
     const used = b.last_used ? relativeAge(b.last_used) : (b.created_at ? 'never' : '?');
     const tag = b.backend === 'file'
@@ -550,7 +604,7 @@ function renderBundleCard(b, held, cols) {
         : b.backend === 'vault'
             ? chalk.blue(' [synced]')
             : '';
-    const meta = chalk.gray(`${keys} key${keys === 1 ? '' : 's'} · `) + renderPolicyCol(b, held) + chalk.gray(` · used ${used}`);
+    const meta = chalk.gray(`${keys} key${keys === 1 ? '' : 's'} · `) + renderPolicyCol(b, holdMs, held) + chalk.gray(` · used ${used}`);
     const line1 = `${chalk.cyan(b.name)}  ${meta}${tag}`;
     if (!b.description)
         return line1;
@@ -662,7 +716,10 @@ function renderMetaLine(meta, reveal) {
         return '';
     return `    ${parts.join('  ')}`;
 }
-/** Count entries in `meta` whose `expires` falls in the next 30 days. */
+/** Count entries in `meta` whose `expires` falls in the next 30 days. Excludes
+ * keys that have ALREADY expired — those are counted by `bundleExpiry().expired`
+ * and rendered separately, since a lapsed key is a different problem from one
+ * coming due. */
 function countExpiringSoon(meta) {
     if (!meta)
         return 0;
@@ -676,6 +733,23 @@ function countExpiringSoon(meta) {
     }
     return n;
 }
+/**
+ * The EXPIRING cell. Counts keys needing attention — already expired plus due
+ * within 30 days — and colours by the worst of the two: red once anything has
+ * lapsed, yellow while everything is merely upcoming.
+ *
+ * Expired keys used to be invisible here. `countExpiringSoon` requires
+ * `d >= 0`, so a bundle whose token died last month rendered `-`, identical to
+ * one with no expiry at all; the only places it surfaced were `secrets view`
+ * and a hard abort at inject time, i.e. after it had already broken something.
+ */
+export function renderExpiringCol(b, now = Date.now()) {
+    const { expired, soon } = bundleExpiry(b, now);
+    const total = expired + soon;
+    if (total === 0)
+        return chalk.gray('-');
+    return expired > 0 ? chalk.red(String(total)) : chalk.yellow(String(total));
+}
 /**
  * Resolve an existing import target bundle (inheriting its backend) or create a
  * new one with the requested backend. Refuses to silently downgrade a
@@ -801,22 +875,61 @@ export function registerSecretsCommands(program) {
         { title: 'Sync commands', names: ['push', 'pull', 'remote-list'] },
         { title: 'Utilities', names: ['exec', 'mcp', 'generate', 'migrate-acl'] },
     ]);
-    cmd
-        .command('list')
+    const listCmd = cmd
+        .command('list [query]')
         .alias('ls')
-        .description('List configured secrets bundles (use --host/--hosts to list bundles on other machines over SSH)')
+        .description('List configured secrets bundles, optionally filtered (use --host/--hosts for other machines over SSH)')
         .option('--host <target>', 'List bundles on a remote host over SSH (enrolled `agents hosts` name, ssh-config alias, or user@host)')
         .option('--hosts <list>', 'Comma-separated hosts to list in one shot, e.g. yosemite-s0,yosemite-s1')
         .option('--device <target>', 'Alias for --host')
         .option('--devices <list>', 'Alias for --hosts')
         .option('--json', 'Emit machine-readable JSON (bundle metadata only — never secret values) instead of the table')
-        .action(async (opts) => {
+        .option('--policy <list>', "Only these prompt policies (comma-separated): hold, always, never. '--policy never' is the audit for bundles that read with no Touch ID at all")
+        .option('--backend <list>', 'Only these backends (comma-separated): keychain, file, vault')
+        .option('--type <list>', `Only bundles carrying a key of these types (comma-separated): ${SECRET_TYPES.join(', ')}`)
+        .option('--kind <list>', `Only bundles carrying a value of these ref kinds (comma-separated): ${REF_KINDS.join(', ')}. '--kind literal' finds raw values stored inline; '--kind exec' finds bundles that shell out`)
+        .option('--held', 'Only bundles the secrets-agent is holding right now (read silently, no Touch ID). macOS only')
+        .option('--not-held', 'Only bundles the agent is NOT holding — the next read of each will prompt. macOS only')
+        .option('--expired', 'Only bundles with at least one key whose expiry has already passed')
+        .option('--expiring [days]', `Only bundles with a key falling due within N days (default ${DEFAULT_EXPIRING_DAYS})`)
+        .option('--unused <duration>', 'Only bundles not read since this far back (e.g. 30d, 4w, 3mo). Never-used bundles always match')
+        .addOption(new Option('--sort <field>', 'Sort by: name (default), used, created, updated, expiry').choices([...SORT_FIELDS]))
+        .option('-n, --limit <n>', 'Show at most this many bundles (after filtering and sorting)')
+        .action(async (query, opts) => {
         const targets = parseHostsOption(opts);
         if (targets.length > 0) {
-            await browseRemote(targets, opts.json ? ['list', '--json'] : ['list'], false);
+            // Forward the filters — browseRemote sends this argv verbatim, so a
+            // dropped flag would make the remote silently list everything.
+            await browseRemote(targets, buildRemoteListArgs(opts, query), false);
             return;
         }
-        const bundles = listBundles();
+        // Parse before touching the keychain so a typo'd flag fails instantly,
+        // and render the message rather than a stack trace (the `policy` pattern).
+        let filter;
+        let sortField;
+        let limit;
+        try {
+            filter = parseListFilters(opts, query);
+            sortField = parseSortField(opts.sort);
+            limit = opts.limit === undefined ? undefined : Number(opts.limit);
+            if (limit !== undefined && (!Number.isInteger(limit) || limit < 1)) {
+                throw new Error(`Invalid --limit '${opts.limit}'. Use a whole number of bundles, e.g. --limit 10.`);
+            }
+            // The broker is macOS-only, so off darwin `held` is always empty and a
+            // hold-state filter would answer from no data — every bundle would look
+            // not-held. Refuse rather than return a confidently wrong list.
+            if (filter.held !== undefined && process.platform !== 'darwin') {
+                throw new Error('--held/--not-held need the secrets-agent, which is macOS-only. Run it on a Mac, or with --host <mac>.');
+            }
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+        const all = listBundles();
+        // The configured hold window, read once for the whole listing — it is
+        // global, so every `hold` bundle renders the same span.
+        const holdMs = secretsHoldMs();
         // Cross-reference the secrets-agent so `hold` bundles that are currently
         // held can show "· held Nh". Soft-fails to no hint if the broker is down.
         const held = new Map();
@@ -829,6 +942,12 @@ export function registerSecretsCommands(program) {
                 /* broker not running — render policy without the countdown */
             }
         }
+        // Filter, sort, then cap — before the --json branch, so the machine
+        // payload is the exact twin of the table (the sessions ordering rule).
+        const now = Date.now();
+        const matched = all.filter((b) => bundleMatchesFilter(b, filter, { held, now }));
+        const sorted = sortBundles(matched, sortField);
+        const bundles = limit === undefined ? sorted : sorted.slice(0, limit);
         if (opts.json) {
             // Discovery payload for agents: metadata only, no secret values. Gated on
             // the explicit --json flag (not stdout.isTTY) so piping the human table to
@@ -837,36 +956,96 @@ export function registerSecretsCommands(program) {
                 name: b.name,
                 keys: describeBundle(b).length,
                 policy: bundlePolicy(b),
+                // The window `policy: "hold"` is shorthand for. Null on always/never,
+                // which have no window at all.
+                holdMs: bundlePolicy(b) === 'hold' ? holdMs : null,
                 backend: b.backend === 'file' ? 'file' : 'keychain',
                 allowExec: Boolean(b.allow_exec),
                 expiringSoon: countExpiringSoon(b.meta),
+                // Already-lapsed keys, which `expiringSoon` deliberately excludes. A
+                // machine caller polling for rotation needs both numbers.
+                expired: bundleExpiry(b, now).expired,
                 description: b.description ?? null,
                 createdAt: b.created_at ?? null,
                 updatedAt: b.updated_at ?? null,
                 lastUsed: b.last_used ?? null,
-                heldExpiresAt: held.get(b.name) ?? null,
+                // Same liveness rule the POLICY column and --held use: a broker entry
+                // past its expiry is not held. Without the check this field reported a
+                // stale past timestamp as if the bundle were still warm, disagreeing
+                // with the table and the filter about the very same bundle.
+                heldExpiresAt: liveHold(held.get(b.name), now),
             }));
             process.stdout.write(JSON.stringify(payload) + '\n');
             return;
         }
         if (bundles.length === 0) {
-            console.log(chalk.gray('No secrets bundles configured.'));
-            console.log(chalk.gray('Try: agents secrets create <name>'));
+            // Distinguish "you have none" from "your filter excluded all of them",
+            // and name the axes that did it — otherwise the only way to find out
+            // which flag emptied the list is to remove them one at a time.
+            if (filterIsActive(filter)) {
+                console.log(chalk.gray(`No bundles ${describeFilter(filter)}. ${all.length} bundle${all.length === 1 ? '' : 's'} total.`));
+                console.log(chalk.gray('Try: agents secrets list  (no filters)'));
+            }
+            else {
+                console.log(chalk.gray('No secrets bundles configured.'));
+                console.log(chalk.gray('Try: agents secrets create <name>'));
+            }
             return;
         }
         const cols = terminalWidth();
         if (cols >= SECRETS_WIDE) {
-            console.log(chalk.bold(`${'NAME'.padEnd(20)} ${'KEYS'.padEnd(5)} ${'POLICY'.padEnd(18)} ${'EXPIRING'.padEnd(9)} ${'CREATED'.padEnd(9)} ${'UPDATED'.padEnd(9)} ${'USED'.padEnd(7)} DESCRIPTION`));
+            console.log(chalk.bold(`${'NAME'.padEnd(20)} ${'KEYS'.padEnd(5)} ${'POLICY'.padEnd(POLICY_COL_WIDTH)} ${'EXPIRING'.padEnd(9)} ${'CREATED'.padEnd(9)} ${'UPDATED'.padEnd(9)} ${'USED'.padEnd(7)} DESCRIPTION`));
             for (const b of bundles) {
-                console.log(renderBundleRow(b, held, cols));
+                console.log(renderBundleRow(b, holdMs, held, cols));
             }
         }
         else {
             for (const b of bundles) {
-                console.log(renderBundleCard(b, held, cols));
+                console.log(renderBundleCard(b, holdMs, held, cols));
             }
         }
     });
+    setHelpSections(listCmd, {
+        examples: `
+      # Everything, newest-used first
+      agents secrets list --sort used
+
+      # Find one by name or description
+      agents secrets list github
+
+      # The security audit: which bundles read with NO Touch ID at all?
+      agents secrets list --policy never
+
+      # Which still store a raw value inline, or can shell out?
+      agents secrets list --kind literal
+      agents secrets list --kind exec
+
+      # What has already lapsed, and what is about to
+      agents secrets list --expired
+      agents secrets list --expiring 7 --sort expiry
+
+      # What can I delete? Untouched in three months
+      agents secrets list --unused 3mo --sort used
+
+      # Which bundles will prompt me on the next read (macOS)
+      agents secrets list --not-held
+
+      # Combine axes — every filter narrows further
+      agents secrets list --policy hold --backend file --expiring
+
+      # Same filters, on another machine, machine-readable
+      agents secrets list --expired --host mac-mini --json
+    `,
+        notes: `
+      - Filters compose: every flag you add narrows the list further.
+      - An unknown value is an error, not an empty list — '--policy hodl' names the valid set.
+      - --held/--not-held read live broker state, so they need macOS. Use --host <mac> from elsewhere.
+      - --expired and --expiring are different questions: already lapsed vs coming due. The EXPIRING column counts both and turns red once anything has lapsed.
+      - --unused matches bundles never read at all, not just old ones.
+      - Filters apply before --json, so the JSON is the exact twin of the table.
+      - Filters are forwarded over --host, so a remote list narrows the same way.
+    `,
+    });
     cmd
         .command('view [name]')
         .alias('show')
@@ -971,6 +1150,9 @@ export function registerSecretsCommands(program) {
                     name: bundle.name,
                     description: bundle.description ?? null,
                     policy: bundlePolicy(bundle),
+                    // The window `policy: "hold"` is shorthand for. Null on
+                    // always/never, which have no window at all.
+                    holdMs: bundlePolicy(bundle) === 'hold' ? secretsHoldMs() : null,
                     backend: bundle.backend === 'file' ? 'file' : 'keychain',
                     allowExec: Boolean(bundle.allow_exec),
                     createdAt: bundle.created_at ?? null,
@@ -995,7 +1177,10 @@ export function registerSecretsCommands(program) {
             }
             else {
                 console.log(bundlePolicy(bundle) === 'hold'
-                    ? chalk.gray('policy: hold (ask once, then held for the hold window — 7d by default — until sleep / logout; screen-lock does not drop it)')
+                    // The window comes from secretsHoldMs(), never a literal — this
+                    // line used to hardcode "7d by default" and so misstated the
+                    // window for anyone who had configured secrets.agent.holdMs.
+                    ? chalk.gray(`policy: hold (ask once, then held for ${formatHoldWindow(secretsHoldMs())} — until sleep / logout; screen-lock does not drop it)`)
                     : chalk.gray('policy: always (asks for Touch ID every time — never auto-held)'));
             }
             if (bundle.created_at)

package/dist/commands/send.d.ts

@@ -1,6 +1,10 @@
 /**
  * `agents send <text> --channel <name> --to <target>` — deliver a message over
- * any registered channel (mailbox, telegram, imessage, slack, discord, apps).
+ * any registered channel (mailbox, telegram, imessage, slack, discord, desktop, apps).
+ *
+ * `desktop` is the local machine's notification centre — the only channel with no
+ * external dependency, so it still reaches the operator at their Mac when a
+ * messaging gateway is down.
  *
  * `agents notify <text>` — owner-facing alias. Fills channel + target from the
  * `notify.owner` block in agents.yaml when not passed, so routines/agents ping

package/dist/commands/send.js

@@ -29,7 +29,7 @@ async function doSend(text, channel, to, opts) {
 export function registerSendCommand(program) {
     program
         .command('send <text>')
-        .description('Send a message through a channel provider (mailbox, telegram, imessage, slack, discord).')
+        .description('Send a message through a channel provider (mailbox, telegram, imessage, slack, discord, desktop).')
         .requiredOption('--channel <name>', 'channel / provider name')
         .requiredOption('--to <target>', 'channel-specific recipient id')
         .option('--thread <id>', 'channel thread id / timestamp')