@sayknow-cli/coding-agent 0.3.16 → 0.4.1

package/src/session/session-storage.ts

@@ -1,9 +1,24 @@
+import { createHash } from "node:crypto";
+
 import * as fs from "node:fs";
-import * as fsp from "node:fs/promises";
 import * as path from "node:path";
+import * as native from "@sayknow-cli/natives";
+
 import { isEnoent, pathIsWithin, peekFile, toError } from "@sayknow-cli/utils";
+import {
+	assertManagedDirectoryRoot,
+	type ManagedDirectoryRoot,
+	validateNativeSecurityResult,
+} from "./internal/managed-session-storage";
 
 const utf8Decoder = new TextDecoder("utf-8");
+function canonicalPathSync(value: string): string {
+	try {
+		return fs.realpathSync.native(value);
+	} catch {
+		return path.resolve(value);
+	}
+}
 
 export interface SessionStorageStat {
 	dev: bigint;
@@ -79,8 +94,41 @@ export interface SessionStorageWriterOpenOptions {
 	onError?: (err: Error) => void;
 	/** Injectable OS-close dispatcher; defaults to `fs.closeSync`. */
 	closeAdapter?: SessionStorageWriterCloseAdapter;
+	/** Opaque authority for default-computed managed destinations only. */
+	securityContext?: SessionStorageSecurityContext;
 }
 
+/**
+ * Immutable authority attached only to a computed managed session destination.
+ * A caller-supplied pathname never receives this capability, even when it
+ * happens to equal the current default session directory.
+ */
+export interface ManagedSessionSecurityContext {
+	readonly kind: "managed";
+	readonly agentDir: string;
+	readonly sessionsRoot: string;
+	readonly sessionDir: string;
+	readonly rootAuthority: ManagedDirectoryRoot;
+	readonly retainedAuthority?: native.RecoveryFsRoot;
+}
+
+const managedSecurityContexts = new WeakSet<ManagedSessionSecurityContext>();
+
+/** @internal Create the only accepted managed writer authority object. */
+export function createManagedSessionSecurityContext(input: {
+	agentDir: string;
+	sessionsRoot: string;
+	sessionDir: string;
+	rootAuthority: ManagedDirectoryRoot;
+	retainedAuthority?: native.RecoveryFsRoot;
+}): ManagedSessionSecurityContext {
+	const context = Object.freeze({ kind: "managed" as const, ...input });
+	managedSecurityContexts.add(context);
+	return context;
+}
+
+export type SessionStorageSecurityContext = ManagedSessionSecurityContext | undefined;
+
 export interface SessionStorageWriter {
 	writeLine(line: string): Promise<void>;
 	/**
@@ -148,10 +196,13 @@ export interface SessionStorage {
 // Verified hard-delete identity + typed partial-cleanup evidence
 // =============================================================================
 
-/** Exact (dev, ino) identity fields used for ACP authorization binding. */
+/** Exact authorization evidence for a transcript or artifact path. */
 export interface SessionStorageFileIdentity {
 	dev: bigint;
 	ino: bigint;
+	size: number;
+	mtimeNs: bigint;
+	sha256: string;
 }
 
 /** Kind of verification failure surfaced by {@link deleteSessionVerified}. */
@@ -202,6 +253,18 @@ export interface VerifiedSessionDeleteTarget {
 	 * fails closed. Omit on first attempt or to accept recorded absence.
 	 */
 	expectedArtifactsIdentity?: SessionStorageFileIdentity;
+	/** Stable native recursive-tree evidence captured before artifact detachment. */
+	expectedArtifactsTree?: NativeDirectoryTreeSnapshot;
+	/** Identity-bound quarantine path retained when recursive artifact cleanup failed. */
+	detachedArtifactsPath?: string;
+	/** Identity-bound quarantine path retained when transcript unlink deferred cleanup. */
+	detachedTranscriptPath?: string;
+	/** Caller-published, no-replace quarantine pathname for the next artifact detach. */
+	plannedArtifactsPath?: string;
+	/** Caller-published, no-replace quarantine pathname for the next transcript detach. */
+	plannedTranscriptPath?: string;
+	/** Set only after a durable caller receipt records successful artifact removal. */
+	artifactsRemoved?: true;
 }
 
 /**
@@ -211,6 +274,7 @@ export interface VerifiedSessionDeleteTarget {
  * `deleted` and never `{}`.
  */
 export type VerifiedSessionDeleteResult =
+	| { kind: "artifacts_removed"; phase: "artifacts"; transcriptIdentity: SessionStorageFileIdentity }
 	| { kind: "deleted" }
 	| {
 			kind: "cleanup_pending";
@@ -218,6 +282,10 @@ export type VerifiedSessionDeleteResult =
 			error: Error;
 			/** Artifact directory identity at failure time; undefined when absent. */
 			artifactsIdentity: SessionStorageFileIdentity | undefined;
+			/** Identity-bound quarantine path retained when recursive cleanup failed. */
+			detachedArtifactsPath: string;
+			/** Native snapshot required for an identity-bound recursive retry. */
+			artifactsTree: NativeDirectoryTreeSnapshot;
 			/** Transcript identity (unchanged) for retry binding. */
 			transcriptIdentity: SessionStorageFileIdentity;
 	  }
@@ -227,6 +295,8 @@ export type VerifiedSessionDeleteResult =
 			error: Error;
 			/** Transcript identity at failure time for retry binding. */
 			transcriptIdentity: SessionStorageFileIdentity;
+			/** Optional identity-bound transcript quarantine path for restart cleanup. */
+			detachedTranscriptPath?: string;
 	  };
 
 /** Default OS-close dispatcher: a direct `fs.closeSync`. */
@@ -236,6 +306,155 @@ const defaultCloseAdapter: SessionStorageWriterCloseAdapter = {
 	},
 };
 
+type NativeExactUnlinkResult = { ok: true; detachedPath?: string } | { ok: false; code: string; detachedPath?: string };
+type NativeExactUnlink = (
+	path: string,
+	identity: {
+		dev: bigint;
+		ino: bigint;
+		size: bigint;
+		mtimeNs: bigint;
+		/** Required for regular-file deletion; directories are identity-bound only. */
+		sha256?: string;
+		directory?: boolean;
+		/** Optional caller-planned no-replace quarantine destination component. */
+		quarantineName?: string;
+	},
+) => NativeExactUnlinkResult;
+
+function nativeExactUnlink(
+	pathname: string,
+	identity: {
+		dev: bigint;
+		ino: bigint;
+		size: bigint;
+		mtimeNs: bigint;
+		/** Required for regular-file deletion; directories are identity-bound only. */
+		sha256?: string;
+		directory?: boolean;
+		quarantineName?: string;
+	},
+): NativeExactUnlinkResult {
+	return (native.exactUnlink as unknown as NativeExactUnlink)(pathname, identity);
+}
+
+type NativeDirectoryTreeEntry = {
+	relativePath: string;
+	kind: string;
+	dev: string;
+	ino: string;
+	size: string;
+	mtimeNs: string;
+	ctimeNs: string;
+	sha256?: string;
+};
+export type NativeDirectoryTreeSnapshot = {
+	rootDev: string;
+	rootIno: string;
+	entries: NativeDirectoryTreeEntry[];
+};
+type NativeDirectoryTreeResult =
+	| { ok: true; snapshot: NativeDirectoryTreeSnapshot }
+	| { ok: false; code: string; snapshot?: undefined };
+type NativeDirectoryTreeApi = {
+	snapshotDirectoryTree(pathname: string): NativeDirectoryTreeResult;
+	exactRemoveDirectoryTree(pathname: string, snapshot: NativeDirectoryTreeSnapshot): NativeExactUnlinkResult;
+};
+function nativeDirectoryTreeApi(): NativeDirectoryTreeApi {
+	return native as unknown as NativeDirectoryTreeApi;
+}
+function snapshotDirectoryTree(pathname: string): NativeDirectoryTreeSnapshot {
+	const result = nativeDirectoryTreeApi().snapshotDirectoryTree(pathname);
+	if (!result.ok || !result.snapshot)
+		throw new SessionDeleteVerificationError(
+			"artifacts",
+			`Native artifact snapshot rejected: ${result.ok ? "missing_snapshot" : result.code}`,
+		);
+	return result.snapshot;
+}
+function removeDirectoryTreeExact(pathname: string, snapshot: NativeDirectoryTreeSnapshot): NativeExactUnlinkResult {
+	return nativeDirectoryTreeApi().exactRemoveDirectoryTree(pathname, snapshot);
+}
+
+function exactUnlinkFailure(result: NativeExactUnlinkResult): SessionDeleteVerificationError {
+	if (result.ok) throw new Error("Expected exact unlink failure");
+	const kind: VerifiedDeleteFailureKind =
+		result.code === "reparse_point" || result.code === "not_regular_file"
+			? "symlink"
+			: result.code === "identity_mismatch"
+				? "identity"
+				: "stat";
+	return new SessionDeleteVerificationError(kind, `Exact transcript deletion rejected: ${result.code}`);
+}
+
+function isValidManagedSecurityContext(value: SessionStorageSecurityContext): value is ManagedSessionSecurityContext {
+	if (
+		value?.kind !== "managed" ||
+		!Object.isFrozen(value) ||
+		!managedSecurityContexts.has(value) ||
+		!pathIsWithin(value.agentDir, value.sessionsRoot) ||
+		!pathIsWithin(value.sessionsRoot, value.sessionDir)
+	) {
+		return false;
+	}
+	assertManagedDirectoryRoot(value.rootAuthority);
+	if (!pathIsWithin(value.rootAuthority.canonicalPath, value.agentDir)) return false;
+	return true;
+}
+
+function secureOwnerOnlyFileDescriptor(
+	pathname: string,
+	fd: number,
+	operation: "apply" | "verify",
+	securityContext: SessionStorageSecurityContext,
+): void {
+	if (securityContext && !isValidManagedSecurityContext(securityContext))
+		throw new Error("Invalid managed session security context");
+	if (process.platform !== "linux" || !securityContext) {
+		if (operation === "apply") {
+			const applied = validateNativeSecurityResult(
+				native.applyOwnerOnlyPathSecurity(pathname, "file"),
+				"apply",
+				"file",
+			);
+			if (!applied.ok) throw new Error(`Owner-only security rejected ${pathname}: ${applied.code}`);
+		}
+		const verified = validateNativeSecurityResult(
+			native.verifyOwnerOnlyPathSecurity(pathname, "file"),
+			"verify",
+			"file",
+		);
+		if (!verified.ok) throw new Error(`Owner-only security rejected ${pathname}: ${verified.code}`);
+		return;
+	}
+	if (!pathIsWithin(securityContext.sessionDir, pathname))
+		throw new Error(`Managed writer escaped its session directory: ${pathname}`);
+	const result = validateNativeSecurityResult(
+		operation === "apply"
+			? native.applyOwnerOnlyFdSecurity(pathname, "file", fd)
+			: native.verifyOwnerOnlyFdSecurity(pathname, "file", fd),
+		operation,
+		"file",
+	);
+	if (!result.ok) throw new Error(`Owner-only security rejected ${pathname}: ${result.code}`);
+}
+
+/** Reject a symlink/junction/reparse component before a storage path is created or opened. */
+function assertNoReparsePath(pathname: string): void {
+	const resolved = path.resolve(pathname);
+	const parsed = path.parse(resolved);
+	let current = parsed.root;
+	for (const part of resolved.slice(parsed.root.length).split(path.sep)) {
+		if (!part) continue;
+		current = path.join(current, part);
+		try {
+			if (fs.lstatSync(current).isSymbolicLink()) throw new Error(`Unsafe reparse storage path: ${current}`);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		}
+	}
+}
+
 // FinalizationRegistry to clean up leaked file descriptors
 const writerRegistry = new FinalizationRegistry<number>(fd => {
 	try {
@@ -247,24 +466,41 @@ const writerRegistry = new FinalizationRegistry<number>(fd => {
 
 class FileSessionStorageWriter implements SessionStorageWriter {
 	#fd: number;
+	#path: string;
+
 	#closeState: SessionStorageWriterCloseState = "open";
 	#closeError: Error | undefined;
 	#error: Error | undefined;
 	#onError: ((err: Error) => void) | undefined;
 	#closeAdapter: SessionStorageWriterCloseAdapter;
+	#securityContext: SessionStorageSecurityContext;
 
 	constructor(fpath: string, options?: SessionStorageWriterOpenOptions) {
 		this.#onError = options?.onError;
 		this.#closeAdapter = options?.closeAdapter ?? defaultCloseAdapter;
+		this.#securityContext = options?.securityContext;
 		const flags = options?.flags ?? "a";
-		// Ensure parent directory exists
 		const dir = path.dirname(fpath);
-		if (!fs.existsSync(dir)) {
-			fs.mkdirSync(dir, { recursive: true });
+		assertNoReparsePath(dir);
+		if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+		assertNoReparsePath(dir);
+		assertNoReparsePath(fpath);
+		// Never truncate before the descriptor and its terminal pathname have passed native security.
+		const openFlags =
+			(flags === "w"
+				? fs.constants.O_WRONLY | fs.constants.O_CREAT
+				: fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_APPEND) | (fs.constants.O_NOFOLLOW ?? 0);
+		const fd = fs.openSync(fpath, openFlags, 0o600);
+		try {
+			secureOwnerOnlyFileDescriptor(fpath, fd, "apply", this.#securityContext);
+			if (flags === "w") fs.ftruncateSync(fd, 0);
+		} catch (error) {
+			fs.closeSync(fd);
+			throw error;
 		}
-		// Open file once, keep fd for lifetime
-		this.#fd = fs.openSync(fpath, flags === "w" ? "w" : "a");
-		// Register for cleanup if abandoned without close()
+		this.#fd = fd;
+		this.#path = fpath;
+
 		writerRegistry.register(this, this.#fd, this);
 	}
 
@@ -322,6 +558,7 @@ class FileSessionStorageWriter implements SessionStorageWriter {
 		if (this.#error) throw this.#error;
 		try {
 			fs.fsyncSync(this.#fd);
+			secureOwnerOnlyFileDescriptor(this.#path, this.#fd, "verify", this.#securityContext);
 		} catch (err) {
 			throw this.#recordError(err);
 		}
@@ -334,6 +571,14 @@ class FileSessionStorageWriter implements SessionStorageWriter {
 		// for this numeric fd again; surface the stored non-quiescent error.
 		if (this.#closeState === "close_unknown") throw this.#closeError!;
 		// State is "open" or "close_failed_retryable": a close may be dispatched.
+		try {
+			secureOwnerOnlyFileDescriptor(this.#path, this.#fd, "verify", this.#securityContext);
+		} catch (err) {
+			// Verification happens before the OS-close dispatch, so descriptor ownership remains proven.
+			this.#closeState = "close_failed_retryable";
+			this.#closeError = toError(err);
+			throw this.#closeError;
+		}
 		try {
 			this.#closeAdapter.close(this.#fd);
 		} catch (err) {
@@ -484,20 +729,18 @@ export class FileSessionStorage implements SessionStorage {
 	}
 
 	/**
-	 * Delete a session file and its artifacts directory.
-	 * Artifacts are stored in a sibling directory with the same name minus .jsonl extension.
+	 * Delete a session and sibling artifacts in an operator-selected explicit directory.
+	 * Default managed roots use deleteSessionVerified and never call this path.
 	 */
 	async deleteSessionWithArtifacts(sessionPath: string): Promise<void> {
-		// Delete the session file itself
-		await this.unlink(sessionPath);
-
-		// Compute artifacts directory: /path/to/session.jsonl -> /path/to/session
+		try {
+			await this.unlink(sessionPath);
+		} catch (error) {
+			if (!isEnoent(error)) throw error;
+		}
 		const artifactsDir = sessionPath.slice(0, -6);
-
-		// Delete artifacts directory if it exists. Missing directories are fine, but
-		// surface real cleanup failures because the session file is already gone.
 		try {
-			await fsp.rm(artifactsDir, { recursive: true, force: true });
+			await fs.promises.rm(artifactsDir, { recursive: true, force: true });
 		} catch (err) {
 			const error = toError(err);
 			throw new Error(
@@ -514,68 +757,314 @@ export class FileSessionStorage implements SessionStorage {
 	 * evidence; identity/symlink/containment/header/cwd mismatch throws.
 	 */
 	async deleteSessionVerified(target: VerifiedSessionDeleteTarget): Promise<VerifiedSessionDeleteResult> {
-		const { sessionsRoot, transcriptPath, sessionId, cwd, transcriptIdentity, expectedArtifactsIdentity } = target;
+		const {
+			sessionsRoot,
+			transcriptPath,
+			sessionId,
+			cwd,
+			transcriptIdentity,
+			expectedArtifactsIdentity,
+			expectedArtifactsTree,
+			detachedArtifactsPath,
+			detachedTranscriptPath,
+			plannedArtifactsPath,
+			plannedTranscriptPath,
+			artifactsRemoved,
+		} = target;
+		try {
+			assertNoReparsePath(sessionsRoot);
+			assertNoReparsePath(transcriptPath);
+		} catch (err) {
+			throw new SessionDeleteVerificationError("symlink", "Sessions root or transcript path is a symlink", {
+				cause: toError(err),
+			});
+		}
 		if (!transcriptPath.endsWith(".jsonl")) {
 			throw new SessionDeleteVerificationError("containment", "Transcript path is not a .jsonl file");
 		}
 		if (!pathIsWithin(sessionsRoot, transcriptPath)) {
 			throw new SessionDeleteVerificationError("containment", "Transcript is outside the sessions root");
 		}
-		const initial = this.#verifiedReadAndHeader(transcriptPath, sessionId, cwd);
-		const initialStat = initial.snapshot.stat;
-		if (initialStat.dev !== transcriptIdentity.dev || initialStat.ino !== transcriptIdentity.ino) {
+		if (
+			!plannedArtifactsPath ||
+			!plannedTranscriptPath ||
+			path.dirname(plannedArtifactsPath) !== path.dirname(transcriptPath) ||
+			path.dirname(plannedTranscriptPath) !== path.dirname(transcriptPath) ||
+			!path.basename(plannedArtifactsPath).startsWith(".skc-delete-") ||
+			!path.basename(plannedTranscriptPath).startsWith(".skc-delete-") ||
+			plannedArtifactsPath === plannedTranscriptPath
+		) {
+			throw new SessionDeleteVerificationError(
+				"artifacts",
+				"Verified deletion requires caller-persisted quarantine paths",
+			);
+		}
+		const cleanupTranscriptPath = detachedTranscriptPath ?? transcriptPath;
+		const hasDetachedTranscript = detachedTranscriptPath !== undefined;
+		if (
+			detachedTranscriptPath &&
+			(path.dirname(detachedTranscriptPath) !== path.dirname(transcriptPath) ||
+				!path.basename(detachedTranscriptPath).startsWith(".skc-delete-") ||
+				detachedTranscriptPath === plannedTranscriptPath)
+		) {
+			throw new SessionDeleteVerificationError(
+				"identity",
+				"Detached transcript retry requires a fresh quarantine destination",
+			);
+		}
+		if (hasDetachedTranscript && fs.existsSync(transcriptPath)) {
+			throw new SessionDeleteVerificationError(
+				"identity",
+				"Original transcript pathname became occupied during detached cleanup replay",
+			);
+		}
+		const artifactRemovalRoot = `${plannedArtifactsPath}.removing`;
+		if (detachedArtifactsPath === plannedArtifactsPath) {
+			throw new SessionDeleteVerificationError(
+				"artifacts",
+				"Detached artifact retry requires a fresh quarantine destination",
+			);
+		}
+		const retainedArtifactRoot = (input: string): string =>
+			input.endsWith(".removing") ? input : `${input}.removing`;
+
+		const initial = hasDetachedTranscript ? undefined : this.#verifiedReadAndHeader(transcriptPath, sessionId, cwd);
+		const initialStat = initial?.snapshot.stat;
+		const initialDigest = initial ? createHash("sha256").update(initial.snapshot.bytes).digest("hex") : undefined;
+		if (
+			initialStat &&
+			(initialStat.dev !== transcriptIdentity.dev ||
+				initialStat.ino !== transcriptIdentity.ino ||
+				initialStat.size !== transcriptIdentity.size ||
+				initialStat.mtimeNs !== transcriptIdentity.mtimeNs ||
+				initialDigest !== transcriptIdentity.sha256)
+		) {
 			throw new SessionDeleteVerificationError("identity", "Transcript identity does not match authorization");
 		}
+
 		const parentIdentity = this.#directoryIdentity(path.dirname(transcriptPath));
+		if (detachedArtifactsPath) {
+			if (
+				!expectedArtifactsIdentity ||
+				path.dirname(detachedArtifactsPath) !== path.dirname(transcriptPath) ||
+				!path.basename(detachedArtifactsPath).startsWith(".skc-delete-")
+			) {
+				throw new SessionDeleteVerificationError("artifacts", "Detached artifact cleanup evidence is invalid");
+			}
+			const detachedIdentity = this.#optionalDirectoryIdentity(detachedArtifactsPath);
+			if (
+				!detachedIdentity ||
+				detachedIdentity.dev !== expectedArtifactsIdentity.dev ||
+				detachedIdentity.ino !== expectedArtifactsIdentity.ino
+			) {
+				throw new SessionDeleteVerificationError("artifacts", "Detached artifact identity changed before retry");
+			}
+			if (!expectedArtifactsTree)
+				throw new SessionDeleteVerificationError(
+					"artifacts",
+					"Detached artifact cleanup requires a persisted tree snapshot",
+				);
+			const removal = removeDirectoryTreeExact(detachedArtifactsPath, expectedArtifactsTree);
+			if (!removal.ok) {
+				const retainedRoot = removal.detachedPath ?? detachedArtifactsPath;
+				if (retainedRoot !== detachedArtifactsPath && retainedRoot !== retainedArtifactRoot(detachedArtifactsPath))
+					throw new SessionDeleteVerificationError(
+						"artifacts",
+						"Native artifact removal returned an unauthorized root",
+					);
+				return {
+					kind: "cleanup_pending",
+					phase: "artifacts",
+					error: new SessionDeleteVerificationError(
+						"artifacts",
+						`Exact detached artifact removal rejected: ${removal.code}`,
+					),
+					artifactsIdentity: expectedArtifactsIdentity,
+					detachedArtifactsPath: retainedRoot,
+					artifactsTree: expectedArtifactsTree,
+					transcriptIdentity,
+				};
+			}
+		}
 
+		if (artifactsRemoved && (detachedArtifactsPath || expectedArtifactsIdentity)) {
+			throw new SessionDeleteVerificationError(
+				"artifacts",
+				"Artifact phase receipt conflicts with pending artifact cleanup",
+			);
+		}
 		const artifactsDir = transcriptPath.slice(0, -6);
 		const artifactsIdentity = this.#optionalDirectoryIdentity(artifactsDir);
-		if (artifactsIdentity) {
+		if (artifactsRemoved && artifactsIdentity) {
+			throw new SessionDeleteVerificationError(
+				"artifacts",
+				"Artifact path reappeared after durable artifact-phase completion",
+			);
+		}
+		if (!artifactsIdentity && expectedArtifactsIdentity && !detachedArtifactsPath && !artifactsRemoved) {
+			// Absence at the original path alone is not completion: native recursive removal
+			// may retain the planned root or its deterministic `.removing` final-stage root.
+			if (fs.existsSync(plannedArtifactsPath) || fs.existsSync(artifactRemovalRoot))
+				throw new SessionDeleteVerificationError(
+					"artifacts",
+					"Authorized artifact removal root remains after restart",
+				);
+			return { kind: "artifacts_removed", phase: "artifacts", transcriptIdentity };
+		}
+
+		if (artifactsIdentity && !artifactsRemoved) {
 			if (
 				expectedArtifactsIdentity &&
 				(artifactsIdentity.dev !== expectedArtifactsIdentity.dev ||
-					artifactsIdentity.ino !== expectedArtifactsIdentity.ino)
+					artifactsIdentity.ino !== expectedArtifactsIdentity.ino ||
+					artifactsIdentity.size !== expectedArtifactsIdentity.size ||
+					artifactsIdentity.mtimeNs !== expectedArtifactsIdentity.mtimeNs ||
+					artifactsIdentity.sha256 !== expectedArtifactsIdentity.sha256)
 			) {
 				throw new SessionDeleteVerificationError(
 					"artifacts",
 					"Artifact directory identity does not match recorded cleanup evidence",
 				);
 			}
-			try {
-				await fsp.rm(artifactsDir, { recursive: true, force: true });
-			} catch (err) {
+			const artifactStat = fs.lstatSync(artifactsDir, { bigint: true });
+			if (
+				artifactStat.isSymbolicLink() ||
+				!artifactStat.isDirectory() ||
+				artifactStat.dev !== artifactsIdentity.dev ||
+				artifactStat.ino !== artifactsIdentity.ino
+			) {
+				throw new SessionDeleteVerificationError("artifacts", "Artifact directory changed before deletion");
+			}
+			const observedArtifactsTree = snapshotDirectoryTree(artifactsDir);
+			if (expectedArtifactsTree && JSON.stringify(observedArtifactsTree) !== JSON.stringify(expectedArtifactsTree))
+				throw new SessionDeleteVerificationError("artifacts", "Artifact tree changed before root detach");
+			const artifactsTree = expectedArtifactsTree ?? observedArtifactsTree;
+			const detach = nativeExactUnlink(artifactsDir, {
+				dev: artifactStat.dev,
+				ino: artifactStat.ino,
+				size: artifactStat.size,
+				mtimeNs: artifactStat.mtimeNs,
+				directory: true,
+				quarantineName: path.basename(plannedArtifactsPath),
+			});
+			if (!detach.ok || !detach.detachedPath) {
+				throw new SessionDeleteVerificationError(
+					"artifacts",
+					`Exact artifact detach rejected: ${detach.ok ? "missing_path" : detach.code}`,
+				);
+			}
+			const removal = removeDirectoryTreeExact(detach.detachedPath, artifactsTree);
+			if (!removal.ok) {
+				const retainedRoot = removal.detachedPath ?? detach.detachedPath;
+				if (retainedRoot !== detach.detachedPath && retainedRoot !== retainedArtifactRoot(detach.detachedPath))
+					throw new SessionDeleteVerificationError(
+						"artifacts",
+						"Native artifact removal returned an unauthorized root",
+					);
 				return {
 					kind: "cleanup_pending",
 					phase: "artifacts",
-					error: toError(err),
+					error: new SessionDeleteVerificationError(
+						"artifacts",
+						`Exact detached artifact removal rejected: ${removal.code}`,
+					),
 					artifactsIdentity,
-					transcriptIdentity: { dev: initialStat.dev, ino: initialStat.ino },
+					detachedArtifactsPath: retainedRoot,
+					artifactsTree,
+					transcriptIdentity,
 				};
 			}
 		}
-
+		if (!artifactsRemoved) {
+			if (process.platform !== "win32") {
+				let descriptor: number | undefined;
+				try {
+					descriptor = fs.openSync(
+						path.dirname(transcriptPath),
+						fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW,
+					);
+					const durableParent = fs.fstatSync(descriptor, { bigint: true });
+					if (
+						!durableParent.isDirectory() ||
+						durableParent.dev !== parentIdentity.dev ||
+						durableParent.ino !== parentIdentity.ino
+					)
+						throw new Error("parent_changed");
+					fs.fsyncSync(descriptor);
+				} catch (error) {
+					throw new SessionDeleteVerificationError("artifacts", "durability_failed", { cause: toError(error) });
+				} finally {
+					if (descriptor !== undefined) fs.closeSync(descriptor);
+				}
+			}
+			return { kind: "artifacts_removed", phase: "artifacts", transcriptIdentity };
+		}
+		if (hasDetachedTranscript) {
+			const deletion = nativeExactUnlink(cleanupTranscriptPath, {
+				dev: transcriptIdentity.dev,
+				ino: transcriptIdentity.ino,
+				size: BigInt(transcriptIdentity.size),
+				mtimeNs: transcriptIdentity.mtimeNs,
+				sha256: transcriptIdentity.sha256,
+				quarantineName: path.basename(plannedTranscriptPath),
+			});
+			if (!deletion.ok) {
+				const error = exactUnlinkFailure(deletion);
+				if (error.kind === "identity" || error.kind === "symlink") throw error;
+				return {
+					kind: "cleanup_pending",
+					phase: "transcript",
+					error,
+					transcriptIdentity,
+					detachedTranscriptPath: deletion.detachedPath ?? detachedTranscriptPath,
+				};
+			}
+			return { kind: "deleted" };
+		}
+		if (!initialStat || !initialDigest)
+			throw new SessionDeleteVerificationError("stat", "Transcript cleanup state is invalid");
 		const revalidate = this.#verifiedReadAndHeader(transcriptPath, sessionId, cwd);
 		const revalidateStat = revalidate.snapshot.stat;
-		if (revalidateStat.dev !== initialStat.dev || revalidateStat.ino !== initialStat.ino) {
+		const revalidateDigest = createHash("sha256").update(revalidate.snapshot.bytes).digest("hex");
+		if (
+			revalidateStat.dev !== initialStat.dev ||
+			revalidateStat.ino !== initialStat.ino ||
+			revalidateStat.size !== initialStat.size ||
+			revalidateStat.mtimeNs !== initialStat.mtimeNs ||
+			revalidateDigest !== initialDigest
+		) {
 			throw new SessionDeleteVerificationError(
 				"identity",
 				"Transcript identity changed after artifact removal (replacement detected)",
 			);
 		}
+
 		const parentIdentityNow = this.#directoryIdentity(path.dirname(transcriptPath));
 		if (parentIdentityNow.dev !== parentIdentity.dev || parentIdentityNow.ino !== parentIdentity.ino) {
 			throw new SessionDeleteVerificationError("identity", "Parent directory identity changed during deletion");
 		}
 
-		try {
-			await this.unlink(transcriptPath);
-		} catch (err) {
-			if (isEnoent(err)) return { kind: "deleted" };
+		this.#assertPathMatchesSnapshot(transcriptPath, revalidate.snapshot);
+		if (!Number.isSafeInteger(revalidateStat.size) || revalidateStat.size < 0) {
+			throw new SessionDeleteVerificationError("identity", "Transcript size cannot be bound exactly for deletion");
+		}
+		const deletion = nativeExactUnlink(transcriptPath, {
+			dev: initialStat.dev,
+			ino: initialStat.ino,
+			size: BigInt(initialStat.size),
+			mtimeNs: initialStat.mtimeNs,
+			sha256: initialDigest,
+			quarantineName: path.basename(plannedTranscriptPath),
+		});
+		if (!deletion.ok) {
+			const error = exactUnlinkFailure(deletion);
+			if (error.kind === "identity" || error.kind === "symlink") throw error;
 			return {
 				kind: "cleanup_pending",
 				phase: "transcript",
-				error: toError(err),
-				transcriptIdentity: { dev: revalidateStat.dev, ino: revalidateStat.ino },
+				error,
+				transcriptIdentity,
+				detachedTranscriptPath: deletion.detachedPath,
 			};
 		}
 		return { kind: "deleted" };
@@ -614,12 +1103,33 @@ export class FileSessionStorage implements SessionStorage {
 		if (typeof header.cwd !== "string") {
 			throw new SessionDeleteVerificationError("cwd", "Transcript header is missing a cwd");
 		}
-		if (path.resolve(header.cwd) !== path.resolve(expectedCwd)) {
+		if (canonicalPathSync(header.cwd) !== canonicalPathSync(expectedCwd)) {
 			throw new SessionDeleteVerificationError("cwd", "Transcript header cwd does not match authorization");
 		}
 		return { snapshot };
 	}
 
+	#assertPathMatchesSnapshot(transcriptPath: string, snapshot: SessionStorageSnapshot): void {
+		let named: fs.BigIntStats;
+		try {
+			named = fs.lstatSync(transcriptPath, { bigint: true });
+		} catch (err) {
+			throw new SessionDeleteVerificationError("stat", "Transcript path could not be revalidated", {
+				cause: toError(err),
+			});
+		}
+		if (
+			named.isSymbolicLink() ||
+			!named.isFile() ||
+			named.dev !== snapshot.stat.dev ||
+			named.ino !== snapshot.stat.ino ||
+			Number(named.size) !== snapshot.stat.size ||
+			named.mtimeNs !== snapshot.stat.mtimeNs
+		) {
+			throw new SessionDeleteVerificationError("identity", "Transcript path changed before deletion");
+		}
+	}
+
 	#directoryIdentity(dirPath: string): SessionStorageFileIdentity {
 		let stat: fs.BigIntStats;
 		try {
@@ -630,7 +1140,7 @@ export class FileSessionStorage implements SessionStorage {
 		if (stat.isSymbolicLink() || !stat.isDirectory()) {
 			throw new SessionDeleteVerificationError("symlink", "Directory is a symlink or not a directory");
 		}
-		return { dev: stat.dev, ino: stat.ino };
+		return { dev: stat.dev, ino: stat.ino, size: Number(stat.size), mtimeNs: stat.mtimeNs, sha256: "" };
 	}
 
 	#optionalDirectoryIdentity(dirPath: string): SessionStorageFileIdentity | undefined {
@@ -653,7 +1163,7 @@ export class FileSessionStorage implements SessionStorage {
 			// Fail closed before any mutation.
 			throw new SessionDeleteVerificationError("artifacts", "Artifact path exists but is not a directory");
 		}
-		return { dev: stat.dev, ino: stat.ino };
+		return { dev: stat.dev, ino: stat.ino, size: Number(stat.size), mtimeNs: stat.mtimeNs, sha256: "" };
 	}
 }