@tea-agent/loop-agent 0.38.0 → 0.38.1

package/CHANGELOG.md

@@ -2,6 +2,80 @@
 
 ## [Unreleased]
 
+### 改进
+
+- Operator Chat 恢复工具对齐真实能力：系统提示改用 `dagReport` / `dagRerunPlan` / `dagRerun` / `standaloneTaskRerun` / `workerTaskRetry` 真名，不再写 `operator_*` 或把 `dagResume` 当成模型可执行项；`dagDoctor` / `dagStatus` / `workerPoolDoctor` 改为 typed `runId`/`taskId`，不再让模型猜 CLI `args[]`。ADR 0013 自定义 base prompt 上限由 1900 统一调整为 2500（2026-08-18，废止 0.8×2498 比例），预算用于写清节点续跑 / 整单重生 / Worker 重排队分流，以及多轮迭代恢复纪律（先一句话总结上一轮错误、修根因不修症状、禁止原样重交、同错两轮后停下报告）。
+
+- Operator Chat 对齐 pi-web：建会话不再传封闭 `tools` 白名单（避免 SDK 把扩展 MCP 工具滤出 registry），创建后 `bindExtensions` 发 `session_start`，再钉激活集。扩展注册的 MCP 工具可被模型调用；`apply_patch` / `full-tools` / `shell` / `coding-chat` 仍排除。
+- 对话侧栏 Plugins 右侧新增只读 MCP 弹窗：展示 `mcp.json` 配置的服务，以及当前会话真正注册/激活的 MCP 工具；没有配置也没有工具时保持真实空态。
+- 对话侧栏原 Packages 入口改名为 Plugins，与 pi-web / Pi 用户面一致；内部仍是 package inventory。
+- 对话进行中底部上下文占用百分比保持常驻：token 用量事件不再冲掉上一帧的 contextUsage，并在回合中持续刷新。
+- 上一轮大量 bash 结束后再发新消息，旧工具条不再整批挂到新气泡下面：无主工具不再丢进最新一组，历史按完整回合裁切，空助手气泡若还挂着工具会留下来当锚点。
+- 侧栏文件树点击目录行直接插入 `@目录/` 引用（箭头单独负责展开/收起）；输入框 @ 补全也列出目录，排在文件前面。
+- 对话进行中点「停止」立即安静下来（乐观停止，对齐 pi-web）：不再等 POST /abort 往返；后端 abort 等待从 8s 降到 2.5s，未终结时由状态对账收敛。
+- 侧栏文件树实时刷新：agent 回合结束、浏览器标签页回到前台、手动点「刷新」时重拉根目录+全部已展开目录（此前手动刷新只拉根目录，子目录永远旧缓存）。
+- Skills / Packages / Models 面板不再把 Pi 的 warning / collision 原文堆在列表上方：改成标题条一颗摘要芯片（如「14 条提示」），点开按「需要处理 / 名称不规范 / 同名未生效」分组，文案用自然语言，路径只显示末两段；名称不规范的技能在列表旁标「提示」，详情里说明「现在这样也能用」。加载失败仍单独成组，可点「再读一次」。
+- Skills / Packages 双栏改为左右各自滚动；资源弹窗挂到 `document.body`，按顶部对话导航的实时高度在剩余视口居中，不再被 sticky 顶栏挡住上沿。
+
+### 新增
+
+- 前端 plan 唯一机器契约化（JSON-only）：`frontend-plan-pi` / `frontend-plan-revision-pi` 输出收敛为「一行导语 + 唯一 fenced `json` 契约 + 唯一 `openspec-citations` 引用块」，彻底移除「可选 Markdown 说明」；plan.md（`contracts/frontend-plan.md`）改由 prewrite gate 用纯函数 `renderFrontendPlanMarkdown` 确定性渲染（不新增 DAG 节点/不新增 Pi 调用）
+- 契约 schema 新增 5 个可选字段（`implementationSteps` / `stylingStrategy` / `dependencyPolicy` / `residualRisks` / `realIntegrationGap`），`schemaVersion` 保持 1；`docs/templates/frontend-implementation-contract.schema.json` 同步
+- revision 输出改为 RFC 7386 merge-patch delta + 引用块：gate 配置新增 `revisionPatch`，生效时在 `planFallbackFromNodeIds[0]` 原始契约上应用 `applyFrontendImplementationContractPatch` 后进入既有分析/规范化/物化管线；旧 DAG 缺字段按整契约处理
+- canonical contract 序列化（UTF-8）超过 64KB → `retryable-invalid` + 新增 `contract-too-large` failureCode（体积守卫兜底）
+- `design-review` / `final-design-review` 提示改为消费契约 JSON（注入契约字段摘要），不再要求读取 plan prose
+- Console「模型与认证」页新增模型矩阵编辑器：展示并允许编辑 `harness.json executors.pi` 的 LOW/MED/HIGH 三档模型；输入框从 readiness 结构化投影 `piModelMatrix` 预填（provider/model 或裸 model id），本地内联校验（空串 / `default` 哨兵 / 畸形 `provider/`、`/model`、`a//b`）非法时禁用保存；保存经既有 `POST /api/operator/v1/operations` 派发 `savePiModelMatrix`，复用 HTTP 层 `evaluateMutationGate`（boot capability cookie + `x-loop-console-confirmation` 头 + Origin/Host/Sec-Fetch-Site），读全文档后原子写 tmp+fsync+rename（保留 `$schema` 与其余字段），成功后自动重测 readiness 并对活动 Chat session 触发 `/sessions/:id/reload`（409 `PI_SESSION_BUSY` 给出可恢复提示）
+- `GET /api/operator/v1/readiness` 的 probe 新增 `piModelMatrix` 结构化投影（向后兼容，不改动既有 `modelsMessage`）
+- 组件选型规范合规（ADR 0016）：契约 schema 新增可选 `uiComponentChoices[]`（`{ purpose, component, decision(specified|reuse-existing|new), specReference{path,section,line}|null, rationale }`），`specified` 必须给非空 `specReference`、`new` 不得携带、空串拒绝；`schemaVersion` 保持 1；`docs/templates/frontend-implementation-contract.schema.json` 同步
+- `frontend-prewrite-gate` 新增三个 `retryable-invalid` failureCode：`component-spec-reference-invalid`（specReference.path 非受支持规范路径）、`component-spec-not-cited`（未在 openspec-citations 引用块引用或未真实读取）、`component-choices-missing`（组件/主题候选桶非空且契约有 UI 可见工作而 `uiComponentChoices` 缺失/空）
+- gate 配置新增可选 `componentSpecCandidatePaths`（旧 DAG 缺字段兼容）；`init-hybrid` 从 `designEvidence.classified.component ∪ theme ∪ rule.components` 冻结注入，capability context 强调组件/主题桶语义，plan/revision/design-review/final-design-review 提示加入硬规则与 BAD/GOOD 示例
+- `frontend-plan.md` 新增 `Component Selection (spec conformance)` 章节（纯函数确定性渲染，缺省 `_(not specified)_`）
+
+- `frontend-prewrite-gate` 的 OpenSpec 读取校验支持 `task.json.frontendOpenspec` 配置：`policy` 缺省 `cited`（候选 = `requiredReadPaths` ∪ 任务源显式引用的 openspec 路径），`scan-strict` 保留止血任务后的全量必读语义；`requiredReadPaths` 中非 openspec 支持路径在生成期确定性失败
+- 确定性引用块协议：生效 plan 输出在 fenced `json` 契约块后追加 `openspec-citations` fenced 块（每行一个 JSON `{"path","section","line"}`）；gate 解析并与生效 plan/review 节点的成功 read 事件核验，新增 `openspec-citation-block-unparseable` / `openspec-not-cited` / `openspec-citation-not-read` 三个 retryable-invalid failureCode（防捏造、防遗漏）
+- `src/shared/openspec-spec.ts` 新增 `extractTaskSourceOpenspecPaths` 纯函数（反引号内联、markdown 链接目标、裸路径 token → 归一化 → spec 过滤 → 治理子树排除 → 去重排序）
+- 生成期把 `openspecPolicy` 与候选来源元数据（`openspecCandidateSources.declared` / `taskSourceCited` / `scanStrict`）冻结进 prewrite gate 配置；`task advance` 的 advisories 说明当前模式与候选来源
+
+### 修复
+
+- `frontend-plan-revision-pi` 节点级校验与 merge-patch 输出协议矛盾修复：新增 schemaId `frontend-implementation-contract-revision-patch-v1` 与格式级宽松校验 `validateFrontendRevisionPatchNodeOutput`（至少一个 `openspec-citations` 块 + 剥离引用块后恰好一个 JSON 对象，不做完整契约 schema 校验），revision 节点 `structuredContractOutput.schemaId` 切换（plan-pi 仍为 v1）；node-execution 的 invalid-output retry 指令按 schemaId 分支，patch 协议提示 merge-patch delta + 引用块，消除「prompt 要求 patch、retry 要求完整契约」的 retryable 死循环；gate 仍是唯一权威合并/校验点（零改动）。ADR 0015 补「节点级校验」决策 7
+- `frontend-implementation-contract.schema.json` 的 `uiComponentChoices` items 补 `if/then` 决策语义（`specified` ⇒ `specReference` 必填非 null；`new` ⇒ `specReference` 为 null/缺失）；`frontend-plan-render.ts` 空 `section` 不再渲染尾随 `#`；ADR 0016 增补「门禁边界」小节
+
+### 文档
+
+- 新增 `docs/decisions/0016-frontend-component-conformance.md`，并同步 `docs/runtime/frontend-implementation-workflow.md`、`docs/templates/frontend-implementation-contract.schema.json`、`skills/frontend-implementation/references/design-spec.md`、`skills/frontend-implementation/references/node-contracts.md`、`skills/frontend-design-review/references/review-checklist.md`、`CONTEXT.md`
+- 新增 `docs/decisions/0015-frontend-plan-json-only-contract.md`，并同步 `docs/runtime/frontend-implementation-workflow.md`、`docs/templates/frontend-implementation-contract.schema.json`、`skills/frontend-implementation/references/node-contracts.md`
+- 新增 `docs/decisions/0014-openspec-gate-claim-verification.md`，并同步 `docs/runtime/frontend-implementation-workflow.md`、`docs/templates/frontend-task-constraints.md`、`docs/templates/frontend-design-contract.md`、`skills/frontend-implementation/references/node-contracts.md`
+
+## [0.36.4-beta.0] - 2026-08-16
+
+> 前端 DAG 规范上下文确定性落地（beta，发布到 `beta` dist-tag）。
+
+### 新增
+
+- `discoverFrontendProjectCapability` 产出 `designEvidence.classified` 语义归类：按通用目录约定（`openspec/schemas/**`、`openspec/project-specs/templates/**`、`openspec/project-specs/rules/**`、`openspec/project-specs/ui/**`、`ai_workspace/**`）把规范路径分入稳定键 `schemas` / `codeTemplate` / `rule.*` / `theme` / `component` / `uiOther` / `advisoryOther`，并进入 zod schema 校验（分区恒等式：归类值集合 == `normativePaths` 集合），重复探测稳定，不硬编码具体项目文件名
+- 前端 contract/scout/plan/design-review 节点的 `subtask_prompt` 注入归类后的规范路径（含角色语义）并明确要求报告适用规则、命中路径/章节/行号、冲突与缺失
+
+### 修复
+
+- `frontend-prewrite-gate` 在 `openspecCandidatePaths` 非空时强制生效 plan/review 节点实际读取候选路径：未读 → `retryable-invalid` + 新增 `openspec-not-read` failureCode，错误信息列出未读路径；空候选（greenfield）不阻断。此前读取证据仅记录不阻断（advisory），本次真正 fail-closed
+- OpenSpec 候选发现止血：默认排除治理子树（`harness.json.governanceRoot` → 缺省 `ai_workspace/loop-agent`），移除固定 `slice(0, 40)` 截断，`openspec/**` 排序优先于 `ai_workspace/**`，仅保留 ≥200 的显式安全上限（命中时写入 `DagSpec.advisories`，非静默丢弃）；`openspec-not-read` 失败原因增加实际读取路径/候选总数/排除统计与「重新生成 DAG」归因，生成后已删除/改名的候选改为 `candidate-missing-drift` 诊断而非误报「未读」
+
+### 文档
+
+- `docs/templates/frontend-task-constraints.md` 把裸 `TODO` 改写为「探索协议 + 结果 schema + 缺失/冲突 fail-closed」，不再出现具体业务组件名或项目专属路径/命令
+- `docs/templates/frontend-task-requirement.md` 与 `docs/templates/frontend-design-contract.md` 把裸 `TODO` 改写为「编写协议」三要素（要写什么 / DAG 如何消费 / 缺失/冲突时 fail-closed），并新增 `test/frontend-template-no-todo.test.ts` 扫描三个前端模板断言无裸 `TODO`
+- `docs/runtime/frontend-implementation-workflow.md` 的项目规范归类清单改为通用目录约定 + 归类规则，删除写死的示例项目文件名
+
+## [0.36.3-beta.0] - 2026-08-16
+
+> 前端 DAG Mock 治理收紧（beta，发布到 `beta` dist-tag）。
+
+### 改进
+
+- 前端 DAG 的 Mock 策略约束注入设计评审链：`mockContextBlock`（含冻结 allowlist 的「HARD CONSTRAINT」与修复路径）现在也注入 `frontend-design-review-pi` / `frontend-plan-revision-pi` / `frontend-final-design-review-pi`，消除「design-review 按项目规范要求 native、但生成期 allowlist 冻结为 not-needed、prewrite 硬阻断」的策略断环——评审链会明确提示这是生成期契约缺口（需声明 `frontendMock.verifyCommands` 或 `policy: "required"` 后重新生成 DAG）
+- 前端任务生成期 Mock 预警：新增 `DagSpec.advisories`，任务源提到接口/API/Mock 但 auto 模式把策略收窄为 `not-needed` 时，`task advance` 的 `warnings` 会给出可操作提示（声明 `frontendMock.verifyCommands` 或 `policy: required` 后重新生成 DAG），把契约缺口提前到生成期暴露
+
 ### 新增
 
 - 版本发布改为三渠道：main 自动发布 npm `next`（`x.y.0-next.N`）、release 分支自动发布正式 patch 到 `release-x.y`、`latest` 仅由人工 GitHub Actions promotion 移动（支持 dry-run 与 CAS 校验）
@@ -49,6 +123,27 @@
 - move interrupt eligibility to observability to honor kernel import boundary
 - retry semantic intake across Pi tiers with 300s timeout
 
+## [0.36.1-beta.0] - 2026-08-16
+
+> 标准 DAG planner 输出超长紧凑重试（beta，发布到 `beta` dist-tag）。
+
+### 改进
+
+- 标准 DAG 的 planner 节点（`contract-pi` / `plan-pi`）输出超长（`output-too-large`）时自动紧凑重试：新增 `PLANNER_OUTPUT_LIMIT_RETRY_POLICY`（默认重试集合 + `output-too-large`），紧凑重试指令按节点类型区分——结构化契约节点只返回单个紧凑 JSON，普通计划节点返回最小计划（有序步骤、writeSet 边界、验证命令），并丢弃上游原文引用与长证据摘录
+
+## [0.35.4-beta.0] - 2026-08-15
+
+> frontend prewrite 阻断误路由修正 + Mock 契约文档落地（beta，发布到 `beta` dist-tag）。
+
+### 改进
+
+- prewrite 阻断导致的 writer `SKIPPED`（`skippedReason=frontend-prewrite-not-authorized`）失败路由从 `DependencyFailure`/`unblock dependency` 修正为 `ContractMismatch`/`fix-frontend-task-contract-and-regenerate-dag`；`dag report` / `dag doctor` 透传 `skippedReason`，对「Mock 策略契约缺陷需改 task.json + 重新生成 DAG」这类场景给出可操作建议，而非误导性的「解除依赖」
+
+### 文档
+
+- `docs/templates/frontend-task-constraints.md` 的 Mock 约束从 TODO 改为可落地契约：要求从项目**探索**实际存在的确定性 Mock 验证命令（不硬编码命令名）并声明到 `task.json.frontendMock.verifyCommands`，说明生成期 `allowedMockStrategies` 来源、`mock-strategy-outside-allowed` 是生成期契约问题（修复 = 补契约 + 重新生成 DAG，plan-revision 无法修复）
+- `docs/runtime/frontend-implementation-workflow.md` 的 task.json 输入标准补充 Mock 契约声明、命令探索与失败恢复指引
+
 ## [0.36.0] - 2026-08-15
 
 ### 新增

package/dist/build-stamp.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "version": "0.38.0",
-  "gitSha": "cc01c2ec09b56080f4c32416bddcc911feaa0e7a",
-  "builtAt": "2026-08-17T01:42:05.218Z"
+  "version": "0.38.1",
+  "gitSha": "0b7518c6f009d1fcf8776f757775bb447fd006ee",
+  "builtAt": "2026-08-18T22:33:47.281Z"
 }

package/dist/commands/init-upgrade.js

@@ -938,6 +938,80 @@ function changedWorkspacePaths(before, after) {
         .filter((relativePath) => before[relativePath] !== after[relativePath])
         .sort();
 }
+/**
+ * Generated-output prefixes treated as verification noise when git ignore
+ * rules are unavailable (non-git target). In a git repo the authoritative
+ * filter is `.gitignore` via `git check-ignore`; this list only covers the
+ * common case where a verification command such as `npm run build` writes
+ * untracked artifacts (build/dist/coverage/...) into the workspace.
+ */
+const WORKSPACE_NOISE_PREFIXES = [
+    "node_modules/",
+    "build/",
+    "dist/",
+    "coverage/",
+    ".turbo/",
+    ".next/",
+    ".nuxt/",
+    ".cache/",
+    ".parcel-cache/",
+    ".vite/",
+    "out/",
+    "target/",
+    "__pycache__/",
+];
+function isWorkspaceNoisePath(relative) {
+    if (relative === ".git" || relative.startsWith(".git/"))
+        return true;
+    if (relative === RUN_ROOT || relative.startsWith(`${RUN_ROOT}/`))
+        return true;
+    return WORKSPACE_NOISE_PREFIXES.some((prefix) => relative === prefix.slice(0, -1) || relative.startsWith(prefix));
+}
+/**
+ * Filters changed workspace paths down to meaningful (non-generated) changes
+ * so a verification command that legitimately writes git-ignored artifacts is
+ * not misjudged as an unauthorized workspace mutation. Git ignore rules are
+ * authoritative when the target is a git repo; otherwise the built-in
+ * generated-output prefixes apply.
+ */
+async function filterWorkspaceNoise(repoRoot, relativePaths) {
+    const builtinFiltered = relativePaths.filter((relative) => !isWorkspaceNoisePath(relative));
+    if (builtinFiltered.length === 0)
+        return builtinFiltered;
+    const ignored = await gitIgnoredPaths(repoRoot, builtinFiltered);
+    if (ignored === null)
+        return builtinFiltered;
+    return builtinFiltered.filter((relative) => !ignored.has(relative));
+}
+/**
+ * Returns the subset of paths matched by git ignore rules, or null when the
+ * target is not a git repository (or git is unavailable), in which case the
+ * caller falls back to the built-in noise prefixes.
+ */
+async function gitIgnoredPaths(repoRoot, relativePaths) {
+    return await new Promise((resolve) => {
+        execFile("git", ["-C", repoRoot, "check-ignore", ...relativePaths], {
+            timeout: 15_000,
+            maxBuffer: 4 * 1024 * 1024,
+            windowsHide: true,
+        }, (error, stdout) => {
+            if (error) {
+                // `git check-ignore` exits 1 when no path is ignored: that is a
+                // successful lookup with an empty result set. Any other failure
+                // (e.g. 128 outside a repo) means the git filter is unavailable.
+                if (error.code === 1 && stdout.length === 0)
+                    resolve(new Set());
+                else
+                    resolve(null);
+                return;
+            }
+            resolve(new Set(stdout
+                .split("\n")
+                .filter(Boolean)
+                .map((entry) => entry.split(path.sep).join("/"))));
+        });
+    });
+}
 function isFrozenVerificationSurface(value) {
     return (isRecord(value) &&
         value.schemaVersion === 1 &&
@@ -1587,7 +1661,7 @@ async function validateContinueMerge(directory, state, anchor) {
         await assertSafeMergePath(state.repoRoot, allowedPath);
     }
     const current = await snapshotWorkspace(state.repoRoot);
-    const changed = changedWorkspacePaths(authoritativeGuard.baselineWorkspace, current);
+    const rawChanged = changedWorkspacePaths(authoritativeGuard.baselineWorkspace, current);
     const pending = await readPendingAcceptance({
         directory,
         state,
@@ -1602,6 +1676,10 @@ async function validateContinueMerge(directory, state, anchor) {
             pending,
         })
         : undefined;
+    // Only the out-of-bound drift check treats git-ignored/generated-output
+    // changes as noise; allowed-path changes are merge content and must stay
+    // intact even when the target is git-ignored (e.g. `.agents/skills/*`).
+    const changed = await filterWorkspaceNoise(state.repoRoot, rawChanged);
     const unexpected = changed.filter((relativePath) => {
         if (allowed.has(relativePath))
             return false;
@@ -1611,7 +1689,7 @@ async function validateContinueMerge(directory, state, anchor) {
     if (unexpected.length > 0) {
         throw new Error(`init upgrade merge write-guard blocked out-of-bound workspace changes: ${unexpected.join(", ")}`);
     }
-    const changedAllowed = changed.filter((relativePath) => allowed.has(relativePath));
+    const changedAllowed = rawChanged.filter((relativePath) => allowed.has(relativePath));
     if (changedAllowed.length === 0) {
         if (pending) {
             throw new Error("pending merge acceptance cannot authorize a merge without an allowed workspace change");
@@ -1834,16 +1912,8 @@ async function createVerificationWriteAudit(input) {
     const note = (scope, file) => {
         events.push(`${scope}=${file.split(path.sep).join("/")}`);
     };
-    const ignoredWorkspacePath = (candidate) => {
-        const relative = toRepoPath(canonicalRepoRoot, candidate);
-        return (relative === ".git" ||
-            relative.startsWith(".git/") ||
-            relative === "node_modules" ||
-            relative.startsWith("node_modules/") ||
-            relative === RUN_ROOT ||
-            relative.startsWith(`${RUN_ROOT}/`));
-    };
-    const install = async (scope, directory, ignore) => {
+    const ignoredWorkspacePath = (candidate) => isWorkspaceNoisePath(toRepoPath(canonicalRepoRoot, candidate));
+    const install = async (scope, directory, ignore, scopeRoot) => {
         const canonical = await realpath(directory);
         if (watched.has(canonical))
             return;
@@ -1867,11 +1937,11 @@ async function createVerificationWriteAudit(input) {
                 // traversal opens an existing child directory. Nested watchers own real
                 // mutations below that child; persistent changes are also snapshot-checked.
                 if (!existingDirectory) {
-                    note(scope, path.relative(directory, candidate) || ".");
+                    note(scope, path.relative(scopeRoot ?? directory, candidate) || ".");
                 }
                 // A parent rename can introduce a new directory. Installing its watcher
                 // closes the delayed-descendant gap even when the container event is noise.
-                void install(scope, candidate, ignore).catch((error) => {
+                void install(scope, candidate, ignore, scopeRoot).catch((error) => {
                     const code = error.code;
                     if (code !== "ENOENT" && code !== "ENOTDIR") {
                         failures.push(`watcher refresh failed for ${scope}: ${error instanceof Error ? error.message : String(error)}`);
@@ -1891,10 +1961,10 @@ async function createVerificationWriteAudit(input) {
             const child = path.join(canonical, entry.name);
             if (ignore?.(child) || !entry.isDirectory() || entry.isSymbolicLink())
                 continue;
-            await install(scope, child, ignore);
+            await install(scope, child, ignore, scopeRoot);
         }
     };
-    await install("workspace", canonicalRepoRoot, ignoredWorkspacePath);
+    await install("workspace", canonicalRepoRoot, ignoredWorkspacePath, canonicalRepoRoot);
     await install("controller", runRoot(input.repoRoot));
     await install("controller-anchor", anchor.anchorRoot);
     const piHomeEntry = await lstat(piHome).catch((error) => {
@@ -2194,17 +2264,25 @@ async function runVerificationCommand(input) {
         if (audit.failures.length)
             throw new Error(audit.failures.join("; "));
         await assertFrozenVerificationSurface(repoRoot, surface);
-        const changedWorkspace = changedWorkspacePaths(workspaceBefore, await snapshotWorkspace(repoRoot));
+        const changedWorkspace = await filterWorkspaceNoise(repoRoot, changedWorkspacePaths(workspaceBefore, await snapshotWorkspace(repoRoot)));
         const changedController = changedWorkspacePaths(controllerBefore, await snapshotDirectory(runRoot(repoRoot)));
         const changedAnchors = changedWorkspacePaths(anchorBefore, await controllerAnchorSnapshot(repoRoot, state));
         const changedPiHome = changedWorkspacePaths(piHomeBefore, await snapshotOptionalDirectory(path.join(os.homedir(), ".pi")));
-        if (descendantsObserved || audit.events.length || changedWorkspace.length || changedController.length || changedAnchors.length || changedPiHome.length) {
+        // Workspace watcher events are repo-root relative (see scopeRoot in
+        // createVerificationWriteAudit); drop git-ignored/generated-output noise
+        // before deciding whether the subprocess wrote the workspace.
+        const workspaceEvents = audit.events.filter((event) => event.startsWith("workspace="));
+        const remainingEvents = [
+            ...audit.events.filter((event) => !event.startsWith("workspace=")),
+            ...(await filterWorkspaceNoise(repoRoot, workspaceEvents.map((event) => event.slice("workspace=".length)))).map((relative) => `workspace=${relative}`),
+        ];
+        if (descendantsObserved || remainingEvents.length || changedWorkspace.length || changedController.length || changedAnchors.length || changedPiHome.length) {
             return {
                 ...result,
                 ok: false,
                 stderr: boundedOutput(`${result.stderr}\nverification write guard blocked changes: ${[
                     ...(descendantsObserved ? ["process-tree=descendant"] : []),
-                    ...(audit.events.length ? [`events=${audit.events.join(",")}`] : []),
+                    ...(remainingEvents.length ? [`events=${remainingEvents.join(",")}`] : []),
                     ...(changedWorkspace.length ? [`workspace=${changedWorkspace.join(",")}`] : []),
                     ...(changedController.length ? [`controller=${changedController.join(",")}`] : []),
                     ...(changedAnchors.length ? [`controller-anchor=${changedAnchors.join(",")}`] : []),

package/dist/commands/init.js

@@ -1362,7 +1362,13 @@ async function readExistingSurfaceState(repoRoot) {
 }
 /** The IDE schema reference remains a structural update signal. */
 const HARNESS_STRUCTURAL_VALUE_KEYS = new Set(["$schema"]);
-const PI_MODEL_ROUTING_KEYS = new Set(["LOW", "MED", "HIGH", "defaultModel"]);
+const PI_MODEL_ROUTING_KEYS = new Set([
+    "LOW",
+    "MED",
+    "HIGH",
+    "defaultModel",
+    "modelOptions",
+]);
 function isPiModelRoutingPath(path) {
     return path.length === 2 && path[0] === "executors" && path[1] === "pi";
 }
@@ -1727,7 +1733,13 @@ function assessHarnessModelMigration(harness) {
     const hasDefaultModel = "defaultModel" in pi;
     const hasTier = PI_MODEL_TIERS.some((tier) => tier in pi);
     if (["requiresApiKey", "provider", "model"].some((field) => field in pi) ||
-        Object.keys(pi).some((field) => !["description", "enabled", "defaultModel", ...PI_MODEL_TIERS].includes(field))) {
+        Object.keys(pi).some((field) => ![
+            "description",
+            "enabled",
+            "defaultModel",
+            "modelOptions",
+            ...PI_MODEL_TIERS,
+        ].includes(field))) {
         return {
             kind: "ambiguous",
             reason: "executors.pi contains unknown or deprecated model semantics",

package/dist/executors/dag-pi-executor.js

@@ -1043,6 +1043,7 @@ export function mapPiResultToDagNodeResult(result, firstProtocolLine) {
         sdkAttempted: result.sdkAttempted,
         tokensUsed: result.tokensUsed,
         parsedEvents: result.parsedEvents,
+        stopReason: readWriterThinkingExhaustionEvidence(result).stopReason,
     };
 }
 function canonicalizeProtocolFirstLine(assistantText, firstProtocolLine) {

package/dist/governance/manifest-types.js

@@ -78,6 +78,8 @@ export const executorManifestSchema = z
     LOW: executorTierModelSchema.optional(),
     MED: executorTierModelSchema.optional(),
     HIGH: executorTierModelSchema.optional(),
+    /** Console 模型矩阵下拉专用列表；仅供 UI 使用，不参与 DAG 模型路由。 */
+    modelOptions: z.array(z.string().min(1)).optional(),
 })
     .strict();
 export const workflowPolicyProfileNameSchema = z.enum([

package/dist/infrastructure/harness/atomic-write.js

@@ -1,13 +1,14 @@
 import { copyFile, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { assertHarnessWriteAllowed, } from "./completed-facts-guard.js";
+let atomicWriteSequence = 0;
 async function writeAtomic(targetPath, content, options) {
     assertHarnessWriteAllowed(targetPath, options);
     const resolved = options?.repoRoot && !path.isAbsolute(targetPath)
         ? path.resolve(options.repoRoot, targetPath)
         : path.resolve(targetPath);
     await mkdir(path.dirname(resolved), { recursive: true });
-    const tempPath = `${resolved}.${process.pid}.tmp`;
+    const tempPath = `${resolved}.${process.pid}.${(atomicWriteSequence += 1)}.tmp`;
     try {
         await writeFile(tempPath, content, "utf-8");
         try {

package/dist/shared/openspec-spec.js

@@ -14,6 +14,30 @@ export const OPENSPEC_SPEC_DIRS = [
 ];
 /** Allowed spec file extensions (case-insensitive). */
 export const OPENSPEC_SPEC_EXT_RE = /\.(md|mdx|json|yaml|yml)$/i;
+/**
+ * Default governance subtree excluded from candidate discovery. Aligned with
+ * init.ts's DEFAULT_GOVERNANCE_ROOT; discovery derives the real root from
+ * harness.json.governanceRoot and falls back to this value.
+ */
+export const DEFAULT_OPENSPEC_GOVERNANCE_ROOT = "ai_workspace/loop-agent";
+/**
+ * Explicit safety ceiling for auto-discovered openspec candidates (>=200).
+ * Reaching the cap is reported via DagSpec.advisories, never silently dropped.
+ */
+export const MAX_OPENSPEC_CANDIDATE_PATHS = 200;
+/**
+ * Returns `true` when `filePath` is the governance subtree itself or any path
+ * under it. `filePath` must be a repo-relative POSIX path (backslashes are
+ * normalised internally). Comparison is case-sensitive, matching the other
+ * predicates in this module.
+ */
+export function isGovernanceSubtreePath(filePath, governanceRoot) {
+    const normalized = filePath.replaceAll("\\", "/");
+    const root = governanceRoot.replaceAll("\\", "/").replace(/\/+$/, "");
+    if (!root)
+        return false;
+    return normalized === root || normalized.startsWith(root + "/");
+}
 /**
  * Returns `true` when `filePath` is inside one of the canonical frontend spec
  * directories.  `filePath` must be a repo-relative POSIX path (backslashes are
@@ -47,3 +71,55 @@ export function isOpenspecSpecSearchTarget(value) {
     const normalized = value.replaceAll("\\", "/");
     return /(?:^|[^A-Za-z0-9_.-])(?:openspec\/(?:schemas|project-specs)|ai_workspace)(?:\/|$)/.test(normalized);
 }
+/** Normalizes a free-form path token to a repo-relative POSIX path or null. */
+function normalizeCitationToken(raw) {
+    let token = raw.trim();
+    token = token.replace(/^[<"'`(\[\s]+|[>"'`)\]\s]+$/g, "");
+    // Strip trailing punctuation that is not part of a filename.
+    token = token.replace(/[),.;:!?]+$/g, "");
+    const hashIndex = token.indexOf("#");
+    if (hashIndex >= 0)
+        token = token.slice(0, hashIndex);
+    token = token.replace(/\\/g, "/");
+    if (!token)
+        return null;
+    return token;
+}
+/**
+ * Deterministically extracts repo-relative openspec spec paths explicitly cited
+ * in task-source markdown (requirement + execution constraint). Pure function,
+ * no IO.
+ *
+ * Scanned sources, in order:
+ * - backtick inline code spans (`path`)
+ * - markdown link targets ([text](path))
+ * - bare path tokens under openspec/ or ai_workspace/
+ *
+ * Every token is normalized to POSIX, stripped of a trailing `#fragment`,
+ * filtered through `isOpenspecSpecFilePath`, and excluded when it falls inside
+ * the governance subtree (matching `listOpenspecDiscovery`'s exclusion口径).
+ * Results are deduped and sorted.
+ */
+export function extractTaskSourceOpenspecPaths(markdown, governanceRoot = DEFAULT_OPENSPEC_GOVERNANCE_ROOT) {
+    if (!markdown)
+        return [];
+    const raw = new Set();
+    const collect = (token) => {
+        const normalized = normalizeCitationToken(token);
+        if (normalized)
+            raw.add(normalized);
+    };
+    for (const match of markdown.matchAll(/`([^`\n]+)`/g)) {
+        collect(match[1] ?? "");
+    }
+    for (const match of markdown.matchAll(/\[[^\]]*\]\(([^)\s]+)\)/g)) {
+        collect(match[1] ?? "");
+    }
+    for (const match of markdown.matchAll(/(?:^|[\s"'([>])((?:openspec|ai_workspace)\/[A-Za-z0-9._/-]+)/g)) {
+        collect(match[1] ?? "");
+    }
+    return [...raw]
+        .filter((token) => isOpenspecSpecFilePath(token) &&
+        !isGovernanceSubtreePath(token, governanceRoot))
+        .sort();
+}

package/dist/shared/operator/capabilities.js

@@ -63,8 +63,6 @@ const officialAction = (action, cli, kind, coverage) => ({
 });
 const OFFICIAL_ACTIONS = [
     ...[
-        ["dagDoctor", "loop-agent dag doctor", "read", "model-callable"],
-        ["dagStatus", "loop-agent dag status", "read", "model-callable"],
         [
             "dagDecisionInspect",
             "loop-agent dag decision inspect",
@@ -284,7 +282,6 @@ const OFFICIAL_ACTIONS = [
             "long-running",
             "advanced",
         ],
-        ["workerPoolDoctor", "agent-worker pool doctor", "read", "model-callable"],
         [
             "workerPoolMarkFailed",
             "agent-worker pool mark-failed",
@@ -1079,7 +1076,7 @@ export function buildOperatorCapabilitiesDocument() {
                 "CONTROLLER_MISMATCH",
                 "INVALID_INPUT",
             ],
-            description: "Consume a single-use execution receipt and execute the reviewed DAG (prefer task advance --approve-gate when gate token present). accepted/queued/running/operationId are NOT completion — supervise via operationGet/status/dagReport/dagDoctor/operationWait.",
+            description: "Consume a single-use executionId from prepareDagExecution and execute the reviewed DAG. Do not pass a DAG path and do not bash `task advance --approve-gate`. accepted/queued/running/operationId are NOT completion — supervise via operationGet/status/dagReport/dagDoctor/operationWait.",
             inputParams: [
                 {
                     name: "executionId",
@@ -1102,7 +1099,7 @@ export function buildOperatorCapabilitiesDocument() {
             resultSchemaVersion: 1,
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["INVALID_INPUT", "NOT_FOUND"],
-            description: "Read-only R1 subgraph plan (no mutation). Call before dagRerun. Prefer primaryFailure.nodeId from dagReport. If eligible=false (writer/decision/fingerprint, unsafe shell, worker-managed, workspace/controller drift), do not force execute — Worker-owned runs use workerTaskRetry; standalone runs use standaloneTaskRerun or same-task advance after fixing the root cause (contract changes must be adopted first). Returns planHash required by execute.",
+            description: "Read-only check: can this failed run continue from fromNode? Call after dagReport; pass primaryFailure.nodeId. Does not execute. eligible=true returns planHash for dagRerun. eligible=false: Worker/Task Pool Failed → workerTaskRetry; standalone Console run → standaloneTaskRerun after any required contract adopt. Do not call dagRerun or invent a new task.",
             inputParams: [
                 {
                     name: "runId",
@@ -1132,7 +1129,7 @@ export function buildOperatorCapabilitiesDocument() {
                 "BINDING_DRIFT",
                 "INVALID_INPUT",
             ],
-            description: "Execute R1 continuation from effective node. Requires planHash from a fresh dagRerunPlan (eligible=true). Prefer this over new task / standaloneTaskRerun for provider flake and safe downstream failures. Server enforces planHash/binding/fingerprint freshness.",
+            description: "Continue the same DAG from fromNode. Requires a fresh dagRerunPlan with eligible=true and that exact planHash. Prefer this for provider flake / safe downstream failures. Not a full task regenerate (that is standaloneTaskRerun). Server rejects stale planHash or binding drift.",
             inputParams: [
                 {
                     name: "runId",
@@ -1498,7 +1495,7 @@ export function buildOperatorCapabilitiesDocument() {
                 "INVALID_INPUT",
                 "HUMAN_CONFIRMATION_REQUIRED",
             ],
-            description: "Full standalone task regenerate → validate → execute with parent lineage. Only when node rerun plan is ineligible or primaryRecovery recommends rerun-task; the server checks read-only run facts before accepting. Regeneration reuses the CURRENT contract snapshot: if the failure requires contract changes (e.g. allowing a catalog index path), first update the contract (re-import PRD, or adopt externally-edited sources via `task contract adopt`) BEFORE calling this action, otherwise the regenerated DAG repeats the same failure.",
+            description: "Regenerate the whole standalone DAG from the CURRENT contract, then validate and execute a new run (parent lineage kept). This is NOT continue-from-failed-node — that is dagRerun. Server rejects the call when dagRerunPlan is eligible, when primaryRecovery.humanRequired=true, or when run facts do not recommend rerun-task. Adopt contract changes before calling or the new DAG repeats the same failure.",
             inputParams: [
                 {
                     name: "runId",
@@ -1542,7 +1539,7 @@ export function buildOperatorCapabilitiesDocument() {
                 "INVALID_INPUT",
                 "HUMAN_CONFIRMATION_REQUIRED",
             ],
-            description: "Requeue failed Task Pool task (Failed → Ready) via in-package pool store. Only when read-only validation confirms the task exists in Failed state; the server checks this before accepting.",
+            description: "Requeue a Worker Task Pool task Failed → Ready. Not a DAG node rerun (use dagRerun) and not a standalone DAG regenerate (use standaloneTaskRerun). Confirm with workerPoolDoctor first; server accepts only Failed pool tasks. Pass featureId when known — it must match the pool record.",
             inputParams: [
                 {
                     name: "taskId",
@@ -1568,6 +1565,66 @@ export function buildOperatorCapabilitiesDocument() {
             modelCallable: "always",
             humanConfirmation: "none",
         },
+        {
+            action: "dagDoctor",
+            cli: "loop-agent dag doctor [--run-id <id>] --json",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["NOT_FOUND", "INVALID_INPUT"],
+            description: "Diagnose DAG run health. Omit runId for a repo-wide inventory (active/paused/completed + health issues). Pass runId for one run's liveness, heartbeat, failure node, and recovery hints. Use this to supervise stalls; it does not mutate the run.",
+            inputParams: [
+                {
+                    name: "runId",
+                    type: "string",
+                    required: false,
+                    description: "optional dag run id; omit to inventory all runs, pass to diagnose one run",
+                },
+            ],
+            modelCallable: "always",
+            humanConfirmation: "none",
+        },
+        {
+            action: "dagStatus",
+            cli: "loop-agent dag status --run-id <id>",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["NOT_FOUND", "INVALID_INPUT"],
+            description: "Read one DAG run's live status, current node, and liveness. Requires runId. Complements dagReport (terminal handoff) and dagDoctor (health diagnosis). Does not mutate the run.",
+            inputParams: [
+                {
+                    name: "runId",
+                    type: "string",
+                    required: true,
+                    description: "dag run id",
+                },
+            ],
+            modelCallable: "always",
+            humanConfirmation: "none",
+        },
+        {
+            action: "workerPoolDoctor",
+            cli: "agent-worker pool doctor --repo . --json",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["INVALID_INPUT", "NOT_FOUND"],
+            description: "Read-only Task Pool inventory (legacy + v2). Use before workerTaskRetry to confirm the task exists and status is Failed. Optional taskId filters the returned inventory to that task.",
+            inputParams: [
+                {
+                    name: "taskId",
+                    type: "string",
+                    required: false,
+                    description: "optional task id to focus the inventory",
+                },
+            ],
+            modelCallable: "always",
+            humanConfirmation: "none",
+        },
         ...OFFICIAL_ACTIONS,
     ];
     return {

package/dist/task/config-types.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { isOpenspecSpecFilePath } from "../shared/openspec-spec.js";
 export const taskFlowSchema = z.enum([
     "auto",
     "micro",
@@ -65,6 +66,24 @@ export const frontendMockConfigSchema = z.object({
     serviceRoot: z.string().min(1).optional(),
     verifyCommands: z.array(frontendMockVerifyCommandSchema).optional().default([]),
 });
+/** OpenSpec gate policy for frontend prewrite: cited (default) vs scan-strict. */
+export const frontendOpenspecPolicySchema = z.enum(["cited", "scan-strict"]);
+/**
+ * Frontend OpenSpec gate configuration. `cited` (the task-config default) makes
+ * the prewrite gate verify contract-declared requiredReadPaths plus task-source
+ * citations instead of the full generation-time directory snapshot; `scan-strict`
+ * keeps the auto-discovered full-read semantics.
+ */
+export const frontendOpenspecConfigSchema = z.object({
+    policy: frontendOpenspecPolicySchema.optional().default("cited"),
+    requiredReadPaths: z
+        .array(z
+        .string()
+        .refine((candidate) => !candidate.includes("\\") &&
+        isOpenspecSpecFilePath(candidate), "frontendOpenspec.requiredReadPaths entries must be repo-relative supported files under openspec/schemas/, openspec/project-specs/, or ai_workspace/"))
+        .optional()
+        .default([]),
+});
 /** Batch limits and gate profile for the browser-driven frontend test DAG.
  * Token fields are post-case stop thresholds, not model-provider hard caps. */
 export const frontendTestConfigSchema = z.object({
@@ -175,6 +194,8 @@ const taskConfigObjectSchema = z.object({
     frontendMock: frontendMockConfigSchema.optional(),
     /** Frontend browser-test batch and post-case token-stop configuration. */
     frontendTest: frontendTestConfigSchema.optional(),
+    /** Frontend OpenSpec gate policy and contract-declared required read paths. */
+    frontendOpenspec: frontendOpenspecConfigSchema.optional(),
     notes: z.string().optional().default(""),
 });
 export const taskConfigSchema = z.preprocess((raw) => {