@jayyuen66/dsh-quality-gate 0.1.2 → 0.1.4

package/host.js

@@ -7,10 +7,11 @@ import Schema from "@deepseek-ai/schemastery";
 import { credentialRef, isCredentialRefName } from "@deepseek-ai/dsh-credentials";
 import { LOCALE_SETTINGS_NAMESPACE, messagesFor, resolveLocalePreference } from "@jayyuen66/dsh-plugin-shared/lib/locale";
 import { deriveProjectKey } from "@jayyuen66/dsh-plugin-shared/lib/project-key";
-import { editPathOf, scanToolEvents } from "@jayyuen66/dsh-plugin-shared/lib/tool-events";
+import { editPathOf, scanToolEvents, toolEventRowsOf } from "@jayyuen66/dsh-plugin-shared/lib/tool-events";
 import { settleLessonCall } from "@jayyuen66/dsh-plugin-shared/lib/lesson-bus";
 import { fieldOf, isRecord } from "@jayyuen66/dsh-plugin-shared/lib/record";
-//#region lib/accumulator.ts
+import { z } from "zod";
+// lib/accumulator.ts
 /**
 * 需要过门禁的扩展名（代码与配置；md/txt/图片等免检）。
 *
@@ -20,7 +21,11 @@ import { fieldOf, isRecord } from "@jayyuen66/dsh-plugin-shared/lib/record";
 */
 const GATED_EXT = /\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs|rs|py|json|ya?ml|toml)$/iu;
 /** 编辑类工具名。str_replace_editor 是 dsh-base 并存的另一套编辑器
-*  （host 侧只对 create/str_replace/insert 记账，view 只读不入这里）。 */
+*  （host 侧只对 create/str_replace/insert 记账，view 只读不入这里）。
+*
+*  这是**唯一真源**：host 侧的同名判定（isEditTool）也用这一份，两边各写一份时新增
+*  编辑器工具只改一侧就会静默分叉——只改 host 则累加器静默丢弃记账，只改这里则 host
+*  根本不会调用 note。 */
 const EDIT_TOOLS = /* @__PURE__ */ new Set([
 	"edit",
 	"write",
@@ -34,24 +39,26 @@ var EditAccumulator = class {
 	/** 容量淘汰累计丢弃数：drain 时清零（静默淘汰要可观测）。 */
 	dropped = 0;
 	constructor(options = {}) {
-		this.maxFiles = options.maxFiles ?? DEFAULT_MAX_FILES;
+		const configured = options.maxFiles;
+		this.maxFiles = configured !== void 0 && Number.isInteger(configured) && configured > 0 ? configured : DEFAULT_MAX_FILES;
 	}
 	/** 记一笔：编辑类工具 + 代码/配置扩展名 + 非空路径才收；容量淘汰时计数。 */
 	note(name, filePath) {
 		if (name === void 0 || !EDIT_TOOLS.has(name)) return;
 		if (typeof filePath !== "string" || filePath.length === 0) return;
 		if (!GATED_EXT.test(filePath)) return;
-		if (this.files.size >= this.maxFiles && !this.files.has(filePath)) this.evictOldest();
+		this.files.delete(filePath);
+		if (this.files.size >= this.maxFiles) this.evictOldest();
 		this.files.add(filePath);
 	}
 	/**
-	* 淘汰插入序最旧的一项并计数。`maxFiles` 配成 0 时调用点对空集也成立，所以取到的首项
-	* 可以不存在——那一支什么都不做，由该退化配置的用例钉住。
-	* 这里只需要**取首项这一次动作**，不需要迭代：`for…of` + 无条件 `break` 正是
-	* eslint(no-unreachable-loop) 判的「循环体只允许一次迭代」——循环结构在这里不承载任何语义。
+	* 淘汰顺序最旧的一项并计数。
+	*
+	* 归一化后 `maxFiles >= 1`，而调用点只在 `size >= maxFiles` 时进来，所以集合必有可取首项。
 	*/
 	evictOldest() {
 		const [oldest] = this.files;
+		/* v8 ignore next 3 —— 上面那条不变量的直接推论：这一支只为类型收窄而写，正常配置下不可达。 */
 		if (oldest === void 0) return;
 		this.files.delete(oldest);
 		this.dropped += 1;
@@ -68,8 +75,7 @@ var EditAccumulator = class {
 		return out;
 	}
 };
-//#endregion
-//#region lib/gate-detect.ts
+// lib/gate-detect.ts
 /**
 * `pnpm check` 是否可用：必须有已声明的 check 脚本，**信息缺失时一律判否**。
 *
@@ -83,9 +89,25 @@ var EditAccumulator = class {
 function pnpmCheckReady(scripts) {
 	return scripts?.includes("check") === true;
 }
-/** 从 ProjectRoot（根目录相对名清单 + 已声明脚本）判定单根门禁。 */
+/**
+* `ruff check .` 是否可用：必须有 ruff 自己的配置面，**信息缺失时一律判否**。
+*
+* 为什么 pyproject.toml 单独不算证据：它不是 ruff 的配置标记，而是 Python 工程最常见的
+* 元数据文件——只写 `[project]`、lint 交给别的工具（flake8 / pylint / ruff 的编辑器集成）
+* 的工程大量存在。对这类工程发 `ruff check .`，一旦宿主 PATH 上有 ruff，就会拿 ruff 的
+* 默认规则集去判一个从未声明用 ruff 的项目，产出与使用者意图无关的告警，再经同一个注入
+* 通道被当成真实缺陷。这正是本模块要压住的假失败，方向与 pnpmCheckReady 一致。
+*
+* 判据收在两处**声明**上：`ruff.toml`（ruff 专属文件名，在场即声明）与 pyproject 里真有
+* 的 `[tool.ruff]` 一族段（由 host 读盘后经 ruffConfigured 传入）。二者都缺＝没有信息，
+* 按保守口径不给门禁——代价只是这一轮少一次自动核验，用户可以自己跑。
+*/
+function ruffGateReady(files, ruffConfigured) {
+	return files.includes("ruff.toml") || ruffConfigured === true;
+}
+/** 从 ProjectRoot（根目录相对名清单 + 已声明脚本 + ruff 配置事实）判定单根门禁。 */
 function gateForRoot(entry) {
-	const { root, files, scripts } = entry;
+	const { root, files, scripts, ruffConfigured } = entry;
 	const has = (name) => files.includes(name);
 	let gate;
 	if (has("pnpm-workspace.yaml") && has("package.json") && pnpmCheckReady(scripts)) gate = {
@@ -96,7 +118,7 @@ function gateForRoot(entry) {
 		root,
 		command: ["cargo", "check"]
 	};
-	else if (has("pyproject.toml") || has("ruff.toml")) gate = {
+	else if (ruffGateReady(files, ruffConfigured)) gate = {
 		root,
 		command: [
 			"ruff",
@@ -119,8 +141,7 @@ function detectGate(roots) {
 	}
 	return out;
 }
-//#endregion
-//#region lib/messages.ts
+// lib/messages.ts
 const MESSAGES = {
 	zh: {
 		evidenceTruncated: "[证据截断] {label} 内存里只保留尾部（首个错误可能在被丢弃的头部）。完整输出：{spill}",
@@ -171,33 +192,44 @@ const MESSAGES = {
 };
 /** 渲染模板里的 {name} 占位符；未提供的名字留空串（宁可少一段说明，也不给模型留裸花括号）。
 *  与 client 半官方 `@deepseek-ai/dsh-client-locale` 的 Translate 插值同语义（宿主同规则）。
+*
+*  查参数用 `Object.hasOwn` 而不是直接下标：模板里若出现 `{constructor}` / `{toString}` 这类被
+*  Object.prototype 覆盖的名字，裸下标取到的是函数对象、`String()` 之后会渲染成源码串，
+*  与"未提供的名字留空串"这条契约相反。
 *  @param text - 字典里的整行模板。
 *  @param params - 占位符名 → 值（数字会转成字符串）。
 *  @returns 替换后的文本。
 */
 function renderTemplate(text, params) {
-	return text.replaceAll(/\{(?<key>\w+)\}/gu, (_all, key) => {
-		const value = params[key];
-		return value === void 0 ? "" : String(value);
-	});
+	const provided = new Map(Object.entries(params));
+	return text.replaceAll(/\{(?<key>\w+)\}/gu, (_all, key) => provided.get(key)?.toString() ?? "");
+}
+// lib/feedback-content.ts
+/** 空白折叠成单个空格并去首尾：让副本身处"一行正文"的契约之内。
+*  参数收 `unknown` 而不是 `string`：这是运行时边界（门禁执行结果由 spawn 与上游透传拼出来），
+*  类型注释拦不住 undefined/null。原先直接 `text.replaceAll` 时，异常会冒到
+*  pushFeedbackToMemory 的 catch 里 → "门禁失败却一条记忆都没写"，且日志里只有一句
+*  "memory feedback skipped"，看起来像网关挂了。 */
+function oneLine(text) {
+	return typeof text === "string" ? text.replaceAll(/\s+/gu, " ").trim() : "";
 }
-//#endregion
-//#region lib/feedback-content.ts
 /** 门禁失败 → 记忆正文：单行化（防换行噪音）。
+*  三处插值都要折叠：`failure` 来自被检查仓库的自由文本，`command` 来自配置里的自定义命令，
+*  `root` 可以是任何路径——任一处带换行/制表符，这条"一条记忆正文"就会被 auto-recall 拆成多段。
 *  不截断：截尾会吃掉多根错误里的中间根因；记忆网关的入库限额由网关侧把关，这里送全文。
 *  正文语言随官方 locale 偏好走（messages 由调用方按回合取出后传进来）——这条文本会被
 *  auto-recall 注入后续会话的上下文，是模型读的，不是日志。 */
 function buildFeedbackText({ command, root, failure }, messages) {
-	const cmd = command.join(" ");
-	const tail = failure.replaceAll(/\s+/gu, " ").trim();
 	return renderTemplate(messages.memoryFeedback, {
-		command: cmd,
-		root,
-		failure: tail
+		command: oneLine(command.join(" ")),
+		root: oneLine(root),
+		failure: oneLine(failure)
 	});
 }
-//#endregion
-//#region lib/gateway-target.ts
+// lib/gateway-target.ts
+/** 基址末尾斜杠与 IPv4 单段。 */
+const TRAILING_SLASHES$1 = /\/+$/u;
+const IPV4_OCTET = /^\d{1,3}$/u;
 /** env 值 trim 后非空则用之，否则回到 fallback（保留原 `||` 语义，
 *  又以显式比较规避 prefer-nullish-coalescing 与 strict-boolean-expressions）。 */
 function envOr(key, fallback) {
@@ -210,15 +242,44 @@ function envOr(key, fallback) {
 * 端口写死成默认，等于让别人的每次门禁失败都去连一个不存在的服务。设置优先于 env 的理由：
 * 设置卡是用户显式配置面，env 只能兜底，
 * 否则用户改了设置卡仍被一个看不见的环境变量越权。
+*
+* 解析不出合法 URL 时同样返回空串（按"未配置"处理）：`http://` 这类半截串裁掉斜杠后剩
+* `http:`，如果原样透给调用方，凭据安全判据会把它报成"明文 http 且非回环"——把配置写错
+* 误报成协议不安全，用户照提示改成 https 也修不好。
 */
 function resolveGatewayUrl(settingUrl) {
 	const configured = settingUrl.trim();
-	return (configured === "" ? envOr("TDAI_GATEWAY_URL", "") : configured).replace(/\/+$/u, "");
+	const candidate = configured === "" ? envOr("TDAI_GATEWAY_URL", "") : configured;
+	if (candidate === "") return "";
+	const normalized = candidate.replace(TRAILING_SLASHES$1, "");
+	let parsed;
+	try {
+		parsed = new URL(normalized);
+	} catch {
+		return "";
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return "";
+	return normalized;
+}
+/** 是否为 IPv4 回环（127.0.0.0/8 整段，不只是 127.0.0.1）。 */
+function isIpv4Loopback(host) {
+	const parts = host.split(".");
+	if (parts.length !== 4 || parts[0] !== "127") return false;
+	return parts.every((part) => IPV4_OCTET.test(part) && Number(part) <= 255);
 }
 /**
 * 凭据只允许发往 https 或回环地址：明文 http 到远端会把 Bearer 令牌暴露给同网段
 * （设置卡默认值就是本机 http，属有意用法）。返回 false 时调用方按"未配置"处理，
 * 不解析、不发送凭据。
+*
+* 回环按整段判定而不是三个字面量：IPv4 回环是 127.0.0.0/8，网关绑在 127.0.0.2 /
+* 127.0.1.1 时同样只在本机，判成"不安全"会让记忆反馈静默停掉、而用户从提示里看不出
+* 自己其实就在本机；IPv6 的 IPv4-mapped 写法（URL 把 `[::ffff:127.0.0.1]` 归一成
+* `[::ffff:7f00:1]`）同理。
+*
+* `localhost` 这一支是**有意保留的 fail-open**：它依赖 hosts/DNS 解析，hosts 被指向远端时
+* 本函数仍判安全。保留它是为了让设置卡的默认写法可用；要彻底关掉这个口子只能改成只认 IP
+* 字面量，那会让"本机网关"这条最常见用法需要用户自己去查 IP。
 */
 function isCredentialSafeUrl(url) {
 	let parsed;
@@ -230,25 +291,51 @@ function isCredentialSafeUrl(url) {
 	if (parsed.protocol === "https:") return true;
 	if (parsed.protocol !== "http:") return false;
 	const host = parsed.hostname.replaceAll(/^\[|\]$/gu, "");
-	return host === "localhost" || host === "127.0.0.1" || host === "::1";
+	return host === "localhost" || isIpv4Loopback(host) || host === "::1" || host.startsWith("::ffff:7f");
 }
-/** x-tdai-service-id：env 可覆盖，默认是网关协议的匿名服务名（不含任何机器信息）。 */
+/** `x-tdai-service-id` 的合法形状：网关侧按服务名路由，空白与控制字符会让请求头
+*  在 fetch 处直接抛 TypeError（undici 拒收含换行的头值），把一次投递变成一条异常。
+*  不合规的值一律回落到默认服务名，而不是把用户的笔误送上网关。 */
+const SERVICE_ID_RE = /^[\w.-]{1,64}$/u;
+/** 默认服务名：网关协议的匿名服务名（不含任何机器信息）。 */
+const DEFAULT_SERVICE_ID = "default";
+/** x-tdai-service-id：env 可覆盖，形状不合规时回落默认值。 */
 function resolveServiceId() {
-	return envOr("TDAI_SERVICE_ID", "default");
+	const configured = envOr("TDAI_SERVICE_ID", "");
+	return SERVICE_ID_RE.test(configured) ? configured : DEFAULT_SERVICE_ID;
 }
-/** cwd → agent_id：'尾目录名-<cwd 前 8 位 sha256>'（与网关插件 workspace-peer 同分桶语义，
-* 读/写同键，保证反馈沉淀进 auto-recall 同一记忆桶）。
-* 派生本体在 shared/lib/project-key.ts：lesson-loop 的 project 与这里同源一份实现，
-* 此前两处各存一份，改一处漏一处就把"教训 ↔ 记忆"的跨系统对照拆断了。 */
+/**
+* 作用：cwd → agent_id，'尾目录名-<cwd 前 8 位 sha256>'（与网关插件 workspace-peer 同分桶
+* 语义，读/写同键，保证反馈沉淀进 auto-recall 同一记忆桶）。
+*
+* 条件：派生本体在 shared/lib/project-key.ts —— lesson-loop 的 project 与这里同源一份实现，
+* 两处各存一份时改一处漏一处，把"教训 ↔ 记忆"的跨系统对照拆断而不报错。
+*
+* 子功能：参数保留 `unknown`（调用方的 cwd 来自会话事件，形状不由本包保证）；非字符串、
+* 空串、根路径一律回落 'default'。
+*
+* 执行：直接委托 deriveProjectKey。
+*
+* 验证方式：test/gateway-feedback.test.ts 的 deriveAgentId 组逐条钉住回落面，并有一例
+* 断言它与 deriveProjectKey 逐值同源。
+*
+* 不适用条件：'default' 是所有项目共享的记忆桶 —— 回落因此**可能**把反馈混进别人的桶。
+* 这里不为此加日志：本模块被 host 的 catch 包着、失败只 warn 一次，再往 lib 里塞一条
+* console 会污染测试日志账本（test/setup-logs.ts 要求每条日志都有模板认领）；而实际
+* 调用点传的是会话 cwd（host.ts 里由事件流给出，必为字符串），回落是给未来调用方的护栏。
+*/
 function deriveAgentId(cwd) {
 	return deriveProjectKey(cwd);
 }
-//#endregion
-//#region lib/gateway-feedback.ts
+// lib/gateway-feedback.ts
+/** 基址末尾斜杠。 */
+const TRAILING_SLASHES = /\/+$/u;
 /** 反馈尽力而为：5s 封顶，超时/失败只 warn（不吃掉门禁主流程）。 */
 const FEEDBACK_TIMEOUT_MS = 5e3;
 /** 沉淀门禁失败到 L0 记忆（role=assistant：这是 agent 自身行为教训，归顺 assistant 提炼面）。 */
 async function pushGateFeedback(input, target, messages) {
+	const base = target.url.trim().replace(TRAILING_SLASHES, "");
+	if (base === "" || target.key.trim() === "") throw new Error("投递目标不完整：url 与 key 都必须非空（目标面应由调用方解析后传入）");
 	const agentId = deriveAgentId(input.cwd);
 	const content = buildFeedbackText(input, messages);
 	const payload = JSON.stringify({
@@ -259,21 +346,108 @@ async function pushGateFeedback(input, target, messages) {
 			content
 		}]
 	});
-	const res = await fetch(`${target.url}/v2/conversation/add`, {
+	const res = await fetch(`${base}/v2/conversation/add`, {
 		method: "POST",
 		headers: {
 			Authorization: `Bearer ${target.key}`,
-			"x-tdai-service-id": resolveServiceId(),
+			"x-tdai-service-id": target.serviceId,
 			"Content-Type": "application/json"
 		},
 		body: payload,
 		signal: AbortSignal.timeout(FEEDBACK_TIMEOUT_MS)
 	});
-	if (!res.ok) throw new Error(`gateway feedback HTTP ${res.status}`);
-	await res.arrayBuffer().catch(() => null);
+	const drained = await res.arrayBuffer().catch(() => null);
+	if (!res.ok) {
+		const detail = drained === null ? "" : new TextDecoder().decode(drained).trim().slice(0, 200);
+		throw new Error(detail === "" ? `gateway feedback HTTP ${res.status}` : `gateway feedback HTTP ${res.status}：${detail}`, { cause: drained });
+	}
+}
+// lib/edit-ledger.ts
+/** 会话编辑台账投影：折叠与回退扫描共用 `toolEventRowsOf`，两处不会各自演化。 */
+const EDIT_LEDGER_KEY = "quality-gate.edit-ledger";
+/** 台账上限：超过即丢最旧的（门禁游标每回合推到末端；防的是从没跑成门禁的长会话）。 */
+const EDIT_LEDGER_MAX = 1024;
+const entrySchema = z.strictObject({
+	seq: z.int().nonnegative(),
+	callId: z.string(),
+	name: z.string(),
+	path: z.string(),
+	failed: z.boolean()
+});
+const editLedgerSchema = z.object({ edits: z.array(entrySchema) });
+/** 把最近一条同 callId 的记录标记为失败（tool/result 的 isError）；找不到就不动。 */
+function failEntry(state, callId) {
+	let index = -1;
+	for (let at = state.length - 1; at >= 0; at -= 1) if (state[at]?.callId === callId) {
+		index = at;
+		break;
+	}
+	return index < 0 ? state : state.map((entry, at) => at === index ? {
+		...entry,
+		failed: true
+	} : entry);
+}
+const editLedgerProjection = {
+	key: EDIT_LEDGER_KEY,
+	stateVersion: 1,
+	stateSchema: editLedgerSchema,
+	init: () => ({ edits: [] }),
+	apply: (state, event) => {
+		const { call, result } = toolEventRowsOf(event, event.seq);
+		let { edits } = state;
+		if (call !== void 0 && EDIT_TOOLS.has(call.name) && !call.badArguments) {
+			const target = editPathOf(call);
+			if (target.kind === "write") edits = [...edits, {
+				seq: call.seq,
+				callId: call.callId ?? "",
+				name: call.name,
+				path: target.path ?? "",
+				failed: false
+			}];
+		}
+		if (result !== void 0 && result.isError && result.callId !== void 0) edits = failEntry(edits, result.callId);
+		const bounded = edits.length > 1024 ? edits.slice(edits.length - EDIT_LEDGER_MAX) : edits;
+		return bounded === state.edits ? state : { edits: bounded };
+	}
+};
+// lib/edit-ledger-reader.ts
+const isDisposer = (value) => typeof value === "function";
+const isProjectionHandle = (value) => value !== null && typeof value === "object" && typeof value.stateOf === "function" && typeof value.dispose === "function";
+/** 把原始状态校验成台账：形状不合约定的持久行按「不可读」处理。 */
+function asLedger(raw) {
+	const parsed = editLedgerProjection.stateSchema.safeParse(raw);
+	return parsed.success ? parsed.data.edits : void 0;
+}
+/**
+* 注册投影并发布读口；失败（同步抛错或异步拒绝）只报告、不发布。
+* @param registry - 官方 sessionProjections 服务
+* @param face - 读口发布位与释放登记位
+*/
+async function mountEditLedgerReader(registry, face) {
+	let read;
+	let release;
+	try {
+		const ready = await registry.register(editLedgerProjection);
+		if (isDisposer(ready)) {
+			read = (session) => asLedger(registry.stateOf(session, EDIT_LEDGER_KEY));
+			release = ready;
+		} else if (isProjectionHandle(ready)) {
+			read = (session) => asLedger(ready.stateOf(session));
+			release = () => {
+				ready.dispose();
+			};
+		} else throw new TypeError("sessionProjections.register returned neither a disposer nor a handle");
+	} catch (error) {
+		face.onError(error);
+		return;
+	}
+	face.publish(read);
+	face.effect(() => () => {
+		face.publish(void 0);
+		release();
+	});
 }
-//#endregion
-//#region host.ts
+// host.ts
 /**
 * 常见项目根标记文件：向上找最近的含清单目录。
 * ruff.toml 必须在列：只有 ruff 配置、无 pyproject.toml 的 Python
@@ -281,10 +455,12 @@ async function pushGateFeedback(input, target, messages) {
 * 也就永远没有门禁。
 */
 const PKG_MANIFEST = "package.json";
+const TSCONFIG_MANIFEST = "tsconfig.json";
+const PYPROJECT_MANIFEST = "pyproject.toml";
 const MANIFESTS = [
 	PKG_MANIFEST,
 	"Cargo.toml",
-	"pyproject.toml",
+	PYPROJECT_MANIFEST,
 	"pnpm-workspace.yaml",
 	"ruff.toml"
 ];
@@ -423,10 +599,12 @@ function gateCommandArgs(gate) {
 	正常安装不可达，而那一路由 126/127 报成未执行。 */
 	return [tscEntry(gate.root) ?? "tsc", "--noEmit"];
 }
+/** shell 里无需加引号的参数形状。 */
+const SHELL_SAFE_ARG = /^[\w./:=@+-]+$/u;
 /** 拼 shell 串：路径可能带空格，含空白或元字符的参数加单引号。
 *  导出只为直接测这段引号处理：tsc 入口是绝对路径，它所在目录未必没有空格。 */
 function shellArg(part) {
-	return /^[\w./:=@+-]+$/u.test(part) ? part : `'${part.replaceAll("'", `'\\''`)}'`;
+	return SHELL_SAFE_ARG.test(part) ? part : `'${part.replaceAll("'", `'\\''`)}'`;
 }
 /** 门禁命令的展示/执行串（与 gateCommandArgs 同源）。 */
 function gateCommandText(gate) {
@@ -558,16 +736,26 @@ function interruptedRunOutcome(messages, budgetMs, res) {
 	}
 	return outcome;
 }
+/** 门禁工具不可用的 stderr 措辞。 */
+const TOOL_UNAVAILABLE_TEXT = /command not found|not recognised|not recognized|permission denied|not executable/u;
 /**
-* 门禁工具本身不可用（exit 126/127 = 不可执行/未找到）→ not-run，并 warn 给运维。
-*
-* 环境问题非代码问题：走失败注入会让模型去"修"装不了的工具（配合配额环更糟）。
-* 但它同样是"没跑成的检查"，所以按 not-run 注入"请手动确认"，不再算作通过
-* ——没跑成 ≠ 通过。
+* exit 126/127 只有在 stderr 点名门禁命令自己的首 token 时才算「工具不可用」：
+* `pnpm check` 的脚本里缺命令 pnpm 同样回 127（`[ELIFECYCLE] Command failed with exit code 127`），
+* 混判会把项目自己的坏脚本当成环境问题放掉。判据按行：同一行既有「不可用」措辞又出现该 token。
+*/
+function gateToolUnavailable(gate, res) {
+	if (res.exitCode !== 126 && res.exitCode !== 127) return false;
+	const token = gate.command[0].toLowerCase();
+	return res.stderr.text.toLowerCase().split("\n").some((line) => line.includes(token) && TOOL_UNAVAILABLE_TEXT.test(line));
+}
+/**
+* 门禁工具本身不可用（exit 126/127 且 stderr 点名门禁命令）→ not-run，并 warn 给运维。
+* 环境问题非代码问题：失败注入会逼模型去修装不了的工具；但没跑成 ≠ 通过。
+* 脚本内部的 126/127 不走这支（见 gateToolUnavailable），按代码失败。
 */
 function unavailableToolOutcome(messages, gate, res, log) {
 	let outcome;
-	if (res.exitCode === 126 || res.exitCode === 127) {
+	if (gateToolUnavailable(gate, res)) {
 		log.warn(`[quality-gate] gate tool unavailable (exit ${res.exitCode}): ${gateCommandText(gate)} — reported as not-run, not as pass`);
 		const cause = res.exitCode === 127 ? messages.toolMissing : messages.toolNotExecutable;
 		outcome = {
@@ -608,9 +796,11 @@ function classifyRun(messages, gate, budgetMs, res, log) {
 		text: `exit=${res.exitCode}\n${evidenceText(messages, res.stdout, "stdout")}${evidenceText(messages, res.stderr, "stderr")}`
 	};
 }
-/** 是否是会被记账的编辑类工具（edit/write + str_replace_editor）。 */
+/** 是否是会被记账的编辑类工具（edit/write + str_replace_editor）。名单的真源在
+*  lib/accumulator.ts 的 EDIT_TOOLS：host 先用它过滤、累加器再用同一集合过滤一次，
+*  两边各写一份时新增编辑器工具只改一侧就会静默分叉。 */
 function isEditTool(name) {
-	return name === "edit" || name === "write" || name === "str_replace_editor";
+	return EDIT_TOOLS.has(name);
 }
 /**
 * 根 package.json 已声明的 scripts 名清单（值是非空字符串才算"声明了这条脚本"）。
@@ -621,7 +811,7 @@ function isEditTool(name) {
 function declaredScriptsOf(root) {
 	let names;
 	try {
-		const raw = JSON.parse(readFileSync(`${root}/package.json`, "utf8"));
+		const raw = JSON.parse(readFileSync(path.join(root, PKG_MANIFEST), "utf8"));
 		const scripts = fieldOf(raw, "scripts");
 		if (isRecord(scripts)) names = Object.entries(scripts).filter(([, body]) => typeof body === "string" && body.length > 0).map(([name]) => name);
 	} catch {
@@ -634,6 +824,33 @@ function isArrayDelivery(value) {
 	return Array.isArray(value);
 }
 /**
+* pyproject 里 ruff 段头的字面形状：`[tool.ruff]` 或它的子表 `[tool.ruff.lint]` 等。
+*
+* `^` 加 `m` 旗标限定为行首；`[tool.ruff]` 与 `[tool.ruff.<子表>]` 都要认——只写子表、
+* 不写父表的 pyproject 是常见写法。数组表（`[[tool.ruff...]]`）同样命中段名，一并算声明。
+*/
+const RUFF_SECTION = /^\[\[?tool\.(?:"ruff"|ruff)[\].]/mu;
+/**
+* 根 pyproject.toml 里是否声明了 ruff 配置段（段头形状见 RUFF_SECTION）。
+*
+* 只按行首段头字面匹配，不引 TOML 解析器：判据只需要回答"有没有这一段"，而段头在
+* TOML 里必须独占一行（行内写法 `[a.b] c = 1` 非法），故行首匹配与解析器同解。带引号的
+* 键形式（`[tool."ruff"]`）在 TOML 里合法且等价，一并认。
+*
+* 读不到 / 解码失败 → undefined（"没有信息"），由 gate-detect 按保守口径处理：不发 ruff
+* 门禁。这里与 declaredScriptsOf 同一方向，理由见 gate-detect 的 ruffGateReady。
+*/
+function ruffConfiguredOf(root) {
+	let configured;
+	try {
+		const text = readFileSync(path.join(root, PYPROJECT_MANIFEST), "utf8");
+		configured = RUFF_SECTION.test(text);
+	} catch {
+		configured = void 0;
+	}
+	return configured;
+}
+/**
 * 解析事件游标窗口：fork 切点下限 vs 上次已读 seq 取大，返回起始 seq 与本批事件。
 * 事件流取自官方 `ctx.sessionQuery.observeSession(sessionId)`（见上面 SessionQueryFace：
 * 一次交回 `events` 与 `inheritedEventCount`）。两条降级路径一律 `undefined`（调用方直接
@@ -649,8 +866,9 @@ function isArrayDelivery(value) {
 */
 async function resolveEventWindow(query, sessionId, lastSeq) {
 	let window;
+	let observation;
 	try {
-		const observation = await query.observeSession(sessionId, { projectionMode: "none" });
+		observation = await query.observeSession(sessionId, { projectionMode: "none" });
 		const forkCut = observation.inheritedEventCount ?? 0;
 		const from = Math.max(forkCut, lastSeq.get(sessionId) ?? forkCut);
 		if (isArrayDelivery(observation.events)) window = {
@@ -659,6 +877,8 @@ async function resolveEventWindow(query, sessionId, lastSeq) {
 		};
 	} catch {
 		window = void 0;
+	} finally {
+		observation?.[Symbol.dispose]();
 	}
 	return window;
 }
@@ -704,7 +924,7 @@ function findManifestRoot(file, maxDepth) {
 	let found;
 	let hitDepthLimit = false;
 	for (let depth = 0; depth < maxDepth; depth += 1) {
-		for (const manifest of MANIFESTS) if (existsSync(`${dir}/${manifest}`)) {
+		for (const manifest of MANIFESTS) if (existsSync(path.join(dir, manifest))) {
 			found = dir;
 			break;
 		}
@@ -726,7 +946,7 @@ function findManifestRoot(file, maxDepth) {
 function workspaceRootUpgrade(root, maxDepth) {
 	let up = path.dirname(root);
 	for (let depth = 0; depth < maxDepth; depth += 1) {
-		if (existsSync(`${up}/pnpm-workspace.yaml`)) return up;
+		if (existsSync(path.join(up, "pnpm-workspace.yaml"))) return up;
 		const parent = path.dirname(up);
 		if (parent === up) break;
 		up = parent;
@@ -740,20 +960,22 @@ function workspaceRootUpgrade(root, maxDepth) {
 * - tsconfig.json 不作为"根标记"（不进 MANIFESTS，避免改动根向上探测的语义），
 *   但要进清单集合——gate-detect 用它区分"真 TS 项目"与"只有 package.json 的空壳"；
 * - scripts：根 package.json 已声明的脚本名清单，交给 gate-detect 判定 pnpm check
-*   是否可用。**这里只做如实登记，不做取舍**（探测策略集中在纯函数里）。
+*   是否可用。**这里只做如实登记，不做取舍**（探测策略集中在纯函数里）；
+* - ruffConfigured：根 pyproject.toml 里是否真有 `[tool.ruff]` 一族段，交给 gate-detect
+*   判定 ruff 门禁是否可用。理由同上——只登记，不取舍。
 */
 function probeProjectRoot(root) {
-	const manifests = MANIFESTS.filter((manifest) => existsSync(`${root}/${manifest}`));
-	if (existsSync(`${root}/tsconfig.json`)) manifests.push("tsconfig.json");
+	const manifests = MANIFESTS.filter((manifest) => existsSync(path.join(root, manifest)));
+	if (existsSync(path.join(root, TSCONFIG_MANIFEST))) manifests.push(TSCONFIG_MANIFEST);
 	const scripts = manifests.includes("package.json") ? declaredScriptsOf(root) : void 0;
-	return scripts === void 0 ? {
+	const ruffConfigured = manifests.includes(PYPROJECT_MANIFEST) ? ruffConfiguredOf(root) : void 0;
+	const entry = {
 		root,
 		files: manifests
-	} : {
-		root,
-		files: manifests,
-		scripts
 	};
+	if (scripts !== void 0) entry.scripts = scripts;
+	if (ruffConfigured !== void 0) entry.ruffConfigured = ruffConfigured;
+	return entry;
 }
 /** 注入载荷组装（id 唯一，同一毫秒多次注入也不碰撞）。 */
 const injectMessage = (text) => ({
@@ -828,7 +1050,8 @@ async function resolveFeedbackTarget(cfg, credentials) {
 		ok: true,
 		target: {
 			url,
-			key: hit.value
+			key: hit.value,
+			serviceId: resolveServiceId()
 		}
 	};
 }
@@ -883,14 +1106,26 @@ function isGateHost(value) {
 	return typeof get === "function" && typeof on === "function" && typeof effect === "function" && typeof inject === "function" && isRecord(fiber) && typeof fieldOf(settings, "describe") === "function" && typeof fieldOf(settings, "configure") === "function";
 }
 /**
-* 一个文件的最近清单根 → 实际要跑的根：workspace 根优先，**但只在外层真能产出门禁时**才升级。
+* 子包自己就产得出 `pnpm check`（自带 `pnpm-workspace.yaml` 且声明了 check）时，它就是离
+* 文件最近、又真能跑的那一层门禁；再上溯外层工作区只会把「改一个子包」放大成「跑整棵
+* workspace 的全套检查」——门禁的作用域应当止步于最近的 workspace 根。
+*/
+function hasPnpmCheckGate(root) {
+	return detectGate([root]).some((gate) => gate.command[0] === "pnpm");
+}
+/**
+* 一个文件的最近清单根 → 实际要跑的根：最近的 workspace 根优先，**但只在外层真能产出门禁时**才升级。
 *
 * 只判「上面有没有 pnpm-workspace.yaml」就升级是漏门禁的一条路：外层若是"有 workspace 清单、
 * 却没有 check 脚本也没有 tsconfig"的根，gate-detect 对它返回空表，子包本来有的
 * `npx tsc --noEmit` / `ruff check` 会被这次上溯抹掉，且没有任何输出。
+*
+* 反方向也一样：子包本身就是 workspace 根且能出门禁时不再上溯——否则「本仓自己的门禁」
+* 会被外层伞工作区的全套 `pnpm check` 顶掉，单仓改动要等着跑九个仓。
 */
 function rootForFile(useRoot, maxDepth) {
 	const inner = probeProjectRoot(useRoot);
+	if (hasPnpmCheckGate(inner)) return inner;
 	const upgraded = workspaceRootUpgrade(useRoot, maxDepth);
 	if (upgraded === useRoot) return inner;
 	const outer = probeProjectRoot(upgraded);
@@ -1021,6 +1256,26 @@ function accumulatorOf(rt, sessionId) {
 * Session.inheritedEventCount（0.1.2-rc.1 起公开只读）给出 fork 切点——首读下限
 * 取切点而非 0，父前缀天然跳过；缺属性退回 0（旧行为，保守不漏门禁）。
 */
+/**
+* 只用投影台账记本回合编辑。返回 false = 走不了投影（读口缺席、fork 会话、读数不可信、
+* 或会话交不出日志长度），调用方回退观察面。
+*
+* fork 会话（isSeeded）不进这条路：继承前缀的精确长度只有观察面的 `inheritedEventCount`
+* 给得出，投影的 `apply` 看不到那条边界。读口交回 undefined 同样回退，且**不推游标**——
+* 把一次不可读当成「没有编辑」会静默跳过本回合的门禁。
+*/
+function noteLedgerEdits(rt, session, note) {
+	const reader = rt.editLedger.value;
+	const directSeq = session.seq;
+	if (reader === void 0 || session.header.isSeeded || typeof directSeq !== "number") return false;
+	const ledger = reader(session);
+	if (ledger === void 0) return false;
+	const from = rt.lastSeqBySession.get(session.id) ?? 0;
+	for (const entry of ledger) if (entry.seq >= from && !entry.failed) note(entry.name, entry.path === "" ? void 0 : entry.path);
+	rt.lastSeqBySession.set(session.id, directSeq);
+	pruneToSessionBudget(rt.lastSeqBySession, session.id);
+	return true;
+}
 async function readEditedFiles(rt, agent, acc) {
 	const { session } = agent;
 	const sessionId = session.id;
@@ -1032,6 +1287,13 @@ async function readEditedFiles(rt, agent, acc) {
 		}
 		return;
 	}
+	const { cwd } = session.header;
+	const note = (name, pathValue) => {
+		let resolvedPath = pathValue;
+		if (resolvedPath !== void 0 && cwd !== void 0 && !path.isAbsolute(resolvedPath)) resolvedPath = path.resolve(cwd, resolvedPath);
+		acc.note(name, resolvedPath);
+	};
+	if (noteLedgerEdits(rt, session, note)) return;
 	const window = await resolveEventWindow(query, sessionId, rt.lastSeqBySession);
 	if (window === void 0) {
 		if (!rt.queryReadWarned) {
@@ -1043,12 +1305,6 @@ async function readEditedFiles(rt, agent, acc) {
 	rt.lastSeqBySession.set(sessionId, window.from + window.events.length);
 	pruneToSessionBudget(rt.lastSeqBySession, sessionId);
 	const edits = collectEdits(window.events);
-	const { cwd } = session.header;
-	const note = (name, pathValue) => {
-		let resolvedPath = pathValue;
-		if (resolvedPath !== void 0 && cwd !== void 0 && !path.isAbsolute(resolvedPath)) resolvedPath = path.resolve(cwd, resolvedPath);
-		acc.note(name, resolvedPath);
-	};
 	for (const entry of edits.noCallId) note(entry.name, entry.path);
 	for (const [callId, entry] of edits.pending) if (!edits.failed.has(callId)) note(entry.name, entry.path);
 }
@@ -1281,8 +1537,20 @@ function apply(ctx, config) {
 		shellWarned: false,
 		queryMissingWarned: false,
 		queryReadWarned: false,
+		editLedger: { value: void 0 },
 		disposed: false
 	};
+	svc.inject(["sessionProjections"], (child) => {
+		mountEditLedgerReader(child.sessionProjections, {
+			publish: (reader) => {
+				rt.editLedger.value = reader;
+			},
+			effect: (factory) => child.effect(factory),
+			onError: (error) => {
+				log.warn(`[quality-gate] sessionProjections register failed, falling back to full scan: ${String(error)}`);
+			}
+		});
+	});
 	svc.on("agent/turn-stopping", async (payload) => {
 		try {
 			await handleTurnGate(rt, payload);
@@ -1304,5 +1572,4 @@ var host_default = {
 	Config,
 	apply
 };
-//#endregion
 export { Config, apply, host_default as default, shellArg };