difftab 0.1.0

package/dist/server/main.js

@@ -0,0 +1,2305 @@
+import { closeSync, mkdirSync, openSync, readFileSync, realpathSync, statSync, unlinkSync, watch, writeFileSync, writeSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { spawn } from "node:child_process";
+import { createServer, request } from "node:http";
+import { homedir, tmpdir } from "node:os";
+import { access, lstat, readFile, readlink } from "node:fs/promises";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+
+//#region src/server/cli/args.ts
+var CliUsageError = class extends Error {};
+const HELP_TEXT = `difftab — see what changed in this repository (read-only)
+
+Usage:
+  difftab [options]
+
+Options:
+  --no-open      print the URL instead of opening a browser
+  -v, --version  print the version and exit
+  -h, --help     print this help and exit
+
+difftab never writes to your repository.
+`;
+function parseCliArgs(argv) {
+	try {
+		const { values } = parseArgs({
+			args: [...argv],
+			options: {
+				version: {
+					type: "boolean",
+					short: "v"
+				},
+				help: {
+					type: "boolean",
+					short: "h"
+				},
+				"no-open": { type: "boolean" }
+			},
+			strict: true,
+			allowPositionals: false
+		});
+		return {
+			version: values.version === true,
+			help: values.help === true,
+			noOpen: values["no-open"] === true
+		};
+	} catch (cause) {
+		throw new CliUsageError(cause instanceof Error ? cause.message : String(cause));
+	}
+}
+
+//#endregion
+//#region src/server/git/run.ts
+/**
+* 所有 git 调用统一注入,不留给各调用点自己记得加(spec §5.2)。
+*
+* `-z` 只作用于 status / numstat 这类**列表输出**,管不到 `git diff` 的补丁正文 ——
+* 正文里的 `diff --git` / `---` / `+++` / `rename from|to` 头部行仍会按 C 风格转义
+* (已实测),而 diff2html 恰恰是从这些头部行解析文件名的。两者互补,不可相互替代。
+*
+* 注入位置必须在子命令**之前**:`-c` 是 git 的全局选项,放在子命令后面 git 不认。
+*/
+const GLOBAL_CONFIG = ["-c", "core.quotePath=false"];
+/**
+* 子进程环境。
+*
+* `GIT_OPTIONAL_LOCKS=0` 是只读承诺的一部分而不是性能开关:默认情况下 `git status`
+* 会顺手把刷新过的 stat 缓存写回 `.git/index`。那不改变 status 的输出,因此
+* 「前后 `git status` 比对」这类验证发现不了它(§5.10 排除该做法的原因之一)。
+*
+* **把这一行删掉,只读 `.git` 那半层门禁照样全绿**(已实测,见 §10):git 把 index
+* 回写当 best-effort,`.git` 不可写时它静默跳过、exit 0、stderr 全空。真正看得见
+* 的是 §5.10 第二层的 **B 半**——在可写的 `.git` 上前后做逐字节快照比对
+* (`test/smoke/readonly-git-dir.test.js`)。别把 B 半当成 A 半的重复给删了。
+*
+* 该变量在 git < 2.15 上不存在,设了也无害 —— 那个区间的 git 只是照旧写 index。
+*
+* `GIT_TERMINAL_PROMPT=0` 防止任何意外的凭据交互把无人值守的进程挂住。
+*
+* **`GIT_LITERAL_PATHSPECS=1` 是安全项而不是洁癖**:`--` 后面的路径默认是 **wildmatch
+* 模式**,不是字面路径。我们的路径全部来自 URL query,于是 `path=*` 会让
+* `git diff HEAD -- '*'` 回一份**整仓 diff**(已实测)——正是 §5.2 明令禁止、
+* 会把浏览器主线程冻上数十秒的那件事;而一个真实存在、名字里带 `*` 的文件同样会
+* 匹配到别人身上,页面在 A 的标题下显示 B 的补丁。设了它,`*` / `?` / `[…]` 一律
+* 按字面比较。本项目的路径无一例外来自 git 自己的输出,不需要任何通配语义。
+*/
+const GIT_ENV = {
+	GIT_OPTIONAL_LOCKS: "0",
+	GIT_TERMINAL_PROMPT: "0",
+	GIT_LITERAL_PATHSPECS: "1"
+};
+/**
+* stdout 的**兜底**上限。没有它,一个几百 MB 的文件的 diff 会被整个读进内存,
+* 而这条路径上没有任何东西会先失败。
+*
+* 产品语义那道 5MB 闸不在这里,而是由调用方按次传 `maxStdoutBytes`(§5.2 的
+* 「卡补丁字节数」——见 git/diff.ts):**能不能渲染取决于补丁多大,而不是文件多大**,
+* 一个 6MB 的数据文件改一行照样该看得见。本常量只管「别把进程撑爆」。
+*/
+const MAX_STDOUT_BYTES = 67108864;
+var GitError = class extends Error {
+	kind;
+	args;
+	stderr;
+	code;
+	constructor(kind, args, stderr, code) {
+		super(`git ${args.join(" ")} failed (${kind})`);
+		this.name = "GitError";
+		this.kind = kind;
+		this.args = args;
+		this.stderr = stderr;
+		this.code = code;
+	}
+};
+/**
+* 跑一条 git 命令。**非零退出不抛异常** —— 交给调用方判断,因为若干只读探测
+* (空仓库下的 `rev-parse --verify HEAD`、下限之下的 `--show-object-format`)
+* 正是靠非零退出来给出答案的。
+*/
+function runGit(args, cwd, options = {}) {
+	const limit = Math.min(options.maxStdoutBytes ?? MAX_STDOUT_BYTES, MAX_STDOUT_BYTES);
+	return new Promise((resolvePromise, rejectPromise) => {
+		const argv = [...GLOBAL_CONFIG, ...args];
+		const child = spawn("git", argv, {
+			cwd,
+			env: {
+				...process.env,
+				...GIT_ENV
+			},
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		const out = [];
+		const err = [];
+		let outBytes = 0;
+		let overflowed = false;
+		child.stdout.on("data", (chunk) => {
+			outBytes += chunk.length;
+			if (outBytes > limit) {
+				overflowed = true;
+				child.kill();
+				return;
+			}
+			out.push(chunk);
+		});
+		child.stderr.on("data", (chunk) => {
+			err.push(chunk);
+		});
+		/**
+		* **`kill()` 之后到达的报错是这次 kill 的后果,不是新事实。**
+		*
+		* 实测(CI run 31755485278):超限掐断 git 之后,**windows × Node 22.0.x 那一档**
+		* 会走到下面的 `'error'` 分支,于是 `kind` 成了 `exit`——调用方认不出「补丁太大」
+		* 这个结论,`too-large` 那条分支静默变成一个 500;另外 8 档与本机全绿,因为那里
+		* 这个事件根本不触发。至于报的是 EPIPE(git 还写在管道上)还是 kill 本身失败,
+		* 无从也无需区分:**判定超限之后,任何错误都是我们自己动手的结果。**
+		*
+		* 所以只要已经判定超限,一律以 `overflow` 收尾;流上的 `'error'` 同样咽掉 ——
+		* 一个没人监听的流错误会以未捕获异常掀掉整个服务,而进程的死活由下面两个
+		* 事件负责报告,不需要它再说一遍。
+		*/
+		const settleOverflow = () => rejectPromise(new GitError("overflow", argv, "", null));
+		for (const stream of [child.stdout, child.stderr]) stream.on("error", () => {
+			if (overflowed) settleOverflow();
+		});
+		child.on("error", (cause) => {
+			if (overflowed) {
+				settleOverflow();
+				return;
+			}
+			rejectPromise(new GitError(cause.code === "ENOENT" ? "missing" : "exit", argv, String(cause.message), null));
+		});
+		child.on("close", (code) => {
+			const stderr = Buffer.concat(err).toString("utf8");
+			if (overflowed) {
+				rejectPromise(new GitError("overflow", argv, stderr, code));
+				return;
+			}
+			resolvePromise({
+				stdout: Buffer.concat(out).toString("utf8"),
+				stderr,
+				code
+			});
+		});
+	});
+}
+/** 同上,但非零退出即抛。用于「失败没有第二种解释」的调用点。 */
+async function runGitStrict(args, cwd) {
+	const result = await runGit(args, cwd);
+	if (result.code !== 0) throw new GitError("exit", args, result.stderr, result.code);
+	return result.stdout;
+}
+
+//#endregion
+//#region src/server/git/repo.ts
+/** `--porcelain=v2` 的最低要求(spec §5.2)。 */
+const MIN_GIT = {
+	major: 2,
+	minor: 11
+};
+/**
+* 空树对象哈希。空仓库下 HEAD 不存在、`git diff HEAD` 直接 fatal,改用它作 diff 基准
+* 即可(spec §5.3),不必为空仓库写一条特殊分支。
+*
+* 硬编码是**要求**而不是偷懒:`git hash-object -t tree /dev/null` 依赖 `/dev/null`,
+* Windows 上不可移植;`git mktree` 会写对象库,直接违反只读承诺。
+*/
+const EMPTY_TREE = {
+	sha1: "4b825dc642cb6eb9a060e54bf8d69288fbee4904",
+	sha256: "6ef19b41225c5369f1c104d45d8d85efa9b057b53b14b4b9b939dd74decc5321"
+};
+/** 启动前置检查失败。CLI 据此打印一句话友好报错,而不是抛 Node 异常栈(§5.2)。 */
+var PreflightError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "PreflightError";
+		this.code = code;
+	}
+};
+/** `git version 2.50.1 (Apple Git-155)` → `{ major: 2, minor: 50 }`。 */
+function parseGitVersion(output) {
+	const m = /\bversion\s+(\d+)\.(\d+)/.exec(output);
+	if (!m) return null;
+	return {
+		major: Number(m[1]),
+		minor: Number(m[2])
+	};
+}
+function tooOld(v) {
+	return v.major < MIN_GIT.major || v.major === MIN_GIT.major && v.minor < MIN_GIT.minor;
+}
+/**
+* 前置检查 + 定位,一次做完。
+*
+* 两条命令并发跑:串行等于把两次进程启动开销叠加进 §6 的 300ms 冷启动预算,
+* 而它们之间没有依赖。失败路径上的额外一次 `rev-parse` 不计成本 —— 那条路径的
+* 终点是打印一行报错然后退出。
+*/
+async function locateRepo(cwd) {
+	const [version, located] = await Promise.all([runGit(["--version"], cwd), runGit([
+		"rev-parse",
+		"--show-toplevel",
+		"--git-dir"
+	], cwd)]).catch((cause) => {
+		if (cause instanceof GitError && cause.kind === "missing") throw new PreflightError("git-missing", "git was not found on your PATH. Install git and try again.");
+		throw cause;
+	});
+	const parsed = version.code === 0 ? parseGitVersion(version.stdout) : null;
+	if (parsed && tooOld(parsed)) throw new PreflightError("git-too-old", `difftab needs git ${MIN_GIT.major}.${MIN_GIT.minor} or newer (for --porcelain=v2), but found ${parsed.major}.${parsed.minor}.`);
+	if (located.code !== 0) {
+		const bare = await runGit(["rev-parse", "--is-bare-repository"], cwd);
+		if (bare.code === 0 && bare.stdout.trim() === "true") throw new PreflightError("bare-repo", "this is a bare repository — it has no working tree to show changes for.");
+		throw new PreflightError("not-a-repo", "this directory is not inside a git repository.");
+	}
+	const lines = located.stdout.split("\n");
+	const root = lines[0]?.trim();
+	const gitDir = lines[1]?.trim();
+	if (!root || !gitDir) throw new PreflightError("not-a-repo", "this directory is not inside a git repository.");
+	return {
+		root,
+		gitDir: isAbsolute(gitDir) ? gitDir : resolve(root, gitDir)
+	};
+}
+/**
+* diff 的基准。
+*
+* 正常仓库是 `HEAD`;空仓库(尚无任何提交)下 HEAD 不存在,`git diff HEAD` 会 fatal,
+* 降级为空树哈希(spec §5.3)。
+*
+* 不做缓存:`git checkout --orphan` 之后 HEAD 会重新变回未出生状态,缓存的正结果
+* 会让 diff 从此全部 fatal。这条只在取 diff 时调用,不落在冷启动路径上。
+*/
+async function resolveDiffBase(root) {
+	const head = await runGit([
+		"rev-parse",
+		"--verify",
+		"--quiet",
+		"HEAD"
+	], root);
+	if (head.code === 0 && head.stdout.trim()) return "HEAD";
+	const format = await runGit(["rev-parse", "--show-object-format"], root);
+	return (format.code === 0 ? format.stdout.trim() : "sha1") === "sha256" ? EMPTY_TREE.sha256 : EMPTY_TREE.sha1;
+}
+
+//#endregion
+//#region src/server/git/diff.ts
+/**
+* 超过这个字节数只提示、不预览(spec §3 / §5.2)。
+*
+* **两条路量的东西不同,但量的都是「前端要吃下多少字节」**:未跟踪那一侧整份文件
+* 就是补丁,所以量文件(还省得把它读进来);已跟踪那一侧补丁只含改动与上下文,
+* 所以量补丁本身(见 `trackedDiff`)。
+*/
+const MAX_BYTES = 5242880;
+/**
+* 行数上限。体积阈值挡不住另一头:超长行数的窄文件体积不大,但逐行构造 diff 与
+* 前端渲染同样会卡(spec §5.2)。
+*
+* 已跟踪那一侧数的是**改动行数**(numstat 的加 + 减),未跟踪数的是文件行数 ——
+* 后者本来就整份都是新增行。两边量的都是「前端要渲染多少行」。
+*/
+const MAX_LINES = 5e4;
+var DiffRequestError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "DiffRequestError";
+		this.code = code;
+	}
+};
+/**
+* 把请求里的仓库相对路径落到磁盘上,并保证它没有走出仓库。
+*
+* 路径来自 URL query,是外部输入。`git diff -- <pathspec>` 自身受仓库边界约束,
+* 但未跟踪文件那条路径要**直接读磁盘**,没有这道检查就是一个路径穿越。
+*/
+function resolveInRepo(root, path) {
+	if (!path || isAbsolute(path) || path.includes("\0")) throw new DiffRequestError("invalid-path", "invalid path");
+	const abs = resolve(root, path);
+	const rel = relative(root, abs);
+	if (rel === "" || rel.startsWith("..") || rel.startsWith(`..${sep}`) || isAbsolute(rel)) throw new DiffRequestError("invalid-path", "invalid path");
+	return abs;
+}
+/** `-z` 输出里是否原样出现这条路径。 */
+function lists(output, path) {
+	return output.split("\0").some((entry) => entry === path);
+}
+/** 路径在 index 里。 */
+async function inIndex(root, path) {
+	return lists(await runGitStrict([
+		"ls-files",
+		"-z",
+		"--",
+		path
+	], root), path);
+}
+/**
+* `git diff --numstat -z` 的解析。**重命名记录不是一段而是三段。**
+*
+* 实测(见 spec §10):普通记录是 `<加>\t<减>\t<路径>`,一条占一个 NUL 段;
+* 重命名记录的**路径字段是空的**,后面紧跟两段 `<旧路径>` `<新路径>` ——
+* 与 `status --porcelain=v2` 的 `2 ` 记录**顺序相反**(那边是新在前、旧在后)。
+* 无状态地按 NUL 平铺切分,就会把 `<旧路径>` 当成下一条记录的开头。
+*
+* 本项目每次只问一条路径,所以「多吞两段」眼下不改变结果 —— 但把它写对的成本是
+* 三行,而写错的症状是将来某天改成批量查询后,一半记录静默错位。
+*/
+function parseNumstat(output) {
+	const segments = output.split("\0");
+	const records = [];
+	for (let i = 0; i < segments.length; i += 1) {
+		const match = /^(-|\d+)\t(-|\d+)\t(.*)$/s.exec(segments[i] ?? "");
+		if (!match) continue;
+		const binary = match[1] === "-" || match[2] === "-";
+		let path = match[3];
+		let oldPath = null;
+		if (path === "") {
+			oldPath = segments[i + 1] ?? "";
+			path = segments[i + 2] ?? "";
+			i += 2;
+		}
+		records.push({
+			binary,
+			lines: binary ? 0 : Number(match[1]) + Number(match[2]),
+			path,
+			oldPath
+		});
+	}
+	return records;
+}
+/**
+* 「基准 → 工作区」这条路径上的 numstat 记录;不在差异里就是 `null`。
+*
+* 这一次调用同时回答三个问题,所以它取代了原先那次 `diff --name-only`:
+* 1. **它是不是已跟踪的**。`ls-files` 只答得出 index 里有什么,而已跟踪是
+*    **HEAD ∪ index**:`git rm` 之后已暂存的删除在 index 里已经没有了(实测
+*    `ls-files` 输出为空),status 却照样报 `1 D.`、基准侧也还在。只认 index 会把
+*    它误判成未跟踪、掉进读磁盘那条路,以「文件不存在」告终;
+* 2. **是不是二进制**。已跟踪那一侧一律以 git 自己的判定为准(含 `.gitattributes`),
+*    比 NUL 探测准确(§5.2),形态是 `-\t-\t<路径>`;
+* 3. **改了多少行**。行数阈值那一路的判据。
+*
+* 重命名同样要传两个路径 + `-M`:只传新路径时 git 无法配对,numstat 会把它算成
+* 一个全新增文件(行数因此是整份文件),与补丁那一侧的退化是同一回事(§5.2)。
+*/
+async function readNumstat(root, base, path, oldPath) {
+	/**
+	* **一次查询可以回不止一条记录**,所以必须按路径挑,不能取 `[0]`:
+	*
+	* 传了两个路径而 git **配不上对**时(`git mv` 之后把内容全部重写、留在工作区不
+	* `git add` —— status 照报 `R100`,所以 `oldPath` 是有的,见 §10),它会拆成
+	* 「删掉旧的」+「新增新的」两条,按路径排序。取 `[0]` 就是掷硬币:实测那条
+	* 60,000 行的改名里,排在前面的是旧文件那条 100 行的删除,于是行数闸放它过去,
+	* 一份 6 万行的补丁照旧发给浏览器 —— 正是本阶段要防的那次冻结。二进制同理,
+	* 挑错记录会让一个文本文件被报成 binary(或反过来)。
+	*
+	* 挑中之后**合并**而不是取一条:那份补丁里两个文件都在,前端要渲染的是两者之和。
+	*/
+	const mine = parseNumstat(await runGitStrict(oldPath ? [
+		"diff",
+		base,
+		"--numstat",
+		"-z",
+		"-M",
+		"--",
+		path,
+		oldPath
+	] : [
+		"diff",
+		base,
+		"--numstat",
+		"-z",
+		"--",
+		path
+	], root)).filter((record) => record.path === path || oldPath !== void 0 && record.path === oldPath);
+	if (mine.length === 0) return null;
+	return {
+		binary: mine.some((record) => record.binary),
+		lines: mine.reduce((total, record) => total + record.lines, 0)
+	};
+}
+/** 工作区里这个文件的字节数;文件不在(删除)就是 `null`。 */
+async function worktreeSize(abs) {
+	try {
+		return (await lstat(abs)).size;
+	} catch {
+		return null;
+	}
+}
+/**
+* 已跟踪文件的补丁,以及三道拒绝(§5.2 / §5.12)。
+*
+* **已跟踪那一侧卡的是「补丁多大」,不是「文件多大」**:文件体积只对未跟踪那条路
+* 成立(整份文件就是补丁),而已跟踪文件的补丁只包含改动与上下文 —— 按文件体积拒绝,
+* 一个 6MB 的数据文件改一行就再也看不了,而那是 agent 最常见的输出之一。反过来,
+* 行数也**不能**替代:一个「一行 6MB」的文件 numstat 只报 1 行,行数闸对它毫无作用。
+* 两者都量不到的东西正是字节,所以那一闸只能由取补丁那次调用自己带着上限去撞。
+*
+* 顺序:二进制(numstat)→ 行数(numstat)→ 取补丁并卡字节。二进制先答是因为它比
+* 「太大」更具体,一个 8MB 的 PNG 说「文件过大」等于把原因说错了;行数排在取补丁之前,
+* 是因为它不用付出取补丁的代价就能拦下 5 万行以上的改动。
+*
+* `size` 只用于**说话**(告诉用户这文件多大),不再参与判定,所以**只在要拒绝的那两条
+* 分支上才去 `lstat`**:正常那条路(绝大多数请求)一次系统调用都不欠。文件已被删除时
+* 取不到,给 0,前端据此不显示体积(§5.12)。
+*
+* **重命名条目必须同时传新旧两个路径**:只传新路径时 git 看不到另一侧、无法配对,
+* 会把重命名退化成一个全新增文件(已实测,spec §5.2),「重命名识别并标注」随之落空。
+* 两个路径都来自 status 的 `2 ` 记录,无需额外查询。
+*/
+async function trackedDiff(root, base, path, abs, oldPath, stat) {
+	if (stat?.binary) return { kind: "binary" };
+	if (stat && stat.lines > MAX_LINES) return {
+		kind: "too-large",
+		size: await worktreeSize(abs) ?? 0,
+		reason: "lines"
+	};
+	const args = oldPath ? [
+		"diff",
+		base,
+		"-M",
+		"--",
+		path,
+		oldPath
+	] : [
+		"diff",
+		base,
+		"--",
+		path
+	];
+	let result;
+	try {
+		result = await runGit(args, root, { maxStdoutBytes: MAX_BYTES });
+	} catch (cause) {
+		if (cause instanceof GitError && cause.kind === "overflow") return {
+			kind: "too-large",
+			size: await worktreeSize(abs) ?? 0,
+			reason: "size"
+		};
+		throw cause;
+	}
+	if (result.code !== 0) throw new DiffRequestError("not-found", "no diff available for this path");
+	return {
+		kind: "text",
+		patch: result.stdout
+	};
+}
+/** unified diff 的头四行。未跟踪的一切都是「新增」,左侧恒为 /dev/null。 */
+function newFileHeader(path, mode) {
+	return [
+		`diff --git a/${path} b/${path}`,
+		`new file mode ${mode}`,
+		"--- /dev/null",
+		`+++ b/${path}`
+	];
+}
+/**
+* 未跟踪文件的补丁:**直接读文件内容手工构造 unified diff**。
+*
+* 不用 `git diff --no-index` —— 它依赖 `/dev/null` 作为对比端,Windows 上不可移植
+* (spec §5.2 / §10)。
+*/
+async function untrackedDiff(root, path) {
+	const abs = resolveInRepo(root, path);
+	let info;
+	try {
+		info = await lstat(abs);
+	} catch {
+		throw new DiffRequestError("not-found", "file no longer exists");
+	}
+	if (info.isSymbolicLink()) {
+		const target = await readlink(abs);
+		return {
+			kind: "untracked-text",
+			patch: `${[
+				...newFileHeader(path, "120000"),
+				"@@ -0,0 +1 @@",
+				`+${target}`,
+				"\"
+			].join("\n")}\n`
+		};
+	}
+	if (!info.isFile()) throw new DiffRequestError("invalid-path", "not a regular file");
+	if (info.size > MAX_BYTES) return {
+		kind: "too-large",
+		size: info.size,
+		reason: "size"
+	};
+	const buffer = await readFile(abs);
+	if (buffer.includes(0)) return { kind: "binary" };
+	const text = buffer.toString("utf8");
+	const endsWithNewline = text.endsWith("\n");
+	const lines = text === "" ? [] : text.split("\n");
+	if (endsWithNewline) lines.pop();
+	if (lines.length > MAX_LINES) return {
+		kind: "too-large",
+		size: info.size,
+		reason: "lines"
+	};
+	const head = newFileHeader(path, info.mode & 73 ? "100755" : "100644");
+	if (lines.length === 0) return {
+		kind: "untracked-text",
+		patch: `${head.join("\n")}\n`
+	};
+	const body = lines.map((line) => `+${line}`);
+	if (!endsWithNewline) body.push("\");
+	return {
+		kind: "untracked-text",
+		patch: `${[
+			...head,
+			`@@ -0,0 +1,${lines.length} @@`,
+			...body
+		].join("\n")}\n`
+	};
+}
+async function readDiff(root, query) {
+	const abs = resolveInRepo(root, query.path);
+	if (query.oldPath) resolveInRepo(root, query.oldPath);
+	const [base, listed] = await Promise.all([resolveDiffBase(root), inIndex(root, query.path)]);
+	const stat = await readNumstat(root, base, query.path, query.oldPath);
+	if (listed || stat !== null) return trackedDiff(root, base, query.path, abs, query.oldPath, stat);
+	return untrackedDiff(root, query.path);
+}
+
+//#endregion
+//#region src/server/git/operation.ts
+/**
+* 判据表,**按序取第一个命中**(spec §5.3)。
+*
+* 两处顺序不是随手排的:
+*
+* - **rebase 排在 merge 之前**。rebase 冲突停下时 git 目录里同时躺着 `rebase-merge/`
+*   与 `MERGE_MSG` / `AUTO_MERGE`(已实测,§10),而用户处在的是 rebase —— 反过来
+*   排会把它标成「合并中」,页面上看不出任何异样,只是说错了用户在干什么。
+*   `MERGE_HEAD` 本身在那种情形下不出现,所以这一条更像是给后来者的防线
+* - **`rebase-apply/rebasing` 排在 `rebase-apply` 之前**。`git am` 与 `git rebase --apply`
+*   共用 `rebase-apply/` 这一个目录,里面有没有 `rebasing` 是区分两者的唯一办法;
+*   合并成一个标注等于对着一个正在 `git am` 的用户说他在 rebase
+*/
+const PROBES = [
+	{
+		path: "rebase-merge",
+		operation: "rebase"
+	},
+	{
+		path: "rebase-apply/rebasing",
+		operation: "rebase"
+	},
+	{
+		path: "rebase-apply",
+		operation: "am"
+	},
+	{
+		path: "MERGE_HEAD",
+		operation: "merge"
+	},
+	{
+		path: "CHERRY_PICK_HEAD",
+		operation: "cherry-pick"
+	},
+	{
+		path: "REVERT_HEAD",
+		operation: "revert"
+	},
+	{
+		path: "BISECT_LOG",
+		operation: "bisect"
+	}
+];
+/** 存在与否,不区分文件还是目录 —— 上表里两种都有,而判据只是「在不在」。 */
+function exists(path) {
+	return access(path).then(() => true, () => false);
+}
+/**
+* 当前进行中的多步操作;没有则 `undefined`。
+*
+* **传进来的必须是 `git rev-parse --git-dir` 的返回值,不能自己拼 `<root>/.git`**
+* (§5.3):linked worktree 下 `.git` 是个文件、真正的 git 目录在
+* `<主仓库>/.git/worktrees/<名>`,submodule 在 `<父仓库>/.git/modules/<路径>`
+* (均已实测,§10)。拼出来的路径在那两种仓库里永远读不到 —— 于是永远标不出操作,
+* 而它不报错。`RepoInfo.gitDir` 已经是这个值,调用方照传即可。
+*
+* 七个探针**并发发**再按上表定序:顺序判据只有一处(上面那张表),而不是散落在
+* 一串 `await` 的先后里 —— 后者调换两行就静默换了语义。每个探针直接产出**答案还是
+* undefined**,于是取第一个命中就是一次普通的 `find`,不必再拿下标去另一个数组里
+* 对号入座 —— 那种写法会让「顺序对不对」多出一个不在表里的依赖。
+*/
+async function readOperation(gitDir) {
+	return (await Promise.all(PROBES.map(async (probe) => await exists(join(gitDir, probe.path)) ? probe.operation : void 0))).find((operation) => operation !== void 0);
+}
+
+//#endregion
+//#region src/server/git/status.ts
+/**
+* 文件列表与分支状态的**唯一**数据源,一次调用同时拿到文件状态、暂存/未暂存双状态位、
+* 重命名信息与分支 / ahead-behind。
+*
+* 导出成常量是为了让 S3b 的降级轮询**复用逐字相同的这一条**,而不是各写各的:
+* 漏掉 `-uall` 的后果是静默的 —— git 会把未跟踪目录折叠成一行 `dir/`,于是在一个
+* 已存在的未跟踪目录里新增文件根本不改变输出,轮询判定「无变化」、页面不刷新,
+* 而那正是 agent 边跑边生成文件时最常见的形态(spec §5.7 / §10)。
+*
+* 两个参数都不能省:`-uall` 见上;`-z` 是因为不加它 git 会对含非 ASCII 字符、空格、
+* 引号的路径做 C 风格转义并加引号(已实测)。
+*/
+const STATUS_ARGS = [
+	"status",
+	"--porcelain=v2",
+	"--branch",
+	"-uall",
+	"-z"
+];
+const STATUS_CODES = /* @__PURE__ */ new Set([
+	".",
+	"M",
+	"T",
+	"A",
+	"D",
+	"R",
+	"C",
+	"U"
+]);
+function asStatusCode(ch) {
+	return ch && STATUS_CODES.has(ch) ? ch : ".";
+}
+/**
+* 切出记录开头的 `n` 个空格分隔字段,剩下的整段就是路径。
+*
+* 不能整条 `split(' ')` —— 路径本身可以含空格,而 `-z` 只把**记录**分隔成 NUL 段,
+* 段内仍是空格分隔。
+*/
+function splitLeading(rec, n) {
+	const fields = [];
+	let start = 0;
+	for (let k = 0; k < n; k += 1) {
+		const sp = rec.indexOf(" ", start);
+		if (sp === -1) return null;
+		fields.push(rec.slice(start, sp));
+		start = sp + 1;
+	}
+	const rest = rec.slice(start);
+	return rest ? [fields, rest] : null;
+}
+/** `R100` / `C75` → 100 / 75。 */
+function parseScore(field) {
+	const m = field ? /^[RC](\d+)$/.exec(field) : null;
+	return m?.[1] ? Number(m[1]) : null;
+}
+/**
+* 解析 `-z` 输出。
+*
+* **NUL 在重命名记录里既是记录分隔符、又是字段分隔符**:`2 ` 记录的格式是
+* `2 <XY> ... R<score> <新路径>\0<旧路径>`,一条记录占**两个** NUL 段(已实测)。
+* 因此不能无状态地按 NUL 平铺切分,遇到 `2 ` 必须额外吞掉下一段作为旧路径。
+*/
+function parseStatus(raw) {
+	const segments = raw.split("\0");
+	const files = [];
+	let head = "";
+	let detached = false;
+	let upstream = null;
+	for (let i = 0; i < segments.length; i += 1) {
+		const rec = segments[i];
+		if (!rec) continue;
+		switch (rec[0]) {
+			case "#": {
+				const sp = rec.indexOf(" ", 2);
+				const key = sp === -1 ? rec.slice(2) : rec.slice(2, sp);
+				const value = sp === -1 ? "" : rec.slice(sp + 1);
+				if (key === "branch.head") {
+					head = value;
+					detached = value === "(detached)";
+				} else if (key === "branch.ab") {
+					const m = /^\+(\d+)\s+-(\d+)$/.exec(value.trim());
+					if (m?.[1] && m[2]) upstream = {
+						ahead: Number(m[1]),
+						behind: Number(m[2])
+					};
+				}
+				break;
+			}
+			case "1": {
+				const split = splitLeading(rec, 8);
+				if (!split) break;
+				const [fields, path] = split;
+				files.push({
+					path,
+					kind: "tracked",
+					staged: asStatusCode(fields[1]?.[0]),
+					unstaged: asStatusCode(fields[1]?.[1])
+				});
+				break;
+			}
+			case "2": {
+				const split = splitLeading(rec, 9);
+				const oldPath = segments[i + 1] ?? "";
+				i += 1;
+				if (!split) break;
+				const [fields, path] = split;
+				const score = parseScore(fields[8]);
+				files.push({
+					path,
+					oldPath,
+					kind: "tracked",
+					staged: asStatusCode(fields[1]?.[0]),
+					unstaged: asStatusCode(fields[1]?.[1]),
+					...score === null ? {} : { renameScore: score }
+				});
+				break;
+			}
+			case "u": {
+				const split = splitLeading(rec, 10);
+				if (!split) break;
+				const [fields, path] = split;
+				files.push({
+					path,
+					kind: "tracked",
+					staged: asStatusCode(fields[1]?.[0]),
+					unstaged: asStatusCode(fields[1]?.[1]),
+					conflicted: true
+				});
+				break;
+			}
+			case "?": files.push({
+				path: rec.slice(2),
+				kind: "untracked",
+				staged: ".",
+				unstaged: "?"
+			});
+		}
+	}
+	return {
+		branch: {
+			head,
+			detached,
+			upstream
+		},
+		files
+	};
+}
+/**
+* 主查询的**原始输出**,不解析。
+*
+* 存在的唯一理由是 §5.7 的降级轮询:它只需要回答「变没变」,而逐字节比对原始输出
+* 既是最省的判据,也让「轮询与主查询是同一条命令」成为**构造上的事实**而不是
+* 两处各自维护的巧合 —— 后者漏个 `-uall` 不报错,只是在一个已存在的未跟踪目录里
+* 新增文件时页面不刷新(§5.2 / §5.7 的红线)。
+*
+* 比对解析后的结构也做得到,但那要么写一份深比较、要么 `JSON.stringify` 一遍,
+* 而两者都会随协议类型增删字段而静默改变灵敏度。
+*/
+async function readStatusRaw(root) {
+	return runGitStrict(STATUS_ARGS, root);
+}
+/**
+* 变更列表 + 分支状态。
+*
+* 取 `RepoInfo` 而不是两个字符串:进行中的多步操作只能从 **git 目录**下的状态文件读
+* (§5.3),而它和工作区根是两条不同的路径 —— linked worktree 与 submodule 下差得很远。
+* 两个同类型参数并排放着,调换顺序不会报错,只会让 `operation` 从此恒为空。
+*
+* 两件事并发:`git status` 是一次子进程,`readOperation` 是七个 `access`,互不依赖。
+*/
+async function readStatus(repo) {
+	const [raw, operation] = await Promise.all([readStatusRaw(repo.root), readOperation(repo.gitDir)]);
+	const status = parseStatus(raw);
+	if (operation !== void 0) status.branch.operation = operation;
+	return status;
+}
+
+//#endregion
+//#region src/server/watch/tier.ts
+/** `fs.watch` 的 `ignore` 选项自此版本可用(spec §5.7)。 */
+const IGNORE_SINCE = {
+	major: 24,
+	minor: 14,
+	patch: 0
+};
+/**
+* 强制指定档位的**内部**环境变量(spec §7:S3b1 的首个交付物)。
+*
+* 没有它,S3b2 的六条档位验收项在单机上一条都无从自查 —— 一台机器只有一个 Node
+* 版本、一个平台,而三档正是按这两者分的。它不是给用户的开关,README 不写它。
+*/
+const TIER_ENV = "DIFFTAB_WATCH_TIER";
+/** 档位环境变量的取值不合法。由 main() 收成一句话友好报错。 */
+var WatchTierError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "WatchTierError";
+	}
+};
+/**
+* `24.14.1` / `26.0.0-nightly20260101` → 三元组 + 是否带预发布标签。
+*
+* 解析不出来返回 null,调用方按「没有 `ignore`」处理 —— 见 `supportsIgnoreOption`
+* 里那段关于误判方向的说明。
+*/
+function parseNodeVersion(version) {
+	const m = /^v?(\d+)\.(\d+)\.(\d+)(-.*)?$/.exec(version.trim());
+	if (!m) return null;
+	return {
+		major: Number(m[1]),
+		minor: Number(m[2]),
+		patch: Number(m[3]),
+		prerelease: m[4] !== void 0
+	};
+}
+/**
+* 当前 Node 是否具备 `fs.watch` 的 `ignore` 选项。
+*
+* **解析失败一律按「没有」处理**,方向是刻意的:误判成没有,代价是 Linux 上退化为
+* 1.5s 轮询(功能完整,只是不即时);误判成有,代价是上面那条注释里的 ENOSPC。
+* 两种误判的代价差着一个数量级,判据不确定时只能倒向便宜的那一侧。
+*
+* 预发布标签按 semver 的规矩算作**低于**同版本正式版(`24.14.0-rc.1 < 24.14.0`):
+* 那正是选项刚合入、行为还可能变的窗口。
+*/
+function supportsIgnoreOption(nodeVersion) {
+	const v = parseNodeVersion(nodeVersion);
+	if (!v) return false;
+	if (v.major !== IGNORE_SINCE.major) return v.major > IGNORE_SINCE.major;
+	if (v.minor !== IGNORE_SINCE.minor) return v.minor > IGNORE_SINCE.minor;
+	if (v.patch !== IGNORE_SINCE.patch) return v.patch > IGNORE_SINCE.patch;
+	return !v.prerelease;
+}
+/**
+* 档位判定(spec §5.7 的三档表)。
+*
+* - **A**:有 `ignore`,三端通用 —— Linux 上是注册前跳过,正是配额问题的官方解法
+* - **B**:没有 `ignore`,但在 macOS / Windows 上走原生 FSEvents / `ReadDirectoryChangesW`,
+*   单句柄监听整棵树,本就没有配额问题,回调里自己过滤即可
+* - **C**:没有 `ignore` 且在 Linux 上 —— **不建递归 watch**,工作区改动走轮询
+*/
+function detectTier(nodeVersion, platform) {
+	if (supportsIgnoreOption(nodeVersion)) return "A";
+	return platform === "linux" ? "C" : "B";
+}
+/**
+* 实际生效的档位:环境变量优先,否则按运行时判定。
+*
+* **取值不合法时抛错而不是退回自动判定**:`DIFFTAB_WATCH_TIER=b` 那种手滑,退回
+* 自动判定的话在本机上多半照样给出 B 档,于是「我验过 B 档了」这个结论建立在
+* 一次根本没生效的强制指定上 —— 而 S3b2 的六条验收项全都压在这个变量上。
+*/
+function forcedTier(env) {
+	const forced = env[TIER_ENV];
+	if (forced === void 0 || forced.trim() === "") return null;
+	const tier = forced.trim().toUpperCase();
+	if (tier !== "A" && tier !== "B" && tier !== "C") throw new WatchTierError(`${TIER_ENV} must be one of A, B, C — got ${JSON.stringify(forced)}.`);
+	return tier;
+}
+function resolveTier(env = process.env, nodeVersion = process.versions.node, platform = process.platform) {
+	return forcedTier(env) ?? detectTier(nodeVersion, platform);
+}
+/**
+* 该档位下**工作区通路**的既定形态(spec §5.12 的 `WatchState.mode`)。
+*
+* C 档一开始就以轮询为工作区通路,A / B 档则是原生监听。**它只是「还没起监听时
+* 答什么」**:监听懒起(见 http/server.ts),起了之后真实取值由 `WatchHandle.mode`
+* 给 —— A / B 档运行中落到轮询兜底时,那一侧会翻成 `polling`。
+*/
+function initialMode(tier) {
+	return tier === "C" ? "polling" : "native";
+}
+/**
+* 强制指定 A 档、但这个 Node 根本没有 `ignore` 时的一句提醒(没有则返回 null)。
+*
+* **不是报错**:「三档均可通过内部环境变量强制指定」是 §6 已经勾掉的验收项,
+* 在 Node 22 上拒绝启动会把它推翻,而 macOS / Windows 上强制 A 档去看别的行为
+* 也是正当用法。但沉默同样不行 —— Node 对未知选项是**静默忽略**,于是这次
+* 「A 档」跑的是一个**没有任何过滤的递归 watch**:在 Linux 上那正是耗尽
+* `fs.inotify.max_user_watches` 的那条路,而结论会写成「我验过 A 档了」。
+*/
+function forcedTierWarning(env = process.env, nodeVersion = process.versions.node) {
+	if (forcedTier(env) !== "A" || supportsIgnoreOption(nodeVersion)) return null;
+	const since = `${IGNORE_SINCE.major}.${IGNORE_SINCE.minor}.${IGNORE_SINCE.patch}`;
+	return `${TIER_ENV}=A on Node ${nodeVersion}: fs.watch has no "ignore" option before ${since}, so the recursive watch runs unfiltered — this is not tier A.`;
+}
+
+//#endregion
+//#region src/server/watch/ignore.ts
+/**
+* 路径任一段命中即忽略。
+*
+* `.git` 在集合里**与档位无关**:工作区那条递归 watch 绝不能进 `.git`(一次 gc 就是
+* 几万个条目),`.git` 侧另有目录级非递归 watch 盯着(见 watcher.ts)。
+*/
+const IGNORE_NAMES = /* @__PURE__ */ new Set([
+	"node_modules",
+	".git",
+	"dist",
+	"target",
+	".next",
+	"build"
+]);
+/** 路径分隔符两种都切:Windows 的原生 watcher 给的是反斜杠分隔的相对路径。 */
+const SEPARATOR = /[\\/]/;
+/**
+* 大小写归一,对齐 `ignore` 内部的 `nocase: isWindows || isMacOS`。**不导出**:
+* 它只有 `createIsIgnored` 一个消费者,而多一个入口就多一份会跟着漂的契约。
+*
+* Linux 上**原样返回**:那里的文件系统区分大小写,`Node_Modules` 与 `node_modules`
+* 是两个不同的目录,归一等于把一个用户真的想看的目录悄悄屏蔽掉。
+*/
+function caseFold(segment, platform) {
+	return platform === "win32" || platform === "darwin" ? segment.toLowerCase() : segment;
+}
+/**
+* 造一个绑定平台的匹配器。**平台可注入是为了让三端的归一行为都能在一台机器上验**
+* —— 与 `DIFFTAB_WATCH_TIER` 同一个理由(§5.7)。
+*
+* 收到的是**相对被监听目录的路径**(A 档 Linux 侧是遍历到的条目,A 档 macOS/Windows
+* 与 B 档是事件路径),不是绝对路径 —— 传绝对路径进来也能工作,只是仓库自身若躺在
+* 某个叫 `build` 的目录下就会整片被忽略,所以调用方不该那么用。
+*/
+function createIsIgnored(platform = process.platform) {
+	return (path) => path.split(SEPARATOR).some((segment) => IGNORE_NAMES.has(caseFold(segment, platform)));
+}
+/** 当前平台的那一份。A 档传给 `ignore`、B 档在回调最前面调,是**同一个函数**。 */
+const isIgnored = createIsIgnored();
+
+//#endregion
+//#region src/server/watch/watcher.ts
+/**
+* 事件合并窗口(spec §5.7 建议 100-200ms)。
+*
+* **在 Linux 上这是必需项而非优化项**:用户态递归实现初次遍历目录树时会对遍历到的
+* 每个条目 emit 一次事件,启动瞬间即产生一波与实际变更无关的风暴。`.git` 侧同样需要:
+* 一条 `git commit` 会连着写 index.lock、index、COMMIT_EDITMSG、HEAD 的 reflog、
+* refs/heads/<分支>,五六个事件是常态。
+*/
+const DEBOUNCE_MS = 150;
+/** 降级轮询的周期(spec §5.7「1.5s 轮询」)。C 档的工作区通路也是它。 */
+const POLL_MS = 1500;
+/**
+* **原生档(A / B)的低频安全轮询周期**(spec §5.7)。
+*
+* 它补的是一个没有任何信号的缺口:Linux 上 inotify 配额在**遍历途中**耗尽时,Node
+* 一次都不 emit(2026-08-18 实测,推翻了此前的源码推断,见 §10)—— 没轮上注册的那些
+* 目录里,改一个**启动前就存在**的文件从此静默丢失,`mode` 还一直说 `native`。
+* 原生监听少报了什么是没法从监听那一侧知道的,只有拿 status 输出本身去比才看得见。
+*
+* **取 30s 而不是 1.5s**:§6 要求「原生监听模式下空闲 CPU 接近零」,一次 status 几十
+* 毫秒,30s 一拍的占空比是千分之几;代价是那个病态场景下最坏 30s 的滞后。
+*/
+const SAFETY_POLL_MS = 3e4;
+/**
+* `.git` 下需要盯的目录清单。
+*
+* **一律是目录,绝不是单个文件**:Linux / macOS 上 watch 绑的是 inode,而 git 写
+* `HEAD` / `index` 走的是「写临时文件 + 原子 rename」,新文件是新 inode,对文件建的
+* watch 从此静默失效(spec §5.7)。
+*
+* **绝不递归、更绝不进 `objects`**:一次 gc 就是几万个条目,既是配额灾难,也会把
+* 与展示无关的写入变成事件风暴。清单之所以短得像不够用,是因为主力其实是 `gitDir`
+* 本身 —— 提交写 `index` 与 `COMMIT_EDITMSG`、切分支写 `HEAD`、fetch 写 `FETCH_HEAD`,
+* 全都直接落在它下面。`refs/` 那两条是补 `refs/heads/<分支>` 这种一层深的更新,
+* 属于锦上添花;`refs/heads/feature/x` 这类嵌套分支名照样只由 `index` 那一路兜住,
+* 而那一路本来就够。
+*/
+function gitWatchDirs(gitDir) {
+	const dirs = [];
+	for (const rel of [
+		"",
+		"refs",
+		"refs/heads",
+		"refs/remotes"
+	]) {
+		const dir = rel === "" ? gitDir : join(gitDir, ...rel.split("/"));
+		try {
+			if (statSync(dir).isDirectory()) dirs.push(dir);
+		} catch {}
+	}
+	return dirs;
+}
+/**
+* 起监听。
+*
+* 关于「我们自己会不会把自己触发起来」:不会,而且这件事全靠封装层那条
+* `GIT_OPTIONAL_LOCKS=0`(§5.2 红线)。不设它的话 `git status` 会把 stat 缓存写回
+* `.git/index`,于是每次刷新都写一次 index、每次写 index 都触发一次刷新 —— 一个不报错、
+* 只是 CPU 常年 1% 的自激循环,而 status 的输出从头到尾都是对的。轮询那条路上这
+* 一点更要命:它每 1.5s 主动跑一次 status。
+*/
+function createWatcher(options) {
+	const { gitDir, repoRoot, tier, onChange, pollStatus, onDegrade, debounceMs = 150, pollMs = POLL_MS, safetyPollMs = SAFETY_POLL_MS } = options;
+	const gitWatchers = [];
+	let workspaceWatcher = null;
+	let timer = null;
+	let pollTimer = null;
+	let lastSnapshot = null;
+	let polling = false;
+	let pollLoopStarted = false;
+	let pollInFlight = false;
+	let closed = false;
+	/**
+	* **不是「每来一个事件就把窗口往后推」的那种 debounce**。
+	*
+	* 那一种在持续写入下会一直不触发 —— 而 agent 连着改几十个文件、跑一次装依赖,
+	* 正是持续写入。这里是「第一个事件起一个窗口,窗口内的后续事件被它吞掉」,
+	* 于是风暴期间也保证每 `debounceMs` 至少刷新一次。
+	*
+	* `.git` 侧、工作区侧与轮询共用这一个窗口(见文件头)。
+	*/
+	const schedule = () => {
+		if (closed || timer !== null) return;
+		timer = setTimeout(() => {
+			timer = null;
+			onChange();
+		}, debounceMs);
+		timer.unref();
+	};
+	/**
+	* 轮询一拍:取一份快照,与上一份不同就当作一次变更。
+	*
+	* 用 `setTimeout` 链而不是 `setInterval`:探针是一次 git 子进程,大仓库上未必
+	* 1.5s 内跑得完,`setInterval` 会让它们叠着跑。
+	*
+	* **首拍只建立基线,不触发刷新**(`lastSnapshot === null`):降级那一刻页面刚
+	* 重取过,再推一次纯属白刷。探针失败(仓库正被 index.lock 挡住、git 一时不可用)
+	* 也不终止轮询 —— 那是暂态,停下来就再也起不来了。
+	*/
+	const pollOnce = async () => {
+		pollInFlight = true;
+		try {
+			const snapshot = await pollStatus();
+			if (closed) {
+				pollInFlight = false;
+				return;
+			}
+			if (lastSnapshot !== null && snapshot !== lastSnapshot) schedule();
+			lastSnapshot = snapshot;
+		} catch {}
+		pollInFlight = false;
+		if (closed) return;
+		armPoll();
+	};
+	/**
+	* 排下一拍。**同一个循环的两个周期,不是两套机制**:原生档跑 `safetyPollMs`(30s)
+	* 的安全轮询,降级之后自动收到 `pollMs`(1.5s)。两个定时器各排各的话,降级那一刻
+	* 要记得把前一个停掉 —— 忘了不报错,只是从此每 30s 白跑一次 git。
+	*
+	* 每次都先清掉在等的那一拍:降级时正是靠这一下把 30s 的等待按新周期提前,否则
+	* 「已降级」之后最长还要再等 30s 才有第一次轮询,而页面上标的已经是轮询了。
+	*/
+	const armPoll = () => {
+		if (closed) return;
+		if (pollTimer !== null) clearTimeout(pollTimer);
+		pollTimer = setTimeout(() => void pollOnce(), polling ? pollMs : safetyPollMs);
+		pollTimer.unref();
+	};
+	/** 起轮询循环。**只起一次** —— 起两次就是两条链各自排各自的定时器。 */
+	const startPolling = () => {
+		if (pollLoopStarted) return;
+		pollLoopStarted = true;
+		pollOnce();
+	};
+	/**
+	* 转到轮询。**`cause` 为 null 表示这是该档位的既定形态,不是降级** —— C 档一开始
+	* 就走这条路,没有任何东西坏掉,自然也不该上报。
+	*
+	* 只有一个入口(而不是「起轮询」+「降级」两个),是因为 `polling` 这个闩只该在
+	* 一处合上:两个入口各带一份 `closed || polling` 判断时,「谁先谁后、谁的守卫
+	* 拦住了谁」就成了调用点必须自己想清楚的事,而想错的症状是多推一次降级通知。
+	*
+	* **不可逆,而且只上报一次**:一次 ENOSPC 往往连着把几个 watcher 全打下来,
+	* 每个都上报的话前端会收到一串重复的降级通知。也**不尝试恢复原生监听** ——
+	* 恢复要么靠定期重试(在真的没有配额时就是每隔一会儿遍历一次整棵树)、要么靠猜,
+	* 而轮询已经是功能完整的通路,唯一代价是 1.5s 延迟。
+	*/
+	const usePolling = (cause) => {
+		if (closed || polling) return;
+		polling = true;
+		if (!pollLoopStarted) startPolling();
+		else if (!pollInFlight) armPoll();
+		if (cause) onDegrade(cause);
+	};
+	const toError = (cause) => cause instanceof Error ? cause : new Error(String(cause));
+	/**
+	* C 档的轮询要在 `.git` 侧之前起,否则那边一个 watch 失败会被当成降级上报:
+	* stderr 打一行、再往刚连上的客户端推一个 `change`,而 `mode` 从头到尾就是
+	* `polling`,没有任何东西真的变过。
+	*
+	* 「哪档以轮询为既定形态」只此一份判据(`initialMode`)—— server 那侧在监听还没
+	* 懒起时也读它来答 `/api/state`,各写各的话两边会在加档位时静默分家。
+	*/
+	if (initialMode(tier) === "polling") usePolling(null);
+	else
+ /**
+	* 原生档的低频安全轮询(§5.7)。**直接起循环而不经 `usePolling`**:那个闩一合上
+	* 就意味着「已降级」,而这里没有任何东西坏掉 —— `mode` 必须还是 `native`,
+	* 否则页面会把一次完全正常的运行标成降级。首拍照例只建立基线。
+	*/
+	startPolling();
+	for (const dir of gitWatchDirs(gitDir)) {
+		/**
+		* **只有 `gitDir` 自己那条算主力**(见 gitWatchDirs 的注释):提交写 `index` 与
+		* `COMMIT_EDITMSG`、切分支写 `HEAD`、fetch 写 `FETCH_HEAD`,全都直接落在它下面。
+		* `refs/` 那两条是锦上添花,它们失败(权限、网络盘)不值得把整个工具**不可逆地**
+		* 拖进轮询 —— 那样 UI 会永远标着「轮询刷新」、进程永远每 1.5s 起一次 git,
+		* 而实际上什么都没坏。
+		*/
+		const primary = dir === gitDir;
+		try {
+			/**
+			* **不传 `recursive`**(见 gitWatchDirs 的注释);`persistent: false` 是说
+			* 监听不吊住事件循环。
+			*
+			* **filename 一概不看**。它可能为 null(§5.7),而这几个目录里的任何写入都
+			* 值得刷新一次:非递归就是真的非递归 —— macOS 已实测(2026-08-11,见 spec §10),
+			* Linux 的 inotify 与 Windows 的 `bWatchSubtree=FALSE` 按机制如此 —— 于是
+			* `objects/` 的海量写入根本到不了这里,没有需要按名字排除的东西。曾按
+			* 「macOS 会漏过来」加过一个顶层段过滤,那是把**建流窗口的补报**(建流前一刻的
+			* 写入会被补进来一两条)误读成了嵌套事件。
+			*/
+			const w = watch(dir, { persistent: false }, () => schedule());
+			w.on("error", (cause) => {
+				/**
+				* 出错的 watcher 已经不再送事件了(Node 在 emit 之前就把 handle 关了),
+				* 留在数组里只会让 `size` 虚高 —— 而 `size` 正是调用方判断「`.git` 侧还
+				* 活着吗」的唯一依据。虚高的那份不会报错,只是判据从此对着一个空壳返回
+				* 「还活着」。
+				*/
+				const at = gitWatchers.indexOf(w);
+				if (at !== -1) gitWatchers.splice(at, 1);
+				if (!closed && primary) usePolling(cause);
+			});
+			gitWatchers.push(w);
+		} catch (cause) {
+			if (primary) usePolling(toError(cause));
+		}
+	}
+	/**
+	* 工作区侧,按档位分(§5.7 的三档表)。
+	*
+	* **C 档一个递归 watch 都不建**:Node 在 Linux 上的递归实现是用户态遍历,对遍历到的
+	* 每个**普通文件**也注册一个 inotify watch,monorepo 下足以耗尽
+	* `fs.inotify.max_user_watches` —— 之后整机所有依赖 inotify 的工具(包括用户自己的
+	* 编辑器)开始报 ENOSPC。那是本工具唯一可能对用户机器造成的外部副作用。
+	*/
+	if (tier !== "C") try {
+		const handler = (_event, filename) => {
+			/**
+			* **B 档的过滤必须在这里,也就是合并窗口之前**(§5.7 红线)。放在窗口之后
+			* 等于让 `node_modules` 的写入噪声照样把窗口顶开、触发无谓刷新 —— 而
+			* §6 那条「`node_modules` 的嵌套子目录里批量写文件不触发刷新」正是钉这件事。
+			*
+			* A 档不在这里过滤:`ignore` 已经过滤过了(Linux 上还是**注册前跳过**,
+			* 那才是配额问题的解法)。
+			*
+			* `filename` 可能为 null(§5.7,Node 文档载明即便在支持的平台上也不保证提供),
+			* 那时**放行**:漏刷一次比多刷一次糟得多。
+			*/
+			if (tier === "B" && typeof filename === "string" && isIgnored(filename)) return;
+			schedule();
+		};
+		const w = watch(repoRoot, tier === "A" ? {
+			recursive: true,
+			persistent: false,
+			ignore: isIgnored
+		} : {
+			recursive: true,
+			persistent: false
+		}, handler);
+		w.on("error", (cause) => {
+			/**
+			* **必须显式 `close()`,不能只把引用丢掉。**
+			*
+			* 原生 watcher(macOS / Windows,以及非递归那条)确实在 emit 之前就关了自己,
+			* 但 Linux 的**用户态递归实现**不是:核对 `internal/fs/recursive_watch.js`,
+			* `#watchFolder` 的 catch 里只有一句 `this.emit('error', …)`,已经注册的那一
+			* 大批 inotify watch 全都还在,只有显式 `close()` 才放得掉。丢掉引用等于
+			* 让它们活到进程结束 —— 而这条路径最典型的触发原因**正是 inotify 配额耗尽**,
+			* 那时候还占着一堆配额不放,伤的是用户整机的其他工具。
+			*/
+			w.close();
+			workspaceWatcher = null;
+			if (!closed) usePolling(cause);
+		});
+		workspaceWatcher = w;
+	} catch (cause) {
+		usePolling(toError(cause));
+	}
+	return {
+		get size() {
+			return gitWatchers.length;
+		},
+		get mode() {
+			return polling ? "polling" : "native";
+		},
+		close() {
+			closed = true;
+			if (timer !== null) {
+				clearTimeout(timer);
+				timer = null;
+			}
+			if (pollTimer !== null) {
+				clearTimeout(pollTimer);
+				pollTimer = null;
+			}
+			for (const w of gitWatchers) w.close();
+			gitWatchers.length = 0;
+			workspaceWatcher?.close();
+			workspaceWatcher = null;
+		}
+	};
+}
+
+//#endregion
+//#region src/server/http/assets.ts
+/**
+* 产物目录。
+*
+* 口径是**打包后**的位置:`dist/server/main.js` → `dist/web/`。本文件在 src 下的
+* 相对位置与此无关 —— 它只作为 tsdown 的输入存在,运行时永远是那个单文件 ESM。
+*/
+const WEB_ROOT = new URL("../web/", import.meta.url);
+const ASSETS = /* @__PURE__ */ new Map([
+	["/", {
+		file: "index.html",
+		contentType: "text/html; charset=utf-8"
+	}],
+	["/index.html", {
+		file: "index.html",
+		contentType: "text/html; charset=utf-8"
+	}],
+	["/app.js", {
+		file: "app.js",
+		contentType: "text/javascript; charset=utf-8"
+	}],
+	["/app.css", {
+		file: "app.css",
+		contentType: "text/css; charset=utf-8"
+	}]
+]);
+/**
+* 读过一次就留在内存里。
+*
+* `dist/web/` 在进程生命周期内不会变(产物由构建产生,服务端不监听它),而所有响应
+* 都带 `Cache-Control: no-store`,浏览器那侧也不缓存 —— 不留的话每次刷新都要把三个
+* 文件重新读一遍磁盘。三份加起来两百多 KB,常驻的代价可以忽略。
+*/
+const cache = /* @__PURE__ */ new Map();
+async function readAsset(asset) {
+	const cached = cache.get(asset.file);
+	if (cached) return cached;
+	const buffer = await readFile(fileURLToPath(new URL(asset.file, WEB_ROOT)));
+	cache.set(asset.file, buffer);
+	return buffer;
+}
+
+//#endregion
+//#region src/server/http/idle.ts
+/** 宽限期。取 30-60s 区间中值(spec §5.8)。 */
+const IDLE_EXIT_MS = 45e3;
+/** 内部环境变量,名字定在 spec §5.8。不是给用户的开关,不进 `--help` 与 README。 */
+const IDLE_ENV = "DIFFTAB_IDLE_MS";
+var IdleConfigError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "IdleConfigError";
+	}
+};
+/**
+* 读宽限期。
+*
+* **取值不合法即启动失败,不退回默认的 45s** —— 与 §5.7 的 `DIFFTAB_WATCH_TIER`
+* 同一条理由:退回时手滑写错的那次照样启动成功、照样跑出一个看着合理的行为,
+* 于是「我验过空闲退出了」建立在一次根本没生效的强制指定上(那条用例会等满 45s
+* 而不是它以为的 800ms,表现为超时,读起来像产品坏了)。
+*/
+function resolveIdleMs(env = process.env) {
+	const raw = env[IDLE_ENV];
+	if (raw === void 0 || raw === "") return IDLE_EXIT_MS;
+	const parsed = Number(raw);
+	if (!Number.isFinite(parsed) || parsed <= 0) throw new IdleConfigError(`${IDLE_ENV} must be a positive number of milliseconds, got "${raw}"`);
+	return parsed;
+}
+function createIdleWatchdog(options) {
+	const { idleMs, hasClients, onIdle } = options;
+	let timer = null;
+	let stopped = false;
+	const disarm = () => {
+		if (timer === null) return;
+		clearTimeout(timer);
+		timer = null;
+	};
+	return {
+		touch() {
+			disarm();
+			if (stopped || hasClients()) return;
+			timer = setTimeout(() => {
+				timer = null;
+				/**
+				* **落地前再问一次**。定时器排队与回调执行之间隔着整个事件循环的这一圈,
+				* 同一圈里完全可能刚接进一个 SSE 连接;而这个判断错了的症状是「用户正开着
+				* 页面,进程自己没了」—— 比多活 45 秒糟得多。
+				*/
+				if (stopped || hasClients()) return;
+				onIdle();
+			}, idleMs);
+			/**
+			* **计时器不是进程活着的理由**,HTTP server 的监听句柄才是(与 sse.ts 的心跳、
+			* watcher 的合并窗口同一条)。不 unref 的话,close() 之后漏了 stop() 就会把
+			* 进程多吊住一个宽限期,而那种残留最难看见。
+			*/
+			timer.unref();
+		},
+		stop() {
+			stopped = true;
+			disarm();
+		}
+	};
+}
+
+//#endregion
+//#region src/server/http/security.ts
+/** 服务只绑这个地址。Host 白名单里的两个名字都指向它。 */
+const BIND_HOST = "127.0.0.1";
+const ALLOWED_HOSTNAMES = ["127.0.0.1", "localhost"];
+/**
+* cookie 名带上端口。
+*
+* cookie 的作用域是 host 而非 origin,**不隔离端口**(spec §5.9):同机另一个监听
+* `127.0.0.1:<其他端口>` 的服务同样会收到我们的 cookie,反过来它设的同名 cookie
+* 也会盖掉我们的。名字里带端口,两个 difftab 实例(不同仓库、不同端口)才能
+* 在同一个浏览器里共存。
+*/
+function cookieName(port) {
+	return `difftab_token_${port}`;
+}
+/** 会话 token 的秘密部分。进程生命周期内持续有效,以支持页面刷新与多标签。 */
+function createSecret() {
+	return randomBytes(32).toString("base64url");
+}
+/**
+* token 形如 `<port>.<secret>`。
+*
+* 端口写进 token 本身,是为了让服务端校验时**一并绑定校验本次会话的端口**
+* (spec §5.9 第 3 条):cookie 会泄漏给本机其他 localhost 服务,带上端口后
+* 那份 token 在别处无法复用。
+*/
+function composeToken(port, secret) {
+	return `${port}.${secret}`;
+}
+/**
+* 打印给用户、也拿去拉起浏览器的那个 URL。
+*
+* **只此一处**:探活复用命中时,是**另一个进程**按注册表里的 port + token 重新拼出
+* 同一个 URL 交给浏览器(§5.8)。两处各拼一遍的话,哪天 token 的落地方式变了
+* (换 query 名、换编码),复用那条路会拼出一个 403 的链接 —— 而它平时不走,
+* 谁也不会先注意到。
+*/
+function sessionUrl(port, token) {
+	return `http://${BIND_HOST}:${port}/?token=${encodeURIComponent(token)}`;
+}
+/**
+* 第 1 道:**校验 `Host` 头**。这才是 DNS rebinding 的正面防御 —— token 挡不住
+* 同源判定本身,rebinding 的攻击页面把自己的域名重绑到 127.0.0.1 后,浏览器
+* 认为它与本服务同源,而它发出的请求 `Host` 是攻击者的域名。
+*/
+function isHostAllowed(host, port) {
+	if (!host) return false;
+	return ALLOWED_HOSTNAMES.some((name) => host === `${name}:${port}`);
+}
+/**
+* 第 2 道:**校验 `Origin`**。非空且不等于自身则拒。
+*
+* 空是正常的:同源的导航与 GET fetch 本来就不带 Origin。`null`(沙箱化 iframe、
+* 跨源重定向)是非空值,按不匹配处理 —— 那正是要挡的东西。
+*/
+function isOriginAllowed(origin, port) {
+	if (!origin) return true;
+	return ALLOWED_HOSTNAMES.some((name) => origin === `http://${name}:${port}`);
+}
+/** 从 `Cookie` 头里取出本会话的 token。 */
+function readCookieToken(header, port) {
+	if (!header) return null;
+	const wanted = cookieName(port);
+	for (const part of header.split(";")) {
+		const eq = part.indexOf("=");
+		if (eq === -1) continue;
+		if (part.slice(0, eq).trim() === wanted) return part.slice(eq + 1).trim();
+	}
+	return null;
+}
+/** 定长比较。长度不同直接判否 —— 长度本身不是秘密。 */
+function tokensMatch(presented, expected) {
+	if (!presented) return false;
+	const a = Buffer.from(presented, "utf8");
+	const b = Buffer.from(expected, "utf8");
+	if (a.length !== b.length) return false;
+	return timingSafeEqual(a, b);
+}
+/**
+* 第 3 道之外的公共响应头。
+*
+* CSP 的后三个指令**不回退到 `default-src`**,不显式写就等于没设(spec §5.9 / §10):
+* `'none'` 一并挡掉被 iframe 嵌套、`<base>` 改写相对 URL 与表单外发。
+* 不开 `'unsafe-inline'` 是 §5.11 构建链路顺带解锁的 —— 产物是独立的 .js / .css、
+* 页面无内联脚本,才有条件不开。
+*/
+const SECURITY_HEADERS = {
+	"Cache-Control": "no-store",
+	"X-Content-Type-Options": "nosniff",
+	"Content-Security-Policy": [
+		"default-src 'none'",
+		"script-src 'self'",
+		"style-src 'self'",
+		"connect-src 'self'",
+		"img-src 'self' data:",
+		"frame-ancestors 'none'",
+		"base-uri 'none'",
+		"form-action 'none'"
+	].join("; ")
+};
+/**
+* 把 token 落成 cookie 的 Set-Cookie 值。
+*
+* `HttpOnly; SameSite=Strict` + 随后 302 掉 query,避免 token 长期滞留在浏览器
+* 历史、地址栏和日志中(spec §5.9)。不设 `Secure` —— 那会让 http://127.0.0.1
+* 上的 cookie 直接不生效。
+*/
+function tokenCookie(port, token) {
+	return `${cookieName(port)}=${token}; Path=/; HttpOnly; SameSite=Strict`;
+}
+
+//#endregion
+//#region src/server/shared/protocol.ts
+/**
+* 服务端 SSE 心跳周期(spec §5.8「服务端 SSE 心跳约 15s」)。
+*
+* **它是协议的一部分,所以定在这里而不是 http/sse.ts**:后端拿它当发送周期,前端
+* 拿它当「对端还在」的判据(`web/state/events.ts` 的 `STALE_MS` 由它推出来)。两边
+* 各写一个 15000,改周期时只改一边不会报错、也没有任何用例会红 —— 前端的死连接
+* 判定就此静默失准,而症状只是「有时候刷不出来」。
+*/
+const HEARTBEAT_MS = 15e3;
+
+//#endregion
+//#region src/server/http/sse.ts
+/**
+* 一条 SSE 消息的线格式。
+*
+* `data` 一律是一行 JSON:多行正文要逐行加 `data: ` 前缀,而正文里一旦出现换行
+* (将来带上文件名之类)就会静默变成半条消息。`JSON.stringify` 保证不含裸换行。
+*/
+function formatEvent(name, data) {
+	return `event: ${name}\ndata: ${JSON.stringify(data)}\n\n`;
+}
+function createSseChannel({ heartbeatMs = HEARTBEAT_MS, onChange } = {}) {
+	const clients = /* @__PURE__ */ new Set();
+	const send = (name, data) => {
+		const chunk = formatEvent(name, data);
+		for (const client of clients) try {
+			client.write(chunk);
+		} catch {
+			/**
+			* **真正把死连接摘出去的不是这里**,是端点上的 `'close'` / `'error'` 监听器:
+			* `ServerResponse.write()` 对已结束或已销毁的响应不会同步抛,失败是异步的。
+			* 这层 catch 只保证一个客户端写炸了不会让这一轮广播半路夭折 —— 后面的连接
+			* 照样收得到。
+			*/
+			clients.delete(client);
+		}
+	};
+	const heartbeat = setInterval(() => send("heartbeat", {}), heartbeatMs);
+	heartbeat.unref();
+	return {
+		add(client) {
+			clients.add(client);
+			onChange?.();
+		},
+		remove(client) {
+			clients.delete(client);
+			onChange?.();
+		},
+		get size() {
+			return clients.size;
+		},
+		send,
+		close() {
+			clearInterval(heartbeat);
+			for (const client of clients) try {
+				client.end();
+			} catch {}
+			clients.clear();
+		}
+	};
+}
+
+//#endregion
+//#region src/server/http/server.ts
+/**
+* 错误信息不含绝对路径(spec §5.12 / §5.9)。
+*
+* git 的 fatal 文本里经常带着完整仓库路径,原样回给页面就把本机目录结构泄漏进了
+* 一个任何本地页面都可能读到的响应体。
+*/
+function sanitizeMessage(message, repoRoot) {
+	const home = homedir();
+	let out = message.split(repoRoot).join("<repo>");
+	if (home) out = out.split(home).join("~");
+	return out.split("\n")[0]?.trim() ?? "";
+}
+function send(res, status, body, contentType) {
+	const payload = typeof body === "string" ? Buffer.from(body, "utf8") : body;
+	res.writeHead(status, {
+		...SECURITY_HEADERS,
+		"Content-Type": contentType,
+		"Content-Length": payload.byteLength
+	});
+	res.end(payload);
+}
+function sendJson(res, status, body) {
+	send(res, status, JSON.stringify(body), "application/json; charset=utf-8");
+}
+async function startServer(repo, options = {}) {
+	/**
+	* 出站错误一律经此发出,**sanitize 就做在这里**。
+	*
+	* 早先只在兜底的 500 分支上过一次 sanitizeMessage,于是「响应体不含绝对路径」这条
+	* 不变式实际挂在「以后新增的错误消息恰好都不带路径」上 —— 那不是不变式,是巧合。
+	* 放在唯一出口上,新增分支自动被覆盖(spec §5.12)。
+	*/
+	const sendError = (res, status, code, message) => {
+		sendJson(res, status, { error: {
+			code,
+			message: sanitizeMessage(message, repo.root)
+		} });
+	};
+	const secret = createSecret();
+	let token = "";
+	let port = 0;
+	/**
+	* 档位在**启动时**定,不等第一个订阅者。
+	*
+	* `/api/state` 里就带着它(§5.12),而那个请求先于任何 SSE 连接到达;更要紧的是
+	* `DIFFTAB_WATCH_TIER` 写错时要在启动那一刻响亮地失败,而不是等到某次订阅。
+	* 判定本身是纯计算(读 `process.versions.node` 与 `process.platform`),不落在
+	* §6 的 300ms 冷启动预算上。
+	*/
+	const tier = resolveTier();
+	const tierWarning = forcedTierWarning();
+	if (tierWarning) process.stderr.write(`difftab: ${tierWarning}\n`);
+	/**
+	* 通道与空闲计时器互相接线:连接数一变(add / remove)就 `touch` 一次。
+	* 端点那侧因此**不必记得**在断连时重新武装 —— 见 sse.ts 的 `onChange`。
+	*/
+	const events = createSseChannel({ onChange: () => idle.touch() });
+	/**
+	* 空闲退出的计时器(spec §5.8)。**判据是 SSE 连接数,但任何通过校验的请求都重置
+	* 计时** —— 连接数是正面判据,而它在两种情形下同样是 0:刚被探活复用、浏览器
+	* 还在启动的那几秒,以及页面活着但 SSE 被中间层悄悄回收了。两者取并集,退出条件
+	* 因此严格弱于「连接数为 0 持续 45s」,只会晚退不会早退。
+	*
+	* `resolveIdleMs()` 在这里(listen 之前)读环境变量:写错的取值要在启动那一刻
+	* 响亮地失败,而不是等到 45 秒后什么都没发生。
+	*/
+	const idle = createIdleWatchdog({
+		idleMs: resolveIdleMs(),
+		hasClients: () => events.size > 0,
+		onIdle: () => options.onIdle?.()
+	});
+	/**
+	* 监听**懒起**:第一个 SSE 订阅者到了才建,起了就一直留到关服务。
+	*
+	* 两头都是有理由的。懒起是因为 §6 的冷启动门禁量的是「监听成功并打印 URL」,而
+	* S3b2 的 A/B 档要在 repoRoot 上建递归 watch —— Linux 上那是用户态遍历整棵树,
+	* 大仓库里足以把 300ms 预算一口吃掉,而此刻还没有任何人在等变更通知。
+	* 不随最后一个订阅者关掉,则是因为刷新页面 = 断开再连,那会让上面那趟遍历
+	* 每刷新一次重来一遍;空闲着的原生 watch 本身开销接近零(§6 的资源占用项)。
+	*/
+	let watcher = null;
+	const ensureWatcher = () => {
+		if (watcher !== null) return;
+		watcher = createWatcher({
+			gitDir: repo.gitDir,
+			repoRoot: repo.root,
+			tier,
+			onChange: () => events.send("change", {}),
+			/**
+			* 轮询探针。**注入而不是让 watch/ 自己去调 git**:git 子进程只许出现在
+			* server/git(§5.0 不变式 1),而 §5.0 的依赖方向里也没有 watch → git 这条边。
+			* 传进去的是主查询本身(`readStatusRaw` 用的就是 `STATUS_ARGS`),于是「轮询
+			* 与主查询逐字相同」这条红线在这里是**一处赋值**而不是两处各自维护的巧合。
+			* 拦住它的不是类型(签名只是 `() => Promise<string>`),是这个唯一的注入点
+			* 加上冒烟里那条「C 档在已存在的未跟踪目录里新增文件要推出 change」。
+			*
+			* **已知的覆盖边界**:`/api/state` 里的 `operation`(§5.3)不来自 status 输出,
+			* 所以这条探针看不见它。三档都在 `gitDir` 上建了非递归 watch,`MERGE_HEAD` /
+			* `rebase-merge/` 的增删就落在那儿,正常情况下照样推得出 change;只有**那条
+			* watch 自己也失败、整体落到轮询**之后,一次「只动 git 目录、不动 HEAD 也不动
+			* 工作区」的操作(实际上只有 `rebase --quit` 这一类)才会让标注停在旧值上。
+			* 不为它把探针拆成两个来源:那会让「轮询与主查询是同一条命令」不再是构造上的
+			* 事实,而换来的是一个交集极窄的窗口。
+			*/
+			pollStatus: () => readStatusRaw(repo.root),
+			/**
+			* 降级为轮询(§5.7 的兜底)。**推一个 `change` 是必需的**:`mode` 只在
+			* `/api/state` 里,前端不重取就看不到降级 —— 而它自己无从推断这件事(§5.12),
+			* 于是页面会一直标着「原生监听」直到下一次真的有文件变更。
+			*/
+			onDegrade: (cause) => {
+				process.stderr.write(`difftab: file watching degraded — ${sanitizeMessage(cause.message, repo.root)}\n`);
+				events.send("change", {});
+			}
+		});
+	};
+	/**
+	* 当前的监听状态(§5.12 的 `WatchState`)。
+	*
+	* **每次请求现算,不是启动时算一次**:降级发生在运行中,而算一次存起来的那份
+	* 不会报错,只是从此永远说「原生监听」。监听懒起(见上),还没起来时按档位的
+	* 既定形态答 —— C 档从第一份 `/api/state` 起就该是 `polling`。
+	*/
+	const currentWatchState = () => ({
+		mode: watcher?.mode ?? initialMode(tier),
+		tier
+	});
+	const handle = async (req, res) => {
+		if (!isHostAllowed(req.headers.host, port)) {
+			sendError(res, 403, "forbidden", "forbidden");
+			return;
+		}
+		if (!isOriginAllowed(req.headers.origin, port)) {
+			sendError(res, 403, "forbidden", "forbidden");
+			return;
+		}
+		const url = new URL(req.url ?? "/", `http://${BIND_HOST}:${port}`);
+		const fromQuery = url.searchParams.get("token");
+		if (fromQuery !== null) {
+			if (!tokensMatch(fromQuery, token)) {
+				sendError(res, 403, "forbidden", "forbidden");
+				return;
+			}
+			idle.touch();
+			url.searchParams.delete("token");
+			res.writeHead(302, {
+				...SECURITY_HEADERS,
+				"Set-Cookie": tokenCookie(port, token),
+				Location: `${url.pathname}${url.search}`,
+				"Content-Length": 0
+			});
+			res.end();
+			return;
+		}
+		if (!tokensMatch(readCookieToken(req.headers.cookie, port), token)) {
+			sendError(res, 403, "forbidden", "forbidden");
+			return;
+		}
+		/**
+		* 到这里才算「有人在」,**三道校验之前不算**(上面那个 302 分支同理:token 对了
+		* 才 touch)。放在函数开头看起来更省事,代价是本机任何一个端口扫描器都能无限期
+		* 续命一个该退的进程 —— 而 §5.8 的承诺是「不留后台常驻进程」。
+		*/
+		idle.touch();
+		/**
+		* 只读工具不需要任何非幂等端点(spec §5.12)。
+		*
+		* **必须留在三道校验之后,不得挪回函数开头** —— 理由(泄漏服务存在性)见 spec §5.9
+		* 第 4 条,验收项 §6 `[S5]`。副作用是上面那个 query token 分支也排在它前面:带合法
+		* token 的非幂等请求会先被 302 换成 cookie 而不是 405。它已经过了三道校验,是取舍。
+		*/
+		if (req.method !== "GET" && req.method !== "HEAD") {
+			sendError(res, 405, "method-not-allowed", "only GET is supported");
+			return;
+		}
+		const asset = ASSETS.get(url.pathname);
+		if (asset) {
+			send(res, 200, await readAsset(asset), asset.contentType);
+			return;
+		}
+		switch (url.pathname) {
+			case "/api/state": {
+				const status = await readStatus(repo);
+				sendJson(res, 200, {
+					branch: status.branch,
+					files: status.files,
+					watch: currentWatchState()
+				});
+				return;
+			}
+			/**
+			* 探活复用的应答(spec §5.8 / §5.12)。**消费者是下一个 CLI 进程,不是前端。**
+			*
+			* 它答的是「这个端口现在还是**这个仓库**的实例吗」。光有三道校验答不了:
+			* token 不匹配只证明「不是我们这一份会话」,而端口被系统回收给另一个仓库的
+			* difftab 时,那边同样有一份合法 token —— 只不过不是我们记在注册表里的那个,
+			* 于是它会 403、被判为陈旧,正确。真正需要这个正文的是相反的一侧:200 之后
+			* 还要确认路径确实是我们这个仓库,否则「复用」会把用户带到别人的页面(§5.8
+			* 排除 pid 判活也是同一条理由)。
+			*/
+			case "/api/instance":
+				sendJson(res, 200, {
+					repoRoot: repo.root,
+					pid: process.pid
+				});
+				return;
+			case "/api/diff": {
+				const path = url.searchParams.get("path");
+				if (!path) {
+					sendError(res, 400, "bad-request", "path is required");
+					return;
+				}
+				const oldPath = url.searchParams.get("oldPath");
+				sendJson(res, 200, await readDiff(repo.root, {
+					path,
+					...oldPath ? { oldPath } : {}
+				}));
+				return;
+			}
+			/**
+			* SSE(spec §5.8 / §5.12)。**三道校验在上面已经统一走过**,这里没有例外分支 ——
+			* 「所有端点(含 SSE)统一校验」正是 §5.9 第 4 条。
+			*/
+			case "/api/events": {
+				const headers = {
+					...SECURITY_HEADERS,
+					"Content-Type": "text/event-stream; charset=utf-8",
+					Connection: "keep-alive"
+				};
+				if (req.method === "HEAD") {
+					res.writeHead(200, headers);
+					res.end();
+					return;
+				}
+				res.writeHead(200, headers);
+				res.write(": connected\n\n");
+				/**
+				* 两个监听器都必须挂在 `events.add` **之前**。
+				*
+				* `close` 覆盖全部断开路径(关标签、刷新、进程被 kill 掉对端);`error` 则是
+				* 长连接独有的一条:写向一条已经结束的响应,`write()` 不会同步抛,而是在 `res`
+				* 上**异步** emit 一个 `'error'` —— 一个零监听器的 EventEmitter 收到 `'error'`
+				* 是整个进程带着裸栈崩掉,而不是丢一条心跳。
+				*
+				* 顺序则是因为 add 之后、挂上之前的那一小段里断开的话,就再没人把它摘出去:
+				* 心跳会一直写向一条死响应,§5.8 的空闲退出也永远数不回 0。
+				*/
+				/**
+				* 断开之后**必须再 touch 一次**:计时只在 `touch()` 里起,而这是「最后一个
+				* 标签被关掉」在服务端的唯一形态。少了它,进程要等到下一个请求(而那正是
+				* 没有人再发的东西)才想起来自己已经空了 —— 症状是关完浏览器留一个永久
+				* 常驻进程,与 §6 那条验收项正相反。
+				*/
+				res.on("close", () => events.remove(res));
+				res.on("error", () => events.remove(res));
+				events.add(res);
+				/**
+				* **监听推到下一拍再起**,不在这个请求里同步建。
+				*
+				* Linux 上 A / B 档的递归 watch 是**用户态的同步遍历**(`readdirSync` +
+				* `statSync` 递归,已核对 `internal/fs/recursive_watch.js`),大仓库上要跑
+				* 几百毫秒到数秒。留在这里的话,它占住的是整条事件循环 —— 页面此刻正并发
+				* 发着 `/api/state` 与静态资源,那些请求会一起卡住,首屏因此变慢,
+				* 而症状与「监听很慢」毫无相似之处。
+				*/
+				setImmediate(ensureWatcher);
+				return;
+			}
+			default: sendError(res, 404, "not-found", "not found");
+		}
+	};
+	const server = createServer((req, res) => {
+		handle(req, res).catch((cause) => {
+			if (res.headersSent) {
+				res.destroy();
+				return;
+			}
+			if (cause instanceof DiffRequestError) {
+				sendError(res, 400, cause.code, cause.message);
+				return;
+			}
+			const detail = cause instanceof Error ? cause.message : String(cause);
+			sendError(res, 500, "internal", detail);
+		});
+	});
+	const sockets = /* @__PURE__ */ new Set();
+	server.on("connection", (socket) => {
+		sockets.add(socket);
+		socket.on("close", () => sockets.delete(socket));
+	});
+	await new Promise((resolvePromise, rejectPromise) => {
+		server.once("error", rejectPromise);
+		server.listen(0, BIND_HOST, () => {
+			server.removeListener("error", rejectPromise);
+			resolvePromise();
+		});
+	});
+	server.on("error", (cause) => {
+		process.stderr.write(`difftab: local server error — ${sanitizeMessage(cause.message, repo.root)}\n`);
+	});
+	const address = server.address();
+	if (typeof address === "string" || address === null) throw new Error("failed to determine the listening port");
+	port = address.port;
+	token = composeToken(port, secret);
+	/**
+	* **宽限期从这一刻就开始计,不等第一个客户端**(spec §5.8)。
+	*
+	* 等第一个客户端才起计时看着更稳妥,实则把「浏览器压根没拉起来」整类情形
+	* (headless、无 `xdg-open`、`--no-open` 之后用户改了主意)变成永久常驻的后台进程。
+	* 45 秒足够覆盖冷启动一个浏览器进程的 2-5s(§6)。
+	*/
+	idle.touch();
+	return {
+		port,
+		token,
+		url: sessionUrl(port, token),
+		close: () => new Promise((resolvePromise) => {
+			idle.stop();
+			watcher?.close();
+			events.close();
+			for (const socket of sockets) socket.destroy();
+			server.close(() => resolvePromise());
+		})
+	};
+}
+
+//#endregion
+//#region src/server/cli/browser.ts
+/**
+* 平台 → 命令的固定映射。**纯函数,便于测试逐条钉住**。
+*
+* Windows 那串里的空串不是笔误:它是 `start` 的窗口标题占位,少了它,带引号的 URL
+* 会被当作标题吞掉,浏览器根本不开(spec §5.1)。
+*/
+function browserCommand(platform, url) {
+	if (platform === "darwin") return {
+		command: "open",
+		args: [url]
+	};
+	if (platform === "win32") return {
+		command: "cmd",
+		args: [
+			"/c",
+			"start",
+			"",
+			url
+		]
+	};
+	return {
+		command: "xdg-open",
+		args: [url]
+	};
+}
+/**
+* CI 与冷启动测量里必须能关掉这个调用,否则每跑一次测试就弹一次浏览器(spec §5.10)。
+*
+* 这不是「为开发便利而放宽的分支」—— 它不改变任何校验,只决定要不要多起一个进程。
+*/
+function browserDisabled(env = process.env) {
+	return Boolean(env.DIFFTAB_NO_OPEN);
+}
+/**
+* 返回是否真的尝试了拉起。
+*
+* 失败(没有 `xdg-open`、headless 环境)只打印 URL 让用户自行访问,**不作为启动失败**
+* (spec §5.1)。URL 在调用本函数之前已经打印过了,所以这里什么都不用补。
+*/
+function openBrowser(url) {
+	if (browserDisabled()) return false;
+	const { command, args } = browserCommand(process.platform, url);
+	try {
+		const child = spawn(command, args, {
+			stdio: "ignore",
+			detached: true
+		});
+		child.on("error", () => {});
+		child.unref();
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+//#endregion
+//#region src/server/cli/registry.ts
+/**
+* 注册表目录。
+*
+* **绝不能写进 `.git/` 或工作区** —— 那既污染 `git status`,也实质违背零写操作承诺
+* (spec §5.8 / §10)。`os.tmpdir()` 的权限因平台而异,Linux 上是 `/tmp`(1777,
+* 同机其他用户可读),所以这里再套一层每用户私有子目录,文件本身另有 0o600。
+*/
+function registryDir() {
+	return join(tmpdir(), "difftab");
+}
+/**
+* 把仓库路径归一成注册表的键。
+*
+* 写入侧给的是 `git rev-parse --show-toplevel`,读取侧(dev proxy)给的是
+* `process.cwd()` —— **两者指向同一个目录时字面量仍可能不同**,而 hash 只认字面量:
+*   - Windows:git 给 `C:/Users/x/repo`,cwd 给 `C:\Users\x\repo`;
+*   - macOS:cwd 经符号链接进来时是 `/var/...`,git 给的是 `/private/var/...`。
+* 不归一的话 dev proxy 永远找不到正在运行的后端,症状是「后端明明起着却说没找到」。
+*
+* **探活比对仓库身份时用的也是这一份**(probe.ts):一侧是 `/api/instance` 返回的
+* `git rev-parse --show-toplevel`、另一侧是本进程的同一条命令,看着不可能不等 ——
+* 但 macOS 上 `/tmp` 与 `/private/tmp` 这类差异照样能让两个活着的实例互不相认,
+* 于是同一个仓库开出第二个进程。两处各写一份归一化,漂移是静默的。
+*/
+function normalizeRepoKey(repoRoot) {
+	const abs = resolve(repoRoot);
+	try {
+		return realpathSync.native(abs);
+	} catch {
+		return abs;
+	}
+}
+/** 文件名用仓库绝对路径的 hash,避免把路径本身暴露在一个全局可读的目录名里。 */
+function registryPath(repoRoot) {
+	const hash = createHash("sha256").update(normalizeRepoKey(repoRoot)).digest("hex").slice(0, 32);
+	return join(registryDir(), `${hash}.json`);
+}
+/**
+* 写入注册表。
+*
+* `0o600` 必须**配合 `O_EXCL` 在创建时**给出(`'wx'` + mode),而不是先建后 chmod ——
+* 后者留下一个竞态窗口,窗口里文件是可读的,而它存着本次会话的 token(spec §5.8)。
+*/
+function writeExclusive(path, payload) {
+	const fd = openSync(path, "wx", 384);
+	try {
+		writeFileSync(fd, payload);
+	} finally {
+		closeSync(fd);
+	}
+}
+function writeRegistry(entry) {
+	const path = registryPath(entry.repoRoot);
+	mkdirSync(registryDir(), {
+		recursive: true,
+		mode: 448
+	});
+	const payload = JSON.stringify(entry);
+	try {
+		writeExclusive(path, payload);
+	} catch (cause) {
+		if (cause.code !== "EEXIST") throw cause;
+		/**
+		* 走到这里说明**探活已经判过它是陈旧的**(start.ts 命中就不会再启动,更不会
+		* 写注册表),所以覆盖是对的。
+		*
+		* 保留 `O_EXCL` + 显式 unlink 而不是改成 `'w'`:两者的区别只在这个分支要不要
+		* 显式承认「我在覆盖别人的条目」。而 §5.8 那条 `0o600` 必须在创建时给出的要求
+		* 也只有 `'wx'` 满足 —— `'w'` 对已存在的文件根本不套用 mode,一次遗留的
+		* 0644 条目会被原样沿用,里面躺着本次会话的 token。
+		*/
+		unlinkSync(path);
+		writeExclusive(path, payload);
+	}
+	return path;
+}
+/**
+* 读取注册表。dev proxy(见 vite.config.ts)与探活(probe.ts)共用;读不到、或者
+* 读到一条用不了的条目,一律返回 null。
+*
+* **「这条目还能用吗」只在这里判一次**:端口得是一个真能连的端口号、token 不能是
+* 空串。放在消费侧各判各的话,两个消费者迟早对「可用」有两套定义,而分歧的表现是
+* dev proxy 与探活对同一条陈旧条目给出不同结论。
+*/
+function readRegistry(repoRoot) {
+	try {
+		const raw = readFileSync(registryPath(repoRoot), "utf8");
+		const parsed = JSON.parse(raw);
+		if (typeof parsed.token !== "string" || parsed.token === "") return null;
+		if (!Number.isInteger(parsed.port) || (parsed.port ?? 0) <= 0 || (parsed.port ?? 0) > 65535) return null;
+		return parsed;
+	} catch {
+		return null;
+	}
+}
+/** 退出时清理。只删自己写的那一条,免得把另一个实例的条目带走。 */
+function removeRegistry(repoRoot) {
+	const path = registryPath(repoRoot);
+	let raw;
+	try {
+		raw = readFileSync(path, "utf8");
+	} catch {
+		return;
+	}
+	let entry = null;
+	try {
+		entry = JSON.parse(raw);
+	} catch {}
+	if (!entry || entry.pid !== process.pid) return;
+	try {
+		unlinkSync(path);
+	} catch {}
+}
+
+//#endregion
+//#region src/server/cli/probe.ts
+/**
+* 探活超时。**不取更短**(spec §5.8)。
+*
+* 被探的实例可能正卡在 §5.7 那趟用户态递归遍历里(Linux 大仓库上几百毫秒到数秒),
+* 超时过短的代价不是慢一点,而是**给同一个仓库起了第二个进程**——正是本模块要防的
+* 那件事。反过来这 1.5s 平时根本走不到:注册表不存在时压根不探(常态,冷启动门禁
+* 不受影响),端口已死时 localhost 上的 `ECONNREFUSED` 是立即返回的。
+*/
+const PROBE_TIMEOUT_MS = 1500;
+/**
+* 正文读到这么多还没完就放弃。
+*
+* 端口可能已经归了一个完全无关的服务,而它的 `/api/instance` 可以是任何东西 ——
+* 一个流式响应会让下面那句 `body +=` 一直涨下去。上限之内,一份真正的
+* `InstanceInfo` 绰绰有余。
+*/
+const MAX_BODY_BYTES = 65536;
+/**
+* 向记录的端口要一份 `InstanceInfo`。任何不顺利一律返回 null(= 按陈旧处理)。
+*
+* **带上 token 与合规的 `Host`**:§5.9 的三道校验一视同仁,探活不是例外 ——
+* 那也正是「端口已经归了另一个仓库的 difftab」这种情形的判据:它那份 token
+* 不是我们记下的这个,于是 403、判陈旧,正确。
+*/
+function requestInstance(entry, timeoutMs) {
+	return new Promise((resolvePromise) => {
+		const req = request({
+			host: BIND_HOST,
+			port: entry.port,
+			path: "/api/instance",
+			headers: {
+				Host: `${BIND_HOST}:${entry.port}`,
+				Cookie: `${cookieName(entry.port)}=${entry.token}`
+			}
+		}, (res) => {
+			if (res.statusCode !== 200) {
+				req.destroy();
+				resolvePromise(null);
+				return;
+			}
+			/**
+			* **响应头到手之后,`req` 就不再是错误的出口了**(已在 Node 24.14.1 实测)。
+			*
+			* 此后 `req.destroy()` 与对端中途断开都只落在 `res` 上(`'aborted'` 随后
+			* `'error': ECONNRESET`),而 `IncomingMessage` 会把没人听的 `'error'` 自己
+			* 吞掉 —— 于是下面那两处 `destroy()`(超时、正文过大)既走不到 `'end'`、也走
+			* 不到 `req.on('error')`,**这个 Promise 永远不 settle**,`start.ts` 里那句
+			* `await findLiveInstance()` 就把启动整个吊死,没有任何输出。
+			*
+			* `'close'` 是 `res` 上唯一覆盖全部结局的事件;正常读完时它排在 `'end'`
+			* 之后,那时早已 resolve 过,再 resolve 一次没有作用(首次为准)。
+			*/
+			res.on("close", () => resolvePromise(null));
+			let body = "";
+			res.setEncoding("utf8");
+			res.on("data", (chunk) => {
+				body += chunk;
+				if (body.length > MAX_BODY_BYTES) {
+					req.destroy();
+					resolvePromise(null);
+				}
+			});
+			res.on("end", () => {
+				try {
+					const parsed = JSON.parse(body);
+					if (typeof parsed.repoRoot !== "string" || typeof parsed.pid !== "number") {
+						resolvePromise(null);
+						return;
+					}
+					resolvePromise({
+						repoRoot: parsed.repoRoot,
+						pid: parsed.pid
+					});
+				} catch {
+					resolvePromise(null);
+				}
+			});
+		});
+		req.on("error", () => resolvePromise(null));
+		/**
+		* 超时用 `setTimeout` 而不是 `req.setTimeout`:后者只管**socket 空闲**,
+		* 一个每 200ms 吐一个字节的第三方服务能让它永远不触发。这里要的是整次探活的
+		* 墙钟上限。
+		*
+		* **`destroy()` 之后必须自己 resolve**:响应头已经到手时,这一下的错误落在 `res`
+		* 上而不是 `req` 上(见上面那段),光 destroy 等于把超时做成了一个不生效的摆设 ——
+		* 而症状是启动整个吊死,恰好比没有超时更难看出来。
+		*/
+		const timer = setTimeout(() => {
+			req.destroy();
+			resolvePromise(null);
+		}, timeoutMs);
+		req.on("close", () => clearTimeout(timer));
+		req.end();
+	});
+}
+/**
+* 这个仓库已经有活着的实例吗?有就返回它的 URL,没有就 null。
+*
+* 命中之后调用方**不得碰注册表**:那条目是另一个进程写的,连「顺手更新一下」都不行
+* ——它退出时按 pid 只删自己的那条(registry.ts),我们改过的内容会让它留下垃圾。
+*/
+async function findLiveInstance(repoRoot, { timeoutMs = PROBE_TIMEOUT_MS } = {}) {
+	const entry = readRegistry(repoRoot);
+	if (!entry) return null;
+	const info = await requestInstance(entry, timeoutMs);
+	if (!info) return null;
+	/**
+	* **200 还不够,路径也得对得上**(spec §5.8)。
+	*
+	* 这一条挡的是「注册表条目还在,而那个端口已经被系统回收给了别的东西」——
+	* 它恰好也认得这份 token 的概率不高,但代价是把用户带到别人的页面,而这类判断
+	* 错了不会有任何东西报错。归一化复用注册表键那一份实现,理由记在那边。
+	*/
+	if (normalizeRepoKey(info.repoRoot) !== normalizeRepoKey(repoRoot)) return null;
+	return {
+		pid: info.pid,
+		url: sessionUrl(entry.port, entry.token)
+	};
+}
+
+//#endregion
+//#region src/server/cli/start.ts
+async function start(options) {
+	/**
+	* 「可以看了」的唯一出口:**stdout 的第一行是且只是 URL**,随后一行说明,最后
+	* 拉起浏览器。
+	*
+	* 复用与新起两条路各写一遍的话,只有新起那条天天在跑 —— 改了第一行的形状
+	* (加前缀、换写法)会在复用那条上静默漂走,而 `scripts/bench-startup.mjs` 与
+	* 冒烟套件的 ready 判据都压在这一行上(spec §6「ready 的口径」)。
+	*/
+	function announce(url, note) {
+		process.stdout.write(`${url}\n`);
+		process.stdout.write(`${note}\n`);
+		if (!options.noOpen) openBrowser(url);
+	}
+	const repo = await locateRepo(options.cwd);
+	/**
+	* **同一个仓库已经有实例在跑,就把用户送去那一个**(spec §5.8)。
+	*
+	* 判活是 HTTP 探活而不是 pid —— 理由在 probe.ts。命中这条路之后**什么都不写**:
+	* 不写注册表(那条目属于对面那个进程)、不装信号与 exit 处理器(装了会在本进程
+	* 退出时替对面清理掉它的条目,虽然 removeRegistry 按 pid 又挡了一道)。
+	*/
+	const existing = await findLiveInstance(repo.root);
+	if (existing) {
+		announce(existing.url, `difftab: reusing the instance already serving this repository (pid ${existing.pid}).`);
+		return;
+	}
+	const server = await startServer(repo, { 
+	/**
+	* 空闲宽限期走满(spec §5.8)。**「怎么退」归这一层**:http/ 那边只知道
+	* 「没人了」,退出码、提示语、以及退出前要不要先 close 都是启动流程的事。
+	*/
+onIdle: () => stop(0, "difftab: no tabs left — exiting.\n") });
+	writeRegistry({
+		pid: process.pid,
+		port: server.port,
+		token: server.token,
+		repoRoot: repo.root,
+		startedAt: Date.now()
+	});
+	let closing = false;
+	/**
+	* 唯一的退出路径。信号与空闲退出共用它 —— 两者完全可能撞在一起(Ctrl+C 恰好
+	* 落在宽限期走满的同一拍),各写一份的话 `server.close()` 会跑两次,第二次撞上
+	* 已经 destroy 的 socket。
+	*/
+	const stop = (code, note) => {
+		if (closing) return;
+		closing = true;
+		/**
+		* **`writeSync` 而不是 `process.stdout.write`**:后者写到**管道**时在 Windows 上
+		* 是异步的,紧跟着的 `process.exit()` 会把还在缓冲区里的内容整条丢掉(与 main.ts
+		* 那条报错同一个规避手法)。而这句提示正是自动化验证「它是自己走的、不是被
+		* kill 的」的判据,丢了之后症状是 stdout 里什么都没有。
+		*
+		* **而它得能失败**:`writeSync` 与 `process.stdout.write` 不同,读端已经走了
+		* (`difftab --no-open | head -1`)时它**抛 EPIPE**。抛在这个定时器回调里,
+		* `closing` 已经合上,于是 `server.close()` 不再执行,进程带着一屏 Node 栈以 1
+		* 退出 —— 而这条路承诺的是干净的 0。提示没打出去不是错误,是没人在听。
+		*/
+		if (note) try {
+			writeSync(1, note);
+		} catch {}
+		server.close().finally(() => {
+			process.exit(code);
+		});
+	};
+	process.on("SIGINT", () => stop(130));
+	process.on("SIGTERM", () => stop(143));
+	process.on("exit", () => removeRegistry(repo.root));
+	announce(server.url, "difftab: read-only view of this repository. Press Ctrl+C to stop.");
+}
+
+//#endregion
+//#region src/server/main.ts
+/**
+* 版本号只有 package.json 一个来源。
+*
+* 不把它硬编码在这里,也不在构建期 define 进去:硬编码会在第一次发版改号时
+* 静默漂移(`--version` 报旧号,没有任何东西会失败);构建期注入则让 `dist/` 与
+* 源码对不上、调试时更难看清。运行时读一次的代价只落在 `--version` 这条路径上。
+* dist/server/main.js → 包根的 package.json;`files` 之外 npm 总会带上它。
+*/
+function readVersion() {
+	const manifestPath = fileURLToPath(new URL("../../package.json", import.meta.url));
+	return JSON.parse(readFileSync(manifestPath, "utf8")).version;
+}
+/** 一句话友好报错,不是 Node 异常栈(spec §5.2 的启动前置检查)。 */
+function fail(message) {
+	try {
+		writeSync(2, `difftab: ${message}\n`);
+	} catch {}
+	process.exit(1);
+}
+/**
+* 读端先走了不算错误(`difftab --no-open | head -1`:用户只想要那行 URL)。
+*
+* 之后每一次写都以 EPIPE 失败,而**在 Windows 上管道写是异步的**(POSIX 上同步),
+* 失败因此以一个 `'error'` 事件到达 —— 零监听器的流收到 `'error'` 就是整个进程带着
+* 裸栈以 1 退出。已在 CI 的 windows × Node 24 档实测到:`head` 一退,紧接着那句
+* 「read-only view of this repository」就把服务打死了,而 macOS / Linux 上同一条路
+* 一声不响(见 spec §10)。
+*
+* 服务本身没坏 —— 浏览器照常用得上,45 秒没人连再自己退,所以这里只是把 EPIPE
+* 咽掉。**非 EPIPE 的错误照旧抛**:那是真出事了,不该借这条路一起被吞掉。
+*/
+function ignoreBrokenPipe(stream) {
+	stream.on("error", (cause) => {
+		if (cause.code !== "EPIPE") throw cause;
+	});
+}
+async function main(argv) {
+	ignoreBrokenPipe(process.stdout);
+	ignoreBrokenPipe(process.stderr);
+	let options;
+	try {
+		options = parseCliArgs(argv);
+	} catch (cause) {
+		if (cause instanceof CliUsageError) fail(`${cause.message}\n\n${HELP_TEXT}`);
+		throw cause;
+	}
+	if (options.help) {
+		process.stdout.write(HELP_TEXT);
+		return;
+	}
+	if (options.version) {
+		process.stdout.write(`difftab ${readVersion()}\n`);
+		return;
+	}
+	try {
+		await start({
+			cwd: process.cwd(),
+			noOpen: options.noOpen
+		});
+	} catch (cause) {
+		if (cause instanceof PreflightError || cause instanceof WatchTierError || cause instanceof IdleConfigError) fail(cause.message);
+		throw cause;
+	}
+}
+
+//#endregion
+export { main };