@phnx-labs/agents-cli 1.20.37 → 1.20.39

package/dist/commands/sessions.d.ts

@@ -98,6 +98,24 @@ export declare function dedupeByMachineSession(sessions: ActiveSession[]): Activ
  * `localMachine` is injected so the ordering is testable without os.hostname().
  */
 export declare function mergeLocalFirst(sessions: SessionMeta[], localMachine: string): SessionMeta[];
+/**
+ * Whether the local machine's sessions belong in an `--active` view. Local is
+ * included by default; an explicit `--host`/`--device` list scopes the view to
+ * exactly those machines, so local is dropped unless it is itself named (by
+ * alias or `user@host`, matched on the normalized machine id). Exported for
+ * unit testing without touching SSH or the live process table.
+ */
+export declare function shouldIncludeLocal(hosts: string[] | undefined, self: string): boolean;
+/**
+ * The peers to dial for an `--active` view. No `--host` → `undefined`, which
+ * tells `gatherRemoteActive` to sweep the registered online devices. An
+ * explicit list → exactly those, minus this machine (its sessions come from the
+ * local seed, so dialing self would be a wasted SSH and a spurious "unreachable"
+ * note). Returns `[]` when the only named host is self — the caller then skips
+ * the remote fan-out entirely rather than letting `[]` trigger the sweep.
+ * Exported for unit testing.
+ */
+export declare function remoteHostsToDial(hosts: string[] | undefined, self: string): string[] | undefined;
 /**
  * Group key for the overview: prefer the indexed project name; else fold the cwd
  * to its repo — a worktree (`.../<repo>/.agents/worktrees/<slug>`) folds to the
@@ -164,7 +182,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`;
 /**
@@ -600,25 +601,65 @@ async function enrichLocalLocators(local) {
     }
     catch { /* non-fatal */ }
 }
+/** Normalize a `--host`/`--device` token (`alias`, `user@host`, `host.domain`)
+ * to the machine id the fan-out and registry key off. */
+function hostToken(h) {
+    return normalizeHost(h.split('@').pop() || h);
+}
 /**
- * Render the unified active-session view, grouped by machine. Local sessions
- * come from `getActiveSessions()`; unless `--local`, sessions from other
- * machines are folded in over SSH (explicit `--host` targets, else the
- * registered online devices from `ag devices`). A tip is shown when there are
- * no other machines to include.
+ * Whether the local machine's sessions belong in an `--active` view. Local is
+ * included by default; an explicit `--host`/`--device` list scopes the view to
+ * exactly those machines, so local is dropped unless it is itself named (by
+ * alias or `user@host`, matched on the normalized machine id). Exported for
+ * unit testing without touching SSH or the live process table.
+ */
+export function shouldIncludeLocal(hosts, self) {
+    if (!hosts || hosts.length === 0)
+        return true;
+    return hosts.some(h => hostToken(h) === self);
+}
+/**
+ * The peers to dial for an `--active` view. No `--host` → `undefined`, which
+ * tells `gatherRemoteActive` to sweep the registered online devices. An
+ * explicit list → exactly those, minus this machine (its sessions come from the
+ * local seed, so dialing self would be a wasted SSH and a spurious "unreachable"
+ * note). Returns `[]` when the only named host is self — the caller then skips
+ * the remote fan-out entirely rather than letting `[]` trigger the sweep.
+ * Exported for unit testing.
+ */
+export function remoteHostsToDial(hosts, self) {
+    if (!hosts || hosts.length === 0)
+        return undefined;
+    return hosts.filter(h => hostToken(h) !== self);
+}
+/**
+ * Render the unified active-session view, grouped by machine. With no `--host`,
+ * local sessions come from `getActiveSessions()` and (unless `--local`) the
+ * registered online devices from `ag devices` are folded in over SSH. An
+ * explicit `--host`/`--device` list SCOPES the view to exactly those machines —
+ * the local machine is included only when it is itself named — so `--host` is a
+ * filter, not an addition (matching the non-`--active` listing path). A tip is
+ * shown when there are no other machines to include.
  */
 async function renderActiveSessions(asJson, waitingOnly = false, opts = {}) {
     const self = machineId();
-    const local = await getActiveSessions();
+    // An explicit --host/--device list scopes the view: seed local sessions only
+    // when no hosts are named, or when this machine is one of the named targets.
+    const local = shouldIncludeLocal(opts.hosts, self) ? await getActiveSessions() : [];
     for (const s of local)
         if (!s.machine)
             s.machine = self;
     let remoteDeviceCount = 0;
     let merged = local;
     if (!opts.local) {
-        const remote = await gatherRemoteActive(opts.hosts);
-        remoteDeviceCount = remote.deviceCount;
-        merged = dedupeByMachineSession([...local, ...remote.sessions]);
+        const remoteHosts = remoteHostsToDial(opts.hosts, self);
+        // An explicit list naming only self leaves nothing remote to dial — skip the
+        // fan-out rather than let an empty list fall through to the device sweep.
+        if (!opts.hosts?.length || (remoteHosts && remoteHosts.length > 0)) {
+            const remote = await gatherRemoteActive(remoteHosts);
+            remoteDeviceCount = remote.deviceCount;
+            merged = dedupeByMachineSession([...local, ...remote.sessions]);
+        }
     }
     // --waiting: only sessions blocked on the user. Exits non-zero when any are
     // present so a supervising agent or hook can poll it as a gate.
@@ -664,6 +705,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 +1409,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 +1429,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 +1933,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 +2013,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/beta.d.ts

@@ -8,7 +8,7 @@
  * checks.
  */
 import type { BetaFeatureName } from './types.js';
-export declare const ALL_BETA_FEATURES: readonly ["drive", "factory"];
+export declare const ALL_BETA_FEATURES: readonly ["drive", "factory", "session-sync"];
 export declare function getEnabledBetaFeatures(): BetaFeatureName[];
 export declare function isBetaEnabled(feature: BetaFeatureName): boolean;
 export declare function getBetaConfigLocation(): {

package/dist/lib/beta.js

@@ -10,7 +10,7 @@
 import * as path from 'path';
 import { getAgentsDir, getOptionalUserAgentsDir, readMeta, writeMeta } from './state.js';
 import { readManifest, writeManifest } from './manifest.js';
-export const ALL_BETA_FEATURES = ['drive', 'factory'];
+export const ALL_BETA_FEATURES = ['drive', 'factory', 'session-sync'];
 function isBetaFeatureName(value) {
     return typeof value === 'string' && ALL_BETA_FEATURES.includes(value);
 }

package/dist/lib/daemon.js

@@ -343,10 +343,14 @@ export async function runDaemon() {
             return;
         syncing = true;
         try {
-            const { isSyncConfigured, isSyncEnabled } = await import('./session/sync/config.js');
-            // isSyncEnabled() first: a machine the operator turned off must skip the
-            // keychain read entirely, not just the network cycle.
-            if (!isSyncEnabled() || !isSyncConfigured())
+            const { isBetaEnabled } = await import('./beta.js');
+            // Off by default: session sync is an opt-in beta feature. Check the beta
+            // flag FIRST so a machine that hasn't opted in skips the keychain read
+            // (isSyncConfigured) entirely, not just the network cycle.
+            if (!isBetaEnabled('session-sync'))
+                return;
+            const { isSyncConfigured } = await import('./session/sync/config.js');
+            if (!isSyncConfigured())
                 return;
             const { syncSessions } = await import('./session/sync/sync.js');
             const r = await syncSessions();

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/session/sync/config.d.ts

@@ -5,19 +5,6 @@
  */
 /** Secrets bundle holding the R2 credentials. */
 export declare const SYNC_BUNDLE = "r2.backups";
-/** Env var that overrides the persisted enable flag (on/off/true/false/1/0/yes/no). */
-export declare const SYNC_ENABLED_ENV = "AGENTS_SESSIONS_SYNC";
-/** Durable, machine-local path holding the sync enable flag. */
-export declare function syncStateFilePath(): string;
-/**
- * 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 declare function isSyncEnabled(): boolean;
-/** Persist the machine-local sync enable flag (durable across cache wipes). */
-export declare function setSyncEnabled(enabled: boolean): void;
 export interface R2Config {
     accountId: string;
     bucket: string;

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

@@ -3,65 +3,9 @@
  * 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/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.
@@ -299,7 +299,10 @@ export declare function getShimPath(agent: AgentId): string;
  * loop because addShimsToPath() only edits the rc file, never the legacy
  * shim file itself.
  */
-export declare function getPathShadowingExecutable(agent: AgentId): string | null;
+export declare function getPathShadowingExecutable(agent: AgentId, overrides?: {
+    pathDirs?: string[];
+    shimPath?: string;
+}): string | null;
 /**
  * Delete the legacy ~/.agents/shims/<cli> file if it exists, returning whether
  * anything was removed. Pre-split installs put shims under ~/.agents/shims/;
@@ -311,6 +314,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;