@phnx-labs/agents-cli 1.22.23 → 1.22.25

package/dist/commands/secrets.js

@@ -31,6 +31,7 @@ import { readMeta } from '../lib/state.js';
 import { parseDuration } from '../lib/hooks/cache.js';
 import { emit, query } from '../lib/events.js';
 import { emitSecretAudit } from '../lib/secrets/audit.js';
+import { SYNC_PASSPHRASE_ENV, resolveSyncPassphraseFromEnv } from '../lib/secrets/sync-passphrase.js';
 import { getBundleUsage, getAllBundleUsage, getUsageHistory, SECRET_USAGE_EVENTS, } from '../lib/secrets/usage-db.js';
 import { frequentlyPromptedBundles } from '../lib/secrets/unlock-hints.js';
 import { registerCommandGroups, setHelpSections } from '../lib/help.js';
@@ -266,11 +267,31 @@ function maybePrintSyncedHint(name, stillPresent) {
  * defaults). Shared with the command action so the wiring is unit-testable
  * without a live SSH session.
  */
+export function resolveUnlockTtlMs(ttl, until, now = Date.now()) {
+    if (ttl && until)
+        throw new Error('--ttl and --until are mutually exclusive.');
+    if (until) {
+        const expiresAt = Date.parse(until);
+        if (!Number.isFinite(expiresAt))
+            throw new Error("Invalid --until '" + until + "'. Use an ISO date or timestamp.");
+        if (expiresAt <= now)
+            throw new Error("Invalid --until '" + until + "': date must be in the future.");
+        return expiresAt - now;
+    }
+    if (ttl) {
+        const secs = parseDuration(ttl);
+        if (!secs)
+            throw new Error("Invalid --ttl '" + ttl + "'. Use e.g. 30m, 2h, 8h, 3d.");
+        return secs * 1000;
+    }
+    return secretsHoldMs();
+}
 export function buildRemoteUnlockArgs(names, opts) {
     return [
         'unlock',
         ...(opts.all ? ['--all'] : names),
         ...(opts.ttl ? ['--ttl', opts.ttl] : []),
+        ...(opts.until ? ['--until', opts.until] : []),
         // Forward --durable so a remote unlock honors it too; without this the remote
         // silently falls back to its own secrets.agent.durable default (off).
         ...(opts.durable ? ['--durable'] : []),
@@ -1957,7 +1978,7 @@ Examples:
         .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)')
-        .option('--from-file <path>', 'Import from an AES-256-GCM encrypted offline bundle file (needs AGENTS_SECRETS_PASSPHRASE; symmetric counterpart of export --to-file)')
+        .option('--from-file <path>', `Import from an AES-256-GCM encrypted offline bundle file (needs ${SYNC_PASSPHRASE_ENV}; symmetric counterpart of export --to-file)`)
         .option('--from-ssh', 'Pull the bundle from a fleet peer over SSH and import it locally (requires --host)')
         .option('--host <peer>', 'SSH peer to pull from when using --from-ssh (host alias or user@host)')
         .action(async (bundleName, opts) => {
@@ -1973,9 +1994,10 @@ Examples:
                 throw new Error('--from-file, --from-ssh, and --from/--from-1password are mutually exclusive; pick one import source.');
             }
             if (opts.fromFile) {
-                const passphrase = process.env.AGENTS_SECRETS_PASSPHRASE ?? '';
+                // Transport, not the local store's master key — see lib/secrets/sync-passphrase.ts.
+                const passphrase = resolveSyncPassphraseFromEnv().value ?? '';
                 if (!passphrase) {
-                    throw new Error('--from-file needs AGENTS_SECRETS_PASSPHRASE set to decrypt the bundle file.');
+                    throw new Error(`--from-file needs ${SYNC_PASSPHRASE_ENV} set to decrypt the bundle file.`);
                 }
                 const env = importBundleFromFile(opts.fromFile, passphrase);
                 const resolvedBundleName = bundleName ?? (await pickBundleName('import into'));
@@ -2063,7 +2085,7 @@ Examples:
         .option('--remote-backend <backend>', 'Backend for the bundle on the remote (with --host): keychain (default) or file. file is headless-readable via the remote\'s machine-local key; it forwards AGENTS_SECRETS_PASSPHRASE over stdin only if set (opt-in).', 'keychain')
         .option('--force', 'Overwrite existing keys/items on the target (used with --to-1password and --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)')
+        .option('--to-file <path>', `Write the bundle as an AES-256-GCM encrypted offline file (needs ${SYNC_PASSPHRASE_ENV}; symmetric counterpart of import --from-file)`)
         .action(async (bundleName, opts) => {
         try {
             // `--device` is an alias for `--host` (fleet vocabulary parity with
@@ -2074,9 +2096,10 @@ Examples:
             const { readAndResolveBundleEnv, bundleToEnvPrefix, isReservedEnvName } = await import('../lib/secrets/bundles.js');
             const resolvedBundleName = bundleName ?? (await pickBundleName('export'));
             if (opts.toFile) {
-                const passphrase = process.env.AGENTS_SECRETS_PASSPHRASE ?? '';
+                // Transport, not the local store's master key — see lib/secrets/sync-passphrase.ts.
+                const passphrase = resolveSyncPassphraseFromEnv().value ?? '';
                 if (!passphrase) {
-                    throw new Error('--to-file needs AGENTS_SECRETS_PASSPHRASE set to encrypt the bundle. ' +
+                    throw new Error(`--to-file needs ${SYNC_PASSPHRASE_ENV} 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: true });
@@ -2483,11 +2506,16 @@ Examples:
         .command('unlock [names...]')
         .description('Hold a bundle in the secrets-agent after one Touch ID, so concurrent runs read it without re-prompting (macOS). With --host, unlock FILE-backed bundle(s) on a remote (the passphrase prompt surfaces over the SSH TTY); keychain/biometry bundles are GUI-only and can\'t be remote-unlocked.')
         .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('--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) => {
+        if (opts.ttl && opts.until) {
+            console.error(chalk.red('--ttl and --until are mutually exclusive.'));
+            process.exit(1);
+        }
         // Single-valued (not variadic): a variadic --host greedily consumes the
         // positional bundle name (`unlock --host mac wztest` -> host=[mac,wztest],
         // names=[]). Unlock targets one remote at a time anyway.
@@ -2524,6 +2552,15 @@ Examples:
                 process.exit(1);
             return;
         }
+        if (opts.until) {
+            try {
+                resolveUnlockTtlMs(undefined, opts.until);
+            }
+            catch (err) {
+                console.error(chalk.red(err.message));
+                process.exit(1);
+            }
+        }
         if (process.platform !== 'darwin') {
             // No broker + no biometry prompt off darwin: secrets already resolve
             // durably from the OS store (libsecret / Credential Manager) on every
@@ -2537,15 +2574,15 @@ Examples:
             console.error(chalk.red('Specify one or more bundle names, or --all.'));
             process.exit(1);
         }
-        let ttlMs = secretsHoldMs(); // default hold, capped by secrets.agent.holdMs
-        if (opts.ttl) {
-            const secs = parseDuration(opts.ttl);
-            if (!secs) {
-                console.error(chalk.red(`Invalid --ttl '${opts.ttl}'. Use e.g. 30m, 2h, 8h, 3d.`));
-                process.exit(1);
-            }
-            ttlMs = secs * 1000;
+        let ttlMs;
+        try {
+            ttlMs = resolveUnlockTtlMs(opts.ttl, opts.until);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
         }
+        const expiresAt = Date.now() + ttlMs;
         if (!(await ensureAgentRunning())) {
             console.error(chalk.red('Could not start the secrets broker.'));
             process.exit(1);
@@ -2571,7 +2608,7 @@ Examples:
                     noAgent: true,
                     caller: 'unlock secrets',
                     agent: harness,
-                    duration: humanRemaining(Date.now() + ttlMs),
+                    duration: humanRemaining(expiresAt),
                     keyMode: 'storage',
                 });
                 // Migrations are authorized only by this explicit unlock. The bundle
@@ -2587,7 +2624,7 @@ Examples:
                     saveSession(name, {
                         bundle,
                         env,
-                        expiresAt: Date.now() + ttlMs,
+                        expiresAt,
                         sleepPersist: durable,
                         harness,
                     });
@@ -2606,7 +2643,7 @@ Examples:
                         agent: harness,
                         ttlMs,
                     });
-                    console.log(`${chalk.green('unlocked')} ${chalk.cyan(name)} ${chalk.gray(`(${Object.keys(env).length} keys, ${humanRemaining(Date.now() + ttlMs)})`)}`);
+                    console.log(`${chalk.green('unlocked')} ${chalk.cyan(name)} ${chalk.gray(`(${Object.keys(env).length} keys, ${humanRemaining(expiresAt)})`)}`);
                 }
                 else {
                     console.error(chalk.red(`Failed to load '${name}' into the agent.`));

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

@@ -11,6 +11,7 @@
  */
 import { type SessionMeta } from '../lib/session/types.js';
 import type { ActiveSession } from '../lib/session/active.js';
+import { type LiveStatusFilter } from './sessions.js';
 /**
  * The single canonical filter state. Every field has a flag equivalent, so the
  * same view is reachable interactively (hotkeys) or from the command line (flags).
@@ -32,6 +33,23 @@ export interface BrowserFilter {
     projectScope: 'repo' | 'all';
     /** time window (undefined = all time) — the `W` key / `--since`. */
     window?: string;
+    /** individual live states; an OR-union and, like the CLI flags, running-only. */
+    statuses: LiveStatusFilter[];
+    /** named project scope, independent of the repo/all hotkey. */
+    project?: string;
+    /** upper time bound from --until. */
+    until?: string;
+    /** retain only routine-origin sessions. */
+    routine: boolean;
+    /** indexed resource filters shared by the flag and focus surfaces. */
+    skill?: string;
+    plugin?: string;
+    /** discovery cap. */
+    limit: number;
+    /** include unmanaged native-home transcripts. */
+    unmanaged: boolean;
+    /** candidate order shared with --sort. */
+    sort: 'timestamp' | 'cost' | 'duration';
 }
 /**
  * Complete a seed into the filter the picker actually runs on.
@@ -97,6 +115,9 @@ export declare function bareBrowserSeed(opts: {
     inTeam?: string;
     favorites?: boolean;
 }): Partial<BrowserFilter>;
+/** Build the static peer query. Keeping it pure pins the per-device alias
+ * contract: latest/oldest travel unresolved and are resolved by each peer. */
+export declare function remotePoolArgs(f: BrowserFilter, fixedFilters: boolean): string[];
 /**
  * A live session's stable row key: its session id when the agent reported one,
  * else a per-machine handle so an id-less live session (a just-booted harness, a
@@ -126,7 +147,7 @@ export declare function liveSessionToMeta(a: ActiveSession, self: string): Sessi
  * `--active --json` listed it. Live sessions the pool lacks are appended as their
  * own rows, then the whole set is grouped local-machine-first.
  */
-export declare function mergeLiveIntoPool(rows: SessionMeta[], live: Map<string, ActiveSession>, self: string): SessionMeta[];
+export declare function mergeLiveIntoPool(rows: SessionMeta[], live: Map<string, ActiveSession>, self: string, includeUnindexed?: boolean): SessionMeta[];
 /**
  * Whether to render the host-program column. It belongs to the running view
  * only, so this gates on the FILTER — not on the live index being populated.
@@ -135,6 +156,20 @@ export declare function mergeLiveIntoPool(rows: SessionMeta[], live: Map<string,
  * listing that has no live rows to explain it.
  */
 export declare function shouldShowHostColumn(f: BrowserFilter, live: Map<string, ActiveSession> | null, rows: SessionMeta[]): boolean;
+/** Apply the cheap in-memory filters (agent / device / project / running / favorites). */
+export declare function applyFilters(rows: SessionMeta[], live: Map<string, ActiveSession>, f: BrowserFilter, self: string, favorites: Set<string>): SessionMeta[];
+/** One-shot form of the browser's canonical candidate pipeline. Focus uses this
+ * instead of maintaining a second discovery/filter implementation. */
+export declare function collectSessionCandidates(initial: Partial<BrowserFilter>, opts?: {
+    local?: boolean;
+    hosts?: string[];
+    includeLive?: boolean;
+}): Promise<{
+    sessions: SessionMeta[];
+    liveById: Map<string, ActiveSession>;
+    self: string;
+    unreachable: string[];
+}>;
 /**
  * Launch the interactive session browser. `initial` seeds the filter (e.g.
  * `{ running: true }` for `--active`). Resolves after the user resumes a session

package/dist/commands/sessions-browser.js

@@ -16,11 +16,13 @@ import { dynamicPicker } from '../lib/picker.js';
 import { isSessionTrackedAgent } from '../lib/session/types.js';
 import { discoverSessions } from '../lib/session/discover.js';
 import { gatherRemoteList } from '../lib/session/remote-list.js';
+import { resolveVersionAliasLoose } from '../lib/versions.js';
+import { AGENTS } from '../lib/agents.js';
 import { enrichTeamOrigins, safeTeamText } from '../lib/session/team-filter.js';
 import { listFavorites, toggleFavorite } from '../lib/session/favorites.js';
 import { machineId, normalizeHost } from '../lib/session/sync/config.js';
 import { buildPreview } from './sessions-picker.js';
-import { formatPickerLabel, pickerColumnsFor, ticketLabel, mergeLocalFirst, gatherActiveSessions, liveHostLabel, LIVE_ROW_PREFIX, cleanPreview, handlePickedSession, shouldIncludeLocal, remoteHostsToDial, matchesTeam, formatLiveStatusHeadline, } from './sessions.js';
+import { formatPickerLabel, pickerColumnsFor, ticketLabel, mergeLocalFirst, gatherActiveSessions, liveHostLabel, LIVE_ROW_PREFIX, cleanPreview, handlePickedSession, shouldIncludeLocal, remoteHostsToDial, matchesTeam, formatLiveStatusHeadline, isRunningLiveSession, matchesLiveStatus, parseAgentFilter, } from './sessions.js';
 /**
  * Complete a seed into the filter the picker actually runs on.
  *
@@ -44,6 +46,15 @@ export function buildInitialFilter(initial) {
         team: initial.team,
         projectScope: initial.projectScope ?? 'repo',
         window: 'window' in initial ? initial.window : '30d',
+        statuses: initial.statuses ?? [],
+        project: initial.project,
+        until: initial.until,
+        routine: initial.routine ?? false,
+        skill: initial.skill,
+        plugin: initial.plugin,
+        limit: initial.limit ?? 500,
+        unmanaged: initial.unmanaged ?? false,
+        sort: initial.sort ?? 'timestamp',
     };
 }
 /** Cache key for the transcript pool: every filter that changes what is FETCHED
@@ -54,10 +65,16 @@ function poolCacheKey(f) {
     // fetches the same deep pool and is then narrowed in memory. Keying on the name
     // would make `t` the one hotkey that re-fans-out the fleet on every step of the
     // cycle, at up to REMOTE_TIMEOUT_MS per unreachable peer.
-    return `${f.window ?? 'all'}|${f.teams}|${f.team ? 'team' : ''}`;
+    const versionScoped = f.agent?.includes('@') ? f.agent : '';
+    return [
+        f.window ?? 'all', f.until ?? '', f.teams, f.team ? 'team' : '', versionScoped,
+        f.project ?? '', f.routine, f.skill ?? '', f.plugin ?? '', f.limit, f.unmanaged, f.sort,
+    ].join('|');
 }
 /** Pool size when a team filter is active; one team's rows can sit anywhere. */
 const WHOLE_TEAM_POOL_LIMIT = 5000;
+/** A cold peer may need to resolve an installed-version alias and scan its index. */
+const BROWSER_PEER_TIMEOUT_MS = 30_000;
 /** Ordered window cycle for the `W` key. `undefined` = all time. */
 const WINDOW_CYCLE = [undefined, '1d', '7d', '30d'];
 /** Return the next value in `[undefined, ...options]`, wrapping. */
@@ -105,8 +122,10 @@ export function sessionMatchesQuery(s, query) {
  */
 export function browserFilterToArgv(f, query = '') {
     const a = ['sessions'];
-    if (f.running)
+    if (f.statuses.length === 0 && f.running)
         a.push('--active');
+    for (const status of f.statuses)
+        a.push(`--${status === 'orphaned' ? 'orphan' : status}`);
     if (f.teams)
         a.push('--teams');
     if (f.favorites)
@@ -121,6 +140,22 @@ export function browserFilterToArgv(f, query = '') {
         a.push('--all');
     if (f.window)
         a.push('--since', f.window);
+    if (f.until)
+        a.push('--until', f.until);
+    if (f.project)
+        a.push('--project', f.project);
+    if (f.routine)
+        a.push('--routine');
+    if (f.skill)
+        a.push('--skill', f.skill);
+    if (f.plugin)
+        a.push('--plugin', f.plugin);
+    if (f.unmanaged)
+        a.push('--unmanaged');
+    if (f.sort !== 'timestamp')
+        a.push('--sort', f.sort === 'cost' ? 'cost' : 'duration');
+    if (f.limit !== 500)
+        a.push('--limit', String(f.limit));
     const q = query.trim();
     if (q)
         a.push(JSON.stringify(q));
@@ -151,6 +186,7 @@ export function activeBrowserSeed(opts) {
         // --all widens the window to all-time (project is already 'all' here);
         // --since still overrides.
         window: opts.since ?? (opts.all ? undefined : '30d'),
+        statuses: [],
     };
 }
 /**
@@ -184,6 +220,7 @@ export function bareBrowserSeed(opts) {
         // --all maxes every non-status filter: all dirs AND all-time. --since wins.
         projectScope: opts.all || scoped || wholeTeam ? 'all' : 'repo',
         window: opts.since ?? (opts.all || wholeTeam ? undefined : '30d'),
+        statuses: [],
     };
 }
 /** Copy text to the OS clipboard (best-effort; silently no-ops if unavailable). */
@@ -214,8 +251,13 @@ function copyToClipboard(text) {
  * `hosts` is the explicit `--host`/`--device` scope (if any): it restricts which
  * peers are dialed and whether local is included, honoring the flag's "scope,
  * not add" contract instead of always sweeping the whole fleet. */
-async function fetchRawPool(f, self, local, hosts) {
+async function fetchRawPool(f, self, local, hosts, fixedFilters = false) {
     const since = f.window;
+    const selectedAgent = f.agent ? parseAgentFilter(f.agent) : {};
+    const parsedAgent = fixedFilters ? selectedAgent : {};
+    const localAgentVersion = parsedAgent.agent && parsedAgent.agent in AGENTS
+        ? resolveVersionAliasLoose(parsedAgent.agent, parsedAgent.version)
+        : parsedAgent.version;
     let unreachable = [];
     // Local pool: wide (every directory) — device/agent/project are applied in
     // memory so a hotkey toggle is instant and doesn't re-hit the disk. Skipped
@@ -223,16 +265,33 @@ async function fetchRawPool(f, self, local, hosts) {
     let rows = shouldIncludeLocal(hosts, self)
         ? await discoverSessions({
             all: true,
+            agent: parsedAgent.agent,
+            version: localAgentVersion,
+            includeUnmanaged: f.unmanaged,
             cwd: process.cwd(),
             since,
+            until: f.until,
+            project: f.project,
+            origin: f.routine ? 'routine' : undefined,
+            skill: f.skill,
+            plugin: f.plugin,
             excludeTeamOrigin: !f.teams,
             // A team filter reaches back past the usual browse window, so the pool it
             // draws from has to as well — otherwise the newest 500 rows decide which
             // teams exist.
-            limit: f.team ? WHOLE_TEAM_POOL_LIMIT : 500,
-            sortBy: 'timestamp',
+            limit: f.team ? WHOLE_TEAM_POOL_LIMIT : f.limit,
+            sortBy: f.sort,
         })
         : [];
+    // A synced mirror knows which VERSION produced a session, but it cannot know
+    // which version is currently installed as latest/oldest on the origin device.
+    // For an alias selector, keep only this device's rows here and accept peer
+    // rows only from the live query below, where that peer resolves its own
+    // inventory. If the peer is unavailable, an empty/partial result is honest;
+    // widening to cached sessions from every version is not.
+    if (selectedAgent.version === 'latest' || selectedAgent.version === 'oldest') {
+        rows = rows.filter((row) => (row.machine ?? self) === self);
+    }
     // Fleet: fold in peers' own indexes over SSH (no sync), same as the flag path.
     // Skipped under --local. An explicit --host/--device scopes exactly which peers
     // are dialed (undefined = sweep every online device). Best-effort — a fan-out
@@ -251,12 +310,10 @@ async function fetchRawPool(f, self, local, hosts) {
             // the same bug one hop out. A numeric --limit is forwarded rather than
             // --in-team itself, which a peer on an older build would reject as an
             // unknown option and fail the whole fan-out.
-            const forwarded = ['sessions', '--all', '--json', '--limit', String(f.team ? WHOLE_TEAM_POOL_LIMIT : 500)];
-            if (since)
-                forwarded.push('--since', since);
-            if (f.teams)
-                forwarded.push('--teams');
-            const remoteResult = await gatherRemoteList(forwarded, remoteHosts);
+            const forwarded = remotePoolArgs(f, fixedFilters);
+            const remoteResult = await gatherRemoteList(forwarded, remoteHosts, {
+                timeoutMs: BROWSER_PEER_TIMEOUT_MS,
+            });
             unreachable = remoteResult.unreachable;
             if (remoteResult.sessions.length > 0)
                 rows = mergeLocalFirst([...rows, ...remoteResult.sessions], self);
@@ -272,6 +329,32 @@ async function fetchRawPool(f, self, local, hosts) {
         rows = enrichTeamOrigins(rows);
     return { key: poolCacheKey(f), rows, unreachable };
 }
+/** Build the static peer query. Keeping it pure pins the per-device alias
+ * contract: latest/oldest travel unresolved and are resolved by each peer. */
+export function remotePoolArgs(f, fixedFilters) {
+    const forwarded = ['sessions', '--all', '--json', '--limit', String(f.team ? WHOLE_TEAM_POOL_LIMIT : f.limit)];
+    if (f.window)
+        forwarded.push('--since', f.window);
+    if (f.until)
+        forwarded.push('--until', f.until);
+    if (f.project)
+        forwarded.push('--project', f.project);
+    if (f.routine)
+        forwarded.push('--routine');
+    if (f.skill)
+        forwarded.push('--skill', f.skill);
+    if (f.plugin)
+        forwarded.push('--plugin', f.plugin);
+    if (f.unmanaged)
+        forwarded.push('--unmanaged');
+    if (f.sort !== 'timestamp')
+        forwarded.push('--sort', f.sort === 'cost' ? 'cost' : 'duration');
+    if (f.agent && (fixedFilters || f.agent.includes('@')))
+        forwarded.push('--agent', f.agent);
+    if (f.teams)
+        forwarded.push('--teams');
+    return forwarded;
+}
 /**
  * A live session's stable row key: its session id when the agent reported one,
  * else a per-machine handle so an id-less live session (a just-booted harness, a
@@ -344,7 +427,12 @@ export function liveSessionToMeta(a, self) {
  * `--active --json` listed it. Live sessions the pool lacks are appended as their
  * own rows, then the whole set is grouped local-machine-first.
  */
-export function mergeLiveIntoPool(rows, live, self) {
+export function mergeLiveIntoPool(rows, live, self, includeUnindexed = true) {
+    // A latest/oldest selector is resolved by the peer's transcript query. A live
+    // row absent from that result has no proof it belongs to the resolved version,
+    // so callers using an alias fail closed instead of widening the selector.
+    if (!includeUnindexed)
+        return rows;
     const known = new Set(rows.map((r) => r.id));
     const extra = [];
     for (const [key, a] of live) {
@@ -366,27 +454,82 @@ export function shouldShowHostColumn(f, live, rows) {
     return rows.some((r) => liveHostLabel(live.get(r.id)) !== '');
 }
 /** Apply the cheap in-memory filters (agent / device / project / running / favorites). */
-function applyFilters(rows, live, f, self, favorites) {
+export function applyFilters(rows, live, f, self, favorites) {
     let out = rows;
     // A projected live row is keyed by pid/task when it has no session id, and a
     // favorite is always keyed by a real session id — so an id-less row can never
     // be favorited and correctly drops out here.
     if (f.favorites)
         out = out.filter((r) => favorites.has(r.id));
-    if (f.agent)
-        out = out.filter((r) => r.agent === f.agent);
+    if (f.agent) {
+        const { agent, version: rawVersion } = parseAgentFilter(f.agent);
+        const localVersion = agent && agent in AGENTS
+            ? resolveVersionAliasLoose(agent, rawVersion)
+            : rawVersion;
+        const peerResolvedAlias = rawVersion === 'latest' || rawVersion === 'oldest';
+        out = out.filter((r) => {
+            if (r.agent !== agent)
+                return false;
+            // Only a LIVE peer result may claim it resolved latest/oldest against that
+            // device's installed inventory. A synced mirror is historical data, not a
+            // version-inventory oracle.
+            if (peerResolvedAlias && (r.machine ?? self) !== self)
+                return r._remote === true;
+            if (!localVersion)
+                return true;
+            return r.version === localVersion;
+        });
+    }
     if (f.device)
         out = out.filter((r) => (r.machine ?? self) === f.device);
     if (f.team)
         out = out.filter((r) => matchesTeam(r, f.team));
+    if (f.project) {
+        const q = f.project.toLowerCase();
+        out = out.filter((r) => (r.project ?? '').toLowerCase().includes(q) || (r.cwd ?? '').toLowerCase().includes(q));
+    }
     if (f.projectScope === 'repo') {
         const cwd = process.cwd();
         out = out.filter((r) => !!r.cwd && (r.cwd === cwd || r.cwd.startsWith(cwd + '/')));
     }
-    if (f.running)
-        out = out.filter((r) => live.has(r.id));
+    // The live registry retains dead rows so explicit --closed/--crashed filters
+    // can recover them. Bare --active means currently active; a lifecycle filter
+    // intentionally replaces that default predicate with its exact status union.
+    if (f.running && f.statuses.length === 0) {
+        out = out.filter((r) => {
+            const active = live.get(r.id);
+            return !!active && isRunningLiveSession(active);
+        });
+    }
+    if (f.statuses.length > 0) {
+        out = out.filter((r) => {
+            const active = live.get(r.id);
+            return !!active && f.statuses.some((status) => matchesLiveStatus(active, status));
+        });
+    }
     return out;
 }
+/** One-shot form of the browser's canonical candidate pipeline. Focus uses this
+ * instead of maintaining a second discovery/filter implementation. */
+export async function collectSessionCandidates(initial, opts = {}) {
+    const self = machineId();
+    const filter = buildInitialFilter(initial);
+    if (filter.statuses.length > 0)
+        filter.running = true;
+    const hosts = opts.hosts && opts.hosts.length > 0 ? opts.hosts : undefined;
+    const pool = await fetchRawPool(filter, self, opts.local ?? false, hosts, true);
+    let liveById = new Map();
+    if (filter.running || opts.includeLive) {
+        const { sessions } = await gatherActiveSessions({ local: opts.local ?? false, hosts });
+        liveById = indexLiveRows(sessions, self);
+    }
+    const includeUnindexedLive = !filter.agent?.match(/@(latest|oldest)$/);
+    const rows = filter.running || opts.includeLive
+        ? mergeLiveIntoPool(pool.rows, liveById, self, includeUnindexedLive)
+        : pool.rows;
+    const sessions = applyFilters(rows, liveById, filter, self, listFavorites());
+    return { sessions, liveById, self, unreachable: pool.unreachable };
+}
 /** Derive the SSH-launch origin tag for a picker row from the live index. Set
  * only when the live session's provenance is ssh transport; `device` is the
  * resolved origin device (absent → the row shows a bare `ssh`). Rows without a
@@ -492,7 +635,10 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
             liveCache = live;
         // Live sessions the transcript pool lacks become rows of their own, so the
         // running view lists every active session, not just the ones already indexed.
-        const rows = f.running && live ? mergeLiveIntoPool(pool.rows, live, self) : pool.rows;
+        const includeUnindexedLive = !f.agent?.match(/@(latest|oldest)$/);
+        const rows = f.running && live
+            ? mergeLiveIntoPool(pool.rows, live, self, includeUnindexedLive)
+            : pool.rows;
         agentsInPool = distinct(rows.map((r) => r.agent));
         devicesInPool = distinct(rows.map((r) => r.machine ?? self));
         // Both ends of the lineage seed the cycle: teams a row spawned, and teams a

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

@@ -1,4 +1,5 @@
 import type { Command } from 'commander';
+import type { SessionMeta } from '../lib/session/types.js';
 import { type Backend, type EngineContext, type Packing } from '../lib/terminal/index.js';
 /** Opening more than this many live sessions at once asks for confirmation first. */
 export declare const CONFIRM_THRESHOLD = 5;
@@ -30,6 +31,7 @@ export declare function resumeSelectorInPlace(selector: string): Promise<void>;
 export declare function dispatchSessionLifecycleInPlace(selector: string, hosts?: string[]): Promise<void>;
 export declare function buildSessionLifecycleArgs(selector: string, hosts?: string[]): string[];
 export declare function resolveResumePacking(options: Pick<ResumeOptions, 'splits'>): Packing;
+export declare function resumeHostMismatch(session: Pick<SessionMeta, 'shortId' | 'machine'>, requestedHost: string, self?: string): string | null;
 /**
  * Decide which backend to launch into. Returns a concrete backend, `'inplace'`
  * (resume in the current process — no GUI/tmux available), or `'cancel'` (the