tmux-ide 2.7.0 → 2.9.0-beta.5

package/packages/daemon/dist/lib/daemon-embed.js

@@ -13,25 +13,73 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 import { execFileSync } from "node:child_process";
-import { randomBytes } from "node:crypto";
+import { randomBytes, randomUUID } from "node:crypto";
+import { createWriteStream } from "node:fs";
 import { createServer } from "node:http";
 import { createRequire } from "node:module";
+import { performance } from "node:perf_hooks";
 import { WebSocket, WebSocketServer } from "ws";
-import { computeAgentStates, computePortPanes } from "./session-monitor.js";
+import { ownerBearerMatches } from "../command-center/owner-authority.js";
+import { DAEMON_WIRE_PROTOCOL_VERSION, DaemonInstanceIdentitySchemaZ, PANE_STREAM_REDEEM_PATH, PaneStreamLoopbackWebSocketUrlSchemaZ, TERMINAL_ATTACHMENT_REDEEM_PATH, TerminalAttachmentLoopbackWebSocketUrlSchemaZ, } from "@tmux-ide/contracts";
+import { classifySessionInspectionError, DaemonSessionMonitor, execTmuxAsync, isConfirmedMissingTmuxTarget, parseDaemonMonitorPanes, readPortProcessFactsAsync, } from "./daemon-session-monitor.js";
 import { DaemonShutdownError, DaemonStartupError } from "./errors.js";
 import { handlePtyWebSocket, shutdownPtyBridges } from "../server/ws-route.js";
-import { handleWsEventsConnection } from "../command-center/ws-events.js";
+import { broadcastInteractionReceipt, broadcastResourceChanged, handleWsEventsConnection, setFleetFactsObserverDiagnostics, setFleetFactsTmuxRunner, shutdownWsEventObservation, } from "../command-center/ws-events.js";
 import { setRemoteAccessRestartBackend } from "../command-center/actions/handlers/app-set-remote-access.js";
 import { setDaemonShutdownBackend } from "../command-center/actions/handlers/daemon-shutdown.js";
 import { readAppSettings } from "./app-settings.js";
-import { getDefaultWorkspaceRegistry } from "./workspace-registry.js";
+import { getDefaultWorkspaceRegistry, readWorkspaceRegistrySessionInventory, WORKSPACE_REGISTRY_TMUX_TIMEOUT_MS, } from "./workspace-registry.js";
+import { createPinnedWorkspaceTmuxRunner, resolveWorkspacePaneTmuxAuthority, WorkspacePaneCreationAuthority, } from "./workspace-pane-creation.js";
+import { discoverLiveSessionSummaries, readAdoptedFleet } from "../command-center/discovery.js";
+import { WorkspaceOpenAuthority } from "./workspace-open.js";
+import { WorkspacePromotionAuthority } from "./workspace-promotion.js";
+import { WorkspaceOpenHandoffCoordinator } from "./workspace-open-handoff.js";
+import { FleetLifecycleAuthority } from "./fleet-lifecycle-authority.js";
+import { AppWindowMutationAuthority } from "./app-window-mutation.js";
+import { WorkspaceMultiplexerAuthority } from "./workspace-multiplexer-verbs.js";
+import { TmuxExternalInteractionObserver } from "./tmux-external-interaction-observer.js";
+import { createNativeTerminalAttachmentRuntime, WorkspaceTerminalInventoryRuntime, } from "../terminal/attachments/native-runtime.js";
+import { createTmuxAgentStatusProbe } from "../terminal/attachments/agent-status-probe.js";
+import { attachTerminalAttachmentWebSocket, } from "../server/terminal-attachment-upgrade.js";
+import { attachPaneStreamWebSocket, } from "../server/pane-stream-upgrade.js";
+import { createPaneStreamRuntime, } from "../terminal/pane-stream/runtime.js";
+import { SessionRuntimeRegistry } from "../terminal/session-runtime/registry.js";
+import { createSessionRuntimeObservability } from "../terminal/session-runtime/runtime-observability.js";
+import { createSessionRuntimeMultiplexerBackend } from "../terminal/session-runtime/multiplexer-backend.js";
+import { PaneSourceCredentialAuthority, reconcilePaneSourceCredentialsAtStartup, } from "./pane-source-credentials.js";
 import { setActivationBackend } from "./active-projects.js";
-import { clearCanonicalDaemonInfo, isCanonicalDaemonAlive, readCanonicalDaemonInfo, writeCanonicalDaemonInfo, } from "./canonical-daemon.js";
+import { readOrMintEnvironmentId } from "./environment-identity.js";
+import { canonicalDaemonUrl, clearCanonicalDaemonInfoIfOwned, clearCanonicalDaemonInfoIfUnchanged, inspectCanonicalDaemonInfo, isCanonicalDaemonAlive, isCanonicalDaemonRecordOwnerProvenDead, probeCanonicalDaemonHealth, probeCanonicalDaemonIdentity, releaseCanonicalDaemonClaim, tryAcquireCanonicalDaemonClaim, writeCanonicalDaemonInfo, } from "./canonical-daemon.js";
 const requireFromHere = createRequire(import.meta.url);
 const DEFAULT_HOSTNAME = "127.0.0.1";
 const DEFAULT_GRACEFUL_MS = 2000;
-const MONITOR_INTERVAL_MS = 1000;
 const EMBEDDED_SESSION_NAME = "__embedded__";
+const TAKEOVER_TIMEOUT_MS = 10_000;
+const TAKEOVER_POLL_MS = 50;
+const TAKEOVER_DEADLINE_TEST_OVERRIDE = Symbol.for("tmux-ide.daemon-embed.takeover-deadline-ms.test-only");
+function loadBundledPackage() {
+    return requireFromHere("../../package.json");
+}
+/**
+ * Resolve diagnostic version metadata without making daemon startup depend on
+ * package.json being present next to a bundled executable.
+ */
+export function resolveDaemonProductVersion(explicit, loadPackage = loadBundledPackage) {
+    if (typeof explicit === "string" && explicit.trim().length > 0)
+        return explicit.trim();
+    try {
+        const pkg = loadPackage();
+        if (pkg && typeof pkg === "object" && "version" in pkg) {
+            const version = pkg.version;
+            if (typeof version === "string" && version.trim().length > 0)
+                return version.trim();
+        }
+    }
+    catch {
+        // Bundled/single-file hosts may have no package.json at this relative path.
+    }
+    return "0.0.0";
+}
 function tmux(...args) {
     return execFileSync("tmux", args, {
         encoding: "utf-8",
@@ -41,6 +89,7 @@ function tmux(...args) {
         // child spawn fails with EBADF. The visible symptom is sessionExists()
         // returning false → stopSelf → ghost daemon.
         stdio: ["ignore", "pipe", "pipe"],
+        timeout: 2_000,
     }).trim();
 }
 function tmuxSilent(...args) {
@@ -51,9 +100,9 @@ function tmuxSilent(...args) {
         return "";
     }
 }
-function assertTmuxSession(sessionName) {
+function assertTmuxSession(sessionName, runTmux = (args) => tmux(...args)) {
     try {
-        tmux("has-session", "-t", sessionName);
+        runTmux(["has-session", "-t", sessionName]);
     }
     catch (err) {
         throw new DaemonStartupError(`tmux session "${sessionName}" does not exist`, "tmux_session_missing", { cause: err });
@@ -64,6 +113,50 @@ function validatePort(port) {
         throw new DaemonStartupError(`Invalid daemon port: ${port}`, "port_invalid");
     }
 }
+/**
+ * Renderer descriptors are always local capabilities, even when the HTTP
+ * server listens on a wildcard. Explicit remote-only binds are deliberately
+ * unsupported rather than leaking an unreachable or remotely addressable URL.
+ */
+export function terminalAttachmentWebSocketUrl(bindHostname, port) {
+    const descriptorHostname = bindHostname === "0.0.0.0" ? "127.0.0.1" : bindHostname === "::" ? "::1" : bindHostname;
+    if (!["127.0.0.1", "localhost", "::1"].includes(descriptorHostname)) {
+        throw new TypeError("Terminal attachment listener must include a canonical loopback address.");
+    }
+    return TerminalAttachmentLoopbackWebSocketUrlSchemaZ.parse(canonicalDaemonUrl("ws", descriptorHostname, port, TERMINAL_ATTACHMENT_REDEEM_PATH));
+}
+/** Pane-stream descriptors share the loopback-only discipline above. */
+export function paneStreamWebSocketUrl(bindHostname, port) {
+    const descriptorHostname = bindHostname === "0.0.0.0" ? "127.0.0.1" : bindHostname === "::" ? "::1" : bindHostname;
+    if (!["127.0.0.1", "localhost", "::1"].includes(descriptorHostname)) {
+        throw new TypeError("Pane-stream listener must include a canonical loopback address.");
+    }
+    return PaneStreamLoopbackWebSocketUrlSchemaZ.parse(canonicalDaemonUrl("ws", descriptorHostname, port, PANE_STREAM_REDEEM_PATH));
+}
+/**
+ * Start both direct-terminal retirement barriers before awaiting either one.
+ * The runtime call closes admission and PTYs; the boundary call detaches the
+ * upgrade listener. Returning failures lets the outer daemon shutdown keep
+ * retiring legacy transports, HTTP, and canonical publication.
+ */
+export async function retireTerminalAttachmentTransport(runtime, boundary) {
+    let runtimeDisposal;
+    try {
+        runtimeDisposal = runtime?.dispose() ?? Promise.resolve();
+    }
+    catch (error) {
+        runtimeDisposal = Promise.reject(error);
+    }
+    let boundaryClose;
+    try {
+        boundaryClose = boundary.close();
+    }
+    catch (error) {
+        boundaryClose = Promise.reject(error);
+    }
+    const results = await Promise.allSettled([runtimeDisposal, boundaryClose]);
+    return results.flatMap((result) => (result.status === "rejected" ? [result.reason] : []));
+}
 async function pickFreePort(hostname) {
     const probe = createServer();
     return await new Promise((resolve, reject) => {
@@ -80,50 +173,6 @@ async function pickFreePort(hostname) {
         });
     });
 }
-function sessionExists(sessionName) {
-    try {
-        tmux("has-session", "-t", sessionName);
-        return "yes";
-    }
-    catch (err) {
-        const msg = err.message ?? "";
-        const code = err.code;
-        // Spawn-level failures (EBADF, EAGAIN, etc.) are transient OS issues,
-        // not "session is gone" signals. Same for non-zero exits without stderr
-        // — `has-session` returns 1 only when the session is genuinely missing,
-        // and tmux always writes to stderr in that case.
-        if (code === "EBADF" ||
-            code === "EAGAIN" ||
-            code === "EMFILE" ||
-            code === "ENFILE" ||
-            msg.includes("EBADF") ||
-            msg.includes("EAGAIN")) {
-            console.error("[daemon] sessionExists transient spawn error:", msg);
-            return "unknown";
-        }
-        return "no";
-    }
-}
-function hasClients() {
-    return tmuxSilent("list-clients").length > 0;
-}
-function listPanes(sessionName) {
-    const raw = tmuxSilent("list-panes", "-t", sessionName, "-F", "#{pane_id}\t#{pane_pid}\t#{pane_current_command}\t#{pane_title}\t#{@ide_role}\t#{@ide_type}\t#{@ide_name}");
-    if (!raw)
-        return [];
-    return raw.split("\n").map((line) => {
-        const [id, pid, cmd, title, role, type, name] = line.split("\t");
-        return {
-            id: id,
-            pid: pid,
-            cmd,
-            title,
-            role: role || undefined,
-            type: type || undefined,
-            name: name || undefined,
-        };
-    });
-}
 function bearerToken(authHeader) {
     const value = Array.isArray(authHeader) ? authHeader[0] : authHeader;
     if (!value?.startsWith("Bearer "))
@@ -172,7 +221,7 @@ function rejectUpgradeWithPolicy(wss, req, socket, head) {
         ws.close(1008, "Remote access token required");
     });
 }
-function attachWebSockets(server, opts = {}) {
+function attachWebSockets(server, opts) {
     const eventsWss = new WebSocketServer({ noServer: true });
     const ptyWss = new WebSocketServer({ noServer: true });
     const clients = new Set();
@@ -191,7 +240,11 @@ function attachWebSockets(server, opts = {}) {
         if (pathname === "/ws/events") {
             eventsWss.handleUpgrade(req, socket, head, (ws) => {
                 track(ws);
-                handleWsEventsConnection(ws);
+                const requestUrl = new URL(req.url ?? "/ws/events", "http://daemon.local");
+                handleWsEventsConnection(ws, opts.daemonIdentity, {
+                    mode: requestUrl.searchParams.get("mode") === "semantic" ? "semantic" : "legacy",
+                    ownerAuthorized: ownerBearerMatches(req.headers.authorization, opts.ownerToken ?? null),
+                });
             });
             return;
         }
@@ -242,64 +295,155 @@ function delay(ms) {
 function generateLocalBypassToken() {
     return randomBytes(32).toString("base64url");
 }
-function probeHostname(bindHostname) {
-    return bindHostname === "0.0.0.0" ? "127.0.0.1" : bindHostname;
-}
-function timeoutSignal(ms) {
+function createTakeoverDeadline(timeoutMs) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        throw new TypeError("Takeover deadline must be a positive finite duration.");
+    }
     const controller = new AbortController();
-    setTimeout(() => controller.abort(), ms).unref?.();
-    return controller.signal;
+    const expiresAt = performance.now() + timeoutMs;
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    timer.unref?.();
+    return {
+        signal: controller.signal,
+        expiresAt,
+        remainingMs: () => Math.max(0, expiresAt - performance.now()),
+        dispose: () => clearTimeout(timer),
+    };
 }
-async function healthGone(port, bindHostname) {
-    try {
-        const res = await fetch(`http://${probeHostname(bindHostname)}:${port}/health`, {
-            signal: timeoutSignal(500),
-        });
-        return !res.ok;
+function takeoverTimeoutMs() {
+    const override = globalThis[TAKEOVER_DEADLINE_TEST_OVERRIDE];
+    return typeof override === "number" ? override : TAKEOVER_TIMEOUT_MS;
+}
+function throwTakeoverTimeout(message) {
+    throw new DaemonStartupError(message, "canonical_takeover_timeout");
+}
+function assertTakeoverDeadline(deadline, message) {
+    if (deadline.signal.aborted || deadline.remainingMs() <= 0)
+        throwTakeoverTimeout(message);
+}
+async function waitForTakeoverPoll(deadline) {
+    assertTakeoverDeadline(deadline, "Canonical daemon did not quiesce before the takeover deadline");
+    const waitMs = Math.min(TAKEOVER_POLL_MS, deadline.remainingMs());
+    await new Promise((resolve) => {
+        const timer = setTimeout(finish, waitMs);
+        const onAbort = () => finish();
+        function finish() {
+            clearTimeout(timer);
+            deadline.signal.removeEventListener("abort", onAbort);
+            resolve();
+        }
+        deadline.signal.addEventListener("abort", onAbort, { once: true });
+    });
+    assertTakeoverDeadline(deadline, "Canonical daemon did not quiesce before the takeover deadline");
+}
+function sameCanonicalInstance(left, right) {
+    return (left.pid === right.pid &&
+        left.port === right.port &&
+        left.protocolVersion === right.protocolVersion &&
+        left.instanceId === right.instanceId &&
+        left.startedAt === right.startedAt &&
+        left.bindHostname === right.bindHostname);
+}
+async function requestValidatedDaemonShutdown(info, deadline) {
+    const identity = await probeCanonicalDaemonIdentity(info, deadline.signal);
+    assertTakeoverDeadline(deadline, "Canonical daemon did not answer the takeover request before the takeover deadline");
+    if (!identity ||
+        identity.pid !== info.pid ||
+        identity.protocolVersion !== info.protocolVersion ||
+        identity.protocolVersion !== DAEMON_WIRE_PROTOCOL_VERSION ||
+        identity.instanceId !== info.instanceId ||
+        identity.startedAt !== info.startedAt) {
+        throw new DaemonStartupError("Canonical daemon identity changed before takeover", "canonical_takeover_identity_mismatch");
     }
-    catch {
-        return true;
+    const health = await probeCanonicalDaemonHealth(info, deadline.signal);
+    assertTakeoverDeadline(deadline, "Canonical daemon did not answer the takeover request before the takeover deadline");
+    if (!health ||
+        health.protocolVersion !== info.protocolVersion ||
+        health.protocolVersion !== DAEMON_WIRE_PROTOCOL_VERSION) {
+        throw new DaemonStartupError("Canonical daemon protocol or health is incompatible with takeover", "canonical_takeover_refused");
     }
-}
-async function requestDaemonShutdown(port, bindHostname) {
+    const current = inspectCanonicalDaemonInfo();
+    if (current.status !== "valid" || !sameCanonicalInstance(current.info, info)) {
+        throw new DaemonStartupError("Canonical daemon generation changed before takeover", "canonical_takeover_identity_mismatch");
+    }
+    const headers = { "Content-Type": "application/json" };
+    if (info.authToken)
+        headers.Authorization = `Bearer ${info.authToken}`;
+    let response;
     try {
-        await fetch(`http://${probeHostname(bindHostname)}:${port}/api/v2/action/daemon.shutdown`, {
+        response = await fetch(canonicalDaemonUrl("http", info.bindHostname, info.port, "/api/v2/action/daemon.shutdown"), {
             method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ reason: "takeover" }),
-            signal: timeoutSignal(1_000),
+            headers,
+            body: JSON.stringify({ reason: "takeover", expectedInstanceId: info.instanceId }),
+            signal: deadline.signal,
         });
     }
-    catch {
-        // The existing daemon may predate the action or be mid-shutdown. Polling
-        // and the final PID kill below handle both cases.
-    }
-}
-async function takeoverCanonicalDaemon(info) {
-    await requestDaemonShutdown(info.port, info.bindHostname);
-    const deadline = Date.now() + 10_000;
-    while (Date.now() < deadline) {
-        const current = readCanonicalDaemonInfo();
-        const fileGone = !current || current.pid !== info.pid || current.port !== info.port;
-        const serverGone = await healthGone(info.port, info.bindHostname);
-        if (fileGone && serverGone)
-            return;
-        await delay(150);
+    catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+            throw new DaemonStartupError("Canonical daemon did not answer the takeover request in time", "canonical_takeover_timeout", { cause: error });
+        }
+        throw new DaemonStartupError("Canonical daemon did not accept the takeover request", "canonical_takeover_refused", { cause: error });
     }
-    try {
-        process.kill(info.pid, "SIGTERM");
+    const envelope = (await response.json().catch(() => null));
+    assertTakeoverDeadline(deadline, "Canonical daemon did not answer the takeover request before the takeover deadline");
+    if (envelope?.error?.code === "daemon_instance_mismatch") {
+        throw new DaemonStartupError("Canonical daemon generation changed before shutdown", "canonical_takeover_identity_mismatch");
     }
-    catch {
-        // Already gone or not ours.
+    if (!response.ok || envelope?.ok !== true || envelope.result?.stopping !== true) {
+        throw new DaemonStartupError(`Canonical daemon refused takeover (HTTP ${response.status})`, "canonical_takeover_refused");
     }
-    await delay(500);
-    try {
-        process.kill(info.pid, "SIGKILL");
+}
+async function waitForTakeoverQuiescence(info, deadline) {
+    while (!deadline.signal.aborted) {
+        const current = inspectCanonicalDaemonInfo();
+        if (current.status === "valid" && !sameCanonicalInstance(current.info, info)) {
+            throw new DaemonStartupError("Another daemon generation won the takeover race", "canonical_already_running");
+        }
+        const recordOwnerGone = current.status === "missing" || (await isCanonicalDaemonRecordOwnerProvenDead(current));
+        const [identity, health] = await Promise.all([
+            probeCanonicalDaemonIdentity(info, deadline.signal),
+            probeCanonicalDaemonHealth(info, deadline.signal),
+        ]);
+        assertTakeoverDeadline(deadline, "Canonical daemon retained its generation after accepting takeover");
+        if (recordOwnerGone && identity === null && health === null)
+            return;
+        await waitForTakeoverPoll(deadline);
     }
-    catch {
-        // Already gone or not ours.
+    throwTakeoverTimeout("Canonical daemon retained its generation after accepting takeover");
+}
+async function acquireCanonicalDaemonClaimAfterTakeover(info, deadline) {
+    while (!deadline.signal.aborted) {
+        const current = inspectCanonicalDaemonInfo();
+        if (current.status === "valid" && !sameCanonicalInstance(current.info, info)) {
+            throw new DaemonStartupError("Another daemon generation won the takeover race", "canonical_already_running");
+        }
+        const attempt = tryAcquireCanonicalDaemonClaim();
+        if (attempt.status === "acquired") {
+            try {
+                await waitForTakeoverQuiescence(info, deadline);
+                return attempt.claim;
+            }
+            catch (error) {
+                releaseCanonicalDaemonClaim(attempt.claim);
+                throw error;
+            }
+        }
+        if (attempt.status === "invalid") {
+            throw new DaemonStartupError(`Canonical daemon claim is invalid: ${attempt.detail}`, "canonical_record_invalid");
+        }
+        await waitForTakeoverPoll(deadline);
+    }
+    throwTakeoverTimeout("Canonical daemon did not release its startup claim after accepting takeover");
+}
+function acquireCanonicalDaemonClaim() {
+    const attempt = tryAcquireCanonicalDaemonClaim();
+    if (attempt.status === "busy") {
+        throw new DaemonStartupError(`Canonical daemon startup is owned by PID ${attempt.owner.pid}`, "canonical_claim_busy");
+    }
+    if (attempt.status === "invalid") {
+        throw new DaemonStartupError(`Canonical daemon claim is invalid: ${attempt.detail}`, "canonical_record_invalid");
     }
-    clearCanonicalDaemonInfo();
+    return attempt.claim;
 }
 function closeWsGoingAway(ws) {
     const reason = Buffer.from("going away");
@@ -314,20 +458,22 @@ function closeWsGoingAway(ws) {
     }
     ws.close(1001, reason);
 }
-async function startHttpServer({ sessionName, requestedPort, bindHostname, dir, authToken, localBypassToken, silent, }) {
+async function startHttpServer({ sessionName, requestedPort, bindHostname, dir, authToken, localBypassToken, silent, readProjectAuth, daemonIdentity, workspacePaneCreationBackend, workspaceOpenBackend, workspaceOpenHandoffBackend, fleetLifecycleBackend, workspacePromotionBackend, appWindowMutationBackend, workspaceMultiplexerBackend, workspaceRegistry, terminalInventoryRuntime, getTerminalAttachmentRuntime, peekTerminalAttachmentRuntime, paneStreamRuntime, catalogLiveSessions, catalogFleet, }) {
     const { createApp } = await import("../command-center/server.js");
     const { getRequestListener } = await import(__rewriteRelativeImportExtension(requireFromHere.resolve("@hono/node-server"), true));
     const { AuthService } = await import("./auth/auth-service.js");
     const { AuthConfigSchema } = await import("./auth/types.js");
     let authConfig = AuthConfigSchema.parse({});
-    try {
-        const { readConfig } = await import("./yaml-io.js");
-        const { config } = readConfig(dir);
-        if (config.auth)
-            authConfig = AuthConfigSchema.parse(config.auth);
-    }
-    catch {
-        // Config not readable — use defaults.
+    if (readProjectAuth !== false) {
+        try {
+            const { resolveConfig } = await import("./resolved-config.js");
+            const { launchConfig } = await resolveConfig(dir);
+            if (launchConfig?.auth)
+                authConfig = AuthConfigSchema.parse(launchConfig.auth);
+        }
+        catch {
+            // Config not readable — use defaults.
+        }
     }
     const authService = new AuthService(authConfig.secret);
     const app = createApp({
@@ -337,52 +483,105 @@ async function startHttpServer({ sessionName, requestedPort, bindHostname, dir,
             bindHostname,
             token: authToken ?? null,
             localBypassToken: localBypassToken ?? null,
+            ownerToken: localBypassToken ?? null,
         },
+        daemonIdentity,
+        workspacePaneCreationBackend,
+        workspaceOpenBackend,
+        workspaceOpenHandoffBackend,
+        fleetLifecycleBackend,
+        workspacePromotionBackend,
+        appWindowMutationBackend,
+        // Named in this function's parameter type since the verb routes shipped and
+        // never forwarded, so every multiplexer verb answered "not available from
+        // this daemon" in every real process. Only the in-test dispatcher, which is
+        // handed the authority directly, ever reached it.
+        workspaceMultiplexerBackend,
+        workspaceRegistry,
+        terminalAttachmentIssueBackend: {
+            issue: (request, context) => getTerminalAttachmentRuntime().admission.issue(request, context),
+        },
+        paneStreamIssueBackend: paneStreamRuntime.coordinator,
+        applicationShellInventoryBackend: terminalInventoryRuntime,
+        startupReadinessAttachmentBackend: terminalInventoryRuntime,
+        catalogLiveSessions,
+        catalogFleet,
     });
     app.get("/api/daemon/health", (c) => {
-        return c.json({ ok: true, session: sessionName });
+        return c.json({
+            ok: true,
+            session: sessionName,
+            compatibilityTerminalAttachmentRuntimeConstructed: peekTerminalAttachmentRuntime() !== null,
+        });
     });
     const server = createServer(getRequestListener(app.fetch));
     const sockets = new Set();
     server.on("connection", (socket) => {
         sockets.add(socket);
         socket.on("close", () => sockets.delete(socket));
+        // `upgrade` hands the raw TCP socket to our route boundaries. A route can
+        // deliberately decline an unrelated path, leaving no protocol-specific
+        // owner to observe a later peer reset. Keep error ownership at this common
+        // accepted-socket boundary so ECONNRESET is connection-local and can never
+        // terminate the canonical daemon during client/session teardown.
+        socket.on("error", () => sockets.delete(socket));
     });
     const { closeClients, closeServers: closeWsServers } = attachWebSockets(server, {
         authToken,
         localBypassToken,
         bindHostname,
+        daemonIdentity: DaemonInstanceIdentitySchemaZ.parse({
+            protocolVersion: DAEMON_WIRE_PROTOCOL_VERSION,
+            ...daemonIdentity,
+        }),
+        ownerToken: localBypassToken,
     });
-    await new Promise((resolve, reject) => {
-        const onError = (err) => {
-            server.off("listening", onListening);
-            if (err.code === "EADDRINUSE") {
-                reject(new DaemonStartupError(`Port ${requestedPort} is already in use`, "port_in_use", {
-                    cause: err,
-                }));
-            }
-            else {
-                reject(new DaemonStartupError(`Failed to bind daemon on port ${requestedPort}`, "bind_failed", {
-                    cause: err,
-                }));
-            }
-        };
-        const onListening = () => {
-            server.off("error", onError);
-            if (!silent) {
-                console.log(`[daemon] Command Center on http://${bindHostname}:${requestedPort} (session: ${sessionName})`);
-            }
-            resolve();
-        };
-        server.once("error", onError);
-        server.once("listening", onListening);
-        server.listen(requestedPort, bindHostname);
-    });
+    const terminalAttachmentBoundary = attachTerminalAttachmentWebSocket(server, (create) => (create ? getTerminalAttachmentRuntime() : peekTerminalAttachmentRuntime())?.admission ??
+        null);
+    const paneStreamBoundary = attachPaneStreamWebSocket(server, paneStreamRuntime.coordinator);
+    try {
+        await new Promise((resolve, reject) => {
+            const onError = (err) => {
+                server.off("listening", onListening);
+                if (err.code === "EADDRINUSE") {
+                    reject(new DaemonStartupError(`Port ${requestedPort} is already in use`, "port_in_use", {
+                        cause: err,
+                    }));
+                }
+                else {
+                    reject(new DaemonStartupError(`Failed to bind daemon on port ${requestedPort}`, "bind_failed", { cause: err }));
+                }
+            };
+            const onListening = () => {
+                server.off("error", onError);
+                if (!silent) {
+                    console.log(`[daemon] Command Center on http://${bindHostname}:${requestedPort} (session: ${sessionName})`);
+                }
+                resolve();
+            };
+            server.once("error", onError);
+            server.once("listening", onListening);
+            server.listen(requestedPort, bindHostname);
+        });
+    }
+    catch (error) {
+        await Promise.allSettled([
+            Promise.resolve().then(() => terminalAttachmentBoundary.close()),
+            Promise.resolve().then(() => paneStreamBoundary.close()),
+            Promise.resolve().then(() => closeClients()),
+            ...[...sockets].map((socket) => Promise.resolve().then(() => socket.destroy())),
+            ...(server.listening ? [waitForServerClose(server)] : []),
+            Promise.resolve().then(() => closeWsServers()),
+        ]);
+        throw error;
+    }
     return {
         server,
         sockets,
         closeClients,
         closeWsServers,
+        terminalAttachmentBoundary,
+        paneStreamBoundary,
     };
 }
 export async function startEmbeddedDaemon(opts) {
@@ -393,251 +592,756 @@ export async function startEmbeddedDaemon(opts) {
         ? appSettings.remoteAccess
         : null;
     const bindHostname = opts.bindHostname ?? opts.hostname ?? (persistedRemoteAccess ? "0.0.0.0" : DEFAULT_HOSTNAME);
-    const authToken = opts.authToken ?? persistedRemoteAccess?.token ?? null;
+    // Explicit null means "no auth". This is important for the native app's
+    // loopback-only `tmux-ide --headless` child: persisted remote-access settings
+    // must not silently change the process contract it requested.
+    const authToken = Object.prototype.hasOwnProperty.call(opts, "authToken")
+        ? (opts.authToken ?? null)
+        : (persistedRemoteAccess?.token ?? null);
     const localBypassToken = opts.localBypassToken ?? generateLocalBypassToken();
-    const existingCanonical = readCanonicalDaemonInfo();
-    if (existingCanonical) {
-        if (await isCanonicalDaemonAlive(existingCanonical)) {
-            if (opts.takeoverIfRunning) {
-                await takeoverCanonicalDaemon(existingCanonical);
+    let claim;
+    if (opts.takeoverIfRunning) {
+        const state = inspectCanonicalDaemonInfo();
+        if (state.status === "valid" && (await isCanonicalDaemonAlive(state.info))) {
+            const takeoverDeadline = createTakeoverDeadline(takeoverTimeoutMs());
+            try {
+                await requestValidatedDaemonShutdown(state.info, takeoverDeadline);
+                claim = await acquireCanonicalDaemonClaimAfterTakeover(state.info, takeoverDeadline);
             }
-            else {
-                throw new DaemonStartupError(`Canonical daemon is already running on port ${existingCanonical.port}`, "canonical_already_running");
+            finally {
+                takeoverDeadline.dispose();
             }
         }
         else {
-            clearCanonicalDaemonInfo();
+            claim = acquireCanonicalDaemonClaim();
         }
     }
-    if (!sessionless)
-        assertTmuxSession(sessionName);
-    const port = opts.port ?? (await pickFreePort(bindHostname));
-    validatePort(port);
-    const dir = process.cwd();
-    // Workspace registry: load + reconcile against live tmux sessions on
-    // startup. Backwards-compat: if TMUX_IDE_SESSION is set, auto-add it as
-    // a workspace so legacy single-session callers (pre-T068) keep working.
-    // The registry is the source of truth for /api/project/:name lookups.
-    const workspaceRegistry = getDefaultWorkspaceRegistry();
-    await workspaceRegistry.load();
-    const legacySession = process.env.TMUX_IDE_SESSION;
-    if (legacySession && !workspaceRegistry.has(legacySession)) {
-        try {
-            workspaceRegistry.add({
-                name: legacySession,
-                sessionName: legacySession,
-                projectDir: dir,
-            });
-        }
-        catch {
-            // Already added or persistence failed; non-fatal.
-        }
+    else {
+        claim = acquireCanonicalDaemonClaim();
     }
-    // Also register the explicit sessionName when the daemon is launched
-    // against a specific tmux session (e.g. `node daemon.ts new-name 6060`).
-    // Without this the operator has to POST /api/workspaces by hand before
-    // /api/sessions / /api/project/:name return anything — which was the
-    // dashboard's "terminal not connecting" symptom before this fix.
-    if (!sessionless &&
-        sessionName !== EMBEDDED_SESSION_NAME &&
-        !workspaceRegistry.has(sessionName)) {
-        try {
-            workspaceRegistry.add({
-                name: sessionName,
-                sessionName,
-                projectDir: dir,
-            });
-        }
-        catch {
-            // Already added or persistence failed; non-fatal.
-        }
-    }
-    const { server, sockets, closeClients, closeWsServers } = await startHttpServer({
-        sessionName,
-        requestedPort: port,
-        bindHostname,
-        dir,
-        authToken,
-        localBypassToken,
-        silent: opts.silent,
-    });
-    const pkg = requireFromHere("../../package.json");
-    writeCanonicalDaemonInfo({
-        pid: process.pid,
-        port,
-        version: pkg.version ?? "0.0.0",
-        startedAt: new Date().toISOString(),
-        bindHostname,
-        authToken,
-    });
-    let lastState = "";
-    let stopped = false;
-    let stopping = null;
-    let stopSelf = null;
-    const activeProjectStops = new Map();
-    // Track active projects so the session-control surface can open/close
-    // them. Orchestration moved out of tmux-ide (agent coordination lives in
-    // sfora.ai), so activation is now bookkeeping only.
-    const activateProjectOnDaemon = async (projectName, _options = {}) => {
-        if (!activeProjectStops.has(projectName)) {
-            activeProjectStops.set(projectName, { stop: () => undefined });
+    try {
+        const existingCanonical = inspectCanonicalDaemonInfo();
+        if (existingCanonical.status === "invalid") {
+            if (await isCanonicalDaemonRecordOwnerProvenDead(existingCanonical)) {
+                if (!clearCanonicalDaemonInfoIfUnchanged(existingCanonical, claim)) {
+                    throw new DaemonStartupError("Canonical daemon metadata changed while stale state was being removed", "canonical_record_invalid");
+                }
+            }
+            else {
+                throw new DaemonStartupError(`Canonical daemon metadata is ${existingCanonical.reason}: ${existingCanonical.detail}. ` +
+                    "Refusing to start another owner.", "canonical_record_invalid");
+            }
         }
-        return {
-            stop: async () => {
-                const current = activeProjectStops.get(projectName);
-                if (!current)
-                    return;
-                activeProjectStops.delete(projectName);
-                current.stop();
-            },
-        };
-    };
-    setActivationBackend({
-        activateProject: async (name, options) => {
-            await activateProjectOnDaemon(name, options);
-        },
-        deactivateProject: async (name) => {
-            const stop = activeProjectStops.get(name);
-            if (!stop)
-                return;
-            activeProjectStops.delete(name);
-            stop.stop();
-        },
-    });
-    const tick = () => {
-        if (sessionless)
-            return;
-        const session = sessionExists(sessionName);
-        if (session === "no") {
-            stopSelf?.();
-            return;
+        else if (existingCanonical.status === "valid") {
+            if (await isCanonicalDaemonAlive(existingCanonical.info)) {
+                throw new DaemonStartupError(`Canonical daemon is already running on port ${existingCanonical.info.port}`, "canonical_already_running");
+            }
+            else {
+                if (!clearCanonicalDaemonInfoIfUnchanged(existingCanonical, claim)) {
+                    throw new DaemonStartupError("Canonical daemon metadata changed while stale state was being removed", "canonical_already_running");
+                }
+            }
         }
-        if (session === "unknown") {
-            // Transient spawn failure — skip this tick rather than self-destruct.
-            return;
+        // Resolve both tmux selectors before any state read. Registry discovery,
+        // explicit-session validation, catalog reads and later mutations must all
+        // observe one daemon-generation authority rather than whichever server a
+        // caller's ambient TMUX/PATH happens to select.
+        const tmuxAuthority = resolveWorkspacePaneTmuxAuthority();
+        const catalogTmuxRunner = createPinnedWorkspaceTmuxRunner(tmuxAuthority);
+        const registryTmuxRunner = createPinnedWorkspaceTmuxRunner(tmuxAuthority, {
+            timeoutMs: WORKSPACE_REGISTRY_TMUX_TIMEOUT_MS,
+        });
+        if (!sessionless)
+            assertTmuxSession(sessionName, catalogTmuxRunner);
+        const port = opts.port ?? (await pickFreePort(bindHostname));
+        validatePort(port);
+        const dir = process.cwd();
+        const productVersion = resolveDaemonProductVersion(opts.productVersion);
+        const instanceId = randomUUID();
+        const startedAt = new Date().toISOString();
+        // Stable across restarts, unlike the per-process nonce above; minted once
+        // per daemon state home and re-minted only if its record disappears.
+        const environmentId = readOrMintEnvironmentId();
+        // Workspace registry: load + reconcile against live tmux sessions on
+        // startup. Backwards-compat: if TMUX_IDE_SESSION is set, auto-add it as
+        // a workspace so legacy single-session callers (pre-T068) keep working.
+        // The registry is the source of truth for /api/project/:name lookups.
+        const workspaceRegistry = getDefaultWorkspaceRegistry();
+        await workspaceRegistry.load(() => readWorkspaceRegistrySessionInventory(registryTmuxRunner));
+        const paneSourceCredentials = new PaneSourceCredentialAuthority({
+            run: (args) => tmuxSilent(...args),
+            runAsync: (args, signal) => execTmuxAsync(args, signal),
+        });
+        const legacySession = process.env.TMUX_IDE_SESSION;
+        if (legacySession && !workspaceRegistry.has(legacySession)) {
+            try {
+                workspaceRegistry.add({
+                    name: legacySession,
+                    sessionName: legacySession,
+                    projectDir: dir,
+                });
+            }
+            catch {
+                // Already added or persistence failed; non-fatal.
+            }
         }
-        if (!hasClients())
-            return;
-        const panes = listPanes(sessionName);
-        if (panes.length === 0)
-            return;
-        const portPanes = computePortPanes(panes);
-        const agentStates = computeAgentStates(panes);
-        const stateKey = panes
-            .map((pane) => {
-            const portState = portPanes.has(pane.id) ? "1" : "0";
-            const agent = agentStates.get(pane.id) ?? "-";
-            const titleDrift = pane.name && pane.title !== pane.name ? "d" : "ok";
-            return `${pane.id}:${portState}:${agent}:${titleDrift}`;
-        })
-            .join("|");
-        if (stateKey === lastState)
-            return;
-        for (const pane of panes) {
-            const hasPort = portPanes.has(pane.id) ? "1" : "0";
-            const agent = agentStates.get(pane.id);
-            tmuxSilent("set-option", "-pqt", pane.id, "@has_port", hasPort);
-            tmuxSilent("set-option", "-pqt", pane.id, "@agent_busy", agent === "busy" ? "1" : "0");
-            tmuxSilent("set-option", "-pqt", pane.id, "@agent_idle", agent === "idle" ? "1" : "0");
-            if (pane.name && pane.title !== pane.name) {
-                tmuxSilent("select-pane", "-t", pane.id, "-T", pane.name);
+        // Also register the explicit sessionName when the daemon is launched
+        // against a specific tmux session (e.g. `node daemon.ts new-name 6060`).
+        // Without this the operator has to POST /api/workspaces by hand before
+        // /api/sessions / /api/project/:name return anything — which was the
+        // dashboard's "terminal not connecting" symptom before this fix.
+        if (!sessionless &&
+            sessionName !== EMBEDDED_SESSION_NAME &&
+            !workspaceRegistry.has(sessionName)) {
+            try {
+                workspaceRegistry.add({
+                    name: sessionName,
+                    sessionName,
+                    projectDir: dir,
+                });
+            }
+            catch {
+                // Already added or persistence failed; non-fatal.
             }
         }
-        tmuxSilent("refresh-client", "-S");
-        lastState = stateKey;
-    };
-    const monitorInterval = setInterval(tick, MONITOR_INTERVAL_MS);
-    const apiBaseUrl = `http://${bindHostname}:${port}`;
-    const wsUrl = `ws://${bindHostname}:${port}/ws/events`;
-    const handle = {
-        port,
-        apiBaseUrl,
-        wsUrl,
-        localBypassToken,
-        stop: async ({ gracefulMs = DEFAULT_GRACEFUL_MS } = {}) => {
-            if (stopped)
-                return;
-            if (stopping)
-                return stopping;
-            stopping = (async () => {
-                try {
-                    stopped = true;
-                    setActivationBackend(null);
-                    clearInterval(monitorInterval);
-                    const closePromise = waitForServerClose(server);
-                    closeClients();
-                    for (const stop of activeProjectStops.values()) {
-                        stop.stop();
-                    }
-                    activeProjectStops.clear();
-                    shutdownPtyBridges();
-                    await Promise.race([closePromise, delay(gracefulMs)]);
-                    for (const socket of sockets)
-                        socket.destroy();
-                    await Promise.race([closePromise.catch(() => undefined), delay(100)]);
-                    await closeWsServers();
-                    setRemoteAccessRestartBackend(null);
-                    setDaemonShutdownBackend(null);
-                }
-                catch (err) {
-                    throw new DaemonShutdownError("Daemon shutdown failed", { cause: err });
-                }
-                finally {
-                    clearCanonicalDaemonInfo();
+        await reconcilePaneSourceCredentialsAtStartup(paneSourceCredentials, workspaceRegistry.list().map((workspace) => workspace.sessionName));
+        const workspacePaneCreation = new WorkspacePaneCreationAuthority({
+            daemonInstanceId: instanceId,
+            registry: workspaceRegistry,
+            tmuxAuthority,
+        });
+        const workspaceOpen = new WorkspaceOpenAuthority({
+            daemonInstanceId: instanceId,
+            registry: workspaceRegistry,
+            tmuxAuthority,
+        });
+        const workspacePromotion = new WorkspacePromotionAuthority({
+            daemonInstanceId: instanceId,
+            registry: workspaceRegistry,
+            tmuxAuthority,
+        });
+        const fleetLifecycle = new FleetLifecycleAuthority({
+            daemonInstanceId: instanceId,
+            productVersion,
+            startedAt,
+            registry: workspaceRegistry,
+            runTmux: catalogTmuxRunner,
+            readFleet: () => readAdoptedFleet(workspaceRegistry, catalogTmuxRunner),
+        });
+        const appWindowMutation = new AppWindowMutationAuthority({
+            daemonInstanceId: instanceId,
+            registry: workspaceRegistry,
+        });
+        const workspaceMultiplexer = new WorkspaceMultiplexerAuthority({
+            daemonInstanceId: instanceId,
+            registry: workspaceRegistry,
+            tmuxAuthority,
+        });
+        let sessionRuntimeRegistry = null;
+        let workspaceOpenHandoff = null;
+        let terminalInventoryRuntime = null;
+        const externalInteractionObserver = new TmuxExternalInteractionObserver({
+            daemonInstanceId: instanceId,
+            internalReadOwnerToken: localBypassToken,
+            registry: workspaceRegistry,
+            tmuxAuthority,
+            onObserved: ({ workspaceName, semanticPaneId, operationKind, operationId }) => {
+                if (operationKind !== "workspace.pane.read")
+                    terminalInventoryRuntime?.invalidate();
+                if (operationId) {
+                    const consumed = sessionRuntimeRegistry?.observeTmuxInteraction({
+                        operationId,
+                        workspaceName,
+                        semanticPaneId,
+                        operationKind,
+                    }) ?? false;
+                    if (consumed)
+                        return true;
                 }
-            })();
-            return stopping;
-        },
-        activateProject: activateProjectOnDaemon,
-    };
-    setDaemonShutdownBackend(async () => {
-        await handle.stop({ gracefulMs: 500 });
-    });
-    setRemoteAccessRestartBackend((request) => {
-        setTimeout(() => {
-            void (async () => {
-                const restartPort = request.port ?? port;
                 try {
-                    await handle.stop({ gracefulMs: 500 });
+                    broadcastInteractionReceipt({
+                        operationId: randomUUID(),
+                        origin: "external",
+                        workspaceName,
+                        target: { kind: "pane", semanticPaneId },
+                        operationKind,
+                        phase: "observed",
+                        summary: operationKind === "workspace.pane.read"
+                            ? { operationKind, observedOnly: true }
+                            : { operationKind, observedOnly: true },
+                        proof: { operationKind, observed: true, semanticPaneId },
+                    }, instanceId);
                 }
-                catch (err) {
-                    console.error("[daemon] Remote access stop before restart failed:", err);
+                catch (error) {
+                    if (!opts.silent)
+                        console.error("[daemon] External interaction receipt failed:", error);
                 }
-                finally {
-                    clearCanonicalDaemonInfo();
+                return false;
+            },
+        });
+        let terminalAttachmentRuntime = null;
+        let paneStreamRuntime = null;
+        let runtimeTraceStream = null;
+        const closeRuntimeTraceStream = async () => {
+            externalInteractionObserver.setDiagnostics(null);
+            setFleetFactsObserverDiagnostics(null);
+            const stream = runtimeTraceStream;
+            runtimeTraceStream = null;
+            if (!stream || stream.closed || stream.destroyed)
+                return;
+            await new Promise((resolve) => stream.end(resolve));
+        };
+        let startedServer;
+        try {
+            const selector = tmuxAuthority.socketSelector;
+            const executeRuntimeIntent = (operationId, intent, timing) => {
+                if (intent.verb === "workspace.pane.read") {
+                    workspaceMultiplexer.readPane(operationId, intent);
+                    return;
                 }
-                for (let attempt = 0; attempt < 2; attempt++) {
+                return workspaceMultiplexer.mutate({ operationId, expectedDaemonInstanceId: instanceId, intent }, timing);
+            };
+            const runtimeTracePath = process.env.TMUX_IDE_SESSION_RUNTIME_TRACE_LOG;
+            runtimeTraceStream = runtimeTracePath
+                ? createWriteStream(runtimeTracePath, { flags: "a", highWaterMark: 64 * 1_024 })
+                : null;
+            let runtimeTraceSaturated = false;
+            runtimeTraceStream?.on("error", () => {
+                runtimeTraceSaturated = true;
+            });
+            runtimeTraceStream?.on("drain", () => {
+                runtimeTraceSaturated = false;
+            });
+            const runtimeObservability = runtimeTracePath
+                ? createSessionRuntimeObservability({
+                    // The JSONL stream is the qualifying record. Keep only a small
+                    // in-memory diagnostic tail so a sustained terminal flood cannot
+                    // retain tens of thousands of frozen span objects or induce GC
+                    // pauses on the daemon's input/output event loop.
+                    capacity: 1_024,
+                    onSpan: (span) => {
+                        if (!runtimeTraceStream || runtimeTraceSaturated)
+                            return;
+                        runtimeTraceSaturated = !runtimeTraceStream.write(`${JSON.stringify({ version: 1, type: "performance.stage", ...span })}\n`);
+                    },
+                })
+                : undefined;
+            if (runtimeTracePath) {
+                const publishObserverDiagnostic = (event) => {
+                    try {
+                        if (!runtimeTraceStream || runtimeTraceSaturated)
+                            return;
+                        runtimeTraceSaturated = !runtimeTraceStream.write(`${JSON.stringify({
+                            version: 1,
+                            type: "performance.daemon-observer",
+                            ...event,
+                            generation: instanceId,
+                        })}\n`);
+                    }
+                    catch {
+                        // Qualification diagnostics never alter daemon observation.
+                    }
+                };
+                const diagnostics = {
+                    nowMicros: () => Math.floor(performance.now() * 1_000),
+                    createTraceId: randomUUID,
+                    publish: publishObserverDiagnostic,
+                };
+                externalInteractionObserver.setDiagnostics(diagnostics);
+                setFleetFactsObserverDiagnostics(diagnostics);
+            }
+            sessionRuntimeRegistry = new SessionRuntimeRegistry({
+                generation: instanceId,
+                ...(runtimeObservability ? { observability: runtimeObservability } : {}),
+                semanticMutations: {
+                    resolveSession: (workspaceName) => workspaceRegistry.get(workspaceName)?.sessionName ?? null,
+                    execute: executeRuntimeIntent,
+                    traceAuthority: { generation: instanceId, incarnation: null },
+                    publishReceipt: (receipt) => broadcastInteractionReceipt(receipt, instanceId),
+                    publishResourceChange: (change) => broadcastResourceChanged(change, instanceId),
+                },
+                mirror: {
+                    executable: tmuxAuthority.executablePath,
+                    internalReadHookEmission: (runtimePaneId, marker) => externalInteractionObserver.internalReadHookEmission(runtimePaneId, marker),
+                    ...(selector.kind === "path" ? { socketPath: selector.path } : {}),
+                    ...(selector.kind === "name" && selector.name !== "default"
+                        ? { socketName: selector.name }
+                        : {}),
+                },
+            });
+            workspaceOpenHandoff = new WorkspaceOpenHandoffCoordinator({
+                daemonInstanceId: instanceId,
+                openProject: (request) => workspaceOpen.open(request),
+                adoptLiveSession: (request) => workspacePromotion.promote(request),
+                prewarmPrevious: async (workspaceName) => {
+                    const record = workspaceRegistry.get(workspaceName);
+                    if (record)
+                        await sessionRuntimeRegistry.prewarmSession(record.sessionName);
+                },
+                prepareRuntime: async (workspaceName, preferredPaneId) => {
+                    const record = workspaceRegistry.get(workspaceName);
+                    if (!record)
+                        throw new Error(`Prepared workspace ${workspaceName} is absent from the durable catalog.`);
+                    await sessionRuntimeRegistry.prewarmSession(record.sessionName);
+                    const consumer = sessionRuntimeRegistry.connect(record.sessionName, "workspace-open-prepare", `workspace-open-${randomUUID()}`);
                     try {
-                        const nextHandle = await startEmbeddedDaemon({
-                            sessionName: sessionless ? undefined : sessionName,
-                            port: restartPort,
-                            bindHostname: request.bindHostname,
-                            authToken: request.token,
-                            localBypassToken,
+                        const layout = await consumer.describe();
+                        if (layout.degraded || layout.panes.length === 0) {
+                            throw new Error(`Prepared workspace ${workspaceName} has no coherent semantic layout.`);
+                        }
+                        const semanticPaneId = layout.panes.find((pane) => pane.semanticPaneId === preferredPaneId)
+                            ?.semanticPaneId ??
+                            layout.panes.find((pane) => pane.active)?.semanticPaneId ??
+                            layout.panes[0].semanticPaneId;
+                        const seed = await new Promise((resolve, reject) => {
+                            const timeout = setTimeout(() => reject(new Error("Timed out awaiting first coherent terminal seed.")), 5_000);
+                            void consumer
+                                .subscribeReplica(semanticPaneId, (update) => {
+                                if (update.type !== "terminal.seed")
+                                    return;
+                                clearTimeout(timeout);
+                                resolve({ revision: update.revision, stateHash: update.stateHash });
+                            })
+                                .catch((error) => {
+                                clearTimeout(timeout);
+                                reject(error);
+                            });
                         });
-                        const mutableHandle = handle;
-                        mutableHandle.stop = nextHandle.stop;
-                        mutableHandle.activateProject = nextHandle.activateProject;
+                        return {
+                            semanticPaneId,
+                            paneCount: layout.panes.length,
+                            terminalRevision: seed.revision,
+                            terminalStateHash: seed.stateHash,
+                        };
+                    }
+                    finally {
+                        await consumer.close();
+                    }
+                },
+            });
+            const terminalRuntimeOptions = {
+                registry: workspaceRegistry,
+                sessionRuntimeRegistry,
+                tmuxAuthority: {
+                    executablePath: tmuxAuthority.executablePath,
+                    socketSelector: tmuxAuthority.socketSelector,
+                    trustedCwd: dir,
+                },
+                agentStatusProbeFactory: ({ run }) => createTmuxAgentStatusProbe({ run }),
+                onInventory: (snapshot) => workspaceMultiplexer.adoptPaneInventory(snapshot.panes),
+                onSessionInventory: (sessionName, snapshot) => workspaceMultiplexer.adoptSessionPaneInventory(sessionName, snapshot?.panes ?? []),
+                ...(runtimeObservability ? { observability: runtimeObservability } : {}),
+            };
+            terminalInventoryRuntime = new WorkspaceTerminalInventoryRuntime(terminalRuntimeOptions);
+            // Reconcile only cryptographically marked legacy view sessions before
+            // publishing this daemon generation. This neutral cleanup does not
+            // construct PTYs, attachment leases, or admission.
+            await terminalInventoryRuntime.whenReady();
+            const getTerminalAttachmentRuntime = () => {
+                if (terminalAttachmentRuntime)
+                    return terminalAttachmentRuntime;
+                terminalAttachmentRuntime = createNativeTerminalAttachmentRuntime({
+                    daemonInstanceId: instanceId,
+                    webSocketUrl: terminalAttachmentWebSocketUrl(bindHostname, port),
+                    ...terminalRuntimeOptions,
+                    inventoryRuntime: terminalInventoryRuntime,
+                });
+                void terminalAttachmentRuntime.whenReady().catch(() => undefined);
+                return terminalAttachmentRuntime;
+            };
+            const peekTerminalAttachmentRuntime = () => terminalAttachmentRuntime;
+            paneStreamRuntime = createPaneStreamRuntime({
+                daemonInstanceId: instanceId,
+                webSocketUrl: paneStreamWebSocketUrl(bindHostname, port),
+                sessionRuntimeRegistry,
+                semanticPaneCatalog: terminalInventoryRuntime.semanticPaneCatalog,
+                ...(runtimeObservability ? { observability: runtimeObservability } : {}),
+            });
+            const orderedMultiplexerBackend = createSessionRuntimeMultiplexerBackend({
+                registry: sessionRuntimeRegistry,
+                resolveSession: (workspaceName) => workspaceRegistry.get(workspaceName)?.sessionName ?? null,
+                resolvePaneSourceCredential: (credential, resolvedSession, claimedSource) => paneSourceCredentials.resolve(credential, resolvedSession, claimedSource),
+            });
+            await externalInteractionObserver.start();
+            setFleetFactsTmuxRunner(catalogTmuxRunner);
+            startedServer = await startHttpServer({
+                sessionName,
+                requestedPort: port,
+                bindHostname,
+                dir,
+                authToken,
+                localBypassToken,
+                silent: opts.silent,
+                readProjectAuth: !sessionless,
+                daemonIdentity: { productVersion, instanceId, startedAt, environmentId },
+                workspacePaneCreationBackend: workspacePaneCreation,
+                workspaceOpenBackend: workspaceOpen,
+                workspaceOpenHandoffBackend: workspaceOpenHandoff,
+                fleetLifecycleBackend: fleetLifecycle,
+                workspacePromotionBackend: workspacePromotion,
+                appWindowMutationBackend: appWindowMutation,
+                workspaceMultiplexerBackend: orderedMultiplexerBackend,
+                workspaceRegistry,
+                terminalInventoryRuntime,
+                getTerminalAttachmentRuntime,
+                peekTerminalAttachmentRuntime,
+                paneStreamRuntime,
+                catalogLiveSessions: () => discoverLiveSessionSummaries(catalogTmuxRunner),
+                catalogFleet: () => readAdoptedFleet(workspaceRegistry, catalogTmuxRunner),
+            });
+        }
+        catch (error) {
+            setFleetFactsTmuxRunner(null);
+            await Promise.allSettled([
+                Promise.resolve().then(() => terminalAttachmentRuntime?.dispose()),
+                Promise.resolve().then(() => terminalInventoryRuntime?.dispose()),
+                paneStreamRuntime?.dispose() ?? Promise.resolve(),
+                workspacePaneCreation.dispose(),
+                workspaceOpen.dispose(),
+                Promise.resolve().then(() => workspaceOpenHandoff?.dispose()),
+                workspacePromotion.dispose(),
+                appWindowMutation.dispose(),
+                workspaceMultiplexer.dispose(),
+                externalInteractionObserver.dispose(),
+                closeRuntimeTraceStream(),
+            ]);
+            // The pane-stream coordinator may still hold runtime consumers while it
+            // drains. Preserve the normal shutdown order on startup rollback too:
+            // transports first, then the one session/control authority.
+            await Promise.allSettled([sessionRuntimeRegistry?.dispose() ?? Promise.resolve()]);
+            throw error;
+        }
+        const { server, sockets, closeClients, closeWsServers, terminalAttachmentBoundary, paneStreamBoundary, } = startedServer;
+        const retirePaneStreamTransport = async () => {
+            const transportResults = await Promise.allSettled([
+                Promise.resolve().then(() => paneStreamRuntime.dispose()),
+                Promise.resolve().then(() => paneStreamBoundary.close()),
+            ]);
+            const runtimeResults = await Promise.allSettled([
+                Promise.resolve().then(() => sessionRuntimeRegistry.dispose()),
+            ]);
+            return [...transportResults, ...runtimeResults].flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+        };
+        const abortStartedServer = async () => {
+            setFleetFactsTmuxRunner(null);
+            const terminalFailures = [
+                ...(await retireTerminalAttachmentTransport(terminalAttachmentRuntime, terminalAttachmentBoundary)),
+                ...(await retirePaneStreamTransport()),
+            ];
+            terminalInventoryRuntime.dispose();
+            const paneDisposal = Promise.resolve().then(() => workspacePaneCreation.dispose());
+            const workspaceOpenDisposal = Promise.resolve().then(() => workspaceOpen.dispose());
+            const workspaceOpenHandoffDisposal = Promise.resolve().then(() => workspaceOpenHandoff?.dispose());
+            const workspacePromotionDisposal = Promise.resolve().then(() => workspacePromotion.dispose());
+            const appWindowMutationDisposal = Promise.resolve().then(() => appWindowMutation.dispose());
+            const workspaceMultiplexerDisposal = Promise.resolve().then(() => workspaceMultiplexer.dispose());
+            const externalInteractionDisposal = Promise.resolve().then(() => externalInteractionObserver.dispose());
+            const closePromise = Promise.resolve()
+                .then(() => waitForServerClose(server))
+                .catch(() => undefined);
+            await Promise.allSettled([
+                paneDisposal,
+                workspaceOpenDisposal,
+                workspaceOpenHandoffDisposal,
+                workspacePromotionDisposal,
+                appWindowMutationDisposal,
+                workspaceMultiplexerDisposal,
+                externalInteractionDisposal,
+                closeRuntimeTraceStream(),
+                Promise.resolve().then(() => closeClients()),
+                ...[...sockets].map((socket) => Promise.resolve().then(() => socket.destroy())),
+                Promise.race([closePromise, delay(100)]),
+                Promise.resolve().then(() => closeWsServers()),
+            ]);
+            if (terminalFailures.length > 0 && !opts.silent) {
+                console.error("[daemon] Direct terminal startup rollback reported cleanup failures.");
+            }
+        };
+        try {
+            writeCanonicalDaemonInfo({
+                pid: process.pid,
+                port,
+                protocolVersion: DAEMON_WIRE_PROTOCOL_VERSION,
+                productVersion,
+                instanceId,
+                startedAt,
+                environmentId,
+                bindHostname,
+                authToken: localBypassToken,
+            }, claim);
+            const published = inspectCanonicalDaemonInfo();
+            if (published.status !== "valid" ||
+                published.info.instanceId !== instanceId ||
+                published.info.pid !== process.pid ||
+                published.info.port !== port) {
+                throw new DaemonStartupError("Canonical daemon publication does not belong to the started server", "canonical_publication_lost");
+            }
+        }
+        catch (error) {
+            await abortStartedServer();
+            throw error;
+        }
+        let stopped = false;
+        let stopping = null;
+        let stopSelf = null;
+        const activeProjectStops = new Map();
+        // Track active projects so the session-control surface can open/close
+        // them. Orchestration moved out of tmux-ide (agent coordination lives in
+        // sfora.ai), so activation is now bookkeeping only.
+        const activateProjectOnDaemon = async (projectName, _options = {}) => {
+            if (!activeProjectStops.has(projectName)) {
+                activeProjectStops.set(projectName, { stop: () => undefined });
+            }
+            return {
+                stop: async () => {
+                    const current = activeProjectStops.get(projectName);
+                    if (!current)
                         return;
+                    activeProjectStops.delete(projectName);
+                    current.stop();
+                },
+            };
+        };
+        setActivationBackend({
+            activateProject: async (name, options) => {
+                await activateProjectOnDaemon(name, options);
+            },
+            deactivateProject: async (name) => {
+                const stop = activeProjectStops.get(name);
+                if (!stop)
+                    return;
+                activeProjectStops.delete(name);
+                stop.stop();
+            },
+        });
+        const sessionMonitor = sessionless
+            ? null
+            : new DaemonSessionMonitor({
+                sessionName,
+                backend: {
+                    inspectSession: async (candidate, signal) => {
+                        try {
+                            await execTmuxAsync(["has-session", "-t", candidate], signal);
+                            return "yes";
+                        }
+                        catch (error) {
+                            if (signal.aborted)
+                                return "unknown";
+                            return classifySessionInspectionError(error);
+                        }
+                    },
+                    listCredentialSessions: () => workspaceRegistry.list().map((workspace) => workspace.sessionName),
+                    reconcileCredentials: async (workspaceSession, signal) => {
+                        try {
+                            await paneSourceCredentials.reconcileSessionAsync(workspaceSession, signal);
+                        }
+                        catch (error) {
+                            // Registry/session races are idempotent; transport/resource
+                            // failures must escape so this state is retried next cycle.
+                            if (!isConfirmedMissingTmuxTarget(error))
+                                throw error;
+                        }
+                    },
+                    hasClients: async (signal) => {
+                        try {
+                            return (await execTmuxAsync(["list-clients"], signal)).length > 0;
+                        }
+                        catch {
+                            return null;
+                        }
+                    },
+                    listPanes: async (candidate, signal) => {
+                        try {
+                            const raw = await execTmuxAsync([
+                                "list-panes",
+                                "-t",
+                                candidate,
+                                "-F",
+                                "#{pane_id}\t#{pane_pid}\t#{pane_current_command}\t#{pane_title}\t#{@ide_role}\t#{@ide_type}\t#{@ide_name}",
+                            ], signal);
+                            return parseDaemonMonitorPanes(raw);
+                        }
+                        catch {
+                            return null;
+                        }
+                    },
+                    readPortProcessFacts: async (signal) => {
+                        try {
+                            return await readPortProcessFactsAsync(signal);
+                        }
+                        catch {
+                            return null;
+                        }
+                    },
+                    setPaneOption: async (paneId, option, value, signal) => {
+                        try {
+                            await execTmuxAsync(["set-option", "-pt", paneId, option, value], signal);
+                        }
+                        catch (error) {
+                            if (!isConfirmedMissingTmuxTarget(error))
+                                throw error;
+                        }
+                    },
+                    setPaneTitle: async (paneId, title, signal) => {
+                        try {
+                            await execTmuxAsync(["select-pane", "-t", paneId, "-T", title], signal);
+                        }
+                        catch (error) {
+                            if (!isConfirmedMissingTmuxTarget(error))
+                                throw error;
+                        }
+                    },
+                    refreshClients: async (signal) => {
+                        try {
+                            await execTmuxAsync(["refresh-client", "-S"], signal);
+                        }
+                        catch (error) {
+                            if (!isConfirmedMissingTmuxTarget(error))
+                                throw error;
+                        }
+                    },
+                    onSessionGone: () => stopSelf?.(),
+                },
+            });
+        sessionMonitor?.start();
+        const apiBaseUrl = canonicalDaemonUrl("http", bindHostname, port);
+        const wsUrl = canonicalDaemonUrl("ws", bindHostname, port, "/ws/events");
+        const handle = {
+            instanceId,
+            pid: process.pid,
+            port,
+            apiBaseUrl,
+            wsUrl,
+            localBypassToken,
+            compatibilityTerminalAttachmentRuntimeConstructed: () => terminalAttachmentRuntime !== null,
+            stop: async ({ gracefulMs = DEFAULT_GRACEFUL_MS } = {}) => {
+                if (stopping)
+                    return stopping;
+                if (stopped)
+                    return;
+                stopping = (async () => {
+                    const failures = [];
+                    const capture = async (operation) => {
+                        try {
+                            await operation();
+                        }
+                        catch (error) {
+                            failures.push(error);
+                        }
+                    };
+                    try {
+                        stopped = true;
+                        await capture(() => setActivationBackend(null));
+                        await capture(() => sessionMonitor?.stop());
+                        paneSourceCredentials.dispose();
+                        // Retire direct-ticket admission, live PTYs, and the direct upgrade
+                        // listener before touching the legacy WS or HTTP surfaces.
+                        failures.push(...(await retireTerminalAttachmentTransport(terminalAttachmentRuntime, terminalAttachmentBoundary)));
+                        failures.push(...(await retirePaneStreamTransport()));
+                        await capture(() => terminalInventoryRuntime.dispose());
+                        await capture(() => workspacePaneCreation.dispose());
+                        await capture(() => workspaceOpen.dispose());
+                        await capture(() => workspaceOpenHandoff?.dispose());
+                        await capture(() => workspacePromotion.dispose());
+                        await capture(() => appWindowMutation.dispose());
+                        await capture(() => workspaceMultiplexer.dispose());
+                        await capture(() => externalInteractionObserver.dispose());
+                        let closePromise;
+                        try {
+                            closePromise = waitForServerClose(server);
+                        }
+                        catch (error) {
+                            failures.push(error);
+                            closePromise = Promise.resolve();
+                        }
+                        await capture(() => closeClients());
+                        for (const stop of activeProjectStops.values()) {
+                            await capture(() => stop.stop());
+                        }
+                        activeProjectStops.clear();
+                        await capture(() => shutdownPtyBridges());
+                        await capture(() => Promise.race([closePromise, delay(gracefulMs)]));
+                        for (const socket of sockets) {
+                            await capture(() => {
+                                socket.destroy();
+                            });
+                        }
+                        await capture(() => Promise.race([closePromise, delay(100)]));
+                        await capture(() => closeWsServers());
+                        await capture(() => shutdownWsEventObservation());
+                        await capture(() => setFleetFactsTmuxRunner(null));
+                        await capture(() => closeRuntimeTraceStream());
+                        await capture(() => setRemoteAccessRestartBackend(null));
+                        await capture(() => setDaemonShutdownBackend(null));
+                        if (failures.length > 0) {
+                            const cause = failures.length === 1
+                                ? failures[0]
+                                : new AggregateError(failures, "Daemon resources reported shutdown failures");
+                            throw new DaemonShutdownError("Daemon shutdown failed", { cause: cause });
+                        }
+                    }
+                    finally {
+                        try {
+                            clearCanonicalDaemonInfoIfOwned(instanceId, claim);
+                        }
+                        finally {
+                            releaseCanonicalDaemonClaim(claim);
+                        }
+                    }
+                })();
+                return stopping;
+            },
+            activateProject: activateProjectOnDaemon,
+        };
+        setDaemonShutdownBackend(async () => {
+            await handle.stop({ gracefulMs: 500 });
+        }, instanceId);
+        setRemoteAccessRestartBackend((request) => {
+            setTimeout(() => {
+                void (async () => {
+                    const restartPort = request.port ?? port;
+                    try {
+                        await handle.stop({ gracefulMs: 500 });
                     }
                     catch (err) {
-                        if (err instanceof DaemonStartupError &&
-                            err.reason === "port_in_use" &&
-                            attempt === 0) {
-                            await delay(150);
-                            continue;
+                        console.error("[daemon] Remote access stop before restart failed:", err);
+                    }
+                    for (let attempt = 0; attempt < 2; attempt++) {
+                        try {
+                            const nextHandle = await startEmbeddedDaemon({
+                                sessionName: sessionless ? undefined : sessionName,
+                                port: restartPort,
+                                bindHostname: request.bindHostname,
+                                authToken: request.token,
+                                localBypassToken,
+                            });
+                            const mutableHandle = handle;
+                            mutableHandle.stop = nextHandle.stop;
+                            mutableHandle.activateProject = nextHandle.activateProject;
+                            return;
+                        }
+                        catch (err) {
+                            if (err instanceof DaemonStartupError &&
+                                err.reason === "port_in_use" &&
+                                attempt === 0) {
+                                await delay(150);
+                                continue;
+                            }
+                            throw err;
                         }
-                        throw err;
                     }
-                }
-            })().catch((err) => {
-                console.error("[daemon] Remote access restart failed:", err);
-                clearCanonicalDaemonInfo();
-            });
-        }, 50).unref?.();
-        return { port };
-    });
-    stopSelf = () => void handle.stop();
-    tick();
-    return handle;
+                })().catch((err) => {
+                    console.error("[daemon] Remote access restart failed:", err);
+                });
+            }, 50).unref?.();
+            return { port };
+        });
+        stopSelf = () => void handle.stop();
+        void sessionMonitor?.runOnce();
+        return handle;
+    }
+    catch (error) {
+        releaseCanonicalDaemonClaim(claim);
+        throw error;
+    }
 }