@hydraharness/harness-fs-review 0.1.1-rc.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,33 @@
+# File review
+
+`@hydraharness/harness-fs-review` provides `ctx.fileReview`: chronological, session-owned Write/Edit/Create evidence, Keep, and hash-guarded Undo. [PI source map](PI-SOURCE-MAP.md) records the implementation studied and explicit differences.
+
+Its client types also describe read-only `WorkspaceReview` Git comparisons. The host resolves these comparisons from the session cwd; this package owns their shared mode, file, hunk and metadata types, while Keep and Undo remain exclusive to persisted `ReviewChange` records.
+
+The local filesystem emits `fs/mutate` inside its existing per-file lock, after the sandbox fence. The review plugin captures raw bytes before delegating and commits SHA-256 hashes, attribution, counts, and bounded hunks outside the workspace. Git operations cannot erase these records. Keep marks an applied change reviewed and retains Undo; it does not write the workspace or change tool permissions.
+
+Undo verifies the owner, workspace, canonical path, snapshot hash and current after hash. New files are removed. Sequential edits must be undone in reverse order when their post-edit states differ. Interrupted pending/undoing records remain unavailable and never trigger automatic restoration. Records use the tool execution's session, tool call, root call, turn/step sequence, preset and parent session metadata.
+
+## Configuration
+
+`directory` defaults to `$HYDRA_HOME/review-changes`. It must be absolute and outside the tracked workspace. `snapshotMaxBytes` defaults to 16 MiB inclusive; larger existing files have hashes but no reversible before copy. `diffMaxBytes` defaults to 512 KiB per side, `diffMaxLines` to 4,000, and `diffMaxCells` to 2,000,000. Preview limits do not discard snapshot bytes. Binary or invalid UTF-8 content has no text preview.
+
+## Storage and actions
+
+Each session directory is the SHA-256 of its session id, containing UUID change directories with a raw optional `before` file and versioned `meta.json`. `ReviewChange` owns the session/call/turn/step/preset lineage, relative path, hashes, status, state, and stored hunks. `ChangeId` identifies this directory. `ReviewOutcome` returns the record plus kept, rolledBack, alreadyRolledBack, conflict or unavailable. The [source map](PI-SOURCE-MAP.md) documents all PI comparisons.
+
+Startup removes review directories for sessions absent from persistence and the live session store. A failed mutation discards evidence only when the target still equals the before hash. Surviving sessions retain their records without age expiry; no session-deletion API is available for immediate deletion cleanup. No automatic recovery writes workspace files.
+
+## Model Experience
+
+None, as review evidence is user-facing storage keyed to existing session/tool identities.
+
+#### KV Cache effect
+
+None; review records are not model request inputs.
+
+## Known Limitations and Deferred Work
+
+- Shell commands, external editors, Delete/Move tools and non-local filesystem providers do not produce reversible review history. External edits are detected by Undo's current hash.
+- Cooperating local writes share a provider lock; an unrelated process can still race the final check and OS publication. The service retains uncertain operations for inspection instead of guessing after a crash. Snapshot preparation failure prevents an untracked mutation, a deliberate difference from PI's best-effort capture.
+- Metadata replacement is atomic, but the shared atomic-write helper does not fsync metadata or directory entries. Power-loss durability is not guaranteed. A stale action lock after process failure requires operator inspection; the service never steals it.

package/lib/client.js

@@ -0,0 +1,47 @@
+import { z } from "zod";
+//#region lib/types/client.js
+/** Browser-safe validation for durable/wire review records. @module */
+const hash = z.string().regex(/^[a-f0-9]{64}$/).nullable();
+/** Reject unknown record versions, unsafe paths, and malformed snapshot evidence. */
+const reviewChangeSchema = z.object({
+	version: z.literal(1),
+	id: z.uuid(),
+	sessionId: z.string().min(1),
+	callId: z.string().min(1),
+	rootCallId: z.string().min(1),
+	toolName: z.string().min(1),
+	seq: z.number().int().nonnegative(),
+	turnSeq: z.number().int().nonnegative().nullable(),
+	stepSeq: z.number().int().nonnegative().nullable(),
+	parentSessionId: z.string().nullable(),
+	agentPreset: z.string().nullable(),
+	createdAt: z.number().int().nonnegative(),
+	workspace: z.string().min(1),
+	path: z.string().min(1).refine((p) => !p.startsWith("/") && !p.includes("\\") && !p.includes(":") && !p.split("/").includes("..")),
+	operation: z.enum(["write", "edit"]),
+	status: z.enum([
+		"added",
+		"modified",
+		"deleted"
+	]),
+	state: z.enum([
+		"pending",
+		"active",
+		"kept",
+		"undoing",
+		"rolledBack"
+	]),
+	beforeHash: hash,
+	afterHash: hash,
+	reversible: z.boolean(),
+	binary: z.boolean(),
+	truncated: z.boolean(),
+	additions: z.number().int().nonnegative(),
+	deletions: z.number().int().nonnegative(),
+	hunks: z.array(z.object({
+		header: z.string(),
+		lines: z.array(z.string())
+	}))
+}).strict();
+//#endregion
+export { reviewChangeSchema };

package/lib/index.js

@@ -0,0 +1,361 @@
+import { reviewChangeSchema } from "./client.js";
+import { Service } from "@hydraharness/cordis";
+import z from "@hydraharness/schemastery";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, open, readFile, readdir, rm } from "node:fs/promises";
+import { isAbsolute, join, relative, sep } from "node:path";
+import { withFileLock, writeFileAtomic } from "@hydraharness/harness-atomic-write";
+import { resolveHydraHome } from "@hydraharness/harness-home-paths";
+import { FsError } from "@hydraharness/harness-fs";
+import { effectiveSandboxMode } from "@hydraharness/harness-sandbox-policy";
+import { structuredPatch } from "diff";
+//#region lib/types/diff.js
+/** Bounded, stored diff evidence with PI Desktop's preview limits. @module */
+/**
+* Compute persisted counts/hunks without re-reading the workspace on review.
+* @param before - bounded raw before bytes; null marks unavailable content.
+* @param after - bounded raw after bytes; null marks unavailable content.
+* @param limits - inclusive per-side limits and diff work bound.
+* @returns preview evidence or an explicit binary/truncated marker.
+*/
+function preview(before, after, limits) {
+	const empty = {
+		binary: false,
+		truncated: false,
+		additions: 0,
+		deletions: 0,
+		hunks: []
+	};
+	if (!before || !after || before.length > limits.diffMaxBytes || after.length > limits.diffMaxBytes) return {
+		...empty,
+		truncated: true
+	};
+	if (before.includes(0) || after.includes(0)) return {
+		...empty,
+		binary: true
+	};
+	let oldText;
+	let newText;
+	try {
+		const decoder = new TextDecoder("utf-8", {
+			fatal: true,
+			ignoreBOM: true
+		});
+		oldText = decoder.decode(before).replaceAll("\r\n", "\n");
+		newText = decoder.decode(after).replaceAll("\r\n", "\n");
+	} catch (_invalidUtf8) {
+		return {
+			...empty,
+			binary: true
+		};
+	}
+	const count = (text) => text === "" ? 0 : text.split("\n").length - Number(text.endsWith("\n"));
+	const oldLines = count(oldText);
+	const newLines = count(newText);
+	if (oldLines > limits.diffMaxLines || newLines > limits.diffMaxLines || (oldLines + 1) * (newLines + 1) > limits.diffMaxCells) return {
+		...empty,
+		truncated: true
+	};
+	const patch = structuredPatch("", "", oldText, newText, void 0, void 0, { context: 3 });
+	let additions = 0;
+	let deletions = 0;
+	const hunks = patch.hunks.map((hunk) => {
+		for (const line of hunk.lines) {
+			if (line.startsWith("+")) additions++;
+			if (line.startsWith("-")) deletions++;
+		}
+		return {
+			header: `@@ -${hunk.oldStart},${hunk.oldLines} +${hunk.newStart},${hunk.newLines} @@`,
+			lines: hunk.lines
+		};
+	});
+	return {
+		...empty,
+		additions,
+		deletions,
+		hunks
+	};
+}
+//#endregion
+//#region lib/types/index.js
+/** Agent-owned snapshots and hash-guarded review actions over the filesystem provider. @module */
+/** Durable review service; records are scoped by exact session and random change id. */
+var FileReview = class extends Service {
+	static inject = [
+		"fs",
+		"tools",
+		"sessions",
+		"sessionPersistence"
+	];
+	static Config = z.object({
+		directory: z.string().default(join(resolveHydraHome(), "review-changes")),
+		snapshotMaxBytes: z.number().step(1).min(1).default(16 * 1024 * 1024),
+		diffMaxBytes: z.number().step(1).min(1).default(512 * 1024),
+		diffMaxLines: z.number().step(1).min(1).default(4e3),
+		diffMaxCells: z.number().step(1).min(1).default(2e6)
+	});
+	executions = new AsyncLocalStorage();
+	/** Schema-resolved storage location and resource limits. */
+	config;
+	constructor(ctx, options) {
+		super(ctx, "fileReview");
+		const config = this.config = {
+			directory: options.directory ?? join(resolveHydraHome(), "review-changes"),
+			snapshotMaxBytes: options.snapshotMaxBytes ?? 16 * 1024 * 1024,
+			diffMaxBytes: options.diffMaxBytes ?? 512 * 1024,
+			diffMaxLines: options.diffMaxLines ?? 4e3,
+			diffMaxCells: options.diffMaxCells ?? 2e6
+		};
+		if (!isAbsolute(config.directory)) throw new Error("file-review directory must be absolute");
+		ctx.effect(async function* () {
+			await this.sweep();
+		}.bind(this));
+		ctx.on("tools/execute", (exec, next) => this.executions.run(exec, next));
+		ctx.on("fs/mutate", async (target, operation, next) => {
+			const exec = this.executions.getStore();
+			const session = exec?.agent?.session;
+			if (!exec || !session?.header.cwd || !["write", "edit"].includes(exec.name)) return next();
+			const root = await ctx.fs.resolve(session.header.cwd);
+			if (!ctx.fs.contains(root, target) || root.targetKey === target.targetKey) return next();
+			const storage = await ctx.fs.resolve(config.directory);
+			if (ctx.fs.contains(root, storage)) throw new Error("review snapshots must be stored outside the workspace");
+			const before = await ctx.fs.snapshot(target, config.snapshotMaxBytes);
+			const id = randomUUID();
+			const dir = this.changeDir(session.id, id);
+			await mkdir(dir, {
+				recursive: true,
+				mode: 448
+			});
+			if (before.bytes) {
+				const file = await open(join(dir, "before"), "wx", 384);
+				try {
+					await file.writeFile(before.bytes);
+					await file.sync();
+				} finally {
+					await file.close();
+				}
+			}
+			const change = {
+				version: 1,
+				id,
+				sessionId: session.id,
+				callId: exec.callId,
+				rootCallId: exec.rootCallId,
+				toolName: exec.name,
+				seq: session.seq,
+				turnSeq: session.events.findLast((e) => e.type === "turn/start")?.seq ?? null,
+				stepSeq: session.events.findLast((e) => e.type === "step/start")?.seq ?? null,
+				parentSessionId: session.header.origin === "subagent" ? session.header.parentSession ?? null : null,
+				agentPreset: session.header.agentPreset ?? null,
+				createdAt: Date.now(),
+				workspace: ctx.fs.processPath(root),
+				path: relative(ctx.fs.processPath(root), ctx.fs.processPath(target)).split(sep).join("/"),
+				operation,
+				status: before.hash === null ? "added" : "modified",
+				state: "pending",
+				beforeHash: before.hash,
+				afterHash: null,
+				reversible: false,
+				binary: false,
+				truncated: true,
+				additions: 0,
+				deletions: 0,
+				hunks: []
+			};
+			await this.save(change);
+			let result;
+			try {
+				result = await next();
+			} catch (error) {
+				if ((await ctx.fs.snapshot(target, 0)).hash === before.hash) await rm(dir, {
+					recursive: true,
+					force: true
+				});
+				throw error;
+			}
+			const after = await ctx.fs.snapshot(target, config.diffMaxBytes);
+			Object.assign(change, {
+				afterHash: after.hash,
+				state: "active",
+				status: after.hash === null ? "deleted" : change.status,
+				reversible: before.hash === null ? after.hash !== null : before.bytes !== null,
+				...preview(before.hash === null ? new Uint8Array() : before.bytes, after.hash === null ? new Uint8Array() : after.bytes, config)
+			});
+			await this.save(change);
+			return result;
+		});
+	}
+	sessionDir(id) {
+		return join(this.config.directory, createHash("sha256").update(id).digest("hex"));
+	}
+	changeDir(sessionId, id) {
+		if (!/^[a-f0-9-]{36}$/.test(id)) throw new Error("invalid review change id");
+		return join(this.sessionDir(sessionId), id);
+	}
+	async save(change) {
+		const meta = join(this.changeDir(change.sessionId, change.id), "meta.json");
+		await withFileLock(meta, () => this.saveUnlocked(change, meta));
+		this.ctx.emit("file-review/changed", change.sessionId);
+	}
+	async saveUnlocked(change, meta) {
+		await writeFileAtomic(meta, JSON.stringify(reviewChangeSchema.parse(change)), {
+			mode: 384,
+			dirMode: 448
+		});
+	}
+	async read(sessionId, id) {
+		const meta = join(this.changeDir(sessionId, id), "meta.json");
+		return withFileLock(meta, () => this.readUnlocked(sessionId, id, meta));
+	}
+	async readUnlocked(sessionId, id, meta) {
+		const change = reviewChangeSchema.parse(JSON.parse(await readFile(meta, "utf8")));
+		if (change.sessionId !== sessionId || change.id !== id) throw new Error("review change does not belong to this session");
+		return change;
+	}
+	/**
+	* Read chronological snapshot history without consulting Git or current file contents.
+	* @param sessionId - exact owner; forks do not inherit mutation authority.
+	* @returns every committed record, including unavailable interrupted operations.
+	*/
+	async list(sessionId) {
+		let entries;
+		try {
+			entries = await readdir(this.sessionDir(sessionId), { withFileTypes: true });
+		} catch (error) {
+			if (error.code === "ENOENT") return [];
+			throw error;
+		}
+		return (await Promise.all(entries.filter((e) => e.isDirectory()).map(async (e) => {
+			try {
+				return await this.read(sessionId, e.name);
+			} catch (error) {
+				if (error.code === "ENOENT") return void 0;
+				throw error;
+			}
+		}))).filter((record) => record !== void 0).sort((a, b) => a.seq - b.seq || a.createdAt - b.createdAt || a.id.localeCompare(b.id));
+	}
+	/**
+	* Mark a change kept, retaining its evidence and ability to undo.
+	* @param sessionId - owning session id.
+	* @param id - exact change id.
+	* @returns the committed review state.
+	*/
+	async keep(sessionId, id) {
+		return this.act(sessionId, id, false);
+	}
+	/**
+	* Undo only the recorded post-edit state; verifies snapshot integrity before writing.
+	* @param sessionId - owning session id.
+	* @param id - exact change id.
+	* @returns success, conflict, or unavailable; unavailable/uncertain records never write.
+	*/
+	async undo(sessionId, id) {
+		return this.act(sessionId, id, true);
+	}
+	async act(sessionId, id, undo) {
+		const meta = join(this.changeDir(sessionId, id), "meta.json");
+		return withFileLock(meta, async () => {
+			const change = await this.readUnlocked(sessionId, id, meta);
+			if (change.state === "rolledBack") return {
+				status: "alreadyRolledBack",
+				change
+			};
+			if (change.state === "pending" || change.state === "undoing") return {
+				status: "unavailable",
+				change
+			};
+			const { meta: header, events } = await this.ctx.sessionPersistence.inspect(sessionId);
+			const root = header.cwd === void 0 ? void 0 : await this.ctx.fs.resolve(header.cwd);
+			if (!root || this.ctx.fs.processPath(root) !== change.workspace) throw new Error("review workspace does not match its session");
+			if (!undo) {
+				change.state = "kept";
+				await this.saveUnlocked(change, meta);
+				this.ctx.emit("file-review/changed", change.sessionId);
+				return {
+					status: "kept",
+					change
+				};
+			}
+			if (!change.reversible) return {
+				status: "unavailable",
+				change
+			};
+			const target = await this.ctx.fs.resolve(change.path, { cwd: change.workspace });
+			if (!this.ctx.fs.contains(root, target) || root.targetKey === target.targetKey || relative(change.workspace, this.ctx.fs.processPath(target)).split(sep).join("/") !== change.path) throw new Error("review path changed or escaped its workspace");
+			let bytes = null;
+			if (change.beforeHash !== null) {
+				const snapshot = await open(join(this.changeDir(sessionId, id), "before"), "r");
+				try {
+					const info = await snapshot.stat();
+					if (!info.isFile() || info.size > this.config.snapshotMaxBytes) throw new Error("review snapshot exceeds size limit or is not a regular file");
+					const size = info.size;
+					const buffer = Buffer.alloc(size + 1);
+					let length = 0;
+					while (length < buffer.length) {
+						const { bytesRead } = await snapshot.read(buffer, length, buffer.length - length, null);
+						if (bytesRead === 0) break;
+						length += bytesRead;
+					}
+					if (length !== size) throw new Error("review snapshot changed while reading");
+					bytes = buffer.subarray(0, size);
+				} finally {
+					await snapshot.close();
+				}
+				if (createHash("sha256").update(bytes).digest("hex") !== change.beforeHash) throw new Error("review snapshot is corrupt");
+			}
+			const priorState = change.state;
+			change.state = "undoing";
+			await this.saveUnlocked(change, meta);
+			this.ctx.emit("file-review/changed", change.sessionId);
+			const policyService = this.ctx.get("sandboxPolicy");
+			const policy = policyService === void 0 ? void 0 : {
+				mode: effectiveSandboxMode(events) ?? policyService.defaultMode,
+				workspaceRoot: change.workspace
+			};
+			let restored;
+			try {
+				restored = await this.ctx.fs.restoreSnapshot(target, bytes, change.afterHash, policy);
+			} catch (error) {
+				if (error instanceof FsError && error.code === "FS_SANDBOX_DENIED") {
+					change.state = priorState;
+					await this.saveUnlocked(change, meta);
+					this.ctx.emit("file-review/changed", change.sessionId);
+				}
+				throw error;
+			}
+			change.state = restored ? "rolledBack" : priorState;
+			await this.saveUnlocked(change, meta);
+			this.ctx.emit("file-review/changed", change.sessionId);
+			return {
+				status: restored ? "rolledBack" : "conflict",
+				change
+			};
+		});
+	}
+	/**
+	* Remove orphan session directories; surviving sessions retain all review evidence.
+	* @returns completion after stale directories are removed; never restores workspace files.
+	*/
+	async sweep() {
+		let entries;
+		try {
+			entries = await readdir(this.config.directory, { withFileTypes: true });
+		} catch (error) {
+			if (error.code === "ENOENT") return;
+			throw error;
+		}
+		const live = new Set((await this.ctx.sessionPersistence.list()).map((h) => this.sessionDir(h.id)));
+		for (const session of this.ctx.sessions.list()) live.add(this.sessionDir(session.id));
+		for (const entry of entries) {
+			if (!entry.isDirectory() || !/^[a-f0-9]{64}$/.test(entry.name)) continue;
+			const path = join(this.config.directory, entry.name);
+			if (!live.has(path)) await rm(path, {
+				recursive: true,
+				force: true
+			});
+		}
+	}
+};
+//#endregion
+export { FileReview, FileReview as default };

package/lib/invariant.js

@@ -0,0 +1,14 @@
+//#region lib/types/invariant.js
+/** Companion plugin identity. */
+const name = "fs-review-invariant";
+/** Registration owner. */
+const inject = ["invariants"];
+const install = () => {};
+/**
+* Register the package's invariant ownership.
+* @param ctx - companion context.
+* @returns registration disposer.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register("@hydraharness/harness-fs-review", install));
+//#endregion
+export { apply, inject, name };

package/lib/types/client.d.ts

@@ -0,0 +1,18 @@
+/** Browser-safe validation for durable/wire review records. @module */
+import { z } from 'zod';
+import type { ReviewChange } from './types.ts';
+import type { SessionId } from '@hydraharness/harness-session/types';
+export type { ChangeId, ReviewChange, ReviewHunk, ReviewMode, ReviewOutcome, WorkspaceReview, WorkspaceReviewFile } from './types.ts';
+declare module '@hydraharness/cordis' {
+    interface Events {
+        /**
+         * A durable record was created or changed; clients refetch its history.
+         * @param sessionId - session owning the committed record.
+         * @mode emit
+         */
+        'file-review/changed'(sessionId: SessionId): void;
+    }
+}
+/** Reject unknown record versions, unsafe paths, and malformed snapshot evidence. */
+export declare const reviewChangeSchema: z.ZodType<ReviewChange>;
+//# sourceMappingURL=client.d.ts.map

package/lib/types/diff.d.ts

@@ -0,0 +1,21 @@
+import type { ReviewChange } from './types.ts';
+/** Deployment limits for snapshot storage and preview work. */
+export interface ReviewLimits {
+    /** Inclusive before-snapshot byte cap; larger files retain hashes only. */
+    snapshotMaxBytes: number;
+    /** Inclusive text-preview byte cap for each side. */
+    diffMaxBytes: number;
+    /** Inclusive text-preview line cap for each side. */
+    diffMaxLines: number;
+    /** Maximum product of the two line counts plus their empty-prefix rows. */
+    diffMaxCells: number;
+}
+/**
+ * Compute persisted counts/hunks without re-reading the workspace on review.
+ * @param before - bounded raw before bytes; null marks unavailable content.
+ * @param after - bounded raw after bytes; null marks unavailable content.
+ * @param limits - inclusive per-side limits and diff work bound.
+ * @returns preview evidence or an explicit binary/truncated marker.
+ */
+export declare function preview(before: Uint8Array | null, after: Uint8Array | null, limits: ReviewLimits): Pick<ReviewChange, 'binary' | 'truncated' | 'additions' | 'deletions' | 'hunks'>;
+//# sourceMappingURL=diff.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,60 @@
+/** Agent-owned snapshots and hash-guarded review actions over the filesystem provider. @module */
+import { Context, Service } from '@hydraharness/cordis';
+import z from '@hydraharness/schemastery';
+import type { SessionId } from '@hydraharness/harness-session';
+import { type ReviewLimits } from './diff.ts';
+import type { ChangeId, ReviewChange, ReviewOutcome } from './types.ts';
+export type { ChangeId, ReviewChange, ReviewOutcome } from './types.ts';
+declare module '@hydraharness/cordis' {
+    interface Context {
+        fileReview: FileReview;
+    }
+}
+/** Snapshot location and inclusive resource limits. */
+export interface Config extends Partial<ReviewLimits> {
+    /** Defaults to the review-changes directory in the Hydra home, outside workspaces. */
+    directory?: string;
+}
+/** Durable review service; records are scoped by exact session and random change id. */
+export declare class FileReview extends Service {
+    static inject: string[];
+    static Config: z<Config>;
+    private readonly executions;
+    /** Schema-resolved storage location and resource limits. */
+    readonly config: Required<Config>;
+    constructor(ctx: Context, options: Config);
+    private sessionDir;
+    private changeDir;
+    private save;
+    private saveUnlocked;
+    private read;
+    private readUnlocked;
+    /**
+     * Read chronological snapshot history without consulting Git or current file contents.
+     * @param sessionId - exact owner; forks do not inherit mutation authority.
+     * @returns every committed record, including unavailable interrupted operations.
+     */
+    list(sessionId: SessionId): Promise<ReviewChange[]>;
+    /**
+     * Mark a change kept, retaining its evidence and ability to undo.
+     * @param sessionId - owning session id.
+     * @param id - exact change id.
+     * @returns the committed review state.
+     */
+    keep(sessionId: SessionId, id: ChangeId): Promise<ReviewOutcome>;
+    /**
+     * Undo only the recorded post-edit state; verifies snapshot integrity before writing.
+     * @param sessionId - owning session id.
+     * @param id - exact change id.
+     * @returns success, conflict, or unavailable; unavailable/uncertain records never write.
+     */
+    undo(sessionId: SessionId, id: ChangeId): Promise<ReviewOutcome>;
+    private act;
+    /**
+     * Remove orphan session directories; surviving sessions retain all review evidence.
+     * @returns completion after stale directories are removed; never restores workspace files.
+     */
+    sweep(): Promise<void>;
+}
+export default FileReview;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,13 @@
+/** Review storage validates ownership and hashes at its durable parser. @module */
+import type { Context } from '@hydraharness/cordis';
+/** Companion plugin identity. */
+export declare const name = "fs-review-invariant";
+/** Registration owner. */
+export declare const inject: string[];
+/**
+ * Register the package's invariant ownership.
+ * @param ctx - companion context.
+ * @returns registration disposer.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,76 @@
+/** Durable agent-owned change evidence, independent of current Git state. @module */
+import type { Branded } from '@hydraharness/harness-brand';
+import type { SessionId } from '@hydraharness/harness-session/types';
+import type { CallId } from '@hydraharness/harness-llm/brand';
+/** Identifies one snapshot and its review record. */
+export type ChangeId = Branded<'ChangeId'>;
+/** One stored unified-diff hunk. */
+export interface ReviewHunk {
+    header: string;
+    lines: string[];
+}
+/** Live Git comparison modes shown beside persisted session evidence. */
+export type ReviewMode = 'uncommitted' | 'unstaged' | 'staged' | 'committed' | 'branch';
+/** One read-only current-workspace file comparison. */
+export interface WorkspaceReviewFile {
+    path: string;
+    status: 'added' | 'modified' | 'deleted';
+    additions: number;
+    deletions: number;
+    hunks: ReviewHunk[];
+    binary: boolean;
+    truncated: boolean;
+    patch: string | null;
+}
+/** Git metadata and changes restricted to a session's recorded workspace. */
+export interface WorkspaceReview {
+    workspace: string;
+    repository: string | null;
+    branch: string | null;
+    branches: string[];
+    commits: {
+        oid: string;
+        subject: string;
+    }[];
+    mode: ReviewMode;
+    baseRef: string | null;
+    files: WorkspaceReviewFile[];
+    truncated: boolean;
+}
+/** Snapshot metadata and review evidence committed together. */
+export interface ReviewChange {
+    version: 1;
+    id: ChangeId;
+    sessionId: SessionId;
+    callId: CallId;
+    rootCallId: CallId;
+    toolName: string;
+    /** Session sequence immediately before the mutation; turn/step use their opening seq. */
+    seq: number;
+    turnSeq: number | null;
+    stepSeq: number | null;
+    parentSessionId: SessionId | null;
+    agentPreset: string | null;
+    createdAt: number;
+    /** Canonical workspace root and relative file path, validated again before Undo. */
+    workspace: string;
+    path: string;
+    operation: 'write' | 'edit';
+    status: 'added' | 'modified' | 'deleted';
+    /** Pending/undoing records are uncertain after interruption and cannot mutate files. */
+    state: 'pending' | 'active' | 'kept' | 'undoing' | 'rolledBack';
+    beforeHash: string | null;
+    afterHash: string | null;
+    reversible: boolean;
+    binary: boolean;
+    truncated: boolean;
+    additions: number;
+    deletions: number;
+    hunks: ReviewHunk[];
+}
+/** User review action outcome. Conflicts never modify workspace files. */
+export interface ReviewOutcome {
+    status: 'kept' | 'rolledBack' | 'alreadyRolledBack' | 'conflict' | 'unavailable';
+    change: ReviewChange;
+}
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@hydraharness/harness-fs-review",
+  "description": "Durable agent-owned file change review and hash-guarded rollback",
+  "hydra": {
+    "plugin": {
+      "application": "Record agent-made file changes and support undo when the file still matches the recorded change."
+    }
+  },
+  "version": "0.1.1-rc.5",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-Harness.git",
+    "directory": "packages/fs/fs-review"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "diff": "^9.0.0",
+    "zod": "^4.4.3",
+    "@hydraharness/schemastery": "^3.18.2"
+  },
+  "peerDependencies": {
+    "@hydraharness/harness-atomic-write": "^0.1.1-rc.5",
+    "@hydraharness/harness-fs": "^0.1.1-rc.5",
+    "@hydraharness/harness-home-paths": "^0.1.1-rc.5",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.5",
+    "@hydraharness/harness-llm": "^0.1.1-rc.5",
+    "@hydraharness/harness-sandbox-policy": "^0.1.1-rc.5",
+    "@hydraharness/harness-session-persistence": "^0.1.1-rc.5",
+    "@hydraharness/harness-session": "^0.1.1-rc.5",
+    "@hydraharness/harness-tools": "^0.1.1-rc.5",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-brand": "^0.1.1-rc.5"
+  },
+  "devDependencies": {
+    "@hydraharness/harness-atomic-write": "^0.1.1-rc.5",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-brand": "^0.1.1-rc.5",
+    "@hydraharness/harness-fs": "^0.1.1-rc.5",
+    "@hydraharness/harness-fs-local": "^0.1.1-rc.5",
+    "@hydraharness/harness-home-paths": "^0.1.1-rc.5",
+    "@hydraharness/harness-llm": "^0.1.1-rc.5",
+    "@hydraharness/harness-session": "^0.1.1-rc.5",
+    "@hydraharness/harness-sandbox-policy": "^0.1.1-rc.5",
+    "@hydraharness/harness-session-persistence": "^0.1.1-rc.5",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.5",
+    "@hydraharness/harness-session-persistence-jsonl": "^0.1.1-rc.5",
+    "@hydraharness/harness-system-prompt": "^0.1.1-rc.5",
+    "@hydraharness/harness-tool-fs": "^0.1.1-rc.5",
+    "@hydraharness/harness-tools": "^0.1.1-rc.5"
+  }
+}