feat: terminal persistence, chat scroll overhaul, and notification reliability

- Terminal sessions survive tab/panel switching with snapshot-based hydration and seq ordering
- Terminal tab state persisted to localStorage and reconciled with live PTY processes on startup
- Chat scroll now uses user-intent-based bottom lock instead of proximity-only auto-follow
- Notification system prevents false completion alerts on stops, interrupts, reverts, and chat switches
- Tool group animations only trigger when the view previously rendered a tool as standalone
- Extracted pure utilities with tests: chat-scroll, notification-utils, terminal-history, terminal-tabs

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: OpenSource03

electron/src/ipc/terminal.ts

@@ -2,6 +2,12 @@ import { BrowserWindow, ipcMain } from "electron";
 import crypto from "crypto";
 import { log } from "../lib/logger";
 import { safeSend } from "../lib/safe-send";
+import {
+  appendTerminalHistory,
+  EMPTY_TERMINAL_HISTORY,
+  readTerminalHistory,
+} from "../lib/terminal-history";
+import type { TerminalHistoryState } from "../lib/terminal-history";
 
 interface TerminalEntry {
   pty: {
@@ -14,6 +20,12 @@ interface TerminalEntry {
   cols: number;
   rows: number;
   spaceId: string;
+  createdAt: number;
+  history: TerminalHistoryState;
+  seq: number;
+  exited: boolean;
+  exitCode: number | null;
+  destroyed: boolean;
 }
 
 export const terminals = new Map<string, TerminalEntry>();
@@ -46,15 +58,40 @@ export function register(getMainWindow: () => BrowserWindow | null): void {
         env: { ...process.env, TERM: "xterm-256color", COLORTERM: "truecolor" },
       });
 
-      terminals.set(terminalId, { pty: ptyProcess, cols: cols || 80, rows: rows || 24, spaceId: spaceId || "default" });
+      const entry: TerminalEntry = {
+        pty: ptyProcess,
+        cols: cols || 80,
+        rows: rows || 24,
+        spaceId: spaceId || "default",
+        createdAt: Date.now(),
+        history: EMPTY_TERMINAL_HISTORY,
+        seq: 0,
+        exited: false,
+        exitCode: null,
+        destroyed: false,
+      };
+      terminals.set(terminalId, entry);
 
       ptyProcess.onData((data: string) => {
-        safeSend(getMainWindow, "terminal:data", { terminalId, data });
+        if (entry.destroyed) return;
+        entry.history = appendTerminalHistory(entry.history, data);
+        entry.seq += 1;
+        safeSend(getMainWindow, "terminal:data", { terminalId, data, seq: entry.seq });
       });
 
       ptyProcess.onExit(({ exitCode }: { exitCode: number }) => {
+        if (entry.destroyed) return;
         log("TERMINAL", `Terminal ${terminalId.slice(0, 8)} exited with code ${exitCode}`);
-        terminals.delete(terminalId);
+        entry.exited = true;
+        entry.exitCode = exitCode;
+        const exitNotice = "\r\n\x1b[2m[process exited]\x1b[0m\r\n";
+        entry.history = appendTerminalHistory(entry.history, exitNotice);
+        entry.seq += 1;
+        safeSend(getMainWindow, "terminal:data", {
+          terminalId,
+          data: exitNotice,
+          seq: entry.seq,
+        });
         safeSend(getMainWindow, "terminal:exit", { terminalId, exitCode });
       });
 
@@ -70,13 +107,19 @@ export function register(getMainWindow: () => BrowserWindow | null): void {
   ipcMain.handle("terminal:write", (_event, { terminalId, data }: { terminalId: string; data: string }) => {
     const term = terminals.get(terminalId);
     if (!term) return { error: "Terminal not found" };
+    if (term.exited) return { error: "Terminal has exited" };
     term.pty.write(data);
     return { ok: true };
   });
 
   ipcMain.handle("terminal:resize", (_event, { terminalId, cols, rows }: { terminalId: string; cols: number; rows: number }) => {
     const term = terminals.get(terminalId);
     if (!term) return { error: "Terminal not found" };
+    if (term.exited) {
+      term.cols = cols;
+      term.rows = rows;
+      return { ok: true };
+    }
     try {
       term.pty.resize(cols, rows);
       term.cols = cols;
@@ -87,10 +130,36 @@ export function register(getMainWindow: () => BrowserWindow | null): void {
     return { ok: true };
   });
 
+  ipcMain.handle("terminal:snapshot", (_event, terminalId: string) => {
+    const term = terminals.get(terminalId);
+    if (!term) return { error: "Terminal not found" };
+    return {
+      output: readTerminalHistory(term.history),
+      seq: term.seq,
+      exited: term.exited,
+      exitCode: term.exitCode,
+    };
+  });
+
+  ipcMain.handle("terminal:list", () => {
+    return {
+      terminals: Array.from(terminals.entries())
+        .map(([terminalId, term]) => ({
+          terminalId,
+          spaceId: term.spaceId,
+          createdAt: term.createdAt,
+          exited: term.exited,
+          exitCode: term.exitCode,
+        }))
+        .sort((a, b) => a.createdAt - b.createdAt),
+    };
+  });
+
   ipcMain.handle("terminal:destroy", (_event, terminalId: string) => {
     const term = terminals.get(terminalId);
     if (term) {
-      term.pty.kill();
+      term.destroyed = true;
+      if (!term.exited) term.pty.kill();
       terminals.delete(terminalId);
       log("TERMINAL", `Destroyed terminal ${terminalId.slice(0, 8)}`);
     }
@@ -100,7 +169,8 @@ export function register(getMainWindow: () => BrowserWindow | null): void {
   ipcMain.handle("terminal:destroy-space", (_event, spaceId: string) => {
     for (const [terminalId, term] of terminals.entries()) {
       if (term.spaceId !== spaceId) continue;
-      term.pty.kill();
+      term.destroyed = true;
+      if (!term.exited) term.pty.kill();
       terminals.delete(terminalId);
       log("TERMINAL", `Destroyed terminal ${terminalId.slice(0, 8)} for space ${spaceId}`);
     }

electron/src/lib/__tests__/chat-scroll.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import {
+  BOTTOM_LOCK_THRESHOLD_PX,
+  getDistanceFromBottom,
+  isWithinBottomLockThreshold,
+  shouldUnlockBottomLock,
+} from "../../../../src/lib/chat-scroll";
+
+describe("chat scroll helpers", () => {
+  it("computes exact distance from the bottom", () => {
+    expect(getDistanceFromBottom({
+      scrollTop: 700,
+      scrollHeight: 1000,
+      clientHeight: 300,
+    })).toBe(0);
+  });
+
+  it("treats near-bottom viewports as bottom-locked", () => {
+    expect(isWithinBottomLockThreshold({
+      scrollTop: 660,
+      scrollHeight: 1000,
+      clientHeight: 300,
+    })).toBe(true);
+  });
+
+  it("does not unlock from passive content growth alone", () => {
+    expect(shouldUnlockBottomLock({
+      scrollTop: 600,
+      scrollHeight: 1000,
+      clientHeight: 300,
+      hasRecentUserIntent: false,
+    })).toBe(false);
+  });
+
+  it("unlocks only after user-originated upward scroll leaves the threshold", () => {
+    expect(shouldUnlockBottomLock({
+      scrollTop: 500,
+      scrollHeight: 1000,
+      clientHeight: 300,
+      hasRecentUserIntent: true,
+    })).toBe(true);
+  });
+
+  it("re-locks when the viewport returns within the threshold", () => {
+    expect(isWithinBottomLockThreshold({
+      scrollTop: 1000 - 300 - BOTTOM_LOCK_THRESHOLD_PX,
+      scrollHeight: 1000,
+      clientHeight: 300,
+    })).toBe(true);
+  });
+});

electron/src/lib/__tests__/notification-utils.test.ts

@@ -0,0 +1,121 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import {
+  advanceSessionCompletionTracker,
+  consumeSuppressedSessionCompletion,
+  resetNotificationStateForTesting,
+  suppressNextSessionCompletion,
+  shouldNotifyPermissionRequest,
+} from "../../../../src/lib/notification-utils";
+
+beforeEach(() => {
+  resetNotificationStateForTesting();
+});
+
+describe("advanceSessionCompletionTracker", () => {
+  it("marks a real completion in the same session", () => {
+    expect(advanceSessionCompletionTracker(
+      { sessionId: "session-a", isProcessing: true },
+      { sessionId: "session-a", isProcessing: false },
+    )).toEqual({
+      completed: true,
+      tracked: { sessionId: "session-a", isProcessing: false },
+    });
+  });
+
+  it("resets tracking when switching from a busy session to a different idle session", () => {
+    expect(advanceSessionCompletionTracker(
+      { sessionId: "session-a", isProcessing: true },
+      { sessionId: "session-b", isProcessing: false },
+    )).toEqual({
+      completed: false,
+      tracked: { sessionId: "session-b", isProcessing: false },
+    });
+  });
+
+  it("drops carried-over busy state on the first render after switching chats", () => {
+    const firstRender = advanceSessionCompletionTracker(
+      { sessionId: "session-a", isProcessing: true },
+      { sessionId: "session-b", isProcessing: true },
+    );
+
+    expect(firstRender).toEqual({
+      completed: false,
+      tracked: { sessionId: "session-b", isProcessing: false },
+    });
+
+    expect(advanceSessionCompletionTracker(
+      firstRender.tracked,
+      { sessionId: "session-b", isProcessing: false },
+    )).toEqual({
+      completed: false,
+      tracked: { sessionId: "session-b", isProcessing: false },
+    });
+  });
+});
+
+describe("shouldNotifyPermissionRequest", () => {
+  it("fires once for a given session/request pair", () => {
+    const seen = new Set<string>();
+
+    expect(shouldNotifyPermissionRequest(seen, {
+      sessionId: "session-a",
+      requestId: "req-1",
+    })).toBe(true);
+
+    expect(shouldNotifyPermissionRequest(seen, {
+      sessionId: "session-a",
+      requestId: "req-1",
+    })).toBe(false);
+  });
+
+  it("suppresses replay when the same open request moves between foreground and background", () => {
+    const seen = new Set<string>();
+
+    expect(shouldNotifyPermissionRequest(seen, {
+      sessionId: "session-a",
+      requestId: "req-1",
+    })).toBe(true);
+
+    expect(shouldNotifyPermissionRequest(seen, {
+      sessionId: "session-a",
+      requestId: "req-1",
+    })).toBe(false);
+  });
+
+  it("allows different sessions or requests to notify independently", () => {
+    const seen = new Set<string>();
+
+    expect(shouldNotifyPermissionRequest(seen, {
+      sessionId: "session-a",
+      requestId: "req-1",
+    })).toBe(true);
+
+    expect(shouldNotifyPermissionRequest(seen, {
+      sessionId: "session-a",
+      requestId: "req-2",
+    })).toBe(true);
+
+    expect(shouldNotifyPermissionRequest(seen, {
+      sessionId: "session-b",
+      requestId: "req-1",
+    })).toBe(true);
+  });
+});
+
+describe("session completion suppression", () => {
+  it("consumes one suppressed completion per session", () => {
+    suppressNextSessionCompletion("session-a");
+
+    expect(consumeSuppressedSessionCompletion("session-a")).toBe(true);
+    expect(consumeSuppressedSessionCompletion("session-a")).toBe(false);
+  });
+
+  it("tracks repeated suppressions independently", () => {
+    suppressNextSessionCompletion("session-a");
+    suppressNextSessionCompletion("session-a");
+
+    expect(consumeSuppressedSessionCompletion("session-a")).toBe(true);
+    expect(consumeSuppressedSessionCompletion("session-a")).toBe(true);
+    expect(consumeSuppressedSessionCompletion("session-a")).toBe(false);
+  });
+});

electron/src/lib/__tests__/terminal-history.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import {
+  appendTerminalHistory,
+  EMPTY_TERMINAL_HISTORY,
+  readTerminalHistory,
+} from "../terminal-history";
+
+describe("terminal history", () => {
+  it("accumulates output chunks in order", () => {
+    const history = appendTerminalHistory(
+      appendTerminalHistory(EMPTY_TERMINAL_HISTORY, "hello "),
+      "world",
+    );
+
+    expect(readTerminalHistory(history)).toBe("hello world");
+  });
+
+  it("drops oldest chunks when the buffer exceeds the limit", () => {
+    let history = EMPTY_TERMINAL_HISTORY;
+    history = appendTerminalHistory(history, "abc", 5);
+    history = appendTerminalHistory(history, "de", 5);
+    history = appendTerminalHistory(history, "fg", 5);
+
+    expect(readTerminalHistory(history)).toBe("defg");
+  });
+});

electron/src/lib/__tests__/terminal-tabs.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+import {
+  parseStoredTerminalState,
+  reconcileTerminalState,
+} from "../../../../src/lib/terminal-tabs";
+
+describe("terminal tabs state", () => {
+  it("keeps persisted tab metadata for live terminals and drops stale ones", () => {
+    const persisted = parseStoredTerminalState(JSON.stringify({
+      default: {
+        tabs: [
+          { id: "term-a", terminalId: "term-a", label: "Build" },
+          { id: "term-stale", terminalId: "term-stale", label: "Old" },
+        ],
+        activeTabId: "term-a",
+      },
+    }));
+
+    expect(reconcileTerminalState(persisted, [
+      { terminalId: "term-a", spaceId: "default", createdAt: 1 },
+    ])).toEqual({
+      default: {
+        tabs: [
+          { id: "term-a", terminalId: "term-a", label: "Build" },
+        ],
+        activeTabId: "term-a",
+      },
+    });
+  });
+
+  it("recovers live terminals missing from persisted state without duplicates", () => {
+    expect(reconcileTerminalState({}, [
+      { terminalId: "term-a", spaceId: "default", createdAt: 1 },
+      { terminalId: "term-b", spaceId: "default", createdAt: 2 },
+    ])).toEqual({
+      default: {
+        tabs: [
+          { id: "term-a", terminalId: "term-a", label: "Terminal 1" },
+          { id: "term-b", terminalId: "term-b", label: "Terminal 2" },
+        ],
+        activeTabId: "term-b",
+      },
+    });
+  });
+});