@phnx-labs/agents-cli 1.15.0 → 1.17.0

package/dist/lib/migrate.js

@@ -7,9 +7,12 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-const HOME = os.homedir();
+import * as yaml from 'yaml';
+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');
+const CACHE_DIR = path.join(USER_DIR, '.cache');
 /**
  * Move ~/.agents-system/agents.yaml -> ~/.agents/agents.yaml.
  * No-op if user file already exists or system file absent.
@@ -19,12 +22,22 @@ const USER_DIR = path.join(HOME, '.agents');
 function migrateAgentsYaml() {
     const src = path.join(SYSTEM_DIR, 'agents.yaml');
     const dest = path.join(USER_DIR, 'agents.yaml');
-    if (fs.existsSync(dest) || !fs.existsSync(src))
+    if (!fs.existsSync(src))
+        return;
+    if (fs.existsSync(dest)) {
+        // User copy is authoritative — drop the stale system leftover. The system
+        // repo (npm-shipped) does not track agents.yaml; any copy here is residue
+        // from the pre-split layout.
+        try {
+            fs.unlinkSync(src);
+        }
+        catch { /* best-effort */ }
         return;
+    }
     try {
         fs.mkdirSync(USER_DIR, { recursive: true, mode: 0o700 });
         fs.renameSync(src, dest);
-        console.log('Migrated agents.yaml to ~/.agents/');
+        console.error('Migrated agents.yaml to ~/.agents/');
     }
     catch { /* best-effort */ }
 }
@@ -77,28 +90,32 @@ function migratePromptcutsIntoHooks() {
     }
 }
 /**
- * Move installed agent versions from the legacy single-root layout
- * (~/.agents/versions/<agent>/<ver>/) into the system root
- * (~/.agents-system/versions/<agent>/<ver>/).
+ * Move installed agent versions from the legacy system-root layout
+ * (~/.agents-system/versions/<agent>/<ver>/) into the user root
+ * (~/.agents/versions/<agent>/<ver>/).
  *
- * Pre-split installs put binaries and home dirs under ~/.agents/. After the
- * split, the system code only scans ~/.agents-system/versions/, so without
- * this migration the versions become invisible to listInstalledVersions and
- * every command that depends on it (view, prune, run).
+ * Earlier installs (and an inverted prior version of this migrator) put
+ * binaries and home dirs under ~/.agents-system/. The current architecture
+ * keeps all operational state (versions, sessions, shims, trash) under
+ * ~/.agents/, and getVersionsDir() in state.ts resolves there. Without this
+ * migration the legacy versions become invisible to listInstalledVersions
+ * and every command that depends on it (view, prune, run, sync) writes a
+ * second copy to ~/.agents/versions/ while the agent CLIs keep reading the
+ * stale ~/.agents-system/versions/ copy via the existing ~/.<agent> symlink.
  *
  * Idempotent and non-destructive: if a same-named dest already exists we
  * leave the legacy copy in place so the user can reconcile manually.
  */
-function migrateUserVersionsToSystem() {
-    const userVersions = path.join(USER_DIR, 'versions');
+function migrateSystemVersionsToUser() {
     const sysVersions = path.join(SYSTEM_DIR, 'versions');
-    if (!fs.existsSync(userVersions))
+    const userVersions = path.join(USER_DIR, 'versions');
+    if (!fs.existsSync(sysVersions))
         return;
     let movedCount = 0;
     let skippedCount = 0;
     let agentEntries;
     try {
-        agentEntries = fs.readdirSync(userVersions, { withFileTypes: true });
+        agentEntries = fs.readdirSync(sysVersions, { withFileTypes: true });
     }
     catch {
         return;
@@ -106,8 +123,8 @@ function migrateUserVersionsToSystem() {
     for (const agent of agentEntries) {
         if (!agent.isDirectory())
             continue;
-        const srcAgentDir = path.join(userVersions, agent.name);
-        const dstAgentDir = path.join(sysVersions, agent.name);
+        const srcAgentDir = path.join(sysVersions, agent.name);
+        const dstAgentDir = path.join(userVersions, agent.name);
         try {
             fs.mkdirSync(dstAgentDir, { recursive: true, mode: 0o700 });
         }
@@ -141,15 +158,15 @@ function migrateUserVersionsToSystem() {
         catch { /* best-effort */ }
     }
     try {
-        if (fs.readdirSync(userVersions).length === 0)
-            fs.rmdirSync(userVersions);
+        if (fs.readdirSync(sysVersions).length === 0)
+            fs.rmdirSync(sysVersions);
     }
     catch { /* best-effort */ }
     if (movedCount > 0) {
-        console.log(`Migrated ${movedCount} version dir${movedCount === 1 ? '' : 's'} from ~/.agents/versions/ to ~/.agents-system/versions/`);
+        console.error(`Migrated ${movedCount} version dir${movedCount === 1 ? '' : 's'} from ~/.agents-system/versions/ to ~/.agents/versions/`);
     }
     if (skippedCount > 0) {
-        console.log(`Skipped ${skippedCount} version dir${skippedCount === 1 ? '' : 's'} already present in ~/.agents-system/versions/ (kept legacy copy at ~/.agents/versions/)`);
+        console.error(`Skipped ${skippedCount} version dir${skippedCount === 1 ? '' : 's'} already present in ~/.agents/versions/ (kept legacy copy at ~/.agents-system/versions/)`);
     }
 }
 /**
@@ -195,14 +212,1212 @@ function migrateBackupsToHidden() {
     }
     catch { /* best-effort */ }
 }
+/**
+ * Fold ~/.agents/hooks.yaml into ~/.agents/agents.yaml under a `hooks:` key,
+ * then delete the standalone hooks.yaml. Single user file to sync.
+ *
+ * On collision (a hook name already exists in agents.yaml hooks:), the
+ * existing agents.yaml entry wins and the standalone copy is dropped — this
+ * matches the behavior a user would get if they had already migrated
+ * manually and edited agents.yaml.
+ *
+ * Idempotent: skips if hooks.yaml is absent or unparseable.
+ */
+function foldUserHooksYamlIntoAgentsYaml() {
+    const hooksFile = path.join(USER_DIR, 'hooks.yaml');
+    if (!fs.existsSync(hooksFile))
+        return;
+    let hooks;
+    try {
+        const raw = fs.readFileSync(hooksFile, 'utf-8');
+        const parsed = yaml.parse(raw);
+        hooks = parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return;
+    }
+    const metaFile = path.join(USER_DIR, 'agents.yaml');
+    let meta = {};
+    if (fs.existsSync(metaFile)) {
+        try {
+            const raw = fs.readFileSync(metaFile, 'utf-8');
+            const parsed = yaml.parse(raw);
+            if (parsed && typeof parsed === 'object')
+                meta = parsed;
+        }
+        catch {
+            return;
+        }
+    }
+    const existingHooks = meta.hooks ?? {};
+    const merged = { ...hooks, ...existingHooks };
+    meta.hooks = merged;
+    const header = `# agents-cli metadata
+# Auto-generated - do not edit manually
+# https://github.com/phnx-labs/agents-cli
+
+`;
+    try {
+        fs.mkdirSync(USER_DIR, { recursive: true, mode: 0o700 });
+        fs.writeFileSync(metaFile, header + yaml.stringify(meta), 'utf-8');
+        fs.unlinkSync(hooksFile);
+        console.error('Folded ~/.agents/hooks.yaml into ~/.agents/agents.yaml (hooks: section)');
+    }
+    catch { /* best-effort */ }
+}
+/**
+ * Fold ~/.agents/browser/profiles/*.yaml into ~/.agents/agents.yaml under a
+ * `browser:` key, then delete the profiles directory. Single user file to sync.
+ *
+ * On collision (a profile name already exists in agents.yaml browser:), the
+ * existing agents.yaml entry wins and the standalone copy is dropped.
+ *
+ * Idempotent: skips if profiles dir is absent or empty.
+ */
+function foldBrowserProfilesIntoAgentsYaml() {
+    const profilesDir = path.join(USER_DIR, 'browser', 'profiles');
+    if (!fs.existsSync(profilesDir))
+        return;
+    let files;
+    try {
+        files = fs.readdirSync(profilesDir).filter((f) => f.endsWith('.yaml'));
+    }
+    catch {
+        return;
+    }
+    if (files.length === 0)
+        return;
+    const profiles = {};
+    for (const file of files) {
+        try {
+            const raw = fs.readFileSync(path.join(profilesDir, file), 'utf-8');
+            const parsed = yaml.parse(raw);
+            if (!parsed || typeof parsed !== 'object')
+                continue;
+            const name = parsed.name || file.replace(/\.yaml$/, '');
+            const { name: _, ...config } = parsed;
+            profiles[name] = config;
+        }
+        catch { /* skip unreadable file */ }
+    }
+    if (Object.keys(profiles).length === 0)
+        return;
+    const metaFile = path.join(USER_DIR, 'agents.yaml');
+    let meta = {};
+    if (fs.existsSync(metaFile)) {
+        try {
+            const raw = fs.readFileSync(metaFile, 'utf-8');
+            const parsed = yaml.parse(raw);
+            if (parsed && typeof parsed === 'object')
+                meta = parsed;
+        }
+        catch {
+            return;
+        }
+    }
+    const existingBrowser = meta.browser ?? {};
+    const merged = { ...profiles, ...existingBrowser };
+    meta.browser = merged;
+    const header = `# agents-cli metadata
+# Auto-generated - do not edit manually
+# https://github.com/phnx-labs/agents-cli
+
+`;
+    try {
+        fs.mkdirSync(USER_DIR, { recursive: true, mode: 0o700 });
+        fs.writeFileSync(metaFile, header + yaml.stringify(meta), 'utf-8');
+        for (const file of files) {
+            try {
+                fs.unlinkSync(path.join(profilesDir, file));
+            }
+            catch { /* best-effort */ }
+        }
+        try {
+            fs.rmdirSync(profilesDir);
+        }
+        catch { /* may not be empty */ }
+        try {
+            const browserDir = path.join(USER_DIR, 'browser');
+            if (fs.existsSync(browserDir) && fs.readdirSync(browserDir).length === 0) {
+                fs.rmdirSync(browserDir);
+            }
+        }
+        catch { /* best-effort */ }
+        console.error('Folded ~/.agents/browser/profiles/ into ~/.agents/agents.yaml (browser: section)');
+    }
+    catch { /* best-effort */ }
+}
+/**
+ * Delete ~/.agents/linear.json. The linear-cli now manages its own
+ * credentials in the OS keychain; this file was a legacy plaintext store.
+ */
+function deleteUserLinearJson() {
+    const f = path.join(USER_DIR, 'linear.json');
+    if (!fs.existsSync(f))
+        return;
+    try {
+        fs.unlinkSync(f);
+    }
+    catch { /* best-effort */ }
+}
+/**
+ * Delete ~/.agents/prompts.json. Dead file with zero refs in src/ (the
+ * system-repo copy was cleared by deleteSystemPromptsJson; this is the
+ * matching cleanup at the user layer).
+ */
+function deleteUserPromptsJson() {
+    const f = path.join(USER_DIR, 'prompts.json');
+    if (!fs.existsSync(f))
+        return;
+    try {
+        fs.unlinkSync(f);
+    }
+    catch { /* best-effort */ }
+}
+/**
+ * Delete ~/.agents/config.json. The canonical teams config is at
+ * ~/.agents/teams/config.json (teams/persistence.ts). If the canonical
+ * file exists we just unlink the legacy copy; otherwise migrate first.
+ */
+function cleanupUserConfigJson() {
+    const legacy = path.join(USER_DIR, 'config.json');
+    if (!fs.existsSync(legacy))
+        return;
+    const canonical = path.join(USER_DIR, 'teams', 'config.json');
+    try {
+        if (!fs.existsSync(canonical)) {
+            fs.mkdirSync(path.dirname(canonical), { recursive: true, mode: 0o700 });
+            fs.copyFileSync(legacy, canonical);
+        }
+        fs.unlinkSync(legacy);
+    }
+    catch { /* best-effort */ }
+}
+/**
+ * Remove an empty ~/.agents/runs/ directory left over after the
+ * migrateRunsIntoRoutines() rename. Some older code paths re-created the
+ * empty parent; this trims it once it has no contents.
+ */
+function cleanupEmptyTopLevelRuns() {
+    const dir = path.join(USER_DIR, 'runs');
+    if (!fs.existsSync(dir))
+        return;
+    try {
+        if (fs.readdirSync(dir).length === 0)
+            fs.rmdirSync(dir);
+    }
+    catch { /* best-effort */ }
+}
+/**
+ * Move ~/.agents-system/aliases.json -> ~/.agents/aliases.json.
+ * Aliases are per-user state and were previously written to the system root
+ * by mistake. Idempotent: skips if dest already exists or src absent.
+ */
+function migrateAliasesToUser() {
+    const src = path.join(SYSTEM_DIR, 'aliases.json');
+    const dest = path.join(USER_DIR, 'aliases.json');
+    if (fs.existsSync(dest) || !fs.existsSync(src))
+        return;
+    try {
+        fs.mkdirSync(USER_DIR, { recursive: true, mode: 0o700 });
+        fs.renameSync(src, dest);
+    }
+    catch { /* best-effort */ }
+}
+/**
+ * For overlapping versions that exist in BOTH ~/.agents-system/versions/ and
+ * ~/.agents/versions/, merge legacy operational state (history, sessions,
+ * settings) into the user copy without overwriting any files synced by
+ * agents-cli (skills, commands, hooks, memory). Then drop the legacy copy.
+ *
+ * Why: when both paths exist, the inverted-prior migrator left them split.
+ * Agent CLIs read from ~/.<agent> (a symlink that historically targeted
+ * the system path), while sync writes to the user path. Same skill ends up
+ * in both → duplicate entries in the skills picker, stale state, broken
+ * resource resolution.
+ *
+ * Strategy: copy legacy → user with "skip if exists". Sync-managed dirs
+ * (which live in user already, freshly written) stay untouched. Anything
+ * the agent CLI created on its own (history.jsonl, sessions/, settings.json,
+ * file-history/, paste-cache/, …) lands in user where it belongs. The
+ * legacy version-home is then renamed into ~/.agents/.trash/versions/ so
+ * it's recoverable.
+ */
+function mergeOverlappingVersionHomes() {
+    const sysVersions = path.join(SYSTEM_DIR, 'versions');
+    const userVersions = path.join(USER_DIR, 'versions');
+    if (!fs.existsSync(sysVersions))
+        return;
+    let mergedCount = 0;
+    let agentEntries;
+    try {
+        agentEntries = fs.readdirSync(sysVersions, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const agent of agentEntries) {
+        if (!agent.isDirectory())
+            continue;
+        const sysAgentDir = path.join(sysVersions, agent.name);
+        const userAgentDir = path.join(userVersions, agent.name);
+        let verEntries;
+        try {
+            verEntries = fs.readdirSync(sysAgentDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const ver of verEntries) {
+            if (!ver.isDirectory())
+                continue;
+            const sysHome = path.join(sysAgentDir, ver.name, 'home');
+            const userHome = path.join(userAgentDir, ver.name, 'home');
+            if (!fs.existsSync(sysHome) || !fs.existsSync(userHome))
+                continue;
+            try {
+                copyDirSkipExisting(sysHome, userHome);
+                const trashRoot = path.join(USER_DIR, '.trash', 'versions', agent.name, ver.name);
+                const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+                fs.mkdirSync(trashRoot, { recursive: true, mode: 0o700 });
+                fs.renameSync(path.join(sysAgentDir, ver.name), path.join(trashRoot, `legacy-${stamp}`));
+                mergedCount++;
+            }
+            catch { /* best-effort */ }
+        }
+        try {
+            if (fs.readdirSync(sysAgentDir).length === 0)
+                fs.rmdirSync(sysAgentDir);
+        }
+        catch { /* best-effort */ }
+    }
+    try {
+        if (fs.readdirSync(sysVersions).length === 0)
+            fs.rmdirSync(sysVersions);
+    }
+    catch { /* best-effort */ }
+    if (mergedCount > 0) {
+        console.error(`Merged ${mergedCount} overlapping version home${mergedCount === 1 ? '' : 's'} from legacy ~/.agents-system/versions/ into ~/.agents/versions/ (legacy moved to ~/.agents/.trash/versions/)`);
+    }
+}
+function copyDirSkipExisting(src, dest) {
+    let entries;
+    try {
+        entries = fs.readdirSync(src, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    fs.mkdirSync(dest, { recursive: true, mode: 0o700 });
+    for (const entry of entries) {
+        const s = path.join(src, entry.name);
+        const d = path.join(dest, entry.name);
+        if (fs.existsSync(d)) {
+            if (entry.isDirectory()) {
+                const dStat = fs.lstatSync(d);
+                if (dStat.isDirectory())
+                    copyDirSkipExisting(s, d);
+            }
+            continue;
+        }
+        try {
+            fs.renameSync(s, d);
+        }
+        catch {
+            try {
+                if (entry.isDirectory()) {
+                    copyDirSkipExisting(s, d);
+                }
+                else if (entry.isSymbolicLink()) {
+                    fs.symlinkSync(fs.readlinkSync(s), d);
+                }
+                else {
+                    fs.copyFileSync(s, d);
+                }
+            }
+            catch { /* best-effort */ }
+        }
+    }
+}
+/**
+ * Rename ~/.agents/permissions/sets/ -> ~/.agents/permissions/presets/.
+ * Also handles ~/.agents-system/permissions/sets/ for system repo.
+ * Idempotent: skips if dest already exists or src absent.
+ */
+function migratePermissionSetsToPresets() {
+    for (const root of [USER_DIR, SYSTEM_DIR]) {
+        const src = path.join(root, 'permissions', 'sets');
+        const dest = path.join(root, 'permissions', 'presets');
+        if (!fs.existsSync(src) || fs.existsSync(dest))
+            continue;
+        try {
+            fs.renameSync(src, dest);
+            const label = root === USER_DIR ? '~/.agents' : '~/.agents-system';
+            console.error(`Migrated ${label}/permissions/sets/ to ${label}/permissions/presets/`);
+        }
+        catch { /* best-effort */ }
+    }
+}
+/**
+ * After versions are migrated to ~/.agents/versions/, rewrite the per-agent
+ * config symlinks (~/.claude, ~/.codex, …) to point at the user-side
+ * version-home so the agent CLIs read fresh resources.
+ *
+ * Idempotent: if the symlink already points at the right user-path target,
+ * leave it. If it points at the legacy system path, re-create it. If a real
+ * directory exists there (no symlink yet), leave it alone — version-config
+ * switching is owned by `agents use`, not the migrator.
+ */
+function repairAgentConfigSymlinks() {
+    let yaml;
+    try {
+        yaml = fs.readFileSync(path.join(USER_DIR, 'agents.yaml'), 'utf-8');
+    }
+    catch {
+        return;
+    }
+    const agentsBlock = yaml.match(/^agents:\s*\n((?:  [^\n]*\n)+)/m);
+    if (!agentsBlock)
+        return;
+    const defaults = [];
+    for (const line of agentsBlock[1].split('\n')) {
+        const m = line.match(/^\s+([a-z][a-z0-9_-]*):\s*([^\s#]+)/);
+        if (m)
+            defaults.push({ agent: m[1], version: m[2] });
+    }
+    let repaired = 0;
+    for (const { agent, version } of defaults) {
+        const userTarget = fs.existsSync(path.join(HISTORY_DIR, 'versions', agent, version, 'home', `.${agent}`))
+            ? path.join(HISTORY_DIR, 'versions', agent, version, 'home', `.${agent}`)
+            : path.join(USER_DIR, 'versions', agent, version, 'home', `.${agent}`);
+        if (!fs.existsSync(userTarget))
+            continue;
+        const symlinkPath = path.join(HOME, `.${agent}`);
+        let stat = null;
+        try {
+            stat = fs.lstatSync(symlinkPath);
+        }
+        catch { /* missing */ }
+        if (stat && stat.isSymbolicLink()) {
+            let current;
+            try {
+                current = fs.readlinkSync(symlinkPath);
+            }
+            catch {
+                continue;
+            }
+            const resolved = path.resolve(path.dirname(symlinkPath), current);
+            if (resolved === path.resolve(userTarget))
+                continue; // already correct
+            try {
+                fs.unlinkSync(symlinkPath);
+                fs.symlinkSync(userTarget, symlinkPath);
+                repaired++;
+            }
+            catch { /* best-effort */ }
+        }
+        else if (!stat) {
+            try {
+                fs.symlinkSync(userTarget, symlinkPath);
+                repaired++;
+            }
+            catch { /* best-effort */ }
+        }
+    }
+    if (repaired > 0) {
+        console.error(`Repaired ${repaired} agent config symlink${repaired === 1 ? '' : 's'} to point at ~/.agents/versions/`);
+    }
+}
+/**
+ * Move a directory from `src` to `dest`. No-op when src is absent. When dest
+ * already exists, merge by copying everything that isn't already there, then
+ * remove the source. Idempotent: re-running converges without duplicating.
+ *
+ * The merge-on-collision behavior matters because `ensureAgentsDir()` may have
+ * pre-created an empty `dest` during startup before the migrator gets to run.
+ */
+function moveDirOnce(src, dest) {
+    if (!fs.existsSync(src))
+        return;
+    if (!fs.existsSync(dest)) {
+        try {
+            fs.mkdirSync(path.dirname(dest), { recursive: true, mode: 0o700 });
+            fs.renameSync(src, dest);
+            return;
+        }
+        catch {
+            /* fall through to copy + remove */
+        }
+    }
+    try {
+        copyDirSkipExisting(src, dest);
+        fs.rmSync(src, { recursive: true, force: true });
+    }
+    catch { /* best-effort */ }
+}
+/**
+ * Move a single file from `src` to `dest`. No-op when src is absent. When
+ * dest exists, the source is simply deleted (the in-place version is treated
+ * as the canonical state). Idempotent.
+ */
+function moveFileOnce(src, dest) {
+    if (!fs.existsSync(src))
+        return;
+    if (fs.existsSync(dest)) {
+        try {
+            fs.unlinkSync(src);
+        }
+        catch { /* best-effort */ }
+        return;
+    }
+    try {
+        fs.mkdirSync(path.dirname(dest), { recursive: true, mode: 0o700 });
+        fs.renameSync(src, dest);
+    }
+    catch {
+        try {
+            fs.copyFileSync(src, dest);
+            fs.unlinkSync(src);
+        }
+        catch { /* best-effort */ }
+    }
+}
+/** Remove a directory tree if it exists and contains no files (best-effort). */
+function rmEmptyDirTree(dir) {
+    if (!fs.existsSync(dir))
+        return;
+    try {
+        const entries = fs.readdirSync(dir);
+        for (const entry of entries) {
+            const child = path.join(dir, entry);
+            try {
+                const stat = fs.statSync(child);
+                if (stat.isDirectory())
+                    rmEmptyDirTree(child);
+            }
+            catch { /* skip */ }
+        }
+        if (fs.readdirSync(dir).length === 0)
+            fs.rmdirSync(dir);
+    }
+    catch { /* best-effort */ }
+}
+/**
+ * Move durable runtime data into ~/.agents/.history/.
+ *
+ * Sources cleared:
+ *   ~/.agents/sessions/   -> ~/.agents/.history/sessions/
+ *   ~/.agents/versions/   -> ~/.agents/.history/versions/
+ *   ~/.agents/.trash/     -> ~/.agents/.history/trash/
+ *   ~/.agents/.backups/   -> ~/.agents/.history/backups/
+ *   ~/.agents/routines/runs/ -> ~/.agents/.history/runs/
+ *   ~/.agents/teams/agents/  -> ~/.agents/.history/teams/agents/
+ *
+ * Idempotent — skips entries whose destination already exists.
+ */
+function migrateRuntimeToHistory() {
+    moveDirOnce(path.join(USER_DIR, 'sessions'), path.join(HISTORY_DIR, 'sessions'));
+    moveDirOnce(path.join(USER_DIR, 'versions'), path.join(HISTORY_DIR, 'versions'));
+    // Some installs left both `.trash/` (current) and `trash/` (legacy lowercase).
+    // Move whichever exist into the history bucket.
+    moveDirOnce(path.join(USER_DIR, '.trash'), path.join(HISTORY_DIR, 'trash'));
+    moveDirOnce(path.join(USER_DIR, 'trash'), path.join(HISTORY_DIR, 'trash'));
+    moveDirOnce(path.join(USER_DIR, '.backups'), path.join(HISTORY_DIR, 'backups'));
+    moveDirOnce(path.join(USER_DIR, 'routines', 'runs'), path.join(HISTORY_DIR, 'runs'));
+    moveDirOnce(path.join(USER_DIR, 'teams', 'agents'), path.join(HISTORY_DIR, 'teams', 'agents'));
+    // Drop any empty leftover skeletons created mid-rename (e.g. `versions/<agent>/<v>/home/`
+    // recreated by a concurrent process). The real data is already under .history/.
+    rmEmptyDirTree(path.join(USER_DIR, 'versions'));
+    rmEmptyDirTree(path.join(USER_DIR, 'sessions'));
+    // Old empty zero-byte sessions.db at user root is obsolete once the new db lives at
+    // .history/sessions/sessions.db.
+    const oldSessionsDb = path.join(USER_DIR, 'sessions.db');
+    if (fs.existsSync(oldSessionsDb)) {
+        try {
+            if (fs.statSync(oldSessionsDb).size === 0)
+                fs.unlinkSync(oldSessionsDb);
+        }
+        catch { /* best-effort */ }
+    }
+}
+/**
+ * Move regenerable runtime data into ~/.agents/.cache/.
+ *
+ * Sources cleared:
+ *   ~/.agents/shims/         -> ~/.agents/.cache/shims/
+ *   ~/.agents/bin/           -> ~/.agents/.cache/bin/
+ *   ~/.agents/packages/      -> ~/.agents/.cache/packages/
+ *   ~/.agents/plugins/       -> ~/.agents/.cache/plugins/
+ *   ~/.agents/cloud/         -> ~/.agents/.cache/cloud/
+ *   ~/.agents/drive/         -> ~/.agents/.cache/drive/
+ *   ~/.agents/terminals/     -> ~/.agents/.cache/terminals/
+ *   ~/.agents/logs/          -> ~/.agents/.cache/logs/
+ *   ~/.agents/swarmify/      -> ~/.agents/.cache/swarmify/
+ *   ~/.agents/runtime/       -> ~/.agents/.cache/state/
+ *   ~/.agents/cache/         -> ~/.agents/.cache/   (flatten — already a cache subdir)
+ *   ~/.agents/helpers/{daemon,pty,...} -> ~/.agents/.cache/helpers/...
+ *   ~/.agents-system/helpers/{daemon,pty,...} -> ~/.agents/.cache/helpers/...
+ *   ~/.agents/browser/<profile>/  -> ~/.agents/.cache/browser/<profile>/  (profiles/ dir stays)
+ *   ~/.agents-system/.fetch/ -> ~/.agents/.cache/.fetch/
+ *
+ * Loose dot-files at user root that are runtime caches:
+ *   ~/.agents/.cli-version-cache.json -> ~/.agents/.cache/.cli-version-cache.json
+ *   ~/.agents/.update-check           -> ~/.agents/.cache/.update-check
+ *   ~/.agents/.migrated               -> ~/.agents/.cache/.migrated
+ *   ~/.agents/watchdog.log            -> ~/.agents/.cache/logs/watchdog.log
+ *
+ * Idempotent.
+ */
+function migrateRuntimeToCache() {
+    moveDirOnce(path.join(USER_DIR, 'shims'), path.join(CACHE_DIR, 'shims'));
+    moveDirOnce(path.join(USER_DIR, 'bin'), path.join(CACHE_DIR, 'bin'));
+    moveDirOnce(path.join(USER_DIR, 'packages'), path.join(CACHE_DIR, 'packages'));
+    moveDirOnce(path.join(USER_DIR, 'plugins'), path.join(CACHE_DIR, 'plugins'));
+    moveDirOnce(path.join(USER_DIR, 'cloud'), path.join(CACHE_DIR, 'cloud'));
+    moveDirOnce(path.join(USER_DIR, 'drive'), path.join(CACHE_DIR, 'drive'));
+    // terminals/ stays at the top level: the agents-cli IDE extension publishes
+    // ~/.agents/terminals/live-terminals.json and would race with the move on
+    // VS Code restart. Leave the path where the extension expects it.
+    moveDirOnce(path.join(USER_DIR, 'logs'), path.join(CACHE_DIR, 'logs'));
+    moveDirOnce(path.join(USER_DIR, 'swarmify'), path.join(CACHE_DIR, 'swarmify'));
+    moveDirOnce(path.join(USER_DIR, 'runtime'), path.join(CACHE_DIR, 'state'));
+    // Pre-existing user `cache/` dir (claude usage cache, cloud-runs, etc.) — flatten
+    // so it's not confused with the new bucket. Its contents merge into .cache/.
+    const oldCache = path.join(USER_DIR, 'cache');
+    if (fs.existsSync(oldCache) && fs.statSync(oldCache).isDirectory()) {
+        try {
+            fs.mkdirSync(CACHE_DIR, { recursive: true, mode: 0o700 });
+            copyDirSkipExisting(oldCache, CACHE_DIR);
+            fs.rmSync(oldCache, { recursive: true, force: true });
+        }
+        catch { /* best-effort */ }
+    }
+    // helpers/ at user-root and system-root → .cache/helpers/
+    for (const root of [USER_DIR, SYSTEM_DIR]) {
+        const src = path.join(root, 'helpers');
+        if (!fs.existsSync(src))
+            continue;
+        const destBase = path.join(CACHE_DIR, 'helpers');
+        try {
+            fs.mkdirSync(destBase, { recursive: true, mode: 0o700 });
+            copyDirSkipExisting(src, destBase);
+            fs.rmSync(src, { recursive: true, force: true });
+        }
+        catch { /* best-effort */ }
+    }
+    // browser runtime — keep browser/profiles/ in place, move everything else under
+    // browser/ into .cache/browser/.
+    const browserSrc = path.join(USER_DIR, 'browser');
+    if (fs.existsSync(browserSrc) && fs.statSync(browserSrc).isDirectory()) {
+        let entries = [];
+        try {
+            entries = fs.readdirSync(browserSrc);
+        }
+        catch { /* skip */ }
+        for (const entry of entries) {
+            if (entry === 'profiles')
+                continue;
+            const src = path.join(browserSrc, entry);
+            const dest = path.join(CACHE_DIR, 'browser', entry);
+            moveDirOnce(src, dest);
+        }
+    }
+    // System-root operational state that should not live in the npm-shipped repo.
+    moveDirOnce(path.join(SYSTEM_DIR, '.fetch'), path.join(CACHE_DIR, '.fetch'));
+    moveDirOnce(path.join(SYSTEM_DIR, 'browser'), path.join(CACHE_DIR, 'browser'));
+    moveDirOnce(path.join(SYSTEM_DIR, 'state'), path.join(CACHE_DIR, 'state'));
+    moveDirOnce(path.join(SYSTEM_DIR, 'swarmify'), path.join(CACHE_DIR, 'swarmify'));
+    moveFileOnce(path.join(SYSTEM_DIR, '.cli-version-cache.json'), path.join(CACHE_DIR, '.cli-version-cache.json'));
+    moveFileOnce(path.join(SYSTEM_DIR, '.update-check'), path.join(CACHE_DIR, '.update-check'));
+    moveFileOnce(path.join(SYSTEM_DIR, '.migrated'), path.join(CACHE_DIR, '.migrated'));
+    moveFileOnce(path.join(SYSTEM_DIR, '.models-cache.json'), path.join(CACHE_DIR, '.models-cache.json'));
+    // Loose dot-files at user root that belong in the cache bucket.
+    moveFileOnce(path.join(USER_DIR, '.cli-version-cache.json'), path.join(CACHE_DIR, '.cli-version-cache.json'));
+    moveFileOnce(path.join(USER_DIR, '.update-check'), path.join(CACHE_DIR, '.update-check'));
+    moveFileOnce(path.join(USER_DIR, '.migrated'), path.join(CACHE_DIR, '.migrated'));
+    moveFileOnce(path.join(USER_DIR, '.models-cache.json'), path.join(CACHE_DIR, '.models-cache.json'));
+    moveFileOnce(path.join(USER_DIR, 'watchdog.log'), path.join(CACHE_DIR, 'logs', 'watchdog.log'));
+}
+/**
+ * Merge a SQLite database file at `src` into the one at `dest`, then delete the
+ * source (including its WAL/SHM sidecars). User-side rows win on collision via
+ * INSERT OR IGNORE.
+ *
+ * If `dest` is missing, the source is simply moved into place (no merge). If
+ * the SQLite open fails (corrupt / zero-byte / locked), the source is dropped
+ * so the system repo returns to npm-shipped state — the data is stale-anyway
+ * runtime state, not user resources.
+ */
+async function mergeSqliteDb(src, dest) {
+    if (!fs.existsSync(src))
+        return;
+    try {
+        if (fs.statSync(src).size === 0) {
+            // Zero-byte legacy DB — drop sidecars too and leave dest alone.
+            try {
+                fs.unlinkSync(src);
+            }
+            catch { /* best-effort */ }
+            for (const ext of ['-shm', '-wal']) {
+                try {
+                    fs.unlinkSync(src + ext);
+                }
+                catch { /* best-effort */ }
+            }
+            return;
+        }
+    }
+    catch { /* best-effort */ }
+    if (!fs.existsSync(dest)) {
+        try {
+            fs.mkdirSync(path.dirname(dest), { recursive: true, mode: 0o700 });
+            fs.renameSync(src, dest);
+            for (const ext of ['-shm', '-wal']) {
+                if (fs.existsSync(src + ext)) {
+                    try {
+                        fs.renameSync(src + ext, dest + ext);
+                    }
+                    catch { /* best-effort */ }
+                }
+            }
+            return;
+        }
+        catch { /* fall through to merge */ }
+    }
+    // Both files exist — open the dest DB and ATTACH src, then INSERT OR IGNORE
+    // every user table. Dynamic import keeps the sqlite shim off the hot path
+    // for CLI starts that don't actually need a merge.
+    try {
+        const sqliteMod = (await import('./sqlite.js'));
+        const Database = sqliteMod.default;
+        const db = new Database(dest);
+        try {
+            db.exec(`ATTACH DATABASE '${src.replace(/'/g, "''")}' AS src`);
+            const tables = db.prepare(`SELECT name FROM src.sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'`).all();
+            // FTS5 virtual tables maintain shadow tables (<name>_data, _idx, _content,
+            // _docsize, _config) with internal segids/pgnos that MUST stay consistent.
+            // Row-merging shadow tables across two DBs corrupts the index. Skip them
+            // here — the indexer reconstructs FTS content on the next scan.
+            const ftsVirtuals = new Set(db.prepare(`SELECT name FROM src.sqlite_master WHERE type='table' AND sql LIKE '%fts5%'`).all().map((r) => r.name));
+            const ftsShadowSuffixes = ['_data', '_idx', '_content', '_docsize', '_config'];
+            const isFtsShadow = (name) => {
+                for (const v of ftsVirtuals) {
+                    for (const suf of ftsShadowSuffixes) {
+                        if (name === `${v}${suf}`)
+                            return true;
+                    }
+                }
+                return false;
+            };
+            for (const { name } of tables) {
+                if (ftsVirtuals.has(name) || isFtsShadow(name))
+                    continue;
+                try {
+                    const row = db.prepare(`SELECT sql FROM src.sqlite_master WHERE type='table' AND name = ?`).get(name);
+                    if (row?.sql) {
+                        const ddl = row.sql.replace(/^CREATE TABLE\s+/i, 'CREATE TABLE IF NOT EXISTS ');
+                        db.exec(ddl);
+                    }
+                }
+                catch { /* table likely exists already */ }
+                const quoted = '"' + name.replace(/"/g, '""') + '"';
+                try {
+                    db.exec(`INSERT OR IGNORE INTO main.${quoted} SELECT * FROM src.${quoted}`);
+                }
+                catch { /* schema drift — skip table */ }
+            }
+            try {
+                db.exec('DETACH DATABASE src');
+            }
+            catch { /* best-effort */ }
+        }
+        finally {
+            try {
+                db.close();
+            }
+            catch { /* best-effort */ }
+        }
+        try {
+            fs.unlinkSync(src);
+        }
+        catch { /* best-effort */ }
+        for (const ext of ['-shm', '-wal']) {
+            try {
+                fs.unlinkSync(src + ext);
+            }
+            catch { /* best-effort */ }
+        }
+    }
+    catch {
+        // Merge failed — drop the source so the system repo returns to clean state.
+        // The user-side DB is authoritative; system-side rows were duplicate state.
+        try {
+            fs.unlinkSync(src);
+        }
+        catch { /* best-effort */ }
+        for (const ext of ['-shm', '-wal']) {
+            try {
+                fs.unlinkSync(src + ext);
+            }
+            catch { /* best-effort */ }
+        }
+    }
+}
+/**
+ * Move ~/.agents-system/sessions/ into ~/.agents/.history/sessions/.
+ *
+ * Filesystem entries (claude/, index.jsonl, content_index.jsonl, etc.) merge
+ * directory-by-directory with user-side winning on collision. The bundled
+ * sessions.db (plus WAL/SHM) goes through mergeSqliteDb so historical rows
+ * land in the user DB.
+ */
+async function migrateSystemSessionsToHistory() {
+    const src = path.join(SYSTEM_DIR, 'sessions');
+    if (!fs.existsSync(src))
+        return;
+    const dest = path.join(HISTORY_DIR, 'sessions');
+    try {
+        fs.mkdirSync(dest, { recursive: true, mode: 0o700 });
+    }
+    catch { /* best-effort */ }
+    let entries;
+    try {
+        entries = fs.readdirSync(src, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const s = path.join(src, entry.name);
+        if (entry.name === 'sessions.db' || entry.name === 'sessions.db-shm' || entry.name === 'sessions.db-wal') {
+            // Handled by mergeSqliteDb on the canonical .db name below.
+            continue;
+        }
+        const d = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            moveDirOnce(s, d);
+        }
+        else {
+            moveFileOnce(s, d);
+        }
+    }
+    await mergeSqliteDb(path.join(src, 'sessions.db'), path.join(dest, 'sessions.db'));
+    try {
+        if (fs.readdirSync(src).length === 0)
+            fs.rmdirSync(src);
+    }
+    catch { /* best-effort */ }
+}
+/**
+ * Move ~/.agents-system/teams/ contents to ~/.agents/teams/ (registry/config)
+ * and ~/.agents/.history/teams/ (per-run dirs).
+ *
+ * Strategy:
+ *   config.json, registry.json   -> ~/.agents/teams/        (live state)
+ *   agents/                       -> ~/.agents/.history/teams/agents/
+ *   <anything else>               -> ~/.agents/.history/teams/<name>/  (per-run dirs)
+ */
+function migrateSystemTeamsToUser() {
+    const src = path.join(SYSTEM_DIR, 'teams');
+    if (!fs.existsSync(src))
+        return;
+    const liveDest = path.join(USER_DIR, 'teams');
+    const historyDest = path.join(HISTORY_DIR, 'teams');
+    let entries;
+    try {
+        entries = fs.readdirSync(src, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const s = path.join(src, entry.name);
+        if (entry.name === 'config.json' || entry.name === 'registry.json') {
+            moveFileOnce(s, path.join(liveDest, entry.name));
+            continue;
+        }
+        if (entry.name === 'agents' && entry.isDirectory()) {
+            moveDirOnce(s, path.join(historyDest, 'agents'));
+            continue;
+        }
+        if (entry.isDirectory()) {
+            moveDirOnce(s, path.join(historyDest, entry.name));
+        }
+        else {
+            moveFileOnce(s, path.join(historyDest, entry.name));
+        }
+    }
+    try {
+        if (fs.readdirSync(src).length === 0)
+            fs.rmdirSync(src);
+    }
+    catch { /* best-effort */ }
+}
+/**
+ * Move ~/.agents-system/trash/ -> ~/.agents/.history/trash/.
+ *
+ * The system trash was where the legacy `mergeOverlappingVersionHomes()` parked
+ * orphan version homes. Folding it into the history bucket keeps "everything
+ * recoverable" in one place.
+ */
+function migrateSystemTrashToHistory() {
+    const src = path.join(SYSTEM_DIR, 'trash');
+    if (!fs.existsSync(src))
+        return;
+    moveDirOnce(src, path.join(HISTORY_DIR, 'trash'));
+}
+/**
+ * Move ~/.agents-system/cache/ contents into ~/.agents/.cache/.
+ *
+ * Special cases:
+ *   sessions.db        -> mergeSqliteDb into HISTORY_DIR/sessions/sessions.db
+ *   cloud-runs/        -> .cache/cloud-runs/
+ *   claude-usage.json  -> drop (regenerable per-version cache)
+ *   <anything else>    -> .cache/<name> (merge-on-collision)
+ */
+async function migrateSystemCacheToUserCache() {
+    const src = path.join(SYSTEM_DIR, 'cache');
+    if (!fs.existsSync(src))
+        return;
+    let entries;
+    try {
+        entries = fs.readdirSync(src, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const s = path.join(src, entry.name);
+        if (entry.name === 'sessions.db' || entry.name === 'sessions.db-shm' || entry.name === 'sessions.db-wal') {
+            // Sessions DB belongs in HISTORY, not CACHE — merge into the durable one.
+            if (entry.name === 'sessions.db') {
+                await mergeSqliteDb(s, path.join(HISTORY_DIR, 'sessions', 'sessions.db'));
+            }
+            // Sidecars get dropped if they outlived the merge or were orphaned.
+            try {
+                if (fs.existsSync(s))
+                    fs.unlinkSync(s);
+            }
+            catch { /* best-effort */ }
+            continue;
+        }
+        if (entry.name === 'claude-usage.json') {
+            try {
+                fs.unlinkSync(s);
+            }
+            catch { /* best-effort */ }
+            continue;
+        }
+        const d = path.join(CACHE_DIR, entry.name);
+        if (entry.isDirectory()) {
+            moveDirOnce(s, d);
+        }
+        else {
+            moveFileOnce(s, d);
+        }
+    }
+    try {
+        if (fs.readdirSync(src).length === 0)
+            fs.rmdirSync(src);
+    }
+    catch { /* best-effort */ }
+}
+/**
+ * Merge ~/.agents-system/cloud/tasks.db into ~/.agents/.cache/cloud/tasks.db.
+ */
+async function migrateSystemCloudToCache() {
+    const srcDir = path.join(SYSTEM_DIR, 'cloud');
+    if (!fs.existsSync(srcDir))
+        return;
+    await mergeSqliteDb(path.join(srcDir, 'tasks.db'), path.join(CACHE_DIR, 'cloud', 'tasks.db'));
+    // Any other files in cloud/ get moved into the user cache bucket.
+    let entries;
+    try {
+        entries = fs.readdirSync(srcDir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const s = path.join(srcDir, entry.name);
+        const d = path.join(CACHE_DIR, 'cloud', entry.name);
+        if (entry.isDirectory()) {
+            moveDirOnce(s, d);
+        }
+        else {
+            moveFileOnce(s, d);
+        }
+    }
+    try {
+        if (fs.readdirSync(srcDir).length === 0)
+            fs.rmdirSync(srcDir);
+    }
+    catch { /* best-effort */ }
+}
+/**
+ * Legacy ~/.agents-system/swarm/ predates the rename to teams/. Fold any
+ * per-agent dirs into ~/.agents/.history/teams/agents/ and drop the bookkeeping
+ * JSONs (cache.json, config.json, teams.json) — those are regenerable.
+ */
+function migrateLegacySwarmToTeams() {
+    const src = path.join(SYSTEM_DIR, 'swarm');
+    if (!fs.existsSync(src))
+        return;
+    const agentsSrc = path.join(src, 'agents');
+    if (fs.existsSync(agentsSrc)) {
+        moveDirOnce(agentsSrc, path.join(HISTORY_DIR, 'teams', 'agents'));
+    }
+    for (const dead of ['cache.json', 'config.json', 'teams.json']) {
+        const f = path.join(src, dead);
+        if (fs.existsSync(f)) {
+            try {
+                fs.unlinkSync(f);
+            }
+            catch { /* best-effort */ }
+        }
+    }
+    try {
+        if (fs.readdirSync(src).length === 0)
+            fs.rmdirSync(src);
+    }
+    catch { /* best-effort */ }
+}
+/**
+ * Move ~/.agents-system/repos/<alias>/ to ~/.agents-<alias>/ peer dirs.
+ *
+ * Extra DotAgents repos are user-defined config and belong as peer dirs to
+ * ~/.agents/, not nested under the npm-shipped system repo. The dir name in
+ * `repos/` becomes the alias.
+ */
+function migrateSystemReposToPeerDirs() {
+    const src = path.join(SYSTEM_DIR, 'repos');
+    if (!fs.existsSync(src))
+        return;
+    let entries;
+    try {
+        entries = fs.readdirSync(src, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    let moved = 0;
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const alias = entry.name;
+        const s = path.join(src, alias);
+        const d = path.join(HOME, `.agents-${alias}`);
+        if (fs.existsSync(d)) {
+            // Peer dir already exists — drop the system-side copy to avoid drift.
+            try {
+                fs.rmSync(s, { recursive: true, force: true });
+            }
+            catch { /* best-effort */ }
+            continue;
+        }
+        try {
+            fs.renameSync(s, d);
+            moved++;
+        }
+        catch { /* best-effort, leave in place */ }
+    }
+    try {
+        if (fs.readdirSync(src).length === 0)
+            fs.rmdirSync(src);
+    }
+    catch { /* best-effort */ }
+    if (moved > 0) {
+        console.error(`Moved ${moved} extra repo${moved === 1 ? '' : 's'} from ~/.agents-system/repos/ to ~/.agents-<alias>/ peer dirs`);
+    }
+}
+/**
+ * Drop known-dead artifacts from ~/.agents-system/ that are pure regenerable
+ * runtime state and don't belong anywhere:
+ *   bin/agents-keychain-*  — per-version keychain helper, rebuilt on demand
+ *   shims/                  — moved long ago, only empty leftover remains
+ */
+function dropDeadSystemArtifacts() {
+    const binDir = path.join(SYSTEM_DIR, 'bin');
+    if (fs.existsSync(binDir)) {
+        try {
+            for (const name of fs.readdirSync(binDir)) {
+                if (name.startsWith('agents-keychain-')) {
+                    try {
+                        fs.unlinkSync(path.join(binDir, name));
+                    }
+                    catch { /* best-effort */ }
+                }
+            }
+            if (fs.readdirSync(binDir).length === 0)
+                fs.rmdirSync(binDir);
+        }
+        catch { /* best-effort */ }
+    }
+    const shimsDir = path.join(SYSTEM_DIR, 'shims');
+    if (fs.existsSync(shimsDir)) {
+        try {
+            if (fs.readdirSync(shimsDir).length === 0)
+                fs.rmdirSync(shimsDir);
+        }
+        catch { /* best-effort */ }
+    }
+    // After migrateSystemVersionsToUser() moves real version dirs out, the system
+    // may still hold an empty `versions/<agent>/` skeleton with a stray .DS_Store.
+    // Sweep it: if every leaf file is .DS_Store, drop the tree entirely.
+    const versionsDir = path.join(SYSTEM_DIR, 'versions');
+    if (fs.existsSync(versionsDir)) {
+        try {
+            if (containsOnlyDsStore(versionsDir)) {
+                fs.rmSync(versionsDir, { recursive: true, force: true });
+            }
+        }
+        catch { /* best-effort */ }
+    }
+}
+function containsOnlyDsStore(dir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return false;
+    }
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            if (!containsOnlyDsStore(path.join(dir, entry.name)))
+                return false;
+        }
+        else if (entry.name !== '.DS_Store') {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * After the sweep runs, warn (once per invocation) about any unrecognized
+ * subdirectory left in ~/.agents-system/. The system repo is the npm-shipped
+ * defaults — anything outside the allowlist is drift that future maintainers
+ * need to handle explicitly.
+ */
+function warnSystemOrphans() {
+    const SHIPPED_ALLOWLIST = new Set([
+        // resource directories shipped by the npm package
+        'commands', 'hooks', 'skills', 'rules', 'mcp', 'permissions', 'subagents', 'profiles', 'agents',
+        // top-level metadata files
+        'agents.yaml', 'hooks.yaml', 'README.md', 'CHANGELOG.md',
+        // git + repo metadata
+        '.git', '.githooks', '.gitignore', '.assets', '.environment', '.plans',
+        // benign noise that's safe to ignore
+        '.DS_Store', '.claude',
+    ]);
+    let entries;
+    try {
+        entries = fs.readdirSync(SYSTEM_DIR);
+    }
+    catch {
+        return;
+    }
+    // Transient runtime sockets (.sock) are bound by long-running helpers like the
+    // VS Code extension; they're live state, not stale data, and a future fix in
+    // those helpers will move them into ~/.agents/.cache/ — until then, suppress.
+    const orphans = entries.filter((name) => !SHIPPED_ALLOWLIST.has(name) && !name.endsWith('.sock'));
+    if (orphans.length === 0)
+        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 function runMigration() {
+export async function runMigration() {
     migrateAgentsYaml();
     deleteSystemPromptsJson();
     migrateSystemConfigJson();
     migratePromptcutsIntoHooks();
-    migrateUserVersionsToSystem();
+    migrateSystemVersionsToUser();
+    mergeOverlappingVersionHomes();
     migrateRunsIntoRoutines();
     migrateTrashToHidden();
     migrateBackupsToHidden();
+    migrateAliasesToUser();
+    migratePermissionSetsToPresets();
+    deleteUserLinearJson();
+    deleteUserPromptsJson();
+    cleanupUserConfigJson();
+    cleanupEmptyTopLevelRuns();
+    foldUserHooksYamlIntoAgentsYaml();
+    foldBrowserProfilesIntoAgentsYaml();
+    migrateVersionResourcesToPatterns();
+    // Bucket moves: collapse runtime state into ~/.agents/.history and ~/.agents/.cache.
+    migrateRuntimeToHistory();
+    migrateRuntimeToCache();
+    // System-repo sweep: move every remaining operational dir into its canonical
+    // user-bucket location, then drop known-dead artifacts and warn about
+    // anything we don't recognize. Order: durable (sessions/teams/trash/repos/
+    // legacy-swarm) -> caches (cache/, cloud/) -> drops -> orphan check.
+    await migrateSystemSessionsToHistory();
+    migrateSystemTeamsToUser();
+    migrateSystemTrashToHistory();
+    migrateLegacySwarmToTeams();
+    migrateSystemReposToPeerDirs();
+    await migrateSystemCacheToUserCache();
+    await migrateSystemCloudToCache();
+    dropDeadSystemArtifacts();
+    warnSystemOrphans();
+    // Symlink repair runs LAST so it can find the post-move version homes.
+    repairAgentConfigSymlinks();
 }