tmux-ide 2.7.0 → 2.9.0-beta.5

package/packages/daemon/dist/command-center/server.js

@@ -1,21 +1,25 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { existsSync, readdirSync } from "node:fs";
 import { join, dirname, basename } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Hono } from "hono";
 import { streamSSE } from "hono/streaming";
 import { cors } from "hono/cors";
-import { discoverSessions, buildOverviews, buildProjectDetail, } from "./discovery.js";
+import { discoverSessions, discoverLiveSessionSummaries, buildOverviews, buildProjectDetail, } from "./discovery.js";
 import { listSessionPanes, sendCommand, sendEnterToPane, sendLiteralToPane, sendText, getPaneBusyStatus, } from "../widgets/lib/pane-comms.js";
 import { resolvePane } from "../send.js";
 import { getSessionState, killSession, stopSessionMonitor } from "@tmux-ide/tmux-bridge";
-import { readConfig, writeConfig } from "../lib/yaml-io.js";
+import { writeConfig } from "../lib/yaml-io.js";
+import { resolveConfig } from "../lib/resolved-config.js";
+import { resolveProjectConfigContext } from "../lib/config-context.js";
 import { IdeConfigSchema } from "../schemas/ide-config.js";
 import { getLogBuffer, subscribeLogs } from "../lib/log.js";
 import { zValidator } from "@hono/zod-validator";
+import { z } from "zod";
+import { isSemanticMultiplexerActionName } from "./actions/semantic-multiplexer-actions.js";
 import { getDefaultWorkspaceRegistry, WorkspaceAlreadyExistsError, WorkspaceNotFoundError, } from "../lib/workspace-registry.js";
-import { AddWorkspaceRequestSchemaZ } from "@tmux-ide/contracts";
+import { AddWorkspaceRequestSchemaZ, APPLICATION_SHELL_RESOURCE_V1_VERSION, APPLICATION_SHELL_RESOURCE_V2_VERSION, APPLICATION_SHELL_RESOURCE_V3_VERSION, WORKSPACE_CATALOG_RESOURCE_VERSION, WORKSPACE_CATALOG_RESOURCE_V2_VERSION, WORKSPACE_CATALOG_RESOURCE_V3_VERSION, projectWorkspaceCatalogV2, projectWorkspaceCatalogV3, DAEMON_WIRE_PROTOCOL_VERSION, DaemonInstanceIdentitySchemaZ, TERMINAL_RUNTIME_INVENTORY_RESOURCE_VERSION, } from "@tmux-ide/contracts";
 import { sendCommandSchema } from "./schemas.js";
 import { createScriptTerminalId, terminalCreateRequestSchema, terminalRenameRequestSchema, } from "@tmux-ide/contracts";
 import { deleteTerminal as deleteTerminalRecord, loadTerminals, renameTerminal as renameTerminalRecord, upsertTerminal as upsertTerminalRecord, } from "../lib/terminals-store.js";
@@ -24,7 +28,8 @@ import { broadcastTerminalsChanged } from "./ws-events.js";
 import { AuthService } from "../lib/auth/auth-service.js";
 import { authMiddleware } from "../lib/auth/middleware.js";
 import { handleWsEventsConnection, broadcastInitOutput, broadcastInitError } from "./ws-events.js";
-import { createActionDispatcher } from "./actions/dispatcher.js";
+import { createActionDispatcher, markActionOwnerAuthorized } from "./actions/dispatcher.js";
+import { PANE_SOURCE_CREDENTIAL_HEADER } from "../lib/pane-source-credentials.js";
 import { listProjects, getProject, registerProject, unregisterProject, refreshProject, ProjectAlreadyRegisteredError, ProjectDirNotFoundError, ProjectNotFoundError, } from "../lib/project-registry.js";
 import { runInit, ProjectInitFailedError, ProjectInitTimeoutError, } from "../lib/project-init-runner.js";
 import { RegisterProjectRequestSchemaZ, InitProjectRequestSchemaZ, } from "../schemas/registry.js";
@@ -37,34 +42,64 @@ import { homedir } from "node:os";
 import { isAbsolute, resolve as pathResolve } from "node:path";
 import { randomUUID } from "node:crypto";
 import { WebSocketServer } from "ws";
-const __dirname = dirname(fileURLToPath(import.meta.url));
-// Resolve our package.json's version. The lookup needs to handle BOTH
-// dev (this file lives at src/command-center/, so the workspace root
-// is two levels up) AND the packaged Electron bundle (this file is
-// flattened into app.asar/dist-electron/, so the bundled package.json
-// is ONE level up; two levels up escapes the asar). Try the candidates
-// in order; fall back to a sentinel if neither is readable.
-function resolvePackageVersion() {
-    const candidates = [join(__dirname, "../../package.json"), join(__dirname, "../package.json")];
-    for (const candidate of candidates) {
-        try {
-            const parsed = JSON.parse(readFileSync(candidate, "utf-8"));
-            if (typeof parsed.version === "string")
-                return parsed.version;
-        }
-        catch {
-            /* try the next candidate */
-        }
-    }
-    return "0.0.0";
-}
-const pkgVersion = resolvePackageVersion();
+import { projectDeprecatedStandaloneApplicationShellResourceV1, projectApplicationShellResource, projectApplicationShellResourceV3, } from "./resources/application-shell.js";
+import { terminalRuntimeInventoryEnvelope } from "./resources/terminal-runtime-inventory.js";
+import { currentResourceRevision } from "./ws-events.js";
+import { fleetSessionIdForName } from "./resources/fleet-catalog.js";
+import { FilesAuthority } from "./resources/workspace-files-authority.js";
+import { ChangesAuthority } from "./resources/workspace-changes-authority.js";
+import { loadApplicationShellAppWindows } from "../lib/application-shell-app-windows.js";
+import { daemonActionCommandRegistry } from "./actions/command-definitions.js";
+import { MissionRepository } from "../lib/mission-repository.js";
+import { projectDesktopMissionWorkspace } from "./resources/desktop-missions.js";
+import { mountTerminalAttachmentIssueRoute, } from "./terminal-attachment-issue.js";
+import { mountPaneStreamIssueRoute } from "./pane-stream-issue.js";
+import { mountWorkspaceResourceRoutes } from "./resources/workspace-resource-routes.js";
+import { mountFleetResourceRoute } from "./resources/fleet-resource-route.js";
+import { mountWorkspaceMissionsRoute } from "./resources/workspace-missions-route.js";
+import { ownerAuthorityGate, requireOwnerAuthority } from "./owner-authority.js";
+import { mountStartupReadinessRoute, } from "./resources/startup-readiness-route.js";
+import { readWidgetAsset } from "../lib/widget-asset-store.js";
+const defaultApplicationShellAppWindowBackend = {
+    async load(projectDir, terminalSourceIds, focusedTerminalSourceId) {
+        return loadApplicationShellAppWindows(projectDir, terminalSourceIds, focusedTerminalSourceId);
+    },
+};
+const defaultApplicationShellMissionBackend = {
+    async load(projectDir) {
+        const repository = await MissionRepository.open(projectDir);
+        return projectDesktopMissionWorkspace(repository.snapshot());
+    },
+    async loadSnapshot(projectDir) {
+        const repository = await MissionRepository.open(projectDir);
+        return repository.snapshot();
+    },
+};
 let projectStreamConnections = 0;
 function bearerToken(authHeader) {
     if (!authHeader?.startsWith("Bearer "))
         return null;
     return authHeader.slice("Bearer ".length);
 }
+/**
+ * Bounded Files/Changes counts for the V3 dock badges. Best-effort: a failed
+ * listing or non-repository maps to a zero count so the shell read never fails
+ * on a workspace surface that has its own honest unavailable state.
+ */
+function workspaceDockSummary(projectDir, workspaceName) {
+    const safeCount = (read) => {
+        try {
+            return read() ?? 0;
+        }
+        catch {
+            return 0;
+        }
+    };
+    return {
+        fileCount: safeCount(() => new FilesAuthority(projectDir, workspaceName).rootEntryCount()),
+        changeCount: safeCount(() => new ChangesAuthority(projectDir, workspaceName).changeCount()),
+    };
+}
 function requireAuth(token, localBypassToken) {
     return async (c, next) => {
         if (!token)
@@ -77,10 +112,93 @@ function requireAuth(token, localBypassToken) {
         return c.json({ error: "Remote access token required" }, 401);
     };
 }
+/**
+ * Every action that changes a user's tmux world, and what each one demands.
+ *
+ * `owner-and-operation-id` is the full m44 discipline: owner authority plus a
+ * stable operation id, so a retried request replays rather than repeats. The
+ * multiplexer verbs join it because they destroy things — a `kill-pane`
+ * delivered twice must not take a second pane with it.
+ *
+ * `owner` is the same authority gate without the idempotency requirement. The
+ * `project.*` lifecycle actions sit here rather than in the list above: they
+ * predate the operation-id envelope and are reached by the CLI, which has no
+ * host to mint one, so demanding an id would break `tmux-ide stop` rather than
+ * secure it. What they must not keep doing is bypassing the owner check
+ * entirely — `project.stop` kills a tmux session, and it was open to any caller
+ * that could reach the port. For GUI use `workspace.session.kill` supersedes
+ * it: same effect, owner-gated, idempotent, and it answers with a verified
+ * result instead of a boolean.
+ *
+ * Anything absent from this table is a read or a query and passes through.
+ */
+const GATED_ACTIONS = {
+    "workspace.pane.create": "owner-and-operation-id",
+    "workspace.session.create": "owner-and-operation-id",
+    "fleet.agent.mutate": "owner-and-operation-id",
+    "fleet.agent.provision": "owner-and-operation-id",
+    "workspace.open": "owner-and-operation-id",
+    "workspace.open.prepare": "owner-and-operation-id",
+    "workspace.open.commit": "owner-and-operation-id",
+    "workspace.open.cancel": "owner-and-operation-id",
+    "workspace.promote": "owner-and-operation-id",
+    "workspace.app-window.mutate": "owner-and-operation-id",
+    "workspace.window.split": "owner-and-operation-id",
+    "workspace.window.kill": "owner-and-operation-id",
+    "workspace.pane.kill": "owner-and-operation-id",
+    "workspace.session.kill": "owner-and-operation-id",
+    "workspace.rename": "owner-and-operation-id",
+    "workspace.pane.zoom.toggle": "owner-and-operation-id",
+    "workspace.pane.select": "owner-and-operation-id",
+    "workspace.pane.send": "owner-and-operation-id",
+    "workspace.pane.swap": "owner-and-operation-id",
+    "workspace.pane.resize": "owner-and-operation-id",
+    "project.launch": "owner",
+    "project.stop": "owner",
+    "project.restart": "owner",
+    "project.activate": "owner",
+    "project.openTerminal": "owner",
+    "daemon.shutdown": "owner",
+};
+function requireHostCapability(ownerToken) {
+    const gate = ownerAuthorityGate(ownerToken, {
+        whenOwnerless: "unavailable",
+        unavailableMessage: "Host mutation capability is unavailable",
+        mismatchMessage: "Host mutation capability required",
+    });
+    return async (c, next) => {
+        const actionName = c.req.param("name");
+        const requirement = actionName ? GATED_ACTIONS[actionName] : undefined;
+        if (!requirement)
+            return next();
+        const semanticPrincipal = isSemanticMultiplexerActionName(actionName ?? "") &&
+            (c.req.header("X-Tmux-Ide-Host-Client-Id") !== undefined ||
+                c.req.header(PANE_SOURCE_CREDENTIAL_HEADER) !== undefined);
+        if (!semanticPrincipal) {
+            const denied = gate(c);
+            if (denied)
+                return denied;
+            markActionOwnerAuthorized(c);
+        }
+        if (requirement === "owner-and-operation-id" &&
+            !z.uuid().safeParse(c.req.header("X-Tmux-Ide-Operation-Id")).success) {
+            return c.json({ error: "A stable host operation id is required" }, 400);
+        }
+        return next();
+    };
+}
+// Owner-only. Capability negotiation is how the host learns this generation's
+// identity, so without the credential there is nothing to negotiate.
+const requireOwnerCapability = (ownerToken) => requireOwnerAuthority(ownerToken, {
+    whenOwnerless: "unavailable",
+    unavailableMessage: "Host capability discovery is unavailable",
+    mismatchMessage: "Host capability discovery requires owner authority",
+});
 function remoteAccessAuth(options) {
     const bindHostname = options.remoteAccess?.bindHostname ?? "127.0.0.1";
+    const loopback = bindHostname === "127.0.0.1" || bindHostname === "::1" || bindHostname === "localhost";
     return {
-        token: bindHostname === "127.0.0.1" ? null : (options.remoteAccess?.token ?? null),
+        token: loopback ? null : (options.remoteAccess?.token ?? null),
         localBypassToken: options.remoteAccess?.localBypassToken ?? null,
     };
 }
@@ -88,6 +206,12 @@ const sseMetrics = {
     connections: 0,
     messagesSent: 0,
 };
+const compatibilityMetrics = {
+    applicationShellV1Requests: 0,
+};
+export function getCompatibilityMetrics() {
+    return { ...compatibilityMetrics };
+}
 export function getSseMetrics() {
     return { ...sseMetrics };
 }
@@ -173,9 +297,34 @@ function sandboxResolveDir(rawDir) {
 export function createApp(options = {}) {
     const authConfig = options.authConfig ?? { method: "none", token_expiry: 86400 };
     const authService = options.authService ?? new AuthService();
+    const daemonIdentity = options.daemonIdentity ?? {
+        productVersion: "0.0.0",
+        instanceId: randomUUID(),
+        startedAt: new Date().toISOString(),
+    };
+    const daemonInstanceIdentity = DaemonInstanceIdentitySchemaZ.parse({
+        protocolVersion: DAEMON_WIRE_PROTOCOL_VERSION,
+        ...daemonIdentity,
+    });
+    const healthBootedAt = Date.now();
     const app = new Hono();
     // Allow cross-origin (Next.js dashboard, Tailscale, etc.)
     app.use("/*", cors());
+    // This exact route carries its own owner-only bearer and correlation gate.
+    // Mount it before remote and project auth so a valid host capability is
+    // neither rejected nor confused with any remotely shared user credential.
+    mountTerminalAttachmentIssueRoute(app, {
+        daemonInstanceId: daemonIdentity.instanceId,
+        ownerToken: options.remoteAccess?.ownerToken ?? null,
+        workspaceRegistry: options.workspaceRegistry ?? getDefaultWorkspaceRegistry(),
+        backend: options.terminalAttachmentIssueBackend ?? null,
+    });
+    mountPaneStreamIssueRoute(app, {
+        daemonInstanceId: daemonIdentity.instanceId,
+        ownerToken: options.remoteAccess?.ownerToken ?? null,
+        workspaceRegistry: options.workspaceRegistry ?? getDefaultWorkspaceRegistry(),
+        backend: options.paneStreamIssueBackend ?? null,
+    });
     // Remote access bearer gate. Local Electron access uses a per-daemon
     // bypass token from preload; loopback IPs are not implicitly trusted.
     const remoteAuth = remoteAccessAuth(options);
@@ -217,7 +366,43 @@ export function createApp(options = {}) {
     });
     // --- v2 action dispatcher (single typed entry-point for state-changing
     //     project / terminal operations — see src/command-center/actions/) ---
-    app.post("/api/v2/action/:name", createActionDispatcher());
+    app.post("/api/v2/capabilities", requireOwnerCapability(options.remoteAccess?.ownerToken ?? null), async (c) => {
+        let body;
+        try {
+            body = await c.req.json();
+        }
+        catch {
+            return c.json({ error: "Invalid capability request" }, 400);
+        }
+        if (!z.object({}).strict().safeParse(body).success) {
+            return c.json({ error: "Invalid capability request" }, 400);
+        }
+        const appWindowCommandRegistered = daemonActionCommandRegistry
+            .descriptors()
+            .some(({ id }) => id === "workspace.app-window.mutate");
+        return c.json({
+            status: "ok",
+            daemon: daemonInstanceIdentity,
+            capabilities: {
+                appWindowMutation: appWindowCommandRegistered && options.appWindowMutationBackend !== undefined
+                    ? { available: true }
+                    : {
+                        available: false,
+                        reason: "This daemon generation has no AppWindow mutation backend.",
+                    },
+            },
+        });
+    });
+    app.post("/api/v2/action/:name", requireHostCapability(options.remoteAccess?.ownerToken ?? null), createActionDispatcher({
+        daemonInstanceId: daemonIdentity.instanceId,
+        workspacePaneCreationBackend: options.workspacePaneCreationBackend,
+        workspaceOpenBackend: options.workspaceOpenBackend,
+        workspaceOpenHandoffBackend: options.workspaceOpenHandoffBackend,
+        fleetLifecycleBackend: options.fleetLifecycleBackend,
+        workspacePromotionBackend: options.workspacePromotionBackend,
+        appWindowMutationBackend: options.appWindowMutationBackend,
+        workspaceMultiplexerBackend: options.workspaceMultiplexerBackend,
+    }));
     app.get("/api/widget/:name/spawn", async (c) => {
         const { resolveWidgetSpawn, WIDGET_TYPES } = await import("../widgets/resolve.js");
         const name = c.req.param("name");
@@ -253,15 +438,45 @@ export function createApp(options = {}) {
             return c.json({ error: err instanceof Error ? err.message : String(err) }, 500);
         }
     });
+    // Pane widgets publish only content-addressed, media-validated bytes into the
+    // private tmux-ide state home. This route can therefore serve an opaque id
+    // without becoming a general-purpose filesystem reader.
+    app.get("/api/widget-assets/:assetId", (c) => {
+        const asset = readWidgetAsset(c.req.param("assetId"));
+        if (!asset)
+            return c.json({ error: "widget asset not found" }, 404);
+        return c.json({
+            assetId: asset.assetId,
+            media: asset.media,
+            name: asset.name,
+            data: asset.bytes.toString("base64"),
+        });
+    });
     // T067: /healthz — minimal liveness probe used by daemon-client.
     // Intentionally NOT under /api so it bypasses the auth middleware on
-    // every consumer. Returns ok + version + uptime (ms since boot).
-    const HEALTHZ_BOOTED_AT = Date.now();
+    // every consumer. Returns ok + productVersion + uptime (ms since boot).
     app.get("/healthz", (c) => {
         return c.json({
             ok: true,
-            version: process.env.npm_package_version ?? "dev",
-            uptimeMs: Date.now() - HEALTHZ_BOOTED_AT,
+            protocolVersion: DAEMON_WIRE_PROTOCOL_VERSION,
+            productVersion: daemonIdentity.productVersion,
+            uptimeMs: Date.now() - healthBootedAt,
+        });
+    });
+    // Credential-free endpoint binding. A desktop host reads the nonce from the
+    // owner-only canonical record, probes this endpoint, and compares before it
+    // sends any remote-access or local-bypass credential.
+    app.get("/identity", (c) => {
+        return c.json({
+            ok: true,
+            pid: process.pid,
+            protocolVersion: DAEMON_WIRE_PROTOCOL_VERSION,
+            productVersion: daemonIdentity.productVersion,
+            instanceId: daemonIdentity.instanceId,
+            startedAt: daemonIdentity.startedAt,
+            ...(daemonIdentity.environmentId !== undefined
+                ? { environmentId: daemonIdentity.environmentId }
+                : {}),
         });
     });
     app.get("/api/sessions", (c) => {
@@ -279,6 +494,63 @@ export function createApp(options = {}) {
         const registry = getDefaultWorkspaceRegistry();
         return c.json({ workspaces: registry.list() });
     });
+    // OWNER POLICY: not owner-gated, deliberately. This is the path-free index
+    // the host reads BEFORE it can address any owner-gated resource, and the
+    // production broker fetches it with no Authorization header
+    // (`daemon-resource-broker.ts` `#requestJson`, whose `authorize` argument
+    // defaults to false and is passed `true` only for the fleet catalog and the
+    // workspace resources). It is path-free by construction — `{workspaceName,
+    // sessionName}` pairs and nothing else, asserted in `workspaces.test.ts` —
+    // and it still sits behind the remote-access gate on a non-loopback bind.
+    // Gating it on the owner bearer would break every desktop workspace read
+    // without withholding a single fact the owner-gated routes do not already
+    // protect. V2 live rows carry the daemon-minted opaque Fleet session id;
+    // additive V3 also carries the tmux-incarnation identity used by long-lived
+    // Home selection without changing V2 for existing clients.
+    app.get("/api/resources/workspace-catalog", (c) => {
+        const registry = getDefaultWorkspaceRegistry();
+        const requestedCatalogVersion = c.req.query("version");
+        if (requestedCatalogVersion === String(WORKSPACE_CATALOG_RESOURCE_V2_VERSION) ||
+            requestedCatalogVersion === String(WORKSPACE_CATALOG_RESOURCE_V3_VERSION)) {
+            const workspaceIntents = registry.list().map(({ name, sessionName }) => ({
+                workspaceName: name,
+                sessionName,
+                source: "workspace",
+            }));
+            const knownWorkspaceNames = new Set(workspaceIntents.map(({ workspaceName }) => workspaceName));
+            const projectIntents = listProjects().flatMap((project) => knownWorkspaceNames.has(project.name)
+                ? []
+                : [
+                    {
+                        workspaceName: project.name,
+                        sessionName: project.name,
+                        source: "project",
+                    },
+                ]);
+            const observedSessions = options.catalogLiveSessions?.() ?? discoverLiveSessionSummaries();
+            const liveSessions = observedSessions.map(({ sessionName, paneCount }) => ({
+                sessionName,
+                fleetSessionId: fleetSessionIdForName(sessionName),
+                paneCount,
+            }));
+            if (requestedCatalogVersion === String(WORKSPACE_CATALOG_RESOURCE_V3_VERSION)) {
+                return c.json(projectWorkspaceCatalogV3(daemonInstanceIdentity, [...workspaceIntents, ...projectIntents], observedSessions.map(({ liveSessionId, sessionName, paneCount }) => ({
+                    liveSessionId,
+                    sessionName,
+                    fleetSessionId: fleetSessionIdForName(sessionName),
+                    paneCount,
+                }))));
+            }
+            return c.json(projectWorkspaceCatalogV2(daemonInstanceIdentity, [...workspaceIntents, ...projectIntents], liveSessions));
+        }
+        return c.json({
+            version: WORKSPACE_CATALOG_RESOURCE_VERSION,
+            daemon: daemonInstanceIdentity,
+            workspaces: registry
+                .list()
+                .map(({ name, sessionName }) => ({ workspaceName: name, sessionName })),
+        });
+    });
     app.get("/api/workspaces/:name", (c) => {
         const name = c.req.param("name");
         const registry = getDefaultWorkspaceRegistry();
@@ -287,19 +559,23 @@ export function createApp(options = {}) {
             return c.json({ error: "Workspace not found" }, 404);
         return c.json({ workspace });
     });
-    app.post("/api/workspaces", zValidator("json", AddWorkspaceRequestSchemaZ), (c) => {
+    app.post("/api/workspaces", zValidator("json", AddWorkspaceRequestSchemaZ), async (c) => {
         const body = c.req.valid("json");
         const registry = getDefaultWorkspaceRegistry();
         const name = body.name ?? basename(body.projectDir);
         if (!name || name.length === 0) {
             return c.json({ error: "Cannot derive workspace name from projectDir" }, 400);
         }
+        const facts = await resolveProjectConfigContext(body.projectDir);
         try {
             const workspace = registry.add({
                 name,
                 sessionName: body.sessionName,
                 projectDir: body.projectDir,
-                ideConfigPath: body.ideConfigPath ?? null,
+                ideConfigPath: body.ideConfigPath ?? facts.ideConfigPath,
+                configKind: body.configKind ?? facts.configKind,
+                configPath: body.configPath ?? facts.configPath,
+                hasWorkspaceConfig: body.hasWorkspaceConfig ?? facts.hasWorkspaceConfig,
             });
             return c.json({ workspace }, 201);
         }
@@ -337,6 +613,190 @@ export function createApp(options = {}) {
         const detail = buildProjectDetail(session);
         return c.json({ ...detail });
     });
+    const terminalRuntimeInventoryOwnerGate = ownerAuthorityGate(options.remoteAccess?.ownerToken ?? null, {
+        whenOwnerless: "unavailable",
+        unavailableMessage: "Terminal runtime inventory capability is unavailable",
+        mismatchMessage: "Terminal runtime inventory requires owner authority",
+    });
+    app.get("/api/project/:name/terminal-runtime-inventory", async (c) => {
+        const denied = terminalRuntimeInventoryOwnerGate(c);
+        if (denied)
+            return denied;
+        if ((c.req.query("version") ?? String(TERMINAL_RUNTIME_INVENTORY_RESOURCE_VERSION)) !==
+            String(TERMINAL_RUNTIME_INVENTORY_RESOURCE_VERSION)) {
+            return c.json({ error: "Unsupported terminal-runtime inventory resource version" }, 400);
+        }
+        const backend = options.applicationShellInventoryBackend;
+        if (!backend?.discoverTerminalRuntimeSession) {
+            return c.json({ error: "Terminal runtime inventory unavailable" }, 503);
+        }
+        try {
+            backend.recordTerminalRuntimeResourceMark?.("terminal-resource-handler-admitted");
+        }
+        catch {
+            // Diagnostics never own the authenticated request lifecycle.
+        }
+        const requestedSessionName = c.req.param("name");
+        let session;
+        try {
+            session = await backend.discoverTerminalRuntimeSession(requestedSessionName, c.req.raw.signal);
+        }
+        catch {
+            return c.json({ error: "Terminal runtime inventory unavailable" }, 503);
+        }
+        if (!session)
+            return c.json({ error: "Session not found" }, 404);
+        const projection = terminalRuntimeInventoryEnvelope(daemonInstanceIdentity, session, currentResourceRevision(session.workspaceName, "terminal-runtime-inventory"));
+        try {
+            backend.recordTerminalRuntimeResourceMark?.("terminal-resource-response-projection");
+        }
+        catch {
+            // Diagnostics never own response projection.
+        }
+        return c.json(projection);
+    });
+    app.get("/api/project/:name/application-shell", async (c) => {
+        const name = c.req.param("name");
+        // The unversioned compatibility default used to mean V1. Every current
+        // product host requests V3 (with an Electron V2 fallback), so the default
+        // now follows the current contract. Explicit V1 remains for external peers
+        // during a measured deprecation window.
+        const requestedVersion = c.req.query("version") ?? String(APPLICATION_SHELL_RESOURCE_V3_VERSION);
+        const markV1Compatibility = () => {
+            compatibilityMetrics.applicationShellV1Requests += 1;
+            c.header("Deprecation", "true");
+            c.header("Sunset", "Mon, 01 Feb 2027 00:00:00 GMT");
+            c.header("Link", `</api/project/${encodeURIComponent(name)}/application-shell?version=3>; rel="successor-version"`);
+            c.header("X-Tmux-Ide-Compatibility", "application-shell-v1");
+        };
+        if (requestedVersion !== String(APPLICATION_SHELL_RESOURCE_V1_VERSION) &&
+            requestedVersion !== String(APPLICATION_SHELL_RESOURCE_V2_VERSION) &&
+            requestedVersion !== String(APPLICATION_SHELL_RESOURCE_V3_VERSION)) {
+            return c.json({ error: "Unsupported application-shell resource version" }, 400);
+        }
+        if (requestedVersion === String(APPLICATION_SHELL_RESOURCE_V2_VERSION) ||
+            requestedVersion === String(APPLICATION_SHELL_RESOURCE_V3_VERSION)) {
+            const backend = options.applicationShellInventoryBackend;
+            if (!backend)
+                return c.json({ error: "Session discovery unavailable" }, 503);
+            let session;
+            try {
+                session = await backend.discoverApplicationShellSession(name);
+            }
+            catch {
+                return c.json({ error: "Session discovery unavailable" }, 503);
+            }
+            if (!session)
+                return c.json({ error: "Session not found" }, 404);
+            const resource = projectApplicationShellResource(session);
+            if (requestedVersion === String(APPLICATION_SHELL_RESOURCE_V3_VERSION)) {
+                const appWindowBackend = options.applicationShellAppWindowBackend === undefined
+                    ? defaultApplicationShellAppWindowBackend
+                    : options.applicationShellAppWindowBackend;
+                if (!appWindowBackend)
+                    return c.json({ error: "App window state unavailable" }, 503);
+                let appWindows;
+                try {
+                    appWindows = await appWindowBackend.load(session.dir, resource.terminalInventory.resources.map(({ id }) => id), resource.terminalInventory.activeResourceId);
+                }
+                catch {
+                    return c.json({ error: "App window state unavailable" }, 503);
+                }
+                return c.json({
+                    version: APPLICATION_SHELL_RESOURCE_V3_VERSION,
+                    daemon: daemonInstanceIdentity,
+                    resource: projectApplicationShellResourceV3(session, appWindows, undefined, workspaceDockSummary(session.dir, name)),
+                });
+            }
+            return c.json({
+                version: APPLICATION_SHELL_RESOURCE_V2_VERSION,
+                daemon: daemonInstanceIdentity,
+                resource,
+            });
+        }
+        const backend = options.applicationShellInventoryBackend;
+        if (!backend) {
+            if (requestedVersion === String(APPLICATION_SHELL_RESOURCE_V1_VERSION)) {
+                const standaloneSession = discoverSessions().find((candidate) => candidate.name === name);
+                if (!standaloneSession)
+                    return c.json({ error: "Session not found" }, 404);
+                markV1Compatibility();
+                return c.json({
+                    version: APPLICATION_SHELL_RESOURCE_V1_VERSION,
+                    daemon: daemonInstanceIdentity,
+                    resource: projectDeprecatedStandaloneApplicationShellResourceV1(standaloneSession),
+                });
+            }
+            return c.json({ error: "Session discovery unavailable" }, 503);
+        }
+        let session;
+        try {
+            session = await backend.discoverApplicationShellSession(name);
+        }
+        catch {
+            return c.json({ error: "Session discovery unavailable" }, 503);
+        }
+        if (!session)
+            return c.json({ error: "Session not found" }, 404);
+        const resource = projectApplicationShellResource(session);
+        const legacyResource = {
+            project: resource.project,
+            workspace: resource.workspace,
+            dock: resource.dock,
+            focus: resource.focus,
+            connection: resource.connection,
+        };
+        markV1Compatibility();
+        return c.json({
+            version: APPLICATION_SHELL_RESOURCE_V1_VERSION,
+            daemon: daemonInstanceIdentity,
+            resource: legacyResource,
+        });
+    });
+    // Owner-only, generation-stamped native Files and Changes read resources.
+    // The route param is a semantic workspace name resolved through the private
+    // workspace registry; renderer-supplied ids never decode to a path.
+    mountWorkspaceResourceRoutes(app, {
+        daemon: daemonInstanceIdentity,
+        ownerToken: options.remoteAccess?.ownerToken ?? null,
+        registry: options.workspaceRegistry ?? getDefaultWorkspaceRegistry(),
+    });
+    // Missions/Activity is intentionally lazy: the terminal-first V3 shell
+    // never opens mission history or assembles a graph. Only an interested,
+    // owner-authenticated consumer pays for this projection.
+    mountWorkspaceMissionsRoute(app, {
+        daemon: daemonInstanceIdentity,
+        ownerToken: options.remoteAccess?.ownerToken ?? null,
+        registry: options.workspaceRegistry ?? getDefaultWorkspaceRegistry(),
+        inventoryBackend: options.applicationShellInventoryBackend ?? null,
+        appWindowBackend: options.applicationShellAppWindowBackend === undefined
+            ? defaultApplicationShellAppWindowBackend
+            : options.applicationShellAppWindowBackend,
+        missionBackend: options.applicationShellMissionBackend === undefined
+            ? defaultApplicationShellMissionBackend
+            : options.applicationShellMissionBackend,
+    });
+    // Owner-only, generation-stamped fleet catalog: every ADOPTED tmux session
+    // (registry-backed and adopted-only) with its authority-stamped agents. It
+    // enumerates independently of the registry-gated session discovery so the
+    // app can SEE sessions it never created; the resource is path-free.
+    // OWNER POLICY: owner-only, 503 when this generation holds no credential.
+    mountFleetResourceRoute(app, {
+        daemon: daemonInstanceIdentity,
+        ownerToken: options.remoteAccess?.ownerToken ?? null,
+        registry: options.workspaceRegistry ?? getDefaultWorkspaceRegistry(),
+        readFleet: options.catalogFleet,
+    });
+    // The startup readiness ladder: the ordered, typed answer to "what is this
+    // daemon still missing?", computed from real state on every request.
+    // OWNER POLICY: owner-only when a credential exists; ownerless SERVES the
+    // ladder, whose `credential-held` rung is that answer. See the route header.
+    mountStartupReadinessRoute(app, {
+        daemon: daemonInstanceIdentity,
+        ownerToken: options.remoteAccess?.ownerToken ?? null,
+        registry: options.workspaceRegistry ?? getDefaultWorkspaceRegistry(),
+        attachmentRuntime: options.startupReadinessAttachmentBackend ?? null,
+    });
     app.get("/api/project/:name/panes", (c) => {
         const name = c.req.param("name");
         let panes;
@@ -613,25 +1073,36 @@ export function createApp(options = {}) {
             busyStatus,
         });
     });
-    // GET /api/project/:name/config — read parsed ide.yml + raw text. Used by
+    // GET /api/project/:name/config — read parsed workspace config. Used by
     // the v2 Config editor to hydrate the form.
-    app.get("/api/project/:name/config", (c) => {
+    app.get("/api/project/:name/config", async (c) => {
         const name = c.req.param("name");
         const sessions = discoverSessions();
         const session = sessions.find((s) => s.name === name);
         if (!session)
             return c.json({ error: "Session not found" }, 404);
         try {
-            const { config, configPath } = readConfig(session.dir);
-            return c.json({ ok: true, config, configPath });
+            const resolved = await resolveConfig(session.dir);
+            if (!resolved.launchConfig || !resolved.path) {
+                return c.json({ error: "Config not found" }, 404);
+            }
+            return c.json({
+                ok: true,
+                config: resolved.launchConfig,
+                configPath: resolved.path,
+                configKind: resolved.kind,
+                hasWorkspaceConfig: resolved.kind === "workspace",
+                hasIdeYml: resolved.resolution.legacyConfigPath !== null,
+                ideConfigPath: resolved.resolution.legacyConfigPath,
+            });
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            return c.json({ error: "Failed to read ide.yml", detail: message }, 500);
+            return c.json({ error: "Failed to read workspace config", detail: message }, 500);
         }
     });
     // POST /api/project/:name/config — accept a full IdeConfig payload, validate
-    // against IdeConfigSchema, and write to ide.yml. Returns the persisted
+    // against IdeConfigSchema, and write to workspace.yml. Returns the persisted
     // config so the client can re-hydrate without a follow-up GET.
     app.post("/api/project/:name/config", async (c) => {
         const name = c.req.param("name");
@@ -651,12 +1122,22 @@ export function createApp(options = {}) {
             return c.json({ error: "Invalid config", details: parsed.error.issues }, 400);
         }
         try {
-            const configPath = writeConfig(session.dir, parsed.data);
-            return c.json({ ok: true, config: parsed.data, configPath });
+            const context = await resolveProjectConfigContext(session.dir);
+            const configPath = writeConfig(context.configWriteRoot, parsed.data);
+            const resolved = await resolveConfig(session.dir);
+            return c.json({
+                ok: true,
+                config: parsed.data,
+                configPath,
+                configKind: resolved.kind,
+                hasWorkspaceConfig: resolved.kind === "workspace",
+                hasIdeYml: resolved.resolution.legacyConfigPath !== null,
+                ideConfigPath: resolved.resolution.legacyConfigPath,
+            });
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            return c.json({ error: "Failed to write ide.yml", detail: message }, 500);
+            return c.json({ error: "Failed to write workspace config", detail: message }, 500);
         }
     });
     // Launch a tmux-ide session (shells out to CLI since launch has complex side effects)
@@ -814,8 +1295,9 @@ export function createApp(options = {}) {
     app.get("/health", (c) => {
         return c.json({
             ok: true,
+            protocolVersion: DAEMON_WIRE_PROTOCOL_VERSION,
             uptime: Math.round(process.uptime()),
-            version: pkgVersion,
+            productVersion: daemonIdentity.productVersion,
         });
     });
     // --- Project registry ---
@@ -841,6 +1323,7 @@ export function createApp(options = {}) {
             const project = await registerProject({
                 dir: parsed.data.dir,
                 name: parsed.data.name,
+                persistence: parsed.data.persistence,
             });
             return c.json({ project }, 201);
         }
@@ -942,7 +1425,7 @@ export function createApp(options = {}) {
     });
     // -------------------------------------------------------------------------
     // POST /api/filesystem/inspect — registry-agnostic directory inspection.
-    // POST /api/projects/onboard   — generate ide.yml + register the project.
+    // POST /api/projects/onboard   — generate workspace.yml + register the project.
     // -------------------------------------------------------------------------
     app.post("/api/projects/onboard", async (c) => {
         let body;
@@ -971,9 +1454,9 @@ export function createApp(options = {}) {
             }
             throw err;
         }
-        // Never overwrite an existing ide.yml.
+        // Never overwrite an existing workspace or legacy config.
         try {
-            assertNoExistingIdeYml(dir);
+            await assertNoExistingIdeYml(dir);
         }
         catch (err) {
             if (err instanceof OnboardConflictError) {
@@ -1030,7 +1513,10 @@ function listAvailableTemplates() {
     // Repo-root templates/ — 4 levels up from packages/daemon/src/command-center/.
     // Pre-fold this lived at <pkg>/templates (..,.. worked); post-fold the
     // canonical templates dir is at the repo root.
-    const templatesDir = join(__dir, "..", "..", "..", "..", "templates");
+    const configuredTemplatesDir = process.env.TMUX_IDE_TEMPLATES_DIR;
+    const templatesDir = configuredTemplatesDir && isAbsolute(configuredTemplatesDir)
+        ? configuredTemplatesDir
+        : join(__dir, "..", "..", "..", "..", "templates");
     if (!existsSync(templatesDir))
         return [];
     const labels = {
@@ -1082,7 +1568,7 @@ function listAvailableTemplates() {
  * SSE endpoints (`/api/events`, `/api/project/<name>/stream`) continue to
  * work alongside this — they will be retired in a follow-up slice.
  */
-export function attachWsEvents(server) {
+export function attachWsEvents(server, daemonIdentity) {
     const wss = new WebSocketServer({ noServer: true });
     const upgradeListener = (req, socket, head) => {
         const url = req.url ?? "/";
@@ -1090,7 +1576,10 @@ export function attachWsEvents(server) {
         if (pathname !== "/ws/events")
             return;
         wss.handleUpgrade(req, socket, head, (ws) => {
-            handleWsEventsConnection(ws);
+            const requestUrl = new URL(req.url ?? "/ws/events", "http://daemon.local");
+            handleWsEventsConnection(ws, daemonIdentity, {
+                mode: requestUrl.searchParams.get("mode") === "semantic" ? "semantic" : "legacy",
+            });
         });
     };
     server.on("upgrade", upgradeListener);