pipane 0.1.5 → 0.1.7

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

@@ -2,22 +2,24 @@
  * WebSocket handler for pipane.
  *
  * Architecture:
- * - Sessions are either "attached" (pi process running, full state in memory)
- *   or "detached" (no in-memory state, read from JSONL on disk on demand).
- * - Any number of clients can connect simultaneously.
- * - Each client can subscribe to one session at a time.
- * - Attached sessions push stream_delta or snapshot ops to subscribed clients.
- * - Detached sessions are read from disk when a client subscribes.
+ * - SessionRegistry provides one serialized SessionActor per session path.
+ * - The actor owns its process lease, phase, materialized state, steering, and cleanup.
+ * - WsHandler validates/routes transport commands and publishes actor updates.
+ * - 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 { URL } from "node:url";
-import { getAgentDir } from "@mariozechner/pi-coding-agent";
-import { SessionJsonl, readSessionFromDisk, getSessionFileSize, } from "./session-jsonl.js";
+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() {
     return `turn_${Date.now()}_${++nextTurnId}`;
@@ -26,41 +28,40 @@ function debugTurn(stage, data) {
     console.log(`[turn] ${stage} ${JSON.stringify(data)}`);
 }
 export class WsHandler {
-    lifecycle;
+    registry;
     pool;
+    sessionPaths;
     defaultCwd;
     piLaunch;
     ensurePool;
     isRequestAuthorized;
-    traceStore;
     clients = new Map();
-    wsTraceIds = new Map();
-    busyProcesses = new Set();
-    procEventCleanup = new Map();
-    /** Processes marked for graceful decommission after current turn ends. */
-    decommissionProcesses = new Set();
-    /**
-     * In-memory state for sessions with an attached pi process.
-     * Keyed by session path. Created on attach, deleted on detach.
-     */
-    attachedSessions = new Map();
+    /** Last known extension statuses, retained while a session is detached. */
+    extensionStatusesBySession = new Map();
+    /** Latest successful account-wide subscription usage from any process. */
+    providerUsageStatuses = new Map();
+    /** Statuses emitted while a process is switching to a not-yet-attached session. */
+    pendingExtensionStatuses = new WeakMap();
     /**
      * Track file sizes for detached sessions that clients are subscribed to.
      * 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.lifecycle = options.lifecycle;
+        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;
         this.isRequestAuthorized = options.isRequestAuthorized;
-        this.traceStore = options.traceStore;
         this.piAvailable = checkCommandAvailable(this.piLaunch.command);
-        this.lifecycle.subscribe((event) => {
+        this.pool.subscribeEvents((proc, event) => this.handleProcessEvent(proc, event));
+        this.registry.subscribe((event) => {
             switch (event.type) {
                 case "session_attached":
                     this.broadcast({
@@ -77,11 +78,9 @@ export class WsHandler {
                     });
                     break;
                 case "steering_queue_update": {
-                    const session = this.attachedSessions.get(event.sessionPath);
-                    if (session) {
-                        session.steeringQueue = [...event.queue];
+                    const session = this.registry.find(event.sessionPath)?.session;
+                    if (session)
                         this.pushUpdateToSubscribers(event.sessionPath, session);
-                    }
                     break;
                 }
             }
@@ -90,23 +89,100 @@ export class WsHandler {
     get isPiAvailable() {
         return this.piAvailable;
     }
-    recordTrace(traceId, source, kind, name, durationMs, attrs) {
-        if (!traceId || !this.traceStore)
+    /** Idempotently clean up the owning actor after an RPC process exits. */
+    handleProcessExit(proc) {
+        this.pendingExtensionStatuses.delete(proc);
+        const actor = this.registry.getActorForProcess(proc);
+        if (!actor)
             return;
-        this.traceStore.record(traceId, {
-            ts: new Date().toISOString(),
-            source,
-            kind,
-            name,
-            durationMs,
-            attrs,
+        console.log(`[pool] pi#${proc.id} crashed while attached to ${path.basename(actor.sessionPath)} — marking done`);
+        void actor.enqueue("process exit", () => {
+            if (actor.process !== proc)
+                return;
+            actor.markFailed();
+            // Without a final get_state, disk is safer than potentially stale
+            // in-memory controls (pi may have persisted a model change before crash).
+            this.releaseActor(actor, false);
         });
     }
-    getTraceIdForMessage(ws, command) {
-        const fromCommand = command?.__trace?.traceId;
-        if (typeof fromCommand === "string" && fromCommand.length > 0)
-            return fromCommand;
-        return this.wsTraceIds.get(ws);
+    handleProcessEvent(proc, event) {
+        if (event.type !== "extension_ui_request" || event.method !== "setStatus")
+            return;
+        if (!isValidExtensionStatusKey(event.statusKey))
+            return;
+        const normalizedStatusText = typeof event.statusText === "string"
+            ? normalizeExtensionStatusText(event.statusText)
+            : undefined;
+        // Subscription usage belongs to the provider account, not a conversation.
+        // Capture successful values even from unattached prewarm processes so a
+        // virtual or never-run conversation can still display the latest quota.
+        if (event.statusKey === PROVIDER_USAGE_STATUS_KEY && normalizedStatusText) {
+            const provider = providerForUsageStatus(normalizedStatusText);
+            if (provider && this.providerUsageStatuses.get(provider) !== normalizedStatusText) {
+                this.providerUsageStatuses.set(provider, normalizedStatusText);
+                this.broadcast(this.makeProviderUsageMessage());
+            }
+        }
+        const sessionPath = this.registry.getActorForProcess(proc)?.sessionPath;
+        const statuses = sessionPath
+            ? (this.extensionStatusesBySession.get(sessionPath) ?? new Map())
+            : this.pendingExtensionStatuses.get(proc);
+        if (!statuses)
+            return;
+        if (sessionPath && !this.extensionStatusesBySession.has(sessionPath)) {
+            this.extensionStatusesBySession.set(sessionPath, statuses);
+        }
+        const previous = statuses.get(event.statusKey);
+        if (event.statusText === undefined) {
+            statuses.delete(event.statusKey);
+        }
+        else if (normalizedStatusText !== undefined) {
+            if (normalizedStatusText)
+                statuses.set(event.statusKey, normalizedStatusText);
+            else
+                statuses.delete(event.statusKey);
+        }
+        else {
+            return;
+        }
+        if (sessionPath && previous !== statuses.get(event.statusKey)) {
+            this.pushExtensionStatusesToSubscribers(sessionPath);
+        }
+    }
+    beginPendingExtensionStatusCapture(proc, sessionPath) {
+        const existing = sessionPath ? this.extensionStatusesBySession.get(sessionPath) : undefined;
+        this.pendingExtensionStatuses.set(proc, new Map(existing ?? []));
+    }
+    commitPendingExtensionStatuses(proc, sessionPath) {
+        const pending = this.pendingExtensionStatuses.get(proc);
+        this.pendingExtensionStatuses.delete(proc);
+        if (pending)
+            this.extensionStatusesBySession.set(sessionPath, pending);
+        else if (!this.extensionStatusesBySession.has(sessionPath)) {
+            this.extensionStatusesBySession.set(sessionPath, new Map());
+        }
+        this.pushExtensionStatusesToSubscribers(sessionPath);
+    }
+    makeExtensionStatusMessage(sessionPath) {
+        return {
+            type: "extension_status",
+            sessionPath,
+            statuses: extensionStatusSnapshot(this.extensionStatusesBySession.get(sessionPath)),
+        };
+    }
+    makeProviderUsageMessage() {
+        return {
+            type: "provider_usage",
+            statuses: Object.fromEntries(this.providerUsageStatuses),
+        };
+    }
+    pushExtensionStatusesToSubscribers(sessionPath) {
+        const message = encodeServerMessage(this.makeExtensionStatusMessage(sessionPath));
+        for (const [ws, client] of this.clients) {
+            if (client.subscribedSession !== sessionPath || ws.readyState !== FRAME_CONNECTION_OPEN)
+                continue;
+            ws.send(message);
+        }
     }
     /**
      * Called by the file watcher when a JSONL file changes on disk.
@@ -115,7 +191,7 @@ export class WsHandler {
      */
     notifySessionFileChanged(sessionPath) {
         // If the session is attached, ignore — streaming events are authoritative
-        if (this.attachedSessions.has(sessionPath))
+        if (this.registry.find(sessionPath)?.isAttached)
             return;
         // Check if any client is subscribed to this session
         let hasSubscribers = false;
@@ -138,170 +214,179 @@ export class WsHandler {
         this.pushSnapshotToSubscribers(sessionPath, json, hash);
     }
     getDebugState() {
-        const processes = this.pool.getAllProcesses().map((p) => ({
-            id: p.id,
-            pid: p.process.pid ?? null,
-            alive: p.process.exitCode === null,
-            exitCode: p.process.exitCode,
-            cwd: p.cwd,
-            busy: this.busyProcesses.has(p),
-            decommissioning: this.decommissionProcesses.has(p),
-            attachedSession: this.lifecycle.getAttachedSessionForProcess(p) ?? null,
-            pendingRequests: p.pendingRequests.size,
+        const processes = this.pool.getAllProcesses().map((proc) => ({
+            id: proc.id,
+            pid: proc.process.pid ?? null,
+            alive: proc.process.exitCode === null,
+            exitCode: proc.process.exitCode,
+            cwd: proc.cwd,
+            busy: this.pool.isLeased(proc),
+            decommissioning: this.pool.isDecommissioning(proc),
+            attachedSession: this.registry.getActorForProcess(proc)?.sessionPath ?? null,
+            pendingRequests: proc.pendingRequests.size,
         }));
         return {
             now: new Date().toISOString(),
             totalProcesses: this.pool.totalProcesses,
-            attachedSessionCount: this.lifecycle.attachedCount,
-            sessionStatuses: this.lifecycle.getAllStatuses(),
-            connectedWsOpen: Array.from(this.clients.keys()).filter((ws) => ws.readyState === WebSocket.OPEN).length,
+            attachedSessionCount: this.registry.attachedCount,
+            attachedSessionPaths: processes
+                .map((process) => process.attachedSession)
+                .filter((sessionPath) => sessionPath !== null),
+            sessionStatuses: this.registry.getAllStatuses(),
+            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;
-        }
-        const reqUrl = req.url || "/ws";
-        const parsed = new URL(reqUrl, "http://localhost");
-        const traceId = parsed.searchParams.get("traceId") || undefined;
-        if (traceId) {
-            this.wsTraceIds.set(ws, traceId);
-            this.recordTrace(traceId, "backend", "instant", "ws connection open");
-        }
-        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.lifecycle.getAllStatuses(),
-            steeringQueues: this.lifecycle.getAllSteeringQueues(),
-        }));
+            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", () => {
-            const wsTraceId = this.wsTraceIds.get(ws);
-            this.recordTrace(wsTraceId, "backend", "instant", "ws connection close");
-            console.log("WebSocket client disconnected");
+            console.log("Frame client disconnected");
             this.clients.delete(ws);
-            this.wsTraceIds.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;
-        const traceId = this.getTraceIdForMessage(ws, command);
-        const commandStart = performance.now();
-        this.recordTrace(traceId, "backend", "instant", `ws command received: ${command.type}`);
         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, 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 }));
-            this.recordTrace(traceId, "backend", "span", `ws command ${command.type}`, Number((performance.now() - commandStart).toFixed(2)), { success: false, error: err?.message });
-            return;
+        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");
         }
-        this.recordTrace(traceId, "backend", "span", `ws command ${command.type}`, Number((performance.now() - commandStart).toFixed(2)), { success: true });
     }
-    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.`);
@@ -324,36 +409,51 @@ 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 in-memory state
-        const attached = this.attachedSessions.get(sessionPath);
+        // If the session is attached, send from its actor-owned in-memory state
+        const attached = this.registry.find(sessionPath)?.session;
         if (attached) {
             // Send full sync
             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
@@ -363,288 +463,492 @@ 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,
-            }));
+            });
         }
-        ws.send(JSON.stringify({ id, type: "response", command: "subscribe_session", success: true, data: {} }));
+        // Extension status is a separate, authoritative snapshot so reconnects
+        // and session switches replace rather than merge stale client state.
+        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;
         let proc;
+        let unownedLease;
+        let generation;
         try {
+            let newSessionCwd;
             if (sessionPath === "__new__") {
-                const cwd = command.cwd || this.defaultCwd;
-                proc = await this.acquireProcess(cwd);
+                newSessionCwd = command.cwd || this.defaultCwd;
+                unownedLease = await this.acquireProcess(newSessionCwd);
+                proc = unownedLease.process;
                 await this.pool.waitForReady(proc);
-                await this.pool.sendRpc(proc, { type: "new_session" });
-                const stateResp = await this.pool.sendRpc(proc, { type: "get_state" });
-                sessionPath = stateResp.data?.sessionFile;
-                if (!sessionPath)
+                this.beginPendingExtensionStatusCapture(proc);
+                await this.replacePiSession(proc, { type: "new_session" }, "new_session");
+                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");
-                this.busyProcesses.add(proc);
-                // Create attached session with empty state (new session)
-                this.createAttachedSession(sessionPath);
-                ws.send(JSON.stringify({
-                    type: "session_attached",
-                    sessionPath,
-                    cwd,
-                    firstMessage: command.message,
-                }));
-                this.lifecycle.attach(sessionPath, proc);
-            }
-            else {
-                proc = await this.acquireForSession(sessionPath);
-            }
-            if (!command.model) {
-                throw new Error(`BUG: prompt command received without model. sessionPath=${sessionPath}`);
+                sessionPath = this.sessionPaths.resolvePending(createdPath);
             }
-            await this.pool.sendRpcChecked(proc, {
-                type: "set_model",
-                provider: command.model.provider,
-                modelId: command.model.modelId,
+            actor = this.registry.get(sessionPath);
+            const start = await actor.enqueue("prompt start", async () => {
+                // A second prompt that arrived during startup observes the committed
+                // actor phase and becomes steering rather than a second turn owner.
+                if (actor.isTurnActive) {
+                    await this.sendSteering(actor, command.message);
+                    return undefined;
+                }
+                actor.assertAvailable("start prompt");
+                if (unownedLease) {
+                    proc = unownedLease.process;
+                    actor.attach(unownedLease, this.createSessionState(sessionPath));
+                    unownedLease = undefined;
+                    this.commitPendingExtensionStatuses(proc, sessionPath);
+                    this.sendMessage(ws, {
+                        type: "session_attached",
+                        sessionPath,
+                        cwd: newSessionCwd,
+                        firstMessage: command.message,
+                    });
+                }
+                else {
+                    proc = await this.acquireForActor(actor);
+                }
+                generation = actor.beginTurn();
+                const observer = this.setupTurnEventForwarding(actor, proc, generation, turnId);
+                await this.applyRequestedControlState(proc, actor, ws, command);
+                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 };
             });
-            const modelState = await this.pool.sendRpcChecked(proc, { type: "get_state" });
-            const activeModel = modelState.data?.model;
-            if (!activeModel || activeModel.provider !== command.model.provider || activeModel.id !== command.model.modelId) {
-                throw new Error(`Failed to switch model to ${command.model.provider}/${command.model.modelId}`);
-            }
-            if (command.thinkingLevel) {
-                await this.pool.sendRpcChecked(proc, { type: "set_thinking_level", level: command.thinkingLevel });
-            }
-            this.setupTurnEventForwarding(proc, sessionPath, ws, turnId);
-            const promptCmd = { type: "prompt", message: command.message };
-            if (command.images?.length > 0) {
-                promptCmd.images = command.images;
+            if (!start) {
+                this.sendSuccess(ws, command.id, "prompt", { newSessionPath: sessionPath });
+                return;
             }
-            const response = await this.pool.sendRpc(proc, promptCmd);
-            const enriched = { ...response };
-            if (!enriched.data)
-                enriched.data = {};
-            enriched.data.newSessionPath = sessionPath;
-            ws.send(JSON.stringify({ ...enriched, id, command: "prompt" }));
+            await this.waitForPromptSettlement(proc, start.observer);
+            await actor.enqueue("prompt settlement", async () => {
+                if (!actor.owns(proc, start.generation))
+                    return;
+                await this.reconcileEffectiveControlState(proc, actor);
+                this.releaseActor(actor);
+            });
+            this.sendSuccess(ws, command.id, "prompt", { newSessionPath: sessionPath });
         }
-        catch (err) {
-            if (proc && sessionPath && this.lifecycle.getAttachedProcess(sessionPath) === proc) {
-                const detailed = this.buildPromptFailureMessage(err, proc, sessionPath);
-                this.injectSessionError(sessionPath, detailed);
-                this.releaseProcess(sessionPath);
-                if ((err?.message || "").includes("Timeout waiting for RPC response to prompt") && proc.process.exitCode === null) {
+        catch (error) {
+            if (proc)
+                this.pendingExtensionStatuses.delete(proc);
+            unownedLease?.release();
+            if (actor && proc && actor.process === proc) {
+                let detailed = this.buildPromptFailureMessage(error, proc, actor);
+                await actor.enqueue("prompt failure", () => {
+                    if (actor.process !== proc)
+                        return;
+                    detailed = this.buildPromptFailureMessage(error, proc, actor);
+                    actor.markFailed();
+                    this.injectSessionError(actor, detailed);
+                    this.releaseActor(actor);
+                });
+                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) {
-                this.busyProcesses.delete(proc);
-                if (proc.process.exitCode === null)
-                    proc.process.kill("SIGTERM");
-            }
-            throw err;
+            if (proc && proc.process.exitCode === null)
+                proc.process.kill("SIGTERM");
+            throw error;
         }
     }
-    async handleSteer(ws, id, command) {
+    async handleSteer(ws, command) {
         const sessionPath = command.sessionPath;
         if (!sessionPath)
             throw new Error("Missing sessionPath");
-        const proc = this.lifecycle.getAttachedProcess(sessionPath);
-        if (!proc)
+        const actor = this.registry.find(sessionPath);
+        if (!actor)
             throw new Error("Session is not attached (agent not running)");
-        this.lifecycle.enqueueSteering(sessionPath, command.message);
-        await this.pool.sendRpc(proc, { type: "steer", message: command.message });
-        ws.send(JSON.stringify({ id, type: "response", command: "steer", success: true }));
+        await actor.enqueue("steer", () => this.sendSteering(actor, command.message));
+        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");
         const index = command.index;
         if (typeof index !== "number")
             throw new Error("Missing index");
-        this.lifecycle.removeSteeringByIndex(sessionPath, index);
-        ws.send(JSON.stringify({ id, type: "response", command: "remove_steering", success: true }));
+        const actor = this.registry.find(sessionPath);
+        if (actor)
+            await actor.enqueue("remove steering", () => actor.removeSteeringByIndex(index));
+        this.sendSuccess(ws, command.id, "remove_steering", {});
     }
-    async handleAbort(ws, id, command) {
+    async handleAbort(ws, command) {
         const sessionPath = command.sessionPath;
-        const proc = sessionPath ? this.lifecycle.getAttachedProcess(sessionPath) : undefined;
-        if (proc) {
-            await this.pool.sendRpc(proc, { type: "abort" });
+        const actor = sessionPath ? this.registry.find(sessionPath) : undefined;
+        if (actor) {
+            await actor.enqueue("abort", async () => {
+                if (actor.isTurnActive && actor.process) {
+                    await this.pool.sendRpc(actor.process, { type: "abort" });
+                }
+            });
         }
-        ws.send(JSON.stringify({ id, type: "response", command: "abort", success: true }));
+        this.sendSuccess(ws, command.id, "abort", {});
     }
-    async handleCompact(ws, id, command) {
+    async handleHardKill(ws, command) {
         const sessionPath = command.sessionPath;
         if (!sessionPath)
             throw new Error("Missing sessionPath");
-        const proc = await this.acquireForSession(sessionPath);
-        const response = await this.pool.sendRpc(proc, { type: "compact", customInstructions: command.customInstructions });
-        this.releaseProcess(sessionPath);
-        ws.send(JSON.stringify({ ...response, id, command: "compact" }));
-    }
-    async handleGetAvailableModels(ws, id) {
-        const proc = this.getAnyProcess();
-        const response = await this.pool.sendRpc(proc, { type: "get_available_models" });
-        ws.send(JSON.stringify({ ...response, id, command: "get_available_models" }));
-    }
-    async handleGetCommands(ws, id) {
-        const proc = this.getAnyProcess();
-        const response = await this.pool.sendRpc(proc, { type: "get_commands" });
-        ws.send(JSON.stringify({ ...response, id, command: "get_commands" }));
-    }
-    async handleReloadProcesses(ws, id) {
-        const all = this.pool.getAllProcesses();
-        let killed = 0;
-        let draining = 0;
-        for (const proc of all) {
-            if (proc.process.exitCode !== null)
-                continue;
-            const sessionPath = this.lifecycle.getAttachedSessionForProcess(proc);
-            if (sessionPath) {
-                // Graceful path: keep running turns alive, but decommission the process
-                // once the turn ends (releaseProcess will terminate it).
-                if (!this.decommissionProcesses.has(proc)) {
-                    this.decommissionProcesses.add(proc);
-                    draining += 1;
-                }
-                continue;
+        const actor = this.registry.find(sessionPath);
+        let hadProcess = false;
+        let killed = false;
+        if (actor) {
+            await actor.enqueue("hard kill", () => {
+                const proc = actor.process;
+                if (!proc)
+                    return;
+                hadProcess = true;
+                killed = this.pool.forceKill(proc);
+                actor.markFailed();
+                this.releaseActor(actor, false);
+            });
+        }
+        if (hadProcess)
+            this.ensurePool();
+        this.sendSuccess(ws, command.id, "hard_kill", killed
+            ? { killed: true }
+            : { killed: false, reason: hadProcess ? "signal_failed" : "not_attached" });
+    }
+    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");
+            const proc = await this.acquireForActor(actor);
+            try {
+                // Pi returns only after the summarization model call and session write.
+                // The generic 30s RPC timeout can expire while compaction is healthy,
+                // causing its eventual response and compaction_end event to be orphaned.
+                return await this.pool.sendRpc(proc, { type: "compact", customInstructions: command.customInstructions }, COMPACT_RPC_TIMEOUT_MS);
             }
-            // Idle/unattached process: terminate immediately.
-            const cleanup = this.procEventCleanup.get(proc);
-            if (cleanup) {
-                cleanup();
-                this.procEventCleanup.delete(proc);
+            finally {
+                this.releaseActor(actor);
             }
-            this.busyProcesses.delete(proc);
-            this.decommissionProcesses.delete(proc);
-            proc.process.kill("SIGTERM");
-            killed += 1;
+        });
+        if (!response.success)
+            throw new Error(response.error);
+        this.sendSuccess(ws, command.id, "compact", { ...response.data });
+    }
+    async handleGetAvailableModels(ws, command) {
+        const lease = await this.acquireAnyProcess();
+        try {
+            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, 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.sendRpcChecked(lease.process, { type: "get_commands" });
+            this.sendSuccess(ws, command.id, "get_commands", {
+                commands: response.data.commands,
+            });
+        }
+        finally {
+            lease.release();
+        }
+    }
+    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) {
-        const proc = this.getAnyProcess();
-        const stateResp = await this.pool.sendRpc(proc, { 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 } }));
+    async handleGetDefaultModel(ws, command) {
+        const lease = await this.acquireAnyProcess();
+        try {
+            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.lifecycle.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");
-        const proc = await this.acquireForSession(sessionPath);
-        const response = await this.pool.sendRpc(proc, { type: "fork", entryId });
-        const stateResp = await this.pool.sendRpc(proc, { type: "get_state" });
-        const newSessionPath = stateResp.data?.sessionFile;
-        this.releaseProcess(sessionPath);
-        ws.send(JSON.stringify({
-            id, type: "response", command: "fork", success: true,
-            data: {
-                text: response.data?.text ?? "",
-                cancelled: response.data?.cancelled ?? false,
-                newSessionPath: newSessionPath ?? null,
-            },
-        }));
+        const actor = this.registry.get(sessionPath);
+        const result = await actor.enqueue("fork", async () => {
+            actor.assertAvailable("fork");
+            const proc = await this.acquireForActor(actor);
+            try {
+                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);
+            }
+        });
+        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 newFilename = `${timestamp}_${newId}.jsonl`;
-        const newSessionPath = path.join(sessionsDir, newFilename);
-        await copyFile(sessionPath, newSessionPath);
+        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, fsConstants.COPYFILE_EXCL);
+            newSessionPath = this.sessionPaths.resolveExisting(newSessionPath);
+        });
         const forkCwd = getSessionCwd(sessionPath);
         const cwd = (forkCwd && existsSync(forkCwd)) ? forkCwd : this.defaultCwd;
-        const proc = await this.acquireProcess(cwd);
-        await this.pool.waitForReady(proc);
-        this.busyProcesses.add(proc);
+        const actor = this.registry.get(newSessionPath);
+        let proc;
+        let unownedLease;
         try {
-            // Create attached session, seeded from the forked file
-            this.createAttachedSession(newSessionPath);
-            ws.send(JSON.stringify({ type: "session_attached", sessionPath: newSessionPath, cwd, firstMessage: message }));
-            this.lifecycle.attach(newSessionPath, proc);
-            await this.pool.sendRpc(proc, { type: "switch_session", sessionPath: newSessionPath });
-            if (!command.model) {
-                throw new Error(`BUG: fork_prompt command received without model. sessionPath=${newSessionPath}`);
-            }
-            await this.pool.sendRpcChecked(proc, {
-                type: "set_model",
-                provider: command.model.provider,
-                modelId: command.model.modelId,
+            const start = await actor.enqueue("fork prompt start", async () => {
+                actor.assertAvailable("fork and prompt");
+                unownedLease = await this.acquireProcess(cwd);
+                proc = unownedLease.process;
+                await this.pool.waitForReady(proc);
+                this.beginPendingExtensionStatusCapture(proc);
+                await this.replacePiSession(proc, { type: "switch_session", sessionPath: newSessionPath }, "switch_session");
+                actor.attach(unownedLease, this.createSessionState(newSessionPath));
+                unownedLease = undefined;
+                this.commitPendingExtensionStatuses(proc, newSessionPath);
+                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);
+                await this.pool.sendRpcChecked(proc, {
+                    type: "prompt",
+                    message,
+                    ...(command.images?.length ? { images: command.images } : {}),
+                });
+                await this.reconcileEffectiveControlState(proc, actor);
+                return { observer, generation };
             });
-            const modelState = await this.pool.sendRpcChecked(proc, { type: "get_state" });
-            const activeModel = modelState.data?.model;
-            if (!activeModel || activeModel.provider !== command.model.provider || activeModel.id !== command.model.modelId) {
-                throw new Error(`Failed to switch model to ${command.model.provider}/${command.model.modelId}`);
-            }
-            if (command.thinkingLevel) {
-                await this.pool.sendRpcChecked(proc, { type: "set_thinking_level", level: command.thinkingLevel });
-            }
-            const turnId = makeTurnId();
-            this.setupTurnEventForwarding(proc, newSessionPath, ws, turnId);
-            const promptCmd = { type: "prompt", message };
-            if (command.images?.length > 0) {
-                promptCmd.images = command.images;
-            }
-            await this.pool.sendRpc(proc, promptCmd);
-            ws.send(JSON.stringify({ id, type: "response", command: "fork_prompt", success: true, data: { newSessionPath } }));
+            await this.waitForPromptSettlement(proc, start.observer);
+            await actor.enqueue("fork prompt settlement", async () => {
+                if (!actor.owns(proc, start.generation))
+                    return;
+                await this.reconcileEffectiveControlState(proc, actor);
+                this.releaseActor(actor);
+            });
+            this.sendSuccess(ws, command.id, "fork_prompt", { newSessionPath });
         }
-        catch (err) {
-            if (this.lifecycle.getAttachedProcess(newSessionPath) === proc) {
-                const detailed = this.buildPromptFailureMessage(err, proc, newSessionPath);
-                this.injectSessionError(newSessionPath, detailed);
-                this.releaseProcess(newSessionPath);
-                if ((err?.message || "").includes("Timeout waiting for RPC response to prompt") && proc.process.exitCode === null) {
+        catch (error) {
+            if (proc)
+                this.pendingExtensionStatuses.delete(proc);
+            unownedLease?.release();
+            if (proc && actor.process === proc) {
+                let detailed = this.buildPromptFailureMessage(error, proc, actor);
+                await actor.enqueue("fork prompt failure", () => {
+                    if (actor.process !== proc)
+                        return;
+                    detailed = this.buildPromptFailureMessage(error, proc, actor);
+                    actor.markFailed();
+                    this.injectSessionError(actor, detailed);
+                    this.releaseActor(actor);
+                });
+                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);
             }
-            this.busyProcesses.delete(proc);
-            if (proc.process.exitCode === null)
+            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");
-        const proc = await this.acquireForSession(sessionPath);
-        const response = await this.pool.sendRpc(proc, { type: "set_session_name", name: command.name });
-        this.releaseProcess(sessionPath);
-        ws.send(JSON.stringify({ ...response, id, command: "set_session_name" }));
+    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");
+            const proc = await this.acquireForActor(actor);
+            try {
+                return await this.pool.sendRpc(proc, { type: "set_session_name", name: command.name });
+            }
+            finally {
+                this.releaseActor(actor);
+            }
+        });
+        if (!response.success)
+            throw new Error(response.error);
+        this.sendSuccess(ws, command.id, "set_session_name", {});
     }
     // ── Internal helpers ─────────────────────────────────────────────────
-    buildPromptFailureMessage(err, proc, sessionPath) {
+    async replacePiSession(proc, command, operation) {
+        const response = await this.pool.sendRpcChecked(proc, command);
+        if (response.data?.cancelled) {
+            throw new Error(`Pi ${operation} was cancelled`);
+        }
+    }
+    /**
+     * Apply a client's requested controls as one ordered RPC transaction, then
+     * publish pi's effective (possibly clamped) state before the prompt starts.
+     */
+    async applyRequestedControlState(proc, actor, ws, command) {
+        const sessionPath = actor.sessionPath;
+        if (!command.model) {
+            throw new Error(`BUG: prompt command received without model. sessionPath=${sessionPath}`);
+        }
+        let stateResponse = await this.pool.sendRpcChecked(proc, { type: "get_state" });
+        if (!modelsMatch(stateResponse.data?.model, command.model)) {
+            await this.pool.sendRpcChecked(proc, {
+                type: "set_model",
+                provider: command.model.provider,
+                modelId: command.model.modelId,
+            });
+        }
+        if (typeof command.thinkingLevel === "string") {
+            await this.pool.sendRpcChecked(proc, {
+                type: "set_thinking_level",
+                level: command.thinkingLevel,
+            });
+        }
+        // set_thinking_level has no effective value in its response and set_model
+        // may clamp effort, so get_state is the authoritative transaction result.
+        stateResponse = await this.pool.sendRpcChecked(proc, { type: "get_state" });
+        const activeModel = stateResponse.data?.model;
+        if (!modelsMatch(activeModel, command.model)) {
+            throw new Error(`Failed to switch model to ${command.model.provider}/${command.model.modelId}`);
+        }
+        this.publishEffectiveControlState(actor, stateResponse.data);
+        if (ws.readyState === FRAME_CONNECTION_OPEN) {
+            this.sendMessage(ws, {
+                type: "control_state",
+                sessionPath,
+                controlRevision: command.controlRevision,
+                model: activeModel,
+                thinkingLevel: stateResponse.data.thinkingLevel,
+            });
+        }
+    }
+    async waitForPromptSettlement(proc, observer) {
+        const state = await this.pool.sendRpcChecked(proc, { type: "get_state" });
+        // Pi >= 0.80 acknowledges a prompt only after preflight. Before that
+        // acknowledgement is written, a real agent run synchronously marks the
+        // session streaming; an extension-handled input remains idle and emits no
+        // agent lifecycle. This authoritative state check avoids timing guesses.
+        if (!state.data?.isStreaming && !observer.hasStarted())
+            return;
+        let removeExitListener = () => { };
+        const exited = new Promise((_resolve, reject) => {
+            if (proc.process.exitCode !== null) {
+                reject(new Error(`pi process #${proc.id} exited before the turn settled`));
+                return;
+            }
+            const onExit = () => reject(new Error(`pi process #${proc.id} exited before the turn settled`));
+            proc.process.once("exit", onExit);
+            removeExitListener = () => proc.process.removeListener("exit", onExit);
+        });
+        try {
+            await Promise.race([observer.settled, exited]);
+        }
+        finally {
+            removeExitListener();
+        }
+    }
+    /** Refresh controls after extensions or model clamps that happened in-turn. */
+    async reconcileEffectiveControlState(proc, actor) {
+        const stateResponse = await this.pool.sendRpcChecked(proc, { type: "get_state" });
+        this.publishEffectiveControlState(actor, stateResponse.data);
+    }
+    publishEffectiveControlState(actor, rpcState) {
+        const session = actor.session;
+        if (!session)
+            return;
+        const model = toCompactModelRef(rpcState?.model ?? {});
+        if (!model)
+            return;
+        const changed = session.setControlState(model, rpcState?.thinkingLevel ?? "off");
+        if (changed)
+            this.pushUpdateToSubscribers(actor.sessionPath, session);
+    }
+    buildPromptFailureMessage(err, proc, actor) {
         const raw = err instanceof Error ? err.message : String(err);
-        const session = this.attachedSessions.get(sessionPath);
-        const sessionError = session?.toState().error;
+        const sessionError = actor.session?.toState().error;
         const stderrTail = this.pool.getRecentStderr(proc, 12);
         let message = raw;
         if (raw.includes("Timeout waiting for RPC response to prompt")) {
@@ -658,74 +962,79 @@ export class WsHandler {
         }
         return message;
     }
-    injectSessionError(sessionPath, errorMessage) {
-        const session = this.attachedSessions.get(sessionPath);
+    injectSessionError(actor, errorMessage) {
+        const session = actor.session;
         if (!session)
             return;
         session.applyEvent({
             type: "turn_end",
             message: { role: "assistant", errorMessage },
         });
-        this.pushUpdateToSubscribers(sessionPath, session);
+        this.pushUpdateToSubscribers(actor.sessionPath, session);
+    }
+    async sendSteering(actor, message) {
+        if (!actor.isTurnActive || !actor.process) {
+            throw new Error("Session is not attached (agent not running)");
+        }
+        actor.enqueueSteering(message);
+        try {
+            await this.pool.sendRpc(actor.process, { type: "steer", message });
+        }
+        catch (error) {
+            actor.dequeueSteering(message);
+            throw error;
+        }
     }
     sleep(ms) {
         return new Promise((resolve) => setTimeout(resolve, ms));
     }
-    /** Busy + decommissioned processes are unavailable for reuse. */
-    getUnavailableProcesses() {
-        return new Set([...this.busyProcesses, ...this.decommissionProcesses]);
-    }
-    /**
-     * Create a SessionJsonl for a session path.
-     * Reads existing JSONL from disk to seed the initial messages.
-     */
-    createAttachedSession(sessionPath) {
+    /** Build the active materialized view owned by a SessionActor. */
+    createSessionState(sessionPath) {
         const { state } = readSessionFromDisk(sessionPath);
-        const session = new SessionJsonl({
+        return new SessionJsonl({
             messages: state.messages,
             model: state.model,
             thinkingLevel: state.thinkingLevel,
+            toolCallTimings: state.toolCallTimings,
         });
-        this.attachedSessions.set(sessionPath, session);
-        return session;
     }
-    /**
-     * Acquire a process for an existing session. Resolves the session's cwd
-     * from its JSONL header and gets a process from the matching pool.
-     */
-    async acquireForSession(sessionPath) {
-        const existing = this.lifecycle.getAttachedProcess(sessionPath);
-        if (existing)
-            return existing;
+    /** Acquire, switch, and transfer a process lease to a detached actor. */
+    async acquireForActor(actor) {
+        if (actor.process)
+            return actor.process;
+        const sessionPath = actor.sessionPath;
         const sessionCwd = getSessionCwd(sessionPath);
         const cwd = (sessionCwd && existsSync(sessionCwd)) ? sessionCwd : this.defaultCwd;
-        const proc = await this.acquireProcess(cwd);
-        this.busyProcesses.add(proc);
-        this.lifecycle.attach(sessionPath, proc);
-        // Create attached session if it doesn't exist yet
-        if (!this.attachedSessions.has(sessionPath)) {
-            this.createAttachedSession(sessionPath);
-        }
-        await this.pool.sendRpc(proc, { type: "switch_session", sessionPath });
+        const lease = await this.acquireProcess(cwd);
+        const proc = lease.process;
+        this.beginPendingExtensionStatusCapture(proc, sessionPath);
+        try {
+            await this.replacePiSession(proc, { type: "switch_session", sessionPath }, "switch_session");
+            actor.attach(lease, this.createSessionState(sessionPath));
+            this.commitPendingExtensionStatuses(proc, sessionPath);
+        }
+        catch (err) {
+            this.pendingExtensionStatuses.delete(proc);
+            if (actor.process === proc)
+                actor.detach();
+            else
+                lease.release();
+            throw err;
+        }
         console.log(`[ws] pi#${proc.id} attached to ${path.basename(sessionPath)} (cwd: ${cwd})`);
         return proc;
     }
-    /**
-     * Acquire a process for a given cwd. Spawns if needed.
-     */
+    /** Acquire an atomically reserved process lease for a cwd. */
     async acquireProcess(cwd) {
-        if (!this.piAvailable) {
+        if (!this.piAvailable)
             throw new Error(makePiNotFoundMessage(this.piLaunch.command));
-        }
         const timeoutMs = 60000;
         const start = Date.now();
         while (true) {
-            const unavailable = this.getUnavailableProcesses();
-            const proc = this.pool.acquire(cwd, unavailable);
-            if (proc)
-                return proc;
-            const evicted = this.pool.evictIdleDifferentCwd(cwd, unavailable);
-            if (evicted) {
+            const lease = this.pool.acquire(cwd);
+            if (lease)
+                return lease;
+            if (this.pool.evictIdleDifferentCwd(cwd)) {
                 await this.sleep(50);
                 continue;
             }
@@ -735,52 +1044,57 @@ export class WsHandler {
             await this.sleep(100);
         }
     }
-    releaseProcess(sessionPath) {
-        const proc = this.lifecycle.getAttachedProcess(sessionPath);
-        if (proc) {
-            const cleanup = this.procEventCleanup.get(proc);
-            if (cleanup) {
-                cleanup();
-                this.procEventCleanup.delete(proc);
+    async acquireAnyProcess() {
+        const existing = this.pool.acquireAny();
+        if (existing)
+            return existing;
+        return this.acquireProcess(this.defaultCwd);
+    }
+    releaseActor(actor, preserveLiveControls = true) {
+        const sessionPath = actor.sessionPath;
+        const proc = actor.process;
+        const liveState = actor.session?.toState();
+        if (proc)
+            this.pendingExtensionStatuses.delete(proc);
+        actor.detach();
+        // Read final messages from disk, but preserve the just-reconciled controls.
+        // This prevents JSONL flush timing from regressing the detach snapshot.
+        const disk = readSessionFromDisk(sessionPath);
+        if (liveState) {
+            if (preserveLiveControls) {
+                disk.state.model = liveState.model;
+                disk.state.thinkingLevel = liveState.thinkingLevel;
             }
+            disk.state.toolCallTimings = liveState.toolCallTimings;
+            disk.state.error = liveState.error;
         }
-        // Delete the attached session — no more in-memory state
-        this.attachedSessions.delete(sessionPath);
-        this.lifecycle.detach(sessionPath);
-        // Read final state from disk and push to subscribers
-        const { json, hash } = readSessionFromDisk(sessionPath);
+        const { json, hash } = serializeSessionState(disk.state);
         this.subscribedFileSizes.set(sessionPath, getSessionFileSize(sessionPath));
         this.pushSnapshotToSubscribers(sessionPath, json, hash);
-        if (proc) {
-            const shouldDecommission = this.decommissionProcesses.has(proc);
-            if (shouldDecommission) {
-                this.decommissionProcesses.delete(proc);
-                console.log(`[pool] Decommissioning pi#${proc.id} after completed turn`);
-                proc.process.kill("SIGTERM");
-            }
-            this.busyProcesses.delete(proc);
-        }
     }
-    getAnyProcess() {
-        let proc = this.pool.getAny(this.getUnavailableProcesses());
-        if (!proc) {
-            proc = this.pool.spawn(this.defaultCwd);
-        }
-        return proc;
+    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;
@@ -791,84 +1105,76 @@ 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;
         }
     }
-    setupTurnEventForwarding(proc, sessionPath, ws, turnId) {
-        const existingCleanup = this.procEventCleanup.get(proc);
-        if (existingCleanup) {
-            existingCleanup();
-            this.procEventCleanup.delete(proc);
-        }
-        // Capture the SessionJsonl object — if it gets deleted (detach),
-        // the handler becomes a no-op because we check for it.
-        const sessionRef = this.attachedSessions.get(sessionPath);
-        if (!sessionRef) {
-            console.error(`[turn] setupTurnEventForwarding called but no SessionJsonl for ${sessionPath}`);
-            return;
+    setupTurnEventForwarding(actor, proc, generation, turnId) {
+        const sessionPath = actor.sessionPath;
+        if (!actor.session || !actor.owns(proc, generation)) {
+            throw new Error(`setupTurnEventForwarding called without actor ownership for ${sessionPath}`);
         }
-        const lineHandler = (line) => {
-            let data;
-            try {
-                data = JSON.parse(line);
-            }
-            catch {
+        let hasStarted = false;
+        let hasSettled = false;
+        let resolveStarted;
+        let resolveEnded;
+        let resolveSettled;
+        const started = new Promise((resolve) => { resolveStarted = resolve; });
+        const ended = new Promise((resolve) => { resolveEnded = resolve; });
+        const settled = new Promise((resolve) => { resolveSettled = resolve; });
+        const eventHandler = (sourceProc, data) => {
+            if (sourceProc !== proc || data.type === "extension_ui_request")
                 return;
-            }
-            if (data.type === "response" && data.id)
-                return;
-            // Guard: if the attached session was deleted (turn ended),
-            // this handler is stale — skip.
-            const currentSession = this.attachedSessions.get(sessionPath);
-            if (currentSession !== sessionRef)
-                return;
-            // Apply event to the in-memory attached session
-            let changed = currentSession.applyEvent(data);
-            // After auto-compaction, the pi process rewrites the JSONL and calls
-            // replaceMessages() internally.  SessionJsonl doesn't know about this,
-            // so re-read the session from disk to pick up the compacted state.
-            if (data.type === "auto_compaction_end" && data.result) {
-                const { state } = readSessionFromDisk(sessionPath);
-                currentSession.replaceMessages(state.messages);
-                changed = true;
-            }
-            // Side-channel raw event for UI hooks (canvas/jsonl), not state updates
-            if (ws.readyState === WebSocket.OPEN) {
-                ws.send(JSON.stringify({ type: "agent_event", sessionPath, event: data }));
-            }
-            if (data.type === "message_end" && data.message?.role === "user") {
-                const text = typeof data.message.content === "string"
-                    ? data.message.content
-                    : (data.message.content || []).filter((c) => c.type === "text").map((c) => c.text).join(" ");
-                this.lifecycle.dequeueSteering(sessionPath, text);
-            }
-            // Push update to all subscribed clients
-            if (changed) {
-                this.pushUpdateToSubscribers(sessionPath, currentSession);
-            }
-            if (data.type === "agent_end") {
-                debugTurn("agent_end_received", { turnId, procId: proc.id, sessionPath });
-                this.lifecycle.clearSteering(sessionPath);
-                this.releaseProcess(sessionPath);
-            }
+            const replacementMessages = data.type === "compaction_end" && data.result
+                ? readSessionFromDisk(sessionPath).state.messages
+                : undefined;
+            void actor.applyProcessEvent(proc, generation, data, replacementMessages).then((result) => {
+                if (!result.accepted)
+                    return;
+                if (result.started) {
+                    hasStarted = true;
+                    resolveStarted();
+                }
+                if (result.ended)
+                    resolveEnded();
+                if (result.settled) {
+                    hasSettled = true;
+                    resolveSettled();
+                }
+                if (result.changed && actor.session) {
+                    this.pushUpdateToSubscribers(sessionPath, actor.session);
+                }
+                if (data.type === "agent_end") {
+                    debugTurn("agent_end_received", { turnId, procId: proc.id, sessionPath });
+                }
+            }).catch((error) => {
+                console.error(`[session-actor] Failed to apply ${data.type} for ${sessionPath}:`, error);
+            });
+        };
+        const cleanup = this.pool.subscribeEvents(eventHandler);
+        actor.setTurnEventCleanup(generation, cleanup);
+        return {
+            started,
+            ended,
+            settled,
+            hasStarted: () => hasStarted,
+            hasSettled: () => hasSettled,
         };
-        proc.rl.on("line", lineHandler);
-        const cleanup = () => proc.rl.removeListener("line", lineHandler);
-        this.procEventCleanup.set(proc, cleanup);
     }
 }