@jayyuen66/dsh-ocr-review 0.1.4-rc → 0.1.4

package/host.js

@@ -27,9 +27,9 @@ 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) 看元数据与逐文件检查点。后台运行不设宿主超时，只在 2 小时后兜底回收（挂死不动会一直占着官方作业桶），取消本工具调用即终止该后台 OCR（宿主 kill + 命令内回收守护）。",
+		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，默认 2 小时）到点后回收（挂死不动会一直占着官方作业桶），取消本工具调用即终止该后台 OCR（宿主 kill + 命令内回收守护）。",
 		jobReasonAborted: "ocr-review 工具调用被中止",
-		jobReasonTimeout: "ocr-review 后台评审超过 2 小时，兜底回收",
+		jobReasonTimeout: "ocr-review 后台评审超过兜底窗口（{minutes} 分钟），兜底回收",
 		jobReasonUnload: "ocr-review 插件卸载",
 		jobOutputGap: "\n[ocr-review] 注意：有一次输出读取失败，已按原游标重试（这段可能不完整）",
 		requiredNotArray: "parameters.required 必须是字符串数组",
@@ -83,6 +83,7 @@ const MESSAGES = {
 		configPathLayoutInvalid: "设置项 ocrConfigPath 必须是 <X>/.opencodereview/config.json 布局：{path}。OCR 端没有配置文件级的路径覆盖（只按 <HOME>/.opencodereview/config.json 定位），本插件通过给 ocr 子进程注入 HOME=<X> 让它生效；任意形状的文件路径写下去 OCR 也不会读",
 		noApiKeyEnv: "provider {provider} 未声明 apiKeyEnv，无法动态读取 key（OCR 自定义 provider 不支持无 key 解析）",
 		keyNotResolvable: "provider {provider} 的 API key 未配置：dsh 凭据服务未解析到 {ref}",
+		keyNotReachable: "provider {provider} 的 API key 存在于凭据层「{source}」，OCR 运行时取不到它：dsh 起 shell 会剥掉名字含 KEY/PASSWORD/SECRET/TOKEN 或 DSH_ 前缀的环境变量，get-cred 也刻意不读被审查仓库的 .env。请把 key 存入 dsh 托管凭据（$DSH_HOME/.credentials.yaml 的 refs.{ref}）或 $DSH_HOME/.env 后重试",
 		credScriptMissing: "get-cred 脚本缺失：{path}（api_key_cmd 无法工作）",
 		reaperDegraded: "[ocr-review] 宿主回收守护已降级：ps/pgrep 不可用（进程信息命令被沙箱拒绝），改由宿主管进程树。dsh 硬退出时 ocr 可能留孤儿进程。",
 		warningUnreadable: "（一条格式无法解析的 warning：既不是字符串，也没有 file/error 字段）",
@@ -108,7 +109,7 @@ const MESSAGES = {
 		paramBackgroundPreview: "业务上下文（会出现在输出中供审查参考）",
 		paramExclude: "gitignore 风格排除模式（可多值）",
 		paramExcludeShort: "排除模式",
-		paramWait: "true（缺省）=等待完成并返回聚合摘要；false=后台启动立即返回（2 小时后兜底回收），用 ocr_session 轮询结果。两种模式都带宿主回收守护：dsh 退出（含 kill -9）时 OCR 进程一并结束",
+		paramWait: "true（缺省）=等待完成并返回聚合摘要；false=后台启动立即返回（兜底窗口 ocrBackgroundMaxMs 默认 2 小时），用 ocr_session 轮询结果。两种模式都带宿主回收守护：dsh 退出（含 kill -9）时 OCR 进程一并结束",
 		paramProvider: "本次运行临时指定已配置 provider",
 		paramModel: "本次运行临时覆盖 model",
 		paramResume: "从之前中断的会话 id 恢复（会话 id 在返回结果里）",
@@ -157,9 +158,9 @@ 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. Background runs get reclaimed by a 2-hour backstop (a wedged one would otherwise keep occupying the official job bucket); cancelling this tool call terminates the background OCR (host kill + the reaper guard inside the command).",
+		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. Background runs get no host timeout; they are reclaimed when the backstop window (ocrBackgroundMaxMs, 2 hours by default) elapses (a wedged one would otherwise keep occupying the official job bucket); cancelling this tool call terminates the background OCR (host kill + the reaper guard inside the command).",
 		jobReasonAborted: "ocr-review tool call aborted",
-		jobReasonTimeout: "ocr-review background review exceeded 2 hours and was reclaimed",
+		jobReasonTimeout: "the ocr-review background review exceeded its backstop window ({minutes} minutes) and was reclaimed",
 		jobReasonUnload: "ocr-review plugin unloaded",
 		jobOutputGap: "\n[ocr-review] note: one output read failed and was retried from the same offset (this stretch may be incomplete)",
 		requiredNotArray: "parameters.required must be an array of strings",
@@ -213,6 +214,7 @@ const MESSAGES = {
 		configPathLayoutInvalid: "the ocrConfigPath setting must follow the <X>/.opencodereview/config.json layout: {path}. OCR has no file-level path override (it only looks at <HOME>/.opencodereview/config.json); this plugin makes it effective by injecting HOME=<X> into the ocr subprocess. A file path of any other shape would never be read by OCR",
 		noApiKeyEnv: "provider {provider} declares no apiKeyEnv, so the key cannot be read dynamically (OCR custom providers do not support keyless resolution)",
 		keyNotResolvable: "the API key of provider {provider} is not configured: the dsh credentials service resolved no {ref}",
+		keyNotReachable: "the API key of provider {provider} lives in the credential source \"{source}\", which OCR cannot reach at runtime: dsh strips variables named KEY/PASSWORD/SECRET/TOKEN or prefixed DSH_ from spawned shells, and get-cred deliberately does not read the reviewed repository's .env. Store the key in the dsh managed credentials ($DSH_HOME/.credentials.yaml refs.{ref}) or $DSH_HOME/.env and retry",
 		credScriptMissing: "get-cred script missing: {path} (api_key_cmd cannot work)",
 		reaperDegraded: "[ocr-review] host reaper degraded: ps/pgrep are unavailable (process-info commands denied by the sandbox), so the host manages the process tree. dsh may leave an orphaned ocr process.",
 		warningUnreadable: "(one unreadable warning entry: neither a string nor an object with file/error)",
@@ -238,7 +240,7 @@ const MESSAGES = {
 		paramBackgroundPreview: "Business context (it shows up in the output for review reference)",
 		paramExclude: "gitignore-style exclusion patterns (multiple allowed)",
 		paramExcludeShort: "Exclusion patterns",
-		paramWait: "true (default) = wait for completion and return the aggregated summary; false = start in the background and return immediately (a 2-hour backstop reclaims it), poll with ocr_session. Both modes carry the host reaper guard: when dsh exits (including kill -9) the OCR process is terminated too",
+		paramWait: "true (default) = wait for completion and return the aggregated summary; false = start in the background and return immediately (reclaimed when the backstop window ocrBackgroundMaxMs, 2 hours by default, elapses), poll with ocr_session. Both modes carry the host reaper guard: when dsh exits (including kill -9) the OCR process is terminated too",
 		paramProvider: "Temporarily use a configured provider for this run",
 		paramModel: "Temporarily override the model for this run",
 		paramResume: "Resume from a previously interrupted session id (the id is in the result)",
@@ -341,14 +343,15 @@ function scalarMismatch(type, value) {
 function objectViolations(schema, value, path, walk) {
 	if (!isRecord(value)) return [`${path}: expected object`];
 	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) => properties?.[key] === void 0);
+		const extra = Object.keys(value).filter((key) => declared(key) === void 0);
 		if (extra.length > 0) return [`${path}: fields outside the schema: ${extra.join(", ")}`];
 	}
-	for (const key of required ?? []) if (!(key in value) || value[key] === void 0) return [`${path}: missing required field ${key}`];
+	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 = properties?.[key];
+		const child = declared(key);
 		if (child !== void 0) violations.push(...walk(child, value[key], `${path}.${key}`));
 	}
 	return violations;
@@ -360,42 +363,6 @@ function arrayViolations(schema, value, path, walk) {
 	if (items === void 0) return [];
 	return value.flatMap((item, index) => walk(items, item, `${path}[${index}]`));
 }
-/** 官方子集的迷你走查（path 限定违规位置，一次列全）。oneOf 语义与官方一致：
-*  恰好一支命中，多支/零支都算违规。 */
-function violationsOf(schema, value, path) {
-	if (schema.oneOf !== void 0) {
-		const passing = schema.oneOf.filter((branch) => violationsOf(branch, value, path).length === 0);
-		if (passing.length !== 1) return [`${path}: matched ${passing.length} of ${schema.oneOf.length} oneOf branches`];
-		return [];
-	}
-	const { type } = schema;
-	if (type === "object") return objectViolations(schema, value, path, violationsOf);
-	if (type === "array") return arrayViolations(schema, value, path, violationsOf);
-	if (type === void 0) return [];
-	if (scalarMismatch(type, value)) return [`${path}: expected ${type}`];
-	if (schema.const !== void 0 && value !== schema.const) return [`${path}: must be exactly ${JSON.stringify(schema.const)}`];
-	if (schema.enum !== void 0 && !schema.enum.includes(value)) return [`${path}: must be one of ${schema.enum.map((entry) => JSON.stringify(entry)).join("/")}`];
-	return [];
-}
-/**
-* 校验并放行工具返回值：必须命中该工具自己的 output schema。
-* 违规抛错而非静默裁剪——静默修正是第二个 bug 的开始，抛错让回归在开发期
-* （vitest/首次调用）就炸出来。
-* @param schema 该工具注册时声明的 output.schema（与宿主校验用的是同一个对象）
-* @param value execute 交回的 canonical 值（结构化对象 / 数组 / 标量 / null）
-* @param toolName 工具名（违规信息要点名，模型才知道该重试哪一次调用）
-* @param messages 双语文案
-* @returns 原值（校验只读不改，值原样交给宿主）
-*/
-function assertToolOutput(schema, value, toolName, messages) {
-	assertGuardable(schema, toolName, messages);
-	const violations = violationsOf(schema, value, "result");
-	if (violations.length > 0) throw new Error(format(messages.resultSchemaViolation, {
-		tool: toolName,
-		violations: violations.join("; ")
-	}));
-	return value;
-}
 /** provider key 形状：`sk-…`/`ark-…`/`ghp-…` 一类「短前缀 + 长随机串」。
 *
 *  为什么额外要求随机串里至少有一个数字或大写字母：真实 key 是随机 base62（32 位
@@ -403,14 +370,19 @@ function assertToolOutput(schema, value, toolName, messages) {
 *  （`src/my-super-long-directory-name/index.ts`）。少了这道约束，session/delegate
 *  透传出的路径会被抹成 ***REDACTED***，模型拿不到可行动的位置信息。 */
 const STANDALONE_KEY = /\b[A-Za-z]{2,5}-(?=[A-Za-z0-9_-]{20,}\b)(?=[A-Za-z0-9_-]*[0-9A-Z])[A-Za-z0-9_-]{20,}\b/gu;
-/** `Authorization: Bearer xxx` / `bearer xxx`。
-*
-*  字符集写 `[a-z…]` 而不是 `[A-Za-z…]`：本条带 `i` 旗标，`a-z` 在大小写不敏感下
-*  已同时匹配 `A-Z`——再并列一枚 `A-Z` 是同一个字符集抄两遍（sonarjs 判为字符类内重复），
-*  删掉重复的那一位，匹配语言不变。 */
-const BEARER_VALUE = /(?<scheme>\bbearer\s+)[a-z0-9._~+/=-]{12,}/giu;
-/** `api_key: "xxx"`、`apiKey=xxx`、`token: xxx`、`x-api-key: xxx` 等赋值形态。 */
-const KEY_ASSIGNMENT = /(?<name>\b(?:api[_-]?key|apikey|access[_-]?key|secret[_-]?key|client[_-]?secret|password|token)["'\s]*[:=]["'\s]*)[^\s"',;)}\]]{6,}/giu;
+/** `Authorization: <scheme> <value>` / `Proxy-Authorization: …`：认**头名**而不是
+*  枚举认证方案。头名本身就是「后面跟着凭据」的信号，Basic / Token / Digest 乃至
+*  vendor 自定义 scheme 都不会漏；而只认头名还避开了正文里「token based
+*  authentication」这类措辞被误抹。scheme 组连同其后的空白一起捕获，回填时凭据被
+*  替换而 scheme 词保留。 */
+const AUTH_HEADER_VALUE = /(?<name>\b(?:proxy-)?authorization["'\s]*[:=]["'\s]*)(?:(?<scheme>[a-z][a-z0-9_-]*[ \t]+))?[^\s"',;)}\]]{4,}/giu;
+/** 裸 scheme + 值（没有头名时 OCR 也会整行回显）。scheme 只留 bearer：它在散文中几乎
+*  不出现，而 token / basic 之类会撞上「token count」「basic usage」等普通措辞。 */
+const BEARER_VALUE = /(?<scheme>\bbearer[ \t]+)[a-z0-9._~+/=-]{4,}/giu;
+/** `api_key: "xxx"`、`apiKey=xxx`、`token: xxx`、`x-api-key: xxx` 等赋值形态。
+*  值下限取 4 且容许一个 scheme 词：`token: Basic <base64>` 里赋值形态先能吃到的只是
+*  scheme 词（Basic 恰好 5 字符），下限更高时整条失配，后面那个 base64 就原样进了日志。 */
+const KEY_ASSIGNMENT = /(?<name>\b(?:api[_-]?key|apikey|access[_-]?key|secret[_-]?key|client[_-]?secret|password|token)["'\s]*[:=]["'\s]*)(?:(?<scheme>[a-z][a-z0-9_-]*[ \t]+))?[^\s"',;)}\]]{4,}/giu;
 const REDACTION = "***REDACTED***";
 /**
 * 抹掉文本里 key 形状的片段。
@@ -425,7 +397,49 @@ const REDACTION = "***REDACTED***";
 * 要求随机串特征，避免把要交给模型的文件路径一起抹掉。
 */
 function redactKeyMaterial(text) {
-	return text.replaceAll(BEARER_VALUE, `$<scheme>${REDACTION}`).replaceAll(KEY_ASSIGNMENT, `$<name>${REDACTION}`).replaceAll(STANDALONE_KEY, REDACTION);
+	return text.replaceAll(AUTH_HEADER_VALUE, `$<name>$<scheme>${REDACTION}`).replaceAll(BEARER_VALUE, `$<scheme>${REDACTION}`).replaceAll(KEY_ASSIGNMENT, `$<name>$<scheme>${REDACTION}`).replaceAll(STANDALONE_KEY, REDACTION);
+}
+/** 官方子集的迷你走查（path 限定违规位置，一次列全）。oneOf 语义与官方一致：
+*  恰好一支命中，多支/零支都算违规。 */
+function violationsOf(schema, value, path) {
+	const violations = [];
+	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`);
+	}
+	const { type } = schema;
+	if (type === "object") violations.push(...objectViolations(schema, value, path, violationsOf));
+	else if (type === "array") violations.push(...arrayViolations(schema, value, path, violationsOf));
+	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;
+}
+/**
+* 校验并放行工具返回值：必须命中该工具自己的 output schema。
+* 违规抛错而非静默裁剪——静默修正是第二个 bug 的开始，抛错让回归在开发期
+* （vitest/首次调用）就炸出来。
+* @param schema 该工具注册时声明的 output.schema（与宿主校验用的是同一个对象）
+* @param value execute 交回的 canonical 值（结构化对象 / 数组 / 标量 / null）
+* @param toolName 工具名（违规信息要点名，模型才知道该重试哪一次调用）
+* @param messages 双语文案
+* @returns 原值（校验只读不改，值原样交给宿主）
+*/
+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})` : "");
+		throw new Error(format(messages.resultSchemaViolation, {
+			tool: toolName,
+			violations: redactKeyMaterial(listed).slice(0, MAX_CHARS)
+		}));
+	}
+	return value;
 }
 //#endregion
 //#region lib/argv-guard.ts
@@ -563,19 +577,23 @@ function idValue(value, name, messages) {
 * 负数/非整数由 OCR 侧报错，但桥接层先做同源校验给出更早的错误）。
 * value 为 undefined/null 时省略 flag（跟随 OCR flag 默认值）。
 *
-* 注入面：数值经 `String(num)` 落进命令串（不走 shq）。Number.isInteger 对
-* 1e21 为 true 而 String() 会写成 `1e+21`，故再加一道「只含数字」的形态校验：
-* 命令串里的数值 token 结构上不可能带 shell 元字符。
+* 注入面：数值经 `String(num)` 落进命令串（不走 shq）。数值 token 结构上不可能带
+* shell 元字符，「只含数字」的形态校验顺带把 1e21 写成 `1e+21` 这类形态也挡住。
 */
 function pushIntFlag(parts, flag, value, min, messages) {
 	if (value === void 0 || value === null) return;
-	const num = typeof value === "number" ? value : Number(value);
+	const reject = () => {
+		throw new Error(format(messages.intFlagMustBeInt, {
+			flag,
+			min: String(min),
+			received: describeValue(value)
+		}));
+	};
+	const decimalString = typeof value === "string" && /^\d+$/u.test(value.trim());
+	if (typeof value !== "number" && !decimalString) reject();
+	const num = Number(value);
 	const text = String(num);
-	if (!Number.isInteger(num) || num < min || !/^\d+$/u.test(text)) throw new Error(format(messages.intFlagMustBeInt, {
-		flag,
-		min: String(min),
-		received: describeValue(value)
-	}));
+	if (!Number.isSafeInteger(num) || num < min || !/^\d+$/u.test(text)) reject();
 	parts.push(flag, text);
 }
 /** 模式参数解析：workspace（默认）/commit/branch 互斥，非法组合与错类型抛错。
@@ -698,8 +716,11 @@ const memoBox = {};
 */
 function ocrCommand(locate = locateLauncher, memo = memoBox) {
 	if (memo.value === void 0) {
-		const launcher = locate();
-		memo.value = launcher === null ? "ocr" : shq(launcher);
+		if (process.platform === "win32") memo.value = "ocr";
+		else {
+			const launcher = locate();
+			memo.value = launcher === null ? "ocr" : shq(launcher);
+		}
 	}
 	return memo.value;
 }
@@ -983,14 +1004,15 @@ function str(value) {
 * 故作兜底值。
 */
 function nonNegativeInt(value) {
-	if (!Number.isFinite(value) || value < 0) return 0;
-	return Math.trunc(value);
+	const truncated = Math.trunc(value);
+	if (!Number.isSafeInteger(truncated) || truncated < 0) return 0;
+	return truncated;
 }
 function num(value) {
 	if (typeof value === "number") return nonNegativeInt(value);
 	if (typeof value === "string") {
 		const trimmed = value.trim();
-		if (trimmed === "") return 0;
+		if (!/^\d+$/u.test(trimmed)) return 0;
 		return nonNegativeInt(Number(trimmed));
 	}
 	return 0;
@@ -1153,6 +1175,42 @@ function delegatePreviewFailure() {
 		mergeBase: ""
 	};
 }
+/**
+* preview 的条目数组 → 结构化清单；返回 null 表示「上游给了条目却一条都没解析出来」。
+*
+* 判据分两层：部分条目解析不出来照旧丢弃（OCR 偶发脏条目不该毁掉整份清单），
+* 但一条不剩时不能继续以 ok:true 的形态报「0 个文件可审」——那不是「没有可审的
+* 文件」，是半截产出，模型与用户都会拿它当范围结论。
+*/
+function toDelegateFiles(raw) {
+	if (!Array.isArray(raw)) return [];
+	const files = raw.map((entry) => {
+		if (!isRecord(entry)) return null;
+		const entryPath = str(entry["path"]);
+		if (entryPath === "") return null;
+		return {
+			path: entryPath,
+			status: str(entry["status"]),
+			insertions: num(entry["insertions"]),
+			deletions: num(entry["deletions"])
+		};
+	}).filter((fileEntry) => fileEntry !== null);
+	return raw.length > 0 && files.length === 0 ? null : files;
+}
+/** excluded_files 同款门：条目形状与 reviewable 一致，缺 path 即不可用。 */
+function toExcludedFiles(raw) {
+	if (!Array.isArray(raw)) return [];
+	const files = raw.map((entry) => {
+		if (!isRecord(entry)) return null;
+		const entryPath = str(entry["path"]);
+		if (entryPath === "") return null;
+		return {
+			path: entryPath,
+			reason: str(entry["reason"])
+		};
+	}).filter((fileEntry) => fileEntry !== null);
+	return raw.length > 0 && files.length === 0 ? null : files;
+}
 /** 解析 `ocr delegate preview --format json` 输出。 */
 function parseDelegatePreview(text) {
 	let doc;
@@ -1168,22 +1226,9 @@ function parseDelegatePreview(text) {
 		const value = root[key];
 		if (value !== void 0 && !Array.isArray(value)) return delegatePreviewFailure();
 	}
-	const reviewable = Array.isArray(root["reviewable_files"]) ? root["reviewable_files"].map((fileRaw) => {
-		if (!isRecord(fileRaw)) return null;
-		return {
-			path: str(fileRaw["path"]),
-			status: str(fileRaw["status"]),
-			insertions: num(fileRaw["insertions"]),
-			deletions: num(fileRaw["deletions"])
-		};
-	}).filter((fileEntry) => fileEntry !== null && fileEntry.path.length > 0) : [];
-	const excluded = Array.isArray(root["excluded_files"]) ? root["excluded_files"].map((fileRaw) => {
-		if (!isRecord(fileRaw)) return null;
-		return {
-			path: str(fileRaw["path"]),
-			reason: str(fileRaw["reason"])
-		};
-	}).filter((fileEntry) => fileEntry !== null && fileEntry.path.length > 0) : [];
+	const reviewable = toDelegateFiles(root["reviewable_files"]);
+	const excluded = toExcludedFiles(root["excluded_files"]);
+	if (reviewable === null || excluded === null) return delegatePreviewFailure();
 	return {
 		ok: true,
 		mode: str(root["mode"]),
@@ -1223,15 +1268,20 @@ function parseDelegateRules(text) {
 		ok: false,
 		groups: []
 	};
+	const groups = groupsRaw.filter((groupRaw) => isRecord(groupRaw) && Array.isArray(groupRaw["files"])).map((groupRaw) => ({
+		groupId: num(groupRaw["group_id"]),
+		source: str(groupRaw["source"]),
+		pattern: str(groupRaw["pattern"]),
+		files: groupRaw.files.filter((file) => typeof file === "string" && file.trim() !== "").map((file) => file.trim()),
+		rule: str(groupRaw["rule"])
+	})).filter((group) => group.files.length > 0);
+	if (groupsRaw.length > 0 && groups.length === 0) return {
+		ok: false,
+		groups: []
+	};
 	return {
 		ok: true,
-		groups: groupsRaw.filter((groupRaw) => isRecord(groupRaw) && Array.isArray(groupRaw["files"])).map((groupRaw) => ({
-			groupId: num(groupRaw["group_id"]),
-			source: str(groupRaw["source"]),
-			pattern: str(groupRaw["pattern"]),
-			files: groupRaw.files.map((file) => str(file)).filter(Boolean),
-			rule: str(groupRaw["rule"])
-		})).filter((group) => group.files.length > 0)
+		groups
 	};
 }
 //#endregion
@@ -1464,8 +1514,17 @@ function readText(configPath) {
 		return "";
 	}
 }
-/** 单引号转义（api_key_cmd 内嵌命令用，模块级纯函数）。 */
+/**
+* api_key_cmd 内嵌值的转义。POSIX 走单引号（ocr 在 Unix 用 `sh -c` 跑 api_key_cmd，
+* keycmd_unix.go）；Windows 的 ocr 用 **cmd.exe** 跑它（keycmd_windows.go），单引号
+* 在那里是普通字符、命令必坏，故走双引号：值内 `"` 翻倍、收尾反斜杠再翻倍（防被
+* CommandLineToArgvW 当成转义吃掉收尾引号）。ref 名白名单 `^[A-Z0-9_]+$` 不含两种
+* 引号；脚本与数据目录是盘上常规路径。已知残留：cmd.exe 会对双引号内的 `%VAR%`
+* 做环境展开，路径含 `%` 的 Windows 部署需自行规避（Windows 非目标平台，此处只
+* 保证常规路径形态正确）。
+*/
 function shqDyn(value) {
+	if (process.platform === "win32") return `"${value.replaceAll("\"", "\"\"").replace(/\\+$/u, (backslashes) => backslashes + backslashes)}"`;
 	return `'${value.replaceAll("'", String.raw`'\''`)}'`;
 }
 /** api_key_cmd 值构造：脚本路径与 env key 名（及可选的 dsh 数据目录）shq 转义后
@@ -1534,19 +1593,73 @@ function readShqTokens(body) {
 	return malformed ? null : tokens;
 }
 /**
-* api_key_cmd → 三个槽位；只认本包写出的那一种形态。
+* 读一个 cmd.exe 双引号串：解出它的值与结束位置（`""` 是翻倍的引号）。
+* 未闭合返回 null：宁可判「读不懂」，也不把半截命令当可信输入。
+*/
+function readDqToken(body, start) {
+	let value = "";
+	let i = start + 1;
+	let closed = false;
+	while (i < body.length && !closed) {
+		const ch = body[i];
+		if (ch === "\"" && body[i + 1] === "\"") {
+			value += "\"";
+			i += 2;
+		} else if (ch === "\"") {
+			closed = true;
+			i += 1;
+		} else {
+			value += ch;
+			i += 1;
+		}
+	}
+	if (!closed) return null;
+	return {
+		value: value.replace(/(?:\\\\)+$/u, (backslashes) => "\\".repeat(backslashes.length / 2)),
+		next: i
+	};
+}
+/**
+* cmd.exe 双引号形态的 token 列表（buildApiKeyCmd 的 win32 臂写出的那种：
+* `node "a" "b" "c"`）；形态不符（裸词 / 未闭合）返回 null。
+*
+* 只在 readShqTokens 判 null 之后被调用，而那条路必有非空白内容 ⇒ 循环至少走一轮，
+* 解析成功的列表至少一枚 token；末尾的 `return tokens` 对实际可达的输入不可能交出
+* 空列表（parseApiKeyCmd 的 `script === ""` 闸对它另有兜底）。
+*/
+function readDqTokens(body) {
+	const tokens = [];
+	let i = 0;
+	while (i < body.length) {
+		while (i < body.length && (body[i] === " " || body[i] === "	")) i += 1;
+		if (i >= body.length) break;
+		if (body[i] !== "\"") return null;
+		const token = readDqToken(body, i);
+		if (token === null) return null;
+		tokens.push(token.value);
+		i = token.next;
+	}
+	return tokens;
+}
+/**
+* api_key_cmd → 三个槽位；认本包写出的**两种**形态（POSIX 单引号与 Windows 双引号）。
 *
 * 为什么需要反解：写进 config.json 的脚本路径是**写那一刻**的插件安装目录（绝对
 * 路径），而插件会被重装、换 profile、换发布形态——目录一变，ocr 执行 api_key_cmd
 * 就是 MODULE_NOT_FOUND，而它把这件事报成「resolve LLM endpoint 失败」，错误完全
 * 指不到「本包被挪了地方」这个真因。没有反解就无从判断一条 api_key_cmd 是否还活着。
 *
-* 为什么只认一种形态：认不出来的一律给 undefined，由调用方原样保留。改写一条读不
-* 懂的命令串，可能把用户手写的凭据取用方式弄坏，而那正是本包明令不该插手的部分。
+* 为什么两种形态都认：config.json 可能跨机迁移（HOME 同步、换部署），反解不能假设
+* 「写它的平台 = 读它的平台」。POSIX 形态优先判（单引号）；POSIX 判不出且整体是
+* 双引号形态时再走 cmd.exe 那一档。
+*
+* 为什么认不出来一律给 undefined：由调用方原样保留。改写一条读不懂的命令串，可能
+* 把用户手写的凭据取用方式弄坏，而那正是本包明令不该插手的部分。
 */
 function parseApiKeyCmd(command) {
 	const body = command.replace(/^node[ \t]+/u, "");
-	const tokens = body === command ? null : readShqTokens(body);
+	if (body === command) return null;
+	const tokens = readShqTokens(body) ?? readDqTokens(body);
 	if (tokens === null) return null;
 	const script = tokens[0] ?? "";
 	const envKey = tokens[1] ?? "";
@@ -1729,6 +1842,32 @@ function repointDanglingKeyScripts(doc, current, messages) {
 /** 外部 ocr CLI 的默认配置目录/文件名（宿主服务管不到，只能由本包直读直写）。 */
 const OCR_CONFIG_DIR = ".opencodereview";
 const OCR_CONFIG_FILE = "config.json";
+/**
+* 宿主起 shell 子进程时的**环境净化**模式（dsh-subprocess 的 SENSITIVE_ENV_PATTERN
+* `KEY|PASSWORD|SECRET|TOKEN` 大小写不敏感命中即剥，另加 `DSH_` 前缀全剥）。
+* 本包不传 `env`，OCR 子进程拿到的环境就是净化后的那一份——名字命中本模式的
+* 凭据 ref，OCR 及其孙进程（get-cred）在「继承环境」这一层永远读到空。
+*/
+const HOST_SCRUBBED_ENV_PATTERN = /KEY|PASSWORD|SECRET|TOKEN|^DSH_/iu;
+/**
+* key 在 **OCR 运行时**是否真的取得到（get-cred 三层里有没有一层够得到它）。
+*
+* 宿主侧 resolve() 的 source 是「dsh 进程自己的取值层」，不等于「OCR 子进程够得到的
+* 层」——少了这道判定就是「select 成功 → OCR 401」的假绿：
+*   - `file`（$DSH_HOME/.credentials.yaml）→ get-cred 第 2 层，可达；
+*   - `user-env`（$DSH_HOME/.env）→ get-cred 第 3 层，可达；
+*   - `env`（dsh 进程继承的环境）→ 只有 ref 名**不**命中宿主净化模式时才可达
+*     （API key 类 ref 几乎全含 KEY/TOKEN，实际常不可达）；
+*   - `project-env`（dsh 工作区 .env）→ get-cred 刻意不读被审查仓库的 .env，永不可达；
+*   - 未知层 / `undefined`（未配置）→ 一律按不可达，由调用方分别报「未配置」。
+* @param source credentials.resolve() 交出的层 id（gateway.credentialSource）。
+* @param ref 凭据 ref 名（get-cred/buildApiKeyCmd 用的那个大写名）。
+*/
+function keyReachableAtOcrRuntime(source, ref) {
+	if (source === "file" || source === "user-env") return true;
+	if (source === "env") return !HOST_SCRUBBED_ENV_PATTERN.test(ref);
+	return false;
+}
 /** 无凭据可问时的一律 false（卡片据 source 显示原因，不显示假的「未配置 key」）。 */
 function withoutKeyFlags(providers) {
 	return providers.map((providerCfg) => ({
@@ -1795,6 +1934,7 @@ async function providersForCard(gateway, paths, messages) {
 */
 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, {}));
 	const { providers, source } = readProviders(gateway, messages);
 	if (source.status !== "ready") throw new Error(source.message);
 	const target = providers.find((providerCfg) => providerCfg.name === provider);
@@ -1803,10 +1943,16 @@ async function applyProviderSelection(gateway, paths, selection, messages) {
 		provider
 	}));
 	if (target.apiKeyEnv === null || target.apiKeyEnv === "") throw new Error(format(messages.noApiKeyEnv, { provider }));
-	if (!await gateway.credentialResolvable(target.apiKeyEnv)) throw new Error(format(messages.keyNotResolvable, {
+	const keySource = await gateway.credentialSource(target.apiKeyEnv);
+	if (keySource === void 0) throw new Error(format(messages.keyNotResolvable, {
 		provider,
 		ref: target.apiKeyEnv
 	}));
+	if (!keyReachableAtOcrRuntime(keySource, target.apiKeyEnv)) throw new Error(format(messages.keyNotReachable, {
+		provider,
+		ref: target.apiKeyEnv,
+		source: keySource
+	}));
 	const scriptPath = credentialScriptPath(paths);
 	if (!existsSync(scriptPath)) throw new Error(format(messages.credScriptMissing, { path: scriptPath }));
 	const apiKeyCmd = buildApiKeyCmd(scriptPath, target.apiKeyEnv, resolveDshHome(), messages);
@@ -1834,11 +1980,11 @@ async function applyProviderSelection(gateway, paths, selection, messages) {
 * api_key_cmd 并删除明文，返回 'migrated'；找不到 envKey 或构造命令失败 →
 * 'unknown'；无明文 → 'noPlain'（不动作）。
 */
-function migrateEntry(entry, envKey, scriptPath, dshHome, messages) {
+function migrateEntry(entry, envKey, context) {
 	if (typeof entry["api_key"] !== "string" || entry["api_key"].length === 0) return "noPlain";
-	if (envKey === void 0 || envKey === "") return "unknown";
+	if (envKey === void 0 || envKey === "" || !context.reachableEnvKeys.has(envKey)) return "unknown";
 	try {
-		entry["api_key_cmd"] = buildApiKeyCmd(scriptPath, envKey, dshHome, messages);
+		entry["api_key_cmd"] = buildApiKeyCmd(context.scriptPath, envKey, context.dshHome, context.messages);
 	} catch {
 		return "unknown";
 	}
@@ -1865,13 +2011,23 @@ async function migratePlaintextKeys(gateway, paths, messages) {
 	if (source.status !== "ready" && source.status !== "credentials-unavailable") throw new Error(source.message);
 	parseExistingConfig(precheck, paths.ocrConfigJson, messages);
 	const scriptPath = credentialScriptPath(paths);
-	if (!existsSync(scriptPath)) return {
-		migrated: [],
-		skippedUnknown: []
-	};
+	if (!existsSync(scriptPath)) throw new Error(format(messages.credScriptMissing, { path: scriptPath }));
 	const dshHome = resolveDshHome();
 	const envByProvider = /* @__PURE__ */ new Map();
 	for (const providerCfg of providers) if (providerCfg.apiKeyEnv !== null && providerCfg.apiKeyEnv !== "") envByProvider.set(providerCfg.name, providerCfg.apiKeyEnv);
+	const candidateEnvKeys = [...new Set(envByProvider.values())];
+	const keySources = await Promise.all(candidateEnvKeys.map((envKey) => gateway.credentialSource(envKey)));
+	const reachableEnvKeys = /* @__PURE__ */ new Set();
+	for (const [index, envKey] of candidateEnvKeys.entries()) {
+		const keySource = keySources[index];
+		if (keySource !== void 0 && keyReachableAtOcrRuntime(keySource, envKey)) reachableEnvKeys.add(envKey);
+	}
+	const migrateContext = {
+		scriptPath,
+		dshHome,
+		reachableEnvKeys,
+		messages
+	};
 	return await updateConfigLocked(paths.ocrConfigJson, async () => {
 		const doc = parseExistingConfig(readText(paths.ocrConfigJson), paths.ocrConfigJson, messages);
 		const customsRaw = fieldOf(doc, "custom_providers");
@@ -1883,7 +2039,7 @@ async function migratePlaintextKeys(gateway, paths, messages) {
 		const migrated = [];
 		const skippedUnknown = [];
 		for (const [name, raw] of Object.entries(customs)) if (isRecord(raw)) {
-			const result = migrateEntry(raw, envByProvider.get(name), scriptPath, dshHome, messages);
+			const result = migrateEntry(raw, envByProvider.get(name), migrateContext);
 			if (result === "migrated") migrated.push(name);
 			else if (result === "unknown") skippedUnknown.push(name);
 		}
@@ -2384,7 +2540,7 @@ const SESSION_OUTPUT_SCHEMA = {
 * owner 口径是「状态归 ocr 自己，围栏由本包显式放开」，故直接要 `danger-full-access`。
 *
 * **「能不能只放开需要写的那一条路径」：不能。** 官方按调用携带的 `SandboxPolicyRequest`
-* 只有 `session` 与 `mode` 两个字段（dsh-sandbox-policy 0.2.1-alpha.1 的
+* 只有 `session` 与 `mode` 两个字段（dsh-sandbox-policy 0.2.1-alpha.2 的
 * lib/types/index.d.ts:50），**没有**附加可写路径、没有自定义 HOME、没有目录级豁免。
 * 可选的收紧路径只有「改 ocr 自己的状态落点」或「等上游加字段」，两者都不是本包能在
 * 一次补丁里做完的事。故此处维持放开，但把边界写明：放开的是 ocr 这一个子进程的整棵
@@ -2410,7 +2566,16 @@ function failureDetail(result, messages) {
 	const detail = redactKeyMaterial(result.stderr.text === "" ? result.stdout.text : result.stderr.text);
 	return detail.length <= 800 ? detail : `${truncateEnd(detail, 400)}${messages.middleEllipsis}${truncateStart(detail, 400)}`;
 }
-/** 前台执行：失败抛错（含给模型的行动提示），成功返回 stdout 文本。
+/** 截断说明（stdoutTruncated 文案 + 可选的落盘位置），判据见 ForegroundRun 的注释。 */
+function stdoutTruncationNote(limitBytes, run, messages) {
+	if (!run.truncated) return "";
+	const spill = run.spillPath === void 0 ? "" : format(messages.outputSpill, { path: run.spillPath });
+	return `\n${format(messages.stdoutTruncated, {
+		limit: String(limitBytes),
+		spill
+	})}`;
+}
+/** 前台执行：失败抛错（含给模型的行动提示），成功返回 stdout 的一手结果。
 * timeoutMs 恒有值（tuningOf(config)），宿主按 min(请求, shell.maxTimeoutMs) 收口。
 * signal 必传：harness ToolExecution.signal 是必填的调用方取消权。 */
 async function runForeground(host, command, workdir, run, signal) {
@@ -2436,14 +2601,11 @@ async function runForeground(host, command, workdir, run, signal) {
 		throw new Error(detail === "" ? head : `${head}${messages.detailSeparator}${detail}`);
 	}
 	const { text, truncated, spillPath } = result.stdout;
-	if (truncated) {
-		const spill = typeof spillPath === "string" ? format(messages.outputSpill, { path: spillPath }) : "";
-		return `${text}\n${format(messages.stdoutTruncated, {
-			limit: String(run.stdoutMaxBytes),
-			spill
-		})}`;
-	}
-	return text;
+	return {
+		text,
+		truncated,
+		spillPath
+	};
 }
 /**
 * 终止 OCR 进程，忽略"已经没有必要杀"的那一类异常（进程自然退出、已被注册表或宿主回收）。
@@ -2568,7 +2730,8 @@ async function startBackground(host, job, signal) {
 		killProc(proc);
 		throw error;
 	}
-	enforceOcrDeadline(registry, jobId, messages.jobReasonTimeout, job.backgroundMaxMs);
+	const backstopMinutes = Math.round(job.backgroundMaxMs / 6e4);
+	enforceOcrDeadline(registry, jobId, format(messages.jobReasonTimeout, { minutes: String(backstopMinutes) }), job.backgroundMaxMs);
 	const stop = () => {
 		try {
 			registry.kill(jobId, void 0, messages.jobReasonAborted);
@@ -2888,15 +3051,15 @@ function createGateway(host) {
 				return false;
 			}
 		},
-		credentialResolvable: async (envKey) => {
+		credentialSource: async (envKey) => {
 			const svc = credentialsService();
-			if (svc === void 0 || !isCredentialRefName(envKey)) return false;
-			try {
-				const resolved = await svc.resolve(credentialRef(envKey));
-				return resolved !== void 0 && resolved.value.length > 0;
+			let resolved;
+			if (svc !== void 0 && isCredentialRefName(envKey)) try {
+				resolved = await svc.resolve(credentialRef(envKey));
 			} catch {
-				return false;
+				resolved = void 0;
 			}
+			return resolved !== void 0 && resolved.value.length > 0 ? resolved.source : void 0;
 		}
 	};
 }
@@ -2946,6 +3109,21 @@ async function canonicalReviewRoot(host, root) {
 	} catch {}
 	return realpathOrSelf(root);
 }
+/**
+* 判定 webserver 绑定地址字面量是否回环（127/8、::1 及其全展开/IPv4 映射形态；
+* `%zone` 后缀剥掉再比，对齐宿主 isLoopbackHost 的判定域）。
+*
+* 为什么不是 `host === "0.0.0.0"`：宿主 webserver 的 Config 在装载期就**拒绝通配
+* 地址**（0.2.1-alpha.2 packages/host/webserver/src/index.ts:263-267 —— 0.0.0.0/::
+* 一律 throw，要求绑定本机某个具体接口的 IP 字面量），所以那个等式是永假死分支，
+* 唯一需要 trust 闸放行局域网 Host 头的场景（绑定 LAN IP，容器/远端部署的正路）
+* 反而被当成回环、整批 403。host 经 config 校验必为具体 IP 字面量，故本函数
+* 不必处理主机名与通配，只枚举回环字面量的常见书写。
+*/
+function isLoopbackBindAddress(host) {
+	const value = host.toLowerCase().replace(/%.*$/u, "");
+	return value === "::1" || value === "0:0:0:0:0:0:0:1" || value.startsWith("127.") || /^::ffff:127(?:\.\d{1,3}){3}$/u.test(value);
+}
 /** POST select 的响应：把 body 里的 provider/model 应用到 OCR 配置，按需附带 llm test 回执。 */
 async function sendSelectResponse(text, res, deps) {
 	const msgs = deps.messages();
@@ -2996,7 +3174,7 @@ async function sendSelectResponse(text, res, deps) {
 function registerConfigEndpoints(ctx, host, config, csrf) {
 	const webServer = host.get("webServer");
 	if (!webServer) return;
-	const servingNonLoopback = webServer.host === "0.0.0.0";
+	const servingNonLoopback = !isLoopbackBindAddress(webServer.host);
 	const gateway = createGateway(host);
 	const messages = () => localeMessages(host);
 	const disposeProviders = webServer.register({
@@ -3343,13 +3521,13 @@ function registerDelegatePreviewTool(host, config) {
 				...args,
 				repo
 			}, runMsgs);
-			const text = await runForeground(host, withHomeEnv(command, homeOverride), workdir, tuningOf(config), exec.signal);
-			const parsed = parseDelegatePreview(text);
+			const stdout = await runForeground(host, withHomeEnv(command, homeOverride), workdir, tuningOf(config), exec.signal);
+			const parsed = parseDelegatePreview(stdout.text);
 			if (!parsed.ok) return format(runMsgs.parseFailedPlain, {
 				tool: "ocr delegate preview",
 				limit: String(RAW_ECHO_LIMIT),
-				raw: echoRaw(text, RAW_ECHO_LIMIT)
-			});
+				raw: echoRaw(stdout.text, RAW_ECHO_LIMIT)
+			}) + stdoutTruncationNote(config.stdoutMaxBytes, stdout, runMsgs);
 			return {
 				mode: parsed.mode,
 				repository: parsed.repository,
@@ -3392,13 +3570,13 @@ function registerDelegateRuleTool(host, config) {
 				repo: ocrRepo(args, exec, runMsgs),
 				paths: args["paths"]
 			}, runMsgs);
-			const text = await runForeground(host, withHomeEnv(command, ocrHome(config)), workdir, tuningOf(config), exec.signal);
-			const parsed = parseDelegateRules(text);
+			const stdout = await runForeground(host, withHomeEnv(command, ocrHome(config)), workdir, tuningOf(config), exec.signal);
+			const parsed = parseDelegateRules(stdout.text);
 			if (!parsed.ok) return format(runMsgs.parseFailedPlain, {
 				tool: "ocr delegate rule",
 				limit: String(RAW_ECHO_LIMIT),
-				raw: echoRaw(text, RAW_ECHO_LIMIT)
-			});
+				raw: echoRaw(stdout.text, RAW_ECHO_LIMIT)
+			}) + stdoutTruncationNote(config.stdoutMaxBytes, stdout, runMsgs);
 			return {
 				groupCount: parsed.groups.length,
 				groups: parsed.groups.map((group) => ({
@@ -3452,12 +3630,13 @@ function registerSessionTool(host, config) {
 				...args,
 				repo
 			}, runMsgs);
-			const text = await runForeground(host, withHomeEnv(command, ocrHome(config)), workdir, tuningOf(config), exec.signal);
+			const stdout = await runForeground(host, withHomeEnv(command, ocrHome(config)), workdir, tuningOf(config), exec.signal);
+			const { text } = stdout;
 			const stripped = text.trim();
 			const empty = stripped === "null" || stripped === "[]";
 			const capped = text.length > 12e3 ? `${echoRaw(text, 11900)}\n${runMsgs.sessionTruncated}` : redactKeyMaterial(text);
 			return {
-				sessionOutput: empty ? runMsgs.sessionEmpty : capped,
+				sessionOutput: (empty ? runMsgs.sessionEmpty : capped) + stdoutTruncationNote(config.stdoutMaxBytes, stdout, runMsgs),
 				hint: runMsgs.sessionResumeHint
 			};
 		}
@@ -3497,4 +3676,4 @@ var host_default = {
 	apply
 };
 //#endregion
-export { configSchema as Config, createGateway, host_default as default, ocrRepo, parseJsonBody, registerConfigEndpoints, requiredKeys };
+export { configSchema as Config, createGateway, host_default as default, isLoopbackBindAddress, ocrRepo, parseJsonBody, registerConfigEndpoints, requiredKeys };