wiki-viewer 1.6.0 → 1.7.0

package/.next/standalone/src/app/api/agent/fs/file/[...path]/route.ts

@@ -24,6 +24,7 @@ import {
 	isMarkdown,
 	atomicWrite,
 	ensureParentDir,
+	looksLikeBinary,
 } from "@/lib/proof/raw-fs";
 import { computeCollabState } from "@/lib/proof/collab-state";
 
@@ -125,16 +126,28 @@ export async function GET(
 	});
 }
 
-// ── PUT ──────────────────────────────────────────────────────────────────────
+// ── Shared mutation path (PUT + PATCH) ────────────────────────────────────────
 
-export async function PUT(
+/**
+ * Single code path for all Tier-1 byte mutations so PUT and PATCH cannot drift
+ * on auth/scope/If-Match/R6/atomicWrite/reconcile/audit.
+ *
+ * `computeNewBody` receives the existing file buffer (or null if absent) and
+ * returns the new bytes, or an error response to short-circuit (e.g. PATCH
+ * match-count mismatch). `op` is the audit verb ("put" | "patch").
+ */
+async function applyMutation(
 	req: Request,
-	{ params }: { params: Promise<{ path: string[] }> },
+	segments: string[],
+	opts: {
+		op: "put" | "patch";
+		allowCreate: boolean;
+		computeNewBody: (existing: Buffer | null) => Buffer | NextResponse;
+	},
 ): Promise<NextResponse> {
 	const auth = await checkAuth(req);
 	if (!auth.ok) return errJson("UNAUTHORIZED", auth.message ?? "Unauthorized", 401);
 
-	const { path: segments } = await params;
 	const relPath = rel(segments);
 	const url = new URL(req.url);
 	const mkdirs = url.searchParams.get("mkdirs") === "true";
@@ -150,56 +163,52 @@ export async function PUT(
 	if (!scope.ok) return errJson(scope.code, scope.message, 403);
 
 	const ifMatch = req.headers.get("if-match");
-	const bodyBuf = Buffer.from(await req.arrayBuffer());
-	const newSha = sha256ofBuf(bodyBuf);
-
-	// Check existing file
-	let existingSha: string | undefined;
-	let existed = false;
-	try {
-		const existing = await readFile(absPath);
-		existingSha = sha256ofBuf(existing);
-		existed = true;
-	} catch (e) {
-		if ((e as NodeJS.ErrnoException).code !== "ENOENT") throw e;
-	}
+	const ifCollabMatch = req.headers.get("if-collab-match");
+	const rootDir = getRootDir();
 
-	if (existed) {
-		// Overwrite: If-Match required by default (unless ?force=true)
-		if (!force && !ifMatch) {
-			return errJson(
-				"PRECONDITION_REQUIRED",
-				"If-Match header required for overwrites (use ?force=true to bypass with audit)",
-				412,
-			);
+	// The whole read-existing → precondition → compute → write → reconcile → audit
+	// sequence runs inside the mutex for .md (so R6 and reconcile are atomic with
+	// the write); non-.md runs it without the mutex.
+	const doMutation = async (): Promise<NextResponse> => {
+		// Read existing
+		let existingBuf: Buffer | null = null;
+		let existingSha: string | undefined;
+		try {
+			existingBuf = await readFile(absPath);
+			existingSha = sha256ofBuf(existingBuf);
+		} catch (e) {
+			if ((e as NodeJS.ErrnoException).code !== "ENOENT") throw e;
 		}
-		if (ifMatch) {
-			const provided = extractShaHex(ifMatch);
-			const current = extractShaHex(existingSha!);
-			if (provided !== current) {
+		const existed = existingBuf !== null;
+
+		if (existed) {
+			// Overwrite: If-Match required by default (unless ?force=true)
+			if (!force && !ifMatch) {
+				return errJson(
+					"PRECONDITION_REQUIRED",
+					"If-Match header required for overwrites (use ?force=true to bypass with audit)",
+					412,
+				);
+			}
+			if (ifMatch && extractShaHex(ifMatch) !== extractShaHex(existingSha!)) {
 				return errJson("PRECONDITION_FAILED", "If-Match sha256 mismatch", 412);
 			}
+		} else {
+			if (!opts.allowCreate) {
+				return errJson("NOT_FOUND", "File not found", 404);
+			}
+			const parentOk = await ensureParentDir(absPath, mkdirs);
+			if (!parentOk) {
+				return errJson(
+					"PARENT_NOT_FOUND",
+					"Parent directory does not exist (use ?mkdirs=true to create)",
+					400,
+				);
+			}
 		}
-	} else {
-		// Create: ensure parent dir exists
-		const parentOk = await ensureParentDir(absPath, mkdirs);
-		if (!parentOk) {
-			return errJson(
-				"PARENT_NOT_FOUND",
-				"Parent directory does not exist (use ?mkdirs=true to create)",
-				400,
-			);
-		}
-	}
 
-	const rootDir = getRootDir();
-	// R6: for .md, re-check collab state atomically inside write mutex
-	const ifCollabMatch = req.headers.get("if-collab-match");
-
-	if (isMarkdown(relPath)) {
-		// R1: acquire shared mutex; R2: reconcile eagerly inside it
-		return await withFileMutex(relPath, async () => {
-			// R6: atomic collab-state check (closes TOCTOU race)
+		// R6: for .md, re-check collab state atomically (inside mutex)
+		if (isMarkdown(relPath)) {
 			const { state, revision, snapshotUrl } = await computeCollabState(rootDir, relPath);
 			if (state === "active") {
 				const matchVal = ifCollabMatch?.trim();
@@ -216,9 +225,17 @@ export async function PUT(
 					);
 				}
 			}
+		}
+
+		// Compute new bytes (PUT: request body; PATCH: str-replace on existing)
+		const computed = opts.computeNewBody(existingBuf);
+		if (computed instanceof NextResponse) return computed;
+		const bodyBuf = computed;
+		const newSha = sha256ofBuf(bodyBuf);
 
-			await atomicWrite(absPath, bodyBuf);
+		await atomicWrite(absPath, bodyBuf);
 
+		if (isMarkdown(relPath)) {
 			const content = bodyBuf.toString("utf-8");
 			const sidecar = (await readSidecar(rootDir, relPath)) ?? emptySidecar(relPath);
 			await reconcileSidecar({
@@ -230,44 +247,119 @@ export async function PUT(
 				eventType: "file.rawWritten",
 				fingerprint: newSha,
 			});
+		}
 
-			writeAuditRow({
-				agentId: auth.agent.id,
-				op: "put",
-				path: relPath,
-				oldSha: existingSha,
-				newSha,
-				forced: force,
-			});
+		writeAuditRow({
+			agentId: auth.agent.id,
+			op: opts.op,
+			path: relPath,
+			oldSha: existingSha,
+			newSha,
+			forced: force,
+		});
 
-			const st = await stat(absPath);
-			return NextResponse.json({
-				path: relPath,
-				sha256: newSha,
-				size: st.size,
-				mtime: st.mtime.toISOString(),
-				created: !existed,
-			});
+		const st = await stat(absPath);
+		return NextResponse.json({
+			path: relPath,
+			sha256: newSha,
+			size: st.size,
+			mtime: st.mtime.toISOString(),
+			created: !existed,
 		});
-	}
+	};
 
-	// Non-.md: atomic write + audit (no mutex, no sidecar)
-	await atomicWrite(absPath, bodyBuf);
-	writeAuditRow({
-		agentId: auth.agent.id,
+	return isMarkdown(relPath) ? withFileMutex(relPath, doMutation) : doMutation();
+}
+
+// ── PUT ──────────────────────────────────────────────────────────────────────
+
+export async function PUT(
+	req: Request,
+	{ params }: { params: Promise<{ path: string[] }> },
+): Promise<NextResponse> {
+	const { path: segments } = await params;
+	const bodyBuf = Buffer.from(await req.arrayBuffer());
+	return applyMutation(req, segments, {
 		op: "put",
-		path: relPath,
-		oldSha: existingSha,
-		newSha,
-		forced: force,
+		allowCreate: true,
+		computeNewBody: () => bodyBuf,
 	});
-	const st = await stat(absPath);
-	return NextResponse.json({
-		path: relPath,
-		sha256: newSha,
-		size: st.size,
-		mtime: st.mtime.toISOString(),
-		created: !existed,
+}
+
+// ── PATCH ─────────────────────────────────────────────────────────────────────
+// Server-side str-replace so agents send only the change, not the whole file.
+// Strict: exact substring (no regex), text/UTF-8 only, If-Match required,
+// expectedOccurrences must match exactly (default 1). Shares applyMutation, so
+// lock / R6 / reconcile / audit behave identically to PUT.
+
+const MAX_PATCH_STRING = 1_000_000; // 1MB cap on find/replace strings
+
+export async function PATCH(
+	req: Request,
+	{ params }: { params: Promise<{ path: string[] }> },
+): Promise<NextResponse> {
+	const { path: segments } = await params;
+
+	let body: { find?: unknown; replace?: unknown; expectedOccurrences?: unknown };
+	try {
+		body = (await req.json()) as typeof body;
+	} catch {
+		return errJson("INVALID_PAYLOAD", "Body must be JSON {find, replace, expectedOccurrences?}", 400);
+	}
+	const find = body.find;
+	const replace = body.replace;
+	if (typeof find !== "string" || typeof replace !== "string") {
+		return errJson("INVALID_PAYLOAD", "find and replace must be strings", 400);
+	}
+	if (find.length === 0) {
+		return errJson("INVALID_PAYLOAD", "find must not be empty", 400);
+	}
+	if (find.length > MAX_PATCH_STRING || replace.length > MAX_PATCH_STRING) {
+		return errJson("PAYLOAD_TOO_LARGE", "find/replace exceeds 1MB limit", 413);
+	}
+	let expected = 1;
+	if (body.expectedOccurrences !== undefined) {
+		if (typeof body.expectedOccurrences !== "number" || !Number.isInteger(body.expectedOccurrences) || body.expectedOccurrences < 1) {
+			return errJson("INVALID_PAYLOAD", "expectedOccurrences must be a positive integer", 400);
+		}
+		expected = body.expectedOccurrences;
+	}
+
+	return applyMutation(req, segments, {
+		op: "patch",
+		allowCreate: false, // patch only edits existing files
+		computeNewBody: (existing) => {
+			if (existing === null) return errJson("NOT_FOUND", "File not found", 404);
+			if (looksLikeBinary(existing)) {
+				return errJson("UNSUPPORTED", "Cannot patch binary / non-text file", 415);
+			}
+			let text: string;
+			try {
+				text = new TextDecoder("utf-8", { fatal: true }).decode(existing);
+			} catch {
+				return errJson("UNSUPPORTED", "File is not valid UTF-8", 415);
+			}
+			// Count exact occurrences (no regex).
+			let count = 0;
+			let idx = text.indexOf(find);
+			while (idx !== -1) {
+				count++;
+				idx = text.indexOf(find, idx + find.length);
+			}
+			if (count !== expected) {
+				return NextResponse.json(
+					{
+						error: "MATCH_COUNT_MISMATCH",
+						message: `Expected ${expected} occurrence(s) of find, found ${count}. Re-read the file or adjust expectedOccurrences.`,
+						found: count,
+						expected,
+					},
+					{ status: 422 },
+				);
+			}
+			// Replace all (count == expected) occurrences, literally.
+			return Buffer.from(text.split(find).join(replace), "utf-8");
+		},
 	});
 }
 

package/.next/standalone/src/app/api/wiki/download/route.ts

@@ -0,0 +1,99 @@
+import { createReadStream } from "node:fs";
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { Readable } from "node:stream";
+import JSZip from "jszip";
+import { NextResponse } from "next/server";
+import { requireUser } from "@/lib/auth/server";
+import { safeRootPath } from "@/lib/root-dir";
+
+// Skip noise that should never end up in a downloaded archive.
+const SKIP_DIRS = new Set([".git", "node_modules", ".next", ".proof"]);
+
+function contentDisposition(filename: string): string {
+	// RFC 5987: ASCII fallback + UTF-8 encoded form for non-ASCII names.
+	const ascii = filename.replace(/[^\x20-\x7e]/g, "_").replace(/"/g, "'");
+	const encoded = encodeURIComponent(filename);
+	return `attachment; filename="${ascii}"; filename*=UTF-8''${encoded}`;
+}
+
+async function addDirToZip(
+	zip: JSZip,
+	absDir: string,
+	zipPrefix: string,
+): Promise<void> {
+	const names = await readdir(absDir);
+	for (const name of names) {
+		if (SKIP_DIRS.has(name)) continue;
+		const abs = path.join(absDir, name);
+		const info = await stat(abs);
+		const zipPath = zipPrefix ? `${zipPrefix}/${name}` : name;
+		if (info.isDirectory()) {
+			await addDirToZip(zip, abs, zipPath);
+		} else if (info.isFile()) {
+			zip.file(zipPath, await readFile(abs));
+		}
+	}
+}
+
+export async function GET(request: Request) {
+	const auth = await requireUser(request);
+	if (!auth.ok)
+		return NextResponse.json({ error: "UNAUTHORIZED" }, { status: 401 });
+
+	const { searchParams } = new URL(request.url);
+	const rel = searchParams.get("path") ?? "";
+	const target = safeRootPath(rel);
+	if (!target)
+		return NextResponse.json({ error: "Invalid path" }, { status: 400 });
+
+	let info: Awaited<ReturnType<typeof stat>>;
+	try {
+		info = await stat(target);
+	} catch {
+		return NextResponse.json({ error: "Not found" }, { status: 404 });
+	}
+
+	const baseName = path.basename(target) || "download";
+
+	if (info.isFile()) {
+		const webStream = Readable.toWeb(
+			createReadStream(target),
+		) as ReadableStream;
+		return new Response(webStream, {
+			headers: {
+				"Content-Type": "application/octet-stream",
+				"Content-Length": String(info.size),
+				"Content-Disposition": contentDisposition(baseName),
+				"Cache-Control": "private, no-store",
+			},
+		});
+	}
+
+	if (info.isDirectory()) {
+		const zip = new JSZip();
+		try {
+			await addDirToZip(zip, target, "");
+		} catch {
+			return NextResponse.json(
+				{ error: "Failed to read folder" },
+				{ status: 500 },
+			);
+		}
+		const buffer = await zip.generateAsync({
+			type: "nodebuffer",
+			compression: "DEFLATE",
+			compressionOptions: { level: 6 },
+		});
+		return new Response(new Uint8Array(buffer), {
+			headers: {
+				"Content-Type": "application/zip",
+				"Content-Length": String(buffer.length),
+				"Content-Disposition": contentDisposition(`${baseName}.zip`),
+				"Cache-Control": "private, no-store",
+			},
+		});
+	}
+
+	return NextResponse.json({ error: "Unsupported path" }, { status: 400 });
+}

package/.next/standalone/src/app/page.tsx

@@ -6,6 +6,7 @@ import {
 	Check,
 	ChevronDown,
 	ChevronRight,
+	Download,
 	File,
 	FilePlus,
 	FileText,
@@ -742,6 +743,16 @@ export default function Page() {
 		}
 	}
 
+	function handleDownload(node: TreeNode) {
+		const url = `/api/wiki/download?path=${encodeURIComponent(node.path)}`;
+		const a = document.createElement("a");
+		a.href = url;
+		a.download = node.type === "file" ? node.name : `${node.name}.zip`;
+		document.body.appendChild(a);
+		a.click();
+		a.remove();
+	}
+
 	async function handleDelete() {
 		if (!deletingPath) return;
 		await fetch("/api/wiki", {
@@ -956,6 +967,15 @@ export default function Page() {
 								</Button>
 							</>
 						)}
+						<Button
+							size="sm"
+							variant="ghost"
+							className="h-6 w-6 p-0 text-muted-foreground hover:text-foreground"
+							title={node.type === "file" ? "Download" : "Download as zip"}
+							onClick={() => handleDownload(node)}
+						>
+							<Download className="h-3 w-3" />
+						</Button>
 						<Button
 							size="sm"
 							variant="ghost"

package/.next/standalone/src/tests/proof/agent-fs.test.ts

@@ -23,6 +23,7 @@ import { _resetAuditDb } from "../../lib/proof/audit.js";
 // Route handlers (loaded after env is set)
 let fileGET: (req: Request, ctx: { params: Promise<{ path: string[] }> }) => Promise<Response>;
 let filePUT: (req: Request, ctx: { params: Promise<{ path: string[] }> }) => Promise<Response>;
+let filePATCH: (req: Request, ctx: { params: Promise<{ path: string[] }> }) => Promise<Response>;
 let fileDELETE: (req: Request, ctx: { params: Promise<{ path: string[] }> }) => Promise<Response>;
 let lsGET: (req: Request, ctx: { params: Promise<{ path?: string[] }> }) => Promise<Response>;
 let movePOST: (req: Request) => Promise<Response>;
@@ -103,6 +104,7 @@ before(async () => {
 	const fileRoute = await import("../../app/api/agent/fs/file/[...path]/route.js");
 	fileGET = fileRoute.GET;
 	filePUT = fileRoute.PUT;
+	filePATCH = fileRoute.PATCH;
 	fileDELETE = fileRoute.DELETE;
 
 	const lsRoute = await import("../../app/api/agent/fs/ls/[[...path]]/route.js");
@@ -822,3 +824,150 @@ test("traversal: .proof/ denied on PUT", async () => {
 	const res = await filePUT(req, makeCtx([".proof", "inject.json"]));
 	assert.equal(res.status, 400);
 });
+
+// ── PATCH (server-side str-replace) ──────────────────────────────────────────
+
+test("PATCH: str-replace on .md succeeds, sends only find/replace", async () => {
+	const orig = Buffer.from("# Title\n\nHello world. Keep this.\n");
+	await writeFile(path.join(tmpRoot, "patch1.md"), orig);
+	const req = new Request(fileUrl("patch1.md"), {
+		method: "PATCH",
+		headers: { ...agentHeaders(MUTATE_TOKEN, "ai:mutate-agent"), "Content-Type": "application/json", "If-Match": sha256(orig) },
+		body: JSON.stringify({ find: "Hello world", replace: "Goodbye moon" }),
+	});
+	const res = await filePATCH(req, makeCtx(["patch1.md"]));
+	assert.equal(res.status, 200, await res.text());
+	const out = await readFile(path.join(tmpRoot, "patch1.md"), "utf-8");
+	assert.equal(out, "# Title\n\nGoodbye moon. Keep this.\n");
+});
+
+test("PATCH: missing If-Match → 412", async () => {
+	const orig = Buffer.from("alpha beta gamma");
+	await writeFile(path.join(tmpRoot, "patch2.txt"), orig);
+	const req = new Request(fileUrl("patch2.txt"), {
+		method: "PATCH",
+		headers: { ...agentHeaders(MUTATE_TOKEN, "ai:mutate-agent"), "Content-Type": "application/json" },
+		body: JSON.stringify({ find: "beta", replace: "BETA" }),
+	});
+	const res = await filePATCH(req, makeCtx(["patch2.txt"]));
+	assert.equal(res.status, 412);
+});
+
+test("PATCH: If-Match mismatch → 412", async () => {
+	const orig = Buffer.from("alpha beta gamma");
+	await writeFile(path.join(tmpRoot, "patch3.txt"), orig);
+	const req = new Request(fileUrl("patch3.txt"), {
+		method: "PATCH",
+		headers: { ...agentHeaders(MUTATE_TOKEN, "ai:mutate-agent"), "Content-Type": "application/json", "If-Match": "sha256:deadbeef" },
+		body: JSON.stringify({ find: "beta", replace: "BETA" }),
+	});
+	const res = await filePATCH(req, makeCtx(["patch3.txt"]));
+	assert.equal(res.status, 412);
+});
+
+test("PATCH: zero matches → 422 MATCH_COUNT_MISMATCH", async () => {
+	const orig = Buffer.from("alpha beta gamma");
+	await writeFile(path.join(tmpRoot, "patch4.txt"), orig);
+	const req = new Request(fileUrl("patch4.txt"), {
+		method: "PATCH",
+		headers: { ...agentHeaders(MUTATE_TOKEN, "ai:mutate-agent"), "Content-Type": "application/json", "If-Match": sha256(orig) },
+		body: JSON.stringify({ find: "nonexistent", replace: "x" }),
+	});
+	const res = await filePATCH(req, makeCtx(["patch4.txt"]));
+	assert.equal(res.status, 422);
+	const j = await res.json();
+	assert.equal(j.error, "MATCH_COUNT_MISMATCH");
+	assert.equal(j.found, 0);
+});
+
+test("PATCH: multiple matches but expected 1 → 422", async () => {
+	const orig = Buffer.from("foo bar foo baz foo");
+	await writeFile(path.join(tmpRoot, "patch5.txt"), orig);
+	const req = new Request(fileUrl("patch5.txt"), {
+		method: "PATCH",
+		headers: { ...agentHeaders(MUTATE_TOKEN, "ai:mutate-agent"), "Content-Type": "application/json", "If-Match": sha256(orig) },
+		body: JSON.stringify({ find: "foo", replace: "X" }),
+	});
+	const res = await filePATCH(req, makeCtx(["patch5.txt"]));
+	assert.equal(res.status, 422);
+	const j = await res.json();
+	assert.equal(j.found, 3);
+});
+
+test("PATCH: expectedOccurrences matching multi replaces all", async () => {
+	const orig = Buffer.from("foo bar foo baz foo");
+	await writeFile(path.join(tmpRoot, "patch6.txt"), orig);
+	const req = new Request(fileUrl("patch6.txt"), {
+		method: "PATCH",
+		headers: { ...agentHeaders(MUTATE_TOKEN, "ai:mutate-agent"), "Content-Type": "application/json", "If-Match": sha256(orig) },
+		body: JSON.stringify({ find: "foo", replace: "X", expectedOccurrences: 3 }),
+	});
+	const res = await filePATCH(req, makeCtx(["patch6.txt"]));
+	assert.equal(res.status, 200, await res.text());
+	const out = await readFile(path.join(tmpRoot, "patch6.txt"), "utf-8");
+	assert.equal(out, "X bar X baz X");
+});
+
+test("PATCH: empty find → 400", async () => {
+	const orig = Buffer.from("abc");
+	await writeFile(path.join(tmpRoot, "patch7.txt"), orig);
+	const req = new Request(fileUrl("patch7.txt"), {
+		method: "PATCH",
+		headers: { ...agentHeaders(MUTATE_TOKEN, "ai:mutate-agent"), "Content-Type": "application/json", "If-Match": sha256(orig) },
+		body: JSON.stringify({ find: "", replace: "x" }),
+	});
+	const res = await filePATCH(req, makeCtx(["patch7.txt"]));
+	assert.equal(res.status, 400);
+});
+
+test("PATCH: binary file → 415", async () => {
+	const orig = Buffer.from([0x00, 0x01, 0x02, 0xff, 0xfe, 0x00, 0x10]);
+	await writeFile(path.join(tmpRoot, "patch8.bin"), orig);
+	const req = new Request(fileUrl("patch8.bin"), {
+		method: "PATCH",
+		headers: { ...agentHeaders(MUTATE_TOKEN, "ai:mutate-agent"), "Content-Type": "application/json", "If-Match": sha256(orig) },
+		body: JSON.stringify({ find: "x", replace: "y" }),
+	});
+	const res = await filePATCH(req, makeCtx(["patch8.bin"]));
+	assert.equal(res.status, 415);
+});
+
+test("PATCH: nonexistent file → 404 (no create)", async () => {
+	const req = new Request(fileUrl("patch-missing.txt"), {
+		method: "PATCH",
+		headers: { ...agentHeaders(MUTATE_TOKEN, "ai:mutate-agent"), "Content-Type": "application/json", "If-Match": "sha256:abc" },
+		body: JSON.stringify({ find: "a", replace: "b" }),
+	});
+	const res = await filePATCH(req, makeCtx(["patch-missing.txt"]));
+	assert.equal(res.status, 404);
+});
+
+test("PATCH: .md emits file.rawWritten + reconciles (same path as PUT)", async () => {
+	const orig = Buffer.from("# H\n\noriginal paragraph here\n");
+	await writeFile(path.join(tmpRoot, "patch-md.md"), orig);
+	const req = new Request(fileUrl("patch-md.md"), {
+		method: "PATCH",
+		headers: { ...agentHeaders(MUTATE_TOKEN, "ai:mutate-agent"), "Content-Type": "application/json", "If-Match": sha256(orig) },
+		body: JSON.stringify({ find: "original", replace: "updated" }),
+	});
+	const res = await filePATCH(req, makeCtx(["patch-md.md"]));
+	assert.equal(res.status, 200, await res.text());
+	const sidecar = await readSidecar(tmpRoot, "patch-md.md");
+	assert.ok(sidecar, "sidecar created");
+	const events = sidecar!.events.filter((e) => e.type === "file.rawWritten");
+	assert.ok(events.length > 0, "file.rawWritten event present");
+	const newContent = await readFile(path.join(tmpRoot, "patch-md.md"), "utf-8");
+	assert.equal(sidecar!.fingerprint, sha256(Buffer.from(newContent)), "fingerprint matches new content (eager reconcile)");
+});
+
+test("PATCH: requires mutate scope", async () => {
+	const orig = Buffer.from("hello");
+	await writeFile(path.join(tmpRoot, "patch-scope.txt"), orig);
+	const req = new Request(fileUrl("patch-scope.txt"), {
+		method: "PATCH",
+		headers: { ...agentHeaders(READ_TOKEN, "ai:read-agent"), "Content-Type": "application/json", "If-Match": sha256(orig) },
+		body: JSON.stringify({ find: "hello", replace: "hi" }),
+	});
+	const res = await filePATCH(req, makeCtx(["patch-scope.txt"]));
+	assert.equal(res.status, 403);
+});