@phnx-labs/agents-cli 1.22.8 → 1.22.10

package/dist/commands/secrets.js

@@ -18,10 +18,10 @@ 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, 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, 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, getKeychainTokens, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from '../lib/secrets/index.js';
+import { getKeychainToken, hasKeychainToken, secretsKeychainItem, setKeychainToken, maybeAutoRekey, } from '../lib/secrets/index.js';
 import { assertOpAvailable, createPasswordItem, deleteItemByTitle, extractSecrets, itemExistsByTitle, listItems, listVaults, } from '../lib/onepassword.js';
 import { GLOBAL_HARNESS } from '../lib/secrets/scope.js';
 import { secretsHoldMs, secretsAgentDurable, agentLoad, agentLock, agentPing, agentStatus, ensureAgentRunning, runAgentLoadFromStdin, runSecretsAgent, uninstallSecretsAgentService, } from '../lib/secrets/agent.js';
@@ -1251,15 +1251,15 @@ export function registerSecretsCommands(program) {
                 }
                 const revealed = new Map();
                 if (reveal) {
-                    const items = entries
-                        .filter((e) => e.kind === 'keychain')
-                        .map((e) => secretsKeychainItem(bundle.name, e.detail));
-                    try {
-                        for (const [item, value] of getKeychainTokens(items))
-                            revealed.set(item, value);
-                    }
-                    catch {
-                        /* cancelled / batch failure — fall through to masked (null) values */
+                    const { env } = readAndResolveBundleEnv(bundle.name, {
+                        caller: 'view --reveal --json',
+                        keyMode: 'storage',
+                        agentOnly: true,
+                    });
+                    for (const entry of entries) {
+                        if (entry.kind === 'keychain' && env[entry.key] !== undefined) {
+                            revealed.set(secretsKeychainItem(bundle.name, entry.detail), env[entry.key]);
+                        }
                     }
                     const exposed = revealed.size + entries.filter((e) => e.kind === 'literal').length;
                     if (exposed > 0) {
@@ -1369,23 +1369,20 @@ export function registerSecretsCommands(program) {
                 console.error(chalk.red('--reveal in a non-TTY requires --plaintext.'));
                 process.exit(1);
             }
-            // Batch every backend read into one helper call where supported, so
-            // keychain --reveal pops Touch ID once and synced/file bundles use
-            // their declared storage.
+            // Resolve through the broker / durable-session path. A locked keychain
+            // bundle errors with the explicit unlock hint; viewing never raises a
+            // Touch ID sheet itself.
             const revealedValues = new Map();
             if (reveal) {
-                const items = entries
-                    .filter((e) => e.kind === 'keychain')
-                    .map((e) => secretsKeychainItem(bundle.name, e.detail));
-                try {
-                    const fetched = bundle.backend
-                        ? new Map(items.map((item) => [item, bundleItemStore(bundle.backend).get(item)]))
-                        : getKeychainTokens(items);
-                    for (const [item, value] of fetched)
-                        revealedValues.set(item, value);
-                }
-                catch {
-                    // Fall through to masked output on cancellation / batch failure.
+                const { env } = readAndResolveBundleEnv(bundle.name, {
+                    caller: 'view --reveal',
+                    keyMode: 'storage',
+                    agentOnly: true,
+                });
+                for (const entry of entries) {
+                    if (entry.kind === 'keychain' && env[entry.key] !== undefined) {
+                        revealedValues.set(secretsKeychainItem(bundle.name, entry.detail), env[entry.key]);
+                    }
                 }
                 // Revealing plaintext bypasses readAndResolveBundleEnv (the usual
                 // audit chokepoint), so emit here — a `--reveal` exposes real values
@@ -1475,10 +1472,9 @@ export function registerSecretsCommands(program) {
                 process.exit(1);
             }
             // `secrets get` is the scriptable automation primitive ($(agents secrets
-            // get bundle KEY)); when embedded in a headless routine/CI script — or run
-            // beneath any agent, which inherits AGENTS_RUNTIME — it must not pop an
-            // unwatched Touch ID prompt. Typed in a plain shell it still prompts.
-            const { env } = readAndResolveBundleEnv(item, { caller: 'secrets get', keys: [key], keyMode: 'storage', agentOnly: isHeadlessSecretsContext() });
+            // 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);
@@ -2083,7 +2079,7 @@ Examples:
                     throw new Error('--to-file needs AGENTS_SECRETS_PASSPHRASE set to encrypt the bundle. ' +
                         'Set it for this command, then supply the same value when importing.');
                 }
-                const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: 'export --to-file', keyMode: 'storage', agentOnly: isHeadlessSecretsContext() });
+                const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: 'export --to-file', keyMode: 'storage', agentOnly: true });
                 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}`));
@@ -2111,7 +2107,7 @@ Examples:
                             'bundle at rest on the remote. Set it for this command, then unlock it the same way per run.');
                     }
                 }
-                const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: `ssh export`, keyMode: 'storage', agentOnly: isHeadlessSecretsContext() });
+                const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: `ssh export`, keyMode: 'storage', agentOnly: true });
                 const dotenv = bundleEnvToDotenv(env);
                 const keyCount = Object.keys(env).length;
                 // Drive the remote's own `agents secrets import --from -` so the values
@@ -2200,7 +2196,7 @@ Examples:
             if (opts.to1password) {
                 assertOpAvailable();
                 const vault = await resolveVault(opts.vault);
-                const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: `1Password vault ${vault}`, keyMode: 'storage', agentOnly: isHeadlessSecretsContext() });
+                const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: `1Password vault ${vault}`, keyMode: 'storage', agentOnly: true });
                 let created = 0;
                 let overwritten = 0;
                 let skipped = 0;
@@ -2240,14 +2236,12 @@ Examples:
                 process.exit(1);
             }
             // `agents secrets export --plaintext` is what release/CI scripts eval.
-            // When it runs detached (both stdio non-TTY) or beneath ANY agent — which
-            // inherits AGENTS_RUNTIME — resolve broker-only so it can never pop a Touch
-            // ID sheet on the interactive user's screen. An `eval "$(...)"` typed in a
-            // plain shell carries no AGENTS_RUNTIME, so it is not headless and still prompts.
+            // Every caller is broker-only, including a plain shell, so export never
+            // raises Touch ID on the interactive user's screen.
             const { env } = readAndResolveBundleEnv(resolvedBundleName, {
                 caller: `export to shell`,
                 keyMode: 'process',
-                agentOnly: isHeadlessSecretsContext(),
+                agentOnly: true,
             });
             if (opts.format === 'json') {
                 // Machine-readable form consumed by `remoteResolveEnv` over SSH.
@@ -2309,7 +2303,7 @@ Examples:
                     caller: `command ${cmd}`,
                     keys: keysSubset,
                     allowExpired: execOpts.allowExpired,
-                    agentOnly: isHeadlessSecretsContext(),
+                    agentOnly: true,
                 }).env;
             }
             const { spawn } = await import('child_process');
@@ -2575,6 +2569,11 @@ Examples:
                     duration: humanRemaining(Date.now() + ttlMs),
                     keyMode: 'storage',
                 });
+                // Migrations are authorized only by this explicit unlock. The bundle
+                // metadata was included in the successful authenticated batch, so the
+                // ACL heal can rewrite that already-read value without another read.
+                maybeAutoRekey();
+                healKeychainBundleMetadataAclOnce(new Map([[bundle.name, JSON.stringify(bundle)]]));
                 if (await agentLoad(name, bundle, env, ttlMs, harness)) {
                     loaded++;
                     // Persist a durable session snapshot so the unlock survives a daemon

package/dist/commands/sessions-picker.js

@@ -11,7 +11,7 @@ import chalk from 'chalk';
 import { truncate, humanDuration } from '../lib/format.js';
 import { parseSession, sanitizeForTerminal, SNAPSHOT_TODO_TOOLS } from '../lib/session/parse.js';
 import { safeTeamText } from '../lib/session/team-filter.js';
-import { cleanSessionPrompt, extractSessionTopic } from '../lib/session/prompt.js';
+import { cleanSessionPrompt, extractSessionTopic, isSyntheticUserMessage } from '../lib/session/prompt.js';
 import { linkPath, linkUrl, relativeToCwd, shortenModel } from '../lib/session/render.js';
 import { linearIssueUrl } from '../lib/session/linear.js';
 import { extractTodoProgress, WORKTREE_RE } from '../lib/session/state.js';
@@ -383,7 +383,7 @@ function formatCompactPreview(events, session) {
     const knownToolUsage = session.usedBrowser !== undefined;
     for (const event of events) {
         if (event.type === 'message') {
-            if (event.role === 'user' && !firstUser && event.content) {
+            if (event.role === 'user' && !event._synthetic && !firstUser && event.content) {
                 if (!SYSTEM_MESSAGE_PATTERNS.some(p => p.test(event.content))) {
                     firstUser = event.content;
                 }
@@ -443,7 +443,7 @@ function formatCompactPreview(events, session) {
             lines.push(chalk.cyan('Prompt: ') + chalk.white(truncate(first.trim(), termWidth - 12)));
         }
     }
-    else if (session.topic) {
+    else if (session.topic && !isSyntheticUserMessage(session.topic)) {
         lines.push(chalk.cyan('Prompt: ') + chalk.white(truncate(session.topic.trim(), termWidth - 12)));
     }
     // Compact checklist: ✓done/total · current step (RUSH-2045).

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

@@ -0,0 +1,12 @@
+import type { Command } from 'commander';
+import type { SessionMeta } from '../lib/session/types.js';
+export declare const MARKDOWN_RENDER_AGENTS: readonly ["claude", "codex", "gemini", "antigravity", "opencode", "grok", "rush", "hermes", "kimi", "droid", "cursor"];
+export type ReasoningMode = 'omit' | 'fold' | 'include';
+/** Build one shareable Markdown document from the canonical preview and event model. */
+export declare function renderSessionMarkdownDocument(session: SessionMeta, options?: {
+    redact?: boolean;
+    reasoning?: ReasoningMode;
+    knownSecrets?: readonly string[];
+    maxToolOutputChars?: number;
+}): string;
+export declare function registerSessionsRenderCommand(sessionsCmd: Command): void;

package/dist/commands/sessions-render.js

@@ -0,0 +1,124 @@
+/** Render selected normalized session transcripts as redacted Markdown documents. */
+import * as fs from 'fs';
+import { stripVTControlCharacters } from 'node:util';
+import chalk from 'chalk';
+import { setHelpSections } from '../lib/help.js';
+import { knownSecretValuesFromEnv, redactSecrets } from '../lib/redact.js';
+import { discoverSessions } from '../lib/session/discover.js';
+import { parseSession } from '../lib/session/parse.js';
+import { extractSessionTopic, isSyntheticUserMessage } from '../lib/session/prompt.js';
+import { renderConversationMarkdown } from '../lib/session/render.js';
+import { buildPreview } from './sessions-picker.js';
+import { parseAgentFilter } from './sessions.js';
+import { selectSessions } from './sessions-export.js';
+export const MARKDOWN_RENDER_AGENTS = [
+    'claude',
+    'codex',
+    'gemini',
+    'antigravity',
+    'opencode',
+    'grok',
+    'rush',
+    'hermes',
+    'kimi',
+    'droid',
+    'cursor',
+];
+function parseReasoning(value) {
+    if (value === 'omit' || value === 'fold' || value === 'include')
+        return value;
+    throw new Error(`Unknown reasoning mode "${value}". Expected omit, fold, or include.`);
+}
+function quotePreview(preview) {
+    return preview.split('\n').map((line) => `> ${line}`).join('\n');
+}
+/** Build one shareable Markdown document from the canonical preview and event model. */
+export function renderSessionMarkdownDocument(session, options = {}) {
+    if (!MARKDOWN_RENDER_AGENTS.includes(session.agent)) {
+        throw new Error(`Cannot render ${session.agent} session ${session.shortId || session.id}: Markdown rendering supports ${MARKDOWN_RENDER_AGENTS.join(', ')}.`);
+    }
+    // Preserve normalized tool output here so the Markdown renderer owns the
+    // visible cap and can report exactly how much it omitted.
+    const events = parseSession(session.filePath, session.agent, { maxToolOutputChars: Infinity });
+    if (events.length === 0) {
+        throw new Error(`Cannot render ${session.agent} session ${session.shortId || session.id}: transcript produced no normalized events.`);
+    }
+    const shouldRedact = options.redact !== false;
+    const sanitize = (text) => shouldRedact ? redactSecrets(text, options.knownSecrets) : text;
+    const preview = sanitize(stripVTControlCharacters(buildPreview(session)));
+    const shareEvents = events.filter((event) => !(event.type === 'message' && event._synthetic));
+    const firstPrompt = shareEvents.find((event) => event.type === 'message' && event.role === 'user')?.content;
+    const title = sanitize(session.label || (firstPrompt ? extractSessionTopic(firstPrompt) : undefined) ||
+        (session.topic && !isSyntheticUserMessage(session.topic) ? session.topic : undefined) ||
+        `${session.agent} session ${session.shortId || session.id}`);
+    const conversation = renderConversationMarkdown(shareEvents, {
+        redact: shouldRedact,
+        knownSecrets: options.knownSecrets,
+        reasoning: options.reasoning ?? 'omit',
+        maxToolOutputChars: options.maxToolOutputChars,
+    });
+    return `# ${title}\n\n## Session preview\n\n${quotePreview(preview)}\n\n## Conversation\n\n${conversation}\n`;
+}
+export function registerSessionsRenderCommand(sessionsCmd) {
+    const cmd = sessionsCmd
+        .command('render <selectors...>')
+        .description('Render one or more sessions as readable, redacted Markdown for review or sharing.')
+        .option('--format <format>', 'Output format (md or markdown)', 'md')
+        .option('-o, --output <path>', 'Write the rendered document to a file instead of stdout')
+        .option('--reasoning <mode>', 'Reasoning visibility: omit, fold, or include', 'omit');
+    setHelpSections(cmd, {
+        examples: `# Render one redacted session for a confidential gist
+agents sessions render a1b2c3d4 -o session.md
+
+# Combine several sessions into one Markdown document
+agents sessions render a1b2c3d4 d4c3b2a1 -o delivery-sessions.md
+
+# Keep reasoning locally in collapsible sections and opt out of redaction
+agents sessions render a1b2c3d4 --reasoning fold --no-redact`,
+        notes: `Markdown is redacted by default, including credential-shaped values and local home paths.
+The preview at the top is the same preview shown by 'agents sessions'. Tool output is truncated
+with an explicit note. Use --no-redact only for local output that will not be shared.`,
+    });
+    cmd.action(async (selectors, options, command) => {
+        const globals = command.optsWithGlobals();
+        if (!['md', 'markdown'].includes(options.format.toLowerCase())) {
+            throw new Error(`Unknown format "${options.format}". Expected md or markdown.`);
+        }
+        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,
+        }), selectors);
+        if (sessions.length === 0) {
+            process.stderr.write(chalk.yellow('No sessions matched the selection.\n'));
+            process.exitCode = 1;
+            return;
+        }
+        const knownSecrets = globals.redact === false ? undefined : knownSecretValuesFromEnv();
+        const rendered = sessions.map((session) => ({
+            id: session.id,
+            agent: session.agent,
+            markdown: renderSessionMarkdownDocument(session, {
+                redact: globals.redact !== false,
+                reasoning,
+                knownSecrets,
+            }),
+        }));
+        const markdown = rendered.map((item) => item.markdown.trimEnd()).join('\n\n---\n\n') + '\n';
+        if (options.output)
+            fs.writeFileSync(options.output, markdown, { mode: 0o600 });
+        if (globals.json) {
+            process.stdout.write(JSON.stringify({ redacted: globals.redact !== false, reasoning, sessions: rendered }, null, 2) + '\n');
+        }
+        else if (!options.output) {
+            process.stdout.write(markdown);
+        }
+        else {
+            process.stderr.write(chalk.green(`Rendered ${rendered.length} session${rendered.length === 1 ? '' : 's'} to ${options.output}\n`));
+        }
+    });
+}

package/dist/commands/sessions.js

@@ -56,6 +56,7 @@ import { registerDetachCommand } from './detach.js';
 import { registerAttachCommand } from './attach.js';
 import { registerSessionsInjectCommand } from './sessions-inject.js';
 import { registerSessionsExportCommand } from './sessions-export.js';
+import { registerSessionsRenderCommand } from './sessions-render.js';
 import { registerSessionsImportCommand } from './sessions-import.js';
 import { registerSessionsMigrateCommand, registerSessionsMigrationsCommand } from './sessions-migrate.js';
 import { registerSessionsBackfillCommand } from './sessions-backfill.js';
@@ -3584,7 +3585,7 @@ export function registerSessionsCommands(program) {
         .option('--query <clause>', 'Search text; repeat with --include tools to require distinct matching calls', collectQueryClause, [])
         .option('--resolve <selector>', 'Resolve one full ID, unique prefix, or keyword query to safe session metadata (requires --json; searches the fleet unless --local)')
         .addOption(new Option('--resolve-safe-v1 <selector>').hideHelp())
-        .description('Find, browse, and read agent conversation transcripts across Claude, Codex, Gemini, and OpenCode.')
+        .description('Find, browse, and read agent conversation transcripts. Live roster: `agents sessions --active` (alias: `agents roster`).')
         .option('-a, --agent <agent>', 'Filter by agent type and version (e.g., claude, codex@0.116.0)')
         .option('--claude', 'Shorthand for --agent claude')
         .option('--codex', 'Shorthand for --agent codex')
@@ -3735,11 +3736,37 @@ export function registerSessionsCommands(program) {
     registerAttachCommand(sessionsCmd);
     registerSessionsInjectCommand(sessionsCmd);
     registerSessionsExportCommand(sessionsCmd);
+    registerSessionsRenderCommand(sessionsCmd);
     registerSessionsImportCommand(sessionsCmd);
     registerSessionsMigrateCommand(sessionsCmd);
     registerSessionsMigrationsCommand(sessionsCmd);
     registerSessionsBackfillCommand(sessionsCmd);
     registerSessionsStatsCommand(sessionsCmd);
+    // Observe-umbrella alias (Phase 3): roster → sessions --active.
+    registerSessionsObserveAliases(program);
+}
+/**
+ * `roster` → sessions --active. Registered with the sessions module so the
+ * lazy loader for `roster` also registers the real `sessions` command for re-parse.
+ */
+function registerSessionsObserveAliases(program) {
+    program
+        .command('roster')
+        .description('Live agent roster (alias of `agents sessions --active`). Who is running right now.')
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .action(async () => {
+        const { expandObserveAlias } = await import('../lib/observe-aliases.js');
+        const rest = process.argv.slice(3);
+        const expanded = expandObserveAlias('roster', rest);
+        if (!expanded) {
+            console.error(chalk.red('Unknown observe alias: roster'));
+            process.exit(1);
+        }
+        if (process.stderr.isTTY)
+            process.stderr.write(chalk.gray(`${expanded.note}\n`));
+        await program.parseAsync(['node', 'agents', ...expanded.argv]);
+    });
 }
 function formatNoSessionsMessage(showAll, project) {
     const projectQuery = project?.trim();

package/dist/commands/ssh.js

@@ -16,8 +16,9 @@ import * as path from 'path';
 import chalk from 'chalk';
 import ora from 'ora';
 import { getCliVersion } from '../lib/version.js';
-import { readAndResolveBundleEnv, isHeadlessSecretsContext } from '../lib/secrets/bundles.js';
+import { readAndResolveBundleEnv } from '../lib/secrets/bundles.js';
 import { machineId } from '../lib/session/sync/config.js';
+import { isDeviceAuto, resolveDeviceAffinity } from '../lib/smart-launch.js';
 import { registerFleetCaptureCommand } from './fleet-capture.js';
 import { registerFleetApplyAlias } from './apply.js';
 import { addIgnored, getDevice, loadDevices, loadIgnored, removeDevice, removeIgnored, setAutoLaunchEnabled, setAutoLaunchPreferred, upsertDevice, writeReachability, } from '../lib/devices/registry.js';
@@ -30,7 +31,7 @@ import { resolveDeviceTarget, splitUserHost } from '../lib/devices/resolve-targe
 import { clearPendingSentinel } from '../lib/devices/pending.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { hostNameFor, renderSshConfig } from '../lib/devices/ssh-config.js';
-import { ASKPASS_BUNDLE_ENV, ASKPASS_KEY_ENV, ASKPASS_AGENT_ONLY_ENV, buildSshInvocation, fleetDialTarget, writeAskpassShim, } from '../lib/devices/connect.js';
+import { ASKPASS_BUNDLE_ENV, ASKPASS_KEY_ENV, buildSshInvocation, fleetDialTarget, writeAskpassShim, } from '../lib/devices/connect.js';
 import { ensureManagedKnownHostsDir, isHostPinned } from '../lib/devices/known-hosts.js';
 import { shouldSyncTerminfo, syncTerminfoToDevice, terminfoHostKey } from '../lib/devices/terminfo.js';
 import { fanOutDevices, fleetHealthSkip, planFleetTargets, remoteFleetTargets, runFleet, skipLabel, upgradeCommand, } from '../lib/devices/fleet.js';
@@ -1413,9 +1414,12 @@ Examples:
   agents ssh win-mini                       # interactive login
   agents ssh win-mini hostname              # run a command (PowerShell on Windows)
   agents ssh yosemite-s0 uptime             # run a command (POSIX)
+  agents ssh auto                           # affinity-pick a device (same engine as 'agents run --device auto')
 
 Devices come from 'agents devices'. Password auth pulls the secret from a
 secrets bundle via an askpass shim — the password never touches argv.
+'auto' picks a remote device by 14-day usage; a pick landing on this machine
+is refused with a clear message instead of self-dialing.
 `)
         .action(async (name, cmd) => {
         // Hidden askpass bridge: ssh execs the shim, which re-invokes us here.
@@ -1423,16 +1427,35 @@ secrets bundle via an askpass shim — the password never touches argv.
             await runAskpass();
             return;
         }
+        // `auto` is the same affinity sentinel `agents run --device auto` resolves
+        // (RUSH-2185) — pick the concrete device up front via the SAME engine
+        // (resolveDeviceAffinity), rather than leaning on matchHost's generic
+        // self-resolution (../lib/hosts/registry.js): `agents ssh` connects OUT to
+        // a remote device, so a pick that lands on THIS machine is refused with a
+        // clear message instead of self-SSHing — which also holds when this
+        // machine was never itself enrolled as a device (matchHost would have
+        // nothing to resolve "self" to, and mis-report the pick as "Unknown
+        // device").
+        let target = name;
+        if (isDeviceAuto(name)) {
+            const plan = resolveDeviceAffinity({});
+            if (!plan.host) {
+                console.error(chalk.red(`'auto' picked this machine — 'agents ssh' connects to a remote device. Pass a device name; see 'agents devices list'.`));
+                process.exit(1);
+            }
+            process.stderr.write(chalk.gray(`[agents] device=auto → ${plan.host}\n`));
+            target = plan.host;
+        }
         // Accept the full fleet target grammar: a registered `name`, a
         // `user@device` (same device, login user overridden — dialed via its
         // Tailscale route, not LAN DNS), or an ad-hoc `user@host`/`host` literal.
         // A bare unregistered alias still errors as "Unknown device".
-        const device = await resolveDeviceTarget(name);
+        const device = await resolveDeviceTarget(target);
         if (!device) {
             // Not a registered device — it may be a leased crabbox box slug. ssh into
             // it directly (crabbox@<tailnet|ip>:2222) before giving up.
-            trySshLeasedBox(name, cmd); // exits the process on a match
-            console.error(chalk.red(`Unknown device '${name}'. See 'agents devices list'.`));
+            trySshLeasedBox(target, cmd); // exits the process on a match
+            console.error(chalk.red(`Unknown device '${target}'. See 'agents devices list'.`));
             process.exit(1);
         }
         // Preflight: a device Tailscale last saw offline would otherwise hang
@@ -1491,9 +1514,8 @@ async function runAskpass() {
     }
     // A read-only stats probe sets ASKPASS_AGENT_ONLY_ENV to force a broker-only
     // resolve even under a TTY — so `agents devices` never pops Touch ID just to
-    // render load/mem for an uncached password-auth device (RUSH-1970). Otherwise
-    // fall back to the headless-context heuristic.
-    const agentOnly = process.env[ASKPASS_AGENT_ONLY_ENV] === '1' || isHeadlessSecretsContext();
+    // render load/mem for an uncached password-auth device (RUSH-1970).
+    const agentOnly = true;
     try {
         const { env } = readAndResolveBundleEnv(bundle, { caller: 'agents ssh', keys: [key], keyMode: 'storage', agentOnly });
         const value = env[key];

package/dist/commands/teams.js

@@ -17,6 +17,7 @@ import { createTeam, ensureTeam, getTeam, loadTeams, removeTeam, teamExists, } f
 import { setHelpSections } from '../lib/help.js';
 import { createWorktree, isGitRepo, hasUncommittedChanges, removeWorktree, } from '../lib/teams/worktree.js';
 import { resolveHost } from '../lib/hosts/registry.js';
+import { isDeviceAuto, resolveDeviceAffinity } from '../lib/smart-launch.js';
 import { sshTargetFor } from '../lib/hosts/types.js';
 import { ensureHostReady } from '../lib/hosts/ready.js';
 import { remoteShellFor } from '../lib/hosts/remote-cmd.js';
@@ -1330,7 +1331,7 @@ export function registerTeamsCommands(program) {
         // `--device`/`--host` are aliases (addHostOption registers both). For `teams
         // add` the passthrough special-cases them as PLACEMENT, not routing, so the
         // local action reads them here. Reject a conflicting pair.
-        const explicitDevice = (() => {
+        let explicitDevice = (() => {
             const h = opts.host;
             const d = opts.device;
             if (h && d && h !== d) {
@@ -1338,6 +1339,16 @@ export function registerTeamsCommands(program) {
             }
             return h ?? d ?? null;
         })();
+        // `auto` is the same affinity sentinel `agents run --device auto` resolves
+        // (RUSH-2185) — pick the concrete device name up front so the local-machine
+        // check right below (and every dieFriction message further down) sees the
+        // real target instead of the literal string "auto".
+        if (explicitDevice && isDeviceAuto(explicitDevice)) {
+            const plan = resolveDeviceAffinity({});
+            const picked = plan.host ?? machineId();
+            process.stderr.write(chalk.gray(`[teams] device=auto → ${picked === machineId() ? 'local' : picked}\n`));
+            explicitDevice = picked;
+        }
         // Distributed teams: --device <name> PINS this teammate to a machine over
         // SSH. Resolve + validate the placement here so a bad target fails at `add`
         // time, not silently at launch. Persisted (hostName/hostTarget/repoPath) so

package/dist/commands/workflows.js

@@ -29,7 +29,7 @@ Structure:
     skills/            optional: knowledge packs scoped to this workflow
     plugins/           optional: plugin bundles scoped to this workflow
 
-Resolution: project (.agents/workflows/) > user (~/.agents/workflows/) > system.
+Resolution: project > user > plugin (plugins/*/workflows/) > extra > system.
 
 Note: agents run defaults to --mode plan (read-only). For workflows that
 write files, post comments, or otherwise mutate state, pass --mode edit or

package/dist/index.js

@@ -310,6 +310,15 @@ Run and dispatch:
   browser                         Automate a browser — navigate, click, screenshot, console, network
   pty                             Drive interactive terminal programs (REPLs, TUIs) via a persistent PTY session
 
+Observe (read the fleet — no store merge; aliases point at the real readers):
+  feed / inbox                    Needs-you inbox (open blocks waiting on you)
+  timeline                        Agent progress stream (= feed --filter updates)
+  roster                          Live agents (= sessions --active)
+  events                          Unified ops + activity event trail
+  audit                           Tamper-evident run-dispatch log (not events)
+  snapshot                        One-process inventory + active sessions poll
+  status                          Sync/drift only (not the live fleet snapshot)
+
 Credentials and profiles:
   profile                         Activate resource profiles across skills, MCP, permissions, and secrets
   profiles                        Bundles of (host CLI, endpoint, model, auth)
@@ -317,8 +326,6 @@ Credentials and profiles:
 
 Diagnostics:
   doctor [agent[@version]]        Diagnose CLI availability, sync status, and resource divergence; --check for the CI drift gate
-  status                          Unified sync status (drift/missing) — not the live fleet snapshot
-  snapshot                        One-process poll: inventory + active sessions (+ optional feed/sync)
   usage [agent]                   Show rate-limit and quota usage per agent
   perf                            Latency rollups (hooks, commands, runs) from the disposable perf warehouse
 

package/dist/lib/crabbox/cli.d.ts

@@ -114,6 +114,41 @@ export declare function crabboxEnv(opts: CrabboxOptions): NodeJS.ProcessEnv;
 export declare function crabboxList(opts?: CrabboxOptions): CrabboxBox[];
 /** Find one box by slug, or null. */
 export declare function crabboxFind(slug: string, opts?: CrabboxOptions): CrabboxBox | null;
+/**
+ * Whether `crabbox status` reports the box SSH-ready (`ready=true`). A box whose
+ * cloud-init bootstrap failed still LISTS as `running` but never becomes ready —
+ * selecting it burns the full SSH wait before hard-failing. `crabbox status`
+ * flips ready=true only once sshd answers, so warm-pool reuse gates on it
+ * (mirrors scripts/sandbox.sh's `box_ready`).
+ */
+export declare function crabboxStatusReady(slug: string, opts?: CrabboxOptions): boolean;
+export interface PoolMatchOptions {
+    /**
+     * Profile label this run would warm a box with (from the repo's
+     * `.crabbox.yaml`; see config.ts). Both sides normalize an unset profile to
+     * DEFAULT_CRABBOX_PROFILE, so profile-less runs match unlabeled boxes.
+     */
+    profile?: string;
+    /**
+     * Network mode of the run (default 'public'). A tailnet-joined box is never
+     * handed to a public run, nor a public box to a tailnet run — reachability and
+     * exposure differ, so the pool is partitioned by it.
+     */
+    netMode?: 'public' | 'tailscale';
+    /** Injectable clock (unix seconds) for the expiry check. */
+    nowSecs?: number;
+}
+/**
+ * Warm boxes in the profile pool this run could reuse: `running`, same profile
+ * label, same network mode, lease unexpired — most-recently-touched first.
+ *
+ * Readiness is NOT required here (deliberately mirrors sandbox.sh's
+ * `running_slugs_for_profile`, which filters on `status` only): the list `state`
+ * label can lag, so the caller gates each candidate on `crabboxStatusReady`
+ * before committing. A not-ready box is skipped, never stopped — a concurrent
+ * run may be mid-boot on it, and crabbox's idle timeout reaps genuine duds.
+ */
+export declare function poolReusableBoxes(boxes: CrabboxBox[], opts?: PoolMatchOptions): CrabboxBox[];
 export interface WarmupOptions extends CrabboxOptions {
     class?: string;
     profile?: string;

package/dist/lib/crabbox/cli.js

@@ -14,6 +14,7 @@
 import { spawn, spawnSync } from 'child_process';
 import { readAndResolveBundleEnv, listBundles, bundleExists } from '../secrets/bundles.js';
 import { readMeta, writeMeta } from '../state.js';
+import { DEFAULT_CRABBOX_PROFILE } from './config.js';
 /** Locate the crabbox binary, or throw an actionable error. */
 export function findCrabbox() {
     const r = spawnSync('crabbox', ['--help'], { encoding: 'utf-8' });
@@ -301,6 +302,51 @@ export function crabboxList(opts = {}) {
 export function crabboxFind(slug, opts = {}) {
     return crabboxList(opts).find((b) => b.slug === slug) ?? null;
 }
+/**
+ * Whether `crabbox status` reports the box SSH-ready (`ready=true`). A box whose
+ * cloud-init bootstrap failed still LISTS as `running` but never becomes ready —
+ * selecting it burns the full SSH wait before hard-failing. `crabbox status`
+ * flips ready=true only once sshd answers, so warm-pool reuse gates on it
+ * (mirrors scripts/sandbox.sh's `box_ready`).
+ */
+export function crabboxStatusReady(slug, opts = {}) {
+    findCrabbox();
+    const r = spawnSync('crabbox', ['status', '--id', slug], {
+        encoding: 'utf-8',
+        env: crabboxEnv(opts),
+        timeout: opts.timeoutMs ?? 15000,
+    });
+    if (r.status !== 0 || !r.stdout)
+        return false;
+    return /(^|\s)ready=true(\s|$)/m.test(r.stdout);
+}
+/**
+ * Warm boxes in the profile pool this run could reuse: `running`, same profile
+ * label, same network mode, lease unexpired — most-recently-touched first.
+ *
+ * Readiness is NOT required here (deliberately mirrors sandbox.sh's
+ * `running_slugs_for_profile`, which filters on `status` only): the list `state`
+ * label can lag, so the caller gates each candidate on `crabboxStatusReady`
+ * before committing. A not-ready box is skipped, never stopped — a concurrent
+ * run may be mid-boot on it, and crabbox's idle timeout reaps genuine duds.
+ */
+export function poolReusableBoxes(boxes, opts = {}) {
+    const profile = opts.profile ?? DEFAULT_CRABBOX_PROFILE;
+    const netMode = opts.netMode ?? 'public';
+    const nowSecs = opts.nowSecs ?? Math.floor(Date.now() / 1000);
+    return boxes
+        .filter((b) => {
+        if (b.status !== 'running')
+            return false;
+        if ((b.profile ?? DEFAULT_CRABBOX_PROFILE) !== profile)
+            return false;
+        const boxNet = b.tailscaleIPv4 || b.tailscaleFQDN ? 'tailscale' : 'public';
+        if (boxNet !== netMode)
+            return false;
+        return b.expiresAt === null || b.expiresAt > nowSecs;
+    })
+        .sort((a, b) => (b.lastTouchedAt ?? 0) - (a.lastTouchedAt ?? 0));
+}
 /**
  * Lease a box and block until it is ready. Returns the leased box.
  *