tmux-ide 2.6.1 → 2.7.0

package/packages/daemon/src/lib/app-config.ts

@@ -20,9 +20,9 @@
  * per-concern readers ({@link ../tui/chrome/notify.ts}, {@link ../restore.ts})
  * now delegate here.
  */
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import type { AgentStatus } from "../tui/detect/classify.ts";
 
 // ---------------------------------------------------------------------------
@@ -133,6 +133,17 @@ export interface AppIntegrations {
   offer: boolean;
 }
 
+/** The unified-app front-door decision (M22.6). */
+export interface AppApp {
+  /**
+   * Whether bare `tmux-ide` (no ide.yml here, no `--team`) launches the unified
+   * app (`tmux-ide app`) instead of the classic team cockpit. Default false —
+   * the flip is opt-in until the default-entry decision is made. `tmux-ide team`
+   * (the explicit cockpit) and a project's `ide.yml` auto-launch are unaffected.
+   */
+  frontDoor: boolean;
+}
+
 /** Worktree flow config (`tmux-ide worktree`). */
 export interface AppWorktrees {
   /**
@@ -154,6 +165,7 @@ export interface AppConfig {
   welcome: AppWelcome;
   integrations: AppIntegrations;
   worktrees: AppWorktrees;
+  app: AppApp;
 }
 
 // ---------------------------------------------------------------------------
@@ -190,6 +202,7 @@ export const DEFAULT_APP_CONFIG: AppConfig = {
   welcome: { show: true },
   integrations: { offer: true },
   worktrees: { dir: "" },
+  app: { frontDoor: false },
 };
 
 /** The default theme tokens — the fallback threaded into the pure builders. */
@@ -245,6 +258,7 @@ export function parseAppConfig(input: unknown): AppConfig {
   const welcome = asObject(root.welcome);
   const integrations = asObject(root.integrations);
   const worktrees = asObject(root.worktrees);
+  const app = asObject(root.app);
   return {
     keys: {
       popup: pickString(keys.popup, D.keys.popup),
@@ -287,6 +301,7 @@ export function parseAppConfig(input: unknown): AppConfig {
     welcome: { show: pickBool(welcome.show, D.welcome.show) },
     integrations: { offer: pickBool(integrations.offer, D.integrations.offer) },
     worktrees: { dir: pickString(worktrees.dir, D.worktrees.dir) },
+    app: { frontDoor: pickBool(app.frontDoor, D.app.frontDoor) },
   };
 }
 
@@ -334,3 +349,79 @@ export function getAppConfig(): AppConfig {
 export function _resetForTests(): void {
   cached = null;
 }
+
+// ---------------------------------------------------------------------------
+// Writes (M22.4 — the settings surface persists through here)
+// ---------------------------------------------------------------------------
+
+/**
+ * io — the RAW parsed config file as the user wrote it (`{}` when missing or
+ * malformed). Writers merge over THIS, not over {@link parseAppConfig}'s output:
+ * round-tripping through the parser would materialize every default into the
+ * hand-editable file and silently DROP fields the typed shape doesn't model yet
+ * (e.g. the notification polish fields `notifications.enabled` /
+ * `notifications.quietHours` that {@link ../tui/chrome/notify.ts} reads raw).
+ */
+export function loadRawAppConfig(): Record<string, unknown> {
+  const path = appConfigPath();
+  if (!existsSync(path)) return {};
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf-8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+/** A partial config write: plain objects merge recursively, scalars/arrays
+ *  replace, and an explicit `undefined` DELETES the key (how "reset to
+ *  defaults" removes a block so the parser's defaults take over). */
+export type AppConfigPatch = { [key: string]: unknown };
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * PURE — merge `patch` into `raw` without touching either input. Objects merge
+ * key-by-key (recursively), anything else replaces, and a key whose patch value
+ * is `undefined` is REMOVED from the result. Unknown user fields survive — the
+ * merge only visits keys the patch names.
+ */
+export function mergeConfigPatch(
+  raw: Record<string, unknown>,
+  patch: AppConfigPatch,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...raw };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === undefined) {
+      delete out[key];
+    } else if (isPlainObject(value) && isPlainObject(out[key])) {
+      out[key] = mergeConfigPatch(out[key] as Record<string, unknown>, value as AppConfigPatch);
+    } else if (isPlainObject(value)) {
+      out[key] = mergeConfigPatch({}, value as AppConfigPatch);
+    } else {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+/**
+ * io — apply a patch to the config file ATOMICALLY (temp + rename, the same
+ * discipline as the editor save): read raw → {@link mergeConfigPatch} → write.
+ * Busts the {@link getAppConfig} process cache and returns the new parsed
+ * config. Honors `TMUX_IDE_CONFIG`, so tests never touch the real file.
+ */
+export function updateAppConfig(patch: AppConfigPatch): AppConfig {
+  const path = appConfigPath();
+  const merged = mergeConfigPatch(loadRawAppConfig(), patch);
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(merged, null, 2)}\n`, "utf-8");
+  renameSync(tmp, path);
+  cached = null;
+  return parseAppConfig(merged);
+}

package/packages/daemon/src/lib/tui-binary.ts

@@ -0,0 +1,165 @@
+/**
+ * Per-platform TUI binary: the runtime-download fallback that lets a clean
+ * `npm i -g tmux-ide` run the full OpenTUI/Solid cockpit WITHOUT `bun`.
+ *
+ * The dev checkout runs the `.tsx` surfaces via bun; an npm install with no bun
+ * needs a self-contained binary. We do NOT bundle that ~70MB blob in the npm
+ * tarball (a surprise on every install) — instead the release workflow
+ * (`.github/workflows/release-binaries.yml`) cross-compiles one per platform and
+ * uploads them as GitHub release assets, and this module downloads the right one
+ * on demand (explicit `tmux-ide update --tui-binary`, or a consented first run).
+ *
+ * The mapping/URL/path helpers are PURE (unit-tested); {@link downloadTuiBinary}
+ * and {@link findDownloadedTui} are the thin io that fetch and probe.
+ */
+import { chmodSync, existsSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { gunzipSync } from "node:zlib";
+import { getCurrentVersion } from "./update-check.ts";
+
+/** The `<os>-<arch>` tags we publish a prebuilt TUI binary for. */
+export type TuiPlatformTag = "darwin-arm64" | "darwin-x64" | "linux-x64" | "linux-arm64";
+
+/** The GitHub repo the release assets live under. */
+export const RELEASE_REPO = "wavyrai/tmux-ide";
+
+/** A downloaded binary smaller than this is treated as corrupt/truncated. */
+export const MIN_TUI_BINARY_BYTES = 10 * 1024 * 1024;
+
+const SUPPORTED: Record<string, TuiPlatformTag> = {
+  "darwin-arm64": "darwin-arm64",
+  "darwin-x64": "darwin-x64",
+  "linux-x64": "linux-x64",
+  "linux-arm64": "linux-arm64",
+};
+
+// ---------------------------------------------------------------------------
+// Pure
+// ---------------------------------------------------------------------------
+
+/**
+ * PURE — map a Node `process.platform`/`process.arch` pair to the release tag,
+ * or null when we don't publish a binary for it (e.g. windows, freebsd) so the
+ * caller can fall back to the "install bun" message.
+ */
+export function tuiPlatformTag(
+  platform: NodeJS.Platform = process.platform,
+  arch: string = process.arch,
+): TuiPlatformTag | null {
+  return SUPPORTED[`${platform}-${arch}`] ?? null;
+}
+
+/** PURE — the `bun build --compile --target` flag for a tag (`bun-<tag>`). */
+export function bunTargetForTag(tag: TuiPlatformTag): string {
+  return `bun-${tag}`;
+}
+
+/** PURE — the release asset filename for a tag (gzip-compressed binary). */
+export function releaseAssetName(tag: TuiPlatformTag): string {
+  return `tmux-ide-tui-${tag}.gz`;
+}
+
+/** PURE — strip a leading `v` from a version string; `2.6.1` and `v2.6.1` both → `2.6.1`. */
+export function normalizeVersion(version: string): string {
+  return version.startsWith("v") ? version.slice(1) : version;
+}
+
+/**
+ * PURE — the GitHub download URL for a platform's asset at a given version:
+ * `https://github.com/<repo>/releases/download/v<version>/tmux-ide-tui-<tag>.gz`.
+ */
+export function releaseAssetUrl(version: string, tag: TuiPlatformTag): string {
+  return `https://github.com/${RELEASE_REPO}/releases/download/v${normalizeVersion(version)}/${releaseAssetName(tag)}`;
+}
+
+/**
+ * PURE — where a downloaded binary lives: `<home>/bin/tmux-ide-tui-<tag>-<version>`.
+ * The version is stamped INTO the name so a `tmux-ide update` to a new version
+ * misses the old download and re-fetches (rather than launching a stale binary).
+ */
+export function downloadedTuiPath(home: string, tag: TuiPlatformTag, version: string): string {
+  return join(home, "bin", `tmux-ide-tui-${tag}-${normalizeVersion(version)}`);
+}
+
+// ---------------------------------------------------------------------------
+// io
+// ---------------------------------------------------------------------------
+
+/**
+ * io — the tmux-ide state home (`TMUX_IDE_HOME` override, else `~/.tmux-ide`),
+ * the same resolution the update-check cache and welcome marker use.
+ */
+export function tuiStateHome(): string {
+  return process.env.TMUX_IDE_HOME ?? join(homedir(), ".tmux-ide");
+}
+
+/**
+ * io — locate a previously downloaded per-platform binary for THIS version and
+ * platform, or null. Feeds the resolution order in `tui/compiled.ts` after the
+ * shipped/local compiled binary and before the honest "unavailable" error.
+ */
+export function findDownloadedTui(version: string = getCurrentVersion()): string | null {
+  const tag = tuiPlatformTag();
+  if (!tag) return null;
+  const path = downloadedTuiPath(tuiStateHome(), tag, version);
+  return existsSync(path) ? path : null;
+}
+
+/**
+ * io — download, verify, and install the per-platform TUI binary for the running
+ * version. Fetches the gzip asset, inflates it, rejects anything under
+ * {@link MIN_TUI_BINARY_BYTES} (a truncated download or an HTML error page),
+ * writes it `0o755`, and atomically renames it into place (temp-in-same-dir →
+ * rename, so a crashed download never leaves a half-written executable).
+ *
+ * Throws with an actionable message on an unsupported platform or a failed
+ * fetch. Returns the installed path and byte size.
+ */
+export async function downloadTuiBinary(
+  opts: {
+    version?: string;
+    log?: (msg: string) => void;
+  } = {},
+): Promise<{ path: string; bytes: number }> {
+  const log = opts.log ?? (() => {});
+  const version = normalizeVersion(opts.version ?? getCurrentVersion());
+  const tag = tuiPlatformTag();
+  if (!tag) {
+    throw new Error(
+      `no prebuilt TUI binary is published for ${process.platform}-${process.arch} — ` +
+        `install bun (https://bun.sh) to run the TUI surfaces from source instead`,
+    );
+  }
+
+  const url = releaseAssetUrl(version, tag);
+  const dest = downloadedTuiPath(tuiStateHome(), tag, version);
+  mkdirSync(dirname(dest), { recursive: true });
+
+  log(`downloading ${url}`);
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(
+      `could not download the TUI binary (${url} → HTTP ${res.status} ${res.statusText}). ` +
+        `Check that release v${version} exists and published its assets.`,
+    );
+  }
+
+  const gz = Buffer.from(await res.arrayBuffer());
+  const bin = gunzipSync(gz);
+  if (bin.byteLength < MIN_TUI_BINARY_BYTES) {
+    throw new Error(
+      `the downloaded TUI binary is only ${bin.byteLength} bytes (expected >10MB) — ` +
+        `treating it as corrupt and leaving the previous binary (if any) in place`,
+    );
+  }
+
+  const tmp = `${dest}.${process.pid}.tmp`;
+  writeFileSync(tmp, bin, { mode: 0o755 });
+  chmodSync(tmp, 0o755);
+  renameSync(tmp, dest);
+
+  const mb = (bin.byteLength / 1024 / 1024).toFixed(1);
+  log(`installed ${dest} (${mb} MB)`);
+  return { path: dest, bytes: bin.byteLength };
+}

package/packages/daemon/src/tui/chrome/notify.ts

@@ -7,23 +7,36 @@
  * signals out to the human: a tmux toast on each attached client
  * (`display-message -c`), and optionally a macOS notification.
  *
- * Split as usual: {@link decideNotifications} + {@link notificationPrefs} +
- * {@link applyKillSwitch} + {@link parseClients} are PURE (unit-tested without a
- * live tmux / filesystem); {@link sendToasts}, {@link sendSystemNotification},
+ * Split as usual: {@link decideNotifications} + {@link notifyMessage} +
+ * {@link enabledStates} + {@link inQuietHours} + {@link parseNotificationPrefs}
+ * + {@link applyKillSwitch} + {@link parseClients} + {@link terminalNotifierArgs}
+ * are PURE (unit-tested without a live tmux / filesystem); {@link sendToasts},
+ * {@link sendSystemNotification}, {@link hasTerminalNotifier},
  * {@link listAttachedClients} and {@link readNotificationPrefs} are the thin io
  * wrappers. Every io path is best-effort — a failed ping must never break the
  * updater loop.
  */
 import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
 import { runTmux } from "@tmux-ide/tmux-bridge";
-import { appConfigPath, loadAppConfig, parseAppConfig } from "../../lib/app-config.ts";
+import { appConfigPath, parseAppConfig } from "../../lib/app-config.ts";
 import type { AgentStatus } from "../detect/classify.ts";
 
-/** A fleet transition this tick — the shape {@link ./events.ts diffFleet} emits. */
+/**
+ * A fleet transition this tick — the shape {@link ./events.ts diffFleet} emits,
+ * ENRICHED by the updater with the pane's resolved `agent` id and human
+ * `location` (`session:window.pane`) so the ping can name who needs the user.
+ * Both 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;
 }
 
 /** An attached tmux client and the session it's currently viewing. */
@@ -38,9 +51,13 @@ export interface ToastTarget {
   message: string;
 }
 
-/** A macOS-notification payload (title is fixed by {@link sendSystemNotification}). */
+/**
+ * A macOS-notification payload. `session` rides along so the click-through path
+ * ({@link terminalNotifierArgs}) can focus the right session on click.
+ */
 export interface SystemNotification {
   message: string;
+  session: string;
 }
 
 /** The verdict of {@link decideNotifications}. */
@@ -53,25 +70,58 @@ export interface NotifyDecision {
 
 /** The only two states worth pinging the user over. */
 const NOTIFY_STATES: ReadonlySet<AgentStatus> = new Set<AgentStatus>(["blocked", "done"]);
-/** Don't re-ping the same session+state more than once inside this window. */
+/**
+ * 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 const NOTIFY_DEBOUNCE_MS = 30_000;
+/** Cap the ping text so a macOS banner never truncates mid-word (banners clip ~200+). */
+export const NOTIFY_MAX_LEN = 120;
+
+/** PURE — the trailing clause for a notifiable state. */
+function statusPhrase(to: AgentStatus): string {
+  return to === "blocked" ? "needs input" : "finished";
+}
+
+/**
+ * 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 function notifyMessage(ev: NotifyEvent): string {
+  const agent = ev.agent && ev.agent.length > 0 ? ev.agent : "agent";
+  const where = ev.location && ev.location.length > 0 ? ev.location : ev.session;
+  const text = `${agent} ${ev.to} · ${where} — ${statusPhrase(ev.to)}`;
+  return text.length > NOTIFY_MAX_LEN ? `${text.slice(0, NOTIFY_MAX_LEN - 1)}…` : text;
+}
 
-/** PURE — the human-readable ping text for a notifiable state. */
-function notifyMessage(session: string, to: AgentStatus): string {
-  return to === "blocked" ? `⚠ ${session} needs you (blocked)` : `✓ ${session} finished (done)`;
+/**
+ * PURE — which states this user has opted into pinging on, from the
+ * `onBlocked`/`onDone` prefs. Empty when both are off (→ no notifications).
+ */
+export function enabledStates(prefs: NotificationPrefs): ReadonlySet<AgentStatus> {
+  const states = new Set<AgentStatus>();
+  if (prefs.onBlocked) states.add("blocked");
+  if (prefs.onDone) states.add("done");
+  return states;
 }
 
 /**
  * PURE — decide who to ping from this tick's transitions.
  *
  * Rules:
- *   - only `blocked` / `done` transitions qualify (working/idle etc. are noise);
- *   - DEBOUNCE: skip a session+state that fired within {@link NOTIFY_DEBOUNCE_MS};
+ *   - only states in `states` qualify (default {@link NOTIFY_STATES}; the caller
+ *     narrows it via {@link enabledStates} to honor `onBlocked`/`onDone`);
+ *   - DEBOUNCE: skip a session+state that fired within {@link NOTIFY_DEBOUNCE_MS}
+ *     — this is the flap guard (see {@link NOTIFY_DEBOUNCE_MS});
  *   - SUPPRESS the toast for any client already viewing that session (they can
  *     see the bar flip themselves) — 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).
+ *     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.
@@ -81,22 +131,23 @@ export function decideNotifications(
   clients: AttachedClient[],
   lastNotified: Map<string, number>,
   nowMs: number,
+  states: ReadonlySet<AgentStatus> = NOTIFY_STATES,
 ): NotifyDecision {
   const nextLastNotified = new Map(lastNotified);
   const toasts: ToastTarget[] = [];
   const system: SystemNotification[] = [];
   for (const ev of events) {
-    if (!NOTIFY_STATES.has(ev.to)) continue;
+    if (!states.has(ev.to)) continue;
     const key = `${ev.session}:${ev.to}`;
     const last = nextLastNotified.get(key);
     if (last !== undefined && nowMs - last < NOTIFY_DEBOUNCE_MS) continue;
     nextLastNotified.set(key, nowMs);
-    const message = notifyMessage(ev.session, ev.to);
+    const message = notifyMessage(ev);
     for (const c of clients) {
       if (c.session === ev.session) continue; // they're already looking at it
       toasts.push({ client: c.client, message });
     }
-    system.push({ message });
+    system.push({ message, session: ev.session });
   }
   return { toasts, system, nextLastNotified };
 }
@@ -137,47 +188,172 @@ export function sendToasts(toasts: ToastTarget[]): void {
   }
 }
 
+/** io — whether `terminal-notifier` is on PATH (enables click-through banners). */
+export function hasTerminalNotifier(): boolean {
+  try {
+    execFileSync("which", ["terminal-notifier"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** PURE — single-quote a string for safe interpolation into a `/bin/sh -c` command. */
+function shellSingleQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
 /**
- * io — fire a macOS notification via `osascript`. macOS-only (guarded), and
- * quotes/backslashes are escaped for the AppleScript string literal. Best-effort.
+ * PURE — the `terminal-notifier` argv for a click-through banner: clicking it
+ * runs `tmux switch-client -t <session>`, jumping the user's most-recent client
+ * straight to the session that needs them. (`switch-client` without `-c` targets
+ * the last-active client — the best we can do without knowing which terminal the
+ * click came from.)
  */
-export function sendSystemNotification(message: string): void {
+export function terminalNotifierArgs(n: SystemNotification): string[] {
+  return [
+    "-title",
+    "tmux-ide",
+    "-message",
+    n.message,
+    "-execute",
+    `tmux switch-client -t ${shellSingleQuote(n.session)}`,
+  ];
+}
+
+/**
+ * io — fire a macOS notification. macOS-only (guarded), best-effort. When
+ * `terminal-notifier` is available we use it for a CLICK-THROUGH banner
+ * ({@link terminalNotifierArgs}) that focuses the session on click; otherwise we
+ * fall back to `osascript`, whose `display notification` has NO click action —
+ * so on a stock machine the banner informs but can't be clicked to jump.
+ */
+export function sendSystemNotification(n: SystemNotification): void {
   if (process.platform !== "darwin") return;
-  const escaped = message.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
   try {
+    if (hasTerminalNotifier()) {
+      execFileSync("terminal-notifier", terminalNotifierArgs(n), { stdio: "ignore" });
+      return;
+    }
+    const escaped = n.message.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
     execFileSync("osascript", ["-e", `display notification "${escaped}" with title "tmux-ide"`], {
       stdio: "ignore",
     });
   } catch {
-    // osascript missing / notification blocked — never fatal
+    // osascript / terminal-notifier missing or notification blocked — never fatal
   }
 }
 
-/** User notification preferences (minimal, pre-M14). */
+/** A "quiet hours" window — banners are suppressed while the wall clock is inside it. */
+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;
+}
+
+/** User notification preferences. */
 export interface NotificationPrefs {
+  /** Master switch — false silences every channel. */
+  enabled: boolean;
+  /** In-terminal status-line toasts. */
   toast: boolean;
+  /** macOS system banners. */
   macos: boolean;
+  /** Ping when an agent goes `blocked`. */
+  onBlocked: boolean;
+  /** Ping when an agent goes `done`. */
+  onDone: boolean;
+  /** Optional local-time window that suppresses macOS banners (events still record). */
+  quietHours: QuietHours | null;
+}
+
+/** Defaults: enabled, tmux toasts on, macOS banners off, both states pinged, no quiet window. */
+export const DEFAULT_NOTIFICATION_PREFS: NotificationPrefs = {
+  enabled: true,
+  toast: true,
+  macos: false,
+  onBlocked: true,
+  onDone: true,
+  quietHours: null,
+};
+
+/** A plain object, or `{}` for anything that isn't one (arrays included). */
+function asObject(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+/** A boolean, else the default. */
+function pickBool(value: unknown, fallback: boolean): boolean {
+  return typeof value === "boolean" ? value : fallback;
 }
 
-/** Defaults: tmux toasts on, macOS notifications off. */
-export const DEFAULT_NOTIFICATION_PREFS: NotificationPrefs = { toast: true, macos: false };
+/** PURE — parse `HH:MM` to minutes-since-midnight, or null when malformed / out of range. */
+export function parseHHMM(value: unknown): number | null {
+  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;
+}
 
 /**
- * PURE — read `{ notifications: { toast, macos } }` out of a parsed config,
- * falling back to {@link DEFAULT_NOTIFICATION_PREFS} for anything missing or of
- * the wrong type. Delegates to the shared {@link parseAppConfig} so notification
- * parsing can't drift from the rest of the config.
+ * 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 function notificationPrefs(parsedConfig: unknown): NotificationPrefs {
-  return parseAppConfig(parsedConfig).notifications;
+export function inQuietHours(now: Date, quiet: QuietHours | null): boolean {
+  if (!quiet) return false;
+  const start = parseHHMM(quiet.start);
+  const end = parseHHMM(quiet.end);
+  if (start === null || end === null || start === end) return false;
+  const nowMin = now.getHours() * 60 + now.getMinutes();
+  return start < end ? nowMin >= start && nowMin < end : nowMin >= start || nowMin < end;
 }
 
-/** PURE — the `TMUX_IDE_NOTIFY=0` kill-switch: disables both channels. */
+/** PURE — parse a `{ start, end }` quiet-hours block, or null when absent / malformed. */
+function parseQuietHours(value: unknown): QuietHours | null {
+  const o = asObject(value);
+  const start = typeof o.start === "string" ? o.start : null;
+  const end = typeof o.end === "string" ? o.end : null;
+  if (start === null || end === null) return null;
+  if (parseHHMM(start) === null || parseHHMM(end) === null) return null;
+  return { start, end };
+}
+
+/**
+ * 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 function parseNotificationPrefs(rawConfig: unknown): NotificationPrefs {
+  const base = parseAppConfig(rawConfig).notifications;
+  const n = asObject(asObject(rawConfig).notifications);
+  return {
+    enabled: pickBool(n.enabled, DEFAULT_NOTIFICATION_PREFS.enabled),
+    toast: base.toast,
+    macos: base.macos,
+    onBlocked: pickBool(n.onBlocked, DEFAULT_NOTIFICATION_PREFS.onBlocked),
+    onDone: pickBool(n.onDone, DEFAULT_NOTIFICATION_PREFS.onDone),
+    quietHours: parseQuietHours(n.quietHours),
+  };
+}
+
+/** PURE — the `TMUX_IDE_NOTIFY=0` kill-switch: disables everything. */
 export function applyKillSwitch(
   prefs: NotificationPrefs,
   envValue: string | undefined,
 ): NotificationPrefs {
-  return envValue === "0" ? { toast: false, macos: false } : prefs;
+  return envValue === "0" ? { ...prefs, enabled: false, toast: false, macos: false } : prefs;
 }
 
 /** Absolute path to the shared config (honors `TMUX_IDE_CONFIG`). */
@@ -185,11 +361,22 @@ export function notifyConfigPath(): string {
   return appConfigPath();
 }
 
+/** io — read + JSON-parse the raw config file; undefined when missing / malformed. */
+function readRawConfig(): unknown {
+  const path = appConfigPath();
+  if (!existsSync(path)) return undefined;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * 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 is honored each call.
+ * fresh so the env kill-switch and config edits are honored each call.
  */
 export function readNotificationPrefs(): NotificationPrefs {
-  return applyKillSwitch(loadAppConfig().notifications, process.env.TMUX_IDE_NOTIFY);
+  return applyKillSwitch(parseNotificationPrefs(readRawConfig()), process.env.TMUX_IDE_NOTIFY);
 }