sandbox 3.0.0-beta.22 → 3.0.0-beta.24

package/dist/{app-BvadkI4m.mjs → app-CpryW0ai.mjs}

@@ -15,10 +15,11 @@ import childProcess, { execFile } from "node:child_process";
 import fs, { constants, writeFile } from "node:fs/promises";
 import fs$1, { createWriteStream } from "node:fs";
 import * as Auth from "@vercel/sandbox/dist/auth/index.js";
-import { OAuth, getAuth, inferScope, pollForToken, updateAuthConfig } from "@vercel/sandbox/dist/auth/index.js";
+import { NotOk, OAuth, getAuth, inferScope, pollForToken, updateAuthConfig } from "@vercel/sandbox/dist/auth/index.js";
 import { EOL } from "os";
 import { z } from "zod/v4";
 import { z as z$1 } from "zod";
+import retry from "async-retry";
 import { APIError, Sandbox, Snapshot } from "@vercel/sandbox";
 import readline from "node:readline";
 import { randomUUID } from "crypto";
@@ -1997,7 +1998,7 @@ var require_parser$1 = /* @__PURE__ */ __commonJS$1({ "../../node_modules/.pnpm/
 	};
 	Object.defineProperty(exports, "__esModule", { value: true });
 	exports.parse = parse$5;
-	const debug$6 = (0, __importDefault$1(__require$1("debug")).default)("cmd-ts:parser");
+	const debug$7 = (0, __importDefault$1(__require$1("debug")).default)("cmd-ts:parser");
 	/**
 	* Create an AST from a token list
 	*
@@ -2005,14 +2006,14 @@ var require_parser$1 = /* @__PURE__ */ __commonJS$1({ "../../node_modules/.pnpm/
 	* @param forceFlag Keys to force as flag. {@see ForceFlag} to read more about it.
 	*/
 	function parse$5(tokens, forceFlag) {
-		if (debug$6.enabled) {
+		if (debug$7.enabled) {
 			const registered = {
 				shortFlags: [...forceFlag.forceFlagShortNames],
 				longFlags: [...forceFlag.forceFlagLongNames],
 				shortOptions: [...forceFlag.forceOptionShortNames],
 				longOptions: [...forceFlag.forceOptionLongNames]
 			};
-			debug$6("Registered:", JSON.stringify(registered));
+			debug$7("Registered:", JSON.stringify(registered));
 		}
 		const nodes = [];
 		let index = 0;
@@ -2143,9 +2144,9 @@ var require_parser$1 = /* @__PURE__ */ __commonJS$1({ "../../node_modules/.pnpm/
 			}
 			index++;
 		}
-		if (debug$6.enabled) {
+		if (debug$7.enabled) {
 			const objectNodes = nodes.map((node) => ({ [node.type]: node.raw }));
-			debug$6("Parsed items:", JSON.stringify(objectNodes));
+			debug$7("Parsed items:", JSON.stringify(objectNodes));
 		}
 		return nodes;
 	}
@@ -6755,7 +6756,7 @@ function _usingCtx() {
 //#region src/commands/login.ts
 var import_cjs$23 = /* @__PURE__ */ __toESM(require_cjs());
 init_source();
-const debug$5 = createDebugger("sandbox:login");
+const debug$6 = createDebugger("sandbox:login");
 const login = import_cjs$23.command({
 	name: "login",
 	description: "Log in to the Sandbox CLI",
@@ -6797,13 +6798,13 @@ const login = import_cjs$23.command({
 				oauth
 			})) switch (event._tag) {
 				case "Timeout":
-					debug$5(`Connection timeout. Slowing down, polling every ${event.newInterval / 1e3}s...`);
+					debug$6(`Connection timeout. Slowing down, polling every ${event.newInterval / 1e3}s...`);
 					break;
 				case "SlowDown":
-					debug$5(`Authorization server requests to slow down. Polling every ${event.newInterval / 1e3}s...`);
+					debug$6(`Authorization server requests to slow down. Polling every ${event.newInterval / 1e3}s...`);
 					break;
 				case "Response":
-					debug$5("Device Access Token response:", await event.response.text());
+					debug$6("Device Access Token response:", await event.response.text());
 					break;
 				case "Error":
 					error = event.error;
@@ -6977,7 +6978,20 @@ var require_dist = /* @__PURE__ */ __commonJS$1({ "../../node_modules/.pnpm/@ver
 var import_cjs$22 = /* @__PURE__ */ __toESM(require_cjs());
 init_source();
 var import_dist = require_dist();
-const debug$4 = createDebugger("sandbox:args:auth");
+const debug$5 = createDebugger("sandbox:args:auth");
+/**
+* Timestamp (ms epoch) of the most recent auto-login. Used to identify
+* tokens so that the first 401/403 against a freshly-issued token can be
+* retried instead of surfaced to the user.
+*/
+let freshTokenAcquiredAt;
+const FRESH_TOKEN_WINDOW_MS = 1e4;
+function isTokenFresh() {
+	return freshTokenAcquiredAt !== void 0 && Date.now() - freshTokenAcquiredAt < FRESH_TOKEN_WINDOW_MS;
+}
+function markTokenAsFresh() {
+	freshTokenAcquiredAt = Date.now();
+}
 const token = import_cjs$22.option({
 	long: "token",
 	description: "A Vercel authentication token. If not provided, will use the token stored in your system from `VERCEL_AUTH_TOKEN` or will start a log in process.",
@@ -6990,18 +7004,20 @@ const token = import_cjs$22.option({
 			if (process.env.VERCEL_OIDC_TOKEN) try {
 				return await (0, import_dist.getVercelOidcToken)();
 			} catch (cause) {
-				debug$4(`Failed to get or refresh OIDC token: ${getMessage(cause)}`);
+				debug$5(`Failed to get or refresh OIDC token: ${getMessage(cause)}`);
 				console.warn(source_default.yellow(`${source_default.bold("warn:")} failed to get or refresh OIDC token, using personal token authentication.`));
 			}
 			try {
 				return await (0, import_dist.getVercelToken)();
 			} catch (error) {
 				if (error instanceof import_dist.AccessTokenMissingError || error instanceof import_dist.RefreshAccessTokenFailedError) {
-					debug$4(`CLI token unavailable (${error.name}), prompting for login...`);
+					debug$5(`CLI token unavailable (${error.name}), prompting for login...`);
 					console.warn(source_default.yellow(`${source_default.bold("notice:")} Your session has expired. Please log in again.`));
 					await login.handler({});
 					try {
-						return await (0, import_dist.getVercelToken)();
+						const refreshed = await (0, import_dist.getVercelToken)();
+						markTokenAsFresh();
+						return refreshed;
 					} catch (retryError) {
 						throw new Error([
 							`Failed to retrieve authentication token.`,
@@ -7062,18 +7078,18 @@ function readProjectConfiguration(cwd) {
 
 //#endregion
 //#region src/util/infer-scope.ts
-const debug$3 = createDebugger("sandbox:scope");
+const debug$4 = createDebugger("sandbox:scope");
 async function inferScope$1({ token: token$1, team: team$1 }) {
 	const jwt = z.jwt().safeParse(token$1);
 	if (jwt.success) {
-		debug$3("trying to infer scope from OIDC JWT");
+		debug$4("trying to infer scope from OIDC JWT");
 		const data = await inferFromJwt(jwt.data);
-		debug$3("Using scope from OIDC JWT", data);
+		debug$4("Using scope from OIDC JWT", data);
 		return data;
 	}
 	const projectJson = readProjectConfiguration(process.cwd());
 	if (projectJson) {
-		debug$3("Using scope from project configuration", {
+		debug$4("Using scope from project configuration", {
 			owner: projectJson.orgId,
 			project: projectJson.projectId
 		});
@@ -7082,12 +7098,12 @@ async function inferScope$1({ token: token$1, team: team$1 }) {
 			project: projectJson.projectId
 		};
 	}
-	debug$3("trying to infer scope from API token", {
+	debug$4("trying to infer scope from API token", {
 		token: token$1,
 		team: team$1
 	});
 	const fromToken = await inferFromToken(token$1, team$1);
-	debug$3("Using scope from API token", fromToken);
+	debug$4("Using scope from API token", fromToken);
 	return fromToken;
 }
 const JwtSchema = z.object({
@@ -7123,6 +7139,44 @@ async function inferFromToken(token$1, requestedTeam) {
 	};
 }
 
+//#endregion
+//#region src/util/fresh-auth-retry.ts
+const debug$3 = createDebugger("sandbox:fresh-auth-retry");
+/**
+* Run an async operation, transparently retrying on 401/403 when the auth
+* token was just acquired via auto-login.
+*/
+async function withFreshAuthRetry(factory) {
+	return retry(async (bail, attempt) => {
+		try {
+			return await factory();
+		} catch (error) {
+			const status = getAuthFailureStatus(error);
+			if (status !== void 0 && isTokenFresh()) {
+				debug$3(`fresh-auth retry attempt ${attempt} (status ${status})`);
+				throw error;
+			}
+			bail(error);
+			return;
+		}
+	}, {
+		retries: 3,
+		minTimeout: 250,
+		factor: 2,
+		maxRetryTime: 3e3
+	});
+}
+/**
+* Returns the HTTP status if the error represents a 401 or 403.
+* Returns undefined for any other error.
+*/
+function getAuthFailureStatus(error) {
+	let status;
+	if (error instanceof APIError) status = error.response.status;
+	else if (error instanceof NotOk) status = error.response.statusCode;
+	return status === 401 || status === 403 ? status : void 0;
+}
+
 //#endregion
 //#region src/args/scope.ts
 var import_cjs$21 = /* @__PURE__ */ __toESM(require_cjs());
@@ -7190,10 +7244,10 @@ const scope = {
 		let projectSlug;
 		let teamSlug;
 		if (typeof projectId.value === "undefined" || typeof teamId.value === "undefined") try {
-			const scope$1 = await inferScope$1({
+			const scope$1 = await withFreshAuthRetry(() => inferScope$1({
 				token: t.value,
 				team: teamId.value
-			});
+			}));
 			projectId.value ?? (projectId.value = scope$1.project);
 			teamId.value ?? (teamId.value = scope$1.owner);
 			projectSlug = scope$1.projectSlug;
@@ -7236,7 +7290,7 @@ const scope = {
 
 //#endregion
 //#region package.json
-var version = "3.0.0-beta.22";
+var version = "3.0.0-beta.24";
 
 //#endregion
 //#region src/error.ts
@@ -7255,29 +7309,33 @@ init_source();
 * A {@link Sandbox} wrapper that adds user-agent headers and error handling.
 */
 const sandboxClient = {
-	get: (params) => withErrorHandling(Sandbox.get({
+	get: (params) => withErrorHandling(() => Sandbox.get({
 		fetch: fetchWithUserAgent,
 		resume: false,
 		...params
 	})),
-	create: (params) => withErrorHandling(Sandbox.create({
+	create: (params) => withErrorHandling(() => Sandbox.create({
 		fetch: fetchWithUserAgent,
 		...params
 	})),
-	list: (params) => withErrorHandling(Sandbox.list({
+	list: (params) => withErrorHandling(() => Sandbox.list({
 		fetch: fetchWithUserAgent,
 		...params
 	}))
 };
 const snapshotClient = {
-	list: (params) => withErrorHandling(Snapshot.list({
+	list: (params) => withErrorHandling(() => Snapshot.list({
 		fetch: fetchWithUserAgent,
 		...params
 	})),
-	get: (params) => withErrorHandling(Snapshot.get({ ...params })),
-	fromSandbox: (name, opts) => withErrorHandling(Snapshot.fromSandbox(name, {
+	get: (params) => withErrorHandling(() => Snapshot.get({ ...params })),
+	fromSandbox: (name, opts) => withErrorHandling(() => Snapshot.fromSandbox(name, {
 		fetch: fetchWithUserAgent,
 		...opts
+	})),
+	tree: (params) => withErrorHandling(() => Snapshot.tree({
+		fetch: fetchWithUserAgent,
+		...params
 	}))
 };
 const fetchWithUserAgent = (input, init$1) => {
@@ -7291,9 +7349,9 @@ const fetchWithUserAgent = (input, init$1) => {
 		headers
 	});
 };
-async function withErrorHandling(promise) {
+async function withErrorHandling(factory) {
 	try {
-		return await promise;
+		return await withFreshAuthRetry(factory);
 	} catch (error) {
 		if (error instanceof APIError) return await handleApiError(error);
 		throw error;
@@ -11621,6 +11679,30 @@ const args$2 = {
 		type: import_cjs$14.optional(SnapshotExpiration),
 		description: "Default snapshot expiration. Use \"none\" or 0 for no expiration. Example: 7d, 30d"
 	}),
+	keepLastSnapshots: import_cjs$14.option({
+		long: "keep-last-snapshots",
+		type: import_cjs$14.optional(import_cjs$14.extendType(import_cjs$14.number, {
+			displayName: "COUNT",
+			async from(n) {
+				if (!Number.isInteger(n) || n < 1 || n > 10) throw new Error(`Invalid --keep-last-snapshots value: ${n}. Must be an integer between 1 and 10.`);
+				return n;
+			}
+		})),
+		description: "Keep only the N most recent snapshots of this sandbox (1-10)."
+	}),
+	keepLastSnapshotsFor: import_cjs$14.option({
+		long: "keep-last-snapshots-for",
+		type: import_cjs$14.optional(SnapshotExpiration),
+		description: "Expiration applied to kept snapshots. Use \"none\" or 0 for no expiration. Example: 7d, 30d"
+	}),
+	deleteEvictedSnapshots: import_cjs$14.option({
+		long: "delete-evicted-snapshots",
+		type: import_cjs$14.optional({
+			...import_cjs$14.oneOf(["true", "false"]),
+			displayName: "true|false"
+		}),
+		description: "When \"true\" (the default), evicted snapshots are deleted immediately; when \"false\", they keep the default expiration."
+	}),
 	...networkPolicyArgs,
 	scope
 };
@@ -11632,7 +11714,7 @@ const create = import_cjs$14.command({
 		description: "Create and connect to a sandbox without a network access",
 		command: `sandbox run --network-policy=none --connect`
 	}],
-	async handler({ name, nonPersistent, ports, scope: scope$1, runtime: runtime$1, timeout: timeout$1, vcpus: vcpus$1, silent, snapshot: snapshot$1, sandboxSnapshot, connect: connect$2, envVars, tags, snapshotExpiration, networkPolicy: networkPolicyMode$1, allowedDomains: allowedDomains$1, allowedCIDRs: allowedCIDRs$1, deniedCIDRs: deniedCIDRs$1 }) {
+	async handler({ name, nonPersistent, ports, scope: scope$1, runtime: runtime$1, timeout: timeout$1, vcpus: vcpus$1, silent, snapshot: snapshot$1, sandboxSnapshot, connect: connect$2, envVars, tags, snapshotExpiration, keepLastSnapshots, keepLastSnapshotsFor, deleteEvictedSnapshots, networkPolicy: networkPolicyMode$1, allowedDomains: allowedDomains$1, allowedCIDRs: allowedCIDRs$1, deniedCIDRs: deniedCIDRs$1 }) {
 		if (snapshot$1 && sandboxSnapshot) throw new Error([`Cannot use --snapshot and --sandbox-snapshot together.`, `${source_default.bold("hint:")} Pick one source for the new sandbox.`].join("\n"));
 		const networkPolicy$1 = buildNetworkPolicy({
 			networkPolicy: networkPolicyMode$1,
@@ -11640,6 +11722,12 @@ const create = import_cjs$14.command({
 			allowedCIDRs: allowedCIDRs$1,
 			deniedCIDRs: deniedCIDRs$1
 		});
+		if (keepLastSnapshots === void 0 && (keepLastSnapshotsFor !== void 0 || deleteEvictedSnapshots !== void 0)) throw new Error(["--keep-last-snapshots-for and --delete-evicted-snapshots require --keep-last-snapshots.", `${source_default.bold("hint:")} Pass --keep-last-snapshots <count> to enable the retention policy.`].join("\n"));
+		const keepLastSnapshotsPayload = keepLastSnapshots !== void 0 ? {
+			count: keepLastSnapshots,
+			expiration: keepLastSnapshotsFor !== void 0 ? (0, import_ms$2.default)(keepLastSnapshotsFor) : void 0,
+			deleteEvicted: deleteEvictedSnapshots !== void 0 ? deleteEvictedSnapshots === "true" : void 0
+		} : void 0;
 		const persistent = !nonPersistent;
 		const resources = vcpus$1 ? { vcpus: vcpus$1 } : void 0;
 		const tagsObj = Object.keys(tags).length > 0 ? tags : void 0;
@@ -11666,6 +11754,7 @@ const create = import_cjs$14.command({
 			tags: tagsObj,
 			persistent,
 			snapshotExpiration: snapshotExpiration ? (0, import_ms$2.default)(snapshotExpiration) : void 0,
+			keepLastSnapshots: keepLastSnapshotsPayload,
 			__interactive: true
 		}) : await sandboxClient.create({
 			name,
@@ -11681,6 +11770,7 @@ const create = import_cjs$14.command({
 			tags: tagsObj,
 			persistent,
 			snapshotExpiration: snapshotExpiration ? (0, import_ms$2.default)(snapshotExpiration) : void 0,
+			keepLastSnapshots: keepLastSnapshotsPayload,
 			__interactive: true
 		});
 		spinner?.stop();
@@ -14501,6 +14591,75 @@ const snapshot = import_cjs$6.command({
 	}
 });
 
+//#endregion
+//#region src/util/snapshot-tree.ts
+init_source();
+function formatExpires(expiresAt) {
+	if (expiresAt === void 0) return source_default.gray("never");
+	const ms$4 = expiresAt - Date.now();
+	if (ms$4 <= 0) return source_default.red("expired");
+	const formatted = timeAgo(expiresAt);
+	return ms$4 <= 3600 * 1e3 ? source_default.red(formatted) : source_default.green(formatted);
+}
+function renderNode(id, expiresAt, isCurrent) {
+	const bullet = isCurrent ? source_default.magenta.bold("●") : source_default.magenta("●");
+	const suffix = isCurrent ? `  ${source_default.green("◂ current")}` : "";
+	return `${bullet} ${source_default.yellow(id)}   expires: ${formatExpires(expiresAt)}${suffix}`;
+}
+function renderSiblings(siblings, count) {
+	const lines = [];
+	const shown = siblings.slice(0, 5);
+	const totalCount = parseInt(count, 10);
+	const hasPlus = count.endsWith("+");
+	const remaining = totalCount - 1 - shown.length;
+	for (let i = 0; i < shown.length; i++) {
+		const connector = i === shown.length - 1 && remaining <= 0 ? "╰──" : "├──";
+		lines.push(`│   ${connector} ${source_default.gray(shown[i].sourceSessionId)}`);
+	}
+	if (remaining > 0) {
+		const suffix = hasPlus ? "+" : "";
+		lines.push(`│   ╰── ${source_default.gray(`+${remaining}${suffix} more sandboxes`)}`);
+	}
+	return lines;
+}
+function renderSnapshotTree(params) {
+	const { ancestors, descendants } = params;
+	const hideCurrent = params.hideCurrent === true;
+	const currentSnapshotId = hideCurrent ? void 0 : params.currentSnapshotId;
+	const lines = [];
+	const pushNode = (node, isCurrent) => {
+		lines.push("│");
+		lines.push(renderNode(node.snapshot.id, node.snapshot.expiresAt, isCurrent));
+		if (node.siblings.length > 0) lines.push(...renderSiblings(node.siblings, node.count));
+	};
+	const descendantNodes = descendants.snapshots.filter((n) => n.snapshot.id !== currentSnapshotId);
+	if (descendantNodes.length > 0) for (const node of [...descendantNodes].reverse()) pushNode(node, false);
+	if (!hideCurrent) {
+		const { currentSnapshotId: id, currentSnapshotExpiresAt } = params;
+		pushNode(ancestors.snapshots.find((n) => n.snapshot.id === id) ?? descendants.snapshots.find((n) => n.snapshot.id === id) ?? {
+			snapshot: {
+				id,
+				sourceSessionId: "",
+				expiresAt: currentSnapshotExpiresAt
+			},
+			siblings: [],
+			count: "1"
+		}, true);
+	}
+	const ancestorNodes = ancestors.snapshots.filter((n) => n.snapshot.id !== currentSnapshotId);
+	for (const node of ancestorNodes) pushNode(node, false);
+	if (!hideCurrent) {
+		const lastAncestor = ancestorNodes[ancestorNodes.length - 1];
+		if (ancestors.pagination.next === null) {
+			if (lastAncestor && !lastAncestor.snapshot.parentId || ancestorNodes.length === 0) {
+				lines.push("│");
+				lines.push(`${source_default.white("○")} ${source_default.gray("(root)")}`);
+			}
+		}
+	}
+	return lines.join("\n");
+}
+
 //#endregion
 //#region src/commands/snapshots.ts
 var import_cjs$4 = /* @__PURE__ */ __toESM(require_cjs());
@@ -14651,12 +14810,154 @@ const remove$1 = import_cjs$4.command({
 		}
 	}
 });
+const tree = import_cjs$4.command({
+	name: "tree",
+	description: "Show the snapshot ancestry tree for a sandbox.",
+	args: {
+		scope,
+		sandboxName: import_cjs$4.positional({
+			type: sandboxName,
+			description: "Sandbox name"
+		}),
+		sortOrder: import_cjs$4.option({
+			long: "sort-order",
+			description: "Sort order. Options: asc, desc (default). 'desc' walks ancestors, 'asc' walks descendants. Requires --cursor.",
+			type: import_cjs$4.optional(import_cjs$4.oneOf(["asc", "desc"]))
+		}),
+		limit: import_cjs$4.option({
+			long: "limit",
+			description: "Maximum number of snapshots per page (1–10, default 10).",
+			type: import_cjs$4.optional(import_cjs$4.number)
+		}),
+		cursor: import_cjs$4.option({
+			long: "cursor",
+			description: "Pagination cursor from a previous 'More ancestors' or 'More descendants' hint.",
+			type: import_cjs$4.optional(import_cjs$4.string)
+		})
+	},
+	async handler({ scope: { token: token$1, team: team$1, project: project$1 }, sandboxName: name, sortOrder, limit, cursor }) {
+		if (limit !== void 0 && (limit < 1 || limit > 10)) {
+			console.error(source_default.red("Error: --limit must be between 1 and 10."));
+			process.exitCode = 1;
+			return;
+		}
+		if (sortOrder !== void 0 && !cursor) {
+			console.error(source_default.red("Error: --sort-order requires --cursor."));
+			process.exitCode = 1;
+			return;
+		}
+		const pageLimit = limit ?? 10;
+		if (cursor) {
+			const effectiveSortOrder = sortOrder ?? "desc";
+			const page = await (async () => {
+				try {
+					var _usingCtx4 = _usingCtx();
+					const _spinner$1 = _usingCtx4.u(acquireRelease(() => ora("Fetching snapshot tree...").start(), (s$1) => s$1.stop()));
+					return snapshotClient.tree({
+						snapshotId: cursor,
+						sortOrder: effectiveSortOrder,
+						limit: pageLimit,
+						token: token$1,
+						teamId: team$1,
+						projectId: project$1
+					});
+				} catch (_) {
+					_usingCtx4.e = _;
+				} finally {
+					_usingCtx4.d();
+				}
+			})();
+			const ancestors = effectiveSortOrder === "desc" ? page : {
+				snapshots: [],
+				pagination: {
+					count: 0,
+					next: null
+				}
+			};
+			const descendants = effectiveSortOrder === "asc" ? page : {
+				snapshots: [],
+				pagination: {
+					count: 0,
+					next: null
+				}
+			};
+			console.log(renderSnapshotTree({
+				hideCurrent: true,
+				ancestors,
+				descendants
+			}));
+			if (page.pagination.next !== null) console.log(formatNextCursorHint(page.pagination.next));
+			return;
+		}
+		const result = await (async () => {
+			try {
+				var _usingCtx5 = _usingCtx();
+				const _spinner$1 = _usingCtx5.u(acquireRelease(() => ora("Fetching snapshot tree...").start(), (s$1) => s$1.stop()));
+				const currentSnapshotId = (await sandboxClient.get({
+					name,
+					token: token$1,
+					teamId: team$1,
+					projectId: project$1
+				})).currentSnapshotId;
+				if (!currentSnapshotId) return null;
+				const [currentSnap, ancestors, descendants] = await Promise.all([
+					snapshotClient.get({
+						snapshotId: currentSnapshotId,
+						token: token$1,
+						teamId: team$1,
+						projectId: project$1
+					}),
+					snapshotClient.tree({
+						snapshotId: currentSnapshotId,
+						sortOrder: "desc",
+						limit: pageLimit,
+						token: token$1,
+						teamId: team$1,
+						projectId: project$1
+					}),
+					snapshotClient.tree({
+						snapshotId: currentSnapshotId,
+						sortOrder: "asc",
+						limit: pageLimit,
+						token: token$1,
+						teamId: team$1,
+						projectId: project$1
+					})
+				]);
+				return {
+					currentSnap,
+					currentSnapshotId,
+					ancestors,
+					descendants
+				};
+			} catch (_) {
+				_usingCtx5.e = _;
+			} finally {
+				_usingCtx5.d();
+			}
+		})();
+		if (!result) {
+			console.log(source_default.yellow("No snapshots found for this sandbox."));
+			return;
+		}
+		console.log(renderSnapshotTree({
+			currentSnapshotId: result.currentSnapshotId,
+			currentSnapshotExpiresAt: result.currentSnap.expiresAt?.getTime(),
+			ancestors: result.ancestors,
+			descendants: result.descendants
+		}));
+		const limitArg = limit !== void 0 ? ` --limit ${limit}` : "";
+		if (result.ancestors.pagination.next !== null) console.log(`\nMore ancestors: sandbox snapshots tree ${name} --sort-order desc${limitArg} --cursor ${result.ancestors.pagination.next}`);
+		if (result.descendants.pagination.next !== null) console.log(`More descendants: sandbox snapshots tree ${name} --sort-order asc${limitArg} --cursor ${result.descendants.pagination.next}`);
+	}
+});
 const snapshots = (0, import_cjs$5.subcommands)({
 	name: "snapshots",
 	description: "Manage sandbox snapshots",
 	cmds: {
 		list: list$2,
 		get,
+		tree,
 		delete: remove$1
 	}
 });
@@ -14910,6 +15211,136 @@ const snapshotExpirationCommand = import_cjs$1.command({
 		}
 	}
 });
+const keepLastCountType = import_cjs$1.extendType(import_cjs$1.number, {
+	displayName: "COUNT",
+	async from(n) {
+		if (!Number.isInteger(n) || n < 0 || n > 10) throw new Error(`Invalid count: ${n}. Must be an integer between 0 and 10 (0 removes the policy).`);
+		return n;
+	}
+});
+const keepLastSnapshotsCommand = import_cjs$1.command({
+	name: "keep-last-snapshots",
+	description: "Update the snapshot retention policy (keep only the N most recent snapshots) of a sandbox",
+	args: {
+		sandbox: import_cjs$1.positional({
+			type: sandboxName,
+			description: "Sandbox name to update"
+		}),
+		count: import_cjs$1.positional({
+			type: keepLastCountType,
+			description: "Number of most recent snapshots to keep (1-10). Pass 0 to remove the policy."
+		}),
+		scope
+	},
+	async handler({ scope: { token: token$1, team: team$1, project: project$1 }, sandbox: name, count }) {
+		const sandbox = await sandboxClient.get({
+			name,
+			projectId: project$1,
+			teamId: team$1,
+			token: token$1
+		});
+		const spinner = ora("Updating sandbox configuration...").start();
+		try {
+			if (count === 0) await sandbox.update({ keepLastSnapshots: null });
+			else {
+				const current = sandbox.keepLastSnapshots;
+				await sandbox.update({ keepLastSnapshots: {
+					count,
+					expiration: current?.expiration,
+					deleteEvicted: current?.deleteEvicted
+				} });
+			}
+			spinner.stop();
+			process.stderr.write("✅ Configuration updated for sandbox " + source_default.cyan(name) + "\n");
+			process.stderr.write(source_default.dim("   ╰ ") + "keep-last-snapshots: " + source_default.cyan(count === 0 ? "cleared" : `count=${count}`) + "\n");
+		} catch (error) {
+			spinner.stop();
+			throw error;
+		}
+	}
+});
+const keepLastSnapshotsForCommand = import_cjs$1.command({
+	name: "keep-last-snapshots-for",
+	description: "Update the expiration applied to snapshots kept by the retention policy",
+	args: {
+		sandbox: import_cjs$1.positional({
+			type: sandboxName,
+			description: "Sandbox name to update"
+		}),
+		duration: import_cjs$1.positional({
+			type: SnapshotExpiration,
+			description: "Expiration for kept snapshots. Use \"none\" or 0 for no expiration. Example: 7d, 30d"
+		}),
+		scope
+	},
+	async handler({ scope: { token: token$1, team: team$1, project: project$1 }, sandbox: name, duration }) {
+		const sandbox = await sandboxClient.get({
+			name,
+			projectId: project$1,
+			teamId: team$1,
+			token: token$1
+		});
+		const current = sandbox.keepLastSnapshots;
+		if (!current) throw new Error(["No keep-last-snapshots policy is set on this sandbox.", `${source_default.bold("hint:")} Set a count first with: sandbox config keep-last-snapshots ${name} <count>`].join("\n"));
+		const spinner = ora("Updating sandbox configuration...").start();
+		try {
+			await sandbox.update({ keepLastSnapshots: {
+				count: current.count,
+				expiration: (0, import_ms.default)(duration),
+				deleteEvicted: current.deleteEvicted
+			} });
+			spinner.stop();
+			const display = (0, import_ms.default)(duration) === 0 ? "none" : duration;
+			process.stderr.write("✅ Configuration updated for sandbox " + source_default.cyan(name) + "\n");
+			process.stderr.write(source_default.dim("   ╰ ") + "keep-last-snapshots-for: " + source_default.cyan(display) + "\n");
+		} catch (error) {
+			spinner.stop();
+			throw error;
+		}
+	}
+});
+const deleteEvictedSnapshotsCommand = import_cjs$1.command({
+	name: "delete-evicted-snapshots",
+	description: "When \"true\" (the default), snapshots evicted by the keep-last-snapshots policy are deleted immediately; when \"false\", they keep the default expiration.",
+	args: {
+		sandbox: import_cjs$1.positional({
+			type: sandboxName,
+			description: "Sandbox name to update"
+		}),
+		value: import_cjs$1.positional({
+			type: {
+				...import_cjs$1.oneOf(["true", "false"]),
+				displayName: "true|false"
+			},
+			description: "Whether to delete evicted snapshots immediately (\"true\") or let them keep the default expiration (\"false\")."
+		}),
+		scope
+	},
+	async handler({ scope: { token: token$1, team: team$1, project: project$1 }, sandbox: name, value }) {
+		const sandbox = await sandboxClient.get({
+			name,
+			projectId: project$1,
+			teamId: team$1,
+			token: token$1
+		});
+		const current = sandbox.keepLastSnapshots;
+		if (!current) throw new Error(["No keep-last-snapshots policy is set on this sandbox.", `${source_default.bold("hint:")} Set a count first with: sandbox config keep-last-snapshots ${name} <count>`].join("\n"));
+		const spinner = ora("Updating sandbox configuration...").start();
+		try {
+			await sandbox.update({ keepLastSnapshots: {
+				count: current.count,
+				expiration: current.expiration,
+				deleteEvicted: value === "true"
+			} });
+			spinner.stop();
+			process.stderr.write("✅ Configuration updated for sandbox " + source_default.cyan(name) + "\n");
+			process.stderr.write(source_default.dim("   ╰ ") + "delete-evicted-snapshots: " + source_default.cyan(value) + "\n");
+		} catch (error) {
+			spinner.stop();
+			throw error;
+		}
+	}
+});
 const currentSnapshotCommand = import_cjs$1.command({
 	name: "current-snapshot",
 	description: "Update the current snapshot of a sandbox",
@@ -14994,6 +15425,10 @@ const listCommand = import_cjs$1.command({
 				field: "Snapshot expiration",
 				value: sandbox.snapshotExpiration != null && sandbox.snapshotExpiration > 0 ? (0, import_ms.default)(sandbox.snapshotExpiration, { long: true }) : sandbox.snapshotExpiration === 0 ? "none" : "-"
 			},
+			{
+				field: "Keep last snapshots",
+				value: formatKeepLastSnapshots(sandbox.keepLastSnapshots)
+			},
 			{
 				field: "Current snapshot",
 				value: sandbox.currentSnapshotId ?? "-"
@@ -15098,6 +15533,13 @@ const tagsCommand = import_cjs$1.command({
 		}
 	}
 });
+function formatKeepLastSnapshots(keepLastSnapshots) {
+	if (!keepLastSnapshots) return "-";
+	const parts = [`count=${keepLastSnapshots.count}`];
+	if (keepLastSnapshots.expiration !== void 0) parts.push(`for=${keepLastSnapshots.expiration === 0 ? "none" : (0, import_ms.default)(keepLastSnapshots.expiration, { long: true })}`);
+	if (keepLastSnapshots.deleteEvicted !== void 0) parts.push(`delete-evicted-snapshots=${keepLastSnapshots.deleteEvicted}`);
+	return parts.join(", ");
+}
 const config = import_cjs$1.subcommands({
 	name: "config",
 	description: "View and update sandbox configuration",
@@ -15108,6 +15550,9 @@ const config = import_cjs$1.subcommands({
 		persistent: persistentCommand,
 		"network-policy": networkPolicyCommand,
 		"snapshot-expiration": snapshotExpirationCommand,
+		"keep-last-snapshots": keepLastSnapshotsCommand,
+		"keep-last-snapshots-for": keepLastSnapshotsForCommand,
+		"delete-evicted-snapshots": deleteEvictedSnapshotsCommand,
 		"current-snapshot": currentSnapshotCommand,
 		tags: tagsCommand
 	}
@@ -15156,4 +15601,4 @@ const app = (opts) => (0, import_cjs.subcommands)({
 
 //#endregion
 export { source_exports as a, init_source as i, StyledError as n, require_cjs as r, app as t };
-//# sourceMappingURL=app-BvadkI4m.mjs.map
+//# sourceMappingURL=app-CpryW0ai.mjs.map