@phnx-labs/agents-cli 1.20.89 → 1.20.91

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,19 +489,46 @@ 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. `daily` 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
+ * "daily", the one name the CLI no longer accepts in its own help. Pure so the
+ * vocabulary is pinned by a test rather than re-drifting on the next rename. */
+export function renderHoldSummary(holdStr, configured) {
+    const source = configured ? ' (secrets.agent.holdMs)' : ' (default)';
+    return `hold: ${holdStr}${source} — a bundle on the hold policy prompts once, then stays silent for this long or until sleep/logout.`;
 }
+/** The empty-broker line under the hold summary. Named here, beside
+ * `renderHoldSummary`, for the same reason: it is the second line the rename
+ * left saying `daily`, and a test pins both. */
+export const NO_BUNDLES_HELD_LINE = 'No bundles held. The next read of each hold-policy bundle will prompt once, then hold.';
 /** Human-readable hold window for `secrets status`. Sub-hour values render in
  * minutes (so a near-floor `holdMs` never shows a confusing "0 hours"), whole
  * hours up to 2 days, whole days beyond. Pure — unit-tested. */
@@ -490,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
@@ -509,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)} ` +
@@ -530,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'
@@ -538,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;
@@ -650,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;
@@ -664,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
@@ -789,23 +875,62 @@ 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();
-        // Cross-reference the secrets-agent so `daily` bundles that are currently
+        // 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();
         if (process.platform === 'darwin') {
@@ -817,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
@@ -825,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')
@@ -959,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,
@@ -983,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)
@@ -1174,7 +1371,7 @@ export function registerSecretsCommands(program) {
             const resolvedName = name ?? (await promptBundleName());
             validateBundleName(resolvedName);
             // Leave policy unset unless the user explicitly chose one, so the bundle
-            // inherits the configured default (`daily`) instead of being pinned.
+            // inherits the configured default (`hold`) instead of being pinned.
             const policyOpt = opts.policy ?? opts.tier;
             const policy = policyOpt ? parsePolicyOpt(policyOpt) : undefined;
             const backend = opts.synced ? 'vault' : resolveBackendOpt(opts.backend);
@@ -2266,7 +2463,7 @@ Examples:
             (brokerUp
                 ? chalk.green('running') + chalk.gray(isDaemonRunning() ? ' (hosted by the daemon)' : ' (standalone)')
                 : chalk.yellow('not running — starts on demand, or run `agents secrets start` to bring the daemon up now')));
-        // Diagnostic: version skew is the top reason a `daily` bundle keeps
+        // Diagnostic: version skew is the top reason a `hold` bundle keeps
         // re-prompting — a broker on an older build gets torn down when the CLI
         // version changes (e.g. `agents-cli-update`), wiping every held bundle.
         const onDisk = getCliVersionFresh();
@@ -2286,11 +2483,11 @@ Examples:
         catch {
             return false;
         } })();
-        console.log(chalk.gray(`hold: ${holdStr}${configured ? ' (secrets.agent.holdMs)' : ' (default)'} — a daily bundle prompts once, then stays silent for this long or until sleep/logout.`));
+        console.log(chalk.gray(renderHoldSummary(holdStr, configured)));
         const entries = await agentStatus();
         const held = new Set(entries.map((e) => e.name));
         if (entries.length === 0) {
-            console.log(chalk.gray('No bundles held. The next read of each daily bundle will prompt once, then hold.'));
+            console.log(chalk.gray(NO_BUNDLES_HELD_LINE));
             console.log(chalk.gray('Pre-warm now with: agents secrets unlock <bundle>  (or --all)'));
         }
         else {

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

package/dist/commands/sessions-browser.d.ts

@@ -26,6 +26,8 @@ export interface BrowserFilter {
     device?: string;
     /** filter to one team's lineage, or all — the `T` key / `--in-team`. */
     team?: string;
+    /** favorited-only — the `f` key / `--favorites`. */
+    favorites: boolean;
     /** this-repo subtree vs every directory — the `P` key / `--all`. */
     projectScope: 'repo' | 'all';
     /** time window (undefined = all time) — the `W` key / `--since`. */
@@ -77,6 +79,7 @@ export declare function activeBrowserSeed(opts: {
     host?: string[];
     since?: string;
     all?: boolean;
+    favorites?: boolean;
 }): Partial<BrowserFilter>;
 /**
  * The initial filter for the bare interactive listing: current-repo subtree by
@@ -92,6 +95,7 @@ export declare function bareBrowserSeed(opts: {
     since?: string;
     host?: string[];
     inTeam?: string;
+    favorites?: boolean;
 }): Partial<BrowserFilter>;
 /**
  * A live session's stable row key: its session id when the agent reported one,

package/dist/commands/sessions-browser.js

@@ -17,9 +17,10 @@ import { isSessionTrackedAgent } from '../lib/session/types.js';
 import { discoverSessions } from '../lib/session/discover.js';
 import { gatherRemoteList } from '../lib/session/remote-list.js';
 import { enrichTeamOrigins, safeTeamText } from '../lib/session/team-filter.js';
+import { listFavorites, toggleFavorite } from '../lib/session/favorites.js';
 import { machineId, normalizeHost } from '../lib/session/sync/config.js';
 import { buildPreview } from './sessions-picker.js';
-import { formatPickerLabel, pickerColumnsFor, ticketLabel, mergeLocalFirst, gatherActiveSessions, liveHostLabel, LIVE_ROW_PREFIX, cleanPreview, handlePickedSession, shouldIncludeLocal, remoteHostsToDial, matchesTeam, } from './sessions.js';
+import { formatPickerLabel, pickerColumnsFor, ticketLabel, mergeLocalFirst, gatherActiveSessions, liveHostLabel, LIVE_ROW_PREFIX, cleanPreview, handlePickedSession, shouldIncludeLocal, remoteHostsToDial, matchesTeam, formatLiveStatusHeadline, } from './sessions.js';
 /**
  * Complete a seed into the filter the picker actually runs on.
  *
@@ -37,6 +38,7 @@ export function buildInitialFilter(initial) {
     return {
         running: initial.running ?? false,
         teams: initial.teams ?? false,
+        favorites: initial.favorites ?? false,
         agent: initial.agent,
         device: initial.device,
         team: initial.team,
@@ -107,6 +109,8 @@ export function browserFilterToArgv(f, query = '') {
         a.push('--active');
     if (f.teams)
         a.push('--teams');
+    if (f.favorites)
+        a.push('--favorites');
     if (f.agent)
         a.push('-a', f.agent);
     if (f.device)
@@ -140,6 +144,7 @@ export function activeBrowserSeed(opts) {
     return {
         running: true,
         teams: !!opts.teams,
+        favorites: !!opts.favorites,
         agent: opts.agent,
         projectScope: 'all',
         device: normalizeDeviceSeed(opts.host?.[0]),
@@ -170,6 +175,7 @@ export function bareBrowserSeed(opts) {
     const wholeTeam = !!opts.inTeam;
     return {
         teams: !!opts.teams,
+        favorites: !!opts.favorites,
         agent: opts.agent,
         // The filter carries one device; seed it only when the scope names exactly
         // one, so a two-device scope isn't narrowed to the first of them.
@@ -359,9 +365,14 @@ export function shouldShowHostColumn(f, live, rows) {
         return false;
     return rows.some((r) => liveHostLabel(live.get(r.id)) !== '');
 }
-/** Apply the cheap in-memory filters (agent / device / project / running). */
-function applyFilters(rows, live, f, self) {
+/** Apply the cheap in-memory filters (agent / device / project / running / favorites). */
+function applyFilters(rows, live, f, self, favorites) {
     let out = rows;
+    // A projected live row is keyed by pid/task when it has no session id, and a
+    // favorite is always keyed by a real session id — so an id-less row can never
+    // be favorited and correctly drops out here.
+    if (f.favorites)
+        out = out.filter((r) => favorites.has(r.id));
     if (f.agent)
         out = out.filter((r) => r.agent === f.agent);
     if (f.device)
@@ -398,13 +409,15 @@ function headerFor(f) {
         bits.push('running');
     if (f.teams)
         bits.push('teams');
+    if (f.favorites)
+        bits.push('favorites');
     return bits.join(' · ');
 }
 function helpFor(_f, mode) {
     if (mode === 'search') {
         return 'type to filter · ↑↓ navigate · esc exit search · ⏎ resume';
     }
-    return 's search · r running · c teams · t team · a agent · d device · p project · w window · tab preview · y copy-cmd · ⏎ resume · esc quit';
+    return 's search · r running · f favorites · * star · c teams · t team · a agent · d device · p project · w window · tab preview · y copy-cmd · ⏎ resume · esc quit';
 }
 /**
  * Launch the interactive session browser. `initial` seeds the filter (e.g.
@@ -432,6 +445,10 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
     // The live index is slow (a full ps/tmux scan) and only the running filter
     // needs it — fetch it once, lazily, the first time running is toggled on.
     let liveCache = null;
+    // Re-read every load (it's an mtime-memoized parse of one small file), so the
+    // `*` key's reload picks up the star it just wrote — and so does a favorite
+    // starred by another session on this machine.
+    let favorites = new Set();
     // Generation guard: two quick keypresses can start overlapping loads whose
     // SSH fan-outs settle out of order. dynamicPicker's own gen ref guards which
     // rows become `items`, but the shared closure state below (cols / cycle pools /
@@ -489,9 +506,14 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
             ...rows.map((r) => safeTeamText(r.spawnedTeam)),
             ...rows.map((r) => safeTeamText(r.teamOrigin?.team)),
         ]);
-        const filtered = applyFilters(rows, live ?? new Map(), f, self);
+        favorites = listFavorites();
+        const filtered = applyFilters(rows, live ?? new Map(), f, self, favorites);
         cols = pickerColumnsFor(filtered);
         cols.showHost = shouldShowHostColumn(f, live, filtered);
+        // Status rides the same gate as the host column: both come from the live
+        // scan, so both belong to the running view and neither should widen a plain
+        // transcript listing that has no live rows to fill them.
+        cols.showStatus = !!f.running && !!live;
         return filtered;
     };
     const picked = await dynamicPicker({
@@ -499,9 +521,17 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
         initialFilter,
         load,
         keyFor: (s) => s.id,
-        labelFor: (s, q) => formatPickerLabel(s, q, cols, sshOriginTagFor(liveCache, s.id), liveHostLabel(liveCache?.get(s.id))),
+        labelFor: (s, q) => formatPickerLabel(s, q, cols, sshOriginTagFor(liveCache, s.id), liveHostLabel(liveCache?.get(s.id)), favorites.has(s.id), liveCache?.get(s.id)),
         matches: sessionMatchesQuery,
-        buildPreview,
+        // Lead the preview with the live status banner — the one place a `crashed` /
+        // `orphaned` session gets a sentence instead of a glyph. `buildPreview` is
+        // memoized per session, so the volatile live half is prepended here rather
+        // than baked into the cached body.
+        buildPreview: (s) => {
+            const headline = formatLiveStatusHeadline(liveCache?.get(s.id), favorites.has(s.id));
+            const body = buildPreview(s);
+            return headline ? `${headline}\n${body}` : body;
+        },
         headerFor: (f) => unreachable.length > 0
             ? `${headerFor(f)} · ${chalk.yellow(`${unreachable.join(', ')}: unreachable`)}`
             : headerFor(f),
@@ -511,6 +541,7 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
         loadingMessage: local ? 'Loading…' : 'Loading (reaching other machines)…',
         keyBindings: {
             r: (f) => ({ ...f, running: !f.running }),
+            f: (f) => ({ ...f, favorites: !f.favorites }),
             c: (f) => ({ ...f, teams: !f.teams }),
             a: (f) => ({ ...f, agent: cycle(f.agent, agentsInPool) }),
             d: (f) => ({ ...f, device: cycle(f.device, devicesInPool) }),
@@ -521,8 +552,19 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
             p: (f) => (hosts ? f : { ...f, projectScope: f.projectScope === 'repo' ? 'all' : 'repo' }),
             w: (f) => ({ ...f, window: cycleWindow(f.window) }),
         },
-        onKey: (name, f, _active, query) => {
-            if (name === 'y') {
+        onKey: (name, f, active, query) => {
+            if (name === '*') {
+                // Only a row with a real session id can be starred: a projected live row
+                // with no id is keyed by pid, which is gone the moment the process is.
+                if (!active || active.id.startsWith(LIVE_ROW_PREFIX))
+                    return 'nothing to star on this row';
+                const on = toggleFavorite(active.id);
+                // reload so the row's star is repainted — labels are memoized per row.
+                return { flash: on ? `★ favorited ${active.shortId}` : `☆ unfavorited ${active.shortId}`, reload: true };
+            }
+            // Both cases: `hotkeyToken` hands `onKey` the literal character, and this
+            // key worked with caps lock on before it existed.
+            if (name === 'y' || name === 'Y') {
                 // Thread the live search query so the copied command reproduces the
                 // exact view — the human→agent bridge must include the search term.
                 const cmd = 'ag ' + browserFilterToArgv(f, query).join(' ');