docs: document the Session Workflow setting

[DragonnZhang]

What this PR does

Adds the missing user-facing reference for the experimental Session Workflow setting, including its default-off state, live-update behavior, Web Shell presentation changes, and observational boundary.

Why it's needed

The setting is shipped in the configuration schema and exposed through daemon workspace settings, but users could not discover its key or behavior in the configuration reference. Documenting it makes the opt-in path and its limits explicit without implying a new execution or approval system.

Reviewer Test Plan

How to verify

Compare the documented key, boolean type, default value, and restart behavior with the configuration schema. In the daemon Web Shell, enable the setting and confirm that the Workflow DAG appears and the existing plan mode is labeled Plan & Review; disable it and confirm that ordinary Plan and Todo behavior remains unchanged.

The focused configuration-schema suite passed 40 tests. The focused Web Shell application, mode-selector, approval-dialog, and Todo suites passed 423 tests. The repository build, workspace typecheck, formatting check, and diff whitespace check also passed.

Evidence (Before & After)

N/A — documentation-only change.

Tested on

OS	Status
🍏 macOS	✅ tested
🪟 Windows	⚠️ not tested
🐧 Linux	⚠️ not tested

Environment (optional)

macOS 27.0 on arm64, Node.js 24.18.0, and npm 11.16.0 in a local worktree without sandboxing.

Risk & Scope

• Main risk or tradeoff: The description could become stale if the experimental presentation or rollout boundaries change; every claim was checked against the current schema, design contract, implementation, and focused tests.
• Not validated / out of scope: Windows and Linux were not tested locally, and no browser-driven visual test was performed. README, runtime behavior, and other documentation areas are unchanged.
• Breaking changes / migration notes: None.

Linked Issues

N/A.

中文说明

本 PR 做了什么

补充实验性 Session Workflow 设置缺失的用户参考说明，包括默认关闭状态、无需重启即可生效、Web Shell 展示变化，以及仅观察不调度的边界。

为什么需要

该设置已经随配置 schema 发布，并通过 daemon workspace 设置暴露，但用户无法在配置参考中找到它的键名或行为。补充文档可以明确启用方式和限制，同时避免让人误以为它引入了新的执行或审批系统。

Reviewer 测试计划

如何验证

将文档中的键名、布尔类型、默认值和重启行为与配置 schema 逐项比较。在 daemon Web Shell 中启用该设置，确认 Workflow DAG 出现，且现有 plan 模式显示为 Plan & Review；关闭后，确认普通 Plan 与 Todo 行为保持不变。

聚焦的配置 schema 测试套件有 40 个测试通过。聚焦的 Web Shell 应用、模式选择器、审批对话框和 Todo 测试套件有 423 个测试通过。仓库构建、workspace 类型检查、格式检查和 diff 空白检查也均通过。

前后证据

N/A——仅文档改动。

测试平台

OS	状态
🍏 macOS	✅ 已测试
🪟 Windows	⚠️ 未测试
🐧 Linux	⚠️ 未测试

环境（可选）

macOS 27.0（arm64）、Node.js 24.18.0、npm 11.16.0，本地 worktree，未启用 sandbox。

风险与范围

• 主要风险或取舍：如果实验性展示或发布边界发生变化，说明可能过时；本次已将每项声明与当前 schema、设计契约、实现和聚焦测试核对。
• 未验证或不在范围内：未在本地测试 Windows 和 Linux，也未执行浏览器驱动的可视测试。README、运行时行为和其他文档区域均未改动。
• 破坏性变更或迁移说明：无。

关联 Issue

N/A。

[qwen-code-ci-bot]

✅ Qwen Triage finished — CI landed green on 1cb963d and the deferred approval was posted. finalize run

✅ Qwen Triage 已完成 —— 1cb963d 的 CI 全绿，延迟审批已提交。查看 finalize 运行

[qwen-code-ci-bot]

Thanks for the PR!

Template looks good ✓

Problem: confirmed. experimental.sessionWorkflow shipped in #8391 — it exists in the configuration schema and the daemon workspace settings dialog — but nothing under docs/users/ mentions it. This is a real, observed documentation gap, not a hypothetical one.

Direction: aligned. Documenting an already-shipped experimental setting in the canonical settings reference is squarely in scope. The repo CHANGELOG records the setting's introduction (#8391), and the design contract lives in docs/design/experimental-session-plan-review.md.

Size: not applicable — docs-only, one added line in one file.

Approach: the scope is exactly right. A single table row, inserted where the schema declares the property (first in the experimental block, ahead of experimental.cron), with no unrelated changes. Nothing to cut.

Risk: no elevated risk signals.

Moving on to code review. 🔍

中文说明

感谢贡献！

模板完整 ✓

问题：已确认。experimental.sessionWorkflow 在 #8391 中引入——配置 schema 和 daemon workspace 设置对话框中都有——但 docs/users/ 下没有任何提及。这是真实存在的文档缺失，不是假设性问题。

方向：对齐。为已发布的实验性设置补充正式配置参考文档，完全在职责范围内。仓库 CHANGELOG 记录了该设置的引入（#8391），设计契约见 docs/design/experimental-session-plan-review.md。

规模：不适用——仅文档改动，单文件新增一行。

方案：范围恰好。一行表格，插入位置与 schema 中的属性声明顺序一致（experimental 块首位，位于 experimental.cron 之前），无无关改动。没有可裁剪的内容。

风险：无升级风险信号。

进入代码审查 🔍

— Qwen Code · qwen3.8-max

_{Reviewed at 1cb963dc4ef3742e43940e8ac0b9e22ea7370bf4 · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

Code review

For a docs PR the review is fact-checking every claim in the new row against the code. I verified each one:

• Key, type, default — experimental.sessionWorkflow, boolean, default false: matches the configuration schema entry exactly.
• "Show the daemon Web Shell Session Workflow DAG and present the existing plan approval mode as Plan & Review" — accurate. With the setting enabled, the Web Shell feeds the Workflow DAG inputs (planTodos/agentTools) and renames the plan entry in the approval-mode dialog and the chat editor; with it disabled those paths stay as they are today.
• "This changes presentation only: it does not add an approval mode, alter Todo execution behavior, or schedule dependencies" — matches the design contract's rollout and boundary sections ("changes presentation only; it does not register tools, alter Todo semantics, or create another approval mode"; "The Workflow remains observational").
• "Changes take effect without restarting" — correct. The schema marks this property requiresRestart: false (unlike its cron/todoStopGuard siblings), and the Web Shell derives the flag from live workspace-settings state on every render.
• Table placement — inserted first in the experimental table, matching the order the schema declares the property (before cron), consistent with how the table mirrors schema order.

No blockers. The row is accurate, uses the same language as the schema description and design doc, and carries no unrelated changes.

Test evidence — the PR's own CI

At review time the ubuntu unit suite is still running; the table below is a snapshot and the finalize job will refresh it once CI settles. precheck (format/lint gates) and the Desktop Shell job already passed. The macOS/Windows test and CLI integration jobs were skipped in this run — noting it as observed, without claiming a reason; for a single-line markdown change the ubuntu suite plus precheck are the meaningful gates. I did not re-run anything myself (fork PR code is never executed in this environment).

Final CI results for 1cb963d (auto-updated by the triage finalize job after CI completed):

Check	Conclusion
Classify PR	✅ success
Desktop Shell (ubuntu-22.04)	✅ success
Test (ubuntu-latest, Node 22.x)	✅ success
web-shell E2E Smoke (ubuntu-latest, Node 22.x)	✅ success

_{One row per check name (latest run); skipped checks omitted; failures sort first. / 每个检查名一行（取最新一次运行），省略 skipped，失败项排在最前。}

Real-scenario testing

N/A — docs-only change; there is no user-visible behavior to drive in tmux. Every factual statement in the added row was instead cross-checked against the configuration schema, the design contract, and the Web Shell implementation, as listed above.

中文说明

代码审查

对文档 PR 来说，审查就是把新增行的每项声明与代码逐一核对，均已验证：

• 键名、类型、默认值——experimental.sessionWorkflow、boolean、默认 false：与配置 schema 条目完全一致。
• "显示 daemon Web Shell Session Workflow DAG，并将现有 plan 审批模式呈现为 Plan & Review"——准确。启用后，Web Shell 会向 Workflow DAG 提供输入（planTodos/agentTools），并在审批模式对话框和聊天编辑器中重命名 plan 条目；关闭时这些路径保持现状。
• "仅改变呈现：不新增审批模式、不改变 Todo 执行行为、不调度依赖"——与设计契约的发布与边界章节一致（"只改变呈现；不注册工具、不改变 Todo 语义、不创建另一个审批模式"；"Workflow 保持观察性质"）。
• "更改无需重启即可生效"——正确。schema 将该属性标记为 requiresRestart: false（与同级的 cron/todoStopGuard 不同），且 Web Shell 在每次渲染时从实时的 workspace 设置状态推导该开关。
• 表格位置——插入 experimental 表格首位，与 schema 声明属性的顺序一致（在 cron 之前），符合表格跟随 schema 顺序的惯例。

无阻塞项。该行内容准确，措辞与 schema 描述及设计文档一致，且不夹带任何无关改动。

测试证据——PR 自身的 CI

审查时 ubuntu 单元测试仍在运行；下表为快照，CI 结束后 finalize 任务会刷新。precheck（格式/lint 门禁）与 Desktop Shell 任务已通过。macOS/Windows 测试与 CLI 集成任务在本次运行中被跳过——仅陈述观察到的事实，不断言原因；对单行 markdown 改动而言，ubuntu 套件加 precheck 是有意义的门禁。本环境不执行 fork PR 代码，因此未自行重跑任何内容。

真实场景测试

不适用——仅文档改动，没有可在 tmux 中操作的用户可见行为。新增行中的每项事实声明已按上文所列，与配置 schema、设计契约和 Web Shell 实现逐一核对。

— Qwen Code · qwen3.8-max

_{Reviewed at 1cb963dc4ef3742e43940e8ac0b9e22ea7370bf4 · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

Confidence: 5/5 — a single-line docs row with every claim cross-checked against the schema, design contract, and implementation; nothing to fix.

My independent take on "document the Session Workflow setting" would have been exactly this: one row in the settings reference's experimental table, taking type/default/restart semantics from the schema. The PR does precisely that and nothing more. The gap was real — the setting shipped in #8391 and is exposed through daemon workspace settings, yet no user-facing doc mentioned it. And the row's description isn't just plausible wording: each clause was verified — the DAG gating and Plan & Review rename in the Web Shell, the presentation-only boundary from the design contract, and the restart-free behavior (schema requiresRestart: false, with the flag derived from live workspace settings on every render). Placement follows schema property order. It's a small, accurate documentation fix that's easy to review and easy to revert — in six months nobody will curse this diff.

Verdict: approve. The ubuntu unit suite is still running on the reviewed commit, so approval is deferred until CI lands green on 1cb963dc4ef3742e43940e8ac0b9e22ea7370bf4; the finalize job will post it, or flag the PR if anything lands red.

中文说明

Confidence: 5/5 —— 单行文档新增，每项声明均已与 schema、设计契约和实现核对，无需修改。

我对"补充 Session Workflow 设置文档"的独立方案正是如此：在配置参考的 experimental 表格中加一行，类型/默认值/重启语义取自 schema。本 PR 恰好做到这一点，没有任何多余内容。缺失是真实存在的——该设置在 #8391 中发布，并通过 daemon workspace 设置暴露，但没有任何面向用户的文档提及它。这行描述也不是看似合理的措辞而已：每一句都经过验证——Web Shell 中的 DAG 门控与 Plan & Review 重命名、设计契约中"仅改变呈现"的边界、以及免重启行为（schema 中 requiresRestart: false，且该开关在每次渲染时从实时 workspace 设置推导）。插入位置遵循 schema 属性顺序。这是一个小而准确的文档修复，易审查、易回滚。

结论：批准。ubuntu 单元测试仍在所审查的提交上运行，因此批准推迟到该提交的 CI 全绿后执行；finalize 任务届时会提交批准，若有检查变红则会标记该 PR。

— Qwen Code · qwen3.8-max

_{Reviewed at 1cb963dc4ef3742e43940e8ac0b9e22ea7370bf4 · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

⚠️ Downgraded from Approve to Comment: CI still running. Reviewed.

中文说明

⚠️ 已从批准降级为评论：CI still running。 已审查。

— qwen3.8-max via Qwen Code /review (v0.21.5)

[qwen-code-ci-bot]

LGTM, looks ready to ship — CI landed green after the review. ✅

[qwen-code-ci-bot]

📄 Docs-only change — the automatic review ran at --effort medium (verified findings, no reverse audit; medium posts no inline comments). Outcome:

Review complete: pr-8554 — Comment, not posted (0 Critical, 0 Suggestion)

Reviewed head: af0fe6198440da844e1c3a46dd4eb109ba00afea. Full report in the workflow run. For a full high-effort review with inline comments, comment @qwen-code /review.

中文说明

📄 纯文档变更 —— 自动评审以 --effort medium 运行（发现已验证、无反向审计；medium 不发布行内评论），结果见上方引用行。评审的 head：af0fe6198440da844e1c3a46dd4eb109ba00afea。完整报告见 workflow 运行；如需带行内评论的完整高强度（high-effort）评审，请评论 @qwen-code /review。

[yiliang114]

LGTM — existing approval matches the current head and CI is green.

[qwen-code-ci-bot]

Released in v0.22.0.