patchwarden 1.5.0 → 1.6.1

package/docs/agentseal-integration.md

@@ -0,0 +1,150 @@
+# AgentSeal 集成模式
+
+> 本文基于 v1.5.1 源码编写；安装时请使用已验证发布的 <published-version>。
+> 说明：本文描述的是 PatchWarden 与 AgentSeal 的集成模式建议，**不是** AgentSeal 的官方功能。
+> AgentSeal 是独立的 agent 安全检测项目，本文不声称任何官方集成关系。
+
+## AgentSeal 是什么
+
+AgentSeal 是面向 AI 编程 Agent 的安全检测工具，主要职能包括：
+
+- 识别项目级安全策略（哪些文件可改、哪些命令可执行、哪些路径禁止访问）。
+- 对 Agent 的执行行为进行策略比对与违规告警。
+- 为 Agent 工作流提供可配置的策略层。
+
+AgentSeal 侧重于“策略声明与检测”，本身不强制执行；
+PatchWarden 侧重于“强制执行与证据收集”。两者互补。
+
+## 集成定位
+
+```
+AgentSeal:   声明策略 → 检测违规 → 告警
+                            ↓ 策略对齐
+PatchWarden: 接收任务 → 强制执行 → 证据收集
+```
+
+- AgentSeal 负责**策略侧**：识别并校验项目安全策略。
+- PatchWarden 负责**执行侧**：在执行任务时强制遵守策略，并产出可审计证据。
+
+## 配置文件关系
+
+PatchWarden 与 AgentSeal 共享两个关键配置文件，但职责不同：
+
+| 文件 | AgentSeal 角色 | PatchWarden 角色 |
+| --- | --- | --- |
+| `.patchwarden/config.json` | 读取并识别 PatchWarden 运行配置 | 运行时核心配置入口 |
+| `project-policy.json` | 校验项目策略合规性 | 执行时强制遵守的 allowed paths / commands |
+
+### `.patchwarden/config.json`
+
+PatchWarden 的运行配置，典型字段包括：
+
+```json
+{
+  "workspaceRoot": "D:\\repos\\my-project",
+  "agents": ["opencode", "codex"],
+  "evidencePackVersion": 2,
+  "safeResult": { "maxBytes": 4096 }
+}
+```
+
+AgentSeal 可读取此文件以了解 PatchWarden 的 workspace 边界与 agent 注册情况，
+用于检测配置是否与项目策略一致。
+
+### `project-policy.json`
+
+项目级安全策略，声明允许的路径与命令：
+
+```json
+{
+  "allowedPaths": ["src/**", "test/**"],
+  "allowedCommands": ["npm.cmd test", "npm.cmd run build", "git status"],
+  "blockedFiles": [".env", ".env.*", "id_rsa", "cookies.db"],
+  "scopeRules": { "enforceDeclaredFiles": true }
+}
+```
+
+- AgentSeal 将此文件作为策略基准进行检测。
+- PatchWarden 将此文件作为执行时的强制约束。
+- 两者读取同一份文件，保证“检测基准”与“执行约束”一致。
+
+## 集成流程示例
+
+### 1. 编写项目安全策略
+
+在仓库根目录放置 `project-policy.json`（与 `.patchwarden/config.json` 配合）：
+
+```json
+{
+  "allowedPaths": ["src/**", "docs/**"],
+  "allowedCommands": ["npm.cmd run build", "npm.cmd test"],
+  "blockedFiles": [".env", "*.key", "*.pem"],
+  "scopeRules": { "enforceDeclaredFiles": true }
+}
+```
+
+### 2. AgentSeal 识别并校验策略
+
+```powershell
+# AgentSeal 扫描项目，识别 .patchwarden/config.json 与 project-policy.json
+# 输出策略合规报告
+agentseal scan --project D:\repos\my-project
+```
+
+AgentSeal 输出策略快照，作为后续违规比对的基准。
+
+### 3. PatchWarden 执行任务时强制遵守
+
+当 MCP 客户端通过 PatchWarden 执行任务时：
+
+```powershell
+# PatchWarden 启动时加载 project-policy.json
+# 执行任务时对每条命令与文件改动进行策略校验
+```
+
+PatchWarden 的强制行为：
+
+- 命令必须在 `allowedCommands` 列表中（精确匹配）。
+- 文件改动必须在 `allowedPaths` 范围内。
+- 命中 `blockedFiles` 的访问被立即阻断。
+- `enforceDeclaredFiles` 为 true 时，未声明文件的改动触发范围违规检测。
+
+### 4. 证据对齐与回溯
+
+任务完成后，PatchWarden 导出 Evidence Pack v2：
+
+```powershell
+# 产物位于 .patchwarden/evidence-packs/<lineage_id>/
+```
+
+其中：
+
+- `verify.json` 记录每轮迭代的策略校验结果，可与 AgentSeal 的策略快照对齐。
+- `risk.json` 聚合执行中识别的风险项。
+- `redactions.json` 记录已脱敏内容，证明未泄露敏感信息。
+
+AgentSeal 可读取这些文件，作为策略执行情况的回溯证据。
+
+## 安全边界
+
+- PatchWarden 不依赖 AgentSeal 运行。即使 AgentSeal 未启动，
+  PatchWarden 仍会按 `project-policy.json` 强制执行策略。
+- AgentSeal 不修改 PatchWarden 的运行时行为，仅提供策略检测与告警。
+- 两者共享 `project-policy.json` 作为单一策略真源，避免策略漂移。
+- 若 AgentSeal 检测到策略与 PatchWarden 配置不一致，
+  应由人工修正配置，不应自动放宽 PatchWarden 的约束。
+
+## 注意事项
+
+- 本集成模式不修改 AgentSeal 的任何行为，仅在配置与流程上配合。
+- `project-policy.json` 的字段定义以 PatchWarden 实际加载逻辑为准，
+  AgentSeal 侧应按相同 schema 解析。
+- 如策略允许读取 `.env` 等敏感文件，PatchWarden 仍会按安全契约阻断，
+  此时需要重新设计策略以避免触碰敏感资源。
+
+## 相关文档
+
+- `docs/threat-model.md`：PatchWarden 安全契约与敏感文件清单。
+- `docs/evidence-pack-schema.md`：Evidence Pack v2 文件结构。
+- `docs/why-patchwarden.md`：PatchWarden 定位与动机。
+- 上游草稿 PR：https://github.com/getagentseal/agentseal/pull/35

package/docs/architecture.md

@@ -0,0 +1,23 @@
+# PatchWarden Architecture
+
+PatchWarden 是一个本地优先的 MCP（Model Context Protocol）安全桥接器，通过 5 种运行角色（MCP Server / Watcher / Agent / Control Center / Desktop App）协同，为 AI agent 提供任务编排、安全守卫、变更证据收集与审计能力。
+
+## 详细文档
+
+- [Code Wiki](./CODE_WIKI.md) —— 完整项目架构、模块职责、关键类与函数说明、依赖关系、运行方式、现有缺陷
+- [Threat Model](./threat-model.md) —— 安全威胁模型与防护设计
+- [Control Center](./control-center/README.md) —— Control Center HTTP 管理界面文档
+- [Desktop App](./desktop-app.md) —— Electron 桌面应用文档
+- [Direct Session Workflow](./direct-session-workflow.md) —— Direct 模式会话工作流
+- [Task Safe Review Workflow](./task-safe-review-workflow.md) —— 任务安全审查工作流
+
+## 一致性与资源边界
+
+- `.patchwarden/` 只是证据存储位置，不是敏感路径豁免区；敏感文件名在任意目录深度都阻断。
+- Goal 状态变更由跨进程 mutation lock 串行化并原子落盘；非空 Goal 的子目标全部 accepted 后自动转为 `completed`。
+- 子目标任务以 Goal 保存的 `repo_path` 为权威并拒绝 mismatch；worktree create/merge/discard 共享该仓库的 lifecycle lock。
+- task diff/summary/log tail 采用有界读取，`audit_task` 对文档数量和总字节设置预算，持续 invocation/reconcile 日志采用锁内有界追加并明确标记截断。
+
+## 历史版本
+
+历史架构文档与阶段性设计已归档至 [archive/](./archive/)。

package/docs/control-center/README.md

@@ -15,13 +15,13 @@ PatchWarden has three control layers:
 From the repository root:
 
 ```powershell
-.\PatchWarden-Desktop.cmd
-.\PatchWarden-Control.cmd
-.\PatchWarden-Control-Tray.cmd --foreground
+.\scripts\launchers\PatchWarden-Desktop.cmd
+.\scripts\launchers\PatchWarden-Control.cmd
+.\scripts\launchers\PatchWarden-Control-Tray.cmd --foreground
 .\PatchWarden.cmd status all
 ```
 
-Use `PatchWarden-Control.cmd` for normal desktop use. Use the tray when you only
+Use `scripts\launchers\PatchWarden-Control.cmd` for normal desktop use. Use the tray when you only
 need quick controls. Use `PatchWarden.cmd` when you need explicit CLI output or
 automation-friendly commands.
 

package/docs/dashboard-overview.md

@@ -0,0 +1,86 @@
+# Dashboard 概览
+
+> 本文基于 v1.5.1 源码编写；安装时请使用已验证发布的 <published-version>。
+> 入口：`scripts\launchers\PatchWarden-Control.cmd` 或托盘菜单中的 "Open Control Center"。
+
+## 目的
+
+PatchWarden Dashboard（Control Center）把本地 Agent 工作流从“只能看的状态面板”
+升级为“可操作的工作流控制中心”。所有操作默认走 safe 摘要接口，有界日志、diff、
+test log 仅在折叠的“高级区”按需加载，不改变 PatchWarden 的安全边界。
+
+## 核心概念
+
+- **Safe-first**：默认展示 `safe_result` / `safe_audit` / `safe_test_summary` /
+  `safe_diff_summary` / `safe_direct_summary` 等有界摘要，避免直接渲染完整产物。
+- **Repo selector**：顶部下拉列出 workspace 根目录及其一级项目目录（带 package.json
+  版本标记）。切换 repo 会刷新 Project Policy、Release、Recent Tasks、Lineage、
+  Evidence Pack、Direct Sessions。
+- **Health Score**：综合 watcher / tunnel / agents / stale 任务 / 失败任务 /
+  policy 有效性 / release readiness / direct profile 状态计算出的健康分，
+  状态为 `healthy` / `warning` / `degraded` / `blocked`。
+- **Bound to lineage**：Evidence Pack 与 Lineage 绑定，只有 `run_task_loop` 产生
+  lineage 后才能导出证据包。
+
+## 主要页面
+
+| 页面 | 主要内容 |
+| --- | --- |
+| Dashboard | Repo selector、Health Score、服务状态、Release 卡片、Project Policy、Lineage、Evidence Pack、Stale 任务提示、最近任务列表、系统状态（含 Copy diagnostics） |
+| Tasks | 任务列表，支持按 repo_path / status / acceptance_status / warning_type / agent / date range 过滤 |
+| Task Detail | safe 摘要默认视图 + 折叠的高级区（配置上限内的 result / diff / test_log） |
+| Direct Sessions | 按 active / finalized / audited / expired 分组的 Direct 会话 |
+| Audit / Warnings | 按 warning 类型聚合的诊断页 |
+| Workspace | workspace 一级目录与项目列表 |
+| Logs | Core / Direct / Watcher / Control Center 日志尾部 |
+
+## 推荐工作流
+
+1. 在 Dashboard 顶部选择目标 repo。
+2. 查看 Health Score，确认系统健康（`healthy` 或 `warning`）。
+3. 在 Release 卡片确认发布就绪状态；若 `blocked`，按 `blocked_reason` 修复。
+4. 在最近任务列表点击 `safe_result` 快捷查看任务摘要。
+5. 打开 Task Detail 进行 safe-first 验收（详见
+   [task-safe-review-workflow.md](task-safe-review-workflow.md)）。
+6. 使用 Lineage Detail 查看 `run_task_loop` 成功/失败原因（详见
+   [lineage-evidence-pack-workflow.md](lineage-evidence-pack-workflow.md)）。
+7. 验收完成后导出 Evidence Pack。
+8. Direct 会话用于独立验证，完成后 finalize + audit（详见
+   [direct-session-workflow.md](direct-session-workflow.md)）。
+9. 遇到问题时点击 **Copy diagnostics** 复制诊断信息，发给 ChatGPT / Codex / opencode 排查。
+
+## 卡片速查
+
+### Release 卡片
+
+显示 package name、version_source、version、version_consistent、required_commands
+（每条命令的 allowed + blocked_reason）、commands_blocked_count、
+ready/unknown/blocked 状态及 blocked 原因。`next_action` 会引导使用
+`release_check` 模板。
+
+### Stale 任务卡片
+
+不再是简单的“过期任务列表”，而是可解释、可操作的健康建议卡片，包含 task_id、
+repo_path、status、error、人类可读的 explanation、next_action，以及快捷操作
+（查看详情、复制 task_id、隐藏、重建任务）。
+
+### Project Policy 卡片
+
+只读展示 auto_cleanup、protected_paths 数量、high_risk_commands 数量、
+release_mode 摘要。
+
+## 安全边界
+
+- 所有 safe 接口返回有界摘要，不包含完整日志、stdout/stderr tail、diff、密钥内容。
+- 有界 result / diff / test_log 只在折叠的高级区按需加载，永不自动加载。
+- Project Policy 卡片只读，不能从 UI 修改策略。
+- 不执行远程写操作（npm publish / git push / git tag / gh release）。
+- Diagnostics 输出经过 `redactSensitiveContent` 脱敏。
+
+## 相关 API 端点
+
+- `GET /api/workspace/repos` — Repo selector 数据源
+- `GET /api/diagnostics` — Copy diagnostics 数据源
+- `GET /api/warnings` — Warnings 页数据源
+- `GET /api/release/status` — Release 卡片数据源
+- `GET /api/tasks/stale` — Stale 任务卡片数据源（含 explanation / next_action）

package/docs/demo.md

@@ -3,6 +3,14 @@
 This is a privacy-safe demo flow for GitHub. It uses placeholder workspace
 names and avoids real tunnel IDs, account names, API keys, or local user paths.
 
+## Animated OSS Demo
+
+This scripted GIF summarizes the public maintainer workflow without showing
+private accounts, real API keys, real task history, or local user paths. It is a
+demo asset, not third-party adoption evidence.
+
+![PatchWarden OSS demo](assets/patchwarden-oss-demo.gif)
+
 ## Demo: ChatGPT Lists A Workspace
 
 Prompt in ChatGPT with the PatchWarden connector selected:

package/docs/desktop-app.md

@@ -0,0 +1,175 @@
+# PatchWarden Windows Desktop
+
+PatchWarden Desktop is the installable Windows shell for the existing local
+Control Center. It does not add a remote shell or replace the MCP server. The
+desktop process starts the same loopback-only Control Center, displays it in an
+isolated Electron window, and keeps quick controls in the system tray.
+
+## Install
+
+1. Download `PatchWarden-Setup-<version>-x64.exe` (installed) or
+   `PatchWarden-Portable-<version>-x64.zip` (no install), plus
+   `PatchWarden-Desktop-SHA256SUMS.txt` from the matching GitHub Release.
+2. Verify the SHA256 value before running the installer.
+3. Install for the current Windows user. Administrator access is not required.
+4. Select a dedicated workspace, review detected local CLIs and models, and let
+   the read-only doctor finish.
+
+## First-run routes
+
+The first screen asks whether PatchWarden will be used through **ChatGPT
+Tunnel** or **Local MCP**. Local MCP can skip Platform Tunnel configuration.
+For ChatGPT, use the same eight steps shown in both READMEs:
+
+1. Confirm Platform Tunnel access and enable developer mode for the target ChatGPT workspace.
+2. Create a Tunnel in [Platform Tunnel settings](https://platform.openai.com/settings/organization/tunnels) and associate that workspace.
+3. Detect or choose an existing `tunnel-client.exe` in Desktop Settings.
+4. Enter the Core Tunnel ID and dedicated Tunnel runtime API key used as `CONTROL_PLANE_API_KEY`. It is not an application `OPENAI_API_KEY`.
+5. Configure and test the environment, direct, or credential-free HTTP/HTTPS/SOCKS5 (Mixed) proxy.
+6. Configure the Core profile, run `tunnel-client doctor --explain --json`, and start Core. The runtime key travels from the isolated renderer to the main process over bounded IPC, then to a one-time PowerShell process over stdin. It is DPAPI-encrypted only after doctor succeeds and is never placed in repository config, HTTP APIs, command arguments, logs, or returned objects.
+7. Confirm Tunnel ready, Watcher healthy, and the fixed 26-tool `chatgpt_core` catalog on Getting Started.
+8. In ChatGPT **Settings → Plugins**, create a developer-mode app, choose the Tunnel, reconnect, open a new chat, and call `health_check`.
+
+The current term is **developer-mode app / Plugins**; older releases called it
+a Connector. Direct remains optional and must be enabled explicitly. Start All
+starts Core and reports Direct as skipped while Direct is disabled; Stop All
+still covers both profiles.
+
+The setup flow searches `PATH`, current-user application directories, and a
+bounded area next to the selected workspace for `tunnel-client.exe`. If it is
+not found, continue into the read-only console and open **Settings > MCP and
+tunnel**. Use **Detect** or the dedicated file picker; it accepts only an
+existing file named `tunnel-client.exe`. PatchWarden never downloads or runs
+new software automatically. Download the Windows x64 build only from the
+trusted release source named by your tunnel provider and compare its SHA256
+with that release before selecting it.
+
+Prerequisites are Windows x64, Node.js 18 or newer, and the configured
+tunnel-client used by the existing Core/Direct launcher chain. Electron runs
+the desktop window and Control Center child, but does not replace those runtime
+requirements.
+
+The first unsigned desktop release may show Windows SmartScreen. Verify the
+checksum and GitHub Release source before choosing to continue. No updater or
+login startup entry is installed in v1.
+
+## Local agents and models
+
+Desktop supports Codex, OpenCode, Claude Code, Gemini CLI, GitHub Copilot CLI,
+Qwen Code, Kimi Code, and Aider. Settings detects only verified native
+executables or known npm package entry points and never launches Windows shell
+shims through a command shell.
+
+Model discovery reads only allowlisted model fields from each agent's normal
+JSON/JSONC, TOML, or YAML settings. It does not read `.env`, API keys, browser
+state, provider secrets, or session history. Online model listing is never run
+automatically; the user must select the refresh control for an agent that
+supports a bounded model-list command. Choosing **Follow agent default** omits
+the model argument so the agent retains its own precedence rules.
+
+## Local state
+
+- Desktop config: `%LOCALAPPDATA%\PatchWarden\patchwarden.config.json`
+- Desktop preferences: `%LOCALAPPDATA%\PatchWarden\desktop-preferences.json`
+- Desktop startup log: `%LOCALAPPDATA%\PatchWarden\desktop.log`
+- Control Center logs: `%LOCALAPPDATA%\patchwarden\control-center`
+- Tasks and evidence remain below the selected workspace.
+
+If `PATCHWARDEN_CONFIG` points to a valid config, the desktop app uses that path
+instead of creating the LocalAppData config. Config changes are written
+atomically and the previous file is retained as a timestamped `.bak-*` copy.
+Uninstalling the app does not remove config, tasks, evidence, or workspace data.
+
+## Runtime behavior
+
+- The app binds only to `127.0.0.1:8090` and reuses an existing verified
+  PatchWarden Control Center on that address.
+- A foreign listener on port 8090 is reported; the app never kills it or takes
+  the port.
+- Closing the window hides it to the tray by default. `Exit desktop app` stops
+  only the Control Center child owned by that app process.
+- Desktop-owned utility and PowerShell children receive a minimal runtime and
+  proxy environment. Provider variables require an explicit Agent allow-list,
+  while Control/Tunnel owner credentials are always removed. Windows
+  PowerShell and `where.exe` are resolved from the system directory rather than
+  the selected workspace or its current directory.
+- Backend restarts are serialized. A restart waits for the exact owned child to
+  emit `exit` (or reach a bounded timeout), and a configuration change received
+  during an active restart schedules one further restart instead of racing it.
+- `Stop all and exit` explicitly requests the existing bounded stop action for
+  Core/Direct before closing.
+- Start/restart succeeds only after the selected tunnel health endpoint is
+  ready and the Core watcher heartbeat is healthy. Early supervisor exits and
+  timeouts are reported with a reason and next steps.
+- Background start uses `run-background-supervisor.ps1` so the lifecycle API
+  returns without holding the long-running supervisor's output handles. The
+  wrapper writes bounded `supervisor.stdout.log` and `supervisor.stderr.log`
+  files while `supervisor-status.json` records only PID, state, timestamps, and
+  log paths.
+- The legacy CMD, PowerShell tray, and browser Dashboard remain supported.
+
+## MCP and proxy settings
+
+The desktop settings page can enable the Direct profile and configure tunnel
+proxy behavior. Direct remains disabled until the user explicitly enables it.
+
+- **Use environment proxy** inherits `HTTPS_PROXY` when it is present.
+- **No proxy** removes proxy variables for the launcher-owned tunnel process.
+- **Manual proxy** accepts only `http`, `https`, or `socks5` URLs without an
+  embedded username or password.
+
+Core and Direct can share one proxy definition or use separate definitions.
+PatchWarden does not store proxy credentials in URLs or logs.
+
+## Build from source
+
+Run from the repository in Windows PowerShell:
+
+```powershell
+npm.cmd ci
+npm.cmd run build
+npm.cmd install --prefix desktop --cache .\.npm-cache
+npm.cmd run desktop:test
+npm.cmd run desktop:preflight
+npm.cmd run desktop:package
+```
+
+Artifacts are written below `release\desktop`. Desktop dependencies remain in
+the private `desktop` package and are not included in the `patchwarden` npm
+package.
+
+Desktop staging must include `scripts/checks/mcp-manifest-check.js` and the
+root package-lock production dependency closure below `resources/core/node_modules`.
+Validate the unpacked runtime from a directory outside the repository so it
+cannot accidentally resolve dependencies from the developer checkout.
+
+`npm.cmd run desktop:preflight` automates that isolated validation and writes a
+privacy-bounded receipt in a unique `release/desktop-preflight-*` directory.
+The receipt records the branch, commit, dirty-state hashes, toolchain versions,
+check durations, package file count, runtime manifest digest, unpacked
+executable digest, and UI smoke result. It stores no diff content, credentials,
+configuration values, or browser state. The smoke process uses temporary
+`LOCALAPPDATA` / `APPDATA`, a nonexistent isolated config, and launcher-owned
+processes only.
+
+Viewport DOM metrics, page readiness, and the single-instance result are hard
+smoke gates. Electron screenshots are best-effort evidence because Windows
+graphics capture can be unavailable in CI sessions; capture failures are
+counted in the receipt without crashing Desktop. Local visual acceptance can
+pass `--require-screenshots` to `desktop/scripts/smoke-unpacked.mjs`, or use
+`--no-capture` while an external UI automation tool owns Windows Graphics
+Capture.
+
+For a release candidate, run `npm.cmd run desktop:preflight:release`. It rejects
+dirty worktrees. The regular preflight remains available for validating an
+intentional local working-tree baseline before it is committed.
+
+## Release checklist
+
+1. From a clean checkout, run `npm.cmd run desktop:preflight:release`, then the
+   full core validation chain and `npm.cmd run desktop:package`.
+2. Install and uninstall on a clean Windows x64 environment without elevation.
+3. Verify first-run setup, tray behavior, restart, explicit exit, and retained
+   user data after uninstall.
+4. Compare the installer SHA256 with the generated checksum file.
+5. Publish GitHub assets manually. npm publication remains a separate action.

package/docs/direct-session-workflow.md

@@ -0,0 +1,98 @@
+# Direct 会话工作流
+
+> 本文基于 v1.5.1 源码编写；安装时请使用已验证发布的 <published-version>。
+> 相关页面：Direct Sessions
+
+## 目的
+
+Direct 会话（Direct Session）是 PatchWarden 提供给 ChatGPT 等 Direct agent 的
+独立验证通道：在 watcher 守护的任务流程之外，对一个 repo 做独立的文件查看、
+命令执行和验证。Direct 不会自动 patch 文件、不会绕过命令守卫，所有操作仍受
+workspace 隔离、敏感路径拦截和审计约束。
+
+## 核心概念
+
+- **Direct session**：绑定到某个 repo_path 的一次独立会话，有 session_id、
+  title、created_at、expires_at。
+- **会话状态分组**：`active` / `finalized` / `audited` / `expired`。
+  expired 默认折叠。
+- **safe_direct_summary**：Direct 会话的有界摘要，包含 changed_files_total、
+  verification status，不含完整 diff 或 stdout。
+- **finalize**：把 active 会话标记为已完成（finalized），冻结变更记录。
+- **audit**：对 finalized 会话做审计，生成审计摘要（audited 状态）。
+- **verification bundle**：`run_direct_verification_bundle` 一次性跑测试 + diff +
+  验收检查的成组操作。
+
+## 生命周期
+
+### 1. 创建 Direct 会话
+
+通过 Direct profile 的 MCP 工具创建会话（如 `start_direct_session`），指定
+repo_path 和 title。会话会进入 `active` 状态，并记录 created_at 与 expires_at。
+
+### 2. 在 Direct Sessions 页查看
+
+Direct Sessions 页按状态分组展示所有会话：
+
+- **active** — 进行中
+- **finalized** — 已 finalize，待 audit
+- **audited** — 已完成审计
+- **expired** — 已过期（默认折叠）
+
+每个会话显示 session_id、repo_path、title、created_at、expires_at、finalized、
+audited、changed_files_total、verification status。
+
+### 3. 执行独立验证
+
+在 active 会话中，使用 Direct 工具进行独立验证：
+
+- 查看文件（受敏感路径拦截）
+- 执行允许的命令（受白名单约束）
+- 调用 `run_direct_verification_bundle` 一次跑完测试 + diff + 验收检查
+
+或直接在 Direct Sessions 页点击 **run_direct_verification_bundle** 快捷操作。
+
+### 4. 查看 safe 摘要
+
+点击 **safe_direct_summary** 查看会话的有界摘要：
+
+- changed_files_total
+- verification status
+- 是否命中受保护路径
+
+> 完整 diff 与 stdout 不会自动加载，仅在高级区按需查看。
+
+### 5. Finalize 会话
+
+验证完成后点击 **safe_finalize_direct_session**（或调用
+`POST /api/direct-sessions/:sessionId/finalize`），把会话标记为 `finalized`，
+冻结变更记录，准备进入审计。
+
+### 6. Audit 会话
+
+对 finalized 会话点击 **safe_audit_direct_session**（或调用
+`POST /api/direct-sessions/:sessionId/audit`），生成审计摘要，会话进入
+`audited` 状态。审计摘要可用于归档或与 lineage 的 direct_verification 对照。
+
+### 7. 处理过期会话
+
+超过 expires_at 的会话进入 `expired` 状态，默认折叠。可执行：
+
+- **copy session_id** — 复制 id 用于追溯
+- **hide expired** — 调用 `POST /api/direct-sessions/:sessionId/hide` 隐藏
+
+## 安全边界
+
+- Direct 会话仍受 workspace 隔离、命令白名单、敏感路径拦截约束。
+- Direct 不会自动 patch 文件，所有写操作都需要显式确认。
+- safe 摘要不含完整 diff / stdout / 密钥内容。
+- finalize 与 audit 只修改本地会话状态，不触发远程写。
+- Direct 不执行 `npm publish` / `git push` / `git tag` / `gh release`。
+
+## 相关 API 端点
+
+- `GET /api/direct-sessions` — 会话列表（按状态分组）
+- `GET /api/direct-sessions/:sessionId` — 单个会话详情
+- `POST /api/direct-sessions/:sessionId/finalize` — finalize 会话
+- `POST /api/direct-sessions/:sessionId/audit` — audit 会话
+- `POST /api/direct-sessions/:sessionId/hide` — 隐藏过期会话