aibroker 0.5.1 → 0.6.2

package/dist/adapters/pailot/gateway.js

@@ -13,24 +13,151 @@
 import { WebSocketServer, WebSocket } from "ws";
 import { join } from "node:path";
 import { writeFileSync, readFileSync, existsSync, unlinkSync, appendFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-const DEBUG_LOG = "/tmp/pailot-ws-debug.log";
+import { tmpdir, homedir } from "node:os";
+const DEBUG_LOG = process.env.PAILOT_DEBUG ? "/tmp/pailot-ws-debug.log" : null;
 function dbg(msg) {
-    appendFileSync(DEBUG_LOG, `[${new Date().toISOString()}] ${msg}\n`);
+    if (DEBUG_LOG)
+        appendFileSync(DEBUG_LOG, `[${new Date().toISOString()}] ${msg}\n`);
 }
 import { randomUUID } from "node:crypto";
 import { promisify } from "node:util";
 import { execFile } from "node:child_process";
 import { log } from "../../core/log.js";
 import { WHISPER_BIN, WHISPER_MODEL } from "../kokoro/media.js";
-import { setMessageSource, activeItermSessionId, setActiveItermSessionId, } from "../../core/state.js";
-import { setItermSessionVar, setItermTabName } from "../iterm/sessions.js";
+import { setMessageSource, activeItermSessionId, setActiveItermSessionId, lastRoutedSessionId, setLastRoutedSessionId, getAibpBridge, } from "../../core/state.js";
+import { setItermSessionVar, setItermTabName, setItermBadge, killSession, createClaudeSession } from "../iterm/sessions.js";
+import { listPaiProjects, launchPaiProject } from "../../daemon/pai-projects.js";
 import { runAppleScript, sendKeystrokeToSession, sendEscapeSequenceToSession, pasteTextIntoSession, snapshotAllSessions } from "../iterm/core.js";
 import { hybridManager } from "../../core/hybrid.js";
 const WS_PORT = parseInt(process.env.PAILOT_PORT ?? "8765", 10);
 // --- State ---
 let wss = null;
 const clients = new Set();
+/** Maps PAILot session ID → iTerm session ID for explicit reply routing.
+ *  When PAILot sends a message tagged with sessionId, we record it here so
+ *  outbound replies go back tagged with the same sessionId — regardless of
+ *  which iTerm tab happens to be focused on the Mac at response time.
+ */
+const pailotReplyMap = new Map();
+/** Track which session each WebSocket client is currently viewing.
+ *  Messages tagged with a different sessionId are NOT delivered to that client.
+ *  This prevents cross-session content bleed in multi-session PAILot views.
+ */
+const clientActiveSession = new Map();
+/** Track when each client last proved it's alive (pong, message, or connect). */
+const clientLastActive = new Map();
+/** Consider a client "alive" if it responded within this window. */
+const CLIENT_ALIVE_THRESHOLD = 90_000; // 90s (3x the 30s heartbeat)
+// --- Per-session message outbox for offline/backgrounded clients ---
+// Buffers messages when no live client can receive them.
+// Stored per-session so drain delivers to the correct session.
+const MAX_OUTBOX_PER_SESSION = 50;
+const OUTBOX_DIR = join(homedir(), ".aibroker", "outbox");
+const outboxMap = new Map(); // sessionId → entries
+let missedImageCount = 0;
+function addToOutbox(msg) {
+    const type = msg.type;
+    if (type === "typing")
+        return;
+    if (type === "image") {
+        missedImageCount++;
+        return;
+    }
+    const sessionId = msg.sessionId || "_global";
+    let queue = outboxMap.get(sessionId);
+    if (!queue) {
+        queue = [];
+        outboxMap.set(sessionId, queue);
+    }
+    queue.push({ msg, timestamp: Date.now() });
+    if (queue.length > MAX_OUTBOX_PER_SESSION)
+        queue.shift();
+    // Persist to disk (best-effort, async)
+    persistOutbox();
+}
+function drainOutbox(ws) {
+    // Collect all entries across all sessions
+    let totalEntries = 0;
+    let textCount = 0;
+    let voiceCount = 0;
+    for (const entries of outboxMap.values()) {
+        totalEntries += entries.length;
+        for (const e of entries) {
+            const t = e.msg.type;
+            if (t === "text")
+                textCount++;
+            else if (t === "voice")
+                voiceCount++;
+        }
+    }
+    if (totalEntries === 0 && missedImageCount === 0)
+        return;
+    const otherCount = totalEntries - textCount - voiceCount;
+    const parts = [];
+    if (textCount > 0)
+        parts.push(`${textCount} text message(s)`);
+    if (voiceCount > 0)
+        parts.push(`${voiceCount} voice note(s)`);
+    if (missedImageCount > 0)
+        parts.push(`${missedImageCount} image(s)`);
+    if (otherCount > 0)
+        parts.push(`${otherCount} other`);
+    sendTo(ws, {
+        type: "text",
+        content: `📬 While you were away: ${parts.join(", ")}`,
+    });
+    // Replay all buffered messages (sorted by timestamp across sessions)
+    const allEntries = [];
+    for (const entries of outboxMap.values())
+        allEntries.push(...entries);
+    allEntries.sort((a, b) => a.timestamp - b.timestamp);
+    for (const entry of allEntries) {
+        sendTo(ws, entry.msg);
+    }
+    // Clear outbox
+    outboxMap.clear();
+    missedImageCount = 0;
+    persistOutbox();
+}
+/** Persist outbox to disk so daemon restarts don't lose messages. */
+function persistOutbox() {
+    try {
+        const { mkdirSync, writeFileSync: writeSync } = require("node:fs");
+        mkdirSync(OUTBOX_DIR, { recursive: true });
+        const data = {};
+        for (const [k, v] of outboxMap)
+            data[k] = v;
+        writeSync(join(OUTBOX_DIR, "pending.json"), JSON.stringify({ messages: data, missedImageCount }));
+    }
+    catch { /* best-effort */ }
+}
+/** Restore outbox from disk on startup. */
+function restoreOutbox() {
+    try {
+        const path = join(OUTBOX_DIR, "pending.json");
+        if (!existsSync(path))
+            return;
+        const raw = readFileSync(path, "utf-8");
+        const data = JSON.parse(raw);
+        if (data.messages) {
+            for (const [k, v] of Object.entries(data.messages)) {
+                outboxMap.set(k, v);
+            }
+        }
+        if (data.missedImageCount)
+            missedImageCount = data.missedImageCount;
+        log(`[PAILot] Restored ${outboxMap.size} outbox queue(s) from disk`);
+        // Clean up the file after restoring
+        unlinkSync(path);
+    }
+    catch { /* ignore */ }
+}
+function isClientAlive(ws) {
+    if (ws.readyState !== WebSocket.OPEN)
+        return false;
+    const lastActive = clientLastActive.get(ws) ?? 0;
+    return (Date.now() - lastActive) < CLIENT_ALIVE_THRESHOLD;
+}
 // Reference to the screenshot handler — set via setScreenshotHandler()
 // to avoid circular imports (screenshot.ts imports from state.ts which
 // would create a cycle if we imported it here directly).
@@ -43,13 +170,82 @@ export function setScreenshotHandler(handler) {
     screenshotHandler = handler;
 }
 // --- Structured command handling ---
-/** Detect which iTerm2 session is currently focused and sync the hybrid manager to it. */
-function handleSyncCommand(ws) {
+/**
+ * Filter: include only Claude-related sessions.
+ * A session qualifies if it has paiName, name contains "claude",
+ * or is not at shell prompt (has a process running — likely Claude).
+ */
+function isClaudeRelated(snap) {
+    if (snap.paiName)
+        return true;
+    const name = (snap.tabTitle ?? snap.name).toLowerCase();
+    if (name.includes("claude"))
+        return true;
+    if (!snap.atPrompt)
+        return true;
+    return false;
+}
+/** Detect which iTerm2 session is currently focused and sync the hybrid manager to it.
+ *  If the client passes activeSessionId, preserve that selection instead of
+ *  jumping to whatever iTerm has focused on the Mac.
+ */
+function handleSyncCommand(ws, args) {
     if (!hybridManager) {
         handleSessionsCommand(ws);
+        drainOutbox(ws);
         return;
     }
-    // Ask iTerm2 which session is focused right now
+    const clientActiveId = typeof args?.activeSessionId === "string" ? args.activeSessionId : undefined;
+    // Auto-discover Claude-related iTerm2 tabs so freshly-started daemons can match
+    const liveSnapshots = snapshotAllSessions();
+    const liveIds = new Set(liveSnapshots.map(s => s.id));
+    hybridManager.pruneDeadVisualSessions(liveIds);
+    const knownIds = new Set(hybridManager.listSessions().map(s => s.backendSessionId));
+    const seenTabs = new Set();
+    for (const snap of liveSnapshots) {
+        if (!isClaudeRelated(snap))
+            continue;
+        const displayName = snap.tabTitle ?? snap.paiName ?? snap.name;
+        if (seenTabs.has(displayName))
+            continue;
+        seenTabs.add(displayName);
+        if (!knownIds.has(snap.id)) {
+            hybridManager.registerVisualSession(displayName, "", snap.id);
+        }
+    }
+    // If the client had a session open, try to restore it
+    if (clientActiveId) {
+        // First pass: check if it was already registered (by auto-discovery above or a prior sync)
+        let sessions = hybridManager.listSessions();
+        let idx = sessions.findIndex(s => s.backendSessionId === clientActiveId);
+        // Second pass: the session may exist in liveSnapshots but wasn't registered because
+        // isClaudeRelated() returned false (e.g. session is at a shell prompt between Claude runs
+        // after a daemon restart). Since the client explicitly asked for this session by ID, register
+        // it unconditionally if it is still alive in iTerm.
+        if (idx < 0 && liveIds.has(clientActiveId)) {
+            const snap = liveSnapshots.find(s => s.id === clientActiveId);
+            if (snap) {
+                const displayName = snap.tabTitle ?? snap.paiName ?? snap.name;
+                hybridManager.registerVisualSession(displayName, "", clientActiveId);
+                sessions = hybridManager.listSessions();
+                idx = sessions.findIndex(s => s.backendSessionId === clientActiveId);
+                log(`[PAILot] sync: force-registered client session "${displayName}" (${clientActiveId.slice(0, 8)}...)`);
+            }
+        }
+        if (idx >= 0) {
+            hybridManager.switchToIndex(idx + 1);
+            setActiveItermSessionId(clientActiveId);
+            setLastRoutedSessionId(clientActiveId);
+            clientActiveSession.set(ws, clientActiveId);
+            log(`[PAILot] sync: restored client session "${sessions[idx].name}" (${clientActiveId.slice(0, 8)}...)`);
+            handleSessionsCommand(ws);
+            drainOutbox(ws);
+            return;
+        }
+        // Client's session no longer exists in iTerm — fall through to iTerm focus
+        log(`[PAILot] sync: client session ${clientActiveId.slice(0, 8)}... not found in live iTerm — falling back to focused session`);
+    }
+    // No client preference (or client's session is gone) — ask iTerm2 which session is focused
     const focusedId = runAppleScript(`tell application "iTerm2"
   try
     return id of current session of current tab of current window
@@ -58,20 +254,45 @@ function handleSyncCommand(ws) {
   end try
 end tell`)?.trim() ?? "";
     if (focusedId) {
-        // Find this session in the hybrid manager and activate it
-        const sessions = hybridManager.listSessions();
-        const idx = sessions.findIndex(s => s.backendSessionId === focusedId);
+        // Find this session in the hybrid manager and activate it.
+        // If it wasn't registered by the Claude-related filter, register it now since the
+        // user is actively looking at it.
+        let sessions = hybridManager.listSessions();
+        let idx = sessions.findIndex(s => s.backendSessionId === focusedId);
+        if (idx < 0 && liveIds.has(focusedId)) {
+            const snap = liveSnapshots.find(s => s.id === focusedId);
+            if (snap) {
+                const displayName = snap.tabTitle ?? snap.paiName ?? snap.name;
+                hybridManager.registerVisualSession(displayName, "", focusedId);
+                sessions = hybridManager.listSessions();
+                idx = sessions.findIndex(s => s.backendSessionId === focusedId);
+            }
+        }
         if (idx >= 0) {
             hybridManager.switchToIndex(idx + 1);
             setActiveItermSessionId(focusedId);
+            setLastRoutedSessionId(focusedId);
+            clientActiveSession.set(ws, focusedId);
             log(`[PAILot] sync: activated focused session "${sessions[idx].name}" (${focusedId.slice(0, 8)}...)`);
         }
         else {
-            log(`[PAILot] sync: focused session ${focusedId.slice(0, 8)}... not registered`);
+            log(`[PAILot] sync: focused session ${focusedId.slice(0, 8)}... not found in live iTerm`);
+        }
+    }
+    // Last resort: if nothing is active yet but we have registered sessions, activate the first one
+    if (!hybridManager.activeSession) {
+        const sessions = hybridManager.listSessions();
+        if (sessions.length > 0) {
+            hybridManager.switchToIndex(1);
+            setActiveItermSessionId(sessions[0].backendSessionId);
+            setLastRoutedSessionId(sessions[0].backendSessionId);
+            clientActiveSession.set(ws, sessions[0].backendSessionId);
+            log(`[PAILot] sync: no focused session found — defaulting to first session "${sessions[0].name}"`);
         }
     }
-    // Return sessions with updated active state
+    // Return sessions with updated active state, then drain buffered messages
     handleSessionsCommand(ws);
+    drainOutbox(ws);
 }
 function handleSessionsCommand(ws) {
     if (!hybridManager) {
@@ -82,12 +303,32 @@ function handleSessionsCommand(ws) {
     const liveSnapshots = snapshotAllSessions();
     const liveIds = new Set(liveSnapshots.map(s => s.id));
     hybridManager.pruneDeadVisualSessions(liveIds);
+    // Auto-discover Claude-related iTerm2 tabs not yet in the hybrid manager,
+    // and sync names of existing sessions from live iTerm state.
+    // Deduplicate by tab title — only register first session per tab.
+    const knownIds = new Set(hybridManager.listSessions().map(s => s.backendSessionId));
+    const seenTabs = new Set();
+    for (const snap of liveSnapshots) {
+        if (!isClaudeRelated(snap))
+            continue;
+        const displayName = snap.tabTitle ?? snap.paiName ?? snap.name;
+        if (seenTabs.has(displayName))
+            continue; // skip split panes in same tab
+        seenTabs.add(displayName);
+        if (!knownIds.has(snap.id)) {
+            hybridManager.registerVisualSession(displayName, "", snap.id);
+        }
+        else {
+            // Sync name from iTerm (handles double-click renames)
+            hybridManager.updateName(snap.id, displayName);
+        }
+    }
     const hybridSessions = hybridManager.listSessions();
     const active = hybridManager.activeSession;
     const sessions = hybridSessions.map((s, i) => ({
         index: i + 1,
         name: s.name,
-        type: s.kind === "visual" ? "claude" : "claude",
+        type: "claude",
         kind: s.kind,
         isActive: active ? s.id === active.id : false,
         id: s.backendSessionId,
@@ -147,8 +388,13 @@ end tell`);
         if (session.kind === "visual") {
             setItermSessionVar(session.backendSessionId, newName);
             setItermTabName(session.backendSessionId, newName);
+            setItermBadge(session.backendSessionId, newName);
         }
     }
+    // Record this as the last routed session so outbound replies go here,
+    // regardless of which iTerm tab is focused on the Mac.
+    setLastRoutedSessionId(session.backendSessionId);
+    clientActiveSession.set(ws, session.backendSessionId);
     sendTo(ws, { type: "session_switched", name: session.name, sessionId: session.backendSessionId });
     log(`[PAILot] switched to ${session.kind} session "${session.name}" (${session.id})`);
 }
@@ -167,11 +413,110 @@ function handleRenameCommand(ws, args) {
         if (session.kind === "visual") {
             setItermSessionVar(sessionId, name);
             setItermTabName(sessionId, name);
+            setItermBadge(sessionId, name);
         }
     }
     sendTo(ws, { type: "session_renamed", sessionId, name });
+    // Send updated sessions list so PAILot refreshes the header
+    handleSessionsCommand(ws);
     log(`[PAILot] renamed session ${sessionId} to "${name}"`);
 }
+function handleRemoveCommand(ws, args) {
+    const sessionId = args.sessionId;
+    if (!sessionId || !hybridManager) {
+        sendTo(ws, { type: "error", message: "Missing sessionId" });
+        return;
+    }
+    // Find session by backendSessionId
+    const sessions = hybridManager.listSessions();
+    const idx = sessions.findIndex(s => s.backendSessionId === sessionId);
+    if (idx < 0) {
+        sendTo(ws, { type: "error", message: "Session not found" });
+        return;
+    }
+    const target = sessions[idx];
+    // Kill the iTerm2 session if it's visual
+    if (target.kind === "visual" && target.backendSessionId) {
+        killSession(target.backendSessionId);
+    }
+    const removed = hybridManager.removeByIndex(idx + 1);
+    if (removed) {
+        log(`[PAILot] removed ${removed.kind} session "${removed.name}" (${removed.id})`);
+    }
+    // Send updated session list
+    handleSessionsCommand(ws);
+}
+function handleCreateCommand(ws, args = {}) {
+    const projectName = args.project;
+    const path = args.path;
+    // PAI project launch — async path
+    if (projectName) {
+        handleCreateFromProject(ws, projectName);
+        return;
+    }
+    // Custom path — cd then claude
+    const command = path ? `cd ${path.replace(/"/g, '\\"')} && claude` : "claude";
+    const name = path ? path.split("/").filter(Boolean).pop() ?? "Claude" : "Claude";
+    const sessionId = createClaudeSession(command);
+    if (!sessionId) {
+        sendTo(ws, { type: "error", message: "Failed to create new session" });
+        return;
+    }
+    setItermSessionVar(sessionId, name);
+    setItermTabName(sessionId, name);
+    setItermBadge(sessionId, name);
+    if (hybridManager) {
+        hybridManager.registerVisualSession(name, "", sessionId);
+        const sessions = hybridManager.listSessions();
+        const idx = sessions.findIndex(s => s.backendSessionId === sessionId);
+        if (idx >= 0) {
+            hybridManager.switchToIndex(idx + 1);
+            setActiveItermSessionId(sessionId);
+            setLastRoutedSessionId(sessionId);
+        }
+    }
+    log(`[PAILot] created new session "${name}" (${sessionId.slice(0, 8)}...)`);
+    sendTo(ws, { type: "session_switched", name, sessionId });
+    handleSessionsCommand(ws);
+}
+async function handleCreateFromProject(ws, projectName) {
+    try {
+        const { itermSessionId } = await launchPaiProject(projectName);
+        const displayName = projectName;
+        if (hybridManager) {
+            hybridManager.registerVisualSession(displayName, "", itermSessionId);
+            const sessions = hybridManager.listSessions();
+            const idx = sessions.findIndex(s => s.backendSessionId === itermSessionId);
+            if (idx >= 0) {
+                hybridManager.switchToIndex(idx + 1);
+                setActiveItermSessionId(itermSessionId);
+            }
+        }
+        log(`[PAILot] launched PAI project "${projectName}" (${itermSessionId.slice(0, 8)}...)`);
+        sendTo(ws, { type: "session_switched", name: displayName, sessionId: itermSessionId });
+        handleSessionsCommand(ws);
+    }
+    catch (err) {
+        log(`[PAILot] project launch failed: ${err}`);
+        sendTo(ws, { type: "error", message: `Failed to launch project: ${err instanceof Error ? err.message : String(err)}` });
+    }
+}
+async function handleProjectsCommand(ws) {
+    try {
+        const projects = await listPaiProjects();
+        const list = projects.map(p => ({
+            name: p.displayName || p.name,
+            slug: p.slug,
+            path: p.rootPath,
+            sessions: p.sessionCount,
+        }));
+        sendTo(ws, { type: "projects", projects: list });
+    }
+    catch (err) {
+        log(`[PAILot] projects list failed: ${err}`);
+        sendTo(ws, { type: "projects", projects: [] });
+    }
+}
 async function handleNavCommand(ws, args) {
     const key = args.key;
     if (!key)
@@ -241,13 +586,30 @@ function sendTo(ws, msg) {
     }
 }
 function broadcast(msg) {
-    if (clients.size === 0)
-        return;
+    // Only deliver to clients that have proven liveness recently.
+    // iOS can keep a WebSocket "open" while the app is backgrounded —
+    // ws.send() succeeds but the app never processes the data.
+    //
+    // Session filtering: if the message carries a sessionId, only deliver to
+    // clients viewing that session. This prevents cross-session content bleed.
+    const msgSessionId = msg.sessionId;
+    let delivered = false;
     const payload = JSON.stringify(msg);
     for (const ws of clients) {
-        if (ws.readyState === WebSocket.OPEN) {
-            ws.send(payload);
+        if (!isClientAlive(ws))
+            continue;
+        // Session gate: if both the message and client have a session, they must match
+        if (msgSessionId) {
+            const clientSession = clientActiveSession.get(ws);
+            if (clientSession && clientSession !== msgSessionId)
+                continue;
         }
+        ws.send(payload);
+        delivered = true;
+    }
+    // No live clients — buffer for later
+    if (!delivered) {
+        addToOutbox(msg);
     }
 }
 // --- Voice message batching ---
@@ -257,16 +619,29 @@ const BATCH_WINDOW_MS = 3000;
 let voiceBatchTimer = null;
 let voiceBatchTranscripts = [];
 let voiceBatchOnMessage = null;
+/** iTerm session ID resolved when the first voice chunk of this batch arrived. */
+let voiceBatchSessionId = "";
 function flushVoiceBatch() {
     if (voiceBatchTranscripts.length === 0)
         return;
     const combined = voiceBatchTranscripts.join(" ");
     const handler = voiceBatchOnMessage;
+    const batchSession = voiceBatchSessionId;
     voiceBatchTranscripts = [];
     voiceBatchOnMessage = null;
+    voiceBatchSessionId = "";
     voiceBatchTimer = null;
-    if (handler) {
-        log(`[PAILot] Flushing voice batch (${combined.length} chars)`);
+    log(`[PAILot] Flushing voice batch (${combined.length} chars)`);
+    const routeSession = batchSession || activeItermSessionId;
+    if (routeSession) {
+        pailotReplyMap.set(routeSession, routeSession);
+        setLastRoutedSessionId(routeSession);
+    }
+    const bridge = getAibpBridge();
+    if (bridge && routeSession) {
+        bridge.routeFromMobile(routeSession, `[PAILot:voice] ${combined}`);
+    }
+    else if (handler) {
         setMessageSource("pailot");
         handler(`[PAILot:voice] ${combined}`, Date.now());
         setMessageSource("whatsapp");
@@ -274,7 +649,7 @@ function flushVoiceBatch() {
 }
 // --- Voice transcription for PAILot ---
 const execFileAsync = promisify(execFile);
-async function transcribeAndRoute(audioBase64, onMessage) {
+async function transcribeAndRoute(audioBase64, onMessage, messageId) {
     const base = `pailot-voice-${Date.now()}-${randomUUID().slice(0, 8)}`;
     const audioFile = join(tmpdir(), `${base}.m4a`);
     const filesToClean = [
@@ -309,6 +684,10 @@ async function transcribeAndRoute(audioBase64, onMessage) {
             return;
         }
         log(`[PAILot] Transcription: ${transcript.slice(0, 80)}${transcript.length > 80 ? "..." : ""}`);
+        // Reflect transcript back to the app so the voice bubble shows text
+        if (messageId) {
+            broadcast({ type: "transcript", messageId, content: transcript });
+        }
         // Batch: accumulate transcripts and reset the timer
         voiceBatchTranscripts.push(transcript);
         voiceBatchOnMessage = onMessage;
@@ -335,18 +714,68 @@ async function transcribeAndRoute(audioBase64, onMessage) {
  */
 export function startWsGateway(onMessage) {
     wss = new WebSocketServer({ port: WS_PORT });
+    // Restore any buffered messages from a previous daemon run
+    restoreOutbox();
     wss.on("listening", () => {
         log(`WebSocket gateway listening on ws://0.0.0.0:${WS_PORT}`);
+        // Pre-populate hybrid manager with live iTerm sessions so messages
+        // can be tagged with sessionId even before a PAILot client connects.
+        if (hybridManager) {
+            try {
+                const liveSnapshots = snapshotAllSessions();
+                const knownIds = new Set(hybridManager.listSessions().map(s => s.backendSessionId));
+                const seenTabs = new Set();
+                for (const snap of liveSnapshots) {
+                    if (!isClaudeRelated(snap))
+                        continue;
+                    const displayName = snap.tabTitle ?? snap.paiName ?? snap.name;
+                    if (seenTabs.has(displayName))
+                        continue;
+                    seenTabs.add(displayName);
+                    if (!knownIds.has(snap.id)) {
+                        hybridManager.registerVisualSession(displayName, "", snap.id);
+                    }
+                }
+                // Also set the active session based on current iTerm focus
+                const focusedId = runAppleScript(`tell application "iTerm2"
+  try
+    return id of current session of current tab of current window
+  on error
+    return ""
+  end try
+end tell`)?.trim() ?? "";
+                if (focusedId) {
+                    const sessions = hybridManager.listSessions();
+                    const idx = sessions.findIndex(s => s.backendSessionId === focusedId);
+                    if (idx >= 0) {
+                        hybridManager.switchToIndex(idx + 1);
+                        setActiveItermSessionId(focusedId);
+                    }
+                }
+                log(`Pre-registered ${hybridManager.listSessions().length} session(s) from live iTerm`);
+            }
+            catch (err) {
+                log(`Failed to pre-register sessions: ${err}`);
+            }
+        }
     });
     wss.on("connection", (ws, req) => {
         const addr = req.socket.remoteAddress ?? "unknown";
         log(`PAILot client connected from ${addr}`);
         clients.add(ws);
+        clientLastActive.set(ws, Date.now());
         ws.on("message", (raw) => {
+            clientLastActive.set(ws, Date.now());
             try {
                 const rawStr = raw.toString();
-                dbg(`RAW msg (${rawStr.length} chars): type=${JSON.parse(rawStr).type}, hasAudio=${!!JSON.parse(rawStr).audioBase64}, content=${(JSON.parse(rawStr).content ?? "").slice(0, 50)}`);
                 const msg = JSON.parse(rawStr);
+                dbg(`RAW msg (${rawStr.length} chars): type=${msg.type}, hasAudio=${!!msg.audioBase64}, content=${(msg.content ?? "").slice(0, 50)}`);
+                // Heartbeat ping — reply with pong immediately.
+                // The clientLastActive update above already covers liveness.
+                if (msg.type === "ping") {
+                    sendTo(ws, { type: "pong" });
+                    return;
+                }
                 // Structured commands from PAILot app
                 if (msg.type === "command") {
                     const command = msg.command;
@@ -357,7 +786,7 @@ export function startWsGateway(onMessage) {
                             handleSessionsCommand(ws);
                             return;
                         case "sync":
-                            handleSyncCommand(ws);
+                            handleSyncCommand(ws, args);
                             return;
                         case "switch":
                             handleSwitchCommand(ws, args);
@@ -365,6 +794,15 @@ export function startWsGateway(onMessage) {
                         case "rename":
                             handleRenameCommand(ws, args);
                             return;
+                        case "remove":
+                            handleRemoveCommand(ws, args);
+                            return;
+                        case "create":
+                            handleCreateCommand(ws, args);
+                            return;
+                        case "projects":
+                            handleProjectsCommand(ws);
+                            return;
                         case "screenshot":
                             // For API sessions, send text status instead of screenshot
                             if (hybridManager?.activeSession?.kind === "api") {
@@ -388,23 +826,92 @@ export function startWsGateway(onMessage) {
                             break;
                     }
                 }
+                // Extract the session ID that PAILot says this message belongs to.
+                // This is the iTerm session ID the user was viewing when they typed/spoke.
+                // We use it for routing instead of guessing from activeItermSessionId.
+                const pailotSessionId = typeof msg.sessionId === "string" ? msg.sessionId : undefined;
+                // Helper: resolve the routing target for this message.
+                // Prefers the explicit PAILot session ID; falls back to active session.
+                const routeTarget = pailotSessionId || activeItermSessionId;
+                // If PAILot told us the session, switch iTerm to it (for stdin routing)
+                // and record it in the reply map so outbound replies go to the same session.
+                if (pailotSessionId) {
+                    pailotReplyMap.set(pailotSessionId, pailotSessionId);
+                    setLastRoutedSessionId(pailotSessionId);
+                    // Switch iTerm to the correct session if it differs from the active one
+                    if (pailotSessionId !== activeItermSessionId) {
+                        setActiveItermSessionId(pailotSessionId);
+                        if (hybridManager) {
+                            const sessions = hybridManager.listSessions();
+                            const idx = sessions.findIndex(s => s.backendSessionId === pailotSessionId);
+                            if (idx >= 0)
+                                hybridManager.switchToIndex(idx + 1);
+                        }
+                    }
+                }
                 // Voice message — transcribe with Whisper then route
                 if (msg.type === "voice" && msg.audioBase64) {
                     dbg(`Voice message received, audioBase64 length: ${msg.audioBase64.length}`);
-                    transcribeAndRoute(msg.audioBase64, onMessage).catch((err) => {
+                    broadcast({ type: "typing", typing: true, ...(routeTarget && { sessionId: routeTarget }) });
+                    const voiceMsgId = typeof msg.messageId === "string" ? msg.messageId : undefined;
+                    // Capture the routing session for this batch (first chunk wins)
+                    if (!voiceBatchSessionId && routeTarget)
+                        voiceBatchSessionId = routeTarget;
+                    transcribeAndRoute(msg.audioBase64, onMessage, voiceMsgId).catch((err) => {
                         log(`[PAILot] voice transcription error: ${err}`);
                     });
                     return;
                 }
-                // Plain text message — route through handleMessage
+                // Image message — save to temp file, route caption as text
+                // NOTE: Do NOT send the file path to Claude Code — it tries to read .jpg files
+                // as images, which corrupts the conversation context with unprocessable image data.
+                if (msg.type === "image" && msg.imageBase64) {
+                    const ext = (msg.mimeType ?? "image/jpeg").includes("png") ? "png" : "jpg";
+                    const imgPath = join(tmpdir(), `pailot-img-${Date.now()}-${randomUUID().slice(0, 8)}.${ext}`);
+                    const imgBuf = Buffer.from(msg.imageBase64, "base64");
+                    writeFileSync(imgPath, imgBuf);
+                    log(`[PAILot] Image saved (${imgBuf.length} bytes) → ${imgPath}`);
+                    const caption = msg.caption || "";
+                    // Embed the path inside parentheses so Claude Code doesn't auto-attach
+                    // the .jpg as an image (which corrupts the session if the API rejects it).
+                    // Claude can still use the Read tool to view it.
+                    const routeText = caption
+                        ? `${caption} (image at ${imgPath})`
+                        : `(image at ${imgPath})`;
+                    if (!pailotSessionId)
+                        setLastRoutedSessionId(activeItermSessionId);
+                    const imgBridge = getAibpBridge();
+                    if (imgBridge && routeTarget) {
+                        imgBridge.routeFromMobile(routeTarget, routeText, "IMAGE", {
+                            imageBase64: msg.imageBase64,
+                            mimeType: msg.mimeType ?? "image/jpeg",
+                        });
+                    }
+                    else {
+                        setMessageSource("pailot");
+                        onMessage(routeText, Date.now());
+                        setMessageSource("whatsapp");
+                    }
+                    return;
+                }
+                // Plain text message — route through AIBP bridge (or legacy fallback)
                 const text = msg.content ?? "";
                 if (!text.trim())
                     return;
                 log(`[PAILot] ← ${text.slice(0, 80)}${text.length > 80 ? "..." : ""}`);
-                // Set source so commands handler uses [PAILot] prefix
-                setMessageSource("pailot");
-                onMessage(text, Date.now());
-                setMessageSource("whatsapp");
+                broadcast({ type: "typing", typing: true, ...(routeTarget && { sessionId: routeTarget }) });
+                if (!pailotSessionId)
+                    setLastRoutedSessionId(activeItermSessionId);
+                const bridge = getAibpBridge();
+                if (bridge && routeTarget) {
+                    bridge.routeFromMobile(routeTarget, text);
+                }
+                else {
+                    // Fallback to legacy routing
+                    setMessageSource("pailot");
+                    onMessage(text, Date.now());
+                    setMessageSource("whatsapp");
+                }
             }
             catch {
                 log(`[PAILot] Invalid message from ${addr}`);
@@ -413,12 +920,17 @@ export function startWsGateway(onMessage) {
         ws.on("close", () => {
             log(`PAILot client disconnected from ${addr}`);
             clients.delete(ws);
+            clientLastActive.delete(ws);
+            clientActiveSession.delete(ws);
         });
         ws.on("error", (err) => {
             log(`[PAILot] WebSocket error: ${err.message}`);
             clients.delete(ws);
+            clientLastActive.delete(ws);
+            clientActiveSession.delete(ws);
         });
-        // Welcome
+        // Welcome — outbox drains after client sends "sync" command
+        // (so activeSessionId is set before messages arrive)
         sendTo(ws, { type: "text", content: "Connected to PAILot gateway." });
     });
     wss.on("error", (err) => {
@@ -427,15 +939,40 @@ export function startWsGateway(onMessage) {
 }
 /**
  * Broadcast a text message to all connected PAILot clients.
+ * @param sessionId — iTerm session ID of the originating Claude session
  */
-export function broadcastText(text) {
-    broadcast({ type: "text", content: text });
+function resolveSessionId(sessionId) {
+    // If an explicit sessionId was passed (from MCP detectSessionId), check the reply map
+    // first — the reply map records which session the user was actually talking to,
+    // which may differ from whatever iTerm tab is currently focused on the Mac.
+    if (sessionId) {
+        const mapped = pailotReplyMap.get(sessionId);
+        if (mapped)
+            return mapped;
+        return sessionId;
+    }
+    // Prefer the session that last received user input from PAILot —
+    // this survives session switches that happen while Claude is thinking.
+    if (lastRoutedSessionId)
+        return lastRoutedSessionId;
+    if (activeItermSessionId)
+        return activeItermSessionId;
+    // Last resort: ask hybrid manager for the active session's backend ID
+    return hybridManager?.activeSession?.backendSessionId || undefined;
+}
+export function broadcastText(text, sessionId) {
+    const resolvedSession = resolveSessionId(sessionId);
+    broadcast({ type: "typing", typing: false, ...(resolvedSession && { sessionId: resolvedSession }) });
+    broadcast({ type: "text", content: text, ...(resolvedSession && { sessionId: resolvedSession }) });
 }
 /**
  * Broadcast a voice note to all connected PAILot clients.
  * Converts OGG Opus to M4A (AAC) since iOS can't play OGG natively.
+ * @param sessionId — iTerm session ID of the originating Claude session
  */
-export async function broadcastVoice(audioBuffer, transcript) {
+export async function broadcastVoice(audioBuffer, transcript, sessionId) {
+    const resolvedSession = resolveSessionId(sessionId);
+    broadcast({ type: "typing", typing: false, ...(resolvedSession && { sessionId: resolvedSession }) });
     let sendBuffer = audioBuffer;
     // Convert OGG Opus → M4A for iOS compatibility
     try {
@@ -462,16 +999,20 @@ export async function broadcastVoice(audioBuffer, transcript) {
         type: "voice",
         content: transcript,
         audioBase64: sendBuffer.toString("base64"),
+        ...(resolvedSession && { sessionId: resolvedSession }),
     });
 }
 /**
  * Broadcast a screenshot/image to all connected PAILot clients.
+ * @param sessionId — iTerm session ID of the originating Claude session
  */
-export function broadcastImage(imageBuffer, caption) {
+export function broadcastImage(imageBuffer, caption, sessionId) {
+    const resolvedSession = resolveSessionId(sessionId);
     broadcast({
         type: "image",
         imageBase64: imageBuffer.toString("base64"),
         caption: caption ?? "Screenshot",
+        ...(resolvedSession && { sessionId: resolvedSession }),
     });
 }
 /**