@phuetz/code-buddy 0.3.0 → 1.0.0-rc.8

package/dist/agent/codebuddy-agent.js

@@ -9,16 +9,21 @@ import { getRepoProfiler } from "./repo-profiler.js";
 import { getToolSelectionStrategy } from "./execution/tool-selection-strategy.js";
 import { PromptBuilder } from "../services/prompt-builder.js";
 import { StreamingHandler } from "./streaming/index.js";
-import { AgentExecutor } from "./execution/agent-executor.js";
+import { AgentExecutor, setDecisionContextProvider, setICMBridgeProvider, setCodeGraphContextProvider, setDocsContextProvider } from "./execution/agent-executor.js";
 import { ToolHandler } from "./tool-handler.js";
 import { BaseAgent } from "./base-agent.js";
 import { createAgentInfrastructureSync } from "./infrastructure/index.js";
 import { getLaneQueue } from "../concurrency/lane-queue.js";
-import { findSkill } from "../skills/index.js";
+import { findSkill, findStarterPack } from "../skills/index.js";
 import { skillMdToUnified } from "../skills/adapters/index.js";
+import { getSkillsHub } from "../skills/hub.js";
 import { MessageQueue } from "./message-queue.js";
 import { CostPredictor } from "../analytics/cost-predictor.js";
 import { BudgetAlertManager } from "../analytics/budget-alerts.js";
+import { initializeMemory, getMemoryManager } from "../memory/persistent-memory.js";
+import { getUserHooksManager } from "../hooks/user-hooks.js";
+import { isFeatureEnabled } from "../config/feature-flags.js";
+import { getActiveRunStore } from "../observability/run-store.js";
 /**
  * Main agent class that orchestrates conversation with CodeBuddy AI and tool execution
  *
@@ -39,6 +44,15 @@ export class CodeBuddyAgent extends BaseAgent {
     codebuddyClient;
     toolHandler;
     promptBuilder;
+    customSystemPromptOverride = null;
+    systemPromptAppend;
+    /**
+     * When true (set only by the interactive entrypoint), a Hermes-style
+     * background self-learning review runs after each completed turn. Off for
+     * cron/headless/sub-agent constructions so they never trigger a review.
+     */
+    backgroundReviewEnabled = false;
+    visionGroundingModel;
     streamingHandler;
     executor;
     toolSelectionStrategy;
@@ -51,6 +65,7 @@ export class CodeBuddyAgent extends BaseAgent {
     costPredictor;
     /** Budget alert monitoring */
     budgetAlertManager = new BudgetAlertManager();
+    _budgetAlertListener;
     /**
      * Create a new CodeBuddyAgent instance
      *
@@ -60,9 +75,12 @@ export class CodeBuddyAgent extends BaseAgent {
      * @param maxToolRounds - Maximum tool execution rounds (default: depends on YOLO mode)
      * @param useRAGToolSelection - Enable RAG-based tool selection (default: true)
      */
-    constructor(apiKey, baseURL, model, maxToolRounds, useRAGToolSelection = true, systemPromptId // New: external prompt ID (default, minimal, secure, etc.)
-    ) {
+    constructor(apiKey, baseURL, model, maxToolRounds, useRAGToolSelection = true, systemPromptId, // New: external prompt ID (default, minimal, secure, etc.)
+    workingDirectory, systemPromptAppend) {
         super();
+        this.systemPromptAppend = systemPromptAppend;
+        this.visionGroundingModel = process.env.CODEBUDDY_VISION_GROUNDING_MODEL || undefined;
+        const initialWorkingDirectory = workingDirectory || process.cwd();
         // Determine model to use
         const manager = getSettingsManager();
         const savedModel = manager.getCurrentModel();
@@ -114,34 +132,70 @@ export class CodeBuddyAgent extends BaseAgent {
         this.modelRouter = this.infrastructure.modelRouter;
         this.marketplace = this.infrastructure.marketplace;
         this.repairCoordinator = this.infrastructure.repairCoordinator;
+        // Initialize Persistent Memory (CLAUDE.md style)
+        initializeMemory().catch(err => {
+            logger.error('Failed to initialize persistent memory', { error: String(err) });
+        });
         // Initialize cost prediction and budget alerts
         this.costPredictor = new CostPredictor(this.costTracker);
         this.budgetAlertManager = new BudgetAlertManager();
-        this.budgetAlertManager.on('alert', (alert) => {
+        this._budgetAlertListener = (alert) => {
             logger.warn(`Budget alert [${alert.type}]: ${alert.message}`);
             this.emit('budget:alert', alert);
-        });
+        };
+        this.budgetAlertManager.on('alert', this._budgetAlertListener);
         // Initialize tool selection
         this.useRAGToolSelection = useRAGToolSelection;
         this.toolSelectionStrategy = getToolSelectionStrategy({ useRAG: useRAGToolSelection });
         // Initialize client
         this.codebuddyClient = new CodeBuddyClient(apiKey, modelToUse, baseURL);
+        // Apply thinkingLevel from settings if configured
+        try {
+            import('../utils/settings-manager.js').then(({ getSettingsManager }) => {
+                const settings = getSettingsManager().loadProjectSettings();
+                if (settings?.thinkingLevel) {
+                    this.codebuddyClient.setDefaultThinkingLevel(settings.thinkingLevel);
+                }
+            }).catch(() => { });
+        }
+        catch { /* settings optional */ }
         // Forward repair events from RepairCoordinator (store refs for cleanup)
-        this.repairListeners = {
+        const repairListeners = {
             start: (data) => this.emit('repair:start', data),
             success: (data) => this.emit('repair:success', data),
             failed: (data) => this.emit('repair:failed', data),
             error: (data) => this.emit('repair:error', data),
         };
-        this.repairCoordinator.on('repair:start', this.repairListeners.start);
-        this.repairCoordinator.on('repair:success', this.repairListeners.success);
-        this.repairCoordinator.on('repair:failed', this.repairListeners.failed);
-        this.repairCoordinator.on('repair:error', this.repairListeners.error);
+        this.repairListeners = repairListeners;
+        this.repairCoordinator.on('repair:start', repairListeners.start);
+        this.repairCoordinator.on('repair:success', repairListeners.success);
+        this.repairCoordinator.on('repair:failed', repairListeners.failed);
+        this.repairCoordinator.on('repair:error', repairListeners.error);
         // Initialize StreamingHandler
+        //
+        // `extractToolCalls` parses streamed content for embedded "commentary
+        // tool calls" — useful for small Ollama models that hallucinate JSON
+        // tool-call shapes inside their text. But for backends with native
+        // structured tool_calls (ChatGPT Codex, Anthropic, Gemini, Grok...),
+        // it triggers false positives when the LLM legitimately mentions tool
+        // names in markdown backticks (e.g. "use `view_file` to read"), which
+        // splits the response into duplicate TUI entries (Phase d.25 fix).
+        //
+        // Heuristic: enable only for local/small models that can't emit
+        // structured tool_calls. Everything else uses the native API path.
+        const lower = modelToUse.toLowerCase();
+        const isLocalOrSmall = lower.startsWith('qwen') ||
+            lower.startsWith('llama') ||
+            lower.startsWith('deepseek') ||
+            lower.startsWith('gemma') ||
+            lower.startsWith('mistral') ||
+            lower.startsWith('ollama/') ||
+            lower.includes(':') /* Ollama tag form like `qwen2.5-coder:7b` */;
         this.streamingHandler = new StreamingHandler({
             model: modelToUse,
             trackTokens: true,
-            sanitizeOutput: true
+            sanitizeOutput: true,
+            extractToolCalls: isLocalOrSmall,
         });
         // Initialize ToolHandler
         this.toolHandler = new ToolHandler({
@@ -150,6 +204,7 @@ export class CodeBuddyAgent extends BaseAgent {
             marketplace: this.marketplace,
             repairCoordinator: this.repairCoordinator
         });
+        this.toolHandler.setWorkingDirectory(workingDirectory);
         // Initialize Executor
         this.executor = new AgentExecutor({
             client: this.codebuddyClient,
@@ -161,32 +216,127 @@ export class CodeBuddyAgent extends BaseAgent {
             laneQueue: getLaneQueue(),
             laneId: 'agent-tools',
             messageQueue: this.messageQueue,
+            // Phase d.22 — query-aware system prompt rebuild. Called by the
+            // executor on toolRounds === 0 so trivial queries on `lite`-profile
+            // models (Ollama qwen, llama, deepseek) get a minimal SP (~9 KB)
+            // instead of the full 73 KB rich prompt that confuses small models
+            // into hallucinating JSON tool calls.
+            rebuildSystemPromptForQuery: async (msg) => {
+                try {
+                    if (this.customSystemPromptOverride) {
+                        return this.customSystemPromptOverride;
+                    }
+                    if (!this.promptBuilder)
+                        return null;
+                    const customInstructions = loadCustomInstructions();
+                    const prompt = await this.promptBuilder.buildForQuery(msg, systemPromptId, this.getCurrentModel(), customInstructions);
+                    return this.applyRuntimeSystemPromptAppend(prompt);
+                }
+                catch (err) {
+                    logger.warn('rebuildSystemPromptForQuery failed', {
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                    return null;
+                }
+            },
         }, {
             maxToolRounds: this.maxToolRounds,
             isGrokModel: this.isGrokModel.bind(this),
             recordSessionCost: this.recordSessionCost.bind(this),
             isSessionCostLimitReached: this.isSessionCostLimitReached.bind(this),
+            estimateSessionCostLimitReached: this.estimateSessionCostLimitReached.bind(this),
             getSessionCost: this.getSessionCost.bind(this),
             getSessionCostLimit: this.getSessionCostLimit.bind(this),
         });
-        // Initialize default middleware pipeline with WorkflowGuardMiddleware
-        import('./middleware/index.js').then(({ MiddlewarePipeline, WorkflowGuardMiddleware }) => {
+        // Wire the ContextEngine provider so multi-agent lifecycle hooks
+        // (onSubagentStarted / onSubagentEnded / ownsCompaction, cf. Native Engine Vague 2 Phase 1)
+        // can reach the active context engine installed on the ContextManager.
+        // Without this, setContextEngineProvider was defined but never called, leaving
+        // the three call sites in agent-tools.ts (prepareSubagentSpawn, completeAgent,
+        // closeAgent) as no-ops — same dead-wiring pattern as the prior ICM bridge bug.
+        import('./multi-agent/agent-tools.js').then(({ setContextEngineProvider }) => {
+            setContextEngineProvider(() => this.contextManager.getContextEngine?.() ?? null);
+        }).catch(err => {
+            logger.warn('Failed to wire ContextEngine provider for sub-agents', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        });
+        // Initialize default middleware pipeline with WorkflowGuardMiddleware + ReasoningMiddleware
+        import('./middleware/index.js').then(async ({ MiddlewarePipeline, WorkflowGuardMiddleware }) => {
             if (!this.executor.getMiddlewarePipeline()) {
                 const pipeline = new MiddlewarePipeline();
+                // Turn limit middleware (priority 10) — enforces max turns per session
+                try {
+                    const { TurnLimitMiddleware } = await import('./middleware/turn-limit.js');
+                    pipeline.use(new TurnLimitMiddleware());
+                    logger.debug('TurnLimitMiddleware registered in pipeline (priority 10)');
+                }
+                catch (err) {
+                    logger.debug('Failed to register TurnLimitMiddleware (non-critical)', { error: err instanceof Error ? err.message : String(err) });
+                }
+                // Cost limit middleware (priority 20) — enforces session cost budget
+                try {
+                    const { CostLimitMiddleware } = await import('./middleware/cost-limit.js');
+                    pipeline.use(new CostLimitMiddleware({
+                        recordSessionCost: this.recordSessionCost.bind(this),
+                        isSessionCostLimitReached: this.isSessionCostLimitReached.bind(this),
+                    }));
+                    logger.debug('CostLimitMiddleware registered in pipeline (priority 20)');
+                }
+                catch (err) {
+                    logger.debug('Failed to register CostLimitMiddleware (non-critical)', { error: err instanceof Error ? err.message : String(err) });
+                }
+                // Context warning middleware (priority 30) — warns when nearing context limits
+                try {
+                    const { ContextWarningMiddleware } = await import('./middleware/context-warning.js');
+                    pipeline.use(new ContextWarningMiddleware(this.contextManager));
+                    logger.debug('ContextWarningMiddleware registered in pipeline (priority 30)');
+                }
+                catch (err) {
+                    logger.debug('Failed to register ContextWarningMiddleware (non-critical)', { error: err instanceof Error ? err.message : String(err) });
+                }
+                // Reasoning middleware (priority 42) — auto-detects complex queries
+                try {
+                    const { createReasoningMiddleware } = await import('./middleware/reasoning-middleware.js');
+                    pipeline.use(createReasoningMiddleware());
+                    logger.debug('ReasoningMiddleware registered in pipeline (priority 42)');
+                }
+                catch (err) {
+                    logger.debug('Failed to register ReasoningMiddleware (non-critical)', { error: err instanceof Error ? err.message : String(err) });
+                }
+                // Workflow guard (priority 45)
                 pipeline.use(new WorkflowGuardMiddleware());
+                // Auto-repair middleware (priority 150) — detects tool failures, invokes repair engine
+                try {
+                    const { createAutoRepairMiddleware } = await import('./middleware/auto-repair-middleware.js');
+                    pipeline.use(createAutoRepairMiddleware());
+                    logger.debug('AutoRepairMiddleware registered in pipeline (priority 150)');
+                }
+                catch (err) {
+                    logger.debug('Failed to register AutoRepairMiddleware (non-critical)', { error: err instanceof Error ? err.message : String(err) });
+                }
+                // Quality gate middleware (priority 200) — auto-delegates to specialized agents
+                try {
+                    const { createQualityGateMiddleware } = await import('./middleware/quality-gate-middleware.js');
+                    pipeline.use(createQualityGateMiddleware());
+                    logger.debug('QualityGateMiddleware registered in pipeline (priority 200)');
+                }
+                catch (err) {
+                    logger.debug('Failed to register QualityGateMiddleware (non-critical)', { error: err instanceof Error ? err.message : String(err) });
+                }
                 this.executor.setMiddlewarePipeline(pipeline);
                 logger.debug('WorkflowGuardMiddleware registered in default pipeline');
             }
         }).catch(err => {
-            logger.debug('Failed to register WorkflowGuardMiddleware (non-critical)', err);
+            logger.debug('Failed to register middleware pipeline (non-critical)', err);
         });
         // Initialize PromptBuilder with Moltbot hooks for intro injection
         this.promptBuilder = new PromptBuilder({
             yoloMode: this.yoloMode,
             memoryEnabled: this.memoryEnabled,
             morphEditorEnabled: !!this.toolHandler.morphEditor,
-            cwd: process.cwd()
-        }, this.promptCacheManager, this.memory, this.infrastructure.moltbotHooksManager);
+            cwd: initialWorkingDirectory,
+        }, this.promptCacheManager, this.memory, this.infrastructure.moltbotHooksManager, getMemoryManager());
         // Set up executors for the repair coordinator
         this.repairCoordinator.setExecutors({
             commandExecutor: async (cmd) => {
@@ -208,15 +358,112 @@ export class CodeBuddyAgent extends BaseAgent {
         });
         // Initialize facades (required before initializeMCP)
         this.initializeFacades();
-        // Initialize MCP servers if configured
-        this.initializeMCP();
+        // Initialize specialized agent registry (PDF, Excel, SQL, etc.)
+        import('./specialized/agent-registry.js').then(({ initializeAgentRegistry }) => {
+            initializeAgentRegistry().catch(err => {
+                logger.debug('Agent registry init skipped', { error: err instanceof Error ? err.message : String(err) });
+            });
+        }).catch((e) => { logger.debug('Agent registry module load failed (optional)', { error: String(e) }); });
+        // Load SKILL.md skills so findSkill() returns results
+        import('../skills/index.js').then(({ initializeSkills }) => {
+            initializeSkills().catch((e) => { logger.debug('Skills initialization failed (optional)', { error: String(e) }); });
+        }).catch((e) => { logger.debug('Skills module load failed (optional)', { error: String(e) }); });
+        // Initialize MCP servers if configured (can be disabled for headless/one-shot runs).
+        if (process.env.CODEBUDDY_DISABLE_MCP !== 'true') {
+            this.initializeMCP();
+        }
         // Load custom instructions and generate system prompt
         const customInstructions = loadCustomInstructions();
         // Initialize system prompt (async operation) — track readiness
         this.systemPromptReady = this.initializeAgentSystemPrompt(systemPromptId, modelToUse, customInstructions);
+        // Fire SessionStart user hook (non-blocking)
+        getUserHooksManager(initialWorkingDirectory).executeHooks('SessionStart', {}).catch((err) => logger.debug(`[user-hooks] SessionStart error: ${err}`));
+        // Wire visual grounding fallback provider into computer-control-tool
+        import('../tools/computer-control-tool.js').then(({ setVisionGroundingProvider }) => {
+            setVisionGroundingProvider(async (req) => {
+                try {
+                    if (req.candidates.length === 0) {
+                        // Coordinate-based visual grounding fallback for empty UIA tree (e.g., Skia, Avalonia, Canvas)
+                        const prompt = `You are a visual grounding agent. Your task is to find the pixel coordinate of the element matching the user's intent: "${req.intent}".${req.roleHint ? ` Expected role hint: "${req.roleHint}".` : ''}
+
+Identify the target element in the provided screenshot. Return the target's center coordinates on a relative scale from 0 to 1000, where (0, 0) is the top-left corner and (1000, 1000) is the bottom-right corner of the image.
+
+Output ONLY a JSON object in this exact format:
+{
+  "x": <integer between 0 and 1000>,
+  "y": <integer between 0 and 1000>
+}
+Do not write any other text or explanations.`;
+                        const response = await this.codebuddyClient.chat([
+                            {
+                                role: 'user',
+                                content: [
+                                    { type: 'text', text: prompt },
+                                    { type: 'image_url', image_url: { url: `data:image/png;base64,${req.imageBase64}` } }
+                                ]
+                            }
+                        ], undefined, this.visionGroundingModel ? { model: this.visionGroundingModel } : undefined);
+                        const reply = response.choices[0]?.message?.content?.trim();
+                        if (!reply)
+                            return null;
+                        try {
+                            const { parseJsonResponse } = await import('../utils/llm-retry.js');
+                            const parsed = parseJsonResponse(reply);
+                            if (parsed && typeof parsed.x === 'number' && typeof parsed.y === 'number') {
+                                return { x: parsed.x, y: parsed.y };
+                            }
+                        }
+                        catch (e) {
+                            logger.warn('Failed to parse coordinate response as JSON, trying regex fallback', { reply, error: String(e) });
+                            const xMatch = reply.match(/"x"\s*:\s*(\d+)/i);
+                            const yMatch = reply.match(/"y"\s*:\s*(\d+)/i);
+                            const xStr = xMatch?.[1];
+                            const yStr = yMatch?.[1];
+                            if (xStr !== undefined && yStr !== undefined) {
+                                return { x: parseInt(xStr, 10), y: parseInt(yStr, 10) };
+                            }
+                        }
+                        return null;
+                    }
+                    // Traditional Set-of-Marks badging flow if candidates are available
+                    const prompt = `You are a visual grounding agent. Your task is to identify the unique [ref] number of the interactive element in the provided screenshot that matches the user's intent: "${req.intent}".${req.roleHint ? ` Expected role hint: "${req.roleHint}".` : ''}
+
+Here are the candidate elements present in the screenshot:
+${req.candidates.map(c => `[${c.ref}] role="${c.role}" name="${c.name}"`).join('\n')}
+
+Look at the screenshot and find the element matching the user's intent. Output only the reference number (e.g. 42) or "none" if no matching element can be found. Do not write any explanations or other text.`;
+                    const response = await this.codebuddyClient.chat([
+                        {
+                            role: 'user',
+                            content: [
+                                { type: 'text', text: prompt },
+                                { type: 'image_url', image_url: { url: `data:image/png;base64,${req.imageBase64}` } }
+                            ]
+                        }
+                    ], undefined, this.visionGroundingModel ? { model: this.visionGroundingModel } : undefined);
+                    const reply = response.choices[0]?.message?.content?.trim();
+                    if (!reply)
+                        return null;
+                    const match = reply.match(/\b\d+\b/);
+                    if (match) {
+                        return parseInt(match[0], 10);
+                    }
+                }
+                catch (err) {
+                    logger.error('Error in VisionGroundingProvider execution', { error: err });
+                }
+                return null;
+            });
+        }).catch((e) => { logger.debug('setVisionGroundingProvider setup failed', { error: String(e) }); });
     }
     /** Resolves when the system prompt has been loaded (or failed gracefully). */
     systemPromptReady;
+    /**
+     * Set the model override to use specifically for visual grounding fallback calls.
+     */
+    setVisionGroundingModel(model) {
+        this.visionGroundingModel = model;
+    }
     /**
      * Link tool executions to an observability run.
      * Called by dev workflows to associate tool calls with a RunStore run.
@@ -239,20 +486,8 @@ export class CodeBuddyAgent extends BaseAgent {
             catch {
                 // Non-fatal — repo profiling is best-effort
             }
-            // Inject knowledge base context if any Knowledge.md files are loaded
-            try {
-                const { getKnowledgeManager } = await import('../knowledge/knowledge-manager.js');
-                const km = getKnowledgeManager();
-                await km.load();
-                const knowledgeBlock = km.buildContextBlock();
-                if (knowledgeBlock) {
-                    systemPrompt = `${systemPrompt}\n\n${knowledgeBlock}`;
-                    logger.debug('KnowledgeManager: injected knowledge context into system prompt');
-                }
-            }
-            catch {
-                // Non-fatal — knowledge injection is best-effort
-            }
+            systemPrompt = this.applyRuntimeSystemPromptAppend(systemPrompt);
+            // Knowledge base is already injected by PromptBuilder.buildSystemPrompt() — skip duplicate injection here.
             this.messages.push({
                 role: "system",
                 content: systemPrompt,
@@ -267,9 +502,16 @@ export class CodeBuddyAgent extends BaseAgent {
             });
         }
     }
+    applyRuntimeSystemPromptAppend(systemPrompt) {
+        const append = this.systemPromptAppend?.trim();
+        if (!append) {
+            return systemPrompt;
+        }
+        return `${systemPrompt}\n\n<runtime_persona>\n${append}\n</runtime_persona>`;
+    }
     isGrokModel() {
         const currentModel = this.codebuddyClient.getCurrentModel();
-        return currentModel.toLowerCase().includes("codebuddy");
+        return currentModel.toLowerCase().includes("grok");
     }
     /**
      * Match the user query against the skill registry and apply the matched
@@ -278,36 +520,406 @@ export class CodeBuddyAgent extends BaseAgent {
      *
      * This is called at the start of every message processing cycle.
      */
+    _dmProviderWired = false;
+    ensureDecisionMemoryProvider() {
+        if (this._dmProviderWired)
+            return;
+        this._dmProviderWired = true;
+        // Skip in test environment to avoid expensive module loading
+        if (typeof process !== 'undefined' && process.env.NODE_ENV === 'test')
+            return;
+        // Fire-and-forget: wires the provider once the module is loaded.
+        // The executor will skip decision memory injection until the provider is set.
+        import('../memory/decision-memory.js').then(({ getDecisionMemory }) => {
+            setDecisionContextProvider((query) => getDecisionMemory().buildDecisionContext(query));
+        }).catch((e) => { logger.debug('Decision memory module load failed (optional)', { error: String(e) }); });
+        // Wire AskUserQuestion readline UI provider (V4.3 ADR-01)
+        import('../tools/ask-user-question-tool.js').then(({ setAskUserQuestionUIProvider }) => {
+            import('../tools/ask-user-question-readline-provider.js').then(({ getAskUserQuestionReadlineProvider }) => {
+                setAskUserQuestionUIProvider(getAskUserQuestionReadlineProvider());
+            }).catch((e) => { logger.debug('AskUserQuestion readline provider wire failed (optional)', { error: String(e) }); });
+        }).catch((e) => { logger.debug('AskUserQuestion provider register failed (optional)', { error: String(e) }); });
+        // Wire ExitPlanMode readline UI provider (V4.4 — mirror of V4.3 ADR-01)
+        import('../tools/exit-plan-mode-tool.js').then(({ setExitPlanModeUIProvider }) => {
+            import('../tools/exit-plan-mode-readline-provider.js').then(({ getExitPlanModeReadlineProvider }) => {
+                setExitPlanModeUIProvider(getExitPlanModeReadlineProvider());
+            }).catch((e) => { logger.debug('ExitPlanMode readline provider wire failed (optional)', { error: String(e) }); });
+        }).catch((e) => { logger.debug('ExitPlanMode provider register failed (optional)', { error: String(e) }); });
+        // Wire Advisor tool context + config providers (V4.1)
+        import('../tools/advisor-tool.js').then(({ setAdvisorContextProvider }) => {
+            setAdvisorContextProvider(() => ({
+                messages: this.historyManager.getMessages(),
+            }));
+        }).catch((e) => { logger.debug('Advisor context provider wire failed (optional)', { error: String(e) }); });
+        import('../tools/registry/advisor-tools.js').then(({ setAdvisorConfigProvider }) => {
+            import('../config/toml-config.js').then(({ getConfigManager }) => {
+                setAdvisorConfigProvider(() => {
+                    const cfg = getConfigManager().getConfig().advisor ?? {};
+                    return {
+                        enabled: cfg.enabled,
+                        model: cfg.model,
+                        api_key_env: cfg.api_key_env,
+                        base_url: cfg.base_url,
+                    };
+                });
+            }).catch((e) => { logger.debug('Advisor toml-config import failed (optional)', { error: String(e) }); });
+        }).catch((e) => { logger.debug('Advisor config provider wire failed (optional)', { error: String(e) }); });
+        // Phase (d).21 ship 3 — wake NotificationManager via default sink.
+        // Idempotent. Once wired, anyone in the codebase can call notify()
+        // / notifyQuick() and it will gate + log + emit on the manager bus.
+        import('./proactive/notification-default-sink.js')
+            .then(({ wireDefaultNotificationSink }) => wireDefaultNotificationSink())
+            .catch((e) => logger.debug('NotificationManager wire failed (optional)', { error: String(e) }));
+        // Phase (d).21 ship 4 — wake ProgressTracker via default sink.
+        // Idempotent. Logs at 25/50/75/100 thresholds; consumers can attach
+        // additional listeners on getProgressTracker() for richer UX.
+        import('./planner/progress-default-sink.js')
+            .then(({ wireDefaultProgressSink }) => wireDefaultProgressSink())
+            .catch((e) => logger.debug('ProgressTracker wire failed (optional)', { error: String(e) }));
+        // Boot-time auto-start of HeartbeatEngine when [heartbeat] enabled=true in TOML.
+        // The /heartbeat slash command can also start it manually at runtime.
+        // Wired for autonomous fleet support (AUTONOMOUS-FLEET-PROTOCOL v0.1).
+        import('../config/toml-config.js').then(({ getConfigManager }) => {
+            const hbCfg = getConfigManager().getConfig().heartbeat;
+            if (!hbCfg?.enabled)
+                return;
+            import('../daemon/heartbeat.js').then(({ getHeartbeatEngine }) => {
+                const p = { enabled: true };
+                if (hbCfg.interval_minutes !== undefined)
+                    p.intervalMs = hbCfg.interval_minutes * 60 * 1000;
+                if (hbCfg.active_hours_start !== undefined)
+                    p.activeHoursStart = hbCfg.active_hours_start;
+                if (hbCfg.active_hours_end !== undefined)
+                    p.activeHoursEnd = hbCfg.active_hours_end;
+                if (hbCfg.heartbeat_file !== undefined)
+                    p.heartbeatFilePath = hbCfg.heartbeat_file;
+                if (hbCfg.suppression_keyword !== undefined)
+                    p.suppressionKeyword = hbCfg.suppression_keyword;
+                if (hbCfg.max_consecutive_suppressions !== undefined)
+                    p.maxConsecutiveSuppressions = hbCfg.max_consecutive_suppressions;
+                const engine = getHeartbeatEngine(p);
+                if (!engine.isRunning())
+                    engine.start();
+                logger.info('HeartbeatEngine auto-started from TOML config');
+            }).catch((e) => { logger.debug('HeartbeatEngine module load failed (optional)', { error: String(e) }); });
+        }).catch((e) => { logger.debug('Heartbeat config check failed (optional)', { error: String(e) }); });
+        // Boot-time auto-start of Autonomous Fleet Protocol v0.1 (Phase d.18).
+        // Schedules its own setInterval that runs the fleet tick — pull repo,
+        // pick task, claim, exec via in-process agent, append worklog, push.
+        // Independent of HeartbeatEngine (different concern, different cadence).
+        import('../config/toml-config.js').then(({ getConfigManager }) => {
+            const af = getConfigManager().getConfig().autonomous_fleet;
+            if (!af?.enabled)
+                return;
+            if (!af.repo_path || !af.host) {
+                logger.warn('autonomous_fleet enabled but repo_path/host not configured — skipping');
+                return;
+            }
+            import('./autonomous/fleet-tick-handler.js').then(({ runFleetTick }) => {
+                const intervalMs = (af.interval_minutes ?? 30) * 60 * 1000;
+                const fire = () => {
+                    runFleetTick({
+                        repoPath: af.repo_path,
+                        host: af.host,
+                        maxTaskMs: af.max_task_ms,
+                        priorityThreshold: af.priority_threshold ?? 'high',
+                        llmProvider: af.llm_provider,
+                    })
+                        .then((outcome) => logger.info('Autonomous fleet tick result', { outcome }))
+                        .catch((e) => logger.error('Autonomous fleet tick threw', { error: String(e) }));
+                };
+                // First tick after a short warm-up so boot stays fast; then on the
+                // configured interval. setInterval is fine — runFleetTick never
+                // throws and self-bounds via maxTaskMs.
+                setTimeout(fire, 60_000);
+                setInterval(fire, intervalMs);
+                logger.info('Autonomous fleet tick scheduled', { intervalMs, host: af.host });
+            }).catch((e) => logger.debug('autonomous_fleet module load failed (optional)', { error: String(e) }));
+        }).catch((e) => logger.debug('autonomous_fleet config check failed (optional)', { error: String(e) }));
+        // Boot-time auto-start of DailyResetManager when [daily_reset] enabled=true.
+        // The /daily-reset slash command can also start it manually at runtime.
+        // Wired via audit OpenClaw heritage findings (2026-05-02).
+        import('../config/toml-config.js').then(({ getConfigManager }) => {
+            const drCfg = getConfigManager().getConfig().daily_reset;
+            if (!drCfg?.enabled)
+                return;
+            import('../daemon/daily-reset.js').then(({ getDailyResetManager }) => {
+                const p = { enabled: true };
+                if (drCfg.reset_hour !== undefined)
+                    p.resetHour = drCfg.reset_hour;
+                if (drCfg.reset_minute !== undefined)
+                    p.resetMinute = drCfg.reset_minute;
+                if (drCfg.timezone !== undefined)
+                    p.timezone = drCfg.timezone;
+                if (drCfg.post_summary !== undefined)
+                    p.postSummary = drCfg.post_summary;
+                if (drCfg.idle_minutes !== undefined)
+                    p.idleMinutes = drCfg.idle_minutes;
+                const engine = getDailyResetManager(p);
+                engine.start();
+                logger.info('DailyResetManager auto-started from TOML config');
+            }).catch((e) => { logger.debug('DailyResetManager module load failed (optional)', { error: String(e) }); });
+        }).catch((e) => { logger.debug('Daily reset config check failed (optional)', { error: String(e) }); });
+        // Boot-time auto-instantiate of the TeamSessionManager when [team_session]
+        // enabled=true. The /session slash command can also instantiate it manually
+        // at runtime. Wired via audit OpenClaw heritage findings (2026-05-02 — top 1).
+        // V0.1 only instantiates the singleton (local-first); WS sync arrives in V0.2.
+        import('../config/toml-config.js').then(({ getConfigManager }) => {
+            const tsCfg = getConfigManager().getConfig().team_session;
+            if (!tsCfg?.enabled)
+                return;
+            import('../collaboration/team-session.js').then(({ getTeamSessionManager }) => {
+                const p = {};
+                if (tsCfg.server_url !== undefined)
+                    p.serverUrl = tsCfg.server_url;
+                if (tsCfg.enable_encryption !== undefined)
+                    p.enableEncryption = tsCfg.enable_encryption;
+                if (tsCfg.encryption_key !== undefined)
+                    p.encryptionKey = tsCfg.encryption_key;
+                if (tsCfg.auto_reconnect !== undefined)
+                    p.autoReconnect = tsCfg.auto_reconnect;
+                if (tsCfg.reconnect_interval !== undefined)
+                    p.reconnectInterval = tsCfg.reconnect_interval;
+                if (tsCfg.heartbeat_interval !== undefined)
+                    p.heartbeatInterval = tsCfg.heartbeat_interval;
+                if (tsCfg.max_reconnect_attempts !== undefined)
+                    p.maxReconnectAttempts = tsCfg.max_reconnect_attempts;
+                getTeamSessionManager(p);
+                logger.info('TeamSessionManager auto-instantiated from TOML config');
+            }).catch((e) => { logger.debug('TeamSessionManager module load failed (optional)', { error: String(e) }); });
+        }).catch((e) => { logger.debug('Team session config check failed (optional)', { error: String(e) }); });
+        // Boot-time auto-instantiate of MultiAgentSystem when [multi_agent_system]
+        // enabled=true. The /agents slash command can also instantiate it manually
+        // at runtime. Wired via audit OpenClaw heritage findings (2026-05-02 — top 4).
+        // V0.1: only instantiates the singleton (boot does NOT auto-run a workflow).
+        // Requires GROK_API_KEY env var; logs a warning and skips if absent.
+        import('../config/toml-config.js').then(({ getConfigManager }) => {
+            const masCfg = getConfigManager().getConfig().multi_agent_system;
+            if (!masCfg?.enabled)
+                return;
+            const apiKey = process.env.GROK_API_KEY;
+            if (!apiKey) {
+                logger.warn('MultiAgentSystem boot skipped: GROK_API_KEY not set');
+                return;
+            }
+            import('../agent/multi-agent/multi-agent-system.js').then(({ getMultiAgentSystem }) => {
+                getMultiAgentSystem(apiKey, process.env.GROK_BASE_URL);
+                logger.info('MultiAgentSystem auto-instantiated from TOML config', {
+                    default_strategy: masCfg.default_strategy ?? 'hierarchical',
+                });
+            }).catch((e) => { logger.debug('MultiAgentSystem module load failed (optional)', { error: String(e) }); });
+        }).catch((e) => { logger.debug('Multi-agent system config check failed (optional)', { error: String(e) }); });
+        // Boot-time auto-instantiate of EnhancedCoordinator + SessionRegistry
+        // when [multi_agent_system.coordination|sessions].enabled = true (Phase F).
+        // Independent of MAS — these can be enabled separately to enable the
+        // /agents metrics / /agents conflicts / /agents sessions slash actions
+        // and to populate the SessionRegistry that the Phase E session_* tools depend on.
+        import('../config/toml-config.js').then(({ getConfigManager }) => {
+            const cfg = getConfigManager().getConfig().multi_agent_system;
+            const coordCfg = cfg?.coordination;
+            const sessCfg = cfg?.sessions;
+            if (coordCfg?.enabled) {
+                import('../agent/multi-agent/enhanced-coordination.js').then(async ({ getEnhancedCoordinator }) => {
+                    const c = {};
+                    if (coordCfg.enable_adaptive_allocation !== undefined)
+                        c.enableAdaptiveAllocation = coordCfg.enable_adaptive_allocation;
+                    if (coordCfg.min_assignment_confidence !== undefined)
+                        c.minAssignmentConfidence = coordCfg.min_assignment_confidence;
+                    if (coordCfg.max_parallel_per_agent !== undefined)
+                        c.maxParallelPerAgent = coordCfg.max_parallel_per_agent;
+                    if (coordCfg.enable_conflict_resolution !== undefined)
+                        c.enableConflictResolution = coordCfg.enable_conflict_resolution;
+                    if (coordCfg.conflict_timeout !== undefined)
+                        c.conflictTimeout = coordCfg.conflict_timeout;
+                    if (coordCfg.enable_learning !== undefined)
+                        c.enableLearning = coordCfg.enable_learning;
+                    if (coordCfg.history_size !== undefined)
+                        c.historySize = coordCfg.history_size;
+                    if (coordCfg.checkpoint_interval !== undefined)
+                        c.checkpointInterval = coordCfg.checkpoint_interval;
+                    if (coordCfg.auto_resolve_enabled !== undefined)
+                        c.autoResolveEnabled = coordCfg.auto_resolve_enabled;
+                    if (coordCfg.auto_resolve_strategy !== undefined)
+                        c.autoResolveStrategy = coordCfg.auto_resolve_strategy;
+                    const coordinator = getEnhancedCoordinator(c);
+                    logger.info('EnhancedCoordinator auto-instantiated from TOML config');
+                    // Phase N (V0.4.1) — async warm-start from disk if requested.
+                    // Awaited so logger.info happens after load completes; failure
+                    // is best-effort (logged inside enablePersistence).
+                    if (coordCfg.enable_persistence) {
+                        await coordinator.enablePersistence({
+                            metricsTtlDays: coordCfg.metrics_ttl_days,
+                        });
+                        const savedAt = coordinator.getMetricsSavedAt();
+                        if (savedAt) {
+                            logger.info(`EnhancedCoordinator metrics warm-started from disk (savedAt=${savedAt.toISOString()})`);
+                        }
+                    }
+                }).catch((e) => { logger.debug('EnhancedCoordinator module load failed (optional)', { error: String(e) }); });
+            }
+            if (sessCfg?.enabled) {
+                import('../agent/multi-agent/session-registry.js').then(async ({ getSessionRegistry }) => {
+                    const s = {};
+                    if (sessCfg.max_sessions !== undefined)
+                        s.maxSessions = sessCfg.max_sessions;
+                    if (sessCfg.idle_timeout_minutes !== undefined)
+                        s.idleTimeoutMs = sessCfg.idle_timeout_minutes * 60 * 1000;
+                    const reg = getSessionRegistry(s);
+                    await reg.start();
+                    logger.info('SessionRegistry auto-started from TOML config');
+                    // Phase (d).4 (V0.4.1) — attach session fleet bridge. Listeners are
+                    // installed unconditionally; the per-emit env gate
+                    // (CODEBUDDY_FLEET_STREAM=1) decides whether to broadcast. This way
+                    // toggling at runtime doesn't require re-attaching.
+                    try {
+                        const { enableSessionFleetBridge } = await import('../agent/multi-agent/session-fleet-bridge.js');
+                        enableSessionFleetBridge(reg);
+                    }
+                    catch (err) {
+                        logger.debug('Session fleet bridge attach skipped (optional)', { error: String(err) });
+                    }
+                }).catch((e) => { logger.debug('SessionRegistry module load failed (optional)', { error: String(e) }); });
+            }
+        }).catch((e) => { logger.debug('Coordination/sessions config check failed (optional)', { error: String(e) }); });
+        // Wire ICM cross-session memory bridge into executor
+        import('../memory/icm-bridge.js').then(({ ICMBridge }) => {
+            const bridge = new ICMBridge();
+            // Initialize once MCP client is available
+            if (this.mcpClient) {
+                bridge.initialize(this.mcpClient).catch(err => logger.debug('Optional init failed', { error: String(err) }));
+            }
+            setICMBridgeProvider(() => bridge);
+        }).catch((e) => { logger.debug('ICM bridge module load failed (optional)', { error: String(e) }); });
+        // Wire code graph context provider into executor + middleware
+        import('../knowledge/code-graph-context-provider.js').then(({ buildCodeGraphContext, warmEmbeddingIndex }) => {
+            import('../knowledge/knowledge-graph.js').then(({ getKnowledgeGraph }) => {
+                const graph = getKnowledgeGraph();
+                setCodeGraphContextProvider((message) => buildCodeGraphContext(graph, message));
+                // Pre-warm embedding index in background for semantic fallback
+                warmEmbeddingIndex(graph);
+                // Wire graph into workflow guard and reasoning middleware
+                import('./middleware/workflow-guard.js').then(({ setWorkflowGuardGraphProvider }) => {
+                    setWorkflowGuardGraphProvider(() => graph);
+                }).catch(err => logger.debug('Optional init failed', { error: String(err) }));
+                import('./middleware/reasoning-middleware.js').then(({ setReasoningGraphProvider }) => {
+                    setReasoningGraphProvider(() => graph);
+                }).catch(err => logger.debug('Optional init failed', { error: String(err) }));
+                // Wire graph into plan tool and fault localizer
+                import('../tools/registry/plan-tools.js').then(({ wirePlanToolGraph }) => {
+                    wirePlanToolGraph(graph);
+                }).catch(err => logger.debug('Optional init failed', { error: String(err) }));
+                if (this.repairCoordinator) {
+                    try {
+                        this.repairCoordinator.setFaultLocalizerGraph?.(graph);
+                    }
+                    catch { /* non-critical */ }
+                }
+            });
+        }).catch((e) => { logger.debug('Code graph context provider load failed (optional)', { error: String(e) }); });
+        // Wire docs context provider into executor + reasoning middleware
+        import('../docs/docs-context-provider.js').then(async ({ getDocsContextProvider }) => {
+            const docsProvider = getDocsContextProvider();
+            await docsProvider.loadDocsIndex(process.cwd());
+            if (docsProvider.isLoaded) {
+                const provider = (message) => docsProvider.getRelevantContext(message);
+                setDocsContextProvider(provider);
+                // Also wire into reasoning middleware + workflow guard
+                import('./middleware/reasoning-middleware.js').then(({ setReasoningDocsProvider }) => {
+                    setReasoningDocsProvider(provider);
+                }).catch(err => logger.debug('Optional init failed', { error: String(err) }));
+                import('./middleware/workflow-guard.js').then(({ setWorkflowGuardDocsProvider }) => {
+                    setWorkflowGuardDocsProvider(provider);
+                }).catch(err => logger.debug('Optional init failed', { error: String(err) }));
+                logger.debug('Docs context provider wired into executor + reasoning');
+            }
+        }).catch(err => logger.debug('Optional init failed', { error: String(err) }));
+    }
     applySkillMatching(message) {
         try {
-            const match = findSkill(message);
-            if (match && match.confidence >= 0.3) {
+            // Guard: if the message was already injected by /starter, skip re-matching
+            if (message.startsWith('[Starter Pack:')) {
+                return;
+            }
+            // For empty projects, try starter packs first (tag-filtered, lower threshold)
+            let match = null;
+            const isEmpty = getRepoProfiler().isEmptyProject();
+            if (isEmpty) {
+                const starterMatch = findStarterPack(message);
+                if (starterMatch && starterMatch.confidence >= 0.2) {
+                    match = starterMatch;
+                }
+            }
+            // Fall back to general skill matching
+            if (!match) {
+                match = findSkill(message);
+                if (match && match.confidence < 0.3) {
+                    match = null;
+                }
+            }
+            if (match) {
                 const unifiedSkill = skillMdToUnified(match.skill);
-                // Set active skill on the tool selection strategy so required tools are included
-                this.toolSelectionStrategy.setActiveSkill(unifiedSkill);
-                // Inject skill system prompt into the conversation context
-                const skillPrompt = unifiedSkill.systemPrompt || unifiedSkill.description;
-                if (skillPrompt) {
-                    // Find existing skill context message and replace, or insert before the last user message
+                let isDisabled = false;
+                try {
+                    const disabledSkills = new Set(getSkillsHub()
+                        .list()
+                        .filter((s) => s.enabled === false)
+                        .map((s) => s.name));
+                    if (disabledSkills.has(unifiedSkill.name)) {
+                        isDisabled = true;
+                    }
+                }
+                catch {
+                    // Ignored
+                }
+                if (match.skill.enabled === false) {
+                    isDisabled = true;
+                }
+                if (isDisabled) {
+                    logger.warn(`Skill matched but was disabled: ${unifiedSkill.name}`);
+                    this.toolSelectionStrategy.setActiveSkill(null);
+                    // Also clear any existing skill message
                     const existingIdx = this.messages.findIndex(m => m.role === 'system' && typeof m.content === 'string' && m.content.startsWith('[Skill:'));
-                    const skillMessage = {
-                        role: 'system',
-                        content: `[Skill: ${unifiedSkill.name}]\n${skillPrompt}`,
-                    };
                     if (existingIdx >= 0) {
-                        this.messages[existingIdx] = skillMessage;
+                        this.messages.splice(existingIdx, 1);
                     }
-                    else {
-                        // Insert after the main system prompt (index 1)
-                        const insertIdx = Math.min(1, this.messages.length);
-                        this.messages.splice(insertIdx, 0, skillMessage);
+                }
+                else {
+                    // Set active skill on the tool selection strategy so required tools are included
+                    this.toolSelectionStrategy.setActiveSkill(unifiedSkill);
+                    // Inject skill system prompt into the conversation context
+                    const skillPrompt = unifiedSkill.systemPrompt || unifiedSkill.description;
+                    if (skillPrompt) {
+                        // Find existing skill context message and replace, or insert before the last user message
+                        const existingIdx = this.messages.findIndex(m => m.role === 'system' && typeof m.content === 'string' && m.content.startsWith('[Skill:'));
+                        const skillMessage = {
+                            role: 'system',
+                            content: `[Skill: ${unifiedSkill.name}]\n${skillPrompt}`,
+                        };
+                        if (existingIdx >= 0) {
+                            this.messages[existingIdx] = skillMessage;
+                        }
+                        else {
+                            // Insert after the main system prompt (index 1)
+                            const insertIdx = Math.min(1, this.messages.length);
+                            this.messages.splice(insertIdx, 0, skillMessage);
+                        }
+                    }
+                    logger.debug('Skill matched for query', {
+                        skill: unifiedSkill.name,
+                        confidence: match.confidence,
+                        reason: match.reason,
+                    });
+                    try {
+                        getActiveRunStore()?.appendEvent('skill_selected', {
+                            skillName: unifiedSkill.name,
+                            confidence: match.confidence,
+                            reason: match.reason,
+                        });
+                    }
+                    catch {
+                        // Skill usage telemetry is best-effort and must not block a turn.
                     }
                 }
-                logger.debug('Skill matched for query', {
-                    skill: unifiedSkill.name,
-                    confidence: match.confidence,
-                    reason: match.reason,
-                });
             }
             else {
                 // No skill matched - clear any previous skill context
@@ -320,6 +932,8 @@ export class CodeBuddyAgent extends BaseAgent {
         }
     }
     async processUserMessage(message) {
+        // Lazy-wire decision memory provider on first call
+        this.ensureDecisionMemoryProvider();
         // Reset cached tools for new conversation turn
         this.toolSelectionStrategy.clearCache();
         // Match user query against skill registry
@@ -335,9 +949,13 @@ export class CodeBuddyAgent extends BaseAgent {
         // Trim history to prevent memory bloat
         this.trimHistory();
         const newEntries = await this.executor.processUserMessage(message, this.chatHistory, this.messages);
+        // Fire-and-forget Hermes-style post-session learning review (interactive only).
+        void this.maybeRunBackgroundReview();
         return [userEntry, ...newEntries];
     }
     async *processUserMessageStream(message) {
+        // Lazy-wire decision memory provider on first call
+        this.ensureDecisionMemoryProvider();
         // Create new abort controller for this request
         this.abortController = new AbortController();
         // Reset cached tools for new conversation turn
@@ -412,6 +1030,8 @@ export class CodeBuddyAgent extends BaseAgent {
             // Clean up abort controller
             this.abortController = null;
         }
+        // Fire-and-forget Hermes-style post-session learning review (interactive only).
+        void this.maybeRunBackgroundReview();
     }
     async executeTool(toolCall) {
         return this.toolHandler.executeTool(toolCall);
@@ -431,9 +1051,33 @@ export class CodeBuddyAgent extends BaseAgent {
     getCurrentDirectory() {
         return this.toolHandler.bash.getCurrentDirectory();
     }
+    /**
+     * Set the working directory used to scope tool execution contexts. The
+     * Cowork embedded engine calls this with the active project's
+     * `workspacePath` so `.codebuddy/`-backed tools (`lessons_propose`,
+     * `user_model_observe`, …) target the project instead of the Electron
+     * process directory. `undefined` restores the `process.cwd()` default.
+     */
+    setWorkingDirectory(dir) {
+        this.toolHandler.setWorkingDirectory(dir);
+        this.promptBuilder.updateConfig({ cwd: dir || process.cwd() });
+    }
+    setSystemPromptAppend(append) {
+        this.systemPromptAppend = append;
+    }
     async executeBashCommand(command) {
         return await this.toolHandler.bash.execute(command);
     }
+    async executeToolByName(name, parameters = {}) {
+        return await this.toolHandler.executeTool({
+            id: `server_tool_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+            type: 'function',
+            function: {
+                name,
+                arguments: JSON.stringify(parameters),
+            },
+        });
+    }
     getCurrentModel() {
         return this.codebuddyClient.getCurrentModel();
     }
@@ -459,8 +1103,9 @@ export class CodeBuddyAgent extends BaseAgent {
         const customInstructions = loadCustomInstructions();
         const chatOnlyPrompt = getChatOnlySystemPrompt(process.cwd(), customInstructions || undefined);
         // Replace the system message
-        if (this.messages.length > 0 && this.messages[0].role === 'system') {
-            this.messages[0].content = chatOnlyPrompt;
+        const firstMessage = this.messages[0];
+        if (firstMessage && firstMessage.role === 'system') {
+            firstMessage.content = chatOnlyPrompt;
         }
         else {
             // Insert at the beginning if no system message exists
@@ -614,10 +1259,11 @@ export class CodeBuddyAgent extends BaseAgent {
      * @param prompt - The custom system prompt content
      */
     setSystemPrompt(prompt) {
+        this.customSystemPromptOverride = prompt;
         // Find and update the system message
-        const systemMessageIndex = this.messages.findIndex(m => m.role === 'system');
-        if (systemMessageIndex >= 0) {
-            this.messages[systemMessageIndex].content = prompt;
+        const systemMessage = this.messages.find(m => m.role === 'system');
+        if (systemMessage) {
+            systemMessage.content = prompt;
         }
         else {
             // Add system message if none exists
@@ -653,17 +1299,28 @@ export class CodeBuddyAgent extends BaseAgent {
      */
     setYoloMode(enabled) {
         this.yoloMode = enabled;
-        this.maxToolRounds = enabled ? 400 : 50;
-        this.sessionCostLimit = enabled ? Infinity : 10;
+        const YOLO_HARD_LIMIT = 100;
+        const maxCostEnv = process.env.MAX_COST ? parseFloat(process.env.MAX_COST) : null;
+        if (enabled) {
+            this.sessionCostLimit = maxCostEnv !== null
+                ? Math.min(maxCostEnv, YOLO_HARD_LIMIT * 10)
+                : YOLO_HARD_LIMIT;
+            this.maxToolRounds = 400;
+        }
+        else {
+            this.sessionCostLimit = maxCostEnv !== null ? maxCostEnv : 10;
+            this.maxToolRounds = 50;
+        }
         // Update prompt builder config
         this.promptBuilder.updateConfig({ yoloMode: enabled });
         // Update system prompt for new mode — track readiness
         const customInstructions = loadCustomInstructions();
         this.systemPromptReady = (async () => {
-            const systemPrompt = await this.promptBuilder.buildSystemPrompt(undefined, this.getCurrentModel(), customInstructions);
+            const systemPrompt = this.applyRuntimeSystemPromptAppend(await this.promptBuilder.buildSystemPrompt(undefined, this.getCurrentModel(), customInstructions));
             // Update the system message
-            if (this.messages.length > 0 && this.messages[0].role === "system") {
-                this.messages[0].content = systemPrompt;
+            const firstMessage = this.messages[0];
+            if (firstMessage && firstMessage.role === "system") {
+                firstMessage.content = systemPrompt;
             }
         })().catch(error => {
             logger.error("Failed to update system prompt for YOLO mode", error);
@@ -674,14 +1331,15 @@ export class CodeBuddyAgent extends BaseAgent {
      * Lazily imports and adds AutoObservationMiddleware to the executor's pipeline.
      * Called automatically when a profile with metadata.enableAutoObservation is active.
      */
-    enableAutoObservation(config) {
+    async enableAutoObservation(config) {
         // Ensure the executor has a middleware pipeline
         if (!this.executor.getMiddlewarePipeline()) {
-            const { MiddlewarePipeline } = require('./middleware/index.js');
+            const { MiddlewarePipeline } = await import('./middleware/index.js');
             this.executor.setMiddlewarePipeline(new MiddlewarePipeline());
         }
         // Lazily import and add the middleware
-        import('./middleware/auto-observation.js').then(({ AutoObservationMiddleware }) => {
+        try {
+            const { AutoObservationMiddleware } = await import('./middleware/auto-observation.js');
             const pipeline = this.executor.getMiddlewarePipeline();
             if (!pipeline)
                 return;
@@ -690,9 +1348,59 @@ export class CodeBuddyAgent extends BaseAgent {
                 return;
             pipeline.use(new AutoObservationMiddleware(config));
             logger.info('Auto-observation middleware enabled');
-        }).catch(err => {
+        }
+        catch (err) {
             logger.error('Failed to enable auto-observation middleware', err);
-        });
+        }
+    }
+    /**
+     * Opt this agent into the Hermes-style post-session background self-learning
+     * review. Set ONLY by the interactive entrypoint so cron/headless/sub-agent
+     * agents never trigger a review (recursion + cost safety). The review itself
+     * is additionally gated by the `CODEBUDDY_LEARNING_BACKGROUND_REVIEW` env flag.
+     */
+    enableBackgroundReview() {
+        this.backgroundReviewEnabled = true;
+    }
+    /**
+     * Fire a one-shot restricted-toolset learning review over the recent
+     * transcript. Fire-and-forget: callers do NOT await it on the response path.
+     * No-ops unless opted in (interactive flag) AND the env flag is on AND we are
+     * not already inside a review (sentinel), so a review can never recurse.
+     */
+    async maybeRunBackgroundReview() {
+        // Wrap everything: this is invoked fire-and-forget, so an unhandled rejection
+        // here (including a dynamic-import failure) must never escape.
+        try {
+            // Snapshot the recent transcript synchronously before any async work.
+            const transcript = this.chatHistory.slice(-20).map((entry) => ({
+                role: typeof entry.type === 'string' ? entry.type : 'assistant',
+                content: typeof entry.content === 'string' ? entry.content : JSON.stringify(entry.content ?? ''),
+            }));
+            const { shouldTriggerBackgroundReview, runBackgroundReview } = await import('./learning/background-review-agent.js');
+            if (!shouldTriggerBackgroundReview({
+                interactiveOptIn: this.backgroundReviewEnabled,
+                envFlag: process.env.CODEBUDDY_LEARNING_BACKGROUND_REVIEW,
+                sentinel: process.env.CODEBUDDY_BACKGROUND_REVIEW,
+                transcriptLength: transcript.length,
+            })) {
+                return;
+            }
+            const result = await runBackgroundReview({
+                client: this.codebuddyClient,
+                transcript,
+                mode: 'combined',
+                workDir: this.getCurrentDirectory(),
+            });
+            if (!result.skipped && result.summary) {
+                logger.info(`[background-review] ${result.summary}`);
+            }
+        }
+        catch (err) {
+            logger.debug('[background-review] post-session review failed', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
     }
     /**
      * Record cost for current request
@@ -710,6 +1418,15 @@ export class CodeBuddyAgent extends BaseAgent {
             this.budgetAlertManager.check(this.sessionCost, this.sessionCostLimit);
         }
     }
+    /**
+     * Estimate session cost after hypothetically recording the given tokens.
+     * Does NOT mutate state — safe for pre-checks.
+     */
+    estimateSessionCostAfter(inputTokens, outputTokens) {
+        const model = this.codebuddyClient.getCurrentModel();
+        const cost = this.costTracker.calculateCost(inputTokens, outputTokens, model);
+        return this.sessionCost + cost;
+    }
     /**
      * Format cost status for display
      */
@@ -796,8 +1513,8 @@ export class CodeBuddyAgent extends BaseAgent {
     /**
      * Check if a request is complex enough to warrant planning
      */
-    needsPlanning(request) {
-        const { TaskPlanner } = require('./planner/index.js');
+    async needsPlanning(request) {
+        const { TaskPlanner } = await import('./planner/index.js');
         const planner = new TaskPlanner();
         return planner.needsPlanning(request);
     }
@@ -818,7 +1535,7 @@ export class CodeBuddyAgent extends BaseAgent {
         tracker.start(plan.tasks.length);
         const delegationEngine = new DelegationEngine();
         const entries = [];
-        const result = await graph.execute(async (task) => {
+        const _result = await graph.execute(async (task) => {
             tracker.update(task.id, 'running');
             const progress = tracker.getProgress();
             this.emit('plan:progress', {
@@ -873,18 +1590,77 @@ export class CodeBuddyAgent extends BaseAgent {
             this.emit('error', err instanceof Error ? err : new Error(String(err)));
         }
     }
+    /**
+     * Add a message to the agent's conversation history.
+     * Used by the desktop engine adapter to restore session context
+     * when creating a new agent for an existing session.
+     */
+    addToHistory(message) {
+        this.messages.push({ role: message.role, content: message.content });
+        if (message.role === 'user') {
+            this.chatHistory.push({
+                type: 'user',
+                content: message.content,
+                timestamp: new Date(),
+            });
+        }
+        else if (message.role === 'assistant') {
+            this.chatHistory.push({
+                type: 'assistant',
+                content: message.content,
+                timestamp: new Date(),
+            });
+        }
+    }
     /**
      * Clean up all resources
      * Should be called when the agent is no longer needed
      */
     dispose() {
+        // Fire SessionEnd user hook (non-blocking). Shutdown errors should be
+        // visible (warn, not debug) — silent debug logs masked prior bugs.
+        getUserHooksManager(process.cwd()).executeHooks('SessionEnd', {}).catch((err) => logger.warn(`[user-hooks] SessionEnd error: ${err instanceof Error ? err.message : String(err)}`));
+        if (isFeatureEnabled('USER_MODEL_DIALECTIC_ON_SESSION_END')) {
+            const chatHistory = this.historyManager.getChatHistory();
+            if (chatHistory && chatHistory.length > 0) {
+                import('../memory/user-model.js')
+                    .then(({ runUserDialecticInference }) => {
+                    return runUserDialecticInference(chatHistory, process.cwd(), this.codebuddyClient);
+                })
+                    .then((proposed) => {
+                    if (proposed.length > 0) {
+                        logger.info(`[user-model] Auto dialectic inference proposed ${proposed.length} new preference(s).`);
+                    }
+                })
+                    .catch((err) => {
+                    logger.debug('[user-model] Dialectic session-end inference failed', { error: String(err) });
+                });
+            }
+        }
         // Remove only the forwarding listeners we attached (not other listeners)
-        if (this.repairListeners.start) {
-            this.repairCoordinator.off('repair:start', this.repairListeners.start);
-            this.repairCoordinator.off('repair:success', this.repairListeners.success);
-            this.repairCoordinator.off('repair:failed', this.repairListeners.failed);
-            this.repairCoordinator.off('repair:error', this.repairListeners.error);
+        const { start, success, failed, error } = this.repairListeners;
+        if (start) {
+            this.repairCoordinator.off('repair:start', start);
+            if (success)
+                this.repairCoordinator.off('repair:success', success);
+            if (failed)
+                this.repairCoordinator.off('repair:failed', failed);
+            if (error)
+                this.repairCoordinator.off('repair:error', error);
         }
+        if (this._budgetAlertListener) {
+            this.budgetAlertManager.off('alert', this._budgetAlertListener);
+            this._budgetAlertListener = undefined;
+        }
+        // Release the ContextEngine provider to avoid retaining this agent instance
+        // via the agent-tools module-level closure.
+        import('./multi-agent/agent-tools.js').then(({ setContextEngineProvider }) => {
+            setContextEngineProvider(() => null);
+        }).catch(err => {
+            logger.warn('Failed to release ContextEngine provider on dispose', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        });
         this.peerRoutingConfig = null;
         super.dispose();
     }