@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/installations/migrate.js

@@ -1,4 +1,3 @@
-/** One-shot idempotent migrations. Each is guarded by an existence check so re-running is safe. */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
@@ -17,17 +16,11 @@ import { enabledRoutineNames, replaceEnabledRoutines } from '../routine-activati
 import { evaluateActivationReadiness } from '../routine-readiness.js';
 import { migrateDeviceConfigStores } from '../devices/config-migration.js';
 import { detrackViaGitExclude } from '../project-resources.js';
-// Migrations operate on raw YAML so they never take the meta lock or prime the
-// meta cache mid-migration.
 import { META_HEADER as DEVICE_META_HEADER } from '../state.js';
-/** The pre-device-scope central browser profile name this one-shot migration
- *  folds into the device doc. Inlined (the in-repo browser engine that defined it
- *  was removed with PHNX-4101); the legacy on-disk name is unchanged. */
 const LEGACY_DEFAULT_BROWSER_PROFILE_NAME = 'default';
 import { COMPILED_HEADER_PROJECT } from '../rules/compile.js';
 const HOME = process.env.HOME ?? os.homedir();
 const USER_DIR = path.join(HOME, '.agents');
-/** Canonical system-repo location (post-fold). */
 const SYSTEM_DIR = path.join(USER_DIR, '.system');
 const HISTORY_DIR = path.join(USER_DIR, '.history');
 const CACHE_DIR = path.join(USER_DIR, '.cache');
@@ -37,25 +30,21 @@ function isTrackedInGitRepo(repoDir, relPath) {
         return true;
     }
     catch {
-        // Not a git repo, or the file is untracked — either way, not tracked.
         return false;
     }
 }
-/** Migrate a legacy single-repo agents.yaml into ~/.agents/agents.yaml. Leaves the tracked system-mirror copy alone to avoid dirtying the npm-shipped defaults. */
 export function migrateAgentsYaml(systemDir = SYSTEM_DIR, userDir = USER_DIR) {
     const src = path.join(systemDir, 'agents.yaml');
     const dest = path.join(userDir, 'agents.yaml');
     if (!fs.existsSync(src))
         return;
-    // Never move the tracked system-mirror copy; doing so would dirty the npm-shipped defaults.
     if (isTrackedInGitRepo(systemDir, 'agents.yaml'))
         return;
     if (fs.existsSync(dest)) {
-        // User copy is authoritative — drop the untracked stale system leftover.
         try {
             fs.unlinkSync(src);
         }
-        catch { /* best-effort */ }
+        catch { }
         return;
     }
     try {
@@ -63,7 +52,7 @@ export function migrateAgentsYaml(systemDir = SYSTEM_DIR, userDir = USER_DIR) {
         fs.renameSync(src, dest);
         console.error('Migrated agents.yaml to ~/.agents/');
     }
-    catch { /* best-effort */ }
+    catch { }
 }
 function deleteSystemPromptsJson() {
     const f = path.join(SYSTEM_DIR, 'prompts.json');
@@ -72,25 +61,15 @@ function deleteSystemPromptsJson() {
     try {
         fs.unlinkSync(f);
     }
-    catch { /* best-effort */ }
+    catch { }
 }
-/**
- * Stop tracking the user repo's CHANGELOG.md. It duplicates the npm-shipped
- * `.system/CHANGELOG.md` (read the canonical copy from there), and as a tracked
- * file that upstream never carries it can only ever show as `M`/`??`
- * — dirtying the tree and, when a peer's publish commit arrives, tripping the
- * dirty-tree pull guard. De-track it into `.git/info/exclude` (per-clone,
- * uncommitted; never `.gitignore`, which would re-introduce the same failure).
- * Idempotent: a no-op once the path is untracked and excluded.
- */
 export function detrackUserChangelog(userDir = USER_DIR) {
     if (!fs.existsSync(path.join(userDir, '.git')))
-        return; // plain dir, not a clone
+        return;
     const untracked = detrackViaGitExclude(userDir, 'CHANGELOG.md');
     if (untracked)
         console.error('Stopped tracking ~/.agents/CHANGELOG.md (duplicates .system/CHANGELOG.md)');
 }
-/** Delete the legacy ~/.agents-system/config.json (dead teams agent registry). */
 function migrateSystemConfigJson() {
     const src = path.join(SYSTEM_DIR, 'config.json');
     if (!fs.existsSync(src))
@@ -98,9 +77,8 @@ function migrateSystemConfigJson() {
     try {
         fs.unlinkSync(src);
     }
-    catch { /* best-effort */ }
+    catch { }
 }
-/** Move promptcuts.yaml from each repo root into hooks/. */
 function migratePromptcutsIntoHooks() {
     for (const root of [SYSTEM_DIR, USER_DIR]) {
         const src = path.join(root, 'promptcuts.yaml');
@@ -111,10 +89,9 @@ function migratePromptcutsIntoHooks() {
             fs.mkdirSync(path.dirname(dest), { recursive: true, mode: 0o700 });
             fs.renameSync(src, dest);
         }
-        catch { /* best-effort */ }
+        catch { }
     }
 }
-/** Move installed versions from the legacy ~/.agents-system/versions/ tree into ~/.agents/versions/. Leaves collisions in place for manual reconciliation. */
 function migrateSystemVersionsToUser() {
     const sysVersions = path.join(SYSTEM_DIR, 'versions');
     const userVersions = path.join(USER_DIR, 'versions');
@@ -137,7 +114,7 @@ function migrateSystemVersionsToUser() {
         try {
             fs.mkdirSync(dstAgentDir, { recursive: true, mode: 0o700 });
         }
-        catch { /* best-effort */ }
+        catch { }
         let verEntries;
         try {
             verEntries = fs.readdirSync(srcAgentDir, { withFileTypes: true });
@@ -158,19 +135,19 @@ function migrateSystemVersionsToUser() {
                 fs.renameSync(src, dst);
                 movedCount++;
             }
-            catch { /* best-effort, leave legacy in place */ }
+            catch { }
         }
         try {
             if (fs.readdirSync(srcAgentDir).length === 0)
                 fs.rmdirSync(srcAgentDir);
         }
-        catch { /* best-effort */ }
+        catch { }
     }
     try {
         if (fs.readdirSync(sysVersions).length === 0)
             fs.rmdirSync(sysVersions);
     }
-    catch { /* best-effort */ }
+    catch { }
     if (movedCount > 0) {
         console.error(`Migrated ${movedCount} version dir${movedCount === 1 ? '' : 's'} from ~/.agents-system/versions/ to ~/.agents/versions/`);
     }
@@ -178,7 +155,6 @@ function migrateSystemVersionsToUser() {
         console.error(`Skipped ${skippedCount} version dir${skippedCount === 1 ? '' : 's'} already present in ~/.agents/versions/ (kept legacy copy at ~/.agents-system/versions/)`);
     }
 }
-/** Move ~/.agents/runs/ into ~/.agents/routines/runs/. */
 function migrateRunsIntoRoutines() {
     const src = path.join(USER_DIR, 'runs');
     const dest = path.join(USER_DIR, 'routines', 'runs');
@@ -188,9 +164,8 @@ function migrateRunsIntoRoutines() {
         fs.mkdirSync(path.dirname(dest), { recursive: true, mode: 0o700 });
         fs.renameSync(src, dest);
     }
-    catch { /* best-effort */ }
+    catch { }
 }
-/** Move ~/.agents/trash/ to ~/.agents/.trash/. */
 function migrateTrashToHidden() {
     const src = path.join(USER_DIR, 'trash');
     const dest = path.join(USER_DIR, '.trash');
@@ -199,9 +174,8 @@ function migrateTrashToHidden() {
     try {
         fs.renameSync(src, dest);
     }
-    catch { /* best-effort */ }
+    catch { }
 }
-/** Move ~/.agents/backups/ to ~/.agents/.backups/. */
 function migrateBackupsToHidden() {
     const src = path.join(USER_DIR, 'backups');
     const dest = path.join(USER_DIR, '.backups');
@@ -210,9 +184,8 @@ function migrateBackupsToHidden() {
     try {
         fs.renameSync(src, dest);
     }
-    catch { /* best-effort */ }
+    catch { }
 }
-/** Fold ~/.agents/hooks.yaml into ~/.agents/agents.yaml under `hooks:`, dropping the standalone file. agents.yaml wins on collision. */
 function foldUserHooksYamlIntoAgentsYaml() {
     const hooksFile = path.join(USER_DIR, 'hooks.yaml');
     if (!fs.existsSync(hooksFile))
@@ -253,9 +226,8 @@ function foldUserHooksYamlIntoAgentsYaml() {
         fs.unlinkSync(hooksFile);
         console.error('Folded ~/.agents/hooks.yaml into ~/.agents/agents.yaml (hooks: section)');
     }
-    catch { /* best-effort */ }
+    catch { }
 }
-/** Fold the legacy global browser/sessions/<task>/ tree into the per-profile browser/<profile>/sessions/<task>/ layout. Unclaimed tasks move under `_legacy`. */
 export function foldBrowserSessionsIntoProfiles(browserDir = path.join(CACHE_DIR, 'browser')) {
     const legacySessionsDir = path.join(browserDir, 'sessions');
     let taskDirs;
@@ -263,14 +235,14 @@ export function foldBrowserSessionsIntoProfiles(browserDir = path.join(CACHE_DIR
         taskDirs = fs.readdirSync(legacySessionsDir, { withFileTypes: true });
     }
     catch {
-        return; // no legacy global sessions/ root — already folded or never existed
+        return;
     }
     const taskOwner = new Map();
     let profileDirs = [];
     try {
         profileDirs = fs.readdirSync(browserDir, { withFileTypes: true });
     }
-    catch { /* browserDir vanished mid-run */ }
+    catch { }
     for (const p of profileDirs) {
         if (!p.isDirectory() || p.name === 'sessions' || p.name === '_legacy')
             continue;
@@ -281,20 +253,16 @@ export function foldBrowserSessionsIntoProfiles(browserDir = path.join(CACHE_DIR
                     taskOwner.set(taskName, p.name);
             }
         }
-        catch { /* missing or invalid tasks.json */ }
+        catch { }
     }
     for (const taskEntry of taskDirs) {
         if (!taskEntry.isDirectory())
             continue;
         const owner = taskOwner.get(taskEntry.name) ?? '_legacy';
-        // A capture dir can hold a nested recordings/ subdir and may collide with a
-        // dest that already has newer captures — moveDirOnce merges (skip-existing),
-        // moveFileOnce would EISDIR on unlink and silently strand the captures.
         moveDirOnce(path.join(legacySessionsDir, taskEntry.name), path.join(browserDir, owner, 'sessions', taskEntry.name));
     }
     rmEmptyDirTree(legacySessionsDir);
 }
-/** Fold ~/.agents/browser/profiles/*.yaml into ~/.agents/agents.yaml under `browser:`. agents.yaml wins on collision. */
 function foldBrowserProfilesIntoAgentsYaml() {
     const profilesDir = path.join(USER_DIR, 'browser', 'profiles');
     if (!fs.existsSync(profilesDir))
@@ -319,7 +287,7 @@ function foldBrowserProfilesIntoAgentsYaml() {
             const { name: _, ...config } = parsed;
             profiles[name] = config;
         }
-        catch { /* skip unreadable file */ }
+        catch { }
     }
     if (Object.keys(profiles).length === 0)
         return;
@@ -351,24 +319,23 @@ function foldBrowserProfilesIntoAgentsYaml() {
             try {
                 fs.unlinkSync(path.join(profilesDir, file));
             }
-            catch { /* best-effort */ }
+            catch { }
         }
         try {
             fs.rmdirSync(profilesDir);
         }
-        catch { /* may not be empty */ }
+        catch { }
         try {
             const browserDir = path.join(USER_DIR, 'browser');
             if (fs.existsSync(browserDir) && fs.readdirSync(browserDir).length === 0) {
                 fs.rmdirSync(browserDir);
             }
         }
-        catch { /* best-effort */ }
+        catch { }
         console.error('Folded ~/.agents/browser/profiles/ into ~/.agents/agents.yaml (browser: section)');
     }
-    catch { /* best-effort */ }
+    catch { }
 }
-/** Delete the legacy ~/.agents/linear.json plaintext credential store. */
 function deleteUserLinearJson() {
     const f = path.join(USER_DIR, 'linear.json');
     if (!fs.existsSync(f))
@@ -376,9 +343,8 @@ function deleteUserLinearJson() {
     try {
         fs.unlinkSync(f);
     }
-    catch { /* best-effort */ }
+    catch { }
 }
-/** Delete the dead ~/.agents/prompts.json file. */
 function deleteUserPromptsJson() {
     const f = path.join(USER_DIR, 'prompts.json');
     if (!fs.existsSync(f))
@@ -386,9 +352,8 @@ function deleteUserPromptsJson() {
     try {
         fs.unlinkSync(f);
     }
-    catch { /* best-effort */ }
+    catch { }
 }
-/** Delete the dead ~/.agents/teams/config.json file. */
 function deleteTeamsConfigJson() {
     const f = path.join(USER_DIR, 'teams', 'config.json');
     if (!fs.existsSync(f))
@@ -396,15 +361,13 @@ function deleteTeamsConfigJson() {
     try {
         fs.unlinkSync(f);
     }
-    catch { /* best-effort */ }
+    catch { }
 }
-/** Move ~/.agents/teams/registry.json (per-machine runtime state) into ~/.agents/.history/teams/. */
 function moveTeamsRegistryToHistory() {
     const src = path.join(USER_DIR, 'teams', 'registry.json');
     const dest = path.join(HISTORY_DIR, 'teams', 'registry.json');
     moveFileOnce(src, dest);
 }
-/** Delete the legacy ~/.agents/config.json teams config file. */
 function cleanupUserConfigJson() {
     const legacy = path.join(USER_DIR, 'config.json');
     if (!fs.existsSync(legacy))
@@ -412,9 +375,8 @@ function cleanupUserConfigJson() {
     try {
         fs.unlinkSync(legacy);
     }
-    catch { /* best-effort */ }
+    catch { }
 }
-/** Remove an empty ~/.agents/runs/ directory left over after migrateRunsIntoRoutines(). */
 function cleanupEmptyTopLevelRuns() {
     const dir = path.join(USER_DIR, 'runs');
     if (!fs.existsSync(dir))
@@ -423,9 +385,8 @@ function cleanupEmptyTopLevelRuns() {
         if (fs.readdirSync(dir).length === 0)
             fs.rmdirSync(dir);
     }
-    catch { /* best-effort */ }
+    catch { }
 }
-/** Move ~/.agents-system/aliases.json into ~/.agents/aliases.json. */
 function migrateAliasesToUser() {
     const src = path.join(SYSTEM_DIR, 'aliases.json');
     const dest = path.join(USER_DIR, 'aliases.json');
@@ -435,27 +396,8 @@ function migrateAliasesToUser() {
         fs.mkdirSync(USER_DIR, { recursive: true, mode: 0o700 });
         fs.renameSync(src, dest);
     }
-    catch { /* best-effort */ }
+    catch { }
 }
-/**
- * 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');
@@ -496,24 +438,23 @@ function mergeOverlappingVersionHomes() {
                 fs.renameSync(path.join(sysAgentDir, ver.name), path.join(trashRoot, `legacy-${stamp}`));
                 mergedCount++;
             }
-            catch { /* best-effort */ }
+            catch { }
         }
         try {
             if (fs.readdirSync(sysAgentDir).length === 0)
                 fs.rmdirSync(sysAgentDir);
         }
-        catch { /* best-effort */ }
+        catch { }
     }
     try {
         if (fs.readdirSync(sysVersions).length === 0)
             fs.rmdirSync(sysVersions);
     }
-    catch { /* best-effort */ }
+    catch { }
     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/)`);
     }
 }
-/** Rename permissions/sets/ to permissions/presets/ in both user and system repos. */
 function migratePermissionSetsToPresets() {
     for (const root of [USER_DIR, SYSTEM_DIR]) {
         const src = path.join(root, 'permissions', 'sets');
@@ -525,15 +466,10 @@ function migratePermissionSetsToPresets() {
             const label = root === USER_DIR ? '~/.agents' : '~/.agents-system';
             console.error(`Migrated ${label}/permissions/sets/ to ${label}/permissions/presets/`);
         }
-        catch { /* best-effort */ }
+        catch { }
     }
 }
-/** Rewrite per-agent config symlinks to point at the user-side version home after migration. Leaves real directories alone (switching is owned by `agents use`). */
 function repairAgentConfigSymlinks() {
-    // Version pins live in the machine-local pins JSON (~/.agents/.history/
-    // devices/pins-<machine>.json); the tracked device doc and central
-    // agents.yaml may still carry them mid-transition. Read pins first
-    // (authoritative), then the legacy locations, first-seen-agent wins.
     const defaults = [];
     const seen = new Set();
     const collectJsonPins = (file) => {
@@ -588,7 +524,7 @@ function repairAgentConfigSymlinks() {
         try {
             stat = fs.lstatSync(symlinkPath);
         }
-        catch { /* missing */ }
+        catch { }
         if (stat && stat.isSymbolicLink()) {
             let current;
             try {
@@ -599,42 +535,39 @@ function repairAgentConfigSymlinks() {
             }
             const resolved = path.resolve(path.dirname(symlinkPath), current);
             if (resolved === path.resolve(userTarget))
-                continue; // already correct
+                continue;
             try {
                 fs.unlinkSync(symlinkPath);
                 createLink(userTarget, symlinkPath);
                 repaired++;
             }
-            catch { /* best-effort */ }
+            catch { }
         }
         else if (!stat) {
             try {
                 createLink(userTarget, symlinkPath);
                 repaired++;
             }
-            catch { /* best-effort */ }
+            catch { }
         }
     }
     if (repaired > 0) {
         console.error(`Repaired ${repaired} agent config symlink${repaired === 1 ? '' : 's'} to point at ~/.agents/versions/`);
     }
 }
-/** Repair node_modules/.bin/<cli> symlinks that resolve back into our own shims dir (infinite exec-loop fix). */
 export function repairSelfReferentialBinShims(versionsRoot = path.join(HISTORY_DIR, 'versions'), shimsDir = path.resolve(CACHE_DIR, 'shims'), historyDir = path.dirname(versionsRoot)) {
-    // realpath the shims dir so the prefix check survives symlinked paths (e.g. macOS /tmp -> /private/tmp).
     shimsDir = path.resolve(shimsDir);
     try {
         shimsDir = fs.realpathSync(shimsDir);
     }
     catch {
-        /* shims dir absent — leave the resolved path; nothing will match it */
     }
     let agents;
     try {
         agents = fs.readdirSync(versionsRoot);
     }
     catch {
-        return; // no versions installed yet
+        return;
     }
     let repaired = 0;
     for (const agent of agents) {
@@ -653,7 +586,7 @@ export function repairSelfReferentialBinShims(versionsRoot = path.join(HISTORY_D
                 stat = fs.lstatSync(binLink);
             }
             catch {
-                continue; // no .bin entry for this version
+                continue;
             }
             if (!stat.isSymbolicLink())
                 continue;
@@ -662,38 +595,29 @@ export function repairSelfReferentialBinShims(versionsRoot = path.join(HISTORY_D
                 real = fs.realpathSync(binLink);
             }
             catch {
-                // Dangling symlink — if it was aimed at the shims dir it's the loop
-                // residue; drop it either way so getBinaryPath reports honestly.
                 try {
                     fs.unlinkSync(binLink);
                     repaired++;
                 }
-                catch { /* best-effort */ }
+                catch { }
                 continue;
             }
             if (!path.resolve(real).startsWith(shimsDir + path.sep))
-                continue; // points at a real binary — fine
-            // Self-referential: the link resolves back into our own shims dir.
-            // findInPath does a pure-Node PATH scan (no subprocess) and already
-            // skips our shims dir, so it returns the genuine install if one exists.
+                continue;
             const realBinary = findInPath(cli, { shimsDir, historyDir });
             try {
                 fs.unlinkSync(binLink);
-                // createLink: a real symlink where the OS allows it (POSIX, and Windows
-                // with the symlink privilege), copy-fallback otherwise — so the repair
-                // lands a working binary on Windows runners without the symlink right.
                 if (realBinary)
                     createLink(realBinary, binLink);
                 repaired++;
             }
-            catch { /* best-effort */ }
+            catch { }
         }
     }
     if (repaired > 0) {
         console.error(`Repaired ${repaired} self-referential agent binary symlink${repaired === 1 ? '' : 's'} (infinite exec-loop fix).`);
     }
 }
-/** Move `src` to `dest`; when `dest` exists, merge missing entries then remove `src`. Idempotent. */
 function moveDirOnce(src, dest) {
     if (!fs.existsSync(src))
         return;
@@ -704,16 +628,14 @@ function moveDirOnce(src, dest) {
             return;
         }
         catch {
-            /* fall through to copy + remove */
         }
     }
     try {
         copyDirSkipExisting(src, dest);
         fs.rmSync(src, { recursive: true, force: true });
     }
-    catch { /* best-effort */ }
+    catch { }
 }
-/** Move `src` to `dest`; when `dest` exists, delete `src` (dest is canonical). Idempotent. */
 function moveFileOnce(src, dest) {
     if (!fs.existsSync(src))
         return;
@@ -721,7 +643,7 @@ function moveFileOnce(src, dest) {
         try {
             fs.unlinkSync(src);
         }
-        catch { /* best-effort */ }
+        catch { }
         return;
     }
     try {
@@ -733,7 +655,7 @@ function moveFileOnce(src, dest) {
             fs.copyFileSync(src, dest);
             fs.unlinkSync(src);
         }
-        catch { /* best-effort */ }
+        catch { }
     }
 }
 function rmEmptyDirTree(dir) {
@@ -748,69 +670,35 @@ function rmEmptyDirTree(dir) {
                 if (stat.isDirectory())
                     rmEmptyDirTree(child);
             }
-            catch { /* skip */ }
+            catch { }
         }
         if (fs.readdirSync(dir).length === 0)
             fs.rmdirSync(dir);
     }
-    catch { /* best-effort */ }
+    catch { }
 }
-/**
- * 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 */ }
+        catch { }
     }
 }
-/** Rename the session marker store after the product vocabulary changed from
- * favorite to bookmark. The destination wins if a newer CLI already wrote it. */
 function migrateLegacySessionMarkersToBookmarks() {
     moveFileOnce(path.join(HISTORY_DIR, 'favorites.json'), path.join(HISTORY_DIR, 'bookmarks.json'));
 }
-/**
- * Restore plugins from the cache bucket back to the user-root.
- *
- * Earlier releases moved ~/.agents/plugins/ → ~/.agents/.cache/plugins/ as part
- * of `migrateRuntimeToCache`. That was wrong: plugins are user-authored
- * resources (alongside skills/, commands/, hooks/) and belong at the user-root
- * so they're git-tracked. See issue #20.
- *
- * For each ~/.agents/.cache/plugins/<name>/ that the user already has at
- * ~/.agents/plugins/<name>/, the cache copy is left alone — the user-root copy
- * wins. For plugins only present in the cache, the directory is moved back to
- * the user-root. Idempotent.
- */
 function migratePluginsBackToUserRoot() {
     const cachePlugins = path.join(CACHE_DIR, 'plugins');
     const userPlugins = path.join(USER_DIR, 'plugins');
@@ -844,59 +732,25 @@ function migratePluginsBackToUserRoot() {
                 copyDirSkipExisting(src, dest);
                 fs.rmSync(src, { recursive: true, force: true });
             }
-            catch { /* best-effort */ }
+            catch { }
         }
     }
-    // Drop the cache plugins dir if we emptied it.
     try {
         if (fs.readdirSync(cachePlugins).length === 0)
             fs.rmdirSync(cachePlugins);
     }
-    catch { /* best-effort */ }
+    catch { }
 }
-/**
- * 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/cloud/         -> ~/.agents/.cache/cloud/
- *   ~/.agents/drive/         -> ~/.agents/.cache/drive/
- *   ~/.agents/terminals/     -> ~/.agents/.cache/terminals/
- *   ~/.agents/logs/          -> ~/.agents/.cache/logs/
- *   ~/.agents/companion/      -> ~/.agents/.cache/companion/
- *   ~/.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'));
-    // ~/.agents/plugins/ is intentionally NOT migrated — it is user-authored
-    // content (git-tracked), alongside skills/, commands/, hooks/. The reverse
-    // migration `migratePluginsBackToUserRoot` reclaims any plugins/ that prior
-    // releases moved into ~/.agents/.cache/plugins/. See issue #20.
     moveDirOnce(path.join(USER_DIR, 'cloud'), path.join(CACHE_DIR, 'cloud'));
     moveDirOnce(path.join(USER_DIR, 'drive'), path.join(CACHE_DIR, 'drive'));
     moveDirOnce(path.join(USER_DIR, 'terminals'), path.join(CACHE_DIR, 'terminals'));
     moveDirOnce(path.join(USER_DIR, 'logs'), path.join(CACHE_DIR, 'logs'));
     moveDirOnce(path.join(USER_DIR, 'companion'), path.join(CACHE_DIR, 'companion'));
     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 {
@@ -904,9 +758,8 @@ function migrateRuntimeToCache() {
             copyDirSkipExisting(oldCache, CACHE_DIR);
             fs.rmSync(oldCache, { recursive: true, force: true });
         }
-        catch { /* best-effort */ }
+        catch { }
     }
-    // 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))
@@ -917,17 +770,15 @@ function migrateRuntimeToCache() {
             copyDirSkipExisting(src, destBase);
             fs.rmSync(src, { recursive: true, force: true });
         }
-        catch { /* best-effort */ }
+        catch { }
     }
-    // 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 */ }
+        catch { }
         for (const entry of entries) {
             if (entry === 'profiles')
                 continue;
@@ -936,7 +787,6 @@ function migrateRuntimeToCache() {
             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'));
@@ -945,43 +795,31 @@ function migrateRuntimeToCache() {
     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 */ }
+            catch { }
             for (const ext of ['-shm', '-wal']) {
                 try {
                     fs.unlinkSync(src + ext);
                 }
-                catch { /* best-effort */ }
+                catch { }
             }
             return;
         }
     }
-    catch { /* best-effort */ }
+    catch { }
     if (!fs.existsSync(dest)) {
         try {
             fs.mkdirSync(path.dirname(dest), { recursive: true, mode: 0o700 });
@@ -991,16 +829,13 @@ async function mergeSqliteDb(src, dest) {
                     try {
                         fs.renameSync(src + ext, dest + ext);
                     }
-                    catch { /* best-effort */ }
+                    catch { }
                 }
             }
             return;
         }
-        catch { /* fall through to merge */ }
+        catch { }
     }
-    // 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;
@@ -1008,10 +843,6 @@ async function mergeSqliteDb(src, 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) => {
@@ -1033,58 +864,48 @@ async function mergeSqliteDb(src, dest) {
                         db.exec(ddl);
                     }
                 }
-                catch { /* table likely exists already */ }
+                catch { }
                 const quoted = '"' + name.replace(/"/g, '""') + '"';
                 try {
                     db.exec(`INSERT OR IGNORE INTO main.${quoted} SELECT * FROM src.${quoted}`);
                 }
-                catch { /* schema drift — skip table */ }
+                catch { }
             }
             try {
                 db.exec('DETACH DATABASE src');
             }
-            catch { /* best-effort */ }
+            catch { }
         }
         finally {
             try {
                 db.close();
             }
-            catch { /* best-effort */ }
+            catch { }
         }
         try {
             fs.unlinkSync(src);
         }
-        catch { /* best-effort */ }
+        catch { }
         for (const ext of ['-shm', '-wal']) {
             try {
                 fs.unlinkSync(src + ext);
             }
-            catch { /* best-effort */ }
+            catch { }
         }
     }
     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 */ }
+        catch { }
         for (const ext of ['-shm', '-wal']) {
             try {
                 fs.unlinkSync(src + ext);
             }
-            catch { /* best-effort */ }
+            catch { }
         }
     }
 }
-/**
- * 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))
@@ -1093,7 +914,7 @@ async function migrateSystemSessionsToHistory() {
     try {
         fs.mkdirSync(dest, { recursive: true, mode: 0o700 });
     }
-    catch { /* best-effort */ }
+    catch { }
     let entries;
     try {
         entries = fs.readdirSync(src, { withFileTypes: true });
@@ -1104,7 +925,6 @@ async function migrateSystemSessionsToHistory() {
     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);
@@ -1120,17 +940,8 @@ async function migrateSystemSessionsToHistory() {
         if (fs.readdirSync(src).length === 0)
             fs.rmdirSync(src);
     }
-    catch { /* best-effort */ }
+    catch { }
 }
-/**
- * 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))
@@ -1165,30 +976,14 @@ function migrateSystemTeamsToUser() {
         if (fs.readdirSync(src).length === 0)
             fs.rmdirSync(src);
     }
-    catch { /* best-effort */ }
+    catch { }
 }
-/**
- * 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))
@@ -1203,23 +998,21 @@ async function migrateSystemCacheToUserCache() {
     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 */ }
+            catch { }
             continue;
         }
         if (entry.name === 'claude-usage.json') {
             try {
                 fs.unlinkSync(s);
             }
-            catch { /* best-effort */ }
+            catch { }
             continue;
         }
         const d = path.join(CACHE_DIR, entry.name);
@@ -1234,17 +1027,13 @@ async function migrateSystemCacheToUserCache() {
         if (fs.readdirSync(src).length === 0)
             fs.rmdirSync(src);
     }
-    catch { /* best-effort */ }
+    catch { }
 }
-/**
- * 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 });
@@ -1266,13 +1055,8 @@ async function migrateSystemCloudToCache() {
         if (fs.readdirSync(srcDir).length === 0)
             fs.rmdirSync(srcDir);
     }
-    catch { /* best-effort */ }
+    catch { }
 }
-/**
- * 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))
@@ -1287,22 +1071,15 @@ function migrateLegacySwarmToTeams() {
             try {
                 fs.unlinkSync(f);
             }
-            catch { /* best-effort */ }
+            catch { }
         }
     }
     try {
         if (fs.readdirSync(src).length === 0)
             fs.rmdirSync(src);
     }
-    catch { /* best-effort */ }
+    catch { }
 }
-/**
- * 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))
@@ -1322,34 +1099,27 @@ function migrateSystemReposToPeerDirs() {
         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 */ }
+            catch { }
             continue;
         }
         try {
             fs.renameSync(s, d);
             moved++;
         }
-        catch { /* best-effort, leave in place */ }
+        catch { }
     }
     try {
         if (fs.readdirSync(src).length === 0)
             fs.rmdirSync(src);
     }
-    catch { /* best-effort */ }
+    catch { }
     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)) {
@@ -1359,13 +1129,13 @@ function dropDeadSystemArtifacts() {
                     try {
                         fs.unlinkSync(path.join(binDir, name));
                     }
-                    catch { /* best-effort */ }
+                    catch { }
                 }
             }
             if (fs.readdirSync(binDir).length === 0)
                 fs.rmdirSync(binDir);
         }
-        catch { /* best-effort */ }
+        catch { }
     }
     const shimsDir = path.join(SYSTEM_DIR, 'shims');
     if (fs.existsSync(shimsDir)) {
@@ -1373,11 +1143,8 @@ function dropDeadSystemArtifacts() {
             if (fs.readdirSync(shimsDir).length === 0)
                 fs.rmdirSync(shimsDir);
         }
-        catch { /* best-effort */ }
+        catch { }
     }
-    // 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 {
@@ -1385,7 +1152,7 @@ function dropDeadSystemArtifacts() {
                 fs.rmSync(versionsDir, { recursive: true, force: true });
             }
         }
-        catch { /* best-effort */ }
+        catch { }
     }
 }
 function containsOnlyDsStore(dir) {
@@ -1407,21 +1174,11 @@ function containsOnlyDsStore(dir) {
     }
     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', 'clis', 'permissions', 'subagents', 'profiles', 'agents', 'routines', 'webhooks',
-        // 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;
@@ -1431,25 +1188,12 @@ function warnSystemOrphans() {
     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))
@@ -1476,10 +1220,8 @@ function migrateVersionResourcesToPatterns() {
                 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];
                         }
@@ -1496,14 +1238,6 @@ function migrateVersionResourcesToPatterns() {
         console.error('Migrated agents.yaml versions: entries to pattern format');
     }
 }
-/**
- * Split the machine-local fields out of the committed central agents.yaml so it
- * becomes portable and syncs cleanly (no more skip-worktree band-aid):
- *   agents:   -> ~/.agents/.history/devices/pins-<machineId>.json  (untracked, machine-local)
- *   versions: -> ~/.agents/.history/version-resources.json         (gitignored, machine-local)
- * Then clear any externally-set skip-worktree bit. Idempotent: no-op once central
- * carries neither field. Operates on raw YAML (never through state.ts).
- */
 function migrateSplitDeviceLocalMeta() {
     const metaFile = path.join(USER_DIR, 'agents.yaml');
     if (!fs.existsSync(metaFile))
@@ -1519,49 +1253,39 @@ function migrateSplitDeviceLocalMeta() {
     const versions = meta.versions;
     const hasLocal = (!!agents && Object.keys(agents).length > 0) || (!!versions && Object.keys(versions).length > 0);
     const HEADER = '# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agi-cli\n\n';
-    // Only rewrite central when it actually carries machine-local fields — a
-    // machine whose agents.yaml is already portable-only is left untouched.
     if (hasLocal) {
-        // agents: -> machine-local pins JSON (merge, existing pins win).
         if (agents && Object.keys(agents).length > 0) {
             const pinsPath = path.join(USER_DIR, '.history', 'devices', `pins-${machineId()}.json`);
             let existing = {};
             try {
                 existing = JSON.parse(fs.readFileSync(pinsPath, 'utf-8')) || {};
             }
-            catch { /* absent */ }
+            catch { }
             fs.mkdirSync(path.dirname(pinsPath), { recursive: true });
             atomicWriteFileSync(pinsPath, JSON.stringify({ ...existing, agents: { ...agents, ...existing.agents } }, null, 2) + '\n');
         }
-        // versions: -> machine-local history JSON (merge, existing wins).
         if (versions && Object.keys(versions).length > 0) {
             const vrPath = path.join(USER_DIR, '.history', 'version-resources.json');
             let existing = {};
             try {
                 existing = JSON.parse(fs.readFileSync(vrPath, 'utf-8')) || {};
             }
-            catch { /* absent */ }
+            catch { }
             fs.mkdirSync(path.dirname(vrPath), { recursive: true });
             atomicWriteFileSync(vrPath, JSON.stringify({ ...versions, ...existing }, null, 2) + '\n');
         }
-        // Strip machine-local fields from central and rewrite (portable only) — after
-        // the pins/history writes above, so a crash never loses data.
         delete meta.agents;
         delete meta.versions;
         atomicWriteFileSync(metaFile, HEADER + yaml.stringify(meta));
     }
-    // Always clear any skip-worktree bit (idempotent, best-effort) so agents.yaml
-    // syncs cleanly on every machine — even one that had nothing to split. Runs
-    // after any rewrite so the tracked content already matches the split shape.
     try {
         execSync('git update-index --no-skip-worktree agents.yaml', { cwd: USER_DIR, stdio: 'ignore' });
     }
-    catch { /* not a git repo / bit not set */ }
+    catch { }
     if (hasLocal) {
         console.error('Split agents.yaml: agents: -> .history/devices/pins-*.json, versions: -> .history/version-resources.json');
     }
 }
-/** Move the auto-detected `default` browser profile from committed agents.yaml into the per-device file. The device file is written first so a crash cannot lose the profile; central is edited via yaml.Document to preserve comments. */
 export function migrateMachineLocalBrowserProfileOutOfCentral(userDir = USER_DIR, machine = machineId()) {
     const metaFile = path.join(userDir, 'agents.yaml');
     if (!fs.existsSync(metaFile))
@@ -1582,14 +1306,12 @@ export function migrateMachineLocalBrowserProfileOutOfCentral(userDir = USER_DIR
     const entry = browser[LEGACY_DEFAULT_BROWSER_PROFILE_NAME];
     if (entry === undefined)
         return;
-    // Device file first — a crash before central is rewritten leaves a harmless
-    // duplicate, while the reverse order would drop the profile entirely.
     const devicePath = path.join(userDir, 'devices', machine, 'agents.yaml');
     let deviceDoc = {};
     try {
         deviceDoc = yaml.parse(fs.readFileSync(devicePath, 'utf-8')) || {};
     }
-    catch { /* absent — first write */ }
+    catch { }
     const deviceBrowser = (deviceDoc.browser && typeof deviceDoc.browser === 'object' && !Array.isArray(deviceDoc.browser))
         ? deviceDoc.browser
         : {};
@@ -1599,8 +1321,6 @@ export function migrateMachineLocalBrowserProfileOutOfCentral(userDir = USER_DIR
         fs.mkdirSync(path.dirname(devicePath), { recursive: true });
         atomicWriteFileSync(devicePath, DEVICE_META_HEADER + yaml.stringify(deviceDoc));
     }
-    // Then strip it from the synced file, dropping `browser:` entirely when the
-    // machine-local entry was its only member.
     doc.deleteIn(['browser', LEGACY_DEFAULT_BROWSER_PROFILE_NAME]);
     if (Object.keys(browser).length === 1) {
         const itemsOf = () => (doc.contents?.items) ?? [];
@@ -1608,7 +1328,6 @@ export function migrateMachineLocalBrowserProfileOutOfCentral(userDir = USER_DIR
         const orphaned = idx >= 0 ? itemsOf()[idx]?.key?.commentBefore ?? undefined : undefined;
         doc.delete('browser');
         if (orphaned) {
-            // Deleting shifted the following pair down into `idx`.
             const next = itemsOf()[idx]?.key;
             if (next)
                 next.commentBefore = next.commentBefore ? `${orphaned}\n${next.commentBefore}` : orphaned;
@@ -1616,15 +1335,10 @@ export function migrateMachineLocalBrowserProfileOutOfCentral(userDir = USER_DIR
                 doc.commentBefore = orphaned;
         }
     }
-    // Everything cleared -> header only, never a bare `{}`. stringifyDoc emits a
-    // FLOW empty map for an empty root, and a later parseDocument inherits that
-    // flow and renders the whole rewritten file inline. serializeCentral guards
-    // the identical case (state.ts, `isEmpty ? META_HEADER : stringifyDoc(doc)`).
     const remaining = Object.keys(doc.toJSON() ?? {}).length;
     atomicWriteFileSync(metaFile, remaining === 0 ? DEVICE_META_HEADER : stringifyDoc(doc));
     console.error(`Migrated agents.yaml: browser '${LEGACY_DEFAULT_BROWSER_PROFILE_NAME}' profile -> devices/${machine}/agents.yaml`);
 }
-/** Rename the legacy `extras-extras/` plugin marketplace dir to `agents-extras/` in every installed version home, and rewrite cross-references in `known_marketplaces.json` and `settings.json`. */
 export function migrateExtrasExtrasToAgentsExtras(historyDir = HISTORY_DIR) {
     const versionsRoot = path.join(historyDir, 'versions');
     if (!fs.existsSync(versionsRoot))
@@ -1670,16 +1384,14 @@ export function migrateExtrasExtrasToAgentsExtras(historyDir = HISTORY_DIR) {
                     fs.renameSync(oldDir, newDir);
                     renamedDirs++;
                 }
-                catch { /* best-effort, leave orphan */ }
+                catch { }
             }
             else if (oldExists && newExists) {
-                // Previous incomplete migration — drop the stale old dir.
                 try {
                     fs.rmSync(oldDir, { recursive: true, force: true });
                 }
-                catch { /* best-effort */ }
+                catch { }
             }
-            // Rewrite marketplace.json name field inside the (now) agents-extras dir.
             const marketplaceJson = path.join(newDir, '.claude-plugin', 'marketplace.json');
             if (fs.existsSync(marketplaceJson)) {
                 try {
@@ -1690,9 +1402,8 @@ export function migrateExtrasExtrasToAgentsExtras(historyDir = HISTORY_DIR) {
                         fs.writeFileSync(marketplaceJson, JSON.stringify(parsed, null, 2) + '\n', 'utf-8');
                     }
                 }
-                catch { /* best-effort */ }
+                catch { }
             }
-            // Rewrite known_marketplaces.json key + path fields.
             const knownFile = path.join(pluginsDir, 'known_marketplaces.json');
             if (fs.existsSync(knownFile)) {
                 try {
@@ -1712,9 +1423,8 @@ export function migrateExtrasExtrasToAgentsExtras(historyDir = HISTORY_DIR) {
                         rewroteKnown++;
                     }
                 }
-                catch { /* best-effort */ }
+                catch { }
             }
-            // Rewrite settings.json enabledPlugins keys.
             const settingsFile = path.join(configDir, 'settings.json');
             if (fs.existsSync(settingsFile)) {
                 try {
@@ -1744,7 +1454,7 @@ export function migrateExtrasExtrasToAgentsExtras(historyDir = HISTORY_DIR) {
                         }
                     }
                 }
-                catch { /* best-effort */ }
+                catch { }
             }
         }
     }
@@ -1752,14 +1462,6 @@ export function migrateExtrasExtrasToAgentsExtras(historyDir = HISTORY_DIR) {
         console.error(`Renamed extras-extras → agents-extras (dirs: ${renamedDirs}, known_marketplaces: ${rewroteKnown}, settings: ${rewroteSettings})`);
     }
 }
-/**
- * Rewrite every routine YAML that carries the legacy singular `device: <value>`
- * field to the new plural `devices: [<value>]` format. Preserves all other
- * fields. Idempotent: a routine that already has `devices:` (or neither field)
- * is left untouched.
- *
- * Params default to the real routines dir; injectable for tests.
- */
 export function migrateRoutineDeviceToDevices(routinesDir) {
     const dir = routinesDir ?? path.join(USER_DIR, 'routines');
     if (!fs.existsSync(dir))
@@ -1798,21 +1500,6 @@ export function migrateRoutineDeviceToDevices(routinesDir) {
         console.error(`Migrated ${migrated} routine${migrated === 1 ? '' : 's'}: device → devices`);
     }
 }
-/**
- * Fold the legacy host-placement `remoteCwd` field into the canonical portable
- * `cwd` (RUSH-2290). Host dispatch used to read `remoteCwd` while a local run
- * inferred its cwd from `repo` — two path semantics for one concept. The runner
- * now resolves every placement from `cwd`, so this idempotently rewrites the
- * field:
- *
- * - `remoteCwd` present, no `cwd`  → rename to `cwd`.
- * - both present and equal          → drop the duplicate `remoteCwd`.
- * - both present and DIFFERENT       → conflict: leave BOTH fields untouched so
- *   the migration never silently chooses one; `validateJob`/`doctor` then flag the
- *   pair and the routine stays paused rather than running against a guessed path.
- *
- * Idempotent: a file with only `cwd` (already migrated) is skipped.
- */
 export function migrateRoutineRemoteCwdToCwd(routinesDir) {
     const dir = routinesDir ?? path.join(USER_DIR, 'routines');
     if (!fs.existsSync(dir))
@@ -1836,19 +1523,18 @@ export function migrateRoutineRemoteCwdToCwd(routinesDir) {
             continue;
         const remote = doc.remoteCwd;
         if (typeof remote !== 'string' || !remote.trim()) {
-            // A malformed legacy value is not something to fold — drop it and move on.
             delete doc.remoteCwd;
             atomicWriteFileSync(filePath, yaml.stringify(doc));
             continue;
         }
         if ('cwd' in doc) {
             if (doc.cwd === remote) {
-                delete doc.remoteCwd; // duplicate — dedupe to the canonical field
+                delete doc.remoteCwd;
                 atomicWriteFileSync(filePath, yaml.stringify(doc));
                 migrated++;
             }
             else {
-                conflicts++; // leave both fields; validateJob/doctor pause the conflict
+                conflicts++;
             }
             continue;
         }
@@ -1864,20 +1550,10 @@ export function migrateRoutineRemoteCwdToCwd(routinesDir) {
         console.error(`${conflicts} routine${conflicts === 1 ? '' : 's'} have conflicting remoteCwd/cwd — left paused for manual repair (migration_conflict)`);
     }
 }
-/**
- * Pause every currently-active routine whose execution context no longer
- * resolves ready (RUSH-2290). An agent/workflow routine with no project/cwd, a
- * missing directory, or a non-portable path used to fire and fail every tick —
- * the mass auth_failed / untrusted-home storm this ticket exists to stop. After
- * the fold, such a routine is deactivated on THIS device (only), preventing it
- * from being scheduled until `agents routines doctor --all --fix` (or a repair +
- * `resume`) makes it ready. Never materializes a device manifest that does not
- * yet exist, and never touches command routines (they run in the target home).
- */
 function pauseUnreadyEnabledRoutines() {
     const enabled = enabledRoutineNames();
     if (enabled === null)
-        return; // no manifest yet — nothing activated to pause
+        return;
     const enabledSet = new Set(enabled);
     const paused = [];
     for (const job of listJobs()) {
@@ -1888,7 +1564,7 @@ function pauseUnreadyEnabledRoutines() {
             ready = validateJob(job).length === 0 && evaluateActivationReadiness(job).ready;
         }
         catch {
-            ready = true; // never pause a routine because readiness itself threw
+            ready = true;
         }
         if (!ready)
             paused.push(job.name);
@@ -1900,23 +1576,6 @@ function pauseUnreadyEnabledRoutines() {
     console.error(`Paused ${paused.length} routine${paused.length === 1 ? '' : 's'} with an unresolved execution context ` +
         `(run 'agents routines doctor --all' to see why): ${paused.join(', ')}`);
 }
-/**
- * Fold the legacy watchdog enable sentinel into the `watchdog.enabled` config.
- *
- * The always-on watchdog used to be gated by a presence sentinel at
- * `<runtime-state>/watchdog/enabled`; it is now a daemon-owned timer (RUSH-2495)
- * gated by the `watchdog.enabled` device-config flag — the same flag
- * `agents watchdog enable` writes. A user who had run `agents watchdog enable`
- * under the old build has that file on disk; without this, upgrading would
- * silently drop them back to OFF (the nudge just stops), the worst failure mode
- * for a "survives reboots" feature. If the sentinel exists, set
- * `watchdog.enabled: true`, then delete the sentinel so this runs exactly once.
- * If setting it fails, the sentinel is left in place so a later run retries
- * rather than silently losing the opt-in.
- *
- * The setter seam is injectable so the migration is unit-testable without
- * touching the real device config.
- */
 export function migrateWatchdogSentinelToConfig(sentinelPath = path.join(CACHE_DIR, 'state', 'watchdog', 'enabled'), enable = (value) => setConfigValue('watchdog.enabled', value)) {
     if (!fs.existsSync(sentinelPath))
         return;
@@ -1930,16 +1589,9 @@ export function migrateWatchdogSentinelToConfig(sentinelPath = path.join(CACHE_D
     try {
         fs.rmSync(sentinelPath);
     }
-    catch { /* already gone */ }
+    catch { }
     console.error('Migrated watchdog: legacy enable sentinel → watchdog.enabled config (kept enabled)');
 }
-/**
- * Rename cli/ → clis/ in each of the given `.agents/` directories.
- *
- * One-way, idempotent: no-op when src is absent. Throws when both
- * `<dir>/cli` and `<dir>/clis` exist — the user must resolve the conflict
- * manually before proceeding. Exported for unit-testing with temp dirs.
- */
 export function migrateCliDirToClis(agentsDirs) {
     for (const agentsDir of agentsDirs) {
         const src = path.join(agentsDir, 'cli');
@@ -1953,17 +1605,6 @@ export function migrateCliDirToClis(agentsDirs) {
         fs.renameSync(src, dest);
     }
 }
-/**
- * Migrate owner identity into humans.yaml.
- *
- * Sources (both are optional; migration is a no-op when neither exists):
- *   1. ~/.agents/agents.yaml notify.owner.{channel,to} — short-form notify config.
- *   2. ~/.agents/owner.md  — YAML frontmatter with name/timezone/quiet_hours/channels/policy.
- *
- * Writes ~/.agents/humans.yaml (version: 1) when at least one source is
- * present, then removes the migrated keys. Idempotent: exits immediately when
- * humans.yaml already exists.
- */
 function migrateHumans() {
     const humansFile = path.join(USER_DIR, 'humans.yaml');
     if (fs.existsSync(humansFile))
@@ -1977,7 +1618,6 @@ function migrateHumans() {
     let ownerDefaultSeverity;
     let ownerChannels;
     let ownerPolicy;
-    // 1. Read notify.owner from agents.yaml.
     if (fs.existsSync(agentsYamlPath)) {
         try {
             const raw = fs.readFileSync(agentsYamlPath, 'utf-8');
@@ -1990,9 +1630,8 @@ function migrateHumans() {
                 notifyOwner = { channel, to };
             }
         }
-        catch { /* best-effort */ }
+        catch { }
     }
-    // 2. Read YAML frontmatter from owner.md.
     if (fs.existsSync(ownerMdPath)) {
         try {
             const raw = fs.readFileSync(ownerMdPath, 'utf-8');
@@ -2015,9 +1654,8 @@ function migrateHumans() {
                 }
             }
         }
-        catch { /* best-effort */ }
+        catch { }
     }
-    // Only write if we have at least one piece of owner data.
     if (!notifyOwner && !ownerName && !ownerTimezone && !ownerQuietHours && !ownerDefaultSeverity && !ownerChannels && !ownerPolicy)
         return;
     const humansDoc = { version: 1 };
@@ -2046,7 +1684,6 @@ function migrateHumans() {
         console.error(`humans.yaml migration: could not write (${err.message})`);
         return;
     }
-    // Remove notify.owner from agents.yaml after successful migration.
     if (notifyOwner && fs.existsSync(agentsYamlPath)) {
         try {
             const raw = fs.readFileSync(agentsYamlPath, 'utf-8');
@@ -2057,23 +1694,11 @@ function migrateHumans() {
                 if (notifyNode.items.length === 0)
                     doc.delete('notify');
             }
-            // `flowCollectionPadding: false` keeps committed flow sequences unpadded
-            // (`[a, b]`, not `[ a, b ]`) so re-emitting agents.yaml here does not dirty
-            // the synced ~/.agents tree and block pulls (RUSH-2505).
             fs.writeFileSync(agentsYamlPath, stringifyDoc(doc), 'utf-8');
         }
-        catch { /* best-effort — leave the old key if we can't rewrite */ }
+        catch { }
     }
 }
-/**
- * An earlier agents-cli release put Cursor's file-backed OAuth token at
- * ~/.config/cursor/auth.json. Current Cursor actually writes the file store to
- * HOME-relative ~/.cursor/auth.json. Copy that legacy token into the active
- * account's version home. The active account
- * is the home the ~/.cursor symlink currently targets. Idempotent: skips when
- * the home already has its own token, and a no-op for unmanaged Cursor installs
- * (where ~/.cursor is a real dir, not a symlink into a version home).
- */
 export function seedActiveCursorLoginPerVersion() {
     const realHome = process.env.AGENTS_REAL_HOME || os.homedir();
     const globalAuth = path.join(realHome, '.config', 'cursor', 'auth.json');
@@ -2081,14 +1706,12 @@ export function seedActiveCursorLoginPerVersion() {
     try {
         if (!fs.existsSync(globalAuth))
             return;
-        // ~/.cursor -> .../versions/cursor/<version>/home/.cursor ; the version home
-        // is that link's parent directory.
         const link = fs.readlinkSync(path.join(realHome, '.cursor'));
         const resolved = path.isAbsolute(link) ? link : path.resolve(realHome, link);
         versionHome = path.dirname(resolved);
     }
     catch {
-        return; // not a symlink (unmanaged install) or unreadable — nothing to seed
+        return;
     }
     if (!versionHome.includes(path.join('versions', 'cursor')))
         return;
@@ -2099,25 +1722,8 @@ export function seedActiveCursorLoginPerVersion() {
         fs.mkdirSync(path.dirname(dest), { recursive: true });
         fs.copyFileSync(globalAuth, dest);
     }
-    catch { /* best-effort — a failed seed just means one re-login */ }
+    catch { }
 }
-/**
- * Fold the pre-markdown Kimi subagent layout out of every kimi version home.
- *
- * agents-cli used to write each Kimi subagent as a `<name>.yaml` +
- * `<name>.system.md` pair plus a managed `_agents-cli.yaml` index, against the
- * agentspec of `kimi-cli` — a different product from the `kimi-code` harness we
- * install, which never read any of it. Those files are inert, but not harmless:
- * `<name>.system.md` ends in `.md`, so the subagent enumerator would surface it
- * as a phantom subagent named `<name>.system`, and kimi-code logs
- * `Missing frontmatter` for it once per session.
- *
- * This is the ONE place that knows about the old layout — the registry target
- * describes only the current `<name>.md` shape. A pair is identified by its
- * signature (a `<name>.yaml` with a sibling `<name>.system.md`), so a subagent a
- * user legitimately named e.g. `foo.system` is never touched: it has no
- * `foo.yaml` beside it. Idempotent; a no-op once the dirs are clean.
- */
 export function migrateKimiSubagentsToMarkdown(versionsDir) {
     const kimiVersions = path.join(versionsDir ?? path.join(HISTORY_DIR, 'versions'), 'kimi');
     let versions;
@@ -2125,7 +1731,7 @@ export function migrateKimiSubagentsToMarkdown(versionsDir) {
         versions = fs.readdirSync(kimiVersions);
     }
     catch {
-        return; // no kimi installed
+        return;
     }
     let removed = 0;
     for (const version of versions) {
@@ -2141,14 +1747,12 @@ export function migrateKimiSubagentsToMarkdown(versionsDir) {
         const doomed = [];
         for (const entry of entries) {
             if (entry === '_agents-cli.yaml') {
-                doomed.push(entry); // reserved managed index, only ever written by us
+                doomed.push(entry);
                 continue;
             }
             if (!entry.endsWith('.yaml'))
                 continue;
             const base = entry.slice(0, -'.yaml'.length);
-            // Only a genuine legacy pair — a bare .yaml with no sibling prompt is not
-            // ours to delete.
             if (!present.has(`${base}.system.md`))
                 continue;
             doomed.push(entry, `${base}.system.md`);
@@ -2159,7 +1763,6 @@ export function migrateKimiSubagentsToMarkdown(versionsDir) {
                 removed++;
             }
             catch {
-                // leave it; the next run retries
             }
         }
     }
@@ -2167,17 +1770,6 @@ export function migrateKimiSubagentsToMarkdown(versionsDir) {
         console.error(`Removed ${removed} pre-markdown Kimi subagent file(s); run 'agents sync kimi' to write the new format`);
     }
 }
-/**
- * Remove the compiled "project" ruleset the compiler used to write into $HOME
- * (RUSH-2725). `compileRulesForProject` treated any cwd with `.agents/rules`
- * as a project — and the user layer at ~/.agents satisfies that test — so it
- * wrote ~/AGENTS.md plus per-agent symlinks, and every session under $HOME
- * then loaded the entire ruleset twice (global memory + "project" memory).
- * The compiler now refuses reserved roots; this removes the artifact already
- * on disk. Only files we provably own are touched: an AGENTS.md carrying the
- * compiled-project header, symlinks pointing at it, and copy-fallback files
- * (symlink-less filesystems) carrying the same header.
- */
 export function removeHomeCompiledProjectRules(homeDir = HOME) {
     const agentsPath = path.join(homeDir, 'AGENTS.md');
     let agentsLstat;
@@ -2224,11 +1816,10 @@ export function removeHomeCompiledProjectRules(homeDir = HOME) {
                 try {
                     fs.unlinkSync(linkPath);
                 }
-                catch { /* next run retries */ }
+                catch { }
             }
         }
         else if (lstat.isFile()) {
-            // Symlink-less filesystems got a copy of AGENTS.md instead — same header.
             let copy = '';
             try {
                 copy = fs.readFileSync(linkPath, 'utf8');
@@ -2240,18 +1831,16 @@ export function removeHomeCompiledProjectRules(homeDir = HOME) {
                 try {
                     fs.unlinkSync(linkPath);
                 }
-                catch { /* next run retries */ }
+                catch { }
             }
         }
     }
     try {
         fs.unlinkSync(agentsPath);
     }
-    catch { /* next run retries */ }
+    catch { }
 }
-/** Run all idempotent migrations. Safe to call multiple times. */
 export async function runMigration() {
-    // MUST run first: every other migrator reads SYSTEM_DIR (the new path).
     foldLegacySystemRepo();
     const cliMigrateDirs = [USER_DIR, SYSTEM_DIR];
     const projectDotAgents = path.join(process.cwd(), '.agents');
@@ -2266,10 +1855,7 @@ export async function runMigration() {
     migratePromptcutsIntoHooks();
     migrateSystemVersionsToUser();
     mergeOverlappingVersionHomes();
-    // Cursor runs now isolate the login per version home; preserve the current
-    // login by seeding the active home's token from the legacy global copy.
     seedActiveCursorLoginPerVersion();
-    // Drop the pre-markdown Kimi subagent files; the registry now writes <name>.md.
     migrateKimiSubagentsToMarkdown();
     migrateRunsIntoRoutines();
     migrateTrashToHidden();
@@ -2285,40 +1871,14 @@ export async function runMigration() {
     foldUserHooksYamlIntoAgentsYaml();
     foldBrowserProfilesIntoAgentsYaml();
     migrateVersionResourcesToPatterns();
-    // Split machine-local fields (agents:/versions:) out of the committed central
-    // agents.yaml. After migrateVersionResourcesToPatterns so versions: is already
-    // in pattern form when it moves to the history file.
     migrateSplitDeviceLocalMeta();
-    // Same split, one level deeper: `browser` stays central (named profiles are
-    // fleet config) but its auto-detected `default` entry is machine-local and was
-    // left behind in the synced file, keeping every box dirty. After
-    // migrateSplitDeviceLocalMeta so the device file is already in its canonical
-    // location before this merges an entry into it.
     migrateMachineLocalBrowserProfileOutOfCentral();
-    // Converge the device-config/pins stores: fold the central
-    // fleet.devices.<name>.config block + legacy auto-launch.json into the
-    // per-device docs' config:, and extract pins from tracked docs into the
-    // untracked pins JSON. After migrateSplitDeviceLocalMeta so the pins file is
-    // in its canonical location. Also invoked on daemon boot and on the first
-    // device-config read/write in a process, so sentinel'd installs (which skip
-    // this whole run) still converge.
     migrateDeviceConfigStores();
-    // Bucket moves: collapse runtime state into ~/.agents/.history and ~/.agents/.cache.
     migrateRuntimeToHistory();
     migrateLegacySessionMarkersToBookmarks();
     migrateRuntimeToCache();
-    // Restore plugins (user-authored) from cache back to user-root. Runs AFTER
-    // migrateRuntimeToCache so any legacy plugins/ still at the user-root from
-    // very-old layouts have already been handled.
     migratePluginsBackToUserRoot();
-    // Browser captures: fold the legacy global browser/sessions/<task> root into the
-    // per-profile browser/<profile>/sessions/<task> layout. After the cache moves so
-    // the browser dir is at its canonical .cache location.
     foldBrowserSessionsIntoProfiles();
-    // 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();
@@ -2328,38 +1888,15 @@ export async function runMigration() {
     await migrateSystemCloudToCache();
     dropDeadSystemArtifacts();
     warnSystemOrphans();
-    // Rename the legacy extras-extras marketplace dir to agents-extras across every
-    // installed version-home. Runs after migrateRuntimeToHistory so the version
-    // homes are at their canonical HISTORY_DIR location.
     migrateExtrasExtrasToAgentsExtras();
-    // Rewrite routine YAML files: singular `device:` -> plural `devices: []`.
     migrateRoutineDeviceToDevices();
-    // Fold legacy host-placement `remoteCwd` into the canonical portable `cwd`.
     migrateRoutineRemoteCwdToCwd();
     migrateLegacyRoutineActivation();
-    // Fold the legacy watchdog enable sentinel into `watchdog.enabled` config so a
-    // user who opted in under the old build stays opted in after upgrading.
     migrateWatchdogSentinelToConfig();
-    // Delete the compiled "project" ruleset older builds wrote into $HOME — the
-    // duplicate-injection artifact of RUSH-2725. The compiler no longer writes
-    // it; this cleans up what is already on every machine.
     removeHomeCompiledProjectRules();
-    // Deactivate any routine whose execution context no longer resolves ready, so
-    // an anchor-less agent/workflow routine cannot keep firing-and-failing after the
-    // fold (RUSH-2290). Runs AFTER the tick/watchdog routines are added so those
-    // (command/home) routines are evaluated in their final shape.
     pauseUnreadyEnabledRoutines();
-    // Symlink repair runs LAST so it can find the post-move version homes.
     repairAgentConfigSymlinks();
-    // Repair self-referential node_modules/.bin/<cli> symlinks (the droid
-    // infinite-exec-loop). Also runs after the bucket moves so it scans the
-    // canonical HISTORY_DIR/versions tree.
     repairSelfReferentialBinShims();
-    // Version-skew one-shot (RUSH-2435): retrofit the current pane-died hook
-    // onto any managed tmux session an older binary left with a stale one. Runs
-    // at upgrade time in addition to the daemon-startup call (daemon.ts) so a
-    // machine that upgrades without immediately restarting its daemon still
-    // repairs on the next `agents` invocation. Idempotent/non-destructive.
     try {
         const { reconcileSessionHooks } = await import('../tmux/session.js');
         const { isTmuxInstalled } = await import('../tmux/binary.js');
@@ -2367,15 +1904,11 @@ export async function runMigration() {
             await reconcileSessionHooks();
     }
     catch {
-        // best-effort — a migration must never fail because tmux wasn't reachable
     }
-    // PHNX-3940 T7: report leftover per-account installations. Dry-run only —
-    // moving homes requires an explicit `agents accounts migrate --apply`.
     try {
         const { reportAccountSlotMigrationOnUpgrade } = await import('../accounts/migrate.js');
         await reportAccountSlotMigrationOnUpgrade();
     }
     catch {
-        // best-effort — a corrupt install must not block the rest of upgrade
     }
 }