fix(sandbox): register SIGTERM handler before composite pre-await (#110)

Author: iamladi

packages/core/src/__tests__/sandbox.test.ts

@@ -1225,6 +1225,47 @@ describe("runAgentInSandbox — composite orchestration", () => {
 		onSpy.mockRestore();
 	});
 
+	it("registers SIGTERM handler before any await in composite pre-work", async () => {
+		// In composite mode, sandbox.ts runs `await instance.commands.run("rm -f
+		// /tmp/sandcaster-ipc-*.json*")` to clear stale IPC files. If SIGTERM
+		// arrives during that await and no handler is registered, Node exits
+		// immediately and the sandbox leaks. The handler must be installed
+		// before the first awaited operation following sandbox creation.
+		const instance = makeCompositeInstance([]);
+		registerFakeProvider(instance);
+
+		const onSpy = vi.spyOn(process, "once");
+
+		for await (const _ of runAgentInSandbox({
+			request: makeRequest({ composite: { maxSandboxes: 2 } }),
+		})) {
+			// consume
+		}
+
+		const sigtermCall = onSpy.mock.calls.find((call) => call[0] === "SIGTERM");
+		expect(sigtermCall).toBeDefined();
+
+		// Find the IPC cleanup call to instance.commands.run.
+		const ipcCleanupCall = instance.commands.run.mock.calls.find(
+			(call) =>
+				typeof call[0] === "string" && call[0].includes("sandcaster-ipc-"),
+		);
+		expect(ipcCleanupCall).toBeDefined();
+
+		const sigtermOrder = onSpy.mock.invocationCallOrder[
+			onSpy.mock.calls.findIndex((c) => c[0] === "SIGTERM")
+		] as number;
+		const ipcCleanupOrder = instance.commands.run.mock.invocationCallOrder[
+			instance.commands.run.mock.calls.findIndex(
+				(c) => typeof c[0] === "string" && c[0].includes("sandcaster-ipc-"),
+			)
+		] as number;
+
+		expect(sigtermOrder).toBeLessThan(ipcCleanupOrder);
+
+		onSpy.mockRestore();
+	});
+
 	it("registers a SIGTERM handler that kills the instance in non-composite mode", async () => {
 		// Without a SIGTERM handler, Node exits immediately on signal and the
 		// `finally` block that calls `instance.kill()` never runs, leaving the

packages/core/src/sandbox.ts

@@ -277,6 +277,21 @@ export async function* runAgentInSandbox(
 	let compositeNonce: string | undefined;
 	let resolvedComposite: ReturnType<typeof resolveCompositeConfig> | undefined;
 
+	// Register SIGTERM handler for graceful cleanup BEFORE any await that
+	// follows sandbox creation. Required for both modes: without a handler,
+	// Node exits immediately on SIGTERM and the `finally` block at the bottom
+	// of this function never runs — leaving the sandbox alive until the
+	// provider's idle timeout (5 min on E2B). Composite mode kills the whole
+	// pool (set below); non-composite kills the single instance.
+	const sigTermHandler: () => Promise<void> = async () => {
+		if (pool !== undefined) {
+			await pool.killAll();
+		} else {
+			await instance.kill();
+		}
+	};
+	process.once("SIGTERM", sigTermHandler);
+
 	if (compositeActive) {
 		resolvedComposite = resolveCompositeConfig(
 			config?.composite,
@@ -327,20 +342,6 @@ export async function* runAgentInSandbox(
 		await instance.commands.run(`rm -f /tmp/sandcaster-ipc-*.json*`);
 	}
 
-	// Register SIGTERM handler for graceful cleanup. Required for both modes:
-	// without a handler, Node exits immediately on SIGTERM and the `finally`
-	// block at the bottom of this function never runs — leaving the sandbox
-	// alive until the provider's idle timeout (5 min on E2B). Composite mode
-	// kills the whole pool; non-composite kills the single instance.
-	const sigTermHandler: () => Promise<void> = async () => {
-		if (pool !== undefined) {
-			await pool.killAll();
-		} else {
-			await instance.kill();
-		}
-	};
-	process.once("SIGTERM", sigTermHandler);
-
 	// Runner directory — use instance.workDir so providers with restricted
 	// filesystems (e.g. Vercel) can write to a writable location.
 	const runnerDir = `${instance.workDir}/.sandcaster`;