ai-agent-session-center 1.0.0

package/server/hookStats.js

@@ -0,0 +1,107 @@
+// hookStats.js — In-memory hook performance statistics
+// Tracks delivery latency, server processing time, and throughput per event type.
+// Stats are broadcast to the dashboard via WebSocket.
+
+const ROLLING_WINDOW = 200; // keep last N samples per event type
+const RATE_WINDOW_MS = 60_000; // 1 minute for hooks/min calculation
+
+// Per event type: { count, latencies: [], processingTimes: [], timestamps: [] }
+const byEvent = {};
+// Global totals
+let totalHooks = 0;
+const globalTimestamps = []; // for hooks/min rate
+
+function ensureEvent(eventType) {
+  if (!byEvent[eventType]) {
+    byEvent[eventType] = {
+      count: 0,
+      latencies: [],       // delivery latency (hook_sent_at → server received), ms
+      processingTimes: [],  // server handleEvent() duration, ms
+      timestamps: [],       // for per-event rate
+    };
+  }
+  return byEvent[eventType];
+}
+
+/**
+ * Record a hook event's timing.
+ * @param {string} eventType - e.g. 'PreToolUse', 'Stop'
+ * @param {number|null} deliveryLatencyMs - hook_sent_at → server received (null if no timestamp)
+ * @param {number} processingTimeMs - server handleEvent() duration
+ */
+export function recordHook(eventType, deliveryLatencyMs, processingTimeMs) {
+  const now = Date.now();
+  totalHooks++;
+
+  // Global rate tracking
+  globalTimestamps.push(now);
+  while (globalTimestamps.length > 0 && now - globalTimestamps[0] > RATE_WINDOW_MS) {
+    globalTimestamps.shift();
+  }
+
+  const ev = ensureEvent(eventType);
+  ev.count++;
+  ev.timestamps.push(now);
+
+  if (deliveryLatencyMs !== null && deliveryLatencyMs >= 0) {
+    ev.latencies.push(deliveryLatencyMs);
+    if (ev.latencies.length > ROLLING_WINDOW) ev.latencies.shift();
+  }
+
+  ev.processingTimes.push(processingTimeMs);
+  if (ev.processingTimes.length > ROLLING_WINDOW) ev.processingTimes.shift();
+
+  // Trim timestamps
+  while (ev.timestamps.length > 0 && now - ev.timestamps[0] > RATE_WINDOW_MS) {
+    ev.timestamps.shift();
+  }
+}
+
+function calcStats(arr) {
+  if (arr.length === 0) return { avg: 0, min: 0, max: 0, p95: 0 };
+  const sorted = [...arr].sort((a, b) => a - b);
+  const sum = sorted.reduce((a, b) => a + b, 0);
+  return {
+    avg: Math.round(sum / sorted.length),
+    min: sorted[0],
+    max: sorted[sorted.length - 1],
+    p95: sorted[Math.floor(sorted.length * 0.95)],
+  };
+}
+
+/**
+ * Get current hook stats snapshot for API/WebSocket.
+ */
+export function getStats() {
+  const now = Date.now();
+  const events = {};
+
+  for (const [eventType, ev] of Object.entries(byEvent)) {
+    // Count hooks in last minute for per-event rate
+    const recentCount = ev.timestamps.filter(t => now - t < RATE_WINDOW_MS).length;
+    events[eventType] = {
+      count: ev.count,
+      rate: recentCount, // hooks in last minute
+      latency: calcStats(ev.latencies),
+      processing: calcStats(ev.processingTimes),
+    };
+  }
+
+  return {
+    totalHooks,
+    hooksPerMin: globalTimestamps.filter(t => now - t < RATE_WINDOW_MS).length,
+    events,
+    sampledAt: now,
+  };
+}
+
+/**
+ * Reset all stats (for testing or manual reset).
+ */
+export function resetStats() {
+  totalHooks = 0;
+  globalTimestamps.length = 0;
+  for (const key of Object.keys(byEvent)) {
+    delete byEvent[key];
+  }
+}

package/server/index.js

@@ -0,0 +1,314 @@
+// index.js — Express + WS server entry point
+// Quick start: npm start → auto-installs hooks, starts server, opens browser
+import express from 'express';
+import { createServer } from 'http';
+import { WebSocketServer } from 'ws';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { homedir } from 'os';
+import { execSync } from 'child_process';
+import { copyFileSync, chmodSync, mkdirSync, readFileSync, writeFileSync, existsSync } from 'fs';
+import hookRouter from './hookRouter.js';
+import { handleConnection, broadcast } from './wsManager.js';
+import { getAllSessions } from './sessionStore.js';
+import apiRouter from './apiRouter.js';
+import { startMqReader, stopMqReader } from './mqReader.js';
+import log from './logger.js';
+import { config } from './serverConfig.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const args = process.argv.slice(2);
+const noOpen = args.includes('--no-open');
+
+const app = express();
+const server = createServer(app);
+const wss = new WebSocketServer({ server });
+
+app.use(express.json({ limit: '10mb' }));
+app.use(express.static(join(__dirname, '..', 'public')));
+app.use('/api', apiRouter);
+app.use('/api/hooks', hookRouter);
+app.get('/api/sessions', (req, res) => {
+  log.debug('api', 'GET /api/sessions');
+  res.json(getAllSessions());
+});
+
+// Request logging middleware (debug mode only)
+if (log.isDebug) {
+  app.use((req, res, next) => {
+    const start = Date.now();
+    res.on('finish', () => {
+      log.debug('http', `${req.method} ${req.originalUrl} ${res.statusCode} ${Date.now() - start}ms`);
+    });
+    next();
+  });
+}
+
+wss.on('connection', handleConnection);
+wss.on('error', () => {}); // Suppress WSS re-emit; handled on HTTP server
+
+// Port priority: --port flag > PORT env > config file > 3333
+function resolvePort() {
+  const portArgIdx = args.indexOf('--port');
+  if (portArgIdx >= 0 && args[portArgIdx + 1]) {
+    const p = parseInt(args[portArgIdx + 1], 10);
+    if (p > 0) return p;
+  }
+  if (process.env.PORT) {
+    const p = parseInt(process.env.PORT, 10);
+    if (p > 0) return p;
+  }
+  return config.port || 3333;
+}
+
+const PORT = resolvePort();
+
+function killPortProcess(port) {
+  try {
+    if (process.platform === 'win32') {
+      const output = execSync(
+        `netstat -ano | findstr :${port} | findstr LISTENING`,
+        { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+      );
+      const pids = [...new Set(
+        output.trim().split('\n')
+          .map(line => line.trim().split(/\s+/).pop())
+          .filter(Boolean)
+      )];
+      for (const pid of pids) {
+        try { execSync(`taskkill /F /PID ${pid}`, { stdio: 'pipe' }); } catch {}
+      }
+    } else {
+      // macOS & Linux
+      const output = execSync(`lsof -ti:${port}`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+      const pids = output.trim().split('\n').filter(Boolean);
+      for (const pid of pids) {
+        try { process.kill(Number(pid), 'SIGTERM'); } catch {}
+      }
+    }
+  } catch {
+    // No process found on port — nothing to kill
+  }
+}
+
+// ── Hook auto-install ──
+// Copies hook scripts and registers hooks for all enabled CLIs
+// Runs on every startup so users never need to manually install hooks
+function ensureHooksInstalled() {
+  const isWindows = process.platform === 'win32';
+  const hookPattern = 'dashboard-hook';
+  const hookSource = 'ai-agent-session-center';
+
+  // Read saved config
+  let density = 'medium';
+  let enabledClis = ['claude'];
+  try {
+    const serverConfig = JSON.parse(readFileSync(join(__dirname, '..', 'data', 'server-config.json'), 'utf8'));
+    if (serverConfig.hookDensity) density = serverConfig.hookDensity;
+    if (serverConfig.enabledClis) enabledClis = serverConfig.enabledClis;
+  } catch {}
+
+  // ── Claude Code hooks ──
+  if (enabledClis.includes('claude')) {
+    const hookName = isWindows ? 'dashboard-hook.ps1' : 'dashboard-hook.sh';
+    const hookCommand = isWindows
+      ? `powershell -NoProfile -ExecutionPolicy Bypass -File "~/.claude/hooks/${hookName}"`
+      : '~/.claude/hooks/dashboard-hook.sh';
+    const src = join(__dirname, '..', 'hooks', hookName);
+    const hooksDir = join(homedir(), '.claude', 'hooks');
+    const dest = join(hooksDir, hookName);
+    const settingsPath = join(homedir(), '.claude', 'settings.json');
+
+    // Copy hook script
+    syncHookFile(src, dest, hooksDir, isWindows, 'claude');
+
+    // Register in settings.json
+    const densityEvents = {
+      high: ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'PostToolUseFailure', 'PermissionRequest', 'Stop', 'Notification', 'SubagentStart', 'SubagentStop', 'TeammateIdle', 'TaskCompleted', 'PreCompact', 'SessionEnd'],
+      medium: ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'PostToolUseFailure', 'PermissionRequest', 'Stop', 'Notification', 'SubagentStart', 'SubagentStop', 'TaskCompleted', 'SessionEnd'],
+      low: ['SessionStart', 'UserPromptSubmit', 'PermissionRequest', 'Stop', 'SessionEnd'],
+    };
+    const events = densityEvents[density] || densityEvents.medium;
+
+    try {
+      let settings;
+      try { settings = JSON.parse(readFileSync(settingsPath, 'utf8')); } catch { settings = {}; }
+      if (!settings.hooks) settings.hooks = {};
+
+      let changed = false;
+      for (const event of events) {
+        if (!settings.hooks[event]) settings.hooks[event] = [];
+        const hasHook = settings.hooks[event].some(g =>
+          g.hooks?.some(h => h.command?.includes(hookPattern))
+        );
+        if (!hasHook) {
+          settings.hooks[event].push({
+            _source: hookSource,
+            hooks: [{ type: 'command', command: hookCommand, async: true }]
+          });
+          changed = true;
+        }
+      }
+      if (changed) {
+        mkdirSync(join(homedir(), '.claude'), { recursive: true });
+        writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+        log.info('server', `Registered ${events.length} Claude hook events (density: ${density})`);
+      }
+    } catch (e) {
+      log.debug('server', `Claude hook registration skipped: ${e.message}`);
+    }
+  }
+
+  // ── Gemini CLI hooks ──
+  if (enabledClis.includes('gemini')) {
+    const src = join(__dirname, '..', 'hooks', 'dashboard-hook-gemini.sh');
+    const hooksDir = join(homedir(), '.gemini', 'hooks');
+    const dest = join(hooksDir, 'dashboard-hook.sh');
+    const settingsPath = join(homedir(), '.gemini', 'settings.json');
+
+    syncHookFile(src, dest, hooksDir, false, 'gemini');
+
+    // Gemini events mapped to density
+    const geminiDensityEvents = {
+      high: ['SessionStart', 'BeforeAgent', 'BeforeTool', 'AfterTool', 'AfterAgent', 'SessionEnd', 'Notification'],
+      medium: ['SessionStart', 'BeforeAgent', 'AfterAgent', 'SessionEnd', 'Notification'],
+      low: ['SessionStart', 'AfterAgent', 'SessionEnd'],
+    };
+    const geminiEvents = geminiDensityEvents[density] || geminiDensityEvents.medium;
+
+    try {
+      let settings;
+      try { settings = JSON.parse(readFileSync(settingsPath, 'utf8')); } catch { settings = {}; }
+      if (!settings.hooks) settings.hooks = {};
+
+      let changed = false;
+      for (const event of geminiEvents) {
+        if (!settings.hooks[event]) settings.hooks[event] = [];
+        const hasHook = settings.hooks[event].some(g =>
+          g.hooks?.some(h => h.command?.includes(hookPattern))
+        );
+        if (!hasHook) {
+          settings.hooks[event].push({
+            _source: hookSource,
+            hooks: [{ type: 'command', command: `~/.gemini/hooks/dashboard-hook.sh ${event}` }]
+          });
+          changed = true;
+        }
+      }
+      if (changed) {
+        mkdirSync(join(homedir(), '.gemini'), { recursive: true });
+        writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+        log.info('server', `Registered ${geminiEvents.length} Gemini hook events (density: ${density})`);
+      }
+    } catch (e) {
+      log.debug('server', `Gemini hook registration skipped: ${e.message}`);
+    }
+  }
+
+  // ── Codex CLI hooks ──
+  if (enabledClis.includes('codex')) {
+    const src = join(__dirname, '..', 'hooks', 'dashboard-hook-codex.sh');
+    const hooksDir = join(homedir(), '.codex', 'hooks');
+    const dest = join(hooksDir, 'dashboard-hook.sh');
+    const configPath = join(homedir(), '.codex', 'config.toml');
+
+    syncHookFile(src, dest, hooksDir, false, 'codex');
+
+    // Codex uses TOML config with a notify command
+    try {
+      let toml = '';
+      try { toml = readFileSync(configPath, 'utf8'); } catch {}
+
+      if (!toml.includes(hookPattern)) {
+        mkdirSync(join(homedir(), '.codex'), { recursive: true });
+        const commentLine = `# [${hookSource}] Dashboard hook — safe to remove with "npm run reset"`;
+        const notifyLine = `notify = ["~/.codex/hooks/dashboard-hook.sh"]`;
+        if (toml && !toml.endsWith('\n')) toml += '\n';
+        toml += commentLine + '\n' + notifyLine + '\n';
+        writeFileSync(configPath, toml);
+        log.info('server', 'Registered Codex notify hook in ~/.codex/config.toml');
+      }
+    } catch (e) {
+      log.debug('server', `Codex hook registration skipped: ${e.message}`);
+    }
+  }
+}
+
+// Helper: copy hook script if changed
+function syncHookFile(src, dest, hooksDir, isWindows, label) {
+  if (!existsSync(src)) return;
+  try {
+    let needsCopy = !existsSync(dest);
+    if (!needsCopy) {
+      const srcContent = readFileSync(src);
+      const destContent = readFileSync(dest);
+      needsCopy = !srcContent.equals(destContent);
+    }
+    if (needsCopy) {
+      mkdirSync(hooksDir, { recursive: true });
+      copyFileSync(src, dest);
+      if (!isWindows) chmodSync(dest, 0o755);
+      log.info('server', `Synced ${label} hook → ${dest}`);
+    }
+  } catch (e) {
+    log.debug('server', `${label} hook file sync skipped: ${e.message}`);
+  }
+}
+
+// ── Auto-open browser ──
+function openBrowser(url) {
+  if (noOpen) return;
+  try {
+    const cmd = process.platform === 'darwin' ? 'open'
+      : process.platform === 'win32' ? 'start'
+      : 'xdg-open';
+    execSync(`${cmd} "${url}"`, { stdio: 'ignore', timeout: 5000 });
+  } catch {
+    // Browser open failed — not critical
+  }
+}
+
+function onReady() {
+  log.info('server', `AI Agent Session Center`);
+  log.info('server', `Dashboard: http://localhost:${PORT}`);
+  if (log.isDebug) {
+    log.info('server', 'Debug mode ENABLED — verbose logging active');
+  }
+
+  // Auto-install hooks (copy script + register in settings.json)
+  ensureHooksInstalled();
+
+  // Start file-based message queue reader
+  startMqReader();
+
+  // Open browser after a brief delay (let server fully initialize)
+  setTimeout(() => openBrowser(`http://localhost:${PORT}`), 300);
+}
+
+let retried = false;
+server.on('error', (err) => {
+  if (err.code === 'EADDRINUSE' && !retried) {
+    retried = true;
+    log.info('server', `Port ${PORT} in use — killing existing process…`);
+    killPortProcess(PORT);
+    setTimeout(() => server.listen(PORT, onReady), 1000);
+  } else {
+    throw err;
+  }
+});
+
+server.listen(PORT, onReady);
+
+// Graceful shutdown
+function gracefulShutdown(signal) {
+  log.info('server', `Received ${signal}, shutting down...`);
+  stopMqReader();
+  server.close(() => {
+    log.info('server', 'Server closed');
+    process.exit(0);
+  });
+  setTimeout(() => process.exit(1), 5000);
+}
+
+process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
+process.on('SIGINT', () => gracefulShutdown('SIGINT'));

package/server/logger.js

@@ -0,0 +1,67 @@
+// logger.js — Debug-aware logging utility
+// Usage: node server/index.js --debug   OR   npm start -- --debug
+
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+// Check CLI flag first, then fall back to config file
+let isDebug = process.argv.includes('--debug') || process.argv.includes('-debug');
+if (!isDebug) {
+  try {
+    const __dir = dirname(fileURLToPath(import.meta.url));
+    const cfg = JSON.parse(readFileSync(join(__dir, '..', 'data', 'server-config.json'), 'utf8'));
+    if (cfg.debug) isDebug = true;
+  } catch { /* no config file yet */ }
+}
+
+const RESET = '\x1b[0m';
+const DIM   = '\x1b[2m';
+const CYAN  = '\x1b[36m';
+const YELLOW = '\x1b[33m';
+const RED   = '\x1b[31m';
+const GREEN = '\x1b[32m';
+const MAGENTA = '\x1b[35m';
+
+function timestamp() {
+  return new Date().toISOString().replace('T', ' ').replace('Z', '');
+}
+
+function formatTag(tag) {
+  return `${DIM}[${timestamp()}]${RESET} ${CYAN}[${tag}]${RESET}`;
+}
+
+const logger = {
+  /** Always shown */
+  info(tag, ...args) {
+    console.log(formatTag(tag), ...args);
+  },
+
+  /** Always shown */
+  warn(tag, ...args) {
+    console.warn(`${formatTag(tag)} ${YELLOW}WARN${RESET}`, ...args);
+  },
+
+  /** Always shown */
+  error(tag, ...args) {
+    console.error(`${formatTag(tag)} ${RED}ERROR${RESET}`, ...args);
+  },
+
+  /** Only shown in debug mode */
+  debug(tag, ...args) {
+    if (!isDebug) return;
+    console.log(`${formatTag(tag)} ${MAGENTA}DEBUG${RESET}`, ...args);
+  },
+
+  /** Only shown in debug mode — logs object as JSON */
+  debugJson(tag, label, obj) {
+    if (!isDebug) return;
+    console.log(`${formatTag(tag)} ${MAGENTA}DEBUG${RESET} ${label}:`, JSON.stringify(obj, null, 2));
+  },
+
+  get isDebug() {
+    return isDebug;
+  },
+};
+
+export default logger;

package/server/mqReader.js

@@ -0,0 +1,218 @@
+// mqReader.js — File-based JSONL message queue reader
+// Hooks append JSON lines to a queue file; this module watches it and processes events.
+//
+// Performance: fs.watch() for instant notification + 500ms fallback poll.
+// Atomicity: POSIX guarantees atomic append for writes <= PIPE_BUF (4096 bytes).
+// Our enriched hook JSON is typically 300-800 bytes.
+
+import {
+  existsSync, mkdirSync, writeFileSync,
+  openSync, readSync, closeSync, fstatSync, watch
+} from 'fs';
+import { join } from 'path';
+import { processHookEvent } from './hookProcessor.js';
+import log from './logger.js';
+
+// Use /tmp on macOS/Linux (matches the hardcoded path in dashboard-hook.sh).
+// os.tmpdir() on macOS returns /var/folders/... which hooks can't predict.
+// On Windows, hooks use $env:TEMP which matches os.tmpdir().
+const QUEUE_DIR = process.platform === 'win32'
+  ? join(process.env.TEMP || process.env.TMP || 'C:\\Temp', 'claude-session-center')
+  : '/tmp/claude-session-center';
+const QUEUE_FILE = join(QUEUE_DIR, 'queue.jsonl');
+const POLL_INTERVAL_MS = 500;
+const DEBOUNCE_MS = 10;
+const TRUNCATE_THRESHOLD = 1 * 1024 * 1024; // 1 MB
+
+// Internal state
+let watcher = null;
+let pollTimer = null;
+let lastByteOffset = 0;
+let partialLine = '';
+let debounceTimer = null;
+let running = false;
+
+// Stats
+const mqStats = {
+  linesProcessed: 0,
+  linesErrored: 0,
+  truncations: 0,
+  lastProcessedAt: null,
+  startedAt: null,
+};
+
+/**
+ * Start the MQ reader. Called once from server startup.
+ * Creates queue directory/file, truncates stale data, begins watching.
+ */
+export function startMqReader() {
+  if (running) return;
+  running = true;
+  mqStats.startedAt = Date.now();
+
+  // Ensure queue directory exists
+  mkdirSync(QUEUE_DIR, { recursive: true });
+
+  // Truncate (or create) the queue file — fresh start
+  writeFileSync(QUEUE_FILE, '');
+  lastByteOffset = 0;
+  partialLine = '';
+
+  log.info('mq', `Queue reader started: ${QUEUE_FILE}`);
+
+  // Start fs.watch for instant notification
+  try {
+    watcher = watch(QUEUE_FILE, (eventType) => {
+      if (eventType === 'change') {
+        scheduleRead();
+      }
+    });
+    watcher.on('error', (err) => {
+      log.warn('mq', `fs.watch error: ${err.message}, relying on poll`);
+      watcher = null;
+    });
+  } catch (err) {
+    log.warn('mq', `fs.watch failed: ${err.message}, using poll only`);
+  }
+
+  // Fallback poll (catches events fs.watch may miss)
+  pollTimer = setInterval(() => {
+    readNewLines();
+  }, POLL_INTERVAL_MS);
+}
+
+/** Debounced read scheduler — coalesces rapid fs.watch events */
+function scheduleRead() {
+  if (debounceTimer) return;
+  debounceTimer = setTimeout(() => {
+    debounceTimer = null;
+    readNewLines();
+  }, DEBOUNCE_MS);
+}
+
+/**
+ * Core read loop: reads from lastByteOffset to current EOF,
+ * processes complete JSON lines, retains any partial trailing line.
+ */
+function readNewLines() {
+  let fd;
+  try {
+    fd = openSync(QUEUE_FILE, 'r');
+    const fileStat = fstatSync(fd);
+    const fileSize = fileStat.size;
+
+    // File was truncated externally or is smaller than our offset
+    if (fileSize < lastByteOffset) {
+      log.info('mq', 'Detected external truncation, resetting offset');
+      lastByteOffset = 0;
+      partialLine = '';
+    }
+
+    if (fileSize <= lastByteOffset) {
+      closeSync(fd);
+      return;
+    }
+
+    // Read the new chunk
+    const bytesToRead = fileSize - lastByteOffset;
+    const buffer = Buffer.alloc(bytesToRead);
+    const bytesRead = readSync(fd, buffer, 0, bytesToRead, lastByteOffset);
+    closeSync(fd);
+    fd = null;
+
+    if (bytesRead === 0) return;
+
+    const chunk = buffer.toString('utf-8', 0, bytesRead);
+    const combined = partialLine + chunk;
+    const lines = combined.split('\n');
+
+    // Last element is either '' (if chunk ended with \n) or a partial line
+    partialLine = lines.pop();
+
+    // Process each complete line
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+
+      try {
+        const hookData = JSON.parse(trimmed);
+        processHookEvent(hookData, 'mq');
+        mqStats.linesProcessed++;
+      } catch (err) {
+        mqStats.linesErrored++;
+        log.warn('mq', `Parse error: ${err.message} — line: ${trimmed.substring(0, 100)}`);
+      }
+    }
+
+    // Update offset: advance by bytes consumed (exclude held-back partial)
+    const partialBytes = Buffer.byteLength(partialLine, 'utf-8');
+    lastByteOffset = lastByteOffset + bytesRead - partialBytes;
+    mqStats.lastProcessedAt = Date.now();
+
+    // Truncate if file grew too large and we've fully caught up
+    if (lastByteOffset > TRUNCATE_THRESHOLD && partialLine === '') {
+      truncateQueue();
+    }
+  } catch (err) {
+    if (fd != null) {
+      try { closeSync(fd); } catch {}
+    }
+    if (err.code !== 'ENOENT') {
+      log.warn('mq', `Read error: ${err.message}`);
+    } else {
+      // Queue file deleted — recreate it
+      try { writeFileSync(QUEUE_FILE, ''); } catch {}
+      lastByteOffset = 0;
+      partialLine = '';
+    }
+  }
+}
+
+/** Truncate the queue file after all lines have been processed. */
+function truncateQueue() {
+  try {
+    writeFileSync(QUEUE_FILE, '');
+    lastByteOffset = 0;
+    partialLine = '';
+    mqStats.truncations++;
+    log.info('mq', 'Queue file truncated (all events processed)');
+  } catch (err) {
+    log.warn('mq', `Truncation error: ${err.message}`);
+  }
+}
+
+/** Stop the MQ reader. Called during server shutdown. */
+export function stopMqReader() {
+  running = false;
+  if (watcher) {
+    watcher.close();
+    watcher = null;
+  }
+  if (pollTimer) {
+    clearInterval(pollTimer);
+    pollTimer = null;
+  }
+  if (debounceTimer) {
+    clearTimeout(debounceTimer);
+    debounceTimer = null;
+  }
+  // Final read to flush remaining lines
+  readNewLines();
+  log.info('mq', `Queue reader stopped. Processed: ${mqStats.linesProcessed}, Errors: ${mqStats.linesErrored}`);
+}
+
+/** Get MQ reader stats for the API. */
+export function getMqStats() {
+  return {
+    ...mqStats,
+    queueFile: QUEUE_FILE,
+    running,
+    currentOffset: lastByteOffset,
+    hasPartialLine: partialLine.length > 0,
+  };
+}
+
+/** Get the queue file path (used by install-hooks logging). */
+export function getQueueFilePath() {
+  return QUEUE_FILE;
+}