@phnx-labs/agents-cli 1.20.46 → 1.20.48

package/dist/lib/shims.js

@@ -1610,6 +1610,85 @@ export function isShimCurrent(agent) {
     const version = readShimSchemaVersion(agent);
     return version === SHIM_SCHEMA_VERSION;
 }
+/** Extract the baked `AGENTS_BIN='...'` value from a shim file, or null. */
+function readAgentsBinFromShim(shimPath) {
+    try {
+        const header = fs.readFileSync(shimPath, 'utf8').split('\n', 12).join('\n');
+        const m = header.match(/^AGENTS_BIN=(?:'([^']*)'|"([^"]*)"|(\S+))/m);
+        return m ? (m[1] ?? m[2] ?? m[3] ?? null) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * True when the agent shim's baked `AGENTS_BIN` is fine to keep: it either already
+ * points at the install we'd generate now, OR points at some OTHER install that
+ * still exists on disk (leave it — regenerating could ping-pong two live installs
+ * sharing the shims dir). Returns FALSE only when the shim points at a DIFFERENT,
+ * now-removed install — the exact drift a deleted dev build (`~/.local/agents-cli-dev`),
+ * an old npm-global (`/opt/homebrew`), or a rotated version dir leaves behind. A shim
+ * can pass the schema check (`isShimCurrent`) yet still carry that stale path.
+ */
+export function shimPointsAtLiveInstall(agent) {
+    if (!shimExists(agent))
+        return true; // missing shim is handled by ensureShimCurrent
+    const baked = readAgentsBinFromShim(onDiskShimPath(agent));
+    if (!baked)
+        return true;
+    if (baked === getAgentsBinForGeneratedShim())
+        return true; // already the current install
+    return fs.existsSync(baked); // a different install — keep only while it still exists
+}
+/** Shim files in the shims dir, excluding the hooks/ subdir and @-versioned aliases. */
+export function listShimFileNames() {
+    try {
+        return fs
+            .readdirSync(getShimsDir(), { withFileTypes: true })
+            .filter((e) => e.isFile() && !e.name.includes('@'))
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * 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
+ * are legacy `exec "$AGENTS_BIN" <cmd>` command shims (browser/secrets/sessions/…)
+ * left behind by a removed install — the current source never generates them, and
+ * they either die with `exit 127` or shadow the real package bin on PATH. Only
+ * removed when the baked target is gone, so a working shim is never touched.
+ * Returns true if removed.
+ */
+export function pruneOrphanedCommandShim(fileName) {
+    // Never touch a shim that corresponds to a real agent — agents-cli manages those.
+    const isAgentCommand = Object.values(AGENTS).some((a) => a.cliCommand === fileName);
+    if (isAgentCommand)
+        return false;
+    const shimPath = path.join(getShimsDir(), fileName);
+    let content;
+    try {
+        content = fs.readFileSync(shimPath, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    if (content.includes('# Alias shim:'))
+        return false; // a user `agents alias` — leave it
+    const bin = readAgentsBinFromShim(shimPath);
+    if (!bin)
+        return false; // not an AGENTS_BIN-baked shim
+    if (fs.existsSync(bin))
+        return false; // its install is still alive — leave it
+    try {
+        fs.rmSync(shimPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Regenerate the shim if it's missing or outdated. Returns a status describing
  * what happened — callers can surface a one-line notice to the user ("Updated

package/dist/lib/versions.d.ts

@@ -320,6 +320,21 @@ export declare function isMissingBinarySignature(output: string): boolean;
  * missing-binary signature (see isMissingBinarySignature) fails the check; a
  * plain nonzero exit or a timeout is treated as healthy so we never false-fail.
  */
+/**
+ * Compose the spawn spec for a `<binary> --version` launch probe. On Windows the
+ * `.cmd` wrapper runs through cmd.exe, so the path is fully quoted into ONE
+ * command line and the args array is emptied (composeWin32CommandLine) — the
+ * DEP0190-safe pattern the real launch uses. Critically this keeps a spaced
+ * Windows profile path (`C:\Users\John Doe\…\claude.cmd`) intact; passing the raw
+ * path to a shell would split it at the space and false-fail a HEALTHY install.
+ * On POSIX no shell is involved and the binary is exec'd directly. Pure/exported
+ * so the quoting is unit-testable without spawning.
+ */
+export declare function probeSpawnSpec(binary: string, isWin: boolean): {
+    command: string;
+    args: string[];
+    shell: boolean;
+};
 export declare function verifyInstalledBinaryLaunches(agent: AgentId, version: string): Promise<{
     ok: boolean;
     detail?: string;
@@ -344,6 +359,7 @@ export declare function verifyInstalledBinaryLaunches(agent: AgentId, version: s
  * droid) have no such tarball and are returned unchanged.
  */
 export declare function ensureAgentRunnable(agent: AgentId, version: string, log?: (message: string) => void): Promise<string | null>;
+export declare function healBrokenDefaultLaunches(log?: (m: string) => void): Promise<string[]>;
 /** Outcome of syncing resources to a version home, keyed by resource type. */
 export interface SyncResult {
     commands: boolean;

package/dist/lib/versions.js

@@ -33,7 +33,7 @@ import { discoverPermissionGroups, getActivePermissionPresetName, readPermission
 import { parseMcpServerConfig } from './mcp.js';
 import { createVersionedAlias, removeVersionedAlias, getConfigSymlinkVersion, ensureClaudeInsideSymlink } from './shims.js';
 import { importInstallScriptBinary } from './import.js';
-import { IS_WINDOWS } from './platform/index.js';
+import { IS_WINDOWS, composeWin32CommandLine } from './platform/index.js';
 import { pruneVersionHomeHookEntriesFromSettings } from './hooks.js';
 import { supports, explainSkip } from './capabilities.js';
 import { discoverPlugins } from './plugins.js';
@@ -1621,22 +1621,48 @@ export function isMissingBinarySignature(output) {
  * missing-binary signature (see isMissingBinarySignature) fails the check; a
  * plain nonzero exit or a timeout is treated as healthy so we never false-fail.
  */
+/**
+ * Compose the spawn spec for a `<binary> --version` launch probe. On Windows the
+ * `.cmd` wrapper runs through cmd.exe, so the path is fully quoted into ONE
+ * command line and the args array is emptied (composeWin32CommandLine) — the
+ * DEP0190-safe pattern the real launch uses. Critically this keeps a spaced
+ * Windows profile path (`C:\Users\John Doe\…\claude.cmd`) intact; passing the raw
+ * path to a shell would split it at the space and false-fail a HEALTHY install.
+ * On POSIX no shell is involved and the binary is exec'd directly. Pure/exported
+ * so the quoting is unit-testable without spawning.
+ */
+export function probeSpawnSpec(binary, isWin) {
+    if (isWin)
+        return { command: composeWin32CommandLine(binary, ['--version']), args: [], shell: true };
+    return { command: binary, args: ['--version'], shell: false };
+}
 export async function verifyInstalledBinaryLaunches(agent, version) {
-    // Windows: `getBinaryPath` returns the extensionless `.bin/<cli>` (a shell
-    // wrapper), NOT the `.cmd`/`.exe` that actually launches there — `execFile`ing
-    // it would ENOENT on a perfectly healthy install, and the integrity gate would
-    // then WIPE it. The gutted-native-binary failure this guards against is a POSIX
-    // concern in practice; treat win32 as healthy rather than risk destroying a
-    // good install. (isVersionInstalled already validates presence on Windows.)
-    if (process.platform === 'win32')
-        return { ok: true };
-    const binary = getBinaryPath(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.
+    const isWin = process.platform === 'win32';
+    const binary = isWin ? getBinaryPath(agent, version) + '.cmd' : getBinaryPath(agent, version);
     if (!fs.existsSync(binary)) {
-        return { ok: false, detail: `binary not found at ${binary}` };
+        // Windows: a missing `.cmd` means a non-npm/global agent (droid.exe) we can't
+        // safely probe — treat as healthy (isVersionInstalled validates presence).
+        // POSIX: a missing launch binary is a genuine gutted install.
+        return isWin ? { ok: true } : { ok: false, detail: `binary not found at ${binary}` };
     }
     try {
-        await execFileAsync(binary, ['--version'], {
+        // On Windows the `.cmd` runs via cmd.exe (shell). Pass a single FULLY-QUOTED
+        // command line + EMPTY args (composeWin32CommandLine) — the same DEP0190-safe
+        // pattern the real launch uses (exec.ts) — so a space in the Windows profile
+        // path (`C:\Users\John Doe\…`) can't split the path and false-fail a healthy
+        // install into a destructive reinstall.
+        const spec = probeSpawnSpec(binary, isWin);
+        await execFileAsync(spec.command, spec.args, {
             timeout: 15000,
+            shell: spec.shell,
             env: { ...process.env, HOME: getVersionHomePath(agent, version) },
         });
         return { ok: true };
@@ -1703,6 +1729,51 @@ export async function ensureAgentRunnable(agent, version, log) {
     }
     return null;
 }
+/**
+ * Proactive launch-health pass for the daemon. Probe the DEFAULT version of
+ * every npm-package agent and repair any that won't launch (via
+ * ensureAgentRunnable), so a gutted install is healed BEFORE the user's next
+ * `agents run` hits a raw ENOENT — the run-time heal (ensureAgentRunnable) only
+ * fires once a run is already starting; this catches it in the background.
+ *
+ * Returns a label (`agent@broken→healed`) for each version actually repaired, so
+ * the daemon can log/notify. A version that already launches costs one cheap
+ * `--version` probe and is left untouched.
+ */
+const failedRepairAt = new Map();
+const REPAIR_COOLDOWN_MS = 24 * 60 * 60_000;
+export async function healBrokenDefaultLaunches(log) {
+    const repaired = [];
+    for (const agent of Object.keys(AGENTS)) {
+        if (!AGENTS[agent].npmPackage)
+            continue; // native/global agents have no gutted-tarball failure mode
+        const version = getGlobalDefault(agent);
+        if (!version)
+            continue;
+        if ((await verifyInstalledBinaryLaunches(agent, version)).ok)
+            continue;
+        // Backoff: a version whose repair just failed (offline, npm 404, an arch the
+        // registry can't serve) must NOT re-trigger a full clean-reinstall +
+        // install-latest on every 6h pass. Skip it for a day; a daemon restart clears
+        // the memo, giving a fresh attempt.
+        const key = `${agent}@${version}`;
+        const last = failedRepairAt.get(key);
+        if (last !== undefined && Date.now() - last < REPAIR_COOLDOWN_MS) {
+            log?.(`${AGENTS[agent].name}@${version} still won't launch — repair attempted recently, skipping until cooldown elapses.`);
+            continue;
+        }
+        log?.(`${AGENTS[agent].name}@${version} won't launch — repairing…`);
+        const healed = await ensureAgentRunnable(agent, version, log);
+        if (healed) {
+            failedRepairAt.delete(key);
+            repaired.push(`${agent}@${version}${healed === version ? '' : `→${healed}`}`);
+        }
+        else {
+            failedRepairAt.set(key, Date.now());
+        }
+    }
+    return repaired;
+}
 async function getCliVersionFromPath(agent) {
     const agentConfig = AGENTS[agent];
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.46",
+  "version": "1.20.48",
   "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",
@@ -44,10 +44,10 @@
     "url": "https://github.com/phnx-labs/agents-cli/issues"
   },
   "scripts": {
-    "build": "tsc && rm -rf 'dist/lib/secrets/AgentsKeychain.app' 'dist/lib/secrets/Agents CLI.app' 'dist/lib/menubar/MenubarHelper.app' && ([ \"$(uname)\" = \"Darwin\" ] && cp -R 'bin/Agents CLI.app' 'dist/lib/secrets/Agents CLI.app' || true) && ([ \"$(uname)\" = \"Darwin\" ] && [ -d 'bin/MenubarHelper.app' ] && mkdir -p 'dist/lib/menubar' && cp -R 'bin/MenubarHelper.app' 'dist/lib/menubar/MenubarHelper.app' || true)",
+    "build": "tsc && rm -rf 'dist/lib/secrets/AgentsKeychain.app' 'dist/lib/secrets/Agents CLI.app' 'dist/lib/menubar/MenubarHelper.app' && ([ -d 'bin/Agents CLI.app' ] && cp -R 'bin/Agents CLI.app' 'dist/lib/secrets/Agents CLI.app' || true) && ([ -d 'bin/MenubarHelper.app' ] && mkdir -p 'dist/lib/menubar' && cp -R 'bin/MenubarHelper.app' 'dist/lib/menubar/MenubarHelper.app' || true)",
     "build:bin": "scripts/build-bin.sh",
     "prepare": "npm run build",
-    "prepack": "scripts/verify-keychain-helper.sh && scripts/verify-menubar-helper.sh",
+    "prepack": "cp ../../README.md README.md && scripts/verify-keychain-helper.sh && scripts/verify-menubar-helper.sh",
     "postinstall": "node scripts/postinstall.js",
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",