@phnx-labs/agents-cli 1.20.78 → 1.20.82

package/dist/commands/secrets.js

@@ -15,7 +15,7 @@ import * as path from 'path';
 import { SSH_TARGET_RE, assertValidSshTarget, sshExec } from '../lib/ssh-exec.js';
 import { quoteWin32ExecArg, composeWin32CommandLine } from '../lib/platform/index.js';
 import { ensureDaemonStarted, isDaemonRunning } from '../lib/daemon.js';
-import { parseHostsOption, remoteResolveEnv, remoteSecretsRaw, remoteSecretsStream, resolveHostSshTarget, } from '../lib/secrets/remote.js';
+import { parseHostsOption, remoteResolveEnv, remoteSecretsRaw, remoteSecretsStream, resolveHostSshTarget, verifyRemoteKeychainPush, keychainWriteFailureMessage, } from '../lib/secrets/remote.js';
 import { remoteShellFor, buildWindowsStdinImportCommand } from '../lib/hosts/remote-cmd.js';
 import { resolveRemoteOsSync } from '../lib/hosts/remote-os.js';
 import { bundleBackend, bundleExists, bundleItemStore, bundlePolicy, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, isHeadlessSecretsContext, readBundle, readBundleIfDecryptable, renameBundle, rotateBundleSecret, sanitizeProcessEnv, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, writeBundleWithItems, } from '../lib/secrets/bundles.js';
@@ -29,6 +29,7 @@ import { getCliVersionFresh } from '../lib/version.js';
 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 { frequentlyPromptedBundles } from '../lib/secrets/unlock-hints.js';
 import { registerCommandGroups, setHelpSections } from '../lib/help.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
@@ -468,7 +469,7 @@ export function renderPolicyCol(b, held) {
     if (bundlePolicy(b) === 'always')
         return chalk.yellow('always · prompt');
     const exp = held?.get(b.name);
-    return exp ? chalk.green(`daily · held ${compactRemaining(exp)}`) : chalk.gray('daily');
+    return exp ? chalk.green(`hold · held ${compactRemaining(exp)}`) : chalk.gray('hold');
 }
 /** Human-readable hold window for `secrets status`. Sub-hour values render in
  * minutes (so a near-floor `holdMs` never shows a confusing "0 hours"), whole
@@ -669,7 +670,7 @@ function countExpiringSoon(meta) {
  * guard can't drift between them.
  */
 function resolveImportBundle(name, backendOpt, synced = false) {
-    const requestedBackend = synced ? 'vault' : parseBackendOpt(backendOpt);
+    const requestedBackend = synced ? 'vault' : resolveBackendOpt(backendOpt);
     if (bundleExists(name)) {
         const bundle = readBundle(name);
         if (requestedBackend !== 'keychain' && bundle.backend !== requestedBackend) {
@@ -735,7 +736,7 @@ export function registerSecretsCommands(program) {
       agents secrets view prod
 
       # Stop a noisy automation bundle from prompting every run: ask once a week
-      agents secrets policy prod daily
+      agents secrets policy prod hold
 
       # Eval the bundle into your current shell
       eval "$(agents secrets export prod --plaintext)"
@@ -753,17 +754,21 @@ export function registerSecretsCommands(program) {
 
       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':
-        daily (default)   ask once, then hold it silently in the local agent up
-                          to ~7 days, until sleep / logout or 'lock' (a bare
-                          screen-lock does NOT drop it). Name is historical.
+        hold (default)    ask once, then serve it silently from the local agent
+                          for the hold window ('secrets.agent.holdMs', 7d by
+                          default), until sleep / logout or 'lock' (a bare
+                          screen-lock does NOT drop it). Accepts the older names
+                          'daily' and 'session'.
         always            ask for Touch ID every time — never auto-held.
-      The default is 'daily' (one Touch ID per ~7 days); change it globally with
+        never             no biometry ACL at all — reads are silent forever, even
+                          if the agent is down. Automation credentials only.
+      The default is 'hold' (one Touch ID per hold window); change it globally with
       'secrets.policy' in agents.yaml, or per bundle with 'agents secrets policy
       <bundle> always'. 'agents secrets unlock <bundle>' holds any bundle after one
       prompt regardless of policy. Nothing on disk.
 
       See also:
-        agents secrets policy <bundle> daily           ask once a week, not every run
+        agents secrets policy <bundle> hold            ask once per hold window (7d by default), not every run
         agents secrets unlock <bundle>                 hold a bundle after one Touch ID
         agents secrets lock                            wipe held bundles (re-prompt next read)
         agents secrets status                          show held bundles + when they lock
@@ -789,6 +794,8 @@ export function registerSecretsCommands(program) {
         .description('List configured secrets bundles (use --host/--hosts to list bundles on other machines over SSH)')
         .option('--host <target>', 'List bundles on a remote host over SSH (enrolled `agents hosts` name, ssh-config alias, or user@host)')
         .option('--hosts <list>', 'Comma-separated hosts to list in one shot, e.g. yosemite-s0,yosemite-s1')
+        .option('--device <target>', 'Alias for --host')
+        .option('--devices <list>', 'Alias for --hosts')
         .option('--json', 'Emit machine-readable JSON (bundle metadata only — never secret values) instead of the table')
         .action(async (opts) => {
         const targets = parseHostsOption(opts);
@@ -856,6 +863,8 @@ export function registerSecretsCommands(program) {
         .option('--json', 'Emit machine-readable JSON (values masked unless --reveal) instead of the human view')
         .option('--host <target>', 'Show a bundle on a remote host over SSH (enrolled `agents hosts` name, ssh-config alias, or user@host)')
         .option('--hosts <list>', 'Comma-separated hosts to show in one shot, e.g. yosemite-s0,yosemite-s1')
+        .option('--device <target>', 'Alias for --host')
+        .option('--devices <list>', 'Alias for --hosts')
         .action(async (name, opts) => {
         try {
             const targets = parseHostsOption(opts);
@@ -913,8 +922,8 @@ export function registerSecretsCommands(program) {
                     }
                     const exposed = revealed.size + entries.filter((e) => e.kind === 'literal').length;
                     if (exposed > 0) {
-                        emit('secrets.get', {
-                            module: 'secrets',
+                        emitSecretAudit({
+                            event: 'secrets.get',
                             bundle: bundle.name,
                             operation: 'view --reveal --json',
                             source: 'reveal',
@@ -972,8 +981,8 @@ export function registerSecretsCommands(program) {
                 console.log(chalk.red.bold('policy: never — NO biometry ACL; reads are silent (no Touch ID, no user-presence check). Automation-only.'));
             }
             else {
-                console.log(bundlePolicy(bundle) === 'daily'
-                    ? chalk.gray('policy: daily (ask once, then held ~7 days until sleep / logout — screen-lock does not drop it)')
+                console.log(bundlePolicy(bundle) === 'hold'
+                    ? chalk.gray('policy: hold (ask once, then held for the hold window — 7d by default — until sleep / logout; screen-lock does not drop it)')
                     : chalk.gray('policy: always (asks for Touch ID every time — never auto-held)'));
             }
             if (bundle.created_at)
@@ -1021,8 +1030,8 @@ export function registerSecretsCommands(program) {
                 const literalCount = entries.filter((e) => e.kind === 'literal').length;
                 const exposedCount = revealedValues.size + literalCount;
                 if (exposedCount > 0) {
-                    emit('secrets.get', {
-                        module: 'secrets',
+                    emitSecretAudit({
+                        event: 'secrets.get',
                         bundle: bundle.name,
                         operation: 'view --reveal',
                         source: 'reveal',
@@ -1079,7 +1088,7 @@ export function registerSecretsCommands(program) {
                 const value = getKeychainToken(item);
                 // Raw item reads bypass readAndResolveBundleEnv, so audit here too.
                 // `item` is the keychain service name, never the value.
-                emit('secrets.get', { module: 'secrets', item, source: 'raw-item', status: 'success' });
+                emitSecretAudit({ event: 'secrets.get', item, source: 'raw-item', status: 'success' });
                 process.stdout.write(value.endsWith('\n') ? value : `${value}\n`);
             }
             catch {
@@ -1153,10 +1162,10 @@ export function registerSecretsCommands(program) {
         .description('Create an empty bundle')
         .option('--description <text>', 'Free-form description')
         .option('--allow-exec', 'Allow exec: refs in this bundle (off by default)')
-        .option('--policy <policy>', 'prompt policy: daily (default, ask once a week), always (ask every time), or never (silent, NO biometry ACL — needs --i-understand)')
+        .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())
         .option('--i-understand', 'Confirm creating a "never"-policy bundle (no biometry ACL) without an interactive prompt')
-        .option('--backend <backend>', 'storage backend: keychain (default) or file (passphrase-encrypted)', 'keychain')
+        .option('--backend <backend>', 'storage backend: keychain or file (defaults to agents.yaml secrets.backend)')
         .option('--synced', 'Store this bundle in the age-encrypted synced secrets file for user-managed cross-machine file sync')
         .option('--force', 'Overwrite an existing bundle')
         .action(async (name, opts) => {
@@ -1167,7 +1176,7 @@ export function registerSecretsCommands(program) {
             // inherits the configured default (`daily`) instead of being pinned.
             const policyOpt = opts.policy ?? opts.tier;
             const policy = policyOpt ? parsePolicyOpt(policyOpt) : undefined;
-            const backend = opts.synced ? 'vault' : parseBackendOpt(opts.backend);
+            const backend = opts.synced ? 'vault' : resolveBackendOpt(opts.backend);
             if (bundleExists(resolvedName) && !opts.force) {
                 console.error(chalk.red(`Bundle '${resolvedName}' already exists. Use --force to overwrite.`));
                 process.exit(1);
@@ -1188,8 +1197,8 @@ export function registerSecretsCommands(program) {
                 vars: {},
             };
             writeBundle(bundle);
-            const policyTag = bundlePolicy(bundle) === 'daily'
-                ? 'policy: daily'
+            const policyTag = bundlePolicy(bundle) === 'hold'
+                ? 'policy: hold'
                 : bundlePolicy(bundle) === 'always'
                     ? 'policy: always ask'
                     : 'policy: never (NO biometry ACL)';
@@ -1572,7 +1581,7 @@ Examples:
         .addOption(new Option('--from-1password', 'deprecated alias for --from 1password:<vault>').hideHelp())
         .addOption(new Option('--vault <name>', 'deprecated: name the vault in --from 1password:<vault>').hideHelp())
         .option('--all-plaintext', 'Store every imported value as a literal in the bundle metadata (skip keychain item creation)')
-        .option('--backend <backend>', 'When creating the bundle: keychain (default) or file (passphrase-encrypted)', 'keychain')
+        .option('--backend <backend>', 'When creating the bundle: keychain or file (defaults to agents.yaml secrets.backend)')
         .option('--synced', 'When creating the bundle, store it in the age-encrypted synced secrets file')
         .option('--force', 'Overwrite an existing key in the bundle')
         .option('--purge', 'With --from icloud: delete the iCloud copies after a successful import (iCloud propagates the deletion to your other devices)')
@@ -1623,7 +1632,7 @@ Examples:
             if (opts.from1password) {
                 console.log(chalk.yellow('--from-1password is deprecated; use --from 1password:<vault>.'));
             }
-            const requestedBackend = opts.synced ? 'vault' : parseBackendOpt(opts.backend);
+            const requestedBackend = opts.synced ? 'vault' : resolveBackendOpt(opts.backend);
             if (source.kind === 'icloud') {
                 await importFromICloud(bundleName, {
                     force: opts.force,
@@ -1674,12 +1683,18 @@ Examples:
         .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('--host <target...>', 'Push the bundle over SSH to this target (host alias or user@host); repeatable for multiple machines')
+        .option('--device <target...>', 'Alias for --host; repeatable')
         .option('--remote-backend <backend>', 'Backend for the bundle on the remote (with --host): keychain (default) or file (passphrase-encrypted, headless-readable). file forwards AGENTS_SECRETS_PASSPHRASE over stdin.', 'keychain')
         .option('--force', 'Overwrite existing keys/items on the target (used with --to-1password and --host)')
         .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 AGENTS_SECRETS_PASSPHRASE; symmetric counterpart of import --from-file)')
         .action(async (bundleName, opts) => {
         try {
+            // `--device` is an alias for `--host` (fleet vocabulary parity with
+            // `agents activity`/`run --device`); fold it into the host list up front so
+            // every downstream branch sees one resolved target list.
+            if (opts.device?.length)
+                opts.host = [...(opts.host ?? []), ...opts.device];
             const { readAndResolveBundleEnv, bundleToEnvPrefix, isReservedEnvName } = await import('../lib/secrets/bundles.js');
             const resolvedBundleName = bundleName ?? (await pickBundleName('export'));
             if (opts.toFile) {
@@ -1770,6 +1785,29 @@ Examples:
                         console.error(chalk.red(`${host}: remote import failed (exit ${res.code})${msg ? `: ${msg}` : ''}`));
                         continue;
                     }
+                    // A keychain-backed push to a macOS remote over headless SSH can land
+                    // the bundle metadata but no READABLE value items: the remote login
+                    // keychain is locked in the non-interactive SSH context, so Security
+                    // accepts the write but the biometry-ACL'd item is unreadable, and the
+                    // remote `import` still exits 0. Read the bundle back the same way a
+                    // release will (drops the plaintext, keeps only key presence; the
+                    // remote's headless `agentOnly` guard fails fast, so no Touch ID) and
+                    // FAIL LOUDLY if the keys didn't materialize — rather than leave a
+                    // metadata-only bundle that breaks later with "stored item not found".
+                    // The file backend is headless-readable by construction, so skip it.
+                    if (remoteBackend === 'keychain') {
+                        const verdict = verifyRemoteKeychainPush(host, resolvedBundleName, Object.keys(env), { osLookupName: host });
+                        if (!verdict.ok) {
+                            failures++;
+                            if (verdict.kind === 'locked-keychain') {
+                                console.error(chalk.red(keychainWriteFailureMessage(host, resolvedBundleName, verdict.reason)));
+                            }
+                            else {
+                                console.error(chalk.red(`${host}: pushed '${resolvedBundleName}' but could not verify it on the remote: ${verdict.reason}`));
+                            }
+                            continue;
+                        }
+                    }
                     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`}`));
                 }
@@ -2152,13 +2190,29 @@ Examples:
                     loaded++;
                     // Persist a durable session snapshot so the unlock survives a daemon
                     // restart / upgrade (and sleep too, with --durable). session-store.ts.
+                    const durable = opts.durable ?? secretsAgentDurable();
                     saveSession(name, {
                         bundle,
                         env,
                         expiresAt: Date.now() + ttlMs,
-                        sleepPersist: opts.durable ?? secretsAgentDurable(),
+                        sleepPersist: durable,
                         harness,
                     });
+                    // Audit the GRANT itself — the broker + durable session now serve this
+                    // bundle prompt-free for the whole TTL, to every reader in `harness`
+                    // scope. The pre-read above emits `secrets.get`; this records the
+                    // longer-lived unlock a `secrets.get` does not capture. Key NAMES only.
+                    emitSecretAudit({
+                        event: 'secrets.unlocked',
+                        bundle: name,
+                        operation: 'unlock',
+                        source: durable ? 'broker+durable' : 'broker',
+                        status: 'success',
+                        keyCount: Object.keys(env).length,
+                        keys: Object.keys(env).sort(),
+                        agent: harness,
+                        ttlMs,
+                    });
                     console.log(`${chalk.green('unlocked')} ${chalk.cyan(name)} ${chalk.gray(`(${Object.keys(env).length} keys, ${humanRemaining(Date.now() + ttlMs)})`)}`);
                 }
                 else {
@@ -2278,7 +2332,7 @@ Examples:
     cmd
         .command('policy <bundle> [policy]')
         .alias('tier')
-        .description("Show or set a bundle's prompt policy: daily (default, ask once a week), always (ask every time), or never (silent, NO biometry ACL).")
+        .description("Show or set a bundle's 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). 'daily'/'session' are accepted aliases for 'hold'.")
         .option('--i-understand', 'Confirm switching to the "never" policy (no biometry ACL) without an interactive prompt')
         .action(async (bundleName, policyArg, opts) => {
         try {
@@ -2295,12 +2349,12 @@ Examples:
                 return;
             }
             bundle.policy = next;
-            // writeBundle evicts any broker-held copy, so tightening daily ->
+            // writeBundle evicts any broker-held copy, so tightening hold ->
             // always/never takes effect NOW: the next read re-prompts (`always`)
             // or reads its no-ACL item directly (`never`).
             writeBundle(bundle);
             console.log(chalk.green(`${bundle.name} policy set to ${next}.`));
-            if (next === 'daily') {
+            if (next === 'hold') {
                 console.log(chalk.gray('Held by the secrets-agent for ~7 days after one unlock (auto-cache is on by default; disable with `secrets.agent.auto: false` in agents.yaml).'));
             }
             else if (next === 'always') {
@@ -2375,11 +2429,11 @@ export function parsePolicyOpt(raw) {
     const v = (raw ?? 'always').toLowerCase();
     if (v === 'always' || v === 'biometry')
         return 'always';
-    if (v === 'daily' || v === 'session')
-        return 'daily';
+    if (v === 'hold' || v === 'daily' || v === 'session')
+        return 'hold';
     if (v === 'never' || v === 'none')
         return 'never';
-    throw new Error(`Invalid policy '${raw}'. Use 'always', 'daily', or 'never'.`);
+    throw new Error(`Invalid policy '${raw}'. Use 'always', 'hold', or 'never'.`);
 }
 /**
  * Gate a create/switch to the `never` prompt-policy behind an explicit,
@@ -2414,13 +2468,27 @@ async function confirmNeverPolicyInteractive(bundleName) {
     return confirm({ message: `Store '${bundleName}' WITHOUT biometry protection?`, default: false });
 }
 /** Validate a --backend value, exiting with a clear message on a bad one. */
-function parseBackendOpt(raw) {
-    const v = (raw ?? 'keychain').toLowerCase();
+export function secretsDefaultBackend() {
+    const raw = readMeta().secrets?.backend;
+    if (raw === undefined)
+        return 'keychain';
+    if (raw === 'keychain' || raw === 'file' || raw === 'vault')
+        return raw;
+    console.error(chalk.red(`Invalid secrets.backend '${raw}'. Use 'keychain', 'file', or 'vault'.`));
+    process.exit(1);
+}
+function parseBackendOpt(raw, defaultBackend = 'keychain') {
+    const v = (raw ?? defaultBackend).toLowerCase();
+    if (!raw && v === 'vault')
+        return 'vault';
     if (v === 'keychain' || v === 'file')
         return v;
     console.error(chalk.red(`Invalid --backend '${raw}'. Use 'keychain' or 'file'. For cross-machine file sync, pass --synced.`));
     process.exit(1);
 }
+function resolveBackendOpt(raw) {
+    return parseBackendOpt(raw, raw === undefined ? secretsDefaultBackend() : 'keychain');
+}
 /** Human-readable "locks in 3 hours" / "locks in 5 minutes" from an epoch-ms expiry. */
 function humanRemaining(expiresAt) {
     const ms = expiresAt - Date.now();

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

@@ -4,10 +4,13 @@
  * (`injectIntoTerminal`, src/lib/terminal/inject.ts), so a native watchdog
  * (RUSH-1415) can shell out to nudge a stalled agent with "continue".
  *
- * Resolution: find the active session by id, map its `provenance.reply` rail
- * (provenance.ts:47) to an engine `InjectTarget` and inject. Today only tmux rails
- * are externally addressable; `--pane`/`--pty` target a backend directly when the
- * handle is already known (skipping the session lookup).
+ * Resolution: find the active session by id, then resolve its exact split through
+ * the SAME canonical resolver the watchdog uses — `resolveInjectTargetForSession`
+ * (lib/terminal/resolve.ts), precedence tmux > iterm > vscodium > pty. Sharing one
+ * resolver keeps the manual unblock path and the watchdog in agreement on which
+ * sessions are addressable (a prior duplicate resolver read only `provenance.reply`
+ * and could not address a VSCodium/Cursor terminal the watchdog handled fine).
+ * `--pane`/`--pty` target a backend directly when the handle is already known.
  */
 import type { Command } from 'commander';
 /** Attach the `inject` subcommand to an existing `sessions` command. */

package/dist/commands/sessions-inject.js

@@ -4,33 +4,32 @@
  * (`injectIntoTerminal`, src/lib/terminal/inject.ts), so a native watchdog
  * (RUSH-1415) can shell out to nudge a stalled agent with "continue".
  *
- * Resolution: find the active session by id, map its `provenance.reply` rail
- * (provenance.ts:47) to an engine `InjectTarget` and inject. Today only tmux rails
- * are externally addressable; `--pane`/`--pty` target a backend directly when the
- * handle is already known (skipping the session lookup).
+ * Resolution: find the active session by id, then resolve its exact split through
+ * the SAME canonical resolver the watchdog uses — `resolveInjectTargetForSession`
+ * (lib/terminal/resolve.ts), precedence tmux > iterm > vscodium > pty. Sharing one
+ * resolver keeps the manual unblock path and the watchdog in agreement on which
+ * sessions are addressable (a prior duplicate resolver read only `provenance.reply`
+ * and could not address a VSCodium/Cursor terminal the watchdog handled fine).
+ * `--pane`/`--pty` target a backend directly when the handle is already known.
  */
 import chalk from 'chalk';
 import { getActiveSessions } from '../lib/session/active.js';
-import { injectTargetFromReplyRail } from '../lib/session/inject.js';
+import { resolveInjectTargetForSession } from '../lib/terminal/resolve.js';
 import { injectIntoTerminal } from '../lib/terminal/index.js';
 import { setHelpSections } from '../lib/help.js';
-/** Resolve a session id (short or full) to an addressable terminal target. */
+/** Resolve a session id (short or full) to an addressable terminal target, via the
+ * same resolver the watchdog uses so both agree on what is reachable. */
 async function resolveTarget(sessionId) {
     const sessions = await getActiveSessions();
     const match = sessions.find((s) => s.sessionId === sessionId || (s.sessionId != null && s.sessionId.startsWith(sessionId)));
     if (!match)
         return { target: null, reason: `No active session matches "${sessionId}".` };
-    const rail = match.provenance?.reply;
-    if (!rail) {
-        return {
-            target: null,
-            reason: `Session "${sessionId}" has no addressable reply rail (not running under tmux). Relaunch it under a tmux/pty rail to inject.`,
-        };
+    const resolution = resolveInjectTargetForSession(match);
+    if (!resolution.addressable) {
+        // Surface the resolver's precise reason (host/rail), not a generic "not tmux".
+        return { target: null, reason: `Session "${sessionId}": ${resolution.reason}` };
     }
-    const target = injectTargetFromReplyRail(rail);
-    if (!target)
-        return { target: null, reason: `Session "${sessionId}" reply rail is not injectable.` };
-    return { target };
+    return { target: resolution.target };
 }
 async function runInject(sessionId, text, options) {
     // Direct-target shortcuts skip the session lookup — the watchdog often already
@@ -97,8 +96,9 @@ export function registerSessionsInjectCommand(sessionsCmd) {
         notes: `
       - Ink-TUI Enter semantics: by default the text and Enter are two separate
         writes, which is what Claude's Ink TUI needs. --combined fuses them.
-      - Only sessions running under a tmux pane are addressable by id today
-        (provenance.ts reply rails). Use --pane/--pty for direct targeting.
+      - A session is addressable by id when it resolves to a precise split —
+        tmux, iTerm, a VSCodium/Cursor/VS Code integrated terminal, or a pty
+        (resolveInjectTargetForSession). Use --pane/--pty for direct targeting.
       - Built on the Terminal Engine (src/lib/terminal): --host runs the tmux /
         AppleScript spec over the same SSH transport the launch engine uses.
     `,

package/dist/commands/sessions-picker.js

@@ -11,7 +11,7 @@ import chalk from 'chalk';
 import { truncate, humanDuration } from '../lib/format.js';
 import { parseSession, sanitizeForTerminal } from '../lib/session/parse.js';
 import { cleanSessionPrompt, extractSessionTopic } from '../lib/session/prompt.js';
-import { linkPath, linkUrl, relativeToCwd } from '../lib/session/render.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';
 import { renderMarkdown } from '../lib/markdown.js';
@@ -137,7 +137,7 @@ function displayAgent(agent) {
 }
 const DOT = chalk.gray(' · ');
 function formatHeader(session, events) {
-    const model = extractModel(events);
+    const model = extractModel(events) || session.model;
     const { startedAgo, duration } = extractTiming(events);
     const totalMessages = session.messageCount ?? countMessages(events);
     const totalTokens = session.tokenCount;
@@ -147,7 +147,7 @@ function formatHeader(session, events) {
     if (session.shortId)
         line1.push(chalk.dim(session.shortId));
     if (model)
-        line1.push(chalk.bold.white(model));
+        line1.push(chalk.bold.white(shortenModel(model)));
     if (session.account)
         line1.push(chalk.gray(session.account));
     // Line 2: cwd · project · branch · started X ago · lasted Y
@@ -285,6 +285,8 @@ function formatCompactPreview(events, session) {
     let planFile = '';
     /** Latest checklist from the transcript (Claude TodoWrite / Codex update_plan). */
     let latestTodos;
+    let subAgentCount = 0;
+    const toolTags = new Set();
     for (const event of events) {
         if (event.type === 'message') {
             if (event.role === 'user' && !firstUser && event.content) {
@@ -298,6 +300,11 @@ function formatCompactPreview(events, session) {
         }
         else if (event.type === 'tool_use' && !event._local) {
             const tool = event.tool || '';
+            const command = event.command || '';
+            for (const tag of classifySessionTool(tool, command))
+                toolTags.add(tag);
+            if (isSubAgentTool(tool, command))
+                subAgentCount++;
             const p = event.path || event.args?.file_path || event.args?.path || '';
             if (['Read', 'read_file', 'view_file', 'cat_file', 'get_file'].includes(tool) && p) {
                 filesRead.add(p);
@@ -369,6 +376,13 @@ function formatCompactPreview(events, session) {
     if (activity.length) {
         lines.push(chalk.cyan('Changes:  ') + activity.join(chalk.gray(' · ')));
     }
+    const metadata = [
+        ...toolTags,
+        subAgentCount ? `${subAgentCount} sub-agent${subAgentCount === 1 ? '' : 's'}` : '',
+    ].filter(Boolean);
+    if (metadata.length) {
+        lines.push(chalk.cyan('Meta:     ') + chalk.gray(metadata.join(' · ')));
+    }
     // Tool mix (top 4) — what kind of work this was.
     const hist = toolHistogram(toolCounts, 4);
     if (hist.length) {
@@ -403,6 +417,21 @@ function formatCompactPreview(events, session) {
     }
     return lines.map(l => '  ' + l).join('\n');
 }
+function classifySessionTool(tool, command) {
+    const toolName = tool.toLowerCase();
+    const commandUses = (surface) => (new RegExp(`\\b(?:agents|ag)\\b[^\\n;&|]*\\b${surface}\\b`).test(command.toLowerCase()));
+    const tags = [];
+    if (/browser|webfetch|websearch/.test(toolName) || commandUses('browser'))
+        tags.push('browser');
+    if (/computer/.test(toolName) || commandUses('computer'))
+        tags.push('computer');
+    return tags;
+}
+function isSubAgentTool(tool, command) {
+    if (/^(Agent|Task)$/i.test(tool))
+        return true;
+    return /\b(?:agents|ag)\b[^\n;&|]*\b(?:run|cloud\s+run|teams\s+(?:add|start))\b/.test(command);
+}
 /**
  * Unique directories the session touched, compact and human-readable.
  * Prefer `session.dirsTouched` when the parser teammate has populated it;

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

@@ -1,2 +1,18 @@
 import type { Command } from 'commander';
+import { type Packing } from '../lib/terminal/index.js';
+interface ResumeOptions {
+    agent?: string;
+    all?: boolean;
+    teams?: boolean;
+    since?: string;
+    limit?: string;
+    host?: string;
+    iterm?: boolean;
+    ghostty?: boolean;
+    tmux?: boolean;
+    vscodium?: boolean;
+    splits?: boolean;
+}
 export declare function registerSessionsResumeCommand(sessionsCmd: Command): void;
+export declare function resolveResumePacking(options: Pick<ResumeOptions, 'splits'>): Packing;
+export {};

package/dist/commands/sessions-resume.js

@@ -4,9 +4,9 @@
  *
  * Unlike the single-select picker behind bare `agents sessions` (which resumes
  * one session in place), this opens a checkbox picker, then asks where the
- * chosen sessions should resume. By default they pack two-per-tab (session 1 in
- * a new tab, session 2 split beside it, session 3 a new tab, …) in the terminal
- * you're in — iTerm / Ghostty / tmux, locally or on a remote host via --host.
+ * chosen sessions should resume. By default each session opens in its own tab in
+ * the terminal you're in — iTerm / Ghostty / tmux, locally or on a remote host
+ * via --host. `--splits` opts into packing two sessions side by side per tab.
  */
 import * as fs from 'fs';
 import chalk from 'chalk';
@@ -36,25 +36,24 @@ export function registerSessionsResumeCommand(sessionsCmd) {
         .option('--ghostty', 'Force the Ghostty backend')
         .option('--tmux', 'Force the tmux backend')
         .option('--vscodium', 'Force the VSCodium agent-terminal backend (swarm-ext)')
-        .option('--tabs', 'One tab per session (default: pack two panes per tab)');
+        .option('--splits', 'Pack two sessions side by side per tab (default: one tab per session)');
     setHelpSections(cmd, {
         examples: `
-      # Pick several sessions; they pack two-per-tab in your current terminal
+      # Pick several sessions; each opens in its own tab
       agents sessions resume
 
       # Pre-filter the pool before selecting (space in the filter → use [query])
       agents sessions resume "auth middleware"
 
-      # Force a backend / one tab each / a remote host
+      # Force a backend / side-by-side splits / a remote host
       agents sessions resume --ghostty
       agents sessions resume --vscodium
-      agents sessions resume --tabs
+      agents sessions resume --splits
       agents sessions resume --host zion --tmux
     `,
         notes: `
       - space toggles a session, enter confirms; tab toggles the preview pane.
-      - Layout: two-per-tab by default (session 1 → new tab, session 2 → split beside it, …). --tabs disables splitting.
-      - VSCodium defaults to one editor tab per session (matches swarm-ext's native agent-terminal UX); the others default to two-per-tab.
+      - Layout: one tab per session by default. --splits packs session pairs side by side in each tab.
       - Backend: auto-detected from the terminal you're in (iTerm / Ghostty / tmux); override with --iterm/--ghostty/--tmux/--vscodium.
       - --vscodium opens each session as an agent terminal tab in VSCodium via the swarm-ext extension (works with --host too).
       - --host <alias> resumes on a remote machine over the same SSH transport as 'sessions --host' (defaults to tmux).
@@ -153,10 +152,9 @@ async function sessionsResumeAction(query, options) {
             await resumeSessionInPlace(it.session);
         return;
     }
-    // 5b. Fan out through the engine. Split-packing (two-per-tab) suits the
-    // terminal apps; the VSCodium backend defaults to one editor tab per session,
-    // matching swarm-ext's native agent-terminal UX. --tabs forces tabs anywhere.
-    const packing = options.tabs || backend === 'vscodium-agent' ? 'tabs' : 'two-per-tab';
+    // 5b. Fan out through the engine. Full-width tabs are the default for batch
+    // recovery; callers can explicitly opt into pairs of side-by-side panes.
+    const packing = resolveResumePacking(options);
     const where = options.host ? `${backend} on ${options.host}` : backend;
     console.log(chalk.gray(`Opening ${items.length} session${items.length === 1 ? '' : 's'} in ${where} (${packing})…`));
     const results = await openSurfaces(items.map((it) => ({ cwd: it.cwd, command: it.command })), { backend, host: options.host, packing });
@@ -174,6 +172,9 @@ async function sessionsResumeAction(query, options) {
     });
     console.log(chalk.gray(`\nOpened ${opened}/${items.length} in ${where}.`));
 }
+export function resolveResumePacking(options) {
+    return options.splits ? 'two-per-tab' : 'tabs';
+}
 /**
  * Decide which backend to launch into. Returns a concrete backend, `'inplace'`
  * (resume in the current process — no GUI/tmux available), or `'cancel'` (the