@phnx-labs/agents-cli 1.20.37 → 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.d.ts

@@ -164,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

package/dist/commands/sessions.js

@@ -39,6 +39,7 @@ import { setHelpSections } from '../lib/help.js';
 import { registerSessionsTailCommand } from './sessions-tail.js';
 import { registerSessionsSyncCommand } from './sessions-sync.js';
 import { registerSessionsResumeCommand } from './sessions-resume.js';
+import { registerGoCommand } from './go.js';
 import { registerSessionsInjectCommand } from './sessions-inject.js';
 const SESSION_AGENT_FILTER_HELP = `Filter by agent, e.g. claude, codex, claude@2.0.65`;
 /**
@@ -664,6 +665,9 @@ function printCrossMachineTip() {
 }
 /** Main action handler for `agents sessions`. Routes to picker, table, or single-session render. */
 async function sessionsAction(query, options) {
+    // Explicit --query is interchangeable with the positional; it's how you search
+    // for text that collides with a subcommand name (e.g. `sessions --query go`).
+    query = query ?? options.query;
     // Normalize convenience flags before any routing reads them: per-agent
     // shorthands fold into --agent, and --device is an alias for --host (both
     // resolve against the same device registry).
@@ -1365,7 +1369,7 @@ const PICKER_TIPS = [
 export function formatPickerTip(sessions) {
     return chalk.gray(PICKER_TIPS[sessions.length % PICKER_TIPS.length]);
 }
-export async function pickSessionInteractive(sessions, message = 'Search sessions:', initialSearch, hiddenCount = 0) {
+export async function pickSessionInteractive(sessions, message = 'Search sessions:', initialSearch, hiddenCount = 0, enterHint) {
     if (hiddenCount > 0) {
         console.log(chalk.gray(formatTeamHiddenFooter(hiddenCount)));
     }
@@ -1385,6 +1389,7 @@ export async function pickSessionInteractive(sessions, message = 'Search session
             labelFor: (s, query) => formatPickerLabel(s, query, cols),
             pageSize: PICKER_RECENT_COUNT,
             initialSearch,
+            enterHint,
         });
     }
     catch (err) {
@@ -1888,6 +1893,7 @@ export function registerSessionsCommands(program) {
     const sessionsCmd = program
         .command('sessions')
         .argument('[query]', 'Session ID, search query, or path (., ../, /path) to filter by project')
+        .option('--query <text>', 'Search text — use when the term collides with a subcommand name (e.g. "go")')
         .description('Find, browse, and read agent conversation transcripts across Claude, Codex, Gemini, and OpenCode.')
         .option('-a, --agent <agent>', 'Filter by agent type and version (e.g., claude, codex@0.116.0)')
         .option('--claude', 'Shorthand for --agent claude')
@@ -1967,6 +1973,7 @@ export function registerSessionsCommands(program) {
     registerSessionsTailCommand(sessionsCmd);
     registerSessionsSyncCommand(sessionsCmd);
     registerSessionsResumeCommand(sessionsCmd);
+    registerGoCommand(sessionsCmd);
     registerSessionsInjectCommand(sessionsCmd);
 }
 function formatNoSessionsMessage(showAll, project) {

package/dist/index.js

@@ -483,7 +483,7 @@ async function maybeBootstrapShimIntegration(requestedCommand, helpOrVersionRequ
     const { confirm } = await import('@inquirer/prompts');
     const { AGENTS } = await import('./lib/agents.js');
     const { getGlobalDefault, listInstalledVersions } = await import('./lib/versions.js');
-    const { addShimsToPath, ensureShimCurrent, ensureVersionedAliasCurrent, getPathShadowingExecutable, getPathSetupInstructions, getShimsDir, isShimsInPath, listAgentsWithInstalledVersions, removeLegacyUserShim, } = await import('./lib/shims.js');
+    const { addShimsToPath, adoptShadowingLauncher, ensureShimCurrent, ensureVersionedAliasCurrent, getPathShadowingExecutable, getPathSetupInstructions, getShimsDir, isShimsInPath, listAgentsWithInstalledVersions, removeLegacyUserShim, } = await import('./lib/shims.js');
     const installedAgents = listAgentsWithInstalledVersions();
     if (installedAgents.length === 0) {
         return;
@@ -519,87 +519,78 @@ async function maybeBootstrapShimIntegration(requestedCommand, helpOrVersionRequ
         return;
     }
     const defaultAgents = installedAgents.filter((agent) => getGlobalDefault(agent));
+    // Auto-adopt any harness launcher that shadows our shim. PATH-order repair
+    // (below) cannot win against `~/.local/bin` — it's prepended in .zshenv for
+    // every shell while our prepend only lands in .zshrc — so for symlink
+    // launchers we *become* the launcher instead. Detection keys on the launcher
+    // symlink EXISTING (via adoptShadowingLauncher's own fallback), not on this
+    // shell's PATH order, so it also heals the GUI/non-interactive shadow an
+    // interactive run can't see. Reversible; only ever rewrites a symlink.
+    for (const agent of defaultAgents) {
+        const result = adoptShadowingLauncher(agent);
+        if (result.adopted) {
+            console.log(chalk.green(`Adopted ${AGENTS[agent].cliCommand} launcher (${result.launcher}) — version management now wins regardless of PATH order.`));
+        }
+    }
+    // Recompute AFTER adoption so anything we just took over drops out. What
+    // remains is a real binary we deliberately don't touch (adoption is
+    // symlink-only) — those get an honest one-time note, never a looping prompt.
     const shadowed = defaultAgents
         .map((agent) => ({ agent, shadowedBy: getPathShadowingExecutable(agent) }))
         .filter((item) => Boolean(item.shadowedBy));
-    // Shell aliases that call the same command with extra flags are intentional
-    // customization and don't break shim integration — `addShimsToPath` cannot
-    // touch them, so they don't belong in the repair prompt. We previously
-    // computed an `aliased` list here and inserted it into `affected`, which
-    // contradicted the comment below and surfaced false positives (e.g. an
-    // earlier `alias codex=...` cancelled by a later `unalias codex` was
-    // reported because the detector did a static rc-file regex).
-    if (shadowed.length === 0 && isShimsInPath()) {
+    // After adoption, the only things left are (a) real-binary shadows we won't
+    // touch, and (b) a genuinely missing PATH entry. Nothing else needs the user.
+    const pathMissing = !isShimsInPath();
+    if (shadowed.length === 0 && !pathMissing) {
         return;
     }
-    // Suppress repeated prompts within the same shell. A successful rc-file
-    // edit doesn't reload the parent shell, so the next invocation sees the
-    // same PATH and re-fires detection. The sentinel survives only as long as
-    // the parent shell process — once the user opens a new terminal, the
-    // PPID changes and the prompt is allowed again.
+    // Suppress repeated notices within the same shell. A successful rc-file edit
+    // doesn't reload the parent shell, so the next invocation re-fires detection.
+    // The sentinel survives only as long as the parent shell process — a new
+    // terminal (new PPID) is allowed to surface it again.
     const sentinelPath = path.join(os.tmpdir(), `agents-shim-prompted-${process.ppid}`);
     if (fs.existsSync(sentinelPath)) {
         return;
     }
-    const affected = [];
-    for (const { agent, shadowedBy } of shadowed) {
-        affected.push(`${AGENTS[agent].cliCommand} -> ${shadowedBy}`);
-    }
-    if (affected.length === 0) {
-        // Pure PATH-not-loaded case: rc may already have the shim block, but the
-        // running shell hasn't sourced it. Don't list agents here — they aren't
-        // broken; only the PATH is stale. The prompt + post-message handle it.
-        affected.push('PATH entry missing');
-    }
-    const shouldRepair = await confirm({
-        message: `Repair shim integration now? ${affected.join(', ')}`,
-        default: true,
-    });
-    if (!shouldRepair) {
-        console.log(chalk.yellow('Shim integration still needs attention.'));
-        console.log(chalk.gray(getPathSetupInstructions()));
-        try {
-            fs.writeFileSync(sentinelPath, '1');
-        }
-        catch { /* best-effort */ }
-        return;
-    }
-    const pathResult = addShimsToPath();
-    if (!pathResult.success) {
-        console.log(chalk.yellow('Could not repair shim PATH setup automatically.'));
-        console.log(chalk.gray(pathResult.error || getPathSetupInstructions()));
-        // Write the sentinel even on failure — otherwise an unwritable rc file
-        // re-prompts every invocation in the same shell. The user opens a new
-        // terminal (new PPID) to retry.
-        try {
-            fs.writeFileSync(sentinelPath, '1');
-        }
-        catch { /* best-effort */ }
-        return;
+    // Real-binary shadows: adoption is symlink-only (we never rename a real native
+    // binary), and `addShimsToPath` provably can't outrank an early-PATH dir like
+    // ~/.local/bin across zsh's whole sourcing chain. So DON'T offer a "Repair?"
+    // prompt here — that was the infinite-loop bug (Yes was always a no-op).
+    // Inform once and point at the real levers.
+    if (shadowed.length > 0) {
+        const targets = shadowed
+            .map(({ agent, shadowedBy }) => `  ${AGENTS[agent].cliCommand}: ${shadowedBy}`)
+            .join('\n');
+        console.log(chalk.yellow('These agent commands run a native binary instead of the version-managed shim:'));
+        console.log(chalk.gray(targets));
+        console.log(chalk.gray(`It's a real binary (not a symlink), so agents-cli won't move it. To hand it to agents-cli, remove/reorder it, or put ${getShimsDir()} earlier in PATH.`));
     }
-    // When the rc file already has the canonical shim block, `addShimsToPath`
-    // is a no-op — re-emitting produced byte-identical content. In this branch
-    // the user clicked "Yes" but nothing changed on disk, AND the underlying
-    // cause (a real binary shadow, or a stale shell PATH) is unaffected by
-    // this command. Be honest about it and point at the actual action.
-    if (pathResult.alreadyPresent) {
-        if (shadowed.length > 0) {
-            const targets = shadowed
-                .map(({ agent, shadowedBy }) => `  ${AGENTS[agent].cliCommand}: ${shadowedBy}`)
-                .join('\n');
-            console.log(chalk.yellow('Repair could not change anything — the shim is shadowed by another binary on PATH:'));
-            console.log(chalk.gray(targets));
-            console.log(chalk.gray(`Fix it by removing or reordering that binary, or making sure ${getShimsDir()} appears earlier in PATH than its parent dir.`));
+    // Genuinely-missing PATH entry is the one thing addShimsToPath actually fixes,
+    // so it's the only case that still earns an interactive prompt.
+    if (pathMissing) {
+        const shouldRepair = await confirm({
+            message: 'Add the agents-cli shims directory to your PATH now?',
+            default: true,
+        });
+        if (!shouldRepair) {
+            console.log(chalk.gray(getPathSetupInstructions()));
         }
         else {
-            console.log(chalk.yellow(`Shim PATH entry is already in ~/${pathResult.rcFile} — this shell just needs to reload it.`));
-            console.log(chalk.gray(`Run: source ~/${pathResult.rcFile}   (or open a new terminal)`));
+            const pathResult = addShimsToPath();
+            if (!pathResult.success) {
+                console.log(chalk.yellow('Could not update PATH automatically.'));
+                console.log(chalk.gray(pathResult.error || getPathSetupInstructions()));
+            }
+            else if (pathResult.alreadyPresent) {
+                console.log(chalk.yellow(`Shim PATH entry is already in ~/${pathResult.rcFile} — this shell just needs to reload it.`));
+                console.log(chalk.gray(`Run: source ~/${pathResult.rcFile}   (or open a new terminal)`));
+            }
+            else {
+                console.log(chalk.green(`Added shims to PATH in ~/${pathResult.rcFile}`));
+                console.log(chalk.gray(getPathSetupInstructions()));
+            }
         }
     }
-    else {
-        console.log(chalk.green(`Repaired shim PATH setup in ~/${pathResult.rcFile}`));
-        console.log(chalk.gray(getPathSetupInstructions()));
-    }
     try {
         fs.writeFileSync(sentinelPath, '1');
     }

package/dist/lib/session/active.d.ts

@@ -89,6 +89,12 @@ export interface ActiveQueryOptions {
     /** Skip the `ps` scan for ad-hoc headless agents. */
     skipHeadless?: boolean;
 }
+/**
+ * Locate the live transcript for an agent process. Claude files are keyed by
+ * cwd (+ optional session uuid); Codex files are date-partitioned, so we resolve
+ * the newest indexed Codex session for the cwd instead.
+ */
+export declare function findSessionFileForKind(kind: string, cwd?: string, sessionId?: string): string | undefined;
 /** Live teams teammates. Reuses AgentManager which already polls PIDs via `kill -0`. */
 export declare function listTeamsActive(): Promise<ActiveSession[]>;
 /** Live editor-terminal agents across every IDE window. */

package/dist/lib/session/active.js

@@ -161,7 +161,7 @@ function classifyActivity(sessionFile) {
  * cwd (+ optional session uuid); Codex files are date-partitioned, so we resolve
  * the newest indexed Codex session for the cwd instead.
  */
-function findSessionFileForKind(kind, cwd, sessionId) {
+export function findSessionFileForKind(kind, cwd, sessionId) {
     if (!cwd)
         return undefined;
     if (kind === 'claude')

package/dist/lib/shims.d.ts

@@ -77,7 +77,7 @@ export interface ConflictInfo {
  *         top-level entry add/remove — deep edits to plugin contents won't
  *         trigger auto-resync, run `agents sync` for that.
  */
-export declare const SHIM_SCHEMA_VERSION = 22;
+export declare const SHIM_SCHEMA_VERSION = 23;
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.
@@ -311,6 +311,70 @@ export declare function getPathShadowingExecutable(agent: AgentId): string | nul
 export declare function removeLegacyUserShim(agent: AgentId, overrides?: {
     homeDir?: string;
 }): boolean;
+/**
+ * Where an adopted launcher's provenance is recorded. Lives under durable
+ * `.history` (NOT the regenerable `.cache`) so the reverse pointer to the native
+ * binary survives a cache wipe — the shim reads it to fall through to the native
+ * binary by absolute path when no managed version resolves. Two lines:
+ * line 1 = original binary, line 2 = launcher path (for `--release`).
+ */
+export declare function getAdoptedRecordPath(agent: AgentId, historyDir?: string): string;
+/**
+ * The launcher a harness's own installer drops in an early-PATH dir. Detection
+ * for adoption keys on the launcher *existing as a symlink resolving outside our
+ * shims dir* — NOT on current PATH order. That's deliberate: the shim only loses
+ * PATH races in non-interactive / GUI-launched shells, which an interactive
+ * `agents` run can't observe via its own PATH. Keying on the durable symlink lets
+ * auto-adoption fire for those users too. Returns the launcher path or null.
+ */
+export declare function findAdoptableLauncher(agent: AgentId, overrides?: {
+    homeDir?: string;
+    shimsDir?: string;
+}): string | null;
+export type AdoptResult = {
+    adopted: true;
+    launcher: string;
+    original: string;
+} | {
+    adopted: false;
+    reason: 'no-shadow' | 'already-adopted' | 'not-a-symlink' | 'unsafe-target' | 'error';
+    launcher?: string;
+};
+/**
+ * Adopt the harness's own launcher that shadows our shim on PATH.
+ *
+ * PATH-ordering fixes (editing rc files) can never reliably win: `~/.local/bin`
+ * (where grok/droid/etc. self-install) is prepended in `.zshenv`/`.zprofile`
+ * for *every* shell, while our shims prepend only lands in `.zshrc`
+ * (interactive). No single rc file guarantees "last prepend wins" across zsh's
+ * whole sourcing chain, so the shim loses in non-interactive / GUI-launched
+ * contexts. Instead of fighting PATH order, we *become* the launcher: replace
+ * the shadowing symlink with one pointing at our shim, and record the real
+ * original so the shim falls through to it when no managed version is selected.
+ *
+ * Regression bounds:
+ * - Only ever touches a **symlink** (never renames/deletes a real binary).
+ * - Records the resolved original + launcher path for lossless restore
+ *   (`releaseAdoptedLauncher`), in durable `.history` so a cache wipe can't
+ *   orphan the reverse pointer.
+ * - Idempotent: a no-op once the launcher already points at our shim.
+ * - Never records our own shim as the "original" (would loop).
+ */
+export declare function adoptShadowingLauncher(agent: AgentId, overrides?: {
+    shadowedBy?: string;
+    shimsDir?: string;
+    historyDir?: string;
+}): AdoptResult;
+/**
+ * Undo `adoptShadowingLauncher`: repoint the launcher back at the recorded
+ * original and drop the record. Reversible escape hatch for users who want the
+ * native launcher to win. Returns the restored original path, or null if there
+ * was nothing to release.
+ */
+export declare function releaseAdoptedLauncher(agent: AgentId, overrides?: {
+    shimsDir?: string;
+    historyDir?: string;
+}): string | null;
 export declare function hasAliasShadowingShim(agent: AgentId, overrides?: {
     homeDir?: string;
 }): boolean;

package/dist/lib/shims.js

@@ -14,7 +14,7 @@ import * as os from 'os';
 import { fileURLToPath } from 'url';
 import { confirm, select } from '@inquirer/prompts';
 import { IS_WINDOWS, prependToWindowsUserPath } from './platform/index.js';
-import { getShimsDir, getVersionsDir, getBackupsDir, ensureAgentsDir } from './state.js';
+import { getShimsDir, getVersionsDir, getBackupsDir, getHistoryDir, ensureAgentsDir } from './state.js';
 export { getShimsDir };
 import { AGENTS, agentConfigDirName } from './agents.js';
 /**
@@ -211,7 +211,7 @@ async function promptConflictStrategy(conflictInfos) {
 // v22 — export DISABLE_AUTOUPDATER=1 for claude shims so a pinned per-version
 //        install can't self-mutate: Claude Code's background auto-updater would
 //        otherwise rewrite the pinned binary in place. Explicit user value wins.
-export const SHIM_SCHEMA_VERSION = 22;
+export const SHIM_SCHEMA_VERSION = 23;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
 function shellQuote(value) {
@@ -295,6 +295,33 @@ if [ -z "$AGENTS_BIN" ] || [ ! -x "$AGENTS_BIN" ]; then
   exit 127
 fi
 
+# When agents-cli "adopts" a harness's own launcher (symlinks the native binary
+# in ~/.local/bin to this dispatcher so version management wins regardless of
+# PATH order), it records the real original here. Durable (.history, not the
+# regenerable .cache) so the reverse pointer survives a cache wipe. Line 1 is
+# the original binary (what we fall through to); line 2 is the launcher path
+# (used by --release). It is the only safe fall-through target: exec it by
+# ABSOLUTE PATH so we never re-resolve through PATH (which now points back at
+# this dispatcher → infinite re-exec loop).
+ADOPTED_ORIGINAL="$AGENTS_USER_DIR/.history/adopted-launchers/$CLI_COMMAND"
+# Print the recorded original binary iff it is an executable file, else nothing.
+adopted_original_bin() {
+  [ -f "$ADOPTED_ORIGINAL" ] || return 1
+  local orig
+  # First line only — line 2 (launcher path) is for --release, not exec.
+  IFS= read -r orig < "$ADOPTED_ORIGINAL" 2>/dev/null || return 1
+  [ -n "$orig" ] && [ -x "$orig" ] || return 1
+  printf '%s' "$orig"
+}
+# Last-resort fall-through: if a managed version can't be resolved but we've
+# adopted this command's native launcher, run the original so the user's command
+# never breaks. Replaces the process; returns non-zero only when no usable record.
+exec_adopted_original() {
+  local orig
+  orig=$(adopted_original_bin) || return 1
+  exec "$orig" "$@"
+}
+
 # Find project agents.yaml walking up from cwd (skip $HOME/.agents/agents.yaml)
 find_project_version() {
   local dir="$PWD"
@@ -378,15 +405,20 @@ if [ -z "$VERSION" ]; then
           VERSION_SOURCE="default"
           ;;
         *)
+          exec_adopted_original "$@"
           echo "  Run: agents use $AGENT <version>" >&2
           exit 1
           ;;
       esac
     else
+      exec_adopted_original "$@"
       echo "  Run: agents use $AGENT <version>" >&2
       exit 1
     fi
   else
+    # No managed version at all. If we adopted this command's native launcher,
+    # run it so the command keeps working; otherwise report it's unconfigured.
+    exec_adopted_original "$@"
     echo "agents: no version of $AGENT configured" >&2
     echo "  Run: agents add $AGENT@<version>" >&2
     exit 1
@@ -414,16 +446,18 @@ if [ "$AGENT" = "grok" ]; then
     fi
   fi
   if [ -z "$BINARY" ] || [ ! -x "$BINARY" ]; then
-    # Last resort: whatever is on PATH (user may have installed grok globally).
-    # Refuse anything under our own shims dir: the shims dir sits ahead of
-    # ~/.local/bin on PATH, so "command -v grok" resolves to THIS dispatcher.
-    # exec-ing it would re-enter and spin in an infinite re-exec loop (the same
-    # bug the droid branch below guards against). Fall through to the clean
-    # "not installed" error instead.
-    BINARY=$(command -v grok 2>/dev/null || echo "")
-    case "$BINARY" in
-      "$AGENTS_USER_DIR/.cache/shims/"*) BINARY="" ;;
-    esac
+    # Last resort: the adopted native launcher (recorded absolute path) if we
+    # adopted grok, else whatever is on PATH. Prefer the adopted record — after
+    # adoption, "command -v grok" resolves to the ~/.local/bin symlink that now
+    # points at THIS dispatcher, so exec-ing it would re-enter and spin forever.
+    BINARY=$(adopted_original_bin || echo "")
+    if [ -z "$BINARY" ]; then
+      BINARY=$(command -v grok 2>/dev/null || echo "")
+      # Refuse anything that resolves into our own shims dir (the dispatcher).
+      case "$(command -v "$BINARY" 2>/dev/null; readlink -f "$BINARY" 2>/dev/null)" in
+        *"$AGENTS_USER_DIR/.cache/shims/"*) BINARY="" ;;
+      esac
+    fi
   fi
 # Kimi is a normal npm agent: "agents add kimi" npm-installs
 # @moonshot-ai/kimi-code into the version dir and the binary lands at
@@ -440,14 +474,20 @@ if [ "$AGENT" = "grok" ]; then
 # IS this dispatcher, so exec'ing it would re-enter and spin in an infinite
 # re-exec loop (the bug this branch fixes).
 elif [ "$AGENT" = "droid" ]; then
-  DROID_BINARY="$HOME/.local/bin/droid"
-  if [ -x "$DROID_BINARY" ]; then
-    BINARY="$DROID_BINARY"
-  else
-    BINARY=$(command -v droid 2>/dev/null || echo "")
-    case "$BINARY" in
-      "$AGENTS_USER_DIR/.cache/shims/"*) BINARY="" ;;
-    esac
+  # Prefer the adopted record first: if droid's ~/.local/bin/droid launcher was
+  # adopted, that fixed path now points at THIS dispatcher, so using it directly
+  # would infinite-loop. The record holds the real original binary.
+  BINARY=$(adopted_original_bin || echo "")
+  if [ -z "$BINARY" ]; then
+    DROID_BINARY="$HOME/.local/bin/droid"
+    if [ -x "$DROID_BINARY" ] && [ "$(readlink -f "$DROID_BINARY" 2>/dev/null)" != "$(readlink -f "$AGENTS_USER_DIR/.cache/shims/$CLI_COMMAND" 2>/dev/null)" ]; then
+      BINARY="$DROID_BINARY"
+    else
+      BINARY=$(command -v droid 2>/dev/null || echo "")
+      case "$(readlink -f "$BINARY" 2>/dev/null)" in
+        "$AGENTS_USER_DIR/.cache/shims/"*) BINARY="" ;;
+      esac
+    fi
   fi
 else
   BINARY="$VERSION_DIR/node_modules/.bin/$CLI_COMMAND"
@@ -481,6 +521,7 @@ if [ ! -x "$BINARY" ]; then
       echo "  ✔ Installed $AGENT@$VERSION" >&2
     else
       echo "  ✗ Failed to install $AGENT@$VERSION" >&2
+      exec_adopted_original "$@"
       exit 1
     fi
   else
@@ -498,15 +539,18 @@ if [ ! -x "$BINARY" ]; then
             BINARY="$VERSION_DIR/node_modules/.bin/$CLI_COMMAND"
             ;;
           *)
+            exec_adopted_original "$@"
             echo "  Run: agents add $AGENT@$VERSION" >&2
             exit 1
             ;;
         esac
       else
+        exec_adopted_original "$@"
         echo "  Run: agents add $AGENT@$VERSION" >&2
         exit 1
       fi
     else
+      exec_adopted_original "$@"
       echo "agents: $AGENT@$VERSION not installed" >&2
       echo "  Run: agents add $AGENT@$VERSION" >&2
       exit 1
@@ -1630,6 +1674,179 @@ export function removeLegacyUserShim(agent, overrides) {
         return false;
     }
 }
+/**
+ * Where an adopted launcher's provenance is recorded. Lives under durable
+ * `.history` (NOT the regenerable `.cache`) so the reverse pointer to the native
+ * binary survives a cache wipe — the shim reads it to fall through to the native
+ * binary by absolute path when no managed version resolves. Two lines:
+ * line 1 = original binary, line 2 = launcher path (for `--release`).
+ */
+export function getAdoptedRecordPath(agent, historyDir = getHistoryDir()) {
+    return path.join(historyDir, 'adopted-launchers', AGENTS[agent].cliCommand);
+}
+/**
+ * The launcher a harness's own installer drops in an early-PATH dir. Detection
+ * for adoption keys on the launcher *existing as a symlink resolving outside our
+ * shims dir* — NOT on current PATH order. That's deliberate: the shim only loses
+ * PATH races in non-interactive / GUI-launched shells, which an interactive
+ * `agents` run can't observe via its own PATH. Keying on the durable symlink lets
+ * auto-adoption fire for those users too. Returns the launcher path or null.
+ */
+export function findAdoptableLauncher(agent, overrides) {
+    const cliCommand = AGENTS[agent].cliCommand;
+    const homeDir = overrides?.homeDir ?? os.homedir();
+    const shimsDirReal = canonical(overrides?.shimsDir ?? getShimsDir());
+    // ~/.local/bin is where grok/kimi/antigravity/claude/codex/droid self-install.
+    const candidate = path.join(homeDir, '.local', 'bin', cliCommand);
+    let stat;
+    try {
+        stat = fs.lstatSync(candidate);
+    }
+    catch {
+        return null;
+    }
+    if (!stat.isSymbolicLink())
+        return null; // real binaries are never auto-adopted
+    let resolved;
+    try {
+        resolved = fs.realpathSync(candidate); // broken symlink throws → skip
+    }
+    catch {
+        return null;
+    }
+    // Already ours, or resolves into our shims dir → not adoptable.
+    if (resolved === shimsDirReal || resolved.startsWith(shimsDirReal + path.sep))
+        return null;
+    return candidate;
+}
+/** Canonical path for identity comparison — realpath when it exists (resolves
+ * symlinks AND platform aliases like macOS /var → /private/var), else resolve. */
+function canonical(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+/**
+ * Adopt the harness's own launcher that shadows our shim on PATH.
+ *
+ * PATH-ordering fixes (editing rc files) can never reliably win: `~/.local/bin`
+ * (where grok/droid/etc. self-install) is prepended in `.zshenv`/`.zprofile`
+ * for *every* shell, while our shims prepend only lands in `.zshrc`
+ * (interactive). No single rc file guarantees "last prepend wins" across zsh's
+ * whole sourcing chain, so the shim loses in non-interactive / GUI-launched
+ * contexts. Instead of fighting PATH order, we *become* the launcher: replace
+ * the shadowing symlink with one pointing at our shim, and record the real
+ * original so the shim falls through to it when no managed version is selected.
+ *
+ * Regression bounds:
+ * - Only ever touches a **symlink** (never renames/deletes a real binary).
+ * - Records the resolved original + launcher path for lossless restore
+ *   (`releaseAdoptedLauncher`), in durable `.history` so a cache wipe can't
+ *   orphan the reverse pointer.
+ * - Idempotent: a no-op once the launcher already points at our shim.
+ * - Never records our own shim as the "original" (would loop).
+ */
+export function adoptShadowingLauncher(agent, overrides) {
+    const shimsDir = overrides?.shimsDir ?? getShimsDir();
+    const shimPath = path.join(shimsDir, AGENTS[agent].cliCommand);
+    const shimReal = canonical(shimPath);
+    const shimsDirReal = canonical(shimsDir);
+    const launcher = overrides?.shadowedBy ?? getPathShadowingExecutable(agent) ?? findAdoptableLauncher(agent, { shimsDir });
+    if (!launcher)
+        return { adopted: false, reason: 'no-shadow' };
+    let stat;
+    try {
+        stat = fs.lstatSync(launcher);
+    }
+    catch {
+        return { adopted: false, reason: 'error', launcher };
+    }
+    // Only adopt symlinks. A real binary in an early-PATH dir is left untouched —
+    // renaming a multi-hundred-MB native binary is exactly the kind of surprise
+    // this feature must avoid. (Its shim stays reachable via the versioned name.)
+    if (!stat.isSymbolicLink()) {
+        return { adopted: false, reason: 'not-a-symlink', launcher };
+    }
+    const resolved = canonical(launcher);
+    // Already ours → nothing to do.
+    if (resolved === shimReal) {
+        return { adopted: false, reason: 'already-adopted', launcher };
+    }
+    // Never record a target that resolves back into our shims dir: exec-ing it
+    // from the shim would re-enter this dispatcher and spin forever.
+    if (resolved === shimsDirReal || resolved.startsWith(shimsDirReal + path.sep)) {
+        return { adopted: false, reason: 'unsafe-target', launcher };
+    }
+    try {
+        const recordPath = getAdoptedRecordPath(agent, overrides?.historyDir);
+        fs.mkdirSync(path.dirname(recordPath), { recursive: true });
+        // Line 1: original binary (shim fall-through target). Line 2: launcher path
+        // (release restores this exact symlink, independent of PATH order at release
+        // time — the M3 fix). Absolute launcher path so release never has to
+        // re-derive it from a PATH scan that may miss.
+        fs.writeFileSync(recordPath, `${resolved}\n${path.resolve(launcher)}\n`, 'utf-8');
+        // Repoint the launcher at our shim. rm + symlink (not atomic rename) is fine
+        // here: the record is already written, so a crash between the two leaves a
+        // recoverable state and the next run re-adopts idempotently.
+        fs.rmSync(launcher);
+        fs.symlinkSync(shimPath, launcher);
+        return { adopted: true, launcher, original: resolved };
+    }
+    catch {
+        return { adopted: false, reason: 'error', launcher };
+    }
+}
+/**
+ * Undo `adoptShadowingLauncher`: repoint the launcher back at the recorded
+ * original and drop the record. Reversible escape hatch for users who want the
+ * native launcher to win. Returns the restored original path, or null if there
+ * was nothing to release.
+ */
+export function releaseAdoptedLauncher(agent, overrides) {
+    const shimsDir = overrides?.shimsDir ?? getShimsDir();
+    const recordPath = getAdoptedRecordPath(agent, overrides?.historyDir);
+    let lines;
+    try {
+        lines = fs.readFileSync(recordPath, 'utf-8').split('\n').map((l) => l.trim());
+    }
+    catch {
+        return null;
+    }
+    const original = lines[0] ?? '';
+    if (!original)
+        return null;
+    // Line 2 is the exact launcher we rewrote at adopt time. Restoring it directly
+    // (rather than re-deriving from PATH) means release works regardless of the
+    // current shell's PATH order — the M3 fix. Fall back to a PATH scan only for
+    // records written before this format existed.
+    const launcher = lines[1] || getPathShadowingExecutable(agent) || original;
+    const shimReal = canonical(path.join(shimsDir, AGENTS[agent].cliCommand));
+    try {
+        // Only rewrite the launcher if it currently points at our shim (i.e. we own
+        // it). If the user has since replaced it themselves, leave it alone.
+        let pointsAtShim = false;
+        try {
+            pointsAtShim = fs.lstatSync(launcher).isSymbolicLink()
+                && canonical(launcher) === shimReal;
+        }
+        catch { /* launcher gone — recreate below */ }
+        if (pointsAtShim || !fs.existsSync(launcher)) {
+            try {
+                fs.rmSync(launcher);
+            }
+            catch { /* may not exist */ }
+            fs.symlinkSync(original, launcher);
+        }
+        fs.rmSync(recordPath);
+        return original;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Check if the agent's CLI command is shadowed by a shell alias.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.37",
+  "version": "1.20.38",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",