@opengeni/api-router 0.30.1 → 1.0.0

package/src/routes/sessions.ts

@@ -1,6 +1,25 @@
+import { getRetainedProviderCommand } from "@opengeni/db/retained-provider-commands";
+import { UnsupportedLatencyModeError } from "@opengeni/config";
+import { searchSessionMessagesForSubject, SessionMessageSearchCursorError } from "@opengeni/db";
+import { listSessionEventSlices } from "@opengeni/db/session-event-slices";
+import * as sessionPreviewSchema from "@opengeni/db/schema";
+import { and, eq, sql } from "drizzle-orm";
+import { SessionMessageSearchRequest } from "@opengeni/contracts";
+import { scheduledSessionIds } from "@opengeni/db";
+import { isVerifiedDelegatedHumanAuthorization, withSiteSessionOrigin } from "@opengeni/core";
+import { freezeSessionRealtimeConnectionAccounts } from "@opengeni/core";
+import { resolveSiteSessionOrigin, withOptionalSiteCommandOrigin } from "../site-session-origin";
+import { SandboxRecoveryRequest } from "@opengeni/contracts";
+import { getManagedHumanSandboxRecovery, consentManagedHumanSandboxRecovery } from "@opengeni/core";
+import { SandboxRecoveryConflictError } from "@opengeni/db";
+import { codexAccountJson } from "./codex";
+import { getSessionCodexAccounts } from "@opengeni/db";
 import {
   AcknowledgeStreamRequest,
   ApplySessionGoalRevisionRequest,
+  ListSessionGoalRevisionsQuery,
+  RejectSessionGoalRevisionRequest,
+  RollbackSessionGoalRevisionRequest,
   ActivateCodexRealtimeConnectionRequest,
   AttachViewerRequest,
   BeginSessionRealtimeRequest,
@@ -9,6 +28,7 @@ import {
   GatewayRealtimeConnectRequest,
   ClientSessionEvent,
   CompactSessionContextRequest,
+  CreateSessionRequest,
   DeleteSessionQueueItemRequest,
   EditSessionQueueItemRequest,
   EndSessionRealtimeRequest,
@@ -19,6 +39,7 @@ import {
   FsMoveRequest,
   FsReadRequest,
   FsWriteRequest,
+  ForkSessionRequest,
   HumanInputRequestStatus,
   GitDiffRequest,
   GitReadBatchRequest,
@@ -30,38 +51,60 @@ import {
   PtyOpenRequest,
   PtyResizeRequest,
   PtyWriteRequest,
+  PublishSandboxFileArtifactRequest,
   RenewSessionRealtimeRequest,
   SyncSessionRealtimeLedgerRequest,
   SessionControlRequest,
+  SessionRetryRequest,
   SESSION_EVENT_RAW_DELTA_TYPES,
   SessionEventPayloadMode,
   SessionEventReadDirection,
   SessionEventReadMode,
   SessionEventLatestClass,
   SessionEventResultMode,
+  SessionScopeSubjectId,
   SessionEventSemanticClass,
   SessionEventType,
   SessionMcpServerId,
+  SaveNewSessionDraftRequest,
   compactSessionEventResult,
   sessionEventLatestClassToSemanticClass,
   SaveComposerDraftRequest,
+  SubmitComposerDraftRequest,
   SteerSessionQueueItemRequest,
   SteerSessionMessageRequest,
   TerminalExecRequest,
   UpdateSessionChannelRequest,
+  UpdateSessionAttentionRequest,
+  UpdateSessionArchiveRequest,
   UpdateSessionPinRequest,
   UpdateSessionGoalRequest,
   UpdateSessionMcpApprovalPolicyRequest,
   UpdateSessionRequest,
+  UpdateSessionVariableSetsRequest,
+  UpdateSessionVisibilityRequest,
   UpdateSessionToolPolicyRequest,
+  UpdateSessionAgentRequest,
+  AgentConfigError,
   ViewerHeartbeatRequest,
   WORKSPACE_CONTROL_ACTOR_MAX_BYTES,
+  WORK_CLAIM_CANONICAL_KEY_MAX_BYTES,
+  WORK_CLAIM_DISCOVERY_LIMIT,
+  WORK_CLAIM_NAMESPACE_MAX_BYTES,
+  WORK_DISCOVERY_QUERY_MAX_CHARS,
+  WORK_DISCOVERY_RECENT_HOURS_MAX,
+  WorkClaimSubjectFilter as WorkClaimSubjectFilterSchema,
+  WorkClaimSubjectType,
+  normalizeWorkClaimCanonicalKey,
+  normalizeWorkClaimNamespace,
   workspaceControlUtf8Bytes,
   type AccessGrant,
   type AttachViewerResponse,
   type SandboxBackend,
   type LineageNode,
   type Session,
+  type SessionStatus,
+  type WorkClaimSubjectFilter,
   type SessionGoalRevision,
   type AgentTopologyPageResponse,
   type ErrorCode,
@@ -70,21 +113,27 @@ import {
   type TerminalPtyExitedPayload,
   type TerminalPtyOutputDeltaPayload,
   type TerminalPtyStartedPayload,
+  type VariableSet,
 } from "@opengeni/contracts";
 import { streamTokenDegraded } from "@opengeni/config";
 import {
+  recordAuditEvent,
   acceptSessionApprovalDecision,
   acceptSessionHumanInputResponse,
   clearSessionGoal,
   clearSessionContext,
   getOpenPtySession,
   getEnrollment,
+  getLiveEnrollmentConnection,
   getRetainedProcess,
   getSandbox,
   getSession,
+  readActiveSandbox,
+  deleteSessionTreeIfQuiescent,
   getSessionEvent,
   getSessionForSubject,
   getSessionGoal,
+  getLatestSessionModelContext,
   getSessionHumanInputRequest,
   getSessionGoalWithContinuation,
   getSessionGoalRevision,
@@ -93,28 +142,34 @@ import {
   insertPtySession,
   listSessionEventPage,
   listSessionHumanInputRequests,
+  listSessionGoalRevisionPage,
   listSessionGoalRevisions,
+  rejectSessionGoalRevisionWithEvent,
   listSessionIdsInGroup,
   listSessionDiscoverySummaries,
   listSessionDiscoveryAncestorPaths,
   listSessionsForSubject,
+  listSessionEntriesForSubject,
   getLatestStartedSessionTurn,
   listSessionTurns,
   projectEffectiveControlForRelatedAccess,
   projectSessionForRelatedAccess,
   recordStreamAcknowledgment,
   requestSessionCompaction,
-  setSessionCodexPinInTransaction,
-  withSessionCodexCapacityMutation,
+  switchSessionCodexAccount,
   setSessionChannel,
+  updateSessionVariableSets,
   ChannelNotFoundError,
+  setSessionAttention,
+  setSessionArchive,
   setSessionPin,
+  SessionAttentionVersionConflictError,
+  SessionArchiveVersionConflictError,
   SessionPinVersionConflictError,
   SessionPinAccessError,
   SessionListAccessError,
   SessionListCursorError,
   SessionListCursorExpiredError,
-  SessionListSnapshotLimitError,
   decodeSessionListCursor,
   revokeViewer,
   setSessionGoalStatusWithEvent,
@@ -133,7 +188,15 @@ import {
   SessionRealtimeConflictError,
   SessionToolPolicyVersionConflictError,
   SessionContextBusyError,
+  SessionVariableSetSelectionUnavailableError,
+  SessionCreateConnectionSelectionUnavailableError,
+  workspaceControlRequestLockTimeoutMs,
+  SessionTenancyAccessError,
+  SessionTenancyConflictError,
+  SessionTenancyInvalidRequestError,
+  SessionTenancyNotActivatedError,
   HumanInputResponseValidationError,
+  SkillHumanResponseError,
   latestWorkspaceCapture,
   sessionLatestWorkspaceCapture,
   renewSessionRealtimeInTransaction,
@@ -147,12 +210,18 @@ import {
   type SandboxRetainedProcess,
   type Database,
   type SessionDiscoveryCursor,
+  type SessionDiscoveryOrderBy,
   type SessionDiscoveryAncestor,
 } from "@opengeni/db";
+import {
+  backgroundCommandActivityForSessions,
+  listSessionBackgroundCommands,
+  requestSessionBackgroundCommandCancellation,
+} from "@opengeni/db/session-background-commands";
 import {
   appendAndPublishEvents,
   boundSessionEventHttpPage,
-  coalesceSessionEventDeltas,
+  coalesceSessionEventDeltasWithCoverage,
   publishDurableSessionEvents,
 } from "@opengeni/events";
 import {
@@ -160,6 +229,10 @@ import {
   GatewayRealtimeBrokerError,
 } from "../gateway-realtime";
 import { createXaiRealtimeConnectionSecret, XaiRealtimeBrokerError } from "../xai-realtime";
+import {
+  prepareExternalLinkTurnAdmission,
+  externalContinuationCommitAuthorizer,
+} from "@opengeni/core";
 import { z, ZodError } from "zod";
 import {
   runConcurrentChannelAReads,
@@ -173,24 +246,35 @@ import {
   NatsControlRpc,
   negotiateCapabilities,
   negotiateSelfhostedCapabilities,
+  resolveConnectedMachineWorkspaceRoot,
+  selectBackend,
   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 {
+  getManagedAuthRequestActorEpoch,
   hasPermission,
   requireAccessGrant,
+  requireAccessGrantAuthorization,
+  requireFreshAccessGrant,
+  rotateSessionMcpCredentialsForRequest,
+  hasVerifiedOwningUserAuthorization,
   requirePermission,
   requireSessionAuthorization,
   requireSessionAuthorizationListScope,
+  resolveWorkspaceCatalogSettings,
   withResolvedSessionAuthorization,
   SESSION_AUTHORIZATION_DEFAULT_REAUTHORIZE_MS,
   SessionAuthorizationDeniedError,
   SessionAuthorizationUnavailableError,
+  SessionTenancyManagedHumanRequiredError,
+  SessionTenancyPersistenceOutcomeUnknownError,
   type ResolvedSessionAuthorization,
 } from "@opengeni/core";
 import type { ApiRouteDeps } from "@opengeni/core";
+import { SessionRetryConflictError } from "@opengeni/db";
 import {
   attachViewer,
   detachViewer,
@@ -207,12 +291,16 @@ import {
 import { buildSessionCodexRealtimeBroker, CodexRealtimeBrokerError } from "../codex-realtime";
 import {
   acceptSessionUserMessage,
+  validateSessionMcpCredentialUpdates,
   controlHumanSessionWorkstream,
+  retryFailedSession,
   createSessionForRequest,
   deleteHumanQueuePrompt,
   editHumanQueuePrompt,
   getActorNewSessionDraft,
+  getManagedHumanSessionCreateCapabilities,
   getHumanComposerDraft,
+  forkManagedHumanSession,
   moveHumanQueuePrompt,
   readSessionLineage,
   saveHumanComposerDraft,
@@ -220,27 +308,51 @@ import {
   SessionSpawnDeniedError,
   sessionSpawnDenialEnvelope,
   steerHumanQueuePrompt,
+  submitComposerDraftForRequest,
   updateSessionMcpApprovalPolicy,
+  updateManagedHumanSessionVisibility,
   updateSessionToolPolicy,
+  updateSessionAgent,
   updateSessionTitle,
   workflowIdForSession,
   sessionWithEffectiveToolPolicy,
-  workspaceSessionToolPolicyDefaultServerIds,
-  workspaceSessionToolPolicyServerIds,
+  workspaceSessionEffectiveToolsContext,
+  workspaceSessionToolPolicyContext,
   relayConfigFromSettings,
+  validateVariableSetAttachment,
 } from "@opengeni/core";
 import { assertSessionExists, boundedLimit } from "../http/common";
-import { sseSessionStream } from "../http/sse";
+import { browserSseDeliveryOptions, sseSessionStream } from "../http/sse";
 import {
   serveWorkspaceCapture,
   serveWorkspaceCaptureFile,
   WorkspaceCaptureManifestCache,
 } from "./workspace-capture";
+import { publishSandboxFileArtifact } from "../sandbox-file-artifacts";
+import { ApiHttpError } from "../http/api-error";
+import { observeWorkDiscovery, summarizeWorkDiscoveryRows } from "../work-discovery-observability";
+import { recordAcceptedApiAdmission } from "../admission-trace";
+import { parseRequestBody, parseRequestJson } from "../http/request-body";
+import { measureSessionCreatePhase } from "../session-create-observability";
 
 type SessionRouteDeps = ApiRouteDeps & Pick<ViewerServices, "establishSandboxSession">;
 
 const VIEWER_LIFECYCLE_PERMISSIONS = ["stream:view", "terminal:attach", "files:write"] as const;
 
+/**
+ * Bounded responder kind recorded on a child's requires-action resolution
+ * notice for its parent: a key principal is `api`, a signed agent attempt is
+ * `agent_attempt`, and every other HTTP caller is a human. Never a subject id.
+ */
+function childRequiresActionRespondedByKindForGrant(
+  grant: Pick<AccessGrant, "principalKind">,
+): "human" | "api" | "agent_attempt" | "system" {
+  if (grant.principalKind === "api_key" || grant.principalKind === "configured_key") return "api";
+  if (grant.principalKind === "agent_attempt") return "agent_attempt";
+  if (grant.principalKind === "service") return "system";
+  return "human";
+}
+
 function requireViewerLifecyclePermission(grant: AccessGrant): void {
   if (
     VIEWER_LIFECYCLE_PERMISSIONS.some((permission) => hasPermission(grant.permissions, permission))
@@ -258,9 +370,18 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     db,
     settings,
     bus,
+    objectStorage,
     observability: deps.observability,
   };
   const workspaceCaptureManifestCache = new WorkspaceCaptureManifestCache();
+  const withSiteCommandOrigin = <T>(c: Context, workspaceId: string, run: () => Promise<T>) =>
+    withOptionalSiteCommandOrigin(
+      db,
+      workspaceId,
+      c.req.header("x-opengeni-site-id"),
+      c.req.header("x-opengeni-site-version"),
+      run,
+    );
   const ptyIdentity = (pty: SandboxOpenPtySessionRow): SandboxPtyProcessIdentity => ({
     leaseId: pty.leaseId,
     sandboxGroupId: pty.sandboxGroupId,
@@ -317,8 +438,18 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         message: "pty retained-process identity is stale; reopen the terminal",
       });
     }
+    const providerCommand = await getRetainedProviderCommand(db, {
+      accountId: ctx.accountId,
+      workspaceId: ctx.workspaceId,
+      sessionId: ctx.session.id,
+      processId: process.id,
+    });
     handle.routingSession.adoptRetainedProcess({
-      process: { id: process.id, providerSessionId: process.providerSessionId },
+      process: {
+        id: process.id,
+        providerSessionId: process.providerSessionId,
+        ...(providerCommand ? { providerCommand } : {}),
+      },
       backend: {
         sandboxId: null,
         leaseEpoch: process.leaseEpoch,
@@ -406,6 +537,16 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     if (!operation) {
       throw sessionAuthorizationHttpError(new SessionAuthorizationUnavailableError());
     }
+    if (operation === "session.visibility.write" || operation === "session.fork.create") {
+      // These product mutations perform their target-free managed-cookie,
+      // permission, and activation gates inside core before resolving the
+      // target exactly once. Visibility changes remain owner-only; a shared
+      // source may be forked by any currently authorized workspace member.
+      // Running the generic middleware here would both create a pre-gate
+      // existence oracle and double-call the host.
+      await next();
+      return;
+    }
     const grant = await requireAccessGrant(c, deps, workspaceId);
     try {
       const authorization = await requireSessionAuthorization(deps, grant, {
@@ -429,17 +570,34 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     db,
     settings,
     bus,
+    objectStorage,
     ...(deps.establishSandboxSession
       ? { establishSandboxSession: deps.establishSandboxSession }
       : {}),
   };
 
+  app.get("/v1/workspaces/:workspaceId/session-tenancy/capabilities", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "sessions:create",
+    );
+    return c.json(await getManagedHumanSessionCreateCapabilities(deps, authorization, workspaceId));
+  });
+
   app.post("/v1/workspaces/:workspaceId/sessions", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:create");
+    const authorization = await measureSessionCreatePhase(deps.observability, "authorization", () =>
+      requireAccessGrantAuthorization(c, deps, workspaceId, "sessions:create"),
+    );
+    const grant = authorization.grant;
     let payload: unknown;
     try {
-      payload = await c.req.json();
+      payload = await measureSessionCreatePhase(deps.observability, "body_read", () =>
+        c.req.json(),
+      );
     } catch {
       return c.json(
         {
@@ -451,25 +609,66 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     }
     let session: Session;
     try {
-      session = await createSessionForRequest(deps, grant, workspaceId, payload);
+      CreateSessionRequest.parse(payload);
+      const origin = await measureSessionCreatePhase(deps.observability, "site_origin", () =>
+        resolveSiteSessionOrigin(
+          db,
+          workspaceId,
+          c.req.header("x-opengeni-site-id"),
+          c.req.header("x-opengeni-site-version"),
+        ),
+      );
+      const create = () =>
+        createSessionForRequest(deps, grant, workspaceId, payload, authorization);
+      session = await measureSessionCreatePhase(deps.observability, "core_create", () =>
+        origin ? withSiteSessionOrigin(origin, create) : create(),
+      );
     } catch (error) {
       return sessionCreateErrorResponse(c, error);
     }
     // 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, grant.subjectId, session), 202);
+    return c.json(
+      await measureSessionCreatePhase(deps.observability, "response_projection", () =>
+        withEffectivePolicy(deps, workspaceId, grant.subjectId, session),
+      ),
+      202,
+    );
   });
 
   app.get("/v1/workspaces/:workspaceId/new-session-draft", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:read");
-    return c.json(await getActorNewSessionDraft({ settings, db }, grant, workspaceId));
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "sessions:read",
+    );
+    const grant = authorization.grant;
+    const catalog = await resolveWorkspaceCatalogSettings(db, settings, {
+      accountId: grant.accountId,
+      workspaceId,
+    });
+    return c.json(
+      await getActorNewSessionDraft(
+        { settings: catalog.settings, db },
+        grant,
+        workspaceId,
+        authorization,
+      ),
+    );
   });
 
   app.put("/v1/workspaces/:workspaceId/new-session-draft", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:create");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "sessions:create",
+    );
+    const grant = authorization.grant;
     let payload: unknown;
     try {
       payload = await c.req.json();
@@ -483,12 +682,19 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
       );
     }
     try {
+      SaveNewSessionDraftRequest.parse(payload);
+      const catalog = await resolveWorkspaceCatalogSettings(db, settings, {
+        accountId: grant.accountId,
+        workspaceId,
+      });
       return c.json(
         await saveActorNewSessionDraft(
-          { settings, db, objectStorage },
+          { settings: catalog.settings, db, objectStorage },
           grant,
           workspaceId,
           payload,
+          authorization.canonicalManagedHumanSession,
+          authorization,
         ),
       );
     } catch (error) {
@@ -515,9 +721,68 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     }
   });
 
+  app.get("/v1/workspaces/:workspaceId/session-message-search", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "sessions:read",
+    );
+    const grant = authorization.grant;
+    // A single-session filter is not authority: both searches use the complete
+    // live host/agent list scope, plus ordinary private/archive/RLS boundaries.
+    let authorizationScope;
+    try {
+      authorizationScope = await requireSessionAuthorizationListScope(deps, grant, "http");
+    } catch (error) {
+      throw sessionAuthorizationHttpError(error);
+    }
+    const raw = c.req.query();
+    const parsed = SessionMessageSearchRequest.safeParse({
+      ...raw,
+      ...(raw.limit !== undefined ? { limit: Number(raw.limit) } : {}),
+    });
+    if (!parsed.success)
+      throw new HTTPException(400, { message: "Invalid session message search request" });
+    try {
+      return c.json(
+        await searchSessionMessagesForSubject(
+          db,
+          workspaceId,
+          parsed.data,
+          {
+            subjectId: grant.subjectId,
+            ...(authorizationScope ? { authorizationScope } : {}),
+            personalWorkspaceOwnerException: hasVerifiedOwningUserAuthorization(authorization),
+          },
+          { signal: c.req.raw.signal },
+        ),
+      );
+    } catch (error) {
+      if (error instanceof SessionListAccessError)
+        throw new HTTPException(403, { message: error.message });
+      if (error instanceof SessionMessageSearchCursorError)
+        throw new HTTPException(400, { message: error.message });
+      // Clients are told to cancel superseded searches, so an abort here is a
+      // routine client disconnect, never a server failure. Match the existing
+      // client-gone convention (mcp/request-abort.ts): 499 with an empty body,
+      // which a departed client never reads and monitors never count as 5xx.
+      if (c.req.raw.signal.aborted || (error instanceof Error && error.name === "AbortError"))
+        return new Response(null, { status: 499 });
+      throw error;
+    }
+  });
+
   app.get("/v1/workspaces/:workspaceId/sessions", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:read");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "sessions:read",
+    );
+    const grant = authorization.grant;
     let authorizationScope;
     try {
       authorizationScope = await requireSessionAuthorizationListScope(deps, grant, "http");
@@ -526,18 +791,50 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     }
     const pageView = c.req.query("view") === "page";
     const query = sessionListQuery(c.req.query(), pageView);
-    let page: Awaited<ReturnType<typeof listSessionsForSubject>>;
+    const projection = c.req.query("projection");
+    if (projection !== undefined && projection !== "summary")
+      throw new HTTPException(400, { message: 'projection must be "summary"' });
+    if (projection && !pageView)
+      throw new HTTPException(400, { message: 'summary projection requires view="page"' });
+    const summary = projection === "summary";
+    let page: Awaited<
+      ReturnType<typeof listSessionsForSubject | typeof listSessionEntriesForSubject>
+    >;
     try {
-      page = await listSessionsForSubject(db, workspaceId, {
-        subjectId: grant.subjectId,
-        limit: boundedLimit(query.limit),
-        materializeSnapshot: pageView,
-        ...(query.cursor ? { cursor: query.cursor } : {}),
-        ...(query.search ? { search: query.search } : {}),
-        ...(query.pinsOnly ? { pinsOnly: true } : {}),
-        ...(query.parentSessionId !== undefined ? { parentSessionId: query.parentSessionId } : {}),
-        ...(authorizationScope ? { authorizationScope } : {}),
-      });
+      page = await (summary ? listSessionEntriesForSubject : listSessionsForSubject)(
+        db,
+        workspaceId,
+        {
+          subjectId: grant.subjectId,
+          limit: boundedLimit(query.limit),
+          materializeSnapshot: pageView,
+          ...(query.cursor ? { cursor: query.cursor } : {}),
+          ...(query.search ? { search: query.search } : {}),
+          ...(query.pinsOnly ? { pinsOnly: true } : {}),
+          ...(query.includeTotals ? { includeTotals: true } : {}),
+          ...(query.needsYouOnly ? { needsYouOnly: true } : {}),
+          ...(query.includePinned === false ? { includePinned: false } : {}),
+          ...(query.archivedOnly ? { archivedOnly: true } : {}),
+          ...(query.sortBy ? { sortBy: query.sortBy } : {}),
+          ...(query.archiveStatus ? { archiveStatus: query.archiveStatus } : {}),
+          ...(query.parentSessionId !== undefined
+            ? { parentSessionId: query.parentSessionId }
+            : {}),
+          ...(query.channelId !== undefined ? { channelId: query.channelId } : {}),
+          ...(query.originSiteId ? { originSiteId: query.originSiteId } : {}),
+          ...(query.createdBy ? { createdBy: query.createdBy } : {}),
+          ...(query.updatedFrom ? { updatedFrom: query.updatedFrom } : {}),
+          ...(query.updatedBefore ? { updatedBefore: query.updatedBefore } : {}),
+          ...(query.createdFrom ? { createdFrom: query.createdFrom } : {}),
+          ...(query.createdBefore ? { createdBefore: query.createdBefore } : {}),
+          ...(query.scopeSubjectId ? { scopeSubjectId: query.scopeSubjectId } : {}),
+          ...(authorizationScope ? { authorizationScope } : {}),
+          // A managed human's own personal workspace has no membership row, so
+          // the list's removal fence must fall back to the organization-membership
+          // pointer, only with verified native or external owning-user provenance.
+          personalWorkspaceOwnerException: hasVerifiedOwningUserAuthorization(authorization),
+        },
+      );
     } catch (error) {
       if (error instanceof SessionListAccessError) {
         throw new HTTPException(403, { message: error.message });
@@ -552,26 +849,65 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
       if (error instanceof SessionListCursorError) {
         throw new HTTPException(400, { message: error.message });
       }
-      if (error instanceof SessionListSnapshotLimitError) {
-        c.header("Retry-After", "5");
-        throw new HTTPException(429, { message: error.message });
-      }
       throw error;
     }
     // The page body carries this fact directly. Preserve the historical array
     // 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, grant.subjectId);
-    const decorate = (session: Session): Session =>
-      sessionWithEffectiveToolPolicy(
-        session,
+    const commandActivity = await backgroundCommandActivityForSessions(db, {
+      accountId: grant.accountId,
+      workspaceId,
+      sessionIds: [...page.pinned, ...page.sessions].map((session) => session.id),
+    });
+    const scheduleTargets =
+      hasPermission(grant.permissions, "scheduled_tasks:run") &&
+      hasPermission(grant.permissions, "sessions:control")
+        ? await scheduledSessionIds(
+            db,
+            workspaceId,
+            [...page.pinned, ...page.sessions].map((session) => session.id),
+          )
+        : new Set<string>();
+    if ("projection" in page) {
+      const decorateEntry = (session: (typeof page.sessions)[number]) => ({
+        ...session,
+        hasSchedules: scheduleTargets.has(session.id),
+        ...(commandActivity.has(session.id)
+          ? { backgroundCommandActivity: commandActivity.get(session.id)! }
+          : {}),
+      });
+      return c.json({
+        ...page,
+        ...(query.hasPageFilters ? { filtersApplied: true as const } : {}),
+        ...(query.originSiteId ? { originSiteId: query.originSiteId } : {}),
+        pinned: page.pinned.map(decorateEntry),
+        sessions: page.sessions.map(decorateEntry),
+      });
+    }
+    const policy = await loadEffectivePolicyContext(deps, workspaceId, grant.subjectId, [
+      ...page.pinned,
+      ...page.sessions,
+    ]);
+    const decorate = (session: Session): Session => {
+      const activity = commandActivity.get(session.id);
+      const decorated = {
+        ...session,
+        hasSchedules: scheduleTargets.has(session.id),
+        ...(activity ? { backgroundCommandActivity: activity } : {}),
+      };
+      return sessionWithEffectiveToolPolicy(
+        decorated,
         policy.workspaceServerIds,
         policy.workspaceDefaultServerIds,
+        policy.effectiveToolsContext,
       );
+    };
     if (pageView) {
       return c.json({
         ...page,
+        ...(query.hasPageFilters ? { filtersApplied: true as const } : {}),
+        ...(query.originSiteId ? { originSiteId: query.originSiteId } : {}),
         pinned: page.pinned.map(decorate),
         sessions: page.sessions.map(decorate),
       });
@@ -594,71 +930,144 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
       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,
+    const startedAtMs = performance.now();
+    const mode = query.subject ? "subject" : query.query ? "query" : "browse";
+    const metricAuthorizationScope = authorizationScope?.kind === "scoped" ? "scoped" : "workspace";
+    if ((query.query || query.subject) && !settings.workDiscoveryEnabled) {
+      observeWorkDiscovery(deps.observability, {
+        surface: "agent_topology",
+        mode,
+        outcome: "disabled",
+        authorizationScope: metricAuthorizationScope,
+        durationMs: performance.now() - startedAtMs,
+        responseBytes: 0,
+        resultCount: 0,
+        overlapCount: 0,
+        matchCounts: {},
+      });
+      throw new HTTPException(503, {
+        message: "Agent work discovery is disabled by the operator.",
+      });
+    }
+    try {
+      const orderBy: SessionDiscoveryOrderBy =
+        query.query || query.subject ? "relevance" : "updatedAt";
+      const page = await listSessionDiscoverySummaries(db, workspaceId, {
+        limit: query.limit,
+        orderBy,
+        subjectId: grant.subjectId,
+        ...(query.cursor ? { cursor: query.cursor } : {}),
+        ...(query.parentSessionId !== undefined ? { parentSessionId: query.parentSessionId } : {}),
+        ...(query.rootSessionId ? { rootSessionId: query.rootSessionId } : {}),
+        ...(query.query ? { query: query.query } : {}),
+        ...(query.statuses ? { statuses: query.statuses } : {}),
+        activeOnly: query.activeOnly,
+        ...(query.recentHours !== undefined ? { recentHours: query.recentHours } : {}),
+        ...(query.subject ? { subject: query.subject } : {}),
+        ...(query.claimLimit !== undefined ? { claimLimit: query.claimLimit } : {}),
+        includeWorkDiscovery: settings.workDiscoveryEnabled,
+        ...(authorizationScope ? { authorizationScope } : {}),
+      });
+      const ancestorPaths =
+        query.query || query.subject
+          ? await listSessionDiscoveryAncestorPaths(
+              db,
+              workspaceId,
+              page.sessions.map((session) => session.id),
+              authorizationScope ?? undefined,
+              grant.subjectId,
+            )
+          : 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:
-            ancestor.titleOriginalChars !== null &&
-            ancestor.titleOriginalChars > Array.from(ancestor.title ?? "").length,
-        })),
-        status: session.status,
-        pause: {
-          state: session.effectiveControl.state,
-          additionalBlockerCount: session.effectiveControl.additionalBlockerCount,
-          source: blocker
+            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,
+          goal: session.goal
             ? {
-                kind: blocker.kind,
-                ...(blocker.sessionId ? { sessionId: blocker.sessionId } : {}),
-                displayName: blocker.displayName,
-                displayNameTruncated:
-                  blocker.displayNameOriginalChars > Array.from(blocker.displayName).length,
+                status: session.goal.status,
+                summary: session.goal.text,
+                summaryTruncated:
+                  session.goal.textOriginalChars > Array.from(session.goal.text).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);
+          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,
+          relatedWork: session.workDiscovery,
+          createdAt: session.createdAt,
+          updatedAt: session.updatedAt,
+        };
+      });
+      const response = {
+        sessions,
+        total: page.total,
+        hasMore: page.hasMore,
+        humanAdvisoriesEnabled:
+          settings.workDiscoveryEnabled && settings.workDiscoveryHumanAdvisoriesEnabled,
+        nextCursor: page.nextCursor
+          ? encodeAgentTopologyCursor({
+              cursor: page.nextCursor,
+              parentSessionId: query.parentSessionId === undefined ? "all" : query.parentSessionId,
+              rootSessionId: query.rootSessionId ?? null,
+              query: query.query ?? null,
+              statuses: query.statuses ?? [],
+              activeOnly: query.activeOnly,
+              recentHours: query.recentHours ?? null,
+              subject: query.subject ?? null,
+              claimLimit: query.claimLimit ?? null,
+            })
+          : null,
+      } satisfies AgentTopologyPageResponse;
+      observeWorkDiscovery(deps.observability, {
+        surface: "agent_topology",
+        mode,
+        outcome: sessions.length === 0 ? "empty" : "ok",
+        authorizationScope: metricAuthorizationScope,
+        durationMs: performance.now() - startedAtMs,
+        responseBytes: Buffer.byteLength(JSON.stringify(response), "utf8"),
+        ...summarizeWorkDiscoveryRows(sessions),
+      });
+      return c.json(response);
+    } catch (error) {
+      observeWorkDiscovery(deps.observability, {
+        surface: "agent_topology",
+        mode,
+        outcome: "error",
+        authorizationScope: metricAuthorizationScope,
+        durationMs: performance.now() - startedAtMs,
+        responseBytes: 0,
+        resultCount: 0,
+        overlapCount: 0,
+        matchCounts: {},
+      });
+      throw error;
+    }
   });
 
   app.get("/v1/workspaces/:workspaceId/sessions/:sessionId", async (c) => {
@@ -678,7 +1087,143 @@ 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, grant.subjectId, session));
+    const activity = await backgroundCommandActivityForSessions(db, {
+      accountId: grant.accountId,
+      workspaceId,
+      sessionIds: [sessionId],
+    });
+    const scheduleTargets =
+      hasPermission(grant.permissions, "scheduled_tasks:run") &&
+      hasPermission(grant.permissions, "sessions:control")
+        ? await scheduledSessionIds(db, workspaceId, [sessionId])
+        : new Set<string>();
+    return c.json(
+      await withEffectivePolicy(deps, workspaceId, grant.subjectId, {
+        ...session,
+        hasSchedules: scheduleTargets.has(sessionId),
+        ...(activity.get(sessionId) ? { backgroundCommandActivity: activity.get(sessionId) } : {}),
+      }),
+    );
+  });
+
+  app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/model-context", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:read");
+    const sessionId = c.req.param("sessionId");
+    if (!z.string().uuid().safeParse(sessionId).success) {
+      throw new HTTPException(404, { message: "session not found" });
+    }
+    const session = await getSessionForSubject(
+      db,
+      workspaceId,
+      sessionId,
+      grant.subjectId,
+      relatedSessionAccessFor(c),
+    );
+    if (!session) {
+      throw new HTTPException(404, { message: "session not found" });
+    }
+    return c.json(
+      await getLatestSessionModelContext(db, {
+        accountId: grant.accountId,
+        workspaceId,
+        sessionId,
+      }),
+    );
+  });
+
+  app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/background-commands", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const sessionId = c.req.param("sessionId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:read");
+    const commands = await listSessionBackgroundCommands(db, {
+      accountId: grant.accountId,
+      workspaceId,
+      sessionId,
+      activeOnly: true,
+    });
+    return c.json({ commands });
+  });
+
+  app.delete(
+    "/v1/workspaces/:workspaceId/sessions/:sessionId/background-commands/:commandId",
+    async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      const sessionId = c.req.param("sessionId");
+      const commandId = c.req.param("commandId");
+      if (!z.string().uuid().safeParse(commandId).success) {
+        throw new HTTPException(404, { message: "background command not found" });
+      }
+      const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:control");
+      const result = await requestSessionBackgroundCommandCancellation(db, {
+        accountId: grant.accountId,
+        workspaceId,
+        sessionId,
+        commandId,
+        subjectId: grant.subjectId,
+      });
+      if (!result.command) {
+        throw new HTTPException(404, { message: "background command not found" });
+      }
+      return c.json(result);
+    },
+  );
+
+  app.put("/v1/workspaces/:workspaceId/sessions/:sessionId/visibility", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const sessionId = c.req.param("sessionId");
+    const authorization = await requireAccessGrantAuthorization(c, deps, workspaceId);
+    const parsed = UpdateSessionVisibilityRequest.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) {
+      throw new ApiHttpError(422, {
+        code: "validation_failed",
+        message: "Invalid session visibility request.",
+        retryable: false,
+        details: { fields: zodErrorFields(parsed.error) },
+      });
+    }
+    try {
+      return c.json(
+        await updateManagedHumanSessionVisibility(
+          deps,
+          authorization,
+          workspaceId,
+          sessionId,
+          parsed.data,
+          "http",
+        ),
+      );
+    } catch (error) {
+      throw sessionTenancyHttpError(error);
+    }
+  });
+
+  app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/forks", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const sessionId = c.req.param("sessionId");
+    const authorization = await requireAccessGrantAuthorization(c, deps, workspaceId);
+    const parsed = ForkSessionRequest.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) {
+      throw new ApiHttpError(422, {
+        code: "validation_failed",
+        message: "Invalid session fork request.",
+        retryable: false,
+        details: { fields: zodErrorFields(parsed.error) },
+      });
+    }
+    try {
+      const response = await forkManagedHumanSession(
+        deps,
+        authorization,
+        workspaceId,
+        sessionId,
+        parsed.data,
+        "http",
+      );
+      return c.json(response, response.replay ? 200 : 201);
+    } catch (error) {
+      throw sessionTenancyHttpError(error);
+    }
   });
 
   const publishRealtimeMutation = async (
@@ -719,15 +1264,23 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
       });
     }
     try {
-      const result = await withWorkspaceSessionActivityRls(db, workspaceId, async (scopedDb) =>
-        beginSessionRealtimeInTransaction(scopedDb, {
+      const result = await withWorkspaceSessionActivityRls(db, workspaceId, async (scopedDb) => {
+        const accounts = await freezeSessionRealtimeConnectionAccounts({
+          db: scopedDb as unknown as Database,
+          settings,
+          grant,
+          workspaceId,
+          sessionId,
+        });
+        return beginSessionRealtimeInTransaction(scopedDb, {
           accountId: grant.accountId,
           workspaceId,
           sessionId,
           ownerSubjectId: grant.subjectId,
           ...parsed.data,
-        }),
-      );
+          ...accounts,
+        });
+      });
       await publishRealtimeMutation(grant.accountId, workspaceId, sessionId, result);
       c.header("cache-control", "private, no-store");
       return c.json({ mode: result.mode, replay: result.replay }, result.replay ? 200 : 201);
@@ -1276,7 +1829,15 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
       const workspaceId = c.req.param("workspaceId");
       const sessionId = c.req.param("sessionId");
       const realtimeId = c.req.param("realtimeId");
-      const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:control");
+      const authorization = await requireAccessGrantAuthorization(
+        c,
+        deps,
+        workspaceId,
+        "sessions:control",
+      );
+      const grant = authorization.grant;
+      const beforeCommit = externalContinuationCommitAuthorizer(authorization);
+      const captureLinked = prepareExternalLinkTurnAdmission(authorization);
       if (
         !z.string().uuid().safeParse(sessionId).success ||
         !z.string().uuid().safeParse(realtimeId).success
@@ -1292,15 +1853,29 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         });
       }
       try {
-        const result = await withWorkspaceSessionActivityRls(db, workspaceId, async (scopedDb) =>
-          syncSessionRealtimeLedgerInTransaction(scopedDb, {
-            workspaceId,
-            sessionId,
-            realtimeId,
-            ownerSubjectId: grant.subjectId,
-            ...parsed.data,
-          }),
-        );
+        const result = await withWorkspaceSessionActivityRls(db, workspaceId, async (scopedDb) => {
+          // Acquire origin authority before inference/session locks. A deferred
+          // realtime session has no initial worker turn; capture its exact
+          // linked actor when the ledger actually admits ordinary agent work.
+          await beforeCommit?.(scopedDb as unknown as Database);
+          return syncSessionRealtimeLedgerInTransaction(
+            scopedDb,
+            {
+              workspaceId,
+              sessionId,
+              realtimeId,
+              ownerSubjectId: grant.subjectId,
+              ...parsed.data,
+              controlLockTimeoutMs: workspaceControlRequestLockTimeoutMs(),
+            },
+            captureLinked
+              ? {
+                  afterDelegationAdmission: async ({ turnId }) =>
+                    captureLinked(scopedDb as unknown as Database, sessionId, turnId),
+                }
+              : {},
+          );
+        });
         await publishRealtimeMutation(grant.accountId, workspaceId, sessionId, result);
         c.header("cache-control", "private, no-store");
         return c.json({ accepted: result.accepted, outbound: result.outbound });
@@ -1315,7 +1890,13 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
   // (not session control) and returns 404 for a foreign/inaccessible session.
   app.put("/v1/workspaces/:workspaceId/sessions/:sessionId/pin", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:read");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "sessions:read",
+    );
+    const grant = authorization.grant;
     const sessionId = c.req.param("sessionId");
     if (!z.string().uuid().safeParse(sessionId).success) {
       throw new HTTPException(404, { message: "session not found" });
@@ -1329,6 +1910,8 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         workspaceId,
         subjectId: grant.subjectId,
         sessionId,
+        // Same owner-only personal-workspace fallback as the list above.
+        personalWorkspaceOwnerException: hasVerifiedOwningUserAuthorization(authorization),
         ...parsed.data,
       });
       if (!session) {
@@ -1359,28 +1942,186 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     }
   });
 
-  app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/lineage", async (c) => {
+  // Personal follow-up state. Session reads stay side-effect free; clients use
+  // this explicit mutation after a deliberate read/unread action. The managed
+  // web console treats an exact foreground chat event frontier as that action,
+  // while the actively-working label remains independent of acknowledgment.
+  app.put("/v1/workspaces/:workspaceId/sessions/:sessionId/attention", async (c) => {
     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, grant.subjectId);
-    return c.json({
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "sessions:read",
+    );
+    const grant = authorization.grant;
+    const sessionId = c.req.param("sessionId");
+    if (!z.string().uuid().safeParse(sessionId).success) {
+      throw new HTTPException(404, { message: "session not found" });
+    }
+    const parsed = UpdateSessionAttentionRequest.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) {
+      throw new HTTPException(400, { message: "invalid session attention request" });
+    }
+    try {
+      const session = await setSessionAttention(db, {
+        workspaceId,
+        subjectId: grant.subjectId,
+        sessionId,
+        personalWorkspaceOwnerException: hasVerifiedOwningUserAuthorization(authorization),
+        ...parsed.data,
+      });
+      if (!session) throw new HTTPException(404, { message: "session not found" });
+      return c.json(
+        await withEffectivePolicy(
+          deps,
+          workspaceId,
+          grant.subjectId,
+          projectSessionForRelatedAccess(session, relatedSessionAccessFor(c)),
+        ),
+      );
+    } catch (error) {
+      if (error instanceof SessionPinAccessError) {
+        throw new HTTPException(403, { message: error.message });
+      }
+      if (error instanceof SessionAttentionVersionConflictError) {
+        return c.json(
+          {
+            message: "session attention changed in another client",
+            current: error.current,
+          },
+          409,
+        );
+      }
+      throw error;
+    }
+  });
+
+  // Personal chat organization: archived roots leave the ordinary rail only
+  // for this member and remain recoverable through the archived list view.
+  app.put("/v1/workspaces/:workspaceId/sessions/:sessionId/archive", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "sessions:read",
+    );
+    const grant = authorization.grant;
+    const sessionId = c.req.param("sessionId");
+    const parsed = UpdateSessionArchiveRequest.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) {
+      throw new HTTPException(400, { message: "invalid session archive request" });
+    }
+    try {
+      const session = await setSessionArchive(db, {
+        workspaceId,
+        subjectId: grant.subjectId,
+        sessionId,
+        personalWorkspaceOwnerException: hasVerifiedOwningUserAuthorization(authorization),
+        ...parsed.data,
+      });
+      if (!session) throw new HTTPException(404, { message: "session not found" });
+      return c.json(
+        await withEffectivePolicy(
+          deps,
+          workspaceId,
+          grant.subjectId,
+          projectSessionForRelatedAccess(session, relatedSessionAccessFor(c)),
+        ),
+      );
+    } catch (error) {
+      if (error instanceof SessionPinAccessError) {
+        throw new HTTPException(403, { message: error.message });
+      }
+      if (error instanceof SessionArchiveVersionConflictError) {
+        return c.json(
+          { message: "session archive changed in another client", current: error.current },
+          409,
+        );
+      }
+      throw error;
+    }
+  });
+
+  app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/lineage", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:read");
+    const lineage = await readSessionLineage(deps, grant, c.req.param("sessionId"));
+    const sessionIds = [
+      c.req.param("sessionId"),
+      ...lineage.ancestors.map((session) => session.id),
+    ];
+    const lineageSessions = [...lineage.ancestors];
+    const collect = (nodes: LineageNode[]) => {
+      for (const node of nodes) {
+        sessionIds.push(node.session.id);
+        lineageSessions.push(node.session as Session);
+        collect(node.children);
+      }
+    };
+    collect(lineage.children);
+    const targets =
+      hasPermission(grant.permissions, "scheduled_tasks:run") &&
+      hasPermission(grant.permissions, "sessions:control")
+        ? await scheduledSessionIds(db, workspaceId, sessionIds)
+        : new Set<string>();
+    const decorateNodes = (nodes: LineageNode[]): LineageNode[] =>
+      nodes.map((node) => ({
+        ...node,
+        session: { ...node.session, hasSchedules: targets.has(node.session.id) },
+        children: decorateNodes(node.children),
+      }));
+    const policy = await loadEffectivePolicyContext(
+      deps,
+      workspaceId,
+      grant.subjectId,
+      lineageSessions,
+    );
+    return c.json({
       ...lineage,
+      sessionHasSchedules: targets.has(c.req.param("sessionId")),
       ancestors: lineage.ancestors.map((session) =>
         sessionWithEffectiveToolPolicy(
-          session,
+          { ...session, hasSchedules: targets.has(session.id) },
           policy.workspaceServerIds,
           policy.workspaceDefaultServerIds,
+          policy.effectiveToolsContext,
         ),
       ),
-      children: mapLineageNodes(lineage.children, policy),
+      children: decorateNodes(mapLineageNodes(lineage.children, policy)),
+    });
+  });
+
+  app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/codex-accounts", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "sessions:read");
+    await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+    // authorizeSessionHttp has already enforced private-session and agent scope.
+    const projection = await getSessionCodexAccounts(db, workspaceId, c.req.param("sessionId"));
+    if (!projection) throw new HTTPException(404, { message: "session not found" });
+    const activeAccountId = projection.rotation?.activeCredentialId ?? null;
+    return c.json({
+      accounts: projection.accounts.map((account) => codexAccountJson(account)),
+      activeAccountId,
+      settings: {
+        rotationEnabled: projection.rotation?.rotationEnabled ?? false,
+        rotationStrategy: "sharded",
+        activeCredentialId: activeAccountId,
+      },
+      currentSelection: projection.currentSelection,
+      currentAccount: projection.currentAccount
+        ? codexAccountJson(projection.currentAccount)
+        : null,
+      pinnedAccountId: projection.pinnedAccountId,
+      lastAccountId: projection.lastAccountId,
     });
   });
 
   // Pin (or unpin) the session's Codex account. body { target: "auto" | "<id>" }:
   // "auto" clears the pin (the session follows the workspace active pointer); a
-  // uuid pins the session to that specific account. The pin applies to the NEXT
-  // turn (the worker reads it at turn start). 404 when the session or the target
+  // uuid pins the session to that specific account. Overrides a capacity-blocked
+  // turn; a running attempt keeps its account. 404 when the session or the target
   // account id isn't in the workspace.
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/codex-account", async (c) => {
     const workspaceId = c.req.param("workspaceId");
@@ -1405,15 +2146,13 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
       }
     }
     const pinned = target === "auto" ? null : target;
-    const mutation = await withSessionCodexCapacityMutation(
-      db,
-      { workspaceId, reason: "codex_manual_session_pin_changed" },
-      async (tx) => {
-        const changed = await setSessionCodexPinInTransaction(tx, workspaceId, sessionId, pinned);
-        return { result: changed, changed };
-      },
-    );
-    const ok = mutation.result;
+    const mutation = await switchSessionCodexAccount(db, {
+      workspaceId,
+      sessionId,
+      credentialId: pinned,
+      subjectId: grant.subjectId,
+    });
+    const ok = mutation.result.changed;
     if (!ok) {
       throw new HTTPException(404, {
         message: "session or codex account not found",
@@ -1439,7 +2178,11 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
             }),
       ),
     );
-    return c.json({ pinned: target === "auto" ? "auto" : target });
+    await publishDurableSessionEvents(bus, workspaceId, sessionId, mutation.result.events);
+    return c.json({
+      pinned: target === "auto" ? "auto" : target,
+      appliedTo: mutation.result.appliedTo,
+    });
   });
 
   // Re-file the session into a workspace channel (rail organization only;
@@ -1450,7 +2193,12 @@ 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 payload = UpdateSessionChannelRequest.parse(await c.req.json());
+    await requireSessionAuthorization(deps, grant, {
+      sessionId,
+      operation: "session.control",
+      surface: "http",
+    });
+    const payload = await parseRequestJson(c, UpdateSessionChannelRequest);
     try {
       const updated = await setSessionChannel(db, {
         workspaceId,
@@ -1479,6 +2227,91 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     return c.json(await withEffectivePolicy(deps, workspaceId, grant.subjectId, session));
   });
 
+  // Replace the complete ordered Variable Set selection. The DB mutation
+  // serializes with turn claim, rejects live/shared sandbox use, and requests a
+  // cold rotation before the new environment can be materialized.
+  app.put("/v1/workspaces/:workspaceId/sessions/:sessionId/variable-sets", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const sessionId = c.req.param("sessionId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:control");
+    try {
+      await requireSessionAuthorization(deps, grant, {
+        sessionId,
+        operation: "session.variable_sets.write",
+        surface: "http",
+      });
+    } catch (error) {
+      throw sessionAuthorizationHttpError(error);
+    }
+    // Detach still requires attach authority: it changes which protected
+    // resources the session may materialize. Non-empty selections additionally
+    // require use authority through validateVariableSetAttachment.
+    requirePermission(grant, "variable-sets:attach");
+    const parsed = UpdateSessionVariableSetsRequest.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) {
+      throw new ApiHttpError(422, {
+        code: "validation_failed",
+        message: "Invalid session Variable Set request.",
+        retryable: false,
+        details: { fields: zodErrorFields(parsed.error) },
+      });
+    }
+    const variableSets: VariableSet[] = [];
+    for (const variableSetId of parsed.data.variableSetIds) {
+      variableSets.push(
+        await validateVariableSetAttachment({ settings, db }, grant, workspaceId, variableSetId),
+      );
+    }
+    const result = await updateSessionVariableSets(db, {
+      accountId: grant.accountId,
+      workspaceId,
+      sessionId,
+      subjectId: grant.subjectId,
+      variableSets: variableSets.map((variableSet) => ({
+        id: variableSet.id,
+        name: variableSet.name,
+        scope: variableSet.scope,
+      })),
+    });
+    if (result.status === "not_found") {
+      throw new HTTPException(404, { message: "session not found" });
+    }
+    if (result.status === "invalid_variable_sets") {
+      throw new ApiHttpError(422, {
+        code: "validation_failed",
+        message: "One or more selected Variable Sets are no longer available.",
+        retryable: false,
+        outcomeUnknown: false,
+        details: { variableSetIds: result.variableSetIds },
+      });
+    }
+    if (result.status === "blocked") {
+      const messages = {
+        turn_in_flight:
+          "Variable Sets can be changed only when the session has no accepted, queued, claimed, or pending work.",
+        shared_sandbox_group:
+          "Variable Sets cannot be changed while this session shares a sandbox; fork it into a separate session first.",
+        live_sandbox_holders:
+          "Close active terminal, desktop, and sandbox operations before changing Variable Sets.",
+      } as const;
+      throw new HTTPException(409, { message: messages[result.reason] });
+    }
+    if (result.status === "updated") {
+      await publishDurableSessionEvents(bus, workspaceId, sessionId, [result.event]);
+    }
+    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.
@@ -1487,7 +2320,7 @@ 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 payload = UpdateSessionRequest.parse(await c.req.json());
+    const payload = await parseRequestJson(c, UpdateSessionRequest);
     const titleUpdate = await updateSessionTitle(deps, grant, sessionId, payload.title, "user");
     // A session-returning member route must preserve the caller's private pin
     // projection. Returning the generic mapSession() default here would reset a
@@ -1505,6 +2338,49 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     return c.json(await withEffectivePolicy(deps, workspaceId, grant.subjectId, session));
   });
 
+  app.delete("/v1/workspaces/:workspaceId/sessions/:sessionId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:control");
+    const deleted = await deleteSessionTreeIfQuiescent(db, {
+      workspaceId,
+      subjectId: grant.subjectId,
+      sessionId: c.req.param("sessionId"),
+      controlLockTimeoutMs: workspaceControlRequestLockTimeoutMs(),
+    });
+    switch (deleted.status) {
+      case "deleted":
+        return c.json({ deletedSessionCount: deleted.deletedSessionCount });
+      case "not_found":
+        throw new HTTPException(404, { message: "session not found" });
+      case "not_root":
+        throw new HTTPException(409, {
+          message: "delete the root session to remove the complete workstream",
+        });
+      case "active_sessions":
+        throw new HTTPException(409, {
+          message: "cancel the workstream and wait for active turns to finish before deleting it",
+        });
+      case "active_video_generations":
+        throw new HTTPException(409, {
+          message: "wait for active video generations to finish before deleting this workstream",
+        });
+      case "active_background_commands":
+        throw new HTTPException(409, {
+          message: "pause or cancel this workstream's background commands before deleting it",
+        });
+      case "live_sandboxes":
+        throw new HTTPException(409, {
+          message:
+            "wait for the workstream's sandbox activity to finish draining before deleting it",
+        });
+      case "externally_referenced":
+        throw new HTTPException(409, {
+          message:
+            "this workstream has durable workspace outputs or independent forks; archive it instead",
+        });
+    }
+  });
+
   app.patch(
     "/v1/workspaces/:workspaceId/sessions/:sessionId/mcp-servers/:serverId/approval-policy",
     async (c) => {
@@ -1537,7 +2413,10 @@ 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 payload = UpdateSessionToolPolicyRequest.parse(await c.req.json().catch(() => null));
+    const payload = parseRequestBody(
+      UpdateSessionToolPolicyRequest,
+      await c.req.json().catch(() => null),
+    );
     try {
       const session = await updateSessionToolPolicy(deps, grant, sessionId, payload);
       return c.json(await withEffectivePolicy(deps, workspaceId, grant.subjectId, session));
@@ -1556,6 +2435,35 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     }
   });
 
+  // Replace the session's agent configuration (capabilities, identity,
+  // instructions alias, renderer). Shares the tool-policy version CAS and
+  // applies from the next attempt.
+  app.put("/v1/workspaces/:workspaceId/sessions/:sessionId/agent", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:control");
+    const sessionId = c.req.param("sessionId");
+    const payload = parseRequestBody(
+      UpdateSessionAgentRequest,
+      await c.req.json().catch(() => null),
+    );
+    try {
+      const session = await updateSessionAgent(deps, grant, sessionId, payload);
+      return c.json(await withEffectivePolicy(deps, workspaceId, grant.subjectId, session));
+    } catch (error) {
+      if (error instanceof SessionToolPolicyVersionConflictError) {
+        return c.json(
+          {
+            code: error.code,
+            message: error.message,
+            currentVersion: error.currentVersion,
+          },
+          409,
+        );
+      }
+      throw error;
+    }
+  });
+
   app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/goal", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     await requireAccessGrant(c, deps, workspaceId, "sessions:read");
@@ -1576,6 +2484,34 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     return c.json(await listSessionGoalRevisions(db, workspaceId, sessionId));
   });
 
+  app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/goal/revisions/page", 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);
+    const parsedQuery = ListSessionGoalRevisionsQuery.safeParse({
+      limit: c.req.query("limit"),
+      before: c.req.query("before"),
+    });
+    if (!parsedQuery.success) {
+      throw new HTTPException(400, { message: "invalid goal revision page query" });
+    }
+    const query = parsedQuery.data;
+    try {
+      return c.json(
+        await listSessionGoalRevisionPage(db, workspaceId, sessionId, {
+          limit: query.limit,
+          ...(query.before ? { before: query.before } : {}),
+        }),
+      );
+    } catch (error) {
+      if (error instanceof SessionControlConflictError) {
+        throw new HTTPException(409, { message: error.message, cause: error });
+      }
+      throw error;
+    }
+  });
+
   app.post(
     "/v1/workspaces/:workspaceId/sessions/:sessionId/goal/revisions/:revisionId/apply",
     async (c) => {
@@ -1583,7 +2519,7 @@ 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 payload = ApplySessionGoalRevisionRequest.parse(await c.req.json());
+      const payload = await parseRequestJson(c, ApplySessionGoalRevisionRequest);
       const revision = await getSessionGoalRevision(
         db,
         workspaceId,
@@ -1607,6 +2543,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
           sessionId,
           text: revision.text,
           successCriteria: revision.successCriteria,
+          rootConstraints: revision.rootConstraints,
           mutationPolicy: revision.mutationPolicy,
           expectedObjectiveRevision: payload.expectedObjectiveRevision,
           expectedGoalId: revision.goalId,
@@ -1639,12 +2576,94 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     },
   );
 
+  app.post(
+    "/v1/workspaces/:workspaceId/sessions/:sessionId/goal/revisions/:revisionId/reject",
+    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 = await parseRequestJson(c, RejectSessionGoalRevisionRequest);
+      try {
+        const result = await rejectSessionGoalRevisionWithEvent(db, {
+          accountId: grant.accountId,
+          workspaceId,
+          sessionId,
+          revisionId: c.req.param("revisionId"),
+          expectedObjectiveRevision: payload.expectedObjectiveRevision,
+          rationale: payload.rationale,
+        });
+        await publishDurableSessionEvents(bus, workspaceId, sessionId, result.events);
+        return c.json({ revision: result.revision, replay: result.replay });
+      } catch (error) {
+        if (error instanceof SessionControlConflictError) {
+          throw new HTTPException(409, { message: error.message, cause: error });
+        }
+        throw error;
+      }
+    },
+  );
+
+  app.post(
+    "/v1/workspaces/:workspaceId/sessions/:sessionId/goal/revisions/:revisionId/rollback",
+    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 = await parseRequestJson(c, RollbackSessionGoalRevisionRequest);
+      const revision = await getSessionGoalRevision(
+        db,
+        workspaceId,
+        sessionId,
+        c.req.param("revisionId"),
+      );
+      if (!revision || revision.disposition !== "applied") {
+        throw new HTTPException(404, { message: "applied goal revision not found" });
+      }
+      try {
+        const { goal, workflowWakeRevision, events } = await upsertSessionGoalWithEvent(db, {
+          accountId: grant.accountId,
+          workspaceId,
+          sessionId,
+          text: revision.text,
+          successCriteria: revision.successCriteria,
+          rootConstraints: revision.rootConstraints,
+          mutationPolicy: revision.mutationPolicy,
+          expectedObjectiveRevision: payload.expectedObjectiveRevision,
+          expectedGoalId: revision.goalId,
+          changeKind: "replacement",
+          changeRationale: payload.rationale,
+          rollbackOfRevisionId: 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");
     const sessionId = c.req.param("sessionId");
     await assertSessionExists(db, workspaceId, sessionId);
-    const payload = UpdateSessionGoalRequest.parse(await c.req.json());
+    const payload = await parseRequestJson(c, UpdateSessionGoalRequest);
     const existing = await getSessionGoal(db, workspaceId, sessionId);
     if (!existing) {
       throw new HTTPException(404, { message: "session goal not found" });
@@ -1660,6 +2679,10 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
             payload.successCriteria !== undefined
               ? payload.successCriteria
               : existing.successCriteria,
+          rootConstraints:
+            payload.rootConstraints !== undefined
+              ? payload.rootConstraints
+              : existing.rootConstraints,
           maxAutoContinuations: existing.maxAutoContinuations,
           mutationPolicy: payload.mutationPolicy ?? existing.mutationPolicy,
           expectedObjectiveRevision: payload.expectedObjectiveRevision,
@@ -1752,10 +2775,17 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
 
   app.delete("/v1/workspaces/:workspaceId/sessions/:sessionId/goal", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "sessions:control");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:control");
     const sessionId = c.req.param("sessionId");
     await assertSessionExists(db, workspaceId, sessionId);
-    const { event } = await clearSessionGoal(db, workspaceId, sessionId);
+    const { event } = await clearSessionGoal(db, workspaceId, sessionId, {
+      actor: grant.principalKind === "agent_attempt" ? "agent" : "api",
+    }).catch((error: unknown) => {
+      if (error instanceof SessionControlConflictError) {
+        throw new HTTPException(409, { message: error.message, cause: error });
+      }
+      throw error;
+    });
     if (event) {
       try {
         await bus.publish(workspaceId, sessionId, [event]);
@@ -1818,7 +2848,7 @@ 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);
-    CompactSessionContextRequest.parse((await c.req.json().catch(() => ({}))) ?? {});
+    parseRequestBody(CompactSessionContextRequest, (await c.req.json().catch(() => ({}))) ?? {});
     // /compact sets one durable request. The worker clears it only in the same
     // fenced transaction that installs replacement history, so failed or stale
     // attempts cannot lose the request.
@@ -1967,22 +2997,35 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
       c.header("X-OpenGeni-Covered-Last", String(result.coveredSequence.last));
       return c.json(result);
     }
-    const projected = compact ? coalesceSessionEventDeltas(events) : events;
+    const compactProjection = compact ? coalesceSessionEventDeltasWithCoverage(events) : null;
+    const projected = compactProjection?.events ?? events;
+    const forensicExact =
+      !compact && mode === "forensic" && payloadMode === "full" && dbPage.fullPayloadsExact;
     const page = boundSessionEventHttpPage(projected, {
       direction,
-      eventProjection: mode === "forensic" && payloadMode === "full" ? "exact" : "bounded",
+      eventProjection: payloadMode === "full" ? "exact" : "bounded",
+      ...(compactProjection
+        ? { coveredThroughBySequence: compactProjection.coveredThroughBySequence }
+        : {}),
     });
     const hasMore = dbPage.hasMore || page.truncated;
     c.header("X-OpenGeni-Page-Bytes", String(page.bytes));
-    c.header("X-OpenGeni-Page-Max-Bytes", String(1024 * 1024));
+    // One oversized exact event is admitted alone; never advertise a maximum
+    // smaller than the response we actually deliver.
+    c.header("X-OpenGeni-Page-Max-Bytes", String(Math.max(1024 * 1024, page.bytes)));
     c.header("X-OpenGeni-Page-Truncated", String(hasMore));
     c.header("X-OpenGeni-Has-More", String(hasMore));
     c.header("X-OpenGeni-Event-Mode", mode);
     c.header("X-OpenGeni-Event-Direction", direction);
     c.header("X-OpenGeni-Payload-Mode", payloadMode);
-    c.header("X-OpenGeni-Forensic-Exact", String(mode === "forensic" && payloadMode === "full"));
+    c.header("X-OpenGeni-Forensic-Exact", String(forensicExact));
     const coveredFirst = page.events[0]?.sequence;
-    const coveredLast = page.events.at(-1)?.sequence;
+    const coveredLastEvent = page.events.at(-1);
+    const coveredLast =
+      coveredLastEvent === undefined
+        ? undefined
+        : (compactProjection?.coveredThroughBySequence.get(coveredLastEvent.sequence) ??
+          coveredLastEvent.sequence);
     if (coveredFirst !== undefined) c.header("X-OpenGeni-Covered-First", String(coveredFirst));
     if (coveredLast !== undefined) c.header("X-OpenGeni-Covered-Last", String(coveredLast));
     const truncatedBy = page.truncated ? "http_bytes" : dbPage.truncatedBy;
@@ -1996,6 +3039,90 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     return c.json(page.events);
   });
 
+  // Selected search hit only: never use the audit event projection here, even
+  // in summary mode (it can contain modelContext or truncate visible text).
+  app.get(
+    "/v1/workspaces/:workspaceId/sessions/:sessionId/events/:eventId/message-preview",
+    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);
+      const eventId = c.req.param("eventId");
+      const rawSequence = c.req.query("sequence");
+      const sequence = Number(rawSequence);
+      if (
+        !z.string().uuid().safeParse(eventId).success ||
+        rawSequence === undefined ||
+        !/^\d+$/.test(rawSequence) ||
+        !Number.isSafeInteger(sequence) ||
+        sequence < 1 ||
+        sequence > 2_147_483_647
+      )
+        throw new HTTPException(400, { message: "Invalid message preview reference" });
+
+      const notFound = () => new HTTPException(404, { message: "message not found" });
+      const maxUnits = 12_000;
+      const eventTable = sessionPreviewSchema.sessionEvents;
+      // The slice helper supports structured result views too. Check only the
+      // JSON scalar *kind* before calling it; never fetch a structured text value.
+      const candidates = await withWorkspaceRls(db, workspaceId, (tx) =>
+        tx
+          .select({ kind: sql<string | null>`jsonb_typeof(${eventTable.payload}->'text')` })
+          .from(eventTable)
+          .where(
+            and(
+              eq(eventTable.workspaceId, workspaceId),
+              eq(eventTable.sessionId, sessionId),
+              eq(eventTable.id, eventId),
+              eq(eventTable.sequence, sequence),
+              sql`${eventTable.type} in ('user.message', 'agent.message.completed')`,
+            ),
+          )
+          .limit(1),
+      );
+      if (candidates[0]?.kind !== "string") throw notFound();
+      const read = (offset: number) =>
+        listSessionEventSlices(db, workspaceId, sessionId, {
+          sourceSequence: sequence,
+          sourceOffset: offset,
+          after: sequence - 1,
+          before: sequence + 1,
+          includeTypes: ["user.message", "agent.message.completed"],
+          view: "conversation",
+        });
+      const first = await read(0);
+      const event = first.events[0];
+      const slice = first.slices?.[sequence];
+      // Includes the slice reader's duplicate, late and unclaimed-prompt gates.
+      if (!event || event.id !== eventId || event.sequence !== sequence || !slice || slice.omitted)
+        throw notFound();
+      if (slice.total > maxUnits) return c.json({ status: "unavailable" as const });
+
+      let text = slice.text;
+      let offset = slice.unit === "utf16" ? slice.text.length : Array.from(slice.text).length;
+      if (text.length > maxUnits) return c.json({ status: "unavailable" as const });
+      while (offset < slice.total) {
+        if (offset === 0) throw notFound();
+        const next = await read(offset);
+        const part = next.slices?.[sequence];
+        if (
+          next.events[0]?.id !== eventId ||
+          !part ||
+          part.omitted ||
+          part.unit !== slice.unit ||
+          part.total !== slice.total ||
+          part.offset !== offset
+        )
+          throw notFound();
+        text += part.text;
+        offset += slice.unit === "utf16" ? part.text.length : Array.from(part.text).length;
+        if (text.length > maxUnits) return c.json({ status: "unavailable" as const });
+      }
+      return c.json({ status: "available" as const, text });
+    },
+  );
+
   app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/events/stream", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:read");
@@ -2020,20 +3147,19 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
       Number.isFinite(after) ? after : 0,
       c.req.raw.signal,
       {
+        ...browserSseDeliveryOptions(c.req.query("transport")),
         observability: deps.observability,
-        ...(authorization
-          ? {
-              reauthorizeAfterMs:
-                authorization.reauthorizeAfterMs ?? SESSION_AUTHORIZATION_DEFAULT_REAUTHORIZE_MS,
-              reauthorize: async () => {
-                await requireSessionAuthorization(deps, grant, {
-                  sessionId,
-                  operation: "session.stream.read",
-                  surface: "stream",
-                });
-              },
-            }
-          : {}),
+        actorEpoch: getManagedAuthRequestActorEpoch(c.req.raw) ?? undefined,
+        reauthorizeAfterMs:
+          authorization?.reauthorizeAfterMs ?? SESSION_AUTHORIZATION_DEFAULT_REAUTHORIZE_MS,
+        reauthorize: async () => {
+          const freshGrant = await requireFreshAccessGrant(c, deps, workspaceId, "sessions:read");
+          await requireSessionAuthorization(deps, freshGrant, {
+            sessionId,
+            operation: "session.stream.read",
+            surface: "stream",
+          });
+        },
       },
     );
   });
@@ -2055,6 +3181,27 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     );
   });
 
+  app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/mcp-credentials/rotate", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "sessions:control",
+    );
+    const payload = await c.req.json().catch(() => null);
+    c.header("cache-control", "private, no-store");
+    return c.json(
+      await rotateSessionMcpCredentialsForRequest(
+        deps,
+        authorization,
+        c.req.param("sessionId"),
+        payload,
+        (tx) => requireFreshAccessGrant(c, { ...deps, db: tx }, workspaceId, "sessions:control"),
+      ),
+    );
+  });
+
   app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/queue", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     await requireAccessGrant(c, deps, workspaceId, "sessions:read");
@@ -2069,7 +3216,7 @@ 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 payload = MoveSessionQueueItemRequest.parse(await c.req.json());
+    const payload = await parseRequestJson(c, MoveSessionQueueItemRequest);
     try {
       const response = await moveHumanQueuePrompt(
         deps,
@@ -2096,7 +3243,7 @@ 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 payload = EditSessionQueueItemRequest.parse(await c.req.json());
+    const payload = await parseRequestJson(c, EditSessionQueueItemRequest);
     try {
       const response = await editHumanQueuePrompt(
         deps,
@@ -2123,7 +3270,7 @@ 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 payload = SteerSessionQueueItemRequest.parse(await c.req.json());
+    const payload = await parseRequestJson(c, SteerSessionQueueItemRequest);
     try {
       const response = await steerHumanQueuePrompt(
         deps,
@@ -2150,7 +3297,7 @@ 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 payload = DeleteSessionQueueItemRequest.parse(await c.req.json());
+    const payload = await parseRequestJson(c, DeleteSessionQueueItemRequest);
     try {
       const response = await deleteHumanQueuePrompt(
         deps,
@@ -2190,7 +3337,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 payload = SaveComposerDraftRequest.parse(await c.req.json());
+    const payload = await parseRequestJson(c, SaveComposerDraftRequest);
     try {
       return c.json(
         await saveHumanComposerDraft(
@@ -2209,6 +3356,112 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     }
   });
 
+  app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/sandbox-recovery", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const authorization = await requireAccessGrantAuthorization(c, deps, workspaceId);
+    try {
+      return c.json(
+        await getManagedHumanSandboxRecovery(
+          deps,
+          authorization,
+          workspaceId,
+          c.req.param("sessionId"),
+        ),
+      );
+    } catch (error) {
+      throw sessionTenancyHttpError(error);
+    }
+  });
+
+  app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/sandbox-recovery", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const sessionId = c.req.param("sessionId");
+    const authorization = await requireAccessGrantAuthorization(c, deps, workspaceId);
+    const parsed = SandboxRecoveryRequest.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) throw new HTTPException(400, { message: "invalid checkpoint consent" });
+    let consentCommitted = false;
+    try {
+      const receipt = await consentManagedHumanSandboxRecovery(
+        deps,
+        authorization,
+        workspaceId,
+        sessionId,
+        parsed.data,
+      );
+      consentCommitted = true;
+      const projection = await getManagedHumanSandboxRecovery(
+        deps,
+        authorization,
+        workspaceId,
+        sessionId,
+      );
+      if (
+        projection.operationId === receipt.operationId &&
+        projection.status === "consent_accepted"
+      ) {
+        // Establish/verify only. No failed-turn Retry, Send, tool callback or
+        // command replay. The ordinary cold->warming election owns creation.
+        const session = await getSession(db, workspaceId, sessionId);
+        if (session) {
+          try {
+            await withChannelARead(
+              channelAServices,
+              {
+                accountId: authorization.grant.accountId,
+                workspaceId,
+                session,
+                subjectId: authorization.grant.subjectId,
+              },
+              async () => undefined,
+            );
+          } catch {
+            // Consent committed. Never turn a provider failure into a false
+            // rejection of consent or leak native provider bindings/messages.
+          }
+        }
+      }
+      return c.json({
+        ...receipt,
+        recovery: await getManagedHumanSandboxRecovery(deps, authorization, workspaceId, sessionId),
+      });
+    } catch (error) {
+      if (consentCommitted) {
+        // A later authorization/read failure cannot revoke the committed
+        // receipt. Return no session state, checkpoint or provider details.
+        return c.json(
+          {
+            code: "upstream_unavailable",
+            message:
+              "Recovery status could not be confirmed. Check status without resubmitting consent.",
+            outcomeUnknown: true,
+            retryable: false,
+          },
+          503,
+        );
+      }
+      if (error instanceof SandboxRecoveryConflictError)
+        return c.json({ code: error.code, message: error.message }, 409);
+      if (error instanceof SessionCommandIdempotencyError) return commandConflictResponse(c, error);
+      throw sessionTenancyHttpError(error);
+    }
+  });
+
+  app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/retry", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:control");
+    const parsed = SessionRetryRequest.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) throw new HTTPException(400, { message: "invalid session retry request" });
+    try {
+      return c.json(
+        await retryFailedSession(deps, grant, workspaceId, c.req.param("sessionId"), parsed.data),
+      );
+    } catch (error) {
+      if (error instanceof SessionRetryConflictError)
+        return c.json({ code: error.code, message: error.message }, 409);
+      return commandConflictResponse(c, error);
+    }
+  });
+
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/control", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:control");
@@ -2246,37 +3499,91 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     } catch (error) {
       return commandConflictResponse(c, error);
     }
-  });
-
-  app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/steer", 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 = 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,
-      reasoningEffort: payload.reasoningEffort ?? null,
-      latencyMode: payload.latencyMode ?? null,
-      mcpCredentialUpdates: payload.mcpCredentialUpdates ?? [],
-      delivery: "steer",
-      origin: "human",
-      ...(payload.controlEtag !== undefined ? { controlEtag: payload.controlEtag } : {}),
-      ...(payload.expectedDraftRevision !== undefined
-        ? { expectedDraftRevision: payload.expectedDraftRevision }
-        : {}),
-      ...(payload.clientEventId ? { clientEventId: payload.clientEventId } : {}),
-    });
+  });
+
+  app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/steer", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "sessions:control",
+    );
+    const grant = authorization.grant;
+    const sessionId = c.req.param("sessionId");
+    await assertSessionExists(db, workspaceId, sessionId);
+    const payload = parseSteerSessionAdmission(await c.req.json().catch(() => null));
+    let result: Awaited<ReturnType<typeof acceptSessionUserMessage>>;
+    try {
+      result = await withSiteCommandOrigin(c, workspaceId, () =>
+        acceptSessionUserMessage(deps, grant, workspaceId, sessionId, {
+          text: payload.text,
+          annotations: payload.annotations,
+          modelContext: payload.modelContext ?? null,
+          resources: payload.resources,
+          model: payload.model ?? null,
+          reasoningEffort: payload.reasoningEffort ?? null,
+          latencyMode: payload.latencyMode ?? null,
+          mcpCredentialUpdates: payload.mcpCredentialUpdates ?? [],
+          connectionAccounts: payload.connectionAccounts,
+          ...(payload.personalResourceAttachment
+            ? { personalResourceAttachment: payload.personalResourceAttachment }
+            : {}),
+          authorization,
+          delivery: "steer",
+          origin: "human",
+          ...(payload.controlEtag !== undefined ? { controlEtag: payload.controlEtag } : {}),
+          ...(payload.expectedDraftRevision !== undefined
+            ? { expectedDraftRevision: payload.expectedDraftRevision }
+            : {}),
+          ...(payload.clientEventId ? { clientEventId: payload.clientEventId } : {}),
+        }),
+      );
+    } catch (error) {
+      return commandConflictResponse(c, error);
+    }
+    recordAcceptedApiAdmission(deps.observability, result);
+    return c.json(result, 202);
+  });
+
+  app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/composer-draft/submit", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "sessions:control",
+    );
+    const grant = authorization.grant;
+    const sessionId = c.req.param("sessionId");
+    await assertSessionExists(db, workspaceId, sessionId);
+    const payload = parseRequestBody(
+      SubmitComposerDraftRequest,
+      await c.req.json().catch(() => null),
+    );
+    let result: Awaited<ReturnType<typeof submitComposerDraftForRequest>>;
+    try {
+      result = await withSiteCommandOrigin(c, workspaceId, () =>
+        submitComposerDraftForRequest(deps, grant, workspaceId, sessionId, payload, {
+          authorization,
+        }),
+      );
+    } catch (error) {
+      return commandConflictResponse(c, error);
+    }
+    recordAcceptedApiAdmission(deps.observability, result);
     return c.json(result, 202);
   });
 
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/events", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:control");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "sessions:control",
+    );
+    const grant = authorization.grant;
     const sessionId = c.req.param("sessionId");
     const event = parseSessionEventAdmission(await c.req.json().catch(() => null));
     const refinedOperation =
@@ -2297,35 +3604,75 @@ 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,
-        reasoningEffort: event.payload.reasoningEffort ?? null,
-        latencyMode: event.payload.latencyMode ?? null,
-        mcpCredentialUpdates: event.payload.mcpCredentialUpdates ?? [],
-        ...(event.payload.controlEtag !== undefined
-          ? { controlEtag: event.payload.controlEtag }
-          : {}),
-        ...(event.payload.expectedDraftRevision !== undefined
-          ? { expectedDraftRevision: event.payload.expectedDraftRevision }
-          : {}),
-        ...(event.clientEventId ? { clientEventId: event.clientEventId } : {}),
+      let result: Awaited<ReturnType<typeof acceptSessionUserMessage>>;
+      try {
+        result = await withSiteCommandOrigin(c, workspaceId, () =>
+          acceptSessionUserMessage(deps, grant, workspaceId, sessionId, {
+            text: event.payload.text,
+            annotations: event.payload.annotations,
+            modelContext: event.payload.modelContext ?? null,
+            resources: event.payload.resources ?? [],
+            model: event.payload.model ?? null,
+            reasoningEffort: event.payload.reasoningEffort ?? null,
+            latencyMode: event.payload.latencyMode ?? null,
+            mcpCredentialUpdates: event.payload.mcpCredentialUpdates ?? [],
+            connectionAccounts: event.payload.connectionAccounts,
+            ...(event.payload.personalResourceAttachment
+              ? { personalResourceAttachment: event.payload.personalResourceAttachment }
+              : {}),
+            authorization,
+            ...(event.payload.controlEtag !== undefined
+              ? { controlEtag: event.payload.controlEtag }
+              : {}),
+            ...(event.payload.expectedDraftRevision !== undefined
+              ? { expectedDraftRevision: event.payload.expectedDraftRevision }
+              : {}),
+            ...(event.clientEventId ? { clientEventId: event.clientEventId } : {}),
+          }),
+        );
+      } catch (error) {
+        return commandConflictResponse(c, error);
+      }
+      recordAcceptedApiAdmission(deps.observability, result);
+      return c.json(result.accepted, 202);
+    }
+
+    // Responses use the same header-only validation, permission and encryption
+    // boundary as Send/Steer. Persistence belongs to the response transaction,
+    // never a separate rotation that could commit without accepting the reply.
+    const updates = event.payload.mcpCredentialUpdates ?? [];
+    let mcpCredentialUpdates = [] as ReturnType<typeof validateSessionMcpCredentialUpdates>;
+    if (updates.length) {
+      const session = await getSession(db, workspaceId, sessionId);
+      if (!session) throw new HTTPException(404, { message: "session not found" });
+      mcpCredentialUpdates = validateSessionMcpCredentialUpdates({
+        settings,
+        grant,
+        session,
+        updates,
       });
-      return c.json(accepted, 202);
     }
 
     if (event.type === "user.approvalDecision") {
-      const accepted = await acceptSessionApprovalDecision(db, {
-        accountId: grant.accountId,
-        workspaceId,
-        sessionId,
-        subjectId: grant.subjectId,
-        payload: event.payload,
-        clientEventId: event.clientEventId ?? null,
-      });
+      const { mcpCredentialUpdates: _writeOnlyCredentials, ...payload } = event.payload;
+      let accepted;
+      try {
+        accepted = await acceptSessionApprovalDecision(db, {
+          accountId: grant.accountId,
+          workspaceId,
+          sessionId,
+          subjectId: grant.subjectId,
+          respondedByKind: childRequiresActionRespondedByKindForGrant(grant),
+          payload,
+          mcpCredentialUpdates,
+          clientEventId: event.clientEventId ?? null,
+        });
+      } catch (error) {
+        if (error instanceof Error && error.message.startsWith("Unknown session MCP server")) {
+          throw new HTTPException(422, { message: error.message });
+        }
+        throw error;
+      }
       if (accepted.action === "conflict") {
         throw new HTTPException(409, {
           message: `session is ${accepted.sessionStatus}; no unhandled approval is pending`,
@@ -2354,13 +3701,37 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
           requestId: event.payload.requestId,
           response: event.payload.response,
           respondedBy: grant.subjectId,
+          canonicalHumanSession:
+            authorization.canonicalManagedHumanSession ||
+            authorization.canonicalLocalHumanSession ||
+            isVerifiedDelegatedHumanAuthorization(authorization),
+          respondedByKind: childRequiresActionRespondedByKindForGrant(grant),
           clientEventId: event.clientEventId ?? null,
+          mcpCredentialUpdates,
         });
       } catch (error) {
+        if (error instanceof Error && error.message.startsWith("Unknown session MCP server")) {
+          throw new HTTPException(422, { message: error.message });
+        }
+        if (error instanceof SkillHumanResponseError) {
+          throw new HTTPException(
+            error.code === "conflict" ? 409 : error.code === "forbidden" ? 403 : 422,
+            {
+              message: error.message,
+            },
+          );
+        }
         if (error instanceof HumanInputResponseValidationError) {
-          throw new HTTPException(error.code === "SKIP_NOT_ALLOWED" ? 409 : 422, {
-            message: error.message,
-          });
+          throw new HTTPException(
+            error.code === "HUMAN_AUTH_REQUIRED"
+              ? 403
+              : error.code === "SKIP_NOT_ALLOWED"
+                ? 409
+                : 422,
+            {
+              message: error.message,
+            },
+          );
         }
         throw error;
       }
@@ -2382,10 +3753,10 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
       }
       if (accepted.action === "conflict") {
         throw new HTTPException(409, {
-          message: `human-input request is ${accepted.request.status}`,
+          message: "human-input request is not currently actionable",
         });
       }
-      return c.json(accepted.event, 202);
+      return c.json(accepted.event, accepted.action === "completed" ? 200 : 202);
     }
   });
 
@@ -2481,7 +3852,11 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     // 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)
+      ? await getSandbox(
+          db,
+          { accountId: grant.accountId, workspaceId, subjectId: grant.subjectId },
+          session.activeSandboxId,
+        )
       : null;
     const selfhostedActive = activeSandbox?.kind === "selfhosted";
     const lease = await readGroupLease(
@@ -2513,12 +3888,8 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
       // 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.
+      // take-control). Agent interaction uses managed ComputerSession tools.
       desktopInteractive: settings.sandboxDesktopInteractive,
-      // 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 when scoped stream credentials cannot be minted.
       streamTokenSecretAvailable: !streamTokenDegraded(settings),
       desktopAcknowledged: acknowledged,
@@ -2529,12 +3900,23 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
 
     let capabilities;
     if (selfhostedActive && activeSandbox.enrollmentId) {
-      const enrollment = await getEnrollment(db, workspaceId, activeSandbox.enrollmentId);
+      const [enrollment, liveConnection] = await Promise.all([
+        getEnrollment(db, grant, activeSandbox.enrollmentId),
+        getLiveEnrollmentConnection(db, grant, activeSandbox.enrollmentId),
+      ]);
+      const reportedWorkspaceRoot = liveConnection?.workspaceRoot ?? enrollment?.workspaceRoot;
+      const effectiveWorkspaceRoot = reportedWorkspaceRoot
+        ? resolveConnectedMachineWorkspaceRoot(reportedWorkspaceRoot, session.workingDir)
+        : null;
       let probeResponded = false;
-      if (enrollment?.status === "active") {
+      if (liveConnection?.connectionInstanceId) {
         const machine = new SelfhostedSession({
-          workspaceId,
-          agentId: enrollment.id,
+          workspaceId: activeSandbox.workspaceId,
+          agentId: liveConnection.id,
+          connectionInstanceId: liveConnection.connectionInstanceId,
+          // Capability negotiation only pings, so a pre-root agent may still
+          // report upgrade guidance without exposing a false filesystem root.
+          workspaceRoot: effectiveWorkspaceRoot ?? liveConnection.workspaceRoot ?? "/",
           controlRpc: new NatsControlRpc(async () => bus.getRequestConnection()),
           relay: relayConfigFromSettings(settings),
           epoch: session.activeEpoch,
@@ -2550,7 +3932,10 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         ...commonNegotiation,
         os: enrollment?.os ?? session.sandboxOs,
         leaseEpoch: session.activeEpoch,
-        enrollment,
+        enrollment:
+          enrollment && effectiveWorkspaceRoot
+            ? { ...enrollment, workspaceRoot: effectiveWorkspaceRoot }
+            : enrollment,
         probeResponded,
       });
     } else {
@@ -2597,6 +3982,20 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     // place (resolveActiveDesktopTransport), covering BOTH swap directions.
     let responseCapabilities = {
       ...capabilities,
+      FileSystem: {
+        ...capabilities.FileSystem,
+        root: selfhostedActive
+          ? capabilities.FileSystem.root
+          : selectBackend(
+              (activeSandbox?.kind === "modal"
+                ? "modal"
+                : session.sandboxBackend === "selfhosted" &&
+                    settings.sandboxBackend !== "selfhosted" &&
+                    settings.sandboxBackend !== "none"
+                  ? settings.sandboxBackend
+                  : session.sandboxBackend) as SandboxBackend,
+            ).workspaceRoot,
+      },
       Git: {
         ...capabilities.Git,
         repos: capabilities.Git.available ? repositoryRoots : [],
@@ -2612,6 +4011,21 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         DesktopStream: { ...capabilities.DesktopStream, ...wire },
       };
     }
+    if (selfhostedActive) {
+      const currentPointer = await readActiveSandbox(db, workspaceId, sessionId);
+      if (
+        !currentPointer ||
+        currentPointer.activeSandboxId !== session.activeSandboxId ||
+        currentPointer.activeEpoch !== session.activeEpoch ||
+        currentPointer.workingDir !== session.workingDir
+      ) {
+        throw new ApiHttpError(409, {
+          code: "conflict",
+          message: "sandbox route changed while capabilities were being negotiated; retry",
+          retryable: true,
+        });
+      }
+    }
     return c.json(responseCapabilities);
   });
 
@@ -2723,7 +4137,11 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     // attachViewer (it warms the Modal group box — the wrong target). Synthesize a
     // result shaped like ViewerAttachResult and mint relay cells directly.
     const activeSandbox = session.activeSandboxId
-      ? await getSandbox(db, workspaceId, session.activeSandboxId)
+      ? await getSandbox(
+          db,
+          { accountId: grant.accountId, workspaceId, subjectId: grant.subjectId },
+          session.activeSandboxId,
+        )
       : null;
     const selfhostedActive = activeSandbox?.kind === "selfhosted";
 
@@ -2753,6 +4171,8 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
           stream = await mintDesktopStream(viewerServices, {
             accountId: grant.accountId,
             workspaceId,
+            resourceSubjectId: grant.subjectId,
+            resourceSubjectDelegated: grant.metadata?.delegated === true,
             session,
             viewerId,
             // No Modal lease for selfhosted-active; the mint routes to the relay.
@@ -2762,6 +4182,8 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
           terminal = await mintTerminalStream(viewerServices, {
             accountId: grant.accountId,
             workspaceId,
+            resourceSubjectId: grant.subjectId,
+            resourceSubjectDelegated: grant.metadata?.delegated === true,
             session,
             viewerId,
             // No Modal lease for selfhosted-active; the mint routes to the relay.
@@ -2773,6 +4195,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         accountId: grant.accountId,
         workspaceId,
         session,
+        viewerSubjectId: grant.subjectId,
         waitSignal: c.req.raw.signal,
         ...(parsed.data.viewerId ? { viewerId: parsed.data.viewerId } : {}),
       });
@@ -2800,6 +4223,8 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
             stream = await mintDesktopStream(viewerServices, {
               accountId: grant.accountId,
               workspaceId,
+              resourceSubjectId: grant.subjectId,
+              resourceSubjectDelegated: grant.metadata?.delegated === true,
               session,
               viewerId: result.viewerId,
               lease,
@@ -2809,6 +4234,8 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
             terminal = await mintTerminalStream(viewerServices, {
               accountId: grant.accountId,
               workspaceId,
+              resourceSubjectId: grant.subjectId,
+              resourceSubjectDelegated: grant.metadata?.delegated === true,
               session,
               viewerId: result.viewerId,
               lease,
@@ -2951,6 +4378,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
   // (rides files:read); Terminal exec + PTY ride terminal:attach.
 
   type ChannelARouteCtx = ChannelAContext & {
+    grant: AccessGrant;
     waitSignal: AbortSignal;
     operation: ChannelAOperation;
   };
@@ -2971,6 +4399,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
       throw new HTTPException(404, { message: "session not found" });
     }
     return {
+      grant,
       accountId: grant.accountId,
       workspaceId,
       session,
@@ -3020,6 +4449,36 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     return c.json(out);
   });
 
+  app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/fs/read-workspace", async (c) => {
+    const ctx = await channelAPreamble(c, "files:read", "fs.read");
+    const req = await parseChannelABody(c, FsReadRequest);
+    const out = await withChannelARead(channelAServices, ctx, ({ service }) =>
+      service.fsRead({ ...req, workspaceOnly: true }),
+    );
+    return c.json(out);
+  });
+
+  app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/artifacts/publish", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "files:upload",
+    );
+    const ctx = await channelAPreamble(c, "files:read", "artifact.publish");
+    const request = await parseChannelABody(c, PublishSandboxFileArtifactRequest);
+    return c.json(
+      await publishSandboxFileArtifact(deps, {
+        grant: ctx.grant,
+        authorization,
+        session: ctx.session,
+        path: request.path,
+        signal: ctx.waitSignal,
+      }),
+    );
+  });
+
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/fs/write", async (c) => {
     const ctx = await channelAPreamble(c, "files:write", "fs.write");
     const req = await parseChannelABody(c, FsWriteRequest);
@@ -3142,7 +4601,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
   // the live/wake path — the feature degrades to today's behavior, never worse.
   app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/workspace/capture", async (c) => {
     const workspaceId = c.req.param("workspaceId") ?? "";
-    await requireAccessGrant(c, deps, workspaceId, "files:read");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "files:read");
     const sessionId = c.req.param("sessionId") ?? "";
     const lookup = await sessionLatestWorkspaceCapture(db, workspaceId, sessionId);
     if (!lookup.sessionExists) {
@@ -3153,13 +4612,27 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
       return c.json({ available: false });
     }
     return c.json(
-      await serveWorkspaceCapture(lookup.capture, objectStorage, workspaceCaptureManifestCache),
+      await serveWorkspaceCapture(
+        lookup.capture,
+        objectStorage,
+        workspaceCaptureManifestCache,
+        (fact) =>
+          recordAuditEvent(db, {
+            accountId: grant.accountId,
+            workspaceId,
+            subjectId: grant.subjectId,
+            action: "file.signed_url.issued",
+            targetType: "workspace_capture",
+            targetId: sessionId,
+            metadata: { sessionId, ...fact },
+          }),
+      ),
     );
   });
 
   app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/workspace/capture/file", async (c) => {
     const workspaceId = c.req.param("workspaceId") ?? "";
-    await requireAccessGrant(c, deps, workspaceId, "files:read");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "files:read");
     const sessionId = c.req.param("sessionId") ?? "";
     const path = c.req.query("path");
     if (!path) {
@@ -3188,7 +4661,21 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     } else {
       row = await latestWorkspaceCapture(db, workspaceId, sessionId);
     }
-    return c.json(await serveWorkspaceCaptureFile(row, path, objectStorage));
+    return c.json(
+      await serveWorkspaceCaptureFile(row, path, objectStorage, (fact) =>
+        recordAuditEvent(db, {
+          accountId: grant.accountId,
+          workspaceId,
+          subjectId: grant.subjectId,
+          action: "file.signed_url.issued",
+          targetType: "workspace_capture",
+          targetId: sessionId,
+          // The captured PATH is workspace-file identity (like a filename),
+          // not content; the signed URL and object key are never recorded.
+          metadata: { sessionId, path, ...fact },
+        }),
+      ),
+    );
   });
 
   // ── Terminal: synchronous exec ────────────────────────────────────────────
@@ -3510,15 +4997,30 @@ export function sessionAuthorizationOperationForHttp(
   if (suffix === "") {
     if (verb === "GET") return "session.read";
     if (verb === "PATCH") return "session.title.write";
+    if (verb === "DELETE") return "session.delete";
     return null;
   }
   if (suffix === "/pin" && verb === "PUT") return "session.pin.write";
+  if (suffix === "/attention" && verb === "PUT") return "session.attention.write";
+  if (suffix === "/archive" && verb === "PUT") return "session.archive.write";
+  if (suffix === "/visibility" && verb === "PUT") return "session.visibility.write";
+  if (suffix === "/forks" && verb === "POST") return "session.fork.create";
   if (suffix === "/channel" && verb === "PUT") return "session.channel.write";
+  if (suffix === "/variable-sets" && verb === "PUT") return "session.variable_sets.write";
   if (suffix === "/tool-policy" && verb === "PUT") return "session.tool_policy.write";
+  if (suffix === "/agent" && verb === "PUT") return "session.tool_policy.write";
+  if (suffix === "/mcp-credentials/rotate" && verb === "POST")
+    return "session.mcp.credentials.rotate";
   if (/^\/mcp-servers\/[^/]+\/approval-policy$/.test(suffix) && verb === "PATCH") {
     return "session.mcp.approval_policy.write";
   }
   if (suffix === "/lineage" && verb === "GET") return "session.lineage.read";
+  if (suffix === "/background-commands" && verb === "GET") return "session.read";
+  if (suffix === "/model-context" && verb === "GET") return "session.read";
+  if (suffix === "/codex-accounts" && verb === "GET") return "session.read";
+  if (/^\/background-commands\/[^/]+$/.test(suffix) && verb === "DELETE") {
+    return "session.control";
+  }
   if (suffix === "/codex-account" && verb === "POST") {
     return "session.codex_account.write";
   }
@@ -3554,13 +5056,19 @@ export function sessionAuthorizationOperationForHttp(
         : null;
   }
   if (suffix === "/goal/revisions" && verb === "GET") return "session.goal.read";
+  if (suffix === "/goal/revisions/page" && verb === "GET") return "session.goal.read";
   if (/^\/goal\/revisions\/[^/]+\/apply$/.test(suffix) && verb === "POST") {
     return "session.goal.write";
   }
+  if (/^\/goal\/revisions\/[^/]+\/(reject|rollback)$/.test(suffix) && verb === "POST") {
+    return "session.goal.write";
+  }
   if (suffix === "/context/clear" || suffix === "/context/compact") {
     return verb === "POST" ? "session.context.write" : null;
   }
   if (suffix === "/events/stream" && verb === "GET") return "session.stream.read";
+  if (/^\/events\/[^/]+\/message-preview$/.test(suffix) && verb === "GET")
+    return "session.events.read";
   if (suffix === "/events") {
     if (verb === "GET") return "session.events.read";
     if (verb === "POST") return "session.append";
@@ -3574,7 +5082,12 @@ export function sessionAuthorizationOperationForHttp(
     if (verb === "PUT") return "session.composer.write";
     return null;
   }
+  // Same HTTP gate as POST /events. Delivery `steer` is re-authorized inside
+  // acceptSessionUserMessageWithOutcome after the body is parsed.
+  if (suffix === "/composer-draft/submit" && verb === "POST") return "session.append";
   if (suffix === "/control" && verb === "POST") return "session.control";
+  if (suffix === "/retry" && verb === "POST") return "session.control";
+  if (suffix === "/sandbox-recovery" && ["GET", "POST"].includes(verb)) return "session.control";
   if (suffix === "/steer" && verb === "POST") return "session.steer";
   if (suffix === "/human-input-requests" && verb === "GET") {
     return "session.human_input.read";
@@ -3590,9 +5103,16 @@ export function sessionAuthorizationOperationForHttp(
   if (suffix.startsWith("/viewers/") && ["POST", "DELETE"].includes(verb)) {
     return "session.viewer.control";
   }
-  if (suffix === "/fs/list" || suffix === "/fs/list-batch" || suffix === "/fs/read") {
+  if (
+    suffix === "/fs/list" ||
+    suffix === "/fs/list-batch" ||
+    suffix === "/fs/read" ||
+    suffix === "/fs/read-workspace"
+  ) {
     return verb === "POST" ? "session.files.read" : null;
   }
+  if (suffix === "/artifacts/publish" && verb === "POST") return "session.files.write";
+  if (suffix.startsWith("/artifact-associations/") && verb === "GET") return "session.read";
   if (["/fs/write", "/fs/delete", "/fs/move", "/fs/mkdir"].includes(suffix)) {
     return verb === "POST" ? "session.files.write" : null;
   }
@@ -3621,6 +5141,70 @@ function sessionAuthorizationHttpError(error: unknown): HTTPException {
   throw error;
 }
 
+export function sessionTenancyHttpError(error: unknown): Error {
+  if (error instanceof SessionTenancyManagedHumanRequiredError) {
+    return new ApiHttpError(403, {
+      code: "forbidden",
+      message: "Session tenancy mutations require the owning managed-human session.",
+      retryable: false,
+    });
+  }
+  if (error instanceof SessionTenancyNotActivatedError) {
+    return new ApiHttpError(409, {
+      code: "conflict",
+      message: "Session tenancy is not activated for this organization.",
+      retryable: false,
+      details: { reason: "not_activated" },
+    });
+  }
+  if (error instanceof SessionTenancyConflictError) {
+    return new ApiHttpError(409, {
+      code: error.reason === "operation_reuse" ? "idempotency_conflict" : "conflict",
+      message:
+        error.reason === "not_quiescent"
+          ? "The session must be fully quiescent before this change."
+          : error.reason === "authority_epoch"
+            ? "The session authority changed before this operation committed."
+            : "The idempotency key was already used with different input.",
+      retryable: false,
+      details: {
+        reason: error.reason,
+        ...(error.blocker ? { blocker: error.blocker } : {}),
+      },
+    });
+  }
+  if (
+    error instanceof SessionTenancyAccessError ||
+    error instanceof SessionAuthorizationDeniedError
+  ) {
+    return new ApiHttpError(404, {
+      code: "not_found",
+      message: "Session not found.",
+      retryable: false,
+    });
+  }
+  if (error instanceof SessionTenancyInvalidRequestError) {
+    return new ApiHttpError(422, {
+      code: "validation_failed",
+      message: "Invalid session tenancy request.",
+      retryable: false,
+    });
+  }
+  if (error instanceof SessionTenancyPersistenceOutcomeUnknownError) {
+    return new ApiHttpError(503, {
+      code: "upstream_unavailable",
+      message:
+        "The session tenancy mutation outcome is unknown. Retry with the same idempotency key.",
+      retryable: true,
+      outcomeUnknown: true,
+    });
+  }
+  if (error instanceof SessionAuthorizationUnavailableError) {
+    return sessionAuthorizationHttpError(error);
+  }
+  return error instanceof Error ? error : new Error("Unknown session tenancy error");
+}
+
 function eventEnumValue<T extends string>(
   raw: string | undefined,
   schema: { safeParse(value: unknown): { success: boolean; data?: T } },
@@ -3673,17 +5257,35 @@ function eventEnumList<T extends string>(
   });
 }
 
-function sessionListQuery(
+export function sessionListQuery(
   query: Record<string, string>,
   allowCursor = true,
 ): {
+  originSiteId: string | undefined;
   limit: string | undefined;
   parentSessionId: string | null | undefined;
   cursor: ReturnType<typeof decodeSessionListCursor> | undefined;
   search: string | undefined;
   pinsOnly: boolean;
+  includePinned: boolean;
+  includeTotals: boolean;
+  needsYouOnly: boolean;
+  archivedOnly: boolean;
+  sortBy: "updatedAt" | "createdAt" | "name" | undefined;
+  archiveStatus: "active" | "archived" | "all" | undefined;
+  channelId: string | null | undefined;
+  createdBy: { kind: "subject" | "service"; subjectId: string } | undefined;
+  updatedFrom: Date | undefined;
+  updatedBefore: Date | undefined;
+  createdFrom: Date | undefined;
+  createdBefore: Date | undefined;
+  scopeSubjectId: SessionScopeSubjectId | undefined;
+  hasPageFilters: boolean;
 } {
   const parentSessionId = query.parentSessionId;
+  const originSiteId = query.originSiteId;
+  if (originSiteId !== undefined && !z.string().uuid().safeParse(originSiteId).success)
+    throw new HTTPException(400, { message: "originSiteId must be a Site id" });
   // "null" = roots only; a uuid = children of that session; anything else is
   // a client error (an unvalidated value would surface as a Postgres uuid cast
   // failure -> 500 rather than an honest 400).
@@ -3713,16 +5315,136 @@ function sessionListQuery(
     });
   }
   const pinsOnly = query.pinsOnly === "true";
+  if (query.includePinned !== undefined && !["true", "false"].includes(query.includePinned)) {
+    throw new HTTPException(400, { message: 'includePinned must be "true" or "false"' });
+  }
+  const includePinned = query.includePinned !== "false";
+  for (const key of ["includeTotals", "needsYouOnly"]) {
+    if (query[key] !== undefined && !["true", "false"].includes(query[key]!))
+      throw new HTTPException(400, { message: `${key} must be "true" or "false"` });
+  }
+  const includeTotals = query.includeTotals === "true";
+  const needsYouOnly = query.needsYouOnly === "true";
+  if (includeTotals && (!allowCursor || (parentSessionId !== "null" && !pinsOnly)))
+    throw new HTTPException(400, { message: "includeTotals requires a root page" });
+  if (needsYouOnly && !allowCursor)
+    throw new HTTPException(400, { message: 'needsYouOnly requires view="page"' });
+  if (pinsOnly && !includePinned) {
+    throw new HTTPException(400, { message: "pinsOnly requires includePinned" });
+  }
+  if (query.archivedOnly !== undefined && query.archivedOnly !== "true") {
+    throw new HTTPException(400, { message: 'archivedOnly must be the literal "true"' });
+  }
+  const archivedOnly = query.archivedOnly === "true";
+  const sortBy = z.enum(["updatedAt", "createdAt", "name"]).optional().safeParse(query.sortBy);
+  const archiveStatus = z
+    .enum(["active", "archived", "all"])
+    .optional()
+    .safeParse(query.archiveStatus);
+  if (!sortBy.success || !archiveStatus.success) {
+    throw new HTTPException(400, { message: "Invalid session sortBy or archiveStatus" });
+  }
+  if (archivedOnly && archiveStatus.data !== undefined && archiveStatus.data !== "archived") {
+    throw new HTTPException(400, { message: "archivedOnly conflicts with archiveStatus" });
+  }
+  if (pinsOnly && archiveStatus.data === "archived") {
+    throw new HTTPException(400, { message: "pinsOnly cannot be combined with archived status" });
+  }
+  const channelId = query.channelId;
+  if (
+    channelId !== undefined &&
+    channelId !== "null" &&
+    !z.string().uuid().safeParse(channelId).success
+  ) {
+    throw new HTTPException(400, {
+      message: 'channelId must be a channel id or the literal "null"',
+    });
+  }
+  const createdByKind = query.createdByKind;
+  const createdBySubjectId = query.createdBySubjectId;
+  if ((createdByKind === undefined) !== (createdBySubjectId === undefined)) {
+    throw new HTTPException(400, {
+      message: "createdByKind and createdBySubjectId must be supplied together",
+    });
+  }
+  if (createdByKind !== undefined && createdByKind !== "subject" && createdByKind !== "service") {
+    throw new HTTPException(400, {
+      message: 'createdByKind must be "subject" or "service"',
+    });
+  }
+  if (
+    createdBySubjectId !== undefined &&
+    (createdBySubjectId.trim().length < 1 || createdBySubjectId.length > 1_024)
+  ) {
+    throw new HTTPException(400, {
+      message: "createdBySubjectId must be between 1 and 1024 characters",
+    });
+  }
+  const parseDateBound = (name: string): Date | undefined => {
+    const raw = query[name];
+    if (raw === undefined) return undefined;
+    const parsed = z.string().datetime({ offset: true }).safeParse(raw);
+    if (!parsed.success) {
+      throw new HTTPException(400, { message: `${name} must be an ISO-8601 timestamp` });
+    }
+    // Date-backed filters must not silently round accepted microseconds to an
+    // earlier boundary. Clients can use any ISO offset with at most 3 decimals.
+    if (/\.\d{4,}/.test(parsed.data)) {
+      throw new HTTPException(400, { message: `${name} supports at most millisecond precision` });
+    }
+    return new Date(parsed.data);
+  };
+  const updatedFrom = parseDateBound("updatedFrom");
+  const updatedBefore = parseDateBound("updatedBefore");
+  const createdFrom = parseDateBound("createdFrom");
+  const createdBefore = parseDateBound("createdBefore");
+  if (updatedFrom && updatedBefore && updatedFrom >= updatedBefore) {
+    throw new HTTPException(400, { message: "updatedFrom must be earlier than updatedBefore" });
+  }
+  if (createdFrom && createdBefore && createdFrom >= createdBefore) {
+    throw new HTTPException(400, { message: "createdFrom must be earlier than createdBefore" });
+  }
+  // The opaque end-user label filter is an exact pair: one half alone is a
+  // client error rather than a silently unfiltered list.
+  if (query.endUserSource !== undefined || query.endUserId !== undefined) {
+    throw new HTTPException(400, {
+      message: "Use canonical scopeSubjectId, not an external-user label",
+    });
+  }
+  let scopeSubjectId: SessionScopeSubjectId | undefined;
+  if (query.scopeSubjectId !== undefined) {
+    const parsedEndUser = SessionScopeSubjectId.safeParse(query.scopeSubjectId);
+    if (!parsedEndUser.success) {
+      throw new HTTPException(400, {
+        message: "scopeSubjectId must be a canonical Opengeni user subject",
+      });
+    }
+    scopeSubjectId = parsedEndUser.data;
+  }
+  const hasPageFilters =
+    needsYouOnly ||
+    originSiteId !== undefined ||
+    channelId !== undefined ||
+    createdByKind !== undefined ||
+    updatedFrom !== undefined ||
+    updatedBefore !== undefined ||
+    createdFrom !== undefined ||
+    createdBefore !== undefined ||
+    scopeSubjectId !== undefined;
   if (pinsOnly && !allowCursor) {
     throw new HTTPException(400, { message: 'pinsOnly requires view="page"' });
   }
-  if (pinsOnly && (rawCursor || parentSessionId !== undefined || search)) {
+  if (pinsOnly && (rawCursor || parentSessionId !== undefined || search || hasPageFilters)) {
     throw new HTTPException(400, {
-      message: "pinsOnly cannot be combined with cursor, parentSessionId, or search",
+      message: "pinsOnly cannot be combined with cursor, parentSessionId, search, or filters",
     });
   }
+  if (pinsOnly && archivedOnly) {
+    throw new HTTPException(400, { message: "pinsOnly cannot be combined with archivedOnly" });
+  }
   return {
     limit: query.limit,
+    originSiteId,
     parentSessionId:
       parentSessionId === undefined
         ? undefined
@@ -3732,17 +5454,40 @@ function sessionListQuery(
     cursor,
     search: search || undefined,
     pinsOnly,
+    includePinned,
+    includeTotals,
+    needsYouOnly,
+    archivedOnly,
+    sortBy: sortBy.data,
+    archiveStatus: archiveStatus.data,
+    channelId: channelId === undefined ? undefined : channelId === "null" ? null : channelId,
+    createdBy:
+      createdByKind && createdBySubjectId
+        ? { kind: createdByKind, subjectId: createdBySubjectId }
+        : undefined,
+    updatedFrom,
+    updatedBefore,
+    createdFrom,
+    createdBefore,
+    scopeSubjectId,
+    hasPageFilters,
   };
 }
 
 export type AgentTopologyCursorEnvelope = {
   cursor: SessionDiscoveryCursor;
-  parentSessionId: string | null;
-  search: string | null;
+  parentSessionId: string | null | "all";
+  rootSessionId: string | null;
+  query: string | null;
+  statuses: SessionStatus[];
+  activeOnly: boolean;
+  recentHours: number | null;
+  subject: WorkClaimSubjectFilter | null;
+  claimLimit: number | null;
 };
 
 export function encodeAgentTopologyCursor(value: AgentTopologyCursorEnvelope): string {
-  return Buffer.from(JSON.stringify({ v: 1, ...value }), "utf8").toString("base64url");
+  return Buffer.from(JSON.stringify({ v: 2, ...value }), "utf8").toString("base64url");
 }
 
 function decodeAgentTopologyCursor(value: string): AgentTopologyCursorEnvelope {
@@ -3752,25 +5497,92 @@ function decodeAgentTopologyCursor(value: string): AgentTopologyCursorEnvelope {
     });
   }
   try {
-    const parsed = z
+    const decoded = JSON.parse(Buffer.from(value, "base64url").toString("utf8")) as unknown;
+    const legacy = z
       .object({
         v: z.literal(1),
         parentSessionId: z.string().uuid().nullable(),
-        search: z.string().max(200).nullable(),
+        search: z.string().max(WORK_DISCOVERY_QUERY_MAX_CHARS).nullable(),
+        cursor: z.object({
+          orderBy: z.literal("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.null(),
+        }),
+      })
+      .safeParse(decoded);
+    if (legacy.success) {
+      if (legacy.data.search !== null) {
+        throw new Error("legacy search cursor is not relevance-fenced");
+      }
+      const cursor = {
+        ...legacy.data.cursor,
+        sortRank: null,
+        filterHash: null,
+      } satisfies SessionDiscoveryCursor;
+      return {
+        cursor,
+        parentSessionId: legacy.data.parentSessionId,
+        rootSessionId: null,
+        query: null,
+        statuses: [],
+        activeOnly: false,
+        recentHours: null,
+        subject: null,
+        claimLimit: null,
+      };
+    }
+    const parsed = z
+      .object({
+        v: z.literal(2),
+        parentSessionId: z.union([z.string().uuid(), z.literal("all"), z.null()]),
+        rootSessionId: z.string().uuid().nullable(),
+        query: z.string().max(WORK_DISCOVERY_QUERY_MAX_CHARS).nullable(),
+        statuses: z
+          .array(
+            z.enum([
+              "queued",
+              "running",
+              "idle",
+              "requires_action",
+              "recovering",
+              "waiting_capacity",
+              "failed",
+              "cancelled",
+            ]),
+          )
+          .max(8),
+        activeOnly: z.boolean(),
+        recentHours: z.number().int().positive().max(WORK_DISCOVERY_RECENT_HOURS_MAX).nullable(),
+        subject: z
+          .object({
+            namespace: z.string().min(1).max(WORK_CLAIM_NAMESPACE_MAX_BYTES),
+            type: WorkClaimSubjectType,
+            canonicalKey: z.string().min(1).max(WORK_CLAIM_CANONICAL_KEY_MAX_BYTES),
+          })
+          .strict()
+          .nullable(),
+        claimLimit: z.number().int().positive().max(WORK_CLAIM_DISCOVERY_LIMIT).nullable(),
         cursor: z.object({
-          orderBy: z.enum(["createdAt", "updatedAt"]),
+          orderBy: z.enum(["updatedAt", "relevance"]),
+          sortRank: z.number().int().nonnegative().nullable(),
           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(),
+          updatedAfter: z.null(),
+          filterHash: z
+            .string()
+            .regex(/^[0-9a-f]{64}$/)
+            .nullable(),
         }),
       })
-      .parse(JSON.parse(Buffer.from(value, "base64url").toString("utf8")));
+      .parse(decoded);
     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 ||
@@ -3780,6 +5592,14 @@ function decodeAgentTopologyCursor(value: string): AgentTopologyCursorEnvelope {
     ) {
       throw new Error("invalid topology cursor fields");
     }
+    if (
+      (parsed.cursor.orderBy === "relevance" &&
+        (parsed.cursor.sortRank === null || parsed.cursor.filterHash === null)) ||
+      (parsed.cursor.orderBy === "updatedAt" &&
+        (parsed.cursor.sortRank !== null || parsed.cursor.filterHash !== null))
+    ) {
+      throw new Error("invalid topology cursor relevance fields");
+    }
     return parsed;
   } catch {
     throw new HTTPException(400, {
@@ -3790,8 +5610,14 @@ function decodeAgentTopologyCursor(value: string): AgentTopologyCursorEnvelope {
 
 export function agentTopologyQuery(query: Record<string, string>): {
   limit: number;
-  parentSessionId: string | null;
-  search: string | undefined;
+  parentSessionId: string | null | undefined;
+  rootSessionId: string | undefined;
+  query: string | undefined;
+  statuses: SessionStatus[] | undefined;
+  activeOnly: boolean;
+  recentHours: number | undefined;
+  subject: WorkClaimSubjectFilter | undefined;
+  claimLimit: number | undefined;
   cursor: SessionDiscoveryCursor | undefined;
 } {
   const rawLimit = query.limit;
@@ -3811,22 +5637,141 @@ export function agentTopologyQuery(query: Record<string, string>): {
       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) {
+  const rootSessionId = query.rootSessionId?.trim();
+  if (rootSessionId && !z.string().uuid().safeParse(rootSessionId).success) {
+    throw new HTTPException(400, { message: "rootSessionId must be a session id" });
+  }
+  const normalizeSearchQuery = (value: string | undefined): string | undefined => {
+    if (value === undefined) return undefined;
+    const canonical = value.normalize("NFKC");
+    if (/[\u0000-\u001f\u007f-\u009f]/u.test(canonical)) {
+      throw new HTTPException(400, { message: "query must not contain control characters" });
+    }
+    const normalized = canonical.trim().replace(/\s+/gu, " ").toLowerCase();
+    if (!normalized) return undefined;
+    if (Array.from(normalized).length > WORK_DISCOVERY_QUERY_MAX_CHARS) {
+      throw new HTTPException(400, {
+        message: `query must be at most ${WORK_DISCOVERY_QUERY_MAX_CHARS} characters`,
+      });
+    }
+    return normalized;
+  };
+  const requestedQuery = normalizeSearchQuery(query.query);
+  const legacySearch = normalizeSearchQuery(query.search);
+  const searchQuery = requestedQuery ?? legacySearch;
+  if (requestedQuery && legacySearch && requestedQuery !== legacySearch) {
+    throw new HTTPException(400, { message: "query and legacy search must match" });
+  }
+  const statuses = query.statuses
+    ? [
+        ...new Set(
+          query.statuses
+            .split(",")
+            .map((status) => status.trim())
+            .filter(Boolean),
+        ),
+      ].sort()
+    : [];
+  const parsedStatuses = z
+    .array(
+      z.enum([
+        "queued",
+        "running",
+        "idle",
+        "requires_action",
+        "recovering",
+        "waiting_capacity",
+        "failed",
+        "cancelled",
+      ]),
+    )
+    .max(8)
+    .safeParse(statuses);
+  if (!parsedStatuses.success) {
+    throw new HTTPException(400, { message: "statuses contains an unsupported lifecycle state" });
+  }
+  const activeOnly = query.activeOnly === "true";
+  if (
+    query.activeOnly !== undefined &&
+    query.activeOnly !== "true" &&
+    query.activeOnly !== "false"
+  ) {
+    throw new HTTPException(400, { message: "activeOnly must be true or false" });
+  }
+  const recentHours = query.recentHours === undefined ? undefined : Number(query.recentHours);
+  if (
+    recentHours !== undefined &&
+    (!Number.isSafeInteger(recentHours) ||
+      recentHours < 1 ||
+      recentHours > WORK_DISCOVERY_RECENT_HOURS_MAX)
+  ) {
     throw new HTTPException(400, {
-      message: "search must be at most 200 characters",
+      message: `recentHours must be an integer between 1 and ${WORK_DISCOVERY_RECENT_HOURS_MAX}`,
+    });
+  }
+  const subjectFields = [query.subjectNamespace, query.subjectType, query.subjectKey];
+  if (subjectFields.some((value) => value !== undefined) && subjectFields.some((value) => !value)) {
+    throw new HTTPException(400, {
+      message: "subjectNamespace, subjectType, and subjectKey must be supplied together",
     });
   }
-  if (search && rawParent !== undefined) {
+  const parsedSubject = subjectFields.every((value) => value !== undefined)
+    ? WorkClaimSubjectFilterSchema.safeParse({
+        namespace: normalizeWorkClaimNamespace(query.subjectNamespace!),
+        type: query.subjectType,
+        canonicalKey: normalizeWorkClaimCanonicalKey(query.subjectKey!),
+      })
+    : null;
+  if (parsedSubject && !parsedSubject.success) {
+    throw new HTTPException(400, { message: "exact subject filter is invalid" });
+  }
+  const subject = parsedSubject?.success ? parsedSubject.data : undefined;
+  if (searchQuery && subject) {
+    throw new HTTPException(400, { message: "query cannot be combined with an exact subject" });
+  }
+  const relevanceRequested = Boolean(searchQuery || subject);
+  // An explicit root scopes the whole workstream; only an explicit parent
+  // narrows it to one level. Ordinary browse still defaults to root sessions.
+  const parentSessionId =
+    rawParent === undefined
+      ? relevanceRequested || Boolean(rootSessionId)
+        ? undefined
+        : null
+      : rawParent === "null"
+        ? null
+        : rawParent;
+  const claimLimit = query.claimLimit === undefined ? undefined : Number(query.claimLimit);
+  if (
+    claimLimit !== undefined &&
+    (!Number.isSafeInteger(claimLimit) || claimLimit < 1 || claimLimit > WORK_CLAIM_DISCOVERY_LIMIT)
+  ) {
     throw new HTTPException(400, {
-      message: "search cannot be combined with parentSessionId",
+      message: `claimLimit must be an integer between 1 and ${WORK_CLAIM_DISCOVERY_LIMIT}`,
     });
   }
   const envelope = query.cursor ? decodeAgentTopologyCursor(query.cursor) : undefined;
+  const expectedEnvelope = {
+    parentSessionId: parentSessionId === undefined ? "all" : parentSessionId,
+    rootSessionId: rootSessionId ?? null,
+    query: searchQuery || null,
+    statuses: parsedStatuses.data,
+    activeOnly,
+    recentHours: recentHours ?? null,
+    subject: subject ?? null,
+    claimLimit: claimLimit ?? null,
+  };
   if (
     envelope &&
-    (envelope.parentSessionId !== parentSessionId || envelope.search !== (search || null))
+    JSON.stringify({
+      parentSessionId: envelope.parentSessionId,
+      rootSessionId: envelope.rootSessionId,
+      query: envelope.query,
+      statuses: envelope.statuses,
+      activeOnly: envelope.activeOnly,
+      recentHours: envelope.recentHours,
+      subject: envelope.subject,
+      claimLimit: envelope.claimLimit,
+    }) !== JSON.stringify(expectedEnvelope)
   ) {
     throw new HTTPException(400, {
       message: "agent topology cursor does not match its filters",
@@ -3835,7 +5780,13 @@ export function agentTopologyQuery(query: Record<string, string>): {
   return {
     limit,
     parentSessionId,
-    search: search || undefined,
+    rootSessionId: rootSessionId || undefined,
+    query: searchQuery || undefined,
+    statuses: parsedStatuses.data.length > 0 ? parsedStatuses.data : undefined,
+    activeOnly,
+    recentHours,
+    subject,
+    claimLimit,
     cursor: envelope?.cursor,
   };
 }
@@ -3865,11 +5816,57 @@ 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 UnsupportedLatencyModeError) {
+    return c.json(
+      {
+        code: "SESSION_CREATE_REJECTED",
+        message: error.message,
+        details: {
+          code: error.code,
+          modelId: error.modelId,
+          latencyMode: error.latencyMode,
+          allowedLatencyModes: [...error.allowedLatencyModes],
+        },
+      },
+      422,
+    );
+  }
+  if (error instanceof SessionCreateConnectionSelectionUnavailableError) {
+    return c.json({ code: error.code, message: error.message, retryable: false }, 409);
+  }
+  if (error instanceof SessionTenancyManagedHumanRequiredError) {
+    return c.json(
+      {
+        code: "SESSION_CREATE_FORBIDDEN",
+        message: "Only managed-account users can create an Only-me session.",
+      },
+      403,
+    );
+  }
+  if (error instanceof SessionTenancyNotActivatedError) {
+    return c.json(
+      {
+        code: "SESSION_TENANCY_NOT_ACTIVATED",
+        message: "Private sessions are not enabled for this organization.",
+      },
+      409,
+    );
+  }
   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 SessionVariableSetSelectionUnavailableError) {
+    return c.json(
+      {
+        code: "SESSION_CREATE_REJECTED",
+        message: error.message,
+        details: { variableSetIds: error.variableSetIds },
+      },
+      422,
+    );
+  }
   if (error instanceof SessionSpawnDeniedError) {
     return c.json(
       sessionSpawnDenialEnvelope(error),
@@ -3885,6 +5882,38 @@ export function sessionCreateErrorResponse(c: Context, error: unknown): Response
       422,
     );
   }
+  if (
+    error instanceof HTTPException &&
+    error.status === 409 &&
+    error.cause instanceof NewSessionDraftConflictError
+  ) {
+    return c.json(
+      {
+        code: "NEW_SESSION_DRAFT_CONFLICT",
+        message: error.cause.message,
+        currentRevision: error.cause.currentRevision,
+      },
+      409,
+    );
+  }
+  if (
+    error instanceof HTTPException &&
+    error.status === 422 &&
+    error.cause instanceof AgentConfigError
+  ) {
+    // Typed agent-configuration failure: the specific code is details.code.
+    return c.json(
+      {
+        code: "SESSION_CREATE_REJECTED",
+        message: error.message,
+        details: {
+          code: error.cause.code,
+          ...(error.cause.capability ? { capability: error.cause.capability } : {}),
+        },
+      },
+      422,
+    );
+  }
   if (error instanceof HTTPException && error.status === 422) {
     return c.json(
       {
@@ -3894,6 +5923,15 @@ export function sessionCreateErrorResponse(c: Context, error: unknown): Response
       422,
     );
   }
+  if (error instanceof HTTPException && error.status === 409) {
+    return c.json(
+      {
+        code: "SESSION_CREATE_CONFLICT",
+        message: error.message,
+      },
+      409,
+    );
+  }
   throw error;
 }
 
@@ -3943,18 +5981,20 @@ function commandConflictResponse(c: Context, error: unknown): Response {
 type EffectivePolicyContext = {
   workspaceServerIds: string[];
   workspaceDefaultServerIds: string[];
+  effectiveToolsContext: Awaited<ReturnType<typeof workspaceSessionEffectiveToolsContext>>;
 };
 
 async function loadEffectivePolicyContext(
   deps: ApiRouteDeps,
   workspaceId: string,
   subjectId: string,
+  sessions: readonly Session[],
 ): Promise<EffectivePolicyContext> {
-  const [workspaceServerIds, workspaceDefaultServerIds] = await Promise.all([
-    workspaceSessionToolPolicyServerIds(deps.db, workspaceId, deps.settings, subjectId),
-    workspaceSessionToolPolicyDefaultServerIds(deps.db, workspaceId, deps.settings, subjectId),
+  const [policy, effectiveToolsContext] = await Promise.all([
+    workspaceSessionToolPolicyContext(deps.db, workspaceId, deps.settings, subjectId),
+    workspaceSessionEffectiveToolsContext(deps, workspaceId, subjectId, sessions),
   ]);
-  return { workspaceServerIds, workspaceDefaultServerIds };
+  return { ...policy, effectiveToolsContext };
 }
 
 async function withEffectivePolicy(
@@ -3963,11 +6003,12 @@ async function withEffectivePolicy(
   subjectId: string,
   session: Session,
 ): Promise<Session> {
-  const policy = await loadEffectivePolicyContext(deps, workspaceId, subjectId);
+  const policy = await loadEffectivePolicyContext(deps, workspaceId, subjectId, [session]);
   return sessionWithEffectiveToolPolicy(
     session,
     policy.workspaceServerIds,
     policy.workspaceDefaultServerIds,
+    policy.effectiveToolsContext,
   );
 }
 
@@ -3978,6 +6019,7 @@ function mapLineageNodes(nodes: LineageNode[], policy: EffectivePolicyContext):
       node.session as Session,
       policy.workspaceServerIds,
       policy.workspaceDefaultServerIds,
+      policy.effectiveToolsContext,
     ),
     children: mapLineageNodes(node.children, policy),
   }));