feat: add command completion notifications (sound, OS notify, highlight)

Add three notification features when a background block's command finishes:

1. **Sound** - plays system bell when command completes in an unfocused block
2. **OS Notification** - shows desktop notification with last terminal line
   as body, clickable to jump to the completed block
3. **Visual Highlight** - blue border glow for success (exit 0), red for
   failure, auto-clears on focus

Also adds `wsh done` CLI command to explicitly signal command completion,
publishing a `block:done` WPS event. Includes bell badge on block header
that focuses the block when clicked.

Three new settings: term:donenotify, term:donesound, term:doneautofocus.

Author: hyi1233

cmd/wsh/cmd/wshcmd-done.go

@@ -0,0 +1,62 @@
+// Copyright 2026, Command Line Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package cmd
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/spf13/cobra"
+	"github.com/wavetermdev/waveterm/pkg/wps"
+	"github.com/wavetermdev/waveterm/pkg/wshrpc"
+	"github.com/wavetermdev/waveterm/pkg/wshrpc/wshclient"
+)
+
+var doneExitCode int
+var doneTitle string
+var doneMessage string
+
+var doneCmd = &cobra.Command{
+	Use:     "done [-t title] [-m message] [-e exitcode]",
+	Short:   "Signal that a command has finished (triggers notification sound, highlight, and OS notification for background blocks)",
+	Args:    cobra.MaximumNArgs(1),
+	RunE:    doneRun,
+	PreRunE: preRunSetupRpcClient,
+}
+
+func init() {
+	doneCmd.Flags().IntVarP(&doneExitCode, "exitcode", "e", 0, "exit code of the completed command")
+	doneCmd.Flags().StringVarP(&doneTitle, "title", "t", "", "notification title (default: Command Finished)")
+	doneCmd.Flags().StringVarP(&doneMessage, "message", "m", "", "notification message")
+	rootCmd.AddCommand(doneCmd)
+}
+
+func doneRun(cmd *cobra.Command, args []string) (rtnErr error) {
+	defer func() {
+		sendActivity("done", rtnErr == nil)
+	}()
+	blockId := os.Getenv("WAVETERM_BLOCKID")
+	if blockId == "" {
+		return fmt.Errorf("WAVETERM_BLOCKID not set, must be run inside a Wave terminal block")
+	}
+
+	if doneMessage == "" && len(args) > 0 {
+		doneMessage = args[0]
+	}
+
+	err := wshclient.EventPublishCommand(RpcClient, wps.WaveEvent{
+		Event:  "block:done",
+		Scopes: []string{fmt.Sprintf("block:%s", blockId)},
+		Data: map[string]any{
+			"blockid":  blockId,
+			"exitcode": doneExitCode,
+			"title":    doneTitle,
+			"message":  doneMessage,
+		},
+	}, &wshrpc.RpcOpts{NoResponse: true})
+	if err != nil {
+		return fmt.Errorf("done command: %w", err)
+	}
+	return nil
+}

emain/emain-ipc.ts

@@ -504,6 +504,32 @@ export function initIpcHandlers() {
         bw.destroy();
     });
 
+    electron.ipcMain.on(
+        "show-completion-notification",
+        (event, tabId: string, blockId: string, title: string, body: string) => {
+            const senderWcId = event.sender.id;
+            const { Notification: ElectronNotification } = electron;
+            if (ElectronNotification == null || !ElectronNotification.isSupported()) {
+                return;
+            }
+            const notification = new ElectronNotification({ title, body, silent: false });
+            notification.on("click", () => {
+                const ww = getWaveWindowByWebContentsId(senderWcId);
+                if (ww == null) return;
+                if (ww.isMinimized()) {
+                    ww.restore();
+                }
+                ww.focus();
+                ww.setActiveTab(tabId, false);
+                const tabView = ww.allLoadedTabViews.get(tabId);
+                if (tabView) {
+                    tabView.webContents.send("focus-block", blockId);
+                }
+            });
+            notification.show();
+        }
+    );
+
     electron.ipcMain.on("do-refresh", (event) => {
         event.sender.reloadIgnoringCache();
     });

emain/preload.ts

@@ -73,6 +73,10 @@ contextBridge.exposeInMainWorld("api", {
     getPathForFile: (file: File): string => webUtils.getPathForFile(file),
     saveTextFile: (fileName: string, content: string) => ipcRenderer.invoke("save-text-file", fileName, content),
     setIsActive: () => ipcRenderer.invoke("set-is-active"),
+    showCompletionNotification: (tabId, blockId, title, body) =>
+        ipcRenderer.send("show-completion-notification", tabId, blockId, title, body),
+    onFocusBlock: (callback) =>
+        ipcRenderer.on("focus-block", (_event, blockId) => callback(blockId)),
 });
 
 // Custom event for "new-window"

frontend/app/block/block-model.ts

@@ -12,12 +12,12 @@ export interface BlockHighlightType {
 export class BlockModel {
     private static instance: BlockModel | null = null;
     private blockHighlightAtomCache = new Map<string, jotai.Atom<BlockHighlightType | null>>();
+    private completionHighlightAtomCache = new Map<string, jotai.Atom<number | null>>();
 
     blockHighlightAtom: jotai.PrimitiveAtom<BlockHighlightType> = jotai.atom(null) as jotai.PrimitiveAtom<BlockHighlightType>;
+    completionHighlightAtom: jotai.PrimitiveAtom<Map<string, number>> = jotai.atom(new Map()) as jotai.PrimitiveAtom<Map<string, number>>;
 
-    private constructor() {
-        // Empty for now
-    }
+    private constructor() {}
 
     getBlockHighlightAtom(blockId: string): jotai.Atom<BlockHighlightType | null> {
         let atom = this.blockHighlightAtomCache.get(blockId);
@@ -38,6 +38,32 @@ export class BlockModel {
         globalStore.set(this.blockHighlightAtom, highlight);
     }
 
+    getCompletionHighlightAtom(blockId: string): jotai.Atom<number | null> {
+        let atom = this.completionHighlightAtomCache.get(blockId);
+        if (!atom) {
+            atom = jotai.atom((get) => {
+                const map = get(this.completionHighlightAtom);
+                return map.get(blockId) ?? null;
+            });
+            this.completionHighlightAtomCache.set(blockId, atom);
+        }
+        return atom;
+    }
+
+    setCompletionHighlight(blockId: string, exitCode: number) {
+        const currentMap = new Map(globalStore.get(this.completionHighlightAtom));
+        currentMap.clear();
+        currentMap.set(blockId, exitCode);
+        globalStore.set(this.completionHighlightAtom, currentMap);
+    }
+
+    clearCompletionHighlight(blockId: string) {
+        const currentMap = new Map(globalStore.get(this.completionHighlightAtom));
+        if (!currentMap.has(blockId)) return;
+        currentMap.delete(blockId);
+        globalStore.set(this.completionHighlightAtom, currentMap);
+    }
+
     static getInstance(): BlockModel {
         if (!BlockModel.instance) {
             BlockModel.instance = new BlockModel();
@@ -48,4 +74,4 @@ export class BlockModel {
     static resetInstance(): void {
         BlockModel.instance = null;
     }
-}
+}

frontend/app/block/block.scss

@@ -444,5 +444,9 @@
                 }
             }
         }
+
+        .block-mask.completion-highlight {
+            transition: border-color 0.3s ease-out, box-shadow 0.3s ease-out;
+        }
     }
 }

frontend/app/block/blockframe-header.tsx

@@ -23,7 +23,7 @@ import { uxCloseBlock } from "@/app/store/keymodel";
 import { TabRpcClient } from "@/app/store/wshrpcutil";
 import { useWaveEnv } from "@/app/waveenv/waveenv";
 import { IconButton } from "@/element/iconbutton";
-import { NodeModel } from "@/layout/index";
+import { NodeModel, getLayoutModelForStaticTab } from "@/layout/index";
 import * as util from "@/util/util";
 import { cn, makeIconClass } from "@/util/util";
 import * as jotai from "jotai";
@@ -281,7 +281,17 @@ const BlockFrame_Header = ({
                 />
             )}
             {useTermHeader && badge && (
-                <div className="pointer-events-none flex items-center px-1" style={{ color: badge.color || "#fbbf24" }}>
+                <div
+                    className="flex cursor-pointer items-center px-1"
+                    style={{ color: badge.color || "#fbbf24" }}
+                    onClick={() => {
+                        const layoutModel = getLayoutModelForStaticTab();
+                        const node = layoutModel?.getNodeByBlockId(nodeModel.blockId);
+                        if (node?.id) {
+                            layoutModel.focusNode(node.id);
+                        }
+                    }}
+                >
                     <i className={makeIconClass(badge.icon, true, { defaultIcon: "circle-small" })} />
                 </div>
             )}

frontend/app/block/blockframe.tsx

@@ -6,6 +6,7 @@ import { BlockFrame_Header } from "@/app/block/blockframe-header";
 import { blockViewToIcon, getViewIconElem, useTabBackground } from "@/app/block/blockutil";
 import { ConnStatusOverlay } from "@/app/block/connstatusoverlay";
 import { ChangeConnectionBlockModal } from "@/app/modals/conntypeahead";
+import { clearBadgesForBlockOnFocus } from "@/app/store/badge";
 import { getBlockComponentModel, globalStore, useBlockAtom } from "@/app/store/global";
 import { useTabModel } from "@/app/store/tab-model";
 import { TabRpcClient } from "@/app/store/wshrpcutil";
@@ -32,6 +33,9 @@ const BlockMask = React.memo(({ nodeModel }: { nodeModel: NodeModel }) => {
     const isLayoutMode = jotai.useAtomValue(waveEnv.atoms.controlShiftDelayAtom);
     const showOverlayBlockNums = jotai.useAtomValue(waveEnv.getSettingsKeyAtom("app:showoverlayblocknums")) ?? true;
     const blockHighlight = jotai.useAtomValue(BlockModel.getInstance().getBlockHighlightAtom(nodeModel.blockId));
+    const completionHighlight = jotai.useAtomValue(
+        BlockModel.getInstance().getCompletionHighlightAtom(nodeModel.blockId)
+    );
     const frameActiveBorderColor = jotai.useAtomValue(
         waveEnv.getBlockMetaKeyAtom(nodeModel.blockId, "frame:activebordercolor")
     );
@@ -63,6 +67,24 @@ const BlockMask = React.memo(({ nodeModel }: { nodeModel: NodeModel }) => {
         style.borderColor = "rgb(59, 130, 246)";
     }
 
+    if (completionHighlight != null && !isFocused) {
+        const highlightColor = completionHighlight === 0 ? "rgb(59, 130, 246)" : "rgb(239, 68, 68)";
+        style.borderColor = highlightColor;
+        style.boxShadow = `0 0 8px 2px ${highlightColor}`;
+    }
+
+    if (isFocused && completionHighlight != null) {
+        style.borderColor = "";
+        style.boxShadow = "";
+    }
+
+    React.useEffect(() => {
+        if (isFocused && completionHighlight != null) {
+            BlockModel.getInstance().clearCompletionHighlight(nodeModel.blockId);
+            clearBadgesForBlockOnFocus(nodeModel.blockId);
+        }
+    }, [isFocused, completionHighlight]);
+
     let innerElem = null;
     if (isLayoutMode && showOverlayBlockNums) {
         showBlockMask = true;
@@ -83,7 +105,11 @@ const BlockMask = React.memo(({ nodeModel }: { nodeModel: NodeModel }) => {
 
     return (
         <div
-            className={clsx("block-mask", { "show-block-mask": showBlockMask, "bg-blue-500/10": blockHighlight })}
+            className={clsx("block-mask", {
+                "show-block-mask": showBlockMask,
+                "bg-blue-500/10": blockHighlight,
+                "completion-highlight": completionHighlight != null && !isFocused,
+            })}
             style={style}
         >
             {innerElem}

frontend/app/view/term/term-model.ts

@@ -2,9 +2,12 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { WaveAIModel } from "@/app/aipanel/waveai-model";
+import { BlockModel } from "@/app/block/block-model";
 import { BlockNodeModel } from "@/app/block/blocktypes";
 import { appHandleKeyDown } from "@/app/store/keymodel";
+import { FocusManager } from "@/app/store/focusManager";
 import { modalsModel } from "@/app/store/modalmodel";
+import { setBadge } from "@/app/store/badge";
 import type { TabModel } from "@/app/store/tab-model";
 import { waveEventSubscribeSingle } from "@/app/store/wps";
 import { RpcApi } from "@/app/store/wshclientapi";
@@ -14,6 +17,7 @@ import { TermClaudeIcon, TerminalView } from "@/app/view/term/term";
 import { TermWshClient } from "@/app/view/term/term-wsh";
 import { VDomModel } from "@/app/view/vdom/vdom-model";
 import { WorkspaceLayoutModel } from "@/app/workspace/workspace-layout-model";
+import { getLayoutModelForStaticTab } from "@/layout/lib/layoutModelHooks";
 import {
     atoms,
     createBlock,
@@ -73,6 +77,7 @@ export class TermViewModel implements ViewModel {
     shellProcFullStatus: jotai.PrimitiveAtom<BlockControllerRuntimeStatus>;
     shellProcStatus: jotai.Atom<string>;
     shellProcStatusUnsubFn: () => void;
+    blockDoneUnsubFn: () => void;
     blockJobStatusAtom: jotai.PrimitiveAtom<BlockJobStatusData>;
     blockJobStatusVersionTs: number;
     blockJobStatusUnsubFn: () => void;
@@ -346,6 +351,13 @@ export class TermViewModel implements ViewModel {
                 this.updateShellProcStatus(event.data);
             },
         });
+        this.blockDoneUnsubFn = waveEventSubscribeSingle({
+            eventType: "block:done",
+            scope: WOS.makeORef("block", blockId),
+            handler: (event) => {
+                this.handleBlockDoneEvent(event.data);
+            },
+        });
         this.shellProcStatus = jotai.atom((get) => {
             const fullStatus = get(this.shellProcFullStatus);
             return fullStatus?.shellprocstatus ?? "init";
@@ -565,6 +577,74 @@ export class TermViewModel implements ViewModel {
         }
     }
 
+    getLastTerminalLine(): string {
+        const term = this.termRef.current?.terminal;
+        if (term == null) return "";
+        const buf = term.buffer.active;
+        for (let i = buf.length - 1; i >= 0; i--) {
+            const line = buf.getLine(i);
+            if (line == null) continue;
+            const text = line.translateToString(true).trim();
+            if (text.length > 0) return text;
+        }
+        return "";
+    }
+
+    handleBlockDoneEvent(data: BlockDoneEventData) {
+        if (data == null || data.blockid !== this.blockId) {
+            return;
+        }
+        const exitCode = data.exitcode ?? 0;
+        const title = data.title || (exitCode === 0 ? "Command Finished" : "Command Failed");
+        let body = data.message;
+        if (!body) {
+            body = this.getLastTerminalLine() || `exit code ${exitCode}`;
+        }
+        this.triggerCompletionNotifications(exitCode, title, body);
+    }
+
+    triggerCompletionNotifications(exitCode: number, title: string, notifyBody?: string) {
+        const focusManager = FocusManager.getInstance();
+        const focusedBlockId = globalStore.get(focusManager.blockFocusAtom);
+        if (focusedBlockId === this.blockId) {
+            return;
+        }
+
+        const doneSoundEnabled = globalStore.get(getOverrideConfigAtom(this.blockId, "term:donesound")) ?? true;
+        if (doneSoundEnabled) {
+            fireAndForget(() =>
+                RpcApi.ElectronSystemBellCommand(TabRpcClient, { route: "electron" })
+            );
+        }
+
+        const doneNotifyEnabled = globalStore.get(getOverrideConfigAtom(this.blockId, "term:donenotify")) ?? true;
+        if (doneNotifyEnabled) {
+            const body = notifyBody || `exit code ${exitCode}`;
+            getApi().showCompletionNotification(this.tabModel.tabId, this.blockId, title, body);
+        }
+
+        const doneAutoFocusEnabled = globalStore.get(getOverrideConfigAtom(this.blockId, "term:doneautofocus")) ?? false;
+        if (doneAutoFocusEnabled) {
+            getApi().setActiveTab(this.tabModel.tabId);
+            setTimeout(() => {
+                const layoutModel = getLayoutModelForStaticTab();
+                const node = layoutModel?.getNodeByBlockId(this.blockId);
+                if (node?.id) {
+                    layoutModel.focusNode(node.id);
+                }
+            }, 150);
+        }
+
+        BlockModel.getInstance().setCompletionHighlight(this.blockId, exitCode);
+
+        setBadge(this.blockId, {
+            badgeid: `done-${this.blockId}`,
+            icon: "bell",
+            color: exitCode === 0 ? "#3b82f6" : "#ef4444",
+            priority: 5,
+        });
+    }
+
     getVDomModel(): VDomModel {
         const vdomBlockId = globalStore.get(this.vdomBlockId);
         if (!vdomBlockId) {

frontend/preview/mock/preview-electron-api.ts

@@ -59,6 +59,8 @@ const previewElectronApi: ElectronApi = {
     doRefresh: () => {},
     saveTextFile: (_fileName: string, _content: string) => Promise.resolve(false),
     setIsActive: async () => {},
+    showCompletionNotification: (_tabId: string, _blockId: string, _title: string, _body: string) => {},
+    onFocusBlock: (_callback: (blockId: string) => void) => {},
 };
 
 function installPreviewElectronApi() {

frontend/types/custom.d.ts

@@ -136,6 +136,8 @@ declare global {
         getPathForFile: (file: File) => string; // webUtils.getPathForFile
         saveTextFile: (fileName: string, content: string) => Promise<boolean>; // save-text-file
         setIsActive: () => Promise<void>; // set-is-active
+        showCompletionNotification: (tabId: string, blockId: string, title: string, body: string) => void; // show-completion-notification
+        onFocusBlock: (callback: (blockId: string) => void) => void; // focus-block
     };
 
     type ElectronContextMenuItem = {