@phnx-labs/agents-cli 1.20.37 → 1.20.39

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
@@ -1572,12 +1616,16 @@ export function getShimPath(agent) {
  * loop because addShimsToPath() only edits the rc file, never the legacy
  * shim file itself.
  */
-export function getPathShadowingExecutable(agent) {
-    const pathDirs = (process.env.PATH || '').split(path.delimiter).filter(Boolean);
-    const shimPath = path.resolve(getShimPath(agent));
+export function getPathShadowingExecutable(agent, overrides) {
+    const pathDirs = overrides?.pathDirs ?? (process.env.PATH || '').split(path.delimiter).filter(Boolean);
+    const shimPath = path.resolve(overrides?.shimPath ?? getShimPath(agent));
     const cliCommand = AGENTS[agent].cliCommand;
     const legacyUserShim = path.resolve(path.join(os.homedir(), '.agents', 'shims', cliCommand));
     const managedShimExists = fs.existsSync(shimPath);
+    // The shim's own realpath — an adopted launcher is a symlink at a DIFFERENT
+    // path that resolves here, so identity must be by resolved target, not the
+    // literal path string.
+    const shimReal = managedShimExists ? canonicalOrNull(shimPath) : null;
     for (const dir of pathDirs) {
         const candidate = path.resolve(dir, cliCommand);
         if (!fs.existsSync(candidate)) {
@@ -1585,6 +1633,12 @@ export function getPathShadowingExecutable(agent) {
         }
         if (candidate === shimPath)
             return null;
+        // Adopted launcher: a symlink we repointed at our shim. Its path differs
+        // from shimPath but it resolves to the same file, so it is NOT a shadow —
+        // otherwise every adopted default would be re-flagged forever, resurfacing
+        // the false "runs a native binary" note this whole feature set out to kill.
+        if (shimReal && canonicalOrNull(candidate) === shimReal)
+            return null;
         if (candidate === legacyUserShim && managedShimExists) {
             // Legacy file from the pre-split layout. Don't treat as shadow — the
             // repair flow deletes it via removeLegacyUserShim instead. Continue
@@ -1630,6 +1684,189 @@ 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);
+    }
+}
+/** Like canonical(), but null when the path can't be resolved (broken/racy
+ * symlink) — used where a failed resolve must NOT collapse to the input path. */
+function canonicalOrNull(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 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.d.ts

@@ -13,7 +13,7 @@
  *   secrets  -> listRemoteBundles + pullBundle (needs a passphrase; skipped
  *               cleanly when none is available — tokenized non-interactive auth
  *               arrives with `agents login`, #366/#367)
- *   sessions -> syncSessions(), gated by isSyncConfigured() exactly like the daemon
+ *   sessions -> syncSessions(), gated by the session-sync beta opt-in + isSyncConfigured(), like the daemon
  *   reconcile-> refresh({ skipPrompts }) — re-materialize resources into homes
  */
 /** The five umbrella flags off `agents sync`. */

package/dist/lib/sync-umbrella.js

@@ -13,7 +13,7 @@
  *   secrets  -> listRemoteBundles + pullBundle (needs a passphrase; skipped
  *               cleanly when none is available — tokenized non-interactive auth
  *               arrives with `agents login`, #366/#367)
- *   sessions -> syncSessions(), gated by isSyncConfigured() exactly like the daemon
+ *   sessions -> syncSessions(), gated by the session-sync beta opt-in + isSyncConfigured(), like the daemon
  *   reconcile-> refresh({ skipPrompts }) — re-materialize resources into homes
  */
 import { pullRepo } from './git.js';
@@ -111,10 +111,12 @@ export async function runUmbrellaSync(args) {
         }
     }
     if (plan.fetchSessions) {
-        // 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()) {
+        // Gate exactly like the daemon: without the `session-sync` beta opt-in (or
+        // with a missing r2.backups bundle) this is a clean no-op, not an error that
+        // fails the whole sync.
+        const { isBetaEnabled } = await import('./beta.js');
+        const { isSyncConfigured } = await import('./session/sync/config.js');
+        if (isBetaEnabled('session-sync') && 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/types.d.ts

@@ -61,7 +61,7 @@ export interface BudgetConfig {
     require_confirm_over?: number;
 }
 /** Preview features that users can opt into via `agents beta`. */
-export type BetaFeatureName = 'drive' | 'factory';
+export type BetaFeatureName = 'drive' | 'factory' | 'session-sync';
 /** Subset of chalk color names used for agent-specific terminal output. */
 export type ChalkColor = 'magenta' | 'green' | 'blue' | 'cyan' | 'yellowBright' | 'redBright' | 'whiteBright' | 'blueBright' | 'greenBright' | 'magentaBright' | 'cyanBright';
 /** Static configuration for a single agent -- paths, capabilities, and format conventions. */

package/package.json

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