@phnx-labs/agents-cli 1.20.40 → 1.20.42

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## Unreleased
 
+## 1.20.42
+
+- **Fix: exiting a split pane inside an interactive `ag run` session kicked you out of tmux entirely.** When you split the window of an interactive agent session (`ag run claude`) with Ctrl-b `"`/`%` and then `exit`ed *your* split, the whole tmux client detached and dumped you back to the parent shell — even though the agent was still running in the other pane. Cause: `runInTmux` installed a session-wide `pane-died` hook (`detach-client`) meant to fire only when the AGENT pane exits (so the attach returns and the exit status is read), but with no `#{hook_pane}` guard it fired for *any* pane's death. The hook is now scoped to the agent pane; a user split that exits is closed in place (`kill-pane`, no lingering dead husk) and the agent keeps running full-window. Source: `apps/cli/src/lib/exec.ts`, `apps/cli/src/lib/tmux/session.test.ts`.
+- **Every secret-value read is now audited, not just the ones that flowed through the resolver.** `agents events --module secrets` (or `--event secrets.get`) is meant to show "every secret accessed or revealed", but several paths read plaintext values without going through `readAndResolveBundleEnv` (the only place that emitted `secrets.get`), so they were invisible: `secrets push` (which reads the whole bundle to upload it — the most sensitive silent read), `secrets view --reveal`, the raw `secrets get <item>`, `secrets set <item>` (a raw write, no `secrets.set`), and the *initiating* side of `secrets exec --host` / `run --secrets bundle@host` (only the remote host logged it). Each now emits with a `source` telling you HOW it was read — `keychain`, `agent` (served from the unlocked broker), `reveal`, `raw-item`, `sync-push`, or `remote` (with the target `host`) — alongside the bundle, caller, keyCount, and OS-user/host/transport. The resolved **value is never written to the log**, only names and counts. All `secrets.*` events are now tagged `module: 'secrets'` so `--module secrets` actually surfaces the value reads (previously it matched only the coarse command events). Note: the event log has a 7-day retention, so export what you need for long-term records. Source: `src/lib/secrets/bundles.ts`, `src/lib/secrets/sync.ts`, `src/lib/secrets/remote.ts`, `src/commands/secrets.ts`, `docs/06-observability.md`.
+- **Fix: `sessions --active` showed the SAME preview + topic for every co-located session.** Multiple Claude sessions in one cwd (e.g. several editor tabs, or two worktree siblings) all rendered identical activity — they looked like duplicate cards. `findClaudeSessionFile` fell back to the newest `.jsonl` in the cwd whenever a session's `<id>.jsonl` wasn't found, so every distinct session collapsed onto ONE file's preview/topic. The stale-id trigger: an editor caches the launch uuid in `live-terminals.json`, but Claude rotates its transcript uuid on resume/compact, so the cached id no longer matches any file. Now the terminal path resolves each tab's EXACT id from the pid registry (mirroring the headless path), the newest-file fallback is gated to the no-id case (`pickSessionFile`), and an unresolvable file reads as `idle` rather than `running`. Source: `apps/cli/src/lib/session/active.ts`.
+- **Fix: one malformed Kimi session blanked the WHOLE `agents sessions` listing.** A Kimi `state.json` with neither `createdAt` nor `updatedAt` made `readKimiMeta` return an `undefined` timestamp, which binds `NULL` into the `timestamp TEXT NOT NULL` column and aborts the entire batch index — so a single bad session took down the listing for every session, not just itself. Two layers: `readKimiMeta` now coerces the timestamp to never-null, falling back to the `state.json` mtime (matching how the listing already ranks Kimi via `last_activity`, like every other parser); and `upsertSessionsBatch` wraps each row in a per-row guard so a future constraint-violating row skips itself (ledger deliberately not stamped, so the next scan re-tries it) instead of rolling back the whole batch. Source: `apps/cli/src/lib/session/discover.ts`, `apps/cli/src/lib/session/db.ts`.
+
+## 1.20.41
+
+- **NEW: `agents sessions focus [id]`** — one command to get back to a session, however it's reachable. It **attaches** a live session in place (tmux `switch-client`/`attach-session`, a remote tmux over `ssh -tt`, or a Ghostty tab — joining the live process without forking); where there's **no live terminal to attach**, it **opens a new tab and resumes** the session — locally, or on the remote peer over SSH (`runOnPeer`, so the peer resolves the version-pinned binary). No id opens the rich live-session picker (this-machine first). Reuses the live-session detection and the terminal launch engine (`openSurfaces`), and folds `go`'s attach paths in. Source: `src/commands/focus.ts`, `src/commands/go.ts`.
+- **`--device` is now a first-class alias of `--host`** on every host-routable command (`sessions`, `run`, …), registered centrally on `addHostOption` so a local fall-through no longer errors. Source: `src/lib/hosts/`.
+- **`agents computer` steers Electron/webview targets over CDP** instead of reporting a fake success when the native-automation path can't reach them (#716).
+- **Secrets: the "remember" policy hold now lasts 7 days and survives screen-lock**, instead of re-prompting after every lock/sleep; stale copies are evicted when a policy is tightened. Source: `src/lib/secrets/`.
+- **Fixes:** shim `machine_id()` normalizes to match `normalizeHost()`, and shim resolution honors the per-device default pin (not just the central `agents.yaml`).
+- **`agents sessions go` is retired as a deprecated alias for `agents sessions focus --attach-only`.** `go` was already a strict subset of `focus` — its only unique behavior was "attach the live terminal or refuse, never fork/resume." That behavior is now a first-class `--attach-only` flag on `focus` (`focus.ts`: `selectFallback()` picks `refuseFallback` under `--attach-only`, else the resume-in-a-new-tab fallback). `go` now prints a one-line deprecation notice and delegates to `focusAction(id, { attachOnly: true })`; the shared reach engine (`jumpTo`/`gatherLiveTargets`/`pickLiveTarget`/`refuseFallback`) still lives in `go.ts` and is imported by `focus.ts`. Source: `src/commands/go.ts`, `src/commands/focus.ts`.
+- **`agents sessions --json --host <h>` now emits a clean JSON array** of recent (non-active) sessions instead of the legacy per-host raw banner stream, so a UI can fetch a remote device's recent sessions when it has no live agents. `serializeSessionsJson()` is shared by the local and remote `--json` paths; `runRemoteSessionsJson()` reuses the existing `gatherRemoteList` SSH fan-out. The non-JSON banner path and `--active` are unchanged (#711).
+
 ## 1.20.36
 
 **[windows] `agents sessions --active` detects sessions on Windows, and shim launches carry cwd + session identity everywhere**

package/dist/commands/computer-actions.d.ts

@@ -80,4 +80,6 @@ export declare function shouldRaise(opts: {
     id?: string;
     raise?: boolean;
 }): boolean;
+export declare function appPathIsElectron(appPath: string | null, exists?: (p: string) => boolean): boolean;
+export declare function electronWebviewTip(appLabel: string): string;
 export declare function registerActionCommands(program: Command): void;

package/dist/commands/computer-actions.js

@@ -6,6 +6,7 @@
 // The daemon already implements every method; this file is the thin, typed
 // CLI skin over it plus a shared target resolver so callers stay in bundle-id
 // space and never hand-manage pids.
+import { execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import { openComputerClient, describeTransport, resolvePolicyPath, } from '../lib/computer-rpc.js';
@@ -199,7 +200,7 @@ function warnIfNotFrontmost(res) {
     }
 }
 function reportMissingHelper() {
-    console.error('helper not built. Run: ./packages/computer-helper/scripts/build.sh debug');
+    console.error('helper not built. Run: ./native/computer-mac/scripts/build.sh debug');
     process.exit(1);
 }
 // Open a client, run fn, always close. Fails fast if no helper is present.
@@ -288,6 +289,59 @@ async function applyFocusPolicy(client, pid, opts) {
     if (shouldRaise(opts))
         unwrap(await client.call('focus_window', { pid }));
 }
+// Electron/webview steering. macOS accepts an AX action (AXPress / set-AXValue)
+// on an Electron/Chromium window, but it does NOT run the web app's real DOM
+// handlers — React ignores it — so a reported `clicked`/`typed` on a webview can
+// be a silent no-op. Detect Electron targets and steer the caller to CDP
+// (`agents browser --electron`), which drives the webview for real. We warn, not
+// block: the caller may still want the raw action (e.g. to focus + coordinate).
+const electronCache = new Map();
+// Resolve a bundle id to its .app path via Spotlight. Best-effort; null on miss.
+function appPathForBundle(bundleId) {
+    try {
+        const out = execFileSync('mdfind', [`kMDItemCFBundleIdentifier == '${bundleId}'`], {
+            encoding: 'utf-8',
+            timeout: 3000,
+        });
+        return out.split('\n').map((s) => s.trim()).find((s) => s.endsWith('.app')) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+// Pure + unit-tested: does the .app at this path bundle the Electron framework?
+export function appPathIsElectron(appPath, exists = fs.existsSync) {
+    if (!appPath)
+        return false;
+    return exists(path.join(appPath, 'Contents', 'Frameworks', 'Electron Framework.framework'));
+}
+// Is the app for this bundle id an Electron/webview app? macOS-only; memoized so
+// the mdfind lookup runs at most once per bundle id per process.
+function isElectronApp(bundleId) {
+    if (!bundleId || process.platform !== 'darwin')
+        return false;
+    const cached = electronCache.get(bundleId);
+    if (cached !== undefined)
+        return cached;
+    const result = appPathIsElectron(appPathForBundle(bundleId));
+    electronCache.set(bundleId, result);
+    return result;
+}
+// Pure + unit-tested: the CDP-steer note printed for a webview target.
+export function electronWebviewTip(appLabel) {
+    return `note: ${appLabel} is an Electron/web UI — an AX click/type may not reach the webview `
+        + `(a reported success can be a no-op). To drive it reliably, relaunch it with `
+        + '`--remote-debugging-port=9222` and use `agents browser --electron` (CDP).';
+}
+// Print the CDP steer when the target is a known Electron app. Keyed off --bundle
+// (the recommended way to target); a frontmost-resolved target without --bundle is
+// left alone to avoid a second RPC on the hot path. Skipped for remote --host.
+function warnIfElectronWebview(opts) {
+    if (opts.host)
+        return;
+    if (opts.bundle && isElectronApp(opts.bundle))
+        console.error(electronWebviewTip(opts.bundle));
+}
 function emit(result, json, human) {
     if (json) {
         console.log(JSON.stringify(result, null, 2));
@@ -355,6 +409,7 @@ export function registerActionCommands(program) {
         .option('--json', 'Emit JSON'))).action(async (opts) => {
         await withClient(async (client) => {
             const pid = await resolveTargetPid(client, opts, { verb: 'click' });
+            warnIfElectronWebview(opts);
             const spec = buildElementOrCoords(opts);
             if (!spec.ok) {
                 console.error(spec.error);
@@ -377,6 +432,7 @@ export function registerActionCommands(program) {
         .option('--json', 'Emit JSON'))).action(async (opts) => {
         await withClient(async (client) => {
             const pid = await resolveTargetPid(client, opts, { verb: 'right-click' });
+            warnIfElectronWebview(opts);
             const spec = buildElementOrCoords(opts);
             if (!spec.ok) {
                 console.error(spec.error);
@@ -397,6 +453,7 @@ export function registerActionCommands(program) {
         .option('--json', 'Emit JSON'))).action(async (opts) => {
         await withClient(async (client) => {
             const pid = await resolveTargetPid(client, opts, { verb: 'type' });
+            warnIfElectronWebview(opts);
             const spec = buildElementOrCoords(opts);
             if (!spec.ok) {
                 console.error(spec.error);
@@ -424,6 +481,7 @@ export function registerActionCommands(program) {
         .option('--json', 'Emit JSON')).action(async (opts) => {
         await withClient(async (client) => {
             const pid = await resolveTargetPid(client, opts, { verb: 'type-text' });
+            warnIfElectronWebview(opts);
             await applyFocusPolicy(client, pid, opts);
             const params = { pid, text: opts.text };
             if (opts.commit)
@@ -448,6 +506,7 @@ export function registerActionCommands(program) {
         .option('--json', 'Emit JSON')).action(async (opts) => {
         await withClient(async (client) => {
             const pid = await resolveTargetPid(client, opts, { verb: 'key' });
+            warnIfElectronWebview(opts);
             await applyFocusPolicy(client, pid, opts);
             const params = { pid, keys: opts.keys };
             if (opts.requireFrontmost)

package/dist/commands/computer.d.ts

@@ -22,9 +22,9 @@ export declare function detectImageFormat(buf: Buffer): '.png' | '.jpg' | null;
  * Make the screenshot filename honest about its bytes. The two helper backends
  * encode DIFFERENT formats and neither re-encodes to match the requested name:
  * the macOS helper (ScreenCaptureKit) returns JPEG
- * (packages/computer-helper/Sources/ComputerHelper/Screenshot.swift:207,212),
+ * (native/computer-mac/Sources/ComputerHelper/Screenshot.swift:207,212),
  * the Windows helper returns PNG
- * (packages/computer-helper-win/Screenshot.cs:33). So a fixed default extension
+ * (native/computer-win/Screenshot.cs:33). So a fixed default extension
  * cannot be correct for both — the only honest path is to sniff the real format
  * and swap the extension to match. Pure so it's unit-testable.
  *

package/dist/commands/computer.js

@@ -53,9 +53,9 @@ export function detectImageFormat(buf) {
  * Make the screenshot filename honest about its bytes. The two helper backends
  * encode DIFFERENT formats and neither re-encodes to match the requested name:
  * the macOS helper (ScreenCaptureKit) returns JPEG
- * (packages/computer-helper/Sources/ComputerHelper/Screenshot.swift:207,212),
+ * (native/computer-mac/Sources/ComputerHelper/Screenshot.swift:207,212),
  * the Windows helper returns PNG
- * (packages/computer-helper-win/Screenshot.cs:33). So a fixed default extension
+ * (native/computer-win/Screenshot.cs:33). So a fixed default extension
  * cannot be correct for both — the only honest path is to sniff the real format
  * and swap the extension to match. Pure so it's unit-testable.
  *
@@ -354,7 +354,7 @@ function registerSetupCommand(program) {
         }
         const srcApp = resolveHelperApp();
         if (!srcApp || !fs.existsSync(srcApp)) {
-            console.error('helper not built. Run: ./packages/computer-helper/scripts/build.sh debug');
+            console.error('helper not built. Run: ./native/computer-mac/scripts/build.sh debug');
             process.exit(1);
         }
         const home = os.homedir();
@@ -392,7 +392,7 @@ function registerSetupCommand(program) {
         }
         catch {
             console.error('codesign verify FAILED. The destination .app is unsigned or its signature was stripped.');
-            console.error('rebuild the helper with a Developer ID cert: ./packages/computer-helper/scripts/build.sh release');
+            console.error('rebuild the helper with a Developer ID cert: ./native/computer-mac/scripts/build.sh release');
             process.exit(1);
         }
         // 3. Ensure socket + log parent dirs exist.

package/dist/commands/exec.js

@@ -219,6 +219,7 @@ export function registerRunCommand(program) {
         .option('--resume [id]', 'Resume a previous conversation. Accepts a full or partial session id (prefix-matched against the index); omit the id to pick from recent sessions interactively. Resumes under the version that started the session. claude/codex resume natively; other agents replay via a /continue first message. Pair with a prompt to continue headlessly.')
         .option('--session-id <id>', 'Force a NEW conversation to use this exact session UUID (Claude only). This CREATES a session — to resume an existing one, use --resume.')
         .option('--verbose', 'Show detailed execution logs')
+        .option('--raw', 'Interactive runs on macOS/Linux launch inside a shared tmux session (for %pane addressing + re-attach). Pass --raw to spawn the agent directly instead. Also disabled by AGENTS_NO_TMUX=1.')
         .option('--timeout <duration>', 'Kill the agent after this duration (e.g., 30m, 1h, 2h30m)')
         .option('--fallback <agents>', 'Comma-separated agents to try on rate-limit failure. Each entry accepts an optional @version pin (e.g., codex@0.116.0,gemini). The primary runs first; if it exits with a rate-limit error, the next agent picks up via /continue handoff.')
         .option('-b, --balanced', 'Shortcut for --strategy balanced. Ignored when @version is pinned.')
@@ -1063,6 +1064,7 @@ export function registerRunCommand(program) {
             sessionId: resumeSessionId ?? options.sessionId,
             resume: resumeNative,
             verbose: options.verbose,
+            raw: options.raw,
             timeout: options.timeout,
             env,
             toolsRestrict: workflowToolsRestrict,

package/dist/commands/focus.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `agents sessions focus [id]` — take me to a live session, however it's reachable.
+ *
+ * Same detection as `go`, but where `go` *refuses* an un-attachable session,
+ * `focus` **opens a new tab and resumes it** — locally, or on the remote over SSH
+ * (via the terminal launch engine's `openSurfaces`, `host` = the peer). So:
+ *   - in tmux (local/remote)   -> attach the live pane (join it, no fork)
+ *   - in Ghostty               -> focus its tab
+ *   - headless / plain / etc.  -> new tab + `resume` (a copy if it's mid-run — the
+ *                                  original keeps going; a clean continue if it's idle)
+ *
+ * NOTE: joining a live process without forking is only possible via tmux — that's
+ * 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 type { ActiveSession } from '../lib/session/active.js';
+import type { SessionMeta } from '../lib/session/types.js';
+export declare function registerFocusCommand(program: Command): void;
+/**
+ * Which fallback fires when a session has no attach rail. `--attach-only` (the old
+ * `go`) refuses; the default opens a new tab and resumes a copy. Pure so it's testable
+ * without touching `jumpTo`'s side effects.
+ */
+export declare function selectFallback(attachOnly: boolean | undefined): UnreachableFallback;
+export declare function focusAction(id: string | undefined, opts: {
+    local?: boolean;
+    attachOnly?: boolean;
+}): Promise<void>;
+/** Minimal SessionMeta for a live session, enough for `buildResumeCommand` + placement. */
+export declare function metaFromActive(s: ActiveSession): SessionMeta;

package/dist/commands/focus.js

@@ -0,0 +1,150 @@
+/**
+ * `agents sessions focus [id]` — take me to a live session, however it's reachable.
+ *
+ * Same detection as `go`, but where `go` *refuses* an un-attachable session,
+ * `focus` **opens a new tab and resumes it** — locally, or on the remote over SSH
+ * (via the terminal launch engine's `openSurfaces`, `host` = the peer). So:
+ *   - in tmux (local/remote)   -> attach the live pane (join it, no fork)
+ *   - in Ghostty               -> focus its tab
+ *   - headless / plain / etc.  -> new tab + `resume` (a copy if it's mid-run — the
+ *                                  original keeps going; a clean continue if it's idle)
+ *
+ * NOTE: joining a live process without forking is only possible via tmux — that's
+ * why `--tmux`-wrapped launches are worth it for sessions you'll want back live.
+ */
+import fs from 'node:fs';
+import chalk from 'chalk';
+import { gatherLiveTargets, pickLiveTarget, jumpTo, refuseFallback } from './go.js';
+import { buildResumeCommand, resumeSessionInPlace } from './sessions.js';
+import { runOnPeer } from '../lib/session/remote-list.js';
+import { discoverSessions } from '../lib/session/discover.js';
+import { openSurfaces, currentContext, availableBackends, detectCurrentBackend, } from '../lib/terminal/index.js';
+import { isInteractiveTerminal } from './utils.js';
+export function registerFocusCommand(program) {
+    program
+        .command('focus')
+        .argument('[id]', 'Short/full session id to focus; omit for an interactive picker')
+        .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)')
+        .description('Focus a live session — attach its terminal, or open a new tab and resume it')
+        .action(async (id, opts) => {
+        await focusAction(id, opts);
+    });
+}
+/**
+ * Which fallback fires when a session has no attach rail. `--attach-only` (the old
+ * `go`) refuses; the default opens a new tab and resumes a copy. Pure so it's testable
+ * without touching `jumpTo`'s side effects.
+ */
+export function selectFallback(attachOnly) {
+    return attachOnly ? refuseFallback : resumeInNewTab;
+}
+export async function focusAction(id, opts) {
+    const { self, activeById } = await gatherLiveTargets(!!opts.local);
+    const fallback = selectFallback(opts.attachOnly);
+    if (id) {
+        const q = id.toLowerCase();
+        const matches = [...activeById.values()].filter((s) => s.sessionId.toLowerCase().startsWith(q));
+        if (matches.length === 1) {
+            await jumpTo(matches[0], self, fallback);
+            return;
+        }
+        if (matches.length > 1) {
+            console.error(chalk.red(`"${id}" is ambiguous (${matches.length} live matches). Use more of the id.`));
+            process.exitCode = 1;
+            return;
+        }
+        // Not live — it's a past session; resume is the right tool (multi-select + placement).
+        console.log(chalk.yellow(`No live session matching "${id}".`) +
+            chalk.gray(`\nTo resume a past session: agents sessions resume ${id}`));
+        process.exitCode = 1;
+        return;
+    }
+    if (!isInteractiveTerminal()) {
+        console.error(chalk.red('focus needs an interactive terminal, or pass a session id.'));
+        process.exitCode = 1;
+        return;
+    }
+    if (activeById.size === 0) {
+        console.log(chalk.gray('No live sessions to focus. To resume a past one: agents sessions resume'));
+        return;
+    }
+    const target = await pickLiveTarget(activeById, self, 'Focus a live session:', 'focus');
+    if (!target)
+        return;
+    await jumpTo(target, self, fallback);
+}
+function shortId(s) {
+    return (s.sessionId ?? '').slice(0, 8) || '-';
+}
+/** Minimal SessionMeta for a live session, enough for `buildResumeCommand` + placement. */
+export function metaFromActive(s) {
+    return {
+        id: s.sessionId ?? '',
+        shortId: shortId(s),
+        agent: s.kind,
+        timestamp: new Date(s.startedAtMs ?? Date.now()).toISOString(),
+        filePath: '',
+        cwd: s.cwd,
+    };
+}
+/** Look up the rich indexed SessionMeta by id so `version` survives (version-pinned resume). */
+async function richMetaById(id) {
+    try {
+        const metas = await discoverSessions({ all: true, since: '90d', limit: 2000 });
+        return metas.find((m) => m.id === id) ?? metas.find((m) => m.id.startsWith(id));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * `focus`'s fallback for a session with no attach rail: reopen it and hand you to it.
+ *   - remote → resume ON the peer over SSH (foreground) — the peer resolves the pinned
+ *              version and holds the transcript, and `-tt` delivers you there.
+ *   - local  → resume in a new tab in your terminal, version-pinned via the indexed meta.
+ * 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, remote) => {
+    const id = s.sessionId ?? '';
+    if (!id) {
+        console.log(chalk.yellow('This session has no id to resume.'));
+        return;
+    }
+    // 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(['sessions', 'resume', 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(`  or run it yourself: ssh ${remote} 'agents sessions resume ${shortId(s)}'`));
+        }
+        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 = buildResumeCommand(meta);
+    if (!command) {
+        console.log(chalk.yellow(`${meta.shortId} — ${meta.agent} sessions aren't resumable, so there's no way to reopen it.`));
+        return;
+    }
+    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 resumeSessionInPlace(meta);
+        return;
+    }
+    console.log(chalk.gray(`${shortId(s)} has no live terminal to attach — opening a new ${backend} tab and resuming a copy.`));
+    const results = await openSurfaces([{ cwd, command }], { backend, packing: 'tabs' });
+    const r = results[0];
+    if (!r || !r.ok) {
+        console.log(chalk.red(`  failed to open — ${r?.error ?? 'unknown error'}`));
+        console.log(chalk.gray(`  try: agents sessions resume ${meta.shortId}`));
+    }
+};

package/dist/commands/go.d.ts

@@ -1,21 +1,35 @@
 /**
- * `agents sessions go [id]` — jump to a LIVE agent session's terminal.
+ * `agents sessions go [id]` — DEPRECATED alias for `agents sessions focus --attach-only`.
  *
- * No id  -> the SAME rich interactive picker as `agents sessions` (worktree, PR,
- *           changed files, tools, tests, last response — this-machine first),
- *           filtered to sessions that are running right now.
- * With id -> jump directly.
+ * `go` was "attach or refuse" (never fork/resume). `focus --attach-only` is exactly
+ * that behavior, so `go` now prints a deprecation notice and delegates to `focusAction`.
  *
- * "Jump" is not "resume" (which spawns a new process from the transcript). It walks
- * you to the already-running terminal:
- *   local tmux    -> attach (switch-client when already inside tmux)
- *   local Ghostty -> focus its tab (Cmd+<n> via System Events; tab # from ghostty-tabs)
- *   remote tmux   -> ssh -tt + tmux attach (pane->session resolved on the remote)
- *   otherwise     -> refuse with a reason + resume hint (cloud / no attach rail)
+ * This file still owns the shared reach engine that `focus` imports:
+ *   - `gatherLiveTargets` / `pickLiveTarget` / `buildLivePool` — live-session discovery + picker
+ *   - `jumpTo` — the side-effecting jump: attach the already-running terminal
+ *       local tmux    -> attach (switch-client when already inside tmux)
+ *       local Ghostty -> focus its tab (Cmd+<n> via System Events; tab # from ghostty-tabs)
+ *       remote tmux   -> ssh -tt + tmux attach (pane->session resolved on the remote)
+ *       otherwise     -> hand off to the `UnreachableFallback` (attach-only refuses; focus resumes)
+ *   - `refuseFallback` — the attach-only fallback (remote -> login shell; local -> refuse)
  */
 import type { Command } from 'commander';
 import { type ActiveSession } from '../lib/session/active.js';
+import type { SessionMeta } from '../lib/session/types.js';
 export declare function registerGoCommand(program: Command): void;
+/** Live jump targets (local + remote), keyed by session id. Cloud excluded (no pid). */
+export declare function gatherLiveTargets(local: boolean): Promise<{
+    self: string;
+    activeById: Map<string, ActiveSession>;
+}>;
+/** Interactive pick over the live sessions' rich SessionMeta; returns the chosen live session. */
+export declare function pickLiveTarget(activeById: Map<string, ActiveSession>, self: string, message: string, enterHint: string): Promise<ActiveSession | null>;
+/**
+ * Map each live session to its rich SessionMeta (worktree/PR/changes/tools/tests
+ * via the shared picker), reusing `discoverSessions`. Remote or unindexed live
+ * sessions get a minimal synthesized meta so they still appear and jump.
+ */
+export declare function buildLivePool(activeById: Map<string, ActiveSession>, self: string): Promise<SessionMeta[]>;
 export interface Where {
     label: string;
     action: string;
@@ -26,3 +40,12 @@ export interface Where {
  * `jumpTo` below: remote-tmux, then local-tmux, then ghostty, then refuse.
  */
 export declare function describeWhere(s: ActiveSession, self: string): Where;
+/**
+ * What to do when a session can't be *attached* (no tmux/Ghostty rail). `go`
+ * refuses; `focus` opens a new tab and resumes. `remote` is the peer name when
+ * 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 declare function refuseFallback(s: ActiveSession, remote: string | undefined): Promise<void>;
+export declare function jumpTo(s: ActiveSession, self: string, fallback?: UnreachableFallback): Promise<void>;