zeitlich 0.2.35 → 0.2.37

package/src/lib/sandbox/manager.ts

@@ -50,8 +50,12 @@ export interface SandboxManagerHooks<
 
   /**
    * Called after a sandbox has been successfully created.
+   *
+   * Receives the live {@link Sandbox} instance so the hook can run setup
+   * commands, seed files, or capture identifiers without an extra
+   * `provider.get()` round-trip.
    */
-  onPostCreate?: (sandboxId: string) => Promise<void>;
+  onPostCreate?: (sandbox: Sandbox, ctx: TCtx) => Promise<void>;
 }
 
 /**
@@ -87,8 +91,9 @@ export interface SandboxManagerHooks<
  *         for (const p of filePaths) files[p] = await db.readFile(projectId, p);
  *         return { modifiedOptions: { initialFiles: files } };
  *       },
- *       onPostCreate: async (sandboxId) => {
- *         console.log("Sandbox created:", sandboxId);
+ *       onPostCreate: async (sandbox) => {
+ *         console.log("Sandbox created:", sandbox.id);
+ *         await sandbox.exec("git init");
  *       },
  *     },
  *   },
@@ -148,7 +153,7 @@ export class SandboxManager<
     const { sandbox } = await this.provider.create(providerOptions);
 
     if (this.hooks.onPostCreate) {
-      await this.hooks.onPostCreate(sandbox.id);
+      await this.hooks.onPostCreate(sandbox, ctx ?? ({} as TCtx));
     }
 
     return { sandboxId: sandbox.id };
@@ -179,6 +184,10 @@ export class SandboxManager<
     return sandbox.id;
   }
 
+  async deleteSnapshot(snapshot: SandboxSnapshot): Promise<void> {
+    await this.provider.deleteSnapshot(snapshot);
+  }
+
   async fork(sandboxId: string): Promise<string> {
     const sandbox = await this.provider.fork(sandboxId);
     return sandbox.id;
@@ -232,6 +241,14 @@ export class SandboxManager<
       snapshotSandbox: async (sandboxId: string): Promise<SandboxSnapshot> => {
         return this.snapshot(sandboxId);
       },
+      restoreSandbox: async (snapshot: SandboxSnapshot): Promise<string> => {
+        return this.restore(snapshot);
+      },
+      deleteSandboxSnapshot: async (
+        snapshot: SandboxSnapshot
+      ): Promise<void> => {
+        await this.deleteSnapshot(snapshot);
+      },
       forkSandbox: async (sandboxId: string): Promise<string> => {
         return this.fork(sandboxId);
       },

package/src/lib/sandbox/node-fs.ts

@@ -65,10 +65,7 @@ export class NodeFsSandboxFileSystem implements SandboxFileSystem {
     };
   }
 
-  async mkdir(
-    path: string,
-    options?: { recursive?: boolean },
-  ): Promise<void> {
+  async mkdir(path: string, options?: { recursive?: boolean }): Promise<void> {
     await fsp.mkdir(this.abs(path), options);
   }
 
@@ -88,7 +85,7 @@ export class NodeFsSandboxFileSystem implements SandboxFileSystem {
 
   async rm(
     path: string,
-    options?: { recursive?: boolean; force?: boolean },
+    options?: { recursive?: boolean; force?: boolean }
   ): Promise<void> {
     await fsp.rm(this.abs(path), options);
   }
@@ -96,7 +93,7 @@ export class NodeFsSandboxFileSystem implements SandboxFileSystem {
   async cp(
     src: string,
     dest: string,
-    options?: { recursive?: boolean },
+    options?: { recursive?: boolean }
   ): Promise<void> {
     await fsp.cp(this.abs(src), this.abs(dest), options);
   }

package/src/lib/sandbox/sandbox.test.ts

@@ -157,18 +157,21 @@ describe("SandboxManager", () => {
     expect(await sandbox.fs.readFile("/file.txt")).toBe("explicit");
   });
 
-  it("onPostCreate hook receives sandboxId", async () => {
+  it("onPostCreate hook receives the live sandbox", async () => {
     let capturedId: string | undefined;
     const mgr = new SandboxManager(new InMemorySandboxProvider(), {
       hooks: {
-        onPostCreate: async (sandboxId) => {
-          capturedId = sandboxId;
+        onPostCreate: async (sandbox) => {
+          capturedId = sandbox.id;
+          await sandbox.fs.writeFile("/hook.txt", "written-by-hook");
         },
       },
     });
 
     const { sandboxId } = await mustCreate(mgr);
     expect(capturedId).toBe(sandboxId);
+    const sandbox = await mgr.getSandbox(sandboxId);
+    expect(await sandbox.fs.readFile("/hook.txt")).toBe("written-by-hook");
   });
 
   it("onPostCreate hook does not run when creation is skipped", async () => {
@@ -192,6 +195,8 @@ describe("SandboxManager", () => {
     expect(activities.inMemoryTestCreateSandbox).toBeTypeOf("function");
     expect(activities.inMemoryTestDestroySandbox).toBeTypeOf("function");
     expect(activities.inMemoryTestSnapshotSandbox).toBeTypeOf("function");
+    expect(activities.inMemoryTestRestoreSandbox).toBeTypeOf("function");
+    expect(activities.inMemoryTestDeleteSandboxSnapshot).toBeTypeOf("function");
 
     const result = await activities.inMemoryTestCreateSandbox();
     expect(result).not.toBeNull();
@@ -203,6 +208,34 @@ describe("SandboxManager", () => {
       SandboxNotFoundError
     );
   });
+
+  it("restoreSandbox activity creates a new sandbox from a snapshot", async () => {
+    const activities = manager.createActivities("Test");
+
+    const created = await activities.inMemoryTestCreateSandbox({
+      initialFiles: { "/greeting.txt": "hello" },
+    });
+    const { sandboxId } = created as { sandboxId: string };
+
+    const snapshot = await activities.inMemoryTestSnapshotSandbox(sandboxId);
+    await activities.inMemoryTestDestroySandbox(sandboxId);
+
+    const restoredId = await activities.inMemoryTestRestoreSandbox(snapshot);
+    const restored = await manager.getSandbox(restoredId);
+    expect(await restored.fs.readFile("/greeting.txt")).toBe("hello");
+  });
+
+  it("deleteSandboxSnapshot activity is a no-op for in-memory snapshots", async () => {
+    const activities = manager.createActivities("Test");
+
+    const created = await activities.inMemoryTestCreateSandbox();
+    const { sandboxId } = created as { sandboxId: string };
+
+    const snapshot = await activities.inMemoryTestSnapshotSandbox(sandboxId);
+    await expect(
+      activities.inMemoryTestDeleteSandboxSnapshot(snapshot)
+    ).resolves.toBeUndefined();
+  });
 });
 
 describe("InMemorySandboxProvider", () => {

package/src/lib/sandbox/tree.integration.test.ts

@@ -3,7 +3,10 @@ import { toTree } from "./tree";
 import type { SandboxFileSystem, DirentEntry } from "./types";
 
 function createMockFs(
-  structure: Record<string, { isDir: boolean; isLink?: boolean; linkTarget?: string }>,
+  structure: Record<
+    string,
+    { isDir: boolean; isLink?: boolean; linkTarget?: string }
+  >
 ): SandboxFileSystem {
   return {
     workspaceBase: "/",
@@ -21,13 +24,17 @@ function createMockFs(
     readdir: async (dir: string) => {
       const prefix = dir.endsWith("/") ? dir : dir + "/";
       return Object.keys(structure)
-        .filter((p) => p.startsWith(prefix) && !p.slice(prefix.length).includes("/"))
+        .filter(
+          (p) => p.startsWith(prefix) && !p.slice(prefix.length).includes("/")
+        )
         .map((p) => p.slice(prefix.length));
     },
     readdirWithFileTypes: async (dir: string): Promise<DirentEntry[]> => {
       const prefix = dir.endsWith("/") ? dir : dir + "/";
       return Object.entries(structure)
-        .filter(([p]) => p.startsWith(prefix) && !p.slice(prefix.length).includes("/"))
+        .filter(
+          ([p]) => p.startsWith(prefix) && !p.slice(prefix.length).includes("/")
+        )
         .map(([p, meta]) => ({
           name: p.slice(prefix.length),
           isFile: !meta.isDir && !meta.isLink,

package/src/lib/sandbox/types.ts

@@ -17,6 +17,21 @@ export interface FileStat {
   mtime: Date;
 }
 
+// ============================================================================
+// Network & lifecycle
+// ============================================================================
+
+export interface SandboxNetworkConfig {
+  allowOut?: string[];
+  denyOut?: string[];
+  allowPublicTraffic?: boolean;
+}
+
+export interface SandboxLifecycleConfig {
+  onTimeout: "kill" | "pause";
+  autoResume?: boolean;
+}
+
 /**
  * Provider-agnostic filesystem interface.
  *
@@ -114,6 +129,16 @@ export interface SandboxCreateOptions {
   initialFiles?: Record<string, string | Uint8Array>;
   /** Environment variables available inside the sandbox */
   env?: Record<string, string>;
+  /** Key-value metadata surfaced via provider list/query APIs */
+  metadata?: Record<string, string>;
+  /** Sandbox idle timeout in milliseconds */
+  timeoutMs?: number;
+  /** Enable or disable outbound internet access */
+  allowInternetAccess?: boolean;
+  /** Outbound network allow/deny rules */
+  network?: SandboxNetworkConfig;
+  /** Sandbox timeout behaviour */
+  lifecycle?: SandboxLifecycleConfig;
 }
 
 export interface SandboxCreateResult {
@@ -135,6 +160,8 @@ export interface SandboxProvider<
   resume(sandboxId: string): Promise<void>;
   snapshot(sandboxId: string): Promise<SandboxSnapshot>;
   restore(snapshot: SandboxSnapshot): Promise<Sandbox>;
+  /** Delete a previously captured snapshot. No-op if already deleted. */
+  deleteSnapshot(snapshot: SandboxSnapshot): Promise<void>;
   fork(sandboxId: string): Promise<Sandbox>;
 }
 
@@ -155,6 +182,10 @@ export interface SandboxOps<
   /** Resume a paused sandbox. No-op if already running. */
   resumeSandbox(sandboxId: string): Promise<void>;
   snapshotSandbox(sandboxId: string): Promise<SandboxSnapshot>;
+  /** Create a fresh sandbox from a previously captured snapshot. */
+  restoreSandbox(snapshot: SandboxSnapshot): Promise<string>;
+  /** Delete a previously captured snapshot. No-op if already deleted. */
+  deleteSandboxSnapshot(snapshot: SandboxSnapshot): Promise<void>;
   forkSandbox(sandboxId: string): Promise<string>;
 }
 
@@ -172,7 +203,10 @@ export type PrefixedSandboxOps<
   TOptions extends SandboxCreateOptions = SandboxCreateOptions,
   TCtx = unknown,
 > = {
-  [K in keyof SandboxOps<TOptions, TCtx> as `${TPrefix}${Capitalize<K & string>}`]: SandboxOps<TOptions, TCtx>[K];
+  [K in keyof SandboxOps<
+    TOptions,
+    TCtx
+  > as `${TPrefix}${Capitalize<K & string>}`]: SandboxOps<TOptions, TCtx>[K];
 };
 
 // ============================================================================

package/src/lib/session/session-edge-cases.integration.test.ts

@@ -42,7 +42,13 @@ vi.mock("@temporalio/workflow", () => {
     uuid4: () =>
       `00000000-0000-0000-0000-${String(++idCounter).padStart(12, "0")}`,
     ApplicationFailure: MockApplicationFailure,
-    log: { trace: () => {}, debug: () => {}, info: () => {}, warn: () => {}, error: () => {} },
+    log: {
+      trace: () => {},
+      debug: () => {},
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+    },
   };
 });
 
@@ -61,7 +67,9 @@ type TurnScript = {
  * Wraps every method on a ThreadOps object so it also has `.executeWithOptions()`,
  * matching Temporal's `ActivityInterfaceFor<ThreadOps>` shape.
  */
-function toActivityInterface<TContent = string>(raw: ThreadOps<TContent>): ActivityInterfaceFor<ThreadOps<TContent>> {
+function toActivityInterface<TContent = string>(
+  raw: ThreadOps<TContent>
+): ActivityInterfaceFor<ThreadOps<TContent>> {
   const result = {} as Record<string, unknown>;
   for (const [key, fn] of Object.entries(raw)) {
     const wrapped = (...args: unknown[]) =>
@@ -433,6 +441,8 @@ describe("createSession edge cases", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sandbox-id",
+      restoreSandbox: async () => "restored-sandbox-id",
+      deleteSandboxSnapshot: async () => {},
       pauseSandbox: async () => {},
       resumeSandbox: async () => {},
     };
@@ -476,6 +486,8 @@ describe("createSession edge cases", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sandbox-id",
+      restoreSandbox: async () => "restored-sandbox-id",
+      deleteSandboxSnapshot: async () => {},
       pauseSandbox: async () => {},
       resumeSandbox: async () => {},
     };
@@ -765,7 +777,11 @@ describe("createSession edge cases", () => {
       },
     });
 
-    const session = await createSession<Record<string, never>, unknown, TestContent>({
+    const session = await createSession<
+      Record<string, never>,
+      unknown,
+      TestContent
+    >({
       agentName: "TestAgent",
       thread: { mode: "new", threadId: "thread-1" },
       runAgent: createScriptedRunAgent([{ message: "done", toolCalls: [] }]),
@@ -940,6 +956,8 @@ describe("createSession edge cases", () => {
       destroySandbox: async () => {},
       snapshotSandbox: snapshotSpy,
       forkSandbox: async () => "forked-sandbox-id",
+      restoreSandbox: async () => "restored-sandbox-id",
+      deleteSandboxSnapshot: async () => {},
       pauseSandbox: async () => {},
       resumeSandbox: async () => {},
     };
@@ -1040,6 +1058,8 @@ describe("createSession edge cases", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sb",
+      restoreSandbox: async () => "restored-sb",
+      deleteSandboxSnapshot: async () => {},
     };
 
     const session = await createSession({
@@ -1074,6 +1094,8 @@ describe("createSession edge cases", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sb",
+      restoreSandbox: async () => "restored-sb",
+      deleteSandboxSnapshot: async () => {},
     };
 
     const session = await createSession({
@@ -1119,6 +1141,8 @@ describe("createSession edge cases", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sb",
+      restoreSandbox: async () => "restored-sb",
+      deleteSandboxSnapshot: async () => {},
     };
 
     const session = await createSession({
@@ -1166,6 +1190,8 @@ describe("createSession edge cases", () => {
         sandboxLog.push(`fork:${id}`);
         return `forked-from-${id}`;
       },
+      restoreSandbox: async () => "restored-sb",
+      deleteSandboxSnapshot: async () => {},
     };
 
     const session = await createSession({
@@ -1186,7 +1212,9 @@ describe("createSession edge cases", () => {
 
     expect(sandboxLog).toContain("fork:paused-sb-1");
     expect(sandboxLog).not.toContain("create");
-    expect((result as { sandboxId?: string }).sandboxId).toBe("forked-from-paused-sb-1");
+    expect((result as { sandboxId?: string }).sandboxId).toBe(
+      "forked-from-paused-sb-1"
+    );
     expect(sandboxLog).toContain("destroy:forked-from-paused-sb-1");
   });
 
@@ -1210,6 +1238,8 @@ describe("createSession edge cases", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sb",
+      restoreSandbox: async () => "restored-sb",
+      deleteSandboxSnapshot: async () => {},
     };
 
     const session = await createSession({
@@ -1253,6 +1283,8 @@ describe("createSession edge cases", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sb",
+      restoreSandbox: async () => "restored-sb",
+      deleteSandboxSnapshot: async () => {},
     };
 
     const session = await createSession({
@@ -1297,6 +1329,8 @@ describe("createSession edge cases", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sb",
+      restoreSandbox: async () => "restored-sb",
+      deleteSandboxSnapshot: async () => {},
     };
 
     const session = await createSession({
@@ -1370,9 +1404,7 @@ describe("createSession edge cases", () => {
 
     const session = await createSession({
       agentName: "TestAgent",
-      runAgent: createScriptedRunAgent([
-        { message: "done", toolCalls: [] },
-      ]),
+      runAgent: createScriptedRunAgent([{ message: "done", toolCalls: [] }]),
       threadOps: ops,
       buildContextMessage: () => "go",
     });
@@ -1413,6 +1445,8 @@ describe("createSession edge cases", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sb",
+      restoreSandbox: async () => "restored-sb",
+      deleteSandboxSnapshot: async () => {},
     };
 
     const session = await createSession({
@@ -1431,9 +1465,7 @@ describe("createSession edge cases", () => {
       initialState: { systemPrompt: "test" },
     });
 
-    await expect(session.runSession({ stateManager })).rejects.toThrow(
-      "crash"
-    );
+    await expect(session.runSession({ stateManager })).rejects.toThrow("crash");
 
     expect(sandboxLog).toContain("pause:sb-err");
     expect(sandboxLog).not.toContain("destroy:sb-err");
@@ -1461,6 +1493,8 @@ describe("createSession edge cases", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sb",
+      restoreSandbox: async () => "restored-sb",
+      deleteSandboxSnapshot: async () => {},
     };
 
     const session = await createSession({
@@ -1503,6 +1537,8 @@ describe("createSession edge cases", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sb",
+      restoreSandbox: async () => "restored-sb",
+      deleteSandboxSnapshot: async () => {},
     };
 
     const session = await createSession({
@@ -1521,9 +1557,7 @@ describe("createSession edge cases", () => {
       initialState: { systemPrompt: "test" },
     });
 
-    await expect(session.runSession({ stateManager })).rejects.toThrow(
-      "crash"
-    );
+    await expect(session.runSession({ stateManager })).rejects.toThrow("crash");
 
     expect(sandboxLog).not.toContain("pause:sb-keep-err");
     expect(sandboxLog).not.toContain("destroy:sb-keep-err");
@@ -1553,6 +1587,8 @@ describe("createSession edge cases", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sb",
+      restoreSandbox: async () => "restored-sb",
+      deleteSandboxSnapshot: async () => {},
     };
 
     const session = await createSession({
@@ -1598,6 +1634,8 @@ describe("createSession edge cases", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sb",
+      restoreSandbox: async () => "restored-sb",
+      deleteSandboxSnapshot: async () => {},
     };
 
     const session = await createSession({

package/src/lib/session/session.integration.test.ts

@@ -517,6 +517,8 @@ describe("createSession integration", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sandbox-id",
+      restoreSandbox: async () => "restored-sandbox-id",
+      deleteSandboxSnapshot: async () => {},
       pauseSandbox: async () => {},
       resumeSandbox: async () => {},
     };
@@ -559,6 +561,8 @@ describe("createSession integration", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sandbox-id",
+      restoreSandbox: async () => "restored-sandbox-id",
+      deleteSandboxSnapshot: async () => {},
       pauseSandbox: async () => {},
       resumeSandbox: async () => {},
     };
@@ -610,6 +614,8 @@ describe("createSession integration", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sb",
+      restoreSandbox: async () => "restored-sb",
+      deleteSandboxSnapshot: async () => {},
     };
 
     const session = await createSession({
@@ -822,6 +828,8 @@ describe("createSession integration", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sandbox-id",
+      restoreSandbox: async () => "restored-sandbox-id",
+      deleteSandboxSnapshot: async () => {},
       pauseSandbox: async () => {},
       resumeSandbox: async () => {},
     };
@@ -873,6 +881,8 @@ describe("createSession integration", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sandbox-id",
+      restoreSandbox: async () => "restored-sandbox-id",
+      deleteSandboxSnapshot: async () => {},
       pauseSandbox: async () => {},
       resumeSandbox: async () => {},
     };
@@ -949,4 +959,133 @@ describe("createSession integration", () => {
     expect(result.usage.totalInputTokens).toBe(180);
     expect(result.usage.totalOutputTokens).toBe(90);
   });
+
+  // --- Snapshot-driven shutdown ---
+
+  it("captures base + exit snapshot and destroys sandbox on sandboxShutdown=snapshot", async () => {
+    const { ops } = createMockThreadOps();
+    const sandboxLog: string[] = [];
+    let snapCounter = 0;
+
+    const sandboxOps: SandboxOps = {
+      createSandbox: async () => {
+        sandboxLog.push("create");
+        return { sandboxId: "sb-snap" };
+      },
+      destroySandbox: async (id: string) => {
+        sandboxLog.push(`destroy:${id}`);
+      },
+      pauseSandbox: async () => {
+        sandboxLog.push("pause");
+      },
+      resumeSandbox: async () => {},
+      snapshotSandbox: async (id: string) => {
+        snapCounter += 1;
+        sandboxLog.push(`snapshot:${id}`);
+        return {
+          sandboxId: id,
+          providerId: "test",
+          data: { tag: `snap-${snapCounter}` },
+          createdAt: new Date().toISOString(),
+        };
+      },
+      restoreSandbox: async () => "restored-sb",
+      deleteSandboxSnapshot: async () => {},
+      forkSandbox: async () => "forked-sb",
+    };
+
+    const session = await createSession({
+      agentName: "TestAgent",
+      thread: { mode: "new", threadId: "thread-snap" },
+      runAgent: createScriptedRunAgent([{ message: "done", toolCalls: [] }]),
+      threadOps: ops,
+      buildContextMessage: () => "go",
+      sandboxOps,
+      sandboxShutdown: "snapshot",
+    });
+
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "test" },
+    });
+
+    const result = await session.runSession({ stateManager });
+
+    expect(result.exitReason).toBe("completed");
+    expect(result.sandboxId).toBe("sb-snap");
+    expect(result.baseSnapshot?.data).toEqual({ tag: "snap-1" });
+    expect(result.snapshot?.data).toEqual({ tag: "snap-2" });
+    expect(sandboxLog).toEqual([
+      "create",
+      "snapshot:sb-snap",
+      "snapshot:sb-snap",
+      "destroy:sb-snap",
+    ]);
+    expect(sandboxLog).not.toContain("pause");
+  });
+
+  it("restores a sandbox when sandbox.mode=from-snapshot and skips base snapshot", async () => {
+    const { ops } = createMockThreadOps();
+    const sandboxLog: string[] = [];
+    const priorSnapshot = {
+      sandboxId: "sb-prior",
+      providerId: "test",
+      data: { tag: "prior" },
+      createdAt: new Date().toISOString(),
+    };
+
+    const sandboxOps: SandboxOps = {
+      createSandbox: async () => {
+        sandboxLog.push("create");
+        return { sandboxId: "sb-should-not-be-created" };
+      },
+      destroySandbox: async (id: string) => {
+        sandboxLog.push(`destroy:${id}`);
+      },
+      pauseSandbox: async () => {},
+      resumeSandbox: async () => {},
+      snapshotSandbox: async (id: string) => {
+        sandboxLog.push(`snapshot:${id}`);
+        return {
+          sandboxId: id,
+          providerId: "test",
+          data: { tag: "exit" },
+          createdAt: new Date().toISOString(),
+        };
+      },
+      restoreSandbox: async (snap) => {
+        sandboxLog.push(`restore:${(snap.data as { tag: string }).tag}`);
+        return "sb-restored";
+      },
+      deleteSandboxSnapshot: async () => {},
+      forkSandbox: async () => "forked-sb",
+    };
+
+    const session = await createSession({
+      agentName: "TestAgent",
+      thread: { mode: "new", threadId: "thread-restore" },
+      runAgent: createScriptedRunAgent([{ message: "done", toolCalls: [] }]),
+      threadOps: ops,
+      buildContextMessage: () => "go",
+      sandboxOps,
+      sandbox: { mode: "from-snapshot", snapshot: priorSnapshot },
+      sandboxShutdown: "snapshot",
+    });
+
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "test" },
+    });
+
+    const result = await session.runSession({ stateManager });
+
+    expect(result.sandboxId).toBe("sb-restored");
+    // No base snapshot because the sandbox was restored, not freshly created.
+    expect(result.baseSnapshot).toBeUndefined();
+    expect(result.snapshot?.data).toEqual({ tag: "exit" });
+    expect(sandboxLog).toEqual([
+      "restore:prior",
+      "snapshot:sb-restored",
+      "destroy:sb-restored",
+    ]);
+    expect(sandboxLog).not.toContain("create");
+  });
 });