@phnx-labs/agents-cli 1.20.38 → 1.20.40

package/dist/commands/beta.js

@@ -3,6 +3,7 @@ import { ALL_BETA_FEATURES, getBetaConfigLocation, getEnabledBetaFeatures, setBe
 const BETA_DESCRIPTIONS = {
     drive: 'Google Drive integration for reading and writing files',
     factory: 'Cloud-based agent dispatch via Rush Factory',
+    'session-sync': 'Cross-machine session transcript sync via R2 (daemon push/pull)',
 };
 function parseFeatures(values) {
     const valid = new Set(ALL_BETA_FEATURES);

package/dist/commands/sessions-sync.js

@@ -5,31 +5,39 @@
  */
 import chalk from 'chalk';
 import { setHelpSections } from '../lib/help.js';
-import { isSyncConfigured, isSyncEnabled, setSyncEnabled, SYNC_BUNDLE, } from '../lib/session/sync/config.js';
+import { isSyncConfigured, SYNC_BUNDLE } from '../lib/session/sync/config.js';
+import { isBetaEnabled, setBetaEnabled, betaEnableHint } from '../lib/beta.js';
 import { syncSessions } from '../lib/session/sync/sync.js';
+/** The daemon's automatic session sync is gated by this beta feature. */
+const SYNC_BETA = 'session-sync';
 export async function runSessionsSync(options) {
-    // Toggle / status actions short-circuit before any network cycle.
+    // Toggle / status delegate to the `session-sync` beta feature — the single
+    // source of truth for whether the daemon auto-syncs (opt-in, off by default).
+    // These short-circuit before any network cycle.
     if (options.disable) {
-        setSyncEnabled(false);
+        setBetaEnabled([SYNC_BETA], false);
         console.log(chalk.yellow('Automatic session sync disabled') +
-            chalk.dim(' — the daemon stops pushing/pulling within ~90s. Re-enable: agents sessions sync --enable'));
+            chalk.dim(' — the daemon stops pushing/pulling within ~90s. (Same as: agents beta disable session-sync)'));
         return;
     }
     if (options.enable) {
-        setSyncEnabled(true);
-        console.log(chalk.green('Automatic session sync enabled') + chalk.dim(' — the daemon resumes on its next cycle.'));
+        setBetaEnabled([SYNC_BETA], true);
+        console.log(chalk.green('Automatic session sync enabled') +
+            chalk.dim(' — the daemon resumes on its next cycle. (Same as: agents beta enable session-sync)'));
         return;
     }
     if (options.status) {
-        const enabled = isSyncEnabled();
+        const enabled = isBetaEnabled(SYNC_BETA);
         const configured = isSyncConfigured();
         if (options.json) {
             console.log(JSON.stringify({ enabled, configured }, null, 2));
         }
         else {
-            console.log(`automatic sync: ${enabled ? chalk.green('enabled') : chalk.yellow('disabled')}` +
+            console.log(`automatic sync: ${enabled ? chalk.green('enabled (beta)') : chalk.yellow('disabled')}` +
                 chalk.dim('  ·  ') +
                 `credentials: ${configured ? chalk.green('configured') : chalk.yellow(`missing (${SYNC_BUNDLE})`)}`);
+            if (!enabled)
+                console.log(chalk.dim(`  ${betaEnableHint(SYNC_BETA)}`));
         }
         return;
     }
@@ -77,9 +85,9 @@ export function registerSessionsSyncCommand(sessionsCmd) {
         .description('Sync session transcripts across machines via R2 (CRDT merge). Claude and Codex.')
         .option('-v, --verbose', 'Log each pushed and pulled session')
         .option('--json', 'Output the sync result as JSON')
-        .option('--enable', 'Turn ON automatic background sync on this machine (persisted)')
-        .option('--disable', 'Turn OFF automatic background sync on this machine (persisted)')
-        .option('--status', 'Show whether automatic sync is enabled and configured');
+        .option('--enable', 'Opt in to automatic background sync (beta; alias for: agents beta enable session-sync)')
+        .option('--disable', 'Opt out of automatic background sync (alias for: agents beta disable session-sync)')
+        .option('--status', 'Show whether automatic sync is opted-in (beta) and configured');
     setHelpSections(syncCmd, {
         examples: `
       # One sync cycle (push local changes, pull + merge from other machines)
@@ -97,11 +105,11 @@ export function registerSessionsSyncCommand(sessionsCmd) {
         notes: `
       - Credentials come from the '${SYNC_BUNDLE}' secrets bundle (R2 S3 API, read+write).
       - Each machine writes only its own prefix; conflicts are impossible by construction.
-      - The daemon runs this automatically (~90s); this command forces an immediate cycle.
       - Sessions present locally always win; synced-in copies fill in other machines' sessions.
-      - --disable/--enable persist a machine-local switch (~/.agents/.history) that gates the
-        daemon's automatic sync; a bare 'agents sessions sync' still forces a manual cycle.
-        The AGENTS_SESSIONS_SYNC env var (on/off) overrides the switch for one invocation.
+      - Automatic background sync is an opt-in BETA feature, OFF by default. The daemon only
+        syncs (~90s) once you opt in via 'agents beta enable session-sync' (or the --enable
+        alias here). A bare 'agents sessions sync' always forces a manual one-shot cycle
+        regardless of the beta opt-in.
     `,
     });
     // `--json` is also declared on the parent `sessions` command, so a bare

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

package/dist/commands/sessions.js

@@ -601,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.

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/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

@@ -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/;

package/dist/lib/shims.js

@@ -1616,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)) {
@@ -1629,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
@@ -1729,6 +1739,16 @@ function canonical(p) {
         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.
  *

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.38",
+  "version": "1.20.40",
   "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",