@opengeni/api-router 0.23.1 → 0.26.1

package/src/routes/sessions.ts

@@ -55,9 +55,12 @@ import {
   ViewerHeartbeatRequest,
   WORKSPACE_CONTROL_ACTOR_MAX_BYTES,
   workspaceControlUtf8Bytes,
+  type AccessGrant,
+  type AttachViewerResponse,
   type SandboxBackend,
   type LineageNode,
   type Session,
+  type AgentTopologyPageResponse,
   type ErrorCode,
   type SessionAuthorizationOperation,
   type SessionQueueSnapshot,
@@ -86,6 +89,8 @@ import {
   listSessionEventPage,
   listSessionHumanInputRequests,
   listSessionIdsInGroup,
+  listSessionDiscoverySummaries,
+  listSessionDiscoveryAncestorPaths,
   listSessionsForSubject,
   getLatestStartedSessionTurn,
   listSessionTurns,
@@ -93,8 +98,8 @@ import {
   projectSessionForRelatedAccess,
   recordStreamAcknowledgment,
   requestSessionCompaction,
-  setSessionCodexPin,
-  withCodexCapacityMutation,
+  setSessionCodexPinInTransaction,
+  withSessionCodexCapacityMutation,
   setSessionPin,
   SessionPinVersionConflictError,
   SessionPinAccessError,
@@ -124,6 +129,7 @@ import {
   sessionLatestWorkspaceCapture,
   renewSessionRealtimeInTransaction,
   syncSessionRealtimeLedgerInTransaction,
+  withWorkspaceSessionActivityRls,
   withWorkspaceRls,
   workspaceCaptureAtRevision,
   type AppendEventInput,
@@ -131,6 +137,8 @@ import {
   type SandboxPtyProcessIdentity,
   type SandboxRetainedProcess,
   type Database,
+  type SessionDiscoveryCursor,
+  type SessionDiscoveryAncestor,
 } from "@opengeni/db";
 import {
   appendAndPublishEvents,
@@ -143,12 +151,20 @@ import {
   GatewayRealtimeBrokerError,
 } from "../gateway-realtime";
 import { z, ZodError } from "zod";
-import { withChannelA, type ChannelAContext, type ChannelAHandle } from "../sandbox/channel-a";
+import {
+  runConcurrentChannelAReads,
+  withChannelA,
+  withChannelARead,
+  type ChannelAContext,
+  type ChannelAHandle,
+  type ChannelAOperation,
+} from "../sandbox/channel-a";
 import { negotiateCapabilities } 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,
@@ -206,6 +222,19 @@ 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 };
@@ -407,7 +436,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 +540,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 +562,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 +656,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 (
@@ -589,16 +695,14 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
       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");
@@ -626,16 +730,14 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         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");
@@ -662,16 +764,14 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
       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");
@@ -1034,16 +1134,14 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         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 +1180,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         await withEffectivePolicy(
           deps,
           workspaceId,
+          grant.subjectId,
           projectSessionForRelatedAccess(session, relatedSessionAccessFor(c)),
         ),
       );
@@ -1106,7 +1205,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 +1247,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 };
       },
     );
@@ -1208,7 +1307,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 +1345,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(
@@ -1563,6 +1662,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 +1945,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 +1970,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 +1991,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 +2156,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");
@@ -2074,12 +2174,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,65 +2186,10 @@ 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 } : {}),
-        },
-      );
-    }
-
+    // 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 capabilities = negotiateCapabilities({
       sessionId,
       backend: session.sandboxBackend as SandboxBackend,
@@ -2174,31 +2216,9 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
       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.
+      // Plane policy only. Live addresses are intentionally absent on a
+      // descriptor read and arrive from an authorized viewer grant.
       terminalEnabled: settings.sandboxTerminalEnabled,
-      ...(terminalStream
-        ? {
-            terminalStream: {
-              url: terminalStream.url,
-              token: terminalStream.token,
-              expiresAt: terminalStream.expiresAt,
-            },
-          }
-        : {}),
     });
 
     const repositoryRoots = [
@@ -2316,20 +2336,29 @@ 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 +2401,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 +2414,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 +2429,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 +2441,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 +2450,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 +2461,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 +2473,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 ? ("pty-ws" as const) : 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 +2538,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 +2606,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 +2616,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 +2631,8 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
       workspaceId,
       session,
       subjectId: grant.subjectId,
+      waitSignal: c.req.raw.signal,
+      operation,
     };
   }
 
@@ -2622,55 +2652,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 +2706,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 +2849,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 +2859,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 +2968,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 +3032,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 +3064,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,
@@ -3311,6 +3376,99 @@ 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";
 }
@@ -3363,6 +3521,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 +3572,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 +3584,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,