wave-agent-sdk 1.2.0 → 1.3.0

package/dist/managers/aiManager.js

@@ -6,8 +6,13 @@ import { parseTaskNotificationXml } from "../utils/notificationXml.js";
 import { estimateContextTokens } from "../utils/tokenCalculation.js";
 import { estimateTokens } from "../utils/tokenEstimate.js";
 import { getTaskReminderTurnCounts, maybeInjectTaskReminder, TASK_REMINDER_CONFIG, } from "../utils/taskReminder.js";
+import { getChangedFilesReminder } from "../utils/fileChangeReminder.js";
+import { buildMcpInstructionsAnnouncement, collectAnnouncedServers, } from "../utils/mcpInstructions.js";
+import { buildExecCatalogAnnouncement, collectExecCatalogState, } from "../exec/catalogAnnouncement.js";
 import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import * as path from "node:path";
+import { EDIT_TOOL_NAME, WRITE_TOOL_NAME } from "../constants/tools.js";
 import { buildSystemPrompt, formatCompactSummary, getCompactPrompt, } from "../prompts/index.js";
 import { buildPlanModeReminder, buildPlanModeReEntryReminder, buildExitedPlanModeReminder, wrapInSystemReminder, } from "../prompts/planModeReminders.js";
 import { recoverTruncatedJson } from "../utils/stringUtils.js";
@@ -112,6 +117,9 @@ export class AIManager {
     get permissionManager() {
         return this.container.get("PermissionManager");
     }
+    get mcpManager() {
+        return this.container.get("McpManager");
+    }
     get planManager() {
         return this.container.get("PlanManager");
     }
@@ -420,6 +428,12 @@ export class AIManager {
             logger?.warn("Compaction already in progress");
             return;
         }
+        // 压缩绑定发起时的会话：LLM fork 期间用户可能已把 agent 原地切到另一会话
+        // （IDE「历史对话」restoreSession / CLI 与插件 `/clear` 都会换 sessionId，
+        // 且均不被 isCompacting 阻拦）。写入阶段前必须复核，否则摘要块会追加进
+        // 切换后会话的内存列表并持久化进其转录文件（spec message-compact「压缩
+        // 期间的会话保护」；PM 缺陷 3478352534577408）。
+        const sessionIdAtStart = this.messageManager.getSessionId();
         // 1. Run PreCompact hooks
         let hookInstructions;
         if (this.hookManager) {
@@ -440,7 +454,7 @@ export class AIManager {
         this.setIsCompacting(true);
         try {
             const modelConfig = this.getModelConfig();
-            const recentChatMessages = convertMessagesForAPI(messagesToCompact, {
+            const recentChatMessages = await convertMessagesForAPI(messagesToCompact, {
                 supportsVision: supportsVision(modelConfig.capabilities),
             });
             const compactPrompt = getCompactPrompt(mergedInstructions);
@@ -467,7 +481,15 @@ export class AIManager {
             const formattedSummary = formatCompactSummary(summaryContent);
             // 7. Build post-compact context restoration
             const enhancedSummary = await this.buildPostCompactContext(formattedSummary);
-            // 8. Execute message reconstruction
+            // 8. Execute message reconstruction — only if the session is still the
+            // one this compaction started for. Abandoning here skips the entire
+            // write phase (summary append, post-compact context restore, plan-mode
+            // reminder, SessionStart/PostCompact hooks); the spent LLM call is not
+            // recovered and the original session simply stays uncompacted.
+            if (this.messageManager.getSessionId() !== sessionIdAtStart) {
+                logger?.warn(`Compaction abandoned: session switched from ${sessionIdAtStart} to ${this.messageManager.getSessionId()} while the summary was being generated`);
+                return;
+            }
             await this.messageManager.compactMessagesAndUpdateSession(enhancedSummary, compactUsage);
             // Clear readFileState after compaction (aligned with Claude Code's
             // compact flow): a file_unchanged stub would otherwise reference Read
@@ -534,7 +556,10 @@ export class AIManager {
         catch (compactError) {
             this.consecutiveCompactionFailures++;
             logger?.error(`Failed to compact messages (${this.consecutiveCompactionFailures} consecutive): ${compactError instanceof Error ? compactError.message : String(compactError)}`);
-            this.messageManager.addErrorBlock(`Failed to compact conversation history: ${compactError instanceof Error ? compactError.message : String(compactError)}. You may encounter context limit issues.`);
+            // 会话已被切走时错误块同样不得写进切换后的会话（与上面的写入放弃同口径）
+            if (this.messageManager.getSessionId() === sessionIdAtStart) {
+                this.messageManager.addErrorBlock(`Failed to compact conversation history: ${compactError instanceof Error ? compactError.message : String(compactError)}. You may encounter context limit issues.`);
+            }
         }
         finally {
             this.setIsCompacting(false);
@@ -562,6 +587,58 @@ export class AIManager {
             autoMemory: autoMemoryOptions,
         });
     }
+    /**
+     * Announce the connected MCP servers' own usage notes in the conversation,
+     * once per server. Not part of the system prompt: this content appears when a
+     * connection happens, and rewriting the system prompt mid-session would drop
+     * the whole cached prefix (see `utils/mcpInstructions.ts`).
+     */
+    maybeAnnounceMcpInstructions() {
+        const mcpManager = this.mcpManager;
+        // Optional for the same reason as `getEffectiveAdditionalDirectories` above:
+        // hosts and tests register partial McpManager doubles, and a missing
+        // usage-notes channel is not a reason to fail the turn. Bailing out matters
+        // more here than elsewhere — reading an absent manager as "no servers left"
+        // would announce every previously announced server as disconnected.
+        if (!mcpManager || typeof mcpManager.getServerInstructions !== "function") {
+            return;
+        }
+        const available = mcpManager.getServerInstructions((toolName) => this.permissionManager?.isToolDenied?.(toolName) === true);
+        const announced = collectAnnouncedServers(this.messageManager.getMessages());
+        const availableNames = new Set(available.map((server) => server.name));
+        const text = buildMcpInstructionsAnnouncement({
+            added: available.filter((server) => !announced.has(server.name)),
+            removed: Array.from(announced).filter((name) => !availableNames.has(name)),
+        });
+        if (!text)
+            return;
+        this.messageManager.addUserMessage({
+            content: wrapInSystemReminder(text),
+            isMeta: true,
+        });
+    }
+    /**
+     * Announce the MCP catalog in the conversation, whenever the pool renders
+     * differently from the last announcement. Keeping it out of `Exec`'s description
+     * is what makes that declaration a constant: a server connecting would otherwise
+     * rewrite `tools[]`, which sits in the cached prefix (see
+     * `exec/catalogAnnouncement.ts`).
+     */
+    maybeAnnounceExecCatalog() {
+        const toolManager = this.toolManager;
+        // Optional for the same reason as `maybeAnnounceMcpInstructions` above, and it
+        // matters just as much here: reading an absent channel as "the catalog is gone"
+        // would tell the model to stop using every tool an earlier catalog listed.
+        if (!toolManager || typeof toolManager.getExecCatalog !== "function")
+            return;
+        const text = buildExecCatalogAnnouncement(collectExecCatalogState(this.messageManager.getMessages()), toolManager.getExecCatalog());
+        if (!text)
+            return;
+        this.messageManager.addUserMessage({
+            content: wrapInSystemReminder(text),
+            isMeta: true,
+        });
+    }
     resolveFilteredTools() {
         const toolsConfig = this.getFilteredToolsConfig();
         const toolNames = new Set(toolsConfig.map((t) => t.function.name));
@@ -596,9 +673,13 @@ export class AIManager {
         forkMessages.push({ role: "user", content: prompt });
         const { toolsConfig, filteredToolPlugins } = this.resolveFilteredTools();
         const systemPrompt = await this.buildMainSystemPrompt(filteredToolPlugins);
-        // Fresh read-state map so Read/Edit state built up inside the fork never
-        // leaks into the main session's dedup and staleness tracking.
-        const forkReadFileState = new Map();
+        // Clone the parent session's read state so the fork inherits the read/dedup
+        // baseline (aligned with Claude Code's cloneFileStateCache): the fork can
+        // Edit a file the parent already read without re-reading it first. The
+        // clone is an independent Map with copied entries, so reads/writes inside
+        // the fork never leak back into the main session's dedup and staleness
+        // tracking.
+        const forkReadFileState = new Map(Array.from(this.readFileState, ([path, entry]) => [path, { ...entry }]));
         let totalUsage;
         let content;
         for (let turn = 0; turn < options.maxTurns; turn++) {
@@ -706,7 +787,7 @@ export class AIManager {
      */
     async runAutoMemoryFork(messages, prompt, options, abortSignal) {
         const modelConfig = this.getModelConfig();
-        const historyMessages = convertMessagesForAPI(messages, {
+        const historyMessages = await convertMessagesForAPI(messages, {
             supportsVision: supportsVision(modelConfig.capabilities),
         });
         // Give the fork a real signal even when the caller has none, so tools
@@ -804,7 +885,7 @@ export class AIManager {
         const lastMessage = rawMessages[rawMessages.length - 1];
         const hasInProgressMessage = lastMessage?.role === "assistant" &&
             lastMessage.blocks.some((b) => "stage" in b && b.stage === "streaming");
-        const forkMessages = convertMessagesForAPI(hasInProgressMessage ? rawMessages.slice(0, -1) : rawMessages, { supportsVision: supportsVision(modelConfig.capabilities) });
+        const forkMessages = await convertMessagesForAPI(hasInProgressMessage ? rawMessages.slice(0, -1) : rawMessages, { supportsVision: supportsVision(modelConfig.capabilities) });
         // Mirror the main loop's memory injection so the request prefix matches.
         const { prependContent } = await this.messageManager.getMemoryForInjection();
         if (prependContent.trim()) {
@@ -933,29 +1014,32 @@ ${question}`;
         // 4. Invoked skills context (with token budget, matching Claude Code)
         const POST_COMPACT_SKILLS_TOKEN_BUDGET = 25000;
         const POST_COMPACT_MAX_TOKENS_PER_SKILL = 5000;
-        const invokedSkillNames = this.messageManager.getInvokedSkillNames(10);
-        if (invokedSkillNames.length > 0 && this.skillManager) {
+        const invokedSkills = this.messageManager.getInvokedSkills?.(10) ?? [];
+        if (invokedSkills.length > 0 && this.skillManager) {
             const invokedSkillParts = [];
             let skillsUsedTokens = 0;
-            for (const skillName of invokedSkillNames) {
+            for (const invoked of invokedSkills) {
                 try {
-                    const skill = await this.skillManager.loadSkill(skillName);
-                    if (!skill)
+                    const skill = await this.skillManager.loadSkill(invoked.skillName);
+                    // Re-inject what the model actually saw (already substituted, with the
+                    // base-directory header). Re-render from the file only when that
+                    // record is missing — never hand the model a raw SKILL.md, whose
+                    // `${WAVE_SKILL_DIR}` would be a literal placeholder
+                    // (spec core/message-compact 场景 4).
+                    let skillContent = invoked.content?.trim() ??
+                        (skill ? this.skillManager.renderSkillContent(skill) : undefined);
+                    if (!skillContent)
                         continue;
-                    const contentMatch = skill.content.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
-                    let skillContent = contentMatch
-                        ? contentMatch[1].trim()
-                        : skill.content;
                     const maxSkillChars = POST_COMPACT_MAX_TOKENS_PER_SKILL * 4;
                     if (skillContent.length > maxSkillChars) {
-                        skillContent =
-                            skillContent.slice(0, maxSkillChars) + "\n\n...[truncated]...";
+                        skillContent = `${skillContent.slice(0, maxSkillChars)}\n\n...[truncated]...`;
                     }
                     const skillTokens = estimateTokens(skillContent);
                     if (skillsUsedTokens + skillTokens > POST_COMPACT_SKILLS_TOKEN_BUDGET)
                         break;
                     skillsUsedTokens += skillTokens;
-                    invokedSkillParts.push(`\n\n## ${skill.name}\n${skill.description ? `*${skill.description}*\n\n` : ""}\`\`\`\n${skillContent}\n\`\`\``);
+                    const description = skill?.description;
+                    invokedSkillParts.push(`\n\n## ${skill?.name ?? invoked.skillName}\n${description ? `*${description}*\n\n` : ""}\`\`\`\n${skillContent}\n\`\`\``);
                 }
                 catch {
                     // Skip skills that can't be loaded
@@ -1030,9 +1114,22 @@ ${question}`;
     get skillManager() {
         return this.container.get("SkillManager");
     }
+    get liveConfigManager() {
+        return this.container.get("LiveConfigManager");
+    }
     async sendAIMessage(options = {}) {
         const { recursionDepth = 0, model, allowedRules, maxTokens } = options;
         let turnOffset = recursionDepth;
+        // Pin the settings.json-derived configuration for the whole turn: live
+        // reload can land mid-turn and the turn must not see values shift under it
+        // (core/agent-config.md scenario 5). Nested turns (subagent turns inside
+        // their parent's) share the outer snapshot instead of re-capturing it; the
+        // release at the end of the turn mirrors this capture and lives on the
+        // single exit path of this function.
+        const ownsTurnSnapshot = recursionDepth === 0;
+        if (ownsTurnSnapshot) {
+            this.liveConfigManager?.onTurnStart();
+        }
         // Reserve this turn synchronously before any async work. Bumping the
         // generation invalidates any in-flight turn's end-of-turn cleanup, and
         // recording myGeneration lets us skip cleanup if a newer turn (or abort)
@@ -1132,14 +1229,33 @@ ${question}`;
                             isMeta: true,
                         });
                     }
+                    // Nested memory: a read inside a subtree pulls in that subtree's
+                    // AGENTS.md (persisted as a meta message, aligned with Claude Code's
+                    // nested_memory attachment). Runs with the rules above — before the
+                    // message snapshot below, so the file lands in this request rather
+                    // than the next one. Optional call: hosts and tests register partial
+                    // MessageManager doubles, and absence reads as "nothing triggered".
+                    const nestedMemories = (await this.messageManager.collectNestedMemoryFiles?.()) ?? [];
+                    for (const memory of nestedMemories) {
+                        this.messageManager.addUserMessage({
+                            content: wrapInSystemReminder(`Contents of ${memory.path}:\n\n${memory.content}`),
+                            isMeta: true,
+                        });
+                    }
                     // Pre-request auto-compaction: estimate the context about to be sent
                     // and compact BEFORE issuing the request, so an over-limit request
                     // never goes out. Skipped on fork paths (they use runForkLoop).
                     await this.maybeAutoCompactBeforeRequest(abortController);
+                    // Announce MCP servers' own usage notes (persisted meta message) before
+                    // the snapshot below, so a server that connected mid-session explains
+                    // itself in the request that can already call it. After compaction, so
+                    // the announcement is not the content that just got summarized away.
+                    this.maybeAnnounceMcpInstructions();
+                    this.maybeAnnounceExecCatalog();
                     // Get recent message history
                     const rawMessages = this.messageManager.getMessages();
                     const currentModelConfig = this.getModelConfig();
-                    const recentMessages = convertMessagesForAPI(rawMessages, {
+                    const recentMessages = await convertMessagesForAPI(rawMessages, {
                         supportsVision: supportsVision(currentModelConfig.capabilities),
                     });
                     // Track if assistant message has been created
@@ -1183,6 +1299,19 @@ ${question}`;
                             isMeta: true,
                         });
                     }
+                    // External file-change reminder (aligned with Claude Code's
+                    // changed_files attachment): notify the agent about files it read
+                    // that were since changed on disk by another process — the
+                    // auto-memory extraction fork, an external editor, another session.
+                    // Persisted as a meta message like the task reminder, so it stays in
+                    // the message prefix the auto-memory fork mirrors for cache reuse.
+                    const changedFilesReminder = await getChangedFilesReminder(this.readFileState);
+                    if (changedFilesReminder) {
+                        this.messageManager.addUserMessage({
+                            content: wrapInSystemReminder(changedFilesReminder),
+                            isMeta: true,
+                        });
+                    }
                     // Add streaming callbacks only if streaming is enabled
                     if (this.stream) {
                         callAgentOptions.onContentUpdate = (content) => {
@@ -1579,6 +1708,9 @@ ${question}`;
                 if (myGeneration === this.turnGeneration) {
                     this.setIsLoading(false);
                 }
+                if (ownsTurnSnapshot) {
+                    this.liveConfigManager?.onTurnEnd();
+                }
                 break outer;
             }
         }
@@ -1838,6 +1970,10 @@ ${question}`;
                 images: toolImages,
                 timestamp: Date.now(),
             });
+            // Plan panel refresh (spec: 计划文件更新后刷新计划面板): a successful
+            // Write/Edit of the plan file broadcasts the new content so hosts can
+            // update an already-open plan panel without waiting for ExitPlanMode.
+            await this.notifyPlanFileUpdate(toolName, toolArgs, toolResult.success);
             // Execute PostToolUse hooks after successful tool completion
             await this.executePostToolUseHooks(toolId, toolName, toolArgs, toolResult);
         }
@@ -1856,6 +1992,39 @@ ${question}`;
             });
         }
     }
+    /**
+     * Plan panel refresh (spec: 计划文件更新后刷新计划面板).
+     *
+     * When a successful `Write`/`Edit` targets the current plan file, read it and
+     * emit the full content so hosts can update an already-open plan panel. The
+     * path comparison mirrors the plan-mode allow branch in PermissionManager so
+     * "the write that was allowed" and "the write that refreshes the panel" stay
+     * the same set. The path is only set while plan mode is active, so post-exit
+     * writes can't reach the panels.
+     */
+    async notifyPlanFileUpdate(toolName, toolArgs, success) {
+        if (!success)
+            return;
+        if (toolName !== WRITE_TOOL_NAME && toolName !== EDIT_TOOL_NAME)
+            return;
+        const targetPath = toolArgs.file_path;
+        if (typeof targetPath !== "string" || targetPath.trim() === "")
+            return;
+        const planFilePath = this.container
+            .get("PermissionManager")
+            ?.getPlanFilePath();
+        if (!planFilePath)
+            return;
+        if (path.resolve(targetPath) !== path.resolve(planFilePath))
+            return;
+        try {
+            const content = await readFile(planFilePath, "utf8");
+            this.callbacks?.onPlanFileUpdated?.(content);
+        }
+        catch (error) {
+            logger?.warn(`Failed to read plan file for panel refresh: ${planFilePath}`, error);
+        }
+    }
     /**
      * Execute PreToolUse hooks before tool execution
      * Returns true if hooks allow tool execution, false if blocked

package/dist/managers/backgroundTaskManager.js

@@ -3,6 +3,7 @@ import * as os from "os";
 import * as fs from "fs";
 import * as path from "path";
 import { stripAnsiColors } from "../utils/stringUtils.js";
+import { readTailTextSync } from "../utils/fileUtils.js";
 import { WindowsStreamDecoder } from "../utils/encoding.js";
 import { logger } from "../utils/globalLogger.js";
 import { resolveShellPath } from "../utils/shellResolver.js";
@@ -386,6 +387,19 @@ export class BackgroundTaskManager {
         }
         let stdout = task.stdout;
         let stderr = task.stderr;
+        // A running agent task keeps its tool-call log in `outputPath` while
+        // `stdout` stays empty until the terminal snapshot fills it (see
+        // SubagentManager) — so /tasks shows an empty output block for the whole
+        // run. Fall back to the log file tail to surface live progress.
+        //
+        // Only when the in-memory buffer is empty, and only while running: shell
+        // tasks accumulate stdout chunk by chunk (that buffer is authoritative and
+        // identical to the file), so reading the file on top of it would duplicate
+        // the text; once a task reaches a terminal state the snapshot already
+        // carries the final output.
+        if (!stdout && task.status === "running" && task.outputPath) {
+            stdout = stripAnsiColors(readTailTextSync(task.outputPath));
+        }
         // Apply regex filter if provided
         if (filter) {
             try {

package/dist/managers/hookManager.d.ts

@@ -13,6 +13,12 @@ export declare class HookManager {
     private container;
     private configuration;
     private programmaticHooks;
+    /**
+     * Plugin hooks grouped by plugin root path. A map rather than one merged
+     * object because mergeHooksConfiguration only appends — a flat object can
+     * never be reversed, so the in-place plugin reload path could not drop
+     * exactly one plugin's hooks (and re-registering would double them).
+     */
     private pluginHooks;
     private waveConfigHooks;
     private readonly matcher;
@@ -120,6 +126,13 @@ export declare class HookManager {
      * Register hooks provided by a plugin
      */
     registerPluginHooks(pluginRoot: string, hooks: PartialHookConfiguration): void;
+    /**
+     * Drop every hook contributed by a plugin, addressed by its root path.
+     * Used by the in-place plugin reload path (before re-registering) and when a
+     * plugin is disabled or uninstalled.
+     * @returns true if this root had hooks registered
+     */
+    unregisterPluginHooks(pluginRoot: string): boolean;
     /**
      * Get hooks registered by plugins (read-only view for the settings UI).
      * Plugin hooks carry pluginRoot on each command and are read-only in the UI.

package/dist/managers/hookManager.js

@@ -13,7 +13,13 @@ export class HookManager {
     constructor(container, workdir, matcher = new HookMatcher()) {
         this.container = container;
         this.programmaticHooks = {};
-        this.pluginHooks = {};
+        /**
+         * Plugin hooks grouped by plugin root path. A map rather than one merged
+         * object because mergeHooksConfiguration only appends — a flat object can
+         * never be reversed, so the in-place plugin reload path could not drop
+         * exactly one plugin's hooks (and re-registering would double them).
+         */
+        this.pluginHooks = new Map();
         this.waveConfigHooks = {};
         this.workdir = workdir;
         this.matcher = matcher;
@@ -78,7 +84,9 @@ export class HookManager {
     rebuildConfiguration() {
         const rebuilt = {};
         this.mergeHooksConfiguration(rebuilt, this.programmaticHooks);
-        this.mergeHooksConfiguration(rebuilt, this.pluginHooks);
+        for (const hooks of this.pluginHooks.values()) {
+            this.mergeHooksConfiguration(rebuilt, hooks);
+        }
         this.mergeHooksConfiguration(rebuilt, this.waveConfigHooks);
         this.configuration = Object.keys(rebuilt).length > 0 ? rebuilt : undefined;
     }
@@ -667,15 +675,34 @@ export class HookManager {
                 hooks: config.hooks.map((cmd) => ({ ...cmd, pluginRoot })),
             }));
         }
-        this.mergeHooksConfiguration(this.pluginHooks, stampedHooks);
+        // Replace (not append) the previous registration for this root, so
+        // re-registering the same plugin never doubles its hooks.
+        this.pluginHooks.set(pluginRoot, stampedHooks);
         this.rebuildConfiguration();
     }
+    /**
+     * Drop every hook contributed by a plugin, addressed by its root path.
+     * Used by the in-place plugin reload path (before re-registering) and when a
+     * plugin is disabled or uninstalled.
+     * @returns true if this root had hooks registered
+     */
+    unregisterPluginHooks(pluginRoot) {
+        const removed = this.pluginHooks.delete(pluginRoot);
+        if (removed) {
+            this.rebuildConfiguration();
+        }
+        return removed;
+    }
     /**
      * Get hooks registered by plugins (read-only view for the settings UI).
      * Plugin hooks carry pluginRoot on each command and are read-only in the UI.
      */
     getPluginHooks() {
-        return this.pluginHooks;
+        const merged = {};
+        for (const hooks of this.pluginHooks.values()) {
+            this.mergeHooksConfiguration(merged, hooks);
+        }
+        return merged;
     }
     /**
      * Execute SessionStart hooks during initialization.

package/dist/managers/liveConfigManager.d.ts

@@ -6,6 +6,7 @@
  * - Configuration file watching for settings.json files
  * - Coordination between file watchers and configuration updates
  */
+import type { TurnConfigurationSnapshot } from "../services/configurationService.js";
 import { Container } from "../utils/container.js";
 import type { WaveConfiguration } from "../types/configuration.js";
 export interface LiveConfigManagerOptions {
@@ -19,6 +20,8 @@ export declare class LiveConfigManager {
     private isInitialized;
     private currentConfiguration;
     private lastValidConfiguration;
+    private turnSnapshot;
+    private turnDepth;
     private fileWatcher;
     private userConfigPaths?;
     private projectConfigPaths?;
@@ -28,6 +31,15 @@ export declare class LiveConfigManager {
     private get hookManager();
     private get permissionManager();
     private get configurationService();
+    private get memoryService();
+    /**
+     * Keep the auto-memory system safe zone in sync with the live auto-memory
+     * toggle (core/agent-config.md scenario 6). Turning auto-memory off must
+     * revoke the privilege its directory got at construction time, and turning it
+     * back on must restore it — both without rebuilding the session. Idempotent:
+     * the underlying add/remove are dedup'ed by path.
+     */
+    private syncAutoMemorySafeZone;
     /**
      * Initialize configuration watching
      * Maps to FR-004: System MUST watch settings.json files
@@ -46,6 +58,19 @@ export declare class LiveConfigManager {
      * Shutdown configuration management and cleanup resources
      */
     shutdown(): Promise<void>;
+    /**
+     * Turn boundary: pin the settings.json-derived configuration for the duration
+     * of a turn (called by AIManager). A live reload may land mid-turn and the
+     * turn must not see it (core/agent-config.md scenario 5) — the change is
+     * picked up by the snapshot taken when the next turn starts. Permission rules,
+     * hooks and env stay live: those are enforcement state and follow the file
+     * immediately.
+     */
+    onTurnStart(): void;
+    /** Turn boundary: drop the snapshot so the next turn reads live values. */
+    onTurnEnd(): void;
+    /** Configuration snapshot of the running turn, or null outside a turn. */
+    getTurnSnapshot(): TurnConfigurationSnapshot | null;
     /**
      * Reload configuration from files
      * Maps to FR-008: Continue with previous valid configuration on errors
@@ -77,6 +102,14 @@ export declare class LiveConfigManager {
     private setupFileWatcherEvents;
     private handleFileChange;
     private detectChanges;
+    /**
+     * Chokidar only starts watching a non-existent path when its parent directory
+     * exists at watch time (a path whose parents are all missing is never
+     * picked up, not even after they appear). Walk up to the deepest node whose
+     * parent exists and watch that instead — events for its descendants still
+     * reach this path's callback (FileWatcherService matches by path prefix).
+     */
+    private resolveWatchTarget;
     /**
      * Get configuration file paths for user and project settings
      * Returns paths in priority order (local.json first, then .json)