@phnx-labs/agents-cli 1.20.36 → 1.20.38

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

@@ -70,4 +70,14 @@ export declare function resolveTargetPidDecision(client: ComputerClient, opts: {
     ok: false;
     error: string;
 }>;
+export declare function focusStealNotes(opts: {
+    id?: string;
+    x?: number;
+    y?: number;
+    raise?: boolean;
+}): string[];
+export declare function shouldRaise(opts: {
+    id?: string;
+    raise?: boolean;
+}): boolean;
 export declare function registerActionCommands(program: Command): void;

package/dist/commands/computer-actions.js

@@ -254,10 +254,38 @@ async function resolveTargetPid(client, opts, gate) {
     }
     return resolved.pid;
 }
-// --raise flag: app-level focus_window before the main action so coordinate
-// clicks and keystrokes land on a visible, key window.
-async function raiseIfRequested(client, pid, raise) {
-    if (raise)
+// Focus-safety policy for input verbs. Element mode (--id) drives an app through
+// Accessibility actions (AXPress / set AXValue) that never activate the app or move
+// the cursor, so the user keeps working while an agent acts. The two paths that DO
+// take over the screen are (a) --raise (brings the app to the front + steals keyboard
+// focus) and (b) coordinate mode (--x/--y warps the physical cursor and needs the app
+// frontmost). Both are surfaced as notes, and --raise is ignored in element mode so a
+// reflexive flag cannot hijack the user's session.
+// Pure, unit-tested: the focus/cursor costs an action will impose, as human notes.
+export function focusStealNotes(opts) {
+    const notes = [];
+    const elementMode = opts.id != null;
+    if (opts.raise) {
+        notes.push(elementMode
+            ? 'note: --raise ignored in element mode (--id) — element actions do not need the app frontmost, so your focus is left alone.'
+            : 'note: --raise brings the target app to the front and takes keyboard focus from you. Element mode (`describe` then --id) drives apps without stealing focus.');
+    }
+    if (!elementMode && (opts.x != null || opts.y != null)) {
+        notes.push('note: coordinate mode moves your real cursor and needs the app frontmost. Prefer element mode (`describe` then --id) to act without moving your pointer.');
+    }
+    return notes;
+}
+// Pure, unit-tested: whether --raise is actually honored. Element mode suppresses it
+// so an element-targeted action never steals the user's foreground.
+export function shouldRaise(opts) {
+    return Boolean(opts.raise) && opts.id == null;
+}
+// Apply the focus-safety policy for an input verb: print the cost notes, and raise
+// only when raising is actually warranted (non-element mode with --raise).
+async function applyFocusPolicy(client, pid, opts) {
+    for (const note of focusStealNotes(opts))
+        console.error(note);
+    if (shouldRaise(opts))
         unwrap(await client.call('focus_window', { pid }));
 }
 function emit(result, json, human) {
@@ -281,9 +309,9 @@ function addTargetOpts(cmd) {
 // Add the shared --id/--x/--y element-or-coords options to a verb.
 function addElementOrCoordOpts(cmd) {
     return cmd
-        .option('--id <@eN>', 'Element id from `describe`')
-        .option('--x <n>', 'X coordinate (global, points)', (v) => parseInt(v, 10))
-        .option('--y <n>', 'Y coordinate (global, points)', (v) => parseInt(v, 10));
+        .option('--id <@eN>', 'Element id from `describe` (focus-safe: no foreground steal, no cursor move)')
+        .option('--x <n>', 'X coordinate (global, points; moves your real cursor, needs app frontmost)', (v) => parseInt(v, 10))
+        .option('--y <n>', 'Y coordinate (global, points; moves your real cursor, needs app frontmost)', (v) => parseInt(v, 10));
 }
 export function registerActionCommands(program) {
     // apps — list_apps
@@ -323,7 +351,7 @@ export function registerActionCommands(program) {
         .description('Click an element (--id) or screen coordinate (--x --y)')
         .option('--count <n>', 'Click count (2 = double-click)', (v) => parseInt(v, 10))
         .option('--background', 'Focus-safe postToPid delivery (plain AppKit only; skips HID tap)')
-        .option('--raise', 'Bring the target app to the front first')
+        .option('--raise', 'Bring the target app to the front first (steals your foreground + keyboard focus; ignored in element mode --id)')
         .option('--json', 'Emit JSON'))).action(async (opts) => {
         await withClient(async (client) => {
             const pid = await resolveTargetPid(client, opts, { verb: 'click' });
@@ -332,7 +360,7 @@ export function registerActionCommands(program) {
                 console.error(spec.error);
                 process.exit(1);
             }
-            await raiseIfRequested(client, pid, opts.raise);
+            await applyFocusPolicy(client, pid, opts);
             const params = { pid, ...spec.params };
             if (opts.count != null)
                 params.count = opts.count;
@@ -354,6 +382,7 @@ export function registerActionCommands(program) {
                 console.error(spec.error);
                 process.exit(1);
             }
+            await applyFocusPolicy(client, pid, opts);
             const res = unwrap(await client.call('right_click', { pid, ...spec.params }));
             emit(res, Boolean(opts.json), () => `right-clicked (${res.method ?? 'ok'})`);
         });
@@ -373,6 +402,7 @@ export function registerActionCommands(program) {
                 console.error(spec.error);
                 process.exit(1);
             }
+            await applyFocusPolicy(client, pid, opts);
             const params = { pid, ...spec.params, text: opts.text };
             if (opts.commit)
                 params.commit = true;
@@ -388,13 +418,13 @@ export function registerActionCommands(program) {
         .description('Type an arbitrary unicode string into the focused field (focus first via click/focus)')
         .requiredOption('--text <s>', 'Text to type')
         .option('--commit', 'Press Return after typing')
-        .option('--raise', 'Bring the target app to the front first')
+        .option('--raise', 'Bring the target app to the front first (steals your foreground + keyboard focus; ignored in element mode --id)')
         .option('--require-frontmost', 'Fail (not warn) if the target is not the frontmost app')
         .option('--char-delay <ms>', 'Inter-character delay in ms (default 4; raise for lossy keyboard relays like VM guests, e.g. 25). Clamped to [1, 250].', (v) => parseInt(v, 10))
         .option('--json', 'Emit JSON')).action(async (opts) => {
         await withClient(async (client) => {
             const pid = await resolveTargetPid(client, opts, { verb: 'type-text' });
-            await raiseIfRequested(client, pid, opts.raise);
+            await applyFocusPolicy(client, pid, opts);
             const params = { pid, text: opts.text };
             if (opts.commit)
                 params.commit = true;
@@ -413,12 +443,12 @@ export function registerActionCommands(program) {
         .command('key')
         .description('Send a key chord, e.g. "cmd+shift+s", "enter", "esc"')
         .requiredOption('--keys <chord>', 'Key chord')
-        .option('--raise', 'Bring the target app to the front first')
+        .option('--raise', 'Bring the target app to the front first (steals your foreground + keyboard focus; ignored in element mode --id)')
         .option('--require-frontmost', 'Fail (not warn) if the target is not the frontmost app')
         .option('--json', 'Emit JSON')).action(async (opts) => {
         await withClient(async (client) => {
             const pid = await resolveTargetPid(client, opts, { verb: 'key' });
-            await raiseIfRequested(client, pid, opts.raise);
+            await applyFocusPolicy(client, pid, opts);
             const params = { pid, keys: opts.keys };
             if (opts.requireFrontmost)
                 params.require_frontmost = true;
@@ -435,7 +465,7 @@ export function registerActionCommands(program) {
         .requiredOption('--to <x,y>', 'End coordinate "x,y"')
         .option('--button <left|right>', 'Mouse button', 'left')
         .option('--background', 'Focus-safe postToPid delivery (plain AppKit only)')
-        .option('--raise', 'Bring the target app to the front first')
+        .option('--raise', 'Bring the target app to the front first (steals your foreground + keyboard focus; ignored in element mode --id)')
         .option('--json', 'Emit JSON')).action(async (opts) => {
         let from;
         let to;
@@ -449,7 +479,7 @@ export function registerActionCommands(program) {
         }
         await withClient(async (client) => {
             const pid = await resolveTargetPid(client, opts, { verb: 'drag' });
-            await raiseIfRequested(client, pid, opts.raise);
+            await applyFocusPolicy(client, pid, opts);
             const params = {
                 pid,
                 from: [from.x, from.y],
@@ -468,11 +498,11 @@ export function registerActionCommands(program) {
         .description('Scroll by a pixel delta at an element or coordinate')
         .option('--dy <n>', 'Vertical delta (negative = down)', (v) => parseInt(v, 10))
         .option('--dx <n>', 'Horizontal delta', (v) => parseInt(v, 10))
-        .option('--raise', 'Bring the target app to the front first')
+        .option('--raise', 'Bring the target app to the front first (steals your foreground + keyboard focus; ignored in element mode --id)')
         .option('--json', 'Emit JSON'))).action(async (opts) => {
         await withClient(async (client) => {
             const pid = await resolveTargetPid(client, opts, { verb: 'scroll' });
-            await raiseIfRequested(client, pid, opts.raise);
+            await applyFocusPolicy(client, pid, opts);
             const params = { pid };
             if (opts.id)
                 params.element_id = opts.id;

package/dist/commands/doctor.js

@@ -482,7 +482,9 @@ export function registerDoctorCommand(program) {
         .option('--diff', 'In target mode, include unified diffs for divergent files')
         .option('--fix', 'Heal gaps: install missing resources, repair invalid plugin manifests, refresh stale plugins, and reconcile drift (all installed versions, or just the target)')
         .option('--kind <kinds>', 'Restrict to comma-separated resource kinds (commands,skills,hooks,rules,mcp,permissions,subagents,plugins,promptcuts)')
-        .option('--cwd <path>', 'Resolution cwd for project layer detection (default: process.cwd())');
+        .option('--cwd <path>', 'Resolution cwd for project layer detection (default: process.cwd())')
+        .option('--adopt <agent>', "Take over the agent's native launcher that shadows the shim (symlink it to the version-managed shim; reversible with --release)")
+        .option('--release <agent>', 'Undo --adopt: restore the native launcher agents-cli previously adopted');
     setHelpSections(doctorCmd, {
         examples: `
       # Overview: CLI availability + sync status + orphans across all defaults
@@ -509,6 +511,51 @@ export function registerDoctorCommand(program) {
     });
     doctorCmd.action(async (target, opts) => {
         const cwd = opts.cwd ? opts.cwd : process.cwd();
+        // Launcher adoption escape hatch. `--adopt <agent>` forces the take-over
+        // even for a non-default agent; `--release <agent>` reverses it.
+        if (opts.adopt || opts.release) {
+            if (opts.adopt && opts.release) {
+                console.error(chalk.red('--adopt and --release are mutually exclusive; pass only one.'));
+                process.exit(1);
+            }
+            const { adoptShadowingLauncher, releaseAdoptedLauncher } = await import('../lib/shims.js');
+            const raw = (opts.adopt || opts.release);
+            const agent = resolveAgentName(raw);
+            if (!agent) {
+                console.error(chalk.red(formatAgentError(raw)));
+                process.exit(1);
+            }
+            if (opts.release) {
+                const restored = releaseAdoptedLauncher(agent);
+                if (restored) {
+                    console.log(chalk.green(`Released ${AGENTS[agent].cliCommand}: launcher restored to ${restored}.`));
+                }
+                else {
+                    console.log(chalk.gray(`${AGENTS[agent].cliCommand} has no adopted launcher to release.`));
+                }
+                return;
+            }
+            // adoptShadowingLauncher resolves the launcher itself (PATH shadow, then
+            // the durable ~/.local/bin symlink), so it forces the take-over even when
+            // this shell's PATH already has the shim first.
+            const result = adoptShadowingLauncher(agent);
+            if (result.adopted) {
+                console.log(chalk.green(`Adopted ${AGENTS[agent].cliCommand} launcher (${result.launcher} -> shim). Original recorded for --release; version management now wins regardless of PATH order.`));
+            }
+            else if (result.reason === 'already-adopted') {
+                console.log(chalk.gray(`${AGENTS[agent].cliCommand} launcher is already adopted.`));
+            }
+            else if (result.reason === 'no-shadow') {
+                console.log(chalk.gray(`Nothing to adopt — no ${AGENTS[agent].cliCommand} launcher found shadowing the shim (checked PATH and ~/.local/bin).`));
+            }
+            else if (result.reason === 'not-a-symlink') {
+                console.log(chalk.yellow(`${AGENTS[agent].cliCommand} is shadowed by a real binary (${result.launcher}), not a symlink. agents-cli won't move a real binary — remove/reorder it or reorder PATH.`));
+            }
+            else {
+                console.log(chalk.yellow(`Could not adopt ${AGENTS[agent].cliCommand} (${result.reason}).`));
+            }
+            return;
+        }
         // --fix turns the read-only diagnosis into a heal. With no target it heals
         // every installed version; with a target it scopes to that agent.
         if (opts.fix) {

package/dist/commands/go.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `agents sessions go [id]` — jump to a LIVE agent session's terminal.
+ *
+ * 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.
+ *
+ * "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)
+ */
+import type { Command } from 'commander';
+import { type ActiveSession } from '../lib/session/active.js';
+export declare function registerGoCommand(program: Command): void;
+export interface Where {
+    label: string;
+    action: string;
+}
+/**
+ * Pure, testable mirror of `jumpTo`'s path selection (jumpTo itself has side
+ * effects — process.exit / ssh / osascript). Keep the branch ORDER in sync with
+ * `jumpTo` below: remote-tmux, then local-tmux, then ghostty, then refuse.
+ */
+export declare function describeWhere(s: ActiveSession, self: string): Where;

package/dist/commands/go.js

@@ -0,0 +1,238 @@
+/**
+ * `agents sessions go [id]` — jump to a LIVE agent session's terminal.
+ *
+ * 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.
+ *
+ * "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)
+ */
+import chalk from 'chalk';
+import path from 'path';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { getActiveSessions, findSessionFileForKind } from '../lib/session/active.js';
+import { gatherRemoteActive } from '../lib/session/remote-active.js';
+import { discoverSessions } from '../lib/session/discover.js';
+import { dedupeByMachineSession, mergeLocalFirst, pickSessionInteractive } from './sessions.js';
+import { machineId } from '../lib/session/sync/config.js';
+import { isInteractiveTerminal } from './utils.js';
+import { attachTmux, runTmux } from '../lib/tmux/binary.js';
+import { getDefaultSocketPath } from '../lib/tmux/paths.js';
+import { sshStream, assertValidSshTarget, shellQuote } from '../lib/ssh-exec.js';
+import { enumerateGhosttyTabs, assignGhosttyTabs } from '../lib/session/ghostty-tabs.js';
+const execFileAsync = promisify(execFile);
+export function registerGoCommand(program) {
+    program
+        .command('go')
+        .argument('[id]', 'Short/full session id to jump to; omit for an interactive picker')
+        .option('--local', 'Only this machine (skip the cross-host sweep)')
+        .description('Jump to a live agent session — attach its tmux, or focus its terminal tab')
+        .action(async (id, opts) => {
+        await goAction(id, opts);
+    });
+}
+async function goAction(id, opts) {
+    const self = machineId();
+    // Live jump targets (local + remote), keyed by session id.
+    const localActive = await getActiveSessions();
+    for (const s of localActive)
+        if (!s.machine)
+            s.machine = self;
+    let active = localActive;
+    if (!opts.local) {
+        try {
+            const remote = await gatherRemoteActive();
+            active = dedupeByMachineSession([...localActive, ...remote.sessions]);
+        }
+        catch { /* remote sweep is best-effort */ }
+    }
+    const activeById = new Map();
+    for (const s of active)
+        if (s.context !== 'cloud' && s.sessionId)
+            activeById.set(s.sessionId, s);
+    if (activeById.size === 0) {
+        console.log(chalk.gray('No live agent sessions to jump to.'));
+        return;
+    }
+    // Direct jump by id — no picker.
+    if (id) {
+        const q = id.toLowerCase();
+        const matches = [...activeById.values()].filter((s) => s.sessionId.toLowerCase().startsWith(q));
+        if (matches.length === 0) {
+            console.error(chalk.red(`No live session matching "${id}".`));
+            process.exitCode = 1;
+            return;
+        }
+        if (matches.length > 1) {
+            console.error(chalk.red(`"${id}" is ambiguous (${matches.length} matches). Use more of the id.`));
+            process.exitCode = 1;
+            return;
+        }
+        await jumpTo(matches[0], self);
+        return;
+    }
+    if (!isInteractiveTerminal()) {
+        console.error(chalk.red('go needs an interactive terminal, or pass a session id.'));
+        process.exitCode = 1;
+        return;
+    }
+    // Reuse the rich `sessions` picker over the live sessions' full SessionMeta.
+    const pool = await buildLivePool(activeById, self);
+    if (pool.length === 0) {
+        console.log(chalk.gray('No live sessions to jump to.'));
+        return;
+    }
+    const picked = await pickSessionInteractive(pool, 'Jump to a live session:', undefined, 0, 'jump');
+    if (!picked)
+        return;
+    const target = activeById.get(picked.session.id);
+    if (!target) {
+        console.log(chalk.yellow(`${picked.session.shortId} is no longer live — try: `) + chalk.gray(`agents sessions resume ${picked.session.shortId}`));
+        return;
+    }
+    await jumpTo(target, self);
+}
+/**
+ * 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.
+ */
+async function buildLivePool(activeById, self) {
+    let metas = [];
+    try {
+        metas = await discoverSessions({ all: true, since: '30d', limit: 1000 });
+    }
+    catch { /* fall back to synthesized metas */ }
+    const byId = new Map();
+    for (const m of metas)
+        byId.set(m.id, m);
+    const pool = [];
+    for (const [sid, s] of activeById) {
+        pool.push(byId.get(sid) ?? synthMeta(s, self));
+    }
+    return mergeLocalFirst(pool, self);
+}
+function synthMeta(s, self) {
+    const remote = !!s.machine && s.machine !== self;
+    // For a local session, locate the real transcript on disk so the picker's
+    // buildPreview parses it directly (rich Prompt/Changes/Tools/Last response) —
+    // independent of the sessions DB. Remote transcripts live on the peer, so leave
+    // filePath empty and the preview shows a clean "not indexed here" note.
+    const filePath = remote ? '' : (findSessionFileForKind(s.kind, s.cwd, s.sessionId) ?? '');
+    return {
+        id: s.sessionId,
+        shortId: s.sessionId.slice(0, 8),
+        agent: s.kind,
+        timestamp: new Date(s.startedAtMs ?? Date.now()).toISOString(),
+        filePath,
+        cwd: s.cwd,
+        project: s.cwd ? path.basename(s.cwd) : undefined,
+        topic: s.topic,
+        machine: s.machine,
+        _remote: remote,
+    };
+}
+function shortId(s) {
+    return (s.sessionId ?? '').slice(0, 8) || '-';
+}
+/**
+ * Pure, testable mirror of `jumpTo`'s path selection (jumpTo itself has side
+ * effects — process.exit / ssh / osascript). Keep the branch ORDER in sync with
+ * `jumpTo` below: remote-tmux, then local-tmux, then ghostty, then refuse.
+ */
+export function describeWhere(s, self) {
+    const remote = s.machine && s.machine !== self ? s.machine : undefined;
+    const mux = s.provenance?.mux;
+    if (mux?.kind === 'tmux' && mux.pane) {
+        return remote
+            ? { label: `tmux ${mux.pane} on ${remote}`, action: `ssh + attach on ${remote}` }
+            : { label: `tmux ${mux.pane}`, action: 'attach its tmux' };
+    }
+    if (!remote && s.host === 'ghostty')
+        return { label: 'Ghostty', action: 'focus its Ghostty tab' };
+    if (remote)
+        return { label: `${s.host ?? 'shell'} on ${remote}`, action: `open a shell on ${remote}` };
+    return { label: s.host ?? 'unknown terminal', action: 'resume it (no live attach rail)' };
+}
+async function jumpTo(s, self) {
+    const remote = s.machine && s.machine !== self ? s.machine : undefined;
+    const mux = s.provenance?.mux;
+    // Path C: remote tmux — ssh in and attach, resolving the pane's session on the remote.
+    if (remote) {
+        if (mux?.kind === 'tmux' && mux.pane) {
+            assertValidSshTarget(remote);
+            const sock = mux.socket ? `-S ${shellQuote(mux.socket)} ` : '';
+            const p = shellQuote(mux.pane);
+            const remoteCmd = `w=$(tmux ${sock}display-message -pt ${p} '#{session_name}:#{window_index}' 2>/dev/null); ` +
+                `sess=$(tmux ${sock}display-message -pt ${p} '#{session_name}' 2>/dev/null); ` +
+                `[ -n "$w" ] && tmux ${sock}select-window -t "$w" 2>/dev/null; ` +
+                `exec tmux ${sock}attach-session -t "\${sess:-${p}}"`;
+            console.log(chalk.gray(`Attaching ${shortId(s)} on ${remote} over SSH — Ctrl-b d to detach.`));
+            process.exit(sshStream(remote, remoteCmd, { tty: true }));
+        }
+        console.log(chalk.yellow(`${shortId(s)} on ${remote} isn't inside tmux — opening a shell on ${remote} instead.`));
+        assertValidSshTarget(remote);
+        process.exit(sshStream(remote, 'exec "${SHELL:-/bin/sh}" -l', { tty: true }));
+    }
+    // Path B: local tmux — attach (or switch-client if we're already inside tmux).
+    if (mux?.kind === 'tmux' && mux.pane) {
+        const socket = mux.socket ?? getDefaultSocketPath();
+        const { session, window } = await resolveLocalPane(socket, mux.pane);
+        if (session && window != null) {
+            await runTmux({ socket, args: ['select-window', '-t', `${session}:${window}`], throwOnError: false }).catch(() => { });
+        }
+        const tgt = session ?? mux.pane;
+        if (process.env.TMUX) {
+            await runTmux({ socket, args: ['switch-client', '-t', tgt], throwOnError: false }).catch(() => { });
+            console.log(chalk.gray(`Switched this tmux client to ${shortId(s)} (${tgt}).`));
+            return;
+        }
+        console.log(chalk.gray(`Attaching ${shortId(s)} (tmux ${tgt}) — Ctrl-b d to detach.`));
+        process.exit(await attachTmux({ socket, args: ['attach-session', '-t', tgt] }));
+    }
+    // Path A: local Ghostty — focus its tab (Cmd+N via System Events).
+    if (s.host === 'ghostty') {
+        let tab;
+        try {
+            const surfaces = await enumerateGhosttyTabs();
+            tab = assignGhosttyTabs([s], surfaces).get(s);
+        }
+        catch { /* best-effort */ }
+        if (tab != null && tab <= 9) {
+            const script = `tell application "Ghostty" to activate\n` +
+                `delay 0.15\n` +
+                `tell application "System Events" to keystroke "${tab}" using command down`;
+            await execFileAsync('osascript', ['-e', script]).catch(() => { });
+            console.log(chalk.gray(`Focused ${shortId(s)} → Ghostty tab ${tab}.`));
+            return;
+        }
+        await execFileAsync('osascript', ['-e', 'tell application "Ghostty" to activate']).catch(() => { });
+        console.log(chalk.yellow(`Raised Ghostty for ${shortId(s)}`) +
+            chalk.gray(tab != null ? ` — switch to tab ${tab} (Cmd+${tab}).` : " — couldn't pinpoint its tab (same-repo forks are ambiguous); switch tabs manually."));
+        return;
+    }
+    // Path D: refuse with a reason.
+    console.log(chalk.yellow(`Can't jump to ${shortId(s)} — it's in ${s.host ?? 'an unknown terminal'} with no attach rail (not tmux/Ghostty).`) +
+        chalk.gray(`\nTry: agents sessions resume ${shortId(s)}`));
+}
+/** Resolve a local tmux pane id to its session name + window index. */
+async function resolveLocalPane(socket, pane) {
+    try {
+        const res = await runTmux({ socket, args: ['display-message', '-pt', pane, '-p', '#{session_name}\t#{window_index}'], throwOnError: false });
+        if (res.code !== 0)
+            return {};
+        const [session, win] = res.stdout.trim().split('\t');
+        const window = Number.parseInt(win, 10);
+        return { session: session || undefined, window: Number.isFinite(window) ? window : undefined };
+    }
+    catch {
+        return {};
+    }
+}

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

@@ -12,6 +12,8 @@ export interface SessionPickerConfig {
     labelFor: (s: SessionMeta, query: string) => string;
     pageSize?: number;
     initialSearch?: string;
+    /** Verb shown on the Enter key in the footer (default 'resume'). */
+    enterHint?: string;
 }
 /** Build a cached multi-line preview string for display in the session picker. */
 export declare function buildPreview(session: SessionMeta): string;

package/dist/commands/sessions-picker.js

@@ -5,6 +5,7 @@
  * Builds a compact preview for each session (prompt, activity summary, last
  * response) and delegates to the generic `itemPicker` for the interactive UI.
  */
+import fs from 'node:fs';
 import chalk from 'chalk';
 import { parseSession, sanitizeForTerminal } from '../lib/session/parse.js';
 import { cleanSessionPrompt, extractSessionTopic } from '../lib/session/prompt.js';
@@ -61,6 +62,14 @@ export function buildPreview(session) {
         previewCache.set(cacheKey, output);
         return output;
     }
+    // No transcript on disk — a live session not indexed locally, or a synthesized
+    // entry (e.g. `sessions go`). Show the header + a clean note, not a parse error.
+    if (!session.filePath || !fs.existsSync(session.filePath)) {
+        const note = '  ' + chalk.gray('Live session — full transcript not indexed here.');
+        const output = [formatHeader(safe, []), '', note].filter(Boolean).join('\n');
+        previewCache.set(cacheKey, output);
+        return output;
+    }
     let events = [];
     let parseError;
     try {
@@ -371,7 +380,7 @@ export async function sessionPicker(config) {
         pageSize: config.pageSize,
         initialSearch: config.initialSearch,
         emptyMessage: 'No sessions match.',
-        enterHint: 'resume',
+        enterHint: config.enterHint ?? 'resume',
     });
     if (!picked)
         return null;

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

@@ -7,6 +7,9 @@ import type { Command } from 'commander';
 interface SyncCmdOptions {
     verbose?: boolean;
     json?: boolean;
+    enable?: boolean;
+    disable?: boolean;
+    status?: boolean;
 }
 export declare function runSessionsSync(options: SyncCmdOptions): Promise<void>;
 export declare function registerSessionsSyncCommand(sessionsCmd: Command): void;

package/dist/commands/sessions-sync.js

@@ -5,9 +5,34 @@
  */
 import chalk from 'chalk';
 import { setHelpSections } from '../lib/help.js';
-import { isSyncConfigured, SYNC_BUNDLE } from '../lib/session/sync/config.js';
+import { isSyncConfigured, isSyncEnabled, setSyncEnabled, SYNC_BUNDLE, } from '../lib/session/sync/config.js';
 import { syncSessions } from '../lib/session/sync/sync.js';
 export async function runSessionsSync(options) {
+    // Toggle / status actions short-circuit before any network cycle.
+    if (options.disable) {
+        setSyncEnabled(false);
+        console.log(chalk.yellow('Automatic session sync disabled') +
+            chalk.dim(' — the daemon stops pushing/pulling within ~90s. Re-enable: agents sessions sync --enable'));
+        return;
+    }
+    if (options.enable) {
+        setSyncEnabled(true);
+        console.log(chalk.green('Automatic session sync enabled') + chalk.dim(' — the daemon resumes on its next cycle.'));
+        return;
+    }
+    if (options.status) {
+        const enabled = isSyncEnabled();
+        const configured = isSyncConfigured();
+        if (options.json) {
+            console.log(JSON.stringify({ enabled, configured }, null, 2));
+        }
+        else {
+            console.log(`automatic sync: ${enabled ? chalk.green('enabled') : chalk.yellow('disabled')}` +
+                chalk.dim('  ·  ') +
+                `credentials: ${configured ? chalk.green('configured') : chalk.yellow(`missing (${SYNC_BUNDLE})`)}`);
+        }
+        return;
+    }
     if (!isSyncConfigured()) {
         console.error(chalk.red(`Sessions sync is not configured.`) +
             `\nAdd R2 credentials to the '${SYNC_BUNDLE}' bundle:\n` +
@@ -51,7 +76,10 @@ export function registerSessionsSyncCommand(sessionsCmd) {
         .command('sync')
         .description('Sync session transcripts across machines via R2 (CRDT merge). Claude and Codex.')
         .option('-v, --verbose', 'Log each pushed and pulled session')
-        .option('--json', 'Output the sync result as JSON');
+        .option('--json', 'Output the sync result as JSON')
+        .option('--enable', 'Turn ON automatic background sync on this machine (persisted)')
+        .option('--disable', 'Turn OFF automatic background sync on this machine (persisted)')
+        .option('--status', 'Show whether automatic sync is enabled and configured');
     setHelpSections(syncCmd, {
         examples: `
       # One sync cycle (push local changes, pull + merge from other machines)
@@ -59,15 +87,27 @@ export function registerSessionsSyncCommand(sessionsCmd) {
 
       # See exactly what moved
       agents sessions sync --verbose
+
+      # Stop this machine's daemon from auto-syncing (prefer on-demand --host reads)
+      agents sessions sync --disable
+
+      # Check the current switch + credential state
+      agents sessions sync --status
     `,
         notes: `
       - Credentials come from the '${SYNC_BUNDLE}' secrets bundle (R2 S3 API, read+write).
       - Each machine writes only its own prefix; conflicts are impossible by construction.
       - The daemon runs this automatically (~90s); this command forces an immediate cycle.
       - Sessions present locally always win; synced-in copies fill in other machines' sessions.
+      - --disable/--enable persist a machine-local switch (~/.agents/.history) that gates the
+        daemon's automatic sync; a bare 'agents sessions sync' still forces a manual cycle.
+        The AGENTS_SESSIONS_SYNC env var (on/off) overrides the switch for one invocation.
     `,
     });
-    syncCmd.action(async (options) => {
-        await runSessionsSync(options);
+    // `--json` is also declared on the parent `sessions` command, so a bare
+    // `options` arg would miss it (Commander binds the shared flag to the parent).
+    // optsWithGlobals() merges ancestor + local options so --json resolves here.
+    syncCmd.action(async (_options, cmd) => {
+        await runSessionsSync(cmd.optsWithGlobals());
     });
 }

package/dist/commands/sessions.d.ts

@@ -2,6 +2,13 @@ import type { Command } from 'commander';
 import type { SessionAgentId, SessionMeta } from '../lib/session/types.js';
 import { type ActiveSession } from '../lib/session/active.js';
 import { type PickedSession } from './sessions-picker.js';
+/**
+ * Strip terminal/harness noise from a preview so the column stays a single line
+ * of plain prose: OSC title escapes, CSI/SGR ANSI, and the harness wrapper tags
+ * (`<local-command-stdout>`, `<task-notification>`, `<command-*>`) that leak from
+ * a captured transcript tail. Collapses runs of whitespace.
+ */
+export declare function cleanPreview(text: string): string;
 /**
  * Index live sessions by their full session UUID so a historical `SessionMeta`
  * row (`meta.id`) can be matched to the session that is still running now.
@@ -157,7 +164,7 @@ export declare function formatPickerLabel(s: SessionMeta, query: string, cols?:
  * so it stays fixed across the picker's re-renders within a single run.
  */
 export declare function formatPickerTip(sessions: SessionMeta[]): string;
-export declare function pickSessionInteractive(sessions: SessionMeta[], message?: string, initialSearch?: string, hiddenCount?: number): Promise<PickedSession | null>;
+export declare function pickSessionInteractive(sessions: SessionMeta[], message?: string, initialSearch?: string, hiddenCount?: number, enterHint?: string): Promise<PickedSession | null>;
 /**
  * Resume a session in the current terminal — a foreground takeover of this
  * process. Used by the single-select picker and by `sessions resume` when the