pipane 0.1.5 → 0.1.7

package/dist/server/server/server.js

@@ -9,10 +9,9 @@
  * switched to that session, and runs one turn. After the turn completes,
  * the process is released back to the pool.
  *
- * Session lifecycle is managed by SessionLifecycle (single source of truth
- * for session→process mappings and status). Process spawning and pooling
- * is handled by ProcessPool. The WsHandler routes WebSocket commands to
- * these modules.
+ * Each session is owned by a serialized SessionActor registered in
+ * SessionRegistry. ProcessPool owns exclusive process leases, and WsHandler
+ * only routes transport commands and publishes actor state.
  */
 import express from "express";
 import { createServer } from "node:http";
@@ -21,26 +20,40 @@ import path from "node:path";
 import { hostname } from "node:os";
 import { randomBytes } from "node:crypto";
 import { existsSync, readFileSync, watch } from "node:fs";
-import { WebSocketServer, WebSocket } from "ws";
-import { getAgentDir } from "@mariozechner/pi-coding-agent";
+import { WebSocketServer } from "ws";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { WS_PROTOCOL_VERSION } from "../shared/ws-protocol.js";
+import { BACKEND_PROTOCOL_VERSION } from "../shared/backend-protocol.js";
 import { resolvePiLaunch } from "./pi-launch.js";
 import { checkCommandAvailable, makePiNotFoundMessage } from "./pi-runtime.js";
 import { registerRestApi } from "./rest-api.js";
-import { SessionLifecycle } from "./session-lifecycle.js";
+import { SessionRegistry } from "./session-registry.js";
 import { ProcessPool } from "./process-pool.js";
 import { WsHandler } from "./ws-handler.js";
-import { LoadTraceStore } from "./load-trace-store.js";
 import { LocalSettingsStore } from "./local-settings.js";
-import { fetchLatestVersion, compareSemver } from "./update-check.js";
+import { resolveUsageExtensionPath } from "./bundled-extensions.js";
+import { UpdateManager } from "./update-manager.js";
+import { registerUpdateApi } from "./update-api.js";
+import { SessionPathGuard } from "./session-path.js";
+import { AuthGuard } from "./auth-guard.js";
+import { loadOrCreateBackendIdentity } from "./backend-identity.js";
+import { BackendRendezvousClient } from "./rendezvous-client.js";
+import { BackendWebRtcManager } from "./backend-webrtc.js";
+import { BackendTrustStore } from "./backend-trust-store.js";
+import { BackendConnectionAuthorizer } from "./backend-connection-authorizer.js";
+import { DataChannelFrameConnection } from "./frame-connection.js";
+import { routeFrameConnection } from "./frame-router.js";
+import { BackendProtocolHandler } from "./backend-protocol-handler.js";
+import { LocalBackendApi } from "./local-backend-api.js";
+import qrcode from "qrcode-terminal";
 const DEFAULT_PORT = process.env.NODE_ENV === "production" ? "8222" : "18111";
-const PORT = parseInt(process.env.PORT || DEFAULT_PORT, 10);
+const REQUESTED_PORT = parseInt(process.env.PORT || DEFAULT_PORT, 10);
+const INSTANCE_ID = process.env.PIPANE_INSTANCE_ID || null;
 const PI_CWD = process.env.PI_CWD || process.cwd();
 // Quiet mode: only show URLs unless --verbose or PIPANE_VERBOSE=1
 const VERBOSE = process.argv.includes("--verbose") || process.env.PIPANE_VERBOSE === "1";
 if (!VERBOSE) {
     const origLog = console.log;
-    const origError = console.error;
-    const origWarn = console.warn;
     // Suppress all console output; we'll use _log for the few lines we want
     console.log = () => { };
     console.error = () => { };
@@ -59,6 +72,10 @@ const PI_LAUNCH = resolvePiLaunch(PI_CLI);
 const PI_AVAILABLE = checkCommandAvailable(PI_LAUNCH.command);
 const PI_MAX_PROCESSES = parseInt(process.env.PI_MAX_PROCESSES || "24", 10);
 const PI_PREWARM_COUNT = parseInt(process.env.PI_PREWARM_COUNT || "2", 10);
+const USAGE_EXTENSION_ENABLED = process.env.PIPANE_USAGE_EXTENSION !== "0";
+const RENDEZVOUS_URL = process.env.PIPANE_RENDEZVOUS_URL;
+let rendezvousPairingRuntime;
+let registeredBackendId;
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // Read own version from package.json
 const PKG_JSON_PATH = path.resolve(__dirname, "../../../package.json");
@@ -71,45 +88,79 @@ const PKG_VERSION = (() => {
     }
 })();
 const PKG_NAME = "pipane";
-const AUTH_COOKIE_NAME = "pipane_auth";
-const AUTH_TOKEN = process.env.PIPANE_AUTH_TOKEN || randomBytes(24).toString("base64url");
-const PUBLIC_HOSTNAME = process.env.PI_PUBLIC_HOSTNAME || hostname();
-const AUTH_URL = `http://${PUBLIC_HOSTNAME}:${PORT}/auth?token=${encodeURIComponent(AUTH_TOKEN)}`;
-function parseCookies(header) {
-    const out = {};
-    if (!header)
-        return out;
-    for (const part of header.split(";")) {
-        const idx = part.indexOf("=");
-        if (idx <= 0)
-            continue;
-        const k = part.slice(0, idx).trim();
-        const v = part.slice(idx + 1).trim();
-        out[k] = decodeURIComponent(v);
+async function startRendezvousRegistration() {
+    if (!RENDEZVOUS_URL)
+        return;
+    const identity = loadOrCreateBackendIdentity(process.env.PIPANE_BACKEND_IDENTITY_FILE);
+    const trustStore = new BackendTrustStore({ filePath: process.env.PIPANE_BACKEND_TRUST_FILE });
+    registeredBackendId = identity.backendId;
+    const client = new BackendRendezvousClient({
+        url: RENDEZVOUS_URL,
+        identity,
+        metadata: {
+            name: process.env.PIPANE_BACKEND_NAME || hostname(),
+            softwareVersion: PKG_VERSION,
+            protocolVersions: [WS_PROTOCOL_VERSION, BACKEND_PROTOCOL_VERSION],
+        },
+    });
+    client.onError((error) => {
+        console.warn("[rendezvous]", error instanceof Error ? error.message : error.message);
+    });
+    let peers;
+    client.onAuthorizationRevoked(({ accountId, deviceId }) => {
+        trustStore.applyRevocation(accountId, deviceId);
+        peers?.closeAuthorization(accountId, deviceId);
+    });
+    const backendId = await client.start();
+    const authorizer = new BackendConnectionAuthorizer(trustStore, client);
+    peers = new BackendWebRtcManager({
+        signaling: client,
+        identity,
+        ticketPublicKey: () => client.ticketPublicKey,
+        authorize: (context) => authorizer.authorize(context),
+        iceTransportPolicy: process.env.PIPANE_ICE_TRANSPORT_POLICY === "relay" ? "relay" : "all",
+    });
+    peers.onDataChannel(({ channel, deviceId }) => {
+        const routes = routeFrameConnection(new DataChannelFrameConnection(channel));
+        wsHandler.acceptAuthenticatedConnection(routes.application);
+        backendProtocolHandler.accept(routes.semantic, deviceId);
+    });
+    peers.onError((_connectionId, error) => console.warn("[webrtc]", error.message));
+    const appUrl = new URL(process.env.PIPANE_APP_URL || RENDEZVOUS_URL);
+    if (appUrl.protocol === "ws:")
+        appUrl.protocol = "http:";
+    if (appUrl.protocol === "wss:")
+        appUrl.protocol = "https:";
+    appUrl.pathname = `/backend/${backendId}`;
+    appUrl.search = "";
+    appUrl.hash = "";
+    log(`  Backend: ${backendId}`);
+    log(`  Web:     ${appUrl.toString()}`);
+    const createPairingUrl = async () => {
+        const pairing = trustStore.createPairing();
+        await client.openPairing(pairing.pairId, pairing.expiresAt);
+        const pairingUrl = new URL(appUrl);
+        pairingUrl.pathname = `/pair/${encodeURIComponent(pairing.pairId)}`;
+        pairingUrl.hash = new URLSearchParams({ backend: backendId, secret: pairing.secret }).toString();
+        return pairingUrl.toString();
+    };
+    rendezvousPairingRuntime = { createPairingUrl };
+    for (const pairing of trustStore.listActivePairings()) {
+        void client.openPairing(pairing.pairId, pairing.expiresAt).catch((error) => console.warn("[pairing]", error.message));
+    }
+    if (!trustStore.ownerAccountId || process.argv.includes("--pair")) {
+        const pairingUrl = await createPairingUrl();
+        log(`  Pair:    ${pairingUrl}`);
+        qrcode.generate(pairingUrl, { small: true }, (code) => log(code));
     }
-    return out;
-}
-function isLocalAddress(addr) {
-    if (!addr)
-        return false;
-    return addr === "127.0.0.1" || addr === "::1" || addr === "::ffff:127.0.0.1";
-}
-function isLocalRequest(req) {
-    if (process.env.PIPANE_DISABLE_LOCAL_BYPASS === "1")
-        return false;
-    return isLocalAddress(req.socket.remoteAddress);
-}
-function setAuthCookie(res) {
-    const secure = process.env.PIPANE_SECURE_COOKIE === "1" ? "; Secure" : "";
-    const maxAgeSeconds = 60 * 60 * 24 * 30;
-    res.setHeader("Set-Cookie", `${AUTH_COOKIE_NAME}=${encodeURIComponent(AUTH_TOKEN)}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${maxAgeSeconds}${secure}`);
-}
-function isAuthorizedRequest(req) {
-    if (isLocalRequest(req))
-        return true;
-    const cookies = parseCookies(req.headers.cookie);
-    return cookies[AUTH_COOKIE_NAME] === AUTH_TOKEN;
 }
+const AUTH_TOKEN = process.env.PIPANE_AUTH_TOKEN || randomBytes(24).toString("base64url");
+const PUBLIC_HOSTNAME = process.env.PI_PUBLIC_HOSTNAME || hostname();
+const authGuard = new AuthGuard({
+    token: AUTH_TOKEN,
+    disableLocalBypass: process.env.PIPANE_DISABLE_LOCAL_BYPASS === "1",
+    secureCookie: process.env.PIPANE_SECURE_COOKIE === "1",
+});
 // ============================================================================
 // Express + HTTP server
 // ============================================================================
@@ -140,76 +191,45 @@ const pingInterval = setInterval(() => {
     }
 }, WS_PING_INTERVAL);
 wss.on("close", () => { clearInterval(pingInterval); });
-app.get("/auth", (req, res) => {
-    const token = typeof req.query.token === "string" ? req.query.token : undefined;
-    if (isLocalRequest(req) || token === AUTH_TOKEN) {
-        setAuthCookie(res);
-        res.redirect("/");
-        return;
-    }
-    res.status(401).type("html").send("<h3>Unauthorized</h3><p>Invalid auth token.</p>");
+authGuard.register(app);
+// A harness can provide a unique ID and verify that it reached the child it
+// launched, rather than an unrelated process that happened to acquire a port.
+app.get("/api/debug/health", (_req, res) => {
+    res.json({ ok: true, instanceId: INSTANCE_ID, pid: process.pid });
 });
-app.use((req, res, next) => {
-    if (isAuthorizedRequest(req)) {
-        if (isLocalRequest(req)) {
-            setAuthCookie(res);
-        }
-        next();
+app.post("/api/pairing", async (_req, res) => {
+    res.setHeader("Cache-Control", "no-store");
+    if (!rendezvousPairingRuntime) {
+        res.status(503).json({ error: "Backend is not registered with rendezvous" });
         return;
     }
-    res.status(401).type("html").send("<h3>Unauthorized</h3><p>Open the one-time auth URL shown in the pipane terminal.</p>");
-});
-const traceStore = new LoadTraceStore();
-const localSettingsStore = new LocalSettingsStore();
-app.use((req, res, next) => {
-    const traceId = typeof req.headers["x-pi-trace-id"] === "string" ? req.headers["x-pi-trace-id"] : "";
-    if (!traceId) {
-        next();
-        return;
+    try {
+        res.json({ url: await rendezvousPairingRuntime.createPairingUrl() });
+    }
+    catch (error) {
+        res.status(500).json({ error: error instanceof Error ? error.message : String(error) });
     }
-    const start = performance.now();
-    res.on("finish", () => {
-        traceStore.record(traceId, {
-            ts: new Date().toISOString(),
-            source: "backend",
-            kind: "span",
-            name: `http ${req.method} ${req.path}`,
-            durationMs: Number((performance.now() - start).toFixed(2)),
-            attrs: {
-                statusCode: res.statusCode,
-            },
-        });
-    });
-    next();
 });
+const localSettingsStore = new LocalSettingsStore();
+const registry = new SessionRegistry();
+const SESSIONS_DIR = path.join(getAgentDir(), "sessions");
+const sessionPaths = new SessionPathGuard(SESSIONS_DIR);
 // Serve static files in production
 const clientDist = path.resolve(__dirname, "../../client");
 app.use(express.static(clientDist));
-// Register REST endpoints
-registerRestApi(app, {
-    traceStore,
-    localSettingsStore,
-    onLocalSettingsReloaded: () => {
-        wss.clients.forEach((client) => {
-            if (client.readyState === WebSocket.OPEN) {
-                client.send(JSON.stringify({
-                    type: "sessions_changed",
-                    file: "__local_settings__",
-                }));
-            }
-        });
-    },
-});
 // ============================================================================
 // Core modules
 // ============================================================================
-const lifecycle = new SessionLifecycle();
-// Resolve canvas extension path relative to project root
+// Resolve bundled extension entrypoints once at startup.
 const canvasExtension = path.resolve(__dirname, "../../../extensions/canvas.ts");
+const usageExtension = resolveUsageExtensionPath();
 const pool = new ProcessPool({
     command: PI_LAUNCH.command,
     baseArgs: () => {
         const args = [...PI_LAUNCH.baseArgs, "--mode", "rpc"];
+        if (USAGE_EXTENSION_ENABLED) {
+            args.push("-e", usageExtension);
+        }
         if (localSettingsStore.canvasEnabled) {
             args.push("-e", canvasExtension);
         }
@@ -219,12 +239,8 @@ const pool = new ProcessPool({
     maxProcesses: PI_MAX_PROCESSES,
     prewarmCount: PI_PREWARM_COUNT,
     onProcessExit: (proc) => {
-        // If the process was attached to a session, handle the crash
-        const sessionPath = lifecycle.getAttachedSessionForProcess(proc);
-        if (sessionPath) {
-            console.log(`[pool] pi#${proc.id} crashed while attached to ${path.basename(sessionPath)} — marking done`);
-            lifecycle.crash(sessionPath);
-        }
+        // WsHandler owns attached-session snapshots and listener bookkeeping.
+        wsHandler.handleProcessExit(proc);
         // Replenish the pool for the default cwd
         if (PI_AVAILABLE) {
             pool.prewarm(PI_CWD);
@@ -232,8 +248,9 @@ const pool = new ProcessPool({
     },
 });
 const wsHandler = new WsHandler({
-    lifecycle,
+    registry,
     pool,
+    sessionPaths,
     defaultCwd: PI_CWD,
     piLaunch: PI_LAUNCH,
     ensurePool: () => {
@@ -241,11 +258,38 @@ const wsHandler = new WsHandler({
             pool.prewarm(PI_CWD);
         }
     },
-    isRequestAuthorized: (req) => isAuthorizedRequest(req),
-    traceStore,
+    isRequestAuthorized: (req) => authGuard.isAuthorizedRequest(req),
 });
 // Register WS handler
 wsHandler.register(wss);
+const updateManager = new UpdateManager({
+    pipaneVersion: PKG_VERSION,
+    pipanePackageName: PKG_NAME,
+    piLaunch: PI_LAUNCH,
+    cwd: PI_CWD,
+    onPiRuntimeChanged: async () => {
+        pool.decommissionAll();
+        if (wsHandler.isPiAvailable)
+            await pool.prewarm(PI_CWD);
+    },
+});
+registerUpdateApi(app, updateManager);
+const backendApi = new LocalBackendApi({
+    localSettingsStore,
+    sessionPaths,
+    backendId: () => registeredBackendId,
+    updateManager,
+    runSessionMutation: (sessionPath, operation, mutation) => {
+        const actor = registry.get(sessionPath);
+        return actor.enqueue(operation, async () => {
+            actor.assertAvailable(operation);
+            await mutation();
+        });
+    },
+    onLocalSettingsReloaded: () => wsHandler.notifySessionsChanged("__local_settings__"),
+});
+registerRestApi(app, { api: backendApi });
+const backendProtocolHandler = new BackendProtocolHandler(backendApi);
 // ============================================================================
 // Debug endpoints
 // ============================================================================
@@ -304,7 +348,6 @@ setInterval(tick, 1000); tick();
 // ============================================================================
 // Sessions Directory Watcher
 // ============================================================================
-const SESSIONS_DIR = path.join(getAgentDir(), "sessions");
 function startSessionsWatcher() {
     if (!existsSync(SESSIONS_DIR)) {
         console.log(`Sessions dir does not exist yet: ${SESSIONS_DIR}`);
@@ -320,18 +363,10 @@ function startSessionsWatcher() {
             clearTimeout(debounceTimer);
         debounceTimer = setTimeout(() => {
             const fullPath = path.join(SESSIONS_DIR, lastChangedFile);
-            // Notify the message cache — it will re-read from disk if changed
-            // and push session_messages to the subscribed client if needed.
+            // Re-read detached session state and push it to active subscribers.
             wsHandler.notifySessionFileChanged(fullPath);
-            // Also notify all WS clients about the file change (for sidebar refresh)
-            wss.clients.forEach((client) => {
-                if (client.readyState === WebSocket.OPEN) {
-                    client.send(JSON.stringify({
-                        type: "sessions_changed",
-                        file: fullPath,
-                    }));
-                }
-            });
+            // Notify every local WebSocket and authenticated DataChannel client.
+            wsHandler.notifySessionsChanged(fullPath);
         }, 300);
     });
     console.log(`Watching sessions directory: ${SESSIONS_DIR}`);
@@ -348,7 +383,13 @@ if (PI_AVAILABLE) {
 else {
     console.log(`[pi] ${makePiNotFoundMessage(PI_LAUNCH.command)}`);
 }
-server.listen(PORT, async () => {
+server.listen(REQUESTED_PORT, () => {
+    void startRendezvousRegistration().catch((error) => {
+        console.warn("[rendezvous] registration stopped:", error);
+    });
+    const address = server.address();
+    const port = address && typeof address !== "string" ? address.port : REQUESTED_PORT;
+    const authUrl = `http://${PUBLIC_HOSTNAME}:${port}/auth?token=${encodeURIComponent(AUTH_TOKEN)}`;
     log("");
     log("        _                        ");
     log("  _ __ (_)_ __   __ _ _ __   ___ ");
@@ -358,18 +399,31 @@ server.listen(PORT, async () => {
     log(" |_|     |_|                      ");
     log(`  v${PKG_VERSION}`);
     log("");
-    log(`  Local:  http://localhost:${PORT}`);
-    log(`  Remote: ${AUTH_URL}`);
+    log(`  Local:  http://localhost:${port}`);
+    log(`  Remote: ${authUrl}`);
     if (!process.env.PIPANE_AUTH_TOKEN) {
         log(`\n  Auth token is random and changes on restart.`);
         log(`  Set PIPANE_AUTH_TOKEN to use a fixed token.`);
     }
     log("");
-    // Non-blocking update check
-    const latest = await fetchLatestVersion(PKG_NAME);
-    if (latest && compareSemver(PKG_VERSION, latest) < 0) {
-        log(`  Update available: v${PKG_VERSION} → v${latest}`);
-        log(`  Run \`npm install -g ${PKG_NAME}\` to upgrade.`);
-        log("");
-    }
+    // The same asynchronous check feeds the web UI and preserves terminal hints.
+    void updateManager.check().then(({ notices }) => {
+        for (const notice of notices) {
+            if (notice.target === "pipane") {
+                log(`  Update available: v${notice.currentVersion} → v${notice.latestVersion}`);
+                log(`  Open pipane in the browser to install it, or run \`npm install -g ${PKG_NAME}\`.`);
+            }
+            else if (notice.target === "pi") {
+                log(`  Pi update available: v${notice.currentVersion} → v${notice.latestVersion}`);
+                log("  Open pipane in the browser to install it, or run `pi update --self`.");
+            }
+            else if (notice.packages?.length) {
+                log(`  Pi package updates available: ${notice.packages.join(", ")}`);
+                log("  Open pipane in the browser to install them, or run `pi update --extensions`.");
+            }
+            log("");
+        }
+    }).catch((error) => {
+        console.warn("[updates] Update check failed:", error);
+    });
 });

package/dist/server/server/session-actor.js

@@ -0,0 +1,202 @@
+const LEGAL_TRANSITIONS = {
+    detached: ["attaching"],
+    attaching: ["ready", "failed", "releasing"],
+    ready: ["starting", "releasing", "failed"],
+    starting: ["running", "settling", "releasing", "failed"],
+    running: ["settling", "releasing", "failed"],
+    settling: ["releasing", "failed"],
+    releasing: ["detached"],
+    failed: ["releasing"],
+};
+/**
+ * Serialized owner of one session's mutable runtime state.
+ *
+ * Long-running turns do not hold the command mailbox: prompt startup commits the
+ * `starting` phase and returns, Pi events are enqueued as internal commands, and
+ * final settlement is enqueued separately. This leaves steer/abort responsive
+ * while preventing compact/fork/rename from overlapping the turn.
+ */
+export class SessionActor {
+    sessionPath;
+    _phase = "detached";
+    _lease;
+    _session;
+    _turnGeneration = 0;
+    _steeringQueue = [];
+    _turnEventCleanup;
+    commandTail = Promise.resolve();
+    emitEvent;
+    constructor(sessionPath, emitEvent) {
+        this.sessionPath = sessionPath;
+        this.emitEvent = emitEvent;
+    }
+    get phase() { return this._phase; }
+    get process() { return this._lease?.process; }
+    get session() { return this._session; }
+    get turnGeneration() { return this._turnGeneration; }
+    get steeringQueue() { return this._steeringQueue; }
+    get isAttached() { return this._lease !== undefined; }
+    get isTurnActive() {
+        return this._phase === "starting" || this._phase === "running" || this._phase === "settling";
+    }
+    /** Serialize one command or internal event for this session. */
+    enqueue(operation, fn) {
+        const run = this.commandTail.then(fn);
+        this.commandTail = run.then(() => undefined, () => undefined);
+        return run.catch((error) => {
+            if (error instanceof Error) {
+                error.message = `[${operation}] ${error.message}`;
+            }
+            throw error;
+        });
+    }
+    assertAvailable(operation) {
+        if (this.isTurnActive) {
+            throw new Error(`Cannot ${operation} while session turn is ${this._phase}`);
+        }
+        if (this._phase !== "detached" && this._phase !== "ready") {
+            throw new Error(`Cannot ${operation} while session is ${this._phase}`);
+        }
+    }
+    attach(lease, session) {
+        if (this._phase !== "detached" || this._lease) {
+            throw new Error(`Session is already owned in phase ${this._phase}`);
+        }
+        this.transition("attaching");
+        this._lease = lease;
+        this._session = session;
+        this.transition("ready");
+        this.emitEvent({ type: "attached", proc: lease.process });
+    }
+    beginTurn() {
+        if (this._phase !== "ready" || !this._lease || !this._session) {
+            throw new Error(`Cannot start turn while session is ${this._phase}`);
+        }
+        this._turnGeneration += 1;
+        this.transition("starting");
+        return this._turnGeneration;
+    }
+    setTurnEventCleanup(generation, cleanup) {
+        if (generation !== this._turnGeneration || !this.isTurnActive) {
+            cleanup();
+            return;
+        }
+        this._turnEventCleanup?.();
+        this._turnEventCleanup = cleanup;
+    }
+    owns(proc, generation) {
+        return this.process === proc && (generation === undefined || generation === this._turnGeneration);
+    }
+    async applyProcessEvent(proc, generation, event, replacementMessages) {
+        return this.enqueue("process event", () => {
+            if (!this.owns(proc, generation) || !this._session) {
+                return { accepted: false, changed: false, started: false, ended: false, settled: false };
+            }
+            let started = false;
+            let ended = false;
+            let settled = false;
+            if (event.type === "agent_start") {
+                started = true;
+                if (this._phase === "starting")
+                    this.transition("running");
+            }
+            if (event.type === "agent_end") {
+                ended = true;
+                if (this._phase === "starting" || this._phase === "running")
+                    this.transition("settling");
+                this.clearSteering();
+            }
+            if (event.type === "agent_settled") {
+                started = true;
+                ended = true;
+                settled = true;
+                if (this._phase === "starting" || this._phase === "running")
+                    this.transition("settling");
+            }
+            let changed = this._session.applyEvent(event);
+            if (replacementMessages) {
+                this._session.replaceMessages(replacementMessages);
+                changed = true;
+            }
+            if (event.type === "message_end" && event.message?.role === "user") {
+                const text = typeof event.message.content === "string"
+                    ? event.message.content
+                    : (event.message.content || [])
+                        .filter((content) => content.type === "text")
+                        .map((content) => content.text)
+                        .join(" ");
+                this.dequeueSteering(text);
+            }
+            return { accepted: true, changed, started, ended, settled };
+        });
+    }
+    enqueueSteering(message) {
+        this._steeringQueue = [...this._steeringQueue, message];
+        this.syncSteeringQueue();
+    }
+    removeSteeringByIndex(index) {
+        if (index < 0 || index >= this._steeringQueue.length)
+            return false;
+        this._steeringQueue = this._steeringQueue.filter((_, itemIndex) => itemIndex !== index);
+        this.syncSteeringQueue();
+        return true;
+    }
+    dequeueSteering(text) {
+        const index = this._steeringQueue.indexOf(text);
+        if (index === -1)
+            return false;
+        this._steeringQueue = this._steeringQueue.filter((_, itemIndex) => itemIndex !== index);
+        this.syncSteeringQueue();
+        return true;
+    }
+    clearSteering() {
+        if (this._steeringQueue.length === 0)
+            return;
+        this._steeringQueue = [];
+        this.syncSteeringQueue();
+    }
+    markFailed() {
+        if (this._phase === "detached" || this._phase === "releasing" || this._phase === "failed")
+            return;
+        this.transition("failed");
+    }
+    /**
+     * Release all runtime ownership. Safe to call once the actor command holding
+     * the current mutation reaches a terminal path.
+     */
+    detach() {
+        const lease = this._lease;
+        const liveSession = this._session;
+        if (!lease || !liveSession)
+            return undefined;
+        if (this._phase !== "releasing")
+            this.transition("releasing");
+        this._turnEventCleanup?.();
+        this._turnEventCleanup = undefined;
+        if (this._steeringQueue.length > 0) {
+            this._steeringQueue = [];
+            this.emitEvent({ type: "steering_queue_update", queue: [] });
+        }
+        const proc = lease.process;
+        this._lease = undefined;
+        this._session = undefined;
+        lease.release();
+        this.transition("detached");
+        this.emitEvent({ type: "detached", proc });
+        return { proc, liveSession };
+    }
+    syncSteeringQueue() {
+        if (this._session)
+            this._session.steeringQueue = [...this._steeringQueue];
+        this.emitEvent({ type: "steering_queue_update", queue: [...this._steeringQueue] });
+    }
+    transition(next) {
+        if (next === this._phase)
+            return;
+        if (!LEGAL_TRANSITIONS[this._phase].includes(next)) {
+            throw new Error(`Illegal session transition ${this._phase} -> ${next}`);
+        }
+        this._phase = next;
+        this.emitEvent({ type: "phase_change", phase: next });
+    }
+}