@phnx-labs/agents-cli 1.22.23 → 1.22.24

package/dist/commands/focus.d.ts

@@ -13,9 +13,9 @@
  * why `--tmux`-wrapped launches are worth it for sessions you'll want back live.
  */
 import type { Command } from 'commander';
-import { type UnreachableFallback } from './go.js';
+import { probeAttachRail, type AttachRailLiveness, type UnreachableFallback } from './go.js';
 import type { ActiveSession } from '../lib/session/active.js';
-import type { SessionMeta } from '../lib/session/types.js';
+import { type SessionMeta } from '../lib/session/types.js';
 import { type LiveStatusFilter } from './sessions.js';
 import { openSurfaces, type Backend } from '../lib/terminal/index.js';
 /** Options for `sessions focus` — device/host scope + the `--active` live-state filters. */
@@ -24,6 +24,27 @@ export interface FocusOptions {
     attachOnly?: boolean;
     host?: string[];
     device?: string[];
+    active?: boolean;
+    agent?: string;
+    claude?: boolean;
+    codex?: boolean;
+    kimi?: boolean;
+    antigravity?: boolean;
+    grok?: boolean;
+    opencode?: boolean;
+    all?: boolean;
+    teams?: boolean;
+    inTeam?: string;
+    routine?: boolean;
+    project?: string;
+    skill?: string;
+    plugin?: string;
+    since?: string;
+    until?: string;
+    limit?: string;
+    favorites?: boolean;
+    unmanaged?: boolean;
+    sort?: string;
     working?: boolean;
     idle?: boolean;
     waiting?: boolean;
@@ -35,6 +56,10 @@ export interface FocusOptions {
     queued?: boolean;
     unknown?: boolean;
 }
+/** Commander gives overlapping `sessions` flags to the parent command, even
+ * when they appear after `focus`. Fold only values explicitly provided there
+ * into the child options; child defaults (limit/sort) otherwise stay intact. */
+export declare function inheritFocusOptions(child: FocusOptions, parent?: Command): FocusOptions;
 /** `--device` is an alias of `--host`; both are repeatable. Merge into one host list. */
 export declare function mergeFocusHosts(opts: FocusOptions): string[];
 /** Picker header that reflects the active filter + device, e.g. "Focus orphaned sessions on yosemite-s0:". */
@@ -85,7 +110,7 @@ export declare function tmuxAttachScript(mux: {
  * `resumeCommandFor` resolver (injected so the local version-pinned resume command
  * and the tests stay decoupled from `discoverSessions`).
  */
-export declare function planFocusSurface(s: ActiveSession, self: string, resumeCommandFor: (s: ActiveSession) => string[] | null): FocusSurfacePlan;
+export declare function planFocusSurface(s: ActiveSession, self: string, resumeCommandFor: (s: ActiveSession) => string[] | null, rail?: AttachRailLiveness): FocusSurfacePlan;
 /** The engine seam — real `openSurfaces`, overridable in tests to assert the tab requests. */
 export type OpenSurfacesFn = typeof openSurfaces;
 /** Test seams for `openFocusTabs`: inject the engine boundary + force a backend. */
@@ -93,6 +118,12 @@ export interface OpenFocusTabsDeps {
     open?: OpenSurfacesFn;
     /** Skip `resolveBackend` (which needs a live terminal) when set — tests pass 'tmux'. */
     backend?: Backend | 'inplace';
+    /** Rich rows selected by the shared browser pipeline (including remote history). */
+    metas?: SessionMeta[];
+    /** Liveness boundary; production probes tmux, tests exercise planning deterministically. */
+    probe?: typeof probeAttachRail;
+    /** Strict focus mode: open living attach rails only; never recover a copy. */
+    attachOnly?: boolean;
 }
 /**
  * Open each selected live session as a tab: attach its live pane where one exists,

package/dist/commands/focus.js

@@ -15,15 +15,42 @@
 import fs from 'node:fs';
 import chalk from 'chalk';
 import { confirm } from '@inquirer/prompts';
-import { gatherLiveTargets, pickLiveTarget, pickLiveTargets, jumpTo, refuseFallback } from './go.js';
-import { requestedLiveStatuses, resolveSessionMetadataValue } from './sessions.js';
-import { resolveBackend, CONFIRM_THRESHOLD, resumeSelectorInPlace } from './sessions-resume.js';
+import { gatherLiveTargets, pickLiveTarget, pickLiveTargets, jumpTo, probeAttachRail, refuseFallback } from './go.js';
+import { buildSessionRecoveryCommand, filterSessionsByQuery, formatLiveStatusHeadline, formatPickerLabel, pickerColumnsFor, resumeSessionInPlace, resolveSessionMetadataValue, resolveSessionAgentName, requestedLiveStatuses, } from './sessions.js';
+import { resolveBackend, CONFIRM_THRESHOLD } from './sessions-resume.js';
+import { runOnPeer } from '../lib/session/remote-list.js';
 import { discoverSessions } from '../lib/session/discover.js';
+import { collectSessionCandidates, normalizeDeviceSeed } from './sessions-browser.js';
+import { buildPreview } from './sessions-picker.js';
+import { multiItemPicker } from '../lib/picker.js';
+import { sessionRecoveryRunArgs } from '../lib/session/recovery.js';
 import { shellQuote, assertValidSshTarget } from '../lib/ssh-exec.js';
 import { openSurfaces, currentContext, availableBackends, detectCurrentBackend, } from '../lib/terminal/index.js';
-import { isInteractiveTerminal } from './utils.js';
+import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { setHelpSections } from '../lib/help.js';
-import { buildCanonicalResumeCommand } from '../lib/session/resume-command.js';
+const INHERITED_FOCUS_OPTIONS = [
+    'local', 'host', 'device', 'active', 'agent',
+    'claude', 'codex', 'kimi', 'antigravity', 'grok', 'opencode',
+    'all', 'teams', 'inTeam', 'routine', 'project', 'skill', 'plugin',
+    'since', 'until', 'limit', 'favorites', 'unmanaged', 'sort',
+    'working', 'idle', 'waiting', 'orphan', 'orphaned', 'crashed',
+    'closed', 'abandoned', 'queued', 'unknown',
+];
+/** Commander gives overlapping `sessions` flags to the parent command, even
+ * when they appear after `focus`. Fold only values explicitly provided there
+ * into the child options; child defaults (limit/sort) otherwise stay intact. */
+export function inheritFocusOptions(child, parent) {
+    if (!parent)
+        return child;
+    const merged = { ...child };
+    for (const key of INHERITED_FOCUS_OPTIONS) {
+        const source = parent.getOptionValueSource(String(key));
+        if (source && source !== 'default') {
+            merged[key] = parent.getOptionValue(String(key));
+        }
+    }
+    return merged;
+}
 /** `--device` is an alias of `--host`; both are repeatable. Merge into one host list. */
 export function mergeFocusHosts(opts) {
     return [...(opts.host ?? []), ...(opts.device ?? [])];
@@ -43,11 +70,32 @@ function statusWord(status) {
 export function registerFocusCommand(program) {
     const cmd = program
         .command('focus')
-        .argument('[id]', 'Short/full session id to focus; omit for an interactive picker')
+        .argument('[selector]', 'Session id/prefix, agent@version, or topic/path search')
         .option('--local', 'Only this machine (skip the cross-host sweep)')
         .option('--attach-only', 'Attach only — never open a new tab / resume a copy (the old `go` behavior)')
         .option('-H, --host <target...>', 'Scope the picker to live sessions on these devices (host alias or user@host; repeatable)')
         .option('--device <target...>', 'Alias for --host (device alias from `agents devices`; repeatable)')
+        .option('--active', 'Only sessions present in the live roster')
+        .option('-a, --agent <agent>', 'Filter by harness and recorded version (for example claude@latest)')
+        .option('--claude', 'Shorthand for --agent claude')
+        .option('--codex', 'Shorthand for --agent codex')
+        .option('--kimi', 'Shorthand for --agent kimi')
+        .option('--antigravity', 'Shorthand for --agent antigravity')
+        .option('--grok', 'Shorthand for --agent grok')
+        .option('--opencode', 'Shorthand for --agent opencode')
+        .option('--all', 'Include every directory and all time')
+        .option('--teams', 'Include team-spawned sessions')
+        .option('--in-team <name>', 'Only one team lineage')
+        .option('--routine', 'Only routine-run sessions')
+        .option('-p, --project <name>', 'Only a named project')
+        .option('--skill <name>', 'Only sessions that invoked this skill')
+        .option('--plugin <name>', 'Only sessions that used this plugin')
+        .option('--since <time>', 'Only sessions newer than this (for example 7d)')
+        .option('--until <time>', 'Only sessions older than this timestamp')
+        .option('-n, --limit <n>', 'Maximum candidates to load', '500')
+        .option('--favorites', 'Only favorited sessions')
+        .option('--unmanaged', 'Also include native-home sessions outside managed versions')
+        .option('--sort <field>', 'Order candidates by recent, cost, or duration', 'recent')
         .option('--working', 'Only live sessions currently doing work')
         .option('--idle', 'Only live sessions that have stopped between turns')
         .option('--waiting', 'Only live sessions waiting on your input')
@@ -58,13 +106,13 @@ export function registerFocusCommand(program) {
         .option('--abandoned', 'Only sessions with no transcript progress for the abandonment window')
         .option('--queued', 'Only queued sessions that have not started running')
         .option('--unknown', 'Only sessions whose live state cannot be determined')
-        .description('Focus live sessions — multi-select and open each as a tab (attach its pane, or resume a copy)')
-        .action(async (id, opts) => {
-        await focusAction(id, opts);
+        .description('Focus sessions by id, harness/version, topic, device, or live state; attach living panes and recover ended ones')
+        .action(async (id, opts, command) => {
+        await focusAction(id, inheritFocusOptions(opts, command.parent ?? undefined));
     });
     setHelpSections(cmd, {
         examples: `
-      # Jump to a live session (attach pane/tab, or open a new tab and resume)
+      # Focus a session directly (attach a living pane, otherwise recover it)
       agents sessions focus a1b2c3d4
 
       # Multi-select live sessions; each opens as a tab in this terminal
@@ -73,6 +121,9 @@ export function registerFocusCommand(program) {
       # Scope the picker to one device's orphaned sessions
       agents sessions focus --orphan --device yosemite-s0
 
+      # Resolve latest on yosemite-s0, then pick from that version's sessions
+      agents sessions focus claude@latest --device yosemite-s0
+
       # Attach only — refuse if nothing is joinable (old sessions go)
       agents sessions focus a1b2c3d4 --attach-only
 
@@ -81,11 +132,11 @@ export function registerFocusCommand(program) {
     `,
         notes: `
       - space toggles a session, enter opens the selected set; a single check + enter opens just one.
-      - Each selected session opens as a new tab in the terminal you're in (Ghostty / iTerm / tmux, auto-detected).
-      - A live tmux session is JOINED in the tab (a second client, no fork) — local or remote over SSH; a session with no attach rail resumes a copy in the tab, reported never silently dropped.
-      - --host/--device scopes the pool to those devices; the live-state filters (--orphan/--crashed/…) narrow by status and compose with the device scope.
+      - With no selector/filter, the picker shows the live fleet. An id focuses directly; agent@version and text selectors always show the preview picker.
+      - A living tmux pane is JOINED (a second client, no fork). Dead/missing panes recover on the origin device: exact healthy origin uses native resume; otherwise a healthy version of the same harness receives /continue <id>.
+      - --host/--device and the sessions-browser filters compose. latest/oldest resolve against each selected device's installed versions.
       Lifecycle siblings (not synonyms):
-        focus              live jump (default "take me there")
+        focus              attach if alive, otherwise recover (default "take me there")
         focus --attach-only  attach only; never fork (replaces go)
         detach / attach    interactive ↔ headless presence
         resume             multi-select history → tabs
@@ -106,38 +157,98 @@ export async function focusAction(id, opts) {
     const statuses = requestedLiveStatuses(opts);
     // A device scope needs the cross-host sweep; --local only wins when no host is named.
     const local = !!opts.local && hosts.length === 0;
-    const { self, activeById } = await gatherLiveTargets(local, { hosts, statuses });
     const fallback = selectFallback(opts.attachOnly);
-    if (id) {
-        const outcome = await resolveSessionMetadataValue(id.trim(), { local, hosts });
-        if (outcome.kind === 'partial') {
-            console.error(chalk.red(`Could not resolve session while these devices were unavailable: ${outcome.failedPeers.join(', ')}`));
-            process.exitCode = 2;
+    const agentSelector = focusAgentSelector(id, opts);
+    const textSelector = id && !agentSelector ? id : undefined;
+    const filtered = !!id || hasFocusFilters(opts, statuses);
+    // Preserve the fast live multi-picker for an unqualified `focus`. Every
+    // selector/filter path below uses the sessions browser's shared candidate
+    // pipeline and rich preview.
+    if (filtered) {
+        if (!isInteractiveTerminal() && !looksLikeIdentitySelector(textSelector)) {
+            console.error(chalk.red('focus selectors need an interactive terminal; pass a session id for direct focus.'));
+            process.exitCode = 1;
             return;
         }
-        if (outcome.kind === 'ambiguous') {
-            console.error(chalk.red(`"${id}" matches ${outcome.candidates.length} sessions. Pass a longer id or alias.`));
+        const limit = Number.parseInt(opts.limit ?? '500', 10);
+        const idLookup = looksLikeIdentitySelector(textSelector);
+        const sort = focusSort(opts.sort);
+        if (!sort) {
+            console.error(chalk.red(`Invalid sort: ${opts.sort}. Use recent, cost, or duration.`));
             process.exitCode = 1;
             return;
         }
-        if (outcome.kind === 'not-found') {
-            console.error(chalk.red(`No session matching "${id}".`));
-            process.exitCode = 1;
+        const { sessions, liveById, self, unreachable } = await collectSessionCandidates({
+            running: opts.active === true || statuses.length > 0,
+            statuses,
+            agent: agentSelector ?? focusOptionAgent(opts),
+            teams: opts.teams === true,
+            team: opts.inTeam,
+            favorites: opts.favorites === true,
+            projectScope: opts.all || hosts.length > 0 || !!opts.project || idLookup ? 'all' : 'repo',
+            project: opts.project,
+            window: opts.since ?? (opts.all || idLookup ? undefined : '30d'),
+            until: opts.until,
+            routine: opts.routine === true,
+            skill: opts.skill,
+            plugin: opts.plugin,
+            limit: idLookup && limit === 500 ? 5000 : (Number.isFinite(limit) && limit > 0 ? limit : 500),
+            unmanaged: opts.unmanaged === true,
+            sort,
+            device: hosts.length === 1 ? normalizeDeviceSeed(hosts[0]) : undefined,
+        }, { local, hosts, includeLive: true });
+        if (unreachable.length > 0) {
+            console.error(chalk.yellow(`Unavailable devices: ${unreachable.join(', ')}`));
+        }
+        let exact = textSelector && looksLikeIdSelector(textSelector)
+            ? sessions.filter((session) => session.id.toLowerCase().startsWith(textSelector.toLowerCase()))
+            : [];
+        if (exact.length === 0 && textSelector && looksLikeIdentitySelector(textSelector)) {
+            const outcome = await resolveSessionMetadataValue(textSelector, { local, hosts });
+            if (outcome.kind === 'partial') {
+                console.error(chalk.red(`Could not resolve session while these devices were unavailable: ${outcome.failedPeers.join(', ')}`));
+                process.exitCode = 2;
+                return;
+            }
+            if (outcome.kind === 'ambiguous') {
+                console.error(chalk.red(`"${textSelector}" matches ${outcome.candidates.length} sessions. Pass a longer id or alias.`));
+                process.exitCode = 1;
+                return;
+            }
+            if (outcome.kind === 'not-found') {
+                console.error(chalk.red(`No session matching "${textSelector}".`));
+                process.exitCode = 1;
+                return;
+            }
+            const filteredMatch = sessions.find((session) => session.id === outcome.session.id);
+            if (!filteredMatch) {
+                console.error(chalk.red(`Session ${outcome.session.shortId} does not match the selected focus filters.`));
+                process.exitCode = 1;
+                return;
+            }
+            exact = [filteredMatch];
+        }
+        if (exact.length === 1) {
+            await focusResolvedSession(exact[0], liveById, self, fallback, opts.attachOnly === true);
             return;
         }
-        const live = activeById.get(outcome.session.id);
-        if (live && isAttachableLiveSession(live)) {
-            await jumpTo(live, self, fallback);
+        if (exact.length > 1) {
+            console.error(chalk.red(`"${textSelector}" is ambiguous (${exact.length} sessions). Use more of the id.`));
+            process.exitCode = 1;
             return;
         }
-        if (opts.attachOnly) {
-            console.error(chalk.red(`${outcome.session.shortId} has no live terminal to attach.`));
+        if (!isInteractiveTerminal()) {
+            console.error(chalk.red(`No session matching "${textSelector}" in the selected scope.`));
             process.exitCode = 1;
             return;
         }
-        await recoverResolvedSession(outcome.session);
+        const chosen = await pickFocusCandidates(sessions, liveById, textSelector);
+        if (chosen.length === 0)
+            return;
+        await openFocusTabs(chosen.map((meta) => liveById.get(meta.id) ?? activeFromMeta(meta)), self, { metas: chosen, attachOnly: opts.attachOnly === true });
         return;
     }
+    const { self, activeById } = await gatherLiveTargets(local, { hosts, statuses });
     if (!isInteractiveTerminal()) {
         console.error(chalk.red('focus needs an interactive terminal, or pass a session id.'));
         process.exitCode = 1;
@@ -167,21 +278,110 @@ export async function focusAction(id, opts) {
 export function isAttachableLiveSession(session) {
     return session.pidAlive !== false && session.status !== 'closed' && session.status !== 'crashed';
 }
-async function recoverResolvedSession(session) {
-    const command = buildCanonicalResumeCommand(session.id);
-    const cwd = session.cwd && fs.existsSync(session.cwd) ? session.cwd : process.cwd();
-    const ctx = currentContext();
-    const backend = detectCurrentBackend(ctx) ?? availableBackends(ctx)[0]?.id;
-    if (!backend) {
-        await resumeSelectorInPlace(session.id);
+const FOCUS_AGENT_SHORTHANDS = ['claude', 'codex', 'kimi', 'antigravity', 'grok', 'opencode'];
+function focusOptionAgent(opts) {
+    if (opts.agent)
+        return opts.agent;
+    return FOCUS_AGENT_SHORTHANDS.find((agent) => opts[agent] === true);
+}
+function focusAgentSelector(selector, opts) {
+    const candidate = selector ?? focusOptionAgent(opts);
+    if (!candidate)
+        return undefined;
+    const [name, version] = candidate.split('@', 2);
+    const agent = resolveSessionAgentName(name);
+    if (!agent)
+        return undefined;
+    return version === undefined ? agent : `${agent}@${version}`;
+}
+function looksLikeIdSelector(selector) {
+    return !!selector && /^[0-9a-f][0-9a-f-]{5,}$/i.test(selector);
+}
+function looksLikeIdentitySelector(selector) {
+    return !!selector && (/^[0-9a-f][0-9a-f-]{5,}$/i.test(selector) ||
+        /^ag-[a-z][a-z0-9-]*-[0-9a-f]{8}$/i.test(selector));
+}
+function hasFocusFilters(opts, statuses) {
+    return statuses.length > 0 || !!(opts.active || opts.local || opts.host?.length || opts.device?.length || focusOptionAgent(opts) ||
+        opts.all || opts.teams || opts.inTeam || opts.routine || opts.project || opts.skill || opts.plugin ||
+        opts.since || opts.until || opts.favorites || opts.unmanaged || (opts.sort && opts.sort !== 'recent'));
+}
+function focusSort(value) {
+    if (!value || value === 'recent')
+        return 'timestamp';
+    return value === 'cost' || value === 'duration' ? value : null;
+}
+async function pickFocusCandidates(sessions, liveById, initialSearch) {
+    if (sessions.length === 0) {
+        console.log(chalk.gray('No sessions match the focus filters.'));
+        return [];
+    }
+    const cols = {
+        ...pickerColumnsFor(sessions),
+        gutter: 6,
+        showStatus: liveById.size > 0,
+        showHost: liveById.size > 0,
+    };
+    try {
+        const chosen = await multiItemPicker({
+            message: 'Focus sessions:',
+            items: sessions,
+            filter: (query) => query.trim() ? filterSessionsByQuery(sessions, query) : sessions,
+            labelFor: (session, query) => formatPickerLabel(session, query, cols, undefined, liveById.get(session.id)?.host, false, liveById.get(session.id)),
+            keyFor: (session) => session.id,
+            buildPreview: (session) => {
+                const headline = formatLiveStatusHeadline(liveById.get(session.id));
+                const preview = buildPreview(session);
+                return headline ? `${headline}\n${preview}` : preview;
+            },
+            pageSize: 15,
+            initialSearch,
+            emptyMessage: 'No sessions match.',
+            enterHint: 'focus',
+        });
+        return chosen ?? [];
+    }
+    catch (err) {
+        if (isPromptCancelled(err))
+            return [];
+        throw err;
+    }
+}
+async function focusResolvedSession(meta, liveById, self, fallback, attachOnly) {
+    const active = liveById.get(meta.id);
+    if (active && isAttachableLiveSession(active)) {
+        await jumpTo(active, self, fallback);
         return;
     }
-    console.log(chalk.gray(`${session.shortId} is not live — opening a ${backend} tab and resuming it.`));
-    const [result] = await openSurfaces([{ cwd, command }], { backend, packing: 'tabs' });
-    if (!result?.ok) {
-        console.error(chalk.red(`Failed to open ${session.shortId}: ${result?.error ?? 'unknown error'}`));
+    if (attachOnly) {
+        console.log(chalk.yellow(`${meta.shortId} has no living process or pane to attach.`));
         process.exitCode = 1;
+        return;
+    }
+    const remote = meta.machine && meta.machine !== self ? meta.machine : undefined;
+    if (remote) {
+        console.log(chalk.gray(`Recovering ${meta.shortId} on ${remote}…`));
+        const rc = await runOnPeer(sessionRecoveryRunArgs(meta), remote, { tty: true });
+        if (rc === 'no-target') {
+            console.error(chalk.red(`Cannot recover ${meta.shortId}: ${remote} is unreachable.`));
+            process.exitCode = 1;
+        }
+        return;
     }
+    await resumeSessionInPlace(meta);
+}
+function activeFromMeta(meta) {
+    return {
+        context: 'headless',
+        kind: meta.agent,
+        sessionId: meta.id,
+        cwd: meta.cwd,
+        project: meta.project,
+        topic: meta.topic,
+        startedAtMs: Date.parse(meta.timestamp),
+        status: 'closed',
+        machine: meta.machine,
+    };
 }
 /** Human scope suffix for the empty-pool message, e.g. " (orphaned on yosemite-s0)". */
 function describeScope(statuses, hosts) {
@@ -201,7 +401,9 @@ function describeScope(statuses, hosts) {
 export function tmuxAttachScript(mux) {
     const sock = mux.socket ? `-S ${shellQuote(mux.socket)} ` : '';
     const p = shellQuote(mux.pane);
-    return (`sess=$(tmux ${sock}display-message -pt ${p} '#{session_name}' 2>/dev/null); ` +
+    return (`dead=$(tmux ${sock}display-message -pt ${p} -p '#{pane_dead}' 2>/dev/null) || { echo 'agents: tmux pane is missing'; exit 42; }; ` +
+        `[ "$dead" = 0 ] || { echo 'agents: tmux pane is dead'; exit 42; }; ` +
+        `sess=$(tmux ${sock}display-message -pt ${p} '#{session_name}' 2>/dev/null); ` +
         `exec tmux ${sock}attach-session -t "\${sess:-${p}}"`);
 }
 /**
@@ -209,13 +411,13 @@ export function tmuxAttachScript(mux) {
  * `resumeCommandFor` resolver (injected so the local version-pinned resume command
  * and the tests stay decoupled from `discoverSessions`).
  */
-export function planFocusSurface(s, self, resumeCommandFor) {
+export function planFocusSurface(s, self, resumeCommandFor, rail = { state: 'alive' }) {
     const remote = s.machine && s.machine !== self ? s.machine : undefined;
     const mux = s.provenance?.mux;
     const sid = shortId(s);
     // Join rail = tmux only (local or remote over SSH). A new tab attaching the live
     // tmux session is a second client: join, no fork.
-    if (mux?.kind === 'tmux' && mux.pane) {
+    if (mux?.kind === 'tmux' && mux.pane && rail.state === 'alive') {
         const script = tmuxAttachScript({ socket: mux.socket, pane: mux.pane });
         if (remote) {
             assertValidSshTarget(remote);
@@ -227,7 +429,20 @@ export function planFocusSurface(s, self, resumeCommandFor) {
         }
         return { kind: 'attach', command: ['sh', '-c', shellQuote(script)], note: `attach ${mux.pane}` };
     }
-    // No join rail → the canonical command resolves the owner device itself.
+    // No join rail → resume a copy (never a silent drop).
+    if (remote) {
+        // Recover ON the peer so health and installed versions are resolved where
+        // the transcript actually originated.
+        const command = resumeCommandFor(s);
+        if (!command)
+            return { kind: 'skip', note: `${sid} has no recovery command` };
+        assertValidSshTarget(remote);
+        return {
+            kind: 'resume',
+            command: ['ssh', '-tt', remote, shellQuote(command.map(shellQuote).join(' '))],
+            note: `recover on ${remote} (no living tmux pane to join)`,
+        };
+    }
     const cmd = resumeCommandFor(s);
     if (!cmd)
         return { kind: 'skip', note: `${sid} — ${s.kind} sessions can't be resumed, and it has no live tmux to join` };
@@ -239,11 +454,27 @@ export function planFocusSurface(s, self, resumeCommandFor) {
  */
 export async function openFocusTabs(targets, self, deps = {}) {
     const open = deps.open ?? openSurfaces;
-    // The canonical resume command resolves metadata itself; active cwd is enough
-    // to place the terminal without another transcript scan.
-    const byId = new Map();
-    const resumeCommandFor = (s) => s.sessionId ? buildCanonicalResumeCommand(s.sessionId) : null;
-    const planned = targets.map((s) => ({ s, plan: planFocusSurface(s, self, resumeCommandFor) }));
+    const probe = deps.probe ?? probeAttachRail;
+    // Resolve rich indexed metas ONCE so local resume commands stay version-pinned.
+    let byId = new Map((deps.metas ?? []).map((m) => [m.id, m]));
+    if (!deps.metas) {
+        try {
+            const metas = await discoverSessions({ all: true, since: '90d', limit: 2000 });
+            byId = new Map(metas.map((m) => [m.id, m]));
+        }
+        catch { /* fall back to synthesized metas per session */ }
+    }
+    const metaFor = (s) => byId.get(s.sessionId ?? '') ?? metaFromActive(s);
+    const resumeCommandFor = (s) => {
+        if (deps.attachOnly)
+            return null;
+        const remote = !!s.machine && s.machine !== self;
+        return buildSessionRecoveryCommand(metaFor(s), remote);
+    };
+    const planned = await Promise.all(targets.map(async (s) => {
+        const rail = await probe(s, self);
+        return { s, plan: planFocusSurface(s, self, resumeCommandFor, rail) };
+    }));
     // Skips are reported, never silently dropped.
     for (const p of planned)
         if (p.plan.kind === 'skip')
@@ -268,7 +499,7 @@ export async function openFocusTabs(targets, self, deps = {}) {
         if (openable.length > 1) {
             console.log(chalk.yellow(`This terminal can't open tabs — jumping to the first; open in Ghostty/iTerm/tmux to focus several at once.`));
         }
-        await jumpTo(openable[0].s, self, selectFallback(false));
+        await jumpTo(openable[0].s, self, selectFallback(deps.attachOnly));
         return;
     }
     console.log(chalk.gray(`Opening ${openable.length} session${openable.length === 1 ? '' : 's'} in ${backend} (tabs)…`));
@@ -323,21 +554,34 @@ async function richMetaById(id) {
  * Note: for a session that's still mid-run, this opens a COPY (the original keeps going);
  * only tmux can *join* a live one without forking (see the header).
  */
-const resumeInNewTab = async (s) => {
+const resumeInNewTab = async (s, remote) => {
     const id = s.sessionId ?? '';
     if (!id) {
         console.log(chalk.yellow('This session has no id to resume.'));
         return;
     }
-    // The canonical command resolves the source device and pinned launch metadata.
+    // Remote: the transcript + pinned version live on the peer, so resume THERE over SSH.
+    // runOnPeer runs `agents sessions resume <id>` with a real TTY (`-tt`) in the foreground —
+    // it actually delivers you to the session (the peer picks the right version + HOME).
+    if (remote) {
+        console.log(chalk.gray(`${shortId(s)} has no live terminal on ${remote} — resuming it there over SSH…`));
+        const rc = await runOnPeer(sessionRecoveryRunArgs({ id }), remote, { tty: true });
+        if (rc === 'no-target') {
+            console.log(chalk.red(`${remote} isn't reachable as a device. Try: agents devices sync`));
+            console.log(chalk.gray(`  recovery must run on ${remote}, where the indexed session originated`));
+        }
+        return;
+    }
+    // Local: resume in a new tab. Use the indexed meta so the version-pinned binary
+    // resumes in the same isolated HOME the transcript was written in.
     const meta = (await richMetaById(id)) ?? metaFromActive(s);
-    const command = buildCanonicalResumeCommand(meta.id);
+    const command = buildSessionRecoveryCommand(meta);
     const cwd = meta.cwd && fs.existsSync(meta.cwd) ? meta.cwd : process.cwd();
     const ctx = currentContext();
     const backend = detectCurrentBackend(ctx) ?? availableBackends(ctx)[0]?.id;
     if (!backend) {
         // No tab-capable surface (off-macOS, not in tmux) — resume in this process.
-        await resumeSelectorInPlace(meta.id);
+        await resumeSessionInPlace(meta);
         return;
     }
     console.log(chalk.gray(`${shortId(s)} has no live terminal to attach — opening a new ${backend} tab and resuming a copy.`));

package/dist/commands/go.d.ts

@@ -78,6 +78,19 @@ export declare function describeWhere(s: ActiveSession, self: string): Where;
  * the session lives on another machine, else undefined.
  */
 export type UnreachableFallback = (s: ActiveSession, remote: string | undefined) => void | Promise<void>;
-/** Default (attach-only): open a login shell on the remote, or refuse locally. */
+export type AttachRailLiveness = {
+    state: 'alive';
+} | {
+    state: 'dead';
+    exitStatus?: number;
+} | {
+    state: 'missing';
+};
+/** Probe the tmux process, not just retained provenance. This is deliberately
+ * called immediately before an attach so remain-on-exit panes cannot masquerade
+ * as living agent sessions. */
+export declare function probeAttachRail(s: ActiveSession, self: string): Promise<AttachRailLiveness>;
+/** Strict attach-only fallback: no pane means no attach. Never open a shell or
+ * start recovery, because both would violate the caller's no-fork intent. */
 export declare function refuseFallback(s: ActiveSession, remote: string | undefined): Promise<void>;
 export declare function jumpTo(s: ActiveSession, self: string, fallback?: UnreachableFallback): Promise<void>;