fix(sandbox): adopt open-agents scheduleBackgroundWork pattern for lifecycle kick

Smoke test caught: the lifecycle kick fired but its async chain
(selectSessions → claim lease → start workflow) never completed
because the serverless function tore down on response. No
[kickSandboxLifecycleWorkflow] log lines, no workflow run started.

Original PR placed `after()` from next/server inside the kick lib —
which violated open-agents' architecture: the kick is a generic
fan-out lib, the platform-specific scheduler belongs at the call
site.

Refactored to match open-agents' open / api conventions:
- `kickSandboxLifecycleWorkflow` accepts an optional
  `scheduleBackgroundWork: (task: Promise<void>) => void` parameter.
  Default behavior is `void task` (matches open-agents fallback),
  scheduler used when provided.
- createSandboxHandler + getSandboxStatusHandler pass
  `scheduleBackgroundWork: task => after(() => task)`. Same pattern
  api already uses in `lib/agents/createPlatformRoutes.ts:62` and
  `app/api/chat/slack/route.ts:16` for waitUntil-style background
  work.

Test updated to use `expect.objectContaining` since the kick now
receives an extra `scheduleBackgroundWork` callback. Suite stays at
2579.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: sweetmantech

lib/sandbox/__tests__/createSandboxHandler.test.ts

@@ -288,10 +288,13 @@ describe("createSandboxHandler", () => {
   it("kicks the sandbox lifecycle workflow with reason='sandbox-created' when sessionId is provided", async () => {
     await createSandboxHandler(makeReq());
 
-    expect(kickSandboxLifecycleWorkflow).toHaveBeenCalledWith({
-      sessionId: "sess-1",
-      reason: "sandbox-created",
-    });
+    expect(kickSandboxLifecycleWorkflow).toHaveBeenCalledWith(
+      expect.objectContaining({
+        sessionId: "sess-1",
+        reason: "sandbox-created",
+        scheduleBackgroundWork: expect.any(Function),
+      }),
+    );
   });
 
   it("does not kick the lifecycle workflow when no sessionId is provided", async () => {

lib/sandbox/createSandboxHandler.ts

@@ -1,5 +1,5 @@
 import ms from "ms";
-import { NextRequest, NextResponse } from "next/server";
+import { NextRequest, NextResponse, after } from "next/server";
 import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
 import { validateCreateSandboxBody } from "@/lib/sandbox/validateCreateSandboxBody";
 import { selectSessions } from "@/lib/supabase/sessions/selectSessions";
@@ -145,11 +145,17 @@ export async function createSandboxHandler(request: NextRequest): Promise<NextRe
     }
 
     // Register the new sandbox with the lifecycle workflow so it gets
-    // auto-paused after SANDBOX_INACTIVITY_TIMEOUT_MS of idle. Fire-and-
-    // forget — failure to start the workflow doesn't fail the request,
-    // and a future status read will reclaim a stale lease if the
-    // workflow never picked up.
-    kickSandboxLifecycleWorkflow({ sessionId: sessionRow.id, reason: "sandbox-created" });
+    // auto-paused after SANDBOX_INACTIVITY_TIMEOUT_MS of idle. The
+    // kick chain (selectSessions → claim lease → start workflow) is
+    // registered with `after()` so the serverless platform keeps the
+    // function alive past the response until the chain completes —
+    // without that, the chain dies on function teardown and the
+    // workflow never starts. Failures are logged and never surfaced.
+    kickSandboxLifecycleWorkflow({
+      sessionId: sessionRow.id,
+      reason: "sandbox-created",
+      scheduleBackgroundWork: task => after(() => task),
+    });
   }
 
   return NextResponse.json(

lib/sandbox/getSandboxStatusHandler.ts

@@ -1,4 +1,4 @@
-import { NextRequest, NextResponse } from "next/server";
+import { NextRequest, NextResponse, after } from "next/server";
 import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
 import { validateAuthContext } from "@/lib/auth/validateAuthContext";
 import { buildLifecycle } from "@/lib/sandbox/buildLifecycle";
@@ -55,7 +55,11 @@ export async function getSandboxStatusHandler(request: NextRequest): Promise<Nex
   const active = isSandboxActive(row);
 
   if (active && row.lifecycle_state === "active" && Date.now() >= getLifecycleDueAtMs(row)) {
-    kickSandboxLifecycleWorkflow({ sessionId: row.id, reason: "status-check-overdue" });
+    kickSandboxLifecycleWorkflow({
+      sessionId: row.id,
+      reason: "status-check-overdue",
+      scheduleBackgroundWork: task => after(() => task),
+    });
   }
 
   return NextResponse.json(

lib/sandbox/kickSandboxLifecycleWorkflow.ts

@@ -12,6 +12,15 @@ import type { Tables } from "@/types/database.types";
 interface KickInput {
   sessionId: string;
   reason: SandboxLifecycleReason;
+  /**
+   * Optional scheduler for the kick chain (selectSessions → claim
+   * lease → start workflow). Callers in serverless contexts should
+   * pass `p => after(() => p)` (or `waitUntil(p)`) so the platform
+   * keeps the function alive until the chain completes — without it
+   * the chain dies when the request returns. Mirrors open-agents'
+   * `scheduleBackgroundWork` parameter.
+   */
+  scheduleBackgroundWork?: (task: Promise<void>) => void;
 }
 
 /**
@@ -29,9 +38,16 @@ interface KickInput {
  * is considered stale and gets reclaimed.
  */
 export function kickSandboxLifecycleWorkflow(input: KickInput): void {
-  void runKick(input).catch(error =>
+  const task = runKick(input).catch(error =>
     console.error(`[kickSandboxLifecycleWorkflow] failed for session ${input.sessionId}:`, error),
   );
+
+  if (input.scheduleBackgroundWork) {
+    input.scheduleBackgroundWork(task);
+    return;
+  }
+
+  void task;
 }
 
 async function runKick(input: KickInput): Promise<void> {