@phnx-labs/agents-cli 1.20.3 → 1.20.4

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.20.4
+
+**Plugin marketplace sync (skip outside-pointing symlinks)**
+
+- `copyPluginToMarketplace` used `fs.cpSync(plugin.root, dest, { recursive: true, dereference: false })`, which faithfully preserved every symlink — including the ones plugin authors put at the top of their plugin source for prompt-side references (the rush plugin's `app -> ../../../rush/app`, `web -> rush/web`, `widgets -> rush/widgets`). Those targets resolve to the rush monorepo (~8.7 GB of `app/` including node_modules + .next builds, 782 MB of `web/`, plus 463 MB brand-assets). Every claude version got a full set of those symlinks in `~/.claude/plugins/marketplaces/agents-cli/plugins/rush/`. When the consumer (Claude Code, OpenClaw) discovers plugins, it walks the marketplace tree and follows those symlinks — producing multi-minute startup hangs.
+- The copy now walks the source tree and drops symlinks whose `realpath` escapes the plugin root, leaving internal symlinks intact (cpSync rewrites internal targets to absolute paths into the source tree, which the consumer still resolves correctly). One informational line per plugin lists the skipped names so plugin authors notice.
+- Existing per-version marketplace directories still hold the bloat from prior syncs; clean up with `rm` against `~/.claude/plugins/marketplaces/agents-cli/plugins/*/{app,web,widgets,*-symlinks-that-escaped}` then re-run `agents pull` or any plugin sync to re-copy with the filter.
+
 ## 1.20.3
 
 **`agents run` startup latency (stale-while-revalidate the usage probe + memoize agents.yaml)**

package/dist/commands/import.js

@@ -23,12 +23,13 @@
 import chalk from 'chalk';
 import ora from 'ora';
 import * as fs from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 import { confirm } from '@inquirer/prompts';
 import { ALL_AGENT_IDS } from '../lib/agents.js';
 import { AGENTS, getCliPath, getCliVersion, agentLabel } from '../lib/agents.js';
 import { getVersionDir } from '../lib/versions.js';
-import { finalizeImport, importAgentBinary, importAgentConfig, isValidImportVersion, resolvePackageDirFromBinary, } from '../lib/import.js';
+import { finalizeImport, importAgentBinary, importAgentConfig, importInstallScriptBinary, isValidImportVersion, resolvePackageDirFromBinary, } from '../lib/import.js';
 import { isPromptCancelled, isInteractiveTerminal } from './utils.js';
 function isValidAgentId(value) {
     return ALL_AGENT_IDS.includes(value);
@@ -41,54 +42,94 @@ async function runImport(agentArg, opts) {
     }
     const agentId = agentArg;
     const agent = AGENTS[agentId];
-    // Reject agents that don't ship via npm before we spin up PATH lookups and
-    // prompts. cursor/kiro/goose/roo all have npmPackage='' and use custom
-    // install scripts — the symlink-farm import doesn't apply to them.
-    if (!agent.npmPackage) {
-        console.error(chalk.red(`${agentLabel(agentId)} doesn't install via npm — \`agents import\` only handles npm-style packages.`));
-        console.error(chalk.gray(`Use \`agents add ${agentId}\` to install via its native script.`));
-        process.exit(1);
-    }
+    // installScript-based agents (Grok, Antigravity, Cursor, Kiro, Goose, Roo)
+    // don't have an npm package; their binary lives wherever the curl/brew
+    // installer dropped it. We adopt by symlinking that PATH binary directly
+    // into the version's `node_modules/.bin/`. No package.json walk.
+    const isInstallScriptAgent = !agent.npmPackage;
     let globalPath = null;
+    let installScriptBinary = null;
     if (opts.fromPath) {
         globalPath = path.resolve(opts.fromPath);
         if (!fs.existsSync(globalPath)) {
             console.error(chalk.red(`Path does not exist: ${globalPath}`));
             process.exit(1);
         }
+        if (isInstallScriptAgent) {
+            // With --from-path on an installScript agent, the path is the binary
+            // itself (or a directory containing it). Accept either.
+            if (fs.statSync(globalPath).isDirectory()) {
+                const candidate = path.join(globalPath, agent.cliCommand);
+                if (!fs.existsSync(candidate)) {
+                    console.error(chalk.red(`No "${agent.cliCommand}" in ${globalPath}`));
+                    process.exit(1);
+                }
+                installScriptBinary = candidate;
+            }
+            else {
+                installScriptBinary = globalPath;
+            }
+        }
     }
     else {
         const binary = await getCliPath(agentId);
         if (!binary) {
-            // Use || (not ??) so empty-string npmPackage falls back to cliCommand.
-            // Defensive: agents with empty npmPackage are rejected above, but keep
-            // the operator correct in case that early check is ever relaxed.
-            const installName = agent.npmPackage || agent.cliCommand;
+            const installHint = isInstallScriptAgent
+                ? `Run \`agents add ${agentId}\` to install via the official script, or pass --from-path.`
+                : `Install it first (e.g. \`npm i -g ${agent.npmPackage || agent.cliCommand}\`) or pass --from-path.`;
             console.error(chalk.red(`No "${agent.cliCommand}" found on PATH.`));
-            console.error(chalk.gray(`Install it first (e.g. \`npm i -g ${installName}\`) or pass --from-path.`));
+            console.error(chalk.gray(installHint));
             process.exit(1);
         }
-        globalPath = resolvePackageDirFromBinary(binary);
-        if (!globalPath) {
-            console.error(chalk.red(`Could not resolve npm package for binary: ${binary}`));
-            console.error(chalk.gray('Pass --from-path <dir> with the package directory explicitly.'));
-            process.exit(1);
+        if (isInstallScriptAgent) {
+            installScriptBinary = binary;
+        }
+        else {
+            globalPath = resolvePackageDirFromBinary(binary);
+            if (!globalPath) {
+                console.error(chalk.red(`Could not resolve npm package for binary: ${binary}`));
+                console.error(chalk.gray('Pass --from-path <dir> with the package directory explicitly.'));
+                process.exit(1);
+            }
+        }
+    }
+    // For Grok, the binary on PATH is typically `~/.grok/bin/grok` (a moving
+    // pointer to the latest install). Prefer the exact versioned file in
+    // `~/.grok/downloads/` so the v<x.y.z> alias is pinned to that file and
+    // doesn't drift when the user upgrades externally.
+    if (isInstallScriptAgent && agentId === 'grok' && !opts.fromPath) {
+        const detected = await getCliVersion(agentId);
+        if (detected) {
+            const downloads = path.join(os.homedir(), '.grok', 'downloads');
+            try {
+                const entries = fs.readdirSync(downloads);
+                const exact = entries.find((e) => e.startsWith('grok-') && e.includes(detected));
+                if (exact) {
+                    installScriptBinary = path.join(downloads, exact);
+                }
+            }
+            catch {
+                /* fall back to PATH binary already set above */
+            }
         }
     }
     let version = opts.version;
     if (!version) {
-        try {
-            const pkg = JSON.parse(fs.readFileSync(path.join(globalPath, 'package.json'), 'utf8'));
-            version = typeof pkg.version === 'string' ? pkg.version : undefined;
-        }
-        catch {
-            /* fall through */
+        if (!isInstallScriptAgent && globalPath) {
+            try {
+                const pkg = JSON.parse(fs.readFileSync(path.join(globalPath, 'package.json'), 'utf8'));
+                version = typeof pkg.version === 'string' ? pkg.version : undefined;
+            }
+            catch {
+                /* fall through */
+            }
         }
         // Only fall back to running the PATH binary's --version when we're
-        // auto-detecting. With --from-path, the PATH binary may belong to a
-        // different install entirely; reporting its version here would silently
-        // mis-attribute the imported version.
-        if (!version && !opts.fromPath) {
+        // auto-detecting. With --from-path on an npm agent, the PATH binary may
+        // belong to a different install entirely; reporting its version here
+        // would silently mis-attribute the imported version. installScript agents
+        // always use `<bin> --version` since they have no package.json to read.
+        if (!version && (isInstallScriptAgent || !opts.fromPath)) {
             const detected = await getCliVersion(agentId);
             version = detected ?? undefined;
         }
@@ -104,8 +145,9 @@ async function runImport(agentArg, opts) {
         process.exit(1);
     }
     const versionDir = getVersionDir(agentId, version);
+    const fromLabel = isInstallScriptAgent ? installScriptBinary : globalPath;
     console.log(chalk.bold(`\nImport ${agentLabel(agentId)} v${version}`));
-    console.log(`  from: ${chalk.gray(globalPath)}`);
+    console.log(`  from: ${chalk.gray(fromLabel)}`);
     console.log(`  into: ${chalk.gray(versionDir)}`);
     const configDirExists = fs.existsSync(agent.configDir);
     let configAlreadyManaged = false;
@@ -146,7 +188,8 @@ async function runImport(agentArg, opts) {
         const cfgSpinner = ora(`Importing config dir for ${agentLabel(agentId)} v${version}...`).start();
         const cfgResult = await importAgentConfig(agentId, version);
         if (cfgResult.success) {
-            cfgSpinner.succeed(`Config imported (${agent.configDir} -> ${versionDir}/home/.${agentId})`);
+            const relConfig = path.relative(os.homedir(), agent.configDir);
+            cfgSpinner.succeed(`Config imported (${agent.configDir} -> ${versionDir}/home/${relConfig})`);
         }
         else if (cfgResult.skipped) {
             cfgSpinner.warn(`Config: ${cfgResult.error}`);
@@ -157,9 +200,11 @@ async function runImport(agentArg, opts) {
         }
     }
     const binSpinner = ora(`Registering ${agentLabel(agentId)} v${version} binary...`).start();
-    const binResult = importAgentBinary({ agentId, npmPackage: agent.npmPackage, cliCommand: agent.cliCommand }, version, globalPath, versionDir);
+    const binResult = isInstallScriptAgent
+        ? importInstallScriptBinary({ agentId, npmPackage: agent.npmPackage, cliCommand: agent.cliCommand }, version, installScriptBinary, versionDir)
+        : importAgentBinary({ agentId, npmPackage: agent.npmPackage, cliCommand: agent.cliCommand }, version, globalPath, versionDir);
     if (binResult.success) {
-        binSpinner.succeed(`Binary registered (${agent.cliCommand} -> ${globalPath})`);
+        binSpinner.succeed(`Binary registered (${agent.cliCommand} -> ${binResult.resolvedFromPath})`);
     }
     else if (binResult.skipped) {
         binSpinner.warn(`Binary: ${binResult.error}`);
@@ -198,11 +243,19 @@ Examples:
   $ agents import openclaw --version 2026.3.8       Pin a version label
   $ agents import openclaw --from-path /opt/homebrew/lib/node_modules/openclaw
 
+  # installScript-based agents (curl/brew installers, no npm package):
+  $ agents import grok                              Adopt ~/.grok/downloads/grok-<ver>
+  $ agents import antigravity                       Adopt ~/.local/bin/agy
+  $ agents import cursor                            Adopt ~/.local/bin/cursor-agent
+  $ agents import antigravity --from-path ~/.local/bin/agy
+
 When to use:
-  When an agent CLI is already installed globally via npm or homebrew and you
-  want to bring it under agents-cli management without reinstalling. Creates a
-  symlink farm pointing at the existing install — nothing is copied or moved
-  (except the agent's config dir, which is moved into the version's home).
+  When an agent CLI is already installed globally and you want to bring it
+  under agents-cli management without reinstalling. Creates a symlink farm
+  pointing at the existing install — nothing is copied or moved (except the
+  agent's config dir, which is moved into the version's home). Works for both
+  npm-style packages (claude, codex, gemini, opencode, openclaw) and
+  installScript-based agents (grok, antigravity, cursor, kiro, goose, roo).
 `)
         .action(runImport);
 }

package/dist/commands/view.js

@@ -455,6 +455,11 @@ async function showInstalledVersions(filterAgentId) {
             if (agent.npmPackage && cliState?.version) {
                 console.log(chalk.gray(`    Manage: agents add ${agentId}@${cliState.version} -y`));
             }
+            else if (!agent.npmPackage && cliState?.installed) {
+                // installScript-based agent already on PATH — direct users to adopt the
+                // existing install with `agents import` instead of re-running curl.
+                console.log(chalk.gray(`    Adopt:  agents import ${agentId}`));
+            }
             console.log();
         }
     }

package/dist/lib/agents.js

@@ -55,13 +55,25 @@ function saveCliVersionCache() {
         /* best-effort cache persist */
     }
 }
-/** Synchronous PATH search -- no subprocess. Returns first matching binary path. */
+/**
+ * Synchronous PATH search -- no subprocess. Returns first matching binary path.
+ *
+ * Skips our own shims dir (`~/.agents/.cache/shims/`) — those shims are
+ * dispatch helpers, not real installs. Counting them as installed produced a
+ * false positive where agents with NO real binary on the host (e.g. a
+ * never-installed Cursor whose only PATH entry was our `cursor-agent` shim
+ * dispatcher) showed up under `agents view`'s "Not Managed by Agents CLI"
+ * section, even though the user had nothing to import.
+ */
 function findInPath(command) {
     const pathEnv = process.env.PATH || '';
     const pathExt = process.platform === 'win32' ? (process.env.PATHEXT || '').split(';') : [''];
+    const shimsDir = getShimsDir();
     for (const dir of pathEnv.split(path.delimiter)) {
         if (!dir)
             continue;
+        if (path.resolve(dir) === path.resolve(shimsDir))
+            continue;
         for (const ext of pathExt) {
             const full = path.join(dir, command + ext);
             try {
@@ -507,8 +519,16 @@ async function getCachedVersionForBinary(agentId, binaryPath) {
         /* version command failed */
         version = null;
     }
-    cache[agentId] = { binaryPath, mtime, version };
-    saveCliVersionCache();
+    // Skip persisting null results — the most common cause is a transient
+    // `--version` failure (slow startup, stdout race, etc.). A sticky-null
+    // entry kept users in a broken state where every subsequent
+    // `getCachedVersionForBinary` short-circuited to null forever, even
+    // after the binary started working. Re-probing on the next call costs
+    // one execFile; persisting null costs the whole feature.
+    if (version !== null) {
+        cache[agentId] = { binaryPath, mtime, version };
+        saveCliVersionCache();
+    }
     return version;
 }
 /**

package/dist/lib/import.d.ts

@@ -81,6 +81,27 @@ export interface AgentBinarySpec {
  *     node_modules/.bin/{cliCommand} -> {binaryEntry}
  */
 export declare function importAgentBinary(spec: AgentBinarySpec, version: string, globalPath: string, versionDir: string): ImportBinaryResult;
+/**
+ * Register an existing installScript-based binary (Grok, Antigravity, Cursor,
+ * etc. — anything with `npmPackage: ''` and a curl/brew installer) under the
+ * managed version path. Unlike `importAgentBinary` this skips the npm
+ * package.json walk and just symlinks the resolved PATH binary directly into
+ * `{versionDir}/node_modules/.bin/{cliCommand}`. The symlink is what makes
+ * `listInstalledVersions` consider the version Managed.
+ *
+ * Layout produced:
+ *
+ *   {versionDir}/
+ *     package.json                              # marker (private, imported, from)
+ *     home/                                     # empty isolated $HOME
+ *     node_modules/.bin/{cliCommand} -> {binaryPath}
+ *
+ * For agents whose binary lookup is special-cased elsewhere (e.g. Grok's
+ * `~/.grok/downloads/`), the symlink is still created — `getBinaryPath` won't
+ * read it for those agents, but it documents provenance and lets a future
+ * refactor consolidate the binary-resolution registry.
+ */
+export declare function importInstallScriptBinary(spec: AgentBinarySpec, version: string, binaryPath: string, versionDir: string): ImportBinaryResult;
 /**
  * Resolve the on-disk npm package directory for an agent's CLI binary by
  * walking up from the binary, following any symlinks. Returns null if the

package/dist/lib/import.js

@@ -17,6 +17,7 @@
  * true.
  */
 import * as fs from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 import { AGENTS } from './agents.js';
 import { getVersionsDir } from './state.js';
@@ -42,12 +43,17 @@ export async function importAgentConfig(agentId, version) {
     const configDir = agent.configDir;
     const versionsDir = getVersionsDir();
     const versionHome = path.join(versionsDir, agentId, version, 'home');
-    const versionConfigDir = path.join(versionHome, `.${agentId}`);
+    // Match the shim's derivation in generateShimScript: the per-version config
+    // path mirrors the original configDir's path relative to $HOME. Hardcoding
+    // `.${agentId}` broke for nested configDirs like Antigravity
+    // (`~/.gemini/antigravity-cli`) — the destination would be `.antigravity`,
+    // mismatching the shim's expectation of `.gemini/antigravity-cli`.
+    const versionConfigDir = path.join(versionHome, path.relative(os.homedir(), configDir));
     if (fs.existsSync(versionConfigDir)) {
         return { success: false, skipped: true, error: `${version} already installed` };
     }
     try {
-        fs.mkdirSync(versionHome, { recursive: true });
+        fs.mkdirSync(path.dirname(versionConfigDir), { recursive: true });
         fs.renameSync(configDir, versionConfigDir);
         fs.symlinkSync(versionConfigDir, configDir);
         setGlobalDefault(agentId, version);
@@ -155,6 +161,53 @@ export function importAgentBinary(spec, version, globalPath, versionDir) {
         return { success: false, error: err.message };
     }
 }
+/**
+ * Register an existing installScript-based binary (Grok, Antigravity, Cursor,
+ * etc. — anything with `npmPackage: ''` and a curl/brew installer) under the
+ * managed version path. Unlike `importAgentBinary` this skips the npm
+ * package.json walk and just symlinks the resolved PATH binary directly into
+ * `{versionDir}/node_modules/.bin/{cliCommand}`. The symlink is what makes
+ * `listInstalledVersions` consider the version Managed.
+ *
+ * Layout produced:
+ *
+ *   {versionDir}/
+ *     package.json                              # marker (private, imported, from)
+ *     home/                                     # empty isolated $HOME
+ *     node_modules/.bin/{cliCommand} -> {binaryPath}
+ *
+ * For agents whose binary lookup is special-cased elsewhere (e.g. Grok's
+ * `~/.grok/downloads/`), the symlink is still created — `getBinaryPath` won't
+ * read it for those agents, but it documents provenance and lets a future
+ * refactor consolidate the binary-resolution registry.
+ */
+export function importInstallScriptBinary(spec, version, binaryPath, versionDir) {
+    const binaryLink = path.join(versionDir, 'node_modules', '.bin', spec.cliCommand);
+    let alreadyExists = false;
+    try {
+        fs.lstatSync(binaryLink);
+        alreadyExists = true;
+    }
+    catch {
+        /* not present */
+    }
+    if (alreadyExists) {
+        return { success: false, skipped: true, error: `${version} already installed`, resolvedFromPath: binaryPath };
+    }
+    if (!fs.existsSync(binaryPath)) {
+        return { success: false, error: `Binary does not exist: ${binaryPath}` };
+    }
+    try {
+        fs.mkdirSync(path.join(versionDir, 'home'), { recursive: true });
+        fs.mkdirSync(path.join(versionDir, 'node_modules', '.bin'), { recursive: true });
+        fs.writeFileSync(path.join(versionDir, 'package.json'), JSON.stringify({ name: `agents-${spec.agentId}-${version}`, version: '1.0.0', private: true, imported: true, from: binaryPath, installScriptBased: true }, null, 2));
+        fs.symlinkSync(binaryPath, binaryLink);
+        return { success: true, resolvedFromPath: binaryPath };
+    }
+    catch (err) {
+        return { success: false, error: err.message };
+    }
+}
 /**
  * Resolve the on-disk npm package directory for an agent's CLI binary by
  * walking up from the binary, following any symlinks. Returns null if the

package/dist/lib/plugin-marketplace.d.ts

@@ -45,6 +45,16 @@ export declare function knownMarketplacesPath(agent: AgentId, versionHome: strin
 /**
  * Copy plugin source into marketplace install dir.
  * Source of truth remains ~/.agents/plugins/<name>/ — this is a per-version snapshot.
+ *
+ * Symlinks pointing OUTSIDE the plugin source root are dropped. They show up
+ * when plugin authors (legitimately) link prompt-side references to sibling
+ * codebases — e.g. the rush plugin's `app -> ../../../rush/app` for @app/...
+ * autocomplete in user prompts. Faithfully copying those symlinks pollutes
+ * the marketplace with gigabytes of node_modules / .next / brand-asset video
+ * that the consumer (Claude Code, OpenClaw) then walks during plugin
+ * discovery — which is the documented cause of multi-minute startup hangs.
+ *
+ * Internal symlinks (target stays inside the plugin root) are preserved.
  */
 export declare function copyPluginToMarketplace(plugin: DiscoveredPlugin, agent: AgentId, versionHome: string): string;
 /**

package/dist/lib/plugin-marketplace.js

@@ -40,6 +40,16 @@ function settingsPath(agent, versionHome) {
 /**
  * Copy plugin source into marketplace install dir.
  * Source of truth remains ~/.agents/plugins/<name>/ — this is a per-version snapshot.
+ *
+ * Symlinks pointing OUTSIDE the plugin source root are dropped. They show up
+ * when plugin authors (legitimately) link prompt-side references to sibling
+ * codebases — e.g. the rush plugin's `app -> ../../../rush/app` for @app/...
+ * autocomplete in user prompts. Faithfully copying those symlinks pollutes
+ * the marketplace with gigabytes of node_modules / .next / brand-asset video
+ * that the consumer (Claude Code, OpenClaw) then walks during plugin
+ * discovery — which is the documented cause of multi-minute startup hangs.
+ *
+ * Internal symlinks (target stays inside the plugin root) are preserved.
  */
 export function copyPluginToMarketplace(plugin, agent, versionHome) {
     const dest = pluginInstallDir(plugin, agent, versionHome);
@@ -47,7 +57,43 @@ export function copyPluginToMarketplace(plugin, agent, versionHome) {
     if (fs.existsSync(dest)) {
         fs.rmSync(dest, { recursive: true, force: true });
     }
-    fs.cpSync(plugin.root, dest, { recursive: true, dereference: false });
+    const sourceRealRoot = (() => {
+        try {
+            return fs.realpathSync(plugin.root);
+        }
+        catch {
+            return plugin.root;
+        }
+    })();
+    const skipped = [];
+    fs.cpSync(plugin.root, dest, {
+        recursive: true,
+        dereference: false,
+        filter: (src) => {
+            try {
+                const stat = fs.lstatSync(src);
+                if (!stat.isSymbolicLink())
+                    return true;
+                const target = fs.realpathSync(src);
+                if (target === sourceRealRoot || target.startsWith(sourceRealRoot + path.sep)) {
+                    return true;
+                }
+                skipped.push(path.relative(plugin.root, src) || path.basename(src));
+                return false;
+            }
+            catch {
+                // Dangling symlink or stat failure — drop it; it can't be useful in
+                // the marketplace and would error the consumer's walk anyway.
+                skipped.push(path.relative(plugin.root, src) || path.basename(src));
+                return false;
+            }
+        },
+    });
+    if (skipped.length > 0) {
+        process.stderr.write(`agents-cli: plugin '${plugin.name}' has ${skipped.length} symlink(s) ` +
+            `pointing outside its source root; not copied to marketplace ` +
+            `(would bloat consumer startup): ${skipped.join(', ')}\n`);
+    }
     return dest;
 }
 /**

package/dist/lib/pty-server.js

@@ -192,7 +192,33 @@ export async function runPtyServer() {
     }
     const sessions = new Map();
     const socketPath = getSocketPath();
-    // Remove stale socket
+    const pidPath = getPtyPidPath();
+    // Race resolution must happen BEFORE touching the socket file. Two clients
+    // racing ensureServer() in pty-client.ts can both observe
+    // isPtyServerRunning()=false and spawn parallel servers; without the
+    // O_EXCL claim below, the second spawn would unlink the first's socket
+    // inode and overwrite its PID file, orphaning the first server with its
+    // kernel socket binding intact but unreachable via the filesystem.
+    if (isPtyServerRunning()) {
+        log('INFO', 'PTY server already running; duplicate spawn exits cleanly');
+        process.exit(0);
+    }
+    try {
+        fs.writeFileSync(pidPath, String(process.pid), { flag: 'wx', encoding: 'utf-8' });
+    }
+    catch (err) {
+        if (err && err.code === 'EEXIST') {
+            log('INFO', 'PID slot claimed by a concurrent server; exiting cleanly');
+            process.exit(0);
+        }
+        throw err;
+    }
+    // We own the PID slot; ensure it's released on any exit path, not just SIGTERM/SIGINT.
+    process.on('exit', () => { try {
+        fs.unlinkSync(pidPath);
+    }
+    catch { } });
+    // Remove stale socket from a prior crashed server. Safe now that we hold the PID slot.
     if (fs.existsSync(socketPath)) {
         try {
             fs.unlinkSync(socketPath);
@@ -510,8 +536,6 @@ export async function runPtyServer() {
     // assumption, not a nice-to-have. If we can't lock it down, refuse to
     // start so the caller learns immediately.
     fs.chmodSync(socketPath, 0o600);
-    // Write PID
-    fs.writeFileSync(getPtyPidPath(), String(process.pid), 'utf-8');
     log('INFO', `PTY server started (PID: ${process.pid}, socket: ${socketPath})`);
     // Shutdown handler
     function shutdown() {

package/dist/lib/versions.js

@@ -31,6 +31,7 @@ import { applyPermissionsToVersion as applyPermsToVersion, PERMISSIONS_CAPABLE_A
 import { installMcpServers, parseMcpServerConfig } from './mcp.js';
 import { markdownToToml } from './convert.js';
 import { createVersionedAlias, removeVersionedAlias, getConfigSymlinkVersion, ensureClaudeInsideSymlink } from './shims.js';
+import { importInstallScriptBinary } from './import.js';
 import { listInstalledSubagents, transformSubagentForClaude, syncSubagentToOpenclaw, SUBAGENT_CAPABLE_AGENTS } from './subagents.js';
 import { WORKFLOW_CAPABLE_AGENTS, listInstalledWorkflows, syncWorkflowToVersion } from './workflows.js';
 import { registerHooksToSettings } from './hooks.js';
@@ -1176,6 +1177,26 @@ export async function installVersion(agent, version, onProgress) {
         const versionDir = getVersionDir(agent, installedVersion);
         fs.mkdirSync(versionDir, { recursive: true });
         fs.mkdirSync(path.join(versionDir, 'home'), { recursive: true });
+        // Symlink the installed binary into the version's node_modules/.bin so
+        // listInstalledVersions (which checks getBinaryPath) sees this version as
+        // installed. Without this, `agents add antigravity@latest` succeeds
+        // but `agents view` shows the agent under "Not Managed" because
+        // listInstalledVersions returns [] — the installer drops the binary in
+        // ~/.local/bin (or similar) rather than the version's node_modules/.bin.
+        // Grok is special-cased in getBinaryPath itself (binary lives in
+        // ~/.grok/downloads), so we skip the symlink there.
+        if (agent !== 'grok') {
+            try {
+                const { stdout: whichOut } = await execFileAsync('which', [agentConfig.cliCommand]);
+                const installedBinary = whichOut.trim();
+                if (installedBinary && fs.existsSync(installedBinary)) {
+                    importInstallScriptBinary({ agentId: agent, npmPackage: agentConfig.npmPackage, cliCommand: agentConfig.cliCommand }, installedVersion, installedBinary, versionDir);
+                }
+            }
+            catch {
+                /* binary missing from PATH — install script failed silently; surface via the existing version.install error path below isn't possible here since the script returned 0. Leave the version dir empty so getBinaryPath check correctly reports it uninstalled. */
+            }
+        }
         createVersionedAlias(agent, installedVersion);
         emit('version.install', { agent, version: installedVersion });
         return { success: true, installedVersion };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.3",
+  "version": "1.20.4",
   "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",
@@ -74,7 +74,7 @@
     "npm": ">=9"
   },
   "dependencies": {
-    "@inquirer/prompts": "8.5.1",
+    "@inquirer/prompts": "8.5.2",
     "@types/proper-lockfile": "4.1.4",
     "@xterm/headless": "6.0.0",
     "@zed-industries/agent-client-protocol": "0.4.5",
@@ -85,7 +85,7 @@
     "marked": "15.0.12",
     "marked-terminal": "7.3.0",
     "node-pty": "1.1.0",
-    "ora": "8.2.0",
+    "ora": "9.4.0",
     "proper-lockfile": "4.1.2",
     "simple-git": "3.36.0",
     "smol-toml": "1.6.1",
@@ -94,9 +94,9 @@
   "devDependencies": {
     "@types/diff": "8.0.0",
     "@types/marked-terminal": "6.1.1",
-    "@types/node": "25.9.1",
-    "tsx": "4.22.3",
+    "@types/node": "25.9.2",
+    "tsx": "4.22.4",
     "typescript": "6.0.3",
-    "vitest": "4.1.6"
+    "vitest": "4.1.8"
   }
 }