@phnx-labs/agents-cli 1.22.40 → 1.22.41

package/dist/commands/secrets.js

@@ -18,7 +18,7 @@ import { ensureDaemonStarted, isDaemonRunning } from '../lib/daemon/daemon.js';
 import { parseHostsOption, remoteResolveEnv, remoteSecretsRaw, remoteSecretsStream, resolveHostSshTarget, } from '../lib/secrets/remote.js';
 import { resolveBundleForPush, pushResolvedBundleToHost, bundleEnvToDotenv } from '../lib/secrets/push.js';
 export { bundleEnvToDotenv };
-import { bundleBackend, bundleExists, bundleItemStore, bundlePolicy, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, healKeychainBundleMetadataAclOnce, isHeadlessSecretsContext, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, readBundle, readBundleIfDecryptable, reAclBundleItems, renameBundle, rotateBundleSecret, sanitizeProcessEnv, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, writeBundleWithItems, SECRET_TYPES, } from '../lib/secrets/bundles.js';
+import { bundleBackend, bundleExists, bundleItemStore, bundlePolicy, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, healKeychainBundleMetadataAclOnce, isHeadlessSecretsContext, isAgentInvocationContext, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, readBundle, readBundleIfDecryptable, reAclBundleItems, 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, hasKeychainToken, secretsKeychainItem, setKeychainToken, maybeAutoRekey, } from '../lib/secrets/index.js';
@@ -38,7 +38,6 @@ import { frequentlyPromptedBundles } from '../lib/secrets/unlock-hints.js';
 import { registerCommandGroups, setHelpSections } from '../lib/help.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { discoverSyncedBundles, importSyncedBundle, } from '../lib/secrets/icloud-import.js';
-import { getVaultSession, vaultExists } from '../lib/secrets/vault.js';
 import { registerSecretsSyncCommands } from './secrets-sync.js';
 import { registerSecretsMigrateAclCommand } from './secrets-migrate.js';
 import { registerSecretsImportKeyringCommand } from './secrets-import.js';
@@ -924,14 +923,17 @@ export function registerSecretsCommands(program) {
       # Stop a noisy automation bundle from prompting every run: ask once a week
       agents secrets policy prod hold
 
-      # Eval the bundle into your current shell
-      eval "$(agents secrets export prod --plaintext)"
+      # Run a one-off command with secrets injected (values ride the child env, never stdout)
+      agents secrets exec prod -- ./deploy.sh
+
+      # Need one value inside a script? Read it under injection, not with a printer
+      agents secrets exec prod -- printenv STRIPE_API_KEY
+
+      # Deliberately reveal values at your terminal (interactive only)
+      agents secrets view prod --reveal
 
       # Push the bundle to remote machine(s) over SSH (lands as a native bundle there)
       agents secrets export prod --device yosemite-s0 --device yosemite-s1 --force
-
-      # Run a one-off command with secrets injected
-      agents secrets exec prod -- ./deploy.sh
     `,
         notes: `
       Bundles are containers; secrets are the variables inside them. Keychain values
@@ -1222,13 +1224,22 @@ export function registerSecretsCommands(program) {
         .command('view [name]')
         .alias('show')
         .description('Show a bundle. Keychain values are masked by default — pass --reveal to see them.')
-        .option('--reveal', 'Print keychain-backed values in the clear (TTY only unless --plaintext)')
-        .option('--plaintext', 'Allow --reveal in non-interactive shells (use with care)')
+        .option('--reveal', 'Print keychain-backed values in the clear (interactive terminal only)')
         .option('--json', 'Emit machine-readable JSON (values masked unless --reveal) instead of the human view')
         .option('--device <target>', 'Show a bundle on a remote device over SSH (enrolled `agents hosts` name, ssh-config alias, or user@host)')
         .option('--devices <list>', 'Comma-separated devices to show in one shot, e.g. yosemite-s0,yosemite-s1')
         .action(async (name, opts) => {
         try {
+            // `--reveal` is a deliberate HUMAN reveal: interactive terminal only, and
+            // never inside an agent session (an agent under tmux has a TTY, so the
+            // env markers are the load-bearing check). The old `--plaintext` escape
+            // that allowed a piped/non-TTY reveal is removed (RUSH-2774) — printed
+            // values land in an agent's context and session transcript.
+            if (opts.reveal && (isAgentInvocationContext() || !isInteractiveTerminal())) {
+                console.error(chalk.red('--reveal prints values in the clear and needs a real interactive terminal outside an agent session.'));
+                console.error(chalk.dim('Run the consuming command under injection instead: agents secrets exec <bundle> -- <cmd>'));
+                process.exit(1);
+            }
             const targets = parseHostsOption({ device: opts.device, devices: opts.devices });
             if (targets.length > 0) {
                 if (!name) {
@@ -1238,14 +1249,13 @@ export function registerSecretsCommands(program) {
                 const args = ['view', name];
                 if (opts.reveal)
                     args.push('--reveal');
-                if (opts.plaintext)
-                    args.push('--plaintext');
                 if (opts.json)
                     args.push('--json');
                 // With --reveal, force a TTY so the remote keychain prompt can surface
-                // (and the remote's "--reveal in a non-TTY needs --plaintext" gate is
-                // satisfied) — only when this side is itself interactive.
-                const tty = Boolean(opts.reveal) && Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+                // and the remote's own interactive-terminal gate is satisfied. The
+                // early gate above already proved this side is an interactive,
+                // non-agent terminal.
+                const tty = Boolean(opts.reveal);
                 // `--reveal` streams the plaintext value back over ssh stdout — a
                 // secret-bearing read that must pin the host key and not multiplex,
                 // whether it runs on the interactive (tty) or `--plaintext` non-tty path.
@@ -1288,14 +1298,10 @@ export function registerSecretsCommands(program) {
             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
-                // event as the human path). Gated on the explicit flag, not stdout.isTTY,
-                // so a piped human view never silently swaps formats.
+                // (already gated above: interactive terminal, outside an agent session).
+                // Gated on the explicit flag, not stdout.isTTY, so a piped human view
+                // never silently swaps formats.
                 const reveal = Boolean(opts.reveal);
-                if (reveal && !isInteractiveTerminal() && !opts.plaintext) {
-                    console.error(chalk.red('--reveal in a non-TTY requires --plaintext.'));
-                    process.exit(1);
-                }
                 const revealed = new Map();
                 if (reveal) {
                     const { env } = readAndResolveBundleEnv(bundle.name, {
@@ -1415,10 +1421,6 @@ export function registerSecretsCommands(program) {
                 return;
             }
             const reveal = Boolean(opts.reveal);
-            if (reveal && !isInteractiveTerminal() && !opts.plaintext) {
-                console.error(chalk.red('--reveal in a non-TTY requires --plaintext.'));
-                process.exit(1);
-            }
             // An explicit human `view --reveal` at a terminal is a deliberate value
             // access: resolve interactively (one Touch ID) so a locked bundle shows
             // its values. Under an agent (AGENTS_RUNTIME) or headless (no TTY) it
@@ -1491,50 +1493,38 @@ export function registerSecretsCommands(program) {
     });
     cmd
         .command('get <item> [key]')
-        .description('Print one secret value for shell hooks/automation. One arg = a raw keychain item by name; two args = one KEY out of a bundle (`get <bundle> <KEY>`). Cross-platform.')
+        .description('Print one raw keychain item by name, for shell hooks/automation. Cross-platform. Bundle values are never printed — run commands under `agents secrets exec` instead.')
         .action((item, key) => {
-        if (key === undefined) {
-            // Raw keychain item path — unchanged.
-            try {
-                // Routes through the platform keychain layer: macOS reads bare items
-                // via /usr/bin/security (no Touch ID), Linux via secret-tool with the
-                // encrypted-file fallback. The value goes to stdout (newline-terminated
-                // so `$(agents secrets get NAME)` captures it cleanly); diagnostics go
-                // to stderr so they never pollute the captured value.
-                const value = getKeychainToken(item);
-                // Raw item reads bypass readAndResolveBundleEnv, so audit here too.
-                // `item` is the keychain service name, never the value.
-                emitSecretAudit({ event: 'secrets.get', item, source: 'raw-item', status: 'success' });
-                process.stdout.write(value.endsWith('\n') ? value : `${value}\n`);
-            }
-            catch {
-                // Missing item is a normal, quiet outcome for a hook probe: exit 1,
-                // print nothing to stdout. Callers test the exit code / empty capture.
-                process.exit(1);
-            }
-            return;
+        if (key !== undefined) {
+            // The bundle-key form (`get <bundle> <KEY>`) is REMOVED (RUSH-2774): a
+            // one-liner that prints a bundle credential is the exfiltration path
+            // this change closes, for every caller. The injection replacement is
+            // just as short for a human script and never touches this stdout.
+            console.error(chalk.red(`'secrets get <bundle> <KEY>' has been removed — printing a bundle value to stdout is the exfiltration path this blocks.`));
+            console.error(chalk.dim(`Use: agents secrets exec ${item} -- printenv ${key}   (or run the consuming command directly under exec)`));
+            process.exit(1);
         }
-        // Bundle-key path: `get <bundle> <KEY>` prints exactly one resolved value.
-        // Ungated like the raw path (it IS the automation primitive); the
-        // `secrets.get` audit event is emitted inside readAndResolveBundleEnv.
+        // Raw keychain item path — a single ad-hoc token, not a credential bundle.
+        // Deliberately NOT agent-gated (unlike the removed bundle-key form): shell
+        // hooks that run inside agent sessions inherit the session env markers and
+        // legitimately capture a raw item into their own variables (e.g. the
+        // posthog analytics hook), where the value never reaches the transcript.
+        // A single ad-hoc token is the accepted narrower residual (RUSH-2774).
         try {
-            if (!bundleExists(item) && !(vaultExists() && !getVaultSession().loggedIn)) {
-                console.error(chalk.red(`Secrets bundle '${item}' not found.`));
-                process.exit(1);
-            }
-            // `secrets get` is the scriptable automation primitive ($(agents secrets
-            // get bundle KEY)). Every read is broker-only; a locked bundle points at
-            // the explicit unlock command instead of raising Touch ID.
-            const { env } = readAndResolveBundleEnv(item, { caller: 'secrets get', keys: [key], keyMode: 'storage', agentOnly: true });
-            if (!(key in env)) {
-                console.error(chalk.red(`Key '${key}' not in bundle '${item}'.`));
-                process.exit(1);
-            }
-            const value = env[key];
+            // Routes through the platform keychain layer: macOS reads bare items
+            // via /usr/bin/security (no Touch ID), Linux via secret-tool with the
+            // encrypted-file fallback. The value goes to stdout (newline-terminated
+            // so `$(agents secrets get NAME)` captures it cleanly); diagnostics go
+            // to stderr so they never pollute the captured value.
+            const value = getKeychainToken(item);
+            // Raw item reads bypass readAndResolveBundleEnv, so audit here too.
+            // `item` is the keychain service name, never the value.
+            emitSecretAudit({ event: 'secrets.get', item, source: 'raw-item', status: 'success' });
             process.stdout.write(value.endsWith('\n') ? value : `${value}\n`);
         }
-        catch (err) {
-            console.error(chalk.red(err.message));
+        catch {
+            // Missing item is a normal, quiet outcome for a hook probe: exit 1,
+            // print nothing to stdout. Callers test the exit code / empty capture.
             process.exit(1);
         }
     });
@@ -2133,18 +2123,23 @@ Examples:
     });
     cmd
         .command('export [bundle]')
-        .description('Resolve a bundle and print KEY=VALUE lines, push it to a 1Password vault with --to-1password, or push it to remote machine(s) over SSH with --device.')
-        .option('--plaintext', 'Acknowledge that the resolved values will be printed in the clear (shell export mode)')
+        .description('Move a bundle without exposing it: push to remote machine(s) over SSH with --device, to a 1Password vault with --to-1password, or to an encrypted file with --to-file.')
+        // Both transport flags are hidden, not documented: the ONLY caller is the
+        // machine-to-machine SSH resolve (remoteResolveEnv / verifyRemoteKeychainPush),
+        // which sets AGENTS_SECRETS_REMOTE_TRANSPORT=1 on the remote invocation. The
+        // old public shell-eval mode (`eval "$(agents secrets export … --plaintext)"`)
+        // was the top agent-exfiltration path and is removed (RUSH-2774).
+        .addOption(new Option('--plaintext', 'internal remote-resolve transport').hideHelp())
+        .addOption(new Option('--format <json>', 'internal remote-resolve transport').hideHelp())
         .option('--to-1password', 'Push every key in the bundle as a PASSWORD item in a 1Password vault')
         .option('--vault <name>', '1Password vault name (used with --to-1password)')
         .option('--device <target...>', 'Push the bundle over SSH to this device (host alias or user@host); repeatable for multiple machines')
         .option('--remote-backend <backend>', 'Backend for the bundle on the remote device (with --device): keychain (default) or file. file is headless-readable via the remote\'s machine-local key; it forwards AGENTS_SECRETS_PASSPHRASE over stdin only if set (opt-in).', 'keychain')
         .option('--force', 'Overwrite existing keys/items on the target (used with --to-1password and --device)')
-        .option('--format <shell|json>', 'Output for --plaintext export: shell (default) or json (lossless, machine-readable; used by remote resolve)', 'shell')
         .option('--to-file <path>', `Write the bundle as an AES-256-GCM encrypted offline file (needs ${SYNC_PASSPHRASE_ENV}; symmetric counterpart of import --from-file)`)
         .action(async (bundleName, opts) => {
         try {
-            const { readAndResolveBundleEnv, bundleToEnvPrefix, isReservedEnvName } = await import('../lib/secrets/bundles.js');
+            const { readAndResolveBundleEnv } = await import('../lib/secrets/bundles.js');
             const resolvedBundleName = bundleName ?? (await pickBundleName('export'));
             if (opts.toFile) {
                 // Transport, not the local store's master key — see lib/secrets/sync-passphrase.ts.
@@ -2251,41 +2246,36 @@ Examples:
                 console.log(chalk.green(`Exported to 1Password vault '${vault}': ${parts.join(', ')}.`));
                 return;
             }
-            if (opts.format && opts.format !== 'shell' && opts.format !== 'json') {
-                console.error(chalk.red(`Invalid --format ${JSON.stringify(opts.format)}. Expected 'shell' or 'json'.`));
+            // The shell-eval print mode (`eval "$(agents secrets export … --plaintext)"`)
+            // is REMOVED (RUSH-2774): a whole bundle printed to stdout lands in a
+            // coding agent's context and session transcript, and it was the single
+            // most-copied exfiltration one-liner on the fleet. The sole surviving
+            // stdout emitter is the machine-to-machine SSH resolve transport, which
+            // requires the remote-invocation marker AND a non-agent context — both
+            // set only by remoteResolveEnv / verifyRemoteKeychainPush building the
+            // remote command. Everything else gets the refusal with the paved paths.
+            const isTransportCall = process.env.AGENTS_SECRETS_REMOTE_TRANSPORT === '1' &&
+                Boolean(opts.plaintext) &&
+                opts.format === 'json' &&
+                !isAgentInvocationContext();
+            if (!isTransportCall) {
+                console.error(chalk.red('export no longer prints values. Pick a destination:'));
+                console.error(chalk.red('  --device <host> | --to-1password | --to-file <path>'));
+                console.error(chalk.dim(`Run a command with the values injected instead:  agents secrets exec ${resolvedBundleName} -- <cmd>`));
+                console.error(chalk.dim(`Reveal one value at your terminal:               agents secrets view ${resolvedBundleName} --reveal`));
                 process.exit(1);
             }
-            if (!opts.plaintext) {
-                console.error(chalk.red('export prints secrets in the clear and requires --plaintext (works for TTY and pipes alike).'));
-                process.exit(1);
-            }
-            // `agents secrets export --plaintext` is what release/CI scripts eval.
-            // Every caller is broker-only, including a plain shell, so export never
-            // raises Touch ID on the interactive user's screen.
+            // Machine-readable form consumed by `remoteResolveEnv` over SSH: single
+            // object of injected env KEY -> value; values verbatim. Broker-only, so a
+            // headless remote read fails fast rather than raising Touch ID. The
+            // resolve emits its own `secrets.get` audit on the remote; no export
+            // event here — that would tally every peer pull as an export.
             const { env } = readAndResolveBundleEnv(resolvedBundleName, {
-                caller: `export to shell`,
+                caller: 'remote resolve transport',
                 keyMode: 'process',
                 agentOnly: true,
             });
-            if (opts.format === 'json') {
-                // Machine-readable form consumed by `remoteResolveEnv` over SSH.
-                // Single object of injected env KEY -> value; values verbatim.
-                process.stdout.write(JSON.stringify(env));
-                return;
-            }
-            const prefix = bundleToEnvPrefix(resolvedBundleName);
-            for (const [k, v] of Object.entries(env)) {
-                const exportKey = isReservedEnvName(k) ? `${prefix}_${k}` : k;
-                const needsQuotes = /[\s$`"'\\|&;<>(){}[\]!#~]/.test(v);
-                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 });
+            process.stdout.write(JSON.stringify(env));
         }
         catch (err) {
             if (isPromptCancelled(err))

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

@@ -119,5 +119,6 @@ export declare function buildSessionPreviewDigest(events: SessionEvent[], sessio
 export declare function directoriesTouched(session: SessionMeta, events: SessionEvent[], changes: ReturnType<typeof classifyFileChanges>): string[];
 /** Relativize a file path to its parent dir, short enough for one preview line. */
 export declare function relativizeDir(filePath: string, cwd?: string): string | undefined;
+export declare function renderLastResponse(content: string, maxLines?: number, width?: number): string[];
 /** Show an interactive session picker and return the selected session with its action (resume or view). */
 export declare function sessionPicker(config: SessionPickerConfig): Promise<PickedSession | null>;

package/dist/commands/sessions-picker.js

@@ -17,6 +17,8 @@ import { linkPath, linkUrl, relativeToCwd, shortenModel } from '../lib/session/r
 import { linearIssueUrl } from '../lib/session/linear.js';
 import { extractTodoProgress, WORKTREE_RE } from '../lib/session/state.js';
 import { renderMarkdown } from '../lib/markdown.js';
+import { wrapToWidth } from '../lib/wrap.js';
+import { terminalWidth, stringWidth } from '../lib/session/width.js';
 import { itemPicker } from '../lib/picker.js';
 import { createMemoryCache } from '../lib/memory-cache.js';
 import { classifyFileChanges, changeCounts, toolHistogram, detectTestResult } from '../lib/session/digest.js';
@@ -435,8 +437,6 @@ function formatHeader(session, events) {
     if (totalTokens !== undefined) {
         line3.push(chalk.bold.white(formatTokens(totalTokens)) + chalk.gray(' tokens'));
     }
-    if (session.label)
-        line3.push(chalk.white(session.label));
     if (session.filePath)
         line3.push(chalk.gray(linkPath(session.filePath, session.id)));
     else
@@ -452,7 +452,19 @@ function formatHeader(session, events) {
         const label = session.prNumber ? `PR#${session.prNumber}` : 'PR';
         line4.push(chalk.blue(linkUrl(session.prUrl, label)));
     }
+    // Lead with the session's human title: `session.label` — an agent-generated
+    // name / `/rename`, else the `--name` launch handle. NOT `session.topic`: the
+    // topic is the derived first-prompt, already shown on the `Prompt:` line, so
+    // using it here too would print the same text twice. Unlabelled sessions keep
+    // that `Prompt:` line as their topic indicator and simply lead with the agent
+    // line. Wrapped to the pane (the header sits at column 0, full terminal width);
+    // nothing renders when there is no label.
+    const title = (session.label || '').trim();
+    const titleLines = title
+        ? wrapToWidth(title, terminalWidth()).map(l => chalk.bold.white(l))
+        : [];
     return [
+        ...titleLines,
         line1.join(DOT),
         line2.join(DOT),
         line3.join(DOT),
@@ -821,7 +833,9 @@ function formatCompactPreview(digest, session) {
     }
     if (lastAssistant) {
         const maxLines = todosRendered.length > 0 || compact ? LAST_RESPONSE_MAX_LINES_WITH_TODOS : LAST_RESPONSE_MAX_LINES;
-        const rendered = renderLastResponse(lastAssistant, maxLines);
+        // Content sits at column 4 (outer body indent + the '  ' prefix below), so
+        // wrap it to the pane minus that indent.
+        const rendered = renderLastResponse(lastAssistant, maxLines, terminalWidth() - 4);
         if (rendered.length > 0) {
             lines.push('');
             lines.push(chalk.cyan('Last response:'));
@@ -999,7 +1013,7 @@ export function relativizeDir(filePath, cwd) {
         dir = parts.slice(-3).join('/');
     return dir || undefined;
 }
-function renderLastResponse(content, maxLines = LAST_RESPONSE_MAX_LINES) {
+export function renderLastResponse(content, maxLines = LAST_RESPONSE_MAX_LINES, width = terminalWidth()) {
     const cleaned = stripTags(content).trim();
     if (!cleaned)
         return [];
@@ -1010,7 +1024,15 @@ function renderLastResponse(content, maxLines = LAST_RESPONSE_MAX_LINES) {
     catch {
         rendered = cleaned;
     }
-    const all = rendered.replace(/\s+$/, '').split('\n');
+    // `marked-terminal` runs with `reflowText` off, so a paragraph with no hard
+    // breaks renders as one long line that overflows the pane. Wrap any line whose
+    // VISIBLE width exceeds the budget; leave lines that already fit untouched so
+    // rendered-markdown indentation (lists, code blocks) is preserved. The text is
+    // ANSI-coloured, so width is measured with `stringWidth`, never `String.length`.
+    const all = rendered
+        .replace(/\s+$/, '')
+        .split('\n')
+        .flatMap(line => (stringWidth(line) <= width ? [line] : wrapToWidth(line, width)));
     // Drop leading/trailing empty lines
     while (all.length && !all[0].trim())
         all.shift();

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

@@ -0,0 +1,25 @@
+import type { Command } from 'commander';
+import type { SessionMeta } from '../lib/session/types.js';
+import { type PublishOptions } from '../lib/share/publish.js';
+interface ShareOptions {
+    public?: boolean;
+    slug?: string;
+    label?: string;
+    expire?: string;
+    reasoning: string;
+    force?: boolean;
+    cover?: boolean;
+}
+/** `session-<shortId>` — stable per session, so re-sharing updates the same URL. */
+export declare function defaultSessionSlug(session: SessionMeta): string;
+/**
+ * Map the command's flags onto {@link PublishOptions}.
+ *
+ * Extracted so the defaults are testable directly. `unlisted` in particular is the
+ * security-relevant one — it inverts the parent command's public-by-default
+ * behavior, and a test that re-implements this mapping would still pass with it
+ * flipped.
+ */
+export declare function buildSharePublishOptions(session: SessionMeta, options: Pick<ShareOptions, 'public' | 'slug' | 'label' | 'expire' | 'force' | 'cover'>): PublishOptions;
+export declare function registerSessionsShareCommand(sessionsCmd: Command): void;
+export {};

package/dist/commands/sessions-share.js

@@ -0,0 +1,166 @@
+/**
+ * `agents sessions share <id>` — publish one session transcript as a link.
+ *
+ * Composes three pieces that already existed but were never wired together:
+ * `renderSessionMarkdownDocument()` (redacted transcript),
+ * `renderSessionHtmlDocument()` (self-contained branded page), and
+ * `publishFile()` (the R2-backed share Worker). Before this, sharing a session
+ * meant three commands and a detour through the external artifacts-cli.
+ *
+ * Unlisted by default, unlike `agents artifacts share`. A transcript carries file
+ * paths, command output, error text, and whatever a tool printed — strictly more
+ * than a plan does — so it does not belong in the public `/<user>` gallery unless
+ * the operator asks for it with `--public`. The URL itself stays world-readable:
+ * unlisted is a capability URL, not a secret.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import chalk from 'chalk';
+import { setHelpSections } from '../lib/help.js';
+import { knownSecretValuesFromEnv } from '../lib/redact.js';
+import { discoverSessions } from '../lib/session/discover.js';
+import { renderSessionHtmlDocument } from '../lib/session/share-html.js';
+import { publishFile, redactEmails } from '../lib/share/publish.js';
+import { renderSessionMarkdownDocument } from './sessions-render.js';
+import { selectSessions } from './sessions-export.js';
+import { parseAgentFilter } from './sessions.js';
+function parseReasoning(value) {
+    if (value === 'omit' || value === 'fold' || value === 'include')
+        return value;
+    throw new Error(`Unknown reasoning mode "${value}". Expected omit, fold, or include.`);
+}
+/** `session-<shortId>` — stable per session, so re-sharing updates the same URL. */
+export function defaultSessionSlug(session) {
+    return `session-${session.shortId || session.id}`;
+}
+/**
+ * Map the command's flags onto {@link PublishOptions}.
+ *
+ * Extracted so the defaults are testable directly. `unlisted` in particular is the
+ * security-relevant one — it inverts the parent command's public-by-default
+ * behavior, and a test that re-implements this mapping would still pass with it
+ * flipped.
+ */
+export function buildSharePublishOptions(session, options) {
+    return {
+        slug: options.slug ?? defaultSessionSlug(session),
+        unlisted: options.public !== true,
+        expire: options.expire,
+        force: options.force === true,
+        cover: options.cover !== false,
+        label: options.label,
+        meta: { kind: 'session' },
+    };
+}
+export function registerSessionsShareCommand(sessionsCmd) {
+    const cmd = sessionsCmd
+        .command('share <session>')
+        .description('Publish one session as a redacted, self-contained web page and print the link.')
+        .option('--public', 'List the page in your public share gallery (default: unlisted capability URL)')
+        .option('--slug <slug>', 'URL slug under your namespace (default: session-<shortId>)')
+        .option('--label <text>', 'Display title in the gallery and `agents artifacts share list`')
+        .option('--expire <spec>', 'Auto-expire window: 30d, 12h, a date, or never (default: 30d)')
+        .option('--reasoning <mode>', 'Reasoning visibility: omit, fold, or include', 'omit')
+        .option('--force', 'Publish despite the sensitive-content scan flagging the transcript')
+        .option('--no-cover', 'Skip generating the Open Graph preview image');
+    setHelpSections(cmd, {
+        examples: `# Share a session — prints an unlisted, redacted link
+agents sessions share a1b2c3d4
+
+# Put it in your public gallery at share.agents-cli.sh/<you>
+agents sessions share a1b2c3d4 --public --label "How the retry bug got fixed"
+
+# Keep the model's reasoning in collapsible sections
+agents sessions share a1b2c3d4 --reasoning fold
+
+# A link that does not decay
+agents sessions share a1b2c3d4 --expire never`,
+        notes: `Requires a share endpoint: 'agents artifacts share status' shows it, 'agents artifacts setup'
+provisions one, 'agents artifacts share join <baseUrl>' uses an existing one.
+
+Unlisted by default — the URL is world-readable but the page stays out of your public
+gallery and out of 'agents artifacts share list'. Pass --public to list it.
+
+Secrets are redacted and the same pre-publish scan as 'agents artifacts share' runs on the
+page, so a transcript carrying emails or credential-shaped strings is refused
+unless you pass --force. --no-redact (the sessions-level flag) disables redaction
+and is a bad idea for anything you publish.
+
+Re-running with the same session updates the same URL and keeps the prior version
+as a revision ('agents artifacts share revisions <slug>').
+
+Manage published sessions with 'agents artifacts share list' and
+'agents artifacts share delete <slug>'.`,
+    });
+    cmd.action(async (selector, options, command) => {
+        const globals = command.optsWithGlobals();
+        const reasoning = parseReasoning(options.reasoning);
+        const limit = Math.max(1, Number.parseInt(globals.limit || '100', 10) || 100);
+        const agent = parseAgentFilter(globals.agent).agent;
+        const sessions = selectSessions(await discoverSessions({
+            all: globals.all !== false,
+            since: globals.since,
+            limit,
+            agent: agent ?? undefined,
+        }), [selector]);
+        if (sessions.length === 0) {
+            process.stderr.write(chalk.yellow(`No session matched "${selector}".\n`));
+            process.exitCode = 1;
+            return;
+        }
+        // One link per share: several sessions in one page would give the reader no
+        // way to reference just the one that matters, and the slug could only name one.
+        if (sessions.length > 1) {
+            process.stderr.write(chalk.yellow(`"${selector}" matched ${sessions.length} sessions. Share one at a time — pass a full or unique session id.\n`));
+            process.exitCode = 1;
+            return;
+        }
+        const session = sessions[0];
+        const redact = globals.redact !== false;
+        const markdown = renderSessionMarkdownDocument(session, {
+            redact,
+            reasoning,
+            knownSecrets: redact ? knownSecretValuesFromEnv() : undefined,
+        });
+        // Emails on top of what the renderer masks. Almost every real transcript
+        // carries a few — git author addresses, `gh api user`, a pasted log — and
+        // publishToEndpoint refuses a body containing any (RUSH-2428). Masking them
+        // means the published page genuinely does not carry them; the alternative,
+        // telling people to pass --force, would train everyone to bypass the gate
+        // that also catches real credentials.
+        //
+        // Applied to the RENDERED PAGE, not the Markdown, so the text that is masked
+        // is exactly the text `scanShareContent` will scan. Markdown escaping stands
+        // between the two: `foo\@example.com` hides from the pattern in the Markdown
+        // and reappears as a live address once marked drops the backslash.
+        const page = renderSessionHtmlDocument(session, markdown, { redacted: redact });
+        const html = redact ? redactEmails(page) : page;
+        // A real file on disk is what publishFile() takes, and the OG capturer opens
+        // it in a browser. 0600 + a per-run directory keeps the intermediate off a
+        // world-readable /tmp path while it exists.
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'agents-session-share-'));
+        const file = path.join(dir, `${defaultSessionSlug(session)}.html`);
+        try {
+            fs.writeFileSync(file, html, { mode: 0o600 });
+            const result = await publishFile(file, buildSharePublishOptions(session, options));
+            if (globals.json) {
+                process.stdout.write(JSON.stringify({
+                    session: session.id,
+                    agent: session.agent,
+                    redacted: redact,
+                    ...result,
+                }, null, 2) + '\n');
+                return;
+            }
+            process.stdout.write(`${result.url}\n`);
+            const bits = [result.unlisted ? 'unlisted' : 'public', redact ? 'redacted' : chalk.red('NOT redacted')];
+            if (result.expiresAt)
+                bits.push(`expires ${result.expiresAt.slice(0, 10)}`);
+            process.stderr.write(chalk.dim(`${bits.join(' · ')}\n`));
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+}

package/dist/commands/sessions.js

@@ -70,6 +70,7 @@ import { registerAttachCommand } from './attach.js';
 import { registerSessionsInjectCommand } from './sessions-inject.js';
 import { registerSessionsExportCommand } from './sessions-export.js';
 import { registerSessionsRenderCommand } from './sessions-render.js';
+import { registerSessionsShareCommand } from './sessions-share.js';
 import { registerSessionsImportCommand } from './sessions-import.js';
 import { registerSessionsMigrateCommand, registerSessionsMigrationsCommand } from './sessions-migrate.js';
 import { registerSessionsBackfillCommand } from './sessions-backfill.js';
@@ -5173,6 +5174,7 @@ export function registerSessionsCommands(program) {
     registerSessionsInjectCommand(sessionsCmd);
     registerSessionsExportCommand(sessionsCmd);
     registerSessionsRenderCommand(sessionsCmd);
+    registerSessionsShareCommand(sessionsCmd);
     registerSessionsImportCommand(sessionsCmd);
     registerSessionsMigrateCommand(sessionsCmd);
     registerSessionsMigrationsCommand(sessionsCmd);

package/dist/commands/setup-browser.js

@@ -14,7 +14,7 @@ import { DEFAULT_BROWSER_PROFILE_NAME, createProfile, findFreeProfilePort, getCo
 import { DEFAULT_VIEWPORT } from '../lib/browser/devices.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { defaultBrowserChoice } from './setup-preferences.js';
-const INSTALL_HINT = 'Install one of: Google Chrome, Brave, Microsoft Edge, Chromium, or Comet, then re-run `agents setup browser`.\n' +
+const INSTALL_HINT = 'Install one of: Google Chrome, Brave, Microsoft Edge, Chromium, Comet, or Arc, then re-run `agents setup browser`.\n' +
     '(Safari and Firefox are not supported — agents browser drives over the Chrome DevTools Protocol.)';
 /**
  * Interactive browser setup. Returns true if a usable default profile exists

package/dist/commands/setup-preferences.js

@@ -115,10 +115,10 @@ export async function maybePickBrowserProfile() {
         viewport: { width: DEFAULT_VIEWPORT.width, height: DEFAULT_VIEWPORT.height },
     };
     await createProfile(profile);
-    // The same key `agents browser profiles set-default` writes (device-local).
+    // The same key `agents browser use` writes (device-local).
     setConfigValue('browser.profile', profile.name);
     console.log(chalk.green(`Browser: '${chosen.browserType}'`) +
-        chalk.dim(` — profile "${profile.name}" is this machine's default (agents browser profiles set-default to change).`));
+        chalk.dim(` — profile "${profile.name}" is this machine's default (agents browser use to change).`));
     return true;
 }
 /**