@opengeni/api-router 0.5.2 → 0.5.4

package/src/routes/sessions.ts

@@ -2,6 +2,7 @@ import {
   AcknowledgeStreamRequest,
   AttachViewerRequest,
   ClearSessionContextRequest,
+  CancelSessionQueueItemRequest,
   ClientSessionEvent,
   CompactSessionContextRequest,
   FsDeleteRequest,
@@ -18,11 +19,12 @@ import {
   PtyOpenRequest,
   PtyResizeRequest,
   PtyWriteRequest,
-  ReorderSessionTurnsRequest,
+  SessionControlRequest,
+  SteerSessionMessageRequest,
   TerminalExecRequest,
+  UpdateSessionPinRequest,
   UpdateSessionGoalRequest,
   UpdateSessionRequest,
-  UpdateSessionTurnRequest,
   ViewerHeartbeatRequest,
   type SandboxBackend,
   type Session,
@@ -30,57 +32,79 @@ import {
   type TerminalPtyOutputDeltaPayload,
   type TerminalPtyStartedPayload,
 } from "@opengeni/contracts";
-import { resolveContextCompactionMode, streamTokenDegraded } from "@opengeni/config";
+import { streamTokenDegraded } from "@opengeni/config";
 import {
-  cancelQueuedSessionTurn,
+  cancelQueuedSessionTurnWithVersion,
+  acceptSessionApprovalDecision,
+  clearSessionGoal,
   clearSessionContext,
   closePtySession,
   getOpenPtySession,
   getSandbox,
   getSession,
+  getSessionForSubject,
   getSessionGoal,
+  getSessionQueueSnapshot,
   getStreamAcknowledgment,
   insertPtySession,
   listSessionEvents,
   listSessionIdsInGroup,
-  listSessions,
+  listSessionsForSubject,
   listSessionTurns,
   recordStreamAcknowledgment,
-  reorderQueuedSessionTurns,
   requestSessionCompaction,
-  requireSession,
   setSessionCodexPin,
+  withCodexCapacityMutation,
+  setSessionPin,
+  SessionPinVersionConflictError,
+  SessionPinAccessError,
+  SessionListAccessError,
+  SessionListCursorError,
+  decodeSessionListCursor,
   revokeViewer,
   setSessionGoalStatus,
   updatePtySessionActivity,
-  updateQueuedSessionTurn,
+  requestSessionControl,
+  SessionQueueConflictError,
+  SessionContextBusyError,
+  latestWorkspaceCapture,
+  workspaceCaptureAtRevision,
   type AppendEventInput,
 } from "@opengeni/db";
-import { appendAndPublishEvents, coalesceSessionEventDeltas } from "@opengeni/events";
+import {
+  appendAndPublishEvents,
+  coalesceSessionEventDeltas,
+  publishDurableSessionEvents,
+} from "@opengeni/events";
+import { z } from "zod";
 import { withChannelA } from "../sandbox/channel-a";
 import { negotiateCapabilities } from "@opengeni/runtime/sandbox";
 import type { Context, Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
 import { requireAccessGrant } from "@opengeni/core";
 import type { ApiRouteDeps } from "@opengeni/core";
-import { attachViewer, detachViewer, heartbeatViewer, mintDesktopStream, mintTerminalStream, readGroupLease, resolveActiveDesktopTransport, viewerHeartbeatIntervalMs, type DesktopStreamMint, type TerminalStreamMint } from "../sandbox/viewer";
-import { settingsWithEnabledCapabilityMcpServers, settingsWithSessionMcpServerMetadata } from "@opengeni/core";
 import {
-  normalizeResources,
-  validateFileResources,
-  validateGitHubRepositorySelection,
-  validateToolRefs,
-} from "@opengeni/core";
+  attachViewer,
+  detachViewer,
+  heartbeatViewer,
+  mintDesktopStream,
+  mintTerminalStream,
+  readGroupLease,
+  resolveActiveDesktopTransport,
+  viewerHeartbeatIntervalMs,
+  type DesktopStreamMint,
+  type TerminalStreamMint,
+} from "../sandbox/viewer";
 import {
   acceptSessionUserMessage,
-  assertConfiguredModel,
   createSessionForRequest,
-  requireQueuedTurnForApi,
+  readSessionLineage,
   updateSessionTitle,
   workflowIdForSession,
 } from "@opengeni/core";
 import { assertSessionExists, boundedLimit } from "../http/common";
 import { sseSessionStream } from "../http/sse";
+import { serveWorkspaceCapture, serveWorkspaceCaptureFile } from "./workspace-capture";
 
 export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
   const { settings, db, bus, workflowClient, objectStorage } = deps;
@@ -94,20 +118,97 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
 
   app.get("/v1/workspaces/:workspaceId/sessions", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "sessions:read");
-    return c.json(await listSessions(db, workspaceId, boundedLimit(c.req.query("limit"))));
+    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:read");
+    const pageView = c.req.query("view") === "page";
+    const query = sessionListQuery(c.req.query(), pageView);
+    let page: Awaited<ReturnType<typeof listSessionsForSubject>>;
+    try {
+      page = await listSessionsForSubject(db, workspaceId, {
+        subjectId: grant.subjectId,
+        limit: boundedLimit(query.limit),
+        ...(query.cursor ? { cursor: query.cursor } : {}),
+        ...(query.search ? { search: query.search } : {}),
+        ...(query.parentSessionId !== undefined ? { parentSessionId: query.parentSessionId } : {}),
+      });
+    } catch (error) {
+      if (error instanceof SessionListAccessError) {
+        throw new HTTPException(403, { message: error.message });
+      }
+      if (error instanceof SessionListCursorError) {
+        throw new HTTPException(400, { message: error.message });
+      }
+      throw error;
+    }
+    if (pageView) {
+      return c.json(page);
+    }
+    // Same-major compatibility: listSessions() has historically returned an
+    // array. Preserve that wire shape while adding personal pin metadata/order;
+    // cursor consumers opt into the additive page view. A query flag rather
+    // than a /sessions/page path is deliberate: an older API safely ignores it
+    // and returns its historical array instead of treating "page" as a UUID.
+    return c.json([...page.pinned, ...page.sessions]);
   });
 
   app.get("/v1/workspaces/:workspaceId/sessions/:sessionId", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "sessions:read");
-    const session = await getSession(db, workspaceId, c.req.param("sessionId"));
+    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:read");
+    const sessionId = c.req.param("sessionId");
+    if (!z.string().uuid().safeParse(sessionId).success) {
+      throw new HTTPException(404, { message: "session not found" });
+    }
+    const session = await getSessionForSubject(db, workspaceId, sessionId, grant.subjectId);
     if (!session) {
       throw new HTTPException(404, { message: "session not found" });
     }
     return c.json(session);
   });
 
+  // Personal pin only: this is organization state for the authenticated member,
+  // not a mutation of the shared session. It deliberately requires read access
+  // (not session control) and returns 404 for a foreign/inaccessible session.
+  app.put("/v1/workspaces/:workspaceId/sessions/:sessionId/pin", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:read");
+    const sessionId = c.req.param("sessionId");
+    if (!z.string().uuid().safeParse(sessionId).success) {
+      throw new HTTPException(404, { message: "session not found" });
+    }
+    const parsed = UpdateSessionPinRequest.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) {
+      throw new HTTPException(400, { message: "invalid session pin request" });
+    }
+    try {
+      const session = await setSessionPin(db, {
+        workspaceId,
+        subjectId: grant.subjectId,
+        sessionId,
+        ...parsed.data,
+      });
+      if (!session) {
+        throw new HTTPException(404, { message: "session not found" });
+      }
+      return c.json(session);
+    } catch (error) {
+      if (error instanceof SessionPinAccessError) {
+        throw new HTTPException(403, { message: error.message });
+      }
+      if (error instanceof SessionPinVersionConflictError) {
+        return c.json(
+          { message: "session pin changed in another client", current: error.current },
+          409,
+        );
+      }
+      throw error;
+    }
+  });
+
+  app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/lineage", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "sessions:read");
+    return c.json(await readSessionLineage(db, workspaceId, c.req.param("sessionId")));
+  });
+
   // Pin (or unpin) the session's Codex account. body { target: "auto" | "<id>" }:
   // "auto" clears the pin (the session follows the workspace active pointer); a
   // uuid pins the session to that specific account. The pin applies to the NEXT
@@ -120,13 +221,41 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     const body = (await c.req.json()) as { target?: string };
     const target = typeof body.target === "string" ? body.target : "";
     if (!target) {
-      throw new HTTPException(400, { message: "target is required (\"auto\" or an account id)" });
+      throw new HTTPException(400, { message: 'target is required ("auto" or an account id)' });
     }
     const pinned = target === "auto" ? null : target;
-    const ok = await setSessionCodexPin(db, workspaceId, sessionId, pinned);
+    const mutation = await withCodexCapacityMutation(
+      db,
+      { workspaceId, reason: "codex_manual_session_pin_changed" },
+      async (tx) => {
+        const changed = await setSessionCodexPin(tx, workspaceId, sessionId, pinned);
+        return { result: changed, changed };
+      },
+    );
+    const ok = mutation.result;
     if (!ok) {
       throw new HTTPException(404, { message: "session or codex account not found" });
     }
+    await Promise.allSettled(
+      mutation.wakeTargets.map((wake) =>
+        workflowClient.signalCodexCapacity
+          ? workflowClient.signalCodexCapacity({
+              accountId: wake.accountId,
+              workspaceId: wake.workspaceId,
+              sessionId: wake.sessionId,
+              workflowId: wake.workflowId,
+              wakeRevision: wake.wakeRevision,
+              workflowWakeRevision: wake.workflowWakeRevision,
+            })
+          : workflowClient.wakeSessionWorkflow({
+              accountId: wake.accountId,
+              workspaceId: wake.workspaceId,
+              sessionId: wake.sessionId,
+              workflowId: wake.workflowId,
+              wakeRevision: wake.workflowWakeRevision,
+            }),
+      ),
+    );
     return c.json({ pinned: target === "auto" ? "auto" : target });
   });
 
@@ -135,12 +264,15 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
   // agent writes. Returns the refreshed session, mirroring GET detail.
   app.patch("/v1/workspaces/:workspaceId/sessions/:sessionId", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "sessions:control");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:control");
     const sessionId = c.req.param("sessionId");
     await assertSessionExists(db, workspaceId, sessionId);
     const payload = UpdateSessionRequest.parse(await c.req.json());
     await updateSessionTitle({ db, bus }, workspaceId, sessionId, payload.title, "user");
-    const session = await getSession(db, workspaceId, sessionId);
+    // A session-returning member route must preserve the caller's private pin
+    // projection. Returning the generic mapSession() default here would reset a
+    // pinned React consumer to false/version 0 after a harmless rename.
+    const session = await getSessionForSubject(db, workspaceId, sessionId, grant.subjectId);
     if (!session) {
       throw new HTTPException(404, { message: "session not found" });
     }
@@ -170,7 +302,9 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
       throw new HTTPException(404, { message: "session goal not found" });
     }
     if (existing.status === "completed") {
-      throw new HTTPException(409, { message: "session goal is completed; set a new goal instead" });
+      throw new HTTPException(409, {
+        message: "session goal is completed; set a new goal instead",
+      });
     }
     if (payload.status === "paused") {
       const { goal, changed } = await setSessionGoalStatus(db, workspaceId, sessionId, {
@@ -179,45 +313,86 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
         pausedReason: "api",
       });
       if (changed) {
-        await appendAndPublishEvents(db, bus, workspaceId, sessionId, [{
-          type: "goal.paused",
-          payload: {
-            goalId: goal.id,
-            actor: "api",
-            reason: "api",
-            ...(payload.rationale ? { rationale: payload.rationale } : {}),
-            autoContinuations: goal.autoContinuations,
-            noProgressStreak: goal.noProgressStreak,
+        await appendAndPublishEvents(db, bus, workspaceId, sessionId, [
+          {
+            type: "goal.paused",
+            payload: {
+              goalId: goal.id,
+              actor: "api",
+              reason: "api",
+              ...(payload.rationale ? { rationale: payload.rationale } : {}),
+              autoContinuations: goal.autoContinuations,
+              noProgressStreak: goal.noProgressStreak,
+            },
           },
-        }]);
+        ]);
       }
       return c.json(goal);
     }
     // Resume: only valid from paused; resets counters and re-arms the loop.
     if (existing.status !== "paused") {
-      throw new HTTPException(409, { message: `session goal is ${existing.status}; only paused goals can be resumed` });
+      throw new HTTPException(409, {
+        message: `session goal is ${existing.status}; only paused goals can be resumed`,
+      });
     }
-    const { goal, changed } = await setSessionGoalStatus(db, workspaceId, sessionId, { status: "active" });
+    const { goal, changed, workflowWakeRevision } = await setSessionGoalStatus(
+      db,
+      workspaceId,
+      sessionId,
+      {
+        status: "active",
+      },
+    );
     // `changed` guards the racing-PATCH case: both requests can pass the
     // status pre-check, but only the transition winner emits and wakes.
     if (changed) {
-      await appendAndPublishEvents(db, bus, workspaceId, sessionId, [{
-        type: "goal.resumed",
-        payload: {
-          goalId: goal.id,
-          text: goal.text,
-          ...(goal.successCriteria ? { successCriteria: goal.successCriteria } : {}),
-          version: goal.version,
-          actor: "api",
+      await appendAndPublishEvents(db, bus, workspaceId, sessionId, [
+        {
+          type: "goal.resumed",
+          payload: {
+            goalId: goal.id,
+            text: goal.text,
+            ...(goal.successCriteria ? { successCriteria: goal.successCriteria } : {}),
+            version: goal.version,
+            actor: "api",
+          },
         },
-      }]);
-      // signalWithStart restarts a completed workflow whose first claim finds no
-      // queued turn, so maybeContinueGoal fires — resume works on an idle session.
-      await workflowClient.wakeSessionWorkflow({ accountId: grant.accountId, workspaceId, sessionId, workflowId: workflowIdForSession(sessionId) });
+      ]);
+      // signalWithStart restarts an eligible idle workflow so maybeContinueGoal
+      // fires. A closed workspace/session gate keeps the resumed goal durable
+      // and inert until that gate's own Resume mutation commits its wake.
+      if (workflowWakeRevision !== null) {
+        await workflowClient.wakeSessionWorkflow({
+          accountId: grant.accountId,
+          workspaceId,
+          sessionId,
+          workflowId: workflowIdForSession(sessionId),
+          wakeRevision: workflowWakeRevision,
+        });
+      }
     }
     return c.json(goal);
   });
 
+  app.delete("/v1/workspaces/:workspaceId/sessions/:sessionId/goal", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "sessions:control");
+    const sessionId = c.req.param("sessionId");
+    await assertSessionExists(db, workspaceId, sessionId);
+    const { event } = await clearSessionGoal(db, workspaceId, sessionId);
+    if (event) {
+      try {
+        await bus.publish(workspaceId, sessionId, [event]);
+      } catch (error) {
+        console.warn(
+          `[api] live publish failed for cleared goal ${workspaceId}/${sessionId}; event is durable and reconciles on replay`,
+          error,
+        );
+      }
+    }
+    return c.body(null, 204);
+  });
+
   // Operator context controls (slash-command palette: /clear, /compact). These
   // are session/operator actions — NOT a structured channel to the agent. Both
   // require sessions:control.
@@ -232,51 +407,53 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     // missing/false confirm is a client error (400), not a server fault.
     const clearBody = ClearSessionContextRequest.safeParse(await c.req.json().catch(() => ({})));
     if (!clearBody.success) {
-      throw new HTTPException(400, { message: "context clear requires an explicit { confirm: true }" });
-    }
-    const session = await requireSession(db, workspaceId, sessionId);
-    // Clearing mid-turn would strand the in-flight RunState (and, in
-    // requires_action, an awaiting approval whose resume needs that blob).
-    // Refuse, mirroring the goal 409 guards.
-    if (session.status === "queued" || session.status === "running" || session.status === "requires_action") {
-      throw new HTTPException(409, { message: `session is ${session.status}; cannot clear context mid-turn — stop the turn first` });
+      throw new HTTPException(400, {
+        message: "context clear requires an explicit { confirm: true }",
+      });
     }
-    const result = await clearSessionContext(db, { accountId: grant.accountId, workspaceId, sessionId });
-    await appendAndPublishEvents(db, bus, workspaceId, sessionId, [{
-      type: "session.context.cleared",
-      payload: {
-        clearedBy: "api",
-        supersededItems: result.supersededItems,
-        markerPosition: result.markerPosition,
+    // The database checks this under workspace/session locks so a turn cannot
+    // start between an API precheck and the history rewrite.
+    const result = await clearSessionContext(db, {
+      accountId: grant.accountId,
+      workspaceId,
+      sessionId,
+    }).catch((error: unknown) => {
+      if (error instanceof SessionContextBusyError) {
+        throw new HTTPException(409, { message: error.message });
+      }
+      throw error;
+    });
+    await appendAndPublishEvents(db, bus, workspaceId, sessionId, [
+      {
+        type: "session.context.cleared",
+        payload: {
+          clearedBy: "api",
+          supersededItems: result.supersededItems,
+          markerPosition: result.markerPosition,
+        },
       },
-    }]);
+    ]);
     return c.body(null, 204);
   });
 
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/context/compact", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "sessions:control");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:control");
     const sessionId = c.req.param("sessionId");
     await assertSessionExists(db, workspaceId, sessionId);
     CompactSessionContextRequest.parse((await c.req.json().catch(() => ({}))) ?? {});
-    // /compact is only a TRIGGER — it never duplicates the compaction engine.
-    // Client-managed (Azure) path: set a durable request flag the worker honors
-    // before the next turn (forced compaction). Server-managed provider / off:
-    // compaction is automatic or disabled, so this is an honest no-op.
-    //
-    // Integration seam with provider-aware-compaction: when that work exposes a
-    // synchronous "compact now" entry callable from the API process, this route
-    // should call it directly and return its result; until then the flag +
-    // worker maybeCompactContext(force) is the minimal honored interface.
-    const mode = resolveContextCompactionMode(settings);
-    if (mode === "client") {
-      await requestSessionCompaction(db, workspaceId, sessionId);
-      return c.json({ status: "queued", message: "Compaction will run before the next turn." });
-    }
-    if (mode === "server") {
-      return c.json({ status: "noop", message: "This session's provider compacts context automatically; no manual compaction is needed." });
-    }
-    return c.json({ status: "noop", message: "Context compaction is disabled for this session." });
+    // /compact sets one durable request. The worker clears it only in the same
+    // fenced transaction that installs replacement history, so failed or stale
+    // attempts cannot lose the request.
+    const requested = await requestSessionCompaction(db, workspaceId, sessionId);
+    await workflowClient.wakeSessionWorkflow({
+      accountId: grant.accountId,
+      workspaceId,
+      sessionId,
+      workflowId: requested.temporalWorkflowId,
+      wakeRevision: requested.wakeRevision,
+    });
+    return c.json({ status: "pending", message: "Compaction will run at the next safe boundary." });
   });
 
   app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/events", async (c) => {
@@ -302,7 +479,14 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     const sessionId = c.req.param("sessionId");
     await assertSessionExists(db, workspaceId, sessionId);
     const after = Number(c.req.query("after") ?? c.req.header("Last-Event-ID") ?? 0);
-    return sseSessionStream(db, bus, workspaceId, sessionId, Number.isFinite(after) ? after : 0, c.req.raw.signal);
+    return sseSessionStream(
+      db,
+      bus,
+      workspaceId,
+      sessionId,
+      Number.isFinite(after) ? after : 0,
+      c.req.raw.signal,
+    );
   });
 
   app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/turns", async (c) => {
@@ -310,78 +494,157 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     await requireAccessGrant(c, deps, workspaceId, "sessions:read");
     const sessionId = c.req.param("sessionId");
     await assertSessionExists(db, workspaceId, sessionId);
-    return c.json(await listSessionTurns(db, workspaceId, sessionId, boundedLimit(c.req.query("limit"))));
+    return c.json(
+      await listSessionTurns(db, workspaceId, sessionId, boundedLimit(c.req.query("limit"))),
+    );
   });
 
-  app.patch("/v1/workspaces/:workspaceId/sessions/:sessionId/turns/:turnId", async (c) => {
+  app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/queue", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "sessions:control");
+    await requireAccessGrant(c, deps, workspaceId, "sessions:read");
+    const sessionId = c.req.param("sessionId");
+    const snapshot = await getSessionQueueSnapshot(db, workspaceId, sessionId);
+    if (!snapshot) throw new HTTPException(404, { message: "session not found" });
+    return c.json(snapshot);
+  });
+
+  app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/queue/:turnId/cancel", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:control");
     const sessionId = c.req.param("sessionId");
-    const turnId = c.req.param("turnId");
     await assertSessionExists(db, workspaceId, sessionId);
-    const existing = await requireQueuedTurnForApi(db, workspaceId, sessionId, turnId);
-    const payload = UpdateSessionTurnRequest.parse(await c.req.json());
-    // A turn-update may switch the queued turn's model; reject one the host
-    // does not expose (omitted leaves the existing model unchanged).
-    assertConfiguredModel(settings, payload.model);
-    const session = await requireSession(db, workspaceId, sessionId);
-    const runtimeSettings = settingsWithSessionMcpServerMetadata(
-      await settingsWithEnabledCapabilityMcpServers(db, workspaceId, settings),
-      session.mcpServers,
-    );
-    const resources = payload.resources !== undefined ? normalizeResources(payload.resources) : existing.resources;
-    const tools = payload.tools !== undefined ? validateToolRefs(payload.tools, runtimeSettings) : existing.tools;
-    if (resources.some((resource) => resource.kind === "file") && !objectStorage) {
-      throw new HTTPException(503, { message: "object storage is not configured" });
+    const payload = CancelSessionQueueItemRequest.parse(await c.req.json());
+    try {
+      const result = await cancelQueuedSessionTurnWithVersion(
+        db,
+        workspaceId,
+        sessionId,
+        c.req.param("turnId"),
+        payload.expectedQueueVersion,
+        payload.expectedItemVersion,
+        grant.subjectId,
+        payload.reason ?? null,
+      );
+      await bus.publish(workspaceId, sessionId, result.events);
+      if (result.shouldWake) {
+        if (result.workflowWakeRevision === null) {
+          throw new Error("Queue continuation has no workflow wake revision");
+        }
+        await workflowClient.wakeSessionWorkflow({
+          accountId: grant.accountId,
+          workspaceId,
+          sessionId,
+          workflowId: workflowIdForSession(sessionId),
+          wakeRevision: result.workflowWakeRevision,
+        });
+      }
+      return c.json(result);
+    } catch (error) {
+      throwQueueConflict(error);
     }
-    await validateFileResources(db, workspaceId, resources);
-    await validateGitHubRepositorySelection(db, workspaceId, [...session.resources, ...resources]);
-    const turn = await updateQueuedSessionTurn(db, workspaceId, turnId, {
-      ...(payload.prompt !== undefined ? { prompt: payload.prompt.trim() } : {}),
-      ...(payload.model !== undefined ? { model: payload.model } : {}),
-      ...(payload.reasoningEffort !== undefined ? { reasoningEffort: payload.reasoningEffort } : {}),
-      ...(payload.sandboxBackend !== undefined ? { sandboxBackend: payload.sandboxBackend } : {}),
-      ...(payload.metadata !== undefined ? { metadata: payload.metadata } : {}),
-      resources,
-      tools,
-    });
-    await appendAndPublishEvents(db, bus, workspaceId, sessionId, [{
-      type: "turn.updated",
-      turnId: turn.id,
-      payload: { turnId: turn.id },
-    }]);
-    return c.json(turn);
   });
 
-  app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/turns/reorder", async (c) => {
+  app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/control", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:control");
     const sessionId = c.req.param("sessionId");
-    await assertSessionExists(db, workspaceId, sessionId);
-    const payload = ReorderSessionTurnsRequest.parse(await c.req.json());
-    const turns = await reorderQueuedSessionTurns(db, workspaceId, sessionId, payload.turnIds);
-    await appendAndPublishEvents(db, bus, workspaceId, sessionId, [{
-      type: "turn.updated",
-      payload: { reorderedTurnIds: payload.turnIds },
-    }]);
-    await workflowClient.wakeSessionWorkflow({ accountId: grant.accountId, workspaceId, sessionId, workflowId: workflowIdForSession(sessionId) });
-    return c.json(turns);
+    const payload = SessionControlRequest.parse(await c.req.json());
+    let result;
+    try {
+      result = await requestSessionControl(db, {
+        accountId: grant.accountId,
+        workspaceId,
+        sessionId,
+        actor: grant.subjectId,
+        mode: payload.mode,
+        reason: payload.reason ?? null,
+        clientEventId: payload.clientEventId ?? null,
+        ...(payload.expectedControlState !== undefined
+          ? { expectedControlState: payload.expectedControlState }
+          : {}),
+        ...(payload.expectedControlGeneration !== undefined
+          ? { expectedControlGeneration: payload.expectedControlGeneration }
+          : {}),
+        ...(payload.expectedWorkspaceInferenceGeneration !== undefined
+          ? {
+              expectedWorkspaceInferenceGeneration: payload.expectedWorkspaceInferenceGeneration,
+            }
+          : {}),
+      });
+    } catch (error) {
+      throwQueueConflict(error);
+    }
+    await bus.publish(workspaceId, sessionId, result.events);
+    const workflowId = workflowIdForSession(sessionId);
+    if (result.shouldSignalControl) {
+      if (result.workflowWakeRevision === null) {
+        throw new Error("Session control has no workflow wake revision");
+      }
+      await workflowClient.signalSessionControl({
+        accountId: grant.accountId,
+        workspaceId,
+        sessionId,
+        eventId: result.event.id,
+        workflowId,
+        workflowWakeRevision: result.workflowWakeRevision,
+      });
+    } else if (result.shouldWake) {
+      if (result.workflowWakeRevision === null) {
+        throw new Error("Session resume has no workflow wake revision");
+      }
+      await workflowClient.wakeSessionWorkflow({
+        accountId: grant.accountId,
+        workspaceId,
+        sessionId,
+        workflowId,
+        wakeRevision: result.workflowWakeRevision,
+      });
+    }
+    return c.json(
+      {
+        operationId: result.operationId,
+        event: result.event,
+        controlState: result.controlState,
+        controlGeneration: result.controlGeneration,
+        expectedActiveTurnId: result.expectedActiveTurnId,
+        expectedExecutionGeneration: result.expectedExecutionGeneration,
+        expectedAttemptId: result.expectedAttemptId,
+        deliveryEventId: result.deliveryEventId,
+        shouldSignalControl: result.shouldSignalControl,
+        shouldWake: result.shouldWake,
+      },
+      202,
+    );
   });
 
-  app.delete("/v1/workspaces/:workspaceId/sessions/:sessionId/turns/:turnId", async (c) => {
+  app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/steer", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "sessions:control");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:control");
     const sessionId = c.req.param("sessionId");
-    const turnId = c.req.param("turnId");
     await assertSessionExists(db, workspaceId, sessionId);
-    await requireQueuedTurnForApi(db, workspaceId, sessionId, turnId);
-    const turn = await cancelQueuedSessionTurn(db, workspaceId, turnId);
-    await appendAndPublishEvents(db, bus, workspaceId, sessionId, [{
-      type: "turn.cancelled",
-      turnId: turn.id,
-      payload: { turnId: turn.id, triggerEventId: turn.triggerEventId },
-    }]);
-    return c.json(turn);
+    const raw = await c.req.json();
+    const payload = SteerSessionMessageRequest.parse(raw);
+    const result = await acceptSessionUserMessage(deps, grant, workspaceId, sessionId, {
+      text: payload.text,
+      resources: payload.resources,
+      tools: payload.tools,
+      toolsProvided: userMessagePayloadHasOwnProperty({ payload: raw }, "tools"),
+      model: payload.model ?? null,
+      reasoningEffort: payload.reasoningEffort ?? null,
+      mcpCredentialUpdates: payload.mcpCredentialUpdates ?? [],
+      delivery: "steer",
+      origin: "human",
+      ...(payload.expectedControlGeneration !== undefined
+        ? { expectedControlGeneration: payload.expectedControlGeneration }
+        : {}),
+      ...(payload.expectedWorkspaceInferenceGeneration !== undefined
+        ? {
+            expectedWorkspaceInferenceGeneration: payload.expectedWorkspaceInferenceGeneration,
+          }
+        : {}),
+      ...(payload.clientEventId ? { clientEventId: payload.clientEventId } : {}),
+    });
+    return c.json(result, 202);
   });
 
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/events", async (c) => {
@@ -404,33 +667,31 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
       return c.json(accepted, 202);
     }
 
-    const session = await requireSession(db, workspaceId, sessionId);
-    if (event.type === "user.approvalDecision" && session.status !== "requires_action") {
-      throw new HTTPException(409, { message: `session is ${session.status}; no approval is pending` });
-    }
-    const eventsToAppend: AppendEventInput[] = [{
-      type: event.type,
-      payload: event.payload,
-      ...(event.clientEventId ? { clientEventId: event.clientEventId } : {}),
-    }];
-    const appended = await appendAndPublishEvents(db, bus, workspaceId, sessionId, eventsToAppend);
-    const accepted = appended[0];
-    if (!accepted) {
-      throw new HTTPException(500, { message: "failed to append client event" });
-    }
-    const workflowId = workflowIdForSession(sessionId);
     if (event.type === "user.approvalDecision") {
-      await workflowClient.signalApprovalDecision({ sessionId, eventId: accepted.id, workflowId });
-    } else {
-      await workflowClient.signalInterrupt({
+      const accepted = await acceptSessionApprovalDecision(db, {
+        accountId: grant.accountId,
+        workspaceId,
+        sessionId,
+        payload: event.payload,
+        clientEventId: event.clientEventId ?? null,
+      });
+      if (accepted.action === "conflict") {
+        throw new HTTPException(409, {
+          message: `session is ${accepted.sessionStatus}; no unhandled approval is pending`,
+        });
+      }
+      await publishDurableSessionEvents(bus, workspaceId, sessionId, accepted.events);
+      const workflowId = workflowIdForSession(sessionId);
+      await workflowClient.signalApprovalDecision({
         accountId: grant.accountId,
         workspaceId,
         sessionId,
-        eventId: accepted.id,
+        eventId: accepted.event.id,
         workflowId,
+        workflowWakeRevision: accepted.workflowWakeRevision,
       });
+      return c.json(accepted.event, 202);
     }
-    return c.json(accepted, 202);
   });
 
   // ── API-direct stream capabilities + viewer attach (P1.4) ─────────────────
@@ -449,7 +710,9 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
       // The viewer-holder lifecycle rides the sandbox lease, which is dormant
       // until the flag flips per-environment. A 404 (not 403) keeps the route
       // invisible while disabled — it does not exist for this deployment yet.
-      throw new HTTPException(404, { message: "sandbox ownership is not enabled for this deployment" });
+      throw new HTTPException(404, {
+        message: "sandbox ownership is not enabled for this deployment",
+      });
     }
   }
 
@@ -479,7 +742,10 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     if (!session) {
       throw new HTTPException(404, { message: "session not found" });
     }
-    const lease = await readGroupLease({ db, settings }, { workspaceId, sandboxGroupId: session.sandboxGroupId });
+    const lease = await readGroupLease(
+      { db, settings },
+      { workspaceId, sandboxGroupId: session.sandboxGroupId },
+    );
     const { shared, sharedSessionIds } = await resolveSharedExposure(workspaceId, session);
     // Per-principal acknowledgment: A acknowledging does not consent for B. The
     // un-redacted desktop stream ALWAYS requires the un-redacted ack; a shared box
@@ -488,8 +754,14 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     // WITHOUT un-redacted consent could be handed a live VNC URL + scoped token
     // from this read path while being correctly 409'd on attach (a consent-gate
     // bypass of the un-redacted pixel plane).
-    const ack = await getStreamAcknowledgment(db, { workspaceId, sandboxGroupId: session.sandboxGroupId, subjectId: grant.subjectId });
-    const acknowledged = ack ? (ack.acknowledgedUnredacted && (!shared || ack.acknowledgedShared)) : false;
+    const ack = await getStreamAcknowledgment(db, {
+      workspaceId,
+      sandboxGroupId: session.sandboxGroupId,
+      subjectId: grant.subjectId,
+    });
+    const acknowledged = ack
+      ? ack.acknowledgedUnredacted && (!shared || ack.acknowledgedShared)
+      : false;
 
     // P4.2 — the pixel DATA PLANE, served API-direct. When the backend is
     // desktop-capable AND sandboxDesktopEnabled AND the (shared, if shared)
@@ -502,22 +774,27 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     // (no secret / display-stack or tunnel failure) returns null → transport:null.
     let desktopStream: DesktopStreamMint | null = null;
     const desktopUnlocked =
-      settings.sandboxDesktopEnabled
-      && !streamTokenDegraded(settings)
-      && acknowledged
-      && (session.activeSandboxId != null || lease?.liveness === "warm" || lease?.liveness === "draining");
+      settings.sandboxDesktopEnabled &&
+      !streamTokenDegraded(settings) &&
+      acknowledged &&
+      (session.activeSandboxId != null ||
+        lease?.liveness === "warm" ||
+        lease?.liveness === "draining");
     if (desktopUnlocked) {
-      desktopStream = await mintDesktopStream({ db, settings, bus }, {
-        accountId: grant.accountId,
-        workspaceId,
-        session,
-        // The handshake's token is scoped to the calling principal (it is a read,
-        // not a viewer-holder acquire); the per-holder token is re-minted on
-        // POST /viewers. A previousEpoch != current would have rotated already
-        // via the warming-commit; the read does not itself drive rotation.
-        viewerId: grant.subjectId,
-        ...(lease ? { lease } : {}),
-      });
+      desktopStream = await mintDesktopStream(
+        { db, settings, bus },
+        {
+          accountId: grant.accountId,
+          workspaceId,
+          session,
+          // The handshake's token is scoped to the calling principal (it is a read,
+          // not a viewer-holder acquire); the per-holder token is re-minted on
+          // POST /viewers. A previousEpoch != current would have rotated already
+          // via the warming-commit; the read does not itself drive rotation.
+          viewerId: grant.subjectId,
+          ...(lease ? { lease } : {}),
+        },
+      );
     }
 
     // P5.t — the REAL PTY terminal cell, served API-DIRECT. Independent of the
@@ -527,17 +804,22 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     // returns null → the Terminal cell falls back to the sse-events firehose.
     let terminalStream: TerminalStreamMint | null = null;
     const terminalUnlocked =
-      settings.sandboxTerminalEnabled
-      && !streamTokenDegraded(settings)
-      && (session.activeSandboxId != null || lease?.liveness === "warm" || lease?.liveness === "draining");
+      settings.sandboxTerminalEnabled &&
+      !streamTokenDegraded(settings) &&
+      (session.activeSandboxId != null ||
+        lease?.liveness === "warm" ||
+        lease?.liveness === "draining");
     if (terminalUnlocked) {
-      terminalStream = await mintTerminalStream({ db, settings, bus }, {
-        accountId: grant.accountId,
-        workspaceId,
-        session,
-        viewerId: grant.subjectId,
-        ...(lease ? { lease } : {}),
-      });
+      terminalStream = await mintTerminalStream(
+        { db, settings, bus },
+        {
+          accountId: grant.accountId,
+          workspaceId,
+          session,
+          viewerId: grant.subjectId,
+          ...(lease ? { lease } : {}),
+        },
+      );
     }
 
     const capabilities = negotiateCapabilities({
@@ -611,8 +893,13 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     // place (resolveActiveDesktopTransport), covering BOTH swap directions.
     let responseCapabilities = capabilities;
     if (capabilities.DesktopStream.transport !== null) {
-      const activeSandbox = session.activeSandboxId ? await getSandbox(db, workspaceId, session.activeSandboxId) : null;
-      const wire = resolveActiveDesktopTransport(activeSandbox?.kind === "selfhosted", settings.sandboxDesktopInteractive !== false);
+      const activeSandbox = session.activeSandboxId
+        ? await getSandbox(db, workspaceId, session.activeSandboxId)
+        : null;
+      const wire = resolveActiveDesktopTransport(
+        activeSandbox?.kind === "selfhosted",
+        settings.sandboxDesktopInteractive !== false,
+      );
       responseCapabilities = {
         ...capabilities,
         DesktopStream: { ...capabilities.DesktopStream, ...wire },
@@ -626,29 +913,35 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
   // shared-exposure disclosure). Reuses the acknowledgment machinery — gated on
   // stream:acknowledge, no new permission. Until this is recorded the
   // desktop-stream (viewer attach) path returns 409 (P3.2 consent gate).
-  app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/stream-capabilities/acknowledge", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "stream:acknowledge");
-    assertOwnershipEnabled();
-    const sessionId = c.req.param("sessionId");
-    const session = await getSession(db, workspaceId, sessionId);
-    if (!session) {
-      throw new HTTPException(404, { message: "session not found" });
-    }
-    const parsed = AcknowledgeStreamRequest.safeParse(await c.req.json().catch(() => ({})));
-    if (!parsed.success) {
-      throw new HTTPException(400, { message: "invalid stream acknowledgment request" });
-    }
-    const recorded = await recordStreamAcknowledgment(db, {
-      accountId: grant.accountId,
-      workspaceId,
-      sandboxGroupId: session.sandboxGroupId,
-      subjectId: grant.subjectId,
-      acknowledgeUnredacted: parsed.data.acknowledgeUnredacted,
-      acknowledgeShared: parsed.data.acknowledgeShared,
-    });
-    return c.json({ acknowledged: recorded.acknowledgedUnredacted, acknowledgedShared: recorded.acknowledgedShared });
-  });
+  app.post(
+    "/v1/workspaces/:workspaceId/sessions/:sessionId/stream-capabilities/acknowledge",
+    async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      const grant = await requireAccessGrant(c, deps, workspaceId, "stream:acknowledge");
+      assertOwnershipEnabled();
+      const sessionId = c.req.param("sessionId");
+      const session = await getSession(db, workspaceId, sessionId);
+      if (!session) {
+        throw new HTTPException(404, { message: "session not found" });
+      }
+      const parsed = AcknowledgeStreamRequest.safeParse(await c.req.json().catch(() => ({})));
+      if (!parsed.success) {
+        throw new HTTPException(400, { message: "invalid stream acknowledgment request" });
+      }
+      const recorded = await recordStreamAcknowledgment(db, {
+        accountId: grant.accountId,
+        workspaceId,
+        sandboxGroupId: session.sandboxGroupId,
+        subjectId: grant.subjectId,
+        acknowledgeUnredacted: parsed.data.acknowledgeUnredacted,
+        acknowledgeShared: parsed.data.acknowledgeShared,
+      });
+      return c.json({
+        acknowledged: recorded.acknowledgedUnredacted,
+        acknowledgedShared: recorded.acknowledgedShared,
+      });
+    },
+  );
 
   // POST .../viewers — acquire a viewer holder on the desktop-stream (un-redacted
   // pixel) path. Gated on stream:view (strictly broader than sessions:read: the
@@ -684,7 +977,11 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     const wantDesktop = parsed.data.desktop ?? false;
     const { shared } = await resolveSharedExposure(workspaceId, session);
     if (wantDesktop) {
-      const ack = await getStreamAcknowledgment(db, { workspaceId, sandboxGroupId: session.sandboxGroupId, subjectId: grant.subjectId });
+      const ack = await getStreamAcknowledgment(db, {
+        workspaceId,
+        sandboxGroupId: session.sandboxGroupId,
+        subjectId: grant.subjectId,
+      });
       if (!ack?.acknowledgedUnredacted) {
         throw new HTTPException(409, { message: "stream_acknowledgment_required" });
       }
@@ -695,7 +992,9 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     // SELFHOSTED ACTIVE: when the session's active sandbox is selfhosted, skip
     // attachViewer (it warms the Modal group box — the wrong target). Synthesize a
     // result shaped like ViewerAttachResult and mint relay cells directly.
-    const activeSandbox = session.activeSandboxId ? await getSandbox(db, workspaceId, session.activeSandboxId) : null;
+    const activeSandbox = session.activeSandboxId
+      ? await getSandbox(db, workspaceId, session.activeSandboxId)
+      : null;
     const selfhostedActive = activeSandbox?.kind === "selfhosted";
 
     let stream: DesktopStreamMint | null = null;
@@ -713,35 +1012,44 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
         dataPlaneUrl: null,
       };
       if (
-        (settings.sandboxDesktopEnabled || settings.sandboxTerminalEnabled)
-        && !streamTokenDegraded(settings)
+        (settings.sandboxDesktopEnabled || settings.sandboxTerminalEnabled) &&
+        !streamTokenDegraded(settings)
       ) {
         if (wantDesktop && settings.sandboxDesktopEnabled) {
-          stream = await mintDesktopStream({ db, settings, bus }, {
-            accountId: grant.accountId,
-            workspaceId,
-            session,
-            viewerId,
-            // No Modal lease for selfhosted-active; the mint routes to the relay.
-          });
+          stream = await mintDesktopStream(
+            { db, settings, bus },
+            {
+              accountId: grant.accountId,
+              workspaceId,
+              session,
+              viewerId,
+              // No Modal lease for selfhosted-active; the mint routes to the relay.
+            },
+          );
         }
         if (settings.sandboxTerminalEnabled) {
-          terminal = await mintTerminalStream({ db, settings, bus }, {
-            accountId: grant.accountId,
-            workspaceId,
-            session,
-            viewerId,
-            // No Modal lease for selfhosted-active; the mint routes to the relay.
-          });
+          terminal = await mintTerminalStream(
+            { db, settings, bus },
+            {
+              accountId: grant.accountId,
+              workspaceId,
+              session,
+              viewerId,
+              // No Modal lease for selfhosted-active; the mint routes to the relay.
+            },
+          );
         }
       }
     } else {
-      result = await attachViewer({ db, settings }, {
-        accountId: grant.accountId,
-        workspaceId,
-        session,
-        ...(parsed.data.viewerId ? { viewerId: parsed.data.viewerId } : {}),
-      });
+      result = await attachViewer(
+        { db, settings },
+        {
+          accountId: grant.accountId,
+          workspaceId,
+          session,
+          ...(parsed.data.viewerId ? { viewerId: parsed.data.viewerId } : {}),
+        },
+      );
 
       // P4.2 — the viewer now holds a WARM box; mint the real pixel cell IN-PROCESS
       // (resume by id → ensureDisplayStack → exposeStreamPort) scoped to THIS
@@ -751,34 +1059,43 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
       // box is warm here (attachViewer spun it up or attached), so the handshake's
       // never-spin-up rule does not apply.
       if (
-        (settings.sandboxDesktopEnabled || settings.sandboxTerminalEnabled)
-        && !streamTokenDegraded(settings)
+        (settings.sandboxDesktopEnabled || settings.sandboxTerminalEnabled) &&
+        !streamTokenDegraded(settings)
       ) {
-        const lease = await readGroupLease({ db, settings }, { workspaceId, sandboxGroupId: session.sandboxGroupId });
+        const lease = await readGroupLease(
+          { db, settings },
+          { workspaceId, sandboxGroupId: session.sandboxGroupId },
+        );
         if (lease) {
           // The pixel cell is minted only when the caller asked for the desktop plane
           // (and consented above). A terminal-only attach skips it — the box is warm,
           // the terminal mint below still runs.
           if (wantDesktop && settings.sandboxDesktopEnabled) {
-            stream = await mintDesktopStream({ db, settings, bus }, {
-              accountId: grant.accountId,
-              workspaceId,
-              session,
-              viewerId: result.viewerId,
-              lease,
-            });
+            stream = await mintDesktopStream(
+              { db, settings, bus },
+              {
+                accountId: grant.accountId,
+                workspaceId,
+                session,
+                viewerId: result.viewerId,
+                lease,
+              },
+            );
           }
           // P5.t — the same warm-box viewer attach also mints the REAL PTY terminal
           // address (independent of the desktop toggle). A degraded mint leaves the
           // terminal fields null → the client falls back to the sse-events firehose.
           if (settings.sandboxTerminalEnabled) {
-            terminal = await mintTerminalStream({ db, settings, bus }, {
-              accountId: grant.accountId,
-              workspaceId,
-              session,
-              viewerId: result.viewerId,
-              lease,
-            });
+            terminal = await mintTerminalStream(
+              { db, settings, bus },
+              {
+                accountId: grant.accountId,
+                workspaceId,
+                session,
+                viewerId: result.viewerId,
+                lease,
+              },
+            );
           }
         }
       }
@@ -795,7 +1112,11 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
         // (vnc-ws/novnc). Hardcoding vnc-ws here handed a machine's relay URL to the
         // noVNC renderer (and vice-versa on the swap-away case) → "closed before it
         // opened". Key off the SAME selfhostedActive the mint routed on.
-        transport: stream ? (selfhostedActive ? ("relay-frames" as const) : ("vnc-ws" as const)) : null,
+        transport: stream
+          ? selfhostedActive
+            ? ("relay-frames" as const)
+            : ("vnc-ws" as const)
+          : null,
         client: stream ? (selfhostedActive ? ("frames" as const) : ("novnc" as const)) : null,
         // The REAL PTY terminal address (pty-ws), null when degraded.
         terminalUrl: terminal?.url ?? null,
@@ -809,28 +1130,34 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
 
   // POST .../viewers/:viewerId/heartbeat — refresh the holder TTL (epoch-fenced).
   // The desktop-stream lifecycle is gated on stream:view (the un-redacted plane).
-  app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/viewers/:viewerId/heartbeat", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "stream:view");
-    assertOwnershipEnabled();
-    const sessionId = c.req.param("sessionId");
-    const session = await getSession(db, workspaceId, sessionId);
-    if (!session) {
-      throw new HTTPException(404, { message: "session not found" });
-    }
-    const parsed = ViewerHeartbeatRequest.safeParse(await c.req.json().catch(() => ({})));
-    if (!parsed.success) {
-      throw new HTTPException(400, { message: "viewer heartbeat requires { leaseEpoch }" });
-    }
-    const alive = await heartbeatViewer({ db, settings }, {
-      accountId: grant.accountId,
-      workspaceId,
-      sandboxGroupId: session.sandboxGroupId,
-      viewerId: c.req.param("viewerId"),
-      expectedEpoch: parsed.data.leaseEpoch,
-    });
-    return c.json({ alive });
-  });
+  app.post(
+    "/v1/workspaces/:workspaceId/sessions/:sessionId/viewers/:viewerId/heartbeat",
+    async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      const grant = await requireAccessGrant(c, deps, workspaceId, "stream:view");
+      assertOwnershipEnabled();
+      const sessionId = c.req.param("sessionId");
+      const session = await getSession(db, workspaceId, sessionId);
+      if (!session) {
+        throw new HTTPException(404, { message: "session not found" });
+      }
+      const parsed = ViewerHeartbeatRequest.safeParse(await c.req.json().catch(() => ({})));
+      if (!parsed.success) {
+        throw new HTTPException(400, { message: "viewer heartbeat requires { leaseEpoch }" });
+      }
+      const alive = await heartbeatViewer(
+        { db, settings },
+        {
+          accountId: grant.accountId,
+          workspaceId,
+          sandboxGroupId: session.sandboxGroupId,
+          viewerId: c.req.param("viewerId"),
+          expectedEpoch: parsed.data.leaseEpoch,
+        },
+      );
+      return c.json({ alive });
+    },
+  );
 
   // DELETE .../viewers/:viewerId — release the holder (idempotent).
   app.delete("/v1/workspaces/:workspaceId/sessions/:sessionId/viewers/:viewerId", async (c) => {
@@ -842,12 +1169,15 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     if (!session) {
       throw new HTTPException(404, { message: "session not found" });
     }
-    await detachViewer({ db, settings }, {
-      accountId: grant.accountId,
-      workspaceId,
-      sandboxGroupId: session.sandboxGroupId,
-      viewerId: c.req.param("viewerId"),
-    });
+    await detachViewer(
+      { db, settings },
+      {
+        accountId: grant.accountId,
+        workspaceId,
+        sandboxGroupId: session.sandboxGroupId,
+        viewerId: c.req.param("viewerId"),
+      },
+    );
     return c.body(null, 204);
   });
 
@@ -857,25 +1187,28 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
   // group-refcount liveness). Gated on stream:view (no new permission). The
   // live-RFB force-disconnect of an already-open socket is a P4 follow-up; the
   // holder-drop (so the box can drain) is the v1 deliverable.
-  app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/viewers/:viewerId/revoke", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "stream:view");
-    assertOwnershipEnabled();
-    const sessionId = c.req.param("sessionId");
-    const session = await getSession(db, workspaceId, sessionId);
-    if (!session) {
-      throw new HTTPException(404, { message: "session not found" });
-    }
-    const result = await revokeViewer(db, {
-      accountId: grant.accountId,
-      workspaceId,
-      sandboxGroupId: session.sandboxGroupId,
-      viewerId: c.req.param("viewerId"),
-      idleGraceMs: settings.sandboxIdleGraceMs,
-    });
-    // null ⇒ the lease was already cold-and-reaped (revoke is an idempotent no-op).
-    return c.json({ liveness: result?.liveness ?? null, refcount: result?.refcount ?? null });
-  });
+  app.post(
+    "/v1/workspaces/:workspaceId/sessions/:sessionId/viewers/:viewerId/revoke",
+    async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      const grant = await requireAccessGrant(c, deps, workspaceId, "stream:view");
+      assertOwnershipEnabled();
+      const sessionId = c.req.param("sessionId");
+      const session = await getSession(db, workspaceId, sessionId);
+      if (!session) {
+        throw new HTTPException(404, { message: "session not found" });
+      }
+      const result = await revokeViewer(db, {
+        accountId: grant.accountId,
+        workspaceId,
+        sandboxGroupId: session.sandboxGroupId,
+        viewerId: c.req.param("viewerId"),
+        idleGraceMs: settings.sandboxIdleGraceMs,
+      });
+      // null ⇒ the lease was already cold-and-reaped (revoke is an idempotent no-op).
+      return c.json({ liveness: result?.liveness ?? null, refcount: result?.refcount ?? null });
+    },
+  );
 
   // ══════════════════════ Channel-A structured services (P4.4) ══════════════
   //
@@ -917,7 +1250,10 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     return { accountId: grant.accountId, workspaceId, session, subjectId: grant.subjectId };
   }
 
-  async function parseChannelABody<T>(c: Context, schema: { safeParse: (v: unknown) => { success: true; data: T } | { success: false } }): Promise<T> {
+  async function parseChannelABody<T>(
+    c: Context,
+    schema: { safeParse: (v: unknown) => { success: true; data: T } | { success: false } },
+  ): Promise<T> {
     const raw = await c.req.json().catch(() => undefined);
     const result = schema.safeParse(raw ?? {});
     if (!result.success) {
@@ -930,42 +1266,54 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/fs/list", async (c) => {
     const ctx = await channelAPreamble(c, "files:read");
     const req = await parseChannelABody(c, FsListRequest);
-    const out = await withChannelA({ db, settings, bus }, ctx, ({ service }) => service.fsList(req));
+    const out = await withChannelA({ db, settings, bus }, ctx, ({ service }) =>
+      service.fsList(req),
+    );
     return c.json(out);
   });
 
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/fs/read", async (c) => {
     const ctx = await channelAPreamble(c, "files:read");
     const req = await parseChannelABody(c, FsReadRequest);
-    const out = await withChannelA({ db, settings, bus }, ctx, ({ service }) => service.fsRead(req));
+    const out = await withChannelA({ db, settings, bus }, ctx, ({ service }) =>
+      service.fsRead(req),
+    );
     return c.json(out);
   });
 
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/fs/write", async (c) => {
     const ctx = await channelAPreamble(c, "files:write");
     const req = await parseChannelABody(c, FsWriteRequest);
-    const out = await withChannelA({ db, settings, bus }, ctx, ({ service }) => service.fsWrite(req));
+    const out = await withChannelA({ db, settings, bus }, ctx, ({ service }) =>
+      service.fsWrite(req),
+    );
     return c.json(out);
   });
 
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/fs/delete", async (c) => {
     const ctx = await channelAPreamble(c, "files:write");
     const req = await parseChannelABody(c, FsDeleteRequest);
-    const out = await withChannelA({ db, settings, bus }, ctx, ({ service }) => service.fsDelete(req));
+    const out = await withChannelA({ db, settings, bus }, ctx, ({ service }) =>
+      service.fsDelete(req),
+    );
     return c.json(out);
   });
 
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/fs/move", async (c) => {
     const ctx = await channelAPreamble(c, "files:write");
     const req = await parseChannelABody(c, FsMoveRequest);
-    const out = await withChannelA({ db, settings, bus }, ctx, ({ service }) => service.fsMove(req));
+    const out = await withChannelA({ db, settings, bus }, ctx, ({ service }) =>
+      service.fsMove(req),
+    );
     return c.json(out);
   });
 
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/fs/mkdir", async (c) => {
     const ctx = await channelAPreamble(c, "files:write");
     const req = await parseChannelABody(c, FsMkdirRequest);
-    const out = await withChannelA({ db, settings, bus }, ctx, ({ service }) => service.fsMkdir(req));
+    const out = await withChannelA({ db, settings, bus }, ctx, ({ service }) =>
+      service.fsMkdir(req),
+    );
     return c.json(out);
   });
 
@@ -973,36 +1321,98 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/git/status", async (c) => {
     const ctx = await channelAPreamble(c, "files:read");
     const req = await parseChannelABody(c, GitStatusRequest);
-    const out = await withChannelA({ db, settings, bus }, ctx, ({ service }) => service.gitStatus(req));
+    const out = await withChannelA({ db, settings, bus }, ctx, ({ service }) =>
+      service.gitStatus(req),
+    );
     return c.json(out);
   });
 
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/git/diff", async (c) => {
     const ctx = await channelAPreamble(c, "files:read");
     const req = await parseChannelABody(c, GitDiffRequest);
-    const out = await withChannelA({ db, settings, bus }, ctx, ({ service }) => service.gitDiff(req));
+    const out = await withChannelA({ db, settings, bus }, ctx, ({ service }) =>
+      service.gitDiff(req),
+    );
     return c.json(out);
   });
 
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/git/log", async (c) => {
     const ctx = await channelAPreamble(c, "files:read");
     const req = await parseChannelABody(c, GitLogRequest);
-    const out = await withChannelA({ db, settings, bus }, ctx, ({ service }) => service.gitLog(req));
+    const out = await withChannelA({ db, settings, bus }, ctx, ({ service }) =>
+      service.gitLog(req),
+    );
     return c.json(out);
   });
 
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/git/show", async (c) => {
     const ctx = await channelAPreamble(c, "files:read");
     const req = await parseChannelABody(c, GitShowRequest);
-    const out = await withChannelA({ db, settings, bus }, ctx, ({ service }) => service.gitShow(req));
+    const out = await withChannelA({ db, settings, bus }, ctx, ({ service }) =>
+      service.gitShow(req),
+    );
     return c.json(out);
   });
 
+  // ── Workspace capture (read-only; served from DB + object storage, NO box) ──
+  // Grant-first (files:read) then a pure DB/storage read — deliberately NOT the
+  // channelAPreamble path: a capture is the durable turn-end snapshot, served
+  // without warming a machine (the <200ms cold paint). No ownership-flag gate:
+  // absent captures return {available:false} (200) so the client falls back to
+  // the live/wake path — the feature degrades to today's behavior, never worse.
+  app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/workspace/capture", async (c) => {
+    const workspaceId = c.req.param("workspaceId") ?? "";
+    await requireAccessGrant(c, deps, workspaceId, "files:read");
+    const sessionId = c.req.param("sessionId") ?? "";
+    const session = await getSession(db, workspaceId, sessionId);
+    if (!session) {
+      throw new HTTPException(404, { message: "session not found" });
+    }
+    if (!objectStorage) {
+      // No storage configured → no captures can exist. Cold-fallback, not an error.
+      return c.json({ available: false });
+    }
+    const row = await latestWorkspaceCapture(db, workspaceId, sessionId);
+    return c.json(await serveWorkspaceCapture(row, objectStorage));
+  });
+
+  app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/workspace/capture/file", async (c) => {
+    const workspaceId = c.req.param("workspaceId") ?? "";
+    await requireAccessGrant(c, deps, workspaceId, "files:read");
+    const sessionId = c.req.param("sessionId") ?? "";
+    const path = c.req.query("path");
+    if (!path) {
+      throw new HTTPException(400, { message: "path query parameter is required" });
+    }
+    const session = await getSession(db, workspaceId, sessionId);
+    if (!session) {
+      throw new HTTPException(404, { message: "session not found" });
+    }
+    if (!objectStorage) {
+      throw new HTTPException(404, { message: "capture not found" });
+    }
+    // Explicit ?revision pins a specific capture; omitted → latest.
+    const revisionParam = c.req.query("revision");
+    let row;
+    if (revisionParam !== undefined && revisionParam !== "") {
+      const revision = Number(revisionParam);
+      if (!Number.isInteger(revision) || revision < 0) {
+        throw new HTTPException(400, { message: "revision must be a non-negative integer" });
+      }
+      row = await workspaceCaptureAtRevision(db, workspaceId, sessionId, revision);
+    } else {
+      row = await latestWorkspaceCapture(db, workspaceId, sessionId);
+    }
+    return c.json(await serveWorkspaceCaptureFile(row, path, objectStorage));
+  });
+
   // ── Terminal: synchronous exec ────────────────────────────────────────────
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/terminal/exec", async (c) => {
     const ctx = await channelAPreamble(c, "terminal:attach");
     const req = await parseChannelABody(c, TerminalExecRequest);
-    const out = await withChannelA({ db, settings, bus }, ctx, ({ service }) => service.terminalExec(req));
+    const out = await withChannelA({ db, settings, bus }, ctx, ({ service }) =>
+      service.terminalExec(req),
+    );
     return c.json(out);
   });
 
@@ -1028,10 +1438,21 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
         openedBy: ctx.subjectId,
       });
       // Emit terminal.pty.started + any initial banner output on A1.
-      const started: TerminalPtyStartedPayload = { ptyId, cols: req.cols, rows: req.rows, shell: opened.shell, cwd: req.cwd };
+      const started: TerminalPtyStartedPayload = {
+        ptyId,
+        cols: req.cols,
+        rows: req.rows,
+        shell: opened.shell,
+        cwd: req.cwd,
+      };
       const events: AppendEventInput[] = [{ type: "terminal.pty.started", payload: started }];
       if (opened.initialOutput) {
-        const delta: TerminalPtyOutputDeltaPayload = { ptyId, stream: "stdout", chunk: opened.initialOutput, seq: 0 };
+        const delta: TerminalPtyOutputDeltaPayload = {
+          ptyId,
+          stream: "stdout",
+          chunk: opened.initialOutput,
+          seq: 0,
+        };
         events.push({ type: "terminal.pty.output.delta", payload: delta });
       }
       await appendAndPublishEvents(db, bus, ctx.workspaceId, ctx.session.id, events);
@@ -1053,10 +1474,22 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     let seq = 1;
     await withChannelA({ db, settings, bus }, ctx, async ({ service }) => {
       const output = await service.ptyWrite(req, pty.execSessionId!, req.data);
-      await updatePtySessionActivity(db, { accountId: ctx.accountId, workspaceId: ctx.workspaceId, ptyId: req.ptyId, execSessionId: pty.execSessionId });
+      await updatePtySessionActivity(db, {
+        accountId: ctx.accountId,
+        workspaceId: ctx.workspaceId,
+        ptyId: req.ptyId,
+        execSessionId: pty.execSessionId,
+      });
       if (output) {
-        const delta: TerminalPtyOutputDeltaPayload = { ptyId: req.ptyId, stream: "stdout", chunk: output, seq: seq++ };
-        await appendAndPublishEvents(db, bus, ctx.workspaceId, ctx.session.id, [{ type: "terminal.pty.output.delta", payload: delta }]);
+        const delta: TerminalPtyOutputDeltaPayload = {
+          ptyId: req.ptyId,
+          stream: "stdout",
+          chunk: output,
+          seq: seq++,
+        };
+        await appendAndPublishEvents(db, bus, ctx.workspaceId, ctx.session.id, [
+          { type: "terminal.pty.output.delta", payload: delta },
+        ]);
       }
     });
     return c.body(null, 204);
@@ -1070,9 +1503,17 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
       throw new HTTPException(404, { message: "pty not found or closed" });
     }
     if (pty.execSessionId !== null) {
-      await withChannelA({ db, settings, bus }, ctx, ({ service }) => service.ptyResize(req, pty.execSessionId!));
+      await withChannelA({ db, settings, bus }, ctx, ({ service }) =>
+        service.ptyResize(req, pty.execSessionId!),
+      );
     }
-    await updatePtySessionActivity(db, { accountId: ctx.accountId, workspaceId: ctx.workspaceId, ptyId: req.ptyId, cols: req.cols, rows: req.rows });
+    await updatePtySessionActivity(db, {
+      accountId: ctx.accountId,
+      workspaceId: ctx.workspaceId,
+      ptyId: req.ptyId,
+      cols: req.cols,
+      rows: req.rows,
+    });
     return c.body(null, 204);
   });
 
@@ -1082,10 +1523,18 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     const pty = await getOpenPtySession(db, ctx.workspaceId, req.ptyId);
     // Idempotent: closing an already-closed/absent PTY is a 204 no-op.
     if (pty) {
-      await withChannelA({ db, settings, bus }, ctx, ({ service }) => service.ptyClose(req, pty.execSessionId));
-      await closePtySession(db, { accountId: ctx.accountId, workspaceId: ctx.workspaceId, ptyId: req.ptyId });
+      await withChannelA({ db, settings, bus }, ctx, ({ service }) =>
+        service.ptyClose(req, pty.execSessionId),
+      );
+      await closePtySession(db, {
+        accountId: ctx.accountId,
+        workspaceId: ctx.workspaceId,
+        ptyId: req.ptyId,
+      });
       const exited: TerminalPtyExitedPayload = { ptyId: req.ptyId, exitCode: 0, reason: "exit" };
-      await appendAndPublishEvents(db, bus, ctx.workspaceId, ctx.session.id, [{ type: "terminal.pty.exited", payload: exited }]);
+      await appendAndPublishEvents(db, bus, ctx.workspaceId, ctx.session.id, [
+        { type: "terminal.pty.exited", payload: exited },
+      ]);
     }
     return c.body(null, 204);
   });
@@ -1099,6 +1548,50 @@ function eventListLimit(raw: string | undefined, max = 2000): number {
   return Math.min(max, Math.max(1, Math.floor(limit)));
 }
 
+function sessionListQuery(
+  query: Record<string, string>,
+  allowCursor = true,
+): {
+  limit: string | undefined;
+  parentSessionId: string | null | undefined;
+  cursor: ReturnType<typeof decodeSessionListCursor> | undefined;
+  search: string | undefined;
+} {
+  const parentSessionId = query.parentSessionId;
+  // "null" = roots only; a uuid = children of that session; anything else is
+  // a client error (an unvalidated value would surface as a Postgres uuid cast
+  // failure -> 500 rather than an honest 400).
+  if (
+    parentSessionId !== undefined &&
+    parentSessionId !== "null" &&
+    !z.string().uuid().safeParse(parentSessionId).success
+  ) {
+    throw new HTTPException(400, {
+      message: 'parentSessionId must be a session id or the literal "null"',
+    });
+  }
+  const rawCursor = allowCursor ? query.cursor : undefined;
+  const cursor = rawCursor ? decodeSessionListCursor(rawCursor) : undefined;
+  if (rawCursor && !cursor) {
+    throw new HTTPException(400, { message: "cursor is invalid" });
+  }
+  const search = query.search?.trim();
+  if (search && search.length > 200) {
+    throw new HTTPException(400, { message: "search must be at most 200 characters" });
+  }
+  return {
+    limit: query.limit,
+    parentSessionId:
+      parentSessionId === undefined
+        ? undefined
+        : parentSessionId === "null"
+          ? null
+          : parentSessionId,
+    cursor,
+    search: search || undefined,
+  };
+}
+
 function compactEvents(raw: string | undefined): boolean {
   return raw === "1" || raw === "true";
 }
@@ -1123,7 +1616,9 @@ function optionalEventSequence(raw: string | undefined): number | undefined {
 }
 
 function hasOwnProperty(value: unknown, key: string): boolean {
-  return Boolean(value && typeof value === "object" && Object.prototype.hasOwnProperty.call(value, key));
+  return Boolean(
+    value && typeof value === "object" && Object.prototype.hasOwnProperty.call(value, key),
+  );
 }
 
 function userMessagePayloadHasOwnProperty(value: unknown, key: string): boolean {
@@ -1133,3 +1628,18 @@ function userMessagePayloadHasOwnProperty(value: unknown, key: string): boolean
   const payload = (value as { payload?: unknown }).payload;
   return hasOwnProperty(payload, key);
 }
+
+function throwQueueConflict(error: unknown): never {
+  if (error instanceof SessionQueueConflictError) {
+    throw new HTTPException(409, {
+      message: JSON.stringify({
+        message: error.message,
+        currentQueueVersion: error.currentQueueVersion,
+        ...(error.currentItemVersion !== undefined
+          ? { currentItemVersion: error.currentItemVersion }
+          : {}),
+      }),
+    });
+  }
+  throw error;
+}