@opengeni/api-router 0.5.7 → 0.7.3

package/src/mcp/server.ts

@@ -1,11 +1,19 @@
 import {
   CreateScheduledTaskRequest,
+  defaultRepositoryMountPath,
+  SESSION_EVENT_RAW_DELTA_TYPES,
+  SessionEventPayloadMode,
+  SessionEventReadDirection,
+  SessionEventReadMode,
+  SessionEventSemanticClass,
+  SessionEventType,
   SessionMcpCredentialUpdateInput,
   VariableSetVariableName,
   type AccessGrant,
   type GitHubRepository,
   type Permission,
   type ResourceRef,
+  type SessionAuthorizationOperation,
   UpdateScheduledTaskRequest,
 } from "@opengeni/contracts";
 import {
@@ -21,12 +29,18 @@ import {
   getSessionTurn,
   getVariableSet,
   getVariableSetByName,
-  listGitHubInstallationIdsForWorkspace,
+  areGitHubRepositoriesAllowedForWorkspace,
   listScheduledTaskRuns,
   listScheduledTasks,
-  listSessionEvents,
-  listSessions,
+  listSessionEventPage,
+  listSessionDiscoverySummaries,
+  projectEffectiveControlForRelatedAccess,
+  projectSessionForRelatedAccess,
+  type SessionDiscoveryCursor,
+  type SessionDiscoveryOrderBy,
   listRigs,
+  listRigChangeMonitoringSummaries,
+  listRigVersionMonitoringSummaries,
   listSocialConnections,
   listSocialPosts,
   listVariableSets,
@@ -38,6 +52,7 @@ import {
   requireSession,
   saveWorkspaceMemory,
   searchWorkspaceMemories,
+  serializeEffectiveSessionControl,
   setSessionGoalStatus,
   setVariableSetVariable,
   updateScheduledTask,
@@ -49,20 +64,21 @@ import {
 import { appendAndPublishEvents } from "@opengeni/events";
 import {
   createGitHubAppInstallationToken,
-  createSignedState,
   GitHubAppConfigurationError,
   githubAppMissingSettings,
-  listGitHubAppRepositories,
-  stateMaxAgeSeconds,
 } from "@opengeni/github";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z4 from "zod/v4";
-import { hasPermission } from "@opengeni/core";
+import {
+  hasPermission,
+  requireSessionAuthorization,
+  requireSessionAuthorizationListScope,
+  type ResolvedSessionAuthorization,
+} from "@opengeni/core";
 import { recordWorkspaceUsage, requireLimit } from "@opengeni/core";
 import type { ApiRouteDeps } from "@opengeni/core";
+import { listWorkspaceGitHubRepositories } from "../github-access";
 import {
-  listRigChangesForApi,
-  listRigVersionsForApi,
   promoteVerifiedDefinitionEditChangeForApi,
   proposeRigChangeForApi,
   requireRigChangeForApi,
@@ -103,13 +119,18 @@ import {
   type FleetServices,
   type RunOnOp,
 } from "@opengeni/core";
-import { capEventPage, capSessionDetail } from "./session-view";
+import {
+  boundSessionEventMcpPage,
+  boundSessionDetailMcp,
+  boundRigDetailMcp,
+  SESSION_EVENT_MCP_MAX_BYTES,
+} from "./session-view";
 import type { ToolspaceMcpSurface } from "./toolspace";
 
 export type McpServerOptions = {
-  // Origin of the HTTP request that reached the MCP route; last-resort base
-  // for links the server mints (github_connect_link) when neither
-  // OPENGENI_PUBLIC_BASE_URL nor the manifest base URL is configured.
+  // Origin of the HTTP request that reached the MCP route. Retained in the
+  // options ABI for browser-oriented tools; github_connect_link does not use
+  // it or mint state while new installation binding is disabled.
   requestOrigin?: string | null;
   toolspace?: ToolspaceMcpSurface | null;
   workspaceMemoryEnabled?: boolean | undefined;
@@ -148,8 +169,13 @@ export function buildOpenGeniMcpServer(
         inputSchema: { title: z4.string().min(1).max(200) },
       },
       async ({ title }) => {
-        const result = await updateSessionTitle(deps, grant.workspaceId, sessionId, title, "agent");
-        return json({ ok: true, updated: result.updated, title: result.title ?? title });
+        await authorizeFirstPartySession(deps, grant, sessionId, "session.title.write");
+        const result = await updateSessionTitle(deps, grant, sessionId, title, "agent");
+        return json({
+          ok: true,
+          updated: result.updated,
+          title: result.title ?? title,
+        });
       },
     );
   }
@@ -178,19 +204,20 @@ export function buildOpenGeniMcpServer(
     registerRigTools(server, deps, grant, can, sessionId, json);
   }
 
-  // Orchestration, variableSet, and GitHub-connect tools are permission-gated
+  // Orchestration, variableSet, and GitHub status/token tools are permission-gated
   // at registration: a grant without the permission does not see the tool.
   // Sandboxed workers reach this server with the first-party delegated
   // permission set (firstPartyMcpPermissions in @opengeni/runtime), which is
   // POWERFUL BY DEFAULT — it carries sessions:*, variable sets:*, and github:use,
-  // so agents can spawn/read sessions, manage variable set variables,
-  // and mint GitHub install links out of the box. A user DEMOTES a specific
+  // so agents can spawn/read sessions, manage variable set variables, inspect
+  // GitHub connection availability, and refresh scoped tokens for already-bound
+  // repositories out of the box. A user DEMOTES a specific
   // session by setting a narrower session.firstPartyMcpPermissions (capped to
   // the creator's own grant); operators still cap what any session can be given.
   registerWorkspaceOrchestrationTools(server, deps, grant, can, sessionId, toolspaceMode, json);
   registerVariableSetTools(server, deps, grant, can, json);
   if (can("github:use")) {
-    registerGitHubConnectTool(server, deps, grant, options, json);
+    registerGitHubConnectTool(server, deps, json);
     // TOKEN-BROKER (B1): the agent-refreshable git token. Session-scoped (keys off the
     // worker-signed sessionId claim so it mints for THIS session's repos), gated on
     // the same github:use capability as github_connect_link.
@@ -214,7 +241,9 @@ export function buildOpenGeniMcpServer(
         if (file.status !== "ready") {
           throw new Error(`file is ${file.status}`);
         }
-        const signed = await deps.objectStorage.createGetUrl({ key: file.objectKey });
+        const signed = await deps.objectStorage.createGetUrl({
+          key: file.objectKey,
+        });
         return json({
           file: {
             id: file.id,
@@ -246,11 +275,7 @@ export function buildOpenGeniMcpServer(
       },
       async ({ limit }) => {
         try {
-          const installationIds = await listGitHubInstallationIdsForWorkspace(
-            deps.db,
-            grant.workspaceId,
-          );
-          const repositories = await listGitHubAppRepositories(deps.settings, { installationIds });
+          const repositories = await listWorkspaceGitHubRepositories(deps, grant.workspaceId);
           const visible = typeof limit === "number" ? repositories.slice(0, limit) : repositories;
           return json({
             repositories: visible.map((repository) =>
@@ -380,7 +405,9 @@ export function buildOpenGeniMcpServer(
         inputSchema: { limit: z4.number().int().positive().optional() },
       },
       async ({ limit }) =>
-        json({ tasks: await listScheduledTasks(deps.db, grant.workspaceId, limit ?? 100) }),
+        json({
+          tasks: await listScheduledTasks(deps.db, grant.workspaceId, limit ?? 100),
+        }),
     );
 
     server.registerTool(
@@ -429,7 +456,11 @@ export function buildOpenGeniMcpServer(
           payload,
           toolsProvided: scheduledTaskToolsProvided(args),
         });
-        await syncCreatedScheduledTask({ db: deps.db, workflowClient: deps.workflowClient, task });
+        await syncCreatedScheduledTask({
+          db: deps.db,
+          workflowClient: deps.workflowClient,
+          task,
+        });
         return json(task);
       },
     );
@@ -526,7 +557,10 @@ export function buildOpenGeniMcpServer(
       {
         description:
           "Trigger a scheduled task immediately. Pass a stable triggerId to make a retried trigger idempotent (one charge, one run).",
-        inputSchema: { id: z4.string().uuid(), triggerId: z4.string().min(1).max(128).optional() },
+        inputSchema: {
+          id: z4.string().uuid(),
+          triggerId: z4.string().min(1).max(128).optional(),
+        },
       },
       async ({ id, triggerId }) => {
         const task = await requireScheduledTask(deps.db, grant.workspaceId, id);
@@ -584,7 +618,10 @@ export function buildOpenGeniMcpServer(
       "scheduled_task_runs_list",
       {
         description: "List runs for a scheduled task.",
-        inputSchema: { taskId: z4.string().uuid(), limit: z4.number().int().positive().optional() },
+        inputSchema: {
+          taskId: z4.string().uuid(),
+          limit: z4.number().int().positive().optional(),
+        },
       },
       async ({ taskId, limit }) =>
         json({
@@ -686,6 +723,7 @@ function registerGoalTools(
       },
     },
     async ({ text, successCriteria, maxAutoContinuations }) => {
+      await authorizeFirstPartySession(deps, grant, sessionId, "session.goal.write");
       await requireSession(deps.db, grant.workspaceId, sessionId);
       const callerTurnId =
         typeof grant.metadata?.["turnId"] === "string"
@@ -730,6 +768,7 @@ function registerGoalTools(
       },
     },
     async ({ text, successCriteria, progressNote }) => {
+      await authorizeFirstPartySession(deps, grant, sessionId, "session.goal.write");
       await requireSession(deps.db, grant.workspaceId, sessionId);
       const existing = await getSessionGoal(deps.db, grant.workspaceId, sessionId);
       if (!existing) {
@@ -767,6 +806,7 @@ function registerGoalTools(
       inputSchema: { evidence: z4.string().min(1) },
     },
     async ({ evidence }) => {
+      await authorizeFirstPartySession(deps, grant, sessionId, "session.goal.write");
       await requireSession(deps.db, grant.workspaceId, sessionId);
       const existing = await getSessionGoal(deps.db, grant.workspaceId, sessionId);
       if (!existing) {
@@ -796,6 +836,7 @@ function registerGoalTools(
       inputSchema: { rationale: z4.string().min(1) },
     },
     async ({ rationale }) => {
+      await authorizeFirstPartySession(deps, grant, sessionId, "session.goal.write");
       await requireSession(deps.db, grant.workspaceId, sessionId);
       const existing = await getSessionGoal(deps.db, grant.workspaceId, sessionId);
       if (!existing) {
@@ -826,7 +867,22 @@ function registerGoalTools(
   );
 }
 
-type JsonResult = (value: unknown) => { content: Array<{ type: "text"; text: string }> };
+type JsonResult = (value: unknown) => {
+  content: Array<{ type: "text"; text: string }>;
+};
+
+async function authorizeFirstPartySession(
+  deps: ApiRouteDeps,
+  grant: AccessGrant,
+  sessionId: string,
+  operation: SessionAuthorizationOperation,
+): Promise<ResolvedSessionAuthorization | null> {
+  return await requireSessionAuthorization(deps, grant, {
+    sessionId,
+    operation,
+    surface: "first_party_mcp",
+  });
+}
 
 const MemoryKindSchema = z4.enum(["preference", "semantic", "procedural", "decision", "episodic"]);
 
@@ -969,7 +1025,11 @@ function registerFleetTools(
   sessionId: string,
   json: JsonResult,
 ): void {
-  const services: FleetServices = { db: deps.db, settings: deps.settings, bus: deps.bus };
+  const services: FleetServices = {
+    db: deps.db,
+    settings: deps.settings,
+    bus: deps.bus,
+  };
 
   // Resolve the session's group sandbox (the default/home fleet member) at
   // call-time via the shared helper (same context the user-authenticated swap
@@ -1026,7 +1086,11 @@ function registerFleetTools(
             workdir: z4.string().optional(),
           }),
           z4.object({ kind: z4.literal("read"), path: z4.string().min(1) }),
-          z4.object({ kind: z4.literal("write"), path: z4.string().min(1), content: z4.string() }),
+          z4.object({
+            kind: z4.literal("write"),
+            path: z4.string().min(1),
+            content: z4.string(),
+          }),
         ]),
       },
     },
@@ -1046,7 +1110,10 @@ function registerFleetTools(
     },
     async ({ kind, name }) =>
       json(
-        await provisionSandbox(services, await fleetContext(), { kind, ...(name ? { name } : {}) }),
+        await provisionSandbox(services, await fleetContext(), {
+          kind,
+          ...(name ? { name } : {}),
+        }),
       ),
   );
 }
@@ -1100,24 +1167,31 @@ function registerRigTools(
     server.registerTool(
       "rig_get",
       {
-        description: "Get a rig, its versions, and recent changes.",
+        description:
+          "Get one rig's bounded active definition plus compact historical version/change summaries. Historical setup scripts, checks, payloads, and verification logs are represented by counts/byte facts rather than copied into model context; use the access-controlled REST detail endpoints for exact retained definitions.",
         inputSchema: {
           rigId: z4.string().uuid(),
+          versionLimit: z4.number().int().positive().optional(),
           changeLimit: z4.number().int().positive().optional(),
         },
       },
-      async ({ rigId, changeLimit }) => {
+      async ({ rigId, versionLimit, changeLimit }) => {
         const rig = await requireRigForApi(deps.db, grant.workspaceId, rigId);
-        return json({
-          rig,
-          versions: await listRigVersionsForApi({ db: deps.db }, grant.workspaceId, rig.id),
-          changes: await listRigChangesForApi(
-            { db: deps.db },
+        const [versions, changes] = await Promise.all([
+          listRigVersionMonitoringSummaries(
+            deps.db,
             grant.workspaceId,
             rig.id,
-            boundedMcpLimit(changeLimit),
+            boundedRigHistoryLimit(versionLimit),
           ),
-        });
+          listRigChangeMonitoringSummaries(
+            deps.db,
+            grant.workspaceId,
+            rig.id,
+            boundedRigHistoryLimit(changeLimit),
+          ),
+        ]);
+        return json(boundRigDetailMcp(rig, versions, changes));
       },
     );
 
@@ -1237,6 +1311,7 @@ function exactAgentCommandContext(
   return {
     accountId: grant.accountId,
     workspaceId: grant.workspaceId,
+    subjectId: grant.subjectId,
     callerSessionId,
     callerTurnId: turnId,
     callerAttemptId: attemptId,
@@ -1257,11 +1332,47 @@ function registerWorkspaceOrchestrationTools(
     server.registerTool(
       "sessions_list",
       {
-        description: "List sessions in this workspace, newest first.",
-        inputSchema: { limit: z4.number().int().positive().optional() },
+        description: `List compact high-level session status in this workspace. Defaults to creation order; use orderBy=updatedAt with decimal activity-revision updatedAfter/updatedThrough tokens for gap-free indexed incremental monitoring independent of application clocks. Cursors are opaque revision-fenced keysets. includeLastMessage is opt-in; its rendered previews share a deterministic ${SESSION_DISCOVERY_PREVIEW_MAX_BYTES}-byte UTF-8 aggregate budget, and omitted previews include a bounded session_events drill-down input (exact message type, direction=before, limit=1, monitoring summary). Use session_get for exact known targets and detailed resources/tools/settings. The list never returns full session objects or history.`,
+        inputSchema: {
+          limit: z4.number().int().positive().max(100).optional(),
+          cursor: z4.string().max(512).optional(),
+          includeLastMessage: z4.boolean().optional(),
+          orderBy: z4.enum(["createdAt", "updatedAt"]).optional(),
+          updatedAfter: z4.string().max(64).optional(),
+        },
+      },
+      async ({ limit, cursor, includeLastMessage, orderBy: requestedOrderBy, updatedAfter }) => {
+        const authorizationScope = await requireSessionAuthorizationListScope(
+          deps,
+          grant,
+          "first_party_mcp",
+        );
+        const decodedCursor = cursor ? decodeSessionDiscoveryCursor(cursor) : undefined;
+        const orderBy: SessionDiscoveryOrderBy =
+          requestedOrderBy ?? decodedCursor?.orderBy ?? "createdAt";
+        if (decodedCursor && decodedCursor.orderBy !== orderBy) {
+          throw new Error("sessions_list cursor order does not match orderBy");
+        }
+        const normalizedUpdatedAfter =
+          updatedAfter !== undefined
+            ? normalizeSessionDiscoveryRevision(updatedAfter, "updatedAfter")
+            : (decodedCursor?.updatedAfter ?? undefined);
+        if (normalizedUpdatedAfter !== undefined && orderBy !== "updatedAt") {
+          throw new Error("sessions_list updatedAfter requires orderBy=updatedAt");
+        }
+        if (decodedCursor && decodedCursor.updatedAfter !== (normalizedUpdatedAfter ?? null)) {
+          throw new Error("sessions_list cursor does not match updatedAfter");
+        }
+        const page = await listSessionDiscoverySummaries(deps.db, grant.workspaceId, {
+          limit: boundedSessionDiscoveryLimit(limit),
+          ...(decodedCursor ? { cursor: decodedCursor } : {}),
+          includeLastMessage: includeLastMessage === true,
+          orderBy,
+          ...(normalizedUpdatedAfter ? { updatedAfter: normalizedUpdatedAfter } : {}),
+          ...(authorizationScope ? { authorizationScope } : {}),
+        });
+        return json(capSessionDiscoveryPage(page, includeLastMessage === true));
       },
-      async ({ limit }) =>
-        json({ sessions: await listSessions(deps.db, grant.workspaceId, boundedMcpLimit(limit)) }),
     );
 
     server.registerTool(
@@ -1272,15 +1383,25 @@ function registerWorkspaceOrchestrationTools(
         inputSchema: { sessionId: z4.string().uuid() },
       },
       async ({ sessionId }) => {
+        const authorization = await authorizeFirstPartySession(
+          deps,
+          grant,
+          sessionId,
+          "session.read",
+        );
         const session = await getSession(deps.db, grant.workspaceId, sessionId);
         if (!session) {
           throw new Error("session not found");
         }
         const queue = await getSessionQueueSnapshot(deps.db, grant.workspaceId, sessionId);
-        return json({
-          ...capSessionDetail(session),
-          effectiveControl: queue?.effectiveControl ?? null,
-        });
+        const projected = projectSessionForRelatedAccess(
+          {
+            ...session,
+            effectiveControl: queue?.effectiveControl ?? session.effectiveControl,
+          },
+          authorization?.relatedSessionAccess ?? "root",
+        );
+        return json(boundSessionDetailMcp(projected));
       },
     );
 
@@ -1288,28 +1409,83 @@ function registerWorkspaceOrchestrationTools(
       "session_events",
       {
         description:
-          "Read a session's event timeline (oldest first), to monitor another session's progress. Pass `after` = the highest event `sequence` already seen to page forward; the response's `nextAfter` is that cursor. The response is BYTE-CAPPED for a monitoring glance: fat per-event payloads (a worker's verbatim tool outputs, message/reasoning bodies) are clamped, and an over-budget page is reduced to its head + tail with a marker — page the gap with `after`/`limit`, or read the worker's session notebook, if you need omitted content verbatim. `nextAfter` always advances past every event the page covered, so paging never skips real events.",
+          "Read a compact semantic tail only when session_get status is insufficient. With no cursor, this returns the newest matching events and excludes raw message/reasoning/command/PTY deltas. Use `latest` as an exclusive lookup for the newest event in exactly one semantic class; it cannot be combined with type or class filters. Use nextBefore to page older or explicit after/nextAfter to page forward. Type/class filters run in the RLS-scoped database query. payloadMode none|summary|full controls retained audit payload projection, but every model result is independently byte-capped with explicit truncation and exact covered sequence bounds. Exact retained forensic payloads require the access-controlled REST/SDK events API with mode=forensic&payloadMode=full; generic source bytes never retained by the audit boundary remain unavailable.",
         inputSchema: {
           sessionId: z4.string().uuid(),
           after: z4.number().int().nonnegative().optional(),
+          before: z4.number().int().positive().optional(),
           limit: z4.number().int().positive().optional(),
+          direction: z4.enum(SessionEventReadDirection.options).optional(),
+          mode: z4.enum(SessionEventReadMode.options).optional(),
+          payloadMode: z4.enum(SessionEventPayloadMode.options).optional(),
+          includeTypes: z4.array(z4.enum(SessionEventType.options)).max(100).optional(),
+          excludeTypes: z4.array(z4.enum(SessionEventType.options)).max(100).optional(),
+          includeClasses: z4
+            .array(z4.enum(SessionEventSemanticClass.options))
+            .max(SessionEventSemanticClass.options.length)
+            .optional(),
+          excludeClasses: z4
+            .array(z4.enum(SessionEventSemanticClass.options))
+            .max(SessionEventSemanticClass.options.length)
+            .optional(),
+          latest: z4.enum(SessionEventSemanticClass.options).optional(),
         },
       },
-      async ({ sessionId, after, limit }) => {
+      async ({
+        sessionId,
+        after,
+        before,
+        limit,
+        direction: requestedDirection,
+        mode: requestedMode,
+        payloadMode: requestedPayloadMode,
+        includeTypes,
+        excludeTypes,
+        includeClasses,
+        excludeClasses,
+        latest,
+      }) => {
+        await authorizeFirstPartySession(deps, grant, sessionId, "session.events.read");
         await requireSession(deps.db, grant.workspaceId, sessionId);
-        const events = await listSessionEvents(
-          deps.db,
-          grant.workspaceId,
-          sessionId,
-          after ?? 0,
-          boundedMcpLimit(limit),
-        );
-        const capped = capEventPage(events);
-        return json({
-          events: capped.events,
-          nextAfter: capped.nextAfter ?? after ?? 0,
-          ...(capped.truncated ? { truncated: true } : {}),
+        if (
+          latest &&
+          [includeTypes, excludeTypes, includeClasses, excludeClasses].some(
+            (filter) => filter !== undefined,
+          )
+        ) {
+          throw new Error("latest cannot be combined with event filters");
+        }
+        const mode = requestedMode ?? (after !== undefined ? "forensic" : "monitoring");
+        const direction = latest
+          ? "before"
+          : (requestedDirection ??
+            (before !== undefined ? "before" : after !== undefined ? "after" : "before"));
+        const payloadMode = requestedPayloadMode ?? (mode === "monitoring" ? "summary" : "full");
+        const dbPage = await listSessionEventPage(deps.db, grant.workspaceId, sessionId, {
+          after: after ?? 0,
+          ...(before !== undefined ? { before } : {}),
+          direction,
+          limit: latest ? 1 : boundedSessionEventMcpLimit(limit),
+          payloadMode,
+          includeTypes: includeTypes ?? [],
+          excludeTypes: excludeTypes ?? [],
+          includeClasses: latest ? [latest] : (includeClasses ?? []),
+          excludeClasses: excludeClasses ?? [],
+          ...(mode === "monitoring" ? { defaultExcludeTypes: SESSION_EVENT_RAW_DELTA_TYPES } : {}),
+          maxBytes: SESSION_EVENT_MCP_MAX_BYTES * 4,
         });
+        return json(
+          boundSessionEventMcpPage({
+            events: dbPage.events,
+            mode,
+            payloadMode,
+            direction,
+            sourceHasMore: dbPage.hasMore,
+            sourceTruncatedBy: dbPage.truncatedBy,
+            after: after ?? 0,
+            before: before ?? null,
+          }),
+        );
       },
     );
   }
@@ -1360,7 +1536,14 @@ function registerWorkspaceOrchestrationTools(
           idempotencyKey: z4.string().min(1).max(200).optional(),
           // First-party MCP token permissions for the spawned session; every
           // permission must be held by this grant (validated in the domain).
-          firstPartyMcpPermissions: z4.array(z4.string()).optional(),
+          // A goal requires goals:manage in the resulting set; it is never
+          // silently added beyond the inherited or explicit authority.
+          firstPartyMcpPermissions: z4
+            .array(z4.string())
+            .optional()
+            .describe(
+              "Optional first-party capability set for the child. Omit to inherit this session's effective permissions. An explicit set may only narrow capabilities held by this session. A goal-bearing child requires goals:manage in the resulting set; creation fails rather than adding it implicitly.",
+            ),
           // Shared-sandbox placement (addendum 05 §D). OMIT (default) to SHARE the
           // creator's box — one filesystem/repo/desktop, N independent conversations;
           // this is the SAFE DEFAULT. Pass "new" for a fresh isolated box (a different
@@ -1394,7 +1577,12 @@ function registerWorkspaceOrchestrationTools(
           // arbitrary session's wake channel without sessions:control on it.
         },
       },
-      async (args) => json(await createSessionForRequest(deps, grant, grant.workspaceId, args)),
+      async (args) => {
+        if (callerSessionId !== null) {
+          await authorizeFirstPartySession(deps, grant, callerSessionId, "session.child.create");
+        }
+        return json(await createSessionForRequest(deps, grant, grant.workspaceId, args));
+      },
     );
   }
 
@@ -1414,6 +1602,7 @@ function registerWorkspaceOrchestrationTools(
         },
       },
       async ({ sessionId: targetSessionId, text, idempotencyKey, mcpCredentialUpdates }) => {
+        await authorizeFirstPartySession(deps, grant, targetSessionId, "session.append");
         if (callerSessionId !== null) {
           if ((mcpCredentialUpdates?.length ?? 0) > 0) {
             throw new Error("internal session updates cannot change MCP credentials");
@@ -1464,6 +1653,12 @@ function registerWorkspaceOrchestrationTools(
         },
       },
       async ({ sessionId, idempotencyKey, reason }) => {
+        const authorization = await authorizeFirstPartySession(
+          deps,
+          grant,
+          sessionId,
+          "session.control",
+        );
         if (callerSessionId !== null) {
           const controlled = await controlAgentSessionWorkstream(
             deps,
@@ -1477,27 +1672,37 @@ function registerWorkspaceOrchestrationTools(
           );
           return json({
             receiptId: controlled.receipt.id,
-            effectiveControl: controlled.control,
+            effectiveControl: projectEffectiveControlForRelatedAccess(
+              serializeEffectiveSessionControl(controlled.control),
+              sessionId,
+              authorization?.relatedSessionAccess ?? "root",
+            ),
             interruptionCount: controlled.interruptionCount,
             replay: controlled.replay,
           });
         }
-        return json(
-          await controlHumanSessionWorkstream(
-            deps,
-            {
-              accountId: grant.accountId,
-              workspaceId: grant.workspaceId,
-              sessionId,
-              subjectId: grant.subjectId,
-            },
-            {
-              action: "pause",
-              clientEventId: idempotencyKey,
-              ...(reason ? { reason } : {}),
-            },
-          ),
+        const controlled = await controlHumanSessionWorkstream(
+          deps,
+          {
+            accountId: grant.accountId,
+            workspaceId: grant.workspaceId,
+            sessionId,
+            subjectId: grant.subjectId,
+          },
+          {
+            action: "pause",
+            clientEventId: idempotencyKey,
+            ...(reason ? { reason } : {}),
+          },
         );
+        return json({
+          ...controlled,
+          effectiveControl: projectEffectiveControlForRelatedAccess(
+            controlled.effectiveControl,
+            sessionId,
+            authorization?.relatedSessionAccess ?? "root",
+          ),
+        });
       },
     );
 
@@ -1513,6 +1718,12 @@ function registerWorkspaceOrchestrationTools(
         },
       },
       async ({ sessionId, idempotencyKey, reason }) => {
+        const authorization = await authorizeFirstPartySession(
+          deps,
+          grant,
+          sessionId,
+          "session.control",
+        );
         if (callerSessionId !== null) {
           const controlled = await controlAgentSessionWorkstream(
             deps,
@@ -1526,27 +1737,37 @@ function registerWorkspaceOrchestrationTools(
           );
           return json({
             receiptId: controlled.receipt.id,
-            effectiveControl: controlled.control,
+            effectiveControl: projectEffectiveControlForRelatedAccess(
+              serializeEffectiveSessionControl(controlled.control),
+              sessionId,
+              authorization?.relatedSessionAccess ?? "root",
+            ),
             interruptionCount: controlled.interruptionCount,
             replay: controlled.replay,
           });
         }
-        return json(
-          await controlHumanSessionWorkstream(
-            deps,
-            {
-              accountId: grant.accountId,
-              workspaceId: grant.workspaceId,
-              sessionId,
-              subjectId: grant.subjectId,
-            },
-            {
-              action: "resume",
-              clientEventId: idempotencyKey,
-              ...(reason ? { reason } : {}),
-            },
-          ),
+        const controlled = await controlHumanSessionWorkstream(
+          deps,
+          {
+            accountId: grant.accountId,
+            workspaceId: grant.workspaceId,
+            sessionId,
+            subjectId: grant.subjectId,
+          },
+          {
+            action: "resume",
+            clientEventId: idempotencyKey,
+            ...(reason ? { reason } : {}),
+          },
         );
+        return json({
+          ...controlled,
+          effectiveControl: projectEffectiveControlForRelatedAccess(
+            controlled.effectiveControl,
+            sessionId,
+            authorization?.relatedSessionAccess ?? "root",
+          ),
+        });
       },
     );
 
@@ -1563,6 +1784,7 @@ function registerWorkspaceOrchestrationTools(
           },
         },
         async ({ sessionId, instruction, idempotencyKey }) => {
+          await authorizeFirstPartySession(deps, grant, sessionId, "session.steer");
           const result = await steerAgentSession(
             deps,
             exactAgentCommandContext(grant, callerSessionId),
@@ -1590,15 +1812,14 @@ function registerWorkspaceOrchestrationTools(
         },
       },
       async ({ session_id, title }) => {
+        await authorizeFirstPartySession(deps, grant, session_id, "session.title.write");
         await requireSession(deps.db, grant.workspaceId, session_id);
-        const result = await updateSessionTitle(
-          deps,
-          grant.workspaceId,
-          session_id,
-          title,
-          "agent",
-        );
-        return json({ ok: true, updated: result.updated, title: result.title ?? title });
+        const result = await updateSessionTitle(deps, grant, session_id, title, "agent");
+        return json({
+          ok: true,
+          updated: result.updated,
+          title: result.title ?? title,
+        });
       },
     );
   }
@@ -1703,7 +1924,11 @@ function registerVariableSetTools(
       variableSetId: variableSet.id,
       variableName: parsedName.data,
     });
-    const responseVariableSet = { id: variableSet.id, name: variableSet.name, created };
+    const responseVariableSet = {
+      id: variableSet.id,
+      name: variableSet.name,
+      created,
+    };
     return json({
       variableSet: responseVariableSet,
       environment: responseVariableSet,
@@ -1750,22 +1975,15 @@ function registerVariableSetTools(
   }
 }
 
-// GitHub connect link for manager-style agents: mirrors GET .../github/app but
-// returns a browser entry URL (.../github/connect) that plants the CSRF state
-// cookie before forwarding to GitHub, because an MCP-issued link is opened in
-// a browser that never called the API directly.
-function registerGitHubConnectTool(
-  server: McpServer,
-  deps: ApiRouteDeps,
-  grant: AccessGrant,
-  options: McpServerOptions,
-  json: JsonResult,
-): void {
+// The tool remains registered for compatibility, but every new installation
+// binding entry point is fail-closed until a provider-supported authority
+// proof stronger than installation visibility is available.
+function registerGitHubConnectTool(server: McpServer, deps: ApiRouteDeps, json: JsonResult): void {
   server.registerTool(
     "github_connect_link",
     {
       description:
-        "Create a workspace-bound GitHub App install link to share with a human. Opening it redirects to GitHub to install the app and select repositories for this workspace; completing the connection requires the person to be signed in to this OpenGeni deployment with github:manage. The link expires.",
+        "Report GitHub App connection availability. New installation binding is disabled until GitHub installation authority can be proven, so installUrl and linkUrl are null.",
       inputSchema: {},
     },
     async () => {
@@ -1773,28 +1991,19 @@ function registerGitHubConnectTool(
       const missing = githubAppMissingSettings(settings);
       const slug = settings.githubAppSlug?.trim() || null;
       if (missing.length > 0 || !slug) {
-        return json({ configured: false, appSlug: slug, installUrl: null, missing });
-      }
-      const base = (
-        settings.publicBaseUrl ??
-        settings.githubAppManifestBaseUrl ??
-        options.requestOrigin ??
-        ""
-      ).replace(/\/+$/, "");
-      if (!base) {
-        throw new Error(
-          "github_connect_link requires OPENGENI_PUBLIC_BASE_URL (or OPENGENI_GITHUB_APP_MANIFEST_BASE_URL) so the install link can route through this deployment",
-        );
+        return json({
+          configured: false,
+          appSlug: slug,
+          installUrl: null,
+          linkUrl: null,
+          missing,
+        });
       }
-      const state = createSignedState(deps.githubStateSecret, {
-        accountId: grant.accountId,
-        workspaceId: grant.workspaceId,
-      });
       return json({
         configured: true,
         appSlug: slug,
-        installUrl: `${base}/v1/workspaces/${grant.workspaceId}/github/connect?state=${encodeURIComponent(state)}`,
-        expiresInSeconds: stateMaxAgeSeconds,
+        installUrl: null,
+        linkUrl: null,
         missing: [],
       });
     },
@@ -1845,9 +2054,20 @@ function registerGitHubTokenTool(
       if (selected.some((item) => item.installationId !== installationId)) {
         throw new Error("GitHub App repository resources must belong to one installation");
       }
+      const repositoryIds = selected.map((item) => item.repositoryId);
+      if (
+        !(await areGitHubRepositoriesAllowedForWorkspace(
+          deps.db,
+          grant.workspaceId,
+          installationId,
+          repositoryIds,
+        ))
+      ) {
+        throw new Error("this workspace no longer authorizes the session's GitHub repositories");
+      }
       const token = await createGitHubAppInstallationToken(deps.settings, {
         installationId,
-        repositoryIds: selected.map((item) => item.repositoryId),
+        repositoryIds,
       });
       return json({
         token,
@@ -1881,9 +2101,12 @@ function repositoryWithScheduledTaskResource(
       kind: "repository",
       uri,
       ref: repository.defaultBranch,
-      mountPath: repositoryMountPath(uri),
+      mountPath: defaultRepositoryMountPath(uri),
       ...(repository.private
-        ? { githubInstallationId: repository.installationId, githubRepositoryId: repository.id }
+        ? {
+            githubInstallationId: repository.installationId,
+            githubRepositoryId: repository.id,
+          }
         : {}),
     },
   };
@@ -1892,12 +2115,7 @@ function repositoryWithScheduledTaskResource(
 function normalizedRepositoryUri(value: string): string {
   const url = new URL(value);
   const path = url.pathname.replace(/^\/+|\/+$/g, "").replace(/\.git$/, "");
-  return `https://${url.hostname.toLowerCase()}/${path}.git`;
-}
-
-function repositoryMountPath(uri: string): string {
-  const url = new URL(uri);
-  return `repos/${url.pathname.replace(/^\/+|\/+$/g, "").replace(/\.git$/, "")}`;
+  return `https://${url.host.toLowerCase()}/${path}.git`;
 }
 
 function boundedMcpLimit(limit: number | undefined): number {
@@ -1907,6 +2125,416 @@ function boundedMcpLimit(limit: number | undefined): number {
   return Math.min(500, Math.max(1, Math.floor(limit)));
 }
 
+function boundedRigHistoryLimit(limit: number | undefined): number {
+  if (!limit || !Number.isFinite(limit)) return 20;
+  return Math.min(100, Math.max(1, Math.floor(limit)));
+}
+
+function boundedSessionEventMcpLimit(limit: number | undefined): number {
+  if (!limit || !Number.isFinite(limit)) return 40;
+  return Math.min(250, Math.max(1, Math.floor(limit)));
+}
+
+const SESSION_DISCOVERY_DEFAULT_LIMIT = 20;
+const SESSION_DISCOVERY_MAX_LIMIT = 100;
+const SESSION_DISCOVERY_TEXT_CHARS = 600;
+const SESSION_DISCOVERY_PREVIEW_MAX_BYTES = 16_384;
+const SESSION_DISCOVERY_PREVIEW_OMISSION_REASON = "aggregatePreviewBudget" as const;
+const SESSION_DISCOVERY_PAGE_MAX_BYTES = 128_000;
+const SESSION_DISCOVERY_PREVIEW_DRILL_DOWN_TOOL = "session_events" as const;
+const SESSION_DISCOVERY_PREVIEW_DRILL_DOWN_BASE_INPUT = {
+  direction: "before",
+  limit: 1,
+  mode: "monitoring",
+  payloadMode: "summary",
+} as const;
+
+function sessionDiscoveryPreviewDrillDownInput(sessionId: string, type: SessionEventType) {
+  return {
+    sessionId,
+    includeTypes: [type],
+    ...SESSION_DISCOVERY_PREVIEW_DRILL_DOWN_BASE_INPUT,
+  };
+}
+
+function boundedSessionDiscoveryLimit(limit: number | undefined): number {
+  if (!limit || !Number.isFinite(limit)) return SESSION_DISCOVERY_DEFAULT_LIMIT;
+  return Math.min(SESSION_DISCOVERY_MAX_LIMIT, Math.max(1, Math.floor(limit)));
+}
+
+export function encodeSessionDiscoveryCursor(cursor: SessionDiscoveryCursor): string {
+  return Buffer.from(
+    JSON.stringify({
+      v: 2,
+      orderBy: cursor.orderBy,
+      sortRevision: cursor.sortRevision,
+      sortAt: cursor.sortAt,
+      id: cursor.id,
+      snapshotAt: cursor.snapshotAt,
+      snapshotRevision: cursor.snapshotRevision,
+      updatedAfter: cursor.updatedAfter,
+    }),
+    "utf8",
+  ).toString("base64url");
+}
+
+const SESSION_DISCOVERY_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,6})?Z$/;
+const SESSION_DISCOVERY_REVISION = /^(?:0|[1-9]\d*)$/;
+const SESSION_DISCOVERY_REVISION_MAX = 9_223_372_036_854_775_807n;
+const SESSION_DISCOVERY_UUID =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+function normalizeSessionDiscoveryTimestamp(value: string, label: string): string {
+  if (!SESSION_DISCOVERY_TIMESTAMP.test(value) || Number.isNaN(new Date(value).getTime())) {
+    throw new Error(`sessions_list ${label} must be an ISO UTC date-time`);
+  }
+  // Preserve up to six fractional digits. Converting through JS Date would
+  // discard PostgreSQL microseconds and can skip equal-millisecond rows.
+  return value;
+}
+
+function normalizeSessionDiscoveryRevision(value: string, label: string): string {
+  if (!SESSION_DISCOVERY_REVISION.test(value)) {
+    throw new Error(`sessions_list ${label} must be a decimal activity revision`);
+  }
+  const revision = BigInt(value);
+  if (revision > SESSION_DISCOVERY_REVISION_MAX) {
+    throw new Error(`sessions_list ${label} exceeds the database activity revision range`);
+  }
+  return revision.toString();
+}
+
+export function decodeSessionDiscoveryCursor(value: string): SessionDiscoveryCursor {
+  try {
+    const parsed = JSON.parse(Buffer.from(value, "base64url").toString("utf8")) as {
+      v?: unknown;
+      orderBy?: unknown;
+      sortRevision?: unknown;
+      sortAt?: unknown;
+      createdAt?: unknown;
+      id?: unknown;
+      snapshotAt?: unknown;
+      snapshotRevision?: unknown;
+      updatedAfter?: unknown;
+    };
+    if (
+      parsed.v === undefined &&
+      typeof parsed.createdAt === "string" &&
+      typeof parsed.id === "string" &&
+      SESSION_DISCOVERY_UUID.test(parsed.id)
+    ) {
+      const createdAt = normalizeSessionDiscoveryTimestamp(
+        parsed.createdAt,
+        "legacy cursor createdAt",
+      );
+      return {
+        orderBy: "createdAt",
+        sortRevision: "0",
+        sortAt: createdAt,
+        id: parsed.id,
+        snapshotAt: createdAt,
+        snapshotRevision: "0",
+        updatedAfter: null,
+      };
+    }
+    // The timestamp-fenced v1 format was never safe for updated-order
+    // continuation. Preserve rolling compatibility only for creation cursors,
+    // whose immutable ordering does not need an activity revision.
+    if (
+      parsed.v === 1 &&
+      parsed.orderBy === "createdAt" &&
+      typeof parsed.sortAt === "string" &&
+      typeof parsed.snapshotAt === "string" &&
+      parsed.updatedAfter === null &&
+      typeof parsed.id === "string" &&
+      SESSION_DISCOVERY_UUID.test(parsed.id)
+    ) {
+      return {
+        orderBy: "createdAt",
+        sortRevision: "0",
+        sortAt: normalizeSessionDiscoveryTimestamp(parsed.sortAt, "cursor sortAt"),
+        id: parsed.id,
+        snapshotAt: normalizeSessionDiscoveryTimestamp(parsed.snapshotAt, "cursor snapshotAt"),
+        snapshotRevision: "0",
+        updatedAfter: null,
+      };
+    }
+    if (
+      parsed.v !== 2 ||
+      (parsed.orderBy !== "createdAt" && parsed.orderBy !== "updatedAt") ||
+      typeof parsed.sortRevision !== "string" ||
+      typeof parsed.sortAt !== "string" ||
+      typeof parsed.snapshotAt !== "string" ||
+      typeof parsed.snapshotRevision !== "string" ||
+      (parsed.updatedAfter !== null && typeof parsed.updatedAfter !== "string") ||
+      typeof parsed.id !== "string" ||
+      !SESSION_DISCOVERY_UUID.test(parsed.id)
+    ) {
+      throw new Error("invalid cursor fields");
+    }
+    const sortAt = normalizeSessionDiscoveryTimestamp(parsed.sortAt, "cursor sortAt");
+    const snapshotAt = normalizeSessionDiscoveryTimestamp(parsed.snapshotAt, "cursor snapshotAt");
+    const sortRevision = normalizeSessionDiscoveryRevision(
+      parsed.sortRevision,
+      "cursor sortRevision",
+    );
+    const snapshotRevision = normalizeSessionDiscoveryRevision(
+      parsed.snapshotRevision,
+      "cursor snapshotRevision",
+    );
+    const normalizedUpdatedAfter =
+      parsed.updatedAfter === null
+        ? null
+        : normalizeSessionDiscoveryRevision(parsed.updatedAfter, "cursor updatedAfter");
+    if (normalizedUpdatedAfter !== null && parsed.orderBy !== "updatedAt") {
+      throw new Error("incremental cursor requires updatedAt order");
+    }
+    if (parsed.orderBy === "createdAt" && (sortRevision !== "0" || snapshotRevision !== "0")) {
+      throw new Error("creation cursor cannot carry activity revisions");
+    }
+    return {
+      orderBy: parsed.orderBy,
+      sortRevision,
+      sortAt,
+      id: parsed.id,
+      snapshotAt,
+      snapshotRevision,
+      updatedAfter: normalizedUpdatedAfter,
+    };
+  } catch {
+    throw new Error("sessions_list cursor is invalid");
+  }
+}
+
+function capSessionDiscoveryText(
+  value: string | null,
+  maxChars = SESSION_DISCOVERY_TEXT_CHARS,
+  originalChars?: number | null,
+) {
+  if (value === null) {
+    return { text: value, truncated: false };
+  }
+  const projectedChars = Array.from(value);
+  const sourceChars = Math.max(projectedChars.length, originalChars ?? projectedChars.length);
+  if (sourceChars <= maxChars) {
+    return { text: value, truncated: false };
+  }
+
+  // The database supplies only a bounded prefix plus the original character
+  // count. Iterate to a stable marker width so the reported omission includes
+  // the characters replaced by the marker itself.
+  let bodyChars = maxChars;
+  let marker = "";
+  for (let attempt = 0; attempt < 4; attempt += 1) {
+    const omittedChars = Math.max(0, sourceChars - bodyChars);
+    marker = `…[${omittedChars} chars truncated]…`;
+    const nextBodyChars = Math.max(0, maxChars - Array.from(marker).length);
+    if (nextBodyChars === bodyChars) break;
+    bodyChars = nextBodyChars;
+  }
+  return {
+    text: `${projectedChars.slice(0, bodyChars).join("")}${marker}`,
+    truncated: true,
+  };
+}
+
+export function capSessionDiscoveryPage(
+  page: Awaited<ReturnType<typeof listSessionDiscoverySummaries>>,
+  includeLastMessage: boolean,
+) {
+  const projected = page.sessions.map((session) => {
+    const title = capSessionDiscoveryText(session.title, 200, session.titleOriginalChars);
+    const goal = session.goal
+      ? capSessionDiscoveryText(
+          session.goal.text,
+          SESSION_DISCOVERY_TEXT_CHARS,
+          session.goal.textOriginalChars,
+        )
+      : null;
+    const preview = includeLastMessage
+      ? capSessionDiscoveryText(
+          session.latestMessage?.preview ?? null,
+          SESSION_DISCOVERY_TEXT_CHARS,
+          session.latestMessage?.previewOriginalChars,
+        )
+      : null;
+    const blocker = session.effectiveControl.primaryBlocker;
+    const blockerDisplayName = blocker
+      ? capSessionDiscoveryText(blocker.displayName, 200, blocker.displayNameOriginalChars)
+      : null;
+    return {
+      id: session.id,
+      title: title.text,
+      titleTruncated: title.truncated,
+      parentSessionId: session.parentSessionId,
+      isRoot: session.parentSessionId === null,
+      status: session.status,
+      pause: {
+        state: session.effectiveControl.state,
+        additionalBlockerCount: session.effectiveControl.additionalBlockerCount,
+        source: blocker
+          ? {
+              kind: blocker.kind,
+              ...(blocker.sessionId ? { sessionId: blocker.sessionId } : {}),
+              displayName: blockerDisplayName!.text,
+              displayNameTruncated: blockerDisplayName!.truncated,
+            }
+          : null,
+      },
+      goal: session.goal
+        ? {
+            status: session.goal.status,
+            summary: goal!.text,
+            summaryTruncated: goal!.truncated,
+          }
+        : null,
+      queuedPromptCount: session.queuedPromptCount,
+      children: session.treeStats,
+      ...(includeLastMessage
+        ? {
+            latestMessage: session.latestMessage
+              ? {
+                  type: session.latestMessage.type,
+                  preview: preview!.text,
+                  previewTruncated: preview!.truncated,
+                }
+              : null,
+          }
+        : {}),
+      createdAt: session.createdAt,
+      updatedAt: session.updatedAt,
+    };
+  });
+
+  // The database order is already the useful discovery order. Spend the
+  // separate preview budget in that order so the first page retains previews
+  // for the most relevant rows and later rows remain discoverable by status.
+  let budgetBytes = 0;
+  const budgeted = includeLastMessage
+    ? projected.map((session) => {
+        const latestMessage = session.latestMessage;
+        if (!latestMessage || latestMessage.preview === null) return session;
+        const candidateBytes = Buffer.byteLength(latestMessage.preview, "utf8");
+        if (budgetBytes + candidateBytes <= SESSION_DISCOVERY_PREVIEW_MAX_BYTES) {
+          budgetBytes += candidateBytes;
+          return session;
+        }
+        return {
+          ...session,
+          latestMessage: {
+            ...latestMessage,
+            preview: null,
+            previewOmitted: true,
+            previewOmissionReason: SESSION_DISCOVERY_PREVIEW_OMISSION_REASON,
+            previewDrillDownTool: SESSION_DISCOVERY_PREVIEW_DRILL_DOWN_TOOL,
+            previewDrillDownInput: sessionDiscoveryPreviewDrillDownInput(
+              session.id,
+              latestMessage.type,
+            ),
+          },
+        };
+      })
+    : projected;
+
+  let kept = budgeted;
+  const build = () => {
+    const previewBytes = includeLastMessage
+      ? kept.reduce(
+          (total, session) =>
+            total +
+            (session.latestMessage?.preview === null || !session.latestMessage
+              ? 0
+              : Buffer.byteLength(session.latestMessage.preview, "utf8")),
+          0,
+        )
+      : 0;
+    const previewOmittedCount = includeLastMessage
+      ? kept.filter((session) => {
+          const latestMessage = session.latestMessage;
+          return (
+            latestMessage != null &&
+            "previewOmitted" in latestMessage &&
+            latestMessage.previewOmitted === true
+          );
+        }).length
+      : 0;
+    const lastKept = kept.at(-1);
+    const droppedForByteCap = kept.length < projected.length;
+    const sourceLast = lastKept
+      ? page.sessions.find((session) => session.id === lastKept.id)
+      : undefined;
+    const nextCursor = droppedForByteCap
+      ? sourceLast
+        ? encodeSessionDiscoveryCursor({
+            orderBy: page.orderBy,
+            sortRevision: sourceLast.sortRevision,
+            sortAt: sourceLast.sortAt,
+            id: sourceLast.id,
+            snapshotAt: page.snapshotAt,
+            snapshotRevision: page.snapshotRevision,
+            updatedAfter: page.updatedAfter,
+          })
+        : null
+      : page.nextCursor
+        ? encodeSessionDiscoveryCursor(page.nextCursor)
+        : null;
+    const result = {
+      sessions: kept,
+      total: page.total,
+      hasMore: page.hasMore || droppedForByteCap,
+      nextCursor,
+      orderBy: page.orderBy,
+      snapshotAt: page.snapshotAt,
+      snapshotRevision: page.snapshotRevision,
+      updatedAfter: page.updatedAfter,
+      updatedThrough: page.updatedThrough,
+      ...(includeLastMessage
+        ? {
+            latestMessagePreviewBudget: {
+              bytes: previewBytes,
+              maxBytes: SESSION_DISCOVERY_PREVIEW_MAX_BYTES,
+              omittedCount: previewOmittedCount,
+              truncated: previewOmittedCount > 0,
+              omissionReason:
+                previewOmittedCount > 0 ? SESSION_DISCOVERY_PREVIEW_OMISSION_REASON : null,
+              drillDownTool: SESSION_DISCOVERY_PREVIEW_DRILL_DOWN_TOOL,
+              drillDownInput: {
+                includeTypes: ["user.message", "agent.message.completed"] as const,
+                ...SESSION_DISCOVERY_PREVIEW_DRILL_DOWN_BASE_INPUT,
+              },
+            },
+          }
+        : {}),
+      responseTruncated: droppedForByteCap,
+      ...(droppedForByteCap
+        ? {
+            truncationReason: `response exceeded ${SESSION_DISCOVERY_PAGE_MAX_BYTES} bytes; continue with nextCursor`,
+          }
+        : {}),
+      bytes: 0,
+      maxBytes: SESSION_DISCOVERY_PAGE_MAX_BYTES,
+    };
+    for (let attempt = 0; attempt < 8; attempt += 1) {
+      const measured = Buffer.byteLength(JSON.stringify(result, null, 2), "utf8");
+      if (result.bytes === measured) break;
+      result.bytes = measured;
+    }
+    return result;
+  };
+
+  let result = build();
+  while (result.bytes > SESSION_DISCOVERY_PAGE_MAX_BYTES && kept.length > 1) {
+    kept = kept.slice(0, -1);
+    result = build();
+  }
+  if (result.bytes > SESSION_DISCOVERY_PAGE_MAX_BYTES) {
+    throw new RangeError(
+      `sessions_list metadata exceeds its ${SESSION_DISCOVERY_PAGE_MAX_BYTES}-byte envelope`,
+    );
+  }
+  return result;
+}
+
 function parseMcpDate(raw: string, label: string): Date {
   const date = new Date(raw);
   if (Number.isNaN(date.getTime())) {