@pellux/goodvibes-tui 1.13.0 → 1.14.0

package/src/core/rewind-turn-anchors.ts

@@ -0,0 +1,160 @@
+/**
+ * rewind-turn-anchors.ts — the session-scoped join key between the conversation
+ * and the workspace-checkpoint store, for message-anchored rewind.
+ *
+ * The unified rewind service (SDK platform/rewind) anchors a rewind to a
+ * `{ sessionId, turnId }`. Files-scope resolves that turnId against the
+ * workspace checkpoints the turn engine already stamps with the same turnId.
+ * Conversation-scope, however, needs to know HOW MANY conversation messages
+ * existed at that turn boundary — a mapping the SDK's checkpoint store does not
+ * carry (TUI turn-checkpoints are not stamped with a conversation-message
+ * count). This registry supplies exactly that mapping: at every TURN_COMPLETED
+ * the TUI records the turnId together with the live `conversation.getMessageCount()`,
+ * so a later rewind to that turnId can truncate the conversation to precisely
+ * the boundary the files checkpoint captured.
+ *
+ * Scope + lifetime: in-memory, keyed by sessionId. The registry is the live
+ * working copy; it is mirrored to a small per-session sidecar file next to the
+ * session's JSONL (`<sessionsDir>/<sessionId>.anchors.json`) at every turn, and
+ * `restoreTurnAnchors` reloads that sidecar on resume so message-anchored
+ * /rewind works identically before and after a resume. The sidecar's
+ * `messageCount` boundaries stay valid because a resume rehydrates the same
+ * message history the anchors were recorded against.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { operations } from '@pellux/goodvibes-sdk/platform/runtime';
+
+const { getUserSessionsDir } = operations;
+
+/** One recorded turn boundary — the rewind coordinator's per-turn anchor. */
+export interface TurnAnchor {
+  /** The turn engine's turn id, shared with the workspace checkpoint's `turnId`. */
+  readonly turnId: string;
+  /** A short human label (the truncated user prompt) for the recent-turns picker. */
+  readonly label: string;
+  /** `conversation.getMessageCount()` captured at this turn's completion — the conversation truncation boundary. */
+  readonly messageCount: number;
+  /** Wall-clock ms at capture, for ordering + age display. */
+  readonly at: number;
+}
+
+/** Hard cap so a very long session cannot grow this registry without bound. */
+const MAX_ANCHORS_PER_SESSION = 500;
+
+const registry = new Map<string, TurnAnchor[]>();
+
+/** Trim a user prompt to a single compact line for the picker. */
+export function summarizeTurnLabel(text: string | null | undefined, max = 72): string {
+  const oneLine = (text ?? '').replace(/\s+/g, ' ').trim();
+  if (oneLine.length === 0) return '(no prompt text)';
+  return oneLine.length > max ? `${oneLine.slice(0, max - 1)}…` : oneLine;
+}
+
+/**
+ * Record a completed turn's anchor. Idempotent per turnId: a repeated turnId
+ * updates the existing entry in place (the checkpoint engine can re-snapshot a
+ * turn) rather than duplicating it.
+ */
+export function recordTurnAnchor(sessionId: string, anchor: TurnAnchor): void {
+  if (!sessionId || !anchor.turnId) return;
+  const list = registry.get(sessionId) ?? [];
+  const existingIndex = list.findIndex((a) => a.turnId === anchor.turnId);
+  if (existingIndex >= 0) {
+    list[existingIndex] = anchor;
+  } else {
+    list.push(anchor);
+    if (list.length > MAX_ANCHORS_PER_SESSION) list.splice(0, list.length - MAX_ANCHORS_PER_SESSION);
+  }
+  registry.set(sessionId, list);
+}
+
+/** All recorded anchors for a session, oldest first (chronological). */
+export function getTurnAnchors(sessionId: string): readonly TurnAnchor[] {
+  return registry.get(sessionId) ?? [];
+}
+
+/** Resolve an anchor by exact turnId, or null when this run never recorded it. */
+export function resolveTurnAnchor(sessionId: string, turnId: string): TurnAnchor | null {
+  return registry.get(sessionId)?.find((a) => a.turnId === turnId) ?? null;
+}
+
+/** Drop a session's anchors. Exposed for tests and session reset. */
+export function clearTurnAnchors(sessionId: string): void {
+  registry.delete(sessionId);
+}
+
+// --- Cross-resume persistence -------------------------------------------------
+//
+// The TUI mirrors the in-memory registry to a sidecar next to the session file.
+// Surface is always 'tui' (the sessions the TUI reads/writes live under the same
+// scoped directory), matching how the session JSONL itself is persisted.
+const ANCHOR_SIDECAR_SURFACE = 'tui';
+const ANCHOR_SIDECAR_VERSION = 1;
+
+/** Absolute path to a session's anchor sidecar, or null when inputs are unusable. */
+function anchorSidecarPath(sessionId: string, workingDirectory: string): string | null {
+  if (!sessionId || !workingDirectory) return null;
+  // A sessionId is a filename component; refuse anything with path separators so
+  // a malformed id can never escape the sessions directory.
+  if (/[\\/]/.test(sessionId)) return null;
+  return join(getUserSessionsDir(workingDirectory, ANCHOR_SIDECAR_SURFACE), `${sessionId}.anchors.json`);
+}
+
+function isTurnAnchor(value: unknown): value is TurnAnchor {
+  if (typeof value !== 'object' || value === null) return false;
+  const a = value as Record<string, unknown>;
+  return (
+    typeof a.turnId === 'string' && a.turnId.length > 0 &&
+    typeof a.label === 'string' &&
+    typeof a.messageCount === 'number' && Number.isFinite(a.messageCount) &&
+    typeof a.at === 'number' && Number.isFinite(a.at)
+  );
+}
+
+/**
+ * Write the current in-memory anchors for a session to its sidecar so they
+ * survive a resume. Best-effort and atomic (temp file + rename): a failed or
+ * torn write must never break the turn that triggered it. Called after each
+ * `recordTurnAnchor` at TURN_COMPLETED.
+ */
+export function persistTurnAnchors(sessionId: string, workingDirectory: string): void {
+  const path = anchorSidecarPath(sessionId, workingDirectory);
+  if (!path) return;
+  const list = registry.get(sessionId) ?? [];
+  if (list.length === 0) return; // nothing to mirror yet
+  try {
+    mkdirSync(getUserSessionsDir(workingDirectory, ANCHOR_SIDECAR_SURFACE), { recursive: true });
+    const payload = JSON.stringify({ version: ANCHOR_SIDECAR_VERSION, sessionId, anchors: list });
+    const tmp = `${path}.tmp-${process.pid}`;
+    writeFileSync(tmp, payload);
+    renameSync(tmp, path);
+  } catch {
+    /* best-effort; a rewind-anchor persist miss must never break the turn */
+  }
+}
+
+/**
+ * Reload a session's persisted anchors into the in-memory registry on resume.
+ * Returns the number of anchors restored (0 when no sidecar exists or it is
+ * unreadable). Idempotent via `recordTurnAnchor`'s per-turnId dedup, so a resume
+ * that later re-records the same turn keeps a single entry.
+ */
+export function restoreTurnAnchors(sessionId: string, workingDirectory: string): number {
+  const path = anchorSidecarPath(sessionId, workingDirectory);
+  if (!path || !existsSync(path)) return 0;
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8')) as { anchors?: unknown };
+    if (!parsed || !Array.isArray(parsed.anchors)) return 0;
+    let restored = 0;
+    for (const candidate of parsed.anchors) {
+      if (isTurnAnchor(candidate)) {
+        recordTurnAnchor(sessionId, candidate);
+        restored++;
+      }
+    }
+    return restored;
+  } catch {
+    return 0;
+  }
+}

package/src/core/scriptable-statusline.ts

@@ -0,0 +1,141 @@
+/**
+ * Scriptable status line.
+ *
+ * When the user sets `statusline.command` in settings.json, that command is run
+ * as a POSIX shell command (`/bin/sh -c <command>`) at each turn boundary and
+ * its first stdout line is shown in the status area. Every run is bounded by a
+ * timeout (`statusline.timeoutMs`, default 2000ms) so a slow or hung command
+ * can never stall the UI, and runs never overlap: a refresh requested while one
+ * is in flight coalesces into a single trailing run.
+ *
+ * Output is sanitized to one safe line: first line only, ANSI escape sequences
+ * and control characters stripped, trimmed, and length-capped. On failure
+ * (non-zero exit, timeout, spawn error) the previous value is cleared so the
+ * status area does not show stale text.
+ */
+
+import type { ConfigManager } from '../config/index.ts';
+import { readStatuslineSettings, STATUSLINE_DEFAULT_TIMEOUT_MS, type StatuslineSettings } from '../config/tui-extension-settings.ts';
+
+/** Runs the shell command and resolves its raw stdout, or throws on failure/timeout. */
+export type StatuslineCommandRunner = (command: string, cwd: string, timeoutMs: number) => Promise<string>;
+
+export interface ScriptableStatuslineOptions {
+  readonly configManager: Pick<ConfigManager, 'getRaw'>;
+  readonly cwd: string;
+  /** Turn-boundary event subscription surface. */
+  readonly turns: { on(event: string, handler: () => void): () => void };
+  /** Called after a refresh actually changes the rendered value, to trigger a repaint. */
+  readonly onChange?: () => void;
+  /** Injectable command runner (defaults to a Bun.spawn-based POSIX shell runner). Test seam. */
+  readonly runner?: StatuslineCommandRunner;
+  /** Read settings each refresh so live config edits take effect. Test seam / override. */
+  readonly readSettings?: (configManager: Pick<ConfigManager, 'getRaw'>) => StatuslineSettings;
+}
+
+export interface ScriptableStatusline {
+  /** The current sanitized status line, or null when disabled or the last run failed. */
+  current(): string | null;
+  /** Request a refresh now (coalesced against any in-flight run). */
+  refresh(): void;
+  /** Turn-boundary unsubscribe handles. */
+  readonly unsubs: ReadonlyArray<() => void>;
+}
+
+const MAX_OUTPUT_CHARS = 512;
+// Built from escape codes so no literal control byte appears in source.
+// CSI/ANSI escape sequences: ESC (0x1b) '[' params intermediates final-byte.
+const ANSI_ESCAPE = new RegExp('\\x1b\\[[0-9;?]*[ -/]*[@-~]', 'g');
+// C0 control characters (0x00-0x1f) and DEL (0x7f).
+const CONTROL_CHARS = new RegExp('[\\x00-\\x1f\\x7f]', 'g');
+
+/** Reduce raw command stdout to a single safe status line. Exported for testing. */
+export function sanitizeStatuslineOutput(raw: string): string | null {
+  const firstLine = raw.split('\n', 1)[0] ?? '';
+  const cleaned = firstLine
+    .replace(ANSI_ESCAPE, '')
+    .replace(/\t/g, ' ')
+    .replace(CONTROL_CHARS, '')
+    .trim();
+  if (!cleaned) return null;
+  return cleaned.length > MAX_OUTPUT_CHARS ? cleaned.slice(0, MAX_OUTPUT_CHARS) : cleaned;
+}
+
+/** Default runner: `/bin/sh -c <command>` via Bun.spawn with a hard timeout. */
+const defaultRunner: StatuslineCommandRunner = async (command, cwd, timeoutMs) => {
+  const proc = Bun.spawn(['/bin/sh', '-c', command], {
+    stdout: 'pipe',
+    stderr: 'ignore',
+    cwd,
+    timeout: timeoutMs,
+    killSignal: 'SIGKILL',
+  });
+  const out = await new Response(proc.stdout).text();
+  const exitCode = await proc.exited;
+  // A timed-out process is killed by Bun; treat any non-zero exit (including the
+  // kill) as failure so stale output is cleared rather than shown.
+  if (exitCode !== 0) throw new Error(`statusline command exited with code ${exitCode}`);
+  return out;
+};
+
+export function createScriptableStatusline(options: ScriptableStatuslineOptions): ScriptableStatusline {
+  const runner = options.runner ?? defaultRunner;
+  const readSettings = options.readSettings ?? readStatuslineSettings;
+  let value: string | null = null;
+  let inFlight = false;
+  let pending = false;
+
+  const setValue = (next: string | null): void => {
+    if (next === value) return;
+    value = next;
+    options.onChange?.();
+  };
+
+  const run = async (): Promise<void> => {
+    inFlight = true;
+    try {
+      const settings = readSettings(options.configManager);
+      if (!settings.command) {
+        setValue(null);
+        return;
+      }
+      const timeoutMs = settings.timeoutMs ?? STATUSLINE_DEFAULT_TIMEOUT_MS;
+      try {
+        const raw = await runner(settings.command, options.cwd, timeoutMs);
+        setValue(sanitizeStatuslineOutput(raw));
+      } catch {
+        // Non-zero exit, timeout, or spawn error: clear rather than show stale text.
+        setValue(null);
+      }
+    } finally {
+      inFlight = false;
+      if (pending) {
+        pending = false;
+        void run();
+      }
+    }
+  };
+
+  const refresh = (): void => {
+    if (inFlight) {
+      pending = true;
+      return;
+    }
+    void run();
+  };
+
+  const unsubs: Array<() => void> = [
+    options.turns.on('TURN_COMPLETED', refresh),
+    options.turns.on('TURN_ERROR', refresh),
+    options.turns.on('TURN_CANCEL', refresh),
+  ];
+
+  // Prime once so an enabled statusline shows before the first turn completes.
+  refresh();
+
+  return {
+    current: () => value,
+    refresh,
+    unsubs,
+  };
+}

package/src/core/session-auto-titler.ts

@@ -0,0 +1,110 @@
+/**
+ * Session auto-titler.
+ *
+ * When `session.autoTitle` is enabled, an untitled session is given a short
+ * title generated by the configured tool/helper (weak/fast) model after the
+ * first turn completes. It is OFF by default because it spends a small model
+ * call. It only ever sets a SYSTEM-sourced title, so a user-chosen title is
+ * never overwritten, and it runs at most once per session.
+ */
+
+import type { ConversationMessageSnapshot } from '@pellux/goodvibes-sdk/platform/core';
+import type { ConfigManager } from '../config/index.ts';
+import { readSessionSettings } from '../config/tui-extension-settings.ts';
+
+/** Minimal conversation surface the titler needs. */
+export interface TitlerConversation {
+  readonly title: string;
+  getTitleSource(): 'system' | 'user';
+  setSystemTitle(value: string): void;
+  getMessageSnapshot(): ConversationMessageSnapshot[];
+}
+
+/** Minimal weak-model surface (satisfied by the tool LLM). */
+export interface TitlerModel {
+  chat(prompt: string, options?: { maxTokens?: number; systemPrompt?: string }): Promise<string>;
+}
+
+export interface SessionAutoTitlerOptions {
+  readonly conversation: TitlerConversation;
+  readonly model: TitlerModel;
+  readonly configManager: Pick<ConfigManager, 'getRaw'>;
+  readonly turns: { on(event: string, handler: () => void): () => void };
+  /** Called with the generated title after it is applied (for a system message / repaint). */
+  readonly onTitled?: (title: string) => void;
+  /** Test seams. */
+  readonly readSettings?: (configManager: Pick<ConfigManager, 'getRaw'>) => { autoTitle?: boolean };
+}
+
+export interface SessionAutoTitler {
+  readonly unsubs: ReadonlyArray<() => void>;
+  /** Attempt titling now (used by the turn handler; exposed for testing). */
+  maybeTitle(): Promise<void>;
+}
+
+const MAX_TITLE_CHARS = 60;
+const TITLE_SYSTEM_PROMPT =
+  'You write terse chat titles. Reply with ONLY a 3 to 6 word title, Title Case, no surrounding quotes, no trailing punctuation, no preamble.';
+
+/** Extract plain text from a user message's content. */
+function userText(snapshot: ConversationMessageSnapshot[]): string | null {
+  for (const message of snapshot) {
+    if (message.role !== 'user') continue;
+    const { content } = message;
+    if (typeof content === 'string') {
+      const trimmed = content.trim();
+      if (trimmed) return trimmed;
+      continue;
+    }
+    const text = content
+      .map((part) => (part && typeof part === 'object' && 'text' in part && typeof (part as { text: unknown }).text === 'string' ? (part as { text: string }).text : ''))
+      .join(' ')
+      .trim();
+    if (text) return text;
+  }
+  return null;
+}
+
+/** Reduce a model reply to a clean single-line title. */
+export function sanitizeTitle(raw: string): string | null {
+  const firstLine = (raw.split('\n', 1)[0] ?? '').trim();
+  const unquoted = firstLine.replace(/^["'`]+|["'`]+$/g, '').trim();
+  const cleaned = unquoted.replace(/[.!?,;:]+$/g, '').replace(/\s+/g, ' ').trim();
+  if (!cleaned) return null;
+  return cleaned.length > MAX_TITLE_CHARS ? cleaned.slice(0, MAX_TITLE_CHARS).trim() : cleaned;
+}
+
+export function createSessionAutoTitler(options: SessionAutoTitlerOptions): SessionAutoTitler {
+  const readSettings = options.readSettings ?? readSessionSettings;
+  let attempted = false;
+
+  const maybeTitle = async (): Promise<void> => {
+    if (attempted) return;
+    if (!readSettings(options.configManager).autoTitle) return;
+    // Never overwrite a user-chosen title.
+    if (options.conversation.getTitleSource() === 'user') return;
+    const first = userText(options.conversation.getMessageSnapshot());
+    if (!first) return;
+    attempted = true; // Set before the async call so a burst of TURN_COMPLETED fires once.
+    try {
+      const reply = await options.model.chat(
+        `Title this conversation. First user message:\n"""${first.slice(0, 2000)}"""`,
+        { maxTokens: 24, systemPrompt: TITLE_SYSTEM_PROMPT },
+      );
+      const title = sanitizeTitle(reply);
+      if (!title) return;
+      // Re-check: a user may have set a title during the await.
+      if (options.conversation.getTitleSource() === 'user') return;
+      options.conversation.setSystemTitle(title);
+      options.onTitled?.(title);
+    } catch {
+      // Tool LLM unavailable or failed: leave the session untitled, silently.
+    }
+  };
+
+  const unsubs: Array<() => void> = [
+    options.turns.on('TURN_COMPLETED', () => { void maybeTitle(); }),
+  ];
+
+  return { unsubs, maybeTitle };
+}

package/src/core/stream-event-wiring.ts

@@ -1,5 +1,6 @@
 import type { UiRuntimeEvents } from '@/runtime/index.ts';
 import { createStreamStallWatchdog } from './stream-stall-watchdog.ts';
+import { buildRoutingChip } from './model-routing-chip.ts';
 import { formatUserFacingErrorLine } from './format-user-error.ts';
 import { logger } from '@pellux/goodvibes-sdk/platform/utils';
 
@@ -75,6 +76,8 @@ interface FailoverOptimizer {
   readonly enabled: boolean;
   testFallback(profile?: Record<string, unknown>): { readonly chain: readonly FailoverChainNode[] };
   recordFallbackTransition(from: string, to: string, reason: string): void;
+  /** Recent fallback transitions — read by the routing chip to skip double-narrating a failover. */
+  readonly fallbackLog: readonly { readonly from: string; readonly to: string; readonly reason: string; readonly ts: number }[];
 }
 
 /** Minimal system-message surface required for user-visible notifications. */
@@ -300,6 +303,23 @@ export function wireStreamEventMetrics(
     failoverVisited.clear();
   }));
 
+  // Routing chip (never-silent model change): every MODEL_CHANGED that is not
+  // already narrated by the richer [Failover] line becomes a one-line
+  // conversation notice. Deferred a microtask so a failover's
+  // recordFallbackTransition (which runs right AFTER its setCurrentModel) has
+  // landed in the fallback log before buildRoutingChip checks for correlation.
+  // Degrade gracefully when a bare test double omits the providers feed.
+  if (events.providers) {
+    unsubs.push(events.providers.on('MODEL_CHANGED', (change) => {
+      queueMicrotask(() => {
+        const chip = buildRoutingChip(change, providerOptimizer?.fallbackLog ?? [], Date.now());
+        if (chip === null) return;
+        systemMessageRouter.high(chip);
+        render();
+      });
+    }));
+  }
+
   unsubs.push(events.turns.on('TURN_ERROR', (event) => {
     const errVal: string = event.error;
 

package/src/core/system-message-router.ts

@@ -76,7 +76,7 @@ export type SystemMessagePriority = 'high' | 'low';
  * high-priority message inline (model/provider/session confirmations still
  * honour the configured target), so the routing-target config stays meaningful.
  */
-const FORCE_CONVERSATION_PREFIXES = ['[Error]', '[Failover]', '[Compaction]', '[Context]'] as const;
+const FORCE_CONVERSATION_PREFIXES = ['[Error]', '[Failover]', '[Routing]', '[Compaction]', '[Context]', '[Rewind]', '[Revert]'] as const;
 
 function mustReachConversation(message: string): boolean {
   return FORCE_CONVERSATION_PREFIXES.some((prefix) => message.startsWith(prefix));

package/src/core/terminal-notifier.ts

@@ -0,0 +1,102 @@
+/**
+ * terminal-notifier — emits in-terminal desktop notifications via the OSC 9
+ * escape sequence (`ESC ] 9 ; <text> BEL`) and, optionally, an audible bell.
+ *
+ * This is distinct from the OS-level desktop notifications the alert classes in
+ * this directory fire through the SDK's notifyCompletion: OSC 9 is delivered by
+ * the terminal emulator itself, so it works over SSH and inside tmux where a
+ * host-side notify daemon is not reachable. The two are complementary — a user
+ * can enable either, both, or neither.
+ *
+ * Three signals, each with its own config toggle (documented in
+ * settings-modal-data.ts): a tool call waiting on approval (default on), a turn
+ * finishing (default off), and a delegated agent blocking on human input
+ * (default off). A separate `behavior.terminalBell` toggle (default off) adds an
+ * audible BEL to whichever of those fire.
+ *
+ * Focus rule (per the feature brief): emit only when the terminal is NOT focused
+ * if focus is knowable, and unconditionally when the terminal never reported
+ * focus — exactly FocusTracker.shouldAlertWhenUnfocused(). This is deliberately
+ * NOT tied to the alert classes' master `notifyOnlyWhenUnfocused` gate: an
+ * in-terminal notification only makes sense for an unattended window.
+ *
+ * Write discipline: the escape sequence goes out through allowTerminalWrite (so
+ * the terminal-output guard passes it rather than intercepting it as stray
+ * output) and NEVER after the terminal has been handed back to the shell
+ * (isReleased() — the same restore gate the render scheduler honors). No cursor
+ * positioning is involved, so an OSC 9 emitted between frames is safe.
+ */
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+import { allowTerminalWrite } from '../runtime/terminal-output-guard.ts';
+import { readBooleanConfig, type ConfigGet } from './alert-gating.ts';
+import type { FocusTracker } from './focus-tracker.ts';
+
+export type TerminalNotifySignal = 'approval-wait' | 'turn-end' | 'agent-blocked';
+
+interface SignalSpec {
+  readonly configKey: string;
+  readonly defaultOn: boolean;
+}
+
+/** Per-signal config keys + defaults. Kept in sync with settings-modal-data.ts. */
+export const TERMINAL_NOTIFY_SIGNALS: Record<TerminalNotifySignal, SignalSpec> = {
+  'approval-wait': { configKey: 'behavior.terminalNotifyApprovalWait', defaultOn: true },
+  'turn-end': { configKey: 'behavior.terminalNotifyTurnEnd', defaultOn: false },
+  'agent-blocked': { configKey: 'behavior.terminalNotifyAgentBlocked', defaultOn: false },
+};
+
+/** The audible-bell toggle key. Default off. */
+export const TERMINAL_BELL_KEY = 'behavior.terminalBell';
+
+const BEL = '\x07';
+
+/**
+ * Build an OSC 9 desktop-notification sequence. Control characters in the
+ * message are collapsed to spaces so they cannot terminate the sequence early
+ * or corrupt the terminal, and the text is length-capped defensively.
+ */
+export function buildOsc9(message: string): string {
+  const safe = message.replace(/[\x00-\x1f\x7f]/g, ' ').trim().slice(0, 200);
+  return `\x1b]9;${safe}${BEL}`;
+}
+
+export interface TerminalNotifierDeps {
+  readonly stdout: { write(s: string): boolean };
+  readonly configGet: ConfigGet;
+  readonly focusTracker: Pick<FocusTracker, 'shouldAlertWhenUnfocused'>;
+  /** True once the terminal has been restored to the shell — no writes after that. */
+  readonly isReleased: () => boolean;
+}
+
+export interface TerminalNotifier {
+  /** Emit an OSC 9 notification (and optional bell) for `signal`, subject to its toggle + the focus rule. */
+  notify(signal: TerminalNotifySignal, message: string): void;
+}
+
+/** True when `signal` should emit right now (toggle on AND the focus rule allows it). Exposed for tests. */
+export function shouldEmitTerminalNotification(
+  signal: TerminalNotifySignal,
+  configGet: ConfigGet,
+  focusTracker: Pick<FocusTracker, 'shouldAlertWhenUnfocused'>,
+): boolean {
+  const spec = TERMINAL_NOTIFY_SIGNALS[signal];
+  if (!readBooleanConfig(configGet, spec.configKey, spec.defaultOn)) return false;
+  return focusTracker.shouldAlertWhenUnfocused();
+}
+
+export function createTerminalNotifier(deps: TerminalNotifierDeps): TerminalNotifier {
+  return {
+    notify(signal, message) {
+      if (!shouldEmitTerminalNotification(signal, deps.configGet, deps.focusTracker)) return;
+      // Never write escape sequences once the terminal is back on the shell.
+      if (deps.isReleased()) return;
+      const bell = readBooleanConfig(deps.configGet, TERMINAL_BELL_KEY, false);
+      const seq = buildOsc9(message) + (bell ? BEL : '');
+      try {
+        allowTerminalWrite(() => deps.stdout.write(seq));
+      } catch (err) {
+        logger.debug('terminal-notifier: OSC9 write error', { error: String(err) });
+      }
+    },
+  };
+}