@phnx-labs/agents-cli 1.22.89 → 1.22.91

package/CHANGELOG.md

@@ -1,5 +1,98 @@
 # Changelog
 
+## 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`.
+
+- **AGI Menu: Sessions window, feed-driven RECENT, Notifications submenu (PHNX-4003).**
+  `Cmd-Shift-I` (or the new **Sessions** row at the top of the dropdown) opens a
+  persistent Sessions window: live sessions across the fleet grouped by project on
+  the left, with **Recent / Needs you / Running / Done today** filter chips, a
+  `Cmd-F` search (label, topic, project, ticket, device), and a device strip that
+  marks stale heartbeats; a session card on the right shows the phase, PR chip,
+  request excerpt, progress tally, latest action, today's rendered artifacts with an
+  **Open** button, and the attention block when the agent is waiting — numbered
+  option buttons, permission Allow/Deny, plan-review Approve/Send back — answered
+  atomically through `agents feed answer`. A reply field routes by capability
+  (`agents feed answer`, `agents sessions inject`, `agents cloud message`,
+  `agents teams message`) and shows the CLI's own result inline; keys `1`–`9`,
+  `Return`, `Cmd-Return`, `Cmd-K` answer, reply, open the terminal, or nudge. The
+  dropdown's RECENT section now renders the same feed-driven rows (status dot,
+  `n/N` checklist, `working · 18h · host`, latest action + PR chip) grouped by
+  project, each opening the window on that session, and a **Notifications**
+  submenu lists today's feed banners unanswered-first. Blocked sessions leave the
+  NEEDS YOU strip, which keeps only load, scheduler, and routine triage.
+  Source: `cli/menubar/Sources/MenubarHelper/SessionsWindow.swift`,
+  `cli/menubar/Sources/MenubarHelper/SessionCard.swift`,
+  `cli/menubar/Sources/MenubarHelper/SessionRowModel.swift`,
+  `cli/menubar/Sources/MenubarHelper/Reply.swift`,
+  `cli/menubar/Sources/MenubarHelper/RecentSectionBuilder.swift`.
+
+- **AGI Menu delivers attention banners on `UNUserNotificationCenter` with real
+  action buttons (PHNX-4004).** The deprecated `NSUserNotification` toast is
+  replaced for actionable notices: the banner carries the mapped category, a
+  time-sensitive interruption level for a blocked ask, a per-session thread so a
+  session's banners group, and the harness avatar as an attachment. The
+  persistent menu-bar instance is the delegate; a tapped action runs one bounded
+  `agents feed answer` / `agents open` command off the delegate thread and posts
+  a "Could not deliver your reply" follow-up when it fails, or a "Could not open
+  the report/PR" follow-up when a done banner carried no link for that button.
+  When macOS declines notification authorization it degrades to the old plain
+  banner so a notice is never lost.
+  Source: `menubar/Sources/MenubarHelper/Notifier.swift`,
+  `menubar/Sources/MenubarHelper/AgentAvatar.swift`.
+
+- **AGI Menu palette: dispatch form with remembered defaults, project pulse, and session-id minting (PHNX-4005).**
+  The `Cmd-Shift-O` palette now carries the dimensions a dispatch actually needs
+  below its text field — **mode** (Plan / Auto / Edit), **run on** (This Mac,
+  `auto`, or a fleet device by name), **surface** (Interactive / Headless), and
+  **watchdog** (Off / Keep moving / Hands-off) — collapsed to one summary line
+  (`Claude 2.1.263 · this-mac · agi · Auto · Interactive · Keep moving`) with a
+  `▸ details` disclosure. Every dimension is **remembered per project**, so
+  switching projects restores the agent, mode, and target you last used there and
+  one keystroke dispatches. `Cmd-P` switches **this one dispatch** to Plan without
+  touching the remembered defaults. A Claude dispatch mints its session id and
+  passes `--session-id`, which lets the palette apply a non-default watchdog policy
+  at dispatch and register a **launching placeholder** with the feed stream: the
+  row shows in the project pulse strip as `◌ launching · <name>` (and in any
+  window that reads the feed rows) until the real session reports, and reads
+  "did not start" — with the CLI's own stderr — if the launch exits non-zero or
+  no row arrives within 60 s. Under the project row a **pulse strip** shows the
+  headline milestone from `agents projects status`, open tickets and PRs, live
+  running / need-you / idle counts with NOW chips (not-progressing first), and
+  the NEXT UP ticket (`Cmd-N` attaches).
+  Source: `cli/menubar/Sources/MenubarHelper/DispatchForm.swift`,
+  `cli/menubar/Sources/MenubarHelper/DispatchDefaults.swift`,
+  `cli/menubar/Sources/MenubarHelper/ProjectPulse.swift`,
+  `cli/menubar/Sources/MenubarHelper/FeedStream.swift`,
+  `cli/menubar/Sources/MenubarHelper/AgentsCLI.swift`.
+
+- **AGI Menu palette: find a screenshot by the text on it (PHNX-4006).**
+  Every capture in the palette's screenshot folders (the system `screencapture`
+  location, CleanShot's export path, and the clip attachments dir) is now OCR'd
+  once, on-device, and indexed so you can search screenshots by the words on them.
+  With the palette key, `Cmd-Shift-F` focuses a search field above the strip:
+  typing filters the thumbnails to captures whose recognized text matches every
+  token (case-insensitive, tokenized AND), newest first, with an `n of m match`
+  hint; clearing it restores the newest-six strip. A **more** disclosure expands
+  the strip into a grid grouped by hour (last 24 h) then day — each cell shows the
+  thumbnail, the time, and the first recognized line — where a click attaches and a
+  double-click previews the full image in Preview.app. Nothing leaves the machine:
+  recognition runs through Vision locally (`.fast`, no language correction) on a
+  background queue, images over 20 MB are skipped and the rest downsampled to
+  2000 px before recognition, each capture is keyed by the SHA-256 of its bytes so
+  a rename or duplicate is never OCR'd twice, a deleted capture drops out of the
+  index (search and grid never return it, and the next scan prunes its row), and
+  the index is a local SQLite file at `~/.agents/.history/menubar/screenshots.db`.
+  Source:
+  `cli/menubar/Sources/MenubarHelper/ScreenshotIndex.swift`,
+  `cli/menubar/Sources/MenubarHelper/ScreenshotGrid.swift`,
+  `cli/menubar/Sources/MenubarHelper/PromptPanel.swift`.
+
 ## 1.22.89
 
 - **Worker daemons now actually relaunch onto a new agents-cli release, so a fix

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/accounts/migrate.js

@@ -163,6 +163,30 @@ async function duplicateTrashLabels(items) {
 function plannedTrashPath(agent, label) {
     return path.join(getHistoryDir(), 'trash', 'versions', agent, label, '<stamp>');
 }
+/**
+ * Where a canonical install's stale `home/` goes when its account already holds
+ * a slot: the binary and the (recreated, empty) home stay under `versions/`, so
+ * the old home cannot use the versions trash — `agents trash restore` would put a
+ * whole install back over a live one. Restoring is a plain move back; the
+ * migration manifest records the path under `<agent>@<label>#home`.
+ */
+function homeTrashDir(agent, label) {
+    return path.join(getHistoryDir(), 'trash', 'homes', agent, label);
+}
+function plannedHomeTrashPath(agent, label) {
+    return path.join(homeTrashDir(agent, label), '<stamp>');
+}
+function trashHome(agent, item) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const dest = path.join(homeTrashDir(agent, item.label), stamp);
+    fs.mkdirSync(path.dirname(dest), { recursive: true, mode: 0o700 });
+    if (!fs.existsSync(item.home)) {
+        throw new Error(`Home ${item.home} is missing; cannot trash it.`);
+    }
+    fs.renameSync(item.home, dest);
+    fs.mkdirSync(item.home, { recursive: true, mode: 0o700 });
+    return dest;
+}
 function emptyDir(dir) {
     if (!fs.existsSync(dir))
         return true;
@@ -180,6 +204,23 @@ function assertSlotAbsent(agent, accountId) {
     }
     return dest;
 }
+/**
+ * True when this device already holds a populated slot directory for the
+ * account. The daemon's auth-sync provisions durable worker slots on its own
+ * (PHNX-3940), so by the time an operator runs `--apply` a worker commonly has
+ * a slot for every account whose legacy per-version home is still on disk.
+ * A regular file at the slot path is NOT a slot: the plan keeps routing such a
+ * home to `slot` so the apply-time guard fails loud on the corruption.
+ */
+function provisionedSlotExists(agent, accountId) {
+    const dest = slotDir(agent, accountId);
+    try {
+        return fs.statSync(dest).isDirectory() && fs.readdirSync(dest).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
 function takenNames(meta) {
     const taken = new Set();
     for (const row of listNativeAccounts(meta)) {
@@ -255,6 +296,42 @@ async function planHarness(agent, deps) {
             });
             continue;
         }
+        if (item.hasCredential && item.accountId && provisionedSlotExists(agent, item.accountId)) {
+            // The account already owns a populated slot on this device, so this
+            // per-version home is a stale copy of a credential the slot now carries.
+            // Routing it to `slot` would only trip `assertSlotAbsent` and abort the
+            // whole apply with nothing done — the state every auth-synced worker was
+            // in. Trash it instead (`agents trash restore` reverses). The canonical
+            // install keeps its binary and ends up with an empty home, exactly as it
+            // does when its home is the one that moves into the slot: two on-disk
+            // copies of one credential is not an end state the migration leaves.
+            if (canonical && item.label === canonical.label) {
+                actions.push({
+                    kind: 'canonical',
+                    label: item.label,
+                    release: item.release,
+                    reason: 'canonical install (binary kept); account already holds a slot — stale home trashed, empty home recreated',
+                    accountId: item.accountId,
+                    identityKey: item.identityKey,
+                    email: item.email,
+                    sessionCount: item.sessionCount,
+                    pathMoves: [{ from: item.home, to: plannedHomeTrashPath(agent, item.label) }],
+                });
+                continue;
+            }
+            actions.push({
+                kind: 'trash',
+                label: item.label,
+                release: item.release,
+                reason: 'account already holds a provisioned slot on this device — stale home trashed',
+                accountId: item.accountId,
+                identityKey: item.identityKey,
+                email: item.email,
+                sessionCount: item.sessionCount,
+                pathMoves: [{ from: item.dir, to: plannedTrashPath(agent, item.label) }],
+            });
+            continue;
+        }
         if (item.hasCredential && item.identityKey) {
             const dest = item.accountId ? slotDir(agent, item.accountId) : slotDir(agent, '<new-account>');
             actions.push({
@@ -494,6 +571,21 @@ export async function applyAccountMigration(agents = [...ALL_AGENT_IDS], deps =
             if (kept)
                 labelToAccount.set(item.label, kept);
         }
+        for (const action of h.actions.filter((a) => a.kind === 'canonical' && a.accountId)) {
+            // Canonical install whose account already holds a slot: hand the stale
+            // home off to the homes trash and leave an empty home behind, mirroring
+            // the slot branch's end state for a canonical home.
+            const item = byLabel.get(action.label);
+            if (!item)
+                throw new Error(`Plan named ${h.agent}@${action.label} but inventory has no such install.`);
+            const trashPath = trashHome(h.agent, item);
+            remaps.push({ from: item.home, to: trashPath });
+            labelToAccount.set(item.label, action.accountId);
+            movedAccountIds.push(action.accountId);
+            entry.trashed.push({ label: item.label, reason: 'stale canonical home — account already holds a provisioned slot', trashPath });
+            manifest.map[`${h.agent}@${item.label}#home`] = trashPath;
+            persistManifest(manifestPath, manifest);
+        }
         for (const action of trashActions) {
             const item = byLabel.get(action.label);
             if (!item)
@@ -504,6 +596,13 @@ export async function applyAccountMigration(agents = [...ALL_AGENT_IDS], deps =
             removeVersionedAlias(h.agent, item.label);
             remaps.push({ from: item.dir, to: trashPath });
             stillPresent.delete(item.label);
+            if (action.accountId) {
+                // A home trashed because its account already holds a slot: anything
+                // bound to this version label follows the account, and the stale
+                // home record clears so spawn resolves through the slot alone.
+                labelToAccount.set(item.label, action.accountId);
+                movedAccountIds.push(action.accountId);
+            }
             entry.trashed.push({ label: item.label, reason: action.reason, trashPath });
             manifest.map[`${h.agent}@${item.label}`] = trashPath;
             persistManifest(manifestPath, manifest);

package/dist/lib/auth-mint.d.ts

@@ -13,7 +13,7 @@
  * stored and optionally synced. Interactive mint is Claude-only; every other
  * harness fails loud with the command that actually provisions it.
  */
-import type { AgentId } from './types.js';
+import type { AgentId, Meta } from './types.js';
 import { type CredentialAccount } from './account-registry.js';
 import { type StorableCredentialKind } from './secrets-policy.js';
 import { type DriveOptions, type PtyDriver } from './fleet/remote-login.js';
@@ -110,6 +110,27 @@ export declare function seedReservedStoreKey(harness: AgentId, kind: StorableCre
     bundle: string;
     key: string;
 };
+export interface AdoptLegacyReservedItemsResult {
+    adopted: Array<{
+        bundle: string;
+        key: string;
+    }>;
+    errors: Array<{
+        bundle: string;
+        key: string;
+        message: string;
+    }>;
+}
+/**
+ * Adopt reserved-store keys written by 1.22.84–1.22.89 as bare file items (no
+ * bundle record) into the file-backed bundle the daemon push reads. Every
+ * `accounts add codex|grok|cursor` from those releases left its worker key in
+ * that shape on the laptop, unpushable; the item name is the same in both
+ * shapes, so adoption re-seeds the bundle from the raw value in place and
+ * nothing already on a worker changes. Idempotent: a key the bundle already
+ * carries is skipped. Local data repair only — it never talks to a peer.
+ */
+export declare function adoptLegacyReservedStoreItems(meta: Pick<Meta, 'accounts' | 'deviceAccounts'>): AdoptLegacyReservedItemsResult;
 /**
  * Create or rotate the named provider account that `agents run --account` and
  * `agents accounts sync` consume. Existing account of a different kind fails

package/dist/lib/auth-mint.js

@@ -1,7 +1,7 @@
 import { resolveAgentName } from './agents.js';
-import { AUTH_BUNDLE, claudeAccountTokenKey, isValidClaudeSetupToken, readClaudeAccountEmail, invalidateClaudeSetupTokenCache, } from './claude-account-token.js';
-import { addAccount, findAccount, readAccountRegistry, setAccountSecret } from './account-registry.js';
-import { bundleBackendSync, bundleExists, bundleExistsSync, keychainRef, pushBundleToHost, readBundleSync, rotateBundleSecretSync, secretsKeychainItem, storeSetSync, writeBundleWithItemsSync, } from './secrets-client.js';
+import { AUTH_BUNDLE, claudeAccountTokenKey, isValidClaudeSetupToken, readClaudeAccountEmail, readReservedCredential, invalidateClaudeSetupTokenCache, } from './claude-account-token.js';
+import { addAccount, findAccount, listNativeAccounts, readAccountRegistry, setAccountSecret } from './account-registry.js';
+import { bundleBackendSync, isSecretsClientError, bundleExists, bundleExistsSync, keychainRef, pushBundleToHost, readBundleSync, rotateBundleSecretSync, secretsKeychainItem, writeBundleWithItemsSync, } from './secrets-client.js';
 import { assertStorableCredentialKind, reservedStoreName, } from './secrets-policy.js';
 import { getBinaryPath, getGlobalDefault, getVersionHomePath, listInstalledVersions } from './installations/versions.js';
 import { shellQuote } from './ssh-exec.js';
@@ -243,13 +243,88 @@ export function seedReservedStoreKey(harness, kind, key, value) {
     const cleaned = value.trim();
     if (!cleaned)
         throw new Error(`Empty ${kind} for reserved store '${name}' key ${key}.`);
-    // A `__<harness>__` reserved store is written and read as raw FILE-backed items,
-    // never as a standalone bundle: the standalone's bundle-name validation rejects
-    // the `__`-wrapped reserved name, so the worker credential rides the raw item
-    // directly, symmetric with how `readReservedCredential` reads it. A first write
-    // and a rotation are the same operation — `store.set` overwrites the item value.
-    storeSetSync('file', secretsKeychainItem(name, key), cleaned);
-    return { bundle: name, key };
+    // A `__<harness>__` reserved store is a real FILE-backed, policy-`never` bundle
+    // — the same shape as the legacy `auth` bundle — because the only transport to
+    // a worker is the ordinary bundle push (`syncReservedStores` →
+    // `pushBundleToHost`), which reads the store as a bundle and imports it
+    // remotely as one. It used to be written as a bare `store.set` item with no
+    // bundle record (the standalone rejected the `__`-wrapped name at the time), so
+    // the push could never read it and no worker received a Cursor/Codex/Grok key.
+    // The item name is unchanged (`agents-cli.secrets.__<harness>__.<KEY>`), so
+    // `readReservedCredential` and every worker that already holds the raw item
+    // keep resolving it. Requires -labs/secrets-cli >= 0.1.1 (reserved-shape
+    // bundle names).
+    const item = secretsKeychainItem(name, key);
+    try {
+        if (bundleExistsSync(name)) {
+            const backend = bundleBackendSync(name);
+            if (backend !== 'file') {
+                throw new Error(`Reserved store '${name}' exists with backend '${backend}', but worker provisioning only reads a FILE-backed store. Recreate it with: agents secrets delete ${name} --yes`);
+            }
+            const bundle = readBundleSync(name);
+            if (key in bundle.vars) {
+                rotateBundleSecretSync(bundle, key, { newValue: cleaned, meta: { type: 'token' } });
+                return { bundle: name, key };
+            }
+            bundle.vars[key] = keychainRef(key);
+            if (!bundle.meta)
+                bundle.meta = {};
+            bundle.meta[key] = { type: 'token' };
+            writeBundleWithItemsSync(bundle, new Map([[item, cleaned]]));
+            return { bundle: name, key };
+        }
+        const bundle = {
+            name,
+            backend: 'file',
+            policy: 'never',
+            description: `Reserved ${harness} worker credentials (${kind}), one key per account; pushed to worker devices by the daemon. Never a native OAuth session.`,
+            vars: { [key]: keychainRef(key) },
+            meta: { [key]: { type: 'token' } },
+        };
+        writeBundleWithItemsSync(bundle, new Map([[item, cleaned]]));
+        return { bundle: name, key };
+    }
+    catch (err) {
+        // A standalone older than 0.1.1 rejects the `__<harness>__` bundle name and
+        // the client only sees a sanitized code. Name the real requirement instead
+        // of leaving `accounts add` to fail with `OPERATION_FAILED`.
+        if (isSecretsClientError(err, 'OPERATION_FAILED')) {
+            throw new Error(`Could not write the reserved store '${name}' as a bundle: ${err.message}. agents-cli needs @phnx-labs/secrets-cli 0.1.1 or newer, which accepts the __<harness>__ bundle name: npm i -g @phnx-labs/secrets-cli@latest`);
+        }
+        throw err;
+    }
+}
+/**
+ * Adopt reserved-store keys written by 1.22.84–1.22.89 as bare file items (no
+ * bundle record) into the file-backed bundle the daemon push reads. Every
+ * `accounts add codex|grok|cursor` from those releases left its worker key in
+ * that shape on the laptop, unpushable; the item name is the same in both
+ * shapes, so adoption re-seeds the bundle from the raw value in place and
+ * nothing already on a worker changes. Idempotent: a key the bundle already
+ * carries is skipped. Local data repair only — it never talks to a peer.
+ */
+export function adoptLegacyReservedStoreItems(meta) {
+    const result = { adopted: [], errors: [] };
+    for (const account of listNativeAccounts(meta)) {
+        const cred = account.workerCredential;
+        if (!cred || !cred.bundle.startsWith('__'))
+            continue;
+        if (cred.kind !== 'setup-token' && cred.kind !== 'api-key')
+            continue;
+        try {
+            if (bundleExistsSync(cred.bundle) && cred.key in readBundleSync(cred.bundle).vars)
+                continue;
+            const value = readReservedCredential(cred.bundle, cred.key);
+            if (value === null)
+                continue;
+            seedReservedStoreKey(account.agent, cred.kind, cred.key, value);
+            result.adopted.push({ bundle: cred.bundle, key: cred.key });
+        }
+        catch (err) {
+            result.errors.push({ bundle: cred.bundle, key: cred.key, message: err.message });
+        }
+    }
+    return result;
 }
 /**
  * Create or rotate the named provider account that `agents run --account` and

package/dist/lib/daemon/auth-sync-service.js

@@ -75,6 +75,8 @@ export class AuthSyncService extends BasePeriodicService {
         // the only transport — provisioning (above) writes only locally (invariant 1).
         try {
             const stores = await syncReservedStores();
+            if (stores.adopted.length > 0)
+                ctx.log('INFO', `auth-sync: adopted ${stores.adopted.length} legacy reserved item(s) into their bundle: ${stores.adopted.map((a) => `${a.bundle} ${a.key}`).join(', ')}`);
             for (const p of stores.pushed)
                 ctx.log('INFO', `auth-sync: pushed ${p.bundle} (${p.keys.length} key(s)) to ${p.device}`);
             for (const err of stores.errors)

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-policy.d.ts

@@ -171,6 +171,11 @@ export declare function readDeliveryMemo(root?: string): Record<string, string>;
 export declare function peerPresentKeys(peer: string, accounts: ReservedSyncAccount[], memo: Record<string, string>, legacyAuthReady: boolean): Record<string, ReadonlySet<string>>;
 export interface ReservedStoreSyncResult {
     publisher: string | null;
+    /** Legacy raw reserved items adopted into their bundle on this box before planning (local repair). */
+    adopted: Array<{
+        bundle: string;
+        key: string;
+    }>;
     pushed: Array<{
         device: string;
         bundle: string;
@@ -197,6 +202,18 @@ export interface ReservedStoreSyncDeps {
     localReady?: boolean;
     /** Does THIS publisher hold (bundle, key) to push? Defaults to a local bundle read. */
     hasLocalKey?: (bundle: string, key: string) => boolean;
+    /** Adopt pre-bundle raw reserved items locally before planning; defaults to `adoptLegacyReservedStoreItems`. */
+    adoptLegacy?: (meta: Pick<Meta, 'accounts' | 'deviceAccounts'>) => Promise<{
+        adopted: Array<{
+            bundle: string;
+            key: string;
+        }>;
+        errors: Array<{
+            bundle: string;
+            key: string;
+            message: string;
+        }>;
+    }>;
     push?: (bundle: string, host: string) => Promise<PushBundleResult>;
     sshTarget?: (device: DeviceProfile) => string;
 }

package/dist/lib/secrets-policy.js

@@ -375,11 +375,24 @@ function defaultHasLocalKey(bundle, key) {
  * there is no second scheduler. The daemon runs this each tick.
  */
 export async function syncReservedStores(deps = {}) {
-    const result = { publisher: null, pushed: [], skipped: [], errors: [] };
+    const result = { publisher: null, adopted: [], pushed: [], skipped: [], errors: [] };
     const localName = deps.localName ?? machineId();
     const localNorm = normalizeHost(localName);
     const root = deps.userAgentsDir ?? getUserAgentsDir();
     const meta = (deps.readMetaFn ?? readMeta)();
+    // Local repair first: a reserved key written by 1.22.84–1.22.89 is a bare
+    // file item with no bundle record, which the push below cannot read. Adopt
+    // it into its bundle here so the plan sees it; nothing leaves the box.
+    const adopt = deps.adoptLegacy ?? (async (m) => (await import('./auth-mint.js')).adoptLegacyReservedStoreItems(m));
+    try {
+        const adoption = await adopt(meta);
+        result.adopted.push(...adoption.adopted);
+        for (const err of adoption.errors)
+            result.errors.push({ device: localName, message: `adopt ${err.bundle} ${err.key}: ${err.message}` });
+    }
+    catch (err) {
+        result.errors.push({ device: localName, message: `adopt legacy reserved items: ${err.message}` });
+    }
     const hasLocalKey = deps.hasLocalKey ?? defaultHasLocalKey;
     const targets = reservedSyncTargets(meta).filter((t) => hasLocalKey(t.bundle, t.key));
     const devices = (deps.listDevices ?? defaultDevices)().filter((d) => normalizeHost(d.name) !== localNorm);

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.89",
+  "version": "1.22.91",
   "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) {