@phnx-labs/agents-cli 1.15.0 → 1.17.0

package/dist/lib/shims.js

@@ -44,7 +44,7 @@ function shouldIgnore(name) {
  * Detect conflicting files between source and destination directories.
  * Returns list of filenames that exist in both locations (excluding symlinks in dest).
  */
-export function detectConflicts(src, dest, prefix = '') {
+function detectConflicts(src, dest, prefix = '') {
     const conflicts = [];
     if (!fs.existsSync(src) || !fs.existsSync(dest)) {
         return conflicts;
@@ -93,7 +93,7 @@ export function detectConflicts(src, dest, prefix = '') {
 /**
  * Prompt user for conflict resolution strategy.
  */
-export async function promptConflictStrategy(conflictInfos) {
+async function promptConflictStrategy(conflictInfos) {
     const totalConflicts = conflictInfos.reduce((sum, info) => sum + info.conflicts.length, 0);
     if (totalConflicts === 0) {
         return null; // No conflicts, no prompt needed
@@ -171,8 +171,10 @@ export async function promptConflictStrategy(conflictInfos) {
  *        and capability flag `memoryImports` → `rulesImports`.
  *   v8 — versions moved from ~/.agents-system/versions to ~/.agents/versions
  *        (two-repo split: system = shipped defaults, user = operational state).
+ *   v9 — claude shim exports CLAUDE_CODE_OAUTH_TOKEN from per-version
+ *        .oauth_token file on Linux (keychain-less sandbox fallback).
  */
-export const SHIM_SCHEMA_VERSION = 8;
+export const SHIM_SCHEMA_VERSION = 10;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
 /**
@@ -189,6 +191,12 @@ export function generateShimScript(agent) {
 # selected version's config directory so switching versions also switches the
 # live Claude account.
 export CLAUDE_CONFIG_DIR="$VERSION_DIR/home/${configDirName}"
+# On Linux sandboxes (no keychain), fall back to a per-version token file.
+# The env var always wins if already set; no-op on macOS.
+if [ "\$(uname -s)" = "Linux" ] && [ -z "\${CLAUDE_CODE_OAUTH_TOKEN:-}" ] && [ -f "\$CLAUDE_CONFIG_DIR/.oauth_token" ]; then
+  CLAUDE_CODE_OAUTH_TOKEN=\$(cat "\$CLAUDE_CONFIG_DIR/.oauth_token")
+  export CLAUDE_CODE_OAUTH_TOKEN
+fi
 `
         : agent === 'codex'
             ? `
@@ -287,7 +295,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 +388,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 +413,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 +429,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
@@ -543,7 +551,7 @@ function getVersionConfigPath(agent, version) {
  * Returns null if no migration is needed (already symlink or doesn't exist),
  * or ConflictInfo with the list of conflicting files.
  */
-export function detectMigrationConflicts(agent, version) {
+function detectMigrationConflicts(agent, version) {
     const configPath = getAgentConfigPath(agent);
     const versionConfigPath = getVersionConfigPath(agent, version);
     try {
@@ -837,7 +845,7 @@ export function ensureClaudeInsideSymlink(version) {
  * Apply `ensureClaudeInsideSymlink` to every installed Claude version.
  * Safe to call repeatedly; per-version calls are idempotent.
  */
-export function ensureAllClaudeInsideSymlinks() {
+function ensureAllClaudeInsideSymlinks() {
     const versionsDir = getVersionsDir();
     const claudeVersionsDir = path.join(versionsDir, 'claude');
     const migrated = [];
@@ -975,7 +983,7 @@ export function shimExists(agent) {
  * Read the schema version embedded in an existing on-disk shim. Returns
  * `null` if the shim doesn't exist or has no version marker (pre-v2 shim).
  */
-export function readShimSchemaVersion(agent) {
+function readShimSchemaVersion(agent) {
     if (!shimExists(agent))
         return null;
     try {
@@ -996,7 +1004,7 @@ export function readShimSchemaVersion(agent) {
  * False means either the shim is missing, is pre-v2 (no marker), or is an
  * older version that needs regeneration.
  */
-export function isShimCurrent(agent) {
+function isShimCurrent(agent) {
     const version = readShimSchemaVersion(agent);
     return version === SHIM_SCHEMA_VERSION;
 }
@@ -1309,7 +1317,7 @@ export function listAgentsWithInstalledVersions() {
 /**
  * Create shims for all installed agents.
  */
-export function ensureAllShims() {
+function ensureAllShims() {
     const versionsDir = getVersionsDir();
     if (!fs.existsSync(versionsDir)) {
         return;
@@ -1331,7 +1339,7 @@ export function ensureAllShims() {
  * Compare resources between two versions.
  * Returns resources that exist in currentVersion but not in targetVersion.
  */
-export function compareVersionResources(agent, currentVersion, targetVersion) {
+function compareVersionResources(agent, currentVersion, targetVersion) {
     const agentConfig = AGENTS[agent];
     const currentPath = getVersionConfigPath(agent, currentVersion);
     const targetPath = getVersionConfigPath(agent, targetVersion);
@@ -1420,7 +1428,7 @@ export function hasResourceDiff(diff) {
  * Copy resources from one version to another.
  * Only copies resources listed in the diff (i.e., ones missing in target).
  */
-export function copyResourcesToVersion(agent, fromVersion, toVersion, diff) {
+function copyResourcesToVersion(agent, fromVersion, toVersion, diff) {
     const agentConfig = AGENTS[agent];
     const fromPath = getVersionConfigPath(agent, fromVersion);
     const toPath = getVersionConfigPath(agent, toVersion);

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/sqlite.js

@@ -66,12 +66,18 @@ class Database {
     pragma(stmt) {
         this.inner.exec(`PRAGMA ${stmt}`);
     }
-    // Wrap fn in BEGIN/COMMIT, ROLLBACK on throw. Manual on both runtimes
-    // because node:sqlite has no `db.transaction(fn)` and the manual form is
-    // identical in shape to what better-sqlite3 / bun:sqlite produce.
+    // Wrap fn in BEGIN IMMEDIATE/COMMIT, ROLLBACK on throw. Manual on both
+    // runtimes because node:sqlite has no `db.transaction(fn)`.
+    //
+    // BEGIN IMMEDIATE (not BEGIN DEFERRED) is required for write transactions in
+    // WAL mode. BEGIN DEFERRED upgrades the lock lazily on the first write; if
+    // another writer already committed since the transaction started, SQLite
+    // returns SQLITE_BUSY_SNAPSHOT (a sub-code of SQLITE_BUSY that the busy
+    // handler does NOT retry). BEGIN IMMEDIATE claims the write lock upfront so
+    // the busy handler fires correctly and respects busy_timeout.
     transaction(fn) {
         return (...args) => {
-            this.inner.exec('BEGIN');
+            this.inner.exec('BEGIN IMMEDIATE');
             try {
                 const result = fn(...args);
                 this.inner.exec('COMMIT');

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. */
@@ -69,28 +89,83 @@ export declare function getUserRulesDir(): string;
 export declare function getUserMcpDir(): string;
 export declare function getUserPermissionsDir(): string;
 export declare function getUserSubagentsDir(): string;
+export declare function getSystemWorkflowsDir(): string;
+export declare function getUserWorkflowsDir(): 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;
+export declare function getTrashWorkflowsDir(): string;
 /**
  * Path to a single user-level extra DotAgent repo clone (~/.agents-<alias>/).
  *
@@ -122,8 +197,18 @@ export declare function writeMeta(meta: Meta): void;
 export declare function updateMeta(updates: Partial<Meta>): Meta;
 /** Derive a filesystem-safe local clone path for a package source URL. */
 export declare function getPackageLocalPath(source: string): string;
-import type { AgentId, ResourceType, VersionResources } from './types.js';
-export declare function recordVersionResources(agent: AgentId, version: string, resourceType: ResourceType, resources: string[]): void;
+import type { AgentId, ResourceType, VersionResources, ResourcePattern } from './types.js';
+/**
+ * @deprecated No-op. Use ensureVersionResourcePatterns instead.
+ * Kept for backward compat with command files that still call it.
+ */
+export declare function recordVersionResources(_agent: AgentId, _version: string, _resourceType: ResourceType, _resources: string[]): void;
+/**
+ * Write default resource selection patterns for an agent@version.
+ * Only writes each field when it is not already set, preserving user customization.
+ * Pass all resource types you want to initialize in one call to batch the write.
+ */
+export declare function ensureVersionResourcePatterns(agent: AgentId, version: string, updates: Partial<Record<Exclude<keyof VersionResources, 'rulesPreset'>, ResourcePattern[]>>): void;
 export declare function getVersionResources(agent: AgentId, version: string): VersionResources | null;
 export declare function clearVersionResources(agent: AgentId, version: string): void;
 /** Active rules preset for an agent@version. Defaults to "default" when unset. */

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.
@@ -16,7 +23,7 @@ import * as path from 'path';
 import * as os from 'os';
 import * as yaml from 'yaml';
 import { SEEDED_REGISTRIES } from './types.js';
-const HOME = os.homedir();
+const HOME = process.env.HOME ?? os.homedir();
 // ─── Root directories ─────────────────────────────────────────────────────────
 /** System repo — npm-shipped, read-only from user commands. */
 const SYSTEM_AGENTS_DIR = path.join(HOME, '.agents-system');
@@ -34,19 +41,46 @@ const SYSTEM_RULES_DIR = path.join(SYSTEM_AGENTS_DIR, 'rules');
 const SYSTEM_MCP_DIR = path.join(SYSTEM_AGENTS_DIR, 'mcp');
 const SYSTEM_PERMISSIONS_DIR = path.join(SYSTEM_AGENTS_DIR, 'permissions');
 const SYSTEM_SUBAGENTS_DIR = path.join(SYSTEM_AGENTS_DIR, 'subagents');
+const SYSTEM_WORKFLOWS_DIR = path.join(SYSTEM_AGENTS_DIR, 'workflows');
 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');
@@ -55,6 +89,7 @@ const USER_RULES_DIR = path.join(USER_AGENTS_DIR, 'rules');
 const USER_MCP_DIR = path.join(USER_AGENTS_DIR, 'mcp');
 const USER_PERMISSIONS_DIR = path.join(USER_AGENTS_DIR, 'permissions');
 const USER_SUBAGENTS_DIR = path.join(USER_AGENTS_DIR, 'subagents');
+const USER_WORKFLOWS_DIR = path.join(USER_AGENTS_DIR, 'workflows');
 const USER_SECRETS_DIR = path.join(USER_AGENTS_DIR, 'secrets');
 const USER_PROMPTCUTS_FILE = path.join(USER_AGENTS_DIR, 'hooks', 'promptcuts.yaml');
 const META_HEADER = `# agents-cli metadata
@@ -147,8 +182,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. */
@@ -170,29 +240,87 @@ export function getUserRulesDir() { return USER_RULES_DIR; }
 export function getUserMcpDir() { return USER_MCP_DIR; }
 export function getUserPermissionsDir() { return USER_PERMISSIONS_DIR; }
 export function getUserSubagentsDir() { return USER_SUBAGENTS_DIR; }
+export function getSystemWorkflowsDir() { return SYSTEM_WORKFLOWS_DIR; }
+export function getUserWorkflowsDir() { return USER_WORKFLOWS_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'); }
+export function getTrashWorkflowsDir() { return path.join(TRASH_DIR, 'workflows'); }
 /**
  * Path to a single user-level extra DotAgent repo clone (~/.agents-<alias>/).
  *
@@ -242,6 +370,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))
@@ -425,9 +557,19 @@ export function getPackageLocalPath(source) {
         .replace(/\//g, '-');
     return path.join(PACKAGES_DIR, sanitized);
 }
-export function recordVersionResources(agent, version, resourceType, resources) {
-    if (resources.length === 0)
-        return;
+/**
+ * @deprecated No-op. Use ensureVersionResourcePatterns instead.
+ * Kept for backward compat with command files that still call it.
+ */
+export function recordVersionResources(_agent, _version, _resourceType, _resources) {
+    // intentional no-op — tracking moved to pattern-based ensureVersionResourcePatterns
+}
+/**
+ * Write default resource selection patterns for an agent@version.
+ * Only writes each field when it is not already set, preserving user customization.
+ * Pass all resource types you want to initialize in one call to batch the write.
+ */
+export function ensureVersionResourcePatterns(agent, version, updates) {
     const meta = readMeta();
     if (!meta.versions)
         meta.versions = {};
@@ -435,10 +577,16 @@ export function recordVersionResources(agent, version, resourceType, resources)
         meta.versions[agent] = {};
     if (!meta.versions[agent][version])
         meta.versions[agent][version] = {};
-    const existing = meta.versions[agent][version][resourceType] || [];
-    const merged = [...new Set([...existing, ...resources])];
-    meta.versions[agent][version][resourceType] = merged;
-    writeMeta(meta);
+    const vr = meta.versions[agent][version];
+    let changed = false;
+    for (const [type, patterns] of Object.entries(updates)) {
+        if (!vr[type] || vr[type].length === 0) {
+            vr[type] = patterns;
+            changed = true;
+        }
+    }
+    if (changed)
+        writeMeta(meta);
 }
 export function getVersionResources(agent, version) {
     const meta = readMeta();