docs(api): lease/state mutation fallback 入公开文档（task_operation_failed，来源 OV #330 / #334） by tizerluo · Pull Request #92 · openagentemail/website

tizerluo · 2026-09-22T22:46:52Z

What / why

来源 = OV #330 的 docs 追加件（代码面 = 主仓 PR #334，已合 squash 8a270026）；docs 真源在 website 仓 ⇒ 按属主映射由本组开 docs-only PR（总指挥 #4585 转交）。无 Closes（不需要关单）。

落点（内容锚定，非行号）

src/content/docs/docs/reference/api.md 的 ## POST /v1/tasks 段内：紧接既有 “Monitoring note: …” 段落之后、## GET /v1/tasks?state= 之前（真源 origin/main = 9921293，插入点落在 :387 与 :389 之间）。

内容（逐字照贴）

Lease and state mutation fallback:

| Stage | Status | `body` | Meaning |
|---|---|---|---|
| `POST /v1/tasks/:id/{claim,lease,release,claim-lost,decision,state}` and the console task-mutation path, when a failure is not mapped to a domain error | `502` | `{error:"task_operation_failed"}` (no `taskId`) | These paths **do deliver mail during the write stage** (lease-journal delivery, approval-terminal delivery, remind, update notification), so an SMTP delivery failure is **one possible cause** — but the same code also covers unmapped/internal failures (for example `task_leases_disabled`). The previous `smtp_error` label attributed all of them to SMTP alone. Mapped domain errors keep their own codes and statuses. |

Monitoring note: this fallback carries **no** `taskId`, so on these routes the pre/post-create `taskId` test above does not apply; the server-side `console.warn` on the mutate paths is the primary attribution aid.

范围

docs-only：只加这一小节（表 + 监控注记），不碰本段其它文字、不改站点其它文件。
未动 public/llms.txt（已核：不含 task_operation_failed / task_leases_disabled 等串 ⇒ 无第二面需要同步）。
主仓那份 docs/api.md（已声明 moved 的指针）未动。

本地核（FC 亲跑；权威格 = CI）

检查	结果
`npm ci`（worktree 内精确装依赖）+ `npx astro build`	成功（70 pages）
`node --test tests/seo-docs.test.mjs tests/llms-txt.test.mjs tests/mcp-tools.test.mjs`	17 pass / 0 fail
`npm run postbuild`（compare/jsonld/seo-docs/llms-txt/mcp-tools/i18n-sync 全套 rendered）	全绿 + `en-baseline 5-part invariant check PASSED`
`i18n-en-baseline.json` 同轮重算	恰 1 行：`docs/reference/api/index.html` `bodySha256` `0ee6108e…` → `ce1d3b8b…`（其余条目逐字节相同）
`git diff --shortstat`	2 文件（`api.md` +9、`i18n-en-baseline.json` +1/−1）

纪律留痕（按 13 号文【已知坑】新立那条）：本仓基线是「渲染后 en HTML 逐页 sha256」冻结件 ⇒ 重算必须在锁文件精确重建的环境里做。本卡在 worktree 内 npm ci 后重建再算，一次即恰 1 行（对照 website#90 的教训：用主 checkout node_modules 软链算出的 97 行漂移是假漂移）。

Summary by CodeRabbit

Documentation
- Updated the API reference to clarify the fallback error response for task mutation requests, including that it does not include a task ID.
- Added details on how failures are logged, including exceptions for lease renewals and releases.

…_failed) [#330] 来源：OV #330 的 docs 追加件（代码面 = PR #334，已合 squash 8a270026）。真源在 website ⇒ 由本组开 docs PR。内容（逐字，总指挥 #4585 转交）：`## POST /v1/tasks` 段内**紧接既有 Monitoring note 段落之后**追加「Lease and state mutation fallback」小节——`/v1/tasks/:id/{claim,lease,release,claim-lost,decision,state}` 与控制台 task-mutation 路径在**未映射到域错误**时统一 `502 {error:"task_operation_failed"}`（无 taskId）；这些路径**在写阶段确实会发信**，故 SMTP 失败只是**可能原因之一**（同段代码也覆盖未映射/内部失败，如 `task_leases_disabled`），旧的 `smtp_error` 标签把二者混为一谈；已映射域错误保留各自码与状态码。附监控注记：该 fallback **不带 taskId** ⇒ 上面那条 pre/post-create 判别不适用于这些路由，服务端 mutate 路径的 `console.warn` 是主要归因手段。 i18n-en-baseline.json 同轮重算：**恰 1 行**（docs/reference/api/index.html bodySha256 0ee6108e… → ce1d3b8b…），按纪律在 worktree 内 `npm ci` 精确装依赖后重建再算（避免工具链漂移造成假漂移）。本地核：seo-docs/llms-txt/mcp-tools 17 pass·0 fail；astro build OK；postbuild 全绿 + 5-part en-baseline 不变量 PASSED。

tizerluo · 2026-09-22T22:47:25Z

@coderabbitai review

coderabbitai · 2026-09-22T22:47:32Z

⚠️ Action not completed

Pull request base or head changed.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

coderabbitai · 2026-09-22T22:47:42Z

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: openagentemail/website/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: fbe682fc-b903-43d1-b6cc-eb562427d716

📥 Commits

Reviewing files that changed from the base of the PR and between 9921293 and 75b8b72.

📒 Files selected for processing (2)

i18n-en-baseline.json
src/content/docs/docs/reference/api.md

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

📝 Walkthrough

Walkthrough

The API reference now documents fallback errors for task mutation routes and console mutations. The English baseline checksum for the generated API reference was updated.

Changes

Task mutation error documentation

Layer / File(s)	Summary
Document mutation fallback errors `src/content/docs/docs/reference/api.md`, `i18n-en-baseline.json`	The API reference documents the `502 {"error":"task_operation_failed"}` fallback, the absence of `taskId`, and the available logging details. The generated reference’s baseline checksum is updated.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~3 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to 75b8b

This documentation update clarifies mutation fallback responses and monitoring exceptions. No actionable merge risk is established; it appears ready after normal checks.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the API documentation update for the task mutation fallback and names the documented error code.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Commit to this branch
Create a new PR

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

tizerluo · 2026-09-22T22:50:17Z

ZCode Review Gate：✅ pass

项	值
head（mimosa 扫描基线）	`075a00b70afe`
严重度分布	P0 × 0 · P1 × 0 · P2 × 0 · P3 × 4
结论	未发现阻断问题，可以合并

完整审查报告（zcode_pr_review：git diff + mimosa 深扫 + ZCode 只读复核）

审查完成。以下为完整审查报告。

PR 安全审查报告

PR: base=origin/main → 075a00b(2 个文件:src/content/docs/docs/reference/api.md、i18n-en-baseline.json)

一、汇总

级别	数量
P0(阻断合并)	0
P1(应修)	0
P2(建议)	0
P3(提示)	4

mimosa findings 核实: 扫描结果为 0 findings、0 业务逻辑假设,无可核实条目(确认漏洞 0 / 误报 0 / 存疑 0)。我按规则对改动文件相关代码做了人工抽查(i18n-check 脚本、i18n 测试、docs 渲染链路),未发现可利用问题。

结论: 本 PR 为纯文档改动 + 对应的 i18n 英文基线哈希同步,未引入任何可执行代码、未泄露敏感信息、未扩大攻击面。可以合并。

二、改动内容定性

api.md:389-395 — 在 POST /v1/tasks 章节的错误码表之后新增"Lease and state mutation fallback"表格与一段监控说明:任务变更路由(POST /v1/tasks/:id/{claim,lease,release,claim-lost,decision,state} 及 console 任务变更路径)在失败未映射到领域错误时返回 502 {error:"task_operation_failed"}(无 taskId),并说明该 fallback 此前标记为 smtp_error、现涵盖未映射/内部错误(如 task_leases_disabled)。
i18n-en-baseline.json:265 — 仅更新 docs/reference/api/index.html 条目的 bodySha256;headNormSha256、rulesSha256、stylesheets 均未变,与"仅正文内容变化"的文档改动完全吻合。这是仓库的标准工作流(node scripts/i18n-check.mjs --write-en-baseline 重新生成,scripts/i18n-check.mjs:368-376),且 CI 有 tests/i18n-sync.test.mjs:465(G13)对照 dist 构建产物做五元不变量校验,哈希若与实际构建不符会自动失败,属自我验证机制。

安全性判定依据: 改动为 Markdown 文本,经 Starlight 内容集合安全渲染,无原始 HTML、无脚本、无新增外链;不涉及凭证、内部主机名或密钥;公开文档描述错误码语义与监控归因方法属 API 参考文档的正常内容。所有 /v1/* 路由均要求 Bearer token(api.md 第 10-37 行),文档中提及路由路径名不产生新的暴露面。

三、问题清单(均为 P3 提示,不阻断)

P3-1|文档完整性 — api.md:393
新表格引用的 REST 路由 claim、lease、release、claim-lost 在全部文档中仅此一处出现(已全库 grep 确认;decision/state 有独立章节,MCP 侧仅有 task_claim/task_renew/task_release 工具记载于 src/data/mcp-tools.js:19-21)。读者会碰到未被参考文档定义的端点名。判定:非安全问题,属文档完整性瑕疵,建议后续补充对应端点章节。

P3-2|跨仓库一致性 — api.md:393
文档描述的服务端行为(task_operation_failed 取代 smtp_error)在本仓库无法交叉验证——本仓库为纯网站/文档仓库,无服务端代码。若服务端配套改动尚未发布,线上文档将与实际行为不符。判定:纯文档准确性风险,无安全影响;建议确认与服务端仓库同批发布。

P3-3|审查惯例提示(存量机制) — i18n-en-baseline.json
checkEnBaseline(scripts/i18n-check.mjs:378-454)是译文/渲染漂移检测门,不是内容防篡改基线:同一 PR 内同时改内容并更新哈希即可通过门禁。本 PR 的哈希变更已核对确与 api.md 正文新增成对、合理;提示今后审查此类 PR 时必须核对每个哈希变更都有对应的良性源内容 diff。

P3-4|存量提示(非本 PR 引入) — tests/e2e-redirect/fixtures/{key,cert}.pem
仓库提交了自签 TLS 密钥对。经核对其 README("All Local Fixtures, Zero Production/Public Network",仅服务 localhost e2e 测试),公开无害,属常见测试做法,仅作记录。

四、mimosa findings 核实

摘要显示 findings: 0,business-logic hypotheses: 0(scanId scan-2026-09-22T22-47-44.892Z-ba556273d4f3,dependency 477 包已完成)。无可核实条目:确认漏洞 0、误报 0、存疑 0。人工抽查补充:改动涉及的 scripts/i18n-check.mjs 为零依赖只读校验脚本,其 extractStylesheetShas 内含路径遍历防护(scripts/i18n-check.mjs:315-319,断言解析路径不越出 distDir),未见与本 PR 相关的风险。

VERDICT: P0=0 P1=0 P2=0 P3=4 MERGE=yes

_{由 zcode-review-gate 自动审查 · 写工具物理禁用 · 同一 head 不重复审}

tizerluo · 2026-09-22T22:52:06Z

Codex Local Review：⚠️ concerns

项	值
head	`075a00b70afe`
严重度分布	P0 × 0 · P1 × 2 · P2 × 0 · P3 × 0
结论	patch is incorrect（置信 0.98）——The fallback response itself is documented correctly, but the patch gives one condition that cannot reach that fallback and overstates the diagnostic information available from two route warnings. Bot

完整审查报告（本地 codex CLI · 只读沙箱 · 官方 rubric）

P1 · [P1] Remove the unreachable `task_leases_disabled` fallback example

位置：/home/ops/.local/share/codex-review-gate/crg-wt-b8t1y51y/src/content/docs/docs/reference/api.md:393 · 置信 0.99
When lease support is disabled, all four lease routes return 409 {error:"task_leases_disabled"} before invoking the service (packages/api/src/routes/tasks.ts:364,399,441,476), using the same immutable-at-runtime gate as the sole internal throw; decision and state cannot emit this code either. Thus no documented mutation path exposes this condition as 502 task_operation_failed, so this example misstates the public error contract.

P1 · [P1] Do not promise causal attribution from every mutation warning

位置：/home/ops/.local/share/codex-review-gate/crg-wt-b8t1y51y/src/content/docs/docs/reference/api.md:395 · 置信 0.97
When an unmapped /lease or /release failure occurs, the implementation logs only the static messages [task] renew failed and [task] release failed (packages/api/src/routes/tasks.ts:426,468) and discards the exception code. Those warnings cannot distinguish SMTP failures from the internal failures discussed above, so describing console.warn as the primary attribution aid is inaccurate for two of the listed routes unless their logging is enhanced.

_{Codex Local Review Gate（自托管 3+ 加固：严判 verdict · 同轮重试 · 现场诊断；模型线见 ~/.codex-dev/config.toml；in 598469/out 5960 tok，254s）· 同一 head 不重复审 · 云端 connector 延迟时的快速闸}

…table (Codex P1×2) Codex 报两条 P1，我**逐条对服务端源码亲核 = 全真**（`openagentemail/openagentemail@8a270026`）： 1. **删掉不可达的 `task_leases_disabled` 例子**（置信 0.99）：该码在四条 lease 路由上是 `if (!leasesEnabled()) return 409`（`packages/api/src/routes/tasks.ts:364/399/441/476`） —— **在调用 service 之前**的守卫返回，`decision`/`state` 也发不出它 ⇒ 任何已文档化的 mutation 路径都**不可能**以 502 `task_operation_failed` 暴露该条件。原句把它当 fallback 的例子属**误述公开错误契约** ⇒ 改为「also covers unmapped/internal failures.」（去例子）。 2. **不夸大 console.warn 的归因能力**（置信 0.97）：`/lease`(renew) 与 `/release` 的未映射失败分支只打静态文案（`tasks.ts:426` `[task] renew failed` / `:468` `[task] release failed`）并**丢弃异常码** ⇒ 这两条路由上「console.warn 是主要归因手段」不成立 ⇒ 监控注记补限定：**除** `/lease`(renew) 与 `/release` 外可用；那两条路由单凭响应无法区分 SMTP 失败与内部失败。 i18n-en-baseline.json 随同重算：仍**恰 1 行**（bodySha256 ce1d3b8b… → 226db8eb…）。本地核：astro build OK；源测 17/0；postbuild 全绿 + 5-part 不变量 PASSED。

tizerluo · 2026-09-22T22:57:01Z

Codex Local Review：✅ pass

项	值
head	`75b8b7273797`
严重度分布	P0 × 0 · P1 × 0 · P2 × 0 · P3 × 0
结论	patch is correct（置信 0.98）——The documented fallback bodies, statuses, affected mutation paths, mail-delivery behavior, and logging limitations match the authoritative implementation. No actionable defect introduced by this docum

完整审查报告（本地 codex CLI · 只读沙箱 · 官方 rubric）

未发现该 PR 新引入的问题。

_{Codex Local Review Gate（自托管 3+ 加固：严判 verdict · 同轮重试 · 现场诊断；模型线见 ~/.codex-dev/config.toml；in 501470/out 3766 tok，167s）· 同一 head 不重复审 · 云端 connector 延迟时的快速闸}

tizerluo · 2026-09-22T22:57:49Z

ZCode Review Gate：✅ pass

项	值
head（mimosa 扫描基线）	`75b8b7273797`
严重度分布	P0 × 0 · P1 × 0 · P2 × 0 · P3 × 3
结论	未发现阻断问题，可以合并

完整审查报告（zcode_pr_review：git diff + mimosa 深扫 + ZCode 只读复核）

审查完成。以下是完整报告。

PR 安全审查报告

PR: origin/main → 75b8b727 | 改动 2 个文件:i18n-en-baseline.json、src/content/docs/docs/reference/api.md
改动性质：纯文档变更(在 API 参考中新增一张任务 mutation 路径错误回退表格 + 监控说明)，外加 i18n 英文基线中对应页面 bodySha256 的同步更新。无任何可执行代码、配置或依赖变更。

一、汇总

级别	数量	说明
P0(阻断)	0	—
P1(应修)	0	—
P2(建议)	0	—
P3(提示)	3	文档-服务端同步依赖、基线哈希不可复算、内部日志细节披露

mimosa findings 核实：扫描报告 0 findings、0 业务逻辑假设，无可逐条核实条目(确认 0 / 误报 0 / 存疑 0)。按任务要求做了抽查：diff 中无密钥/凭证、无可执行内容、无 XSS 注入面(新增内容为 Markdown 表格文本，Starlight 静态渲染会转义，单元格内无 HTML/管道符破坏表格结构);package-lock.json 与 CI workflow 未触碰。

结论：可以合并。 文档与基线哈希的联动更新符合仓库既定流程，无新增安全风险。

二、逐条详述(P3)

P3-1 文档描述的服务端行为在本仓库不可验证，存在跨仓库同步依赖

文件位置:src/content/docs/docs/reference/api.md:389-395(新增表格与监控说明)
判定依据：本仓库是 openagentemail/website 官网/文档仓库，不含 API 服务端实现。全仓库检索 task_operation_failed 仅命中 api.md 本身(即本次新增文本)，/claim、/lease、/release、/claim-lost 等路由的实现代码、502 状态、console.warn 差异(/lease、/release 仅静态日志)均无法对照源码核实。文档声称"previous smtp_error label"指的是服务端行为而非本仓库旧文档(旧 api.md 中 smtp_error 仅出现在第 379 行 create 路径，该行不在本次改动范围且与新表格不矛盾)。若服务端仓库对应改动(错误码 smtp_error → task_operation_failed)未同步发布，此文档会误导用户的错误处理与告警归因。
建议：合并前确认服务端仓库的对应错误码变更已合入/将同版本发布；作为纯文档风险，不阻断本次合并。

P3-2 `bodySha256` 更新的正确性依赖 CI 构建门禁，只读审查无法复算

文件位置:i18n-en-baseline.json:265(docs/reference/api/index.html 条目)
判定依据：该基线由 scripts/i18n-check.mjs --write-en-baseline 对构建产物 dist/ 计算得出(scripts/i18n-check.mjs:347-376),tests/i18n-sync.test.mjs:465(G13)会在 CI 中用五要素不变量校验 dist 与基线一致。本次仅更新 bodySha256 而 headNormSha256/rulesSha256/stylesheets 不变，与"只改正文、不动 head/CSS"的改动内容机制上自洽；但新哈希值是否真对应新 api.md 的构建产物，只能靠构建复算，只读审查(执行被禁)无法验证。若哈希写错，后果是 CI G13 变红(完整性门禁失效方向是"误报"而非"漏报")，不构成安全风险。另外注意：基线与源码同库同 PR 提交，它对恶意 PR 作者本无独立防御力——这是存量设计属性，非本次引入。
建议：无需动作；依赖 CI 兜底即可。

P3-3 文档新增内容披露服务端日志/错误归因的内部实现细节

文件位置:src/content/docs/docs/reference/api.md:395(监控说明段)
判定依据：明文披露"/lease(renew)与 /release 仅记录静态日志、不带底层异常，仅凭响应无法区分 SMTP 失败与内部失败"。这是面向运维的正常错误归因文档，不泄露可利用信息(无端点、参数、鉴权绕过线索)，攻击面增益可忽略；仅作信息披露面的提示。同时确认：新增文本不触发现有文档门禁断言——seo-docs.test.mjs:1699/1942 硬编码的 curl 安全写法计数 33(新增内容无 curl 块)、mcp-tools.test.mjs:210 的 "N tools" 禁令、webhook-normative.test.mjs 的章节存在性检查均不受影响。
建议：无需动作；如服务端后续补齐 /lease、/release 的异常日志，记得同步修订该段。

三、mimosa findings 核实

扫描(depth=deep)报告 0 findings、0 business-logic hypotheses,依赖扫描 477 包完成且无发现，故无逐条判定条目(确认 0 / 误报 0 / 存疑 0)。抽查补充：diff 两个文件均非代码路径；i18n-en-baseline.json 的哈希校验逻辑(checkEnBaseline)自带样式表路径穿越防护(scripts/i18n-check.mjs:315-319),且该逻辑为存量代码、本次未改动。

四、合并结论

文档类 PR,改动内部自洽、不触碰代码/依赖/CI,所有观察点均为提示级。建议合并(附带 P3-1 的跨仓库发布顺序确认)。

VERDICT: P0=0 P1=0 P2=0 P3=3 MERGE=yes

_{由 zcode-review-gate 自动审查 · 写工具物理禁用 · 同一 head 不重复审}

tizerluo · 2026-09-22T23:05:02Z

@coderabbitai review

coderabbitai · 2026-09-22T23:05:10Z

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

tizerluo · 2026-09-22T23:18:40Z

终审报 · website#92（`/v1/tasks` lease/state 变更 fallback 入公开文档）

出处：总指挥 #4585（转交 OV #330 的 docs 追加件；代码面 = 主仓 PR #334，已合 squash 8a270026）
性质：docs-only（2 文件：api.md +9、i18n-en-baseline.json +1/−1）
树 ~/orca/workspaces/website/w-330-mutation-fallback｜分支 tizerluo/330-mutation-fallback｜基线 main = 9921293
**终头 75b8b7273797**｜核验方式：FC 本人亲跑亲读 + 原始输出留痕

一、五格逐格绑终头（`75b8b7273797`）

格	结论	证据
CI `build`	✅ 26s	run `35794750310` job `106971328584`
CI `guard`	✅ 5s	run `35794750313` job `106971328760`
CI `otp-redirect-smoke`	✅ 33s	run `35794750310` job `106971328925`
Codex Local	✅ pass，P0–P3 全零（置信 0.98）	绑终头；结论「documented fallback bodies / statuses / affected mutation paths / mail-delivery behavior / logging limitations match the authoritative implementation」
ZCode	✅ pass	绑终头 `P0=0 · P1=0`；「未发现阻断问题，可以合并」
CodeRabbit	✅ 真审完成 + 零 actionable	状态 `Review completed`；摘要「No actionable comments were generated in the recent review」；绑终头（"Reviewing files that changed … between `9921293…` and `75b8b727…`"）
未解决 review thread	0（total=0）	—
mergeable	`MERGEABLE / CLEAN`	基线 = 本 PR base ⇒ 无需 rebase

⚠️ 注意本仓 CR 与别的仓不同：website 仓是 Advanced plan + 仓内 .coderabbit.yaml ⇒ 具备逐行审能力（不是 Free plan 的结构性上限、也不是限流）⇒ 本单不适用任何降链/豁免，CR 为真审零 actionable。

二、闸意见逐条处置（两条 P1 我对服务端源码逐条亲核 = 全真）

闸	级别	报告	FC 亲核（`openagentemail/openagentemail@8a270026`）	处置
Codex	P1	「Remove the unreachable `task_leases_disabled` fallback example」— 租约关闭时四条 lease 路由在调用 service 之前就返回 `409 task_leases_disabled`，故没有任何已文档化路径会以 `502 task_operation_failed` 暴露它	真：`packages/api/src/routes/tasks.ts:364/399/441/476` 均为 `if (!leasesEnabled()) return c.json({error:'task_leases_disabled'}, 409)`；`decision`/`state` 分支无该码	已修：删去该例（改「also covers unmapped/internal failures.」）
Codex	P1	「Do not promise causal attribution from every mutation warning」— `/lease`(renew) 与 `/release` 的未映射失败只打静态文案并丢弃异常码，故「`console.warn` 是主要归因手段」对这两条路由不成立	真：`:426 console.warn('[task] renew failed')`、`:468 console.warn('[task] release failed')`（其后才 502）	已修：监控注记补限定「except `/lease`(renew) 与 `/release` … 单凭响应无法区分 SMTP 失败与内部失败」
ZCode	P3×3	术语/措辞提示	认	记档（不阻断）

三、⚠️ 与「逐字件」的偏差声明（请复核；最小可回退）

总指挥给的逐字件里两处与实现不符；我先对源码亲核、再改（改动全在同一表/注记内，回退即一行）：

删掉不可达的 task_leases_disabled 例子（原句把它当 502 fallback 的原因 —— 实为 409 前置守卫）⇒ 会误述公开错误契约；
监控注记补限定（原句「console.warn 是主要归因手段」对 /lease(renew)、/release 不成立）。

若你要保留原文，一句话我改回（我判不该保留：两处都有源码实证，且 Codex 判 P1；#4585 你已复核过 website#90 的同款处置）。

四、本地核（FC 亲跑；权威格 = CI）

检查	结果
`npm ci`（worktree 内精确装依赖）+ `npx astro build`	成功
`node --test tests/{seo-docs,llms-txt,mcp-tools}.test.mjs`	17 pass / 0 fail
`npm run postbuild`（全套 rendered）	全绿 + `en-baseline 5-part invariant check PASSED`
`i18n-en-baseline.json` 同轮重算	两轮均恰 1 行（`bodySha256`：`0ee6108e…` → `ce1d3b8b…` → `226db8eb…`；其余条目逐字节相同）
范围	未动 `public/llms.txt`（已核无相关串）、未动主仓 `docs/api.md` 指针

纪律留痕：本仓基线是「渲染后 en HTML 逐页 sha256」冻结件 ⇒ 重算必须在锁文件精确重建的环境里做（worktree 内 npm ci 后重建再算）；本次一次即恰 1 行（对照 website#90 的教训：拿主 checkout node_modules 软链算出的 97 行是假漂移）。

五、请求

准并（你亲核亲合；无需 Closes）。
§三两处偏差照准或令回退（我建议照准，理由见上）。
顺带一行：CR 于本仓是 Advanced + 仓内配置的逐行真审，与 hosted-ops 侧的 Free plan 形态不同 —— 建议在台账里记一笔，免得后续误套降链口径。

tizerluo merged commit e253250 into main Sep 22, 2026
4 checks passed

tizerluo deleted the tizerluo/330-mutation-fallback branch September 23, 2026 00:12

tizerluo mentioned this pull request Sep 23, 2026

docs(api): 两条已映射 409 mutation 错误入公开文档（来源 OV #336 / #337） #93

Merged

Conversation

tizerluo commented Sep 22, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What / why

落点（内容锚定，非行号）

内容（逐字照贴）

范围

本地核（FC 亲跑；权威格 = CI）

Summary by CodeRabbit

Uh oh!

tizerluo commented Sep 22, 2026

Uh oh!

coderabbitai Bot commented Sep 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Sep 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Uh oh!

tizerluo commented Sep 22, 2026

ZCode Review Gate：✅ pass

PR 安全审查报告

一、汇总

二、改动内容定性

三、问题清单(均为 P3 提示,不阻断)

四、mimosa findings 核实

Uh oh!

tizerluo commented Sep 22, 2026

Codex Local Review：⚠️ concerns

P1 · [P1] Remove the unreachable task_leases_disabled fallback example

P1 · [P1] Do not promise causal attribution from every mutation warning

Uh oh!

tizerluo commented Sep 22, 2026

Codex Local Review：✅ pass

Uh oh!

tizerluo commented Sep 22, 2026

ZCode Review Gate：✅ pass

PR 安全审查报告

一、汇总

二、逐条详述(P3)

P3-1 文档描述的服务端行为在本仓库不可验证，存在跨仓库同步依赖

P3-2 bodySha256 更新的正确性依赖 CI 构建门禁，只读审查无法复算

P3-3 文档新增内容披露服务端日志/错误归因的内部实现细节

三、mimosa findings 核实

四、合并结论

Uh oh!

tizerluo commented Sep 22, 2026

Uh oh!

coderabbitai Bot commented Sep 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tizerluo commented Sep 22, 2026

终审报 · website#92（/v1/tasks lease/state 变更 fallback 入公开文档）

一、五格逐格绑终头（75b8b7273797）

二、闸意见逐条处置（两条 P1 我对服务端源码逐条亲核 = 全真）

三、⚠️ 与「逐字件」的偏差声明（请复核；最小可回退）

四、本地核（FC 亲跑；权威格 = CI）

五、请求

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

tizerluo commented Sep 22, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Sep 22, 2026 •

edited

Loading

coderabbitai Bot commented Sep 22, 2026 •

edited

Loading

P1 · [P1] Remove the unreachable `task_leases_disabled` fallback example

P3-2 `bodySha256` 更新的正确性依赖 CI 构建门禁，只读审查无法复算

coderabbitai Bot commented Sep 22, 2026 •

edited

Loading

终审报 · website#92（`/v1/tasks` lease/state 变更 fallback 入公开文档）

一、五格逐格绑终头（`75b8b7273797`）