@opengeni/api-router 0.30.3 → 2.2.0-canary.0

package/src/routes/sessions.ts

@@ -1,6 +1,9 @@
 import {
   AcknowledgeStreamRequest,
   ApplySessionGoalRevisionRequest,
+  ListSessionGoalRevisionsQuery,
+  RejectSessionGoalRevisionRequest,
+  RollbackSessionGoalRevisionRequest,
   ActivateCodexRealtimeConnectionRequest,
   AttachViewerRequest,
   BeginSessionRealtimeRequest,
@@ -19,6 +22,7 @@ import {
   FsMoveRequest,
   FsReadRequest,
   FsWriteRequest,
+  ForkSessionRequest,
   HumanInputRequestStatus,
   GitDiffRequest,
   GitReadBatchRequest,
@@ -30,6 +34,7 @@ import {
   PtyOpenRequest,
   PtyResizeRequest,
   PtyWriteRequest,
+  PublishSandboxFileArtifactRequest,
   RenewSessionRealtimeRequest,
   SyncSessionRealtimeLedgerRequest,
   SessionControlRequest,
@@ -45,14 +50,18 @@ import {
   compactSessionEventResult,
   sessionEventLatestClassToSemanticClass,
   SaveComposerDraftRequest,
+  SubmitComposerDraftRequest,
   SteerSessionQueueItemRequest,
   SteerSessionMessageRequest,
   TerminalExecRequest,
   UpdateSessionChannelRequest,
+  UpdateSessionAttentionRequest,
+  UpdateSessionArchiveRequest,
   UpdateSessionPinRequest,
   UpdateSessionGoalRequest,
   UpdateSessionMcpApprovalPolicyRequest,
   UpdateSessionRequest,
+  UpdateSessionVisibilityRequest,
   UpdateSessionToolPolicyRequest,
   ViewerHeartbeatRequest,
   WORKSPACE_CONTROL_ACTOR_MAX_BYTES,
@@ -73,15 +82,18 @@ import {
 } from "@opengeni/contracts";
 import { streamTokenDegraded } from "@opengeni/config";
 import {
+  recordAuditEvent,
   acceptSessionApprovalDecision,
   acceptSessionHumanInputResponse,
   clearSessionGoal,
   clearSessionContext,
   getOpenPtySession,
   getEnrollment,
+  getLiveEnrollmentConnection,
   getRetainedProcess,
   getSandbox,
   getSession,
+  deleteSessionTreeIfQuiescent,
   getSessionEvent,
   getSessionForSubject,
   getSessionGoal,
@@ -93,7 +105,9 @@ import {
   insertPtySession,
   listSessionEventPage,
   listSessionHumanInputRequests,
+  listSessionGoalRevisionPage,
   listSessionGoalRevisions,
+  rejectSessionGoalRevisionWithEvent,
   listSessionIdsInGroup,
   listSessionDiscoverySummaries,
   listSessionDiscoveryAncestorPaths,
@@ -108,13 +122,16 @@ import {
   withSessionCodexCapacityMutation,
   setSessionChannel,
   ChannelNotFoundError,
+  setSessionAttention,
+  setSessionArchive,
   setSessionPin,
+  SessionAttentionVersionConflictError,
+  SessionArchiveVersionConflictError,
   SessionPinVersionConflictError,
   SessionPinAccessError,
   SessionListAccessError,
   SessionListCursorError,
   SessionListCursorExpiredError,
-  SessionListSnapshotLimitError,
   decodeSessionListCursor,
   revokeViewer,
   setSessionGoalStatusWithEvent,
@@ -133,6 +150,11 @@ import {
   SessionRealtimeConflictError,
   SessionToolPolicyVersionConflictError,
   SessionContextBusyError,
+  workspaceControlRequestLockTimeoutMs,
+  SessionTenancyAccessError,
+  SessionTenancyConflictError,
+  SessionTenancyInvalidRequestError,
+  SessionTenancyNotActivatedError,
   HumanInputResponseValidationError,
   latestWorkspaceCapture,
   sessionLatestWorkspaceCapture,
@@ -149,6 +171,11 @@ import {
   type SessionDiscoveryCursor,
   type SessionDiscoveryAncestor,
 } from "@opengeni/db";
+import {
+  backgroundCommandActivityForSessions,
+  listSessionBackgroundCommands,
+  requestSessionBackgroundCommandCancellation,
+} from "@opengeni/db/session-background-commands";
 import {
   appendAndPublishEvents,
   boundSessionEventHttpPage,
@@ -173,6 +200,7 @@ import {
   NatsControlRpc,
   negotiateCapabilities,
   negotiateSelfhostedCapabilities,
+  selectBackend,
   SelfhostedSession,
 } from "@opengeni/runtime/sandbox";
 import type { Context, Hono, MiddlewareHandler } from "hono";
@@ -181,6 +209,8 @@ import type { ContentfulStatusCode } from "hono/utils/http-status";
 import {
   hasPermission,
   requireAccessGrant,
+  requireAccessGrantAuthorization,
+  requireFreshAccessGrant,
   requirePermission,
   requireSessionAuthorization,
   requireSessionAuthorizationListScope,
@@ -188,6 +218,8 @@ import {
   SESSION_AUTHORIZATION_DEFAULT_REAUTHORIZE_MS,
   SessionAuthorizationDeniedError,
   SessionAuthorizationUnavailableError,
+  SessionTenancyManagedHumanRequiredError,
+  SessionTenancyPersistenceOutcomeUnknownError,
   type ResolvedSessionAuthorization,
 } from "@opengeni/core";
 import type { ApiRouteDeps } from "@opengeni/core";
@@ -207,12 +239,15 @@ import {
 import { buildSessionCodexRealtimeBroker, CodexRealtimeBrokerError } from "../codex-realtime";
 import {
   acceptSessionUserMessage,
+  acceptSessionUserMessageWithOutcome,
   controlHumanSessionWorkstream,
   createSessionForRequest,
   deleteHumanQueuePrompt,
   editHumanQueuePrompt,
   getActorNewSessionDraft,
+  getManagedHumanSessionCreateCapabilities,
   getHumanComposerDraft,
+  forkManagedHumanSession,
   moveHumanQueuePrompt,
   readSessionLineage,
   saveHumanComposerDraft,
@@ -221,6 +256,7 @@ import {
   sessionSpawnDenialEnvelope,
   steerHumanQueuePrompt,
   updateSessionMcpApprovalPolicy,
+  updateManagedHumanSessionVisibility,
   updateSessionToolPolicy,
   updateSessionTitle,
   workflowIdForSession,
@@ -236,11 +272,27 @@ import {
   serveWorkspaceCaptureFile,
   WorkspaceCaptureManifestCache,
 } from "./workspace-capture";
+import { publishSandboxFileArtifact } from "../sandbox-file-artifacts";
+import { ApiHttpError } from "../http/api-error";
 
 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))
@@ -406,6 +458,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, {
@@ -434,9 +496,26 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
       : {}),
   };
 
+  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 requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "sessions:create",
+    );
+    const grant = authorization.grant;
     let payload: unknown;
     try {
       payload = await c.req.json();
@@ -451,7 +530,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     }
     let session: Session;
     try {
-      session = await createSessionForRequest(deps, grant, workspaceId, payload);
+      session = await createSessionForRequest(deps, grant, workspaceId, payload, authorization);
     } catch (error) {
       return sessionCreateErrorResponse(c, error);
     }
@@ -469,7 +548,13 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
 
   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();
@@ -489,6 +574,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
           grant,
           workspaceId,
           payload,
+          authorization.canonicalManagedHumanSession,
         ),
       );
     } catch (error) {
@@ -517,7 +603,13 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
 
   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");
@@ -535,8 +627,13 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         ...(query.cursor ? { cursor: query.cursor } : {}),
         ...(query.search ? { search: query.search } : {}),
         ...(query.pinsOnly ? { pinsOnly: true } : {}),
+        ...(query.archivedOnly ? { archivedOnly: true } : {}),
         ...(query.parentSessionId !== undefined ? { parentSessionId: query.parentSessionId } : {}),
         ...(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 — for the canonical managed-cookie session that owns it only.
+        personalWorkspaceOwnerException: authorization.canonicalManagedHumanSession,
       });
     } catch (error) {
       if (error instanceof SessionListAccessError) {
@@ -552,10 +649,6 @@ 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
@@ -563,12 +656,19 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     // 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 decorate = (session: Session): Session => {
+      const activity = commandActivity.get(session.id);
+      return sessionWithEffectiveToolPolicy(
+        { ...session, ...(activity ? { backgroundCommandActivity: activity } : {}) },
         policy.workspaceServerIds,
         policy.workspaceDefaultServerIds,
       );
+    };
     if (pageView) {
       return c.json({
         ...page,
@@ -681,6 +781,99 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     return c.json(await withEffectivePolicy(deps, workspaceId, grant.subjectId, session));
   });
 
+  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,
+    });
+    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 (
     accountId: string,
     workspaceId: string,
@@ -1299,6 +1492,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
             realtimeId,
             ownerSubjectId: grant.subjectId,
             ...parsed.data,
+            controlLockTimeoutMs: workspaceControlRequestLockTimeoutMs(),
           }),
         );
         await publishRealtimeMutation(grant.accountId, workspaceId, sessionId, result);
@@ -1315,7 +1509,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 +1529,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: authorization.canonicalManagedHumanSession,
         ...parsed.data,
       });
       if (!session) {
@@ -1359,6 +1561,94 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     }
   });
 
+  // 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 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,
+        ...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 grant = await requireAccessGrant(c, deps, workspaceId, "sessions:read");
+    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,
+        ...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");
@@ -1505,6 +1795,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) => {
@@ -1576,6 +1909,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) => {
@@ -1607,6 +1968,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,6 +2001,88 @@ 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 = RejectSessionGoalRevisionRequest.parse(await c.req.json());
+      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 = RollbackSessionGoalRevisionRequest.parse(await c.req.json());
+      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");
@@ -1660,6 +2104,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,
@@ -2021,19 +2469,16 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
       c.req.raw.signal,
       {
         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",
-                });
-              },
-            }
-          : {}),
+        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",
+          });
+        },
       },
     );
   });
@@ -2250,7 +2695,13 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
 
   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 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));
@@ -2263,6 +2714,11 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
       reasoningEffort: payload.reasoningEffort ?? null,
       latencyMode: payload.latencyMode ?? null,
       mcpCredentialUpdates: payload.mcpCredentialUpdates ?? [],
+      connectionAuthorities: payload.connectionAuthorities,
+      ...(payload.personalResourceAttachment
+        ? { personalResourceAttachment: payload.personalResourceAttachment }
+        : {}),
+      authorization,
       delivery: "steer",
       origin: "human",
       ...(payload.controlEtag !== undefined ? { controlEtag: payload.controlEtag } : {}),
@@ -2274,9 +2730,69 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     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 = SubmitComposerDraftRequest.parse(await c.req.json().catch(() => null));
+    let result: Awaited<ReturnType<typeof acceptSessionUserMessageWithOutcome>>;
+    try {
+      result = await acceptSessionUserMessageWithOutcome(deps, grant, workspaceId, sessionId, {
+        text: payload.text,
+        annotations: payload.annotations,
+        modelContext: payload.modelContext ?? null,
+        resources: payload.resources,
+        model: payload.model,
+        reasoningEffort: payload.reasoningEffort,
+        latencyMode: payload.latencyMode,
+        mcpCredentialUpdates: payload.mcpCredentialUpdates ?? [],
+        connectionAuthorities: payload.connectionAuthorities,
+        ...(payload.personalResourceAttachment
+          ? { personalResourceAttachment: payload.personalResourceAttachment }
+          : {}),
+        authorization,
+        delivery: payload.delivery,
+        origin: "human",
+        expectedDraftRevision: payload.expectedDraftRevision,
+        clientEventId: payload.clientEventId,
+        ...(payload.controlEtag ? { controlEtag: payload.controlEtag } : {}),
+      });
+    } catch (error) {
+      return commandConflictResponse(c, error);
+    }
+    if (!result.draft) {
+      throw new Error("Accepted composer draft submission did not return its next draft");
+    }
+    return c.json(
+      {
+        accepted: result.accepted,
+        turn: result.turn,
+        draft: result.draft,
+        receipt: result.receipt,
+        routing: result.routing,
+        interruptionCount: result.interruptionCount,
+        replay: result.replay,
+      },
+      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 =
@@ -2306,6 +2822,11 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         reasoningEffort: event.payload.reasoningEffort ?? null,
         latencyMode: event.payload.latencyMode ?? null,
         mcpCredentialUpdates: event.payload.mcpCredentialUpdates ?? [],
+        connectionAuthorities: event.payload.connectionAuthorities,
+        ...(event.payload.personalResourceAttachment
+          ? { personalResourceAttachment: event.payload.personalResourceAttachment }
+          : {}),
+        authorization,
         ...(event.payload.controlEtag !== undefined
           ? { controlEtag: event.payload.controlEtag }
           : {}),
@@ -2323,6 +2844,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         workspaceId,
         sessionId,
         subjectId: grant.subjectId,
+        respondedByKind: childRequiresActionRespondedByKindForGrant(grant),
         payload: event.payload,
         clientEventId: event.clientEventId ?? null,
       });
@@ -2354,6 +2876,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
           requestId: event.payload.requestId,
           response: event.payload.response,
           respondedBy: grant.subjectId,
+          respondedByKind: childRequiresActionRespondedByKindForGrant(grant),
           clientEventId: event.clientEventId ?? null,
         });
       } catch (error) {
@@ -2481,7 +3004,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(
@@ -2529,12 +3056,19 @@ 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),
+      ]);
       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: liveConnection.workspaceRoot ?? "/",
           controlRpc: new NatsControlRpc(async () => bus.getRequestConnection()),
           relay: relayConfigFromSettings(settings),
           epoch: session.activeEpoch,
@@ -2597,6 +3131,20 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     // place (resolveActiveDesktopTransport), covering BOTH swap directions.
     let responseCapabilities = {
       ...capabilities,
+      FileSystem: {
+        ...capabilities.FileSystem,
+        root: selectBackend(
+          (selfhostedActive
+            ? "selfhosted"
+            : 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 : [],
@@ -2723,7 +3271,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 +3305,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 +3316,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 +3329,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 +3357,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 +3368,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 +3512,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 +3533,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 +3583,21 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     return c.json(out);
   });
 
+  app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/artifacts/publish", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(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,
+        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 +3720,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 +3731,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 +3780,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 +4116,24 @@ 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 === "/tool-policy" && verb === "PUT") return "session.tool_policy.write";
   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 (/^\/background-commands\/[^/]+$/.test(suffix) && verb === "DELETE") {
+    return "session.control";
+  }
   if (suffix === "/codex-account" && verb === "POST") {
     return "session.codex_account.write";
   }
@@ -3554,9 +4169,13 @@ 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;
   }
@@ -3574,6 +4193,9 @@ 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 === "/steer" && verb === "POST") return "session.steer";
   if (suffix === "/human-input-requests" && verb === "GET") {
@@ -3593,6 +4215,7 @@ export function sessionAuthorizationOperationForHttp(
   if (suffix === "/fs/list" || suffix === "/fs/list-batch" || suffix === "/fs/read") {
     return verb === "POST" ? "session.files.read" : null;
   }
+  if (suffix === "/artifacts/publish" && verb === "POST") return "session.files.write";
   if (["/fs/write", "/fs/delete", "/fs/move", "/fs/mkdir"].includes(suffix)) {
     return verb === "POST" ? "session.files.write" : null;
   }
@@ -3621,6 +4244,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 } },
@@ -3682,6 +4369,7 @@ function sessionListQuery(
   cursor: ReturnType<typeof decodeSessionListCursor> | undefined;
   search: string | undefined;
   pinsOnly: boolean;
+  archivedOnly: boolean;
 } {
   const parentSessionId = query.parentSessionId;
   // "null" = roots only; a uuid = children of that session; anything else is
@@ -3713,6 +4401,10 @@ function sessionListQuery(
     });
   }
   const pinsOnly = query.pinsOnly === "true";
+  if (query.archivedOnly !== undefined && query.archivedOnly !== "true") {
+    throw new HTTPException(400, { message: 'archivedOnly must be the literal "true"' });
+  }
+  const archivedOnly = query.archivedOnly === "true";
   if (pinsOnly && !allowCursor) {
     throw new HTTPException(400, { message: 'pinsOnly requires view="page"' });
   }
@@ -3721,6 +4413,9 @@ function sessionListQuery(
       message: "pinsOnly cannot be combined with cursor, parentSessionId, or search",
     });
   }
+  if (pinsOnly && archivedOnly) {
+    throw new HTTPException(400, { message: "pinsOnly cannot be combined with archivedOnly" });
+  }
   return {
     limit: query.limit,
     parentSessionId:
@@ -3732,6 +4427,7 @@ function sessionListQuery(
     cursor,
     search: search || undefined,
     pinsOnly,
+    archivedOnly,
   };
 }
 
@@ -3865,6 +4561,24 @@ 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 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.
@@ -3885,6 +4599,20 @@ 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) {
     return c.json(
       {
@@ -3894,6 +4622,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;
 }