feat(sessions): enhance session patching with sandbox state management

app/api/sessions/[sessionId]/__tests__/route.test.ts

@@ -5,6 +5,15 @@ import type { Tables } from "@/types/database.types";
 
 type SessionRow = Tables<"sessions">;
 
+vi.mock("next/server", async importOriginal => {
+  const actual = await importOriginal<typeof import("next/server")>();
+  return { ...actual, after: vi.fn() };
+});
+
+vi.mock("@/lib/sessions/stopSandboxOnArchive", () => ({
+  stopSandboxOnArchive: vi.fn(),
+}));
+
 vi.mock("@/lib/supabase/sessions/selectSessions", () => ({
   selectSessions: vi.fn(),
 }));
@@ -352,6 +361,11 @@ describe("PATCH /api/sessions/[sessionId]", () => {
     expect(updateSession).toHaveBeenCalledWith("sess_1", {
       title: "Renamed session",
       status: "archived",
+      lifecycle_state: "archived",
+      lifecycle_error: null,
+      lifecycle_run_id: null,
+      sandbox_expires_at: null,
+      hibernate_after: null,
     });
   });
 

lib/sandbox/isSandboxPausing.ts

@@ -0,0 +1,21 @@
+import { hasRuntimeSandboxState } from "@/lib/sandbox/hasRuntimeSandboxState";
+
+/**
+ * Returns true when a sandbox is actively being paused — i.e. it has
+ * live runtime state but has not yet reached a terminal lifecycle state
+ * (`hibernated` or `archived`).
+ *
+ * Used by `PATCH /api/sessions/{sessionId}` to guard unarchive requests:
+ * if the sandbox is still pausing the request returns 409 so the caller
+ * can retry once the sandbox has settled.
+ */
+export function isSandboxPausing(row: {
+  sandbox_state: unknown;
+  lifecycle_state: string | null;
+}): boolean {
+  return (
+    hasRuntimeSandboxState(row.sandbox_state) &&
+    row.lifecycle_state !== "hibernated" &&
+    row.lifecycle_state !== "archived"
+  );
+}

lib/sessions/isUnarchiveConflict.ts

@@ -0,0 +1,16 @@
+import { isSandboxPausing } from "@/lib/sandbox/isSandboxPausing";
+
+/**
+ * Returns true when an unarchive request should be rejected with 409:
+ * the sandbox has no snapshot to restore from and is still actively pausing.
+ *
+ * Without a snapshot, the sandbox cannot be unarchived until the pause
+ * completes; callers should retry after the sandbox settles.
+ */
+export function isUnarchiveConflict(row: {
+  sandbox_state: unknown;
+  lifecycle_state: string | null;
+  snapshot_url: string | null;
+}): boolean {
+  return !row.snapshot_url && isSandboxPausing(row);
+}

lib/sessions/lifecycleStatePatches.ts

@@ -0,0 +1,21 @@
+/**
+ * Lifecycle fields applied synchronously when a session is archived via
+ * `PATCH /api/sessions/{sessionId}`. Sandbox stop and snapshot clearing
+ * run afterward via `stopSandboxOnArchive`.
+ */
+export const ARCHIVE_LIFECYCLE_PATCH = {
+  lifecycle_state: "archived",
+  lifecycle_error: null,
+  lifecycle_run_id: null,
+  sandbox_expires_at: null,
+  hibernate_after: null,
+} as const;
+
+/**
+ * Lifecycle fields applied synchronously when a session is unarchived via
+ * `PATCH /api/sessions/{sessionId}`.
+ */
+export const UNARCHIVE_LIFECYCLE_PATCH = {
+  lifecycle_state: null,
+  lifecycle_error: null,
+} as const;

lib/sessions/patchSessionByIdHandler.ts

@@ -1,6 +1,13 @@
+import { after } from "next/server";
 import { NextRequest, NextResponse } from "next/server";
 import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { isUnarchiveConflict } from "@/lib/sessions/isUnarchiveConflict";
+import {
+  ARCHIVE_LIFECYCLE_PATCH,
+  UNARCHIVE_LIFECYCLE_PATCH,
+} from "@/lib/sessions/lifecycleStatePatches";
 import { validatePatchSessionBody } from "@/lib/sessions/validatePatchSessionBody";
+import { stopSandboxOnArchive } from "@/lib/sessions/stopSandboxOnArchive";
 import { selectSessions } from "@/lib/supabase/sessions/selectSessions";
 import { updateSession } from "@/lib/supabase/sessions/updateSession";
 import { toSessionResponse } from "@/lib/sessions/toSessionResponse";
@@ -56,11 +63,23 @@ export async function patchSessionByIdHandler(
     );
   }
 
+  const shouldArchive = body.status === "archived" && row.status !== "archived";
+  const shouldUnarchive = body.status === "running" && row.status === "archived";
+
+  if (shouldUnarchive && isUnarchiveConflict(row)) {
+    return NextResponse.json(
+      { status: "error", error: "Sandbox is still being paused, try again in a few seconds." },
+      { status: 409, headers: getCorsHeaders() },
+    );
+  }
+
   const updates = {
     ...(body.title !== undefined && { title: body.title }),
     ...(body.status !== undefined && { status: body.status }),
     ...(body.linesAdded !== undefined && { lines_added: body.linesAdded }),
     ...(body.linesRemoved !== undefined && { lines_removed: body.linesRemoved }),
+    ...(shouldArchive && ARCHIVE_LIFECYCLE_PATCH),
+    ...(shouldUnarchive && UNARCHIVE_LIFECYCLE_PATCH),
   };
 
   if (Object.keys(updates).length === 0) {
@@ -79,6 +98,10 @@ export async function patchSessionByIdHandler(
     );
   }
 
+  if (shouldArchive) {
+    after(() => stopSandboxOnArchive(row));
+  }
+
   return NextResponse.json(
     { session: toSessionResponse(updated) },
     { status: 200, headers: getCorsHeaders() },

lib/sessions/stopSandboxOnArchive.ts

@@ -0,0 +1,68 @@
+import { connectSandbox, type SandboxState } from "@/lib/sandbox/factory";
+import { clearSandboxState } from "@/lib/sandbox/clearSandboxState";
+import { hasRuntimeSandboxState } from "@/lib/sandbox/hasRuntimeSandboxState";
+import { selectSessions } from "@/lib/supabase/sessions/selectSessions";
+import { updateSession } from "@/lib/supabase/sessions/updateSession";
+import type { Tables } from "@/types/database.types";
+import type { Json } from "@/types/database.types";
+
+/**
+ * Fire-and-forget sandbox teardown for newly-archived sessions.
+ *
+ * Stops the running sandbox then clears its runtime state so the
+ * auto-hibernate workflow ignores the row. When the stop fails, persists
+ * a `lifecycle_error` and — if the row has no snapshot to fall back to —
+ * clears the runtime sandbox state so future unarchive attempts are not
+ * blocked forever by the 409 guard.
+ *
+ * Must be scheduled via `after()` so the HTTP response is not blocked.
+ * No-ops immediately when the session has no runtime sandbox.
+ *
+ * @param session - The session row as it existed before archiving.
+ */
+export async function stopSandboxOnArchive(session: Tables<"sessions">): Promise<void> {
+  if (!hasRuntimeSandboxState(session.sandbox_state)) return;
+
+  let stopError: unknown;
+
+  try {
+    const sandbox = await connectSandbox(session.sandbox_state as unknown as SandboxState);
+    await sandbox.stop();
+  } catch (error) {
+    stopError = error;
+    console.error(`[stopSandboxOnArchive] stop failed for session ${session.id}:`, error);
+  }
+
+  try {
+    const rows = await selectSessions({ id: session.id });
+    const current = rows?.[0] ?? null;
+
+    if (!current || current.status !== "archived") return;
+
+    if (stopError !== undefined) {
+      const message = stopError instanceof Error ? stopError.message : String(stopError);
+      const shouldClearState =
+        !current.snapshot_url && hasRuntimeSandboxState(current.sandbox_state);
+
+      await updateSession(session.id, {
+        lifecycle_error: `Archive finalization failed: ${message}`,
+        lifecycle_state: "archived",
+        lifecycle_run_id: null,
+        sandbox_expires_at: null,
+        hibernate_after: null,
+        ...(shouldClearState && {
+          sandbox_state: clearSandboxState(current.sandbox_state) as unknown as Json,
+        }),
+      });
+      return;
+    }
+
+    await updateSession(session.id, {
+      snapshot_url: null,
+      snapshot_created_at: null,
+      sandbox_state: clearSandboxState(session.sandbox_state) as unknown as Json,
+    });
+  } catch (error) {
+    console.error(`[stopSandboxOnArchive] state update failed for session ${session.id}:`, error);
+  }
+}