claude-mission-control 1.5.0

package/lib/config.js

@@ -0,0 +1,203 @@
+'use strict';
+// User configuration: config.json (general), names.json (display names),
+// ignore.json (hidden path prefixes). All read fresh-by-mtime and written
+// pretty-printed so hand-editing stays pleasant.
+const fs = require('fs');
+const path = require('path');
+const { canonicalize } = require('./paths');
+
+const ROOT = path.join(__dirname, '..');
+
+// Config lives beside the code when that's writable (git checkout — the
+// original layout). Under npx / a global npm install the package dir may be
+// read-only or ephemeral, so fall back to ~/.config/claude-dashboard.
+// CLAUDE_DASH_CONFIG_DIR overrides both.
+function resolveConfigDir() {
+  const os = require('os');
+  const env = process.env.CLAUDE_DASH_CONFIG_DIR;
+  if (env) {
+    fs.mkdirSync(env, { recursive: true });
+    return env;
+  }
+  try {
+    fs.accessSync(ROOT, fs.constants.W_OK);
+    return ROOT;
+  } catch {
+    const dir = path.join(os.homedir(), '.config', 'claude-dashboard');
+    fs.mkdirSync(dir, { recursive: true });
+    return dir;
+  }
+}
+const CONFIG_DIR = resolveConfigDir();
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+const NAMES_FILE = path.join(CONFIG_DIR, 'names.json');
+const IGNORE_FILE = path.join(CONFIG_DIR, 'ignore.json');
+
+const DEFAULTS = { terminal: 'ghostty', notifications: true, usageApi: true, mutedProjects: [], weeklyBudget: 0, pinnedSessions: [] };
+
+function readJson(file, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJson(file, value) {
+  fs.writeFileSync(file, JSON.stringify(value, null, 2) + '\n');
+}
+
+function readConfig() {
+  return { ...DEFAULTS, ...readJson(CONFIG_FILE, {}) };
+}
+
+function updateConfig(patch) {
+  const next = { ...readConfig() };
+  if (typeof patch.terminal === 'string') next.terminal = patch.terminal;
+  if (typeof patch.notifications === 'boolean') next.notifications = patch.notifications;
+  if (typeof patch.usageApi === 'boolean') next.usageApi = patch.usageApi;
+  if (typeof patch.weeklyBudget === 'number' && patch.weeklyBudget >= 0 && Number.isFinite(patch.weeklyBudget)) {
+    next.weeklyBudget = Math.round(patch.weeklyBudget);
+  }
+  writeJson(CONFIG_FILE, next);
+  return next;
+}
+
+// Add or remove a project from the notification mute list.
+function setProjectMuted(projectPath, muted) {
+  const next = { ...readConfig() };
+  const key = canonicalize(projectPath);
+  const list = (next.mutedProjects || []).filter((p) => canonicalize(p).toLowerCase() !== key.toLowerCase());
+  if (muted) list.push(key);
+  next.mutedProjects = list;
+  writeJson(CONFIG_FILE, next);
+  return next;
+}
+
+// Pin or unpin a session for the pinned strip. Returns the new pinned state.
+function togglePin(sessionId) {
+  const next = { ...readConfig() };
+  const list = next.pinnedSessions || [];
+  const has = list.includes(sessionId);
+  next.pinnedSessions = has ? list.filter((id) => id !== sessionId) : [...list, sessionId];
+  writeJson(CONFIG_FILE, next);
+  return !has;
+}
+
+function readNames() {
+  return readJson(NAMES_FILE, {});
+}
+
+function setName(projectPath, name) {
+  const names = readNames();
+  const key = canonicalize(projectPath);
+  // Stored keys may differ in case from the canonical path — replace any match.
+  for (const k of Object.keys(names)) {
+    if (canonicalize(k).toLowerCase() === key.toLowerCase()) delete names[k];
+  }
+  if (name && name.trim()) names[key] = name.trim().slice(0, 80);
+  writeJson(NAMES_FILE, names);
+}
+
+function readIgnores() {
+  const raw = readJson(IGNORE_FILE, []);
+  return Array.isArray(raw) ? raw : [];
+}
+
+function addIgnore(prefix) {
+  const list = readIgnores();
+  const key = canonicalize(prefix);
+  if (!list.some((p) => canonicalize(p).toLowerCase() === key.toLowerCase())) {
+    list.push(key);
+    writeJson(IGNORE_FILE, list);
+  }
+}
+
+function removeIgnore(prefix) {
+  const key = canonicalize(prefix).toLowerCase();
+  writeJson(IGNORE_FILE, readIgnores().filter((p) => canonicalize(p).toLowerCase() !== key));
+}
+
+// Walk PATH for a binary; `exists` injected so the walk is unit-testable.
+function findOnPath(name, pathEnv = process.env.PATH || '', exists = fs.existsSync) {
+  for (const dir of String(pathEnv).split(path.delimiter)) {
+    if (!dir) continue;
+    const p = path.join(dir, name);
+    if (exists(p)) return p;
+  }
+  return null;
+}
+
+const LINUX_TERMINALS = [
+  { id: 'kitty', label: 'kitty' },
+  { id: 'alacritty', label: 'Alacritty' },
+  { id: 'gnome-terminal', label: 'GNOME Terminal' },
+  { id: 'konsole', label: 'Konsole' },
+  { id: 'xterm', label: 'xterm' },
+];
+
+// Terminals we know how to launch, filtered to what's installed.
+function detectTerminals() {
+  if (process.platform === 'linux') {
+    return LINUX_TERMINALS.filter((t) => findOnPath(t.id));
+  }
+  if (process.platform === 'win32') {
+    const wtPath = path.join(
+      process.env.LOCALAPPDATA || '', 'Microsoft', 'WindowsApps', 'wt.exe'
+    );
+    const out = [];
+    if (fs.existsSync(wtPath)) out.push({ id: 'wt', label: 'Windows Terminal' });
+    out.push({ id: 'powershell', label: 'PowerShell' });
+    out.push({ id: 'cmd', label: 'Command Prompt' });
+    return out;
+  }
+  const home = process.env.HOME || '';
+  const candidates = [
+    { id: 'ghostty', label: 'Ghostty', app: 'Ghostty.app' },
+    { id: 'iterm', label: 'iTerm2', app: 'iTerm.app' },
+    { id: 'terminal', label: 'Terminal.app', app: null }, // always present on macOS
+  ];
+  return candidates.filter(
+    (c) =>
+      !c.app ||
+      fs.existsSync(path.join('/Applications', c.app)) ||
+      fs.existsSync(path.join(home, 'Applications', c.app))
+  );
+}
+
+function detectClaudeApp() {
+  if (process.platform === 'win32') {
+    return fs.existsSync(
+      path.join(process.env.LOCALAPPDATA || '', 'AnthropicClaude')
+    );
+  }
+  const home = process.env.HOME || '';
+  return (
+    fs.existsSync('/Applications/Claude.app') ||
+    fs.existsSync(path.join(home, 'Applications', 'Claude.app'))
+  );
+}
+
+// The terminal that will actually be used: configured if installed, else the
+// first installed one.
+function resolvedTerminal() {
+  const installed = detectTerminals();
+  const configured = readConfig().terminal;
+  return installed.find((t) => t.id === configured) || installed[0] || { id: 'terminal', label: 'Terminal.app' };
+}
+
+module.exports = {
+  readConfig,
+  findOnPath,
+  detectClaudeApp,
+  resolvedTerminal,
+  updateConfig,
+  setProjectMuted,
+  togglePin,
+  readNames,
+  setName,
+  readIgnores,
+  addIgnore,
+  removeIgnore,
+  detectTerminals,
+};

package/lib/detail.js

@@ -0,0 +1,134 @@
+'use strict';
+// On-demand project detail: CLAUDE.md files, per-project memory, skills/
+// agents/commands, and settings. Read-only; every read is confined to the
+// project root or that project's memory dir under ~/.claude.
+const fsp = require('fs/promises');
+const path = require('path');
+const { CLAUDE_DIR, canonicalize, encodeProjectDir } = require('./paths');
+
+const MAX_FILE_BYTES = 64 * 1024; // per-file cap for returned content
+
+async function readCapped(abs) {
+  try {
+    const st = await fsp.stat(abs);
+    if (!st.isFile()) return null;
+    const fh = await fsp.open(abs, 'r');
+    try {
+      const len = Math.min(st.size, MAX_FILE_BYTES);
+      const buf = Buffer.alloc(len);
+      await fh.read(buf, 0, len, 0);
+      let content = buf.toString('utf8');
+      if (st.size > MAX_FILE_BYTES) content += `\n\n… truncated (${st.size} bytes total)`;
+      return { content, size: st.size, mtimeMs: st.mtimeMs };
+    } finally {
+      await fh.close();
+    }
+  } catch {
+    return null;
+  }
+}
+
+async function listMd(dir) {
+  try {
+    const names = await fsp.readdir(dir);
+    return names.filter((n) => n.endsWith('.md')).sort();
+  } catch {
+    return [];
+  }
+}
+
+// First `description:` line of YAML frontmatter, if any.
+function frontmatterDescription(content) {
+  if (!content || !content.startsWith('---')) return null;
+  const end = content.indexOf('\n---', 3);
+  if (end === -1) return null;
+  const m = content.slice(0, end).match(/^description:\s*(.+)$/m);
+  return m ? m[1].trim().replace(/^["']|["']$/g, '').slice(0, 300) : null;
+}
+
+// Skills are directories containing SKILL.md; agents/commands are .md files.
+async function collectCapabilities(root) {
+  const base = path.join(root, '.claude');
+  const out = { skills: [], agents: [], commands: [] };
+
+  try {
+    for (const entry of await fsp.readdir(path.join(base, 'skills'), { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const skillMd = await readCapped(path.join(base, 'skills', entry.name, 'SKILL.md'));
+      out.skills.push({
+        name: entry.name,
+        description: skillMd ? frontmatterDescription(skillMd.content) : null,
+        content: skillMd ? skillMd.content : null,
+      });
+    }
+  } catch { /* no skills dir */ }
+
+  for (const kind of ['agents', 'commands']) {
+    for (const name of await listMd(path.join(base, kind))) {
+      const file = await readCapped(path.join(base, kind, name));
+      out[kind].push({
+        name: name.replace(/\.md$/, ''),
+        description: file ? frontmatterDescription(file.content) : null,
+        content: file ? file.content : null,
+      });
+    }
+  }
+  return out;
+}
+
+async function collectSettings(root) {
+  const out = {};
+  for (const [key, rel] of [
+    ['settings', '.claude/settings.json'],
+    ['settingsLocal', '.claude/settings.local.json'],
+    ['mcpJson', '.mcp.json'],
+  ]) {
+    const f = await readCapped(path.join(root, rel));
+    if (f) out[key] = f.content;
+  }
+  // Per-project entry in Claude's own registry: MCP servers + allowed tools.
+  try {
+    const reg = JSON.parse(await fsp.readFile(path.join(CLAUDE_DIR, '..', '.claude.json'), 'utf8'));
+    for (const [p, info] of Object.entries(reg.projects || {})) {
+      if (canonicalize(p).toLowerCase() !== canonicalize(root).toLowerCase()) continue;
+      if (info.mcpServers && Object.keys(info.mcpServers).length) {
+        out.mcpServers = Object.keys(info.mcpServers);
+      }
+      if (Array.isArray(info.allowedTools) && info.allowedTools.length) {
+        out.allowedTools = info.allowedTools;
+      }
+      break;
+    }
+  } catch { /* registry unreadable */ }
+  return out;
+}
+
+async function collectMemory(root) {
+  const memDir = path.join(CLAUDE_DIR, 'projects', encodeProjectDir(root), 'memory');
+  const files = [];
+  for (const name of await listMd(memDir)) {
+    const f = await readCapped(path.join(memDir, name));
+    if (f) files.push({ name, content: f.content, mtimeMs: f.mtimeMs });
+  }
+  // MEMORY.md (the index) first, then newest first.
+  files.sort((a, b) =>
+    a.name === 'MEMORY.md' ? -1 : b.name === 'MEMORY.md' ? 1 : b.mtimeMs - a.mtimeMs
+  );
+  return files;
+}
+
+async function projectDetail(root) {
+  const claudeMd = [];
+  for (const name of ['CLAUDE.md', 'CLAUDE.local.md']) {
+    const f = await readCapped(path.join(root, name));
+    if (f) claudeMd.push({ name, content: f.content });
+  }
+  const [capabilities, settings, memory] = await Promise.all([
+    collectCapabilities(root),
+    collectSettings(root),
+    collectMemory(root),
+  ]);
+  return { path: root, claudeMd, memory, ...capabilities, settings };
+}
+
+module.exports = { projectDetail };

package/lib/gitstatus.js

@@ -0,0 +1,84 @@
+'use strict';
+// Git status per project via `git -C <path> status --porcelain=v2 --branch`.
+// execFile arg-arrays only (paths contain spaces). Keeps last good values.
+const { execFile } = require('child_process');
+const fs = require('fs/promises');
+const path = require('path');
+
+const lastGood = new Map(); // projectPath -> git object
+
+async function isGitRepo(projectPath) {
+  try {
+    // .git is a dir in normal repos, a FILE in worktrees.
+    await fs.stat(path.join(projectPath, '.git'));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function runGitStatus(projectPath) {
+  return new Promise((resolve) => {
+    execFile(
+      'git',
+      ['-C', projectPath, 'status', '--porcelain=v2', '--branch'],
+      { timeout: 4000, maxBuffer: 4 * 1024 * 1024 },
+      (err, stdout) => {
+        if (err) {
+          const prev = lastGood.get(projectPath);
+          resolve(prev ? { ...prev, error: shortErr(err) } : { isRepo: true, error: shortErr(err) });
+          return;
+        }
+        const git = parsePorcelainV2(stdout);
+        lastGood.set(projectPath, git);
+        resolve(git);
+      }
+    );
+  });
+}
+
+function parsePorcelainV2(text) {
+  const git = { isRepo: true, branch: null, dirty: 0, untracked: 0, ahead: null, behind: null, error: null };
+  for (const line of text.split('\n')) {
+    if (line.startsWith('# branch.head ')) {
+      const h = line.slice('# branch.head '.length).trim();
+      git.branch = h === '(detached)' ? '(detached)' : h;
+    } else if (line.startsWith('# branch.ab ')) {
+      const m = line.match(/\+(\d+) -(\d+)/);
+      if (m) {
+        git.ahead = Number(m[1]);
+        git.behind = Number(m[2]);
+      }
+    } else if (line.startsWith('1 ') || line.startsWith('2 ') || line.startsWith('u ')) {
+      git.dirty++;
+    } else if (line.startsWith('? ')) {
+      git.untracked++;
+    }
+  }
+  return git;
+}
+
+function shortErr(err) {
+  const msg = String(err.message || err).split('\n')[0];
+  return msg.slice(0, 120);
+}
+
+// Pooled: at most 3 concurrent git processes.
+async function collectGitStatus(projectPaths) {
+  const results = new Map();
+  const queue = [...projectPaths];
+  const workers = Array.from({ length: 3 }, async () => {
+    while (queue.length) {
+      const p = queue.shift();
+      if (!(await isGitRepo(p))) {
+        results.set(p, { isRepo: false });
+        continue;
+      }
+      results.set(p, await runGitStatus(p));
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+
+module.exports = { collectGitStatus, parsePorcelainV2 };

package/lib/history.js

@@ -0,0 +1,103 @@
+'use strict';
+// Incremental reader for ~/.claude/history.jsonl (append-only prompt log).
+// Keeps per-project timestamps (90 days) + total counts in memory.
+const fs = require('fs/promises');
+const path = require('path');
+const { CLAUDE_DIR, worktreeRoot } = require('./paths');
+
+const HISTORY_FILE = path.join(CLAUDE_DIR, 'history.jsonl');
+const KEEP_MS = 400 * 24 * 60 * 60 * 1000; // enough for a year-ish heatmap
+
+const state = {
+  offset: 0,
+  partial: '',
+  // lowercaseProjectPath -> { timestamps: number[], promptCount, lastPrompt, lastTimestamp }
+  byProject: new Map(),
+};
+
+async function refreshHistory() {
+  let st;
+  try {
+    st = await fs.stat(HISTORY_FILE);
+  } catch {
+    return state.byProject;
+  }
+  if (st.size < state.offset) {
+    // truncated/rotated: start over
+    state.offset = 0;
+    state.partial = '';
+    state.byProject.clear();
+  }
+  if (st.size === state.offset) return state.byProject;
+
+  const fh = await fs.open(HISTORY_FILE, 'r');
+  try {
+    const len = st.size - state.offset;
+    const buf = Buffer.alloc(len);
+    await fh.read(buf, 0, len, state.offset);
+    state.offset = st.size;
+    const text = state.partial + buf.toString('utf8');
+    const lines = text.split('\n');
+    state.partial = lines.pop() || ''; // last element may be a partial line
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      let rec;
+      try {
+        rec = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (!rec.project || !rec.timestamp) continue;
+      const { root } = worktreeRoot(rec.project);
+      const key = root.toLowerCase();
+      let e = state.byProject.get(key);
+      if (!e) {
+        e = { path: root, timestamps: [], promptCount: 0, lastPrompt: null, lastTimestamp: 0 };
+        state.byProject.set(key, e);
+      }
+      e.promptCount++;
+      if (rec.timestamp >= e.lastTimestamp) {
+        e.lastTimestamp = rec.timestamp;
+        e.lastPrompt = typeof rec.display === 'string' ? rec.display.slice(0, 200) : null;
+      }
+      if (Date.now() - rec.timestamp < KEEP_MS) e.timestamps.push(rec.timestamp);
+    }
+  } finally {
+    await fh.close();
+  }
+  // prune old timestamps occasionally
+  const cutoff = Date.now() - KEEP_MS;
+  for (const e of state.byProject.values()) {
+    if (e.timestamps.length && e.timestamps[0] < cutoff) {
+      e.timestamps = e.timestamps.filter((t) => t >= cutoff);
+    }
+  }
+  return state.byProject;
+}
+
+// Daily prompt counts for the last `days` local days, oldest -> newest.
+function activityBuckets(timestamps, days = 14) {
+  const counts = new Array(days).fill(0);
+  const midnight = new Date();
+  midnight.setHours(0, 0, 0, 0);
+  const todayStart = midnight.getTime();
+  const DAY = 24 * 60 * 60 * 1000;
+  for (const t of timestamps) {
+    const daysAgo = t >= todayStart ? 0 : Math.ceil((todayStart - t) / DAY);
+    const slot = days - 1 - daysAgo;
+    if (slot >= 0 && slot < days) counts[slot]++;
+  }
+  return counts;
+}
+
+// 7×24 grid of prompt counts by [dayOfWeek][hour], Sunday-first, local time.
+function weekHourHeat(timestamps) {
+  const heat = Array.from({ length: 7 }, () => new Array(24).fill(0));
+  for (const t of timestamps) {
+    const d = new Date(t);
+    heat[d.getDay()][d.getHours()]++;
+  }
+  return heat;
+}
+
+module.exports = { refreshHistory, activityBuckets, weekHourHeat };

package/lib/ignore.js

@@ -0,0 +1,42 @@
+'use strict';
+// User-editable ignore list: ignore.json is an array of absolute path prefixes.
+// A project is hidden if its path equals a prefix or sits anywhere under it.
+// Hides from the dashboard only — nothing on disk or in ~/.claude is touched.
+const fs = require('fs');
+const path = require('path');
+const { canonicalize } = require('./paths');
+
+const IGNORE_FILE = path.join(__dirname, '..', 'ignore.json');
+
+let cache = { mtimeMs: 0, prefixes: [] };
+
+function loadIgnores() {
+  try {
+    const st = fs.statSync(IGNORE_FILE);
+    if (st.mtimeMs !== cache.mtimeMs) {
+      const raw = JSON.parse(fs.readFileSync(IGNORE_FILE, 'utf8'));
+      const prefixes = (Array.isArray(raw) ? raw : [])
+        .map((p) => canonicalize(String(p)).toLowerCase())
+        .filter(Boolean);
+      cache = { mtimeMs: st.mtimeMs, prefixes };
+    }
+  } catch {
+    cache = { mtimeMs: 0, prefixes: [] };
+  }
+  return cache.prefixes;
+}
+
+// Pure prefix matcher (prefixes pre-lowercased) — unit-testable.
+function matchesPrefix(projectPath, prefixes) {
+  const p = canonicalize(projectPath).toLowerCase();
+  for (const prefix of prefixes) {
+    if (p === prefix || p.startsWith(prefix + '/')) return true;
+  }
+  return false;
+}
+
+function isIgnored(projectPath) {
+  return matchesPrefix(projectPath, loadIgnores());
+}
+
+module.exports = { isIgnored, matchesPrefix };

package/lib/names.js

@@ -0,0 +1,54 @@
+'use strict';
+// Friendly project names: names.json exact match, else a cleaned-up basename.
+const fs = require('fs');
+const path = require('path');
+const { canonicalize } = require('./paths');
+
+const NAMES_FILE = path.join(__dirname, '..', 'names.json');
+
+let cache = { mtimeMs: 0, map: {} };
+
+function loadNames() {
+  try {
+    const st = fs.statSync(NAMES_FILE);
+    if (st.mtimeMs !== cache.mtimeMs) {
+      const raw = JSON.parse(fs.readFileSync(NAMES_FILE, 'utf8'));
+      const map = {};
+      for (const [k, v] of Object.entries(raw)) map[canonicalize(k).toLowerCase()] = v;
+      cache = { mtimeMs: st.mtimeMs, map };
+    }
+  } catch {
+    cache = { mtimeMs: 0, map: {} };
+  }
+  return cache.map;
+}
+
+// Segments that are scaffolding, not identity. Walk up past them so
+// "/Users/x/Local Sites/jonimms/app/public" names as "jonimms".
+const GENERIC = new Set(['app', 'public', 'wp-content', 'themes', 'plugins', 'src', 'site']);
+
+function displayBase(p) {
+  const parts = canonicalize(p).split(path.sep).filter(Boolean);
+  for (let i = parts.length - 1; i >= 0; i--) {
+    if (!GENERIC.has(parts[i].toLowerCase())) return parts[i];
+  }
+  return parts[parts.length - 1] || p;
+}
+
+function titleCase(s) {
+  return s
+    .replace(/[-_]+/g, ' ')
+    .split(' ')
+    .filter(Boolean)
+    .map((w) => (/[A-Z]/.test(w.slice(1)) ? w : w[0].toUpperCase() + w.slice(1)))
+    .join(' ');
+}
+
+function friendlyName(projectPath) {
+  const map = loadNames();
+  const hit = map[canonicalize(projectPath).toLowerCase()];
+  if (hit) return hit;
+  return titleCase(displayBase(projectPath));
+}
+
+module.exports = { friendlyName, displayBase, titleCase };

package/lib/notify.js

@@ -0,0 +1,62 @@
+'use strict';
+// macOS notifications via osascript — no dependencies, no signing.
+// Disable with CLAUDE_DASH_NOTIFY=0.
+const { execFile } = require('child_process');
+const { readConfig } = require('./config');
+const { canonicalize } = require('./paths');
+
+function notificationsEnabled() {
+  if (process.env.CLAUDE_DASH_NOTIFY === '0') return false;
+  return readConfig().notifications !== false;
+}
+
+function aq(s) {
+  // AppleScript string literal: escape backslash and double quote.
+  return String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+function sendNotification({ title, body, sound }) {
+  if (!notificationsEnabled()) return;
+  if (process.platform === 'darwin') {
+    const script =
+      `display notification "${aq(body)}" with title "${aq(title)}"` +
+      (sound ? ` sound name "${aq(sound)}"` : '');
+    execFile('osascript', ['-e', script], { timeout: 5000 }, () => {});
+  } else if (process.platform === 'win32') {
+    // Windows toast via WinRT — no modules required. Untested; best effort.
+    const esc = (s) => String(s).replace(/'/g, "''").replace(/[\r\n]+/g, ' ');
+    const ps = `
+$null = [Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime]
+$xml = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02)
+$t = $xml.GetElementsByTagName('text')
+$null = $t.Item(0).AppendChild($xml.CreateTextNode('${esc(title)}'))
+$null = $t.Item(1).AppendChild($xml.CreateTextNode('${esc(body)}'))
+[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('Claude Dashboard').Show([Windows.UI.Notifications.ToastNotification]::new($xml))`;
+    execFile('powershell', ['-NoProfile', '-NonInteractive', '-Command', ps], { timeout: 8000 }, () => {});
+  } else {
+    execFile('notify-send', [title, body], { timeout: 5000 }, () => {});
+  }
+}
+
+// Pure transition detector so it's unit-testable.
+// prev/next: Map<sessionId, status>; prev === null means first poll after
+// startup — never notify then, or every restart would replay notifications.
+// A session unseen in prev but waiting in next DOES notify (it went waiting
+// between polls).
+function newlyWaiting(prev, next) {
+  if (prev === null) return [];
+  const out = [];
+  for (const [id, status] of next) {
+    if (status === 'waiting' && prev.get(id) !== 'waiting') out.push(id);
+  }
+  return out;
+}
+
+// Per-project mute: compare canonical, lowercased roots.
+function isProjectMuted(root, mutedProjects) {
+  if (!Array.isArray(mutedProjects) || !mutedProjects.length) return false;
+  const key = canonicalize(root).toLowerCase();
+  return mutedProjects.some((p) => canonicalize(p).toLowerCase() === key);
+}
+
+module.exports = { sendNotification, newlyWaiting, isProjectMuted };