@phnx-labs/agents-cli 1.20.36 → 1.20.38

package/dist/lib/session/sync/config.js

@@ -3,9 +3,65 @@
  * machine's stable identity. Credentials come from the `r2.backups` secrets
  * bundle (OS keychain on macOS, libsecret on Linux) — never from env or disk.
  */
+import * as fs from 'fs';
+import * as path from 'path';
 import { readAndResolveBundleEnv } from '../../secrets/bundles.js';
+import { getHistoryDir } from '../../state.js';
 /** Secrets bundle holding the R2 credentials. */
 export const SYNC_BUNDLE = 'r2.backups';
+// ── Enable / disable switch ─────────────────────────────────────────────────
+// Whether the daemon's automatic cross-machine sync (and `agents sync
+// --sessions`) may run on THIS machine. Independent of credential presence
+// (isSyncConfigured): a machine can hold valid R2 creds yet still opt out of the
+// background push/pull — e.g. when on-demand `agents sessions --host` is
+// preferred over the ad-hoc R2 mirror. Manual `agents sessions sync` is an
+// explicit user action and is deliberately NOT gated by this switch.
+//
+// Resolution order: the AGENTS_SESSIONS_SYNC env var (a recognized on/off value
+// wins outright, for ad-hoc overrides and tests), then a durable machine-local
+// flag file, then the default (enabled). The flag lives in the durable
+// ~/.agents/.history tree — NOT .cache — so a cache wipe can never silently
+// re-enable a sync the operator turned off.
+/** Env var that overrides the persisted enable flag (on/off/true/false/1/0/yes/no). */
+export const SYNC_ENABLED_ENV = 'AGENTS_SESSIONS_SYNC';
+const SYNC_ENABLED_FILE = 'sessions-sync.json';
+const OFF_VALUES = new Set(['0', 'off', 'false', 'no', 'disabled']);
+const ON_VALUES = new Set(['1', 'on', 'true', 'yes', 'enabled']);
+/** Durable, machine-local path holding the sync enable flag. */
+export function syncStateFilePath() {
+    return path.join(getHistoryDir(), SYNC_ENABLED_FILE);
+}
+/**
+ * Whether automatic session sync is enabled on this machine. Defaults to true;
+ * an unrecognized env value falls through to the file; an absent/unreadable file
+ * falls through to the default. Read fresh every call (no memoization) so a
+ * `--disable` takes effect on the daemon's next ~90s cycle without a restart.
+ */
+export function isSyncEnabled() {
+    const envRaw = process.env[SYNC_ENABLED_ENV]?.trim().toLowerCase();
+    if (envRaw) {
+        if (OFF_VALUES.has(envRaw))
+            return false;
+        if (ON_VALUES.has(envRaw))
+            return true;
+        // Unrecognized value: ignore and consult the persisted flag.
+    }
+    try {
+        const parsed = JSON.parse(fs.readFileSync(syncStateFilePath(), 'utf-8'));
+        if (parsed && typeof parsed.enabled === 'boolean')
+            return parsed.enabled;
+    }
+    catch {
+        // Absent or unreadable → default enabled.
+    }
+    return true;
+}
+/** Persist the machine-local sync enable flag (durable across cache wipes). */
+export function setSyncEnabled(enabled) {
+    const p = syncStateFilePath();
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify({ enabled }, null, 2) + '\n', 'utf-8');
+}
 /**
  * Resolve R2 credentials from the `r2.backups` bundle. Throws a clear,
  * actionable error if the bundle or any key is missing — sync cannot proceed

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

@@ -46,6 +46,12 @@ export interface SessionMeta {
     shortId: string;
     agent: SessionAgentId;
     timestamp: string;
+    /**
+     * Last-activity time (ISO): the last message timestamp when a parser computed
+     * it, else file mtime, else `timestamp`. This is the recency signal the
+     * listing sorts and labels by; `timestamp` stays the creation time.
+     */
+    lastActivity?: string;
     project?: string;
     cwd?: string;
     filePath: string;

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/dist/lib/sync-umbrella.js

@@ -111,10 +111,10 @@ export async function runUmbrellaSync(args) {
         }
     }
     if (plan.fetchSessions) {
-        // Gate exactly like the daemon: a missing r2.backups bundle is a clean no-op,
-        // not an error that fails the whole sync.
-        const { isSyncConfigured } = await import('./session/sync/config.js');
-        if (isSyncConfigured()) {
+        // Gate exactly like the daemon: an off switch or a missing r2.backups bundle
+        // is a clean no-op, not an error that fails the whole sync.
+        const { isSyncConfigured, isSyncEnabled } = await import('./session/sync/config.js');
+        if (isSyncEnabled() && isSyncConfigured()) {
             const { syncSessions } = await import('./session/sync/sync.js');
             const r = await syncSessions();
             result.sessions = { ran: true, pushed: r.pushed, pulled: r.pulled, merged: r.merged };

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

@@ -70,6 +70,16 @@ export declare function killSession(name: string, socket?: string): Promise<bool
  * meta files. Wipes the socket so the next `new` starts from a clean slate.
  */
 export declare function killAll(socket?: string): Promise<number>;
+/**
+ * Map every pane id (`%N`) on a socket to its `session:window.pane` attach
+ * target, in one batched `tmux list-panes -a` call. `%116 -> main:2.0` is a
+ * valid `tmux attach -t main:2` / `tmux select-window -t main:2` target — a
+ * human jump target, unlike the bare `%pane` send-keys id. Because it walks
+ * every pane (not just one-per-session), it also surfaces multiple agents that
+ * share a session across windows. Best-effort: returns an empty map on any
+ * failure (tmux gone, foreign socket) so callers fall back to the raw pane id.
+ */
+export declare function mapPanesToTargets(socket?: string): Promise<Map<string, string>>;
 /**
  * List live sessions on the socket. Reconciles meta JSONs against tmux's view:
  *  - tmux session with no meta → returned without `meta` (external session)

package/dist/lib/tmux/session.js

@@ -156,6 +156,37 @@ export async function killAll(socket) {
     catch { /* may not exist */ }
     return count;
 }
+/**
+ * Map every pane id (`%N`) on a socket to its `session:window.pane` attach
+ * target, in one batched `tmux list-panes -a` call. `%116 -> main:2.0` is a
+ * valid `tmux attach -t main:2` / `tmux select-window -t main:2` target — a
+ * human jump target, unlike the bare `%pane` send-keys id. Because it walks
+ * every pane (not just one-per-session), it also surfaces multiple agents that
+ * share a session across windows. Best-effort: returns an empty map on any
+ * failure (tmux gone, foreign socket) so callers fall back to the raw pane id.
+ */
+export async function mapPanesToTargets(socket) {
+    const out = new Map();
+    let res;
+    try {
+        res = await runTmux({
+            socket,
+            args: ['list-panes', '-a', '-F', '#{pane_id} #{session_name}:#{window_index}.#{pane_index}'],
+            throwOnError: false,
+        });
+    }
+    catch {
+        return out;
+    }
+    if (res.code !== 0)
+        return out;
+    for (const line of res.stdout.split('\n')) {
+        const sp = line.indexOf(' ');
+        if (sp > 0)
+            out.set(line.slice(0, sp), line.slice(sp + 1).trim());
+    }
+    return out;
+}
 /**
  * List live sessions on the socket. Reconciles meta JSONs against tmux's view:
  *  - tmux session with no meta → returned without `meta` (external session)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.36",
+  "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",