tmux-ide 2.8.0 → 2.9.0-beta.6

package/packages/daemon/dist/tui/chrome/notify-prefs.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Notification PREFERENCES — the pure shapes and parsing, hoisted out of
+ * {@link ./notify.ts} (which is io: node:child_process, node:fs, tmux).
+ *
+ * Why the split: `settings-model.ts` is pure and only needs `NotificationPrefs`
+ * + `parseHHMM`, but importing them from notify.ts dragged the whole io graph in
+ * behind them. That's invisible in the daemon (node has `process`), and it broke
+ * the moment a pure surface was imported anywhere else — the web host loads
+ * these same modules in a browser, where `process` does not exist.
+ *
+ * The rule this restores is the repo's own: pure core, thin io. Anything a pure
+ * module needs belongs in a pure module.
+ *
+ * notify.ts re-exports these, so existing importers are untouched.
+ */
+import type { NotificationSound } from "../../lib/app-config.ts";
+/** A local-time window, `HH:MM`–`HH:MM`. */
+export interface QuietHours {
+    /** Local `HH:MM` the window opens (e.g. `22:00`). */
+    start: string;
+    /** Local `HH:MM` the window closes (e.g. `08:00`). */
+    end: string;
+}
+export interface NotificationPrefs {
+    /** Master switch — false silences every channel. */
+    enabled: boolean;
+    /** In-terminal status-line toasts. */
+    toast: boolean;
+    /** System banners (native macOS helper, Linux `notify-send`). */
+    macos: boolean;
+    /** Terminal-native banners — OSC 9/99 escapes to eligible client ttys (M25.2). */
+    terminal: boolean;
+    /** Seconds the OS-level channels wait + re-verify before firing (0 = immediate). */
+    delaySeconds: number;
+    /** Sound channel — ping sound + BEL routing (M25.2). */
+    sound: NotificationSound;
+    /** Ping when an agent goes `blocked`. */
+    onBlocked: boolean;
+    /** Ping when an agent goes `done`. */
+    onDone: boolean;
+    /** Optional local-time window that suppresses every OS-LEVEL channel (banner,
+     *  terminal escape, sound, BEL — since M25.2). In-app toasts and the event
+     *  log stay on. */
+    quietHours: QuietHours | null;
+}
+/** PURE — parse `HH:MM` to minutes-since-midnight, or null when malformed / out of range. */
+export declare function parseHHMM(value: unknown): number | null;

package/packages/daemon/dist/tui/chrome/notify-prefs.js

@@ -0,0 +1,13 @@
+/** PURE — parse `HH:MM` to minutes-since-midnight, or null when malformed / out of range. */
+export function parseHHMM(value) {
+    if (typeof value !== "string")
+        return null;
+    const m = /^(\d{2}):(\d{2})$/.exec(value.trim());
+    if (!m)
+        return null;
+    const hours = Number(m[1]);
+    const minutes = Number(m[2]);
+    if (hours > 23 || minutes > 59)
+        return null;
+    return hours * 60 + minutes;
+}

package/packages/daemon/dist/tui/chrome/notify-state.d.ts

@@ -0,0 +1,13 @@
+/** Absolute path to the persisted debounce map. */
+export declare function notifyStatePath(): string;
+/** PURE — the JSON body for a debounce map, dropping entries whose timestamp
+ *  is already outside the debounce window (they can't suppress anything). */
+export declare function serializeLastNotified(map: ReadonlyMap<string, number>, nowMs: number): string;
+/** PURE — parse a persisted body back into the map, pruning stale entries.
+ *  Malformed input (or a FUTURE timestamp beyond the window — clock skew)
+ *  yields an empty/partial map, never a throw. */
+export declare function parseLastNotified(json: string, nowMs: number): Map<string, number>;
+/** io — load the persisted map (empty when missing/unreadable). Never throws. */
+export declare function loadLastNotified(nowMs?: number): Map<string, number>;
+/** io — persist the map (creating the home if needed). Best-effort. */
+export declare function saveLastNotified(map: ReadonlyMap<string, number>, nowMs?: number): void;

package/packages/daemon/dist/tui/chrome/notify-state.js

@@ -0,0 +1,77 @@
+/**
+ * Persistence for the notification debounce map (M25.1) — `lastNotified`
+ * survives updater restarts, so a respawned updater can't re-ping inside the
+ * debounce window (the old in-memory map made every restart an amnesty).
+ *
+ * Same split and same home discipline as {@link ../../lib/update-check.ts}:
+ * {@link serializeLastNotified} + {@link parseLastNotified} are PURE (and prune
+ * entries older than the debounce window — a stamp that can no longer suppress
+ * anything is dead weight); {@link loadLastNotified} / {@link saveLastNotified}
+ * are the thin, never-throwing io wrappers over
+ * `<TMUX_IDE_HOME>/notify-state.json`.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { stateHome } from "../../lib/state-home.js";
+import { NOTIFY_DEBOUNCE_MS } from "./notify.js";
+/** Absolute path to the persisted debounce map. */
+export function notifyStatePath() {
+    return join(stateHome(), "notify-state.json");
+}
+/** PURE — the JSON body for a debounce map, dropping entries whose timestamp
+ *  is already outside the debounce window (they can't suppress anything). */
+export function serializeLastNotified(map, nowMs) {
+    const lastNotified = {};
+    for (const [key, ts] of map) {
+        if (nowMs - ts < NOTIFY_DEBOUNCE_MS)
+            lastNotified[key] = ts;
+    }
+    return JSON.stringify({ lastNotified });
+}
+/** PURE — parse a persisted body back into the map, pruning stale entries.
+ *  Malformed input (or a FUTURE timestamp beyond the window — clock skew)
+ *  yields an empty/partial map, never a throw. */
+export function parseLastNotified(json, nowMs) {
+    const out = new Map();
+    try {
+        const parsed = JSON.parse(json);
+        const raw = parsed?.lastNotified;
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            return out;
+        for (const [key, ts] of Object.entries(raw)) {
+            if (typeof ts !== "number")
+                continue;
+            if (nowMs - ts >= NOTIFY_DEBOUNCE_MS)
+                continue; // expired
+            if (ts - nowMs > NOTIFY_DEBOUNCE_MS)
+                continue; // absurd future stamp
+            out.set(key, ts);
+        }
+    }
+    catch {
+        // unreadable state just means a fresh debounce map
+    }
+    return out;
+}
+/** io — load the persisted map (empty when missing/unreadable). Never throws. */
+export function loadLastNotified(nowMs = Date.now()) {
+    const path = notifyStatePath();
+    if (!existsSync(path))
+        return new Map();
+    try {
+        return parseLastNotified(readFileSync(path, "utf-8"), nowMs);
+    }
+    catch {
+        return new Map();
+    }
+}
+/** io — persist the map (creating the home if needed). Best-effort. */
+export function saveLastNotified(map, nowMs = Date.now()) {
+    try {
+        mkdirSync(stateHome(), { recursive: true });
+        writeFileSync(notifyStatePath(), serializeLastNotified(map, nowMs));
+    }
+    catch {
+        // an unwritable map just means a restart re-arms the debounce — never fatal
+    }
+}

package/packages/daemon/dist/tui/chrome/notify.d.ts

@@ -0,0 +1,361 @@
+import { type NotificationSound } from "../../lib/app-config.ts";
+import type { AgentStatus } from "../detect/classify.ts";
+import { parseHHMM, type NotificationPrefs, type QuietHours } from "./notify-prefs.ts";
+export { parseHHMM };
+export type { NotificationPrefs, QuietHours };
+/**
+ * A fleet transition this tick — since M25.1 a PANE-level transition (the
+ * updater diffs per-pane states, not the session rollup, so a second agent
+ * blocking in an already-blocked session still pings), ENRICHED with the
+ * pane's resolved `agent` id and human `location` (`session:window.pane`) so
+ * the ping can name who needs the user. The enrichments are optional: a caller
+ * that can't resolve them falls back to a generic `agent` label and the bare
+ * session name (see {@link notifyMessage}).
+ */
+export interface NotifyEvent {
+    session: string;
+    from: AgentStatus | null;
+    to: AgentStatus;
+    /** Resolved agent id (e.g. `claude`), or null/absent when unknown. */
+    agent?: string | null;
+    /** Human location `session:window.pane` (e.g. `myproj:1.2`); falls back to `session`. */
+    location?: string;
+    /** The pane behind the transition — the debounce key and the visibility
+     *  test both want the pane, not the session. Absent for a caller that only
+     *  has session granularity (falls back to session-keyed behavior). */
+    paneId?: string | null;
+    /** The pane's `window_index` — window-granular toast suppression needs it.
+     *  Absent/null degrades that check to session granularity. */
+    windowIndex?: number | null;
+}
+/** An attached tmux client, the session it's viewing, and that session's
+ *  CURRENT window (null when the caller couldn't resolve it — suppression then
+ *  degrades to session granularity for that client). `tty`/`termname` (M25.2)
+ *  are what the terminal-escape channel needs — the device to write and which
+ *  escape form the terminal behind it understands; null/absent means the
+ *  caller couldn't resolve them and that client just gets no escapes. */
+export interface AttachedClient {
+    client: string;
+    session: string;
+    windowIndex?: number | null;
+    /** `#{client_tty}` — the device the escape/BEL bytes are written to. */
+    tty?: string | null;
+    /** `#{client_termname}` — picks OSC 99 (kitty) / passthrough (nested tmux). */
+    termname?: string | null;
+}
+/** A toast destined for one client's status line. */
+export interface ToastTarget {
+    client: string;
+    message: string;
+}
+/**
+ * One OS-level ping. `session` rides along so the click-through path
+ * ({@link terminalNotifierArgs}) can focus the right session on click; since
+ * M25.2 the payload also carries the transition's `state` (urgency + sound
+ * routing) and its pane identity (`paneId`/`windowIndex`) so the delayed
+ * re-verify can confirm the pane is STILL in that state and the terminal-escape
+ * channel can re-apply per-client suppression at fire time.
+ */
+export interface SystemNotification {
+    message: string;
+    session: string;
+    /** The state that was pinged — must still hold when a delayed ping fires. */
+    state: AgentStatus;
+    /** The pane behind the ping (null: session-granular caller — unverifiable). */
+    paneId: string | null;
+    /** The pane's window — per-client escape suppression wants it. */
+    windowIndex: number | null;
+}
+/** The verdict of {@link decideNotifications}. */
+export interface NotifyDecision {
+    toasts: ToastTarget[];
+    system: SystemNotification[];
+    /** The debounce map to thread into the next tick (a copy of the input). */
+    nextLastNotified: Map<string, number>;
+}
+/**
+ * Don't re-ping the same session+state more than once inside this window. This
+ * is what tames a FLAPPING agent (working↔blocked every few seconds): the first
+ * `blocked` fires, and every subsequent `blocked` inside the window is dropped,
+ * so a flap notifies at most once per 30s instead of on every bounce.
+ */
+export declare const NOTIFY_DEBOUNCE_MS = 30000;
+/** Cap the ping text so a macOS banner never truncates mid-word (banners clip ~200+). */
+export declare const NOTIFY_MAX_LEN = 120;
+/**
+ * PURE — the human-readable ping for an (enriched) transition, e.g.
+ * `claude blocked · myproj:1.2 — needs input`. Falls back to a generic `agent`
+ * label and the bare session name when the updater couldn't resolve the pane's
+ * agent/location. Clamped to {@link NOTIFY_MAX_LEN} so it fits a macOS banner.
+ */
+export declare function notifyMessage(ev: NotifyEvent): string;
+/**
+ * PURE — which states this user has opted into pinging on, from the
+ * `onBlocked`/`onDone` prefs. Empty when both are off (→ no notifications).
+ */
+export declare function enabledStates(prefs: NotificationPrefs): ReadonlySet<AgentStatus>;
+/** PURE — the debounce-map key for an event: the PANE when known (so a second
+ *  agent blocking in the same session still pings — per-pane debounce), else
+ *  the session (session-granular callers keep the old behavior). */
+export declare function notifyDebounceKey(ev: Pick<NotifyEvent, "session" | "to" | "paneId">): string;
+/** PURE — should this client's toast be suppressed for this event? A client
+ *  gets no toast when it is already LOOKING at the transition: same session
+ *  AND same window (window-granular since M25.1 — an agent in window 2 while
+ *  the client views window 1 IS toast-worthy). Unknown window info on either
+ *  side degrades to the old session-granular suppression. Clients viewing the
+ *  hosted app are always suppressed: the app has its own in-app surfacing, and
+ *  a raw tmux message over the app's renderer is noise. */
+export declare function suppressToastFor(client: AttachedClient, ev: NotifyEvent): boolean;
+/**
+ * PURE — decide who to ping from this tick's transitions.
+ *
+ * Rules:
+ *   - a FIRST-SIGHT event (`from: null`) never notifies — the updater's first
+ *     tick (or a restart, or a session appearing) sees every pane as new, and
+ *     re-pinging an agent that has been blocked for an hour is noise;
+ *   - only states in `states` qualify (default {@link NOTIFY_STATES}; the caller
+ *     narrows it via {@link enabledStates} to honor `onBlocked`/`onDone`);
+ *   - DEBOUNCE: skip a pane+state (see {@link notifyDebounceKey}) that fired
+ *     within {@link NOTIFY_DEBOUNCE_MS} — the flap guard;
+ *   - APP FOCUS: when the unified app is attached and the event's pane is on
+ *     its screen ({@link AppFocus}), the user is LOOKING at it — no toast, no
+ *     banner (and no debounce stamp: nothing fired);
+ *   - SUPPRESS the toast for any client already viewing that pane's window
+ *     ({@link suppressToastFor}) — other clients still get toasted;
+ *   - a `system` entry is produced per qualifying, non-debounced event regardless
+ *     of clients (so the macOS path fires even with nothing attached — the
+ *     caller gates it on prefs / quiet hours).
+ *
+ * Returns the toasts/system to dispatch plus `nextLastNotified` (a copy of the
+ * input with fresh timestamps for the events we acted on) to thread onward.
+ */
+export declare function decideNotifications(events: NotifyEvent[], clients: AttachedClient[], lastNotified: Map<string, number>, nowMs: number, states?: ReadonlySet<AgentStatus>, appFocus?: AppFocus | null): NotifyDecision;
+/** PURE — parse `list-clients -F '#{client_name}\t#{session_name}\t#{window_index}
+ *  \t#{client_tty}\t#{client_termname}'` output (fields three-plus are optional;
+ *  missing/non-numeric window parses as null so shorter-format callers degrade
+ *  gracefully, and a missing tty/termname just disables that client's escapes). */
+export declare function parseClients(lines: string[]): AttachedClient[];
+/** io — enumerate attached clients (+ their current window, tty, termname) from
+ *  the live tmux server. Never throws. */
+export declare function listAttachedClients(): AttachedClient[];
+/**
+ * What the unified app publishes about its own screen, so the updater can
+ * suppress pings for panes the user is literally looking at. Lives as a tmux
+ * SERVER option ({@link APP_FOCUS_OPTION}) rather than a file: the record is
+ * scoped to exactly the server whose panes are being watched (no cross-server
+ * or cross-`TMUX_IDE_HOME` leakage), it is readable in the same cheap tmux
+ * calls the updater already makes, and it DIES WITH THE SERVER — a crashed
+ * server can't leave a stale record behind. A crashed APP can, which is what
+ * the `ts` staleness guard covers ({@link APP_FOCUS_STALE_MS}).
+ */
+export interface AppFocus {
+    /** Epoch ms the app last refreshed the record (each fleet poll, ~3s). */
+    ts: number;
+    /** Whether a client is attached to the app (hosted: probed; plain: true). */
+    attached: boolean;
+    /** The session the app's Terminal tab mirrors ("" on Home with no context). */
+    session: string;
+    /** Pane ids VISIBLE on the app's screen right now — the mirrored window's
+     *  panes while the Terminal tab is active, [] on Files/Diff/Home. */
+    panes: string[];
+}
+/** The tmux server option carrying the app's JSON {@link AppFocus} record. */
+export declare const APP_FOCUS_OPTION = "@tmux_ide_app_focus";
+/** Ignore a focus record older than this — covers an app that died without
+ *  cleanup (the app refreshes every ~3s fleet poll). */
+export declare const APP_FOCUS_STALE_MS = 15000;
+/** PURE — serialize an {@link AppFocus} for the option value. */
+export declare function buildAppFocusValue(focus: AppFocus): string;
+/** PURE — parse a raw option value into a live {@link AppFocus}, or null for
+ *  anything missing, malformed, or STALE (`ts` older than
+ *  {@link APP_FOCUS_STALE_MS} relative to `nowMs`). Never throws. */
+export declare function parseAppFocus(raw: string | null | undefined, nowMs: number): AppFocus | null;
+/** io — read the app's focus record off the live tmux server (null when unset,
+ *  malformed, or stale). Never throws. */
+export declare function readAppFocus(nowMs?: number): AppFocus | null;
+/**
+ * io — flash each toast on its client's status line (`-d 3000` = 3s; needs tmux
+ * ≥3.2). Best-effort per toast: a gone client / failed call just drops that one.
+ */
+export declare function sendToasts(toasts: ToastTarget[]): void;
+/**
+ * PURE — the OSC 9 desktop-notification escape (iTerm2 / Ghostty / WezTerm and
+ * friends; BEL-terminated). Terminals without support ignore it entirely.
+ */
+export declare function osc9Notification(text: string): string;
+/**
+ * PURE — kitty's richer OSC 99 form (ST-terminated; the empty-metadata payload
+ * is the notification title). Blocked pings carry `u=2` (critical urgency) —
+ * kitty ignores metadata keys it doesn't know, so this is safe on older kitties.
+ */
+export declare function osc99Notification(text: string, urgent: boolean): string;
+/**
+ * PURE — the escape a client's terminal actually understands, by
+ * `#{client_termname}` (conservative, MEASURED — see {@link writeClientTty}):
+ *
+ *   - `*kitty*` → OSC 99 (kitty ignores OSC 9's text form);
+ *   - `tmux-*` / `screen*` → the OSC 9 wrapped in the tmux passthrough envelope
+ *     ({@link tmuxPassthrough}): that termname means the client is itself INSIDE
+ *     another tmux/screen, so our bytes land as pane OUTPUT of the outer mux and
+ *     only the envelope (plus the outer mux's `allow-passthrough`, which is the
+ *     user's to set — we can't reach a foreign server) carries them further;
+ *   - anything else → raw OSC 9. A direct client-tty write BYPASSES our own
+ *     tmux server entirely (measured: bytes arrive on the tty stream verbatim),
+ *     so for a directly-attached terminal the RAW escape is the correct form —
+ *     an envelope there would be ignored by the terminal, not unwrapped.
+ */
+export declare function terminalNotifyEscape(termname: string | null | undefined, text: string, urgent: boolean): string;
+/** One pending write to a client's tty device. */
+export interface TtyWrite {
+    tty: string;
+    data: string;
+}
+/** PURE — should the sound channel fire for this state under this pref? */
+export declare function soundEligible(state: AgentStatus, sound: NotificationSound): boolean;
+/**
+ * PURE — the tty writes for one OS-level ping: for every attached client that
+ * is NOT already looking at the transition (the SAME suppression rule as toasts,
+ * {@link suppressToastFor}) and whose tty we know, the terminal-notification
+ * escape (when `prefs.terminal`) plus a BEL on blocked (when the sound pref
+ * allows). Clients contribute nothing when both channels are off for them.
+ */
+export declare function decideTtyWrites(n: SystemNotification, clients: AttachedClient[], prefs: Pick<NotificationPrefs, "terminal" | "sound">): TtyWrite[];
+/**
+ * io — write escape/BEL bytes straight to a client's tty device. This is the
+ * delivery mechanism (MEASURED against a recorded client tty): the write goes
+ * to the pty the tmux client sits on, so the bytes reach the outer terminal
+ * verbatim without our tmux server ever seeing them — no `allow-passthrough`
+ * needed on this server, no `run-shell`/`display-message` indirection.
+ * Non-blocking open so a flow-stopped tty (^S) can never stall the updater
+ * tick; any failure just drops that client's ping.
+ */
+export declare function writeClientTty(write: TtyWrite): void;
+/** io — dispatch a batch of tty writes, each best-effort. */
+export declare function writeTtys(writes: TtyWrite[]): void;
+/** The calm default ping sounds — a short macOS system chime and the standard
+ *  freedesktop completion sound (skipped silently when absent). */
+export declare const DARWIN_SOUND_FILE = "/System/Library/Sounds/Tink.aiff";
+export declare const LINUX_SOUND_FILE = "/usr/share/sounds/freedesktop/stereo/complete.oga";
+/** PURE — the sound-player argv for a platform, or null when it has none. */
+export declare function soundArgv(platform: NodeJS.Platform): string[] | null;
+/**
+ * io — play the platform ping sound, fire-and-forget (a sync wait would stall
+ * the updater tick for the clip's duration). Missing sound file or player →
+ * silent skip.
+ */
+export declare function playPingSound(platform?: NodeJS.Platform): void;
+/** io — whether `terminal-notifier` is on PATH (enables click-through banners). */
+export declare function hasTerminalNotifier(): boolean;
+/** The session option a banner click stamps on the hosted app: "open THIS
+ *  session when you next look". The app consumes it on its fleet poll. */
+export declare const APP_JUMP_OPTION = "@tmux_ide_app_jump";
+/**
+ * PURE — the shell command a banner click runs (M25.1 click-to-jump v2).
+ * When the hosted app exists, the click routes THROUGH the cockpit: stamp
+ * {@link APP_JUMP_OPTION} on the host session (the running app consumes it and
+ * opens that workspace — so even a DETACHED cockpit shows the right session on
+ * the next attach), then switch the user's most-recent client to the cockpit.
+ * Without a hosted app, fall back to switching the client straight to the
+ * session. (`switch-client` without `-c` targets the last-active client — the
+ * best we can do without knowing which terminal the click came from; with no
+ * client attached at all it fails silently, and the jump stamp still lands.)
+ *
+ * NOTE the target spellings: has-session/switch-client take the `=` exact-match
+ * prefix, but set-option REJECTS it ("no such session", measured on 3.7b — see
+ * {@link ../mirror/hosted.ts hostSetupArgvs}), so the stamp uses the plain name.
+ */
+export declare function notifierExecuteCommand(session: string): string;
+/** The native sender injected into the npm/Homebrew payload at release. */
+export declare const NATIVE_MACOS_NOTIFIER_RELATIVE_PATH = "packages/daemon/dist/native/TmuxIdeNotifier.app";
+export interface NativeMacosNotifierPathIo {
+    /** The real node CLI path forwarded to compiled TUI surfaces. */
+    cliPath?: string | null;
+    /** Injectable module path keeps the ancestor walk deterministic in tests. */
+    modulePath?: string;
+    exists?: (path: string) => boolean;
+}
+/**
+ * io — find the packaged native notifier from either runtime shape:
+ *
+ * - the bundled CLI lives at `bin/cli.js`, one level below the package root;
+ * - checkout source lives below `packages/daemon/src/…`;
+ * - the standalone Bun TUI has a virtual module URL, but the CLI forwards its
+ *   real path through `TMUX_IDE_CLI`.
+ *
+ * Walking ancestors handles all three without baking an install prefix into
+ * the binary. A missing helper is a silent null so older installs can fall back.
+ */
+export declare function resolveNativeMacosNotifierPath(io?: NativeMacosNotifierPathIo): string | null;
+/** PURE — recover tmux's exact socket from `$TMUX` (`path,server-pid,pane-id`). */
+export declare function parseTmuxSocketPath(value: string | undefined): string | null;
+/**
+ * PURE — launch the branded LSUIElement app through LaunchServices. The helper
+ * stores structured tmux coordinates in the system notification payload so a
+ * later click can jump without inheriting a shell, PATH, or TMUX environment.
+ */
+export declare function nativeMacosNotifierArgs(appPath: string, n: SystemNotification, tmuxPath: string | null, socketPath: string | null): string[];
+/**
+ * PURE — the legacy `terminal-notifier` argv retained for older installations
+ * whose package predates the native helper.
+ */
+export declare function terminalNotifierArgs(n: SystemNotification): string[];
+/**
+ * PURE — the `notify-send` argv for a Linux desktop banner: app-named, blocked
+ * pings marked critical so they persist until dismissed (that's the "an agent
+ * is stuck waiting on you" contract).
+ */
+export declare function notifySendArgs(n: SystemNotification): string[];
+/** The io {@link sendSystemNotification} needs — injectable so the per-platform
+ *  routing is unit-tested without firing real banners. */
+export interface SystemNotifyIo {
+    platform?: NodeJS.Platform;
+    env?: Record<string, string | undefined>;
+    exec?: (cmd: string, args: string[]) => void;
+    hasBinary?: (name: string) => boolean;
+    /** undefined auto-resolves the shipped bundle; null tests/old installs skip it. */
+    nativeNotifierPath?: string | null;
+    /** Absolute executable retained for a click relaunch with no terminal PATH. */
+    tmuxPath?: string | null;
+}
+/**
+ * io — fire a system notification, best-effort. macOS: the bundled native app
+ * first (branded, appearance-aware, click-through), then `terminal-notifier`
+ * for an older install, then `osascript` as the last unbranded fallback. Linux:
+ * under a
+ * desktop session (DISPLAY / WAYLAND_DISPLAY) with `notify-send` on PATH, the
+ * same title/body (+ critical urgency for blocked — {@link notifySendArgs});
+ * anything missing → silent skip. Other platforms: no-op.
+ */
+export declare function sendSystemNotification(n: SystemNotification, io?: SystemNotifyIo): void;
+/** A "quiet hours" window — banners are suppressed while the wall clock is inside it. */
+/** User notification preferences. */
+/** Defaults: enabled, tmux toasts + terminal escapes on, system banners off,
+ *  sound on blocked, a 2s re-verify delay, both states pinged, no quiet window. */
+export declare const DEFAULT_NOTIFICATION_PREFS: NotificationPrefs;
+/**
+ * PURE — is `now` (local time) inside the quiet window? Handles a window that
+ * WRAPS midnight (`22:00`–`08:00`). A null window, or a malformed / zero-width
+ * (`start === end`) one, is never quiet.
+ */
+export declare function inQuietHours(now: Date, quiet: QuietHours | null): boolean;
+/**
+ * PURE — resolve full {@link NotificationPrefs} from a parsed config object.
+ *
+ * `toast`/`macos` delegate to the shared {@link parseAppConfig} (so those two
+ * can't drift from the rest of the config); the polish-era fields
+ * (`enabled`/`onBlocked`/`onDone`/`quietHours`) are read straight off the raw
+ * `notifications` block here — `parseAppConfig` doesn't model them, so reading
+ * them locally keeps this change inside the chrome layer. Anything missing or
+ * mistyped falls back to {@link DEFAULT_NOTIFICATION_PREFS}.
+ */
+export declare function parseNotificationPrefs(rawConfig: unknown): NotificationPrefs;
+/** PURE — the `TMUX_IDE_NOTIFY=0` kill-switch: disables everything. */
+export declare function applyKillSwitch(prefs: NotificationPrefs, envValue: string | undefined): NotificationPrefs;
+/** Absolute path to the shared config (honors `TMUX_IDE_CONFIG`). */
+export declare function notifyConfigPath(): string;
+/**
+ * io — resolve effective prefs from the shared app config (defaults for a
+ * missing/invalid file), then apply the `TMUX_IDE_NOTIFY=0` kill-switch. Reads
+ * fresh so the env kill-switch and config edits are honored each call.
+ */
+export declare function readNotificationPrefs(): NotificationPrefs;