@gajae-code/coding-agent 0.12.0 → 0.12.1

package/src/session/blob-store.ts

@@ -1,22 +1,65 @@
+import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as fsp from "node:fs/promises";
 import * as path from "node:path";
-import { isEnoent, logger } from "@gajae-code/utils";
+import { isEnoent, logger, postmortem } from "@gajae-code/utils";
 
 const BLOB_PREFIX = "blob:sha256:";
+const TAKE_BLOB_BUFFER_OWNERSHIP = Symbol("takeBlobBufferOwnership");
 
 /**
  * Owner-only permissions for on-disk blob directories and files.
  *
- * Blob stores can live inside a managed session scope (e.g. the resident-cache
- * `EphemeralBlobStore` created on the explicit session path). The managed-tree
- * snapshot fails closed unless every descendant is owner-only, so blobs and
- * their directories MUST be created 0700/0600 rather than inheriting a
- * group/other-readable mode from the process umask.
+ * Generic blob stores may live inside a managed session scope, whose snapshot
+ * fails closed unless every descendant is owner-only. Resident text instead
+ * uses a verified private cache root, but its instance directories and blobs
+ * obey the same 0700/0600 contract.
  */
 const BLOB_DIR_MODE = 0o700;
 const BLOB_FILE_MODE = 0o600;
 
+const RESIDENT_CACHE_OWNER_RECORD = "owner.json";
+const RESIDENT_CACHE_GC_MAX_DIRECTORIES = 64;
+const RESIDENT_CACHE_GC_MAX_DURATION_MS = 250;
+const RESIDENT_CACHE_SWEEP_EXPECTED_IO_CODES = new Set([
+	"EACCES",
+	"EBUSY",
+	"EEXIST",
+	"EIO",
+	"EISDIR",
+	"ELOOP",
+	"EMFILE",
+	"ENAMETOOLONG",
+	"ENFILE",
+	"ENOENT",
+	"ENOTDIR",
+	"ENOTEMPTY",
+	"EPERM",
+	"EROFS",
+	"ESTALE",
+]);
+const ownedResidentCacheInstanceDirs = new Set<string>();
+const activeResidentCacheRootSweeps = new Set<string>();
+let ownResidentCacheProcessStartTimeMs: number | null | undefined;
+
+interface ResidentCacheOwnerToken {
+	readonly pid: number;
+	readonly startTimeMs: number | null;
+	readonly nonce: string;
+	readonly createdAt?: number;
+}
+
+interface ResidentCacheOwnerSnapshot {
+	readonly owner: ResidentCacheOwnerToken;
+	readonly directory: fs.Stats;
+}
+
+/** Limits for a single best-effort resident-cache garbage-collection pass. */
+export interface ResidentCacheGcSweepOptions {
+	readonly maxDirectories?: number;
+	readonly maxDurationMs?: number;
+}
+
 export interface BlobPutResult {
 	hash: string;
 	path: string;
@@ -37,6 +80,563 @@ export class BlobCorruptError extends Error {
 	}
 }
 
+/**
+ * A resident-cache path or blob failed the owner-only verification contract.
+ * SessionManager catches this error to demote the entire resident store to
+ * memory before retrying the triggering write.
+ */
+export class ResidentCacheTrustError extends Error {
+	constructor(
+		readonly reason: string,
+		readonly path: string,
+		options?: ErrorOptions,
+	) {
+		super(`Resident cache trust validation failed (${reason}): ${path}`, options);
+		this.name = "ResidentCacheTrustError";
+	}
+}
+
+function residentCacheTrustError(reason: string, pathname: string, cause?: unknown): ResidentCacheTrustError {
+	if (cause instanceof ResidentCacheTrustError) return cause;
+	return new ResidentCacheTrustError(reason, pathname, cause === undefined ? undefined : { cause });
+}
+
+function errorCode(error: unknown): string | undefined {
+	if (typeof error !== "object" || error === null || !("code" in error)) return undefined;
+	return typeof error.code === "string" ? error.code : undefined;
+}
+
+function isExpectedResidentCacheSweepFailure(error: unknown): boolean {
+	return (
+		error instanceof ResidentCacheTrustError || RESIDENT_CACHE_SWEEP_EXPECTED_IO_CODES.has(errorCode(error) ?? "")
+	);
+}
+
+function residentCacheOwnerUid(pathname: string): number {
+	if (process.platform === "win32") {
+		throw new ResidentCacheTrustError("unsupported_platform", pathname);
+	}
+	const uid = process.getuid?.();
+	if (uid === undefined) throw new ResidentCacheTrustError("owner_identity_unavailable", pathname);
+	return uid;
+}
+
+function hasOwnerOnlyMode(mode: number): boolean {
+	return (mode & 0o077) === 0;
+}
+
+function residentCacheDirectoryOpenFlags(pathname: string): number {
+	const noFollow = fs.constants.O_NOFOLLOW;
+	const directory = fs.constants.O_DIRECTORY;
+	if (!noFollow || !directory) throw new ResidentCacheTrustError("no_follow_unavailable", pathname);
+	return fs.constants.O_RDONLY | directory | noFollow;
+}
+
+function hasSameFilesystemIdentity(a: fs.Stats, b: fs.Stats): boolean {
+	return a.dev === b.dev && a.ino === b.ino;
+}
+
+function assertResidentCacheDirectory(pathname: string, uid: number): fs.Stats {
+	let stat: fs.Stats;
+	try {
+		stat = fs.lstatSync(pathname);
+	} catch (error) {
+		throw residentCacheTrustError("directory_unverifiable", pathname, error);
+	}
+	if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== uid || !hasOwnerOnlyMode(stat.mode)) {
+		throw new ResidentCacheTrustError("directory_untrusted", pathname);
+	}
+	return stat;
+}
+
+function assertResidentCacheDirectoryDescriptor(
+	pathname: string,
+	expected: fs.Stats,
+	descriptor: number,
+	uid: number,
+): void {
+	let opened: fs.Stats;
+	try {
+		opened = fs.fstatSync(descriptor);
+	} catch (error) {
+		throw residentCacheTrustError("directory_descriptor_unverifiable", pathname, error);
+	}
+	if (
+		!opened.isDirectory() ||
+		opened.uid !== uid ||
+		!hasOwnerOnlyMode(opened.mode) ||
+		!hasSameFilesystemIdentity(expected, opened)
+	) {
+		throw new ResidentCacheTrustError("directory_identity_changed", pathname);
+	}
+}
+
+function openVerifiedResidentCacheDirectory(pathname: string, uid: number): number {
+	const expected = assertResidentCacheDirectory(pathname, uid);
+	let descriptor: number | null = null;
+	try {
+		descriptor = fs.openSync(pathname, residentCacheDirectoryOpenFlags(pathname));
+		assertResidentCacheDirectoryDescriptor(pathname, expected, descriptor, uid);
+		return descriptor;
+	} catch (error) {
+		if (descriptor !== null) {
+			try {
+				fs.closeSync(descriptor);
+			} catch {
+				// Preserve the verification failure.
+			}
+		}
+		throw residentCacheTrustError("directory_open_untrusted", pathname, error);
+	}
+}
+
+function assertResidentCacheDirectoryPathMatchesDescriptor(pathname: string, descriptor: number, uid: number): void {
+	const current = assertResidentCacheDirectory(pathname, uid);
+	assertResidentCacheDirectoryDescriptor(pathname, current, descriptor, uid);
+}
+
+function residentCacheProcessStartTimeMs(pid: number): number | null {
+	if (pid === process.pid && ownResidentCacheProcessStartTimeMs !== undefined) {
+		return ownResidentCacheProcessStartTimeMs;
+	}
+
+	// Mirror file-lock's `ps`-based process incarnation probe, but pin the
+	// locale so its `lstart` output can be represented as a stable epoch value.
+	let startTimeMs: number | null = null;
+	try {
+		const result = Bun.spawnSync(["ps", "-o", "lstart=", "-p", String(pid)], {
+			stdout: "pipe",
+			stderr: "ignore",
+			env: { ...process.env, LC_ALL: "C", LANG: "C" },
+		});
+		if (result.exitCode === 0) {
+			const parsed = Date.parse(new TextDecoder().decode(result.stdout).trim());
+			if (Number.isFinite(parsed)) startTimeMs = parsed;
+		}
+	} catch {
+		// An unavailable process-start source cannot prove PID reuse.
+	}
+	if (pid === process.pid) ownResidentCacheProcessStartTimeMs = startTimeMs;
+	return startTimeMs;
+}
+
+type ResidentCacheOwnerLiveness = "alive" | "dead" | "unknown";
+
+function residentCacheOwnerLiveness(pid: number): ResidentCacheOwnerLiveness {
+	if (!Number.isFinite(pid) || pid <= 0) return "unknown";
+	try {
+		process.kill(pid, 0);
+		return "alive";
+	} catch (error) {
+		const code = errorCode(error);
+		if (code === "ESRCH") return "dead";
+		// EPERM means the process exists but the current user cannot signal it.
+		// All other errors leave liveness indeterminate and fail closed.
+		return code === "EPERM" ? "alive" : "unknown";
+	}
+}
+
+function isTrustedResidentCacheOwnerFile(stat: fs.Stats, uid: number): boolean {
+	return (
+		stat.isFile() &&
+		!stat.isSymbolicLink() &&
+		stat.uid === uid &&
+		hasOwnerOnlyMode(stat.mode) &&
+		stat.size <= 16 * 1024
+	);
+}
+
+function parseResidentCacheOwnerToken(text: string): ResidentCacheOwnerToken | null {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		return null;
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+	const { pid, startTimeMs, nonce, createdAt } = parsed as {
+		pid?: unknown;
+		startTimeMs?: unknown;
+		nonce?: unknown;
+		createdAt?: unknown;
+	};
+	if (
+		typeof pid !== "number" ||
+		!Number.isInteger(pid) ||
+		pid <= 0 ||
+		(startTimeMs !== null && (typeof startTimeMs !== "number" || !Number.isFinite(startTimeMs))) ||
+		typeof nonce !== "string" ||
+		nonce.length === 0 ||
+		(createdAt !== undefined && (typeof createdAt !== "number" || !Number.isFinite(createdAt)))
+	) {
+		return null;
+	}
+	return createdAt === undefined ? { pid, startTimeMs, nonce } : { pid, startTimeMs, nonce, createdAt };
+}
+
+function sameResidentCacheOwnerToken(a: ResidentCacheOwnerToken, b: ResidentCacheOwnerToken): boolean {
+	return a.pid === b.pid && a.startTimeMs === b.startTimeMs && a.nonce === b.nonce && a.createdAt === b.createdAt;
+}
+
+function readResidentCacheOwnerSnapshot(instanceDir: string, uid: number): ResidentCacheOwnerSnapshot | null {
+	let descriptor: number | null = null;
+	try {
+		descriptor = openVerifiedResidentCacheDirectory(instanceDir, uid);
+		assertResidentCacheDirectoryPathMatchesDescriptor(instanceDir, descriptor, uid);
+		const directory = fs.fstatSync(descriptor);
+		const ownerPath = path.join(instanceDir, RESIDENT_CACHE_OWNER_RECORD);
+		const before = fs.lstatSync(ownerPath);
+		if (!isTrustedResidentCacheOwnerFile(before, uid)) return null;
+		const owner = parseResidentCacheOwnerToken(fs.readFileSync(ownerPath, "utf8"));
+		if (!owner) return null;
+		const after = fs.lstatSync(ownerPath);
+		if (!isTrustedResidentCacheOwnerFile(after, uid) || !hasSameFilesystemIdentity(before, after)) return null;
+		assertResidentCacheDirectoryPathMatchesDescriptor(instanceDir, descriptor, uid);
+		return { owner, directory };
+	} catch {
+		return null;
+	} finally {
+		if (descriptor !== null) {
+			try {
+				fs.closeSync(descriptor);
+			} catch {
+				// A failed close cannot make a previously unreadable owner trustworthy.
+			}
+		}
+	}
+}
+
+function writeResidentCacheOwnerToken(instanceDir: string, uid: number): void {
+	const nonce = path.basename(instanceDir).slice("i-".length);
+	if (!nonce) throw new ResidentCacheTrustError("instance_nonce_missing", instanceDir);
+	const owner: ResidentCacheOwnerToken = {
+		pid: process.pid,
+		startTimeMs: residentCacheProcessStartTimeMs(process.pid),
+		nonce,
+		createdAt: Date.now(),
+	};
+	const ownerPath = path.join(instanceDir, RESIDENT_CACHE_OWNER_RECORD);
+	const noFollow = fs.constants.O_NOFOLLOW;
+	if (!noFollow) throw new ResidentCacheTrustError("no_follow_unavailable", ownerPath);
+
+	let descriptor: number | null = null;
+	let expected: fs.Stats | null = null;
+	let failure: ResidentCacheTrustError | null = null;
+	try {
+		descriptor = fs.openSync(
+			ownerPath,
+			fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | noFollow,
+			BLOB_FILE_MODE,
+		);
+		fs.writeFileSync(descriptor, JSON.stringify(owner), "utf8");
+		fs.fchmodSync(descriptor, BLOB_FILE_MODE);
+		expected = fs.fstatSync(descriptor);
+		if (!isTrustedResidentCacheOwnerFile(expected, uid)) {
+			throw new ResidentCacheTrustError("owner_file_untrusted", ownerPath);
+		}
+	} catch (error) {
+		failure = residentCacheTrustError("owner_write_failed", ownerPath, error);
+	} finally {
+		if (descriptor !== null) {
+			try {
+				fs.closeSync(descriptor);
+			} catch (error) {
+				failure ??= residentCacheTrustError("owner_close_failed", ownerPath, error);
+			}
+		}
+	}
+	if (failure !== null) throw failure;
+
+	try {
+		const current = fs.lstatSync(ownerPath);
+		if (
+			expected === null ||
+			!isTrustedResidentCacheOwnerFile(current, uid) ||
+			!hasSameFilesystemIdentity(expected, current)
+		) {
+			throw new ResidentCacheTrustError("owner_identity_changed", ownerPath);
+		}
+	} catch (error) {
+		throw residentCacheTrustError("owner_write_untrusted", ownerPath, error);
+	}
+}
+
+function removeEmptyResidentCacheInstanceDir(instanceDir: string): void {
+	try {
+		const stat = fs.lstatSync(instanceDir);
+		if (stat.isSymbolicLink()) {
+			fs.unlinkSync(instanceDir);
+		} else if (stat.isDirectory()) {
+			fs.rmdirSync(instanceDir);
+		}
+	} catch {
+		// The candidate is already absent, was replaced, or is no longer empty.
+		// Never recursively delete an unverified path while handling a trust failure.
+	}
+}
+
+function removeResidentCacheTreeNoFollow(pathname: string): void {
+	const stat = fs.lstatSync(pathname);
+	if (stat.isDirectory() && !stat.isSymbolicLink()) {
+		for (const entry of fs.readdirSync(pathname)) {
+			removeResidentCacheTreeNoFollow(path.join(pathname, entry));
+		}
+		fs.rmdirSync(pathname);
+		return;
+	}
+	fs.unlinkSync(pathname);
+}
+
+function disposeVerifiedResidentCacheInstanceDir(instanceDir: string): void {
+	const instanceKey = path.resolve(instanceDir);
+	const uid = residentCacheOwnerUid(instanceDir);
+	const quarantineDir = path.join(
+		path.dirname(instanceDir),
+		`${path.basename(instanceDir)}.dispose.${crypto.randomUUID()}`,
+	);
+	try {
+		fs.lstatSync(quarantineDir);
+		throw new ResidentCacheTrustError("quarantine_exists", quarantineDir);
+	} catch (error) {
+		if (error instanceof ResidentCacheTrustError) throw error;
+		if (errorCode(error) !== "ENOENT") throw residentCacheTrustError("quarantine_unverifiable", quarantineDir, error);
+	}
+
+	let descriptor: number | null = null;
+	let removed = false;
+	try {
+		descriptor = openVerifiedResidentCacheDirectory(instanceDir, uid);
+		assertResidentCacheDirectoryPathMatchesDescriptor(instanceDir, descriptor, uid);
+		const expected = fs.fstatSync(descriptor);
+		fs.renameSync(instanceDir, quarantineDir);
+		const moved = fs.lstatSync(quarantineDir);
+		if (
+			!moved.isDirectory() ||
+			moved.isSymbolicLink() ||
+			moved.uid !== uid ||
+			!hasOwnerOnlyMode(moved.mode) ||
+			!hasSameFilesystemIdentity(expected, moved)
+		) {
+			throw new ResidentCacheTrustError("quarantine_identity_changed", quarantineDir);
+		}
+		removeResidentCacheTreeNoFollow(quarantineDir);
+		removed = true;
+	} catch (error) {
+		throw residentCacheTrustError("instance_dispose_failed", instanceDir, error);
+	} finally {
+		if (descriptor !== null) {
+			try {
+				fs.closeSync(descriptor);
+			} catch {
+				// The instance was either quarantined or left intact by the primary failure.
+			}
+		}
+		if (removed) ownedResidentCacheInstanceDirs.delete(instanceKey);
+	}
+}
+
+function removePartialResidentCacheInstanceDir(instanceDir: string): void {
+	try {
+		disposeVerifiedResidentCacheInstanceDir(instanceDir);
+	} catch {
+		removeEmptyResidentCacheInstanceDir(instanceDir);
+	}
+}
+
+function isResidentCacheInstanceDirName(name: string): boolean {
+	return /^i-[A-Za-z0-9_-]+$/.test(name);
+}
+
+function residentCacheSweepLimit(value: number | undefined, ceiling: number): number {
+	if (value === undefined || !Number.isFinite(value)) return ceiling;
+	return Math.max(0, Math.min(Math.floor(value), ceiling));
+}
+
+function cachedResidentCacheProcessStartTimeMs(pid: number, cache: Map<number, number | null>): number | null {
+	if (cache.has(pid)) return cache.get(pid) ?? null;
+	const startTimeMs = residentCacheProcessStartTimeMs(pid);
+	cache.set(pid, startTimeMs);
+	return startTimeMs;
+}
+
+function residentCacheOwnerIsStale(
+	owner: ResidentCacheOwnerToken,
+	startTimeCache: Map<number, number | null>,
+): boolean {
+	const liveness = residentCacheOwnerLiveness(owner.pid);
+	if (liveness === "dead") return true;
+	if (liveness !== "alive" || owner.startTimeMs === null) return false;
+	const currentStartTimeMs = cachedResidentCacheProcessStartTimeMs(owner.pid, startTimeCache);
+	return currentStartTimeMs !== null && currentStartTimeMs !== owner.startTimeMs;
+}
+
+function reapResidentCacheInstanceDir(
+	root: string,
+	rootDescriptor: number,
+	instanceDir: string,
+	expected: ResidentCacheOwnerSnapshot,
+	uid: number,
+): boolean {
+	const quarantineDir = path.join(root, `${path.basename(instanceDir)}.reap.${crypto.randomUUID()}`);
+	try {
+		fs.lstatSync(quarantineDir);
+		return false;
+	} catch (error) {
+		if (errorCode(error) !== "ENOENT") return false;
+	}
+
+	// Re-read immediately before rename so a replacement owner cannot be reaped
+	// based on the stale observation above (the same compare-before-delete shape
+	// used by file-lock GC).
+	const current = readResidentCacheOwnerSnapshot(instanceDir, uid);
+	if (
+		current === null ||
+		!sameResidentCacheOwnerToken(current.owner, expected.owner) ||
+		!hasSameFilesystemIdentity(current.directory, expected.directory)
+	) {
+		return false;
+	}
+
+	try {
+		const beforeRename = fs.lstatSync(instanceDir);
+		if (
+			!beforeRename.isDirectory() ||
+			beforeRename.isSymbolicLink() ||
+			beforeRename.uid !== uid ||
+			!hasOwnerOnlyMode(beforeRename.mode) ||
+			!hasSameFilesystemIdentity(beforeRename, current.directory)
+		) {
+			return false;
+		}
+		assertResidentCacheDirectoryPathMatchesDescriptor(root, rootDescriptor, uid);
+		fs.renameSync(instanceDir, quarantineDir);
+		const moved = fs.lstatSync(quarantineDir);
+		if (
+			!moved.isDirectory() ||
+			moved.isSymbolicLink() ||
+			moved.uid !== uid ||
+			!hasOwnerOnlyMode(moved.mode) ||
+			!hasSameFilesystemIdentity(moved, current.directory)
+		) {
+			throw new ResidentCacheTrustError("reap_quarantine_identity_changed", quarantineDir);
+		}
+		removeResidentCacheTreeNoFollow(quarantineDir);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Best-effort cleanup of abandoned resident-cache instances. The root is
+ * re-verified before scanning, work is bounded, and all failures fail closed.
+ */
+export async function sweepResidentCacheRoot(root: string, options: ResidentCacheGcSweepOptions = {}): Promise<void> {
+	const rootKey = path.resolve(root);
+	if (activeResidentCacheRootSweeps.has(rootKey)) return;
+	activeResidentCacheRootSweeps.add(rootKey);
+	try {
+		// Yield before filesystem work so callers can fire-and-forget this sweep.
+		await Promise.resolve();
+		const startedAt = Date.now();
+		const maxDirectories = residentCacheSweepLimit(options.maxDirectories, RESIDENT_CACHE_GC_MAX_DIRECTORIES);
+		const maxDurationMs = residentCacheSweepLimit(options.maxDurationMs, RESIDENT_CACHE_GC_MAX_DURATION_MS);
+		if (maxDirectories === 0 || maxDurationMs === 0) return;
+
+		const uid = residentCacheOwnerUid(root);
+		let rootDescriptor: number | null = null;
+		try {
+			// Do not create the root here: a failed verification must leave no new
+			// cache state behind.
+			rootDescriptor = openVerifiedResidentCacheDirectory(root, uid);
+			assertResidentCacheDirectoryPathMatchesDescriptor(root, rootDescriptor, uid);
+			const startTimeCache = new Map<number, number | null>();
+			const entries = fs.opendirSync(root);
+			try {
+				let examined = 0;
+				for (let entry = entries.readSync(); entry !== null; entry = entries.readSync()) {
+					if (examined >= maxDirectories || Date.now() - startedAt >= maxDurationMs) return;
+					if (!isResidentCacheInstanceDirName(entry.name)) continue;
+					const instanceDir = path.join(root, entry.name);
+					if (ownedResidentCacheInstanceDirs.has(path.resolve(instanceDir))) continue;
+					assertResidentCacheDirectoryPathMatchesDescriptor(root, rootDescriptor, uid);
+					examined++;
+					const expected = readResidentCacheOwnerSnapshot(instanceDir, uid);
+					if (expected === null || !residentCacheOwnerIsStale(expected.owner, startTimeCache)) continue;
+					reapResidentCacheInstanceDir(root, rootDescriptor, instanceDir, expected, uid);
+				}
+			} finally {
+				entries.closeSync();
+			}
+		} finally {
+			if (rootDescriptor !== null) fs.closeSync(rootDescriptor);
+		}
+	} catch (error) {
+		if (!isExpectedResidentCacheSweepFailure(error)) throw error;
+		logger.debug("Resident cache GC sweep skipped", { root, error: String(error) });
+	} finally {
+		activeResidentCacheRootSweeps.delete(rootKey);
+	}
+}
+
+function scheduleResidentCacheRootSweep(root: string): void {
+	void sweepResidentCacheRoot(root).catch(error => {
+		logger.debug("Resident cache GC sweep failed", { root, error: String(error) });
+	});
+}
+
+/**
+ * Create a private resident-cache instance directory beneath a trusted profile
+ * root. The cache-owned root and nonce instance are both verified owner-only
+ * directories; callers must use {@link EphemeralBlobStore.adoptVerifiedDir}
+ * rather than the destructive EphemeralBlobStore constructor.
+ */
+export function openVerifiedResidentCacheInstanceDir(root: string): string {
+	const uid = residentCacheOwnerUid(root);
+	let rootDescriptor: number | null = null;
+	let instanceDir: string | null = null;
+	try {
+		try {
+			fs.mkdirSync(root, { recursive: true, mode: BLOB_DIR_MODE });
+		} catch (error) {
+			throw residentCacheTrustError("root_create_failed", root, error);
+		}
+
+		rootDescriptor = openVerifiedResidentCacheDirectory(root, uid);
+		try {
+			instanceDir = fs.mkdtempSync(path.join(root, "i-"));
+		} catch (error) {
+			throw residentCacheTrustError("instance_create_failed", root, error);
+		}
+
+		// Keep the root descriptor open while creating the nonce directory, then
+		// re-check the path against that descriptor before trusting the child.
+		assertResidentCacheDirectoryPathMatchesDescriptor(root, rootDescriptor, uid);
+		let instanceDescriptor: number | null = null;
+		try {
+			instanceDescriptor = openVerifiedResidentCacheDirectory(instanceDir, uid);
+		} finally {
+			if (instanceDescriptor !== null) fs.closeSync(instanceDescriptor);
+		}
+		writeResidentCacheOwnerToken(instanceDir, uid);
+		assertResidentCacheDirectoryPathMatchesDescriptor(root, rootDescriptor, uid);
+		ownedResidentCacheInstanceDirs.add(path.resolve(instanceDir));
+		scheduleResidentCacheRootSweep(root);
+		return instanceDir;
+	} catch (error) {
+		if (instanceDir !== null) removePartialResidentCacheInstanceDir(instanceDir);
+		throw residentCacheTrustError("instance_directory_untrusted", root, error);
+	} finally {
+		if (rootDescriptor !== null) {
+			try {
+				fs.closeSync(rootDescriptor);
+			} catch {
+				// Descriptor cleanup must not turn a verified candidate into a failure.
+			}
+		}
+	}
+}
+
 function sha256Hex(data: Buffer): string {
 	return new Bun.SHA256().update(data).digest("hex");
 }
@@ -99,6 +699,141 @@ function verifyBlobFileSync(hash: string, blobPath: string): Buffer {
 	return data;
 }
 
+function isTrustedResidentCacheBlobDescriptor(stat: fs.Stats, uid: number): boolean {
+	return stat.isFile() && stat.uid === uid && hasOwnerOnlyMode(stat.mode);
+}
+
+function isTrustedResidentCacheBlobFile(stat: fs.Stats, uid: number, byteLength: number): boolean {
+	return isTrustedResidentCacheBlobDescriptor(stat, uid) && stat.size === byteLength;
+}
+
+function readVerifiedResidentCacheBlobSync(hash: string, blobPath: string): Buffer | null {
+	const uid = residentCacheOwnerUid(blobPath);
+	const noFollow = fs.constants.O_NOFOLLOW;
+	if (!noFollow) throw new ResidentCacheTrustError("no_follow_unavailable", blobPath);
+
+	let descriptor: number;
+	try {
+		descriptor = fs.openSync(blobPath, fs.constants.O_RDONLY | noFollow);
+	} catch (error) {
+		if (isEnoent(error)) return null;
+		throw residentCacheTrustError("blob_open_failed", blobPath, error);
+	}
+
+	let data: Buffer | null = null;
+	let failure: ResidentCacheTrustError | null = null;
+	try {
+		const stat = fs.fstatSync(descriptor);
+		if (!isTrustedResidentCacheBlobDescriptor(stat, uid)) {
+			throw new ResidentCacheTrustError("blob_descriptor_untrusted", blobPath);
+		}
+		data = fs.readFileSync(descriptor);
+		verifyBlobBytesSync(hash, blobPath, data);
+	} catch (error) {
+		failure = residentCacheTrustError("blob_read_untrusted", blobPath, error);
+	} finally {
+		try {
+			fs.closeSync(descriptor);
+		} catch (error) {
+			failure ??= residentCacheTrustError("blob_close_failed", blobPath, error);
+		}
+	}
+	if (failure !== null) throw failure;
+	return data;
+}
+
+function assertResidentCacheBlobFile(pathname: string, uid: number, byteLength: number): fs.Stats {
+	let stat: fs.Stats;
+	try {
+		stat = fs.lstatSync(pathname);
+	} catch (error) {
+		throw residentCacheTrustError("blob_unverifiable", pathname, error);
+	}
+	if (!isTrustedResidentCacheBlobFile(stat, uid, byteLength)) {
+		throw new ResidentCacheTrustError("blob_untrusted", pathname);
+	}
+	return stat;
+}
+
+function verifyExistingResidentCacheBlob(
+	hash: string,
+	blobPath: string,
+	uid: number,
+	byteLength: number,
+): BlobPutResult {
+	const before = assertResidentCacheBlobFile(blobPath, uid, byteLength);
+	try {
+		verifyBlobFileSync(hash, blobPath);
+	} catch (error) {
+		throw residentCacheTrustError("blob_content_unverifiable", blobPath, error);
+	}
+	const after = assertResidentCacheBlobFile(blobPath, uid, byteLength);
+	if (!hasSameFilesystemIdentity(before, after)) {
+		throw new ResidentCacheTrustError("blob_identity_changed", blobPath);
+	}
+	return makeBlobPutResult(hash, blobPath);
+}
+
+function removeNewResidentCacheBlob(blobPath: string, expected: fs.Stats): void {
+	try {
+		const current = fs.lstatSync(blobPath);
+		if (current.isFile() && !current.isSymbolicLink() && hasSameFilesystemIdentity(current, expected)) {
+			fs.unlinkSync(blobPath);
+		}
+	} catch {
+		// A failed put must never delete a path whose identity no longer matches
+		// the exclusively-created file descriptor we opened.
+	}
+}
+
+function putResidentCacheBlobSync(dir: string, data: Buffer): BlobPutResult {
+	const hash = sha256Hex(data);
+	const blobPath = path.join(dir, hash);
+	const uid = residentCacheOwnerUid(blobPath);
+	const noFollow = fs.constants.O_NOFOLLOW;
+	if (!noFollow) throw new ResidentCacheTrustError("no_follow_unavailable", blobPath);
+
+	let descriptor: number;
+	try {
+		descriptor = fs.openSync(
+			blobPath,
+			fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | noFollow,
+			BLOB_FILE_MODE,
+		);
+	} catch (error) {
+		if (errorCode(error) === "EEXIST") return verifyExistingResidentCacheBlob(hash, blobPath, uid, data.byteLength);
+		throw residentCacheTrustError("blob_create_failed", blobPath, error);
+	}
+
+	let created: fs.Stats | null = null;
+	let failure: ResidentCacheTrustError | null = null;
+	try {
+		created = fs.fstatSync(descriptor);
+		if (!created.isFile() || created.uid !== uid)
+			throw new ResidentCacheTrustError("blob_descriptor_untrusted", blobPath);
+		fs.fchmodSync(descriptor, BLOB_FILE_MODE);
+		fs.writeFileSync(descriptor, data);
+		const written = fs.fstatSync(descriptor);
+		if (!isTrustedResidentCacheBlobFile(written, uid, data.byteLength)) {
+			throw new ResidentCacheTrustError("blob_write_untrusted", blobPath);
+		}
+	} catch (error) {
+		failure = residentCacheTrustError("blob_write_failed", blobPath, error);
+	} finally {
+		try {
+			fs.closeSync(descriptor);
+		} catch (error) {
+			failure ??= residentCacheTrustError("blob_close_failed", blobPath, error);
+		}
+	}
+
+	if (failure !== null) {
+		if (created !== null) removeNewResidentCacheBlob(blobPath, created);
+		throw failure;
+	}
+	return makeBlobPutResult(hash, blobPath);
+}
+
 /**
  * Content-addressed blob store for externalizing large binary data (images) from session JSONL files.
  *
@@ -139,7 +874,7 @@ export class BlobStore {
 	 * cannot afford the microtask hops of the async version (e.g. OOM-safe session writes).
 	 * Returns once the bytes are in the kernel page cache.
 	 */
-	putSync(data: Buffer): BlobPutResult {
+	putSync(data: Buffer, _ownership?: typeof TAKE_BLOB_BUFFER_OWNERSHIP): BlobPutResult {
 		const hash = new Bun.SHA256().update(data).digest("hex");
 		const blobPath = path.join(this.dir, hash);
 		const result = {
@@ -154,6 +889,15 @@ export class BlobStore {
 		return result;
 	}
 
+	/**
+	 * Store a buffer that the caller will not mutate after this call returns.
+	 * Resident-cache implementations may retain that private buffer without an
+	 * additional defensive copy.
+	 */
+	putOwnedSync(data: Buffer): BlobPutResult {
+		return this.putSync(data, TAKE_BLOB_BUFFER_OWNERSHIP);
+	}
+
 	/**
 	 * Durably install binary data as an immutable content-addressed blob.
 	 *
@@ -278,6 +1022,42 @@ export class BlobStore {
 	}
 }
 
+interface EphemeralBlobStoreOptions {
+	readonly adoptVerifiedDir?: boolean;
+}
+
+/**
+ * Resident-cache directories this process created and has not disposed.
+ *
+ * The directory name embeds the pid (`<session>-<pid>-<n>`), so a run that never
+ * reaches `dispose()` cannot be cleaned by a later run: the next process picks a
+ * different name, and the constructor's wipe only ever clears its own path. The
+ * leftovers are therefore permanent. A developer machine held seven of them from
+ * dead pids, up to 26 days old, totalling 13.4 MB of externalized session text.
+ */
+const liveResidentCacheDirs = new Set<string>();
+
+/** Resident-cache directories still tracked by this process. Test seam. */
+export function trackedResidentCacheDirsForTest(): string[] {
+	return [...liveResidentCacheDirs];
+}
+
+/**
+ * Sweep the directories this process created when it exits abnormally, matching
+ * `shell-snapshot` and `python-runner-artifact`. Best-effort by contract: a
+ * postmortem handler must not throw.
+ */
+postmortem.register("session-resident-cache", () => {
+	for (const dir of [...liveResidentCacheDirs]) {
+		try {
+			fs.rmSync(dir, { recursive: true, force: true });
+		} catch {
+			// Exit path: a failed removal must not mask the original fault.
+		}
+		liveResidentCacheDirs.delete(dir);
+	}
+});
+
 export class EphemeralBlobStore extends BlobStore {
 	/**
 	 * Bounded LRU byte budget for the in-memory buffer cache. Keeps recent
@@ -288,11 +1068,44 @@ export class EphemeralBlobStore extends BlobStore {
 
 	#bufferCache = new Map<string, Buffer>();
 	#bufferCacheBytes = 0;
+	#adoptedVerifiedDir = false;
+	#disposed = false;
 
-	constructor(dir: string) {
+	constructor(dir: string, options: EphemeralBlobStoreOptions = {}) {
 		super(dir);
+		this.#adoptedVerifiedDir = options.adoptVerifiedDir === true;
+		if (this.#adoptedVerifiedDir) return;
 		fs.rmSync(dir, { recursive: true, force: true });
 		fs.mkdirSync(dir, { recursive: true, mode: BLOB_DIR_MODE });
+		liveResidentCacheDirs.add(dir);
+	}
+
+	/**
+	 * Adopt a directory returned by {@link openVerifiedResidentCacheInstanceDir}
+	 * without the ordinary constructor's destructive remove-and-recreate path.
+	 */
+	static adoptVerifiedDir(dir: string): EphemeralBlobStore {
+		const uid = residentCacheOwnerUid(dir);
+		let descriptor: number | null = null;
+		let failure: unknown;
+		try {
+			descriptor = openVerifiedResidentCacheDirectory(dir, uid);
+			assertResidentCacheDirectoryPathMatchesDescriptor(dir, descriptor, uid);
+		} catch (error) {
+			failure = error;
+		}
+		if (descriptor !== null) {
+			try {
+				fs.closeSync(descriptor);
+			} catch (error) {
+				failure ??= residentCacheTrustError("instance_close_failed", dir, error);
+			}
+		}
+		if (failure !== undefined) {
+			removeEmptyResidentCacheInstanceDir(dir);
+			throw residentCacheTrustError("instance_adoption_failed", dir, failure);
+		}
+		return new EphemeralBlobStore(dir, { adoptVerifiedDir: true });
 	}
 
 	#cachePut(hash: string, data: Buffer): void {
@@ -311,18 +1124,33 @@ export class EphemeralBlobStore extends BlobStore {
 		}
 	}
 
-	putSync(data: Buffer): BlobPutResult {
-		const result = super.putSync(data);
-		this.#cachePut(result.hash, Buffer.from(data));
+	async put(data: Buffer): Promise<BlobPutResult> {
+		if (!this.#adoptedVerifiedDir) return super.put(data);
+		return this.putSync(data);
+	}
+
+	putSync(data: Buffer, ownership?: typeof TAKE_BLOB_BUFFER_OWNERSHIP): BlobPutResult {
+		const result = this.#adoptedVerifiedDir ? putResidentCacheBlobSync(this.dir, data) : super.putSync(data);
+		this.#cachePut(result.hash, ownership === TAKE_BLOB_BUFFER_OWNERSHIP ? data : Buffer.from(data));
 		return result;
 	}
 
 	putImmutableSync(data: Buffer): CheckedBlobPutResult {
+		if (this.#adoptedVerifiedDir) {
+			const result = putResidentCacheBlobSync(this.dir, data);
+			this.#cachePut(result.hash, Buffer.from(data));
+			return makeBlobPutResult(result.hash, result.path, data.byteLength);
+		}
 		const result = super.putImmutableSync(data);
 		this.#cachePut(result.hash, Buffer.from(data));
 		return result;
 	}
 
+	async get(hash: string): Promise<Buffer | null> {
+		if (this.#adoptedVerifiedDir) return this.getSync(hash);
+		return super.get(hash);
+	}
+
 	getSync(hash: string): Buffer | null {
 		const cached = this.#bufferCache.get(hash);
 		if (cached) {
@@ -336,12 +1164,25 @@ export class EphemeralBlobStore extends BlobStore {
 			this.#bufferCache.delete(hash);
 			this.#bufferCacheBytes -= cached.byteLength;
 		}
-		const data = super.getSync(hash);
+
+		const data = this.#adoptedVerifiedDir
+			? readVerifiedResidentCacheBlobSync(hash, path.join(this.dir, hash))
+			: super.getSync(hash);
 		if (data) this.#cachePut(hash, Buffer.from(data));
 		return data;
 	}
 
+	/** Return a trusted in-memory copy without reopening an invalidated cache path. */
+	getBufferedSync(hash: string): Buffer | null {
+		const cached = this.#bufferCache.get(hash);
+		if (!cached) return null;
+		this.#bufferCache.delete(hash);
+		this.#bufferCache.set(hash, cached);
+		return Buffer.from(cached);
+	}
+
 	getCheckedSync(hash: string): Buffer | null {
+		if (this.#adoptedVerifiedDir) return this.getSync(hash);
 		const data = super.getCheckedSync(hash);
 		if (data) this.#cachePut(hash, Buffer.from(data));
 		return data;
@@ -350,32 +1191,79 @@ export class EphemeralBlobStore extends BlobStore {
 	clear(): void {
 		this.#bufferCache.clear();
 		this.#bufferCacheBytes = 0;
-		fs.rmSync(this.dir, { recursive: true, force: true });
-		fs.mkdirSync(this.dir, { recursive: true, mode: BLOB_DIR_MODE });
+		if (!this.#adoptedVerifiedDir) {
+			fs.rmSync(this.dir, { recursive: true, force: true });
+			fs.mkdirSync(this.dir, { recursive: true, mode: BLOB_DIR_MODE });
+			return;
+		}
+
+		const uid = residentCacheOwnerUid(this.dir);
+		const descriptor = openVerifiedResidentCacheDirectory(this.dir, uid);
+		try {
+			for (const entry of fs.readdirSync(this.dir)) {
+				if (entry === RESIDENT_CACHE_OWNER_RECORD) continue;
+				const blobPath = path.join(this.dir, entry);
+				const stat = fs.lstatSync(blobPath);
+				if (
+					!/^[a-f0-9]{64}$/.test(entry) ||
+					!stat.isFile() ||
+					stat.isSymbolicLink() ||
+					stat.uid !== uid ||
+					!hasOwnerOnlyMode(stat.mode)
+				) {
+					throw new ResidentCacheTrustError("clear_untrusted_entry", blobPath);
+				}
+				fs.unlinkSync(blobPath);
+			}
+		} catch (error) {
+			throw residentCacheTrustError("clear_failed", this.dir, error);
+		} finally {
+			try {
+				fs.closeSync(descriptor);
+			} catch {
+				// The clear result is already determined; do not mask it with cleanup.
+			}
+		}
 	}
 
 	dispose(): void {
+		if (this.#adoptedVerifiedDir && this.#disposed) return;
 		this.#bufferCache.clear();
 		this.#bufferCacheBytes = 0;
+		if (this.#adoptedVerifiedDir) {
+			disposeVerifiedResidentCacheInstanceDir(this.dir);
+			this.#disposed = true;
+			return;
+		}
+		// Untrack before removing so the sweep cannot race a clean disposal.
+		liveResidentCacheDirs.delete(this.dir);
 		fs.rmSync(this.dir, { recursive: true, force: true });
 	}
 }
 
+export interface MemoryBlobStoreOptions {
+	/** A canonical store owns every reference in its session's resident entries. */
+	readonly ownership?: "cache" | "canonical";
+}
+
 export class MemoryBlobStore extends BlobStore {
 	/**
-	 * Generous byte/count LRU bound (F8). Content-addressed resident blobs are fail-closed
-	 * on miss (callers raise/handle {@link ResidentBlobMissingError}), so evicting the
-	 * least-recently-used entry on an extremely large session is preferable to unbounded
-	 * RAM growth. The caps sit well above normal usage and only trip on pathological sizes.
+	 * Cache-owned stores use a bounded LRU. Canonical ownership deliberately
+	 * retains every blob: a degraded resident session has no trusted disk store
+	 * behind its references, so eviction would silently replace valid content
+	 * with unavailable placeholders. This matches the pre-resident-cache
+	 * in-RAM raw-string lifetime while leaving non-canonical caches bounded.
 	 */
 	static readonly #MAX_BYTES = 64 * 1024 * 1024;
 	static readonly #MAX_COUNT = 4096;
 
 	#blobs = new Map<string, Buffer>();
 	#bytes = 0;
+	#canonical: boolean;
 
-	constructor() {
+	constructor(options: MemoryBlobStoreOptions = {}) {
 		super(":memory:");
+		this.#canonical = options.ownership === "canonical";
 	}
 
 	#store(hash: string, data: Buffer): void {
@@ -386,6 +1274,7 @@ export class MemoryBlobStore extends BlobStore {
 		}
 		this.#blobs.set(hash, data);
 		this.#bytes += data.byteLength;
+		if (this.#canonical) return;
 		while (
 			(this.#bytes > MemoryBlobStore.#MAX_BYTES || this.#blobs.size > MemoryBlobStore.#MAX_COUNT) &&
 			this.#blobs.size > 1
@@ -421,9 +1310,11 @@ export class MemoryBlobStore extends BlobStore {
 	getSync(hash: string): Buffer | null {
 		const data = this.#blobs.get(hash);
 		if (!data) return null;
-		// Refresh LRU recency on hit so hot blobs survive eviction.
-		this.#blobs.delete(hash);
-		this.#blobs.set(hash, data);
+		if (!this.#canonical) {
+			// Refresh LRU recency on hit so hot blobs survive eviction.
+			this.#blobs.delete(hash);
+			this.#blobs.set(hash, data);
+		}
 		return Buffer.from(data);
 	}
 
@@ -484,7 +1375,7 @@ export async function externalizeImageDataUrl(blobStore: BlobStore, dataUrl: str
 /** Synchronous variant of {@link externalizeImageDataUrl}. */
 export function externalizeImageDataUrlSync(blobStore: BlobStore, dataUrl: string): string {
 	if (isBlobRef(dataUrl)) return dataUrl;
-	return blobStore.putSync(Buffer.from(dataUrl, "utf8")).ref;
+	return blobStore.putOwnedSync(Buffer.from(dataUrl, "utf8")).ref;
 }
 
 /**
@@ -501,7 +1392,7 @@ export async function externalizeImageData(blobStore: BlobStore, base64Data: str
 /** Synchronous variant of {@link externalizeImageData}. */
 export function externalizeImageDataSync(blobStore: BlobStore, base64Data: string): string {
 	if (isBlobRef(base64Data)) return base64Data;
-	return blobStore.putSync(Buffer.from(base64Data, "base64")).ref;
+	return blobStore.putOwnedSync(Buffer.from(base64Data, "base64")).ref;
 }
 
 /**