dsh-punky-swarm 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -1,3 +1,50 @@
+## 0.4.2（2026-09-06）
+
+### 治理配置面板：Lane 过期检测与重派探针
+
+- 治理配置页新增 **Lane 过期检测** 与 **长跑超时重派探针** 两级开关：前者控制 running lane 的心跳过期扫描，后者控制长时间无 checkpoint / 活动进展 lane 的重派候选探测。开关随护栏共用同一保存通道写入运行配置，保存即热更生效，进程重启后按 runtime.json 自动对账，无需重复设置；出厂默认开（缺省即开、显式关闭才停），关闭仅停止扫描与候选探测，不改动已落盘批次 / 成员状态，重新开启后自基线恢复扫描。
+- 长跑时间窗口面板化：**超时窗口**（默认 20 分钟）与**无进展窗口**（默认 5 分钟）可在表单以分钟输入，保存时自动换算毫秒生效，无需手工编辑配置文件。
+- 「违规自动升级」说明文案优化：直接说明触发次数 / 窗口阈值的判定与升级暂停行为，去除括号提示与实现细节，降低配置理解成本。
+- 配套新增回归测试：覆盖开关保存热更、进程重启对账与长跑无进展候选场景。
+
+### 无 Manager 批次的长跑候选消费
+
+- 未拉起编排 Manager 的批次运行期间，由任务负责人（Leader）兜底承担长跑候选消费：读取候选广播、核对 lane 探针状态与 checkpoint / 活动进展，按半自动规则裁决继续观察或重新派发；已拉起 Manager 的批次仍由 Manager 完成调度。
+
+### 注释与文档口径统一
+
+- 「出厂默认开、显式关闭才停」口径统一：Lane 过期检测与长跑探针的默认开启说明跨代码注释、预设说明与双语文档对齐（纯注释与文档改动，零逻辑变更）。
+
+### 发布整理
+
+- 版本 0.4.1 → 0.4.2；变更记录整理。
+
+## 0.4.1（2026-09-05）
+
+### 治理预设规则包
+
+- 出厂护栏规则预设随包发布（presets/hook-rules）：l1-sensitive（L1 敏感数据防护 12 条）、l2-resource（L2 资源上限 6 条）、compose（L1+L2 全量 18 条），wrapper 结构（`_meta` 元数据 + `rules` 数组），规则字段与引擎 Rule 类型逐字段对齐、零扩展字段。
+- preset 装载与引用：装载器剥离 `_meta` 取 rules 并做受控资产早失败校验；`governance.hook.preset` 支持注册 id / id 数组引用（如 `"preset": "compose"` 或 `["l1-sensitive","l2-resource"]`），跨 preset 规则 id 全局唯一性校验拒绝重复。
+
+### Web UI 治理配置页 + runtime.json 写通道
+
+- 治理配置设置页（Web UI 设置区）：护栏开关、规则预设、违规自动升级（触发次数 / 窗口）可视化配置；页面保存即时生效、无需重启。
+- runtime.json 热写通道：保存请求经 config-trust 校验（顶层白名单 / 值域 / preset 与内联规则冲突守卫）后落盘 runtime.json，400 校验拒绝不回写；窗口秒输入后端毫秒归一化（windowSeconds → windowMs，线协议键不落盘）。
+- 随包双语主题文档：docs/webui-governance-config(.en).md。
+
+### lane_longrun 超时无进展探针
+
+- watch 长跑档（默认开启）：running lane 运行超时且长期无 checkpoint / 活动进展 → 产候选并广播给 Manager（探针只产候选，不改成员状态），重派裁决归 Manager / Leader。
+- 与心跳 stalled 档并列扫描；事件留痕可审计。
+
+### Web UI 修复
+
+- 治理配置页 UI 修复：重命名、preset 多选、放大字号、移除全组合提示。
+
+### 发布整理
+
+- 版本 0.4.0 → 0.4.1；根 README（GitHub 面）精简：170 → ≈100 行，中文 / 英文 1:1 同构重写，去除过期版本与测试数（实测刷新 816）；删除 README.market.md（人话版内容并入精简后根 README 机制表与能力段）。
+
 ## 0.4.0（2026-09-03）
 
 ### 工具调用级治理护栏

package/README.en.md

@@ -15,8 +15,8 @@
 - **In-process messaging with loop protection** — the mailbox's three boxes (inbox / outbox / broadcast) use atomic writes and acknowledgements; loop protection suppresses message storms, and communication paths stay traceable.
 - **Crash-recoverable** — heartbeat expiry detection plus progress checkpoint preservation: after a crash the scene and artifacts remain inspectable and a new worker can take over; no automatic resume — a failed task is redone by opening a new batch.
 - **Read-only monitoring panel** — the Web UI shows batches, lane states, and the event timeline directly; read-only, non-intrusive, so nothing can be altered by accident.
-- **Call-level guardrails (6 primitives)** — the call-level line of defense in two-layer governance (local-first, evidence-auditable): besides the pre-dispatch difficulty gate, every tool call is adjudicated per call against the six primitives ALLOW / DENY / REQUIRE_APPROVAL / NARROW / DEFER / PAUSE to decide whether it is out of bounds; a hit produces a **tamper-evident refusal receipt** (sha256 hash-chain anchored; re-checking can locate where tampering happened). Adjudication is deterministic, predictable, and easy to test — suited to local multi-agent orchestration needing **auditable out-of-bounds prevention with deterministic, testable governance**. Guardrail events are observable at the event level through receipts and event-stream files (verifiable), with no dedicated UI panel; out of the box `rules` is empty (zero interception) and takes effect once rules are configured on demand.
-- **Hot-updatable configuration, no restart** — guardrail rules and switches written to `runtime.json` take effect immediately, with no process restart.
+- **Call-level guardrails (6 primitives)** — the call-level line of defense in two-layer governance (local-first, evidence-auditable): besides the pre-dispatch difficulty gate, every tool call is adjudicated per call against the six primitives ALLOW / DENY / REQUIRE_APPROVAL / NARROW / DEFER / PAUSE to decide whether it is out of bounds; a hit produces a **tamper-evident refusal receipt** (sha256 hash-chain anchored; re-checking can locate where tampering happened). Adjudication is deterministic, predictable, and easy to test — suited to local multi-agent orchestration needing **auditable out-of-bounds prevention with deterministic, testable governance**. Guardrail events are observable at the event level through receipts and event-stream files (verifiable); the switches and rules are configured on the "Punky Swarm Governance" page in the Settings sidebar (out of the box `rules` is empty (zero interception) and takes effect once rules are configured on demand).
+- **Hot-updatable configuration, no restart** — guardrail rules and switches, plus the watch capability switches (lane heartbeat / longrun probe), written to `runtime.json` take effect immediately, with no process restart; on restart they are also reconciled against `runtime.json`.
 - **National-standard AIP compatible** — follows the descriptor structures of GB/Z 185-2026 (Artificial Intelligence — Agent Interconnection): tool 6 attributes / agent ACS / message-task-session mapping; additive only, pluggable.
 - **Optional ACPs communication** — external mTLS service endpoint, registry registration, and external discovery, all off by default (secure default).
 - **Runs locally, works out of the box** — zero cloud dependency, zero network exposure by default; a single npm package contains the plugin engine, the Punky Swarm preset, and the jiufeng-team role guide, with bilingual (Chinese / English) documentation.
@@ -68,6 +68,8 @@ The plugin ships a **read-only** monitoring panel — the third tab, "Conversati
 - **Batch detail**: lane status cards (state, task summary, gate missing items, layer and dependencies), event timeline, inbox counts;
 - **Read-only by design**: 3-second auto-refresh, follows the light/dark theme; batch and gate states are view-only, and governance operations are carried out by the Leader through governance tools.
 
+The Settings sidebar also provides a "**Punky Swarm Governance**" page (writable, saveable): configure the guardrails (`governance.hook` switch/preset/escalation/narrowing) and the lane capability switches (`watch.enabled` / `watch.longrun.enabled`) here; saving writes `runtime.json` and takes effect immediately with no dsh restart. See [docs/webui-governance-config.en.md](docs/webui-governance-config.en.md).
+
 ## Configuration at a Glance
 
 Plugin configuration is centralized in `cordis.patch.yml`; the key assembly keys and their defaults:
@@ -81,6 +83,8 @@ Plugin configuration is centralized in `cordis.patch.yml`; the key assembly keys
 | Identity system (AIC / CAI / signing) | `aip.identity.enabled` | Off |
 | ACPs communication (mTLS endpoint / bridge / registry / discovery) | `acps.*` | Off (when off: no listeners, no timers, no network) |
 
+> Note: `capabilities.watch` includes a `longrun` sub-switch (longrun timeout re-dispatch probe, on by factory default, off only when explicitly set to `false`); both `watch.enabled` and `watch.longrun.enabled` can be hot-toggled on the "Punky Swarm Governance" page, written to `runtime.json` and taking effect immediately (see "Hot-updatable configuration, no restart" above and [docs/webui-governance-config.en.md](docs/webui-governance-config.en.md)).
+
 Key semantics, configuration examples, and rule authoring: see [docs/governance-technical.en.md](docs/governance-technical.en.md) and [docs/guardrails-hook.en.md](docs/guardrails-hook.en.md).
 
 ### Secure defaults
@@ -117,7 +121,8 @@ Technical details live under `docs/` (each document ships with an English versio
 
 | Document | Contents |
 |---|---|
-| [docs/governance-technical.en.md](docs/governance-technical.en.md) | Batch-level governance technical manual: three-layer gates, state machine, wavePlan contract, 20 governance tools reference, assembly key table, lifecycle |
+| [docs/governance-technical.en.md](docs/governance-technical.en.md) | Batch-level governance technical manual: three-layer gates, state machine, wavePlan contract, 21 governance tools reference, assembly key table, lifecycle |
+| [docs/webui-governance-config.en.md](docs/webui-governance-config.en.md) | Web UI "Governance Configuration" page guide: save/activation semantics and behavior boundaries for guardrail switch/presets and the lane capability switch (watch) |
 | [docs/guardrails-hook.en.md](docs/guardrails-hook.en.md) | Call-level guardrail technical manual: runtime semantics of the 6 primitives, rule configuration and examples, refusal receipts and verification, hot update, boundaries and non-provisions, capability boundaries & trade-offs |
 | [docs/aip-compliance.en.md](docs/aip-compliance.en.md) | National-standard AIP compliance details: tool 6 attributes, ACS field set, message / task / session mapping, identity system |
 | [docs/acps-communication.en.md](docs/acps-communication.en.md) | ACPs communication details: mTLS endpoints, internal bridge, registry / discovery, configuration examples, capability boundaries |

package/README.md

@@ -15,8 +15,8 @@ English: [README.en.md](README.en.md)
 - **进程内消息与环防护**——mailbox 三箱（inbox / outbox / broadcast）原子写与确认，环防护抑制消息风暴，通信路径可追踪。
 - **崩溃可恢复**——心跳过期检测 + 进度 checkpoint 保全：崩溃后现场与产物可查、新 worker 可接续；不自动续跑，失败任务重做即开新批次。
 - **只读监控面板**——Web UI 直接查看批次、lane 状态与事件时间线，只读不干预，人工不可误改。
-- **工具调用级护栏（6 原语）**——双层治理中的调用级防线（本地优先、证据可审计）：除派发前难度门禁外，每次工具调用再按 ALLOW / DENY / REQUIRE_APPROVAL / NARROW / DEFER / PAUSE 六原语逐调用裁决是否越界，命中即产出**可验篡改的拒绝收据**（sha256 哈希链锚定，复核可定位篡改位置）。裁决确定、可预期、便于测试，适合需要**可审计防越界、确定性可测试治理**的本地多 Agent 编排。护栏事件以收据与事件流文件留痕、可复核（事件级可观测），暂无独立 UI 面板；出厂 `rules` 为空即零拦截，按需配置规则后生效。
-- **热更新配置，免重启**——护栏规则与开关写入 `runtime.json` 即时生效，进程无需重启。
+- **工具调用级护栏（6 原语）**——双层治理中的调用级防线（本地优先、证据可审计）：除派发前难度门禁外，每次工具调用再按 ALLOW / DENY / REQUIRE_APPROVAL / NARROW / DEFER / PAUSE 六原语逐调用裁决是否越界，命中即产出**可验篡改的拒绝收据**（sha256 哈希链锚定，复核可定位篡改位置）。裁决确定、可预期、便于测试，适合需要**可审计防越界、确定性可测试治理**的本地多 Agent 编排。护栏事件以收据与事件流文件留痕、可复核（事件级可观测）；开关与规则在设置侧边栏「蟛蜞治理配置」页配置（出厂 `rules` 为空即零拦截，按需配置规则后生效）。
+- **热更新配置，免重启**——护栏规则与开关、watch 能力开关（lane 心跳/长跑探针）写入 `runtime.json` 即时生效，进程无需重启；重启时亦按 `runtime.json` 对账生效。
 - **国标 AIP 兼容**——遵循《人工智能 智能体互联》GB/Z 185-2026 描述结构（工具 6 属性 / 智能体 ACS / 消息任务会话映射），仅增不改、可插拔。
 - **可选的 ACPs 通讯**——对外 mTLS 服务端点、registry 注册与外部发现，默认全部关闭（安全默认）。
 - **本地运行，开箱即用**——零云依赖、默认零网络暴露；单一 npm 包内含插件引擎、Punky Swarm 预设与 jiufeng-team 角色指引，附中英双语文档。
@@ -68,6 +68,8 @@ dsh web restart
 - **批次详情**：lane 状态卡（状态、任务简述、门禁缺件、层与依赖）、事件时间线、收件箱计数；
 - **只读设计**：3 秒自动刷新，跟随深浅主题；批次与门禁状态只能查看，治理操作由 Leader 通过治理工具完成。
 
+设置侧边栏另提供「**蟛蜞治理配置**」页（非只读，可保存）：在此配置护栏（`governance.hook` 开关/预设/升级/窄化）与 lane 能力开关（`watch.enabled` / `watch.longrun.enabled`），保存即写入 `runtime.json` 并即时生效、无需重启 dsh；详见 [docs/webui-governance-config.md](docs/webui-governance-config.md)。
+
 ## 配置速览
 
 插件配置集中在 `cordis.patch.yml`，关键装配键与默认值：
@@ -81,6 +83,8 @@ dsh web restart
 | 身份体系（AIC / CAI / 签名） | `aip.identity.enabled` | 关 |
 | ACPs 通讯（mTLS 端点 / 桥接 / registry / discovery） | `acps.*` | 关（关闭时无监听、无定时器、无网络） |
 
+> 注：`capabilities.watch` 含 `longrun` 子开关（长跑超时重派探针，出厂默认开，显式 `false` 才关）；`watch.enabled` 与 `watch.longrun.enabled` 均可在「蟛蜞治理配置」页热更开关，写入 `runtime.json` 即时生效（见「热更新配置，免重启」与 [docs/webui-governance-config.md](docs/webui-governance-config.md)）。
+
 各键语义、配置示例与规则写法见 [docs/governance-technical.md](docs/governance-technical.md) 与 [docs/guardrails-hook.md](docs/guardrails-hook.md)。
 
 ### 安全默认
@@ -117,7 +121,8 @@ flowchart LR
 
 | 文档 | 内容 |
 |---|---|
-| [docs/governance-technical.md](docs/governance-technical.md) | 批级治理技术手册：三层门禁、状态机、wavePlan 契约、20 治理工具参考、装配键表、生命周期 |
+| [docs/governance-technical.md](docs/governance-technical.md) | 批级治理技术手册：三层门禁、状态机、wavePlan 契约、21 治理工具参考、装配键表、生命周期 |
+| [docs/webui-governance-config.md](docs/webui-governance-config.md) | Web UI「治理配置」页说明：护栏开关/预设与 lane 能力开关（watch）的保存生效口径与行为边界 |
 | [docs/guardrails-hook.md](docs/guardrails-hook.md) | 调用级护栏技术手册：6 原语运行期语义、规则配置与示例、拒绝收据与验签、热更新、边界与不提供项、能力边界与取舍 |
 | [docs/aip-compliance.md](docs/aip-compliance.md) | 国标 AIP 兼容明细：工具 6 属性、ACS 字段集、消息/任务/会话映射、身份体系 |
 | [docs/acps-communication.md](docs/acps-communication.md) | ACPs 通讯明细：mTLS 端点、内部桥接、registry / discovery、配置示例、能力边界 |

package/cordis.patch.yml

@@ -31,11 +31,20 @@
           #   intervalsMinutes 退避档位（分钟，默认 [10,20,30]，冷场越久追问间隔越长）；maxMissed 硬停拍数
           #   （默认 3，连续 N 拍无活动 → appendEvent('lane.stalled') 停止追问，只标记不自动处置）；
           #   scanIntervalMinutes watchdog 扫描间隔（默认 1）；probeTemplate 可选覆写追问模板（{lane}/{batchId}/{missed} 占位）。
+          #   longrun 子键（长跑档探针，出厂默认开——用户定案修订，非设计默认关）：running lane 持续超
+          #   maxDurationMs（默认 1200000=20min）且近 noProgressWindowMs（默认 300000=5min）无新 checkpoint
+          #   且无活动（严格 AND）→ 同 tick 产 lane.longrun.candidate 事件 + mailbox broadcast 候选通知
+          #   Manager 裁决（探针只标记不改 lane 状态；lane_longrun 工具并列注册，enabled=false 不注册、
+          #   tick 不判、零事件零消息零行为变化）。
           watch:
             enabled: true
+            longrun:
+              enabled: true           # 出厂默认开（定案修订：显式 false 才关）
+              maxDurationMs: 1200000  # 长跑超时阈值（默认 20min；正整数 ms，非法回退默认）
+              noProgressWindowMs: 300000  # 无进展窗（默认 5min；正整数 ms，非法回退默认）
           # worktree 物理隔离（lane-tools）：enabled=true 时注册 lane_worktree_create / lane_worktree_merge / lane_checkpoint
           # （git worktree 隔离 + checkpoint 提交；与 lane_claim 逻辑锁互补——lane_claim 管状态层「写谁的」，
-          #  本组工具管工作区层「写到哪」；全能力默认开 → 工具总数 18（14+heartbeat+worktree 三件+log_export），回归已覆盖）。
+          #  本组工具管工作区层「写到哪」；工具总数按 register.js TBD-2 实测口径：裸配置 20 / patch 全开 21（含 lane_longrun 与 lane_checkpoint_status）/ 显式关（worktree+watch 关）14）。
           worktree:
             enabled: true
             # merge agent 装配键：enabled=true 且宿主注入 mergeAgentSpawner 时，
@@ -70,6 +79,14 @@
           hook:
             enabled: true      # 默认开启；空规则表 → decide 恒 ALLOW → 零行为变化
             rules: []          # 规则表（空=零拦截）；Rule 结构见 lib/governance/types.ts
+            # M5-b preset 装载键（preset-build）：引用随包预设（presets/hook-rules/ 三 JSON，注册 id 枚举：
+            #   l1-sensitive / l2-resource / compose——不接受任意路径），保序展开拼接至 rules（inline rules 在后）。
+            #   preset: 'l1-sensitive' 或 preset: ['l1-sensitive', 'l2-resource']（= compose 逐条等价，二选一互斥引用——
+            #   同批引用 compose + l1-sensitive 会产生重复 id → 装载失败回退空表 + warn，宁空勿半）。
+            #   runtime.json 热更示例：{"governance":{"hook":{"preset":["l1-sensitive","l2-resource"]}}}（⑤ 通道即时生效）。
+            #   出厂不默认启用任何 preset（本键缺省 = 空表零拦截不变，与 rules:[] 出厂安全默认严格一致）——
+            #   需启用时经 runtime.json 下发或装配 config 注入；preset 文件内容随包版本发布生效（boot 装载一次）。
+            # preset: []        # ← 示例注释（默认不启用，勿取消注释即默认值）
             # M5-a：护栏违规计数升级（默认关——出厂零行为变化；开启后：归属批次的规则拒绝
             # （DENY/NARROW）在 windowMs 内达 threshold → 经棘轮校验批 paused（reason=governance-escalate）；
             # 与 hook enabled:true 内核就位零拦截正交——出厂 rules:[] 本就零收据，关保持「改规则不意外武装暂停」保守面）

package/docs/governance-technical.en.md

@@ -137,7 +137,10 @@ Tools are grouped by function; registration is controlled by assembly keys (see
 
 | Tool | Description |
 |---|---|
-| `lane_heartbeat` | Lane heartbeat query/trigger (watchdog scan, stalled marking) |
+| `lane_heartbeat` | Lane heartbeat query/trigger (watchdog scan, stalled marking; lane omitted → returns all running lanes of the batch) |
+| `lane_longrun` | Lane longrun probe query/trigger (longrun tier: runningSince/duration/no-progress window/candidate state; lane omitted → returns all running lanes of the batch; registered when both the watch and longrun sub-switches are on) |
+
+Watch consumption for batches without a Manager (or while the Manager is absent) falls to the Leader: on each worker settlement or confirmed idle, the Leader checks `mailbox_read(broadcast)` for longrun.candidate broadcasts and cross-checks probe state (candidate/emitted/reason) with `lane_longrun` (whole-batch default); a hit candidate is handled as a semi-automatic redispatch — keep observing while the lane has recent checkpoints/activity, stop-and-redispatch or reopen the batch when there is genuinely no progress, and escalate doubtful cases to the user; once a Manager is raised, scheduling returns to the Manager.
 
 ### worktree physical isolation
 
@@ -163,7 +166,7 @@ Assembly is centralized in `cordis.patch.yml`; runtime overrides are covered in
 | Discovery service (ADP) | `capabilities.discovery` | on | Mounts `POST /api/dsh-punky-swarm/discover` + `GET /.well-known/aip`; nodes can hide per-node with active=false |
 | Diagnostics bridging | `capabilities.trajectory` | on (autoFail=false) | anomaly diagnosis → sessionId→lane mapping → notify; auto-failed only when autoFail=true (failConfidence threshold) |
 | Mailbox loop protection | `capabilities.budget` | on (hops=4 / roundTrips=2) | checkBudget before outbox/broadcast sends; inbox (Leader downlink dispatch) never limited |
-| Heartbeat/expiry detection | `capabilities.watch` | on | watchdog timer + lane_heartbeat; backoff-tier follow-ups + N consecutive no-activity beats → lane.stalled mark (mark only, no automatic disposition) |
+| Heartbeat/expiry detection | `capabilities.watch` | on | watchdog timer + lane_heartbeat; backoff-tier follow-ups + N consecutive no-activity beats → lane.stalled mark (mark only, no automatic disposition); hot-apply/restart-reconcile surface = 5 keys {`enabled`, `longrun.enabled`, `scanIntervalMinutes`, `longrun.maxDurationMs`, `longrun.noProgressWindowMs`} — longrun thresholds can be set via the governance-config page form (minutes→ms) or runtime.json and take effect on hot-apply/restart |
 | worktree physical isolation | `capabilities.worktree` | on | lane_worktree_create/merge/checkpoint; complements the lane_claim logical lock |
 | Acceptance evidence | `capabilities.verify` | on (mode=advisory) | post-execute evidence capture (content-addressed blob + ledger); three-state adjudication (done/failed/blocked); intercepts when mode=enforce |
 | Log export | `capabilities.logs` | off | log_export tool registration (explicitly enabled by the patch) |

package/docs/governance-technical.md

@@ -137,7 +137,10 @@
 
 | 工具 | 说明 |
 |---|---|
-| `lane_heartbeat` | lane 心跳查询/触发（watchdog 扫描，stalled 标记） |
+| `lane_heartbeat` | lane 心跳查询/触发（watchdog 扫描，stalled 标记；lane 缺省 → 返回该批全部 running lane） |
+| `lane_longrun` | lane 长跑超时重派探针查询/触发（longrun 档：runningSince/时长/无进展窗/候选状态；lane 缺省 → 返回该批全部 running lane；watch 与 longrun 子开关均开启时注册） |
+
+无 Manager（或 Manager 缺席）批次的 watch 消费由 Leader 兜底承担：每次 worker 结算或确认空闲时，Leader 以 `mailbox_read(broadcast)` 查 longrun.candidate 广播，再以 `lane_longrun` 缺省全批查询核对探针态（candidate/emitted/reason）；命中候选按半自动重派处置——近窗有 checkpoint/活动则等待继续观察，确无进展则停轮重派或重开批次，处置存疑则上报用户裁决；批次拉起 Manager 后调度交还 Manager。
 
 ### worktree 物理隔离
 
@@ -163,7 +166,7 @@
 | 发现服务（ADP） | `capabilities.discovery` | 开 | 挂载 `POST /api/dsh-punky-swarm/discover` + `GET /.well-known/aip`；nodes 可逐节点 active=false 隐藏 |
 | 诊断桥接 | `capabilities.trajectory` | 开（autoFail=false） | 异常诊断 → sessionId→lane 映射 → notify；autoFail=true 时才自动 failed（failConfidence 阈值） |
 | mailbox 环防护 | `capabilities.budget` | 开（hops=4 / roundTrips=2） | outbox/broadcast 发送前 checkBudget；inbox（Leader 下行派发）永不受限 |
-| 心跳/过期检测 | `capabilities.watch` | 开 | watchdog 定时器 + lane_heartbeat；退避档位追问 + 连续 N 拍无活动 → lane.stalled 标记（只标记不自动处置） |
+| 心跳/过期检测 | `capabilities.watch` | 开 | watchdog 定时器 + lane_heartbeat；退避档位追问 + 连续 N 拍无活动 → lane.stalled 标记（只标记不自动处置）；热更/重启对账生效面 5 键 = {`enabled`, `longrun.enabled`, `scanIntervalMinutes`, `longrun.maxDurationMs`, `longrun.noProgressWindowMs`}——长跑阈值可经治理配置页表单（分钟换算 ms）或 runtime.json 写入并生效 |
 | worktree 物理隔离 | `capabilities.worktree` | 开 | lane_worktree_create/merge/checkpoint；与 lane_claim 逻辑锁互补 |
 | 验收证据 | `capabilities.verify` | 开（mode=advisory） | post-execute 证据捕获（内容寻址 blob + ledger）；三态裁决（done/failed/blocked）；mode=enforce 时拦截 |
 | 日志导出 | `capabilities.logs` | 关 | log_export 工具注册（patch 显式开启） |

package/docs/webui-governance-config.en.md

@@ -0,0 +1,77 @@
+# Governance Configuration
+
+> This guide covers the Governance page under Settings in the dsh Web UI: which guardrail options you can adjust, how changes take effect immediately after saving, and what this page deliberately does not do.
+> 中文: [webui-governance-config.md](webui-governance-config.md)
+
+## What this page does
+
+Governance is a dedicated page in the Settings area of the dsh Web UI. It manages a set of guardrail options for dsh running on this machine: the guardrails inspect the tool calls an Agent makes, detect out-of-bounds calls, and then allow, deny, or escalate them according to the rules you have chosen. Changes made on this page take effect **immediately after saving — no dsh restart needed**.
+
+Besides the guardrails, this page also provides lane capability switches and time windows: enabling and disabling lane expiry detection (watch, including the longrun timeout re-dispatch probe), and setting the two longrun time windows (timeout / no-progress).
+
+At the top of the page you can see the current state: whether the guardrails are live, and how many rules are currently in effect.
+
+## Configurable options
+
+### Guardrail switch
+
+- **On**: the guardrails take part in checking, judging out-of-bounds calls against the rule set below.
+- **Off**: the guardrails take no part at all and calls are not held back by this feature.
+- **Factory default: on**. However, the factory rule set is empty, so nothing is actually intercepted (see "Behavior boundaries").
+
+### Rule preset
+
+Pick a ready-made rule set to quickly enable a group of out-of-bounds protections:
+
+| Option | Number of rules | Purpose |
+|---|---|---|
+| Factory default (no interception) | 0 | No rules enabled; guardrails on but nothing is held back |
+| Sensitive-data guard | 12 | For out-of-bounds calls involving sensitive data such as credentials and private keys |
+| Resource limits | 6 | For calls that exceed resource ceilings such as timeout and concurrency |
+| Combination (L1 + L2) | 18 | The full combination of the two rule sets above |
+
+Once you select a preset, the page shows the **count and a purpose summary** for that rule set. Switching presets does not change the running state by itself — it takes effect when you click Save.
+
+### Auto-escalation
+
+Off by default. When on, once guardrail refusals for the same batch reach the threshold within the counting window, the batch is automatically paused with a record, waiting for you to review and resume it manually.
+
+- **Refusals within window**: how many rule refusals accumulate within one time window before the automatic pause triggers (minimum 1).
+- **Window (s)**: the length of the counting window (default 600 s — 10 minutes; minimum 1). Entered in seconds on the form and stored in milliseconds internally (×1000).
+- **Counted verdicts**: "Deny" and "Narrowed allowance" are counted by default; "Defer" and "Pause" can be added as needed; verdicts that require human approval are not on this list.
+
+### Narrowed allowance
+
+Off by default. When enabled, calls that go beyond the allowed bounds are no longer denied outright; instead the guardrails give narrowing guidance so the caller can retry with narrowed parameters. When disabled, such calls are denied outright.
+
+### Lane capability switches (watch)
+
+Control lane expiry detection (heartbeat / longrun):
+
+- **Lane expiry watch**: the parent switch, controls the watchdog expiry scan over running lanes (heartbeat backoff follow-ups + stalled marking). When off, expiry detection does not run at all.
+- **Long-run timeout probe**: the child switch, controls the longrun candidate probe for lanes making no progress for too long. **On by factory default**; it takes effect only while the parent switch is on (when the parent is off, the child is disabled).
+  - **Timeout window (min)**: a lane running longer than this enters longrun judging (default 20, minimum 1, whole minutes).
+  - **No-progress window (min)**: a lane under longrun judging with no checkpoint/activity within this window produces a redispatch candidate (default 5, minimum 1, whole minutes).
+
+Both switches are on by factory default (`enabled` defaults to on — off only when explicitly `false`). While off, running lanes producing no stalled / longrun candidate events is expected; after re-enabling, scanning resumes from the baseline. The two time windows are entered in minutes on the form and converted to milliseconds when saved (internal keys `maxDurationMs`/`noProgressWindowMs`, defaults 1200000/300000); sub-minute tuning is done by editing the configuration file directly.
+
+## Saving and activation
+
+- **Save**: after clicking Save, the settings are written to the local configuration file and then applied to the running dsh immediately — no restart at any point. The page first shows "Saved, confirming…" and turns to "Live" once confirmed.
+- **Activation of the lane capability switches (watch)**: the watch group is saved together with the guardrails (same Save button, merged into `runtime.json`); **any change — either switch or a time window — hot-applies immediately on save** (the watch effective surface is 5 keys: `enabled`/`longrun.enabled`/`scanIntervalMinutes`/`longrun.maxDurationMs`/`longrun.noProgressWindowMs`); after a process restart they are also reconciled against `runtime.json`, so there is no need to set them again.
+- **Reset**: discards your unsaved changes and returns to the state most recently loaded into the page.
+- **Save rejected**: the page shows why the save was rejected; the common reasons are listed in "Behavior boundaries" below.
+
+## Behavior boundaries
+
+- **A controlled form — no free-form rule editing**: this page offers only the switches, presets, and numeric options above; there is no entry point for editing rules one by one. Teams that need fully custom rules should maintain the rule list in the configuration file (see the technical manual linked below).
+- **Factory default zero interception is unchanged**: a fresh install ships with the factory default — guardrails on but no rules loaded, so no call is intercepted and existing behavior is unaffected; interception only begins after you select a preset or configure rules manually.
+- **Manual rules must be handled first when they conflict with presets**: if a hand-maintained rule list already exists in the configuration, switching presets is rejected (to avoid overwriting manual rules); remove those rules manually first, or keep the preset unchanged, then save.
+- **Saving is accepted only from this machine (or trusted sources)**: this page only accepts save requests from a browser on this machine (a local address); if dsh is served through a remote address, the deployment must add the visiting source to the trust list (the dsh host and this plugin must stay consistent), otherwise saves are rejected.
+- **Boundaries of the watch switches**: on by factory default — off only when explicitly disabled; turning them off only stops scanning and probe events and never changes already-landed batch/member states. The tool registration surface (whether the heartbeat/longrun query tools appear in the available list) is fixed at startup; while watch is turned off at runtime, the query tools remain available and return a "disabled" state (no error).
+- **watch longrun thresholds are now configurable on this page**: the longrun timeout window and no-progress window can be configured on this page's form (entered in minutes, stored in milliseconds) and hot-apply immediately on save (see "Lane capability switches (watch)" and "Saving and activation" above); the remaining watch-level keys — `scanIntervalMinutes`/`intervalsMinutes`/`maxMissed`/`probeTemplate` — are still maintained manually in `runtime.json`.
+
+## Further reading
+
+- [Call-level guardrails technical manual](guardrails-hook.en.md): guardrail mechanics, rule authoring, and runtime details (for maintainers and developers).
+- [Batch governance technical manual](governance-technical.en.md): batches, gates, and state machine (for operators).

package/docs/webui-governance-config.md

@@ -0,0 +1,77 @@
+# 治理配置
+
+> 本文介绍 dsh Web UI「设置 → 治理配置」页面：可以调整哪些护栏选项、保存后如何即时生效，以及本页面刻意不做的事。
+> English: [webui-governance-config.en.md](webui-governance-config.en.md)
+
+## 这个页面是什么
+
+「治理配置」是 dsh Web UI 设置区的一个独立页面。它管理 dsh 在本机运行时的一组护栏选项：护栏会检查 Agent 的工具调用是否越界，再按你所选规则决定放行、拒绝或升级处理。页面上的改动保存后**立即生效，无需重启 dsh**。
+
+除护栏外，本页面还提供 lane 能力开关与时间窗口：lane 过期检测（watch，含长跑超时重派探针）的启用与关闭，以及超时/无进展两个长跑时间窗口的设置。
+
+页面顶部显示当前状态：护栏是否已生效，以及当前生效的规则数量。
+
+## 可配置项
+
+### 护栏开关
+
+- **打开**：护栏参与检查，依据下方规则集判断越界调用。
+- **关闭**：护栏整体不参与，调用不被本功能拦阻。
+- **出厂默认：打开**。但出厂规则为空，因此实际不拦截任何调用（见「行为边界」）。
+
+### 规则预设
+
+选择一个现成的规则集，快速启用一组越界防护：
+
+| 选项 | 规则数量 | 用途 |
+|---|---|---|
+| 出厂空表（零拦截） | 0 | 不启用任何规则；护栏开启但不拦阻 |
+| 敏感数据防护 | 12 | 针对凭据、私钥等敏感数据的越界调用 |
+| 资源上限 | 6 | 针对超时、并发等资源使用上限的调用 |
+| 组合（L1 + L2） | 18 | 以上两套规则集的完整组合 |
+
+选择某个预设后，页面显示该套规则的**数量与用途摘要**。切换预设本身不会立即改变运行状态，需要点击「保存」生效。
+
+### 违规自动升级
+
+出厂关闭。开启后：同一批任务在设定时间窗口内被护栏拒绝达到阈值次数时，自动将该批次暂停并留痕，等待你检查后手动恢复运行。
+
+- **窗口内触发次数**：一个时间窗口内累计多少次规则拒绝即触发自动暂停（最小为 1）。
+- **窗口（秒）**：计数的窗口长度（默认 600 秒，即 10 分钟；最小为 1）。表单以秒输入，内部按毫秒存储（×1000）。
+- **计入的处理结果**：默认计入「拒绝」与「收窄放行」，可按需增选「延后」「暂停」；需要人工审批的处理结果不在此列。
+
+### 窄化放行
+
+出厂关闭。打开后，对超出允许范围的调用不再直接拒绝，而是给出收窄指引，让调用方按收窄后的参数重试放行；关闭时此类调用直接拒绝。
+
+### Lane 能力开关（watch）
+
+控制 lane 过期检测（心跳/长跑）的运行：
+
+- **Lane 过期检测**：父开关，控制 watchdog 对 running lane 的过期扫描（心跳退避追问 + stalled 标记）。关闭后过期检测整体不运行。
+- **长跑超时重派探针**：子开关，控制对长时间无进展 lane 的长跑候选探测。**出厂默认开**；仅当父开关开启时才生效（父关时子项禁用）。
+  - **超时窗口（分钟）**：lane 运行超过该时长即进入长跑判定（默认 20，最小 1，整数分钟）。
+  - **无进展窗口（分钟）**：进入长跑判定的 lane 若在该窗口内无 checkpoint/活动，即产出重派候选（默认 5，最小 1，整数分钟）。
+
+两个开关出厂默认均为开（`enabled` 缺省即开，显式 `false` 才关）。关闭期间，running lane 不再产生 stalled / 长跑候选事件属预期；重新开启后自基线恢复扫描。两个时间窗口在表单以分钟输入，保存时换算为毫秒写入配置（内部键 `maxDurationMs`/`noProgressWindowMs`，默认值 1200000/300000）；亚分钟级微调请直接编辑配置文件。
+
+## 保存与生效
+
+- **保存**：点击后，设置先写入本机配置文件，再即时应用到运行中的 dsh，全程无需重启。页面先显示「已保存，生效确认中」，确认后转为「已生效」。
+- **Lane 能力开关（watch）的生效**：watch 组随护栏一起保存（同一保存按钮，合并写入 `runtime.json`）；两个开关与时间窗口**任一变化都保存即热更生效**（watch 生效面共 5 键：`enabled`/`longrun.enabled`/`scanIntervalMinutes`/`longrun.maxDurationMs`/`longrun.noProgressWindowMs`），进程重启后亦按 `runtime.json` 对账生效，无需重复设置。
+- **重置**：放弃本次未保存的修改，回到最近一次载入页面的状态。
+- **保存被拒**：页面会显示被拒原因；常见原因见下节「行为边界」。
+
+## 行为边界
+
+- **受控表单，不开放任意规则编辑**：本页面只提供上述开关、预设与数值选项，没有逐条编辑规则的入口。需要逐条定制规则的团队，请在配置文件中维护规则清单（写法见延伸阅读的技术手册）。
+- **出厂默认零拦截不变**：全新安装即出厂空表——护栏开启但不加载任何规则、不拦截任何调用，既有行为不受影响；只有选择预设或手工配置规则后才会开始拦截。
+- **预设与手工规则冲突时先手工处置**：若配置中已存在手工维护的规则清单，切换预设会被拒绝（避免覆盖手工规则）；请先手工移除这些规则，或保持预设不变，再保存。
+- **仅本机（或受信任来源）可保存**：本页面只接受来自本机浏览器（本地地址）的保存请求；若 dsh 通过远程地址对外提供服务，部署方须把访问来源加入信任名单（dsh 宿主与本插件保持一致），否则保存会被拒绝。
+- **watch 开关的边界**：出厂默认开，显式关闭才停；关闭只停扫描与探针事件，不改动已落盘的批次/成员状态。工具注册面（心跳/长跑查询工具是否出现在可用列表）在启动时固定；运行期关闭 watch 时查询工具仍可用并返回「已禁用」状态（不报错）。
+- **watch 长跑阈值现可经本页表单配置**：长跑超时窗口与无进展窗口可经本页表单配置（分钟输入，换算毫秒落盘）并随保存即时热更生效（见上文「Lane 能力开关（watch）」「保存与生效」）；`scanIntervalMinutes`/`intervalsMinutes`/`maxMissed`/`probeTemplate` 等其余 watch 级键仍走手工 `runtime.json` 维护。
+
+## 延伸阅读
+
+- [调用级护栏技术手册](guardrails-hook.md)：护栏机制、规则写法与运行细节（面向维护者与开发者）。
+- [批级治理技术手册](governance-technical.md)：批次、门禁与状态机（面向 Leader 与运维）。

package/lib/api.js

@@ -22,6 +22,9 @@ import * as mailbox from './comms/mailbox.js';
 import { createStreamHub } from './panel/stream.js';
 // P1 批 R-07 排除项（承接归 panel 批）：事件读端字面量收敛——EVT 常量源 lib/state/event-types.js（P2-07 单点）
 import * as EVT from './state/event-types.js';
+// WebUI 治理配置写通道（webui-config-build-20260903）：/config 端点 trusted 判定（自复刻宿主 /api
+//   护栏语义，conn:184-198 未导出故复刻——插件 exact 路由不经宿主护栏，写端点须自理，见 config-trust.js）
+import { isTrustedConfigRequest } from './webui/config-trust.js';
 
 function sendJson(res, status, data) {
   const body = JSON.stringify(data);
@@ -175,7 +178,7 @@ export function createApi(ctx, deps) {
 
   // P4 ACS 智能体描述目录：enabled=true 时 agentCatalog 非空，注册 /agents；
   // 端点输出 ACS 字段集（AgentCapabilitySpec，逐字字段见 lib/aip/agent-descriptor.js）；只读、无参。
-  // enabled=false（默认）时 agentCatalog 为 null，不注册该路由（既有路由契约不变）。
+  // aip.enabled=false（显式关闭——aip 出厂默认开，readCapability 缺省合并 {enabled:true}）时 agentCatalog 为 null，不注册该路由（既有路由契约不变）。
   if (agentCatalog) {
     register({
       kind: 'exact',
@@ -217,6 +220,88 @@ export function createApi(ctx, deps) {
     });
   }
 
+  // WebUI 治理配置写通道（webui-config-build-20260903，设计 §1.1/§1.2，落点 = discover 段与 stream 段之间）：
+  //   GET + POST /api/dsh-punky-swarm/config —— 配置页页载取数 / 受控字段集保存（写 <root>/config/runtime.json）。
+  //   条件注册仿 discovery/agentCatalog（上方 :162-190 注入形态）：deps.configEndpoints.runtimeConfig
+  //   注入时注册；未注入不注册 → 既有 7 路由/9 路由计数测试零回归（不改既有注册面，disposer 统一回收）。
+  //   trusted 判定（GET/POST 共用，§1.3）：Host loopback/trustedHosts + sec-fetch-site≠cross-site + Origin 同源
+  //   （isTrustedConfigRequest，lib/webui/config-trust.js；trustedHosts 出厂 [] → loopback-only）。
+  //   写逻辑全在 service（lib/webui/runtime-config.js）：白名单预检 400 → 读-改-写 → validateOverlay
+  //   兜底 500 → tmp+rename 原子写；GET 取数 overlay（磁盘原样）/applied（装配侧解析快照）/presets（注册目录）。
+  if (deps.configEndpoints?.runtimeConfig) {
+    const cfgEp = deps.configEndpoints;
+    const trustedHosts = Array.isArray(cfgEp.trustedHosts) ? cfgEp.trustedHosts : [];
+    register({
+      kind: 'exact',
+      path: '/api/dsh-punky-swarm/config',
+      handler(req, res) {
+        // trusted 护栏前置（GET/POST 共用；护栏语义非鉴权层、防 DNS-rebinding/跨站——§1.2）
+        if (!isTrustedConfigRequest(req, trustedHosts)) {
+          const body = req.method === 'POST' ? { ok: false, error: 'forbidden' } : { error: 'forbidden' };
+          return sendJson(res, 403, body);
+        }
+        if (req.method === 'GET') {
+          try {
+            const overlay = cfgEp.runtimeConfig.readOverlay();
+            const gov = overlay && typeof overlay === 'object' && !Array.isArray(overlay)
+              && overlay.governance && typeof overlay.governance === 'object' && !Array.isArray(overlay.governance)
+              ? overlay.governance : null;
+            // watch 段取数（longrun-panel-config-20260905）：overlayWatch = 磁盘 capabilities.watch 段原样
+            //   （无 = null）；applied.watch = 装配侧解析生效快照（watchInstalledCfg，经 appliedWatch getter——
+            //   未注入时省略该键，旧 harness/旧客户端零感知）。既有 overlay=governance 语义不动。
+            const caps = overlay && typeof overlay === 'object' && !Array.isArray(overlay)
+              && overlay.capabilities && typeof overlay.capabilities === 'object' && !Array.isArray(overlay.capabilities)
+              ? overlay.capabilities : null;
+            const overlayWatch = caps && typeof caps.watch === 'object' && !Array.isArray(caps.watch) ? caps.watch : null;
+            const applied = typeof cfgEp.applied === 'function' ? cfgEp.applied() : null;
+            const appliedWatch = typeof cfgEp.appliedWatch === 'function' ? cfgEp.appliedWatch() : null;
+            const presets = typeof cfgEp.presets === 'function' ? (cfgEp.presets() ?? []) : [];
+            // overlay = 磁盘 runtime.json governance 段原样（表单未保存改动基准；无 = null）；
+            // overlayWatch = 磁盘 capabilities.watch 段原样（watch 开关表单基准；无 = null）；
+            // applied = 装配侧已解析快照（默认补齐 + preset 展开 rules）；applied.watch = watch 生效快照
+            //   （{ enabled, longrun:{enabled}, scanIntervalMinutes }——enabled/longrun.enabled 缺省 true）；
+            // presets = 注册目录元数据 [{id,count}]
+            const appliedOut = { hook: applied };
+            if (appliedWatch !== null && appliedWatch !== undefined) appliedOut.watch = appliedWatch;
+            sendJson(res, 200, { overlay: gov, overlayWatch, applied: appliedOut, presets });
+          } catch (e) { sendJson(res, 500, { error: String(e?.message ?? e) }); }
+          return;
+        }
+        if (req.method === 'POST') {
+          let bodyPromise;
+          try {
+            bodyPromise = readJsonBody(req); // req.body 为 string 时 JSON.parse 同步抛 → 先包住归 400
+          } catch (e) {
+            return sendJson(res, 400, { ok: false, error: 'invalid-json: ' + String(e?.message ?? e) });
+          }
+          return bodyPromise.then((payload) => {
+            try {
+              // POST 按 body 键存在性分派（longrun-panel-config-20260905）：含 capabilities 段 → writeWatch
+              //   （单保存合并 governance + capabilities.watch 双段同 body，Leader 裁决 1——writeWatch 内部
+              //   同时处理可选 governance 段，分节校验 + 单次原子写）；仅 governance（旧客户端/既有测试契约）
+              //   → writeGovernance 原路径（错误形态与路由零变化）。
+              const hasCaps = payload && typeof payload === 'object' && !Array.isArray(payload) && 'capabilities' in payload;
+              const out = hasCaps
+                ? cfgEp.runtimeConfig.writeWatch(payload)
+                : cfgEp.runtimeConfig.writeGovernance(payload);
+              if (!out.ok) {
+                if (out.status === 500 || !Array.isArray(out.errors)) {
+                  return sendJson(res, out.status || 500, { ok: false, error: out.error ?? 'write-rejected' });
+                }
+                return sendJson(res, 400, { ok: false, errors: out.errors });
+              }
+              return sendJson(res, 200, { ok: true, written: out.written, ts: new Date().toISOString() });
+            } catch (e) {
+              // 读-改-写 IO 异常（坏 base JSON / rename 失败等）→ 500 不回写（设计 §1.5「不应发生」面）
+              return sendJson(res, 500, { ok: false, error: String(e?.message ?? e) });
+            }
+          }).catch((e) => sendJson(res, 400, { ok: false, error: 'invalid-json: ' + String(e?.message ?? e) }));
+        }
+        return sendJson(res, 405, { ok: false, error: 'method-not-allowed' });
+      },
+    });
+  }
+
   // R3 SSE 端点（设计 §3.3.3，纯新增路由——既有 /api 路由一字不动）：
   //   GET /api/dsh-punky-swarm/stream?session=<sid>[&batchId=<bid>]
   //   SSE 帧协议：event: batch|mailbox|heartbeat + data:<JSON>；注释心跳帧每 10s（hub 内维护）。