@shawnowen/comet-mcp 2.3.1 → 2.4.2

package/dist/http-server.js

@@ -6,10 +6,236 @@
 // Architecture:
 //   Cowork VM -> Claude-in-Chrome MCP -> Chrome fetch('localhost:3456') -> this server -> CDP -> Comet
 import { createServer } from "node:http";
+import { readFileSync, mkdirSync, writeFileSync, appendFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
 import { cometClient } from "./cdp-client.js";
 import { cometAI } from "./comet-ai.js";
 import { tabGroupsClient } from "./tab-groups.js";
+import { startBindingReaper, readReaperConfig } from "./binding-reaper.js";
+import { BoundSessionError, resolveHttpBoundSession } from "./bound-session.js";
+import { createOrReuseDelegateBinding } from "./delegate-binding.js";
+import { deriveCodexSessionIdentity, windowBindingStore, } from "./window-bindings.js";
+import { readAgentRegistry, classifyAgentStatus, getHealth, getSnapshot, getStatus, getDetail, formatHealth, formatSnapshot, } from "./observer.js";
+import { dispatchAlert } from "./alert-dispatcher.js";
 const PORT = parseInt(process.env.COMET_HTTP_PORT || "3456", 10);
+// Lifecycle + orchestration paths (mirrored from index.ts)
+const CC_LIFECYCLE_URL = process.env.COMET_CC_LIFECYCLE_URL || "http://localhost:3001/command-center/api/comet/lifecycle";
+const OUTBOX_PATH = join(homedir(), "equabot", "agent-chat", "outbox-comet.jsonl");
+const INBOX_PATH = join(homedir(), "equabot", "agent-chat", "inbox-comet.jsonl");
+const MANIFEST_PATH = join(homedir(), ".claude", "comet-browser", "session-manifest.json");
+const EQUA_SERVER_URL = process.env.EQUA_SERVER_URL || "http://localhost:3000";
+const EQUANAUT_GATEWAY_ASK_URL = process.env.EQUANAUT_GATEWAY_ASK_URL || "";
+const EQUANAUT_GATEWAY_STATUS_URLS = [
+    process.env.EQUANAUT_GATEWAY_STATUS_URL,
+    "http://localhost:3001/api/v1/agent/gateway/status",
+    "http://localhost:3001/command-center/api/v1/agent/gateway/status",
+    "http://localhost:3000/api/v1/agent/gateway/status",
+].filter(Boolean);
+const EQUANAUT_OLLAMA_BASE = process.env.EQUANAUT_OLLAMA_BASE || "http://localhost:11434";
+// ---- Helper utilities ----
+/** Safely quote a CSS selector for use in browser evaluate() expressions */
+function safeSelector(sel) {
+    return JSON.stringify(sel);
+}
+/** Append a JSON line to a JSONL file (non-fatal if directory missing) */
+function appendJsonl(filePath, obj) {
+    try {
+        mkdirSync(dirname(filePath), { recursive: true });
+        appendFileSync(filePath, JSON.stringify(obj) + "\n", "utf-8");
+    }
+    catch {
+        /* non-fatal — outbox may not be configured */
+    }
+}
+/** Read and parse a JSON file safely, returning null on any error */
+function readJsonSafe(filePath) {
+    try {
+        return JSON.parse(readFileSync(filePath, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** POST to Command Center lifecycle API */
+async function callLifecycleEndpoint(payload) {
+    const resp = await fetch(CC_LIFECYCLE_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(5000),
+    });
+    const data = await resp.text();
+    if (!resp.ok) {
+        throw new Error(`CC-SO lifecycle ${resp.status}: ${data.substring(0, 200)}`);
+    }
+    return data;
+}
+/**
+ * Session guard for browsing endpoints.
+ * Returns true (and sends HTTP 409) if no active session; returns false if OK to proceed.
+ */
+function requireSession(res) {
+    if (!cometClient.isConnected) {
+        errorJson(res, "No active Comet session. Call POST /api/connect first.", 409);
+        return true;
+    }
+    return false;
+}
+function paramsToRecord(params) {
+    const args = {};
+    for (const [key, value] of params.entries()) {
+        if (["windowId", "tabGroupId", "groupId"].includes(key)) {
+            const parsed = Number(value);
+            args[key] = Number.isFinite(parsed) ? parsed : value;
+        }
+        else {
+            args[key] = value;
+        }
+    }
+    return args;
+}
+function identityInputFromArgs(args = {}) {
+    return {
+        codexSessionId: args.codexSessionId,
+        projectThreadId: args.projectThreadId,
+        projectThreadFamily: args.projectThreadFamily,
+        worktreePath: args.worktreePath,
+        repoSlug: args.repoSlug,
+        branchName: args.branchName,
+        sessionKey: args.sessionKey,
+        role: args.codexSessionRole,
+        strict: true,
+        fallbackAgentId: args.agentId,
+        fallbackTaskThreadId: args.taskThreadId,
+    };
+}
+function assertAgentRuntimeProfileArg(profile) {
+    if (profile === undefined ||
+        profile === null ||
+        profile === "" ||
+        profile === "agent" ||
+        profile === "oe") {
+        return profile === "agent" ? "oe" : profile;
+    }
+    throw new Error(`PROFILE_OWNERSHIP_VIOLATION: profile ${String(profile)} is not an agent-owned Comet runtime profile`);
+}
+async function getWindowIdForTarget(targetId) {
+    const CDP = (await import("chrome-remote-interface")).default;
+    const client = await CDP({ host: "127.0.0.1", port: 9222, target: targetId });
+    try {
+        const { windowId } = await client.Browser.getWindowForTarget();
+        return windowId;
+    }
+    finally {
+        try {
+            await client.close();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+/**
+ * Resolve the distinct live window ids for the window-binding reaper (Spec 084).
+ * Returns `null` when the live set cannot be determined (CDP unreachable, or page
+ * targets exist but none resolved) so the reaper performs a safe no-op instead of
+ * treating every binding as missing.
+ */
+async function getLiveWindowIds() {
+    try {
+        const resp = await fetch("http://127.0.0.1:9222/json", {
+            signal: AbortSignal.timeout(5000),
+        });
+        const targets = (await resp.json());
+        const pages = targets.filter((t) => t.type === "page" && typeof t.id === "string");
+        const ids = new Set();
+        for (const t of pages) {
+            try {
+                ids.add(await getWindowIdForTarget(t.id));
+            }
+            catch {
+                /* per-target resolution failure — skip this target */
+            }
+        }
+        // Page targets existed but none resolved → treat live set as unknown (no-op).
+        if (pages.length > 0 && ids.size === 0)
+            return null;
+        return [...ids];
+    }
+    catch {
+        return null; // CDP unreachable → unknown
+    }
+}
+/**
+ * Archive a recovery snapshot of a binding before the reaper deletes it
+ * (Spec 084 FR-006). Writes a JSON record into the snapshots dir; throwing here
+ * causes the reaper to skip the delete (fail-safe).
+ */
+async function archiveBindingForReap(binding) {
+    const dir = join(homedir(), ".claude", "comet-browser", "snapshots");
+    mkdirSync(dir, { recursive: true });
+    const safeId = binding.bindingId.replace(/[^a-zA-Z0-9_-]/g, "");
+    const file = join(dir, `reaped-binding-${safeId}-${Date.now()}.json`);
+    writeFileSync(file, JSON.stringify({ reapedAt: new Date().toISOString(), reason: "ttl-reaper", binding }, null, 2));
+    dispatchAlert({
+        type: "ORPHAN_REAPED",
+        message: `Window binding ${binding.bindingId} reaped by TTL reaper after recovery snapshot.`,
+        consumerId: binding.codexSessionId,
+        sessionKey: binding.sessionKey,
+        context: {
+            bindingId: binding.bindingId,
+            runIds: binding.runIds,
+            windowId: binding.windowId,
+            tabGroupId: binding.tabGroupId,
+            targetId: binding.targetId,
+            repoSlug: binding.repoSlug,
+            branchName: binding.branchName,
+            snapshotPath: file,
+            reaperReason: "ttl-reaper",
+        },
+    });
+    console.log(`[binding-reaper] archived recovery snapshot -> ${file}`);
+}
+function writeBoundError(res, err) {
+    if (err instanceof BoundSessionError) {
+        errorJson(res, `${err.code}: ${err.message}. ${err.repairAction}`, err.status);
+        return true;
+    }
+    return false;
+}
+async function requireHttpBinding(res, args) {
+    try {
+        const resolved = await resolveHttpBoundSession(identityInputFromArgs(args), args);
+        if (resolved.binding.targetId) {
+            await cometClient.connect(resolved.binding.targetId);
+        }
+        return resolved.binding;
+    }
+    catch (err) {
+        if (!writeBoundError(res, err))
+            throw err;
+        return null;
+    }
+}
+async function attachRunIdToHttpBinding(runId, args) {
+    if (!runId)
+        return null;
+    const bindingId = typeof args.bindingId === "string" ? args.bindingId : undefined;
+    if (bindingId) {
+        return windowBindingStore.addRunId(bindingId, runId);
+    }
+    try {
+        const identity = deriveCodexSessionIdentity(identityInputFromArgs(args));
+        const binding = await windowBindingStore.findActiveByIdentity(identity);
+        if (!binding)
+            return null;
+        return windowBindingStore.addRunId(binding.bindingId, runId);
+    }
+    catch {
+        return null;
+    }
+}
 // Simple mutex to prevent concurrent CDP operations
 let busy = false;
 function json(res, data, status = 200) {
@@ -40,6 +266,138 @@ async function readBody(req) {
         });
     });
 }
+async function fetchJsonWithTimeout(url, init = {}, timeoutMs = 1500) {
+    const resp = await fetch(url, { ...init, signal: AbortSignal.timeout(timeoutMs) });
+    const contentType = resp.headers.get("content-type") || "";
+    const data = contentType.includes("application/json") ? await resp.json() : await resp.text();
+    return { resp, data };
+}
+function routerCapability(reachable, extra = {}) {
+    return { reachable, fresh: reachable, ...extra };
+}
+function routerCapabilityUsable(capability) {
+    return !!(capability &&
+        capability.reachable === true &&
+        capability.fresh !== false &&
+        capability.connected !== false &&
+        capability.usable !== false);
+}
+function selectRouterRoute(capabilities) {
+    if (routerCapabilityUsable(capabilities.equaGateway)) {
+        return { route: "gateway", degraded: false };
+    }
+    if (routerCapabilityUsable(capabilities.equaApi)) {
+        return {
+            route: "equa_api_enriched",
+            degraded: true,
+            degradedReason: "gateway unavailable; using Equa API context enrichment",
+        };
+    }
+    if (routerCapabilityUsable(capabilities.cometBridgeAsk)) {
+        return {
+            route: "comet_bridge",
+            degraded: true,
+            degradedReason: "gateway and Equa API unavailable; using Comet bridge fallback",
+        };
+    }
+    if (routerCapabilityUsable(capabilities.localModel)) {
+        return {
+            route: "local_model",
+            degraded: true,
+            degradedReason: "gateway, Equa API, and Comet bridge unavailable; using local model fallback",
+        };
+    }
+    return { route: "unavailable", degraded: true, degradedReason: "no router backend reachable" };
+}
+function mergeRouterCapability(probedCapability, envelopeCapability) {
+    if (!probedCapability)
+        return envelopeCapability || {};
+    if (!envelopeCapability)
+        return probedCapability;
+    const probedUsable = routerCapabilityUsable(probedCapability);
+    const envelopeUsable = routerCapabilityUsable(envelopeCapability);
+    const preferred = probedUsable || !envelopeUsable ? probedCapability : envelopeCapability;
+    return {
+        ...envelopeCapability,
+        ...probedCapability,
+        ...preferred,
+    };
+}
+function mergeRouterCapabilities(probedCapabilities, envelopeCapabilities) {
+    const merged = { ...envelopeCapabilities, ...probedCapabilities };
+    for (const key of new Set([
+        ...Object.keys(envelopeCapabilities || {}),
+        ...Object.keys(probedCapabilities || {}),
+    ])) {
+        merged[key] = mergeRouterCapability(probedCapabilities?.[key], envelopeCapabilities?.[key]);
+    }
+    return merged;
+}
+async function probeGatewayCapability() {
+    for (const url of EQUANAUT_GATEWAY_STATUS_URLS) {
+        try {
+            const { resp, data } = await fetchJsonWithTimeout(url, { method: "GET", headers: { Accept: "application/json" } }, 1200);
+            if (!resp.ok || typeof data !== "object" || data === null)
+                continue;
+            const payload = data;
+            if (payload.connected) {
+                return routerCapability(true, {
+                    connected: true,
+                    modelId: payload.modelId || payload.model?.id || payload.model || null,
+                    threadId: payload.threadId || payload.sessionKey || null,
+                    statusUrl: url,
+                });
+            }
+        }
+        catch {
+            /* try next status URL */
+        }
+    }
+    return routerCapability(false, { connected: false });
+}
+async function probeEquaApiCapability() {
+    try {
+        const { resp } = await fetchJsonWithTimeout(`${EQUA_SERVER_URL}/api/equanaut/threads`, { method: "GET", headers: { Accept: "application/json" } }, 1200);
+        // Auth failures still prove the API surface is reachable. The router can
+        // report reachability while leaving authenticated data access to configured
+        // local credentials.
+        if (resp.ok || resp.status === 401 || resp.status === 403) {
+            return routerCapability(true, { status: resp.status, baseUrl: EQUA_SERVER_URL });
+        }
+    }
+    catch {
+        /* unavailable */
+    }
+    return routerCapability(false, { baseUrl: EQUA_SERVER_URL });
+}
+async function probeLocalModelCapability() {
+    try {
+        const { resp, data } = await fetchJsonWithTimeout(`${EQUANAUT_OLLAMA_BASE}/api/tags`, { method: "GET", headers: { Accept: "application/json" } }, 1200);
+        if (resp.ok) {
+            const models = data?.models;
+            const firstModel = Array.isArray(models) && models[0] ? models[0].name || models[0].model : null;
+            return routerCapability(true, { modelId: firstModel || null });
+        }
+    }
+    catch {
+        /* unavailable */
+    }
+    return routerCapability(false);
+}
+async function getEquanautRouterCapabilities() {
+    const [gateway, equaApi, localModel] = await Promise.all([
+        probeGatewayCapability(),
+        probeEquaApiCapability(),
+        probeLocalModelCapability(),
+    ]);
+    return {
+        cometMcpRouter: routerCapability(true, { port: PORT }),
+        equaGateway: gateway,
+        equaApi,
+        cometBridgeAsk: routerCapability(true, { path: "/api/ask" }),
+        localModel,
+    };
+}
 async function withMutex(res, fn) {
     if (busy) {
         errorJson(res, "Server busy — another operation is in progress. Try again shortly.", 429);
@@ -54,37 +412,58 @@ async function withMutex(res, fn) {
     }
 }
 // ---- Route handlers (mirrored from index.ts MCP tool handlers) ----
-async function handleConnect(res) {
+async function handleConnect(res, body) {
+    const identity = deriveCodexSessionIdentity(identityInputFromArgs(body));
     const result = await withMutex(res, async () => {
+        const profileAlias = assertAgentRuntimeProfileArg(body.profile);
         const startResult = await cometClient.startComet(9222);
-        const targets = await cometClient.listTargets();
-        const pageTabs = targets.filter((t) => t.type === "page");
-        if (pageTabs.length > 1) {
-            for (let i = 1; i < pageTabs.length; i++) {
-                try {
-                    await cometClient.closeTab(pageTabs[i].id);
-                }
-                catch { /* ignore */ }
-            }
-        }
-        const freshTargets = await cometClient.listTargets();
-        const anyPage = freshTargets.find((t) => t.type === "page");
-        if (anyPage) {
-            await cometClient.connect(anyPage.id);
-            await cometClient.navigate("https://www.perplexity.ai/", true);
-            await new Promise((r) => setTimeout(r, 1500));
-            return { message: `${startResult}\nConnected to Perplexity (cleaned ${pageTabs.length - 1} old tabs)` };
-        }
-        const newTab = await cometClient.newTab("https://www.perplexity.ai/");
+        const initialUrl = `about:blank#comet-http-session-${Date.now()}`;
+        const windowTab = await tabGroupsClient.createTopDisplayFullscreenWindowWithTab(initialUrl);
+        const newTab = await cometClient.waitForTargetUrl(initialUrl);
         await new Promise((r) => setTimeout(r, 2000));
         await cometClient.connect(newTab.id);
-        return { message: `${startResult}\nCreated new tab and navigated to Perplexity` };
+        await cometClient.navigate("https://www.perplexity.ai/", true);
+        await cometClient.positionOnTopDisplay(newTab.id);
+        const targetId = newTab.id;
+        let tabGroupId = null;
+        // Create tab group for the new agent session (FR-007, spec 010)
+        // Mirrors MCP tool path: session-registry.ts creates a dedicated window and group.
+        try {
+            const group = await tabGroupsClient.createGroup({
+                tabIds: [windowTab.tabId],
+                title: `session-${Date.now()}`,
+                color: "blue",
+            });
+            tabGroupId = group.groupId;
+        }
+        catch {
+            // Tab group creation is advisory — do not fail the connection
+        }
+        const windowId = windowTab.windowId || (await getWindowIdForTarget(targetId));
+        const bindingResult = await windowBindingStore.createOrReuse({
+            ...identity,
+            windowId,
+            tabGroupId,
+            targetId,
+            runIds: typeof body.runId === "string" ? [body.runId] : [],
+            profileId: "agent",
+            profileAlias: profileAlias || "oe",
+            profileOwner: "agent",
+        });
+        return {
+            message: `${startResult}\nCreated dedicated top-display full-screen bounds window and tab group`,
+            binding: bindingResult.binding,
+            bindingAction: bindingResult.action,
+        };
     });
     if (result)
         json(res, result);
 }
 async function handleAsk(res, body) {
     const result = await withMutex(res, async () => {
+        const binding = await requireHttpBinding(res, body);
+        if (!binding)
+            return null;
         let prompt = body.prompt;
         const timeout = body.timeout || 15000;
         const newChat = body.newChat || false;
@@ -97,20 +476,10 @@ async function handleAsk(res, body) {
             .replace(/\n+/g, " ")
             .replace(/\s+/g, " ")
             .trim();
-        // newChat: full reset
+        // newChat: navigate to fresh Perplexity page (without closing other agents' tabs)
         if (newChat) {
             const targets = await cometClient.listTargets();
-            const pageTabs = targets.filter((t) => t.type === "page");
-            if (pageTabs.length > 1) {
-                for (let i = 1; i < pageTabs.length; i++) {
-                    try {
-                        await cometClient.closeTab(pageTabs[i].id);
-                    }
-                    catch { /* ignore */ }
-                }
-            }
-            const freshTargets = await cometClient.listTargets();
-            const mainTab = freshTargets.find((t) => t.type === "page");
+            const mainTab = targets.find((t) => t.type === "page");
             if (mainTab)
                 await cometClient.connect(mainTab.id);
             await cometClient.navigate("https://www.perplexity.ai/", true);
@@ -170,7 +539,10 @@ async function handleAsk(res, body) {
                     stepsCollected.push(step);
             }
             if (status.status === "completed" && sawNewResponse) {
-                return { status: "completed", response: status.response || "Task completed (no response text extracted)" };
+                return {
+                    status: "completed",
+                    response: status.response || "Task completed (no response text extracted)",
+                };
             }
         }
         // Timeout — return in-progress status
@@ -192,8 +564,79 @@ async function handleAsk(res, body) {
         }
     }
 }
-async function handlePoll(res) {
+async function handleEquanautRouterStatus(res) {
+    const capabilities = await getEquanautRouterCapabilities();
+    json(res, {
+        capabilities,
+        decision: selectRouterRoute(capabilities),
+        timestamp: new Date().toISOString(),
+    });
+}
+async function handleEquanautRouterAsk(res, body) {
+    const prompt = body.prompt;
+    const envelope = body.envelope || {};
+    if (!prompt || !prompt.trim()) {
+        errorJson(res, "prompt is required", 400);
+        return;
+    }
+    const probedCapabilities = await getEquanautRouterCapabilities();
+    const envelopeCapabilities = envelope.capabilities && typeof envelope.capabilities === "object" ? envelope.capabilities : {};
+    const liveCapabilities = mergeRouterCapabilities(probedCapabilities, envelopeCapabilities);
+    const decision = selectRouterRoute(liveCapabilities);
+    if (decision.route === "gateway" && EQUANAUT_GATEWAY_ASK_URL) {
+        try {
+            const { resp, data } = await fetchJsonWithTimeout(EQUANAUT_GATEWAY_ASK_URL, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", Accept: "application/json" },
+                body: JSON.stringify({ prompt, envelope, timeout: body.timeout || 60000 }),
+            }, Number(body.timeout || 60000));
+            if (!resp.ok) {
+                json(res, {
+                    ...decision,
+                    error: `gateway ask ${resp.status}`,
+                    details: typeof data === "string" ? data.slice(0, 200) : data,
+                }, 502);
+                return;
+            }
+            const payload = typeof data === "object" && data !== null ? data : {};
+            json(res, {
+                ...decision,
+                response: payload.response || payload.answer || payload.text || "",
+                telemetry: {
+                    route: decision.route,
+                    degraded: decision.degraded,
+                    activeWindowId: envelope.telemetry?.activeWindowId || null,
+                    completedAt: new Date().toISOString(),
+                },
+            });
+            return;
+        }
+        catch (err) {
+            json(res, {
+                ...decision,
+                error: `gateway ask unavailable: ${err instanceof Error ? err.message : String(err)}`,
+            }, 502);
+            return;
+        }
+    }
+    json(res, {
+        ...decision,
+        error: decision.route === "gateway"
+            ? "gateway route selected but EQUANAUT_GATEWAY_ASK_URL is not configured"
+            : "router has no stronger configured answer route; caller should use existing fallback",
+        telemetry: {
+            route: decision.route,
+            degraded: decision.degraded,
+            activeWindowId: envelope.telemetry?.activeWindowId || null,
+            completedAt: new Date().toISOString(),
+        },
+    }, 503);
+}
+async function handlePoll(res, args) {
     const result = await withMutex(res, async () => {
+        const binding = await requireHttpBinding(res, args);
+        if (!binding)
+            return null;
         const status = await cometAI.getAgentStatus();
         if (status.status === "completed" && status.response) {
             return { status: "completed", response: status.response };
@@ -216,8 +659,11 @@ async function handleStop(res) {
     if (result)
         json(res, result);
 }
-async function handleScreenshot(res) {
+async function handleScreenshot(res, args) {
     const result = await withMutex(res, async () => {
+        const binding = await requireHttpBinding(res, args);
+        if (!binding)
+            return null;
         const screenshot = await cometClient.screenshot("png");
         return { data: screenshot.data, mimeType: "image/png" };
     });
@@ -249,7 +695,12 @@ async function handleMode(res, body) {
       `);
             return { currentMode: modeResult.result.value };
         }
-        const modeMap = { search: "Search", research: "Research", labs: "Labs", learn: "Learn" };
+        const modeMap = {
+            search: "Search",
+            research: "Research",
+            labs: "Labs",
+            learn: "Learn",
+        };
         const ariaLabel = modeMap[mode];
         if (!ariaLabel) {
             return { error: `Invalid mode: ${mode}. Use: search, research, labs, learn` };
@@ -307,6 +758,1486 @@ async function handleMode(res, body) {
         }
     }
 }
+// ---- Navigation & Interaction handlers (require session) ----
+async function handleNavigate(res, body) {
+    const result = await withMutex(res, async () => {
+        const binding = await requireHttpBinding(res, body);
+        if (!binding)
+            return null;
+        const url = body.url;
+        if (!url || url.trim().length === 0) {
+            return { error: "url is required" };
+        }
+        const waitForIdle = body.waitForIdle !== false; // default true
+        const navResult = await cometClient.navigate(url, true, waitForIdle);
+        const finalUrlResult = await cometClient.safeEvaluate("window.location.href");
+        const finalUrl = finalUrlResult.result.value || url;
+        const titleResult = await cometClient.safeEvaluate("document.title");
+        const title = titleResult.result.value || "";
+        return {
+            url: finalUrl,
+            title,
+            networkIdle: navResult.networkIdle !== undefined ? navResult.networkIdle : null,
+        };
+    });
+    if (result !== null) {
+        if (result && "error" in result)
+            errorJson(res, result.error, 400);
+        else if (result)
+            json(res, result);
+    }
+}
+async function handleInteract(res, body) {
+    const result = await withMutex(res, async () => {
+        const binding = await requireHttpBinding(res, body);
+        if (!binding)
+            return null;
+        const actions = body.actions;
+        if (!actions || actions.length === 0) {
+            return { error: "actions array is required and cannot be empty" };
+        }
+        const results = [];
+        for (const act of actions) {
+            try {
+                switch (act.action) {
+                    case "click": {
+                        if (!act.selector)
+                            throw new Error("click requires a selector");
+                        const clicked = await cometClient.safeEvaluate(`
+              (() => {
+                const el = document.querySelector(${safeSelector(act.selector)});
+                if (!el) return JSON.stringify({ ok: false, error: 'Element not found: ${act.selector.replace(/'/g, "\\'")}' });
+                el.scrollIntoView({ block: 'center' });
+                el.click();
+                return JSON.stringify({ ok: true, tag: el.tagName, text: (el.textContent || '').trim().substring(0, 80) });
+              })()
+            `);
+                        const clickRes = JSON.parse(clicked.result.value);
+                        if (!clickRes.ok)
+                            throw new Error(clickRes.error);
+                        results.push({
+                            action: "click",
+                            success: true,
+                            result: `Clicked <${clickRes.tag}> "${clickRes.text}"`,
+                        });
+                        break;
+                    }
+                    case "type": {
+                        if (!act.selector)
+                            throw new Error("type requires a selector");
+                        if (!act.value)
+                            throw new Error("type requires a value");
+                        await cometClient.safeEvaluate(`
+              (() => {
+                const el = document.querySelector(${safeSelector(act.selector)});
+                if (!el) throw new Error('Element not found');
+                el.focus();
+              })()
+            `);
+                        for (const char of act.value) {
+                            await cometClient.pressKey(char);
+                            await new Promise((r) => setTimeout(r, 50));
+                        }
+                        results.push({
+                            action: "type",
+                            success: true,
+                            result: `Typed ${act.value.length} chars`,
+                        });
+                        break;
+                    }
+                    case "fill": {
+                        if (!act.selector)
+                            throw new Error("fill requires a selector");
+                        const fillRes = await cometClient.safeEvaluate(`
+              (() => {
+                const el = document.querySelector(${safeSelector(act.selector)});
+                if (!el) return JSON.stringify({ ok: false, error: 'Element not found' });
+                el.focus();
+                if (el.tagName === 'INPUT' || el.tagName === 'TEXTAREA') {
+                  const nativeSetter = Object.getOwnPropertyDescriptor(
+                    el.tagName === 'INPUT' ? HTMLInputElement.prototype : HTMLTextAreaElement.prototype, 'value'
+                  )?.set;
+                  if (nativeSetter) nativeSetter.call(el, ${JSON.stringify(act.value || "")});
+                  else el.value = ${JSON.stringify(act.value || "")};
+                  el.dispatchEvent(new Event('input', { bubbles: true }));
+                  el.dispatchEvent(new Event('change', { bubbles: true }));
+                } else if (el.contentEditable === 'true') {
+                  el.focus();
+                  document.execCommand('selectAll', false, null);
+                  document.execCommand('insertText', false, ${JSON.stringify(act.value || "")});
+                }
+                return JSON.stringify({ ok: true });
+              })()
+            `);
+                        const fRes = JSON.parse(fillRes.result.value);
+                        if (!fRes.ok)
+                            throw new Error(fRes.error);
+                        results.push({
+                            action: "fill",
+                            success: true,
+                            result: `Filled with "${(act.value || "").substring(0, 40)}"`,
+                        });
+                        break;
+                    }
+                    case "press": {
+                        const key = act.key || act.value || "Enter";
+                        if (act.selector) {
+                            await cometClient.safeEvaluate(`
+                (() => {
+                  const el = document.querySelector(${safeSelector(act.selector)});
+                  if (el) el.focus();
+                })()
+              `);
+                        }
+                        await cometClient.pressKey(key);
+                        results.push({ action: "press", success: true, result: `Pressed ${key}` });
+                        break;
+                    }
+                    case "check":
+                    case "uncheck": {
+                        if (!act.selector)
+                            throw new Error(`${act.action} requires a selector`);
+                        const shouldCheck = act.action === "check";
+                        const checkRes = await cometClient.safeEvaluate(`
+              (() => {
+                const el = document.querySelector(${safeSelector(act.selector)});
+                if (!el) return JSON.stringify({ ok: false, error: 'Element not found' });
+                const isCheckbox = el.type === 'checkbox' || el.getAttribute('role') === 'checkbox';
+                if (isCheckbox) {
+                  if (el.checked !== ${shouldCheck}) el.click();
+                  return JSON.stringify({ ok: true, checked: ${shouldCheck} });
+                }
+                el.scrollIntoView({ block: 'center' });
+                el.click();
+                return JSON.stringify({ ok: true, clicked: true });
+              })()
+            `);
+                        const cRes = JSON.parse(checkRes.result.value);
+                        if (!cRes.ok)
+                            throw new Error(cRes.error);
+                        results.push({
+                            action: act.action,
+                            success: true,
+                            result: `${act.action}ed: ${act.selector}`,
+                        });
+                        break;
+                    }
+                    case "select": {
+                        if (!act.selector)
+                            throw new Error("select requires a selector");
+                        if (!act.value)
+                            throw new Error("select requires a value");
+                        const selRes = await cometClient.safeEvaluate(`
+              (() => {
+                const el = document.querySelector(${safeSelector(act.selector)});
+                if (!el || el.tagName !== 'SELECT') return JSON.stringify({ ok: false, error: 'SELECT element not found' });
+                let found = false;
+                for (const opt of el.options) {
+                  if (opt.value === ${JSON.stringify(act.value)} || opt.text === ${JSON.stringify(act.value)}) {
+                    el.value = opt.value;
+                    found = true;
+                    break;
+                  }
+                }
+                if (!found) return JSON.stringify({ ok: false, error: 'Option not found' });
+                el.dispatchEvent(new Event('change', { bubbles: true }));
+                return JSON.stringify({ ok: true, selected: el.value });
+              })()
+            `);
+                        const sRes = JSON.parse(selRes.result.value);
+                        if (!sRes.ok)
+                            throw new Error(sRes.error);
+                        results.push({ action: "select", success: true, result: `Selected: ${sRes.selected}` });
+                        break;
+                    }
+                    case "scroll": {
+                        const dir = act.direction || "down";
+                        const amount = act.amount || 500;
+                        const dx = dir === "right" ? amount : dir === "left" ? -amount : 0;
+                        const dy = dir === "down" ? amount : dir === "up" ? -amount : 0;
+                        if (act.selector) {
+                            await cometClient.safeEvaluate(`
+                (() => {
+                  const el = document.querySelector(${safeSelector(act.selector)});
+                  if (el) el.scrollBy(${dx}, ${dy});
+                })()
+              `);
+                        }
+                        else {
+                            await cometClient.safeEvaluate(`window.scrollBy(${dx}, ${dy})`);
+                        }
+                        results.push({
+                            action: "scroll",
+                            success: true,
+                            result: `Scrolled ${dir} ${amount}px`,
+                        });
+                        break;
+                    }
+                    case "wait": {
+                        if (act.selector) {
+                            const waitTimeout = act.ms || 10000;
+                            const start = Date.now();
+                            let found = false;
+                            while (Date.now() - start < waitTimeout) {
+                                const exists = await cometClient.safeEvaluate(`document.querySelector(${safeSelector(act.selector)}) !== null`);
+                                if (exists.result.value === true) {
+                                    found = true;
+                                    break;
+                                }
+                                await new Promise((r) => setTimeout(r, 300));
+                            }
+                            if (!found)
+                                throw new Error(`Timeout waiting for ${act.selector}`);
+                            results.push({ action: "wait", success: true, result: `Found: ${act.selector}` });
+                        }
+                        else {
+                            const ms = act.ms || 1000;
+                            await new Promise((r) => setTimeout(r, ms));
+                            results.push({ action: "wait", success: true, result: `Waited ${ms}ms` });
+                        }
+                        break;
+                    }
+                    case "extract": {
+                        if (!act.selector)
+                            throw new Error("extract requires a selector");
+                        const extRes = await cometClient.safeEvaluate(`
+              (() => {
+                const el = document.querySelector(${safeSelector(act.selector)});
+                if (!el) return JSON.stringify({ ok: false, error: 'Element not found' });
+                return JSON.stringify({
+                  ok: true,
+                  text: el.innerText?.trim() || '',
+                  value: el.value || '',
+                  tag: el.tagName,
+                });
+              })()
+            `);
+                        const eRes = JSON.parse(extRes.result.value);
+                        if (!eRes.ok)
+                            throw new Error(eRes.error);
+                        const extracted = eRes.text || eRes.value || `<${eRes.tag}>`;
+                        results.push({
+                            action: "extract",
+                            success: true,
+                            result: extracted.substring(0, 2000),
+                        });
+                        break;
+                    }
+                    case "evaluate": {
+                        if (!act.script)
+                            throw new Error("evaluate requires a script");
+                        const evalRes = await cometClient.safeEvaluate(`
+              (() => {
+                try {
+                  const result = (function() { ${act.script} })();
+                  return JSON.stringify({ ok: true, result: String(result ?? 'undefined').substring(0, 4000) });
+                } catch (e) {
+                  return JSON.stringify({ ok: false, error: e.message });
+                }
+              })()
+            `);
+                        const evRes = JSON.parse(evalRes.result.value);
+                        if (!evRes.ok)
+                            throw new Error(evRes.error);
+                        results.push({ action: "evaluate", success: true, result: evRes.result });
+                        break;
+                    }
+                    default:
+                        throw new Error(`Unknown action: ${act.action}`);
+                }
+                await new Promise((r) => setTimeout(r, 100));
+            }
+            catch (err) {
+                const errorMsg = err instanceof Error ? err.message : String(err);
+                results.push({ action: act.action, success: false, error: errorMsg });
+                if (!act.optional) {
+                    results.push({
+                        action: "ABORTED",
+                        success: false,
+                        error: `Stopped after ${act.action} failed`,
+                    });
+                    break;
+                }
+            }
+        }
+        const allSucceeded = results.every((r) => r.success);
+        return { results, allSucceeded };
+    });
+    if (result !== null) {
+        if (result && "error" in result)
+            errorJson(res, result.error, 400);
+        else if (result)
+            json(res, result);
+    }
+}
+async function handleReadPage(res, params) {
+    const result = await withMutex(res, async () => {
+        const args = paramsToRecord(params);
+        const binding = await requireHttpBinding(res, args);
+        if (!binding)
+            return null;
+        const mode = params.get("mode") || "text";
+        const maxDepth = parseInt(params.get("maxDepth") || "5", 10);
+        const maxLength = parseInt(params.get("maxLength") || "12000", 10);
+        const parts = [];
+        if (mode === "tree" || mode === "both") {
+            const tree = await cometClient.getAccessibilityTree(maxDepth, maxLength);
+            parts.push("## Accessibility Tree\n" + tree);
+        }
+        if (mode === "text" || mode === "both") {
+            const text = await cometClient.getPageText(maxLength);
+            parts.push("## Page Text\n" + text);
+        }
+        if (parts.length === 0) {
+            return { error: `Invalid mode: ${mode}. Use: text, tree, or both` };
+        }
+        return { mode, content: parts.join("\n\n") };
+    });
+    if (result !== null) {
+        if (result && "error" in result)
+            errorJson(res, result.error, 400);
+        else if (result)
+            json(res, result);
+    }
+}
+async function handleShortcut(res, body) {
+    const result = await withMutex(res, async () => {
+        if (requireSession(res))
+            return null;
+        let shortcut = body.shortcut;
+        if (!shortcut || shortcut.trim().length === 0) {
+            return { error: "shortcut is required" };
+        }
+        shortcut = shortcut.replace(/^\//, "");
+        const context = body.context;
+        const timeout = body.timeout || 30000;
+        // Ensure on Perplexity
+        const tabs = await cometClient.listTabsCategorized();
+        if (tabs.main)
+            await cometClient.connect(tabs.main.id);
+        const urlResult = await cometClient.evaluate("window.location.href");
+        const currentUrl = urlResult.result.value;
+        if (!currentUrl?.includes("perplexity.ai")) {
+            await cometClient.navigate("https://www.perplexity.ai/", true);
+            await new Promise((r) => setTimeout(r, 2000));
+        }
+        // Capture old state
+        const oldStateResult = await cometClient.evaluate(`
+      (() => {
+        const proseEls = document.querySelectorAll('[class*="prose"]');
+        const lastProse = proseEls[proseEls.length - 1];
+        return { count: proseEls.length, lastText: lastProse ? lastProse.innerText.substring(0, 100) : '' };
+      })()
+    `);
+        const oldState = oldStateResult.result.value;
+        await cometAI.sendShortcut(shortcut, context);
+        const startTime = Date.now();
+        let sawNewResponse = false;
+        while (Date.now() - startTime < timeout) {
+            await new Promise((r) => setTimeout(r, 2000));
+            const currentStateResult = await cometClient.evaluate(`
+        (() => {
+          const proseEls = document.querySelectorAll('[class*="prose"]');
+          const lastProse = proseEls[proseEls.length - 1];
+          return { count: proseEls.length, lastText: lastProse ? lastProse.innerText.substring(0, 100) : '' };
+        })()
+      `);
+            const currentState = currentStateResult.result.value;
+            if (!sawNewResponse) {
+                if (currentState.count > oldState.count ||
+                    (currentState.lastText && currentState.lastText !== oldState.lastText)) {
+                    sawNewResponse = true;
+                }
+            }
+            const status = await cometAI.getAgentStatus();
+            if (status.status === "completed" && sawNewResponse) {
+                return {
+                    status: "completed",
+                    response: status.response || "Shortcut completed (no response text extracted)",
+                };
+            }
+        }
+        const finalStatus = await cometAI.getAgentStatus();
+        return {
+            status: "in_progress",
+            currentStep: finalStatus.currentStep || null,
+            message: `Shortcut /${shortcut} in progress (timed out after ${timeout}ms). Use GET /api/poll to check progress.`,
+        };
+    });
+    if (result !== null) {
+        if (result && "error" in result)
+            errorJson(res, result.error, 400);
+        else if (result)
+            json(res, result);
+    }
+}
+async function handleWaitForIdle(res, body) {
+    const result = await withMutex(res, async () => {
+        if (requireSession(res))
+            return null;
+        const idleTime = body.idleTime || 1500;
+        const timeout = body.timeout || 15000;
+        const idleResult = await cometClient.waitForNetworkIdle({ idleTime, timeout });
+        return {
+            idle: idleResult.idle,
+            waitedMs: idleResult.waitedMs,
+            totalRequests: idleResult.totalRequests,
+            totalCompleted: idleResult.totalCompleted,
+            totalFailed: idleResult.totalFailed,
+            pendingRequests: idleResult.pendingRequests,
+        };
+    });
+    if (result !== null) {
+        if (result)
+            json(res, result);
+    }
+}
+// ---- Safe Observation handlers (no session, no mutex) ----
+async function handleObserve(res, params) {
+    const action = params.get("action") || "health";
+    const filters = {
+        group: params.get("group") || undefined,
+        agentId: params.get("agentId") || undefined,
+        urlPattern: params.get("urlPattern") || undefined,
+        thumbnails: params.get("thumbnails") === "true",
+        codexIdentity: (() => {
+            try {
+                return deriveCodexSessionIdentity(identityInputFromArgs(paramsToRecord(params)));
+            }
+            catch {
+                return undefined;
+            }
+        })(),
+    };
+    try {
+        switch (action) {
+            case "health": {
+                const health = await getHealth();
+                json(res, { action: "health", formatted: formatHealth(health), data: health });
+                break;
+            }
+            case "snapshot": {
+                const snapshot = await getSnapshot(filters);
+                json(res, { action: "snapshot", formatted: formatSnapshot(snapshot), data: snapshot });
+                break;
+            }
+            case "status": {
+                const statusText = await getStatus(filters);
+                json(res, { action: "status", formatted: statusText });
+                break;
+            }
+            case "detail": {
+                if (!filters.group) {
+                    errorJson(res, "The 'detail' action requires a 'group' query parameter (tab group name).", 400);
+                    return;
+                }
+                const detailText = await getDetail(filters.group, filters);
+                json(res, { action: "detail", group: filters.group, formatted: detailText });
+                break;
+            }
+            default:
+                errorJson(res, `Unknown observe action: ${action}. Use: health, snapshot, status, or detail.`, 400);
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        errorJson(res, message);
+    }
+}
+async function handlePeek(res, params) {
+    const args = paramsToRecord(params);
+    const targetId = params.get("targetId");
+    const action = params.get("action") || "info";
+    const binding = await requireHttpBinding(res, args);
+    if (!binding)
+        return;
+    if (!targetId) {
+        errorJson(res, "targetId query parameter is required. Use GET /api/observe?action=snapshot to find target IDs.", 400);
+        return;
+    }
+    // Resolve CDP target list (no session, no mutex needed for info)
+    let peekTargets;
+    try {
+        const resp = await fetch(`http://127.0.0.1:9222/json/list`);
+        if (!resp.ok) {
+            errorJson(res, "Cannot connect to CDP on port 9222. Is Comet browser running?", 503);
+            return;
+        }
+        peekTargets = (await resp.json());
+    }
+    catch {
+        errorJson(res, "Cannot reach CDP on port 9222. Is Comet browser running?", 503);
+        return;
+    }
+    const peekTarget = peekTargets.find((t) => t.id === targetId);
+    if (!peekTarget) {
+        errorJson(res, `Target ID '${targetId}' not found. Use GET /api/observe?action=snapshot to list current targets.`, 404);
+        return;
+    }
+    if (action === "info") {
+        json(res, {
+            targetId: peekTarget.id,
+            url: peekTarget.url,
+            title: peekTarget.title,
+            type: peekTarget.type,
+        });
+        return;
+    }
+    // screenshot and read require temporary CDP attachment — use mutex
+    const mutexResult = await withMutex(res, async () => {
+        if (!peekTarget.webSocketDebuggerUrl) {
+            return { error: "Target has no WebSocket debugger URL" };
+        }
+        const peekCDP = await (await import("chrome-remote-interface")).default({
+            target: peekTarget.webSocketDebuggerUrl,
+        });
+        try {
+            if (action === "screenshot") {
+                await peekCDP.Page.enable();
+                const ssResult = (await Promise.race([
+                    peekCDP.Page.captureScreenshot({ format: "png" }),
+                    new Promise((_, reject) => setTimeout(() => reject(new Error("Screenshot timeout (3s)")), 3000)),
+                ]));
+                const outputDir = join(homedir(), ".claude", "comet-browser", "output");
+                mkdirSync(outputDir, { recursive: true });
+                const outputPath = join(outputDir, `peek-${Date.now()}.png`);
+                writeFileSync(outputPath, Buffer.from(ssResult.data, "base64"));
+                return { filePath: outputPath, url: peekTarget.url, title: peekTarget.title };
+            }
+            if (action === "read") {
+                await peekCDP.Runtime.enable();
+                const readResult = await peekCDP.Runtime.evaluate({
+                    expression: `(() => {
+            const title = document.title;
+            const url = window.location.href;
+            const text = document.body?.innerText?.substring(0, 10000) || '';
+            const links = Array.from(document.querySelectorAll('a[href]')).slice(0, 20).map(a => ({ text: a.innerText.trim().substring(0, 50), href: a.href }));
+            return JSON.stringify({ title, url, text, links });
+          })()`,
+                    returnByValue: true,
+                });
+                const pageData = JSON.parse(readResult.result.value);
+                return {
+                    title: pageData.title,
+                    url: pageData.url,
+                    text: pageData.text.substring(0, 5000),
+                    links: pageData.links,
+                };
+            }
+            return { error: `Unknown peek action: ${action}. Use: info, screenshot, or read.` };
+        }
+        finally {
+            try {
+                await peekCDP.close();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    });
+    if (mutexResult !== null) {
+        if (mutexResult && "error" in mutexResult)
+            errorJson(res, mutexResult.error, 400);
+        else if (mutexResult)
+            json(res, mutexResult);
+    }
+}
+// ---- Lifecycle handlers (no session, no mutex, forward to CC-SO) ----
+async function handleLifecycleStart(res, body) {
+    const runId = body.runId;
+    const taskThreadId = body.taskThreadId;
+    if (!runId) {
+        errorJson(res, "runId is required", 400);
+        return;
+    }
+    if (!taskThreadId) {
+        errorJson(res, "taskThreadId is required", 400);
+        return;
+    }
+    let result = "skipped";
+    let warning;
+    try {
+        result = await callLifecycleEndpoint({
+            action: "start",
+            runId,
+            taskThreadId,
+            agentId: body.agentId,
+            route: body.route || "http",
+            deferred: body.deferred,
+        });
+    }
+    catch {
+        warning = "CC-SO unavailable — lifecycle event not persisted";
+    }
+    const binding = await attachRunIdToHttpBinding(runId, body);
+    appendJsonl(OUTBOX_PATH, {
+        ts: Math.floor(Date.now() / 1000),
+        from: "comet-http",
+        to: "orchestration",
+        type: "update",
+        task: runId,
+        thread: taskThreadId,
+        msg: `Lifecycle started: run=${runId}`,
+        lifecycle: { action: "start", runId, status: "started", bindingId: binding?.bindingId ?? null },
+    });
+    json(res, {
+        success: true,
+        runId,
+        result,
+        bindingId: binding?.bindingId ?? null,
+        ...(warning ? { warning } : {}),
+    });
+}
+async function handleLifecycleComplete(res, body) {
+    const runId = body.runId;
+    if (!runId) {
+        errorJson(res, "runId is required", 400);
+        return;
+    }
+    let result = "skipped";
+    let warning;
+    try {
+        result = await callLifecycleEndpoint({ action: "complete", runId });
+    }
+    catch {
+        warning = "CC-SO unavailable — lifecycle event not persisted";
+    }
+    const binding = await windowBindingStore.transitionByRunId(runId, "completed");
+    appendJsonl(OUTBOX_PATH, {
+        ts: Math.floor(Date.now() / 1000),
+        from: "comet-http",
+        to: "orchestration",
+        type: "complete",
+        task: runId,
+        msg: `Lifecycle completed: run=${runId}`,
+        lifecycle: {
+            action: "complete",
+            runId,
+            status: "completed",
+            bindingId: binding?.bindingId ?? null,
+        },
+    });
+    json(res, {
+        success: true,
+        runId,
+        result,
+        bindingId: binding?.bindingId ?? null,
+        ...(warning ? { warning } : {}),
+    });
+}
+async function handleLifecycleAbort(res, body) {
+    const runId = body.runId;
+    if (!runId) {
+        errorJson(res, "runId is required", 400);
+        return;
+    }
+    let result = "skipped";
+    let warning;
+    try {
+        result = await callLifecycleEndpoint({
+            action: "abort",
+            runId,
+            reason: body.reason,
+        });
+    }
+    catch {
+        warning = "CC-SO unavailable — lifecycle event not persisted";
+    }
+    const binding = await windowBindingStore.transitionByRunId(runId, "stale");
+    appendJsonl(OUTBOX_PATH, {
+        ts: Math.floor(Date.now() / 1000),
+        from: "comet-http",
+        to: "orchestration",
+        type: "blocked",
+        task: runId,
+        msg: `Lifecycle aborted: run=${runId}${body.reason ? ` reason=${body.reason}` : ""}`,
+        lifecycle: {
+            action: "abort",
+            runId,
+            status: "aborted",
+            reason: body.reason,
+            bindingId: binding?.bindingId ?? null,
+        },
+    });
+    json(res, {
+        success: true,
+        runId,
+        result,
+        bindingId: binding?.bindingId ?? null,
+        ...(warning ? { warning } : {}),
+    });
+}
+async function handleLifecycleUpdate(res, body) {
+    const runId = body.runId;
+    if (!runId) {
+        errorJson(res, "runId is required", 400);
+        return;
+    }
+    let result = "skipped";
+    let warning;
+    try {
+        result = await callLifecycleEndpoint({
+            action: "update",
+            runId,
+            auditSessionId: body.auditSessionId,
+            tabGroupId: body.tabGroupId,
+            workflowId: body.workflowId,
+            metadata: body.metadata,
+        });
+    }
+    catch {
+        warning = "CC-SO unavailable — lifecycle event not persisted";
+    }
+    json(res, { success: true, runId, result, ...(warning ? { warning } : {}) });
+}
+// ---- Orchestration handlers ----
+async function handleTaskStatus(res, params) {
+    const args = paramsToRecord(params);
+    const binding = await requireHttpBinding(res, args);
+    if (!binding)
+        return;
+    const groupId = typeof args.groupId === "number" ? args.groupId : undefined;
+    const threadId = args.projectThreadId ?? args.threadId;
+    const bindingId = args.bindingId;
+    const sessionKey = args.sessionKey;
+    const runId = args.runId;
+    const manifest = readJsonSafe(MANIFEST_PATH);
+    const sessions = manifest?.sessions || [];
+    const matched = sessions.filter((s) => {
+        const codexBinding = s.codexBinding;
+        if (codexBinding?.bindingId !== binding.bindingId)
+            return false;
+        const checks = [];
+        if (bindingId)
+            checks.push(codexBinding.bindingId === bindingId);
+        if (sessionKey)
+            checks.push(s.sessionKey === sessionKey);
+        if (groupId !== undefined)
+            checks.push(s.tabGroupId === groupId);
+        if (threadId)
+            checks.push(s.taskThreadId === threadId || codexBinding.projectThreadId === threadId);
+        if (runId)
+            checks.push(Array.isArray(codexBinding.runIds) && codexBinding.runIds.includes(runId));
+        return checks.every(Boolean);
+    });
+    if (matched.length === 0) {
+        errorJson(res, `No sessions found for binding-scoped query ${JSON.stringify({ bindingId, sessionKey, projectThreadId: threadId, runId, groupId })}`, 404);
+        return;
+    }
+    const result = matched.map((s) => ({
+        bindingId: s.codexBinding?.bindingId ?? null,
+        sessionKey: s.sessionKey,
+        groupId: s.tabGroupId,
+        threadId: s.taskThreadId,
+        status: s.agent?.status || "unknown",
+        agentId: s.agentId ?? s.agent?.id ?? null,
+        tabs: Array.isArray(s.tabs) ? s.tabs.length : 0,
+        metrics: s.metrics || {},
+        links: s.links || {},
+        lastActivity: s.metrics?.lastActivityAt || null,
+    }));
+    json(res, { sessions: result });
+}
+async function handleDelegate(res, body) {
+    const delegateResult = await withMutex(res, async () => {
+        const threadId = body.threadId;
+        const instruction = body.instruction;
+        if (!threadId || !instruction) {
+            return { error: "threadId and instruction are required" };
+        }
+        const priority = body.priority || "P3";
+        const urls = body.urls || [];
+        const dependsOn = body.dependsOn || [];
+        const agentId = body.agentId || "comet-http";
+        const taskId = `comet-${Date.now()}`;
+        const priorityColors = {
+            P1: "red",
+            P2: "yellow",
+            P3: "blue",
+            P4: "grey",
+        };
+        const color = priorityColors[priority] || "blue";
+        // 1. Write to inbox
+        appendJsonl(INBOX_PATH, {
+            ts: Math.floor(Date.now() / 1000),
+            from: "comet-delegate",
+            to: "comet-browser",
+            task: taskId,
+            type: "instruction",
+            thread: threadId,
+            priority,
+            msg: instruction,
+            browser_task: {
+                thread_id: threadId,
+                group_name: threadId.slice(0, 50),
+                color,
+                priority,
+                urls,
+                depends_on: dependsOn,
+            },
+        });
+        // 2. Start lifecycle (graceful)
+        let lifecycleResult = "skipped";
+        try {
+            lifecycleResult = await callLifecycleEndpoint({
+                action: "start",
+                runId: taskId,
+                taskThreadId: threadId,
+                agentId,
+                route: "http",
+            });
+        }
+        catch {
+            /* CC-SO may not be running */
+        }
+        // 3. Create/reuse the Codex window binding directly (no legacy session-controller dispatch).
+        let currentBinding = null;
+        try {
+            const identity = deriveCodexSessionIdentity(identityInputFromArgs(body));
+            currentBinding = await windowBindingStore.findActiveByIdentity(identity);
+        }
+        catch {
+            currentBinding = null;
+        }
+        const bindingDispatch = await createOrReuseDelegateBinding({
+            ...identityInputFromArgs(body),
+            strict: false,
+            taskId,
+            threadId,
+            agentId,
+            currentBinding,
+            bindingId: body.bindingId,
+            projectThreadId: body.projectThreadId ?? threadId,
+            fallbackAgentId: agentId,
+            fallbackTaskThreadId: threadId,
+            windowId: body.windowId,
+            tabGroupId: body.tabGroupId ?? body.groupId ?? null,
+            targetId: body.targetId,
+        });
+        // 4. Write to outbox
+        appendJsonl(OUTBOX_PATH, {
+            ts: Math.floor(Date.now() / 1000),
+            from: "comet-http",
+            to: "orchestration",
+            type: "update",
+            task: taskId,
+            thread: threadId,
+            msg: `Delegated: ${instruction.slice(0, 100)}`,
+            lifecycle: { action: "start", runId: taskId, status: "dispatched" },
+        });
+        return {
+            taskId,
+            threadId,
+            priority,
+            color,
+            lifecycleResult,
+            bindingId: bindingDispatch.bindingId,
+            windowId: bindingDispatch.windowId,
+            tabGroupId: bindingDispatch.tabGroupId,
+            dispatchStatus: bindingDispatch.dispatchStatus,
+        };
+    });
+    if (delegateResult !== null) {
+        if (delegateResult && "error" in delegateResult)
+            errorJson(res, delegateResult.error, 400);
+        else if (delegateResult)
+            json(res, delegateResult);
+    }
+}
+// ---- Parity tool handlers (require session) ----
+async function handlePdf(res, body) {
+    const result = await withMutex(res, async () => {
+        if (requireSession(res))
+            return null;
+        const pdfUrl = body.url;
+        const pdfName = body.name;
+        const pdfFormat = body.format || "Letter";
+        const pdfLandscape = body.landscape || false;
+        const pdfMargin = body.margin ?? 0.5;
+        const pdfScale = body.scale || 1;
+        const pdfPrintBg = body.printBackground !== false;
+        const pdfHideSelectors = body.hideSelectors;
+        if (pdfUrl) {
+            await cometClient.navigate(pdfUrl, true, true);
+        }
+        if (pdfHideSelectors) {
+            const selectors = pdfHideSelectors.split(",").map((s) => s.trim());
+            for (const sel of selectors) {
+                await cometClient.evaluate(`document.querySelectorAll(${safeSelector(sel)}).forEach(el => el.style.display = 'none')`);
+            }
+        }
+        const paperSizes = {
+            Letter: { width: 8.5, height: 11 },
+            Legal: { width: 8.5, height: 14 },
+            A4: { width: 8.27, height: 11.69 },
+            A3: { width: 11.69, height: 16.54 },
+            Tabloid: { width: 11, height: 17 },
+        };
+        const paper = paperSizes[pdfFormat] || paperSizes.Letter;
+        const cdp = cometClient.protocol;
+        const pdfResult = await cdp.send("Page.printToPDF", {
+            landscape: pdfLandscape,
+            printBackground: pdfPrintBg,
+            scale: pdfScale,
+            paperWidth: paper.width,
+            paperHeight: paper.height,
+            marginTop: pdfMargin,
+            marginBottom: pdfMargin,
+            marginLeft: pdfMargin,
+            marginRight: pdfMargin,
+        });
+        const outputDir = join(homedir(), ".claude", "comet-browser", "output");
+        mkdirSync(outputDir, { recursive: true });
+        const titleResult = await cometClient.evaluate("document.title");
+        const pageTitle = titleResult.result.value || "page";
+        const safeName = pdfName || pageTitle.replace(/[^a-zA-Z0-9-_]/g, "_").substring(0, 60);
+        const outputPath = join(outputDir, `${safeName}-${Date.now()}.pdf`);
+        const pdfBuffer = Buffer.from(pdfResult.data, "base64");
+        writeFileSync(outputPath, pdfBuffer);
+        return {
+            filePath: outputPath,
+            sizeKB: (pdfBuffer.length / 1024).toFixed(1),
+            format: pdfFormat,
+            landscape: pdfLandscape,
+        };
+    });
+    if (result !== null) {
+        if (result)
+            json(res, result);
+    }
+}
+async function handleScrape(res, body) {
+    const result = await withMutex(res, async () => {
+        if (requireSession(res))
+            return null;
+        const scrapeUrl = body.url;
+        const scrapeSelector = body.selector;
+        const scrapeMode = body.mode || "text";
+        const scrapeAttr = body.attr;
+        const scrapeScroll = body.scroll || false;
+        const scrapeWaitFor = body.waitFor;
+        if (scrapeUrl) {
+            await cometClient.navigate(scrapeUrl, true, true);
+        }
+        if (scrapeWaitFor) {
+            const waitStart = Date.now();
+            while (Date.now() - waitStart < 10000) {
+                const found = await cometClient.evaluate(`!!document.querySelector(${safeSelector(scrapeWaitFor)})`);
+                if (found.result.value)
+                    break;
+                await new Promise((r) => setTimeout(r, 300));
+            }
+        }
+        if (scrapeScroll) {
+            await cometClient.evaluate(`
+        (async () => {
+          let totalHeight = 0;
+          const distance = 500;
+          while (totalHeight < document.body.scrollHeight && totalHeight < 50000) {
+            window.scrollBy(0, distance);
+            totalHeight += distance;
+            await new Promise(r => setTimeout(r, 200));
+          }
+          window.scrollTo(0, 0);
+        })()
+      `);
+            await new Promise((r) => setTimeout(r, 500));
+        }
+        const safeSel = safeSelector(scrapeSelector || "body");
+        const safeAttrName = safeSelector(scrapeAttr || "href");
+        let extractionScript;
+        switch (scrapeMode) {
+            case "table":
+                extractionScript = `
+          (() => {
+            const table = document.querySelector(${safeSelector(scrapeSelector || "table")});
+            if (!table) return { error: 'No table found' };
+            const rows = [...table.querySelectorAll('tr')];
+            const headers = [...rows[0]?.querySelectorAll('th, td')].map(c => c.innerText.trim());
+            const data = rows.slice(1).map(row => {
+              const cells = [...row.querySelectorAll('td, th')].map(c => c.innerText.trim());
+              return headers.length ? Object.fromEntries(headers.map((h, i) => [h, cells[i] || ''])) : cells;
+            });
+            return { rows: data.length, headers, data };
+          })()`;
+                break;
+            case "json-ld":
+                extractionScript = `
+          (() => {
+            const scripts = [...document.querySelectorAll('script[type="application/ld+json"]')];
+            const data = scripts.map(s => { try { return JSON.parse(s.textContent); } catch { return null; } }).filter(Boolean);
+            return { count: data.length, data };
+          })()`;
+                break;
+            case "list":
+                extractionScript = `
+          (() => {
+            const sel = ${safeSelector(scrapeSelector || "ul li, ol li")};
+            const items = [...document.querySelectorAll(sel)].map(el => el.innerText.trim());
+            return { count: items.length, items };
+          })()`;
+                break;
+            case "attr":
+                extractionScript = `
+          (() => {
+            const sel = ${safeSel};
+            const attr = ${safeAttrName};
+            const els = [...document.querySelectorAll(sel)];
+            const values = els.map(el => el.getAttribute(attr)).filter(Boolean);
+            return { count: values.length, attribute: attr, values };
+          })()`;
+                break;
+            case "multi":
+                extractionScript = `
+          (() => {
+            const sel = ${safeSelector(scrapeSelector || "p")};
+            const els = [...document.querySelectorAll(sel)];
+            const items = els.map(el => ({ tag: el.tagName, text: el.innerText.trim().substring(0, 500) }));
+            return { count: items.length, items };
+          })()`;
+                break;
+            default: // text
+                extractionScript = `
+          (() => {
+            const sel = ${safeSel};
+            const el = document.querySelector(sel);
+            if (!el) return { error: 'Selector not found: ' + sel };
+            return { tag: el.tagName, text: el.innerText.trim().substring(0, 10000) };
+          })()`;
+        }
+        const scrapeResult = await cometClient.evaluate(extractionScript);
+        return { data: scrapeResult.result.value };
+    });
+    if (result !== null) {
+        if (result)
+            json(res, result);
+    }
+}
+async function handleNetwork(res, body) {
+    const result = await withMutex(res, async () => {
+        if (requireSession(res))
+            return null;
+        const netAction = body.action || "capture";
+        const netUrl = body.url;
+        const netDuration = body.duration || 10000;
+        const netFilter = body.filter;
+        const netResourceType = body.resourceType;
+        const netPattern = body.pattern;
+        const netMockResponse = body.mockResponse;
+        const netMockStatus = body.mockStatus || 200;
+        const netIncludeHeaders = body.includeHeaders || false;
+        // CDP.Client extends EventEmitter at runtime but types don't expose on/once/removeListener
+        const cdp = cometClient.protocol;
+        if (netAction === "block") {
+            if (!netPattern)
+                return { error: "'pattern' is required for block action" };
+            await cdp.send("Network.enable");
+            await cdp.send("Network.setBlockedURLs", { urls: [netPattern] });
+            return {
+                action: "block",
+                pattern: netPattern,
+                message: `Blocking requests matching: ${netPattern}`,
+            };
+        }
+        if (netAction === "intercept") {
+            if (!netPattern)
+                return { error: "'pattern' is required for intercept action" };
+            await cdp.send("Fetch.enable", {
+                patterns: [{ urlPattern: `*${netPattern}*`, requestStage: "Response" }],
+            });
+            const interceptResult = await new Promise((resolve) => {
+                const timeout = setTimeout(() => resolve("No matching request within 30s"), 30000);
+                cdp.once("Fetch.requestPaused", async (params) => {
+                    clearTimeout(timeout);
+                    const body = netMockResponse || '{"mocked":true}';
+                    const headers = [
+                        { name: "Content-Type", value: "application/json" },
+                        { name: "Access-Control-Allow-Origin", value: "*" },
+                    ];
+                    await cdp.send("Fetch.fulfillRequest", {
+                        requestId: params.requestId,
+                        responseCode: netMockStatus,
+                        responseHeaders: headers,
+                        body: Buffer.from(body).toString("base64"),
+                    });
+                    resolve(`Intercepted: ${params.request.url}\nResponded with status ${netMockStatus}`);
+                });
+            });
+            await cdp.send("Fetch.disable");
+            return { action: "intercept", pattern: netPattern, result: interceptResult };
+        }
+        // capture action
+        if (netUrl)
+            await cometClient.navigate(netUrl, true, true);
+        await cdp.send("Network.enable");
+        const captured = [];
+        const responseMap = new Map();
+        const onRequest = (params) => {
+            if (netFilter && !params.request.url.includes(netFilter))
+                return;
+            if (netResourceType && params.type?.toLowerCase() !== netResourceType.toLowerCase())
+                return;
+            captured.push({
+                requestId: params.requestId,
+                method: params.request.method,
+                url: params.request.url,
+                type: params.type,
+                ...(netIncludeHeaders ? { requestHeaders: params.request.headers } : {}),
+            });
+        };
+        const onResponse = (params) => {
+            responseMap.set(params.requestId, {
+                status: params.response.status,
+                mimeType: params.response.mimeType,
+                ...(netIncludeHeaders ? { responseHeaders: params.response.headers } : {}),
+            });
+        };
+        cdp.on("Network.requestWillBeSent", onRequest);
+        cdp.on("Network.responseReceived", onResponse);
+        await new Promise((r) => setTimeout(r, netDuration));
+        cdp.removeListener("Network.requestWillBeSent", onRequest);
+        cdp.removeListener("Network.responseReceived", onResponse);
+        await cdp.send("Network.disable");
+        for (const req of captured) {
+            const resp = responseMap.get(req.requestId);
+            if (resp) {
+                req.status = resp.status;
+                req.mimeType = resp.mimeType;
+                if (resp.responseHeaders)
+                    req.responseHeaders = resp.responseHeaders;
+            }
+            delete req.requestId;
+        }
+        return {
+            action: "capture",
+            summary: `Captured ${captured.length} requests over ${netDuration}ms${netFilter ? ` (filter: ${netFilter})` : ""}`,
+            captured: captured.slice(0, 50),
+            overflow: captured.length > 50 ? captured.length - 50 : 0,
+        };
+    });
+    if (result !== null) {
+        if (result && "error" in result)
+            errorJson(res, result.error, 400);
+        else if (result)
+            json(res, result);
+    }
+}
+async function handleAutomate(res, body) {
+    const result = await withMutex(res, async () => {
+        if (requireSession(res))
+            return null;
+        const autoSteps = body.steps;
+        if (!autoSteps || autoSteps.length === 0) {
+            return { error: "'steps' array is required and must not be empty" };
+        }
+        const variables = {};
+        const results = [];
+        function isValidIdentifier(name) {
+            return /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name);
+        }
+        function isSafeConditionExpression(expression) {
+            if (typeof expression !== "string" || expression.length === 0 || expression.length > 200)
+                return false;
+            if (/[;{}\\`]/.test(expression))
+                return false;
+            if (/\b(?:function|new|this|window|document|globalThis|constructor|__proto__|prototype|eval|import|return)\b/.test(expression)) {
+                return false;
+            }
+            return /^[\w\s.$'"!?<>=&|()+\-*/%:[\],]+$/.test(expression);
+        }
+        async function executeStep(step, index) {
+            const prefix = `Step ${index + 1} [${step.tool}]`;
+            try {
+                switch (step.tool) {
+                    case "navigate":
+                        await cometClient.navigate(step.url, true, true);
+                        results.push(`✓ ${prefix}: navigated to ${step.url}`);
+                        break;
+                    case "click":
+                        await cometClient.evaluate(`
+              (() => {
+                const el = document.querySelector(${safeSelector(step.selector)});
+                if (!el) throw new Error('Element not found: ' + ${safeSelector(step.selector)});
+                el.scrollIntoView({ block: 'center' });
+                el.click();
+              })()
+            `);
+                        results.push(`✓ ${prefix}: clicked ${step.selector}`);
+                        break;
+                    case "fill": {
+                        const safeFillVal = JSON.stringify(step.value || "");
+                        await cometClient.evaluate(`
+              (() => {
+                const el = document.querySelector(${safeSelector(step.selector)});
+                if (!el) throw new Error('Element not found: ' + ${safeSelector(step.selector)});
+                const val = ${safeFillVal};
+                const nativeSet = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value')?.set
+                  || Object.getOwnPropertyDescriptor(window.HTMLTextAreaElement.prototype, 'value')?.set;
+                if (nativeSet) nativeSet.call(el, val);
+                else el.value = val;
+                el.dispatchEvent(new Event('input', { bubbles: true }));
+                el.dispatchEvent(new Event('change', { bubbles: true }));
+              })()
+            `);
+                        results.push(`✓ ${prefix}: filled ${step.selector}`);
+                        break;
+                    }
+                    case "type":
+                        for (const char of step.value || "") {
+                            await cometClient.protocol.send("Input.dispatchKeyEvent", {
+                                type: "keyDown",
+                                text: char,
+                            });
+                            await cometClient.protocol.send("Input.dispatchKeyEvent", {
+                                type: "keyUp",
+                                text: char,
+                            });
+                        }
+                        results.push(`✓ ${prefix}: typed ${(step.value || "").length} chars`);
+                        break;
+                    case "press":
+                        await cometClient.protocol.send("Input.dispatchKeyEvent", {
+                            type: "keyDown",
+                            key: step.value,
+                            code: `Key${step.value?.toUpperCase()}`,
+                        });
+                        await cometClient.protocol.send("Input.dispatchKeyEvent", {
+                            type: "keyUp",
+                            key: step.value,
+                            code: `Key${step.value?.toUpperCase()}`,
+                        });
+                        results.push(`✓ ${prefix}: pressed ${step.value}`);
+                        break;
+                    case "select":
+                        await cometClient.evaluate(`
+              (() => {
+                const el = document.querySelector(${safeSelector(step.selector)});
+                if (!el) throw new Error('Element not found');
+                el.value = ${JSON.stringify(step.value || "")};
+                el.dispatchEvent(new Event('change', { bubbles: true }));
+              })()
+            `);
+                        results.push(`✓ ${prefix}: selected ${step.value}`);
+                        break;
+                    case "wait":
+                        if (step.selector) {
+                            const waitMs = Date.now();
+                            while (Date.now() - waitMs < 10000) {
+                                const found = await cometClient.evaluate(`!!document.querySelector(${safeSelector(step.selector)})`);
+                                if (found.result.value)
+                                    break;
+                                await new Promise((r) => setTimeout(r, 300));
+                            }
+                        }
+                        else if (step.value) {
+                            await new Promise((r) => setTimeout(r, parseInt(step.value)));
+                        }
+                        results.push(`✓ ${prefix}: waited for ${step.selector || step.value + "ms"}`);
+                        break;
+                    case "screenshot": {
+                        const ssResult = await cometClient.protocol.send("Page.captureScreenshot", {
+                            format: "png",
+                        });
+                        const ssDir = join(homedir(), ".claude", "comet-browser", "output");
+                        mkdirSync(ssDir, { recursive: true });
+                        const ssPath = join(ssDir, `${step.name || "step-" + (index + 1)}-${Date.now()}.png`);
+                        writeFileSync(ssPath, Buffer.from(ssResult.data, "base64"));
+                        results.push(`✓ ${prefix}: screenshot → ${ssPath}`);
+                        break;
+                    }
+                    case "extract": {
+                        const extractResult = await cometClient.evaluate(`
+              (() => {
+                const el = document.querySelector(${safeSelector(step.selector)});
+                if (!el) return null;
+                return el.innerText?.trim() || el.value || '';
+              })()
+            `);
+                        const extractedValue = extractResult.result.value;
+                        if (step.variable && isValidIdentifier(step.variable))
+                            variables[step.variable] = extractedValue;
+                        results.push(`✓ ${prefix}: extracted ${String(extractedValue).substring(0, 100)}${step.variable ? ` → $${step.variable}` : ""}`);
+                        break;
+                    }
+                    case "assert": {
+                        const assertResult = await cometClient.evaluate(`document.querySelector(${safeSelector(step.selector)})?.innerText || ''`);
+                        const assertText = assertResult.result.value;
+                        if (step.contains && !assertText.includes(step.contains)) {
+                            throw new Error(`Assertion failed: "${step.selector}" does not contain "${step.contains}". Got: "${assertText.substring(0, 200)}"`);
+                        }
+                        results.push(`✓ ${prefix}: assertion passed`);
+                        break;
+                    }
+                    case "evaluate": {
+                        const evalResult = await cometClient.evaluate(step.expression);
+                        const evalValue = evalResult.result.value;
+                        if (step.variable && isValidIdentifier(step.variable))
+                            variables[step.variable] = evalValue;
+                        results.push(`✓ ${prefix}: ${JSON.stringify(evalValue).substring(0, 200)}${step.variable ? ` → $${step.variable}` : ""}`);
+                        break;
+                    }
+                    case "if": {
+                        if (!isSafeConditionExpression(step.condition)) {
+                            throw new Error("Unsafe condition expression in if step");
+                        }
+                        const varInjection = Object.entries(variables)
+                            .filter(([k]) => isValidIdentifier(k))
+                            .map(([k, v]) => `const ${k} = ${JSON.stringify(v)};`)
+                            .join(" ");
+                        const condEvalResult = await cometClient.evaluate(`(() => { ${varInjection} return !!(${step.condition}); })()`);
+                        const condResult = condEvalResult.result.value;
+                        if (condResult && step.then) {
+                            for (let i = 0; i < step.then.length; i++) {
+                                const ok = await executeStep(step.then[i], i);
+                                if (!ok)
+                                    return false;
+                            }
+                        }
+                        results.push(`✓ ${prefix}: condition ${condResult ? "true" : "false"}`);
+                        break;
+                    }
+                    case "loop": {
+                        const loopItems = variables[step.items];
+                        if (!Array.isArray(loopItems))
+                            throw new Error(`Variable "${step.items}" is not an array`);
+                        for (let li = 0; li < loopItems.length; li++) {
+                            variables["_item"] = loopItems[li];
+                            variables["_index"] = li;
+                            for (let si = 0; si < (step.each || []).length; si++) {
+                                const ok = await executeStep(step.each[si], si);
+                                if (!ok)
+                                    return false;
+                            }
+                        }
+                        results.push(`✓ ${prefix}: looped ${loopItems.length} items`);
+                        break;
+                    }
+                    default:
+                        throw new Error(`Unknown step tool: ${step.tool}`);
+                }
+                await new Promise((r) => setTimeout(r, 100));
+                return true;
+            }
+            catch (err) {
+                const errMsg = err instanceof Error ? err.message : String(err);
+                results.push(`✗ ${prefix}: ${errMsg}`);
+                if (step.optional)
+                    return true;
+                return false;
+            }
+        }
+        let aborted = false;
+        for (let i = 0; i < autoSteps.length; i++) {
+            const ok = await executeStep(autoSteps[i], i);
+            if (!ok) {
+                results.push(`\n⚠ Workflow aborted at step ${i + 1}`);
+                aborted = true;
+                break;
+            }
+        }
+        const publicVars = Object.fromEntries(Object.entries(variables).filter(([k]) => !k.startsWith("_")));
+        return {
+            stepsTotal: autoSteps.length,
+            stepsCompleted: results.filter((r) => r.startsWith("✓")).length,
+            results,
+            variables: publicVars,
+            aborted,
+        };
+    });
+    if (result !== null) {
+        if (result && "error" in result)
+            errorJson(res, result.error, 400);
+        else if (result)
+            json(res, result);
+    }
+}
+async function handleDomain(res, body) {
+    const result = await withMutex(res, async () => {
+        if (requireSession(res))
+            return null;
+        const domainName = body.domain;
+        const domainAction = body.action || "check-auth";
+        const domainPath = body.path;
+        if (!domainName) {
+            return { error: "domain is required. Use: qbo, mercury, github, google, salt" };
+        }
+        const domainConfigs = {
+            qbo: {
+                home: "https://app.qbo.intuit.com/app/homepage",
+                authCheck: "app.qbo.intuit.com",
+                name: "QuickBooks Online",
+            },
+            mercury: {
+                home: "https://app.mercury.com/dashboard",
+                authCheck: "app.mercury.com",
+                name: "Mercury Banking",
+            },
+            github: { home: "https://github.com", authCheck: "github.com", name: "GitHub" },
+            google: {
+                home: "https://drive.google.com",
+                authCheck: "accounts.google.com/SignOut",
+                name: "Google Workspace",
+            },
+            salt: { home: "https://app.salt.dev", authCheck: "app.salt.dev", name: "SALT Tax" },
+        };
+        const domainConfig = domainConfigs[domainName];
+        if (!domainConfig) {
+            return { error: `Unknown domain: ${domainName}. Use: qbo, mercury, github, google, salt` };
+        }
+        if (domainAction === "navigate" || domainAction === "status") {
+            const targetUrl = domainPath
+                ? new URL(domainPath, domainConfig.home).href
+                : domainConfig.home;
+            await cometClient.navigate(targetUrl, true, true);
+            const finalUrlResult = await cometClient.evaluate("window.location.href");
+            const finalUrl = finalUrlResult.result.value;
+            const titleResult = await cometClient.evaluate("document.title");
+            const title = titleResult.result.value;
+            const isLoginPage = finalUrl.includes("login") ||
+                finalUrl.includes("signin") ||
+                finalUrl.includes("auth") ||
+                finalUrl.includes("accounts.google.com/v3/signin");
+            return {
+                domain: domainName,
+                name: domainConfig.name,
+                action: domainAction,
+                url: finalUrl,
+                title,
+                authenticated: !isLoginPage,
+            };
+        }
+        // check-auth: check current URL, navigate to verify if not on domain
+        const currentUrlResult = await cometClient.evaluate("window.location.href");
+        const currentUrl = currentUrlResult.result.value;
+        const isOnDomain = currentUrl.includes(domainConfig.authCheck);
+        if (!isOnDomain) {
+            await cometClient.navigate(domainConfig.home, true, true);
+            const checkUrlResult = await cometClient.evaluate("window.location.href");
+            const checkUrl = checkUrlResult.result.value;
+            const isLoginRedirect = checkUrl.includes("login") || checkUrl.includes("signin") || checkUrl.includes("auth");
+            return {
+                domain: domainName,
+                name: domainConfig.name,
+                action: "check-auth",
+                url: checkUrl,
+                authenticated: !isLoginRedirect,
+            };
+        }
+        return {
+            domain: domainName,
+            name: domainConfig.name,
+            action: "check-auth",
+            url: currentUrl,
+            authenticated: true,
+        };
+    });
+    if (result !== null) {
+        if (result && "error" in result)
+            errorJson(res, result.error, 400);
+        else if (result)
+            json(res, result);
+    }
+}
 // ---- Tab Group route handlers ----
 async function handleTabGroupsList(res) {
     const result = await withMutex(res, async () => {
@@ -322,6 +2253,13 @@ async function handleTabGroupsListTabs(res) {
     if (result)
         json(res, result);
 }
+async function handleTabGroupsMetadataList(res) {
+    const result = await withMutex(res, async () => {
+        return await tabGroupsClient.listExtensionMetadata();
+    });
+    if (result)
+        json(res, result);
+}
 async function handleTabGroupsCreate(res, body) {
     const result = await withMutex(res, async () => {
         const tabIds = body.tabIds;
@@ -359,6 +2297,26 @@ async function handleTabGroupsUpdate(res, body) {
             json(res, result);
     }
 }
+async function handleTabGroupsMetadataUpdate(res, body) {
+    const result = await withMutex(res, async () => {
+        return await tabGroupsClient.updateExtensionMetadata({
+            entityType: body.entityType,
+            entityId: body.entityId,
+            windowId: body.windowId,
+            activeWindowId: body.activeWindowId,
+            taskThreadId: body.taskThreadId,
+            tabIndex: body.tabIndex,
+            sourceFamily: body.sourceFamily,
+            policyTier: body.policyTier,
+            description: body.description,
+            title: body.title,
+            label: body.label,
+            status: body.status,
+        });
+    });
+    if (result)
+        json(res, result);
+}
 async function handleTabGroupsDelete(res, body) {
     const result = await withMutex(res, async () => {
         const groupId = body.groupId;
@@ -378,6 +2336,37 @@ async function handleTabGroupsDelete(res, body) {
             json(res, result);
     }
 }
+/// Spec 037: Session lookup endpoint — returns manifest entry for a taskThreadId
+function handleSessionLookup(res, taskThreadId) {
+    if (!taskThreadId) {
+        errorJson(res, "taskThreadId is required", 400);
+        return;
+    }
+    try {
+        const manifestPath = join(homedir(), ".claude", "comet-browser", "session-manifest.json");
+        const data = readFileSync(manifestPath, "utf-8");
+        const manifest = JSON.parse(data);
+        const entry = (manifest.sessions || []).find((e) => e.taskThreadId === taskThreadId);
+        if (entry) {
+            json(res, entry);
+        }
+        else {
+            errorJson(res, `No session found for taskThreadId: ${taskThreadId}`, 404);
+        }
+    }
+    catch {
+        errorJson(res, "Session manifest not available", 404);
+    }
+}
+// T110b: Agent registry endpoint — sync file read, no mutex needed
+function handleAgents(res) {
+    const registry = readAgentRegistry();
+    const agents = {};
+    for (const [id, entry] of Object.entries(registry)) {
+        agents[id] = classifyAgentStatus(entry);
+    }
+    json(res, { agents });
+}
 // ---- HTTP Server ----
 const server = createServer(async (req, res) => {
     // CORS preflight
@@ -397,20 +2386,28 @@ const server = createServer(async (req, res) => {
             json(res, { status: "ok", port: PORT, timestamp: new Date().toISOString() });
         }
         else if (path === "/api/connect" && req.method === "POST") {
-            await handleConnect(res);
+            const body = await readBody(req);
+            await handleConnect(res, body);
         }
         else if (path === "/api/ask" && req.method === "POST") {
             const body = await readBody(req);
             await handleAsk(res, body);
         }
+        else if (path === "/api/equanaut/router/status" && req.method === "GET") {
+            await handleEquanautRouterStatus(res);
+        }
+        else if (path === "/api/equanaut/router/ask" && req.method === "POST") {
+            const body = await readBody(req);
+            await handleEquanautRouterAsk(res, body);
+        }
         else if (path === "/api/poll" && req.method === "GET") {
-            await handlePoll(res);
+            await handlePoll(res, paramsToRecord(url.searchParams));
         }
         else if (path === "/api/stop" && req.method === "POST") {
             await handleStop(res);
         }
         else if (path === "/api/screenshot" && req.method === "GET") {
-            await handleScreenshot(res);
+            await handleScreenshot(res, paramsToRecord(url.searchParams));
         }
         else if (path === "/api/mode" && req.method === "POST") {
             const body = await readBody(req);
@@ -422,6 +2419,9 @@ const server = createServer(async (req, res) => {
         else if (path === "/api/tab-groups/tabs" && req.method === "GET") {
             await handleTabGroupsListTabs(res);
         }
+        else if (path === "/api/tab-groups/metadata" && req.method === "GET") {
+            await handleTabGroupsMetadataList(res);
+        }
         else if (path === "/api/tab-groups" && req.method === "POST") {
             const body = await readBody(req);
             await handleTabGroupsCreate(res, body);
@@ -430,15 +2430,103 @@ const server = createServer(async (req, res) => {
             const body = await readBody(req);
             await handleTabGroupsUpdate(res, body);
         }
+        else if (path === "/api/tab-groups/metadata/update" && req.method === "POST") {
+            const body = await readBody(req);
+            await handleTabGroupsMetadataUpdate(res, body);
+        }
         else if (path === "/api/tab-groups/delete" && req.method === "POST") {
             const body = await readBody(req);
             await handleTabGroupsDelete(res, body);
         }
+        else if (path === "/api/agents" && req.method === "GET") {
+            handleAgents(res);
+        }
+        else if (path.startsWith("/api/session/") && req.method === "GET") {
+            // Spec 037: Return session manifest entry by taskThreadId
+            const taskThreadId = path.replace("/api/session/", "");
+            handleSessionLookup(res, taskThreadId);
+            // ---- Spec 042: New endpoints ----
+            // Safe observation (no session required)
+        }
+        else if (path === "/api/observe" && req.method === "GET") {
+            await handleObserve(res, url.searchParams);
+        }
+        else if (path === "/api/peek" && req.method === "GET") {
+            await handlePeek(res, url.searchParams);
+            // Lifecycle (no session required)
+        }
+        else if (path === "/api/lifecycle/start" && req.method === "POST") {
+            const body = await readBody(req);
+            await handleLifecycleStart(res, body);
+        }
+        else if (path === "/api/lifecycle/complete" && req.method === "POST") {
+            const body = await readBody(req);
+            await handleLifecycleComplete(res, body);
+        }
+        else if (path === "/api/lifecycle/abort" && req.method === "POST") {
+            const body = await readBody(req);
+            await handleLifecycleAbort(res, body);
+        }
+        else if (path === "/api/lifecycle/update" && req.method === "POST") {
+            const body = await readBody(req);
+            await handleLifecycleUpdate(res, body);
+            // Orchestration
+        }
+        else if (path === "/api/task-status" && req.method === "GET") {
+            await handleTaskStatus(res, url.searchParams);
+        }
+        else if (path === "/api/delegate" && req.method === "POST") {
+            const body = await readBody(req);
+            await handleDelegate(res, body);
+            // Navigation & interaction (require session)
+        }
+        else if (path === "/api/navigate" && req.method === "POST") {
+            const body = await readBody(req);
+            await handleNavigate(res, body);
+        }
+        else if (path === "/api/interact" && req.method === "POST") {
+            const body = await readBody(req);
+            await handleInteract(res, body);
+        }
+        else if (path === "/api/read-page" && req.method === "GET") {
+            await handleReadPage(res, url.searchParams);
+        }
+        else if (path === "/api/shortcut" && req.method === "POST") {
+            const body = await readBody(req);
+            await handleShortcut(res, body);
+        }
+        else if (path === "/api/wait-for-idle" && req.method === "POST") {
+            const body = await readBody(req);
+            await handleWaitForIdle(res, body);
+            // Parity tools (require session)
+        }
+        else if (path === "/api/pdf" && req.method === "POST") {
+            const body = await readBody(req);
+            await handlePdf(res, body);
+        }
+        else if (path === "/api/scrape" && req.method === "POST") {
+            const body = await readBody(req);
+            await handleScrape(res, body);
+        }
+        else if (path === "/api/network" && req.method === "POST") {
+            const body = await readBody(req);
+            await handleNetwork(res, body);
+        }
+        else if (path === "/api/automate" && req.method === "POST") {
+            const body = await readBody(req);
+            await handleAutomate(res, body);
+        }
+        else if (path === "/api/domain" && req.method === "POST") {
+            const body = await readBody(req);
+            await handleDomain(res, body);
+        }
         else {
             errorJson(res, `Not found: ${req.method} ${path}`, 404);
         }
     }
     catch (err) {
+        if (writeBoundError(res, err))
+            return;
         const message = err instanceof Error ? err.message : String(err);
         console.error(`[${new Date().toISOString()}] Error on ${req.method} ${path}:`, message);
         errorJson(res, message, 500);
@@ -447,17 +2535,70 @@ const server = createServer(async (req, res) => {
 server.listen(PORT, () => {
     console.log(`Comet Bridge HTTP API listening on port ${PORT}`);
     console.log(`Health check: http://localhost:${PORT}/api/health`);
-    console.log(`\nEndpoints:`);
-    console.log(`  POST /api/connect     - Start Comet & connect`);
-    console.log(`  POST /api/ask         - Send prompt {prompt, newChat?, timeout?}`);
-    console.log(`  GET  /api/poll        - Check agent status`);
-    console.log(`  POST /api/stop        - Stop current agent`);
-    console.log(`  GET  /api/screenshot  - Capture page screenshot`);
-    console.log(`  POST /api/mode        - Get/set Perplexity mode {mode?}`);
+    console.log(`\nEndpoints (31 total):`);
+    console.log(`\n  --- Connection & Querying ---`);
+    console.log(`  POST /api/connect          - Start Comet & connect {taskGoal?}`);
+    console.log(`  POST /api/ask              - Send prompt {prompt, newChat?, timeout?}`);
+    console.log(`  GET  /api/equanaut/router/status - Probe Equanaut router capabilities`);
+    console.log(`  POST /api/equanaut/router/ask - Route sidepanel envelope through gateway`);
+    console.log(`  GET  /api/poll             - Check agent status`);
+    console.log(`  POST /api/stop             - Stop current agent`);
+    console.log(`  GET  /api/screenshot       - Capture page screenshot`);
+    console.log(`  POST /api/mode             - Get/set Perplexity mode {mode?}`);
+    console.log(`  POST /api/shortcut         - Trigger query shortcut {shortcut, context?, timeout?}`);
+    console.log(`\n  --- Navigation & Interaction (require session) ---`);
+    console.log(`  POST /api/navigate         - Navigate to URL {url, waitForIdle?}`);
+    console.log(`  POST /api/interact         - CDP interactions {actions: Action[]}`);
+    console.log(`  GET  /api/read-page        - Read page content ?mode=text|tree|both`);
+    console.log(`  POST /api/wait-for-idle    - Wait for network idle {idleTime?, timeout?}`);
+    console.log(`\n  --- Safe Observation (no session required) ---`);
+    console.log(`  GET  /api/observe          - Browser state ?action=health|snapshot|status|detail`);
+    console.log(`  GET  /api/peek             - Read tab by target ID ?targetId=&action=info|screenshot|read`);
+    console.log(`  GET  /api/agents           - Agent registry snapshot`);
+    console.log(`\n  --- Lifecycle (no session required) ---`);
+    console.log(`  POST /api/lifecycle/start   - Register run {runId, taskThreadId, agentId?, route?}`);
+    console.log(`  POST /api/lifecycle/complete - Complete run {runId}`);
+    console.log(`  POST /api/lifecycle/abort   - Abort run {runId, reason?}`);
+    console.log(`  POST /api/lifecycle/update  - Update run metadata {runId, tabGroupId?, workflowId?}`);
+    console.log(`\n  --- Orchestration ---`);
+    console.log(`  GET  /api/task-status      - Unified task status ?groupId=|threadId=`);
+    console.log(`  POST /api/delegate         - Dispatch browser task {threadId, instruction, priority?}`);
+    console.log(`  GET  /api/session/:id      - Session manifest lookup by taskThreadId`);
+    console.log(`\n  --- Parity Tools (require session) ---`);
+    console.log(`  POST /api/pdf              - Generate PDF {url?, format?, landscape?, ...}`);
+    console.log(`  POST /api/scrape           - Extract structured data {mode?, selector?, ...}`);
+    console.log(`  POST /api/network          - Network traffic {action?, duration?, filter?, ...}`);
+    console.log(`  POST /api/automate         - Multi-step workflow {steps: Step[]}`);
+    console.log(`  POST /api/domain           - Domain playbook {domain, action?, path?}`);
+    console.log(`\n  --- Tab Groups ---`);
     console.log(`  GET  /api/tab-groups       - List all tab groups`);
     console.log(`  GET  /api/tab-groups/tabs  - List all tabs with group info`);
+    console.log(`  GET  /api/tab-groups/metadata - List extension metadata`);
     console.log(`  POST /api/tab-groups       - Create group {tabIds, title?, color?}`);
     console.log(`  POST /api/tab-groups/update - Update group {groupId, title?, color?, collapsed?}`);
+    console.log(`  POST /api/tab-groups/metadata/update - Update extension metadata`);
     console.log(`  POST /api/tab-groups/delete - Delete group {groupId}`);
+    // --- Window-binding TTL reaper (Spec 084) ---
+    // Periodically prune binding records whose Comet window has been gone past the
+    // TTL, so the Session Manager / mirror stop accumulating "Display unknown" phantoms.
+    const reaperConfig = readReaperConfig();
+    const stopReaper = startBindingReaper(reaperConfig, {
+        getLiveWindowIds,
+        archive: archiveBindingForReap,
+        log: (m) => console.log(m),
+    });
+    for (const sig of ["SIGINT", "SIGTERM"]) {
+        process.once(sig, () => {
+            try {
+                stopReaper();
+            }
+            catch {
+                /* ignore */
+            }
+            const exitCode = sig === "SIGINT" ? 130 : 143;
+            server.close(() => process.exit(exitCode));
+            server.closeAllConnections?.();
+        });
+    }
 });
 //# sourceMappingURL=http-server.js.map