@jayyuen66/dsh-ocr-review 0.1.9 → 0.1.11

package/host.js

@@ -1,7 +1,7 @@
 // GENERATED by build-host.mjs — edit host.ts / lib/*.ts, then run `node build-host.mjs`.
 import { createRequire } from "node:module";
 import Schema from "@deepseek-ai/schemastery";
-import { chmodSync, copyFileSync, existsSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import path from "node:path";
 import { Remote, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
@@ -12,8 +12,9 @@ import { truncateEnd, truncateStart } from "@jayyuen66/dsh-plugin-shared/lib/tex
 import { fieldOf, hasMethods, isRecord } from "@jayyuen66/dsh-plugin-shared/lib/record";
 import { expandHomePath, resolveDshHome } from "@deepseek-ai/dsh-home-paths";
 import { errorText } from "@jayyuen66/dsh-plugin-shared/lib/errors";
-import { mkdir, readFile } from "node:fs/promises";
+import { mkdir, readFile, readlink, realpath, stat } from "node:fs/promises";
 import { withFileLock, writeFileAtomic } from "@deepseek-ai/dsh-atomic-write";
+import { createHash } from "node:crypto";
 // lib/messages.ts
 const MESSAGES = {
 	zh: {
@@ -30,7 +31,7 @@ const MESSAGES = {
 		detailSeparator: "：",
 		stdoutTruncated: "[ocr-review] 注意：输出超过 {limit} 字节上限已截断{spill}",
 		outputSpill: "（完整输出已落盘：{path}）",
-		backgroundPolling: "先 job_output(job_id=<本回执的 jobId>) 读这条后台评审的实时输出与最终结局——按 id 走，启动即可读，一定有结果；要停它就 job_kill(job_id=<同一 id>)。会话落盘后再走 ocr_session：ocr_session(action=list) 找本仓库最新会话（启动几秒后出现，按 scanPaths/时间匹配）；completed_files == selected_files 即已完成；再 ocr_session(action=comments, id) 取全部评论、ocr_session(action=show, id) 看元数据与逐文件检查点。后台评审不随工具调用结束而停止，默认也不设时限（ocrBackgroundMaxMs=0 表示无兜底窗口）；只有 dsh 宿主退出、本会话被停止、插件卸载或显式 job_kill 才会结束。",
+		backgroundPolling: "先 job_output(job_id=<本回执的 jobId>) 读这条后台评审的实时输出与最终结局——按 id 走，启动即可读，一定有结果；要停它就 job_kill(job_id=<同一 id>)。会话落盘后再走 ocr_session：ocr_session(action=list) 找本仓库最新会话（启动几秒后出现，按 scanPaths/时间匹配）；completed_files + reused_files + waived_files == selected_files 即已完成（failed_files 是没审成的部分，reused 是续扫复用的文件）；再 ocr_session(action=comments, id) 取全部评论、ocr_session(action=show, id) 看元数据与逐文件检查点。后台评审不随工具调用结束而停止，默认也不设时限（ocrBackgroundMaxMs=0 表示无兜底窗口）；只有 dsh 宿主退出、本会话被停止、插件卸载或显式 job_kill 才会结束。",
 		jobReasonSessionStopped: "ocr-review 会话已停止，回收在跑的后台评审",
 		jobReasonTimeout: "ocr-review 后台评审超过兜底窗口（{minutes} 分钟），兜底回收",
 		jobReasonUnload: "ocr-review 插件卸载",
@@ -47,6 +48,7 @@ const MESSAGES = {
 		repoRequired: "repo 必填，且为 Git 仓库绝对路径",
 		repoRequiredUnknownWorkspace: "repo 必填：当前会话工作区未知，请显式传入 Git 仓库绝对路径",
 		repoMustBeAbsolute: "repo 必须是绝对路径：{root}",
+		repoMustNotBeFilesystemRoot: "repo 不能是文件系统根（{root}）：根下任何文件都会被当成仓内文件，--rule / --background-file 会把仓库外的内容送进模型；请给出具体仓库目录",
 		noNulBytes: "{name} 不能包含 NUL 字节",
 		boolMustBeBoolean: "{name} 必须是布尔值（true/false），收到 {received}",
 		repoRootUnreadable: "repo 根目录不可读：{path}",
@@ -78,13 +80,14 @@ const MESSAGES = {
 		resultSchemaMalformed: "ocr {tool}: output schema 自身不合法——{detail}（插件内 bug：schema 的写法超出了返回形态守卫支持的官方子集）",
 		ocrNotJson: "OCR 未返回合法 JSON 输出",
 		ocrNotObject: "OCR JSON 输出不是对象",
-		ocrStatusInvalid: "OCR 输出 status 非法或缺失：{status}（期望 {expected}）；exit 0 不代表评审完成，请查 stderr 与 ~/.opencodereview/sessions/",
+		ocrStatusInvalid: "OCR 输出 status 非法或缺失：{status}（期望 {expected}）；exit 0 不代表评审完成，请查 stderr 与 OCR 会话目录（默认 ~/.opencodereview/sessions/，自定义 ocrConfigPath 时随 HOME 重定向）",
 		statusNone: "（无）",
 		ocrStatusFailed: "OCR 回执自报 status=failed（这一场评审没有成功完成）",
 		ocrCommentsNotArray: "OCR 输出 comments 字段不是数组，无法确认评论完整性",
 		warningSeparator: "：",
 		reviewSummaryHint: "完整评论与逐文件失败详情请用 `ocr_session(action=show/comments, id=<session_id>)` 查看；start_line=0 表示 OCR 未能锚定行号，可依据 suggestion/existing_code 在文件中定位。两套口径不要混：droppedCount 与 invalidCommentCount 同时为 0 只说明**本摘要**列全了 OCR 产出的评论（否则调大 maxComments 或置 0 后复核）；而**这一场有没有审完**看 coverage（selected 是分母，completed/reused/failed/waived 是它的互斥划分；coverage 为 null 时退回看 warnings 与 status=partial）和 budgetExceeded（true = token 预算花完提前收工，status 里只写 partial，看不出这一层）。toolCalls.failure 大于 0 说明当前模型的工具调用没跑通，换模型比重试同一个更省 token。切勿把「本摘要无 critical」当作「代码干净」。",
 		lineZeroNote: "(line 0: 定位失败，按 existing_code 手动定位)",
+		pathUnknown: "(路径未知)",
 		parseFailedWithReason: "{tool} 输出解析失败：{message}\n原始内容前 {limit} 码元（已脱敏）：\n{raw}",
 		parseFailedPlain: "{tool} 输出解析失败\n原始内容前 {limit} 码元（已脱敏）：\n{raw}",
 		previewParseFailed: "OCR 的 --preview 回执不是可识别的文件清单（files 缺失或条目形状不合）",
@@ -93,13 +96,16 @@ const MESSAGES = {
 		mcpReadFailed: "读取 MCP 配置失败（{where}）：{cause}",
 		mcpJsonInvalid: "MCP 配置不是合法 JSON：{cause}",
 		mcpJsonTooLarge: "MCP 配置超过 {limit} 字节上限",
-		mcpShapeInvalid: "MCP 配置必须是 {{name: entry}} 形式的对象",
+		mcpShapeInvalid: "MCP 配置必须是 {name: entry} 形式的对象",
 		mcpTooManyServers: "MCP servers 最多 {limit} 个",
 		mcpServerInvalid: "MCP server「{name}」的 {field} 不合法：{reason}",
 		mcpSaved: "MCP servers 已保存（{count} 个）",
+		mcpSaveFailed: "写入 MCP 配置失败（{where}）：{cause}",
+		mcpSaveConflict: "MCP 配置在读取之后已被改动（另一张设置卡或手工编辑），本次保存未写入。请重新载入后再保存。",
 		chatGptModelRequired: "ChatGPT 模型名必填",
 		chatGptSaved: "已切换到 ChatGPT provider，模型：{model}",
 		chatGptSaveFailed: "写入 ChatGPT 配置失败：{cause}",
+		chatGptProvidersInvalid: "config.json 里的 providers 或 providers.chatgpt 不是对象，无法安全写入（先手工修正再保存）",
 		compareNeedsBoth: "action=compare 需要同时给出 before 与 after 两个会话 id",
 		compareRejectsArgs: "action=compare 不接受 id/limit/severity/category",
 		exportRejectsArgs: "action=export 不接受 before/after/limit/severity/category",
@@ -195,7 +201,7 @@ const MESSAGES = {
 		filePreviewHint: "这是文件选择预览：没有调用 LLM、没有创建会话。要真正审查请去掉 preview 后重跑。列表按上限截断；truncated=true 时请用 exclude/path 缩小范围。",
 		ruleHint: "按分组规则逐个审查对应文件，输出评论建议格式：{path, content, start_line, end_line, category, severity}。",
 		sessionEmpty: "（暂无历史评审会话：先跑一次 ocr_review/ocr_scan 再查询）",
-		sessionTruncated: "…[截断] 完整内容见 ~/.opencodereview/sessions/",
+		sessionTruncated: "…[截断] 完整内容见 OCR 会话目录（默认 ~/.opencodereview/sessions/，自定义 ocrConfigPath 时随 HOME 重定向）",
 		sessionResumeHint: "要恢复中断的区间/commit 评审：ocr_review ... --resume <session_id>（工作区评审不支持恢复）；scan 会话用 ocr_scan ... --resume <session_id>。",
 		rulesCheckHint: "输出里的 Source 是命中的层（--rule/项目/全局/内置），Pattern 是命中的 glob；规则按声明顺序先到先得。",
 		llmHint: "providers 是内置清单，models 是 ChatGPT 账号专属列表；评审实际用哪个 provider/model 仍以 OCR 配置为准。",
@@ -239,7 +245,7 @@ const MESSAGES = {
 		detailSeparator: ": ",
 		stdoutTruncated: "[ocr-review] note: output exceeded the {limit}-byte cap and was truncated{spill}",
 		outputSpill: " (full output spilled to {path})",
-		backgroundPolling: "First read this background review's live output and final outcome with job_output(job_id=<the jobId in this receipt>) — that path goes by id, so it is readable immediately after start and always has a result; job_kill(job_id=<the same id>) stops it. Once the session has landed, use ocr_session: ocr_session(action=list) finds this repository's newest session (it appears a few seconds after start; match by scanPaths/time); completed_files == selected_files means it is done. Then ocr_session(action=comments, id) for all comments and ocr_session(action=show, id) for metadata and per-file checkpoints. A background run does not stop when the tool call ends and has no time limit by default (ocrBackgroundMaxMs=0 means no backstop window); it ends only when the dsh host exits, this session is stopped, the plugin unloads, or you call job_kill.",
+		backgroundPolling: "First read this background review's live output and final outcome with job_output(job_id=<the jobId in this receipt>) — that path goes by id, so it is readable immediately after start and always has a result; job_kill(job_id=<the same id>) stops it. Once the session has landed, use ocr_session: ocr_session(action=list) finds this repository's newest session (it appears a few seconds after start; match by scanPaths/time); completed_files + reused_files + waived_files == selected_files means it is done (failed_files is the part that did not complete, and reused means files carried over by a resumed run). Then ocr_session(action=comments, id) for all comments and ocr_session(action=show, id) for metadata and per-file checkpoints. A background run does not stop when the tool call ends and has no time limit by default (ocrBackgroundMaxMs=0 means no backstop window); it ends only when the dsh host exits, this session is stopped, the plugin unloads, or you call job_kill.",
 		jobReasonSessionStopped: "the ocr-review session stopped; running background reviews were reclaimed",
 		jobReasonTimeout: "the ocr-review background review exceeded its backstop window ({minutes} minutes) and was reclaimed",
 		jobReasonUnload: "ocr-review plugin unloaded",
@@ -256,6 +262,7 @@ const MESSAGES = {
 		repoRequired: "repo is required and must be the absolute path of a Git repository",
 		repoRequiredUnknownWorkspace: "repo is required: the current session workspace is unknown, pass the absolute path of a Git repository explicitly",
 		repoMustBeAbsolute: "repo must be an absolute path: {root}",
+		repoMustNotBeFilesystemRoot: "repo must not be a filesystem root ({root}): every file under it would count as inside the repo, so --rule / --background-file could feed files from outside it to the model; pass a concrete repository directory",
 		boolMustBeBoolean: "{name} must be a boolean (true/false), got {received}",
 		repoRootUnreadable: "the repo root is not readable: {path}",
 		repoFileMissing: "{name} points at a file that does not exist: {path}",
@@ -287,13 +294,14 @@ const MESSAGES = {
 		resultSchemaMalformed: "ocr {tool}: the output schema itself is malformed — {detail} (plugin bug: the schema goes beyond the official subset the result guard supports)",
 		ocrNotJson: "OCR returned no valid JSON output",
 		ocrNotObject: "the OCR JSON output is not an object",
-		ocrStatusInvalid: "OCR output has an invalid or missing status: {status} (expected {expected}); exit 0 does not mean the review completed — check stderr and ~/.opencodereview/sessions/",
+		ocrStatusInvalid: "OCR output has an invalid or missing status: {status} (expected {expected}); exit 0 does not mean the review completed — check stderr and the OCR session directory (default ~/.opencodereview/sessions/, relocated with HOME when ocrConfigPath is customized)",
 		statusNone: "(none)",
 		ocrStatusFailed: "the OCR receipt reports status=failed (this review run did not complete)",
 		ocrCommentsNotArray: "the comments field of the OCR output is not an array, comment completeness cannot be confirmed",
 		warningSeparator: ": ",
 		reviewSummaryHint: "Use `ocr_session(action=show/comments, id=<session_id>)` for the full comments and per-file failure details; start_line=0 means OCR could not anchor a line — locate it via suggestion/existing_code. Keep the two notions apart: droppedCount and invalidCommentCount both being 0 only means THIS SUMMARY listed every comment OCR produced (otherwise raise maxComments, or set it to 0, and re-check). Whether the run itself covered everything is answered by coverage (selected is the denominator, completed/reused/failed/waived are its disjoint partition; fall back to warnings and status=partial when coverage is null) and by budgetExceeded (true = the token budget stopped the run early — status still only says partial). A toolCalls.failure above 0 means the current model's tool calls did not work: switch models instead of retrying the same one. Never treat \"no critical in this summary\" as \"the code is clean\".",
 		lineZeroNote: "(line 0: not anchored, locate it via existing_code)",
+		pathUnknown: "(path unknown)",
 		parseFailedWithReason: "{tool} output parsing failed: {message}\nfirst {limit} UTF-16 code units of the raw output (redacted):\n{raw}",
 		parseFailedPlain: "{tool} output parsing failed\nfirst {limit} UTF-16 code units of the raw output (redacted):\n{raw}",
 		previewParseFailed: "the OCR --preview receipt is not a recognizable file list (files missing or every entry malformed)",
@@ -306,9 +314,12 @@ const MESSAGES = {
 		mcpTooManyServers: "at most {limit} MCP servers are allowed",
 		mcpServerInvalid: "MCP server \"{name}\" has an invalid {field}: {reason}",
 		mcpSaved: "MCP servers saved ({count})",
+		mcpSaveFailed: "failed to write the MCP config ({where}): {cause}",
+		mcpSaveConflict: "the MCP config changed after it was read (another settings card or a manual edit); nothing was written. Reload and save again.",
 		chatGptModelRequired: "a ChatGPT model slug is required",
 		chatGptSaved: "switched to the ChatGPT provider, model: {model}",
 		chatGptSaveFailed: "failed to write the ChatGPT config: {cause}",
+		chatGptProvidersInvalid: "providers or providers.chatgpt in config.json is not an object; fix it by hand before saving",
 		compareNeedsBoth: "action=compare requires both before and after session ids",
 		compareRejectsArgs: "action=compare does not take id/limit/severity/category",
 		exportRejectsArgs: "action=export does not take before/after/limit/severity/category",
@@ -404,7 +415,7 @@ const MESSAGES = {
 		filePreviewHint: "This is a file-selection preview: no LLM call and no session were created. Drop preview and rerun to actually review. Lists are capped; when truncated=true, narrow the scope with exclude/path.",
 		ruleHint: "Review the files of each group against its rule and emit comment suggestions in the shape {path, content, start_line, end_line, category, severity}.",
 		sessionEmpty: "(no review sessions yet: run ocr_review/ocr_scan once before querying)",
-		sessionTruncated: "…[truncated] full content in ~/.opencodereview/sessions/",
+		sessionTruncated: "…[truncated] full content in the OCR session directory (default ~/.opencodereview/sessions/, relocated with HOME when ocrConfigPath is customized)",
 		sessionResumeHint: "To resume an interrupted range/commit review: ocr_review ... --resume <session_id> (workspace reviews cannot be resumed); scan sessions use ocr_scan ... --resume <session_id>.",
 		rulesCheckHint: "Source names the winning layer (--rule/project/global/built-in) and Pattern the glob; rules are first-match in declaration order.",
 		llmHint: "providers is the built-in catalogue; models is the ChatGPT account-specific list; the effective review provider/model still comes from OCR's own config.",
@@ -481,23 +492,33 @@ const SCHEMA_TYPES = /* @__PURE__ */ new Set([
 	"boolean",
 	"null"
 ]);
-/**
-* schema 里的关键字必须全部落在守卫支持的子集内（递归查 oneOf/properties/items），
-* 关键字的**取值形态**也必须合法。
-*
-* 违例抛错而不是当违规值报：schema 是插件自己的代码，错的是代码不是模型的数据。
-*
-* 为什么取值形态也要查：只查键名的话，`type: ["string","null"]` 这种官方子集不认的
-* 写法会让 `scalarMismatch` 走进最后那支 `value !== null`——于是 `null` 放行、字符串
-* 反而判违规，守卫给出的结论与它自己声称支持的子集无关。`enum` 写成字符串同理：
-* 走到 `enum.includes` 时成了子串匹配，非字符串值还会抛 `map is not a function`。
-*/
+/** schema 形态错误的统一出口：错的是插件自己的 schema，不是模型交回的数据。 */
 function malformed(toolName, detail, messages) {
 	return new Error(format(messages.resultSchemaMalformed, {
 		tool: toolName,
 		detail
 	}));
 }
+/** 容器关键字的取值形态：`properties` 是字段表、`required` 是字段名数组、
+*  `additionalProperties` 是布尔或子 schema、`items` 是单个子 schema。
+*
+*  形态不对时走查器会**静默丢掉整条约束**（数组 properties 把下标当字段名、字符串
+*  required 逐字符迭代、对象 additionalProperties 与 `=== false` 比较恒假），
+*  与 `type`/`enum` 写错是同一类「守卫假装支持」的缺陷，所以同样当场抛。
+*  容器关键字也必须显式声明 `type`：走查按 `type` 分派，缺了它这些约束从不生效。 */
+function assertContainerShapes(schema, toolName, messages) {
+	const { properties, required, additionalProperties, items, type } = schema;
+	if ([
+		properties,
+		required,
+		additionalProperties,
+		items
+	].filter((value) => value !== void 0).length > 0 && type === void 0) throw malformed(toolName, "properties/required/additionalProperties/items 必须同时声明 type", messages);
+	if (properties !== void 0 && !isRecord(properties)) throw malformed(toolName, "properties 必须是字段名的对象", messages);
+	if (required !== void 0 && (!Array.isArray(required) || required.some((key) => typeof key !== "string"))) throw malformed(toolName, "required 必须是字段名数组", messages);
+	if (additionalProperties !== void 0 && typeof additionalProperties !== "boolean" && !isRecord(additionalProperties)) throw malformed(toolName, "additionalProperties 必须是布尔或子 schema", messages);
+	if (items !== void 0 && !isRecord(items)) throw malformed(toolName, "items 必须是单个子 schema（不支持元组数组）", messages);
+}
 /** 关键字白名单：守卫只认官方子集，多一个都算插件自己的 schema 写错了。 */
 function assertKnownKeywords(schema, toolName, messages) {
 	for (const keyword of Object.keys(schema)) if (!SUPPORTED_KEYWORDS.has(keyword)) throw new Error(format(messages.resultSchemaUnsupported, {
@@ -517,11 +538,22 @@ function assertOneOfShape(oneOf, toolName, messages) {
 	if (Array.isArray(oneOf) && oneOf.length >= 2) return;
 	throw malformed(toolName, "oneOf 必须是至少两项的数组", messages);
 }
-/** `enum` 的取值形态：非空数组。写成字符串时 `enum.includes` 会退化成子串匹配。 */
+/** JSON 标量（null / 布尔 / 有限数字 / 字符串）：const/enum 的比较只在标量上成立。 */
+function isJsonScalar(value) {
+	return value === null || typeof value === "boolean" || typeof value === "string" || typeof value === "number" && Number.isFinite(value);
+}
+/** `enum` 的取值形态：非空数组，且成员必须是 JSON 标量。
+*  非标量成员在 `includes` 下按引用比较，deep-equal 也会失配；本守卫的子集只认标量。 */
 function assertEnumShape(enumValues, toolName, messages) {
 	if (enumValues === void 0) return;
-	if (Array.isArray(enumValues) && enumValues.length > 0) return;
-	throw malformed(toolName, "enum 必须是非空数组", messages);
+	if (Array.isArray(enumValues) && enumValues.length > 0 && enumValues.every((entry) => isJsonScalar(entry))) return;
+	throw malformed(toolName, "enum 必须是非空的 JSON 标量数组", messages);
+}
+/** `const` 的取值形态：JSON 标量。对象/数组型 const 只能用引用比较，
+*  而值侧总是新对象——deep-equal 也在本守卫的子集之外。 */
+function assertConstShape(schema, toolName, messages) {
+	const { const: constValue } = schema;
+	if (constValue !== void 0 && !isJsonScalar(constValue)) throw malformed(toolName, "const 必须是 JSON 标量（本守卫不支持对象/数组比较）", messages);
 }
 /**
 * schema 里的关键字必须全部落在守卫支持的子集内（递归查 oneOf/properties/items），
@@ -536,15 +568,17 @@ function assertEnumShape(enumValues, toolName, messages) {
 */
 function assertGuardable(schema, toolName, messages) {
 	assertKnownKeywords(schema, toolName, messages);
+	assertContainerShapes(schema, toolName, messages);
 	const { type, oneOf, enum: enumValues } = schema;
-	if (type !== void 0 && oneOf !== void 0) throw malformed(toolName, "type 与 oneOf 不能同时声明", messages);
 	assertTypeShape(type, toolName, messages);
 	assertOneOfShape(oneOf, toolName, messages);
 	assertEnumShape(enumValues, toolName, messages);
+	assertConstShape(schema, toolName, messages);
 	for (const branch of Array.isArray(oneOf) ? oneOf : []) assertGuardable(branch, toolName, messages);
 	for (const property of Object.values(schema.properties ?? {})) assertGuardable(property, toolName, messages);
-	const { items } = schema;
+	const { items, additionalProperties } = schema;
 	if (items !== void 0) assertGuardable(items, toolName, messages);
+	if (additionalProperties !== void 0 && typeof additionalProperties !== "boolean") assertGuardable(additionalProperties, toolName, messages);
 }
 /** 标量分支的形态判定（true = 不合形态；判据对齐官方 checkValue 的标量臂：
 *  number 须为有限 JSON 数、integer 须整数值）。 */
@@ -555,30 +589,50 @@ function scalarMismatch(type, value) {
 	if (type === "boolean") return typeof value !== "boolean";
 	return value !== null;
 }
+/** 违规清单的保留上限与最终文本上限：失败消息会被宿主持久化进会话日志，两者都限量。 */
+const MAX_VIOLATIONS_LISTED = 20;
+const MAX_VIOLATION_CHARS = 2e3;
+function recordViolation(sink, message) {
+	sink.total += 1;
+	if (sink.messages.length < sink.limit) sink.messages.push(message);
+}
+const MAX_FIELDS_LISTED = 10;
+/** 字段名单同样限量：一个多余字段值可以声明任意多键，整份名单不该无界地进失败消息。 */
+function listedFields(keys) {
+	const omitted = keys.length - MAX_FIELDS_LISTED;
+	return keys.slice(0, MAX_FIELDS_LISTED).join(", ") + (omitted > 0 ? ` …(+${omitted})` : "");
+}
 /** object 分支：isRecord → additionalProperties:false 的多余键 → required（缺键与
 *  「键在但值是 undefined」同判，与官方一致）→ 逐声明字段递归。 */
-function objectViolations(schema, value, path, walk) {
-	if (!isRecord(value)) return [`${path}: expected object`];
+function objectViolations(schema, value, path, sink, walk) {
+	if (!isRecord(value)) {
+		recordViolation(sink, `${path}: expected object`);
+		return;
+	}
 	const { properties, required, additionalProperties } = schema;
 	const declared = (key) => properties !== void 0 && Object.hasOwn(properties, key) ? properties[key] : void 0;
 	if (additionalProperties === false) {
 		const extra = Object.keys(value).filter((key) => declared(key) === void 0);
-		if (extra.length > 0) return [`${path}: fields outside the schema: ${extra.join(", ")}`];
+		if (extra.length > 0) recordViolation(sink, `${path}: fields outside the schema: ${listedFields(extra)}`);
+	}
+	for (const key of required ?? []) if (!Object.hasOwn(value, key) || value[key] === void 0) {
+		recordViolation(sink, `${path}: missing required field ${key}`);
+		return;
 	}
-	for (const key of required ?? []) if (!Object.hasOwn(value, key) || value[key] === void 0) return [`${path}: missing required field ${key}`];
-	const violations = [];
 	for (const key of Object.keys(value)) {
 		const child = declared(key);
-		if (child !== void 0) violations.push(...walk(child, value[key], `${path}.${key}`));
+		if (child !== void 0) walk(child, value[key], `${path}.${key}`, sink);
 	}
-	return violations;
 }
 /** array 分支：Array.isArray → 无 items 视为任意元素 → 逐元素递归（违规一次列全）。 */
-function arrayViolations(schema, value, path, walk) {
-	if (!Array.isArray(value)) return [`${path}: expected array`];
+function arrayViolations(schema, value, path, sink, walk) {
+	if (!Array.isArray(value)) {
+		recordViolation(sink, `${path}: expected array`);
+		return;
+	}
 	const { items } = schema;
-	if (items === void 0) return [];
-	return value.flatMap((item, index) => walk(items, item, `${path}[${index}]`));
+	if (items === void 0) return;
+	for (let index = 0; index < value.length; index += 1) walk(items, value[index], `${path}[${index}]`, sink);
 }
 /** provider key 形状：`sk-…`/`ark-…`/`ghp-…` 一类「短前缀 + 长随机串」。
 *
@@ -620,16 +674,23 @@ const UNDERSCORE_TOKEN = /\b(?:gh[pousr]|github_pat)_\w{20,}\b/gu;
 const REDACTION = "***REDACTED***";
 /** token 尾部至少一枚非 `-` 的字母/数字。 */
 const TOKEN_TAIL_CHARACTER = /[0-9A-Z]/u;
+/** 已知 provider key 的前缀：即便两侧是路径分隔符也按 key 处理。路径豁免是为了让
+*  仓库路径保持可读，而裸 key 同样可能被嵌进 URL 或日志路径（代理回显、错误行），
+*  这条豁免不能替它开口。 */
+const KNOWN_KEY_PREFIX = /^(?:sk|ark|xai|gsk|ghp)-/iu;
 /** 独立 key 形态的替换臂：随机串段里真有数字或大写才抹，否则原样交回（文件路径要保持可读）。
 *  两侧任一是路径分隔符的匹配是路径段而非 key：ocr CLI 会把仓库路径拍平成 kebab 段嵌进
 *  session 的 file_path（`…/sessions/Users-yuanjiang-Documents-…/uuid.jsonl`），原路径里
 *  只要有大写组件（macOS 的 Documents/Desktop 一类）就过得了「数字或大写」那道护栏——
-*  裸 key 从不出现在斜杠两侧，路径段也从不出现在别处，按上下文分比按字符集猜稳。 */
+*  裸 key 从不出现在斜杠两侧，路径段也从不出现在别处，按上下文分比按字符集猜稳。
+*  已知凭据前缀不走这条豁免：见 `KNOWN_KEY_PREFIX`。 */
 function redactStandaloneKey(match, offset, whole) {
+	if (!TOKEN_TAIL_CHARACTER.test(match.slice(match.indexOf("-") + 1))) return match;
+	if (KNOWN_KEY_PREFIX.test(match)) return REDACTION;
 	const before = whole[offset - 1];
 	const after = whole[offset + match.length];
 	if (before === "/" || after === "/" || before === "\\" || after === "\\") return match;
-	return TOKEN_TAIL_CHARACTER.test(match.slice(match.indexOf("-") + 1)) ? REDACTION : match;
+	return REDACTION;
 }
 /**
 * 抹掉文本里 key 形状的片段。
@@ -646,8 +707,18 @@ function redactStandaloneKey(match, offset, whole) {
 function redactKeyMaterial(text) {
 	return text.replaceAll(AUTH_HEADER_VALUE, `$<name>$<scheme>${REDACTION}`).replaceAll(BEARER_VALUE, `$<scheme>${REDACTION}`).replaceAll(KEY_ASSIGNMENT, `$<name>$<scheme>${REDACTION}`).replaceAll(UNDERSCORE_TOKEN, REDACTION).replaceAll(STANDALONE_KEY, redactStandaloneKey);
 }
+/** ESC 由运行时构造：`eslint(no-control-regex)` 不许控制字符出现在正则字面量里，而这里
+*  必须按真 ESC 匹配——放宽成「匹配 `[33m` 这种文本」会把日志里合法的方括号内容一起吃掉。 */
+const ESC = String.fromCodePoint(27);
+/** BEL：OSC 的另一种合法终结符。 */
+const BEL = String.fromCodePoint(7);
 /** ECMA-48 的 CSI 序列：ESC `[` + 参数位 + 中间位 + 终结位（SGR 颜色码就是终结位 `m`）。 */
-const ANSI_CSI = new RegExp(`${String.fromCodePoint(27)}\\[[0-?]*[ -/]*[@-~]`, "gu");
+const ANSI_CSI = new RegExp(`${ESC}\\[[0-?]*[ -/]*[@-~]`, "gu");
+/** OSC（ESC `]` …）与 DCS/PM/APC/SOS（ESC `P`/`X`/`^`/`_` …）：以 BEL 或 ST（ESC `\`）收尾。
+*  上游可能用 OSC 改窗口标题/超链接，DCS 回显设备控制；只剥 CSI 会让这些字节留在正文里。 */
+const ANSI_OSC_DCS = new RegExp(`${ESC}(?:\\][^${BEL}${ESC}]*|[PX^_][^${ESC}]*)(?:${BEL}|${ESC}\\\\)?`, "gu");
+/** 其余单字符 ESC 序列（ESC + 一个终结字符）：放在 CSI/OSC/DCS 之后跑，避免抢走它们的起始字符。 */
+const ANSI_ESC_SINGLE = new RegExp(`${ESC}[^\\[\\]PX^_]`, "gu");
 /**
 * 剥掉终端控制序列，只给**要显示给人复制**的那段输出用。
 *
@@ -657,24 +728,39 @@ const ANSI_CSI = new RegExp(`${String.fromCodePoint(27)}\\[[0-?]*[ -/]*[@-~]`, "
 * 复制进终端的恰好是那条 `npm i -g …`——复制到的是带控制字符的脏命令。
 */
 function stripAnsi(text) {
-	return text.replaceAll(ANSI_CSI, "");
+	return text.replaceAll(ANSI_OSC_DCS, "").replaceAll(ANSI_CSI, "").replaceAll(ANSI_ESC_SINGLE, "");
 }
-/** 官方子集的迷你走查（path 限定违规位置，一次列全）。oneOf 语义与官方一致：
-*  恰好一支命中，多支/零支都算违规。 */
-function violationsOf(schema, value, path) {
-	const violations = [];
+/** oneOf 分支数必须恰好为 1。试跑只关心「这一支有没有违规」，不保留文案；
+*  limit 0 让大数组不至于为每支各留一份名单。 */
+function oneOfViolations(schema, value, path, sink, walk) {
 	const { oneOf } = schema;
-	if (oneOf !== void 0) {
-		const passing = oneOf.filter((branch) => violationsOf(branch, value, path).length === 0);
-		if (passing.length !== 1) violations.push(`${path}: matched ${passing.length} of ${oneOf.length} oneOf branches`);
+	if (oneOf === void 0) return;
+	let passing = 0;
+	for (const branch of oneOf) {
+		const probe = {
+			messages: [],
+			limit: 0,
+			total: 0
+		};
+		walk(branch, value, path, probe);
+		if (probe.total === 0) passing += 1;
 	}
+	if (passing !== 1) recordViolation(sink, `${path}: matched ${passing} of ${oneOf.length} oneOf branches`);
+}
+/** type 分派的容器/标量走查，以及同级的 const/enum 比较。 */
+function leafViolations(schema, value, path, sink, walk) {
 	const { type } = schema;
-	if (type === "object") for (const violation of objectViolations(schema, value, path, violationsOf)) violations.push(violation);
-	else if (type === "array") for (const violation of arrayViolations(schema, value, path, violationsOf)) violations.push(violation);
-	else if (type !== void 0 && scalarMismatch(type, value)) violations.push(`${path}: expected ${type}`);
-	if (schema.const !== void 0 && value !== schema.const) violations.push(`${path}: must be exactly ${JSON.stringify(schema.const)}`);
-	if (schema.enum !== void 0 && !schema.enum.includes(value)) violations.push(`${path}: must be one of ${schema.enum.map((entry) => JSON.stringify(entry)).join("/")}`);
-	return violations;
+	if (type === "object") objectViolations(schema, value, path, sink, walk);
+	else if (type === "array") arrayViolations(schema, value, path, sink, walk);
+	else if (type !== void 0 && scalarMismatch(type, value)) recordViolation(sink, `${path}: expected ${type}`);
+	if (schema.const !== void 0 && value !== schema.const) recordViolation(sink, `${path}: must be exactly ${JSON.stringify(schema.const)}`);
+	if (schema.enum !== void 0 && !schema.enum.includes(value)) recordViolation(sink, `${path}: must be one of ${schema.enum.map((entry) => JSON.stringify(entry)).join("/")}`);
+}
+/** 官方子集的迷你走查（path 限定违规位置，一次列全）。oneOf 语义与官方一致：
+*  恰好一支命中，多支/零支都算违规。 */
+function violationsOf(schema, value, path, sink) {
+	oneOfViolations(schema, value, path, sink, violationsOf);
+	leafViolations(schema, value, path, sink, violationsOf);
 }
 /**
 * 校验并放行工具返回值：必须命中该工具自己的 output schema。
@@ -688,15 +774,18 @@ function violationsOf(schema, value, path) {
 */
 function assertToolOutput(schema, value, toolName, messages) {
 	assertGuardable(schema, toolName, messages);
-	const violations = violationsOf(schema, value, "result");
-	if (violations.length > 0) {
-		const MAX_LISTED = 20;
-		const MAX_CHARS = 2e3;
-		const omitted = violations.length - MAX_LISTED;
-		const listed = violations.slice(0, MAX_LISTED).join("; ") + (omitted > 0 ? ` …(+${omitted})` : "");
+	const sink = {
+		messages: [],
+		limit: MAX_VIOLATIONS_LISTED,
+		total: 0
+	};
+	violationsOf(schema, value, "result", sink);
+	if (sink.total > 0) {
+		const omitted = sink.total - sink.messages.length;
+		const listed = sink.messages.join("; ") + (omitted > 0 ? ` …(+${omitted})` : "");
 		throw new Error(format(messages.resultSchemaViolation, {
 			tool: toolName,
-			violations: redactKeyMaterial(listed).slice(0, MAX_CHARS)
+			violations: redactKeyMaterial(listed).slice(0, MAX_VIOLATION_CHARS)
 		}));
 	}
 	return value;
@@ -727,8 +816,14 @@ function shq(value) {
 * 归一（posix.normalize + 去尾随斜杠）的目的：同一个仓库只允许一种字符串形态到达下游。
 * `/repo//sub`、`/repo/./a`、`/repo/` 与 `/repo/sub` 是同一目录的几种写法，而会话目录
 * 等按路径派生的键会把这些写法各存一份；`..` 段按词法折叠成实际目标（`/repo/../..`
-* 落到 `/`）——折叠是 normalize 对绝对路径的既有行为，不存在「解析后仍含 `..`」的
-* 形态，所以这里没有可写的拒绝分支。
+* 落到 `/`）——折叠是 normalize 对绝对路径的既有行为，不存在「解析后仍含 ..」的形态。
+*
+* 但**折叠到文件系统根必须拒绝**，这不是防御性噪音：/repo/../.. 与 / 都归一成 /，而下游
+* resolveRepoFile 的边界判据是 path.relative(rootReal, real) 不以 .. 开头——根为 / 时它对
+* /etc/passwd 给出 etc/passwd，判据恒成立，于是 --rule /etc/passwd 会被当成仓内文件读进
+* OCR 并送给 LLM（子进程跑在 danger-full-access 下）。所以归一后落在根上的输入一律按
+* 「repo 给得太宽」拒绝；win32 用 path.win32.parse 解出的根与归一结果比较，覆盖盘符根
+* 与 UNC 共享根（两者的根形态各不止一种，不能只比字面量）。
 */
 function assertAbsoluteRoot(root, messages) {
 	const trimmed = typeof root === "string" ? root.trim() : "";
@@ -736,11 +831,15 @@ function assertAbsoluteRoot(root, messages) {
 	if (trimmed.includes("\0")) throw new Error(format(messages.noNulBytes, { name: "repo" }));
 	if (trimmed.startsWith("/")) {
 		const normalized = path.posix.normalize(trimmed);
-		return normalized.length > 1 ? normalized.replace(TRAILING_POSIX_SLASHES, "") : normalized;
+		const collapsed = normalized.length > 1 ? normalized.replace(TRAILING_POSIX_SLASHES, "") : normalized;
+		if (collapsed === "/") throw new Error(format(messages.repoMustNotBeFilesystemRoot, { root: trimmed }));
+		return collapsed;
 	}
 	if (process.platform === "win32" && path.win32.isAbsolute(trimmed)) {
 		const normalized = path.win32.normalize(trimmed);
-		return normalized.length > 3 ? normalized.replace(TRAILING_PATH_SEPARATORS, "") : normalized;
+		const collapsed = normalized.length > 3 ? normalized.replace(TRAILING_PATH_SEPARATORS, "") : normalized;
+		if (path.win32.parse(collapsed).root === collapsed) throw new Error(format(messages.repoMustNotBeFilesystemRoot, { root: trimmed }));
+		return collapsed;
 	}
 	throw new Error(format(messages.repoMustBeAbsolute, { root: trimmed }));
 }
@@ -790,8 +889,8 @@ function resolveRepoFile(root, value, name, maxBytes, messages) {
 		name,
 		path: text
 	}));
-	const stat = statSync(real);
-	if (!stat.isFile()) throw new Error(format(messages.repoFileNotFile, {
+	const stat = statSync(real, { throwIfNoEntry: false });
+	if (stat === void 0 || !stat.isFile()) throw new Error(format(messages.repoFileNotFile, {
 		name,
 		path: text
 	}));
@@ -901,17 +1000,27 @@ function resolveOutputFormat(value) {
 // lib/cli.ts
 /** Homebrew 安装路径（`Cellar` / `Homebrew` 任一段）。 */
 const HOMEBREW_PATH = /(?:^|[/\\])(?:Cellar|Homebrew)(?:[/\\]|$)/iu;
-/** `ocr` 版本行：`open-code-review v1.13.3`（允许预发布/构建元数据）。 */
+/** `ocr` 版本行：`open-code-review v1.13.4`（允许预发布/构建元数据）。 */
 const OCR_VERSION = /open-code-review\s+v?(?<version>\d+\.\d+(?:\.\d+)?(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)/u;
 /** `--exclude` 的模式条数上限。**不是审查范围的上限**，只是防一条失控输入把命令串撑爆；
 *  真实使用里几十条就到头，给到 2000 是为了"尽量不截断"——超了会明确告警，不静默丢。 */
 const EXCLUDE_LIST_LIMIT = 2e3;
 /** `--path` 的路径条数上限（同 EXCLUDE_LIST_LIMIT 的取向：够大 + 超限告警）。 */
 const PATH_LIST_LIMIT = 2e3;
+/** `ocr delegate rule` 的位置参数条数上限。与 PATH_LIST_LIMIT 分列，是因为两者的投放
+*  方式不同：这些路径逐个作为位置参数进 argv，而 `--path` 把同量级的路径压进一个逗号串；
+*  上限仍只用于拦住失控输入，合法清单以 OCR 侧实际处理能力为准。 */
+const DELEGATE_PATHS_LIMIT = 200;
+/** 会话过滤列表（severity/category）的条数上限。它拦的是失控输入的长度，不是取值域：
+*  severity 的合法取值另由白名单收口，拿枚举个数当上限会把「合法取值 + 一个重复值」误报成
+*  超限。 */
+const SESSION_FILTER_LIST_LIMIT = 50;
 /** `--rule` / `--background-file` 的文件大小上限：规则是检查清单，背景是需求文档。 */
 const RULE_FILE_MAX_BYTES = 262144;
 const BACKGROUND_FILE_MAX_BYTES = 1048576;
 const MAX_GIT_PROCS_FLAG = "--max-git-procs";
+/** `review` / `scan` / `delegate preview` 共用：四类命令构造各自转发同一枚上限。 */
+const MAX_TOKENS_FLAG = "--max-tokens";
 /** `ocr review|scan|delegate preview` 的背景说明 flag（三处命令构造共用一条）。
 *  pushTextFlag 按 `flag.slice(2)` 反推报错用的参数名，故值必须带 `--` 前缀。 */
 const BACKGROUND_FLAG = "--background";
@@ -924,7 +1033,7 @@ const BACKGROUND_FLAG = "--background";
 * test/readme-parity.test.ts 再断言两侧 README 写的也是它。三处只有一处是人写的、
 * 靠门禁钉住另两处，就不会出现「README 教用户装 A、代码按 B 校验」这种两边各自自洽的错。
 */
-const EXPECTED_OCR_CLI_VERSION = "1.13.3";
+const EXPECTED_OCR_CLI_VERSION = "1.13.4";
 /** 报错用的值形态（永不调用可能被劫持的 toJSON/toString）。host.ts 的入参闸
 *  （effort/wait）复用同一口径，故导出。 */
 function describeValue(value) {
@@ -1087,15 +1196,14 @@ function pushTextFlag(parts, flag, value, messages) {
 	const text = idValue(value, flag.slice(2), messages);
 	if (text !== "") parts.push(flag, shq(text));
 }
-/** --exclude/--background/--provider/--model 等通用 flag。
-* 注意：ocr 的 --exclude 是 String 类型（实测多个 flag 实例只认最后一个，
-* 逗号分隔才生效）——多值必须合并为一个 flag 逗号连接，绝不能展开多个。
-* resume 不在这里：它与 scope 是互斥语义（workspace 禁恢复），由
-* buildReviewCommand 在拿到 scopeFlags 结果后前置校验。 */
-function optionalFlags(args, messages) {
+/** 只作用于 LLM 阶段的说明面 flag：--background / --provider / --model。
+*  preview 不建 LLM 运行时，故这三个值不参与文件选择（`agent.Preview` 的入参里没有
+*  Background，也不加载 provider 配置）；非 preview 分支与 delegate preview 各自按需调用。
+*  注意：ocr 的 --exclude 是 String 类型（实测多个 flag 实例只认最后一个，逗号分隔才生效）
+*  ——多值必须合并为一个 flag 逗号连接，绝不能展开多个。exclude 与 rule/maxGitProcs 同属
+*  选择面，住在 selectionFlags。 */
+function backgroundFlags(args, messages) {
 	const parts = [];
-	const excludes = commaList(args.exclude, "exclude", EXCLUDE_LIST_LIMIT, messages);
-	if (excludes.length > 0) parts.push("--exclude", shq(excludes.join(",")));
 	pushTextFlag(parts, BACKGROUND_FLAG, args.background, messages);
 	pushTextFlag(parts, "--provider", args.provider, messages);
 	pushTextFlag(parts, "--model", args.model, messages);
@@ -1139,7 +1247,7 @@ function wrapWithHostReaper(command, messages) {
 	if (process.platform === "win32") return command;
 	return `bash -c ${shq([
 		`p0=$(ps -o ppid= -p $$ 2>/dev/null | tr -d ' '); [ -n "$p0" ] && HAVEPS=1 || HAVEPS=0`,
-		`pgrep -P 1 >/dev/null 2>&1 && HAVEPG=1 || HAVEPG=0`,
+		`pgrep -P 1 >/dev/null 2>&1; [ $? -lt 2 ] && HAVEPG=1 || HAVEPG=0`,
 		`[ "$HAVEPS" = 1 ] && [ "$HAVEPG" = 1 ] || { printf '%s\\n' ${shq(messages.reaperDegraded)} >&2; { ${command} ; }; exit $?; }`,
 		`{ ${command} ; } & ocr=$!`,
 		`desc() { for k in $(pgrep -P "$1" 2>/dev/null); do desc "$k"; printf '%s ' "$k"; done; }`,
@@ -1376,6 +1484,7 @@ function buildReviewCommand(args, outputPath, messages) {
 	if (preview) {
 		if (resume !== "") throw new Error(messages.previewRejectsResume);
 		parts.push("--preview", ...scopeFlags(args, messages), ...selectionFlags(args, repo, messages));
+		pushIntFlag(parts, MAX_TOKENS_FLAG, args.maxTokens, 0, messages);
 		if (outputPath !== void 0) parts.push("--output", shq(outputPath));
 		return {
 			command: parts.join(" "),
@@ -1390,13 +1499,10 @@ function buildReviewCommand(args, outputPath, messages) {
 	pushIntFlag(parts, "--max-tokens", args.maxTokens, 0, messages);
 	pushIntFlag(parts, "--max-tokens-budget", args.maxTokensBudget, 0, messages);
 	const scopeParts = scopeFlags(args, messages);
-	parts.push(...scopeParts, ...optionalFlags(args, messages));
+	parts.push(...scopeParts, ...selectionFlags(args, repo, messages), ...backgroundFlags(args, messages));
 	pushBoolFlag(parts, "--no-filter", args.noFilter, "noFilter", messages);
-	const rule = repoFileOf(args.rule, repo, "rule", RULE_FILE_MAX_BYTES, messages);
-	if (rule !== null) parts.push("--rule", shq(rule));
 	const backgroundFile = repoFileOf(args.backgroundFile, repo, "backgroundFile", BACKGROUND_FILE_MAX_BYTES, messages);
 	if (backgroundFile !== null) parts.push("--background-file", shq(backgroundFile));
-	pushIntFlag(parts, MAX_GIT_PROCS_FLAG, args.maxGitProcs, 1, messages);
 	if (resume !== "") {
 		if (scopeParts.length === 0) throw new Error(messages.resumeNeedsScope);
 		parts.push("--resume", shq(resume));
@@ -1425,7 +1531,10 @@ function buildScanCommand(args, outputPath, messages) {
 		"--format",
 		outputFormat
 	];
-	if (preview) parts.push("--preview");
+	if (preview) {
+		parts.push("--preview");
+		pushIntFlag(parts, MAX_TOKENS_FLAG, args.maxTokens, 0, messages);
+	}
 	const paths = commaList(args.path, "path", PATH_LIST_LIMIT, messages);
 	if (paths.length > 0) parts.push("--path", shq(paths.join(",")));
 	if (!preview) {
@@ -1435,7 +1544,7 @@ function buildScanCommand(args, outputPath, messages) {
 		pushIntFlag(parts, "--concurrency", args.concurrency, 1, messages);
 		pushIntFlag(parts, "--timeout", args.timeoutMinutes, 0, messages);
 		pushIntFlag(parts, "--max-tools", args.maxTools, 0, messages);
-		pushIntFlag(parts, "--max-tokens", args.maxTokens, 0, messages);
+		pushIntFlag(parts, MAX_TOKENS_FLAG, args.maxTokens, 0, messages);
 		pushIntFlag(parts, "--max-tokens-budget", args.maxTokensBudget, 0, messages);
 		pushBoolFlag(parts, "--no-plan", args.noPlan, "noPlan", messages);
 		pushBoolFlag(parts, "--no-dedup", args.noDedup, "noDedup", messages);
@@ -1463,16 +1572,12 @@ function buildDelegatePreviewCommand(args, messages) {
 		"preview",
 		"--format",
 		"json",
-		...scopeFlags(scopeArgs, messages)
+		...scopeFlags(scopeArgs, messages),
+		...selectionFlags(scopeArgs, repo, messages),
+		...backgroundFlags(scopeArgs, messages)
 	];
-	const excludes = commaList(args.exclude, "exclude", EXCLUDE_LIST_LIMIT, messages);
-	if (excludes.length > 0) parts.push("--exclude", shq(excludes.join(",")));
-	pushTextFlag(parts, BACKGROUND_FLAG, args.background, messages);
 	const backgroundFile = repoFileOf(args.backgroundFile, repo, "backgroundFile", BACKGROUND_FILE_MAX_BYTES, messages);
 	if (backgroundFile !== null) parts.push("--background-file", shq(backgroundFile));
-	const rule = repoFileOf(args.rule, repo, "rule", RULE_FILE_MAX_BYTES, messages);
-	if (rule !== null) parts.push("--rule", shq(rule));
-	pushIntFlag(parts, MAX_GIT_PROCS_FLAG, args.maxGitProcs, 1, messages);
 	return {
 		command: parts.join(" "),
 		workdir: repo
@@ -1481,7 +1586,7 @@ function buildDelegatePreviewCommand(args, messages) {
 /** 构造 `ocr delegate rule` 命令（路径为位置参数，逐条 shq 转义）。 */
 function buildDelegateRuleCommand(args, messages) {
 	const repo = assertAbsoluteRoot(args.repo, messages);
-	const paths = commaList(args.paths, "paths", 200, messages).map((filePath) => shq(filePath));
+	const paths = commaList(args.paths, "paths", DELEGATE_PATHS_LIMIT, messages).map((filePath) => shq(filePath));
 	if (paths.length === 0) throw new Error(messages.pathsRequired);
 	const parts = [
 		ocrCommand(),
@@ -1543,13 +1648,14 @@ const SESSION_SEVERITIES = [
 	"medium",
 	"low"
 ];
-/** severity 过滤：大小写归一 + 白名单；未知值报错而不是交给 CLI 返回空集。 */
+/** severity 过滤：大小写归一 + 白名单 + 去重；未知值报错而不是交给 CLI 返回空集。 */
 function severityFilter(value, messages) {
-	return commaList(value, "severity", SESSION_SEVERITIES.length, messages).map((item) => {
+	const items = commaList(value, "severity", SESSION_FILTER_LIST_LIMIT, messages).map((item) => {
 		const lower = item.toLowerCase();
 		if (!SESSION_SEVERITIES.includes(lower)) throw new Error(format(messages.invalidSeverity, { value: item }));
 		return lower;
 	});
+	return [...new Set(items)];
 }
 /** session list --limit：缺省 10（OCR 原生默认 20，本包收紧；OCR 的 0=不限在本包
 * 上限 100 下无意义）。显式给出时必须是 1-100 的整数（与工具 description 的承诺
@@ -1677,7 +1783,7 @@ function buildSessionCommand(args, messages) {
 		before: idValue(args.before, "before", messages),
 		after: idValue(args.after, "after", messages),
 		severities: severityFilter(args.severity, messages),
-		categories: commaList(args.category, "category", 50, messages),
+		categories: commaList(args.category, "category", SESSION_FILTER_LIST_LIMIT, messages),
 		hasFilters: false,
 		limit: args.limit,
 		output: idValue(args.output, "output", messages),
@@ -1737,6 +1843,7 @@ function aggregateComments(comments) {
 		if (category !== "") categoryCounts.set(category, (categoryCounts.get(category) ?? 0) + 1);
 	}
 	const byCategory = Object.fromEntries(categoryCounts);
+	Object.setPrototypeOf(byCategory, null);
 	return {
 		total: comments.length,
 		bySeverity,
@@ -1831,7 +1938,9 @@ function llmOf(raw) {
 		model
 	};
 }
-/** `resume` 回执：字段全空时回 null（CLI 只在真的续审时发这个对象）。 */
+/** `retry_report`：三个计数全为 0 时回 null（CLI 只在这一场发生过重试/恢复时才发
+*  这个对象；键是 total_retries / recovered_requests / failed_requests，不是 resume 的
+*  resumed_from / reused_files 那一组）。 */
 function retryOf(raw) {
 	if (!isRecord(raw)) return null;
 	const view = {
@@ -1863,11 +1972,15 @@ function capLines(lines, total, messages) {
 	if (lines.length >= total) return lines;
 	return [...lines, format(messages.diagnosticOmitted, { count: String(total - lines.length) })];
 }
-/** 计数字段的合法形态：非负整数或纯十进制数字串（与 {@link num} 的取值域对齐，
-*  否则 "x" 或 -1 会被 num 折成 0，把「读不出」伪装成「零失败」）。 */
+/** 计数字段的合法形态：**安全整数域内**的非负整数或纯十进制数字串——与 {@link num}
+*  的取值域是同一道闸。只查「是不是数字串」不够：`"99999999999999999999"` 过得了
+*  `^\d+$`，而 num() 的 nonNegativeInt 会把它折成 0，于是「读不出」被伪装成「零失败」
+*  （tool_calls 不进 unreadable、preview 的计数回退到本地长度），两种口径必须一起判。 */
 function isCount(value) {
 	if (typeof value === "number") return Number.isSafeInteger(value) && value >= 0;
-	return typeof value === "string" && DECIMAL_INTEGER.test(value.trim());
+	if (typeof value !== "string") return false;
+	const trimmed = value.trim();
+	return DECIMAL_INTEGER.test(trimmed) && Number.isSafeInteger(Number(trimmed));
 }
 /**
 * 解析 `tool_calls`。字段缺失或为 null（这一场没有工具调用记录）返回 null；
@@ -1886,8 +1999,7 @@ function toolCallsOf(raw, messages) {
 		view: null,
 		unreadable: true
 	};
-	const rows = Array.isArray(details) ? details : [];
-	const rendered = rows.filter((row) => isRecord(row)).map((row) => {
+	const rendered = (Array.isArray(details) ? details : []).filter((row) => isRecord(row)).map((row) => {
 		const key = str(row["file_path"]);
 		const tool = str(row["tool_name"]);
 		const error = str(row["error"]);
@@ -1897,7 +2009,7 @@ function toolCallsOf(raw, messages) {
 		view: {
 			total: num(doc["total"]),
 			failure: num(doc["failure"]),
-			failures: capLines(rendered.slice(0, DIAGNOSTIC_DETAIL_LIMIT), rows.length, messages)
+			failures: capLines(rendered.slice(0, DIAGNOSTIC_DETAIL_LIMIT), rendered.length, messages)
 		},
 		unreadable: false
 	};
@@ -2016,17 +2128,35 @@ function reviewFailure(status, message) {
 * 诊断字段读不出来时**不判整场失败**（评论仍然有效、token 已经花掉），而是各补一条
 * 说明进同一个 warnings 出口——「这一路没有数据」必须看得见，但不能把结果作废。
 */
+/**
+* OCR 的 warnings 数组 → 渲染行 + 限流旗标（`limitReached`）。
+*
+* 明细到 DIAGNOSTIC_DETAIL_LIMIT 就停：条目带 file/message 全文，大会话里几百条能把
+* 「省 token 的摘要」变成第二份原始输出。旗标必须扫**完整数组**——限流条目落在明细
+* 上限之外时同样要抬旗，否则截断本身会把「这一场被限流」这条事实吃掉。
+*/
+function warningLinesOf(warningsRaw, messages) {
+	const lines = [];
+	let limitReached = false;
+	for (const warn of warningsRaw) {
+		limitReached ||= isRecord(warn) && LIMIT_WARNING_TYPES.has(str(warn["type"]));
+		if (lines.length < DIAGNOSTIC_DETAIL_LIMIT) lines.push(warningLineOf(warn, messages));
+	}
+	if (warningsRaw.length > DIAGNOSTIC_DETAIL_LIMIT) lines.push(format(messages.diagnosticOmitted, { count: String(warningsRaw.length - DIAGNOSTIC_DETAIL_LIMIT) }));
+	return {
+		lines,
+		limitReached
+	};
+}
 function diagnosticsOf(root, messages) {
+	const warningsRaw = root["warnings"];
 	const warnings = [];
 	let limitReached = false;
-	const warningsRaw = root["warnings"];
-	if (warningsRaw !== void 0) {
-		if (Array.isArray(warningsRaw)) for (const warn of warningsRaw) {
-			warnings.push(warningLineOf(warn, messages));
-			limitReached ||= isRecord(warn) && LIMIT_WARNING_TYPES.has(str(warn["type"]));
-		}
-		else warnings.push(messages.warningUnreadable);
-	}
+	if (Array.isArray(warningsRaw)) {
+		const { lines, limitReached: flagged } = warningLinesOf(warningsRaw, messages);
+		warnings.push(...lines);
+		limitReached = flagged;
+	} else if (warningsRaw !== void 0) warnings.push(messages.warningUnreadable);
 	const toolCalls = toolCallsOf(root["tool_calls"], messages);
 	const coverage = coverageOf(root["manifest"], messages);
 	if (toolCalls.unreadable) warnings.push(format(messages.diagnosticUnreadable, { field: "tool_calls" }));
@@ -2108,17 +2238,24 @@ function parseReviewOutput(text, messages) {
 		droppedComments
 	};
 }
+/** 行号锚点：`start-end` / `start`；未锚定（start_line<=0）回空串，由调用方决定怎么表达。 */
+function lineRangeOf(comment) {
+	if (comment.startLine <= 0) return "";
+	return comment.endLine > comment.startLine ? `${comment.startLine}-${comment.endLine}` : `${comment.startLine}`;
+}
 /** 默认摘要计划（no-object-as-default-parameter：避免对象字面量作参数默认值）。 */
 const DEFAULT_PLAN = {
 	maxComments: 12,
 	includeZeroLine: false
 };
-/** 单条评论的 top 位置（0 行未锚定降级为 :0）。 */
-function locationOf(comment) {
-	const fallbackPath = comment.path || "(path unknown)";
-	if (comment.startLine <= 0) return `${fallbackPath}:0`;
-	const suffix = comment.endLine > comment.startLine ? `-${comment.endLine}` : "";
-	return `${fallbackPath}:${comment.startLine}${suffix}`;
+/** 单条评论的位置标签：`path:start[-end]`，未锚定降级为 `:0`。
+*
+*  path 缺失时的占位文本来自 messages（`pathUnknown`），不在这里硬编码：本模块产出的
+*  人读文本全部经 messages（见文件头「文案」一段），硬编码的英文占位会让中文界面里
+*  冒出英文，也与 renderComment 里那份副本各说一套。 */
+function locationOf(comment, messages) {
+	const range = lineRangeOf(comment);
+	return `${comment.path || messages.pathUnknown}:${range === "" ? "0" : range}`;
 }
 /**
 * 生成工具返回给模型的结构化摘要（省 token：给聚合与 top-N 评论，不塞全量）。
@@ -2149,7 +2286,7 @@ function summarizeReview(parsed, messages, plan = DEFAULT_PLAN) {
 		droppedCount: parsed.comments.length - ranked.length,
 		invalidCommentCount: parsed.droppedComments,
 		topComments: ranked.map((comment) => ({
-			location: locationOf(comment),
+			location: locationOf(comment, messages),
 			severity: comment.severity,
 			category: comment.category,
 			content: comment.content,
@@ -2161,14 +2298,16 @@ function summarizeReview(parsed, messages, plan = DEFAULT_PLAN) {
 		hint: messages.reviewSummaryHint
 	};
 }
-/** preview/rule 文档各自的契约键：一个都不命中即视为「不是该命令的输出」。 */
-const DELEGATE_PREVIEW_KEYS = [
-	"mode",
-	"repository",
-	"total_files",
-	"reviewable_files"
-];
-const DELEGATE_RULE_KEYS = ["groups", "schema_version"];
+/** preview/rule 文档各自的结构性键：一个都不命中即视为「不是该命令的输出」。
+*
+*  只取结构性键（数组字段），不取 `mode` / `schema_version` / `total_files` 这类
+*  任何回执都可能带的通用键：`{"schema_version":"1.0","error":"auth failed"}` 命中
+*  通用键就会过闸，被报成「0 个文件可审 / 0 条规则」——那是假阴性的范围结论，比解析
+*  失败更难察觉。两侧由 CLI 的结构体标签保证必带（cmd/opencodereview/delegate_cmd.go：
+*  `ReviewableFiles []… \`json:"reviewable_files"\`` 与 `Groups []… \`json:"groups"\``，
+*  都没有 omitempty，空清单也发 []）。 */
+const DELEGATE_PREVIEW_KEYS = ["reviewable_files"];
+const DELEGATE_RULE_KEYS = ["groups"];
 function hitsContract(root, keys) {
 	return keys.some((key) => root[key] !== void 0);
 }
@@ -2192,7 +2331,6 @@ function delegatePreviewFailure() {
 * 文件」，是半截产出，模型与用户都会拿它当范围结论。
 */
 function toDelegateFiles(raw) {
-	if (!Array.isArray(raw)) return [];
 	const files = raw.map((entry) => {
 		if (!isRecord(entry)) return null;
 		const entryPath = str(entry["path"]);
@@ -2214,7 +2352,6 @@ function toDelegateFiles(raw) {
 *  于是「被排除文件及原因」永远只有文件没有原因——schema 与工具描述都在承诺后者。
 *  `reason` 作回退保留：形如 `{"reason":…}` 的旧形态/别家产物仍读得出来。 */
 function toExcludedFiles(raw) {
-	if (!Array.isArray(raw)) return [];
 	const files = raw.map((entry) => {
 		if (!isRecord(entry)) return null;
 		const entryPath = str(entry["path"]);
@@ -2237,12 +2374,12 @@ function parseDelegatePreview(text) {
 	if (!isRecord(doc)) return delegatePreviewFailure();
 	const root = doc;
 	if (!hitsContract(root, DELEGATE_PREVIEW_KEYS)) return delegatePreviewFailure();
-	for (const key of ["reviewable_files", "excluded_files"]) {
-		const value = root[key];
-		if (value !== void 0 && !Array.isArray(value)) return delegatePreviewFailure();
-	}
-	const reviewable = toDelegateFiles(root["reviewable_files"]);
-	const excluded = toExcludedFiles(root["excluded_files"]);
+	const reviewableRaw = root["reviewable_files"];
+	if (!Array.isArray(reviewableRaw)) return delegatePreviewFailure();
+	const excludedRaw = root["excluded_files"];
+	if (excludedRaw !== void 0 && !Array.isArray(excludedRaw)) return delegatePreviewFailure();
+	const reviewable = toDelegateFiles(reviewableRaw);
+	const excluded = toExcludedFiles(excludedRaw ?? []);
 	if (reviewable === null || excluded === null) return delegatePreviewFailure();
 	return {
 		ok: true,
@@ -2274,11 +2411,12 @@ function parseDelegateRules(text) {
 		ok: false,
 		groups: []
 	};
-	if (root["groups"] !== void 0 && !Array.isArray(root["groups"])) return {
+	const groupsValue = root["groups"];
+	if (!Array.isArray(groupsValue)) return {
 		ok: false,
 		groups: []
 	};
-	const groupsRaw = Array.isArray(root["groups"]) ? root["groups"] : [];
+	const groupsRaw = groupsValue;
 	if (groupsRaw.some((groupRaw) => isRecord(groupRaw) && groupRaw["files"] !== void 0 && !Array.isArray(groupRaw["files"]))) return {
 		ok: false,
 		groups: []
@@ -2369,26 +2507,26 @@ function compareSideOf(raw) {
 		range: isRecord(raw) ? str(raw["range"]) : ""
 	};
 }
-function compareCommentOf(raw) {
+function compareCommentOf(raw, messages) {
 	const comment = commentOf(raw);
 	if (comment === null) return null;
 	return {
-		location: locationOf(comment),
+		location: locationOf(comment, messages),
 		severity: comment.severity,
 		category: comment.category,
 		content: comment.content
 	};
 }
 /** 一个 compare 桶：缺失/非数组判整个 compare 失败，部分条目坏只丢该条并计入 dropped。 */
-function compareBucketOf(raw) {
+function compareBucketOf(raw, messages) {
 	if (!Array.isArray(raw)) return null;
 	return {
-		items: raw.map((entry) => compareCommentOf(entry)).filter((entry) => entry !== null).slice(0, COMPARE_BUCKET_LIMIT),
+		items: raw.map((entry) => compareCommentOf(entry, messages)).filter((entry) => entry !== null).slice(0, COMPARE_BUCKET_LIMIT),
 		total: raw.length
 	};
 }
 /** 解析 `ocr session compare --json`：四个桶与两侧会话标识。 */
-function parseSessionCompare(text) {
+function parseSessionCompare(text, messages) {
 	let doc;
 	try {
 		doc = JSON.parse(text);
@@ -2402,10 +2540,10 @@ function parseSessionCompare(text) {
 		ok: false,
 		view: null
 	};
-	const newBucket = compareBucketOf(doc["new"]);
-	const persisting = compareBucketOf(doc["persisting"]);
-	const resolved = compareBucketOf(doc["resolved"]);
-	const notReviewed = compareBucketOf(doc["not_reviewed"]);
+	const newBucket = compareBucketOf(doc["new"], messages);
+	const persisting = compareBucketOf(doc["persisting"], messages);
+	const resolved = compareBucketOf(doc["resolved"], messages);
+	const notReviewed = compareBucketOf(doc["not_reviewed"], messages);
 	if (newBucket === null || persisting === null || resolved === null || notReviewed === null) return {
 		ok: false,
 		view: null
@@ -2686,23 +2824,32 @@ const REVIEW_SUMMARY_SCHEMA = {
 		hint: { type: "string" }
 	}
 };
+/** preview 文件条目里两个输出共有的四字段（review/scan 的预览与 delegate preview
+*  的文件清单都从这里取，避免两份 additionalProperties:false 各自演进后一边通过、
+*  另一边被守卫拒绝）。 */
+const PREVIEW_FILE_FIELDS = {
+	path: { type: "string" },
+	status: { type: "string" },
+	insertions: { type: "number" },
+	deletions: { type: "number" }
+};
+const PREVIEW_FILE_REQUIRED = [
+	"path",
+	"status",
+	"insertions",
+	"deletions"
+];
 /** review/scan `preview:true` 的文件清单对象（lib/parse.ts 的 PreviewView）。 */
 const PREVIEW_FILE_SCHEMA = {
 	type: "object",
 	additionalProperties: false,
 	required: [
-		"path",
-		"status",
-		"insertions",
-		"deletions",
+		...PREVIEW_FILE_REQUIRED,
 		"willReview",
 		"excludeReason"
 	],
 	properties: {
-		path: { type: "string" },
-		status: { type: "string" },
-		insertions: { type: "number" },
-		deletions: { type: "number" },
+		...PREVIEW_FILE_FIELDS,
 		willReview: { type: "boolean" },
 		excludeReason: { type: "string" }
 	}
@@ -2773,18 +2920,8 @@ const PREVIEW_OUTPUT_SCHEMA = { oneOf: [{
 			items: {
 				type: "object",
 				additionalProperties: false,
-				required: [
-					"path",
-					"status",
-					"insertions",
-					"deletions"
-				],
-				properties: {
-					path: { type: "string" },
-					status: { type: "string" },
-					insertions: { type: "number" },
-					deletions: { type: "number" }
-				}
+				required: [...PREVIEW_FILE_REQUIRED],
+				properties: { ...PREVIEW_FILE_FIELDS }
 			}
 		},
 		excludedFiles: {
@@ -2947,10 +3084,16 @@ const TEXT_OUTPUT_SCHEMA = {
 const ROUTING_NAME = "ocr-review-routing";
 const ROUTING_ORDER = 1555;
 // lib/provider-projection.ts
-/** llm-pi-ai 命名空间里 provider 表的字段名。 */
+/** llm-pi-ai 命名空间里 provider 表的字段名。导出给 lib/provider-source.ts：读口判
+*  「命名空间里有 providers 表吗」与投影取同一张表，两处各写一份字面量迟早漂。 */
 const PROVIDERS_FIELD = "providers";
-/** provider 的 baseURL 只认 http(s)。 */
-const HTTP_URL$1 = /^https?:\/\//iu;
+/** provider 的 baseURL 里出现空白或控制字符：URL 解析器会把换行/制表符直接吃掉、
+*  把空格编码进路径，畸形串因此可能变形后通过，故先按原文拒绝。 */
+const RAW_SPACE_OR_CONTROL = /[\p{Cc} ]/u;
+/** 可写进 config.json `api_key_cmd` 的凭据 ref 名（config-store.ts 的构造与反解共用这一枚）。
+*  收紧到「大写 + 数字 + 下划线」有两层理由：OCR 侧凭据惯例大写；把真实 key 误填进
+*  `apiKeyEnv` 时它不会被当作 ref 送进凭据查询、也不会在失败文案里被原样回显。 */
+const CREDENTIAL_ENV_KEY = /^[A-Z0-9_]+$/u;
 /**
 * llm-pi-ai 的 `api` 协议 → OCR config 的 `protocol` 映射。
 *
@@ -3017,16 +3160,37 @@ function modelFromRaw(modelRaw) {
 		name: name === "" ? id : name
 	};
 }
+/** baseURL 的可用形态：http(s)、有主机、无内嵌凭据。
+*
+*  只用前缀正则（此前的 `/^https?:\/\//`）放行了 `https://`（无主机）、内嵌
+*  `user:pass@` 的地址与含换行/空白的串：内嵌凭据会把明文密码写进 OCR config.json，
+*  其余形态把故障拖到 OCR 调用期才暴露。`new URL` 能拒掉无主机与空白主机，
+*  但会**静默吃掉**换行/制表符并把空格编码进路径，所以原文里先禁空白与控制字符。 */
+function isAcceptableBaseUrl(value) {
+	if (RAW_SPACE_OR_CONTROL.test(value)) return false;
+	let parsed;
+	try {
+		parsed = new URL(value);
+	} catch {
+		return false;
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return false;
+	return parsed.username === "" && parsed.password === "";
+}
 /** 原始 provider 对象 → DshProvider（缺 baseURL 或形状不合视为无效，返回 null）。 */
 function providerFromRaw(name, raw) {
 	if (!isRecord(raw)) return null;
 	const entry = raw;
-	const apiKeyEnv = typeof entry["apiKeyEnv"] === "string" && entry["apiKeyEnv"].trim() ? entry["apiKeyEnv"].trim() : null;
+	const rawApiKeyEnv = typeof entry["apiKeyEnv"] === "string" ? entry["apiKeyEnv"].trim() : "";
+	const apiKeyEnv = CREDENTIAL_ENV_KEY.test(rawApiKeyEnv) ? rawApiKeyEnv : null;
+	const apiKeyEnvInvalid = apiKeyEnv === null && rawApiKeyEnv !== "" ? rawApiKeyEnv : null;
 	const api = apiKeyOf(entry["api"]);
 	const protocol = api === null ? "openai" : OCR_PROTOCOL_BY_API.get(api) ?? api;
 	const baseURL = typeof entry["baseURL"] === "string" ? entry["baseURL"].trim() : "";
-	if (!baseURL || !HTTP_URL$1.test(baseURL)) return null;
-	const modelsRaw = Array.isArray(entry["models"]) ? entry["models"] : [];
+	if (!baseURL || !isAcceptableBaseUrl(baseURL)) return null;
+	const modelsField = entry["models"];
+	if (modelsField !== void 0 && modelsField !== null && !Array.isArray(modelsField)) return null;
+	const modelsRaw = Array.isArray(modelsField) ? modelsField : [];
 	const models = modelsRaw.map((model) => modelFromRaw(model)).filter((model) => model !== null);
 	if (modelsRaw.length > 0 && models.length === 0) return null;
 	const displayName = typeof entry["displayName"] === "string" ? entry["displayName"].trim() : "";
@@ -3034,6 +3198,7 @@ function providerFromRaw(name, raw) {
 		name,
 		displayName: displayName === "" ? name : displayName,
 		apiKeyEnv,
+		apiKeyEnvInvalid,
 		protocol,
 		baseURL,
 		models
@@ -3066,23 +3231,35 @@ const SOURCE_READY = Object.freeze({
 /** settings 通道侧抛错（health / descriptors / 投影三处共用同一状态与同一份文案）。 */
 const SOURCE_SETTINGS_FAILED = "settings-failed";
 /**
+* settings 侧任一读取点抛错时的统一出口：空清单 + settings-failed 原因。
+*
+* 抽出来的理由不是「少写几行」：这条是**契约出口**（readProviders 承诺不抛），四处
+* 各手写一份时，改文案或改状态码只改一处就漂了；现在它只在这里定义一次。
+*/
+function settingsFailed(messages, error) {
+	return {
+		providers: [],
+		source: {
+			status: SOURCE_SETTINGS_FAILED,
+			message: format(messages.sourceSettingsFailed, { message: errorText(error) })
+		}
+	};
+}
+/**
 * 读 provider 清单并把一切失败折进 source（不抛）：会话热路径与卡片读面
 * 都只消费返回值，服务缺席/抛错时卡片仍能显示原因。
 */
 function readProviders(gateway, messages) {
-	let health;
+	let settingsUp;
+	let credentialsUp;
 	try {
-		health = gateway.health();
+		const health = gateway.health();
+		settingsUp = health.settings;
+		credentialsUp = health.credentials;
 	} catch (error) {
-		return {
-			providers: [],
-			source: {
-				status: SOURCE_SETTINGS_FAILED,
-				message: format(messages.sourceSettingsFailed, { message: errorText(error) })
-			}
-		};
+		return settingsFailed(messages, error);
 	}
-	if (!health.settings) return {
+	if (!settingsUp) return {
 		providers: [],
 		source: {
 			status: "settings-unavailable",
@@ -3093,26 +3270,14 @@ function readProviders(gateway, messages) {
 	try {
 		descriptors = gateway.descriptors();
 	} catch (error) {
-		return {
-			providers: [],
-			source: {
-				status: SOURCE_SETTINGS_FAILED,
-				message: format(messages.sourceSettingsFailed, { message: errorText(error) })
-			}
-		};
+		return settingsFailed(messages, error);
 	}
 	let hit;
 	try {
 		if (!Array.isArray(descriptors)) throw new TypeError(`ctx.settings.describe() 没有给出数组（收到 ${typeof descriptors}）`);
 		hit = descriptors.find((descriptor) => descriptor.ns === PI_AI_NAMESPACE);
 	} catch (error) {
-		return {
-			providers: [],
-			source: {
-				status: SOURCE_SETTINGS_FAILED,
-				message: format(messages.sourceSettingsFailed, { message: errorText(error) })
-			}
-		};
+		return settingsFailed(messages, error);
 	}
 	if (hit === void 0) return {
 		providers: [],
@@ -3121,7 +3286,7 @@ function readProviders(gateway, messages) {
 			message: format(messages.sourceNamespaceUnavailable, { ns: PI_AI_NAMESPACE })
 		}
 	};
-	const providersValue = fieldOf(hit.value, "providers");
+	const providersValue = fieldOf(hit.value, PROVIDERS_FIELD);
 	if (!isRecord(providersValue)) return {
 		providers: [],
 		source: {
@@ -3133,15 +3298,9 @@ function readProviders(gateway, messages) {
 	try {
 		providers = providersFromSettingsValue(hit.value);
 	} catch (error) {
-		return {
-			providers: [],
-			source: {
-				status: SOURCE_SETTINGS_FAILED,
-				message: format(messages.sourceSettingsFailed, { message: errorText(error) })
-			}
-		};
+		return settingsFailed(messages, error);
 	}
-	if (!health.credentials) return {
+	if (!credentialsUp) return {
 		providers,
 		source: {
 			status: "credentials-unavailable",
@@ -3156,14 +3315,10 @@ function readProviders(gateway, messages) {
 /** 逐 provider 问凭据服务「有没有 key」（并行；只回布尔）。 */
 async function markKeyFlags(gateway, providers) {
 	return await Promise.all(providers.map(async (providerCfg) => {
-		const ref = providerCfg.apiKeyEnv;
-		if (ref === null || ref === "") return {
-			...providerCfg,
-			hasKey: false
-		};
-		let hasKey;
+		let hasKey = false;
 		try {
-			hasKey = await gateway.credentialConfigured(ref);
+			const ref = providerCfg.apiKeyEnv;
+			if (ref !== null && ref !== "") hasKey = await gateway.credentialConfigured(ref);
 		} catch {
 			hasKey = false;
 		}
@@ -3176,10 +3331,9 @@ async function markKeyFlags(gateway, providers) {
 // lib/config-store.ts
 /** api_key_cmd 脚本名（pluginDir 兜底路径的唯一拼法来源）。 */
 const GET_CRED_SCRIPT = path.join("scripts", "get-cred.mjs");
-/** 尾部反斜杠 / 翻倍反斜杠 / env 键 / 行首 node 命令。 */
+/** 尾部反斜杠 / 翻倍反斜杠 / 行首 node 命令。 */
 const TRAILING_BACKSLASHES = /\\+$/u;
 const DOUBLED_BACKSLASHES = /(?:\\\\)+$/u;
-const ENV_KEY = /^[A-Z0-9_]+$/u;
 const LEADING_NODE_CMD = /^node[ \t]+/u;
 /** 未知值 → 安全字符串（非字符串给 ''）。 */
 function strOf(value) {
@@ -3261,10 +3415,11 @@ function shqDyn(value) {
 *  $DSH_HOME > homedir()/.dsh）：ocrConfigPath 重定向 ocr 子进程的 HOME 后，
 *  get-cred 的 homedir() 兜底会跟着跑偏，须在宿主侧把解析出的数据目录显式钉进
 *  命令。undefined（未重定向）时省略，沿用 env/默认档。
-*  env key 白名单维持 ^[A-Z0-9_]+$（刻意比宿主 CredentialRef 的语法紧：OCR 侧
-*  惯例大写，且这是写进 config.json 的可信输入）。 */
+*  env key 白名单是 CREDENTIAL_ENV_KEY（定义在 lib/provider-projection.ts，投影与写侧
+*  共用同一枚；刻意比宿主 CredentialRef 的语法紧：OCR 侧惯例大写，且这是写进
+*  config.json 的可信输入）。 */
 function buildApiKeyCmd(scriptPath, envKey, dshHome, messages) {
-	if (!ENV_KEY.test(envKey)) throw new Error(format(messages.badEnvKey, { key: envKey }));
+	if (!CREDENTIAL_ENV_KEY.test(envKey)) throw new Error(format(messages.badEnvKey, { key: envKey }));
 	const parts = [
 		"node",
 		shqDyn(scriptPath),
@@ -3392,7 +3547,7 @@ function parseApiKeyCmd(command) {
 	if (tokens === null) return null;
 	const script = tokens[0] ?? "";
 	const envKey = tokens[1] ?? "";
-	if (script === "" || tokens.length < 2 || tokens.length > 3 || !ENV_KEY.test(envKey)) return null;
+	if (script === "" || tokens.length < 2 || tokens.length > 3 || !CREDENTIAL_ENV_KEY.test(envKey)) return null;
 	return {
 		script,
 		envKey,
@@ -3438,6 +3593,27 @@ async function updateConfigLocked(targetPath, operation) {
 	return withFileLock(targetPath, operation);
 }
 /**
+* 原子写回的落点：符号链接解到真身。
+*
+* ocr CLI 自己用 `os.WriteFile`（跟随链接）写这份配置，用户把 `config.json` 链到
+* dotfiles 仓库是常见用法。官方 `writeFileAtomic` 以 rename 提交，它会**替换链接本身**
+* （包内文档原文："replaces a symlinked target itself instead of writing through to its
+* referent"），于是链接消失、真身停在旧内容，配置仓库从此与运行配置脱钩。
+* `realpath` 对普通文件返回自身、对链接返回最终真身，一条判据就够；悬空链接解不出真身，
+* 按链接文本定位它指向的位置（首写会创建该文件）；文件尚未存在时两者都失败，仍用原路径。
+*/
+async function writableTargetOf(targetPath) {
+	try {
+		return await realpath(targetPath);
+	} catch {
+		try {
+			return path.resolve(path.dirname(targetPath), await readlink(targetPath));
+		} catch {
+			return targetPath;
+		}
+	}
+}
+/**
 * 原子写回 config.json：先留 `.bak` 备份，再交官方 `writeFileAtomic` 落盘。
 * 此前是 `writeFileSync` 直写：进程/磁盘在写入中途出问题就会留下半截配置
 * （OCR 与用户都读不到），且没有任何回滚点。rename 在同目录内是原子的。
@@ -3446,14 +3622,24 @@ async function updateConfigLocked(targetPath, operation) {
 * 创建（`dirMode`）与新 inode 携带 `mode` 全是官方件既有行为，本仓不再手抄
 * （实测）。本地只剩 `.bak`：官方写文件面无备份语义，且备份必须落在
 * rename **之前**——挪到之后备份到的就是新内容。
+*
+* 备份的权限必须**在创建那一刻**就是 0600：备份里可能仍有迁移前的明文 api_key，
+* 而 `copyFileSync` 沿用源文件权限位，"先复制再 chmod"之间既有宽权限窗口，中途
+* 崩溃/被杀还会把宽权限永久留下。因此先删旧备份、再按 0600 直接创建；删与写之间
+* 崩溃只会少一份备份，目标文件尚未动过。
 */
 async function writeConfigAtomic(targetPath, text) {
+	const target = await writableTargetOf(targetPath);
 	const bakPath = `${targetPath}.bak`;
-	if (existsSync(targetPath)) {
-		copyFileSync(targetPath, bakPath);
-		chmodSync(bakPath, 384);
+	if (existsSync(target)) {
+		const previous = readFileSync(target);
+		rmSync(bakPath, { force: true });
+		writeFileSync(bakPath, previous, {
+			mode: 384,
+			flag: "wx"
+		});
 	}
-	await writeFileAtomic(targetPath, text, {
+	await writeFileAtomic(target, text, {
 		mode: 384,
 		dirMode: 448
 	});
@@ -3505,7 +3691,8 @@ function renderSelectedConfig(input, messages) {
 	customs[input.provider] = entry;
 	doc["provider"] = input.provider;
 	doc["custom_providers"] = customs;
-	if (input.language !== void 0) doc["language"] = input.language;
+	const language = input.language?.trim();
+	if (language !== void 0 && language !== "") doc["language"] = language;
 	return `${JSON.stringify(doc, null, 2)}\n`;
 }
 /**
@@ -3662,8 +3849,9 @@ async function providersForCard(gateway, paths, messages, endpointVerify) {
 * 任何一步不合条件都抛可读错误（Remote 的 select/migrate 兜成 `status: 400`，卡片显示原因）。
 */
 async function applyProviderSelection(gateway, paths, selection, messages) {
-	const { provider, model } = selection;
-	if (typeof provider !== "string" || typeof model !== "string" || provider.trim() === "" || model.trim() === "") throw new Error(format(messages.providerModelRequired, {}));
+	if (typeof selection.provider !== "string" || typeof selection.model !== "string" || selection.provider.trim() === "" || selection.model.trim() === "") throw new Error(format(messages.providerModelRequired, {}));
+	const provider = selection.provider.trim();
+	const model = selection.model.trim();
 	const { providers, source } = readProviders(gateway, messages);
 	if (source.status !== "ready") throw new Error(source.message);
 	const target = providers.find((providerCfg) => providerCfg.name === provider);
@@ -3671,7 +3859,11 @@ async function applyProviderSelection(gateway, paths, selection, messages) {
 		ns: PI_AI_NAMESPACE,
 		provider
 	}));
-	if (target.apiKeyEnv === null || target.apiKeyEnv === "") throw new Error(format(messages.noApiKeyEnv, { provider }));
+	if (target.apiKeyEnv === null) {
+		const invalid = target.apiKeyEnvInvalid;
+		if (invalid !== null) throw new Error(format(messages.badEnvKey, { key: invalid }));
+		throw new Error(format(messages.noApiKeyEnv, { provider }));
+	}
 	const keySource = await gateway.credentialSource(target.apiKeyEnv);
 	if (keySource === void 0) throw new Error(format(messages.keyNotResolvable, {
 		provider,
@@ -3693,7 +3885,7 @@ async function applyProviderSelection(gateway, paths, selection, messages) {
 			provider,
 			model,
 			apiKeyCmd,
-			...selection.language === void 0 ? {} : { language: selection.language }
+			...selection.language === void 0 || selection.language.trim() === "" ? {} : { language: selection.language.trim() }
 		}, messages);
 		await writeConfigAtomic(paths.ocrConfigJson, next);
 	});
@@ -3711,20 +3903,19 @@ async function applyProviderSelection(gateway, paths, selection, messages) {
 */
 function migrateEntry(entry, envKey, context) {
 	if (typeof entry["api_key"] !== "string" || entry["api_key"].length === 0) return "noPlain";
+	const existingCmd = entry["api_key_cmd"];
+	if (typeof existingCmd === "string" && existingCmd.trim() !== "") return "unknown";
 	if (envKey === void 0 || envKey === "" || !context.reachableEnvKeys.has(envKey)) return "unknown";
-	try {
-		entry["api_key_cmd"] = buildApiKeyCmd(context.scriptPath, envKey, context.dshHome, context.messages);
-	} catch {
-		return "unknown";
-	}
+	entry["api_key_cmd"] = buildApiKeyCmd(context.scriptPath, envKey, context.dshHome, context.messages);
 	delete entry["api_key"];
 	return "migrated";
 }
 /**
 * 迁移：把自定义 provider 条目里的明文 api_key 改为 api_key_cmd（动态读凭据）。
 * api_key_cmd 优先于 api_key，因此清除明文即可。
-* 对「明文 api_key + 无 api_key_cmd」的条目，依据 settings 里该 provider 的
-* apiKeyEnv 补充命令；settings 里找不到的 provider 不动（不破坏既有配置），
+* 只对「明文 api_key + 无 api_key_cmd」的条目动手，依据 settings 里该 provider 的
+* apiKeyEnv 补充命令；**已有非空 api_key_cmd 的条目不覆写**（那条命令可能正在生效，
+* 换掉它等于无声改配置），与 settings 里找不到的 provider 一起记进 skippedUnknown，
 * 在返回信息里说明。credentials 缺席不阻断本操作（它只要 name→apiKeyEnv 映射），
 * settings 侧读不到则抛错——那正是「不知道该写哪条命令」的状态，静默跳过会让用户
 * 以为迁移过了。
@@ -3776,7 +3967,7 @@ async function migratePlaintextKeys(gateway, paths, messages) {
 			migrated,
 			skippedUnknown
 		};
-		await writeConfigAtomic(paths.ocrConfigJson, `${JSON.stringify(doc, null, 2)}\n`);
+		await writeConfigAtomic(paths.ocrConfigJson, renderConfigDoc(doc));
 		return {
 			migrated,
 			skippedUnknown
@@ -3793,8 +3984,10 @@ async function migratePlaintextKeys(gateway, paths, messages) {
 * 为什么永不抛错：这是锦上添花的修复，不能因为它把工具拖死。坏 JSON、锁抢不到、权限
 * 不足、设置项写坏——一律放过，让 ocr 报它自己的原始错误，那才是诊断价值最高的形态。
 *
-* 常态零锁开销：先无锁读一次做判据，确实要改写才进 withFileLock（锁内按新快照重判，
-* 避免把并发写入的 provider 选择覆盖掉）。
+* 锁外那一次读只用于区分两种**不需要动锁**的状态：文件不存在/空白（连配置目录都不该
+* 被凭空造出来）与读不动（报 checked: false）。其余一律进 withFileLock，并在锁内按
+* 新快照重判——不拿锁外快照决定「要不要改」，那份快照随时可能过期，为省一次锁而多留
+* 一个只能靠并发触发的分支不值。
 */
 async function ensureKeyScriptPointer(paths, messages) {
 	const scriptPath = credentialScriptPath(paths);
@@ -3840,11 +4033,37 @@ async function ensureKeyScriptPointer(paths, messages) {
 // lib/remote-shape.ts
 /** 宿主服务键 = 客户端线上命名空间（两侧共用的唯一来源）。 */
 const OCR_REMOTE_NAMESPACE = "ocrReview";
+/**
+* 拒绝回执的**种类码**（`status` 位）的唯一出处。
+*
+* 不是 HTTP 状态：本包已无 HTTP 面，卡片只读 `error`。集中定义的理由是它此前只是裸
+* `number`：宿主实现在十几处各写一次字面量、类型收不到任何提示，调用方也分不清
+* 「本包自定的种类码」与顺手塞进来的 HTTP 状态码。测试仍**独立写死**数字（不从这份表
+* 派生），否则两边一起错时判据会跟着错。
+*
+* · `invalid`：入参/配置不合法，卡片改完就能重试。
+* · `internal`：宿主侧读取或执行失败（读不到配置、子进程起不来），不是改参数能解决的。
+*/
+const OCR_REFUSE_STATUS = {
+	invalid: 400,
+	internal: 500
+};
 // lib/mcp-config.ts
 /** 整体上限：MCP 配置是一份人工维护的小表，不承载大文件。 */
 const MCP_MAX_BYTES = 65536;
-/** remote MCP server 的 url 只认 http(s)。 */
-const HTTP_URL = /^https?:\/\//iu;
+/**
+* remote MCP server 的 url 只认 http(s)，且必须解析得出一台主机。
+* 前缀匹配（旧实现）会放行 "http://" 这种没有主机的串——写进配置时不报错，OCR 到连接时才炸，
+* 报错点离用户动作很远，所以在这里用 URL 解析判它。
+*/
+function isHttpServerUrl(value) {
+	try {
+		const parsed = new URL(value);
+		return (parsed.protocol === "http:" || parsed.protocol === "https:") && parsed.hostname !== "";
+	} catch {
+		return false;
+	}
+}
 const MCP_MAX_SERVERS = 100;
 const MCP_MAX_ARRAY = 100;
 const MCP_MAX_TEXT = 4096;
@@ -3858,6 +4077,19 @@ const KNOWN_FIELDS = /* @__PURE__ */ new Set([
 	"setup",
 	"env"
 ]);
+/**
+* `mcp_servers` 这一支的摘要，读侧交给卡片、写侧在锁内重算后比对。
+*
+* 只覆盖 `mcp_servers`：保存本来也只改这一支，`providers`/keys 等由别的动作维护，把它们
+* 算进基线会让「改了别处」也变成保存冲突。取值用 `JSON.stringify` 的紧凑形态——两侧都由
+* 同一份文本解析而来，键序一致，摘要可直接逐字节比较。
+*
+* @param servers - 从 config.json 解析出的 `mcp_servers`（缺省按空表）
+* @returns sha256 十六进制摘要
+*/
+function mcpServersRevision(servers) {
+	return createHash("sha256").update(JSON.stringify(servers)).digest("hex");
+}
 function failure(name, field, reason, messages) {
 	return {
 		ok: false,
@@ -3868,6 +4100,19 @@ function failure(name, field, reason, messages) {
 		})
 	};
 }
+/**
+* 用 CreateDataProperty 落动态键，再把原型置空。
+*
+* `out[name] = value` 在 name 为 "__proto__" 时走的是 Object.prototype 的 setter：该条目
+* 既不会成为自有属性（写进 config.json 后静默少一条 server），value 还成了 out 的原型。
+* Object.fromEntries 走 CreateDataProperty，__proto__ 会落成普通自有键（实测：hasOwn 为 true、
+* 原型仍是 Object.prototype、JSON.stringify 带上它）；置空原型是让读侧查不到继承成员。
+*/
+function recordOf(entries) {
+	const out = Object.fromEntries(entries);
+	Object.setPrototypeOf(out, null);
+	return out;
+}
 function textField(value, name, field, messages) {
 	if (typeof value !== "string" || value.trim() === "") return failure(name, field, "must be a non-empty string", messages);
 	const trimmed = value.trim();
@@ -3891,14 +4136,14 @@ function stringArray(value, name, field, messages) {
 }
 function headersField(value, name, messages) {
 	if (!isRecord(value) || Object.keys(value).length > 50) return failure(name, "headers", "must be an object of at most 50 string headers", messages);
-	const out = {};
+	const headers = [];
 	for (const [header, raw] of Object.entries(value)) {
 		if (header.trim() === "" || typeof raw !== "string" || raw.length > MCP_MAX_TEXT) return failure(name, `headers.${header}`, "must be a non-empty name and a string value", messages);
-		out[header] = raw;
+		headers.push([header, raw]);
 	}
 	return {
 		ok: true,
-		value: out
+		value: recordOf(headers)
 	};
 }
 function normalizeStdio(raw, name, messages) {
@@ -3934,7 +4179,7 @@ function normalizeRemote(raw, name, messages) {
 	if (raw["command"] !== void 0 || raw["args"] !== void 0 || raw["env"] !== void 0 || raw["setup"] !== void 0) return failure(name, "type", "remote does not accept command/args/env/setup", messages);
 	const url = textField(raw["url"], name, "url", messages);
 	if (!url.ok) return url;
-	if (!HTTP_URL.test(url.value)) return failure(name, "url", "must start with http:// or https://", messages);
+	if (!isHttpServerUrl(url.value)) return failure(name, "url", "must be a valid http:// or https:// URL with a host", messages);
 	const entry = {
 		type: "remote",
 		url: url.value
@@ -3949,10 +4194,33 @@ function normalizeRemote(raw, name, messages) {
 		value: entry
 	};
 }
-/** 单个 server 条目 → 只含已知字段的普通对象；未知字段直接拒绝，避免写出 OCR 不认的配置。 */
-function normalizeServer(name, raw, messages) {
+/**
+* 单个 server 条目 → 只含已知字段的普通对象。
+*
+* 未知字段默认拒绝（避免写出 OCR 不认的配置），但**盘上同一条目已有的未知字段会原样接回**：
+* OCR 自己的 MCPServerConfig 带 unknownJSONFields 契约（读进来不认识的键在来回写时留着），
+* 手写或新版写下的字段在这里丢掉，等于用户改一个字段就静默删掉另一个。
+* 判据是「基线里出现过这个键」——新条目里出现未知键仍判非法，否则一次拼错会被写成 OCR 忽略的键。
+*/
+/**
+* 未知字段的保留判据（理由见 normalizeServer 的 JSDoc）。
+*/
+function preservedFieldsOf(name, raw, baseline, messages) {
+	const preserved = [];
+	for (const field of Object.keys(raw)) if (!KNOWN_FIELDS.has(field)) {
+		if (baseline !== void 0 && !(isRecord(baseline) && Object.hasOwn(baseline, field))) return failure(name, field, "is not a supported MCP field", messages);
+		preserved.push([field, raw[field]]);
+	}
+	return {
+		ok: true,
+		value: preserved
+	};
+}
+function normalizeServer(name, raw, messages, baseline) {
 	if (!isRecord(raw)) return failure(name, "entry", "must be an object", messages);
-	for (const field of Object.keys(raw)) if (!KNOWN_FIELDS.has(field)) return failure(name, field, "is not a supported MCP field", messages);
+	const preservedFields = preservedFieldsOf(name, raw, baseline, messages);
+	if (!preservedFields.ok) return preservedFields;
+	const preserved = preservedFields.value;
 	const type = raw["type"] === void 0 ? "stdio" : raw["type"];
 	if (type !== "stdio" && type !== "remote") return failure(name, "type", "must be stdio or remote", messages);
 	const base = type === "stdio" ? normalizeStdio(raw, name, messages) : normalizeRemote(raw, name, messages);
@@ -3962,9 +4230,10 @@ function normalizeServer(name, raw, messages) {
 		if (!tools.ok) return tools;
 		base.value["tools"] = tools.value;
 	}
+	for (const [field, value] of preserved) base.value[field] = value;
 	return base;
 }
-function normalizeServers(raw, messages) {
+function normalizeServers(raw, messages, baseline) {
 	if (!isRecord(raw)) return {
 		ok: false,
 		error: messages.mcpShapeInvalid
@@ -3974,26 +4243,35 @@ function normalizeServers(raw, messages) {
 		ok: false,
 		error: format(messages.mcpTooManyServers, { limit: String(MCP_MAX_SERVERS) })
 	};
-	const out = {};
+	const entries = [];
 	for (const name of names) {
 		if (name.trim() === "" || name.includes("\0") || name.length > 64) return failure(name, "name", "must be a non-empty key of at most 64 characters", messages);
-		const parsed = normalizeServer(name, raw[name], messages);
+		const entryBaseline = baseline === void 0 ? void 0 : baseline[name] ?? {};
+		const parsed = normalizeServer(name, raw[name], messages, entryBaseline);
 		if (!parsed.ok) return parsed;
-		out[name] = parsed.value;
+		entries.push([name, parsed.value]);
 	}
 	return {
 		ok: true,
-		value: out
+		value: recordOf(entries)
 	};
 }
-/** 读侧用异步读：卡片端点是 async 面，读大文件时不该占住事件循环。 */
 function isNotFound(error) {
 	return isRecord(error) && error["code"] === "ENOENT";
 }
-/** 读当前 `mcp_servers`，交给卡片编辑；文件不存在按空表处理，坏 JSON/读不动返回可读错误。 */
+/**
+* 读当前 `mcp_servers`，交给卡片编辑；文件不存在按空表处理，坏 JSON/读不动返回可读错误。
+*
+* 读侧是 async 面（卡片端点不该占住事件循环），且**先 stat 再读**：写侧有 MCP_MAX_BYTES
+* 上限，读侧不设闸就等于允许任意大的 config.json 整个进内存。
+*/
 async function readMcpServers(configPath, messages) {
 	let text;
 	try {
+		if ((await stat(configPath)).size > MCP_MAX_BYTES) return {
+			ok: false,
+			error: format(messages.mcpJsonTooLarge, { limit: String(MCP_MAX_BYTES) })
+		};
 		text = await readFile(configPath, "utf8");
 	} catch (error) {
 		if (!isNotFound(error)) return {
@@ -4007,7 +4285,8 @@ async function readMcpServers(configPath, messages) {
 	}
 	if (!text.trim()) return {
 		ok: true,
-		json: "{}"
+		json: "{}",
+		revision: mcpServersRevision({})
 	};
 	let doc;
 	try {
@@ -4024,7 +4303,8 @@ async function readMcpServers(configPath, messages) {
 	const servers = doc["mcp_servers"];
 	if (servers === void 0 || servers === null) return {
 		ok: true,
-		json: "{}"
+		json: "{}",
+		revision: mcpServersRevision({})
 	};
 	if (!isRecord(servers)) return {
 		ok: false,
@@ -4032,11 +4312,24 @@ async function readMcpServers(configPath, messages) {
 	};
 	return {
 		ok: true,
-		json: JSON.stringify(servers, null, 2)
+		json: JSON.stringify(servers, null, 2),
+		revision: mcpServersRevision(servers)
 	};
 }
-/** 校验并写回 `mcp_servers`；只改这一支，其余配置原样保留。 */
-async function saveMcpServers(configPath, json, messages) {
+/**
+* 校验并写回 `mcp_servers`；只改这一支，其余配置原样保留。
+*
+* `revision` 是读侧交回的基线：锁内重算盘上这一支的摘要，与基线不一致就整笔拒绝。没有这道
+* 比较时，两张设置卡（或卡片与手工编辑）先后保存，后一笔会把前一笔新增/修改的条目整段覆盖掉，
+* 而两笔各自都「成功」。
+*
+* @param configPath - 目标 config.json
+* @param json - 卡片交回的 `mcp_servers` JSON 文本
+* @param messages - 双语文案
+* @param revision - 读侧交回的摘要；`undefined` 表示调用方没有基线（旧客户端），跳过比较
+* @returns 保存后的条数与新摘要，或拒绝理由
+*/
+async function saveMcpServers(configPath, json, messages, revision) {
 	if (Buffer.byteLength(json, "utf8") > MCP_MAX_BYTES) return {
 		ok: false,
 		error: format(messages.mcpJsonTooLarge, { limit: String(MCP_MAX_BYTES) })
@@ -4050,22 +4343,30 @@ async function saveMcpServers(configPath, json, messages) {
 			error: format(messages.mcpJsonInvalid, { cause: String(error) })
 		};
 	}
-	const normalized = normalizeServers(raw, messages);
-	if (!normalized.ok) return normalized;
+	const shaped = normalizeServers(raw, messages);
+	if (!shaped.ok) return shaped;
 	try {
-		return {
-			ok: true,
-			count: await updateConfigLocked(configPath, async () => {
-				const doc = parseExistingConfig(readExistingText(configPath, messages), configPath, messages);
-				doc["mcp_servers"] = normalized.value;
-				await writeConfigAtomic(configPath, `${JSON.stringify(doc, null, 2)}\n`);
-				return Object.keys(normalized.value).length;
-			})
-		};
+		return await updateConfigLocked(configPath, async () => {
+			const doc = parseExistingConfig(readExistingText(configPath, messages), configPath, messages);
+			const existing = isRecord(doc["mcp_servers"]) ? doc["mcp_servers"] : {};
+			if (revision !== void 0 && mcpServersRevision(existing) !== revision) return {
+				ok: false,
+				error: messages.mcpSaveConflict
+			};
+			const normalized = normalizeServers(raw, messages, existing);
+			if (!normalized.ok) return normalized;
+			doc["mcp_servers"] = normalized.value;
+			await writeConfigAtomic(configPath, `${JSON.stringify(doc, null, 2)}\n`);
+			return {
+				ok: true,
+				count: Object.keys(normalized.value).length,
+				revision: mcpServersRevision(normalized.value)
+			};
+		});
 	} catch (error) {
 		return {
 			ok: false,
-			error: format(messages.mcpReadFailed, {
+			error: format(messages.mcpSaveFailed, {
 				where: configPath,
 				cause: String(error)
 			})
@@ -4080,10 +4381,16 @@ async function applyChatGptModel(configPath, model, messages) {
 		error: messages.chatGptModelRequired
 	};
 	try {
-		await updateConfigLocked(configPath, async () => {
+		return await updateConfigLocked(configPath, async () => {
 			const doc = parseExistingConfig(readExistingText(configPath, messages), configPath, messages);
-			const providers = isRecord(doc["providers"]) ? doc["providers"] : {};
-			const entry = isRecord(providers["chatgpt"]) ? providers["chatgpt"] : {};
+			const providersRaw = doc["providers"];
+			const entryRaw = isRecord(providersRaw) ? providersRaw["chatgpt"] : void 0;
+			if (providersRaw !== void 0 && providersRaw !== null && !isRecord(providersRaw) || entryRaw !== void 0 && entryRaw !== null && !isRecord(entryRaw)) return {
+				ok: false,
+				error: messages.chatGptProvidersInvalid
+			};
+			const providers = isRecord(providersRaw) ? providersRaw : {};
+			const entry = isRecord(entryRaw) ? entryRaw : {};
 			delete entry["api_key"];
 			delete entry["api_key_cmd"];
 			entry["model"] = trimmed;
@@ -4091,8 +4398,8 @@ async function applyChatGptModel(configPath, model, messages) {
 			doc["providers"] = providers;
 			doc["provider"] = "chatgpt";
 			await writeConfigAtomic(configPath, `${JSON.stringify(doc, null, 2)}\n`);
+			return { ok: true };
 		});
-		return { ok: true };
 	} catch (error) {
 		return {
 			ok: false,
@@ -4319,8 +4626,8 @@ function textBlock(value) {
 * 按调用携带的 `SandboxPolicyRequest` 只有 `session` 与 `mode` 两个字段，**没有**附加可写
 * 路径、没有自定义 HOME、没有目录级豁免；而 `SandboxMode` 的取值只有
 * `read-only | workspace-write | danger-full-access` 三档，中间那一档的可写根就是
-* `workspaceRoot` 一枚。两处声明都取自本包实际解析到的那版（dsh-sandbox-policy 与
-* dsh-sandbox 的 0.2.1-rc.3，`lib/types/index.d.ts`）。
+* `workspaceRoot` 一枚。两处声明都取自本包实际解析到的 dsh-sandbox-policy 与
+* dsh-sandbox 的 `lib/types/index.d.ts`。
 * 可选的收紧路径只有「改 ocr 自己的状态落点」或「等上游加字段」，两者都不是本包能在
 * 一次补丁里做完的事。故此处维持放开，但把边界写明：放开的是 ocr 这一个子进程的整棵
 * 文件系统写权限，不是宿主其它能力；且 ocr 读什么、写什么仍由上面那条 argv 闸与
@@ -4469,8 +4776,14 @@ async function startBackground(host, job, ledger) {
 		sandboxPolicy: ocrSandboxPolicy(job.workdir)
 	});
 	const proc = await host.shell.execute(spec);
-	pruneOcrJobHistory(registry, job.owner, ledger);
-	const messages = localeMessages(host);
+	let messages;
+	try {
+		pruneOcrJobHistory(registry, job.owner, ledger);
+		messages = localeMessages(host);
+	} catch (error) {
+		killProc(proc);
+		throw error;
+	}
 	let jobId;
 	try {
 		jobId = startUnderOcrController(registry, {
@@ -4879,7 +5192,7 @@ function cliStatusPayload(status, config, messages, measured) {
 * @returns 同一份摘要，或 hint 尾部多了一句的副本。
 */
 function withCliVersionNote(summary, measured, messages) {
-	if (measured === null || measured === "1.13.3") return summary;
+	if (measured === null || measured === "1.13.4") return summary;
 	const note = format(messages.versionMismatch, {
 		actual: measured,
 		expected: EXPECTED_OCR_CLI_VERSION
@@ -4905,14 +5218,15 @@ async function runLlmTest(host, config) {
 	};
 }
 /** effort 入参闸：undefined/null → 设置卡默认（auto 表示跟随 OCR 配置）；字符串 →
-*  白名单钳制（未知值回落 auto，与 --format 同一纪律）；其余类型抛错——静默回落会改变审查深度。 */
+*  白名单钳制（未知值按「未指定」处理，回落设置卡值，与 undefined 同一条路）；其余类型抛错
+*  ——静默回落会改变审查深度，所以类型错误必须当场说，而认不出的字符串只能当没指定。 */
 function effortOf(value, config, messages) {
 	if (value === void 0 || value === null) return readEffort(config);
 	if (typeof value !== "string") throw new TypeError(format(messages.mustBeString, {
 		name: "effort",
 		received: describeValue(value)
 	}));
-	return clampEffort(value, "medium");
+	return clampEffort(value, readEffort(config));
 }
 /**
 * wait 入参闸：undefined → **false（后台缺省）**；布尔透传；其余类型抛错——字符串
@@ -5029,7 +5343,7 @@ async function canonicalReviewRoot(host, root) {
 			stdoutMaxBytes: 4096
 		});
 		const top = exitCode === 0 ? output.trim() : "";
-		if (top.startsWith("/")) return top;
+		if (path.isAbsolute(top)) return top;
 	} catch {}
 	return realpathOrSelf(root);
 }
@@ -5045,7 +5359,7 @@ async function selectReply(provider, model, deps) {
 	if (provider === "" || model === "") return {
 		ok: false,
 		error: msgs.providerModelRequired,
-		status: 400
+		status: OCR_REFUSE_STATUS.invalid
 	};
 	try {
 		const language = readLanguage(deps.config);
@@ -5065,7 +5379,7 @@ async function selectReply(provider, model, deps) {
 		return {
 			ok: false,
 			error: errorText(error),
-			status: 400
+			status: OCR_REFUSE_STATUS.invalid
 		};
 	}
 }
@@ -5102,7 +5416,7 @@ async function probeReply(deps) {
 		return {
 			ok: false,
 			error: errorText(error),
-			status: 400
+			status: OCR_REFUSE_STATUS.invalid
 		};
 	}
 }
@@ -5124,7 +5438,7 @@ async function providersReply(deps) {
 		return {
 			ok: false,
 			error: errorText(error),
-			status: 500
+			status: OCR_REFUSE_STATUS.internal
 		};
 	}
 }
@@ -5140,7 +5454,7 @@ async function migrateReply(deps) {
 		return {
 			ok: false,
 			error: errorText(error),
-			status: 400
+			status: OCR_REFUSE_STATUS.invalid
 		};
 	}
 }
@@ -5156,7 +5470,7 @@ async function testReply(deps) {
 		return {
 			ok: false,
 			error: errorText(error),
-			status: 400
+			status: OCR_REFUSE_STATUS.invalid
 		};
 	}
 }
@@ -5166,39 +5480,59 @@ async function mcpReply(deps) {
 		const result = await readMcpServers(pluginPaths(deps.config, msgs).ocrConfigJson, msgs);
 		return result.ok ? {
 			ok: true,
-			json: result.json
+			json: result.json,
+			revision: result.revision
 		} : {
 			ok: false,
 			error: result.error,
-			status: 400
+			status: OCR_REFUSE_STATUS.invalid
 		};
 	} catch (error) {
 		return {
 			ok: false,
 			error: errorText(error),
-			status: 500
+			status: OCR_REFUSE_STATUS.internal
 		};
 	}
 }
-async function saveMcpReply(json, deps) {
+/** 保存回执：`request` 是整笔入参（`json` 与可选的基线 `revision`），两者都要过形态判定。 */
+async function saveMcpReply(request, deps) {
 	const msgs = deps.messages();
+	const { json, revision } = isRecord(request) ? request : {};
 	if (typeof json !== "string") return {
 		ok: false,
 		error: format(msgs.mustBeString, {
 			name: "json",
 			received: describeValue(json)
 		}),
-		status: 400
+		status: OCR_REFUSE_STATUS.invalid
 	};
-	const result = await saveMcpServers(pluginPaths(deps.config, msgs).ocrConfigJson, json, msgs);
-	return result.ok ? {
-		ok: true,
-		count: result.count
-	} : {
+	if (revision !== void 0 && typeof revision !== "string") return {
 		ok: false,
-		error: result.error,
-		status: 400
+		error: format(msgs.mustBeString, {
+			name: "revision",
+			received: describeValue(revision)
+		}),
+		status: OCR_REFUSE_STATUS.invalid
 	};
+	try {
+		const result = await saveMcpServers(pluginPaths(deps.config, msgs).ocrConfigJson, json, msgs, revision);
+		return result.ok ? {
+			ok: true,
+			count: result.count,
+			revision: result.revision
+		} : {
+			ok: false,
+			error: result.error,
+			status: OCR_REFUSE_STATUS.invalid
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			error: errorText(error),
+			status: OCR_REFUSE_STATUS.internal
+		};
+	}
 }
 async function authReply(deps) {
 	try {
@@ -5216,7 +5550,7 @@ async function authReply(deps) {
 		return {
 			ok: false,
 			error: errorText(error),
-			status: 400
+			status: OCR_REFUSE_STATUS.invalid
 		};
 	}
 }
@@ -5228,17 +5562,25 @@ async function chatGptReply(model, deps) {
 			name: "model",
 			received: describeValue(model)
 		}),
-		status: 400
-	};
-	const result = await applyChatGptModel(pluginPaths(deps.config, msgs).ocrConfigJson, model, msgs);
-	return result.ok ? {
-		ok: true,
-		model: model.trim()
-	} : {
-		ok: false,
-		error: result.error,
-		status: 400
+		status: OCR_REFUSE_STATUS.invalid
 	};
+	try {
+		const result = await applyChatGptModel(pluginPaths(deps.config, msgs).ocrConfigJson, model, msgs);
+		return result.ok ? {
+			ok: true,
+			model: model.trim()
+		} : {
+			ok: false,
+			error: result.error,
+			status: OCR_REFUSE_STATUS.invalid
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			error: errorText(error),
+			status: OCR_REFUSE_STATUS.internal
+		};
+	}
 }
 /**
 * 设置卡的九条读/写方法（providers / select / migrate / test / probe / mcp / saveMcp / auth / chatGpt）。
@@ -5284,9 +5626,9 @@ var OcrReviewRemoteService = class extends TypertRemoteService {
 	async mcp() {
 		return mcpReply(this.deps);
 	}
-	/** 校验并写入 `mcp_servers`；其他配置原样保留。 */
+	/** 校验并写入 `mcp_servers`；其他配置原样保留。`revision` 为读侧基线，不一致即整笔拒绝。 */
 	async saveMcp(request) {
-		return saveMcpReply(isRecord(request) ? request.json : void 0, this.deps);
+		return saveMcpReply(request, this.deps);
 	}
 	/** 只读查询 ChatGPT 登录态；登录命令原样带回给卡片显示。 */
 	async auth() {
@@ -5906,7 +6248,7 @@ function registerSessionTool(host, config, probe) {
 					repo
 				}, runMsgs);
 				const stdout = await runForeground(host, withHomeEnv(command, ocrHome(config)), workdir, tuningOf(config), exec.signal);
-				const parsed = parseSessionCompare(stdout.text);
+				const parsed = parseSessionCompare(stdout.text, runMsgs);
 				if (parsed.ok) return {
 					...parsed.view,
 					hint: runMsgs.sessionCompareHint
@@ -6054,7 +6396,9 @@ function endpointVerifyOf(result) {
 	};
 }
 async function probeEndpointAtApply(host, config, sink) {
-	sink.value = endpointVerifyOf(await runLlmTest(host, config));
+	try {
+		sink.value = endpointVerifyOf(await runLlmTest(host, config));
+	} catch {}
 }
 /**
 * 装载期版本自检（fire-and-forget）：跑一次 `ocr version`，把实测版本落在本次 apply 的闭包里。
@@ -6068,7 +6412,9 @@ async function probeEndpointAtApply(host, config, sink) {
 * @param sink 本次 apply 的闭包槽（与 POST probe 写的是同一个）
 */
 async function probeVersionAtApply(host, config, sink) {
-	sink.value = (await runVersionProbe(host, config, localeMessages(host))).version;
+	try {
+		sink.value = (await runVersionProbe(host, config, localeMessages(host))).version;
+	} catch {}
 }
 function apply(ctx, config, probe) {
 	const host = resolveHost(ctx);