@phnx-labs/agents-cli 1.22.23 → 1.22.24

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
@@ -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, 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,7 +65,11 @@ 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;
@@ -105,8 +120,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 +138,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 +184,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 +218,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 +249,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 +263,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,11 +308,7 @@ 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 forwarded = remotePoolArgs(f, fixedFilters);
             const remoteResult = await gatherRemoteList(forwarded, remoteHosts);
             unreachable = remoteResult.unreachable;
             if (remoteResult.sessions.length > 0)
@@ -272,6 +325,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
@@ -366,27 +445,74 @@ 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));
+    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 rows = filter.running || opts.includeLive
+        ? mergeLiveIntoPool(pool.rows, liveById, self)
+        : 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

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

package/dist/commands/sessions-resume.js

@@ -14,14 +14,15 @@ import { discoverSessions } from '../lib/session/discover.js';
 import { filterTeamSessions } from '../lib/session/team-filter.js';
 import { multiItemPicker, itemPicker } from '../lib/picker.js';
 import { buildPreview } from './sessions-picker.js';
-import { filterSessionsByQuery, formatPickerLabel, pickerColumnsFor, resumeSessionInPlace, parseAgentFilter, } from './sessions.js';
+import { filterSessionsByQuery, formatPickerLabel, pickerColumnsFor, buildSessionRecoveryCommand, resumeSessionInPlace, parseAgentFilter, } from './sessions.js';
 import { openSurfaces, availableBackends, detectCurrentBackend, currentContext, } from '../lib/terminal/index.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { setHelpSections } from '../lib/help.js';
 import { confirm } from '@inquirer/prompts';
 import { spawn } from 'node:child_process';
-import { buildCanonicalResumeCommand } from '../lib/session/resume-command.js';
 import { looksLikeSessionId } from '../lib/session/discover.js';
+import { machineId } from '../lib/session/sync/config.js';
+import { sessionOriginDevice, sessionRecoveryDestinationMatches } from '../lib/session/recovery.js';
 /** Opening more than this many live sessions at once asks for confirmation first. */
 export const CONFIRM_THRESHOLD = 5;
 export function registerSessionsResumeCommand(sessionsCmd) {
@@ -34,7 +35,7 @@ export function registerSessionsResumeCommand(sessionsCmd) {
         .option('--teams', 'Include team-spawned sessions (hidden by default)')
         .option('--since <time>', 'Only sessions newer than this (e.g., 2h, 7d, 4w, or ISO date)')
         .option('-n, --limit <n>', 'Maximum number of sessions to load into the picker', '200')
-        .option('--host <alias>', 'Resume on a remote host over SSH (defaults to tmux there)')
+        .option('--host <alias>', 'Open on the session origin host over SSH; the host must match every selected session')
         .option('--iterm', 'Force the iTerm backend')
         .option('--ghostty', 'Force the Ghostty backend')
         .option('--tmux', 'Force the tmux backend')
@@ -65,8 +66,8 @@ export function registerSessionsResumeCommand(sessionsCmd) {
       - 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).
-      - Each session opens version-pinned, in its own cwd. Non-resumable agents are skipped with a note.
+      - --host <alias> opens the terminal surface on that host only when it is the selected sessions' origin; recovery never migrates a session to another device.
+      - Recovery runs on the session's origin device: exact healthy origin uses native resume; otherwise a healthy version of the same harness receives /continue <id>.
     `,
     });
     cmd.action(async (query, options) => {
@@ -127,17 +128,25 @@ async function sessionsResumeAction(query, options) {
     }
     if (!chosen || chosen.length === 0)
         return;
-    // 2. Split the selection into resumable surfaces and skipped agents (no silent drop).
+    if (options.host) {
+        const requestedHost = options.host;
+        const mismatches = chosen
+            .map((session) => resumeHostMismatch(session, requestedHost))
+            .filter((message) => message !== null);
+        if (mismatches.length > 0) {
+            for (const message of mismatches)
+                console.error(chalk.red(message));
+            process.exitCode = 1;
+            return;
+        }
+    }
+    // 2. Route every selection through the owning device's recovery resolver.
     const items = [];
     for (const s of chosen) {
-        const command = buildCanonicalResumeCommand(s.id);
+        const command = buildSessionRecoveryCommand(s, !!options.host);
         const cwd = s.cwd && fs.existsSync(s.cwd) ? s.cwd : process.cwd();
         items.push({ session: s, cwd, command });
     }
-    if (items.length === 0) {
-        console.log(chalk.gray('Nothing resumable in the selection.'));
-        return;
-    }
     // 3. Resolve the backend (and host).
     const ctx = currentContext();
     const backend = await resolveBackend(options, ctx, items.length);
@@ -221,6 +230,12 @@ async function spawnCliInPlace(args) {
 export function resolveResumePacking(options) {
     return options.splits ? 'two-per-tab' : 'tabs';
 }
+export function resumeHostMismatch(session, requestedHost, self = machineId()) {
+    const origin = sessionOriginDevice(session, self);
+    return sessionRecoveryDestinationMatches(session, requestedHost, self)
+        ? null
+        : `Session ${session.shortId} originated on ${origin}; --host ${requestedHost} cannot move recovery to another device.`;
+}
 /**
  * Decide which backend to launch into. Returns a concrete backend, `'inplace'`
  * (resume in the current process — no GUI/tmux available), or `'cancel'` (the

package/dist/commands/sessions.d.ts

@@ -573,6 +573,13 @@ export declare function handlePickedSession(picked: PickedSession): Promise<void
  * version-pinned launcher is genuinely missing.
  */
 export declare function resumeSessionInPlace(session: SessionMeta): Promise<void>;
+/**
+ * Relaunch this CLI's one recovery path. The owning device resolves account
+ * health and either performs exact-home native resume or same-harness
+ * `/continue`; callers never guess which version home can see the transcript.
+ * `portable` is for an SSH/terminal-engine command that executes on a peer.
+ */
+export declare function buildSessionRecoveryCommand(session: Pick<SessionMeta, 'id'>, portable?: boolean): string[];
 /**
  * Map a resume argv to the spawn(command, args, {shell}) triple.
  *
@@ -594,6 +601,9 @@ interface AgentFilter {
     agent?: SessionAgentId;
     version?: string;
 }
+/** Resolve the harness portion of a sessions selector with the CLI's canonical
+ * alias and single-typo rules. Kept pure so focus and the browser cannot drift. */
+export declare function resolveSessionAgentName(name: string): SessionAgentId | null;
 export declare function parseAgentFilter(agentName?: string): AgentFilter;
 /**
  * How a `sessions <query>` argument was resolved against the pool.

package/dist/commands/sessions.js

@@ -20,7 +20,7 @@ import { listProjectDefs, resolveProjectNameForCwd } from '../lib/projects.js';
 import ora from 'ora';
 import { SESSION_AGENTS } from '../lib/session/types.js';
 import { discoverArtifacts, readArtifact, resolveArtifact } from '../lib/session/artifacts.js';
-import { looksLikePath, toComparablePath, homeDir, needsWindowsShell, findExecutable, composeWin32CommandLine } from '../lib/platform/index.js';
+import { looksLikePath, toComparablePath, homeDir, needsWindowsShell, composeWin32CommandLine } from '../lib/platform/index.js';
 import { getActiveSessions } from '../lib/session/active.js';
 import { enumerateGhosttyTabs, assignGhosttyTabs } from '../lib/session/ghostty-tabs.js';
 import { mapPanesToTargets, listClients } from '../lib/tmux/session.js';
@@ -45,6 +45,8 @@ import { getShimsDir } from '../lib/state.js';
 import { fuzzyMatch, FUZZY_PRESETS } from '../lib/fuzzy.js';
 import { resolveSessionAlias } from '../lib/session/actor-sidecar.js';
 import { resolveVersionAliasLoose } from '../lib/versions.js';
+import { getAgentsInvocation } from '../lib/daemon.js';
+import { sessionRecoveryRunArgs } from '../lib/session/recovery.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { sessionPicker, buildPreview, formatTodoCompact, githubRepoUrlFromCwd, } from './sessions-picker.js';
 import { setHelpSections } from '../lib/help.js';
@@ -3017,34 +3019,23 @@ export async function resumeSessionInPlace(session) {
     const cwd = session.cwd && fs.existsSync(session.cwd)
         ? session.cwd
         : process.cwd();
-    const resume = buildResumeCommand(session);
-    if (!resume) {
-        console.log(chalk.yellow(`Resume is not supported for ${session.agent} sessions yet. Showing summary instead.`));
-        await renderSession(session, 'summary', {});
-        return;
-    }
+    const resume = buildSessionRecoveryCommand(session);
     console.log(chalk.gray(`Resuming: ${resume.join(' ')} (cwd: ${cwd})`));
-    // Resolve the (possibly version-pinned) launcher up front. On Windows the
-    // agent shim is a `.cmd`/`.ps1` and, under the shell needed to run it (see
-    // spawnResumeCommand), a missing command exits non-zero rather than emitting
-    // an ENOENT `error` event — so detect a removed version here instead of
-    // relying on that event, keeping the fallback working on every OS.
-    // `resume[0]` is an absolute alias path when one exists on disk, so only a bare
-    // name still needs a PATH lookup. Checking existsSync first is what keeps an
-    // isolated install (shims deliberately off PATH) out of the fallback.
-    const launcherFound = path.isAbsolute(resume[0])
-        ? fs.existsSync(resume[0])
-        : !!findExecutable(resume[0]);
-    if (!launcherFound && session.version) {
-        const fallback = buildFallbackCommand(session);
-        if (fallback) {
-            console.log(chalk.gray(`Version ${session.version} is not installed. Resuming with the current version instead...`));
-            await spawnResumeCommand(fallback, cwd);
-            return;
-        }
-    }
     await spawnResumeCommand(resume, cwd);
 }
+/**
+ * Relaunch this CLI's one recovery path. The owning device resolves account
+ * health and either performs exact-home native resume or same-harness
+ * `/continue`; callers never guess which version home can see the transcript.
+ * `portable` is for an SSH/terminal-engine command that executes on a peer.
+ */
+export function buildSessionRecoveryCommand(session, portable = false) {
+    const args = sessionRecoveryRunArgs(session);
+    if (portable)
+        return ['agents', ...args];
+    const invocation = getAgentsInvocation(args);
+    return [invocation.command, ...invocation.args];
+}
 /**
  * Map a resume argv to the spawn(command, args, {shell}) triple.
  *
@@ -3112,8 +3103,6 @@ function spawnResumeCommand(cmd, cwd) {
  * isolated HOME where the JSONL was written — regardless of which version is
  * currently the default. Falls back to the bare shim when version is unknown.
  *
- * If the versioned binary is missing (version was removed), the ENOENT
- * handler in handlePickedSession retries via buildFallbackCommand.
  */
 /**
  * The agent's own resume invocation, given whichever launcher we resolved.
@@ -3180,19 +3169,6 @@ export function buildResumeCommand(session) {
             return null;
     }
 }
-/**
- * Fallback when the pinned version really is gone: the same resume invocation
- * against the current version.
- *
- * This used to spawn `<cli> "/continue <id>"`, feeding a slash command into the
- * TUI as a prompt. Neither CLI has `/continue` — codex documents `/resume` — so
- * the agent received an unrecognised command and the session was not resumed at
- * all. Reusing resumeArgv keeps the two paths from drifting apart again.
- */
-function buildFallbackCommand(session) {
-    const cli = AGENTS[session.agent]?.cliCommand ?? session.agent;
-    return resumeArgv(session.agent, session.id, cli);
-}
 // ---------------------------------------------------------------------------
 // Cloud session source (--cloud)
 // ---------------------------------------------------------------------------
@@ -3263,25 +3239,24 @@ async function runCloudSessions(query, options) {
     // Ensure the SessionMeta points at the local cache path for renderSession.
     await renderSession({ ...meta, filePath: cachedPath }, mode, filterOpts, options);
 }
+/** Resolve the harness portion of a sessions selector with the CLI's canonical
+ * alias and single-typo rules. Kept pure so focus and the browser cannot drift. */
+export function resolveSessionAgentName(name) {
+    const normalized = name.toLowerCase();
+    if (SESSION_AGENTS.includes(normalized)) {
+        return normalized;
+    }
+    const resolved = resolveAgentName(normalized);
+    if (resolved && SESSION_AGENTS.includes(resolved)) {
+        return resolved;
+    }
+    return fuzzyMatch(normalized, SESSION_AGENTS, FUZZY_PRESETS.agents);
+}
 export function parseAgentFilter(agentName) {
     if (!agentName)
         return {};
     const [name, version] = agentName.split('@', 2);
-    let agent = SESSION_AGENTS.includes(name)
-        ? name
-        : null;
-    if (!agent) {
-        // Aliases and single-typo corrections (cladue -> claude). SESSION_AGENTS
-        // includes ids (rush, hermes) that resolveAgentName doesn't know, so fall
-        // back to fuzzy-matching the session list directly.
-        const resolved = resolveAgentName(name);
-        if (resolved && SESSION_AGENTS.includes(resolved)) {
-            agent = resolved;
-        }
-        else {
-            agent = fuzzyMatch(name, SESSION_AGENTS, FUZZY_PRESETS.agents);
-        }
-    }
+    const agent = resolveSessionAgentName(name);
     if (!agent) {
         console.error(chalk.red(`Unknown agent: ${name}. Use: ${SESSION_AGENTS.join(', ')}`));
         process.exit(1);
@@ -3930,7 +3905,7 @@ export function registerSessionsCommands(program) {
         .option('--opencode', 'Shorthand for --agent opencode')
         .option('--all', 'Widen every non-status filter to "all": every directory (not just this project) and all time (no window cap). Status filters like --active still compose; -a/--device/--since still narrow their axis.')
         .option('--unmanaged', "Also show sessions from your own ~/.<agent> installs (hidden once agents-cli manages that agent)")
-        .option('--teams', 'Include team-spawned sessions (hidden by default)')
+        .option('--team, --teams', 'Include team-spawned sessions (hidden by default)')
         .option('--in-team <name>', "Only this team: the session that spawned it plus (with --teams) its teammates. Spans every directory and all time, since a team's worktrees and history sit outside the default window.")
         .option('--routine', 'Show only sessions archived from routine runs')
         .option('-p, --project <name>', 'Filter by project name (searches across all directories)')
@@ -3997,7 +3972,7 @@ export function registerSessionsCommands(program) {
       agents sessions --crashed
 
       # --- Session lifecycle (one verb per intent) ---
-      # Jump to a live session (attach its terminal, or open a tab + resume)
+      # Focus a session (attach its living terminal, or recover an ended one)
       agents sessions focus a1b2c3d4
       # Attach only — never fork a copy (old: sessions go)
       agents sessions focus a1b2c3d4 --attach-only
@@ -4049,7 +4024,7 @@ export function registerSessionsCommands(program) {
     `,
         notes: `
       Session lifecycle (pick one verb — they are not synonyms):
-        focus [id]              jump to a live session (attach, or open tab + resume)
+        focus [selector]        attach a living pane, or recover on the origin device
         focus [id] --attach-only  attach only; never fork (replaces sessions go)
         detach <id>             interactive → headless continuation
         attach <id>             headless → interactive in this terminal

package/dist/commands/setup-secrets.js

@@ -66,7 +66,7 @@ function printBackendNotes(backend) {
         console.log(chalk.gray('backend: keychain — macOS reads may ask for Touch ID or the device password.'));
     }
     else if (backend === 'file') {
-        console.log(chalk.gray('backend: file — set AGENTS_SECRETS_PASSPHRASE for headless encrypted-file reads.'));
+        console.log(chalk.gray('backend: file — encrypted at rest; headless reads need no passphrase by default, via a machine-local key at ~/.agents/.secrets-key/passphrase.'));
     }
     else {
         console.log(chalk.gray('backend: vault — synced ~/.agents/vault.age storage; unlock it with agents login.'));