@phnx-labs/agents-cli 0.1.0 → 1.14.1

package/dist/lib/state.js

@@ -1,186 +1,366 @@
+/**
+ * Filesystem layout and persistent state for agents-cli.
+ *
+ * Two roots:
+ *  - ~/.agents-system/ — system repo (npm-shipped resources, versions, shims, backups, runs)
+ *  - ~/.agents/        — user repo  (user-authored commands, skills, hooks, rules, mcp,
+ *                                    permissions, subagents, profiles, secrets, agents.yaml)
+ *
+ * Resolution precedence for resources: project > user > system.
+ * Every module that needs a path or reads/writes agents.yaml goes through here.
+ */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as yaml from 'yaml';
+import { SEEDED_REGISTRIES } from './types.js';
 const HOME = os.homedir();
-const AGENTS_DIR = path.join(HOME, '.agents');
-const META_FILE = path.join(AGENTS_DIR, 'agents.yaml');
-const COMMANDS_DIR = path.join(AGENTS_DIR, 'commands');
-const HOOKS_DIR = path.join(AGENTS_DIR, 'hooks');
-const SKILLS_DIR = path.join(AGENTS_DIR, 'skills');
-const MEMORY_DIR = path.join(AGENTS_DIR, 'memory');
-const INSTRUCTIONS_FILE = path.join(AGENTS_DIR, 'instructions.md');
-const PROMPTCUTS_FILE = path.join(AGENTS_DIR, 'promptcuts.yaml');
-const MCP_CONFIG_FILE = path.join(AGENTS_DIR, 'mcp.json');
-const PACKAGES_DIR = path.join(AGENTS_DIR, 'packages');
-const ROUTINES_DIR = path.join(AGENTS_DIR, 'routines');
-const RUNS_DIR = path.join(AGENTS_DIR, 'runs');
-const VERSIONS_DIR = path.join(AGENTS_DIR, 'versions');
-const SHIMS_DIR = path.join(AGENTS_DIR, 'shims');
-const PERMISSIONS_DIR = path.join(AGENTS_DIR, 'permissions');
-const MCP_DIR = path.join(AGENTS_DIR, 'mcp');
-const BACKUPS_DIR = path.join(AGENTS_DIR, 'backups');
-const SUBAGENTS_DIR = path.join(AGENTS_DIR, 'subagents');
-const PLUGINS_DIR = path.join(AGENTS_DIR, 'plugins');
-const DRIVE_DIR = path.join(AGENTS_DIR, 'drive');
-const SECRETS_DIR = path.join(AGENTS_DIR, 'secrets');
+// ─── Root directories ─────────────────────────────────────────────────────────
+/** System repo — npm-shipped, read-only from user commands. */
+const SYSTEM_AGENTS_DIR = path.join(HOME, '.agents-system');
+/** User repo — user-authored resources and agents.yaml. Always-on. */
+const USER_AGENTS_DIR = path.join(HOME, '.agents');
+// ─── Meta file (agents.yaml lives in the user repo) ──────────────────────────
+const META_FILE = path.join(USER_AGENTS_DIR, 'agents.yaml');
+/** Legacy location — used only for one-shot migration in readMeta(). */
+const SYSTEM_META_FILE = path.join(SYSTEM_AGENTS_DIR, 'agents.yaml');
+// ─── System resource dirs ─────────────────────────────────────────────────────
+const SYSTEM_COMMANDS_DIR = path.join(SYSTEM_AGENTS_DIR, 'commands');
+const SYSTEM_HOOKS_DIR = path.join(SYSTEM_AGENTS_DIR, 'hooks');
+const SYSTEM_SKILLS_DIR = path.join(SYSTEM_AGENTS_DIR, 'skills');
+const SYSTEM_RULES_DIR = path.join(SYSTEM_AGENTS_DIR, 'rules');
+const SYSTEM_LEGACY_MEMORY_DIR = path.join(SYSTEM_AGENTS_DIR, 'memory');
+const SYSTEM_MCP_DIR = path.join(SYSTEM_AGENTS_DIR, 'mcp');
+const SYSTEM_PERMISSIONS_DIR = path.join(SYSTEM_AGENTS_DIR, 'permissions');
+const SYSTEM_SUBAGENTS_DIR = path.join(SYSTEM_AGENTS_DIR, 'subagents');
+const SYSTEM_SECRETS_DIR = path.join(SYSTEM_AGENTS_DIR, 'secrets');
+const SYSTEM_PROMPTCUTS_FILE = path.join(SYSTEM_AGENTS_DIR, 'hooks', 'promptcuts.yaml');
+const SYSTEM_MCP_CONFIG_FILE = path.join(SYSTEM_AGENTS_DIR, 'mcp.json');
+const SYSTEM_INSTRUCTIONS_FILE = path.join(SYSTEM_AGENTS_DIR, 'instructions.md');
+// System-only paths (never duplicated in user repo)
+const PACKAGES_DIR = path.join(SYSTEM_AGENTS_DIR, 'packages');
+const ROUTINES_DIR = path.join(SYSTEM_AGENTS_DIR, 'routines');
+const RUNS_DIR = path.join(SYSTEM_AGENTS_DIR, 'runs');
+const VERSIONS_DIR = path.join(SYSTEM_AGENTS_DIR, 'versions');
+const SHIMS_DIR = path.join(SYSTEM_AGENTS_DIR, 'shims');
+const BACKUPS_DIR = path.join(SYSTEM_AGENTS_DIR, 'backups');
+const PLUGINS_DIR = path.join(SYSTEM_AGENTS_DIR, 'plugins');
+const DRIVE_DIR = path.join(SYSTEM_AGENTS_DIR, 'drive');
+// ─── User resource dirs ───────────────────────────────────────────────────────
+const USER_COMMANDS_DIR = path.join(USER_AGENTS_DIR, 'commands');
+const USER_HOOKS_DIR = path.join(USER_AGENTS_DIR, 'hooks');
+const USER_SKILLS_DIR = path.join(USER_AGENTS_DIR, 'skills');
+const USER_RULES_DIR = path.join(USER_AGENTS_DIR, 'rules');
+const USER_MCP_DIR = path.join(USER_AGENTS_DIR, 'mcp');
+const USER_PERMISSIONS_DIR = path.join(USER_AGENTS_DIR, 'permissions');
+const USER_SUBAGENTS_DIR = path.join(USER_AGENTS_DIR, 'subagents');
+const USER_SECRETS_DIR = path.join(USER_AGENTS_DIR, 'secrets');
+const USER_PROMPTCUTS_FILE = path.join(USER_AGENTS_DIR, 'hooks', 'promptcuts.yaml');
 const META_HEADER = `# agents-cli metadata
 # Auto-generated - do not edit manually
-# https://github.com/muqsitnawaz/agents-cli
+# https://github.com/phnx-labs/agents-cli
 
 `;
+// ─── Root getters ─────────────────────────────────────────────────────────────
+/** Root of the system data directory (~/.agents-system/). Legacy alias — prefer getSystemAgentsDir(). */
 export function getAgentsDir() {
-    return AGENTS_DIR;
+    return SYSTEM_AGENTS_DIR;
+}
+/** Root of the system data directory (~/.agents-system/). */
+export function getSystemAgentsDir() {
+    return SYSTEM_AGENTS_DIR;
+}
+/** Root of the user repo (~/.agents/). Always present after ensureAgentsDir(). */
+export function getUserAgentsDir() {
+    return USER_AGENTS_DIR;
+}
+/**
+ * Backward-compat shim. Returns null when ~/.agents/ is a symlink to the
+ * system dir; otherwise returns USER_AGENTS_DIR.
+ *
+ * @deprecated Use getUserAgentsDir() directly.
+ */
+export function getOptionalUserAgentsDir() {
+    if (fs.existsSync(USER_AGENTS_DIR)) {
+        try {
+            const stat = fs.lstatSync(USER_AGENTS_DIR);
+            if (stat.isSymbolicLink()) {
+                try {
+                    if (fs.realpathSync(USER_AGENTS_DIR) === fs.realpathSync(SYSTEM_AGENTS_DIR))
+                        return null;
+                }
+                catch {
+                    return null;
+                }
+            }
+        }
+        catch { /* dir may not exist yet */ }
+    }
+    return USER_AGENTS_DIR;
 }
+/** Walk up from startPath to find a project-scoped .agents/ directory (skipping both roots). */
 export function getProjectAgentsDir(startPath = process.cwd()) {
     let dir = path.resolve(startPath);
     while (true) {
         const agentsPath = path.join(dir, '.agents');
         if (fs.existsSync(agentsPath) && fs.statSync(agentsPath).isDirectory()) {
-            // Skip if this is ~/.agents (user scope, not project scope)
-            if (agentsPath !== AGENTS_DIR) {
+            if (agentsPath !== SYSTEM_AGENTS_DIR && agentsPath !== USER_AGENTS_DIR) {
                 return agentsPath;
             }
         }
         const isProjectBoundary = fs.existsSync(path.join(dir, '.git')) || fs.existsSync(path.join(dir, 'agents.yaml'));
         const parent = path.dirname(dir);
-        if (parent === dir) {
+        if (parent === dir)
             break;
-        }
-        if (isProjectBoundary) {
-            // Check this boundary dir but don't go further
+        if (isProjectBoundary)
             break;
-        }
         dir = parent;
     }
     return null;
 }
+/** Return all .agents/ directories in scope: project, user, then system. */
 export function getScopedAgentsDirs(startPath = process.cwd()) {
     const dirs = [];
     const projectDir = getProjectAgentsDir(startPath);
     if (projectDir) {
         dirs.push({ scope: 'project', path: projectDir });
     }
-    dirs.push({ scope: 'user', path: AGENTS_DIR });
+    dirs.push({ scope: 'user', path: USER_AGENTS_DIR });
+    dirs.push({ scope: 'system', path: SYSTEM_AGENTS_DIR });
     return dirs;
 }
-export function getPackagesDir() {
-    return PACKAGES_DIR;
-}
-export function getRoutinesDir() {
-    return ROUTINES_DIR;
-}
-export function getRunsDir() {
-    return RUNS_DIR;
-}
-export function getVersionsDir() {
-    return VERSIONS_DIR;
-}
-export function getShimsDir() {
-    return SHIMS_DIR;
-}
-export function getPermissionsDir() {
-    return PERMISSIONS_DIR;
-}
-export function getMcpDir() {
-    return MCP_DIR;
-}
-export function getBackupsDir() {
-    return BACKUPS_DIR;
-}
-export function getSubagentsDir() {
-    return SUBAGENTS_DIR;
-}
-export function getPluginsDir() {
-    return PLUGINS_DIR;
-}
-export function getDriveDir() {
-    return DRIVE_DIR;
-}
-export function getSecretsDir() {
-    return SECRETS_DIR;
-}
-export function getCommandsDir() {
-    return COMMANDS_DIR;
-}
-export function getHooksDir() {
-    return HOOKS_DIR;
-}
-export function getSkillsDir() {
-    return SKILLS_DIR;
+// ─── System resource getters (legacy aliases for read/sync paths) ─────────────
+/** Path to slash command markdown files — system repo. */
+export function getCommandsDir() { return SYSTEM_COMMANDS_DIR; }
+/** Path to hook script directories — system repo. */
+export function getHooksDir() { return SYSTEM_HOOKS_DIR; }
+/** Path to skill bundles — system repo. */
+export function getSkillsDir() { return SYSTEM_SKILLS_DIR; }
+/** Path to the canonical rules directory — system repo. */
+export function getRulesDir() { return SYSTEM_RULES_DIR; }
+/** Back-compat export; resolves to system rules dir. */
+export function getMemoryDir() { return SYSTEM_RULES_DIR; }
+let legacyMemoryWarned = false;
+/**
+ * Read-side resolution for the canonical rules dir.
+ *
+ * Returns SYSTEM_RULES_DIR normally. Falls back to the legacy
+ * SYSTEM_LEGACY_MEMORY_DIR (~/.agents-system/memory/) only when the upstream
+ * still uses the old layout and the user hasn't pulled the rename yet —
+ * detected by absence of rules/AGENTS.md and presence of memory/AGENTS.md.
+ *
+ * Prints a single warning per process the first time the fallback fires.
+ * Per the read-only system-repo invariant, this never moves files; the rename
+ * is applied when the user pulls upstream.
+ */
+export function getResolvedRulesDir() {
+    const rulesAgents = path.join(SYSTEM_RULES_DIR, 'AGENTS.md');
+    const legacyAgents = path.join(SYSTEM_LEGACY_MEMORY_DIR, 'AGENTS.md');
+    if (fs.existsSync(rulesAgents))
+        return SYSTEM_RULES_DIR;
+    if (fs.existsSync(legacyAgents)) {
+        if (!legacyMemoryWarned) {
+            legacyMemoryWarned = true;
+            process.stderr.write('agents-cli: Legacy memory/ directory detected — agents-cli still works, ' +
+                "but run 'agents repo pull system' to migrate to rules/.\n");
+        }
+        return SYSTEM_LEGACY_MEMORY_DIR;
+    }
+    return SYSTEM_RULES_DIR;
 }
-export function getMemoryDir() {
-    return MEMORY_DIR;
+/** Path to MCP server YAML configs — system repo. */
+export function getMcpDir() { return SYSTEM_MCP_DIR; }
+/** Path to permission group YAML files — system repo. */
+export function getPermissionsDir() { return SYSTEM_PERMISSIONS_DIR; }
+/** Path to subagent definition directories — system repo. */
+export function getSubagentsDir() { return SYSTEM_SUBAGENTS_DIR; }
+/** Path to encrypted secret bundles — system repo. */
+export function getSecretsDir() { return SYSTEM_SECRETS_DIR; }
+/** Path to ~/.agents-system/promptcuts.yaml. */
+export function getPromptcutsPath() { return SYSTEM_PROMPTCUTS_FILE; }
+/** Path to the legacy MCP config JSON. */
+export function getMcpConfigPath() { return SYSTEM_MCP_CONFIG_FILE; }
+/** Path to the global instructions file. */
+export function getInstructionsPath() { return SYSTEM_INSTRUCTIONS_FILE; }
+// ─── System-specific getters ───────────────────────────────────────────────────
+export function getSystemCommandsDir() { return SYSTEM_COMMANDS_DIR; }
+export function getSystemHooksDir() { return SYSTEM_HOOKS_DIR; }
+export function getSystemSkillsDir() { return SYSTEM_SKILLS_DIR; }
+export function getSystemRulesDir() { return SYSTEM_RULES_DIR; }
+export function getSystemMcpDir() { return SYSTEM_MCP_DIR; }
+export function getSystemPermissionsDir() { return SYSTEM_PERMISSIONS_DIR; }
+export function getSystemSubagentsDir() { return SYSTEM_SUBAGENTS_DIR; }
+export function getSystemSecretsDir() { return SYSTEM_SECRETS_DIR; }
+export function getSystemPromptcutsPath() { return SYSTEM_PROMPTCUTS_FILE; }
+// ─── User resource getters ────────────────────────────────────────────────────
+export function getUserCommandsDir() { return USER_COMMANDS_DIR; }
+export function getUserHooksDir() { return USER_HOOKS_DIR; }
+export function getUserSkillsDir() { return USER_SKILLS_DIR; }
+export function getUserRulesDir() { return USER_RULES_DIR; }
+export function getUserMcpDir() { return USER_MCP_DIR; }
+export function getUserPermissionsDir() { return USER_PERMISSIONS_DIR; }
+export function getUserSubagentsDir() { return USER_SUBAGENTS_DIR; }
+export function getUserSecretsDir() { return USER_SECRETS_DIR; }
+export function getUserPromptcutsPath() { return USER_PROMPTCUTS_FILE; }
+// ─── System-only path getters ─────────────────────────────────────────────────
+/** Path to cloned packages (~/.agents-system/packages/). */
+export function getPackagesDir() { return PACKAGES_DIR; }
+/** Path to routine YAML definitions (~/.agents-system/routines/). */
+export function getRoutinesDir() { return ROUTINES_DIR; }
+/** Path to routine execution logs (~/.agents-system/runs/). */
+export function getRunsDir() { return RUNS_DIR; }
+/** Path to installed agent CLI binaries (~/.agents-system/versions/). */
+export function getVersionsDir() { return VERSIONS_DIR; }
+/** Path to version-switching shim scripts (~/.agents-system/shims/). */
+export function getShimsDir() { return SHIMS_DIR; }
+/** Path to config backups (~/.agents-system/backups/). */
+export function getBackupsDir() { return BACKUPS_DIR; }
+/** Path to plugin bundles (~/.agents-system/plugins/). */
+export function getPluginsDir() { return PLUGINS_DIR; }
+/** Path to synced remote session data (~/.agents-system/drive/). */
+export function getDriveDir() { return DRIVE_DIR; }
+/**
+ * Path to a single user-level extra DotAgent repo clone (~/.agents-<alias>/).
+ *
+ * Extra repos are user-defined config — they live as peer dirs to ~/.agents/,
+ * not under the system repo. `agents repo add` clones here by default.
+ */
+export function getExtraRepoDir(alias) {
+    return path.join(HOME, `.agents-${alias}`);
 }
-export function getInstructionsPath() {
-    return INSTRUCTIONS_FILE;
+/** Resolve the on-disk path for an extra repo, whether managed or user-owned. */
+export function resolveExtraRepoDir(alias, config) {
+    if (config?.path) {
+        return path.resolve(config.path);
+    }
+    return getExtraRepoDir(alias);
 }
 /**
- * Path to ~/.agents/promptcuts.yaml — the canonical, version-independent
- * source for prompt shortcuts. The expand-promptcuts hook reads directly
- * from this file, so it survives agent-version upgrades without any sync.
+ * Return enabled extra repos that exist on disk, in insertion order.
  */
-export function getPromptcutsPath() {
-    return PROMPTCUTS_FILE;
-}
-export function getMcpConfigPath() {
-    return MCP_CONFIG_FILE;
+export function getEnabledExtraRepos() {
+    const meta = readMeta();
+    const extras = meta.extraRepos || {};
+    const out = [];
+    for (const [alias, config] of Object.entries(extras)) {
+        if (!config.enabled)
+            continue;
+        const dir = resolveExtraRepoDir(alias, config);
+        if (!fs.existsSync(dir))
+            continue;
+        out.push({ alias, dir, url: config.url });
+    }
+    return out;
 }
+// ─── Directory setup ───────────────────────────────────────────────────────────
+/** Create both the system and user directory trees if any subdirectories are missing. */
 export function ensureAgentsDir() {
-    if (!fs.existsSync(AGENTS_DIR)) {
-        fs.mkdirSync(AGENTS_DIR, { recursive: true });
-    }
-    if (!fs.existsSync(PACKAGES_DIR)) {
-        fs.mkdirSync(PACKAGES_DIR, { recursive: true });
-    }
-    if (!fs.existsSync(ROUTINES_DIR)) {
-        fs.mkdirSync(ROUTINES_DIR, { recursive: true });
-    }
-    if (!fs.existsSync(RUNS_DIR)) {
-        fs.mkdirSync(RUNS_DIR, { recursive: true });
-    }
-    if (!fs.existsSync(VERSIONS_DIR)) {
-        fs.mkdirSync(VERSIONS_DIR, { recursive: true });
-    }
-    if (!fs.existsSync(SHIMS_DIR)) {
-        fs.mkdirSync(SHIMS_DIR, { recursive: true });
-    }
-    if (!fs.existsSync(COMMANDS_DIR)) {
-        fs.mkdirSync(COMMANDS_DIR, { recursive: true });
+    const opts = { recursive: true, mode: 0o700 };
+    // User repo — minimal scaffold (sub-dirs created on first write)
+    if (!fs.existsSync(USER_AGENTS_DIR)) {
+        fs.mkdirSync(USER_AGENTS_DIR, opts);
     }
-    if (!fs.existsSync(HOOKS_DIR)) {
-        fs.mkdirSync(HOOKS_DIR, { recursive: true });
+    try {
+        fs.chmodSync(USER_AGENTS_DIR, 0o700);
     }
-    if (!fs.existsSync(SKILLS_DIR)) {
-        fs.mkdirSync(SKILLS_DIR, { recursive: true });
+    catch { }
+    // System repo
+    if (!fs.existsSync(SYSTEM_AGENTS_DIR)) {
+        fs.mkdirSync(SYSTEM_AGENTS_DIR, opts);
     }
-    if (!fs.existsSync(MEMORY_DIR)) {
-        fs.mkdirSync(MEMORY_DIR, { recursive: true });
-    }
-    if (!fs.existsSync(PERMISSIONS_DIR)) {
-        fs.mkdirSync(PERMISSIONS_DIR, { recursive: true });
-    }
-    if (!fs.existsSync(SUBAGENTS_DIR)) {
-        fs.mkdirSync(SUBAGENTS_DIR, { recursive: true });
-    }
-    if (!fs.existsSync(DRIVE_DIR)) {
-        fs.mkdirSync(DRIVE_DIR, { recursive: true });
+    if (!fs.existsSync(PACKAGES_DIR))
+        fs.mkdirSync(PACKAGES_DIR, opts);
+    if (!fs.existsSync(ROUTINES_DIR))
+        fs.mkdirSync(ROUTINES_DIR, opts);
+    if (!fs.existsSync(RUNS_DIR))
+        fs.mkdirSync(RUNS_DIR, opts);
+    if (!fs.existsSync(VERSIONS_DIR))
+        fs.mkdirSync(VERSIONS_DIR, opts);
+    if (!fs.existsSync(SHIMS_DIR))
+        fs.mkdirSync(SHIMS_DIR, opts);
+    if (!fs.existsSync(SYSTEM_COMMANDS_DIR))
+        fs.mkdirSync(SYSTEM_COMMANDS_DIR, opts);
+    if (!fs.existsSync(SYSTEM_HOOKS_DIR))
+        fs.mkdirSync(SYSTEM_HOOKS_DIR, opts);
+    if (!fs.existsSync(SYSTEM_SKILLS_DIR))
+        fs.mkdirSync(SYSTEM_SKILLS_DIR, opts);
+    if (!fs.existsSync(SYSTEM_RULES_DIR))
+        fs.mkdirSync(SYSTEM_RULES_DIR, opts);
+    if (!fs.existsSync(SYSTEM_PERMISSIONS_DIR))
+        fs.mkdirSync(SYSTEM_PERMISSIONS_DIR, opts);
+    if (!fs.existsSync(SYSTEM_SUBAGENTS_DIR))
+        fs.mkdirSync(SYSTEM_SUBAGENTS_DIR, opts);
+    if (!fs.existsSync(DRIVE_DIR))
+        fs.mkdirSync(DRIVE_DIR, opts);
+    try {
+        fs.chmodSync(SYSTEM_AGENTS_DIR, 0o700);
     }
+    catch { }
 }
+// ─── Meta (agents.yaml) ────────────────────────────────────────────────────────
+/** Return an empty Meta object used when no agents.yaml exists yet. */
 export function createDefaultMeta() {
     return {};
 }
 let metaCache = null;
+function applyRegistrySeeds(meta) {
+    const seeded = new Set(meta.seededPresets || []);
+    let changed = false;
+    for (const [type, presets] of Object.entries(SEEDED_REGISTRIES)) {
+        for (const [name, config] of Object.entries(presets)) {
+            const key = `${type}.${name}`;
+            if (seeded.has(key))
+                continue;
+            if (!meta.registries)
+                meta.registries = { mcp: {}, skill: {} };
+            if (!meta.registries[type])
+                meta.registries[type] = {};
+            if (!meta.registries[type][name]) {
+                meta.registries[type][name] = { ...config };
+            }
+            seeded.add(key);
+            changed = true;
+        }
+    }
+    if (changed)
+        meta.seededPresets = [...seeded];
+    return changed;
+}
+/**
+ * One-shot migration: move agents.yaml from system repo to user repo.
+ * Idempotent — no-ops if user file already exists or system file absent.
+ */
+function migrateSystemMetaToUser() {
+    if (fs.existsSync(META_FILE))
+        return;
+    if (!fs.existsSync(SYSTEM_META_FILE))
+        return;
+    try {
+        if (!fs.existsSync(USER_AGENTS_DIR)) {
+            fs.mkdirSync(USER_AGENTS_DIR, { recursive: true, mode: 0o700 });
+        }
+        fs.renameSync(SYSTEM_META_FILE, META_FILE);
+        console.log('Migrated agents.yaml to ~/.agents/');
+    }
+    catch {
+        // Best-effort; proceed with fresh state if it fails.
+    }
+}
+/** Read and cache ~/.agents/agents.yaml, migrating from legacy locations if needed. */
 export function readMeta() {
     ensureAgentsDir();
-    // Migration: check for old meta.yaml
-    const oldMetaFile = path.join(AGENTS_DIR, 'meta.yaml');
+    // NOTE: agents.yaml migration from ~/.agents-system/ to ~/.agents/ is handled
+    // exclusively by runMigration() in migrate.ts, called from postinstall and
+    // explicit command-time fallbacks (agents view/use/pull). Calling it here
+    // would mutate real-user filesystem state during test runs that import this
+    // module, causing cross-test pollution.
+    // Legacy migration: check for old meta.yaml in system dir
+    const oldMetaFile = path.join(SYSTEM_AGENTS_DIR, 'meta.yaml');
     if (fs.existsSync(oldMetaFile) && !fs.existsSync(META_FILE)) {
         try {
             const content = fs.readFileSync(oldMetaFile, 'utf-8');
             const parsed = yaml.parse(content);
             const meta = {};
-            // Migrate versions.*.default -> agents.*
             if (parsed.versions) {
                 meta.agents = {};
                 for (const [agent, state] of Object.entries(parsed.versions)) {
@@ -190,20 +370,18 @@ export function readMeta() {
                     }
                 }
             }
-            // Migrate registries
             if (parsed.registries) {
                 meta.registries = parsed.registries;
             }
             writeMeta(meta);
-            // Remove old meta.yaml to prevent stale reads by shims
             try {
                 fs.unlinkSync(oldMetaFile);
             }
-            catch { /* old meta file cleanup, non-critical */ }
+            catch { /* non-critical */ }
             return meta;
         }
         catch {
-            /* meta.yaml migration failed, continue with fresh state */
+            /* meta.yaml migration failed */
         }
     }
     if (fs.existsSync(META_FILE)) {
@@ -211,9 +389,7 @@ export function readMeta() {
         try {
             mtime = fs.statSync(META_FILE).mtimeMs;
         }
-        catch {
-            /* file vanished between existsSync and statSync */
-        }
+        catch { /* file vanished */ }
         if (metaCache && metaCache.mtime === mtime) {
             return metaCache.meta;
         }
@@ -221,28 +397,38 @@ export function readMeta() {
             const content = fs.readFileSync(META_FILE, 'utf-8');
             const parsed = yaml.parse(content);
             const meta = parsed || createDefaultMeta();
+            if (applyRegistrySeeds(meta)) {
+                writeMeta(meta);
+                return meta;
+            }
             metaCache = { mtime, meta };
             return meta;
         }
         catch {
-            /* agents.yaml corrupt or unreadable, use defaults */
             return createDefaultMeta();
         }
     }
-    return createDefaultMeta();
+    const meta = createDefaultMeta();
+    if (applyRegistrySeeds(meta)) {
+        writeMeta(meta);
+    }
+    return meta;
 }
+/** Serialize and write agents.yaml to the user repo, invalidating the in-memory cache. */
 export function writeMeta(meta) {
     ensureAgentsDir();
     const content = META_HEADER + yaml.stringify(meta);
     fs.writeFileSync(META_FILE, content, 'utf-8');
     metaCache = null;
 }
+/** Shallow-merge updates into agents.yaml and return the new state. */
 export function updateMeta(updates) {
     const meta = readMeta();
     const newMeta = { ...meta, ...updates };
     writeMeta(newMeta);
     return newMeta;
 }
+/** Derive a filesystem-safe local clone path for a package source URL. */
 export function getPackageLocalPath(source) {
     const sanitized = source
         .replace(/^gh:/, '')
@@ -251,11 +437,6 @@ export function getPackageLocalPath(source) {
         .replace(/\//g, '-');
     return path.join(PACKAGES_DIR, sanitized);
 }
-/**
- * Record that resources were synced to a specific version.
- * Creates nested entries if they don't exist (handles existing installs gracefully).
- * Merges with existing resources (uses Set for deduplication).
- */
 export function recordVersionResources(agent, version, resourceType, resources) {
     if (resources.length === 0)
         return;
@@ -271,29 +452,20 @@ export function recordVersionResources(agent, version, resourceType, resources)
     meta.versions[agent][version][resourceType] = merged;
     writeMeta(meta);
 }
-/**
- * Get tracked resources for a specific version.
- */
 export function getVersionResources(agent, version) {
     const meta = readMeta();
     return meta.versions?.[agent]?.[version] || null;
 }
-/**
- * Clear resource tracking when a version is removed.
- */
 export function clearVersionResources(agent, version) {
     const meta = readMeta();
     if (meta.versions?.[agent]?.[version]) {
         delete meta.versions[agent][version];
-        // Clean up empty agent entry
         if (Object.keys(meta.versions[agent]).length === 0) {
             delete meta.versions[agent];
         }
-        // Clean up empty versions section
         if (Object.keys(meta.versions).length === 0) {
             delete meta.versions;
         }
         writeMeta(meta);
     }
 }
-//# sourceMappingURL=state.js.map

package/dist/lib/subagents.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Subagent management -- discovery, installation, and format conversion.
+ *
+ * Subagents are named agent definitions in ~/.agents/subagents/, each a directory
+ * with an agent.md file (frontmatter + instructions). This module discovers them,
+ * transforms them into agent-native formats (Claude .mdc, OpenClaw YAML),
+ * and syncs them into version homes.
+ */
 import type { AgentId, DiscoveredSubagent, InstalledSubagent, SubagentFrontmatter } from './types.js';
 /**
  * Parse AGENT.md frontmatter to extract subagent metadata
@@ -65,6 +73,7 @@ export declare function removeSubagentFromAgent(subagentName: string, agent: Age
  * Check if subagent content matches between source and installed
  */
 export declare function subagentContentMatches(installedDir: string, sourceDir: string): boolean;
+/** Agents that support the subagent system (Claude via flattened .md, OpenClaw via directory copy). */
 export declare const SUBAGENT_CAPABLE_AGENTS: AgentId[];
 /**
  * List subagents installed to a specific agent's home
@@ -72,4 +81,3 @@ export declare const SUBAGENT_CAPABLE_AGENTS: AgentId[];
  * OpenClaw: scans ~/.openclaw/{name}/AGENTS.md
  */
 export declare function listSubagentsForAgent(agentId: AgentId, home: string): InstalledSubagent[];
-//# sourceMappingURL=subagents.d.ts.map