@phnx-labs/agents-cli 1.16.0 → 1.17.1

package/dist/lib/cloud/rush.js

@@ -15,14 +15,15 @@ import { parseSSE } from './stream.js';
 import { listInstalledVersions, getVersionHomePath } from '../versions.js';
 import { getAccountInfo } from '../agents.js';
 import { loadClaudeOauth } from '../usage.js';
+import { selectBalancedVersion } from '../rotate.js';
 const PROXY_BASE = 'https://api.prix.dev';
 const USER_YAML = path.join(os.homedir(), '.rush', 'user.yaml');
 // Persistent consent record for uploading Claude OAuth blobs to Rush Cloud.
 // Created on first explicit consent (env var or flag); subsequent dispatches
 // see it and proceed without re-prompting.
-const RUSH_CONSENT_PATH = path.join(getCloudDir(), 'rush-consent.json');
+export const RUSH_CONSENT_PATH = path.join(getCloudDir(), 'rush-consent.json');
 const RUSH_CONSENT_ENV = 'AGENTS_RUSH_UPLOAD_TOKENS';
-function hasRushUploadConsent(opts) {
+export function hasRushUploadConsent(opts) {
     if (process.env[RUSH_CONSENT_ENV] === '1')
         return true;
     const po = opts?.providerOptions;
@@ -184,20 +185,37 @@ async function readClaudeCredentialsBlob(home) {
  * Returns null when no Claude versions are signed in (the dispatch falls back
  * to the platform-wide key, current behavior).
  */
-export async function buildAccountManifest() {
-    const versions = listInstalledVersions('claude');
-    if (versions.length === 0)
-        return null;
+export async function buildAccountManifest(strategy) {
+    let candidateVersions;
+    if (strategy === 'balanced') {
+        // Use the same health-checked, deduped-by-email set that `agents run --balanced` uses.
+        // `result.healthy` contains one candidate per unique email, ordered by remaining capacity.
+        const result = await selectBalancedVersion('claude');
+        if (!result || result.healthy.length === 0)
+            return null;
+        candidateVersions = result.healthy
+            .filter((c) => !!c.email)
+            .map((c) => ({ version: c.version, email: c.email }));
+    }
+    else {
+        // Default: all installed versions that have a signed-in account.
+        const versions = listInstalledVersions('claude');
+        if (versions.length === 0)
+            return null;
+        const rows = await Promise.all(versions.map(async (version) => {
+            const home = getVersionHomePath('claude', version);
+            const info = await getAccountInfo('claude', home);
+            return info.email ? { version, email: info.email } : null;
+        }));
+        candidateVersions = rows.filter((r) => r !== null);
+    }
     const entries = [];
-    for (const version of versions) {
+    for (const { version, email } of candidateVersions) {
         const home = getVersionHomePath('claude', version);
-        const info = await getAccountInfo('claude', home);
-        if (!info.email)
-            continue;
         const blob = await readClaudeCredentialsBlob(home);
         if (!blob)
             continue;
-        entries.push({ version, email: info.email, cred_fp: sha256(blob) });
+        entries.push({ version, email, cred_fp: sha256(blob) });
     }
     if (entries.length === 0)
         return null;
@@ -237,6 +255,7 @@ export function buildDispatchBody(input) {
         prompt: input.prompt,
         repos: input.resolvedRepos,
         mode: input.mode,
+        ...(input.strategy ? { strategy: input.strategy } : {}),
     };
     if (input.resolvedRepos.length === 1) {
         body.installation_id = primary.installation_id;
@@ -251,6 +270,37 @@ export function buildDispatchBody(input) {
     }
     return body;
 }
+/** Fetch all Claude accounts in this user's Rush Cloud rotation pool (no tokens). */
+export async function listRemoteAccounts() {
+    const token = readToken();
+    const res = await api('GET', '/api/v1/cloud-accounts', token);
+    if (!res.ok) {
+        throw new Error(`Failed to list accounts (${res.status}): ${sanitizeErrorBody(await res.text())}`);
+    }
+    const data = await res.json();
+    return data.accounts ?? [];
+}
+/**
+ * Register a CLAUDE_CODE_OAUTH_TOKEN with Rush Cloud's rotation pool.
+ * The server validates the token against the Anthropic usage API and stores it
+ * encrypted in Vault. Returns the account metadata (no token).
+ */
+export async function addRemoteAccount(provider, pastedToken) {
+    const token = readToken();
+    const res = await api('POST', '/api/v1/cloud-accounts', token, { provider, token: pastedToken });
+    if (!res.ok) {
+        throw new Error(`Failed to add account (${res.status}): ${sanitizeErrorBody(await res.text())}`);
+    }
+    return await res.json();
+}
+/** Remove a Claude account from Rush Cloud's rotation pool by its ID. */
+export async function removeRemoteAccount(id) {
+    const token = readToken();
+    const res = await api('DELETE', `/api/v1/cloud-accounts/${encodeURIComponent(id)}`, token);
+    if (!res.ok) {
+        throw new Error(`Failed to remove account (${res.status}): ${sanitizeErrorBody(await res.text())}`);
+    }
+}
 export class RushCloudProvider {
     id = 'rush';
     name = 'Rush Cloud';
@@ -289,13 +339,18 @@ export class RushCloudProvider {
             repo_owner: r.owner,
             repo_name: r.name,
         })));
-        const accountManifest = await buildAccountManifest();
+        const strategy = options.providerOptions?.strategy;
+        // When balanced, the server owns the pool and rotates internally — no
+        // client-side manifest needed. We just forward the strategy so the server
+        // knows to load from Vault instead of waiting for a manifest.
+        const accountManifest = strategy === 'balanced' ? null : await buildAccountManifest();
         const body = buildDispatchBody({
             agent: options.agent,
             prompt: options.prompt,
             mode: options.providerOptions?.mode,
             resolvedRepos,
             accountManifest,
+            strategy,
         });
         let res = await api('POST', '/api/v1/cloud-runs', token, body);
         // Server detects drift (new account or rotated token) by comparing the
@@ -317,7 +372,7 @@ export class RushCloudProvider {
                         ``,
                         `To consent, re-run with one of:`,
                         `  AGENTS_RUSH_UPLOAD_TOKENS=1 agents cloud run ...`,
-                        `  agents cloud run --upload-account-tokens ...   # if your CLI exposes this flag`,
+                        `  agents cloud run --upload-account-tokens ...`,
                         ``,
                         `Consent will be recorded at ${RUSH_CONSENT_PATH} so you won't be asked again.`,
                         `Remove that file to revoke.`,

package/dist/lib/commands.d.ts

@@ -35,10 +35,6 @@ export interface InstalledCommand {
     path: string;
     description?: string;
 }
-/** Parse command metadata (name, description) from YAML frontmatter or TOML headers. */
-export declare function parseCommandMetadata(filePath: string): CommandMetadata | null;
-/** Validate command metadata, returning errors and warnings. */
-export declare function validateCommandMetadata(metadata: CommandMetadata | null, commandName: string): ValidationResult;
 /** Discover all command markdown files in a repository's commands/ directory. */
 export declare function discoverCommands(repoPath: string): DiscoveredCommand[];
 /** Find the source path for a command in a repository. */
@@ -98,17 +94,6 @@ export declare function iterCommandsCapableVersions(filter?: {
 }>;
 /** Remove a command from an agent's config directory. */
 export declare function uninstallCommand(agentId: AgentId, commandName: string): boolean;
-/** List command names installed for an agent in the active version home. */
-export declare function listInstalledCommands(agentId: AgentId): string[];
-/**
- * Check if a command exists for an agent.
- */
-export declare function commandExists(agentId: AgentId, commandName: string): boolean;
-/**
- * Check if installed command content matches source content.
- * Handles format conversion (markdown to TOML for Gemini).
- */
-export declare function commandContentMatches(agentId: AgentId, commandName: string, sourcePath: string): boolean;
 /**
  * List installed commands with scope information.
  * Pass options.home to read from a version-managed agent's home directory.

package/dist/lib/commands.js

@@ -15,7 +15,7 @@ import { getCommandsDir, getUserCommandsDir, getEnabledExtraRepos, getProjectAge
 import { getEffectiveHome, getVersionHomePath, listInstalledVersions } from './versions.js';
 import { commandSkillMatches, installCommandSkillToVersion, listCommandSkillsInVersion, removeCommandSkillFromVersion, shouldInstallCommandAsSkill, } from './command-skills.js';
 /** Parse command metadata (name, description) from YAML frontmatter or TOML headers. */
-export function parseCommandMetadata(filePath) {
+function parseCommandMetadata(filePath) {
     if (!fs.existsSync(filePath)) {
         return null;
     }
@@ -51,7 +51,7 @@ export function parseCommandMetadata(filePath) {
     }
 }
 /** Validate command metadata, returning errors and warnings. */
-export function validateCommandMetadata(metadata, commandName) {
+function validateCommandMetadata(metadata, commandName) {
     const errors = [];
     const warnings = [];
     if (!metadata) {
@@ -336,7 +336,7 @@ export function uninstallCommand(agentId, commandName) {
     return false;
 }
 /** List command names installed for an agent in the active version home. */
-export function listInstalledCommands(agentId) {
+function listInstalledCommands(agentId) {
     const agent = AGENTS[agentId];
     const home = getEffectiveHome(agentId);
     const commandsDir = path.join(home, `.${agentId}`, agent.commandsSubdir);
@@ -352,7 +352,7 @@ export function listInstalledCommands(agentId) {
 /**
  * Check if a command exists for an agent.
  */
-export function commandExists(agentId, commandName) {
+function commandExists(agentId, commandName) {
     const agent = AGENTS[agentId];
     const home = getEffectiveHome(agentId);
     const commandsDir = path.join(home, `.${agentId}`, agent.commandsSubdir);
@@ -370,7 +370,7 @@ function normalizeContent(content) {
  * Check if installed command content matches source content.
  * Handles format conversion (markdown to TOML for Gemini).
  */
-export function commandContentMatches(agentId, commandName, sourcePath) {
+function commandContentMatches(agentId, commandName, sourcePath) {
     const agent = AGENTS[agentId];
     const home = getEffectiveHome(agentId);
     const commandsDir = path.join(home, `.${agentId}`, agent.commandsSubdir);

package/dist/lib/hooks.js

@@ -14,16 +14,15 @@ import * as TOML from 'smol-toml';
 import { AGENTS, HOOKS_CAPABLE_AGENTS } from './agents.js';
 import { supports, explainSkip } from './capabilities.js';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from './gemini-settings.js';
-import { getHooksDir as getSystemHooksDir, getUserHooksDir, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getTrashHooksDir } from './state.js';
+import { getHooksDir as getSystemHooksDir, getUserHooksDir, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getTrashHooksDir, getEnabledExtraRepos } from './state.js';
 function getCentralHooksDir() { return getUserHooksDir(); }
 /**
- * Resolve a hook script's absolute path by checking the user dir first
- * (where `installHooksCentrally` lands new files) and falling back to the
- * system dir (where npm-shipped defaults live). Returns null if neither
- * exists. Mirrors the precedence used by `listCentralHooks`.
+ * Resolve a hook script's absolute path. Checks user dir first, then enabled
+ * extra repos in insertion order, then system dir. Returns null if not found.
  */
 function resolveHookScriptPath(script) {
-    for (const root of [getUserAgentsDir(), getSystemAgentsDir()]) {
+    const extraDirs = getEnabledExtraRepos().map(e => e.dir);
+    for (const root of [getUserAgentsDir(), ...extraDirs, getSystemAgentsDir()]) {
         const candidate = path.join(root, 'hooks', script);
         if (fs.existsSync(candidate))
             return candidate;
@@ -32,14 +31,15 @@ function resolveHookScriptPath(script) {
 }
 /**
  * Prefixes used for stale-entry cleanup in agent settings files. A registered
- * hook command is considered "managed by us" if it lives under either
- * `~/.agents/hooks/` (user) or `~/.agents-system/hooks/` (system). Cleanup
- * filters use this list so leftover entries from either dir get garbage
- * collected on rewrite.
+ * hook command is considered "managed" if it lives under any known hooks dir
+ * (user, extra repos, or system). Entries from removed extra repos are also
+ * garbage-collected because they won't appear in this list any more.
  */
 function getManagedHookPrefixes() {
+    const extraDirs = getEnabledExtraRepos().map(e => e.dir);
     return [
         path.join(getUserAgentsDir(), 'hooks') + path.sep,
+        ...extraDirs.map(d => path.join(d, 'hooks') + path.sep),
         path.join(getSystemAgentsDir(), 'hooks') + path.sep,
     ];
 }
@@ -616,16 +616,29 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
         return { registered: [], errors: [] };
     }
     const overrideRoots = agentsDirOverride ? [agentsDirOverride] : null;
+    // Scripts are copied into the version home during sync — prefer that stable
+    // local path so registered commands don't break when source dirs change.
+    const localHooksDir = !overrideRoots
+        ? path.join(versionHome, `.${agentId}`, AGENTS[agentId].hooksDir)
+        : null;
     const resolveScript = (script) => {
         if (overrideRoots) {
             const candidate = path.join(overrideRoots[0], 'hooks', script);
             return fs.existsSync(candidate) ? candidate : null;
         }
+        if (localHooksDir) {
+            const local = path.join(localHooksDir, script);
+            if (fs.existsSync(local))
+                return local;
+        }
         return resolveHookScriptPath(script);
     };
     const managedPrefixes = overrideRoots
         ? [path.join(overrideRoots[0], 'hooks') + path.sep]
-        : getManagedHookPrefixes();
+        : [
+            ...getManagedHookPrefixes(),
+            ...(localHooksDir ? [localHooksDir + path.sep] : []),
+        ];
     if (agentId === 'claude') {
         return registerHooksForClaude(versionHome, manifest, resolveScript, managedPrefixes);
     }

package/dist/lib/import.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Import existing unmanaged agent installations into agents-cli.
+ *
+ * Two flavors:
+ *
+ *  1. Config-only import — moves an agent's config dir (e.g. ~/.openclaw)
+ *     into the version structure and symlinks it back. Used by `agents setup`
+ *     on first-run when an agent was previously installed via npm/homebrew.
+ *
+ *  2. Full import — also registers an existing binary install (e.g. a global
+ *     `npm i -g openclaw`) under the managed version path so the shim
+ *     resolver can find it. This is what `agents import <agent>` does.
+ *
+ * The binary side never moves files. It creates a thin symlink farm under
+ * `~/.agents/.history/versions/<agent>/<version>/` pointing at the original
+ * global install, plus a package.json marker so `isVersionInstalled` returns
+ * true.
+ */
+import type { AgentId } from './types.js';
+export interface ImportConfigResult {
+    success: boolean;
+    skipped?: boolean;
+    error?: string;
+}
+export interface ImportBinaryResult {
+    success: boolean;
+    skipped?: boolean;
+    error?: string;
+    resolvedFromPath?: string;
+}
+/**
+ * Move an agent's config dir into the managed version structure and symlink it
+ * back to its original location. Sets the imported version as the global
+ * default and refreshes the shim so the user's PATH lookup hits the managed
+ * version.
+ *
+ * No-op (returns skipped=true) if the version's config dir is already created.
+ */
+export declare function importAgentConfig(agentId: AgentId, version: string): Promise<ImportConfigResult>;
+/**
+ * Wire an imported version into the rest of the system so it behaves the same
+ * as a freshly installed version:
+ *
+ *   - registered as the global default in agents.yaml (so `agents view`
+ *     reports it correctly and resolvers find it),
+ *   - main shim refreshed (`~/.agents/.cache/shims/<cli>`),
+ *   - versioned alias created (`~/.agents/.cache/shims/<cli>@<version>`),
+ *   - home-file symlinks (CLAUDE.md / AGENTS.md / etc.) repointed at this
+ *     version's home dir.
+ *
+ * Without this, the binary-only import path would leave the version stranded:
+ * isVersionInstalled returns true, but the resolver never picks it. Safe to
+ * call multiple times — each underlying function is idempotent.
+ */
+export declare function finalizeImport(agentId: AgentId, version: string): void;
+/**
+ * Agent metadata needed by importAgentBinary. Taking these as explicit
+ * inputs (rather than looking up AGENTS internally) decouples the symlink
+ * farm from the AGENTS registry, which keeps the function pure and avoids
+ * fragile coupling in test setups that stub `lib/agents.ts`.
+ */
+export interface AgentBinarySpec {
+    /** Agent id used in the marker package.json (`agents-{agentId}-{version}`). */
+    agentId: string;
+    /** npm package name (e.g. `openclaw`) — used as the `node_modules/<name>` dir. */
+    npmPackage: string;
+    /** Binary name on PATH (e.g. `openclaw`) — used as the `.bin/<name>` entry. */
+    cliCommand: string;
+}
+/**
+ * Register an existing global npm package install under the managed version
+ * path so the shim resolver finds it.
+ *
+ * Layout produced (everything is a symlink, nothing is copied):
+ *
+ *   {versionDir}/
+ *     package.json                          # marker so isVersionInstalled() is true
+ *     home/                                 # empty isolated $HOME for this version
+ *     node_modules/{npmPackage}    -> {globalPath}
+ *     node_modules/.bin/{cliCommand} -> {binaryEntry}
+ */
+export declare function importAgentBinary(spec: AgentBinarySpec, version: string, globalPath: 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 can't be identified.
+ *
+ * Handles the homebrew/global-npm pattern where:
+ *   /opt/homebrew/bin/{cli}  ->  ../lib/node_modules/{pkg}/dist/index.js
+ */
+export declare function resolvePackageDirFromBinary(binaryPath: string): string | null;

package/dist/lib/import.js

@@ -0,0 +1,179 @@
+/**
+ * Import existing unmanaged agent installations into agents-cli.
+ *
+ * Two flavors:
+ *
+ *  1. Config-only import — moves an agent's config dir (e.g. ~/.openclaw)
+ *     into the version structure and symlinks it back. Used by `agents setup`
+ *     on first-run when an agent was previously installed via npm/homebrew.
+ *
+ *  2. Full import — also registers an existing binary install (e.g. a global
+ *     `npm i -g openclaw`) under the managed version path so the shim
+ *     resolver can find it. This is what `agents import <agent>` does.
+ *
+ * The binary side never moves files. It creates a thin symlink farm under
+ * `~/.agents/.history/versions/<agent>/<version>/` pointing at the original
+ * global install, plus a package.json marker so `isVersionInstalled` returns
+ * true.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { AGENTS } from './agents.js';
+import { getVersionsDir } from './state.js';
+import { setGlobalDefault } from './versions.js';
+import { createShim, createVersionedAlias, ensureShimCurrent, switchHomeFileSymlinks } from './shims.js';
+/**
+ * Move an agent's config dir into the managed version structure and symlink it
+ * back to its original location. Sets the imported version as the global
+ * default and refreshes the shim so the user's PATH lookup hits the managed
+ * version.
+ *
+ * No-op (returns skipped=true) if the version's config dir is already created.
+ */
+export async function importAgentConfig(agentId, version) {
+    const agent = AGENTS[agentId];
+    const configDir = agent.configDir;
+    const versionsDir = getVersionsDir();
+    const versionHome = path.join(versionsDir, agentId, version, 'home');
+    const versionConfigDir = path.join(versionHome, `.${agentId}`);
+    if (fs.existsSync(versionConfigDir)) {
+        return { success: false, skipped: true, error: `${version} already installed` };
+    }
+    try {
+        fs.mkdirSync(versionHome, { recursive: true });
+        fs.renameSync(configDir, versionConfigDir);
+        fs.symlinkSync(versionConfigDir, configDir);
+        setGlobalDefault(agentId, version);
+        switchHomeFileSymlinks(agentId, version);
+        ensureShimCurrent(agentId);
+        return { success: true };
+    }
+    catch (err) {
+        return { success: false, error: err.message };
+    }
+}
+/**
+ * Wire an imported version into the rest of the system so it behaves the same
+ * as a freshly installed version:
+ *
+ *   - registered as the global default in agents.yaml (so `agents view`
+ *     reports it correctly and resolvers find it),
+ *   - main shim refreshed (`~/.agents/.cache/shims/<cli>`),
+ *   - versioned alias created (`~/.agents/.cache/shims/<cli>@<version>`),
+ *   - home-file symlinks (CLAUDE.md / AGENTS.md / etc.) repointed at this
+ *     version's home dir.
+ *
+ * Without this, the binary-only import path would leave the version stranded:
+ * isVersionInstalled returns true, but the resolver never picks it. Safe to
+ * call multiple times — each underlying function is idempotent.
+ */
+export function finalizeImport(agentId, version) {
+    setGlobalDefault(agentId, version);
+    createShim(agentId);
+    createVersionedAlias(agentId, version);
+    switchHomeFileSymlinks(agentId, version);
+    ensureShimCurrent(agentId);
+}
+/**
+ * Register an existing global npm package install under the managed version
+ * path so the shim resolver finds it.
+ *
+ * Layout produced (everything is a symlink, nothing is copied):
+ *
+ *   {versionDir}/
+ *     package.json                          # marker so isVersionInstalled() is true
+ *     home/                                 # empty isolated $HOME for this version
+ *     node_modules/{npmPackage}    -> {globalPath}
+ *     node_modules/.bin/{cliCommand} -> {binaryEntry}
+ */
+export function importAgentBinary(spec, version, globalPath, versionDir) {
+    const binaryLink = path.join(versionDir, 'node_modules', '.bin', spec.cliCommand);
+    // lstat — we want to detect the symlink itself, not follow it. fs.existsSync
+    // can return false on dangling symlinks, which would incorrectly let us
+    // proceed to symlinkSync below and throw EEXIST.
+    let alreadyExists = false;
+    try {
+        fs.lstatSync(binaryLink);
+        alreadyExists = true;
+    }
+    catch {
+        /* not present */
+    }
+    if (alreadyExists) {
+        return { success: false, skipped: true, error: `${version} already installed`, resolvedFromPath: globalPath };
+    }
+    if (!fs.existsSync(globalPath)) {
+        return { success: false, error: `Path does not exist: ${globalPath}` };
+    }
+    const globalPkgJson = path.join(globalPath, 'package.json');
+    if (!fs.existsSync(globalPkgJson)) {
+        return { success: false, error: `Not an npm package (no package.json): ${globalPath}` };
+    }
+    let pkgBinEntry;
+    try {
+        const pkg = JSON.parse(fs.readFileSync(globalPkgJson, 'utf8'));
+        if (typeof pkg.bin === 'string') {
+            pkgBinEntry = pkg.bin;
+        }
+        else if (pkg.bin && typeof pkg.bin === 'object') {
+            // Strict: only accept the exact cliCommand key. Multi-bin packages
+            // (e.g. @anthropic-ai/claude-code ships several bins) would otherwise
+            // silently get a wrong binary chosen by Object.values() ordering.
+            pkgBinEntry = pkg.bin[spec.cliCommand];
+        }
+    }
+    catch (err) {
+        return { success: false, error: `Failed to read package.json: ${err.message}` };
+    }
+    if (!pkgBinEntry) {
+        return { success: false, error: `package.json has no bin entry for "${spec.cliCommand}" — pass --from-path to a package that ships it` };
+    }
+    const binaryTarget = path.resolve(globalPath, pkgBinEntry);
+    if (!fs.existsSync(binaryTarget)) {
+        return { success: false, error: `Binary entry missing: ${binaryTarget}` };
+    }
+    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: globalPath }, null, 2));
+        const pkgLink = path.join(versionDir, 'node_modules', spec.npmPackage);
+        fs.mkdirSync(path.dirname(pkgLink), { recursive: true });
+        if (!fs.existsSync(pkgLink)) {
+            fs.symlinkSync(globalPath, pkgLink);
+        }
+        fs.symlinkSync(binaryTarget, binaryLink);
+        return { success: true, resolvedFromPath: globalPath };
+    }
+    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 can't be identified.
+ *
+ * Handles the homebrew/global-npm pattern where:
+ *   /opt/homebrew/bin/{cli}  ->  ../lib/node_modules/{pkg}/dist/index.js
+ */
+export function resolvePackageDirFromBinary(binaryPath) {
+    try {
+        let real = fs.realpathSync(binaryPath);
+        let dir = path.dirname(real);
+        // Walk up looking for the nearest package.json
+        for (let i = 0; i < 6; i++) {
+            const pkg = path.join(dir, 'package.json');
+            if (fs.existsSync(pkg)) {
+                return dir;
+            }
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/lib/migrate.js

@@ -8,7 +8,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as yaml from 'yaml';
-const HOME = os.homedir();
+const HOME = process.env.HOME ?? os.homedir();
 const SYSTEM_DIR = path.join(HOME, '.agents-system');
 const USER_DIR = path.join(HOME, '.agents');
 const HISTORY_DIR = path.join(USER_DIR, '.history');
@@ -1325,6 +1325,63 @@ function warnSystemOrphans() {
         return;
     console.error(`~/.agents-system/ has unexpected entries (not part of the npm-shipped defaults): ${orphans.join(', ')}`);
 }
+const VERSION_RESOURCE_FLAT_KEYS = ['commands', 'skills', 'hooks', 'memory', 'subagents', 'plugins', 'workflows', 'permissions', 'mcp'];
+/**
+ * Convert agents.yaml versions: entries from the old flat name-list format to
+ * the new pattern format. Flat entries are detected by checking whether all
+ * items in the array lack a ':' separator (plain names have no source prefix).
+ *
+ * The rulesPreset field is preserved. Flat resource lists are dropped — the
+ * next `agents sync` will write default patterns (system:* user:* project:*).
+ *
+ * Idempotent: entries already in pattern format are left untouched.
+ */
+function migrateVersionResourcesToPatterns() {
+    const metaFile = path.join(USER_DIR, 'agents.yaml');
+    if (!fs.existsSync(metaFile))
+        return;
+    let meta;
+    try {
+        const raw = fs.readFileSync(metaFile, 'utf-8');
+        meta = yaml.parse(raw) || {};
+    }
+    catch {
+        return;
+    }
+    const versions = meta.versions;
+    if (!versions || typeof versions !== 'object')
+        return;
+    let changed = false;
+    for (const agentVersions of Object.values(versions)) {
+        if (!agentVersions || typeof agentVersions !== 'object')
+            continue;
+        for (const vr of Object.values(agentVersions)) {
+            if (!vr || typeof vr !== 'object')
+                continue;
+            for (const key of VERSION_RESOURCE_FLAT_KEYS) {
+                const val = vr[key];
+                if (!Array.isArray(val) || val.length === 0)
+                    continue;
+                // Detect legacy: all items are plain names (no ':' separator)
+                if (val.every(item => typeof item === 'string' && !item.includes(':'))) {
+                    if (key === 'memory') {
+                        // memory was a single-element array holding the preset name — move to rulesPreset
+                        if (val.length === 1 && !vr['rulesPreset']) {
+                            vr['rulesPreset'] = val[0];
+                        }
+                    }
+                    delete vr[key];
+                    changed = true;
+                }
+            }
+        }
+    }
+    if (changed) {
+        const META_HEADER = '# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agents-cli\n\n';
+        fs.writeFileSync(metaFile, META_HEADER + yaml.stringify(meta), 'utf-8');
+        console.error('Migrated agents.yaml versions: entries to pattern format');
+    }
+}
 /** Run all idempotent migrations. Safe to call multiple times. */
 export async function runMigration() {
     migrateAgentsYaml();
@@ -1344,6 +1401,7 @@ export async function runMigration() {
     cleanupEmptyTopLevelRuns();
     foldUserHooksYamlIntoAgentsYaml();
     foldBrowserProfilesIntoAgentsYaml();
+    migrateVersionResourcesToPatterns();
     // Bucket moves: collapse runtime state into ~/.agents/.history and ~/.agents/.cache.
     migrateRuntimeToHistory();
     migrateRuntimeToCache();