@agenthippo-ai/agenthippo 0.1.0

package/out/sync.js

@@ -0,0 +1,1827 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) AgentHippo.ai. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SyncService = void 0;
+const vscode = __importStar(require("vscode"));
+const fs_1 = require("fs");
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const utils_1 = require("./utils");
+const remoteSkills_1 = require("./remoteSkills");
+const branding_1 = require("./branding");
+const paths_1 = require("./agentpack/paths");
+const manifest_1 = require("./agentpack/manifest");
+const mcp_1 = require("./mcp");
+const customRegistry_1 = require("./engines/customRegistry");
+// -----------------------------------------------------------------------------
+// Constants
+// -----------------------------------------------------------------------------
+const AGENTIDE_DERIVED_DIR_README = 'AGENTIDE_README.md';
+const AGENTIDE_CONTEXT_FILE = 'context.md';
+const AGENTIDE_MANIFEST_FILE = 'agentide.manifest.json';
+const AGENTIDE_INSTALLED_AGENTS_FILE = 'installed-agents.json';
+const AGENTIDE_MANIFEST_DEBOUNCE_MS = 2000;
+const AGENTIDE_AGENT_YAML = 'agent.yaml';
+const AGENTIDE_AGENTS_DIR = 'agents';
+const AGENTIDE_DEFAULT_AGENT_ID = 'default';
+const AGENTIDE_DIR_NAME = paths_1.AGENT_CONSTANTS.AGENTIDE_DIR_NAME;
+// Use unified AGENT_ENGINES from shared
+const shared_1 = require("./shared");
+function getConfiguredAdditionalEngineDir() {
+    return vscode.workspace
+        .getConfiguration('agentide')
+        .get('additionalEngineDir');
+}
+function getDerivedEngineSyncTargets(workspaceRoot) {
+    const builtins = Object.values(shared_1.AGENT_ENGINES).map(engine => ({
+        id: engine.id,
+        displayName: engine.displayName,
+        workspaceDir: engine.workspaceDir,
+        rulesFile: engine.rulesFile,
+        managedPaths: engine.managedPaths,
+        includeSkills: true,
+        includeRules: true,
+    }));
+    const custom = (0, customRegistry_1.discoverCustomEngineManifests)(workspaceRoot, getConfiguredAdditionalEngineDir())
+        .filter(manifest => manifest.workspaceSync?.enabled)
+        .map(manifest => ({
+        id: manifest.id,
+        displayName: manifest.displayName ?? manifest.id,
+        workspaceDir: manifest.workspaceSync.dir,
+        rulesFile: manifest.workspaceSync.rulesFile,
+        includeSkills: manifest.workspaceSync.includeSkills,
+        includeRules: manifest.workspaceSync.includeRules,
+    }));
+    return [...builtins, ...custom];
+}
+function getSkillDirNameFromRelPath(relPath) {
+    const normalized = relPath.replace(/\\/g, '/');
+    const parts = normalized.split('/').filter(Boolean);
+    const skillsIndex = parts.indexOf('skills');
+    if (skillsIndex !== -1 && parts.length > skillsIndex + 1) {
+        return parts[skillsIndex + 1];
+    }
+    // Common case: skills/<dir>/SKILL.md
+    if (parts.length >= 3 && parts[0] === 'skills') {
+        return parts[1];
+    }
+    return undefined;
+}
+/**
+ * Parse YAML front matter from a SKILL.md file.
+ * Expects format:
+ * ```
+ * ---
+ * name: skill-name
+ * description: A description of the skill
+ * ---
+ * # Content...
+ * ```
+ */
+function parseSkillYamlHeader(content) {
+    const result = {};
+    // Check for YAML front matter (starts with ---)
+    if (!content.startsWith('---')) {
+        return result;
+    }
+    // Find the closing ---
+    const lines = content.split('\n');
+    let endIndex = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i].trim() === '---') {
+            endIndex = i;
+            break;
+        }
+    }
+    if (endIndex === -1) {
+        return result;
+    }
+    // Parse YAML content (simple key: value parsing, no full YAML library needed)
+    for (let i = 1; i < endIndex; i++) {
+        const line = lines[i];
+        const colonIndex = line.indexOf(':');
+        if (colonIndex === -1) {
+            continue;
+        }
+        const key = line.substring(0, colonIndex).trim().toLowerCase();
+        let value = line.substring(colonIndex + 1).trim();
+        // Remove surrounding quotes if present
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith('\'') && value.endsWith('\''))) {
+            value = value.slice(1, -1);
+        }
+        if (key === 'name' && value) {
+            result.name = value;
+        }
+        else if (key === 'description' && value) {
+            result.description = value;
+        }
+    }
+    return result;
+}
+function parseYaml(content) {
+    const yaml = require('js-yaml');
+    return yaml.load(content);
+}
+function dumpYaml(doc) {
+    const yaml = require('js-yaml');
+    return yaml.dump(doc, { lineWidth: 120, noRefs: true });
+}
+async function isDirEmpty(targetDir) {
+    const entries = await fs_1.promises.readdir(targetDir);
+    return entries.length === 0;
+}
+// -----------------------------------------------------------------------------
+// Sync Service
+// -----------------------------------------------------------------------------
+class SyncService {
+    getBundledBasePromptsDir;
+    // Cache for tracking .agentide/ directory state to avoid redundant syncs
+    lastAgentideSyncSignatureByRoot = new Map();
+    agentideSignatureByRoot = new Map();
+    agentideSkillsSignatureByRoot = new Map();
+    agentideRootUpdateState = new Map();
+    agentideWatchersByRoot = new Map();
+    // Track active agent turns to avoid syncing while agent is running
+    activeAgentTurns = 0;
+    // Track active pack per workspace root (for pack-aware file watching)
+    activePackIdByRoot = new Map();
+    // mtime cache for getActiveAgentManifest — handleChatCommand reads this on every turn just
+    // to check spec.remote.url, so avoid a stat+read+parse per message on the hot chat path.
+    activeAgentManifestCache = new Map();
+    constructor(getBundledBasePromptsDir) {
+        this.getBundledBasePromptsDir = getBundledBasePromptsDir;
+    }
+    /**
+     * Set the active pack ID for a workspace root.
+     * This is used by the file watcher to determine which pack to sync.
+     */
+    setActivePackId(workspaceRoot, packId) {
+        this.activePackIdByRoot.set(workspaceRoot, packId);
+    }
+    /**
+     * Get the active pack ID for a workspace root.
+     */
+    getActivePackId(workspaceRoot) {
+        return this.activePackIdByRoot.get(workspaceRoot);
+    }
+    incrementActiveAgentTurns() {
+        this.activeAgentTurns++;
+    }
+    decrementActiveAgentTurns() {
+        this.activeAgentTurns = Math.max(0, this.activeAgentTurns - 1);
+    }
+    getSkillsSignature(workspaceRoot) {
+        return this.agentideSkillsSignatureByRoot.get(workspaceRoot);
+    }
+    async computeWorkspaceAgentideSignature(workspaceRoot, additionalDirectories) {
+        const workspaceFolderRoots = vscode.workspace.workspaceFolders?.map(f => f.uri.fsPath) ?? [];
+        const additionalWorkspaceRoots = (additionalDirectories ?? []).filter(d => workspaceFolderRoots.includes(d));
+        const roots = Array.from(new Set([workspaceRoot, ...additionalWorkspaceRoots].map(r => r.trim()).filter(Boolean)))
+            .filter(r => r !== os.homedir());
+        const pairs = [];
+        for (const root of roots) {
+            let sig = this.agentideSignatureByRoot.get(root);
+            if (!sig) {
+                sig = (await this.readAgentideManifest(root))?.agentideSignature;
+                if (sig) {
+                    this.agentideSignatureByRoot.set(root, sig);
+                }
+            }
+            pairs.push([root, sig ?? 'missing']);
+        }
+        pairs.sort((a, b) => a[0].localeCompare(b[0]));
+        return (0, utils_1.shortSig)(JSON.stringify(pairs));
+    }
+    // -------------------------------------------------------------------------
+    // Managed Resources
+    // -------------------------------------------------------------------------
+    getManagedResources(codexHome, claudeConfigDir, workspaceRoots) {
+        const resources = [];
+        const roots = Array.from(new Set(workspaceRoots.map(r => r.trim()).filter(Boolean)))
+            .filter(r => r !== os.homedir());
+        // Build config dir lookup from EngineConfig
+        const configDirs = {
+            codexHome,
+            claudeConfigDir,
+        };
+        // Map engine configEnvVar to config key
+        const envVarToKey = {
+            'CODEX_HOME': 'codexHome',
+            'CLAUDE_CONFIG_DIR': 'claudeConfigDir',
+        };
+        // Add engine-specific managed resources from AGENT_ENGINES
+        for (const engine of Object.values(shared_1.AGENT_ENGINES)) {
+            const configKey = engine.configEnvVar ? envVarToKey[engine.configEnvVar] : undefined;
+            const configDir = configKey ? configDirs[configKey] : undefined;
+            if (!configDir) {
+                continue;
+            }
+            if (engine.managedPaths?.length) {
+                // Engine specifies individual managed paths
+                for (const managedPath of engine.managedPaths) {
+                    const isDir = !managedPath.includes('.');
+                    resources.push({
+                        path: path.join(configDir, managedPath),
+                        type: isDir ? 'directory' : 'generated',
+                        description: `${engine.displayName} ${managedPath} (managed by AgentIDE)`,
+                        safeToDelete: true,
+                    });
+                }
+            }
+            else {
+                // Engine manages the entire config dir
+                resources.push({
+                    path: configDir,
+                    type: 'directory',
+                    description: `${engine.displayName} config dir (managed by AgentIDE)`,
+                    safeToDelete: true,
+                });
+            }
+        }
+        // Add workspace-level resources
+        for (const root of roots) {
+            resources.push({
+                path: path.join(root, AGENTIDE_DIR_NAME),
+                type: 'directory',
+                description: 'AgentIDE project rules & skills (source-of-truth)',
+                safeToDelete: false,
+            });
+            // Add derived engine directories from built-in and custom engine manifests.
+            for (const engine of getDerivedEngineSyncTargets(root)) {
+                resources.push({
+                    path: path.join(root, engine.workspaceDir),
+                    type: 'directory',
+                    description: `${engine.displayName} project folder (derived/overwritten from ${AGENTIDE_DIR_NAME}/)`,
+                    safeToDelete: true,
+                });
+            }
+        }
+        return resources;
+    }
+    async writeManagedPathsManifest(codexHome, claudeConfigDir, workspaceRoot, additionalDirectories, outputChannel) {
+        if (!workspaceRoot || workspaceRoot === os.homedir()) {
+            return;
+        }
+        const agentideDir = this.getAgentideProjectDir(workspaceRoot);
+        const manifestPath = path.join(agentideDir, 'paths.md');
+        const resources = this.getManagedResources(codexHome, claudeConfigDir, [workspaceRoot, ...(additionalDirectories ?? [])]);
+        const lines = [
+            '# AgentIDE Managed Resources',
+            '',
+            'This file lists all files and directories managed by the AgentIDE extension.',
+            '**Auto-generated** - Do not edit manually.',
+            '',
+            `**Workspace:** \`${workspaceRoot}\``,
+            codexHome ? `**Codex Home:** \`${codexHome}\`` : '',
+            claudeConfigDir ? `**Claude Config Dir:** \`${claudeConfigDir}\`` : '',
+            '',
+            '## Resources',
+            '',
+            '| Path | Type | Safe to Delete | Description |',
+            '|------|------|----------------|-------------|',
+        ];
+        for (const r of resources) {
+            const exists = await (0, utils_1.pathExists)(r.path);
+            const status = exists ? '[x]' : '[ ]';
+            lines.push(`| ${status} \`${r.path}\` | ${r.type} | ${r.safeToDelete ? 'Yes' : 'No'} | ${r.description} |`);
+        }
+        lines.push('');
+        lines.push('## How to Reset');
+        lines.push('');
+        lines.push('Run the command: **AgentIDE: Clear Managed Resources**');
+        lines.push('');
+        lines.push('This will:');
+        lines.push('- Remove symlinks created by the extension');
+        lines.push('- Delete generated files (context.md, config.toml, etc.)');
+        lines.push(`- **NOT** delete user-managed rules/skills inside \`${AGENTIDE_DIR_NAME}/\``);
+        lines.push('');
+        await fs_1.promises.mkdir(agentideDir, { recursive: true });
+        await (0, utils_1.writeFileIfChanged)(manifestPath, lines.filter(Boolean).join('\n'));
+        outputChannel.appendLine(`[AgentIDE] Wrote manifest: ${manifestPath}`);
+    }
+    async clearManagedResources(codexHome, claudeConfigDir, workspaceRoot, additionalDirectories, outputChannel) {
+        const resources = this.getManagedResources(codexHome, claudeConfigDir, [workspaceRoot ?? '', ...(additionalDirectories ?? [])]);
+        const cleared = [];
+        const skipped = [];
+        const errors = [];
+        for (const r of resources) {
+            if (!r.safeToDelete) {
+                skipped.push(r.path);
+                continue;
+            }
+            try {
+                const stat = await fs_1.promises.lstat(r.path);
+                if (r.type === 'symlink') {
+                    if (stat.isSymbolicLink()) {
+                        await fs_1.promises.unlink(r.path);
+                        cleared.push(r.path);
+                        outputChannel.appendLine(`[AgentIDE] Removed symlink: ${r.path}`);
+                    }
+                    else {
+                        skipped.push(r.path);
+                        outputChannel.appendLine(`[AgentIDE] Skipped (not a symlink): ${r.path}`);
+                    }
+                }
+                else if (r.type === 'generated') {
+                    if (stat.isFile()) {
+                        await fs_1.promises.unlink(r.path);
+                        cleared.push(r.path);
+                        outputChannel.appendLine(`[AgentIDE] Removed generated file: ${r.path}`);
+                    }
+                }
+                else if (r.type === 'directory' && r.safeToDelete) {
+                    if (stat.isDirectory()) {
+                        await fs_1.promises.rm(r.path, { recursive: true, force: true });
+                        cleared.push(r.path);
+                        outputChannel.appendLine(`[AgentIDE] Removed directory: ${r.path}`);
+                    }
+                }
+            }
+            catch (e) {
+                if ((0, utils_1.getErrorCode)(e) !== 'ENOENT') {
+                    errors.push(`${r.path}: ${e instanceof Error ? e.message : String(e)}`);
+                }
+            }
+        }
+        // Reset internal state
+        this.lastAgentideSyncSignatureByRoot.clear();
+        this.agentideSignatureByRoot.clear();
+        this.agentideSkillsSignatureByRoot.clear();
+        return { cleared, skipped, errors };
+    }
+    // -------------------------------------------------------------------------
+    // Manifest Management
+    // -------------------------------------------------------------------------
+    getAgentideProjectDir(workspaceRoot) {
+        return (0, paths_1.getAgentideDir)(workspaceRoot);
+    }
+    /**
+     * Get the agents directory path (.agentide/agents/).
+     */
+    getAgentsDir(workspaceRoot) {
+        return path.join(this.getAgentideProjectDir(workspaceRoot), AGENTIDE_AGENTS_DIR);
+    }
+    /**
+     * Get the root directory for a specific agent.
+     */
+    getAgentRoot(workspaceRoot, agentId) {
+        return path.join(this.getAgentsDir(workspaceRoot), agentId);
+    }
+    /**
+     * Get skills directory for an agent.
+     */
+    getAgentSkillsDir(workspaceRoot, agentId) {
+        return path.join(this.getAgentRoot(workspaceRoot, agentId), 'skills');
+    }
+    /**
+     * Get rules directory for an agent.
+     */
+    getAgentRulesDir(workspaceRoot, agentId) {
+        return path.join(this.getAgentRoot(workspaceRoot, agentId), 'rules');
+    }
+    /**
+     * Get AGENTS.md file path for an agent.
+     */
+    getAgentAgentsFile(workspaceRoot, agentId) {
+        return path.join(this.getAgentRoot(workspaceRoot, agentId), 'AGENTS.md');
+    }
+    /**
+     * Get context.md file path for an agent.
+     */
+    getAgentContextFile(workspaceRoot, agentId) {
+        return path.join(this.getAgentRoot(workspaceRoot, agentId), AGENTIDE_CONTEXT_FILE);
+    }
+    /**
+     * Get the active agent ID, defaulting to 'default'.
+     */
+    getActiveAgentId(workspaceRoot) {
+        return this.getActivePackId(workspaceRoot) ?? AGENTIDE_DEFAULT_AGENT_ID;
+    }
+    async resolveManifestSource(workspaceRoot, agentIdOverride) {
+        // All agents (including default) live in .agentide/agents/<agentId>/
+        const agentId = agentIdOverride ?? this.getActiveAgentId(workspaceRoot);
+        const agentRoot = this.getAgentRoot(workspaceRoot, agentId);
+        return {
+            agentId,
+            isPack: agentId !== AGENTIDE_DEFAULT_AGENT_ID,
+            agentRoot,
+            agentsFile: this.getAgentAgentsFile(workspaceRoot, agentId),
+            contextFile: this.getAgentContextFile(workspaceRoot, agentId),
+            rulesDir: this.getAgentRulesDir(workspaceRoot, agentId),
+            skillsDir: this.getAgentSkillsDir(workspaceRoot, agentId),
+            agentYamlPath: path.join(agentRoot, AGENTIDE_AGENT_YAML),
+        };
+    }
+    async getDataPathsForAgent(workspaceRoot, agentId, outputChannel) {
+        const agentRoot = this.getAgentRoot(workspaceRoot, agentId);
+        const agentYamlPath = path.join(agentRoot, AGENTIDE_AGENT_YAML);
+        if (!(await (0, utils_1.pathExists)(agentYamlPath))) {
+            return undefined;
+        }
+        try {
+            const manifest = await (0, manifest_1.loadAgentManifest)(agentYamlPath);
+            const data = manifest.spec?.data;
+            if (!data) {
+                return undefined;
+            }
+            const sourcePath = (data.sourcePath?.trim() || './data');
+            const workspacePath = (data.workspacePath?.trim() || `.${path.sep}${AGENTIDE_DIR_NAME}${path.sep}data${path.sep}${agentId}`)
+                .replace(/^(?:\.\/|\.\\)/, '');
+            const sourceDir = path.resolve(agentRoot, sourcePath);
+            const targetDir = path.resolve(workspaceRoot, workspacePath);
+            return { sourceDir, targetDir };
+        }
+        catch (e) {
+            (0, utils_1.logInfo)(outputChannel, `[AgentIDE] Skipping data sync for ${agentId}: failed to parse data config (${e instanceof Error ? e.message : String(e)})`);
+            return undefined;
+        }
+    }
+    async seedAgentDataIfNeeded(workspaceRoot, agentId, outputChannel) {
+        const dataPaths = await this.getDataPathsForAgent(workspaceRoot, agentId, outputChannel);
+        if (!dataPaths) {
+            return;
+        }
+        const { sourceDir, targetDir } = dataPaths;
+        if (!(await (0, utils_1.pathExists)(sourceDir))) {
+            return;
+        }
+        if (!(await (0, utils_1.pathExists)(targetDir))) {
+            await (0, utils_1.copyDirRecursive)(sourceDir, targetDir);
+            (0, utils_1.logInfo)(outputChannel, `[AgentIDE] Seeded pack data for ${agentId}: ${targetDir}`);
+            return;
+        }
+        try {
+            const st = await fs_1.promises.stat(targetDir);
+            if (!st.isDirectory()) {
+                return;
+            }
+        }
+        catch {
+            return;
+        }
+        if (await isDirEmpty(targetDir)) {
+            await (0, utils_1.copyDirRecursive)(sourceDir, targetDir);
+            (0, utils_1.logInfo)(outputChannel, `[AgentIDE] Seeded pack data for ${agentId}: ${targetDir}`);
+        }
+    }
+    async syncAgentYamlSkills(workspaceRoot, agentId, manifest, outputChannel) {
+        const agentYamlPath = path.join(this.getAgentRoot(workspaceRoot, agentId), AGENTIDE_AGENT_YAML);
+        if (!(await (0, utils_1.pathExists)(agentYamlPath))) {
+            return;
+        }
+        try {
+            const raw = await fs_1.promises.readFile(agentYamlPath, 'utf8');
+            const parsed = parseYaml(raw);
+            if (!parsed || typeof parsed !== 'object') {
+                return;
+            }
+            const doc = parsed;
+            const skillPaths = manifest.skills.map(skill => ({ path: `./skills/${skill.dirName}` }));
+            doc.spec = { ...(doc.spec ?? {}), skills: skillPaths };
+            const next = dumpYaml(doc);
+            await (0, utils_1.writeFileIfChanged)(agentYamlPath, next);
+        }
+        catch (e) {
+            outputChannel.appendLine(`[AgentIDE] Warning: failed to update agent.yaml skills for ${agentId}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    /**
+     * Get the active agent's manifest (agent.yaml) for permission resolution.
+     * Returns undefined if the manifest doesn't exist or can't be parsed.
+     *
+     * Cached by file mtime/size: handleChatCommand calls this on every turn to check
+     * spec.remote.url, so we avoid a stat + read + full YAML parse per message. The
+     * "no agent.yaml" / "invalid" log lines fire only on state transitions, not every
+     * cached return, to keep the output channel clean.
+     */
+    async getActiveAgentManifest(workspaceRoot, outputChannel, agentIdOverride) {
+        const agentId = agentIdOverride ?? this.getActiveAgentId(workspaceRoot);
+        const agentYamlPath = path.join(this.getAgentRoot(workspaceRoot, agentId), AGENTIDE_AGENT_YAML);
+        const stats = await (0, utils_1.getFileStats)(agentYamlPath);
+        if (!stats) {
+            const cached = this.activeAgentManifestCache.get(agentYamlPath);
+            if (!cached?.loggedNoManifest) {
+                outputChannel.appendLine(`[AgentIDE] No agent.yaml found for agent ${agentId}`);
+            }
+            this.activeAgentManifestCache.set(agentYamlPath, {
+                mtimeMs: -1, size: -1, manifest: undefined,
+                loggedNoManifest: true, loggedInvalid: cached?.loggedInvalid ?? false,
+            });
+            return undefined;
+        }
+        const cached = this.activeAgentManifestCache.get(agentYamlPath);
+        if (cached && cached.mtimeMs === stats.mtimeMs && cached.size === stats.size) {
+            return cached.manifest;
+        }
+        try {
+            const raw = await fs_1.promises.readFile(agentYamlPath, 'utf8');
+            const parsed = parseYaml(raw);
+            // Basic validation
+            if (!parsed?.metadata?.name || !parsed?.spec?.engine) {
+                if (!cached?.loggedInvalid) {
+                    outputChannel.appendLine(`[AgentIDE] Invalid agent.yaml for agent ${agentId}: missing required fields`);
+                }
+                this.activeAgentManifestCache.set(agentYamlPath, {
+                    mtimeMs: stats.mtimeMs, size: stats.size, manifest: undefined,
+                    loggedNoManifest: false, loggedInvalid: true,
+                });
+                return undefined;
+            }
+            this.activeAgentManifestCache.set(agentYamlPath, {
+                mtimeMs: stats.mtimeMs, size: stats.size, manifest: parsed,
+                loggedNoManifest: false, loggedInvalid: false,
+            });
+            return parsed;
+        }
+        catch (e) {
+            if (!cached?.loggedInvalid) {
+                outputChannel.appendLine(`[AgentIDE] Failed to parse agent.yaml for agent ${agentId}: ${e instanceof Error ? e.message : String(e)}`);
+            }
+            this.activeAgentManifestCache.set(agentYamlPath, {
+                mtimeMs: stats.mtimeMs, size: stats.size, manifest: undefined,
+                loggedNoManifest: false, loggedInvalid: true,
+            });
+            return undefined;
+        }
+    }
+    getAgentideManifestFilePath(workspaceRoot) {
+        return path.join(this.getAgentideProjectDir(workspaceRoot), AGENTIDE_MANIFEST_FILE);
+    }
+    /**
+     * Check if all derived provider directories exist for the given workspace root.
+     */
+    async allDerivedDirsPresent(workspaceRoot) {
+        const results = await Promise.all(getDerivedEngineSyncTargets(workspaceRoot).map(engine => (0, utils_1.isDirOrSymlink)(path.join(workspaceRoot, engine.workspaceDir))));
+        return results.every(Boolean);
+    }
+    async readAgentideManifest(workspaceRoot) {
+        const manifestPath = this.getAgentideManifestFilePath(workspaceRoot);
+        try {
+            const raw = await fs_1.promises.readFile(manifestPath, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (parsed.version !== 1 || typeof parsed.agentideSignature !== 'string') {
+                return undefined;
+            }
+            return parsed;
+        }
+        catch (e) {
+            if ((0, utils_1.getErrorCode)(e) === 'ENOENT') {
+                return undefined;
+            }
+            return undefined;
+        }
+    }
+    async computeAgentideManifest(workspaceRoot, source, cachedManifest) {
+        const rulesDir = source.rulesDir;
+        const skillsDir = source.skillsDir;
+        // Build lookup maps from cached manifest for fast path (mtime caching)
+        const cachedRulesByPath = new Map();
+        const cachedSkillsByDirName = new Map();
+        if (cachedManifest) {
+            for (const rule of cachedManifest.rules) {
+                cachedRulesByPath.set(rule.relPath, rule);
+            }
+            for (const skill of cachedManifest.skills) {
+                const dirName = skill.dirName || getSkillDirNameFromRelPath(skill.skillMdRelPath) || skill.name;
+                cachedSkillsByDirName.set(dirName, skill);
+            }
+        }
+        const rules = [];
+        const skills = [];
+        // Helper to get file hash with mtime caching (avoids re-hashing unchanged files)
+        const getFileHashWithCache = async (filePath, relPath) => {
+            const stats = await (0, utils_1.getFileStats)(filePath);
+            if (!stats) {
+                return undefined;
+            }
+            const cached = cachedRulesByPath.get(relPath);
+            const validCache = (0, utils_1.isCachedHashValid)(cached, stats);
+            if (validCache) {
+                return validCache; // Fast path: file unchanged, reuse cached hash
+            }
+            // Slow path: file changed, compute new hash
+            const { sha256, size, mtimeMs } = await (0, utils_1.readFileSha256)(filePath);
+            return { relPath, sha256, size, mtimeMs };
+        };
+        const agentsFile = source.agentsFile;
+        const agentsEntry = await getFileHashWithCache(agentsFile, 'AGENTS.md');
+        if (agentsEntry) {
+            rules.push(agentsEntry);
+        }
+        const contextFile = source.contextFile;
+        const contextEntry = await getFileHashWithCache(contextFile, AGENTIDE_CONTEXT_FILE);
+        if (contextEntry) {
+            rules.push(contextEntry);
+        }
+        try {
+            const entries = await fs_1.promises.readdir(rulesDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isFile() || !entry.name.toLowerCase().endsWith('.md')) {
+                    continue;
+                }
+                const abs = path.join(rulesDir, entry.name);
+                const relPath = path.join('rules', entry.name).replace(/\\/g, '/');
+                const ruleEntry = await getFileHashWithCache(abs, relPath);
+                if (ruleEntry) {
+                    rules.push(ruleEntry);
+                }
+            }
+        }
+        catch {
+            // ignore
+        }
+        try {
+            const entries = await fs_1.promises.readdir(skillsDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory()) {
+                    continue;
+                }
+                if (entry.name.startsWith('.')) {
+                    continue;
+                }
+                const skillMd = path.join(skillsDir, entry.name, 'SKILL.md');
+                const stats = await (0, utils_1.getFileStats)(skillMd);
+                if (!stats) {
+                    continue;
+                }
+                const cached = cachedSkillsByDirName.get(entry.name);
+                const validCache = cached && cached.skillMdMtimeMs === stats.mtimeMs && cached.skillMdSize === stats.size;
+                if (validCache) {
+                    // Fast path: skill unchanged, reuse cached entry entirely (including name/description from manifest)
+                    skills.push({
+                        ...cached,
+                        dirName: entry.name, // Ensure dirName is set (for old manifests that might not have it)
+                    });
+                }
+                else {
+                    // Slow path: skill changed, compute new hash and parse YAML header
+                    const { sha256, size, mtimeMs } = await (0, utils_1.readFileSha256)(skillMd);
+                    // Read file content to parse YAML header for name/description
+                    let yamlName;
+                    let yamlDescription;
+                    try {
+                        const content = await fs_1.promises.readFile(skillMd, 'utf-8');
+                        const header = parseSkillYamlHeader(content);
+                        yamlName = header.name;
+                        yamlDescription = header.description;
+                    }
+                    catch {
+                        // Ignore read errors, use directory name as fallback
+                    }
+                    skills.push({
+                        dirName: entry.name,
+                        name: yamlName || entry.name, // Prefer YAML name, fallback to directory name
+                        description: yamlDescription,
+                        skillMdRelPath: path.join('skills', entry.name, 'SKILL.md').replace(/\\/g, '/'),
+                        skillMdSha256: sha256,
+                        skillMdSize: size,
+                        skillMdMtimeMs: mtimeMs,
+                    });
+                }
+            }
+        }
+        catch {
+            // ignore
+        }
+        rules.sort((a, b) => a.relPath.localeCompare(b.relPath));
+        skills.sort((a, b) => a.dirName.localeCompare(b.dirName));
+        const rulesSignature = (0, utils_1.shortSig)(JSON.stringify(rules.map(r => [r.relPath, r.sha256])));
+        // Use dirName (stable folder identifier) to ensure signature changes when a skill folder is renamed.
+        const skillsSignature = (0, utils_1.shortSig)(JSON.stringify(skills.map(s => [s.dirName, s.skillMdSha256])));
+        const agentideSignature = (0, utils_1.shortSig)(`${rulesSignature}:${skillsSignature}`);
+        return {
+            version: 1,
+            workspaceRoot,
+            generatedAt: new Date().toISOString(),
+            activeAgentId: source.agentId,
+            rules,
+            skills,
+            rulesSignature,
+            skillsSignature,
+            agentideSignature,
+        };
+    }
+    async writeAgentideManifest(workspaceRoot, outputChannel, options) {
+        const agentideDir = this.getAgentideProjectDir(workspaceRoot);
+        if (!(await (0, utils_1.pathExists)(agentideDir))) {
+            await fs_1.promises.mkdir(agentideDir, { recursive: true });
+        }
+        const existing = await this.readAgentideManifest(workspaceRoot);
+        const source = await this.resolveManifestSource(workspaceRoot, options?.packIdOverride);
+        const useCache = existing?.activeAgentId === source.agentId;
+        // Pass existing manifest for mtime caching (avoids re-hashing unchanged files)
+        const manifest = await this.computeAgentideManifest(workspaceRoot, source, useCache ? existing : undefined);
+        manifest.derivedSkillIngestState = useCache ? (options?.derivedSkillIngestState ?? existing?.derivedSkillIngestState) : options?.derivedSkillIngestState;
+        // Note: installedAgents is now stored in separate installed-agents.json file
+        const manifestPath = this.getAgentideManifestFilePath(workspaceRoot);
+        await (0, utils_1.writeFileIfChanged)(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+        this.agentideSignatureByRoot.set(workspaceRoot, manifest.agentideSignature);
+        this.agentideSkillsSignatureByRoot.set(workspaceRoot, manifest.skillsSignature);
+        outputChannel.appendLine(`[AgentIDE] Updated manifest: ${manifestPath} (sig=${manifest.agentideSignature})`);
+        if (!source.isPack) {
+            await this.syncAgentYamlSkills(workspaceRoot, source.agentId, manifest, outputChannel);
+        }
+        return manifest;
+    }
+    // -------------------------------------------------------------------------
+    // File Watchers
+    // -------------------------------------------------------------------------
+    ensureAgentideWatchers(outputChannel) {
+        const roots = vscode.workspace.workspaceFolders?.map(f => f.uri.fsPath) ?? [];
+        const existingRoots = new Set(this.agentideWatchersByRoot.keys());
+        for (const root of existingRoots) {
+            if (!roots.includes(root)) {
+                this.disposeAgentideWatchersForRoot(root);
+                this.agentideRootUpdateState.delete(root);
+                this.lastAgentideSyncSignatureByRoot.delete(root);
+                this.agentideSignatureByRoot.delete(root);
+                this.agentideSkillsSignatureByRoot.delete(root);
+            }
+        }
+        for (const root of roots) {
+            if (this.agentideWatchersByRoot.has(root)) {
+                continue;
+            }
+            // Watch all agents in the agent root
+            const patterns = [
+                { pattern: new vscode.RelativePattern(root, `${AGENTIDE_DIR_NAME}/${AGENTIDE_AGENTS_DIR}/*/agent.yaml`), reason: 'source' },
+                { pattern: new vscode.RelativePattern(root, `${AGENTIDE_DIR_NAME}/${AGENTIDE_AGENTS_DIR}/*/AGENTS.md`), reason: 'source' },
+                { pattern: new vscode.RelativePattern(root, `${AGENTIDE_DIR_NAME}/${AGENTIDE_AGENTS_DIR}/*/context.md`), reason: 'source' },
+                { pattern: new vscode.RelativePattern(root, `${AGENTIDE_DIR_NAME}/${AGENTIDE_AGENTS_DIR}/*/rules/**/*.md`), reason: 'source' },
+                { pattern: new vscode.RelativePattern(root, `${AGENTIDE_DIR_NAME}/${AGENTIDE_AGENTS_DIR}/*/skills/**/*`), reason: 'source' },
+                // Also watch agents/ for pack changes (to detect new/updated packs)
+                { pattern: new vscode.RelativePattern(root, `${AGENTIDE_DIR_NAME}/${AGENTIDE_AGENTS_DIR}/*/AGENTS.md`), reason: 'source' },
+                { pattern: new vscode.RelativePattern(root, `${AGENTIDE_DIR_NAME}/${AGENTIDE_AGENTS_DIR}/*/context.md`), reason: 'source' },
+                { pattern: new vscode.RelativePattern(root, `${AGENTIDE_DIR_NAME}/${AGENTIDE_AGENTS_DIR}/*/rules/**/*.md`), reason: 'source' },
+                { pattern: new vscode.RelativePattern(root, `${AGENTIDE_DIR_NAME}/${AGENTIDE_AGENTS_DIR}/*/skills/**/*`), reason: 'source' },
+                { pattern: new vscode.RelativePattern(root, `${AGENTIDE_DIR_NAME}/${AGENTIDE_AGENTS_DIR}/*/agent.yaml`), reason: 'source' },
+                // Watch derived engine directories for ingest back to .agentide
+                ...getDerivedEngineSyncTargets(root).flatMap(engine => [
+                    ...(engine.includeSkills
+                        ? [{ pattern: new vscode.RelativePattern(root, `${engine.workspaceDir}/skills/**/SKILL.md`), reason: 'derived' }]
+                        : []),
+                    { pattern: new vscode.RelativePattern(root, `${engine.workspaceDir}/${engine.rulesFile}`), reason: 'derived' },
+                    ...(engine.includeRules
+                        ? [{ pattern: new vscode.RelativePattern(root, `${engine.workspaceDir}/rules/**/*.md`), reason: 'derived' }]
+                        : []),
+                ]),
+            ];
+            const disposables = [];
+            for (const { pattern, reason } of patterns) {
+                const watcher = vscode.workspace.createFileSystemWatcher(pattern);
+                const onAny = () => this.scheduleAgentideRootUpdate(root, outputChannel, reason);
+                disposables.push(watcher, watcher.onDidChange(onAny), watcher.onDidCreate(onAny), watcher.onDidDelete(onAny));
+            }
+            this.agentideWatchersByRoot.set(root, disposables);
+            this.scheduleAgentideRootUpdate(root, outputChannel, 'source');
+        }
+    }
+    disposeAgentideWatchersForRoot(workspaceRoot) {
+        const disposables = this.agentideWatchersByRoot.get(workspaceRoot);
+        if (!disposables) {
+            return;
+        }
+        for (const d of disposables) {
+            try {
+                d.dispose();
+            }
+            catch { /* ignore */ }
+        }
+        this.agentideWatchersByRoot.delete(workspaceRoot);
+    }
+    disposeAllWatchers() {
+        for (const root of this.agentideWatchersByRoot.keys()) {
+            this.disposeAgentideWatchersForRoot(root);
+        }
+        this.agentideRootUpdateState.clear();
+    }
+    scheduleAgentideRootUpdate(workspaceRoot, outputChannel, reason) {
+        const state = this.agentideRootUpdateState.get(workspaceRoot) ?? {
+            dirty: false,
+            dirtySource: false,
+            dirtyDerived: false,
+            timer: undefined,
+            deferred: undefined,
+        };
+        state.dirty = true;
+        if (reason === 'source') {
+            state.dirtySource = true;
+        }
+        else {
+            state.dirtyDerived = true;
+        }
+        if (!state.deferred) {
+            state.deferred = (0, utils_1.createDeferred)();
+        }
+        if (state.timer) {
+            clearTimeout(state.timer);
+        }
+        state.timer = setTimeout(() => {
+            void this.flushAgentideRootUpdate(workspaceRoot, outputChannel, { allowDuringActiveTurn: false, force: false });
+        }, AGENTIDE_MANIFEST_DEBOUNCE_MS);
+        this.agentideRootUpdateState.set(workspaceRoot, state);
+    }
+    async flushAgentideRootUpdate(workspaceRoot, outputChannel, options) {
+        const allowDuringActiveTurn = options?.allowDuringActiveTurn ?? false;
+        const force = options?.force ?? false;
+        if (!allowDuringActiveTurn && this.activeAgentTurns > 0) {
+            const existing = this.agentideRootUpdateState.get(workspaceRoot);
+            const reason = existing?.dirtySource
+                ? 'source'
+                : existing?.dirtyDerived
+                    ? 'derived'
+                    : 'source';
+            this.scheduleAgentideRootUpdate(workspaceRoot, outputChannel, reason);
+            return;
+        }
+        const state = this.agentideRootUpdateState.get(workspaceRoot);
+        if (!force && (!state || (!state.dirty && !state.deferred))) {
+            return;
+        }
+        const dirtySourceBefore = force || (state?.dirtySource ?? false);
+        const dirtyDerivedBefore = force || (state?.dirtyDerived ?? false);
+        if (state?.timer) {
+            clearTimeout(state.timer);
+            state.timer = undefined;
+        }
+        const deferred = state?.deferred;
+        if (state) {
+            state.dirty = false;
+            state.dirtySource = false;
+            state.dirtyDerived = false;
+            state.deferred = undefined;
+            this.agentideRootUpdateState.set(workspaceRoot, state);
+        }
+        try {
+            let manifest = await this.readAgentideManifest(workspaceRoot);
+            // Import new skills from derived dirs if they changed
+            const ingestResult = dirtyDerivedBefore
+                ? await this.importNewSkillsFromDerivedIntoAgentide(workspaceRoot, outputChannel, manifest?.derivedSkillIngestState)
+                : {
+                    agentideContentChanged: false,
+                    ingestStateChanged: false,
+                    nextIngestState: manifest?.derivedSkillIngestState ?? {},
+                };
+            if (!manifest
+                || force
+                || dirtySourceBefore
+                || ingestResult.agentideContentChanged
+                || ingestResult.ingestStateChanged) {
+                manifest = await this.writeAgentideManifest(workspaceRoot, outputChannel, { derivedSkillIngestState: ingestResult.nextIngestState });
+                // Auto-discover new packs when source files change (e.g., skill creates a new pack)
+                // Only refresh if the number of agents on disk differs from registered count
+                if (dirtySourceBefore) {
+                    try {
+                        const agentsDir = path.join(workspaceRoot, AGENTIDE_DIR_NAME, AGENTIDE_AGENTS_DIR);
+                        if (await (0, utils_1.pathExists)(agentsDir)) {
+                            const entries = await fs_1.promises.readdir(agentsDir, { withFileTypes: true });
+                            const diskAgentCount = entries.filter(e => e.isDirectory() && !e.name.startsWith('.')).length;
+                            const registeredAgents = await this.loadInstalledAgents(workspaceRoot);
+                            if (diskAgentCount > registeredAgents.length) {
+                                await vscode.commands.executeCommand('agentide.pack.refresh');
+                            }
+                        }
+                    }
+                    catch {
+                        // Ignore errors - this is a best-effort optimization
+                    }
+                }
+            }
+            else {
+                this.agentideSignatureByRoot.set(workspaceRoot, manifest.agentideSignature);
+                this.agentideSkillsSignatureByRoot.set(workspaceRoot, manifest.skillsSignature);
+            }
+            if (!manifest) {
+                return;
+            }
+            const lastSynced = this.lastAgentideSyncSignatureByRoot.get(workspaceRoot);
+            const derivedPresent = await this.allDerivedDirsPresent(workspaceRoot);
+            if (dirtySourceBefore || ingestResult.agentideContentChanged || lastSynced !== manifest.agentideSignature || !derivedPresent) {
+                const activePackId = this.getActivePackId(workspaceRoot);
+                const appliedPackId = await this.switchToPack(workspaceRoot, activePackId, outputChannel);
+                if (appliedPackId !== activePackId) {
+                    this.setActivePackId(workspaceRoot, appliedPackId);
+                }
+                const activeAgentId = appliedPackId ?? AGENTIDE_DEFAULT_AGENT_ID;
+                await this.seedAgentDataIfNeeded(workspaceRoot, activeAgentId, outputChannel);
+                this.lastAgentideSyncSignatureByRoot.set(workspaceRoot, manifest.agentideSignature);
+                outputChannel.appendLine(`[AgentIDE] Derived dirs synced for ${workspaceRoot} (sig=${manifest.agentideSignature}, pack=${appliedPackId ?? 'default'})`);
+            }
+            deferred?.resolve();
+        }
+        catch (e) {
+            deferred?.reject(e);
+            outputChannel.appendLine(`[AgentIDE] Warning: failed agentide update for ${workspaceRoot}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Project Preparation
+    // -------------------------------------------------------------------------
+    async ensureAgentideProjectPrepared(workspaceRoot, additionalDirectories, outputChannel) {
+        if (!workspaceRoot) {
+            return;
+        }
+        const workspaceFolderRoots = vscode.workspace.workspaceFolders?.map(f => f.uri.fsPath) ?? [];
+        const additionalWorkspaceRoots = (additionalDirectories ?? []).filter(d => workspaceFolderRoots.includes(d));
+        const roots = Array.from(new Set([workspaceRoot, ...additionalWorkspaceRoots].map(r => r.trim()).filter(Boolean))).filter(r => r !== os.homedir());
+        for (const root of roots) {
+            // Ensure git is initialized and root .gitignore has AgentIDE entries
+            await (0, utils_1.ensureWorkspaceGitAndGitignore)(root, outputChannel);
+            const agentideDir = this.getAgentideProjectDir(root);
+            await fs_1.promises.mkdir(agentideDir, { recursive: true });
+            await this.ensureAgentideGitignore(root, outputChannel);
+            await this.ensureAgentideBundledPromptsCopiedToProject(root, outputChannel);
+            const otherRoots = roots.filter(r => r !== root);
+            await this.ensureAgentideContextTemplate(root, otherRoots, outputChannel);
+            await this.ensureGhostTextPrompt(root, outputChannel);
+            await this.ensureTerminalAssistPrompt(root, outputChannel);
+            // Best-effort remote skills sync (optional, startup path)
+            await this.syncRemoteSkillsIfEnabled(root, outputChannel, { force: false });
+        }
+        for (const root of roots) {
+            await this.flushAgentideRootUpdate(root, outputChannel, { force: false, allowDuringActiveTurn: true });
+            const derivedPresent = await this.allDerivedDirsPresent(root);
+            let manifest = await this.readAgentideManifest(root);
+            if (!manifest) {
+                manifest = await this.writeAgentideManifest(root, outputChannel);
+            }
+            else {
+                this.agentideSignatureByRoot.set(root, manifest.agentideSignature);
+                this.agentideSkillsSignatureByRoot.set(root, manifest.skillsSignature);
+            }
+            const lastSig = this.lastAgentideSyncSignatureByRoot.get(root);
+            if (lastSig === manifest.agentideSignature && derivedPresent) {
+                outputChannel.appendLine(`[AgentIDE] .agentide/ unchanged for ${root}, skipping sync`);
+                continue;
+            }
+            // Use pack-aware sync: switchToPack respects active pack ID
+            // Import derived skills first in case agent created them while extension was stopped
+            const activePackId = this.getActivePackId(root);
+            const appliedPackId = await this.switchToPack(root, activePackId, outputChannel, { importDerivedSkills: true });
+            if (appliedPackId !== activePackId) {
+                this.setActivePackId(root, appliedPackId);
+            }
+            this.lastAgentideSyncSignatureByRoot.set(root, manifest.agentideSignature);
+            outputChannel.appendLine(`[AgentIDE] Sync complete for ${root} (sig: ${manifest.agentideSignature}, pack: ${appliedPackId ?? 'default'})`);
+        }
+    }
+    /**
+     * Sync remote skills into `.agentide/agents/default/skills` for the given workspace root.
+     *
+     * - When `force=false`, this respects `agentide.skills.remote.syncOnStartup`.
+     * - When `force=true`, it runs as long as remote skills are enabled and a registryUrl is configured.
+     */
+    async syncRemoteSkillsIfEnabled(workspaceRoot, outputChannel, opts) {
+        const cfg = vscode.workspace.getConfiguration('agentide.skills.remote');
+        const enabled = cfg.get('enabled', false);
+        if (!enabled) {
+            return;
+        }
+        const syncOnStartup = cfg.get('syncOnStartup', true);
+        if (!opts.force && !syncOnStartup) {
+            return;
+        }
+        const registryUrl = cfg.get('registryUrl', '').trim();
+        if (!registryUrl) {
+            outputChannel.appendLine('[AgentIDE] Remote skills: enabled but agentide.skills.remote.registryUrl is empty');
+            return;
+        }
+        const timeoutMs = cfg.get('timeoutMs', 8000);
+        const allowOverwriteLocal = cfg.get('allowOverwriteLocal', false);
+        try {
+            const agentideSkillsDir = this.getAgentSkillsDir(workspaceRoot, AGENTIDE_DEFAULT_AGENT_ID);
+            const result = await (0, remoteSkills_1.syncRemoteSkillsToAgentideSkillsDir)(agentideSkillsDir, { registryUrl, timeoutMs, allowOverwriteLocal }, line => outputChannel.appendLine(line));
+            if (result.updated > 0) {
+                // Mark source dirty so the manifest/signatures are refreshed and derived dirs re-synced.
+                this.scheduleAgentideRootUpdate(workspaceRoot, outputChannel, 'source');
+            }
+        }
+        catch (e) {
+            outputChannel.appendLine(`[AgentIDE] Remote skills: unexpected error: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    async ensureAgentideBundledPromptsCopiedToProject(workspaceRoot, outputChannel) {
+        const bundledDir = this.getBundledBasePromptsDir();
+        if (!bundledDir) {
+            return;
+        }
+        // All agents live in .agentide/agents/<agentId>/
+        const defaultAgentRoot = this.getAgentRoot(workspaceRoot, AGENTIDE_DEFAULT_AGENT_ID);
+        const agentideAgentsFile = this.getAgentAgentsFile(workspaceRoot, AGENTIDE_DEFAULT_AGENT_ID);
+        const agentideRulesDir = this.getAgentRulesDir(workspaceRoot, AGENTIDE_DEFAULT_AGENT_ID);
+        const agentideSkillsDir = this.getAgentSkillsDir(workspaceRoot, AGENTIDE_DEFAULT_AGENT_ID);
+        await fs_1.promises.mkdir(defaultAgentRoot, { recursive: true });
+        await fs_1.promises.mkdir(agentideRulesDir, { recursive: true });
+        await fs_1.promises.mkdir(agentideSkillsDir, { recursive: true });
+        const bundledAgentsFile = path.join(bundledDir, 'rules', 'AGENTS.md');
+        if (!(await (0, utils_1.pathExists)(agentideAgentsFile)) && (await (0, utils_1.pathExists)(bundledAgentsFile))) {
+            try {
+                const bundledAgentsContent = await fs_1.promises.readFile(bundledAgentsFile, 'utf8');
+                await fs_1.promises.writeFile(agentideAgentsFile, (0, branding_1.applyBrandingTokens)(bundledAgentsContent));
+                outputChannel.appendLine(`[AgentIDE] Bootstrapped project rules: ${agentideAgentsFile}`);
+            }
+            catch (e) {
+                outputChannel.appendLine(`[AgentIDE] Warning: failed to bootstrap project rules: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+        const bundledSkillsDir = path.join(bundledDir, 'skills');
+        if (await (0, utils_1.pathExists)(bundledSkillsDir)) {
+            try {
+                const entries = await fs_1.promises.readdir(bundledSkillsDir, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (!entry.isDirectory()) {
+                        continue;
+                    }
+                    const srcSkill = path.join(bundledSkillsDir, entry.name);
+                    const dstSkill = path.join(agentideSkillsDir, entry.name);
+                    if (await (0, utils_1.pathExists)(dstSkill)) {
+                        continue;
+                    }
+                    // Apply branding tokens to markdown files in bundled skills
+                    await (0, utils_1.copyDirRecursiveWithTransform)(srcSkill, dstSkill, branding_1.applyBrandingTokens);
+                    outputChannel.appendLine(`[AgentIDE] Bootstrapped project skill: ${entry.name}`);
+                }
+            }
+            catch (e) {
+                outputChannel.appendLine(`[AgentIDE] Warning: failed to bootstrap project skills: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+        // Sync MCP config to default agent's mcp/.mcp.json
+        const agentideMcpDir = path.join(defaultAgentRoot, paths_1.AGENT_CONSTANTS.MCP_DIR);
+        const mcpConfigPath = path.join(agentideMcpDir, '.mcp.json');
+        if (!(await (0, utils_1.pathExists)(mcpConfigPath))) {
+            try {
+                const mcpConfig = await (0, mcp_1.getDefaultMcpConfig)(bundledDir);
+                if (mcpConfig) {
+                    await fs_1.promises.mkdir(agentideMcpDir, { recursive: true });
+                    await fs_1.promises.writeFile(mcpConfigPath, mcpConfig);
+                    outputChannel.appendLine(`[AgentIDE] Bootstrapped MCP config: ${mcpConfigPath}`);
+                }
+            }
+            catch (e) {
+                outputChannel.appendLine(`[AgentIDE] Warning: failed to bootstrap MCP config: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+        // Ensure default agent has an agent.yaml
+        await this.ensureDefaultAgentYaml(workspaceRoot, outputChannel);
+    }
+    /**
+     * Ensure default agent has an agent.yaml file.
+     * All agents have the same structure under .agentide/agents/<agentId>/
+     */
+    async ensureDefaultAgentYaml(workspaceRoot, outputChannel) {
+        const defaultAgentRoot = this.getAgentRoot(workspaceRoot, AGENTIDE_DEFAULT_AGENT_ID);
+        const agentYamlPath = path.join(defaultAgentRoot, AGENTIDE_AGENT_YAML);
+        if (await (0, utils_1.pathExists)(agentYamlPath)) {
+            return; // Already exists
+        }
+        await fs_1.promises.mkdir(defaultAgentRoot, { recursive: true });
+        const defaultAgentYaml = (0, paths_1.generateDefaultAgentYaml)({
+            includeModelHintComment: true,
+        });
+        try {
+            await fs_1.promises.writeFile(agentYamlPath, defaultAgentYaml, 'utf8');
+            outputChannel.appendLine(`[AgentIDE] Bootstrapped default agent configuration: ${agentYamlPath}`);
+        }
+        catch (e) {
+            outputChannel.appendLine(`[AgentIDE] Warning: failed to create default agent.yaml: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    async ensureAgentideGitignore(workspaceRoot, outputChannel) {
+        const agentideDir = this.getAgentideProjectDir(workspaceRoot);
+        const gitignorePath = path.join(agentideDir, '.gitignore');
+        const managedBlockLines = [
+            '# AgentHippo (managed)',
+            '# Keep terminal logs and large per-session terminal attachments out of source control.',
+            'terminals/',
+            'agents/default',
+            'sessions',
+            'paths.md',
+            'sessions/**/terminal.md',
+            'sessions/**/terminal.md.1',
+        ];
+        let existing = '';
+        try {
+            existing = await fs_1.promises.readFile(gitignorePath, 'utf8');
+        }
+        catch (e) {
+            if ((0, utils_1.getErrorCode)(e) !== 'ENOENT') {
+                outputChannel.appendLine(`[AgentIDE] Warning: failed to read .gitignore: ${e instanceof Error ? e.message : String(e)}`);
+                return;
+            }
+        }
+        const hasAll = managedBlockLines.every(line => existing.includes(line));
+        if (hasAll) {
+            return;
+        }
+        const next = [
+            existing.trimEnd(),
+            '',
+            managedBlockLines.join('\n'),
+            '',
+        ].join('\n').replace(/^\n+/, '');
+        try {
+            const changed = await (0, utils_1.writeFileIfChanged)(gitignorePath, next);
+            if (changed) {
+                outputChannel.appendLine(`[AgentIDE] Updated ${gitignorePath} to ignore terminal logs`);
+            }
+        }
+        catch (e) {
+            outputChannel.appendLine(`[AgentIDE] Warning: failed to write .gitignore: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    async ensureAgentideContextTemplate(workspaceRoot, additionalDirectories, outputChannel) {
+        const agentideDir = this.getAgentideProjectDir(workspaceRoot);
+        if (!(await (0, utils_1.pathExists)(agentideDir))) {
+            return;
+        }
+        const activeAgentId = this.getActiveAgentId(workspaceRoot);
+        const contextFilePath = this.getAgentContextFile(workspaceRoot, activeAgentId);
+        if (await (0, utils_1.pathExists)(contextFilePath)) {
+            return;
+        }
+        const bundledDir = this.getBundledBasePromptsDir();
+        const bundledTemplatePath = bundledDir ? path.join(bundledDir, 'templates', 'context.md') : undefined;
+        if (!bundledTemplatePath || !(await (0, utils_1.pathExists)(bundledTemplatePath))) {
+            outputChannel.appendLine('[AgentIDE] Warning: bundled context.md template not found');
+            return;
+        }
+        try {
+            let content = await fs_1.promises.readFile(bundledTemplatePath, 'utf8');
+            content = content.replace(/\{\{workspaceRoot\}\}/g, workspaceRoot);
+            const stableDirs = additionalDirectories.slice().filter(Boolean).sort();
+            const dirBlockRegex = /\{\{#additionalDirectories\}\}([\s\S]*?)\{\{\/additionalDirectories\}\}/;
+            const match = content.match(dirBlockRegex);
+            if (match) {
+                const template = match[1];
+                const expanded = stableDirs.length > 0
+                    ? stableDirs.map(dir => template.replace(/\{\{\.\}\}/g, dir)).join('')
+                    : '';
+                content = content.replace(dirBlockRegex, expanded);
+            }
+            await fs_1.promises.mkdir(agentideDir, { recursive: true });
+            await fs_1.promises.writeFile(contextFilePath, content, 'utf8');
+            outputChannel.appendLine(`[AgentIDE] Created context template: ${contextFilePath}`);
+        }
+        catch (e) {
+            outputChannel.appendLine(`[AgentIDE] Warning: failed to copy context template: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    /**
+     * Ensure the active agent has a GHOST_TEXT.md (inline completions prompt).
+     * Only copies from bundled templates if the file doesn't already exist.
+     */
+    async ensureGhostTextPrompt(workspaceRoot, outputChannel) {
+        await this.ensureBundledPromptFile(workspaceRoot, paths_1.AGENT_CONSTANTS.GHOST_TEXT_FILE, outputChannel);
+    }
+    /**
+     * Ensure the active agent has a TERMINAL_ASSIST.md (terminal command assist prompt).
+     * Only copies from bundled templates if the file doesn't already exist.
+     */
+    async ensureTerminalAssistPrompt(workspaceRoot, outputChannel) {
+        await this.ensureBundledPromptFile(workspaceRoot, paths_1.AGENT_CONSTANTS.TERMINAL_ASSIST_FILE, outputChannel);
+    }
+    /**
+     * Ensure a bundled prompt file exists in the active agent's directory.
+     * Copies from base-prompts/ if the file doesn't already exist.
+     *
+     * IMPORTANT: Uses getActiveAgentId() to respect the active pack.
+     * See PLAN/ARCHITECTURE.md "Path Resolution Rules" for why this matters.
+     */
+    async ensureBundledPromptFile(workspaceRoot, fileName, outputChannel) {
+        const agentideDir = this.getAgentideProjectDir(workspaceRoot);
+        if (!(await (0, utils_1.pathExists)(agentideDir))) {
+            return;
+        }
+        // Use active agent ID - never hardcode 'default' for pack-specific paths
+        const activeAgentId = this.getActiveAgentId(workspaceRoot);
+        const agentDir = path.join(agentideDir, 'agents', activeAgentId);
+        const targetPath = path.join(agentDir, fileName);
+        if (await (0, utils_1.pathExists)(targetPath)) {
+            return; // Already exists - don't overwrite user edits
+        }
+        const bundledDir = this.getBundledBasePromptsDir();
+        const bundledPath = bundledDir ? path.join(bundledDir, fileName) : undefined;
+        if (!bundledPath || !(await (0, utils_1.pathExists)(bundledPath))) {
+            return;
+        }
+        try {
+            await fs_1.promises.mkdir(agentDir, { recursive: true });
+            const content = await fs_1.promises.readFile(bundledPath, 'utf8');
+            await fs_1.promises.writeFile(targetPath, content, 'utf8');
+            outputChannel.appendLine(`[AgentIDE] Created ${fileName}: ${targetPath}`);
+        }
+        catch (e) {
+            outputChannel.appendLine(`[AgentIDE] Warning: failed to copy ${fileName}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Derived Directory Sync
+    // -------------------------------------------------------------------------
+    async importNewSkillsFromDerivedIntoAgentide(workspaceRoot, outputChannel, existingIngestState) {
+        // Ingest skills to the active agent's skills dir
+        const activeAgentId = this.getActiveAgentId(workspaceRoot);
+        const agentideSkillsDir = this.getAgentSkillsDir(workspaceRoot, activeAgentId);
+        const derivedSkillDirs = getDerivedEngineSyncTargets(workspaceRoot)
+            .filter(engine => engine.includeSkills)
+            .map(engine => path.join(workspaceRoot, engine.workspaceDir, 'skills'));
+        await fs_1.promises.mkdir(agentideSkillsDir, { recursive: true });
+        const ingestState = {
+            ...(existingIngestState ?? {}),
+        };
+        let agentideContentChanged = false;
+        let ingestStateChanged = false;
+        for (const derivedRoot of derivedSkillDirs) {
+            try {
+                const entries = await fs_1.promises.readdir(derivedRoot, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (!entry.isDirectory()) {
+                        continue;
+                    }
+                    if (entry.name.startsWith('.')) {
+                        continue;
+                    }
+                    const srcSkillDir = path.join(derivedRoot, entry.name);
+                    const srcSkillFile = path.join(srcSkillDir, 'SKILL.md');
+                    if (!(await (0, utils_1.pathExists)(srcSkillFile))) {
+                        continue;
+                    }
+                    const dstSkillDir = path.join(agentideSkillsDir, entry.name);
+                    const dstSkillFile = path.join(dstSkillDir, 'SKILL.md');
+                    const { sha256: srcSha } = await (0, utils_1.readFileSha256)(srcSkillFile);
+                    if (!(await (0, utils_1.pathExists)(dstSkillDir))) {
+                        await (0, utils_1.copyDirRecursive)(srcSkillDir, dstSkillDir);
+                        agentideContentChanged = true;
+                        ingestState[entry.name] = {
+                            lastIngestedSkillMdSha256: srcSha,
+                            lastIngestedAt: new Date().toISOString(),
+                        };
+                        ingestStateChanged = true;
+                        outputChannel.appendLine(`[AgentIDE] Imported new skill from derived dir: ${entry.name} → ${activeAgentId}`);
+                        continue;
+                    }
+                    if (!(await (0, utils_1.pathExists)(dstSkillFile))) {
+                        continue;
+                    }
+                    const { sha256: dstSha } = await (0, utils_1.readFileSha256)(dstSkillFile);
+                    const state = ingestState[entry.name];
+                    if (!state && srcSha === dstSha) {
+                        ingestState[entry.name] = {
+                            lastIngestedSkillMdSha256: dstSha,
+                            lastIngestedAt: new Date().toISOString(),
+                        };
+                        ingestStateChanged = true;
+                        continue;
+                    }
+                    if (!state) {
+                        continue;
+                    }
+                    if (dstSha !== state.lastIngestedSkillMdSha256) {
+                        outputChannel.appendLine(`[AgentIDE] Skipped ingest for skill '${entry.name}' (conflict: .agentide diverged from last ingested state)`);
+                        continue;
+                    }
+                    if (srcSha !== dstSha) {
+                        await fs_1.promises.copyFile(srcSkillFile, dstSkillFile);
+                        agentideContentChanged = true;
+                        ingestState[entry.name] = {
+                            lastIngestedSkillMdSha256: srcSha,
+                            lastIngestedAt: new Date().toISOString(),
+                        };
+                        ingestStateChanged = true;
+                        outputChannel.appendLine(`[AgentIDE] Ingested updated SKILL.md from derived dir: ${entry.name}`);
+                    }
+                }
+            }
+            catch {
+                // ignore
+            }
+        }
+        return { agentideContentChanged, ingestStateChanged, nextIngestState: ingestState };
+    }
+    async readAgentideContextMd(workspaceRoot) {
+        const activeAgentId = this.getActiveAgentId(workspaceRoot);
+        const contextFilePath = this.getAgentContextFile(workspaceRoot, activeAgentId);
+        try {
+            return await fs_1.promises.readFile(contextFilePath, 'utf8');
+        }
+        catch (e) {
+            if ((0, utils_1.getErrorCode)(e) === 'ENOENT') {
+                return undefined;
+            }
+            throw e;
+        }
+    }
+    async writeDerivedDirReadme(targetDir, providerId, outputChannel, sourceOfTruthLines) {
+        try {
+            const readmePath = path.join(targetDir, AGENTIDE_DERIVED_DIR_README);
+            const providerName = providerId.charAt(0).toUpperCase() + providerId.slice(1);
+            const sourceLines = (sourceOfTruthLines && sourceOfTruthLines.length > 0)
+                ? sourceOfTruthLines
+                : [
+                    '- `.agentide/agents/<agentId>/AGENTS.md` (project rules)',
+                    '- `.agentide/agents/<agentId>/rules/*.md` (additional rule fragments)',
+                    '- `.agentide/agents/<agentId>/skills/*/SKILL.md` (project skills)',
+                ];
+            const contents = [
+                `# Managed by ${branding_1.AGENTIDE_BRAND_NAME}`,
+                '',
+                `This directory is managed by the ${branding_1.AGENTIDE_BRAND_NAME} extension.`,
+                '',
+                '## How It Works',
+                '',
+                '- **Skills** created here ARE synced back to `.agentide/agents/<id>/skills/`',
+                '- **Rules files** (`CLAUDE.md`, `AGENTS.md`) are generated from the source and **not synced back**',
+                '  - Edit rules in `.agentide/agents/<id>/AGENTS.md` instead',
+                '- The source-of-truth is in:',
+                ...sourceLines,
+                '',
+                '## Tips',
+                '',
+                '- Create/edit skills here or in `.agentide/` - both will stay in sync',
+                '- To change project rules, edit `.agentide/agents/<id>/AGENTS.md` (not the rules file here)',
+                '- This folder exists for ' + providerName + ' auto-discovery compatibility',
+                '',
+            ].join('\n');
+            await (0, utils_1.writeFileIfChanged)(readmePath, contents);
+        }
+        catch (e) {
+            outputChannel.appendLine(`[AgentIDE] Warning: failed to write ${providerId} derived README: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    async cleanDerivedRulesDir(rulesDir) {
+        try {
+            const existing = await fs_1.promises.readdir(rulesDir, { withFileTypes: true });
+            const rmOps = existing
+                .filter(e => e.isFile() && e.name.toLowerCase().endsWith('.md'))
+                .map(e => fs_1.promises.rm(path.join(rulesDir, e.name), { force: true }));
+            await Promise.all(rmOps);
+        }
+        catch {
+            // ignore
+        }
+    }
+    async syncAgentideProjectToDerivedDirs(workspaceRoots, outputChannel, agentIdOverride) {
+        const roots = Array.from(new Set(workspaceRoots.map(r => r.trim()).filter(Boolean)));
+        for (const root of roots) {
+            if (!root || root === os.homedir()) {
+                continue;
+            }
+            const agentideDir = this.getAgentideProjectDir(root);
+            // Use override if provided, otherwise read from manifest
+            const activeAgentId = agentIdOverride ?? this.getActiveAgentId(root);
+            const agentideSkillsDir = this.getAgentSkillsDir(root, activeAgentId);
+            const agentideRulesDir = this.getAgentRulesDir(root, activeAgentId);
+            const agentideAgentsFile = this.getAgentAgentsFile(root, activeAgentId);
+            if (!(await (0, utils_1.pathExists)(agentideDir))) {
+                continue;
+            }
+            // Build derived directory paths from built-in and custom engine manifests.
+            const derivedDirs = getDerivedEngineSyncTargets(root).map(engine => ({
+                id: engine.id,
+                displayName: engine.displayName,
+                workspaceDir: engine.workspaceDir,
+                rulesFile: engine.rulesFile,
+                managedPaths: engine.managedPaths,
+                includeSkills: engine.includeSkills,
+                includeRules: engine.includeRules,
+                fullPath: path.join(root, engine.workspaceDir),
+                rulesPath: path.join(root, engine.workspaceDir, 'rules'),
+                skillsPath: path.join(root, engine.workspaceDir, 'skills'),
+            }));
+            const sourceOfTruthLines = [
+                `- \`.agentide/agents/${activeAgentId}/AGENTS.md\` (project rules)`,
+                `- \`.agentide/agents/${activeAgentId}/rules/*.md\` (additional rule fragments)`,
+                `- \`.agentide/agents/${activeAgentId}/skills/*/SKILL.md\` (project skills)`,
+            ];
+            // Phase 1: Create base directories
+            await Promise.all(derivedDirs.map(d => fs_1.promises.mkdir(d.fullPath, { recursive: true })));
+            // Phase 2: Write READMEs and create rules dirs
+            await Promise.all(derivedDirs.flatMap(d => [
+                this.writeDerivedDirReadme(d.fullPath, d.id, outputChannel, sourceOfTruthLines),
+                fs_1.promises.mkdir(d.rulesPath, { recursive: true }),
+            ]));
+            // Phase 3: Write combined rules files
+            const writeAgentsOps = [];
+            const agentsFileExists = await (0, utils_1.pathExists)(agentideAgentsFile);
+            if (agentsFileExists) {
+                const [agentsContent, contextContent] = await Promise.all([
+                    fs_1.promises.readFile(agentideAgentsFile, 'utf8'),
+                    this.readAgentideContextMd(root),
+                ]);
+                let combined = (0, branding_1.applyBrandingTokens)(agentsContent).trimEnd();
+                if (contextContent) {
+                    combined += '\n\n---\n\n' + contextContent.trimEnd() + '\n';
+                }
+                else {
+                    combined += '\n';
+                }
+                // Write rules file to each derived provider directory
+                for (const d of derivedDirs) {
+                    writeAgentsOps.push((0, utils_1.writeFileIfChanged)(path.join(d.fullPath, d.rulesFile), combined));
+                }
+            }
+            await Promise.all([
+                ...writeAgentsOps,
+                ...derivedDirs.filter(d => d.includeRules).map(d => this.cleanDerivedRulesDir(d.rulesPath)),
+            ]);
+            // Phase 4: Mirror .agentide/rules/*.md to each derived provider
+            if (await (0, utils_1.pathExists)(agentideRulesDir)) {
+                const entries = await fs_1.promises.readdir(agentideRulesDir, { withFileTypes: true });
+                const ruleOps = entries
+                    .filter(e => e.isFile() && e.name.toLowerCase().endsWith('.md'))
+                    .flatMap(entry => {
+                    const src = path.join(agentideRulesDir, entry.name);
+                    return derivedDirs.filter(d => d.includeRules).map(d => (0, utils_1.symlinkOrCopyFile)(src, path.join(d.rulesPath, entry.name), outputChannel, `Rule ${entry.name} -> ${d.workspaceDir}`, { force: true }));
+                });
+                await Promise.all(ruleOps);
+            }
+            // Phase 5: Ensure skills directories exist
+            await Promise.all(derivedDirs.filter(d => d.includeSkills).map(d => (0, utils_1.ensureRealDirectory)(d.skillsPath)));
+            // Phase 6: Sync skills via file-level links
+            if (await (0, utils_1.pathExists)(agentideSkillsDir)) {
+                const entries = await fs_1.promises.readdir(agentideSkillsDir, { withFileTypes: true });
+                const expectedSkills = [];
+                for (const entry of entries) {
+                    if (!entry.isDirectory() || entry.name.startsWith('.')) {
+                        continue;
+                    }
+                    const srcSkillMd = path.join(agentideSkillsDir, entry.name, 'SKILL.md');
+                    if (!(await (0, utils_1.pathExists)(srcSkillMd))) {
+                        continue;
+                    }
+                    expectedSkills.push(entry.name);
+                }
+                const expectedSet = new Set(expectedSkills);
+                const syncOneDerivedSkillsDir = async (dstSkillsRoot, label) => {
+                    try {
+                        const existing = await fs_1.promises.readdir(dstSkillsRoot, { withFileTypes: true });
+                        const rmOps = [];
+                        for (const e of existing) {
+                            if (!e.isDirectory() && !e.isSymbolicLink()) {
+                                continue;
+                            }
+                            if (e.name.startsWith('.')) {
+                                continue;
+                            }
+                            if (!expectedSet.has(e.name)) {
+                                rmOps.push(fs_1.promises.rm(path.join(dstSkillsRoot, e.name), { recursive: true, force: true }));
+                            }
+                        }
+                        await Promise.all(rmOps);
+                    }
+                    catch {
+                        // ignore
+                    }
+                    for (const skillName of expectedSkills) {
+                        const srcSkill = path.join(agentideSkillsDir, skillName);
+                        const dstSkill = path.join(dstSkillsRoot, skillName);
+                        await (0, utils_1.syncDirByFileLinks)(srcSkill, dstSkill, outputChannel, `${label}/skills/${skillName}`);
+                    }
+                };
+                await Promise.all(derivedDirs.filter(d => d.includeSkills).map(d => syncOneDerivedSkillsDir(d.skillsPath, d.workspaceDir)));
+            }
+        }
+    }
+    // -------------------------------------------------------------------------
+    // AgentPack Support
+    // -------------------------------------------------------------------------
+    /**
+     * Sync derived directories for an agent pack.
+     * Creates .codex/ and .claude/ within the pack folder with synced content.
+     */
+    async syncPackDerivedDirs(packRoot, outputChannel) {
+        if (!packRoot || !(await (0, utils_1.pathExists)(packRoot))) {
+            return;
+        }
+        const agentsFile = path.join(packRoot, 'AGENTS.md');
+        const rulesDir = path.join(packRoot, 'rules');
+        const skillsDir = path.join(packRoot, 'skills');
+        // Build derived directory paths from built-in and custom engine manifests.
+        const derivedDirs = getDerivedEngineSyncTargets(packRoot).map(engine => ({
+            id: engine.id,
+            workspaceDir: engine.workspaceDir,
+            rulesFile: engine.rulesFile,
+            includeSkills: engine.includeSkills,
+            includeRules: engine.includeRules,
+            fullPath: path.join(packRoot, engine.workspaceDir),
+            rulesPath: path.join(packRoot, engine.workspaceDir, 'rules'),
+            skillsPath: path.join(packRoot, engine.workspaceDir, 'skills'),
+        }));
+        // Phase 1: Create base directories
+        await Promise.all(derivedDirs.map(d => fs_1.promises.mkdir(d.fullPath, { recursive: true })));
+        // Phase 2: Create rules dirs
+        await Promise.all(derivedDirs.map(d => fs_1.promises.mkdir(d.rulesPath, { recursive: true })));
+        // Phase 3: Write rules files
+        if (await (0, utils_1.pathExists)(agentsFile)) {
+            const agentsContent = (0, branding_1.applyBrandingTokens)(await fs_1.promises.readFile(agentsFile, 'utf8'));
+            const contextFile = path.join(packRoot, 'context.md');
+            let combined = agentsContent.trimEnd();
+            if (await (0, utils_1.pathExists)(contextFile)) {
+                const contextContent = await fs_1.promises.readFile(contextFile, 'utf8');
+                combined += '\n\n---\n\n' + contextContent.trimEnd() + '\n';
+            }
+            else {
+                combined += '\n';
+            }
+            for (const d of derivedDirs) {
+                await (0, utils_1.writeFileIfChanged)(path.join(d.fullPath, d.rulesFile), combined);
+            }
+        }
+        // Phase 4: Symlink rules
+        if (await (0, utils_1.pathExists)(rulesDir)) {
+            const entries = await fs_1.promises.readdir(rulesDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isFile() || !entry.name.toLowerCase().endsWith('.md')) {
+                    continue;
+                }
+                const src = path.join(rulesDir, entry.name);
+                for (const d of derivedDirs.filter(d => d.includeRules)) {
+                    await (0, utils_1.symlinkOrCopyFile)(src, path.join(d.rulesPath, entry.name), outputChannel, `Pack rule ${entry.name}`, { force: true });
+                }
+            }
+        }
+        // Phase 5: Ensure skills directories exist
+        await Promise.all(derivedDirs.filter(d => d.includeSkills).map(d => (0, utils_1.ensureRealDirectory)(d.skillsPath)));
+        // Phase 6: Sync skills
+        if (await (0, utils_1.pathExists)(skillsDir)) {
+            const entries = await fs_1.promises.readdir(skillsDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory() || entry.name.startsWith('.')) {
+                    continue;
+                }
+                const srcSkill = path.join(skillsDir, entry.name);
+                for (const d of derivedDirs.filter(d => d.includeSkills)) {
+                    await (0, utils_1.syncDirByFileLinks)(srcSkill, path.join(d.skillsPath, entry.name), outputChannel, `Pack skill ${entry.name}`);
+                }
+            }
+        }
+        outputChannel.appendLine(`[AgentPack] Synced derived dirs for pack at ${packRoot}`);
+    }
+    /**
+     * Switch the workspace's .claude/ and .codex/ to use content from the specified pack.
+     * If packId is undefined or 'default', syncs from .agentide/ (default agent).
+     * Otherwise, syncs from .agentide/agents/{packId}/.
+     *
+     * This replaces the content of workspace-root derived directories with the pack's content.
+     *
+     * @param importDerivedSkills If true, import any new skills from derived dirs to the
+     *   current pack's source before switching. This preserves agent-created skills.
+     */
+    async switchToPack(workspaceRoot, packId, outputChannel, options) {
+        // Import any new skills from derived dirs before switching
+        if (options?.importDerivedSkills) {
+            const manifest = await this.readAgentideManifest(workspaceRoot);
+            await this.importNewSkillsFromDerivedIntoAgentide(workspaceRoot, outputChannel, manifest?.derivedSkillIngestState);
+        }
+        if (!packId || packId === 'default') {
+            // Default agent: sync from .agentide/agents/default/
+            outputChannel.appendLine(`[AgentPack] Switching to default workspace agent`);
+            await this.syncAgentideProjectToDerivedDirs([workspaceRoot], outputChannel, 'default');
+            await this.seedAgentDataIfNeeded(workspaceRoot, AGENTIDE_DEFAULT_AGENT_ID, outputChannel);
+            await this.writeAgentideManifest(workspaceRoot, outputChannel, { packIdOverride: 'default' });
+            return undefined;
+        }
+        // Pack mode: sync from .agentide/agents/{packId}/
+        const packRoot = path.join(workspaceRoot, AGENTIDE_DIR_NAME, 'agents', packId);
+        if (!(await (0, utils_1.pathExists)(packRoot))) {
+            outputChannel.appendLine(`[AgentPack] Warning: Pack not found at ${packRoot}, falling back to default`);
+            await this.syncAgentideProjectToDerivedDirs([workspaceRoot], outputChannel, 'default');
+            await this.writeAgentideManifest(workspaceRoot, outputChannel, { packIdOverride: 'default' });
+            return undefined;
+        }
+        outputChannel.appendLine(`[AgentPack] Switching to pack: ${packId}`);
+        const agentsFile = path.join(packRoot, 'AGENTS.md');
+        const rulesDir = path.join(packRoot, 'rules');
+        const skillsDir = path.join(packRoot, 'skills');
+        // Build derived directory paths at WORKSPACE ROOT (not pack root)
+        const derivedDirs = getDerivedEngineSyncTargets(workspaceRoot).map(engine => ({
+            id: engine.id,
+            workspaceDir: engine.workspaceDir,
+            rulesFile: engine.rulesFile,
+            includeSkills: engine.includeSkills,
+            includeRules: engine.includeRules,
+            fullPath: path.join(workspaceRoot, engine.workspaceDir),
+            rulesPath: path.join(workspaceRoot, engine.workspaceDir, 'rules'),
+            skillsPath: path.join(workspaceRoot, engine.workspaceDir, 'skills'),
+        }));
+        const sourceOfTruthLines = [
+            `- \`.agentide/agents/${packId}/AGENTS.md\` (pack rules)`,
+            `- \`.agentide/agents/${packId}/rules/*.md\` (additional rule fragments)`,
+            `- \`.agentide/agents/${packId}/skills/*/SKILL.md\` (pack skills)`,
+        ];
+        // Phase 1: Create base directories
+        await Promise.all(derivedDirs.map(d => fs_1.promises.mkdir(d.fullPath, { recursive: true })));
+        // Phase 2: Write READMEs and create rules dirs
+        await Promise.all(derivedDirs.flatMap(d => [
+            this.writeDerivedDirReadme(d.fullPath, d.id, outputChannel, sourceOfTruthLines),
+            fs_1.promises.mkdir(d.rulesPath, { recursive: true }),
+        ]));
+        // Phase 3: Write combined rules files from pack's AGENTS.md
+        if (await (0, utils_1.pathExists)(agentsFile)) {
+            const agentsContent = (0, branding_1.applyBrandingTokens)(await fs_1.promises.readFile(agentsFile, 'utf8'));
+            const contextFile = path.join(packRoot, 'context.md');
+            let combined = agentsContent.trimEnd();
+            if (await (0, utils_1.pathExists)(contextFile)) {
+                const contextContent = await fs_1.promises.readFile(contextFile, 'utf8');
+                combined += '\n\n---\n\n' + contextContent.trimEnd() + '\n';
+            }
+            else {
+                combined += '\n';
+            }
+            for (const d of derivedDirs) {
+                await (0, utils_1.writeFileIfChanged)(path.join(d.fullPath, d.rulesFile), combined);
+            }
+        }
+        // Clean rules dirs before syncing
+        await Promise.all(derivedDirs.filter(d => d.includeRules).map(d => this.cleanDerivedRulesDir(d.rulesPath)));
+        // Phase 4: Symlink rules from pack
+        if (await (0, utils_1.pathExists)(rulesDir)) {
+            const entries = await fs_1.promises.readdir(rulesDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isFile() || !entry.name.toLowerCase().endsWith('.md')) {
+                    continue;
+                }
+                const src = path.join(rulesDir, entry.name);
+                for (const d of derivedDirs.filter(d => d.includeRules)) {
+                    await (0, utils_1.symlinkOrCopyFile)(src, path.join(d.rulesPath, entry.name), outputChannel, `Pack rule ${entry.name}`, { force: true });
+                }
+            }
+        }
+        // Phase 5: Ensure skills directories exist and clean stale skills
+        await Promise.all(derivedDirs.filter(d => d.includeSkills).map(d => (0, utils_1.ensureRealDirectory)(d.skillsPath)));
+        // Phase 6: Sync skills from pack
+        if (await (0, utils_1.pathExists)(skillsDir)) {
+            const entries = await fs_1.promises.readdir(skillsDir, { withFileTypes: true });
+            const expectedSkills = [];
+            for (const entry of entries) {
+                if (!entry.isDirectory() || entry.name.startsWith('.')) {
+                    continue;
+                }
+                const srcSkillMd = path.join(skillsDir, entry.name, 'SKILL.md');
+                if (!(await (0, utils_1.pathExists)(srcSkillMd))) {
+                    continue;
+                }
+                expectedSkills.push(entry.name);
+            }
+            const expectedSet = new Set(expectedSkills);
+            // Remove skills not in pack
+            for (const d of derivedDirs.filter(d => d.includeSkills)) {
+                try {
+                    const existing = await fs_1.promises.readdir(d.skillsPath, { withFileTypes: true });
+                    for (const e of existing) {
+                        if ((e.isDirectory() || e.isSymbolicLink()) && !expectedSet.has(e.name)) {
+                            await fs_1.promises.rm(path.join(d.skillsPath, e.name), { recursive: true, force: true });
+                            outputChannel.appendLine(`[AgentPack] Removed stale skill: ${e.name}`);
+                        }
+                    }
+                }
+                catch {
+                    // Skills dir might not exist yet
+                }
+            }
+            // Sync pack skills
+            for (const skillName of expectedSkills) {
+                const srcSkill = path.join(skillsDir, skillName);
+                for (const d of derivedDirs.filter(d => d.includeSkills)) {
+                    await (0, utils_1.syncDirByFileLinks)(srcSkill, path.join(d.skillsPath, skillName), outputChannel, `Pack skill ${skillName}`);
+                }
+            }
+        }
+        else {
+            // Pack has no skills - clear derived skills dirs
+            for (const d of derivedDirs.filter(d => d.includeSkills)) {
+                try {
+                    const existing = await fs_1.promises.readdir(d.skillsPath, { withFileTypes: true });
+                    for (const e of existing) {
+                        if (e.isDirectory() || e.isSymbolicLink()) {
+                            await fs_1.promises.rm(path.join(d.skillsPath, e.name), { recursive: true, force: true });
+                        }
+                    }
+                }
+                catch {
+                    // Ignore
+                }
+            }
+        }
+        outputChannel.appendLine(`[AgentPack] Switched workspace to pack: ${packId}`);
+        await this.seedAgentDataIfNeeded(workspaceRoot, packId, outputChannel);
+        await this.writeAgentideManifest(workspaceRoot, outputChannel, { packIdOverride: packId });
+        return packId;
+    }
+    /**
+     * Load the agentide manifest for a workspace.
+     */
+    async loadAgentideManifest(workspaceRoot) {
+        const manifestPath = path.join(workspaceRoot, AGENTIDE_DIR_NAME, AGENTIDE_MANIFEST_FILE);
+        try {
+            const content = await fs_1.promises.readFile(manifestPath, 'utf8');
+            return JSON.parse(content);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Installed Agents (separate file: installed-agents.json)
+    // -------------------------------------------------------------------------
+    getInstalledAgentsFilePath(workspaceRoot) {
+        return path.join(workspaceRoot, AGENTIDE_DIR_NAME, AGENTIDE_INSTALLED_AGENTS_FILE);
+    }
+    /**
+     * Load installed agents from the dedicated file.
+     */
+    async loadInstalledAgents(workspaceRoot) {
+        const filePath = this.getInstalledAgentsFilePath(workspaceRoot);
+        try {
+            const content = await fs_1.promises.readFile(filePath, 'utf8');
+            const data = JSON.parse(content);
+            return data.agents ?? [];
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Save installed agents to the dedicated file.
+     */
+    async saveInstalledAgents(workspaceRoot, agents) {
+        const filePath = this.getInstalledAgentsFilePath(workspaceRoot);
+        const data = {
+            version: 1,
+            agents,
+        };
+        await fs_1.promises.mkdir(path.dirname(filePath), { recursive: true });
+        await fs_1.promises.writeFile(filePath, JSON.stringify(data, null, 2));
+    }
+    /**
+     * Update or add an installed agent.
+     */
+    async updateInstalledAgent(workspaceRoot, agent, outputChannel) {
+        const agents = await this.loadInstalledAgents(workspaceRoot);
+        // Remove existing entry if present
+        const filtered = agents.filter(a => a.id !== agent.id);
+        // Add new entry
+        const entry = {
+            id: agent.id,
+            version: agent.version,
+            source: agent.source,
+            installedAt: new Date().toISOString(),
+            featureSetHash: agent.featureSetHash,
+            preferredEngine: agent.preferredEngine,
+            preferredModel: agent.preferredModel,
+            preferredCheapModel: agent.preferredCheapModel,
+            status: 'active',
+        };
+        filtered.push(entry);
+        await this.saveInstalledAgents(workspaceRoot, filtered);
+        (0, utils_1.logInfo)(outputChannel, `[Agent] Registered agent: ${agent.id}`);
+    }
+    /**
+     * Remove an installed agent.
+     */
+    async removeInstalledAgent(workspaceRoot, agentId, outputChannel) {
+        const agents = await this.loadInstalledAgents(workspaceRoot);
+        const filtered = agents.filter(a => a.id !== agentId);
+        if (filtered.length !== agents.length) {
+            await this.saveInstalledAgents(workspaceRoot, filtered);
+            (0, utils_1.logInfo)(outputChannel, `[Agent] Removed agent: ${agentId}`);
+        }
+    }
+}
+exports.SyncService = SyncService;