wave-agent-sdk 0.19.6 → 0.19.8

package/dist/utils/worktreeSession.d.ts

@@ -5,7 +5,7 @@
  * "WorktreeSession" container slot registered in containerSetup.ts and accessed via
  * AIManager.getWorktreeSession()/setWorktreeSession()). This keeps worktree state
  * isolated per session in stdio multi-agent mode — a process-level singleton would
- * leak state across concurrent sessions (see specs/047-worktree.md FR-042).
+ * leak state across concurrent sessions (see docs/specs/multi-agent/worktree.md FR-042).
  */
 export interface WorktreeSession {
     /** The working directory the session was in before EnterWorktree */
@@ -23,4 +23,3 @@ export interface WorktreeSession {
     /** The HEAD commit of the original branch at worktree creation time */
     originalHeadCommit?: string;
 }
-//# sourceMappingURL=worktreeSession.d.ts.map

package/dist/utils/worktreeSession.js

@@ -5,6 +5,6 @@
  * "WorktreeSession" container slot registered in containerSetup.ts and accessed via
  * AIManager.getWorktreeSession()/setWorktreeSession()). This keeps worktree state
  * isolated per session in stdio multi-agent mode — a process-level singleton would
- * leak state across concurrent sessions (see specs/047-worktree.md FR-042).
+ * leak state across concurrent sessions (see docs/specs/multi-agent/worktree.md FR-042).
  */
 export {};

package/dist/utils/worktreeUtils.d.ts

@@ -25,8 +25,14 @@ export declare function generateWorktreeName(): string;
 export declare function getHeadCommit(cwd: string): string;
 /**
  * Create a git worktree for use during a session.
+ * @param name Worktree name
+ * @param cwd Current working directory (will be resolved to main repo root)
+ * @param options Optional creation options
+ * @param options.baseRef "fresh" (default, origin/<default-branch>) | "head" (local HEAD)
  */
-export declare function createWorktree(name: string, cwd: string): WorktreeInfo;
+export declare function createWorktree(name: string, cwd: string, options?: {
+    baseRef?: "fresh" | "head";
+}): WorktreeInfo;
 /**
  * Remove a git worktree and its branch.
  */
@@ -39,4 +45,3 @@ export declare function countWorktreeChanges(worktreePath: string, originalHeadC
     changedFiles: number;
     commits: number;
 } | null;
-//# sourceMappingURL=worktreeUtils.d.ts.map

package/dist/utils/worktreeUtils.js

@@ -68,8 +68,12 @@ export function getHeadCommit(cwd) {
 }
 /**
  * Create a git worktree for use during a session.
+ * @param name Worktree name
+ * @param cwd Current working directory (will be resolved to main repo root)
+ * @param options Optional creation options
+ * @param options.baseRef "fresh" (default, origin/<default-branch>) | "head" (local HEAD)
  */
-export function createWorktree(name, cwd) {
+export function createWorktree(name, cwd, options) {
     const repoRoot = getGitMainRepoRoot(cwd);
     if (!repoRoot) {
         throw new Error("Cannot create a worktree: not in a git repository. Configure WorktreeCreate and WorktreeRemove hooks in settings.json to use worktree isolation with other VCS systems.");
@@ -78,7 +82,8 @@ export function createWorktree(name, cwd) {
     const originalHeadCommit = getHeadCommit(cwd);
     const worktreePath = path.join(repoRoot, ".wave", "worktrees", name);
     const branchName = `worktree-${name}`;
-    const baseBranch = getDefaultRemoteBranch(cwd);
+    const useHead = options?.baseRef === "head";
+    const baseBranch = useHead ? "HEAD" : getDefaultRemoteBranch(cwd);
     // Ensure Wave runtime files are git-excluded in this repo
     ensureWaveRuntimeFilesExcluded(cwd);
     // Ensure parent directory exists
@@ -144,8 +149,9 @@ export function createWorktree(name, cwd) {
                 throw new Error(`Failed to add worktree: ${innerError.message}`);
             }
         }
-        if (stderr.includes("not a valid object name") ||
-            stderr.includes("unknown revision")) {
+        if (!useHead &&
+            (stderr.includes("not a valid object name") ||
+                stderr.includes("unknown revision"))) {
             // Base branch not fetched yet — try fetching then retrying
             const branchNameOnly = baseBranch.split("/").pop();
             try {

package/dist/workflow/budgetTracker.d.ts

@@ -9,4 +9,3 @@ export declare class BudgetTracker {
     get total(): number | null;
     toBudgetInfo(): import("./types.js").BudgetInfo;
 }
-//# sourceMappingURL=budgetTracker.d.ts.map

package/dist/workflow/concurrencyLimiter.d.ts

@@ -11,4 +11,3 @@ export declare class ConcurrencyLimiter {
     get activeCount(): number;
     get pendingCount(): number;
 }
-//# sourceMappingURL=concurrencyLimiter.d.ts.map

package/dist/workflow/journal.d.ts

@@ -16,4 +16,3 @@ export declare class Journal {
     close(): Promise<void>;
     static load(filePath: string): Promise<Journal>;
 }
-//# sourceMappingURL=journal.d.ts.map

package/dist/workflow/progressReporter.d.ts

@@ -18,4 +18,3 @@ export declare class ProgressReporter {
     onEvent(listener: (event: WorkflowProgressEvent) => void): void;
     private emit;
 }
-//# sourceMappingURL=progressReporter.d.ts.map

package/dist/workflow/runState.d.ts

@@ -13,4 +13,3 @@ export declare class RunStateStore {
     /** List all persisted run IDs */
     listRuns(): Promise<string[]>;
 }
-//# sourceMappingURL=runState.d.ts.map

package/dist/workflow/scriptRuntime.d.ts

@@ -32,4 +32,3 @@ export declare function executeScript(script: string, apis: {
     meta: WorkflowMeta;
     result: unknown;
 }>;
-//# sourceMappingURL=scriptRuntime.d.ts.map

package/dist/workflow/structuredOutput.d.ts

@@ -24,4 +24,3 @@ export declare function extractStructuredResult(messages: Array<{
     }>;
 }>, schema: object): unknown | null;
 export { STRUCTURED_OUTPUT_TOOL_NAME };
-//# sourceMappingURL=structuredOutput.d.ts.map

package/dist/workflow/types.d.ts

@@ -38,6 +38,11 @@ export interface WorkflowRun {
     /** Error message from the failed agent */
     failedAgentError?: string;
 }
+/**
+ * Serializable workflow run for stdio transport, with the non-serializable
+ * `completionPromise` stripped. Returned by the `getWorkflowRuns` RPC.
+ */
+export type SerializableWorkflowRun = Omit<WorkflowRun, "completionPromise">;
 export interface JournalEntry {
     agentIndex: number;
     prompt: string;
@@ -78,4 +83,3 @@ export interface WorkflowProgressEvent {
     agentIndex?: number;
     timestamp: number;
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/workflow/workflowApis.d.ts

@@ -41,4 +41,3 @@ export interface WorkflowApis {
 }
 export declare function createWorkflowApis(ctx: WorkflowApiContext): WorkflowApis;
 export {};
-//# sourceMappingURL=workflowApis.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wave-agent-sdk",
-  "version": "0.19.6",
+  "version": "0.19.8",
   "description": "SDK for building AI-powered development tools and agents",
   "keywords": [
     "ai",

package/src/agent.ts

@@ -10,7 +10,6 @@ import { BangManager } from "./managers/bangManager.js";
 import { CronManager } from "./managers/cronManager.js";
 import { GoalManager } from "./managers/goalManager.js";
 import { BackgroundTaskManager } from "./managers/backgroundTaskManager.js";
-import { NotificationQueue } from "./managers/notificationQueue.js";
 import { MessageQueue, type QueuedMessage } from "./managers/messageQueue.js";
 import { SlashCommandManager } from "./managers/slashCommandManager.js";
 import { PluginManager } from "./managers/pluginManager.js";
@@ -77,9 +76,8 @@ export class Agent {
   private goalManager: GoalManager; // Add goal manager instance
   private hookManager: HookManager; // Add hooks manager instance
   private reversionManager: ReversionManager;
-  private notificationQueue: NotificationQueue; // Add notification queue instance
-  private messageQueue: MessageQueue; // Add message queue instance
-  private pendingNotificationPromises: Promise<void>[] = []; // Track pending notification processing
+  private messageQueue: MessageQueue; // Unified queue for messages, bang commands, and notifications
+  private dispatchPromise: Promise<void> | null = null; // Track current dispatch for teardown
   private memoryRuleManager: MemoryRuleManager; // Add memory rule manager instance
   private liveConfigManager: LiveConfigManager; // Add live configuration manager
   private taskManager: TaskManager;
@@ -207,25 +205,8 @@ export class Agent {
     this.bangManager = this.container.get("BangManager")!;
     this.cronManager = this.container.get("CronManager")!;
     this.goalManager = this.container.get("GoalManager")!;
-    this.notificationQueue = this.container.get("NotificationQueue")!;
     this.messageQueue = this.container.get("MessageQueue")!;
 
-    // Wire up notification queue to trigger AI when notifications arrive while idle
-    this.notificationQueue.onNotificationsEnqueued = () => {
-      // If the AI is NOT loading (idle), trigger a new AI cycle to process notifications
-      if (!this.aiManager.isLoading) {
-        const pendingPromise = this.processPendingNotifications().catch(
-          (error) => {
-            this.logger?.error(
-              "Failed to process pending notifications:",
-              error,
-            );
-          },
-        );
-        this.pendingNotificationPromises.push(pendingPromise);
-      }
-    };
-
     // Wire up CWD change callback from AIManager to sync Agent's workdir
     this.aiManager.setOnCwdChange((newCwd) => {
       this.workdir = newCwd;
@@ -233,18 +214,20 @@ export class Agent {
       this.options.callbacks?.onWorkdirChange?.(newCwd);
     });
 
-    // Wire up message queue to process when agent becomes idle
-    this.messageQueue.onMessageEnqueued = () => this.tryDequeue();
+    // Wire up message queue to process when agent becomes idle.
+    // Both user messages and background task notifications enqueue here,
+    // unified through a single dispatch path (tryDispatch).
+    this.messageQueue.onMessageEnqueued = () => this.tryDispatch();
 
     // Wire up AI loading changes to process queue when AI becomes idle
     this.aiManager.onLoadingChange = (loading: boolean) => {
-      if (!loading) this.tryDequeue();
+      if (!loading) this.tryDispatch();
     };
 
     // Wire up bang manager callback for command running changes
     this.bangManager.onCommandRunningChange = (running: boolean) => {
       this.options.callbacks?.onCommandRunningChange?.(running);
-      if (!running) this.tryDequeue();
+      if (!running) this.tryDispatch();
     };
 
     // Set initial permission mode if provided
@@ -346,9 +329,11 @@ export class Agent {
     return this.bangManager?.isCommandRunning ?? false;
   }
 
-  /** Get queued messages */
+  /** Get queued user-facing messages (excludes background notifications) */
   public get queuedMessages(): QueuedMessage[] {
-    return this.messageQueue.getQueue();
+    return this.messageQueue
+      .getQueue()
+      .filter((m) => m.type !== "notification");
   }
 
   /** Get goal status string */
@@ -421,28 +406,31 @@ export class Agent {
   }
 
   /**
-   * Unified dequeue trigger — checks state machine before processing.
-   * Called from onMessageEnqueued, onLoadingChange(false), and
-   * onCommandRunningChange(false).
+   * Unified dispatch trigger — checks state machine before processing.
+   * Handles user messages, bang commands, and background task notifications
+   * through a single serialized path. Called from onMessageEnqueued,
+   * onLoadingChange(false), and onCommandRunningChange(false).
    */
-  private tryDequeue(): void {
+  private tryDispatch(): void {
     if (this.messageQueue.state !== "idle") return;
     if (!this.messageQueue.hasPending()) return;
     if (this.aiManager.isLoading || this.isCommandRunning) return;
 
     this.messageQueue.transitionTo("dispatching");
-    this.processQueuedMessage()
+    this.dispatchPromise = this.processQueuedMessage()
       .catch((error) => {
         this.logger?.error("Failed to process queued message:", error);
       })
       .finally(() => {
         this.messageQueue.transitionTo("idle");
-        this.tryDequeue(); // Re-check after processing
+        this.dispatchPromise = null;
+        this.tryDispatch(); // Re-check after processing
       });
   }
 
   /**
-   * Process the next queued message when the agent becomes idle.
+   * Process the next queued item when the agent becomes idle.
+   * Handles three item types: user messages, bang commands, and notifications.
    */
   private async processQueuedMessage(): Promise<void> {
     const next = this.messageQueue.dequeue();
@@ -454,6 +442,25 @@ export class Agent {
     if (next.type === "bang") {
       await this.bangManager?.executeCommand(next.content);
       await this.messageManager.saveSession();
+    } else if (next.type === "notification") {
+      // Drain all pending notifications and batch them into a single AI turn
+      const allNotifications = [
+        next.content,
+        ...this.messageQueue.drainNotifications(),
+      ];
+      for (const xml of allNotifications) {
+        const block = parseTaskNotificationXml(xml);
+        if (block) {
+          this.messageManager.addNotificationMessage({
+            taskId: block.taskId,
+            taskType: block.taskType,
+            status: block.status,
+            summary: block.summary,
+            outputFile: block.outputFile,
+          });
+        }
+      }
+      await this.aiManager.sendAIMessage({ recursionDepth: 0 });
     } else {
       await this.sendMessage(next.content, next.images);
     }
@@ -681,31 +688,6 @@ export class Agent {
     this.aiManager.abortAIMessage();
   }
 
-  /**
-   * Process pending background task notifications by injecting them as user messages
-   * and triggering a new AI response cycle.
-   */
-  private async processPendingNotifications(): Promise<void> {
-    const notifications = this.notificationQueue.dequeueAll();
-    if (notifications.length === 0) return;
-
-    for (const notification of notifications) {
-      const block = parseTaskNotificationXml(notification);
-      if (block) {
-        this.messageManager.addNotificationMessage({
-          taskId: block.taskId,
-          taskType: block.taskType,
-          status: block.status,
-          summary: block.summary,
-          outputFile: block.outputFile,
-        });
-      }
-    }
-
-    // Trigger AI to process the notifications
-    await this.aiManager.sendAIMessage({ recursionDepth: 0 });
-  }
-
   /** Execute bash command (bang command) */
   public async bang(command: string): Promise<void> {
     // If the agent is busy, enqueue the bang command
@@ -866,8 +848,9 @@ export class Agent {
   /** Unified interrupt method, interrupts both AI messages and command execution */
   public abortMessage(): void {
     if (this.aiManager.isLoading || this.isCommandRunning) {
-      // Clear queue first to prevent processQueuedMessage from dequeuing
-      // when abortAIMessage triggers onLoadingChange(false)
+      // Clear user-facing queue items first to prevent processQueuedMessage
+      // from dequeuing when abortAIMessage triggers onLoadingChange(false).
+      // Notifications are preserved so background task results aren't lost.
       this.messageQueue.clear();
       this.options.callbacks?.onQueuedMessagesChange?.(this.queuedMessages);
     }
@@ -957,15 +940,14 @@ export class Agent {
     }).catch(() => {});
     await shutdownTelemetry();
 
-    // Clear notification callback first to prevent any late triggers from
+    // Clear message queue callback first to prevent any late triggers from
     // starting async work during teardown
-    this.notificationQueue.onNotificationsEnqueued = undefined;
+    this.messageQueue.onMessageEnqueued = undefined;
 
-    // Await any pending notification processing to prevent race conditions
+    // Await any pending dispatch to prevent race conditions
     // with test teardown (e.g., V8 coverage stream cleanup)
-    if (this.pendingNotificationPromises.length > 0) {
-      await Promise.allSettled(this.pendingNotificationPromises);
-      this.pendingNotificationPromises = [];
+    if (this.dispatchPromise) {
+      await this.dispatchPromise.catch(() => {});
     }
 
     // Fire SessionEnd hooks (fire-and-forget, don't block shutdown)
@@ -1284,4 +1266,14 @@ export class Agent {
       this.subagentManager.getActiveInstances().length > 0;
     return runningTasks || activeSubagents;
   }
+
+  /**
+   * Check if there are pending items (messages, bang commands, or background
+   * task notifications) in the message queue. Background task completion
+   * notifications are enqueued before the main agent's dispatch consumes them,
+   * so callers waiting for the agent to fully settle must also wait on this.
+   */
+  public get hasPendingMessages(): boolean {
+    return this.messageQueue.hasPending();
+  }
 }

package/src/index.ts

@@ -29,6 +29,7 @@ export * from "./utils/tokenCalculation.js";
 export * from "./utils/gitUtils.js";
 export * from "./utils/nameGenerator.js";
 export * from "./utils/worktreeSession.js";
+export { loadMergedWaveConfig } from "./services/configurationService.js";
 export * from "./types/index.js";
 
 // Export tool building utilities

package/src/managers/aiManager.ts

@@ -41,7 +41,7 @@ import { Container } from "../utils/container.js";
 import type { WorktreeSession } from "../utils/worktreeSession.js";
 import { recoverTruncatedJson } from "../utils/stringUtils.js";
 import { ConfigurationService } from "../services/configurationService.js";
-import type { NotificationQueue } from "./notificationQueue.js";
+import type { MessageQueue } from "./messageQueue.js";
 
 import { logger } from "../utils/globalLogger.js";
 import {
@@ -115,6 +115,7 @@ export interface AIManagerOptions {
 
 export class AIManager {
   public isLoading: boolean = false;
+  private turnGeneration = 0; // Guards against concurrent sendAIMessage turns
   private abortController: AbortController | null = null;
   onLoadingChange?: (loading: boolean) => void;
   private toolAbortController: AbortController | null = null;
@@ -251,6 +252,10 @@ export class AIManager {
     return this.configurationService.resolveAutoMemoryEnabled();
   }
 
+  public getWorktreeBaseRef(): "fresh" | "head" {
+    return this.configurationService.resolveWorktreeBaseRef();
+  }
+
   public getWorkdir(): string {
     return this.container.get<string>("Workdir") ?? process.cwd();
   }
@@ -397,6 +402,10 @@ export class AIManager {
   }
 
   public abortAIMessage(): void {
+    // Bump generation so the in-flight turn's end-of-turn setIsLoading(false)
+    // is skipped (generation mismatch), preventing it from racing with this abort.
+    this.turnGeneration++;
+
     // Interrupt AI service
     if (this.abortController) {
       try {
@@ -818,6 +827,15 @@ export class AIManager {
     const { recursionDepth = 0, model, allowedRules, maxTokens } = options;
     let turnOffset = recursionDepth;
 
+    // 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)
+    // has superseded us. setIsLoading(true) here also closes the "idle but
+    // previous turn not finished" race window by marking us busy immediately.
+    this.turnGeneration++;
+    const myGeneration = this.turnGeneration;
+    this.setIsLoading(true);
+
     outer: while (true) {
       let shouldRestart = false;
 
@@ -839,9 +857,8 @@ export class AIManager {
         }).catch(() => {}); // Non-blocking
       }
 
-      // Set loading state early for the initial call, before any async work
+      // Apply allowed rules for the initial call
       if (turnOffset === 0) {
-        this.setIsLoading(true);
         if (allowedRules && allowedRules.length > 0) {
           this.permissionManager?.addTemporaryRules(allowedRules);
         }
@@ -1375,8 +1392,6 @@ export class AIManager {
 
         // Save session in each iteration to ensure message persistence
         await this.messageManager.saveSession();
-        // Set loading to false first
-        this.setIsLoading(false);
 
         // Clear temporary rules
         this.permissionManager?.clearTemporaryRules();
@@ -1475,11 +1490,11 @@ export class AIManager {
 
         // Inject pending notifications from background tasks (after Stop hooks,
         // aligned with Claude Code which fires Stop hooks unconditionally)
-        const notificationQueue = this.container.has("NotificationQueue")
-          ? this.container.get<NotificationQueue>("NotificationQueue")
+        const messageQueue = this.container.has("MessageQueue")
+          ? this.container.get<MessageQueue>("MessageQueue")
           : undefined;
-        if (notificationQueue && notificationQueue.hasPending()) {
-          const notifications = notificationQueue.dequeueAll();
+        if (messageQueue && messageQueue.hasNotifications()) {
+          const notifications = messageQueue.drainNotifications();
           for (const notification of notifications) {
             const block = parseTaskNotificationXml(notification);
             if (block) {
@@ -1498,7 +1513,16 @@ export class AIManager {
         }
       }
 
-      if (!shouldRestart) break outer;
+      if (!shouldRestart) {
+        // Release loading state only after ALL cleanup is done (session save,
+        // Stop hooks, notification injection). Generation check ensures a
+        // superseded (aborted or newer) turn doesn't clobber the current
+        // loading state.
+        if (myGeneration === this.turnGeneration) {
+          this.setIsLoading(false);
+        }
+        break outer;
+      }
     }
   }
 

package/src/managers/backgroundTaskManager.ts

@@ -6,7 +6,7 @@ import { BackgroundTask, BackgroundShell } from "../types/processes.js";
 import { stripAnsiColors } from "../utils/stringUtils.js";
 import { logger } from "../utils/globalLogger.js";
 import { Container } from "../utils/container.js";
-import { NotificationQueue } from "./notificationQueue.js";
+import { MessageQueue } from "./messageQueue.js";
 import { resolveShellPath } from "../utils/shellResolver.js";
 
 export interface BackgroundTaskManagerCallbacks {
@@ -32,10 +32,6 @@ export class BackgroundTaskManager {
     this.workdir = options.workdir;
   }
 
-  private get notificationQueue(): NotificationQueue {
-    return this.container.get<NotificationQueue>("NotificationQueue")!;
-  }
-
   /**
    * Fire the onBackgroundTasksChange callback so UI consumers refresh.
    * Public so other managers (e.g. WorkflowManager) can trigger a refresh
@@ -178,13 +174,13 @@ export class BackgroundTaskManager {
 
       // Skip notification if task was manually killed (user/agent-initiated stop)
       if (!wasKilled) {
-        const notificationQueue = this.container.has("NotificationQueue")
-          ? this.container.get<NotificationQueue>("NotificationQueue")
+        const messageQueue = this.container.has("MessageQueue")
+          ? this.container.get<MessageQueue>("MessageQueue")
           : undefined;
-        if (notificationQueue) {
+        if (messageQueue) {
           const statusStr = shell.status;
           const summary = `Command "${command}" ${statusStr} with exit code ${code ?? 0}`;
-          notificationQueue.enqueue(
+          messageQueue.enqueueNotification(
             `<task-notification>\n<task-id>${id}</task-id>\n<task-type>shell</task-type>\n<output-file>${logPath}</output-file>\n<status>${statusStr}</status>\n<summary>${summary}</summary>\n</task-notification>`,
           );
         }
@@ -208,12 +204,12 @@ export class BackgroundTaskManager {
       this.notifyTasksChange();
 
       // Enqueue error notification
-      const notificationQueue = this.container.has("NotificationQueue")
-        ? this.container.get<NotificationQueue>("NotificationQueue")
+      const messageQueue = this.container.has("MessageQueue")
+        ? this.container.get<MessageQueue>("MessageQueue")
         : undefined;
-      if (notificationQueue) {
+      if (messageQueue) {
         const summary = `Command "${command}" failed with error: ${stripAnsiColors(error.message)}`;
-        notificationQueue.enqueue(
+        messageQueue.enqueueNotification(
           `<task-notification>\n<task-id>${id}</task-id>\n<task-type>shell</task-type>\n<output-file>${logPath}</output-file>\n<status>failed</status>\n<summary>${summary}</summary>\n</task-notification>`,
         );
       }
@@ -337,13 +333,13 @@ export class BackgroundTaskManager {
 
       // Skip notification if task was manually killed (user/agent-initiated stop)
       if (!wasKilled) {
-        const notificationQueue = this.container.has("NotificationQueue")
-          ? this.container.get<NotificationQueue>("NotificationQueue")
+        const messageQueue = this.container.has("MessageQueue")
+          ? this.container.get<MessageQueue>("MessageQueue")
           : undefined;
-        if (notificationQueue) {
+        if (messageQueue) {
           const statusStr = shell.status;
           const summary = `Command "${command}" ${statusStr} with exit code ${code ?? 0}`;
-          notificationQueue.enqueue(
+          messageQueue.enqueueNotification(
             `<task-notification>\n<task-id>${id}</task-id>\n<task-type>shell</task-type>\n<output-file>${logPath}</output-file>\n<status>${statusStr}</status>\n<summary>${summary}</summary>\n</task-notification>`,
           );
         }
@@ -364,12 +360,12 @@ export class BackgroundTaskManager {
       this.notifyTasksChange();
 
       // Enqueue error notification
-      const notificationQueue = this.container.has("NotificationQueue")
-        ? this.container.get<NotificationQueue>("NotificationQueue")
+      const messageQueue = this.container.has("MessageQueue")
+        ? this.container.get<MessageQueue>("MessageQueue")
         : undefined;
-      if (notificationQueue) {
+      if (messageQueue) {
         const summary = `Command "${command}" failed with error: ${stripAnsiColors(error.message)}`;
-        notificationQueue.enqueue(
+        messageQueue.enqueueNotification(
           `<task-notification>\n<task-id>${id}</task-id>\n<task-type>shell</task-type>\n<output-file>${logPath}</output-file>\n<status>failed</status>\n<summary>${summary}</summary>\n</task-notification>`,
         );
       }

package/src/managers/messageQueue.ts

@@ -2,7 +2,7 @@ export type QueueState = "idle" | "dispatching" | "running";
 
 export interface QueuedMessage {
   id?: string;
-  type?: "message" | "bang";
+  type?: "message" | "bang" | "notification";
   content: string;
   images?: Array<{ path: string; mimeType: string }>;
   longTextMap?: Record<string, string>;
@@ -44,8 +44,12 @@ export class MessageQueue {
     return this.queue.shift() ?? null;
   }
 
+  /**
+   * Clear user-facing items (messages, bang commands) but preserve pending
+   * notifications so background task results are not lost on abort.
+   */
   clear(): void {
-    this.queue = [];
+    this.queue = this.queue.filter((m) => m.type === "notification");
     this._state = "idle";
   }
 
@@ -113,4 +117,41 @@ export class MessageQueue {
     this.queue = remaining;
     return editable;
   }
+
+  /**
+   * Enqueue a background task notification (XML string). Notifications are
+   * not user-editable and not surfaced in the queued-messages UI.
+   */
+  enqueueNotification(xml: string): void {
+    this.queue.push({
+      id: `mq-${this.nextId++}`,
+      type: "notification",
+      content: xml,
+      editable: false,
+    });
+    this.onMessageEnqueued?.();
+  }
+
+  /** Whether any notification items are pending. */
+  hasNotifications(): boolean {
+    return this.queue.some((m) => m.type === "notification");
+  }
+
+  /**
+   * Drain all notification items, returning their XML content. Non-notification
+   * items (messages, bang commands) are preserved in the queue.
+   */
+  drainNotifications(): string[] {
+    const notifications: string[] = [];
+    const remaining: QueuedMessage[] = [];
+    for (const msg of this.queue) {
+      if (msg.type === "notification") {
+        notifications.push(msg.content);
+      } else {
+        remaining.push(msg);
+      }
+    }
+    this.queue = remaining;
+    return notifications;
+  }
 }