@phnx-labs/agents-cli 1.22.29 → 1.22.30

package/dist/commands/exec.js

@@ -445,17 +445,18 @@ async function handleTerminalHandoff(agentSpec, options, prompt) {
     // the whole Kimi/DeepSeek/Qwen/GLM path — for `--terminal` runs only.
     const rawTarget = parseRunAccountPickerRequest(agentSpec).normalizedAgentSpec.split('@')[0];
     const knownAgent = resolveAgentName(rawTarget);
-    if (knownAgent && isAgentHardDeprecated(knownAgent)) {
+    const [{ profileExists }, { resolveWorkflowRef }] = await Promise.all([
+        import('../lib/profiles.js'),
+        import('../lib/workflows.js'),
+    ]);
+    const hasProfile = profileExists(rawTarget);
+    if (knownAgent && !hasProfile && isAgentHardDeprecated(knownAgent)) {
         console.error(chalk.red(hardDeprecationError(knownAgent)));
         process.exit(1);
     }
     if (!knownAgent) {
-        const [{ profileExists }, { resolveWorkflowRef }] = await Promise.all([
-            import('../lib/profiles.js'),
-            import('../lib/workflows.js'),
-        ]);
         const probeCwd = options.cwd ?? process.cwd();
-        if (!profileExists(rawTarget) && !resolveWorkflowRef(rawTarget, probeCwd)) {
+        if (!hasProfile && !resolveWorkflowRef(rawTarget, probeCwd)) {
             console.error(chalk.red(`Unknown agent, profile, or workflow: ${rawTarget}. See \`agents list\` for the installed harnesses.`));
             process.exit(1);
         }
@@ -545,6 +546,7 @@ export function registerRunCommand(program) {
         .option('--fallback <agents>', 'Comma-separated agents to try on rate-limit failure. Each entry accepts an optional @version pin (e.g., codex@0.116.0,antigravity). The primary runs first; if it exits with a rate-limit error, the next agent picks up via /continue handoff.')
         .option('-b, --balanced', 'Shortcut for --strategy balanced. Ignored when @version is pinned.')
         .option('--strategy <strategy>', 'Version/account selection strategy: pinned | available | balanced. Defaults to run.<agent>.strategy, then balanced (spreads load across healthy accounts and skips any that are rate-limited). (Legacy `rotate` accepted as alias for `balanced`.)')
+        .option('--account <label>', 'Run a healthy installed version currently signed into this named account (never falls back to another identity)')
         .option('--acp', 'Route through the Agent Client Protocol instead of direct exec. Supported for claude via @zed-industries/claude-code-acp adapter. Unified event stream; emits ndjson when --json.')
         .option('-y, --yes', 'Skip the interactive budget-confirm prompt (require_confirm_over). Never skips a hard budget block.', false)
         .option('--loop', 'Re-inject the prompt/entrypoint each iteration until a stop condition (issue #332). Guards (--max-iterations, --budget, --until) are enforced outside the agent. Writes a checkpoint after every iteration for --resume-checkpoint.')
@@ -812,8 +814,10 @@ export function registerRunCommand(program) {
             process.exit(1);
         }
         // Hard-deprecated harnesses cannot be run — point the user at the successor.
-        const runBaseAgentId = resolveAgentName(normalizedAgentSpec.split('@')[0]);
-        if (runBaseAgentId && isAgentHardDeprecated(runBaseAgentId)) {
+        const runBaseAgentName = normalizedAgentSpec.split('@')[0];
+        const runBaseAgentId = resolveAgentName(runBaseAgentName);
+        const { profileExists: runProfileExists } = await import('../lib/profiles.js');
+        if (runBaseAgentId && !runProfileExists(runBaseAgentName) && isAgentHardDeprecated(runBaseAgentId)) {
             console.error(chalk.red(hardDeprecationError(runBaseAgentId)));
             process.exit(1);
         }
@@ -1567,6 +1571,7 @@ export function registerRunCommand(program) {
                         agent: runAgent,
                         version: resumeId ? undefined : runVersion,
                         strategy: resumeId ? undefined : runStrategy,
+                        account: resumeId ? undefined : options.account,
                         fallback: options.fallback,
                         prompt,
                         mode: forwardedMode,
@@ -1654,6 +1659,7 @@ export function registerRunCommand(program) {
                     agent: runAgent,
                     version: resumeId ? undefined : runVersion,
                     strategy: resumeId ? undefined : runStrategy,
+                    account: resumeId ? undefined : options.account,
                     fallback: options.fallback,
                     prompt,
                     mode: forwardedMode,
@@ -1840,11 +1846,11 @@ export function registerRunCommand(program) {
         // degenerates to a no-op ("I'll wait for the completion notification").
         let workflowHasSubagents = false;
         const cwd = options.cwd ?? process.cwd();
+        if (accountPickerRequested && profileExists(rawAgent)) {
+            console.error(chalk.red(`Account selection is not available for custom harness '${rawAgent}'. Run its concrete host agent with @ instead.`));
+            process.exit(1);
+        }
         if (accountPickerRequested && !isValidAgent(rawAgent)) {
-            if (profileExists(rawAgent)) {
-                console.error(chalk.red(`Account selection is not available for custom harness '${rawAgent}'. Run its concrete host agent with @ instead.`));
-                process.exit(1);
-            }
             if (resolveWorkflowRef(rawAgent, cwd)) {
                 console.error(chalk.red(`Account selection is not available for workflow '${rawAgent}'. Run a concrete agent with @ instead.`));
                 process.exit(1);
@@ -1886,14 +1892,11 @@ export function registerRunCommand(program) {
                 process.stderr.write(chalk.yellow(`[agents] --session-id ignored: auto picked ${agent} (only claude accepts a forced session id)\n`));
             }
         }
-        else if (isValidAgent(rawAgent)) {
-            agent = rawAgent;
-        }
         else if (profileExists(rawAgent)) {
-            // Not a known agent id, but a profile by this name exists. Profiles
-            // bind (host agent, version, env overrides, keychain-backed auth)
-            // so Chinese models (Kimi, DeepSeek, Qwen, GLM) can run inside
-            // Claude Code without a local proxy.
+            // A profile by this exact name exists. Profiles bind (host agent,
+            // version, env overrides, keychain-backed auth) so Chinese models
+            // (Kimi, DeepSeek, Qwen, GLM) can run inside Claude Code without a
+            // local proxy, including when the profile name matches a native id.
             try {
                 const resolved = resolveProfileForRun(rawAgent, options.model);
                 agent = resolved.agent;
@@ -1925,6 +1928,9 @@ export function registerRunCommand(program) {
                 process.exit(1);
             }
         }
+        else if (isValidAgent(rawAgent)) {
+            agent = rawAgent;
+        }
         else if (resolveWorkflowRef(rawAgent, cwd)) {
             // Workflow: explicit directory, project .agents/workflows/<name>, user, system, or extra repo.
             // Resolution follows resource precedence: direct path, then project > user > system > extras.
@@ -2148,6 +2154,23 @@ export function registerRunCommand(program) {
             }
         }
         version = resolveVersionAlias(agent, version);
+        if (options.account) {
+            if (options.cloud || options.provider || options.lease) {
+                console.error(chalk.red('--account selects a local installed identity and cannot be combined with cloud or lease placement.'));
+                process.exit(1);
+            }
+            const { resolveAccountLabel } = await import('../lib/account-labels.js');
+            try {
+                const selected = await resolveAccountLabel(agent, options.account);
+                if (version && version !== selected)
+                    throw new Error(`${agent}@${version} is not a healthy match for account '${options.account}'.`);
+                version ??= selected;
+            }
+            catch (err) {
+                console.error(chalk.red(err.message));
+                process.exit(1);
+            }
+        }
         // --resume: resolve a prior conversation and rewrite the run target to
         // continue it. `version` here is already the alias-resolved candidate-version
         // FILTER (undefined for default/any, concrete for @latest/@oldest/@x.y.z);
@@ -2320,7 +2343,7 @@ export function registerRunCommand(program) {
         // the bare primary still resolves through the strategy — otherwise every
         // `agents run claude --fallback codex` run lands on the pinned default
         // account and account rotation silently stops (the gh-monitor heal bug).
-        if (!accountPickerRequested && (strategy !== 'pinned' || options.balanced || explicitStrategy)) {
+        if (!accountPickerRequested && !options.account && (strategy !== 'pinned' || options.balanced || explicitStrategy)) {
             if (version) {
                 process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} ignored: version ${version} is pinned\n`));
             }
@@ -2434,6 +2457,29 @@ export function registerRunCommand(program) {
                 version = healed;
             }
         }
+        // The harness may simply not be on this machine. The self-heal above only
+        // runs when a managed version resolved, so with nothing installed we used
+        // to fall through and spawn the bare `cliCommand`, which dies as
+        // `exec: cursor-agent: not found` (exit 127) after a misleading
+        // "looks logged out" banner (RUSH-2339). Probe the executable
+        // buildExecCommand will actually spawn and fail loud instead.
+        //
+        // This is an EXISTENCE probe, not "does agents-cli manage a version". A
+        // harness the user installed themselves (Homebrew, a vendor `curl | sh`, a
+        // distro package) has no version home and MUST still launch — the PATH
+        // branch of resolveLaunchBinary is what keeps that working.
+        {
+            const { resolveLaunchBinary } = await import('../lib/exec.js');
+            // `version` already carries the self-heal's resolution above (it assigns
+            // `version = healed` whenever a version resolved at all), so re-deriving
+            // it with resolveVersion here would be dead.
+            if (!resolveLaunchBinary(agent, version)) {
+                const target = version ? `${agent}@${version}` : agent;
+                console.error(chalk.red(`agents: ${target} is not installed on this machine.`));
+                console.error(chalk.yellow(`Install it with: agents add ${target}`));
+                process.exit(1);
+            }
+        }
         const defaultVersion = version ?? resolveVersion(agent, cwd);
         // Re-apply the active rules preset before every launch (issue: preset
         // changes via `setActiveRulesPreset` only took effect after an explicit

package/dist/commands/routines.js

@@ -11,7 +11,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { isDaemonRunning, signalDaemonReload, startDaemon, stopDaemon, readDaemonLog, getDaemonStatus, } from '../lib/daemon.js';
-import { assertSchedulerEnabled } from '../lib/device-config.js';
+import { assertSchedulerEnabled, assertDaemonEnabled, isDaemonEnabled } from '../lib/device-config.js';
 import { resolveAgentName, isAgentHardDeprecated, hardDeprecationError, ROUTINE_AGENT_IDS } from '../lib/agents.js';
 import { humanizeCron, humanizeNextRun, formatRepoLink, REPO_DISPLAY_MAX } from '../lib/routines-format.js';
 import { listJobs as listAllJobs, deleteJob, readJob, validateJob, writeJob, setJobEnabled, listRuns, routineStats, getLatestRun, getRunDir, getJobPath, parseAtTime, hasCompletedOneShotRun, isOneShotLikeSchedule, isOneShotRoutine, isPastOneShotRoutine, jobRunsOnThisDevice, checkJobDeviceEligibility, normalizeTriggerEvent, parseHostStrategy, resolveHostStrategy, HOST_STRATEGIES, computeProjectGroup, computeProjectGroupKind, projectGroupKey, projectGroupTitle, projectGroupOrder, normalizeProjects, } from '../lib/routines.js';
@@ -344,6 +344,7 @@ function parseRoutineTrigger(options) {
 function ensureSchedulerRunning(opts = {}) {
     const log = opts.stderr ? console.error : console.log;
     try {
+        assertDaemonEnabled();
         assertSchedulerEnabled();
     }
     catch (err) {
@@ -1282,11 +1283,18 @@ export function registerRoutinesCommands(program) {
             console.log(`  ${chalk.cyan(job.name)} — missed ${chalk.gray(job.expectedAt.toLocaleString())}, last ran ${chalk.gray(last)}`);
         }
         // Need the daemon alive so spawned jobs are monitored and meta.json is
-        // finalized. Start it if it isn't already running.
+        // finalized. Start it if it isn't already running — unless daemon.enabled
+        // is off, in which case this auto-start is skipped with a stated reason.
         if (!options.dryRun && !isDaemonRunning()) {
-            const started = startDaemon();
-            if (started.pid) {
-                console.log(chalk.gray(`\nStarted scheduler (PID: ${started.pid}) so catchup runs are monitored.`));
+            try {
+                assertDaemonEnabled();
+                const started = startDaemon();
+                if (started.pid) {
+                    console.log(chalk.gray(`\nStarted scheduler (PID: ${started.pid}) so catchup runs are monitored.`));
+                }
+            }
+            catch (err) {
+                console.log(chalk.yellow(`\n${err.message}`));
             }
         }
         console.log(chalk.bold(options.dryRun ? '\nRecording misses...' : '\nTriggering catchup runs...'));
@@ -1372,11 +1380,18 @@ export function registerRoutinesCommands(program) {
             return;
         }
         // Fired jobs run detached via executeJobDetached (the same path cron
-        // uses). Keep the daemon alive so each run's meta.json is finalized.
+        // uses). Keep the daemon alive so each run's meta.json is finalized —
+        // unless daemon.enabled is off, in which case this auto-start is
+        // skipped with a stated reason.
         if (!isDaemonRunning()) {
-            const started = startDaemon();
-            if (started.pid) {
-                console.log(chalk.gray(`Started scheduler (PID: ${started.pid}) so webhook runs are monitored.`));
+            if (!isDaemonEnabled()) {
+                console.log(chalk.yellow(`Daemon is disabled (daemon.enabled=false) — run(s) below fire but are not monitored. Re-enable with: agents daemon enable`));
+            }
+            else {
+                const started = startDaemon();
+                if (started.pid) {
+                    console.log(chalk.gray(`Started scheduler (PID: ${started.pid}) so webhook runs are monitored.`));
+                }
             }
         }
         const fired = await fireWebhookJobs(webhook);
@@ -1649,8 +1664,11 @@ export function registerRoutinesCommands(program) {
         .description('Start the background scheduler. Usually unnecessary — it auto-starts when you add your first routine.')
         .action(() => {
         try {
-            // A manual start on a scheduler-disabled device refuses with the same
-            // message the auto-start surfaces give.
+            // A manual start on a disabled device refuses with the same message the
+            // auto-start surfaces give — `agents routines start` is a convenience
+            // wrapper around the daemon, not the deliberate override. Use
+            // `agents daemon start` to bypass daemon.enabled explicitly.
+            assertDaemonEnabled();
             assertSchedulerEnabled();
         }
         catch (err) {

package/dist/commands/secrets.d.ts

@@ -149,6 +149,23 @@ export declare function renderViewStatusLine(b: SecretsBundle, heldExpiresAt: nu
  * and a hard abort at inject time, i.e. after it had already broken something.
  */
 export declare function renderExpiringCol(b: SecretsBundle, now?: number): string;
+/**
+ * Resolve an existing import target bundle (inheriting its backend) or create a
+ * new one with the requested backend. Refuses to silently downgrade a
+ * keychain-backed bundle to `file` — shared by every `import` source so the
+ * guard can't drift between them.
+ *
+ * `force` additionally recreates a bundle whose METADATA RECORD is present but
+ * undecryptable — a file store whose key was lost or rotated out from under it.
+ * That is precisely the state provisioning exists to repair (import is how a box
+ * gets its bundles back), and without this the import dies on `readBundle` and
+ * the only route left is deleting the record by hand on an already-degraded
+ * store. It is gated on `--force` on purpose: recreating unconditionally would
+ * destroy a perfectly healthy bundle for someone who merely forgot to set
+ * `AGENTS_SECRETS_PASSPHRASE`, which is the hazard `readBundleIfDecryptable`
+ * exists to describe. `--force` already means "overwrite what is there".
+ */
+export declare function resolveImportBundle(name: string, backendOpt: string | undefined, synced?: boolean, force?: boolean): SecretsBundle;
 /** Register the `agents secrets` command tree. */
 export declare function registerSecretsCommands(program: Command): void;
 /** Validate a prompt-policy value, throwing a clear message on a bad one (the

package/dist/commands/secrets.js

@@ -804,16 +804,31 @@ export function renderExpiringCol(b, now = Date.now()) {
  * new one with the requested backend. Refuses to silently downgrade a
  * keychain-backed bundle to `file` — shared by every `import` source so the
  * guard can't drift between them.
+ *
+ * `force` additionally recreates a bundle whose METADATA RECORD is present but
+ * undecryptable — a file store whose key was lost or rotated out from under it.
+ * That is precisely the state provisioning exists to repair (import is how a box
+ * gets its bundles back), and without this the import dies on `readBundle` and
+ * the only route left is deleting the record by hand on an already-degraded
+ * store. It is gated on `--force` on purpose: recreating unconditionally would
+ * destroy a perfectly healthy bundle for someone who merely forgot to set
+ * `AGENTS_SECRETS_PASSPHRASE`, which is the hazard `readBundleIfDecryptable`
+ * exists to describe. `--force` already means "overwrite what is there".
  */
-function resolveImportBundle(name, backendOpt, synced = false) {
+export function resolveImportBundle(name, backendOpt, synced = false, force = false) {
     const requestedBackend = synced ? 'vault' : resolveBackendOpt(backendOpt);
     if (bundleExists(name)) {
-        const bundle = readBundle(name);
-        if (requestedBackend !== 'keychain' && bundle.backend !== requestedBackend) {
-            throw new Error(`Bundle '${name}' already exists with a different backend; ` +
-                `delete it first to recreate it as ${requestedBackend === 'vault' ? 'synced' : `${requestedBackend}-backed`}.`);
+        // readBundleIfDecryptable nulls ONLY on BundleUndecryptableError; a locked
+        // keychain or logged-out vault still throws, so a recoverable state can
+        // never be mistaken for a lost key and silently overwritten.
+        const bundle = force ? readBundleIfDecryptable(name) : readBundle(name);
+        if (bundle) {
+            if (requestedBackend !== 'keychain' && bundle.backend !== requestedBackend) {
+                throw new Error(`Bundle '${name}' already exists with a different backend; ` +
+                    `delete it first to recreate it as ${requestedBackend === 'vault' ? 'synced' : `${requestedBackend}-backed`}.`);
+            }
+            return bundle;
         }
-        return bundle;
     }
     return { name, backend: requestedBackend === 'keychain' ? undefined : requestedBackend, vars: {} };
 }
@@ -1984,7 +1999,7 @@ Examples:
                 }
                 const env = importBundleFromFile(opts.fromFile, passphrase);
                 const resolvedBundleName = bundleName ?? (await pickBundleName('import into'));
-                const bundle = resolveImportBundle(resolvedBundleName, opts.backend, opts.synced);
+                const bundle = resolveImportBundle(resolvedBundleName, opts.backend, opts.synced, opts.force);
                 const { added, skipped } = applyEnvToBundle(bundle, env, opts);
                 emitSecretAudit({ event: 'secrets.import', bundle: bundle.name, operation: 'import --from-file', source: 'file', status: 'success', keyCount: added });
                 console.log(chalk.green(`Imported ${added} key(s) from file${skipped ? `, skipped ${skipped} (already set, pass --force)` : ''}.`));
@@ -1998,7 +2013,7 @@ Examples:
                 const resolvedBundleName = bundleName ?? (await pickBundleName('import into'));
                 const target = await resolveHostSshTarget(opts.host);
                 const env = await remoteResolveEnv(target, resolvedBundleName, { osLookupName: opts.host });
-                const bundle = resolveImportBundle(resolvedBundleName, opts.backend, opts.synced);
+                const bundle = resolveImportBundle(resolvedBundleName, opts.backend, opts.synced, opts.force);
                 const { added, skipped } = applyEnvToBundle(bundle, env, opts);
                 emitSecretAudit({ event: 'secrets.import', bundle: bundle.name, operation: 'import --from-ssh', source: 'ssh', host: opts.host, status: 'success', keyCount: added });
                 console.log(chalk.green(`Imported ${added} key(s) from ${opts.host}${skipped ? `, skipped ${skipped} (already set, pass --force)` : ''}.`));
@@ -2026,7 +2041,7 @@ Examples:
             // to downgrade keychain -> file) or creates it with the requested backend
             // so a single `import --backend file` works (what `export --host ...
             // --remote-backend file` drives on the remote).
-            const bundle = resolveImportBundle(resolvedBundleName, opts.backend, opts.synced);
+            const bundle = resolveImportBundle(resolvedBundleName, opts.backend, opts.synced, opts.force);
             if (source.kind === '1password') {
                 assertOpAvailable();
                 const vault = await resolveVault(source.vault);
@@ -2431,16 +2446,16 @@ Examples:
         .command('lease <bundle>')
         .description('Hold only an explicit subset of a bundle until an independent expiry.')
         .requiredOption('--keys <keys>', 'Comma-separated key subset')
-        .requiredOption('--for <duration>', 'Lease duration, for example 30m or 8h')
+        .requiredOption('--ttl <duration>', 'How long to hold it (e.g. 30m, 8h, 3d)')
         .option('--agent <agent>', 'Narrow the lease to one harness; default is global')
         .option('--durable', 'Keep the lease across sleep as well as broker restart')
         .action(async (name, opts) => {
         if (process.platform !== 'darwin') {
             throw new Error('Scoped lease brokering is not available on this platform yet.');
         }
-        const seconds = parseDuration(opts.for);
+        const seconds = parseDuration(opts.ttl);
         if (seconds === null)
-            throw new Error(`Invalid lease duration '${opts.for}'.`);
+            throw new Error(`Invalid lease duration '${opts.ttl}'.`);
         const ttlMs = seconds * 1000;
         const harness = opts.agent || GLOBAL_HARNESS;
         const { bundle, env } = readAndResolveBundleEnv(name, {
@@ -2516,7 +2531,7 @@ Examples:
         .option('--ttl <duration>', 'How long to hold it (e.g. 30m, 8h, 3d). Default 7d.')
         .option('--until <date>', 'Hold until this absolute date or timestamp (for example 2026-08-06T12:00:00Z). Mutually exclusive with --ttl.')
         .option('--durable', 'Keep the unlock across sleep + reboot too (default: survives upgrade/restart but re-locks on sleep). Set secrets.agent.durable in agents.yaml to make this the default.')
-        .option('--for <agent>', 'Narrow the unlock to ONE harness type (for example claude, codex, or kimi). Default: the grant is global — every harness and a plain shell can read it, so one Touch ID covers them all.')
+        .option('--agent <agent>', 'Narrow the unlock to ONE harness type (for example claude, codex, or kimi). Default: the grant is global — every harness and a plain shell can read it, so one Touch ID covers them all.')
         .option('--all', 'Unlock every configured bundle')
         .option('--host <target>', 'Unlock the bundle(s) on this remote machine over SSH instead of locally (file-backed bundles only — the remote\'s passphrase prompt surfaces on your terminal over a -tt session). Single-valued (NOT variadic) so it never swallows the bundle name: `unlock <name> --host <machine>`.')
         .action(async (names, opts) => {
@@ -2602,12 +2617,12 @@ Examples:
         // (single-instance start lock, #414) and best-effort — never blocks unlock.
         ensureDaemonStarted();
         let loaded = 0;
-        // An unlock is a deliberate act, so it grants GLOBALLY unless `--for`
+        // An unlock is a deliberate act, so it grants GLOBALLY unless `--agent`
         // narrows it to one harness. It must NOT inherit the ambient
         // AGENTS_AGENT_NAME: that silently scoped a terminal unlock to whichever
         // agent happened to launch the shell, leaving the grant unreadable to
         // every other reader for its whole TTL.
-        const harness = opts.for || GLOBAL_HARNESS;
+        const harness = opts.agent || GLOBAL_HARNESS;
         for (const name of targets) {
             try {
                 // noAgent: read the real keychain (one Touch ID) rather than the

package/dist/commands/sessions-browser.js

@@ -560,7 +560,7 @@ function helpFor(_f, mode) {
     if (mode === 'search') {
         return 'type to filter · ↑↓ navigate · esc exit search · ⏎ resume';
     }
-    return 's search · r running · f favorites · * star · c teams · t team · a agent · d device · p project · w window · tab preview · y copy-cmd · ⏎ resume · esc quit';
+    return 's search · r running · f favorites · * favorite · c teams · t team · a agent · d device · p project · w window · tab preview · y copy-cmd · ⏎ resume · esc quit';
 }
 /**
  * Launch the interactive session browser. `initial` seeds the filter (e.g.
@@ -589,8 +589,8 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
     // needs it — fetch it once, lazily, the first time running is toggled on.
     let liveCache = null;
     // Re-read every load (it's an mtime-memoized parse of one small file), so the
-    // `*` key's reload picks up the star it just wrote — and so does a favorite
-    // starred by another session on this machine.
+    // `*` key's reload picks up the favorite it just wrote — and so does one
+    // favorited by another session on this machine.
     let favorites = new Set();
     // Generation guard: two quick keypresses can start overlapping loads whose
     // SSH fan-outs settle out of order. dynamicPicker's own gen ref guards which
@@ -700,12 +700,12 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
         },
         onKey: (name, f, active, query) => {
             if (name === '*') {
-                // Only a row with a real session id can be starred: a projected live row
+                // Only a row with a real session id can be favorited: a projected live row
                 // with no id is keyed by pid, which is gone the moment the process is.
                 if (!active || active.id.startsWith(LIVE_ROW_PREFIX))
-                    return 'nothing to star on this row';
+                    return 'nothing to favorite on this row';
                 const on = toggleFavorite(active.id);
-                // reload so the row's star is repainted — labels are memoized per row.
+                // reload so the row's favorite glyph is repainted — labels are memoized per row.
                 return { flash: on ? `★ favorited ${active.shortId}` : `☆ unfavorited ${active.shortId}`, reload: true };
             }
             // Both cases: `hotkeyToken` hands `onKey` the literal character, and this

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

@@ -1,16 +1,16 @@
 /**
- * `agents sessions favorite` — the non-TTY half of the star.
+ * `agents sessions favorite` — the non-TTY half of the favorite hotkey.
  *
- * The `*` hotkey in the interactive browser is how a human stars a session; this
- * is how a script, an agent, or a machine without a TTY does the same thing, and
- * it is what makes the feature testable end to end without driving a terminal UI.
- * Both write the one store in `lib/session/favorites.ts`.
+ * The `*` hotkey in the interactive browser is how a human favorites a session;
+ * this is how a script, an agent, or a machine without a TTY does the same thing,
+ * and it is what makes the feature testable end to end without driving a terminal
+ * UI. Both write the one store in `lib/session/favorites.ts`.
  */
 import type { Command } from 'commander';
 /**
  * Resolve one user-typed id (usually the 8-char short id the listing prints) to
- * a full session id. Ambiguity is an ERROR, not a silent first-match: starring
- * the wrong session is invisible until the user wonders where their star went.
+ * a full session id. Ambiguity is an ERROR, not a silent first-match: favoriting
+ * the wrong session is invisible until the user wonders where their favorite went.
  */
 export declare function resolveFavoriteTarget(idQuery: string): {
     id: string;

package/dist/commands/sessions-favorite.js

@@ -1,10 +1,10 @@
 /**
- * `agents sessions favorite` — the non-TTY half of the star.
+ * `agents sessions favorite` — the non-TTY half of the favorite hotkey.
  *
- * The `*` hotkey in the interactive browser is how a human stars a session; this
- * is how a script, an agent, or a machine without a TTY does the same thing, and
- * it is what makes the feature testable end to end without driving a terminal UI.
- * Both write the one store in `lib/session/favorites.ts`.
+ * The `*` hotkey in the interactive browser is how a human favorites a session;
+ * this is how a script, an agent, or a machine without a TTY does the same thing,
+ * and it is what makes the feature testable end to end without driving a terminal
+ * UI. Both write the one store in `lib/session/favorites.ts`.
  */
 import chalk from 'chalk';
 import { setHelpSections } from '../lib/help.js';
@@ -13,15 +13,15 @@ import { isCompleteSessionId } from '../lib/session/discover.js';
 import { isFavorite, listFavorites, setFavorite } from '../lib/session/favorites.js';
 /**
  * Resolve one user-typed id (usually the 8-char short id the listing prints) to
- * a full session id. Ambiguity is an ERROR, not a silent first-match: starring
- * the wrong session is invisible until the user wonders where their star went.
+ * a full session id. Ambiguity is an ERROR, not a silent first-match: favoriting
+ * the wrong session is invisible until the user wonders where their favorite went.
  */
 export function resolveFavoriteTarget(idQuery) {
     const matches = findSessionsById(idQuery);
     // A COMPLETE id needs no index entry: the id is the key the store is built on,
     // and requiring a transcript row would refuse exactly the newest sessions — a
-    // live one that has not been indexed yet. The browser's `*` stars those from
-    // the live row, so demanding a DB hit here would make the two disagree.
+    // live one that has not been indexed yet. The browser's `*` favorites those
+    // from the live row, so demanding a DB hit here would make the two disagree.
     if (matches.length === 0) {
         return isCompleteSessionId(idQuery.trim())
             ? { id: idQuery.trim() }
@@ -36,30 +36,30 @@ export function resolveFavoriteTarget(idQuery) {
 export function registerSessionsFavoriteCommand(sessionsCmd) {
     const cmd = sessionsCmd
         .command('favorite')
-        .argument('[ids...]', 'Session ids to star (full or short id prefix)')
-        .description('Star sessions so they are easy to find again — list them with --favorites, or `f` in the browser.')
-        .option('--remove', 'Unstar the given sessions instead of starring them')
-        .option('--list', 'List the starred sessions (the default when no ids are given)')
+        .argument('[ids...]', 'Session ids to favorite (full or short id prefix)')
+        .description('Favorite sessions so they are easy to find again — list them with --favorites, or `f` in the browser.')
+        .option('--remove', 'Remove the given sessions from favorites instead of adding them')
+        .option('--list', 'List the favorited sessions (the default when no ids are given)')
         .option('--json', 'Output JSON');
     setHelpSections(cmd, {
         examples: `
-      # Star a session by its short id (the 8 chars the listing prints)
+      # Favorite a session by its short id (the 8 chars the listing prints)
       agents sessions favorite 26c27162
 
-      # See what is starred
+      # See what is favorited
       agents sessions favorite --list
 
-      # Browse only the starred ones
+      # Browse only the favorited ones
       agents sessions --favorites
 
-      # Unstar it again
+      # Remove it from favorites again
       agents sessions favorite 26c27162 --remove
     `,
         notes: `
-      In the interactive browser (\`agents sessions\`), \`*\` stars the highlighted
-      session and \`f\` filters the list down to the starred ones.
+      In the interactive browser (\`agents sessions\`), \`*\` favorites the highlighted
+      session and \`f\` filters the list down to the favorited ones.
 
-      Stars live in ~/.agents/.history/favorites.json, keyed by session id, so
+      Favorites live in ~/.agents/.history/favorites.json, keyed by session id, so
       they survive a reindex of the session cache. They are per-machine: session
       sync carries transcripts, not this file.
     `,
@@ -74,18 +74,18 @@ export function registerSessionsFavoriteCommand(sessionsCmd) {
         // owns; it is still declared on this command so `--help` documents it.
         const json = self.optsWithGlobals().json === true;
         if (options.list || ids.length === 0) {
-            const starred = [...listFavorites()].sort();
+            const favorited = [...listFavorites()].sort();
             if (json) {
-                process.stdout.write(JSON.stringify({ favorites: starred }, null, 2) + '\n');
+                process.stdout.write(JSON.stringify({ favorites: favorited }, null, 2) + '\n');
                 return;
             }
-            if (starred.length === 0) {
-                console.log(chalk.gray('No favorited sessions. Star one with `agents sessions favorite <id>`.'));
+            if (favorited.length === 0) {
+                console.log(chalk.gray('No favorited sessions. Favorite one with `agents sessions favorite <id>`.'));
                 return;
             }
-            for (const id of starred)
+            for (const id of favorited)
                 console.log(`${chalk.yellow('★')} ${id}`);
-            console.log(chalk.gray(`\n${starred.length} favorite${starred.length === 1 ? '' : 's'}.`));
+            console.log(chalk.gray(`\n${favorited.length} favorite${favorited.length === 1 ? '' : 's'}.`));
             return;
         }
         const on = !options.remove;
@@ -96,8 +96,8 @@ export function registerSessionsFavoriteCommand(sessionsCmd) {
                 results.push({ query: idQuery, error: resolved.error });
                 continue;
             }
-            // Unstarring something that was never starred, or starring it twice, is a
-            // no-op the store already short-circuits — report the resulting state.
+            // Unfavoriting something that was never favorited, or favoriting it twice,
+            // is a no-op the store already short-circuits — report the resulting state.
             setFavorite(resolved.id, on);
             results.push({ query: idQuery, id: resolved.id, favorite: isFavorite(resolved.id) });
         }
@@ -112,8 +112,8 @@ export function registerSessionsFavoriteCommand(sessionsCmd) {
                     console.log(`${r.favorite ? chalk.yellow('★ favorited') : chalk.gray('☆ unfavorited')} ${r.id}`);
             }
         }
-        // A failed lookup is a failed command — a script must not read "starred" from
-        // a zero exit when nothing was starred.
+        // A failed lookup is a failed command — a script must not read "favorited"
+        // from a zero exit when nothing was favorited.
         if (results.some((r) => r.error))
             process.exitCode = 1;
     });

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

@@ -1,5 +1,6 @@
 import type { SessionEvent, SessionMeta, TodoProgress } from '../lib/session/types.js';
-import { classifyFileChanges } from '../lib/session/digest.js';
+import { classifyFileChanges, changeCounts, toolHistogram, detectTestResult } from '../lib/session/digest.js';
+import { extractArtifacts, extractHooks, extractLinks, extractSkills } from '../lib/session/highlights.js';
 /**
  * Compact checklist tally for list rows and previews (RUSH-2045).
  * Example: `✓6/8 · A5 wiring runner`. Empty string when there is no list.
@@ -31,6 +32,12 @@ export interface SessionPickerConfig {
     /** Lines the caller printed above the prompt (hidden-session footer). */
     linesAbovePrompt?: number;
 }
+export declare function clearPreviewMemoryCacheForTest(): void;
+export declare function loadSessionPreviewDigest(session: SessionMeta): {
+    digest?: SessionPreviewDigest;
+    events: SessionEvent[];
+    error?: string;
+};
 /** Build a cached multi-line preview string for display in the session picker. */
 export declare function buildPreview(session: SessionMeta): string;
 /**
@@ -65,6 +72,31 @@ export declare function extractTiming(session: Pick<SessionMeta, 'timestamp' | '
     lastActiveAgo?: string;
     duration?: string;
 };
+export interface SessionPreviewDigest {
+    schemaVersion: 1;
+    firstUser: string;
+    lastAssistant: string;
+    filesRead: number;
+    toolCalls: number;
+    planFile: string;
+    todos?: TodoProgress;
+    subAgentCount: number;
+    toolTags: string[];
+    changes: ReturnType<typeof changeCounts>;
+    dirs: string[];
+    repos: string[];
+    artifacts: ReturnType<typeof extractArtifacts>;
+    skills: ReturnType<typeof extractSkills>;
+    plugins: string[];
+    hooks: ReturnType<typeof extractHooks>;
+    links: ReturnType<typeof extractLinks>;
+    errorCount: number;
+    firstError?: string;
+    toolHistogram: ReturnType<typeof toolHistogram>;
+    test: ReturnType<typeof detectTestResult>;
+}
+/** Fold a harness-normalized event stream into the stable preview data model. */
+export declare function buildSessionPreviewDigest(events: SessionEvent[], session: SessionMeta): SessionPreviewDigest;
 /**
  * Unique directories the session touched, compact and human-readable.
  * Prefer `session.recentDirectoriesTouched` — the scan records it on the row, so