@phnx-labs/agents-cli 1.22.88 → 1.22.90

package/dist/lib/self-update.d.ts

@@ -104,18 +104,22 @@ export declare function resolveMultiInstallInventory(runningRoot: string, runnin
 /**
  * The on-disk package root of the copy that is currently running.
  *
- * For a plain JS install this is just `<__dirname>/..`. Under the compiled
- * standalone binary (shipped since 1.20.53) it is not: Bun sets `__dirname` to
- * its embedded virtual FS, so `<__dirname>/..` yields `/$bunfs` — a path that
- * exists nowhere. That phantom value was reported as a second install by the
- * multi-install check, and rejected by deriveGlobalPrefix as "not an
- * npm-managed install", so every self-upgrade from a compiled copy failed.
+ * For a plain JS install, walk up from the CALLING module's directory to the
+ * directory whose package.json names this package. Never assume a fixed depth:
+ * `<__dirname>/..` is the root only for a module directly under `dist/`, and
+ * from `dist/lib/daemon/self-update-service.js` it answered `dist/lib`, which
+ * deriveGlobalPrefix rejected as "not an npm-managed install" on every daemon
+ * self-update tick (2026-09-07 fleet incident).
  *
- * The physical executable is `process.execPath`, which ships inside the
- * package (`<packageRoot>/dist/bin/agents`). Walk up from it to the directory
- * whose package.json actually names this package rather than assuming a fixed
- * depth, so a change to the dist layout surfaces as a clear throw here instead
- * of a wrong prefix that npm would happily install into.
+ * Under the compiled standalone binary (shipped since 1.20.53) `__dirname` is
+ * Bun's embedded virtual FS, so walking up from it yields `/$bunfs` — a path
+ * that exists nowhere. That phantom value was reported as a second install by
+ * the multi-install check and rejected by deriveGlobalPrefix, so every
+ * self-upgrade from a compiled copy failed. The physical executable is
+ * `process.execPath`, which ships inside the package
+ * (`<packageRoot>/dist/bin/agents`); walk up from it instead. Either way a
+ * change to the dist layout surfaces as a clear throw here rather than a wrong
+ * prefix that npm would happily install into.
  */
 export declare function resolveRunningPackageRoot(dirname: string, execPath?: string): string;
 /**
@@ -175,8 +179,30 @@ export declare function installPackageIntoPrefix(spec: string, prefix: string, s
  * alias shims afterwards via refreshAliasShims() rather than relying on the
  * package's postinstall hook.
  *
+ * Unlike npm's arborist (see {@link sweepStaleInstallStaging}: retire-rename,
+ * then one final rename), bun's write into the package directory is NOT known
+ * to be atomic — files may land incrementally. Anything that trusts a version
+ * bump on disk written by ANOTHER process (the daemon's stale-install relaunch
+ * in `daemon/self-update-service.ts`) must therefore gate on
+ * {@link installLooksSettled} rather than on the version alone.
+ *
  * `signal` behaves exactly as documented on {@link installPackageIntoPrefix}.
  */
+/** How long an install's package.json must have been at rest before a foreign version bump is trusted. */
+export declare const INSTALL_SETTLE_MS = 60000;
+/**
+ * True when the install at `packageRoot` looks complete: its package.json has
+ * not been modified for at least `settleMs`, and every `bin` entry it declares
+ * exists on disk. This is the guard for trusting a version bump that a
+ * DIFFERENT process wrote (an operator's `agents` auto-update, `agents
+ * upgrade`, the installer) without re-running that process's own verification:
+ * npm's reify is an atomic rename, but bun's is not (see
+ * {@link installPackageWithBun}), so a reader can catch bun mid-extraction —
+ * package.json present, `dist/` still landing. An install finishes in seconds;
+ * a minute of quiet plus the bin entry present rules that window out. Any
+ * read error means "not settled".
+ */
+export declare function installLooksSettled(packageRoot: string, settleMs?: number, now?: number): boolean;
 export declare function installPackageWithBun(spec: string, signal?: AbortSignal): Promise<void>;
 /**
  * Verify a downloaded tarball's bytes against a Subresource Integrity (SRI)

package/dist/lib/self-update.js

@@ -240,37 +240,59 @@ function isPackageRoot(dir) {
 /**
  * The on-disk package root of the copy that is currently running.
  *
- * For a plain JS install this is just `<__dirname>/..`. Under the compiled
- * standalone binary (shipped since 1.20.53) it is not: Bun sets `__dirname` to
- * its embedded virtual FS, so `<__dirname>/..` yields `/$bunfs` — a path that
- * exists nowhere. That phantom value was reported as a second install by the
- * multi-install check, and rejected by deriveGlobalPrefix as "not an
- * npm-managed install", so every self-upgrade from a compiled copy failed.
+ * For a plain JS install, walk up from the CALLING module's directory to the
+ * directory whose package.json names this package. Never assume a fixed depth:
+ * `<__dirname>/..` is the root only for a module directly under `dist/`, and
+ * from `dist/lib/daemon/self-update-service.js` it answered `dist/lib`, which
+ * deriveGlobalPrefix rejected as "not an npm-managed install" on every daemon
+ * self-update tick (2026-09-07 fleet incident).
  *
- * The physical executable is `process.execPath`, which ships inside the
- * package (`<packageRoot>/dist/bin/agents`). Walk up from it to the directory
- * whose package.json actually names this package rather than assuming a fixed
- * depth, so a change to the dist layout surfaces as a clear throw here instead
- * of a wrong prefix that npm would happily install into.
+ * Under the compiled standalone binary (shipped since 1.20.53) `__dirname` is
+ * Bun's embedded virtual FS, so walking up from it yields `/$bunfs` — a path
+ * that exists nowhere. That phantom value was reported as a second install by
+ * the multi-install check and rejected by deriveGlobalPrefix, so every
+ * self-upgrade from a compiled copy failed. The physical executable is
+ * `process.execPath`, which ships inside the package
+ * (`<packageRoot>/dist/bin/agents`); walk up from it instead. Either way a
+ * change to the dist layout surfaces as a clear throw here rather than a wrong
+ * prefix that npm would happily install into.
  */
 export function resolveRunningPackageRoot(dirname, execPath = process.execPath) {
-    const fromDirname = path.resolve(dirname, '..');
-    if (!isBunVirtualPath(fromDirname))
-        return fromDirname;
+    if (!isBunVirtualPath(dirname)) {
+        // Walk up from the CALLING module's directory to the package.json that
+        // names this package. The previous `path.resolve(dirname, '..')` was only
+        // right for a module one level below the root (dist/bootstrap.js); from
+        // dist/lib/daemon/self-update-service.js it answered `dist/lib`, so
+        // `deriveGlobalPrefix` threw "not an npm-managed install" on every daemon
+        // self-update tick, fleet-wide, and no daemon ever relaunched onto a
+        // release (2026-09-07: eight workers still running 1.22.79 code four
+        // releases later).
+        const found = findPackageRootAbove(dirname);
+        if (found)
+            return found;
+        throw new Error(`Cannot locate the running agents-cli install: no ${NPM_PACKAGE_NAME} package.json above ` +
+            `${dirname}. Reinstall with: npm install -g ${NPM_PACKAGE_NAME}`);
+    }
     if (!execPath || isBunVirtualPath(execPath)) {
-        throw new Error(`Cannot locate the running agents-cli install: __dirname is the Bun virtual path ${fromDirname} ` +
+        throw new Error(`Cannot locate the running agents-cli install: __dirname is the Bun virtual path ${dirname} ` +
             `and process.execPath (${execPath || '(empty)'}) is not a real file. ` +
             `Reinstall with: npm install -g ${NPM_PACKAGE_NAME}`);
     }
-    let dir = path.dirname(path.resolve(execPath));
+    const found = findPackageRootAbove(path.dirname(path.resolve(execPath)));
+    if (found)
+        return found;
+    throw new Error(`Cannot locate the running agents-cli install: no ${NPM_PACKAGE_NAME} package.json above ` +
+        `${execPath}. Reinstall with: npm install -g ${NPM_PACKAGE_NAME}`);
+}
+/** Nearest ancestor of `start` (inclusive) whose package.json names this package, or null. */
+function findPackageRootAbove(start) {
+    let dir = path.resolve(start);
     for (;;) {
         if (isPackageRoot(dir))
             return dir;
         const parent = path.dirname(dir);
-        if (parent === dir) {
-            throw new Error(`Cannot locate the running agents-cli install: no ${NPM_PACKAGE_NAME} package.json above ` +
-                `${execPath}. Reinstall with: npm install -g ${NPM_PACKAGE_NAME}`);
-        }
+        if (parent === dir)
+            return null;
         dir = parent;
     }
 }
@@ -376,8 +398,43 @@ export async function installPackageIntoPrefix(spec, prefix, signal) {
  * alias shims afterwards via refreshAliasShims() rather than relying on the
  * package's postinstall hook.
  *
+ * Unlike npm's arborist (see {@link sweepStaleInstallStaging}: retire-rename,
+ * then one final rename), bun's write into the package directory is NOT known
+ * to be atomic — files may land incrementally. Anything that trusts a version
+ * bump on disk written by ANOTHER process (the daemon's stale-install relaunch
+ * in `daemon/self-update-service.ts`) must therefore gate on
+ * {@link installLooksSettled} rather than on the version alone.
+ *
  * `signal` behaves exactly as documented on {@link installPackageIntoPrefix}.
  */
+/** How long an install's package.json must have been at rest before a foreign version bump is trusted. */
+export const INSTALL_SETTLE_MS = 60_000;
+/**
+ * True when the install at `packageRoot` looks complete: its package.json has
+ * not been modified for at least `settleMs`, and every `bin` entry it declares
+ * exists on disk. This is the guard for trusting a version bump that a
+ * DIFFERENT process wrote (an operator's `agents` auto-update, `agents
+ * upgrade`, the installer) without re-running that process's own verification:
+ * npm's reify is an atomic rename, but bun's is not (see
+ * {@link installPackageWithBun}), so a reader can catch bun mid-extraction —
+ * package.json present, `dist/` still landing. An install finishes in seconds;
+ * a minute of quiet plus the bin entry present rules that window out. Any
+ * read error means "not settled".
+ */
+export function installLooksSettled(packageRoot, settleMs = INSTALL_SETTLE_MS, now = Date.now()) {
+    try {
+        const pkgJsonPath = path.join(packageRoot, 'package.json');
+        const stat = fs.statSync(pkgJsonPath);
+        if (now - stat.mtimeMs < settleMs)
+            return false;
+        const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+        const bins = typeof pkg.bin === 'string' ? [pkg.bin] : Object.values(pkg.bin ?? {});
+        return bins.every((rel) => fs.existsSync(path.join(packageRoot, rel)));
+    }
+    catch {
+        return false;
+    }
+}
 export async function installPackageWithBun(spec, signal) {
     const { execFile } = await import('child_process');
     const { promisify } = await import('util');

package/package.json

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