@gajae-code/coding-agent 0.11.4 → 0.11.6

package/src/session/internal/managed-session-storage.ts

@@ -1,8 +1,21 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as fsp from "node:fs/promises";
 import * as path from "node:path";
-import { applyOwnerOnlyPathSecurity, renameNoReplacePath, verifyOwnerOnlyPathSecurity } from "@gajae-code/natives";
+import {
+	applyOwnerOnlyFdSecurity,
+	applyOwnerOnlyPathSecurity,
+	exactRemoveDirectoryTree,
+	exactUnlink,
+	type NativeDirectoryTreeSnapshot,
+	type NativeOwnerOnlySecurityResult,
+	openRecoveryFsRoot,
+	type RecoveryFsRoot,
+	renameNoReplacePath,
+	snapshotDirectoryTree,
+	verifyOwnerOnlyFdSecurity,
+	verifyOwnerOnlyPathSecurity,
+} from "@gajae-code/natives";
 
 export const MANAGED_ARTIFACT_MAX_DEPTH = 32;
 export const MANAGED_ARTIFACT_MAX_FILES = 10_000;
@@ -34,10 +47,121 @@ export interface ManagedStorageLock {
 
 export interface ManagedFileSnapshot {
 	bytes: Buffer;
-	identity: { dev: bigint; ino: bigint; size: number; mtimeNs: bigint };
+	identity: { dev: bigint; ino: bigint; size: number; mtimeNs: bigint; ctimeNs: bigint; sha256: string };
 }
 
-type NativeSecurity = { ok: true } | { ok: false; code: string };
+const ACL_FAILURE_CODES = new Set(["acl_denied", "acl_io_error", "acl_present", "acl_malformed", "acl_unknown"]);
+const ACL_CLEAR_EVIDENCE = new Set(["cleared", "already_absent", "unsupported", "not_run"]);
+const GENERAL_FAILURE_CODES = new Set([
+	"acl_unavailable",
+	"acl_apply_failed",
+	"acl_verify_failed",
+	"not_found",
+	"not_directory",
+	"network_unsupported",
+	"reparse_point",
+	"identity_unavailable",
+	"identity_mismatch",
+	"owner_mismatch",
+	"mode_mismatch",
+	"io_error",
+]);
+
+function hasOnlyKeys(value: Record<string, unknown>, allowed: readonly string[]): boolean {
+	return Object.keys(value).every(key => allowed.includes(key));
+}
+const ACL_QUERY_EVIDENCE = new Set(["absent", "unsupported"]);
+
+export function validateNativeSecurityResult(
+	value: unknown,
+	operation: "apply" | "verify",
+	kind: "directory" | "file",
+): NativeOwnerOnlySecurityResult {
+	if (!value || typeof value !== "object" || typeof (value as { ok?: unknown }).ok !== "boolean") {
+		throw new Error("Malformed owner-only security result");
+	}
+	const result = value as Record<string, unknown>;
+	if (result.ok === false) {
+		if (typeof result.code !== "string") throw new Error("Malformed owner-only security failure");
+		if (!ACL_FAILURE_CODES.has(result.code) && !GENERAL_FAILURE_CODES.has(result.code)) {
+			throw new Error("Unknown owner-only security failure code");
+		}
+		if (ACL_FAILURE_CODES.has(result.code)) {
+			if (
+				(result.operation !== "clear" && result.operation !== "query") ||
+				(result.attribute !== "access" && result.attribute !== "default")
+			) {
+				throw new Error("Malformed ACL security failure evidence");
+			}
+		} else if (result.operation !== undefined || result.attribute !== undefined) {
+			throw new Error("Unexpected ACL fields on owner-only security failure");
+		}
+		if (!hasOnlyKeys(result, ["ok", "code", "operation", "attribute"])) {
+			throw new Error("Unexpected owner-only security failure fields");
+		}
+		return value as NativeOwnerOnlySecurityResult;
+	}
+	if (process.platform !== "linux") {
+		if (!hasOnlyKeys(result, ["ok"])) throw new Error("Malformed non-Linux security success");
+		return value as NativeOwnerOnlySecurityResult;
+	}
+	if (result.platform !== "linux" || result.kind !== kind || result.protocol !== operation) {
+		throw new Error("Malformed Linux security success envelope");
+	}
+	if (result.code !== undefined || result.operation !== undefined || result.attribute !== undefined) {
+		throw new Error("Unexpected failure fields on Linux security success");
+	}
+	if (!hasOnlyKeys(result, ["ok", "platform", "kind", "protocol", "aclEvidence"])) {
+		throw new Error("Unexpected Linux security success fields");
+	}
+	const evidence = result.aclEvidence;
+	if (!evidence || typeof evidence !== "object") throw new Error("Missing Linux ACL evidence");
+	const record = evidence as Record<string, unknown>;
+	const validateAttribute = (candidate: unknown): void => {
+		if (!candidate || typeof candidate !== "object") throw new Error("Malformed Linux ACL attribute evidence");
+		const attribute = candidate as Record<string, unknown>;
+		if (!hasOnlyKeys(attribute, ["clear", "query"])) throw new Error("Unexpected Linux ACL evidence fields");
+		if (!ACL_CLEAR_EVIDENCE.has(String(attribute.clear)) || !ACL_QUERY_EVIDENCE.has(String(attribute.query))) {
+			throw new Error("Unknown Linux ACL attribute evidence");
+		}
+		if (operation === "verify" && attribute.clear !== "not_run") {
+			throw new Error("Verify result unexpectedly reports ACL mutation");
+		}
+		if (operation === "apply" && attribute.clear === "not_run") {
+			throw new Error("Apply result omitted ACL mutation evidence");
+		}
+	};
+	validateAttribute(record.access);
+	if (kind === "directory") validateAttribute(record.default);
+	else if (record.default !== undefined) throw new Error("File result unexpectedly carries default ACL evidence");
+	if (!hasOnlyKeys(record, kind === "directory" ? ["access", "default"] : ["access"])) {
+		throw new Error("Unexpected Linux ACL evidence attributes");
+	}
+	return value as NativeOwnerOnlySecurityResult;
+}
+
+type NativeSecurity = NativeOwnerOnlySecurityResult;
+type RetainedManagedReplacer = {
+	replaceManaged(
+		relativePath: string,
+		bytes: Uint8Array,
+		expectedDev: string,
+		expectedIno: string,
+		expectedSize: string,
+		expectedMtimeNs: string,
+		expectedCtimeNs: string,
+		expectedSha256: string,
+	): { ok: boolean; code?: string };
+	removeManaged(
+		relativePath: string,
+		expectedDev: string,
+		expectedIno: string,
+		expectedSize: string,
+		expectedMtimeNs: string,
+		expectedCtimeNs: string,
+		expectedSha256: string,
+	): { ok: boolean; code?: string };
+};
 type LockRecord = {
 	attemptId: string;
 	pid: number;
@@ -48,6 +172,80 @@ type LockRecord = {
 	leaseExpiresAt: number;
 };
 
+/** Captured configured-root authority for managed paths only. */
+export interface ManagedDirectoryRoot {
+	readonly canonicalPath: string;
+	readonly dev: bigint;
+	readonly ino: bigint;
+}
+
+export function managedDirectoryRoot(configuredRoot: string): ManagedDirectoryRoot {
+	const canonicalPath = fs.realpathSync.native(configuredRoot);
+	const stat = fs.lstatSync(canonicalPath, { bigint: true });
+	if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`Unsafe managed root: ${configuredRoot}`);
+	return Object.freeze({ canonicalPath, dev: stat.dev, ino: stat.ino });
+}
+
+export function retainManagedDirectoryAuthority(
+	root: ManagedDirectoryRoot,
+	directory: string,
+	expected?: { dev: bigint; ino: bigint },
+): RecoveryFsRoot | undefined {
+	assertManagedDirectoryRoot(root);
+	managedRelativePath(root, directory);
+	const resolved = path.resolve(directory);
+	if (process.platform !== "linux") return undefined;
+	const named = fs.lstatSync(resolved, { bigint: true });
+	if (!named.isDirectory() || named.isSymbolicLink()) throw new Error("Managed directory authority is unavailable");
+	if (expected && (named.dev !== expected.dev || named.ino !== expected.ino))
+		throw new Error("Managed directory identity changed before retention");
+	const rootAuthority = openRecoveryFsRoot(root.canonicalPath);
+	try {
+		const retainedRoot = rootAuthority.identity();
+		if (
+			!retainedRoot.ok ||
+			!retainedRoot.identity ||
+			retainedRoot.identity.dev !== root.dev.toString() ||
+			retainedRoot.identity.ino !== root.ino.toString()
+		)
+			throw new Error("Managed root authority changed");
+		const relative = path.relative(root.canonicalPath, resolved).split(path.sep).join("/");
+		return rootAuthority.retainManagedDirectory(relative, named.dev.toString(), named.ino.toString());
+	} finally {
+		rootAuthority.close();
+	}
+}
+
+function ensureDirectoryComponent(pathname: string): void {
+	try {
+		fs.mkdirSync(pathname, { mode: 0o700 });
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+	}
+	assertSafeDirectory(pathname);
+	secure(pathname, "directory");
+}
+
+export function assertManagedDirectoryRoot(root: ManagedDirectoryRoot): void {
+	const named = fs.lstatSync(root.canonicalPath, { bigint: true });
+	if (!named.isDirectory() || named.isSymbolicLink() || named.dev !== root.dev || named.ino !== root.ino) {
+		throw new Error(`Managed root authority changed: ${root.canonicalPath}`);
+	}
+}
+
+/** Verify the configured root without rewriting its ownership, mode, or ACLs. */
+function ensureManagedRoot(root: ManagedDirectoryRoot): void {
+	assertManagedDirectoryRoot(root);
+}
+
+function managedRelativePath(root: ManagedDirectoryRoot, pathname: string): readonly string[] {
+	const relative = path.relative(root.canonicalPath, path.resolve(pathname));
+	if (relative === "") return [];
+	if (path.isAbsolute(relative) || relative.split(path.sep).includes(".."))
+		throw new Error(`Managed path escapes configured root: ${pathname}`);
+	return relative.split(path.sep);
+}
+
 const PROCESS_START_ID = randomUUID();
 
 function securityError(pathname: string, result: NativeSecurity): Error {
@@ -59,12 +257,719 @@ function securityError(pathname: string, result: NativeSecurity): Error {
 }
 
 function secure(pathname: string, kind: "directory" | "file"): void {
-	const applied = applyOwnerOnlyPathSecurity(pathname, kind) as NativeSecurity;
+	const applied = validateNativeSecurityResult(applyOwnerOnlyPathSecurity(pathname, kind), "apply", kind);
 	if (!applied.ok) throw securityError(pathname, applied);
-	const verified = verifyOwnerOnlyPathSecurity(pathname, kind) as NativeSecurity;
+	const verified = validateNativeSecurityResult(verifyOwnerOnlyPathSecurity(pathname, kind), "verify", kind);
 	if (!verified.ok) throw securityError(pathname, verified);
 }
 
+/** Internal retained-root capability for one managed descendant subtree. */
+export class ManagedSessionDescendantStore {
+	readonly #root: ManagedDirectoryRoot;
+	readonly #baseDir: string;
+	readonly #authority: RecoveryFsRoot | undefined;
+	readonly #authorityBaseDir: string;
+	readonly #subtreeRoot: ManagedDirectoryRoot;
+
+	constructor(
+		root: ManagedDirectoryRoot,
+		baseDir: string,
+		retained?: { authority: RecoveryFsRoot; authorityBaseDir: string },
+	) {
+		assertManagedDirectoryRoot(root);
+		managedRelativePath(root, baseDir);
+		this.#root = root;
+		this.#baseDir = path.resolve(baseDir);
+		this.#authorityBaseDir = retained?.authorityBaseDir ?? this.#baseDir;
+		if (retained) {
+			const relative = path.relative(retained.authorityBaseDir, this.#baseDir).split(path.sep).join("/");
+			const captured = retained.authority.snapshotManagedTree(relative);
+			if (!captured.ok || !captured.snapshot)
+				throw new Error(captured.code ?? "Managed subtree identity unavailable");
+			const subtreeStat = fs.lstatSync(this.#baseDir, { bigint: true });
+			if (
+				captured.snapshot.rootDev !== subtreeStat.dev.toString() ||
+				captured.snapshot.rootIno !== subtreeStat.ino.toString()
+			)
+				throw new Error("Managed descendant root identity changed");
+			this.#subtreeRoot = Object.freeze({
+				canonicalPath: this.#baseDir,
+				dev: subtreeStat.dev,
+				ino: subtreeStat.ino,
+			});
+			this.#authority = retained.authority;
+			return;
+		}
+		ensureManagedDirectory(this.#baseDir, root);
+		const subtreeStat = fs.lstatSync(this.#baseDir, { bigint: true });
+		this.#subtreeRoot = Object.freeze({ canonicalPath: this.#baseDir, dev: subtreeStat.dev, ino: subtreeStat.ino });
+		if (process.platform === "linux") {
+			const before = fs.lstatSync(this.#baseDir, { bigint: true });
+			const authority = openRecoveryFsRoot(this.#baseDir);
+			const retained = authority.identity();
+			if (
+				!retained.ok ||
+				!retained.identity ||
+				retained.identity.dev !== before.dev.toString() ||
+				retained.identity.ino !== before.ino.toString()
+			) {
+				authority.close();
+				throw new Error("Managed descendant root identity changed");
+			}
+			this.#authority = authority;
+		}
+	}
+
+	get dir(): string {
+		return this.#baseDir;
+	}
+
+	get rootAuthority(): ManagedDirectoryRoot {
+		return this.#root;
+	}
+
+	get subtreeRootAuthority(): ManagedDirectoryRoot {
+		return this.#subtreeRoot;
+	}
+
+	deriveSubtree(relativePath: string): ManagedSessionDescendantStore {
+		const child = this.ensureDirectory(relativePath);
+		const resolved = this.#resolve(relativePath);
+		if (!this.#authority) return new ManagedSessionDescendantStore(this.#root, resolved);
+		const retainedChild = this.#authority.retainManagedDirectory(
+			this.#relative(resolved),
+			child.dev.toString(),
+			child.ino.toString(),
+		);
+		return new ManagedSessionDescendantStore(this.#root, resolved, {
+			authority: retainedChild,
+			authorityBaseDir: resolved,
+		});
+	}
+
+	retainAuthority(): RecoveryFsRoot | undefined {
+		if (!this.#authority) return undefined;
+		return this.#authority.retainManagedDirectory(
+			"",
+			this.#subtreeRoot.dev.toString(),
+			this.#subtreeRoot.ino.toString(),
+		);
+	}
+
+	assertBound(): void {
+		this.#assertBound();
+	}
+
+	verifyRootSecurity(): void {
+		this.#assertBound();
+		if (this.#authority) {
+			if (this.#authorityBaseDir === this.#baseDir) {
+				const verified = this.#authority.verifyOwnerOnlyDirectory();
+				if (!verified.ok) throw new Error(verified.code ?? "acl_verify_failed");
+			} else {
+				this.#assertBound();
+				return;
+			}
+		} else {
+			const verified = validateNativeSecurityResult(
+				verifyOwnerOnlyPathSecurity(this.#baseDir, "directory"),
+				"verify",
+				"directory",
+			);
+			if (!verified.ok) throw securityError(this.#baseDir, verified);
+		}
+		this.#assertBound();
+	}
+	#assertBound(): void {
+		if (!this.#authority) return;
+		const named = fs.lstatSync(this.#baseDir, { bigint: true });
+		const retained =
+			this.#authorityBaseDir === this.#baseDir
+				? this.#authority.identity()
+				: (() => {
+						const relative = path.relative(this.#authorityBaseDir, this.#baseDir).split(path.sep).join("/");
+						const captured = this.#authority?.snapshotManagedTree(relative);
+						return captured?.ok && captured.snapshot
+							? { ok: true, identity: { dev: captured.snapshot.rootDev, ino: captured.snapshot.rootIno } }
+							: { ok: false, identity: undefined };
+					})();
+		if (
+			!retained.ok ||
+			!retained.identity ||
+			!named.isDirectory() ||
+			named.isSymbolicLink() ||
+			retained.identity.dev !== named.dev.toString() ||
+			retained.identity.dev !== this.#subtreeRoot.dev.toString() ||
+			retained.identity.ino !== this.#subtreeRoot.ino.toString() ||
+			retained.identity.ino !== named.ino.toString()
+		) {
+			throw new Error("Managed descendant root binding changed");
+		}
+	}
+
+	ensureDirectory(relativePath = ""): ManagedDirectoryRoot {
+		this.#assertBound();
+		if (this.#authority) {
+			const relative = this.#relative(this.#resolve(relativePath));
+			if (relative === "") return this.#subtreeRoot;
+			const ensured = this.#authority.ensureManagedDirectory(relative);
+			if (!ensured.ok || !ensured.identity) throw new Error(ensured.code ?? "managed_directory_create_failed");
+			this.#assertBound();
+			return Object.freeze({
+				canonicalPath: this.#resolve(relativePath),
+				dev: BigInt(ensured.identity.dev),
+				ino: BigInt(ensured.identity.ino),
+			});
+		}
+		ensureManagedDirectory(this.#resolve(relativePath), this.#root);
+		const named = fs.lstatSync(this.#resolve(relativePath), { bigint: true });
+		return Object.freeze({ canonicalPath: this.#resolve(relativePath), dev: named.dev, ino: named.ino });
+	}
+
+	async publishNoReplace(relativePath: string, bytes: Uint8Array): Promise<void> {
+		const resolved = this.#resolve(relativePath);
+		if (this.#authority) {
+			this.#assertBound();
+			this.#publishRetainedNoReplace(this.#relative(resolved), bytes);
+			this.#assertBound();
+			return;
+		}
+		await publishManagedFileNoReplace(resolved, bytes, undefined, this.#root);
+	}
+
+	publishNoReplaceSync(relativePath: string, bytes: Uint8Array): void {
+		const resolved = this.#resolve(relativePath);
+		if (!this.#authority) {
+			publishManagedFileNoReplaceSync(resolved, bytes, this.#root);
+			this.#assertBound();
+			return;
+		}
+		this.#assertBound();
+		this.#publishRetainedNoReplace(this.#relative(resolved), bytes);
+		this.#assertBound();
+	}
+
+	async replace(relativePath: string, bytes: Uint8Array): Promise<void> {
+		this.#assertBound();
+		const resolved = this.#resolve(relativePath);
+		if (!this.#authority) {
+			await replaceManagedFile(resolved, bytes, this.#subtreeRoot);
+			this.#assertBound();
+			return;
+		}
+		const relative = this.#relative(resolved);
+		this.#replaceRetained(relative, bytes);
+		this.#assertBound();
+	}
+
+	replaceSync(relativePath: string, bytes: Uint8Array): void {
+		this.#assertBound();
+		const resolved = this.#resolve(relativePath);
+		if (!this.#authority) {
+			replaceManagedFileSync(resolved, bytes, this.#subtreeRoot);
+			this.#assertBound();
+			return;
+		}
+		this.#replaceRetained(this.#relative(resolved), bytes);
+		this.#assertBound();
+	}
+
+	appendSync(relativePath: string, bytes: Uint8Array): void {
+		this.#assertBound();
+		const resolved = this.#resolve(relativePath);
+		const existing = this.readExpected(relativePath);
+		if (!existing) throw new Error("managed_append_missing");
+		if (this.#authority) {
+			const appended = this.#authority.appendManaged(
+				this.#relative(resolved),
+				bytes,
+				existing.identity.dev.toString(),
+				existing.identity.ino.toString(),
+				existing.identity.size.toString(),
+				existing.identity.mtimeNs.toString(),
+				existing.identity.ctimeNs.toString(),
+				existing.identity.sha256,
+			);
+			if (!appended.ok) throw new Error(appended.code ?? "managed_append_failed");
+			this.#assertBound();
+			return;
+		}
+		let fd: number | undefined;
+		try {
+			fd = fs.openSync(resolved, fs.constants.O_WRONLY | fs.constants.O_APPEND | fs.constants.O_NOFOLLOW);
+			const before = identity(fs.fstatSync(fd, { bigint: true }));
+			if (!sameIdentity(before, existing.identity)) throw new Error("identity_mismatch");
+			secureFileDescriptor(resolved, fd, "verify");
+			let offset = 0;
+			while (offset < bytes.byteLength) offset += fs.writeSync(fd, bytes, offset, bytes.byteLength - offset);
+			fs.fsyncSync(fd);
+			secureFileDescriptor(resolved, fd, "verify");
+			const after = identity(fs.fstatSync(fd, { bigint: true }));
+			const named = identity(fs.lstatSync(resolved, { bigint: true }));
+			if (!sameIdentity(after, named) || after.dev !== before.dev || after.ino !== before.ino)
+				throw new Error("identity_mismatch");
+		} finally {
+			if (fd !== undefined) fs.closeSync(fd);
+		}
+		this.#assertBound();
+	}
+
+	#relative(resolved: string): string {
+		return path.relative(this.#authorityBaseDir, resolved).split(path.sep).join("/");
+	}
+
+	#publishRetainedNoReplace(relative: string, bytes: Uint8Array): void {
+		if (!this.#authority) throw new Error("Managed descendant authority is unavailable");
+		const separator = relative.lastIndexOf("/");
+		const parent = separator < 0 ? "" : relative.slice(0, separator);
+		const temporaryName = `.gjc-publish-${process.pid}-${randomUUID()}`;
+		const temporary = parent ? `${parent}/${temporaryName}` : temporaryName;
+		const created = this.#authority.createManaged(temporary, bytes);
+		if (!created.ok) throw new Error(created.code ?? "managed_publish_failed");
+		if (!created.identity) throw new Error("managed_publish_identity_unavailable");
+		let captured: ReturnType<RecoveryFsRoot["readManaged"]> | undefined;
+		try {
+			captured = this.#authority.readManaged(temporary);
+			if (!captured.ok || !captured.identity || !captured.data)
+				throw new Error(captured.code ?? "managed_publish_identity_unavailable");
+			const expectedDigest = createHash("sha256").update(bytes).digest("hex");
+			const digest = captured.identity.sha256 ?? createHash("sha256").update(captured.data).digest("hex");
+			if (
+				captured.identity.dev !== created.identity.dev ||
+				captured.identity.ino !== created.identity.ino ||
+				captured.identity.size !== created.identity.size ||
+				captured.identity.mtimeNs !== created.identity.mtimeNs ||
+				captured.identity.ctimeNs !== created.identity.ctimeNs ||
+				digest !== expectedDigest
+			)
+				throw new Error("managed_publish_identity_mismatch");
+			const synced = this.#authority.fsyncExpected(
+				temporary,
+				false,
+				captured.identity.dev,
+				captured.identity.ino,
+				captured.identity.size,
+				captured.identity.mtimeNs,
+				digest,
+			);
+			if (!synced.ok) throw new Error(synced.code ?? "managed_publish_fsync_failed");
+			const published = this.#authority.renameManagedFileNoReplace(
+				temporary,
+				relative,
+				captured.identity.dev,
+				captured.identity.ino,
+				captured.identity.size,
+				captured.identity.mtimeNs,
+				captured.identity.ctimeNs,
+				digest,
+			);
+			if (!published.ok)
+				throw new Error(
+					published.code === "already_exists"
+						? "destination_conflict"
+						: (published.code ?? "managed_publish_failed"),
+				);
+		} catch (error) {
+			if (captured?.ok && captured.identity && captured.data) {
+				const digest = captured.identity.sha256 ?? createHash("sha256").update(captured.data).digest("hex");
+				const installed = this.#authority.readManaged(relative);
+				if (
+					installed.ok &&
+					installed.identity &&
+					installed.data &&
+					installed.identity.dev === captured.identity.dev &&
+					installed.identity.ino === captured.identity.ino &&
+					(installed.identity.sha256 ?? createHash("sha256").update(installed.data).digest("hex")) === digest
+				) {
+					const removed = this.#authority.removeManaged(
+						relative,
+						installed.identity.dev,
+						installed.identity.ino,
+						installed.identity.size,
+						installed.identity.mtimeNs,
+						installed.identity.ctimeNs,
+						digest,
+					);
+					if (!removed.ok) throw new Error(removed.code ?? "managed_publish_reconcile_failed");
+				}
+				const staged = this.#authority.readManaged(temporary);
+				if (
+					staged.ok &&
+					staged.identity &&
+					staged.data &&
+					staged.identity.dev === captured.identity.dev &&
+					staged.identity.ino === captured.identity.ino
+				) {
+					const removed = this.#authority.removeManaged(
+						temporary,
+						staged.identity.dev,
+						staged.identity.ino,
+						staged.identity.size,
+						staged.identity.mtimeNs,
+						staged.identity.ctimeNs,
+						staged.identity.sha256 ?? createHash("sha256").update(staged.data).digest("hex"),
+					);
+					if (!removed.ok) throw new Error(removed.code ?? "managed_publish_reconcile_failed");
+				}
+			}
+			throw error;
+		}
+	}
+
+	#replaceRetained(relative: string, bytes: Uint8Array): void {
+		if (!this.#authority) throw new Error("Managed descendant authority is unavailable");
+		this.#assertBound();
+		const existing = this.#authority.readManaged(relative);
+		if (!existing.ok) {
+			if (existing.code !== "not_found") throw new Error(existing.code ?? "managed_replace_failed");
+			this.#publishRetainedNoReplace(relative, bytes);
+			return;
+		}
+		if (!existing.identity || !existing.data) throw new Error("Managed descendant identity is unavailable");
+		const replaced = (this.#authority as RecoveryFsRoot & RetainedManagedReplacer).replaceManaged(
+			relative,
+			bytes,
+			existing.identity.dev,
+			existing.identity.ino,
+			existing.identity.size,
+			existing.identity.mtimeNs,
+			existing.identity.ctimeNs,
+			existing.identity.sha256 ?? createHash("sha256").update(existing.data).digest("hex"),
+		);
+		if (!replaced.ok) throw new Error(replaced.code ?? "managed_replace_failed");
+	}
+
+	/** Read an exact managed file without exposing its pathname as authority. */
+	readExpected(relativePath: string): ManagedFileSnapshot | null {
+		this.#assertBound();
+		const relative = this.#relative(this.#resolve(relativePath));
+		if (!this.#authority) {
+			try {
+				return captureManagedFileNoFollow(this.#resolve(relativePath));
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+				throw error;
+			}
+		}
+		const read = this.#authority.readManaged(relative);
+		if (!read.ok) {
+			if (read.code === "not_found") return null;
+			throw new Error(read.code ?? "managed_read_failed");
+		}
+		if (!read.data || !read.identity) throw new Error("Managed descendant identity is unavailable");
+		return {
+			bytes: Buffer.from(read.data),
+			identity: {
+				dev: BigInt(read.identity.dev),
+				ino: BigInt(read.identity.ino),
+				size: Number(read.identity.size),
+				mtimeNs: BigInt(read.identity.mtimeNs),
+				ctimeNs: BigInt(read.identity.ctimeNs),
+				sha256: read.identity.sha256 ?? createHash("sha256").update(read.data).digest("hex"),
+			},
+		};
+	}
+
+	/** Remove an exact captured file without reopening its pathname as authority. */
+	removeExpected(relativePath: string, expected: ManagedFileSnapshot): void {
+		this.#assertBound();
+		if (!this.#authority) {
+			const removed = exactUnlink(this.#resolve(relativePath), {
+				dev: expected.identity.dev,
+				ino: expected.identity.ino,
+				size: BigInt(expected.identity.size),
+				mtimeNs: expected.identity.mtimeNs,
+				sha256: expected.identity.sha256,
+				quarantineName: `.gjc-remove-${process.pid}-${randomUUID()}`,
+			});
+			if (!removed.ok) throw new Error(removed.code ?? "managed_remove_failed");
+			this.#assertBound();
+			return;
+		}
+		const removed = (this.#authority as RecoveryFsRoot & RetainedManagedReplacer).removeManaged(
+			this.#relative(this.#resolve(relativePath)),
+			expected.identity.dev.toString(),
+			expected.identity.ino.toString(),
+			expected.identity.size.toString(),
+			expected.identity.mtimeNs.toString(),
+			expected.identity.ctimeNs.toString(),
+			expected.identity.sha256,
+		);
+		if (!removed.ok) throw new Error(removed.code ?? "managed_remove_failed");
+		this.#assertBound();
+	}
+	/** Read and remove one managed descendant through retained authority. */
+	async consume(relativePath: string): Promise<Uint8Array | null> {
+		this.#assertBound();
+		const resolved = this.#resolve(relativePath);
+		if (this.#authority) {
+			const relative = this.#relative(resolved);
+			const existing = this.#authority.readManaged(relative);
+			if (!existing.ok) {
+				if (existing.code === "not_found") return null;
+				throw new Error(existing.code ?? "managed_read_failed");
+			}
+			if (!existing.identity || !existing.data) throw new Error("Managed descendant identity is unavailable");
+			const removed = (this.#authority as RecoveryFsRoot & RetainedManagedReplacer).removeManaged(
+				relative,
+				existing.identity.dev,
+				existing.identity.ino,
+				existing.identity.size,
+				existing.identity.mtimeNs,
+				existing.identity.ctimeNs,
+				existing.identity.sha256 ?? createHash("sha256").update(existing.data).digest("hex"),
+			);
+			if (!removed.ok) throw new Error(removed.code ?? "managed_consume_failed");
+			this.#assertBound();
+			return existing.data;
+		}
+		let snapshot: ManagedFileSnapshot;
+		try {
+			snapshot = captureManagedFileNoFollow(resolved);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+			throw error;
+		}
+		await unlinkManagedFileVerified(resolved, snapshot.identity);
+		this.#assertBound();
+		return snapshot.bytes;
+	}
+
+	/** Remove one managed descendant through retained authority when it exists. */
+	async remove(relativePath: string): Promise<void> {
+		await this.consume(relativePath);
+	}
+
+	/** Capture a complete descendant tree through this retained root. */
+	captureTree(relativePath: string): NativeDirectoryTreeSnapshot {
+		this.#assertBound();
+		const relative = this.#relative(this.#resolve(relativePath));
+		if (this.#authority) {
+			const captured = this.#authority.snapshotManagedTree(relative);
+			if (!captured.ok || !captured.snapshot) throw new Error(captured.code ?? "unsafe_artifacts");
+			return captured.snapshot;
+		}
+		const captured = snapshotDirectoryTree(this.#resolve(relativePath));
+		if (!captured.ok || !captured.snapshot) throw new Error(captured.code ?? "unsafe_artifacts");
+		return captured.snapshot;
+	}
+
+	/** Copy an exact captured tree into an absent managed destination. */
+	async importTree(
+		sourceRelativePath: string,
+		destinationRelativePath: string,
+		snapshot: NativeDirectoryTreeSnapshot,
+	): Promise<void> {
+		const actual = this.captureTree(sourceRelativePath);
+		if (JSON.stringify(actual) !== JSON.stringify(snapshot)) throw new Error("artifact_source_changed");
+		this.ensureDirectory(destinationRelativePath);
+		for (const entry of snapshot.entries) {
+			if (entry.relativePath === "") continue;
+			const target = path.posix.join(destinationRelativePath.replaceAll(path.sep, "/"), entry.relativePath);
+			if (entry.kind === "directory") this.ensureDirectory(target);
+			else {
+				if (!this.#authority) throw new Error("managed_storage_unsupported");
+				const read = this.#authority.readManaged(
+					this.#relative(
+						this.#resolve(path.posix.join(sourceRelativePath.replaceAll(path.sep, "/"), entry.relativePath)),
+					),
+				);
+				if (
+					!read.ok ||
+					!read.data ||
+					!read.identity ||
+					read.identity.dev !== entry.dev ||
+					read.identity.ino !== entry.ino ||
+					read.identity.size !== entry.size ||
+					read.identity.mtimeNs !== entry.mtimeNs ||
+					createHash("sha256").update(read.data).digest("hex") !== entry.sha256
+				)
+					throw new Error("artifact_source_changed");
+				await this.publishNoReplace(target, read.data);
+			}
+		}
+		const imported = this.captureTree(destinationRelativePath);
+		const comparable = (tree: NativeDirectoryTreeSnapshot) =>
+			tree.entries.map(entry => ({
+				relativePath: entry.relativePath,
+				kind: entry.kind,
+				size: entry.size,
+				sha256: entry.sha256,
+			}));
+		if (JSON.stringify(comparable(imported)) !== JSON.stringify(comparable(snapshot)))
+			throw new Error("artifact_destination_mismatch");
+		this.fsyncTree();
+	}
+
+	moveTreeNoReplace(
+		sourceRelativePath: string,
+		destinationRelativePath: string,
+		expected: NativeDirectoryTreeSnapshot,
+	): void {
+		this.#assertBound();
+		if (!this.#authority) {
+			const source = this.#resolve(sourceRelativePath);
+			const destination = this.#resolve(destinationRelativePath);
+			if (fs.existsSync(destination)) throw new Error("already_exists");
+			let destinationSnapshot: NativeDirectoryTreeSnapshot | undefined;
+			try {
+				this.ensureDirectory(destinationRelativePath);
+				destinationSnapshot = this.captureTree(destinationRelativePath);
+				for (const entry of expected.entries) {
+					if (entry.relativePath === "") continue;
+					const target = path.posix.join(destinationRelativePath.replaceAll(path.sep, "/"), entry.relativePath);
+					if (entry.kind === "directory") {
+						this.ensureDirectory(target);
+						destinationSnapshot = this.captureTree(destinationRelativePath);
+						continue;
+					}
+					const sourceEntry = this.readExpected(
+						path.posix.join(sourceRelativePath.replaceAll(path.sep, "/"), entry.relativePath),
+					);
+					if (
+						!sourceEntry ||
+						sourceEntry.identity.dev.toString() !== entry.dev ||
+						sourceEntry.identity.ino.toString() !== entry.ino ||
+						sourceEntry.identity.size.toString() !== entry.size ||
+						sourceEntry.identity.mtimeNs.toString() !== entry.mtimeNs ||
+						sourceEntry.identity.sha256 !== entry.sha256
+					)
+						throw new Error("artifact_source_changed");
+					this.publishNoReplaceSync(target, sourceEntry.bytes);
+					destinationSnapshot = this.captureTree(destinationRelativePath);
+				}
+				destinationSnapshot = this.captureTree(destinationRelativePath);
+				const comparable = (tree: NativeDirectoryTreeSnapshot) =>
+					tree.entries.map(entry => ({
+						relativePath: entry.relativePath,
+						kind: entry.kind,
+						size: entry.size,
+						sha256: entry.sha256,
+					}));
+				if (JSON.stringify(comparable(destinationSnapshot)) !== JSON.stringify(comparable(expected)))
+					throw new Error("artifact_destination_mismatch");
+				const terminalSource = snapshotDirectoryTree(source);
+				if (
+					!terminalSource.ok ||
+					!terminalSource.snapshot ||
+					JSON.stringify(terminalSource.snapshot) !== JSON.stringify(expected)
+				)
+					throw new Error("artifact_source_changed");
+				const retired = exactRemoveDirectoryTree(source, expected);
+				if (!retired.ok) throw new Error(retired.code ?? "managed_remove_failed");
+			} catch (error) {
+				if (destinationSnapshot) {
+					const removed = exactRemoveDirectoryTree(destination, destinationSnapshot);
+					if (!removed.ok) throw new Error(removed.code ?? "managed_publish_reconcile_failed");
+				}
+				throw error;
+			}
+			this.#assertBound();
+			return;
+		}
+		const moved = this.#authority.renameManagedTreeNoReplace(
+			this.#relative(this.#resolve(sourceRelativePath)),
+			this.#relative(this.#resolve(destinationRelativePath)),
+			expected,
+		);
+		if (!moved.ok) {
+			try {
+				const installed = this.captureTree(destinationRelativePath);
+				const comparable = (tree: NativeDirectoryTreeSnapshot) =>
+					tree.entries.map(entry => ({
+						relativePath: entry.relativePath,
+						kind: entry.kind,
+						size: entry.size,
+						sha256: entry.sha256,
+					}));
+				if (JSON.stringify(comparable(installed)) !== JSON.stringify(comparable(expected)))
+					throw new Error("managed_publish_reconcile_failed");
+				this.removeTreeExpected(destinationRelativePath, installed);
+			} catch (error) {
+				if (!(error instanceof Error) || error.message !== "not_found") throw error;
+			}
+			throw new Error(moved.code ?? "managed_move_failed");
+		}
+		this.#assertBound();
+	}
+
+	removeTreeExpected(relativePath: string, expected: NativeDirectoryTreeSnapshot): void {
+		this.#assertBound();
+		if (!this.#authority) {
+			const removed = exactRemoveDirectoryTree(this.#resolve(relativePath), expected);
+			if (!removed.ok) throw new Error(removed.code ?? "managed_remove_failed");
+			this.#assertBound();
+			return;
+		}
+		const removed = this.#authority.removeManagedTree(this.#relative(this.#resolve(relativePath)), expected);
+		if (!removed.ok) throw new Error(removed.code ?? "managed_remove_failed");
+		this.#assertBound();
+	}
+	fsyncTree(): NativeDirectoryTreeSnapshot {
+		this.#assertBound();
+		if (!this.#authority) return fsyncManagedArtifactTree(this.#baseDir);
+		const baseRelative = this.#relative(this.#baseDir);
+		const before = this.#authority.snapshotManagedTree(baseRelative);
+		if (!before.ok || !before.snapshot) throw new Error(before.code ?? "unsafe_artifacts");
+		const entries = [...before.snapshot.entries].sort((left, right) => {
+			const leftDirectory = left.kind === "directory";
+			const rightDirectory = right.kind === "directory";
+			if (leftDirectory !== rightDirectory) return leftDirectory ? 1 : -1;
+			return right.relativePath.split("/").length - left.relativePath.split("/").length;
+		});
+		for (const entry of entries) {
+			const retainedPath = entry.relativePath ? path.posix.join(baseRelative, entry.relativePath) : baseRelative;
+			const synced = this.#authority.fsyncExpected(
+				retainedPath,
+				entry.kind === "directory",
+				entry.dev,
+				entry.ino,
+				entry.size,
+				entry.mtimeNs,
+				entry.sha256,
+			);
+			if (!synced.ok) throw new Error(synced.code ?? "fsync_failed");
+		}
+		const after = this.#authority.snapshotManagedTree(baseRelative);
+		if (!after.ok || !after.snapshot || JSON.stringify(after.snapshot) !== JSON.stringify(before.snapshot)) {
+			throw new Error("artifact_tree_changed_during_fsync");
+		}
+		this.#assertBound();
+		return after.snapshot;
+	}
+
+	#resolve(relativePath: string): string {
+		if (path.isAbsolute(relativePath) || relativePath.split(/[\\/]/).includes("..")) {
+			throw new Error("Managed descendant path escapes retained store");
+		}
+		const resolved = path.resolve(this.#baseDir, relativePath);
+		if (resolved !== this.#baseDir && !resolved.startsWith(`${this.#baseDir}${path.sep}`)) {
+			throw new Error("Managed descendant path escapes retained store");
+		}
+		assertManagedDirectoryRoot(this.#root);
+		return resolved;
+	}
+}
+
+function secureFileDescriptor(pathname: string, fd: number, operation: "apply" | "verify"): void {
+	if (process.platform !== "linux") {
+		if (operation === "apply") secure(pathname, "file");
+		else {
+			const verified = validateNativeSecurityResult(verifyOwnerOnlyPathSecurity(pathname, "file"), "verify", "file");
+			if (!verified.ok) throw securityError(pathname, verified);
+		}
+		return;
+	}
+	const result = validateNativeSecurityResult(
+		operation === "apply"
+			? applyOwnerOnlyFdSecurity(pathname, "file", fd)
+			: verifyOwnerOnlyFdSecurity(pathname, "file", fd),
+		operation,
+		"file",
+	);
+	if (!result.ok) throw securityError(pathname, result);
+}
+
 function assertSafeDirectory(pathname: string): void {
 	const stat = fs.lstatSync(pathname);
 	if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`Unsafe managed directory: ${pathname}`);
@@ -92,13 +997,24 @@ function bootId(): string | undefined {
 	}
 }
 
-function identity(stat: fs.BigIntStats): ManagedFileSnapshot["identity"] {
-	return { dev: stat.dev, ino: stat.ino, size: Number(stat.size), mtimeNs: stat.mtimeNs };
+function identity(stat: fs.BigIntStats, sha256 = ""): ManagedFileSnapshot["identity"] {
+	return {
+		dev: stat.dev,
+		ino: stat.ino,
+		size: Number(stat.size),
+		mtimeNs: stat.mtimeNs,
+		ctimeNs: stat.ctimeNs,
+		sha256,
+	};
 }
 
 function sameIdentity(left: ManagedFileSnapshot["identity"], right: ManagedFileSnapshot["identity"]): boolean {
 	return (
-		left.dev === right.dev && left.ino === right.ino && left.size === right.size && left.mtimeNs === right.mtimeNs
+		left.dev === right.dev &&
+		left.ino === right.ino &&
+		left.size === right.size &&
+		left.mtimeNs === right.mtimeNs &&
+		left.ctimeNs === right.ctimeNs
 	);
 }
 
@@ -144,19 +1060,46 @@ function sameFileIdentity(left: fs.BigIntStats, right: fs.BigIntStats): boolean
 }
 
 /** Create a managed directory and fail closed unless its owner-only mode/ACL verifies. */
-export function ensureManagedDirectory(pathname: string): void {
-	fs.mkdirSync(pathname, { recursive: true, mode: 0o700 });
-	assertSafeDirectory(pathname);
-	secure(pathname, "directory");
+export function ensureManagedDirectory(pathname: string, root?: ManagedDirectoryRoot): void {
+	if (!root) {
+		fs.mkdirSync(pathname, { recursive: true, mode: 0o700 });
+		assertSafeDirectory(pathname);
+		secure(pathname, "directory");
+		return;
+	}
+	ensureManagedRoot(root);
+	let current = root.canonicalPath;
+	for (const component of managedRelativePath(root, pathname)) {
+		// Re-inspect the captured root or already-secured descendant before every
+		// descent; a replaced component cannot grant authority to the next one.
+		if (current === root.canonicalPath) assertManagedDirectoryRoot(root);
+		else {
+			assertSafeDirectory(current);
+			secure(current, "directory");
+		}
+		current = path.join(current, component);
+		ensureDirectoryComponent(current);
+	}
+}
+
+/** Captures a bounded prefix from one no-follow descriptor and rechecks the pathname before use. */
+export function captureManagedFilePrefixNoFollow(pathname: string, maxBytes: number): ManagedFileSnapshot {
+	if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) throw new Error("invalid_capture_limit");
+	return captureManagedFileNoFollowLimit(pathname, maxBytes);
 }
 
 /** Captures header/hash/copy input from one no-follow descriptor and rechecks the pathname before use. */
 export function captureManagedFileNoFollow(pathname: string): ManagedFileSnapshot {
+	return captureManagedFileNoFollowLimit(pathname);
+}
+
+function captureManagedFileNoFollowLimit(pathname: string, maxBytes?: number): ManagedFileSnapshot {
 	const fd = fs.openSync(pathname, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
 	try {
 		const before = fs.fstatSync(fd, { bigint: true });
 		if (!before.isFile() || before.nlink > 1) throw new Error("source_changed");
-		const bytes = Buffer.alloc(Number(before.size));
+		const captureSize = maxBytes === undefined ? Number(before.size) : Math.min(Number(before.size), maxBytes);
+		const bytes = Buffer.alloc(captureSize);
 		let offset = 0;
 		while (offset < bytes.byteLength) {
 			const count = fs.readSync(fd, bytes, offset, bytes.byteLength - offset, offset);
@@ -168,7 +1111,7 @@ export function captureManagedFileNoFollow(pathname: string): ManagedFileSnapsho
 		const named = fs.lstatSync(pathname, { bigint: true });
 		if (!named.isFile() || named.isSymbolicLink() || !sameIdentity(identity(before), identity(named)))
 			throw new Error("source_changed");
-		return { bytes, identity: identity(before) };
+		return { bytes, identity: identity(before, createHash("sha256").update(bytes).digest("hex")) };
 	} finally {
 		fs.closeSync(fd);
 	}
@@ -179,11 +1122,16 @@ export async function publishManagedFileNoReplace(
 	destination: string,
 	bytes: Uint8Array,
 	assertOwned?: () => void,
+	root?: ManagedDirectoryRoot,
 ): Promise<void> {
 	const parent = path.dirname(destination);
-	ensureManagedDirectory(parent);
+	ensureManagedDirectory(parent, root);
 	const staging = path.join(parent, `.${path.basename(destination)}.${randomUUID()}.staging`);
 	let fd: number | undefined;
+	let stagingIdentity: { dev: bigint; ino: bigint } | undefined;
+	let stagingSnapshot: ManagedFileSnapshot | undefined;
+	let committed = false;
+	let failure: unknown;
 	try {
 		assertOwned?.();
 		fd = fs.openSync(
@@ -191,82 +1139,231 @@ export async function publishManagedFileNoReplace(
 			fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY | fs.constants.O_NOFOLLOW,
 			0o600,
 		);
+		secureFileDescriptor(staging, fd, "apply");
 		let offset = 0;
 		while (offset < bytes.byteLength) offset += fs.writeSync(fd, bytes, offset, bytes.byteLength - offset);
 		fs.fsyncSync(fd);
-		fs.closeSync(fd);
-		fd = undefined;
-		secure(staging, "file");
+		secureFileDescriptor(staging, fd, "verify");
+		const staged = fs.fstatSync(fd, { bigint: true });
+		stagingIdentity = { dev: staged.dev, ino: staged.ino };
+		stagingSnapshot = {
+			bytes: Buffer.from(bytes),
+			identity: identity(staged, createHash("sha256").update(bytes).digest("hex")),
+		};
 		assertOwned?.();
+
 		const published = renameNoReplacePath(staging, destination);
 		if (!published.ok) {
 			if (published.code === "quarantine_collision") throw new Error("destination_conflict");
 			throw new Error("durability_failed");
 		}
-		secure(destination, "file");
+		const named = fs.lstatSync(destination, { bigint: true });
+		if (
+			!named.isFile() ||
+			named.isSymbolicLink() ||
+			named.dev !== stagingIdentity.dev ||
+			named.ino !== stagingIdentity.ino
+		) {
+			throw new Error("destination_identity_changed");
+		}
+		secureFileDescriptor(destination, fd, "verify");
+		fs.closeSync(fd);
+		fd = undefined;
+
 		fsyncDirectory(parent);
+		committed = true;
+	} catch (error) {
+		failure = error;
 	} finally {
 		if (fd !== undefined) fs.closeSync(fd);
-		await fsp.unlink(staging).catch(error => {
-			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
-		});
+		if (!committed && stagingSnapshot) {
+			try {
+				const installed = captureManagedFileNoFollow(destination);
+				if (
+					installed.identity.dev === stagingSnapshot.identity.dev &&
+					installed.identity.ino === stagingSnapshot.identity.ino &&
+					installed.identity.sha256 === stagingSnapshot.identity.sha256
+				)
+					await unlinkManagedFileVerified(destination, installed.identity);
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code !== "ENOENT") failure ??= error;
+			}
+		}
+		if (stagingIdentity) {
+			await fsp
+				.lstat(staging, { bigint: true })
+				.then(stat => {
+					if (stat.dev === stagingIdentity?.dev && stat.ino === stagingIdentity.ino) return fsp.unlink(staging);
+					throw new Error("staging_identity_changed");
+				})
+				.catch(error => {
+					if ((error as NodeJS.ErrnoException).code !== "ENOENT") failure ??= error;
+				});
+		}
 	}
+	if (failure !== undefined) throw failure;
 }
 
-export function publishManagedFileNoReplaceSync(destination: string, bytes: Uint8Array): void {
+export function publishManagedFileNoReplaceSync(
+	destination: string,
+	bytes: Uint8Array,
+	root?: ManagedDirectoryRoot,
+): void {
 	const parent = path.dirname(destination);
-	ensureManagedDirectory(parent);
+	ensureManagedDirectory(parent, root);
 	const staging = path.join(parent, `.${path.basename(destination)}.${randomUUID()}.staging`);
+	let fd: number | undefined;
+	let stagingIdentity: { dev: bigint; ino: bigint } | undefined;
+	let stagingSnapshot: ManagedFileSnapshot | undefined;
+	let committed = false;
 	let failure: unknown;
 	try {
-		const fd = fs.openSync(
+		fd = fs.openSync(
 			staging,
 			fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY | fs.constants.O_NOFOLLOW,
 			0o600,
 		);
-		try {
-			let offset = 0;
-			while (offset < bytes.byteLength) offset += fs.writeSync(fd, bytes, offset, bytes.byteLength - offset);
-			fs.fsyncSync(fd);
-		} finally {
-			fs.closeSync(fd);
-		}
-		secure(staging, "file");
+		secureFileDescriptor(staging, fd, "apply");
+		let offset = 0;
+		while (offset < bytes.byteLength) offset += fs.writeSync(fd, bytes, offset, bytes.byteLength - offset);
+		fs.fsyncSync(fd);
+		secureFileDescriptor(staging, fd, "verify");
+		const staged = fs.fstatSync(fd, { bigint: true });
+		stagingIdentity = { dev: staged.dev, ino: staged.ino };
+		stagingSnapshot = {
+			bytes: Buffer.from(bytes),
+			identity: identity(staged, createHash("sha256").update(bytes).digest("hex")),
+		};
+
 		const published = renameNoReplacePath(staging, destination);
 		if (!published.ok) {
 			if (published.code === "quarantine_collision") throw new Error("destination_conflict");
 			throw new Error("durability_failed");
 		}
-		secure(destination, "file");
+		const named = fs.lstatSync(destination, { bigint: true });
+		if (!named.isFile() || named.isSymbolicLink() || named.dev !== staged.dev || named.ino !== staged.ino) {
+			throw new Error("destination_identity_changed");
+		}
+		secureFileDescriptor(destination, fd, "verify");
+		fs.closeSync(fd);
+		fd = undefined;
 		fsyncDirectory(parent);
+		committed = true;
 	} catch (error) {
 		failure = error;
+	} finally {
+		if (fd !== undefined) fs.closeSync(fd);
 	}
-	try {
-		fs.unlinkSync(staging);
-	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code !== "ENOENT") failure ??= error;
+	if (stagingIdentity) {
+		if (!committed && stagingSnapshot) {
+			try {
+				const installed = captureManagedFileNoFollow(destination);
+				if (
+					installed.identity.dev === stagingSnapshot.identity.dev &&
+					installed.identity.ino === stagingSnapshot.identity.ino &&
+					installed.identity.sha256 === stagingSnapshot.identity.sha256
+				) {
+					const removed = exactUnlink(destination, {
+						dev: installed.identity.dev,
+						ino: installed.identity.ino,
+						size: BigInt(installed.identity.size),
+						mtimeNs: installed.identity.mtimeNs,
+						sha256: installed.identity.sha256,
+						quarantineName: `.gjc-remove-${process.pid}-${randomUUID()}`,
+					});
+					if (!removed.ok) failure ??= new Error(removed.code ?? "managed_publish_reconcile_failed");
+				}
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code !== "ENOENT") failure ??= error;
+			}
+		}
+		try {
+			const named = fs.lstatSync(staging, { bigint: true });
+			if (named.dev !== stagingIdentity.dev || named.ino !== stagingIdentity.ino) {
+				throw new Error("staging_identity_changed");
+			}
+			fs.unlinkSync(staging);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") failure ??= error;
+		}
 	}
 	if (failure !== undefined) throw failure;
 }
 
+/** Replace one managed regular file while retaining the secured staging fd through publication. */
+export function replaceManagedFileSync(destination: string, bytes: Uint8Array, root: ManagedDirectoryRoot): void {
+	const parent = path.dirname(destination);
+	ensureManagedDirectory(parent, root);
+	const staging = path.join(parent, `.${path.basename(destination)}.${randomUUID()}.replacement`);
+	let fd: number | undefined;
+	let stagedIdentity: { dev: bigint; ino: bigint } | undefined;
+	try {
+		fd = fs.openSync(
+			staging,
+			fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY | fs.constants.O_NOFOLLOW,
+			0o600,
+		);
+		secureFileDescriptor(staging, fd, "apply");
+		let offset = 0;
+		while (offset < bytes.byteLength) offset += fs.writeSync(fd, bytes, offset, bytes.byteLength - offset);
+		fs.fsyncSync(fd);
+		secureFileDescriptor(staging, fd, "verify");
+		const staged = fs.fstatSync(fd, { bigint: true });
+		stagedIdentity = { dev: staged.dev, ino: staged.ino };
+		assertManagedDirectoryRoot(root);
+		fs.renameSync(staging, destination);
+		assertManagedDirectoryRoot(root);
+		const named = fs.lstatSync(destination, { bigint: true });
+		if (!named.isFile() || named.isSymbolicLink() || named.dev !== staged.dev || named.ino !== staged.ino) {
+			throw new Error("destination_identity_changed");
+		}
+		secureFileDescriptor(destination, fd, "verify");
+		fs.closeSync(fd);
+		fd = undefined;
+		fsyncDirectory(parent);
+	} finally {
+		if (fd !== undefined) fs.closeSync(fd);
+		if (stagedIdentity) {
+			try {
+				const named = fs.lstatSync(staging, { bigint: true });
+				if (named.dev === stagedIdentity.dev && named.ino === stagedIdentity.ino) fs.unlinkSync(staging);
+			} catch {
+				// Never delete an object whose staging identity is no longer proven.
+			}
+		}
+	}
+}
+
+export async function replaceManagedFile(
+	destination: string,
+	bytes: Uint8Array,
+	root: ManagedDirectoryRoot,
+): Promise<void> {
+	replaceManagedFileSync(destination, bytes, root);
+}
+
 /** Copy the exact bytes captured from one no-follow source descriptor. */
 export async function copyManagedFileNoReplace(
 	source: string,
 	destination: string,
 	snapshot = captureManagedFileNoFollow(source),
+	root?: ManagedDirectoryRoot,
 ): Promise<void> {
 	const named = captureManagedFileNoFollow(source);
 	if (!sameIdentity(snapshot.identity, named.identity) || !snapshot.bytes.equals(named.bytes))
 		throw new Error("source_changed");
-	await publishManagedFileNoReplace(destination, snapshot.bytes);
+	await publishManagedFileNoReplace(destination, snapshot.bytes, undefined, root);
 	const destinationSnapshot = captureManagedFileNoFollow(destination);
 	if (!destinationSnapshot.bytes.equals(snapshot.bytes)) throw new Error("durability_failed");
 }
 
 /** Acquire a lease lock with bounded wait, heartbeats, conservative stale reclaim, and fencing. */
-export async function acquireManagedLock(locksDirectory: string, name: string): Promise<ManagedStorageLock> {
-	ensureManagedDirectory(locksDirectory);
+export async function acquireManagedLock(
+	locksDirectory: string,
+	name: string,
+	root?: ManagedDirectoryRoot,
+): Promise<ManagedStorageLock> {
+	ensureManagedDirectory(locksDirectory, root);
 	const lockPath = path.join(locksDirectory, `${name}.lock`);
 	const deadline = Date.now() + LOCK_WAIT_MS;
 	let staleObservedAt: number | undefined;
@@ -289,9 +1386,9 @@ export async function acquireManagedLock(locksDirectory: string, name: string):
 				0o600,
 			);
 			try {
+				secureFileDescriptor(lockPath, fd, "apply");
 				fs.writeFileSync(fd, `${JSON.stringify(record)}\n`);
 				fs.fsyncSync(fd);
-				secure(lockPath, "file");
 				fsyncDirectory(locksDirectory);
 			} catch (error) {
 				fs.closeSync(fd);
@@ -301,7 +1398,10 @@ export async function acquireManagedLock(locksDirectory: string, name: string):
 			let released = false;
 			let descriptorClosed = false;
 			const closeDescriptor = (): void => {
-				if (!descriptorClosed) {
+				if (descriptorClosed) return;
+				try {
+					secureFileDescriptor(lockPath, fd, "verify");
+				} finally {
 					fs.closeSync(fd);
 					descriptorClosed = true;
 				}
@@ -406,7 +1506,9 @@ export function validateManagedArtifactTree(root: string): void {
 }
 
 /** Flush a copied managed artifact tree, including empty directories, before publishing its receipt. */
-export function fsyncManagedArtifactTree(root: string): void {
+export function fsyncManagedArtifactTree(root: string): NativeDirectoryTreeSnapshot {
+	const before = snapshotDirectoryTree(root);
+	if (!before.ok || !before.snapshot) throw new Error(before.code ?? "unsafe_artifacts");
 	const visit = (pathname: string): void => {
 		const stat = fs.lstatSync(pathname);
 		if (stat.isSymbolicLink()) throw new Error("unsafe_artifacts");
@@ -425,7 +1527,11 @@ export function fsyncManagedArtifactTree(root: string): void {
 	};
 	validateManagedArtifactTree(root);
 	visit(root);
-	validateManagedArtifactTree(root);
+	const after = snapshotDirectoryTree(root);
+	if (!after.ok || !after.snapshot || JSON.stringify(after.snapshot) !== JSON.stringify(before.snapshot)) {
+		throw new Error("artifact_tree_changed_during_fsync");
+	}
+	return after.snapshot;
 }
 
 export async function publishManagedTombstone(