@opengeni/api-router 0.23.1 → 0.30.0

package/src/routes/sessions.ts

@@ -1,5 +1,6 @@
 import {
   AcknowledgeStreamRequest,
+  ApplySessionGoalRevisionRequest,
   ActivateCodexRealtimeConnectionRequest,
   AttachViewerRequest,
   BeginSessionRealtimeRequest,
@@ -47,6 +48,7 @@ import {
   SteerSessionQueueItemRequest,
   SteerSessionMessageRequest,
   TerminalExecRequest,
+  UpdateSessionChannelRequest,
   UpdateSessionPinRequest,
   UpdateSessionGoalRequest,
   UpdateSessionMcpApprovalPolicyRequest,
@@ -55,9 +57,13 @@ import {
   ViewerHeartbeatRequest,
   WORKSPACE_CONTROL_ACTOR_MAX_BYTES,
   workspaceControlUtf8Bytes,
+  type AccessGrant,
+  type AttachViewerResponse,
   type SandboxBackend,
   type LineageNode,
   type Session,
+  type SessionGoalRevision,
+  type AgentTopologyPageResponse,
   type ErrorCode,
   type SessionAuthorizationOperation,
   type SessionQueueSnapshot,
@@ -72,6 +78,7 @@ import {
   clearSessionGoal,
   clearSessionContext,
   getOpenPtySession,
+  getEnrollment,
   getRetainedProcess,
   getSandbox,
   getSession,
@@ -80,12 +87,16 @@ import {
   getSessionGoal,
   getSessionHumanInputRequest,
   getSessionGoalWithContinuation,
+  getSessionGoalRevision,
   getSessionQueueSnapshot,
   getStreamAcknowledgment,
   insertPtySession,
   listSessionEventPage,
   listSessionHumanInputRequests,
+  listSessionGoalRevisions,
   listSessionIdsInGroup,
+  listSessionDiscoverySummaries,
+  listSessionDiscoveryAncestorPaths,
   listSessionsForSubject,
   getLatestStartedSessionTurn,
   listSessionTurns,
@@ -93,8 +104,10 @@ import {
   projectSessionForRelatedAccess,
   recordStreamAcknowledgment,
   requestSessionCompaction,
-  setSessionCodexPin,
-  withCodexCapacityMutation,
+  setSessionCodexPinInTransaction,
+  withSessionCodexCapacityMutation,
+  setSessionChannel,
+  ChannelNotFoundError,
   setSessionPin,
   SessionPinVersionConflictError,
   SessionPinAccessError,
@@ -105,6 +118,7 @@ import {
   decodeSessionListCursor,
   revokeViewer,
   setSessionGoalStatusWithEvent,
+  upsertSessionGoalWithEvent,
   updatePtySessionActivity,
   QueueCommandConflictError,
   beginSessionRealtimeInTransaction,
@@ -124,6 +138,7 @@ import {
   sessionLatestWorkspaceCapture,
   renewSessionRealtimeInTransaction,
   syncSessionRealtimeLedgerInTransaction,
+  withWorkspaceSessionActivityRls,
   withWorkspaceRls,
   workspaceCaptureAtRevision,
   type AppendEventInput,
@@ -131,6 +146,8 @@ import {
   type SandboxPtyProcessIdentity,
   type SandboxRetainedProcess,
   type Database,
+  type SessionDiscoveryCursor,
+  type SessionDiscoveryAncestor,
 } from "@opengeni/db";
 import {
   appendAndPublishEvents,
@@ -142,17 +159,32 @@ import {
   createGatewayRealtimeConnectionSecret,
   GatewayRealtimeBrokerError,
 } from "../gateway-realtime";
+import { createXaiRealtimeConnectionSecret, XaiRealtimeBrokerError } from "../xai-realtime";
 import { z, ZodError } from "zod";
-import { withChannelA, type ChannelAContext, type ChannelAHandle } from "../sandbox/channel-a";
-import { negotiateCapabilities } from "@opengeni/runtime/sandbox";
+import {
+  runConcurrentChannelAReads,
+  withChannelA,
+  withChannelARead,
+  type ChannelAContext,
+  type ChannelAHandle,
+  type ChannelAOperation,
+} from "../sandbox/channel-a";
+import {
+  NatsControlRpc,
+  negotiateCapabilities,
+  negotiateSelfhostedCapabilities,
+  SelfhostedSession,
+} from "@opengeni/runtime/sandbox";
 import type { Context, Hono, MiddlewareHandler } from "hono";
 import { HTTPException } from "hono/http-exception";
 import type { ContentfulStatusCode } from "hono/utils/http-status";
 import {
+  hasPermission,
   requireAccessGrant,
   requirePermission,
   requireSessionAuthorization,
   requireSessionAuthorizationListScope,
+  withResolvedSessionAuthorization,
   SESSION_AUTHORIZATION_DEFAULT_REAUTHORIZE_MS,
   SessionAuthorizationDeniedError,
   SessionAuthorizationUnavailableError,
@@ -195,6 +227,7 @@ import {
   sessionWithEffectiveToolPolicy,
   workspaceSessionToolPolicyDefaultServerIds,
   workspaceSessionToolPolicyServerIds,
+  relayConfigFromSettings,
 } from "@opengeni/core";
 import { assertSessionExists, boundedLimit } from "../http/common";
 import { sseSessionStream } from "../http/sse";
@@ -206,9 +239,27 @@ import {
 
 type SessionRouteDeps = ApiRouteDeps & Pick<ViewerServices, "establishSandboxSession">;
 
+const VIEWER_LIFECYCLE_PERMISSIONS = ["stream:view", "terminal:attach", "files:write"] as const;
+
+function requireViewerLifecyclePermission(grant: AccessGrant): void {
+  if (
+    VIEWER_LIFECYCLE_PERMISSIONS.some((permission) => hasPermission(grant.permissions, permission))
+  ) {
+    return;
+  }
+  throw new HTTPException(403, {
+    message: `missing permission: ${VIEWER_LIFECYCLE_PERMISSIONS.join(" or ")}`,
+  });
+}
+
 export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
   const { settings, db, bus, workflowClient, objectStorage } = deps;
-  const channelAServices = { db, settings, bus, observability: deps.observability };
+  const channelAServices = {
+    db,
+    settings,
+    bus,
+    observability: deps.observability,
+  };
   const workspaceCaptureManifestCache = new WorkspaceCaptureManifestCache();
   const ptyIdentity = (pty: SandboxOpenPtySessionRow): SandboxPtyProcessIdentity => ({
     leaseId: pty.leaseId,
@@ -355,10 +406,6 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     if (!operation) {
       throw sessionAuthorizationHttpError(new SessionAuthorizationUnavailableError());
     }
-    if (operation === "session.codex_account.write" && !deps.sessionAuthorization) {
-      await next();
-      return;
-    }
     const grant = await requireAccessGrant(c, deps, workspaceId);
     try {
       const authorization = await requireSessionAuthorization(deps, grant, {
@@ -367,6 +414,10 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         surface: "http",
       });
       if (authorization) requestSessionAuthorization.set(c.req.raw, authorization);
+      if (authorization) {
+        await withResolvedSessionAuthorization(authorization, next);
+        return;
+      }
     } catch (error) {
       throw sessionAuthorizationHttpError(error);
     }
@@ -407,7 +458,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     // Creation has committed by this point. Keep response projection outside
     // the create-rejection boundary so a post-commit policy read cannot be
     // misreported as though the session itself was rejected.
-    return c.json(await withEffectivePolicy(deps, workspaceId, session), 202);
+    return c.json(await withEffectivePolicy(deps, workspaceId, grant.subjectId, session), 202);
   });
 
   app.get("/v1/workspaces/:workspaceId/new-session-draft", async (c) => {
@@ -511,7 +562,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     // body for older clients while still making its older-pin omission visible
     // to raw HTTP consumers without changing that response shape.
     c.header("x-opengeni-pinned-truncated", page.pinnedTruncated === true ? "true" : "false");
-    const policy = await loadEffectivePolicyContext(deps, workspaceId);
+    const policy = await loadEffectivePolicyContext(deps, workspaceId, grant.subjectId);
     const decorate = (session: Session): Session =>
       sessionWithEffectiveToolPolicy(
         session,
@@ -533,6 +584,83 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     return c.json([...page.pinned, ...page.sessions].map(decorate));
   });
 
+  app.get("/v1/workspaces/:workspaceId/agent-topology", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:read");
+    let authorizationScope;
+    try {
+      authorizationScope = await requireSessionAuthorizationListScope(deps, grant, "http");
+    } catch (error) {
+      throw sessionAuthorizationHttpError(error);
+    }
+    const query = agentTopologyQuery(c.req.query());
+    const page = await listSessionDiscoverySummaries(db, workspaceId, {
+      limit: query.limit,
+      orderBy: "updatedAt",
+      subjectId: grant.subjectId,
+      ...(query.cursor ? { cursor: query.cursor } : {}),
+      ...(query.search ? { search: query.search } : { parentSessionId: query.parentSessionId }),
+      ...(authorizationScope ? { authorizationScope } : {}),
+    });
+    const ancestorPaths = query.search
+      ? await listSessionDiscoveryAncestorPaths(
+          db,
+          workspaceId,
+          page.sessions.map((session) => session.id),
+          authorizationScope ?? undefined,
+        )
+      : new Map<string, SessionDiscoveryAncestor[]>();
+    const sessions: AgentTopologyPageResponse["sessions"] = page.sessions.map((session) => {
+      const blocker = session.effectiveControl.primaryBlocker;
+      return {
+        id: session.id,
+        title: session.title,
+        titleTruncated:
+          session.titleOriginalChars !== null &&
+          session.titleOriginalChars > Array.from(session.title ?? "").length,
+        parentSessionId: session.parentSessionId,
+        rootSessionId: session.rootSessionId,
+        nestedAgentDepth: session.nestedAgentDepth,
+        ancestorPath: (ancestorPaths.get(session.id) ?? []).map((ancestor) => ({
+          id: ancestor.id,
+          title: ancestor.title,
+          titleTruncated:
+            ancestor.titleOriginalChars !== null &&
+            ancestor.titleOriginalChars > Array.from(ancestor.title ?? "").length,
+        })),
+        status: session.status,
+        pause: {
+          state: session.effectiveControl.state,
+          additionalBlockerCount: session.effectiveControl.additionalBlockerCount,
+          source: blocker
+            ? {
+                kind: blocker.kind,
+                ...(blocker.sessionId ? { sessionId: blocker.sessionId } : {}),
+                displayName: blocker.displayName,
+                displayNameTruncated:
+                  blocker.displayNameOriginalChars > Array.from(blocker.displayName).length,
+              }
+            : null,
+        },
+        children: session.treeStats,
+        createdAt: session.createdAt,
+        updatedAt: session.updatedAt,
+      };
+    });
+    return c.json({
+      sessions,
+      total: page.total,
+      hasMore: page.hasMore,
+      nextCursor: page.nextCursor
+        ? encodeAgentTopologyCursor({
+            cursor: page.nextCursor,
+            parentSessionId: query.parentSessionId,
+            search: query.search ?? null,
+          })
+        : null,
+    } satisfies AgentTopologyPageResponse);
+  });
+
   app.get("/v1/workspaces/:workspaceId/sessions/:sessionId", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:read");
@@ -550,7 +678,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     if (!session) {
       throw new HTTPException(404, { message: "session not found" });
     }
-    return c.json(await withEffectivePolicy(deps, workspaceId, session));
+    return c.json(await withEffectivePolicy(deps, workspaceId, grant.subjectId, session));
   });
 
   const publishRealtimeMutation = async (
@@ -586,19 +714,19 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     }
     const parsed = BeginSessionRealtimeRequest.safeParse(await c.req.json().catch(() => null));
     if (!parsed.success) {
-      throw new HTTPException(400, { message: "invalid session realtime request" });
+      throw new HTTPException(400, {
+        message: "invalid session realtime request",
+      });
     }
     try {
-      const result = await withWorkspaceRls(db, workspaceId, async (scopedDb) =>
-        scopedDb.transaction(async (tx) =>
-          beginSessionRealtimeInTransaction(tx as unknown as Database, {
-            accountId: grant.accountId,
-            workspaceId,
-            sessionId,
-            ownerSubjectId: grant.subjectId,
-            ...parsed.data,
-          }),
-        ),
+      const result = await withWorkspaceSessionActivityRls(db, workspaceId, async (scopedDb) =>
+        beginSessionRealtimeInTransaction(scopedDb, {
+          accountId: grant.accountId,
+          workspaceId,
+          sessionId,
+          ownerSubjectId: grant.subjectId,
+          ...parsed.data,
+        }),
       );
       await publishRealtimeMutation(grant.accountId, workspaceId, sessionId, result);
       c.header("cache-control", "private, no-store");
@@ -619,23 +747,25 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         !z.string().uuid().safeParse(sessionId).success ||
         !z.string().uuid().safeParse(realtimeId).success
       ) {
-        throw new HTTPException(400, { message: "invalid realtime lifecycle id" });
+        throw new HTTPException(400, {
+          message: "invalid realtime lifecycle id",
+        });
       }
       const parsed = RenewSessionRealtimeRequest.safeParse(await c.req.json().catch(() => null));
       if (!parsed.success) {
-        throw new HTTPException(400, { message: "invalid realtime heartbeat request" });
+        throw new HTTPException(400, {
+          message: "invalid realtime heartbeat request",
+        });
       }
       try {
-        const result = await withWorkspaceRls(db, workspaceId, async (scopedDb) =>
-          scopedDb.transaction(async (tx) =>
-            renewSessionRealtimeInTransaction(tx as unknown as Database, {
-              workspaceId,
-              sessionId,
-              realtimeId,
-              ownerSubjectId: grant.subjectId,
-              ...parsed.data,
-            }),
-          ),
+        const result = await withWorkspaceSessionActivityRls(db, workspaceId, async (scopedDb) =>
+          renewSessionRealtimeInTransaction(scopedDb, {
+            workspaceId,
+            sessionId,
+            realtimeId,
+            ownerSubjectId: grant.subjectId,
+            ...parsed.data,
+          }),
         );
         await publishRealtimeMutation(grant.accountId, workspaceId, sessionId, result);
         c.header("cache-control", "private, no-store");
@@ -655,23 +785,25 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
       !z.string().uuid().safeParse(sessionId).success ||
       !z.string().uuid().safeParse(realtimeId).success
     ) {
-      throw new HTTPException(400, { message: "invalid realtime lifecycle id" });
+      throw new HTTPException(400, {
+        message: "invalid realtime lifecycle id",
+      });
     }
     const parsed = EndSessionRealtimeRequest.safeParse(await c.req.json().catch(() => null));
     if (!parsed.success) {
-      throw new HTTPException(400, { message: "invalid realtime end request" });
+      throw new HTTPException(400, {
+        message: "invalid realtime end request",
+      });
     }
     try {
-      const result = await withWorkspaceRls(db, workspaceId, async (scopedDb) =>
-        scopedDb.transaction(async (tx) =>
-          endSessionRealtimeInTransaction(tx as unknown as Database, {
-            workspaceId,
-            sessionId,
-            realtimeId,
-            ownerSubjectId: grant.subjectId,
-            ...parsed.data,
-          }),
-        ),
+      const result = await withWorkspaceSessionActivityRls(db, workspaceId, async (scopedDb) =>
+        endSessionRealtimeInTransaction(scopedDb, {
+          workspaceId,
+          sessionId,
+          realtimeId,
+          ownerSubjectId: grant.subjectId,
+          ...parsed.data,
+        }),
       );
       await publishRealtimeMutation(grant.accountId, workspaceId, sessionId, result);
       c.header("cache-control", "private, no-store");
@@ -774,7 +906,10 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         deps.codexFetch,
       );
       try {
-        const answer = await broker({ request: providerRequest, signal: c.req.raw.signal });
+        const answer = await broker({
+          request: providerRequest,
+          signal: c.req.raw.signal,
+        });
         const completed = await withWorkspaceRls(db, workspaceId, async (scopedDb) =>
           scopedDb.transaction(async (tx) =>
             completeSessionRealtimeConnectionInTransaction(tx as unknown as Database, {
@@ -867,7 +1002,9 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     }
     const parsed = GatewayRealtimeConnectRequest.safeParse(await c.req.json().catch(() => null));
     if (!parsed.success) {
-      throw new HTTPException(422, { message: "invalid Gateway realtime request" });
+      throw new HTTPException(422, {
+        message: "invalid Gateway realtime request",
+      });
     }
     c.header("cache-control", "private, no-store");
     const {
@@ -972,6 +1109,121 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     }
   });
 
+  app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/realtime/supergrok", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const sessionId = c.req.param("sessionId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:control");
+    if (!z.string().uuid().safeParse(sessionId).success) {
+      throw new HTTPException(404, { message: "session not found" });
+    }
+    const parsed = GatewayRealtimeConnectRequest.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) {
+      throw new HTTPException(422, { message: "invalid SuperGrok realtime request" });
+    }
+    c.header("cache-control", "private, no-store");
+    const {
+      realtimeId,
+      operationId,
+      browserInstanceId,
+      ownerKey,
+      expectedVersion,
+      expectedConnectionEpoch,
+      rotate,
+    } = parsed.data;
+    let claim: Awaited<ReturnType<typeof claimSessionRealtimeConnectionInTransaction>> | null =
+      null;
+    let connectionCompleted = false;
+    try {
+      claim = await withWorkspaceRls(db, workspaceId, async (scopedDb) =>
+        scopedDb.transaction(async (tx) =>
+          claimSessionRealtimeConnectionInTransaction(tx as unknown as Database, {
+            workspaceId,
+            sessionId,
+            realtimeId,
+            operationId,
+            ownerSubjectId: grant.subjectId,
+            browserInstanceId,
+            ownerKey,
+            expectedVersion,
+            expectedConnectionEpoch,
+            rotate,
+            promotionMode: "staged",
+          }),
+        ),
+      );
+      if (claim.replay) {
+        throw new SessionRealtimeConflictError(
+          "REALTIME_CONNECTION_STATE_CHANGED",
+          "SuperGrok realtime tokens are single-use; reconnect with a new operation",
+        );
+      }
+      const secret = await createXaiRealtimeConnectionSecret({
+        db,
+        settings,
+        accountId: grant.accountId,
+        workspaceId,
+        subjectId: grant.subjectId,
+        sessionId,
+        model: claim.mode.model,
+        fetchImpl: deps.xaiFetch ?? fetch,
+      });
+      const claimed = claim;
+      const completed = await withWorkspaceRls(db, workspaceId, async (scopedDb) =>
+        scopedDb.transaction(async (tx) =>
+          completeSessionRealtimeConnectionInTransaction(tx as unknown as Database, {
+            workspaceId,
+            sessionId,
+            realtimeId,
+            connectionId: claimed.connection.id,
+            operationId,
+            connectionEpoch: claimed.connection.connectionEpoch,
+            sdpAnswer: "supergrok-client-secret-minted",
+          }),
+        ),
+      );
+      connectionCompleted = true;
+      return c.json({
+        ...secret,
+        connectionId: completed.connection.id,
+        connectionEpoch: completed.connection.connectionEpoch,
+        startupFenceSequence: completed.connection.startupFenceSequence,
+        modeVersion: claimed.modeVersion,
+        replay: false as const,
+      });
+    } catch (error) {
+      if (claim !== null && !claim.replay && !connectionCompleted) {
+        const claimed = claim;
+        await withWorkspaceRls(db, workspaceId, async (scopedDb) =>
+          scopedDb.transaction(async (tx) =>
+            failSessionRealtimeConnectionInTransaction(tx as unknown as Database, {
+              workspaceId,
+              sessionId,
+              realtimeId,
+              connectionId: claimed.connection.id,
+              operationId,
+              connectionEpoch: claimed.connection.connectionEpoch,
+              failureCode: error instanceof XaiRealtimeBrokerError ? error.code : "supergrok_error",
+            }),
+          ),
+        ).catch(() => undefined);
+      }
+      if (error instanceof SessionRealtimeConflictError) throw sessionRealtimeHttpError(error);
+      if (!(error instanceof XaiRealtimeBrokerError)) throw error;
+      const status = error.code === "credential_unavailable" ? 409 : 502;
+      return c.json(
+        {
+          error: {
+            status,
+            code: `SUPERGROK_REALTIME_${error.code.toUpperCase()}`,
+            message: error.message,
+            retryable: error.code === "provider_error",
+          },
+        },
+        status,
+      );
+    }
+  });
+
   app.post(
     "/v1/workspaces/:workspaceId/sessions/:sessionId/realtime/:realtimeId/connections/:connectionId/activate",
     async (c) => {
@@ -985,13 +1237,17 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         !z.string().uuid().safeParse(realtimeId).success ||
         !z.string().uuid().safeParse(connectionId).success
       ) {
-        throw new HTTPException(400, { message: "invalid realtime connection id" });
+        throw new HTTPException(400, {
+          message: "invalid realtime connection id",
+        });
       }
       const parsed = ActivateCodexRealtimeConnectionRequest.safeParse(
         await c.req.json().catch(() => null),
       );
       if (!parsed.success) {
-        throw new HTTPException(422, { message: "invalid realtime connection activation" });
+        throw new HTTPException(422, {
+          message: "invalid realtime connection activation",
+        });
       }
       try {
         const result = await withWorkspaceRls(db, workspaceId, async (scopedDb) =>
@@ -1031,19 +1287,19 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         await c.req.json().catch(() => null),
       );
       if (!parsed.success) {
-        throw new HTTPException(422, { message: "invalid realtime ledger sync request" });
+        throw new HTTPException(422, {
+          message: "invalid realtime ledger sync request",
+        });
       }
       try {
-        const result = await withWorkspaceRls(db, workspaceId, async (scopedDb) =>
-          scopedDb.transaction(async (tx) =>
-            syncSessionRealtimeLedgerInTransaction(tx as unknown as Database, {
-              workspaceId,
-              sessionId,
-              realtimeId,
-              ownerSubjectId: grant.subjectId,
-              ...parsed.data,
-            }),
-          ),
+        const result = await withWorkspaceSessionActivityRls(db, workspaceId, async (scopedDb) =>
+          syncSessionRealtimeLedgerInTransaction(scopedDb, {
+            workspaceId,
+            sessionId,
+            realtimeId,
+            ownerSubjectId: grant.subjectId,
+            ...parsed.data,
+          }),
         );
         await publishRealtimeMutation(grant.accountId, workspaceId, sessionId, result);
         c.header("cache-control", "private, no-store");
@@ -1082,6 +1338,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         await withEffectivePolicy(
           deps,
           workspaceId,
+          grant.subjectId,
           projectSessionForRelatedAccess(session, relatedSessionAccessFor(c)),
         ),
       );
@@ -1106,7 +1363,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:read");
     const lineage = await readSessionLineage(deps, grant, c.req.param("sessionId"));
-    const policy = await loadEffectivePolicyContext(deps, workspaceId);
+    const policy = await loadEffectivePolicyContext(deps, workspaceId, grant.subjectId);
     return c.json({
       ...lineage,
       ancestors: lineage.ancestors.map((session) =>
@@ -1148,11 +1405,11 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
       }
     }
     const pinned = target === "auto" ? null : target;
-    const mutation = await withCodexCapacityMutation(
+    const mutation = await withSessionCodexCapacityMutation(
       db,
       { workspaceId, reason: "codex_manual_session_pin_changed" },
       async (tx) => {
-        const changed = await setSessionCodexPin(tx, workspaceId, sessionId, pinned);
+        const changed = await setSessionCodexPinInTransaction(tx, workspaceId, sessionId, pinned);
         return { result: changed, changed };
       },
     );
@@ -1185,6 +1442,43 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     return c.json({ pinned: target === "auto" ? "auto" : target });
   });
 
+  // Re-file the session into a workspace channel (rail organization only;
+  // null = back to the unfiled inbox). Shared, workspace-visible state, so it
+  // requires sessions:control like rename. Returns the refreshed session.
+  app.put("/v1/workspaces/:workspaceId/sessions/:sessionId/channel", 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 = UpdateSessionChannelRequest.parse(await c.req.json());
+    try {
+      const updated = await setSessionChannel(db, {
+        workspaceId,
+        sessionId,
+        channelId: payload.channelId,
+      });
+      if (!updated) {
+        throw new HTTPException(404, { message: "session not found" });
+      }
+    } catch (error) {
+      if (error instanceof ChannelNotFoundError) {
+        throw new HTTPException(422, { message: error.message });
+      }
+      throw error;
+    }
+    const session = await getSessionForSubject(
+      db,
+      workspaceId,
+      sessionId,
+      grant.subjectId,
+      relatedSessionAccessFor(c),
+    );
+    if (!session) {
+      throw new HTTPException(404, { message: "session not found" });
+    }
+    return c.json(await withEffectivePolicy(deps, workspaceId, grant.subjectId, session));
+  });
+
   // Manual rename. A user-set title is permanent: the db write is
   // unconditional (source='user'), so it always pins the session over later
   // agent writes. Returns the refreshed session, mirroring GET detail.
@@ -1208,7 +1502,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     if (!session) {
       throw new HTTPException(404, { message: "session not found" });
     }
-    return c.json(await withEffectivePolicy(deps, workspaceId, session));
+    return c.json(await withEffectivePolicy(deps, workspaceId, grant.subjectId, session));
   });
 
   app.patch(
@@ -1246,7 +1540,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     const payload = UpdateSessionToolPolicyRequest.parse(await c.req.json().catch(() => null));
     try {
       const session = await updateSessionToolPolicy(deps, grant, sessionId, payload);
-      return c.json(await withEffectivePolicy(deps, workspaceId, session));
+      return c.json(await withEffectivePolicy(deps, workspaceId, grant.subjectId, session));
     } catch (error) {
       if (error instanceof SessionToolPolicyVersionConflictError) {
         return c.json(
@@ -1274,6 +1568,77 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     return c.json(goal);
   });
 
+  app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/goal/revisions", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "sessions:read");
+    const sessionId = c.req.param("sessionId");
+    await assertSessionExists(db, workspaceId, sessionId);
+    return c.json(await listSessionGoalRevisions(db, workspaceId, sessionId));
+  });
+
+  app.post(
+    "/v1/workspaces/:workspaceId/sessions/:sessionId/goal/revisions/:revisionId/apply",
+    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 = ApplySessionGoalRevisionRequest.parse(await c.req.json());
+      const revision = await getSessionGoalRevision(
+        db,
+        workspaceId,
+        sessionId,
+        c.req.param("revisionId"),
+      );
+      if (!revision || revision.disposition !== "proposed") {
+        throw new HTTPException(404, {
+          message: "goal rewrite proposal not found",
+        });
+      }
+      if (!goalProposalMatchesExpectedRevision(revision, payload.expectedObjectiveRevision)) {
+        throw new HTTPException(409, {
+          message: `goal proposal was based on objective revision ${revision.baseObjectiveRevision}; requested fence ${payload.expectedObjectiveRevision} cannot apply it`,
+        });
+      }
+      try {
+        const { goal, workflowWakeRevision, events } = await upsertSessionGoalWithEvent(db, {
+          accountId: grant.accountId,
+          workspaceId,
+          sessionId,
+          text: revision.text,
+          successCriteria: revision.successCriteria,
+          mutationPolicy: revision.mutationPolicy,
+          expectedObjectiveRevision: payload.expectedObjectiveRevision,
+          expectedGoalId: revision.goalId,
+          changeKind: revision.changeKind,
+          changeRationale: payload.rationale ?? `Applied goal proposal ${revision.id}`,
+          sourceProposalId: revision.id,
+          createdBy: "api",
+          actor: "api",
+        });
+        await publishDurableSessionEvents(bus, workspaceId, sessionId, events);
+        if (workflowWakeRevision !== null) {
+          await workflowClient.wakeSessionWorkflow({
+            accountId: grant.accountId,
+            workspaceId,
+            sessionId,
+            workflowId: workflowIdForSession(sessionId),
+            wakeRevision: workflowWakeRevision,
+          });
+        }
+        return c.json((await getSessionGoalWithContinuation(db, workspaceId, sessionId)) ?? goal);
+      } catch (error) {
+        if (error instanceof SessionControlConflictError) {
+          throw new HTTPException(409, {
+            message: error.message,
+            cause: error,
+          });
+        }
+        throw error;
+      }
+    },
+  );
+
   app.patch("/v1/workspaces/:workspaceId/sessions/:sessionId/goal", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:control");
@@ -1284,6 +1649,48 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     if (!existing) {
       throw new HTTPException(404, { message: "session goal not found" });
     }
+    if (!("status" in payload)) {
+      try {
+        const { goal, workflowWakeRevision, events } = await upsertSessionGoalWithEvent(db, {
+          accountId: grant.accountId,
+          workspaceId,
+          sessionId,
+          text: payload.text,
+          successCriteria:
+            payload.successCriteria !== undefined
+              ? payload.successCriteria
+              : existing.successCriteria,
+          maxAutoContinuations: existing.maxAutoContinuations,
+          mutationPolicy: payload.mutationPolicy ?? existing.mutationPolicy,
+          expectedObjectiveRevision: payload.expectedObjectiveRevision,
+          changeKind: "replacement",
+          changeRationale: payload.rationale,
+          createdBy: "api",
+          actor: "api",
+        });
+        if (events.length > 0) {
+          await bus.publish(workspaceId, sessionId, events);
+        }
+        if (workflowWakeRevision !== null) {
+          await workflowClient.wakeSessionWorkflow({
+            accountId: grant.accountId,
+            workspaceId,
+            sessionId,
+            workflowId: workflowIdForSession(sessionId),
+            wakeRevision: workflowWakeRevision,
+          });
+        }
+        return c.json((await getSessionGoalWithContinuation(db, workspaceId, sessionId)) ?? goal);
+      } catch (error) {
+        if (error instanceof SessionControlConflictError) {
+          throw new HTTPException(409, {
+            message: error.message,
+            cause: error,
+          });
+        }
+        throw error;
+      }
+    }
     if (existing.status === "completed") {
       throw new HTTPException(409, {
         message: "session goal is completed; set a new goal instead",
@@ -1563,6 +1970,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     const projected = compact ? coalesceSessionEventDeltas(events) : events;
     const page = boundSessionEventHttpPage(projected, {
       direction,
+      eventProjection: mode === "forensic" && payloadMode === "full" ? "exact" : "bounded",
     });
     const hasMore = dbPage.hasMore || page.truncated;
     c.header("X-OpenGeni-Page-Bytes", String(page.bytes));
@@ -1845,10 +2253,10 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:control");
     const sessionId = c.req.param("sessionId");
     await assertSessionExists(db, workspaceId, sessionId);
-    const raw = await c.req.json();
-    const payload = SteerSessionMessageRequest.parse(raw);
+    const payload = parseSteerSessionAdmission(await c.req.json().catch(() => null));
     const result = await acceptSessionUserMessage(deps, grant, workspaceId, sessionId, {
       text: payload.text,
+      annotations: payload.annotations,
       turnInstructions: payload.turnInstructions ?? null,
       resources: payload.resources,
       model: payload.model ?? null,
@@ -1870,8 +2278,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:control");
     const sessionId = c.req.param("sessionId");
-    const rawEvent = await c.req.json();
-    const event = ClientSessionEvent.parse(rawEvent);
+    const event = parseSessionEventAdmission(await c.req.json().catch(() => null));
     const refinedOperation =
       event.type === "user.approvalDecision"
         ? "session.approval.write"
@@ -1892,6 +2299,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     if (event.type === "user.message") {
       const { accepted } = await acceptSessionUserMessage(deps, grant, workspaceId, sessionId, {
         text: event.payload.text,
+        annotations: event.payload.annotations,
         turnInstructions: event.payload.turnInstructions ?? null,
         resources: event.payload.resources ?? [],
         model: event.payload.model ?? null,
@@ -2056,8 +2464,8 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
   // GET .../stream-capabilities — the capability-negotiation read. Returns the
   // SessionCapabilities doc (descriptor + lease liveness/epoch + os + the
   // shared-exposure disclosure + the calling principal's acknowledgment state),
-  // API-direct. The desktop URL/token stay null until P4 mints them (gated by
-  // liveness=cold until a box is warm); the read is non-mutating.
+  // API-direct. It is a pure descriptor read: every URL/token stays null until an
+  // exact, permission-checked POST /viewers grant mints it just in time.
   app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/stream-capabilities", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:read");
@@ -2067,6 +2475,15 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     if (!session) {
       throw new HTTPException(404, { message: "session not found" });
     }
+    // Capability truth follows the ACTIVE placement, not the session's managed
+    // home lease. A connected machine has no Modal group lease; treating that
+    // absence as `cold` makes the client suppress the very viewer attach that
+    // would mint its relay terminal/desktop cells. Resolve the active target once
+    // and use the selfhosted liveness probe when it is a connected machine.
+    const activeSandbox = session.activeSandboxId
+      ? await getSandbox(db, workspaceId, session.activeSandboxId)
+      : null;
+    const selfhostedActive = activeSandbox?.kind === "selfhosted";
     const lease = await readGroupLease(
       { db, settings },
       { workspaceId, sandboxGroupId: session.sandboxGroupId },
@@ -2074,12 +2491,9 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     const { shared, sharedSessionIds } = await resolveSharedExposure(workspaceId, session);
     const visibleSharedSessionIds = relatedSessionAccessFor(c) === "root" ? sharedSessionIds : [];
     // Per-principal acknowledgment: A acknowledging does not consent for B. The
-    // un-redacted desktop stream ALWAYS requires the un-redacted ack; a shared box
-    // ADDITIONALLY requires the shared-exposure ack. Both must match the POST
-    // /viewers gate EXACTLY — otherwise a principal who recorded shared consent
-    // 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).
+    // Surface consent state so the UI can decide whether an explicit desktop
+    // grant may be requested. This descriptor read never mints a credential; the
+    // POST /viewers grant below re-checks both consent bits and stream:view.
     const ack = await getStreamAcknowledgment(db, {
       workspaceId,
       sandboxGroupId: session.sandboxGroupId,
@@ -2089,117 +2503,68 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
       ? 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)
-    // acknowledgment is present AND the box is WARM, mint the REAL DesktopStream
-    // cell IN-PROCESS: resume the box by id, ensureDisplayStack (idempotent),
-    // exposeStreamPort (resolve the 6080 tunnel + mint the scoped token), record
-    // data_plane_url under the epoch fence, and emit stream.url.rotated to other
-    // viewers on a box rollover. The handshake never SPINS UP a cold box (that is
-    // the viewer-attach path) — a cold lease stays lease_cold. A degraded mint
-    // (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");
-    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 } : {}),
-        },
-      );
-    }
-
-    // P5.t — the REAL PTY terminal cell, served API-DIRECT. Independent of the
-    // desktop: it gates ONLY on sandboxTerminalEnabled + a real-PTY backend + a
-    // WARM box (NO un-redacted ack — the terminal cell has no acknowledgment
-    // gate). A degraded mint (terminal off / no secret / ttyd or tunnel failure)
-    // 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");
-    if (terminalUnlocked) {
-      terminalStream = await mintTerminalStream(
-        { db, settings, bus },
-        {
-          accountId: grant.accountId,
-          workspaceId,
-          session,
-          viewerId: grant.subjectId,
-          ...(lease ? { lease } : {}),
-        },
-      );
-    }
-
-    const capabilities = negotiateCapabilities({
+    // This GET is deliberately descriptor-only: no provider resume, display/ttyd
+    // startup, port exposure, or short-lived bearer mint. Besides enforcing least
+    // privilege, that keeps the 120-second stream credentials from aging before a
+    // user opens their surface. POST /viewers is the sole credential grant.
+    const commonNegotiation = {
       sessionId,
-      backend: session.sandboxBackend as SandboxBackend,
-      os: session.sandboxOs,
-      liveness: lease?.liveness ?? "cold",
-      leaseEpoch: lease?.leaseEpoch ?? 0,
-      workspaceGeneration: lease?.workspaceGeneration ?? null,
-      archiveGeneration: lease?.archiveGeneration ?? null,
-      archiveComplete: lease?.archiveComplete ?? false,
       desktopEnabled: settings.sandboxDesktopEnabled,
       // Human take-control: when the desktop is available + this policy is on
       // (default), the cell is mode "interactive" — the noVNC viewer drives :0
       // (x11vnc runs without -viewonly). Off → mode "read-only" (client disables
       // take-control). Independent of the agent's computerUseReadOnly.
       desktopInteractive: settings.sandboxDesktopInteractive,
-      // P4.3 computer-use: the agent drives :0 (xdotool/scrot); availability
+      // P4.3 computer-use: the agent drives the active display; availability
       // tracks the desktop tier + a desktop-capable backend.
       computerUseEnabled: settings.computerUseEnabled,
       computerUseReadOnly: settings.computerUseReadOnly,
-      // Graceful degrade (stream-token availability contract): if desktop is enabled but no stream-token
-      // secret is resolvable, the desktop cell reports transport:null rather
-      // than advertising a plane we can never authorize.
+      // Graceful degrade when scoped stream credentials cannot be minted.
       streamTokenSecretAvailable: !streamTokenDegraded(settings),
       desktopAcknowledged: acknowledged,
       shared,
       sharedSessionIds: visibleSharedSessionIds,
-      // The minted live address (null when not unlocked/degraded). The resolver
-      // only folds it in when the desktop gates pass + the ack is present.
-      ...(desktopStream
-        ? {
-            desktopStream: {
-              url: desktopStream.url,
-              token: desktopStream.token,
-              expiresAt: desktopStream.expiresAt,
-              resolution: desktopStream.resolution,
-            },
-          }
-        : {}),
-      // P5.t — the terminal policy toggle + the minted pty-ws address. The
-      // resolver advertises sse-events (firehose) on a cold/disabled terminal and
-      // folds the live pty-ws url/token in only when the gates passed + minted.
       terminalEnabled: settings.sandboxTerminalEnabled,
-      ...(terminalStream
-        ? {
-            terminalStream: {
-              url: terminalStream.url,
-              token: terminalStream.token,
-              expiresAt: terminalStream.expiresAt,
-            },
-          }
-        : {}),
-    });
+    } as const;
+
+    let capabilities;
+    if (selfhostedActive && activeSandbox.enrollmentId) {
+      const enrollment = await getEnrollment(db, workspaceId, activeSandbox.enrollmentId);
+      let probeResponded = false;
+      if (enrollment?.status === "active") {
+        const machine = new SelfhostedSession({
+          workspaceId,
+          agentId: enrollment.id,
+          controlRpc: new NatsControlRpc(async () => bus.getRequestConnection()),
+          relay: relayConfigFromSettings(settings),
+          epoch: session.activeEpoch,
+          timeoutMs: settings.sandboxSelfhostedControlTimeoutMs,
+        });
+        try {
+          probeResponded = await machine.ping();
+        } catch {
+          probeResponded = false;
+        }
+      }
+      capabilities = await negotiateSelfhostedCapabilities({
+        ...commonNegotiation,
+        os: enrollment?.os ?? session.sandboxOs,
+        leaseEpoch: session.activeEpoch,
+        enrollment,
+        probeResponded,
+      });
+    } else {
+      capabilities = negotiateCapabilities({
+        ...commonNegotiation,
+        backend: session.sandboxBackend as SandboxBackend,
+        os: session.sandboxOs,
+        liveness: lease?.liveness ?? "cold",
+        leaseEpoch: lease?.leaseEpoch ?? 0,
+        workspaceGeneration: lease?.workspaceGeneration ?? null,
+        archiveGeneration: lease?.archiveGeneration ?? null,
+        archiveComplete: lease?.archiveComplete ?? false,
+      });
+    }
 
     const repositoryRoots = [
       ...new Set(
@@ -2238,11 +2603,8 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
       },
     };
     if (capabilities.DesktopStream.transport !== null) {
-      const activeSandbox = session.activeSandboxId
-        ? await getSandbox(db, workspaceId, session.activeSandboxId)
-        : null;
       const wire = resolveActiveDesktopTransport(
-        activeSandbox?.kind === "selfhosted",
+        selfhostedActive,
         settings.sandboxDesktopInteractive !== false,
       );
       responseCapabilities = {
@@ -2316,20 +2678,31 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         message: "invalid viewer attach request",
       });
     }
-    // Consent gate (P3.2 / addendum E.1): ONLY the un-redacted DESKTOP pixel plane
-    // requires the calling principal's acknowledgment (recorded per group+subject;
-    // a shared box additionally needs the shared-exposure consent). A TERMINAL-ONLY
-    // warm attach (`desktop:false`, the default) carries NO consent gate — a shell
-    // is interactive by nature and the gate is the scoped tunnel URL + stream token
-    // — so it warms the box and mints the pty-ws terminal cell without a 409. Gating
-    // the terminal attach behind the desktop ack (the bug this fixes) dead-ended the
-    // interactive terminal: the box never warmed → the Terminal cell stayed on the
-    // read-only sse-events firehose forever ("read only"), and with the desktop tier
-    // off by default there was no consent flow to ever clear the gate.
+    // Resolve exact requested planes before authorization. Empty and
+    // `desktop:false` v1 bodies remain terminal-only during rolling upgrades;
+    // either new plane flag selects exact semantics. This closes desktop→terminal
+    // privilege bleed and lets file edits avoid unrelated terminal bearers.
     const wantDesktop = parsed.data.desktop ?? false;
-    requirePermission(grant, wantDesktop ? "stream:view" : "terminal:attach");
-    const { shared } = await resolveSharedExposure(workspaceId, session);
+    const wantFiles = parsed.data.files ?? false;
+    const hasExactPlaneSet = parsed.data.terminal !== undefined || parsed.data.files !== undefined;
+    // v1 clients sent only `desktop:false` for both terminal and file warming;
+    // retain its terminal-only grant during rolling upgrades. Presence of either
+    // v2 flag switches to exact-plane semantics.
+    const wantTerminal = parsed.data.terminal ?? (!hasExactPlaneSet && !wantDesktop);
+    if (!wantDesktop && !wantTerminal && !wantFiles) {
+      throw new HTTPException(400, {
+        message: "viewer attach requires a live plane",
+      });
+    }
+    if (wantDesktop) requirePermission(grant, "stream:view");
+    if (wantTerminal) requirePermission(grant, "terminal:attach");
+    if (wantFiles) requirePermission(grant, "files:write");
+
+    // Consent gate (P3.2 / addendum E.1): only the explicitly requested,
+    // un-redacted desktop plane needs acknowledgment. Terminal and files retain
+    // their independent permission boundaries.
     if (wantDesktop) {
+      const { shared } = await resolveSharedExposure(workspaceId, session);
       const ack = await getStreamAcknowledgment(db, {
         workspaceId,
         sandboxGroupId: session.sandboxGroupId,
@@ -2372,7 +2745,8 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         dataPlaneUrl: null,
       };
       if (
-        (settings.sandboxDesktopEnabled || settings.sandboxTerminalEnabled) &&
+        ((wantDesktop && settings.sandboxDesktopEnabled) ||
+          (wantTerminal && settings.sandboxTerminalEnabled)) &&
         !streamTokenDegraded(settings)
       ) {
         if (wantDesktop && settings.sandboxDesktopEnabled) {
@@ -2384,7 +2758,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
             // No Modal lease for selfhosted-active; the mint routes to the relay.
           });
         }
-        if (settings.sandboxTerminalEnabled) {
+        if (wantTerminal && settings.sandboxTerminalEnabled) {
           terminal = await mintTerminalStream(viewerServices, {
             accountId: grant.accountId,
             workspaceId,
@@ -2399,6 +2773,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         accountId: grant.accountId,
         workspaceId,
         session,
+        waitSignal: c.req.raw.signal,
         ...(parsed.data.viewerId ? { viewerId: parsed.data.viewerId } : {}),
       });
 
@@ -2410,7 +2785,8 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): 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) &&
+        ((wantDesktop && settings.sandboxDesktopEnabled) ||
+          (wantTerminal && settings.sandboxTerminalEnabled)) &&
         !streamTokenDegraded(settings)
       ) {
         const lease = await readGroupLease(
@@ -2418,9 +2794,8 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
           { 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.
+          // Mint only explicitly authorized plane credentials. The shared holder
+          // supplies liveness; it is not itself authority for another plane.
           if (wantDesktop && settings.sandboxDesktopEnabled) {
             stream = await mintDesktopStream(viewerServices, {
               accountId: grant.accountId,
@@ -2430,10 +2805,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
               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) {
+          if (wantTerminal && settings.sandboxTerminalEnabled) {
             terminal = await mintTerminalStream(viewerServices, {
               accountId: grant.accountId,
               workspaceId,
@@ -2445,42 +2817,42 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         }
       }
     }
-    return c.json(
-      {
-        ...result,
-        dataPlaneUrl: stream?.url ?? result.dataPlaneUrl,
-        streamToken: stream?.token ?? null,
-        streamExpiresAt: stream?.expiresAt ?? null,
-        resolution: stream?.resolution ?? null,
-        // Transport MUST match where the pixels were minted: a selfhosted-active box
-        // serves the RELAY framebuffer (relay-frames/frames), a Modal box serves noVNC
-        // (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,
-        client: stream ? (selfhostedActive ? ("frames" as const) : ("novnc" as const)) : null,
-        // The REAL PTY terminal address (pty-ws), null when degraded.
-        terminalUrl: terminal?.url ?? null,
-        terminalToken: terminal?.token ?? null,
-        terminalExpiresAt: terminal?.expiresAt ?? null,
-        terminalTransport: terminal ? ("pty-ws" as const) : null,
-      },
-      201,
-    );
+    const response = {
+      ...result,
+      dataPlaneUrl: stream?.url ?? null,
+      streamToken: stream?.token ?? null,
+      streamExpiresAt: stream?.expiresAt ?? null,
+      resolution: stream?.resolution ?? null,
+      // Transport MUST match where the pixels were minted: a selfhosted-active box
+      // serves the RELAY framebuffer (relay-frames/frames), a Modal box serves noVNC
+      // (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,
+      client: stream ? (selfhostedActive ? ("frames" as const) : ("novnc" as const)) : null,
+      // The REAL PTY terminal address (pty-ws), null when degraded.
+      terminalUrl: terminal?.url ?? null,
+      terminalToken: terminal?.token ?? null,
+      terminalExpiresAt: terminal?.expiresAt ?? null,
+      terminalTransport: terminal?.transport ?? null,
+    } satisfies AttachViewerResponse;
+    return c.json(response, 201);
   });
 
   // POST .../viewers/:viewerId/heartbeat — refresh the holder TTL (epoch-fenced).
-  // A holder can represent the terminal-only plane, so lifecycle control uses
-  // terminal:attach. Desktop callers continue to pass via workspace:admin.
+  // A holder may belong to any exact live plane. Lifecycle control accepts any
+  // permission that could have minted it; the unguessable holder id and workspace
+  // grant remain the ownership boundary.
   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, "terminal:attach");
+      const grant = await requireAccessGrant(c, deps, workspaceId);
+      requireViewerLifecyclePermission(grant);
       assertOwnershipEnabled();
       const sessionId = c.req.param("sessionId");
       const session = await getSession(db, workspaceId, sessionId);
@@ -2510,7 +2882,8 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
   // DELETE .../viewers/:viewerId — release the holder (idempotent).
   app.delete("/v1/workspaces/:workspaceId/sessions/:sessionId/viewers/:viewerId", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "terminal:attach");
+    const grant = await requireAccessGrant(c, deps, workspaceId);
+    requireViewerLifecyclePermission(grant);
     assertOwnershipEnabled();
     const sessionId = c.req.param("sessionId");
     const session = await getSession(db, workspaceId, sessionId);
@@ -2577,11 +2950,9 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
   // FS uses files:read for reads, files:write for mutations; Git is read-only
   // (rides files:read); Terminal exec + PTY ride terminal:attach.
 
-  type ChannelARouteCtx = {
-    accountId: string;
-    workspaceId: string;
-    session: Session;
-    subjectId: string;
+  type ChannelARouteCtx = ChannelAContext & {
+    waitSignal: AbortSignal;
+    operation: ChannelAOperation;
   };
 
   // Shared preamble: grant BEFORE parse, ownership gate, session lookup. Returns
@@ -2589,6 +2960,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
   async function channelAPreamble(
     c: Context,
     permission: "files:read" | "files:write" | "terminal:attach",
+    operation: ChannelAOperation,
   ): Promise<ChannelARouteCtx> {
     const workspaceId = c.req.param("workspaceId") ?? "";
     const grant = await requireAccessGrant(c, deps, workspaceId, permission);
@@ -2603,6 +2975,8 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
       workspaceId,
       session,
       subjectId: grant.subjectId,
+      waitSignal: c.req.raw.signal,
+      operation,
     };
   }
 
@@ -2622,55 +2996,53 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
 
   // ── FileSystem ──────────────────────────────────────────────────────────
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/fs/list", async (c) => {
-    const ctx = await channelAPreamble(c, "files:read");
+    const ctx = await channelAPreamble(c, "files:read", "fs.list");
     const req = await parseChannelABody(c, FsListRequest);
-    const out = await withChannelA(channelAServices, ctx, ({ service }) => service.fsList(req));
+    const out = await withChannelARead(channelAServices, ctx, ({ service }) => service.fsList(req));
     return c.json(out);
   });
 
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/fs/list-batch", async (c) => {
-    const ctx = await channelAPreamble(c, "files:read");
+    const ctx = await channelAPreamble(c, "files:read", "fs.list-batch");
     const req = await parseChannelABody(c, FsListBatchRequest);
-    const out = await withChannelA(channelAServices, ctx, async ({ service }) => ({
-      results: await Promise.all(
-        req.requests.map((request) =>
-          Promise.resolve().then(async () => await service.fsList(request)),
-        ),
+    const out = await withChannelARead(channelAServices, ctx, async ({ service }) => ({
+      results: await runConcurrentChannelAReads(
+        req.requests.map((request) => async () => await service.fsList(request)),
       ),
     }));
     return c.json(out);
   });
 
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/fs/read", async (c) => {
-    const ctx = await channelAPreamble(c, "files:read");
+    const ctx = await channelAPreamble(c, "files:read", "fs.read");
     const req = await parseChannelABody(c, FsReadRequest);
-    const out = await withChannelA(channelAServices, ctx, ({ service }) => service.fsRead(req));
+    const out = await withChannelARead(channelAServices, 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 ctx = await channelAPreamble(c, "files:write", "fs.write");
     const req = await parseChannelABody(c, FsWriteRequest);
     const out = await withChannelA(channelAServices, 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 ctx = await channelAPreamble(c, "files:write", "fs.delete");
     const req = await parseChannelABody(c, FsDeleteRequest);
     const out = await withChannelA(channelAServices, 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 ctx = await channelAPreamble(c, "files:write", "fs.move");
     const req = await parseChannelABody(c, FsMoveRequest);
     const out = await withChannelA(channelAServices, 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 ctx = await channelAPreamble(c, "files:write", "fs.mkdir");
     const req = await parseChannelABody(c, FsMkdirRequest);
     const out = await withChannelA(channelAServices, ctx, ({ service }) => service.fsMkdir(req));
     return c.json(out);
@@ -2678,50 +3050,87 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
 
   // ── Git (read-only) ─────────────────────────────────────────────────────
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/git/status", async (c) => {
-    const ctx = await channelAPreamble(c, "files:read");
+    const ctx = await channelAPreamble(c, "files:read", "git.status");
     const req = await parseChannelABody(c, GitStatusRequest);
-    const out = await withChannelA(channelAServices, ctx, ({ service }) => service.gitStatus(req));
+    const out = await withChannelARead(channelAServices, 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 ctx = await channelAPreamble(c, "files:read", "git.diff");
     const req = await parseChannelABody(c, GitDiffRequest);
-    const out = await withChannelA(channelAServices, ctx, ({ service }) => service.gitDiff(req));
+    const out = await withChannelARead(channelAServices, ctx, ({ service }) =>
+      service.gitDiff(req),
+    );
     return c.json(out);
   });
 
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/git/read-batch", async (c) => {
-    const ctx = await channelAPreamble(c, "files:read");
+    const ctx = await channelAPreamble(c, "files:read", "git.read-batch");
     const req = await parseChannelABody(c, GitReadBatchRequest);
-    const out = await withChannelA(channelAServices, ctx, async ({ service }) => ({
-      results: await Promise.all(
-        req.requests.map(async (request) => {
+    const out = await withChannelARead(channelAServices, ctx, async ({ service }) => {
+      type StatusResult = Awaited<ReturnType<typeof service.gitStatus>>;
+      type DiffResult = Awaited<ReturnType<typeof service.gitDiff>>;
+      type ReadResult =
+        | { requestIndex: number; kind: "status"; value: StatusResult }
+        | { requestIndex: number; kind: "diff"; value: DiffResult };
+      const operations: Array<() => Promise<ReadResult>> = [];
+      req.requests.forEach((request, requestIndex) => {
+        operations.push(async () => ({
+          requestIndex,
+          kind: "status" as const,
+          value: await service.gitStatus(request.status),
+        }));
+        if (request.diff) {
           const diffRequest = request.diff;
-          const [status, diff] = await Promise.all([
-            Promise.resolve().then(async () => await service.gitStatus(request.status)),
-            diffRequest
-              ? Promise.resolve().then(async () => await service.gitDiff(diffRequest))
-              : Promise.resolve(undefined),
-          ]);
+          operations.push(async () => ({
+            requestIndex,
+            kind: "diff" as const,
+            value: await service.gitDiff(diffRequest),
+          }));
+        }
+      });
+
+      const reads = await runConcurrentChannelAReads(operations);
+      const statuses = new Map<number, StatusResult>();
+      const diffs = new Map<number, DiffResult>();
+      for (const read of reads) {
+        if (read.kind === "status") statuses.set(read.requestIndex, read.value);
+        else diffs.set(read.requestIndex, read.value);
+      }
+
+      return {
+        results: req.requests.map((request, requestIndex) => {
+          const status = statuses.get(requestIndex);
+          if (!status) {
+            throw new Error(`Workspace Git batch omitted status result ${requestIndex}.`);
+          }
+          const diff = request.diff ? diffs.get(requestIndex) : undefined;
+          if (request.diff && !diff) {
+            throw new Error(`Workspace Git batch omitted diff result ${requestIndex}.`);
+          }
           return { status, ...(diff ? { diff } : {}) };
         }),
-      ),
-    }));
+      };
+    });
     return c.json(out);
   });
 
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/git/log", async (c) => {
-    const ctx = await channelAPreamble(c, "files:read");
+    const ctx = await channelAPreamble(c, "files:read", "git.log");
     const req = await parseChannelABody(c, GitLogRequest);
-    const out = await withChannelA(channelAServices, ctx, ({ service }) => service.gitLog(req));
+    const out = await withChannelARead(channelAServices, 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 ctx = await channelAPreamble(c, "files:read", "git.show");
     const req = await parseChannelABody(c, GitShowRequest);
-    const out = await withChannelA(channelAServices, ctx, ({ service }) => service.gitShow(req));
+    const out = await withChannelARead(channelAServices, ctx, ({ service }) =>
+      service.gitShow(req),
+    );
     return c.json(out);
   });
 
@@ -2784,7 +3193,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
 
   // ── Terminal: synchronous exec ────────────────────────────────────────────
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/terminal/exec", async (c) => {
-    const ctx = await channelAPreamble(c, "terminal:attach");
+    const ctx = await channelAPreamble(c, "terminal:attach", "terminal.exec");
     const req = await parseChannelABody(c, TerminalExecRequest);
     const out = await withChannelA(channelAServices, ctx, ({ service }) =>
       service.terminalExec(req),
@@ -2794,7 +3203,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
 
   // ── Terminal: interactive PTY control (output rides A1) ───────────────────
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/terminal/pty", async (c) => {
-    const ctx = await channelAPreamble(c, "terminal:attach");
+    const ctx = await channelAPreamble(c, "terminal:attach", "terminal.pty.open");
     const req = await parseChannelABody(c, PtyOpenRequest);
     if (ctx.session.sandboxBackend === "selfhosted" || ctx.session.activeSandboxId !== null) {
       throw new HTTPException(409, {
@@ -2903,7 +3312,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
   });
 
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/terminal/pty/write", async (c) => {
-    const ctx = await channelAPreamble(c, "terminal:attach");
+    const ctx = await channelAPreamble(c, "terminal:attach", "terminal.pty.write");
     const req = await parseChannelABody(c, PtyWriteRequest);
     const pty = await getOpenPtySession(db, {
       workspaceId: ctx.workspaceId,
@@ -2967,7 +3376,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
   });
 
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/terminal/pty/resize", async (c) => {
-    const ctx = await channelAPreamble(c, "terminal:attach");
+    const ctx = await channelAPreamble(c, "terminal:attach", "terminal.pty.resize");
     const req = await parseChannelABody(c, PtyResizeRequest);
     const pty = await getOpenPtySession(db, {
       workspaceId: ctx.workspaceId,
@@ -2999,7 +3408,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
   });
 
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/terminal/pty/close", async (c) => {
-    const ctx = await channelAPreamble(c, "terminal:attach");
+    const ctx = await channelAPreamble(c, "terminal:attach", "terminal.pty.close");
     const req = await parseChannelABody(c, PtyCloseRequest);
     const pty = await getOpenPtySession(db, {
       workspaceId: ctx.workspaceId,
@@ -3028,6 +3437,13 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
   });
 }
 
+export function goalProposalMatchesExpectedRevision(
+  revision: Pick<SessionGoalRevision, "baseObjectiveRevision">,
+  expectedObjectiveRevision: number,
+): boolean {
+  return revision.baseObjectiveRevision === expectedObjectiveRevision;
+}
+
 function eventListLimit(raw: string | undefined, max = 2000, fallback = 500): number {
   const limit = Number(raw ?? fallback);
   if (!Number.isFinite(limit)) {
@@ -3097,6 +3513,7 @@ export function sessionAuthorizationOperationForHttp(
     return null;
   }
   if (suffix === "/pin" && verb === "PUT") return "session.pin.write";
+  if (suffix === "/channel" && verb === "PUT") return "session.channel.write";
   if (suffix === "/tool-policy" && verb === "PUT") return "session.tool_policy.write";
   if (/^\/mcp-servers\/[^/]+\/approval-policy$/.test(suffix) && verb === "PATCH") {
     return "session.mcp.approval_policy.write";
@@ -3111,6 +3528,9 @@ export function sessionAuthorizationOperationForHttp(
   if (suffix === "/realtime/gateway" && verb === "POST") {
     return "session.realtime.start";
   }
+  if (suffix === "/realtime/supergrok" && verb === "POST") {
+    return "session.realtime.start";
+  }
   if (suffix === "/realtime" && verb === "POST") {
     return "session.realtime.start";
   }
@@ -3133,6 +3553,10 @@ export function sessionAuthorizationOperationForHttp(
         ? "session.goal.write"
         : null;
   }
+  if (suffix === "/goal/revisions" && verb === "GET") return "session.goal.read";
+  if (/^\/goal\/revisions\/[^/]+\/apply$/.test(suffix) && verb === "POST") {
+    return "session.goal.write";
+  }
   if (suffix === "/context/clear" || suffix === "/context/compact") {
     return verb === "POST" ? "session.context.write" : null;
   }
@@ -3311,6 +3735,111 @@ function sessionListQuery(
   };
 }
 
+export type AgentTopologyCursorEnvelope = {
+  cursor: SessionDiscoveryCursor;
+  parentSessionId: string | null;
+  search: string | null;
+};
+
+export function encodeAgentTopologyCursor(value: AgentTopologyCursorEnvelope): string {
+  return Buffer.from(JSON.stringify({ v: 1, ...value }), "utf8").toString("base64url");
+}
+
+function decodeAgentTopologyCursor(value: string): AgentTopologyCursorEnvelope {
+  if (value.length > 2_048) {
+    throw new HTTPException(400, {
+      message: "agent topology cursor is invalid",
+    });
+  }
+  try {
+    const parsed = z
+      .object({
+        v: z.literal(1),
+        parentSessionId: z.string().uuid().nullable(),
+        search: z.string().max(200).nullable(),
+        cursor: z.object({
+          orderBy: z.enum(["createdAt", "updatedAt"]),
+          sortRevision: z.string().max(64),
+          sortAt: z.string().max(64),
+          id: z.string().uuid(),
+          snapshotAt: z.string().max(64),
+          snapshotRevision: z.string().max(64),
+          updatedAfter: z.string().max(64).nullable(),
+        }),
+      })
+      .parse(JSON.parse(Buffer.from(value, "base64url").toString("utf8")));
+    if (
+      parsed.cursor.orderBy !== "updatedAt" ||
+      parsed.cursor.updatedAfter !== null ||
+      !/^(?:0|[1-9]\d*)$/.test(parsed.cursor.sortRevision) ||
+      !/^(?:0|[1-9]\d*)$/.test(parsed.cursor.snapshotRevision) ||
+      BigInt(parsed.cursor.sortRevision) > 9_223_372_036_854_775_807n ||
+      BigInt(parsed.cursor.snapshotRevision) > 9_223_372_036_854_775_807n ||
+      Number.isNaN(Date.parse(parsed.cursor.sortAt)) ||
+      Number.isNaN(Date.parse(parsed.cursor.snapshotAt))
+    ) {
+      throw new Error("invalid topology cursor fields");
+    }
+    return parsed;
+  } catch {
+    throw new HTTPException(400, {
+      message: "agent topology cursor is invalid",
+    });
+  }
+}
+
+export function agentTopologyQuery(query: Record<string, string>): {
+  limit: number;
+  parentSessionId: string | null;
+  search: string | undefined;
+  cursor: SessionDiscoveryCursor | undefined;
+} {
+  const rawLimit = query.limit;
+  const limit = rawLimit === undefined ? 25 : Number(rawLimit);
+  if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+    throw new HTTPException(400, {
+      message: "limit must be an integer between 1 and 100",
+    });
+  }
+  const rawParent = query.parentSessionId;
+  if (
+    rawParent !== undefined &&
+    rawParent !== "null" &&
+    !z.string().uuid().safeParse(rawParent).success
+  ) {
+    throw new HTTPException(400, {
+      message: 'parentSessionId must be a session id or the literal "null"',
+    });
+  }
+  const parentSessionId = rawParent === undefined || rawParent === "null" ? null : rawParent;
+  const search = query.search?.trim();
+  if (search && search.length > 200) {
+    throw new HTTPException(400, {
+      message: "search must be at most 200 characters",
+    });
+  }
+  if (search && rawParent !== undefined) {
+    throw new HTTPException(400, {
+      message: "search cannot be combined with parentSessionId",
+    });
+  }
+  const envelope = query.cursor ? decodeAgentTopologyCursor(query.cursor) : undefined;
+  if (
+    envelope &&
+    (envelope.parentSessionId !== parentSessionId || envelope.search !== (search || null))
+  ) {
+    throw new HTTPException(400, {
+      message: "agent topology cursor does not match its filters",
+    });
+  }
+  return {
+    limit,
+    parentSessionId,
+    search: search || undefined,
+    cursor: envelope?.cursor,
+  };
+}
+
 function compactEvents(raw: string | undefined): boolean {
   return raw === "1" || raw === "true";
 }
@@ -3336,6 +3865,11 @@ function optionalEventSequence(raw: string | undefined): number | undefined {
 
 /** Stable, value-free JSON errors for only the create-session boundary. */
 export function sessionCreateErrorResponse(c: Context, error: unknown): Response {
+  if (error instanceof ChannelNotFoundError) {
+    // Covers the create-vs-channel-delete race the pre-validation cannot: the
+    // insert's FK rejection surfaces as the same 422 an unknown id gets.
+    return c.json({ code: "SESSION_CREATE_REJECTED", message: error.message }, 422);
+  }
   if (error instanceof SessionSpawnDeniedError) {
     return c.json(
       sessionSpawnDenialEnvelope(error),
@@ -3363,6 +3897,22 @@ export function sessionCreateErrorResponse(c: Context, error: unknown): Response
   throw error;
 }
 
+export function parseSessionEventAdmission(raw: unknown): ClientSessionEvent {
+  const parsed = ClientSessionEvent.safeParse(raw);
+  if (!parsed.success) {
+    throw new HTTPException(422, { message: "invalid session event" });
+  }
+  return parsed.data;
+}
+
+export function parseSteerSessionAdmission(raw: unknown): SteerSessionMessageRequest {
+  const parsed = SteerSessionMessageRequest.safeParse(raw);
+  if (!parsed.success) {
+    throw new HTTPException(422, { message: "invalid steer request" });
+  }
+  return parsed.data;
+}
+
 function zodErrorFields(error: ZodError): string {
   const paths = [
     ...new Set(
@@ -3398,10 +3948,11 @@ type EffectivePolicyContext = {
 async function loadEffectivePolicyContext(
   deps: ApiRouteDeps,
   workspaceId: string,
+  subjectId: string,
 ): Promise<EffectivePolicyContext> {
   const [workspaceServerIds, workspaceDefaultServerIds] = await Promise.all([
-    workspaceSessionToolPolicyServerIds(deps.db, workspaceId, deps.settings),
-    workspaceSessionToolPolicyDefaultServerIds(deps.db, workspaceId, deps.settings),
+    workspaceSessionToolPolicyServerIds(deps.db, workspaceId, deps.settings, subjectId),
+    workspaceSessionToolPolicyDefaultServerIds(deps.db, workspaceId, deps.settings, subjectId),
   ]);
   return { workspaceServerIds, workspaceDefaultServerIds };
 }
@@ -3409,9 +3960,10 @@ async function loadEffectivePolicyContext(
 async function withEffectivePolicy(
   deps: ApiRouteDeps,
   workspaceId: string,
+  subjectId: string,
   session: Session,
 ): Promise<Session> {
-  const policy = await loadEffectivePolicyContext(deps, workspaceId);
+  const policy = await loadEffectivePolicyContext(deps, workspaceId, subjectId);
   return sessionWithEffectiveToolPolicy(
     session,
     policy.workspaceServerIds,