@worca/ui 0.9.0 → 0.10.0

package/server/project-routes.js

@@ -19,7 +19,10 @@ import {
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { Router } from 'express';
+import { actionAllowed } from '../app/utils/state-actions.js';
 import { dbExists, getIssue, listIssues } from './beads-reader.js';
+import { dispatchExternal } from './dispatch-external.js';
+import { ensureWebhookForUi } from './ensure-webhook.js';
 import { readPreferences } from './preferences.js';
 import { ProcessManager } from './process-manager.js';
 import {
@@ -129,7 +132,13 @@ export function projectResolver({ prefsDir, projectRoot }) {
       settingsPath:
         project.settingsPath || join(project.path, '.claude', 'settings.json'),
       projectRoot: projRoot,
-      pm: new ProcessManager({ worcaDir, projectRoot: projRoot }),
+      pm: new ProcessManager({
+        worcaDir,
+        projectRoot: projRoot,
+        settingsPath:
+          project.settingsPath ||
+          join(project.path, '.claude', 'settings.json'),
+      }),
     };
     next();
   };
@@ -138,7 +147,12 @@ export function projectResolver({ prefsDir, projectRoot }) {
 /**
  * Router for project CRUD: GET/POST/DELETE /api/projects[/:id]
  */
-export function createProjectRoutes({ prefsDir, projectRoot }) {
+export function createProjectRoutes({
+  prefsDir,
+  projectRoot,
+  serverHost,
+  serverPort,
+}) {
   const router = Router();
 
   // GET /api/projects — list all projects (or synthesized default)
@@ -169,6 +183,17 @@ export function createProjectRoutes({ prefsDir, projectRoot }) {
     }
     try {
       writeProject(prefsDir, entry);
+      // Auto-configure webhook so pipeline events reach this UI server
+      if (serverHost && serverPort) {
+        try {
+          ensureWebhookForUi(entry.path, {
+            host: serverHost,
+            port: serverPort,
+          });
+        } catch {
+          /* best-effort — don't fail project creation */
+        }
+      }
       res.status(201).json({ ok: true, project: entry });
     } catch (err) {
       res.status(400).json({ ok: false, error: err.message });
@@ -267,6 +292,16 @@ export function createProjectRoutes({ prefsDir, projectRoot }) {
       for (const entry of batch) {
         writeProject(prefsDir, entry);
         written.push(entry.name);
+        if (serverHost && serverPort) {
+          try {
+            ensureWebhookForUi(entry.path, {
+              host: serverHost,
+              port: serverPort,
+            });
+          } catch {
+            /* best-effort */
+          }
+        }
       }
       res.status(201).json({ ok: true, projects: batch });
     } catch (err) {
@@ -290,7 +325,11 @@ export function createProjectRoutes({ prefsDir, projectRoot }) {
  * @param {{ prefsDir?: string|null }} [options] — prefsDir enables active
  *   worca-cc version lookup for /worca-status' `outdated` flag.
  */
-export function createProjectScopedRoutes({ prefsDir = null } = {}) {
+export function createProjectScopedRoutes({
+  prefsDir = null,
+  serverHost,
+  serverPort,
+} = {}) {
   const router = Router({ mergeParams: true });
   const prefsPath = prefsDir ? join(prefsDir, 'preferences.json') : null;
 
@@ -707,21 +746,6 @@ export function createProjectScopedRoutes({ prefsDir = null } = {}) {
     }
   });
 
-  // DELETE /api/projects/:projectId/runs/:id — stop a running pipeline
-  router.delete('/runs/:id', requireWorcaDir, (req, res) => {
-    try {
-      const result = req.project.pm.stopPipeline(req.params.id);
-      const { broadcast } = req.app.locals;
-      if (broadcast) broadcast('run-stopped', { pid: result.pid });
-      res.json({ ok: true, stopped: true, pid: result.pid });
-    } catch (err) {
-      if (err.code === 'not_running') {
-        return res.status(404).json({ ok: false, error: err.message });
-      }
-      res.status(500).json({ ok: false, error: err.message });
-    }
-  });
-
   // POST /api/projects/:projectId/runs/:id/pause
   router.post('/runs/:id/pause', requireWorcaDir, (req, res) => {
     const runId = req.params.id;
@@ -777,13 +801,13 @@ export function createProjectScopedRoutes({ prefsDir = null } = {}) {
     }
   });
 
-  // POST /api/projects/:projectId/runs/:id/stop — control.json + SIGTERM
-  router.post('/runs/:id/stop', requireWorcaDir, (req, res) => {
+  // POST /api/projects/:projectId/runs/:id/stop — control.json + SIGTERM + webhook
+  router.post('/runs/:id/stop', requireWorcaDir, async (req, res) => {
     const runId = req.params.id;
     if (!validateRunId(runId)) {
       return res.status(400).json({ ok: false, error: 'Invalid runId' });
     }
-    const { worcaDir } = req.project;
+    const { worcaDir, settingsPath } = req.project;
     try {
       const controlDir = join(worcaDir, 'runs', runId);
       mkdirSync(controlDir, { recursive: true });
@@ -803,14 +827,15 @@ export function createProjectScopedRoutes({ prefsDir = null } = {}) {
     } catch {
       /* non-fatal — SIGTERM follows */
     }
+    let forced = false;
     try {
-      const result = req.project.pm.stopPipeline(runId);
-      const { broadcast } = req.app.locals;
-      if (broadcast) broadcast('run-stopped', { runId, pid: result.pid });
-      res.json({ ok: true, stopped: true, runId, pid: result.pid });
+      const result = await req.project.pm.stopPipelineSync(runId, {
+        timeoutMs: 5000,
+      });
+      forced = !!result.forced;
     } catch (err) {
       if (err.code === 'not_running') {
-        const statusPath = findRunStatusPath(req.project.worcaDir, runId);
+        const statusPath = findRunStatusPath(worcaDir, runId);
         if (statusPath) {
           try {
             const st = JSON.parse(readFileSync(statusPath, 'utf8'));
@@ -818,17 +843,11 @@ export function createProjectScopedRoutes({ prefsDir = null } = {}) {
               st.pipeline_status === 'paused' ||
               st.pipeline_status === 'running'
             ) {
-              st.pipeline_status = 'cancelled';
-              st.stop_reason = 'force_cancelled';
-              st.completed_at = new Date().toISOString();
-              writeFileSync(
-                statusPath,
-                `${JSON.stringify(st, null, 2)}\n`,
-                'utf8',
-              );
-              const { broadcast } = req.app.locals;
-              if (broadcast) broadcast('run-stopped', { runId, pid: null });
-              return res.json({ ok: true, stopped: true, runId, pid: null });
+              return res.status(409).json({
+                ok: false,
+                code: 'no_running_process',
+                suggested_action: 'cancel',
+              });
             }
           } catch {
             /* fall through to 404 */
@@ -836,17 +855,61 @@ export function createProjectScopedRoutes({ prefsDir = null } = {}) {
         }
         return res.status(404).json({ ok: false, error: err.message });
       }
-      res.status(500).json({ ok: false, error: err.message });
+      // For other errors, continue — process may have exited
+    }
+
+    const statusPath = findRunStatusPath(worcaDir, runId);
+    const { broadcast, scheduleRefresh } = req.app.locals;
+    if (broadcast) broadcast('run-stopped', { runId });
+    if (scheduleRefresh) scheduleRefresh(req.project?.name);
+    res.json({ ok: true, stopped: true, runId });
+
+    // If Python exited cleanly (not forced), its finally/atexit already
+    // dispatched the webhook. Only dispatch from Node when SIGKILL was needed.
+    if (forced && statusPath) {
+      let st;
+      try {
+        st = JSON.parse(readFileSync(statusPath, 'utf8'));
+      } catch {
+        return;
+      }
+      const terminalStatus = st.pipeline_status;
+      if (terminalStatus === 'interrupted' || terminalStatus === 'failed') {
+        const eventType =
+          terminalStatus === 'interrupted'
+            ? 'pipeline.run.interrupted'
+            : 'pipeline.run.failed';
+        const startedAt = st.started_at;
+        const elapsedMs = startedAt
+          ? Date.now() - new Date(startedAt).getTime()
+          : 0;
+        dispatchExternal({
+          runDir: dirname(statusPath),
+          settingsPath,
+          eventType,
+          payload: {
+            interrupted_stage: st.stage || st.current_stage || 'unknown',
+            elapsed_ms: elapsedMs,
+            source: 'user_stop',
+          },
+        }).then((result) => {
+          if (!result.ok) {
+            console.error(
+              `[stop] dispatchExternal failed for run ${runId}: ${result.reason}${result.stderr ? ` — ${result.stderr}` : ''}`,
+            );
+          }
+        });
+      }
     }
   });
 
-  // POST /api/projects/:projectId/runs/:id/cancel — force-cancel a stale run
-  router.post('/runs/:id/cancel', requireWorcaDir, (req, res) => {
+  // POST /api/projects/:projectId/runs/:id/cancel — force-cancel a run
+  router.post('/runs/:id/cancel', requireWorcaDir, async (req, res) => {
     const runId = req.params.id;
     if (!validateRunId(runId)) {
       return res.status(400).json({ ok: false, error: 'Invalid runId' });
     }
-    const { worcaDir } = req.project;
+    const { worcaDir, settingsPath } = req.project;
     const statusPath = findRunStatusPath(worcaDir, runId);
     if (!statusPath) {
       return res
@@ -854,20 +917,69 @@ export function createProjectScopedRoutes({ prefsDir = null } = {}) {
         .json({ ok: false, error: `Run "${runId}" not found` });
     }
     try {
-      const st = JSON.parse(readFileSync(statusPath, 'utf8'));
+      let st = JSON.parse(readFileSync(statusPath, 'utf8'));
       if (
         st.pipeline_status === 'completed' ||
         st.pipeline_status === 'cancelled'
       ) {
         return res.json({ ok: true, already: st.pipeline_status });
       }
+      if (!actionAllowed('cancel', st.pipeline_status)) {
+        return res.status(409).json({ ok: false, code: 'action_not_allowed' });
+      }
+
+      const wasRunning = st.pipeline_status === 'running';
+      if (wasRunning) {
+        try {
+          await req.project.pm.stopPipelineSync(runId, { timeoutMs: 5000 });
+        } catch {
+          // Expected: process may already be dead (not_running). Cancel proceeds to write cancelled status regardless.
+        }
+        // Re-read: Python's signal/atexit handler may have updated status.json
+        try {
+          st = JSON.parse(readFileSync(statusPath, 'utf8'));
+        } catch {
+          /* use pre-stop snapshot */
+        }
+      }
+
+      // Python's SIGTERM handler may have already emitted pipeline.run.interrupted.
+      // Only emit pipeline.run.cancelled if Python didn't already emit a terminal event.
+      const pythonEmittedTerminal =
+        wasRunning && st.pipeline_status === 'interrupted';
+
       st.pipeline_status = 'cancelled';
       st.stop_reason = 'force_cancelled';
       st.completed_at = new Date().toISOString();
       writeFileSync(statusPath, `${JSON.stringify(st, null, 2)}\n`, 'utf8');
-      const { broadcast } = req.app.locals;
-      if (broadcast) broadcast('run-stopped', { runId, pid: null });
+
+      const { broadcast, scheduleRefresh } = req.app.locals;
+      if (broadcast) broadcast('run-cancelled', { runId });
+      if (scheduleRefresh) scheduleRefresh(req.project?.name);
       res.json({ ok: true, cancelled: true, runId });
+
+      if (!pythonEmittedTerminal) {
+        const startedAt = st.started_at;
+        const elapsedMs = startedAt
+          ? Date.now() - new Date(startedAt).getTime()
+          : 0;
+        dispatchExternal({
+          runDir: dirname(statusPath),
+          settingsPath,
+          eventType: 'pipeline.run.cancelled',
+          payload: {
+            cancelled_stage: st.stage || st.current_stage || 'unknown',
+            elapsed_ms: elapsedMs,
+            source: 'user_cancel',
+          },
+        }).then((result) => {
+          if (!result.ok) {
+            console.error(
+              `[cancel] dispatchExternal failed for run ${runId}: ${result.reason}${result.stderr ? ` — ${result.stderr}` : ''}`,
+            );
+          }
+        });
+      }
     } catch (err) {
       res.status(500).json({ ok: false, error: err.message });
     }
@@ -973,6 +1085,49 @@ export function createProjectScopedRoutes({ prefsDir = null } = {}) {
     }
   });
 
+  // POST /api/projects/:projectId/runs/:id/delete — permanently remove a run
+  router.post('/runs/:id/delete', requireWorcaDir, (req, res) => {
+    const runId = req.params.id;
+    if (!validateRunId(runId)) {
+      return res.status(400).json({ ok: false, error: 'Invalid runId' });
+    }
+    const { worcaDir } = req.project;
+    const statusPath = findRunStatusPath(worcaDir, runId);
+    if (!statusPath) {
+      return res
+        .status(404)
+        .json({ ok: false, error: `Run "${runId}" not found` });
+    }
+    try {
+      const st = JSON.parse(readFileSync(statusPath, 'utf8'));
+      if (!actionAllowed('delete', st.pipeline_status)) {
+        return res.status(409).json({
+          ok: false,
+          code: 'action_not_allowed',
+          error: `Cannot delete a run with status "${st.pipeline_status}" — stop or cancel it first`,
+        });
+      }
+    } catch (err) {
+      return res
+        .status(500)
+        .json({ ok: false, error: `Failed to read status: ${err.message}` });
+    }
+    try {
+      req.project.pm.deleteRun(runId);
+      const { broadcast } = req.app.locals;
+      if (broadcast) broadcast('run-deleted', { runId });
+      res.json({ ok: true, deleted: true, runId });
+    } catch (err) {
+      if (err.code === 'still_running') {
+        return res.status(409).json({ ok: false, error: err.message });
+      }
+      if (err.code === 'not_found') {
+        return res.status(404).json({ ok: false, error: err.message });
+      }
+      res.status(500).json({ ok: false, error: err.message });
+    }
+  });
+
   // POST /api/projects/:projectId/runs/:id/stages/:stage/restart
   router.post(
     '/runs/:id/stages/:stage/restart',
@@ -1365,6 +1520,17 @@ export function createProjectScopedRoutes({ prefsDir = null } = {}) {
 
     try {
       const { pid } = runWorcaSetup(projectRoot, { source });
+      // Auto-configure webhook so pipeline events reach this UI server
+      if (serverHost && serverPort) {
+        try {
+          ensureWebhookForUi(projectRoot, {
+            host: serverHost,
+            port: serverPort,
+          });
+        } catch {
+          /* best-effort */
+        }
+      }
       res.json({ ok: true, pid });
     } catch (err) {
       res.status(500).json({ ok: false, error: err.message });

package/server/settings-validator.js

@@ -532,3 +532,253 @@ export function validateSettingsPayload(body) {
 
   return details.length ? { valid: false, details } : { valid: true };
 }
+
+const VALID_WEBHOOK_OUT_FORMATS = [
+  'generic-json',
+  'slack-compatible',
+  'discord-compatible',
+  'teams-card',
+  'ntfy',
+  'plain-text',
+];
+
+export function validateIntegrationsConfig(cfg) {
+  const details = [];
+
+  if (cfg.schema_version === undefined || cfg.schema_version !== 1) {
+    details.push('schema_version must be present and equal to 1');
+  }
+
+  if (cfg.enabled !== undefined && typeof cfg.enabled !== 'boolean') {
+    details.push('enabled must be a boolean');
+  }
+
+  if (cfg.webhook_secret_env !== undefined) {
+    if (
+      typeof cfg.webhook_secret_env !== 'string' ||
+      cfg.webhook_secret_env.length === 0
+    ) {
+      details.push('webhook_secret_env must be a non-empty string');
+    }
+  }
+
+  if (cfg.webhook_secrets_env !== undefined) {
+    if (
+      typeof cfg.webhook_secrets_env !== 'string' ||
+      cfg.webhook_secrets_env.length === 0
+    ) {
+      details.push('webhook_secrets_env must be a non-empty string');
+    }
+  }
+
+  if (
+    cfg.strict_inbox_verification !== undefined &&
+    typeof cfg.strict_inbox_verification !== 'boolean'
+  ) {
+    details.push('strict_inbox_verification must be a boolean');
+  }
+
+  // telegram
+  if (cfg.telegram !== undefined) {
+    if (
+      typeof cfg.telegram !== 'object' ||
+      cfg.telegram === null ||
+      Array.isArray(cfg.telegram)
+    ) {
+      details.push('telegram must be an object');
+    } else {
+      const tg = cfg.telegram;
+      if (tg.enabled !== undefined && typeof tg.enabled !== 'boolean') {
+        details.push('telegram.enabled must be a boolean');
+      }
+      const hasTgToken =
+        (typeof tg.bot_token === 'string' && tg.bot_token.length > 0) ||
+        (typeof tg.bot_token_env === 'string' && tg.bot_token_env.length > 0);
+      if (!hasTgToken) {
+        details.push(
+          'telegram requires bot_token or bot_token_env (non-empty string)',
+        );
+      }
+      if (
+        tg.chat_id === undefined ||
+        (typeof tg.chat_id !== 'string' && typeof tg.chat_id !== 'number')
+      ) {
+        details.push('telegram.chat_id must be a string or number');
+      }
+      if (tg.events === undefined || !Array.isArray(tg.events)) {
+        details.push('telegram.events must be an array');
+      } else {
+        for (let i = 0; i < tg.events.length; i++) {
+          if (typeof tg.events[i] !== 'string' || tg.events[i].length === 0) {
+            details.push(`telegram.events[${i}] must be a non-empty string`);
+          }
+        }
+      }
+      if (tg.rate_limit_per_min !== undefined) {
+        if (
+          !Number.isInteger(tg.rate_limit_per_min) ||
+          tg.rate_limit_per_min < 1
+        ) {
+          details.push(
+            'telegram.rate_limit_per_min must be a positive integer',
+          );
+        }
+      }
+    }
+  }
+
+  // discord
+  if (cfg.discord !== undefined) {
+    if (
+      typeof cfg.discord !== 'object' ||
+      cfg.discord === null ||
+      Array.isArray(cfg.discord)
+    ) {
+      details.push('discord must be an object');
+    } else {
+      const dc = cfg.discord;
+      if (dc.enabled !== undefined && typeof dc.enabled !== 'boolean') {
+        details.push('discord.enabled must be a boolean');
+      }
+      const hasDcToken =
+        (typeof dc.bot_token === 'string' && dc.bot_token.length > 0) ||
+        (typeof dc.bot_token_env === 'string' && dc.bot_token_env.length > 0);
+      if (!hasDcToken) {
+        details.push(
+          'discord requires bot_token or bot_token_env (non-empty string)',
+        );
+      }
+      if (
+        dc.channel_id === undefined ||
+        typeof dc.channel_id !== 'string' ||
+        dc.channel_id.length === 0
+      ) {
+        details.push('discord.channel_id must be a non-empty string');
+      }
+      if (dc.events !== undefined && !Array.isArray(dc.events)) {
+        details.push('discord.events must be an array');
+      } else if (Array.isArray(dc.events)) {
+        for (let i = 0; i < dc.events.length; i++) {
+          if (typeof dc.events[i] !== 'string' || dc.events[i].length === 0) {
+            details.push(`discord.events[${i}] must be a non-empty string`);
+          }
+        }
+      }
+    }
+  }
+
+  // slack
+  if (cfg.slack !== undefined) {
+    if (
+      typeof cfg.slack !== 'object' ||
+      cfg.slack === null ||
+      Array.isArray(cfg.slack)
+    ) {
+      details.push('slack must be an object');
+    } else {
+      const sl = cfg.slack;
+      if (sl.enabled !== undefined && typeof sl.enabled !== 'boolean') {
+        details.push('slack.enabled must be a boolean');
+      }
+      const hasSlUrl =
+        (typeof sl.webhook_url === 'string' && sl.webhook_url.length > 0) ||
+        (typeof sl.webhook_url_env === 'string' &&
+          sl.webhook_url_env.length > 0);
+      if (!hasSlUrl) {
+        details.push(
+          'slack requires webhook_url or webhook_url_env (non-empty string)',
+        );
+      }
+      if (sl.events !== undefined && !Array.isArray(sl.events)) {
+        details.push('slack.events must be an array');
+      } else if (Array.isArray(sl.events)) {
+        for (let i = 0; i < sl.events.length; i++) {
+          if (typeof sl.events[i] !== 'string' || sl.events[i].length === 0) {
+            details.push(`slack.events[${i}] must be a non-empty string`);
+          }
+        }
+      }
+    }
+  }
+
+  // webhook_out
+  if (cfg.webhook_out !== undefined) {
+    if (
+      typeof cfg.webhook_out !== 'object' ||
+      cfg.webhook_out === null ||
+      Array.isArray(cfg.webhook_out)
+    ) {
+      details.push('webhook_out must be an object');
+    } else {
+      const wo = cfg.webhook_out;
+      if (wo.enabled !== undefined && typeof wo.enabled !== 'boolean') {
+        details.push('webhook_out.enabled must be a boolean');
+      }
+      if (wo.endpoints !== undefined) {
+        if (!Array.isArray(wo.endpoints)) {
+          details.push('webhook_out.endpoints must be an array');
+        } else {
+          for (let i = 0; i < wo.endpoints.length; i++) {
+            const ep = wo.endpoints[i];
+            const pfx = `webhook_out.endpoints[${i}]`;
+            if (typeof ep !== 'object' || ep === null || Array.isArray(ep)) {
+              details.push(`${pfx} must be an object`);
+              continue;
+            }
+            if (
+              ep.url === undefined ||
+              typeof ep.url !== 'string' ||
+              ep.url.trim().length === 0
+            ) {
+              details.push(`${pfx}.url must be a non-empty string`);
+            } else {
+              try {
+                const parsed = new URL(ep.url);
+                if (
+                  parsed.protocol !== 'http:' &&
+                  parsed.protocol !== 'https:'
+                ) {
+                  details.push(`${pfx}.url must use http or https protocol`);
+                }
+              } catch {
+                details.push(`${pfx}.url is not a valid URL`);
+              }
+            }
+            if (ep.format !== undefined) {
+              if (!VALID_WEBHOOK_OUT_FORMATS.includes(ep.format)) {
+                details.push(
+                  `${pfx}.format must be one of: ${VALID_WEBHOOK_OUT_FORMATS.join(', ')}`,
+                );
+              }
+            }
+            if (ep.headers !== undefined) {
+              if (
+                typeof ep.headers !== 'object' ||
+                ep.headers === null ||
+                Array.isArray(ep.headers)
+              ) {
+                details.push(`${pfx}.headers must be an object`);
+              }
+            }
+            if (ep.events !== undefined && !Array.isArray(ep.events)) {
+              details.push(`${pfx}.events must be an array`);
+            } else if (Array.isArray(ep.events)) {
+              for (let j = 0; j < ep.events.length; j++) {
+                if (
+                  typeof ep.events[j] !== 'string' ||
+                  ep.events[j].length === 0
+                ) {
+                  details.push(
+                    `${pfx}.events[${j}] must be a non-empty string`,
+                  );
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return details.length ? { valid: false, details } : { valid: true };
+}

package/server/ws-beads-watcher.js

@@ -1,14 +1,15 @@
 /**
  * Beads database watcher — monitors .beads/beads.db for changes.
- * Watches the directory (not just the file) because SQLite WAL mode
- * writes to beads.db-wal first.
+ * Uses both fs.watch (directory events) and fs.watchFile (stat-based polling)
+ * because fs.watch on macOS misses SQLite WAL writes done via mmap.
  */
 
-import { existsSync, watch } from 'node:fs';
+import { existsSync, unwatchFile, watch, watchFile } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { listIssues } from './beads-reader.js';
 
 const BEADS_DEBOUNCE_MS = 500;
+const BEADS_POLL_MS = 2000;
 
 /**
  * @param {{ worcaDir: string, broadcaster: { broadcast: Function }, projectId?: string }} deps
@@ -16,7 +17,8 @@ const BEADS_DEBOUNCE_MS = 500;
 export function createBeadsWatcher({ worcaDir, broadcaster, projectId }) {
   const beadsDbPath = resolve(join(worcaDir, '..', '.beads', 'beads.db'));
   const beadsDir = resolve(join(worcaDir, '..', '.beads'));
-  let beadsWatcher = null;
+  const beadsWalPath = `${beadsDbPath}-wal`;
+  let fsWatcher = null;
   let BEADS_REFRESH_TIMER = null;
 
   function scheduleBeadsRefresh() {
@@ -41,13 +43,22 @@ export function createBeadsWatcher({ worcaDir, broadcaster, projectId }) {
   }
 
   if (existsSync(beadsDir)) {
+    // fs.watch for directory-level events (checkpoint writes to main db)
     try {
-      beadsWatcher = watch(beadsDir, (_event, filename) => {
+      fsWatcher = watch(beadsDir, (_event, filename) => {
         if (filename?.startsWith('beads.db')) scheduleBeadsRefresh();
       });
     } catch {
       /* ignore */
     }
+
+    // fs.watchFile (stat-based polling) for WAL — fs.watch misses mmap writes
+    // on macOS. watchFile tolerates a missing file; it starts firing once created.
+    watchFile(beadsWalPath, { interval: BEADS_POLL_MS }, (curr, prev) => {
+      if (curr.mtimeMs !== prev.mtimeMs || curr.size !== prev.size) {
+        scheduleBeadsRefresh();
+      }
+    });
   }
 
   function getBeadsDbPath() {
@@ -55,7 +66,12 @@ export function createBeadsWatcher({ worcaDir, broadcaster, projectId }) {
   }
 
   function destroy() {
-    if (beadsWatcher) beadsWatcher.close();
+    if (fsWatcher) fsWatcher.close();
+    try {
+      unwatchFile(beadsWalPath);
+    } catch {
+      /* */
+    }
   }
 
   return { getBeadsDbPath, destroy };