jfl 0.2.2 → 0.2.4

package/dist/commands/context-hub.js

@@ -18,6 +18,13 @@ import { initializeDatabase, getMemoryStats, insertMemory } from "../lib/memory-
 import { searchMemories } from "../lib/memory-search.js";
 import { indexJournalEntries, startPeriodicIndexing } from "../lib/memory-indexer.js";
 import { getProjectPort } from "../utils/context-hub-port.js";
+import { getConfigValue, setConfig } from "../utils/jfl-config.js";
+import Conf from "conf";
+import { MAPEventBus } from "../lib/map-event-bus.js";
+import { FlowEngine } from "../lib/flow-engine.js";
+import { WebSocketServer } from "ws";
+import { telemetry } from "../lib/telemetry.js";
+import { transformHookPayload } from "../lib/hook-transformer.js";
 const PID_FILE = ".jfl/context-hub.pid";
 const LOG_FILE = ".jfl/logs/context-hub.log";
 const TOKEN_FILE = ".jfl/context-hub.token";
@@ -39,22 +46,29 @@ function getOrCreateToken(projectRoot) {
     fs.writeFileSync(tokenFile, token, { mode: 0o600 }); // Owner read/write only
     return token;
 }
-function validateAuth(req, projectRoot) {
+function validateAuth(req, projectRoot, url) {
     const tokenFile = getTokenFile(projectRoot);
     // If no token file exists, allow access (backwards compatibility during migration)
     if (!fs.existsSync(tokenFile)) {
         return true;
     }
     const expectedToken = fs.readFileSync(tokenFile, 'utf-8').trim();
+    // Check Authorization header first
     const authHeader = req.headers['authorization'];
-    if (!authHeader) {
-        return false;
+    if (authHeader) {
+        const providedToken = authHeader.startsWith('Bearer ')
+            ? authHeader.slice(7)
+            : authHeader;
+        if (providedToken === expectedToken)
+            return true;
+    }
+    // Fall back to ?token= query param (needed for SSE/EventSource which can't set headers)
+    if (url) {
+        const queryToken = url.searchParams.get('token');
+        if (queryToken && queryToken === expectedToken)
+            return true;
     }
-    // Support "Bearer <token>" format
-    const providedToken = authHeader.startsWith('Bearer ')
-        ? authHeader.slice(7)
-        : authHeader;
-    return providedToken === expectedToken;
+    return false;
 }
 function isPortInUse(port) {
     return new Promise((resolve) => {
@@ -77,28 +91,31 @@ function isPortInUse(port) {
 // ============================================================================
 // Journal Reader
 // ============================================================================
-function readJournalEntries(projectRoot, limit = 20) {
+function readJournalEntries(projectRoot, limit = 50) {
     const journalDir = path.join(projectRoot, ".jfl", "journal");
     const items = [];
     if (!fs.existsSync(journalDir)) {
         return items;
     }
+    // Sort by modification time (newest first) so recent entries aren't buried
     const files = fs.readdirSync(journalDir)
         .filter(f => f.endsWith(".jsonl"))
-        .sort()
-        .reverse();
+        .map(f => ({
+        name: f,
+        mtime: fs.statSync(path.join(journalDir, f)).mtimeMs
+    }))
+        .sort((a, b) => b.mtime - a.mtime)
+        .map(f => f.name);
+    // Read all entries from all files, then sort globally by timestamp
+    const allEntries = [];
     for (const file of files) {
-        if (items.length >= limit)
-            break;
         const filePath = path.join(journalDir, file);
         const content = fs.readFileSync(filePath, "utf-8");
         const lines = content.trim().split("\n").filter(l => l.trim());
-        for (const line of lines.reverse()) {
-            if (items.length >= limit)
-                break;
+        for (const line of lines) {
             try {
                 const entry = JSON.parse(line);
-                items.push({
+                allEntries.push({
                     source: "journal",
                     type: entry.type || "entry",
                     title: entry.title || "Untitled",
@@ -112,7 +129,13 @@ function readJournalEntries(projectRoot, limit = 20) {
             }
         }
     }
-    return items;
+    // Sort all entries by timestamp descending, then take the limit
+    allEntries.sort((a, b) => {
+        const ta = a.timestamp || "";
+        const tb = b.timestamp || "";
+        return tb.localeCompare(ta);
+    });
+    return allEntries.slice(0, limit);
 }
 // ============================================================================
 // Knowledge Reader
@@ -395,8 +418,34 @@ function getUnifiedContext(projectRoot, query, taskType) {
 // ============================================================================
 // HTTP Server
 // ============================================================================
-function createServer(projectRoot, port) {
+function createServer(projectRoot, port, eventBus) {
     const server = http.createServer((req, res) => {
+        const requestStart = Date.now();
+        const pathname = new URL(req.url || "/", `http://localhost:${port}`).pathname;
+        // Intercept writeHead to capture status code for telemetry
+        let capturedStatus = 200;
+        const originalWriteHead = res.writeHead.bind(res);
+        res.writeHead = function (statusCode, ...args) {
+            capturedStatus = statusCode;
+            return originalWriteHead(statusCode, ...args);
+        };
+        // Track request on response finish (skip health/OPTIONS/dashboard)
+        const shouldTrack = req.method !== "OPTIONS"
+            && pathname !== "/health"
+            && !pathname.startsWith("/dashboard");
+        if (shouldTrack) {
+            res.on('finish', () => {
+                telemetry.track({
+                    category: 'context_hub',
+                    event: 'context_hub:request',
+                    endpoint: pathname,
+                    method: req.method,
+                    status_code: capturedStatus,
+                    duration_ms: Date.now() - requestStart,
+                    hub_port: port,
+                });
+            });
+        }
         // CORS - include Authorization header
         res.setHeader("Access-Control-Allow-Origin", "*");
         res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
@@ -413,8 +462,69 @@ function createServer(projectRoot, port) {
             res.end(JSON.stringify({ status: "ok", port }));
             return;
         }
+        // Dashboard - served without API auth (has its own token flow in JS)
+        if (url.pathname.startsWith("/dashboard")) {
+            import("../dashboard/index.js").then(({ handleDashboardRoutes }) => {
+                if (!handleDashboardRoutes(req, res, projectRoot, port)) {
+                    res.writeHead(404, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ error: "Not found" }));
+                }
+            }).catch(() => {
+                res.writeHead(500, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "Dashboard module failed to load" }));
+            });
+            return;
+        }
+        // Hook ingestion (Claude Code HTTP hooks)
+        // No auth required — localhost-only. Always returns 200.
+        if (url.pathname === "/api/hooks" && req.method === "POST") {
+            const remoteAddr = req.socket.remoteAddress || "";
+            const isLocalhost = remoteAddr === "127.0.0.1" || remoteAddr === "::1" || remoteAddr === "::ffff:127.0.0.1";
+            if (!isLocalhost) {
+                res.writeHead(403, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "localhost only" }));
+                return;
+            }
+            let body = "";
+            let bodySize = 0;
+            const MAX_BODY = 64 * 1024;
+            req.on("data", (chunk) => {
+                bodySize += typeof chunk === "string" ? chunk.length : chunk.byteLength;
+                if (bodySize <= MAX_BODY) {
+                    body += chunk;
+                }
+            });
+            req.on("end", () => {
+                try {
+                    if (bodySize > MAX_BODY) {
+                        console.warn(`[hooks] Dropped oversized payload: ${bodySize} bytes`);
+                        res.writeHead(200, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({ ok: true, dropped: true }));
+                        return;
+                    }
+                    const payload = JSON.parse(body);
+                    const partial = transformHookPayload(payload);
+                    if (eventBus) {
+                        eventBus.emit(partial);
+                    }
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ ok: true }));
+                }
+                catch (err) {
+                    console.warn(`[hooks] Parse error: ${err.message}`);
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ ok: true, parse_error: true }));
+                }
+            });
+            return;
+        }
         // All other endpoints require auth
-        if (!validateAuth(req, projectRoot)) {
+        if (!validateAuth(req, projectRoot, url)) {
+            telemetry.track({
+                category: 'context_hub',
+                event: 'context_hub:auth_failed',
+                endpoint: pathname,
+            });
             res.writeHead(401, { "Content-Type": "application/json" });
             res.end(JSON.stringify({
                 error: "Unauthorized",
@@ -446,6 +556,15 @@ function createServer(projectRoot, port) {
                     if (maxItems && context.items.length > maxItems) {
                         context.items = context.items.slice(0, maxItems);
                     }
+                    telemetry.track({
+                        category: 'context_hub',
+                        event: 'context_hub:context_loaded',
+                        item_count: context.items.length,
+                        journal_count: context.items.filter(i => i.source === 'journal').length,
+                        knowledge_count: context.items.filter(i => i.source === 'knowledge').length,
+                        code_count: context.items.filter(i => i.source === 'code').length,
+                        query_length: query ? query.length : 0,
+                    });
                     res.writeHead(200, { "Content-Type": "application/json" });
                     res.end(JSON.stringify(context));
                 }
@@ -468,10 +587,19 @@ function createServer(projectRoot, port) {
                         res.end(JSON.stringify({ error: "query required" }));
                         return;
                     }
+                    const searchStart = Date.now();
                     const context = getUnifiedContext(projectRoot, query);
                     context.items = context.items
                         .filter(item => item.relevance && item.relevance > 0)
                         .slice(0, maxItems);
+                    telemetry.track({
+                        category: 'context_hub',
+                        event: 'context_hub:search',
+                        result_count: context.items.length,
+                        duration_ms: Date.now() - searchStart,
+                        has_query: true,
+                        query_length: query.length,
+                    });
                     res.writeHead(200, { "Content-Type": "application/json" });
                     res.end(JSON.stringify(context));
                 }
@@ -579,10 +707,158 @@ function createServer(projectRoot, port) {
             });
             return;
         }
+        // Cross-project health
+        if (url.pathname === "/api/projects" && req.method === "GET") {
+            const tracked = getTrackedProjects();
+            Promise.all(tracked.map(async (p) => {
+                // Self-check: if this is our own port, we know we're OK
+                if (p.port === port) {
+                    return {
+                        name: p.path.split("/").pop() || p.path,
+                        path: p.path,
+                        port: p.port,
+                        status: "OK",
+                        pid: process.pid,
+                        message: "This instance",
+                    };
+                }
+                const result = await diagnoseProject(p.path, p.port);
+                return {
+                    name: p.path.split("/").pop() || p.path,
+                    path: p.path,
+                    port: p.port,
+                    status: result.status,
+                    pid: result.pid,
+                    message: result.message,
+                };
+            }))
+                .then((results) => {
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify(results));
+            })
+                .catch((err) => {
+                res.writeHead(500, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: err.message }));
+            });
+            return;
+        }
+        // Publish event
+        if (url.pathname === "/api/events" && req.method === "POST") {
+            if (!eventBus) {
+                res.writeHead(503, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "Event bus not initialized" }));
+                return;
+            }
+            let body = "";
+            req.on("data", chunk => body += chunk);
+            req.on("end", () => {
+                try {
+                    const { type, source, target, session, data, ttl } = JSON.parse(body || "{}");
+                    if (!type || !source) {
+                        res.writeHead(400, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({ error: "type and source required" }));
+                        return;
+                    }
+                    const event = eventBus.emit({
+                        type: type,
+                        source,
+                        target,
+                        session,
+                        data: data || {},
+                        ttl,
+                    });
+                    res.writeHead(201, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify(event));
+                }
+                catch (err) {
+                    res.writeHead(400, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ error: err.message }));
+                }
+            });
+            return;
+        }
+        // Get recent events
+        if (url.pathname === "/api/events" && req.method === "GET") {
+            if (!eventBus) {
+                res.writeHead(503, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "Event bus not initialized" }));
+                return;
+            }
+            const since = url.searchParams.get("since") || undefined;
+            const pattern = url.searchParams.get("pattern") || undefined;
+            const limit = url.searchParams.get("limit") ? parseInt(url.searchParams.get("limit"), 10) : 50;
+            const events = eventBus.getEvents({ since, pattern, limit });
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ events, count: events.length }));
+            return;
+        }
+        // SSE event stream
+        if (url.pathname === "/api/events/stream" && req.method === "GET") {
+            if (!eventBus) {
+                res.writeHead(503, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "Event bus not initialized" }));
+                return;
+            }
+            const patterns = (url.searchParams.get("patterns") || "*").split(",");
+            res.writeHead(200, {
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-cache",
+                Connection: "keep-alive",
+                "Access-Control-Allow-Origin": "*",
+            });
+            res.write("retry: 3000\n\n");
+            const sub = eventBus.subscribe({
+                clientId: `sse-${Date.now()}`,
+                patterns,
+                transport: "sse",
+                callback: (event) => {
+                    res.write(`id: ${event.id}\nevent: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`);
+                },
+            });
+            req.on("close", () => {
+                eventBus.unsubscribe(sub.id);
+            });
+            return;
+        }
         // 404
         res.writeHead(404, { "Content-Type": "application/json" });
         res.end(JSON.stringify({ error: "Not found" }));
     });
+    // WebSocket upgrade for event streaming
+    if (eventBus) {
+        const wss = new WebSocketServer({ noServer: true });
+        server.on("upgrade", (request, socket, head) => {
+            const reqUrl = new URL(request.url || "/", `http://localhost:${port}`);
+            if (reqUrl.pathname !== "/ws/events") {
+                socket.destroy();
+                return;
+            }
+            if (!validateAuth(request, projectRoot, reqUrl)) {
+                socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
+                socket.destroy();
+                return;
+            }
+            wss.handleUpgrade(request, socket, head, (ws) => {
+                const patterns = (reqUrl.searchParams.get("patterns") || "*").split(",");
+                const sub = eventBus.subscribe({
+                    clientId: `ws-${Date.now()}`,
+                    patterns,
+                    transport: "websocket",
+                    callback: (event) => {
+                        if (ws.readyState === ws.OPEN) {
+                            ws.send(JSON.stringify(event));
+                        }
+                    },
+                });
+                ws.on("close", () => {
+                    eventBus.unsubscribe(sub.id);
+                });
+                ws.on("error", () => {
+                    eventBus.unsubscribe(sub.id);
+                });
+            });
+        });
+    }
     return server;
 }
 // ============================================================================
@@ -615,6 +891,89 @@ export function isRunning(projectRoot) {
         return { running: false };
     }
 }
+// ============================================================================
+// Cross-Project Helpers
+// ============================================================================
+function getTrackedProjects() {
+    // Read from both config sources (Conf library + XDG config)
+    const confStore = new Conf({ projectName: "jfl" });
+    const confProjects = confStore.get("projects") || [];
+    const xdgProjects = getConfigValue("projects") || [];
+    // Deduplicate
+    const allPaths = [...new Set([...confProjects, ...xdgProjects])];
+    return allPaths
+        .filter(p => fs.existsSync(path.join(p, ".jfl")))
+        .map(p => ({ path: p, port: getProjectPort(p) }));
+}
+async function ensureForProject(projectRoot, port, quiet = false) {
+    const status = isRunning(projectRoot);
+    if (status.running) {
+        try {
+            const response = await fetch(`http://localhost:${port}/health`, {
+                signal: AbortSignal.timeout(2000)
+            });
+            if (response.ok) {
+                return { status: "running", message: `Already running (PID: ${status.pid})` };
+            }
+        }
+        catch {
+            // Process exists but not responding, fall through
+        }
+    }
+    const portInUse = await isPortInUse(port);
+    if (portInUse) {
+        try {
+            const response = await fetch(`http://localhost:${port}/health`, {
+                signal: AbortSignal.timeout(2000)
+            });
+            if (response.ok) {
+                return { status: "running", message: "Running (PID file missing but healthy)" };
+            }
+        }
+        catch {
+            // Not responding
+        }
+        try {
+            const lsofOutput = execSync(`lsof -ti :${port}`, { encoding: 'utf-8' }).trim();
+            if (lsofOutput) {
+                const orphanedPid = parseInt(lsofOutput.split('\n')[0], 10);
+                if (!status.pid || orphanedPid !== status.pid) {
+                    process.kill(orphanedPid, 'SIGTERM');
+                    await new Promise(resolve => setTimeout(resolve, 500));
+                }
+            }
+        }
+        catch {
+            // lsof failed or process already gone
+        }
+    }
+    const result = await startDaemon(projectRoot, port);
+    if (result.success) {
+        return { status: "started", message: result.message };
+    }
+    return { status: "failed", message: result.message };
+}
+async function diagnoseProject(projectPath, port) {
+    if (!fs.existsSync(projectPath)) {
+        return { path: projectPath, port, status: "STALE", message: "Directory does not exist" };
+    }
+    const pidStatus = isRunning(projectPath);
+    if (!pidStatus.running) {
+        return { path: projectPath, port, status: "DOWN", pid: undefined };
+    }
+    try {
+        const response = await fetch(`http://localhost:${port}/health`, {
+            signal: AbortSignal.timeout(2000)
+        });
+        if (response.ok) {
+            return { path: projectPath, port, status: "OK", pid: pidStatus.pid };
+        }
+    }
+    catch {
+        // Not responding
+    }
+    return { path: projectPath, port, status: "ZOMBIE", pid: pidStatus.pid, message: "PID exists but not responding" };
+}
 async function startDaemon(projectRoot, port) {
     const status = isRunning(projectRoot);
     if (status.running) {
@@ -639,12 +998,13 @@ async function startDaemon(projectRoot, port) {
         // Fall back to current process
         jflCmd = process.argv[1];
     }
-    // Start as detached process
+    // Start as detached process with CONTEXT_HUB_DAEMON=1 so the serve
+    // action knows to ignore SIGTERM during its startup grace period
     const child = spawn(jflCmd, ["context-hub", "serve", "--port", String(port)], {
         cwd: projectRoot,
         detached: true,
         stdio: ["ignore", fs.openSync(logFile, "a"), fs.openSync(logFile, "a")],
-        env: { ...process.env, NODE_ENV: "production" }
+        env: { ...process.env, NODE_ENV: "production", CONTEXT_HUB_DAEMON: "1" }
     });
     child.unref();
     // Wait a moment to ensure process started
@@ -674,7 +1034,6 @@ async function stopDaemon(projectRoot) {
         return { success: true, message: "Context Hub is not running" };
     }
     const pidFile = getPidFile(projectRoot);
-    const tokenFile = getTokenFile(projectRoot);
     try {
         // Send SIGTERM first (graceful)
         process.kill(status.pid, "SIGTERM");
@@ -700,13 +1059,10 @@ async function stopDaemon(projectRoot) {
         catch {
             // Process is gone, that's fine
         }
-        // Clean up PID and token files
+        // Clean up PID file (preserve token for seamless restart)
         if (fs.existsSync(pidFile)) {
             fs.unlinkSync(pidFile);
         }
-        if (fs.existsSync(tokenFile)) {
-            fs.unlinkSync(tokenFile);
-        }
         return { success: true, message: "Context Hub stopped" };
     }
     catch (err) {
@@ -714,6 +1070,117 @@ async function stopDaemon(projectRoot) {
     }
 }
 // ============================================================================
+// Auto-Install Daemon
+// ============================================================================
+export async function ensureDaemonInstalled(opts) {
+    const quiet = opts?.quiet ?? false;
+    if (process.platform !== "darwin") {
+        return false;
+    }
+    const plistLabel = "com.jfl.context-hub";
+    const plistDir = path.join(homedir(), "Library", "LaunchAgents");
+    const plistPath = path.join(plistDir, `${plistLabel}.plist`);
+    const logPath = path.join(homedir(), ".config", "jfl", "context-hub-agent.log");
+    // If plist exists, check if loaded
+    if (fs.existsSync(plistPath)) {
+        try {
+            const output = execSync("launchctl list", { encoding: "utf-8" });
+            if (output.includes(plistLabel)) {
+                return true;
+            }
+        }
+        catch {
+            // launchctl failed, try to reload
+        }
+        // Exists but not loaded — reload it
+        try {
+            execSync(`launchctl load "${plistPath}"`, { stdio: "ignore" });
+            if (!quiet) {
+                console.log(chalk.green(`\n  Daemon reloaded.`));
+                console.log(chalk.gray(`  Plist: ${plistPath}\n`));
+            }
+            return true;
+        }
+        catch {
+            // Fall through to full install
+        }
+    }
+    // Full install
+    let jflPath = "";
+    try {
+        jflPath = execSync("which jfl", { encoding: "utf-8" }).trim();
+    }
+    catch {
+        jflPath = process.argv[1] || "jfl";
+    }
+    const logDir = path.dirname(logPath);
+    if (!fs.existsSync(logDir)) {
+        fs.mkdirSync(logDir, { recursive: true });
+    }
+    const plistContent = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${plistLabel}</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>${jflPath}</string>
+        <string>context-hub</string>
+        <string>ensure-all</string>
+        <string>--quiet</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>StartInterval</key>
+    <integer>300</integer>
+    <key>ProcessType</key>
+    <string>Background</string>
+    <key>LowPriorityIO</key>
+    <true/>
+    <key>Nice</key>
+    <integer>10</integer>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
+    </dict>
+    <key>StandardOutPath</key>
+    <string>${logPath}</string>
+    <key>StandardErrorPath</key>
+    <string>${logPath}</string>
+</dict>
+</plist>
+`;
+    if (!fs.existsSync(plistDir)) {
+        fs.mkdirSync(plistDir, { recursive: true });
+    }
+    // Unload if partially loaded
+    try {
+        execSync(`launchctl unload "${plistPath}" 2>/dev/null`, { stdio: "ignore" });
+    }
+    catch {
+        // Not loaded, fine
+    }
+    fs.writeFileSync(plistPath, plistContent);
+    try {
+        execSync(`launchctl load "${plistPath}"`);
+        if (!quiet) {
+            console.log(chalk.green(`\n  Daemon installed and loaded.`));
+            console.log(chalk.gray(`  Plist: ${plistPath}`));
+            console.log(chalk.gray(`  Log:   ${logPath}`));
+            console.log(chalk.gray(`  Runs ensure-all every 5 minutes + on login.\n`));
+        }
+        return true;
+    }
+    catch {
+        if (!quiet) {
+            console.log(chalk.red(`\n  Failed to load daemon.\n`));
+        }
+        return false;
+    }
+}
+// ============================================================================
 // CLI Command
 // ============================================================================
 export async function contextHubCommand(action, options = {}) {
@@ -797,69 +1264,164 @@ export async function contextHubCommand(action, options = {}) {
             break;
         }
         case "ensure": {
-            const status = isRunning(projectRoot);
-            if (status.running) {
-                // Already running, verify it's healthy
-                try {
-                    const response = await fetch(`http://localhost:${port}/health`, {
-                        signal: AbortSignal.timeout(2000)
-                    });
-                    if (response.ok) {
-                        // Healthy and running, nothing to do
-                        return;
-                    }
-                }
-                catch {
-                    // Process exists but not responding, fall through to cleanup
+            await ensureForProject(projectRoot, port, true);
+            break;
+        }
+        case "ensure-all": {
+            const tracked = getTrackedProjects();
+            if (tracked.length === 0) {
+                if (!options.quiet) {
+                    console.log(chalk.yellow("\n  No tracked projects found.\n"));
                 }
+                break;
             }
-            // Check if port is blocked by orphaned process
-            const portInUse = await isPortInUse(port);
-            if (portInUse) {
-                // Port is in use - check if it's actually Context Hub
-                try {
-                    const response = await fetch(`http://localhost:${port}/health`, {
-                        signal: AbortSignal.timeout(2000)
-                    });
-                    if (response.ok) {
-                        // It's a healthy Context Hub but PID file is missing/wrong
-                        // Don't kill it - just return
-                        return;
-                    }
+            const results = [];
+            for (const project of tracked) {
+                const name = path.basename(project.path);
+                const result = await ensureForProject(project.path, project.port, true);
+                results.push({ name, result });
+            }
+            if (!options.quiet) {
+                console.log(chalk.bold("\n  Context Hub - ensure-all\n"));
+                for (const { name, result } of results) {
+                    const icon = result.status === "failed" ? chalk.red("✗") : chalk.green("✓");
+                    const label = result.status === "started" ? chalk.cyan("started") :
+                        result.status === "running" ? chalk.green("running") :
+                            chalk.red("failed");
+                    console.log(`  ${icon} ${chalk.bold(name)} — ${label}`);
                 }
-                catch {
-                    // Process on port is not responding to health check
-                    // Only kill if we're confident it's not a Context Hub
+                const ok = results.filter(r => r.result.status !== "failed").length;
+                const fail = results.filter(r => r.result.status === "failed").length;
+                console.log(chalk.gray(`\n  ${ok} running, ${fail} failed\n`));
+            }
+            break;
+        }
+        case "doctor": {
+            const confStoreDoctor = new Conf({ projectName: "jfl" });
+            const confProjectsDoctor = confStoreDoctor.get("projects") || [];
+            const xdgProjectsDoctor = getConfigValue("projects") || [];
+            const allProjects = [...new Set([...confProjectsDoctor, ...xdgProjectsDoctor])];
+            if (allProjects.length === 0) {
+                console.log(chalk.yellow("\n  No tracked projects found.\n"));
+                break;
+            }
+            const cleanMode = process.argv.includes("--clean");
+            if (cleanMode) {
+                const before = allProjects.length;
+                const valid = allProjects.filter(p => fs.existsSync(p));
+                // Write cleaned list back to both stores
+                confStoreDoctor.set("projects", valid.filter(p => confProjectsDoctor.includes(p)));
+                setConfig("projects", valid.filter(p => xdgProjectsDoctor.includes(p)));
+                const removed = before - valid.length;
+                if (removed > 0) {
+                    console.log(chalk.green(`\n  Removed ${removed} stale project${removed > 1 ? "s" : ""} from tracker.\n`));
                 }
-                // Port in use but not responding - try to clean up
-                try {
-                    const lsofOutput = execSync(`lsof -ti :${port}`, { encoding: 'utf-8' }).trim();
-                    if (lsofOutput) {
-                        const orphanedPid = parseInt(lsofOutput.split('\n')[0], 10);
-                        // Only kill if it's different from our tracked PID
-                        if (!status.pid || orphanedPid !== status.pid) {
-                            process.kill(orphanedPid, 'SIGTERM');
-                            await new Promise(resolve => setTimeout(resolve, 500)); // Wait for cleanup
-                        }
-                    }
+                else {
+                    console.log(chalk.green("\n  No stale projects found.\n"));
                 }
-                catch {
-                    // lsof failed or process already gone
+                break;
+            }
+            console.log(chalk.bold("\n  Context Hub - doctor\n"));
+            let staleCount = 0;
+            let downCount = 0;
+            let zombieCount = 0;
+            let okCount = 0;
+            for (const projectPath of allProjects) {
+                const projectPort = getProjectPort(projectPath);
+                const result = await diagnoseProject(projectPath, projectPort);
+                const name = path.basename(result.path);
+                switch (result.status) {
+                    case "OK":
+                        console.log(`  ${chalk.green("OK")}     ${chalk.bold(name)} — PID ${result.pid}, port ${result.port}`);
+                        okCount++;
+                        break;
+                    case "ZOMBIE":
+                        console.log(`  ${chalk.red("ZOMBIE")} ${chalk.bold(name)} — PID ${result.pid} not responding on port ${result.port}`);
+                        zombieCount++;
+                        break;
+                    case "DOWN":
+                        console.log(`  ${chalk.red("DOWN")}   ${chalk.bold(name)} — not running (port ${result.port})`);
+                        downCount++;
+                        break;
+                    case "STALE":
+                        console.log(`  ${chalk.yellow("STALE")}  ${chalk.gray(result.path)} — directory missing`);
+                        staleCount++;
+                        break;
                 }
             }
-            // Start silently
-            await startDaemon(projectRoot, port);
+            console.log();
+            if (downCount > 0 || zombieCount > 0) {
+                console.log(chalk.gray(`  Hint: run ${chalk.cyan("jfl context-hub ensure-all")} to start all hubs`));
+            }
+            if (staleCount > 0) {
+                console.log(chalk.gray(`  Hint: run ${chalk.cyan("jfl context-hub doctor --clean")} to remove stale entries`));
+            }
+            if (okCount === allProjects.length) {
+                console.log(chalk.green("  All projects healthy."));
+            }
+            console.log();
+            break;
+        }
+        case "install-daemon": {
+            const result = await ensureDaemonInstalled({ quiet: false });
+            if (!result) {
+                console.log(chalk.yellow("\n  Daemon install skipped (non-macOS or failed).\n"));
+            }
+            break;
+        }
+        case "uninstall-daemon": {
+            const plistLabel = "com.jfl.context-hub";
+            const plistPath = path.join(homedir(), "Library", "LaunchAgents", `${plistLabel}.plist`);
+            if (!fs.existsSync(plistPath)) {
+                console.log(chalk.yellow("\n  Daemon not installed.\n"));
+                break;
+            }
+            try {
+                execSync(`launchctl unload "${plistPath}"`, { stdio: "ignore" });
+            }
+            catch {
+                // Already unloaded
+            }
+            fs.unlinkSync(plistPath);
+            console.log(chalk.green("\n  Daemon uninstalled.\n"));
             break;
         }
         case "serve": {
             // Run server in foreground (used by daemon)
-            const server = createServer(projectRoot, port);
+            const serviceEventsPath = path.join(projectRoot, ".jfl", "service-events.jsonl");
+            const mapPersistPath = path.join(projectRoot, ".jfl", "map-events.jsonl");
+            const journalDir = path.join(projectRoot, ".jfl", "journal");
+            const eventBus = new MAPEventBus({
+                maxSize: 1000,
+                persistPath: mapPersistPath,
+                serviceEventsPath,
+                journalDir: fs.existsSync(journalDir) ? journalDir : null,
+            });
+            const server = createServer(projectRoot, port, eventBus);
             let isListening = false;
+            // When spawned as daemon, ignore SIGTERM during startup grace period.
+            // The parent process (hook runner) may exit and send SIGTERM to the
+            // process group before we're fully detached. After grace period,
+            // re-enable normal shutdown handling.
+            const isDaemon = process.env.CONTEXT_HUB_DAEMON === "1";
+            let startupGrace = isDaemon;
+            if (isDaemon) {
+                setTimeout(() => {
+                    startupGrace = false;
+                }, 5000);
+            }
             // Error handling - keep process alive
             process.on("uncaughtException", (err) => {
                 console.error(`Uncaught exception: ${err.message}`);
                 console.error(err.stack);
-                // Don't exit - log and continue
+                telemetry.track({
+                    category: 'error',
+                    event: 'error:hub_crash',
+                    error_type: err.constructor.name,
+                    error_code: err.code || undefined,
+                    hub_port: port,
+                    hub_uptime_s: isListening ? Math.floor((Date.now() - hubStartTime) / 1000) : 0,
+                });
             });
             process.on("unhandledRejection", (reason, promise) => {
                 console.error(`Unhandled rejection at ${promise}: ${reason}`);
@@ -867,17 +1429,30 @@ export async function contextHubCommand(action, options = {}) {
             });
             server.on("error", (err) => {
                 console.error(`Server error: ${err.message}`);
+                telemetry.track({
+                    category: 'error',
+                    event: 'error:hub_server',
+                    error_type: err.constructor.name,
+                    error_code: err.code || undefined,
+                    hub_port: port,
+                });
                 if (err.code === "EADDRINUSE") {
                     console.error(`Port ${port} is already in use. Exiting.`);
                     process.exit(1);
                 }
-                // For other errors, don't exit
             });
+            const hubStartTime = Date.now();
             server.listen(port, async () => {
                 isListening = true;
                 const timestamp = new Date().toISOString();
                 console.log(`[${timestamp}] Context Hub listening on port ${port}`);
                 console.log(`[${timestamp}] PID: ${process.pid}`);
+                telemetry.track({
+                    category: 'context_hub',
+                    event: 'context_hub:started',
+                    hub_port: port,
+                    duration_ms: Date.now() - hubStartTime,
+                });
                 // Initialize memory system
                 try {
                     await initializeDatabase();
@@ -895,10 +1470,30 @@ export async function contextHubCommand(action, options = {}) {
                     console.error(`[${timestamp}] Failed to initialize memory system:`, err.message);
                     // Don't exit - memory is optional
                 }
+                // Start flow engine
+                try {
+                    const flowEngine = new FlowEngine(eventBus, projectRoot);
+                    const flowCount = await flowEngine.start();
+                    if (flowCount > 0) {
+                        console.log(`[${timestamp}] Flow engine started with ${flowCount} active flow(s)`);
+                    }
+                }
+                catch (err) {
+                    console.error(`[${timestamp}] Failed to start flow engine:`, err.message);
+                }
+                console.log(`[${timestamp}] MAP event bus initialized (buffer: 1000, subscribers: ${eventBus.getSubscriberCount()})`);
                 console.log(`[${timestamp}] Ready to serve requests`);
             });
             // Handle shutdown gracefully
             const shutdown = (signal) => {
+                // During startup grace period (daemon mode), ignore SIGTERM from
+                // parent process cleanup. This prevents the hook runner from
+                // killing the hub before it's fully detached.
+                if (startupGrace && signal === "SIGTERM") {
+                    const ts = new Date().toISOString();
+                    console.log(`[${ts}] Ignoring ${signal} during startup grace period (PID: ${process.pid}, Parent: ${process.ppid})`);
+                    return;
+                }
                 if (!isListening) {
                     // Server never started, just exit
                     process.exit(0);
@@ -909,7 +1504,14 @@ export async function contextHubCommand(action, options = {}) {
                 console.log(`[${timestamp}] Received ${signal}`);
                 console.log(`[${timestamp}] PID: ${process.pid}, Parent PID: ${process.ppid}`);
                 console.log(`[${timestamp}] Shutting down...`);
+                telemetry.track({
+                    category: 'context_hub',
+                    event: 'context_hub:stopped',
+                    hub_port: port,
+                    hub_uptime_s: Math.floor((Date.now() - hubStartTime) / 1000),
+                });
                 server.close(() => {
+                    eventBus.destroy();
                     console.log(`[${new Date().toISOString()}] Server closed`);
                     process.exit(0);
                 });
@@ -964,6 +1566,18 @@ export async function contextHubCommand(action, options = {}) {
             });
             break;
         }
+        case "dashboard": {
+            const token = getOrCreateToken(projectRoot);
+            const dashUrl = `http://localhost:${port}/dashboard?token=${token}`;
+            try {
+                execSync(`open "${dashUrl}"`);
+            }
+            catch {
+                // open not available — print URL instead
+            }
+            console.log(chalk.gray(`  Opening ${dashUrl}`));
+            break;
+        }
         case "clear-logs": {
             // Clear both global and local log files
             const { JFL_FILES } = await import("../utils/jfl-paths.js");
@@ -990,17 +1604,24 @@ export async function contextHubCommand(action, options = {}) {
         default: {
             console.log(chalk.bold("\n  Context Hub - Unified context for AI agents\n"));
             console.log(chalk.gray("  Commands:"));
-            console.log("    jfl context-hub start       Start the daemon");
-            console.log("    jfl context-hub stop        Stop the daemon");
-            console.log("    jfl context-hub restart     Restart the daemon");
-            console.log("    jfl context-hub status      Check if running");
-            console.log("    jfl context-hub logs        Show real-time logs (TUI)");
-            console.log("    jfl context-hub clear-logs  Clear log file");
-            console.log("    jfl context-hub ensure      Start if not running (for hooks)");
-            console.log("    jfl context-hub query       Quick context query");
+            console.log("    jfl context-hub start            Start the daemon");
+            console.log("    jfl context-hub stop             Stop the daemon");
+            console.log("    jfl context-hub restart          Restart the daemon");
+            console.log("    jfl context-hub status           Check if running");
+            console.log("    jfl context-hub ensure           Start if not running (for hooks)");
+            console.log("    jfl context-hub ensure-all       Ensure all tracked projects are running");
+            console.log("    jfl context-hub doctor           Diagnose all tracked projects");
+            console.log("    jfl context-hub doctor --clean   Remove stale project entries");
+            console.log("    jfl context-hub dashboard        Open web dashboard in browser");
+            console.log("    jfl context-hub install-daemon   Install macOS launchd keepalive");
+            console.log("    jfl context-hub uninstall-daemon Remove macOS launchd keepalive");
+            console.log("    jfl context-hub logs             Show real-time logs (TUI)");
+            console.log("    jfl context-hub clear-logs       Clear log file");
+            console.log("    jfl context-hub query            Quick context query");
             console.log();
             console.log(chalk.gray("  Options:"));
             console.log("    --port <port>   Port to run on (default: per-project)");
+            console.log("    --quiet         Suppress output (for daemon use)");
             console.log();
         }
     }