typescript-virtual-container 1.4.7 → 1.4.8

package/src/VirtualFileSystem/index.ts

@@ -19,6 +19,7 @@ import type {
 	InternalDirectoryNode,
 	InternalFileNode,
 	InternalNode,
+	InternalStubNode,
 } from "./internalTypes";
 import { appendJournalEntry, JournalOp, readJournal, truncateJournal } from "./journal";
 import { getNode, getParentDirectory, normalizePath } from "./path";
@@ -155,14 +156,15 @@ class VirtualFileSystem extends EventEmitter {
 	// ── Internal helpers ──────────────────────────────────────────────────────
 
 	private makeDir(name: string, mode: number): InternalDirectoryNode {
-		const now = new Date();
+		const now = Date.now();
 		return {
 			type: "directory",
 			name,
 			mode,
 			createdAt: now,
 			updatedAt: now,
-			children: new Map(),
+			children: Object.create(null) as Record<string, InternalNode>,
+			_childCount: 0,
 		};
 	}
 
@@ -172,7 +174,7 @@ class VirtualFileSystem extends EventEmitter {
 		mode: number,
 		compressed: boolean,
 	): InternalFileNode {
-		const now = new Date();
+		const now = Date.now();
 		return {
 			type: "file",
 			name,
@@ -184,6 +186,35 @@ class VirtualFileSystem extends EventEmitter {
 		};
 	}
 
+	private makeStub(name: string, content: string, mode: number): InternalStubNode {
+		const now = Date.now();
+		return { type: "stub", name, stubContent: content, mode, createdAt: now, updatedAt: now };
+	}
+
+	/**
+	 * Write a lazy stub — stores content as a plain string with no Buffer allocation.
+	 * Use for static rootfs files that may never be read. On first `writeFile()`,
+	 * the stub is promoted to a real `InternalFileNode`.
+	 * Parent directories are created when missing.
+	 */
+	public writeStub(targetPath: string, content: string, mode = 0o644): void {
+		const normalized = normalizePath(targetPath);
+		const { parent, name } = getParentDirectory(
+			this.root,
+			normalized,
+			true,
+			(p) => this.mkdirRecursive(p, 0o755),
+		);
+		const existing = parent.children[name];
+		if (existing?.type === "directory") {
+			throw new Error(`Cannot write stub '${normalized}': path is a directory.`);
+		}
+		// Don't overwrite a real file or an already-promoted node
+		if (existing?.type === "file") return;
+		if (!existing) parent._childCount++;
+		parent.children[name] = this.makeStub(name, content, mode);
+	}
+
 	private mkdirRecursive(targetPath: string, mode: number): void {
 		const normalized = normalizePath(targetPath);
 		if (normalized === "/") return;
@@ -192,10 +223,11 @@ class VirtualFileSystem extends EventEmitter {
 		let builtPath = "";
 		for (const part of parts) {
 			builtPath += `/${part}`;
-			let child = current.children.get(part);
+			let child = current.children[part];
 			if (!child) {
 				child = this.makeDir(part, mode);
-				current.children.set(part, child);
+				current.children[part] = child;
+				current._childCount++;
 				this.emit("dir:create", { path: builtPath, mode });
 				this._journal({ op: JournalOp.MKDIR, path: builtPath, mode });
 			} else if (child.type !== "directory") {
@@ -338,7 +370,33 @@ class VirtualFileSystem extends EventEmitter {
 		if (this._dirty) await this.flushMirror();
 	}
 
-	// ── WAL Journal helpers ───────────────────────────────────────────────────
+	/**
+	 * Replace the entire root tree — used internally by `bootstrapLinuxRootfs`
+	 * to hot-swap the static rootfs snapshot without going through importSnapshot
+	 * (which would re-journal every node in fs mode).
+	 * @internal
+	 */
+	public importRootTree(root: InternalDirectoryNode): void {
+		const prev = this._replayMode;
+		this._replayMode = true;
+		try { this.root = root; } finally { this._replayMode = prev; }
+	}
+
+	/** Serialise current tree to VFSB binary. Used for the static rootfs cache. */
+	public encodeBinary(): Buffer {
+		return encodeVfs(this.root);
+	}
+
+	/**
+	 * Release the in-memory VFS tree, freeing all InternalNode objects for GC.
+	 * The tree MUST be restored via `importRootTree()` before any VFS operation.
+	 * Called by IdleManager when freezing an idle shell.
+	 * @internal
+	 */
+	public releaseTree(): void {
+		// Replace root with a minimal stub — keeps the object alive but frees all children
+		this.root = this.makeDir("", 0o755);
+	}
 
 	/** Set to true during journal replay to suppress re-journaling. */
 	private _replayMode = false;
@@ -392,10 +450,10 @@ class VirtualFileSystem extends EventEmitter {
 	}
 
 	private _evictDir(dir: InternalDirectoryNode): void {
-		for (const node of dir.children.values()) {
+		for (const node of Object.values(dir.children)) {
 			if (node.type === "directory") {
 				this._evictDir(node);
-			} else if (!node.evicted) {
+			} else if (node.type === "file" && !node.evicted) {
 				const rawSize = node.compressed
 					? (node.size ?? node.content.length * 2) // estimate uncompressed
 					: node.content.length;
@@ -405,6 +463,7 @@ class VirtualFileSystem extends EventEmitter {
 					node.evicted = true;
 				}
 			}
+			// stubs: nothing to evict — content is already a plain string, not a Buffer
 		}
 	}
 
@@ -423,7 +482,7 @@ class VirtualFileSystem extends EventEmitter {
 			let cur: InternalNode = tmpRoot;
 			for (const part of parts) {
 				if (cur.type !== "directory") return;
-				const next = cur.children.get(part);
+				const next: InternalNode | undefined = cur.children[part];
 				if (!next) return;
 				cur = next;
 			}
@@ -569,7 +628,7 @@ class VirtualFileSystem extends EventEmitter {
 			(p) => this.mkdirRecursive(p, 0o755),
 		);
 
-		const existing = parent.children.get(name);
+		const existing = parent.children[name];
 		if (existing?.type === "directory") {
 			throw new Error(
 				`Cannot write file '${normalized}': path is a directory.`,
@@ -583,17 +642,17 @@ class VirtualFileSystem extends EventEmitter {
 		const storedContent = shouldCompress ? gzipSync(rawContent) : rawContent;
 		const mode = options.mode ?? 0o644;
 
-		if (existing) {
+		if (existing && existing.type === "file") {
+			// Update real file in place
 			const f = existing as InternalFileNode;
 			f.content = storedContent;
 			f.compressed = shouldCompress;
 			f.mode = mode;
-			f.updatedAt = new Date();
+			f.updatedAt = Date.now();
 		} else {
-			parent.children.set(
-				name,
-				this.makeFile(name, storedContent, mode, shouldCompress),
-			);
+			// Create new real file — also promotes stubs (no _childCount change for stubs)
+			if (!existing) parent._childCount++;
+			parent.children[name] = this.makeFile(name, storedContent, mode, shouldCompress);
 		}
 
 		this.emit("file:write", { path: normalized, size: storedContent.length });
@@ -612,6 +671,10 @@ class VirtualFileSystem extends EventEmitter {
 		}
 		const normalized = normalizePath(targetPath);
 		const node = getNode(this.root, normalized);
+		if (node.type === "stub") {
+			this.emit("file:read", { path: normalized, size: node.stubContent.length });
+			return node.stubContent;
+		}
 		if (node.type !== "file") {
 			throw new Error(`Cannot read '${targetPath}': not a file.`);
 		}
@@ -631,6 +694,11 @@ class VirtualFileSystem extends EventEmitter {
 		}
 		const normalized = normalizePath(targetPath);
 		const node = getNode(this.root, normalized);
+		if (node.type === "stub") {
+			const buf = Buffer.from(node.stubContent, "utf8");
+			this.emit("file:read", { path: normalized, size: buf.length });
+			return buf;
+		}
 		if (node.type !== "file") {
 			throw new Error(`Cannot read '${targetPath}': not a file.`);
 		}
@@ -693,6 +761,19 @@ class VirtualFileSystem extends EventEmitter {
 		const normalized = normalizePath(targetPath);
 		const node = getNode(this.root, normalized);
 		const name = normalized === "/" ? "" : path.posix.basename(normalized);
+		if (node.type === "stub") {
+			const s = node as InternalStubNode;
+			return {
+				type: "file",
+				name,
+				path: normalized,
+				mode: s.mode,
+				createdAt: new Date(s.createdAt),
+				updatedAt: new Date(s.updatedAt),
+				compressed: false,
+				size: s.stubContent.length,
+			};
+		}
 		if (node.type === "file") {
 			const f = node as InternalFileNode;
 			return {
@@ -700,8 +781,8 @@ class VirtualFileSystem extends EventEmitter {
 				name,
 				path: normalized,
 				mode: f.mode,
-				createdAt: f.createdAt,
-				updatedAt: f.updatedAt,
+				createdAt: new Date(f.createdAt),
+				updatedAt: new Date(f.updatedAt),
 				compressed: f.compressed,
 				size: f.evicted ? (f.size ?? 0) : f.content.length,
 			};
@@ -712,9 +793,9 @@ class VirtualFileSystem extends EventEmitter {
 			name,
 			path: normalized,
 			mode: d.mode,
-			createdAt: d.createdAt,
-			updatedAt: d.updatedAt,
-			childrenCount: d.children.size,
+			createdAt: new Date(d.createdAt),
+			updatedAt: new Date(d.updatedAt),
+			childrenCount: d._childCount,
 		};
 	}
 
@@ -732,7 +813,7 @@ class VirtualFileSystem extends EventEmitter {
 		if (node.type !== "directory") {
 			throw new Error(`Cannot list '${dirPath}': not a directory.`);
 		}
-		return Array.from((node as InternalDirectoryNode).children.keys()).sort();
+		return Object.keys((node as InternalDirectoryNode).children).sort();
 	}
 
 	/** Renders ASCII tree view of a directory hierarchy. */
@@ -748,10 +829,10 @@ class VirtualFileSystem extends EventEmitter {
 
 	private renderTreeLines(dir: InternalDirectoryNode, label: string): string {
 		const lines = [label];
-		const entries = Array.from(dir.children.keys()).sort();
+		const entries = Object.keys(dir.children).sort();
 		for (let i = 0; i < entries.length; i++) {
 			const name = entries[i]!;
-			const child = dir.children.get(name)!;
+			const child = dir.children[name]!;
 			const isLast = i === entries.length - 1;
 			const connector = isLast ? "└── " : "├── ";
 			const nextPrefix = isLast ? "    " : "│   ";
@@ -774,8 +855,9 @@ class VirtualFileSystem extends EventEmitter {
 
 	private computeUsage(node: InternalNode): number {
 		if (node.type === "file") return (node as InternalFileNode).content.length;
+		if (node.type === "stub") return node.stubContent.length;
 		let total = 0;
-		for (const child of (node as InternalDirectoryNode).children.values()) {
+		for (const child of Object.values((node as InternalDirectoryNode).children)) {
 			total += this.computeUsage(child);
 		}
 		return total;
@@ -790,7 +872,7 @@ class VirtualFileSystem extends EventEmitter {
 		if (!f.compressed) {
 			f.content = gzipSync(f.content);
 			f.compressed = true;
-			f.updatedAt = new Date();
+			f.updatedAt = Date.now();
 		}
 	}
 
@@ -803,7 +885,7 @@ class VirtualFileSystem extends EventEmitter {
 		if (f.compressed) {
 			f.content = gunzipSync(f.content);
 			f.compressed = false;
-			f.updatedAt = new Date();
+			f.updatedAt = Date.now();
 		}
 	}
 
@@ -828,10 +910,11 @@ class VirtualFileSystem extends EventEmitter {
 			content: Buffer.from(normalizedTarget, "utf8"),
 			mode: 0o120777,
 			compressed: false,
-			createdAt: new Date(),
-			updatedAt: new Date(),
+			createdAt: Date.now(),
+			updatedAt: Date.now(),
 		};
-		parent.children.set(name, symNode);
+		parent.children[name] = symNode;
+		parent._childCount++;
 		// Journal before emit
 		this._journal({ op: JournalOp.SYMLINK, path: normalizedLink, dest: normalizedTarget });
 		this.emit("symlink:create", {
@@ -895,7 +978,7 @@ class VirtualFileSystem extends EventEmitter {
 		const node = getNode(this.root, normalized);
 		if (node.type === "directory") {
 			const dir = node as InternalDirectoryNode;
-			if (!options.recursive && dir.children.size > 0) {
+			if (!options.recursive && dir._childCount > 0) {
 				throw new Error(
 					`Directory '${normalized}' is not empty. Use recursive option.`,
 				);
@@ -907,8 +990,8 @@ class VirtualFileSystem extends EventEmitter {
 			false,
 			() => {},
 		);
-		parent.children.delete(name);
-		this.emit("node:remove", { path: normalized });
+		delete parent.children[name];
+		parent._childCount--;		this.emit("node:remove", { path: normalized });
 		this._journal({ op: JournalOp.REMOVE, path: normalized });
 	}
 
@@ -936,9 +1019,11 @@ class VirtualFileSystem extends EventEmitter {
 			false,
 			() => {},
 		);
-		srcParent.children.delete(srcName);
+		delete srcParent.children[srcName];
+		srcParent._childCount--;
 		node.name = destName;
-		destParent.children.set(destName, node);
+		destParent.children[destName] = node;
+		destParent._childCount++;
 		this._journal({ op: JournalOp.MOVE, path: fromNormalized, dest: toNormalized });
 	}
 
@@ -956,19 +1041,30 @@ class VirtualFileSystem extends EventEmitter {
 
 	private serializeDir(dir: InternalDirectoryNode): VfsSnapshotDirectoryNode {
 		const children: VfsSnapshotNode[] = [];
-		for (const child of dir.children.values()) {
-			children.push(
-				child.type === "file"
-					? this.serializeFile(child as InternalFileNode)
-					: this.serializeDir(child as InternalDirectoryNode),
-			);
+		for (const child of Object.values(dir.children)) {
+			if (child.type === "stub") {
+				// Serialize stub as a regular file node
+				children.push({
+					type: "file",
+					name: child.name,
+					mode: child.mode,
+					createdAt: new Date(child.createdAt).toISOString(),
+					updatedAt: new Date(child.updatedAt).toISOString(),
+					compressed: false,
+					contentBase64: Buffer.from(child.stubContent, "utf8").toString("base64"),
+				} satisfies VfsSnapshotFileNode);
+			} else if (child.type === "file") {
+				children.push(this.serializeFile(child as InternalFileNode));
+			} else {
+				children.push(this.serializeDir(child as InternalDirectoryNode));
+			}
 		}
 		return {
 			type: "directory",
 			name: dir.name,
 			mode: dir.mode,
-			createdAt: dir.createdAt.toISOString(),
-			updatedAt: dir.updatedAt.toISOString(),
+			createdAt: new Date(dir.createdAt).toISOString(),
+			updatedAt: new Date(dir.updatedAt).toISOString(),
 			children,
 		};
 	}
@@ -978,8 +1074,8 @@ class VirtualFileSystem extends EventEmitter {
 			type: "file",
 			name: file.name,
 			mode: file.mode,
-			createdAt: file.createdAt.toISOString(),
-			updatedAt: file.updatedAt.toISOString(),
+			createdAt: new Date(file.createdAt).toISOString(),
+			updatedAt: new Date(file.updatedAt).toISOString(),
 			compressed: file.compressed,
 			contentBase64: file.content.toString("base64"),
 		};
@@ -1021,29 +1117,31 @@ class VirtualFileSystem extends EventEmitter {
 			type: "directory",
 			name,
 			mode: snap.mode,
-			createdAt: new Date(snap.createdAt),
-			updatedAt: new Date(snap.updatedAt),
-			children: new Map(),
+			createdAt: Date.parse(snap.createdAt),
+			updatedAt: Date.parse(snap.updatedAt),
+			children: Object.create(null) as Record<string, InternalNode>,
+			_childCount: 0,
 		};
 		for (const child of snap.children) {
 			if (child.type === "file") {
 				const f = child as VfsSnapshotFileNode;
-				dir.children.set(f.name, {
+				dir.children[f.name] = {
 					type: "file",
 					name: f.name,
 					mode: f.mode,
-					createdAt: new Date(f.createdAt),
-					updatedAt: new Date(f.updatedAt),
+					createdAt: Date.parse(f.createdAt),
+					updatedAt: Date.parse(f.updatedAt),
 					compressed: f.compressed,
 					content: Buffer.from(f.contentBase64, "base64"),
-				});
+				};
 			} else {
 				const sub = this.deserializeDir(
 					child as VfsSnapshotDirectoryNode,
 					child.name,
 				);
-				dir.children.set(child.name, sub);
+				dir.children[child.name] = sub;
 			}
+			dir._childCount++;
 		}
 		return dir;
 	}

package/src/VirtualFileSystem/internalTypes.ts

@@ -1,10 +1,12 @@
-export type InternalNode = InternalFileNode | InternalDirectoryNode;
+export type InternalNode = InternalFileNode | InternalStubNode | InternalDirectoryNode;
 
 interface InternalBaseNode {
 	name: string;
 	mode: number;
-	createdAt: Date;
-	updatedAt: Date;
+	/** Unix timestamp in ms — avoids Date object overhead (~80 bytes each). */
+	createdAt: number;
+	/** Unix timestamp in ms. */
+	updatedAt: number;
 }
 
 export interface InternalFileNode extends InternalBaseNode {
@@ -17,7 +19,21 @@ export interface InternalFileNode extends InternalBaseNode {
 	size?: number;
 }
 
+/**
+ * Lazy stub — stores static rootfs file content as a plain string.
+ * No Buffer allocation until the file is actually read or written.
+ * On first write, promoted to a real InternalFileNode.
+ */
+export interface InternalStubNode extends InternalBaseNode {
+	type: "stub";
+	/** Raw UTF-8 content — never compressed, never evicted. */
+	stubContent: string;
+}
+
 export interface InternalDirectoryNode extends InternalBaseNode {
 	type: "directory";
-	children: Map<string, InternalNode>;
+	/** Null-prototype object — avoids Map overhead (~40% less RAM per entry). */
+	children: Record<string, InternalNode>;
+	/** Cached child count — avoids O(n) Object.keys() on hot paths. */
+	_childCount: number;
 }

package/src/VirtualFileSystem/path.ts

@@ -33,7 +33,7 @@ export function getNode(
 			throw new Error(`Path '${normalized}' does not exist.`);
 		}
 
-		const next = current.children.get(part);
+		const next: InternalNode | undefined = current.children[part];
 		if (!next) {
 			throw new Error(`Path '${normalized}' does not exist.`);
 		}

package/src/VirtualShell/idleManager.ts

@@ -0,0 +1,133 @@
+/**
+ * IdleManager — cold-start / freeze-thaw system for VirtualShell.
+ *
+ * When a shell has had no activity for `idleThresholdMs`, the VFS tree is
+ * serialised to a compact binary buffer and the in-memory tree is released.
+ * On the next command the tree is reconstructed in ~0.1 ms.
+ *
+ * Memory freed per idle shell: the full JS object graph (~250+ InternalNodes
+ * for a typical rootfs + user files). The frozen buffer itself stays in RAM
+ * but is ~27% smaller than the live tree and GC-friendly (one flat Buffer).
+ *
+ * CPU freed: the VFS auto-flush setInterval is suspended while frozen.
+ *
+ * Usage:
+ * ```ts
+ * const idle = new IdleManager(shell, { idleThresholdMs: 60_000 });
+ * idle.start();
+ * // call idle.ping() on every shell activity (exec, keypress, …)
+ * // call idle.stop() on shell destroy
+ * ```
+ */
+
+import { EventEmitter } from "node:events";
+import type VirtualFileSystem from "../VirtualFileSystem";
+import { decodeVfs } from "../VirtualFileSystem/binaryPack";
+
+export interface IdleManagerOptions {
+	/**
+	 * Milliseconds of inactivity before the shell is frozen.
+	 * Default: 60_000 (1 minute).
+	 */
+	idleThresholdMs?: number;
+	/**
+	 * How often the idle check runs.
+	 * Default: 15_000 (15 seconds).
+	 */
+	checkIntervalMs?: number;
+}
+
+export type IdleState = "active" | "frozen";
+
+export class IdleManager extends EventEmitter {
+	private readonly vfs: VirtualFileSystem;
+	private readonly idleThresholdMs: number;
+	private readonly checkIntervalMs: number;
+
+	private _state: IdleState = "active";
+	private _lastActivity = Date.now();
+	private _frozenBuffer: Buffer | null = null;
+	private _checkTimer: ReturnType<typeof setInterval> | null = null;
+
+	/** Emitted when the shell is frozen (VFS tree released). */
+	declare on: ((event: "freeze", listener: () => void) => this) &
+		((event: "thaw", listener: () => void) => this) &
+		((event: string, listener: (...args: unknown[]) => void) => this);
+
+	constructor(vfs: VirtualFileSystem, options: IdleManagerOptions = {}) {
+		super();
+		this.vfs = vfs;
+		this.idleThresholdMs = options.idleThresholdMs ?? 60_000;
+		this.checkIntervalMs = options.checkIntervalMs ?? 15_000;
+	}
+
+	/** Start monitoring for idle. Call once after shell initialisation. */
+	public start(): void {
+		if (this._checkTimer) return;
+		this._lastActivity = Date.now();
+		this._checkTimer = setInterval(() => this._check(), this.checkIntervalMs);
+		// Don't block process exit
+		if (typeof this._checkTimer === "object" && this._checkTimer !== null && "unref" in this._checkTimer) {
+			(this._checkTimer as NodeJS.Timeout).unref();
+		}
+	}
+
+	/** Stop monitoring and thaw if frozen. Call on shell destroy. */
+	public async stop(): Promise<void> {
+		if (this._checkTimer) {
+			clearInterval(this._checkTimer);
+			this._checkTimer = null;
+		}
+		if (this._state === "frozen") await this._thaw();
+	}
+
+	/**
+	 * Signal activity — resets the idle clock and thaws if frozen.
+	 * Call this before every exec / keypress / session event.
+	 */
+	public async ping(): Promise<void> {
+		this._lastActivity = Date.now();
+		if (this._state === "frozen") await this._thaw();
+	}
+
+	/** Current idle state. */
+	public get state(): IdleState {
+		return this._state;
+	}
+
+	/** Ms since last activity. */
+	public get idleMs(): number {
+		return Date.now() - this._lastActivity;
+	}
+
+	// ── Internal ──────────────────────────────────────────────────────────────
+
+	private _check(): void {
+		if (this._state === "frozen") return; // already frozen
+		if (Date.now() - this._lastActivity >= this.idleThresholdMs) {
+			void this._freeze();
+		}
+	}
+
+	private async _freeze(): Promise<void> {
+		if (this._state === "frozen") return;
+		// Flush any pending writes before freezing
+		await this.vfs.stopAutoFlush();
+		// Serialise the live tree to a compact binary buffer
+		this._frozenBuffer = this.vfs.encodeBinary();
+		// Release the live tree — GC can now collect all InternalNode objects
+		this.vfs.releaseTree();
+		this._state = "frozen";
+		this.emit("freeze");
+	}
+
+	private async _thaw(): Promise<void> {
+		if (this._state !== "frozen" || !this._frozenBuffer) return;
+		// Reconstruct the tree from the frozen buffer (~0.07 ms for typical rootfs)
+		const root = decodeVfs(this._frozenBuffer);
+		this.vfs.importRootTree(root);
+		this._frozenBuffer = null;
+		this._state = "active";
+		this.emit("thaw");
+	}
+}

package/src/VirtualShell/index.ts

@@ -14,6 +14,7 @@ import { createPerfLogger } from "../utils/perfLogger";
 import VirtualFileSystem, { type VfsOptions } from "../VirtualFileSystem";
 import { VirtualPackageManager } from "../VirtualPackageManager";
 import { VirtualUserManager } from "../VirtualUserManager";
+import { IdleManager, type IdleManagerOptions } from "./idleManager";
 import { startShell } from "./shell";
 
 /**
@@ -143,6 +144,8 @@ class VirtualShell extends EventEmitter {
 	properties: ShellProperties;
 	/** Unix ms timestamp of shell creation — used by `uptime` and `/proc/uptime`. */
 	startTime: number;
+	/** Idle / cold-start manager — null until `enableIdleManagement()` is called. */
+	private _idle: IdleManager | null = null;
 	private initialized: Promise<void>;
 
 	/**
@@ -236,6 +239,7 @@ class VirtualShell extends EventEmitter {
 	 */
 	executeCommand(rawInput: string, authUser: string, cwd: string): void {
 		perf.mark("executeCommand");
+		if (this._idle) void this._idle.ping();
 		runCommand(rawInput, authUser, this.hostname, "shell", cwd, this);
 		this.emit("command", { command: rawInput, user: authUser, cwd });
 	}
@@ -262,6 +266,7 @@ class VirtualShell extends EventEmitter {
 		terminalSize: { cols: number; rows: number },
 	): void {
 		perf.mark("startInteractiveSession");
+		if (this._idle) void this._idle.ping();
 		// Interactive shell logic
 		this.emit("session:start", { user: authUser, sessionId, remoteAddress });
 		startShell(
@@ -404,6 +409,49 @@ class VirtualShell extends EventEmitter {
 		this.users.assertWriteWithinQuota(authUser, targetPath, content);
 		this.vfs.writeFile(targetPath, content);
 	}
+
+	/**
+	 * Enable idle detection and cold-start freeze/thaw for this shell.
+	 *
+	 * After `idleThresholdMs` of inactivity the VFS tree is serialised and
+	 * released from RAM. The next command transparently restores it in ~0.1 ms.
+	 *
+	 * @example
+	 * ```ts
+	 * await shell.ensureInitialized();
+	 * shell.enableIdleManagement({ idleThresholdMs: 60_000 });
+	 * ```
+	 */
+	public enableIdleManagement(options?: IdleManagerOptions): void {
+		if (this._idle) return; // already enabled
+		this._idle = new IdleManager(this.vfs, options);
+		this._idle.on("freeze", () => this.emit("shell:freeze"));
+		this._idle.on("thaw",   () => this.emit("shell:thaw"));
+		this._idle.start();
+	}
+
+	/**
+	 * Disable idle management and thaw the shell if currently frozen.
+	 * Safe to call even if idle management was never enabled.
+	 */
+	public async disableIdleManagement(): Promise<void> {
+		if (!this._idle) return;
+		await this._idle.stop();
+		this._idle = null;
+	}
+
+	/**
+	 * Current idle state — `"active"` or `"frozen"`.
+	 * Returns `"active"` when idle management is disabled.
+	 */
+	public get idleState(): "active" | "frozen" {
+		return this._idle?.state ?? "active";
+	}
+
+	/** Milliseconds since last shell activity. 0 when idle management is disabled. */
+	public get idleMs(): number {
+		return this._idle?.idleMs ?? 0;
+	}
 }
 
 export { VirtualShell };