Support iTerm2 OSC notifications and terminal bells (#57)

Author: nedtwigg

AGENTS.md

@@ -33,6 +33,7 @@ The primary job of a spec is to be an accurate reference for the current state o
 - **`docs/specs/ontology.md`** — Canonical vocabulary for Session states, layers (Process / Registry / View / Link / Activity / Snapshot), transition verbs, and the Liskov contract on Registry APIs. Read this first. Other specs defer to it when naming a state or a verb.
 - **`docs/specs/layout.md`** — Tiling layout, pane/door containers, dockview configuration, modes (passthrough/command), keyboard shortcuts, selection overlay, spatial navigation, minimize/reattach, inline rename, session lifecycle, session persistence, and theming. Read this when touching: `Wall.tsx`, `Baseboard.tsx`, `Door.tsx`, `TerminalPane.tsx`, `spatial-nav.ts`, `layout-snapshot.ts`, `terminal-registry.ts`, `session-save.ts`, `session-restore.ts`, `reconnect.ts`, `index.css`, `theme.css`, or any keyboard/navigation/mode behavior.
 - **`docs/specs/alert.md`** — Activity monitoring state machine, alert trigger/clearing rules, attention model, TODO lifecycle (soft/hard), bell button visual states and interaction, door alert indicators, and hardening (a11y, motion, i18n, overflow). Read this when touching: `activity-monitor.ts`, `alert-manager.ts`, the alert bell or TODO pill in `Wall.tsx` (TerminalPaneHeader), alert indicators in `Door.tsx`, or the `a`/`t` keyboard shortcuts. Layout.md defers to this spec for all alert/TODO behavior.
+- **`docs/specs/iTerm2.md`** — iTerm2-compatible identity, terminal notification protocols (`OSC 9`, `OSC 99`, `OSC 777`), and `OSC 9;4` progress arming, including how protocol signals force or cock the alert/TODO system. Read this when touching PTY environment identity, terminal device/version reports, OSC parsing, `AlertManager` protocol notification/progress paths, `ActivityState` metadata, or TODO notification preview UI.
 - **`docs/specs/vscode.md`** — VS Code extension architecture: hosting modes (WebviewView + WebviewPanel), PTY lifecycle and buffering, message protocol between webview and extension host, session persistence flow, reconnection protocol, theme integration, CSP, build pipeline, and invariants (save-before-kill ordering, PTY ownership, alert state merging). Read this when touching: `extension.ts`, `webview-view-provider.ts`, `message-router.ts`, `message-types.ts`, `pty-manager.ts`, `pty-host.js`, `session-state.ts`, `webview-html.ts`, `vscode-adapter.ts`, or `pty-core.js`.
 - **`docs/specs/tutorial.md`** — Playground tutorial on the website: 3-pane layout, interactive `tut` TUI runner with three sections (keyboard navigation, alerts/TODOs, copy/paste), per-item detection wired to `WallEvent` / activity store / mouse-selection store, single-key `mouseterm-tut-v3` localStorage scheme, theme picker, and FakePtyAdapter extensions (`sendOutput`, `pumpActivity`, `setInputHandler`). Read this when touching: `website/src/pages/Playground.tsx`, `website/src/lib/tut-runner.ts`, `website/src/lib/tut-detector.ts`, `website/src/lib/tutorial-state.ts`, `website/src/lib/tut-items.ts`, `website/src/lib/tutorial-shell.ts`, `lib/src/components/ThemePicker.tsx`, `lib/src/lib/themes/`, `lib/src/lib/platform/fake-scenarios.ts` (tutorial scenarios), the `WallEvent` union, or the `onApiReady`/`onEvent`/`initialPaneIds` props on Wall.
 - **`docs/specs/theme.md`** — Theme system: two-layer CSS variable strategy, theme data model, conversion pipeline, bundled themes, localStorage store, shared ThemePicker component, standalone AppBar picker, runtime OpenVSX installer. Read this when touching: `lib/src/lib/themes/`, `lib/src/components/ThemePicker.tsx`, `lib/src/theme.css`, `lib/scripts/bundle-themes.mjs`, `standalone/src/AppBar.tsx` (theme picker), `standalone/src/main.tsx` (theme restore), or `website/src/components/SiteHeader.tsx` (themeAware mode).

docs/specs/alert.md

@@ -4,7 +4,7 @@
 
 ## Conceptual model
 
-A **Session** is a single PTY instance — a running shell process with its scrollback, environment, and working directory. Sessions are managed by the terminal registry and persist independently of how they are displayed. Each session also carries Activity state (alert status from the activity monitor, optional TODO flag).
+A **Session** is a single PTY instance — a running shell process with its scrollback, environment, and working directory. Sessions are managed by the terminal registry and persist independently of how they are displayed. Each session also carries Activity state (projected alert status, optional TODO flag, and optional protocol notification detail).
 
 A Session's **View** state places it in one of two containers:
 
@@ -281,7 +281,7 @@ On startup, recovery is priority-based:
 
 ### Activity state
 
-Each session carries `ActivityState` with `status: SessionStatus` and `todo: TodoState`. These are synced to React via `useSyncExternalStore`. State that arrives from the platform before a registry entry exists (resume scenario) is held as "primed state" and applied when the registry entry is created.
+Each session carries `ActivityState` with `status: SessionStatus`, `todo: TodoState`, and `notification: ActivityNotification | null`. `status` is the projected public status from the timer-based visual track plus the terminal-report protocol track described in `docs/specs/alert.md`; it may be `OSC_NOTIF_BUSY` when OSC progress has cocked the bell. These are synced to React via `useSyncExternalStore`. State that arrives from the platform before a registry entry exists (resume scenario) is held as "primed state" and applied when the registry entry is created.
 
 ## Theme
 

docs/specs/iTerm2.md

@@ -63,7 +63,7 @@ A **Session** is the tuple of its `SessionId` plus one state per layer. `Session
 
 Keep the existing state machine (see `docs/specs/alert.md` for transition rules):
 
-`ALERT_DISABLED` · `NOTHING_TO_SHOW` · `MIGHT_BE_BUSY` · `BUSY` · `MIGHT_NEED_ATTENTION` · `ALERT_RINGING`
+`ALERT_DISABLED` · `NOTHING_TO_SHOW` · `MIGHT_BE_BUSY` · `BUSY` · `OSC_NOTIF_BUSY` · `MIGHT_NEED_ATTENTION` · `ALERT_RINGING`
 
 ### Snapshot
 

docs/specs/layout.md

@@ -60,7 +60,7 @@ The detector subscribes to `subscribeToActivity()` and tracks per-id `(status, t
 | ID | Title | Detection |
 |---|---|---|
 | `al-enable` | Enable alerts on a pane (click bell or `a`) | status transitions away from `ALERT_DISABLED` |
-| `al-busy` | Watch the bell tilt while a task runs | status enters `BUSY` or `MIGHT_BE_BUSY` |
+| `al-busy` | Watch the bell tilt while a task runs | status enters `BUSY`, `MIGHT_BE_BUSY`, or `OSC_NOTIF_BUSY` |
 | `al-ring` | Bell rings on completion | status enters `ALERT_RINGING` |
 | `al-todo-auto` | TODO appears when you dismiss the ringing alert | `todo` transitions `false → true` while previous status was `ALERT_RINGING` |
 | `al-todo-clear` | Press passthrough Enter to clear the TODO | `todo` transitions `true → false` |

docs/specs/ontology.md

@@ -190,7 +190,7 @@ All types defined in `message-types.ts`. Webview-side handling in `vscode-adapte
 | `pty:shells` | Available shells list response (matched by requestId) |
 | `mouseterm:flushSessionSave` | Request webview to save state now (deactivate trigger, matched by requestId) |
 | `mouseterm:openThemeDebugger` | Command-triggered request to open the shared theme debugger dialog |
-| `alert:state` | Alert state change (status, todo, attentionDismissedRing) |
+| `alert:state` | Alert state change (projected status, todo, notification, attentionDismissedRing) |
 
 ### Serialization and restore
 
@@ -222,6 +222,7 @@ interface PersistedPane {
 interface PersistedAlertState {
   status: SessionStatus;
   todo: boolean;
+  notification?: ActivityNotification | null;
 }
 
 interface PersistedDoor {

docs/specs/tutorial.md

@@ -206,6 +206,19 @@ export function TodoAlertDialog({
         />
       </div>
 
+      {activity.notification && (
+        <div className="mb-3 max-w-80 border-t border-border pt-2 text-sm leading-relaxed text-foreground">
+          {activity.notification.title && (
+            <div className="font-medium break-words">{activity.notification.title}</div>
+          )}
+          {activity.notification.body && (
+            <div className="mt-1 max-h-32 overflow-auto whitespace-pre-wrap break-words text-muted">
+              {activity.notification.body}
+            </div>
+          )}
+        </div>
+      )}
+
       <div className="border-t border-border pt-2 text-sm leading-relaxed text-muted">
         When a tab with a ringing alert is selected,<br />
         the alert is cleared and the tab gets a TODO.<br />

docs/specs/vscode.md

@@ -6,7 +6,7 @@ export function bellIconClass(status: SessionStatus): string {
   return [
     'transition-transform',
     status === 'MIGHT_BE_BUSY' && '-rotate-[22.5deg]',
-    status === 'BUSY' && 'rotate-45',
+    (status === 'BUSY' || status === 'OSC_NOTIF_BUSY') && 'rotate-45',
     status === 'MIGHT_NEED_ATTENTION' && 'rotate-[60deg]',
     status === 'ALERT_RINGING' && (
       cfg.alert.ringingPaused

lib/src/components/TodoAlertDialog.tsx

@@ -1,4 +1,5 @@
-import { useCallback, useContext, useEffect, useRef, useState, useSyncExternalStore } from 'react';
+import { useCallback, useContext, useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore, type CSSProperties } from 'react';
+import { createPortal } from 'react-dom';
 import type { IDockviewPanelHeaderProps } from 'dockview-react';
 import { tv } from 'tailwind-variants';
 import {
@@ -53,6 +54,19 @@ const tabVariant = tv({
 
 type HeaderTier = 'full' | 'compact' | 'minimal';
 
+const ALERT_BUTTON_ENABLED = { aria: 'Disable alert', tooltip: '[a] Disable alerts' };
+const ALERT_BUTTON_LABELS: Record<SessionStatus, { aria: string; tooltip: string }> = {
+  ALERT_DISABLED: { aria: 'Enable alert', tooltip: '[a] Enable alerts' },
+  NOTHING_TO_SHOW: ALERT_BUTTON_ENABLED,
+  MIGHT_BE_BUSY: ALERT_BUTTON_ENABLED,
+  BUSY: ALERT_BUTTON_ENABLED,
+  MIGHT_NEED_ATTENTION: ALERT_BUTTON_ENABLED,
+  ALERT_RINGING: { aria: 'Alert ringing', tooltip: 'Alert ringing' },
+  OSC_NOTIF_BUSY: { aria: 'Progress active', tooltip: 'Progress active' },
+};
+const TODO_PREVIEW_GAP = 6;
+const TODO_PREVIEW_MARGIN = 8;
+
 export function TerminalPaneHeader({ api }: IDockviewPanelHeaderProps) {
   const mode = useContext(ModeContext);
   const selectedId = useContext(SelectedIdContext);
@@ -80,23 +94,24 @@ export function TerminalPaneHeader({ api }: IDockviewPanelHeaderProps) {
   const suppressAlertClickRef = useRef(false);
   const [tier, setTier] = useState<HeaderTier>('full');
   const [dialogTriggerRect, setDialogTriggerRect] = useState<DOMRect | null>(null);
+  const [todoPreviewRect, setTodoPreviewRect] = useState<DOMRect | null>(null);
   const todoPill = useTodoPillContent(activity.todo);
   const showTodoPill = todoPill.visible && tier !== 'minimal';
-  const alertButtonAriaLabel = activity.status === 'ALERT_RINGING'
-    ? 'Alert ringing'
-    : activity.status === 'ALERT_DISABLED'
-      ? 'Enable alert'
-      : 'Disable alert';
-  const alertButtonTooltip = activity.status === 'ALERT_RINGING'
-    ? 'Alert ringing'
-    : activity.status === 'ALERT_DISABLED'
-      ? '[a] Enable alerts'
-      : '[a] Disable alerts';
+  const alertButtonLabels = ALERT_BUTTON_LABELS[activity.status];
+  const alertButtonAriaLabel = alertButtonLabels.aria;
+  const alertButtonTooltip = alertButtonLabels.tooltip;
   const alertButtonTooltipDetail = activity.status === 'ALERT_RINGING'
     ? 'Click to dismiss and show options'
     : 'Right-click for options';
+  const todoNotificationPreview = formatNotificationPreview(activity.notification);
+  const todoPreviewId = `todo-notification-preview-${api.id}`;
 
   const closeDialog = useCallback(() => setDialogTriggerRect(null), []);
+  const closeTodoPreview = useCallback(() => setTodoPreviewRect(null), []);
+  const openTodoPreview = useCallback((button: HTMLButtonElement) => {
+    if (!activity.notification) return;
+    setTodoPreviewRect(button.getBoundingClientRect());
+  }, [activity.notification]);
 
   const triggerAlertButtonAction = useCallback((displayedStatus: SessionStatus, button: HTMLButtonElement) => {
     const result = actions.onAlertButton(api.id, displayedStatus);
@@ -118,6 +133,10 @@ export function TerminalPaneHeader({ api }: IDockviewPanelHeaderProps) {
     return () => ro.disconnect();
   }, []);
 
+  useEffect(() => {
+    if (!activity.notification) setTodoPreviewRect(null);
+  }, [activity.notification]);
+
   return (
     <div
       ref={tabRef}
@@ -194,12 +213,18 @@ export function TerminalPaneHeader({ api }: IDockviewPanelHeaderProps) {
             type="button"
             data-session-todo-for={api.id}
             data-flourishing={todoPill.flourishing ? 'true' : 'false'}
-            className={`todo-pill-shell shrink-0 rounded border border-current px-1.5 py-px text-xs font-semibold ${TODO_PILL_TRACKING_CLASS} transition-colors hover:bg-current/10`}
-            aria-label="Dismiss TODO"
+            className={`todo-pill-shell shrink-0 rounded border border-current px-1.5 py-px text-xs font-semibold ${TODO_PILL_TRACKING_CLASS} transition-colors hover:bg-current/10 focus:outline-none`}
+            aria-label={todoNotificationPreview ? `Dismiss TODO: ${todoNotificationPreview}` : 'Dismiss TODO'}
+            aria-describedby={todoPreviewRect && activity.notification ? todoPreviewId : undefined}
             aria-hidden={todoPill.flourishing ? true : undefined}
             onMouseDown={(e) => e.stopPropagation()}
+            onMouseEnter={(e) => openTodoPreview(e.currentTarget)}
+            onMouseLeave={closeTodoPreview}
+            onFocus={(e) => openTodoPreview(e.currentTarget)}
+            onBlur={closeTodoPreview}
             onClick={(e) => {
               e.stopPropagation();
+              closeTodoPreview();
               clearSessionTodo(api.id);
             }}
           >
@@ -277,6 +302,80 @@ export function TerminalPaneHeader({ api }: IDockviewPanelHeaderProps) {
           onKeyboardActiveChange={setDialogKeyboardActive}
         />
       )}
+      {todoPreviewRect && activity.notification && !dialogTriggerRect && (
+        <TodoNotificationPreview
+          id={todoPreviewId}
+          notification={activity.notification}
+          anchorRect={todoPreviewRect}
+        />
+      )}
     </div>
   );
 }
+
+function TodoNotificationPreview({
+  id,
+  notification,
+  anchorRect,
+}: {
+  id: string;
+  notification: { title: string | null; body: string | null };
+  anchorRect: DOMRect;
+}) {
+  const ref = useRef<HTMLDivElement>(null);
+  const [style, setStyle] = useState<CSSProperties>({
+    position: 'fixed',
+    left: anchorRect.left,
+    top: anchorRect.bottom + TODO_PREVIEW_GAP,
+  });
+
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    const rect = el.getBoundingClientRect();
+    const top = anchorRect.bottom + TODO_PREVIEW_GAP;
+    const maxLeft = Math.max(TODO_PREVIEW_MARGIN, window.innerWidth - rect.width - TODO_PREVIEW_MARGIN);
+    setStyle({
+      position: 'fixed',
+      left: Math.min(Math.max(anchorRect.left, TODO_PREVIEW_MARGIN), maxLeft),
+      top,
+      maxHeight: Math.max(48, window.innerHeight - top - TODO_PREVIEW_MARGIN),
+    });
+  }, [anchorRect]);
+
+  return createPortal(
+    <div
+      ref={ref}
+      id={id}
+      role="tooltip"
+      className="z-[1000] max-w-80 rounded border border-border bg-surface-raised px-2.5 py-2 font-mono text-sm leading-snug text-foreground shadow-md"
+      style={style}
+    >
+      {notification.title && (
+        <div className="font-medium break-words">{notification.title}</div>
+      )}
+      {notification.body && (
+        <div
+          className="mt-1 whitespace-pre-wrap break-words text-muted"
+          style={{
+            display: '-webkit-box',
+            WebkitBoxOrient: 'vertical',
+            WebkitLineClamp: 3,
+            overflow: 'hidden',
+          }}
+        >
+          {notification.body}
+        </div>
+      )}
+    </div>,
+    document.body,
+  );
+}
+
+function formatNotificationPreview(notification: { title: string | null; body: string | null } | null): string | undefined {
+  if (!notification) return undefined;
+  const parts = [notification.title, notification.body].filter((part): part is string => !!part);
+  if (parts.length === 0) return undefined;
+  const preview = parts.join('\n');
+  return preview.length > 512 ? `${preview.slice(0, 509)}...` : preview;
+}