@phnx-labs/agents-cli 1.20.90 → 1.20.92

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

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

@@ -48,6 +48,21 @@ export declare function buildPreview(session: SessionMeta): string;
  * names the command that does report them instead.
  */
 export declare function formatTeamLineage(session: SessionMeta): string;
+/**
+ * The three timing facts the header reports: when the session was created, when
+ * it was last active, and how long it ran. Reads the parsed transcript when
+ * there is one and otherwise the indexed `SessionMeta`, so a remote or
+ * unindexed session — which has no local transcript to parse — still reports
+ * them instead of silently dropping the whole line.
+ *
+ * `lastActive` and `lasted` are omitted for a session whose whole life was under
+ * a minute: there they just restate `created`.
+ */
+export declare function extractTiming(session: Pick<SessionMeta, 'timestamp' | 'lastActivity' | 'durationMs'>, events: SessionEvent[]): {
+    createdAgo?: string;
+    lastActiveAgo?: string;
+    duration?: string;
+};
 /**
  * Unique directories the session touched, compact and human-readable.
  * Prefer `session.recentDirectoriesTouched` — the scan records it on the row, so

package/dist/commands/sessions-picker.js

@@ -18,6 +18,7 @@ import { extractTodoProgress, WORKTREE_RE } from '../lib/session/state.js';
 import { renderMarkdown } from '../lib/markdown.js';
 import { itemPicker } from '../lib/picker.js';
 import { classifyFileChanges, changeCounts, toolHistogram, detectTestResult } from '../lib/session/digest.js';
+import { extractArtifacts, extractHooks, extractLinks, extractRepos, extractSkills } from '../lib/session/highlights.js';
 /** A session whose transcript lives on another machine (folded in over the live
  * cross-machine fan-out): its `filePath` is on that peer's disk, so the preview
  * can't parse it locally — it shows metadata + a "resume there" note instead.
@@ -145,7 +146,7 @@ function displayAgent(agent) {
 const DOT = chalk.gray(' · ');
 function formatHeader(session, events) {
     const model = extractModel(events) || session.model;
-    const { startedAgo, duration } = extractTiming(events);
+    const { createdAgo, lastActiveAgo, duration } = extractTiming(session, events);
     const totalMessages = session.messageCount ?? countMessages(events);
     const totalTokens = session.tokenCount;
     // Line 1: Agent v version · shortId · model · account
@@ -157,7 +158,7 @@ function formatHeader(session, events) {
         line1.push(chalk.bold.white(shortenModel(model)));
     if (session.account)
         line1.push(chalk.gray(session.account));
-    // Line 2: cwd · project · branch · started X ago · lasted Y
+    // Line 2: cwd · project · branch · created X ago · last active Y ago · lasted Z
     // Project is clickable: Linear issue URL is for tickets (line 4); for the
     // project name prefer a GitHub repo URL derived from the checkout path.
     const line2 = [];
@@ -171,8 +172,10 @@ function formatHeader(session, events) {
     }
     if (session.gitBranch)
         line2.push(chalk.cyan(session.gitBranch));
-    if (startedAgo)
-        line2.push(chalk.gray('started ') + chalk.white(startedAgo + ' ago'));
+    if (createdAgo)
+        line2.push(chalk.gray('created ') + chalk.white(createdAgo + ' ago'));
+    if (lastActiveAgo)
+        line2.push(chalk.gray('last active ') + chalk.white(lastActiveAgo + ' ago'));
     if (duration)
         line2.push(chalk.gray('lasted ') + chalk.white(duration));
     // Line 3: N msgs · T tokens · [label ·] uuid
@@ -291,16 +294,39 @@ function extractModel(events) {
     }
     return undefined;
 }
-function extractTiming(events) {
-    if (events.length === 0)
-        return {};
-    const firstMs = Date.parse(events[0].timestamp);
-    const lastMs = Date.parse(events[events.length - 1].timestamp);
+/** Shortest span worth reporting as a separate last-activity field — matches the
+ * listing's rule, so the pane and the row agree on what counts as a one-shot. */
+const TIMING_SPAN_MIN_MS = 60_000;
+/**
+ * The three timing facts the header reports: when the session was created, when
+ * it was last active, and how long it ran. Reads the parsed transcript when
+ * there is one and otherwise the indexed `SessionMeta`, so a remote or
+ * unindexed session — which has no local transcript to parse — still reports
+ * them instead of silently dropping the whole line.
+ *
+ * `lastActive` and `lasted` are omitted for a session whose whole life was under
+ * a minute: there they just restate `created`.
+ */
+export function extractTiming(session, events) {
+    const firstMs = Date.parse(events[0]?.timestamp ?? session.timestamp);
     if (Number.isNaN(firstMs))
         return {};
-    const ago = humanDuration(Math.max(0, Date.now() - firstMs));
-    const dur = Number.isNaN(lastMs) ? undefined : humanDuration(Math.max(0, lastMs - firstMs));
-    return { startedAgo: ago, duration: dur };
+    const createdAgo = humanDuration(Math.max(0, Date.now() - firstMs));
+    const lastMs = Date.parse(events[events.length - 1]?.timestamp ?? session.lastActivity ?? session.timestamp);
+    if (Number.isNaN(lastMs))
+        return { createdAgo };
+    // A scan-persisted duration beats the timestamp subtraction when there are no
+    // events to read, because `lastActivity` may have fallen back to file mtime.
+    const spanMs = events.length === 0 && session.durationMs !== undefined
+        ? session.durationMs
+        : Math.max(0, lastMs - firstMs);
+    if (spanMs < TIMING_SPAN_MIN_MS)
+        return { createdAgo };
+    return {
+        createdAgo,
+        lastActiveAgo: humanDuration(Math.max(0, Date.now() - lastMs)),
+        duration: humanDuration(spanMs),
+    };
 }
 function countMessages(events) {
     return events.filter(e => e.type === 'message').length;
@@ -417,9 +443,15 @@ function formatCompactPreview(events, session) {
     }
     // Recent activity = directories touched (not raw tool calls). Prefer a
     // parser-supplied dirsTouched when present; else derive from event paths.
+    // Width-capped: a long Dirs line used to wrap and swamp the whole pane.
     const dirs = directoriesTouched(session, events, changes);
     if (dirs.length) {
-        lines.push(chalk.cyan('Dirs:    ') + chalk.white(dirs.join(chalk.gray(' · '))));
+        lines.push(chalk.cyan('Dirs:    ') + joinWidthCapped(dirs, termWidth - 12));
+    }
+    // Repos worked in (basename of each `.git` root under the touched paths).
+    const repos = extractRepos(events, session.cwd);
+    if (repos.length) {
+        lines.push(chalk.cyan('Repos:   ') + chalk.white(repos.slice(0, 4).join(chalk.gray(' · '))));
     }
     const teamLine = formatTeamLineage(session);
     if (teamLine) {
@@ -442,6 +474,41 @@ function formatCompactPreview(events, session) {
     if (activity.length) {
         lines.push(chalk.cyan('Changes:  ') + activity.join(chalk.gray(' · ')));
     }
+    // Documents the session produced (`.agents/artifacts|plans|reports`, other
+    // *.md/*.html creations) — the files a human browses later, named + clickable.
+    const artifacts = extractArtifacts(changes);
+    if (artifacts.length) {
+        const shown = artifacts.slice(0, 5).map(a => linkPath(a.path, a.basename));
+        const more = artifacts.length > 5 ? chalk.gray(` · +${artifacts.length - 5} more`) : '';
+        lines.push(chalk.cyan('Artifacts: ') + shown.join(chalk.gray(' · ')) + more);
+    }
+    // Skills invoked (plugin skills included — they ride the same Skill tool).
+    const skills = extractSkills(events);
+    if (skills.length) {
+        const shown = skills.slice(0, 5).map(s => chalk.white(s.name) + (s.count > 1 ? chalk.gray(` ×${s.count}`) : ''));
+        const more = skills.length > 5 ? chalk.gray(` · +${skills.length - 5} more`) : '';
+        lines.push(chalk.cyan('Skills:  ') + shown.join(chalk.gray(' · ')) + more);
+    }
+    // Hooks fired (Claude transcripts record firings; other harnesses don't).
+    const hooks = extractHooks(events);
+    if (hooks.length) {
+        const shown = hooks.slice(0, 4).map(h => chalk.white(h.name) + (h.count > 1 ? chalk.gray(` ×${h.count}`) : '') + (h.failed ? chalk.red(` (${h.failed} failed)`) : ''));
+        const more = hooks.length > 4 ? chalk.gray(` · +${hooks.length - 4} more`) : '';
+        lines.push(chalk.cyan('Hooks:   ') + shown.join(chalk.gray(' · ')) + more);
+    }
+    // Links mentioned in the conversation — clickable (OSC 8), tracker-classified.
+    const links = extractLinks(events);
+    if (links.length) {
+        const shown = links.slice(0, 5).map(l => chalk.blue(linkUrl(l.url, l.label)));
+        const more = links.length > 5 ? chalk.gray(` · +${links.length - 5} more`) : '';
+        lines.push(chalk.cyan('Links:   ') + shown.join(chalk.gray(' · ')) + more);
+    }
+    // Error tally, mirroring the full summary's Errors section in one line.
+    const errorEvents = events.filter(e => e.type === 'error');
+    if (errorEvents.length) {
+        const first = errorEvents[0].tool || 'unknown';
+        lines.push(chalk.cyan('Errors:  ') + chalk.red(`${errorEvents.length} failure${errorEvents.length === 1 ? '' : 's'}`) + chalk.gray(` — first: ${first}`));
+    }
     const metadata = [
         ...toolTags,
         subAgentCount ? `${subAgentCount} sub-agent${subAgentCount === 1 ? '' : 's'}` : '',
@@ -559,12 +626,39 @@ function encodeClaudeSlug(absPath) {
 }
 /** The `.agents/worktrees/<name>` marker, Claude-slug-encoded (`/.` → `--`). */
 const SLUG_WORKTREE_RE = /--agents-worktrees-(.+)$/;
+/**
+ * Join display tokens with ` · `, stopping before the line exceeds `maxWidth`
+ * and appending `… +N more` for the rest. Keeps the Dirs line on one row.
+ */
+function joinWidthCapped(items, maxWidth) {
+    const sep = ' · ';
+    let out = '';
+    let shown = 0;
+    for (const item of items) {
+        const next = shown === 0 ? item : out + sep + item;
+        if (shown > 0 && next.length > maxWidth)
+            break;
+        out = next;
+        shown++;
+    }
+    const remaining = items.length - shown;
+    const suffix = remaining > 0 ? ` … +${remaining} more` : '';
+    return chalk.white(out) + (suffix ? chalk.gray(suffix) : '');
+}
 /** Relativize a file path to its parent dir, short enough for one preview line. */
 export function relativizeDir(filePath, cwd) {
     const norm = filePath.replace(/\\/g, '/');
     if (!norm || norm.includes('node_modules') || norm.includes('/.git/') || norm.includes('/plans/')) {
         return undefined;
     }
+    // agents-cli internals — version homes, session/run archives, the bare
+    // worktree container/root — are never meaningful "directories the user works
+    // in". Cwd is exempt: a session running inside such a dir keeps its own paths.
+    const normBase = cwd?.replace(/\\/g, '/').replace(/\/$/, '');
+    const underCwd = normBase && (norm === normBase || norm.startsWith(normBase + '/'));
+    if (!underCwd && (norm.includes('/.agents/.history/') || /\/\.agents\/worktrees(\/[^/]+)?\/?$/.test(norm))) {
+        return undefined;
+    }
     let dir = path.posix.dirname(norm);
     // Claude project-slug form: a leading `-`-segment (`-home-me-…`) that carries
     // the cwd, lossily encoded. Handle it in SLUG SPACE — never lossy-decode to a

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

@@ -11,6 +11,8 @@ interface ResumeOptions {
     ghostty?: boolean;
     tmux?: boolean;
     vscodium?: boolean;
+    /** --terminal-app: force macOS Terminal.app. Named to avoid reading as `run --terminal`. */
+    terminalApp?: boolean;
     splits?: boolean;
 }
 export declare function registerSessionsResumeCommand(sessionsCmd: Command): void;