@phnx-labs/agents-cli 1.20.92 → 1.21.0

package/dist/commands/secrets.js

@@ -31,6 +31,7 @@ import { readMeta } from '../lib/state.js';
 import { parseDuration } from '../lib/hooks/cache.js';
 import { emit, query } from '../lib/events.js';
 import { emitSecretAudit } from '../lib/secrets/audit.js';
+import { getBundleUsage, getAllBundleUsage, getUsageHistory, SECRET_USAGE_EVENTS, } from '../lib/secrets/usage-db.js';
 import { frequentlyPromptedBundles } from '../lib/secrets/unlock-hints.js';
 import { registerCommandGroups, setHelpSections } from '../lib/help.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
@@ -733,6 +734,54 @@ function countExpiringSoon(meta) {
     }
     return n;
 }
+/** Human labels for the usage events, in the order `view` prints them. */
+const USAGE_EVENT_LABELS = {
+    access: 'accessed',
+    unlock: 'unlocked',
+    import: 'imported',
+    export: 'exported',
+    create: 'created',
+    view: 'viewed',
+};
+/**
+ * Compact one-line usage summary for `secrets view` — each recorded event with
+ * its count and how long ago it last happened ("accessed 42× (last 2h ago) ·
+ * exported 3× (last 1d ago)"). Empty string when nothing has been recorded yet.
+ * Pure — unit-tested.
+ */
+export function formatUsageLine(summary) {
+    if (!summary || summary.total === 0)
+        return '';
+    const parts = [];
+    for (const ev of SECRET_USAGE_EVENTS) {
+        const stat = summary.events[ev];
+        if (stat.count === 0)
+            continue;
+        const age = stat.last ? relativeAge(stat.last) : null;
+        parts.push(`${USAGE_EVENT_LABELS[ev]} ${stat.count}×${age ? ` (last ${age})` : ''}`);
+    }
+    return parts.join(' · ');
+}
+/**
+ * The held-state line for `secrets view`: whether the secrets-agent currently
+ * holds this bundle (so reads are prompt-free) and for how long, or that Touch
+ * ID is required on the next read. Only meaningful for keychain bundles on macOS
+ * — file/vault backends have no broker to hold, and a `never`-policy bundle is
+ * always readable — so both return an empty line and the caller skips it.
+ * `heldExpiresAt` is the max expiry across every held scope.
+ */
+export function renderViewStatusLine(b, heldExpiresAt) {
+    if (process.platform !== 'darwin')
+        return '';
+    if ((b.backend ?? 'keychain') !== 'keychain')
+        return '';
+    if (bundlePolicy(b) === 'never')
+        return '';
+    if (heldExpiresAt && heldExpiresAt > Date.now()) {
+        return chalk.green(`status:     unlocked (held ${compactRemaining(heldExpiresAt)}; reads are prompt-free until it locks)`);
+    }
+    return chalk.gray('status:     locked (Touch ID required on the next read; `agents secrets unlock` holds it)');
+}
 /**
  * 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
@@ -819,9 +868,13 @@ export function registerSecretsCommands(program) {
       # Inject the bundle into an agent run
       agents run claude "deploy the worker" --secrets prod
 
-      # See what's in the bundle (values masked); shows its prompt policy
+      # See what's in the bundle (values masked); shows its policy, held state, and usage
       agents secrets view prod
 
+      # Order the list by how recently / how often each bundle is used
+      agents secrets list --sort used
+      agents secrets list --sort uses
+
       # Stop a noisy automation bundle from prompting every run: ask once a week
       agents secrets policy prod hold
 
@@ -839,6 +892,17 @@ export function registerSecretsCommands(program) {
       never touch disk in plaintext. Every item is device-local and gated by Touch ID
       or device passcode; cross-machine sync is handled by 'agents secrets push/pull'.
 
+      Naming: name a bundle after the thing it holds credentials for, so an agent can
+      guess it without listing. For a website, use its domain WITH the real suffix —
+      'stripe.com', 'openai.ai', 'github.com'. For a desktop app, use the app's binary
+      suffix — 'slack.app' (macOS) or 'photoshop.exe' (Windows). Always pass
+      '--description' so 'list' / 'view' explain the bundle without opening it; an
+      undescribed bundle prints a "No description found" nudge. 'view' also shows
+      whether the bundle is currently unlocked (held by the agent) and how often / how
+      recently it has been created, imported, exported, viewed, and accessed;
+      'list --sort used|uses' orders by recency / frequency, and
+      'agents secrets activity [bundle]' prints the recent value-free event timeline.
+
       Touch ID noise: macOS pops a prompt per bundle per process. Each bundle has
       a prompt policy, shown in the POLICY column of 'agents secrets list':
         hold (default)    ask once, then serve it silently from the local agent
@@ -868,7 +932,7 @@ export function registerSecretsCommands(program) {
     `,
     });
     registerCommandGroups(cmd, [
-        { title: 'Bundle commands', names: ['list', 'view', 'create', 'rename', 'describe', 'delete'] },
+        { title: 'Bundle commands', names: ['list', 'view', 'activity', 'create', 'rename', 'describe', 'delete'] },
         { title: 'Secret commands', names: ['add', 'rotate', 'remove', 'import', 'export'] },
         { title: 'Agent commands', names: ['start', 'stop', 'unlock', 'lock', 'status', 'policy'] },
         { title: 'Raw item commands', names: ['get', 'set'] },
@@ -893,7 +957,7 @@ export function registerSecretsCommands(program) {
         .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]))
+        .addOption(new Option('--sort <field>', 'Sort by: name (default), used (most recently used), uses (most frequently accessed), 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);
@@ -942,11 +1006,20 @@ export function registerSecretsCommands(program) {
                 /* broker not running — render policy without the countdown */
             }
         }
+        // Value-free usage read-model backs `--sort used|uses` and the --json
+        // `uses`/`usage` fields. Open the DB only when a caller actually needs it
+        // (a machine payload, or a usage-ranked sort) so a plain human `list`
+        // stays a pure keychain read.
+        const needUsage = Boolean(opts.json) || sortField === 'used' || sortField === 'uses';
+        const usage = needUsage ? getAllBundleUsage() : new Map();
+        const usageHints = new Map();
+        for (const [name, s] of usage)
+            usageHints.set(name, { lastUsedAt: s.lastUsedAt, uses: s.events.access.count });
         // 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 sorted = sortBundles(matched, sortField, usageHints);
         const bundles = limit === undefined ? sorted : sorted.slice(0, limit);
         if (opts.json) {
             // Discovery payload for agents: metadata only, no secret values. Gated on
@@ -974,6 +1047,11 @@ export function registerSecretsCommands(program) {
                 // 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),
+                // Value-free usage from the read-model: `uses` is the recorded access
+                // (read/inject) count; `usage` is the full per-kind rollup. Null when
+                // nothing has been recorded yet.
+                uses: usage.get(b.name)?.events.access.count ?? 0,
+                usage: usage.get(b.name) ?? null,
             }));
             process.stdout.write(JSON.stringify(payload) + '\n');
             return;
@@ -1010,6 +1088,9 @@ export function registerSecretsCommands(program) {
       # Everything, newest-used first
       agents secrets list --sort used
 
+      # Order by how often each bundle is read (most-accessed first)
+      agents secrets list --sort uses
+
       # Find one by name or description
       agents secrets list github
 
@@ -1044,6 +1125,51 @@ export function registerSecretsCommands(program) {
       - --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.
+      - --sort used|uses read the value-free usage read-model (~/.agents/secrets/secrets.db); see 'agents secrets activity'.
+    `,
+    });
+    const activityCmd = cmd
+        .command('activity [name]')
+        .description('Show the recent value-free usage timeline (created / imported / exported / viewed / accessed / unlocked) for one bundle, or across all bundles')
+        .option('-n, --limit <n>', 'Show at most this many events (default 20)')
+        .option('--json', 'Emit machine-readable JSON (metadata only — never secret values)')
+        .action((name, opts) => {
+        let limit = opts.limit === undefined ? 20 : Number(opts.limit);
+        if (!Number.isInteger(limit) || limit < 1) {
+            console.error(chalk.red(`Invalid --limit '${opts.limit}'. Use a whole number of events, e.g. --limit 50.`));
+            process.exit(1);
+        }
+        const events = getUsageHistory(name, limit);
+        if (opts.json) {
+            process.stdout.write(JSON.stringify(events) + '\n');
+            return;
+        }
+        if (events.length === 0) {
+            console.log(chalk.gray(name ? `No recorded activity for '${name}'.` : 'No recorded secrets activity yet.'));
+            return;
+        }
+        for (const e of events) {
+            const who = e.agent ? chalk.gray(` by ${e.agent}`) : '';
+            const where = e.source ? chalk.gray(` (${e.source}${e.host ? ` ${e.host}` : ''})`) : '';
+            const bundleTag = name ? '' : chalk.cyan(` ${e.bundle}`);
+            console.log(`${chalk.gray(relativeAge(e.ts).padEnd(10))} ${chalk.bold(e.event.padEnd(8))}${bundleTag}${who}${where}`);
+        }
+    });
+    setHelpSections(activityCmd, {
+        examples: `
+      # The recent value-free event timeline across every bundle
+      agents secrets activity
+
+      # Just one bundle, more history
+      agents secrets activity anthropic.com --limit 50
+
+      # Machine-readable
+      agents secrets activity anthropic.com --json
+    `,
+        notes: `
+      - Reads the value-free usage read-model (~/.agents/secrets/secrets.db), fed off the
+        same emitSecretAudit chokepoint as 'agents events'. Never a secret value.
+      - History is bounded to the last 90 days; the full audit trail is 'agents events --module secrets'.
     `,
     });
     cmd
@@ -1090,6 +1216,29 @@ export function registerSecretsCommands(program) {
                 process.exit(1);
             }
             const entries = describeBundle(bundle);
+            // Value-free usage read-model (per-kind counts + recency + per-agent) for
+            // both the human and --json views. Read before recording this view so the
+            // just-happened view isn't counted in its own summary.
+            const usage = getBundleUsage(bundle.name);
+            // Is the secrets-agent currently holding this bundle? A held bundle reads
+            // prompt-free. macOS keychain only; take the max expiry across every scope
+            // it's held under. Soft-fails to "not held" if the broker is down.
+            let heldExpiresAt = null;
+            if (process.platform === 'darwin' && (bundle.backend ?? 'keychain') === 'keychain') {
+                try {
+                    for (const e of await agentStatus()) {
+                        if (e.name === bundle.name && (heldExpiresAt === null || e.expiresAt > heldExpiresAt)) {
+                            heldExpiresAt = e.expiresAt;
+                        }
+                    }
+                }
+                catch {
+                    /* broker not running — render as not held */
+                }
+            }
+            // Record the inspection through the ONE chokepoint (events.jsonl + the
+            // usage read-model). Value-free; a masked `view` is metadata only.
+            emitSecretAudit({ event: 'secrets.view', bundle: bundle.name, operation: opts.json ? 'view --json' : 'view', source: 'view', status: 'success' });
             if (opts.json) {
                 // Machine-readable discovery for agents. Values are null unless --reveal
                 // (which still routes through the same non-TTY/plaintext gate + audit
@@ -1158,14 +1307,25 @@ export function registerSecretsCommands(program) {
                     createdAt: bundle.created_at ?? null,
                     updatedAt: bundle.updated_at ?? null,
                     lastUsed: bundle.last_used ?? null,
+                    // Held state + value-free usage rollup, same data the human view
+                    // shows. `heldExpiresAt` is null when the bundle is not held.
+                    heldExpiresAt,
+                    usage: usage ?? null,
+                    uses: usage?.events.access.count ?? 0,
                     revealed: reveal,
                     keys,
                 }) + '\n');
                 return;
             }
             console.log(chalk.bold(bundle.name));
-            if (bundle.description)
+            if (bundle.description) {
                 console.log(chalk.gray(safePrint(bundle.description)));
+            }
+            else {
+                // A described bundle is self-documenting for the next agent/human that
+                // reads it. Nudge — never block — toward adding one.
+                console.log(chalk.yellow(`No description found. Add one: agents secrets describe ${bundle.name} "what this bundle is for"`));
+            }
             if (bundle.allow_exec)
                 console.log(chalk.yellow('allow_exec: true'));
             if (bundle.backend === 'file')
@@ -1183,12 +1343,22 @@ export function registerSecretsCommands(program) {
                     ? 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)'));
             }
+            const statusLine = renderViewStatusLine(bundle, heldExpiresAt);
+            if (statusLine)
+                console.log(statusLine);
             if (bundle.created_at)
                 console.log(chalk.gray(`created_at: ${bundle.created_at} (${humanAge(bundle.created_at)})`));
             if (bundle.updated_at)
                 console.log(chalk.gray(`updated_at: ${bundle.updated_at} (${humanAge(bundle.updated_at)})`));
             if (bundle.last_used)
                 console.log(chalk.gray(`last_used:  ${bundle.last_used} (${humanAge(bundle.last_used)})`));
+            const usageLine = formatUsageLine(usage);
+            if (usageLine)
+                console.log(chalk.gray(`usage:      ${usageLine}`));
+            if (usage && usage.byAgent.length > 0) {
+                const top = usage.byAgent.slice(0, 3).map((a) => `${a.agent} ${a.count}×`).join(', ');
+                console.log(chalk.gray(`by:         ${top}`));
+            }
             console.log();
             if (entries.length === 0) {
                 console.log(chalk.gray('(no keys)'));
@@ -1357,8 +1527,8 @@ export function registerSecretsCommands(program) {
     });
     cmd
         .command('create [name]')
-        .description('Create an empty bundle')
-        .option('--description <text>', 'Free-form description')
+        .description('Create an empty bundle. Name it after what it holds — a website by domain (stripe.com, openai.ai), a desktop app by its binary suffix (slack.app, photoshop.exe) — and pass --description.')
+        .option('--description <text>', 'Free-form description (recommended — an undescribed bundle prints a "No description found" nudge)')
         .option('--allow-exec', 'Allow exec: refs in this bundle (off by default)')
         .option('--policy <policy>', "prompt policy: hold (default, ask once per hold window — secrets.agent.holdMs, 7d by default), always (ask every time), or never (silent, NO biometry ACL — needs --i-understand). 'daily'/'session' are accepted aliases for 'hold'.")
         .addOption(new Option('--tier <policy>', 'deprecated alias for --policy').hideHelp())
@@ -1395,6 +1565,9 @@ export function registerSecretsCommands(program) {
                 vars: {},
             };
             writeBundle(bundle);
+            // Record the create through the ONE chokepoint (events.jsonl + the usage
+            // read-model). Value-free — bundle name only.
+            emitSecretAudit({ event: 'secrets.create', bundle: resolvedName, operation: 'create', source: 'create', status: 'success' });
             const policyTag = bundlePolicy(bundle) === 'hold'
                 ? 'policy: hold'
                 : bundlePolicy(bundle) === 'always'
@@ -1406,6 +1579,11 @@ export function registerSecretsCommands(program) {
                 backend === 'vault' ? 'synced' : null,
             ].filter(Boolean);
             console.log(chalk.green(`Bundle '${resolvedName}' created (${tags.join(', ')}).`));
+            if (!bundle.description) {
+                // A described bundle is self-documenting for the next agent that reads
+                // `list` / `view`. Nudge toward one at create time — never blocking.
+                console.log(chalk.yellow(`No description found. Add one: agents secrets describe ${resolvedName} "what this bundle is for"`));
+            }
             if (bundlePolicy(bundle) === 'never') {
                 console.log(chalk.red('Stored without biometry protection — reads are silent. Automation-only; rotate anything sensitive out of it.'));
             }
@@ -1807,6 +1985,7 @@ Examples:
                 const resolvedBundleName = bundleName ?? (await pickBundleName('import into'));
                 const bundle = resolveImportBundle(resolvedBundleName, opts.backend, opts.synced);
                 const { added, skipped } = applyEnvToBundle(bundle, env, opts);
+                emitSecretAudit({ event: 'secrets.import', bundle: bundle.name, operation: 'import --from-file', source: 'file', status: 'success', keyCount: added });
                 console.log(chalk.green(`Imported ${added} key(s) from file${skipped ? `, skipped ${skipped} (already set, pass --force)` : ''}.`));
                 return;
             }
@@ -1820,6 +1999,7 @@ Examples:
                 const env = await remoteResolveEnv(target, resolvedBundleName, { osLookupName: opts.host });
                 const bundle = resolveImportBundle(resolvedBundleName, opts.backend, opts.synced);
                 const { added, skipped } = applyEnvToBundle(bundle, env, opts);
+                emitSecretAudit({ event: 'secrets.import', bundle: bundle.name, operation: 'import --from-ssh', source: 'ssh', host: opts.host, status: 'success', keyCount: added });
                 console.log(chalk.green(`Imported ${added} key(s) from ${opts.host}${skipped ? `, skipped ${skipped} (already set, pass --force)` : ''}.`));
                 return;
             }
@@ -1855,6 +2035,7 @@ Examples:
                 for (const { envKey, value } of secrets)
                     env[envKey] = value;
                 const { added, skipped } = applyEnvToBundle(bundle, env, opts);
+                emitSecretAudit({ event: 'secrets.import', bundle: bundle.name, operation: `import --from 1password:${vault}`, source: '1password', status: 'success', keyCount: added });
                 if (opSkipped.length) {
                     console.log(chalk.yellow(`Skipped ${opSkipped.length} item(s) with no importable fields.`));
                 }
@@ -1864,6 +2045,7 @@ Examples:
                 const raw = readImportDotenv(source.path);
                 const pairs = parseDotenv(raw);
                 const { added, skipped } = applyEnvToBundle(bundle, pairs, opts);
+                emitSecretAudit({ event: 'secrets.import', bundle: bundle.name, operation: 'import --from env-file', source: 'env-file', status: 'success', keyCount: added });
                 console.log(chalk.green(`Imported ${added} key(s)${skipped ? `, skipped ${skipped} (already set, pass --force)` : ''}.`));
             }
         }
@@ -1903,6 +2085,7 @@ Examples:
                 }
                 const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: 'export --to-file', keyMode: 'storage', agentOnly: isHeadlessSecretsContext() });
                 exportBundleToFile(env, opts.toFile, passphrase);
+                emitSecretAudit({ event: 'secrets.export', bundle: resolvedBundleName, operation: 'export --to-file', source: 'file', status: 'success', keyCount: Object.keys(env).length });
                 console.log(chalk.green(`Exported ${Object.keys(env).length} key(s) to ${opts.toFile}`));
                 return;
             }
@@ -2009,6 +2192,7 @@ Examples:
                     const remoteMsg = (res.stdout || '').trim().split('\n').map((l) => l.trim()).filter(Boolean).pop();
                     console.log(chalk.green(`${host} -> '${resolvedBundleName}': ${remoteMsg || `${keyCount} key(s) exported`}`));
                 }
+                emitSecretAudit({ event: 'secrets.export', bundle: resolvedBundleName, operation: `export --host ${hosts.join(',')}`, source: 'ssh', host: hosts.join(','), status: failures > 0 ? 'error' : 'success', keyCount });
                 if (failures > 0)
                     process.exit(1);
                 return;
@@ -2043,6 +2227,7 @@ Examples:
                     parts.push(`${overwritten} overwritten`);
                 if (skipped)
                     parts.push(`${skipped} skipped (already exist, pass --force)`);
+                emitSecretAudit({ event: 'secrets.export', bundle: resolvedBundleName, operation: `export --to-1password ${vault}`, source: '1password', status: 'success', keyCount: created + overwritten });
                 console.log(chalk.green(`Exported to 1Password vault '${vault}': ${parts.join(', ')}.`));
                 return;
             }
@@ -2077,6 +2262,12 @@ Examples:
                 const output = needsQuotes ? `'${v.replace(/'/g, `'\\''`)}'` : v;
                 process.stdout.write(`export ${exportKey}=${output}\n`);
             }
+            // Record the shell export (the `eval "$(...)"` path). The `--format json`
+            // branch above is the machine-to-machine remote-resolve transport (already
+            // counted as an access on this machine by the resolve above), so it is
+            // deliberately not counted here as an export — that would tally every peer
+            // pull as an export.
+            emitSecretAudit({ event: 'secrets.export', bundle: resolvedBundleName, operation: 'export --plaintext', source: 'shell', status: 'success', keyCount: Object.keys(env).length });
         }
         catch (err) {
             if (isPromptCancelled(err))

package/dist/commands/send.d.ts

@@ -1,19 +1,21 @@
 /**
- * `agents send <text> --channel <name> --to <target>` — deliver a message over
- * any registered channel (mailbox, telegram, imessage, slack, discord, desktop, apps).
+ * `agents send` — deliver a message over any registered channel provider.
  *
- * `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.
+ * Envelope (flag-first, industry-shaped):
+ *   agents send --to <dest> --text "…" [--channel <name>] [--attach …] [--url …]
  *
- * `agents notify <text>` — owner-facing alias. Fills channel + target from the
- * `notify.owner` block in agents.yaml when not passed, so routines/agents ping
- * the owner without hardcoding a chat id / host / account.
+ * Destination:
+ *   --to owner          expands to notify.owner.{channel,to} in agents.yaml
+ *   --to <id>           channel-specific recipient (requires --channel)
  *
- * Both go through one `doSend()` seam: resolve the provider for the channel
- * (notify.transports picks the transport per host) and call provider.send().
- * The agent mailbox is just one channel; `agents message` stays the richer
- * agent-control command (feed-claim / identity / PTY / resume) on the same spool.
+ * Compat: positional text still works (`agents send "hi" --channel … --to …`).
+ *
+ * `agents notify` is the same delivery path with owner defaults
+ * (`send --to owner`). Not a second stack. Not agent control — use
+ * `agents message` / `agents sessions inject` for running agents.
+ *
+ * Feed / activity are a different plane (record + read); feed.broadcast may
+ * call this command as a forward sink.
  */
 import type { Command } from 'commander';
 export declare function registerSendCommand(program: Command): void;

package/dist/commands/send.js

@@ -1,20 +1,39 @@
 import chalk from 'chalk';
 import { die } from '../lib/format.js';
+import { setHelpSections } from '../lib/help.js';
 import { readMeta } from '../lib/state.js';
-import { registerBuiltinProviders } from '../lib/channels/providers/index.js';
-import { resolveTransport } from '../lib/channels/resolve.js';
-async function doSend(text, channel, to, opts) {
-    registerBuiltinProviders();
-    const provider = resolveTransport(channel, readMeta());
-    const result = await provider.send(text, {
-        target: to,
+import { sendMessage } from '../lib/channels/send.js';
+function mergeAttachments(opts) {
+    const list = [...(opts.attach ?? []), ...(opts.attachment ?? [])];
+    return list.length ? list : undefined;
+}
+function toInput(positionalText, opts, ownerMode) {
+    return {
+        text: opts.text,
+        positionalText,
+        to: opts.to,
+        channel: opts.channel,
         thread: opts.thread,
-        attachments: opts.attachment,
+        attachments: mergeAttachments(opts),
+        urls: opts.url,
         from: opts.from,
         dryRun: opts.dryRun,
-    });
+        ownerMode,
+    };
+}
+async function runSend(positionalText, opts, ownerMode) {
+    const meta = readMeta();
+    const out = await sendMessage(toInput(positionalText, opts, ownerMode), meta);
+    if ('error' in out) {
+        die(out.error);
+    }
+    const { result, envelope } = out;
     if (opts.json) {
-        console.log(JSON.stringify(result));
+        console.log(JSON.stringify({
+            ...result,
+            text: envelope.text,
+            dryRun: Boolean(envelope.dryRun),
+        }));
         if (!result.ok)
             process.exit(1);
         return;
@@ -23,40 +42,91 @@ async function doSend(text, channel, to, opts) {
         die(`send failed [${result.channel} → ${result.id}]: ${result.error ?? 'unknown error'}`);
     }
     const suffix = result.msgId ? chalk.dim(` (${result.msgId})`) : '';
-    const dry = opts.dryRun ? chalk.dim(' [dry-run]') : '';
+    const dry = envelope.dryRun ? chalk.dim(' [dry-run]') : '';
     console.log(chalk.green(`Sent via ${result.channel} → ${result.id}`) + suffix + dry);
 }
+const SHARED_NOTES = `
+  Planes (do not mix them up):
+    send / notify     - DELIVER a message to a recipient (this command)
+    feed post         - RECORD progress / milestones (optional broadcast may call send)
+    activity          - READ the activity stream (not a send path)
+    message / inject  - CONTROL a running agent (mailbox answer or terminal keystroke)
+
+  --to owner is an address alias for notify.owner in agents.yaml, not a
+  special control path. Agent resume / PTY inject stay on message and
+  sessions inject.
+`;
 export function registerSendCommand(program) {
-    program
-        .command('send <text>')
-        .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')
+    const sendCmd = program
+        .command('send [text]')
+        .description('Deliver a message through a channel provider (imessage, slack, desktop, mailbox, …). Prefer --text/--to flags.')
+        .option('--text <text>', 'message body (preferred over positional text)')
+        .option('--to <target>', 'recipient id, or "owner" for notify.owner in agents.yaml')
+        .option('--channel <name>', 'channel / provider (required unless --to owner)')
         .option('--thread <id>', 'channel thread id / timestamp')
-        .option('--attachment <path...>', 'file attachment path (repeatable)')
+        .option('--attach <path...>', 'local file attachment path (repeatable)')
+        .option('--attachment <path...>', 'alias of --attach')
+        .option('--url <url...>', 'link or remote media URL to include in the body (repeatable)')
         .option('--from <who>', 'sender label (mailbox)')
         .option('--json', 'output JSON')
-        .option('--dry-run', 'resolve + build but do not send')
-        .action(async (text, opts) => {
-        await doSend(text, opts.channel, opts.to, opts);
+        .option('--dry-run', 'resolve + build but do not send');
+    setHelpSections(sendCmd, {
+        examples: `
+      # Flag-first envelope (preferred)
+      agents send --channel imessage --to "+18055550100" --text "PR #1803 is green"
+      agents send --to owner --text "need a decision on the release"
+      agents send --channel desktop --to local --text "deploy finished" --url https://example.com/pr/1
+      agents send --channel mailbox --to <session-id> --text "peer note" --from orchestrator
+
+      # Attach a local file
+      agents send --to owner --text "screenshot" --attach ./out/cover.png
+
+      # Owner alias without the notify verb
+      agents send --to owner --text "wiring test"
+
+      # Legacy positional text still works
+      agents send "hi" --channel desktop --to local
+
+      # Dry-run (resolve provider, no delivery)
+      agents send --to owner --text "probe" --dry-run --json
+    `,
+        notes: SHARED_NOTES,
     });
-    program
-        .command('notify <text>')
-        .description('Notify the owner (channel + target default to notify.owner in agents.yaml).')
+    sendCmd.action(async (text, opts) => {
+        await runSend(text, opts, false);
+    });
+    const notifyCmd = program
+        .command('notify [text]')
+        .description('Deliver to the owner (alias of send --to owner). Channel + target default from notify.owner in agents.yaml.')
+        .option('--text <text>', 'message body (preferred over positional text)')
         .option('--channel <name>', 'override owner channel')
-        .option('--to <target>', 'override owner target')
+        .option('--to <target>', 'override owner target (or pass a non-owner dest with --channel)')
         .option('--thread <id>', 'channel thread id / timestamp')
-        .option('--attachment <path...>', 'file attachment path (repeatable)')
+        .option('--attach <path...>', 'local file attachment path (repeatable)')
+        .option('--attachment <path...>', 'alias of --attach')
+        .option('--url <url...>', 'link or remote media URL to include in the body (repeatable)')
+        .option('--from <who>', 'sender label (mailbox)')
         .option('--json', 'output JSON')
-        .option('--dry-run', 'resolve + build but do not send')
-        .action(async (text, opts) => {
-        const owner = readMeta().notify?.owner;
-        const channel = opts.channel ?? owner?.channel;
-        const to = opts.to ?? owner?.to;
-        if (!channel || !to) {
-            die('notify: no --channel/--to given and no notify.owner.{channel,to} in agents.yaml. ' +
-                'Set notify.owner or pass --channel/--to.');
-        }
-        await doSend(text, channel, to, opts);
+        .option('--dry-run', 'resolve + build but do not send');
+    setHelpSections(notifyCmd, {
+        examples: `
+      # Same as: agents send --to owner --text "…"
+      agents notify --text "Build finished — PR #1346 is green"
+      agents notify "legacy positional still works"
+
+      # Override channel for this one ping
+      agents notify --text "fallback" --channel desktop --to local
+
+      agents notify --text "probe" --dry-run --json
+    `,
+        notes: `
+      notify ≡ send --to owner. One delivery stack (lib/channels). Set
+      notify.owner.{channel,to} in agents.yaml once per machine/fleet.
+
+      ${SHARED_NOTES}
+    `,
+    });
+    notifyCmd.action(async (text, opts) => {
+        await runSend(text, opts, true);
     });
 }

package/dist/commands/sessions.d.ts

@@ -315,6 +315,13 @@ export declare function isBareBrowserListing(options: SessionsOptions, query: st
  * `runSessionBrowser` picker cannot represent.
  */
 export declare function hasNoBrowserDisqualifyingFlags(options: SessionsOptions, query: string | undefined): boolean;
+/** Resolve a session by id/query globally and print its compact preview (no pager).
+ * Backs `--preview` — the fast path for the "peek before resume" hot loop. */
+export declare function renderSessionPreview(query: string, scope: {
+    agent?: string;
+    project?: string;
+    local?: boolean;
+}): Promise<void>;
 /**
  * The one-line live status banner shown above a session preview: the glyph, the
  * status word, and — when the session needs a human or has LOST one — a plain
@@ -351,6 +358,16 @@ export declare function teamBadge(session: SessionMeta): {
  * when `showTicket` — otherwise a listing with no refs would waste a column of
  * dashes and needlessly truncate the topic. Worktree stays a trailing badge. */
 export declare function flatSessionRow(session: SessionMeta, live?: ActiveSession, showTicket?: boolean, cols?: PickerColumns, favorite?: boolean): string;
+/**
+ * Live-session index for enriching the default listing, or undefined when
+ * enrichment is off (`--no-live`) or irrelevant (`--json`, which serializes
+ * SessionMeta). Full detection (incl. the headless `ps` scan) is deliberate:
+ * bare-CLI and tmux agents are the common case here, and skipping them would
+ * leave the glyph almost never showing. The listing is a one-shot user action,
+ * not a hot loop, so the `ps`/`lsof` cost is acceptable; `--no-live` is the
+ * escape hatch. Never throws — a probe failure just yields a plain listing.
+ */
+export declare function maybeLiveIndex(options: SessionsOptions): Promise<Map<string, ActiveSession> | undefined>;
 /**
  * Group key for the overview: resolve the cwd through the same canonical
  * resolver the `agents activity` timeline groups by — a defined project's name