@phnx-labs/agents-cli 1.15.0 → 1.16.0

package/dist/lib/session/discover.js

@@ -13,7 +13,7 @@ import * as crypto from 'crypto';
 import * as readline from 'readline';
 import { execFile } from 'child_process';
 import { promisify } from 'util';
-import { getAgentsDir } from '../state.js';
+import { getAgentsDir, getUserAgentsDir } from '../state.js';
 const execFileAsync = promisify(execFile);
 import { AGENTS, getCliVersion } from '../agents.js';
 import { walkForFiles } from '../fs-walk.js';
@@ -22,6 +22,13 @@ import { SESSION_AGENTS } from './types.js';
 import { extractSessionTopic } from './prompt.js';
 import { getDB, getScanStampByPath, getScanStampsForPaths, recordScans, syncLabels, upsertSessionsBatch, querySessions, countSessions, ftsSearch, } from './db.js';
 const HOME = os.homedir();
+// Versions can live under either repo: the user repo (current canonical
+// location, ~/.agents/versions/) or the system repo (legacy / npm-shipped,
+// ~/.agents-system/versions/). Both must be scanned — sessions written by
+// any installed version end up in that version's projects/ dir, and the user
+// can be running one repo's version while another repo holds older versions
+// whose JSONLs the user still wants to search.
+const VERSIONS_ROOTS = [getUserAgentsDir(), getAgentsDir()];
 const AGENTS_DIR = getAgentsDir();
 const RUSH_SESSIONS_DIR = path.join(HOME, '.rush', 'sessions');
 const HERMES_SESSIONS_DIR = path.join(HOME, '.hermes', 'sessions');
@@ -184,8 +191,10 @@ export function getAgentSessionDirs(agent, subdir) {
         dirs.push(dir);
     }
     addDir(path.join(HOME, `.${agent}`, subdir));
-    const versionsBase = path.join(AGENTS_DIR, 'versions', agent);
-    if (fs.existsSync(versionsBase)) {
+    for (const root of VERSIONS_ROOTS) {
+        const versionsBase = path.join(root, 'versions', agent);
+        if (!fs.existsSync(versionsBase))
+            continue;
         try {
             for (const version of fs.readdirSync(versionsBase)) {
                 addDir(path.join(versionsBase, version, 'home', `.${agent}`, subdir));
@@ -219,8 +228,10 @@ function getClaudeAccount() {
         path.join(HOME, '.claude', '.claude.json'),
         path.join(HOME, '.claude.json'),
     ];
-    const versionsBase = path.join(AGENTS_DIR, 'versions', 'claude');
-    if (fs.existsSync(versionsBase)) {
+    for (const root of VERSIONS_ROOTS) {
+        const versionsBase = path.join(root, 'versions', 'claude');
+        if (!fs.existsSync(versionsBase))
+            continue;
         try {
             for (const version of fs.readdirSync(versionsBase)) {
                 candidates.push(path.join(versionsBase, version, 'home', '.claude', '.claude.json'));
@@ -405,8 +416,10 @@ function getCodexAccount() {
     if (cachedCodexAccount !== undefined)
         return cachedCodexAccount || undefined;
     const candidates = [path.join(HOME, '.codex', 'auth.json')];
-    const versionsBase = path.join(AGENTS_DIR, 'versions', 'codex');
-    if (fs.existsSync(versionsBase)) {
+    for (const root of VERSIONS_ROOTS) {
+        const versionsBase = path.join(root, 'versions', 'codex');
+        if (!fs.existsSync(versionsBase))
+            continue;
         try {
             for (const version of fs.readdirSync(versionsBase)) {
                 candidates.push(path.join(versionsBase, version, 'home', '.codex', 'auth.json'));
@@ -1451,22 +1464,24 @@ function normalizeVersion(version) {
     const trimmed = version?.trim();
     return trimmed ? trimmed : undefined;
 }
-/** Extract the version number from a managed ~/.agents/versions/<agent>/<version>/... path. */
+/** Extract the version number from a managed versions/<agent>/<version>/... path under either repo. */
 function extractVersionFromManagedPath(agent, sourcePath) {
     if (!sourcePath)
         return undefined;
     const candidates = [sourcePath, safeRealpathSync(sourcePath) || ''];
-    const marker = `/.agents/versions/${agent}/`;
+    const markers = [`/.agents/versions/${agent}/`, `/.agents-system/versions/${agent}/`];
     for (const candidate of candidates) {
         if (!candidate)
             continue;
         const normalized = candidate.split(path.sep).join('/');
-        const start = normalized.indexOf(marker);
-        if (start === -1)
-            continue;
-        const version = normalized.slice(start + marker.length).split('/')[0];
-        if (version)
-            return version;
+        for (const marker of markers) {
+            const start = normalized.indexOf(marker);
+            if (start === -1)
+                continue;
+            const version = normalized.slice(start + marker.length).split('/')[0];
+            if (version)
+                return version;
+        }
     }
     return undefined;
 }

package/dist/lib/session/team-filter.js

@@ -9,12 +9,12 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { getAgentsDir } from '../state.js';
+import { getTeamsAgentsDir } from '../state.js';
 const HOME = os.homedir();
 // Default path; tests can override via AGENTS_TEAMS_DIR env var.
 /** Resolve the directory containing per-session team metadata files. */
 function teamsAgentsDir() {
-    return process.env.AGENTS_TEAMS_DIR ?? path.join(getAgentsDir(), 'teams', 'agents');
+    return process.env.AGENTS_TEAMS_DIR ?? getTeamsAgentsDir();
 }
 /**
  * Determine whether `session` was spawned by `agents teams`.

package/dist/lib/shims.d.ts

@@ -58,7 +58,7 @@ export declare function promptConflictStrategy(conflictInfos: ConflictInfo[]): P
  *   v8 — versions moved from ~/.agents-system/versions to ~/.agents/versions
  *        (two-repo split: system = shipped defaults, user = operational state).
  */
-export declare const SHIM_SCHEMA_VERSION = 8;
+export declare const SHIM_SCHEMA_VERSION = 9;
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.
@@ -90,7 +90,7 @@ export declare function removeShim(agent: AgentId): boolean;
  *   v6 — versions moved from ~/.agents-system/versions to ~/.agents/versions
  *        (two-repo split: system = shipped defaults, user = operational state).
  */
-export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 6;
+export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 7;
 /**
  * Generate a versioned alias script that directly execs a specific version.
  * e.g., claude@2.0.65 -> directly runs that version's binary

package/dist/lib/shims.js

@@ -172,7 +172,7 @@ export async function promptConflictStrategy(conflictInfos) {
  *   v8 — versions moved from ~/.agents-system/versions to ~/.agents/versions
  *        (two-repo split: system = shipped defaults, user = operational state).
  */
-export const SHIM_SCHEMA_VERSION = 8;
+export const SHIM_SCHEMA_VERSION = 9;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
 /**
@@ -287,7 +287,7 @@ if [ -z "$VERSION" ]; then
   exit 1
 fi
 
-VERSION_DIR="$AGENTS_USER_DIR/versions/$AGENT/$VERSION"
+VERSION_DIR="$AGENTS_USER_DIR/.history/versions/$AGENT/$VERSION"
 BINARY="$VERSION_DIR/node_modules/.bin/$CLI_COMMAND"
 
 # Auto-install if not present
@@ -380,7 +380,7 @@ export function removeShim(agent) {
  *   v6 — versions moved from ~/.agents-system/versions to ~/.agents/versions
  *        (two-repo split: system = shipped defaults, user = operational state).
  */
-export const VERSIONED_ALIAS_SCHEMA_VERSION = 6;
+export const VERSIONED_ALIAS_SCHEMA_VERSION = 7;
 /** Internal marker string used to embed the schema version in versioned alias scripts. */
 const VERSIONED_ALIAS_VERSION_MARKER = 'agents-versioned-alias-version:';
 // The version string is interpolated into a generated bash script and into
@@ -405,14 +405,14 @@ export function generateVersionedAliasScript(agent, version) {
         ? `
 # Claude stores OAuth credentials in the macOS keychain. Scope them to this
 # version's config directory so direct aliases also switch the live account.
-export CLAUDE_CONFIG_DIR="$HOME/.agents/versions/${agent}/${version}/home/${configDirName}"
+export CLAUDE_CONFIG_DIR="$HOME/.agents/.history/versions/${agent}/${version}/home/${configDirName}"
 `
         : agent === 'codex'
             ? `
 # Codex reads its config (approval_policy, sandbox_mode, MCP servers, rules)
 # from CODEX_HOME. Point direct aliases at the versioned home so permissions
 # and rules written by agents-cli actually take effect.
-export CODEX_HOME="$HOME/.agents/versions/${agent}/${version}/home/${configDirName}"
+export CODEX_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/${configDirName}"
 `
             : '';
     const launchArgs = agent === 'codex' ? ' -c check_for_update_on_startup=false' : '';
@@ -421,7 +421,7 @@ export CODEX_HOME="$HOME/.agents/versions/${agent}/${version}/home/${configDirNa
 # ${VERSIONED_ALIAS_VERSION_MARKER} ${VERSIONED_ALIAS_SCHEMA_VERSION}
 # Direct alias for ${agentConfig.name}@${version}
 
-BINARY="$HOME/.agents/versions/${agent}/${version}/node_modules/.bin/${agentConfig.cliCommand}"
+BINARY="$HOME/.agents/.history/versions/${agent}/${version}/node_modules/.bin/${agentConfig.cliCommand}"
 
 if [ ! -x "$BINARY" ]; then
   echo "agents: ${agent}@${version} not installed" >&2

package/dist/lib/skills.js

@@ -11,7 +11,7 @@ import * as path from 'path';
 import * as os from 'os';
 import * as yaml from 'yaml';
 import { SKILLS_CAPABLE_AGENTS, ensureSkillsDir } from './agents.js';
-import { getUserSkillsDir, getSkillsDir as getSystemSkillsDir, getProjectAgentsDir, getEnabledExtraRepos } from './state.js';
+import { getUserSkillsDir, getSkillsDir as getSystemSkillsDir, getProjectAgentsDir, getEnabledExtraRepos, getTrashSkillsDir } from './state.js';
 import { getEffectiveHome, getVersionHomePath, listInstalledVersions } from './versions.js';
 import { emit } from './events.js';
 const HOME = os.homedir();
@@ -569,7 +569,11 @@ export function removeSkillFromVersion(agent, version, skillName) {
         return { success: true };
     }
     try {
-        fs.rmSync(target, { recursive: true, force: true });
+        const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const trashDir = path.join(getTrashSkillsDir(), agent, version, skillName);
+        const trashDest = path.join(trashDir, stamp);
+        fs.mkdirSync(trashDir, { recursive: true, mode: 0o700 });
+        fs.renameSync(target, trashDest);
     }
     catch (err) {
         return { success: false, error: err.message };

package/dist/lib/state.d.ts

@@ -2,11 +2,18 @@
  * Filesystem layout and persistent state for agents-cli.
  *
  * Two roots:
- *  - ~/.agents-system/ — system repo (npm-shipped resources and canonical read-side defaults)
- *  - ~/.agents/        — user repo  (user-authored commands, skills, hooks, rules, mcp,
- *                                    permissions, subagents, profiles, secrets, agents.yaml,
- *                                    packages, routines, runs, versions, shims, backups, plugins,
- *                                    drive, trash)
+ *  - ~/.agents-system/ — system repo (npm-shipped resources, read-only defaults)
+ *  - ~/.agents/        — user repo (resources + agents.yaml + operational state)
+ *
+ * Inside ~/.agents/, top-level paths hold ONLY resources + agents.yaml.
+ * Operational state lives in two sibling buckets:
+ *
+ *  - ~/.agents/.history/ — durable runtime data (sessions, versions, runs,
+ *                          teams/agents, trash, backups). Backed up by
+ *                          `agents repo push`.
+ *  - ~/.agents/.cache/   — regenerable runtime data (shims, packages, helpers
+ *                          for daemon/pty, terminals, cloud, drive, browser
+ *                          chrome-data, logs, swarmify). Gitignored.
  *
  * Resolution precedence for resources: project > user > system.
  * Every module that needs a path or reads/writes agents.yaml goes through here.
@@ -48,8 +55,21 @@ export declare function getMcpDir(): string;
 export declare function getPermissionsDir(): string;
 /** Path to subagent definition directories — system repo. */
 export declare function getSubagentsDir(): string;
-/** Path to ~/.agents-system/promptcuts.yaml. */
+/** Path to ~/.agents-system/hooks/promptcuts.yaml (system defaults). */
 export declare function getPromptcutsPath(): string;
+/**
+ * Resolve the effective promptcuts file: user file if it exists, otherwise
+ * the system file. Use this for callers that need a single path (doctor
+ * diff, displaying which file is in play). Callers that need the merged
+ * shortcut set should use readMergedPromptcuts() instead.
+ */
+export declare function getEffectivePromptcutsPath(): string;
+/**
+ * Read promptcuts from system + user with user precedence. Returns the
+ * merged `shortcuts` map. Same layering model as parseHookManifest().
+ * Returns an empty object when neither file exists or both fail to parse.
+ */
+export declare function readMergedPromptcuts(): Record<string, unknown>;
 /** Path to the legacy MCP config JSON. */
 export declare function getMcpConfigPath(): string;
 /** Path to the global instructions file. */
@@ -71,26 +91,78 @@ export declare function getUserPermissionsDir(): string;
 export declare function getUserSubagentsDir(): string;
 export declare function getUserSecretsDir(): string;
 export declare function getUserPromptcutsPath(): string;
-/** Path to cloned packages (~/.agents/packages/). */
+/** Bucket root for durable runtime data (~/.agents/.history/). */
+export declare function getHistoryDir(): string;
+/** Bucket root for regenerable runtime data (~/.agents/.cache/). */
+export declare function getCacheDir(): string;
+/** Path to cloned packages (~/.agents/.cache/packages/). */
 export declare function getPackagesDir(): string;
 /** Path to routine YAML definitions (~/.agents/routines/). */
 export declare function getRoutinesDir(): string;
-/** Path to routine execution logs (~/.agents/runs/). */
+/** Path to routine execution logs (~/.agents/.history/runs/). */
 export declare function getRunsDir(): string;
-/** Path to installed agent CLI binaries (~/.agents/versions/). */
+/** Path to installed agent CLI binaries (~/.agents/.history/versions/). */
 export declare function getVersionsDir(): string;
-/** Path to version-switching shim scripts (~/.agents/shims/). */
+/** Path to version-switching shim scripts (~/.agents/.cache/shims/). */
 export declare function getShimsDir(): string;
-/** Path to config backups (~/.agents/backups/). */
+/** Path to per-agent installed CLI binaries (~/.agents/.cache/bin/). */
+export declare function getBinDir(): string;
+/** Path to config backups (~/.agents/.history/backups/). */
 export declare function getBackupsDir(): string;
-/** Path to plugin bundles (~/.agents/plugins/). */
+/** Path to plugin bundles (~/.agents/.cache/plugins/). */
 export declare function getPluginsDir(): string;
-/** Path to synced remote session data (~/.agents/drive/). */
+/** Path to synced remote session data (~/.agents/.cache/drive/). */
 export declare function getDriveDir(): string;
-/** Path to soft-deleted resources (~/.agents/trash/). */
+/** Path to soft-deleted resources (~/.agents/.history/trash/). */
 export declare function getTrashDir(): string;
+/** Path to local session indexer storage (~/.agents/.history/sessions/). */
+export declare function getSessionsDir(): string;
+/** Path to the session index database (~/.agents/.history/sessions.db). */
+export declare function getSessionsDbPath(): string;
+/** Path to teams config + registry (~/.agents/teams/). */
+export declare function getTeamsDir(): string;
+/** Path to teams execution history (~/.agents/.history/teams/agents/). */
+export declare function getTeamsAgentsDir(): string;
+/** Path to cloud dispatch cache (~/.agents/.cache/cloud/). */
+export declare function getCloudDir(): string;
+/** Path to terminal session metadata (~/.agents/.cache/terminals/). */
+export declare function getTerminalsDir(): string;
+/** Path to runtime logs (~/.agents/.cache/logs/). */
+export declare function getLogsDir(): string;
+/** Path to per-process runtime state (~/.agents/.cache/state/). */
+export declare function getRuntimeStateDir(): string;
+/** Path to swarmify-extension scratch (~/.agents/.cache/swarmify/). */
+export declare function getSwarmifyDir(): string;
+/** Path to browser runtime data — chrome-data, pids (~/.agents/.cache/browser/). */
+export declare function getBrowserRuntimeDir(): string;
+/** Path to helper subprocess scratch (~/.agents/.cache/helpers/). */
+export declare function getHelpersDir(): string;
+/** Path to scheduler daemon scratch (~/.agents/.cache/helpers/daemon/). */
+export declare function getDaemonDir(): string;
+/** Path to PTY server scratch (~/.agents/.cache/helpers/pty/). */
+export declare function getPtyDir(): string;
+/** Path to remote-resource auto-pull cache (~/.agents/.cache/.fetch/). */
+export declare function getFetchCacheDir(): string;
+/** Path to the CLI version cache file (~/.agents/.cache/.cli-version-cache.json). */
+export declare function getCliVersionCachePath(): string;
+/** Path to the models cache file (~/.agents/.cache/.models-cache.json). */
+export declare function getModelsCachePath(): string;
+/** Path to the daily update-check sentinel (~/.agents/.cache/.update-check). */
+export declare function getUpdateCheckPath(): string;
+/** Path to the migration sentinel (~/.agents/.cache/.migrated). */
+export declare function getMigratedSentinelPath(): string;
 /** Path to soft-deleted version dirs (~/.agents/trash/versions/). */
 export declare function getTrashVersionsDir(): string;
+/** Path to soft-deleted skills (~/.agents/trash/skills/). */
+export declare function getTrashSkillsDir(): string;
+/** Path to soft-deleted commands (~/.agents/trash/commands/). */
+export declare function getTrashCommandsDir(): string;
+/** Path to soft-deleted hooks (~/.agents/trash/hooks/). */
+export declare function getTrashHooksDir(): string;
+/** Path to soft-deleted plugins (~/.agents/trash/plugins/). */
+export declare function getTrashPluginsDir(): string;
+/** Path to soft-deleted subagents (~/.agents/trash/subagents/). */
+export declare function getTrashSubagentsDir(): string;
 /**
  * Path to a single user-level extra DotAgent repo clone (~/.agents-<alias>/).
  *

package/dist/lib/state.js

@@ -2,11 +2,18 @@
  * Filesystem layout and persistent state for agents-cli.
  *
  * Two roots:
- *  - ~/.agents-system/ — system repo (npm-shipped resources and canonical read-side defaults)
- *  - ~/.agents/        — user repo  (user-authored commands, skills, hooks, rules, mcp,
- *                                    permissions, subagents, profiles, secrets, agents.yaml,
- *                                    packages, routines, runs, versions, shims, backups, plugins,
- *                                    drive, trash)
+ *  - ~/.agents-system/ — system repo (npm-shipped resources, read-only defaults)
+ *  - ~/.agents/        — user repo (resources + agents.yaml + operational state)
+ *
+ * Inside ~/.agents/, top-level paths hold ONLY resources + agents.yaml.
+ * Operational state lives in two sibling buckets:
+ *
+ *  - ~/.agents/.history/ — durable runtime data (sessions, versions, runs,
+ *                          teams/agents, trash, backups). Backed up by
+ *                          `agents repo push`.
+ *  - ~/.agents/.cache/   — regenerable runtime data (shims, packages, helpers
+ *                          for daemon/pty, terminals, cloud, drive, browser
+ *                          chrome-data, logs, swarmify). Gitignored.
  *
  * Resolution precedence for resources: project > user > system.
  * Every module that needs a path or reads/writes agents.yaml goes through here.
@@ -37,16 +44,42 @@ const SYSTEM_SUBAGENTS_DIR = path.join(SYSTEM_AGENTS_DIR, 'subagents');
 const SYSTEM_PROMPTCUTS_FILE = path.join(SYSTEM_AGENTS_DIR, 'hooks', 'promptcuts.yaml');
 const SYSTEM_MCP_CONFIG_FILE = path.join(SYSTEM_AGENTS_DIR, 'mcp.json');
 const SYSTEM_INSTRUCTIONS_FILE = path.join(SYSTEM_AGENTS_DIR, 'instructions.md');
-// User-level operational state
-const PACKAGES_DIR = path.join(USER_AGENTS_DIR, 'packages');
+// ─── User repo operational buckets ────────────────────────────────────────────
+/** Durable runtime data (sessions, versions, runs, teams history, trash, backups). */
+const HISTORY_DIR = path.join(USER_AGENTS_DIR, '.history');
+/** Regenerable runtime data (shims, packages, helpers, terminals, cloud, drive, logs, browser). */
+const CACHE_DIR = path.join(USER_AGENTS_DIR, '.cache');
+// Top-level user dirs (config/definitions only — runtime moves into .history/.cache).
 const ROUTINES_DIR = path.join(USER_AGENTS_DIR, 'routines');
-const RUNS_DIR = path.join(ROUTINES_DIR, 'runs');
-const VERSIONS_DIR = path.join(USER_AGENTS_DIR, 'versions');
-const SHIMS_DIR = path.join(USER_AGENTS_DIR, 'shims');
-const BACKUPS_DIR = path.join(USER_AGENTS_DIR, '.backups');
-const PLUGINS_DIR = path.join(USER_AGENTS_DIR, 'plugins');
-const DRIVE_DIR = path.join(USER_AGENTS_DIR, 'drive');
-const TRASH_DIR = path.join(USER_AGENTS_DIR, '.trash');
+const TEAMS_DIR = path.join(USER_AGENTS_DIR, 'teams');
+// History bucket (durable).
+const SESSIONS_DIR = path.join(HISTORY_DIR, 'sessions');
+const SESSIONS_DB_PATH = path.join(SESSIONS_DIR, 'sessions.db');
+const VERSIONS_DIR = path.join(HISTORY_DIR, 'versions');
+const RUNS_DIR = path.join(HISTORY_DIR, 'runs');
+const TEAMS_AGENTS_DIR = path.join(HISTORY_DIR, 'teams', 'agents');
+const BACKUPS_DIR = path.join(HISTORY_DIR, 'backups');
+const TRASH_DIR = path.join(HISTORY_DIR, 'trash');
+// Cache bucket (regenerable).
+const SHIMS_DIR = path.join(CACHE_DIR, 'shims');
+const BIN_DIR = path.join(CACHE_DIR, 'bin');
+const PACKAGES_DIR = path.join(CACHE_DIR, 'packages');
+const PLUGINS_DIR = path.join(CACHE_DIR, 'plugins');
+const CLOUD_DIR = path.join(CACHE_DIR, 'cloud');
+const DRIVE_DIR = path.join(CACHE_DIR, 'drive');
+const TERMINALS_DIR = path.join(CACHE_DIR, 'terminals');
+const LOGS_DIR = path.join(CACHE_DIR, 'logs');
+const RUNTIME_STATE_DIR = path.join(CACHE_DIR, 'state');
+const SWARMIFY_DIR = path.join(CACHE_DIR, 'swarmify');
+const BROWSER_RUNTIME_DIR = path.join(CACHE_DIR, 'browser');
+const HELPERS_DIR = path.join(CACHE_DIR, 'helpers');
+const DAEMON_DIR = path.join(HELPERS_DIR, 'daemon');
+const PTY_DIR = path.join(HELPERS_DIR, 'pty');
+const FETCH_CACHE_DIR = path.join(CACHE_DIR, '.fetch');
+const CLI_VERSION_CACHE_FILE = path.join(CACHE_DIR, '.cli-version-cache.json');
+const MODELS_CACHE_FILE = path.join(CACHE_DIR, '.models-cache.json');
+const UPDATE_CHECK_FILE = path.join(CACHE_DIR, '.update-check');
+const MIGRATED_SENTINEL_FILE = path.join(CACHE_DIR, '.migrated');
 // ─── User resource dirs ───────────────────────────────────────────────────────
 const USER_COMMANDS_DIR = path.join(USER_AGENTS_DIR, 'commands');
 const USER_HOOKS_DIR = path.join(USER_AGENTS_DIR, 'hooks');
@@ -147,8 +180,43 @@ export function getMcpDir() { return SYSTEM_MCP_DIR; }
 export function getPermissionsDir() { return SYSTEM_PERMISSIONS_DIR; }
 /** Path to subagent definition directories — system repo. */
 export function getSubagentsDir() { return SYSTEM_SUBAGENTS_DIR; }
-/** Path to ~/.agents-system/promptcuts.yaml. */
+/** Path to ~/.agents-system/hooks/promptcuts.yaml (system defaults). */
 export function getPromptcutsPath() { return SYSTEM_PROMPTCUTS_FILE; }
+/**
+ * Resolve the effective promptcuts file: user file if it exists, otherwise
+ * the system file. Use this for callers that need a single path (doctor
+ * diff, displaying which file is in play). Callers that need the merged
+ * shortcut set should use readMergedPromptcuts() instead.
+ */
+export function getEffectivePromptcutsPath() {
+    if (fs.existsSync(USER_PROMPTCUTS_FILE))
+        return USER_PROMPTCUTS_FILE;
+    return SYSTEM_PROMPTCUTS_FILE;
+}
+/**
+ * Read promptcuts from system + user with user precedence. Returns the
+ * merged `shortcuts` map. Same layering model as parseHookManifest().
+ * Returns an empty object when neither file exists or both fail to parse.
+ */
+export function readMergedPromptcuts() {
+    const merged = {};
+    for (const filePath of [SYSTEM_PROMPTCUTS_FILE, USER_PROMPTCUTS_FILE]) {
+        if (!fs.existsSync(filePath))
+            continue;
+        try {
+            const parsed = yaml.parse(fs.readFileSync(filePath, 'utf-8'));
+            if (!parsed?.shortcuts)
+                continue;
+            for (const [key, value] of Object.entries(parsed.shortcuts)) {
+                merged[key] = value;
+            }
+        }
+        catch {
+            // Skip unreadable file, keep going
+        }
+    }
+    return merged;
+}
 /** Path to the legacy MCP config JSON. */
 export function getMcpConfigPath() { return SYSTEM_MCP_CONFIG_FILE; }
 /** Path to the global instructions file. */
@@ -173,26 +241,81 @@ export function getUserSubagentsDir() { return USER_SUBAGENTS_DIR; }
 export function getUserSecretsDir() { return USER_SECRETS_DIR; }
 export function getUserPromptcutsPath() { return USER_PROMPTCUTS_FILE; }
 // ─── User operational path getters ────────────────────────────────────────────
-/** Path to cloned packages (~/.agents/packages/). */
+//
+// Top-level dirs hold definitions/configs only; runtime data lives under
+// .history/ (durable) or .cache/ (regenerable). See file header.
+/** Bucket root for durable runtime data (~/.agents/.history/). */
+export function getHistoryDir() { return HISTORY_DIR; }
+/** Bucket root for regenerable runtime data (~/.agents/.cache/). */
+export function getCacheDir() { return CACHE_DIR; }
+/** Path to cloned packages (~/.agents/.cache/packages/). */
 export function getPackagesDir() { return PACKAGES_DIR; }
 /** Path to routine YAML definitions (~/.agents/routines/). */
 export function getRoutinesDir() { return ROUTINES_DIR; }
-/** Path to routine execution logs (~/.agents/runs/). */
+/** Path to routine execution logs (~/.agents/.history/runs/). */
 export function getRunsDir() { return RUNS_DIR; }
-/** Path to installed agent CLI binaries (~/.agents/versions/). */
+/** Path to installed agent CLI binaries (~/.agents/.history/versions/). */
 export function getVersionsDir() { return VERSIONS_DIR; }
-/** Path to version-switching shim scripts (~/.agents/shims/). */
+/** Path to version-switching shim scripts (~/.agents/.cache/shims/). */
 export function getShimsDir() { return SHIMS_DIR; }
-/** Path to config backups (~/.agents/backups/). */
+/** Path to per-agent installed CLI binaries (~/.agents/.cache/bin/). */
+export function getBinDir() { return BIN_DIR; }
+/** Path to config backups (~/.agents/.history/backups/). */
 export function getBackupsDir() { return BACKUPS_DIR; }
-/** Path to plugin bundles (~/.agents/plugins/). */
+/** Path to plugin bundles (~/.agents/.cache/plugins/). */
 export function getPluginsDir() { return PLUGINS_DIR; }
-/** Path to synced remote session data (~/.agents/drive/). */
+/** Path to synced remote session data (~/.agents/.cache/drive/). */
 export function getDriveDir() { return DRIVE_DIR; }
-/** Path to soft-deleted resources (~/.agents/trash/). */
+/** Path to soft-deleted resources (~/.agents/.history/trash/). */
 export function getTrashDir() { return TRASH_DIR; }
+/** Path to local session indexer storage (~/.agents/.history/sessions/). */
+export function getSessionsDir() { return SESSIONS_DIR; }
+/** Path to the session index database (~/.agents/.history/sessions.db). */
+export function getSessionsDbPath() { return SESSIONS_DB_PATH; }
+/** Path to teams config + registry (~/.agents/teams/). */
+export function getTeamsDir() { return TEAMS_DIR; }
+/** Path to teams execution history (~/.agents/.history/teams/agents/). */
+export function getTeamsAgentsDir() { return TEAMS_AGENTS_DIR; }
+/** Path to cloud dispatch cache (~/.agents/.cache/cloud/). */
+export function getCloudDir() { return CLOUD_DIR; }
+/** Path to terminal session metadata (~/.agents/.cache/terminals/). */
+export function getTerminalsDir() { return TERMINALS_DIR; }
+/** Path to runtime logs (~/.agents/.cache/logs/). */
+export function getLogsDir() { return LOGS_DIR; }
+/** Path to per-process runtime state (~/.agents/.cache/state/). */
+export function getRuntimeStateDir() { return RUNTIME_STATE_DIR; }
+/** Path to swarmify-extension scratch (~/.agents/.cache/swarmify/). */
+export function getSwarmifyDir() { return SWARMIFY_DIR; }
+/** Path to browser runtime data — chrome-data, pids (~/.agents/.cache/browser/). */
+export function getBrowserRuntimeDir() { return BROWSER_RUNTIME_DIR; }
+/** Path to helper subprocess scratch (~/.agents/.cache/helpers/). */
+export function getHelpersDir() { return HELPERS_DIR; }
+/** Path to scheduler daemon scratch (~/.agents/.cache/helpers/daemon/). */
+export function getDaemonDir() { return DAEMON_DIR; }
+/** Path to PTY server scratch (~/.agents/.cache/helpers/pty/). */
+export function getPtyDir() { return PTY_DIR; }
+/** Path to remote-resource auto-pull cache (~/.agents/.cache/.fetch/). */
+export function getFetchCacheDir() { return FETCH_CACHE_DIR; }
+/** Path to the CLI version cache file (~/.agents/.cache/.cli-version-cache.json). */
+export function getCliVersionCachePath() { return CLI_VERSION_CACHE_FILE; }
+/** Path to the models cache file (~/.agents/.cache/.models-cache.json). */
+export function getModelsCachePath() { return MODELS_CACHE_FILE; }
+/** Path to the daily update-check sentinel (~/.agents/.cache/.update-check). */
+export function getUpdateCheckPath() { return UPDATE_CHECK_FILE; }
+/** Path to the migration sentinel (~/.agents/.cache/.migrated). */
+export function getMigratedSentinelPath() { return MIGRATED_SENTINEL_FILE; }
 /** Path to soft-deleted version dirs (~/.agents/trash/versions/). */
 export function getTrashVersionsDir() { return path.join(TRASH_DIR, 'versions'); }
+/** Path to soft-deleted skills (~/.agents/trash/skills/). */
+export function getTrashSkillsDir() { return path.join(TRASH_DIR, 'skills'); }
+/** Path to soft-deleted commands (~/.agents/trash/commands/). */
+export function getTrashCommandsDir() { return path.join(TRASH_DIR, 'commands'); }
+/** Path to soft-deleted hooks (~/.agents/trash/hooks/). */
+export function getTrashHooksDir() { return path.join(TRASH_DIR, 'hooks'); }
+/** Path to soft-deleted plugins (~/.agents/trash/plugins/). */
+export function getTrashPluginsDir() { return path.join(TRASH_DIR, 'plugins'); }
+/** Path to soft-deleted subagents (~/.agents/trash/subagents/). */
+export function getTrashSubagentsDir() { return path.join(TRASH_DIR, 'subagents'); }
 /**
  * Path to a single user-level extra DotAgent repo clone (~/.agents-<alias>/).
  *
@@ -242,6 +365,10 @@ export function ensureAgentsDir() {
     if (!fs.existsSync(SYSTEM_AGENTS_DIR)) {
         fs.mkdirSync(SYSTEM_AGENTS_DIR, opts);
     }
+    if (!fs.existsSync(HISTORY_DIR))
+        fs.mkdirSync(HISTORY_DIR, opts);
+    if (!fs.existsSync(CACHE_DIR))
+        fs.mkdirSync(CACHE_DIR, opts);
     if (!fs.existsSync(PACKAGES_DIR))
         fs.mkdirSync(PACKAGES_DIR, opts);
     if (!fs.existsSync(ROUTINES_DIR))

package/dist/lib/subagents.d.ts

@@ -81,3 +81,31 @@ export declare const SUBAGENT_CAPABLE_AGENTS: AgentId[];
  * OpenClaw: scans ~/.openclaw/{name}/AGENTS.md
  */
 export declare function listSubagentsForAgent(agentId: AgentId, home: string): InstalledSubagent[];
+export interface VersionSubagentDiff {
+    agent: AgentId;
+    version: string;
+    orphans: string[];
+}
+/**
+ * Compare a version home's subagents against discovered subagents.
+ * Returns orphan subagent names.
+ */
+export declare function diffVersionSubagents(agent: AgentId, version: string): VersionSubagentDiff;
+/**
+ * Iterate all (agent, version) pairs that support subagents and are installed.
+ */
+export declare function iterSubagentsCapableVersions(filter?: {
+    agent?: AgentId;
+    version?: string;
+}): Array<{
+    agent: AgentId;
+    version: string;
+}>;
+/**
+ * Remove a single subagent from a specific version home.
+ * Soft-deletes to ~/.agents/.trash/subagents/.
+ */
+export declare function removeSubagentFromVersion(agent: AgentId, version: string, subagentName: string): {
+    success: boolean;
+    error?: string;
+};