clawmatrix 0.4.2 → 0.5.1

package/src/{web.ts → api.ts}

@@ -2,8 +2,12 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import type { PeerManager } from "./peer-manager.ts";
 import type { HandoffManager } from "./handoff.ts";
 import type { ClawMatrixConfig } from "./config.ts";
-import type { SatelliteContext, IngestedEvent } from "./types.ts";
+import type { SatelliteContext, IngestedEvent, KanbanNotifyFrame, CardStage, CardPriority, CardAnnotation } from "./types.ts";
 import type { HealthTracker } from "./health-tracker.ts";
+import type { AutomationManager } from "./automation.ts";
+import type { KanbanManager } from "./kanban.ts";
+import type { KnowledgeSync } from "./knowledge-sync.ts";
+import { nanoid } from "nanoid";
 import { timingSafeEqual } from "./auth.ts";
 import { readBody } from "./http-utils.ts";
 
@@ -15,10 +19,17 @@ const LOGIN_RATE_MAX = 10; // max attempts per window per IP
 const MAX_INGESTED_EVENTS = 500; // ring buffer for ingested events
 const INGESTED_EVENT_TTL = 86400_000; // 24 hours
 const SATELLITE_TOOL_TIMEOUT = 120_000; // 2 min timeout for satellite tool requests
+const CLUSTER_TOOLS = [
+  "cluster_handoff", "cluster_handoff_reply", "cluster_send", "cluster_peers",
+  "cluster_exec", "cluster_read", "cluster_write", "cluster_edit",
+  "cluster_batch", "cluster_tool", "cluster_terminal", "cluster_transfer",
+  "cluster_events", "cluster_diagnostic", "cluster_acp", "cluster_kanban",
+  "cluster_notify", "cluster_query",
+];
 
 interface SatelliteEvent {
   ts: number;
-  type: "peer_online" | "peer_offline" | "handoff_done" | "context_update" | "event_ingested";
+  type: "peer_online" | "peer_offline" | "handoff_done" | "context_update" | "event_ingested" | "kanban";
   data: Record<string, unknown>;
 }
 
@@ -33,7 +44,7 @@ interface PendingSatelliteTool {
   timer: ReturnType<typeof setTimeout>;
 }
 
-export class WebHandler {
+export class ApiHandler {
   private config: ClawMatrixConfig;
   private peerManager: PeerManager;
   private handoffManager: HandoffManager;
@@ -47,6 +58,10 @@ export class WebHandler {
   private loginAttempts = new Map<string, { count: number; resetAt: number }>(); // IP → rate limit
   private loginCleanupTimer: ReturnType<typeof setInterval> | null = null;
   private healthTracker: HealthTracker | null = null;
+  private automationManager: AutomationManager | null = null;
+  private kanbanManager: KanbanManager | null = null;
+  private knowledgeSync: KnowledgeSync | null = null;
+  private store: import("./store.ts").Store | null = null;
   private onPeerConnected: (nodeId: string) => void;
   private onPeerDisconnected: (nodeId: string) => void;
 
@@ -54,7 +69,7 @@ export class WebHandler {
     this.config = config;
     this.peerManager = peerManager;
     this.handoffManager = handoffManager;
-    this.token = config.web!.token;
+    this.token = config.secret;
 
     // Periodically clean up stale login rate-limit entries
     this.loginCleanupTimer = setInterval(() => {
@@ -97,6 +112,28 @@ export class WebHandler {
     this.healthTracker = tracker;
   }
 
+  /** Set the automation manager for automation API. */
+  setAutomationManager(manager: AutomationManager) {
+    this.automationManager = manager;
+  }
+
+  /** Set the kanban manager for board API. */
+  setKanbanManager(manager: KanbanManager) {
+    this.kanbanManager = manager;
+  }
+
+  /** Set the knowledge sync manager for knowledge API. */
+  setKnowledgeSync(ks: KnowledgeSync) {
+    this.knowledgeSync = ks;
+  }
+
+  /** Set the SQLite store for persistent events. */
+  setStore(store: import("./store.ts").Store) {
+    this.store = store;
+    this.satelliteEvents = hydrateSatelliteEvents(store.querySatelliteEvents(0, MAX_EVENTS, true));
+    this.ingestedEvents = this.loadPersistedIngestedEvents({ limit: MAX_INGESTED_EVENTS, latest: true });
+  }
+
   /** Clean up timers and pending requests on shutdown. */
   destroy() {
     // Remove event listeners to prevent post-destroy callbacks
@@ -123,11 +160,35 @@ export class WebHandler {
     this.satelliteWaiters.length = 0;
   }
 
+  /** Add CORS headers to allow cross-origin requests (Tauri WebView, browser satellite). */
+  private setCorsHeaders(req: IncomingMessage, res: ServerResponse) {
+    const origin = req.headers.origin;
+    if (origin) {
+      res.setHeader("Access-Control-Allow-Origin", origin);
+      res.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
+      res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
+      res.setHeader("Access-Control-Allow-Credentials", "true");
+      res.setHeader("Access-Control-Max-Age", "86400");
+    }
+  }
+
   /** Handle an HTTP request. Returns true if handled, false to fall through. */
   handle(req: IncomingMessage, res: ServerResponse): boolean {
     const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
     const path = url.pathname;
 
+    // CORS headers for all /api/ requests
+    if (path.startsWith("/api/")) {
+      this.setCorsHeaders(req, res);
+    }
+
+    // Handle CORS preflight (must be before auth check — preflight carries no credentials)
+    if (req.method === "OPTIONS") {
+      res.writeHead(204);
+      res.end();
+      return true;
+    }
+
     // Public routes (no auth)
     if (path === "/api/login" && req.method === "POST") {
       this.handleLogin(req, res);
@@ -180,6 +241,32 @@ export class WebHandler {
       return;
     }
 
+    if (path === "/api/automations/rules" && req.method === "GET") {
+      this.handleAutomationRulesGet(res);
+      return;
+    }
+
+    if (path === "/api/automations/rules" && req.method === "PUT") {
+      this.handleAutomationRulesPut(req, res);
+      return;
+    }
+
+    if (path === "/api/automations/history" && req.method === "GET") {
+      this.handleAutomationHistory(req, res);
+      return;
+    }
+
+    if (path === "/api/automations/run" && req.method === "POST") {
+      this.handleAutomationRun(req, res);
+      return;
+    }
+
+    const automationReplayMatch = path.match(/^\/api\/automations\/replay\/([^/]+)$/);
+    if (automationReplayMatch && req.method === "POST") {
+      this.handleAutomationReplay(decodeURIComponent(automationReplayMatch[1]!), res);
+      return;
+    }
+
     if (path === "/api/availability" && req.method === "GET") {
       this.handleAvailability(req, res);
       return;
@@ -200,6 +287,60 @@ export class WebHandler {
       return;
     }
 
+    // Knowledge sync API
+    if (path === "/api/knowledge/files" && req.method === "GET") {
+      this.handleKnowledgeFiles(res);
+      return;
+    }
+
+    if (path === "/api/knowledge/history" && req.method === "GET") {
+      this.handleKnowledgeHistory(req, res);
+      return;
+    }
+
+    // Board / Kanban API
+    if (path === "/api/board" && req.method === "GET") {
+      this.handleBoardSummary(res);
+      return;
+    }
+
+    if (path === "/api/board/cards" && req.method === "GET") {
+      this.handleBoardList(req, res);
+      return;
+    }
+
+    if (path === "/api/board/cards" && req.method === "POST") {
+      this.handleBoardCreate(req, res);
+      return;
+    }
+
+    // /api/board/cards/:id routes
+    const boardCardMatch = path.match(/^\/api\/board\/cards\/([^/]+)$/);
+    if (boardCardMatch) {
+      const cardId = decodeURIComponent(boardCardMatch[1]!);
+      if (req.method === "GET") {
+        this.handleBoardGet(cardId, res);
+        return;
+      }
+      if (req.method === "DELETE") {
+        this.handleBoardDelete(cardId, res);
+        return;
+      }
+      if (req.method === "PATCH") {
+        this.handleBoardUpdate(cardId, req, res);
+        return;
+      }
+    }
+
+    const boardActionMatch = path.match(/^\/api\/board\/cards\/([^/]+)\/(claim|move|annotate)$/);
+    if (boardActionMatch && req.method === "POST") {
+      const cardId = decodeURIComponent(boardActionMatch[1]!);
+      const action = boardActionMatch[2]!;
+      if (action === "claim") { this.handleBoardClaim(cardId, req, res); return; }
+      if (action === "move") { this.handleBoardMove(cardId, req, res); return; }
+      if (action === "annotate") { this.handleBoardAnnotate(cardId, req, res); return; }
+    }
+
     if (path === "/api/logout" && req.method === "POST") {
       res.writeHead(200, {
         "Content-Type": "application/json",
@@ -214,10 +355,12 @@ export class WebHandler {
   }
 
   private async checkAuth(req: IncomingMessage): Promise<boolean> {
-    // Check Authorization header
+    // Check Authorization header (accept either web token or shared secret)
     const authHeader = req.headers.authorization;
-    if (authHeader?.startsWith("Bearer ") && timingSafeEqual(authHeader.slice(7), this.token)) {
-      return true;
+    if (authHeader?.startsWith("Bearer ")) {
+      const bearer = authHeader.slice(7);
+      if (timingSafeEqual(bearer, this.token)) return true;
+      if (this.config.secret && timingSafeEqual(bearer, this.config.secret)) return true;
     }
 
     // Check cookie
@@ -312,17 +455,10 @@ export class WebHandler {
         deny: this.config.toolProxy.deny,
       } : undefined,
       clusterTools: [
-        "cluster_handoff", "cluster_send", "cluster_peers",
-        "cluster_exec", "cluster_read", "cluster_write", "cluster_edit",
+        ...CLUSTER_TOOLS,
       ],
     };
 
-    // All mesh peers share these cluster tools (they all run the ClawMatrix plugin)
-    const CLUSTER_TOOLS = [
-      "cluster_handoff", "cluster_send", "cluster_peers",
-      "cluster_exec", "cluster_read", "cluster_write", "cluster_edit",
-    ];
-
     const peerNodes: Record<string, unknown>[] = peers.map((p) => ({
       nodeId: p.nodeId,
       agents: p.agents,
@@ -373,6 +509,7 @@ export class WebHandler {
       uptime: Math.floor((Date.now() - this.startTime) / 1000),
       listen: this.config.listen ? this.config.listenPort : false,
       proxyPort: this.config.proxyPort,
+      knowledgeEnabled: !!this.knowledgeSync,
       local: localNode,
       peers: peerNodes,
     }));
@@ -503,6 +640,15 @@ export class WebHandler {
     if (this.satelliteEvents.length > MAX_EVENTS) {
       this.satelliteEvents.splice(0, this.satelliteEvents.length - MAX_EVENTS);
     }
+    // Persist to SQLite
+    try {
+      this.store?.insertSatelliteEvent({
+        id: `sat-${event.ts}-${Math.random().toString(36).slice(2, 8)}`,
+        ts: event.ts,
+        type: event.type,
+        data: JSON.stringify(event.data),
+      });
+    } catch { /* non-fatal */ }
     // Wake up any long-polling clients immediately
     if (this.satelliteWaiters.length > 0) {
       this.flushSatelliteWaiters();
@@ -587,7 +733,10 @@ export class WebHandler {
   private sendSatellitePollResponse(res: ServerResponse, since: number, satelliteNodeId?: string) {
     this.syncPeerState();
     const peers = this.peerManager.router.getAllPeers();
-    const events = this.satelliteEvents.filter(e => e.ts > since);
+    const events = this.store
+      ? hydrateSatelliteEvents(this.store.querySatelliteEvents(since, MAX_EVENTS))
+      : this.satelliteEvents.filter(e => e.ts > since);
+    const cursorTs = events.length > 0 ? events[events.length - 1]!.ts : Date.now();
 
     // Include pending tool requests for this satellite node
     let pendingTools: Array<{ id: string; tool: string; params: Record<string, unknown> }> | undefined;
@@ -627,7 +776,7 @@ export class WebHandler {
       peers: allPeers,
       events,
       pendingTools,
-      ts: Date.now(),
+      ts: cursorTs,
     };
 
     try {
@@ -771,6 +920,109 @@ export class WebHandler {
     }
   }
 
+  // ── Automation API ─────────────────────────────────────────────
+
+  /** GET /api/automations/rules — list automation rules. */
+  private handleAutomationRulesGet(res: ServerResponse) {
+    if (!this.automationManager) {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ rules: [] }));
+      return;
+    }
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ rules: this.automationManager.getRules() }));
+  }
+
+  /** PUT /api/automations/rules — save automation rules. */
+  private async handleAutomationRulesPut(req: IncomingMessage, res: ServerResponse) {
+    if (!this.automationManager) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Automation manager not available" }));
+      return;
+    }
+    try {
+      const body = await readBody(req);
+      const { rules } = JSON.parse(body);
+      if (!Array.isArray(rules)) {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "rules array required" }));
+        return;
+      }
+      await this.automationManager.saveRules(rules);
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ ok: true, count: rules.length }));
+    } catch (err) {
+      res.writeHead(500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: err instanceof Error ? err.message : "Failed to save rules" }));
+    }
+  }
+
+  /** GET /api/automations/history?limit=<n> — execution history. */
+  private handleAutomationHistory(req: IncomingMessage, res: ServerResponse) {
+    if (!this.automationManager) {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ executions: [] }));
+      return;
+    }
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    const limit = Math.min(parseInt(url.searchParams.get("limit") ?? "50", 10) || 50, 100);
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ executions: this.automationManager.getExecutions(limit) }));
+  }
+
+  /** POST /api/automations/run — manually run a rule. */
+  private async handleAutomationRun(req: IncomingMessage, res: ServerResponse) {
+    if (!this.automationManager) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Automation manager not available" }));
+      return;
+    }
+    try {
+      const body = await readBody(req);
+      const parsed = JSON.parse(body) as { ruleId?: string; event?: Record<string, unknown> };
+      if (!parsed.ruleId || typeof parsed.ruleId !== "string") {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "ruleId required" }));
+        return;
+      }
+
+      const rawEvent = parsed.event;
+      const event = rawEvent
+        ? {
+            id: nanoid(),
+            source: typeof rawEvent.source === "string" ? rawEvent.source : "manual",
+            type: typeof rawEvent.type === "string" ? rawEvent.type : "manual.run",
+            data: (typeof rawEvent.data === "object" && rawEvent.data !== null ? rawEvent.data : {}) as Record<string, unknown>,
+            ts: Date.now(),
+            consumed: false,
+          }
+        : undefined;
+      const execution = await this.automationManager.runRuleById(parsed.ruleId, event);
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ ok: true, execution }));
+    } catch (err) {
+      res.writeHead(500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: err instanceof Error ? err.message : "Failed to run automation" }));
+    }
+  }
+
+  /** POST /api/automations/replay/:id — rerun a historical execution. */
+  private async handleAutomationReplay(executionId: string, res: ServerResponse) {
+    if (!this.automationManager) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Automation manager not available" }));
+      return;
+    }
+    try {
+      const execution = await this.automationManager.replayExecution(executionId);
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ ok: true, execution }));
+    } catch (err) {
+      res.writeHead(500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: err instanceof Error ? err.message : "Failed to replay automation" }));
+    }
+  }
+
   // ── Event ingestion (Shortcuts automations, etc.) ──────────────
 
   /** POST /api/events/ingest — receive events from external sources (e.g. Apple Shortcuts) */
@@ -786,7 +1038,7 @@ export class WebHandler {
       for (const item of items) {
         if (!item.type) continue;
         const event: IngestedEvent = {
-          id: crypto.randomUUID(),
+          id: nanoid(),
           source: String(item.source || "unknown"),
           type: String(item.type),
           data: (typeof item.data === "object" && item.data !== null ? item.data : { value: item.data ?? item }) as Record<string, unknown>,
@@ -795,6 +1047,16 @@ export class WebHandler {
         };
         this.ingestedEvents.push(event);
         ingested.push(event);
+        // Persist to SQLite
+        try {
+          this.store?.insertIngestedEvent({
+            id: event.id,
+            ts: event.ts,
+            type: event.type,
+            source: event.source,
+            data: JSON.stringify(event.data),
+          });
+        } catch { /* non-fatal */ }
       }
 
       // Trim ring buffer
@@ -811,6 +1073,13 @@ export class WebHandler {
         });
       }
 
+      // Trigger automation rules for each ingested event
+      if (this.automationManager) {
+        for (const event of ingested) {
+          this.automationManager.onEventIngested(event);
+        }
+      }
+
       res.writeHead(200, { "Content-Type": "application/json" });
       res.end(JSON.stringify({ ok: true, count: ingested.length, ids: ingested.map(e => e.id) }));
     } catch {
@@ -830,17 +1099,39 @@ export class WebHandler {
 
     this.evictStaleEvents();
 
-    let events = this.ingestedEvents;
-    if (since > 0) events = events.filter(e => e.ts > since);
-    if (type) events = events.filter(e => e.type === type);
-    if (source) events = events.filter(e => e.source === source);
-    if (unconsumed) events = events.filter(e => !e.consumed);
+    const queryOpts = {
+      since: since > 0 ? since : undefined,
+      type,
+      source,
+      unconsumed,
+      limit,
+      latest: true,
+    } as const;
+
+    let total: number | undefined;
+    let events = this.store
+      ? this.loadPersistedIngestedEvents(queryOpts)
+      : this.ingestedEvents;
+    if (!this.store) {
+      if (since > 0) events = events.filter(e => e.ts > since);
+      if (type) events = events.filter(e => e.type === type);
+      if (source) events = events.filter(e => e.source === source);
+      if (unconsumed) events = events.filter(e => !e.consumed);
+      total = events.length;
+    } else {
+      total = this.store.countIngestedEvents({
+        since: queryOpts.since,
+        type,
+        source,
+        unconsumed,
+      });
+    }
 
     // Return newest first, limited
     const result = events.slice(-limit).reverse();
 
     res.writeHead(200, { "Content-Type": "application/json" });
-    res.end(JSON.stringify({ events: result, total: events.length }));
+    res.end(JSON.stringify({ events: result, total }));
   }
 
   /** POST /api/events/consume — mark events as consumed by id(s) */
@@ -862,6 +1153,10 @@ export class WebHandler {
           consumed++;
         }
       }
+      if (this.store) {
+        consumed = this.store.consumeIngestedEvents(ids);
+        this.ingestedEvents = this.loadPersistedIngestedEvents({ limit: MAX_INGESTED_EVENTS, latest: true });
+      }
 
       res.writeHead(200, { "Content-Type": "application/json" });
       res.end(JSON.stringify({ ok: true, consumed }));
@@ -873,7 +1168,7 @@ export class WebHandler {
 
   /** Evict events older than TTL. Centralizes stale-event cleanup. */
   private evictStaleEvents() {
-    const cutoff = Date.now() - INGESTED_EVENT_TTL;
+    const cutoff = this.getIngestedEventCutoff();
     const firstValid = this.ingestedEvents.findIndex(e => e.ts > cutoff);
     if (firstValid > 0) {
       this.ingestedEvents.splice(0, firstValid);
@@ -885,12 +1180,25 @@ export class WebHandler {
   /** Get unconsumed events (for agent context injection). */
   getUnconsumedEvents(limit = 10): IngestedEvent[] {
     this.evictStaleEvents();
+    if (this.store) {
+      return this.loadPersistedIngestedEvents({ unconsumed: true, limit, latest: true }).slice(-limit);
+    }
     return this.ingestedEvents.filter(e => !e.consumed).slice(-limit);
   }
 
   /** Get all ingested events (for tool queries). */
   queryEvents(opts?: { type?: string; source?: string; since?: number; unconsumed?: boolean; limit?: number }): IngestedEvent[] {
     this.evictStaleEvents();
+    if (this.store) {
+      return this.loadPersistedIngestedEvents({
+        since: opts?.since,
+        type: opts?.type,
+        source: opts?.source,
+        unconsumed: opts?.unconsumed,
+        limit: opts?.limit ?? 50,
+        latest: true,
+      }).reverse();
+    }
 
     let events = this.ingestedEvents;
     if (opts?.since) events = events.filter(e => e.ts > opts.since!);
@@ -902,6 +1210,11 @@ export class WebHandler {
 
   /** Mark events as consumed by id(s). */
   consumeEvents(ids: string[]): number {
+    if (this.store) {
+      const consumed = this.store.consumeIngestedEvents(ids);
+      this.ingestedEvents = this.loadPersistedIngestedEvents({ limit: MAX_INGESTED_EVENTS, latest: true });
+      return consumed;
+    }
     const idSet = new Set(ids);
     let consumed = 0;
     for (const event of this.ingestedEvents) {
@@ -913,6 +1226,287 @@ export class WebHandler {
     return consumed;
   }
 
+  private getIngestedEventCutoff(): number {
+    return Date.now() - INGESTED_EVENT_TTL;
+  }
+
+  private loadPersistedIngestedEvents(
+    opts: { since?: number; type?: string; source?: string; unconsumed?: boolean; limit?: number; latest?: boolean },
+  ): IngestedEvent[] {
+    const cutoff = this.getIngestedEventCutoff();
+    const since = opts.since == null ? cutoff : Math.max(opts.since, cutoff);
+    return hydrateIngestedEvents(this.store!.queryIngestedEvents({
+      ...opts,
+      since,
+    }));
+  }
+
+  // ── Knowledge sync API handlers ─────────────────────────────────
+
+  /** GET /api/knowledge/files — list all synced files with metadata. */
+  private handleKnowledgeFiles(res: ServerResponse) {
+    if (!this.knowledgeSync) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Knowledge sync not enabled" }));
+      return;
+    }
+    const files = this.knowledgeSync.listSyncedFiles();
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ success: true, files }));
+  }
+
+  /** GET /api/knowledge/history?path=<relPath> — file change history from CRDT. */
+  private handleKnowledgeHistory(req: IncomingMessage, res: ServerResponse) {
+    if (!this.knowledgeSync) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Knowledge sync not enabled" }));
+      return;
+    }
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    const filePath = url.searchParams.get("path");
+    if (!filePath) {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Missing required query param: path" }));
+      return;
+    }
+    const rawHistory = this.knowledgeSync.getFileHistory(filePath);
+    const history = rawHistory.map((entry) => {
+      let nodeId: string | undefined;
+      let agentId: string | undefined;
+      try {
+        const parsed = JSON.parse(entry.message);
+        nodeId = parsed.nodeId;
+        agentId = parsed.agentId;
+      } catch {
+        // message is not JSON — keep as-is
+      }
+      return {
+        timestamp: entry.timestamp,
+        message: entry.message,
+        actor: entry.actor,
+        ...(nodeId !== undefined ? { nodeId } : {}),
+        ...(agentId !== undefined ? { agentId } : {}),
+      };
+    });
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ success: true, path: filePath, history }));
+  }
+
+  // ── Board / Kanban API handlers ─────────────────────────────────
+
+  private handleBoardSummary(res: ServerResponse) {
+    if (!this.kanbanManager) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Kanban not enabled" }));
+      return;
+    }
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(this.kanbanManager.getSummary()));
+  }
+
+  private handleBoardList(req: IncomingMessage, res: ServerResponse) {
+    if (!this.kanbanManager) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Kanban not enabled" }));
+      return;
+    }
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    const stage = url.searchParams.get("stage") as CardStage | null;
+    const label = url.searchParams.get("label") || undefined;
+    const assignedNode = url.searchParams.get("assignedNode") || undefined;
+    const priority = url.searchParams.get("priority") as CardPriority | null;
+
+    const cards = this.kanbanManager.listCards({
+      stage: stage || undefined,
+      label,
+      assignedNode,
+      priority: priority || undefined,
+    });
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ cards }));
+  }
+
+  private async handleBoardCreate(req: IncomingMessage, res: ServerResponse) {
+    if (!this.kanbanManager) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Kanban not enabled" }));
+      return;
+    }
+    try {
+      const body = await readBody(req);
+      const { title, description, priority, targetNode, targetAgent, cwd, labels } = JSON.parse(body);
+      if (!title) {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "title required" }));
+        return;
+      }
+      const card = this.kanbanManager.createCard({ title, description, priority, targetNode, targetAgent, cwd, labels });
+      res.writeHead(201, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(card));
+    } catch {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Invalid request" }));
+    }
+  }
+
+  private handleBoardGet(cardId: string, res: ServerResponse) {
+    if (!this.kanbanManager) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Kanban not enabled" }));
+      return;
+    }
+    const card = this.kanbanManager.getCard(cardId);
+    if (!card) {
+      res.writeHead(404, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: `Card not found: ${cardId}` }));
+      return;
+    }
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(card));
+  }
+
+  private async handleBoardClaim(cardId: string, req: IncomingMessage, res: ServerResponse) {
+    if (!this.kanbanManager) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Kanban not enabled" }));
+      return;
+    }
+    try {
+      const body = await readBody(req);
+      const { agent } = body ? JSON.parse(body) : {} as { agent?: string };
+      const card = this.kanbanManager.claimCard(
+        cardId,
+        this.config.nodeId,
+        agent ?? "web",
+      );
+      if (!card) {
+        res.writeHead(409, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: `Cannot claim card ${cardId}` }));
+        return;
+      }
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(card));
+    } catch {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Invalid request" }));
+    }
+  }
+
+  private async handleBoardMove(cardId: string, req: IncomingMessage, res: ServerResponse) {
+    if (!this.kanbanManager) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Kanban not enabled" }));
+      return;
+    }
+    try {
+      const body = await readBody(req);
+      const { stage } = JSON.parse(body) as { stage?: string };
+      if (!stage) {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "stage required" }));
+        return;
+      }
+      const card = this.kanbanManager.moveCard(cardId, stage as CardStage);
+      if (!card) {
+        res.writeHead(409, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: `Cannot move card ${cardId}` }));
+        return;
+      }
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(card));
+    } catch {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Invalid request" }));
+    }
+  }
+
+  private async handleBoardAnnotate(cardId: string, req: IncomingMessage, res: ServerResponse) {
+    if (!this.kanbanManager) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Kanban not enabled" }));
+      return;
+    }
+    try {
+      const body = await readBody(req);
+      const { content, type: annotationType, agent } = JSON.parse(body) as {
+        content?: string; type?: string; agent?: string;
+      };
+      if (!content) {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "content required" }));
+        return;
+      }
+      const card = this.kanbanManager.annotateCard(cardId, {
+        nodeId: this.config.nodeId,
+        agent: agent ?? "web",
+        type: (annotationType ?? "note") as CardAnnotation["type"],
+        content,
+      });
+      if (!card) {
+        res.writeHead(404, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: `Card not found: ${cardId}` }));
+        return;
+      }
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(card));
+    } catch {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Invalid request" }));
+    }
+  }
+
+  private async handleBoardUpdate(cardId: string, req: IncomingMessage, res: ServerResponse) {
+    if (!this.kanbanManager) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Kanban not enabled" }));
+      return;
+    }
+    try {
+      const body = await readBody(req);
+      const updates = JSON.parse(body) as {
+        title?: string; description?: string; priority?: string;
+        targetNode?: string; targetAgent?: string; cwd?: string;
+        labels?: string[]; handoffId?: string; acpSessionId?: string;
+      };
+      const card = this.kanbanManager.updateCard(cardId, updates as Parameters<typeof this.kanbanManager.updateCard>[1]);
+      if (!card) {
+        res.writeHead(404, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: `Card not found: ${cardId}` }));
+        return;
+      }
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(card));
+    } catch {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Invalid request" }));
+    }
+  }
+
+  private handleBoardDelete(cardId: string, res: ServerResponse) {
+    if (!this.kanbanManager) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Kanban not enabled" }));
+      return;
+    }
+    const ok = this.kanbanManager.deleteCard(cardId);
+    if (!ok) {
+      res.writeHead(404, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: `Card not found: ${cardId}` }));
+      return;
+    }
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ deleted: true, cardId }));
+  }
+
+  /** Push a kanban notification event into the satellite event stream. */
+  pushKanbanEvent(payload: KanbanNotifyFrame["payload"]) {
+    this.pushSatelliteEvent({
+      ts: Date.now(),
+      type: "kanban",
+      data: { ...payload },
+    });
+  }
+
   /** Get all satellite contexts (for use by other components). */
   getSatelliteContexts(): SatelliteContext[] {
     // Filter out stale contexts (> 10 minutes)
@@ -929,3 +1523,30 @@ export class WebHandler {
   }
 }
 
+function hydrateSatelliteEvents(rows: Array<{ ts: number; type: SatelliteEvent["type"]; data: string }>): SatelliteEvent[] {
+  return rows.map((row) => ({
+    ts: row.ts,
+    type: row.type,
+    data: parseJsonRecord(row.data),
+  }));
+}
+
+function hydrateIngestedEvents(rows: Array<{ id: string; ts: number; type: string; source: string; data: string; consumed: number }>): IngestedEvent[] {
+  return rows.map((row) => ({
+    id: row.id,
+    ts: row.ts,
+    type: row.type,
+    source: row.source,
+    data: parseJsonRecord(row.data),
+    consumed: row.consumed !== 0,
+  }));
+}
+
+function parseJsonRecord(value: string): Record<string, unknown> {
+  try {
+    const parsed = JSON.parse(value);
+    return typeof parsed === "object" && parsed !== null ? parsed as Record<string, unknown> : { value: parsed };
+  } catch {
+    return { value };
+  }
+}