@phnx-labs/agents-cli 1.22.90 → 1.22.92

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.22.92
+
+- **AGI Menu 1.1.0 is the helper the CLI installs (PHNX-4007).** The menu-bar
+  helper floor moves from 1.0.0 to 1.1.0, so `agents menubar setup` and
+  `agents menubar enable` download and install the release that carries the
+  dispatch form, the Sessions window, actionable notification banners, the
+  screenshot OCR index, and the FeedStream data layer (PHNX-3999). The startup
+  self-heal stays network-free: it reinstalls only from a bundled or cached copy,
+  so an existing 1.0.0 install upgrades on the next `agents menubar setup`.
+  Source: `src/lib/helper-versions.ts`.
+
+## 1.22.91
+
+- **`agents sessions` search/list execs the standalone `sessions` CLI (PHNX-4012).** Read queries intercept in `index.ts` before bootstrap so they skip the 6K-line in-process engine. Lifecycle verbs (`resume`, `stop`, `inject`, `watch`, `--active`, `--markdown`) still load the in-repo command. The `sessions` alias shim is retired like `secrets` so it cannot recurse. Install: `npm i -g @phnx-labs/sessions-cli`. Source: `cli/src/index.ts`, `cli/src/lib/sessions-client.ts`, `cli/scripts/postinstall.js`.
+
 ## 1.22.90
 
 - **`accounts migrate --apply` no longer aborts on a worker whose accounts already hold slots (PHNX-3940).** The daemon's auth-sync provisions a durable slot per account on every worker, so `--apply` hit `Slot already exists` on the first credential-bearing legacy home and cleaned nothing. The plan now routes such a home to `trash` (restorable with `agents trash restore`) with the reason "account already holds a provisioned slot on this device", rewrites any `<harness>@<label>` binding to the account, and clears the stale home record; a canonical install in that state keeps its binary, has its stale home moved to `~/.agents/.history/trash/homes/…` (manifest key `<harness>@<label>#home`), and gets an empty home back. A regular file at the slot path is still not a slot, so the apply-time guard still fails loud on that corruption. Source: `cli/src/lib/accounts/migrate.ts`.

package/dist/commands/exec.js

@@ -2234,7 +2234,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 // dispatch time; the peer resolves ITS slot. This block is local-only.
                 const remoteTarget = options.host || options.device;
                 if (!remoteTarget) {
-                    const { adoptedConfigPointsAtHome, adoptedSymlinkMismatchError, isSymlinkAdoptedHarness, resolveNativeSpawnHome, symlinkAdoptedAccountError, } = await import('../lib/exec-account-home.js');
+                    const { adoptedConfigPointsAtHome, adoptedSymlinkMismatchError, durableSlotEnv, isSymlinkAdoptedHarness, resolveNativeSpawnHome, symlinkAdoptedAccountError, } = await import('../lib/exec-account-home.js');
                     const { readMeta } = await import('../lib/state.js');
                     const meta = readMeta();
                     if (isSymlinkAdoptedHarness(agent)) {
@@ -2251,6 +2251,11 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                             process.exit(1);
                         }
                         execHome = resolved.execHome;
+                        // A worker's durable api-key slot holds no file: the pushed key
+                        // rides the harness env var (CURSOR_API_KEY, …) on this launch.
+                        const durable = durableSlotEnv(agent, spawnAccount, resolved, meta);
+                        if (Object.keys(durable).length > 0)
+                            accountEnv = { ...accountEnv, ...durable };
                         if (resolved.source === 'legacy-home') {
                             accountConfigVersion = resolved.label;
                             // A leftover version-labeled home is both the spawn HOME and

package/dist/index.d.ts

@@ -16,6 +16,7 @@
  *   - `__usage-ingest` / `__usage-export`
  *   - `__harness-update-run`
  *   - `__daemon-run`
+ *   - `sessions` (read queries only — PHNX-4012)
  *
  * The synchronous secrets-broker fast paths (`__secrets-get` / `__secrets-ping`
  * / `__secrets-lock`) and `__vault-age-helper` moved out of this CLI entirely

package/dist/index.js

@@ -16,6 +16,7 @@
  *   - `__usage-ingest` / `__usage-export`
  *   - `__harness-update-run`
  *   - `__daemon-run`
+ *   - `sessions` (read queries only — PHNX-4012)
  *
  * The synchronous secrets-broker fast paths (`__secrets-get` / `__secrets-ping`
  * / `__secrets-lock`) and `__vault-age-helper` moved out of this CLI entirely
@@ -131,6 +132,43 @@ if (process.argv[2] === '__daemon-run') {
     }
     process.exit(process.exitCode ?? 0);
 }
+// PHNX-4012: search/list/id lookup of `agents sessions` execs the standalone
+// `sessions` binary without loading bootstrap or the 6K-line sessions module.
+// Lifecycle verbs (resume/stop/inject/watch/--active/--markdown) fall through.
+if (process.argv[2] === 'sessions') {
+    const forwarded = process.argv.slice(3);
+    const { isReadQuery, resolveSessionsBin, invocation, SessionsClientError, SESSIONS_INSTALL_HINT, } = await import('./lib/sessions-client.js');
+    if (isReadQuery(forwarded)) {
+        const { spawnSync } = await import('node:child_process');
+        let bin = null;
+        try {
+            bin = resolveSessionsBin();
+        }
+        catch (err) {
+            // No standalone on this box: fall through to the in-repo engine below
+            // rather than refusing the query. The fast path is an optimization for a
+            // box that has `sessions` installed (skips bootstrap and the sessions
+            // module); a box without it must still answer `agents sessions --json`
+            // exactly as it did before PHNX-4012 — every worker in the fleet and
+            // every CI runner is such a box until @phnx-labs/sessions-cli is
+            // published, and refusing here turned main's full suite red.
+            if (!(err instanceof SessionsClientError && err.code === 'SESSIONS_BIN_MISSING'))
+                throw err;
+            if (process.env.AGENTS_SESSIONS_FASTPATH_HINT !== '0') {
+                process.stderr.write(`agents: standalone \`sessions\` not installed; using the in-process engine (${SESSIONS_INSTALL_HINT})\n`);
+            }
+        }
+        if (bin) {
+            const { command, prefix } = invocation(bin);
+            const res = spawnSync(command, [...prefix, ...forwarded], { stdio: 'inherit' });
+            if (res.error) {
+                process.stderr.write(`Failed to run \`sessions\`: ${res.error.message}\n`);
+                process.exit(1);
+            }
+            process.exit(res.status ?? 1);
+        }
+    }
+}
 // Full CLI: commander tree, update checks, migrations, parse. Static imports
 // inside bootstrap.js evaluate only when we reach this line.
 await import('./bootstrap.js');

package/dist/lib/exec-account-home.d.ts

@@ -1,3 +1,4 @@
+import { selfConfiguredDeviceRole } from './device-config.js';
 import { isSymlinkAdoptedHarness } from './installations/shims.js';
 import type { AgentId, DeviceAccountSlot, Meta } from './types.js';
 export { isAccountSlotDir } from './agents.js';
@@ -10,6 +11,24 @@ export interface NativeSpawnHome {
     /** Installation label when `source` is `legacy-home`. */
     label?: string;
 }
+/**
+ * The env a DURABLE slot injects at spawn (PHNX-3940 T5/T6). A worker's slot
+ * for an api-key harness (codex/grok/cursor/opencode/droid) holds no file — the
+ * daemon pushed the account's worker API key into the reserved
+ * `__<harness>__` store and `provisionWorkerSlot` recorded the slot as
+ * `durable`; the key rides the harness's own env var (`CURSOR_API_KEY`, …)
+ * on every launch. Anything else — a native login in the slot on a headed
+ * device, a claude durable slot (its setup-token is a `.oauth_token` file the
+ * adapter reads), a harness with no api-key worker kind, a headed device — injects
+ * nothing.
+ * Without this, `agents run cursor#gmail` on a worker reached Cursor with an
+ * empty env and got `Authentication required … set CURSOR_API_KEY`.
+ */
+export declare function durableSlotEnv(agent: AgentId, account: {
+    id: string;
+}, resolved: Pick<NativeSpawnHome, 'slot'>, meta: Pick<Meta, 'accounts' | 'deviceAccounts'>, deps?: {
+    selfRole?: () => ReturnType<typeof selfConfiguredDeviceRole>;
+}): Record<string, string>;
 export declare function missingSlotHint(agent: AgentId, name: string): string;
 export declare function symlinkAdoptedAccountError(agent: AgentId, name: string, defaultName: string | undefined): string;
 export declare function adoptedSymlinkMismatchError(agent: AgentId, name: string, execHome: string): string;

package/dist/lib/exec-account-home.js

@@ -13,7 +13,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { listNativeAccounts, nativeAccountHome } from './account-registry.js';
 import { readSlots } from './accounts/slots.js';
-import { workerProvisioningHint } from './accounts/add.js';
+import { workerProvisioningHint, workerApiKeyEnv } from './accounts/add.js';
 import { AGENTS, credentialPresence, getAccountInfo } from './agents.js';
 import { AUTH_BUNDLE, claudeAccountTokenKey, provisionWorkerSlot, readReservedCredential } from './claude-account-token.js';
 import { isHeadedDeviceRole, selfConfiguredDeviceRole } from './device-config.js';
@@ -22,6 +22,40 @@ import { getAgentConfigPath, isSymlinkAdoptedHarness, repointAdoptedConfigToHome
 import { getVersionHomePath, listInstalledVersions } from './installations/versions.js';
 export { isAccountSlotDir } from './agents.js';
 export { isSymlinkAdoptedHarness };
+/**
+ * The env a DURABLE slot injects at spawn (PHNX-3940 T5/T6). A worker's slot
+ * for an api-key harness (codex/grok/cursor/opencode/droid) holds no file — the
+ * daemon pushed the account's worker API key into the reserved
+ * `__<harness>__` store and `provisionWorkerSlot` recorded the slot as
+ * `durable`; the key rides the harness's own env var (`CURSOR_API_KEY`, …)
+ * on every launch. Anything else — a native login in the slot on a headed
+ * device, a claude durable slot (its setup-token is a `.oauth_token` file the
+ * adapter reads), a harness with no api-key worker kind, a headed device — injects
+ * nothing.
+ * Without this, `agents run cursor#gmail` on a worker reached Cursor with an
+ * empty env and got `Authentication required … set CURSOR_API_KEY`.
+ */
+export function durableSlotEnv(agent, account, resolved, meta, deps = {}) {
+    if (resolved.slot?.authMode !== 'durable')
+        return {};
+    // A headed device authenticates from its own native login (invariant 7). A
+    // `durable` record can outlive a role change (`agents devices role … personal`
+    // never rewrites slots), so the gate is the box's CURRENT role, the same
+    // predicate `isProvisionableWorker` applies — never a record on disk.
+    if (isHeadedDeviceRole((deps.selfRole ?? selfConfiguredDeviceRole)()))
+        return {};
+    const envName = workerApiKeyEnv(agent);
+    if (!envName)
+        return {};
+    const row = nativeRow(account.id, meta);
+    const cred = row?.workerCredential;
+    if (!cred || cred.kind !== 'api-key')
+        return {};
+    const value = readReservedCredential(cred.bundle, cred.key);
+    if (!value)
+        return {};
+    return { [envName]: value };
+}
 export function missingSlotHint(agent, name) {
     const role = selfConfiguredDeviceRole();
     if (!isHeadedDeviceRole(role)) {

package/dist/lib/helper-versions.js

@@ -36,7 +36,7 @@
  * helper release now, off this table entirely.
  */
 export const HELPER_RELEASES = {
-    menubar: { tagPrefix: 'menubar', floor: '1.0.0' },
+    menubar: { tagPrefix: 'menubar', floor: '1.1.0' },
     'computer-mac': { tagPrefix: 'computer-mac', floor: '1.0.0' },
     // The Windows helper is a bare .exe, not an .app bundle, so it does not share
     // helper-download.ts's zip/codesign/notarize machinery -- but it has the same

package/dist/lib/installations/shims.d.ts

@@ -179,7 +179,7 @@ export declare function removeShim(agent: AgentId): boolean;
  *        sorted alphabetically before the real self-updated grok binary and
  *        was silently launched instead.
  */
-export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 19;
+export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 20;
 /**
  * Agents whose config directory can be relocated by an environment variable
  * (the per-agent `managedEnv` block in `generateVersionedAliasScript` below).

package/dist/lib/installations/shims.js

@@ -1095,7 +1095,7 @@ export function removeShim(agent) {
 // v18 — Cursor aliases select the file credential store and swap HOME to the
 //       version home because current Cursor writes auth.json under ~/.cursor
 //       and ignores XDG_CONFIG_HOME for credential storage.
-export const VERSIONED_ALIAS_SCHEMA_VERSION = 19;
+export const VERSIONED_ALIAS_SCHEMA_VERSION = 20;
 /** Internal marker string used to embed the schema version in versioned alias scripts. */
 const VERSIONED_ALIAS_VERSION_MARKER = 'agents-versioned-alias-version:';
 // The version string is interpolated into a generated bash script and into
@@ -1220,52 +1220,56 @@ export function generateVersionedAliasScript(agent, version) {
 # already sources this same adapter block, so sharing it keeps the two in sync.
 # plain (not exported) so it feeds shimConfigEnvBash below but never leaks into the
 # launched agent process — matching the main shim's convention.
-VERSION_DIR="$HOME/.agents/.history/versions/${agent}/${version}"
+VERSION_DIR="$AGENTS_REAL_HOME/.agents/.history/versions/${agent}/${version}"
 ${resolveHarnessAdapter(agent).shimConfigEnvBash?.({ configDirName }) ?? ''}`
         : agent === 'codex'
-            ? codexHomeShimBash(`$HOME/.agents/.history/versions/${agent}/${version}/home/${configDirName}`, `$HOME/.agents/.codex-homes/${version}`)
+            ? codexHomeShimBash(`$AGENTS_REAL_HOME/.agents/.history/versions/${agent}/${version}/home/${configDirName}`, `$AGENTS_REAL_HOME/.agents/.codex-homes/${version}`)
             : agent === 'copilot'
                 ? `
 # Copilot honors COPILOT_HOME to relocate ~/.copilot (settings, mcp-config.json,
 # session-state, logs). Point direct aliases at the versioned home so per-
 # version MCP and session state are isolated.
-export COPILOT_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/${configDirName}"
+export COPILOT_HOME="$AGENTS_REAL_HOME/.agents/.history/versions/${agent}/${version}/home/${configDirName}"
 `
                 : agent === 'grok'
                     ? `
 # Grok Build uses GROK_HOME to isolate its entire configuration tree (skills,
 # hooks, plugins, agents, memory, sessions, config.toml, MCP). Point direct
 # aliases at the versioned home for isolation parity with the main shim.
-export GROK_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/${configDirName}"
+export GROK_HOME="$AGENTS_REAL_HOME/.agents/.history/versions/${agent}/${version}/home/${configDirName}"
 `
                     : agent === 'opencode'
                         ? `
 # OpenCode reads plugins, agents, commands, and other config-directory
 # resources from OPENCODE_CONFIG_DIR. Point direct aliases at the versioned
 # global config tree where agents-cli syncs OpenCode resources.
-export OPENCODE_CONFIG_DIR="$HOME/.agents/.history/versions/${agent}/${version}/home/.config/opencode"
+export OPENCODE_CONFIG_DIR="$AGENTS_REAL_HOME/.agents/.history/versions/${agent}/${version}/home/.config/opencode"
 `
                         : agent === 'kimi'
                             ? `
 # Kimi Code CLI honors KIMI_CODE_HOME to relocate ~/.kimi-code (config.toml,
 # mcp.json, sessions, skills, hooks). Point direct aliases at the versioned home.
-export KIMI_CODE_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/${configDirName}"
+export KIMI_CODE_HOME="$AGENTS_REAL_HOME/.agents/.history/versions/${agent}/${version}/home/${configDirName}"
 `
                             : agent === 'muse'
                                 ? `
 # Muse Code: no dedicated config env var. Pin XDG so config/sessions live under
 # the version home as real directories (not via the adopt symlink at
 # ~/.config/muse, which Muse rejects with SymlinkOrReparse).
-export XDG_CONFIG_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/.config"
-export XDG_DATA_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/.local/share"
+export XDG_CONFIG_HOME="$AGENTS_REAL_HOME/.agents/.history/versions/${agent}/${version}/home/.config"
+export XDG_DATA_HOME="$AGENTS_REAL_HOME/.agents/.history/versions/${agent}/${version}/home/.local/share"
 `
                                 : agent === 'cursor'
                                     ? `
 # Cursor defaults to one machine-global OS-keychain login on macOS. Force its
 # file store and swap HOME, so ~/.cursor/auth.json belongs to this
 # version and direct aliases cannot fall through to the shared keychain login.
-export AGENTS_REAL_HOME="\${AGENTS_REAL_HOME:-$HOME}"
-export HOME="$HOME/.agents/.history/versions/${agent}/${version}/home"
+# A spawner that already chose HOME (an account slot, PHNX-3940 T5 — it left
+# the real home in AGENTS_REAL_HOME) keeps its choice: re-swapping here would
+# silently discard the slot.
+if [ "$HOME" = "$AGENTS_REAL_HOME" ]; then
+  export HOME="$AGENTS_REAL_HOME/.agents/.history/versions/${agent}/${version}/home"
+fi
 export AGENT_CLI_CREDENTIAL_STORE="file"
 `
                                     : '';
@@ -1283,7 +1287,7 @@ export AGENT_CLI_CREDENTIAL_STORE="file"
     // alias's sibling dispatcher shim and re-execs forever.
     // This template is unix-only — on Windows the .cmd companion delegates to
     // "agents __shim" which resolves via getBinaryPath() instead.
-    const versionDir = `$HOME/.agents/.history/versions/${agent}/${version}`;
+    const versionDir = `$AGENTS_REAL_HOME/.agents/.history/versions/${agent}/${version}`;
     const binaryResolution = agent === 'grok'
         ? `# Grok ships its native binary in the versioned home's .grok/downloads (or,
 # for pre-fix installs, the global ~/.grok/downloads), not node_modules.
@@ -1295,7 +1299,7 @@ if [ -d "$GROK_DOWNLOADS" ]; then
 fi
 # Fall back to the global grok home (binary installed without GROK_HOME set).
 if [ -z "$BINARY" ] || [ ! -x "$BINARY" ]; then
-  GROK_GLOBAL_DOWNLOADS="$HOME/.grok/downloads"
+  GROK_GLOBAL_DOWNLOADS="$AGENTS_REAL_HOME/.grok/downloads"
   if [ -d "$GROK_GLOBAL_DOWNLOADS" ]; then
     BINARY=$(_resolve_grok_binary "$GROK_GLOBAL_DOWNLOADS" "${version}")
   fi
@@ -1306,31 +1310,31 @@ fi
 if [ -z "$BINARY" ] || [ ! -x "$BINARY" ]; then
   BINARY=$(command -v grok 2>/dev/null || echo "")
   case "$BINARY" in
-    "$HOME/.agents/.cache/shims/"*) BINARY="" ;;
+    "$AGENTS_REAL_HOME/.agents/.cache/shims/"*) BINARY="" ;;
   esac
 fi`
         : agent === 'droid'
             ? `# Droid (Factory AI) installs a standalone native binary at ~/.local/bin/droid;
 # there is no npm package and nothing lands in node_modules/.bin. The PATH
 # fallback refuses anything under our shims dir to avoid an infinite re-exec.
-DROID_BINARY="$HOME/.local/bin/droid"
+DROID_BINARY="$AGENTS_REAL_HOME/.local/bin/droid"
 if [ -x "$DROID_BINARY" ]; then
   BINARY="$DROID_BINARY"
 else
   BINARY=$(command -v droid 2>/dev/null || echo "")
   case "$BINARY" in
-    "$HOME/.agents/.cache/shims/"*) BINARY="" ;;
+    "$AGENTS_REAL_HOME/.agents/.cache/shims/"*) BINARY="" ;;
   esac
 fi`
             : agent === 'muse'
                 ? `# Muse Code installs a self-updating launcher at ~/.local/bin/muse.
-MUSE_BINARY="$HOME/.local/bin/muse"
+MUSE_BINARY="$AGENTS_REAL_HOME/.local/bin/muse"
 if [ -x "$MUSE_BINARY" ]; then
   BINARY="$MUSE_BINARY"
 else
   BINARY=$(command -v muse 2>/dev/null || echo "")
   case "$BINARY" in
-    "$HOME/.agents/.cache/shims/"*) BINARY="" ;;
+    "$AGENTS_REAL_HOME/.agents/.cache/shims/"*) BINARY="" ;;
   esac
 fi`
                 : agent === 'warp'
@@ -1339,7 +1343,7 @@ fi`
 # PATH, refusing anything under our shims dir.
 BINARY=$(command -v warp 2>/dev/null || echo "")
 case "$BINARY" in
-  "$HOME/.agents/.cache/shims/"*) BINARY="" ;;
+  "$AGENTS_REAL_HOME/.agents/.cache/shims/"*) BINARY="" ;;
 esac`
                     : `BINARY="${versionDir}/node_modules/.bin/${agentConfig.cliCommand}"`;
     return `#!/bin/bash
@@ -1347,22 +1351,32 @@ esac`
 # ${VERSIONED_ALIAS_VERSION_MARKER} ${VERSIONED_ALIAS_SCHEMA_VERSION}
 # Direct alias for ${agentConfig.name}@${version}
 
+# The real home. A spawner may have swapped HOME already — an account slot
+# launch (PHNX-3940 T5) sets HOME to the slot dir and leaves the real home in
+# AGENTS_REAL_HOME — so every agents-owned path below (the installation, the
+# version home, the shims dir) is anchored here, never on whatever HOME is now.
+# Anchoring on HOME made a slot launch of cursor#<name> answer "not installed"
+# and the launch lease fail with "No installation directory".
+export AGENTS_REAL_HOME="\${AGENTS_REAL_HOME:-$HOME}"
+
 ${binaryResolution}
 
 if [ -z "$BINARY" ] || [ ! -x "$BINARY" ]; then
   echo "agents: ${agent}@${version} not installed" >&2
   exit 1
 fi
-${managedEnv}
 
 # Register a launch lease for THIS pid before the exec below (PHNX-3940) — see
 # generateShimScript's identical call for what this closes and why it fails
-# closed rather than falling through on error. \$\$ survives exec.
-if ! ${agentsBin} __launch-lease "${agent}" "${version}" "\$\$"; then
+# closed rather than falling through on error. \$\$ survives exec. It runs
+# under the REAL home, before any harness HOME swap below: agents-cli's own
+# state root is $HOME/.agents, so a swapped HOME cannot find the installation.
+if ! HOME="$AGENTS_REAL_HOME" ${agentsBin} __launch-lease "${agent}" "${version}" "\$\$"; then
   echo "agents: could not safely coordinate this launch with a possibly in-progress update of ${agent}@${version}." >&2
   echo "  Check: agents update ${agent}@${version} --check    Retry once any update finishes." >&2
   exit 1
 fi
+${managedEnv}
 
 ${resolveHarnessAdapter(agent).shimExecTail?.(launchArgs) ?? `exec "$BINARY"${launchArgs} "$@"`}
 `;
@@ -2167,14 +2181,11 @@ export function listShimFileNames() {
 }
 /**
  * Legacy command shims that are wrong even when their baked install is alive.
- * `secrets`: the shim `exec`s `agents secrets`, which since PHNX-3989 is a
- * passthrough to the STANDALONE `secrets` binary — so a `secrets` shim that
- * re-enters `agents secrets` is a recursion, never a working command. It sits
- * first on PATH and shadows the real `@phnx-labs/secrets-cli` bin, so it is
- * pruned unconditionally (the liveness check below is what kept it alive across
- * every in-place upgrade from 1.22.84).
+ * `secrets` (PHNX-3989) and `sessions` (PHNX-4012): the shim `exec`s
+ * `agents <name>`, which is a passthrough to the STANDALONE binary — so the
+ * shim re-enters itself (the 1.22.85 fork bomb). Pruned unconditionally.
  */
-const LEGACY_SHIMS_ALWAYS_PRUNED = new Set(['secrets']);
+const LEGACY_SHIMS_ALWAYS_PRUNED = new Set(['secrets', 'sessions']);
 /**
  * Prune a stale, orphaned shim: one that is NOT a managed agent shim and NOT a user
  * alias, whose baked `AGENTS_BIN` points at an install that no longer exists. These

package/dist/lib/secrets-client.d.ts

@@ -185,6 +185,19 @@ export declare function storeDelete(backend: SecretsBackend, item: string): Prom
 export declare function remoteResolveEnv(target: string, bundle: string, opts?: {
     osLookupName?: string;
 }): Promise<Record<string, string>>;
+/**
+ * The user agents dir as the RECEIVING agents-cli resolves it — `~/.agents` on
+ * every box, the same root {@link buildServeEnv} pins the local standalone to
+ * (MIG-1). A push must name it, because the remote `secrets` otherwise runs
+ * under its own default `~/.secrets`: the import succeeds, the file store there
+ * is keyed by a different machine-local passphrase, and the receiving daemon's
+ * `readReservedCredential` never finds the bundle (yosemite-m0, 2026-09-07:
+ * `pushed __cursor__` on the publisher, `no readable durable key` on the worker).
+ * Remote-relative on purpose — the local absolute dir means nothing over there.
+ */
+export declare const REMOTE_USER_AGENTS_DIR = "~/.agents";
+/** Fill in the remote state root unless the caller named one. Pure, for the seam test. */
+export declare function withRemoteStateRoot(opts: PushBundleOptions): PushBundleOptions;
 export declare function pushBundleToHost(bundle: string, host: string, opts: PushBundleOptions): Promise<PushBundleResult>;
 export declare function pushBundleToHostAsync(bundle: string, host: string, opts: PushBundleOptions): Promise<PushBundleResult>;
 export declare function listRemoteBundles(context?: SecretsContext): Promise<RemoteBundleSummary[]>;

package/dist/lib/secrets-client.js

@@ -646,11 +646,26 @@ export function storeDelete(backend, item) {
 export function remoteResolveEnv(target, bundle, opts) {
     return secretsRequest('remote.remoteResolveEnv', [target, bundle, opts ?? {}]);
 }
+/**
+ * The user agents dir as the RECEIVING agents-cli resolves it — `~/.agents` on
+ * every box, the same root {@link buildServeEnv} pins the local standalone to
+ * (MIG-1). A push must name it, because the remote `secrets` otherwise runs
+ * under its own default `~/.secrets`: the import succeeds, the file store there
+ * is keyed by a different machine-local passphrase, and the receiving daemon's
+ * `readReservedCredential` never finds the bundle (yosemite-m0, 2026-09-07:
+ * `pushed __cursor__` on the publisher, `no readable durable key` on the worker).
+ * Remote-relative on purpose — the local absolute dir means nothing over there.
+ */
+export const REMOTE_USER_AGENTS_DIR = '~/.agents';
+/** Fill in the remote state root unless the caller named one. Pure, for the seam test. */
+export function withRemoteStateRoot(opts) {
+    return { ...opts, remoteSecretsHome: opts.remoteSecretsHome ?? REMOTE_USER_AGENTS_DIR };
+}
 export function pushBundleToHost(bundle, host, opts) {
-    return secretsRequest('push.pushBundleToHost', [bundle, host, opts]);
+    return secretsRequest('push.pushBundleToHost', [bundle, host, withRemoteStateRoot(opts)]);
 }
 export function pushBundleToHostAsync(bundle, host, opts) {
-    return secretsRequest('push.pushBundleToHostAsync', [bundle, host, opts]);
+    return secretsRequest('push.pushBundleToHostAsync', [bundle, host, withRemoteStateRoot(opts)]);
 }
 // sync.* (transport pull, used by the `agents sync --secrets` umbrella stage)
 export function listRemoteBundles(context) {

package/dist/lib/secrets-types.d.ts

@@ -155,6 +155,14 @@ export interface PushBundleOptions {
     literalValues?: Record<string, string>;
     /** Per-SSH-operation deadline. Async daemon callers must set this explicitly. */
     timeoutMs?: number;
+    /**
+     * State root (`SECRETS_HOME`) the remote `secrets` runs under for the whole
+     * push (import, read-back verify, literal restoration); remote-relative, a
+     * leading `~/` resolves against the remote user's home. The client wrapper
+     * fills in the user agents dir (`REMOTE_USER_AGENTS_DIR`) so a push lands
+     * where the receiving agents-cli reads (MIG-1 on both ends).
+     */
+    remoteSecretsHome?: string;
 }
 export interface PushBundleResult {
     ok: boolean;

package/dist/lib/sessions-client.d.ts

@@ -0,0 +1,13 @@
+export declare class SessionsClientError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+export declare function resolveSessionsBin(): string;
+export declare function invocation(bin: string): {
+    command: string;
+    prefix: string[];
+};
+export declare function isReadQuery(args: string[]): boolean;
+/** Test seam: drop the memoized bin so PATH fixtures can re-resolve. */
+export declare function _resetSessionsClientForTest(): void;
+export declare const SESSIONS_INSTALL_HINT = "npm i -g @phnx-labs/sessions-cli";

package/dist/lib/sessions-client.js

@@ -0,0 +1,107 @@
+/**
+ * sessions-client.ts — agents-cli's process client for the standalone
+ * `sessions` CLI (PHNX-4012). This client never falls back itself: a missing
+ * binary throws `SESSIONS_BIN_MISSING` (loud, DIST-1). The caller decides what
+ * that means — the read fast-path in `index.ts` falls through to the in-repo
+ * `lib/session` engine when the standalone is not installed (every worker and
+ * CI runner, until @phnx-labs/sessions-cli is published), and takes the fast
+ * path when it is.
+ *
+ * Bin resolution uses `findInPath`, which skips `~/.agents/.cache/shims`.
+ * That skip is load-bearing: the leftover `sessions` alias shim execs
+ * `agents sessions`, and resolving it would recurse (the 1.22.85 secrets
+ * fork bomb with the names swapped — agi-cli#3532).
+ */
+import { findInPath } from './agent-spec/agents.js';
+const INSTALL_HINT = 'npm i -g @phnx-labs/sessions-cli';
+export class SessionsClientError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'SessionsClientError';
+    }
+}
+let cachedBin;
+export function resolveSessionsBin() {
+    if (cachedBin)
+        return cachedBin;
+    const explicit = process.env.SESSIONS_BIN?.trim();
+    const resolved = explicit && explicit.length > 0 ? explicit : findInPath('sessions');
+    if (!resolved) {
+        throw new SessionsClientError('SESSIONS_BIN_MISSING', 'The standalone `sessions` CLI was not found. Install it with:\n' +
+            `  ${INSTALL_HINT}\n` +
+            'or point $SESSIONS_BIN at its executable.');
+    }
+    cachedBin = resolved;
+    return resolved;
+}
+export function invocation(bin) {
+    if (/\.[mc]?js$/.test(bin))
+        return { command: process.execPath, prefix: [bin] };
+    return { command: bin, prefix: [] };
+}
+/**
+ * Allowlist of what sessions-cli v1 actually implements. Anything else —
+ * picker (no args), `--since`, `-D`, `--waiting`, `render`, `stats`,
+ * lifecycle verbs — stays on the in-repo engine. A denylist leaked those
+ * through `allowUnknownOption()` as FTS tokens (PR review on #3554).
+ */
+const READ_FLAGS = new Set([
+    '--json',
+    '--local',
+    '--no-interactive',
+]);
+const ENGINE_VERBS = new Set([
+    'resume',
+    'detach',
+    'stop',
+    'inject',
+    'fork',
+    'backfill',
+    'migrate',
+    'share',
+    'export',
+    'import',
+    'optimize',
+    'trace',
+    'insights',
+    'bookmark',
+    'tail',
+    'watch',
+    'preview',
+    'attach',
+    'focus',
+    'render',
+    'stats',
+    'go',
+    'reconnect',
+    'migrations',
+    'export',
+]);
+export function isReadQuery(args) {
+    if (args.length === 0)
+        return false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--limit' || arg === '--agent') {
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith('--limit=') || arg.startsWith('--agent='))
+            continue;
+        if (arg.startsWith('-')) {
+            if (!READ_FLAGS.has(arg))
+                return false;
+            continue;
+        }
+        if (ENGINE_VERBS.has(arg))
+            return false;
+    }
+    return true;
+}
+/** Test seam: drop the memoized bin so PATH fixtures can re-resolve. */
+export function _resetSessionsClientForTest() {
+    cachedBin = undefined;
+}
+export const SESSIONS_INSTALL_HINT = INSTALL_HINT;

package/package.json

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

package/scripts/postinstall.js

@@ -50,16 +50,15 @@ function shellQuote(value) {
 }
 
 // Shorthands that delegate to the installed agents-cli entrypoint.
-const ALIASES = ['sessions', 'browser', 'pty', 'teams'];
+const ALIASES = ['browser', 'pty', 'teams'];
 
 // Aliases this script USED to write and must now remove on every install.
-// `secrets`: the name belongs to the standalone `@phnx-labs/secrets-cli` binary
-// (PHNX-3989); `agents secrets` is a passthrough to it, so an alias shim that
-// `exec`s `agents secrets` can only re-enter the passthrough, and it shadows the
-// real `secrets` bin because the shims dir sits first on PATH. The self-heal
-// shim pass prunes it too, but that only runs from a daemon or a TTY session —
-// postinstall is what every upgrade path actually executes, so it cleans up here.
-const RETIRED_ALIASES = ['secrets'];
+// `secrets` (PHNX-3989) and `sessions` (PHNX-4012): those names belong to the
+// standalone CLIs. An alias shim that `exec`s `agents <name>` re-enters the
+// passthrough and shadows the real binary because the shims dir sits first on
+// PATH — the 1.22.85 fork bomb. Postinstall is the upgrade path that actually
+// runs, so it prunes here.
+const RETIRED_ALIASES = ['secrets', 'sessions'];
 
 function removeRetiredAliasShims() {
   for (const name of RETIRED_ALIASES) {