@phnx-labs/agents-cli 1.20.26 → 1.20.28

package/dist/lib/versions.js

@@ -898,14 +898,36 @@ export async function isOldestInstalled(agent) {
     }
     return { installed: isVersionInstalled(agent, oldestVersion), version: oldestVersion };
 }
+// Per-process cache for listInstalledVersions. The agent's versions dir mtime
+// changes whenever a version dir is added or removed (install/remove), so a
+// stamp match means the installed set is unchanged and we skip the readdir +
+// N binary stats. Mirrors the readMeta() cache in state.ts. Hot path:
+// resolveAgentTargets and every enumerate-style consumer hit this.
+const installedVersionsCache = new Map();
+/** Drop the installed-versions cache (call after install/remove mutations). */
+export function invalidateInstalledVersionsCache(agent) {
+    if (agent)
+        installedVersionsCache.delete(agent);
+    else
+        installedVersionsCache.clear();
+}
 /**
- * List all installed versions for an agent.
+ * List all installed versions for an agent (cached by versions-dir mtime).
  */
 export function listInstalledVersions(agent) {
     const agentVersionsDir = path.join(getVersionsDir(), agent);
-    if (!fs.existsSync(agentVersionsDir)) {
+    let stamp;
+    try {
+        stamp = fs.statSync(agentVersionsDir).mtimeMs;
+    }
+    catch {
+        installedVersionsCache.set(agent, { stamp: 0, versions: [] });
         return [];
     }
+    const cached = installedVersionsCache.get(agent);
+    if (cached && cached.stamp === stamp) {
+        return cached.versions;
+    }
     const entries = fs.readdirSync(agentVersionsDir, { withFileTypes: true });
     const versions = [];
     for (const entry of entries) {
@@ -916,7 +938,9 @@ export function listInstalledVersions(agent) {
             }
         }
     }
-    return versions.sort(compareVersions);
+    versions.sort(compareVersions);
+    installedVersionsCache.set(agent, { stamp, versions });
+    return versions;
 }
 /**
  * List every version directory for an agent, including ones missing the
@@ -1339,19 +1363,23 @@ export function resolveVersion(agent, projectPath) {
 /**
  * Normalize a user-supplied @version token across CLI subcommands.
  *
- *   undefined / "" / "default"  -> undefined  (caller falls back to project pin or global default)
+ *   undefined / "" / "default" / "pinned" -> undefined  (caller falls back to project pin or global default)
+ *   "any"                       -> undefined  (caller imposes no version constraint — e.g. resume across any version)
  *   "latest"                    -> highest installed version (process.exit if none installed)
  *   "oldest"                    -> lowest installed version (process.exit if none installed)
  *   "x.y.z" (installed)         -> "x.y.z"
  *   "x.y.z" (not installed)     -> process.exit with installed-list hint
  *
+ * `pinned` is a synonym for `default`: both name the project pin / global
+ * default, which the caller resolves.
+ *
  * Use this anywhere the user can type `agents <cmd> claude@<token>` to keep the
  * vocabulary consistent. Subcommands with different semantics for `latest`
  * (install/remove/use, where `latest` means npm-latest) keep their existing
  * parsing.
  */
 export function resolveVersionAlias(agent, raw) {
-    if (!raw || raw === 'default')
+    if (!raw || raw === 'default' || raw === 'pinned' || raw === 'any')
         return undefined;
     if (raw === 'latest' || raw === 'oldest') {
         const installed = listInstalledVersions(agent);
@@ -1375,12 +1403,12 @@ export function resolveVersionAlias(agent, raw) {
 }
 /**
  * Loose variant of resolveVersionAlias for record-filter contexts (sessions,
- * team history). Same `default`/`latest`/`oldest` semantics, but explicit
+ * team history). Same `default`/`pinned`/`latest`/`oldest` semantics, but explicit
  * versions pass through unchanged so historical records of uninstalled versions
  * remain queryable.
  */
 export function resolveVersionAliasLoose(agent, raw) {
-    if (!raw || raw === 'default')
+    if (!raw || raw === 'default' || raw === 'pinned' || raw === 'any')
         return undefined;
     if (raw === 'latest' || raw === 'oldest') {
         const installed = listInstalledVersions(agent);
@@ -1831,7 +1859,15 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
         // dot-dirs to keep plugin-managed subtrees (.plugins/, .promptcuts) intact.
         const skillsTargetSweep = path.join(agentDir, 'skills');
         if (!userPassedSelection && fs.existsSync(skillsTargetSweep) && !fs.lstatSync(skillsTargetSweep).isSymbolicLink()) {
+            // Trust real skills AND command-skills: when commandsAsSkills, the
+            // commands writer (above) materialized each command as a skill dir under
+            // skills/. Those names are not in skillsToSync, so without this they'd be
+            // swept as orphans — silently deleting every converted command (e.g.
+            // /recap on kimi/grok).
             const trustedSkills = new Set(skillsToSync);
+            if (commandsAsSkills)
+                for (const cmd of commandsToSync)
+                    trustedSkills.add(cmd);
             for (const entry of fs.readdirSync(skillsTargetSweep, { withFileTypes: true })) {
                 if (!entry.isDirectory() || entry.name.startsWith('.'))
                     continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.26",
+  "version": "1.20.28",
   "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",
@@ -92,10 +92,10 @@
     "diff": "9.0.0",
     "marked": "15.0.12",
     "marked-terminal": "7.3.0",
-    "ora": "9.4.0",
+    "ora": "9.4.1",
     "proper-lockfile": "4.1.2",
     "simple-git": "3.36.0",
-    "smol-toml": "1.6.1",
+    "smol-toml": "1.7.0",
     "yaml": "2.9.0"
   },
   "devDependencies": {

package/scripts/postinstall.js

@@ -239,6 +239,10 @@ To enable version-aware shims, add this to your shell config:
     console.log(`  Installed shorthands: ${written.join(', ')}`);
   }
 
+  if (process.platform !== 'win32') {
+    await ensureAgentsResolvablePosix();
+  }
+
   await healLongRunningProcesses();
 
   const version = getVersion();
@@ -252,6 +256,64 @@ To enable version-aware shims, add this to your shell config:
   }
 }
 
+/**
+ * Make the `agents` command resolvable in a *login* shell on POSIX.
+ *
+ * `agents`/`ag` reach PATH only through npm's bin symlink in the npm global-bin
+ * dir. Under nvm (and other per-user node prefixes) that dir is missing from a
+ * non-interactive login shell's PATH, so `bash -lc 'agents …'` fails with
+ * command-not-found — which breaks `agents secrets export --host` (it runs
+ * `bash -lc 'agents secrets import …'` on the remote) and the routines daemon
+ * (src/lib/daemon.ts falls back to bare `agents`). This is the POSIX symmetric
+ * counterpart of the Windows branch in main() that registers npm's global-bin
+ * dir on the user PATH.
+ *
+ * Self-heal, not a prompt: it fires ONLY when `agents` is otherwise
+ * unresolvable — the genuinely-broken state — so it acts decisively, exactly
+ * like the Windows PATH registration. The symlink never clobbers a dev build
+ * (scripts/install.sh) or any real file. Skipped in CI (ephemeral homes) and
+ * when AGENTS_NO_HEAL=1.
+ */
+async function ensureAgentsResolvablePosix() {
+  if (process.env.CI || process.env.AGENTS_NO_HEAL === '1') return;
+  try {
+    const { localBinDir, ensureLocalBinSymlink, loginShellResolves, dirOnLoginPath } =
+      await import('../dist/lib/platform/posixpath.js');
+
+    // macOS/homebrew, system-node Linux, and dev-build users already resolve it.
+    if (loginShellResolves('agents')) return;
+
+    const binDir = localBinDir();
+    const results = ['agents', 'ag'].map((name) => ensureLocalBinSymlink(name, AGENTS_BIN, binDir));
+    if (!results.some((r) => r.created)) return; // nothing we could safely link
+
+    if (dirOnLoginPath(binDir)) {
+      console.log(`\n  Linked 'agents' into ${binDir} (already on the login PATH) so 'bash -lc agents' resolves.`);
+      return;
+    }
+
+    // ~/.local/bin isn't on the *bash* login PATH yet. The consumers run
+    // `bash -lc`, so add it to the file a bash login shell reads (~/.bash_profile
+    // when present, else ~/.profile) — not the interactive $SHELL rc, which for a
+    // zsh user (.zshrc) bash would never source.
+    const bashRc = fs.existsSync(path.join(HOME, '.bash_profile'))
+      ? path.join(HOME, '.bash_profile')
+      : path.join(HOME, '.profile');
+    const marker = '# agents-cli: ensure ~/.local/bin on PATH (so the agents command resolves)';
+    let already = false;
+    try {
+      already = fs.existsSync(bashRc) && fs.readFileSync(bashRc, 'utf-8').includes(marker);
+    } catch { /* unreadable rc — fall through and append */ }
+    if (!already) {
+      fs.appendFileSync(bashRc, `\n${marker}\nexport PATH="${binDir}:$PATH"\n`);
+    }
+    console.log(`\n  Linked 'agents' into ${binDir} and added it to PATH in ${path.basename(bashRc)}.`);
+    console.log(`  Restart your shell (or run: source ~/${path.basename(bashRc)}) to pick it up.`);
+  } catch {
+    /* best-effort: a failure here must never break the install */
+  }
+}
+
 /**
  * Self-heal long-running processes onto the just-installed code (macOS).
  *