@phnx-labs/agents-cli 1.14.2 → 1.14.4

package/dist/lib/state.d.ts

@@ -2,15 +2,17 @@
  * Filesystem layout and persistent state for agents-cli.
  *
  * Two roots:
- *  - ~/.agents-system/ — system repo (npm-shipped resources, versions, shims, backups, runs)
+ *  - ~/.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)
+ *                                    permissions, subagents, profiles, secrets, agents.yaml,
+ *                                    packages, routines, runs, versions, shims, backups, plugins,
+ *                                    drive, trash)
  *
  * Resolution precedence for resources: project > user > system.
  * Every module that needs a path or reads/writes agents.yaml goes through here.
  */
 import type { Meta } from './types.js';
-/** Root of the system data directory (~/.agents-system/). Legacy alias — prefer getSystemAgentsDir(). */
+/** Root of the system data directory (~/.agents-system/). */
 export declare function getAgentsDir(): string;
 /** Root of the system data directory (~/.agents-system/). */
 export declare function getSystemAgentsDir(): string;
@@ -38,20 +40,7 @@ export declare function getHooksDir(): string;
 export declare function getSkillsDir(): string;
 /** Path to the canonical rules directory — system repo. */
 export declare function getRulesDir(): string;
-/** Back-compat export; resolves to system rules dir. */
-export declare function getMemoryDir(): string;
-/**
- * Read-side resolution for the canonical rules dir.
- *
- * Returns SYSTEM_RULES_DIR normally. Falls back to the legacy
- * SYSTEM_LEGACY_MEMORY_DIR (~/.agents-system/memory/) only when the upstream
- * still uses the old layout and the user hasn't pulled the rename yet —
- * detected by absence of rules/AGENTS.md and presence of memory/AGENTS.md.
- *
- * Prints a single warning per process the first time the fallback fires.
- * Per the read-only system-repo invariant, this never moves files; the rename
- * is applied when the user pulls upstream.
- */
+/** Read-side resolution for the canonical rules dir — system repo. */
 export declare function getResolvedRulesDir(): string;
 /** Path to MCP server YAML configs — system repo. */
 export declare function getMcpDir(): string;
@@ -59,8 +48,6 @@ export declare function getMcpDir(): string;
 export declare function getPermissionsDir(): string;
 /** Path to subagent definition directories — system repo. */
 export declare function getSubagentsDir(): string;
-/** Path to encrypted secret bundles — system repo. */
-export declare function getSecretsDir(): string;
 /** Path to ~/.agents-system/promptcuts.yaml. */
 export declare function getPromptcutsPath(): string;
 /** Path to the legacy MCP config JSON. */
@@ -74,7 +61,6 @@ export declare function getSystemRulesDir(): string;
 export declare function getSystemMcpDir(): string;
 export declare function getSystemPermissionsDir(): string;
 export declare function getSystemSubagentsDir(): string;
-export declare function getSystemSecretsDir(): string;
 export declare function getSystemPromptcutsPath(): string;
 export declare function getUserCommandsDir(): string;
 export declare function getUserHooksDir(): string;
@@ -85,22 +71,26 @@ 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-system/packages/). */
+/** Path to cloned packages (~/.agents/packages/). */
 export declare function getPackagesDir(): string;
-/** Path to routine YAML definitions (~/.agents-system/routines/). */
+/** Path to routine YAML definitions (~/.agents/routines/). */
 export declare function getRoutinesDir(): string;
-/** Path to routine execution logs (~/.agents-system/runs/). */
+/** Path to routine execution logs (~/.agents/runs/). */
 export declare function getRunsDir(): string;
-/** Path to installed agent CLI binaries (~/.agents-system/versions/). */
+/** Path to installed agent CLI binaries (~/.agents/versions/). */
 export declare function getVersionsDir(): string;
-/** Path to version-switching shim scripts (~/.agents-system/shims/). */
+/** Path to version-switching shim scripts (~/.agents/shims/). */
 export declare function getShimsDir(): string;
-/** Path to config backups (~/.agents-system/backups/). */
+/** Path to config backups (~/.agents/backups/). */
 export declare function getBackupsDir(): string;
-/** Path to plugin bundles (~/.agents-system/plugins/). */
+/** Path to plugin bundles (~/.agents/plugins/). */
 export declare function getPluginsDir(): string;
-/** Path to synced remote session data (~/.agents-system/drive/). */
+/** Path to synced remote session data (~/.agents/drive/). */
 export declare function getDriveDir(): string;
+/** Path to soft-deleted resources (~/.agents/trash/). */
+export declare function getTrashDir(): string;
+/** Path to soft-deleted version dirs (~/.agents/trash/versions/). */
+export declare function getTrashVersionsDir(): string;
 /**
  * Path to a single user-level extra DotAgent repo clone (~/.agents-<alias>/).
  *
@@ -136,3 +126,7 @@ import type { AgentId, ResourceType, VersionResources } from './types.js';
 export declare function recordVersionResources(agent: AgentId, version: string, resourceType: ResourceType, resources: string[]): 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. */
+export declare function getActiveRulesPreset(agent: AgentId, version: string): string;
+/** Persist the active rules preset for an agent@version. */
+export declare function setActiveRulesPreset(agent: AgentId, version: string, preset: string): void;

package/dist/lib/state.js

@@ -2,9 +2,11 @@
  * Filesystem layout and persistent state for agents-cli.
  *
  * Two roots:
- *  - ~/.agents-system/ — system repo (npm-shipped resources, versions, shims, backups, runs)
+ *  - ~/.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)
+ *                                    permissions, subagents, profiles, secrets, agents.yaml,
+ *                                    packages, routines, runs, versions, shims, backups, plugins,
+ *                                    drive, trash)
  *
  * Resolution precedence for resources: project > user > system.
  * Every module that needs a path or reads/writes agents.yaml goes through here.
@@ -29,23 +31,22 @@ const SYSTEM_COMMANDS_DIR = path.join(SYSTEM_AGENTS_DIR, 'commands');
 const SYSTEM_HOOKS_DIR = path.join(SYSTEM_AGENTS_DIR, 'hooks');
 const SYSTEM_SKILLS_DIR = path.join(SYSTEM_AGENTS_DIR, 'skills');
 const SYSTEM_RULES_DIR = path.join(SYSTEM_AGENTS_DIR, 'rules');
-const SYSTEM_LEGACY_MEMORY_DIR = path.join(SYSTEM_AGENTS_DIR, 'memory');
 const SYSTEM_MCP_DIR = path.join(SYSTEM_AGENTS_DIR, 'mcp');
 const SYSTEM_PERMISSIONS_DIR = path.join(SYSTEM_AGENTS_DIR, 'permissions');
 const SYSTEM_SUBAGENTS_DIR = path.join(SYSTEM_AGENTS_DIR, 'subagents');
-const SYSTEM_SECRETS_DIR = path.join(SYSTEM_AGENTS_DIR, 'secrets');
 const SYSTEM_PROMPTCUTS_FILE = path.join(SYSTEM_AGENTS_DIR, 'hooks', 'promptcuts.yaml');
 const SYSTEM_MCP_CONFIG_FILE = path.join(SYSTEM_AGENTS_DIR, 'mcp.json');
 const SYSTEM_INSTRUCTIONS_FILE = path.join(SYSTEM_AGENTS_DIR, 'instructions.md');
-// System-only paths (never duplicated in user repo)
-const PACKAGES_DIR = path.join(SYSTEM_AGENTS_DIR, 'packages');
-const ROUTINES_DIR = path.join(SYSTEM_AGENTS_DIR, 'routines');
-const RUNS_DIR = path.join(SYSTEM_AGENTS_DIR, 'runs');
-const VERSIONS_DIR = path.join(SYSTEM_AGENTS_DIR, 'versions');
-const SHIMS_DIR = path.join(SYSTEM_AGENTS_DIR, 'shims');
-const BACKUPS_DIR = path.join(SYSTEM_AGENTS_DIR, 'backups');
-const PLUGINS_DIR = path.join(SYSTEM_AGENTS_DIR, 'plugins');
-const DRIVE_DIR = path.join(SYSTEM_AGENTS_DIR, 'drive');
+// User-level operational state
+const PACKAGES_DIR = path.join(USER_AGENTS_DIR, 'packages');
+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');
 // ─── User resource dirs ───────────────────────────────────────────────────────
 const USER_COMMANDS_DIR = path.join(USER_AGENTS_DIR, 'commands');
 const USER_HOOKS_DIR = path.join(USER_AGENTS_DIR, 'hooks');
@@ -62,7 +63,7 @@ const META_HEADER = `# agents-cli metadata
 
 `;
 // ─── Root getters ─────────────────────────────────────────────────────────────
-/** Root of the system data directory (~/.agents-system/). Legacy alias — prefer getSystemAgentsDir(). */
+/** Root of the system data directory (~/.agents-system/). */
 export function getAgentsDir() {
     return SYSTEM_AGENTS_DIR;
 }
@@ -138,44 +139,14 @@ export function getHooksDir() { return SYSTEM_HOOKS_DIR; }
 export function getSkillsDir() { return SYSTEM_SKILLS_DIR; }
 /** Path to the canonical rules directory — system repo. */
 export function getRulesDir() { return SYSTEM_RULES_DIR; }
-/** Back-compat export; resolves to system rules dir. */
-export function getMemoryDir() { return SYSTEM_RULES_DIR; }
-let legacyMemoryWarned = false;
-/**
- * Read-side resolution for the canonical rules dir.
- *
- * Returns SYSTEM_RULES_DIR normally. Falls back to the legacy
- * SYSTEM_LEGACY_MEMORY_DIR (~/.agents-system/memory/) only when the upstream
- * still uses the old layout and the user hasn't pulled the rename yet —
- * detected by absence of rules/AGENTS.md and presence of memory/AGENTS.md.
- *
- * Prints a single warning per process the first time the fallback fires.
- * Per the read-only system-repo invariant, this never moves files; the rename
- * is applied when the user pulls upstream.
- */
-export function getResolvedRulesDir() {
-    const rulesAgents = path.join(SYSTEM_RULES_DIR, 'AGENTS.md');
-    const legacyAgents = path.join(SYSTEM_LEGACY_MEMORY_DIR, 'AGENTS.md');
-    if (fs.existsSync(rulesAgents))
-        return SYSTEM_RULES_DIR;
-    if (fs.existsSync(legacyAgents)) {
-        if (!legacyMemoryWarned) {
-            legacyMemoryWarned = true;
-            process.stderr.write('agents-cli: Legacy memory/ directory detected — agents-cli still works, ' +
-                "but run 'agents repo pull system' to migrate to rules/.\n");
-        }
-        return SYSTEM_LEGACY_MEMORY_DIR;
-    }
-    return SYSTEM_RULES_DIR;
-}
+/** Read-side resolution for the canonical rules dir — system repo. */
+export function getResolvedRulesDir() { return SYSTEM_RULES_DIR; }
 /** Path to MCP server YAML configs — system repo. */
 export function getMcpDir() { return SYSTEM_MCP_DIR; }
 /** Path to permission group YAML files — system repo. */
 export function getPermissionsDir() { return SYSTEM_PERMISSIONS_DIR; }
 /** Path to subagent definition directories — system repo. */
 export function getSubagentsDir() { return SYSTEM_SUBAGENTS_DIR; }
-/** Path to encrypted secret bundles — system repo. */
-export function getSecretsDir() { return SYSTEM_SECRETS_DIR; }
 /** Path to ~/.agents-system/promptcuts.yaml. */
 export function getPromptcutsPath() { return SYSTEM_PROMPTCUTS_FILE; }
 /** Path to the legacy MCP config JSON. */
@@ -190,7 +161,6 @@ export function getSystemRulesDir() { return SYSTEM_RULES_DIR; }
 export function getSystemMcpDir() { return SYSTEM_MCP_DIR; }
 export function getSystemPermissionsDir() { return SYSTEM_PERMISSIONS_DIR; }
 export function getSystemSubagentsDir() { return SYSTEM_SUBAGENTS_DIR; }
-export function getSystemSecretsDir() { return SYSTEM_SECRETS_DIR; }
 export function getSystemPromptcutsPath() { return SYSTEM_PROMPTCUTS_FILE; }
 // ─── User resource getters ────────────────────────────────────────────────────
 export function getUserCommandsDir() { return USER_COMMANDS_DIR; }
@@ -202,23 +172,27 @@ export function getUserPermissionsDir() { return USER_PERMISSIONS_DIR; }
 export function getUserSubagentsDir() { return USER_SUBAGENTS_DIR; }
 export function getUserSecretsDir() { return USER_SECRETS_DIR; }
 export function getUserPromptcutsPath() { return USER_PROMPTCUTS_FILE; }
-// ─── System-only path getters ─────────────────────────────────────────────────
-/** Path to cloned packages (~/.agents-system/packages/). */
+// ─── User operational path getters ────────────────────────────────────────────
+/** Path to cloned packages (~/.agents/packages/). */
 export function getPackagesDir() { return PACKAGES_DIR; }
-/** Path to routine YAML definitions (~/.agents-system/routines/). */
+/** Path to routine YAML definitions (~/.agents/routines/). */
 export function getRoutinesDir() { return ROUTINES_DIR; }
-/** Path to routine execution logs (~/.agents-system/runs/). */
+/** Path to routine execution logs (~/.agents/runs/). */
 export function getRunsDir() { return RUNS_DIR; }
-/** Path to installed agent CLI binaries (~/.agents-system/versions/). */
+/** Path to installed agent CLI binaries (~/.agents/versions/). */
 export function getVersionsDir() { return VERSIONS_DIR; }
-/** Path to version-switching shim scripts (~/.agents-system/shims/). */
+/** Path to version-switching shim scripts (~/.agents/shims/). */
 export function getShimsDir() { return SHIMS_DIR; }
-/** Path to config backups (~/.agents-system/backups/). */
+/** Path to config backups (~/.agents/backups/). */
 export function getBackupsDir() { return BACKUPS_DIR; }
-/** Path to plugin bundles (~/.agents-system/plugins/). */
+/** Path to plugin bundles (~/.agents/plugins/). */
 export function getPluginsDir() { return PLUGINS_DIR; }
-/** Path to synced remote session data (~/.agents-system/drive/). */
+/** Path to synced remote session data (~/.agents/drive/). */
 export function getDriveDir() { return DRIVE_DIR; }
+/** Path to soft-deleted resources (~/.agents/trash/). */
+export function getTrashDir() { return TRASH_DIR; }
+/** Path to soft-deleted version dirs (~/.agents/trash/versions/). */
+export function getTrashVersionsDir() { return path.join(TRASH_DIR, 'versions'); }
 /**
  * Path to a single user-level extra DotAgent repo clone (~/.agents-<alias>/).
  *
@@ -264,7 +238,7 @@ export function ensureAgentsDir() {
         fs.chmodSync(USER_AGENTS_DIR, 0o700);
     }
     catch { }
-    // System repo
+    // System repo plus user-level operational state
     if (!fs.existsSync(SYSTEM_AGENTS_DIR)) {
         fs.mkdirSync(SYSTEM_AGENTS_DIR, opts);
     }
@@ -290,8 +264,6 @@ export function ensureAgentsDir() {
         fs.mkdirSync(SYSTEM_PERMISSIONS_DIR, opts);
     if (!fs.existsSync(SYSTEM_SUBAGENTS_DIR))
         fs.mkdirSync(SYSTEM_SUBAGENTS_DIR, opts);
-    if (!fs.existsSync(DRIVE_DIR))
-        fs.mkdirSync(DRIVE_DIR, opts);
     try {
         fs.chmodSync(SYSTEM_AGENTS_DIR, 0o700);
     }
@@ -351,8 +323,8 @@ export function readMeta() {
     ensureAgentsDir();
     // NOTE: agents.yaml migration from ~/.agents-system/ to ~/.agents/ is handled
     // exclusively by runMigration() in migrate.ts, called from postinstall and
-    // explicit command-time fallbacks (agents view/use/pull). Calling it here
-    // would mutate real-user filesystem state during test runs that import this
+    // from a one-shot bootstrap step in src/index.ts. Calling it here would
+    // mutate real-user filesystem state during test runs that import this
     // module, causing cross-test pollution.
     // Legacy migration: check for old meta.yaml in system dir
     const oldMetaFile = path.join(SYSTEM_AGENTS_DIR, 'meta.yaml');
@@ -384,29 +356,45 @@ export function readMeta() {
             /* meta.yaml migration failed */
         }
     }
-    if (fs.existsSync(META_FILE)) {
-        let mtime = 0;
+    // Merge agents.yaml from both system and user repos. User repo wins on conflicts.
+    let systemMeta = null;
+    let userMeta = null;
+    if (fs.existsSync(SYSTEM_META_FILE)) {
         try {
-            mtime = fs.statSync(META_FILE).mtimeMs;
-        }
-        catch { /* file vanished */ }
-        if (metaCache && metaCache.mtime === mtime) {
-            return metaCache.meta;
+            const content = fs.readFileSync(SYSTEM_META_FILE, 'utf-8');
+            systemMeta = yaml.parse(content);
         }
+        catch { /* ignore */ }
+    }
+    if (fs.existsSync(META_FILE)) {
         try {
             const content = fs.readFileSync(META_FILE, 'utf-8');
-            const parsed = yaml.parse(content);
-            const meta = parsed || createDefaultMeta();
-            if (applyRegistrySeeds(meta)) {
-                writeMeta(meta);
-                return meta;
-            }
-            metaCache = { mtime, meta };
-            return meta;
+            userMeta = yaml.parse(content);
         }
-        catch {
-            return createDefaultMeta();
+        catch { /* ignore */ }
+    }
+    if (systemMeta || userMeta) {
+        // Merge: system as base, user overwrites
+        const base = createDefaultMeta();
+        const meta = {
+            ...base,
+            ...systemMeta,
+            ...userMeta,
+            agents: { ...systemMeta?.agents, ...userMeta?.agents },
+        };
+        // Merge registries carefully to preserve type
+        if (systemMeta?.registries || userMeta?.registries) {
+            meta.registries = {
+                ...base.registries,
+                ...systemMeta?.registries,
+                ...userMeta?.registries,
+            };
+        }
+        if (applyRegistrySeeds(meta)) {
+            writeMeta(meta);
+            return meta;
         }
+        return meta;
     }
     const meta = createDefaultMeta();
     if (applyRegistrySeeds(meta)) {
@@ -469,3 +457,20 @@ export function clearVersionResources(agent, version) {
         writeMeta(meta);
     }
 }
+/** Active rules preset for an agent@version. Defaults to "default" when unset. */
+export function getActiveRulesPreset(agent, version) {
+    const meta = readMeta();
+    return meta.versions?.[agent]?.[version]?.rulesPreset || 'default';
+}
+/** Persist the active rules preset for an agent@version. */
+export function setActiveRulesPreset(agent, version, preset) {
+    const meta = readMeta();
+    if (!meta.versions)
+        meta.versions = {};
+    if (!meta.versions[agent])
+        meta.versions[agent] = {};
+    if (!meta.versions[agent][version])
+        meta.versions[agent][version] = {};
+    meta.versions[agent][version].rulesPreset = preset;
+    writeMeta(meta);
+}

package/dist/lib/sync-manifest.d.ts

@@ -74,8 +74,8 @@ export declare function buildManifest(agent: AgentId, version: string, available
  * Returns true (stale) at the first detected mismatch — no need to scan everything.
  * Returns false (clean) only after all checks pass.
  *
- * For rules, also delegates to isMemoryStale() to catch @-import changes
- * for agents that pre-compile their memory file.
+ * For rules, also delegates to isRulesStale() to catch @-import changes
+ * for agents that pre-compile their rules file.
  */
 export declare function isSyncStale(manifest: SyncManifest, available: AvailableResources, agent: AgentId, version: string, cwd: string): boolean;
 export {};

package/dist/lib/sync-manifest.js

@@ -27,7 +27,7 @@ import * as crypto from 'crypto';
 import { getVersionsDir, getProjectAgentsDir, getUserAgentsDir, getSkillsDir, getUserHooksDir, getHooksDir, getUserRulesDir, getResolvedRulesDir, getUserPermissionsDir, getPermissionsDir, getEnabledExtraRepos, } from './state.js';
 import { resolveResource } from './resources.js';
 import { listMcpServerConfigs } from './mcp.js';
-import { isMemoryStale } from './memory-compile.js';
+import { isRulesStale } from './rules/compile.js';
 import { getActivePermissionSetName } from './permissions.js';
 import { listInstalledSubagents } from './subagents.js';
 import { safeJoin } from './paths.js';
@@ -351,8 +351,8 @@ export function buildManifest(agent, version, available, cwd) {
  * Returns true (stale) at the first detected mismatch — no need to scan everything.
  * Returns false (clean) only after all checks pass.
  *
- * For rules, also delegates to isMemoryStale() to catch @-import changes
- * for agents that pre-compile their memory file.
+ * For rules, also delegates to isRulesStale() to catch @-import changes
+ * for agents that pre-compile their rules file.
  */
 export function isSyncStale(manifest, available, agent, version, cwd) {
     // ── Commands ──────────────────────────────────────────────────────────────
@@ -395,7 +395,7 @@ export function isSyncStale(manifest, available, agent, version, cwd) {
         if (!entry || isFileStale(entry.source, hookPath))
             return true;
     }
-    // ── Rules/memory ──────────────────────────────────────────────────────────
+    // ── Rules ─────────────────────────────────────────────────────────────────
     if (nameSetDiffers(Object.keys(manifest.rules.files), available.memory))
         return true;
     for (const name of available.memory) {
@@ -407,7 +407,7 @@ export function isSyncStale(manifest, available, agent, version, cwd) {
             return true;
     }
     // Also catch @-import changes for non-native-import agents
-    if (isMemoryStale(agent, version))
+    if (isRulesStale(agent, version))
         return true;
     // ── MCP ───────────────────────────────────────────────────────────────────
     const mcpServers = listMcpServerConfigs(cwd);

package/dist/lib/teams/agents.d.ts

@@ -97,10 +97,12 @@ export declare class AgentProcess {
     taskType: TaskType | null;
     cloudRepo: string | null;
     cloudBranch: string | null;
+    worktreeName: string | null;
+    worktreePath: string | null;
     private eventsCache;
     private lastReadPos;
     private baseDir;
-    constructor(agentId: string, taskName: string, agentType: AgentType, prompt: string, cwd?: string | null, mode?: Mode, pid?: number | null, status?: AgentStatus, startedAt?: Date, completedAt?: Date | null, baseDir?: string | null, parentSessionId?: string | null, workspaceDir?: string | null, cloudSessionId?: string | null, cloudProvider?: string | null, prUrl?: string | null, version?: string | null, remoteSessionId?: string | null, name?: string | null, after?: string[], effort?: EffortLevel | null, model?: string | null, envOverrides?: Record<string, string> | null, taskType?: TaskType | null, cloudRepo?: string | null, cloudBranch?: string | null);
+    constructor(agentId: string, taskName: string, agentType: AgentType, prompt: string, cwd?: string | null, mode?: Mode, pid?: number | null, status?: AgentStatus, startedAt?: Date, completedAt?: Date | null, baseDir?: string | null, parentSessionId?: string | null, workspaceDir?: string | null, cloudSessionId?: string | null, cloudProvider?: string | null, prUrl?: string | null, version?: string | null, remoteSessionId?: string | null, name?: string | null, after?: string[], effort?: EffortLevel | null, model?: string | null, envOverrides?: Record<string, string> | null, taskType?: TaskType | null, cloudRepo?: string | null, cloudBranch?: string | null, worktreeName?: string | null, worktreePath?: string | null);
     get isEditMode(): boolean;
     getAgentDir(): Promise<string>;
     /**
@@ -191,7 +193,7 @@ export declare class AgentManager {
      */
     rescanFromDisk(): Promise<number>;
     private loadExistingAgents;
-    spawn(taskName: string, agentType: AgentType, prompt: string, cwd?: string | null, mode?: Mode | null, effort?: EffortLevel, parentSessionId?: string | null, workspaceDir?: string | null, version?: string | null, name?: string | null, after?: string[], model?: string | null, envOverrides?: Record<string, string> | null, taskType?: TaskType | null, cloudProvider?: string | null, cloudSessionId?: string | null, cloudRepo?: string | null, cloudBranch?: string | null): Promise<AgentProcess>;
+    spawn(taskName: string, agentType: AgentType, prompt: string, cwd?: string | null, mode?: Mode | null, effort?: EffortLevel, parentSessionId?: string | null, workspaceDir?: string | null, version?: string | null, name?: string | null, after?: string[], model?: string | null, envOverrides?: Record<string, string> | null, taskType?: TaskType | null, cloudProvider?: string | null, cloudSessionId?: string | null, cloudRepo?: string | null, cloudBranch?: string | null, worktreeName?: string | null, worktreePath?: string | null): Promise<AgentProcess>;
     /**
      * Actually spawn the OS process for a teammate. Extracted from spawn() so
      * staged teammates can be launched later by startReady().

package/dist/lib/teams/agents.js

@@ -468,10 +468,13 @@ export class AgentProcess {
     // options the user originally supplied.
     cloudRepo = null;
     cloudBranch = null;
+    // Worktree isolation: when non-null, this teammate runs in its own git worktree.
+    worktreeName = null;
+    worktreePath = null;
     eventsCache = [];
     lastReadPos = 0;
     baseDir = null;
-    constructor(agentId, taskName, agentType, prompt, cwd = null, mode = 'plan', pid = null, status = AgentStatus.RUNNING, startedAt = new Date(), completedAt = null, baseDir = null, parentSessionId = null, workspaceDir = null, cloudSessionId = null, cloudProvider = null, prUrl = null, version = null, remoteSessionId = null, name = null, after = [], effort = null, model = null, envOverrides = null, taskType = null, cloudRepo = null, cloudBranch = null) {
+    constructor(agentId, taskName, agentType, prompt, cwd = null, mode = 'plan', pid = null, status = AgentStatus.RUNNING, startedAt = new Date(), completedAt = null, baseDir = null, parentSessionId = null, workspaceDir = null, cloudSessionId = null, cloudProvider = null, prUrl = null, version = null, remoteSessionId = null, name = null, after = [], effort = null, model = null, envOverrides = null, taskType = null, cloudRepo = null, cloudBranch = null, worktreeName = null, worktreePath = null) {
         this.agentId = agentId;
         this.remoteSessionId = remoteSessionId;
         this.name = name;
@@ -482,6 +485,8 @@ export class AgentProcess {
         this.taskType = taskType;
         this.cloudRepo = cloudRepo;
         this.cloudBranch = cloudBranch;
+        this.worktreeName = worktreeName;
+        this.worktreePath = worktreePath;
         this.taskName = taskName;
         this.agentType = agentType;
         this.prompt = prompt;
@@ -691,6 +696,8 @@ export class AgentProcess {
             task_type: this.taskType,
             cloud_repo: this.cloudRepo,
             cloud_branch: this.cloudBranch,
+            worktree_name: this.worktreeName,
+            worktree_path: this.worktreePath,
         };
         const metaPath = await this.getMetaPath();
         await fs.writeFile(metaPath, JSON.stringify(meta, null, 2));
@@ -726,7 +733,7 @@ export class AgentProcess {
                 : AgentStatus.RUNNING;
             const agent = new AgentProcess(meta.agent_id, meta.task_name || 'default', meta.agent_type, meta.prompt, meta.cwd || null, resolvedMode, meta.pid || null, resolvedStatus, new Date(meta.started_at), meta.completed_at ? new Date(meta.completed_at) : null, baseDir, meta.parent_session_id || null, meta.workspace_dir || null, meta.cloud_session_id || null, meta.cloud_provider || null, meta.pr_url || null, meta.version || null, meta.remote_session_id || null, meta.name || null, Array.isArray(meta.after) ? meta.after : [], meta.effort || null, meta.model || null, meta.env_overrides || null, meta.task_type && VALID_TASK_TYPES.includes(meta.task_type)
                 ? meta.task_type
-                : null, meta.cloud_repo || null, meta.cloud_branch || null);
+                : null, meta.cloud_repo || null, meta.cloud_branch || null, meta.worktree_name || null, meta.worktree_path || null);
             agent.startTime = typeof meta.start_time === 'string' ? meta.start_time : null;
             return agent;
         }
@@ -971,7 +978,7 @@ export class AgentManager {
         }
         debug(`Loaded ${loadedCount} agents from disk`);
     }
-    async spawn(taskName, agentType, prompt, cwd = null, mode = null, effort = 'medium', parentSessionId = null, workspaceDir = null, version = null, name = null, after = [], model = null, envOverrides = null, taskType = null, cloudProvider = null, cloudSessionId = null, cloudRepo = null, cloudBranch = null) {
+    async spawn(taskName, agentType, prompt, cwd = null, mode = null, effort = 'medium', parentSessionId = null, workspaceDir = null, version = null, name = null, after = [], model = null, envOverrides = null, taskType = null, cloudProvider = null, cloudSessionId = null, cloudRepo = null, cloudBranch = null, worktreeName = null, worktreePath = null) {
         await this.initialize();
         const resolvedMode = resolveMode(mode, this.defaultMode);
         // Enforce: teammate names are unique within a team.
@@ -1030,7 +1037,7 @@ export class AgentManager {
         const initialStatus = isStaged || !isCloudBacked
             ? AgentStatus.PENDING
             : AgentStatus.RUNNING;
-        const agent = new AgentProcess(agentId, taskName, agentType, prompt, resolvedCwd, resolvedMode, null, initialStatus, new Date(), null, this.agentsDir, parentSessionId, workspaceDir, cloudSessionId, cloudProvider, null, version, null, name, cleanAfter, effort, model, envOverrides && Object.keys(envOverrides).length > 0 ? envOverrides : null, taskType, cloudRepo, cloudBranch);
+        const agent = new AgentProcess(agentId, taskName, agentType, prompt, resolvedCwd, resolvedMode, null, initialStatus, new Date(), null, this.agentsDir, parentSessionId, workspaceDir, cloudSessionId, cloudProvider, null, version, null, name, cleanAfter, effort, model, envOverrides && Object.keys(envOverrides).length > 0 ? envOverrides : null, taskType, cloudRepo, cloudBranch, worktreeName, worktreePath);
         const agentDir = await agent.getAgentDir();
         try {
             await fs.mkdir(agentDir, { recursive: true });

package/dist/lib/teams/api.d.ts

@@ -88,7 +88,7 @@ export interface TasksResult {
     tasks: TaskInfo[];
 }
 /** Spawn a new teammate in a task and return its initial metadata. */
-export declare function handleSpawn(manager: AgentManager, taskName: string, agentType: AgentType, prompt: string, cwd: string | null, mode: string | null, effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto' | null, parentSessionId?: string | null, workspaceDir?: string | null, version?: string | null, name?: string | null, after?: string[], model?: string | null, envOverrides?: Record<string, string> | null, taskType?: TaskType | null, cloudProvider?: string | null, cloudSessionId?: string | null, cloudRepo?: string | null, cloudBranch?: string | null): Promise<SpawnResult>;
+export declare function handleSpawn(manager: AgentManager, taskName: string, agentType: AgentType, prompt: string, cwd: string | null, mode: string | null, effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto' | null, parentSessionId?: string | null, workspaceDir?: string | null, version?: string | null, name?: string | null, after?: string[], model?: string | null, envOverrides?: Record<string, string> | null, taskType?: TaskType | null, cloudProvider?: string | null, cloudSessionId?: string | null, cloudRepo?: string | null, cloudBranch?: string | null, worktreeName?: string | null, worktreePath?: string | null): Promise<SpawnResult>;
 /** Retrieve the current status of all teammates in a task, with optional timestamp-based delta filtering. */
 export declare function handleStatus(manager: AgentManager, taskName: string | null | undefined, filter?: string, since?: string, // Optional ISO timestamp - return only events after this time
 parentSessionId?: string | null): Promise<TaskStatusResult>;

package/dist/lib/teams/api.js

@@ -56,12 +56,12 @@ function recentToolCalls(events, max = 10) {
     }));
 }
 /** Spawn a new teammate in a task and return its initial metadata. */
-export async function handleSpawn(manager, taskName, agentType, prompt, cwd, mode, effort = 'medium', parentSessionId = null, workspaceDir = null, version = null, name = null, after = [], model = null, envOverrides = null, taskType = null, cloudProvider = null, cloudSessionId = null, cloudRepo = null, cloudBranch = null) {
+export async function handleSpawn(manager, taskName, agentType, prompt, cwd, mode, effort = 'medium', parentSessionId = null, workspaceDir = null, version = null, name = null, after = [], model = null, envOverrides = null, taskType = null, cloudProvider = null, cloudSessionId = null, cloudRepo = null, cloudBranch = null, worktreeName = null, worktreePath = null) {
     const defaultMode = manager.getDefaultMode();
     const resolvedMode = resolveMode(mode, defaultMode);
     const resolvedEffort = effort ?? 'medium';
     debug(`[spawn] Spawning ${agentType} agent for task "${taskName}" [${resolvedMode}] effort=${resolvedEffort}...`);
-    const agent = await manager.spawn(taskName, agentType, prompt, cwd, resolvedMode, resolvedEffort, parentSessionId, workspaceDir, version, name, after, model, envOverrides, taskType, cloudProvider, cloudSessionId, cloudRepo, cloudBranch);
+    const agent = await manager.spawn(taskName, agentType, prompt, cwd, resolvedMode, resolvedEffort, parentSessionId, workspaceDir, version, name, after, model, envOverrides, taskType, cloudProvider, cloudSessionId, cloudRepo, cloudBranch, worktreeName, worktreePath);
     debug(`[spawn] Spawned ${agentType} agent ${agent.agentId} for task "${taskName}"`);
     return {
         task_name: taskName,

package/dist/lib/teams/index.d.ts

@@ -13,3 +13,4 @@ export { readConfig, resolveAgentsDir, resolveBaseDir, type EffortLevel, type Mo
 export { collapseEvents, getToolBreakdown, groupAndFlattenEvents, summarizeEvents, getDelta, filterEventsByPriority, getLastTool, getToolUses, getLastMessages, getQuickStatus, getStatusSummary, AgentSummary, PRIORITY, type QuickStatus, } from './summarizer.js';
 export { extractFileOpsFromBash } from './file_ops.js';
 export { debug } from './debug.js';
+export { createWorktree, removeWorktree, isGitRepo, getGitRoot, hasUncommittedChanges, getWorktreePath, getWorktreeBranch, } from './worktree.js';

package/dist/lib/teams/index.js

@@ -12,3 +12,4 @@ export { readConfig, resolveAgentsDir, resolveBaseDir, } from './persistence.js'
 export { collapseEvents, getToolBreakdown, groupAndFlattenEvents, summarizeEvents, getDelta, filterEventsByPriority, getLastTool, getToolUses, getLastMessages, getQuickStatus, getStatusSummary, AgentSummary, PRIORITY, } from './summarizer.js';
 export { extractFileOpsFromBash } from './file_ops.js';
 export { debug } from './debug.js';
+export { createWorktree, removeWorktree, isGitRepo, getGitRoot, hasUncommittedChanges, getWorktreePath, getWorktreeBranch, } from './worktree.js';

package/dist/lib/teams/persistence.js

@@ -13,7 +13,7 @@ import { homedir, tmpdir } from 'os';
 import { constants as fsConstants } from 'fs';
 import { randomBytes } from 'crypto';
 import lockfile from 'proper-lockfile';
-import { getAgentsDir } from '../state.js';
+import { getUserAgentsDir } from '../state.js';
 /**
  * Atomic JSON write: writes to a sibling tmp file then renames over the
  * target. rename(2) is atomic on POSIX, so a crashed/interrupted write
@@ -62,8 +62,8 @@ async function withConfigLock(p, fn) {
 }
 // All supported teammate agent types
 const ALL_AGENTS = ['claude', 'codex', 'gemini', 'cursor', 'opencode'];
-// Teams data lives under ~/.agents-system/teams/
-const TEAMS_DIR = path.join(getAgentsDir(), 'teams');
+// Teams data lives under ~/.agents/teams/
+const TEAMS_DIR = path.join(getUserAgentsDir(), 'teams');
 // Legacy paths (for migration)
 const LEGACY_CONFIG_DIR = path.join(homedir(), '.agents');
 // Legacy migration from pre-OSS brand; safe to remove after 2026-07

package/dist/lib/teams/registry.d.ts

@@ -2,6 +2,9 @@
 export interface TeamMeta {
     created_at: string;
     description?: string;
+    enable_worktrees?: boolean;
+    /** Shared worktree path for all teammates (mutually exclusive with enable_worktrees). */
+    use_worktree?: string;
 }
 /** Map of team name to team metadata. */
 export type TeamRegistry = Record<string, TeamMeta>;
@@ -12,11 +15,19 @@ export type TeamRegistry = Record<string, TeamMeta>;
  * write, which is exactly the data-loss path we are trying to close.
  */
 export declare function loadTeams(): Promise<TeamRegistry>;
+export interface CreateTeamOptions {
+    description?: string;
+    enableWorktrees?: boolean;
+    /** Path to an existing worktree for all teammates to share. */
+    useWorktree?: string;
+}
 /** Create a new team. Throws if a team with the same name already exists. */
-export declare function createTeam(name: string, description?: string): Promise<TeamMeta>;
+export declare function createTeam(name: string, options?: CreateTeamOptions): Promise<TeamMeta>;
 /** Return existing team metadata or create a new team if it does not exist. */
 export declare function ensureTeam(name: string): Promise<TeamMeta>;
 /** Remove a team from the registry. Returns false if the team did not exist. */
 export declare function removeTeam(name: string): Promise<boolean>;
 /** Check whether a team with the given name exists in the registry. */
 export declare function teamExists(name: string): Promise<boolean>;
+/** Get metadata for a specific team. Returns null if team does not exist. */
+export declare function getTeam(name: string): Promise<TeamMeta | null>;

package/dist/lib/teams/registry.js

@@ -91,7 +91,10 @@ async function saveTeams(reg) {
     await atomicWriteJson(p, reg);
 }
 /** Create a new team. Throws if a team with the same name already exists. */
-export async function createTeam(name, description) {
+export async function createTeam(name, options) {
+    if (options?.enableWorktrees && options?.useWorktree) {
+        throw new Error('Cannot use both --enable-worktrees and --use-worktree. Pick one.');
+    }
     const p = await registryPath();
     return withRegistryLock(p, async () => {
         const reg = await loadTeams();
@@ -100,7 +103,9 @@ export async function createTeam(name, description) {
         }
         const meta = {
             created_at: new Date().toISOString(),
-            ...(description ? { description } : {}),
+            ...(options?.description ? { description: options.description } : {}),
+            ...(options?.enableWorktrees ? { enable_worktrees: true } : {}),
+            ...(options?.useWorktree ? { use_worktree: options.useWorktree } : {}),
         };
         reg[name] = meta;
         await saveTeams(reg);
@@ -137,3 +142,8 @@ export async function teamExists(name) {
     const reg = await loadTeams();
     return Boolean(reg[name]);
 }
+/** Get metadata for a specific team. Returns null if team does not exist. */
+export async function getTeam(name) {
+    const reg = await loadTeams();
+    return reg[name] ?? null;
+}