wave-agent-sdk 1.1.3 → 1.1.5

package/dist/agent.d.ts

@@ -31,6 +31,8 @@ export declare class Agent {
     private taskManager;
     private foregroundTaskManager;
     private container;
+    /** Unregister module-level listeners registered during container setup; invoked at the end of destroy(). */
+    private teardown;
     private configurationService;
     private workdir;
     private systemPrompt?;

package/dist/agent.js

@@ -56,6 +56,8 @@ export class Agent {
         this.isAborting = false; // Transient guard: prevents tryDispatch from firing during abortMessage (reset when the abort completes)
         this.isDestroyed = false; // Terminal guard: set in destroy(), never reset — no dispatch may ever start after destroy
         this.dispatchAborted = false; // Set on abort while a dispatch is running: suppress the .finally re-check so preserved notifications don't get dispatched after abort
+        /** Unregister module-level listeners registered during container setup; invoked at the end of destroy(). */
+        this.teardown = () => { };
         this.sessionStartTime = Date.now();
         const { logger, workdir, systemPrompt, stream = true } = options;
         // Set working directory early as we need it for loading configuration
@@ -68,7 +70,7 @@ export class Agent {
         this.stream = stream; // Save streaming mode flag
         // Store options for dynamic configuration resolution
         this.options = options;
-        this.container = setupAgentContainer({
+        const { container, teardown } = setupAgentContainer({
             options,
             workdir: this.workdir,
             configurationService: this.configurationService,
@@ -92,6 +94,8 @@ export class Agent {
             addPermissionRule: (rule) => this.addPermissionRule(rule),
             addUsage: (usage) => this.messageManager.addUsage(usage),
         });
+        this.container = container;
+        this.teardown = teardown;
         // Retrieve managers from container
         this.foregroundTaskManager = this.container.get("ForegroundTaskManager");
         this.memoryRuleManager = this.container.get("MemoryRuleManager");
@@ -717,6 +721,14 @@ export class Agent {
         if (!drained) {
             this.logger?.error(`Async work did not drain: ${this.asyncWorkRegistry.size} live work item(s) remain after destroy`);
         }
+        // Unregister module-level listeners (remote settings hot-update, auth
+        // change) so the agent's object graph becomes collectable. Without this,
+        // the module-level callback arrays pin every created agent via the
+        // per-agent closure contexts, even after the host drops its references.
+        this.teardown();
+        // Break the DI container's internal references (services/factories) so no
+        // per-agent manager is retained through it after destroy.
+        this.container.clear();
     }
     /**
      * Trigger the rewind UI callback

package/dist/builtin/plugins.js

@@ -41,6 +41,9 @@ const guidance = [
   "- 边界模糊时也先写 spec 草稿请用户确认，不要直接改代码。",
   "- 规格编写技能（specify）由 AI 自动触发：对话中涉及新需求或需求变更时主动创建或更新规格文件，不需要用户手动调用（不出现在斜杠命令列表中）。",
   \`- 新增或修改 spec 后运行校验：\${specCount}（自动检测 docs/specs/，否则 specs/，否则退出）。\`,
+  "- 阶段衔接一律用 AskUserQuestion 单选让用户点击决策，不要求自然语言：spec 确认（确认通过/需要修改）、是否制作原型、是否制定技术方案（plan）均通过单选推进。",
+  "- 可选原型阶段（在规格之后、plan 之前）：仅实现前端界面，数据全部使用 mock；可选 plan 阶段：进入 plan 模式制定技术方案，批准后再编码。二者均可跳过——最短流程=规格+编码，最长=规格+原型+plan+编码。仅当需求涉及前端界面时才询问是否制作原型，无前端界面的需求（后端服务、CLI、算法库等）直接跳过原型询问。",
+  "- 用 task 工具追踪进度：规格、原型、plan、编码各阶段开始前用 TaskCreate 创建任务并标记进行中（TaskUpdate），完成/批准/确认后标记完成，让用户在任务列表中看到当前所处阶段。",
 ].join("\\n");
 
 // JSON form → parsed as hookSpecificOutput.additionalContext by the hook manager.
@@ -128,7 +131,7 @@ if (warnings.length) {
 `,
     "plugins/sdd/skills/specify/SKILL.md": `---
 name: specify
-description: 根据自然语言描述创建或更新功能规格说明，生成包含用户故事与验收场景的规格文件。
+description: 根据自然语言描述创建或更新功能规格说明，并通过单选衔接可选原型、技术方案（plan）与编码阶段。
 user-invocable: false
 ---
 
@@ -144,6 +147,8 @@ $ARGUMENTS
 
 根据对话中的功能描述，执行以下步骤：
 
+0. **创建进度任务**：用 TaskCreate 创建「编写功能规格」任务，并用 TaskUpdate 标记进行中。后续每个阶段（原型、plan、编码）同样在开始前创建任务、结束后更新状态，让用户在任务列表中看到当前进度。
+
 1. **确定规格文件路径**：
    - **确定规格根目录**：优先复用项目中已有的规格目录——若 \`docs/specs/\` 存在则用之，否则若 \`specs/\` 存在则用之，否则默认 \`specs/\`（并在完成报告中说明所选目录，便于用户纠正）。
    - **选择分组**：若规格目录下已有分组子目录，沿用其既有分组约定；否则默认扁平结构（直接放在规格根目录下）。
@@ -165,7 +170,26 @@ $ARGUMENTS
    - 将每个标记作为问题展示，附带建议答案
    - 等待用户回复后更新规格文件
 
-5. 报告完成，输出规格文件路径。
+5. **校验并确认规格**：
+   - 运行会话引导中给出的 spec-count 校验命令（自动检测 docs/specs/，否则 specs/，否则跳过）
+   - 输出规格文件路径，并通过 AskUserQuestion 单选请求确认（选项：确认通过 / 需要修改）
+   - 选「需要修改」→ 按用户反馈更新规格后重新校验，并再次单选确认；选「确认通过」→ 将「编写功能规格」任务标记完成
+
+6. **询问是否制作原型（可选阶段，位于规格之后、plan 之前）**：
+   - 仅当需求涉及前端界面时弹出询问；需求不涉及前端界面（如后端服务、CLI 工具、算法库）时，跳过本阶段直接进入下一步，不弹出原型选择
+   - 通过 AskUserQuestion 单选询问（选项：制作原型 / 跳过）
+   - 选「制作原型」→ 用 TaskCreate 创建「制作原型」任务并标记进行中；仅实现前端界面，数据全部使用 mock（不接后端、不接真实数据）；完成后展示可交互原型供用户查看，并将任务标记完成
+   - 选「跳过」→ 直接进入下一步
+
+7. **询问是否制定技术方案（可选 plan 阶段）**：
+   - 通过 AskUserQuestion 单选询问（选项：进入 plan 模式 / 跳过）
+   - 选「进入 plan 模式」→ 用 TaskCreate 创建「制定技术方案」任务并标记进行中；调用 EnterPlanMode 进入 plan 模式，制定技术方案（技术选型、架构设计、实现步骤）并写入计划文件；用 ExitPlanMode 请求批准——被拒绝则按反馈更新方案后重新请求，批准后标记任务完成
+   - 选「跳过」→ 直接进入下一步
+
+8. **编码阶段**：
+   - 用 TaskCreate 创建「实现功能」任务并标记进行中
+   - 按已确认的规格实现；若制作了原型则遵循其交互设计，若批准了技术方案则遵循其架构
+   - 实现完成后将任务标记完成
 
 ## 指南
 

package/dist/builtin/skills/settings.js

@@ -164,9 +164,13 @@ Wave provides detailed context to hook processes via \`stdin\` as a JSON object.
 - \`new_cwd\`: (CwdChanged) The new working directory.
 - \`compact_instructions\`: (PreCompact) Custom instructions for the compaction, if any.
 - \`compact_summary\`: (PostCompact) The AI-generated compaction summary text.
-- \`source\`: (SessionStart) The session start source: \`"startup"\`, \`"resume"\`, or \`"compact"\`.
+- \`background_tasks\`: (Stop) Snapshot of running background tasks (array of \`{id, type: "shell"|"subagent"|"workflow", status, description, command?, startedAt}\`).
+- \`session_crons\`: (Stop) Snapshot of session-scoped cron jobs (array of \`{name, schedule, prompt}\`).
+- \`last_assistant_message\`: (Stop, SubagentStop) Text content of the last assistant message.
+- \`plan_file_path\`: (Present when in plan mode) Path to the active plan file.
+- \`source\`: (SessionStart) The session start source: \`"startup"\`, \`"resume"\`, \`"compact"\`, or \`"clear"\`.
 - \`agent_type\`: (SessionStart) The agent type identifier.
-- \`end_source\`: (SessionEnd) The session end source: \`"exit"\`, \`"stop"\`, or \`"compact"\`.
+- \`end_source\`: (SessionEnd) The session end source: \`"exit"\`, \`"resume"\`, \`"stop"\`, \`"compact"\`, or \`"clear"\`.
 
 ## Hook Exit Codes
 
@@ -1049,6 +1053,7 @@ For detailed guidance on creating plugins and marketplaces, see [PLUGINS.md](\${
 - \`autoMemoryEnabled\`: Enable or disable auto-memory (default: \`true\`).
 - \`autoMemoryFrequency\`: Frequency of auto-memory extraction turns (default: \`1\`).
 - \`enableArtifact\`: Enable the Artifact tool, which publishes local \`.html\`/\`.md\` files as shareable (default-private) web pages. Defaults to \`false\` while the frame backend is not live; set to \`true\` to register the tool and enable WebFetch interception for artifact URLs. Toggling it hot-reloads the tool registry.
+- \`worktree.baseRef\`: Base ref for new worktrees. \`"fresh"\` (default) creates a new branch from \`origin/<default branch>\`; \`"head"\` branches from the current local HEAD, skipping origin resolution and network fetch. Use \`"head"\` when working from un-pushed local branches.
 
 \`\`\`json
 {

package/dist/managers/aiManager.js

@@ -1353,6 +1353,9 @@ ${question}`;
                     // Add streaming callbacks only if streaming is enabled
                     if (this.stream) {
                         callAgentOptions.onContentUpdate = (content) => {
+                            // Agent may have been destroyed mid-stream; ignore in-flight updates.
+                            if (!this.messageManager)
+                                return;
                             // Create assistant message on first chunk if not already created
                             if (!assistantMessageCreated) {
                                 this.messageManager.addAssistantMessage();
@@ -1361,6 +1364,9 @@ ${question}`;
                             this.messageManager.updateCurrentMessageContent(content);
                         };
                         callAgentOptions.onToolUpdate = (toolCall) => {
+                            // Agent may have been destroyed mid-stream; ignore in-flight updates.
+                            if (!this.messageManager)
+                                return;
                             // Create assistant message on first tool update if not already created
                             if (!assistantMessageCreated) {
                                 this.messageManager.addAssistantMessage();
@@ -1383,6 +1389,9 @@ ${question}`;
                             });
                         };
                         callAgentOptions.onReasoningUpdate = (reasoning) => {
+                            // Agent may have been destroyed mid-stream; ignore in-flight updates.
+                            if (!this.messageManager)
+                                return;
                             // Create assistant message on first reasoning update if not already created
                             if (!assistantMessageCreated) {
                                 this.messageManager.addAssistantMessage();

package/dist/managers/permissionManager.js

@@ -10,6 +10,7 @@ import { minimatch } from "minimatch";
 import { RESTRICTED_TOOLS } from "../types/permissions.js";
 import { splitBashCommand, stripEnvVars, stripRedirections, hasWriteRedirections, getSmartPrefix, isDangerousFind, hasCommandSubstitution, hasProcessSubstitution, hasSedInPlace, stripGitScopePrefix, DANGEROUS_COMMANDS, READ_ONLY_COMMANDS, } from "../utils/bashParser.js";
 import { isPathInside } from "../utils/pathSafety.js";
+import { toWindowsPath } from "../utils/path.js";
 import { BASH_TOOL_NAME, EDIT_TOOL_NAME, WRITE_TOOL_NAME, READ_TOOL_NAME, ASK_USER_QUESTION_TOOL_NAME, } from "../constants/tools.js";
 const DEFAULT_ALLOWED_RULES = [
     "Bash(git status*)",
@@ -286,29 +287,37 @@ export class PermissionManager {
      */
     isInsideSafeZone(targetPath, workdir) {
         const effectiveWorkdir = this.workdir || workdir;
+        // Convert MSYS/git-bash style paths (/c/Users/...) to native Windows form
+        // so `cd /c/...` and file args resolve correctly on win32 instead of
+        // becoming bogus C:\c\... paths that never match the Safe Zone.
+        const normalizedTarget = toWindowsPath(targetPath);
+        const normalizedWorkdir = effectiveWorkdir
+            ? toWindowsPath(effectiveWorkdir)
+            : undefined;
         // Resolve the target path relative to effectiveWorkdir if it's not absolute
-        const absolutePath = effectiveWorkdir && !path.isAbsolute(targetPath)
-            ? path.resolve(effectiveWorkdir, targetPath)
-            : path.resolve(targetPath);
+        const absolutePath = normalizedWorkdir && !path.isAbsolute(normalizedTarget)
+            ? path.resolve(normalizedWorkdir, normalizedTarget)
+            : path.resolve(normalizedTarget);
         // Check workdir
-        if (effectiveWorkdir && isPathInside(absolutePath, effectiveWorkdir)) {
+        if (effectiveWorkdir &&
+            isPathInside(absolutePath, toWindowsPath(effectiveWorkdir))) {
             return { isInside: true, resolvedPath: absolutePath };
         }
         // Check additional directories
         for (const dir of this.additionalDirectories) {
-            if (isPathInside(absolutePath, dir)) {
+            if (isPathInside(absolutePath, toWindowsPath(dir))) {
                 return { isInside: true, resolvedPath: absolutePath };
             }
         }
         // Check instance additional directories
         for (const dir of this.instanceAdditionalDirectories) {
-            if (isPathInside(absolutePath, dir)) {
+            if (isPathInside(absolutePath, toWindowsPath(dir))) {
                 return { isInside: true, resolvedPath: absolutePath };
             }
         }
         // Check system additional directories
         for (const dir of this.systemAdditionalDirectories) {
-            if (isPathInside(absolutePath, dir)) {
+            if (isPathInside(absolutePath, toWindowsPath(dir))) {
                 return { isInside: true, resolvedPath: absolutePath };
             }
         }

package/dist/services/MarketplaceService.js

@@ -4,7 +4,7 @@ import * as crypto from "crypto";
 import { getPluginsDir } from "../utils/configPaths.js";
 import { GitService } from "./GitService.js";
 import { ConfigurationService } from "./configurationService.js";
-import { logger } from "../utils/globalLogger.js";
+import { logger, logError, logWarn } from "../utils/globalLogger.js";
 /**
  * Marketplace Service
  *
@@ -270,7 +270,7 @@ export class MarketplaceService {
             return JSON.parse(content);
         }
         catch (error) {
-            console.error("Failed to load installed plugins:", error);
+            logError("Failed to load installed plugins:", error);
             return { plugins: [] };
         }
     }
@@ -513,7 +513,7 @@ export class MarketplaceService {
                     if (marketplace.source.source === "github" ||
                         marketplace.source.source === "git") {
                         if (!isGitAvailable) {
-                            console.warn(`Skipping update for Git/GitHub marketplace "${marketplace.name}" because Git is not installed.`);
+                            logWarn(`Skipping update for Git/GitHub marketplace "${marketplace.name}" because Git is not installed.`);
                             continue;
                         }
                         const targetPath = this.getMarketplacePath(marketplace.source);
@@ -548,7 +548,7 @@ export class MarketplaceService {
                                     await this.uninstallPlugin(`${plugin.name}@${plugin.marketplace}`, plugin.projectPath);
                                 }
                                 catch (error) {
-                                    console.error(`Failed to uninstall orphaned plugin "${plugin.name}" from marketplace "${marketplace.name}":`, error);
+                                    logError(`Failed to uninstall orphaned plugin "${plugin.name}" from marketplace "${marketplace.name}":`, error);
                                 }
                                 continue;
                             }
@@ -556,14 +556,14 @@ export class MarketplaceService {
                                 await this.installPlugin(`${plugin.name}@${plugin.marketplace}`, plugin.projectPath);
                             }
                             catch (error) {
-                                console.error(`Failed to update plugin "${plugin.name}" from marketplace "${marketplace.name}":`, error);
+                                logError(`Failed to update plugin "${plugin.name}" from marketplace "${marketplace.name}":`, error);
                             }
                         }
                     }
                 }
                 catch (error) {
                     const msg = `Failed to update marketplace "${marketplace.name}": ${error instanceof Error ? error.message : String(error)}`;
-                    console.error(msg);
+                    logError(msg);
                     errors.push(msg);
                 }
             }
@@ -588,7 +588,7 @@ export class MarketplaceService {
                     });
                 }
                 catch (error) {
-                    console.error(`Auto-update failed for marketplace "${marketplaceName}":`, error);
+                    logError(`Auto-update failed for marketplace "${marketplaceName}":`, error);
                 }
             }
         });

package/dist/services/configurationService.d.ts

@@ -8,6 +8,12 @@ import type { ConfigurationLoadResult, ValidationResult, ConfigurationPaths, Wav
 import { type EnvironmentValidationResult, type MergedEnvironmentContext, type EnvironmentMergeOptions } from "../types/environment.js";
 import { GatewayConfig, ModelConfig, PermissionMode, AgentOptions } from "../types/index.js";
 import { ClientOptions } from "openai";
+/**
+ * Validate a configuration object's structure and values. Module-level so it
+ * can be reused without instantiating ConfigurationService (e.g. background
+ * session cleanup runs before config is loaded).
+ */
+export declare function validateConfigurationObject(config: WaveConfiguration): ValidationResult;
 /**
  * Default ConfigurationService implementation
  *

package/dist/services/configurationService.js

@@ -17,6 +17,175 @@ import { getRemoteSettingsSync, mergeRemoteSettings, } from "./remoteSettingsSer
 import { createAuthAwareFetch } from "./authService.js";
 import { ensureWaveRuntimeFilesExcluded } from "../utils/gitUtils.js";
 import { atomicWriteFile } from "../utils/atomicWrite.js";
+/**
+ * Validate a configuration object's structure and values. Module-level so it
+ * can be reused without instantiating ConfigurationService (e.g. background
+ * session cleanup runs before config is loaded).
+ */
+export function validateConfigurationObject(config) {
+    const result = {
+        isValid: true,
+        errors: [],
+        warnings: [],
+    };
+    // Validate basic structure
+    if (!config || typeof config !== "object") {
+        result.isValid = false;
+        result.errors.push("Configuration must be a valid object");
+        return result;
+    }
+    // Validate hooks if present
+    if (config.hooks !== undefined) {
+        if (typeof config.hooks !== "object" || config.hooks === null) {
+            result.isValid = false;
+            result.errors.push("Hooks configuration must be an object");
+        }
+        else {
+            for (const [event, eventConfigs] of Object.entries(config.hooks)) {
+                if (!isValidHookEvent(event)) {
+                    result.warnings.push(`Unknown hook event: ${event}`);
+                    continue;
+                }
+                if (!Array.isArray(eventConfigs)) {
+                    result.isValid = false;
+                    result.errors.push(`Hook event '${event}' must be an array`);
+                    continue;
+                }
+                // Validate individual hook configurations
+                for (let i = 0; i < eventConfigs.length; i++) {
+                    const hookConfig = eventConfigs[i];
+                    if (!hookConfig || typeof hookConfig !== "object") {
+                        result.isValid = false;
+                        result.errors.push(`Hook configuration ${i} for event '${event}' must be an object`);
+                    }
+                }
+            }
+        }
+    }
+    // Validate enabledPlugins if present
+    if (config.enabledPlugins !== undefined) {
+        if (typeof config.enabledPlugins !== "object" ||
+            config.enabledPlugins === null) {
+            result.isValid = false;
+            result.errors.push("enabledPlugins configuration must be an object");
+        }
+        else {
+            for (const [pluginId, enabled] of Object.entries(config.enabledPlugins)) {
+                if (typeof enabled !== "boolean") {
+                    result.isValid = false;
+                    result.errors.push(`Value for plugin '${pluginId}' in enabledPlugins must be a boolean`);
+                }
+                if (!pluginId.includes("@")) {
+                    result.warnings.push(`Plugin ID '${pluginId}' in enabledPlugins should follow 'name@marketplace' format`);
+                }
+            }
+        }
+    }
+    // Validate environment variables if present
+    if (config.env !== undefined) {
+        const envValidation = validateEnvironmentConfig(config.env);
+        if (!envValidation.isValid) {
+            result.isValid = false;
+            result.errors.push(...envValidation.errors);
+        }
+        result.warnings.push(...envValidation.warnings);
+    }
+    // Validate permissions if present
+    if (config.permissions !== undefined) {
+        if (typeof config.permissions !== "object" || config.permissions === null) {
+            result.isValid = false;
+            result.errors.push("Permissions configuration must be an object");
+        }
+        else {
+            // Validate allow if present
+            if (config.permissions.allow !== undefined) {
+                if (!Array.isArray(config.permissions.allow)) {
+                    result.isValid = false;
+                    result.errors.push("Permissions allow must be an array of strings");
+                }
+                else if (!config.permissions.allow.every((rule) => typeof rule === "string")) {
+                    result.isValid = false;
+                    result.errors.push("All permission allow rules must be strings");
+                }
+            }
+            // Validate deny if present
+            if (config.permissions.deny !== undefined) {
+                if (!Array.isArray(config.permissions.deny)) {
+                    result.isValid = false;
+                    result.errors.push("Permissions deny must be an array of strings");
+                }
+                else if (!config.permissions.deny.every((rule) => typeof rule === "string")) {
+                    result.isValid = false;
+                    result.errors.push("All permission deny rules must be strings");
+                }
+            }
+            // Validate permissionMode if present
+            if (config.permissions.permissionMode !== undefined) {
+                const validModes = [
+                    "default",
+                    "bypassPermissions",
+                    "acceptEdits",
+                    "plan",
+                    "dontAsk",
+                ];
+                if (!validModes.includes(config.permissions.permissionMode)) {
+                    result.isValid = false;
+                    result.errors.push(`Invalid permissionMode: "${config.permissions.permissionMode}". Must be one of: ${validModes.join(", ")}`);
+                }
+            }
+        }
+    }
+    // Validate autoMemoryEnabled if present
+    if (config.autoMemoryEnabled !== undefined &&
+        typeof config.autoMemoryEnabled !== "boolean") {
+        result.isValid = false;
+        result.errors.push("autoMemoryEnabled configuration must be a boolean");
+    }
+    // Validate autoMemoryFrequency if present
+    if (config.autoMemoryFrequency !== undefined &&
+        (typeof config.autoMemoryFrequency !== "number" ||
+            config.autoMemoryFrequency <= 0)) {
+        result.isValid = false;
+        result.errors.push("autoMemoryFrequency configuration must be a positive number");
+    }
+    // Validate cleanupPeriodDays if present
+    if (config.cleanupPeriodDays !== undefined &&
+        (typeof config.cleanupPeriodDays !== "number" ||
+            !Number.isInteger(config.cleanupPeriodDays) ||
+            config.cleanupPeriodDays < 0)) {
+        result.isValid = false;
+        result.errors.push("cleanupPeriodDays configuration must be a non-negative integer");
+    }
+    // Validate models if present
+    if (config.models !== undefined) {
+        if (typeof config.models !== "object" || config.models === null) {
+            result.isValid = false;
+            result.errors.push("models configuration must be an object");
+        }
+        else {
+            for (const [modelName, modelConfig] of Object.entries(config.models)) {
+                if (typeof modelConfig !== "object" || modelConfig === null) {
+                    result.isValid = false;
+                    result.errors.push(`Configuration for model '${modelName}' must be an object`);
+                }
+            }
+        }
+    }
+    // Validate worktree if present
+    if (config.worktree !== undefined) {
+        if (typeof config.worktree !== "object" || config.worktree === null) {
+            result.isValid = false;
+            result.errors.push("worktree configuration must be an object");
+        }
+        else if (config.worktree.baseRef !== undefined &&
+            config.worktree.baseRef !== "fresh" &&
+            config.worktree.baseRef !== "head") {
+            result.isValid = false;
+            result.errors.push(`Invalid worktree.baseRef: "${config.worktree.baseRef}". Must be "fresh" or "head".`);
+        }
+    }
+    return result;
+}
 /**
  * Default ConfigurationService implementation
  *
@@ -120,161 +289,7 @@ export class ConfigurationService {
      * Validate configuration object structure and values
      */
     validateConfiguration(config) {
-        const result = {
-            isValid: true,
-            errors: [],
-            warnings: [],
-        };
-        // Validate basic structure
-        if (!config || typeof config !== "object") {
-            result.isValid = false;
-            result.errors.push("Configuration must be a valid object");
-            return result;
-        }
-        // Validate hooks if present
-        if (config.hooks !== undefined) {
-            if (typeof config.hooks !== "object" || config.hooks === null) {
-                result.isValid = false;
-                result.errors.push("Hooks configuration must be an object");
-            }
-            else {
-                for (const [event, eventConfigs] of Object.entries(config.hooks)) {
-                    if (!isValidHookEvent(event)) {
-                        result.warnings.push(`Unknown hook event: ${event}`);
-                        continue;
-                    }
-                    if (!Array.isArray(eventConfigs)) {
-                        result.isValid = false;
-                        result.errors.push(`Hook event '${event}' must be an array`);
-                        continue;
-                    }
-                    // Validate individual hook configurations
-                    for (let i = 0; i < eventConfigs.length; i++) {
-                        const hookConfig = eventConfigs[i];
-                        if (!hookConfig || typeof hookConfig !== "object") {
-                            result.isValid = false;
-                            result.errors.push(`Hook configuration ${i} for event '${event}' must be an object`);
-                        }
-                    }
-                }
-            }
-        }
-        // Validate enabledPlugins if present
-        if (config.enabledPlugins !== undefined) {
-            if (typeof config.enabledPlugins !== "object" ||
-                config.enabledPlugins === null) {
-                result.isValid = false;
-                result.errors.push("enabledPlugins configuration must be an object");
-            }
-            else {
-                for (const [pluginId, enabled] of Object.entries(config.enabledPlugins)) {
-                    if (typeof enabled !== "boolean") {
-                        result.isValid = false;
-                        result.errors.push(`Value for plugin '${pluginId}' in enabledPlugins must be a boolean`);
-                    }
-                    if (!pluginId.includes("@")) {
-                        result.warnings.push(`Plugin ID '${pluginId}' in enabledPlugins should follow 'name@marketplace' format`);
-                    }
-                }
-            }
-        }
-        // Validate environment variables if present
-        if (config.env !== undefined) {
-            const envValidation = validateEnvironmentConfig(config.env);
-            if (!envValidation.isValid) {
-                result.isValid = false;
-                result.errors.push(...envValidation.errors);
-            }
-            result.warnings.push(...envValidation.warnings);
-        }
-        // Validate permissions if present
-        if (config.permissions !== undefined) {
-            if (typeof config.permissions !== "object" ||
-                config.permissions === null) {
-                result.isValid = false;
-                result.errors.push("Permissions configuration must be an object");
-            }
-            else {
-                // Validate allow if present
-                if (config.permissions.allow !== undefined) {
-                    if (!Array.isArray(config.permissions.allow)) {
-                        result.isValid = false;
-                        result.errors.push("Permissions allow must be an array of strings");
-                    }
-                    else if (!config.permissions.allow.every((rule) => typeof rule === "string")) {
-                        result.isValid = false;
-                        result.errors.push("All permission allow rules must be strings");
-                    }
-                }
-                // Validate deny if present
-                if (config.permissions.deny !== undefined) {
-                    if (!Array.isArray(config.permissions.deny)) {
-                        result.isValid = false;
-                        result.errors.push("Permissions deny must be an array of strings");
-                    }
-                    else if (!config.permissions.deny.every((rule) => typeof rule === "string")) {
-                        result.isValid = false;
-                        result.errors.push("All permission deny rules must be strings");
-                    }
-                }
-                // Validate permissionMode if present
-                if (config.permissions.permissionMode !== undefined) {
-                    const validModes = [
-                        "default",
-                        "bypassPermissions",
-                        "acceptEdits",
-                        "plan",
-                        "dontAsk",
-                    ];
-                    if (!validModes.includes(config.permissions.permissionMode)) {
-                        result.isValid = false;
-                        result.errors.push(`Invalid permissionMode: "${config.permissions.permissionMode}". Must be one of: ${validModes.join(", ")}`);
-                    }
-                }
-            }
-        }
-        // Validate autoMemoryEnabled if present
-        if (config.autoMemoryEnabled !== undefined &&
-            typeof config.autoMemoryEnabled !== "boolean") {
-            result.isValid = false;
-            result.errors.push("autoMemoryEnabled configuration must be a boolean");
-        }
-        // Validate autoMemoryFrequency if present
-        if (config.autoMemoryFrequency !== undefined &&
-            (typeof config.autoMemoryFrequency !== "number" ||
-                config.autoMemoryFrequency <= 0)) {
-            result.isValid = false;
-            result.errors.push("autoMemoryFrequency configuration must be a positive number");
-        }
-        // Validate models if present
-        if (config.models !== undefined) {
-            if (typeof config.models !== "object" || config.models === null) {
-                result.isValid = false;
-                result.errors.push("models configuration must be an object");
-            }
-            else {
-                for (const [modelName, modelConfig] of Object.entries(config.models)) {
-                    if (typeof modelConfig !== "object" || modelConfig === null) {
-                        result.isValid = false;
-                        result.errors.push(`Configuration for model '${modelName}' must be an object`);
-                    }
-                }
-            }
-        }
-        // Validate worktree if present
-        if (config.worktree !== undefined) {
-            if (typeof config.worktree !== "object" || config.worktree === null) {
-                result.isValid = false;
-                result.errors.push("worktree configuration must be an object");
-            }
-            else if (config.worktree.baseRef !== undefined &&
-                config.worktree.baseRef !== "fresh" &&
-                config.worktree.baseRef !== "head") {
-                result.isValid = false;
-                result.errors.push(`Invalid worktree.baseRef: "${config.worktree.baseRef}". Must be "fresh" or "head".`);
-            }
-        }
-        return result;
+        return validateConfigurationObject(config);
     }
     /**
      * Validate configuration file without loading
@@ -1078,6 +1093,9 @@ export function loadWaveConfigFromFile(filePath) {
             autoMemoryFrequency: config.autoMemoryFrequency !== undefined
                 ? config.autoMemoryFrequency
                 : undefined,
+            cleanupPeriodDays: config.cleanupPeriodDays !== undefined
+                ? config.cleanupPeriodDays
+                : undefined,
             models: config.models || undefined,
             marketplaces: config.marketplaces || undefined,
             worktree: config.worktree || undefined,
@@ -1216,6 +1234,10 @@ export function loadMergedWaveConfig(workdir) {
         if (config.autoMemoryFrequency !== undefined) {
             mergedConfig.autoMemoryFrequency = config.autoMemoryFrequency;
         }
+        // Merge cleanupPeriodDays (last one wins)
+        if (config.cleanupPeriodDays !== undefined) {
+            mergedConfig.cleanupPeriodDays = config.cleanupPeriodDays;
+        }
         // Merge marketplaces (last one wins for same key)
         if (config.marketplaces) {
             if (!mergedConfig.marketplaces)
@@ -1260,6 +1282,7 @@ export function loadMergedWaveConfig(workdir) {
         language: mergedConfig.language,
         model: mergedConfig.model,
         autoMemoryEnabled: mergedConfig.autoMemoryEnabled,
+        cleanupPeriodDays: mergedConfig.cleanupPeriodDays,
         marketplaces: mergedConfig.marketplaces &&
             Object.keys(mergedConfig.marketplaces).length > 0
             ? mergedConfig.marketplaces

package/dist/services/session.d.ts

@@ -150,13 +150,6 @@ export declare function listAllSessions(options?: {
     worktreePaths?: string[];
     workdir?: string;
 }): Promise<SessionMetadata[]>;
-/**
- * Clean up expired sessions older than 14 days based on file modification time
- *
- * @param workdir - Working directory to clean up sessions for
- * @returns Promise that resolves to the number of sessions that were deleted
- */
-export declare function cleanupExpiredSessionsFromJsonl(workdir: string): Promise<number>;
 /**
  * Clean up empty project directories in the session directory
  */

package/dist/services/session.js

@@ -43,7 +43,6 @@ export function generateSubagentFilename(sessionId) {
 }
 // Constants
 export const SESSION_DIR = join(homedir(), ".wave", "projects");
-const MAX_SESSION_AGE_DAYS = 14;
 /**
  * Ensure session directory exists
  */
@@ -568,59 +567,6 @@ export async function listAllSessions(options) {
         throw new Error(`Failed to list all sessions: ${error}`);
     }
 }
-/**
- * Clean up expired sessions older than 14 days based on file modification time
- *
- * @param workdir - Working directory to clean up sessions for
- * @returns Promise that resolves to the number of sessions that were deleted
- */
-export async function cleanupExpiredSessionsFromJsonl(workdir) {
-    // Do not perform cleanup operations in test environment
-    if (process.env.NODE_ENV === "test") {
-        return 0;
-    }
-    try {
-        const encoder = new PathEncoder();
-        const projectDir = await encoder.getProjectDirectory(workdir, SESSION_DIR);
-        const files = await fs.readdir(projectDir.encodedPath);
-        const now = new Date();
-        const maxAge = MAX_SESSION_AGE_DAYS * 24 * 60 * 60 * 1000; // Convert to milliseconds
-        let deletedCount = 0;
-        for (const file of files) {
-            if (!file.endsWith(".jsonl")) {
-                continue;
-            }
-            const filePath = join(projectDir.encodedPath, file);
-            try {
-                const stat = await fs.stat(filePath);
-                const fileAge = now.getTime() - stat.mtime.getTime();
-                if (fileAge > maxAge) {
-                    await fs.unlink(filePath);
-                    deletedCount++;
-                }
-            }
-            catch {
-                // Skip failed operations and continue processing other files
-                continue;
-            }
-        }
-        // Clean up empty project directory if no files remain
-        try {
-            const remainingFiles = await fs.readdir(projectDir.encodedPath);
-            if (remainingFiles.length === 0) {
-                await fs.rmdir(projectDir.encodedPath);
-            }
-        }
-        catch {
-            // Ignore errors if directory is not empty or can't be removed
-        }
-        return deletedCount;
-    }
-    catch {
-        // Return 0 if project directory doesn't exist or can't be accessed
-        return 0;
-    }
-}
 /**
  * Clean up empty project directories in the session directory
  */
@@ -859,10 +805,6 @@ export async function handleSessionRestoration(restoreSessionId, continueLastSes
     if (!workdir) {
         throw new Error("Working directory is required for session restoration");
     }
-    // Clean up expired sessions first
-    cleanupExpiredSessionsFromJsonl(workdir).catch((error) => {
-        logger.warn("Failed to cleanup expired sessions:", error);
-    });
     if (!restoreSessionId && !continueLastSession) {
         return;
     }

package/dist/types/configuration.d.ts

@@ -57,6 +57,13 @@ export interface WaveConfiguration {
     };
     /** Whether the Artifact tool is enabled. Unset follows the code default constant (ARTIFACT_DEFAULT_ENABLED). */
     enableArtifact?: boolean;
+    /**
+     * Session transcript retention in days (aligned with Claude Code's
+     * cleanupPeriodDays). Session jsonl files in ~/.wave/projects older than
+     * this many days are cleaned up in the background at startup.
+     * Default: 30. 0 disables cleanup entirely.
+     */
+    cleanupPeriodDays?: number;
 }
 /**
  * Legacy alias for backward compatibility - will be deprecated

package/dist/types/core.d.ts

@@ -39,8 +39,8 @@ export interface Change {
 }
 export declare class ConfigurationError extends Error {
     readonly field: string;
-    readonly provided?: unknown | undefined;
-    constructor(message: string, field: string, provided?: unknown | undefined);
+    readonly provided?: unknown;
+    constructor(message: string, field: string, provided?: unknown);
 }
 export declare const CONFIG_ERRORS: {
     readonly MISSING_MODEL: "Agent configuration requires model. Provide via constructor or WAVE_MODEL environment variable.";

package/dist/utils/container.d.ts

@@ -27,4 +27,10 @@ export declare class Container {
      * Check if a service exists
      */
     has(token: string): boolean;
+    /**
+     * Remove all registered services and factories. Call during teardown so the
+     * container does not retain references to per-agent services after the
+     * agent is destroyed (breaking the agent's object graph).
+     */
+    clear(): void;
 }

package/dist/utils/container.js

@@ -52,6 +52,15 @@ export class Container {
             this.factories.has(token) ||
             (this.parent ? this.parent.has(token) : false));
     }
+    /**
+     * Remove all registered services and factories. Call during teardown so the
+     * container does not retain references to per-agent services after the
+     * agent is destroyed (breaking the agent's object graph).
+     */
+    clear() {
+        this.services.clear();
+        this.factories.clear();
+    }
 }
 // Example usage for ToolManager:
 /*

package/dist/utils/containerSetup.d.ts

@@ -16,4 +16,14 @@ export interface AgentContainerSetupOptions {
     addPermissionRule: (rule: string) => Promise<void>;
     addUsage: (usage: Usage) => void;
 }
-export declare function setupAgentContainer(setupOptions: AgentContainerSetupOptions): Container;
+export interface AgentContainerSetupResult {
+    container: Container;
+    /**
+     * Unregister module-level listeners registered during setup (remote settings
+     * hot-update, auth change). Must be called when the agent is destroyed;
+     * without it the module-level callback arrays pin the agent's object graph
+     * (the callback closures capture per-agent managers).
+     */
+    teardown: () => void;
+}
+export declare function setupAgentContainer(setupOptions: AgentContainerSetupOptions): AgentContainerSetupResult;

package/dist/utils/containerSetup.js

@@ -23,6 +23,7 @@ import { SubagentManager } from "../managers/subagentManager.js";
 import { LiveConfigManager } from "../managers/liveConfigManager.js";
 import { ReversionService } from "../services/reversionService.js";
 import { cleanupMetaOnlySessions } from "../services/session.js";
+import { runSessionCleanupInBackground } from "./sessionCleanup.js";
 import { MemoryService } from "../services/memory.js";
 import { AutoMemoryService } from "../services/autoMemoryService.js";
 import { USER_MEMORY_FILE } from "./constants.js";
@@ -37,6 +38,12 @@ export function setupAgentContainer(setupOptions) {
     const container = new Container();
     container.register("AgentOptions", options);
     container.register("Workdir", workdir);
+    // Module-level listener teardowns collected during setup and returned to the
+    // agent, which invokes them in destroy(). The remote-settings callback
+    // strongly captures the per-agent LiveConfigManager: without unsubscribing
+    // it in destroy(), the module-level callback array keeps every created
+    // agent's object graph alive even after the host drops its references.
+    const teardowns = [];
     if (options.worktreeName) {
         container.register("WorktreeName", options.worktreeName);
         container.register("MainRepoRoot", getGitMainRepoRoot(workdir));
@@ -106,14 +113,14 @@ export function setupAgentContainer(setupOptions) {
     });
     container.register("McpManager", mcpManager);
     // Wire up auth change callback to refresh/clear remote settings
-    authService.onAuthChange(async (event) => {
+    teardowns.push(authService.onAuthChange(async (event) => {
         if (event === "login") {
             await remoteSettingsService.refresh();
         }
         else if (event === "logout") {
             remoteSettingsService.clear();
         }
-    });
+    }));
     const lspManager = options.lspManager || new LspManager(container);
     container.register("LspManager", lspManager);
     const permissionManager = new PermissionManager(container, {
@@ -160,6 +167,9 @@ export function setupAgentContainer(setupOptions) {
         .catch((error) => {
         logger.error("Failed to cleanup meta-only session files:", error);
     });
+    // Global session retention cleanup (cleanupPeriodDays, default 30 days).
+    // Once per process; reads settings itself since config isn't loaded yet.
+    runSessionCleanupInBackground(workdir);
     const reversionManager = new ReversionManager(container);
     container.register("ReversionManager", reversionManager);
     const canUseToolWithPermissionRequest = options.canUseTool
@@ -241,9 +251,12 @@ export function setupAgentContainer(setupOptions) {
     container.register("LiveConfigManager", liveConfigManager);
     // Wire up remote settings hot-update: when polling detects changed settings,
     // reload configuration so admin changes propagate to the running agent.
-    remoteSettingsService.onSettingsUpdate(async () => {
+    // The callback strongly captures the per-agent LiveConfigManager, so it MUST
+    // be unsubscribed in destroy() via teardown — otherwise the module-level
+    // callback array pins the whole agent object graph.
+    teardowns.push(remoteSettingsService.onSettingsUpdate(async () => {
         await liveConfigManager.reload();
-    });
+    }));
     const subagentManager = new SubagentManager(container, {
         workdir,
         callbacks: {
@@ -283,5 +296,12 @@ export function setupAgentContainer(setupOptions) {
     cronManager.start();
     const workflowManager = new WorkflowManager(container);
     container.register("WorkflowManager", workflowManager);
-    return container;
+    return {
+        container,
+        teardown: () => {
+            for (const unsubscribe of teardowns) {
+                unsubscribe();
+            }
+        },
+    };
 }

package/dist/utils/globalLogger.d.ts

@@ -85,3 +85,16 @@ export declare const logger: {
      */
     readonly error: (...args: unknown[]) => void;
 };
+/**
+ * Log an error through the channel matching the execution context:
+ * - Interactive terminals (stdout is a TTY) with a configured global logger
+ *   route through the logger (e.g. a log file), keeping the terminal UI clean.
+ * - Non-interactive hosts (stdio pipes, scripts) and contexts without a
+ *   configured logger fall back to stderr via console.error.
+ */
+export declare function logError(...args: unknown[]): void;
+/**
+ * Log a warning through the channel matching the execution context
+ * (see logError for the routing rule).
+ */
+export declare function logWarn(...args: unknown[]): void;

package/dist/utils/globalLogger.js

@@ -118,3 +118,30 @@ export const logger = {
         globalLogger.error(...args);
     },
 };
+/**
+ * Log an error through the channel matching the execution context:
+ * - Interactive terminals (stdout is a TTY) with a configured global logger
+ *   route through the logger (e.g. a log file), keeping the terminal UI clean.
+ * - Non-interactive hosts (stdio pipes, scripts) and contexts without a
+ *   configured logger fall back to stderr via console.error.
+ */
+export function logError(...args) {
+    if (process.stdout.isTTY && isLoggerConfigured()) {
+        logger.error(...args);
+    }
+    else {
+        console.error(...args);
+    }
+}
+/**
+ * Log a warning through the channel matching the execution context
+ * (see logError for the routing rule).
+ */
+export function logWarn(...args) {
+    if (process.stdout.isTTY && isLoggerConfigured()) {
+        logger.warn(...args);
+    }
+    else {
+        console.warn(...args);
+    }
+}

package/dist/utils/sessionCleanup.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Session retention cleanup — aligned with Claude Code's cleanupOldSessionFiles()
+ * (~/.claude-code/src/utils/cleanup.ts).
+ *
+ * Scans ~/.wave/projects for session .jsonl files (main `<uuid>.jsonl` and
+ * `subagent-<uuid>.jsonl`) whose mtime is older than the retention cutoff and
+ * deletes them, then removes project directories left empty. Auto-memory
+ * (`memory/` subdirectories) is never touched.
+ *
+ * Retention is configurable via settings `cleanupPeriodDays` (default 30).
+ * `0` disables cleanup. If settings are corrupt or fail validation while the
+ * user explicitly set `cleanupPeriodDays`, cleanup is skipped entirely — the
+ * same guard Claude Code uses to avoid deleting files when the configured
+ * retention period cannot be trusted.
+ */
+/** Default retention period in days (Claude Code DEFAULT_CLEANUP_PERIOD_DAYS). */
+export declare const DEFAULT_CLEANUP_PERIOD_DAYS = 30;
+export interface SessionCleanupResult {
+    /** Number of session files deleted */
+    deleted: number;
+    /** Number of files/directories that failed to process */
+    errors: number;
+}
+/**
+ * Resolve the effective cleanup period in days, or null to skip cleanup.
+ *
+ * null (skip) happens when:
+ * - settings files exist but cannot be parsed/loaded (corrupt JSON, mid-write)
+ * - settings validation fails AND the user explicitly set cleanupPeriodDays
+ *
+ * Missing settings entirely is NOT a skip: the default 30 days applies.
+ */
+export declare function resolveCleanupPeriodDays(workdir: string): number | null;
+/**
+ * Delete session .jsonl files in ~/.wave/projects older than periodDays,
+ * then remove project directories left empty. Directories that still contain
+ * anything (e.g. `memory/` auto-memory) are preserved. Never throws; errors
+ * are counted and skipped, and a missing/unreadable projects dir is a silent
+ * no-op.
+ */
+export declare function cleanupOldSessionFiles(periodDays: number): Promise<SessionCleanupResult>;
+/**
+ * Kick off session cleanup in the background, once per process. Fire-and-forget:
+ * never throws, never blocks agent startup. In test environments cleanup is a
+ * no-op (same convention as the other startup cleanups in session.ts).
+ */
+export declare function runSessionCleanupInBackground(workdir: string): void;

package/dist/utils/sessionCleanup.js

@@ -0,0 +1,169 @@
+/**
+ * Session retention cleanup — aligned with Claude Code's cleanupOldSessionFiles()
+ * (~/.claude-code/src/utils/cleanup.ts).
+ *
+ * Scans ~/.wave/projects for session .jsonl files (main `<uuid>.jsonl` and
+ * `subagent-<uuid>.jsonl`) whose mtime is older than the retention cutoff and
+ * deletes them, then removes project directories left empty. Auto-memory
+ * (`memory/` subdirectories) is never touched.
+ *
+ * Retention is configurable via settings `cleanupPeriodDays` (default 30).
+ * `0` disables cleanup. If settings are corrupt or fail validation while the
+ * user explicitly set `cleanupPeriodDays`, cleanup is skipped entirely — the
+ * same guard Claude Code uses to avoid deleting files when the configured
+ * retention period cannot be trusted.
+ */
+import { existsSync, promises as fs } from "fs";
+import { join } from "path";
+import { logger } from "./globalLogger.js";
+import { SESSION_DIR } from "../services/session.js";
+import { loadMergedWaveConfig, validateConfigurationObject, } from "../services/configurationService.js";
+import { getProjectConfigPaths, getUserConfigPaths } from "./configPaths.js";
+/** Default retention period in days (Claude Code DEFAULT_CLEANUP_PERIOD_DAYS). */
+export const DEFAULT_CLEANUP_PERIOD_DAYS = 30;
+// Module-level flag: session cleanup runs once per process, on first agent
+// container setup — aligned with CC's once-per-process startup housekeeping.
+let cleanupScheduled = false;
+/**
+ * Resolve the effective cleanup period in days, or null to skip cleanup.
+ *
+ * null (skip) happens when:
+ * - settings files exist but cannot be parsed/loaded (corrupt JSON, mid-write)
+ * - settings validation fails AND the user explicitly set cleanupPeriodDays
+ *
+ * Missing settings entirely is NOT a skip: the default 30 days applies.
+ */
+export function resolveCleanupPeriodDays(workdir) {
+    let merged;
+    try {
+        merged = loadMergedWaveConfig(workdir);
+    }
+    catch (error) {
+        logger.debug(`Session cleanup: skipping (failed to load settings: ${error.message})`);
+        return null;
+    }
+    // No config file at all → default retention. Config files exist but merged
+    // config is null (corrupt JSON / empty file) → skip conservatively rather
+    // than deleting based on a partial config.
+    if (merged === null) {
+        if (hasAnySettingsFile(workdir)) {
+            logger.debug("Session cleanup: skipping (settings file exists but could not be parsed)");
+            return null;
+        }
+        return DEFAULT_CLEANUP_PERIOD_DAYS;
+    }
+    // Guard (CC): validation errors + explicit cleanupPeriodDays → skip entirely.
+    const validation = validateConfigurationObject(merged);
+    if (validation.errors.length > 0 && merged.cleanupPeriodDays !== undefined) {
+        logger.debug("Session cleanup: skipping (settings have validation errors but cleanupPeriodDays was explicitly set). Fix settings errors to enable cleanup.");
+        return null;
+    }
+    return merged.cleanupPeriodDays ?? DEFAULT_CLEANUP_PERIOD_DAYS;
+}
+/**
+ * Delete session .jsonl files in ~/.wave/projects older than periodDays,
+ * then remove project directories left empty. Directories that still contain
+ * anything (e.g. `memory/` auto-memory) are preserved. Never throws; errors
+ * are counted and skipped, and a missing/unreadable projects dir is a silent
+ * no-op.
+ */
+export async function cleanupOldSessionFiles(periodDays) {
+    const result = { deleted: 0, errors: 0 };
+    const cutoffDate = new Date(Date.now() - periodDays * 24 * 60 * 60 * 1000);
+    let projectEntries;
+    try {
+        projectEntries = await fs.readdir(SESSION_DIR, { withFileTypes: true });
+    }
+    catch {
+        // Projects dir doesn't exist or is unreadable — nothing to clean
+        return result;
+    }
+    for (const projectEntry of projectEntries) {
+        if (!projectEntry.isDirectory())
+            continue;
+        const projectDir = join(SESSION_DIR, projectEntry.name);
+        let entries;
+        try {
+            entries = await fs.readdir(projectDir, { withFileTypes: true });
+        }
+        catch {
+            result.errors++;
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isFile() || !entry.name.endsWith(".jsonl"))
+                continue;
+            try {
+                if (await unlinkIfOld(join(projectDir, entry.name), cutoffDate)) {
+                    result.deleted++;
+                }
+            }
+            catch {
+                result.errors++;
+            }
+        }
+        // Removes the project dir only if it is now empty; dirs still containing
+        // files (e.g. memory/) or subdirectories are left untouched.
+        await tryRmdir(projectDir);
+    }
+    return result;
+}
+/**
+ * Kick off session cleanup in the background, once per process. Fire-and-forget:
+ * never throws, never blocks agent startup. In test environments cleanup is a
+ * no-op (same convention as the other startup cleanups in session.ts).
+ */
+export function runSessionCleanupInBackground(workdir) {
+    if (process.env.NODE_ENV === "test")
+        return;
+    if (cleanupScheduled)
+        return;
+    cleanupScheduled = true;
+    void (async () => {
+        try {
+            const periodDays = resolveCleanupPeriodDays(workdir);
+            if (periodDays === null) {
+                return; // skip reason already logged in resolveCleanupPeriodDays
+            }
+            if (periodDays === 0) {
+                logger.debug("Session cleanup: disabled (cleanupPeriodDays is 0)");
+                return;
+            }
+            const result = await cleanupOldSessionFiles(periodDays);
+            if (result.deleted > 0) {
+                logger.debug(`Session cleanup: removed ${result.deleted} session file(s)`);
+            }
+            if (result.errors > 0) {
+                logger.warn(`Session cleanup: encountered ${result.errors} error(s) while cleaning session files`);
+            }
+        }
+        catch (error) {
+            logger.warn(`Session cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    })();
+}
+/**
+ * Whether any settings file exists that loadMergedWaveConfig would consider
+ * (user settings.json + project settings.json/local.json).
+ */
+function hasAnySettingsFile(workdir) {
+    const userPaths = getUserConfigPaths();
+    const projectPaths = getProjectConfigPaths(workdir);
+    return [userPaths[0], projectPaths[1], projectPaths[0]].some((p) => existsSync(p));
+}
+async function unlinkIfOld(filePath, cutoffDate) {
+    const stats = await fs.stat(filePath);
+    if (stats.mtime < cutoffDate) {
+        await fs.unlink(filePath);
+        return true;
+    }
+    return false;
+}
+async function tryRmdir(dirPath) {
+    try {
+        await fs.rmdir(dirPath);
+    }
+    catch {
+        // Not empty or doesn't exist
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wave-agent-sdk",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "SDK for building AI-powered development tools and agents",
   "keywords": [
     "ai",
@@ -62,7 +62,6 @@
     "@types/turndown": "^5.0.6",
     "@vitest/coverage-v8": "^4.1.7",
     "rimraf": "^6.1.2",
-    "tsc-alias": "^1.8.16",
     "vitest": "^4.1.7"
   },
   "engines": {
@@ -70,15 +69,15 @@
   },
   "license": "MIT",
   "scripts": {
-    "build": "rimraf dist && tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
+    "build": "rimraf dist && tsc -p tsconfig.build.json",
     "type-check": "tsc --noEmit --incremental",
-    "watch": "tsc -p tsconfig.build.json --watch & tsc-alias -p tsconfig.build.json --watch",
+    "watch": "tsc -p tsconfig.build.json --watch",
     "test": "vitest run --reporter=dot",
     "test:coverage": "vitest run --coverage --reporter=dot",
     "test:unit": "vitest run --reporter=dot --exclude 'tests/integration/**' --exclude '**/*.integration.test.ts'",
     "test:unit:coverage": "vitest run --coverage --reporter=dot --exclude 'tests/integration/**' --exclude '**/*.integration.test.ts'",
     "test:integration": "vitest run --reporter=dot tests/integration .integration.test",
-    "lint": "eslint --cache",
+    "lint": "oxlint",
     "format": "prettier --write ."
   }
 }