wiki-viewer 1.4.3 → 1.5.0

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

@@ -0,0 +1,147 @@
+/**
+ * Tier-1 Raw FS — directory listing.
+ *
+ * GET /api/agent/fs/ls[/<path>]?recursive&limit=N&depth=N
+ *
+ * Returns {path, entries, truncated}.
+ * Each entry: {name, path, type, size?, mtime?}.
+ * Excludes .proof/ and .git/. Scope-filters every returned path.
+ */
+export const runtime = "nodejs";
+
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { NextResponse } from "next/server";
+import { checkAuth, enforceScope } from "@/lib/proof/auth";
+import { getRootDir, safeRootPath } from "@/lib/root-dir";
+import { safeAbsPath } from "@/lib/proof/raw-fs";
+import type { Agent } from "@/lib/proof/registry";
+
+const HARD_MAX_ENTRIES = 10_000;
+const HARD_MAX_DEPTH = 20;
+
+export interface LsEntry {
+	name: string;
+	path: string;
+	type: "file" | "dir" | "symlink";
+	size?: number;
+	mtime?: string;
+}
+
+function errJson(code: string, message: string, status: number): NextResponse {
+	return NextResponse.json({ error: code, message }, { status });
+}
+
+/** Skip these names at any depth */
+const SKIP_NAMES = new Set([".proof", ".git"]);
+
+async function walkDir(
+	rootDir: string,
+	relDir: string,
+	agent: Agent,
+	recursive: boolean,
+	depth: number,
+	maxDepth: number,
+	limit: number,
+	results: LsEntry[],
+): Promise<void> {
+	if (depth > maxDepth || results.length >= limit) return;
+
+	const absDir = path.join(rootDir, relDir);
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	let items: any[];
+	try {
+		items = await readdir(absDir, { withFileTypes: true }) as any[];
+	} catch {
+		return;
+	}
+
+	for (const item of items) {
+		if (results.length >= limit) break;
+		if (SKIP_NAMES.has(item.name)) continue;
+
+		const childRel = relDir ? `${relDir}/${item.name}` : item.name;
+
+		// Scope check per entry
+		const sc = enforceScope(agent, { filePath: childRel, op: "read" });
+		if (!sc.ok) continue;
+
+		let type: LsEntry["type"];
+		let size: number | undefined;
+		let mtime: string | undefined;
+
+		if (item.isSymbolicLink()) {
+			type = "symlink";
+		} else if (item.isDirectory()) {
+			type = "dir";
+		} else {
+			type = "file";
+			try {
+				const st = await stat(path.join(rootDir, childRel));
+				size = st.size;
+				mtime = st.mtime.toISOString();
+			} catch {
+				// best-effort
+			}
+		}
+
+		results.push({ name: item.name, path: childRel, type, size, mtime });
+
+		if (recursive && type === "dir") {
+			await walkDir(rootDir, childRel, agent, recursive, depth + 1, maxDepth, limit, results);
+		}
+	}
+}
+
+export async function GET(
+	req: Request,
+	{ params }: { params: Promise<{ path?: string[] }> },
+): Promise<NextResponse> {
+	const auth = await checkAuth(req);
+	if (!auth.ok) return errJson("UNAUTHORIZED", auth.message ?? "Unauthorized", 401);
+
+	const { path: segments } = await params;
+	const relPath = segments ? segments.join("/") : "";
+
+	if (relPath) {
+		const basic = safeRootPath(relPath);
+		if (!basic) return errJson("INVALID_PATH", "Path traversal rejected", 400);
+		const safe = await safeAbsPath(relPath);
+		if (!safe) return errJson("INVALID_PATH", "Path rejected (symlink escape or denied)", 400);
+	}
+
+	const url = new URL(req.url);
+	const recursive = url.searchParams.has("recursive");
+	const limit = Math.min(
+		parseInt(url.searchParams.get("limit") ?? "1000", 10) || 1000,
+		HARD_MAX_ENTRIES,
+	);
+	const depth = Math.min(
+		parseInt(url.searchParams.get("depth") ?? "10", 10) || 10,
+		HARD_MAX_DEPTH,
+	);
+
+	// Verify the dir actually exists
+	const rootDir = getRootDir();
+	const absDir = relPath ? path.join(rootDir, relPath) : rootDir;
+	try {
+		const st = await stat(absDir);
+		if (!st.isDirectory()) {
+			return errJson("NOT_A_DIRECTORY", "Path is not a directory", 400);
+		}
+	} catch (e) {
+		if ((e as NodeJS.ErrnoException).code === "ENOENT") {
+			return errJson("NOT_FOUND", "Directory not found", 404);
+		}
+		throw e;
+	}
+
+	const entries: LsEntry[] = [];
+	await walkDir(rootDir, relPath, auth.agent, recursive, 0, depth, limit, entries);
+
+	return NextResponse.json({
+		path: relPath,
+		entries,
+		truncated: entries.length >= limit,
+	});
+}

package/.next/standalone/src/app/api/agent/fs/move/route.ts

@@ -0,0 +1,125 @@
+/**
+ * Tier-1 Raw FS — atomic move/rename.
+ *
+ * POST /api/agent/fs/move
+ * Body: { from: string, to: string, ifMatch?: string }
+ *
+ * Moves sidecar for .md files (R3).
+ * Locks source + dest in sorted order to avoid deadlock.
+ * Requires source read+mutate, dest mutate.
+ */
+export const runtime = "nodejs";
+
+import { rename, stat } from "node:fs/promises";
+import path from "node:path";
+import { NextResponse } from "next/server";
+import { checkAuth, enforceScope } from "@/lib/proof/auth";
+import { getRootDir, safeRootPath } from "@/lib/root-dir";
+import { withFileMutex } from "@/lib/proof/mutex";
+import { moveSidecar } from "@/lib/proof/sidecar";
+import { writeAuditRow } from "@/lib/proof/audit";
+import { safeAbsPath, sha256ofBuf, extractShaHex, isMarkdown } from "@/lib/proof/raw-fs";
+import { readFile } from "node:fs/promises";
+
+function errJson(code: string, message: string, status: number): NextResponse {
+	return NextResponse.json({ error: code, message }, { status });
+}
+
+export async function POST(req: Request): Promise<NextResponse> {
+	const auth = await checkAuth(req);
+	if (!auth.ok) return errJson("UNAUTHORIZED", auth.message ?? "Unauthorized", 401);
+
+	let body: { from?: unknown; to?: unknown; ifMatch?: unknown };
+	try {
+		body = (await req.json()) as typeof body;
+	} catch {
+		return errJson("INVALID_PAYLOAD", "Invalid JSON body", 400);
+	}
+
+	if (typeof body.from !== "string" || !body.from) {
+		return errJson("INVALID_PAYLOAD", "from (string) required", 400);
+	}
+	if (typeof body.to !== "string" || !body.to) {
+		return errJson("INVALID_PAYLOAD", "to (string) required", 400);
+	}
+
+	const fromRel = body.from;
+	const toRel = body.to;
+	const ifMatch = typeof body.ifMatch === "string" ? body.ifMatch : undefined;
+
+	// Basic traversal
+	if (!safeRootPath(fromRel)) return errJson("INVALID_PATH", "from: path traversal rejected", 400);
+	if (!safeRootPath(toRel)) return errJson("INVALID_PATH", "to: path traversal rejected", 400);
+
+	const fromAbs = await safeAbsPath(fromRel);
+	if (!fromAbs) return errJson("INVALID_PATH", "from: path rejected (symlink escape or denied)", 400);
+	const toAbs = await safeAbsPath(toRel);
+	if (!toAbs) return errJson("INVALID_PATH", "to: path rejected (symlink escape or denied)", 400);
+
+	// Self-move guard
+	if (fromAbs === toAbs) return errJson("INVALID_PATH", "from and to are the same path", 400);
+	if (toAbs.startsWith(fromAbs + path.sep)) {
+		return errJson("INVALID_PATH", "Cannot move a directory into itself", 400);
+	}
+
+	// Scope: source requires read+mutate; dest requires mutate
+	const sc1 = enforceScope(auth.agent, { filePath: fromRel, op: "read" });
+	if (!sc1.ok) return errJson(sc1.code, sc1.message, 403);
+	const sc2 = enforceScope(auth.agent, { filePath: fromRel, op: "mutate" });
+	if (!sc2.ok) return errJson(sc2.code, sc2.message, 403);
+	const sc3 = enforceScope(auth.agent, { filePath: toRel, op: "mutate" });
+	if (!sc3.ok) return errJson(sc3.code, sc3.message, 403);
+
+	// Verify source exists
+	try {
+		await stat(fromAbs);
+	} catch (e) {
+		if ((e as NodeJS.ErrnoException).code === "ENOENT") {
+			return errJson("NOT_FOUND", "Source file not found", 404);
+		}
+		throw e;
+	}
+
+	// If-Match guard (R4)
+	let existingSha: string | undefined;
+	if (ifMatch) {
+		let buf: Buffer;
+		try {
+			buf = await readFile(fromAbs);
+		} catch {
+			return errJson("NOT_FOUND", "Source file not found", 404);
+		}
+		existingSha = sha256ofBuf(buf);
+		if (extractShaHex(ifMatch) !== extractShaHex(existingSha)) {
+			return errJson("PRECONDITION_FAILED", "If-Match sha256 mismatch", 412);
+		}
+	}
+
+	const rootDir = getRootDir();
+	const isMd = isMarkdown(fromRel);
+
+	// Lock source + dest in sorted order to avoid deadlock
+	const [first, second] = [fromRel, toRel].sort();
+
+	const doMove = async () => {
+		await rename(fromAbs, toAbs);
+		if (isMd) {
+			await moveSidecar(rootDir, fromRel, toRel);
+		}
+		writeAuditRow({
+			agentId: auth.agent.id,
+			op: "move",
+			path: fromRel,
+			newSha: toRel, // store destination in newSha field for audit trail
+			forced: false,
+		});
+	};
+
+	if (first === fromRel) {
+		await withFileMutex(first, () => withFileMutex(second, doMove));
+	} else {
+		await withFileMutex(first, () => withFileMutex(second, doMove));
+	}
+
+	return NextResponse.json({ from: fromRel, to: toRel });
+}

package/.next/standalone/src/app/api/agent/fs/search/route.ts

@@ -0,0 +1,236 @@
+/**
+ * Tier-1 Raw FS — server-side search.
+ *
+ * POST /api/agent/fs/search
+ * Body: {
+ *   kind: "grep" | "glob",
+ *   query: string,          // grep: regex string; glob: glob pattern
+ *   path?: string,          // root-relative start path (default: root)
+ *   limit?: number,         // max matches (default 200, hard cap 2000)
+ * }
+ *
+ * Returns { kind, query, matches: [{path, line?, col?, text?}], truncated }.
+ *
+ * - Pure JS (no shell interpolation, no rg dependency)
+ * - Skips binary files (null-byte heuristic) for grep
+ * - Skips .proof/ and .git/
+ * - Re-checks scope on every matched path
+ */
+export const runtime = "nodejs";
+
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { NextResponse } from "next/server";
+import { checkAuth, enforceScope } from "@/lib/proof/auth";
+import { getRootDir, safeRootPath } from "@/lib/root-dir";
+import { safeAbsPath, looksLikeBinary } from "@/lib/proof/raw-fs";
+import { matchGlob } from "@/lib/proof/glob";
+import type { Agent } from "@/lib/proof/registry";
+
+const HARD_MAX_MATCHES = 2_000;
+const HARD_MAX_SCAN_BYTES = 50 * 1024 * 1024; // 50 MB total
+const SEARCH_TIMEOUT_MS = 10_000;
+
+export interface SearchMatch {
+	path: string;
+	line?: number;
+	col?: number;
+	text?: string;
+}
+
+function errJson(code: string, message: string, status: number): NextResponse {
+	return NextResponse.json({ error: code, message }, { status });
+}
+
+const SKIP_DIRS = new Set([".proof", ".git", "node_modules", ".next"]);
+
+// ── Walk helpers ──────────────────────────────────────────────────────────────
+
+async function* walkFiles(rootDir: string, relDir: string): AsyncGenerator<string> {
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	let items: any[];
+	try {
+		items = await readdir(path.join(rootDir, relDir), { withFileTypes: true }) as any[];
+	} catch {
+		return;
+	}
+	for (const item of items) {
+		if (SKIP_DIRS.has(item.name as string)) continue;
+		const childRel = relDir ? `${relDir}/${item.name as string}` : item.name as string;
+		if (item.isDirectory()) {
+			yield* walkFiles(rootDir, childRel);
+		} else if (item.isFile() || item.isSymbolicLink()) {
+			yield childRel;
+		}
+	}
+}
+
+// ── Grep ─────────────────────────────────────────────────────────────────────
+
+async function grepSearch(
+	rootDir: string,
+	startRel: string,
+	pattern: string,
+	limit: number,
+	agent: Agent,
+	deadline: number,
+): Promise<{ matches: SearchMatch[]; truncated: boolean }> {
+	let regex: RegExp;
+	try {
+		regex = new RegExp(pattern, "d");
+	} catch {
+		// fallback without indices flag
+		try {
+			regex = new RegExp(pattern);
+		} catch {
+			throw new Error("Invalid regex pattern");
+		}
+	}
+
+	const matches: SearchMatch[] = [];
+	let scannedBytes = 0;
+
+	for await (const fileRel of walkFiles(rootDir, startRel)) {
+		if (matches.length >= limit) return { matches, truncated: true };
+		if (Date.now() > deadline) return { matches, truncated: true };
+
+		const sc = enforceScope(agent, { filePath: fileRel, op: "read" });
+		if (!sc.ok) continue;
+
+		let buf: Buffer;
+		try {
+			buf = await readFile(path.join(rootDir, fileRel));
+		} catch {
+			continue;
+		}
+
+		scannedBytes += buf.length;
+		if (scannedBytes > HARD_MAX_SCAN_BYTES) return { matches, truncated: true };
+
+		if (looksLikeBinary(buf)) continue;
+
+		const text = buf.toString("utf-8");
+		const lines = text.split("\n");
+		for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+			if (matches.length >= limit) return { matches, truncated: true };
+			const lineText = lines[lineIdx]!;
+			// Reset lastIndex for global regexes
+			regex.lastIndex = 0;
+			const m = regex.exec(lineText);
+			if (m) {
+				matches.push({
+					path: fileRel,
+					line: lineIdx + 1,
+					col: (m.index ?? 0) + 1,
+					text: lineText,
+				});
+			}
+		}
+	}
+
+	return { matches, truncated: false };
+}
+
+// ── Glob ─────────────────────────────────────────────────────────────────────
+
+async function globSearch(
+	rootDir: string,
+	startRel: string,
+	pattern: string,
+	limit: number,
+	agent: Agent,
+	deadline: number,
+): Promise<{ matches: SearchMatch[]; truncated: boolean }> {
+	const matches: SearchMatch[] = [];
+
+	for await (const fileRel of walkFiles(rootDir, startRel)) {
+		if (matches.length >= limit) return { matches, truncated: true };
+		if (Date.now() > deadline) return { matches, truncated: true };
+
+		// Match pattern against relative path OR just the filename
+		const baseName = path.basename(fileRel);
+		if (!matchGlob(pattern, fileRel) && !matchGlob(pattern, baseName)) continue;
+
+		const sc = enforceScope(agent, { filePath: fileRel, op: "read" });
+		if (!sc.ok) continue;
+
+		matches.push({ path: fileRel });
+	}
+
+	return { matches, truncated: false };
+}
+
+// ── Route ─────────────────────────────────────────────────────────────────────
+
+export async function POST(req: Request): Promise<NextResponse> {
+	const auth = await checkAuth(req);
+	if (!auth.ok) return errJson("UNAUTHORIZED", auth.message ?? "Unauthorized", 401);
+
+	let body: { kind?: unknown; query?: unknown; path?: unknown; limit?: unknown };
+	try {
+		body = (await req.json()) as typeof body;
+	} catch {
+		return errJson("INVALID_PAYLOAD", "Invalid JSON body", 400);
+	}
+
+	if (body.kind !== "grep" && body.kind !== "glob") {
+		return errJson("INVALID_PAYLOAD", 'kind must be "grep" or "glob"', 400);
+	}
+	if (typeof body.query !== "string" || !body.query) {
+		return errJson("INVALID_PAYLOAD", "query (string) required", 400);
+	}
+
+	const kind = body.kind as "grep" | "glob";
+	const query = body.query as string;
+	const startRelRaw = typeof body.path === "string" ? body.path : "";
+	const limit = Math.min(
+		typeof body.limit === "number" ? body.limit : 200,
+		HARD_MAX_MATCHES,
+	);
+
+	// Validate start path
+	if (startRelRaw) {
+		if (!safeRootPath(startRelRaw)) {
+			return errJson("INVALID_PATH", "path: traversal rejected", 400);
+		}
+		const safe = await safeAbsPath(startRelRaw);
+		if (!safe) return errJson("INVALID_PATH", "path: rejected (symlink escape or denied)", 400);
+	}
+
+	const rootDir = getRootDir();
+
+	// Verify start path is a directory
+	if (startRelRaw) {
+		try {
+			const st = await stat(path.join(rootDir, startRelRaw));
+			if (!st.isDirectory()) {
+				return errJson("NOT_A_DIRECTORY", "path must be a directory", 400);
+			}
+		} catch (e) {
+			if ((e as NodeJS.ErrnoException).code === "ENOENT") {
+				return errJson("NOT_FOUND", "Start path not found", 404);
+			}
+			throw e;
+		}
+	}
+
+	const deadline = Date.now() + SEARCH_TIMEOUT_MS;
+	let result: { matches: SearchMatch[]; truncated: boolean };
+
+	try {
+		if (kind === "grep") {
+			result = await grepSearch(rootDir, startRelRaw, query, limit, auth.agent, deadline);
+		} else {
+			result = await globSearch(rootDir, startRelRaw, query, limit, auth.agent, deadline);
+		}
+	} catch (e) {
+		return errJson("SEARCH_ERROR", (e as Error).message, 400);
+	}
+
+	return NextResponse.json({
+		kind,
+		query,
+		matches: result.matches,
+		truncated: result.truncated,
+	});
+}

package/.next/standalone/src/app/api/agent/register/route.ts

@@ -12,7 +12,7 @@ import { checkRegisterRateLimit } from "@/lib/proof/register-rate-limit";
 export const runtime = "nodejs";
 
 const AGENT_ID_RE = /^ai:[a-z][a-z0-9-]{0,30}$/i;
-const VALID_OPS = new Set(["read", "mutate"]);
+const VALID_OPS = new Set(["read", "mutate", "delete"]);
 
 function validateScope(s: Record<string, unknown>): AgentScope | { error: string } {
 	if (!Array.isArray(s.paths) || s.paths.length === 0 || s.paths.length > 20) {
@@ -28,10 +28,10 @@ function validateScope(s: Record<string, unknown>): AgentScope | { error: string
 	}
 	for (const op of s.ops) {
 		if (!VALID_OPS.has(op as string)) {
-			return { error: `scope.ops values must be "read" or "mutate"` };
+			return { error: `scope.ops values must be "read", "mutate", or "delete"` };
 		}
 	}
-	return { paths: s.paths as string[], ops: s.ops as Array<"read" | "mutate"> };
+	return { paths: s.paths as string[], ops: s.ops as Array<"read" | "mutate" | "delete"> };
 }
 
 /** Exported for reuse in approve route. */

package/.next/standalone/src/app/api/agents/install/route.ts

@@ -4,6 +4,8 @@ import { NextRequest, NextResponse } from "next/server";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 
+const MAX_FILE_BYTES = 50_000_000; // 50 MB
+
 async function readVersion(): Promise<string> {
 	try {
 		const raw = await readFile(path.resolve(process.cwd(), "package.json"), "utf-8");
@@ -57,13 +59,53 @@ export async function GET(req: NextRequest): Promise<NextResponse> {
 		skillRaw: "/api/agents/skill",
 		skillCli: "npx skills add anh-chu/wiki-viewer/agents/wiki-viewer-skill",
 		routes: [
+			// Registration
 			{ method: "POST", path: "/api/agent/register", auth: "none", purpose: "Register an agent" },
 			{ method: "GET", path: "/api/agent/register/<regId>", auth: "none", purpose: "Poll registration status" },
-			{ method: "GET", path: "/api/agent/files/<path>.md", auth: "bearer+agent-id", purpose: "Read snapshot" },
-			{ method: "POST", path: "/api/agent/files/<path>.md", auth: "bearer+agent-id", purpose: "Apply ops" },
+			// Tier 2 — Collab (markdown block-ops + provenance)
+			{ method: "GET", path: "/api/agent/files/<path>.md", auth: "bearer+agent-id", purpose: "Read markdown snapshot (block-ops tier)" },
+			{ method: "POST", path: "/api/agent/files/<path>.md", auth: "bearer+agent-id", purpose: "Apply block-ops" },
 			{ method: "GET", path: "/api/agent/events/<path>.md", auth: "bearer+agent-id", purpose: "Poll events" },
 			{ method: "POST", path: "/api/agent/events/<path>.md", auth: "bearer+agent-id", purpose: "Ack events" },
+			// Tier 1 — Raw FS (all file types)
+			{ method: "GET",    path: "/api/agent/fs/file/<path>",  auth: "bearer+agent-id", purpose: "Read file bytes. Supports Range. Returns ETag (sha256), X-File-Size, X-File-Mtime, X-Collab-State." },
+			{ method: "PUT",    path: "/api/agent/fs/file/<path>",  auth: "bearer+agent-id", purpose: "Atomic whole-file write. If-Match required for overwrites; omit for creates. ?mkdirs=true creates parents. ?force=true bypasses If-Match (audited)." },
+			{ method: "DELETE", path: "/api/agent/fs/file/<path>",  auth: "bearer+agent-id", purpose: "Delete file (+ sidecar for .md). Requires If-Match + delete scope op. ?recursive=true for directories." },
+			{ method: "GET",    path: "/api/agent/fs/ls/<path>",    auth: "bearer+agent-id", purpose: "Directory listing. ?recursive&limit&depth. Scope-filtered. Excludes .proof/." },
+			{ method: "POST",   path: "/api/agent/fs/move",         auth: "bearer+agent-id", purpose: "Move/rename. Body: {from, to, ifMatch?}. Moves .md sidecar too." },
+			{ method: "POST",   path: "/api/agent/fs/search",       auth: "bearer+agent-id", purpose: "Server-side grep or glob. Body: {kind:'grep'|'glob', query, path?, glob?, limit?}." },
+			// Human presence (for editor lease — drives active collab-state)
+			{ method: "POST",   path: "/api/wiki/presence",         auth: "session",          purpose: "Human editor lease heartbeat. Body: {path, action:'open'|'heartbeat'|'close'}." },
 		],
+		capabilities: {
+			maxFileBytes: MAX_FILE_BYTES,
+			supportsRange: true,
+			ifMatchRequired: true,
+			forceBypass: true,
+			search: ["grep", "glob"],
+			globDialect: "**,*,?",
+			scopeOps: ["read", "mutate", "delete"],
+			collabStates: ["active", "tracked", "untracked", "not-markdown"],
+			collabPrecondition: "If-Collab-Match",
+		},
+		modes: {
+			rule: "Before editing a .md file, read it and check the X-Collab-State response header. If 'active', use block-ops (Tier 2) at the X-Collab-Snapshot URL so a human can review your changes. If 'tracked', prefer block-ops for semantic/prose edits; use raw fs only for mechanical/whole-file ops (reformat, regenerate). If 'untracked', raw fs is fine (a Tier-2 edit would create a sidecar). For non-markdown files, always use raw fs (Tier 2 does not apply). A raw PUT to an active .md is rejected 409 COLLAB_ACTIVE with the Tier-2 URL — switch to block-ops.",
+			collabStateHeaders: [
+				"X-Collab-State: active|tracked|untracked|not-markdown",
+				"X-Collab-Revision: <n>",
+				"X-Collab-Snapshot: /api/agent/files/<path>.md",
+			],
+			tiers: {
+				tier1: "Raw FS — /api/agent/fs/* — all file types, fast, light audit (ETag/sha256, file.rawWritten event, audit table). No proof-spans.",
+				tier2: "Collab — /api/agent/files/*.md — markdown only, reviewable proof-spans, comments, suggestions. Human can accept/revert.",
+			},
+		},
+		mcpAdapter: {
+			package: "wiki-viewer-mcp",
+			invoke: "npx wiki-viewer-mcp",
+			env: ["WIKI_VIEWER_URL", "WIKI_VIEWER_TOKEN", "WIKI_VIEWER_AGENT_ID"],
+			description: "Thin MCP adapter mapping standard MCP filesystem tools onto these endpoints. Reads X-Collab-State and blocks or warns on raw writes to active .md files.",
+		},
 		ops: [
 			"block.replace",
 			"block.insertAfter",

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

@@ -3,7 +3,8 @@ import path from "node:path";
 import { NextResponse } from "next/server";
 import { checkOrigin } from "@/lib/auth/csrf";
 import { requireUser } from "@/lib/auth/server";
-import { safeRootPath } from "@/lib/root-dir";
+import { safeRootPath, getRootDir } from "@/lib/root-dir";
+import { moveSidecar } from "@/lib/proof/sidecar";
 
 export async function POST(request: Request) {
 	const csrf = checkOrigin(request);
@@ -45,6 +46,14 @@ export async function POST(request: Request) {
 
 	try {
 		await rename(fromPath, toPath);
+
+		// Fix latent bug: sidecar was orphaned on .md renames (R3)
+		const fromExt = path.extname(body.from).toLowerCase();
+		if (fromExt === ".md" || fromExt === ".markdown") {
+			const rootDir = getRootDir();
+			await moveSidecar(rootDir, body.from, body.to);
+		}
+
 		return NextResponse.json({ ok: true });
 	} catch {
 		return NextResponse.json({ error: "Move failed" }, { status: 500 });

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

@@ -0,0 +1,55 @@
+/**
+ * POST /api/wiki/presence
+ *
+ * Human editor heartbeat — sets or clears a human-edit lease so that
+ * computeCollabState can return "active" even before the first suggestion.
+ *
+ * Body: { path: string; action: "open" | "heartbeat" | "close" }
+ *
+ * Authenticated: requires a logged-in browser session (same as /api/wiki/watch).
+ * Agent tokens are NOT accepted here — this endpoint is human-only.
+ */
+export const runtime = "nodejs";
+
+import { NextResponse } from "next/server";
+import { requireUser } from "@/lib/auth/server";
+import { setLease, clearLease } from "@/lib/proof/lease";
+import { safeRootPath } from "@/lib/root-dir";
+
+function errJson(code: string, message: string, status: number): NextResponse {
+	return NextResponse.json({ error: code, message }, { status });
+}
+
+export async function POST(req: Request): Promise<NextResponse> {
+	const auth = await requireUser(req);
+	if (!auth.ok) return errJson("UNAUTHORIZED", "Not authenticated", 401);
+
+	let body: { path?: unknown; action?: unknown };
+	try {
+		body = (await req.json()) as { path?: unknown; action?: unknown };
+	} catch {
+		return errJson("INVALID_PAYLOAD", "Request body must be JSON", 400);
+	}
+
+	const relPath = typeof body.path === "string" ? body.path : null;
+	const action = typeof body.action === "string" ? body.action : null;
+
+	if (!relPath) return errJson("MISSING_PATH", "path is required", 400);
+	if (!action || !["open", "heartbeat", "close"].includes(action)) {
+		return errJson("INVALID_ACTION", "action must be open | heartbeat | close", 400);
+	}
+
+	// Basic traversal guard
+	if (!safeRootPath(relPath)) {
+		return errJson("INVALID_PATH", "Path traversal rejected", 400);
+	}
+
+	if (action === "open" || action === "heartbeat") {
+		setLease(relPath, auth.user.id);
+	} else {
+		// close
+		clearLease(relPath, auth.user.id);
+	}
+
+	return NextResponse.json({ ok: true });
+}