@phnx-labs/agents-cli 1.22.31 → 1.22.32

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/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.31",
+  "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"
   },