@phnx-labs/agents-cli 1.20.52 → 1.20.53

package/dist/lib/subagents.js

@@ -262,6 +262,153 @@ export function transformSubagentForDroid(subagentDir) {
     }
     return result;
 }
+/**
+ * Transform a subagent into an OpenCode agent markdown file.
+ *
+ * OpenCode loads agents from ~/.config/opencode/agents/*.md (global) with
+ * YAML frontmatter (description required; mode: subagent for invocable
+ * subagents) and a prompt body. File stem becomes the agent name.
+ * https://opencode.ai/docs/agents/
+ */
+export function transformSubagentForOpenCode(subagentDir) {
+    const agentMd = path.join(subagentDir, 'AGENT.md');
+    const frontmatter = parseSubagentFrontmatter(agentMd);
+    const body = getSubagentBody(agentMd);
+    if (!frontmatter) {
+        throw new Error(`Invalid AGENT.md in ${subagentDir}`);
+    }
+    const fm = {
+        description: frontmatter.description,
+        mode: 'subagent',
+    };
+    if (frontmatter.model)
+        fm.model = frontmatter.model;
+    let systemPrompt = body.trim();
+    const files = fs.readdirSync(subagentDir)
+        .filter(f => f.endsWith('.md') && f !== 'AGENT.md')
+        .sort();
+    for (const file of files) {
+        const content = fs.readFileSync(path.join(subagentDir, file), 'utf-8').trim();
+        const sectionName = file.replace('.md', '');
+        const title = sectionName.charAt(0).toUpperCase() + sectionName.slice(1).toLowerCase();
+        systemPrompt += `\n\n## ${title}\n\n${content}`;
+    }
+    return `---\n${yaml.stringify(fm).trim()}\n---\n\n${systemPrompt}\n`;
+}
+/** Managed parent agent file for Kimi (underscore prefix avoids clobbering a user subagent named agents-cli). */
+export const KIMI_SUBAGENTS_PARENT_FILE = '_agents-cli.yaml';
+/**
+ * Transform a subagent into Kimi Code agent files.
+ *
+ * Kimi's schema (agentspec) only accepts `system_prompt_path` (path relative to
+ * the agent YAML) — there is no inline `system_prompt` key. We write:
+ *   ~/.kimi-code/agents/<name>.yaml          — agent YAML
+ *   ~/.kimi-code/agents/<name>.system.md     — system prompt body
+ * plus a managed parent `_agents-cli.yaml` that lists them under agent.subagents
+ * for `kimi --agent-file …/_agents-cli.yaml`.
+ * https://moonshotai.github.io/kimi-cli/en/customization/agents.html
+ */
+export function transformSubagentForKimi(subagentDir, fileBaseName) {
+    const agentMd = path.join(subagentDir, 'AGENT.md');
+    const frontmatter = parseSubagentFrontmatter(agentMd);
+    const body = getSubagentBody(agentMd);
+    if (!frontmatter) {
+        throw new Error(`Invalid AGENT.md in ${subagentDir}`);
+    }
+    let systemPrompt = body.trim();
+    const files = fs.readdirSync(subagentDir)
+        .filter(f => f.endsWith('.md') && f !== 'AGENT.md')
+        .sort();
+    for (const file of files) {
+        const content = fs.readFileSync(path.join(subagentDir, file), 'utf-8').trim();
+        const sectionName = file.replace('.md', '');
+        const title = sectionName.charAt(0).toUpperCase() + sectionName.slice(1).toLowerCase();
+        systemPrompt += `\n\n## ${title}\n\n${content}`;
+    }
+    const systemPromptFileName = `${fileBaseName}.system.md`;
+    const doc = {
+        version: 1,
+        agent: {
+            extend: 'default',
+            name: frontmatter.name,
+            description: frontmatter.description,
+            system_prompt_path: `./${systemPromptFileName}`,
+        },
+    };
+    if (frontmatter.model) {
+        doc.agent.model = frontmatter.model;
+    }
+    return {
+        yaml: yaml.stringify(doc),
+        systemPrompt,
+        systemPromptFileName,
+    };
+}
+/**
+ * Build the managed parent agent YAML that declares all installed subagents
+ * so `kimi --agent-file ~/.kimi-code/agents/_agents-cli.yaml` can launch them.
+ */
+export function buildKimiSubagentsParentYaml(entries) {
+    const subagents = {};
+    for (const e of entries) {
+        subagents[e.name] = { path: e.relativePath, description: e.description };
+    }
+    return yaml.stringify({
+        version: 1,
+        agent: {
+            extend: 'default',
+            name: 'agents-cli',
+            description: 'Managed parent agent listing agents-cli synced subagents',
+            subagents,
+        },
+    });
+}
+/** Write a Kimi subagent YAML + sibling system-prompt md into agentsDir. */
+export function writeKimiSubagentFiles(agentsDir, subagentDir, name) {
+    const { yaml: yml, systemPrompt, systemPromptFileName } = transformSubagentForKimi(subagentDir, name);
+    fs.mkdirSync(agentsDir, { recursive: true });
+    fs.writeFileSync(safeJoin(agentsDir, `${name}.yaml`), yml);
+    fs.writeFileSync(safeJoin(agentsDir, systemPromptFileName), systemPrompt);
+}
+/**
+ * Transform a subagent into a Codex custom-agent TOML file.
+ *
+ * Codex loads standalone TOML under ~/.codex/agents/*.toml. Required fields:
+ * name, description, developer_instructions. Optional model maps from our
+ * frontmatter when present.
+ * https://developers.openai.com/codex/subagents (custom agents section)
+ */
+export function transformSubagentForCodex(subagentDir) {
+    const agentMd = path.join(subagentDir, 'AGENT.md');
+    const frontmatter = parseSubagentFrontmatter(agentMd);
+    const body = getSubagentBody(agentMd);
+    if (!frontmatter) {
+        throw new Error(`Invalid AGENT.md in ${subagentDir}`);
+    }
+    // Append other .md files into the developer_instructions body.
+    let instructions = body.trim();
+    const files = fs.readdirSync(subagentDir)
+        .filter(f => f.endsWith('.md') && f !== 'AGENT.md')
+        .sort();
+    for (const file of files) {
+        const content = fs.readFileSync(path.join(subagentDir, file), 'utf-8').trim();
+        const sectionName = file.replace('.md', '');
+        const title = sectionName.charAt(0).toUpperCase() + sectionName.slice(1).toLowerCase();
+        instructions += `\n\n## ${title}\n\n${content}`;
+    }
+    // Escape TOML multi-line string (""") content — only """ needs escaping.
+    const safeInstructions = instructions.replace(/"""/g, '\\"""');
+    const safeName = frontmatter.name.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    const safeDesc = frontmatter.description.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    let toml = `name = "${safeName}"\n`;
+    toml += `description = "${safeDesc}"\n`;
+    if (frontmatter.model) {
+        const safeModel = String(frontmatter.model).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+        toml += `model = "${safeModel}"\n`;
+    }
+    toml += `developer_instructions = """\n${safeInstructions}\n"""\n`;
+    return toml;
+}
 /**
  * Sync a subagent to an OpenClaw workspace
  * Copies full directory, renames AGENT.md to AGENTS.md
@@ -291,9 +438,10 @@ export function syncSubagentToOpenclaw(subagentDir, targetDir) {
  * Install a subagent to a specific agent's home
  */
 export function installSubagentToAgent(subagentDir, subagentName, agent, agentHome) {
-    if (agent === 'claude') {
-        // Claude: flatten to single .md file
-        const agentsDir = path.join(agentHome, '.claude', 'agents');
+    if (agent === 'claude' || agent === 'grok') {
+        // Claude / Grok: flatten to single .md under ~/.claude/agents or ~/.grok/agents
+        // Grok discovers user agent defs from ~/.grok/agents/*.md (same shape as Claude).
+        const agentsDir = path.join(agentHome, agent === 'grok' ? '.grok' : '.claude', 'agents');
         if (!fs.existsSync(agentsDir)) {
             fs.mkdirSync(agentsDir, { recursive: true });
         }
@@ -306,6 +454,44 @@ export function installSubagentToAgent(subagentDir, subagentName, agent, agentHo
             return { success: false, error: String(err) };
         }
     }
+    else if (agent === 'codex') {
+        // Codex: standalone TOML under ~/.codex/agents/<name>.toml
+        const agentsDir = path.join(agentHome, '.codex', 'agents');
+        if (!fs.existsSync(agentsDir)) {
+            fs.mkdirSync(agentsDir, { recursive: true });
+        }
+        try {
+            const toml = transformSubagentForCodex(subagentDir);
+            fs.writeFileSync(safeJoin(agentsDir, `${subagentName}.toml`), toml);
+            return { success: true };
+        }
+        catch (err) {
+            return { success: false, error: String(err) };
+        }
+    }
+    else if (agent === 'kimi') {
+        // Kimi: YAML + sibling system-prompt md under ~/.kimi-code/agents/
+        try {
+            writeKimiSubagentFiles(path.join(agentHome, '.kimi-code', 'agents'), subagentDir, subagentName);
+            return { success: true };
+        }
+        catch (err) {
+            return { success: false, error: String(err) };
+        }
+    }
+    else if (agent === 'opencode') {
+        // OpenCode: markdown agents under ~/.config/opencode/agents/
+        const agentsDir = path.join(agentHome, '.config', 'opencode', 'agents');
+        if (!fs.existsSync(agentsDir))
+            fs.mkdirSync(agentsDir, { recursive: true });
+        try {
+            fs.writeFileSync(safeJoin(agentsDir, `${subagentName}.md`), transformSubagentForOpenCode(subagentDir));
+            return { success: true };
+        }
+        catch (err) {
+            return { success: false, error: String(err) };
+        }
+    }
     else if (agent === 'openclaw') {
         // OpenClaw: copy full directory
         const targetDir = safeJoin(path.join(agentHome, '.openclaw'), subagentName);
@@ -321,13 +507,37 @@ export function installSubagentToAgent(subagentDir, subagentName, agent, agentHo
  */
 export function removeSubagentFromAgent(subagentName, agent, agentHome) {
     try {
-        if (agent === 'claude') {
-            const targetPath = safeJoin(path.join(agentHome, '.claude', 'agents'), `${subagentName}.md`);
+        if (agent === 'claude' || agent === 'grok') {
+            const agentsRoot = agent === 'grok' ? '.grok' : '.claude';
+            const targetPath = safeJoin(path.join(agentHome, agentsRoot, 'agents'), `${subagentName}.md`);
+            if (fs.existsSync(targetPath)) {
+                fs.unlinkSync(targetPath);
+            }
+            return { success: true };
+        }
+        else if (agent === 'codex') {
+            const targetPath = safeJoin(path.join(agentHome, '.codex', 'agents'), `${subagentName}.toml`);
             if (fs.existsSync(targetPath)) {
                 fs.unlinkSync(targetPath);
             }
             return { success: true };
         }
+        else if (agent === 'kimi') {
+            const agentsDir = path.join(agentHome, '.kimi-code', 'agents');
+            const targetPath = safeJoin(agentsDir, `${subagentName}.yaml`);
+            const promptPath = safeJoin(agentsDir, `${subagentName}.system.md`);
+            if (fs.existsSync(targetPath))
+                fs.unlinkSync(targetPath);
+            if (fs.existsSync(promptPath))
+                fs.unlinkSync(promptPath);
+            return { success: true };
+        }
+        else if (agent === 'opencode') {
+            const targetPath = safeJoin(path.join(agentHome, '.config', 'opencode', 'agents'), `${subagentName}.md`);
+            if (fs.existsSync(targetPath))
+                fs.unlinkSync(targetPath);
+            return { success: true };
+        }
         else if (agent === 'openclaw') {
             const targetDir = safeJoin(path.join(agentHome, '.openclaw'), subagentName);
             if (fs.existsSync(targetDir)) {
@@ -373,13 +583,14 @@ export function subagentContentMatches(installedDir, sourceDir) {
 /**
  * List subagents installed to a specific agent's home
  * Claude: scans ~/.claude/agents/{name}.md
+ * Kimi: scans ~/.kimi-code/agents/{name}.yaml (+ sibling .system.md)
  * OpenClaw: scans ~/.openclaw/{name}/AGENTS.md
  */
 export function listSubagentsForAgent(agentId, home) {
     const subagents = [];
-    if (agentId === 'claude') {
-        // Claude: flat .md files in agents/
-        const agentsDir = path.join(home, '.claude', 'agents');
+    if (agentId === 'claude' || agentId === 'grok') {
+        // Claude / Grok: flat .md files in agents/
+        const agentsDir = path.join(home, agentId === 'grok' ? '.grok' : '.claude', 'agents');
         if (!fs.existsSync(agentsDir))
             return subagents;
         for (const file of fs.readdirSync(agentsDir)) {
@@ -400,6 +611,51 @@ export function listSubagentsForAgent(agentId, home) {
             });
         }
     }
+    else if (agentId === 'kimi') {
+        // Kimi: flat YAML under .kimi-code/agents/ (exclude managed parent _*.yaml)
+        const agentsDir = path.join(home, '.kimi-code', 'agents');
+        if (!fs.existsSync(agentsDir))
+            return subagents;
+        for (const file of fs.readdirSync(agentsDir)) {
+            if (!file.endsWith('.yaml') || file.startsWith('_'))
+                continue;
+            const filePath = path.join(agentsDir, file);
+            if (!fs.statSync(filePath).isFile())
+                continue;
+            const name = file.replace(/\.yaml$/, '');
+            let description = '';
+            try {
+                const parsed = yaml.parse(fs.readFileSync(filePath, 'utf-8'));
+                description = parsed?.agent?.description ?? '';
+            }
+            catch { /* leave description empty */ }
+            const files = [file];
+            const promptFile = `${name}.system.md`;
+            if (fs.existsSync(path.join(agentsDir, promptFile)))
+                files.push(promptFile);
+            subagents.push({
+                name,
+                path: filePath,
+                files,
+                frontmatter: { name, description },
+            });
+        }
+    }
+    else if (agentId === 'opencode') {
+        const agentsDir = path.join(home, '.config', 'opencode', 'agents');
+        if (!fs.existsSync(agentsDir))
+            return subagents;
+        for (const file of fs.readdirSync(agentsDir)) {
+            if (!file.endsWith('.md'))
+                continue;
+            const filePath = path.join(agentsDir, file);
+            if (!fs.statSync(filePath).isFile())
+                continue;
+            const name = file.replace(/\.md$/, '');
+            const frontmatter = parseSubagentFrontmatter(filePath) ?? { name, description: '' };
+            subagents.push({ name, path: filePath, files: [file], frontmatter });
+        }
+    }
     else if (agentId === 'openclaw') {
         // OpenClaw: directories with AGENTS.md
         const openclawDir = path.join(home, '.openclaw');
@@ -462,8 +718,8 @@ export function diffVersionSubagents(agent, version) {
         }
     }
     // Check what's installed
-    if (agent === 'claude') {
-        const agentsDir = path.join(versionHome, '.claude', 'agents');
+    if (agent === 'claude' || agent === 'grok') {
+        const agentsDir = path.join(versionHome, agent === 'grok' ? '.grok' : '.claude', 'agents');
         if (fs.existsSync(agentsDir)) {
             for (const file of fs.readdirSync(agentsDir)) {
                 if (!file.endsWith('.md'))
@@ -475,6 +731,31 @@ export function diffVersionSubagents(agent, version) {
             }
         }
     }
+    else if (agent === 'kimi') {
+        const agentsDir = path.join(versionHome, '.kimi-code', 'agents');
+        if (fs.existsSync(agentsDir)) {
+            for (const file of fs.readdirSync(agentsDir)) {
+                if (!file.endsWith('.yaml') || file.startsWith('_'))
+                    continue;
+                const name = path.basename(file, '.yaml');
+                if (!discovered.has(name)) {
+                    orphans.push(name);
+                }
+            }
+        }
+    }
+    else if (agent === 'opencode') {
+        const agentsDir = path.join(versionHome, '.config', 'opencode', 'agents');
+        if (fs.existsSync(agentsDir)) {
+            for (const file of fs.readdirSync(agentsDir)) {
+                if (!file.endsWith('.md'))
+                    continue;
+                const name = path.basename(file, '.md');
+                if (!discovered.has(name))
+                    orphans.push(name);
+            }
+        }
+    }
     else if (agent === 'openclaw') {
         const openclawDir = path.join(versionHome, '.openclaw');
         if (fs.existsSync(openclawDir)) {
@@ -516,8 +797,30 @@ export function removeSubagentFromVersion(agent, version, subagentName) {
     const stamp = new Date().toISOString().replace(/[:.]/g, '-');
     const trashDir = path.join(getTrashSubagentsDir(), agent, version, subagentName);
     try {
-        if (agent === 'claude') {
-            const targetPath = path.join(versionHome, '.claude', 'agents', `${subagentName}.md`);
+        if (agent === 'claude' || agent === 'grok') {
+            const agentsRoot = agent === 'grok' ? '.grok' : '.claude';
+            const targetPath = path.join(versionHome, agentsRoot, 'agents', `${subagentName}.md`);
+            if (fs.existsSync(targetPath)) {
+                fs.mkdirSync(trashDir, { recursive: true, mode: 0o700 });
+                fs.renameSync(targetPath, path.join(trashDir, `${subagentName}.md.${stamp}`));
+            }
+        }
+        else if (agent === 'kimi') {
+            const agentsDir = path.join(versionHome, '.kimi-code', 'agents');
+            const yamlPath = path.join(agentsDir, `${subagentName}.yaml`);
+            const promptPath = path.join(agentsDir, `${subagentName}.system.md`);
+            if (fs.existsSync(yamlPath) || fs.existsSync(promptPath)) {
+                fs.mkdirSync(trashDir, { recursive: true, mode: 0o700 });
+                if (fs.existsSync(yamlPath)) {
+                    fs.renameSync(yamlPath, path.join(trashDir, `${subagentName}.yaml.${stamp}`));
+                }
+                if (fs.existsSync(promptPath)) {
+                    fs.renameSync(promptPath, path.join(trashDir, `${subagentName}.system.md.${stamp}`));
+                }
+            }
+        }
+        else if (agent === 'opencode') {
+            const targetPath = path.join(versionHome, '.config', 'opencode', 'agents', `${subagentName}.md`);
             if (fs.existsSync(targetPath)) {
                 fs.mkdirSync(trashDir, { recursive: true, mode: 0o700 });
                 fs.renameSync(targetPath, path.join(trashDir, `${subagentName}.md.${stamp}`));

package/dist/lib/teams/worktree.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Check if `dir` is inside a git repository (**async, worktree-correct**).
+ *
+ * Shells out to `git rev-parse --git-dir`, so it returns true from any
+ * subdirectory and for linked worktrees. Distinct from the synchronous,
+ * root-only `isGitRepo` in `lib/git.ts` (a `.git`-existence check): different
+ * semantics, so the two are intentionally **not** merged.
+ */
 export declare function isGitRepo(dir: string): Promise<boolean>;
 export declare function getGitRoot(dir: string): Promise<string>;
 /**

package/dist/lib/teams/worktree.js

@@ -11,6 +11,14 @@ import * as path from 'path';
 import { safeJoin } from '../paths.js';
 const execFileAsync = promisify(execFile);
 const WORKTREE_NAME_RE = /^[A-Za-z0-9_-]+$/;
+/**
+ * Check if `dir` is inside a git repository (**async, worktree-correct**).
+ *
+ * Shells out to `git rev-parse --git-dir`, so it returns true from any
+ * subdirectory and for linked worktrees. Distinct from the synchronous,
+ * root-only `isGitRepo` in `lib/git.ts` (a `.git`-existence check): different
+ * semantics, so the two are intentionally **not** merged.
+ */
 export async function isGitRepo(dir) {
     try {
         await execFileAsync('git', ['rev-parse', '--git-dir'], { cwd: dir });

package/dist/lib/types.d.ts

@@ -7,7 +7,7 @@
  */
 import type { CloudProviderId } from './cloud/types.js';
 /** Unique identifier for a supported AI coding agent. */
-export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'amp' | 'kiro' | 'goose' | 'antigravity' | 'grok' | 'kimi' | 'droid';
+export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'amp' | 'kiro' | 'goose' | 'antigravity' | 'grok' | 'kimi' | 'droid' | 'hermes' | 'forge';
 /** How `agents run <agent>` chooses an installed version when none is pinned. */
 export type RunStrategy = 'pinned' | 'available' | 'balanced';
 /** Per-agent run strategy config. */
@@ -148,6 +148,12 @@ export interface AgentConfig {
         subagents: Capability;
         rules: RulesCapability;
         workflows: Capability;
+        /**
+         * Portable knowledge-store memory (`agents memory` / ~/.agents/memory/).
+         * Distinct from `rules` (instructions). When true, sync fans facts into
+         * the agent version home (see memoryTargetDir).
+         */
+        memory: Capability;
         /**
          * Permission modes this agent natively supports. Modes outside this set
          * are gated by buildExecCommand: `auto` silently degrades to `edit`,
@@ -177,7 +183,7 @@ export type RulesCapability = false | {
     file: string;
 };
 /** Names of every gateable capability on AgentConfig. */
-export type CapabilityName = 'hooks' | 'mcp' | 'mcpHttp' | 'mcpHeaders' | 'allowlist' | 'skills' | 'commands' | 'plugins' | 'subagents' | 'rules' | 'workflows';
+export type CapabilityName = 'hooks' | 'mcp' | 'mcpHttp' | 'mcpHeaders' | 'allowlist' | 'skills' | 'commands' | 'plugins' | 'subagents' | 'rules' | 'workflows' | 'memory';
 /**
  * Permission modes controlling agent autonomy.
  *   plan  read-only investigation; no writes, no shell side-effects
@@ -516,6 +522,8 @@ export interface DiscoveredPlugin {
     commands: string[];
     /** Subagent .md files in the plugin's agents/ directory (names without extension). */
     agentDefs: string[];
+    /** Memory fact basenames from the plugin's memory/ directory (without .md). */
+    memory: string[];
     /** Executable files in the plugin's bin/ directory. */
     bin: string[];
     /** MCP server names parsed from .mcp.json. */

package/dist/lib/versions.js

@@ -42,6 +42,7 @@ import { emit } from './events.js';
 import { safeJoin } from './paths.js';
 import { readSkillSourceCommandMarker, shouldInstallCommandAsSkill } from './command-skills.js';
 import { getWriter, getDetector } from './staleness/registry.js';
+import { syncMemoryToVersionHome } from './memory.js';
 /** Promisified exec for running shell commands. */
 const execAsync = promisify(exec);
 const execFileAsync = promisify(execFile);
@@ -1127,19 +1128,28 @@ export async function installVersion(agent, version, onProgress, opts) {
         emit('version.install', { agent, version: installedVersion });
         return { success: true, installedVersion };
     }
-    // Resolve the `oldest` alias to a concrete npm version up front so the rest
-    // of the install path treats it as an ordinary pinned install. (`latest`
-    // keeps its bare-package-name + post-install-rename handling below.)
-    if (version === 'oldest') {
-        const oldest = await getOldestNpmVersion(agent);
-        if (!oldest) {
+    // Resolve the `latest`/`oldest` aliases to a concrete npm version up front so
+    // the rest of the install path treats them as an ordinary pinned install.
+    // This is what keeps concurrent installs safe: resolving `latest` only AFTER
+    // npm finished meant the install ran in a shared, well-known
+    // `versions/<agent>/latest/` scratch dir that was renamed to the real version
+    // at the end — so a concurrent `agents view` reconcile
+    // (reconcileStaleLatestForAgent) or a second `latest` install could rename
+    // that dir out from under npm mid-extraction and corrupt the install (the
+    // seeded package.json and half-extracted node_modules would vanish, yielding
+    // ENOENT). A concrete dir per version has no shared name to race on.
+    if (version === 'latest' || version === 'oldest') {
+        const resolved = version === 'latest'
+            ? await getLatestNpmVersion(agent)
+            : await getOldestNpmVersion(agent);
+        if (!resolved) {
             return {
                 success: false,
                 installedVersion: version,
-                error: `Could not resolve the oldest published version for ${agentConfig.name} from npm.`,
+                error: `Could not resolve the ${version} published version for ${agentConfig.name} from npm.`,
             };
         }
-        version = oldest;
+        version = resolved;
     }
     ensureAgentsDir();
     const versionDir = getVersionDir(agent, version);
@@ -1161,12 +1171,11 @@ export async function installVersion(agent, version, onProgress, opts) {
         private: true,
     };
     fs.writeFileSync(path.join(versionDir, 'package.json'), JSON.stringify(packageJson, null, 2));
-    // Install the package
-    const packageSpec = version === 'latest'
-        ? agentConfig.npmPackage
-        : `${agentConfig.npmPackage}@${version}`;
-    // The `${agentConfig.npmPackage}@` prefix is load-bearing: it ensures `version`
-    // (which VERSION_RE permits to start with `-`) is never passed as a standalone npm CLI flag.
+    // Install the package. `version` is always concrete here (`latest`/`oldest`
+    // were resolved above), so the spec is always pinned. The `@` prefix is
+    // load-bearing: it ensures `version` (which VERSION_RE permits to start with
+    // `-`) is never passed as a standalone npm CLI flag.
+    const packageSpec = `${agentConfig.npmPackage}@${version}`;
     try {
         // Check npm is available
         const winShell = process.platform === 'win32';
@@ -1181,37 +1190,12 @@ export async function installVersion(agent, version, onProgress, opts) {
             };
         }
         onProgress?.(`Installing ${packageSpec}...`);
-        const { stdout } = await execFileAsync('npm', ['install', packageSpec, '--ignore-scripts'], { cwd: versionDir, shell: winShell });
-        // Determine the actual installed version
-        let installedVersion = version;
-        if (version === 'latest') {
-            const pkgJsonPath = path.join(versionDir, 'node_modules', agentConfig.npmPackage.replace(/^@/, '').split('/')[0], 'package.json');
-            // Try to read the actual version from installed package
-            try {
-                const installedPkgPath = path.join(versionDir, 'node_modules', agentConfig.npmPackage, 'package.json');
-                if (fs.existsSync(installedPkgPath)) {
-                    const installedPkg = JSON.parse(fs.readFileSync(installedPkgPath, 'utf-8'));
-                    installedVersion = installedPkg.version;
-                    // Rename the directory to the actual version
-                    if (installedVersion !== 'latest') {
-                        const actualVersionDir = getVersionDir(agent, installedVersion);
-                        if (!fs.existsSync(actualVersionDir)) {
-                            fs.renameSync(versionDir, actualVersionDir);
-                        }
-                        else {
-                            // Already exists — drop the 'latest' install artifacts but keep
-                            // `home/` (may contain conversation history from sessions that
-                            // ran while the user was on `latest`).
-                            removeInstallArtifacts(versionDir);
-                        }
-                    }
-                }
-            }
-            catch (e) {
-                // Failed to determine version - this shouldn't happen
-                throw new Error(`Failed to determine installed version: ${e.message}`);
-            }
-        }
+        await execFileAsync('npm', ['install', packageSpec, '--ignore-scripts'], { cwd: versionDir, shell: winShell });
+        // `version` is concrete (the `latest`/`oldest` aliases were resolved up
+        // front), so the package installed directly into its final versioned dir —
+        // no post-install rename, and no shared `latest/` dir for a concurrent
+        // process to move out from under us.
+        const installedVersion = version;
         // Create versioned alias (e.g., claude@2.0.65)
         createVersionedAlias(agent, installedVersion);
         // Claude reads its global config from CLAUDE_CONFIG_DIR/.claude.json —
@@ -1241,9 +1225,9 @@ export async function installVersion(agent, version, onProgress, opts) {
         // binary (postinstall failed, or a platform with no published native dep)
         // fails there with the correct message rather than throwing here.
         if (agentConfig.npmPackage) {
-            // Recompute from installedVersion, not the (possibly renamed) `versionDir`:
-            // the `latest` branch above may have renamed the dir to its concrete version.
-            const pkgRoot = path.join(getVersionDir(agent, installedVersion), 'node_modules', agentConfig.npmPackage);
+            // `installedVersion === version`, so this is exactly `versionDir` — the
+            // install landed in its final dir with no rename to chase.
+            const pkgRoot = path.join(versionDir, 'node_modules', agentConfig.npmPackage);
             try {
                 const pkg = JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf-8'));
                 const postinstall = pkg?.scripts?.postinstall;
@@ -2335,6 +2319,12 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
         const r = workflowsWriter.write({ version, versionHome, selection: workflowsToSync, cwd });
         result.workflows.push(...r.synced);
     }
+    // Knowledge memory (RUSH-1330) — distinct from selection.memory which still
+    // means the composed *rules* file. Always fan out ~/.agents/memory/ facts
+    // into capable agent version homes on every full or partial sync.
+    if (supports(agent, 'memory', version).ok) {
+        syncMemoryToVersionHome(agent, versionHome, cwd);
+    }
     // Write manifest after a full sync (no user-passed selection) so the next
     // launch can skip the slow path. Pattern-derived selections still count as
     // "full" — the agents.yaml patterns describe the intended scope, not a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.52",
+  "version": "1.20.53",
   "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",
@@ -24,6 +24,7 @@
     "dist/**/*.js",
     "dist/**/*.d.ts",
     "dist/**/*.json",
+    "dist/bin/**",
     "dist/lib/secrets/Agents CLI.app/**",
     "dist/lib/menubar/MenubarHelper.app/**",
     "scripts/postinstall.js",
@@ -44,10 +45,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' && ([ -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": "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) && ([ -f 'bin/agents-macos' ] && mkdir -p dist/bin && cp -f 'bin/agents-macos' 'dist/bin/agents' && chmod 755 'dist/bin/agents' || true)",
     "build:bin": "scripts/build-bin.sh",
     "prepare": "npm run build",
-    "prepack": "cp ../../README.md README.md && 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 && scripts/verify-cli-binary.sh",
     "postinstall": "node scripts/postinstall.js",
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",