@opengeni/api-router 0.22.2 → 0.23.1

package/src/routes/sessions.ts

@@ -12,6 +12,7 @@ import {
   EditSessionQueueItemRequest,
   EndSessionRealtimeRequest,
   FsDeleteRequest,
+  FsListBatchRequest,
   FsListRequest,
   FsMkdirRequest,
   FsMoveRequest,
@@ -19,6 +20,7 @@ import {
   FsWriteRequest,
   HumanInputRequestStatus,
   GitDiffRequest,
+  GitReadBatchRequest,
   GitLogRequest,
   GitShowRequest,
   GitStatusRequest,
@@ -148,6 +150,7 @@ import { HTTPException } from "hono/http-exception";
 import type { ContentfulStatusCode } from "hono/utils/http-status";
 import {
   requireAccessGrant,
+  requirePermission,
   requireSessionAuthorization,
   requireSessionAuthorizationListScope,
   SESSION_AUTHORIZATION_DEFAULT_REAUTHORIZE_MS,
@@ -333,6 +336,13 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
   const authorizeSessionHttp: MiddlewareHandler = async (c, next) => {
     const workspaceId = c.req.param("workspaceId") ?? "";
     const sessionId = c.req.param("sessionId") ?? "";
+    // Reject malformed route identifiers before the authorization resolver
+    // reaches UUID-typed persistence queries. Besides avoiding a needless DB
+    // round trip, this preserves the session surface's non-enumerating 404
+    // contract instead of leaking a driver-level 500.
+    if (!z.string().uuid().safeParse(sessionId).success) {
+      throw new HTTPException(404, { message: "session not found" });
+    }
     const operation = sessionAuthorizationOperationForHttp(
       c.req.method,
       new URL(c.req.url).pathname,
@@ -1342,11 +1352,12 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     if (event) {
       try {
         await bus.publish(workspaceId, sessionId, [event]);
-      } catch (error) {
-        console.warn(
-          `[api] live publish failed for cleared goal ${workspaceId}/${sessionId}; event is durable and reconciles on replay`,
-          error,
-        );
+      } catch {
+        console.warn("[api] cleared-goal live publish failed; durable event reconciles on replay", {
+          errorClass: "EventPublishOperationError",
+          errorCode: "cleared_goal_live_publish_failed",
+          origin: "api",
+        });
       }
     }
     return c.body(null, 204);
@@ -2190,6 +2201,16 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         : {}),
     });
 
+    const repositoryRoots = [
+      ...new Set(
+        session.resources.flatMap((resource) =>
+          resource.kind === "repository" && typeof resource.mountPath === "string"
+            ? [resource.mountPath.replace(/^\/+|\/+$/g, "")]
+            : [],
+        ),
+      ),
+    ].filter(Boolean);
+
     // SWAP-CASE desktop transport (BOTH directions): negotiateCapabilities keyed on
     // the HOME backend, but the pixel plane actually runs on the ACTIVE sandbox — and
     // the two backends use DIFFERENT wire transports. The advertised transport MUST
@@ -2209,7 +2230,13 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     // active sandbox kind is "selfhosted") — EXACTLY mintDesktopStream's routing. When
     // the desktop is available we set the transport from the ACTIVE sandbox in one
     // place (resolveActiveDesktopTransport), covering BOTH swap directions.
-    let responseCapabilities = capabilities;
+    let responseCapabilities = {
+      ...capabilities,
+      Git: {
+        ...capabilities.Git,
+        repos: capabilities.Git.available ? repositoryRoots : [],
+      },
+    };
     if (capabilities.DesktopStream.transport !== null) {
       const activeSandbox = session.activeSandboxId
         ? await getSandbox(db, workspaceId, session.activeSandboxId)
@@ -2219,7 +2246,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         settings.sandboxDesktopInteractive !== false,
       );
       responseCapabilities = {
-        ...capabilities,
+        ...responseCapabilities,
         DesktopStream: { ...capabilities.DesktopStream, ...wire },
       };
     }
@@ -2273,7 +2300,10 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
   // when cold).
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/viewers", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "stream:view");
+    // Authenticate and bind the workspace before parsing. The requested plane
+    // determines the narrower permission below: terminal-only holders must not
+    // require the strictly broader un-redacted Desktop permission.
+    const grant = await requireAccessGrant(c, deps, workspaceId);
     assertOwnershipEnabled();
     const sessionId = c.req.param("sessionId");
     const session = await getSession(db, workspaceId, sessionId);
@@ -2297,6 +2327,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     // read-only sse-events firehose forever ("read only"), and with the desktop tier
     // off by default there was no consent flow to ever clear the gate.
     const wantDesktop = parsed.data.desktop ?? false;
+    requirePermission(grant, wantDesktop ? "stream:view" : "terminal:attach");
     const { shared } = await resolveSharedExposure(workspaceId, session);
     if (wantDesktop) {
       const ack = await getStreamAcknowledgment(db, {
@@ -2443,12 +2474,13 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
   });
 
   // POST .../viewers/:viewerId/heartbeat — refresh the holder TTL (epoch-fenced).
-  // The desktop-stream lifecycle is gated on stream:view (the un-redacted plane).
+  // A holder can represent the terminal-only plane, so lifecycle control uses
+  // terminal:attach. Desktop callers continue to pass via workspace:admin.
   app.post(
     "/v1/workspaces/:workspaceId/sessions/:sessionId/viewers/:viewerId/heartbeat",
     async (c) => {
       const workspaceId = c.req.param("workspaceId");
-      const grant = await requireAccessGrant(c, deps, workspaceId, "stream:view");
+      const grant = await requireAccessGrant(c, deps, workspaceId, "terminal:attach");
       assertOwnershipEnabled();
       const sessionId = c.req.param("sessionId");
       const session = await getSession(db, workspaceId, sessionId);
@@ -2478,7 +2510,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
   // DELETE .../viewers/:viewerId — release the holder (idempotent).
   app.delete("/v1/workspaces/:workspaceId/sessions/:sessionId/viewers/:viewerId", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "stream:view");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "terminal:attach");
     assertOwnershipEnabled();
     const sessionId = c.req.param("sessionId");
     const session = await getSession(db, workspaceId, sessionId);
@@ -2596,6 +2628,19 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     return c.json(out);
   });
 
+  app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/fs/list-batch", async (c) => {
+    const ctx = await channelAPreamble(c, "files:read");
+    const req = await parseChannelABody(c, FsListBatchRequest);
+    const out = await withChannelA(channelAServices, ctx, async ({ service }) => ({
+      results: await Promise.all(
+        req.requests.map((request) =>
+          Promise.resolve().then(async () => await service.fsList(request)),
+        ),
+      ),
+    }));
+    return c.json(out);
+  });
+
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/fs/read", async (c) => {
     const ctx = await channelAPreamble(c, "files:read");
     const req = await parseChannelABody(c, FsReadRequest);
@@ -2646,6 +2691,26 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     return c.json(out);
   });
 
+  app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/git/read-batch", async (c) => {
+    const ctx = await channelAPreamble(c, "files:read");
+    const req = await parseChannelABody(c, GitReadBatchRequest);
+    const out = await withChannelA(channelAServices, ctx, async ({ service }) => ({
+      results: await Promise.all(
+        req.requests.map(async (request) => {
+          const diffRequest = request.diff;
+          const [status, diff] = await Promise.all([
+            Promise.resolve().then(async () => await service.gitStatus(request.status)),
+            diffRequest
+              ? Promise.resolve().then(async () => await service.gitDiff(diffRequest))
+              : Promise.resolve(undefined),
+          ]);
+          return { status, ...(diff ? { diff } : {}) };
+        }),
+      ),
+    }));
+    return c.json(out);
+  });
+
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/git/log", async (c) => {
     const ctx = await channelAPreamble(c, "files:read");
     const req = await parseChannelABody(c, GitLogRequest);
@@ -3101,7 +3166,7 @@ export function sessionAuthorizationOperationForHttp(
   if (suffix.startsWith("/viewers/") && ["POST", "DELETE"].includes(verb)) {
     return "session.viewer.control";
   }
-  if (suffix === "/fs/list" || suffix === "/fs/read") {
+  if (suffix === "/fs/list" || suffix === "/fs/list-batch" || suffix === "/fs/read") {
     return verb === "POST" ? "session.files.read" : null;
   }
   if (["/fs/write", "/fs/delete", "/fs/move", "/fs/mkdir"].includes(suffix)) {

package/src/routes/transcription-recordings.ts

@@ -35,14 +35,17 @@ import {
   markTranscriptionRecordingObjectsCleaned,
   reserveTranscriptionRecordingChunk,
   reserveTranscriptionRecordingSegment,
+  runIdempotentPersistenceTransaction,
   startTranscriptionRecordingSegmentProviderCall,
   transcriptionRecordingObjectKeys,
   TranscriptionRecordingConflictError,
   TranscriptionRecordingNotFoundError,
   TranscriptionRecordingStateError,
+  isSessionEventPersistenceError,
 } from "@opengeni/db";
 import { getWorkspace } from "@opengeni/db";
 import type { Context, Hono } from "hono";
+import { ApiHttpError } from "../http/api-error";
 import { TranscriptionSegmenterError } from "../transcription/segmenter";
 
 const CHUNK_SHA256_HEADER = "x-opengeni-chunk-sha256";
@@ -153,17 +156,26 @@ export function registerResumableTranscriptionRoutes(app: Hono, deps: ApiRouteDe
         ) {
           return c.json({ code: "not_supported" }, 415);
         }
-        const reservation = await reserveTranscriptionRecordingChunk(deps.db, {
-          ...authority,
-          recordingId: existing.recording.id,
-          chunkNumber,
-          byteLength: body.byteLength,
-          sha256,
-          startMilliseconds,
-          durationMilliseconds,
-          maxTotalBytes: deps.settings.voiceInputResumableMaxSizeBytes,
-          maxDurationMilliseconds: deps.settings.voiceInputResumableMaxDurationSeconds * 1_000,
-        });
+        const persistenceCorrelationId = correlationId(c);
+        const reservation = await runIdempotentPersistenceTransaction(
+          {
+            stage: "transcription_recording_chunk_reservation",
+            eventTypes: ["transcription_recording_chunk"],
+            correlationId: persistenceCorrelationId,
+          },
+          () =>
+            reserveTranscriptionRecordingChunk(deps.db, {
+              ...authority,
+              recordingId: existing.recording.id,
+              chunkNumber,
+              byteLength: body.byteLength,
+              sha256,
+              startMilliseconds,
+              durationMilliseconds,
+              maxTotalBytes: deps.settings.voiceInputResumableMaxSizeBytes,
+              maxDurationMilliseconds: deps.settings.voiceInputResumableMaxDurationSeconds * 1_000,
+            }),
+        );
         if (!reservation.deduplicated) {
           try {
             // A concurrent same-hash retry may still observe the row while it is
@@ -180,12 +192,20 @@ export function registerResumableTranscriptionRoutes(app: Hono, deps: ApiRouteDe
             throw new RecordingProcessingError("Chunk upload failed", "network", true);
           }
         }
-        const completed = await completeTranscriptionRecordingChunk(deps.db, {
-          workspaceId: authority.workspaceId,
-          subjectId: authority.subjectId,
-          recordingId: existing.recording.id,
-          chunkNumber,
-        });
+        const completed = await runIdempotentPersistenceTransaction(
+          {
+            stage: "transcription_recording_chunk_completion",
+            eventTypes: ["transcription_recording_chunk"],
+            correlationId: persistenceCorrelationId,
+          },
+          () =>
+            completeTranscriptionRecordingChunk(deps.db, {
+              workspaceId: authority.workspaceId,
+              subjectId: authority.subjectId,
+              recordingId: existing.recording.id,
+              chunkNumber,
+            }),
+        );
         const response: UploadTranscriptionRecordingChunkResponse = {
           recording: completed.recording.recording,
           chunk: {
@@ -620,9 +640,25 @@ function routeError(c: Context, error: unknown): Response | Promise<Response> {
               : error.code === "unavailable"
                 ? 503
                 : 502;
+    if (error.retryable) {
+      throw new ApiHttpError(status, {
+        code: "upstream_unavailable",
+        message: "Transcription is temporarily unavailable.",
+        retryable: true,
+        details: { transcriptionCode: error.code },
+      });
+    }
     return c.json({ code: error.code }, status as never);
   }
-  return c.json({ code: "unknown" }, 500);
+  if (isSessionEventPersistenceError(error)) {
+    throw new ApiHttpError(503, {
+      code: "upstream_unavailable",
+      message: "Transcription is temporarily unavailable.",
+      retryable: true,
+      details: { persistenceCode: error.code },
+    });
+  }
+  throw error;
 }
 
 async function jsonBody(c: Context): Promise<unknown> {
@@ -688,22 +724,18 @@ async function readBoundedBody(request: Request, maxBytes: number): Promise<Uint
   const reader = request.body.getReader();
   const chunks: Uint8Array[] = [];
   let total = 0;
-  try {
-    for (;;) {
-      if (request.signal.aborted) {
-        throw new RecordingProcessingError("Chunk upload was cancelled", "cancelled", true);
-      }
-      const next = await reader.read();
-      if (next.done) break;
-      total += next.value.byteLength;
-      if (total > maxBytes) {
-        await reader.cancel();
-        throw new RecordingProcessingError("Chunk is too large", "too_large", false);
-      }
-      chunks.push(next.value);
+  for (;;) {
+    if (request.signal.aborted) {
+      throw new RecordingProcessingError("Chunk upload was cancelled", "cancelled", true);
+    }
+    const next = await reader.read();
+    if (next.done) break;
+    total += next.value.byteLength;
+    if (total > maxBytes) {
+      await reader.cancel();
+      throw new RecordingProcessingError("Chunk is too large", "too_large", false);
     }
-  } finally {
-    reader.releaseLock();
+    chunks.push(next.value);
   }
   if (total === 0) {
     throw new RecordingProcessingError("Chunk is required", "invalid_audio", false);

package/src/sandbox/auth-callout.ts

@@ -10,8 +10,8 @@
 //      to, the `server_id` for the response `aud`, and the presented `auth_token`);
 //   2. VALIDATES the bearer with verifyEnrollmentBearer (HMAC, via
 //      resolveEnrollmentSigningSecret) — an invalid/expired/forged bearer is denied;
-//   3. confirms the enrollment is still ACTIVE in the DB (a revoked machine is
-//      denied even with a still-unexpired bearer);
+//   3. confirms the enrollment is still ACTIVE in the DB at the exact credential
+//      generation (a revoked or re-enrolled machine denies an old bearer);
 //   4. signs a NATS user JWT granting pub/sub ONLY `agent.<ws>.>` + `_INBOX.>`
 //      (deny-all-else by an allow-list) and returns it inside a signed
 //      authorization-response JWT.
@@ -48,6 +48,8 @@ import { observabilityEventLogger } from "../observability";
 
 /** The NATS subject nats-server publishes authorization requests on (ADR-26). */
 export const AUTH_CALLOUT_SUBJECT = "$SYS.REQ.USER.AUTH";
+/** Keep live NATS credentials short-lived while never outliving the bearer. */
+export const NATS_USER_JWT_TTL_SECONDS = 5 * 60;
 
 export interface AuthCalloutDeps {
   db: Database;
@@ -123,13 +125,23 @@ export async function handleAuthorizationRequest(
   // Belt-and-braces: the bearer's agentId/enrollmentId must match the row we found.
   // (verifyEnrollmentBearer already binds them; this guards a future schema where
   // agentId != enrollmentId.)
-  if (enrollment.id !== claims.enrollmentId) {
+  if (
+    enrollment.workspaceId !== claims.workspaceId ||
+    enrollment.id !== claims.enrollmentId ||
+    enrollment.id !== claims.agentId ||
+    claims.agentId !== claims.enrollmentId ||
+    claims.subjectPrefix !== `agent.${claims.workspaceId}.${claims.agentId}`
+  ) {
     return deny("enrollment identity mismatch");
   }
+  if (enrollment.credentialGeneration !== claims.credentialGeneration) {
+    return deny("enrollment credential generation mismatch");
+  }
 
   // GRANT: a user JWT scoped to ONLY this workspace's agent subtree + the reply
   // inbox. This allow-list IS the per-workspace isolation boundary.
   const permissions = workspaceAgentPermissions(claims.workspaceId);
+  const nowSeconds = Math.floor(Date.now() / 1000);
   const userJwt = mintUserJwt({
     userPublicKey: decoded.userNkey,
     accountSeed: deps.callout.accountSeed,
@@ -142,7 +154,7 @@ export async function handleAuthorizationRequest(
     audienceAccount: deps.callout.accountName,
     // Tie the credential's life to the bearer's remaining life: a revoked/expired
     // enrollment cannot outlive its bearer at the NATS layer either.
-    expiresAtSeconds: claims.exp,
+    expiresAtSeconds: Math.min(claims.exp, nowSeconds + NATS_USER_JWT_TTL_SECONDS),
   });
   const response = mintAuthResponse({
     userPublicKey: decoded.userNkey,

package/src/sandbox/channel-a.ts

@@ -30,6 +30,7 @@ import type { Session } from "@opengeni/contracts";
 import {
   acquireLease,
   getSandboxSessionEnvelope,
+  getEnrollment,
   getSandbox,
   loadWorkspaceEnvironmentForRun,
   markWarmLeaseInstanceLost,
@@ -49,6 +50,7 @@ import {
   isProviderSandboxNotFoundError,
   SandboxChannelAService,
   NatsControlRpc,
+  NatsOpStreamTransport,
   ChannelAConflictError,
   ChannelANotFoundError,
   ChannelAUnsupportedError,
@@ -90,6 +92,97 @@ export type ChannelAHandle = {
   requestId: string;
 };
 
+/**
+ * Provider handles are lightweight references to a lease-owned sandbox, but
+ * reconstructing one is not free: Modal resume-by-id plus its first command can
+ * dominate a small Git/files read. Workspace panels issue several independent
+ * Channel-A requests together, so reuse the exact fenced handle briefly instead
+ * of making every request reattach to the same warm instance.
+ *
+ * The key includes the session, lease epoch, and immutable provider instance id.
+ * A rotation can therefore never inherit an old handle. Entries are bounded and
+ * expire opportunistically; eviction only drops local references and never
+ * terminates the lease-owned sandbox.
+ */
+const CHANNEL_A_HANDLE_CACHE_TTL_MS = 300_000;
+const CHANNEL_A_HANDLE_CACHE_MAX_ENTRIES = 64;
+type CachedEstablishedHandle = {
+  promise: Promise<EstablishedSandboxSession>;
+  lastUsedAt: number;
+};
+const establishedHandleCache = new Map<string, CachedEstablishedHandle>();
+
+function establishedHandleCacheKey(
+  workspaceId: string,
+  sessionId: string,
+  lease: LeaseSnapshot,
+): string {
+  return [workspaceId, sessionId, lease.leaseEpoch, lease.instanceId ?? ""].join("\u0000");
+}
+
+function pruneEstablishedHandleCache(now: number): void {
+  for (const [key, entry] of establishedHandleCache) {
+    if (now - entry.lastUsedAt > CHANNEL_A_HANDLE_CACHE_TTL_MS) {
+      establishedHandleCache.delete(key);
+    }
+  }
+  while (establishedHandleCache.size >= CHANNEL_A_HANDLE_CACHE_MAX_ENTRIES) {
+    const oldestKey = establishedHandleCache.keys().next().value as string | undefined;
+    if (oldestKey === undefined) break;
+    establishedHandleCache.delete(oldestKey);
+  }
+}
+
+async function establishCachedHandle(
+  key: string,
+  establish: () => Promise<EstablishedSandboxSession>,
+): Promise<EstablishedSandboxSession> {
+  const now = Date.now();
+  pruneEstablishedHandleCache(now);
+  const cached = establishedHandleCache.get(key);
+  if (cached) {
+    cached.lastUsedAt = now;
+    // Refresh insertion order so the bounded map evicts the least-recently used
+    // exact lease identity first.
+    establishedHandleCache.delete(key);
+    establishedHandleCache.set(key, cached);
+    return await cached.promise;
+  }
+
+  const promise = establish();
+  const entry: CachedEstablishedHandle = { promise, lastUsedAt: now };
+  establishedHandleCache.set(key, entry);
+  try {
+    return await promise;
+  } catch (error) {
+    if (establishedHandleCache.get(key) === entry) establishedHandleCache.delete(key);
+    throw error;
+  }
+}
+
+/** Reuse the exact lease-fenced provider handle across API-direct surfaces.
+ * Stream capability negotiation and the first Files/Changes reads commonly run
+ * back-to-back; sharing this handle avoids paying the same Modal resume twice. */
+export async function establishCachedChannelAHandle(
+  workspaceId: string,
+  sessionId: string,
+  lease: LeaseSnapshot,
+  establish: () => Promise<EstablishedSandboxSession>,
+): Promise<EstablishedSandboxSession> {
+  return await establishCachedHandle(
+    establishedHandleCacheKey(workspaceId, sessionId, lease),
+    establish,
+  );
+}
+
+function rememberEstablishedHandle(key: string, established: EstablishedSandboxSession): void {
+  pruneEstablishedHandleCache(Date.now());
+  establishedHandleCache.set(key, {
+    promise: Promise.resolve(established),
+    lastUsedAt: Date.now(),
+  });
+}
+
 /**
  * Run a Channel-A op against a live box, API-direct. Acquires an exact direct holder
  * (warming the box when cold), resumes by id, builds the service, runs `fn`, and
@@ -169,7 +262,12 @@ export async function withChannelA<T>(
       leaseEpoch: lease?.leaseEpoch ?? session.activeEpoch,
       emit,
     });
-    return await fn({ service, lease, routingSession, requestId });
+    const result = await fn({ service, lease, routingSession, requestId });
+    // The direct request has accepted the result in memory. Finalize every
+    // Connected Machine backend the routing proxy reached so a mid-request
+    // route transition cannot leave completed output retained until TTL.
+    await routingSession.finalizeOpStreamOps().catch(() => undefined);
+    return result;
   };
 
   // A machine-targeted top-level session has an honest selfhosted HOME label.
@@ -190,6 +288,7 @@ export async function withChannelA<T>(
           message: "machine-home session points to an unavailable Connected Machine",
         });
       }
+      const enrollment = await getEnrollment(db, workspaceId, sandbox.enrollmentId);
       const built = await buildSelfhostedBackendSession({
         workspaceId,
         agentId: sandbox.enrollmentId,
@@ -200,6 +299,17 @@ export async function withChannelA<T>(
         workingDir: pointer.workingDir,
         timeoutMs: settings.sandboxSelfhostedControlTimeoutMs,
         execTimeoutMs: settings.sandboxSelfhostedExecTimeoutMs,
+        ...(settings.agentOpStreamEnabled === true &&
+        enrollment?.opStream === true &&
+        bus.getOpStreamConnection
+          ? {
+              opStream: {
+                transport: new NatsOpStreamTransport(
+                  async () => bus.getOpStreamConnection?.() ?? null,
+                ),
+              },
+            }
+          : {}),
       });
       established = {
         client: built.client,
@@ -271,6 +381,7 @@ export async function withChannelA<T>(
 
   let established: EstablishedSandboxSession | undefined;
   let leaseSnapshot: LeaseSnapshot = acquired.lease;
+  let establishedCacheKey: string | null = null;
 
   try {
     const envelope = await getSandboxSessionEnvelope(db, workspaceId, session.id);
@@ -303,6 +414,8 @@ export async function withChannelA<T>(
         });
         established = result.established;
         leaseSnapshot = result.lease;
+        establishedCacheKey = establishedHandleCacheKey(workspaceId, session.id, leaseSnapshot);
+        rememberEstablishedHandle(establishedCacheKey, established);
       } catch (error) {
         throw new HTTPException(409, {
           message: `sandbox not available (${error instanceof Error ? error.message : "spawn failed"})`,
@@ -323,17 +436,21 @@ export async function withChannelA<T>(
         });
       }
       leaseSnapshot = live;
+      establishedCacheKey = establishedHandleCacheKey(workspaceId, session.id, live);
       try {
-        established = await establishSandboxSessionFromEnvelope(settings, live.resumeState, {
-          sessionId: session.id,
-          recovery: "resume-only",
-          backendOverride: session.sandboxBackend,
-          environment,
-        });
+        established = await establishCachedChannelAHandle(workspaceId, session.id, live, () =>
+          establishSandboxSessionFromEnvelope(settings, live.resumeState, {
+            sessionId: session.id,
+            recovery: "resume-only",
+            backendOverride: session.sandboxBackend,
+            environment,
+          }),
+        );
       } catch (error) {
         if (!isProviderSandboxNotFoundError(session.sandboxBackend, error)) {
           throw error;
         }
+        establishedHandleCache.delete(establishedCacheKey);
         const marked = await markWarmLeaseInstanceLost(db, {
           accountId,
           workspaceId,

package/src/sandbox/enrollment.ts

@@ -75,8 +75,9 @@ export const DEVICE_POLL_INTERVAL_SECONDS = 5;
 // box) caused a self-hosted agent to drop PERMANENTLY one hour after connecting: the
 // bearer expired and the auth-callout rejected every reconnect ("re-enroll may be
 // required"). A long-lived bearer is safe because the auth-callout RE-CHECKS the
-// enrollment status on every (re)connect (auth-callout.ts) — a revoked machine is
-// denied regardless of bearer life — exactly as the long-lived relay token relies on.
+// enrollment status AND credential generation on every (re)connect
+// (auth-callout.ts) — a revoked machine or an old pre-re-enrollment bearer is denied
+// regardless of bearer life. The short NATS user-JWT cap bounds already-live access.
 export const ENROLLMENT_BEARER_TTL_SECONDS = 30 * 24 * 3600;
 // The relay PRODUCER token (the `ogr_` token; M8b) is ENROLLMENT-scoped,
 // NOT per-stream: the agent presents it on every channel registration for the life
@@ -370,6 +371,7 @@ export async function exchangeEnrollToken(
     secret,
     workspaceId: claims.workspaceId,
     agentId: enrollment.id,
+    credentialGeneration: enrollment.credentialGeneration,
     consentedScreenControl: enrollment.allowScreenControl,
   });
   return { ok: true, credentials };
@@ -430,6 +432,7 @@ export async function pollDeviceEnrollment(
     secret,
     workspaceId: request.workspaceId,
     agentId: enrollment.id,
+    credentialGeneration: enrollment.credentialGeneration,
     consentedScreenControl: enrollment.allowScreenControl,
   });
 
@@ -455,7 +458,13 @@ export async function pollDeviceEnrollment(
  *  bearer so an agent using it as the connect-token credential works uniformly. */
 async function buildEnrollmentCredentials(
   services: EnrollmentServices,
-  input: { secret: string; workspaceId: string; agentId: string; consentedScreenControl: boolean },
+  input: {
+    secret: string;
+    workspaceId: string;
+    agentId: string;
+    credentialGeneration: number;
+    consentedScreenControl: boolean;
+  },
 ): Promise<EnrollmentCredentialsResponse> {
   const { settings } = services;
   // The control-plane subject prefix the agent subscribes to: agent.<ws>.<id>.
@@ -466,6 +475,7 @@ async function buildEnrollmentCredentials(
     workspaceId: input.workspaceId,
     agentId: input.agentId,
     enrollmentId: input.agentId,
+    credentialGeneration: input.credentialGeneration,
     subjectPrefix,
     exp,
   });

package/src/sandbox/machines.ts

@@ -219,7 +219,7 @@ export async function listMachines(
   // onto the machines (no N+1). Each machine is probed for liveness.
   const [sandboxes, enrollments, metricsByEnrollment] = await Promise.all([
     listSandboxes(db, workspaceId),
-    listEnrollments(db, workspaceId),
+    listEnrollments(db, workspaceId, { status: "active" }),
     readMachineMetricsLatestForWorkspace(db, workspaceId),
   ]);
   const enrollmentById = new Map(enrollments.map((e) => [e.id, e]));