@phnx-labs/agents-cli 1.22.30 → 1.22.32

package/dist/lib/secrets/session-store.d.ts

@@ -93,10 +93,6 @@ export declare function deleteBundleSessions(name: string): void;
 /** Delete one bundle's session blob and prune it from the index. */
 export declare function deleteSession(name: string, harness?: string): void;
 export declare function deleteLeaseSession(leaseId: string): number;
-export declare function activeLeaseSessions(now?: number): Array<{
-    name: string;
-    lease: SecretLease;
-}>;
 /** Delete every session blob + the index (for `secrets lock --all`). */
 export declare function deleteAllSessions(): void;
 /** Rehydrate every unexpired session into `[name, entry]` pairs for the broker to

package/dist/lib/secrets/session-store.js

@@ -208,11 +208,6 @@ export function deleteLeaseSession(leaseId) {
     }
     return deleted;
 }
-export function activeLeaseSessions(now = Date.now()) {
-    return rehydrateSessions(now)
-        .filter((item) => Boolean(item.entry.lease))
-        .map(({ name, entry }) => ({ name, lease: entry.lease }));
-}
 /** Delete every session blob + the index (for `secrets lock --all`). */
 export function deleteAllSessions() {
     if (!shouldPersist())

package/dist/lib/self-heal/checks/hook-runtime.d.ts

@@ -0,0 +1,2 @@
+import type { HealCheck } from '../types.js';
+export declare const hookRuntimeCheck: HealCheck;

package/dist/lib/self-heal/checks/hook-runtime.js

@@ -0,0 +1,16 @@
+// hook-runtime check — detects and bounded-repairs agents-managed generated
+// hook shims (~/.agents/.cache/shims/hooks/<name>.sh). A native hook command can
+// look wired while its generated wrapper is missing, non-executable, non-file,
+// or broken — silent breakage. Repair runs at most once per unique path per
+// pass (no retry, no sync recursion); unresolved findings stay needsAttention.
+import { resultOf } from '../types.js';
+import { repairManagedHookRuntimeArtifacts } from '../../hooks.js';
+export const hookRuntimeCheck = {
+    id: 'hook-runtime',
+    title: 'Generated hook runtime shims',
+    cadence: 'frequent',
+    async run(ctx) {
+        const report = repairManagedHookRuntimeArtifacts({ dryRun: ctx.dryRun });
+        return resultOf(report.fixed, report.needsAttention);
+    },
+};

package/dist/lib/self-heal/registry.js

@@ -5,15 +5,18 @@
 // SelfHealReport. Both front doors — the daemon (by cadence) and `agents doctor`
 // (all, or by id) — call runSelfHeal.
 import { resourcesCheck } from './checks/resources.js';
+import { hookRuntimeCheck } from './checks/hook-runtime.js';
 import { shimsCheck } from './checks/shims.js';
 import { shadowingCheck } from './checks/shadowing.js';
 import { pathCheck } from './checks/path.js';
-// Order matters: cheap structural fixes (shims, shadow adoption, PATH) before the
-// heavier resource reconciliation, so a freshly-repaired shim is in place first.
+// Order matters: cheap structural fixes (shims, shadow adoption, PATH, generated
+// hook wrappers) before the heavier resource reconciliation, so a freshly-
+// repaired shim is in place first.
 export const HEAL_CHECKS = [
     shimsCheck,
     shadowingCheck,
     pathCheck,
+    hookRuntimeCheck,
     resourcesCheck,
 ];
 /** Run the selected checks, isolating per-check failures. */

package/dist/lib/self-heal/types.d.ts

@@ -1,4 +1,4 @@
-export type HealCheckId = 'resources' | 'shims' | 'shadowing' | 'path';
+export type HealCheckId = 'resources' | 'hook-runtime' | 'shims' | 'shadowing' | 'path';
 /** When the daemon schedules a check. */
 export type HealCadence = 'startup' | 'frequent' | 'periodic';
 export interface HealCtx {

package/dist/lib/session/{favorites.d.ts → bookmarks.d.ts}

@@ -1,39 +1,39 @@
 /**
- * Favorited sessions — the durable "keep this one handy" mark a human puts on a
+ * Bookmarked sessions — the durable "keep this one handy" mark a human puts on a
  * session, deliberately kept OUT of the session index.
  *
  * `sessions.db` is a rebuildable CACHE: a reindex or a schema bump throws its
- * rows away and re-derives them from the transcripts on disk. A favorite is not
+ * rows away and re-derives them from the transcripts on disk. A bookmark is not
  * derivable from a transcript — it is a human's choice — so a column there would
  * be silently lost on the next rebuild. It lives in `~/.agents/.history/` instead,
  * next to the actor sidecars, which is never pruned.
  *
  * One flat set of session ids. The id is the transcript's own uuid, so it is
  * stable and machine-independent — but the file is NOT synced today: session sync
- * carries `.history/backups/` (`lib/session/sync/agents.ts`), not this. Favorites
+ * carries `.history/backups/` (`lib/session/sync/agents.ts`), not this. Bookmarks
  * are therefore per-machine; carrying them across the fleet would mean adding
  * them to the sync manifest, which this does not do.
  *
- * Reads are memoized against the file's mtime — the picker asks `isFavorite` once
+ * Reads are memoized against the file's mtime — the picker asks `isBookmarked` once
  * per rendered row, and re-reading a JSON file per row on every keystroke is the
  * kind of cost that makes a TUI feel broken.
  */
-export declare function favoritesFilePath(): string;
+export declare function bookmarksFilePath(): string;
 /** Drop the memoized read. Tests that write the file directly need this; nothing
  *  in the CLI does, because every mutation here refreshes the cache itself. */
-export declare function clearFavoritesCache(): void;
+export declare function clearBookmarksCache(): void;
 /**
- * Every favorited session id. Empty (never throws) when the file is absent,
- * unreadable, or malformed — a corrupt favorites file must not take down
+ * Every bookmarked session id. Empty (never throws) when the file is absent,
+ * unreadable, or malformed — a corrupt bookmarks file must not take down
  * `agents sessions`.
  */
-export declare function listFavorites(): Set<string>;
-export declare function isFavorite(sessionId: string | undefined): boolean;
+export declare function listBookmarks(): Set<string>;
+export declare function isBookmarked(sessionId: string | undefined): boolean;
 /**
- * Set (or clear) the favorite mark on a session. Returns the resulting state, so
+ * Set (or clear) the bookmark mark on a session. Returns the resulting state, so
  * a caller can report it without a second read. A no-op write is skipped, which
  * keeps the file's mtime — and every other process's memoized read — untouched.
  */
-export declare function setFavorite(sessionId: string, on: boolean): boolean;
-/** Flip the mark; returns the new state (`true` = now favorited). */
-export declare function toggleFavorite(sessionId: string): boolean;
+export declare function setBookmark(sessionId: string, on: boolean): boolean;
+/** Flip the mark; returns the new state (`true` = now bookmarked). */
+export declare function toggleBookmark(sessionId: string): boolean;

package/dist/lib/session/{favorites.js → bookmarks.js}

@@ -1,28 +1,28 @@
 /**
- * Favorited sessions — the durable "keep this one handy" mark a human puts on a
+ * Bookmarked sessions — the durable "keep this one handy" mark a human puts on a
  * session, deliberately kept OUT of the session index.
  *
  * `sessions.db` is a rebuildable CACHE: a reindex or a schema bump throws its
- * rows away and re-derives them from the transcripts on disk. A favorite is not
+ * rows away and re-derives them from the transcripts on disk. A bookmark is not
  * derivable from a transcript — it is a human's choice — so a column there would
  * be silently lost on the next rebuild. It lives in `~/.agents/.history/` instead,
  * next to the actor sidecars, which is never pruned.
  *
  * One flat set of session ids. The id is the transcript's own uuid, so it is
  * stable and machine-independent — but the file is NOT synced today: session sync
- * carries `.history/backups/` (`lib/session/sync/agents.ts`), not this. Favorites
+ * carries `.history/backups/` (`lib/session/sync/agents.ts`), not this. Bookmarks
  * are therefore per-machine; carrying them across the fleet would mean adding
  * them to the sync manifest, which this does not do.
  *
- * Reads are memoized against the file's mtime — the picker asks `isFavorite` once
+ * Reads are memoized against the file's mtime — the picker asks `isBookmarked` once
  * per rendered row, and re-reading a JSON file per row on every keystroke is the
  * kind of cost that makes a TUI feel broken.
  */
 import fs from 'node:fs';
 import path from 'node:path';
 import { getHistoryDir } from '../state.js';
-export function favoritesFilePath() {
-    return path.join(getHistoryDir(), 'favorites.json');
+export function bookmarksFilePath() {
+    return path.join(getHistoryDir(), 'bookmarks.json');
 }
 /** Memoized parse, invalidated by the file's mtime+size (another process — or
  *  another machine's sync — can rewrite it under us). */
@@ -38,16 +38,16 @@ function statKey(file) {
 }
 /** Drop the memoized read. Tests that write the file directly need this; nothing
  *  in the CLI does, because every mutation here refreshes the cache itself. */
-export function clearFavoritesCache() {
+export function clearBookmarksCache() {
     cache = null;
 }
 /**
- * Every favorited session id. Empty (never throws) when the file is absent,
- * unreadable, or malformed — a corrupt favorites file must not take down
+ * Every bookmarked session id. Empty (never throws) when the file is absent,
+ * unreadable, or malformed — a corrupt bookmarks file must not take down
  * `agents sessions`.
  */
-export function listFavorites() {
-    const file = favoritesFilePath();
+export function listBookmarks() {
+    const file = bookmarksFilePath();
     const key = statKey(file);
     if (cache && cache.key === key)
         return cache.ids;
@@ -64,14 +64,14 @@ export function listFavorites() {
     cache = { key, ids };
     return ids;
 }
-export function isFavorite(sessionId) {
+export function isBookmarked(sessionId) {
     if (!sessionId)
         return false;
-    return listFavorites().has(sessionId);
+    return listBookmarks().has(sessionId);
 }
 /** Atomic write (tmp + rename) so a concurrent reader never sees a half file. */
-function writeFavorites(ids) {
-    const file = favoritesFilePath();
+function writeBookmarks(ids) {
+    const file = bookmarksFilePath();
     fs.mkdirSync(path.dirname(file), { recursive: true });
     const body = { version: 1, sessionIds: [...ids].sort() };
     const tmp = `${file}.${process.pid}.tmp`;
@@ -80,22 +80,22 @@ function writeFavorites(ids) {
     cache = { key: statKey(file), ids };
 }
 /**
- * Set (or clear) the favorite mark on a session. Returns the resulting state, so
+ * Set (or clear) the bookmark mark on a session. Returns the resulting state, so
  * a caller can report it without a second read. A no-op write is skipped, which
  * keeps the file's mtime — and every other process's memoized read — untouched.
  */
-export function setFavorite(sessionId, on) {
-    const ids = new Set(listFavorites());
+export function setBookmark(sessionId, on) {
+    const ids = new Set(listBookmarks());
     if (ids.has(sessionId) === on)
         return on;
     if (on)
         ids.add(sessionId);
     else
         ids.delete(sessionId);
-    writeFavorites(ids);
+    writeBookmarks(ids);
     return on;
 }
-/** Flip the mark; returns the new state (`true` = now favorited). */
-export function toggleFavorite(sessionId) {
-    return setFavorite(sessionId, !isFavorite(sessionId));
+/** Flip the mark; returns the new state (`true` = now bookmarked). */
+export function toggleBookmark(sessionId) {
+    return setBookmark(sessionId, !isBookmarked(sessionId));
 }

package/dist/lib/session/state.js

@@ -194,7 +194,10 @@ const TICKET_BRANCH_RE = /(?:^|[/_-])([a-z]{2,6})-(\d{2,6})(?=[/_-]|$)/;
 /** Keys that look like tickets but aren't — avoid false positives from branches. */
 const TICKET_DENYLIST = new Set(['UTF', 'SHA', 'ISO', 'RFC', 'IPV', 'X86', 'ARM', 'MP', 'H']);
 const PR_URL_RE = /https:\/\/github\.com\/[^\s"'()<>]+\/pull\/(\d+)/;
-export const WORKTREE_RE = /\/\.agents\/worktrees\/([^/]+)/;
+// Either separator: a Windows session cwd is `…\.agents\worktrees\<slug>`, and a
+// forward-slash-only pattern silently derived no slug there (the RUSH-2358
+// worktree_slug parity test is red on the Windows CI leg for exactly this).
+export const WORKTREE_RE = /[\\/]\.agents[\\/]worktrees[\\/]([^\\/]+)/;
 /** gh invocations that create/open a PR. */
 const GH_PR_CREATE_RE = /\bgh\s+pr\s+(?:create|new)\b/;
 /** gh invocation that opens an issue — the created number is read from its result. */

package/dist/lib/startup/command-registry.d.ts

@@ -39,6 +39,7 @@ export declare const loadPlugins: ModuleLoader;
 export declare const loadWorkflows: ModuleLoader;
 export declare const loadWorktree: ModuleLoader;
 export declare const loadVersions: ModuleLoader;
+export declare const loadUpdate: ModuleLoader;
 export declare const loadImport: ModuleLoader;
 export declare const loadExport: ModuleLoader;
 export declare const loadPackages: ModuleLoader;

package/dist/lib/startup/command-registry.js

@@ -38,6 +38,7 @@ export const loadPlugins = async () => (await import('../../commands/plugins.js'
 export const loadWorkflows = async () => (await import('../../commands/workflows.js')).registerWorkflowsCommands;
 export const loadWorktree = async () => (await import('../../commands/worktree.js')).registerWorktreeCommands;
 export const loadVersions = async () => (await import('../../commands/versions.js')).registerVersionsCommands;
+export const loadUpdate = async () => (await import('../../commands/update.js')).registerUpdateCommand;
 export const loadImport = async () => (await import('../../commands/import.js')).registerImportCommand;
 export const loadExport = async () => (await import('../../commands/export.js')).registerExportCommand;
 export const loadPackages = async () => (await import('../../commands/packages.js')).registerPackagesCommands;
@@ -168,6 +169,7 @@ export const COMMAND_LOADERS = {
     remove: [loadVersions],
     rm: [loadVersions],
     purge: [loadVersions],
+    update: [loadUpdate],
     prune: [loadVersions, loadPrune],
     import: [loadImport],
     export: [loadExport],

package/dist/lib/versions.d.ts

@@ -414,6 +414,30 @@ export declare function verifyInstalledBinaryLaunches(agent: AgentId, version: s
     ok: boolean;
     detail?: string;
 }>;
+/**
+ * The launch probe itself, addressed by PATH rather than by installed version.
+ *
+ * `verifyInstalledBinaryLaunches` is this function applied to a version dir that
+ * is already live. `agents update` needs the identical check applied to a release
+ * that is still STAGED — probing it before the swap is what makes the update
+ * transactional, since a staged release that cannot launch is discarded instead
+ * of replacing a working one. Both callers must agree byte-for-byte on what
+ * "launches" means, hence one implementation.
+ *
+ * `posixBinary` is the extensionless launch target. The real launch target
+ * differs by platform, so we probe whatever `agents run` actually execs: on
+ * Windows that is the npm `.cmd` wrapper beside it (exec.ts uses
+ * `absPath + '.cmd'`), which chains to the native `.exe`; a gutted install
+ * (renamed/missing `.exe`) makes that wrapper emit "is not recognized" — the
+ * exact win-mini failure a vendor auto-update leaves behind. Probing the
+ * extensionless `.bin/<cli>` instead would ENOENT even on a HEALTHY Windows
+ * install, so we DON'T. On POSIX the `.bin/<cli>` binary is the launch target
+ * and is probed directly.
+ */
+export declare function verifyBinaryLaunches(posixBinary: string, home: string): Promise<{
+    ok: boolean;
+    detail?: string;
+}>;
 /**
  * Launch-path self-heal. Given the concrete version `agents run` is about to
  * spawn, make sure it will actually run — and if not, repair it instead of

package/dist/lib/versions.js

@@ -34,6 +34,8 @@ import { discoverPermissionGroups, getActivePermissionPresetName, readPermission
 import { parseMcpServerConfig, isProjectMcpTrusted } from './mcp.js';
 import { createVersionedAlias, removeVersionedAlias, getConfigSymlinkVersion, ensureClaudeInsideSymlink, assertIsolationBoundary, } from './shims.js';
 import { importInstallScriptBinary } from './import.js';
+import { createInstallation } from './installations/store.js';
+import { INSTALLATION_RECORD_FILE } from './installations/types.js';
 import { IS_WINDOWS, composeWin32CommandLine } from './platform/index.js';
 import { listInstalledSubagents } from './subagents.js';
 import { listInstalledWorkflows } from './workflows.js';
@@ -1579,6 +1581,10 @@ export async function installVersion(agent, version, onProgress, opts) {
                correctly reports it uninstalled. */
         }
         createVersionedAlias(agent, installedVersion);
+        // Freeze this installation's identity. The dir name is its stable label from
+        // here on; the release it carries is recorded separately so `agents update`
+        // can move the release without invalidating any reference to the label.
+        createInstallation(agent, installedVersion, installedVersion);
         // The self-updating binary just changed on disk — drop the cached
         // `--version` so `agents view` reflects the freshly-installed release.
         invalidateLiveVersionCache(agent);
@@ -1633,6 +1639,9 @@ export async function installVersion(agent, version, onProgress, opts) {
     // load-bearing: it ensures `version` (which VERSION_RE permits to start with
     // `-`) is never passed as a standalone npm CLI flag.
     const packageSpec = `${agentConfig.npmPackage}@${version}`;
+    // Set once the install has passed its integrity gate; read after the try so
+    // the success path's bookkeeping sits outside the catch's cleanup.
+    let healthyVersion;
     try {
         // Check npm is available
         const winShell = process.platform === 'win32';
@@ -1719,8 +1728,10 @@ export async function installVersion(agent, version, onProgress, opts) {
                     + `The install is incomplete — the platform binary is missing. Re-run: agents add ${agent}@${installedVersion}`,
             };
         }
-        emit('version.install', { agent, version: installedVersion });
-        return { success: true, installedVersion };
+        // The install is healthy from here. Identity is frozen AFTER the try (see
+        // below) so a bookkeeping write failure cannot fall into the catch and wipe
+        // a working install.
+        healthyVersion = installedVersion;
     }
     catch (err) {
         // Clean up on failure — preserve `home/` in case a prior install left
@@ -1731,13 +1742,20 @@ export async function installVersion(agent, version, onProgress, opts) {
         emit('version.install', { agent, version, error: err.message });
         return { success: false, installedVersion: version, error: err.message };
     }
+    // Freeze this installation's identity (see the installScript branch above).
+    createInstallation(agent, healthyVersion, healthyVersion);
+    emit('version.install', { agent, version: healthyVersion });
+    return { success: true, installedVersion: healthyVersion };
 }
 // Version-dir entries that are STATE, not install output, and so must survive a
-// clean reinstall: `home/`, and the `.isolated` marker that is the single source
-// of truth for "this copy is walled off". Losing the marker would silently demote
+// clean reinstall: `home/`, the `.isolated` marker that is the single source
+// of truth for "this copy is walled off", and `installation.json`, which carries
+// this installation's frozen identity. Losing the marker would silently demote
 // an isolated copy to a normal one on its first repair — after which shim
-// self-heal would hand it a bare `<agent>` shim and a PATH entry.
-const PRESERVED_ON_CLEAN_REINSTALL = new Set(['home', '.isolated']);
+// self-heal would hand it a bare `<agent>` shim and a PATH entry. Losing the
+// installation record would mint a NEW id for the same install on its first
+// repair, discarding its release history.
+const PRESERVED_ON_CLEAN_REINSTALL = new Set(['home', '.isolated', INSTALLATION_RECORD_FILE]);
 /**
  * Remove install artifacts from a version directory, preserving `home/` which
  * contains the user's conversation history, sessions, history.jsonl, tasks,
@@ -2233,16 +2251,31 @@ export function probeSpawnSpec(binary, isWin) {
     return { command: binary, args: ['--version'], shell: false };
 }
 export async function verifyInstalledBinaryLaunches(agent, version) {
-    // The real launch target differs by platform, so probe whatever `agents run`
-    // actually execs. On Windows that's the npm `.cmd` wrapper (exec.ts uses
-    // `absPath + '.cmd'`), which chains to the native `.exe`; a gutted install
-    // (renamed/missing `.exe`) makes that wrapper emit "is not recognized" — the
-    // exact win-mini failure a vendor auto-update leaves behind. Probing the
-    // extensionless `.bin/<cli>` instead would ENOENT even on a HEALTHY Windows
-    // install, so we DON'T. On POSIX the `.bin/<cli>` binary is the launch target
-    // and is probed directly.
+    return verifyBinaryLaunches(getBinaryPath(agent, version), getVersionHomePath(agent, version));
+}
+/**
+ * The launch probe itself, addressed by PATH rather than by installed version.
+ *
+ * `verifyInstalledBinaryLaunches` is this function applied to a version dir that
+ * is already live. `agents update` needs the identical check applied to a release
+ * that is still STAGED — probing it before the swap is what makes the update
+ * transactional, since a staged release that cannot launch is discarded instead
+ * of replacing a working one. Both callers must agree byte-for-byte on what
+ * "launches" means, hence one implementation.
+ *
+ * `posixBinary` is the extensionless launch target. The real launch target
+ * differs by platform, so we probe whatever `agents run` actually execs: on
+ * Windows that is the npm `.cmd` wrapper beside it (exec.ts uses
+ * `absPath + '.cmd'`), which chains to the native `.exe`; a gutted install
+ * (renamed/missing `.exe`) makes that wrapper emit "is not recognized" — the
+ * exact win-mini failure a vendor auto-update leaves behind. Probing the
+ * extensionless `.bin/<cli>` instead would ENOENT even on a HEALTHY Windows
+ * install, so we DON'T. On POSIX the `.bin/<cli>` binary is the launch target
+ * and is probed directly.
+ */
+export async function verifyBinaryLaunches(posixBinary, home) {
     const isWin = process.platform === 'win32';
-    const binary = isWin ? getBinaryPath(agent, version) + '.cmd' : getBinaryPath(agent, version);
+    const binary = isWin ? posixBinary + '.cmd' : posixBinary;
     if (!fs.existsSync(binary)) {
         // Windows: a missing `.cmd` means a non-npm/global agent (droid.exe) we can't
         // safely probe — treat as healthy (isVersionInstalled validates presence).
@@ -2259,7 +2292,7 @@ export async function verifyInstalledBinaryLaunches(agent, version) {
         await execFileAsync(spec.command, spec.args, {
             timeout: 15000,
             shell: spec.shell,
-            env: { ...process.env, HOME: getVersionHomePath(agent, version) },
+            env: { ...process.env, HOME: home },
         });
         return { ok: true };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.30",
+  "version": "1.22.32",
   "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",
@@ -58,7 +58,7 @@
     "test": "node ./node_modules/vitest/vitest.mjs run",
     "bench": "node ./node_modules/vitest/vitest.mjs bench --run",
     "typecheck:bench": "tsc --noEmit --ignoreConfig --skipLibCheck --module esnext --moduleResolution bundler --target es2022 --strict --esModuleInterop --lib es2022 --types node src/lib/*.bench.ts src/lib/**/*.bench.ts",
-    "test:remote": "scripts/sandbox.sh 'bun install && bun run build && bun run test'",
+    "test:remote": "scripts/sandbox.sh 'cd apps/cli && bun install && bun run build && bun run test'",
     "verify-docs": "scripts/verify-docs.sh",
     "test:watch": "node ./node_modules/vitest/vitest.mjs"
   },