difftab 0.1.3 → 0.2.1

package/dist/server/main.js

@@ -5,7 +5,7 @@ import { basename, 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 { access, lstat, readFile, readdir, readlink, realpath } from "node:fs/promises";
 import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
 
 //#region src/server/cli/args.ts
@@ -53,37 +53,28 @@ function parseCliArgs(argv) {
 //#endregion
 //#region src/server/git/run.ts
 /**
-* 所有 git 调用统一注入,不留给各调用点自己记得加。
+* 所有 git 调用统一注入，不留给各调用点自己记得加。`-z` 只作用于 status / numstat 这类
+* **列表输出**，管不到 `git diff` 的补丁正文——正文里的 `diff --git` / `---` / `+++` /
+* `rename from|to` 头部行仍按 C 风格转义，而 diff2html 恰恰从这些头部行解析文件名。
 *
-* `-z` 只作用于 status / numstat 这类**列表输出**,管不到 `git diff` 的补丁正文 ——
-* 正文里的 `diff --git` / `---` / `+++` / `rename from|to` 头部行仍会按 C 风格转义
-* (已实测),而 diff2html 恰恰是从这些头部行解析文件名的。两者互补,不可相互替代。
-*
-* 注入位置必须在子命令**之前**:`-c` 是 git 的全局选项,放在子命令后面 git 不认。
+* 注入位置必须在子命令**之前**：`-c` 是 git 的全局选项，放在子命令后面 git 不认。
 */
 const GLOBAL_CONFIG = ["-c", "core.quotePath=false"];
 /**
 * 子进程环境。
 *
-* `GIT_OPTIONAL_LOCKS=0` 是只读承诺的一部分而不是性能开关:默认情况下 `git status`
-* 会顺手把刷新过的 stat 缓存写回 `.git/index`。那不改变 status 的输出,因此
-* 「前后 `git status` 比对」这类验证发现不了它(排除该做法的原因之一)。
-*
-* **把这一行删掉,只读 `.git` 那半层门禁照样全绿**(已实测):git 把 index
-* 回写当 best-effort,`.git` 不可写时它静默跳过、exit 0、stderr 全空。真正看得见
-* 的是第二层的 **B 半**——在可写的 `.git` 上前后做逐字节快照比对
-* (`test/smoke/readonly-git-dir.test.js`)。别把 B 半当成 A 半的重复给删了。
-*
-* 该变量在 git < 2.15 上不存在,设了也无害 —— 那个区间的 git 只是照旧写 index。
+* `GIT_OPTIONAL_LOCKS=0` 是只读承诺的一部分而不是性能开关：默认情况下 `git status` 会顺手
+* 把刷新过的 stat 缓存写回 `.git/index`。那不改变 status 的输出，「前后 `git status` 比对」
+* 这类验证因此发现不了它。**把这一行删掉，只读 `.git` 那半层门禁照样全绿**——git 把
+* index 回写当 best-effort,`.git` 不可写时静默跳过、exit 0、stderr 全空；真正看得见的是
+* 第二层的 **B 半**（可写 `.git` 上的逐字节快照比对），别把它当成 A 半的重复给删了。
 *
 * `GIT_TERMINAL_PROMPT=0` 防止任何意外的凭据交互把无人值守的进程挂住。
 *
-* **`GIT_LITERAL_PATHSPECS=1` 是安全项而不是洁癖**:`--` 后面的路径默认是 **wildmatch
-* 模式**,不是字面路径。我们的路径全部来自 URL query,于是 `path=*` 会让
-* `git diff HEAD -- '*'` 回一份**整仓 diff**(已实测)——正是红线明令禁止、
-* 会把浏览器主线程冻上数十秒的那件事;而一个真实存在、名字里带 `*` 的文件同样会
-* 匹配到别人身上,页面在 A 的标题下显示 B 的补丁。设了它,`*` / `?` / `[…]` 一律
-* 按字面比较。本项目的路径无一例外来自 git 自己的输出,不需要任何通配语义。
+* **`GIT_LITERAL_PATHSPECS=1` 是安全项而不是洁癖**：`--` 后面的路径默认是 wildmatch
+* 模式，而我们的路径全部来自 URL query——`path=*` 会让 `git diff HEAD -- '*'` 回一份
+* **整仓 diff**，正是红线明令禁止、会把浏览器主线程冻上数十秒的那件事；而一个真实存在、
+* 名字里带 `*` 的文件同样会匹配到别人身上，页面在 A 的标题下显示 B 的补丁。
 */
 const GIT_ENV = {
 	GIT_OPTIONAL_LOCKS: "0",
@@ -91,12 +82,9 @@ const GIT_ENV = {
 	GIT_LITERAL_PATHSPECS: "1"
 };
 /**
-* stdout 的**兜底**上限。没有它,一个几百 MB 的文件的 diff 会被整个读进内存,
-* 而这条路径上没有任何东西会先失败。
-*
-* 产品语义那道 5MB 闸不在这里,而是由调用方按次传 `maxStdoutBytes`(
-* 「卡补丁字节数」——见 git/diff.ts):**能不能渲染取决于补丁多大,而不是文件多大**,
-* 一个 6MB 的数据文件改一行照样该看得见。本常量只管「别把进程撑爆」。
+* stdout 的**兜底**上限：没有它，一个几百 MB 的文件的 diff 会被整个读进内存，而这条路径
+* 上没有任何东西会先失败。产品语义那道 5MB 闸不在这里，由调用方按次传 `maxStdoutBytes`
+*——**能不能渲染取决于补丁多大，而不是文件多大**，一个 6MB 的数据文件改一行照样该看得见。
 */
 const MAX_STDOUT_BYTES = 67108864;
 var GitError = class extends Error {
@@ -114,9 +102,8 @@ var GitError = class extends Error {
 	}
 };
 /**
-* 跑一条 git 命令。**非零退出不抛异常** —— 交给调用方判断,因为若干只读探测
-* (空仓库下的 `rev-parse --verify HEAD`、下限之下的 `--show-object-format`)
-* 正是靠非零退出来给出答案的。
+* 跑一条 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);
@@ -151,17 +138,13 @@ function runGit(args, cwd, options = {}) {
 			err.push(chunk);
 		});
 		/**
-		* **`kill()` 之后到达的报错是这次 kill 的后果,不是新事实。**
+		* **`kill()` 之后到达的报错是这次 kill 的后果，不是新事实。**
 		*
-		* 实测(CI run 31755485278):超限掐断 git 之后,**windows × Node 22.0.x 那一档**
-		* 会走到下面的 `'error'` 分支,于是 `kind` 成了 `exit`——调用方认不出「补丁太大」
-		* 这个结论,`too-large` 那条分支静默变成一个 500;另外 8 档与本机全绿,因为那里
-		* 这个事件根本不触发。至于报的是 EPIPE(git 还写在管道上)还是 kill 本身失败,
-		* 无从也无需区分:**判定超限之后,任何错误都是我们自己动手的结果。**
-		*
-		* 所以只要已经判定超限,一律以 `overflow` 收尾;流上的 `'error'` 同样咽掉 ——
-		* 一个没人监听的流错误会以未捕获异常掀掉整个服务,而进程的死活由下面两个
-		* 事件负责报告,不需要它再说一遍。
+		* 实测里 windows × Node 22.0.x 那一档会在超限掐断 git 之后走到下面的 `'error'` 分支，
+		* 于是 `kind` 成了 `exit`，调用方认不出「补丁太大」，`too-large` 那条分支静默变成一个
+		* 500。报的是 EPIPE（git 还写在管道上）还是 kill 本身失败无从也无需区分：判定超限
+		* 之后，任何错误都是我们自己动手的结果，一律以 `overflow` 收尾。流上的 `'error'` 同样
+		* 咽掉——一个没人监听的流错误会以未捕获异常掀掉整个服务。
 		*/
 		const settleOverflow = () => rejectPromise(new GitError("overflow", argv, "", null));
 		for (const stream of [child.stdout, child.stderr]) stream.on("error", () => {
@@ -188,7 +171,7 @@ function runGit(args, cwd, options = {}) {
 		});
 	});
 }
-/** 同上,但非零退出即抛。用于「失败没有第二种解释」的调用点。 */
+/** 同上，但非零退出即抛。用于「失败没有第二种解释」的调用点。 */
 async function runGitStrict(args, cwd) {
 	const result = await runGit(args, cwd);
 	if (result.code !== 0) throw new GitError("exit", args, result.stderr, result.code);
@@ -203,17 +186,15 @@ const MIN_GIT = {
 	minor: 11
 };
 /**
-* 空树对象哈希。空仓库下 HEAD 不存在、`git diff HEAD` 直接 fatal,改用它作 diff 基准
-* 即可,不必为空仓库写一条特殊分支。
-*
-* 硬编码是**要求**而不是偷懒:`git hash-object -t tree /dev/null` 依赖 `/dev/null`,
-* Windows 上不可移植;`git mktree` 会写对象库,直接违反只读承诺。
+* 空树对象哈希。空仓库下 HEAD 不存在、`git diff HEAD` 直接 fatal，改用它作 diff 基准即可。
+* 硬编码是**要求**而不是偷懒：`git hash-object -t tree /dev/null` 依赖 `/dev/null`，
+* Windows 上不可移植；`git mktree` 会写对象库，直接违反只读承诺。
 */
 const EMPTY_TREE = {
 	sha1: "4b825dc642cb6eb9a060e54bf8d69288fbee4904",
 	sha256: "6ef19b41225c5369f1c104d45d8d85efa9b057b53b14b4b9b939dd74decc5321"
 };
-/** 启动前置检查失败。CLI 据此打印一句话友好报错,而不是抛 Node 异常栈。 */
+/** 启动前置检查失败。CLI 据此打印一句话友好报错，而不是抛 Node 异常栈。 */
 var PreflightError = class extends Error {
 	code;
 	constructor(code, message) {
@@ -235,11 +216,8 @@ function tooOld(v) {
 	return v.major < MIN_GIT.major || v.major === MIN_GIT.major && v.minor < MIN_GIT.minor;
 }
 /**
-* 前置检查 + 定位,一次做完。
-*
-* 两条命令并发跑:串行等于把两次进程启动开销叠加进 300ms 冷启动预算,
-* 而它们之间没有依赖。失败路径上的额外一次 `rev-parse` 不计成本 —— 那条路径的
-* 终点是打印一行报错然后退出。
+* 前置检查 + 定位，一次做完。两条命令并发跑：串行等于把两次进程启动开销叠加进 300ms
+* 冷启动预算，而它们之间没有依赖。
 */
 async function locateRepo(cwd) {
 	const [version, located] = await Promise.all([runGit(["--version"], cwd), runGit([
@@ -267,30 +245,23 @@ async function locateRepo(cwd) {
 	};
 }
 /**
-* 工作区根目录名 —— 页面标题里的项目标识(`RepoState.repoName`)。
-*
-* **和 `root` 住在一起,不在消费者那边现切**:下面那条「用 `node:path` 不手写切分」
-* 的理由整个建立在 `root` 是怎么来的之上(`rev-parse --show-toplevel`),而那件事只有
-* 本文件知道。放在 `http/` 里的话,这里改一次 `root` 的产出方式,那边的论证就静默过期。
+* 工作区根目录名——页面标题里的项目标识(`RepoState.repoName`)。
 *
-* **用 `node:path` 的 `basename`,不要自己切 `/`**:Windows 上 `--show-toplevel` 回的是
-* `C:/…` 正斜杠,而 win32 的 basename 两种分隔符都认;POSIX 上 `\` 是合法文件名字符,
-* posix 的 basename 不会误把它当分隔符。两个平台各有一半是手写切分挑不对的。
+* **和 `root` 住在一起，不在消费者那边现切**：下面那条「用 `node:path` 不手写切分」的理由
+* 整个建立在 `root` 是怎么来的之上(`rev-parse --show-toplevel`)，而那件事只有本文件知道。
 *
-* 根目录没有 basename 时(`/`、Windows 盘符根)回空串,**不编一个名字出来** ——
-* 「取不到时显示什么」是展示决定,归消费者(见 `shared/protocol.ts`)。
+* **用 `node:path` 的 `basename`，不要自己切 `/`**：Windows 上 `--show-toplevel` 回的是
+* `C:/…` 正斜杠，而 win32 的 basename 两种分隔符都认；POSIX 上 `\` 是合法文件名字符，
+* posix 的 basename 不会误把它当分隔符。根目录没有 basename 时回空串，**不编一个名字
+* 出来**——「取不到时显示什么」是展示决定，归消费者。
 */
 function repoNameOf(repo) {
 	return basename(repo.root);
 }
 /**
-* diff 的基准。
-*
-* 正常仓库是 `HEAD`;空仓库(尚无任何提交)下 HEAD 不存在,`git diff HEAD` 会 fatal,
-* 降级为空树哈希。
-*
-* 不做缓存:`git checkout --orphan` 之后 HEAD 会重新变回未出生状态,缓存的正结果
-* 会让 diff 从此全部 fatal。这条只在取 diff 时调用,不落在冷启动路径上。
+* diff 的基准。正常仓库是 `HEAD`；空仓库（尚无任何提交）下 HEAD 不存在、`git diff HEAD`
+* 会 fatal，降级为空树哈希。不做缓存：`git checkout --orphan` 之后 HEAD 会重新变回未出生
+* 状态，缓存的正结果会让 diff 从此全部 fatal。
 */
 async function resolveDiffBase(root) {
 	const head = await runGit([
@@ -305,44 +276,136 @@ async function resolveDiffBase(root) {
 }
 
 //#endregion
-//#region src/server/git/diff.ts
+//#region src/server/git/worktree.ts
 /**
-* 超过这个字节数只提示、不预览。
-*
-* **两条路量的东西不同,但量的都是「前端要吃下多少字节」**:未跟踪那一侧整份文件
-* 就是补丁,所以量文件(还省得把它读进来);已跟踪那一侧补丁只含改动与上下文,
-* 所以量补丁本身(见 `trackedDiff`)。
+* 超过这个字节数只提示、不预览。**两条路量的东西不同，但量的都是「前端要吃下多少
+* 字节」**：读磁盘那一侧整份文件就是要发的东西（量文件还省得把它读进来），已跟踪那一侧
+* 补丁只含改动与上下文，所以量补丁本身（见 `diff.ts` 的 `trackedDiff`）。
 */
 const MAX_BYTES = 5242880;
 /**
-* 行数上限。体积阈值挡不住另一头:超长行数的窄文件体积不大,但逐行构造 diff 与
-* 前端渲染同样会卡。
-*
-* 已跟踪那一侧数的是**改动行数**(numstat 的加 + 减),未跟踪数的是文件行数 ——
-* 后者本来就整份都是新增行。两边量的都是「前端要渲染多少行」。
+* 行数上限。体积阈值挡不住另一头：超长行数的窄文件体积不大，但逐行构造 diff 与前端渲染
+* 同样会卡。已跟踪那一侧数的是**改动行数**（numstat 的加 + 减），读磁盘这一侧数文件行数。
 */
 const MAX_LINES = 5e4;
-var DiffRequestError = class extends Error {
+/** 坏请求（路径非法 / 目标不在了）。**不叫 `DiffRequestError`**：三条路都会抛它。 */
+var WorktreeError = class extends Error {
 	code;
 	constructor(code, message) {
 		super(message);
-		this.name = "DiffRequestError";
+		this.name = "WorktreeError";
 		this.code = code;
 	}
 };
+/** `target` 落在 `base` 里（含相等）。**边界谓词只此一份**——两份漂开时弱的那份就是一个穿越。 */
+function contains(base, target) {
+	const rel = relative(base, target);
+	return rel === "" || !rel.startsWith("..") && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
 /**
-* 把请求里的仓库相对路径落到磁盘上,并保证它没有走出仓库。
+* 把请求里的路径落到磁盘上，**两道边界一次过完**。
+*
+* 1. **字面量那道**：拒绝绝对路径、含 `\0` 的、以及 `relative()` 走出去的那些。
+* 2. **`realpath` 那道**：把中间段全部展开成真实路径再比一次。**只有第一道时 `lstat` 给的
+*    保护是假的——它只管最后一段**：仓库里有个 `linkdir -> ../outside` 时，
+*    `linkdir/secret.txt` 在字面上老实待在仓库内，而 `readFile` 顺着它走出去（已实测）。
 *
-* 路径来自 URL query,是外部输入。`git diff -- <pathspec>` 自身受仓库边界约束,
-* 但未跟踪文件那条路径要**直接读磁盘**,没有这道检查就是一个路径穿越。
+* **一个 gate、用途由参数说明，而不是按用途分叉成几个函数**：分叉时挑错哪一个不报错，正好
+* 复现上面那个洞。返回值里的 `path` 是**归一化**的——调用方据此做前缀匹配与 pathspec，于是
+* `dir/`、`./dir`、`dir//x` 这些拼法不必逐个特判（`resolve()` 本来就把它们归一了，先前那个
+* 只取 `abs` 的写法把这份结果扔掉了，才不得不在外面补一条 `endsWith('/')`）。
 */
-function resolveInRepo(root, path) {
-	if (!path || isAbsolute(path) || path.includes("\0")) throw new DiffRequestError("invalid-path", "invalid path");
-	const abs = resolve(root, path);
+async function resolveInRepo(root, path, options) {
+	if (path.includes("\0") || isAbsolute(path)) throw new WorktreeError("invalid-path", "invalid path");
+	if (path === "") {
+		if (options.allowRoot !== true) throw new WorktreeError("invalid-path", "invalid path");
+	}
+	const abs = path === "" ? resolve(root) : 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;
+	if (!contains(root, abs) || rel === "" && options.allowRoot !== true) throw new WorktreeError("invalid-path", "invalid path");
+	const realRoot = await realpath(root);
+	if (options.follow) {
+		let real;
+		try {
+			real = await realpath(abs);
+		} catch {
+			throw new WorktreeError("not-found", "no longer exists");
+		}
+		if (!contains(realRoot, real)) throw new WorktreeError("invalid-path", "invalid path");
+	} else {
+		let realParent;
+		try {
+			realParent = await realpath(resolve(abs, ".."));
+		} catch {
+			throw new WorktreeError("not-found", "file no longer exists");
+		}
+		if (!contains(realRoot, realParent)) throw new WorktreeError("invalid-path", "invalid path");
+	}
+	return {
+		abs,
+		path: rel.split(sep).join("/")
+	};
+}
+/**
+* 数行数。**空文件是 0 行，末尾那个换行不另算一行**——这是全仓唯一一份行数口径，diff 与文件
+* 视图共用它；两份漂开的症状是一个正好 50,000 行的文件在一个面板里能看、在另一个里说太大。
+*
+* 在 **Buffer 上数**而不是 `split('\n').length`：后者为了得到一个数字，把整份文件又切成 N 个
+* 字符串立刻丢掉，而超限那一路根本不需要正文。
+*/
+function countLines(buffer) {
+	if (buffer.length === 0) return 0;
+	let lines = 0;
+	for (let i = buffer.indexOf(10); i !== -1; i = buffer.indexOf(10, i + 1)) lines += 1;
+	return buffer[buffer.length - 1] === 10 ? lines : lines + 1;
 }
+/**
+* 读一个工作区文件并分类。顺序是固定的：符号链接 → 非普通文件 → 体积 → 二进制 → 行数。
+*
+* - **`lstat` 而不是 `stat`**：未跟踪的符号链接照样进变更列表、也照样出现在目录树里，而
+*   `stat` 跟随链接——校验过的是**链接自身**的路径，读到的却是链接目标。给的因此是**链接
+*   目标字符串本身**，与 git 对 mode 120000 的处理一致。
+* - **二进制走 NUL 字节探测**：这条路上没有 numstat 可依（未跟踪与被忽略的文件 git 根本不
+*   比对），而 git 自己那套含 `.gitattributes` 的判定只对已跟踪文件给得出。
+* - **二进制排在行数之前**：它比「太大」更具体，一个 8MB 的 PNG 说「文件过大」等于把原因说错。
+*/
+async function inspectFile(root, path) {
+	const { abs } = await resolveInRepo(root, path, { follow: false });
+	let info;
+	try {
+		info = await lstat(abs);
+	} catch {
+		throw new WorktreeError("not-found", "file no longer exists");
+	}
+	if (info.isSymbolicLink()) return {
+		kind: "symlink",
+		target: await readlink(abs)
+	};
+	if (!info.isFile()) throw new WorktreeError("invalid-path", "not a regular file");
+	if (info.size > 5242880) return {
+		kind: "too-large",
+		size: info.size,
+		reason: "size"
+	};
+	const buffer = await readFile(abs);
+	if (buffer.includes(0)) return { kind: "binary" };
+	const lines = countLines(buffer);
+	if (lines > 5e4) return {
+		kind: "too-large",
+		size: info.size,
+		reason: "lines"
+	};
+	return {
+		kind: "text",
+		buffer,
+		size: info.size,
+		lines,
+		executable: (info.mode & 73) !== 0
+	};
+}
+
+//#endregion
+//#region src/server/git/diff.ts
 /** `-z` 输出里是否原样出现这条路径。 */
 function lists(output, path) {
 	return output.split("\0").some((entry) => entry === path);
@@ -357,15 +420,10 @@ async function inIndex(root, path) {
 	], root), path);
 }
 /**
-* `git diff --numstat -z` 的解析。**重命名记录不是一段而是三段。**
-*
-* 实测:普通记录是 `<加>\t<减>\t<路径>`,一条占一个 NUL 段;
-* 重命名记录的**路径字段是空的**,后面紧跟两段 `<旧路径>` `<新路径>` ——
-* 与 `status --porcelain=v2` 的 `2 ` 记录**顺序相反**(那边是新在前、旧在后)。
-* 无状态地按 NUL 平铺切分,就会把 `<旧路径>` 当成下一条记录的开头。
-*
-* 本项目每次只问一条路径,所以「多吞两段」眼下不改变结果 —— 但把它写对的成本是
-* 三行,而写错的症状是将来某天改成批量查询后,一半记录静默错位。
+* `git diff --numstat -z` 的解析。**重命名记录不是一段而是三段**：普通记录是
+* `<加>\t<减>\t<路径>`，占一个 NUL 段；重命名记录的**路径字段是空的**，后面紧跟
+* `<旧路径>` `<新路径>` 两段——与 `status --porcelain=v2` 的 `2 ` 记录**顺序相反**
+* （那边是新在前、旧在后）。无状态地按 NUL 平铺切分，就会把 `<旧路径>` 当成下一条记录。
 */
 function parseNumstat(output) {
 	const segments = output.split("\0");
@@ -391,32 +449,29 @@ function parseNumstat(output) {
 	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 探测准确,形态是 `-\t-\t<路径>`;
+* 「基准 → 工作区」这条路径上的 numstat 记录；不在差异里就是 `null`。这一次调用同时回答
+* 三个问题，所以它取代了原先那次 `diff --name-only`：
+* 1. **它是不是已跟踪的**。已跟踪是 **HEAD ∪ index**，而 `ls-files` 只答得出 index——
+*    `git rm` 之后已暂存的删除在 index 里已经没有了，status 却照样报 `1 D.`、基准侧也
+*    还在。只认 index 会把它误判成未跟踪、掉进读磁盘那条路，以「文件不存在」告终；
+* 2. **是不是二进制**。已跟踪那一侧一律以 git 自己的判定为准（含 `.gitattributes`），
+*    形态是 `-\t-\t<路径>`；
 * 3. **改了多少行**。行数阈值那一路的判据。
 *
-* 重命名同样要传两个路径 + `-M`:只传新路径时 git 无法配对,numstat 会把它算成
-* 一个全新增文件(行数因此是整份文件),与补丁那一侧的退化是同一回事。
+* 重命名同样要传两个路径 + `-M`：只传新路径时 git 无法配对，numstat 会把它算成一个全
+* 新增文件（行数因此是整份文件），与补丁那一侧的退化是同一回事。
 */
 async function readNumstat(root, base, path, oldPath) {
 	/**
-	* **一次查询可以回不止一条记录**,所以必须按路径挑,不能取 `[0]`:
-	*
-	* 传了两个路径而 git **配不上对**时(`git mv` 之后把内容全部重写、留在工作区不
-	* `git add` —— status 照报 `R100`,所以 `oldPath` 是有的),它会拆成
-	* 「删掉旧的」+「新增新的」两条,按路径排序。取 `[0]` 就是掷硬币:实测那条
-	* 60,000 行的改名里,排在前面的是旧文件那条 100 行的删除,于是行数闸放它过去,
-	* 一份 6 万行的补丁照旧发给浏览器 —— 正是本阶段要防的那次冻结。二进制同理,
-	* 挑错记录会让一个文本文件被报成 binary(或反过来)。
+	* **一次查询可以回不止一条记录**，所以必须按路径挑、不能取 `[0]`：传了两个路径而 git
+	* **配不上对**时（`git mv` 之后把内容全部重写、留在工作区不 `git add`——status 照报
+	* `R100`，所以 `oldPath` 是有的），它会拆成「删掉旧的」+「新增新的」两条并按路径排序。
+	* 取 `[0]` 就是掷硬币：实测那条 60,000 行的改名里排在前面的是旧文件那条 100 行的删除，
+	* 于是行数闸放它过去，一份 6 万行的补丁照旧发给浏览器。二进制同理。
 	*
-	* 挑中之后**合并**而不是取一条:那份补丁里两个文件都在,前端要渲染的是两者之和。
+	* 挑中之后**合并**而不是取一条：那份补丁里两个文件都在，前端要渲染的是两者之和。挑的是
+	* `path` 字段——git 的重命名检测发生在 pathspec 过滤**之后**，配上对与配不上对的记录
+	* 都落在我们给的这两个路径里，因此不必再比 `record.oldPath`。
 	*/
 	const mine = parseNumstat(await runGitStrict(oldPath ? [
 		"diff",
@@ -441,7 +496,7 @@ async function readNumstat(root, base, path, oldPath) {
 		lines: mine.reduce((total, record) => total + record.lines, 0)
 	};
 }
-/** 工作区里这个文件的字节数;文件不在(删除)就是 `null`。 */
+/** 工作区里这个文件的字节数；文件不在（删除）就是 `null`。 */
 async function worktreeSize(abs) {
 	try {
 		return (await lstat(abs)).size;
@@ -450,29 +505,26 @@ async function worktreeSize(abs) {
 	}
 }
 /**
-* 已跟踪文件的补丁,以及三道拒绝。
+* 已跟踪文件的补丁，以及三道拒绝。
 *
-* **已跟踪那一侧卡的是「补丁多大」,不是「文件多大」**:文件体积只对未跟踪那条路
-* 成立(整份文件就是补丁),而已跟踪文件的补丁只包含改动与上下文 —— 按文件体积拒绝,
-* 一个 6MB 的数据文件改一行就再也看不了,而那是 agent 最常见的输出之一。反过来,
-* 行数也**不能**替代:一个「一行 6MB」的文件 numstat 只报 1 行,行数闸对它毫无作用。
-* 两者都量不到的东西正是字节,所以那一闸只能由取补丁那次调用自己带着上限去撞。
+* **已跟踪那一侧卡的是「补丁多大」，不是「文件多大」**：按文件体积拒绝的话，一个 6MB 的
+* 数据文件改一行就再也看不了，而那是 agent 最常见的输出之一。行数也**不能**替代——
+* 一个「一行 6MB」的文件 numstat 只报 1 行。两者都量不到的东西正是字节，所以那一闸只能由
+* 取补丁那次调用自己带着上限去撞。
 *
-* 顺序:二进制(numstat)→ 行数(numstat)→ 取补丁并卡字节。二进制先答是因为它比
-* 「太大」更具体,一个 8MB 的 PNG 说「文件过大」等于把原因说错了;行数排在取补丁之前,
-* 是因为它不用付出取补丁的代价就能拦下 5 万行以上的改动。
+* 顺序：二进制(numstat)→ 行数(numstat)→ 取补丁并卡字节。二进制先答是因为它比「太大」
+* 更具体（一个 8MB 的 PNG 说「文件过大」等于把原因说错了）；行数排在取补丁之前，是因为它
+* 不用付出取补丁的代价就能拦下 5 万行以上的改动。
 *
-* `size` 只用于**说话**(告诉用户这文件多大),不再参与判定,所以**只在要拒绝的那两条
-* 分支上才去 `lstat`**:正常那条路(绝大多数请求)一次系统调用都不欠。文件已被删除时
-* 取不到,给 0,前端据此不显示体积。
+* `size` 只用于**说话**、不再参与判定，所以**只在要拒绝的那两条分支上才去 `lstat`**：
+* 正常那条路一次系统调用都不欠。文件已被删除时取不到，给 0。
 *
-* **重命名条目必须同时传新旧两个路径**:只传新路径时 git 看不到另一侧、无法配对,
-* 会把重命名退化成一个全新增文件(已实测),「重命名识别并标注」随之落空。
-* 两个路径都来自 status 的 `2 ` 记录,无需额外查询。
+* **重命名条目必须同时传新旧两个路径**：只传新路径时 git 看不到另一侧、无法配对，会把
+* 重命名退化成一个全新增文件。两个路径都来自 status 的 `2 ` 记录，无需额外查询。
 */
 async function trackedDiff(root, base, path, abs, oldPath, stat) {
 	if (stat?.binary) return { kind: "binary" };
-	if (stat && stat.lines > MAX_LINES) return {
+	if (stat && stat.lines > 5e4) return {
 		kind: "too-large",
 		size: await worktreeSize(abs) ?? 0,
 		reason: "lines"
@@ -501,13 +553,13 @@ async function trackedDiff(root, base, path, abs, oldPath, stat) {
 		};
 		throw cause;
 	}
-	if (result.code !== 0) throw new DiffRequestError("not-found", "no diff available for this path");
+	if (result.code !== 0) throw new WorktreeError("not-found", "no diff available for this path");
 	return {
 		kind: "text",
 		patch: result.stdout
 	};
 }
-/** unified diff 的头四行。未跟踪的一切都是「新增」,左侧恒为 /dev/null。 */
+/** unified diff 的头四行。未跟踪的一切都是「新增」，左侧恒为 /dev/null。 */
 function newFileHeader(path, mode) {
 	return [
 		`diff --git a/${path} b/${path}`,
@@ -517,52 +569,33 @@ function newFileHeader(path, mode) {
 	];
 }
 /**
-* 未跟踪文件的补丁:**直接读文件内容手工构造 unified diff**。
-*
-* 不用 `git diff --no-index` —— 它依赖 `/dev/null` 作为对比端,Windows 上不可移植。
+* 未跟踪文件的补丁：**直接读文件内容手工构造 unified diff**。不用
+* `git diff --no-index`——它依赖 `/dev/null` 作为对比端，Windows 上不可移植。
 */
 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 {
+	const file = await inspectFile(root, path);
+	switch (file.kind) {
+		case "symlink": return {
 			kind: "untracked-text",
 			patch: `${[
 				...newFileHeader(path, "120000"),
 				"@@ -0,0 +1 @@",
-				`+${target}`,
+				`+${file.target}`,
 				"\"
 			].join("\n")}\n`
 		};
+		case "binary":
+		case "too-large": return file;
 	}
-	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 {
+	const head = newFileHeader(path, file.executable ? "100755" : "100644");
+	if (file.lines === 0) return {
 		kind: "untracked-text",
 		patch: `${head.join("\n")}\n`
 	};
+	const text = file.buffer.toString("utf8");
+	const endsWithNewline = text.endsWith("\n");
+	const lines = text.split("\n");
+	if (endsWithNewline) lines.pop();
 	const body = lines.map((line) => `+${line}`);
 	if (!endsWithNewline) body.push("\");
 	return {
@@ -575,28 +608,43 @@ async function untrackedDiff(root, path) {
 	};
 }
 async function readDiff(root, query) {
-	const abs = resolveInRepo(root, query.path);
-	if (query.oldPath) resolveInRepo(root, query.oldPath);
+	const { abs } = await resolveInRepo(root, query.path, { follow: false });
+	if (query.oldPath) await resolveInRepo(root, query.oldPath, { follow: false });
 	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/file.ts
+/** 读一个文件用于只读展示。 */
+async function readFileContent(root, path) {
+	const file = await inspectFile(root, path);
+	switch (file.kind) {
+		case "symlink": return {
+			kind: "symlink",
+			target: file.target
+		};
+		case "binary":
+		case "too-large": return file;
+		case "text": return {
+			kind: "text",
+			content: file.buffer.toString("utf8")
+		};
+	}
+}
+
 //#endregion
 //#region src/server/git/operation.ts
 /**
-* 判据表,**按序取第一个命中**。
+* 判据表，**按序取第一个命中**。两处顺序不是随手排的：
 *
-* 两处顺序不是随手排的:
-*
-* - **rebase 排在 merge 之前**。rebase 冲突停下时 git 目录里同时躺着 `rebase-merge/`
-*   与 `MERGE_MSG` / `AUTO_MERGE`(已实测),而用户处在的是 rebase —— 反过来
-*   排会把它标成「合并中」,页面上看不出任何异样,只是说错了用户在干什么。
-*   `MERGE_HEAD` 本身在那种情形下不出现,所以这一条更像是给后来者的防线
-* - **`rebase-apply/rebasing` 排在 `rebase-apply` 之前**。`git am` 与 `git rebase --apply`
-*   共用 `rebase-apply/` 这一个目录,里面有没有 `rebasing` 是区分两者的唯一办法;
-*   合并成一个标注等于对着一个正在 `git am` 的用户说他在 rebase
+* - **rebase 排在 merge 之前**：rebase 冲突停下时 git 目录里同时躺着 `rebase-merge/` 与
+*   `MERGE_MSG` / `AUTO_MERGE`，而用户处在的是 rebase——反过来排会把它标成「合并中」，
+*   页面上看不出任何异样，只是说错了用户在干什么
+* - **`rebase-apply/rebasing` 排在 `rebase-apply` 之前**：`git am` 与 `git rebase --apply`
+*   共用 `rebase-apply/` 这一个目录，里面有没有 `rebasing` 是区分两者的唯一办法
 */
 const PROBES = [
 	{
@@ -628,23 +676,20 @@ const PROBES = [
 		operation: "bisect"
 	}
 ];
-/** 存在与否,不区分文件还是目录 —— 上表里两种都有,而判据只是「在不在」。 */
+/** 存在与否，不区分文件还是目录——上表里两种都有，而判据只是「在不在」。 */
 function exists(path) {
 	return access(path).then(() => true, () => false);
 }
 /**
-* 当前进行中的多步操作;没有则 `undefined`。
+* 当前进行中的多步操作；没有则 `undefined`。
 *
-* **传进来的必须是 `git rev-parse --git-dir` 的返回值,不能自己拼 `<root>/.git`**
-*:linked worktree 下 `.git` 是个文件、真正的 git 目录在
-* `<主仓库>/.git/worktrees/<名>`,submodule 在 `<父仓库>/.git/modules/<路径>`
-* (均已实测)。拼出来的路径在那两种仓库里永远读不到 —— 于是永远标不出操作,
-* 而它不报错。`RepoInfo.gitDir` 已经是这个值,调用方照传即可。
+* **传进来的必须是 `git rev-parse --git-dir` 的返回值，不能自己拼 `<root>/.git`**：
+* linked worktree 下 `.git` 是个文件、真正的 git 目录在 `<主仓库>/.git/worktrees/<名>`，
+* submodule 在 `<父仓库>/.git/modules/<路径>`。拼出来的路径在那两种仓库里永远读不到——
+* 于是永远标不出操作，而它不报错。`RepoInfo.gitDir` 已经是这个值，调用方照传即可。
 *
-* 七个探针**并发发**再按上表定序:顺序判据只有一处(上面那张表),而不是散落在
-* 一串 `await` 的先后里 —— 后者调换两行就静默换了语义。每个探针直接产出**答案还是
-* undefined**,于是取第一个命中就是一次普通的 `find`,不必再拿下标去另一个数组里
-* 对号入座 —— 那种写法会让「顺序对不对」多出一个不在表里的依赖。
+* 七个探针**并发发**再按上表定序：顺序判据只有一处（上面那张表），而不是散落在一串
+* `await` 的先后里——后者调换两行就静默换了语义。
 */
 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);
@@ -653,16 +698,13 @@ async function readOperation(gitDir) {
 //#endregion
 //#region src/server/git/status.ts
 /**
-* 文件列表与分支状态的**唯一**数据源,一次调用同时拿到文件状态、暂存/未暂存双状态位、
+* 文件列表与分支状态的**唯一**数据源，一次调用同时拿到文件状态、暂存/未暂存双状态位、
 * 重命名信息与分支 / ahead-behind。
 *
-* 导出成常量是为了让 S3b 的降级轮询**复用逐字相同的这一条**,而不是各写各的:
-* 漏掉 `-uall` 的后果是静默的 —— git 会把未跟踪目录折叠成一行 `dir/`,于是在一个
-* 已存在的未跟踪目录里新增文件根本不改变输出,轮询判定「无变化」、页面不刷新,
-* 而那正是 agent 边跑边生成文件时最常见的形态。
-*
-* 两个参数都不能省:`-uall` 见上;`-z` 是因为不加它 git 会对含非 ASCII 字符、空格、
-* 引号的路径做 C 风格转义并加引号(已实测)。
+* 导出成常量是为了让降级轮询**复用逐字相同的这一条**：漏掉 `-uall` 的后果是静默的——
+* git 会把未跟踪目录折叠成一行 `dir/`，于是在一个已存在的未跟踪目录里新增文件根本不改变
+* 输出，轮询判「无变化」、页面不刷新。`-z` 则是因为不加它 git 会对含非 ASCII 字符、空格、
+* 引号的路径做 C 风格转义并加引号。
 */
 const STATUS_ARGS = [
 	"status",
@@ -685,10 +727,8 @@ function asStatusCode(ch) {
 	return ch && STATUS_CODES.has(ch) ? ch : ".";
 }
 /**
-* 切出记录开头的 `n` 个空格分隔字段,剩下的整段就是路径。
-*
-* 不能整条 `split(' ')` —— 路径本身可以含空格,而 `-z` 只把**记录**分隔成 NUL 段,
-* 段内仍是空格分隔。
+* 切出记录开头的 `n` 个空格分隔字段，剩下的整段就是路径。不能整条 `split(' ')`——
+* 路径本身可以含空格，而 `-z` 只把**记录**分隔成 NUL 段，段内仍是空格分隔。
 */
 function splitLeading(rec, n) {
 	const fields = [];
@@ -708,11 +748,9 @@ function parseScore(field) {
 	return m?.[1] ? Number(m[1]) : null;
 }
 /**
-* 解析 `-z` 输出。
-*
-* **NUL 在重命名记录里既是记录分隔符、又是字段分隔符**:`2 ` 记录的格式是
-* `2 <XY> ... R<score> <新路径>\0<旧路径>`,一条记录占**两个** NUL 段(已实测)。
-* 因此不能无状态地按 NUL 平铺切分,遇到 `2 ` 必须额外吞掉下一段作为旧路径。
+* 解析 `-z` 输出。**NUL 在重命名记录里既是记录分隔符、又是字段分隔符**：`2 ` 记录是
+* `2 <XY> ... R<score> <新路径>\0<旧路径>`，一条占**两个** NUL 段。因此不能无状态地按
+* NUL 平铺切分，遇到 `2 ` 必须额外吞掉下一段作为旧路径。
 */
 function parseStatus(raw) {
 	const segments = raw.split("\0");
@@ -800,15 +838,10 @@ function parseStatus(raw) {
 	};
 }
 /**
-* 主查询的**原始输出**,不解析。
-*
-* 存在的唯一理由是降级轮询:它只需要回答「变没变」,而逐字节比对原始输出
-* 既是最省的判据,也让「轮询与主查询是同一条命令」成为**构造上的事实**而不是
-* 两处各自维护的巧合 —— 后者漏个 `-uall` 不报错,只是在一个已存在的未跟踪目录里
-* 新增文件时页面不刷新(红线)。
-*
-* 比对解析后的结构也做得到,但那要么写一份深比较、要么 `JSON.stringify` 一遍,
-* 而两者都会随协议类型增删字段而静默改变灵敏度。
+* 主查询的**原始输出**，不解析。存在的唯一理由是降级轮询：它只需要回答「变没变」，而逐
+* 字节比对原始输出既是最省的判据，也让「轮询与主查询是同一条命令」成为**构造上的事实**
+* 而不是两处各自维护的巧合。比对解析后的结构也做得到，但深比较与 `JSON.stringify` 都会
+* 随协议类型增删字段而静默改变灵敏度。
 */
 async function readStatusRaw(root) {
 	return runGitStrict(STATUS_ARGS, root);
@@ -816,11 +849,9 @@ async function readStatusRaw(root) {
 /**
 * 变更列表 + 分支状态。
 *
-* 取 `RepoInfo` 而不是两个字符串:进行中的多步操作只能从 **git 目录**下的状态文件读
-*,而它和工作区根是两条不同的路径 —— linked worktree 与 submodule 下差得很远。
-* 两个同类型参数并排放着,调换顺序不会报错,只会让 `operation` 从此恒为空。
-*
-* 两件事并发:`git status` 是一次子进程,`readOperation` 是七个 `access`,互不依赖。
+* 取 `RepoInfo` 而不是两个字符串：进行中的多步操作只能从 **git 目录**下的状态文件读，而
+* 它和工作区根是两条不同的路径——两个同类型参数并排放着，调换顺序不会报错，只会让
+* `operation` 从此恒为空。两件事并发：status 是一次子进程，`readOperation` 是七个 `access`。
 */
 async function readStatus(repo) {
 	const [raw, operation] = await Promise.all([readStatusRaw(repo.root), readOperation(repo.gitDir)]);
@@ -829,6 +860,227 @@ async function readStatus(repo) {
 	return status;
 }
 
+//#endregion
+//#region src/server/git/tree.ts
+/**
+* 未跟踪那两条调用共用的尾巴。四个参数每一个都在挡一件具体的事：
+*
+* - `-z`：路径原样输出、按 NUL 切分（与其余所有列表类调用同一条约束）；
+* - **`--directory` 与 `--no-empty-directory` 必须同时带**。`--others` 默认展开到文件粒度，
+*   于是一个装着 30,000 个文件的 `node_modules` 就是 30,000 条路径——**git 照常 exit 0**，
+*   症状只是这一层慢得离谱、内存里凭空多出几 MB 字符串，没有任何东西会报错。带上之后整个
+*   目录折叠成一条 `node_modules/`，正是树上要画的那一条；`--no-empty-directory` 顺带滤掉
+*   折叠后为空的那些；
+* - `--exclude-standard`：读 `.gitignore` / `.git/info/exclude` / 全局 exclude。**它对
+*   `--ignored` 那条是强制的**——单独出现时 git 直接 fatal（`needs some exclude pattern`）。
+*/
+const OTHERS_ARGS = [
+	"-z",
+	"--exclude-standard",
+	"--directory",
+	"--no-empty-directory"
+];
+/**
+* 已跟踪的那一条**带 `--stage`**，为的是拿到 mode。
+*
+* 判据是 **`160000` 即 gitlink（submodule）**：它在普通输出里就是一条不带尾斜杠的路径，与
+* 一个文件长得一模一样——照文件画出来的话，树上那一行没有展开箭头，点下去还会以「不是普通
+* 文件」告终，而 difftab 明确支持在含 submodule 的仓库里跑。
+*
+* **`--stage` 与 `--others` 不能合成一条**：加上它之后 git 把未跟踪那部分整个丢掉（已实测），
+* 所以这里是三条调用而不是两条。三条并发发出，墙上时间仍是一条的量级。
+*/
+const CACHED_ARGS = [
+	"ls-files",
+	"-z",
+	"--stage",
+	"--cached"
+];
+/**
+* gitlink 的 mode，`--stage` 记录（`<mode> <object> <stage>\t<path>`）的开头。git 自己对
+* submodule 的编码，不是我们的约定。按 `indexOf('\t')` 切、不上正则：这一段每个已跟踪文件
+* 各跑一次，而要的只是「\t 后面那截」与「开头六个字符」。
+*/
+const GITLINK_MODE = "160000";
+/**
+* 一层的直接子项。
+*
+* 收敛判据是**「相对本层的第一段」**：`src/web/main.tsx` 相对 `src` 的第一段是 `web`，
+* 后面还跟着 `/`，所以 `web` 是目录；`--directory` 折叠出来的 `node_modules/` 以 `/` 结尾，
+* 同样是目录。去重后目录在前、各自按名字排序（照 VS Code 的排法）。
+*
+* `dir` 为空串即仓库根，此时不带 `--`：`ls-files` 不带 pathspec 就是整仓。
+*/
+async function readTree(root, dir) {
+	/**
+	* 两道边界一次过完，**并且拿走归一化后的那份路径**。`follow: true` 是因为兜底那条要
+	* `readdir` 它，而 `readdir` 本来就跟随最后一段；`allowRoot` 是因为目录树的第一层就是根。
+	*
+	* 归一化那半同样不是顺手：`dir/`、`./dir`、`dir//x` 都会被 `resolve()` 归成同一份，而下面
+	* 整个收敛逻辑靠 `prefix` 做前缀匹配——先前只取绝对路径、把归一结果扔掉，于是不得不在外面
+	* 补一条 `endsWith('/')` 的特判，而那一族拼法是拦不完的。
+	*/
+	const { abs, path } = await resolveInRepo(root, dir, {
+		follow: true,
+		allowRoot: true
+	});
+	const scope = path === "" ? [] : ["--", path];
+	/**
+	* **两条 `--others` 照旧按本层完整路径问，只有 git 自己失败了才退到第一段重问一次。**
+	*
+	* 要它是因为深处那一层会**直接 fatal**（`internal error - directory entry not superset of
+	* prefix`，exit 128）：git 拿全部 pathspec 的公共前导目录当前缀（`a/b/c` 截到最后一个 `/`，
+	* 得 `a/b/`），而 `--ignored` 那条报的是**排除规则命中的那一层**（`.gitignore` 里的
+	* `vendor/`）、与 pathspec 有多深无关——吐目录条目之前那道断言要求前缀不比条目长。于是
+	* **被忽略的那一片里深度 ≥ 3 的那一层必炸，深度 ≤ 2 恒安全**（前缀最长就是 `a/`，正好等于
+	* 最短的那条记录）。`-C` 进那个目录、pathspec 带尾斜杠都绕不过；第一段不含 `/`，前缀因此
+	* 恒为空，断言永远成立。页面上炸出来的样子是那一层写着一行 `git ls-files … failed (exit)`。
+	*
+	* **但第一段只能当兜底，不能当默认**——放宽 pathspec 会静默改掉另外两件事的答案：
+	*
+	* - **被忽略的那一片嵌在一个未跟踪目录里时，放宽之后 `--ignored` 那条一条都不回**（实测：
+	*   `u/` 整个未跟踪、`u/ig/` 被忽略，问 `-- u/ig` 回 `u/ig/`，问 `-- u` 回空）。那一层于是
+	*   继承「不灰显」，页面上只是它不再灰了；
+	* - **`?path=<未跟踪目录里的一个文件>` 会从 400 变成 500**：窄 pathspec 下 git 吐的是这个
+	*   文件自己（下面据此判 `selfKind === 'file'`），放宽之后它被折叠进 `a/`，于是没人认出这是
+	*   坏请求，兜底拿一个普通文件去 `readdir`，以 `ENOTDIR` 收场。
+	*
+	* 所以退让只发生在 git 已经答不出东西的那一刻，代价范围也就限死在「本来是个 500」的那一层。
+	* 重问一次拿到的是折叠记录，之后走的是下面读一层磁盘的兜底——折叠层以下 git 本就答不出内容。
+	*
+	* 判据用「非零退出」而不是去比对那句 fatal 的字面量：这两条调用是只读列举，非零退出没有第二
+	* 种解释，而按消息匹配要赌它逐字不变。重问那次再失败就把**原来那个**错误抛出去。
+	*/
+	const firstSlash = path.indexOf("/");
+	const runOthers = (args) => runGitStrict([...args, ...scope], root).catch((cause) => {
+		if (!(cause instanceof GitError) || cause.kind !== "exit" || firstSlash === -1) throw cause;
+		return runGitStrict([
+			...args,
+			"--",
+			path.slice(0, firstSlash)
+		], root).catch(() => {
+			throw cause;
+		});
+	});
+	const [cached, others, ignoredOut] = await Promise.all([
+		runGitStrict([...CACHED_ARGS, ...scope], root),
+		runOthers([
+			"ls-files",
+			...OTHERS_ARGS,
+			"--others"
+		]),
+		runOthers([
+			"ls-files",
+			...OTHERS_ARGS,
+			"--others",
+			"--ignored"
+		])
+	]);
+	const prefix = path === "" ? "" : `${path}/`;
+	/**
+	* 这一层落在一片被折叠的区域里（`null` 即没有），以及那一片是哪一档。
+	*
+	* `--directory` 是它该有的行为——`vendor/` 与 `node_modules/` 正是靠它才没有变成三万条
+	* 路径——但代价是 git 从此再也答不出那里面有什么。而且**它折叠在最高那一层**：问
+	* `dist/server` 回来的仍是 `dist/`（已实测；三种 pathspec 写法与 `-C` 进去都一样）。
+	*
+	* **判据因此是「回来的这条是本层自己**或**它的某个祖先」，不是「正好等于本层」**：只认
+	* 相等时，`dist/` 这条既不等于 `dist/server/`、又过不了下面那道 `startsWith(prefix)`，
+	* 于是这一层两手空空地返回——页面上就是一个展开后写着 Empty 的目录，而里面明明有东西。
+	*/
+	let collapsedAs = null;
+	const byName = /* @__PURE__ */ new Map();
+	/** 一条路径 → 这一层里的那个条目。`isDir` 由调用方按各自的格式判出来后传进来。 */
+	const add = (path, isIgnored, gitlink = false) => {
+		if (!path.startsWith(prefix)) return;
+		const rest = path.slice(prefix.length);
+		const slash = rest.indexOf("/");
+		const name = slash === -1 ? rest : rest.slice(0, slash);
+		if (name === "" || byName.has(name)) return;
+		byName.set(name, {
+			name,
+			path: `${prefix}${name}`,
+			kind: slash === -1 && !gitlink ? "file" : "directory",
+			ignored: isIgnored
+		});
+	};
+	/**
+	* git 提到了**本层自己**这条路径（而不是它底下的东西），说的是哪一种。两种都要：
+	* `gitlink` 是下面那条兜底的第二个正面判据；`file` 说明**问错了**——有人把一个文件当目录
+	* 展开，那是坏请求，不是一个空目录。
+	*/
+	let selfKind = null;
+	for (const segment of cached.split("\0")) {
+		const tab = segment.indexOf("	");
+		if (tab === -1) continue;
+		const entryPath = segment.slice(tab + 1);
+		const gitlink = segment.startsWith(GITLINK_MODE);
+		if (entryPath === path) {
+			selfKind = gitlink ? "gitlink" : "file";
+			continue;
+		}
+		add(entryPath, false, gitlink);
+	}
+	const collectOthers = (output, isIgnored) => {
+		for (const line of output.split("\0")) {
+			if (line === "") continue;
+			if (line.endsWith("/") && prefix.startsWith(line)) {
+				collapsedAs = isIgnored;
+				continue;
+			}
+			if (line === path) {
+				selfKind ??= "file";
+				continue;
+			}
+			add(line, isIgnored);
+		}
+	};
+	collectOthers(others, false);
+	collectOthers(ignoredOut, true);
+	/**
+	* **git 答不出这一层时读一次磁盘**，只读一层。两种形态都会走到这里，而**两种手上都有正面
+	* 证据**——判据因此是那两条，不是「一条子项都没有」：
+	*
+	* - `--directory` 把这一片折叠了（`node_modules/` 里面、`dist/server` 之类）；
+	* - 这是一个 **submodule**，父仓库的 `ls-files` 对它只有一条 gitlink 记录（`selfKind`）。
+	*
+	* 写成「空就兜底」时它是个 catch-all：`?path=<一个文件>` 与 `?path=<不存在的路径>` 同样
+	* 落进来，`readdir` 抛 `ENOTDIR` / `ENOENT` 被咽掉，页面上是一个「展开后是空的目录」——
+	* 而它们本该是 400 / 404。**为了不吞掉 `EACCES` 而加的那道 code 过滤，本身就是在给一个过宽
+	* 的开关打补丁**；判据换成正面证据之后，那道过滤连同它一起没了。
+	*
+	* 这里读磁盘不需要任何 git 知识，这正是它成立的理由：两条证据都说明整棵子树同属一档，于是
+	* 每个子项的 `ignored` 直接继承（submodule 那一路继承「不灰显」）。`withFileTypes` 的
+	* dirent 不跟随符号链接（`isDirectory()` 对指向目录的链接为 false），而 `dir` 自己那一段
+	* 已经由上面那道 `follow: true` 的边界验过。
+	*/
+	if (selfKind === "file") throw new WorktreeError("invalid-path", "not a directory");
+	if (byName.size === 0 && (collapsedAs !== null || selfKind === "gitlink")) {
+		const inherited = collapsedAs ?? false;
+		for (const child of await readdir(abs, { withFileTypes: true })) {
+			if (child.name === ".git") continue;
+			byName.set(child.name, {
+				name: child.name,
+				path: `${prefix}${child.name}`,
+				kind: child.isDirectory() ? "directory" : "file",
+				ignored: inherited
+			});
+		}
+	}
+	/**
+	* **回的是完整 payload，`path` 用归一后的那份。** http 那层因此只负责发，与 `/api/diff`、
+	* `/api/file` 一致；先前由 http 拿客户端原样传来的 query 去拼，既不对称，也让「归一化」
+	* 这件事没有 owner。
+	*/
+	return {
+		path,
+		entries: [...byName.values()].sort((a, b) => {
+			if (a.kind !== b.kind) return a.kind === "directory" ? -1 : 1;
+			return a.name.localeCompare(b.name);
+		})
+	};
+}
+
 //#endregion
 //#region src/server/watch/tier.ts
 /** `fs.watch` 的 `ignore` 选项自此版本可用。 */
@@ -838,10 +1090,8 @@ const IGNORE_SINCE = {
 	patch: 0
 };
 /**
-* 强制指定档位的**内部**环境变量(S3b1 的首个交付物)。
-*
-* 没有它,S3b2 的六条档位验收项在单机上一条都无从自查 —— 一台机器只有一个 Node
-* 版本、一个平台,而三档正是按这两者分的。它不是给用户的开关,README 不写它。
+* 强制指定档位的**内部**环境变量。没有它，档位相关的验收在单机上一条都无从自查——一台
+* 机器只有一个 Node 版本、一个平台，而三档正是按这两者分的。它不是给用户的开关。
 */
 const TIER_ENV = "DIFFTAB_WATCH_TIER";
 /** 档位环境变量的取值不合法。由 main() 收成一句话友好报错。 */
@@ -852,10 +1102,8 @@ var WatchTierError = class extends Error {
 	}
 };
 /**
-* `24.14.1` / `26.0.0-nightly20260101` → 三元组 + 是否带预发布标签。
-*
-* 解析不出来返回 null,调用方按「没有 `ignore`」处理 —— 见 `supportsIgnoreOption`
-* 里那段关于误判方向的说明。
+* `24.14.1` / `26.0.0-nightly20260101` → 三元组 + 是否带预发布标签。解析不出来返回 null，
+* 调用方按「没有 `ignore`」处理。
 */
 function parseNodeVersion(version) {
 	const m = /^v?(\d+)\.(\d+)\.(\d+)(-.*)?$/.exec(version.trim());
@@ -868,14 +1116,12 @@ function parseNodeVersion(version) {
 	};
 }
 /**
-* 当前 Node 是否具备 `fs.watch` 的 `ignore` 选项。
-*
-* **解析失败一律按「没有」处理**,方向是刻意的:误判成没有,代价是 Linux 上退化为
-* 1.5s 轮询(功能完整,只是不即时);误判成有,代价是上面那条注释里的 ENOSPC。
-* 两种误判的代价差着一个数量级,判据不确定时只能倒向便宜的那一侧。
+* 当前 Node 是否具备 `fs.watch` 的 `ignore` 选项。**解析失败一律按「没有」处理**，方向是
+* 刻意的：误判成没有，代价是 Linux 上退化为 1.5s 轮询（功能完整，只是不即时）；误判成有，
+* 代价是上面那条 ENOSPC。两种误判差着一个数量级，判据不确定时只能倒向便宜的那一侧。
 *
-* 预发布标签按 semver 的规矩算作**低于**同版本正式版(`24.14.0-rc.1 < 24.14.0`):
-* 那正是选项刚合入、行为还可能变的窗口。
+* 预发布标签按 semver 的规矩算作**低于**同版本正式版(`24.14.0-rc.1 < 24.14.0`)：那正是
+* 选项刚合入、行为还可能变的窗口。
 */
 function supportsIgnoreOption(nodeVersion) {
 	const v = parseNodeVersion(nodeVersion);
@@ -888,21 +1134,19 @@ function supportsIgnoreOption(nodeVersion) {
 /**
 * 档位判定。
 *
-* - **A**:有 `ignore`,三端通用 —— Linux 上是注册前跳过,正是配额问题的官方解法
-* - **B**:没有 `ignore`,但在 macOS / Windows 上走原生 FSEvents / `ReadDirectoryChangesW`,
-*   单句柄监听整棵树,本就没有配额问题,回调里自己过滤即可
-* - **C**:没有 `ignore` 且在 Linux 上 —— **不建递归 watch**,工作区改动走轮询
+* - **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 的六条验收项全都压在这个变量上。
+* 实际生效的档位：环境变量优先，否则按运行时判定。**取值不合法时抛错而不是退回自动判定**：
+* `DIFFTAB_WATCH_TIER=b` 那种手滑退回自动判定后，在本机上多半照样给出 B 档，于是「我验过
+* B 档了」这个结论建立在一次根本没生效的强制指定上。
 */
 function forcedTier(env) {
 	const forced = env[TIER_ENV];
@@ -915,23 +1159,19 @@ function resolveTier(env = process.env, nodeVersion = process.versions.node, pla
 	return forcedTier(env) ?? detectTier(nodeVersion, platform);
 }
 /**
-* 该档位下**工作区通路**的既定形态(`WatchState.mode`)。
-*
-* C 档一开始就以轮询为工作区通路,A / B 档则是原生监听。**它只是「还没起监听时
-* 答什么」**:监听懒起(见 http/server.ts),起了之后真实取值由 `WatchHandle.mode`
-* 给 —— A / B 档运行中落到轮询兜底时,那一侧会翻成 `polling`。
+* 该档位下**工作区通路**的既定形态(`WatchState.mode`)。**它只是「还没起监听时答什么」**：
+* 监听懒起，起了之后真实取值由 `WatchHandle.mode` 给——A / B 档运行中落到轮询兜底时，
+* 那一侧会翻成 `polling`。
 */
 function initialMode(tier) {
 	return tier === "C" ? "polling" : "native";
 }
 /**
-* 强制指定 A 档、但这个 Node 根本没有 `ignore` 时的一句提醒(没有则返回 null)。
+* 强制指定 A 档、但这个 Node 根本没有 `ignore` 时的一句提醒（没有则返回 null）。
 *
-* **不是报错**:「三档均可通过内部环境变量强制指定」是已经勾掉的验收项,
-* 在 Node 22 上拒绝启动会把它推翻,而 macOS / Windows 上强制 A 档去看别的行为
-* 也是正当用法。但沉默同样不行 —— Node 对未知选项是**静默忽略**,于是这次
-* 「A 档」跑的是一个**没有任何过滤的递归 watch**:在 Linux 上那正是耗尽
-* `fs.inotify.max_user_watches` 的那条路,而结论会写成「我验过 A 档了」。
+* **不是报错**：「三档均可通过内部环境变量强制指定」是既定用法，在 Node 22 上拒绝启动会把
+* 它推翻。但沉默同样不行——Node 对未知选项是**静默忽略**，于是这次「A 档」跑的是一个
+* **没有任何过滤的递归 watch**，而结论会写成「我验过 A 档了」。
 */
 function forcedTierWarning(env = process.env, nodeVersion = process.versions.node) {
 	if (forcedTier(env) !== "A" || supportsIgnoreOption(nodeVersion)) return null;
@@ -942,10 +1182,8 @@ function forcedTierWarning(env = process.env, nodeVersion = process.versions.nod
 //#endregion
 //#region src/server/watch/ignore.ts
 /**
-* 路径任一段命中即忽略。
-*
-* `.git` 在集合里**与档位无关**:工作区那条递归 watch 绝不能进 `.git`(一次 gc 就是
-* 几万个条目),`.git` 侧另有目录级非递归 watch 盯着(见 watcher.ts)。
+* 路径任一段命中即忽略。`.git` 在集合里**与档位无关**：工作区那条递归 watch 绝不能进
+* `.git`（一次 gc 就是几万个条目），`.git` 侧另有目录级非递归 watch 盯着。
 */
 const IGNORE_NAMES = /* @__PURE__ */ new Set([
 	"node_modules",
@@ -955,70 +1193,48 @@ const IGNORE_NAMES = /* @__PURE__ */ new Set([
 	".next",
 	"build"
 ]);
-/** 路径分隔符两种都切:Windows 的原生 watcher 给的是反斜杠分隔的相对路径。 */
+/** 路径分隔符两种都切：Windows 的原生 watcher 给的是反斜杠分隔的相对路径。 */
 const SEPARATOR = /[\\/]/;
 /**
-* 大小写归一,对齐 `ignore` 内部的 `nocase: isWindows || isMacOS`。**不导出**:
-* 它只有 `createIsIgnored` 一个消费者,而多一个入口就多一份会跟着漂的契约。
-*
-* Linux 上**原样返回**:那里的文件系统区分大小写,`Node_Modules` 与 `node_modules`
-* 是两个不同的目录,归一等于把一个用户真的想看的目录悄悄屏蔽掉。
+* 大小写归一，对齐 `ignore` 内部的 `nocase: isWindows || isMacOS`。**不导出**：多一个入口
+* 就多一份会跟着漂的契约。Linux 上**原样返回**——那里的文件系统区分大小写，`Node_Modules`
+* 与 `node_modules` 是两个不同的目录，归一等于把一个用户真的想看的目录悄悄屏蔽掉。
 */
 function caseFold(segment, platform) {
 	return platform === "win32" || platform === "darwin" ? segment.toLowerCase() : segment;
 }
 /**
-* 造一个绑定平台的匹配器。**平台可注入是为了让三端的归一行为都能在一台机器上验**
-* —— 与 `DIFFTAB_WATCH_TIER` 同一个理由。
-*
-* 收到的是**相对被监听目录的路径**(A 档 Linux 侧是遍历到的条目,A 档 macOS/Windows
-* 与 B 档是事件路径),不是绝对路径 —— 传绝对路径进来也能工作,只是仓库自身若躺在
-* 某个叫 `build` 的目录下就会整片被忽略,所以调用方不该那么用。
+* 造一个绑定平台的匹配器。**平台可注入是为了让三端的归一行为都能在一台机器上验**。收到的
+* 是**相对被监听目录的路径**，不是绝对路径——传绝对路径进来也能工作，只是仓库自身若躺在
+* 某个叫 `build` 的目录下就会整片被忽略，所以调用方不该那么用。
 */
 function createIsIgnored(platform = process.platform) {
 	return (path) => path.split(SEPARATOR).some((segment) => IGNORE_NAMES.has(caseFold(segment, platform)));
 }
-/** 当前平台的那一份。A 档传给 `ignore`、B 档在回调最前面调,是**同一个函数**。 */
+/** 当前平台的那一份。A 档传给 `ignore`、B 档在回调最前面调，是**同一个函数**。 */
 const isIgnored = createIsIgnored();
 
 //#endregion
 //#region src/server/watch/watcher.ts
 /**
-* 事件合并窗口(建议 100-200ms)。
-*
-* **在 Linux 上这是必需项而非优化项**:用户态递归实现初次遍历目录树时会对遍历到的
-* 每个条目 emit 一次事件,启动瞬间即产生一波与实际变更无关的风暴。`.git` 侧同样需要:
-* 一条 `git commit` 会连着写 index.lock、index、COMMIT_EDITMSG、HEAD 的 reflog、
-* refs/heads/<分支>,五六个事件是常态。
+* 事件合并窗口。**Linux 上是必需项而非优化项**：用户态递归实现初次遍历时对每个条目都
+* emit 一次，启动瞬间就是一波风暴；`.git` 侧一条 `git commit` 也是五六个事件。
 */
 const DEBOUNCE_MS = 150;
 /** 降级轮询的周期(1.5s)。C 档的工作区通路也是它。 */
 const POLL_MS = 1500;
 /**
-* **原生档(A / B)的低频安全轮询周期**。
-*
-* 它补的是一个没有任何信号的缺口:Linux 上 inotify 配额在**遍历途中**耗尽时,Node
-* 一次都不 emit(2026-08-18 实测,推翻了此前的源码推断)—— 没轮上注册的那些
-* 目录里,改一个**启动前就存在**的文件从此静默丢失,`mode` 还一直说 `native`。
-* 原生监听少报了什么是没法从监听那一侧知道的,只有拿 status 输出本身去比才看得见。
-*
-* **取 30s 而不是 1.5s**:要求「原生监听模式下空闲 CPU 接近零」,一次 status 几十
-* 毫秒,30s 一拍的占空比是千分之几;代价是那个病态场景下最坏 30s 的滞后。
+* **原生档(A / B)的低频安全轮询周期**。inotify 配额在**遍历途中**耗尽时 Node 一次都
+* 不 emit，改动从此静默丢失而 `mode` 还说 `native`——只有拿 status 输出本身去比才看得
+* 见。30s 而非 1.5s 是为了让原生档空闲 CPU 接近零，代价是最坏 30s 滞后。
 */
 const SAFETY_POLL_MS = 3e4;
 /**
-* `.git` 下需要盯的目录清单。
-*
-* **一律是目录,绝不是单个文件**:Linux / macOS 上 watch 绑的是 inode,而 git 写
-* `HEAD` / `index` 走的是「写临时文件 + 原子 rename」,新文件是新 inode,对文件建的
-* watch 从此静默失效。
+* `.git` 下需要盯的目录清单。**一律是目录，绝不是单个文件**：watch 绑 inode，而 git 写
+* `HEAD` / `index` 走「写临时文件 + 原子 rename」，对文件建的 watch 从此静默失效。
 *
-* **绝不递归、更绝不进 `objects`**:一次 gc 就是几万个条目,既是配额灾难,也会把
-* 与展示无关的写入变成事件风暴。清单之所以短得像不够用,是因为主力其实是 `gitDir`
-* 本身 —— 提交写 `index` 与 `COMMIT_EDITMSG`、切分支写 `HEAD`、fetch 写 `FETCH_HEAD`,
-* 全都直接落在它下面。`refs/` 那两条是补 `refs/heads/<分支>` 这种一层深的更新,
-* 属于锦上添花;`refs/heads/feature/x` 这类嵌套分支名照样只由 `index` 那一路兜住,
-* 而那一路本来就够。
+* **绝不递归、更绝不进 `objects`**（一次 gc 就是几万个条目）。主力是 `gitDir` 本身——
+* 提交、切分支、fetch 都直接写在它下面；`refs/` 那两条只补一层深的更新。
 */
 function gitWatchDirs(gitDir) {
 	const dirs = [];
@@ -1036,13 +1252,9 @@ function gitWatchDirs(gitDir) {
 	return dirs;
 }
 /**
-* 起监听。
-*
-* 关于「我们自己会不会把自己触发起来」:不会,而且这件事全靠封装层那条
-* `GIT_OPTIONAL_LOCKS=0`(红线)。不设它的话 `git status` 会把 stat 缓存写回
-* `.git/index`,于是每次刷新都写一次 index、每次写 index 都触发一次刷新 —— 一个不报错、
-* 只是 CPU 常年 1% 的自激循环,而 status 的输出从头到尾都是对的。轮询那条路上这
-* 一点更要命:它每 1.5s 主动跑一次 status。
+* 起监听。不自激全靠封装层那条 `GIT_OPTIONAL_LOCKS=0`：不设它时 `git status` 把 stat
+* 缓存写回 `.git/index`，于是每次刷新写一次 index、每次写 index 又触发一次刷新，而
+* status 的输出从头到尾都是对的。
 */
 function createWatcher(options) {
 	const { gitDir, repoRoot, tier, onChange, pollStatus, onDegrade, debounceMs = 150, pollMs = POLL_MS, safetyPollMs = SAFETY_POLL_MS } = options;
@@ -1056,13 +1268,9 @@ function createWatcher(options) {
 	let pollInFlight = false;
 	let closed = false;
 	/**
-	* **不是「每来一个事件就把窗口往后推」的那种 debounce**。
-	*
-	* 那一种在持续写入下会一直不触发 —— 而 agent 连着改几十个文件、跑一次装依赖,
-	* 正是持续写入。这里是「第一个事件起一个窗口,窗口内的后续事件被它吞掉」,
-	* 于是风暴期间也保证每 `debounceMs` 至少刷新一次。
-	*
-	* `.git` 侧、工作区侧与轮询共用这一个窗口(见文件头)。
+	* **不是「每来一个事件就把窗口往后推」的那种 debounce**——那一种在持续写入（agent 连
+	* 着改几十个文件）下会一直不触发。这里窗口内的后续事件被第一个吞掉，风暴期间也保证每
+	* `debounceMs` 至少刷新一次。
 	*/
 	const schedule = () => {
 		if (closed || timer !== null) return;
@@ -1073,14 +1281,9 @@ function createWatcher(options) {
 		timer.unref();
 	};
 	/**
-	* 轮询一拍:取一份快照,与上一份不同就当作一次变更。
-	*
-	* 用 `setTimeout` 链而不是 `setInterval`:探针是一次 git 子进程,大仓库上未必
-	* 1.5s 内跑得完,`setInterval` 会让它们叠着跑。
-	*
-	* **首拍只建立基线,不触发刷新**(`lastSnapshot === null`):降级那一刻页面刚
-	* 重取过,再推一次纯属白刷。探针失败(仓库正被 index.lock 挡住、git 一时不可用)
-	* 也不终止轮询 —— 那是暂态,停下来就再也起不来了。
+	* 轮询一拍。`setTimeout` 链而不是 `setInterval`——探针是一次 git 子进程，大仓库上未必
+	* 1.5s 内跑得完，会叠着跑。**首拍只建立基线不刷新**；探针失败（index.lock 挡着）也不
+	* 终止轮询，那是暂态，停下来就再也起不来了。
 	*/
 	const pollOnce = async () => {
 		pollInFlight = true;
@@ -1098,12 +1301,8 @@ function createWatcher(options) {
 		armPoll();
 	};
 	/**
-	* 排下一拍。**同一个循环的两个周期,不是两套机制**:原生档跑 `safetyPollMs`(30s)
-	* 的安全轮询,降级之后自动收到 `pollMs`(1.5s)。两个定时器各排各的话,降级那一刻
-	* 要记得把前一个停掉 —— 忘了不报错,只是从此每 30s 白跑一次 git。
-	*
-	* 每次都先清掉在等的那一拍:降级时正是靠这一下把 30s 的等待按新周期提前,否则
-	* 「已降级」之后最长还要再等 30s 才有第一次轮询,而页面上标的已经是轮询了。
+	* 排下一拍。**同一个循环的两个周期，不是两套机制**：原生档 30s、降级后自动收到 1.5s。
+	* 每次都先清掉在等的那一拍——降级正是靠这一下把 30s 的等待按新周期提前。
 	*/
 	const armPoll = () => {
 		if (closed) return;
@@ -1111,24 +1310,19 @@ function createWatcher(options) {
 		pollTimer = setTimeout(() => void pollOnce(), polling ? pollMs : safetyPollMs);
 		pollTimer.unref();
 	};
-	/** 起轮询循环。**只起一次** —— 起两次就是两条链各自排各自的定时器。 */
+	/** 起轮询循环。**只起一次**——起两次就是两条链各自排各自的定时器。 */
 	const startPolling = () => {
 		if (pollLoopStarted) return;
 		pollLoopStarted = true;
 		pollOnce();
 	};
 	/**
-	* 转到轮询。**`cause` 为 null 表示这是该档位的既定形态,不是降级** —— C 档一开始
-	* 就走这条路,没有任何东西坏掉,自然也不该上报。
-	*
-	* 只有一个入口(而不是「起轮询」+「降级」两个),是因为 `polling` 这个闩只该在
-	* 一处合上:两个入口各带一份 `closed || polling` 判断时,「谁先谁后、谁的守卫
-	* 拦住了谁」就成了调用点必须自己想清楚的事,而想错的症状是多推一次降级通知。
+	* 转到轮询。**`cause` 为 null 表示这是该档位的既定形态，不是降级**（C 档一开始就走这条
+	* 路）。只有一个入口而不是「起轮询」+「降级」两个，是因为 `polling` 这个闩只该在一处
+	* 合上，两个入口时想错守卫顺序的症状是多推一次降级通知。
 	*
-	* **不可逆,而且只上报一次**:一次 ENOSPC 往往连着把几个 watcher 全打下来,
-	* 每个都上报的话前端会收到一串重复的降级通知。也**不尝试恢复原生监听** ——
-	* 恢复要么靠定期重试(在真的没有配额时就是每隔一会儿遍历一次整棵树)、要么靠猜,
-	* 而轮询已经是功能完整的通路,唯一代价是 1.5s 延迟。
+	* **不可逆，而且只上报一次**：一次 ENOSPC 往往连着把几个 watcher 全打下来。也不尝试
+	* 恢复原生监听——轮询是功能完整的通路，唯一代价是 1.5s 延迟。
 	*/
 	const usePolling = (cause) => {
 		if (closed || polling) return;
@@ -1139,49 +1333,34 @@ function createWatcher(options) {
 	};
 	const toError = (cause) => cause instanceof Error ? cause : new Error(String(cause));
 	/**
-	* C 档的轮询要在 `.git` 侧之前起,否则那边一个 watch 失败会被当成降级上报:
-	* stderr 打一行、再往刚连上的客户端推一个 `change`,而 `mode` 从头到尾就是
-	* `polling`,没有任何东西真的变过。
-	*
-	* 「哪档以轮询为既定形态」只此一份判据(`initialMode`)—— server 那侧在监听还没
-	* 懒起时也读它来答 `/api/state`,各写各的话两边会在加档位时静默分家。
+	* C 档的轮询要在 `.git` 侧之前起，否则那边一个 watch 失败会被当成降级上报，而 `mode`
+	* 从头到尾就是 `polling`。「哪档以轮询为既定形态」只此一份判据(`initialMode`)——
+	* server 那侧也读它来答 `/api/state`，各写各的会在加档位时静默分家。
 	*/
 	if (initialMode(tier) === "polling") usePolling(null);
 	else
  /**
-	* 原生档的低频安全轮询。**直接起循环而不经 `usePolling`**:那个闩一合上
-	* 就意味着「已降级」,而这里没有任何东西坏掉 —— `mode` 必须还是 `native`,
-	* 否则页面会把一次完全正常的运行标成降级。首拍照例只建立基线。
+	* 原生档的安全轮询**直接起循环而不经 `usePolling`**：那个闩一合上就意味着「已降级」，
+	* 而这里没有任何东西坏掉，`mode` 必须还是 `native`。
 	*/
 	startPolling();
 	for (const dir of gitWatchDirs(gitDir)) {
 		/**
-		* **只有 `gitDir` 自己那条算主力**(见 gitWatchDirs 的注释):提交写 `index` 与
-		* `COMMIT_EDITMSG`、切分支写 `HEAD`、fetch 写 `FETCH_HEAD`,全都直接落在它下面。
-		* `refs/` 那两条是锦上添花,它们失败(权限、网络盘)不值得把整个工具**不可逆地**
-		* 拖进轮询 —— 那样 UI 会永远标着「轮询刷新」、进程永远每 1.5s 起一次 git,
-		* 而实际上什么都没坏。
+		* **只有 `gitDir` 自己那条算主力**：`refs/` 那两条失败（权限、网络盘）不值得把整个
+		* 工具**不可逆地**拖进轮询——那样 UI 永远标着「轮询刷新」，而实际上什么都没坏。
 		*/
 		const primary = dir === gitDir;
 		try {
 			/**
-			* **不传 `recursive`**(见 gitWatchDirs 的注释);`persistent: false` 是说
-			* 监听不吊住事件循环。
-			*
-			* **filename 一概不看**。它可能为 null,而这几个目录里的任何写入都
-			* 值得刷新一次:非递归就是真的非递归 —— macOS 已实测(2026-08-11),
-			* Linux 的 inotify 与 Windows 的 `bWatchSubtree=FALSE` 按机制如此 —— 于是
-			* `objects/` 的海量写入根本到不了这里,没有需要按名字排除的东西。曾按
-			* 「macOS 会漏过来」加过一个顶层段过滤,那是把**建流窗口的补报**(建流前一刻的
-			* 写入会被补进来一两条)误读成了嵌套事件。
+			* **不传 `recursive`**；`persistent: false` 是说监听不吊住事件循环。**filename 一概
+			* 不看**：它可能为 null，而非递归就是真的非递归，`objects/` 的海量写入到不了这里，
+			* 没有需要按名字排除的东西。
 			*/
 			const w = watch(dir, { persistent: false }, () => schedule());
 			w.on("error", (cause) => {
 				/**
-				* 出错的 watcher 已经不再送事件了(Node 在 emit 之前就把 handle 关了),
-				* 留在数组里只会让 `size` 虚高 —— 而 `size` 正是调用方判断「`.git` 侧还
-				* 活着吗」的唯一依据。虚高的那份不会报错,只是判据从此对着一个空壳返回
-				* 「还活着」。
+				* 出错的 watcher 已经不再送事件，留在数组里只会让 `size` 虚高——而 `size` 正是
+				* 「`.git` 侧还活着吗」的唯一依据，虚高的那份不报错，只是对着空壳答「还活着」。
 				*/
 				const at = gitWatchers.indexOf(w);
 				if (at !== -1) gitWatchers.splice(at, 1);
@@ -1193,25 +1372,17 @@ function createWatcher(options) {
 		}
 	}
 	/**
-	* 工作区侧,按档位分。
-	*
-	* **C 档一个递归 watch 都不建**:Node 在 Linux 上的递归实现是用户态遍历,对遍历到的
-	* 每个**普通文件**也注册一个 inotify watch,monorepo 下足以耗尽
-	* `fs.inotify.max_user_watches` —— 之后整机所有依赖 inotify 的工具(包括用户自己的
-	* 编辑器)开始报 ENOSPC。那是本工具唯一可能对用户机器造成的外部副作用。
+	* 工作区侧，按档位分。**C 档一个递归 watch 都不建**：Node 在 Linux 上的递归实现是用户
+	* 态遍历，对每个**普通文件**也注册一个 inotify watch,monorepo 下足以耗尽
+	* `fs.inotify.max_user_watches`——之后整机依赖 inotify 的工具（含用户的编辑器）全报
+	* ENOSPC，那是本工具唯一可能对用户机器造成的外部副作用。
 	*/
 	if (tier !== "C") try {
 		const handler = (_event, filename) => {
 			/**
-			* **B 档的过滤必须在这里,也就是合并窗口之前**(红线)。放在窗口之后
-			* 等于让 `node_modules` 的写入噪声照样把窗口顶开、触发无谓刷新 —— 而
-			* 那条「`node_modules` 的嵌套子目录里批量写文件不触发刷新」正是钉这件事。
-			*
-			* A 档不在这里过滤:`ignore` 已经过滤过了(Linux 上还是**注册前跳过**,
-			* 那才是配额问题的解法)。
-			*
-			* `filename` 可能为 null(Node 文档载明即便在支持的平台上也不保证提供),
-			* 那时**放行**:漏刷一次比多刷一次糟得多。
+			* **B 档的过滤必须在这里，也就是合并窗口之前**：放在窗口之后等于让 `node_modules`
+			* 的写入噪声照样把窗口顶开。A 档由 `ignore` 过滤（Linux 上还是注册前跳过，那才是
+			* 配额问题的解法）。`filename` 可能为 null，那时**放行**——漏刷比多刷糟得多。
 			*/
 			if (tier === "B" && typeof filename === "string" && isIgnored(filename)) return;
 			schedule();
@@ -1226,14 +1397,9 @@ function createWatcher(options) {
 		}, 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 配额耗尽**,
-			* 那时候还占着一堆配额不放,伤的是用户整机的其他工具。
+			* **必须显式 `close()`，不能只把引用丢掉。** 原生 watcher 在 emit 之前就关了自己，
+			* 但 Linux 的**用户态递归实现**只 emit 一个 error，已注册的那一大批 inotify watch
+			* 全都还在——而这条路径最典型的触发原因正是配额耗尽，占着不放伤的是用户整机。
 			*/
 			w.close();
 			workspaceWatcher = null;
@@ -1271,10 +1437,8 @@ function createWatcher(options) {
 //#endregion
 //#region src/server/http/assets.ts
 /**
-* 产物目录。
-*
-* 口径是**打包后**的位置:`dist/server/main.js` → `dist/web/`。本文件在 src 下的
-* 相对位置与此无关 —— 它只作为 tsdown 的输入存在,运行时永远是那个单文件 ESM。
+* 产物目录。口径是**打包后**的位置：`dist/server/main.js` → `dist/web/`。本文件在 src 下的
+* 相对位置与此无关——它只作为 tsdown 的输入存在，运行时永远是那个单文件 ESM。
 */
 const WEB_ROOT = new URL("../web/", import.meta.url);
 const ASSETS = /* @__PURE__ */ new Map([
@@ -1296,11 +1460,9 @@ const ASSETS = /* @__PURE__ */ new Map([
 	}]
 ]);
 /**
-* 读过一次就留在内存里。
-*
-* `dist/web/` 在进程生命周期内不会变(产物由构建产生,服务端不监听它),而所有响应
-* 都带 `Cache-Control: no-store`,浏览器那侧也不缓存 —— 不留的话每次刷新都要把三个
-* 文件重新读一遍磁盘。三份加起来两百多 KB,常驻的代价可以忽略。
+* 读过一次就留在内存里。`dist/web/` 在进程生命周期内不会变，而所有响应都带
+* `Cache-Control: no-store`、浏览器那侧也不缓存——不留的话每次刷新都要把三个文件重新读一
+* 遍磁盘。三份加起来两百多 KB，常驻的代价可以忽略。
 */
 const cache = /* @__PURE__ */ new Map();
 async function readAsset(asset) {
@@ -1315,7 +1477,7 @@ async function readAsset(asset) {
 //#region src/server/http/idle.ts
 /** 宽限期。取 30-60s 区间中值。 */
 const IDLE_EXIT_MS = 45e3;
-/** 内部环境变量,名字定在。不是给用户的开关,不进 `--help` 与 README。 */
+/** 内部环境变量。不是给用户的开关，不进 `--help` 与 README。 */
 const IDLE_ENV = "DIFFTAB_IDLE_MS";
 var IdleConfigError = class extends Error {
 	constructor(message) {
@@ -1324,12 +1486,9 @@ var IdleConfigError = class extends Error {
 	}
 };
 /**
-* 读宽限期。
-*
-* **取值不合法即启动失败,不退回默认的 45s** —— 与 `DIFFTAB_WATCH_TIER`
-* 同一条理由:退回时手滑写错的那次照样启动成功、照样跑出一个看着合理的行为,
-* 于是「我验过空闲退出了」建立在一次根本没生效的强制指定上(那条用例会等满 45s
-* 而不是它以为的 800ms,表现为超时,读起来像产品坏了)。
+* 读宽限期。**取值不合法即启动失败，不退回默认的 45s**——与 `DIFFTAB_WATCH_TIER` 同一条
+* 理由：退回时手滑写错的那次照样启动成功、照样跑出一个看着合理的行为，于是「我验过空闲退出
+* 了」建立在一次根本没生效的强制指定上。
 */
 function resolveIdleMs(env = process.env) {
 	const raw = env[IDLE_ENV];
@@ -1354,17 +1513,16 @@ function createIdleWatchdog(options) {
 			timer = setTimeout(() => {
 				timer = null;
 				/**
-				* **落地前再问一次**。定时器排队与回调执行之间隔着整个事件循环的这一圈,
-				* 同一圈里完全可能刚接进一个 SSE 连接;而这个判断错了的症状是「用户正开着
-				* 页面,进程自己没了」—— 比多活 45 秒糟得多。
+				* **落地前再问一次**。定时器排队与回调执行之间隔着整个事件循环的这一圈，
+				* 同一圈里完全可能刚接进一个 SSE 连接；而这个判断错了的症状是「用户正开着
+				* 页面，进程自己没了」——比多活 45 秒糟得多。
 				*/
 				if (stopped || hasClients()) return;
 				onIdle();
 			}, idleMs);
 			/**
-			* **计时器不是进程活着的理由**,HTTP server 的监听句柄才是(与 sse.ts 的心跳、
-			* watcher 的合并窗口同一条)。不 unref 的话,close() 之后漏了 stop() 就会把
-			* 进程多吊住一个宽限期,而那种残留最难看见。
+			* **计时器不是进程活着的理由**，HTTP server 的监听句柄才是。不 unref 的话，close()
+			* 之后漏了 stop() 就会把进程多吊住一个宽限期，而那种残留最难看见。
 			*/
 			timer.unref();
 		},
@@ -1381,55 +1539,45 @@ function createIdleWatchdog(options) {
 const BIND_HOST = "127.0.0.1";
 const ALLOWED_HOSTNAMES = ["127.0.0.1", "localhost"];
 /**
-* cookie 名带上端口。
-*
-* cookie 的作用域是 host 而非 origin,**不隔离端口**:同机另一个监听
-* `127.0.0.1:<其他端口>` 的服务同样会收到我们的 cookie,反过来它设的同名 cookie
-* 也会盖掉我们的。名字里带端口,两个 difftab 实例(不同仓库、不同端口)才能
-* 在同一个浏览器里共存。
+* cookie 名带上端口。cookie 的作用域是 host 而非 origin，**不隔离端口**：同机另一个监听
+* `127.0.0.1:<其他端口>` 的服务同样会收到我们的 cookie，反过来它设的同名 cookie 也会盖掉
+* 我们的。名字里带端口，两个 difftab 实例（不同仓库、不同端口）才能在同一个浏览器里共存。
 */
 function cookieName(port) {
 	return `difftab_token_${port}`;
 }
-/** 会话 token 的秘密部分。进程生命周期内持续有效,以支持页面刷新与多标签。 */
+/** 会话 token 的秘密部分。进程生命周期内持续有效，以支持页面刷新与多标签。 */
 function createSecret() {
 	return randomBytes(32).toString("base64url");
 }
 /**
-* token 形如 `<port>.<secret>`。
-*
-* 端口写进 token 本身,是为了让服务端校验时**一并绑定校验本次会话的端口**
-* cookie 的作用域是 host 而非 origin:它会泄漏给本机其他 localhost 服务,带上端口后
-* 那份 token 在别处无法复用。
+* token 形如 `<port>.<secret>`。端口写进 token 本身，是为了让服务端校验时**一并绑定本次
+* 会话的端口**——cookie 会泄漏给本机其他 localhost 服务，带上端口后它在别处无法复用。
 */
 function composeToken(port, secret) {
 	return `${port}.${secret}`;
 }
 /**
-* 打印给用户、也拿去拉起浏览器的那个 URL。
-*
-* **只此一处**:探活复用命中时,是**另一个进程**按注册表里的 port + token 重新拼出
-* 同一个 URL 交给浏览器。两处各拼一遍的话,哪天 token 的落地方式变了
-* (换 query 名、换编码),复用那条路会拼出一个 403 的链接 —— 而它平时不走,
-* 谁也不会先注意到。
+* 打印给用户、也拿去拉起浏览器的那个 URL。**只此一处**：探活复用命中时，是**另一个进程**
+* 按注册表里的 port + token 重新拼出同一个 URL。两处各拼一遍的话，哪天 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` 是攻击者的域名。
+* 第 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、
-* 跨源重定向)是非空值,按不匹配处理 —— 那正是要挡的东西。
+* 第 2 道：**校验 `Origin`**。非空且不等于自身则拒；空是正常的（同源的导航与 GET fetch 本
+* 就不带 Origin）。`null`（沙箱化 iframe、跨源重定向）是非空值，按不匹配处理——那正是要挡
+* 的东西。
 */
 function isOriginAllowed(origin, port) {
 	if (!origin) return true;
@@ -1446,7 +1594,7 @@ function readCookieToken(header, port) {
 	}
 	return null;
 }
-/** 定长比较。长度不同直接判否 —— 长度本身不是秘密。 */
+/** 定长比较。长度不同直接判否——长度本身不是秘密。 */
 function tokensMatch(presented, expected) {
 	if (!presented) return false;
 	const a = Buffer.from(presented, "utf8");
@@ -1455,12 +1603,9 @@ function tokensMatch(presented, expected) {
 	return timingSafeEqual(a, b);
 }
 /**
-* 第 3 道之外的公共响应头。
-*
-* CSP 的后三个指令**不回退到 `default-src`**,不显式写就等于没设:
-* `'none'` 一并挡掉被 iframe 嵌套、`<base>` 改写相对 URL 与表单外发。
-* 不开 `'unsafe-inline'` 是构建链路顺带解锁的 —— 产物是独立的 .js / .css、
-* 页面无内联脚本,才有条件不开。
+* 第 3 道之外的公共响应头。CSP 的后三个指令**不回退到 `default-src`**，不显式写就等于没设：
+* `'none'` 一并挡掉被 iframe 嵌套、`<base>` 改写相对 URL 与表单外发。不开 `'unsafe-inline'`
+* 是构建链路顺带解锁的——产物是独立的 .js / .css、页面无内联脚本，才有条件不开。
 */
 const SECURITY_HEADERS = {
 	"Cache-Control": "no-store",
@@ -1477,11 +1622,9 @@ const SECURITY_HEADERS = {
 	].join("; ")
 };
 /**
-* 把 token 落成 cookie 的 Set-Cookie 值。
-*
-* `HttpOnly; SameSite=Strict` + 随后 302 掉 query,避免 token 长期滞留在浏览器
-* 历史、地址栏和日志中。不设 `Secure` —— 那会让 http://127.0.0.1
-* 上的 cookie 直接不生效。
+* 把 token 落成 cookie 的 Set-Cookie 值。`HttpOnly; SameSite=Strict` + 随后 302 掉 query，
+* 避免 token 长期滞留在浏览器历史、地址栏和日志中。不设 `Secure`——那会让
+* http://127.0.0.1 上的 cookie 直接不生效。
 */
 function tokenCookie(port, token) {
 	return `${cookieName(port)}=${token}; Path=/; HttpOnly; SameSite=Strict`;
@@ -1490,22 +1633,17 @@ function tokenCookie(port, token) {
 //#endregion
 //#region src/server/shared/protocol.ts
 /**
-* 服务端 SSE 心跳周期(约 15s)。
-*
-* **它是协议的一部分,所以定在这里而不是 http/sse.ts**:后端拿它当发送周期,前端
-* 拿它当「对端还在」的判据(`web/state/events.ts` 的 `STALE_MS` 由它推出来)。两边
-* 各写一个 15000,改周期时只改一边不会报错、也没有任何用例会红 —— 前端的死连接
-* 判定就此静默失准,而症状只是「有时候刷不出来」。
+* 服务端 SSE 心跳周期（约 15s）。**它是协议的一部分，所以定在这里而不是 http/sse.ts**：
+* 后端拿它当发送周期，前端拿它当「对端还在」的判据。两边各写一个 15000，改周期时只改一边
+* 不会报错、也没有任何用例会红——前端的死连接判定就此静默失准，症状只是「有时候刷不出来」。
 */
 const HEARTBEAT_MS = 15e3;
 
 //#endregion
 //#region src/server/http/sse.ts
 /**
-* 一条 SSE 消息的线格式。
-*
-* `data` 一律是一行 JSON:多行正文要逐行加 `data: ` 前缀,而正文里一旦出现换行
-* (将来带上文件名之类)就会静默变成半条消息。`JSON.stringify` 保证不含裸换行。
+* 一条 SSE 消息的线格式。`data` 一律是一行 JSON：多行正文要逐行加 `data: ` 前缀，而正文里
+* 一旦出现换行就会静默变成半条消息，`JSON.stringify` 保证不含裸换行。
 */
 function formatEvent(name, data) {
 	return `event: ${name}\ndata: ${JSON.stringify(data)}\n\n`;
@@ -1518,10 +1656,9 @@ function createSseChannel({ heartbeatMs = HEARTBEAT_MS, onChange } = {}) {
 			client.write(chunk);
 		} catch {
 			/**
-			* **真正把死连接摘出去的不是这里**,是端点上的 `'close'` / `'error'` 监听器:
-			* `ServerResponse.write()` 对已结束或已销毁的响应不会同步抛,失败是异步的。
-			* 这层 catch 只保证一个客户端写炸了不会让这一轮广播半路夭折 —— 后面的连接
-			* 照样收得到。
+			* **真正把死连接摘出去的不是这里**，是端点上的 `'close'` / `'error'` 监听器——
+			* `ServerResponse.write()` 对已结束或已销毁的响应不会同步抛，失败是异步的。这层
+			* catch 只保证一个客户端写炸了不会让这一轮广播半路夭折。
 			*/
 			clients.delete(client);
 		}
@@ -1554,10 +1691,8 @@ function createSseChannel({ heartbeatMs = HEARTBEAT_MS, onChange } = {}) {
 //#endregion
 //#region src/server/http/server.ts
 /**
-* 错误信息不含绝对路径。
-*
-* git 的 fatal 文本里经常带着完整仓库路径,原样回给页面就把本机目录结构泄漏进了
-* 一个任何本地页面都可能读到的响应体。
+* 错误信息不含绝对路径：git 的 fatal 文本经常带着完整仓库路径，原样回给页面就把本机
+* 目录结构泄漏进了一个任何本地页面都可能读到的响应体。
 */
 function sanitizeMessage(message, repoRoot) {
 	const home = homedir();
@@ -1579,11 +1714,8 @@ function sendJson(res, status, body) {
 }
 async function startServer(repo, options = {}) {
 	/**
-	* 出站错误一律经此发出,**sanitize 就做在这里**。
-	*
-	* 早先只在兜底的 500 分支上过一次 sanitizeMessage,于是「响应体不含绝对路径」这条
-	* 不变式实际挂在「以后新增的错误消息恰好都不带路径」上 —— 那不是不变式,是巧合。
-	* 放在唯一出口上,新增分支自动被覆盖。
+	* 出站错误一律经此发出，**sanitize 就做在这里**。只在兜底的 500 分支上做时，「响应体
+	* 不含绝对路径」实际挂在「以后新增的消息恰好都不带路径」上——那不是不变式，是巧合。
 	*/
 	const sendError = (res, status, code, message) => {
 		sendJson(res, status, { error: {
@@ -1596,29 +1728,25 @@ async function startServer(repo, options = {}) {
 	let token = "";
 	let port = 0;
 	/**
-	* 档位在**启动时**定,不等第一个订阅者。
-	*
-	* `/api/state` 里就带着它,而那个请求先于任何 SSE 连接到达;更要紧的是
-	* `DIFFTAB_WATCH_TIER` 写错时要在启动那一刻响亮地失败,而不是等到某次订阅。
-	* 判定本身是纯计算(读 `process.versions.node` 与 `process.platform`),不落在
-	* 300ms 冷启动预算上。
+	* 档位在**启动时**定，不等第一个订阅者：`/api/state` 里就带着它，而
+	* `DIFFTAB_WATCH_TIER` 写错时要在启动那一刻响亮地失败。判定是纯计算，不落在 300ms
+	* 冷启动预算上。
 	*/
 	const tier = resolveTier();
 	const tierWarning = forcedTierWarning();
 	if (tierWarning) process.stderr.write(`difftab: ${tierWarning}\n`);
 	/**
-	* 通道与空闲计时器互相接线:连接数一变(add / remove)就 `touch` 一次。
-	* 端点那侧因此**不必记得**在断连时重新武装 —— 见 sse.ts 的 `onChange`。
+	* 通道与空闲计时器互相接线：连接数一变(add / remove)就 `touch` 一次。
+	* 端点那侧因此**不必记得**在断连时重新武装——见 sse.ts 的 `onChange`。
 	*/
 	const events = createSseChannel({ onChange: () => idle.touch() });
 	/**
-	* 空闲退出的计时器。**判据是 SSE 连接数,但任何通过校验的请求都重置
-	* 计时** —— 连接数是正面判据,而它在两种情形下同样是 0:刚被探活复用、浏览器
-	* 还在启动的那几秒,以及页面活着但 SSE 被中间层悄悄回收了。两者取并集,退出条件
-	* 因此严格弱于「连接数为 0 持续 45s」,只会晚退不会早退。
+	* 空闲退出的计时器。**判据是 SSE 连接数，但任何通过校验的请求都重置计时**——连接数
+	* 为 0 也可能是「刚被探活复用、浏览器还在启动」或「页面活着但 SSE 被中间层回收了」。
+	* 两者取并集，退出条件因此严格弱于「连接数为 0 持续 45s」，只会晚退不会早退。
 	*
-	* `resolveIdleMs()` 在这里(listen 之前)读环境变量:写错的取值要在启动那一刻
-	* 响亮地失败,而不是等到 45 秒后什么都没发生。
+	* `resolveIdleMs()` 在这里（listen 之前）读环境变量：写错的取值要在启动那一刻失败，
+	* 而不是等到 45 秒后什么都没发生。
 	*/
 	const idle = createIdleWatchdog({
 		idleMs: resolveIdleMs(),
@@ -1626,13 +1754,11 @@ async function startServer(repo, options = {}) {
 		onIdle: () => options.onIdle?.()
 	});
 	/**
-	* 监听**懒起**:第一个 SSE 订阅者到了才建,起了就一直留到关服务。
+	* 监听**懒起**：第一个 SSE 订阅者到了才建，起了就一直留到关服务。
 	*
-	* 两头都是有理由的。懒起是因为冷启动门禁量的是「监听成功并打印 URL」,而
-	* S3b2 的 A/B 档要在 repoRoot 上建递归 watch —— Linux 上那是用户态遍历整棵树,
-	* 大仓库里足以把 300ms 预算一口吃掉,而此刻还没有任何人在等变更通知。
-	* 不随最后一个订阅者关掉,则是因为刷新页面 = 断开再连,那会让上面那趟遍历
-	* 每刷新一次重来一遍;空闲着的原生 watch 本身开销接近零(资源占用项)。
+	* 懒起是因为冷启动门禁量的是「监听成功并打印 URL」，而 A / B 档要在 repoRoot 上建递归
+	* watch——Linux 上那是用户态遍历整棵树，大仓库里足以把 300ms 预算一口吃掉。不随最后
+	* 一个订阅者关掉，是因为刷新页面 = 断开再连，那会让那趟遍历每刷新一次重来一遍。
 	*/
 	let watcher = null;
 	const ensureWatcher = () => {
@@ -1643,26 +1769,20 @@ async function startServer(repo, options = {}) {
 			tier,
 			onChange: () => events.send("change", {}),
 			/**
-			* 轮询探针。**注入而不是让 watch/ 自己去调 git**:git 子进程只许出现在
-			* server/git(架构边界不变式 1),而依赖方向里也没有 watch → git 这条边。
-			* 传进去的是主查询本身(`readStatusRaw` 用的就是 `STATUS_ARGS`),于是「轮询
-			* 与主查询逐字相同」这条红线在这里是**一处赋值**而不是两处各自维护的巧合。
-			* 拦住它的不是类型(签名只是 `() => Promise<string>`),是这个唯一的注入点
-			* 加上冒烟里那条「C 档在已存在的未跟踪目录里新增文件要推出 change」。
+			* 轮询探针。**注入而不是让 watch/ 自己去调 git**:git 子进程只许出现在 server/git，
+			* 依赖方向里也没有 watch → git 这条边。传进去的是主查询本身（`readStatusRaw` 用的
+			* 就是 `STATUS_ARGS`），于是「轮询与主查询逐字相同」在这里是**一处赋值**而不是两处
+			* 各自维护的巧合。
 			*
-			* **已知的覆盖边界**:`/api/state` 里的 `operation`不来自 status 输出,
-			* 所以这条探针看不见它。三档都在 `gitDir` 上建了非递归 watch,`MERGE_HEAD` /
-			* `rebase-merge/` 的增删就落在那儿,正常情况下照样推得出 change;只有**那条
-			* watch 自己也失败、整体落到轮询**之后,一次「只动 git 目录、不动 HEAD 也不动
-			* 工作区」的操作(实际上只有 `rebase --quit` 这一类)才会让标注停在旧值上。
-			* 不为它把探针拆成两个来源:那会让「轮询与主查询是同一条命令」不再是构造上的
-			* 事实,而换来的是一个交集极窄的窗口。
+			* **已知的覆盖边界**：`operation` 不来自 status 输出，这条探针看不见它。三档都在
+			* `gitDir` 上建了非递归 watch，正常情况下照样推得出 change；只有**那条 watch 自己也
+			* 失败、整体落到轮询**之后，一次只动 git 目录的操作（`rebase --quit` 一类）才会让
+			* 标注停在旧值上。不为它把探针拆成两个来源。
 			*/
 			pollStatus: () => readStatusRaw(repo.root),
 			/**
-			* 降级为轮询(兜底)。**推一个 `change` 是必需的**:`mode` 只在
-			* `/api/state` 里,前端不重取就看不到降级 —— 而它自己无从推断这件事,
-			* 于是页面会一直标着「原生监听」直到下一次真的有文件变更。
+			* 降级为轮询（兜底）。**推一个 `change` 是必需的**：`mode` 只在 `/api/state` 里，
+			* 前端不重取就看不到降级，页面会一直标着「原生监听」直到下一次真的有文件变更。
 			*/
 			onDegrade: (cause) => {
 				process.stderr.write(`difftab: file watching degraded — ${sanitizeMessage(cause.message, repo.root)}\n`);
@@ -1671,11 +1791,8 @@ async function startServer(repo, options = {}) {
 		});
 	};
 	/**
-	* 当前的监听状态(`WatchState`)。
-	*
-	* **每次请求现算,不是启动时算一次**:降级发生在运行中,而算一次存起来的那份
-	* 不会报错,只是从此永远说「原生监听」。监听懒起(见上),还没起来时按档位的
-	* 既定形态答 —— C 档从第一份 `/api/state` 起就该是 `polling`。
+	* 当前的监听状态(`WatchState`)。**每次请求现算**：降级发生在运行中，算一次存起来的
+	* 那份不报错，只是从此永远说「原生监听」。监听懒起，还没起来时按档位的既定形态答。
 	*/
 	const currentWatchState = () => ({
 		mode: watcher?.mode ?? initialMode(tier),
@@ -1713,17 +1830,14 @@ async function startServer(repo, options = {}) {
 			return;
 		}
 		/**
-		* 到这里才算「有人在」,**三道校验之前不算**(上面那个 302 分支同理:token 对了
-		* 才 touch)。放在函数开头看起来更省事,代价是本机任何一个端口扫描器都能无限期
-		* 续命一个该退的进程 —— 而承诺是「不留后台常驻进程」。
+		* 到这里才算「有人在」，**三道校验之前不算**（上面那个 302 分支同理）。放在函数开头
+		* 更省事，代价是本机任何一个端口扫描器都能无限期续命一个该退的进程。
 		*/
 		idle.touch();
 		/**
-		* 只读工具不需要任何非幂等端点。
-		*
-		* **必须留在三道校验之后,不得挪回函数开头** —— 理由(泄漏服务存在性)
-		* 见安全那节。副作用是上面那个 query token 分支也排在它前面:带合法
-		* token 的非幂等请求会先被 302 换成 cookie 而不是 405。它已经过了三道校验,是取舍。
+		* 只读工具不需要任何非幂等端点。**必须留在三道校验之后**，否则泄漏服务存在性。副作用
+		* 是带合法 token 的非幂等请求会先被上面那个分支 302 换成 cookie 而不是 405——它已经
+		* 过了三道校验，是取舍。
 		*/
 		if (req.method !== "GET" && req.method !== "HEAD") {
 			sendError(res, 405, "method-not-allowed", "only GET is supported");
@@ -1746,14 +1860,10 @@ async function startServer(repo, options = {}) {
 				return;
 			}
 			/**
-			* 探活复用的应答。**消费者是下一个 CLI 进程,不是前端。**
-			*
-			* 它答的是「这个端口现在还是**这个仓库**的实例吗」。光有三道校验答不了:
-			* token 不匹配只证明「不是我们这一份会话」,而端口被系统回收给另一个仓库的
-			* difftab 时,那边同样有一份合法 token —— 只不过不是我们记在注册表里的那个,
-			* 于是它会 403、被判为陈旧,正确。真正需要这个正文的是相反的一侧:200 之后
-			* 还要确认路径确实是我们这个仓库,否则「复用」会把用户带到别人的页面(
-			* 排除 pid 判活也是同一条理由)。
+			* 探活复用的应答。**消费者是下一个 CLI 进程，不是前端。** 它答的是「这个端口现在
+			* 还是**这个仓库**的实例吗」：光有三道校验答不了——token 不匹配只证明「不是我们
+			* 这一份会话」，而 200 之后还要确认路径确实是我们这个仓库，否则「复用」会把用户带到
+			* 别人的页面（排除 pid 判活也是同一条理由）。
 			*/
 			case "/api/instance":
 				sendJson(res, 200, {
@@ -1775,9 +1885,26 @@ async function startServer(repo, options = {}) {
 				return;
 			}
 			/**
-			* SSE。**三道校验在上面已经统一走过**,这里没有例外分支 ——
-			* 「所有端点(含 SSE)统一校验」不留例外。
+			* 文件浏览器的目录树，**一次只回一层**。`path` 缺省即仓库根——根是这个端点唯一一个
+			* 天天要用的取值，让它必须显式传一个空串只是把 `?path=` 写进每一次调用。
 			*/
+			case "/api/tree":
+				sendJson(res, 200, await readTree(repo.root, url.searchParams.get("path") ?? ""));
+				return;
+			/**
+			* 单个文件的只读内容。**`path` 必填**，与 `/api/tree` 刻意不同：树有一个自然的默认
+			* 值（根），而「默认读哪个文件」不存在，缺省时静默给一份别的内容比 400 更糟。
+			*/
+			case "/api/file": {
+				const path = url.searchParams.get("path");
+				if (!path) {
+					sendError(res, 400, "bad-request", "path is required");
+					return;
+				}
+				sendJson(res, 200, await readFileContent(repo.root, path));
+				return;
+			}
+			/** SSE。**三道校验在上面已经统一走过**，这里没有例外分支。 */
 			case "/api/events": {
 				const headers = {
 					...SECURITY_HEADERS,
@@ -1792,33 +1919,23 @@ async function startServer(repo, options = {}) {
 				res.writeHead(200, headers);
 				res.write(": connected\n\n");
 				/**
-				* 两个监听器都必须挂在 `events.add` **之前**。
-				*
-				* `close` 覆盖全部断开路径(关标签、刷新、进程被 kill 掉对端);`error` 则是
-				* 长连接独有的一条:写向一条已经结束的响应,`write()` 不会同步抛,而是在 `res`
-				* 上**异步** emit 一个 `'error'` —— 一个零监听器的 EventEmitter 收到 `'error'`
-				* 是整个进程带着裸栈崩掉,而不是丢一条心跳。
+				* 两个监听器都必须挂在 `events.add` **之前**。`close` 覆盖全部断开路径（关标签、
+				* 刷新、对端被 kill）;`error` 是长连接独有的一条——写向一条已经结束的响应，
+				* `write()` 不同步抛，而是在 `res` 上**异步** emit `'error'`，而零监听器的
+				* EventEmitter 收到 `'error'` 是整个进程带着裸栈崩掉。顺序则是因为 add 之后、挂上
+				* 之前断开的话就再没人把它摘出去：心跳一直写向死响应，空闲退出也永远数不回 0。
 				*
-				* 顺序则是因为 add 之后、挂上之前的那一小段里断开的话,就再没人把它摘出去:
-				* 心跳会一直写向一条死响应,空闲退出也永远数不回 0。
-				*/
-				/**
-				* 断开之后**必须再 touch 一次**:计时只在 `touch()` 里起,而这是「最后一个
-				* 标签被关掉」在服务端的唯一形态。少了它,进程要等到下一个请求(而那正是
-				* 没有人再发的东西)才想起来自己已经空了 —— 症状是关完浏览器留一个永久
-				* 常驻进程,与那条验收项正相反。
+				* 断开之后**必须再 touch 一次**（计时只在 `touch()` 里起）：这是「最后一个标签被
+				* 关掉」在服务端的唯一形态，少了它就是关完浏览器留一个永久常驻进程。
 				*/
 				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` 与静态资源,那些请求会一起卡住,首屏因此变慢,
-				* 而症状与「监听很慢」毫无相似之处。
+				* **监听推到下一拍再起**，不在这个请求里同步建：Linux 上 A / B 档的递归 watch 是
+				* 用户态的同步遍历，大仓库上要跑几百毫秒到数秒，留在这里占住的是整条事件循环——
+				* 页面此刻正并发发着 `/api/state` 与静态资源，首屏因此一起卡住，而症状与「监听很
+				* 慢」毫无相似之处。
 				*/
 				setImmediate(ensureWatcher);
 				return;
@@ -1832,7 +1949,7 @@ async function startServer(repo, options = {}) {
 				res.destroy();
 				return;
 			}
-			if (cause instanceof DiffRequestError) {
+			if (cause instanceof WorktreeError) {
 				sendError(res, 400, cause.code, cause.message);
 				return;
 			}
@@ -1860,11 +1977,9 @@ async function startServer(repo, options = {}) {
 	port = address.port;
 	token = composeToken(port, secret);
 	/**
-	* **宽限期从这一刻就开始计,不等第一个客户端**。
-	*
-	* 等第一个客户端才起计时看着更稳妥,实则把「浏览器压根没拉起来」整类情形
-	* (headless、无 `xdg-open`、`--no-open` 之后用户改了主意)变成永久常驻的后台进程。
-	* 45 秒足够覆盖冷启动一个浏览器进程的 2-5s。
+	* **宽限期从这一刻就开始计，不等第一个客户端**：等第一个客户端才起计时，会把「浏览器
+	* 压根没拉起来」（headless、无 `xdg-open`、`--no-open` 之后改主意）整类情形变成永久
+	* 常驻的后台进程。45 秒足够覆盖冷启动一个浏览器进程的 2-5s。
 	*/
 	idle.touch();
 	return {
@@ -1884,10 +1999,8 @@ async function startServer(repo, options = {}) {
 //#endregion
 //#region src/server/cli/browser.ts
 /**
-* 平台 → 命令的固定映射。**纯函数,便于测试逐条钉住**。
-*
-* Windows 那串里的空串不是笔误:它是 `start` 的窗口标题占位,少了它,带引号的 URL
-* 会被当作标题吞掉,浏览器根本不开。
+* 平台 → 命令的固定映射。**纯函数，便于测试逐条钉住**。Windows 那串里的空串不是笔误：
+* 它是 `start` 的窗口标题占位，少了它，带引号的 URL 会被当作标题吞掉，浏览器根本不开。
 */
 function browserCommand(platform, url) {
 	if (platform === "darwin") return {
@@ -1909,18 +2022,15 @@ function browserCommand(platform, url) {
 	};
 }
 /**
-* CI 与冷启动测量里必须能关掉这个调用,否则每跑一次测试就弹一次浏览器。
-*
-* 这不是「为开发便利而放宽的分支」—— 它不改变任何校验,只决定要不要多起一个进程。
+* CI 与冷启动测量里必须能关掉这个调用，否则每跑一次测试就弹一次浏览器。这不是「为开发
+* 便利而放宽的分支」——它不改变任何校验，只决定要不要多起一个进程。
 */
 function browserDisabled(env = process.env) {
 	return Boolean(env.DIFFTAB_NO_OPEN);
 }
 /**
-* 返回是否真的尝试了拉起。
-*
-* 失败(没有 `xdg-open`、headless 环境)只打印 URL 让用户自行访问,**不作为启动失败**。
-* URL 在调用本函数之前已经打印过了,所以这里什么都不用补。
+* 返回是否真的尝试了拉起。失败（没有 `xdg-open`、headless 环境）只打印 URL 让用户自行
+* 访问，**不作为启动失败**；URL 在调用本函数之前已经打印过了。
 */
 function openBrowser(url) {
 	if (browserDisabled()) return false;
@@ -1941,28 +2051,22 @@ function openBrowser(url) {
 //#endregion
 //#region src/server/cli/registry.ts
 /**
-* 注册表目录。
-*
-* **绝不能写进 `.git/` 或工作区** —— 那既污染 `git status`,也实质违背零写操作承诺。
-* `os.tmpdir()` 的权限因平台而异,Linux 上是 `/tmp`(1777,
-* 同机其他用户可读),所以这里再套一层每用户私有子目录,文件本身另有 0o600。
+* 注册表目录。**绝不能写进 `.git/` 或工作区**——那既污染 `git status`，也实质违背零写
+* 操作承诺。`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` 这类差异照样能让两个活着的实例互不相认,
-* 于是同一个仓库开出第二个进程。两处各写一份归一化,漂移是静默的。
+* 把仓库路径归一成注册表的键。写入侧给的是 `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 永远找不
+* 到正在运行的后端，症状是「后端明明起着却说没找到」。
+*
+* **探活比对仓库身份时用的也是这一份**：两处各写一份归一化，漂移是静默的——症状是同一个
+* 仓库开出第二个进程。
 */
 function normalizeRepoKey(repoRoot) {
 	const abs = resolve(repoRoot);
@@ -1972,16 +2076,14 @@ function normalizeRepoKey(repoRoot) {
 		return abs;
 	}
 }
-/** 文件名用仓库绝对路径的 hash,避免把路径本身暴露在一个全局可读的目录名里。 */
+/** 文件名用仓库绝对路径的 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。
+* 写入注册表。`0o600` 必须**配合 `O_EXCL` 在创建时**给出(`'wx'` + mode)，而不是先建后
+* chmod——后者留下一个竞态窗口，窗口里文件是可读的，而它存着本次会话的 token。
 */
 function writeExclusive(path, payload) {
 	const fd = openSync(path, "wx", 384);
@@ -2003,13 +2105,10 @@ function writeRegistry(entry) {
 	} catch (cause) {
 		if (cause.code !== "EEXIST") throw cause;
 		/**
-		* 走到这里说明**探活已经判过它是陈旧的**(start.ts 命中就不会再启动,更不会
-		* 写注册表),所以覆盖是对的。
-		*
-		* 保留 `O_EXCL` + 显式 unlink 而不是改成 `'w'`:两者的区别只在这个分支要不要
-		* 显式承认「我在覆盖别人的条目」。而那条 `0o600` 必须在创建时给出的要求
-		* 也只有 `'wx'` 满足 —— `'w'` 对已存在的文件根本不套用 mode,一次遗留的
-		* 0644 条目会被原样沿用,里面躺着本次会话的 token。
+		* 走到这里说明**探活已经判过它是陈旧的**（start.ts 命中就不会再启动，更不会写注册
+		* 表），所以覆盖是对的。保留 `O_EXCL` + 显式 unlink 而不是改成 `'w'`：那条「`0o600`
+		* 必须在创建时给出」只有 `'wx'` 满足——`'w'` 对已存在的文件根本不套用 mode，一次遗留
+		* 的 0644 条目会被原样沿用，里面躺着本次会话的 token。
 		*/
 		unlinkSync(path);
 		writeExclusive(path, payload);
@@ -2017,11 +2116,9 @@ function writeRegistry(entry) {
 	return path;
 }
 /**
-* 读取注册表。dev proxy(见 vite.config.ts)与探活(probe.ts)共用;读不到、或者
-* 读到一条用不了的条目,一律返回 null。
-*
-* **「这条目还能用吗」只在这里判一次**:端口得是一个真能连的端口号、token 不能是
-* 空串。放在消费侧各判各的话,两个消费者迟早对「可用」有两套定义,而分歧的表现是
+* 读取注册表。dev proxy（见 vite.config.ts）与探活共用；读不到、或者读到一条用不了的条目，
+* 一律返回 null。**「这条目还能用吗」只在这里判一次**：端口得是一个真能连的端口号、token
+* 不能是空串。放在消费侧各判各的话，两个消费者迟早对「可用」有两套定义，而分歧的表现是
 * dev proxy 与探活对同一条陈旧条目给出不同结论。
 */
 function readRegistry(repoRoot) {
@@ -2035,7 +2132,7 @@ function readRegistry(repoRoot) {
 		return null;
 	}
 }
-/** 退出时清理。只删自己写的那一条,免得把另一个实例的条目带走。 */
+/** 退出时清理。只删自己写的那一条，免得把另一个实例的条目带走。 */
 function removeRegistry(repoRoot) {
 	const path = registryPath(repoRoot);
 	let raw;
@@ -2057,28 +2154,21 @@ function removeRegistry(repoRoot) {
 //#endregion
 //#region src/server/cli/probe.ts
 /**
-* 探活超时。**不取更短**。
-*
-* 被探的实例可能正卡在那趟用户态递归遍历里(Linux 大仓库上几百毫秒到数秒),
-* 超时过短的代价不是慢一点,而是**给同一个仓库起了第二个进程**——正是本模块要防的
-* 那件事。反过来这 1.5s 平时根本走不到:注册表不存在时压根不探(常态,冷启动门禁
-* 不受影响),端口已死时 localhost 上的 `ECONNREFUSED` 是立即返回的。
+* 探活超时。**不取更短**：被探的实例可能正卡在那趟用户态递归遍历里（Linux 大仓库上几百
+* 毫秒到数秒），超时过短的代价不是慢一点，而是**给同一个仓库起了第二个进程**。反过来这
+* 1.5s 平时根本走不到——注册表不存在时压根不探，端口已死时 localhost 上的
+* `ECONNREFUSED` 是立即返回的。
 */
 const PROBE_TIMEOUT_MS = 1500;
 /**
-* 正文读到这么多还没完就放弃。
-*
-* 端口可能已经归了一个完全无关的服务,而它的 `/api/instance` 可以是任何东西 ——
-* 一个流式响应会让下面那句 `body +=` 一直涨下去。上限之内,一份真正的
-* `InstanceInfo` 绰绰有余。
+* 正文读到这么多还没完就放弃：端口可能已经归了一个完全无关的服务，而它的 `/api/instance`
+* 可以是任何东西——一个流式响应会让下面那句 `body +=` 一直涨下去。
 */
 const MAX_BODY_BYTES = 65536;
 /**
-* 向记录的端口要一份 `InstanceInfo`。任何不顺利一律返回 null(= 按陈旧处理)。
-*
-* **带上 token 与合规的 `Host`**:三道校验一视同仁,探活不是例外 ——
-* 那也正是「端口已经归了另一个仓库的 difftab」这种情形的判据:它那份 token
-* 不是我们记下的这个,于是 403、判陈旧,正确。
+* 向记录的端口要一份 `InstanceInfo`。任何不顺利一律返回 null（= 按陈旧处理）。**带上
+* token 与合规的 `Host`**：三道校验一视同仁，探活不是例外——那也正是「端口已经归了另一个
+* 仓库的 difftab」这种情形的判据：它那份 token 不是我们记下的这个，于是 403、判陈旧。
 */
 function requestInstance(entry, timeoutMs) {
 	return new Promise((resolvePromise) => {
@@ -2097,16 +2187,14 @@ function requestInstance(entry, timeoutMs) {
 				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()` 就把启动整个吊死,没有任何输出。
+			* **响应头到手之后，`req` 就不再是错误的出口了**：此后 `req.destroy()` 与对端中途
+			* 断开都只落在 `res` 上（`'aborted'` 随后 `'error': ECONNRESET`），而
+			* `IncomingMessage` 会把没人听的 `'error'` 自己吞掉——于是下面那两处 `destroy()`
+			* （超时、正文过大）既走不到 `'end'`、也走不到 `req.on('error')`，**这个 Promise
+			* 永远不 settle**,`start.ts` 里那句 `await findLiveInstance()` 把启动整个吊死。
 			*
-			* `'close'` 是 `res` 上唯一覆盖全部结局的事件;正常读完时它排在 `'end'`
-			* 之后,那时早已 resolve 过,再 resolve 一次没有作用(首次为准)。
+			* `'close'` 是 `res` 上唯一覆盖全部结局的事件；正常读完时它排在 `'end'` 之后，那时
+			* 早已 resolve 过，再 resolve 一次没有作用（首次为准）。
 			*/
 			res.on("close", () => resolvePromise(null));
 			let body = "";
@@ -2136,13 +2224,10 @@ function requestInstance(entry, timeoutMs) {
 		});
 		req.on("error", () => resolvePromise(null));
 		/**
-		* 超时用 `setTimeout` 而不是 `req.setTimeout`:后者只管**socket 空闲**,
-		* 一个每 200ms 吐一个字节的第三方服务能让它永远不触发。这里要的是整次探活的
-		* 墙钟上限。
-		*
-		* **`destroy()` 之后必须自己 resolve**:响应头已经到手时,这一下的错误落在 `res`
-		* 上而不是 `req` 上(见上面那段),光 destroy 等于把超时做成了一个不生效的摆设 ——
-		* 而症状是启动整个吊死,恰好比没有超时更难看出来。
+		* 超时用 `setTimeout` 而不是 `req.setTimeout`：后者只管 **socket 空闲**，一个每 200ms
+		* 吐一个字节的第三方服务能让它永远不触发。**`destroy()` 之后必须自己 resolve**——
+		* 响应头已经到手时，这一下的错误落在 `res` 上而不是 `req` 上，光 destroy 等于把超时做
+		* 成了一个不生效的摆设，而症状是启动整个吊死，恰好比没有超时更难看出来。
 		*/
 		const timer = setTimeout(() => {
 			req.destroy();
@@ -2153,10 +2238,9 @@ function requestInstance(entry, timeoutMs) {
 	});
 }
 /**
-* 这个仓库已经有活着的实例吗?有就返回它的 URL,没有就 null。
-*
-* 命中之后调用方**不得碰注册表**:那条目是另一个进程写的,连「顺手更新一下」都不行
-* ——它退出时按 pid 只删自己的那条(registry.ts),我们改过的内容会让它留下垃圾。
+* 这个仓库已经有活着的实例吗？有就返回它的 URL，没有就 null。命中之后调用方**不得碰注册
+* 表**：那条目是另一个进程写的，连「顺手更新一下」都不行——它退出时按 pid 只删自己的那
+* 条，我们改过的内容会让它留下垃圾。
 */
 async function findLiveInstance(repoRoot, { timeoutMs = PROBE_TIMEOUT_MS } = {}) {
 	const entry = readRegistry(repoRoot);
@@ -2164,11 +2248,9 @@ async function findLiveInstance(repoRoot, { timeoutMs = PROBE_TIMEOUT_MS } = {})
 	const info = await requestInstance(entry, timeoutMs);
 	if (!info) return null;
 	/**
-	* **200 还不够,路径也得对得上**。
-	*
-	* 这一条挡的是「注册表条目还在,而那个端口已经被系统回收给了别的东西」——
-	* 它恰好也认得这份 token 的概率不高,但代价是把用户带到别人的页面,而这类判断
-	* 错了不会有任何东西报错。归一化复用注册表键那一份实现,理由记在那边。
+	* **200 还不够，路径也得对得上**：这一条挡的是「注册表条目还在，而那个端口已经被系统
+	* 回收给了别的东西」——它恰好也认得这份 token 的概率不高，但代价是把用户带到别人的页面，
+	* 而这类判断错了不会有任何东西报错。归一化复用注册表键那一份实现。
 	*/
 	if (normalizeRepoKey(info.repoRoot) !== normalizeRepoKey(repoRoot)) return null;
 	return {
@@ -2181,12 +2263,10 @@ async function findLiveInstance(repoRoot, { timeoutMs = PROBE_TIMEOUT_MS } = {})
 //#region src/server/cli/start.ts
 async function start(options) {
 	/**
-	* 「可以看了」的唯一出口:**stdout 的第一行是且只是 URL**,随后一行说明,最后
-	* 拉起浏览器。
-	*
-	* 复用与新起两条路各写一遍的话,只有新起那条天天在跑 —— 改了第一行的形状
-	* (加前缀、换写法)会在复用那条上静默漂走,而 `scripts/bench-startup.mjs` 与
-	* 冒烟套件的 ready 判据都压在这一行上。
+	* 「可以看了」的唯一出口：**stdout 的第一行是且只是 URL**，随后一行说明，最后拉起浏览器。
+	* 复用与新起两条路各写一遍的话，只有新起那条天天在跑——改了第一行的形状（加前缀、换写
+	* 法）会在复用那条上静默漂走，而 `scripts/bench-startup.mjs` 与冒烟套件的 ready 判据都
+	* 压在这一行上。
 	*/
 	function announce(url, note) {
 		process.stdout.write(`${url}\n`);
@@ -2195,11 +2275,9 @@ async function start(options) {
 	}
 	const repo = await locateRepo(options.cwd);
 	/**
-	* **同一个仓库已经有实例在跑,就把用户送去那一个**。
-	*
-	* 判活是 HTTP 探活而不是 pid —— 理由在 probe.ts。命中这条路之后**什么都不写**:
-	* 不写注册表(那条目属于对面那个进程)、不装信号与 exit 处理器(装了会在本进程
-	* 退出时替对面清理掉它的条目,虽然 removeRegistry 按 pid 又挡了一道)。
+	* **同一个仓库已经有实例在跑，就把用户送去那一个**。判活是 HTTP 探活而不是 pid。命中这
+	* 条路之后**什么都不写**：不写注册表（那条目属于对面那个进程）、不装信号与 exit 处理器
+	* （装了会在本进程退出时替对面清理掉它的条目）。
 	*/
 	const existing = await findLiveInstance(repo.root);
 	if (existing) {
@@ -2208,8 +2286,8 @@ async function start(options) {
 	}
 	const server = await startServer(repo, { 
 	/**
-	* 空闲宽限期走满。**「怎么退」归这一层**:http/ 那边只知道
-	* 「没人了」,退出码、提示语、以及退出前要不要先 close 都是启动流程的事。
+	* 空闲宽限期走满。**「怎么退」归这一层**：http/ 那边只知道
+	* 「没人了」，退出码、提示语、以及退出前要不要先 close 都是启动流程的事。
 	*/
 onIdle: () => stop(0, "difftab: no tabs left — exiting.\n") });
 	writeRegistry({
@@ -2221,23 +2299,20 @@ onIdle: () => stop(0, "difftab: no tabs left — exiting.\n") });
 	});
 	let closing = false;
 	/**
-	* 唯一的退出路径。信号与空闲退出共用它 —— 两者完全可能撞在一起(Ctrl+C 恰好
-	* 落在宽限期走满的同一拍),各写一份的话 `server.close()` 会跑两次,第二次撞上
-	* 已经 destroy 的 socket。
+	* 唯一的退出路径。信号与空闲退出共用它——两者完全可能撞在一起（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`**：后者写到**管道**时在 Windows 上是异步
+		* 的，紧跟着的 `process.exit()` 会把还在缓冲区里的内容整条丢掉（与 main.ts 那条报错同
+		* 一个规避手法），而这句提示正是自动化验证「它是自己走的、不是被 kill 的」的判据。
 		*
-		* **而它得能失败**:`writeSync` 与 `process.stdout.write` 不同,读端已经走了
-		* (`difftab --no-open | head -1`)时它**抛 EPIPE**。抛在这个定时器回调里,
-		* `closing` 已经合上,于是 `server.close()` 不再执行,进程带着一屏 Node 栈以 1
-		* 退出 —— 而这条路承诺的是干净的 0。提示没打出去不是错误,是没人在听。
+		* **而它得能失败**：读端已经走了(`difftab --no-open | head -1`)时 `writeSync` 抛
+		* EPIPE，抛在这个回调里时 `closing` 已经合上，于是 `server.close()` 不再执行，进程带着
+		* 一屏 Node 栈以 1 退出——而这条路承诺的是干净的 0。
 		*/
 		if (note) try {
 			writeSync(1, note);
@@ -2255,18 +2330,15 @@ onIdle: () => stop(0, "difftab: no tabs left — exiting.\n") });
 //#endregion
 //#region src/server/main.ts
 /**
-* 版本号只有 package.json 一个来源。
-*
-* 不把它硬编码在这里,也不在构建期 define 进去:硬编码会在第一次发版改号时
-* 静默漂移(`--version` 报旧号,没有任何东西会失败);构建期注入则让 `dist/` 与
-* 源码对不上、调试时更难看清。运行时读一次的代价只落在 `--version` 这条路径上。
-* dist/server/main.js → 包根的 package.json;`files` 之外 npm 总会带上它。
+* 版本号只有 package.json 一个来源。不硬编码在这里，也不在构建期 define 进去：硬编码会在
+* 第一次发版改号时静默漂移（`--version` 报旧号，没有任何东西会失败）；构建期注入则让
+* `dist/` 与源码对不上。运行时读一次的代价只落在 `--version` 这条路径上。
 */
 function readVersion() {
 	const manifestPath = fileURLToPath(new URL("../../package.json", import.meta.url));
 	return JSON.parse(readFileSync(manifestPath, "utf8")).version;
 }
-/** 一句话友好报错,不是 Node 异常栈(启动前置检查)。 */
+/** 一句话友好报错，不是 Node 异常栈（启动前置检查）。 */
 function fail(message) {
 	try {
 		writeSync(2, `difftab: ${message}\n`);
@@ -2274,16 +2346,12 @@ function fail(message) {
 	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 上同一条路
-* 一声不响。
+* 读端先走了不算错误（`difftab --no-open | head -1`：用户只想要那行 URL）。之后每一次写都以
+* EPIPE 失败，而**在 Windows 上管道写是异步的**（POSIX 上同步），失败因此以一个 `'error'`
+* 事件到达——零监听器的流收到 `'error'` 就是整个进程带着裸栈以 1 退出。
 *
-* 服务本身没坏 —— 浏览器照常用得上,45 秒没人连再自己退,所以这里只是把 EPIPE
-* 咽掉。**非 EPIPE 的错误照旧抛**:那是真出事了,不该借这条路一起被吞掉。
+* 服务本身没坏（浏览器照常用得上），所以这里只是把 EPIPE 咽掉。**非 EPIPE 的错误照旧抛**：
+* 那是真出事了，不该借这条路一起被吞掉。
 */
 function ignoreBrokenPipe(stream) {
 	stream.on("error", (cause) => {