pipane 0.1.6 → 0.1.8

package/dist/server/server/ws-handler.js

@@ -8,16 +8,17 @@
  * - Any number of clients can connect; each subscribes to one session at a time.
  * - Detached sessions are read from JSONL on demand.
  */
-import { WebSocket } from "ws";
+import { FRAME_CONNECTION_OPEN } from "./frame-connection.js";
 import { copyFile } from "node:fs/promises";
-import { existsSync } from "node:fs";
+import { constants as fsConstants, existsSync } from "node:fs";
 import path from "node:path";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { SessionJsonl, readSessionFromDisk, getSessionFileSize, serializeSessionState, } from "./session-jsonl.js";
 import { getSessionCwd } from "./session-cwd.js";
 import { checkCommandAvailable, installPiGlobal, isPiInstallable, makePiNotFoundMessage } from "./pi-runtime.js";
 import { modelsMatch, toCompactModelRef } from "../shared/thinking-levels.js";
 import { COMPACT_RPC_TIMEOUT_MS } from "../shared/rpc-timeouts.js";
+import { assertNever, decodeClientCommand, encodeServerMessage, } from "../shared/ws-protocol.js";
+import { SessionPathError, SessionPathGuard } from "./session-path.js";
 import { extensionStatusSnapshot, isValidExtensionStatusKey, normalizeExtensionStatusText, providerForUsageStatus, PROVIDER_USAGE_STATUS_KEY, } from "./extension-status.js";
 let nextTurnId = 0;
 function makeTurnId() {
@@ -29,6 +30,7 @@ function debugTurn(stage, data) {
 export class WsHandler {
     registry;
     pool;
+    sessionPaths;
     defaultCwd;
     piLaunch;
     ensurePool;
@@ -45,11 +47,14 @@ export class WsHandler {
      * Used for change detection when the file watcher fires.
      */
     subscribedFileSizes = new Map();
+    /** Last revision/hash published for each authoritative session state. */
+    sessionRevisions = new Map();
     piAvailable;
     piInstalling = false;
     constructor(options) {
         this.registry = options.registry;
         this.pool = options.pool;
+        this.sessionPaths = options.sessionPaths ?? new SessionPathGuard();
         this.defaultCwd = options.defaultCwd;
         this.piLaunch = options.piLaunch;
         this.ensurePool = options.ensurePool;
@@ -172,9 +177,9 @@ export class WsHandler {
         };
     }
     pushExtensionStatusesToSubscribers(sessionPath) {
-        const message = JSON.stringify(this.makeExtensionStatusMessage(sessionPath));
+        const message = encodeServerMessage(this.makeExtensionStatusMessage(sessionPath));
         for (const [ws, client] of this.clients) {
-            if (client.subscribedSession !== sessionPath || ws.readyState !== WebSocket.OPEN)
+            if (client.subscribedSession !== sessionPath || ws.readyState !== FRAME_CONNECTION_OPEN)
                 continue;
             ws.send(message);
         }
@@ -228,142 +233,160 @@ export class WsHandler {
                 .map((process) => process.attachedSession)
                 .filter((sessionPath) => sessionPath !== null),
             sessionStatuses: this.registry.getAllStatuses(),
-            connectedWsOpen: Array.from(this.clients.keys()).filter((ws) => ws.readyState === WebSocket.OPEN).length,
+            connectedWsOpen: Array.from(this.clients.keys()).filter((ws) => ws.readyState === FRAME_CONNECTION_OPEN).length,
             processes,
         };
     }
     register(wss) {
-        wss.on("connection", (ws, req) => this.handleConnection(ws, req));
+        wss.on("connection", (ws, req) => {
+            if (!this.isRequestAuthorized(req)) {
+                ws.close(1008, "Unauthorized");
+                return;
+            }
+            this.acceptConnection(ws);
+        });
     }
-    handleConnection(ws, req) {
-        if (!this.isRequestAuthorized(req)) {
-            ws.close(1008, "Unauthorized");
-            return;
-        }
-        console.log("WebSocket client connected");
+    acceptAuthenticatedConnection(connection) {
+        this.acceptConnection(connection);
+    }
+    acceptConnection(ws) {
+        console.log("Frame client connected");
         this.clients.set(ws, {
             subscribedSession: null,
             lastVersion: 0,
             lastJson: "",
             lastHash: "",
         });
-        ws.send(JSON.stringify({
+        this.sendMessage(ws, {
             type: "init",
             sessionStatuses: this.registry.getAllStatuses(),
             steeringQueues: this.registry.getAllSteeringQueues(),
             providerUsageStatuses: this.makeProviderUsageMessage().statuses,
-        }));
+        });
         if (!this.piAvailable) {
-            ws.send(JSON.stringify({
+            this.sendMessage(ws, {
                 type: "pi_install_required",
                 command: this.piLaunch.command,
                 installable: isPiInstallable(this.piLaunch.command, this.piLaunch.baseArgs),
                 installing: this.piInstalling,
                 message: makePiNotFoundMessage(this.piLaunch.command),
-            }));
+            });
         }
         ws.on("message", (raw) => this.handleMessage(ws, raw.toString()));
         ws.on("close", () => {
-            console.log("WebSocket client disconnected");
+            console.log("Frame client disconnected");
             this.clients.delete(ws);
         });
     }
+    sendMessage(ws, payload) {
+        if (ws.readyState === FRAME_CONNECTION_OPEN)
+            ws.send(encodeServerMessage(payload));
+    }
+    sendSuccess(ws, id, command, data) {
+        this.sendMessage(ws, {
+            type: "response",
+            id,
+            command,
+            success: true,
+            data,
+        });
+    }
+    sendError(ws, id, command, error, code) {
+        this.sendMessage(ws, { type: "response", id, command, success: false, code, error });
+    }
+    notifySessionsChanged(file) {
+        this.broadcast({ type: "sessions_changed", file });
+    }
     broadcast(payload) {
+        const message = encodeServerMessage(payload);
         for (const ws of this.clients.keys()) {
-            if (ws.readyState === WebSocket.OPEN) {
-                ws.send(JSON.stringify(payload));
-            }
+            if (ws.readyState === FRAME_CONNECTION_OPEN)
+                ws.send(message);
         }
     }
     async handleMessage(ws, raw) {
-        let command;
-        try {
-            command = JSON.parse(raw);
-        }
-        catch {
-            ws.send(JSON.stringify({ type: "response", command: "parse", success: false, error: "Invalid JSON" }));
+        const decoded = decodeClientCommand(raw);
+        if (!decoded.ok) {
+            this.sendError(ws, decoded.error.requestId, decoded.error.command, decoded.error.message, decoded.error.code);
             return;
         }
+        const command = decoded.value;
         const id = command.id;
         try {
             if (!this.piAvailable && command.type !== "install_pi" && command.type !== "get_session_statuses") {
-                ws.send(JSON.stringify({
+                this.sendMessage(ws, {
                     type: "pi_install_required",
                     command: this.piLaunch.command,
                     installable: isPiInstallable(this.piLaunch.command, this.piLaunch.baseArgs),
                     installing: this.piInstalling,
                     message: makePiNotFoundMessage(this.piLaunch.command),
-                }));
-                if (id) {
-                    ws.send(JSON.stringify({
-                        id, type: "response", command: command.type, success: false,
-                        error: makePiNotFoundMessage(this.piLaunch.command),
-                    }));
-                }
+                });
+                this.sendError(ws, id, command.type, makePiNotFoundMessage(this.piLaunch.command), "command_failed");
                 return;
             }
             switch (command.type) {
                 case "install_pi":
-                    await this.handleInstallPi(ws, id);
+                    await this.handleInstallPi(ws, command);
                     break;
                 case "subscribe_session":
-                    this.handleSubscribeSession(ws, id, command);
+                    this.handleSubscribeSession(ws, command);
                     break;
                 case "prompt":
-                    await this.handlePrompt(ws, id, command);
+                    await this.handlePrompt(ws, command);
                     break;
                 case "steer":
-                    await this.handleSteer(ws, id, command);
+                    await this.handleSteer(ws, command);
                     break;
                 case "remove_steering":
-                    await this.handleRemoveSteering(ws, id, command);
+                    await this.handleRemoveSteering(ws, command);
                     break;
                 case "abort":
-                    await this.handleAbort(ws, id, command);
+                    await this.handleAbort(ws, command);
                     break;
                 case "hard_kill":
-                    await this.handleHardKill(ws, id, command);
+                    await this.handleHardKill(ws, command);
                     break;
                 case "compact":
-                    await this.handleCompact(ws, id, command);
+                    await this.handleCompact(ws, command);
                     break;
                 case "get_available_models":
-                    await this.handleGetAvailableModels(ws, id);
+                    await this.handleGetAvailableModels(ws, command);
                     break;
                 case "get_default_model":
-                    await this.handleGetDefaultModel(ws, id);
+                    await this.handleGetDefaultModel(ws, command);
                     break;
                 case "get_session_statuses":
-                    this.handleGetSessionStatuses(ws, id);
+                    this.handleGetSessionStatuses(ws, command);
+                    break;
+                case "get_session_stats":
+                    await this.handleGetSessionStats(ws, command);
                     break;
                 case "fork":
-                    await this.handleFork(ws, id, command);
+                    await this.handleFork(ws, command);
                     break;
                 case "fork_prompt":
-                    await this.handleForkPrompt(ws, id, command);
+                    await this.handleForkPrompt(ws, command);
                     break;
                 case "set_session_name":
-                    await this.handleSetSessionName(ws, id, command);
+                    await this.handleSetSessionName(ws, command);
                     break;
                 case "get_commands":
-                    await this.handleGetCommands(ws, id);
+                    await this.handleGetCommands(ws, command);
                     break;
                 case "reload_processes":
-                    await this.handleReloadProcesses(ws, id);
+                    await this.handleReloadProcesses(ws, command);
                     break;
                 default:
-                    ws.send(JSON.stringify({
-                        id, type: "response", command: command.type, success: false,
-                        error: `Unknown command: ${command.type}`,
-                    }));
+                    assertNever(command);
             }
         }
-        catch (err) {
-            debugTurn("command_error", { commandType: command?.type, requestId: id, error: err?.message });
-            ws.send(JSON.stringify({ id, type: "response", command: command.type, success: false, error: err.message }));
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            debugTurn("command_error", { commandType: command.type, requestId: id, error: message });
+            this.sendError(ws, id, command.type, message, "command_failed");
         }
     }
-    async handleInstallPi(ws, id) {
+    async handleInstallPi(ws, command) {
         const installable = isPiInstallable(this.piLaunch.command, this.piLaunch.baseArgs);
         if (!installable) {
             throw new Error(`Automatic install not supported for command '${this.piLaunch.command}'. Set PI_CLI or install manually.`);
@@ -386,21 +409,35 @@ export class WsHandler {
             console.log("[pi] pi installed successfully");
             this.ensurePool();
         }
-        ws.send(JSON.stringify({ id, type: "response", command: "install_pi", success: true, data: {} }));
+        this.sendSuccess(ws, command.id, "install_pi", {});
     }
-    handleSubscribeSession(ws, id, command) {
+    handleSubscribeSession(ws, command) {
         const client = this.clients.get(ws);
         if (!client)
             return;
-        const sessionPath = command.sessionPath;
-        if (!sessionPath) {
+        const requestedPath = command.sessionPath;
+        if (!requestedPath) {
             client.subscribedSession = null;
             client.lastVersion = 0;
             client.lastJson = "";
             client.lastHash = "";
-            ws.send(JSON.stringify({ id, type: "response", command: "subscribe_session", success: true, data: {} }));
+            this.sendSuccess(ws, command.id, "subscribe_session", {});
             return;
         }
+        let sessionPath;
+        try {
+            sessionPath = this.sessionPaths.resolveExisting(requestedPath);
+        }
+        catch (error) {
+            // Pi allocates a new path before its first prompt flushes the file. The
+            // actor proves that such a confined pending path belongs to this server.
+            if (!(error instanceof SessionPathError) || error.code !== "not_found")
+                throw error;
+            const pendingPath = this.sessionPaths.resolvePending(requestedPath);
+            if (!this.registry.find(pendingPath)?.isAttached)
+                throw error;
+            sessionPath = pendingPath;
+        }
         client.subscribedSession = sessionPath;
         // If the session is attached, send from its actor-owned in-memory state
         const attached = this.registry.find(sessionPath)?.session;
@@ -409,13 +446,14 @@ export class WsHandler {
             client.lastJson = attached.json;
             client.lastHash = attached.hash;
             client.lastVersion = attached.version;
-            ws.send(JSON.stringify({
+            this.sendMessage(ws, {
                 type: "session_sync",
                 sessionPath,
+                revision: this.revisionForState(sessionPath, attached.hash),
                 op: "full",
                 data: attached.json,
                 hash: attached.hash,
-            }));
+            });
         }
         else {
             // Detached — read from disk
@@ -425,23 +463,27 @@ export class WsHandler {
             client.lastVersion = 0;
             // Track file size for change detection
             this.subscribedFileSizes.set(sessionPath, getSessionFileSize(sessionPath));
-            ws.send(JSON.stringify({
+            this.sendMessage(ws, {
                 type: "session_sync",
                 sessionPath,
+                revision: this.revisionForState(sessionPath, hash),
                 op: "full",
                 data: json,
                 hash,
-            }));
+            });
         }
         // Extension status is a separate, authoritative snapshot so reconnects
         // and session switches replace rather than merge stale client state.
-        ws.send(JSON.stringify(this.makeExtensionStatusMessage(sessionPath)));
-        ws.send(JSON.stringify({ id, type: "response", command: "subscribe_session", success: true, data: {} }));
+        this.sendMessage(ws, this.makeExtensionStatusMessage(sessionPath));
+        this.sendSuccess(ws, command.id, "subscribe_session", {});
     }
-    async handlePrompt(ws, id, command) {
-        let sessionPath = command.sessionPath;
-        if (!sessionPath)
+    async handlePrompt(ws, command) {
+        const requestedPath = command.sessionPath;
+        if (!requestedPath)
             throw new Error("Missing sessionPath");
+        let sessionPath = requestedPath === "__new__"
+            ? requestedPath
+            : this.sessionPaths.resolveExisting(requestedPath);
         const turnId = makeTurnId();
         debugTurn("prompt_start", { turnId, sessionPath, hasModel: !!command.model });
         let actor;
@@ -457,10 +499,11 @@ export class WsHandler {
                 await this.pool.waitForReady(proc);
                 this.beginPendingExtensionStatusCapture(proc);
                 await this.replacePiSession(proc, { type: "new_session" }, "new_session");
-                const stateResp = await this.pool.sendRpc(proc, { type: "get_state" });
-                sessionPath = stateResp.data?.sessionFile;
-                if (!sessionPath)
+                const stateResp = await this.pool.sendRpcChecked(proc, { type: "get_state" });
+                const createdPath = stateResp.data.sessionFile;
+                if (!createdPath)
                     throw new Error("Failed to get session path from new session");
+                sessionPath = this.sessionPaths.resolvePending(createdPath);
             }
             actor = this.registry.get(sessionPath);
             const start = await actor.enqueue("prompt start", async () => {
@@ -476,12 +519,12 @@ export class WsHandler {
                     actor.attach(unownedLease, this.createSessionState(sessionPath));
                     unownedLease = undefined;
                     this.commitPendingExtensionStatuses(proc, sessionPath);
-                    ws.send(JSON.stringify({
+                    this.sendMessage(ws, {
                         type: "session_attached",
                         sessionPath,
                         cwd: newSessionCwd,
                         firstMessage: command.message,
-                    }));
+                    });
                 }
                 else {
                     proc = await this.acquireForActor(actor);
@@ -489,15 +532,18 @@ export class WsHandler {
                 generation = actor.beginTurn();
                 const observer = this.setupTurnEventForwarding(actor, proc, generation, turnId);
                 await this.applyRequestedControlState(proc, actor, ws, command);
-                const promptCmd = { type: "prompt", message: command.message };
-                if (command.images?.length > 0)
-                    promptCmd.images = command.images;
-                const response = await this.pool.sendRpc(proc, promptCmd);
+                const response = await this.pool.sendRpc(proc, {
+                    type: "prompt",
+                    message: command.message,
+                    ...(command.images?.length ? { images: command.images } : {}),
+                });
+                if (!response.success)
+                    throw new Error(response.error);
                 await this.reconcileEffectiveControlState(proc, actor);
                 return { observer, response, generation };
             });
             if (!start) {
-                ws.send(JSON.stringify({ id, type: "response", command: "steer", success: true }));
+                this.sendSuccess(ws, command.id, "prompt", { newSessionPath: sessionPath });
                 return;
             }
             await this.waitForPromptSettlement(proc, start.observer);
@@ -507,37 +553,34 @@ export class WsHandler {
                 await this.reconcileEffectiveControlState(proc, actor);
                 this.releaseActor(actor);
             });
-            const enriched = { ...start.response };
-            if (!enriched.data)
-                enriched.data = {};
-            enriched.data.newSessionPath = sessionPath;
-            ws.send(JSON.stringify({ ...enriched, id, command: "prompt" }));
+            this.sendSuccess(ws, command.id, "prompt", { newSessionPath: sessionPath });
         }
-        catch (err) {
+        catch (error) {
             if (proc)
                 this.pendingExtensionStatuses.delete(proc);
             unownedLease?.release();
             if (actor && proc && actor.process === proc) {
-                let detailed = this.buildPromptFailureMessage(err, proc, actor);
+                let detailed = this.buildPromptFailureMessage(error, proc, actor);
                 await actor.enqueue("prompt failure", () => {
                     if (actor.process !== proc)
                         return;
-                    detailed = this.buildPromptFailureMessage(err, proc, actor);
+                    detailed = this.buildPromptFailureMessage(error, proc, actor);
                     actor.markFailed();
                     this.injectSessionError(actor, detailed);
                     this.releaseActor(actor);
                 });
-                if ((err?.message || "").includes("Timeout waiting for RPC response to prompt") && proc.process.exitCode === null) {
+                const rawMessage = error instanceof Error ? error.message : String(error);
+                if (rawMessage.includes("Timeout waiting for RPC response to prompt") && proc.process.exitCode === null) {
                     proc.process.kill("SIGTERM");
                 }
                 throw new Error(detailed);
             }
             if (proc && proc.process.exitCode === null)
                 proc.process.kill("SIGTERM");
-            throw err;
+            throw error;
         }
     }
-    async handleSteer(ws, id, command) {
+    async handleSteer(ws, command) {
         const sessionPath = command.sessionPath;
         if (!sessionPath)
             throw new Error("Missing sessionPath");
@@ -545,9 +588,9 @@ export class WsHandler {
         if (!actor)
             throw new Error("Session is not attached (agent not running)");
         await actor.enqueue("steer", () => this.sendSteering(actor, command.message));
-        ws.send(JSON.stringify({ id, type: "response", command: "steer", success: true }));
+        this.sendSuccess(ws, command.id, "steer", {});
     }
-    async handleRemoveSteering(ws, id, command) {
+    async handleRemoveSteering(ws, command) {
         const sessionPath = command.sessionPath;
         if (!sessionPath)
             throw new Error("Missing sessionPath");
@@ -557,9 +600,9 @@ export class WsHandler {
         const actor = this.registry.find(sessionPath);
         if (actor)
             await actor.enqueue("remove steering", () => actor.removeSteeringByIndex(index));
-        ws.send(JSON.stringify({ id, type: "response", command: "remove_steering", success: true }));
+        this.sendSuccess(ws, command.id, "remove_steering", {});
     }
-    async handleAbort(ws, id, command) {
+    async handleAbort(ws, command) {
         const sessionPath = command.sessionPath;
         const actor = sessionPath ? this.registry.find(sessionPath) : undefined;
         if (actor) {
@@ -569,9 +612,9 @@ export class WsHandler {
                 }
             });
         }
-        ws.send(JSON.stringify({ id, type: "response", command: "abort", success: true }));
+        this.sendSuccess(ws, command.id, "abort", {});
     }
-    async handleHardKill(ws, id, command) {
+    async handleHardKill(ws, command) {
         const sessionPath = command.sessionPath;
         if (!sessionPath)
             throw new Error("Missing sessionPath");
@@ -591,20 +634,12 @@ export class WsHandler {
         }
         if (hadProcess)
             this.ensurePool();
-        ws.send(JSON.stringify({
-            id,
-            type: "response",
-            command: "hard_kill",
-            success: true,
-            data: killed
-                ? { killed: true }
-                : { killed: false, reason: hadProcess ? "signal_failed" : "not_attached" },
-        }));
+        this.sendSuccess(ws, command.id, "hard_kill", killed
+            ? { killed: true }
+            : { killed: false, reason: hadProcess ? "signal_failed" : "not_attached" });
     }
-    async handleCompact(ws, id, command) {
-        const sessionPath = command.sessionPath;
-        if (!sessionPath)
-            throw new Error("Missing sessionPath");
+    async handleCompact(ws, command) {
+        const sessionPath = this.sessionPaths.resolveExisting(command.sessionPath);
         const actor = this.registry.get(sessionPath);
         const response = await actor.enqueue("compact", async () => {
             actor.assertAvailable("compact");
@@ -619,58 +654,88 @@ export class WsHandler {
                 this.releaseActor(actor);
             }
         });
-        ws.send(JSON.stringify({ ...response, id, command: "compact" }));
+        if (!response.success)
+            throw new Error(response.error);
+        this.sendSuccess(ws, command.id, "compact", { ...response.data });
     }
-    async handleGetAvailableModels(ws, id) {
+    async handleGetAvailableModels(ws, command) {
         const lease = await this.acquireAnyProcess();
         try {
-            const response = await this.pool.sendRpc(lease.process, { type: "get_available_models" });
-            ws.send(JSON.stringify({ ...response, id, command: "get_available_models" }));
+            const response = await this.pool.sendRpcChecked(lease.process, { type: "get_available_models" });
+            this.sendSuccess(ws, command.id, "get_available_models", {
+                models: response.data.models,
+            });
         }
         finally {
             lease.release();
         }
     }
-    async handleGetCommands(ws, id) {
-        const lease = await this.acquireAnyProcess();
+    async handleGetCommands(ws, command) {
+        let cwd = command.cwd || this.defaultCwd;
+        if (command.sessionPath) {
+            const sessionPath = this.sessionPaths.resolveExisting(command.sessionPath);
+            const sessionCwd = getSessionCwd(sessionPath);
+            cwd = sessionCwd && existsSync(sessionCwd) ? sessionCwd : this.defaultCwd;
+        }
+        // Project prompts and skills are loaded when Pi starts, so command discovery
+        // must use a process for the conversation's cwd rather than any idle worker.
+        const lease = await this.acquireProcess(cwd);
         try {
-            const response = await this.pool.sendRpc(lease.process, { type: "get_commands" });
-            ws.send(JSON.stringify({ ...response, id, command: "get_commands" }));
+            const response = await this.pool.sendRpcChecked(lease.process, { type: "get_commands" });
+            this.sendSuccess(ws, command.id, "get_commands", {
+                commands: response.data.commands,
+            });
         }
         finally {
             lease.release();
         }
     }
-    async handleReloadProcesses(ws, id) {
+    async handleReloadProcesses(ws, command) {
         const { killed, draining } = this.pool.decommissionAll();
         this.ensurePool();
-        ws.send(JSON.stringify({
-            id,
-            type: "response",
-            command: "reload_processes",
-            success: true,
-            data: { killed, draining },
-        }));
+        this.sendSuccess(ws, command.id, "reload_processes", { killed, draining });
     }
-    async handleGetDefaultModel(ws, id) {
+    async handleGetDefaultModel(ws, command) {
         const lease = await this.acquireAnyProcess();
         try {
-            const stateResp = await this.pool.sendRpc(lease.process, { type: "get_state" });
-            const model = stateResp.data?.model ?? null;
-            const thinkingLevel = stateResp.data?.thinkingLevel ?? "off";
-            ws.send(JSON.stringify({ id, type: "response", command: "get_default_model", success: true, data: { model, thinkingLevel } }));
+            const stateResp = await this.pool.sendRpcChecked(lease.process, { type: "get_state" });
+            const model = stateResp.data.model ?? null;
+            const thinkingLevel = stateResp.data.thinkingLevel;
+            this.sendSuccess(ws, command.id, "get_default_model", {
+                model: model,
+                thinkingLevel,
+            });
         }
         finally {
             lease.release();
         }
     }
-    handleGetSessionStatuses(ws, id) {
-        ws.send(JSON.stringify({ id, type: "response", command: "get_session_statuses", success: true, data: { statuses: this.registry.getAllStatuses() } }));
+    handleGetSessionStatuses(ws, command) {
+        this.sendSuccess(ws, command.id, "get_session_statuses", { statuses: this.registry.getAllStatuses() });
     }
-    async handleFork(ws, id, command) {
-        const sessionPath = command.sessionPath;
-        if (!sessionPath)
-            throw new Error("Missing sessionPath");
+    async handleGetSessionStats(ws, command) {
+        const sessionPath = this.sessionPaths.resolveExisting(command.sessionPath);
+        const actor = this.registry.get(sessionPath);
+        const response = await actor.enqueue("get session stats", async () => {
+            const wasAttached = actor.process !== undefined;
+            const proc = await this.acquireForActor(actor);
+            try {
+                return await this.pool.sendRpcChecked(proc, { type: "get_session_stats" });
+            }
+            finally {
+                // A running turn owns its process lease. Only release a lease acquired
+                // temporarily to inspect a detached session.
+                if (!wasAttached)
+                    this.releaseActor(actor);
+            }
+        });
+        this.sendSuccess(ws, command.id, "get_session_stats", {
+            ...response.data,
+            sessionFile: response.data.sessionFile ?? sessionPath,
+        });
+    }
+    async handleFork(ws, command) {
+        const sessionPath = this.sessionPaths.resolveExisting(command.sessionPath);
         const entryId = command.entryId;
         if (!entryId)
             throw new Error("Missing entryId");
@@ -679,38 +744,39 @@ export class WsHandler {
             actor.assertAvailable("fork");
             const proc = await this.acquireForActor(actor);
             try {
-                const response = await this.pool.sendRpc(proc, { type: "fork", entryId });
-                const stateResp = await this.pool.sendRpc(proc, { type: "get_state" });
-                return { response, newSessionPath: stateResp.data?.sessionFile };
+                const response = await this.pool.sendRpcChecked(proc, { type: "fork", entryId });
+                const stateResp = await this.pool.sendRpcChecked(proc, { type: "get_state" });
+                const returnedPath = stateResp.data.sessionFile;
+                return {
+                    response,
+                    newSessionPath: returnedPath
+                        ? this.sessionPaths.resolveExisting(returnedPath)
+                        : undefined,
+                };
             }
             finally {
                 this.releaseActor(actor);
             }
         });
-        ws.send(JSON.stringify({
-            id, type: "response", command: "fork", success: true,
-            data: {
-                text: result.response.data?.text ?? "",
-                cancelled: result.response.data?.cancelled ?? false,
-                newSessionPath: result.newSessionPath ?? null,
-            },
-        }));
+        this.sendSuccess(ws, command.id, "fork", {
+            text: result.response.data.text,
+            cancelled: result.response.data.cancelled,
+            newSessionPath: result.newSessionPath ?? null,
+        });
     }
-    async handleForkPrompt(ws, id, command) {
-        const sessionPath = command.sessionPath;
-        if (!sessionPath)
-            throw new Error("Missing sessionPath");
+    async handleForkPrompt(ws, command) {
+        const sessionPath = this.sessionPaths.resolveExisting(command.sessionPath);
         const message = command.message;
         if (!message)
             throw new Error("Missing message");
-        const sessionsDir = path.join(getAgentDir(), "sessions");
         const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
         const newId = crypto.randomUUID().slice(0, 8);
-        const newSessionPath = path.join(sessionsDir, `${timestamp}_${newId}.jsonl`);
+        let newSessionPath = this.sessionPaths.createPath(`${timestamp}_${newId}.jsonl`);
         const sourceActor = this.registry.get(sessionPath);
         await sourceActor.enqueue("fork prompt source", async () => {
             sourceActor.assertAvailable("fork and prompt");
-            await copyFile(sessionPath, newSessionPath);
+            await copyFile(sessionPath, newSessionPath, fsConstants.COPYFILE_EXCL);
+            newSessionPath = this.sessionPaths.resolveExisting(newSessionPath);
         });
         const forkCwd = getSessionCwd(sessionPath);
         const cwd = (forkCwd && existsSync(forkCwd)) ? forkCwd : this.defaultCwd;
@@ -728,14 +794,15 @@ export class WsHandler {
                 actor.attach(unownedLease, this.createSessionState(newSessionPath));
                 unownedLease = undefined;
                 this.commitPendingExtensionStatuses(proc, newSessionPath);
-                ws.send(JSON.stringify({ type: "session_attached", sessionPath: newSessionPath, cwd, firstMessage: message }));
+                this.sendMessage(ws, { type: "session_attached", sessionPath: newSessionPath, cwd, firstMessage: message });
                 const generation = actor.beginTurn();
                 const observer = this.setupTurnEventForwarding(actor, proc, generation, makeTurnId());
                 await this.applyRequestedControlState(proc, actor, ws, command);
-                const promptCmd = { type: "prompt", message };
-                if (command.images?.length > 0)
-                    promptCmd.images = command.images;
-                await this.pool.sendRpc(proc, promptCmd);
+                await this.pool.sendRpcChecked(proc, {
+                    type: "prompt",
+                    message,
+                    ...(command.images?.length ? { images: command.images } : {}),
+                });
                 await this.reconcileEffectiveControlState(proc, actor);
                 return { observer, generation };
             });
@@ -746,36 +813,35 @@ export class WsHandler {
                 await this.reconcileEffectiveControlState(proc, actor);
                 this.releaseActor(actor);
             });
-            ws.send(JSON.stringify({ id, type: "response", command: "fork_prompt", success: true, data: { newSessionPath } }));
+            this.sendSuccess(ws, command.id, "fork_prompt", { newSessionPath });
         }
-        catch (err) {
+        catch (error) {
             if (proc)
                 this.pendingExtensionStatuses.delete(proc);
             unownedLease?.release();
             if (proc && actor.process === proc) {
-                let detailed = this.buildPromptFailureMessage(err, proc, actor);
+                let detailed = this.buildPromptFailureMessage(error, proc, actor);
                 await actor.enqueue("fork prompt failure", () => {
                     if (actor.process !== proc)
                         return;
-                    detailed = this.buildPromptFailureMessage(err, proc, actor);
+                    detailed = this.buildPromptFailureMessage(error, proc, actor);
                     actor.markFailed();
                     this.injectSessionError(actor, detailed);
                     this.releaseActor(actor);
                 });
-                if ((err?.message || "").includes("Timeout waiting for RPC response to prompt") && proc.process.exitCode === null) {
+                const rawMessage = error instanceof Error ? error.message : String(error);
+                if (rawMessage.includes("Timeout waiting for RPC response to prompt") && proc.process.exitCode === null) {
                     proc.process.kill("SIGTERM");
                 }
                 throw new Error(detailed);
             }
             if (proc && proc.process.exitCode === null)
                 proc.process.kill("SIGTERM");
-            throw err;
+            throw error;
         }
     }
-    async handleSetSessionName(ws, id, command) {
-        const sessionPath = command.sessionPath;
-        if (!sessionPath)
-            throw new Error("Missing sessionPath");
+    async handleSetSessionName(ws, command) {
+        const sessionPath = this.sessionPaths.resolveExisting(command.sessionPath);
         const actor = this.registry.get(sessionPath);
         const response = await actor.enqueue("set session name", async () => {
             actor.assertAvailable("rename session");
@@ -787,7 +853,9 @@ export class WsHandler {
                 this.releaseActor(actor);
             }
         });
-        ws.send(JSON.stringify({ ...response, id, command: "set_session_name" }));
+        if (!response.success)
+            throw new Error(response.error);
+        this.sendSuccess(ws, command.id, "set_session_name", {});
     }
     // ── Internal helpers ─────────────────────────────────────────────────
     async replacePiSession(proc, command, operation) {
@@ -827,16 +895,15 @@ export class WsHandler {
             throw new Error(`Failed to switch model to ${command.model.provider}/${command.model.modelId}`);
         }
         this.publishEffectiveControlState(actor, stateResponse.data);
-        if (ws.readyState === WebSocket.OPEN) {
-            ws.send(JSON.stringify({
+        if (ws.readyState === FRAME_CONNECTION_OPEN) {
+            this.sendMessage(ws, {
                 type: "control_state",
                 sessionPath,
                 controlRevision: command.controlRevision,
                 model: activeModel,
-                thinkingLevel: stateResponse.data?.thinkingLevel ?? "off",
-            }));
+                thinkingLevel: stateResponse.data.thinkingLevel,
+            });
         }
-        return stateResponse.data;
     }
     async waitForPromptSettlement(proc, observer) {
         const state = await this.pool.sendRpcChecked(proc, { type: "get_state" });
@@ -928,6 +995,7 @@ export class WsHandler {
             messages: state.messages,
             model: state.model,
             thinkingLevel: state.thinkingLevel,
+            toolCallTimings: state.toolCallTimings,
         });
     }
     /** Acquire, switch, and transfer a process lease to a detached actor. */
@@ -997,25 +1065,36 @@ export class WsHandler {
                 disk.state.model = liveState.model;
                 disk.state.thinkingLevel = liveState.thinkingLevel;
             }
+            disk.state.toolCallTimings = liveState.toolCallTimings;
             disk.state.error = liveState.error;
         }
         const { json, hash } = serializeSessionState(disk.state);
         this.subscribedFileSizes.set(sessionPath, getSessionFileSize(sessionPath));
         this.pushSnapshotToSubscribers(sessionPath, json, hash);
     }
+    revisionForState(sessionPath, hash) {
+        const current = this.sessionRevisions.get(sessionPath);
+        if (current?.hash === hash)
+            return current.revision;
+        const revision = (current?.revision ?? 0) + 1;
+        this.sessionRevisions.set(sessionPath, { revision, hash });
+        return revision;
+    }
     pushSnapshotToSubscribers(sessionPath, json, hash) {
+        const revision = this.revisionForState(sessionPath, hash);
         for (const [ws, client] of this.clients) {
             if (client.subscribedSession !== sessionPath)
                 continue;
-            if (ws.readyState !== WebSocket.OPEN)
+            if (ws.readyState !== FRAME_CONNECTION_OPEN)
                 continue;
-            ws.send(JSON.stringify({
+            this.sendMessage(ws, {
                 type: "session_sync",
                 sessionPath,
+                revision,
                 op: "full",
                 data: json,
                 hash,
-            }));
+            });
             client.lastJson = json;
             client.lastHash = hash;
             client.lastVersion = 0;
@@ -1026,19 +1105,21 @@ export class WsHandler {
      * Uses the hash-verified diff protocol for efficient incremental sync.
      */
     pushUpdateToSubscribers(sessionPath, session) {
+        const revision = this.revisionForState(sessionPath, session.hash);
         for (const [ws, client] of this.clients) {
             if (client.subscribedSession !== sessionPath)
                 continue;
-            if (ws.readyState !== WebSocket.OPEN)
+            if (ws.readyState !== FRAME_CONNECTION_OPEN)
                 continue;
             const syncOp = session.computeSyncOp(client.lastJson, client.lastHash, client.lastVersion);
             if (!syncOp)
                 continue;
-            ws.send(JSON.stringify({
+            this.sendMessage(ws, {
                 type: "session_sync",
                 sessionPath,
+                revision,
                 ...syncOp,
-            }));
+            });
             client.lastJson = session.json;
             client.lastHash = session.hash;
             client.lastVersion = session.version;
@@ -1060,7 +1141,7 @@ export class WsHandler {
         const eventHandler = (sourceProc, data) => {
             if (sourceProc !== proc || data.type === "extension_ui_request")
                 return;
-            const replacementMessages = data.type === "auto_compaction_end" && data.result
+            const replacementMessages = data.type === "compaction_end" && data.result
                 ? readSessionFromDisk(sessionPath).state.messages
                 : undefined;
             void actor.applyProcessEvent(proc, generation, data, replacementMessages).then((result) => {